@flighthq/bitmapfont 0.3.0-next.906.07cea63 → 0.3.0

package/dist/bitmapFont.d.ts

@@ -1,8 +1,12 @@
-import type { BitmapFont, BitmapFontData, GlyphEntry, GlyphMetrics, TextureAtlas } from '@flighthq/types/contract';
+import type { BitmapFont, BitmapFontData, BitmapFontKerningPair, GlyphEntry, GlyphMetrics, TextureAtlas } from '@flighthq/types/contract';
 export declare function createBitmapFont(data: Readonly<BitmapFontData>): BitmapFont;
 export declare function getBitmapFontGlyph(font: Readonly<BitmapFont>, codepoint: number): GlyphEntry | null;
 export declare function getBitmapFontKerning(font: Readonly<BitmapFont>, left: number, right: number): number;
 export declare function getBitmapFontMetrics(font: Readonly<BitmapFont>): Readonly<GlyphMetrics>;
 export declare function getBitmapFontPage(font: Readonly<BitmapFont>, page?: number): TextureAtlas | null;
 export declare function getBitmapFontPages(font: Readonly<BitmapFont>): readonly TextureAtlas[];
+export declare function hasBitmapFontGlyph(font: Readonly<BitmapFont>, codepoint: number): boolean;
+export declare function packBitmapFontKerningKey(left: number, right: number): number;
+export declare function setBitmapFontGuard(guard: ((reason: string, codepoint: number, page: number) => void) | null): void;
+export declare function unpackBitmapFontKerningKey(key: number, out: BitmapFontKerningPair): BitmapFontKerningPair;
 //# sourceMappingURL=bitmapFont.d.ts.map

