@glissade/scene 0.55.0 → 0.56.0

package/dist/describe.js

@@ -23,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.55.0";
+const RAW_VERSION = "0.56.0";
 const PACKAGE_VERSION = RAW_VERSION.includes("GLISSADE_".concat("VERSION")) ? "0.0.0-dev" : RAW_VERSION;
 /**
 * Parse the documented positional-arg count from a helper `usage` string — the
@@ -654,6 +654,30 @@ const HELPERS = [
 		import: "@glissade/scene/type",
 		usage: "fitTextGroup(texts: Text[], opts: { maxW: number, minPx?, measurer? }): number"
 	},
+	{
+		name: "typeOn",
+		summary: "Kinetic type: one-call typewriter over the shipped typewriter(). DEFAULT emits a STRING hold-key track on `<id>/text` (round-trips to Lottie as stepped text docs). { cursor: true } adds a render-only caret sibling (export warns+drops it); { mask: true } swaps to a render-only `<id>/reveal` grapheme mask (export warns 'reveal not exported'). Factory (no `new`). Inject with tl.tracks([r.track]); draw r.node (+ r.cursor). On @glissade/scene/type.",
+		import: "@glissade/scene/type",
+		usage: "typeOn(source: Text | TextProps, opts?: { perChar?, start?, cursor?: boolean, mask?: boolean, cursorWidth?, blinkPeriod? }): { node: Text, cursor?: TextCursor, track: Track, marks, duration }"
+	},
+	{
+		name: "revealWords",
+		summary: "Kinetic type: splitText(by:'word') → cascade each word in (opacity, optionally rising from 'below'/dropping from 'above', or 'fade'). Returns the split Group as `node` (draw THIS, not the source) plus REAL tracks that round-trip to Lottie. Factory (no `new`). Pass { measurer } for exact geometry. On @glissade/scene/type.",
+		import: "@glissade/scene/type",
+		usage: "revealWords(source: Text | TextProps, opts?: { each?, from?: 'below'|'above'|'fade', distance?, duration?, ease?, at?, id?, measurer? }): { node: Group, tracks: Track[] }"
+	},
+	{
+		name: "revealLines",
+		summary: "Kinetic type: like revealWords but splitText(by:'line') — cascade each LINE in. Returns the split Group as `node` + REAL tracks (round-trip to Lottie). Factory (no `new`). On @glissade/scene/type.",
+		import: "@glissade/scene/type",
+		usage: "revealLines(source: Text | TextProps, opts?: { each?, from?: 'below'|'above'|'fade', distance?, duration?, ease?, at?, id?, measurer? }): { node: Group, tracks: Track[] }"
+	},
+	{
+		name: "emphasizeWords",
+		summary: "Kinetic type: pulse (scale up-and-back) the words at `indices` in reading order, cascaded. FAIL-LOUD: an out-of-range or non-integer index THROWS. Real scale tracks (round-trip to Lottie). Returns the split Group as `node`. Factory (no `new`). On @glissade/scene/type.",
+		import: "@glissade/scene/type",
+		usage: "emphasizeWords(source: Text | TextProps, indices: number[], opts?: { scale?, duration?, each?, ease?, at?, by?: 'word'|'grapheme', id?, measurer? }): { node: Group, tracks: Track[] }"
+	},
 	{
 		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.",

package/dist/examples.js

@@ -3,7 +3,7 @@ import { registerExamples } from "./describe.js";
 import { a as evaluate, i as createScene } from "./scene.js";
 import { Grid } from "./grid.js";
 import { Stack } from "./layoutCtors.js";
-import { splitText } from "./type.js";
+import { emphasizeWords, revealLines, revealWords, splitText, typeOn } from "./type.js";
 import { i as orientToPath, r as lookAt, s as motionPath } from "./orient.js";
 import { i as echo, n as motionBlur } from "./motionBlur.js";
 import { pathFromSvg } from "./path.js";
@@ -154,6 +154,48 @@ const EXAMPLES = [
 			fontSize: 40
 		}, { by: "grapheme" })
 	},
+	{
+		key: "typeOn",
+		code: "import { typeOn } from '@glissade/scene/type';\n// one-call typewriter. DEFAULT = a string hold-key track on `<id>/text` (round-trips to Lottie).\n// children: [t.node, t.cursor]; timeline: tl.tracks([t.track])\nconst t = typeOn({ id: 'prompt', text: 'make it pop', fontSize: 40 }, { cursor: true, perChar: 0.06 });",
+		run: () => void typeOn({
+			id: "prompt",
+			text: "make it pop",
+			fontSize: 40
+		}, {
+			cursor: true,
+			perChar: .06
+		})
+	},
+	{
+		key: "revealWords",
+		code: "import { revealWords } from '@glissade/scene/type';\n// split into words + cascade each in. Draw r.node (the split Group), inject r.tracks via tl.tracks(r).\nconst r = revealWords({ id: 'title', text: 'kinetic type', fontSize: 40 }, { from: 'below', each: 0.12 });",
+		run: () => void revealWords({
+			id: "title",
+			text: "kinetic type",
+			fontSize: 40
+		}, {
+			from: "below",
+			each: .12
+		})
+	},
+	{
+		key: "revealLines",
+		code: "import { revealLines } from '@glissade/scene/type';\n// like revealWords but per LINE. Draw r.node; tl.tracks(r).\nconst r = revealLines({ id: 'body', text: 'line one\\nline two', fontSize: 28 }, { each: 0.2 });",
+		run: () => void revealLines({
+			id: "body",
+			text: "line one\nline two",
+			fontSize: 28
+		}, { each: .2 })
+	},
+	{
+		key: "emphasizeWords",
+		code: "import { emphasizeWords } from '@glissade/scene/type';\n// pulse the words at the given indices (fails loud on an out-of-range index). Draw r.node; tl.tracks(r).\nconst r = emphasizeWords({ id: 'title', text: 'make it pop', fontSize: 40 }, [2], { scale: 1.3 });",
+		run: () => void emphasizeWords({
+			id: "title",
+			text: "make it pop",
+			fontSize: 40
+		}, [2], { scale: 1.3 })
+	},
 	{
 		key: "measureWrappedText",
 		code: "import { createScene } from '@glissade/scene';\n// size a bubble/card to wrapped text WITHOUT a Text node (the FontSpec field is `size`, not `fontSize`)\nconst scene = createScene({ size: { w: 400, h: 200 }, children: [] });\nconst { width, lines, height } = scene.measureWrappedText('a long string that wraps across the box', { family: 'sans-serif', size: 24 }, 280);",

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { C as Mat2x3, D as matEquals, E as invert, O as multiply, S as IDENTITY,
 import { $ as isEstimatingMeasurer, A as hachureLines, B as Node, C as HachureSpec, D as SketchValidationError, E as SketchStyle, F as validateSketch, G as MEASURE_QUANTUM_PX, H as NodeProps, I as AnchorSpec, J as WrappedTextMetrics, K as TextMeasurer, L as BindablePropTarget, M as roughen, N as sketchStrokes, O as arcLength, P as validateHachure, Q as estimatingMeasurer, R as EvalContext, S as roundedRectSegs, T as ResolvedSketch, U as PropInit, V as NodeConstructionError, W as resolveAnchor, X as assertFiniteFontSize, Y as __resetEstimateWarnings, Z as breakLines, _ as VideoProps, a as Group, b as pathFromSegs, c as LineBox, d as Rect, et as measureWrappedText, f as RevealMark, g as Video, h as TextProps, i as GraphemeBox, it as setDefaultMeasurer, j as resolveSketch, k as flatten, l as Path, m as Text, n as ClipRegion, nt as segmentGraphemes, o as ImageNode, p as ShapeProps, q as TextMetricsLite, r as Custom, rt as segmentWords, s as ImageProps, t as Circle, tt as quantize, u as PathProps, v as WordBox, w as Polyline, x as revealSchedule, y as coercePathData, z as HitArea } from "./nodes.js";
 import { t as collapseReplacer } from "./collapseReplacer.js";
 import { a as SceneModule, c as evaluate, i as SceneInit, n as ReservedNodeIdError, o as bindScene, r as Scene, s as createScene, t as DuplicateNodeIdError } from "./scene.js";
+import { a as typewriter, c as textCursor, i as TypewriterResult, n as StepMark, o as TextCursor, r as TypeEdit, s as TextCursorProps, t as EditMark } from "./typewriter.js";
 import { a as LayoutEngineMissingError, c as requireLayoutEngine, i as LayoutEngine, l as setLayoutEngine, n as LayoutChildSpec, r as LayoutContainerSpec, s as getLayoutEngine, t as LayoutBox } from "./layoutEngine.js";
 import { BindableSignal, CoverageReport, EaseSpec, FontMode, FontUsage, MeshPaint as MeshPaint$1, Rng, Timeline, Track } from "@glissade/core";
 import { ChannelOverride, Clip } from "@glissade/core/clips";
@@ -50,97 +51,6 @@ 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;
-}
-/** One edit step's phrase boundary — for driving sibling UI (a counter chip, a
- * progress dot) off the same source instead of recomputing wall-clock spans. */
-interface StepMark {
-  /** index of the step in the edit script */
-  index: number;
-  /** time this step began (before its first keystroke) */
-  start: number;
-  /** time this step completed (after its last keystroke and its hold) */
-  end: number;
-  /** the full visible string after this step */
-  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[];
-  /** one entry per edit step, with its start/end times — phrase boundaries */
-  steps: StepMark[];
-  /** 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;
-  gap?: number;
-}): TypewriterResult;
-//#endregion
 //#region src/each.d.ts
 /** An aspect-fraction placement: [fx, fy], each conventionally in [0, 1]. */
 type Place = readonly [number, number];

package/dist/index.js

@@ -1,6 +1,7 @@
 import { $ as multiply, A as __resetEstimateWarnings, B as setDefaultMeasurer, C as Node, F as isEstimatingMeasurer, G as glow, H as FilterValidationError, I as measureWrappedText, J as IDENTITY, K as validateFilters, L as quantize, M as breakLines, N as estimatingMeasurer, Q as matEquals, R as segmentGraphemes, S as validateSketch, T as resolveAnchor, U as createDisplayListBuilder, W as filtersToCanvasFilter, X as fromTRS, Y as applyToPoint, Z as invert, _ as hashStr, a as Path, b as sketchStrokes, c as Video, d as revealSchedule, f as roundedRectSegs, g as hachureLines, h as flatten, i as ImageNode, j as assertFiniteFontSize, k as MEASURE_QUANTUM_PX, l as coercePathData, m as arcLength, n as Custom, o as Rect, p as SketchValidationError, q as collapseReplacer, r as Group, s as Text, t as Circle, u as pathFromSegs, v as resolveSketch, w as NodeConstructionError, x as validateHachure, y as roughen, z as segmentWords } from "./nodes.js";
 import { a as evaluate, i as createScene, n as ReservedNodeIdError, r as bindScene, t as DuplicateNodeIdError } from "./scene.js";
 import { i as setLayoutEngine, n as getLayoutEngine, r as requireLayoutEngine, t as LayoutEngineMissingError } from "./layoutEngine.js";
+import { n as TextCursor, r as textCursor, t as typewriter } from "./typewriter.js";
 import { i as echo, n as motionBlur, r as Echo, t as MotionBlur } from "./motionBlur.js";
 import { buildFontRegistry, emitDevWarning, key, lerpColor, oklabToRgba, parseCmap, parseColor, random, rgbaToOklab, signal, stagger, track, validateFonts } from "@glissade/core";
 //#region src/taxonomy.ts
@@ -47,8 +48,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(signal("#ffe066"), props.color);
+		this.progress = init(signal(1), props.progress);
 		this.padding = props.padding ?? [4, 2];
 		this.cornerRadius = props.cornerRadius ?? 4;
 		this.registerTarget("progress", this.progress, "number");
@@ -101,165 +102,12 @@ function highlight(text, 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/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(signal(""), props.fill);
-		this.registerTarget("fill", this.fill, "color");
-	}
-	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(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;
-	const gap = opts.gap ?? 0;
-	let t = start;
-	const shown = [];
-	const keys = [key(start, "", { interp: "hold" })];
-	const marks = [];
-	const steps = [];
-	for (let ei = 0; ei < edits.length; ei++) {
-		const edit = edits[ei];
-		const stepStart = t;
-		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;
-		steps.push({
-			index: ei,
-			start: stepStart,
-			end: t,
-			value: shown.join("")
-		});
-		if (gap > 0 && ei < edits.length - 1) t += gap;
-	}
-	return {
-		track: track(target, "string", keys),
-		marks,
-		steps,
-		duration: t
-	};
-}
-//#endregion
 //#region src/each.ts
 /**
 * `each()` — deterministic parametric instancing (0.13 clip-tier sugar). Pure

package/dist/type.d.ts

@@ -1,4 +1,6 @@
 import { K as TextMeasurer, a as Group, c as LineBox, h as TextProps, i as GraphemeBox, m as Text, v as WordBox } from "./nodes.js";
+import { o as TextCursor, t as EditMark } from "./typewriter.js";
+import { EaseSpec, Track } from "@glissade/core";
 
 //#region src/type.d.ts
 
@@ -109,5 +111,117 @@ declare function fitText(text: Text, opts: FitTextOpts): Text;
  * `maxW` applies to all. Returns the shared size.
  */
 declare function fitTextGroup(texts: readonly Text[], opts: FitTextOpts): number;
+/** Thrown by the kinetic-type presets on a fail-loud condition (missing id, an
+ *  out-of-range emphasize index). Same fail-loud class as {@link SplitTextError}. */
+declare class KineticTypeError extends Error {
+  constructor(message: string);
+}
+interface TypeOnOpts {
+  /** Seconds per grapheme (keystroke cadence). Default 0.06 (typewriter's default). */
+  perChar?: number;
+  /** Absolute timeline start of the first keystroke (seconds). Default 0. */
+  start?: number;
+  /**
+   * OPT-IN: attach a {@link TextCursor} sibling that rides the reveal/type head.
+   * RENDER-ONLY (custom draw) — NOT bundled by default so the default typeOn stays
+   * Lottie-faithful; the exporter warns+drops the caret node. Add BOTH `.node` and
+   * `.cursor` to the scene (`children: [r.node, r.cursor]`).
+   */
+  cursor?: boolean;
+  /**
+   * OPT-IN: reveal via the grapheme MASK (`Text.reveal`) instead of the string
+   * track. RENDER-ONLY — Skia-identical but the exporter drops+warns "reveal is
+   * not exported" (the 0.55 trap, carried honestly). The default (mask off) uses
+   * the string hold-key track, which ROUND-TRIPS as stepped Lottie text documents.
+   */
+  mask?: boolean;
+  /** Caret width px when `cursor: true` (passthrough to textCursor). */
+  cursorWidth?: number;
+  /** Caret blink period seconds when `cursor: true` (passthrough to textCursor). */
+  blinkPeriod?: number;
+}
+interface TypeOnResult {
+  /** The Text to draw. In the DEFAULT (string-track) mode its `text` is driven by
+   *  `track`; in `mask` mode it keeps its full text and `reveal` masks it. */
+  node: Text;
+  /** Present only with `{ cursor: true }` — the caret sibling (render-only). */
+  cursor?: TextCursor;
+  /** The single track to inject (`tl.tracks([r.track])`): a STRING hold-key track
+   *  on `<id>/text` (default) or a NUMBER `<id>/reveal` grapheme-mask track (mask). */
+  track: Track;
+  /** Every keystroke (insert), for keystroke SFX — see keystrokeClips. */
+  marks: EditMark[];
+  /** Time of the last keystroke — the performance's end (seconds). */
+  duration: number;
+}
+/**
+ * One-call typewriter. Wraps the shipped `typewriter()` so a whole Text types in
+ * with a single call, optionally with a caret and/or a grapheme mask.
+ *
+ *   const t = typeOn({ id: 'prompt', text: 'make it pop', fontSize: 40 }, { cursor: true });
+ *   // scene children: [t.node, t.cursor]   timeline: tl.tracks([t.track])
+ *
+ * DEFAULT (no mask) = the STRING hold-key track on `<id>/text` (delegated to
+ * `typewriter()`); it ROUND-TRIPS to Lottie as stepped text documents. `mask:true`
+ * swaps to a `<id>/reveal` grapheme mask (render-only, export warns). `cursor:true`
+ * adds a render-only caret sibling (export warns).
+ */
+declare function typeOn(source: Text | TextProps, opts?: TypeOnOpts): TypeOnResult;
+/** Direction a part enters from in `revealWords`/`revealLines`. */
+type RevealFrom = 'below' | 'above' | 'fade';
+interface RevealOpts {
+  /** Per-part cascade delay (seconds). Default 0.08. */
+  each?: number;
+  /** Entrance style: rise from `'below'`, drop from `'above'`, or `'fade'` only. Default 'fade'. */
+  from?: RevealFrom;
+  /** Position offset px for 'below'/'above'. Default 24. */
+  distance?: number;
+  /** Per-part tween duration (seconds). Default 0.4. */
+  duration?: number;
+  /** Arriving ease. Default 'easeOutCubic'. */
+  ease?: EaseSpec;
+  /** Absolute start of the cascade (seconds). Default 0. */
+  at?: number;
+  /** Stable id namespace (else the source Text's id; throws if neither). */
+  id?: string;
+  /** Measurer for exact part geometry (like splitText). */
+  measurer?: TextMeasurer;
+}
+interface RevealResult {
+  /** The splitText Group — draw THIS (never the source: the .node-not-.source
+   *  footgun is hidden here). */
+  node: Group;
+  /** Real opacity (+ position) tracks — inject with `tl.tracks(result)`. ✅ round-trips. */
+  tracks: Track[];
+}
+/** Split a Text into WORDS and cascade each in (opacity, optionally rising/dropping
+ *  into place). Additive first-class — REAL tracks, so it round-trips to Lottie. */
+declare function revealWords(source: Text | TextProps, opts?: RevealOpts): RevealResult;
+/** Split a Text into LINES and cascade each in. Real tracks; round-trips to Lottie. */
+declare function revealLines(source: Text | TextProps, opts?: RevealOpts): RevealResult;
+interface EmphasizeOpts {
+  /** Peak scale of the pulse. Default 1.15. */
+  scale?: number;
+  /** Per-word pulse duration (seconds). Default 0.4. */
+  duration?: number;
+  /** Delay between successive emphasized words (seconds). Default 0.12. */
+  each?: number;
+  /** Ease of the up/down halves. Default 'easeInOutSine'. */
+  ease?: EaseSpec;
+  /** Absolute start (seconds). Default 0. */
+  at?: number;
+  /** Split unit to index against. Default 'word'. */
+  by?: 'word' | 'grapheme';
+  /** Stable id namespace (else the source Text's id). */
+  id?: string;
+  /** Measurer for exact part geometry. */
+  measurer?: TextMeasurer;
+}
+/**
+ * Pulse (scale up-and-back) the words at `indices` in reading order, cascaded.
+ * FAIL-LOUD: an out-of-range or non-integer index THROWS (never silently ignored).
+ * Real scale tracks → round-trips to Lottie.
+ */
+declare function emphasizeWords(source: Text | TextProps, indices: readonly number[], opts?: EmphasizeOpts): RevealResult;
 //#endregion
-export { FitTextOpts, type GraphemeBox, type LineBox, SplitBy, SplitPart, SplitTextError, SplitTextOpts, SplitTextResult, type WordBox, fitText, fitTextGroup, fitTextSize, splitText };
+export { EmphasizeOpts, FitTextOpts, type GraphemeBox, KineticTypeError, type LineBox, RevealFrom, RevealOpts, RevealResult, SplitBy, SplitPart, SplitTextError, SplitTextOpts, SplitTextResult, TypeOnOpts, TypeOnResult, type WordBox, emphasizeWords, fitText, fitTextGroup, fitTextSize, revealLines, revealWords, splitText, typeOn };

package/dist/type.js

@@ -1,4 +1,6 @@
-import { I as measureWrappedText, L as quantize, P as fallbackMeasurer, V as warnIfEstimating, r as Group, s as Text } from "./nodes.js";
+import { I as measureWrappedText, L as quantize, P as fallbackMeasurer, R as segmentGraphemes, V as warnIfEstimating, r as Group, s as Text } from "./nodes.js";
+import { r as textCursor, t as typewriter } from "./typewriter.js";
+import { key, timeline, track } from "@glissade/core";
 //#region src/type.ts
 /**
 * `@glissade/scene/type` — `splitText()`: build-time split-text sub-targets
@@ -208,5 +210,149 @@ function fitTextGroup(texts, opts) {
 	}
 	return shared;
 }
+/** Thrown by the kinetic-type presets on a fail-loud condition (missing id, an
+*  out-of-range emphasize index). Same fail-loud class as {@link SplitTextError}. */
+var KineticTypeError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "KineticTypeError";
+	}
+};
+/**
+* One-call typewriter. Wraps the shipped `typewriter()` so a whole Text types in
+* with a single call, optionally with a caret and/or a grapheme mask.
+*
+*   const t = typeOn({ id: 'prompt', text: 'make it pop', fontSize: 40 }, { cursor: true });
+*   // scene children: [t.node, t.cursor]   timeline: tl.tracks([t.track])
+*
+* DEFAULT (no mask) = the STRING hold-key track on `<id>/text` (delegated to
+* `typewriter()`); it ROUND-TRIPS to Lottie as stepped text documents. `mask:true`
+* swaps to a `<id>/reveal` grapheme mask (render-only, export warns). `cursor:true`
+* adds a render-only caret sibling (export warns).
+*/
+function typeOn(source, opts = {}) {
+	const node = source instanceof Text ? source : new Text(source);
+	const id = node.id;
+	if (id === void 0) throw new KineticTypeError("typeOn() needs a stable id on the source Text — pass { id } (the track binds against `<id>/text` or `<id>/reveal`)");
+	const full = node.text();
+	const start = opts.start ?? 0;
+	const tw = typewriter(`${id}/text`, [{ type: full }], {
+		start,
+		...opts.perChar !== void 0 ? { perChar: opts.perChar } : {}
+	});
+	let tr;
+	if (opts.mask) {
+		const count = segmentGraphemes(full).length;
+		tr = track(`${id}/reveal`, "number", [key(start, 0), key(tw.duration, count, "linear")]);
+	} else tr = tw.track;
+	const result = {
+		node,
+		track: tr,
+		marks: tw.marks,
+		duration: tw.duration
+	};
+	if (opts.cursor) result.cursor = textCursor(node, {
+		id: `${id}/cursor`,
+		...opts.cursorWidth !== void 0 ? { width: opts.cursorWidth } : {},
+		...opts.blinkPeriod !== void 0 ? { blinkPeriod: opts.blinkPeriod } : {}
+	});
+	return result;
+}
+function revealBy(source, by, opts) {
+	const split = splitText(source, {
+		by,
+		...opts.id !== void 0 ? { id: opts.id } : {},
+		...opts.measurer !== void 0 ? { measurer: opts.measurer } : {}
+	});
+	const each = opts.each ?? .08;
+	const duration = opts.duration ?? .4;
+	const ease = opts.ease ?? "easeOutCubic";
+	const at = opts.at ?? 0;
+	const from = opts.from ?? "fade";
+	const dy = from === "below" ? opts.distance ?? 24 : from === "above" ? -(opts.distance ?? 24) : 0;
+	const parts = split.parts;
+	const doc = timeline((tl) => {
+		tl.stagger(split.targets("opacity"), {
+			from: 0,
+			to: 1,
+			duration,
+			ease
+		}, {
+			each,
+			at
+		});
+		if (dy !== 0) tl.stagger(split.targets("position"), {
+			from: (i) => {
+				const [x, y] = parts[i].node.position();
+				return [x, y + dy];
+			},
+			to: (i) => parts[i].node.position(),
+			duration,
+			ease
+		}, {
+			each,
+			at
+		});
+	});
+	return {
+		node: split.node,
+		tracks: doc.tracks
+	};
+}
+/** Split a Text into WORDS and cascade each in (opacity, optionally rising/dropping
+*  into place). Additive first-class — REAL tracks, so it round-trips to Lottie. */
+function revealWords(source, opts = {}) {
+	return revealBy(source, "word", opts);
+}
+/** Split a Text into LINES and cascade each in. Real tracks; round-trips to Lottie. */
+function revealLines(source, opts = {}) {
+	return revealBy(source, "line", opts);
+}
+/**
+* Pulse (scale up-and-back) the words at `indices` in reading order, cascaded.
+* FAIL-LOUD: an out-of-range or non-integer index THROWS (never silently ignored).
+* Real scale tracks → round-trips to Lottie.
+*/
+function emphasizeWords(source, indices, opts = {}) {
+	const by = opts.by ?? "word";
+	const split = splitText(source, {
+		by,
+		...opts.id !== void 0 ? { id: opts.id } : {},
+		...opts.measurer !== void 0 ? { measurer: opts.measurer } : {}
+	});
+	const n = split.parts.length;
+	for (const idx of indices) if (!Number.isInteger(idx) || idx < 0 || idx >= n) throw new KineticTypeError(`emphasizeWords: index ${idx} is out of range — the split has ${n} ${by}(s) (valid 0..${n - 1}). Pass only in-range integer indices.`);
+	const scale = opts.scale ?? 1.15;
+	const duration = opts.duration ?? .4;
+	const each = opts.each ?? .12;
+	const ease = opts.ease ?? "easeInOutSine";
+	const at = opts.at ?? 0;
+	const half = duration / 2;
+	const scaleTargets = indices.map((i) => `${split.parts[i].id}/scale`);
+	const doc = timeline((tl) => {
+		tl.stagger(scaleTargets, {
+			from: [1, 1],
+			to: [scale, scale],
+			duration: half,
+			ease
+		}, {
+			each,
+			at
+		});
+		tl.stagger(scaleTargets, {
+			from: [scale, scale],
+			to: [1, 1],
+			duration: half,
+			ease
+		}, {
+			each,
+			at: at + half
+		});
+	});
+	return {
+		node: split.node,
+		tracks: doc.tracks
+	};
+}
 //#endregion
