@weasel-js/font 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 orochi235
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @weasel-js/font
+
+MSDF font atlases, glyph metrics, and runtime glyph rasterization for
+`@weasel-js/core`.
+
+A Tier A leaf: core depends on this package, never the reverse. It owns the
+font registry — the one piece of module-level state whose duplication renders
+no glyphs at all.
+
+## What's here
+
+| Module | Role |
+| --- | --- |
+| `FontAtlas` | BMFont metrics parsing |
+| `registerFont` | The registry, variant resolution, texture upload |
+| `dynamic/` | Runtime canvas-SDF rasterization for glyphs with no baked atlas |
+| `textureSink` | The `GlyphTextureSink` seam — the renderer injects GL texture upload, so this package never imports one |
+| `textSdf` | Shader source for the SDF text program |
+
+## Fallback
+
+An unregistered family renders in the default family with a one-time warning:
+
+```ts
+setFontFallbackPolicy('substitute');  // default — render in the default family
+setFontFallbackPolicy('canvas');      // rasterize the real typeface at runtime
+setFontFallbackPolicy('none');        // hard miss: render nothing (pre-0.7 behavior)
+
+setDefaultFontFamily('Inter');        // defaults to the first registered family
+```
+
+Substitution changes advance widths, so measurement and wrap differ from the
+requested font. `ResolveResult.substituted` reports it structurally so a UI can
+surface the swap rather than leaving it to the console.
+
+## Generating an atlas
+
+`npm run gen:font` (source in `scripts/gen-font.ts`).

package/dist/index.d.ts

@@ -0,0 +1,395 @@
+/**
+ * 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;
+    }[];
+}
+/** 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;
+/** 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;
+/** Subscribe to deferred-bake completion (fires after each flush batch).
+ *  `<SceneCanvas>` subscribes and requests a redraw, mirroring
+ *  `subscribeImageReady`. Returns an unsubscribe. */
+declare function subscribeGlyphReady(cb: () => void): () => 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;
+
+/**
+ * GLSL ES 3.0 sources for the built-in MSDF text shader.
+ *
+ * Vertex inputs (interleaved, stride 20 bytes = 5 × float):
+ *   a_position   vec2   screen-space x,y of the glyph quad vertex
+ *   a_uv         vec2   atlas UV (0..1)
+ *   a_baselineY  float  line baseline Y in screen space (for synth-italic skew)
+ *
+ * Uniforms:
+ *   u_proj         mat3        screen → clip projection
+ *   u_model        mat3        cumulative group transform
+ *   u_atlas        sampler2D   the MSDF atlas texture (bound to TEXTURE0)
+ *   u_color        vec4        text color (straight RGBA)
+ *   u_alpha        float       group alpha multiplier
+ *   u_colorMatrix  mat4        color transform applied to u_color before alpha modulation
+ *   u_colorBias    vec4        bias added after the matrix (identity = zero bias)
+ *
+ * Output: PREMULTIPLIED alpha — `vec4(color.rgb * a, a)` per conventions §2.
+ * Blend func: ONE / ONE_MINUS_SRC_ALPHA.
+ *
+ * MSDF channel layout: msdf-bmfont-xml outputs R,G,B channels as independent
+ * signed-distance fields covering different edge directions. The true SDF
+ * value is the median of R,G,B; this recovers sharp outlines while averaging
+ * out single-channel aliasing artifacts.
+ *
+ * Antialiasing (`aaWidth`, both shaders): the smoothstep band must be one
+ * *screen* pixel wide, so it is derived per-fragment from `fwidth(sdfVal)` —
+ * the rate the field changes between adjacent fragments. That single quantity
+ * already folds in font size, zoom, and DPR: minify the glyph and the field
+ * changes faster, so the band widens in field units to stay one pixel on
+ * screen; magnify it and the band narrows.
+ *
+ * A *constant* band cannot be correct at more than one scale, and this shader
+ * used one (0.05) until 2026-07-29. At 16px text the band collapsed to well
+ * under a pixel and glyph edges quantized to hard stair-steps; at display
+ * sizes the same constant read mushy. `fwidth` is core in GLSL ES 3.00, so
+ * no extension guard is needed. The `max()` floor keeps a degenerate
+ * derivative (flat field, or a driver returning 0) from producing a
+ * 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";
+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
+ * (DynamicGlyphAtlas R8 pages): the R channel IS the distance field, so no
+ * median. Threshold semantics (0.5 edge, u_synthBold shift) match the MSDF
+ * shader because the bake encodes the edge at ~128.
+ *
+ * Accepted trade: corner rounding away from the bake size, mildest near it.
+ * `glyphRasterizer.ts` carries the measurements and the reason neither a
+ * 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";
+declare const TEXT_SDF_UNIFORMS: readonly ["u_proj", "u_model", "u_atlas", "u_color", "u_alpha", "u_synthBold", "u_synthItalic", "u_colorMatrix", "u_colorBias"];
+declare const TEXT_SDF_ATTRIBUTES: readonly ["a_position", "a_uv", "a_baselineY"];
+
+export { type BmFont, type BmFontChar, type BmFontCommon, type BmFontInfo, type BmFontKerning, DEFAULT_BAKE_BUDGET, FIXTURE_FONT, type FontEntry, type FontFallbackPolicy, type FontVariant, type GlyphTextureSink, 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, _resetFontRegistryForTests, dynamicPageTextureId, ensureFontTexture, getDefaultFontFamily, getFont, getFontFallbackPolicy, isCanvasFont, listFonts, markAllFontsNotUploaded, parseBmFont, registerCanvasFont, registerFont, resetBakeBudget, resolveFontVariant, resolveGlyphFallback, setDefaultFontFamily, setFontFallbackPolicy, subscribeGlyphReady, syncDynamicPageTexture, textureCacheKey, unregisterCanvasFont };