@glissade/scene 0.2.0 → 0.4.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,5 +1,5 @@
-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 { BoundTimeline, CompiledTimeline, Playhead, Timeline } from "@glissade/core";
+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 { BindableSignal, BoundTimeline, CompiledTimeline, Playhead, Timeline } from "@glissade/core";
 
 //#region src/assets.d.ts
 
@@ -37,6 +37,113 @@ declare class ColdAssetError extends Error {
   constructor(assetId: string, detail: string, mediaT?: number);
 }
 //#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`. */
+  wgsl: string;
+  /** Initial scalar uniforms; each becomes an animatable signal + track target 'u.<name>'. */
+  uniforms?: Record<string, number>;
+}
+declare class ShaderEffect extends Group {
+  readonly wgsl: string;
+  readonly uniformSignals: ReadonlyMap<string, BindableSignal<number>>;
+  constructor(props: ShaderEffectProps);
+  /** The live uniform signal (throws on unknown names — typos fail loudly). */
+  uniform(name: string): BindableSignal<number>;
+  protected groupShader(): ShaderRef;
+}
+//#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;
+  measureText(text: string): {
+    width: number;
+  };
+  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;
+  /**
+   * §3.7 shader pass: run the WGSL effect over the group layer and return a
+   * drawable replacement, or null when unavailable. Absent/null → the layer
+   * composites unfiltered per caps.shaders (warn by default, error opt-in).
+   * Only browser hosts wire this (via @glissade/effects-webgpu); headless
+   * backends stay GPU-free by construction.
+   */
+  applyShader?(layer: TCanvas, shader: ShaderRef, w: number, h: number): TDrawable | null;
+}
+type ShaderCaps = 'warn' | 'error';
+declare function fontString(font: FontSpec): string;
+declare class Raster2D<TCanvas extends CanvasLike, TPath extends PathLike, TDrawable> {
+  private readonly host;
+  /** caps.shaders (§3.7): what happens when a shader can't run here. */
+  private readonly shaderCaps;
+  private readonly pool;
+  private readonly pathCache;
+  private readonly pathBoundsCache;
+  private readonly images;
+  private readonly videos;
+  private warnedShaders;
+  constructor(host: Raster2DHost<TCanvas, TPath, TDrawable>, /** caps.shaders (§3.7): what happens when a shader can't run here. */
+  shaderCaps?: ShaderCaps);
+  /** 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 pathBounds;
+  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 +193,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 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 };

package/dist/index.js

@@ -1,5 +1,5 @@
-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 { bindTimeline, compileTimeline, createPlayhead, evaluateAt } from "@glissade/core";
+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 { bindTimeline, compileTimeline, createPlayhead, emitDevWarning, evaluateAt, signal } from "@glissade/core";
 //#region src/assets.ts
 var ColdAssetError = class extends Error {
 	assetId;
@@ -15,6 +15,390 @@ var ColdAssetError = class extends Error {
 	}
 };
 //#endregion
+//#region src/shaderEffect.ts
+/**
+* ShaderEffect (§3.7): a group whose rasterized subtree runs through a WGSL
+* pass. THIS FILE IS PURE DATA — the GPU runner lives in the browser-only
+* @glissade/effects-webgpu package; headless backends degrade per
+* caps.shaders (passthrough + warning by default). Uniforms are per-name
+* number signals registered as '<id>/u.<name>' track targets, so shader
+* params animate exactly like any other property.
+*/
+var ShaderEffect = class extends Group {
+	wgsl;
+	uniformSignals;
+	constructor(props) {
+		super(props);
+		this.wgsl = props.wgsl;
+		const map = /* @__PURE__ */ new Map();
+		for (const [name, value] of Object.entries(props.uniforms ?? {})) {
+			const sig = signal(value);
+			map.set(name, sig);
+			this.registerTarget(`u.${name}`, sig);
+		}
+		this.uniformSignals = map;
+	}
+	/** The live uniform signal (throws on unknown names — typos fail loudly). */
+	uniform(name) {
+		const sig = this.uniformSignals.get(name);
+		if (!sig) throw new Error(`ShaderEffect has no uniform '${name}' (have: ${[...this.uniformSignals.keys()].join(", ")})`);
+		return sig;
+	}
+	groupShader() {
+		const uniforms = {};
+		for (const [name, sig] of this.uniformSignals) uniforms[name] = sig();
+		return {
+			wgsl: this.wgsl,
+			uniforms
+		};
+	}
+};
+//#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}`;
+}
+/**
+* How far a filter chain can paint beyond its input (device px). Each stage
+* feeds the next, so outsets ADD. Gaussian reach: Skia truncates at 3σ and
+* the CSS blur/shadow radii are ≥ σ, so 3× the radius over-covers either
+* convention. Color-only filters map transparent → transparent: zero outset.
+*/
+function filterOutset(filters) {
+	let total = 0;
+	for (const f of filters ?? []) if (f.kind === "blur") total += 3 * f.radius;
+	else if (f.kind === "drop-shadow") total += Math.max(Math.abs(f.dx), Math.abs(f.dy)) + 3 * f.blur;
+	return total;
+}
+function growBounds(b, x, y) {
+	if (!b) return {
+		minX: x,
+		minY: y,
+		maxX: x,
+		maxY: y
+	};
+	if (x < b.minX) b.minX = x;
+	if (y < b.minY) b.minY = y;
+	if (x > b.maxX) b.maxX = x;
+	if (y > b.maxY) b.maxY = y;
+	return b;
+}
+/** Local-space rect (already outset) → device-space box under m. */
+function accumulateRect(layer, m, x0, y0, x1, y1) {
+	for (const [x, y] of [
+		[x0, y0],
+		[x1, y0],
+		[x0, y1],
+		[x1, y1]
+	]) layer.bounds = growBounds(layer.bounds, m[0] * x + m[2] * y + m[4], m[1] * x + m[3] * y + m[5]);
+}
+/** Control-point box of a path — curves and rotated ellipses stay inside it. */
+function segsBounds(segs) {
+	let b = null;
+	const pt = (x, y) => {
+		b = growBounds(b, x, y);
+	};
+	for (const seg of segs) switch (seg[0]) {
+		case "M":
+		case "L":
+			pt(seg[1], seg[2]);
+			break;
+		case "C":
+			pt(seg[1], seg[2]);
+			pt(seg[3], seg[4]);
+			pt(seg[5], seg[6]);
+			break;
+		case "Q":
+			pt(seg[1], seg[2]);
+			pt(seg[3], seg[4]);
+			break;
+		case "E": {
+			const r = Math.max(seg[3], seg[4]);
+			pt(seg[1] - r, seg[2] - r);
+			pt(seg[1] + r, seg[2] + r);
+			break;
+		}
+	}
+	return b;
+}
+var Raster2D = class {
+	host;
+	shaderCaps;
+	pool = [];
+	pathCache = /* @__PURE__ */ new WeakMap();
+	pathBoundsCache = /* @__PURE__ */ new WeakMap();
+	images = /* @__PURE__ */ new Map();
+	videos = /* @__PURE__ */ new Map();
+	warnedShaders = false;
+	constructor(host, shaderCaps = "warn") {
+		this.host = host;
+		this.shaderCaps = shaderCaps;
+	}
+	/** 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;
+	}
+	pathBounds(resources, id) {
+		const res = resources[id];
+		if (!res || res.kind !== "path") return null;
+		if (!this.pathBoundsCache.has(res)) this.pathBoundsCache.set(res, segsBounds(res.segs));
+		return this.pathBoundsCache.get(res) ?? null;
+	}
+	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",
+			bounds: null,
+			unbounded: false
+		}];
+		const ctxOf = () => layers[layers.length - 1].ctx;
+		const top = () => layers[layers.length - 1];
+		let mat = IDENTITY;
+		const matStack = [];
+		for (const cmd of list.commands) switch (cmd.op) {
+			case "save":
+				matStack.push(mat);
+				ctxOf().save();
+				break;
+			case "restore":
+				mat = matStack.pop() ?? mat;
+				ctxOf().restore();
+				break;
+			case "transform":
+				mat = multiply(mat, cmd.m);
+				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));
+				const b = this.pathBounds(list.resources, cmd.path);
+				if (b) accumulateRect(top(), mat, b.minX, b.minY, b.maxX, b.maxY);
+				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([]);
+				const b = this.pathBounds(list.resources, cmd.path);
+				if (b) {
+					const o = cmd.stroke.width * ((cmd.stroke.join ?? "miter") === "miter" ? 5 : 1);
+					accumulateRect(top(), mat, b.minX - o, b.minY - o, b.maxX + o, b.maxY + o);
+				}
+				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);
+				try {
+					const width = ctx.measureText(cmd.text).width;
+					const align = cmd.align ?? "left";
+					const x0 = align === "center" ? cmd.x - width / 2 : align === "right" ? cmd.x - width : cmd.x;
+					const m = cmd.font.size;
+					accumulateRect(top(), mat, x0 - m, cmd.y - 1.5 * m, x0 + width + m, cmd.y + .75 * m);
+				} catch {
+					top().unbounded = true;
+				}
+				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);
+				accumulateRect(top(), mat, x, y, x + dw, y + 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),
+					filters: cmd.filters,
+					...cmd.shader !== void 0 ? { shader: cmd.shader } : {},
+					bounds: null,
+					unbounded: false
+				});
+				break;
+			}
+			case "popGroup": {
+				const layer = layers.pop();
+				if (!layer || layer.canvas === null) throw new Error("popGroup without matching pushGroup");
+				const parent = ctxOf();
+				let drawable = layer.canvas;
+				let shaderReplaced = false;
+				if (layer.shader !== void 0) {
+					const replaced = this.host.applyShader?.(layer.canvas, layer.shader, w, h) ?? null;
+					if (replaced !== null) {
+						drawable = replaced;
+						shaderReplaced = true;
+						layer.bounds = {
+							minX: 0,
+							minY: 0,
+							maxX: w,
+							maxY: h
+						};
+						layer.unbounded = false;
+					} else if (this.shaderCaps === "error") throw new Error("a ShaderEffect reached a backend without a shader runner (§3.7) — load @glissade/effects-webgpu in the browser, or accept passthrough with caps.shaders: warn");
+					else if (!this.warnedShaders) {
+						this.warnedShaders = true;
+						emitDevWarning("ShaderEffect pass skipped: no shader runner here (headless or webgpu-less browser) — subtree composites unfiltered (§3.7 caps.shaders)");
+					}
+				}
+				const hasFilter = layer.filter !== void 0 && layer.filter !== "none";
+				const outset = hasFilter ? filterOutset(layer.filters) : 0;
+				const parentLayer = top();
+				if (layer.unbounded || layer.blend !== "source-over") parentLayer.unbounded = true;
+				else if (layer.bounds) accumulateRect(parentLayer, IDENTITY, layer.bounds.minX - outset, layer.bounds.minY - outset, layer.bounds.maxX + outset, layer.bounds.maxY + outset);
+				const clippable = hasFilter && !shaderReplaced && !layer.unbounded && layer.blend === "source-over";
+				if (clippable && layer.bounds === null) {
+					this.release(layer.canvas);
+					break;
+				}
+				parent.save();
+				parent.resetTransform();
+				if (clippable && layer.bounds) {
+					const x0 = Math.max(0, Math.floor(layer.bounds.minX - outset));
+					const y0 = Math.max(0, Math.floor(layer.bounds.minY - outset));
+					const x1 = Math.min(w, Math.ceil(layer.bounds.maxX + outset));
+					const y1 = Math.min(h, Math.ceil(layer.bounds.maxY + outset));
+					if (x0 >= x1 || y0 >= y1) {
+						parent.restore();
+						this.release(layer.canvas);
+						break;
+					}
+					const clip = this.host.newPath();
+					clip.moveTo(x0, y0);
+					clip.lineTo(x1, y0);
+					clip.lineTo(x1, y1);
+					clip.lineTo(x0, y1);
+					clip.closePath();
+					parent.clip(clip, "nonzero");
+				}
+				parent.globalAlpha = layer.opacity;
+				if (hasFilter) parent.filter = layer.filter;
+				parent.globalCompositeOperation = layer.blend;
+				parent.drawImage(drawable, 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 +411,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 +425,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 +484,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, ShaderEffect, Text, Video, applyToPoint, bindScene, breakLines, createDisplayListBuilder, createScene, estimatingMeasurer, evaluate, filtersToCanvasFilter, fontString, fromTRS, getLayoutEngine, glow, 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,17 +52,68 @@ 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;
+/**
+ * Outer glow as stacked zero-offset drop-shadows — the classic recipe, fully
+ * deterministic on both backends (it is just filters). intensity stacks more
+ * layers; pair with a signal binding to follow an animated fill.
+ */
+declare function glow(color: string, radius?: number, intensity?: number): FilterSpec[];
 interface Rect$1 {
   x: number;
   y: number;
   w: number;
   h: number;
 }
+/**
+ * Shader effect pass (§3.7): runs over the group's rasterized texture.
+ * EXPLICITLY outside the determinism guarantee — GPU/driver per-pixel
+ * variance breaks distributed reproducibility; export with shaders is
+ * best-effort, single machine. Uniform VALUES are resolved at emit time
+ * (they ride on signals), so the IR stays a plain serializable snapshot.
+ */
+interface ShaderRef {
+  /** WGSL fragment module: declare `struct Uniforms` + `@fragment fn effect(@location(0) uv: vec2f) -> @location(0) vec4f`. */
+  wgsl: string;
+  /** Scalar uniforms, packed as f32 in SORTED KEY ORDER into the Uniforms struct. */
+  uniforms: Record<string, number>;
+}
 type DrawCommand = {
   op: 'save';
 } | {
@@ -102,6 +153,7 @@ type DrawCommand = {
   opacity: number;
   blend: BlendMode;
   filters: FilterSpec[];
+  shader?: ShaderRef;
   cacheKey?: string;
 } | {
   op: 'popGroup';
@@ -169,6 +221,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 +257,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,8 +289,10 @@ 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;
+  /** §3.7: a subtree-level shader pass; ShaderEffect overrides. */
+  protected groupShader(): ShaderRef | undefined;
   emit(out: DisplayListBuilder, ctx: EvalContext): void;
 }
 //#endregion
@@ -283,6 +345,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 +486,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 +513,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 { 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 };

package/dist/layoutEngine.js

@@ -62,12 +62,73 @@ 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(" ");
+}
+/**
+* Outer glow as stacked zero-offset drop-shadows — the classic recipe, fully
+* deterministic on both backends (it is just filters). intensity stacks more
+* layers; pair with a signal binding to follow an animated fill.
+*/
+function glow(color, radius = 16, intensity = 2) {
+	const layers = [];
+	for (let i = 0; i < Math.max(1, intensity); i++) layers.push({
+		kind: "drop-shadow",
+		dx: 0,
+		dy: 0,
+		blur: radius * (1 + i * 1.5),
+		color
+	});
+	return layers;
+}
 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 +234,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 +252,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,16 +294,19 @@ 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;
 	}
+	/** §3.7: a subtree-level shader pass; ShaderEffect overrides. */
+	groupShader() {}
 	emit(out, ctx) {
 		const opacity = this.opacity();
 		if (opacity <= 0) return;
 		const local = this.localMatrix();
 		const isIdentity = matEquals(local, IDENTITY);
-		const group = this.requiresGroup();
+		const shader = this.groupShader();
+		const group = this.requiresGroup() || shader !== void 0;
 		out.push({ op: "save" });
 		if (!isIdentity) out.push({
 			op: "transform",
@@ -246,7 +316,8 @@ var Node = class {
 			op: "pushGroup",
 			opacity,
 			blend: this.blend(),
-			filters: this.filters()
+			filters: this.filters(),
+			...shader !== void 0 ? { shader } : {}
 		});
 		this.draw(out, ctx);
 		if (group) out.push({ op: "popGroup" });
@@ -473,6 +544,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 +843,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 { 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 };

package/package.json

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