@flighthq/glyphatlas 0.1.0

package/dist/glyphAtlas.d.ts

@@ -0,0 +1,6 @@
+import type { GlyphAtlas, GlyphAtlasOptions, GlyphMetrics, Surface } from '@flighthq/types';
+export declare function createGlyphAtlas(options: Readonly<GlyphAtlasOptions>): GlyphAtlas;
+export declare function deriveGlyphMetricsFromFontSize(fontSize: number): GlyphMetrics;
+export declare function disposeGlyphAtlas(atlas: GlyphAtlas): void;
+export declare function getGlyphAtlasSurface(atlas: Readonly<GlyphAtlas>): Surface;
+//# sourceMappingURL=glyphAtlas.d.ts.map

package/dist/glyphAtlas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glyphAtlas.d.ts","sourceRoot":"","sources":["../src/glyphAtlas.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAO5F,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,QAAQ,CAAC,iBAAiB,CAAC,GAAG,UAAU,CAwBjF;AAKD,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAM7E;AAOD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAQzD;AAID,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,OAAO,CAEzE"}

package/dist/glyphAtlas.js

@@ -0,0 +1,61 @@
+import { createSurface } from '@flighthq/surface';
+// Allocates a dynamic glyph atlas: an empty `width x height` atlas surface, an empty codepoint→entry
+// cache, and a fresh incremental shelf packer. Glyphs are added lazily by `getGlyphAtlasEntry`;
+// nothing is rasterized here. `padding` defaults to 1px of gutter between glyphs and from the edges;
+// `maxGlyphs` (default 0 = unbounded, only the atlas area caps it) bounds the live cache for LRU
+// eviction. Line metrics are derived from `fontSize` for now (see `deriveGlyphMetricsFromFontSize`).
+export function createGlyphAtlas(options) {
+    const padding = options.padding ?? 1;
+    return {
+        runtime: {
+            bitmaps: new Map(),
+            dirty: false,
+            dirtyMaxX: 0,
+            dirtyMaxY: 0,
+            dirtyMinX: 0,
+            dirtyMinY: 0,
+            entries: new Map(),
+            lru: [],
+            maxGlyphs: options.maxGlyphs ?? 0,
+            metrics: deriveGlyphMetricsFromFontSize(options.fontSize),
+            packBottom: padding,
+            padding,
+            rasterizeOptions: {
+                fontFamily: options.fontFamily,
+                fontSize: options.fontSize,
+            },
+            shelves: [],
+            surface: createSurface(options.width, options.height),
+        },
+    };
+}
+// Estimates line metrics from a pixel font size when a real font-metrics source is not wired up. The
+// 0.8/0.2 ascent/descent split and zero line gap are a coarse Latin-typical default; a text
+// renderer that needs true metrics should read them from the shaping layer once that seam exists.
+export function deriveGlyphMetricsFromFontSize(fontSize) {
+    return {
+        ascent: fontSize * 0.8,
+        descent: fontSize * 0.2,
+        lineGap: 0,
+    };
+}
+// Drops the cache, the retained source bitmaps, the LRU order, and the packer so the atlas becomes
+// an empty, inert shell and its sizable retained memory (the per-glyph bitmap copies) becomes
+// GC-eligible. The surface holds only CPU-managed pixel data (no GPU/native handle) and is released
+// to GC when the atlas is dropped, so this is `dispose*`, not `destroy*`; a renderer that uploaded
+// the surface to a GPU texture frees that texture through its own render state.
+export function disposeGlyphAtlas(atlas) {
+    const runtime = atlas.runtime;
+    runtime.entries.clear();
+    runtime.bitmaps.clear();
+    runtime.lru.length = 0;
+    runtime.shelves.length = 0;
+    runtime.packBottom = runtime.padding;
+    runtime.dirty = false;
+}
+// The atlas's backing surface — the pixels a renderer uploads to a GPU texture. Use
+// `getGlyphAtlasDirtyRegion` to upload only the changed sub-rect.
+export function getGlyphAtlasSurface(atlas) {
+    return atlas.runtime.surface;
+}
+//# sourceMappingURL=glyphAtlas.js.map

package/dist/glyphAtlas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glyphAtlas.js","sourceRoot":"","sources":["../src/glyphAtlas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGlD,qGAAqG;AACrG,gGAAgG;AAChG,qGAAqG;AACrG,iGAAiG;AACjG,qGAAqG;AACrG,MAAM,UAAU,gBAAgB,CAAC,OAAoC;IACnE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC;IACrC,OAAO;QACL,OAAO,EAAE;YACP,OAAO,EAAE,IAAI,GAAG,EAAE;YAClB,KAAK,EAAE,KAAK;YACZ,SAAS,EAAE,CAAC;YACZ,SAAS,EAAE,CAAC;YACZ,SAAS,EAAE,CAAC;YACZ,SAAS,EAAE,CAAC;YACZ,OAAO,EAAE,IAAI,GAAG,EAAE;YAClB,GAAG,EAAE,EAAE;YACP,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,CAAC;YACjC,OAAO,EAAE,8BAA8B,CAAC,OAAO,CAAC,QAAQ,CAAC;YACzD,UAAU,EAAE,OAAO;YACnB,OAAO;YACP,gBAAgB,EAAE;gBAChB,UAAU,EAAE,OAAO,CAAC,UAAU;gBAC9B,QAAQ,EAAE,OAAO,CAAC,QAAQ;aAC3B;YACD,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC;SACtD;KACF,CAAC;AACJ,CAAC;AAED,qGAAqG;AACrG,4FAA4F;AAC5F,kGAAkG;AAClG,MAAM,UAAU,8BAA8B,CAAC,QAAgB;IAC7D,OAAO;QACL,MAAM,EAAE,QAAQ,GAAG,GAAG;QACtB,OAAO,EAAE,QAAQ,GAAG,GAAG;QACvB,OAAO,EAAE,CAAC;KACX,CAAC;AACJ,CAAC;AAED,mGAAmG;AACnG,8FAA8F;AAC9F,oGAAoG;AACpG,mGAAmG;AACnG,gFAAgF;AAChF,MAAM,UAAU,iBAAiB,CAAC,KAAiB;IACjD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC9B,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACxB,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACxB,OAAO,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;IACvB,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;IAC3B,OAAO,CAAC,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;IACrC,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC;AACxB,CAAC;AAED,oFAAoF;AACpF,kEAAkE;AAClE,MAAM,UAAU,oBAAoB,CAAC,KAA2B;IAC9D,OAAO,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;AAC/B,CAAC"}

