Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

28.3 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    ui/text/layout.ts
 * @brief   Pure text layout + glyph-quad vertex building for the SDF text path
 *          (TS-centric). Given the glyph atlas (which supplies
 *          per-glyph atlas UVs + metrics), turn a string into positioned quads
 *          and then into the interleaved vertex/index buffers `submitTextBatch`
 *          expects. No Canvas/GL here, so it is fully unit-testable.
 *
 * Conventions: local space, baseline at y = 0, y-up (glyph tops are positive y);
 * positions are pre-transform (the entity world matrix is applied at submit).
 * Glyph metrics from the atlas are in renderSize px; everything scales by
 * displaySize / atlas.renderSize (SDF is resolution-independent).
 */
import type { GlyphAtlas, GlyphEntry } from './glyph-atlas';
import { TEXT_VERTEX_FLOATS } from './submit';
import { parseRichText, type TextSegment, type ImageSegment, type RichTextRun } from './rich-text-parser';
import { UI_TEXT_BOLD, UI_TEXT_ITALIC } from './text-transform';
import { TextAlign, TextOverflow } from '../core/text';

export interface TextLayoutOptions {
    /** Display font size in px. */
    fontSizePx: number;
    /** Extra advance between glyphs, in display px. */
    letterSpacing?: number;
}

/** RGBA color, channels in [0,1]. */
export type RGBA = readonly [number, number, number, number];

/** One positioned glyph quad: atlas UVs + local-space corners (y-up). `color` is
 *  set only by rich text (per-run); single-style layout leaves it for the caller. */
export interface LaidGlyph {
    u0: number; v0: number; u1: number; v1: number;
    x0: number; y0: number; // bottom-left
    x1: number; y1: number; // top-right
    pageId: number;
    color?: RGBA;
    /** The atlas entry the quad was cut from — what an outline of the glyph is grown from. */
    entry?: GlyphEntry;
}

/** One placed inline `<img>` run: a box in the same local space as glyphs
 *  (y-up; (x,y) is the bottom-left corner). `src` is the image reference the
 *  renderer resolves to a texture; `tint` recolors it (null = untinted). */
export interface LaidImage {
    src: string;
    x: number;
    y: number;
    w: number;
    h: number;
    tint: RGBA | null;
}

/** Where one laid-out line sits: its left edge and width, and the baseline, in the same y-up local space as the glyphs. */
export interface LaidLine {
    x: number;
    width: number;
    baseline: number;
}

export interface TextLayout {
    glyphs: LaidGlyph[];
    /** Each line's extent, top to bottom. Undefined for a layout that is a single line laid out on its own. */
    lines?: LaidLine[];
    /** Inline `<img>` placements (rich text only). Undefined/empty = none. */
    images?: LaidImage[];
    /** Total pen advance (display px). */
    width: number;
    /** Line height (display px). */
    lineHeight: number;
    /** The font size the text was laid out at, when that is not the one asked for ({@link TextOverflow.Shrink}). */
    fontSizePx?: number;
}

/**
 * Lay out a single line of text against the atlas. Glyphs missing from the
 * atlas (unproducible) are skipped; whitespace advances the pen without a quad.
 */
export function layoutLine(
    text: string,
    atlas: GlyphAtlas,
    fontFamily: string,
    opts: TextLayoutOptions,
    style = 0,
): TextLayout {
    const pixelSize = atlas.pixelSizeFor(opts.fontSizePx, fontFamily);
    const scale = opts.fontSizePx / pixelSize;
    const spacing = opts.letterSpacing ?? 0;
    const glyphs: LaidGlyph[] = [];
    let penX = 0;

    for (const ch of text) {
        const cp = ch.codePointAt(0);
        if (cp === undefined) continue;
        const g = atlas.getGlyph(cp, fontFamily, style, pixelSize);
        if (!g) continue;

        if (g.width > 0 && g.height > 0) {
            const x0 = penX + g.bearingX * scale;
            const y1 = g.bearingY * scale;            // top, above baseline
            const x1 = x0 + g.width * scale;
            const y0 = y1 - g.height * scale;          // bottom
            glyphs.push({ u0: g.u0, v0: g.v0, u1: g.u1, v1: g.v1, x0, y0, x1, y1, pageId: g.pageId, entry: g });
        }
        penX += g.advance * scale + spacing;
    }

    return { glyphs, width: penX, lineHeight: opts.fontSizePx };
}

