vgpu-render 0.0.0-stage → 0.1.0

package/dist/text-font.js

@@ -0,0 +1,209 @@
+/**
+ * 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 { FIRA_MONO_MEDIUM_SUBSET_BASE64, FIRA_MONO_MEDIUM_SUBSET_TTF_BASE64 } from "./assets/fira-mono-medium-subset.js";
+import { coverageToSdf, DEFAULT_SDF_RANGE } from "./text-sdf.js";
+/**
+ * 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 const DEFAULT_FONT_FAMILY = "vgpu-render-fira-mono";
+/**
+ * Fira Mono's hhea metrics are 935 / -265 per 1000 upem, i.e. exactly the 1.2 em line box
+ * reference default `LineHeight` assumes. They are the fallback when a browser reports no font
+ * bounding box.
+ */
+const FALLBACK_ASCENT_RATIO = 0.935;
+const FALLBACK_DESCENT_RATIO = 0.265;
+const INITIAL_SURFACE_SIZE = 256;
+/** Decodes a base64 payload into bytes. Shared by the inlined font and the prebaked atlas. */
+export function decodeBase64Bytes(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index++)
+        bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}
+/** Decodes the inlined WOFF2 bytes of the bundled font, which is what `FontFace` takes. */
+export function decodeEmbeddedFont() {
+    return decodeBase64Bytes(FIRA_MONO_MEDIUM_SUBSET_BASE64);
+}
+/**
+ * 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 function decodeEmbeddedTrueTypeFont() {
+    return decodeBase64Bytes(FIRA_MONO_MEDIUM_SUBSET_TTF_BASE64);
+}
+let defaultFont;
+/**
+ * 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 function loadDefaultFont() {
+    defaultFont ??= registerDefaultFont();
+    return defaultFont;
+}
+async function registerDefaultFont() {
+    const fonts = typeof document === "undefined" ? undefined : document.fonts;
+    if (fonts === undefined || typeof FontFace === "undefined") {
+        throw new Error("loading the bundled text font requires a browser environment");
+    }
+    const face = new FontFace(DEFAULT_FONT_FAMILY, decodeEmbeddedFont());
+    await face.load();
+    fonts.add(face);
+}
+/**
+ * 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 class CanvasGlyphRasterizer {
+    encoding;
+    distanceRange;
+    rasterScale;
+    /**
+     * 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.
+     */
+    dynamicRaster;
+    #surface;
+    #metrics = new Map();
+    #vertical = new Map();
+    constructor(options = {}) {
+        this.encoding = options.encoding ?? "bitmap";
+        this.distanceRange = options.distanceRange ?? DEFAULT_SDF_RANGE;
+        this.rasterScale = options.rasterScale ?? 1;
+        this.dynamicRaster = options.dynamicRaster ?? true;
+    }
+    #ensureSurface() {
+        if (this.#surface === undefined) {
+            if (typeof document === "undefined") {
+                throw new Error("glyph rasterisation requires a browser environment");
+            }
+            const canvas = document.createElement("canvas");
+            canvas.width = INITIAL_SURFACE_SIZE;
+            canvas.height = INITIAL_SURFACE_SIZE;
+            const context = canvas.getContext("2d", { willReadFrequently: true });
+            if (context === null)
+                throw new Error("a 2D canvas context is required to rasterise glyphs");
+            this.#surface = { canvas, context };
+        }
+        return this.#surface;
+    }
+    #font(fontFamily, fontSize) {
+        return `${fontSize}px "${fontFamily}"`;
+    }
+    verticalMetrics(fontFamily, fontSize) {
+        const key = `${fontFamily}|${fontSize}`;
+        const cached = this.#vertical.get(key);
+        if (cached !== undefined)
+            return cached;
+        const context = this.#ensureSurface().context;
+        context.font = this.#font(fontFamily, fontSize);
+        const metrics = context.measureText("M");
+        const ascent = metrics.fontBoundingBoxAscent > 0 ? metrics.fontBoundingBoxAscent : fontSize * FALLBACK_ASCENT_RATIO;
+        const descent = metrics.fontBoundingBoxDescent > 0 ? metrics.fontBoundingBoxDescent : fontSize * FALLBACK_DESCENT_RATIO;
+        const value = { ascent, descent };
+        this.#vertical.set(key, value);
+        return value;
+    }
+    glyphMetrics(character, fontFamily, fontSize) {
+        const key = `${fontFamily}|${fontSize}|${character}`;
+        const cached = this.#metrics.get(key);
+        if (cached !== undefined)
+            return cached;
+        const context = this.#ensureSurface().context;
+        context.font = this.#font(fontFamily, fontSize);
+        const metrics = context.measureText(character);
+        const bearingLeft = -metrics.actualBoundingBoxLeft;
+        const value = {
+            advance: metrics.width,
+            width: metrics.actualBoundingBoxRight - bearingLeft,
+            height: metrics.actualBoundingBoxAscent + metrics.actualBoundingBoxDescent,
+            bearingLeft,
+            bearingTop: -metrics.actualBoundingBoxAscent,
+        };
+        this.#metrics.set(key, value);
+        return value;
+    }
+    rasterize(character, fontFamily, rasterSize) {
+        // The raster size *is* the face size here: `measureText` and the fill both work in the texels the
+        // atlas will store, and the layout's own measurements never pass through this path.
+        const glyph = this.glyphMetrics(character, fontFamily, rasterSize);
+        if (!(glyph.width > 0) || !(glyph.height > 0))
+            return undefined;
+        // The ink box is fractional; the mask rounds up so no edge pixel is lost.
+        const width = Math.max(1, Math.ceil(glyph.width));
+        const height = Math.max(1, Math.ceil(glyph.height));
+        const { canvas, context } = this.#ensureSurface();
+        if (canvas.width < width || canvas.height < height) {
+            canvas.width = Math.max(canvas.width, width);
+            canvas.height = Math.max(canvas.height, height);
+        }
+        context.clearRect(0, 0, width, height);
+        context.font = this.#font(fontFamily, rasterSize);
+        context.textAlign = "left";
+        context.textBaseline = "alphabetic";
+        context.fillStyle = "#fff";
+        // Place the pen so the ink box starts at (0, 0): the baseline sits `-bearingTop` down.
+        context.fillText(character, -glyph.bearingLeft, -glyph.bearingTop);
+        const pixels = context.getImageData(0, 0, width, height).data;
+        const coverage = new Uint8Array(width * height);
+        for (let index = 0; index < coverage.length; index++)
+            coverage[index] = pixels[index * 4 + 3];
+        return {
+            width,
+            height,
+            texels: encodeCoverage(coverage, width, height, this.encoding, this.distanceRange),
+            inkWidth: glyph.width,
+            inkHeight: glyph.height,
+            bearingLeft: glyph.bearingLeft,
+            bearingTop: glyph.bearingTop,
+            advance: glyph.advance,
+        };
+    }
+}
+/** Packs Canvas2D coverage into the RGBA layout the chosen encoding expects. */
+export function encodeCoverage(coverage, width, height, encoding, range) {
+    const texels = new Uint8Array(coverage.length * 4);
+    if (encoding === "bitmap") {
+        // A tintable alpha mask: RGB stays 255 so the shader can colour it.
+        for (let index = 0; index < coverage.length; index++) {
+            const target = index * 4;
+            texels[target] = 255;
+            texels[target + 1] = 255;
+            texels[target + 2] = 255;
+            texels[target + 3] = coverage[index];
+        }
+        return texels;
+    }
+    // A signed distance in red, and the same distance in alpha so the shader can outline the glyph.
+    // It comes from the mask's coverage rather than from the outline, which makes it a little coarser
+    // than the msdf encoder's — fine for a ring, not what the edge itself is rebuilt from.
+    const field = coverageToSdf(coverage, width, height, range);
+    for (let index = 0; index < field.length; index++) {
+        const target = index * 4;
+        texels[target] = field[index];
+        texels[target + 3] = field[index];
+    }
+    return texels;
+}

