@glissade/scene 0.19.1 → 0.20.0-pre.4

package/dist/collapseReplacer.d.ts

@@ -0,0 +1,40 @@
+//#region src/collapseReplacer.d.ts
+/**
+ * The byte-preserving collapse-replacer (DESIGN.md §3.3 / §3.5).
+ *
+ * Extracted to its OWN tiny module in the 0.20 budget review so the heavy
+ * DEV/CLI diagnostic surface (`diffDisplayLists`/`serializeDisplayList`/… in
+ * `displayDiff.ts`, now on the `@glissade/scene/diagnostics` subpath) can leave
+ * the base scene graph while THIS function — which IS on the render path — stays
+ * reachable from `displayList.ts` (the §3.5 cacheKey serializer) at a few bytes.
+ * Before the split, `displayList.ts` imported `collapseReplacer` from
+ * `displayDiff.ts`, dragging the entire diff/snapshot module into every embed.
+ *
+ * Shared by the cacheKey serializer (`createDisplayListBuilder().cacheKey`),
+ * `cacheColdAudit.hashDisplayList`, and `serializeDisplayList`. CRITICAL: this is
+ * BYTE-PRESERVING — the cacheKey it backs stamps into pushGroup and keys the
+ * §3.5 raster cache, so its output must not move. The three call sites previously
+ * DUPLICATED this byte-for-byte; it lives here once.
+ *
+ *  - ArrayBuffer / typed-array views collapse to a `ab:<len>` / `view:<len>`
+ *    length marker (opaque binary never belongs in a structural key).
+ *  - Functions drop (JSON would already drop them; explicit for parity).
+ *  - Non-finite numbers (`NaN`/`Infinity`/`-Infinity`) collapse to DISTINCT
+ *    string sentinels. `JSON.stringify` natively serializes all three to the
+ *    SAME token (`null`), which would collide the cacheKey of two DisplayLists
+ *    that differ only in WHICH non-finite value reaches a draw field — a stale
+ *    raster + an `auditCacheCold` false-OK. The distinct sentinels keep them
+ *    apart. This does NOT touch FINITE numbers (the common path): only the
+ *    three non-finite inputs change, so the §3.5 cacheKey bytes for every real
+ *    (finite) list are byte-identical — pinned by the regression guard.
+ *
+ * NOTE: `-0` is intentionally NOT normalized here. The matrix layer
+ * (`matrix.ts`) already normalizes `-0 → 0` at the source, and adding a `-0`
+ * pass to THIS replacer would change the cacheKey bytes for any list that ever
+ * carried a raw `-0` — silently invalidating the cache cluster-wide. (`-0` is
+ * finite, so the non-finite branch never touches it.) Byte preservation wins;
+ * the regression guard pins the exact key.
+ */
+declare function collapseReplacer(_key: string, value: unknown): unknown;
+//#endregion
+export { collapseReplacer as t };

package/dist/constructionProps.js

