@weasel-js/text 1.2.0

package/dist/test-seams-nUU2u_Pt.d.ts

@@ -0,0 +1,589 @@
+import { FillStyle, Stroke } from '@weasel-js/paint';
+
+/**
+ * Canonical inline-styling primitive for text nodes. A node's text is
+ * either a plain `string` (treated as a single-run, default-styled fragment)
+ * or `StyledRun[]` for rich content. `toRuns` is the funnel that normalizes
+ * either form into the array shape used by the renderer.
+ *
+ * Every field except `text` is optional; missing fields fall back to the
+ * node-level `TextStyle`. `bold`/`italic` are toggles; richer weight axes
+ * (300/500/900) are out of scope for slice 1.
+ */
+
+/** A span of text with its own styling, as authored. Fields left absent
+ *  inherit from the node's text style — this is the difference between a run
+ *  and a fully resolved one. */
+interface StyledRun {
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    fontFamily?: string;
+    fontSize?: number;
+    fill?: FillStyle;
+    /** Outline over this run's glyphs. Overrides the node style's stroke;
+     *  absent inherits it. Only painted on the outline tier — see
+     *  {@link TextStyle.stroke}. */
+    stroke?: Stroke;
+    letterSpacing?: number;
+    underline?: boolean;
+    strikethrough?: boolean;
+    /** Draw a rule above this run's ascent. Additive over the node style. */
+    overline?: boolean;
+    /**
+     * Set this run as a superscript or subscript — a raised or lowered baseline
+     * and a smaller size together, which is the pair `<sup>` and `<sub>` imply.
+     *
+     * A preset over the two primitives below, not a third mechanism: it supplies
+     * a `baselineShift` and a `fontScale`, and naming either of those directly
+     * overrides that half while leaving the other alone. The numbers are in
+     * {@link SCRIPT_METRICS}.
+     *
+     * There is no node-level counterpart. A whole text node set as a superscript
+     * is a smaller node moved up, which the pose already says better.
+     */
+    script?: 'super' | 'sub';
+    /**
+     * Raise (positive) or lower (negative) this run off the line's shared
+     * baseline, in ems of the *inherited* font size — so a run's rise does not
+     * shrink along with the run when `fontScale` also applies.
+     */
+    baselineShift?: number;
+    /**
+     * Multiplier on the inherited font size. The relative counterpart to
+     * `fontSize`, which pins an absolute size and wins over this when both are
+     * present.
+     */
+    fontScale?: number;
+}
+/** Normalize the two accepted spellings of text content — a plain string or
+ *  an array of runs — to runs. Throws on a run with no string `text`. */
+declare function toRuns(input: string | StyledRun[]): StyledRun[];
+/** Concatenate runs, dropping all styling. */
+declare function runsToPlainText(runs: readonly StyledRun[]): string;
+/** A run flag an inline marker can toggle. The additive style toggles on
+ *  `StyledRun`; the valued fields (family, size, paint, `script`) have no
+ *  inline spelling and are not addressable this way. */
+type RunFlag = 'bold' | 'italic' | 'underline' | 'strikethrough' | 'overline';
+/** One inline marker: a delimiter repeated `repeat` times, and the flags it
+ *  turns on between its opening and closing occurrence. */
+interface RunMarker {
+    delimiter: string;
+    repeat: number;
+    flags: readonly RunFlag[];
+}
+/**
+ * The inline grammar `runsToMarkdown` writes and `markdownToRuns` reads.
+ *
+ * Markers sharing a delimiter are matched longest-first, which is what lets
+ * `***` mean something other than `**` followed by `*`. A backslash escapes
+ * any delimiter character and itself, in both directions.
+ */
+interface RunGrammar {
+    markers: readonly RunMarker[];
+}
+/**
+ * The markdown subset the kit reads and writes: `**bold**`, `*italic*`,
+ * `***both***`.
+ *
+ * Deliberately not the whole of markdown, and deliberately silent on
+ * `underline` / `strikethrough` — the two run flags with no entry here are
+ * dropped by `runsToMarkdown`, as they always have been. A grammar that wants
+ * `~~struck~~` adds one marker; nothing else has to change.
+ */
+declare const MARKDOWN_RUN_GRAMMAR: RunGrammar;
+/**
+ * Render runs in `grammar`, defaulting to the markdown subset. The flavor
+ * written to the clipboard alongside the plain-text one.
+ *
+ * A run whose flags exactly match one marker takes it; otherwise the markers
+ * that cover them nest. Flags no marker spells are dropped — the text still
+ * round-trips, without that styling.
+ */
+declare function runsToMarkdown(runs: readonly StyledRun[], grammar?: RunGrammar): string;
+/**
+ * Parse `input` in `grammar`, defaulting to the markdown subset, into styled
+ * runs. Newlines are preserved as literal characters inside a run — they are
+ * not run-boundary markers in this format.
+ */
+declare function markdownToRuns(input: string, grammar?: RunGrammar): StyledRun[];
+
+/**
+ * Typography for `TextPose` and friends. Every field is optional; consumers
+ * pass `{}` or override the few they care about. Defaults live in
+ * `DEFAULT_TEXT_STYLE` and are applied at render/measure time, never written
+ * back to the pose.
+ *
+ * Paint is not typography and does not live here. A text node carries its
+ * fill and stroke in `data.fill` / `data.stroke`, the slots every other node
+ * kind uses; `resolveTextStyle` takes them as its second argument and
+ * `StyledRun.fill` / `.stroke` override them per range.
+ */
+
+/** User-facing text style. All fields optional; defaults applied at render time via `resolveTextStyle`. */
+interface TextStyle {
+    /** Font size in world units. Default 16. */
+    fontSize?: number;
+    /** Default `'sans-serif'`. */
+    fontFamily?: string;
+    /** Default 400. */
+    fontWeight?: number | string;
+    /** Default `'normal'`. */
+    fontStyle?: 'normal' | 'italic';
+    /** Default `'left'`. */
+    align?: 'left' | 'center' | 'right';
+    /** Multiplier applied to `fontSize`. Default 1.2. */
+    lineHeight?: number;
+    /**
+     * Caret color used by the edit overlay. Defaults to the node's fill when
+     * that fill is solid; falls back to `#000` for non-solid paints.
+     */
+    caretColor?: string;
+    /**
+     * Selection background color used by the edit overlay's `::selection`
+     * pseudo-element. Defaults to a 25%-opacity tint of `caretColor` via CSS
+     * `color-mix`. Pass `'none'` to fall back to the browser-native highlight.
+     */
+    selectionBackground?: string;
+    /** Selection text color paired with `selectionBackground`. Default: inherits text color. */
+    selectionColor?: string;
+    /** Extra advance added after each glyph, in world units. Default 0. */
+    letterSpacing?: number;
+    /** Default `false`. */
+    underline?: boolean;
+    /** Default `false`. */
+    strikethrough?: boolean;
+    /** Default `false`. */
+    overline?: boolean;
+}
+/** `TextStyle` with all fields filled in from defaults — what the renderer actually consumes. */
+interface ResolvedTextStyle {
+    fontSize: number;
+    fontFamily: string;
+    fontWeight: number | string;
+    fontStyle: 'normal' | 'italic';
+    align: 'left' | 'center' | 'right';
+    lineHeight: number;
+    fill: FillStyle;
+    caretColor: string;
+    selectionBackground: string | null;
+    selectionColor: string | null;
+    letterSpacing: number;
+    underline: boolean;
+    strikethrough: boolean;
+    overline: boolean;
+    /** Absent means no outline — unlike the other fields, this one has no
+     *  default to fall back to. See {@link TextPaint.stroke}. */
+    stroke?: Stroke;
+}
+/** Default resolved style used when a `TextPose` omits `style`. */
+declare const DEFAULT_TEXT_STYLE: ResolvedTextStyle;
+/**
+ * The paint a text node hands its glyphs — `data.fill` and `data.stroke`,
+ * read straight off the node. Runs inherit these when they name none of
+ * their own.
+ *
+ * `fill: null` is not yet distinguishable from absent: a `ResolvedRun` must
+ * name a concrete fill, so unfilled-but-stroked text has nowhere to say so
+ * and falls back to the default black. See `docs/TODO.md`.
+ */
+interface TextPaint {
+    fill?: FillStyle | null;
+    /**
+     * Outline painted over the glyph fill. Absent means no outline — there is
+     * no such thing as a default text stroke.
+     *
+     * Only glyphs on the outline tier are stroked: above
+     * `textOutlineMinScreenSize` a glyph is a real `PolygonPath`, so it gets
+     * the ordinary tessellated ribbon with real joins, caps and miters, in any
+     * paint. Below it a glyph is a sampled distance field with no geometry to
+     * stroke, and it renders unstroked rather than approximated. `width` is in
+     * world units, like every other stroke in the kit — it does not scale with
+     * `fontSize`.
+     */
+    stroke?: Stroke | null;
+}
+/** Fill in a partial `TextStyle` with defaults from `DEFAULT_TEXT_STYLE`,
+ *  taking the glyph paint from the node rather than from the style. */
+declare function resolveTextStyle(style?: TextStyle, paint?: TextPaint): ResolvedTextStyle;
+/** Build a CSS `font` shorthand suitable for `ctx.font`. */
+declare function fontString(s: ResolvedTextStyle): string;
+
+/**
+ * Apply node-level `ResolvedTextStyle` defaults to each `StyledRun`,
+ * producing a fully-resolved run with every styling field set. Downstream
+ * layout and draw never re-resolve defaults — `ResolvedRun` is the
+ * canonical shape the renderer consumes.
+ *
+ * `bold`/`italic` toggles on a run are folded into `fontWeight`/`fontStyle`:
+ * `bold: true` → fontWeight 700, `italic: true` → fontStyle 'italic'.
+ * Explicit `fontFamily` / `fontSize` / `fill` / `letterSpacing` on the run
+ * override the node-level value (`letterSpacing: 0` on a run is an override,
+ * not an absence — it zeroes inherited tracking).
+ *
+ * `underline` / `strikethrough` / `overline` are *additive*, like
+ * `bold`/`italic`: a run can turn a decoration on but never off, so they
+ * resolve as `run.x || style.x` and not `run.x ?? style.x`. See the header of
+ * `runs/rangeStyle.ts` for why the model collapses the tri-state.
+ *
+ * `script` is folded the same way the toggles are, into the two primitives it
+ * is a preset over: `baselineShift` and `fontScale`. Both come out as one
+ * world-unit `baselineShift` and a final `fontSize`, so layout never learns
+ * that superscripts exist — it places a run against a baseline and an offset.
+ */
+
+/** A run with every style resolved against the node's text style — no
+ *  optional inheritance left. This is what layout and painting consume. */
+interface ResolvedRun {
+    text: string;
+    fontFamily: string;
+    fontSize: number;
+    fontWeight: number;
+    fontStyle: 'normal' | 'italic';
+    fill: FillStyle;
+    /** Outline over this run's glyphs, or absent for none. Painted only on the
+     *  outline tier — a distance field has no geometry to stroke. */
+    stroke?: Stroke;
+    /** Extra advance added after each glyph of this run, in world units. */
+    letterSpacing: number;
+    /** Draw a rule below this run's baseline. Additive over the node style. */
+    underline: boolean;
+    /** Draw a rule through this run's x-height. Additive over the node style. */
+    strikethrough: boolean;
+    /** Draw a rule above this run's ascent. Additive over the node style. */
+    overline: boolean;
+    /**
+     * How far this run sits off the line's shared baseline, in world units;
+     * positive raises. 0 for ordinary text.
+     *
+     * Already multiplied out against the inherited font size, and already
+     * carrying whatever `script` asked for — layout adds it to a baseline and
+     * asks nothing about where it came from.
+     */
+    baselineShift: number;
+}
+/**
+ * What `script: 'super'` and `script: 'sub'` expand to, as fractions of the
+ * inherited font size: `size` scales it, `shift` raises (positive) or lowers
+ * (negative) the baseline.
+ *
+ * These are Adobe's defaults — InDesign and Illustrator ship 58.3% size and
+ * 33.3% position for both — chosen because a drawing tool's users have those
+ * numbers in their fingers already. They are not read from the font: the
+ * `OS/2` table carries real `ySuperscript*` / `ySubscript*` metrics, but the
+ * baked atlas tier has no slot for them (see `layoutRuns`'s note on the
+ * decoration constants, which are derived for the same reason), and metrics
+ * that applied on one glyph tier and not the other would reflow text as it
+ * crossed the size threshold.
+ *
+ * Exported so a consumer building a character panel can show the percentages
+ * it is about to apply. Override either half per run with `baselineShift` /
+ * `fontScale`.
+ */
+declare const SCRIPT_METRICS: Readonly<Record<'super' | 'sub', Readonly<{
+    size: number;
+    shift: number;
+}>>>;
+/** Resolve each run's styling against the node's text style, filling in
+ *  everything the run left inherited. */
+declare function resolveRuns(runs: readonly StyledRun[], style: ResolvedTextStyle): ResolvedRun[];
+
+/**
+ * Runs-aware MSDF layout. Walks `ResolvedRun[]` codepoint-by-codepoint,
+ * switching atlas per run via `resolveFontVariant`, applying kerning
+ * (using the left glyph's atlas table and size scaling, including across
+ * run boundaries), and bucketing emitted quads by
+ * `(family, resolvedWeight, resolvedStyle, syntheticBold, syntheticItalic, fillKey)`
+ * so the renderer issues one draw call per atlas+color group.
+ *
+ * A run's `letterSpacing` (world units, so it does not scale with `fontSize`)
+ * is added to the advance *after* every character of that run, including the
+ * last one on a line — the CSS `letter-spacing` rule, chosen so a DOM overlay
+ * rendering the same text can be made to agree. Trailing tracking therefore
+ * widens the measured line width and counts toward wrapping. Spaces are
+ * tracked like any other character; a newline is not (it consumes no advance).
+ * One caveat against CSS: tracking is applied per *code point*, not per
+ * grapheme cluster, so `e` + U+0301 takes tracking twice where CSS would
+ * space the cluster once.
+ *
+ * Word wrap is applied when `maxWidth` is finite: words are committed to
+ * a new line when they would exceed the current line width. Forced line
+ * breaks are emitted for `\n` codepoints. Every run on a line shares one
+ * baseline, sunk to clear the tallest run's ascent, so mixing sizes or faces
+ * aligns them the way inline text aligns everywhere else; line height is
+ * `max(fontSize * lineHeight)` across the line.
+ *
+ * A run may also sit off that shared baseline: `ResolvedRun.baselineShift`
+ * displaces it, which is what `script: 'super' | 'sub'` resolves to. The shift
+ * moves the run's glyphs, its outline geometry and its own decoration rules
+ * together, and deliberately does not feed back into the line's baseline or
+ * its height — a superscript rides on the line rather than reflowing it.
+ *
+ * Underline, strikethrough and overline come out on a second channel,
+ * `decorations` —
+ * solid rectangles, not textured glyphs, so they cannot ride in a group's
+ * `quads` (which upload UVs into an MSDF program). They are accumulated
+ * during the same per-line pen walk that emits quads, *not* reconstructed
+ * from quad extents afterwards: quads exist only for glyphs with ink, so a
+ * decorated span's spaces would punch holes in a rule derived from them.
+ *
+ * ### Coordinates are origin-relative
+ *
+ * Every coordinate out of here is measured from the text's own top-left, not
+ * from anywhere on the page: the caller translates. That is what lets a text
+ * node be dragged without re-laying out — `layoutCache` would otherwise need
+ * the position in its key and miss on every frame of the drag — and it costs
+ * the caller one addition per vertex, inside loops already walking every one.
+ * Alignment, wrapping, tracking and decoration placement all read widths and
+ * pen deltas, never an absolute coordinate, so the translation is exact.
+ */
+
+/** One textured glyph quad, origin-relative — see the header. */
+interface LaidOutQuad {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+    u0: number;
+    v0: number;
+    u1: number;
+    v1: number;
+    /** Y coordinate of the line's baseline (penY at quad emission). Used by the
+     *  synthetic-italic vertex skew so above-baseline vertices lean right. */
+    baselineY: number;
+}
+/**
+ * One glyph the renderer should tessellate rather than sample: real font
+ * outline geometry, for text large enough that a distance field shows the
+ * raster it was reconstructed from.
+ *
+ * `d` is em-space SVG path data straight from `@weasel-js/font`'s outline
+ * registry — 1 unit is 1 em, y grows down, origin on the baseline at the pen.
+ * Placing it is therefore a uniform scale by `scale` (world units per em)
+ * followed by a translate to `(x, baselineY)`, and nothing here depends on
+ * zoom: the same glyph at the same size in two places is the same geometry
+ * twice, which is what lets the renderer tessellate it once and cache it.
+ *
+ * `key` identifies that cached tessellation — face identity plus codepoint,
+ * assembled here because layout is where both are in hand.
+ */
+interface LaidOutOutlineGlyph {
+    d: string;
+    key: string;
+    /** Pen position: where em-space x = 0 lands, in world units. */
+    x: number;
+    /** The line's baseline: where em-space y = 0 lands, in world units. */
+    baselineY: number;
+    /** World units per em — the run's `fontSize`, since em space is unit-scale. */
+    scale: number;
+}
+interface LaidOutGroup {
+    /** Resolved atlas family — may differ from the requested family when the
+     *  cross-family fallback policy substituted a default. This is what the
+     *  renderer looks the atlas up by, so it must be the one that resolves. */
+    family: string;
+    /** Resolved variant — matches the registered atlas and the texture-cache key. */
+    weight: number;
+    style: 'normal' | 'italic';
+    /** Gap between the request and the resolved match. Drives shader uniforms. */
+    synthetic: {
+        bold: boolean;
+        italic: boolean;
+    };
+    /** Which glyph source (and therefore shader/texture) this group binds:
+     *  baked MSDF atlas, the runtime canvas-SDF dynamic atlas, or tessellated
+     *  font outlines. */
+    source: 'atlas' | 'canvas' | 'outline';
+    /** Dynamic-atlas page index for 'canvas' groups; 0 for the others. */
+    page: number;
+    fill: FillStyle;
+    /** Outline painted over the glyphs, or absent for none. Only ever set on
+     *  an `'outline'` group — the SDF tiers have no geometry to stroke, which
+     *  is why a stroke pulls its run onto the outline tier at any size. A run
+     *  the tier cannot serve at all (no registered outlines, synthetic bold)
+     *  stays on the atlas and carries the request no further. */
+    stroke?: Stroke;
+    /** Textured glyph quads. Always empty for an `'outline'` group. */
+    quads: LaidOutQuad[];
+    /** Outline geometry. Always empty for an `'atlas'` / `'canvas'` group —
+     *  the two channels are exclusive, since the group is also the draw call
+     *  and one draw call binds one program. */
+    glyphs: LaidOutOutlineGlyph[];
+}
+/**
+ * One decoration rule: an axis-aligned solid rectangle in the same world
+ * space as `LaidOutQuad`. Never spans a line break, and carries the fill of
+ * the run(s) it decorates so the rule follows the text colour.
+ */
+interface LaidOutDecoration {
+    kind: 'underline' | 'strikethrough' | 'overline';
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+    fill: FillStyle;
+}
+/**
+ * One laid-out line's box, in the same world space as `LaidOutQuad`.
+ *
+ * `[x0, x1]` is the line's own advance width *after* alignment — not the
+ * wrap box — so a short centered line reports the span it actually occupies.
+ * `[y0, y1]` is the full line box: `y0` is the pen's line top, `y1` is
+ * `y0 + max(fontSize * lineHeight)` over the line's runs. Ink can escape it
+ * vertically (a tall accent, a deep descender at a lineHeight below ~1.06 —
+ * see the `bounds` note at the end of `layoutRuns`); this is the typographic
+ * box, not an ink bounding box.
+ *
+ * Emitted for every line including empty ones, so indices line up with the
+ * wrap. An empty line has `x0 === x1`.
+ */
+interface LaidOutLineBox {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+    /** The line's baseline, for callers placing carets or rules against it. */
+    baselineY: number;
+    /**
+     * Caret stops along this line, left to right: `caretXs[i]` is the left edge
+     * of the i-th advance cell, and the last entry is the line's right edge, so
+     * there is always one more stop than cell. Post-alignment, in the same
+     * origin-relative space as `x0`/`x1`.
+     *
+     * A cell spans one code point *plus* the kerning that precedes the next
+     * one, which is why a caret snapped to these midpoints lands where the
+     * glyphs actually were painted rather than where an unkerned re-measure
+     * would put them.
+     */
+    caretXs: number[];
+    /**
+     * Source offset for each stop in `caretXs`, as a UTF-16 index into the
+     * runs' concatenated text. Not contiguous: a code point the face cannot
+     * serve occupies no cell, and the wrap swallows the break between lines.
+     */
+    caretIndices: number[];
+}
+interface LaidOutRuns {
+    groups: LaidOutGroup[];
+    /** Decoration rules, in line order; within a span, underline then
+     *  strikethrough then overline. Empty when nothing is decorated. */
+    decorations: LaidOutDecoration[];
+    /** Per-line boxes in layout order. Lets a caller reason about where the
+     *  text actually sits inside its wrap box without re-running the wrap —
+     *  `textLineBoxes` builds the text silhouette from these, so picking and
+     *  painting cannot drift apart. */
+    lines: LaidOutLineBox[];
+    bounds: {
+        width: number;
+        height: number;
+    };
+}
+interface LayoutRunsOpts {
+    maxWidth: number;
+    lineHeight: number;
+    align: 'left' | 'center' | 'right';
+    /**
+     * World-space `fontSize` at or above which glyphs are emitted as outline
+     * geometry, when the resolved face has outlines registered. Omit (the
+     * default) to keep every glyph on its SDF tier.
+     *
+     * A *world* size rather than a screen size because layout knows nothing
+     * about the view; `drawText` divides its screen-pixel threshold by the view
+     * scale before calling, so zooming in lowers the world size that qualifies.
+     *
+     * This is a rendering switch only. Advances, kerning, wrapping and
+     * baselines are identical either way — the outline tier changes what a
+     * glyph looks like, never where it sits — so measurement callers
+     * (`measureTextBounds`, `textLineBoxes`) leave it unset and still agree
+     * with the paint, and crossing the threshold cannot reflow text.
+     *
+     * Ignored for a family that resolved to the outline tier because it has no
+     * atlas: there the geometry is not an upgrade over another rendering, it is
+     * the only one, so the threshold has nothing to choose between.
+     */
+    outlineMinSize?: number;
+}
+declare function layoutRuns(runs: readonly ResolvedRun[], opts: LayoutRunsOpts): LaidOutRuns;
+
+/**
+ * Laid-out text, memoized. The one entry point every caller of `layoutRuns`
+ * should reach for — the renderer's paint path, the silhouette measurement
+ * behind picking, and caret hit-testing all answer from this.
+ *
+ * `layoutRuns` is the most expensive derivation in the kit — it walks every
+ * codepoint, resolves a face per run, measures, wraps, aligns, and places a
+ * quad or an outline glyph for each — and `drawText` ran it per text command
+ * per frame. Measured: 2.0 ms/frame for 200 short labels, 9.3 for 1000, and
+ * 25.9 for 200 wrapped paragraphs. That last figure is the entire frame
+ * budget spent before a single triangle is drawn.
+ *
+ * ### Two keys, tried in order
+ *
+ * **Array identity**, in a `WeakMap`, the same contract as the renderer's
+ * `WeakMap<Path, Mesh>` — and for the same reason: it makes the entry
+ * collectable with whatever owns the runs, and the lookup is a pointer
+ * compare. `kit:text`'s memoized `paint` hands back a stable array per node,
+ * so the renderer stays on this path.
+ *
+ * **Structure**, in a bounded `Map`, for every caller that cannot. Measuring
+ * a pose resolves its style and allocates a fresh `ResolvedRun[]` each call,
+ * so an identity-keyed cache could never hold anything for it — and those
+ * callers run on the drag path, once per pose change. Serializing the runs is
+ * real work, unlike the pointer compare above, which is exactly why it is
+ * second: an identity hit never pays for it.
+ *
+ * Under either, one entry per distinct `(maxWidth, lineHeight, align, outline
+ * threshold)`. Position is deliberately absent: `layoutRuns` emits
+ * origin-relative geometry and `drawText` translates at upload, so a text node
+ * dragged across the page keeps hitting the same entry.
+ *
+ * ### The outline threshold
+ *
+ * `outlineMinSize` is derived from the view scale, so recording it literally
+ * would miss on every frame of a zoom. It reaches `layoutRuns` through exactly
+ * one comparison (`run.fontSize < min`, in `outlineFor`), so what the layout
+ * actually depends on is *which runs clear the bar* — and since the test is a
+ * plain `>=` on size, that set is pinned by how many of the distinct run sizes
+ * clear it. Recording that count is exact, not a quantization: the entry stays
+ * valid across every zoom that doesn't cross a glyph size, and is dropped the
+ * moment one does.
+ *
+ * ### What the keys cannot see
+ *
+ * The font set. A face landing changes metrics with no change to the runs, so
+ * every lookup compares `glyphGeneration()` — advanced by the dynamic SDF
+ * atlas, by the outline registry, and by `registerFont` — and drops
+ * everything when it moves. That is the same escape hatch `nodeMemo`'s
+ * generation counter provides, for the same class of failure. Polled rather
+ * than subscribed: a module-load subscription is a cross-package side effect
+ * that makes importing this package require the font package's whole surface.
+ *
+ * ### Bounds
+ *
+ * Variants per runs array are capped and evicted wholesale, matching
+ * `outlineMeshCache`: the refill cost is one layout, and the bookkeeping would
+ * cost more than the misses it avoids. The structural map cannot ride an
+ * array's lifetime the way the `WeakMap` does — nothing collects its keys —
+ * so it is a real LRU with a hard entry count.
+ */
+
+/** Distinct option combinations held for one runs array before the whole set
+ *  is dropped. Sized for "a few views onto the same text". */
+declare const LAYOUT_CACHE_VARIANT_LIMIT = 8;
+/** Layouts held against the structural key before the least recently used one
+ *  is dropped. Sized for "every text node visible on a page, plus slack". */
+declare const LAYOUT_CACHE_STRUCTURAL_LIMIT = 64;
+/**
+ * Lay `runs` out, reusing the previous result when nothing it depends on has
+ * changed. Drop-in for `layoutRuns` — same arguments, same return value.
+ *
+ * **The result is shared and must be treated as immutable.** `drawText`
+ * applies position and `verticalAlign` while packing vertices rather than by
+ * shifting the layout, precisely so it can be handed the same object every
+ * frame.
+ */
+declare function cachedLayoutRuns(runs: readonly ResolvedRun[], opts: LayoutRunsOpts): LaidOutRuns;
+/** Test helper. Do not call from product code. */
+declare function _resetLayoutCacheForTests(): void;
+
+export { DEFAULT_TEXT_STYLE as D, LAYOUT_CACHE_STRUCTURAL_LIMIT as L, MARKDOWN_RUN_GRAMMAR as M, type ResolvedTextStyle as R, type StyledRun as S, type TextStyle as T, _resetLayoutCacheForTests as _, LAYOUT_CACHE_VARIANT_LIMIT as a, type LaidOutDecoration as b, type LaidOutGroup as c, type LaidOutLineBox as d, type LaidOutOutlineGlyph as e, type LaidOutQuad as f, type LaidOutRuns as g, type LayoutRunsOpts as h, type ResolvedRun as i, type RunFlag as j, type RunGrammar as k, type RunMarker as l, SCRIPT_METRICS as m, type TextPaint as n, cachedLayoutRuns as o, fontString as p, layoutRuns as q, markdownToRuns as r, resolveRuns as s, resolveTextStyle as t, runsToMarkdown as u, runsToPlainText as v, toRuns as w };

package/dist/test-seams.d.ts

@@ -0,0 +1,2 @@
+export { _ as _resetLayoutCacheForTests } from './test-seams-nUU2u_Pt.js';
+import '@weasel-js/paint';

package/dist/test-seams.js

@@ -0,0 +1,3 @@
+export { _resetLayoutCacheForTests } from './chunk-4OGXTESY.js';
+//# sourceMappingURL=test-seams.js.map
+//# sourceMappingURL=test-seams.js.map

package/dist/test-seams.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"test-seams.js"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@weasel-js/text",
+  "version": "1.2.0",
+  "description": "Typography for weasel: styled runs, style resolution, kerned glyph layout, wrap and measurement. No scene graph, no React.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./test-seams": {
+      "import": "./dist/test-seams.js",
+      "types": "./dist/test-seams.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@weasel-js/font": "1.2.0",
+    "@weasel-js/geom": "1.2.0",
+    "@weasel-js/paint": "1.2.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "build": "tsup"
+  },
+  "author": "orochi235",
+  "homepage": "https://orochi235.github.io/weasel/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/orochi235/weasel.git",
+    "directory": "packages/text"
+  },
+  "bugs": {
+    "url": "https://github.com/orochi235/weasel/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}