package/dist/text-layout.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Text layout for the debug text renderer.
+ *
+ * Ported from reference `TextPipeline::update_text_layout_info`
+ * (`the reference implementation`): a text block is wrapped to its `TextBounds`, split
+ * into lines, justified, and turned into one positioned glyph per character. Each glyph
+ * carries its ink box and resolved colour, which is what the GPU pass later instantiates as
+ * a quad.
+ *
+ * Two deliberate differences from reference:
+ *
+ * - There is no shaping. Characters advance one at a time and never form ligatures or
+ *   reorder runs, which suits the monospaced debug font the library bundles.
+ * - Every metric comes from an injected `TextMeasurer`. reference reads parley and swash here;
+ *   staying behind an interface keeps this module free of browser APIs and unit-testable in
+ *   plain Node, and it is also the seam the GPU tests use to feed synthetic glyphs.
+ *
+ * Layout happens in one local space: origin at the block's anchor point, x to the right and
+ * **y down**, matching Canvas2D. The renderer flips y for spaces where up is +y.
+ */
+export type Rgba = readonly [number, number, number, number];
+/** Vertical font metrics, in the same units as the font size the measurer was asked for. */
+export type VerticalMetrics = {
+    readonly ascent: number;
+    readonly descent: number;
+};
+/**
+ * Per-character metrics, mirroring the `Placement` swash reports to reference: an advance along
+ * the baseline plus the ink box relative to the pen.
+ */
+export type GlyphMetrics = {
+    /** Pen advance for this character. */
+    readonly advance: number;
+    /** Ink box width. Zero for whitespace. */
+    readonly width: number;
+    /** Ink box height. Zero for whitespace. */
+    readonly height: number;
+    /** Ink box left edge relative to the pen, y down: positive moves right. */
+    readonly bearingLeft: number;
+    /** Ink box top edge relative to the baseline, y down: positive is below the baseline. */
+    readonly bearingTop: number;
+};
+/** Source of glyph metrics. The browser implementation measures through Canvas2D. */
+export interface TextMeasurer {
+    /** Vertical metrics for a `fontSize`-sized face of `fontFamily`. */
+    verticalMetrics(fontFamily: string, fontSize: number): VerticalMetrics;
+    /** Metrics for one character. Whitespace returns a zero-size ink box. */
+    glyphMetrics(character: string, fontFamily: string, fontSize: number): GlyphMetrics;
+}
+/** Reference `Justify`. `start`/`end` resolve to left/right in this LTR-only layout. */
+export type TextJustify = "left" | "center" | "right" | "justified" | "start" | "end";
+/** Reference `LineBreak`, minus the Unicode-correct word segmentation reference gets from parley. */
+export type TextLineBreak = "word" | "character" | "word-or-character" | "none";
+/** Normalized anchor: x 0 = left, 1 = right; y 0 = top, 1 = bottom (local y grows down). */
+export type TextAnchorPoint = readonly [number, number];
+/** Reference `Anchor` presets, named for the block corner that lands on the position. */
+export type TextAnchor = "center" | "top-left" | "top-center" | "top-right" | "center-left" | "center-right" | "bottom-left" | "bottom-center" | "bottom-right";
+export declare function resolveTextAnchor(anchor: TextAnchor): TextAnchorPoint;
+/** One section of a text block, the equivalent of a reference `TextSpan`. */
+export type TextSpanInput = {
+    readonly text: string;
+    readonly color?: Rgba;
+    readonly fontSize?: number;
+    readonly fontFamily?: string;
+};
+/** reference `LineHeight` default, `RelativeToFont(1.2)`. */
+export declare const DEFAULT_LINE_HEIGHT_SCALE = 1.2;
+export type TextLayoutOptions = {
+    readonly color: Rgba;
+    readonly fontSize: number;
+    readonly fontFamily: string;
+    /**
+     * Absolute line height in layout units, reference `LineHeight::Px`. When omitted the line height
+     * is `lineHeightScale` times the line's own largest font size, which is reference
+     * `LineHeight::RelativeToFont` — the default, and the reason a line holding a larger span gets
+     * a taller box rather than being clipped to the block's own size.
+     */
+    readonly lineHeight?: number | undefined;
+    /** Multiple of the line's largest font size, reference `LineHeight::RelativeToFont`. Default `1.2`. */
+    readonly lineHeightScale?: number | undefined;
+    /**
+     * Added after every character, the last one on a line included: parley adds it to each cluster's
+     * advance, and the trailing whitespace a line breaks at carries its share into the block width.
+     */
+    readonly letterSpacing: number;
+    readonly justify: TextJustify;
+    readonly lineBreak: TextLineBreak;
+    /**
+     * `TextBounds`. Only `width` feeds layout: it is the wrap width. `height` is not a layout input,
+     * matching reference, whose `Text2d` never truncates lines against it (it only sizes the node).
+     */
+    readonly bounds?: readonly [number, number] | undefined;
+    readonly anchor: TextAnchorPoint;
+};
+/** One laid-out glyph, ready to become an instance once its atlas rectangle is known. */
+export type PositionedGlyph = {
+    readonly character: string;
+    readonly fontFamily: string;
+    readonly fontSize: number;
+    readonly color: Rgba;
+    /** Ink box centre relative to the block's anchor point, y down. */
+    readonly center: readonly [number, number];
+    readonly width: number;
+    readonly height: number;
+};
+export type TextLayoutResult = {
+    readonly glyphs: readonly PositionedGlyph[];
+    /** Block size before the anchor offset is applied. */
+    readonly size: readonly [number, number];
+    readonly lineCount: number;
+};
+/**
+ * Lays out one text block. `options.anchor` decides which part of the block lands on the
+ * position the renderer is given; the returned glyph centres are already offset for it.
+ */
+export declare function layoutText(spans: readonly TextSpanInput[], options: TextLayoutOptions, measurer: TextMeasurer): TextLayoutResult;