@@ -0,0 +1,82 @@
+//#region src/constructionProps.ts
+/**
+* The SLIM construction-prop NAME set (0.20) — the embed-path-safe half of the
+* describe() schema. A construction prop (`animatable: false`) is passed to a
+* node's constructor and is NEVER a track target; binding one is rejected.
+*
+* This module carries ONLY the per-node-type set of construction-prop NAMES
+* (plus the shared base set), nothing else — no value types, no `required`
+* flags, no manifest scaffolding. That keeps it tiny: it rides on the
+* embed/bind path (the bind guard imports it to turn a generic UnboundTarget
+* into a friendlier "that's a construction prop" message), so it must stay
+* byte-cheap. `describe.ts` imports the SAME sets and layers its richer
+* per-prop metadata (type/required) on top, so the manifest and this lookup
+* can't drift.
+*/
+/**
+* Base `NodeProps` construction-prop names shared by EVERY node — set once at
+* `new Node({...})`, never animatable (none is a registered target).
+*/
+const BASE_CONSTRUCTION_PROP_NAMES = [
+	"id",
+	"blend",
+	"filters",
+	"anchor",
+	"cache"
+];
+/**
+* Each built-in node's OWN construction-prop names (the base set is merged in
+* separately, via {@link isConstructionProp}). Keyed by the describe TYPE NAME
+* (e.g. `Image`, not the `ImageNode` class name).
+*/
+const SKETCH = [
+	"sketch",
+	"sketchFill",
+	"sketchSeed"
+];
+const LAYOUT = [
+	"direction",
+	"justify",
+	"align",
+	"children"
+];
+const NODE_CONSTRUCTION_PROP_NAMES = {
+	Group: ["children"],
+	Rect: SKETCH,
+	Circle: SKETCH,
+	Path: SKETCH,
+	Text: [
+		"fontFamily",
+		"fontWeight",
+		"fontStyle",
+		"align",
+		"lineHeight",
+		"fontVariationSettings"
+	],
+	Image: ["assetId"],
+	Video: [
+		"assetId",
+		"at",
+		"trimStart",
+		"playbackRate",
+		"clipDuration",
+		"sourceFps"
+	],
+	Layout: LAYOUT,
+	Stack: LAYOUT,
+	Row: LAYOUT,
+	Column: LAYOUT
+};
+/**
+* Is `prop` a KNOWN construction-only prop for a node of describe-type
+* `typeName`? True for the shared base set or that type's own set. Used by the
+* bind guard to special-case the unbound-target error: a construction prop gets
+* a "set it at construction" message instead of the generic one.
+*/
+function isConstructionProp(typeName, prop) {
+	if (BASE_CONSTRUCTION_PROP_NAMES.includes(prop)) return true;
+	const own = NODE_CONSTRUCTION_PROP_NAMES[typeName];
+	return own !== void 0 && own.includes(prop);
+}
+//#endregion
+export { NODE_CONSTRUCTION_PROP_NAMES as n, isConstructionProp as r, BASE_CONSTRUCTION_PROP_NAMES as t };

package/dist/describe.d.ts

@@ -62,6 +62,25 @@ interface DescribedBuilderMethod {
   name: string;
   signature: string;
 }