package/dist/glyphAtlasDirty.d.ts

@@ -0,0 +1,4 @@
+import type { GlyphAtlas, Rectangle } from '@flighthq/types';
+export declare function clearGlyphAtlasDirty(atlas: Readonly<GlyphAtlas>): void;
+export declare function getGlyphAtlasDirtyRegion(atlas: Readonly<GlyphAtlas>): Rectangle | null;
+//# sourceMappingURL=glyphAtlasDirty.d.ts.map

package/dist/glyphAtlasDirty.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glyphAtlasDirty.d.ts","sourceRoot":"","sources":["../src/glyphAtlasDirty.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAI7D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,IAAI,CAEtE;AAKD,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,SAAS,GAAG,IAAI,CAStF"}

package/dist/glyphAtlasDirty.js

@@ -0,0 +1,16 @@
+import { createRectangle } from '@flighthq/geometry';
+// Resets the atlas's dirty region to empty. Call it right after uploading the current dirty rect to
+// the GPU texture so the next glyph addition starts a fresh region.
+export function clearGlyphAtlasDirty(atlas) {
+    atlas.runtime.dirty = false;
+}
+// Returns the union of every atlas rectangle written since the last `clearGlyphAtlasDirty` (a fresh
+// `Rectangle`), or null when nothing has changed. A renderer uploads only this sub-rect of the atlas
+// surface to its GPU texture, then clears it.
+export function getGlyphAtlasDirtyRegion(atlas) {
+    const runtime = atlas.runtime;
+    if (!runtime.dirty)
+        return null;
+    return createRectangle(runtime.dirtyMinX, runtime.dirtyMinY, runtime.dirtyMaxX - runtime.dirtyMinX, runtime.dirtyMaxY - runtime.dirtyMinY);
+}
+//# sourceMappingURL=glyphAtlasDirty.js.map

package/dist/glyphAtlasDirty.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glyphAtlasDirty.js","sourceRoot":"","sources":["../src/glyphAtlasDirty.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGrD,oGAAoG;AACpG,oEAAoE;AACpE,MAAM,UAAU,oBAAoB,CAAC,KAA2B;IAC9D,KAAK,CAAC,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC;AAC9B,CAAC;AAED,oGAAoG;AACpG,qGAAqG;AACrG,8CAA8C;AAC9C,MAAM,UAAU,wBAAwB,CAAC,KAA2B;IAClE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC9B,IAAI,CAAC,OAAO,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAChC,OAAO,eAAe,CACpB,OAAO,CAAC,SAAS,EACjB,OAAO,CAAC,SAAS,EACjB,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,EACrC,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CACtC,CAAC;AACJ,CAAC"}

package/dist/glyphAtlasEntry.d.ts

@@ -0,0 +1,3 @@
+import type { GlyphAtlas, GlyphEntry } from '@flighthq/types';
+export declare function getGlyphAtlasEntry(atlas: Readonly<GlyphAtlas>, codepoint: number): GlyphEntry | null;
+//# sourceMappingURL=glyphAtlasEntry.d.ts.map

package/dist/glyphAtlasEntry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glyphAtlasEntry.d.ts","sourceRoot":"","sources":["../src/glyphAtlasEntry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAqB,UAAU,EAAyB,MAAM,iBAAiB,CAAC;AASxG,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAsDpG"}

package/dist/glyphAtlasEntry.js

