@glissade/scene 0.2.0 → 0.3.0

package/README.md

@@ -0,0 +1,26 @@
+# @glissade/scene
+
+The scene graph and the **DisplayList IR**: nodes (Group, Rect, Circle, Text, Image, Video) whose every animatable property is a signal, `createScene`, and the canonical `evaluate(scene, timeline, t) → DisplayList`. Text layout (explicit fonts, Intl.Segmenter line breaking) is deterministic across browser and headless render. Yoga flexbox lives behind the LayoutEngine seam at the separate `@glissade/scene/layout` entry — the base path never pays for wasm — including `width/height: 'auto'` content sizing and `computedSize()`.
+
+```sh
+npm i @glissade/scene @glissade/core
+```
+
+```ts
+import { createScene, Circle, evaluate } from '@glissade/scene';
+
+const scene = createScene({
+  size: { w: 640, h: 360 },
+  children: [new Circle({ id: 'dot', radius: 40, fill: '#e6a700', position: [320, 180] })],
+});
+const displayList = evaluate(scene, doc, 1.25); // pure, serializable, renderer-agnostic
+```
+
+## Part of glissade
+
+*(glide & slide)* — programmatic motion graphics for TypeScript: realtime-first in any web page, deterministic headless video export from the same code, a visual studio over the same document. No generator functions.
+
+- [Repository & full README](https://github.com/tyevco/glissade)
+- [Getting started](https://github.com/tyevco/glissade/blob/main/docs/getting-started.md) · [Concepts](https://github.com/tyevco/glissade/blob/main/docs/concepts.md) · [Interactivity](https://github.com/tyevco/glissade/blob/main/docs/interactivity.md)
+
+Apache-2.0.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { A as BlendMode, B as ResourceId, C as NodeProps, D as breakLines, E as TextMetricsLite, F as FontSpec, G as applyToPoint, H as createDisplayListBuilder, I as Paint, J as matEquals, K as fromTRS, L as PathSeg, M as DisplayListBuilder, N as DrawCommand, O as estimatingMeasurer, P as FilterSpec, R as Rect$1, S as Node, T as TextMeasurer, U as IDENTITY, V as StrokeStyle, W as Mat2x3, Y as multiply, _ as Video, a as LayoutEngineMissingError, b as EvalContext, c as setLayoutEngine, d as ImageNode, f as ImageProps, g as TextProps, h as Text, i as LayoutEngine, j as DisplayList, k as quantize, l as Circle, m as ShapeProps, n as LayoutChildSpec, o as getLayoutEngine, p as Rect, q as invert, r as LayoutContainerSpec, s as requireLayoutEngine, t as LayoutBox, u as Group, v as VideoProps, w as PropInit, x as HitArea, y as BindablePropTarget, z as Resource } from "./layoutEngine.js";
+import { $ as invert, A as breakLines, B as Paint, C as EvalContext, D as PropInit, E as NodeProps, F as DisplayListBuilder, G as StrokeStyle, H as Rect$1, I as DrawCommand, J as validateFilters, K as createDisplayListBuilder, L as FilterSpec, M as quantize, N as BlendMode, O as TextMeasurer, P as DisplayList, Q as fromTRS, R as FilterValidationError, S as BindablePropTarget, T as Node, U as Resource, V as PathSeg, W as ResourceId, X as Mat2x3, Y as IDENTITY, Z as applyToPoint, _ as ShapeProps, a as LayoutEngineMissingError, b as Video, c as requireLayoutEngine, d as Group, et as matEquals, 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, p as ImageProps, q as filtersToCanvasFilter, r as LayoutContainerSpec, s as getLayoutEngine, t as LayoutBox, tt as multiply, u as Circle, v as Text, w as HitArea, x as VideoProps, y as TextProps, z as FontSpec } from "./layoutEngine.js";
 import { BoundTimeline, CompiledTimeline, Playhead, Timeline } from "@glissade/core";
 
 //#region src/assets.d.ts
@@ -37,6 +37,77 @@ declare class ColdAssetError extends Error {
   constructor(assetId: string, detail: string, mediaT?: number);
 }
 //#endregion
+//#region src/raster2d.d.ts
+/** The structural path surface buildPath drives — DOM Path2D and @napi-rs Path2D both satisfy it. */
+interface PathLike {
+  moveTo(x: number, y: number): void;
+  lineTo(x: number, y: number): void;
+  bezierCurveTo(x1: number, y1: number, x2: number, y2: number, x: number, y: number): void;
+  quadraticCurveTo(cx: number, cy: number, x: number, y: number): void;
+  ellipse(cx: number, cy: number, rx: number, ry: number, rot: number, a0: number, a1: number): void;
+  closePath(): void;
+}
+/** The exact 2D-context surface the interpreter uses — nothing more. */
+interface Ctx2DLike<TPath, TDrawable> {
+  save(): void;
+  restore(): void;
+  transform(a: number, b: number, c: number, d: number, e: number, f: number): void;
+  resetTransform(): void;
+  getTransform(): unknown;
+  setTransform(m: unknown): void;
+  clearRect(x: number, y: number, w: number, h: number): void;
+  clip(path: TPath, rule: 'nonzero' | 'evenodd'): void;
+  fill(path: TPath): void;
+  stroke(path: TPath): void;
+  fillText(text: string, x: number, y: number): void;
+  drawImage(image: TDrawable, x: number, y: number, w?: number, h?: number): void;
+  drawImage(image: TDrawable, sx: number, sy: number, sw: number, sh: number, x: number, y: number, w: number, h: number): void;
+  setLineDash(segments: number[]): void;
+  fillStyle: unknown;
+  strokeStyle: unknown;
+  lineWidth: number;
+  lineCap: string;
+  lineJoin: string;
+  font: string;
+  textBaseline: string;
+  textAlign: string;
+  globalAlpha: number;
+  globalCompositeOperation: string;
+  filter: string;
+  imageSmoothingEnabled: boolean;
+}
+interface CanvasLike {
+  width: number;
+  height: number;
+}
+/** What a backend supplies: constructors and context access for its canvas flavor. */
+interface Raster2DHost<TCanvas extends CanvasLike, TPath extends PathLike, TDrawable> {
+  context(canvas: TCanvas): Ctx2DLike<TPath, TDrawable>;
+  createCanvas(w: number, h: number): TCanvas;
+  newPath(): TPath;
+}
+declare function fontString(font: FontSpec): string;
+declare class Raster2D<TCanvas extends CanvasLike, TPath extends PathLike, TDrawable> {
+  private readonly host;
+  private readonly pool;
+  private readonly pathCache;
+  private readonly images;
+  private readonly videos;
+  constructor(host: Raster2DHost<TCanvas, TPath, TDrawable>);
+  /** Register a decoded still (kind 'image' assets). */
+  setImageAsset(assetId: string, image: TDrawable): void;
+  /** Register a warmed-on-demand video source (kind 'video' assets, §3.8). */
+  setVideoAsset(assetId: string, source: VideoFrameSource): void;
+  dispose(): void;
+  private resolveDrawable;
+  private path;
+  private buildPath;
+  private acquire;
+  private release;
+  /** The command walk — order and operations identical to the pre-extraction twins. */
+  render(target: TCanvas, list: DisplayList): void;
+}
+//#endregion
 //#region src/scene.d.ts
 interface Scene {
   readonly root: Group;
@@ -86,4 +157,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, Circle, ColdAssetError, type DisplayList, type DisplayListBuilder, type DrawCommand, DuplicateNodeIdError, type EvalContext, type FilterSpec, 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, type PathSeg, type PropInit, Rect, type Rect$1 as RectShape, type Resource, type ResourceId, type Scene, type SceneInit, type SceneModule, type ShapeProps, type StrokeStyle, Text, type TextMeasurer, type TextMetricsLite, type TextProps, Video, type VideoFrameSource, type VideoProps, applyToPoint, bindScene, breakLines, createDisplayListBuilder, createScene, estimatingMeasurer, evaluate, fromTRS, getLayoutEngine, invert, matEquals, multiply, quantize, requireLayoutEngine, setLayoutEngine };
+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 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, invert, matEquals, multiply, quantize, requireLayoutEngine, setLayoutEngine, validateFilters };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { _ as applyToPoint, a as Circle, b as matEquals, c as Rect, d as Node, f as breakLines, g as IDENTITY, h as createDisplayListBuilder, i as setLayoutEngine, l as Text, m as quantize, n as getLayoutEngine, o as Group, p as estimatingMeasurer, r as requireLayoutEngine, s as ImageNode, t as LayoutEngineMissingError, u as Video, v as fromTRS, x as multiply, y as invert } from "./layoutEngine.js";
+import { C as invert, S as fromTRS, T as multiply, _ as createDisplayListBuilder, a as Circle, b as IDENTITY, 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 matEquals, x as applyToPoint, y as validateFilters } from "./layoutEngine.js";
 import { bindTimeline, compileTimeline, createPlayhead, evaluateAt } from "@glissade/core";
 //#region src/assets.ts
 var ColdAssetError = class extends Error {
@@ -15,6 +15,201 @@ var ColdAssetError = class extends Error {
 	}
 };
 //#endregion
+//#region src/raster2d.ts
+/**
+* The shared DisplayList interpreter (§3.4): one command walk over the
+* canvas-2d-shaped API, generic over the host's canvas/path/drawable types.
+* backend-canvas2d (DOM) and backend-skia (@napi-rs) instantiate it with
+* four-line adapters, so the twin rasterizers structurally cannot drift —
+* the golden + SSIM suites verify the refactor preserved every byte.
+*/
+function fontString(font) {
+	return `${font.style === "italic" ? "italic " : ""}${font.weight !== void 0 && font.weight !== 400 ? `${font.weight} ` : ""}${font.size}px ${font.family}`;
+}
+var Raster2D = class {
+	host;
+	pool = [];
+	pathCache = /* @__PURE__ */ new WeakMap();
+	images = /* @__PURE__ */ new Map();
+	videos = /* @__PURE__ */ new Map();
+	constructor(host) {
+		this.host = host;
+	}
+	/** Register a decoded still (kind 'image' assets). */
+	setImageAsset(assetId, image) {
+		this.images.set(assetId, image);
+	}
+	/** Register a warmed-on-demand video source (kind 'video' assets, §3.8). */
+	setVideoAsset(assetId, source) {
+		this.videos.set(assetId, source);
+	}
+	dispose() {
+		this.pool.length = 0;
+	}
+	resolveDrawable(res, id) {
+		if (res.kind === "image") {
+			const img = this.images.get(res.assetId);
+			if (!img) throw new ColdAssetError(res.assetId, "no decoded image registered");
+			return img;
+		}
+		if (res.kind === "videoFrame") {
+			const source = this.videos.get(res.assetId);
+			if (!source) throw new ColdAssetError(res.assetId, "no VideoFrameSource registered", res.mediaT);
+			try {
+				return source.getFrameSync(res.mediaT);
+			} catch (e) {
+				if (e instanceof ColdAssetError) throw new ColdAssetError(res.assetId, e.detail, res.mediaT);
+				throw e;
+			}
+		}
+		throw new Error(`resource ${id} is not drawable`);
+	}
+	path(resources, id) {
+		const res = resources[id];
+		if (!res || res.kind !== "path") throw new Error(`resource ${id} is not a path`);
+		let p = this.pathCache.get(res);
+		if (!p) {
+			p = this.buildPath(res.segs);
+			this.pathCache.set(res, p);
+		}
+		return p;
+	}
+	buildPath(segs) {
+		const p = this.host.newPath();
+		for (const seg of segs) switch (seg[0]) {
+			case "M":
+				p.moveTo(seg[1], seg[2]);
+				break;
+			case "L":
+				p.lineTo(seg[1], seg[2]);
+				break;
+			case "C":
+				p.bezierCurveTo(seg[1], seg[2], seg[3], seg[4], seg[5], seg[6]);
+				break;
+			case "Q":
+				p.quadraticCurveTo(seg[1], seg[2], seg[3], seg[4]);
+				break;
+			case "E":
+				p.ellipse(seg[1], seg[2], seg[3], seg[4], seg[5], seg[6], seg[7]);
+				break;
+			case "Z":
+				p.closePath();
+				break;
+		}
+		return p;
+	}
+	acquire(w, h) {
+		const pooled = this.pool.pop();
+		if (pooled) {
+			if (pooled.width !== w) pooled.width = w;
+			if (pooled.height !== h) pooled.height = h;
+			return pooled;
+		}
+		return this.host.createCanvas(w, h);
+	}
+	release(canvas) {
+		if (this.pool.length < 8) this.pool.push(canvas);
+	}
+	/** The command walk — order and operations identical to the pre-extraction twins. */
+	render(target, list) {
+		const { w, h } = list.size;
+		if (target.width !== w) target.width = w;
+		if (target.height !== h) target.height = h;
+		const base = this.host.context(target);
+		base.resetTransform();
+		base.clearRect(0, 0, w, h);
+		const layers = [{
+			ctx: base,
+			canvas: null,
+			opacity: 1,
+			blend: "source-over"
+		}];
+		const ctxOf = () => layers[layers.length - 1].ctx;
+		for (const cmd of list.commands) switch (cmd.op) {
+			case "save":
+				ctxOf().save();
+				break;
+			case "restore":
+				ctxOf().restore();
+				break;
+			case "transform":
+				ctxOf().transform(cmd.m[0], cmd.m[1], cmd.m[2], cmd.m[3], cmd.m[4], cmd.m[5]);
+				break;
+			case "clip":
+				ctxOf().clip(this.path(list.resources, cmd.path), cmd.rule ?? "nonzero");
+				break;
+			case "fillPath": {
+				const ctx = ctxOf();
+				ctx.fillStyle = cmd.paint.color;
+				ctx.fill(this.path(list.resources, cmd.path));
+				break;
+			}
+			case "strokePath": {
+				const ctx = ctxOf();
+				ctx.strokeStyle = cmd.paint.color;
+				ctx.lineWidth = cmd.stroke.width;
+				ctx.lineCap = cmd.stroke.cap ?? "butt";
+				ctx.lineJoin = cmd.stroke.join ?? "miter";
+				if (cmd.stroke.dash) ctx.setLineDash(cmd.stroke.dash);
+				ctx.stroke(this.path(list.resources, cmd.path));
+				if (cmd.stroke.dash) ctx.setLineDash([]);
+				break;
+			}
+			case "fillText": {
+				const ctx = ctxOf();
+				ctx.font = fontString(cmd.font);
+				ctx.fillStyle = cmd.paint.color;
+				ctx.textBaseline = "alphabetic";
+				ctx.textAlign = cmd.align ?? "left";
+				ctx.fillText(cmd.text, cmd.x, cmd.y);
+				break;
+			}
+			case "drawImage": {
+				const res = list.resources[cmd.image];
+				if (!res) throw new Error(`drawImage references missing resource ${cmd.image}`);
+				const drawable = this.resolveDrawable(res, cmd.image);
+				const ctx = ctxOf();
+				if (cmd.smoothing !== void 0) ctx.imageSmoothingEnabled = cmd.smoothing;
+				const { x, y, w: dw, h: dh } = cmd.dst;
+				if (cmd.src) ctx.drawImage(drawable, cmd.src.x, cmd.src.y, cmd.src.w, cmd.src.h, x, y, dw, dh);
+				else ctx.drawImage(drawable, x, y, dw, dh);
+				break;
+			}
+			case "pushGroup": {
+				const parent = ctxOf();
+				const layerCanvas = this.acquire(w, h);
+				const layerCtx = this.host.context(layerCanvas);
+				layerCtx.resetTransform();
+				layerCtx.clearRect(0, 0, w, h);
+				layerCtx.setTransform(parent.getTransform());
+				layers.push({
+					ctx: layerCtx,
+					canvas: layerCanvas,
+					opacity: cmd.opacity,
+					blend: cmd.blend,
+					filter: filtersToCanvasFilter(cmd.filters)
+				});
+				break;
+			}
+			case "popGroup": {
+				const layer = layers.pop();
+				if (!layer || layer.canvas === null) throw new Error("popGroup without matching pushGroup");
+				const parent = ctxOf();
+				parent.save();
+				parent.resetTransform();
+				parent.globalAlpha = layer.opacity;
+				if (layer.filter !== void 0 && layer.filter !== "none") parent.filter = layer.filter;
+				parent.globalCompositeOperation = layer.blend;
+				parent.drawImage(layer.canvas, 0, 0);
+				parent.restore();
+				this.release(layer.canvas);
+				break;
+			}
+		}
+		if (layers.length !== 1) throw new Error("unbalanced pushGroup/popGroup in DisplayList");
+	}
+};
+//#endregion
 //#region src/scene.ts
 /**
 * Scene assembly + the canonical evaluate(scene, timeline, t) (DESIGN.md §2.5,
@@ -27,12 +222,13 @@ var DuplicateNodeIdError = class extends Error {
 		this.name = "DuplicateNodeIdError";
 	}
 };
-function indexNodes(root, into) {
+function indexNodes(root, into, measurerSource) {
+	root.measurerSource = measurerSource;
 	if (root.id !== void 0) {
 		if (into.has(root.id)) throw new DuplicateNodeIdError(root.id);
 		into.set(root.id, root);
 	}
-	if (root instanceof Group) for (const child of root.children) indexNodes(child, into);
+	if (root instanceof Group) for (const child of root.children) indexNodes(child, into, measurerSource);
 }
 function createScene(init) {
 	const root = new Group({
@@ -40,9 +236,9 @@ function createScene(init) {
 		children: init.children
 	});
 	const nodes = /* @__PURE__ */ new Map();
-	indexNodes(root, nodes);
 	const playhead = createPlayhead();
 	let measurer = estimatingMeasurer;
+	indexNodes(root, nodes, () => measurer);
 	return {
 		root,
 		nodes,
@@ -99,4 +295,4 @@ function evaluate(scene, doc, t) {
 	});
 }
 //#endregion