+/**
+ * One helper/factory in the manifest — the broader builder API beyond the node
+ * taxonomy and the timeline builder. These are the free functions an AI consumer
+ * reaches for (transport, motion-path, clips, snapshot, text-splitting); several
+ * live ABOVE `scene` in the dep graph (player/backend), so describe() can't
+ * import them — this is a CURATED literal, drift-guarded by a test that runs in a
+ * package above scene (`@glissade/browser`'s smoke test) and asserts every name
+ * resolves to a real `window.glissade.<name>` function.
+ */
+interface DescribedHelper {
+  /** The exported function name — also the `window.glissade.<name>` global on the IIFE. */
+  name: string;
+  /** One line: what it's for. */
+  summary: string;
+  /** The npm subpath to import it from (e.g. `@glissade/player`). On the IIFE it's `window.glissade.<name>`. */
+  import: string;
+  /** A minimal signature/usage string showing the call shape. */
+  usage: string;
+}
 /** The full machine-readable manifest `describe()` returns. */
 interface ApiManifest {
   version: string;
@@ -73,6 +92,13 @@ interface ApiManifest {
   builder: {
     methods: DescribedBuilderMethod[];
   };
+  /**
+   * The curated helper/factory surface (0.20) — `createPlayer`/`mount`,
+   * `motionPath`/`followPath`, `clip`/`clipList`, `renderToDataURL`/`snapshotCanvas`,
+   * `splitText`, `Grid`, and the `Stack`/`Row`/`Column` layout factories. Every
+   * `name` is also a `window.glissade.<name>` global on the IIFE.
+   */
+  helpers: DescribedHelper[];
   createScene: string;
   subpaths: {
     [entry: string]: string;
@@ -86,4 +112,4 @@ interface ApiManifest {
  */
 declare function describe(): ApiManifest;
 //#endregion
-export { ApiManifest, DescribedBuilderMethod, DescribedNode, DescribedProp, describe };
+export { ApiManifest, DescribedBuilderMethod, DescribedHelper, DescribedNode, DescribedProp, describe };

package/dist/describe.js

@@ -1,4 +1,5 @@
 import { a as Path, c as Video, i as ImageNode, o as Rect, r as Group, s as Text, t as Circle } from "./nodes.js";
+import { n as NODE_CONSTRUCTION_PROP_NAMES, t as BASE_CONSTRUCTION_PROP_NAMES } from "./constructionProps.js";
 import { easings, listValueTypes } from "@glissade/core";
 //#region src/describe.ts
 /**
@@ -22,7 +23,7 @@ import { easings, listValueTypes } from "@glissade/core";
 * never pulled onto the base embed path — a scene that never calls `describe()`
 * pays zero bytes for it.
 */
-const RAW_VERSION = "0.19.1";
+const RAW_VERSION = "0.20.0-pre.4";
 const PACKAGE_VERSION = RAW_VERSION.includes("GLISSADE_".concat("VERSION")) ? "0.0.0-dev" : RAW_VERSION;
 /** Arity of a value type's numeric repr: vec2/vec2-arc → 2, number → 1; others (color/paint/path/string/boolean) carry no scalar arity. */
 function arityOf(type) {
@@ -40,15 +41,18 @@ function expectsToType(expects) {
 	return Array.isArray(expects) ? expects.join("|") : expects;
 }
 /**
-* Construction-only props by node type — the difference between a node's Props
-* interface and its `registerTarget` set (its animatable props). These are set
-* once at `new Node({...})` and can never be animated.
+* Per-prop construction metadata (value type + `required`) for the manifest.
+* The NAME sets themselves are owned by the slim `./constructionProps` module
+* (which BOTH this file and the embed-path bind guard import); this map only
+* layers the richer per-prop type info on top of those names. `describeNode`
+* iterates the slim names and looks each one up here, so a name that exists in
+* one place but not the other is a build-time-visible bug, not silent drift.
 *
 * Base `NodeProps` construction props (`id`, `blend`, `filters`, `anchor`,
 * `cache`) are shared by EVERY node and merged in separately, so this map holds
 * only each node's OWN construction surface.
 */
-const CONSTRUCTION_PROPS = {
+const CONSTRUCTION_PROP_META = {
 	Group: { children: { type: "Node[]" } },
 	Rect: {
 		sketch: { type: "SketchStyle" },
@@ -70,7 +74,8 @@ const CONSTRUCTION_PROPS = {
 		fontWeight: { type: "number" },
 		fontStyle: { type: "'normal'|'italic'" },
 		align: { type: "'left'|'center'|'right'" },
-		lineHeight: { type: "number" }
+		lineHeight: { type: "number" },
+		fontVariationSettings: { type: "string" }
 	},
 	Image: { assetId: {
 		type: "string",
@@ -89,10 +94,12 @@ const CONSTRUCTION_PROPS = {
 	}
 };
 /**
-* Base-`NodeProps` construction props shared by every node — set at
-* construction, never animatable (none is a registered target).
+* Per-prop type metadata for the shared base `NodeProps` construction props —
+* set at construction, never animatable. The NAME set lives in the slim
+* `./constructionProps` module (`BASE_CONSTRUCTION_PROP_NAMES`); this just maps
+* each shared name to its manifest value type.
 */
-const BASE_CONSTRUCTION_PROPS = {
+const BASE_CONSTRUCTION_PROP_META = {
 	id: { type: "string" },
 	blend: { type: "BlendMode" },
 	filters: { type: "FilterSpec[]" },
@@ -115,15 +122,20 @@ function describeNode(node, typeName) {
 			...arity !== void 0 ? { arity } : {}
 		};
 	}
-	const construction = {
-		...BASE_CONSTRUCTION_PROPS,
-		...CONSTRUCTION_PROPS[typeName] ?? {}
-	};
-	for (const [prop, spec] of Object.entries(construction)) props[prop] = {
-		type: spec.type,
-		animatable: false,
-		...spec.required ? { required: true } : {}
+	const ownNames = NODE_CONSTRUCTION_PROP_NAMES[typeName] ?? [];
+	const meta = {
+		...BASE_CONSTRUCTION_PROP_META,
+		...CONSTRUCTION_PROP_META[typeName] ?? {}
 	};
+	for (const prop of [...BASE_CONSTRUCTION_PROP_NAMES, ...ownNames]) {
+		const spec = meta[prop];
+		if (spec === void 0) throw new Error(`describe(): construction prop '${typeName}/${prop}' has no type metadata`);
+		props[prop] = {
+			type: spec.type,
+			animatable: false,
+			...spec.required ? { required: true } : {}
+		};
+	}
 	return { props };
 }
 /**
@@ -145,7 +157,7 @@ const LAYOUT_ANIMATABLE = {
 	gap: { type: "number" },
 	padding: { type: "number" }
 };
-const LAYOUT_CONSTRUCTION = {
+const LAYOUT_CONSTRUCTION_META = {
 	direction: { type: "'row'|'column'" },
 	justify: { type: "'start'|'center'|'end'|'space-between'|'space-around'" },
 	align: { type: "'start'|'center'|'end'|'stretch'" },
@@ -169,12 +181,15 @@ function describeLayoutNode() {
 			...arity !== void 0 ? { arity } : {}
 		};
 	}
-	const construction = LAYOUT_CONSTRUCTION;
-	for (const [prop, spec] of Object.entries(construction)) props[prop] = {
-		type: spec.type,
-		animatable: false,
-		...spec.required ? { required: true } : {}
-	};
+	for (const prop of NODE_CONSTRUCTION_PROP_NAMES.Layout ?? []) {
+		const spec = LAYOUT_CONSTRUCTION_META[prop];
+		if (spec === void 0) throw new Error(`describe(): Layout construction prop '${prop}' has no type metadata`);
+		props[prop] = {
+			type: spec.type,
+			animatable: false,
+			...spec.required ? { required: true } : {}
+		};
+	}
 	return {
 		props,
 		subpath: LAYOUT_SUBPATH
@@ -252,6 +267,96 @@ const BUILDER_METHODS = [
 		signature: "editableDuration(): TimelineBuilder"
 	}
 ];
+/**
+* The curated helper/factory surface (0.20). These are the free functions the
+* discovery doc surfaces beyond the node taxonomy + timeline builder — transport,
+* motion-path sampling, motion clips, frame snapshot, text splitting. Several live
+* ABOVE `scene` in the dep graph (player / backend-canvas2d), so describe() CANNOT
+* import them — this literal is curated by hand and drift-guarded by a test that
+* runs in a package above scene (`@glissade/browser`'s smoke test), which asserts
+* every `name` here resolves to a real `window.glissade.<name>` function on the
+* IIFE. Copy is kept verbatim from `docs/discovery.md` so docs and manifest agree.
+*/
+const HELPERS = [
+	{
+		name: "createPlayer",
+		summary: "Build the transport object (play / pause / seek / rate / loop / marker + cue callbacks) directly — what mount() returns as mounted.player.",
+		import: "@glissade/player",
+		usage: "createPlayer({ playhead: createPlayhead(), duration: 2 }, { loop?: boolean }): Player  —  player.play() → { finished }, player.pause(), player.seek(u), player.rate = 2, player.onMarker(name, cb), player.onCue(kind, cb)"
+	},
+	{
+		name: "mount",
+		summary: "The one-call embed: builds the player, the backend, the rAF render loop, and font handling for you — start here. Returns { player } among other handles.",
+		import: "@glissade/player",
+		usage: "mount(scene, timeline, canvas, opts?: { loop?: boolean }): { player: Player, ... }"
+	},
+	{
+		name: "motionPath",
+		summary: "Build an arc-length sampler over a path — a pure, deterministic table you read points and tangents from by normalized progress (constant speed, not bezier parameter).",
+		import: "@glissade/scene/motion",
+		usage: "motionPath(path: PathValue): { length, atProgress(u): [x,y], tangentAtProgress(u): [x,y] }"
+	},
+	{
+		name: "followPath",
+		summary: "A companion node that makes a target ride a path as an animatable — it owns the target position (and rotation with orient) and exposes a progress you drive with a track.",
+		import: "@glissade/scene/motion",
+		usage: "followPath(target: Node, path: Node, opts?: { id?, orient?: boolean }): FollowPath  —  drive '<id>/progress' with a track"
+	},
+	{
+		name: "clip",
+		summary: "A reusable, target-agnostic motion captured once as a relative-time key schedule, then applied to a node at a wall-clock start time. Build-time sugar: clip.apply() compiles to ordinary Track[].",
+		import: "@glissade/core/clips",
+		usage: "clip({ channels: { <name>: { path, keys: [key(t, value, ease?)] } } }): Clip  —  clip.apply(nodeId, startT) → { tracks, end }"
+	},
+	{
+		name: "clipList",
+		summary: "Fan one clip across many targets, staggered, in a single call — returns the combined Track[].",
+		import: "@glissade/core/clips",
+		usage: "clipList(clip: Clip, targets: string[], startT: number, opts?: { stagger?: number }): { tracks }"
+	},
+	{
+		name: "renderToDataURL",
+		summary: "Capture a single frame as a PNG/WebP data URL — evaluate → render → data-URL, the no-build screenshot DX helper. Browser-only.",
+		import: "@glissade/backend-canvas2d/snapshot",
+		usage: "renderToDataURL(scene, timeline, t, opts?): string  (data: URL)"
+	},
+	{
+		name: "snapshotCanvas",
+		summary: "Render a single frame onto a canvas you pass in (the lower-level primitive renderToDataURL is built on). Browser-only.",
+		import: "@glissade/backend-canvas2d/snapshot",
+		usage: "snapshotCanvas(scene, timeline, t, canvas, opts?): void"
+	},
+	{
+		name: "splitText",
+		summary: "Split a Text node into per-word / per-char parts you can animate individually (kinetic typography). Tree-shaken off the base scene index.",
+		import: "@glissade/scene/type",
+		usage: "splitText(text: Text, opts?: { by?: 'word'|'char' }): Node[]"
+	},
+	{
+		name: "Grid",
+		summary: "Build-time CSS-grid-style track resolver: position plain children into a column grid (fr/px tracks + gaps), returning a Group. Pure fan-out (no Yoga, no new target) — the goldens hold by construction. Tree-shaken off the base scene index.",
+		import: "@glissade/scene/grid",
+		usage: "Grid({ columns: number | (number | { fr })[], children: Node[], gap?, columnGap?, rowGap?, cellHeight?, width? }): Group  —  child[i] → row floor(i/cols), col i%cols"
+	},
+	{
+		name: "Stack",
+		summary: "Yoga-flexbox layout factory (column by default) — a Layout subclass that stacks children with gap/padding/justify/align. Needs loadYogaLayoutEngine() before mount/render. On the @glissade/scene/layout subpath.",
+		import: "@glissade/scene/layout",
+		usage: "Stack({ children, direction?: 'row'|'column', gap?, padding?, justify?, align? }): Layout"
+	},
+	{
+		name: "Row",
+		summary: "Yoga-flexbox layout factory pinned to direction:\"row\" — children laid out horizontally. Needs loadYogaLayoutEngine() before mount/render. On the @glissade/scene/layout subpath.",
+		import: "@glissade/scene/layout",
+		usage: "Row({ children, gap?, padding?, justify?, align? }): Layout"
+	},
+	{
+		name: "Column",
+		summary: "Yoga-flexbox layout factory pinned to direction:\"column\" — children laid out vertically. Needs loadYogaLayoutEngine() before mount/render. On the @glissade/scene/layout subpath.",
+		import: "@glissade/scene/layout",
+		usage: "Column({ children, gap?, padding?, justify?, align? }): Layout"
+	}
+];
 /** One-line "what's there" for each documented tree-shakeable subpath entry. */
 const SUBPATHS = {
 	"@glissade/core/clips": "motion clips: clip/clipList + the popIn/slideIn/pulse/driftLoop literals, presence (enter/exit) and morph (box-FLIP) build-time sugar.",
@@ -281,6 +386,7 @@ function describe() {
 		valueTypes: listValueTypes(),
 		easings: Object.keys(easings),
 		builder: { methods: BUILDER_METHODS },
+		helpers: HELPERS,
 		createScene: "createScene({ size: { w, h }, children: Node[] }): Scene  —  media assets are declared on the Timeline document: timeline({ assets: { <id>: { kind: 'image'|'video', url } } }); an Image/Video node's `assetId` names an entry here.",
 		subpaths: SUBPATHS
 	};

package/dist/diagnostics.d.ts

@@ -0,0 +1,159 @@
+import { i as DrawCommand, m as Resource, n as DisplayList, r as DisplayListBuilder } from "./displayList.js";
+import { t as collapseReplacer } from "./collapseReplacer.js";
+import { B as NodeProps, L as EvalContext, V as PropInit, _ as WordBox, p as Text, z as Node } from "./nodes.js";
+import { r as Scene } from "./scene.js";
+import { Timeline, Vec2 } from "@glissade/core";
+
+//#region src/displayDiff.d.ts
+
+/**
+ * One index-aligned, positional delta between two DisplayList command streams.
+ *
+ * This is the natural per-command shape that `gs verify-determinism --bisect`
+ * (a later card) will consume to drill a cache-cold divergence down to the
+ * exact op/field. Keep it stable.
+ */
+interface CommandDelta {
+  /** Positional command index in BOTH lists (or the longer one for add/remove). */
+  index: number;
+  /**
+   *  - `change`  — same index present in both, but the commands differ.
+   *  - `add`     — present in `b` only (b is longer past this index).
+   *  - `remove`  — present in `a` only (a is longer past this index).
+   */
+  kind: 'change' | 'add' | 'remove';
+  /** op of the `a` command (undefined for `add`). */
+  opA?: DrawCommand['op'];
+  /** op of the `b` command (undefined for `remove`). */
+  opB?: DrawCommand['op'];
+  /**
+   * Field-level changes when both ops match (op changed → a single `op` field).
+   * Each entry names the changed prop path with its `from`/`to` JSON values.
+   */
+  fields: FieldChange[];
+}
+interface FieldChange {
+  /** dotted field path within the command, e.g. `paint.color`, `m`, `text`, `filters`. */
+  path: string;
+  from: unknown;
+  to: unknown;
+}
+interface DisplayDiff {
+  /** true when the two lists are byte-identical (the §3.3 determinism contract holds). */
+  equal: boolean;
+  /** per-command positional deltas, in index order (empty iff `equal`). */
+  deltas: CommandDelta[];
+  /** size mismatch, when the canvases differ (rare, but a real divergence). */
+  size?: {
+    from: DisplayList['size'];
+    to: DisplayList['size'];
+  };
+}
+/**
+ * Index-aligned positional diff of two DisplayLists. Command i in `a` is
+ * compared to command i in `b`; trailing commands become `add`/`remove`. A
+ * single insert/remove cascades — this is the documented v1 cliff.
+ */
+declare function diffDisplayLists(a: DisplayList, b: DisplayList): DisplayDiff;
+/** Human-readable, multi-line rendering of a DisplayDiff (CLI command-tree). */
+declare function formatDisplayDiff(diff: DisplayDiff): string;
+/**
+ * The `.dl.json` snapshot interchange schema (DESIGN §7.4). Users commit
+ * `.dl.json` baselines, so this carries the SAME break-policy obligation as
+ * `Timeline.version` and `SidecarDoc.sidecarVersion`: bump on a breaking shape
+ * change. Independent of the API version.
+ */
+declare const DL_SNAPSHOT_VERSION: 1;
+interface DlSnapshot {
+  /** Interchange schema version (§7.4) — the third versioned interchange document. */
+  dlSnapshotVersion: typeof DL_SNAPSHOT_VERSION;
+  size: DisplayList['size'];
+  commands: DrawCommand[];
+  resources: Resource[];
+}
+/**
+ * Serialize a DisplayList to a stable `.dl.json` document string (reusing the
+ * byte-preserving collapse-replacer). Round-trips through `parseDisplaySnapshot`.
+ */
+declare function serializeDisplayList(dl: DisplayList): string;
+declare class DlSnapshotError extends Error {
+  constructor(message: string);
+}
+/** Parse a `.dl.json` snapshot back into a DisplayList (validates the version). */
+declare function parseDisplaySnapshot(json: string): DisplayList;
+//#endregion
+//#region src/cacheColdAudit.d.ts
+interface CacheColdResult {
+  ok: boolean;
+  /** id of the first node whose isolated emit() diverged (set only when !ok). */
+  node?: string;
+  /**
+   * The FIRST command-level delta of the divergent node's isolated emit (set only
+   * when a specific leaf diverged — never for a Group fallback or a missing node).
+   * The WHOLE `CommandDelta` is embedded — index, kind, opA/opB, and every
+   * field change — so a multi-field divergence isn't flattened away. `gs
+   * verify-determinism --bisect` consumes this to name the (frame, node, op).
+   */
+  delta?: CommandDelta;
+}
+/**
+ * Evaluate two fresh scenes from `createScene` at `t` and confirm the
+ * DisplayLists are byte-identical. Returns `{ ok: true }` for a pure scene, or
+ * `{ ok: false, node }` naming the first divergent node. DEV-only — never on
+ * the render hot path.
+ */
+declare function auditCacheCold(createScene: () => Scene, doc: Timeline, t: number): CacheColdResult;
+//#endregion
+//#region src/tokenHighlight.d.ts
+interface TokenRange {
+  /** token text (whitespace-insensitive run match) or inclusive [from, to] wordBoxes indices */
+  match: string | readonly [number, number];
+  /** which occurrence of a string match; default 1 (the first) */
+  occurrence?: number;
+  /** range id for track targets ('<nodeId>/<rangeId>/fill' …); default 'r<index>' */
+  id?: string;
+  fill?: PropInit<string>;
+  opacity?: PropInit<number>;
+  /** 0→1 left-to-right reveal across the range; default 1 */
+  progress?: PropInit<number>;
+  /** scale about the range rect's center; default 1 */
+  scale?: PropInit<number>;
+  /** translation of the range's rects, px — shakes and nudges; default [0, 0] */
+  offset?: PropInit<Vec2>;
+}
+interface TokenHighlightProps extends NodeProps {
+  /** the Text whose tokens get highlighted; place this node as an EARLIER sibling */
+  text: Text;
+  ranges: TokenRange[];
+  /** marker overhang beyond the ink box, [x, y] px; default [4, 2] */
+  padding?: [number, number];
+  cornerRadius?: number;
+  /** re-resolve string matches every frame (animated text); default false — drift throws */
+  rematch?: boolean;
+}
+declare class TokenMatchError extends Error {
+  constructor(message: string);
+}
+/**
+ * Find the Nth whitespace-stripped consecutive run of boxes equal to token.
+ * Boundary-exact: a run that diverges mid-segment is not a match; ending
+ * mid-segment throws (with the real segment list) rather than half-boxing.
+ */
+declare function matchTokenRun(boxes: WordBox[], token: string, occurrence?: number): [number, number];
+declare class TokenHighlight extends Node {
+  readonly target: Text;
+  readonly padding: [number, number];
+  readonly cornerRadius: number;
+  readonly rematch: boolean;
+  private readonly ranges;
+  constructor(props: TokenHighlightProps);
+  private resolveRun;
+  protected draw(out: DisplayListBuilder, ctx: EvalContext): void;
+}
+/**
+ * `children: [tokenHighlight(para, { ranges: [{ match: '$48,200', fill: cat.money }] }), para]`
+ * — each range animates independently via '<id>/<rangeId>/fill|opacity|progress|scale'.
+ */
+declare function tokenHighlight(text: Text, props: Omit<TokenHighlightProps, 'text'>): TokenHighlight;
+//#endregion
+export { type CacheColdResult, type CommandDelta, DL_SNAPSHOT_VERSION, type DisplayDiff, type DlSnapshot, DlSnapshotError, type FieldChange, TokenHighlight, type TokenHighlightProps, TokenMatchError, type TokenRange, auditCacheCold, collapseReplacer, diffDisplayLists, formatDisplayDiff, matchTokenRun, parseDisplaySnapshot, serializeDisplayList, tokenHighlight };