export interface GlyphVertexData {
    vertices: Float32Array; // TEXT_VERTEX_FLOATS per vertex, 4 verts/glyph
    indices: Uint16Array;   // 6 per glyph
}

/** Four vertices per glyph must fit the text-submit ABI's Uint16 indices. */
export const MAX_TEXT_BATCH_GLYPHS = 0x10000 / 4;

/**
 * Build interleaved glyph vertices and indices, with atlas v0 at screen-top.
 * `originX/Y` positions the batch inside its text box. Disable per-glyph colors
 * when recoloring shadow and outline passes.
 */
export function buildGlyphVertices(
    glyphs: readonly LaidGlyph[],
    color: RGBA,
    originX = 0,
    originY = 0,
    sdfBias = 0,
    useGlyphColors = true,
): GlyphVertexData {
    const n = glyphs.length;
    if (n > MAX_TEXT_BATCH_GLYPHS) throw new RangeError('Glyph batch exceeds the Uint16 index range; split it before tessellation');
    const vertices = new Float32Array(n * 4 * TEXT_VERTEX_FLOATS);
    const indices = new Uint16Array(n * 6);

    for (let i = 0; i < n; i++) {
        const gl = glyphs[i];
        const [r, g, b, a] = (useGlyphColors ? gl.color : undefined) ?? color;
        const x0 = gl.x0 + originX, x1 = gl.x1 + originX;
        const y0 = gl.y0 + originY, y1 = gl.y1 + originY;
        const vo = i * 4 * TEXT_VERTEX_FLOATS;
        // BL, BR, TR, TL — UV V uses v1 at the bottom, v0 at the top.
        writeVertex(vertices, vo + 0 * TEXT_VERTEX_FLOATS, x0, y0, gl.u0, gl.v1, r, g, b, a, sdfBias);
        writeVertex(vertices, vo + 1 * TEXT_VERTEX_FLOATS, x1, y0, gl.u1, gl.v1, r, g, b, a, sdfBias);
        writeVertex(vertices, vo + 2 * TEXT_VERTEX_FLOATS, x1, y1, gl.u1, gl.v0, r, g, b, a, sdfBias);
        writeVertex(vertices, vo + 3 * TEXT_VERTEX_FLOATS, x0, y1, gl.u0, gl.v0, r, g, b, a, sdfBias);

        const io = i * 6, vb = i * 4;
        indices[io] = vb; indices[io + 1] = vb + 1; indices[io + 2] = vb + 2;
        indices[io + 3] = vb; indices[io + 4] = vb + 2; indices[io + 5] = vb + 3;
    }

    return { vertices, indices };
}

function writeVertex(
    out: Float32Array, o: number,
    x: number, y: number, u: number, v: number,
    r: number, g: number, b: number, a: number, sdfBias: number,
): void {
    out[o] = x; out[o + 1] = y; out[o + 2] = u; out[o + 3] = v;
    out[o + 4] = r; out[o + 5] = g; out[o + 6] = b; out[o + 7] = a;
    out[o + 8] = sdfBias;
}

export interface RichTextLayoutOptions extends TextLayoutOptions {
    /** Base color for runs that don't set their own <color=...>. */
    color: RGBA;
}

/** Horizontal alignment: 0 = left, 1 = center, 2 = right. */
export const TEXT_ALIGN_LEFT = 0;
export const TEXT_ALIGN_CENTER = 1;
export const TEXT_ALIGN_RIGHT = 2;

export interface MultilineTextOptions extends TextLayoutOptions {
    /** Baseline-to-baseline distance in px. Default fontSizePx * 1.2. */
    lineHeight?: number;
    /** Horizontal alignment, defaulting to left. */
    align?: TextAlign;
    /** Parse rich markup (`<b>` etc.) per line. */
    rich?: boolean;
    /** Base color (used by rich runs without their own color). */
    color?: RGBA;
    /** Word-wrap width in display px (plain and rich text). 0/undefined = no wrap. */
    maxWidth?: number;
    /**
     * Width (display px) each line is horizontally aligned within — the layout box.
     * Defaults to `maxWidth`, else the widest line. Separating it from `maxWidth` lets
     * horizontal align work inside a fixed box even when word-wrap is off.
     */
    boxWidth?: number;
    /** Height (display px) of the layout box, for {@link overflow}. 0/undefined =
     *  no box, so nothing can overflow one. */
    boxHeight?: number;
    /**
     * What a run too big for the box does. Needs `boxHeight` to drop lines and a
     * width to trim one. The component's own spelling, not a mirror of it: three
     * numbers written twice are two answers the day somebody reorders them.
     */
    overflow?: TextOverflow;
}

