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

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-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 { $ as ResourceId, A as HitArea, B as segmentWords, C as VideoProps, D as AnchorSpec, E as roundedRectSegs, F as TextMeasurer, G as DrawCommand, H as BlendMode, I as TextMetricsLite, J as FontSpec, K as FilterSpec, L as breakLines, M as NodeProps, N as PropInit, O as BindablePropTarget, P as resolveAnchor, Q as Resource, R as estimatingMeasurer, S as Video, T as revealSchedule, U as DisplayList, V as setDefaultMeasurer, W as DisplayListBuilder, X as PathSeg, Y as Paint, Z as Rect$1, _ as Rect, a as LayoutEngineMissingError, at as validateFilters, b as Text, c as requireLayoutEngine, ct as applyToPoint, d as Group, dt as matEquals, et as ShaderRef, f as ImageNode, ft as multiply, g as PathProps, h as Path, i as LayoutEngine, it as glow, j as Node, k as EvalContext, l as setLayoutEngine, lt as fromTRS, m as LineBox, n as LayoutChildSpec, nt as createDisplayListBuilder, ot as IDENTITY, p as ImageProps, q as FilterValidationError, r as LayoutContainerSpec, rt as filtersToCanvasFilter, s as getLayoutEngine, st as Mat2x3, t as LayoutBox, tt as StrokeStyle, u as Circle, ut as invert, v as RevealMark, w as WordBox, x as TextProps, y as ShapeProps, z as quantize } from "./layoutEngine.js";
 import { BindableSignal, BoundTimeline, CompiledTimeline, Playhead, Timeline, Vec2 } from "@glissade/core";
 
 //#region src/highlight.d.ts
@@ -28,6 +28,34 @@ 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/tokenHighlight.d.ts
 interface TokenRange {
   /** token text (whitespace-insensitive run match) or inclusive [from, to] wordBoxes indices */
@@ -270,4 +298,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 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 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, 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, revealSchedule, roundedRectSegs, segmentWords, setDefaultMeasurer, setLayoutEngine, textCursor, tokenHighlight, validateFilters };

package/dist/index.js

@@ -1,4 +1,4 @@
-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 { A as invert, C as createDisplayListBuilder, D as IDENTITY, E as validateFilters, M as multiply, O as applyToPoint, S as FilterValidationError, T as glow, _ as estimatingMeasurer, a as Circle, b as segmentWords, c as Path, d as Video, f as revealSchedule, g as breakLines, h as resolveAnchor, i as setLayoutEngine, j as matEquals, k as fromTRS, 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 filtersToCanvasFilter, x as setDefaultMeasurer, y as quantize } from "./layoutEngine.js";
 import { bindTimeline, compileTimeline, createPlayhead, emitDevWarning, evaluateAt, signal, vec2Signal } from "@glissade/core";
 //#region src/highlight.ts
 /**
@@ -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,6 +73,80 @@ 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);
@@ -752,4 +826,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, Group, Highlight, IDENTITY, ImageNode, LayoutEngineMissingError, Node, Path, Raster2D, Rect, ShaderEffect, Text, TextCursor, TokenHighlight, TokenMatchError, Video, applyToPoint, bindScene, breakLines, createDisplayListBuilder, createScene, estimatingMeasurer, evaluate, filtersToCanvasFilter, fontString, fromTRS, getLayoutEngine, glow, highlight, invert, matEquals, matchTokenRun, multiply, quantize, requireLayoutEngine, resolveAnchor, revealSchedule, roundedRectSegs, segmentWords, setDefaultMeasurer, setLayoutEngine, textCursor, tokenHighlight, 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, M as NodeProps, N as PropInit, W as DisplayListBuilder, 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.
+ */
+
 /**
  * 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 { ResourceId as $, HitArea as A, segmentWords as B, VideoProps as C, AnchorSpec as D, roundedRectSegs as E, TextMeasurer as F, DrawCommand as G, BlendMode as H, TextMetricsLite as I, FontSpec as J, FilterSpec as K, breakLines as L, NodeProps as M, PropInit as N, BindablePropTarget as O, resolveAnchor as P, Resource as Q, estimatingMeasurer as R, Video as S, revealSchedule as T, DisplayList as U, setDefaultMeasurer as V, DisplayListBuilder as W, PathSeg as X, Paint as Y, Rect$1 as Z, Rect as _, LayoutEngineMissingError as a, validateFilters as at, Text as b, requireLayoutEngine as c, applyToPoint as ct, Group as d, matEquals as dt, ShaderRef as et, ImageNode as f, multiply as ft, PathProps as g, Path as h, LayoutEngine as i, glow as it, Node as j, EvalContext as k, setLayoutEngine as l, fromTRS as lt, LineBox as m, LayoutChildSpec as n, createDisplayListBuilder as nt, LayoutResult as o, IDENTITY as ot, ImageProps as p, FilterValidationError as q, LayoutContainerSpec as r, filtersToCanvasFilter as rt, getLayoutEngine as s, Mat2x3 as st, LayoutBox as t, StrokeStyle as tt, Circle as u, invert 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 { invert as A, createDisplayListBuilder as C, IDENTITY as D, validateFilters as E, multiply as M, applyToPoint as O, FilterValidationError as S, glow as T, estimatingMeasurer as _, Circle as a, segmentWords as b, Path as c, Video as d, revealSchedule as f, breakLines as g, resolveAnchor as h, setLayoutEngine as i, matEquals as j, fromTRS 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, filtersToCanvasFilter as w, setDefaultMeasurer 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.2",
   "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.2"
   },
   "repository": {
     "type": "git",