@glissade/scene 0.5.0-pre.1 → 0.5.0-pre.3

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { $ as StrokeStyle, A as NodeProps, B as BlendMode, C as WordBox, D as EvalContext, E as BindablePropTarget, F as breakLines, G as FilterValidationError, H as DisplayListBuilder, I as estimatingMeasurer, J as PathSeg, K as FontSpec, L as quantize, M as resolveAnchor, N as TextMeasurer, O as HitArea, P as TextMetricsLite, Q as ShaderRef, R as segmentWords, S as VideoProps, T as AnchorSpec, U as DrawCommand, V as DisplayList, W as FilterSpec, X as Resource, Y as Rect$1, Z as ResourceId, _ as Rect, a as LayoutEngineMissingError, at as Mat2x3, b as TextProps, c as requireLayoutEngine, ct as invert, d as Group, et as createDisplayListBuilder, f as ImageNode, g as PathProps, h as Path, i as LayoutEngine, it as IDENTITY, j as PropInit, k as Node, l as setLayoutEngine, lt as matEquals, m as LineBox, n as LayoutChildSpec, nt as glow, ot as applyToPoint, p as ImageProps, q as Paint, r as LayoutContainerSpec, rt as validateFilters, s as getLayoutEngine, st as fromTRS, t as LayoutBox, tt as filtersToCanvasFilter, u as Circle, ut as multiply, v as ShapeProps, w as roundedRectSegs, x as Video, y as Text, z as setDefaultMeasurer } from "./layoutEngine.js";
-import { BindableSignal, BoundTimeline, CompiledTimeline, Playhead, Timeline, Vec2 } from "@glissade/core";
+import { $ as Resource, A as HitArea, B as segmentGraphemes, C as VideoProps, D as AnchorSpec, E as roundedRectSegs, F as TextMeasurer, G as DisplayListBuilder, H as setDefaultMeasurer, I as TextMetricsLite, J as FilterValidationError, K as DrawCommand, L as breakLines, M as NodeProps, N as PropInit, O as BindablePropTarget, P as resolveAnchor, Q as Rect$1, R as estimatingMeasurer, S as Video, T as revealSchedule, U as BlendMode, V as segmentWords, W as DisplayList, X as Paint, Y as FontSpec, Z as PathSeg, _ as Rect, a as LayoutEngineMissingError, at as glow, b as Text, c as requireLayoutEngine, ct as Mat2x3, d as Group, dt as invert, et as ResourceId, f as ImageNode, ft as matEquals, g as PathProps, h as Path, i as LayoutEngine, it as filtersToCanvasFilter, j as Node, k as EvalContext, l as setLayoutEngine, lt as applyToPoint, m as LineBox, n as LayoutChildSpec, nt as StrokeStyle, ot as validateFilters, p as ImageProps, pt as multiply, q as FilterSpec, r as LayoutContainerSpec, rt as createDisplayListBuilder, s as getLayoutEngine, st as IDENTITY, t as LayoutBox, tt as ShaderRef, u as Circle, ut as fromTRS, v as RevealMark, w as WordBox, x as TextProps, y as ShapeProps, z as quantize } from "./layoutEngine.js";
+import { BindableSignal, BoundTimeline, CompiledTimeline, PathValue, Playhead, Timeline, Track, Vec2 } from "@glissade/core";
 
 //#region src/highlight.d.ts
 