@@ -0,0 +1,171 @@
+import { createSurfaceRegion, writeSurfacePixels } from '@flighthq/surface';
+import { getGlyphRasterizerBackend } from './glyphRasterizerBackend';
+// Returns the cached entry for `codepoint`, or ensures it first on a miss: rasterize via the active
+// backend, pack the bitmap into the atlas (incremental shelf placement; on exhaustion, evict the
+// least-recently-used glyphs and repack), blit its pixels into the atlas surface, record the dirty
+// rect, and cache the entry. Returns null when the glyph cannot be produced — no rasterizer output,
+// or a single glyph larger than the whole atlas. This is the dynamic `GlyphSource.getGlyphEntry`.
+export function getGlyphAtlasEntry(atlas, codepoint) {
+    const runtime = atlas.runtime;
+    const existing = runtime.entries.get(codepoint);
+    if (existing !== undefined) {
+        _touchGlyphLru(runtime, codepoint);
+        return existing;
+    }
+    const bitmap = getGlyphRasterizerBackend().rasterize(codepoint, runtime.rasterizeOptions);
+    if (bitmap === null)
+        return null;
+    // A glyph larger than the usable atlas area can never be placed, however much is evicted.
+    const padding = runtime.padding;
+    const usableWidth = runtime.surface.width - 2 * padding;
+    const usableHeight = runtime.surface.height - 2 * padding;
+    if (bitmap.width > usableWidth || bitmap.height > usableHeight)
+        return null;
+    // Evicting for the glyph-count budget frees logical cache slots; the freed atlas space is reclaimed
+    // lazily by the first repack that placement forces below.
+    let needsRepack = false;
+    while (runtime.maxGlyphs > 0 && runtime.entries.size >= runtime.maxGlyphs) {
+        if (!_evictLeastRecentlyUsedGlyph(runtime))
+            break;
+        needsRepack = true;
+    }
+    let placement = _placeGlyphOnShelf(runtime, bitmap.width, bitmap.height);
+    if (placement === null && needsRepack) {
+        _repackGlyphAtlas(runtime);
+        placement = _placeGlyphOnShelf(runtime, bitmap.width, bitmap.height);
+    }
+    while (placement === null) {
+        // The usable-bounds check above guarantees the glyph fits in an empty atlas, so this sentinel is
+        // defensive: an empty cache that still cannot place means the glyph exceeds the atlas.
+        if (runtime.entries.size === 0)
+            return null;
+        _evictLeastRecentlyUsedGlyph(runtime);
+        _repackGlyphAtlas(runtime);
+        placement = _placeGlyphOnShelf(runtime, bitmap.width, bitmap.height);
+    }
+    const entry = {
+        advance: bitmap.advance,
+        bearingX: bitmap.bearingX,
+        bearingY: bitmap.bearingY,
+        height: bitmap.height,
+        page: 0, // The dynamic atlas is one growing surface — a single page.
+        width: bitmap.width,
+        x: placement.x,
+        y: placement.y,
+    };
+    runtime.entries.set(codepoint, entry);
+    runtime.bitmaps.set(codepoint, bitmap);
+    runtime.lru.push(codepoint);
+    _blitGlyphIntoAtlasSurface(runtime, entry, bitmap);
+    return entry;
+}
+// Writes the glyph's RGBA pixels into the atlas surface at the entry's rect and unions that rect into
+// the dirty region for incremental upload.
+function _blitGlyphIntoAtlasSurface(runtime, entry, bitmap) {
+    const region = createSurfaceRegion(runtime.surface, entry.x, entry.y, entry.width, entry.height);
+    writeSurfacePixels(region, bitmap.pixels);
+    _markGlyphAtlasDirtyRect(runtime, entry.x, entry.y, entry.width, entry.height);
+}
+// Evicts the least-recently-used glyph (front of the LRU list), removing its entry and retained
+// bitmap. Its atlas space is not reclaimed until the next repack. Returns false when nothing is
+// cached.
+function _evictLeastRecentlyUsedGlyph(runtime) {
+    const codepoint = runtime.lru.shift();
+    if (codepoint === undefined)
+        return false;
+    runtime.entries.delete(codepoint);
+    runtime.bitmaps.delete(codepoint);
+    return true;
+}
+// Unions the rectangle (`x`,`y`,`width`,`height`) into the atlas's dirty region, starting a fresh
+// region when none is pending.
+function _markGlyphAtlasDirtyRect(runtime, x, y, width, height) {
+    const maxX = x + width;
+    const maxY = y + height;
+    if (!runtime.dirty) {
+        runtime.dirty = true;
+        runtime.dirtyMinX = x;
+        runtime.dirtyMinY = y;
+        runtime.dirtyMaxX = maxX;
+        runtime.dirtyMaxY = maxY;
+        return;
+    }
+    runtime.dirtyMinX = Math.min(runtime.dirtyMinX, x);
+    runtime.dirtyMinY = Math.min(runtime.dirtyMinY, y);
+    runtime.dirtyMaxX = Math.max(runtime.dirtyMaxX, maxX);
+    runtime.dirtyMaxY = Math.max(runtime.dirtyMaxY, maxY);
+}
+// Incrementally places a `width x height` glyph with the shelf packer: it reuses the shortest shelf
+// tall enough with horizontal room (best-height-fit), else opens a new shelf at the current bottom.
+// Padding is honored as a gutter to the left/right of each glyph and from the atlas edges. Returns
+// the top-left placement, or null when neither an existing shelf nor a new one has room.
+function _placeGlyphOnShelf(runtime, width, height) {
+    const padding = runtime.padding;
+    const surface = runtime.surface;
+    const rightLimit = surface.width - padding;
+    let best = null;
+    let bestSlack = Number.POSITIVE_INFINITY;
+    for (const shelf of runtime.shelves) {
+        if (shelf.height < height)
+            continue;
+        if (shelf.cursorX + width > rightLimit)
+            continue;
+        const slack = shelf.height - height;
+        if (slack < bestSlack) {
+            best = shelf;
+            bestSlack = slack;
+        }
+    }
+    if (best !== null) {
+        const x = best.cursorX;
+        best.cursorX = x + width + padding;
+        return { x, y: best.y };
+    }
+    const y = runtime.packBottom;
+    if (y + height > surface.height - padding)
+        return null;
+    if (padding + width > rightLimit)
+        return null;
+    runtime.shelves.push({ cursorX: padding + width + padding, height, y });
+    runtime.packBottom = y + height + padding;
+    return { x: padding, y };
+}
+// Rebuilds the atlas from its surviving cached glyphs to reclaim the space freed by eviction: it
+// clears the surface and shelf state, re-places every survivor (tallest first, for tight shelf
+// packing), re-blits its pixels, and updates its entry's position in place. A survivor that no
+// longer fits is dropped. The whole atlas is marked dirty since glyphs have moved.
+function _repackGlyphAtlas(runtime) {
+    runtime.shelves.length = 0;
+    runtime.packBottom = runtime.padding;
+    runtime.surface.data.fill(0);
+    const codepoints = [...runtime.entries.keys()].sort((a, b) => {
+        const heightDelta = runtime.entries.get(b).height - runtime.entries.get(a).height;
+        return heightDelta !== 0 ? heightDelta : a - b;
+    });
+    for (const codepoint of codepoints) {
+        const entry = runtime.entries.get(codepoint);
+        const bitmap = runtime.bitmaps.get(codepoint);
+        const placement = _placeGlyphOnShelf(runtime, bitmap.width, bitmap.height);
+        if (placement === null) {
+            runtime.entries.delete(codepoint);
+            runtime.bitmaps.delete(codepoint);
+            const lruIndex = runtime.lru.indexOf(codepoint);
+            if (lruIndex !== -1)
+                runtime.lru.splice(lruIndex, 1);
+            continue;
+        }
+        entry.x = placement.x;
+        entry.y = placement.y;
+        const region = createSurfaceRegion(runtime.surface, entry.x, entry.y, entry.width, entry.height);
+        writeSurfacePixels(region, bitmap.pixels);
+    }
+    _markGlyphAtlasDirtyRect(runtime, 0, 0, runtime.surface.width, runtime.surface.height);
+}
+// Moves `codepoint` to the most-recently-used end of the LRU list so eviction takes the oldest first.
+function _touchGlyphLru(runtime, codepoint) {
+    const index = runtime.lru.indexOf(codepoint);
+    if (index !== -1)
+        runtime.lru.splice(index, 1);
+    runtime.lru.push(codepoint);
+}
+//# sourceMappingURL=glyphAtlasEntry.js.map

package/dist/glyphAtlasEntry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glyphAtlasEntry.js","sourceRoot":"","sources":["../src/glyphAtlasEntry.ts"],"names":[],"mappings":"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"}

package/dist/glyphAtlasMetrics.d.ts