package/dist/text-layout.js

@@ -0,0 +1,340 @@
+/**
+ * Text layout for the debug text renderer.
+ *
+ * Ported from reference `TextPipeline::update_text_layout_info`
+ * (`the reference implementation`): a text block is wrapped to its `TextBounds`, split
+ * into lines, justified, and turned into one positioned glyph per character. Each glyph
+ * carries its ink box and resolved colour, which is what the GPU pass later instantiates as
+ * a quad.
+ *
+ * Two deliberate differences from reference:
+ *
+ * - There is no shaping. Characters advance one at a time and never form ligatures or
+ *   reorder runs, which suits the monospaced debug font the library bundles.
+ * - Every metric comes from an injected `TextMeasurer`. reference reads parley and swash here;
+ *   staying behind an interface keeps this module free of browser APIs and unit-testable in
+ *   plain Node, and it is also the seam the GPU tests use to feed synthetic glyphs.
+ *
+ * Layout happens in one local space: origin at the block's anchor point, x to the right and
+ * **y down**, matching Canvas2D. The renderer flips y for spaces where up is +y.
+ */
+const TEXT_ANCHORS = {
+    center: [0.5, 0.5],
+    "top-left": [0, 0],
+    "top-center": [0.5, 0],
+    "top-right": [1, 0],
+    "center-left": [0, 0.5],
+    "center-right": [1, 0.5],
+    "bottom-left": [0, 1],
+    "bottom-center": [0.5, 1],
+    "bottom-right": [1, 1],
+};
+export function resolveTextAnchor(anchor) {
+    const point = TEXT_ANCHORS[anchor];
+    if (point === undefined) {
+        throw new RangeError(`unknown text anchor "${anchor}"`);
+    }
+    return point;
+}
+/** reference `LineHeight` default, `RelativeToFont(1.2)`. */
+export const DEFAULT_LINE_HEIGHT_SCALE = 1.2;
+function isWhitespace(character) {
+    return character === " " || character === "\t";
+}
+/**
+ * Characters that break between themselves rather than at spaces.
+ *
+ * UAX #14 calls these classes ID (ideographic) and the punctuation around them. Without this a whole
+ * Chinese sentence arrives as one word token, so `word` breaking can only move it as a block and a
+ * bounded block overflows its bounds instead of wrapping.
+ */
+function isCjkCharacter(character) {
+    const code = character.codePointAt(0) ?? 0;
+    return ((code >= 0x2e80 && code <= 0x303f) || // CJK radicals, symbols and punctuation
+        (code >= 0x3040 && code <= 0x30ff) || // hiragana, katakana
+        (code >= 0x3400 && code <= 0x4dbf) || // CJK unified ideographs extension A
+        (code >= 0x4e00 && code <= 0x9fff) || // CJK unified ideographs
+        (code >= 0xf900 && code <= 0xfaff) || // CJK compatibility ideographs
+        (code >= 0xff00 && code <= 0xffef) || // full-width forms
+        (code >= 0xac00 && code <= 0xd7af) || // hangul syllables
+        (code >= 0x20000 && code <= 0x3ffff) // extensions B and beyond
+    );
+}
+/**
+ * Kinsoku (禁则) sets: punctuation that may not open a line, and brackets that may not close one.
+ *
+ * The line breaker only knows how to move a token, so the rule is expressed by gluing the character
+ * to its neighbour instead: a closing mark joins the run before it, an opening mark the run after.
+ */
+const NO_LINE_START = new Set([
+    ",", ".", "!", "?", ":", ";", ")", "]", "}", ".", ")", "]", "}", "%",
+    "\u3001", "\u3002", "\uff0c", "\uff0e", "\uff01", "\uff1f", "\uff1a", "\uff1b", "\uff09", "\uff3d", "\uff5d", "\uff05",
+    "\u300d", "\u300f", "\u3011", "\u300b", "\u3009", "\u3015", "\u2019", "\u201d",
+]);
+const NO_LINE_END = new Set(["(", "[", "{", "\uff08", "\uff3b", "\uff5b", "\u300c", "\u300e", "\u3010", "\u300a", "\u3008", "\u3014", "\u2018", "\u201c"]);
+/** Appends one character to the token that is already open, or starts a new one. */
+function glueToLastToken(tokens, character) {
+    const last = tokens[tokens.length - 1];
+    if (last === undefined || last.kind === "break") {
+        tokens.push({ kind: "word", characters: [character] });
+        return;
+    }
+    tokens[tokens.length - 1] = { kind: last.kind, characters: [...last.characters, character] };
+}
+/** Splits the flattened block into word / spaces / hard-break tokens. */
+function tokenize(items) {
+    const tokens = [];
+    let current = [];
+    let kind;
+    const flush = () => {
+        if (kind !== undefined && current.length > 0)
+            tokens.push({ kind, characters: current });
+        current = [];
+        kind = undefined;
+    };
+    for (const item of items) {
+        if (item.character === "\n") {
+            flush();
+            tokens.push({ kind: "break", characters: [] });
+            continue;
+        }
+        // CJK text carries no spaces to break at, so each ideograph becomes its own token and the greedy
+        // breaker can wrap between any two of them. Kinsoku is applied here rather than in the breaker
+        // because it can only move a whole token: a mark that may not open a line is glued to the run it
+        // belongs to, and one that may not close a line to the character that follows it.
+        if (!item.isSpace && isCjkCharacter(item.character)) {
+            const previous = current[current.length - 1] ?? tokens[tokens.length - 1]?.characters.at(-1);
+            const glue = previous !== undefined && (NO_LINE_START.has(item.character) || NO_LINE_END.has(previous.character));
+            if (glue) {
+                if (current.length > 0)
+                    current.push(item);
+                else
+                    glueToLastToken(tokens, item);
+                kind = "word";
+                continue;
+            }
+            flush();
+            tokens.push({ kind: "word", characters: [item] });
+            continue;
+        }
+        const next = item.isSpace ? "space" : "word";
+        if (kind !== undefined && next !== kind)
+            flush();
+        kind = next;
+        current.push(item);
+    }
+    flush();
+    return tokens;
+}
+/** Advance of a run. `letterSpacing` lands after every character, the last one included. */
+function runWidth(characters, letterSpacing) {
+    let width = 0;
+    for (const character of characters)
+        width += character.advance + letterSpacing;
+    return width;
+}
+/** Measures one broken line into the two advances and the line box size reference works from. */
+function measureLine(characters, letterSpacing) {
+    // UAX #14 never leaves a space at the start of a line, and the breakers reference runs drop it there.
+    let start = 0;
+    while (start < characters.length && characters[start].isSpace)
+        start++;
+    const content = start === 0 ? characters : characters.slice(start);
+    let end = content.length;
+    while (end > 0 && content[end - 1].isSpace)
+        end--;
+    let fontSize = 0;
+    for (const character of content)
+        fontSize = Math.max(fontSize, character.fontSize);
+    return {
+        characters: content.slice(0, end),
+        advance: runWidth(content.slice(0, end), letterSpacing),
+        fullAdvance: runWidth(content, letterSpacing),
+        fontSize,
+        isEmpty: content.length === 0,
+    };
+}
+/** Splits a word token one character at a time, the fallback for `word-or-character`. */
+function splitCharacters(token) {
+    return token.characters.map((character) => ({ kind: "word", characters: [character] }));
+}
+/**
+ * Greedy line breaker. Words move whole to the next line when they no longer fit, matching
+ * reference `LineBreak::WordBoundary`; `character` strategies hand single characters to the same
+ * loop, and `none` only honours explicit newlines.
+ */
+function breakLines(tokens, maxWidth, lineBreak, letterSpacing) {
+    const lines = [];
+    let line = [];
+    const pushLine = () => {
+        lines.push(line);
+        line = [];
+    };
+    const addCharacters = (characters) => {
+        for (const character of characters) {
+            if (maxWidth !== undefined && line.length > 0 && lineWidth(line, letterSpacing) + character.advance + letterSpacing > maxWidth) {
+                // The space a line breaks at stays on that line as trailing whitespace — it may even take the
+                // line past its bounds, which is why a bounded block can report a wider width. Carrying it to
+                // the next line instead would push the following characters right by one space.
+                if (character.isSpace)
+                    line.push(character);
+                lines.push(line);
+                line = [];
+                if (character.isSpace)
+                    continue;
+            }
+            line.push(character);
+        }
+    };
+    for (const token of tokens) {
+        if (token.kind === "break") {
+            pushLine();
+            continue;
+        }
+        if (maxWidth === undefined || lineBreak === "none") {
+            line.push(...token.characters);
+            continue;
+        }
+        if (lineBreak === "character") {
+            addCharacters(token.characters);
+            continue;
+        }
+        const width = lineWidth(line, letterSpacing) + runWidth(token.characters, letterSpacing);
+        const fits = width <= maxWidth || lineWidth(line, letterSpacing) === 0;
+        if (fits) {
+            line.push(...token.characters);
+            continue;
+        }
+        if (token.kind === "space") {
+            // A space that no longer fits ends the line and belongs to it, as the trailing whitespace
+            // parley keeps for its width even though it is not drawn.
+            line.push(...token.characters);
+            lines.push(line);
+            line = [];
+            continue;
+        }
+        // A word too wide for an empty line falls back to per-character breaking.
+        lines.push(line);
+        line = [];
+        const splittable = lineBreak === "word-or-character" || runWidth(token.characters, letterSpacing) > maxWidth;
+        if (splittable)
+            addCharacters(token.characters);
+        else
+            line.push(...token.characters);
+    }
+    pushLine();
+    return lines.map((characters) => measureLine(characters, letterSpacing));
+}
+function lineWidth(characters, letterSpacing) {
+    return runWidth(characters, letterSpacing);
+}
+function countSpaces(characters) {
+    let count = 0;
+    for (const character of characters)
+        if (character.isSpace)
+            count++;
+    return count;
+}
+/**
+ * Lays out one text block. `options.anchor` decides which part of the block lands on the
+ * position the renderer is given; the returned glyph centres are already offset for it.
+ */
+export function layoutText(spans, options, measurer) {
+    const items = [];
+    for (const span of spans) {
+        const fontSize = span.fontSize ?? options.fontSize;
+        const fontFamily = span.fontFamily ?? options.fontFamily;
+        const color = span.color ?? options.color;
+        // Iterating the string yields code points, so surrogate pairs stay whole.
+        for (const character of span.text) {
+            if (character === "\n") {
+                items.push({ character, fontFamily, fontSize, color, advance: 0, width: 0, height: 0, bearingLeft: 0, bearingTop: 0, isSpace: false });
+                continue;
+            }
+            const metrics = measurer.glyphMetrics(character, fontFamily, fontSize);
+            items.push({
+                character,
+                fontFamily,
+                fontSize,
+                color,
+                advance: metrics.advance,
+                width: metrics.width,
+                height: metrics.height,
+                bearingLeft: metrics.bearingLeft,
+                bearingTop: metrics.bearingTop,
+                isSpace: isWhitespace(character),
+            });
+        }
+    }
+    const maxWidth = options.bounds?.[0];
+    const lines = breakLines(tokenize(items), maxWidth, options.lineBreak, options.letterSpacing);
+    // reference resolves the line box per line, from that line's own largest run: a relative
+    // `LineHeight` multiplies the run's size, so a line holding a larger span grows its box
+    // instead of being held to the block's default size.
+    const boxes = lines.map((line) => {
+        const fontSize = line.fontSize > 0 ? line.fontSize : options.fontSize;
+        const base = measurer.verticalMetrics(options.fontFamily, fontSize);
+        const height = options.lineHeight ?? (options.lineHeightScale ?? DEFAULT_LINE_HEIGHT_SCALE) * fontSize;
+        return { base, height, halfLeading: (height - (base.ascent + base.descent)) / 2 };
+    });
+    // The block is what reference reports and anchors on: `Layout::full_width`, which keeps the
+    // whitespace each line broke at, over the summed line boxes. Both are rounded up.
+    const blockWidth = Math.ceil(lines.reduce((widest, line) => Math.max(widest, line.fullAdvance), 0));
+    let blockHeight = boxes.reduce((sum, box) => sum + box.height, 0);
+    // parley leaves a trailing empty line's box out of the layout height.
+    if (lines.length > 1 && lines[lines.length - 1].isEmpty)
+        blockHeight -= boxes[boxes.length - 1].height;
+    blockHeight = Math.ceil(blockHeight);
+    const offsetX = -options.anchor[0] * blockWidth;
+    const offsetY = -options.anchor[1] * blockHeight;
+    // `Alignment` works inside parley's `max_advance`: the bounds width when bounded, otherwise the
+    // widest line. That is a smaller box than `full_width` whenever a line breaks at a space.
+    const alignBox = maxWidth ?? lines.reduce((widest, line) => Math.max(widest, line.advance), 0);
+    const glyphs = [];
+    let penY = 0;
+    for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+        const line = lines[lineIndex];
+        const box = boxes[lineIndex];
+        const isLastLine = lineIndex === lines.length - 1;
+        let penX = alignPenX(options.justify, line.advance, alignBox);
+        let stretch = 0;
+        if (options.justify === "justified" && !isLastLine && maxWidth !== undefined) {
+            const spaces = countSpaces(line.characters);
+            if (spaces > 0 && alignBox > line.advance) {
+                stretch = (alignBox - line.advance) / spaces;
+                penX = 0;
+            }
+        }
+        const baseline = penY + box.halfLeading + box.base.ascent;
+        for (const character of line.characters) {
+            if (character.width > 0 && character.height > 0) {
+                glyphs.push({
+                    character: character.character,
+                    fontFamily: character.fontFamily,
+                    fontSize: character.fontSize,
+                    color: character.color,
+                    center: [offsetX + penX + character.bearingLeft + character.width / 2, offsetY + baseline + character.bearingTop + character.height / 2],
+                    width: character.width,
+                    height: character.height,
+                });
+            }
+            penX += character.advance + options.letterSpacing;
+            if (character.isSpace)
+                penX += stretch;
+        }
+        penY += box.height;
+    }
+    return { glyphs, size: [blockWidth, blockHeight], lineCount: lines.length };
+}
+/** Reference `Justify` → the pen offset for one line inside the box `Alignment` gets. */
+function alignPenX(justify, lineWidth, box) {
+    switch (justify) {
+        case "center":
+            return (box - lineWidth) / 2;
+        case "right":
+        case "end":
+            return box - lineWidth;
+        default:
+            return 0;
+    }
+}