@weasel-js/text 1.9.3 → 1.10.0

package/dist/{test-seams-DbGu8K5F.d.ts → test-seams-CuLNcDew.d.ts}

@@ -1,5 +1,5 @@
-import { ScreenLength, FillStyle, Stroke } from '@weasel-js/paint';
-import { FaceMetrics, FontStyle, FaceRuleMetrics } from '@weasel-js/font';
+import { ScreenLength, Fill, Stroke } from '@weasel-js/paint';
+import { FaceMetrics, FontStyle, ResolveResult, GlyphMetrics, BmFont, BmFontChar } from '@weasel-js/font';
 
 /**
  * CSS `text-transform` over styled runs: `uppercase`, `lowercase` and
@@ -113,7 +113,9 @@ interface StyledRun {
     /** World units, or `{ px }` for screen pixels — resolved against the view
      *  scale `resolveRuns` is given, like `TextStyle.fontSize`. */
     fontSize?: ScreenLength;
-    fill?: FillStyle;
+    /** This run's ink. `null` is no fill at all, leaving the glyphs to `stroke`
+     *  alone; absent inherits the node's. */
+    fill?: Fill | null;
     /** Outline over this run's glyphs. Overrides the node's own `data.stroke`;
      *  absent inherits it. Only painted on the outline tier. */
     stroke?: Stroke;
