canvas text: a glyph missing from the registered face paints as a solid block, and off macOS that is the only text path

[sepehr-safari]

A glyph the registered face does not have is painted as a solid filled rectangle in the text colour, not as .notdef and not skipped. On macOS you rarely see it because AppKit draws the text. Off macOS the reference rasteriser is the only text path there is, so this is every glyph in the app.

All references are v0.10.1, and I checked main (5 commits ahead, none touching src/primitives/canvas/font_ttf.zig, reference.zig or src/platform/linux/).

The mechanism

drawGlyphBox inks the outline and, on failure, fills the cell:

// src/primitives/canvas/reference.zig:838-840
if (codepoint) |cp| {
    if (self.drawGlyphOutline(command, value, draw_bounds, cp, pen_x, baseline, block_rect.width)) return;
}
self.fillTextRect(command.transform.transformRect(block_rect).normalized(), draw_bounds, value.color, command.opacity);

Three limits make that fallback easy to reach, and none can be worked around from the app:

1. No cascade. One font id resolves to exactly one face and stops (referenceFaceForFontId, reference.zig:1152-1157). The comment at :1154 states it: "a registered face never cascades".
2. cmap format 4 only. parse accepts only a format-4 subtable (font_ttf.zig:201) and glyphIndex starts with if (codepoint > 0xFFFF) return 0; (font_ttf.zig:226). Most emoji are astral, so they can never resolve, whatever face is registered.
3. glyf/loca only, no CFF and no colour tables (font_ttf.zig:1-9), so registering a colour emoji font instead is not an option either.

Why it matters

Your bundled src/primitives/canvas/fonts/Geist-Regular.ttf maps 650 codepoints: Latin and Cyrillic. Everything else hits the fallback. CJK, kana, Hangul, Arabic, Hebrew, Devanagari, Thai, and every emoji. U+2713, U+2764, U+20BF and U+2318 are absent too.

Two effects make it look worse than "a few boxes":

• CJK has no spaces, so a Japanese paragraph inks as one unbroken bar per line.
• The renderer walks per codepoint, so one ZWJ family emoji paints as seven separate blocks.

On Linux this is the whole UI: at v0.10.1 src/platform/linux/root.zig contains the string "font" zero times, while src/platform/macos/root.zig has 34 matches. There is no host text layer to fall back to.

It also reaches macOS in one place worth knowing about: native automate screenshot renders through the same reference surface, so screenshots of a correct macOS window come back with blocks where the emoji are.

Reproduction

No Linux needed:

1. In any canvas app, draw a string containing a codepoint outside the registered face, for example 日本語 or ✅.
2. native automate screenshot <view-label>
3. The PNG has solid rectangles where those characters are.

Suggested fixes, smallest first

1. Draw .notdef instead of filling the cell. This is the one that changes how the app reads, and it needs no new font machinery. Every TrueType face has glyph 0, and Geist's is a hollow box. drawGlyphOutline already resolves a codepoint to a glyph index internally, so the change is to split out the part that renders a known glyph index and call it with 0 on the miss, falling back to drawing nothing if glyph 0 has no contours. fillTextRect then only serves the genuinely unrenderable case.

Alone, this is the difference between "some characters are missing" and "the app looks broken".

2. Cascade on a miss. In referenceFaceForFontId, on a zero glyph index, try the other registered faces and then the bundled geist_regular / geist_mono before giving up. One caution: text_metrics.zig must resolve the same way, or text is measured against one face and inked with another, and the layout drifts. Keeping the cascade to the miss path only should preserve today's determinism.

3. Accept cmap format 12. parse currently scans for format 4 (font_ttf.zig:190-201); accepting format 12 as well (platform 3 encoding 10, or platform 0 encoding 4) and dropping the > 0xFFFF guard at :226 unlocks astral codepoints. Format 12 is a sorted array of (startCharCode, endCharCode, startGlyphID) groups, so lookup is a binary search over nGroups. This is the change that makes emoji possible at all.

4. Colour glyphs (CBDT/sbix/COLR) are a much bigger job. Monochrome emoji via 3 would already be a large improvement.

1 and 2 together would make a Linux build presentable with the faces you already bundle.

I am shipping a Zig canvas app on macOS and preparing a Linux build, so I can test a fix on both.

---

Related but separate, and I am happy to file it on its own if you prefer: the reserved weight ids resolve to the regular face in the reference renderer (reference.zig:1152-1157), and an app cannot register into them (error.ReservedFontId below min_registered_font_id, canvas_fonts.zig:147), so off macOS every weight renders regular. It is the same subsystem, which is why I mention it here.

[sepehr-safari]

I implemented suggestion 2 (cascade on a miss) and have been running it, so here is what it costs in practice, in case it is useful for deciding the shape.

The change

One line. The colour-emoji work in this area already walks the registered faces on a miss; it was gated on the lending face carrying COLR:

for (fonts) |font| {
    if (font.face == primary) continue;
    if (!font.face.hasColorGlyphs()) continue;   // <- this
    const glyph = font.face.glyphIndex(codepoint);
    if (glyph != 0) return .{ .face = font.face, .glyph = glyph, .fallback = true };
}

Dropping that line is the whole cascade. The named face is still asked first and still wins every codepoint it carries, so Latin is untouched; a registered face is consulted only for a codepoint nothing else can draw at all.

What it costs

The property it gives up is real and worth stating plainly: one font id can now draw one codepoint with another face's outlines. That was a deliberate invariant. The counter-argument is that it is bounded to codepoints the named face does not have, where the alternative is not the right face but a filled rectangle.

If you would rather not give it up unconditionally, the natural shape is opt-in per registration, a fallback: bool on FontRegistration, defaulting false. That keeps today's behaviour for every existing app and lets one that has bundled a broad face say so. I did not do that in my tree because I control both sides, but it is the version I would expect upstream to want.

On measurement drift

You flagged this in the issue and it does not bite, for a reason worth writing down. Measurement bills the codepoint from the text face's estimator and never sees the lending face, so the cell is charged before the fallback is chosen. The glyph is then scaled to fit that cell. The class where they disagree is the BMP symbol range U+2190..U+2BFF, billed at 0.8 em while an emoji face draws a full 1.0 em; astral codepoints are already billed 1.0 em. So the fitting matters for exactly one range, and a test that uses an astral emoji cannot detect its absence, which cost me a green test before I noticed.

Coverage numbers, if they help prioritise

Walking Geist-Regular.ttf's cmap: 649 mapped codepoints. ASCII 95, Latin-1 95, Latin Extended-A 117, Cyrillic 134, Greek 4. The Greek four are U+039B, U+03A9, U+03BB and U+03C0, which are the maths picks (ohm, lambda, pi), not the alphabet, so Greek is as unreadable as Japanese today.

What this does not fix

Face.parse reads no GSUB or GPOS and there is no bidi, so a cascade makes CJK, kana, hangul, Greek and Hebrew correct and leaves Arabic unjoined and left to right, and Devanagari and Thai unreordered. I am shipping faces only for the scripts a cascade genuinely fixes, and no face for the others, on the grounds that a wrong rendering is harder to notice than a missing one.

Happy to test any shape you prefer on macOS and Linux.