@weasel-js/font 1.0.2 → 1.0.4

package/dist/index.d.ts

@@ -1,361 +1,5 @@
-/**
- * BmFont JSON types and parser for the MSDF atlas format produced by
- * msdf-bmfont-xml. The parser builds accelerator maps (charMap, kerningMap)
- * for O(1) glyph and kerning lookup during layout.
- */
-interface BmFontInfo {
-    face: string;
-    size: number;
-}
-interface BmFontCommon {
-    lineHeight: number;
-    base: number;
-    scaleW: number;
-    scaleH: number;
-}
-interface BmFontChar {
-    id: number;
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    xoffset: number;
-    yoffset: number;
-    xadvance: number;
-    page: number;
-}
-interface BmFontKerning {
-    first: number;
-    second: number;
-    amount: number;
-}
-interface BmFont {
-    info: BmFontInfo;
-    common: BmFontCommon;
-    chars: BmFontChar[];
-    kernings: BmFontKerning[];
-    charMap: Map<number, BmFontChar>;
-    kerningMap: Map<number, Map<number, number>>;
-}
-/** Two-glyph fixture for unit tests. */
-declare const FIXTURE_FONT: {
-    info: {
-        face: string;
-        size: number;
-    };
-    common: {
-        lineHeight: number;
-        base: number;
-        scaleW: number;
-        scaleH: number;
-    };
-    chars: {
-        id: number;
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-        xoffset: number;
-        yoffset: number;
-        xadvance: number;
-        page: number;
-    }[];
-    kernings: {
-        first: number;
-        second: number;
-        amount: number;
-    }[];
-};
-declare function parseBmFont(raw: unknown): BmFont;
-
-/**
- * The only thing the glyph tier needs from a GL texture cache. Core's
- * `GLTextureCache` satisfies this structurally — there is no adapter and no
- * registration step, because the type *is* the seam.
- *
- * Declared here rather than imported so this package has zero reach-back into
- * core. If core's cache ever drops one of these methods, the failure surfaces
- * as a type error at the call site in `renderer/draw.ts`, which is where it
- * belongs.
- */
-/** Anything WebGL can upload as a texture. */
-type TexSource = HTMLImageElement | ImageBitmap | ImageData | HTMLCanvasElement;
-interface GlyphTextureSink {
-    has(id: string): boolean;
-    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;
-}
-
-interface FaceMetrics {
-    ascent: number;
-    descent: number;
-}
-interface RasterizedGlyph {
-    width: number;
-    height: number;
-    alpha: Uint8ClampedArray;
-    left: number;
-    top: number;
-    advance: number;
-}
-interface GlyphRasterizer {
-    faceMetrics(family: string, weight: number, style: 'normal' | 'italic'): FaceMetrics;
-    rasterize(family: string, weight: number, style: 'normal' | 'italic', codepoint: number): RasterizedGlyph;
-}
-
-/**
- * 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).
- *
- * Baked MSDF atlases always win: this tier only serves families registered
- * via `registerCanvasFont` that have no baked entry (see resolveFontVariant).
- *
- * Faces expose a BmFont-shaped `font` whose charMap grows as glyphs are
- * requested, so `layoutRuns` consumes them through the same code path as
- * 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).
- */
-
-declare const DEFAULT_BAKE_BUDGET = 16;
-interface DynamicFace {
-    family: string;
-    weight: number;
-    style: 'normal' | 'italic';
-    /** BmFont-shaped view consumed by layoutRuns; charMap grows lazily. */
-    font: BmFont;
-    /** 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;
-    }[];
-}
-/** One family served by the dynamic canvas-SDF tier. See `listCanvasFonts`. */
-interface CanvasFontEntry {
-    family: string;
-    /** `'explicit'` — a `registerCanvasFont` call; `'auto'` — the `'canvas'`
-     *  fallback policy enrolled it on a miss, and the enrollment lapses if
-     *  that policy changes. */
-    enrollment: 'explicit' | 'auto';
-}
-/** Mark `family` as canvas-sourced: when no baked atlas covers it,
- *  resolveFontVariant serves it from this dynamic atlas. */
-declare function registerCanvasFont(family: string): void;
-/**
- * Will `family` be served by the dynamic canvas-SDF tier *right now*?
- *
- * Service, not membership — the answer depends on the fallback policy in
- * force and can change without any enrollment call:
- *   - explicitly enrolled via `registerCanvasFont` → `true` under every
- *     policy; a consumer naming a family outranks the policy.
- *   - auto-enrolled by the `'canvas'` policy → `true` only while that policy
- *     is still in force. The enrollment lapses rather than being discarded,
- *     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.
- *
- * `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). */
-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;
-/** @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;
-
-/**
- * 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.
- */
-
-interface FontEntry {
-    font: BmFont;
-    bitmap: ImageBitmap;
-}
-interface FontVariant {
-    weight?: number;
-    style?: 'normal' | 'italic';
-}
-type FontStyle = 'normal' | 'italic';
-/** Test helper. Do not call from product code. */
-declare function _resetFontRegistryForTests(): void;
-/** Exact lookup — does NOT walk the fallback chain. Use `resolveFontVariant` for that. */
-declare function getFont(family: string, weight?: number, style?: FontStyle): FontEntry | null;
-interface RegisteredFont {
-    family: string;
-    variants: readonly {
-        weight: number;
-        style: FontStyle;
-    }[];
-}
-/**
- * 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.
- */
-declare function listFonts(): readonly RegisteredFont[];
-declare function registerFont(family: string, variant: FontVariant, metricsUrl: string, atlasUrl: string): Promise<void>;
-/**
- * Ensure the atlas for `(family, weight, style)` is uploaded to
- * `textureCache`. Cache key is `${family}|${weight}|${style}` so each
- * variant occupies its own texture slot.
- */
-declare function ensureFontTexture(family: string, weight: number, style: FontStyle, textureCache: GlyphTextureSink): boolean;
-/** The texture cache key used by `ensureFontTexture` for a given variant. */
-declare function textureCacheKey(family: string, weight: number, style: FontStyle): string;
-/** Kept as a no-op for context-restore call sites; per-cache dedup handles it now. */
-declare function markAllFontsNotUploaded(): void;
-interface ResolveResult {
-    entry: FontEntry | null;
-    /**
-     * The (family, weight, style) triple that was actually matched. May differ
-     * from the requested values when the resolver walked the fallback chain —
-     * 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.
-     *
-     * The synthetic flags describe the gap between requested and resolved for
-     * shader-side compensation. When `entry` is null, these mirror the
-     * requested values.
-     */
-    resolved: {
-        family: string;
-        weight: number;
-        style: FontStyle;
-    };
-    synthetic: {
-        bold: boolean;
-        italic: boolean;
-    };
-    /** Which tier resolved: a baked MSDF atlas, or the runtime canvas-SDF
-     *  dynamic atlas. Misses report 'atlas' (the default tier). */
-    source: 'atlas' | 'canvas';
-    /** Set only when source === 'canvas': the dynamic face whose BmFont-shaped
-     *  `font` layoutRuns consumes in place of `entry.font`. */
-    dynamicFace?: DynamicFace;
-    /**
-     * 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?: {
-        requested: string;
-        resolved: string;
-    };
-}
-/**
- * Resolve a `(family, weight, style)` request to a registered font entry,
- * walking the fallback chain when an exact match isn't available. Returns
- * synthetic flags describing the gap between requested and resolved so the
- * renderer can apply SDF-thicken / vertex-skew fakes.
- */
-declare function resolveFontVariant(family: string, weight: number, style: FontStyle): ResolveResult;
-/**
- * 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.
- *
- * 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.
- */
-declare function resolveGlyphFallback(family: string, weight: number, style: FontStyle): ResolveResult | null;
-
-/**
- * Cross-family fallback policy. The per-family chain in `resolveFontVariant`
- * (weight → style → synthetic) has always been rich; what was missing is what
- * happens when the family itself was never registered. That case used to
- * render nothing at all, which is the single most common cause of "my text is
- * invisible".
- */
-/**
- * What happens when a requested family has no baked atlas:
- *   - `'substitute'` — render with the default family (see
- *     `setDefaultFontFamily`), reporting the swap on `ResolveResult.substituted`.
- *   - `'canvas'` — auto-enroll the family with the dynamic canvas-SDF
- *     rasterizer. The consumer gets the *real* typeface if the browser has it,
- *     at canvas-SDF quality rather than baked-MSDF quality.
- *   - `'none'` — hard miss; the run renders nothing.
- */
-type FontFallbackPolicy = 'substitute' | 'canvas' | 'none';
-declare function setFontFallbackPolicy(next: FontFallbackPolicy): void;
-declare function getFontFallbackPolicy(): FontFallbackPolicy;
-/** Explicit default family for `'substitute'`. When unset, the first
- *  registered family wins — the right answer for the common case of an app
- *  that registers exactly one. */
-declare function setDefaultFontFamily(family: string): void;
-declare function getDefaultFontFamily(): string | null;
-/** Test helper. Do not call from product code. */
-declare function _resetFallbackForTests(): void;
+import { O as OutlineFontStyle } from './test-seams-DLNsXb8P.js';
+export { B as BmFont, a as BmFontChar, b as BmFontCommon, c as BmFontInfo, d as BmFontKerning, C as CanvasFontEntry, D as DEFAULT_BAKE_BUDGET, F as FIXTURE_FONT, e as FontEntry, f as FontFallbackPolicy, g as FontVariant, G as GlyphTextureSink, h as OutlineFace, i as OutlineFontOptions, j as OutlineParser, k as OutlineSource, l as OutlineStatus, m as OutlineVariant, R as RegisteredFont, n as ResolveResult, T as TexSource, o as dynamicPageTextureId, p as ensureFontTexture, q as getDefaultFontFamily, r as getFont, s as getFontFallbackPolicy, t as glyphOutline, u as hasFontOutlines, v as isCanvasFont, w as listCanvasFonts, x as listFontOutlines, y as listFonts, z as markAllFontsNotUploaded, A as outlineStatus, E as parseBmFont, H as registerCanvasFont, I as registerFont, J as registerFontOutlines, K as resetBakeBudget, L as resolveFontVariant, M as resolveGlyphFallback, N as setDefaultFontFamily, P as setFontFallbackPolicy, Q as syncDynamicPageTexture, S as textureCacheKey, U as unregisterCanvasFont, V as unregisterFontOutlines } from './test-seams-DLNsXb8P.js';
 
 /**
  * "A glyph the renderer asked for can now paint" — the redraw signal shared
@@ -397,161 +41,6 @@ declare function glyphGeneration(): number;
  */
 declare function subscribeGlyphReady(cb: () => void): () => 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.
- *
- * 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.
- */
-/** Weight/style pair identifying one face within a family. */
-type OutlineFontStyle = 'normal' | 'italic';
-interface OutlineFace {
-    /** Font design units per em. Reported for diagnostics; `glyphD` has already
-     *  divided by it, so callers never need to. */
-    unitsPerEm: number;
-    /**
-     * 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.
-     */
-    glyphD(cp: number): string | null;
-}
-/**
- * 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.
- */
-type OutlineParser = (bytes: ArrayBuffer) => OutlineFace | Promise<OutlineFace>;
-
-/**
- * The outline tier's registry: which faces have real font bytes behind them,
- * and what a given glyph looks like.
- *
- * ### 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
- * (`../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.
- *
- * ### 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.
- *
- * ### 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.
- */
-
-/**
- * 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.
- */
-type OutlineSource = string | ArrayBuffer | Blob | (() => ArrayBuffer | Blob | Promise<ArrayBuffer | Blob>);
-interface OutlineVariant {
-    weight?: number;
-    style?: OutlineFontStyle;
-}
-interface OutlineFontOptions {
-    /** Override the default opentype.js parser. Mostly a test seam; also the
-     *  hook for a consumer who already has a font parser in their bundle. */
-    parser?: OutlineParser;
-}
-/** Load state of one registered face. */
-type OutlineStatus = 'idle' | 'loading' | 'ready' | 'failed';
-/**
- * Register font file bytes for one face, so text set in it can render from
- * outlines above the size threshold.
- *
- * 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.
- *
- * 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.
- */
-declare function registerFontOutlines(family: string, variant: OutlineVariant, source: OutlineSource, opts?: OutlineFontOptions): void;
-/** Drop a registration. Glyphs already handed out stay valid — they are
- *  plain path data — but nothing further resolves from this face. */
-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".
- */
-declare function hasFontOutlines(family: string, weight?: number, style?: OutlineFontStyle): boolean;
-/** Load state of a registered face; `null` when nothing is registered. */
-declare function outlineStatus(family: string, weight?: number, style?: OutlineFontStyle): OutlineStatus | null;
-/** Every registered outline face and its load state — the enumeration a
- *  debug overlay or font picker needs, mirroring `listFonts`. */
-declare function listFontOutlines(): readonly {
-    family: string;
-    weight: number;
-    style: OutlineFontStyle;
-    status: OutlineStatus;
-}[];
-declare function glyphOutline(family: string, weight: number, style: OutlineFontStyle, cp: number): string | null;
-/** @internal Test seam — registry and warn-once keys are module state. */
-declare function _resetFontOutlinesForTests(): void;
-
 /**
  * Local Font Access → outline registrations.
  *
@@ -591,6 +80,7 @@ declare function parseFontStyle(style: string): {
     weight: number;
     style: OutlineFontStyle;
 };
+/** Options for `registerLocalFontOutlines`. */
 interface LocalFontOutlinesOptions {
     /**
      * Restrict registration to these families. Defaults to every installed
@@ -600,6 +90,7 @@ interface LocalFontOutlinesOptions {
      */
     families?: readonly string[];
 }
+/** What `registerLocalFontOutlines` registered. */
 interface LocalFontOutlinesResult {
     /** Families that now have at least one outline face, in menu order. */
     families: readonly string[];
@@ -658,6 +149,8 @@ declare function enableLocalFontOutlines(opts?: LocalFontOutlinesOptions): Promi
  * zero-width band, which would be the aliased behavior all over again.
  */
 declare const TEXT_VERT_SRC = "#version 300 es\nin vec2 a_position;\nin vec2 a_uv;\nin float a_baselineY;\nuniform mat3 u_proj;\nuniform mat3 u_model;\nuniform float u_synthItalic;\nout vec2 v_uv;\nvoid main() {\n  // Synthetic italic: shift x by (a_baselineY - a_position.y) * tan(angle).\n  // Above-baseline vertices (lower y in screen coords) lean further right.\n  vec2 skewed = vec2(\n    a_position.x + (a_baselineY - a_position.y) * tan(u_synthItalic),\n    a_position.y\n  );\n  vec3 screen = u_model * vec3(skewed, 1.0);\n  vec3 clip   = u_proj  * vec3(screen.xy, 1.0);\n  gl_Position = vec4(clip.xy, 0.0, 1.0);\n  v_uv = a_uv;\n}\n";
+/** Fragment shader for the MSDF text program. Samples the atlas, applies the
+ *  color transform, and emits premultiplied alpha. */
 declare const TEXT_FRAG_SRC = "#version 300 es\nprecision highp float;\nin vec2 v_uv;\nuniform sampler2D u_atlas;\nuniform vec4 u_color;\nuniform float u_alpha;\nuniform float u_synthBold;\nuniform mat4 u_colorMatrix;\nuniform vec4 u_colorBias;\nout vec4 outColor;\n\nfloat median(float r, float g, float b) {\n  return max(min(r, g), min(max(r, g), b));\n}\n\nvoid main() {\n  vec3 sdf = texture(u_atlas, v_uv).rgb;\n  float sdfVal = median(sdf.r, sdf.g, sdf.b);\n  // Screen-space AA band \u2014 see the file header. Half of fwidth spans ~1px.\n  float aaW = max(0.5 * fwidth(sdfVal), 0.0005);\n  // u_synthBold shifts the SDF threshold to thicken strokes when the\n  // resolver fell back from a missing bold variant to the regular atlas.\n  float threshold = 0.5 - u_synthBold;\n  float msdfAlpha = smoothstep(threshold - aaW, threshold + aaW, sdfVal);\n  vec4 src = vec4(u_color.rgb, u_color.a);\n  vec4 mapped = clamp(u_colorMatrix * src + u_colorBias, 0.0, 1.0);\n  float a = mapped.a * msdfAlpha * u_alpha;\n  outColor = vec4(mapped.rgb * a, a);\n}\n";
 /**
  * Single-channel sibling of TEXT_FRAG_SRC for runtime canvas-SDF glyphs
@@ -670,7 +163,11 @@ declare const TEXT_FRAG_SRC = "#version 300 es\nprecision highp float;\nin vec2
  * larger bake nor extra taps would improve the small-text end.
  */
 declare const TEXT_FRAG_R8_SRC = "#version 300 es\nprecision highp float;\nin vec2 v_uv;\nuniform sampler2D u_atlas;\nuniform vec4 u_color;\nuniform float u_alpha;\nuniform float u_synthBold;\nuniform mat4 u_colorMatrix;\nuniform vec4 u_colorBias;\nout vec4 outColor;\n\nvoid main() {\n  float sdfVal = texture(u_atlas, v_uv).r;\n  // Screen-space AA band \u2014 see the file header. Half of fwidth spans ~1px.\n  float aaW = max(0.5 * fwidth(sdfVal), 0.0005);\n  float threshold = 0.5 - u_synthBold;\n  float sdfAlpha = smoothstep(threshold - aaW, threshold + aaW, sdfVal);\n  vec4 src = vec4(u_color.rgb, u_color.a);\n  vec4 mapped = clamp(u_colorMatrix * src + u_colorBias, 0.0, 1.0);\n  float a = mapped.a * sdfAlpha * u_alpha;\n  outColor = vec4(mapped.rgb * a, a);\n}\n";
+/** Uniform names the text program declares, for the caller that looks up and
+ *  caches their locations. */
 declare const TEXT_SDF_UNIFORMS: readonly ["u_proj", "u_model", "u_atlas", "u_color", "u_alpha", "u_synthBold", "u_synthItalic", "u_colorMatrix", "u_colorBias"];
+/** Vertex attribute names the text program declares, in the order the
+ *  interleaved buffer packs them. */
 declare const TEXT_SDF_ATTRIBUTES: readonly ["a_position", "a_uv", "a_baselineY"];
 
-export { type BmFont, type BmFontChar, type BmFontCommon, type BmFontInfo, type BmFontKerning, type CanvasFontEntry, DEFAULT_BAKE_BUDGET, FIXTURE_FONT, type FontEntry, type FontFallbackPolicy, type FontVariant, type GlyphTextureSink, type LocalFontOutlinesOptions, type LocalFontOutlinesResult, type OutlineFace, type OutlineFontOptions, type OutlineFontStyle, type OutlineParser, type OutlineSource, type OutlineStatus, type OutlineVariant, type RegisteredFont, type ResolveResult, TEXT_FRAG_R8_SRC, TEXT_FRAG_SRC, TEXT_SDF_ATTRIBUTES, TEXT_SDF_UNIFORMS, TEXT_VERT_SRC, type TexSource, __setGlyphRasterizerForTests, _getPagesForTests, _resetDynamicFontsForTests, _resetFallbackForTests, _resetFontOutlinesForTests, _resetFontRegistryForTests, canQueryLocalFonts, dynamicPageTextureId, enableLocalFontOutlines, ensureFontTexture, getDefaultFontFamily, getFont, getFontFallbackPolicy, glyphGeneration, glyphOutline, hasFontOutlines, isCanvasFont, listCanvasFonts, listFontOutlines, listFonts, markAllFontsNotUploaded, outlineStatus, parseBmFont, parseFontStyle, registerCanvasFont, registerFont, registerFontOutlines, resetBakeBudget, resolveFontVariant, resolveGlyphFallback, setDefaultFontFamily, setFontFallbackPolicy, subscribeGlyphReady, syncDynamicPageTexture, textureCacheKey, unregisterCanvasFont, unregisterFontOutlines };
+export { type LocalFontOutlinesOptions, type LocalFontOutlinesResult, OutlineFontStyle, TEXT_FRAG_R8_SRC, TEXT_FRAG_SRC, TEXT_SDF_ATTRIBUTES, TEXT_SDF_UNIFORMS, TEXT_VERT_SRC, canQueryLocalFonts, enableLocalFontOutlines, glyphGeneration, parseFontStyle, subscribeGlyphReady };