@weasel-js/font 1.9.4 → 1.10.0

package/dist/{test-seams-BC5Ykf4D.d.ts → test-seams-BvULFsbo.d.ts}

@@ -29,8 +29,43 @@ interface GlyphTextureSink {
     upload(id: string, source: TexSource): string;
     uploadR8(id: string, width: number, height: number, data: Uint8Array): void;
     subImageR8(id: string, x: number, y: number, w: number, h: number, data: Uint8Array): void;
+    /** Create a texture of premultiplied RGBA texels that are a color, not a
+     *  field, so it may be minified through mipmaps. */
+    uploadRGBA(id: string, width: number, height: number, data: Uint8Array): void;
+    subImageRGBA(id: string, x: number, y: number, w: number, h: number, data: Uint8Array): void;
 }
 
+/**
+ * The dynamic glyph atlas's pages: their CPU-side bytes, and bringing each
+ * renderer's texture of one up to date. Two sets: distance fields, one byte a
+ * texel, and color glyphs, four.
+ */
+
+interface DynamicPage {
+    data: Uint8Array;
+    /** Bumps on every write; each write appends a patch with seq = version. */
+    version: number;
+    patches: {
+        seq: number;
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    }[];
+}
+/** Texture-cache key for a dynamic field page (parallel to `textureCacheKey`). */
+declare function dynamicPageTextureId(page: number): string;
+/** Texture-cache key for a page of color glyphs. */
+declare function colorPageTextureId(page: number): string;
+/** Bring `cache`'s copy of field page `pageIndex` up to date: full R8 upload
+ *  the first time, `texSubImage2D` patches after. Returns false if the page
+ *  doesn't exist yet. */
+declare function syncDynamicPageTexture(cache: GlyphTextureSink, pageIndex: number): boolean;
+/** The same for a page of color glyphs, whose texels are premultiplied RGBA. */
+declare function syncColorPageTexture(cache: GlyphTextureSink, pageIndex: number): boolean;
+/** @internal test seam — inspect CPU-side field pages. */
+declare function _getPagesForTests(): readonly DynamicPage[];
+
 /**
  * Canvas-2D glyph rasterizer for the dynamic SDF atlas. `fillText` is the
  * only web-platform route to *installed* machine fonts (no outline access),
@@ -43,28 +78,18 @@ interface GlyphTextureSink {
  * The bitmap includes a PAD border on all four sides so the SDF field has
  * room to fall off. Blank glyphs (e.g. space) return width/height 0.
  *
- * On BAKE_SIZE — measured 2026-07-29, comparing the reconstructed field
- * against a direct `fillText` of the same glyph at each display size, with
- * sub-pixel registration searched out so it measures fidelity and not
- * alignment. Mean per-pixel coverage error, averaged over A/S/e/W/8:
+ * On BAKE_SIZE: mean per-pixel coverage error of the reconstructed field
+ * against a direct `fillText` of the same glyph at each display size:
  *
  *   display px   12     16     24     32     48     64     96     128
  *   error        .096   .083   .059   .039   .024   .023   .037   .049
  *
- * Two things follow, both of them counterintuitive enough to be worth
- * writing down. The error is minimized *at* the bake size, so raising
- * BAKE_SIZE does not improve small text — it moves the sweet spot away from
- * the 12–32px range where UI text actually lives and makes it worse. And the
- * magnification side is the mild one: 128px costs about twice the floor,
- * which is the corner rounding the shader header already owns.
- *
- * The 12–16px end is the largest divergence, and it is not undersampling —
- * 3×3 supersampling the reconstruction roughly halves the error at 24–48px
- * but recovers almost nothing at 12–16px (.096 → .089, .083 → .068). What is
- * left there is a hinted rasterizer placing stems on the pixel grid, which no
- * size-independent field can encode. So there is nothing to buy with more
- * taps, a bigger bake, or mipmaps (which a packed atlas cannot have anyway —
- * mip levels blend across glyph rects).
+ * The error is minimized *at* the bake size, so raising BAKE_SIZE does not
+ * improve small text — it moves the sweet spot away from the 12–32px range
+ * and makes it worse. The 12–16px error is not undersampling: supersampling
+ * the reconstruction recovers almost nothing there. What is left is a hinted
+ * rasterizer placing stems on the pixel grid, which no size-independent field
+ * can encode, so more taps, a bigger bake, or mipmaps buy nothing.
  */
 
 interface FaceMetrics$1 {
@@ -79,15 +104,29 @@ interface RasterizedGlyph {
     top: number;
     advance: number;
 }
+/** A glyph in its own colors. Placed as a {@link RasterizedGlyph} is. */
+interface RasterizedColorGlyph {
+    width: number;
+    height: number;
+    /** Premultiplied RGBA, four bytes a texel. */
+    rgba: Uint8ClampedArray;
+    left: number;
+    top: number;
+    advance: number;
+}
 interface GlyphRasterizer {
     faceMetrics(family: string, weight: number, style: FontStyle): FaceMetrics$1;
     rasterize(family: string, weight: number, style: FontStyle, codepoint: number): RasterizedGlyph;
+    /** `text`, one grapheme cluster, as the color glyph the platform draws for
+     *  it, or null when it draws none: no ink, or ink in the fill color alone. */
+    rasterizeColor?(family: string, weight: number, style: FontStyle, text: string): RasterizedColorGlyph | null;
 }
 
 /**
  * DynamicGlyphAtlas — runtime single-channel SDF glyphs for canvas-sourced
  * (installed machine) fonts. TinySDF technique: canvas fillText at 48 px →
- * Euclidean distance transform → shelf-packed R8 pages (1024², max 4).
+ * Euclidean distance transform → shelf-packed R8 pages (1024², max 4). When
+ * the pages fill they are emptied whole and the text on screen bakes again.
  *
  * Baked MSDF atlases always win: this tier only serves families registered
  * via `registerCanvasFont` that have no baked entry (see resolveFontVariant).
@@ -97,13 +136,13 @@ interface GlyphRasterizer {
  * baked atlases. A char's advance is valid immediately (measureText); its
  * atlas rect fills in when the bake lands (width 0 / page -1 until then, so
  * layout advances the pen but emits no quad).
+ *
+ * An emoji is the one glyph kept as the canvas drew it: `requestCluster`
+ * rasterizes a whole grapheme cluster in its own colors onto a second set of
+ * pages, RGBA, that fill and empty with the field pages.
  */
 
-/** How many glyphs the dynamic atlas will rasterize synchronously before
- *  deferring the rest to a later flush. Caps the frame cost of text that
- *  suddenly needs many new glyphs; the leftovers arrive a tick later and
- *  notify through `onGlyphReady`. */
-declare const DEFAULT_BAKE_BUDGET = 16;
+/** A face whose glyphs are rasterized on demand into a shared atlas page, rather than shipped as a prebuilt one. */
 interface DynamicFace {
     family: string;
     weight: number;
@@ -113,18 +152,13 @@ interface DynamicFace {
     /** Char record for `cp`, measured on first request (advance always valid
      *  immediately; atlas rect fills in when the bake lands). */
     requestGlyph(cp: number): BmFontChar;
-}
-interface DynamicPage {
-    data: Uint8Array;
-    /** Bumps on every glyph blit; each blit appends a patch with seq = version. */
-    version: number;
-    patches: {
-        seq: number;
-        x: number;
-        y: number;
-        w: number;
-        h: number;
-    }[];
+    /**
+     * The color glyph the platform draws for the grapheme cluster `text`,
+     * measured on first request as `requestGlyph`'s is, or null when it draws
+     * none. Its record is marked `color` and its rect is on a color page. It is
+     * not in `font.charMap`, which holds one code point each.
+     */
+    requestCluster(text: string): BmFontChar | null;
 }
 /** One family served by the dynamic canvas-SDF tier. See `listCanvasFonts`. */
 interface CanvasFontEntry {
@@ -149,75 +183,49 @@ declare function registerCanvasFont(family: string): void;
  *     so returning to `'canvas'` makes it `true` again.
  *   - never enrolled → `false`, including under `'canvas'` (that policy
  *     enrolls lazily, on the first miss).
- *
- * The membership reading would answer `true` for an auto-enrolled family
- * under `'substitute'` / `'none'`, where nothing routes to this tier — a
- * caller predicting what renders would be told the opposite of the truth.
- * Mirrors `listFonts`, which reports the baked registry alone for the same
- * reason: "enrolled" is not "will render".
  */
 declare function isCanvasFont(family: string): boolean;
 /**
  * Every family the dynamic canvas-SDF tier will serve *right now* — the
  * enumeration companion to `isCanvasFont`, which answers one family at a
  * time. Same "service, not membership" rule: an auto-enrolled family appears
- * only while the `'canvas'` policy is in force.
- *
- * Exists so a consumer can offer these families in a font picker.
- * `listFonts` reports the baked registry alone, so without this the only
- * ways to present canvas-served families were to hard-code a list beside the
- * `registerCanvasFont` calls or to omit them — a UI inventing its own answer
- * about what will render.
+ * only while the `'canvas'` policy is in force. `listFonts` reports the baked
+ * registry alone.
  *
  * `enrollment` distinguishes a consumer's explicit `registerCanvasFont` from
  * a lazy enrollment the policy made on a miss; both render identically, but
  * only the explicit one survives a policy change.
  */
 declare function listCanvasFonts(): readonly CanvasFontEntry[];
-/** Remove a canvas family. Its faces are dropped; already-baked glyph
- *  pixels stay in their pages (no eviction in v1). */
+/** Remove a canvas family. Its faces are dropped; the room its glyphs took
+ *  comes back when the pages next fill and are emptied. */
 declare function unregisterCanvasFont(family: string): void;
-/** Reset the per-frame synchronous bake budget. Called by
- *  `WeaselRenderer.render()` at frame start; the headless
- *  `renderSceneToPixels` path passes Infinity so print never defers. */
-declare function resetBakeBudget(n?: number): void;
-/** Texture-cache key for a dynamic page (parallel to `textureCacheKey`). */
-declare function dynamicPageTextureId(page: number): string;
-/** Bring `cache`'s copy of page `pageIndex` up to date: full R8 upload the
- *  first time, `texSubImage2D` patches after. Returns false if the page
- *  doesn't exist yet. */
-declare function syncDynamicPageTexture(cache: GlyphTextureSink, pageIndex: number): boolean;
+/**
+ * Measure `family`'s canvas faces again, or every family's when none is named.
+ *
+ * The tier keeps each face's metrics and each glyph's shape and advance from
+ * the first time it is asked. A web font that finishes loading after that is
+ * picked up from `document.fonts` without this call; a face the document
+ * never announces, one loaded before it was added, needs it.
+ */
+declare function refreshCanvasFont(family?: string): void;
 /** @internal test seam — inject a fake rasterizer (jsdom has no canvas
  *  metrics). Pass null to restore the lazy default. */
 declare function __setGlyphRasterizerForTests(r: GlyphRasterizer | null): void;
-/** @internal test seam — inspect CPU-side pages. */
-declare function _getPagesForTests(): readonly DynamicPage[];
 /** @internal test seam — clear all dynamic-font state. */
 declare function _resetDynamicFontsForTests(): void;
 
 /**
  * The parsed-font seam for the outline tier.
  *
- * A face answers exactly one question — "what does codepoint N look like?" —
- * and answers it as **SVG path data in em space**: one unit is one em, y
- * grows downward, and the origin sits on the baseline at the glyph's pen
- * position. That is a complete description of the glyph independent of size,
- * zoom, and position, which is the whole reason the tier exists: tessellate
- * once, transform per instance.
- *
- * ### Why `d` and not a command stream
- *
- * `@weasel-js/font` is a Tier A leaf — `@weasel-js/core` depends on it and
- * never the reverse (see `leaf-purity.test.ts`), so this package cannot name
- * core's `PolygonPath`. The alternative to a string would be re-declaring
- * core's `PATH_M`/`PATH_L`/… opcodes over here and trusting two packages to
- * keep the same numbering forever. SVG `d` is the kit's documented language
- * for geometry crossing a boundary (`docs/conventions.md`), core already
- * ships `pathFromD`, and a glyph outline is exactly the case it describes.
+ * A face describes a glyph as **SVG path data in em space**: one unit is one
+ * em, y grows downward, and the origin sits on the baseline at the glyph's pen
+ * position. That is independent of size, zoom, and position, so a glyph is
+ * tessellated once and transformed per instance.
  *
- * The string is also a natural cache key and costs nothing to hold: the
- * parse happens once per glyph, and core caches the *tessellation*, not the
- * text.
+ * `d` and not a command stream: `@weasel-js/core` depends on this package and
+ * never the reverse, so it cannot name core's `PolygonPath`, and SVG `d` is
+ * the kit's language for geometry crossing a boundary (`docs/conventions.md`).
  */
 
 /** A parsed font face, viewed only as a source of glyph outlines. See the
@@ -242,15 +250,12 @@ interface OutlineFace {
     faceMetrics?: FaceMetrics;
     /**
      * Em-space SVG path data for `cp`, or `null` when this face has no glyph
-     * for the codepoint *or* the glyph has no contours (a space). Both answers
-     * mean the same thing to a caller: there is nothing here to tessellate, so
-     * fall through to whatever tier would have drawn it.
+     * for the codepoint *or* the glyph has no contours (a space).
      */
     glyphD(cp: number): string | null;
     /**
      * Advance width for `cp` in em units, or `null` when the face has no glyph
-     * for it. Distinct from `glyphD` answering `null`: a space has an advance
-     * and no contours, and layout needs the advance either way.
+     * for it. A space has an advance and no contours.
      */
     advanceOf(cp: number): number | null;
     /** Kerning adjustment between two codepoints, in em units — negative pulls
@@ -258,20 +263,14 @@ interface OutlineFace {
     kernOf(left: number, right: number): number;
 }
 /**
- * Turn font file bytes into a face. Async because the default implementation
- * dynamically imports its parser — see `opentypeParser.ts` for why that
- * matters — and because a caller may want to hand back a face that finishes
- * initializing off-thread.
+ * Turn font file bytes into a face. May be async: the default implementation
+ * dynamically imports its parser.
  */
 type OutlineParser = (bytes: ArrayBuffer) => OutlineFace | Promise<OutlineFace>;
 
 /**
- * FontRegistry and registerFont() public API.
- *
- * Variants are keyed by (family, weight, style). registerFont() takes a
- * FontVariant alongside the family and the two URLs; the registry stores
- * entries in a two-level Map so resolveFontVariant() can iterate a family's
- * variants for the fallback chain.
+ * The atlas font registry, keyed by (family, weight, style), and the fallback
+ * chain that resolves a request against it.
  */
 
 /** A registered face: its parsed metrics and the atlas image to sample. */
@@ -296,8 +295,7 @@ declare function getFont(family: string, weight?: number, style?: FontStyle): Fo
 /**
  * The decoration and script metrics of an exact `(family, weight, style)` —
  * the atlas's when one is registered, else a loaded outline face's. Like
- * {@link getFont}, it walks no fallback chain and enrolls no canvas font,
- * which suits a caller holding a CSS font name rather than a layout result.
+ * {@link getFont}, it walks no fallback chain and enrolls no canvas font.
  * An idle outline face starts loading, as it would for layout.
  * A run already resolved for layout reads `faceMetricsOf(result)` instead.
  */
@@ -312,17 +310,15 @@ interface RegisteredFont {
     }[];
 }
 /**
- * Enumerate the registry — what a font picker can honestly offer. Families
- * come back in registration order; variants sorted by weight, then style, so
- * the output is stable enough to assert against.
+ * Enumerate the registry. Families come back in registration order; variants
+ * sorted by weight, then style.
  */
 declare function listFonts(): readonly RegisteredFont[];
 /**
  * The weights `family` has a real face for, on the atlas tier or the outline
- * tier, in either style — what a weight picker can honestly offer. Ascending
- * and deduplicated; empty for a family nothing registered. An outline face
- * whose load failed is left out. The canvas tier is not consulted: it
- * rasterizes whatever weight it is asked for, so it has no list to report.
+ * tier, in either style. Ascending and deduplicated; empty for a family
+ * nothing registered. An outline face whose load failed is left out. The
+ * canvas tier is not consulted: it rasterizes whatever weight it is asked for.
  */
 declare function listFontWeights(family: string): readonly number[];
 /** Options for {@link registerFont}. */
@@ -342,8 +338,7 @@ interface RegisterFontOptions {
  * present is a no-op.
  *
  * Eager by default: both files are fetched now. With `{ lazy: true }` they are
- * fetched the first time text asks for the family, which keeps the atlas off
- * the critical path of anything that draws no text.
+ * fetched the first time text asks for the family.
  */
 declare function registerFont(family: string, variant: FontVariant, metricsUrl: string, atlasUrl: string, opts?: RegisterFontOptions): Promise<void>;
 /** One face text is set in, the way a render asks for it — what
@@ -367,21 +362,18 @@ interface FontRequest {
  * would draw instead when the requested one has no atlas; and the variant's
  * outline face when one is registered.
  *
- * Starts each lazily declared variant and joins any fetch already running.
  * Resolves once they have all landed; a registered variant counts as loaded.
  * Rejects when a load fails, or for a family name `registerFont` never saw —
- * a request for such a family is not an error, since the canvas and outline
- * tiers serve families no atlas was registered for.
+ * a {@link FontRequest} for such a family is not an error, since the canvas
+ * and outline tiers serve families no atlas was registered for.
  */
 declare function warmFonts(fonts?: readonly (string | FontRequest)[]): Promise<void>;
 /**
  * Could a registration that has not landed yet still serve this request?
  * True while any `registerFont` for the family is fetching — the within-family
  * chain may resolve to whichever variant it brings — or while an outline face
- * registered for this exact variant has not finished loading.
- *
- * A face that resolves to nothing right now is either missing or merely late;
- * this tells the two apart, so "not registered" is reported only when it is.
+ * registered for this exact variant has not finished loading. Tells a face
+ * that is missing from one that is merely late.
  */
 declare function fontPending(family: string, weight?: number, style?: FontStyle): boolean;
 /**
@@ -405,9 +397,8 @@ interface ResolveResult {
      * including `family`, when the cross-family policy substituted a default.
      *
      * This is the atlas identity: pass all three to `getFont` /
-     * `textureCacheKey` and the lookup hits. Describing only weight and style
-     * here once let a caller key its draw on the *requested* family, which
-     * resolves to no atlas at all and paints nothing.
+     * `textureCacheKey` and the lookup hits. Keying a draw on the *requested*
+     * family resolves to no atlas at all and paints nothing.
      *
      * The synthetic flags describe the gap between requested and resolved for
      * shader-side compensation. When `entry` is null, these mirror the
@@ -435,9 +426,8 @@ interface ResolveResult {
     outlineFace?: OutlineFace;
     /**
      * Set when the requested family was not registered and the fallback policy
-     * substituted a different one. Reported structurally so a UI can say
-     * "Inter — not loaded, showing Roboto" instead of leaving the user to
-     * wonder why the family control did nothing.
+     * substituted a different one, so a UI can say "Inter — not loaded, showing
+     * Roboto".
      */
     substituted?: {
         requested: string;
@@ -455,23 +445,14 @@ declare function resolveFontVariant(family: string, weight: number, style: FontS
  * Escalate a *single codepoint* to the dynamic tier when the atlas that
  * resolved for the run has no glyph for it.
  *
- * `resolveFontVariant` answers at family granularity: it picks one tier for a
- * whole run. But a baked MSDF atlas covers a fixed charset, so a run served by
- * a perfectly good atlas can still contain a character that atlas never baked
- * — an em dash, a curly quote, anything outside the subset. The dynamic tier
- * rasterizes on demand from installed fonts and can serve exactly those.
+ * A baked MSDF atlas covers a fixed charset, so a run it serves can still
+ * contain a character it never baked — an em dash, a curly quote. The dynamic
+ * tier rasterizes on demand from installed fonts and can serve those.
  *
  * Returns a canvas-tier `ResolveResult` whose `dynamicFace` the caller drives
- * with `requestGlyph(cp)`, or `null` when escalation isn't available:
- *
- *   - Policy `'none'` documents a miss as a *hard* miss. Quietly reaching for
- *     another tier per codepoint would undo that, so it doesn't.
- *   - No canvas to rasterize into (SSR, a jsdom test without one) makes the
- *     dynamic tier constructible-but-broken; `getDynamicFace` throws and this
- *     reports the miss instead of taking the caller down with it.
- *
- * Cheap to call per missing codepoint: faces are cached by variant and glyphs
- * by codepoint, so a repeat is two map lookups.
+ * with `requestGlyph(cp)`, or `null` when escalation isn't available: under
+ * policy `'none'`, which documents a miss as a *hard* miss, or with no canvas
+ * to rasterize into (SSR, a jsdom test without one).
  */
 declare function resolveGlyphFallback(family: string, weight: number, style: FontStyle): ResolveResult | null;
 
@@ -481,10 +462,8 @@ declare function resolveGlyphFallback(family: string, weight: number, style: Fon
  * baseline to its top edge (y grows down) and a script's `shift` positive
  * for a rise.
  *
- * Both glyph tiers carry the same record — an atlas bakes it into its JSON,
- * a parsed face reads it off the font's tables — and both derive it through
- * {@link faceMetricsFromTables}, so one font yields one set of numbers
- * whichever tier ends up serving a run.
+ * Both glyph tiers derive the record through {@link faceMetricsFromTables},
+ * so one font yields one set of numbers whichever tier serves a run.
  */
 
 /** One rule: the top edge's distance below the baseline, and its weight. */
@@ -552,12 +531,10 @@ interface FaceMetricTables {
  * positive downward.
  *
  * The OpenType rule: `OS/2` `sTypoAscender`/`sTypoDescender` when the font
- * sets `USE_TYPO_METRICS`, otherwise `hhea`. It is the browser's rule rather
- * than a typographer's because the DOM edit overlay stands in for the canvas
- * and can only ever get the browser's numbers. Firefox, and every engine on
+ * sets `USE_TYPO_METRICS`, otherwise `hhea`. Firefox, and every engine on
  * Linux, follow it; Chromium and WebKit on macOS read `hhea` even when the
- * flag is set, and the overlay's measured baseline correction absorbs the
- * difference there. `verticalMetrics.browser.test.ts` pins both.
+ * flag is set, and the DOM edit overlay's measured baseline correction
+ * absorbs the difference there.
  *
  * Falls back to the typo pair, then the win pair, when `hhea` is absent or
  * zero.
@@ -572,16 +549,14 @@ declare function verticalMetricsFromTables(t: FaceMetricTables): {
  * `post.underlinePosition` and `OS/2.yStrikeoutPosition` are the rule's top
  * edge, positive above the baseline. `ySubscriptYOffset` is positive
  * *downward*, unlike its superscript twin. A zero weight or size is a font
- * that left the field blank, not one asking for an invisible rule, so that
- * entry is dropped and the caller's default applies — which is also how an
- * `OS/2` table older than version 2 reads, since it has no heights at all.
+ * that left the field blank, so that entry is dropped and the caller's
+ * default applies.
  */
 declare function faceMetricsFromTables(t: FaceMetricTables): FaceMetrics | undefined;
 /**
  * The face metrics behind a resolved run — the outline face's on the outline
- * tier, the atlas's on the atlas tier. The canvas tier rasterizes through
- * `CanvasRenderingContext2D`, which exposes no font tables, so it has none
- * and callers fall back to their defaults.
+ * tier, the atlas's on the atlas tier. The canvas tier has none, so callers
+ * fall back to their defaults.
  */
 declare function faceMetricsOf(result: ResolveResult): FaceMetrics | undefined;
 
@@ -616,6 +591,9 @@ interface BmFontChar {
     yoffset: number;
     xadvance: number;
     page: number;
+    /** Set on a glyph whose atlas rect holds its own colors, on a page of the
+     *  dynamic tier's color set: an emoji. It is painted as it is, untinted. */
+    color?: true;
 }
 /** A kerning pair: `amount` px to add to the advance when `second` follows
  *  `first`. Codepoints, not glyph indices. */
@@ -716,13 +694,9 @@ declare function _resetFallbackForTests(): void;
  * sans-serif` in the page resolves to Helvetica. Anything the DOM sets in
  * place of canvas text — the text edit overlay above all — asks here instead
  * of writing the name through. The answer names a private `FontFace` loaded
- * from the family's registered font file, with the family itself as fallback
- * while that loads.
- *
- * The font file is the one `registerFontOutlines` holds; that registry is the
- * kit's record of which faces have real bytes behind them. An atlas-only
- * family has none, so the DOM gets the browser's own face for the name and a
- * one-time warning says which registration would fix it.
+ * from the file `registerFontOutlines` holds, with the family itself as
+ * fallback while that loads. An atlas-only family has no file, so the DOM gets
+ * the browser's own face for the name.
  */
 
 /**
@@ -733,15 +707,13 @@ declare function _resetFallbackForTests(): void;
  *   the `'canvas'` fallback policy) comes back unchanged: the DOM already
  *   resolves the name to the same face.
  * - A family drawn from a baked atlas or from outlines comes back as a private
- *   face built from its `registerFontOutlines` file — every registered weight
- *   and style of it, so the browser picks and synthesizes within the family
- *   the way the canvas does — followed by `family` as the fallback.
+ *   face built from its `registerFontOutlines` file, in every registered
+ *   weight and style, followed by `family` as the fallback.
  * - Under the `'substitute'` policy, the face is the substitute's.
  *
  * Starts loading the face on first call and never waits for it; ask
- * {@link cssFontFamilyLoading} for that. A face whose bytes arrived earlier —
- * passed to `registerFontOutlines` as an `ArrayBuffer`, or read for the canvas
- * — was built when they did. Outside a browser, `family` comes back unchanged.
+ * {@link cssFontFamilyLoading} for that. Outside a browser, `family` comes
+ * back unchanged.
  */
 declare function cssFontFamily(family: string, variant?: FontVariant): string;
 /**
@@ -765,57 +737,35 @@ declare function _resetDomFacesForTests(): void;
  *
  * ### What this tier is for
  *
- * A distance field is a *sampled* representation. The baked MSDF atlas is
- * generated from outlines and holds up well; the dynamic canvas-SDF tier
+ * A distance field is a *sampled* representation: the dynamic canvas-SDF tier
  * (`../dynamic/`) reconstructs its field from a 48px raster, so magnifying it
- * past a few times the bake size exposes the raster as contour wobble — bumps
- * one bake-texel apart, ±2–3px at 8×. No bake size fixes that, it only moves
- * the size at which it appears (`glyphRasterizer.ts` measures the tradeoff:
- * error is *minimized at* the bake size, so raising it spoils the 12–32px
- * range where most text lives).
- *
- * Above a size threshold the answer is to stop sampling: parse the font, take
- * the glyph's outline, and hand it to the path renderer the kit already has.
- * Exact at every zoom, and — because a glyph becomes an ordinary path — it
- * takes strokes and non-solid fills for free.
- *
- * Below the threshold the atlas still wins, and not narrowly: outlines carry
- * no hinting and no stem darkening, so body text at 12–16px rendered from
- * them looks *worse* than a platform rasterizer that puts stems on the pixel
- * grid. Two tiers with a size threshold is the standard hybrid, not a
- * compromise.
+ * past a few times the bake size exposes the raster as contour wobble. Above a
+ * size threshold the glyph's outline goes to the path renderer instead, which
+ * is exact at every zoom and takes strokes and non-solid fills.
+ *
+ * Below the threshold the atlas still wins: outlines carry no hinting and no
+ * stem darkening, so body text at 12–16px rendered from them looks *worse*
+ * than a platform rasterizer that puts stems on the pixel grid.
  *
  * ### Metric neutrality (the load-bearing invariant)
  *
  * This tier replaces how a glyph is *painted*, never where it sits. Advances,
- * kerning, line breaking and baselines all keep coming from whichever tier
- * resolved the run — the baked atlas or the canvas face. That is what lets
- * the threshold be a rendering decision: zooming past it swaps glyph geometry
- * with the layout untouched, so text cannot reflow under the user's cursor,
- * and `measureTextBounds` / `textLineBoxes` need to know nothing about
- * outlines at all.
- *
- * The cost is that a face whose real advances disagree with the atlas's
- * inherits the atlas's. For the bundled Inter that is exact (the subset ships
- * from the same source the atlas was baked from), and for a machine font the
- * outline bytes and the canvas metrics come from the same file.
+ * kerning, line breaking, and baselines all keep coming from whichever tier
+ * resolved the run, so zooming past the threshold cannot reflow text. The cost
+ * is that a face whose real advances disagree with the atlas's inherits the
+ * atlas's.
  *
  * ### Availability
  *
- * Everything here degrades rather than blocks. Bytes arrive over `fetch` or
- * `queryLocalFonts` — asynchronous, and in the local case gated behind a
- * permission the user can refuse — so `glyphOutline` answers `null` until a
- * face is loaded and forever if it failed, and the caller falls back down the
- * ladder to SDF. A family must never render *nothing* because the outline
- * tier could not get bytes.
+ * Bytes arrive asynchronously, and in the local case behind a permission the
+ * user can refuse, so `glyphOutline` answers `null` until a face is loaded and
+ * forever if it failed, and the caller falls back to SDF. A family must never
+ * render *nothing* because the outline tier could not get bytes.
  */
 
 /**
  * Where a face's bytes come from. A URL is fetched; a buffer or blob is used
- * as-is; a thunk is called at first use, which is what lets `queryLocalFonts`
- * results be registered eagerly and read lazily — the permission prompt and
- * the (potentially many megabytes of) blob only happen for a family the
- * document actually sets text in.
+ * as-is; a thunk is called at first use.
  */
 type OutlineSource = string | ArrayBuffer | Blob | (() => ArrayBuffer | Blob | Promise<ArrayBuffer | Blob>);
 /** Which face within a family to register outlines for. Defaults to weight
@@ -855,13 +805,12 @@ declare const fontOutlineRegistry: Reflection<OutlineFaceInfo>;
  *
  * Registration is cheap and synchronous: nothing is fetched, and the parser
  * is not even imported, until a frame actually asks for a glyph from this
- * face. Registering a face that is never drawn large costs one map entry.
+ * face.
  *
  * The variant must match exactly what the layout tier resolved — this is
  * deliberately *not* a fallback chain. Painting 400-weight outlines at
- * 700-weight advances, or upright outlines where the shader was going to
- * fake an oblique, looks worse than the SDF it replaced; a miss here falls
- * back down the ladder instead, which is always safe.
+ * 700-weight advances looks worse than the SDF it replaced; a miss falls back
+ * to SDF instead.
  */
 declare function registerFontOutlines(family: string, variant: OutlineVariant, source: OutlineSource, opts?: OutlineFontOptions): void;
 /** Drop a registration. Glyphs already handed out stay valid — they are
@@ -869,9 +818,7 @@ declare function registerFontOutlines(family: string, variant: OutlineVariant, s
 declare function unregisterFontOutlines(family: string, variant?: OutlineVariant): void;
 /**
  * Is an outline face registered for this exact variant? Answers `true` while
- * the bytes are still loading — the question is "could this face serve
- * outlines", which is what a caller deciding whether to *ask* wants; use
- * `outlineStatus` for the narrower "can it right now".
+ * the bytes are still loading; use `outlineStatus` for "can it right now".
  */
 declare function hasFontOutlines(family: string, weight?: number, style?: FontStyle): boolean;
 /** Load state of a registered face; `null` when nothing is registered. */
@@ -881,41 +828,34 @@ declare function outlineStatus(family: string, weight?: number, style?: FontStyl
 declare function listFontOutlines(): readonly OutlineFaceInfo[];
 /**
  * Em-space SVG path data for one glyph of a registered outline face, or `null`
- * when there is nothing to draw.
+ * when this tier cannot serve it — no registration, bytes still loading, load
+ * failed, no such glyph, or a glyph with no contours.
  *
- * Synchronous and non-throwing by design: a face that has not been parsed yet
- * starts loading and answers `null` for now, so a renderer can call this every
- * frame and simply fall through to another text tier until the outline
- * arrives. Results are cached per codepoint.
+ * Synchronous and non-throwing: a face that has not been parsed yet starts
+ * loading and answers `null` for now, so a renderer can call this every frame
+ * and fall through to another text tier until the outline arrives.
  */
 declare function glyphOutline(family: string, weight: number, style: FontStyle, cp: number): string | null;
 /**
  * Metrics for a registered outline face, or `null` when this tier cannot
  * supply them yet — nothing registered, bytes still loading, or a failed load.
  *
- * The face is the *only* metrics source for a family that has no atlas, which
- * is the case this exists for: without it such a family cannot lay out at all.
- * It does not disturb metric neutrality — a family that has an atlas resolves
- * to the atlas long before anything asks here, so registering outlines still
- * cannot move text that was already rendering.
+ * The face is the *only* metrics source for a family that has no atlas. A
+ * family that has an atlas resolves to the atlas before anything asks here,
+ * so registering outlines cannot move text that was already rendering.
  *
- * Starts the load on a first call and answers `null` for now, exactly like
- * `glyphOutline`, so a per-frame caller falls through and picks it up on the
- * frame after the bytes land.
+ * Starts the load on a first call and answers `null` for now, like
+ * `glyphOutline`.
  */
 declare function outlineMetrics(family: string, weight: number, style: FontStyle): OutlineFace | null;
 /**
  * Load a registered face's bytes now and resolve with its settled status:
  * `'ready'`, `'failed'`, or `null` when nothing is registered for the
- * variant. Never rejects — a failed load is a status, the same one
- * `outlineStatus` reports.
- *
- * The per-frame readers start a load and answer `null` until it lands, which
- * suits a renderer and nothing that needs the geometry in one go: converting
- * text to paths awaits this first.
+ * variant. Never rejects — a failed load is a status. For a caller that needs
+ * the geometry in one go, such as converting text to paths.
  */
 declare function loadFontOutlines(family: string, variant?: OutlineVariant): Promise<OutlineStatus | null>;
 /** @internal Test seam — registry and warn-once keys are module state. */
 declare function _resetFontOutlinesForTests(): void;
 
-export { outlineStatus as $, faceMetricsFor as A, type BmFont as B, type CanvasFontEntry as C, DEFAULT_BAKE_BUDGET as D, faceMetricsFromTables as E, type FontStyle as F, type GlyphTextureSink as G, faceMetricsOf as H, fontOutlineRegistry as I, fontPending as J, fontRegistry as K, getDefaultFontFamily as L, getFont as M, getFontFallbackPolicy as N, type OutlineFace as O, glyphOutline as P, hasFontOutlines as Q, type RegisterFontOptions as R, isCanvasFont as S, type TexSource as T, listCanvasFonts as U, listFontOutlines as V, listFontWeights as W, listFonts as X, loadFontOutlines as Y, markAllFontsNotUploaded as Z, outlineMetrics as _, type BmFontChar as a, parseBmFont as a0, registerCanvasFont as a1, registerFont as a2, registerFontOutlines as a3, resetBakeBudget as a4, resolveFontVariant as a5, resolveGlyphFallback as a6, setDefaultFontFamily as a7, setFontFallbackPolicy as a8, syncDynamicPageTexture as a9, textureCacheKey as aa, unregisterCanvasFont as ab, unregisterFontOutlines as ac, verticalMetricsFromTables as ad, warmFonts as ae, __setGlyphRasterizerForTests as af, _getPagesForTests as ag, _resetDomFacesForTests as ah, _resetDynamicFontsForTests as ai, _resetFallbackForTests as aj, _resetFontOutlinesForTests as ak, _resetFontRegistryForTests as al, type BmFontCommon as b, type BmFontInfo as c, type BmFontKerning as d, FIXTURE_FONT as e, type FaceMetricTables as f, type FaceMetrics as g, type FaceRuleMetrics as h, type FaceScriptMetrics as i, type FontEntry as j, type FontFallbackPolicy as k, type FontFamilyFaces as l, type FontRequest as m, type FontVariant as n, type OutlineFaceInfo as o, type OutlineFontOptions as p, type OutlineParser as q, type OutlineSource as r, type OutlineStatus as s, type OutlineVariant as t, type RegisteredFont as u, type ResolveResult as v, cssFontFamily as w, cssFontFamilyLoading as x, dynamicPageTextureId as y, ensureFontTexture as z };
+export { outlineMetrics as $, ensureFontTexture as A, type BmFont as B, type CanvasFontEntry as C, type DynamicFace as D, faceMetricsFor as E, type FontStyle as F, type GlyphTextureSink as G, faceMetricsFromTables as H, faceMetricsOf as I, fontOutlineRegistry as J, fontPending as K, fontRegistry as L, getDefaultFontFamily as M, getFont as N, type OutlineFace as O, getFontFallbackPolicy as P, glyphOutline as Q, type ResolveResult as R, hasFontOutlines as S, type TexSource as T, isCanvasFont as U, listCanvasFonts as V, listFontOutlines as W, listFontWeights as X, listFonts as Y, loadFontOutlines as Z, markAllFontsNotUploaded as _, type BmFontChar as a, outlineStatus as a0, parseBmFont as a1, refreshCanvasFont as a2, registerCanvasFont as a3, registerFont as a4, registerFontOutlines as a5, resolveFontVariant as a6, resolveGlyphFallback as a7, setDefaultFontFamily as a8, setFontFallbackPolicy as a9, syncColorPageTexture as aa, syncDynamicPageTexture as ab, textureCacheKey as ac, unregisterCanvasFont as ad, unregisterFontOutlines as ae, verticalMetricsFromTables as af, warmFonts as ag, __setGlyphRasterizerForTests as ah, _getPagesForTests as ai, _resetDomFacesForTests as aj, _resetDynamicFontsForTests as ak, _resetFallbackForTests as al, _resetFontOutlinesForTests as am, _resetFontRegistryForTests as an, type BmFontCommon as b, type BmFontInfo as c, type BmFontKerning as d, FIXTURE_FONT as e, type FaceMetricTables as f, type FaceMetrics as g, type FaceRuleMetrics as h, type FaceScriptMetrics as i, type FontEntry as j, type FontFallbackPolicy as k, type FontFamilyFaces as l, type FontRequest as m, type FontVariant as n, type OutlineFaceInfo as o, type OutlineFontOptions as p, type OutlineParser as q, type OutlineSource as r, type OutlineStatus as s, type OutlineVariant as t, type RegisterFontOptions as u, type RegisteredFont as v, colorPageTextureId as w, cssFontFamily as x, cssFontFamilyLoading as y, dynamicPageTextureId as z };