@glissade/scene 0.4.3 → 0.4.4

package/dist/index.d.ts

@@ -28,6 +28,56 @@ 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/tokenHighlight.d.ts
+interface TokenRange {
+  /** token text (whitespace-insensitive run match) or inclusive [from, to] wordBoxes indices */
+  match: string | readonly [number, number];
+  /** which occurrence of a string match; default 1 (the first) */
+  occurrence?: number;
+  /** range id for track targets ('<nodeId>/<rangeId>/fill' …); default 'r<index>' */
+  id?: string;
+  fill?: PropInit<string>;
+  opacity?: PropInit<number>;
+  /** 0→1 left-to-right reveal across the range; default 1 */
+  progress?: PropInit<number>;
+  /** scale about the range rect's center; default 1 */
+  scale?: PropInit<number>;
+}
+interface TokenHighlightProps extends NodeProps {
+  /** the Text whose tokens get highlighted; place this node as an EARLIER sibling */
+  text: Text;
+  ranges: TokenRange[];
+  /** marker overhang beyond the ink box, [x, y] px; default [4, 2] */
+  padding?: [number, number];
+  cornerRadius?: number;
+  /** re-resolve string matches every frame (animated text); default false — drift throws */
+  rematch?: boolean;
+}
+declare class TokenMatchError extends Error {
+  constructor(message: string);
+}
+/**
+ * Find the Nth whitespace-stripped consecutive run of boxes equal to token.
+ * Boundary-exact: a run that diverges mid-segment is not a match; ending
+ * mid-segment throws (with the real segment list) rather than half-boxing.
+ */
+declare function matchTokenRun(boxes: WordBox[], token: string, occurrence?: number): [number, number];
+declare class TokenHighlight extends Node {
+  readonly target: Text;
+  readonly padding: [number, number];
+  readonly cornerRadius: number;
+  readonly rematch: boolean;
+  private readonly ranges;
+  constructor(props: TokenHighlightProps);
+  private resolveRun;
+  protected draw(out: DisplayListBuilder, ctx: EvalContext): void;
+}
+/**
+ * `children: [tokenHighlight(para, { ranges: [{ match: '$48,200', fill: cat.money }] }), para]`
+ * — each range animates independently via '<id>/<rangeId>/fill|opacity|progress|scale'.
+ */
+declare function tokenHighlight(text: Text, props: Omit<TokenHighlightProps, 'text'>): TokenHighlight;
+//#endregion
 //#region src/assets.d.ts
 /**
  * Asset contracts (DESIGN.md §3.8): evaluate() never awaits — callers warm
@@ -218,4 +268,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, Video, type VideoFrameSource, type VideoProps, type WordBox, applyToPoint, bindScene, breakLines, createDisplayListBuilder, createScene, estimatingMeasurer, evaluate, filtersToCanvasFilter, fontString, fromTRS, getLayoutEngine, glow, highlight, invert, matEquals, multiply, quantize, requireLayoutEngine, resolveAnchor, roundedRectSegs, segmentWords, setDefaultMeasurer, setLayoutEngine, 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 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 };

package/dist/index.js

@@ -19,8 +19,8 @@ var Highlight = class extends Node {
 	constructor(props) {
 		super(props);
 		this.target = props.text;
-		this.color = init(signal("#ffe066"), props.color);
-		this.progress = init(signal(1), props.progress);
+		this.color = init$1(signal("#ffe066"), props.color);
+		this.progress = init$1(signal(1), props.progress);
 		this.padding = props.padding ?? [4, 2];
 		this.cornerRadius = props.cornerRadius ?? 4;
 		this.registerTarget("progress", this.progress);
@@ -73,6 +73,185 @@ 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/tokenHighlight.ts
+/**
+* Multi-range token highlight: sub-line ranges over a Text node's wordBoxes,
+* each with its OWN animatable fill/opacity/progress/scale — four-color
+* category passes, per-token flips, karaoke-with-color. Design answers from
+* downstream production (the NNDL verification ritual):
+*  - ranges VALIDATE at construction and THROW on copy drift at draw — the
+*    throw is load-bearing (it catches edited copy that no longer matches);
+*    `rematch: true` opts animated text into per-frame re-resolution.
+*  - a range spanning a wrap produces one rect per line segment.
+*  - string matches are whitespace-stripped consecutive box runs and must end
+*    boundary-exact (mid-segment end = error listing the actual segments);
+*    `[wordIndex, wordIndex]` ranges sidestep matching entirely.
+*/
+var TokenMatchError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "TokenMatchError";
+	}
+};
+const stripWs = (s) => s.replace(/\s+/g, "");
+/**
+* Find the Nth whitespace-stripped consecutive run of boxes equal to token.
+* Boundary-exact: a run that diverges mid-segment is not a match; ending
+* mid-segment throws (with the real segment list) rather than half-boxing.
+*/
+function matchTokenRun(boxes, token, occurrence = 1) {
+	const want = stripWs(token);
+	if (want.length === 0) throw new TokenMatchError("empty token");
+	let seen = 0;
+	for (let i = 0; i < boxes.length; i++) {
+		let acc = "";
+		for (let j = i; j < boxes.length; j++) {
+			acc += stripWs(boxes[j].text);
+			if (acc === want) {
+				seen++;
+				if (seen === occurrence) return [i, j];
+				break;
+			}
+			if (!want.startsWith(acc)) break;
+		}
+	}
+	throw new TokenMatchError(`no match for token '${token}'${occurrence > 1 ? ` (occurrence ${occurrence})` : ""} — segments are [${boxes.map((b) => `'${b.text}'`).join(", ")}]`);
+}
+var TokenHighlight = class extends Node {
+	target;
+	padding;
+	cornerRadius;
+	rematch;
+	ranges;
+	constructor(props) {
+		super(props);
+		this.target = props.text;
+		this.padding = props.padding ?? [4, 2];
+		this.cornerRadius = props.cornerRadius ?? 4;
+		this.rematch = props.rematch ?? false;
+		const boxes = this.target.wordBoxes();
+		this.ranges = props.ranges.map((spec, index) => {
+			const run = this.resolveRun(boxes, spec);
+			const id = spec.id ?? `r${index}`;
+			const r = {
+				spec,
+				fill: init(signal("#ffe066"), spec.fill),
+				opacity: init(signal(1), spec.opacity),
+				progress: init(signal(1), spec.progress),
+				scale: init(signal(1), spec.scale),
+				run,
+				bound: runText(boxes, run)
+			};
+			this.registerTarget(`${id}/fill`, r.fill);
+			this.registerTarget(`${id}/opacity`, r.opacity);
+			this.registerTarget(`${id}/progress`, r.progress);
+			this.registerTarget(`${id}/scale`, r.scale);
+			return r;
+		});
+	}
+	resolveRun(boxes, spec) {
+		if (typeof spec.match !== "string") {
+			const [from, to] = spec.match;
+			if (from < 0 || to >= boxes.length || from > to) throw new TokenMatchError(`word index range [${from}, ${to}] out of bounds (${boxes.length} boxes)`);
+			return [from, to];
+		}
+		return matchTokenRun(boxes, spec.match, spec.occurrence ?? 1);
+	}
+	draw(out, ctx) {
+		const boxes = this.target.wordBoxes(ctx.measurer);
+		if (boxes.length === 0) return;
+		const tm = this.target.localMatrix();
+		const [px, py] = this.padding;
+		let pushedTransform = false;
+		for (const r of this.ranges) {
+			const opacity = r.opacity();
+			if (opacity <= 0) continue;
+			const progress = Math.min(1, Math.max(0, r.progress()));
+			if (progress <= 0) continue;
+			let run = r.run;
+			if (this.rematch && typeof r.spec.match === "string") run = matchTokenRun(boxes, r.spec.match, r.spec.occurrence ?? 1);
+			else if (runText(boxes, run) !== r.bound) throw new TokenMatchError(`bound token '${r.bound}' no longer matches boxes [${run[0]}, ${run[1]}] — the text changed (segments now [${boxes.slice(run[0], run[1] + 1).map((b) => `'${b.text}'`).join(", ")}]); pass rematch: true for animated text`);
+			const lineRects = [];
+			for (let i = run[0]; i <= run[1]; i++) {
+				const b = boxes[i];
+				const last = lineRects[lineRects.length - 1];
+				const cur = i > run[0] && boxes[i - 1].line === b.line ? last : void 0;
+				if (cur) {
+					cur.w = b.x + b.w + px - cur.x;
+					cur.y = Math.min(cur.y, b.y - py);
+					cur.h = Math.max(cur.h, b.y + b.h + py - cur.y);
+				} else lineRects.push({
+					x: b.x - px,
+					y: b.y - py,
+					w: b.w + 2 * px,
+					h: b.h + 2 * py
+				});
+			}
+			if (!pushedTransform && !matEquals(tm, IDENTITY)) {
+				out.push({
+					op: "transform",
+					m: tm
+				});
+				pushedTransform = true;
+			}
+			const grouped = opacity < 1;
+			if (grouped) out.push({
+				op: "pushGroup",
+				opacity,
+				blend: "source-over",
+				filters: []
+			});
+			const fill = r.fill();
+			const scale = r.scale();
+			let remaining = progress * lineRects.reduce((sum, q) => sum + q.w, 0);
+			for (const q of lineRects) {
+				const fillW = Math.min(q.w, remaining);
+				remaining -= fillW;
+				if (fillW <= 0) break;
+				const cx = q.x + q.w / 2;
+				const cy = q.y + q.h / 2;
+				const w = fillW * scale;
+				const h = q.h * scale;
+				const x = cx - q.w / 2 * scale;
+				const y = cy - h / 2;
+				const rad = Math.min(this.cornerRadius, w / 2, h / 2);
+				const path = out.resource({
+					kind: "path",
+					segs: roundedRectSegs(x, y, w, h, rad)
+				});
+				out.push({
+					op: "fillPath",
+					path,
+					paint: {
+						kind: "color",
+						color: fill
+					}
+				});
+				if (remaining <= 0) break;
+			}
+			if (grouped) out.push({ op: "popGroup" });
+		}
+	}
+};
+function runText(boxes, run) {
+	return boxes.slice(run[0], run[1] + 1).map((b) => stripWs(b.text)).join("");
+}
+/**
+* `children: [tokenHighlight(para, { ranges: [{ match: '$48,200', fill: cat.money }] }), para]`
+* — each range animates independently via '<id>/<rangeId>/fill|opacity|progress|scale'.
+*/
+function tokenHighlight(text, props) {
+	return new TokenHighlight({
+		...props,
+		text
+	});
+}
 function init(sig, v) {
 	if (typeof v === "function") sig.bindSource(v);
 	else if (v !== void 0) sig.set(v);
@@ -563,4 +742,4 @@ function evaluate(scene, doc, t) {
 	});
 }
 //#endregion
-export { Circle, ColdAssetError, DuplicateNodeIdError, FilterValidationError, Group, Highlight, IDENTITY, ImageNode, LayoutEngineMissingError, Node, Path, Raster2D, Rect, ShaderEffect, Text, Video, applyToPoint, bindScene, breakLines, createDisplayListBuilder, createScene, estimatingMeasurer, evaluate, filtersToCanvasFilter, fontString, fromTRS, getLayoutEngine, glow, highlight, invert, matEquals, multiply, quantize, requireLayoutEngine, resolveAnchor, roundedRectSegs, segmentWords, setDefaultMeasurer, setLayoutEngine, validateFilters };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/scene",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "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.4.3"
+    "@glissade/core": "0.4.4"
   },
   "repository": {
     "type": "git",