@weasel-js/text 1.9.4 → 1.10.1

package/dist/index.d.ts

@@ -1,8 +1,33 @@
-import { S as StyledRun, T as TextStyle, L as LaidOutRuns, R as ResolvedTextStyle, a as ResolvedRun, b as LayoutRunsOpts, c as TextDirection, B as BidiResolver } from './test-seams-Czz9ua7X.js';
-export { d as BidiAnalysis, e as BidiReordering, D as DEFAULT_DECORATION_METRICS, f as DEFAULT_TEXT_STYLE, g as DecorationKind, F as FontVariantCaps, h as LAYOUT_CACHE_STRUCTURAL_LIMIT, i as LAYOUT_CACHE_VARIANT_LIMIT, j as LaidOutCell, k as LaidOutDecoration, l as LaidOutGroup, m as LaidOutLineBox, n as LaidOutOutlineGlyph, o as LaidOutQuad, M as MARKDOWN_RUN_GRAMMAR, p as RunFlag, q as RunGrammar, r as RunMarker, s as RunSourceMap, t as SCRIPT_METRICS, u as SMALL_CAPS_SCALE, v as ScriptPreset, w as SmallCapsText, x as TextAlign, y as TextPaint, z as TextTransform, A as TransformedRunText, C as cachedLayoutRuns, E as decorationMetrics, G as fontString, H as isBoldWeight, I as isSmallCapsLetter, J as layoutRuns, K as markdownToRuns, N as numericWeight, O as resolveAlign, P as resolveRunFace, Q as resolveRuns, U as resolveTextStyle, V as runsToMarkdown, W as runsToPlainText, X as scriptMetrics, Y as scriptMetricsFor, Z as smallCapsScale, _ as smallCapsScaleFor, $ as smallCapsText, a0 as toRuns, a1 as transformRunTexts } from './test-seams-Czz9ua7X.js';
-import { FillStyle, Stroke } from '@weasel-js/paint';
-import { Rect } from '@weasel-js/geom';
-import { FaceMetrics } from '@weasel-js/font';
+import { S as StyledRun, T as TextStyle, L as LaidOutRuns, R as ResolvedTextStyle, a as ResolvedRun, b as LayoutRunsOpts, c as TextPaint } from './test-seams-CuLNcDew.js';
+export { B as BidiAnalysis, d as BidiReordering, e as BidiResolver, D as DEFAULT_TEXT_STYLE, F as FontVariantCaps, f as LAYOUT_CACHE_STRUCTURAL_LIMIT, g as LAYOUT_CACHE_VARIANT_LIMIT, h as LaidOutCell, i as LaidOutLineBox, M as MARKDOWN_RUN_GRAMMAR, P as PlacedGlyph, j as RunFlag, k as RunGrammar, l as RunMarker, m as RunSourceMap, n as SCRIPT_METRICS, o as SMALL_CAPS_SCALE, p as ScriptPreset, q as SmallCapsText, r as TextAlign, s as TextDirection, t as TextTransform, u as TransformedRunText, v as cachedLayoutRuns, w as fontString, x as isBoldWeight, y as isSmallCapsLetter, z as layoutRuns, A as markdownToRuns, C as numericWeight, E as paragraphDirection, G as registerBidi, H as resolveAlign, I as resolveRunFace, J as resolveRuns, K as resolveTextStyle, N as runsToMarkdown, O as runsToPlainText, Q as scriptMetrics, U as scriptMetricsFor, V as smallCapsScale, W as smallCapsScaleFor, X as smallCapsText, Y as toRuns, Z as transformRunTexts } from './test-seams-CuLNcDew.js';
+import { FaceRuleMetrics, FaceMetrics, FontStyle } from '@weasel-js/font';
+import { Fill, Stroke } from '@weasel-js/paint';
+import { Rect, PathInWorldPose, PolygonPath } from '@weasel-js/geom';
+import { Mixed } from '@weasel-js/registry';
+export { MIXED, Mixed } from '@weasel-js/registry';
+
+/** 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>>;
 
 /**
  * Line break opportunities per the Unicode Line Breaking Algorithm
@@ -58,7 +83,7 @@ interface TextPose {
     style?: TextStyle;
     /** Glyph paint — the same `data.fill` / `data.stroke` a scene text node
      *  carries. Not part of `style`: paint is not typography. */
-    fill?: FillStyle | null;
+    fill?: Fill | null;
     stroke?: Stroke | null;
     /** Box vertical alignment within `[y, y+height]`. Default 'top'. */
     verticalAlign?: TextVerticalAlign;