@@ -0,0 +1,4 @@
+import type { GlyphAtlas, GlyphMetrics } from '@flighthq/types';
+export declare function getGlyphAtlasKerning(_atlas: Readonly<GlyphAtlas>, _left: number, _right: number): number;
+export declare function getGlyphAtlasMetrics(atlas: Readonly<GlyphAtlas>): Readonly<GlyphMetrics>;
+//# sourceMappingURL=glyphAtlasMetrics.d.ts.map

package/dist/glyphAtlasMetrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glyphAtlasMetrics.d.ts","sourceRoot":"","sources":["../src/glyphAtlasMetrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAKhE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAExG;AAID,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC,YAAY,CAAC,CAExF"}

package/dist/glyphAtlasMetrics.js

@@ -0,0 +1,12 @@
+// The horizontal kerning adjustment (pixels) between an adjacent `left`/`right` glyph pair. The
+// dynamic canvas rasterizer exposes no pair kerning, so this is 0 in the first build; a native
+// shaping backend or a later kerning-table source can fill it in without changing the seam.
+export function getGlyphAtlasKerning(_atlas, _left, _right) {
+    return 0;
+}
+// The atlas's shared line metrics (ascent/descent/lineGap), as the `GlyphSource` metrics. Currently
+// derived from the configured font size at creation (see `deriveGlyphMetricsFromFontSize`).
+export function getGlyphAtlasMetrics(atlas) {
+    return atlas.runtime.metrics;
+}
+//# sourceMappingURL=glyphAtlasMetrics.js.map

package/dist/glyphAtlasMetrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glyphAtlasMetrics.js","sourceRoot":"","sources":["../src/glyphAtlasMetrics.ts"],"names":[],"mappings":"AAEA,gGAAgG;AAChG,+FAA+F;AAC/F,4FAA4F;AAC5F,MAAM,UAAU,oBAAoB,CAAC,MAA4B,EAAE,KAAa,EAAE,MAAc;IAC9F,OAAO,CAAC,CAAC;AACX,CAAC;AAED,oGAAoG;AACpG,4FAA4F;AAC5F,MAAM,UAAU,oBAAoB,CAAC,KAA2B;IAC9D,OAAO,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;AAC/B,CAAC"}

package/dist/glyphRasterizerBackend.d.ts

@@ -0,0 +1,5 @@
+import type { GlyphRasterizerBackend } from '@flighthq/types';
+export declare function createWebGlyphRasterizerBackend(): GlyphRasterizerBackend;
+export declare function getGlyphRasterizerBackend(): GlyphRasterizerBackend;
+export declare function setGlyphRasterizerBackend(backend: GlyphRasterizerBackend | null): void;
+//# sourceMappingURL=glyphRasterizerBackend.d.ts.map

package/dist/glyphRasterizerBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glyphRasterizerBackend.d.ts","sourceRoot":"","sources":["../src/glyphRasterizerBackend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgD,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAQ5G,wBAAgB,+BAA+B,IAAI,sBAAsB,CAQxE;AAID,wBAAgB,yBAAyB,IAAI,sBAAsB,CAGlE;AAGD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,GAAG,IAAI,CAEtF"}

package/dist/glyphRasterizerBackend.js