@@ -28,6 +28,135 @@ declare class Highlight extends Node {
 /** `children: [highlight(title, { color: '#ffe066' }), title]` — marker behind the text. */
 declare function highlight(text: Text, props?: Omit<HighlightProps, 'text'>): Highlight;
 //#endregion
+//#region src/textCursor.d.ts
+interface TextCursorProps extends NodeProps {
+  /** The Text whose reveal head the caret follows. Place as a sibling. */
+  text: Text;
+  /** Blink period in seconds (full on+off cycle); default 1.06 (~0.53s each). */
+  blinkPeriod?: number;
+  /** Blink phase offset in seconds; default 0. */
+  blinkPhase?: number;
+  /** Stay solid (no blink) while the reveal is still advancing; default true. */
+  solidWhileTyping?: boolean;
+  /** Caret width in px; default 2. */
+  width?: number;
+  /** Caret color; default '' = follow the Text's fill. Track '<id>/fill'. */
+  fill?: PropInit<string>;
+}
+declare class TextCursor extends Node {
+  readonly target: Text;
+  readonly blinkPeriod: number;
+  readonly blinkPhase: number;
+  readonly solidWhileTyping: boolean;
+  readonly caretWidth: number;
+  readonly fill: BindableSignal<string>;
+  constructor(props: TextCursorProps);
+  protected draw(out: DisplayListBuilder, ctx: EvalContext): void;
+}
+/** `children: [title, textCursor(title)]` — a caret riding the reveal head. */
+declare function textCursor(text: Text, props?: Omit<TextCursorProps, 'text'>): TextCursor;
+//#endregion
+//#region src/typewriter.d.ts
+/** One step of a typewriter performance. */
+interface TypeEdit {
+  /** graphemes to type in, one keystroke at a time */
+  type?: string;
+  /** graphemes to backspace, one keystroke at a time */
+  delete?: number;
+  /** seconds to hold the current text before the next step (a pause beat) */
+  hold?: number;
+  /** seconds per keystroke for THIS step; overrides the global perChar */
+  perChar?: number;
+}
+/** One keystroke in the compiled schedule — the keystroke-SFX contract,
+ * extended with `kind` so a backspace can take a different sample. */
+interface EditMark {
+  /** keystroke time, absolute timeline seconds */
+  time: number;
+  /** a character appeared (insert) or was removed (delete/backspace) */
+  kind: 'insert' | 'delete';
+  /** the grapheme inserted, or the one removed */
+  grapheme: string;
+  /** the full visible string AFTER this keystroke */
+  value: string;
+}
+interface TypewriterResult {
+  /** hold-key string track for the Text node's `<id>/text` target */
+  track: Track<string>;
+  /** every keystroke (insert + delete), for keystroke SFX */
+  marks: EditMark[];
+  /** time of the last keystroke or hold — the performance's end */
+  duration: number;
+}
+/**
+ * Compile an edit script into a string track + keystroke schedule.
+ *
+ *   const tw = typewriter('prompt/text', [
+ *     { type: 'make it pop' },
+ *     { hold: 0.4 },
+ *     { delete: 3 },            // backspace 'pop'
+ *     { type: 'sing' },
+ *   ]);
+ *   // tracks: [tw.track, ...]; keystroke SFX: keystrokeClips(tw.marks, ...)
+ */
+declare function typewriter(target: string, edits: readonly TypeEdit[], opts?: {
+  start?: number;
+  perChar?: number;
+}): TypewriterResult;
+//#endregion
+//#region src/motionPath.d.ts
+/** An arc-length-parameterized sampler over a path. */
+interface PathSampler {
+  /** total arc length */
+  readonly length: number;
+  /** point at arc-length s (clamped to [0, length]) */
+  at(s: number): Vec2;
+  /** unit tangent at arc-length s (forward direction of travel) */
+  tangentAt(s: number): Vec2;
+  /** point at normalized progress u in [0, 1] */
+  atProgress(u: number): Vec2;
+  /** unit tangent at normalized progress u in [0, 1] */
+  tangentAtProgress(u: number): Vec2;
+}
+/**
+ * Build a reusable arc-length sampler. Densely samples each cubic into a
+ * cumulative-length polyline (samplesPerSegment, default 32) so `at`/`tangent`
+ * are simple span lerps — smooth enough for motion, no per-call bezier solve.
+ */
+declare function motionPath(path: PathValue, opts?: {
+  samplesPerSegment?: number;
+}): PathSampler;
+/** Total arc length of a path. */
+declare function pathLength(path: PathValue): number;
+/** Point at arc-length s along a path (clamped to [0, length]). */
+declare function pointAtLength(path: PathValue, s: number): Vec2;
+interface FollowPathProps extends NodeProps {
+  /** the node to move along the path; its position (and rotation, if orient) is owned by this */
+  target: Node;
+  path: PathValue;
+  /** 0→1 position along the path's arc length; default 1 (the end). Track `<id>/progress`. */
+  progress?: PropInit<number>;
+  /** rotate the target to the path tangent — a cursor that points where it heads; default false */
+  orient?: boolean;
+  /** degrees added to the orient angle (e.g. if the sprite points up at rest) */
+  orientOffset?: number;
+  samplesPerSegment?: number;
+}
+/**
+ * A companion node that drives `target` along `path` as `progress` animates.
+ * Owns the target's `position` (and `rotation` when `orient`) via pull-based
+ * binding, so there's no eval-order side effect. Add it to the scene (its
+ * `progress` is the animatable target); it draws nothing itself.
+ */
+declare class FollowPath extends Node {
+  readonly target: Node;
+  readonly progress: BindableSignal<number>;
+  constructor(props: FollowPathProps);
+  protected draw(): void;
+}
+/** `children: [route, cursor, followPath(cursor, route, { orient: true })]` — cursor traces the route. */
+declare function followPath(target: Node, path: PathValue | Path, props?: Omit<FollowPathProps, 'target' | 'path'>): FollowPath;
+//#endregion
 //#region src/tokenHighlight.d.ts
 interface TokenRange {
   /** token text (whitespace-insensitive run match) or inclusive [from, to] wordBoxes indices */
@@ -270,4 +399,4 @@ declare function bindScene(scene: Scene, doc: Timeline): BindingCacheEntry;
  */
 declare function evaluate(scene: Scene, doc: Timeline, t: number): DisplayList;
 //#endregion
-export { type AnchorSpec, type BindablePropTarget, type BlendMode, type CanvasLike, Circle, ColdAssetError, type Ctx2DLike, type DisplayList, type DisplayListBuilder, type DrawCommand, DuplicateNodeIdError, type EvalContext, type FilterSpec, FilterValidationError, type FontSpec, Group, Highlight, type HighlightProps, type HitArea, IDENTITY, type ImageHandle, ImageNode, type ImageProps, type LayoutBox, type LayoutChildSpec, type LayoutContainerSpec, type LayoutEngine, LayoutEngineMissingError, type LineBox, type Mat2x3, Node, type NodeProps, type Paint, Path, type PathLike, type PathProps, type PathSeg, type PropInit, Raster2D, type Raster2DHost, Rect, type Rect$1 as RectShape, type Resource, type ResourceId, type Scene, type SceneInit, type SceneModule, type ShaderCaps, ShaderEffect, type ShaderEffectProps, type ShaderRef, type ShapeProps, type StrokeStyle, Text, type TextMeasurer, type TextMetricsLite, type TextProps, TokenHighlight, type TokenHighlightProps, TokenMatchError, type TokenRange, Video, type VideoFrameSource, type VideoProps, type WordBox, applyToPoint, bindScene, breakLines, createDisplayListBuilder, createScene, estimatingMeasurer, evaluate, filtersToCanvasFilter, fontString, fromTRS, getLayoutEngine, glow, highlight, invert, matEquals, matchTokenRun, multiply, quantize, requireLayoutEngine, resolveAnchor, roundedRectSegs, segmentWords, setDefaultMeasurer, setLayoutEngine, tokenHighlight, validateFilters };
+export { type AnchorSpec, type BindablePropTarget, type BlendMode, type CanvasLike, Circle, ColdAssetError, type Ctx2DLike, type DisplayList, type DisplayListBuilder, type DrawCommand, DuplicateNodeIdError, type EditMark, type EvalContext, type FilterSpec, FilterValidationError, FollowPath, type FollowPathProps, type FontSpec, Group, Highlight, type HighlightProps, type HitArea, IDENTITY, type ImageHandle, ImageNode, type ImageProps, type LayoutBox, type LayoutChildSpec, type LayoutContainerSpec, type LayoutEngine, LayoutEngineMissingError, type LineBox, type Mat2x3, Node, type NodeProps, type Paint, Path, type PathLike, type PathProps, type PathSampler, type PathSeg, type PropInit, Raster2D, type Raster2DHost, Rect, type Rect$1 as RectShape, type Resource, type ResourceId, type RevealMark, type Scene, type SceneInit, type SceneModule, type ShaderCaps, ShaderEffect, type ShaderEffectProps, type ShaderRef, type ShapeProps, type StrokeStyle, Text, TextCursor, type TextCursorProps, type TextMeasurer, type TextMetricsLite, type TextProps, TokenHighlight, type TokenHighlightProps, TokenMatchError, type TokenRange, type TypeEdit, type TypewriterResult, Video, type VideoFrameSource, type VideoProps, type WordBox, applyToPoint, bindScene, breakLines, createDisplayListBuilder, createScene, estimatingMeasurer, evaluate, filtersToCanvasFilter, followPath, fontString, fromTRS, getLayoutEngine, glow, highlight, invert, matEquals, matchTokenRun, motionPath, multiply, pathLength, pointAtLength, quantize, requireLayoutEngine, resolveAnchor, revealSchedule, roundedRectSegs, segmentGraphemes, segmentWords, setDefaultMeasurer, setLayoutEngine, textCursor, tokenHighlight, typewriter, validateFilters };

package/dist/index.js

@@ -1,5 +1,5 @@
-import { A as matEquals, C as filtersToCanvasFilter, D as applyToPoint, E as IDENTITY, O as fromTRS, S as createDisplayListBuilder, T as validateFilters, _ as fallbackMeasurer, a as Circle, b as setDefaultMeasurer, c as Path, d as Video, f as roundedRectSegs, g as estimatingMeasurer, h as breakLines, i as setLayoutEngine, j as multiply, k as invert, l as Rect, m as resolveAnchor, n as getLayoutEngine, o as Group, p as Node, r as requireLayoutEngine, s as ImageNode, t as LayoutEngineMissingError, u as Text, v as quantize, w as glow, x as FilterValidationError, y as segmentWords } from "./layoutEngine.js";
-import { bindTimeline, compileTimeline, createPlayhead, emitDevWarning, evaluateAt, signal, vec2Signal } from "@glissade/core";
+import { A as fromTRS, C as FilterValidationError, D as validateFilters, E as glow, M as matEquals, N as multiply, O as IDENTITY, S as setDefaultMeasurer, T as filtersToCanvasFilter, _ as estimatingMeasurer, a as Circle, b as segmentGraphemes, c as Path, d as Video, f as revealSchedule, g as breakLines, h as resolveAnchor, i as setLayoutEngine, j as invert, k as applyToPoint, l as Rect, m as Node, n as getLayoutEngine, o as Group, p as roundedRectSegs, r as requireLayoutEngine, s as ImageNode, t as LayoutEngineMissingError, u as Text, v as fallbackMeasurer, w as createDisplayListBuilder, x as segmentWords, y as quantize } from "./layoutEngine.js";
+import { bindTimeline, compileTimeline, createPlayhead, emitDevWarning, evaluateAt, key, signal, track, vec2Signal } from "@glissade/core";
 //#region src/highlight.ts
 /**
 * Marker-style text highlight: per-line rounded rects behind a Text node's
@@ -19,8 +19,8 @@ var Highlight = class extends Node {
 	constructor(props) {
 		super(props);
 		this.target = props.text;
-		this.color = init$1(signal("#ffe066"), props.color);
-		this.progress = init$1(signal(1), props.progress);
+		this.color = init$2(signal("#ffe066"), props.color);
+		this.progress = init$2(signal(1), props.progress);
 		this.padding = props.padding ?? [4, 2];
 		this.cornerRadius = props.cornerRadius ?? 4;
 		this.registerTarget("progress", this.progress);
@@ -73,12 +73,310 @@ function highlight(text, props = {}) {
 		text
 	});
 }
+function init$2(sig, v) {
+	if (typeof v === "function") sig.bindSource(v);
+	else if (v !== void 0) sig.set(v);
+	return sig;
+}
+//#endregion
+//#region src/textCursor.ts
+/**
+* Terminal-style caret for a Text node's typewriter reveal: a thin vertical bar
+* at Text.revealHead(), so it rides the reveal head as graphemes appear and
+* re-flows with wrap width, font, and align. Pure data, both backends,
+* golden-coverable — the bar is draw() output, not a child node. Place this as
+* a sibling of the Text (same parent) so it shares its transform.
+*
+* Blink is a pure function of ctx.time: on for the first half of each period.
+* With solidWhileTyping (default), the caret stays solid while the reveal is
+* still advancing (reveal < total) and only blinks once the text is fully
+* shown — the familiar "types solid, then blinks waiting" terminal feel.
+*/
+var TextCursor = class extends Node {
+	target;
+	blinkPeriod;
+	blinkPhase;
+	solidWhileTyping;
+	caretWidth;
+	fill;
+	constructor(props) {
+		super(props);
+		this.target = props.text;
+		this.blinkPeriod = props.blinkPeriod ?? 1.06;
+		this.blinkPhase = props.blinkPhase ?? 0;
+		this.solidWhileTyping = props.solidWhileTyping ?? true;
+		this.caretWidth = props.width ?? 2;
+		this.fill = init$1(signal(""), props.fill);
+		this.registerTarget("fill", this.fill);
+	}
+	draw(out, ctx) {
+		const head = this.target.revealHead(ctx.measurer);
+		if (head.h <= 0) return;
+		let on = true;
+		const total = this.target.graphemes(ctx.measurer).length;
+		const typing = head.index < total;
+		if (!(this.solidWhileTyping && typing)) {
+			const period = this.blinkPeriod > 0 ? this.blinkPeriod : 1;
+			on = ((ctx.time - this.blinkPhase) % period + period) % period < period / 2;
+		}
+		if (!on) return;
+		const tm = this.target.localMatrix();
+		if (!matEquals(tm, IDENTITY)) out.push({
+			op: "transform",
+			m: tm
+		});
+		const color = this.fill() || this.target.fill();
+		const path = out.resource({
+			kind: "path",
+			segs: roundedRectSegs(head.x, head.y, this.caretWidth, head.h, 0)
+		});
+		out.push({
+			op: "fillPath",
+			path,
+			paint: {
+				kind: "color",
+				color
+			}
+		});
+	}
+};
+/** `children: [title, textCursor(title)]` — a caret riding the reveal head. */
+function textCursor(text, props = {}) {
+	return new TextCursor({
+		...props,
+		text
+	});
+}
 function init$1(sig, v) {
 	if (typeof v === "function") sig.bindSource(v);
 	else if (v !== void 0) sig.set(v);
 	return sig;
 }
 //#endregion
+//#region src/typewriter.ts
+/**
+* Edit-event-aware typewriter authoring. `Text.reveal` is monotonic sugar for
+* the type-only case; real terminal cold-opens type, delete, and retype. Since
+* `Text.text` is itself a signal, the honest substrate is a hold-key STRING
+* track that carries the visible text after every keystroke — including
+* backspaces. This compiles a compact edit script into that track plus a
+* per-keystroke schedule (deletes included) for keystroke SFX.
+*
+* Drive `Text.text` with the returned track and leave `reveal` at its default
+* (Infinity): the whole current string shows, so deletion just works, and
+* `textCursor` rides the end of the live text with no extra wiring.
+*/
+const DEFAULT_PER_CHAR = .06;
+/**
+* Compile an edit script into a string track + keystroke schedule.
+*
+*   const tw = typewriter('prompt/text', [
+*     { type: 'make it pop' },
+*     { hold: 0.4 },
+*     { delete: 3 },            // backspace 'pop'
+*     { type: 'sing' },
+*   ]);
+*   // tracks: [tw.track, ...]; keystroke SFX: keystrokeClips(tw.marks, ...)
+*/
+function typewriter(target, edits, opts = {}) {
+	const start = opts.start ?? 0;
+	const globalPer = opts.perChar ?? DEFAULT_PER_CHAR;
+	let t = start;
+	const shown = [];
+	const keys = [key(start, "", { interp: "hold" })];
+	const marks = [];
+	for (const edit of edits) {
+		const per = edit.perChar ?? globalPer;
+		if (edit.type !== void 0) for (const g of segmentGraphemes(edit.type)) {
+			t += per;
+			shown.push(g);
+			const value = shown.join("");
+			keys.push(key(t, value, { interp: "hold" }));
+			marks.push({
+				time: t,
+				kind: "insert",
+				grapheme: g,
+				value
+			});
+		}
+		if (edit.delete !== void 0) for (let i = 0; i < edit.delete && shown.length > 0; i++) {
+			t += per;
+			const removed = shown.pop();
+			const value = shown.join("");
+			keys.push(key(t, value, { interp: "hold" }));
+			marks.push({
+				time: t,
+				kind: "delete",
+				grapheme: removed,
+				value
+			});
+		}
+		if (edit.hold !== void 0) t += edit.hold;
+	}
+	return {
+		track: track(target, "string", keys),
+		marks,
+		duration: t
+	};
+}
+//#endregion
+//#region src/motionPath.ts
+/**
+* Motion along a path: sample a point (and tangent) at an arc-length position on
+* a PathValue, and drive a node along it over time. The Path node draws/morphs
+* geometry; this is the companion that makes another node — a cursor, a dot, an
+* arrow — *travel* that geometry.
+*
+* Sampling is arc-length parameterized (constant speed), so progress 0→1 moves
+* evenly instead of bunching at the control points. Pure and deterministic: the
+* table is built once from a static PathValue and `atProgress` is a pure
+* function of progress, so evaluate() stays pure and goldens are byte-stable.
+*/
+const clamp01 = (v) => v < 0 ? 0 : v > 1 ? 1 : v;
+function cubicPoint(p0, p1, p2, p3, t) {
+	const mt = 1 - t;
+	const a = mt * mt * mt;
+	const b = 3 * mt * mt * t;
+	const c = 3 * mt * t * t;
+	const d = t * t * t;
+	return [a * p0[0] + b * p1[0] + c * p2[0] + d * p3[0], a * p0[1] + b * p1[1] + c * p2[1] + d * p3[1]];
+}
+/** PathValue contours → cubic segments, same v/in/out math as Path.pathSegs. */
+function toCubics(path) {
+	const out = [];
+	for (const ct of path) {
+		const n = ct.v.length;
+		for (let i = 0; i < n - 1; i++) out.push([
+			ct.v[i],
+			[ct.v[i][0] + ct.out[i][0], ct.v[i][1] + ct.out[i][1]],
+			[ct.v[i + 1][0] + ct.in[i + 1][0], ct.v[i + 1][1] + ct.in[i + 1][1]],
+			ct.v[i + 1]
+		]);
+		if (ct.closed && n > 1) out.push([
+			ct.v[n - 1],
+			[ct.v[n - 1][0] + ct.out[n - 1][0], ct.v[n - 1][1] + ct.out[n - 1][1]],
+			[ct.v[0][0] + ct.in[0][0], ct.v[0][1] + ct.in[0][1]],
+			ct.v[0]
+		]);
+	}
+	return out;
+}
+/**
+* Build a reusable arc-length sampler. Densely samples each cubic into a
+* cumulative-length polyline (samplesPerSegment, default 32) so `at`/`tangent`
+* are simple span lerps — smooth enough for motion, no per-call bezier solve.
+*/
+function motionPath(path, opts = {}) {
+	const steps = Math.max(1, Math.floor(opts.samplesPerSegment ?? 32));
+	const cubics = toCubics(path);
+	const pts = [];
+	const cum = [];
+	if (cubics.length > 0) {
+		let prev = cubicPoint(...cubics[0], 0);
+		pts.push(prev);
+		cum.push(0);
+		let acc = 0;
+		for (const cub of cubics) for (let k = 1; k <= steps; k++) {
+			const p = cubicPoint(...cub, k / steps);
+			acc += Math.hypot(p[0] - prev[0], p[1] - prev[1]);
+			pts.push(p);
+			cum.push(acc);
+			prev = p;
+		}
+	} else {
+		const first = path[0]?.v[0];
+		pts.push(first ? [first[0], first[1]] : [0, 0]);
+		cum.push(0);
+	}
+	const total = cum[cum.length - 1];
+	const locate = (s) => {
+		if (total <= 0 || s <= 0) return {
+			i: 0,
+			f: 0
+		};
+		if (s >= total) return {
+			i: pts.length - 2,
+			f: 1
+		};
+		let i = 0;
+		while (i < cum.length - 1 && cum[i + 1] < s) i++;
+		const span = cum[i + 1] - cum[i];
+		return {
+			i,
+			f: span > 0 ? (s - cum[i]) / span : 0
+		};
+	};
+	const at = (s) => {
+		if (pts.length === 1) return [pts[0][0], pts[0][1]];
+		const { i, f } = locate(s);
+		const a = pts[i];
+		const b = pts[i + 1];
+		return [a[0] + (b[0] - a[0]) * f, a[1] + (b[1] - a[1]) * f];
+	};
+	const tangentAt = (s) => {
+		if (pts.length === 1) return [1, 0];
+		const { i } = locate(s);
+		const a = pts[i];
+		const b = pts[i + 1];
+		const dx = b[0] - a[0];
+		const dy = b[1] - a[1];
+		const len = Math.hypot(dx, dy);
+		return len > 0 ? [dx / len, dy / len] : [1, 0];
+	};
+	return {
+		length: total,
+		at,
+		tangentAt,
+		atProgress: (u) => at(clamp01(u) * total),
+		tangentAtProgress: (u) => tangentAt(clamp01(u) * total)
+	};
+}
+/** Total arc length of a path. */
+function pathLength(path) {
+	return motionPath(path).length;
+}
+/** Point at arc-length s along a path (clamped to [0, length]). */
+function pointAtLength(path, s) {
+	return motionPath(path).at(s);
+}
+/**
+* A companion node that drives `target` along `path` as `progress` animates.
+* Owns the target's `position` (and `rotation` when `orient`) via pull-based
+* binding, so there's no eval-order side effect. Add it to the scene (its
+* `progress` is the animatable target); it draws nothing itself.
+*/
+var FollowPath = class extends Node {
+	target;
+	progress;
+	constructor(props) {
+		super(props);
+		this.target = props.target;
+		this.progress = signal(1);
+		if (typeof props.progress === "function") this.progress.bindSource(props.progress);
+		else if (props.progress !== void 0) this.progress.set(props.progress);
+		this.registerTarget("progress", this.progress);
+		const sampler = motionPath(props.path, props.samplesPerSegment !== void 0 ? { samplesPerSegment: props.samplesPerSegment } : {});
+		props.target.position.bindSource(() => sampler.atProgress(this.progress()));
+		if (props.orient) {
+			const offset = props.orientOffset ?? 0;
+			props.target.rotation.bindSource(() => {
+				const t = sampler.tangentAtProgress(this.progress());
+				return Math.atan2(t[1], t[0]) * 180 / Math.PI + offset;
+			});
+		}
+	}
+	draw() {}
+};
+/** `children: [route, cursor, followPath(cursor, route, { orient: true })]` — cursor traces the route. */
+function followPath(target, path, props = {}) {
+	const pv = path instanceof Path ? path.data() : path;
+	return new FollowPath({
+		...props,
+		target,
+		path: pv
+	});
+}
+//#endregion
 //#region src/tokenHighlight.ts
 /**
 * Multi-range token highlight: sub-line ranges over a Text node's wordBoxes,
@@ -752,4 +1050,4 @@ function evaluate(scene, doc, t) {
 	});
 }
 //#endregion
-export { Circle, ColdAssetError, DuplicateNodeIdError, FilterValidationError, Group, Highlight, IDENTITY, ImageNode, LayoutEngineMissingError, Node, Path, Raster2D, Rect, ShaderEffect, Text, TokenHighlight, TokenMatchError, Video, applyToPoint, bindScene, breakLines, createDisplayListBuilder, createScene, estimatingMeasurer, evaluate, filtersToCanvasFilter, fontString, fromTRS, getLayoutEngine, glow, highlight, invert, matEquals, matchTokenRun, multiply, quantize, requireLayoutEngine, resolveAnchor, roundedRectSegs, segmentWords, setDefaultMeasurer, setLayoutEngine, tokenHighlight, validateFilters };
+export { Circle, ColdAssetError, DuplicateNodeIdError, FilterValidationError, FollowPath, Group, Highlight, IDENTITY, ImageNode, LayoutEngineMissingError, Node, Path, Raster2D, Rect, ShaderEffect, Text, TextCursor, TokenHighlight, TokenMatchError, Video, applyToPoint, bindScene, breakLines, createDisplayListBuilder, createScene, estimatingMeasurer, evaluate, filtersToCanvasFilter, followPath, fontString, fromTRS, getLayoutEngine, glow, highlight, invert, matEquals, matchTokenRun, motionPath, multiply, pathLength, pointAtLength, quantize, requireLayoutEngine, resolveAnchor, revealSchedule, roundedRectSegs, segmentGraphemes, segmentWords, setDefaultMeasurer, setLayoutEngine, textCursor, tokenHighlight, typewriter, validateFilters };

package/dist/layout.d.ts

@@ -1,4 +1,4 @@
-import { A as NodeProps, D as EvalContext, H as DisplayListBuilder, N as TextMeasurer, a as LayoutEngineMissingError, d as Group, i as LayoutEngine, j as PropInit, k as Node, l as setLayoutEngine, n as LayoutChildSpec, o as LayoutResult, r as LayoutContainerSpec, s as getLayoutEngine, t as LayoutBox } from "./layoutEngine.js";
+import { F as TextMeasurer, G as DisplayListBuilder, M as NodeProps, N as PropInit, a as LayoutEngineMissingError, d as Group, i as LayoutEngine, j as Node, k as EvalContext, l as setLayoutEngine, n as LayoutChildSpec, o as LayoutResult, r as LayoutContainerSpec, s as getLayoutEngine, t as LayoutBox } from "./layoutEngine.js";
 import { BindableSignal } from "@glissade/core";
 
 //#region src/layout.d.ts

package/dist/layout.js

@@ -1,4 +1,4 @@
-import { _ as fallbackMeasurer, i as setLayoutEngine, n as getLayoutEngine, o as Group, r as requireLayoutEngine, t as LayoutEngineMissingError } from "./layoutEngine.js";
+import { i as setLayoutEngine, n as getLayoutEngine, o as Group, r as requireLayoutEngine, t as LayoutEngineMissingError, v as fallbackMeasurer } from "./layoutEngine.js";
 import { signal } from "@glissade/core";
 //#region src/layout.ts
 /**

package/dist/layoutEngine.d.ts

@@ -1,4 +1,4 @@
-import { BindableSignal, PathValue, ReadonlySignal, Vec2, Vec2Signal } from "@glissade/core";
+import { BindableSignal, PathValue, ReadonlySignal, Track, Vec2, Vec2Signal } from "@glissade/core";
 
 //#region src/matrix.d.ts
 
@@ -206,6 +206,12 @@ declare const estimatingMeasurer: TextMeasurer;
  * units the breaker flows.
  */
 declare function segmentWords(text: string): string[];
+/**
+ * Split text into graphemes (user-perceived characters). Exported so Text.draw
+ * (reveal masking), Text.graphemes() (authoring), and revealSchedule() (the SFX
+ * keystroke contract) all count the SAME units.
+ */
+declare function segmentGraphemes(text: string): string[];
 /**
  * Greedy line breaking: explicit '\n' always breaks; otherwise word segments
  * flow until maxWidth is exceeded (Intl.Segmenter boundaries, so CJK wraps
@@ -511,6 +517,13 @@ interface TextProps extends NodeProps {
   width?: PropInit<number>;
   /** Line height as a multiple of fontSize; default 1.25. */
   lineHeight?: number;
+  /**
+   * Typewriter reveal: how many graphemes of the laid-out text are shown,
+   * left-to-right. Default Infinity = fully shown (byte-identical to no
+   * reveal, so existing goldens never shift). Track target '<id>/reveal';
+   * author a per-keystroke staircase off graphemes() — see revealSchedule().
+   */
+  reveal?: PropInit<number>;
 }
 declare class Text extends Node {
   readonly text: BindableSignal<string>;
@@ -521,6 +534,7 @@ declare class Text extends Node {
   readonly align: 'left' | 'center' | 'right';
   readonly width: BindableSignal<number>;
   readonly lineHeight: number;
+  readonly reveal: BindableSignal<number>;
   constructor(props?: TextProps);
   intrinsicSize(measurer: TextMeasurer): {
     w: number;
@@ -557,8 +571,59 @@ declare class Text extends Node {
    * karaoke; draw your own rects for sub-line multi-color token work.
    */
   wordBoxes(measurer?: TextMeasurer): WordBox[];
+  /**
+   * The laid-out grapheme stream the typewriter reveal advances over — every
+   * grapheme of every wrapped line, in reading order (soft-wrap whitespace is
+   * dropped by the breaker, exactly as drawn, so draw/revealHead/revealSchedule
+   * all agree). Pull-based; its length is the `reveal` count that shows
+   * everything. Author a per-keystroke staircase straight off it:
+   *
+   *   const g = title.graphemes();
+   *   track('title/reveal', 'number',
+   *     g.map((_, i) => key(t0 + i * 0.05, i + 1, { interp: 'hold' })));
+   */
+  graphemes(measurer?: TextMeasurer): string[];
+  /**
+   * Draw-space position of the reveal head — the caret point just after the
+   * last revealed grapheme, for the current `reveal` value. Drives TextCursor;
+   * honours align and wrap exactly like wordBoxes(). At reveal 0 it sits at the
+   * start of the first line; fully revealed, at the end of the last line.
+   */
+  revealHead(measurer?: TextMeasurer): {
+    x: number;
+    y: number;
+    h: number;
+    line: number;
+    index: number;
+  };
   protected draw(out: DisplayListBuilder, ctx: EvalContext): void;
 }
+/** One revealed grapheme's timing + draw-space position — the keystroke sync
+ * contract, the direct analogue of narrate's TimedWord[]. SFX maps each mark to
+ * one AudioClip at `at: time`; visuals can place per-key effects at (x, y). */
+interface RevealMark {
+  /** index into the laid-out grapheme stream (Text.graphemes()) */
+  charIndex: number;
+  /** the revealed grapheme (raw — char-class policy is the consumer's) */
+  grapheme: string;
+  /** time the grapheme first becomes visible, from the reveal track */
+  time: number;
+  /** caret x just after this grapheme, in the Text's draw space */
+  x: number;
+  /** top of the grapheme's line box, in the Text's draw space */
+  y: number;
+  /** laid-out line index */
+  line: number;
+}
+/**
+ * Pure per-grapheme schedule from a Text and its reveal track — geometry from
+ * the text, timing from the track. A grapheme's time is the first key whose
+ * value reveals it (value >= index + 1); graphemes the track never reaches are
+ * omitted. The single source SFX keystroke-sync consumes (keystrokeClips()):
+ * one click per mark at `at: mark.time`, char-class policy (skip space/newline,
+ * pick a sample) decided downstream from `mark.grapheme`.
+ */
+declare function revealSchedule(text: Text, reveal: Track<number>, measurer?: TextMeasurer): RevealMark[];
 //#endregion
 //#region src/layoutEngine.d.ts
 /**
@@ -608,4 +673,4 @@ declare function setLayoutEngine(e: LayoutEngine): void;
 declare function getLayoutEngine(): LayoutEngine | null;
 declare function requireLayoutEngine(): LayoutEngine;
 //#endregion
-export { StrokeStyle as $, NodeProps as A, BlendMode as B, WordBox as C, EvalContext as D, BindablePropTarget as E, breakLines as F, FilterValidationError as G, DisplayListBuilder as H, estimatingMeasurer as I, PathSeg as J, FontSpec as K, quantize as L, resolveAnchor as M, TextMeasurer as N, HitArea as O, TextMetricsLite as P, ShaderRef as Q, segmentWords as R, VideoProps as S, AnchorSpec as T, DrawCommand as U, DisplayList as V, FilterSpec as W, Resource as X, Rect$1 as Y, ResourceId as Z, Rect as _, LayoutEngineMissingError as a, Mat2x3 as at, TextProps as b, requireLayoutEngine as c, invert as ct, Group as d, createDisplayListBuilder as et, ImageNode as f, PathProps as g, Path as h, LayoutEngine as i, IDENTITY as it, PropInit as j, Node as k, setLayoutEngine as l, matEquals as lt, LineBox as m, LayoutChildSpec as n, glow as nt, LayoutResult as o, applyToPoint as ot, ImageProps as p, Paint as q, LayoutContainerSpec as r, validateFilters as rt, getLayoutEngine as s, fromTRS as st, LayoutBox as t, filtersToCanvasFilter as tt, Circle as u, multiply as ut, ShapeProps as v, roundedRectSegs as w, Video as x, Text as y, setDefaultMeasurer as z };
+export { Resource as $, HitArea as A, segmentGraphemes as B, VideoProps as C, AnchorSpec as D, roundedRectSegs as E, TextMeasurer as F, DisplayListBuilder as G, setDefaultMeasurer as H, TextMetricsLite as I, FilterValidationError as J, DrawCommand as K, breakLines as L, NodeProps as M, PropInit as N, BindablePropTarget as O, resolveAnchor as P, Rect$1 as Q, estimatingMeasurer as R, Video as S, revealSchedule as T, BlendMode as U, segmentWords as V, DisplayList as W, Paint as X, FontSpec as Y, PathSeg as Z, Rect as _, LayoutEngineMissingError as a, glow as at, Text as b, requireLayoutEngine as c, Mat2x3 as ct, Group as d, invert as dt, ResourceId as et, ImageNode as f, matEquals as ft, PathProps as g, Path as h, LayoutEngine as i, filtersToCanvasFilter as it, Node as j, EvalContext as k, setLayoutEngine as l, applyToPoint as lt, LineBox as m, LayoutChildSpec as n, StrokeStyle as nt, LayoutResult as o, validateFilters as ot, ImageProps as p, multiply as pt, FilterSpec as q, LayoutContainerSpec as r, createDisplayListBuilder as rt, getLayoutEngine as s, IDENTITY as st, LayoutBox as t, ShaderRef as tt, Circle as u, fromTRS as ut, RevealMark as v, WordBox as w, TextProps as x, ShapeProps as y, quantize as z };

package/dist/layoutEngine.js

@@ -198,6 +198,17 @@ function segmentWords(text) {
 	}
 	return text.split(/(\s+)/).filter((w) => w.length > 0);
 }
+let graphemeSegmenter;
+/**
+* Split text into graphemes (user-perceived characters). Exported so Text.draw
+* (reveal masking), Text.graphemes() (authoring), and revealSchedule() (the SFX
+* keystroke contract) all count the SAME units.
+*/
+function segmentGraphemes(text) {
+	if (graphemeSegmenter === void 0) graphemeSegmenter = typeof Intl !== "undefined" && "Segmenter" in Intl ? new Intl.Segmenter(void 0, { granularity: "grapheme" }) : null;
+	if (graphemeSegmenter) return [...graphemeSegmenter.segment(text)].map((s) => s.segment);
+	return Array.from(text);
+}
 /**
 * Greedy line breaking: explicit '\n' always breaks; otherwise word segments
 * flow until maxWidth is exceeded (Intl.Segmenter boundaries, so CJK wraps
@@ -849,6 +860,7 @@ var Text = class extends Node {
 	align;
 	width;
 	lineHeight;
+	reveal;
 	constructor(props = {}) {
 		super(props);
 		this.text = initProp(signal(""), props.text);
@@ -859,10 +871,12 @@ var Text = class extends Node {
 		this.align = props.align ?? "left";
 		this.width = initProp(signal(0), props.width);
 		this.lineHeight = props.lineHeight ?? 1.25;
+		this.reveal = initProp(signal(Number.POSITIVE_INFINITY), props.reveal);
 		this.registerTarget("width", this.width);
 		this.registerTarget("text", this.text);
 		this.registerTarget("fill", this.fill);
 		this.registerTarget("fontSize", this.fontSize);
+		this.registerTarget("reveal", this.reveal);
 	}
 	intrinsicSize(measurer) {
 		const text = this.text();
@@ -993,6 +1007,85 @@ var Text = class extends Node {
 		}
 		return boxes;
 	}
+	/**
+	* The laid-out grapheme stream the typewriter reveal advances over — every
+	* grapheme of every wrapped line, in reading order (soft-wrap whitespace is
+	* dropped by the breaker, exactly as drawn, so draw/revealHead/revealSchedule
+	* all agree). Pull-based; its length is the `reveal` count that shows
+	* everything. Author a per-keystroke staircase straight off it:
+	*
+	*   const g = title.graphemes();
+	*   track('title/reveal', 'number',
+	*     g.map((_, i) => key(t0 + i * 0.05, i + 1, { interp: 'hold' })));
+	*/
+	graphemes(measurer) {
+		const m = measurer ?? this.measurerSource?.() ?? fallbackMeasurer();
+		const text = this.text();
+		if (!text) return [];
+		const font = {
+			family: this.fontFamily,
+			size: this.fontSize(),
+			weight: this.fontWeight
+		};
+		const maxWidth = this.width();
+		const lines = breakLines(text, font, maxWidth > 0 ? maxWidth : void 0, m);
+		const out = [];
+		for (const line of lines) for (const g of segmentGraphemes(line)) out.push(g);
+		return out;
+	}
+	/**
+	* Draw-space position of the reveal head — the caret point just after the
+	* last revealed grapheme, for the current `reveal` value. Drives TextCursor;
+	* honours align and wrap exactly like wordBoxes(). At reveal 0 it sits at the
+	* start of the first line; fully revealed, at the end of the last line.
+	*/
+	revealHead(measurer) {
+		const m = measurer ?? this.measurerSource?.() ?? fallbackMeasurer();
+		const font = {
+			family: this.fontFamily,
+			size: this.fontSize(),
+			weight: this.fontWeight
+		};
+		const maxWidth = this.width();
+		const lines = breakLines(this.text(), font, maxWidth > 0 ? maxWidth : void 0, m);
+		const step = quantize(font.size * this.lineHeight);
+		const total = lines.reduce((n, l) => n + segmentGraphemes(l).length, 0);
+		const revealRaw = this.reveal();
+		const shown = Math.max(0, Math.min(Number.isFinite(revealRaw) ? Math.floor(revealRaw) : total, total));
+		let remaining = shown;
+		let last = {
+			x: 0,
+			y: 0,
+			h: 0,
+			line: 0,
+			index: shown
+		};
+		for (let i = 0; i < lines.length; i++) {
+			const line = lines[i] ?? "";
+			const met = m.measureText(line, font);
+			const lineW = quantize(met.width);
+			const lineX = this.align === "left" ? 0 : this.align === "center" ? -lineW / 2 : -lineW;
+			const y = i * step - met.ascent;
+			const h = met.ascent + met.descent;
+			const gs = segmentGraphemes(line);
+			if (remaining <= gs.length) return {
+				x: lineX + (remaining <= 0 ? 0 : m.measureText(gs.slice(0, remaining).join(""), font).width),
+				y,
+				h,
+				line: i,
+				index: shown
+			};
+			remaining -= gs.length;
+			last = {
+				x: lineX + met.width,
+				y,
+				h,
+				line: i,
+				index: shown
+			};
+		}
+		return last;
+	}
 	draw(out, ctx) {
 		const text = this.text();
 		if (!text) return;
@@ -1004,11 +1097,34 @@ var Text = class extends Node {
 		const maxWidth = this.width();
 		const lines = breakLines(text, font, maxWidth > 0 ? maxWidth : void 0, ctx.measurer);
 		const step = quantize(font.size * this.lineHeight);
+		const revealRaw = this.reveal();
+		const masked = Number.isFinite(revealRaw);
+		let remaining = masked ? Math.max(0, Math.floor(revealRaw)) : 0;
 		for (let i = 0; i < lines.length; i++) {
-			if (!lines[i]) continue;
-			out.push({
+			const line = lines[i];
+			if (!line) continue;
+			if (!masked) {
+				out.push({
+					op: "fillText",
+					text: line,
+					font,
+					paint: {
+						kind: "color",
+						color: this.fill()
+					},
+					x: 0,
+					y: i * step,
+					...this.align !== "left" ? { align: this.align } : {}
+				});
+				continue;
+			}
+			if (remaining <= 0) break;
+			const gs = segmentGraphemes(line);
+			const show = Math.min(remaining, gs.length);
+			remaining -= show;
+			if (show === gs.length) out.push({
 				op: "fillText",
-				text: lines[i],
+				text: line,
 				font,
 				paint: {
 					kind: "color",
@@ -1018,9 +1134,76 @@ var Text = class extends Node {
 				y: i * step,
 				...this.align !== "left" ? { align: this.align } : {}
 			});
+			else {
+				const lineW = quantize(ctx.measurer.measureText(line, font).width);
+				const lineX = this.align === "left" ? 0 : this.align === "center" ? -lineW / 2 : -lineW;
+				out.push({
+					op: "fillText",
+					text: gs.slice(0, show).join(""),
+					font,
+					paint: {
+						kind: "color",
+						color: this.fill()
+					},
+					x: lineX,
+					y: i * step
+				});
+			}
 		}
 	}
 };
+/**
+* Pure per-grapheme schedule from a Text and its reveal track — geometry from
+* the text, timing from the track. A grapheme's time is the first key whose
+* value reveals it (value >= index + 1); graphemes the track never reaches are
+* omitted. The single source SFX keystroke-sync consumes (keystrokeClips()):
+* one click per mark at `at: mark.time`, char-class policy (skip space/newline,
+* pick a sample) decided downstream from `mark.grapheme`.
+*/
+function revealSchedule(text, reveal, measurer) {
+	const m = measurer ?? text.measurerSource?.() ?? fallbackMeasurer();
+	const src = text.text();
+	if (!src) return [];
+	const font = {
+		family: text.fontFamily,
+		size: text.fontSize(),
+		weight: text.fontWeight
+	};
+	const maxWidth = text.width();
+	const lines = breakLines(src, font, maxWidth > 0 ? maxWidth : void 0, m);
+	const step = quantize(font.size * text.lineHeight);
+	const keys = reveal.keys;
+	const marks = [];
+	let k = 0;
+	for (let li = 0; li < lines.length; li++) {
+		const line = lines[li];
+		if (!line) continue;
+		const met = m.measureText(line, font);
+		const lineW = quantize(met.width);
+		const lineX = text.align === "left" ? 0 : text.align === "center" ? -lineW / 2 : -lineW;
+		const y = li * step - met.ascent;
+		let prefix = "";
+		for (const g of segmentGraphemes(line)) {
+			prefix += g;
+			const need = k + 1;
+			let time = Number.POSITIVE_INFINITY;
+			for (const key of keys) if (key.value >= need) {
+				time = key.t;
+				break;
+			}
+			if (Number.isFinite(time)) marks.push({
+				charIndex: k,
+				grapheme: g,
+				time,
+				x: lineX + m.measureText(prefix, font).width,
+				y,
+				line: li
+			});
+			k++;
+		}
+	}
+	return marks;
+}
 //#endregion
 //#region src/layoutEngine.ts
 var LayoutEngineMissingError = class extends Error {
@@ -1041,4 +1224,4 @@ function requireLayoutEngine() {
 	return engine;
 }
 //#endregion
-export { matEquals as A, filtersToCanvasFilter as C, applyToPoint as D, IDENTITY as E, fromTRS as O, createDisplayListBuilder as S, validateFilters as T, fallbackMeasurer as _, Circle as a, setDefaultMeasurer as b, Path as c, Video as d, roundedRectSegs as f, estimatingMeasurer as g, breakLines as h, setLayoutEngine as i, multiply as j, invert as k, Rect as l, resolveAnchor as m, getLayoutEngine as n, Group as o, Node as p, requireLayoutEngine as r, ImageNode as s, LayoutEngineMissingError as t, Text as u, quantize as v, glow as w, FilterValidationError as x, segmentWords as y };
+export { fromTRS as A, FilterValidationError as C, validateFilters as D, glow as E, matEquals as M, multiply as N, IDENTITY as O, setDefaultMeasurer as S, filtersToCanvasFilter as T, estimatingMeasurer as _, Circle as a, segmentGraphemes as b, Path as c, Video as d, revealSchedule as f, breakLines as g, resolveAnchor as h, setLayoutEngine as i, invert as j, applyToPoint as k, Rect as l, Node as m, getLayoutEngine as n, Group as o, roundedRectSegs as p, requireLayoutEngine as r, ImageNode as s, LayoutEngineMissingError as t, Text as u, fallbackMeasurer as v, createDisplayListBuilder as w, segmentWords as x, quantize as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/scene",
-  "version": "0.5.0-pre.1",
+  "version": "0.5.0-pre.3",
   "description": "glissade scene graph: nodes, transforms, DisplayList emission. Renderer-agnostic; zero DOM/Node dependencies.",
   "license": "Apache-2.0",
   "type": "module",
@@ -20,7 +20,7 @@
   ],
   "dependencies": {
     "yoga-layout": "^3.2.1",
-    "@glissade/core": "0.5.0-pre.1"
+    "@glissade/core": "0.5.0-pre.3"
   },
   "repository": {
     "type": "git",