@glissade/scene 0.19.0-pre.0 → 0.19.0-pre.1

package/dist/nodes.js

@@ -1693,6 +1693,12 @@ var Text = class extends Node {
 	width;
 	lineHeight;
 	reveal;
+	/**
+	* Reveal fraction in [0, 1]; NaN (the default) means "unset" so plain `reveal`
+	* is authoritative and the node stays byte-identical to one without it. When
+	* not-NaN it overrides `reveal` via {@link effectiveReveal}.
+	*/
+	revealFraction;
 	constructor(props = {}) {
 		super(props);
 		this.text = initProp(signal(""), props.text);
@@ -1705,11 +1711,27 @@ var Text = class extends Node {
 		this.width = initProp(signal(0), props.width);
 		this.lineHeight = props.lineHeight ?? 1.25;
 		this.reveal = initProp(signal(Number.POSITIVE_INFINITY), props.reveal);
+		this.revealFraction = initProp(signal(NaN), props.revealFraction);
 		this.registerTarget("width", this.width, "number");
 		this.registerTarget("text", this.text, "string");
 		this.registerTarget("fill", this.fill, "color");
 		this.registerTarget("fontSize", this.fontSize, "number");
 		this.registerTarget("reveal", this.reveal, "number");
+		this.registerTarget("revealFraction", this.revealFraction, "number");
+	}
+	/**
+	* The grapheme COUNT to reveal this frame — the single source the draw mask,
+	* {@link revealHead}, and the masked emit path all read. When `revealFraction`
+	* is set (not NaN) it wins: `round(clamp(fraction, 0, 1) * graphemeCount)`,
+	* resolved against the SAME laid-out grapheme stream `reveal` counts. Unset
+	* (NaN) it falls straight through to `reveal()`, so a node without
+	* `revealFraction` is byte-identical to before this prop existed.
+	*/
+	effectiveReveal(measurer) {
+		const frac = this.revealFraction();
+		if (Number.isNaN(frac)) return this.reveal();
+		const total = this.graphemes(measurer).length;
+		return Math.round((frac <= 0 ? 0 : frac >= 1 ? 1 : frac) * total);
 	}
 	intrinsicSize(measurer) {
 		const text = this.text();
@@ -1845,6 +1867,58 @@ var Text = class extends Node {
 		return boxes;
 	}
 	/**
+	* Per-grapheme ink boxes within each laid-out line — the per-grapheme analogue
+	* of {@link wordBoxes}, boxing the SAME grapheme units `reveal`/`graphemes()`
+	* count (`Intl.Segmenter` boundaries via `segmentGraphemes`, so emoji/ZWJ
+	* sequences stay whole). Positioned by cumulative prefix advances so
+	* cross-grapheme kerning is exact and the boxes' advances sum to the line
+	* width — the boundaries MATCH the draw path, so splitText goldens don't
+	* drift. Whitespace graphemes advance but produce no box (dropped), exactly
+	* as `wordBoxes()` trims whitespace advance. The substrate `splitText({ by:
+	* 'grapheme' })` snapshots.
+	*/
+	graphemeBoxes(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,
+			...this.fontStyle === "italic" ? { style: "italic" } : {}
+		};
+		const maxWidth = this.width();
+		const lines = breakLines(text, font, maxWidth > 0 ? maxWidth : void 0, m);
+		const step = quantize(font.size * this.lineHeight);
+		const boxes = [];
+		for (let i = 0; i < lines.length; i++) {
+			const line = lines[i];
+			if (!line) continue;
+			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;
+			let prefix = "";
+			for (const g of segmentGraphemes(line)) {
+				const start = prefix;
+				prefix += g;
+				if (g.trim() === "") continue;
+				const before = m.measureText(start, font).width;
+				const after = m.measureText(start + g, font).width;
+				boxes.push({
+					text: g,
+					line: i,
+					x: lineX + before,
+					y,
+					w: after - before,
+					h
+				});
+			}
+		}
+		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
@@ -1889,7 +1963,7 @@ var Text = class extends Node {
 		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 revealRaw = this.effectiveReveal(m);
 		const shown = Math.max(0, Math.min(Number.isFinite(revealRaw) ? Math.floor(revealRaw) : total, total));
 		let remaining = shown;
 		let last = {
@@ -1937,7 +2011,7 @@ 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 revealRaw = this.effectiveReveal(ctx.measurer);
 		const masked = Number.isFinite(revealRaw);
 		let remaining = masked ? Math.max(0, Math.floor(revealRaw)) : 0;
 		for (let i = 0; i < lines.length; i++) {

package/dist/type.d.ts

@@ -0,0 +1,63 @@
+import { W as TextMeasurer, _ as WordBox, i as Group, m as TextProps, p as Text, r as GraphemeBox, s as LineBox } from "./nodes.js";
+
+//#region src/type.d.ts
+
+type SplitBy = 'word' | 'line' | 'grapheme';
+interface SplitTextOpts {
+  /** What unit to split into. Default 'word'. */
+  by?: SplitBy;
+  /**
+   * Stable id prefix for the wrapping group and its parts (`${id}/${i}`). When
+   * omitted, falls back to the source Text's own `id` (and throws if neither is
+   * set — a split needs a stable id namespace to bind tracks against).
+   */
+  id?: string;
+  /**
+   * The measurer to snapshot part geometry with. Defaults to the source's
+   * injected measurer, then the process fallback — exactly the chain the other
+   * Text geometry getters use.
+   */
+  measurer?: TextMeasurer;
+}
+/** One part of a split, in the source Text's draw space (group-local coords). */
+interface SplitPart {
+  /** The part's text (a word, a full line, or a single grapheme). */
+  text: string;
+  /** The generated child node (a left-aligned Text positioned at the part). */
+  node: Text;
+  /** Laid-out line index the part came from. */
+  line: number;
+  /** Part ink box, in the source's draw space (== the child's group-local box). */
+  box: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+  };
+}
+interface SplitTextResult {
+  /** The wrapping group (`id`), positioned where the source sat — draw THIS. */
+  node: Group;
+  /** The generated part children, in reading order. */
+  children: Text[];
+  /** Per-part geometry + node, in reading order. */
+  parts: SplitPart[];
+}
+declare class SplitTextError extends Error {
+  constructor(message: string);
+}
+/**
+ * Expand a Text (instance or props) into a `Group` of positioned per-part child
+ * Texts — one per word / line / grapheme. PURE build-time expansion to ordinary
+ * nodes; the part geometry is a STATIC snapshot of the source's current layout.
+ *
+ *   const split = splitText(title, { by: 'word', id: 'title' });
+ *   // scene children: [split.node]  (REPLACES the original title)
+ *   // animate each word: split.children[i] / track('title/0/opacity', …)
+ *
+ * Stagger a word-by-word reveal by fanning a clip across `split.children`, or
+ * compose with `tl.stagger` over the `${id}/${i}` ids.
+ */
+declare function splitText(source: Text | TextProps, opts?: SplitTextOpts): SplitTextResult;
+//#endregion
+export { type GraphemeBox, type LineBox, SplitBy, SplitPart, SplitTextError, SplitTextOpts, SplitTextResult, type WordBox, splitText };

package/dist/type.js

@@ -0,0 +1,120 @@
+import { r as Group, s as Text, v as fallbackMeasurer, y as quantize } from "./nodes.js";
+//#region src/type.ts
+/**
+* `@glissade/scene/type` — `splitText()`: build-time split-text sub-targets
+* (0.19 kinetic-typography tier). A PURE PRE-EVALUATE EXPANSION: it expands a
+* Text into a `Group` of independently addressable child Texts — one per word,
+* line, or grapheme, id `${id}/${i}` — so each part animates on its own (stagger
+* a word-by-word reveal, scatter graphemes, …). Like `each()`, nothing executes
+* at play time: it snapshots the source's laid-out part geometry ONCE and emits
+* ordinary positioned nodes, so `evaluate()` stays a pure function of time and
+* the goldens hold by construction.
+*
+* SEPARATE entry point with its own budget (mirrors `each()`/`scene/layout`/
+* `scene/path`) — the base embed never pays for it.
+*
+* Authoring semantics (the blessed defaults):
+* - STATIC SNAPSHOT: part boxes are captured at build time from the source's
+*   measurer. Animating the source's width/fontSize after the split will NOT
+*   reflow the parts — the documented `each()` tradeoff. Re-`splitText()` on a
+*   changed source if you need a different layout.
+* - REPLACE the source: this returns the Group of parts to draw INSTEAD of the
+*   original Text. Don't also add the source to the scene, or it double-draws.
+*/
+var SplitTextError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "SplitTextError";
+	}
+};
+/**
+* Expand a Text (instance or props) into a `Group` of positioned per-part child
+* Texts — one per word / line / grapheme. PURE build-time expansion to ordinary
+* nodes; the part geometry is a STATIC snapshot of the source's current layout.
+*
+*   const split = splitText(title, { by: 'word', id: 'title' });
+*   // scene children: [split.node]  (REPLACES the original title)
+*   // animate each word: split.children[i] / track('title/0/opacity', …)
+*
+* Stagger a word-by-word reveal by fanning a clip across `split.children`, or
+* compose with `tl.stagger` over the `${id}/${i}` ids.
+*/
+function splitText(source, opts = {}) {
+	const text = source instanceof Text ? source : new Text(source);
+	const id = opts.id ?? text.id;
+	if (id === void 0) throw new SplitTextError("splitText() needs a stable id — pass { id } or give the source Text an id (the parts bind tracks against ${id}/${i})");
+	const by = opts.by ?? "word";
+	const m = opts.measurer ?? text.measurerSource?.() ?? fallbackMeasurer();
+	const font = {
+		fontFamily: text.fontFamily,
+		fontSize: text.fontSize(),
+		fontWeight: text.fontWeight,
+		fontStyle: text.fontStyle,
+		fill: text.fill(),
+		lineHeight: text.lineHeight
+	};
+	const step = quantize(font.fontSize * font.lineHeight);
+	const boxes = by === "line" ? text.lineBoxes(m).map((b, i) => ({
+		text: b.text,
+		line: i,
+		x: b.x,
+		y: b.y,
+		w: b.w,
+		h: b.h
+	})) : by === "word" ? text.wordBoxes(m).map((b) => ({
+		text: b.text,
+		line: b.line,
+		x: b.x,
+		y: b.y,
+		w: b.w,
+		h: b.h
+	})) : text.graphemeBoxes(m).map((b) => ({
+		text: b.text,
+		line: b.line,
+		x: b.x,
+		y: b.y,
+		w: b.w,
+		h: b.h
+	}));
+	const children = [];
+	const parts = [];
+	for (let i = 0; i < boxes.length; i++) {
+		const b = boxes[i];
+		const node = new Text({
+			id: `${id}/${i}`,
+			text: b.text,
+			fill: font.fill,
+			fontFamily: font.fontFamily,
+			fontSize: font.fontSize,
+			fontWeight: font.fontWeight,
+			...font.fontStyle === "italic" ? { fontStyle: "italic" } : {},
+			lineHeight: font.lineHeight,
+			align: "left",
+			position: [b.x, b.line * step]
+		});
+		children.push(node);
+		parts.push({
+			text: b.text,
+			node,
+			line: b.line,
+			box: {
+				x: b.x,
+				y: b.y,
+				w: b.w,
+				h: b.h
+			}
+		});
+	}
+	const [px, py] = text.position();
+	return {
+		node: new Group({
+			id,
+			children,
+			position: [px, py]
+		}),
+		children,
+		parts
+	};
+}
+//#endregion
+export { SplitTextError, splitText };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/scene",
-  "version": "0.19.0-pre.0",
+  "version": "0.19.0-pre.1",
   "description": "glissade scene graph: nodes, transforms, DisplayList emission. Renderer-agnostic; zero DOM/Node dependencies.",
   "license": "Apache-2.0",
   "engines": {
@@ -24,6 +24,10 @@
     "./describe": {
       "types": "./dist/describe.d.ts",
       "default": "./dist/describe.js"
+    },
+    "./type": {
+      "types": "./dist/type.d.ts",
+      "default": "./dist/type.js"
     }
   },
   "files": [
@@ -31,7 +35,7 @@
   ],
   "dependencies": {
     "yoga-layout": "^3.2.1",
-    "@glissade/core": "0.19.0-pre.0"
+    "@glissade/core": "0.19.0-pre.1"
   },
   "repository": {
     "type": "git",