/** The character appended to a line the ellipsis mode cut. */
const ELLIPSIS = '\u2026';

/** Trim at codepoint boundaries using shared prefix advances, including the mark. */
function truncateLine(
    line: string, measure: (s: string) => number, limit: number, ellipsis: boolean,
    measurePrefixes: (s: string) => readonly number[],
): string {
    if (limit <= 0 || measure(line) <= limit) return line;
    const tail = ellipsis ? ELLIPSIS : '';
    const tailWidth = measure(tail);
    const widths = measurePrefixes(line);
    const chars = [...line];
    const ends = [0];
    for (const ch of chars) ends.push(ends[ends.length - 1]! + ch.length);
    for (let count = chars.length - 1; count >= 0; count--) {
        while (count > 0 && chars[count - 1]!.trimEnd() === '') count--;
        const end = ends[count]!;
        if (widths[end]! + tailWidth <= limit) return line.slice(0, end) + tail;
    }
    return tail;
}

/** Sum of glyph advances for a string at the given size (display px). Pure. */
export function measureWidth(
    text: string, atlas: GlyphAtlas, fontFamily: string, fontSizePx: number, style: number, letterSpacing = 0,
): number {
    const pixelSize = atlas.pixelSizeFor(fontSizePx, fontFamily);
    const scale = fontSizePx / pixelSize;
    let w = 0;
    for (const ch of text) {
        const cp = ch.codePointAt(0);
        if (cp === undefined) continue;
        const g = atlas.getGlyph(cp, fontFamily, style, pixelSize);
        if (g) w += g.advance * scale + letterSpacing;
    }
    return w;
}

/** UTF-16 prefix widths for caret placement, measured in one pass. */
export function measurePrefixWidths(
    text: string, atlas: GlyphAtlas, fontFamily: string, fontSizePx: number, style: number, letterSpacing = 0,
): number[] {
    const pixelSize = atlas.pixelSizeFor(fontSizePx, fontFamily);
    const scale = fontSizePx / pixelSize;
    const advance = (cp: number): number => {
        const glyph = atlas.getGlyph(cp, fontFamily, style, pixelSize);
        return glyph ? glyph.advance * scale + letterSpacing : 0;
    };
    const widths = new Array<number>(text.length + 1);
    widths[0] = 0;
    let width = 0;
    for (let i = 0; i < text.length;) {
        const cp = text.codePointAt(i)!;
        if (cp > 0xffff) {
            // A textarea can address the boundary between a surrogate pair.
            // Match measuring that truncated prefix, without adding it to the
            // complete code point's advance.
            widths[i + 1] = width + advance(text.charCodeAt(i));
            width += advance(cp);
            i += 2;
        } else {
            width += advance(cp);
            i++;
        }
        widths[i] = width;
    }
    return widths;
}

/**
 * Greedy word-wrap using an arbitrary width `measure` (display px). Breaks at
 * spaces; a token wider than the line (long word, or CJK runs with no spaces) is
 * broken character-by-character. The single source of wrap truth — the
 * atlas-backed {@link wrapLine} and the Canvas2D-backed `measureText` both call
 * it, so measured heights match rendered wraps.
 */
export function wrapByMeasure(
    text: string, measure: (s: string) => number, maxWidth: number,
    appendWidth?: (width: number, suffix: string) => number,
): string[] {
    return wrapMeasured(text, measure, maxWidth, appendWidth);
}