-export { Circle, ColdAssetError, DuplicateNodeIdError, Group, IDENTITY, ImageNode, LayoutEngineMissingError, Node, Rect, Text, Video, applyToPoint, bindScene, breakLines, createDisplayListBuilder, createScene, estimatingMeasurer, evaluate, fromTRS, getLayoutEngine, invert, matEquals, multiply, quantize, requireLayoutEngine, setLayoutEngine };
+export { Circle, ColdAssetError, DuplicateNodeIdError, FilterValidationError, Group, IDENTITY, ImageNode, LayoutEngineMissingError, Node, Path, Raster2D, Rect, Text, Video, applyToPoint, bindScene, breakLines, createDisplayListBuilder, createScene, estimatingMeasurer, evaluate, filtersToCanvasFilter, fontString, fromTRS, getLayoutEngine, invert, matEquals, multiply, quantize, requireLayoutEngine, setLayoutEngine, validateFilters };

package/dist/layout.d.ts

@@ -1,12 +1,13 @@
-import { C as NodeProps, M as DisplayListBuilder, S as Node, a as LayoutEngineMissingError, b as EvalContext, c as setLayoutEngine, i as LayoutEngine, n as LayoutChildSpec, o as getLayoutEngine, r as LayoutContainerSpec, t as LayoutBox, u as Group, w as PropInit } from "./layoutEngine.js";
+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 { BindableSignal } from "@glissade/core";
 
 //#region src/layout.d.ts
 
 interface LayoutProps extends NodeProps {
   children?: Node[];
-  width?: PropInit<number>;
-  height?: PropInit<number>;
+  /** 'auto': the axis sizes itself from content (Yoga content sizing). */
+  width?: PropInit<number> | 'auto';
+  height?: PropInit<number> | 'auto';
   direction?: 'row' | 'column';
   gap?: PropInit<number>;
   padding?: PropInit<number>;
@@ -33,8 +34,21 @@ declare class Layout extends Group {
   readonly direction: 'row' | 'column';
   readonly justify: LayoutContainerSpec['justify'];
   readonly align: LayoutContainerSpec['align'];
+  /** Content-sized axes ('auto'): the size signal is ignored, Yoga computes it. */
+  readonly autoWidth: boolean;
+  readonly autoHeight: boolean;
   constructor(props?: LayoutProps);
-  intrinsicSize(): {
+  intrinsicSize(measurer: TextMeasurer): {
+    w: number;
+    h: number;
+  };
+  /**
+   * The resolved container size — content-driven on 'auto' axes. Pure pull:
+   * reads the same signals the flow reads, so a sibling bound to it
+   * (e.g. panelBg height = () => panel.computedSize().h) tracks every input.
+   * The measurer defaults to the scene-injected one (estimating pre-scene).
+   */
+  computedSize(measurer?: TextMeasurer): {
     w: number;
     h: number;
   };
@@ -43,4 +57,4 @@ declare class Layout extends Group {
 /** Load Yoga (wasm) and register it as the active LayoutEngine. Idempotent. */
 declare function loadYogaLayoutEngine(): Promise<LayoutEngine>;
 //#endregion
-export { Layout, type LayoutBox, type LayoutChildSpec, type LayoutContainerSpec, type LayoutEngine, LayoutEngineMissingError, LayoutProps, getLayoutEngine, loadYogaLayoutEngine, setLayoutEngine };
+export { Layout, type LayoutBox, type LayoutChildSpec, type LayoutContainerSpec, type LayoutEngine, LayoutEngineMissingError, LayoutProps, type LayoutResult, getLayoutEngine, loadYogaLayoutEngine, setLayoutEngine };

package/dist/layout.js

@@ -1,4 +1,4 @@
-import { i as setLayoutEngine, n as getLayoutEngine, o as Group, r as requireLayoutEngine, t as LayoutEngineMissingError } from "./layoutEngine.js";
+import { i as setLayoutEngine, m as estimatingMeasurer, n as getLayoutEngine, o as Group, r as requireLayoutEngine, t as LayoutEngineMissingError } from "./layoutEngine.js";
 import { signal } from "@glissade/core";
 //#region src/layout.ts
 /**
@@ -29,12 +29,21 @@ var Layout = class extends Group {
 	direction;
 	justify;
 	align;
+	/** Content-sized axes ('auto'): the size signal is ignored, Yoga computes it. */
+	autoWidth;
+	autoHeight;
 	#memoKey = "";
-	#memoBoxes = [];
+	#memoResult = {
+		width: 0,
+		height: 0,
+		boxes: []
+	};
 	constructor(props = {}) {
 		super(props);
-		this.width = initProp(signal(0), props.width);
-		this.height = initProp(signal(0), props.height);
+		this.autoWidth = props.width === "auto";
+		this.autoHeight = props.height === "auto";
+		this.width = initProp(signal(0), this.autoWidth ? void 0 : props.width);
+		this.height = initProp(signal(0), this.autoHeight ? void 0 : props.height);
 		this.gap = initProp(signal(0), props.gap);
 		this.padding = initProp(signal(0), props.padding);
 		this.direction = props.direction ?? "row";
@@ -45,16 +54,27 @@ var Layout = class extends Group {
 		this.registerTarget("gap", this.gap);
 		this.registerTarget("padding", this.padding);
 	}
-	intrinsicSize() {
-		return {
+	intrinsicSize(measurer) {
+		if (!this.autoWidth && !this.autoHeight) return {
 			w: this.width(),
 			h: this.height()
 		};
+		return this.#compute(measurer).size;
 	}
-	draw(out, ctx) {
+	/**
+	* The resolved container size — content-driven on 'auto' axes. Pure pull:
+	* reads the same signals the flow reads, so a sibling bound to it
+	* (e.g. panelBg height = () => panel.computedSize().h) tracks every input.
+	* The measurer defaults to the scene-injected one (estimating pre-scene).
+	*/
+	computedSize(measurer) {
+		const m = measurer ?? this.measurerSource?.() ?? estimatingMeasurer;
+		return this.#compute(m).size;
+	}
+	#compute(measurer) {
 		const container = {
-			width: this.width(),
-			height: this.height(),
+			width: this.autoWidth ? "auto" : this.width(),
+			height: this.autoHeight ? "auto" : this.height(),
 			direction: this.direction,
 			gap: this.gap(),
 			padding: this.padding(),
@@ -64,7 +84,7 @@ var Layout = class extends Group {
 		const flowable = [];
 		const absolute = [];
 		this.children.forEach((child, index) => {
-			const size = child.intrinsicSize(ctx.measurer);
+			const size = child.intrinsicSize(measurer);
 			if (size) flowable.push({
 				node: child,
 				spec: {
@@ -77,13 +97,26 @@ var Layout = class extends Group {
 		});
 		const key = JSON.stringify([container, flowable.map((f) => f.spec)]);
 		if (key !== this.#memoKey) {
-			this.#memoBoxes = requireLayoutEngine().compute(container, flowable.map((f) => f.spec));
+			this.#memoResult = requireLayoutEngine().compute(container, flowable.map((f) => f.spec));
 			this.#memoKey = key;
 		}
-		const boxes = this.#memoBoxes;
+		const size = {
+			w: this.autoWidth ? this.#memoResult.width : container.width,
+			h: this.autoHeight ? this.#memoResult.height : container.height
+		};
+		return {
+			result: this.#memoResult,
+			size,
+			flowable,
+			absolute
+		};
+	}
+	draw(out, ctx) {
+		const { result, size, flowable, absolute } = this.#compute(ctx.measurer);
+		const boxes = result.boxes;
 		const order = [...flowable].sort((a, b) => a.node.zIndex() - b.node.zIndex() || a.index - b.index);
-		const ox = -container.width / 2;
-		const oy = -container.height / 2;
+		const ox = -size.w / 2;
+		const oy = -size.h / 2;
 		for (const child of absolute) child.emit(out, ctx);
 		for (const entry of order) {
 			const box = boxes[flowable.indexOf(entry)];
@@ -130,8 +163,8 @@ async function loadYogaLayoutEngine() {
 	const engine = { compute(container, children) {
 		const root = yoga.Node.create();
 		try {
-			root.setWidth(container.width);
-			root.setHeight(container.height);
+			if (container.width !== "auto") root.setWidth(container.width);
+			if (container.height !== "auto") root.setHeight(container.height);
 			root.setFlexDirection(container.direction === "row" ? FlexDirection.Row : FlexDirection.Column);
 			root.setGap(Gutter.All, container.gap);
 			root.setPadding(Edge.All, container.padding);
@@ -145,18 +178,22 @@ async function loadYogaLayoutEngine() {
 				if (children[i].margin !== void 0) child.setMargin(Edge.All, children[i].margin);
 				root.insertChild(child, i);
 			}
-			root.calculateLayout(container.width, container.height, Direction.LTR);
-			const boxes = [];
+			root.calculateLayout(container.width === "auto" ? void 0 : container.width, container.height === "auto" ? void 0 : container.height, Direction.LTR);
+			const result = {
+				width: root.getComputedWidth(),
+				height: root.getComputedHeight(),
+				boxes: []
+			};
 			for (let i = 0; i < children.length; i++) {
 				const child = root.getChild(i);
-				boxes.push({
+				result.boxes.push({
 					x: child.getComputedLeft(),
 					y: child.getComputedTop(),
 					width: child.getComputedWidth(),
 					height: child.getComputedHeight()
 				});
 			}
-			return boxes;
+			return result;
 		} finally {
 			root.freeRecursive();
 		}

package/dist/layoutEngine.d.ts

@@ -1,4 +1,4 @@
-import { BindableSignal, ReadonlySignal, Vec2, Vec2Signal } from "@glissade/core";
+import { BindableSignal, PathValue, ReadonlySignal, Vec2, Vec2Signal } from "@glissade/core";
 
 //#region src/matrix.d.ts
 
@@ -52,11 +52,43 @@ interface FontSpec {
   weight?: number;
   style?: 'normal' | 'italic';
 }
-/** Enumerated at M2 (§3.4); reserved in the IR now. */
-interface FilterSpec {
-  kind: string;
-  [k: string]: unknown;
+/**
+ * Group filters (§3.4): a CLOSED union — validated data, never a CSS
+ * passthrough string — limited to effects both rasterizers implement
+ * faithfully. Cross-backend parity is perceptual (SSIM), not byte-exact:
+ * filters are where rasterizers diverge most. Per-backend output stays
+ * deterministic on the pinned toolchain (golden-tested on Skia).
+ */
+type FilterSpec = {
+  kind: 'blur'; /** Gaussian stdDeviation, px; ≥ 0. */
+  radius: number;
+} | {
+  kind: 'drop-shadow';
+  dx: number;
+  dy: number; /** ≥ 0 */
+  blur: number;
+  color: string;
+} | {
+  kind: 'brightness'; /** 1 = identity; ≥ 0. */
+  amount: number;
+} | {
+  kind: 'contrast'; /** 1 = identity; ≥ 0. */
+  amount: number;
+} | {
+  kind: 'saturate'; /** 1 = identity; ≥ 0. */
+  amount: number;
+};
+declare class FilterValidationError extends Error {
+  constructor(message: string);
 }
+/** Document-layer validation: reject unknown kinds and out-of-range params loudly. */
+declare function validateFilters(filters: readonly FilterSpec[]): void;
+/**
+ * Compile the validated union to the canvas 2D `ctx.filter` syntax — both
+ * backends speak it (browser canvas and @napi-rs/canvas/Skia). This is the
+ * ONLY place the CSS-like syntax appears; documents never carry it.
+ */
+declare function filtersToCanvasFilter(filters: readonly FilterSpec[]): string;
 interface Rect$1 {
   x: number;
   y: number;
@@ -169,6 +201,8 @@ interface NodeProps {
   opacity?: PropInit<number>;
   blend?: PropInit<BlendMode>;
   zIndex?: PropInit<number>;
+  /** Group filters (§3.4): the subtree composites as a unit through them. */
+  filters?: PropInit<FilterSpec[]>;
 }
 interface BindablePropTarget {
   bindSource(fn: () => unknown): void;
@@ -203,6 +237,12 @@ declare abstract class Node {
   interactiveChildren: boolean;
   /** v2 §C.3: explicit hit-shape override in node-local coordinates. */
   hitArea: HitArea | undefined;
+  /**
+   * Injected by createScene: the scene's CURRENT TextMeasurer (§3.2), so
+   * derived-size bindings (e.g. a background tracking Layout.computedSize)
+   * measure with the same rasterizer the flow uses.
+   */
+  measurerSource: (() => TextMeasurer) | null;
   readonly localMatrix: ReadonlySignal<Mat2x3>;
   readonly worldMatrix: ReadonlySignal<Mat2x3>;
   /** Track-target paths → bindable signals; subclasses register their own props. */
@@ -229,7 +269,7 @@ declare abstract class Node {
     x: number;
     y: number;
   };
-  /** §3.5 predicate: composite-as-a-unit when opacity/blend demand it. */
+  /** §3.5 predicate: composite-as-a-unit when opacity/blend/filters demand it. */
   protected requiresGroup(): boolean;
   emit(out: DisplayListBuilder, ctx: EvalContext): void;
 }
@@ -283,6 +323,36 @@ declare class Circle extends Shape {
   };
   protected pathSegs(): PathSeg[];
 }
+interface PathProps extends ShapeProps {
+  /** The geometry (§2.2 'path' value): bezier contours in vertex form, animatable via a track on '<id>/d'. */
+  data?: PropInit<PathValue>;
+}
+/**
+ * Arbitrary bezier geometry — the Lottie-import landing spot and the target
+ * of native path morphs. Coordinates are node-local (the node origin is
+ * wherever the author put 0,0); flow placement uses the control-point bounds.
+ */
+declare class Path extends Shape {
+  readonly data: BindableSignal<PathValue>;
+  constructor(props?: PathProps);
+  /** Control-point bounding box (conservative: contains the true curve). */
+  bounds(): {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+  };
+  intrinsicSize(): {
+    w: number;
+    h: number;
+  };
+  /** Geometry is node-local, not center-anchored: offset to the box's actual top-left. */
+  flowOffset(): {
+    x: number;
+    y: number;
+  };
+  protected pathSegs(): PathSeg[];
+}
 interface ImageProps extends NodeProps {
   /** Asset id from the Timeline manifest (§2.3). */
   assetId: string;
@@ -394,17 +464,25 @@ interface LayoutChildSpec {
   margin?: number;
 }
 interface LayoutContainerSpec {
-  width: number;
-  height: number;
+  /** 'auto': size the axis from content (Yoga computes it). */
+  width: number | 'auto';
+  height: number | 'auto';
   direction: 'row' | 'column';
   gap: number;
   padding: number;
   justify: 'start' | 'center' | 'end' | 'space-between' | 'space-around';
   align: 'start' | 'center' | 'end' | 'stretch';
 }
+interface LayoutResult {
+  /** Resolved container size — equals the spec on fixed axes, content-driven on 'auto'. */
+  width: number;
+  height: number;
+  /** Child boxes (top-left relative to the container's top-left). */
+  boxes: LayoutBox[];
+}
 interface LayoutEngine {
-  /** Pure: child boxes (top-left relative to the container's top-left). */
-  compute(container: LayoutContainerSpec, children: LayoutChildSpec[]): LayoutBox[];
+  /** Pure: resolved container size + child boxes. */
+  compute(container: LayoutContainerSpec, children: LayoutChildSpec[]): LayoutResult;
 }
 declare class LayoutEngineMissingError extends Error {
   constructor();
@@ -413,4 +491,4 @@ declare function setLayoutEngine(e: LayoutEngine): void;
 declare function getLayoutEngine(): LayoutEngine | null;
 declare function requireLayoutEngine(): LayoutEngine;
 //#endregion
-export { BlendMode as A, ResourceId as B, NodeProps as C, breakLines as D, TextMetricsLite as E, FontSpec as F, applyToPoint as G, createDisplayListBuilder as H, Paint as I, matEquals as J, fromTRS as K, PathSeg as L, DisplayListBuilder as M, DrawCommand as N, estimatingMeasurer as O, FilterSpec as P, Rect$1 as R, Node as S, TextMeasurer as T, IDENTITY as U, StrokeStyle as V, Mat2x3 as W, multiply as Y, Video as _, LayoutEngineMissingError as a, EvalContext as b, setLayoutEngine as c, ImageNode as d, ImageProps as f, TextProps as g, Text as h, LayoutEngine as i, DisplayList as j, quantize as k, Circle as l, ShapeProps as m, LayoutChildSpec as n, getLayoutEngine as o, Rect as p, invert as q, LayoutContainerSpec as r, requireLayoutEngine as s, LayoutBox as t, Group as u, VideoProps as v, PropInit as w, HitArea as x, BindablePropTarget as y, Resource as z };
+export { invert as $, breakLines as A, Paint as B, EvalContext as C, PropInit as D, NodeProps as E, DisplayListBuilder as F, StrokeStyle as G, Rect$1 as H, DrawCommand as I, validateFilters as J, createDisplayListBuilder as K, FilterSpec as L, quantize as M, BlendMode as N, TextMeasurer as O, DisplayList as P, fromTRS as Q, FilterValidationError as R, BindablePropTarget as S, Node as T, Resource as U, PathSeg as V, ResourceId as W, Mat2x3 as X, IDENTITY as Y, applyToPoint as Z, ShapeProps as _, LayoutEngineMissingError as a, Video as b, requireLayoutEngine as c, Group as d, matEquals 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, LayoutResult as o, ImageProps as p, filtersToCanvasFilter as q, LayoutContainerSpec as r, getLayoutEngine as s, LayoutBox as t, multiply as tt, Circle as u, Text as v, HitArea as w, VideoProps as x, TextProps as y, FontSpec as z };

package/dist/layoutEngine.js

@@ -62,12 +62,57 @@ function matEquals(a, b) {
 }
 //#endregion
 //#region src/displayList.ts
+var FilterValidationError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "FilterValidationError";
+	}
+};
+const FILTER_KINDS = new Set([
+	"blur",
+	"drop-shadow",
+	"brightness",
+	"contrast",
+	"saturate"
+]);
+/** Document-layer validation: reject unknown kinds and out-of-range params loudly. */
+function validateFilters(filters) {
+	for (const f of filters) {
+		if (!FILTER_KINDS.has(f.kind)) throw new FilterValidationError(`unknown filter kind '${String(f.kind)}' (have: ${[...FILTER_KINDS].join(", ")})`);
+		if (f.kind === "blur" && !(Number.isFinite(f.radius) && f.radius >= 0)) throw new FilterValidationError(`blur radius must be ≥ 0, got ${String(f.radius)}`);
+		if (f.kind === "drop-shadow") {
+			if (![
+				f.dx,
+				f.dy,
+				f.blur
+			].every(Number.isFinite) || f.blur < 0) throw new FilterValidationError("drop-shadow needs finite dx/dy and blur ≥ 0");
+			if (typeof f.color !== "string" || f.color.length === 0) throw new FilterValidationError("drop-shadow needs a color string");
+		}
+		if ((f.kind === "brightness" || f.kind === "contrast" || f.kind === "saturate") && !(Number.isFinite(f.amount) && f.amount >= 0)) throw new FilterValidationError(`${f.kind} amount must be ≥ 0, got ${String(f.amount)}`);
+	}
+}
+/**
+* Compile the validated union to the canvas 2D `ctx.filter` syntax — both
+* backends speak it (browser canvas and @napi-rs/canvas/Skia). This is the
+* ONLY place the CSS-like syntax appears; documents never carry it.
+*/
+function filtersToCanvasFilter(filters) {
+	if (filters.length === 0) return "none";
+	return filters.map((f) => {
+		switch (f.kind) {
+			case "blur": return `blur(${f.radius}px)`;
+			case "drop-shadow": return `drop-shadow(${f.dx}px ${f.dy}px ${f.blur}px ${f.color})`;
+			default: return `${f.kind}(${f.amount})`;
+		}
+	}).join(" ");
+}
 function createDisplayListBuilder(size) {
 	const commands = [];
 	const resources = [];
 	const interned = /* @__PURE__ */ new Map();
 	return {
 		push: (cmd) => {
+			if (cmd.op === "pushGroup" && cmd.filters.length > 0) validateFilters(cmd.filters);
 			commands.push(cmd);
 		},
 		resource: (res) => {
@@ -173,6 +218,12 @@ var Node = class {
 	interactiveChildren = true;
 	/** v2 §C.3: explicit hit-shape override in node-local coordinates. */
 	hitArea;
+	/**
+	* Injected by createScene: the scene's CURRENT TextMeasurer (§3.2), so
+	* derived-size bindings (e.g. a background tracking Layout.computedSize)
+	* measure with the same rasterizer the flow uses.
+	*/
+	measurerSource = null;
 	localMatrix;
 	worldMatrix;
 	/** Track-target paths → bindable signals; subclasses register their own props. */
@@ -185,7 +236,7 @@ var Node = class {
 		this.opacity = initScalar(signal(1), props.opacity);
 		this.blend = initScalar(signal("source-over"), props.blend);
 		this.zIndex = initScalar(signal(0), props.zIndex);
-		this.filters = initScalar(signal([]), void 0);
+		this.filters = initScalar(signal([]), props.filters);
 		this.localMatrix = computed(() => fromTRS(this.position(), this.rotation(), this.scale()), { equals: matEquals });
 		this.worldMatrix = computed(() => this.parent ? multiply(this.parent.worldMatrix(), this.localMatrix()) : this.localMatrix(), { equals: matEquals });
 		this.registerTarget("position", this.position);
@@ -227,9 +278,9 @@ var Node = class {
 			y: -size.h / 2
 		};
 	}
-	/** §3.5 predicate: composite-as-a-unit when opacity/blend demand it. */
+	/** §3.5 predicate: composite-as-a-unit when opacity/blend/filters demand it. */
 	requiresGroup() {
-		return this.opacity() < 1 || this.blend() !== "source-over";
+		return this.opacity() < 1 || this.blend() !== "source-over" || this.filters().length > 0;
 	}
 	emit(out, ctx) {
 		const opacity = this.opacity();
@@ -473,6 +524,102 @@ var Circle = class extends Shape {
 		], ["Z"]];
 	}
 };
+/**
+* Arbitrary bezier geometry — the Lottie-import landing spot and the target
+* of native path morphs. Coordinates are node-local (the node origin is
+* wherever the author put 0,0); flow placement uses the control-point bounds.
+*/
+var Path = class extends Shape {
+	data;
+	constructor(props = {}) {
+		super(props);
+		this.data = initProp(signal([]), props.data);
+		this.registerTarget("d", this.data);
+	}
+	/** Control-point bounding box (conservative: contains the true curve). */
+	bounds() {
+		let minX = Infinity;
+		let minY = Infinity;
+		let maxX = -Infinity;
+		let maxY = -Infinity;
+		for (const c of this.data()) for (let i = 0; i < c.v.length; i++) {
+			const vx = c.v[i][0];
+			const vy = c.v[i][1];
+			const candidates = [
+				[vx, vy],
+				[vx + c.in[i][0], vy + c.in[i][1]],
+				[vx + c.out[i][0], vy + c.out[i][1]]
+			];
+			for (const p of candidates) {
+				if (p[0] < minX) minX = p[0];
+				if (p[1] < minY) minY = p[1];
+				if (p[0] > maxX) maxX = p[0];
+				if (p[1] > maxY) maxY = p[1];
+			}
+		}
+		if (minX > maxX) return {
+			minX: 0,
+			minY: 0,
+			maxX: 0,
+			maxY: 0
+		};
+		return {
+			minX,
+			minY,
+			maxX,
+			maxY
+		};
+	}
+	intrinsicSize() {
+		const b = this.bounds();
+		return {
+			w: b.maxX - b.minX,
+			h: b.maxY - b.minY
+		};
+	}
+	/** Geometry is node-local, not center-anchored: offset to the box's actual top-left. */
+	flowOffset() {
+		const b = this.bounds();
+		return {
+			x: b.minX,
+			y: b.minY
+		};
+	}
+	pathSegs() {
+		const segs = [];
+		for (const c of this.data()) {
+			const n = c.v.length;
+			if (n === 0) continue;
+			segs.push([
+				"M",
+				c.v[0][0],
+				c.v[0][1]
+			]);
+			for (let i = 0; i < n - 1; i++) segs.push([
+				"C",
+				c.v[i][0] + c.out[i][0],
+				c.v[i][1] + c.out[i][1],
+				c.v[i + 1][0] + c.in[i + 1][0],
+				c.v[i + 1][1] + c.in[i + 1][1],
+				c.v[i + 1][0],
+				c.v[i + 1][1]
+			]);
+			if (c.closed && n > 1) {
+				segs.push([
+					"C",
+					c.v[n - 1][0] + c.out[n - 1][0],
+					c.v[n - 1][1] + c.out[n - 1][1],
+					c.v[0][0] + c.in[0][0],
+					c.v[0][1] + c.in[0][1],
+					c.v[0][0],
+					c.v[0][1]
+				]);
+				segs.push(["Z"]);
+			}
+		}
+		return segs;
+	}
+};
 var ImageNode = class extends Node {
 	assetId;
 	width;
@@ -676,4 +823,4 @@ function requireLayoutEngine() {
 	return engine;
 }
 //#endregion
-export { applyToPoint as _, Circle as a, matEquals as b, Rect as c, Node as d, breakLines as f, IDENTITY as g, createDisplayListBuilder as h, setLayoutEngine as i, Text as l, quantize as m, getLayoutEngine as n, Group as o, estimatingMeasurer as p, requireLayoutEngine as r, ImageNode as s, LayoutEngineMissingError as t, Video as u, fromTRS as v, multiply as x, invert as y };
+export { invert as C, fromTRS as S, multiply as T, createDisplayListBuilder as _, Circle as a, IDENTITY 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, matEquals as w, applyToPoint as x, validateFilters as y };

package/package.json

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