Document registered fonts and prove the CJK path on Windows CI#144
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
- New Fonts page: the Options.fonts / registerCanvasFont path with a CJK anchor example, every registration error and its teaching, ownership until Runtime.deinit, how typography tokens resolve a registered face, and the honest platform + TypeScript-tier status - Cross-link the tofu guard's teaching in Native UI and the theming typography group to the new page
- font_coverage_message, the ui builder's Debug diagnostic, the markup CLI usage text, and the native-ui skill now name registering a covering font (UiApp Options.fonts) alongside vector icons and plain words - Platform Support gains a text-and-registered-fonts matrix row: first-class on the three desktops per the code and suite, stated unverified on mobile where no test registers a font and host measurement has no registered-font seam
- Commit a 2.2 KB OFL-licensed fixture (Noto Sans SC instanced at wght=400, subsetted to 你好世界 plus notdef, license beside the file) and a receipt test: a scaffold-shaped UiApp registers it through Options.fonts, every ideograph resolves to its own glyph with nonzero rasterized ink, and the reference screenshot differs from the bundled-face tofu twin - Add zig build test-canvas-fonts (the font-registry suite filtered from the desktop tests) and run it natively on the Windows CI lane; the same tests keep running in zig build test via the canvas-frame shard - Note the Windows-native receipt in the platform matrix footnote
- The example now teaches the mono_font_id slot instead of claiming whole-app coverage, and the lockstep guarantee names the desktop paths and defers mobile to the platform notes.
- The end-to-end receipt now renders a third screenshot: the same registered face showing four ideographs the fixture deliberately does not map (each pinned with glyphIndex() == 0 first), and asserts the real-CJK shot differs from that self-calibrating control. - A renderer that wrongly resolved every ideograph to the registered face's notdef glyph and inked its outline would differ from the bundled-face shot and pass nonblank, yet match this control byte-for-byte; sabotage-verified by forcing the uncovered string into both slots and watching the new assertion fail. - The scaffold model gains a show_uncovered_cjk toggle so the control renders through the identical dispatch-rebuild-screenshot pipeline as the receipt itself.
- The fonts page's registration-time claim now carries its one honest exception: point-matched composite placement is the per-glyph refusal maxp cannot gate, surfacing at first raster as the deterministic block fallback — never a crash, never a silent skip — and no measured production face uses it. - New changelog.d fragment covers the branch's user-visible changes: the tofu-guard teachings now name font registration first, the fonts docs page, and the Windows-native CJK receipt lane. - src/runtime/testdata/fonts/OFL.txt drops one trailing space (line 21) so git diff --check runs clean; the license wording stays verbatim.
- The per-(id, size) NSFont cache is per-process while font-id permanence is per-runtime, so an embedder destroying a runtime and registering a different face under the same id measured and drew the first face from stale cache entries. - native_sdk_appkit_register_font now purges the id's "id/"-prefixed cache entries under the descriptor table's @synchronized guard before installing the new descriptor, and the comment claiming cached NSFonts never go stale states the real lifetime instead. - No SDK test tier links appkit_host.m (only managed app builds compile it), so the eviction wiring is pinned by a file-contains check step like the other AppKit host contracts; the CEF host's register_font is a stateless accept with no cache, so nothing to evict there.
- noteCanvasFontsChanged forced a repaint but installed UiApps never rebuilt (the frame handler rebuilds only on install, scale change, or size change), so the repaint re-inked widget frames and baked text layouts measured before the face joined — breaking the fonts page's every-open-surface-re-measures promise. - The registered-font count is the runtime's fonts generation (registration is permanent, no unregister): UiApp adopts it at install and both frame handlers compare it per presented frame, rebuilding ALL installed surfaces — main canvas and declared windows — through rebuildAllViews when a face joined late; rebuildEmitsTokens also treats a text-measure provider change as an emit reason so static-token apps push the font-aware provider into the stored tokens. - Test: an app with no declared fonts installs a main canvas plus a declared window, registers the CJK fixture through the runtime seam, and one arriving frame must move BOTH surfaces' text frame widths (mixed CJK+Latin text — the Latin tail measures at Geist's sub-em advances before and the face's 1.0 em notdef after); sabotage-verified: with the rebuild call removed, exactly this test fails.
- The single "Text & registered fonts" row rendered "Not available today" for iOS/Android, false for bundled text: mobile hosts present the same reference-renderer pixels the desktop software hosts ink.
- Now two rows: "Text" is full on all five platforms, and "Registered fonts" keeps full desktop with the honest none-unverified mobile note; footnote 3 already narrates both halves, so fn={3} stays on every cell and nothing renumbers.
- The width NSCache in native_sdk_appkit_measure_text survived re-registration: the round-3 eviction covered only the NSFont size cache, so a new runtime reusing an id kept measuring the previous face's widths while drawing the new one. - NSCache cannot enumerate keys, so prefix eviction is impossible there; instead registration bumps a per-id generation (stored beside the descriptor table, under the same @synchronized) and the width-cache key includes it, so the old generation's entries become unreachable and age out under the cache's own count limit — keeping NSCache's bounding and memory-pressure purging, which a dictionary conversion would forfeit for a 16384-entry text-keyed cache. - The test-appkit-registered-font-cache-eviction pin step now covers the width-cache half (generation table, bump inside register_font, generation-carrying key), same textual tier as round 3 since no SDK test tier compiles the ObjC host.
…he truth - Late registration: automatic re-measure and rebuild is UiApp wiring, so the sentence now says UiApp surfaces rebuild automatically while callers driving the runtime directly re-emit their display lists after registering. - No-cascade: true for the engine paths (reference renderer, glyph atlas, SDK-rasterized packet text), but macOS host-drawn text follows platform shaping including system-font fallback, so uncovered codepoints there may render from a substituted family instead of notdef — the paragraph now states both halves.
- New optional platform service unregisterGpuSurfaceFont(id): Runtime.deinit calls it per registered id before freeing the bytes, so the macOS host's per-process font state (CoreText descriptor, size cache, width-cache generation) no longer outlives the runtime that registered it; the CEF host accepts statelessly and platforms without the register seam keep answering UnsupportedService. - The null platform records the teardown call, the embed cycle/idempotence tests assert deinit makes it exactly once, and the AppKit eviction pin step now holds the ObjC removal and the deinit call site. - Fonts page: deinit returns the host-side registration too, and host font state is one face per id per process (concurrent runtimes sharing an id see the last registration - a deliberate current constraint).
- rebuildForRegisteredFonts assigned fonts_built_count before rebuildAllViews, so under production's degrade policy a failed rebuild (widget budget, allocator pressure, a secondary window's emit) marked stale layouts as font-current and never retried. - New test drives a late registration into a budget-failing rebuild, asserts the count stays unadopted, and proves the next healthy frame retries, re-measures with the registered face, and only then adopts.
- Footnote 3 opened with "identical code on every platform" while its own next sentence described macOS resolving packet text through CoreText; the opening now names the SDK's TrueType pipeline as the shared reference path (goldens, screenshots, software presents), matching the distinction the fonts page draws. - Every other fact in the footnote is unchanged.
ctate
force-pushed
the
docs/registered-fonts-cjk
branch
from
July 19, 2026 00:35
10f9a5d to
3475720
Compare
- Replace the per-id registration generations with one monotonic process-global token counter: registration stamps the id with a fresh never-repeated token and the measured-width NSCache key carries it, so no registration can ever reach a previous life's cached widths. - Because tokens never repeat, unregister now deletes the id's token record outright instead of retaining a bumped entry per retired id — descriptor, size-cache entries, and token record all drop, leaving zero host state per retired id, which is what the fonts page's runtime-cycle sentence promises. - Align the file-contains pins with the token names and additionally pin the token-record removal inside native_sdk_appkit_unregister_font so the zero-retained-state property cannot silently regress.
…tion - Each CanvasFontEntry now captures the platform's unregister fn and context when the registration is pushed to the host, and Runtime.deinit returns the registration through that captured pair — never live options.platform, which is publicly mutable and may name a different host (or a null seam) by teardown time, the owned_allocator identity-freeze doctrine applied to the host seam. - Pin the capture and the deinit call site in the file-contains step, and add an embed test that registers through platform A, swaps options.platform to platform B, and asserts the deinit unregister lands on A (count 1) and never on B (count 0); reverting to the live-options read fails both the test and the pin. - One services read in registerCanvasFont now serves both the host sync and the captured return path, so the host that hears the registration is exactly the owner the entry names.
- registerGpuSurfaceFont now returns the host's ownership token for the registration (0 from stateless hosts); the runtime stores it in the font entry beside the captured owner and Runtime.deinit presents it at unregister, so the AppKit host removes an id's descriptor and caches only while the id's current registration still carries that token — an older runtime's deinit can no longer tear down a newer runtime's live face under a shared id, and a stale token is a no-op accept. - The null platform gains an opt-in host-font mirror (id-keyed, last-wins, monotonic tokens — the AppKit table shape without CoreText) plus a token field on its unregister recorder; a new embed test registers one id through two runtimes and proves the newer registration survives the older runtime's deinit. - The AppKit pin step now pins the two-argument unregister signature, the token-match guard line, the reported out-token, and the three-argument deinit call, so reverting the host to id-keyed removal fails the pins.
- native_sdk_appkit_measure_text read the registration token and resolved the font under separate lock acquisitions, so a registration landing between them paired token 0 with the new registered face and cached registered widths under the reusable token-0 key — served as stale registered widths after teardown, when token 0 means built-in resolution. - NativeSdkRegisteredFontSnapshot now reads the id's token and resolves its registered face inside one @synchronized section (shaping stays outside the lock: a stale-but-consistent pair keys a retired token no lookup reaches); built-in resolution is split into NativeSdkBuiltInFontForFontId so token 0 only ever pairs with built-in widths. - measure_text_advances audited: it memoizes nothing host-side (the engine caches the batch under its own measure generation), so it has no (token, face) pairing to tear; the pin step now pins the snapshot signature and its measure_text call site.
…n down - unregister_font purged the descriptor, token, and size cache but the measured-width NSCache was a function-local static inside measure_text, unreachable from teardown: retired-token entries could never be served again (tokens never repeat) yet stayed resident — up to 16,384 keys carrying full text strings — until memory pressure, contradicting the zero-retained-state contract. - The cache is hoisted to a shared accessor (the same shape as the NSFont size cache) and the token-matched unregister path clears it wholesale — NSCache cannot enumerate keys, so per-id eviction is impossible; the trade is stated at the site (teardown-frequency event, live ids re-warm in one measure each), and a stale-token no-op never clears. - The cache-eviction pin step holds the accessor, the clear, and the measure_text call site; sabotage-verified (pin fails with the clear removed). No behavioral tier can observe the ObjC cache, so textual pins are the honest coverage.
- Seven review rounds accumulated user-visible surface beyond the original docs/diagnostics/CI fragment: the late-registration rebuild, the macOS host font teardown, and the registerGpuSurfaceFont token break with the new unregisterGpuSurfaceFont service. - A new fix-tagged fragment covers them, per the one-tag-per-fragment convention; the Breaking bullet states the break deliberately with a matter-of-fact migration note for custom-platform embedders. - Internal-only work (pins, test machinery) stays out, matching the fragments' user-facing voice.
- measure_text shapes outside the descriptor guard, so an unregister landing mid-shape cleared the width cache and then had it repopulated by the in-flight write: a retired-token entry no lookup can serve but resident until memory pressure - Registered-token writes now re-enter the guard and cache only while the id still carries the snapshotted token; token 0 (built-in resolution, never unregistered) keeps the unconditional write - Pin the recheck shape in test-appkit-registered-font-cache-eviction; advances batch and packet drawing re-audited as memoizing nothing host-side that the window could touch
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Registered CJK fonts shipped in #139 with no docs coverage. This round documents the register-a-font path end to end and pins it with a CI-level render proof on Windows.
docs/fontspage: why bundled coverage isn't enough, theOptions.fontsregistration example, every registration error honestly documented (including the glyph-budget gate and its measured limits), the frozen-allocator ownership story, how text finds the registered face per platform, and the current Zig-tier-only TypeScript status.test-canvas-fontsstep — the pipeline is platform-neutral TTF parsing plus the software renderer, so the lane proves that code executes correctly on a real Windows host.