@@ -214,15 +216,12 @@ declare function runsToMarkdown(runs: readonly StyledRun[], grammar?: RunGrammar
 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
+ * Typography for `TextPose` and friends. 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.
+ * Paint does not live here. A text node carries its fill and stroke in
+ * `data.fill` / `data.stroke`, the slots every other node kind uses.
  */
 
 /**
@@ -236,11 +235,9 @@ type TextAlign = 'left' | 'center' | 'right' | 'start' | 'end' | 'justify';
 type TextDirection = 'ltr' | 'rtl';
 /**
  * Collapse a possibly reading-order-relative alignment to an absolute edge.
- *
- * Layout works in absolute edges, so this runs once at its entry and `start` /
- * `end` never reach the geometry. `justify` collapses to the start edge, which
- * is where it sets every line it does not spread; whether to spread is carried
- * separately, as `LayoutRunsOpts.justify`.
+ * `justify` collapses to the start edge, which is where it sets every line it
+ * does not spread; whether to spread is carried separately, as
+ * `LayoutRunsOpts.justify`.
  */
 declare function resolveAlign(align: TextAlign, direction: TextDirection): 'left' | 'center' | 'right';
 /** User-facing text style. All fields optional; defaults applied at render time via `resolveTextStyle`. */
@@ -259,10 +256,16 @@ interface TextStyle {
     fontStyle?: 'normal' | 'italic';
     /** Default `'left'`. Pass `'start'` to align by reading order instead. */
     align?: TextAlign;
-    /** Reading direction, resolving `align: 'start' | 'end'`. Default `'ltr'`. */
-    direction?: TextDirection;
+    /**
+     * Reading direction: the base direction of bidi reordering, and what
+     * `align: 'start' | 'end'` resolve against. Default `'auto'`, each
+     * paragraph's own first strong character.
+     */
+    direction?: TextDirection | 'auto';
     /** Multiplier applied to `fontSize`. Default 1.2. */
     lineHeight?: number;
+    /** Distance between tab stops, in spaces, as CSS `tab-size`. Default 8. */
+    tabSize?: number;
     /**
      * Break lines where they would pass the box width, at the break
      * opportunities of Unicode's line breaking algorithm (UAX #14) — between
@@ -301,9 +304,8 @@ interface TextStyle {
     fontVariantCaps?: FontVariantCaps;
     /**
      * Set the node's text as a superscript or subscript — the default every run
-     * inherits, exactly as a run's own `StyledRun.script` is for that run. The
-     * lines keep the height and baseline the unscripted text would have had.
-     * Absent is ordinary text.
+     * inherits. The lines keep the height and baseline the unscripted text would
+     * have had. Absent is ordinary text.
      */
     script?: 'super' | 'sub';
 }
@@ -315,12 +317,13 @@ interface ResolvedTextStyle {
     fontStyle: 'normal' | 'italic';
     /** Still relative if the author wrote it that way — `direction` resolves it. */
     align: TextAlign;
-    direction: TextDirection;
+    direction: TextDirection | 'auto';
     lineHeight: number;
+    tabSize: number;
     wrap: boolean;
     /** `null` is an explicit no-fill, the way it is on every other node kind:
      *  outline-only text, painted by its stroke alone. */
-    fill: FillStyle | null;
+    fill: Fill | null;
     caretColor: string;
     selectionBackground: string | null;
     selectionColor: string | null;
@@ -338,27 +341,19 @@ interface ResolvedTextStyle {
 }
 /** 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.
- */
+/** The paint a text node hands its glyphs — `data.fill` and `data.stroke`. Runs inherit these when they name none of their own. */
 interface TextPaint {
     /** `null` is an explicit no-fill and absent takes the default black — the
      *  reading every other node kind gives `data.fill`. Unfilled text paints
      *  through its stroke and nothing else, so it needs one to be visible. */
-    fill?: FillStyle | null;
+    fill?: Fill | null;
     /**
-     * Outline painted over the glyph fill. Absent means no outline — there is
-     * no such thing as a default text stroke.
+     * Outline painted over the glyph fill. Absent means no outline.
      *
-     * 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`.
+     * Only glyphs on the outline tier are stroked: below
+     * `textOutlineMinScreenSize` a glyph is a sampled distance field with no
+     * geometry to stroke, and it renders unstroked. `width` is in world units —
+     * it does not scale with `fontSize`.
      */
     stroke?: Stroke | null;
 }
@@ -367,10 +362,7 @@ interface TextPaint {
  * taking the glyph paint from the node rather than from the style.
  *
  * `scale` is the view scale any `{ px }` size resolves against — the same
- * mean-of-the-axes factor `resolveStrokeWidth` takes. It has to be applied
- * here, at the entry to layout, rather than at draw time: a screen-pixel size
- * changes the glyph advances, the wrap points and the measured bounds, and
- * everything downstream of `ResolvedTextStyle` reads a plain world number.
+ * mean-of-the-axes factor `resolveStrokeWidth` takes.
  */
 declare function resolveTextStyle(style?: TextStyle, paint?: TextPaint, scale?: number): ResolvedTextStyle;
 /** Build a CSS `font` shorthand suitable for `ctx.font`. */
@@ -378,35 +370,17 @@ 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'. A run's
- * own numeric `fontWeight` is the primitive `bold` is a preset over, so it
- * wins over both the flag and the node weight.
- * 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.
+ * producing a `ResolvedRun` with every styling field set.
  *
- * `textTransform` is applied here too, so `text` is what gets drawn. When a
- * transform changes a length, `srcMap` says which source characters each
- * drawn one came from; see `textTransform.ts`.
+ * `bold`/`italic` on a run fold into `fontWeight`/`fontStyle`; a run's own
+ * numeric `fontWeight` wins over both the flag and the node weight.
+ * `letterSpacing: 0` on a run is an override, not an absence — it zeroes
+ * inherited tracking. The decorations are *additive*: a run can turn one on
+ * but never off, so they resolve as `run.x || style.x`.
  *
- * `fontVariantCaps: 'small-caps'` is applied after it, over the transformed
- * text: lowercase becomes capitals, and `sizeMap` gives those their smaller
- * size. See `smallCaps.ts`.
+ * `script` folds into the two primitives it is a preset over, and comes out
+ * as one world-unit `baselineShift` and a final `fontSize`. `textTransform`
+ * is applied here, then small caps over the transformed text.
  */
 
 /** A run with every style resolved against the node's text style — no
@@ -431,7 +405,7 @@ interface ResolvedRun {
     /** `null` is an explicit no-fill: the glyphs are painted by `stroke` alone,
      *  which only the outline tier can do. Nothing is emitted for a run with
      *  neither. */
-    fill: FillStyle | null;
+    fill: Fill | null;
     /** 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;
@@ -445,11 +419,8 @@ interface ResolvedRun {
     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.
+     * positive raises. 0 for ordinary text. Already carries whatever `script`
+     * asked for.
      */
     baselineShift: number;
     /**
@@ -469,11 +440,8 @@ type ScriptPreset = Readonly<{
  * What `script: 'super'` and `script: 'sub'` expand to for a face that states
  * no script metrics of its own, 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. A face that carries `OS/2` script metrics uses
- * those instead; {@link scriptMetricsFor} is what a run actually gets.
+ * baseline. These are Adobe's defaults. A face that carries `OS/2` script
+ * metrics uses those instead; {@link scriptMetricsFor} is what a run gets.
  */
 declare const SCRIPT_METRICS: Readonly<Record<'super' | 'sub', ScriptPreset>>;
 /** The script presets for a face: its own `OS/2` values where it states
@@ -481,10 +449,8 @@ declare const SCRIPT_METRICS: Readonly<Record<'super' | 'sub', ScriptPreset>>;
 declare function scriptMetrics(face?: FaceMetrics): Readonly<Record<'super' | 'sub', ScriptPreset>>;
 /**
  * The script presets a run set in `(family, weight, style)` gets — resolved
- * through the font registry exactly as layout resolves the run, so a
- * character panel, an SVG export and the DOM edit overlay read the numbers
- * the canvas draws with. Override either half per run with `baselineShift` /
- * `fontScale`.
+ * through the font registry exactly as layout resolves the run. Override
+ * either half per run with `baselineShift` / `fontScale`.
  */
 declare function scriptMetricsFor(family: string, weight: number, style: FontStyle): Readonly<Record<'super' | 'sub', ScriptPreset>>;
 /** A `TextStyle.fontWeight` as a number: the CSS keywords `bold` and
@@ -506,29 +472,6 @@ declare function resolveRunFace(run: StyledRun, style: Pick<ResolvedTextStyle, '
  *  `style`. */
 declare function resolveRuns(runs: readonly StyledRun[], style: ResolvedTextStyle, viewScale?: number): ResolvedRun[];
 
-/** The three text decoration rules, in the order every tier paints them. */
-type DecorationKind = 'underline' | 'strikethrough' | 'overline';
-/**
- * Decoration placement and weight for a face that states none, as fractions
- * of the run's `fontSize`. Offsets are the *top* edge of the rule, measured
- * down from the baseline — so the two rules that sit above it are negative.
- *
- * Derived, not measured: they apply to an atlas baked before `gen-font`
- * recorded `faceMetrics`, a custom outline parser that reports none, and the
- * canvas tier, which has no font tables to read.
- */
-declare const DEFAULT_DECORATION_METRICS: Readonly<Record<DecorationKind, FaceRuleMetrics>>;
-/**
- * Where each rule sits for a face, in ems: the face's own underline and
- * strikeout where it states them, the defaults where it does not. No font
- * table places an overline, so it keeps the default offset and takes the
- * underline's weight, as browsers draw it.
- *
- * Every text tier places its rules through this, so one face puts a rule in
- * the same place whichever tier paints it.
- */
-declare function decorationMetrics(face?: FaceMetrics): Readonly<Record<DecorationKind, FaceRuleMetrics>>;
-
 /**
  * The bidi contract, declared here and implemented elsewhere.
  *
@@ -554,8 +497,8 @@ interface BidiReordering {
     levels: ArrayLike<number>;
 }
 /**
- * A bidi engine, passed to `layoutRuns` as `opts.bidi`. `@weasel-js/bidi`'s
- * `bidi` object satisfies it. `reorder`'s `start` / `end` index the code points
+ * A bidi engine, registered with `registerBidi` or passed to `layoutRuns` as
+ * `opts.bidi`. `@weasel-js/bidi`'s `bidi` object satisfies it. `reorder`'s `start` / `end` index the code points
  * `analyze` was given.
  */
 interface BidiResolver {
@@ -563,154 +506,90 @@ interface BidiResolver {
     reorder(analysis: BidiAnalysis, start: number, end: number): BidiReordering;
     /** L4 — the mirrored form for a character in a right-to-left run, or null. */
     mirror(cp: number): number | null;
+    /** The level the analysed paragraph reads at: even left to right, odd right
+     *  to left. What `'auto'` resolved to, for aligning `start` and `end`. */
+    baseLevel(analysis: BidiAnalysis): number;
+}
+
+/** Options for `layoutRuns`. */
+interface LayoutRunsOpts {
+    /** Wrap width. `Infinity` never wraps. */
+    maxWidth: number;
+    /**
+     * Width of the box `center` / `right` resolve within, with `x = 0` its left
+     * edge. Default `maxWidth`. Separate from it so a box can align text it does
+     * not wrap. When both are infinite a line anchors on its own width instead:
+     * `x = 0` is its midpoint (`center`) or right edge (`right`).
+     */
+    alignWidth?: number;
+    lineHeight: number;
+    /**
+     * `start` / `end` resolve against `direction`; `left` / `right` are absolute
+     * and ignore it, the way CSS `text-align` treats the same values. `justify`
+     * is `justify: true` with the start edge.
+     */
+    align: TextAlign;
+    /**
+     * Spread each line that wrapped across `alignWidth`, widening its word gaps
+     * (spaces between words; not leading or hanging trailing ones) by equal
+     * shares of the slack. A line that closes its paragraph, or has no gap, or
+     * no slack, keeps `align` — so `align` is CSS `text-align-last` here.
+     * Implied by `align: 'justify'`. Default `false`.
+     */
+    justify?: boolean;
+    /**
+     * Bidi engine. Default: the one given to `registerBidi`. With neither, the
+     * text lays out in logical order, which is correct for left-to-right text
+     * and wrong for right-to-left text — see the warning this emits when it
+     * detects the latter without one.
+     */
+    bidi?: BidiResolver;
+    /**
+     * Reading direction: the base direction of the bidi analysis, and what
+     * `start` / `end` resolve against. Default `'auto'`, each paragraph's own
+     * first strong character, which only an engine can find: with none, `'auto'`
+     * reads left to right.
+     */
+    direction?: TextDirection | 'auto';
+    /**
+     * Distance between tab stops, in spaces of the tab's own run (its advance
+     * plus the run's tracking), as CSS `tab-size` counts it. A tab advances to
+     * the next stop from the start of its line. Default 8.
+     */
+    tabSize?: number;
 }
 
 /**
- * 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.
+ * Runs-aware text layout: wraps `ResolvedRun[]` into lines and places every
+ * glyph on them. What to draw for the result — which glyphs share a draw,
+ * which tier paints each, where the decoration rules go — is `paintRuns`'.
+ * Nothing here reads a run's paint, so recoloring text never lays it out again.
  *
  * A run's `letterSpacing` (world units, so it does not scale with `fontSize`)
  * is added to the advance *after* every grapheme cluster 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. The last code
- * point of a cluster carries it, so a combining mark hangs off its base
- * before the gap opens. Clusters are segmented per run. 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).
+ * including the last one on a line — the CSS `letter-spacing` rule. Trailing
+ * tracking therefore widens the measured line width and counts toward
+ * wrapping. Spaces are tracked like any other character; a newline is not.
  *
- * Word wrap is applied when `maxWidth` is finite: words — the text between
- * UAX #14 break opportunities — are committed to a new line when they would
- * exceed the current line width. Forced line breaks are emitted at UAX #14's
- * hard breaks — `\n`, CR, CRLF as one, VT, FF, NEL, U+2028 and U+2029 — none
+ * Word wrap is applied when `maxWidth` is finite, at UAX #14 break
+ * opportunities. Forced line breaks are emitted at UAX #14's hard breaks, none
  * of which lays out a cell. Every run on a line shares one baseline, sunk to
- * clear whichever run reaches highest above it, so mixing sizes or faces aligns
- * them the way inline text aligns everywhere else; line height is
+ * clear whichever run reaches highest above it; line height is
  * `max(fontSize * lineHeight)` across the line. A face that states its ascent
  * and descent sits in its line the way CSS sets it — half the leading above the
  * ascent, negative when the face is taller than the line, so its glyphs overflow
  * the box rather than growing it. A run a relative size shrank
- * measures at its `strutSize` for both, the way a CSS line keeps its parent's
- * strut under a `<sup>`.
- *
- * 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.
+ * measures at its `strutSize` for both.
  *
- * ### Coordinates are origin-relative
+ * `ResolvedRun.baselineShift` displaces a run off that shared baseline. The
+ * shift moves the run's glyphs and its own decoration rules together, and does
+ * not feed back into the line's baseline or its height.
  *
- * 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.
+ * Every coordinate out of here is measured from the text's own top-left: the
+ * caller translates. That is what lets a text node be dragged without
+ * re-laying out.
  */
 
-/** 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;
-}
-/** Glyphs that share a resolved face, glyph source and paint — one draw call's worth. */
-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: FontStyle;
-    /** 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;
-    /** `null` for an unfilled run: the group's glyphs are painted by `stroke`
-     *  alone. Only ever null on an `'outline'` group carrying a stroke, since
-     *  nothing else can put ink down without a fill. */
-    fill: FillStyle | null;
-    /** 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: DecorationKind;
-    x0: number;
-    y0: number;
-    x1: number;
-    y1: number;
-    fill: FillStyle;
-}
 /**
  * One advance cell: a single code point's slot on a line.
  *
@@ -727,7 +606,7 @@ interface LaidOutCell {
     /** One past that source character — `srcIndex + 2` for an astral one. */
     srcEnd: number;
     cp: number;
-    /** Left edge of the cell, post-alignment, origin-relative like `x0`/`x1`.
+    /** Left edge of the cell, post-alignment, origin-relative.
      *
      *  **Not monotonic across `cells`** once a bidi engine reorders a line: cells
      *  stay in logical order and their x values do not. Sort on `x` for visual
@@ -743,6 +622,8 @@ interface LaidOutCell {
      * Whether this code point can put ink on the page. False for a space and
      * for a code point no tier could serve — each of which still holds its
      * slot. A zero-advance combining mark is `true`: it inks without advancing.
+     * An emoji drawn as one color glyph inks from its cluster's closing code
+     * point, which holds the whole advance; the ones before it are `false`.
      *
      * A property of the character and the face, not of this call: it does not
      * change when a dynamic bake lands or the outline threshold is crossed. A
@@ -750,17 +631,51 @@ interface LaidOutCell {
      * read the quad or outline geometry for exact ink extents.
      */
     drawsInk: boolean;
+    /**
+     * Whether this code point closes a grapheme cluster. A caret stops only
+     * after a cell that does: never between a letter and its combining mark,
+     * inside a joined emoji, or before a variation selector.
+     */
+    clusterEnd: boolean;
+}
+/**
+ * One code point where the pen put it, with what a painter needs to draw it:
+ * the tier that serves it and its record there. Carries no paint.
+ */
+interface PlacedGlyph {
+    /** Index of its run in the runs laid out. */
+    run: number;
+    cp: number;
+    /** The glyph's own size, which small caps sets below its run's. */
+    fontSize: number;
+    /** The tier serving the glyph, which is not its run's own when the code
+     *  point escalated to the dynamic tier, and that tier's metrics. */
+    resolved: ResolveResult;
+    metrics: GlyphMetrics;
+    /** The atlas to sample and the glyph's record in it. Both null on the
+     *  outline tier and for a slot with nothing to draw. A dynamic glyph's
+     *  record gains its atlas rect in place when its bake lands. */
+    font: BmFont | null;
+    glyph: BmFontChar | null;
+    /** Pen position: the left edge of the glyph's slot. */
+    x: number;
+    /** Its line's baseline, raised by its run's `baselineShift`. */
+    baselineY: number;
+    /** The glyph's own advance. */
+    advance: number;
+    /** How far the pen moved past it: `advance`, its run's tracking, and a
+     *  justified gap's share of the slack. */
+    step: number;
 }
 /**
- * One laid-out line's box, in the same world space as `LaidOutQuad`.
+ * One laid-out line's box.
  *
  * `[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.
+ * `[y0, y1]` is the full line box: `y0` is the pen's line top, and the box is
+ * as tall as its tallest run's `lineHeight` times that run's size, or the
+ * larger size a shrunken run inherited. Ink can escape it vertically; 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`.
@@ -773,16 +688,18 @@ interface LaidOutLineBox {
     /** The line's baseline, for callers placing carets or rules against it. */
     baselineY: number;
     /**
-     * One cell per code point on this line, left to right. Every code point the
-     * line covers has exactly one, drawn or not; only a newline has none, since
-     * it separates cells rather than being one. The code points are the drawn
-     * ones, after `textTransform`, so an uppercased `ß` has two cells.
+     * One cell per code point on this line, in logical order. Every code point
+     * the line covers has exactly one, drawn or not; only a newline has none,
+     * since it separates cells rather than being one. The code points are the
+     * drawn ones, after `textTransform`, so an uppercased `ß` has two cells.
      *
      * A caret stop is a cell's `x`, and the stop closing the line is `x1` /
      * `srcEnd` — there is one more stop than cell, except that cells sharing a
      * source span have no stop between them.
      */
     cells: LaidOutCell[];
+    /** The same code points as placed glyphs, in visual order, left to right. */
+    glyphs: PlacedGlyph[];
     /**
      * Source offset just past this line's last cell — the closing caret stop's
      * index, and the only source offset a blank line carries.
@@ -791,86 +708,22 @@ interface LaidOutLineBox {
 }
 /** What {@link layoutRuns} returns. Every coordinate is relative to the text's own top-left. */
 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. */
+    /** Per-line boxes in layout order: where the text actually sits inside its
+     *  wrap box. */
     lines: LaidOutLineBox[];
-    /** The text's ink box. `width` is the widest line measured to its last
+    /** The text's box. `width` is the widest line measured to its last
      *  non-space cell — a trailing space hangs past the aligned edge, so a
-     *  block wrapped at `maxWidth` never reports wider than it. */
+     *  block wrapped at `maxWidth` never reports wider than it. `height` is the
+     *  line boxes stacked. Not an ink box: a decoration rule, or a run shifted
+     *  off the baseline, can fall outside it. */
     bounds: {
         width: number;
         height: number;
     };
 }
-/** Options for {@link layoutRuns}. */
-interface LayoutRunsOpts {
-    /** Wrap width. `Infinity` never wraps. */
-    maxWidth: number;
-    /**
-     * Width of the box `center` / `right` resolve within, with `x = 0` its left
-     * edge. Default `maxWidth`. Separate from it so a box can align text it does
-     * not wrap. When both are infinite a line anchors on its own width instead:
-     * `x = 0` is its midpoint (`center`) or right edge (`right`).
-     */
-    alignWidth?: number;
-    lineHeight: number;
-    /**
-     * `start` / `end` resolve against `direction`; `left` / `right` are absolute
-     * and ignore it, the way CSS `text-align` treats the same values. `justify`
-     * is `justify: true` with the start edge.
-     */
-    align: TextAlign;
-    /**
-     * Spread each line that wrapped across `alignWidth`, widening its word gaps
-     * (spaces between words; not leading or hanging trailing ones) by equal
-     * shares of the slack. A line that closes its paragraph, or has no gap, or
-     * no slack, keeps `align` — so `align` is CSS `text-align-last` here.
-     * Implied by `align: 'justify'`. Default `false`.
-     */
-    justify?: boolean;
-    /**
-     * Bidi engine. Omit and the text lays out in logical order, which is correct
-     * for left-to-right text and wrong for right-to-left text — see the warning
-     * this emits when it detects the latter without one.
-     */
-    bidi?: BidiResolver;
-    /**
-     * Reading direction, for resolving `start` / `end`. Default `'ltr'`.
-     *
-     * Taken as an input rather than sniffed: this package has no DOM, so a
-     * consumer reading `getComputedStyle(box).direction` passes what it found.
-     */
-    direction?: TextDirection;
-    /**
-     * 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;
-}
 /**
- * Lay out `runs` into draw groups, decoration rules and line boxes. Wrapping,
- * baselines, tracking and decorations follow the rules in this file's module doc.
+ * Lay out `runs` into lines of placed glyphs. Wrapping, baselines and tracking
+ * follow the rules in this file's module doc.
  */
 declare function layoutRuns(runs: readonly ResolvedRun[], opts: LayoutRunsOpts): LaidOutRuns;
 
@@ -880,11 +733,10 @@ declare function layoutRuns(runs: readonly ResolvedRun[], opts: LayoutRunsOpts):
  * 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.
+ * codepoint, resolves a face per run, measures, wraps, aligns, and places
+ * every glyph — and `drawText` ran it per text command per frame. Measured,
+ * when it also built the draw groups: 2.0 ms/frame for 200 short labels, 9.3
+ * for 1000, and 25.9 for 200 wrapped paragraphs.
  *
  * ### Two keys, tried in order
  *
@@ -902,30 +754,23 @@ declare function layoutRuns(runs: readonly ResolvedRun[], opts: LayoutRunsOpts):
  * second: an identity hit never pays for it.
  *
  * Under either, one entry per distinct `(maxWidth, alignWidth, 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.
+ * align, direction, bidi engine, tab size)`. 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.
+ * So is everything that only changes what is drawn — a run's fill, stroke and
+ * decorations, the outline threshold — which `cachedPaintRuns` keys on
+ * instead. Two runs arrays that differ only there share one layout.
  *
  * ### 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.
+ * every lookup compares `faceGeneration()` — advanced by a registration, a
+ * load, a fallback policy, and the dynamic atlas measuring a face again or
+ * emptying its pages — and drops everything when it moves. A deferred bake
+ * landing does not advance it: that fills in a glyph record the layout
+ * already holds, and moves no pen. 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
  *
@@ -955,4 +800,25 @@ declare function cachedLayoutRuns(runs: readonly ResolvedRun[], opts: LayoutRuns
 /** Test helper. Do not call from product code. */
 declare function _resetLayoutCacheForTests(): void;
 
-export { smallCapsText as $, type TransformedRunText as A, type BidiAnalysis as B, cachedLayoutRuns as C, DEFAULT_DECORATION_METRICS as D, decorationMetrics as E, type FontVariantCaps as F, fontString as G, isBoldWeight as H, isSmallCapsLetter as I, layoutRuns as J, markdownToRuns as K, type LaidOutRuns as L, MARKDOWN_RUN_GRAMMAR as M, numericWeight as N, resolveAlign as O, resolveRunFace as P, resolveRuns as Q, type ResolvedTextStyle as R, type StyledRun as S, type TextStyle as T, resolveTextStyle as U, runsToMarkdown as V, runsToPlainText as W, scriptMetrics as X, scriptMetricsFor as Y, smallCapsScale as Z, smallCapsScaleFor as _, type ResolvedRun as a, toRuns as a0, transformRunTexts as a1, _resetLayoutCacheForTests as a2, type LayoutRunsOpts as b, type BidiReordering as c, type BidiResolver as d, DEFAULT_TEXT_STYLE as e, type DecorationKind as f, LAYOUT_CACHE_STRUCTURAL_LIMIT as g, LAYOUT_CACHE_VARIANT_LIMIT as h, type LaidOutCell as i, type LaidOutDecoration as j, type LaidOutGroup as k, type LaidOutLineBox as l, type LaidOutOutlineGlyph as m, type LaidOutQuad as n, type RunFlag as o, type RunGrammar as p, type RunMarker as q, type RunSourceMap as r, SCRIPT_METRICS as s, SMALL_CAPS_SCALE as t, type ScriptPreset as u, type SmallCapsText as v, type TextAlign as w, type TextDirection as x, type TextPaint as y, type TextTransform as z };
+/**
+ * Where the bidi engine arrives. This package cannot import one (see
+ * `bidiSeam.ts`), and most callers of `layoutRuns` are kit code a consumer
+ * never touches, so the consumer registers it once and every layout finds it.
+ */
+
+/**
+ * Give every text layout a bidi engine: `registerBidi(bidi)`, with `bidi`
+ * from `@weasel-js/bidi`. `layoutRuns` uses it whenever its options carry
+ * none. Pass `null`, or call the function returned, to take it out again.
+ */
+declare function registerBidi(engine: BidiResolver | null): () => void;
+/**
+ * The direction `text`'s first paragraph reads in: `direction` when it states
+ * one, otherwise its first strong character's. Finding that takes an engine,
+ * so with none registered the answer is `'ltr'`.
+ */
+declare function paragraphDirection(text: string, direction?: TextDirection | 'auto', engine?: BidiResolver | null): TextDirection;
+/** Test helper. Do not call from product code. */
+declare function _resetBidiWarningForTests(): void;
+
+export { _resetLayoutCacheForTests as $, markdownToRuns as A, type BidiAnalysis as B, numericWeight as C, DEFAULT_TEXT_STYLE as D, paragraphDirection as E, type FontVariantCaps as F, registerBidi as G, resolveAlign as H, resolveRunFace as I, resolveRuns as J, resolveTextStyle as K, type LaidOutRuns as L, MARKDOWN_RUN_GRAMMAR as M, runsToMarkdown as N, runsToPlainText as O, type PlacedGlyph as P, scriptMetrics as Q, type ResolvedTextStyle as R, type StyledRun as S, type TextStyle as T, scriptMetricsFor as U, smallCapsScale as V, smallCapsScaleFor as W, smallCapsText as X, toRuns as Y, transformRunTexts as Z, _resetBidiWarningForTests as _, type ResolvedRun as a, type LayoutRunsOpts as b, type TextPaint as c, type BidiReordering as d, type BidiResolver as e, LAYOUT_CACHE_STRUCTURAL_LIMIT as f, LAYOUT_CACHE_VARIANT_LIMIT as g, type LaidOutCell as h, type LaidOutLineBox as i, type RunFlag as j, type RunGrammar as k, type RunMarker as l, type RunSourceMap as m, SCRIPT_METRICS as n, SMALL_CAPS_SCALE as o, type ScriptPreset as p, type SmallCapsText as q, type TextAlign as r, type TextDirection as s, type TextTransform as t, type TransformedRunText as u, cachedLayoutRuns as v, fontString as w, isBoldWeight as x, isSmallCapsLetter as y, layoutRuns as z };