-export { SplitTextError, fitText, fitTextGroup, fitTextSize, splitText };
+export { KineticTypeError, SplitTextError, emphasizeWords, fitText, fitTextGroup, fitTextSize, revealLines, revealWords, splitText, typeOn };

package/dist/typewriter.d.ts

@@ -0,0 +1,97 @@
+import { r as DisplayListBuilder } from "./displayList.js";
+import { B as Node, H as NodeProps, R as EvalContext, U as PropInit, m as Text } from "./nodes.js";
+import { BindableSignal, Track } from "@glissade/core";
+
+//#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;
+}
+/** One edit step's phrase boundary — for driving sibling UI (a counter chip, a
+ * progress dot) off the same source instead of recomputing wall-clock spans. */
+interface StepMark {
+  /** index of the step in the edit script */
+  index: number;
+  /** time this step began (before its first keystroke) */
+  start: number;
+  /** time this step completed (after its last keystroke and its hold) */
+  end: number;
+  /** the full visible string after this step */
+  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[];
+  /** one entry per edit step, with its start/end times — phrase boundaries */
+  steps: StepMark[];
+  /** 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;
+  gap?: number;
+}): TypewriterResult;
+//#endregion
+export { typewriter as a, textCursor as c, TypewriterResult as i, StepMark as n, TextCursor as o, TypeEdit as r, TextCursorProps as s, EditMark as t };

package/dist/typewriter.js

@@ -0,0 +1,156 @@
+import { C as Node, J as IDENTITY, Q as matEquals, R as segmentGraphemes, f as roundedRectSegs } from "./nodes.js";
+import { key, signal, track } from "@glissade/core";
+//#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(signal(""), props.fill);
+		this.registerTarget("fill", this.fill, "color");
+	}
+	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(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;
+	const gap = opts.gap ?? 0;
+	let t = start;
+	const shown = [];
+	const keys = [key(start, "", { interp: "hold" })];
+	const marks = [];
+	const steps = [];
+	for (let ei = 0; ei < edits.length; ei++) {
+		const edit = edits[ei];
+		const stepStart = t;
+		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;
+		steps.push({
+			index: ei,
+			start: stepStart,
+			end: t,
+			value: shown.join("")
+		});
+		if (gap > 0 && ei < edits.length - 1) t += gap;
+	}
+	return {
+		track: track(target, "string", keys),
+		marks,
+		steps,
+		duration: t
+	};
+}
+//#endregion
+export { TextCursor as n, textCursor as r, typewriter as t };

package/package.json

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