@glissade/scene 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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";
+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,24 @@ 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 {
@@ -60,6 +78,9 @@ interface Ctx2DLike<TPath, TDrawable> {
   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;
@@ -85,15 +106,29 @@ interface Raster2DHost<TCanvas extends CanvasLike, TPath extends PathLike, TDraw
   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;
-  constructor(host: Raster2DHost<TCanvas, TPath, TDrawable>);
+  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). */
@@ -101,6 +136,7 @@ declare class Raster2D<TCanvas extends CanvasLike, TPath extends PathLike, TDraw
   dispose(): void;
   private resolveDrawable;
   private path;
+  private pathBounds;
   private buildPath;
   private acquire;
   private release;
@@ -157,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, 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 };
+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 { 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";
+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,45 @@ 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
@@ -26,14 +65,81 @@ var ColdAssetError = class extends Error {
 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();
-	constructor(host) {
+	warnedShaders = false;
+	constructor(host, shaderCaps = "warn") {
 		this.host = host;
+		this.shaderCaps = shaderCaps;
 	}
 	/** Register a decoded still (kind 'image' assets). */
 	setImageAsset(assetId, image) {
@@ -74,6 +180,12 @@ var Raster2D = class {
 		}
 		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]) {
@@ -122,17 +234,25 @@ var Raster2D = class {
 			ctx: base,
 			canvas: null,
 			opacity: 1,
-			blend: "source-over"
+			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":
@@ -142,6 +262,8 @@ var Raster2D = class {
 				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": {
@@ -153,6 +275,11 @@ var Raster2D = class {
 				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": {
@@ -162,6 +289,15 @@ var Raster2D = class {
 				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": {
@@ -173,6 +309,7 @@ var Raster2D = class {
 				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": {
@@ -187,7 +324,11 @@ var Raster2D = class {
 					canvas: layerCanvas,
 					opacity: cmd.opacity,
 					blend: cmd.blend,
-					filter: filtersToCanvasFilter(cmd.filters)
+					filter: filtersToCanvasFilter(cmd.filters),
+					filters: cmd.filters,
+					...cmd.shader !== void 0 ? { shader: cmd.shader } : {},
+					bounds: null,
+					unbounded: false
 				});
 				break;
 			}
@@ -195,12 +336,60 @@ var Raster2D = class {
 				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 (layer.filter !== void 0 && layer.filter !== "none") parent.filter = layer.filter;
+				if (hasFilter) parent.filter = layer.filter;
 				parent.globalCompositeOperation = layer.blend;
-				parent.drawImage(layer.canvas, 0, 0);
+				parent.drawImage(drawable, 0, 0);
 				parent.restore();
 				this.release(layer.canvas);
 				break;
@@ -295,4 +484,4 @@ function evaluate(scene, doc, t) {
 	});
 }
 //#endregion
-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 };
+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/layoutEngine.d.ts

@@ -89,12 +89,31 @@ declare function validateFilters(filters: readonly FilterSpec[]): void;
  * 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';
 } | {
@@ -134,6 +153,7 @@ type DrawCommand = {
   opacity: number;
   blend: BlendMode;
   filters: FilterSpec[];
+  shader?: ShaderRef;
   cacheKey?: string;
 } | {
   op: 'popGroup';
@@ -271,6 +291,8 @@ declare abstract class Node {
   };
   /** §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
@@ -491,4 +513,4 @@ declare function setLayoutEngine(e: LayoutEngine): void;
 declare function getLayoutEngine(): LayoutEngine | null;
 declare function requireLayoutEngine(): LayoutEngine;
 //#endregion
-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 };
+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

@@ -106,6 +106,22 @@ function filtersToCanvasFilter(filters) {
 		}
 	}).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 = [];
@@ -282,12 +298,15 @@ var Node = class {
 	requiresGroup() {
 		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",
@@ -297,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" });
@@ -823,4 +843,4 @@ function requireLayoutEngine() {
 	return engine;
 }
 //#endregion
-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 };
+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.3.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.3.0"
+    "@glissade/core": "0.4.0"
   },
   "repository": {
     "type": "git",