@@ -107,37 +132,145 @@ interface TextPoseLayout {
 declare function layoutTextPose(pose: TextPose, scale?: number): TextPoseLayout;
 
 /**
- * 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.
+ * What to draw for laid-out text: which tier paints each glyph, which glyphs
+ * can be staged together, and the decoration rules. Layout places the glyphs
+ * and knows nothing of this; no decision here moves one.
+ *
+ * Underline, strikethrough and overline come out as solid rectangles built
+ * from pen positions, not from quad extents: quads exist only for glyphs with
+ * ink, so a decorated stretch's spaces would punch holes in a rule derived
+ * from them.
  */
 
+/** One textured glyph quad, relative to the text's own top-left. */
+interface LaidOutQuad {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+    u0: number;
+    v0: number;
+    u1: number;
+    v1: number;
+    /** The glyph's baseline. The synthetic-italic skew leans vertices about it. */
+    baselineY: number;
+}
+/**
+ * One glyph the renderer should tessellate rather than sample.
+ *
+ * `d` is em-space SVG path data — 1 unit is 1 em, y grows down, origin on the
+ * baseline at the pen. Placing it is therefore a uniform scale by `scale`
+ * followed by a translate to `(x, baselineY)`. `key` identifies the cached
+ * tessellation — face identity plus codepoint.
+ */
+interface LaidOutOutlineGlyph {
+    d: string;
+    key: string;
+    /** Pen position: where em-space x = 0 lands, in world units. */
+    x: number;
+    /** The glyph's baseline: where em-space y = 0 lands, in world units. */
+    baselineY: number;
+    /** World units per em — the glyph's `fontSize`, since em space is unit-scale. */
+    scale: number;
+}
 /**
- * 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.
+ * Glyphs that share a resolved face, glyph source and paint, so a renderer
+ * can bind once for all of them. Groups come in the order their first glyph
+ * appears, line by line in visual order, and paint in that order.
  */
-declare function registerBidi(engine: BidiResolver | null): () => void;
+interface LaidOutGroup {
+    /** Resolved atlas family — may differ from the requested family when the
+     *  cross-family fallback policy substituted a default. A renderer looks the
+     *  atlas up by this, exactly. */
+    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, for the renderer to fake. */
+    synthetic: {
+        bold: boolean;
+        italic: boolean;
+    };
+    /** Which glyph source this group binds: a baked MSDF atlas, the runtime
+     *  canvas-SDF dynamic atlas, tessellated font outlines, or the dynamic
+     *  atlas's color pages, whose quads are emoji painted in their own colors. */
+    source: 'atlas' | 'canvas' | 'outline' | 'color';
+    /** Dynamic-atlas page index for 'canvas' and 'color' groups, each in its
+     *  own set of pages; 0 for the others. */
+    page: number;
+    /** The run's fill. It holds no paint — `null`, or a fill without one — only
+     *  on an `'outline'` group carrying a stroke, since nothing else can put ink
+     *  down without a fill. A `'color'` group takes its opacity and nothing else
+     *  from it. */
+    fill: Fill | null;
+    /** Outline painted over the glyphs. 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, unstroked. */
+    stroke?: Stroke;
+    /** Textured glyph quads. Always empty for an `'outline'` group. */
+    quads: LaidOutQuad[];
+    /** Outline geometry. Always empty for an `'atlas'` / `'canvas'` group. */
+    glyphs: LaidOutOutlineGlyph[];
+}
 /**
- * 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'`.
+ * One decoration rule: an axis-aligned solid rectangle in the same space as
+ * `LaidOutQuad`. Never spans a line break, and carries the fill of the run(s)
+ * it decorates so the rule follows the text color.
  */
-declare function paragraphDirection(text: string, direction?: TextDirection | 'auto', engine?: BidiResolver | null): TextDirection;
+interface LaidOutDecoration {
+    kind: DecorationKind;
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+    fill: Fill;
+}
+/** Options for {@link paintRuns}. */
+interface PaintRunsOpts {
+    /**
+     * 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.
+     *
+     * Ignored for a family that resolved to the outline tier because it has no
+     * atlas: there the geometry is the only rendering.
+     */
+    outlineMinSize?: number;
+}
+/** What {@link paintRuns} returns. Relative to the text's own top-left, as the layout is. */
+interface PaintedRuns {
+    groups: LaidOutGroup[];
+    /** Decoration rules, in line order; within a stretch, underline then
+     *  strikethrough then overline. Empty when nothing is decorated. */
+    decorations: LaidOutDecoration[];
+}
+/**
+ * Derive what to draw for `laid`, the layout of `runs` — or of runs that
+ * differ from them only in paint and decoration, which a layout does not read.
+ */
+declare function paintRuns(laid: LaidOutRuns, runs: readonly ResolvedRun[], opts?: PaintRunsOpts): PaintedRuns;
+
+/**
+ * {@link paintRuns}, reusing the previous result while the paints, the outline
+ * threshold's effect, and the glyphs available are what they were. `laid` must
+ * be the layout of `runs`, as for `paintRuns`.
+ *
+ * **The result is shared and must be treated as immutable.**
+ */
+declare function cachedPaintRuns(laid: LaidOutRuns, runs: readonly ResolvedRun[], opts?: PaintRunsOpts): PaintedRuns;
 
 /**
  * Wrap-aware text measurement for a 2D context. Lines end where `layoutRuns`
- * ends them — at UAX #14 break opportunities when a word would overflow
- * `maxWidth`, and at every hard break — through the same `wrapLines`, with
- * widths from `ctx.measureText` plus tracking. A word wider than `maxWidth`
- * is emitted on its own line unbroken (caller can decide to clip).
- *
- * Returns the laid-out lines, the total block height in world units
- * (`lines.length * fontSize * lineHeight`), and per-line `lineStarts` —
- * the UTF-16 offset of each line's first character in `text`, which
- * `caretIndexAt` uses to map a clicked (x, y) back to a source offset.
- * Trailing spaces and tabs hang and are not included in `lines[i]`; neither is the
- * hard break that closed it.
+ * ends them, with widths from `ctx.measureText` plus tracking. A word wider
+ * than `maxWidth` is emitted on its own line unbroken.
+ *
+ * `lineStarts` is the UTF-16 offset of each line's first character in `text`.
+ * Trailing spaces and tabs hang and are not included in `lines[i]`; neither is
+ * the hard break that closed it.
+ *
+ * A tab runs to its next stop and `fillText` draws one as a single space, so
+ * paint a line from `spans[i]` and not from `lines[i]`.
  *
  * The caller owns the `ctx.font` setup — pass a context whose `font`
  * already matches `style` (use `fontString(style)`).
@@ -146,24 +279,26 @@ declare function paragraphDirection(text: string, direction?: TextDirection | 'a
 /**
  * Advance width of `text` in world units, tracking included.
  *
- * `letter-spacing` is not part of the CSS `font` shorthand, so a context
- * whose `font` was set from `fontString(style)` measures glyphs only. The
- * GL path (`layoutRuns`) adds `letterSpacing` after every grapheme cluster
- * including the last, matching CSS, so this does too — and every 2D-side
- * width has to go through here or the two paths disagree about where a line
- * breaks.
+ * `letter-spacing` is not part of the CSS `font` shorthand, so `ctx` measures
+ * glyphs only. `letterSpacing` is added after every grapheme cluster
+ * including the last, as `layoutRuns` does — every 2D-side width has to go
+ * through here or the two paths disagree about where a line breaks.
  */
 declare function measuredWidth(ctx: CanvasRenderingContext2D, text: string, style: ResolvedTextStyle): number;
+/** A stretch of a line between tabs, and how far into the line it starts. */
+interface MeasuredSpan {
+    text: string;
+    x: number;
+}
 /** Result of `measureText`: wrapped lines, per-line source offsets, and total block height. */
 interface MeasuredText {
     lines: string[];
+    /** Per line, what to paint and where: its text split at its tabs. */
+    spans: MeasuredSpan[][];
     lineStarts: number[];
     height: number;
 }
-/**
- * Wrap `text` against `maxWidth` at the break opportunities `layoutRuns`
- * wraps at, measuring with `ctx`.
- */
+/** Wrap `text` against `maxWidth` at the break opportunities `layoutRuns` wraps at, measuring with `ctx`. */
 declare function measureText(ctx: CanvasRenderingContext2D, text: string, maxWidth: number, style: ResolvedTextStyle): MeasuredText;
 
 /** Options for `measureTextBounds`. */
@@ -178,19 +313,12 @@ interface MeasureTextBoundsOpts {
 }
 /**
  * Measure how the GL/MSDF renderer will lay out a single plain-text string,
- * using the registered font atlas metrics. Mirrors `textCommand` exactly
- * (`resolveTextStyle` → `resolveRuns` → `cachedLayoutRuns`), so the returned
- * bounds match what actually gets drawn — use it to size backgrounds/pills, place
- * labels, or test overlap without guessing widths.
- *
- * Pass `opts.maxWidth` to measure word-wrapped height (e.g. for a fixed-width
- * text box); omitting it measures the unwrapped single-line width. `opts.lineHeight`
- * overrides the style's multiplier without changing `style` itself.
+ * using the registered font atlas metrics. Mirrors `textCommand` exactly, so
+ * the returned bounds match what actually gets drawn.
  *
  * Returns `{ width, height }` in the same units as `style.fontSize`. The font
  * must already be registered via `registerFont`; an unregistered family falls
- * back to the atlas fallback glyph (and warns), so register fonts at app boot
- * before measuring.
+ * back to the atlas fallback glyph (and warns).
  */
 declare function measureTextBounds(text: string, style?: TextStyle, opts?: MeasureTextBoundsOpts): {
     width: number;
@@ -200,20 +328,16 @@ declare function measureTextBounds(text: string, style?: TextStyle, opts?: Measu
 /**
  * Where a text node's lines actually sit inside its pose box.
  *
- * A text pose is a layout box, not a bounding box: `"Away"` in a 309-unit-wide
- * box leaves most of the box empty, and anything that treats the pose as the
- * node's extent — picking, lasso, clipping, SVG export — claims that empty
- * space. `textLineBoxes` returns the per-line rectangles instead.
- *
- * The numbers come from `layoutTextPose`, the layout every painter of a text
- * pose draws, so the boxes cannot drift from what is painted — they wrap only
- * where the style declares `wrap`, and honor `align` and `verticalAlign`.
+ * A text pose is a layout box, not a bounding box, and anything that treats
+ * the pose as the node's extent — picking, lasso, clipping, SVG export —
+ * claims its empty space. The numbers come from `layoutTextPose`, the layout
+ * every painter of a text pose draws, so the boxes cannot drift from what is
+ * painted.
  *
  * These are line boxes, not ink boxes: each is `fontSize * lineHeight` tall
  * from the pen's line top. Ink can escape vertically at a `lineHeight` low
- * enough — see the `bounds` note at the end of `layoutRuns` — which is the
- * right trade for hit-testing, where a box that hugged the ink would make
- * an `x` harder to click than an `X`.
+ * enough, which is the right trade for hit-testing, where a box that hugged
+ * the ink would make an `x` harder to click than an `X`.
  */
 
 /** Options for {@link textLineBoxes}. */
@@ -230,6 +354,58 @@ interface TextLineBoxesOpts {
 /** Per-line rectangles for a text pose, in world units, in layout order. */
 declare function textLineBoxes(pose: TextPose, opts?: TextLineBoxesOpts): Rect[];
 
+/**
+ * Hit-testing for text nodes. `caretIndexAt` reads the caret stops off
+ * `layoutTextPose`, the layout the painters draw and `textLineBoxes` picks
+ * against, so the caret cannot land on a different line — or between different
+ * glyphs — than the one under the pointer.
+ */
+
+/** Options for `pointInTextPose`. */
+interface PointInTextPoseOpts {
+    /** Extra padding (world units) added to the rect on all sides. Default 0. */
+    padding?: number;
+}
+/** Coarse pose-rect hit-test for a text node — suitable for click-to-edit dispatch. */
+declare function pointInTextPose(x: number, y: number, pose: TextPose, opts?: PointInTextPoseOpts): boolean;
+/**
+ * Map a world-space point inside `pose` to a character offset into the pose's
+ * text (0..length). Clicks above the first line clamp to 0; clicks below the
+ * last line clamp to the end. Within a line, the caret lands between two
+ * glyphs at whichever side of the advance cell's midpoint `x` falls on.
+ *
+ * Honors `pose.runs` (a mixed-size line snaps on the cells each run actually
+ * produced) and `pose.verticalAlign`. The offset is into the runs'
+ * concatenated text, which `TextPose` requires to equal `pose.text`.
+ */
+declare function caretIndexAt(x: number, y: number, pose: TextPose): number;
+
+/**
+ * Resize a text node's pose to fit its content.
+ *
+ *   - `axis: 'height'` (default): keep `pose.width`, recompute `height` as
+ *     the block height plus optional vertical padding — wrapped at the width
+ *     inside the horizontal padding when the style declares `wrap`.
+ *   - `axis: 'both'`: ignore wrapping; recompute both `width` (longest
+ *     `\n`-split line) and `height` (line count × line height) plus padding.
+ *
+ * `pose.x` / `pose.y` are preserved; for a different growth direction, adjust
+ * `x` / `y` after calling.
+ */
+
+/** Options for `fitTextPose`. */
+interface FitTextPoseOptions {
+    /** Which axis (or axes) to recompute. Default: `'height'`. */
+    axis?: 'height' | 'both';
+    /** Padding (world units) added to all four sides. Default 0. */
+    padding?: number | {
+        x?: number;
+        y?: number;
+    };
+}
+/** Recompute a `TextPose`'s `width`/`height` to fit its content; pure helper, doesn't mutate scene state. */
+declare function fitTextPose(pose: TextPose, opts?: FitTextPoseOptions): TextPose;
+
 /** Width-measurement strategy for `layoutMarkdown`; canvas-backed default supplied by `createMarkdownRenderer`. */
 type MeasureFn = (text: string, fontSize: number, bold: boolean, italic: boolean) => number;
 /** The face a run's rules and script presets come from, for `layoutMarkdown`.
@@ -266,9 +442,10 @@ interface LayoutResult {
 /**
  * Word-wrap parsed runs into lines bounded by `maxWidth`, breaking at the
  * UAX #14 opportunities `layoutRuns` breaks at; pass `Infinity` for
- * single-line layout.
+ * single-line layout. A tab is a run of its own, as wide as it takes to reach
+ * its next stop, `tabSize` spaces apart.
  */
-declare function layoutMarkdown(runs: StyledRun[], maxWidth: number, fontSize: number, measure: MeasureFn, lineHeightFactor?: number, faceOf?: FaceMetricsFn): LayoutResult;
+declare function layoutMarkdown(runs: StyledRun[], maxWidth: number, fontSize: number, measure: MeasureFn, lineHeightFactor?: number, faceOf?: FaceMetricsFn, tabSize?: number): LayoutResult;
 /** Pluggable text-painting strategy. The default fills white at `(x, y)`; markdown renderers replace this. */
 type TextRenderer = (ctx: CanvasRenderingContext2D, text: string, x: number, y: number) => void;
 /** Font styling options threaded through `createMarkdownRenderer`. */
@@ -281,6 +458,8 @@ interface MarkdownFontOptions {
     color?: string;
     /** Multiplier applied to font size for line height. Default 1.3. */
     lineHeight?: number;
+    /** Distance between tab stops, in spaces, as CSS `tab-size`. Default 8. */
+    tabSize?: number;
 }
 /**
  * Build a fill+stroke `TextRenderer` pair, laying the text out once.
@@ -298,4 +477,276 @@ declare function createMarkdownRenderer(ctx: CanvasRenderingContext2D, text: str
     height: number;
 };
 
-export { BREAK_ALLOWED, BREAK_MANDATORY, BidiResolver, type FaceMetricsFn, LaidOutRuns, type LayoutLine, type LayoutResult, LayoutRunsOpts, type MarkdownFontOptions, type MeasureFn, type MeasureTextBoundsOpts, type MeasuredText, NO_BREAK, type PositionedRun, ResolvedRun, ResolvedTextStyle, StyledRun, TextDirection, type TextLineBoxesOpts, type TextPose, type TextPoseLayout, type TextPoseLayoutInput, type TextRenderer, TextStyle, type TextVerticalAlign, createMarkdownRenderer, isHardLineBreak, layoutMarkdown, layoutTextPose, lineBreakOpportunities, measureText, measureTextBounds, measuredWidth, paragraphDirection, registerBidi, textLineBoxes, textPoseLayoutInput, verticalAlignOffset };
+/** Visual options for `renderLabel`. */
+interface LabelOptions {
+    align?: 'center' | 'left';
+    fontSize?: number;
+    renderText?: TextRenderer;
+    /** Override the pill width (content width, excluding padding). */
+    width?: number;
+    /** Override the pill height (content height, excluding padding). */
+    height?: number;
+    /** Horizontal padding inside the pill. Default 4 (screen-pixel default). */
+    padX?: number;
+    /** Vertical padding inside the pill. Default 1 (screen-pixel default). */
+    padY?: number;
+    /** Corner radius of the pill background. Default 3 (screen-pixel default). */
+    cornerRadius?: number;
+}
+/** Render a text label with a 75%-opaque black pill background and white text. */
+declare function renderLabel(ctx: CanvasRenderingContext2D, text: string, x: number, y: number, options?: LabelOptions): void;
+/** Default `TextRenderer` used by `renderLabel`: white fill, no styling. */
+declare const defaultLabelTextRenderer: TextRenderer;
+
+/**
+ * The kit's one answer to "is this node text?": its data carries a string
+ * `text`. Routing, the `textEdit` dep, and `useSceneTextEdit` all ask it.
+ */
+declare function isTextData(data: unknown): data is {
+    text: string;
+};
+
+/**
+ * Range-addressed styling over `StyledRun[]`.
+ *
+ * Character offsets index the concatenated run text (`runsToPlainText`), and
+ * a range is half-open: `[start, end)`. Ranges are clamped, never wrapped,
+ * and a collapsed or inverted range (`start >= end`) is empty. Offsets are
+ * UTF-16 code units, so a boundary can bisect a surrogate pair.
+ *
+ * **Run-level flags are additive over the node's `TextStyle`: a run can
+ * turn `bold` / `italic` / `underline` / `strikethrough` on, never off.**
+ * So a flag is stored only when true, and absent reads as `false`. A run
+ * that must be lighter than a bold node says so with its own numeric
+ * `fontWeight`, which `bold` is a preset over (see {@link supersededKey}).
+ * The decorations have no such primitive, and the tri-state is collapsed by
+ * choice, to keep one canonical form per styling. Resolution must therefore
+ * read decorations as `run.underline || style.underline`, not `??`.
+ *
+ * Copies here are shallow: a `fill` object is shared by reference between
+ * the input runs, the patch, every run the patch touched, and the value
+ * `styleAtRange` reports. Treat `fill` values as immutable.
+ */
+
+/** Every styleable key of a run, each either a concrete value or MIXED (the
+ *  runs in the range disagree at that key). */
+type RangeStyle = {
+    [K in Exclude<keyof StyledRun, 'text'>]?: StyledRun[K] | Mixed;
+};
+/** What `applyStyleToRange` writes. */
+type RunStylePatch = Partial<Omit<StyledRun, 'text'>>;
+/** Every key of a run that carries styling — i.e. everything but `text`. */
+type StyleKey = Exclude<keyof StyledRun, 'text'>;
+/**
+ * The styling shared by every run overlapping `[start, end)`: a concrete
+ * value where the range agrees, `MIXED` where it doesn't. Keys no run
+ * in range sets are absent (they inherit the node's `TextStyle`) — except
+ * the additive flags, which read as `false`. An empty range reads as `{}`.
+ * A reported `fill` is the run's own object, not a copy.
+ */
+declare function styleAtRange(runs: readonly StyledRun[], start: number, end: number): RangeStyle;
+/**
+ * Does any run carry styling of its own? A flag stored as `false` counts as
+ * none, so runs whose styling was toggled back off read as `false`.
+ */
+declare function runsCarryStyling(runs: readonly StyledRun[]): boolean;
+/**
+ * The key a patch clears without naming it. `bold` is a preset over
+ * `fontWeight`, and a run keeps at most one of the two: writing either drops
+ * the other, so a Bold toggle is not hidden under a weight it cannot beat and
+ * a picked weight is not shadowed by a stale flag. Naming both writes both.
+ */
+declare function supersededKey(patch: RunStylePatch): 'bold' | 'fontWeight' | undefined;
+/**
+ * `range` with `patch` laid over it, keyed as a write of `patch` would leave
+ * the runs — for showing styling armed for the next keystroke over the
+ * styling at the caret. A key the patch leaves `undefined` keeps the range's
+ * value; the key it supersedes is dropped.
+ */
+declare function patchRangeStyle(range: RangeStyle, patch: RunStylePatch): RangeStyle;
+/**
+ * Write `patch` over `[start, end)`, splitting runs at the boundaries and
+ * coalescing neighbors that end up identical. A patch value of `undefined`
+ * or `false` deletes the key instead of storing it.
+ *
+ * Returns a new array of new runs (though a nested `fill` is shared by
+ * reference). Normalization — merging identical neighbors, dropping empty
+ * runs — applies to the whole array, not just the patched span, and to every
+ * call, including one whose range is empty.
+ */
+declare function applyStyleToRange(runs: readonly StyledRun[], start: number, end: number, patch: RunStylePatch): StyledRun[];
+
+/**
+ * The weight a range renders at, and whether that reads as bold, resolved as
+ * `resolveRuns` resolves a run: its own `fontWeight`, else 700 for `bold`,
+ * else the node's weight.
+ */
+declare function rangeWeight(range: RangeStyle | null, style: TextStyle | undefined): {
+    fontWeight: number | Mixed;
+    bold: boolean | Mixed;
+};
+/**
+ * What is actually rendering across a range: `range` (from `styleAtRange`,
+ * or `useTextEdit`'s `rangeStyle`) resolved against the node's own `style`
+ * and `paint`, as the canvas resolves runs. `null` reads the node alone.
+ *
+ * Flags are additive — a run can turn one on, never off — so a node flag
+ * makes the flag `true` across the range, `MIXED` runs included. Every other
+ * key is the run's value where the range sets one, otherwise the node's.
+ * The node level is resolved first, so the result has a value for every
+ * key but the run-only ones, and for `fill` unless the node is unfilled.
+ * Bold is read off the weight that renders (see {@link rangeWeight}), since
+ * a run's own `fontWeight` can take a bold node's text back to regular.
+ */
+declare function effectiveRangeStyle(range: RangeStyle | null, style: TextStyle | undefined, paint?: TextPaint): RangeStyle;
+
+/**
+ * Turning a run-level flag **off** inside a node that sets it.
+ *
+ * Run flags are additive over the node's `TextStyle` — a run turns `bold` /
+ * `italic` / `underline` / `strikethrough` on, never off (see the contract at
+ * the top of `rangeStyle.ts`). This resolves it by rewriting rather than by
+ * widening the model: clear the flag on the node, and set it on every run
+ * *outside* the range. The rendered result is identical, with `StyledRun`
+ * unchanged.
+ *
+ * The alternative was a tri-state run flag (`true` / `false` / inherit). It
+ * cannot cover `italic`: that is a boolean on a run but `fontStyle` on the
+ * node, so a run's `false` has no node-level boolean to override.
+ *
+ * `bold` needs neither: a run carries a numeric `fontWeight`, which overrides
+ * the node's outright, so lowering bold writes a regular weight over the
+ * range and leaves the node and the rest of the text alone.
+ */
+
+/** The additive run flags. */
+type FlagKey = 'bold' | 'italic' | 'underline' | 'strikethrough' | 'overline';
+/** The result of toggling a style flag over a text range: the rewritten runs
+ *  and node style. */
+interface SetFlagResult {
+    runs: StyledRun[];
+    style: TextStyle;
+}
+/** Does the node style carry this flag? */
+declare function nodeHasFlag(style: TextStyle, key: FlagKey): boolean;
+/** The patch that takes bold off a range: the flag, and — in a node that is
+ *  itself bold — a regular weight to override the node's. */
+declare function unboldPatch(style: TextStyle): RunStylePatch;
+/**
+ * Set `key` to `value` over `[start, end)`.
+ *
+ * Turning a flag **on**, or off in a node that doesn't set it, is the ordinary
+ * additive write and leaves `style` alone. Turning it off in a node that *does*
+ * set it takes the rewrite: the node flag is cleared and the flag is written
+ * onto the complement of the range. Bold is the exception, written as a
+ * weight over the range alone (see {@link unboldPatch}).
+ *
+ * `runs` is normalized on every path, so the complement collapses back to one
+ * run when the range is empty and the whole array coalesces as usual.
+ */
+declare function setFlagOverRange(runs: readonly StyledRun[], style: TextStyle, start: number, end: number, key: FlagKey, value: boolean): SetFlagResult;
+
+/**
+ * Synthetic-oblique angle, in radians — 12°, the conventional CSS
+ * `font-style: oblique`. Shared by everything that fakes an italic: the SDF
+ * tier skews quads by it, the outline tier shears glyph geometry by it, and
+ * `textToPath` bakes the same shear into extracted outlines. One constant so a
+ * face that falls back to the upright atlas leans the same amount however it
+ * ends up being drawn.
+ */
+declare const SYNTHETIC_ITALIC_RADIANS = 0.2094;
+
+/**
+ * Text as path geometry: the glyph outlines a text node draws, placed in
+ * world space and composed into one `Path`. The glyphs are the ones
+ * `layoutRuns` placed, so they land exactly where the renderer's outline tier
+ * puts them, with the tier forced on for every glyph whatever its size.
+ */
+
+/** The fields of a text node's data that decide its glyph geometry, and the
+ *  paint `textToPathsByPaint` splits it by. Paint never changes the geometry. */
+interface TextOutlineSource {
+    text: string;
+    runs?: readonly StyledRun[];
+    style?: TextStyle;
+    verticalAlign?: TextVerticalAlign;
+    /** The node's `data.fill`: `null` is no fill, absent the default black. */
+    fill?: Fill | null;
+    /** The node's `data.stroke`: absent or `null` is no stroke. */
+    stroke?: Stroke | null;
+}
+/** One paint's share of a text node's outlines — see {@link textToPathsByPaint}. */
+interface TextPaintPath {
+    /** The resolved fill these glyphs wear: the run's own, else the node's.
+     *  `null` for unfilled text, painted by its stroke alone. */
+    fill: Fill | null;
+    /** The resolved stroke — the run's own, else the node's — or absent. */
+    stroke?: Stroke;
+    /** World-space outlines, as {@link textToPath} builds them. */
+    path: PolygonPath;
+}
+/** A text node as {@link textToPath} reads it: its data and its pose. */
+interface TextNodeSource {
+    data: TextOutlineSource;
+    pose: PathInWorldPose;
+}
+/** Options for {@link textToPath}. */
+interface TextToPathOptions {
+    /** The view scale a `{ px }` `fontSize` or `letterSpacing` resolves
+     *  against, as for `textCommandFromPose`. Default 1. */
+    scale?: number;
+}
+/**
+ * Why a text node has no outline geometry to give:
+ *
+ * - `'no-outlines'` — the face that serves it has no outlines registered
+ *   (`registerFontOutlines`), so there is no geometry to read.
+ * - `'outlines-loading'` — registered but not parsed yet. `loadTextOutlines`
+ *   waits for it; the call has already started the load.
+ * - `'outlines-failed'` — registered, and the bytes did not load or parse.
+ * - `'synthetic-bold'` — the requested weight is faked from a lighter face.
+ *   The renderer thickens the distance field for that, and a path has no
+ *   field to thicken. Converting would silently lighten the text.
+ * - `'color-glyph'` — the text holds an emoji, which is a picture in its own
+ *   colors with no outline. Nothing a caller registers changes that.
+ */
+type TextOutlinesFailure = 'no-outlines' | 'color-glyph' | 'outlines-loading' | 'outlines-failed' | 'synthetic-bold';
+/** Thrown by {@link textToPath} when some run of the text has no outline
+ *  geometry. Names the run's requested face. */
+declare class TextOutlinesError extends Error {
+    readonly reason: TextOutlinesFailure;
+    readonly family: string;
+    readonly weight: number;
+    readonly style: FontStyle;
+    constructor(reason: TextOutlinesFailure, family: string, weight: number, style: FontStyle, detail: string);
+}
+/**
+ * The outline geometry of a text node, in world space: every glyph and every
+ * underline, strikethrough and overline rule it draws, as one `'nonzero'`
+ * compound path whose filled region is their union. Glyphs keep the font's
+ * curves; overlapping contours are not merged — run the result through
+ * `pathUnion` for that, at the cost of flattening the curves.
+ *
+ * `pose` is the node's box, rotation, and `transform`. Throws
+ * {@link TextOutlinesError} when any run's face cannot supply outlines — never
+ * returns a partial or empty path for that. Text with no ink (empty, or only
+ * spaces) returns an empty path.
+ */
+declare function textToPath(data: TextOutlineSource, pose: PathInWorldPose, opts?: TextToPathOptions): PolygonPath;
+/**
+ * {@link textToPath}, split by paint: one path per distinct resolved fill and
+ * stroke, each gathering the glyphs and decoration rules that wear it — a
+ * rule takes the fill of the run it underlines. Groups come in the order
+ * their paint first appears in the text; a paint whose runs put down no ink
+ * has none. Paint resolves as the renderer resolves it. Throws as
+ * `textToPath` does.
+ */
+declare function textToPathsByPaint(data: TextOutlineSource, pose: PathInWorldPose, opts?: TextToPathOptions): TextPaintPath[];
+/**
+ * Load the outlines of every face `data` is set in — the requested faces and
+ * the ones they resolve to — so a following {@link textToPath} does not fail
+ * with `'outlines-loading'`. Resolves once each has loaded or failed.
+ */
+declare function loadTextOutlines(data: TextOutlineSource, opts?: TextToPathOptions): Promise<void>;
+
+export { BREAK_ALLOWED, BREAK_MANDATORY, DEFAULT_DECORATION_METRICS, type DecorationKind, type FaceMetricsFn, type FitTextPoseOptions, type FlagKey, type LabelOptions, type LaidOutDecoration, type LaidOutGroup, type LaidOutOutlineGlyph, type LaidOutQuad, LaidOutRuns, type LayoutLine, type LayoutResult, LayoutRunsOpts, type MarkdownFontOptions, type MeasureFn, type MeasureTextBoundsOpts, type MeasuredSpan, type MeasuredText, NO_BREAK, type PaintRunsOpts, type PaintedRuns, type PointInTextPoseOpts, type PositionedRun, type RangeStyle, ResolvedRun, ResolvedTextStyle, type RunStylePatch, SYNTHETIC_ITALIC_RADIANS, type SetFlagResult, type StyleKey, StyledRun, type TextLineBoxesOpts, type TextNodeSource, type TextOutlineSource, TextOutlinesError, type TextOutlinesFailure, TextPaint, type TextPaintPath, type TextPose, type TextPoseLayout, type TextPoseLayoutInput, type TextRenderer, TextStyle, type TextToPathOptions, type TextVerticalAlign, applyStyleToRange, cachedPaintRuns, caretIndexAt, createMarkdownRenderer, decorationMetrics, defaultLabelTextRenderer, effectiveRangeStyle, fitTextPose, isHardLineBreak, isTextData, layoutMarkdown, layoutTextPose, lineBreakOpportunities, loadTextOutlines, measureText, measureTextBounds, measuredWidth, nodeHasFlag, paintRuns, patchRangeStyle, pointInTextPose, rangeWeight, renderLabel, runsCarryStyling, setFlagOverRange, styleAtRange, supersededKey, textLineBoxes, textPoseLayoutInput, textToPath, textToPathsByPaint, unboldPatch, verticalAlignOffset };