@glissade/scene 0.4.0 → 0.4.2

package/dist/index.d.ts

@@ -1,8 +1,34 @@
-import { $ as applyToPoint, A as breakLines, B as Paint, C as EvalContext, D as PropInit, E as NodeProps, F as DisplayListBuilder, G as ShaderRef, H as Rect$1, I as DrawCommand, J as filtersToCanvasFilter, K as StrokeStyle, L as FilterSpec, M as quantize, N as BlendMode, O as TextMeasurer, P as DisplayList, Q as Mat2x3, R as FilterValidationError, S as BindablePropTarget, T as Node, U as Resource, V as PathSeg, W as ResourceId, X as validateFilters, Y as glow, Z as IDENTITY, _ as ShapeProps, a as LayoutEngineMissingError, b as Video, c as requireLayoutEngine, d as Group, et as fromTRS, f as ImageNode, g as Rect, h as PathProps, i as LayoutEngine, j as estimatingMeasurer, k as TextMetricsLite, l as setLayoutEngine, m as Path, n as LayoutChildSpec, nt as matEquals, p as ImageProps, q as createDisplayListBuilder, r as LayoutContainerSpec, rt as multiply, s as getLayoutEngine, t as LayoutBox, tt as invert, u as Circle, v as Text, w as HitArea, x as VideoProps, y as TextProps, z as FontSpec } from "./layoutEngine.js";
+import { $ as createDisplayListBuilder, A as NodeProps, B as DisplayList, C as WordBox, D as EvalContext, E as BindablePropTarget, F as breakLines, G as FontSpec, H as DrawCommand, I as estimatingMeasurer, J as Rect$1, K as Paint, L as quantize, M as resolveAnchor, N as TextMeasurer, O as HitArea, P as TextMetricsLite, Q as StrokeStyle, R as segmentWords, S as VideoProps, T as AnchorSpec, U as FilterSpec, V as DisplayListBuilder, W as FilterValidationError, X as ResourceId, Y as Resource, Z as ShaderRef, _ as Rect, a as LayoutEngineMissingError, at as applyToPoint, b as TextProps, c as requireLayoutEngine, ct as matEquals, d as Group, et as filtersToCanvasFilter, f as ImageNode, g as PathProps, h as Path, i as LayoutEngine, it as Mat2x3, j as PropInit, k as Node, l as setLayoutEngine, lt as multiply, m as LineBox, n as LayoutChildSpec, nt as validateFilters, ot as fromTRS, p as ImageProps, q as PathSeg, r as LayoutContainerSpec, rt as IDENTITY, s as getLayoutEngine, st as invert, t as LayoutBox, tt as glow, u as Circle, v as ShapeProps, w as roundedRectSegs, x as Video, y as Text, z as BlendMode } from "./layoutEngine.js";
 import { BindableSignal, BoundTimeline, CompiledTimeline, Playhead, Timeline } from "@glissade/core";
 
-//#region src/assets.d.ts
+//#region src/highlight.d.ts
 
+interface HighlightProps extends NodeProps {
+  /** The Text whose lines get the marker. Place this node as an EARLIER
+   * sibling (same parent) so it paints behind the glyphs. */
+  text: Text;
+  color?: PropInit<string>;
+  /** 0→1 sweep across all lines in reading order, at constant speed weighted
+   * by line width; default 1 (fully highlighted). Track: '<id>/progress'. */
+  progress?: PropInit<number>;
+  /** Marker overhang beyond each line's ink box, [x, y] px; default [4, 2]. */
+  padding?: [number, number];
+  /** Rounded marker ends; default 4 (clamped to the box). */
+  cornerRadius?: number;
+}
+declare class Highlight extends Node {
+  readonly target: Text;
+  readonly color: BindableSignal<string>;
+  readonly progress: BindableSignal<number>;
+  readonly padding: [number, number];
+  readonly cornerRadius: number;
+  constructor(props: HighlightProps);
+  protected draw(out: DisplayListBuilder, ctx: EvalContext): void;
+}
+/** `children: [highlight(title, { color: '#ffe066' }), title]` — marker behind the text. */
+declare function highlight(text: Text, props?: Omit<HighlightProps, 'text'>): Highlight;
+//#endregion
+//#region src/assets.d.ts
 /**
  * Asset contracts (DESIGN.md §3.8): evaluate() never awaits — callers warm
  * sources first (§2.5 readiness precondition), then emission is pure. The
@@ -38,7 +64,6 @@ declare class ColdAssetError extends Error {
 }
 //#endregion
 //#region src/shaderEffect.d.ts
-
 interface ShaderEffectProps extends NodeProps {
   children?: Node[];
   /** WGSL fragment module: `struct Uniforms {...}` + `@fragment fn effect(@location(0) uv: vec2f) -> @location(0) vec4f`. */