function wrapMeasured(
    text: string, measure: (s: string) => number, maxWidth: number,
    appendWidth?: (width: number, suffix: string) => number,
): string[] {
    const out: string[] = [];
    let cur = '';
    let curWidth = 0;
    const flush = () => { const t = cur.replace(/\s+$/, ''); if (t) out.push(t); cur = ''; curWidth = 0; };
    const appended = (suffix: string) => appendWidth ? appendWidth(curWidth, suffix) : measure(cur + suffix);
    const charBreak = (token: string) => {
        for (const ch of token) {
            let width = cur ? appended(ch) : appendWidth?.(0, ch) ?? 0;
            if (cur && width > maxWidth) {
                flush();
                width = appendWidth?.(0, ch) ?? 0;
            }
            cur += ch;
            curWidth = width;
        }
    };

    for (const token of text.split(/(\s+)/)) {
        if (token === '') continue;
        if (/^\s+$/.test(token)) {
            if (cur) { if (appendWidth) curWidth = appendWidth(curWidth, token); cur += token; }
            continue;
        }
        if (!cur) {
            const width = measure(token);
            if (width <= maxWidth) { cur = token; curWidth = width; }
            else charBreak(token);
        } else {
            const width = appended(token);
            if (width <= maxWidth) { cur += token; curWidth = width; }
            else {
                flush();
                const tokenWidth = measure(token);
                if (tokenWidth <= maxWidth) { cur = token; curWidth = tokenWidth; }
                else charBreak(token);
            }
        }
    }
    flush();
    return out.length ? out : [''];
}

/** Greedy wrap using ordered glyph advances without remeasuring the current line. */
export function wrapLine(
    text: string, atlas: GlyphAtlas, fontFamily: string, fontSizePx: number,
    style: number, maxWidth: number, letterSpacing = 0,
): string[] {
    const pixelSize = atlas.pixelSizeFor(fontSizePx, fontFamily);
    const scale = fontSizePx / pixelSize;
    const append = (width: number, suffix: string): number => {
        for (const ch of suffix) {
            const glyph = atlas.getGlyph(ch.codePointAt(0)!, fontFamily, style, pixelSize);
            if (glyph) width += glyph.advance * scale + letterSpacing;
        }
        return width;
    };
    return wrapMeasured(text, s => append(0, s), maxWidth, append);
}

/**
 * The largest whole-pixel font size, at most the one asked for, at which the text fits its box: no taller than
 * `boxHeight` and no wider than `boxWidth` (each only when given). Line height and letter spacing scale with the
 * size, as they do for a label the author sized by hand. Never below 1px: a box too small for anything shows
 * the smallest text rather than none.
 *
 * Fitting is assumed to get easier as type gets smaller, which holds for wrapping text (fewer, shorter lines) and
 * lets a binary search stand in for trying every size.
 */
export function shrinkFontSize(
    text: string, atlas: GlyphAtlas, fontFamily: string, opts: MultilineTextOptions, style = 0,
): number {
    const base = opts.fontSizePx;
    const width = opts.boxWidth ?? 0;
    const height = opts.boxHeight ?? 0;
    if (!(base > 1) || (!(width > 0) && !(height > 0))) return base;
    const fits = (size: number): boolean => {
        const laid = layoutText(text, atlas, fontFamily, scaledTo(opts, size), style);
        return (!(height > 0) || laid.lineHeight <= height + 1e-6) && (!(width > 0) || laid.width <= width + 1e-6);
    };
    const whole = Math.floor(base);
    if (fits(whole)) return base;
    let lo = 1;          // the smallest size we will answer with, whether or not it fits
    let hi = whole - 1;  // known not to fit at `whole`
    while (lo < hi) {
        const mid = Math.ceil((lo + hi) / 2);
        if (fits(mid)) lo = mid; else hi = mid - 1;
    }
    return lo;
}

/** The same layout request at another font size: line height and letter spacing follow, and nothing is clipped. */
function scaledTo(opts: MultilineTextOptions, size: number): MultilineTextOptions {
    const k = size / opts.fontSizePx;
    return {
        ...opts,
        fontSizePx: size,
        ...(opts.lineHeight !== undefined ? { lineHeight: opts.lineHeight * k } : {}),
        ...(opts.letterSpacing !== undefined ? { letterSpacing: opts.letterSpacing * k } : {}),
        overflow: TextOverflow.Visible,
    };
}

/**
 * Lay out multi-line text: splits on `\n`, lays each line out
 * (rich or plain), stacks lines downward (y-up: line 0 on top) by `lineHeight`,
 * and horizontally aligns each line within the widest line's block. Pure →
 * unit-testable. (Word-wrap to a max width is a later addition.)
 */
