vgpu-render 0.0.0-stage → 0.2.0

package/dist/text-atlas.js

@@ -0,0 +1,498 @@
+/**
+ * Glyph atlas for the text renderer.
+ *
+ * The equivalent of reference `FontAtlas` / `FontAtlasSet`
+ * (`the reference implementation`, `font_atlas_set.rs`): rasterised glyphs are packed
+ * into one or more pages and remembered by their atlas rectangle plus the ink offset that
+ * places them relative to the pen. reference stores every glyph as a tintable alpha mask
+ * (RGB = 255, A = coverage) so the shader can colour it, and uses a minimum 512 px page with
+ * 2 px of padding; both choices are kept here, since the padding is what keeps linear
+ * sampling from bleeding between neighbours.
+ *
+ * Unlike reference the atlas is not keyed per font size: the cache key carries the face and size
+ * instead, so one page set serves every size a frame happens to use. The face part comes from
+ * `GlyphRasterizer.faceKey`, which is how a source states which of the axes it can actually vary.
+ * Glyphs are rasterised at `rasterScale` times their font size, which decouples the atlas' detail from the logical layout
+ * size — the same separation as resampling a font at a higher point size before scaling it down.
+ * Pages grow on demand until `maxPages` is reached — the GPU renderer pins that at one page so a
+ * single draw call covers the whole atlas — and a `revision` counter tells the renderer which of
+ * them changed since the last upload.
+ */
+import { fontFaceKey } from "./text-layout.js";
+/** Page size and inter-glyph padding, matching reference minimum atlas and `GLYPH_ATLAS_PADDING`. */
+export const DEFAULT_ATLAS_SIZE = 512;
+export const DEFAULT_ATLAS_PADDING = 2;
+/**
+ * Which channels hold a distance, per encoding. A mip chain has to resample those through coverage
+ * rather than averaging the values; everything else in a texel is signal that averages.
+ */
+export const DISTANCE_CHANNELS = {
+    bitmap: [],
+    sdf: [0],
+    msdf: [0, 1, 2],
+};
+export class GlyphAtlas {
+    #rasterizer;
+    #size;
+    #padding;
+    #maxPages;
+    #onFull;
+    #skipped = 0;
+    #pages = [];
+    #packing = [];
+    #glyphs = new Map();
+    #missing = new Set();
+    /** Cache keys per page, so a page can be recycled as a whole when every glyph on it is stale. */
+    #pageGlyphs = [];
+    /** Rectangles handed back by recycling a single stale glyph, reusable for later ones. */
+    #free = [];
+    #frame = 0;
+    constructor(rasterizer, options = {}) {
+        this.#rasterizer = rasterizer;
+        this.#size = options.size ?? DEFAULT_ATLAS_SIZE;
+        this.#padding = options.padding ?? DEFAULT_ATLAS_PADDING;
+        this.#maxPages = options.maxPages ?? Number.POSITIVE_INFINITY;
+        this.#onFull = options.onFull ?? "throw";
+        if (!Number.isInteger(this.#size) || this.#size <= 0)
+            throw new RangeError("atlas size must be a positive integer");
+        if (!Number.isInteger(this.#padding) || this.#padding < 0)
+            throw new RangeError("atlas padding must be a non-negative integer");
+        if (this.#maxPages < 1)
+            throw new RangeError("atlas maxPages must be at least one");
+        if (!(this.rasterScale > 0))
+            throw new RangeError("the glyph source's rasterScale must be greater than zero");
+    }
+    /** The encoding the glyph source writes, which is also how the shader will decode the page. */
+    get encoding() {
+        return this.#rasterizer.encoding;
+    }
+    /** The distance range the source encodes with, if it uses a distance field at all. */
+    get distanceRange() {
+        return this.#rasterizer.distanceRange;
+    }
+    /** How much larger the source's texels are than layout units. See `GlyphRasterizer.rasterScale`. */
+    get rasterScale() {
+        return this.#rasterizer.rasterScale ?? 1;
+    }
+    get pages() {
+        return this.#pages;
+    }
+    /**
+     * Glyphs dropped because the atlas was full and no page could be recycled, which only happens when
+     * the caller chose `onFull: "skip"`. A renderer reports it so a frame that is quietly missing a
+     * character can be told apart from one the font never had.
+     */
+    get skipped() {
+        return this.#skipped;
+    }
+    /**
+     * Marks the start of a frame. Glyphs that were not requested in the current frame become
+     * recyclable, so a bounded atlas stops being a hard failure once on-screen text changes shape.
+     * Call it once per frame, before the frame's glyphs are requested.
+     */
+    beginFrame() {
+        this.#frame++;
+    }
+    /**
+     * Returns the atlas entry for a character, rasterising and packing it on first use.
+     * `undefined` means the character has no ink (whitespace) or the rasteriser has nothing for
+     * it; the layout layer has already dropped those glyphs, so callers treat it as a skip.
+     *
+     * `rasterScale` defaults to the source's own scale, which keeps a fixed-raster source drawing
+     * exactly as it did. The renderer passes the size the block covers on screen instead, so the entry
+     * that comes back is rasterised for the rung that face asked for.
+     */
+    glyph(character, face, fontSize, rasterScale) {
+        const scale = rasterScale !== undefined && rasterScale > 0 ? rasterScale : this.rasterScale;
+        // The key carries the size the glyph was *rasterised* at rather than the layout font size: two
+        // font sizes that land on the same rung share one rasterisation, which is what keeps a block
+        // whose size changes every frame from rasterising the same character over and over.
+        const rasterPx = Math.max(1, Math.round(fontSize * scale));
+        const faceKey = this.#rasterizer.faceKey?.(face) ?? fontFaceKey(face);
+        const key = `${faceKey}|${rasterPx}|${character}`;
+        const cached = this.#glyphs.get(key);
+        if (cached !== undefined) {
+            cached.lastFrame = this.#frame;
+            return cached;
+        }
+        if (this.#missing.has(key))
+            return undefined;
+        const rasterized = this.#rasterizer.rasterize(character, face, rasterPx);
+        if (rasterized === undefined) {
+            this.#missing.add(key);
+            return undefined;
+        }
+        const placement = this.#pack(rasterized.width, rasterized.height);
+        if (placement === undefined) {
+            if (this.#onFull === "throw") {
+                throw new RangeError(`the glyph atlas is full: ${this.#pages.length} page(s) of ${this.#size}px no longer fit a new glyph; raise the atlas size or the page count`);
+            }
+            // Capacity, not the font: the next frame may have room again, so this is not cached as missing.
+            this.#skipped++;
+            return undefined;
+        }
+        const page = this.#pages[placement.page];
+        this.#blit(page, placement.x, placement.y, rasterized.width, rasterized.height, rasterized.texels);
+        const glyph = {
+            page: placement.page,
+            // Only the ink box is mapped, not the rounded-up image, so the quad and the texels agree.
+            uv: [
+                placement.x / this.#size,
+                placement.y / this.#size,
+                (placement.x + rasterized.inkWidth) / this.#size,
+                (placement.y + rasterized.inkHeight) / this.#size,
+            ],
+            bearingLeft: rasterized.bearingLeft,
+            bearingTop: rasterized.bearingTop,
+            width: rasterized.inkWidth,
+            height: rasterized.inkHeight,
+            advance: rasterized.advance,
+            rasterScale: rasterPx / fontSize,
+            lastFrame: this.#frame,
+            atlasX: placement.x,
+            atlasY: placement.y,
+            atlasWidth: rasterized.width,
+            atlasHeight: rasterized.height,
+        };
+        this.#glyphs.set(key, glyph);
+        this.#pageGlyphs[placement.page].add(key);
+        return glyph;
+    }
+    /** Drops every cached glyph. The next frame re-rasterises whatever it still draws. */
+    clear() {
+        this.#glyphs.clear();
+        this.#missing.clear();
+        this.#free.length = 0;
+        for (const keys of this.#pageGlyphs)
+            keys.clear();
+        for (const page of this.#pages) {
+            page.data.fill(0);
+            page.revision++;
+            // Blanking the whole page is a full-page upload, not a few dirty rectangles.
+            page.dirty = { x: 0, y: 0, width: page.size, height: page.size };
+        }
+        for (const packing of this.#packing) {
+            packing.nextY = 0;
+            packing.shelves.length = 0;
+        }
+    }
+    #createPage() {
+        const index = this.#pages.length;
+        this.#pages.push({ index, size: this.#size, data: new Uint8Array(this.#size * this.#size * 4), revision: 0, dirty: undefined });
+        this.#packing.push({ nextY: 0, shelves: [] });
+        this.#pageGlyphs.push(new Set());
+        return index;
+    }
+    /**
+     * Blanks a page whose glyphs were all requested in an earlier frame and returns its index, or
+     * `undefined` when no page is entirely stale. Recycling a whole page resets its shelf packing,
+     * which is what makes it the preferred path over handing single rectangles back.
+     */
+    #recyclePage() {
+        let victim = -1;
+        let oldest = Number.POSITIVE_INFINITY;
+        for (let index = 0; index < this.#pages.length; index++) {
+            let newest = -1;
+            for (const key of this.#pageGlyphs[index]) {
+                const entry = this.#glyphs.get(key);
+                if (entry !== undefined && entry.lastFrame > newest)
+                    newest = entry.lastFrame;
+            }
+            if (newest >= this.#frame)
+                continue;
+            if (newest < oldest) {
+                oldest = newest;
+                victim = index;
+            }
+        }
+        if (victim === -1)
+            return undefined;
+        const page = this.#pages[victim];
+        page.data.fill(0);
+        page.revision++;
+        page.dirty = { x: 0, y: 0, width: page.size, height: page.size };
+        const packing = this.#packing[victim];
+        packing.nextY = 0;
+        packing.shelves.length = 0;
+        for (const key of this.#pageGlyphs[victim])
+            this.#glyphs.delete(key);
+        this.#pageGlyphs[victim].clear();
+        return victim;
+    }
+    /**
+     * Falls back to recycling single stale glyphs, oldest first, until one of their rectangles can
+     * hold the new glyph. This is what covers a page that mixes glyphs from the current frame with
+     * ones from earlier frames: the whole page cannot be blanked, but the stale part can be reused.
+     */
+    #recycleGlyphs(w, h) {
+        const stale = [];
+        for (const [key, glyph] of this.#glyphs) {
+            if (glyph.lastFrame < this.#frame)
+                stale.push({ key, glyph });
+        }
+        if (stale.length === 0)
+            return undefined;
+        stale.sort((a, b) => a.glyph.lastFrame - b.glyph.lastFrame);
+        for (const { key, glyph } of stale) {
+            this.#release(key, glyph);
+            const placement = this.#takeFree(w, h);
+            if (placement !== undefined)
+                return placement;
+        }
+        return undefined;
+    }
+    /** Hands one glyph's packed rectangle back, sized to include the packing padding. */
+    #release(key, glyph) {
+        this.#glyphs.delete(key);
+        this.#pageGlyphs[glyph.page].delete(key);
+        this.#free.push({
+            page: glyph.page,
+            x: glyph.atlasX,
+            y: glyph.atlasY,
+            width: glyph.atlasWidth + this.#padding,
+            height: glyph.atlasHeight + this.#padding,
+        });
+    }
+    /** Takes the smallest recycled rectangle that fits, splitting off whatever it does not use. */
+    #takeFree(w, h) {
+        let best = -1;
+        let bestArea = Number.POSITIVE_INFINITY;
+        for (let index = 0; index < this.#free.length; index++) {
+            const rect = this.#free[index];
+            if (rect.width < w || rect.height < h)
+                continue;
+            const area = rect.width * rect.height;
+            if (area < bestArea) {
+                bestArea = area;
+                best = index;
+            }
+        }
+        if (best === -1)
+            return undefined;
+        const rect = this.#free[best];
+        this.#free.splice(best, 1);
+        if (rect.width > w)
+            this.#free.push({ page: rect.page, x: rect.x + w, y: rect.y, width: rect.width - w, height: rect.height });
+        if (rect.height > h)
+            this.#free.push({ page: rect.page, x: rect.x, y: rect.y + h, width: Math.min(rect.width, w), height: rect.height - h });
+        return { page: rect.page, x: rect.x, y: rect.y };
+    }
+    /**
+     * Shelf packing: glyphs fill a row until it runs out of width, then a new row starts below.
+     * reference uses a rectangle packer, but for the handful of sizes a debug frame draws, shelves
+     * waste little and keep placement deterministic.
+     *
+     * `undefined` means every page is full and nothing on them was recyclable. The caller decides what
+     * that costs; see `onFull`.
+     */
+    #pack(width, height) {
+        const w = width + this.#padding;
+        const h = height + this.#padding;
+        if (w > this.#size || h > this.#size) {
+            throw new RangeError(`a ${width}×${height} glyph does not fit a ${this.#size}px atlas page`);
+        }
+        const free = this.#takeFree(w, h);
+        if (free !== undefined)
+            return free;
+        for (let index = 0; index < this.#pages.length; index++) {
+            const placement = packInto(this.#packing[index], w, h, this.#size);
+            if (placement !== undefined)
+                return { page: index, x: placement.x, y: placement.y };
+        }
+        const recycledPage = this.#recyclePage();
+        if (recycledPage !== undefined) {
+            const placement = packInto(this.#packing[recycledPage], w, h, this.#size);
+            return { page: recycledPage, x: placement.x, y: placement.y };
+        }
+        const recycled = this.#recycleGlyphs(w, h);
+        if (recycled !== undefined)
+            return recycled;
+        if (this.#pages.length >= this.#maxPages) {
+            return undefined;
+        }
+        const index = this.#createPage();
+        const placement = packInto(this.#packing[index], w, h, this.#size);
+        // `#createPage` starts from an empty page, and the size check above proved the glyph fits.
+        return { page: index, x: placement.x, y: placement.y };
+    }
+    /** Copies one glyph's texels into the page. The encoding is already baked into them. */
+    #blit(page, x, y, width, height, texels) {
+        const rowBytes = page.size * 4;
+        const glyphRowBytes = width * 4;
+        for (let row = 0; row < height; row++) {
+            page.data.set(texels.subarray(row * glyphRowBytes, (row + 1) * glyphRowBytes), (y + row) * rowBytes + x * 4);
+        }
+        page.revision++;
+        page.dirty = extendDirty(page.dirty, { x, y, width, height });
+    }
+}
+/** Grows a dirty rectangle so it also covers `next`. */
+function extendDirty(current, next) {
+    if (current === undefined)
+        return next;
+    const x = Math.min(current.x, next.x);
+    const y = Math.min(current.y, next.y);
+    const right = Math.max(current.x + current.width, next.x + next.width);
+    const bottom = Math.max(current.y + current.height, next.y + next.height);
+    return { x, y, width: right - x, height: bottom - y };
+}
+/**
+ * Maps a level-0 dirty rectangle onto one mip level. Every level halves the coordinates and grows
+ * the rectangle by one texel, because a box filter reads across the edge it averages.
+ */
+export function dirtyAtLevel(dirty, level, pageSize) {
+    let size = pageSize;
+    let left = dirty.x;
+    let top = dirty.y;
+    let right = dirty.x + dirty.width;
+    let bottom = dirty.y + dirty.height;
+    for (let step = 0; step < level; step++) {
+        size = Math.max(1, size >> 1);
+        left = Math.max(0, (left >> 1) - 1);
+        top = Math.max(0, (top >> 1) - 1);
+        right = Math.min(size, Math.ceil(right / 2) + 1);
+        bottom = Math.min(size, Math.ceil(bottom / 2) + 1);
+    }
+    return { x: left, y: top, width: Math.max(1, right - left), height: Math.max(1, bottom - top) };
+}
+/**
+ * Box-downsamples one mip level: every output texel averages its 2×2 source block, clamped at the
+ * edge. The page is a tintable mask — RGB is a constant 255 and all the signal sits in the coverage
+ * channel — so averaging is exactly the right minification filter here. A distance field would need
+ * the usual distance-compression trick instead, which is why an encoder that stores one keeps its
+ * own resampling.
+ */
+export function downsamplePage(data, size) {
+    const half = Math.max(1, size >> 1);
+    const result = new Uint8Array(half * half * 4);
+    for (let y = 0; y < half; y++) {
+        for (let x = 0; x < half; x++) {
+            const sums = [0, 0, 0, 0];
+            for (let dy = 0; dy < 2; dy++) {
+                const sourceY = Math.min(y * 2 + dy, size - 1);
+                for (let dx = 0; dx < 2; dx++) {
+                    const sourceX = Math.min(x * 2 + dx, size - 1);
+                    const index = (sourceY * size + sourceX) * 4;
+                    for (let channel = 0; channel < 4; channel++)
+                        sums[channel] += data[index + channel];
+                }
+            }
+            const target = (y * half + x) * 4;
+            for (let channel = 0; channel < 4; channel++)
+                result[target + channel] = Math.round(sums[channel] / 4);
+        }
+    }
+    return result;
+}
+/** The coverage an encoded distance reads back as, given the field's range in texels. */
+function readCoverage(value, range) {
+    const coverage = (value / 255 - 0.5) * 2 * range + 0.5;
+    return coverage < 0 ? 0 : coverage > 1 ? 1 : coverage;
+}
+/** The encoded value that reads back as a given coverage. */
+function encodeCoverage(coverage, range) {
+    const value = Math.round(((coverage - 0.5) / (2 * range) + 0.5) * 255);
+    return value < 0 ? 0 : value > 255 ? 255 : value;
+}
+/**
+ * Box-downsamples one mip level of a distance field.
+ *
+ * Averaging stored distances is not the same filter. A distance is the signed distance to the nearest
+ * edge, so where the field saturates its magnitude carries no information — a block that is half
+ * deeply-inside ink and half just-outside ink averages to a value that says "far inside" while its
+ * real coverage is a half — and a level that feeds that back through `clamp(distance + 0.5)` loses or
+ * invents ink. Measured against the geometric coverage of the same glyphs, a level built this way
+ * reads about 10% light. Decoding each value as the coverage it implies, averaging that, and
+ * encoding the result back is the filter that behaves like the coverage mask's own.
+ *
+ * The stored value keeps meaning "distance in level-0 texels, range `range`", which is what the
+ * shader's decode assumes once it scales its range by the level it sampled.
+ *
+ * `distanceChannels` says which channels this applies to, since a texel may mix the two.
+ */
+export function downsampleDistancePage(data, size, range, distanceChannels) {
+    const isDistance = [false, false, false, false];
+    for (const channel of distanceChannels)
+        isDistance[channel] = true;
+    const half = Math.max(1, size >> 1);
+    const result = new Uint8Array(half * half * 4);
+    for (let y = 0; y < half; y++) {
+        for (let x = 0; x < half; x++) {
+            const sums = [0, 0, 0, 0];
+            for (let dy = 0; dy < 2; dy++) {
+                const sourceY = Math.min(y * 2 + dy, size - 1);
+                for (let dx = 0; dx < 2; dx++) {
+                    const sourceX = Math.min(x * 2 + dx, size - 1);
+                    const index = (sourceY * size + sourceX) * 4;
+                    for (let channel = 0; channel < 4; channel++) {
+                        const value = data[index + channel];
+                        sums[channel] += isDistance[channel] ? readCoverage(value, range) : value;
+                    }
+                }
+            }
+            const target = (y * half + x) * 4;
+            for (let channel = 0; channel < 4; channel++) {
+                const mean = sums[channel] / 4;
+                result[target + channel] = isDistance[channel] ? encodeCoverage(mean, range) : Math.round(mean);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Builds a square page's mip chain, stopping early at 1×1 or once `levels` are reached.
+ *
+ * `downsample` defaults to the coverage box filter. A distance-field page passes
+ * `downsampleDistancePage` instead, so its levels keep reporting coverage rather than an average
+ * distance.
+ */
+export function buildMipChain(data, size, levels, downsample = downsamplePage) {
+    const chain = [{ size, data }];
+    let current = data;
+    let currentSize = size;
+    while (chain.length < levels && currentSize > 1) {
+        current = downsample(current, currentSize);
+        currentSize = Math.max(1, currentSize >> 1);
+        chain.push({ size: currentSize, data: current });
+    }
+    return chain;
+}
+/**
+ * Extracts one rectangle of a page and pads its rows to WebGPU's 256 byte `bytesPerRow`
+ * requirement, which only binds once a rectangle has more than one row. The copy is a few hundred
+ * bytes for a single glyph, so it is not worth avoiding.
+ */
+export function extractRegion(data, size, rect) {
+    const rowBytes = rect.width * 4;
+    const stride = Math.ceil(rowBytes / 256) * 256;
+    // A full-width rectangle whose rows already meet the alignment needs no copy at all.
+    if (rect.x === 0 && rect.width === size && stride === rowBytes) {
+        const start = rect.y * rowBytes;
+        return { data: data.subarray(start, start + rowBytes * rect.height), bytesPerRow: stride };
+    }
+    const padded = new Uint8Array(stride * rect.height);
+    for (let row = 0; row < rect.height; row++) {
+        const from = ((rect.y + row) * size + rect.x) * 4;
+        padded.set(data.subarray(from, from + rowBytes), row * stride);
+    }
+    return { data: padded, bytesPerRow: stride };
+}
+/** Pads one whole mip level's rows through `extractRegion`. */
+export function padMipRows(data, size) {
+    return extractRegion(data, size, { x: 0, y: 0, width: size, height: size });
+}
+function packInto(packing, w, h, size) {
+    for (const shelf of packing.shelves) {
+        if (shelf.height >= h && shelf.used + w <= size) {
+            const x = shelf.used;
+            shelf.used += w;
+            return { x, y: shelf.y };
+        }
+    }
+    if (packing.nextY + h > size)
+        return undefined;
+    const y = packing.nextY;
+    packing.shelves.push({ y, height: h, used: w });
+    packing.nextY += h;
+    return { x: 0, y };
+}

package/dist/text-font.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Browser-side font loading and glyph rasterisation for the text renderer.
+ *
+ * reference rasterises glyphs with swash into a `FontAtlas`
+ * (`the reference implementation`); the equivalent rasteriser in a browser is
+ * Canvas2D, so `fillText` plays the role of `swash::scale::Render` and the browser's font
+ * stack stands in for font discovery. The bundled font is inlined exactly the way reference
+ * inlines `FiraMono-subset.ttf` with `include_bytes!`, so nothing is fetched at runtime.
+ *
+ * The subset deliberately has no CJK coverage; pass a different family through the text
+ * options when those are needed.
+ *
+ * Everything here is browser-only. Layout depends on the `TextMeasurer` interface alone, so
+ * unit tests keep running in plain Node, and the GPU tests inject their own rasteriser.
+ */
+import { type FontFace, type GlyphMetrics, type TextMeasurer, type VerticalMetrics } from "./text-layout.js";
+/**
+ * How a glyph is stored in the atlas, and therefore how the shader has to decode it.
+ *
+ * - `bitmap` keeps the anti-aliased coverage reference `FontAtlas` uses: RGB 255, coverage in alpha.
+ *   What was rasterised is what is drawn, and no amount of scaling can recover more edge detail.
+ * - `sdf` stores a signed distance in red. One channel means sharp corners round off, but the
+ *   fragment stage rebuilds the edge from the distance, so it stays sharp at any magnification.
+ * - `msdf` stores a per-edge signed distance in RGB. The extra channels preserve corners, at the
+ *   cost of three times the atlas area and a median — rather than a single — channel lookup.
+ *
+ * Both distance encodings put the *true* distance to the shape in alpha (msdfgen's `mtsdf` layout),
+ * which is what a block's outline reads: the median that preserves a corner cannot also place a
+ * ring around it. `bitmap` has no distance to give, so its outline is sampled instead.
+ */
+export type GlyphEncoding = "bitmap" | "sdf" | "msdf";
+/**
+ * Family name the bundled font is registered under. It is deliberately not `"Fira Mono"` so
+ * a locally installed face can never shadow the inlined one.
+ */
+export declare const DEFAULT_FONT_FAMILY = "vgpu-render-fira-mono";
+/** Decodes a base64 payload into bytes. Shared by the inlined font and the prebaked atlas. */
+export declare function decodeBase64Bytes(base64: string): Uint8Array<ArrayBuffer>;
+/** One inlined face of a multi-weight family: the weight it was built at, plus its WOFF2 bytes. */
+export type EmbeddedFontFace = {
+    readonly weight: number;
+    /** Base64 WOFF2, so the payload stays plain text and every toolchain can read it. */
+    readonly woff2Base64: string;
+};
+/**
+ * Registers a family whose weights are separate faces, each carrying its own `weight` descriptor.
+ *
+ * This is the only way to get more than one drawn weight out of Canvas2D: the font shorthand carries a
+ * single synthesised bold step, and `font-variation-settings` does not exist there, but the browser
+ * does select a face by the weight it was registered with. Registering the same family once per
+ * weight therefore turns `weight: 700` into a real bold face instead of an emboldened regular one.
+ *
+ * Idempotent per family, like `loadDefaultFont`, and browser-only.
+ */
+export declare function loadFontFaces(family: string, faces: readonly EmbeddedFontFace[]): Promise<void>;
+/** Decodes the inlined WOFF2 bytes of the bundled font, which is what `FontFace` takes. */
+export declare function decodeEmbeddedFont(): Uint8Array<ArrayBuffer>;
+/**
+ * Decodes the inlined TrueType bytes of the same subset. The outline-based encoders need this one:
+ * `opentype.js` reads glyph outlines, and it cannot decompress the WOFF2 container.
+ */
+export declare function decodeEmbeddedTrueTypeFont(): Uint8Array<ArrayBuffer>;
+/**
+ * Registers the bundled font with the document, once per page. Measuring or drawing with
+ * `DEFAULT_FONT_FAMILY` before this resolves falls back to another face, so await it before
+ * the first frame that draws text.
+ */
+export declare function loadDefaultFont(): Promise<void>;
+/** One rasterised character: the texels to pack plus the placement swash would have reported. */
+export type RasterizedGlyph = {
+    readonly width: number;
+    readonly height: number;
+    /**
+     * Tightly packed RGBA8 texels, `width * height * 4` bytes.
+     *
+     * The layout is the encoding's business rather than the atlas': the bitmap path writes a
+     * tintable alpha mask, and the distance-field paths write distances into the channels a shader
+     * knows how to decode. Keeping the encoding here means the atlas only packs and copies texels,
+     * which is what lets prebaked and on-demand glyph sources share one atlas.
+     */
+    readonly texels: Uint8Array;
+    /**
+     * The ink box inside those texels, which is up to a texel smaller than the image: the box is
+     * rounded up so no edge coverage is lost, and the atlas has to map only the ink part. Mapping the
+     * whole image would rescale the glyph by that fraction — invisible for interpolated coverage, but
+     * a visible slimming of every stem once a distance field reconstructs the edge.
+     */
+    readonly inkWidth: number;
+    readonly inkHeight: number;
+    readonly bearingLeft: number;
+    readonly bearingTop: number;
+    readonly advance: number;
+};
+/** Rasterises characters for the glyph atlas. */
+export interface GlyphRasterizer {
+    /** The encoding every glyph this source returns is written in. */
+    readonly encoding: GlyphEncoding;
+    /**
+     * Distance in atlas texels that a distance-field encoding covers either side of the edge, which
+     * the shader needs in order to decode it. Unused by `bitmap`.
+     */
+    readonly distanceRange?: number;
+    /**
+     * Default rasterisation scale for this source: a request that names no scale of its own is
+     * rasterised at `fontSize × rasterScale` texels while layout and quads stay in font pixels.
+     * Larger costs atlas area quadratically and keeps a magnified block from showing the texel grid
+     * its distance field was reconstructed from.
+     *
+     * It belongs to the source rather than to the renderer because two sources of the same encoding
+     * can coexist in one frame — which is exactly what a side-by-side quality comparison needs. The
+     * renderer overrides it per block with the size the block occupies on screen; see `text-raster`.
+     */
+    readonly rasterScale?: number;
+    /**
+     * Whether the source can rasterise at whatever size the renderer asks for.
+     *
+     * A source that reads outlines or a Canvas2D face can, so the renderer hands it the size the block
+     * covers on screen and the glyph stays sharp at every font size. A prebaked page cannot: its glyphs
+     * were rasterised once at a fixed size, so the renderer leaves it on `rasterScale` instead.
+     */
+    readonly dynamicRaster?: boolean;
+    /**
+     * Cache-key part for one face. The atlas keys glyphs by this plus the raster size, so a source that
+     * cannot change a face' axes reports just the parts it honours.
+     *
+     * The default keys on every axis (`fontFaceKey`). A source holding one fixed face — a prebaked page
+     * or a single parsed `opentype.js` buffer — overrides it so a weight the source cannot rasterise
+     * does not multiply identical atlas entries.
+     */
+    readonly faceKey?: (face: FontFace) => string;
+    /**
+     * Returns `undefined` for characters with no ink, such as whitespace.
+     *
+     * `rasterSize` is the size in texels the glyph is rasterised at, which is *not* the layout font
+     * size: the atlas asks for the size the glyph will cover on screen, so the same character stays
+     * sharp at any font size while still being rasterised once per size rung.
+     */
+    rasterize(character: string, face: FontFace, rasterSize: number): RasterizedGlyph | undefined;
+    /** Vertical metrics for a `fontSize`-sized instance of `face`. */
+    verticalMetrics(face: FontFace, fontSize: number): VerticalMetrics;
+}
+/**
+ * The CSS font shorthand that selects `face` at `fontSize`.
+ *
+ * Order follows the shorthand's grammar — style, weight, stretch, size, family — because Canvas2D
+ * parses the value as one. Two of the axes are conditional:
+ *
+ * - `font-stretch` keywords are only kept by the parser when the face has a `wdth` axis. A static
+ *   face drops the keyword and draws every stop identically, which is why the bundled subset cannot
+ *   show a `FontWidth` difference at all.
+ * - `italic` is the only slant Canvas2D keeps; `oblique <angle>` reads back as plain `italic`.
+ *
+ * A weight the loaded face does not carry is synthesised by the browser (one emboldened step, which
+ * keeps the advance), so `weight` at least changes what is drawn for the bundled static face.
+ */
+export declare function canvasFontString(face: FontFace, fontSize: number): string;
+/** Encodings Canvas2D coverage can produce directly. `msdf` needs outlines, not a mask. */
+export type CoverageEncoding = Exclude<GlyphEncoding, "msdf">;
+/**
+ * Canvas2D glyph source, doubling as the layout `TextMeasurer` so the canvas is only set up
+ * once per canvas-configured face and every `measureText` result is cached.
+ *
+ * Metrics follow Canvas2D's convention: the pen sits at the origin and the baseline is y = 0
+ * with y growing downwards. `actualBoundingBoxLeft` is a *leftward* distance, so a glyph that
+ * starts right of the pen reports a negative value — negating it yields the ink's left edge
+ * in pen space, which is what the atlas stores.
+ */
+export declare class CanvasGlyphRasterizer implements GlyphRasterizer, TextMeasurer {
+    #private;
+    readonly encoding: CoverageEncoding;
+    readonly distanceRange: number;
+    readonly rasterScale: number;
+    /**
+     * Whether the renderer drives this source's raster size from the size a block covers on screen.
+     * A Canvas2D face can be asked for any size, so it defaults to `true`; a source that needs a fixed
+     * raster — a pixel-accurate comparison against another renderer, say — turns it off.
+     */
+    readonly dynamicRaster: boolean;
+    constructor(options?: {
+        encoding?: CoverageEncoding;
+        distanceRange?: number;
+        rasterScale?: number;
+        dynamicRaster?: boolean;
+    });
+    verticalMetrics(face: FontFace, fontSize: number): VerticalMetrics;
+    glyphMetrics(character: string, face: FontFace, fontSize: number): GlyphMetrics;
+    rasterize(character: string, face: FontFace, rasterSize: number): RasterizedGlyph | undefined;
+}
+/** Packs Canvas2D coverage into the RGBA layout the chosen encoding expects. */
+export declare function encodeCoverage(coverage: Uint8Array, width: number, height: number, encoding: CoverageEncoding, range: number): Uint8Array;