@@ -193,4 +218,4 @@ declare function bindScene(scene: Scene, doc: Timeline): BindingCacheEntry;
  */
 declare function evaluate(scene: Scene, doc: Timeline, t: number): DisplayList;
 //#endregion
-export { 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, type HitArea, IDENTITY, type ImageHandle, ImageNode, type ImageProps, type LayoutBox, type LayoutChildSpec, type LayoutContainerSpec, type LayoutEngine, LayoutEngineMissingError, 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, applyToPoint, bindScene, breakLines, createDisplayListBuilder, createScene, estimatingMeasurer, evaluate, filtersToCanvasFilter, fontString, fromTRS, getLayoutEngine, glow, invert, matEquals, multiply, quantize, requireLayoutEngine, 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, 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, setLayoutEngine, validateFilters };

package/dist/index.js

@@ -1,5 +1,84 @@
-import { C as fromTRS, E as multiply, S as applyToPoint, T as matEquals, _ as createDisplayListBuilder, a as Circle, b as validateFilters, c as Path, d as Video, f as Node, g as FilterValidationError, h as quantize, i as setLayoutEngine, l as Rect, m as estimatingMeasurer, n as getLayoutEngine, o as Group, p as breakLines, r as requireLayoutEngine, s as ImageNode, t as LayoutEngineMissingError, u as Text, v as filtersToCanvasFilter, w as invert, x as IDENTITY, y as glow } from "./layoutEngine.js";
+import { C as validateFilters, D as invert, E as fromTRS, O as matEquals, S as glow, T as applyToPoint, _ as quantize, a as Circle, b as createDisplayListBuilder, c as Path, d as Video, f as roundedRectSegs, g as estimatingMeasurer, h as breakLines, i as setLayoutEngine, k as multiply, 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 segmentWords, w as IDENTITY, x as filtersToCanvasFilter, y as FilterValidationError } from "./layoutEngine.js";
 import { bindTimeline, compileTimeline, createPlayhead, emitDevWarning, evaluateAt, signal } from "@glissade/core";