package/dist/bitmapFont.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bitmapFont.d.ts","sourceRoot":"","sources":["../src/bitmapFont.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AASnH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,CAAC,cAAc,CAAC,GAAG,UAAU,CAiC3E;AAID,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAEnG;AAID,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpG;AAGD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC,YAAY,CAAC,CAEvF;AAKD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,SAAI,GAAG,YAAY,GAAG,IAAI,CAE3F;AAID,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,SAAS,YAAY,EAAE,CAEtF"}
+{"version":3,"file":"bitmapFont.d.ts","sourceRoot":"","sources":["../src/bitmapFont.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,cAAc,EACd,qBAAqB,EACrB,UAAU,EACV,YAAY,EACZ,YAAY,EACb,MAAM,0BAA0B,CAAC;AASlC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,CAAC,cAAc,CAAC,GAAG,UAAU,CAiC3E;AAID,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAEnG;AAID,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpG;AAGD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC,YAAY,CAAC,CAEvF;AAKD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,SAAI,GAAG,YAAY,GAAG,IAAI,CAE3F;AAID,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,SAAS,YAAY,EAAE,CAEtF;AAMD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAEzF;AAeD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5E;AAKD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAElH;AASD,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,qBAAqB,GAAG,qBAAqB,CAIzG"}

package/dist/bitmapFont.js

@@ -1,5 +1,5 @@
 // Builds an immutable static bitmap font from plain data: the glyph list becomes a
-// `codepoint → GlyphEntry` map, the kerning pairs become a `(left << 16) | right → amount` map, and
+// `codepoint → GlyphEntry` map, the kerning pairs become a `left * 0x110000 + right → amount` map, and
 // the page-indexed atlas list, line metrics, and encoding (default `raster`) are carried as-is. Each
 // glyph's `page` (default 0) indexes `data.pages`; an out-of-range page is clamped to 0 so the glyph
 // is still placed (on the primary page) rather than dropped — a bad page index is a source-data
@@ -15,7 +15,7 @@ export function createBitmapFont(data) {
             bearingX: glyph.bearingX,
             bearingY: glyph.bearingY,
             height: glyph.height,
-            page: page >= 0 && page < pageCount ? page : 0,
+            page: resolveBitmapFontGlyphPage(glyph.codepoint, page, pageCount),
             width: glyph.width,
             x: glyph.x,
             y: glyph.y,
@@ -64,10 +64,58 @@ export function getBitmapFontPage(font, page = 0) {
 export function getBitmapFontPages(font) {
     return font.pages;
 }
-// Packs an adjacent glyph pair into the single-number kerning-map key `(left << 16) | right`. Both
-// codepoints are assumed to lie in the Basic Multilingual Plane (< 0x10000); supplementary-plane
-// pairs are outside this table's addressable range.
-function packBitmapFontKerningKey(left, right) {
-    return (left << 16) | right;
+// Whether the font carries a glyph for `codepoint`. Distinct from `getBitmapFontGlyph(...) !== null`
+// only in intent, but that intent is the point: a caller choosing a fallback font, or filtering a string
+// to what this font can draw, asks a question about coverage and should not have to name the sentinel to
+// get an answer. Cheap enough for a per-character loop — one map lookup, no allocation.
+export function hasBitmapFontGlyph(font, codepoint) {
+    return font.glyphs.has(codepoint);
 }
+// Packs an adjacent glyph pair into the single-number kerning-map key `left * 0x110000 + right`. The
+// inverse is `unpackBitmapFontKerningKey`; the two are one primitive and must move together.
+//
+// Multiplication rather than `(left << 16) | right`, because Unicode does not fit in 16 bits and the
+// shift silently ALIASED rather than failing. JavaScript's bitwise operators truncate to 32 bits, so a
+// supplementary-plane left glyph wrapped into another pair's key: U+10000 followed by 'A' produced the
+// same key as U+0000 followed by 'A', and U+1F600 the same as U+F600. A font with emoji kerning would
+// return the wrong adjustment for an unrelated BMP pair, which is worse than returning none.
+//
+// `0x110000` is the Unicode codepoint space (U+0000..U+10FFFF inclusive), so every pair maps to a
+// distinct key. The largest key is 0x10FFFF * 0x110000 + 0x10FFFF, about 1.24e12 — comfortably inside
+// the 2^53 range where a double holds every integer exactly, so this stays exact arithmetic and never
+// touches the 32-bit bitwise path. A C++ port would use a 64-bit integer key for the same reason.
+export function packBitmapFontKerningKey(left, right) {
+    return left * UNICODE_CODEPOINT_SPACE + right;
+}
+// Installs the caller-facing guard invoked when `createBitmapFont` silently repairs source data. The
+// core carries the seam and never the message: `@flighthq/bitmapfont` has no dependency on
+// `@flighthq/log`, and the wording lives in the separately-importable `enableBitmapFontGuards`.
+export function setBitmapFontGuard(guard) {
+    _guard = guard;
+}
+// Recovers the adjacent glyph pair a kerning key encodes, into `out`. The exact inverse of
+// `packBitmapFontKerningKey`, and the reason a codec walking `font.kerning.keys()` never hand-rolls the
+// arithmetic: a `>>> 16` / `& 0xffff` inverse reads a 0x110000-radix key as a 16-bit one, emitting
+// garbage codepoints for ordinary BMP pairs and truncating every key past 2^32 outright.
+//
+// Division and remainder, not shifts, for the same exactness reason the pack multiplies — the key
+// leaves the 32-bit range well inside the supported codepoint space.
+export function unpackBitmapFontKerningKey(key, out) {
+    out.left = Math.floor(key / UNICODE_CODEPOINT_SPACE);
+    out.right = key % UNICODE_CODEPOINT_SPACE;
+    return out;
+}
+// The page a glyph is placed on. An out-of-range index is clamped to the primary page so the glyph is
+// still drawn — a bad page index is a source-data defect the font should survive rather than a reason to
+// lose a glyph — but the clamp is reported through the guard seam, because a silently relocated glyph
+// renders the wrong pixels and looks like a packing bug rather than a bad font file.
+function resolveBitmapFontGlyphPage(codepoint, page, pageCount) {
+    if (page >= 0 && page < pageCount)
+        return page;
+    _guard?.('page-out-of-range', codepoint, page);
+    return 0;
+}
+// U+0000..U+10FFFF inclusive — the stride that keeps one pair's key out of the next pair's range.
+const UNICODE_CODEPOINT_SPACE = 0x110000;
+let _guard = null;
 //# sourceMappingURL=bitmapFont.js.map

package/dist/bitmapFont.js.map

@@ -1 +1 @@
-{"version":3,"file":"bitmapFont.js","sourceRoot":"","sources":["../src/bitmapFont.ts"],"names":[],"mappings":"AAEA,mFAAmF;AACnF,oGAAoG;AACpG,qGAAqG;AACrG,qGAAqG;AACrG,gGAAgG;AAChG,oGAAoG;AACpG,6EAA6E;AAC7E,MAAM,UAAU,gBAAgB,CAAC,IAA8B;IAC7D,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IACpC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC7C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC;QAC7B,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE;YAC1B,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,IAAI,EAAE,IAAI,IAAI,CAAC,IAAI,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAC9C,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,CAAC,EAAE,KAAK,CAAC,CAAC;YACV,CAAC,EAAE,KAAK,CAAC,CAAC;SACX,CAAC,CAAC;IACL,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAC/B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAChC,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAC5E,CAAC;IACH,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,QAAQ;QACnC,MAAM;QACN,OAAO;QACP,OAAO,EAAE;YACP,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM;YAC3B,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO;YAC7B,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO;SAC9B;QACD,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE;KAC1B,CAAC;AACJ,CAAC;AAED,iGAAiG;AACjG,yGAAyG;AACzG,MAAM,UAAU,kBAAkB,CAAC,IAA0B,EAAE,SAAiB;IAC9E,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC;AAC5C,CAAC;AAED,sGAAsG;AACtG,0CAA0C;AAC1C,MAAM,UAAU,oBAAoB,CAAC,IAA0B,EAAE,IAAY,EAAE,KAAa;IAC1F,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC;AACtE,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,oBAAoB,CAAC,IAA0B;IAC7D,OAAO,IAAI,CAAC,OAAO,CAAC;AACtB,CAAC;AAED,qGAAqG;AACrG,kGAAkG;AAClG,8EAA8E;AAC9E,MAAM,UAAU,iBAAiB,CAAC,IAA0B,EAAE,IAAI,GAAG,CAAC;IACpE,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;AAClC,CAAC;AAED,iGAAiG;AACjG,mFAAmF;AACnF,MAAM,UAAU,kBAAkB,CAAC,IAA0B;IAC3D,OAAO,IAAI,CAAC,KAAK,CAAC;AACpB,CAAC;AAED,mGAAmG;AACnG,iGAAiG;AACjG,oDAAoD;AACpD,SAAS,wBAAwB,CAAC,IAAY,EAAE,KAAa;IAC3D,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,GAAG,KAAK,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"bitmapFont.js","sourceRoot":"","sources":["../src/bitmapFont.ts"],"names":[],"mappings":"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"}

package/dist/bitmapFontFromGlyphAtlas.d.ts

@@ -0,0 +1,19 @@
+import type { BitmapFont, GlyphAtlas } from '@flighthq/types/contract';
+/** Freezes a live `GlyphAtlas` into a static `BitmapFont` — the dynamic cache's contents as a fixed
+ *  font, so a build step can bake what a run actually rasterized and ship it instead of rasterizing
+ *  again at startup.
+ *
+ *  This lives in `@flighthq/bitmapfont` rather than in `@flighthq/glyphatlas` because a conversion
+ *  constructor belongs to the package that owns the PRODUCT, the same way `createImageResourceFromBitmap`
+ *  lives in `@flighthq/image`. Every type is in `@flighthq/types`, so reading a `GlyphAtlas` here costs
+ *  no dependency on the atlas package, and `glyphatlas` gains no edge to `textureatlas` or `texture`.
+ *
+ *  The page is CPU-only: the atlas's own bitmap is already a valid `TextureSource` under the flat
+ *  texture model, so the font's page is a `TextureAtlas` over a bitmap-sourced `Texture` with no GPU
+ *  work and no readback. Whichever backend consumes the font uploads it later through the ordinary
+ *  kind-keyed resolver path, exactly as it would for any other bitmap-sourced texture.
+ *
+ *  The result is a snapshot: later rasterization into the source atlas does not reach the font, and the
+ *  font holds its own reference to the atlas bitmap. */
+export declare function createBitmapFontFromGlyphAtlas(atlas: Readonly<GlyphAtlas>): BitmapFont;
+//# sourceMappingURL=bitmapFontFromGlyphAtlas.d.ts.map

package/dist/bitmapFontFromGlyphAtlas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bitmapFontFromGlyphAtlas.d.ts","sourceRoot":"","sources":["../src/bitmapFontFromGlyphAtlas.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAuB,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAI5F;;;;;;;;;;;;;;;wDAewD;AACxD,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,UAAU,CAyBtF"}

package/dist/bitmapFontFromGlyphAtlas.js

@@ -0,0 +1,46 @@
+import { createTexture } from '@flighthq/texture/contract';
+import { createTextureAtlas } from '@flighthq/textureatlas/contract';
+import { createBitmapFont } from './bitmapFont';
+/** Freezes a live `GlyphAtlas` into a static `BitmapFont` — the dynamic cache's contents as a fixed
+ *  font, so a build step can bake what a run actually rasterized and ship it instead of rasterizing
+ *  again at startup.
+ *
+ *  This lives in `@flighthq/bitmapfont` rather than in `@flighthq/glyphatlas` because a conversion
+ *  constructor belongs to the package that owns the PRODUCT, the same way `createImageResourceFromBitmap`
+ *  lives in `@flighthq/image`. Every type is in `@flighthq/types`, so reading a `GlyphAtlas` here costs
+ *  no dependency on the atlas package, and `glyphatlas` gains no edge to `textureatlas` or `texture`.
+ *
+ *  The page is CPU-only: the atlas's own bitmap is already a valid `TextureSource` under the flat
+ *  texture model, so the font's page is a `TextureAtlas` over a bitmap-sourced `Texture` with no GPU
+ *  work and no readback. Whichever backend consumes the font uploads it later through the ordinary
+ *  kind-keyed resolver path, exactly as it would for any other bitmap-sourced texture.
+ *
+ *  The result is a snapshot: later rasterization into the source atlas does not reach the font, and the
+ *  font holds its own reference to the atlas bitmap. */
+export function createBitmapFontFromGlyphAtlas(atlas) {
+    const runtime = atlas.runtime;
+    const glyphs = [];
+    for (const [codepoint, entry] of runtime.entries) {
+        glyphs.push({
+            advance: entry.advance,
+            bearingX: entry.bearingX,
+            bearingY: entry.bearingY,
+            codepoint,
+            height: entry.height,
+            // The dynamic atlas is a single growing bitmap, so every glyph is on page 0.
+            page: 0,
+            width: entry.width,
+            x: entry.x,
+            y: entry.y,
+        });
+    }
+    // Regions stay empty: a bitmap font addresses its glyphs through its own glyph table, so the page
+    // exists to carry the pixels, not to name sub-rectangles.
+    const page = createTextureAtlas({ texture: createTexture({ source: runtime.bitmap }) });
+    return createBitmapFont({
+        glyphs,
+        metrics: { ...runtime.metrics },
+        pages: [page],
+    });
+}
+//# sourceMappingURL=bitmapFontFromGlyphAtlas.js.map

package/dist/bitmapFontFromGlyphAtlas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bitmapFontFromGlyphAtlas.js","sourceRoot":"","sources":["../src/bitmapFontFromGlyphAtlas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAGrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;;;;;;;;;wDAewD;AACxD,MAAM,UAAU,8BAA8B,CAAC,KAA2B;IACxE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC9B,MAAM,MAAM,GAA0B,EAAE,CAAC;IACzC,KAAK,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACjD,MAAM,CAAC,IAAI,CAAC;YACV,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,SAAS;YACT,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,6EAA6E;YAC7E,IAAI,EAAE,CAAC;YACP,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,CAAC,EAAE,KAAK,CAAC,CAAC;YACV,CAAC,EAAE,KAAK,CAAC,CAAC;SACX,CAAC,CAAC;IACL,CAAC;IACD,kGAAkG;IAClG,0DAA0D;IAC1D,MAAM,IAAI,GAAG,kBAAkB,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;IACxF,OAAO,gBAAgB,CAAC;QACtB,MAAM;QACN,OAAO,EAAE,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE;QAC/B,KAAK,EAAE,CAAC,IAAI,CAAC;KACd,CAAC,CAAC;AACL,CAAC"}

package/dist/bitmapFontGlyphSource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bitmapFontGlyphSource.d.ts","sourceRoot":"","sources":["../src/bitmapFontGlyphSource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAQxE,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,WAAW,CAiBvF"}
+{"version":3,"file":"bitmapFontGlyphSource.d.ts","sourceRoot":"","sources":["../src/bitmapFontGlyphSource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAQxE,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,WAAW,CAkBvF"}

package/dist/bitmapFontGlyphSource.js

@@ -8,7 +8,8 @@ export function createGlyphSourceFromBitmapFont(font) {
         getGlyphAtlasImage(page = 0) {
             // Each page's atlas image, indexed by the glyph's `page`. An out-of-range page (or a page whose
             // atlas carries no image yet) yields null — the renderer skips glyphs it cannot sample.
-            return font.pages[page]?.image ?? null;
+            const texture = font.pages[page]?.texture;
+            return texture?.dimension === '2d' ? texture.source : null;
         },
         getGlyphEntry(codepoint) {
             return getBitmapFontGlyph(font, codepoint);

package/dist/bitmapFontGlyphSource.js.map

@@ -1 +1 @@
-{"version":3,"file":"bitmapFontGlyphSource.js","sourceRoot":"","sources":["../src/bitmapFontGlyphSource.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAE9F,sGAAsG;AACtG,mGAAmG;AACnG,0FAA0F;AAC1F,yGAAyG;AACzG,MAAM,UAAU,+BAA+B,CAAC,IAA0B;IACxE,OAAO;QACL,kBAAkB,CAAC,IAAI,GAAG,CAAC;YACzB,gGAAgG;YAChG,wFAAwF;YACxF,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,IAAI,IAAI,CAAC;QACzC,CAAC;QACD,aAAa,CAAC,SAAS;YACrB,OAAO,kBAAkB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAC7C,CAAC;QACD,eAAe,CAAC,IAAI,EAAE,KAAK;YACzB,OAAO,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;QACjD,CAAC;QACD,eAAe;YACb,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAC;QACpC,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"bitmapFontGlyphSource.js","sourceRoot":"","sources":["../src/bitmapFontGlyphSource.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAE9F,sGAAsG;AACtG,mGAAmG;AACnG,0FAA0F;AAC1F,yGAAyG;AACzG,MAAM,UAAU,+BAA+B,CAAC,IAA0B;IACxE,OAAO;QACL,kBAAkB,CAAC,IAAI,GAAG,CAAC;YACzB,gGAAgG;YAChG,wFAAwF;YACxF,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;YAC1C,OAAO,OAAO,EAAE,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;QAC7D,CAAC;QACD,aAAa,CAAC,SAAS;YACrB,OAAO,kBAAkB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAC7C,CAAC;QACD,eAAe,CAAC,IAAI,EAAE,KAAK;YACzB,OAAO,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;QACjD,CAAC;QACD,eAAe;YACb,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAC;QACpC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/contract.d.ts

@@ -1,3 +1,7 @@
 export * from './bitmapFont';
+export * from './bitmapFontFromGlyphAtlas';
 export * from './bitmapFontGlyphSource';
+export * from './enableBitmapFontGuards';
+export * from './explainBitmapFontGlyph';
+export * from './summarizeBitmapFont';
 //# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC"}

package/dist/contract.js

@@ -1,3 +1,7 @@
 export * from './bitmapFont';
+export * from './bitmapFontFromGlyphAtlas';
 export * from './bitmapFontGlyphSource';
+export * from './enableBitmapFontGuards';
+export * from './explainBitmapFontGlyph';
+export * from './summarizeBitmapFont';
 //# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC"}

package/dist/enableBitmapFontGuards.d.ts

@@ -0,0 +1,18 @@
+/** Uninstalls the guard installed by `enableBitmapFontGuards`. */
+export declare function disableBitmapFontGuards(): void;
+/**
+ * Installs the caller-facing bitmap-font guard (opt-in, dev-only). `createBitmapFont` repairs bad source
+ * data rather than rejecting it, and a repair is invisible from the outside — the font builds, every
+ * lookup succeeds, and the glyph simply samples the wrong page. This warns once, through `@flighthq/log`,
+ * for the repair it makes:
+ *
+ * **A glyph names a page the font does not have.** The glyph is clamped onto the primary page so it is
+ * still drawn, which is the right call for a font that must survive a bad asset — but it samples
+ * whatever happens to sit at those coordinates on page 0. That renders as a garbled glyph or a slice of
+ * a neighbour, which reads as an atlas-packing bug rather than the font-file defect it is.
+ *
+ * Pair with `explainBitmapFontGlyph` for a pull-style answer about one codepoint. Not importing this
+ * module costs production nothing: the messages and the `@flighthq/log` dependency live only here.
+ */
+export declare function enableBitmapFontGuards(): void;
+//# sourceMappingURL=enableBitmapFontGuards.d.ts.map

package/dist/enableBitmapFontGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enableBitmapFontGuards.d.ts","sourceRoot":"","sources":["../src/enableBitmapFontGuards.ts"],"names":[],"mappings":"AAKA,kEAAkE;AAClE,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

package/dist/enableBitmapFontGuards.js

@@ -0,0 +1,39 @@
+import { logOnce } from '@flighthq/log/contract';
+import { LogLevel } from '@flighthq/types/contract';
+import { setBitmapFontGuard } from './bitmapFont';
+/** Uninstalls the guard installed by `enableBitmapFontGuards`. */
+export function disableBitmapFontGuards() {
+    setBitmapFontGuard(null);
+}
+/**
+ * Installs the caller-facing bitmap-font guard (opt-in, dev-only). `createBitmapFont` repairs bad source
+ * data rather than rejecting it, and a repair is invisible from the outside — the font builds, every
+ * lookup succeeds, and the glyph simply samples the wrong page. This warns once, through `@flighthq/log`,
+ * for the repair it makes:
+ *
+ * **A glyph names a page the font does not have.** The glyph is clamped onto the primary page so it is
+ * still drawn, which is the right call for a font that must survive a bad asset — but it samples
+ * whatever happens to sit at those coordinates on page 0. That renders as a garbled glyph or a slice of
+ * a neighbour, which reads as an atlas-packing bug rather than the font-file defect it is.
+ *
+ * Pair with `explainBitmapFontGlyph` for a pull-style answer about one codepoint. Not importing this
+ * module costs production nothing: the messages and the `@flighthq/log` dependency live only here.
+ */
+export function enableBitmapFontGuards() {
+    setBitmapFontGuard(warnOnBitmapFontRepair);
+}
+// Dispatched per reason rather than filtered, matching the glyph-atlas guard: a reason with no branch
+// here logs nothing, which is the safe default when the core grows a repair this module has not been
+// taught to describe. There is one reason today, so the no-match path is unreachable by construction and
+// carries no test — a second reason adds its own branch rather than reusing this one's wording.
+function warnOnBitmapFontRepair(reason, codepoint, page) {
+    if (reason !== 'page-out-of-range')
+        return;
+    const printable = `U+${codepoint.toString(16).toUpperCase().padStart(4, '0')}`;
+    logOnce('bitmapfont:page-out-of-range', LogLevel.Warn, {
+        message: `createBitmapFont: ${printable} names page ${page}, which this font does not have, so it was ` +
+            'placed on page 0 and will sample whatever occupies those coordinates there. The font data is ' +
+            'wrong, not the atlas — check the page index the exporter wrote.',
+    }, 'bitmapfont');
+}
+//# sourceMappingURL=enableBitmapFontGuards.js.map

package/dist/enableBitmapFontGuards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enableBitmapFontGuards.js","sourceRoot":"","sources":["../src/enableBitmapFontGuards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,kEAAkE;AAClE,MAAM,UAAU,uBAAuB;IACrC,kBAAkB,CAAC,IAAI,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,sBAAsB;IACpC,kBAAkB,CAAC,sBAAsB,CAAC,CAAC;AAC7C,CAAC;AAED,sGAAsG;AACtG,qGAAqG;AACrG,yGAAyG;AACzG,gGAAgG;AAChG,SAAS,sBAAsB,CAAC,MAAc,EAAE,SAAiB,EAAE,IAAY;IAC7E,IAAI,MAAM,KAAK,mBAAmB;QAAE,OAAO;IAC3C,MAAM,SAAS,GAAG,KAAK,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;IAC/E,OAAO,CACL,8BAA8B,EAC9B,QAAQ,CAAC,IAAI,EACb;QACE,OAAO,EACL,qBAAqB,SAAS,eAAe,IAAI,6CAA6C;YAC9F,+FAA+F;YAC/F,iEAAiE;KACpE,EACD,YAAY,CACb,CAAC;AACJ,CAAC"}

package/dist/explainBitmapFontGlyph.d.ts

@@ -0,0 +1,14 @@
+import type { BitmapFont, BitmapFontGlyphExplanation } from '@flighthq/types/contract';
+/** Reports why `getBitmapFontGlyph` returned null for `codepoint`, or why the glyph it returned will
+ *  still draw nothing, as plain data.
+ *
+ *  The lookup's null sentinel covers two situations a caller resolves differently — a font that does not
+ *  cover the codepoint wants a fallback font, a font with no page images wants a repaired asset — and a
+ *  third the sentinel cannot report at all, because it is not null: a glyph that exists and is zero-sized.
+ *  A space is the ordinary case of that, and it is the one worth naming, since "the glyph is there and
+ *  draws nothing on purpose" and "the glyph is missing" look identical from a blank screen.
+ *
+ *  A pure read of the font's own maps: no rasterizing, no allocation beyond the returned record, and the
+ *  same answer every time for a given font. Cheap enough to call per missing glyph while diagnosing. */
+export declare function explainBitmapFontGlyph(font: Readonly<BitmapFont>, codepoint: number): BitmapFontGlyphExplanation;
+//# sourceMappingURL=explainBitmapFontGlyph.d.ts.map

package/dist/explainBitmapFontGlyph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainBitmapFontGlyph.d.ts","sourceRoot":"","sources":["../src/explainBitmapFontGlyph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAEvF;;;;;;;;;;wGAUwG;AACxG,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,0BAA0B,CAehH"}

package/dist/explainBitmapFontGlyph.js

@@ -0,0 +1,27 @@
+/** Reports why `getBitmapFontGlyph` returned null for `codepoint`, or why the glyph it returned will
+ *  still draw nothing, as plain data.
+ *
+ *  The lookup's null sentinel covers two situations a caller resolves differently — a font that does not
+ *  cover the codepoint wants a fallback font, a font with no page images wants a repaired asset — and a
+ *  third the sentinel cannot report at all, because it is not null: a glyph that exists and is zero-sized.
+ *  A space is the ordinary case of that, and it is the one worth naming, since "the glyph is there and
+ *  draws nothing on purpose" and "the glyph is missing" look identical from a blank screen.
+ *
+ *  A pure read of the font's own maps: no rasterizing, no allocation beyond the returned record, and the
+ *  same answer every time for a given font. Cheap enough to call per missing glyph while diagnosing. */
+export function explainBitmapFontGlyph(font, codepoint) {
+    const pageCount = font.pages.length;
+    const glyph = font.glyphs.get(codepoint);
+    if (glyph === undefined) {
+        return { glyphHeight: 0, glyphWidth: 0, page: -1, pageCount, reason: 'no-glyph', renderable: false };
+    }
+    const shared = { glyphHeight: glyph.height, glyphWidth: glyph.width, page: glyph.page, pageCount };
+    // Checked before the size, because a font with no pages cannot draw even a well-formed glyph, and that
+    // is the more actionable of the two answers.
+    if (pageCount === 0)
+        return { ...shared, reason: 'no-pages', renderable: false };
+    if (glyph.width <= 0 || glyph.height <= 0)
+        return { ...shared, reason: 'empty-glyph', renderable: false };
+    return { ...shared, reason: 'ok', renderable: true };
+}
+//# sourceMappingURL=explainBitmapFontGlyph.js.map

package/dist/explainBitmapFontGlyph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainBitmapFontGlyph.js","sourceRoot":"","sources":["../src/explainBitmapFontGlyph.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;wGAUwG;AACxG,MAAM,UAAU,sBAAsB,CAAC,IAA0B,EAAE,SAAiB;IAClF,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IACpC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAEzC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,EAAE,WAAW,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IACvG,CAAC;IAED,MAAM,MAAM,GAAG,EAAE,WAAW,EAAE,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC;IAEnG,uGAAuG;IACvG,6CAA6C;IAC7C,IAAI,SAAS,KAAK,CAAC;QAAE,OAAO,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IACjF,IAAI,KAAK,CAAC,KAAK,IAAI,CAAC,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IAC1G,OAAO,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;AACvD,CAAC"}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { createBitmapFont, createGlyphSourceFromBitmapFont, getBitmapFontGlyph, getBitmapFontKerning, getBitmapFontMetrics, getBitmapFontPage, getBitmapFontPages, } from './contract';
+export { createBitmapFont, createBitmapFontFromGlyphAtlas, createGlyphSourceFromBitmapFont, disableBitmapFontGuards, enableBitmapFontGuards, explainBitmapFontGlyph, getBitmapFontGlyph, getBitmapFontKerning, getBitmapFontMetrics, getBitmapFontPage, getBitmapFontPages, hasBitmapFontGlyph, summarizeBitmapFont, } from './contract';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,+BAA+B,EAC/B,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,8BAA8B,EAC9B,+BAA+B,EAC/B,uBAAuB,EACvB,sBAAsB,EACtB,sBAAsB,EACtB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { createBitmapFont, createGlyphSourceFromBitmapFont, getBitmapFontGlyph, getBitmapFontKerning, getBitmapFontMetrics, getBitmapFontPage, getBitmapFontPages, } from './contract';
+export { createBitmapFont, createBitmapFontFromGlyphAtlas, createGlyphSourceFromBitmapFont, disableBitmapFontGuards, enableBitmapFontGuards, explainBitmapFontGlyph, getBitmapFontGlyph, getBitmapFontKerning, getBitmapFontMetrics, getBitmapFontPage, getBitmapFontPages, hasBitmapFontGlyph, summarizeBitmapFont, } from './contract';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,+BAA+B,EAC/B,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,8BAA8B,EAC9B,+BAA+B,EAC/B,uBAAuB,EACvB,sBAAsB,EACtB,sBAAsB,EACtB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/dist/summarizeBitmapFont.d.ts

@@ -0,0 +1,14 @@
+import type { BitmapFont, BitmapFontSummary } from '@flighthq/types/contract';
+/** Summarizes a font's size and coverage as plain data: glyph and kerning-pair counts, page count, the
+ *  CPU-side bytes its page images occupy, and the codepoint range.
+ *
+ *  Fonts are the largest fixed asset in a text-heavy scene and their cost is invisible from the API: a
+ *  CJK-covering font carries hundreds of times the glyphs of a Latin one through exactly the same
+ *  surface. This is what a budget check, a build report, or a debug overlay reads.
+ *
+ *  The byte figure comes from `getTextureAtlasByteSize` rather than from width times height, which
+ *  matters for two reasons: a compressed page costs its payload rather than four bytes per pixel, and a
+ *  page that is unbound or already uploaded-and-released costs nothing. That makes `byteSize` a LOWER
+ *  BOUND on a font mid-load rather than an estimate; `pageCount` is what shows the gap. */
+export declare function summarizeBitmapFont(font: Readonly<BitmapFont>): BitmapFontSummary;
+//# sourceMappingURL=summarizeBitmapFont.d.ts.map

package/dist/summarizeBitmapFont.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarizeBitmapFont.d.ts","sourceRoot":"","sources":["../src/summarizeBitmapFont.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE9E;;;;;;;;;;2FAU2F;AAC3F,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,iBAAiB,CAmBjF"}

package/dist/summarizeBitmapFont.js

@@ -0,0 +1,34 @@
+import { getTextureAtlasByteSize } from '@flighthq/textureatlas/contract';
+/** Summarizes a font's size and coverage as plain data: glyph and kerning-pair counts, page count, the
+ *  CPU-side bytes its page images occupy, and the codepoint range.
+ *
+ *  Fonts are the largest fixed asset in a text-heavy scene and their cost is invisible from the API: a
+ *  CJK-covering font carries hundreds of times the glyphs of a Latin one through exactly the same
+ *  surface. This is what a budget check, a build report, or a debug overlay reads.
+ *
+ *  The byte figure comes from `getTextureAtlasByteSize` rather than from width times height, which
+ *  matters for two reasons: a compressed page costs its payload rather than four bytes per pixel, and a
+ *  page that is unbound or already uploaded-and-released costs nothing. That makes `byteSize` a LOWER
+ *  BOUND on a font mid-load rather than an estimate; `pageCount` is what shows the gap. */
+export function summarizeBitmapFont(font) {
+    let byteSize = 0;
+    for (const page of font.pages)
+        byteSize += getTextureAtlasByteSize(page);
+    let minCodepoint = -1;
+    let maxCodepoint = -1;
+    for (const codepoint of font.glyphs.keys()) {
+        if (minCodepoint < 0 || codepoint < minCodepoint)
+            minCodepoint = codepoint;
+        if (codepoint > maxCodepoint)
+            maxCodepoint = codepoint;
+    }
+    return {
+        byteSize,
+        glyphCount: font.glyphs.size,
+        kerningPairCount: font.kerning.size,
+        maxCodepoint,
+        minCodepoint,
+        pageCount: font.pages.length,
+    };
+}
+//# sourceMappingURL=summarizeBitmapFont.js.map

package/dist/summarizeBitmapFont.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarizeBitmapFont.js","sourceRoot":"","sources":["../src/summarizeBitmapFont.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAG1E;;;;;;;;;;2FAU2F;AAC3F,MAAM,UAAU,mBAAmB,CAAC,IAA0B;IAC5D,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK;QAAE,QAAQ,IAAI,uBAAuB,CAAC,IAAI,CAAC,CAAC;IAEzE,IAAI,YAAY,GAAG,CAAC,CAAC,CAAC;IACtB,IAAI,YAAY,GAAG,CAAC,CAAC,CAAC;IACtB,KAAK,MAAM,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QAC3C,IAAI,YAAY,GAAG,CAAC,IAAI,SAAS,GAAG,YAAY;YAAE,YAAY,GAAG,SAAS,CAAC;QAC3E,IAAI,SAAS,GAAG,YAAY;YAAE,YAAY,GAAG,SAAS,CAAC;IACzD,CAAC;IAED,OAAO;QACL,QAAQ;QACR,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI;QAC5B,gBAAgB,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI;QACnC,YAAY;QACZ,YAAY;QACZ,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM;KAC7B,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,8 @@
 {
   "name": "@flighthq/bitmapfont",
-  "version": "0.3.0-next.906.07cea63",
+  "version": "0.3.0",
+  "author": "Joshua Granick and other contributors",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/flighthq/flight.git",
@@ -36,10 +38,13 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/textureatlas": "0.3.0-next.906.07cea63",
-    "@flighthq/types": "0.3.0-next.906.07cea63"
+    "@flighthq/log": "0.3.0",
+    "@flighthq/texture": "0.3.0",
+    "@flighthq/textureatlas": "0.3.0",
+    "@flighthq/types": "0.3.0"
   },
   "devDependencies": {
+    "@flighthq/glyphatlas": "*",
     "typescript": "^5.3.0"
   },
   "description": "Static bitmap font — an immutable pre-baked atlas + glyph/kerning/metrics tables implementing the GlyphSource seam, the static sibling of the dynamic glyphatlas",

package/src/bitmapFont.test.ts

@@ -9,6 +9,10 @@ import {
   getBitmapFontMetrics,
   getBitmapFontPage,
   getBitmapFontPages,
+  hasBitmapFontGlyph,
+  packBitmapFontKerningKey,
+  setBitmapFontGuard,
+  unpackBitmapFontKerningKey,
 } from './bitmapFont';
 
 describe('createBitmapFont', () => {
@@ -82,6 +86,68 @@ describe('getBitmapFontKerning', () => {
   });
 });
 
+describe('getBitmapFontKerning supplementary planes', () => {
+  // The old key was `(left << 16) | right`, and JavaScript's bitwise operators truncate to 32 bits, so a
+  // supplementary-plane codepoint did not overflow — it WRAPPED, landing on another pair's key. These
+  // are the two aliases that produced, verified arithmetically against the old packing before the fix.
+  const ALIASES = [
+    { name: 'U+10000 aliased U+0000', supplementary: 0x10000, basic: 0x0000 },
+    { name: 'U+1F600 aliased U+F600', supplementary: 0x1f600, basic: 0xf600 },
+  ];
+
+  for (const { name, supplementary, basic } of ALIASES) {
+    it(`keeps a supplementary-plane pair distinct where ${name}`, () => {
+      // Both pairs share a right glyph and differ only in the left, so a colliding key would make the
+      // second write overwrite the first and BOTH lookups would return -9.
+      const font = createBitmapFont({
+        ...sampleFontData(),
+        kerning: [
+          { amount: -4, left: basic, right: 65 },
+          { amount: -9, left: supplementary, right: 65 },
+        ],
+      });
+
+      expect(font.kerning.size).toBe(2);
+      expect(getBitmapFontKerning(font, basic, 65)).toBe(-4);
+      expect(getBitmapFontKerning(font, supplementary, 65)).toBe(-9);
+    });
+  }
+
+  it('keeps a supplementary-plane RIGHT glyph out of the left field', () => {
+    // The right codepoint occupied the low 16 bits, so anything above U+FFFF carried into the left
+    // glyph's field and reported another pair's adjustment.
+    const font = createBitmapFont({
+      ...sampleFontData(),
+      kerning: [
+        { amount: -3, left: 65, right: 0x10041 },
+        { amount: -7, left: 66, right: 0x41 },
+      ],
+    });
+
+    expect(getBitmapFontKerning(font, 65, 0x10041)).toBe(-3);
+    expect(getBitmapFontKerning(font, 66, 0x41)).toBe(-7);
+  });
+
+  it('addresses the whole Unicode range up to its last codepoint', () => {
+    const font = createBitmapFont({
+      ...sampleFontData(),
+      kerning: [{ amount: -5, left: 0x10ffff, right: 0x10ffff }],
+    });
+
+    // The largest key this packing produces; still an exact integer well inside the 2^53 range.
+    expect(getBitmapFontKerning(font, 0x10ffff, 0x10ffff)).toBe(-5);
+    expect(Number.isSafeInteger([...font.kerning.keys()][0])).toBe(true);
+  });
+
+  it('still returns 0 for a pair the font does not carry', () => {
+    // Guards the guard: the tests above would pass just as well against a packing that returned a
+    // distinct key for everything AND matched nothing.
+    const font = createBitmapFont(sampleFontData());
+
+    expect(getBitmapFontKerning(font, 0x10000, 65)).toBe(0);
+  });
+});
+
 describe('getBitmapFontMetrics', () => {
   it('returns the font line metrics', () => {
     const font = createBitmapFont(sampleFontData());
@@ -103,16 +169,6 @@ describe('getBitmapFontPage', () => {
   });
 });
 
-describe('getBitmapFontPages', () => {
-  it('returns the page-indexed atlas list', () => {
-    const page0 = createTextureAtlas();
-    const page1 = createTextureAtlas();
-    const font = createBitmapFont({ ...sampleFontData(), pages: [page0, page1] });
-
-    expect(getBitmapFontPages(font)).toEqual([page0, page1]);
-  });
-});
-
 function sampleFontData(): BitmapFontData {
   return {
     glyphs: [
@@ -125,3 +181,147 @@ function sampleFontData(): BitmapFontData {
     pages: [createTextureAtlas()],
   };
 }
+
+describe('getBitmapFontPages', () => {
+  it('returns the page-indexed atlas list', () => {
+    const page0 = createTextureAtlas();
+    const page1 = createTextureAtlas();
+    const font = createBitmapFont({ ...sampleFontData(), pages: [page0, page1] });
+
+    expect(getBitmapFontPages(font)).toEqual([page0, page1]);
+  });
+});
+
+describe('hasBitmapFontGlyph', () => {
+  it('reports coverage without the caller naming the null sentinel', () => {
+    const font = createBitmapFont(sampleFontData());
+
+    expect(hasBitmapFontGlyph(font, 65)).toBe(true);
+    expect(hasBitmapFontGlyph(font, 0x1f600)).toBe(false);
+  });
+
+  it('agrees with getBitmapFontGlyph on every codepoint it is asked about', () => {
+    const font = createBitmapFont(sampleFontData());
+
+    for (const codepoint of [65, 66, 86, 0, 67, 0x10000]) {
+      expect(hasBitmapFontGlyph(font, codepoint)).toBe(getBitmapFontGlyph(font, codepoint) !== null);
+    }
+  });
+});
+
+describe('packBitmapFontKerningKey', () => {
+  it('gives every distinct pair a distinct key across the full codepoint space', () => {
+    const pairs: readonly (readonly [number, number])[] = [
+      [65, 86],
+      [0, 65],
+      [0x10000, 65],
+      [0x1f600, 0xf600],
+      [0xf600, 0x1f600],
+      [0x10ffff, 0x10ffff],
+    ];
+
+    const keys = pairs.map(([left, right]) => packBitmapFontKerningKey(left, right));
+    expect(new Set(keys).size).toBe(pairs.length);
+  });
+
+  it('stays inside exact-integer range at the largest pair', () => {
+    // 0x10FFFF * 0x110000 + 0x10FFFF ≈ 1.24e12, well under 2^53 — the reason the key is arithmetic
+    // rather than a 32-bit shift.
+    const key = packBitmapFontKerningKey(0x10ffff, 0x10ffff);
+
+    expect(Number.isSafeInteger(key)).toBe(true);
+  });
+});
+
+describe('setBitmapFontGuard', () => {
+  afterEach(() => {
+    setBitmapFontGuard(null);
+  });
+
+  it('reports the repair with the codepoint and the index that was out of range', () => {
+    // The seam, tested apart from the wording. enableBitmapFontGuards owns the message; this owns that
+    // the core calls out at all and hands over enough to identify the glyph — remove the call and the
+    // guard module has nothing to say however well written it is.
+    const calls: [string, number, number][] = [];
+    setBitmapFontGuard((reason, codepoint, page) => calls.push([reason, codepoint, page]));
+
+    createBitmapFont({
+      ...sampleFontData(),
+      glyphs: [{ advance: 9, bearingX: 1, bearingY: 8, codepoint: 0x41, height: 8, page: 7, width: 7, x: 0, y: 0 }],
+    });
+
+    expect(calls).toEqual([['page-out-of-range', 0x41, 7]]);
+  });
+
+  it('stays quiet for a glyph whose page exists', () => {
+    const calls: unknown[] = [];
+    setBitmapFontGuard((...args) => calls.push(args));
+
+    createBitmapFont(sampleFontData());
+
+    expect(calls).toEqual([]);
+  });
+
+  it('uninstalls the guard when passed null', () => {
+    const calls: unknown[] = [];
+    setBitmapFontGuard((...args) => calls.push(args));
+    setBitmapFontGuard(null);
+
+    createBitmapFont({
+      ...sampleFontData(),
+      glyphs: [{ advance: 9, bearingX: 1, bearingY: 8, codepoint: 0x41, height: 8, page: 7, width: 7, x: 0, y: 0 }],
+    });
+
+    expect(calls).toEqual([]);
+  });
+});
+
+describe('unpackBitmapFontKerningKey', () => {
+  it('recovers the pair a key was packed from', () => {
+    // The pairs are the ones a 16-bit inverse (`key >>> 16` / `key & 0xffff`) reads back wrong: an
+    // ordinary BMP pair whose key is not shift-shaped, a supplementary-plane left glyph, and a pair
+    // whose key leaves the 32-bit range the shift operators truncate to.
+    const pairs: readonly (readonly [number, number])[] = [
+      [65, 86],
+      [0, 0],
+      [0x41, 0x10ffff],
+      [0x1f600, 0x41],
+      [0x4e00, 0x4e8c],
+      [0x10ffff, 0x10ffff],
+    ];
+
+    for (const [left, right] of pairs) {
+      const key = packBitmapFontKerningKey(left, right);
+      expect(unpackBitmapFontKerningKey(key, { left: 0, right: 0 })).toEqual({ left, right });
+    }
+  });
+
+  it('recovers a pair whose key exceeds 2^32', () => {
+    const key = packBitmapFontKerningKey(0x1f600, 0x41);
+    expect(key).toBeGreaterThan(0x1_0000_0000);
+
+    const pair = unpackBitmapFontKerningKey(key, { left: 0, right: 0 });
+
+    expect(pair).toEqual({ left: 0x1f600, right: 0x41 });
+    // What the truncating inverse this replaced would have produced from the same key.
+    expect(pair.left).not.toBe(key >>> 16);
+  });
+
+  it('writes into the out object the caller supplied and returns it', () => {
+    const out = { left: -1, right: -1 };
+
+    const returned = unpackBitmapFontKerningKey(packBitmapFontKerningKey(0x10000, 0x41), out);
+
+    expect(returned).toBe(out);
+    expect(out).toEqual({ left: 0x10000, right: 0x41 });
+  });
+
+  it('reuses one out object across keys without carrying state between calls', () => {
+    const out = { left: 0, right: 0 };
+
+    unpackBitmapFontKerningKey(packBitmapFontKerningKey(0x10ffff, 0x10ffff), out);
+    unpackBitmapFontKerningKey(packBitmapFontKerningKey(0, 0), out);
+
+    expect(out).toEqual({ left: 0, right: 0 });
+  });
+});

package/src/bitmapFontFromGlyphAtlas.test.ts

@@ -0,0 +1,81 @@
+import { createGlyphAtlas, getGlyphAtlasEntry, setGlyphRasterizerBackend } from '@flighthq/glyphatlas/contract';
+import type { GlyphRasterizerBackend } from '@flighthq/types/contract';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { getBitmapFontGlyph, getBitmapFontMetrics } from './bitmapFont';
+import { createBitmapFontFromGlyphAtlas } from './bitmapFontFromGlyphAtlas';
+
+function backendProducing(width: number, height: number): GlyphRasterizerBackend {
+  return {
+    measureMetrics: () => ({ ascent: 12, descent: 3, lineGap: 1 }),
+    rasterize: () => ({
+      advance: width,
+      bearingX: 1,
+      bearingY: 2,
+      height,
+      pixels: new Uint8ClampedArray(width * height * 4),
+      width,
+    }),
+  };
+}
+
+describe('createBitmapFontFromGlyphAtlas', () => {
+  afterEach(() => setGlyphRasterizerBackend(null));
+
+  function bakedFromTwoGlyphs() {
+    setGlyphRasterizerBackend(backendProducing(8, 8));
+    const atlas = createGlyphAtlas({ fontFamily: 'mock', fontSize: 16, height: 64, width: 64 });
+    getGlyphAtlasEntry(atlas, 65);
+    getGlyphAtlasEntry(atlas, 66);
+    return { atlas, font: createBitmapFontFromGlyphAtlas(atlas) };
+  }
+
+  it('carries every cached glyph across with its rect and pen data', () => {
+    const { atlas, font } = bakedFromTwoGlyphs();
+
+    const source = getGlyphAtlasEntry(atlas, 65)!;
+    const baked = getBitmapFontGlyph(font, 65)!;
+
+    expect(baked).not.toBeNull();
+    expect(baked.x).toBe(source.x);
+    expect(baked.y).toBe(source.y);
+    expect(baked.width).toBe(source.width);
+    expect(baked.advance).toBe(source.advance);
+    expect(baked.bearingY).toBe(source.bearingY);
+    expect(getBitmapFontGlyph(font, 66)).not.toBeNull();
+  });
+
+  it('carries the atlas metrics rather than re-deriving them', () => {
+    const { font } = bakedFromTwoGlyphs();
+    expect(getBitmapFontMetrics(font)).toEqual({ ascent: 12, descent: 3, lineGap: 1 });
+  });
+
+  // The page is CPU-only: the atlas bitmap is already a valid texture source under the flat model, so
+  // baking needs no GPU work and no readback.
+  it('builds a single page whose texture is sourced from the atlas bitmap', () => {
+    const { atlas, font } = bakedFromTwoGlyphs();
+
+    expect(font.pages).toHaveLength(1);
+    expect(font.pages[0]!.texture!.source).toBe(atlas.runtime.bitmap);
+  });
+
+  // A bake is a snapshot. Rasterizing more glyphs into the source atlas afterwards must not reach the
+  // font, or "bake" would just be another view of a live cache.
+  it('does not gain glyphs rasterized into the atlas after the bake', () => {
+    const { atlas, font } = bakedFromTwoGlyphs();
+
+    getGlyphAtlasEntry(atlas, 67);
+
+    expect(getBitmapFontGlyph(font, 67)).toBeNull();
+  });
+
+  it('bakes an empty atlas to a font with no glyphs rather than failing', () => {
+    setGlyphRasterizerBackend(backendProducing(8, 8));
+    const atlas = createGlyphAtlas({ fontFamily: 'mock', fontSize: 16, height: 64, width: 64 });
+
+    const font = createBitmapFontFromGlyphAtlas(atlas);
+
+    expect(getBitmapFontGlyph(font, 65)).toBeNull();
+    expect(font.pages).toHaveLength(1);
+  });
+});

package/src/bitmapFontGlyphSource.test.ts

@@ -1,5 +1,5 @@
-import { createTextureAtlas } from '@flighthq/textureatlas/contract';
-import type { BitmapFontData, ImageResource } from '@flighthq/types/contract';
+import { createTextureAtlas, createTextureAtlasFromImageResource } from '@flighthq/textureatlas/contract';
+import type { BitmapFontData, Image } from '@flighthq/types/contract';
 import { describe, expect, it } from 'vitest';
 
 import { createBitmapFont, getBitmapFontGlyph } from './bitmapFont';
@@ -19,8 +19,8 @@ describe('createGlyphSourceFromBitmapFont', () => {
   });
 
   it('pairs page 0 with the font atlas image and has no other page', () => {
-    const image = {} as ImageResource;
-    const font = createBitmapFont({ ...sampleFontData(), pages: [createTextureAtlas({ image })] });
+    const image = {} as Image;
+    const font = createBitmapFont({ ...sampleFontData(), pages: [createTextureAtlasFromImageResource(image)] });
     const source = createGlyphSourceFromBitmapFont(font);
 
     expect(source.getGlyphAtlasImage(0)).toBe(image);
@@ -29,11 +29,11 @@ describe('createGlyphSourceFromBitmapFont', () => {
   });
 
   it('resolves each page image of a multi-page font', () => {
-    const image0 = {} as ImageResource;
-    const image1 = {} as ImageResource;
+    const image0 = {} as Image;
+    const image1 = {} as Image;
     const font = createBitmapFont({
       ...sampleFontData(),
-      pages: [createTextureAtlas({ image: image0 }), createTextureAtlas({ image: image1 })],
+      pages: [createTextureAtlasFromImageResource(image0), createTextureAtlasFromImageResource(image1)],
     });
     const source = createGlyphSourceFromBitmapFont(font);
 

package/src/enableBitmapFontGuards.test.ts

@@ -0,0 +1,76 @@
+import { setLogSink } from '@flighthq/log/contract';
+import { createTextureAtlas } from '@flighthq/textureatlas/contract';
+import type { BitmapFontData, LogEntry } from '@flighthq/types/contract';
+
+import { createBitmapFont } from './bitmapFont';
+import { disableBitmapFontGuards, enableBitmapFontGuards } from './enableBitmapFontGuards';
+
+let entries: LogEntry[];
+
+beforeEach(() => {
+  entries = [];
+  setLogSink((entry) => entries.push(entry));
+});
+
+afterEach(() => {
+  disableBitmapFontGuards();
+  setLogSink(null);
+});
+
+function messages(): string {
+  return entries.map((e) => String((e.data as { message?: unknown } | undefined)?.message ?? '')).join('\n');
+}
+
+function fontData(page: number, pages = 1): BitmapFontData {
+  return {
+    glyphs: [{ advance: 9, bearingX: 1, bearingY: 8, codepoint: 65, height: 8, page, width: 7, x: 0, y: 0 }],
+    metrics: { ascent: 8, descent: 2, lineGap: 1 },
+    pages: Array.from({ length: pages }, () => createTextureAtlas()),
+  };
+}
+
+describe('disableBitmapFontGuards', () => {
+  it('stops the warning a previously-installed guard would emit', () => {
+    enableBitmapFontGuards();
+    disableBitmapFontGuards();
+
+    createBitmapFont(fontData(4));
+
+    expect(entries).toEqual([]);
+  });
+});
+
+describe('enableBitmapFontGuards', () => {
+  it('warns which glyph and index are wrong, and that the font data is at fault', () => {
+    // ONE test for the whole message, deliberately. logOnce suppresses a key for the life of the
+    // PROCESS, so a second test asserting a second phrase would observe nothing and pass vacuously —
+    // the key is a single-use observation, so every assertion about it belongs in one place.
+    enableBitmapFontGuards();
+
+    createBitmapFont(fontData(4));
+
+    // The codepoint and the bad index, because the value of the warning is telling the reader which
+    // glyph and which index to look for in the font file.
+    expect(messages()).toContain('U+0041');
+    expect(messages()).toContain('page 4');
+    // And who is at fault: the failure renders as a garbled glyph, which reads as an atlas-packing bug.
+    // Naming the real culprit is why this warning exists rather than the clamp being left silent.
+    expect(messages()).toContain('font data is wrong, not the atlas');
+  });
+
+  it('stays silent for a glyph whose page exists', () => {
+    // Guards the guard: every assertion above would pass just as well against a guard that fired
+    // unconditionally, which would make the warning noise on every well-formed font.
+    enableBitmapFontGuards();
+
+    createBitmapFont(fontData(1, 2));
+
+    expect(entries).toEqual([]);
+  });
+
+  it('stays silent when no guard is installed at all', () => {
+    createBitmapFont(fontData(4));
+
+    expect(entries).toEqual([]);
+  });
+});

package/src/explainBitmapFontGlyph.test.ts

@@ -0,0 +1,73 @@
+import { createTextureAtlas } from '@flighthq/textureatlas/contract';
+import type { BitmapFontData } from '@flighthq/types/contract';
+
+import { createBitmapFont } from './bitmapFont';
+import { explainBitmapFontGlyph } from './explainBitmapFontGlyph';
+
+function fontData(over: Partial<BitmapFontData> = {}): BitmapFontData {
+  return {
+    glyphs: [
+      { advance: 9, bearingX: 1, bearingY: 8, codepoint: 65, height: 8, width: 7, x: 0, y: 0 },
+      { advance: 4, bearingX: 0, bearingY: 0, codepoint: 32, height: 0, width: 0, x: 0, y: 0 },
+    ],
+    metrics: { ascent: 8, descent: 2, lineGap: 1 },
+    pages: [createTextureAtlas()],
+    ...over,
+  };
+}
+
+describe('explainBitmapFontGlyph', () => {
+  it('reports ok for a glyph that will draw', () => {
+    const font = createBitmapFont(fontData());
+
+    expect(explainBitmapFontGlyph(font, 65)).toEqual({
+      glyphHeight: 8,
+      glyphWidth: 7,
+      page: 0,
+      pageCount: 1,
+      reason: 'ok',
+      renderable: true,
+    });
+  });
+
+  it('distinguishes a codepoint the font does not cover', () => {
+    const font = createBitmapFont(fontData());
+
+    expect(explainBitmapFontGlyph(font, 0x1f600)).toEqual({
+      glyphHeight: 0,
+      glyphWidth: 0,
+      // -1 rather than 0: there is no glyph, so there is no page it resolved to, and reporting 0 would
+      // read as "page zero" to a caller checking which page to upload.
+      page: -1,
+      pageCount: 1,
+      reason: 'no-glyph',
+      renderable: false,
+    });
+  });
+
+  it('distinguishes a zero-sized glyph the font does carry', () => {
+    // A space. The lookup returns a glyph, so the null sentinel cannot report this at all — which is the
+    // reason it is worth a distinct reason: drew-nothing-on-purpose and drew-nothing-by-mistake look
+    // identical from a blank screen.
+    const font = createBitmapFont(fontData());
+
+    const explanation = explainBitmapFontGlyph(font, 32);
+    expect(explanation.reason).toBe('empty-glyph');
+    expect(explanation.renderable).toBe(false);
+  });
+
+  it('reports a font with no page images ahead of the glyph size', () => {
+    // Both faults are present on this glyph — no pages AND it is well-formed — and no-pages is the more
+    // actionable answer, so the order is deliberate rather than incidental.
+    const font = createBitmapFont(fontData({ pages: [] }));
+
+    expect(explainBitmapFontGlyph(font, 65).reason).toBe('no-pages');
+    expect(explainBitmapFontGlyph(font, 65).pageCount).toBe(0);
+  });
+
+  it('reports no-pages rather than empty-glyph when both apply', () => {
+    const font = createBitmapFont(fontData({ pages: [] }));
+
+    expect(explainBitmapFontGlyph(font, 32).reason).toBe('no-pages');
+  });
+});

package/src/summarizeBitmapFont.test.ts

@@ -0,0 +1,86 @@
+import { createTexture } from '@flighthq/texture/contract';
+import { createTextureAtlas } from '@flighthq/textureatlas/contract';
+import type { Bitmap, BitmapFontData, TextureAtlas } from '@flighthq/types/contract';
+import { BitmapTextureSourceKind } from '@flighthq/types/contract';
+
+import { createBitmapFont } from './bitmapFont';
+import { summarizeBitmapFont } from './summarizeBitmapFont';
+
+// A page whose CPU-side image data is `bytes` long. The summary reports the byte footprint of the
+// actual data rather than width times height, so the fixture supplies data rather than dimensions.
+function pageOfBytes(bytes: number): TextureAtlas {
+  const image = {
+    alphaType: 'straight',
+    gamut: 'srgb',
+    data: new Uint8ClampedArray(bytes),
+    format: 'rgba8unorm',
+    height: 1,
+    kind: BitmapTextureSourceKind,
+    version: 0,
+    width: bytes / 4,
+  } as unknown as Bitmap;
+  return createTextureAtlas({ texture: createTexture({ dimension: '2d', source: image }) });
+}
+
+function fontData(over: Partial<BitmapFontData> = {}): BitmapFontData {
+  return {
+    glyphs: [
+      { advance: 9, bearingX: 1, bearingY: 8, codepoint: 65, height: 8, width: 7, x: 0, y: 0 },
+      { advance: 9, bearingX: 1, bearingY: 8, codepoint: 0x1f600, height: 8, width: 7, x: 8, y: 0 },
+    ],
+    kerning: [{ amount: -2, left: 65, right: 0x1f600 }],
+    metrics: { ascent: 8, descent: 2, lineGap: 1 },
+    pages: [pageOfBytes(64 * 32 * 4)],
+    ...over,
+  };
+}
+
+describe('summarizeBitmapFont', () => {
+  it('counts glyphs, kerning pairs, pages, pixels and bytes', () => {
+    const font = createBitmapFont(fontData());
+
+    expect(summarizeBitmapFont(font)).toEqual({
+      byteSize: 64 * 32 * 4,
+      glyphCount: 2,
+      kerningPairCount: 1,
+      maxCodepoint: 0x1f600,
+      minCodepoint: 65,
+      pageCount: 1,
+    });
+  });
+
+  it('sums every page rather than reporting only the first', () => {
+    const font = createBitmapFont(fontData({ pages: [pageOfBytes(2048), pageOfBytes(512)] }));
+
+    const summary = summarizeBitmapFont(font);
+    expect(summary.pageCount).toBe(2);
+    expect(summary.byteSize).toBe(2560);
+  });
+
+  it('treats an unresolved page as contributing nothing, making the size a lower bound', () => {
+    // A page whose texture has not loaded yet. Counting it as zero is what makes the figure a floor
+    // rather than an estimate, and the page still shows in pageCount so the gap is visible.
+    const font = createBitmapFont(fontData({ pages: [pageOfBytes(2048), createTextureAtlas()] }));
+
+    const summary = summarizeBitmapFont(font);
+    expect(summary.pageCount).toBe(2);
+    expect(summary.byteSize).toBe(2048);
+  });
+
+  it('reports -1 for both ends of the codepoint range of an empty font', () => {
+    // 0 would be a lie: U+0000 is a real codepoint, so a caller cannot tell an empty font from one
+    // carrying only NUL.
+    const font = createBitmapFont(fontData({ glyphs: [], kerning: [] }));
+
+    const summary = summarizeBitmapFont(font);
+    expect(summary.minCodepoint).toBe(-1);
+    expect(summary.maxCodepoint).toBe(-1);
+    expect(summary.glyphCount).toBe(0);
+  });
+
+  it('reports the range across supplementary-plane glyphs', () => {
+    const font = createBitmapFont(fontData());
+
+    expect(summarizeBitmapFont(font).maxCodepoint).toBe(0x1f600);
+  });
+});