@@ -0,0 +1,92 @@
+// Builds the default web backend, which rasterizes a glyph on an offscreen canvas: it sets the font,
+// measures the glyph box + advance with `measureText`, fills the glyph with `fillText`, and reads the
+// pixels back with `getImageData`. Nothing touches the DOM at construction time — the canvas is
+// acquired lazily on the first `rasterize` — so importing the package has no side effect. When no
+// canvas is available (a headless/native host, or jsdom without a 2D context) `rasterize` returns
+// null rather than throwing; a native host installs its own backend via `setGlyphRasterizerBackend`.
+export function createWebGlyphRasterizerBackend() {
+    return {
+        rasterize(codepoint, options) {
+            const context = _acquireGlyphRasterContext();
+            if (context === null)
+                return null;
+            return _rasterizeGlyphOnContext(context, codepoint, options);
+        },
+    };
+}
+// The active rasterizer backend, lazily defaulting to the web canvas backend. There is always a
+// backend; `getGlyphAtlasEntry` asks this one to render a missing glyph.
+export function getGlyphRasterizerBackend() {
+    if (_backend === null)
+        _backend = createWebGlyphRasterizerBackend();
+    return _backend;
+}
+// Installs a native host rasterizer backend; pass null to fall back to the lazy web default.
+export function setGlyphRasterizerBackend(backend) {
+    _backend = backend;
+}
+let _backend = null;
+// Acquires a 2D drawing context from whichever canvas the host offers — an `OffscreenCanvas` first,
+// then a DOM `<canvas>` — or null when neither exists (or has no 2D context). The whole acquisition
+// is guarded so a host that throws on `getContext` degrades to the null sentinel instead of failing.
+function _acquireGlyphRasterContext() {
+    try {
+        if (typeof OffscreenCanvas !== 'undefined') {
+            const context = new OffscreenCanvas(1, 1).getContext('2d');
+            if (context !== null)
+                return context;
+        }
+        if (typeof document !== 'undefined' && typeof document.createElement === 'function') {
+            const context = document.createElement('canvas').getContext('2d');
+            if (context !== null)
+                return context;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+// Renders one glyph onto `context` and reads it back as a straight-alpha RGBA bitmap. The context's
+// canvas is resized to the measured ink box (plus a 1px guard on each side so anti-aliased edges are
+// not clipped); the glyph is filled in opaque white at the baseline so a text renderer can tint it.
+// Returns null for a zero-area glyph (whitespace with no ink) so the caller records only real glyphs.
+function _rasterizeGlyphOnContext(context, codepoint, options) {
+    const text = String.fromCodePoint(codepoint);
+    const fontStyle = options.fontStyle ?? 'normal';
+    const fontWeight = options.fontWeight ?? 'normal';
+    context.font = `${fontStyle} ${fontWeight} ${options.fontSize}px ${options.fontFamily}`;
+    context.textBaseline = 'alphabetic';
+    context.textAlign = 'left';
+    const metrics = context.measureText(text);
+    const advance = metrics.width;
+    const left = metrics.actualBoundingBoxLeft ?? 0;
+    const right = metrics.actualBoundingBoxRight ?? advance;
+    const ascent = metrics.actualBoundingBoxAscent ?? options.fontSize;
+    const descent = metrics.actualBoundingBoxDescent ?? 0;
+    const guard = 1;
+    const width = Math.max(0, Math.ceil(left + right)) + guard * 2;
+    const height = Math.max(0, Math.ceil(ascent + descent)) + guard * 2;
+    if (width <= guard * 2 || height <= guard * 2)
+        return null;
+    const canvas = context.canvas;
+    canvas.width = width;
+    canvas.height = height;
+    // font resets when the canvas is resized, so restore it before drawing.
+    context.font = `${fontStyle} ${fontWeight} ${options.fontSize}px ${options.fontFamily}`;
+    context.textBaseline = 'alphabetic';
+    context.textAlign = 'left';
+    context.clearRect(0, 0, width, height);
+    context.fillStyle = '#ffffff';
+    context.fillText(text, guard + left, guard + ascent);
+    const image = context.getImageData(0, 0, width, height);
+    return {
+        advance,
+        bearingX: -left,
+        bearingY: ascent,
+        height,
+        pixels: new Uint8ClampedArray(image.data),
+        width,
+    };
+}
+//# sourceMappingURL=glyphRasterizerBackend.js.map

package/dist/glyphRasterizerBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glyphRasterizerBackend.js","sourceRoot":"","sources":["../src/glyphRasterizerBackend.ts"],"names":[],"mappings":"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"}

package/dist/glyphSource.d.ts

@@ -0,0 +1,3 @@
+import type { GlyphAtlas, GlyphSource } from '@flighthq/types';
+export declare function createGlyphSourceFromGlyphAtlas(atlas: Readonly<GlyphAtlas>): GlyphSource;
+//# sourceMappingURL=glyphSource.d.ts.map

package/dist/glyphSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glyphSource.d.ts","sourceRoot":"","sources":["../src/glyphSource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAU/D,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,WAAW,CAiBxF"}

package/dist/glyphSource.js

@@ -0,0 +1,26 @@
+import { getGlyphAtlasSurface } from './glyphAtlas';
+import { getGlyphAtlasEntry } from './glyphAtlasEntry';
+import { getGlyphAtlasKerning, getGlyphAtlasMetrics } from './glyphAtlasMetrics';
+// Adapts a `GlyphAtlas` into the `GlyphSource` seam a text renderer consumes, binding the atlas's
+// free functions into the method object. `getGlyphEntry` ensures-then-returns (rasterize-on-miss),
+// so a renderer drawing a string just asks for each glyph. This is the dynamic implementation of
+// `GlyphSource`; `@flighthq/bitmapfont` will provide a static one of the same shape.
+export function createGlyphSourceFromGlyphAtlas(atlas) {
+    return {
+        getGlyphAtlasImage(page = 0) {
+            // One growing surface = page 0; a `Surface` is an `ImageResource`, so this pairs the geometry
+            // seam with its pixels directly.
+            return page === 0 ? getGlyphAtlasSurface(atlas) : null;
+        },
+        getGlyphEntry(codepoint) {
+            return getGlyphAtlasEntry(atlas, codepoint);
+        },
+        getGlyphKerning(left, right) {
+            return getGlyphAtlasKerning(atlas, left, right);
+        },
+        getGlyphMetrics() {
+            return getGlyphAtlasMetrics(atlas);
+        },
+    };
+}
+//# sourceMappingURL=glyphSource.js.map

package/dist/glyphSource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glyphSource.js","sourceRoot":"","sources":["../src/glyphSource.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEjF,kGAAkG;AAClG,mGAAmG;AACnG,iGAAiG;AACjG,qFAAqF;AACrF,MAAM,UAAU,+BAA+B,CAAC,KAA2B;IACzE,OAAO;QACL,kBAAkB,CAAC,IAAI,GAAG,CAAC;YACzB,8FAA8F;YAC9F,iCAAiC;YACjC,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACzD,CAAC;QACD,aAAa,CAAC,SAAS;YACrB,OAAO,kBAAkB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QAC9C,CAAC;QACD,eAAe,CAAC,IAAI,EAAE,KAAK;YACzB,OAAO,oBAAoB,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;QAClD,CAAC;QACD,eAAe;YACb,OAAO,oBAAoB,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './glyphAtlas';
+export * from './glyphAtlasDirty';
+export * from './glyphAtlasEntry';
+export * from './glyphAtlasMetrics';
+export * from './glyphRasterizerBackend';
+export * from './glyphSource';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from './glyphAtlas';
+export * from './glyphAtlasDirty';
+export * from './glyphAtlasEntry';
+export * from './glyphAtlasMetrics';
+export * from './glyphRasterizerBackend';
+export * from './glyphSource';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,eAAe,CAAC"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@flighthq/glyphatlas",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/geometry": "0.1.0",
+    "@flighthq/surface": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Dynamic glyph atlas — rasterize-on-miss into a growing texture atlas with LRU eviction and dirty-region tracking, behind a swappable rasterizer backend; owns and implements the GlyphSource seam for GPU text",
+  "sideEffects": false
+}

package/src/glyphAtlas.test.ts

@@ -0,0 +1,64 @@
+import type { GlyphRasterizerBackend } from '@flighthq/types';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import {
+  createGlyphAtlas,
+  deriveGlyphMetricsFromFontSize,
+  disposeGlyphAtlas,
+  getGlyphAtlasSurface,
+} from './glyphAtlas';
+import { getGlyphAtlasEntry } from './glyphAtlasEntry';
+import { setGlyphRasterizerBackend } from './glyphRasterizerBackend';
+
+describe('createGlyphAtlas', () => {
+  it('allocates an atlas surface at the requested size with an empty cache', () => {
+    const atlas = createGlyphAtlas({ fontFamily: 'mock', fontSize: 16, height: 64, width: 128 });
+    const surface = getGlyphAtlasSurface(atlas);
+
+    expect(surface.width).toBe(128);
+    expect(surface.height).toBe(64);
+    expect(atlas.runtime.entries.size).toBe(0);
+    expect(atlas.runtime.padding).toBe(1);
+  });
+});
+
+describe('deriveGlyphMetricsFromFontSize', () => {
+  it('splits the em into ascent, descent, and zero line gap', () => {
+    expect(deriveGlyphMetricsFromFontSize(10)).toEqual({ ascent: 8, descent: 2, lineGap: 0 });
+  });
+});
+
+describe('disposeGlyphAtlas', () => {
+  afterEach(() => setGlyphRasterizerBackend(null));
+
+  it('clears the cache so a subsequent lookup re-rasterizes', () => {
+    const { backend, calls } = createMockRasterizerBackend();
+    setGlyphRasterizerBackend(backend);
+    const atlas = createGlyphAtlas({ fontFamily: 'mock', fontSize: 16, height: 128, width: 128 });
+
+    getGlyphAtlasEntry(atlas, 65);
+    disposeGlyphAtlas(atlas);
+    expect(atlas.runtime.entries.size).toBe(0);
+
+    getGlyphAtlasEntry(atlas, 65);
+    expect(calls).toEqual([65, 65]);
+  });
+});
+
+describe('getGlyphAtlasSurface', () => {
+  it('returns the atlas backing surface', () => {
+    const atlas = createGlyphAtlas({ fontFamily: 'mock', fontSize: 16, height: 32, width: 32 });
+    expect(getGlyphAtlasSurface(atlas)).toBe(atlas.runtime.surface);
+  });
+});
+
+function createMockRasterizerBackend(): { backend: GlyphRasterizerBackend; calls: number[] } {
+  const calls: number[] = [];
+  const backend: GlyphRasterizerBackend = {
+    rasterize(codepoint) {
+      calls.push(codepoint);
+      return { advance: 8, bearingX: 1, bearingY: 8, height: 8, pixels: new Uint8ClampedArray(8 * 8 * 4), width: 8 };
+    },
+  };
+  return { backend, calls };
+}

package/src/glyphAtlasDirty.test.ts

@@ -0,0 +1,75 @@
+import type { GlyphRasterizerBackend } from '@flighthq/types';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { createGlyphAtlas } from './glyphAtlas';
+import { clearGlyphAtlasDirty, getGlyphAtlasDirtyRegion } from './glyphAtlasDirty';
+import { getGlyphAtlasEntry } from './glyphAtlasEntry';
+import { setGlyphRasterizerBackend } from './glyphRasterizerBackend';
+
+describe('clearGlyphAtlasDirty', () => {
+  afterEach(() => setGlyphRasterizerBackend(null));
+
+  it('resets the dirty region to null', () => {
+    setGlyphRasterizerBackend(createMockRasterizerBackend());
+    const atlas = createGlyphAtlas({ fontFamily: 'mock', fontSize: 16, height: 128, width: 128 });
+
+    getGlyphAtlasEntry(atlas, 65);
+    expect(getGlyphAtlasDirtyRegion(atlas)).not.toBeNull();
+
+    clearGlyphAtlasDirty(atlas);
+    expect(getGlyphAtlasDirtyRegion(atlas)).toBeNull();
+  });
+});
+
+describe('getGlyphAtlasDirtyRegion', () => {
+  afterEach(() => setGlyphRasterizerBackend(null));
+
+  it('is null on a fresh atlas', () => {
+    const atlas = createGlyphAtlas({ fontFamily: 'mock', fontSize: 16, height: 128, width: 128 });
+    expect(getGlyphAtlasDirtyRegion(atlas)).toBeNull();
+  });
+
+  it('covers a newly added glyph rect', () => {
+    setGlyphRasterizerBackend(createMockRasterizerBackend());
+    const atlas = createGlyphAtlas({ fontFamily: 'mock', fontSize: 16, height: 128, width: 128 });
+
+    const entry = getGlyphAtlasEntry(atlas, 65)!;
+    const region = getGlyphAtlasDirtyRegion(atlas)!;
+
+    expect(region.x).toBe(entry.x);
+    expect(region.y).toBe(entry.y);
+    expect(region.width).toBe(entry.width);
+    expect(region.height).toBe(entry.height);
+  });
+
+  it('re-dirties only the new rect after a clear', () => {
+    setGlyphRasterizerBackend(createMockRasterizerBackend());
+    const atlas = createGlyphAtlas({ fontFamily: 'mock', fontSize: 16, height: 128, width: 128 });
+
+    getGlyphAtlasEntry(atlas, 65);
+    clearGlyphAtlasDirty(atlas);
+    const entry = getGlyphAtlasEntry(atlas, 66)!;
+    const region = getGlyphAtlasDirtyRegion(atlas)!;
+
+    expect(region.x).toBe(entry.x);
+    expect(region.y).toBe(entry.y);
+    expect(region.width).toBe(entry.width);
+    expect(region.height).toBe(entry.height);
+  });
+});
+
+function createMockRasterizerBackend(): GlyphRasterizerBackend {
+  return {
+    rasterize(codepoint) {
+      const size = 8 + (codepoint % 4);
+      return {
+        advance: size,
+        bearingX: 1,
+        bearingY: size,
+        height: size,
+        pixels: new Uint8ClampedArray(size * size * 4),
+        width: size,
+      };
+    },
+  };
+}

package/src/glyphAtlasEntry.test.ts

@@ -0,0 +1,157 @@
+import { getSurfacePixel } from '@flighthq/surface';
+import type { GlyphEntry, GlyphRasterizedBitmap, GlyphRasterizerBackend } from '@flighthq/types';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { createGlyphAtlas, getGlyphAtlasSurface } from './glyphAtlas';
+import { getGlyphAtlasEntry } from './glyphAtlasEntry';
+import { setGlyphRasterizerBackend } from './glyphRasterizerBackend';
+
+describe('getGlyphAtlasEntry', () => {
+  afterEach(() => setGlyphRasterizerBackend(null));
+
+  it('rasterizes a missing glyph once and caches it', () => {
+    const { backend, calls } = createMockRasterizerBackend();
+    setGlyphRasterizerBackend(backend);
+    const atlas = createGlyphAtlas({ fontFamily: 'mock', fontSize: 16, height: 256, width: 256 });
+
+    const first = getGlyphAtlasEntry(atlas, 65);
+    const second = getGlyphAtlasEntry(atlas, 65);
+
+    expect(first).not.toBeNull();
+    expect(second).toBe(first);
+    expect(calls).toEqual([65]);
+  });
+
+  it('passes the rasterized size, advance, and bearing through to the entry', () => {
+    const { backend } = createMockRasterizerBackend((cp) => ({ height: 10, width: cp === 65 ? 12 : 6 }));
+    setGlyphRasterizerBackend(backend);
+    const atlas = createGlyphAtlas({ fontFamily: 'mock', fontSize: 16, height: 256, width: 256 });
+
+    const entry = getGlyphAtlasEntry(atlas, 65)!;
+
+    expect(entry.width).toBe(12);
+    expect(entry.height).toBe(10);
+    expect(entry.advance).toBe(12);
+    expect(entry.bearingX).toBe(1);
+    expect(entry.bearingY).toBe(10);
+    expect(entry.page).toBe(0); // The dynamic atlas is a single growing page.
+  });
+
+  it('places different glyphs in non-overlapping, in-bounds rects', () => {
+    const { backend } = createMockRasterizerBackend((cp) => ({ height: 8 + (cp % 5), width: 8 + (cp % 7) }));
+    setGlyphRasterizerBackend(backend);
+    const atlas = createGlyphAtlas({ fontFamily: 'mock', fontSize: 16, height: 256, width: 256 });
+    const surface = getGlyphAtlasSurface(atlas);
+
+    const entries: GlyphEntry[] = [];
+    for (let cp = 65; cp < 75; cp++) entries.push(getGlyphAtlasEntry(atlas, cp)!);
+
+    for (const entry of entries) {
+      expect(entry.x).toBeGreaterThanOrEqual(0);
+      expect(entry.y).toBeGreaterThanOrEqual(0);
+      expect(entry.x + entry.width).toBeLessThanOrEqual(surface.width);
+      expect(entry.y + entry.height).toBeLessThanOrEqual(surface.height);
+    }
+    expectNoOverlap(entries);
+  });
+
+  it('blits the glyph pixels into the atlas surface at the entry rect', () => {
+    const { backend } = createMockRasterizerBackend();
+    setGlyphRasterizerBackend(backend);
+    const atlas = createGlyphAtlas({ fontFamily: 'mock', fontSize: 16, height: 256, width: 256 });
+    const surface = getGlyphAtlasSurface(atlas);
+
+    const entry = getGlyphAtlasEntry(atlas, 0x41)!;
+    const corner = getSurfacePixel(surface, entry.x, entry.y);
+    const inside = getSurfacePixel(surface, entry.x + 2, entry.y + 2);
+
+    // The mock fills every glyph pixel with (R = codepoint & 0xff, G = 0x80, B = 0x40, A = 0xff).
+    expect((corner >>> 24) & 0xff).toBe(0x41);
+    expect((corner >>> 16) & 0xff).toBe(0x80);
+    expect((corner >>> 8) & 0xff).toBe(0x40);
+    expect(corner & 0xff).toBe(0xff);
+    expect(inside).toBe(corner);
+  });
+
+  it('evicts the least-recently-used glyph past the glyph budget and re-rasterizes it on demand', () => {
+    const { backend, calls } = createMockRasterizerBackend();
+    setGlyphRasterizerBackend(backend);
+    const atlas = createGlyphAtlas({ fontFamily: 'mock', fontSize: 16, height: 256, maxGlyphs: 2, width: 256 });
+
+    getGlyphAtlasEntry(atlas, 65);
+    getGlyphAtlasEntry(atlas, 66);
+    getGlyphAtlasEntry(atlas, 65); // touch 65 so 66 becomes least-recently-used
+    getGlyphAtlasEntry(atlas, 67); // over budget -> evicts 66
+    expect(calls).toEqual([65, 66, 67]);
+
+    getGlyphAtlasEntry(atlas, 65); // still cached -> no re-rasterize
+    expect(calls).toEqual([65, 66, 67]);
+
+    getGlyphAtlasEntry(atlas, 66); // evicted -> re-rasterizes
+    expect(calls).toEqual([65, 66, 67, 66]);
+  });
+
+  it('keeps rects non-overlapping after eviction and repack', () => {
+    const { backend } = createMockRasterizerBackend((cp) => ({ height: 8 + (cp % 6), width: 8 + (cp % 4) }));
+    setGlyphRasterizerBackend(backend);
+    const atlas = createGlyphAtlas({ fontFamily: 'mock', fontSize: 16, height: 256, maxGlyphs: 4, width: 256 });
+
+    // Add eight glyphs through a four-glyph budget: each of the last four insertions evicts an older
+    // glyph and repacks. The four most-recent codepoints stay cached, so re-requesting them are pure
+    // hits that return their stable post-repack positions.
+    for (let cp = 65; cp < 73; cp++) getGlyphAtlasEntry(atlas, cp);
+    const surviving: GlyphEntry[] = [];
+    for (let cp = 69; cp < 73; cp++) surviving.push(getGlyphAtlasEntry(atlas, cp)!);
+
+    expect(surviving).toHaveLength(4);
+    expectNoOverlap(surviving);
+  });
+
+  it('returns null for a single glyph larger than the whole atlas', () => {
+    const { backend } = createMockRasterizerBackend(() => ({ height: 200, width: 200 }));
+    setGlyphRasterizerBackend(backend);
+    const atlas = createGlyphAtlas({ fontFamily: 'mock', fontSize: 16, height: 64, width: 64 });
+
+    expect(getGlyphAtlasEntry(atlas, 65)).toBeNull();
+  });
+
+  it('returns null when the rasterizer produces nothing', () => {
+    const backend: GlyphRasterizerBackend = { rasterize: () => null };
+    setGlyphRasterizerBackend(backend);
+    const atlas = createGlyphAtlas({ fontFamily: 'mock', fontSize: 16, height: 256, width: 256 });
+
+    expect(getGlyphAtlasEntry(atlas, 65)).toBeNull();
+  });
+});
+
+function createMockRasterizerBackend(
+  sizeFor: (codepoint: number) => { width: number; height: number } = () => ({ height: 8, width: 8 }),
+): { backend: GlyphRasterizerBackend; calls: number[] } {
+  const calls: number[] = [];
+  const backend: GlyphRasterizerBackend = {
+    rasterize(codepoint): GlyphRasterizedBitmap {
+      calls.push(codepoint);
+      const { width, height } = sizeFor(codepoint);
+      const pixels = new Uint8ClampedArray(width * height * 4);
+      for (let i = 0; i < width * height; i++) {
+        pixels[i * 4] = codepoint & 0xff;
+        pixels[i * 4 + 1] = 0x80;
+        pixels[i * 4 + 2] = 0x40;
+        pixels[i * 4 + 3] = 0xff;
+      }
+      return { advance: width, bearingX: 1, bearingY: height, height, pixels, width };
+    },
+  };
+  return { backend, calls };
+}
+
+function expectNoOverlap(entries: readonly Readonly<GlyphEntry>[]): void {
+  for (let i = 0; i < entries.length; i++) {
+    for (let j = i + 1; j < entries.length; j++) {
+      const a = entries[i];
+      const b = entries[j];
+      const overlaps = a.x < b.x + b.width && b.x < a.x + a.width && a.y < b.y + b.height && b.y < a.y + a.height;
+      expect(overlaps).toBe(false);
+    }
+  }
+}

package/src/glyphAtlasMetrics.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+
+import { createGlyphAtlas } from './glyphAtlas';
+import { getGlyphAtlasKerning, getGlyphAtlasMetrics } from './glyphAtlasMetrics';
+
+describe('getGlyphAtlasKerning', () => {
+  it('is zero in the first build (no pair kerning source)', () => {
+    const atlas = createGlyphAtlas({ fontFamily: 'mock', fontSize: 16, height: 64, width: 64 });
+    expect(getGlyphAtlasKerning(atlas, 65, 66)).toBe(0);
+  });
+});
+
+describe('getGlyphAtlasMetrics', () => {
+  it('returns the font-size-derived line metrics', () => {
+    const atlas = createGlyphAtlas({ fontFamily: 'mock', fontSize: 20, height: 64, width: 64 });
+    expect(getGlyphAtlasMetrics(atlas)).toEqual({ ascent: 16, descent: 4, lineGap: 0 });
+  });
+});

package/src/glyphRasterizerBackend.test.ts

@@ -0,0 +1,49 @@
+import type { GlyphRasterizerBackend } from '@flighthq/types';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import {
+  createWebGlyphRasterizerBackend,
+  getGlyphRasterizerBackend,
+  setGlyphRasterizerBackend,
+} from './glyphRasterizerBackend';
+
+describe('createWebGlyphRasterizerBackend', () => {
+  it('constructs a backend without a DOM side effect', () => {
+    expect(typeof createWebGlyphRasterizerBackend().rasterize).toBe('function');
+  });
+
+  it('sentinels to null when no 2D canvas context is available', () => {
+    // jsdom's HTMLCanvasElement.getContext('2d') returns null without the canvas package installed,
+    // and OffscreenCanvas is undefined, so the web backend has no surface to rasterize onto.
+    const backend = createWebGlyphRasterizerBackend();
+    expect(backend.rasterize(65, { fontFamily: 'sans-serif', fontSize: 16 })).toBeNull();
+  });
+});
+
+describe('getGlyphRasterizerBackend', () => {
+  afterEach(() => setGlyphRasterizerBackend(null));
+
+  it('lazily defaults to a web backend', () => {
+    setGlyphRasterizerBackend(null);
+    expect(typeof getGlyphRasterizerBackend().rasterize).toBe('function');
+  });
+
+  it('returns the installed backend', () => {
+    const backend: GlyphRasterizerBackend = { rasterize: () => null };
+    setGlyphRasterizerBackend(backend);
+    expect(getGlyphRasterizerBackend()).toBe(backend);
+  });
+});
+
+describe('setGlyphRasterizerBackend', () => {
+  afterEach(() => setGlyphRasterizerBackend(null));
+
+  it('restores the lazy web default when passed null', () => {
+    const backend: GlyphRasterizerBackend = { rasterize: () => null };
+    setGlyphRasterizerBackend(backend);
+    expect(getGlyphRasterizerBackend()).toBe(backend);
+
+    setGlyphRasterizerBackend(null);
+    expect(getGlyphRasterizerBackend()).not.toBe(backend);
+  });
+});

package/src/glyphSource.test.ts

@@ -0,0 +1,43 @@
+import type { GlyphRasterizerBackend } from '@flighthq/types';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { createGlyphAtlas, getGlyphAtlasSurface } from './glyphAtlas';
+import { getGlyphAtlasEntry } from './glyphAtlasEntry';
+import { setGlyphRasterizerBackend } from './glyphRasterizerBackend';
+import { createGlyphSourceFromGlyphAtlas } from './glyphSource';
+
+describe('createGlyphSourceFromGlyphAtlas', () => {
+  afterEach(() => setGlyphRasterizerBackend(null));
+
+  it('exposes the atlas as a GlyphSource that rasterizes on miss', () => {
+    const backend: GlyphRasterizerBackend = {
+      rasterize: () => ({
+        advance: 8,
+        bearingX: 1,
+        bearingY: 8,
+        height: 8,
+        pixels: new Uint8ClampedArray(8 * 8 * 4),
+        width: 8,
+      }),
+    };
+    setGlyphRasterizerBackend(backend);
+    const atlas = createGlyphAtlas({ fontFamily: 'mock', fontSize: 20, height: 128, width: 128 });
+    const source = createGlyphSourceFromGlyphAtlas(atlas);
+
+    const entry = source.getGlyphEntry(65);
+    expect(entry).not.toBeNull();
+    expect(entry!.page).toBe(0);
+    expect(source.getGlyphEntry(65)).toBe(getGlyphAtlasEntry(atlas, 65));
+    expect(source.getGlyphKerning(65, 66)).toBe(0);
+    expect(source.getGlyphMetrics()).toEqual({ ascent: 16, descent: 4, lineGap: 0 });
+  });
+
+  it('pairs page 0 with the atlas surface and has no other page', () => {
+    const atlas = createGlyphAtlas({ fontFamily: 'mock', fontSize: 20, height: 128, width: 128 });
+    const source = createGlyphSourceFromGlyphAtlas(atlas);
+
+    expect(source.getGlyphAtlasImage(0)).toBe(getGlyphAtlasSurface(atlas));
+    expect(source.getGlyphAtlasImage()).toBe(getGlyphAtlasSurface(atlas));
+    expect(source.getGlyphAtlasImage(1)).toBeNull();
+  });
+});