+//#region src/highlight.ts
+/**
+* Marker-style text highlight: per-line rounded rects behind a Text node's
+* laid-out lines, swept by ONE 0→1 progress track in reading order. Lines
+* come from Text.lineBoxes() each frame, so the marker re-flows with wrap
+* width, font, and text animation — and the line count is dynamic because
+* the rects are draw() output, not child nodes. Pure data, both backends,
+* golden-coverable. For karaoke, key '<id>/progress' from narrate's
+* word timestamps.
+*/
+var Highlight = class extends Node {
+	target;
+	color;
+	progress;
+	padding;
+	cornerRadius;
+	constructor(props) {
+		super(props);
+		this.target = props.text;
+		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);
+		this.registerTarget("color", this.color);
+	}
+	draw(out, ctx) {
+		const progress = Math.min(1, Math.max(0, this.progress()));
+		if (progress <= 0) return;
+		const [px, py] = this.padding;
+		const boxes = this.target.lineBoxes(ctx.measurer).map((b) => ({
+			x: b.x - px,
+			y: b.y - py,
+			w: b.w + 2 * px,
+			h: b.h + 2 * py
+		}));
+		const total = boxes.reduce((sum, b) => sum + b.w, 0);
+		if (total <= 0) return;
+		const tm = this.target.localMatrix();
+		if (!matEquals(tm, IDENTITY)) out.push({
+			op: "transform",
+			m: tm
+		});
+		const color = this.color();
+		let remaining = progress * total;
+		for (const b of boxes) {
+			const fill = Math.min(b.w, remaining);
+			remaining -= fill;
+			if (fill <= 0) break;
+			const r = Math.min(this.cornerRadius, fill / 2, b.h / 2);
+			const path = out.resource({
+				kind: "path",
+				segs: roundedRectSegs(b.x, b.y, fill, b.h, r)
+			});
+			out.push({
+				op: "fillPath",
+				path,
+				paint: {
+					kind: "color",
+					color
+				}
+			});
+			if (remaining <= 0) break;
+		}
+	}
+};
+/** `children: [highlight(title, { color: '#ffe066' }), title]` — marker behind the text. */
+function highlight(text, props = {}) {
+	return new Highlight({
+		...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/assets.ts
 var ColdAssetError = class extends Error {
 	assetId;
@@ -484,4 +563,4 @@ function evaluate(scene, doc, t) {
 	});
 }
 //#endregion
-export { Circle, ColdAssetError, DuplicateNodeIdError, FilterValidationError, Group, IDENTITY, ImageNode, LayoutEngineMissingError, Node, Path, Raster2D, Rect, ShaderEffect, Text, Video, applyToPoint, bindScene, breakLines, createDisplayListBuilder, createScene, estimatingMeasurer, evaluate, filtersToCanvasFilter, fontString, fromTRS, getLayoutEngine, glow, invert, matEquals, multiply, quantize, requireLayoutEngine, setLayoutEngine, validateFilters };
+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, setLayoutEngine, validateFilters };

package/dist/layout.d.ts

@@ -1,4 +1,4 @@
-import { C as EvalContext, D as PropInit, E as NodeProps, F as DisplayListBuilder, O as TextMeasurer, T as Node, a as LayoutEngineMissingError, d as Group, i as LayoutEngine, l as setLayoutEngine, n as LayoutChildSpec, o as LayoutResult, r as LayoutContainerSpec, s as getLayoutEngine, t as LayoutBox } from "./layoutEngine.js";
+import { A as NodeProps, D as EvalContext, N as TextMeasurer, V as DisplayListBuilder, 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 { BindableSignal } from "@glissade/core";
 
 //#region src/layout.d.ts

package/dist/layout.js

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

package/dist/layoutEngine.d.ts

@@ -194,6 +194,12 @@ declare function quantize(v: number): number;
  * faithful; mount(), the CLI, and exporters always inject the real one.
  */
 declare const estimatingMeasurer: TextMeasurer;
+/**
+ * The draw-path word segmentation (Intl.Segmenter boundaries, punctuation
+ * glued to its predecessor) — exported so Text.wordBoxes() boxes EXACTLY the
+ * units the breaker flows.
+ */
+declare function segmentWords(text: string): string[];
 /**
  * Greedy line breaking: explicit '\n' always breaks; otherwise word segments
  * flow until maxWidth is exceeded (Intl.Segmenter boundaries, so CJK wraps
@@ -203,6 +209,15 @@ declare const estimatingMeasurer: TextMeasurer;
 declare function breakLines(text: string, font: FontSpec, maxWidth: number | undefined, measurer: TextMeasurer): string[];
 //#endregion
 //#region src/node.d.ts
+/**
+ * Where `position` pins to on the node's intrinsic box, as fractions of its
+ * size — and the rotation/scale pivot (the Lottie anchor model). Default
+ * 'center' preserves every pre-anchor scene byte-for-byte. With a non-center
+ * anchor, grow direction falls out: anchor 'left' + a width track sweeps
+ * rightward, anchor [0, 1] grows a bar upward.
+ */
+type AnchorSpec = 'center' | 'top-left' | 'top' | 'top-right' | 'left' | 'right' | 'bottom-left' | 'bottom' | 'bottom-right' | readonly [number, number];
+declare function resolveAnchor(spec: AnchorSpec): Vec2;
 interface EvalContext {
   /** The playhead value at evaluate() entry — the only time channel (§3.1). */
   readonly time: number;
@@ -223,6 +238,8 @@ interface NodeProps {
   zIndex?: PropInit<number>;
   /** Group filters (§3.4): the subtree composites as a unit through them. */
   filters?: PropInit<FilterSpec[]>;
+  /** Placement point + transform pivot on the intrinsic box; default 'center'. */
+  anchor?: AnchorSpec;
 }
 interface BindablePropTarget {
   bindSource(fn: () => unknown): void;
@@ -242,6 +259,7 @@ type HitArea = {
   r: number;
 };
 declare abstract class Node {
+  #private;
   readonly id: string | undefined;
   readonly position: Vec2Signal;
   readonly rotation: BindableSignal<number>;
@@ -250,6 +268,10 @@ declare abstract class Node {
   readonly blend: BindableSignal<BlendMode>;
   readonly zIndex: BindableSignal<number>;
   readonly filters: BindableSignal<FilterSpec[]>;
+  /** Resolved anchor fraction over the intrinsic box; [0.5, 0.5] = center. */
+  readonly anchor: Vec2;
+  /** True only when the author SET an anchor — unset keeps the legacy origin. */
+  readonly hasAnchor: boolean;
   parent: Node | null;
   /** v2 §C.3: participates in hit testing; set implicitly by attaching a listener. */
   interactive: boolean;
@@ -281,14 +303,35 @@ declare abstract class Node {
     h: number;
   } | null;
   /**
-   * Vector from the node origin to its intrinsic box's TOP-LEFT, so Layout
-   * can place any anchor correctly. Default: center-anchored (every shape).
-   * Text overrides — it draws from a left/center/right baseline origin.
+   * Vector from the DRAW origin to the intrinsic box's top-left, in the
+   * geometry space draw() emits into (anchor-independent — the anchor shift
+   * lives in localMatrix). Hit testing boxes nodes with this. Default:
+   * center-anchored geometry (every shape). Text overrides — it draws from a
+   * left/center/right baseline origin; Path from author-positioned bounds.
+   */
+  drawOffset(measurer?: TextMeasurer): {
+    x: number;
+    y: number;
+  };
+  /**
+   * Vector from the node ORIGIN (the point `position` places) to the box's
+   * top-left, so Layout can place any node. With an anchor this is exactly
+   * (−ax·w, −ay·h); the center default reproduces (−w/2, −h/2).
    */
-  flowOffset(measurer: TextMeasurer): {
+  flowOffset(measurer?: TextMeasurer): {
     x: number;
     y: number;
   };
+  /**
+   * Translation composed after TRS in localMatrix: moves the drawn box so the
+   * anchor point lands on the origin. shift = −(drawOffset + anchor·size).
+   * No anchor set → zero shift, the legacy origin (shape center / Text
+   * baseline / Path author coords) — every pre-anchor scene is byte-stable.
+   * An EXPLICIT anchor pins position to that fraction of the box, even
+   * 'center' (which differs from the legacy origin only for Text and Path).
+   * Nodes without an intrinsic box (Group) warn once and ignore it.
+   */
+  protected anchorShift(measurer?: TextMeasurer): Vec2;
   /** §3.5 predicate: composite-as-a-unit when opacity/blend/filters demand it. */
   protected requiresGroup(): boolean;
   /** §3.7: a subtree-level shader pass; ShaderEffect overrides. */
@@ -297,6 +340,8 @@ declare abstract class Node {
 }
 //#endregion
 //#region src/nodes.d.ts
+/** Rounded-rect path segments — Rect's outline, shared with Highlight. */
+declare function roundedRectSegs(x: number, y: number, w: number, h: number, r: number): PathSeg[];
 declare class Group extends Node {
   readonly children: Node[];
   constructor(props?: NodeProps & {
@@ -369,7 +414,7 @@ declare class Path extends Shape {
     h: number;
   };
   /** Geometry is node-local, not center-anchored: offset to the box's actual top-left. */
-  flowOffset(): {
+  drawOffset(): {
     x: number;
     y: number;
   };
@@ -430,6 +475,24 @@ declare class Video extends Node {
   mediaTime(t: number): number | null;
   protected draw(out: DisplayListBuilder, ctx: EvalContext): void;
 }
+/** One laid-out line's ink box, in the Text node's draw space. */
+interface LineBox {
+  text: string;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+/** One word's ink box within a laid-out line, in the Text node's draw space. */
+interface WordBox {
+  text: string;
+  /** laid-out line index (blank lines keep their slot in the numbering) */
+  line: number;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
 interface TextProps extends NodeProps {
   text?: PropInit<string>;
   fill?: PropInit<string>;
@@ -458,10 +521,36 @@ declare class Text extends Node {
     h: number;
   };
   /** Text draws from a baseline origin at its align edge, not a center (§3.6). */
-  flowOffset(measurer: TextMeasurer): {
+  drawOffset(measurer?: TextMeasurer): {
     x: number;
     y: number;
   };
+  /**
+   * The wrapped box {w, h}, measured with the scene's active measurer — the
+   * same numbers Layout flows with, public so bindings never hand-calculate
+   * text dimensions (e.g. underline width = () => title.measuredSize().w).
+   */
+  measuredSize(measurer?: TextMeasurer): {
+    w: number;
+    h: number;
+  };
+  /**
+   * Per-line ink boxes in this node's DRAW space (origin = first baseline at
+   * the align edge), from the same breakLines pass that draws. Pull-based:
+   * re-measures when text/font/width animate. Blank lines (from '\n\n')
+   * produce no box. The substrate for highlights, underlines, per-line
+   * reveals, selections.
+   */
+  lineBoxes(measurer?: TextMeasurer): LineBox[];
+  /**
+   * Per-word ink boxes within each laid-out line — the SAME segmentation the
+   * breaker flows (Intl.Segmenter boundaries, punctuation glued), positioned
+   * by cumulative prefix advances so cross-word kerning is exact and word
+   * widths sum to the line's width. Whitespace contributes advance but no
+   * box. Pair index-wise with a narration manifest's word timestamps for
+   * karaoke; draw your own rects for sub-line multi-color token work.
+   */
+  wordBoxes(measurer?: TextMeasurer): WordBox[];
   protected draw(out: DisplayListBuilder, ctx: EvalContext): void;
 }
 //#endregion
@@ -513,4 +602,4 @@ declare function setLayoutEngine(e: LayoutEngine): void;
 declare function getLayoutEngine(): LayoutEngine | null;
 declare function requireLayoutEngine(): LayoutEngine;
 //#endregion
-export { applyToPoint as $, breakLines as A, Paint as B, EvalContext as C, PropInit as D, NodeProps as E, DisplayListBuilder as F, ShaderRef as G, Rect$1 as H, DrawCommand as I, filtersToCanvasFilter as J, StrokeStyle as K, FilterSpec as L, quantize as M, BlendMode as N, TextMeasurer as O, DisplayList as P, Mat2x3 as Q, FilterValidationError as R, BindablePropTarget as S, Node as T, Resource as U, PathSeg as V, ResourceId as W, validateFilters as X, glow as Y, IDENTITY as Z, ShapeProps as _, LayoutEngineMissingError as a, Video as b, requireLayoutEngine as c, Group as d, fromTRS as et, ImageNode as f, Rect as g, PathProps as h, LayoutEngine as i, estimatingMeasurer as j, TextMetricsLite as k, setLayoutEngine as l, Path as m, LayoutChildSpec as n, matEquals as nt, LayoutResult as o, ImageProps as p, createDisplayListBuilder as q, LayoutContainerSpec as r, multiply as rt, getLayoutEngine as s, LayoutBox as t, invert as tt, Circle as u, Text as v, HitArea as w, VideoProps as x, TextProps as y, FontSpec as z };
+export { createDisplayListBuilder as $, NodeProps as A, DisplayList as B, WordBox as C, EvalContext as D, BindablePropTarget as E, breakLines as F, FontSpec as G, DrawCommand as H, estimatingMeasurer as I, Rect$1 as J, Paint as K, quantize as L, resolveAnchor as M, TextMeasurer as N, HitArea as O, TextMetricsLite as P, StrokeStyle as Q, segmentWords as R, VideoProps as S, AnchorSpec as T, FilterSpec as U, DisplayListBuilder as V, FilterValidationError as W, ResourceId as X, Resource as Y, ShaderRef as Z, Rect as _, LayoutEngineMissingError as a, applyToPoint as at, TextProps as b, requireLayoutEngine as c, matEquals as ct, Group as d, filtersToCanvasFilter as et, ImageNode as f, PathProps as g, Path as h, LayoutEngine as i, Mat2x3 as it, PropInit as j, Node as k, setLayoutEngine as l, multiply as lt, LineBox as m, LayoutChildSpec as n, validateFilters as nt, LayoutResult as o, fromTRS as ot, ImageProps as p, PathSeg as q, LayoutContainerSpec as r, IDENTITY as rt, getLayoutEngine as s, invert as st, LayoutBox as t, glow as tt, Circle as u, ShapeProps as v, roundedRectSegs as w, Video as x, Text as y, BlendMode as z };

package/dist/layoutEngine.js

@@ -1,4 +1,4 @@
-import { TARGET_PATH, computed, signal, vec2Signal } from "@glissade/core";
+import { TARGET_PATH, computed, emitDevWarning, signal, vec2Signal } from "@glissade/core";
 //#region src/matrix.ts
 const IDENTITY = [
 	1,
@@ -166,6 +166,11 @@ const estimatingMeasurer = { measureText(text, font) {
 	};
 } };
 let wordSegmenter;
+/**
+* The draw-path word segmentation (Intl.Segmenter boundaries, punctuation
+* glued to its predecessor) — exported so Text.wordBoxes() boxes EXACTLY the
+* units the breaker flows.
+*/
 function segmentWords(text) {
 	if (wordSegmenter === void 0) wordSegmenter = typeof Intl !== "undefined" && "Segmenter" in Intl ? new Intl.Segmenter(void 0, { granularity: "word" }) : null;
 	if (wordSegmenter) {
@@ -208,6 +213,25 @@ function breakLines(text, font, maxWidth, measurer) {
 * signal; transforms are computed matrix signals; emit() is pure — it reads
 * signals and ctx only, and produces IR commands, never canvas calls.
 */
+const ANCHOR_PRESETS = {
+	"center": [.5, .5],
+	"top-left": [0, 0],
+	"top": [.5, 0],
+	"top-right": [1, 0],
+	"left": [0, .5],
+	"right": [1, .5],
+	"bottom-left": [0, 1],
+	"bottom": [.5, 1],
+	"bottom-right": [1, 1]
+};
+function resolveAnchor(spec) {
+	if (typeof spec === "string") {
+		const preset = ANCHOR_PRESETS[spec];
+		if (!preset) throw new Error(`unknown anchor '${spec}' (use a preset like 'top-left' or a [ax, ay] pair)`);
+		return preset;
+	}
+	return [spec[0], spec[1]];
+}
 function initScalar(sig, init) {
 	if (typeof init === "function") sig.bindSource(init);
 	else if (init !== void 0) sig.set(init);
@@ -227,7 +251,12 @@ var Node = class {
 	blend;
 	zIndex;
 	filters;
+	/** Resolved anchor fraction over the intrinsic box; [0.5, 0.5] = center. */
+	anchor;
+	/** True only when the author SET an anchor — unset keeps the legacy origin. */
+	hasAnchor;
 	parent = null;
+	#warnedAnchor = false;
 	/** v2 §C.3: participates in hit testing; set implicitly by attaching a listener. */
 	interactive = false;
 	/** v2 §C.3: false prunes this subtree from hit testing (PixiJS's flag). */
@@ -253,7 +282,20 @@ var Node = class {
 		this.blend = initScalar(signal("source-over"), props.blend);
 		this.zIndex = initScalar(signal(0), props.zIndex);
 		this.filters = initScalar(signal([]), props.filters);
-		this.localMatrix = computed(() => fromTRS(this.position(), this.rotation(), this.scale()), { equals: matEquals });
+		this.hasAnchor = props.anchor !== void 0;
+		this.anchor = resolveAnchor(props.anchor ?? "center");
+		this.localMatrix = computed(() => {
+			const trs = fromTRS(this.position(), this.rotation(), this.scale());
+			const [sx, sy] = this.anchorShift();
+			return sx === 0 && sy === 0 ? trs : multiply(trs, [
+				1,
+				0,
+				0,
+				1,
+				sx,
+				sy
+			]);
+		}, { equals: matEquals });
 		this.worldMatrix = computed(() => this.parent ? multiply(this.parent.worldMatrix(), this.localMatrix()) : this.localMatrix(), { equals: matEquals });
 		this.registerTarget("position", this.position);
 		this.registerTarget("position.x", this.position.x);
@@ -280,12 +322,15 @@ var Node = class {
 		return null;
 	}
 	/**
-	* Vector from the node origin to its intrinsic box's TOP-LEFT, so Layout
-	* can place any anchor correctly. Default: center-anchored (every shape).
-	* Text overrides — it draws from a left/center/right baseline origin.
+	* Vector from the DRAW origin to the intrinsic box's top-left, in the
+	* geometry space draw() emits into (anchor-independent — the anchor shift
+	* lives in localMatrix). Hit testing boxes nodes with this. Default:
+	* center-anchored geometry (every shape). Text overrides — it draws from a
+	* left/center/right baseline origin; Path from author-positioned bounds.
 	*/
-	flowOffset(measurer) {
-		const size = this.intrinsicSize(measurer) ?? {
+	drawOffset(measurer) {
+		const m = measurer ?? this.measurerSource?.() ?? estimatingMeasurer;
+		const size = this.intrinsicSize(m) ?? {
 			w: 0,
 			h: 0
 		};
@@ -294,6 +339,46 @@ var Node = class {
 			y: -size.h / 2
 		};
 	}
+	/**
+	* Vector from the node ORIGIN (the point `position` places) to the box's
+	* top-left, so Layout can place any node. With an anchor this is exactly
+	* (−ax·w, −ay·h); the center default reproduces (−w/2, −h/2).
+	*/
+	flowOffset(measurer) {
+		const m = measurer ?? this.measurerSource?.() ?? estimatingMeasurer;
+		const d = this.drawOffset(m);
+		const [sx, sy] = this.anchorShift(m);
+		return {
+			x: d.x + sx,
+			y: d.y + sy
+		};
+	}
+	/**
+	* Translation composed after TRS in localMatrix: moves the drawn box so the
+	* anchor point lands on the origin. shift = −(drawOffset + anchor·size).
+	* No anchor set → zero shift, the legacy origin (shape center / Text
+	* baseline / Path author coords) — every pre-anchor scene is byte-stable.
+	* An EXPLICIT anchor pins position to that fraction of the box, even
+	* 'center' (which differs from the legacy origin only for Text and Path).
+	* Nodes without an intrinsic box (Group) warn once and ignore it.
+	*/
+	anchorShift(measurer) {
+		if (!this.hasAnchor) return [0, 0];
+		const [ax, ay] = this.anchor;
+		const m = measurer ?? this.measurerSource?.() ?? estimatingMeasurer;
+		const size = this.intrinsicSize(m);
+		if (!size) {
+			if (!this.#warnedAnchor) {
+				this.#warnedAnchor = true;
+				emitDevWarning(`anchor set on a node without an intrinsic box${this.id ? ` ('${this.id}')` : ""} — ignored (give it a sized node, or position children explicitly)`);
+			}
+			return [0, 0];
+		}
+		const d = this.drawOffset(m);
+		const sx = -(d.x + ax * size.w);
+		const sy = -(d.y + ay * size.h);
+		return [sx === 0 ? 0 : sx, sy === 0 ? 0 : sy];
+	}
 	/** §3.5 predicate: composite-as-a-unit when opacity/blend/filters demand it. */
 	requiresGroup() {
 		return this.opacity() < 1 || this.blend() !== "source-over" || this.filters().length > 0;
@@ -330,6 +415,101 @@ var Node = class {
 * Built-in nodes for M1 (DESIGN.md §3.1): Group, Rect, Circle, Text.
 * Path/Image/Video/Layout arrive with their milestones.
 */
+/** Rounded-rect path segments — Rect's outline, shared with Highlight. */
+function roundedRectSegs(x, y, w, h, r) {
+	if (r <= 0) return [
+		[
+			"M",
+			x,
+			y
+		],
+		[
+			"L",
+			x + w,
+			y
+		],
+		[
+			"L",
+			x + w,
+			y + h
+		],
+		[
+			"L",
+			x,
+			y + h
+		],
+		["Z"]
+	];
+	const HALF = Math.PI / 2;
+	return [
+		[
+			"M",
+			x + r,
+			y
+		],
+		[
+			"L",
+			x + w - r,
+			y
+		],
+		[
+			"E",
+			x + w - r,
+			y + r,
+			r,
+			r,
+			0,
+			-HALF,
+			0
+		],
+		[
+			"L",
+			x + w,
+			y + h - r
+		],
+		[
+			"E",
+			x + w - r,
+			y + h - r,
+			r,
+			r,
+			0,
+			0,
+			HALF
+		],
+		[
+			"L",
+			x + r,
+			y + h
+		],
+		[
+			"E",
+			x + r,
+			y + h - r,
+			r,
+			r,
+			0,
+			HALF,
+			Math.PI
+		],
+		[
+			"L",
+			x,
+			y + r
+		],
+		[
+			"E",
+			x + r,
+			y + r,
+			r,
+			r,
+			0,
+			Math.PI,
+			Math.PI + HALF
+		],
+		["Z"]
+	];
+}
 var Group = class extends Node {
 	children;
 	constructor(props = {}) {
@@ -419,101 +599,8 @@ var Rect = class extends Shape {
 	pathSegs() {
 		const w = this.width();
 		const h = this.height();
-		const x = -w / 2;
-		const y = -h / 2;
 		const r = Math.min(Math.max(0, this.cornerRadius()), w / 2, h / 2);
-		if (r <= 0) return [
-			[
-				"M",
-				x,
-				y
-			],
-			[
-				"L",
-				x + w,
-				y
-			],
-			[
-				"L",
-				x + w,
-				y + h
-			],
-			[
-				"L",
-				x,
-				y + h
-			],
-			["Z"]
-		];
-		const HALF = Math.PI / 2;
-		return [
-			[
-				"M",
-				x + r,
-				y
-			],
-			[
-				"L",
-				x + w - r,
-				y
-			],
-			[
-				"E",
-				x + w - r,
-				y + r,
-				r,
-				r,
-				0,
-				-HALF,
-				0
-			],
-			[
-				"L",
-				x + w,
-				y + h - r
-			],
-			[
-				"E",
-				x + w - r,
-				y + h - r,
-				r,
-				r,
-				0,
-				0,
-				HALF
-			],
-			[
-				"L",
-				x + r,
-				y + h
-			],
-			[
-				"E",
-				x + r,
-				y + h - r,
-				r,
-				r,
-				0,
-				HALF,
-				Math.PI
-			],
-			[
-				"L",
-				x,
-				y + r
-			],
-			[
-				"E",
-				x + r,
-				y + r,
-				r,
-				r,
-				0,
-				Math.PI,
-				Math.PI + HALF
-			],
-			["Z"]
-		];
+		return roundedRectSegs(-w / 2, -h / 2, w, h, r);
 	}
 };
 var Circle = class extends Shape {
@@ -598,7 +685,7 @@ var Path = class extends Shape {
 		};
 	}
 	/** Geometry is node-local, not center-anchored: offset to the box's actual top-left. */
-	flowOffset() {
+	drawOffset() {
 		const b = this.bounds();
 		return {
 			x: b.minX,
@@ -781,20 +868,112 @@ var Text = class extends Node {
 		};
 	}
 	/** Text draws from a baseline origin at its align edge, not a center (§3.6). */
-	flowOffset(measurer) {
-		const size = this.intrinsicSize(measurer);
+	drawOffset(measurer) {
+		const m = measurer ?? this.measurerSource?.() ?? estimatingMeasurer;
+		const size = this.intrinsicSize(m);
 		const font = {
 			family: this.fontFamily,
 			size: this.fontSize(),
 			weight: this.fontWeight
 		};
-		const firstLine = breakLines(this.text(), font, this.width() > 0 ? this.width() : void 0, measurer)[0] ?? "";
-		const ascent = measurer.measureText(firstLine, font).ascent;
+		const firstLine = breakLines(this.text(), font, this.width() > 0 ? this.width() : void 0, m)[0] ?? "";
+		const ascent = m.measureText(firstLine, font).ascent;
 		return {
 			x: this.align === "left" ? 0 : this.align === "center" ? -size.w / 2 : -size.w,
 			y: -ascent
 		};
 	}
+	/**
+	* The wrapped box {w, h}, measured with the scene's active measurer — the
+	* same numbers Layout flows with, public so bindings never hand-calculate
+	* text dimensions (e.g. underline width = () => title.measuredSize().w).
+	*/
+	measuredSize(measurer) {
+		return this.intrinsicSize(measurer ?? this.measurerSource?.() ?? estimatingMeasurer);
+	}
+	/**
+	* Per-line ink boxes in this node's DRAW space (origin = first baseline at
+	* the align edge), from the same breakLines pass that draws. Pull-based:
+	* re-measures when text/font/width animate. Blank lines (from '\n\n')
+	* produce no box. The substrate for highlights, underlines, per-line
+	* reveals, selections.
+	*/
+	lineBoxes(measurer) {
+		const m = measurer ?? this.measurerSource?.() ?? estimatingMeasurer;
+		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 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 w = quantize(met.width);
+			const x = this.align === "left" ? 0 : this.align === "center" ? -w / 2 : -w;
+			boxes.push({
+				text: line,
+				x,
+				y: i * step - met.ascent,
+				w,
+				h: met.ascent + met.descent
+			});
+		}
+		return boxes;
+	}
+	/**
+	* Per-word ink boxes within each laid-out line — the SAME segmentation the
+	* breaker flows (Intl.Segmenter boundaries, punctuation glued), positioned
+	* by cumulative prefix advances so cross-word kerning is exact and word
+	* widths sum to the line's width. Whitespace contributes advance but no
+	* box. Pair index-wise with a narration manifest's word timestamps for
+	* karaoke; draw your own rects for sub-line multi-color token work.
+	*/
+	wordBoxes(measurer) {
+		const m = measurer ?? this.measurerSource?.() ?? estimatingMeasurer;
+		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 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 seg of segmentWords(line)) {
+				const before = prefix === "" ? 0 : m.measureText(prefix, font).width;
+				prefix += seg;
+				if (seg.trim() === "") continue;
+				const after = m.measureText(prefix, font).width;
+				boxes.push({
+					text: seg,
+					line: i,
+					x: lineX + before,
+					y,
+					w: after - before,
+					h
+				});
+			}
+		}
+		return boxes;
+	}
 	draw(out, ctx) {
 		const text = this.text();
 		if (!text) return;
@@ -843,4 +1022,4 @@ function requireLayoutEngine() {
 	return engine;
 }
 //#endregion
-export { fromTRS as C, multiply as E, applyToPoint as S, matEquals as T, createDisplayListBuilder as _, Circle as a, validateFilters as b, Path as c, Video as d, Node as f, FilterValidationError as g, quantize as h, setLayoutEngine as i, Rect as l, estimatingMeasurer as m, getLayoutEngine as n, Group as o, breakLines as p, requireLayoutEngine as r, ImageNode as s, LayoutEngineMissingError as t, Text as u, filtersToCanvasFilter as v, invert as w, IDENTITY as x, glow as y };
+export { validateFilters as C, invert as D, fromTRS as E, matEquals as O, glow as S, applyToPoint as T, quantize as _, Circle as a, createDisplayListBuilder as b, Path as c, Video as d, roundedRectSegs as f, estimatingMeasurer as g, breakLines as h, setLayoutEngine as i, multiply 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, segmentWords as v, IDENTITY as w, filtersToCanvasFilter as x, FilterValidationError as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/scene",
-  "version": "0.4.0",
+  "version": "0.4.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.4.0"
+    "@glissade/core": "0.4.2"
   },
   "repository": {
     "type": "git",