export function layoutText(
    text: string,
    atlas: GlyphAtlas,
    fontFamily: string,
    opts: MultilineTextOptions,
    style = 0,
): TextLayout {
    if (opts.overflow === TextOverflow.Shrink) {
        const size = shrinkFontSize(text, atlas, fontFamily, opts, style);
        const fitted = layoutText(text, atlas, fontFamily, scaledTo(opts, size), style);
        return size === opts.fontSizePx ? fitted : { ...fitted, fontSizePx: size };
    }
    const lineHeight = opts.lineHeight ?? opts.fontSizePx * 1.2;
    const align = opts.align ?? TEXT_ALIGN_LEFT;
    const baseColor = opts.color ?? ([1, 1, 1, 1] as const);
    const rawLines = text.split('\n');
    const wrap = !!(opts.maxWidth && opts.maxWidth > 0);
    const richOpts = { fontSizePx: opts.fontSizePx, letterSpacing: opts.letterSpacing, color: baseColor };

    // Word-wrap before stacking; explicit \n still hard-breaks. Rich lines wrap
    // at the styled-run level so a token measures with its own size/style. Inline
    // images survive the no-wrap path; wrapping is text-only (images drop) for now.
    // How many lines the box has room for. Below Visible only, and never zero: a
    // box too short for one line shows one clipped line rather than nothing, which
    // is what every layout engine does and what a reader can act on.
    const overflow = opts.overflow ?? TextOverflow.Visible;
    const boxHeight = opts.boxHeight ?? 0;
    // ResizeHeight keeps every line (the box grows to them) and every character (nothing is trimmed).
    const keepsAll = overflow === TextOverflow.Visible || overflow === TextOverflow.ResizeHeight;
    const maxLines = !keepsAll && boxHeight > 0
        ? Math.max(1, Math.floor(boxHeight / lineHeight))
        : Infinity;
    const ellipsis = overflow === TextOverflow.Ellipsis;
    // The width a line may not exceed. maxWidth already wrapped to it, so this is
    // for the unwrapped case — a single line in a fixed box, which is the one
    // ellipsis is usually asked for.
    const widthLimit = keepsAll ? 0
        : (opts.maxWidth && opts.maxWidth > 0) ? opts.maxWidth
        : (opts.boxWidth ?? 0);

    let lineLayouts: TextLayout[];
    if (opts.rich) {
        // Rich text truncates by line only: trimming one means measuring per run,
        // and a run's own size and style make that a different calculation.
        const richLines = rawLines
            .map(l => parseRichText(l))
            .flatMap(runs => (wrap
                ? wrapRichRuns(runs.filter((r): r is TextSegment => r.type === 'text'), atlas, fontFamily, opts.fontSizePx, style, opts.maxWidth!, opts.letterSpacing ?? 0)
                : [runs]));
        const kept = richLines.slice(0, maxLines === Infinity ? undefined : maxLines);
        if (ellipsis && kept.length < richLines.length && kept.length > 0) {
            kept[kept.length - 1] = [...kept[kept.length - 1], { type: 'text', text: ELLIPSIS } as TextSegment];
        }
        lineLayouts = kept.map(runs => layoutRichRuns(runs, atlas, fontFamily, richOpts, style));
    } else {
        const plainLines = wrap
            ? rawLines.flatMap(l => wrapLine(l, atlas, fontFamily, opts.fontSizePx, style, opts.maxWidth!, opts.letterSpacing ?? 0))
            : rawLines;
        const kept = plainLines.slice(0, maxLines === Infinity ? undefined : maxLines);
        const dropped = kept.length < plainLines.length;
        const measure = (t: string) => measureWidth(t, atlas, fontFamily, opts.fontSizePx, style, opts.letterSpacing ?? 0);
        const prefixes = (t: string) => measurePrefixWidths(t, atlas, fontFamily, opts.fontSizePx, style, opts.letterSpacing ?? 0);
        const cut = kept.map((line, i) => {
            const last = i === kept.length - 1;
            // The last kept line carries the ellipsis when lines were dropped, even
            // if it fits: the mark says "there is more", not "this line was long".
            if (dropped && last && ellipsis) return truncateLine(line + ELLIPSIS, measure, widthLimit || Infinity, true, prefixes);
            return widthLimit > 0 ? truncateLine(line, measure, widthLimit, ellipsis, prefixes) : line;
        });
        lineLayouts = cut.map(line => layoutLine(line, atlas, fontFamily, opts, style));
    }
    const lines = lineLayouts; // line count only below

    const contentWidth = lineLayouts.reduce((m, l) => Math.max(m, l.width), 0);
    // Align within the layout box when one is given (independent of word-wrap), then
    // the wrap width, else the widest line.
    const alignWidth = (opts.boxWidth && opts.boxWidth > 0) ? opts.boxWidth
        : (opts.maxWidth && opts.maxWidth > 0) ? opts.maxWidth
        : contentWidth;
    const glyphs: LaidGlyph[] = [];
    const images: LaidImage[] = [];
    const laidLines: LaidLine[] = [];

    for (let i = 0; i < lineLayouts.length; i++) {
        const ll = lineLayouts[i];
        const dx = align === TEXT_ALIGN_CENTER ? (alignWidth - ll.width) / 2
            : align === TEXT_ALIGN_RIGHT ? (alignWidth - ll.width)
            : 0;
        const dy = -i * lineHeight; // y-up: first line on top
        laidLines.push({ x: dx, width: ll.width, baseline: dy });
        for (const g of ll.glyphs) {
            glyphs.push({ ...g, x0: g.x0 + dx, x1: g.x1 + dx, y0: g.y0 + dy, y1: g.y1 + dy });
        }
        if (ll.images) {
            for (const im of ll.images) images.push({ ...im, x: im.x + dx, y: im.y + dy });
        }
    }

    return { glyphs, images, lines: laidLines, width: contentWidth, lineHeight: lines.length * lineHeight };
}

/**
 * Lay out a single line of rich text: `<b>`, `<i>`, `<color=#rrggbb[aa]>`,
 * `<font size=N>` runs (parsed by parseRichText) become glyphs carrying per-run
 * color + size + bold/italic style, and `<img>` runs become inline image boxes.
 * Each run scales by its own fontSize / atlas.renderSize; all share the baseline
 * (y = 0). Pure → unit-testable.
 */
export function layoutRichLine(
    content: string,
    atlas: GlyphAtlas,
    fontFamily: string,
    opts: RichTextLayoutOptions,
    baseStyle = 0,
): TextLayout {
    return layoutRichRuns(parseRichText(content), atlas, fontFamily, opts, baseStyle);
}

/** Measure a styled run's advance width (mirrors layoutRichRuns' pen math). */
function measureRun(
    text: string, run: TextSegment, atlas: GlyphAtlas, fontFamily: string,
    baseSizePx: number, baseStyle: number, spacing: number,
): number {
    const runSize = run.fontSize ?? baseSizePx;
    const pixelSize = atlas.pixelSizeFor(runSize, fontFamily);
    const scale = runSize / pixelSize;
    const style = baseStyle | (run.bold ? UI_TEXT_BOLD : 0) | (run.italic ? UI_TEXT_ITALIC : 0);
    let w = 0;
    for (const ch of text) {
        const cp = ch.codePointAt(0);
        if (cp === undefined) continue;
        const gph = atlas.getGlyph(cp, fontFamily, style, pixelSize);
        if (gph) w += gph.advance * scale + spacing;
    }
    return w;
}

/**
 * Greedy word-wrap over styled runs: tokens measure with their own run's
 * size/style, breaks land at spaces (a single oversized token breaks
 * character-by-character), and each output line is a run list ready for
 * {@link layoutRichRuns}. The plain-text twin is {@link wrapLine}.
 */
export function wrapRichRuns(
    runs: TextSegment[], atlas: GlyphAtlas, fontFamily: string,
    baseSizePx: number, baseStyle: number, maxWidth: number, spacing = 0,
): TextSegment[][] {
    interface Token { run: TextSegment; text: string; space: boolean }
    const tokens: Token[] = [];
    for (const run of runs) {
        for (const part of run.text.split(/(\s+)/)) {
            if (part === '') continue;
            tokens.push({ run, text: part, space: /^\s+$/.test(part) });
        }
    }

    const lines: TextSegment[][] = [];
    let cur: Token[] = [];
    let curWidth = 0;
    const measure = (t: Token) =>
        measureRun(t.text, t.run, atlas, fontFamily, baseSizePx, baseStyle, spacing);
    const flush = () => {
        while (cur.length > 0 && cur[cur.length - 1]!.space) cur.pop();
        // Merge adjacent tokens of the same run back into segments.
        const segs: TextSegment[] = [];
        for (const t of cur) {
            const last = segs[segs.length - 1];
            if (last && last.bold === t.run.bold && last.italic === t.run.italic
                && last.color === t.run.color && last.fontSize === t.run.fontSize) {
                last.text += t.text;
            } else {
                segs.push({ ...t.run, text: t.text });
            }
        }
        if (segs.length > 0) lines.push(segs);
        cur = [];
        curWidth = 0;
    };
    const push = (t: Token) => { cur.push(t); curWidth += measure(t); };
    const charBreak = (t: Token) => {
        for (const ch of t.text) {
            const w = measureRun(ch, t.run, atlas, fontFamily, baseSizePx, baseStyle, spacing);
            if (cur.length > 0 && curWidth + w > maxWidth) flush();
            push({ run: t.run, text: ch, space: false });
        }
    };

    for (const t of tokens) {
        if (t.space) {
            if (cur.length > 0) push(t); // keep inter-word spaces, drop leading
            continue;
        }
        const w = measure(t);
        if (cur.length === 0) {
            if (w <= maxWidth) push(t);
            else charBreak(t);
        } else if (curWidth + w <= maxWidth) {
            push(t);
        } else {
            flush();
            if (w <= maxWidth) push(t);
            else charBreak(t);
        }
    }
    flush();
    return lines.length ? lines : [[]];
}

/** Place an `<img>` run's box on the pen. y-up local space, baseline at y = 0;
 *  `valign` picks the vertical anchor (ascent ≈ size×0.8, descent ≈ size×0.2),
 *  `offsetX/Y` nudge it, `scale` sizes it. The pen advances by the scaled width. */
function placeImage(img: ImageSegment, penX: number, fontSizePx: number): LaidImage {
    const w = img.width * img.scale;
    const h = img.height * img.scale;
    const ascent = fontSizePx * 0.8;
    const descent = fontSizePx * 0.2;
    let yBottom: number;
    switch (img.valign) {
        case 'top': yBottom = ascent - h; break;
        case 'bottom': yBottom = -descent; break;
        case 'middle': yBottom = (ascent - descent) / 2 - h / 2; break;
        default: yBottom = 0; break; // baseline
    }
    return {
        src: img.src,
        x: penX + img.offsetX,
        y: yBottom + img.offsetY,
        w, h,
        tint: img.tint ? [img.tint.r, img.tint.g, img.tint.b, img.tint.a] : null,
    };
}

/**
 * Lay out a single rich line from its runs: text runs carry per-run color +
 * size + bold/italic; `<img>` runs place an inline image box that advances the
 * pen by its width. All share the baseline (y = 0). Pure → unit-testable.
 */
export function layoutRichRuns(
    runs: RichTextRun[],
    atlas: GlyphAtlas,
    fontFamily: string,
    opts: RichTextLayoutOptions,
    baseStyle = 0,
): TextLayout {
    const spacing = opts.letterSpacing ?? 0;
    const glyphs: LaidGlyph[] = [];
    const images: LaidImage[] = [];
    let penX = 0;
    let lineHeight = opts.fontSizePx;

    for (const run of runs) {
        if (run.type === 'image') {
            const placed = placeImage(run, penX, opts.fontSizePx);
            images.push(placed);
            if (placed.h > lineHeight) lineHeight = placed.h;
            penX += run.width * run.scale;
            continue;
        }
        const runSize = run.fontSize ?? opts.fontSizePx;
        const pixelSize = atlas.pixelSizeFor(runSize, fontFamily);
        const scale = runSize / pixelSize;
        const style = baseStyle | (run.bold ? UI_TEXT_BOLD : 0) | (run.italic ? UI_TEXT_ITALIC : 0);
        const color: RGBA = run.color
            ? [run.color.r, run.color.g, run.color.b, run.color.a]
            : opts.color;
        if (runSize > lineHeight) lineHeight = runSize;

        for (const ch of run.text) {
            const cp = ch.codePointAt(0);
            if (cp === undefined) continue;
            const gph = atlas.getGlyph(cp, fontFamily, style, pixelSize);
            if (!gph) continue;
            if (gph.width > 0 && gph.height > 0) {
                const x0 = penX + gph.bearingX * scale;
                const y1 = gph.bearingY * scale;
                glyphs.push({
                    u0: gph.u0, v0: gph.v0, u1: gph.u1, v1: gph.v1,
                    x0, y0: y1 - gph.height * scale, x1: x0 + gph.width * scale, y1,
                    pageId: gph.pageId, color, entry: gph,
                });
            }
            penX += gph.advance * scale + spacing;
        }
    }

    return { glyphs, images, width: penX, lineHeight };
}