@osmo.inc/cli 0.1.15

package/runtime/packages/scene/src/evaluate.ts

@@ -0,0 +1,919 @@
+import { readMask, maskSourceIndex } from "./mask.mjs";
+import { clipFields, clipTiming, isClipPrimitive } from "./clip.mjs";
+import { readGroupLabel, readGroupPlayback, readSceneTracks, trackPlayback } from "./metadata.mjs";
+import { isKnobRef, isKnobSet, resolveKnob, evaluateKnobs, type KnobScope, type KnobDescription } from "./knobs.js";
+import { evaluateEffects, type EvaluatedEffect } from "./effects.js";
+import {
+	Scene, Model, Surface,
+	Camera,
+	Group,
+	Rect, Path,
+	Text,
+	Image,
+	Video,
+	Audio,
+	Shader,
+	type UniformValue,
+	Fragment,
+	type Child,
+	type Color,
+	type Element,
+	type FrameContext,
+	type Vec2,
+	type TextPath,
+	type Vec3,
+} from "./elements.js";
+import { isMotion, sampleMotion } from "./motion.js";
+
+export interface Transform {
+	position: Vec2;
+	z: number;
+	rotation: number;
+	scale: Vec2;
+	origin: Vec2;
+	opacity: number;
+}
+interface BaseNode {
+	track?: number;
+	effects?: EvaluatedEffect[];
+	transform: Transform;
+	key?: string | number;
+}
+export interface CompositionNode extends BaseNode {
+    type: "composition";
+    width: number;
+    height: number;
+    scene: EvaluatedScene;
+}
+export interface GroupNode extends BaseNode {
+    mask?: { index: number; mode: "alpha" | "vector" | "luminance"; invert: boolean };
+	controls?: KnobDescription;
+	depth?: number;
+	sideFill?: Color;
+	type: "group";
+	children: SceneNode[];
+	width?: number | "auto" | "fill";
+	height?: number | "auto" | "fill";
+	layout?: "free" | "row" | "column";
+	gap?: number;
+	padding?: readonly number[];
+	align?: string;
+	justify?: string;
+	fill?: Color;
+	stroke?: { color: Color; width: number };
+	rounding?: number;
+	shape?: "box" | "ellipse";
+	clip?: boolean;
+	/** True only for an authored `clip`: effects are bounded to the shape as well. */
+	clipEffects?: boolean;
+}
+export interface RectNode extends BaseNode {
+	type: "rect";
+	width: number;
+	height: number;
+	fill: Color;
+	radius: number;
+}
+export interface PathNode extends BaseNode {
+  width?: number;
+  height?: number;
+  viewBox?: readonly [number, number, number, number];
+  fit?: "contain" | "fill";
+  type: "path";
+  d: string;
+  fill: Color;
+  fillRule: "nonzero" | "evenodd";
+  stroke?: { color: Color; width: number; cap: "butt" | "round" | "square"; join: "miter" | "round" | "bevel"; miterLimit: number; trimStart: number; trimEnd: number };
+}
+export interface TextNode extends BaseNode {
+  height?: number;
+  verticalAlign?: "top" | "center" | "bottom";
+  alignBounds?: "lineBox" | "glyphs";
+	path?: TextPath;
+	type: "text";
+	text: string;
+	font: string;
+	fontSource?: string;
+	fontSize: number;
+	fontWeight?: number;
+	color: Color;
+	width?: number;
+	align: "left" | "center" | "right";
+	lineHeight: number;
+	letterSpacing: number;
+}
+export interface MediaNode extends BaseNode {
+	type: "image" | "video" | "audio";
+	src: string;
+	sourceFile?: string;
+	width?: number;
+	height?: number;
+	fit?: "cover" | "contain" | "fill";
+	rounding?: number;
+	start?: number;
+	duration?: number;
+	trimIn?: number;
+	playbackRate?: number;
+	volume?: number;
+}
+export interface ShaderNode extends BaseNode {
+	type: "shader";
+	src: string;
+	backdrop: boolean | "replace";
+	sourceFile?: string;
+	width: number;
+	height: number;
+	rounding: number;
+	uniforms: Record<string, UniformValue>;
+}
+export interface ModelNode extends BaseNode {
+ type: "model"; src: string; sourceFile?: string; height: number;
+ rotation3d: Vec3; animations: Record<string, number>; children: SurfaceNode[];
+}
+export interface SurfaceNode extends BaseNode {
+ type: "surface"; key?: string | number; nodes?: (string | number)[];
+ material?: string | number; primitive?: number; slot: "baseColor";
+ width?: number; height?: number; shading?: "lit" | "unlit";
+ color?: Color; metalness?: number; roughness?: number;
+ effects?: EvaluatedEffect[]; children: SceneNode[];
+}
+export type SceneNode = CompositionNode | GroupNode | RectNode | PathNode | TextNode | MediaNode | ShaderNode | ModelNode | SurfaceNode;
+export interface EvaluatedCamera {
+	position: Vec2;
+	z: number;
+	target: Vec3;
+	fov: number;
+}
+export interface EvaluatedScene extends FrameContext {
+	effects?: EvaluatedEffect[];
+	camera?: EvaluatedCamera;
+	type: "scene";
+	totalFrames: number;
+	background: Color;
+	children: SceneNode[];
+}
+
+function number(value: unknown, label: string, minimum = -Infinity): number {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < minimum) {
+		throw new Error(`${label}: expected a finite number >= ${minimum}`);
+	}
+	return value;
+}
+function positive(value: unknown, label: string): number {
+	const n = number(value, label, 0);
+	if (n === 0) throw new Error(`${label}: must be greater than zero`);
+	return n;
+}
+function pair(value: unknown, label: string): Vec2 {
+	if (!Array.isArray(value) || value.length !== 2)
+		throw new Error(`${label}: expected [x, y]`);
+	return [number(value[0], label), number(value[1], label)];
+}
+function color(value: unknown, label: string): Color {
+	if (
+		typeof value !== "string" ||
+		(value !== "transparent" && !/^#(?:[\da-f]{6}|[\da-f]{8})$/i.test(value))
+	) {
+		throw new Error(`${label}: expected #RRGGBB, #RRGGBBAA or transparent`);
+	}
+	return value as Color;
+}
+function transform(props: Readonly<Record<string, unknown>>): Transform {
+	const scale = props.scale ?? 1;
+	const opacity = number(props.opacity ?? 1, "opacity", 0);
+	if (opacity > 1) throw new Error("opacity: must be <= 1");
+	return {
+		position: pair(props.position ?? [0, 0], "position"),
+		z: number(props.z ?? 0, "z"),
+		rotation: number(props.rotation ?? 0, "rotation"),
+		scale:
+			typeof scale === "number"
+				? [number(scale, "scale"), scale]
+				: pair(scale, "scale"),
+		origin: pair(props.origin ?? [0, 0], "origin"),
+		opacity,
+	};
+}
+function resolve(value: unknown, time: number, scope: KnobScope = []): unknown {
+	if (isKnobRef(value)) return resolveKnob(value, scope);
+	if (isKnobSet(value)) return value;
+	if (isMotion(value)) return sampleMotion(value, time);
+	if (Array.isArray(value)) return value.map((v) => resolve(v, time, scope));
+	if (
+		value &&
+		typeof value === "object" &&
+		!isElement(value) &&
+		Object.getPrototypeOf(value) === Object.prototype
+	)
+		return Object.fromEntries(
+			Object.entries(value).map(([k, v]) => [k, resolve(v, time, scope)]),
+		);
+	return value;
+}
+function isElement(value: unknown): value is Element {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"type" in value &&
+		"props" in value
+	);
+}
+
+/** Evaluate at an exact frame. Produces host-independent data; does not draw pixels. */
+export function evaluateFrame(root: Element, frame: number): EvaluatedScene {
+    return evaluateScene(root, frame);
+}
+function evaluateScene(root: Element, frame: number, clock?: Partial<ClockContext>, depth = 0): EvaluatedScene {
+    if (depth > 32) throw new Error("Scene nesting exceeds 32 levels");
+	if (!isElement(root) || (root.type !== Scene && root.type !== "scene")) {
+		throw new Error(
+			"The root must be <Scene>; put custom components inside it",
+		);
+	}
+	const p = root.props;
+	checkProps(
+		p,
+		"Scene",
+		["width", "height", "duration", "fps", "background", "children", "effects", "tracks"],
+		false,
+	);
+	const tracks = readSceneTracks(p.tracks);
+	const width = positive(p.width, "Scene.width");
+	const height = positive(p.height, "Scene.height");
+    if (![width,height].every(v=>Number.isInteger(v)&&v<=8192)) throw new Error("Scene dimensions must be whole pixels, at most 8192 per side");
+	const duration = positive(p.duration, "Scene.duration");
+	const fps = positive(p.fps ?? 30, "Scene.fps");
+	const totalFrames = Math.ceil(duration * fps);
+	if (!Number.isSafeInteger(totalFrames) || totalFrames < 1)
+		throw new Error("Scene frame count is out of range");
+	if (!clock && (!Number.isSafeInteger(frame) || frame < 0 || frame >= totalFrames)) {
+		throw new Error(`Frame must be an integer in [0, ${totalFrames - 1}]`);
+	}
+	const context: ClockContext = Object.freeze({
+		frame,
+		time: frame / fps,
+		fps,
+		width,
+		height,
+		duration,
+        ...clock,
+	});
+	let camera: EvaluatedCamera | undefined;
+	const children: unknown[] = [];
+	function collect(child: unknown, depth = 0): void {
+		if (depth > 256) throw new Error("Scene nesting exceeds 256 levels");
+		if (Array.isArray(child)) {
+			for (const item of child) collect(item, depth + 1);
+		} else if (
+			isElement(child) && (child.type === Camera || child.type === "camera")
+		) {
+			if (camera) throw new Error("Scene accepts only one Camera");
+			camera = evaluateCamera(
+				resolve(child.props, context.time) as Record<string, unknown>, context,
+			);
+		} else {
+			children.push(child);
+		}
+	}
+	collect(p.children);
+ const evaluatedChildren = isolateGroups(visit(children, context, depth));
+ function checkPlacement(nodes: SceneNode[], parent: string) {
+  for (const n of nodes) {
+   if (n.track !== undefined && parent !== "scene") throw new Error(`${n.type}.track is only supported on root timeline clips`);
+   if (n.type === "model" && parent !== "scene") throw new Error("Model must be a direct child of Scene");
+   if (n.type === "surface" && parent !== "model") throw new Error("Surface must be a direct child of Model");
+   if ("children" in n) checkPlacement(n.children, n.type);
+  }
+ }
+ checkPlacement(evaluatedChildren, "scene");
+ // Keep topology and local clocks stable while applying lane playback controls.
+ for (const node of evaluatedChildren) {
+  const state = trackPlayback(tracks, node.track);
+  if (!state.visible) node.transform.opacity = 0;
+  if (!state.audible) silence(node);
+ }
+	return {
+		type: "scene",
+		...(camera ? { camera } : {}),
+		...context,
+		totalFrames,
+		background: color(p.background ?? "transparent", "Scene.background"),
+		...(p.effects === undefined ? {} : { effects: evaluateEffects(p.effects, context.time, root.sourceFile) }),
+		children: evaluatedChildren,
+	};
+}
+
+function evaluateCamera(
+	props: Record<string, unknown>,
+	context: FrameContext,
+): EvaluatedCamera {
+	checkProps(props, "Camera", ["position", "z", "target", "fov"], false);
+	const position = pair(
+		props.position ?? [context.width / 2, context.height / 2], "Camera.position",
+	);
+	const z = number(props.z ?? 2000, "Camera.z");
+	const t = props.target ?? [context.width / 2, context.height / 2, 0];
+	if (!Array.isArray(t) || t.length !== 3)
+		throw new Error("Camera.target: expected [x, y, z]");
+	const target: Vec3 = [
+		number(t[0], "Camera.target"), number(t[1], "Camera.target"), number(t[2], "Camera.target"),
+	];
+	if (Math.hypot(position[0] - target[0], position[1] - target[1], z - target[2]) < 0.0001) {
+		throw new Error("Camera.position and z must differ from target");
+	}
+	const fov = positive(
+		props.fov ?? 2 * Math.atan(context.height / 4000) * 180 / Math.PI, "Camera.fov",
+	);
+	if (fov >= 180) throw new Error("Camera.fov must be less than 180 degrees");
+	return { position, z, target, fov };
+}
+
+interface ClockContext extends FrameContext { offset?: number; windowStart?: number; windowEnd?: number; }
+
+// Evaluation-only state: do not serialize editor controls into render snapshots.
+const soloGroups = new WeakSet<SceneNode>();
+function silence(node: SceneNode) {
+    if (node.type === 'audio' || node.type === 'video') node.volume = 0;
+    if ('children' in node) node.children.forEach(silence);
+    if (node.type === 'composition') node.scene.children.forEach(silence);
+}
+function isolateGroups(nodes: SceneNode[]): SceneNode[] {
+    if (nodes.some(node => soloGroups.has(node)))
+        for (const node of nodes) if (!soloGroups.has(node)) {
+            node.transform.opacity = 0;
+            silence(node);
+        }
+    return nodes;
+}
+
+// Flatten only structural fragments: indices continue to match the editor's
+// evaluated children and selection paths, including the mask source itself.
+function maskChildren(child: unknown): Element[] {
+    if (child == null || typeof child === "boolean") return [];
+    if (Array.isArray(child)) return child.flatMap(maskChildren);
+    if (!isElement(child)) throw new Error("Group children must be elements");
+    if (child.type === Fragment || child.type === "fragment") return maskChildren(child.props.children);
+    return [child];
+}
+function vectorMask(child: Element): Element {
+    const p = {...child.props, opacity: 1, effects: undefined};
+    const type = child.type;
+    if (type === Group || type === "group") {
+        const children = maskChildren(child.props.children);
+        Object.assign(p, {children:children.map(vectorMask), depth:0, sideFill:undefined,
+            fill:child.props.fill !== undefined || !children.length ? "#ffffff" : "transparent", stroke:undefined});
+    } else if (type === Path || type === "path" || type === Rect || type === "rect") {
+        Object.assign(p, {fill:"#ffffff", stroke:undefined});
+    } else if (type === Text || type === "text") Object.assign(p, {color:"#ffffff"});
+    else throw new Error("Vector masks require Group, Path, Rect, or Text outlines; use alpha or luminance for media, shaders, and scenes");
+    return {...child, props:p};
+}
+
+function visit(
+	child: unknown,
+	context: ClockContext,
+	depth: number,
+    scope: KnobScope = [],
+): SceneNode[] {
+	if (depth > 256)
+		throw new Error(
+			"Scene nesting exceeds 256 levels; check for recursive components",
+		);
+	if (child === null || child === undefined || typeof child === "boolean")
+		return [];
+	if (Array.isArray(child))
+		return child.flatMap((c) => visit(c, context, depth + 1, scope));
+	if (!isElement(child))
+		throw new Error(
+			"Scene children must be components; put text inside <Text>",
+		);
+	const builtins = new Map<unknown, string>([
+		[Group, "group"], [Model, "model"], [Surface, "surface"],
+		[Rect, "rect"], [Path, "path"],
+		[Text, "text"],
+		[Image, "image"],
+		[Video, "video"],
+		[Audio, "audio"],
+		[Shader, "shader"],
+		[Fragment, "fragment"],
+		[Scene, "scene"],
+		[Camera, "camera"],
+	]);
+	const type = builtins.get(child.type) ?? child.type;
+    if (type === 'composition') {
+        const source = child.props.scene as Element;
+        const timing = clipTiming(child.props, context.duration, context.fps, 'Scene instance');
+        const localTime = Math.max(0,Math.min(timing.duration-1e-9,context.time-timing.start));
+        const p = Object.fromEntries(Object.entries(child.props).filter(([k])=>k!=='scene').map(([k,v])=>[k,k==='effects'?v:resolve(v,localTime,scope)]));
+        const trim = number(p.trimIn ?? 0, 'Scene instance.trimIn', 0);
+        const sourceDuration = positive(source.props.duration, 'Scene.duration');
+        if (trim >= sourceDuration) throw new Error('Scene instance.trimIn must be before the source end');
+        const offset = (context.offset ?? 0) + timing.start - trim;
+        const start = Math.max(context.windowStart ?? 0, offset + trim);
+        const end = Math.min(context.windowEnd ?? Infinity, offset + Math.min(sourceDuration, trim + timing.duration));
+        const time = Math.max(0, Math.min(sourceDuration - 1e-9, context.time - timing.start + trim));
+        // An instance can resize its viewport without scaling its contents or
+        // mutating the shared source. Layout and default camera framing resolve
+        // against these dimensions through the ordinary scene evaluator.
+        const dimension = (name: 'width' | 'height') => {
+            if (p[name] === undefined) return source.props[name];
+            const value = positive(p[name], `Scene instance.${name}`);
+            if (value < 1 || value > 8192) throw new Error('Scene instance dimensions must be 1..8192 pixels per side');
+            return Math.round(value);
+        };
+        const viewport = {...source,props:{...source.props,width:dimension('width'),height:dimension('height')}};
+        const scene = evaluateScene(viewport, 0, {time, frame:time*context.fps, fps:context.fps, offset, windowStart:start, windowEnd:end}, depth+1);
+        const active = context.time >= timing.start && context.time < timing.start + Math.min(timing.duration, sourceDuration-trim);
+        readGroupLabel(p.label); readGroupPlayback(p);
+        const node: CompositionNode = {type:'composition',width:scene.width,height:scene.height,scene,
+            ...(timing.track === undefined ? {} : {track:timing.track}),
+            transform:transform({...p,opacity:active && !p.hidden ? p.opacity : 0}),
+            ...(p.effects === undefined ? {} : {effects:evaluateEffects(p.effects,localTime,child.sourceFile)})};
+        if (p.solo) soloGroups.add(node);
+        return [node];
+    }
+    const parentContext = context;
+    const timing = typeof type === "string" && isClipPrimitive(type)
+        ? clipTiming(child.props, context.duration, context.fps, type) : null;
+    const localClock = timing && (child.props.start !== undefined || child.props.duration !== undefined || child.props.track !== undefined);
+    let active = true;
+    if (localClock) {
+        const { start, duration } = timing;
+        active = context.time >= start && context.time < start + duration;
+        const offset = (context.offset ?? 0) + start;
+        const time = Math.max(0, Math.min(duration - 1e-9, context.time - start));
+        context = { ...context, time, frame: Math.floor(time * context.fps), duration, offset,
+            windowStart: Math.max(context.windowStart ?? 0, offset),
+            windowEnd: Math.min(context.windowEnd ?? Infinity, offset + duration) };
+    }
+    let controls: KnobDescription | undefined;
+    if (type === "group") {
+        readGroupLabel(child.props.label);
+        readGroupPlayback(child.props);
+        if (child.props.knobs !== undefined) {
+            if (!isKnobSet(child.props.knobs)) throw new Error("Group.knobs must be a defineKnobs declaration");
+            controls = evaluateKnobs(child.props.knobs, child.props.values, context.time, scope);
+            scope = [...scope, { set: child.props.knobs, description: controls }];
+        } else if (child.props.values !== undefined) throw new Error("Group.values requires Group.knobs");
+    }
+    const props = Object.fromEntries(Object.entries(child.props).map(([name, value]) => [name,
+        (name === "children" && !isKnobRef(value)) || name === "effects" || (type === "group" && (name === "knobs" || name === "values"))
+            ? value : resolve(value, context.time, scope),
+    ]));
+	if (typeof type === "function") {
+		const result: Child = type(Object.freeze(props), context);
+		const nodes = visit(result, context, depth + 1, scope);
+		// A keyed custom component owns a fragment scope, preserving its identity
+		// independently of repeated child keys inside other component instances.
+		if (child.key !== undefined)
+			return [
+				{
+					type: "group",
+					key: child.key,
+					transform: transform({}),
+					children: nodes,
+				},
+			];
+		return nodes;
+	}
+	if (type === "fragment") {
+		const children = visit(props.children, context, depth + 1, scope);
+		return child.key === undefined
+			? children
+			: [{ type: "group", key: child.key, transform: transform({}), children }];
+	}
+	if (type === "scene") throw new Error("Scenes cannot be nested");
+	if (type === "camera") throw new Error("Camera must be a direct child of Scene");
+ if (type === "model") {
+  checkProps(props, "Model", ["src","position","z","height","rotation","scale","opacity","animations","children"], false);
+  if (typeof props.src !== "string" || !/\.glb$/i.test(props.src) || /^[a-z]+:/i.test(props.src)) throw new Error("Model.src: expected a local .glb path");
+  const rot=props.rotation ?? [0,0,0];
+  if (!Array.isArray(rot) || rot.length !== 3) throw new Error("Model.rotation: expected [x,y,z] degrees");
+  const animations=props.animations ?? {};
+  if (!animations || typeof animations !== "object" || Array.isArray(animations)) throw new Error("Model.animations: expected a map of clip names to progress");
+  const tracks: Record<string,number> = {};
+  for (const [name,v] of Object.entries(animations)) {
+   if (!name.trim()) throw new Error("Model.animations: empty clip name");
+   const progress=number(v,`Model.animations.${name}`,0);
+   if(progress>1)throw new Error("Animation progress must be between 0 and 1");
+   Object.defineProperty(tracks,name,{value:progress,enumerable:true});
+  }
+  const children=visit(props.children,context,depth+1,scope);
+  if(children.some(n=>n.type!=="surface"))throw new Error("Model accepts Surface children only");
+  return [{type:"model",src:props.src,...(child.sourceFile?{sourceFile:child.sourceFile}:{}),
+   ...(child.key===undefined?{}:{key:child.key}),
+   ...(timing?.track === undefined ? {} : {track: timing.track}),
+   transform:transform({...props,opacity:active ? props.opacity : 0,position:props.position??[context.width/2,context.height/2],rotation:0,scale:positive(props.scale??1,"Model.scale")}),
+   height:positive(props.height,"Model.height"),rotation3d:rot.map(v=>number(v,"Model.rotation")) as unknown as Vec3,
+   animations:tracks,children:children as SurfaceNode[]}];
+ }
+ if (type === "surface") {
+  checkProps(props,"Surface",["node","nodes","material","primitive","slot","width","height","shading","color","metalness","roughness","effects","children"],false);
+  const selector=(v:unknown):string|number=>{
+   if(typeof v==="string"&&v.trim())return v;
+   if(typeof v==="number"&&Number.isSafeInteger(v)&&v>=0)return v;
+   throw new Error("Surface selector must be a nonempty name or nonnegative index");
+  };
+  if(props.node!==undefined&&props.nodes!==undefined)throw new Error("Use Surface.node or Surface.nodes, not both");
+  const targets=props.nodes??(props.node===undefined?undefined:[props.node]);
+  if(targets!==undefined&&(!Array.isArray(targets)||!targets.length))throw new Error("Surface.nodes must be a nonempty list");
+  if(targets===undefined&&props.material===undefined)throw new Error("Surface needs a node or material selector");
+  const width=props.width===undefined?undefined:positive(props.width,"Surface.width");
+  const height=props.height===undefined?undefined:positive(props.height,"Surface.height");
+  const children=visit(props.children,width === undefined || height === undefined ? context : Object.freeze({...context,width,height}),depth+1,scope);
+  if((width===undefined)!==(height===undefined)||children.length&&width===undefined)throw new Error("Surface content requires width and height");
+  if(width!==undefined&&(width>4096||height!>4096))throw new Error("Surface canvas limit is 4096 per side");
+  const unit=(v:unknown,label:string)=>{const n=number(v,label,0);if(n>1)throw new Error(`${label}: must be <= 1`);return n;};
+  if(props.primitive!==undefined&&(!Number.isSafeInteger(props.primitive)||number(props.primitive,"Surface.primitive",0)<0))throw new Error("Surface.primitive must be an index");
+  return [{type:"surface",transform:transform({}),...(child.key===undefined?{}:{key:child.key}),
+   ...(targets===undefined?{}:{nodes:(targets as unknown[]).map(selector)}),
+   ...(props.material===undefined?{}:{material:selector(props.material)}),
+   ...(props.primitive===undefined?{}:{primitive:props.primitive as number}),
+   slot:choice(props.slot??"baseColor",["baseColor"],"Surface.slot"),
+   ...(width===undefined?{}:{width,height}),
+   ...(props.shading===undefined?{}:{shading:choice(props.shading,["lit","unlit"],"Surface.shading")}),
+   ...(props.color===undefined?{}:{color:color(props.color,"Surface.color")}),
+   ...(props.metalness===undefined?{}:{metalness:unit(props.metalness,"Surface.metalness")}),
+   ...(props.roughness===undefined?{}:{roughness:unit(props.roughness,"Surface.roughness")}),
+   ...(props.effects===undefined?{}:{effects:evaluateEffects(props.effects,context.time,child.sourceFile)}),children}];
+ }
+	const base: BaseNode = {
+		...(props.effects === undefined ? {} : { effects: evaluateEffects(props.effects, context.time, child.sourceFile, v => isKnobRef(v) ? resolveKnob(v, scope) : v) }),
+		transform: transform(active ? props : {...props, opacity: 0}),
+		...(timing?.track === undefined ? {} : {track: timing.track}),
+		...(child.key === undefined ? {} : { key: child.key }),
+	};
+	if (type === "group") {
+		checkProps(props, "Group", [
+            "knobs", "values", "start", "duration", "track", "label", "hidden", "solo",
+			"depth",
+			"sideFill",
+			"children",
+			"width",
+			"height",
+			"layout",
+			"gap",
+			"padding",
+			"align",
+			"justify",
+			"fill",
+			"stroke",
+			"rounding",
+			"shape",
+			"clip", "mask",
+		]);
+		const layout = choice(
+			props.layout ?? "free",
+			["free", "row", "column"],
+			"Group.layout",
+		);
+		const size = (v: unknown, label: string) =>
+			v === undefined
+				? undefined
+                : v === "fill" ? "fill" as const
+				: v === "auto"
+					? layout === "free"
+						? fail(`${label}: auto requires row/column layout`)
+						: ("auto" as const)
+					: number(v, label, 0);
+		const width = size(props.width, "Group.width"),
+			height = size(props.height, "Group.height");
+		const shape = choice(
+			props.shape ?? "box",
+			["box", "ellipse"],
+			"Group.shape",
+		);
+		const padding = props.padding ?? 0;
+		const pads =
+			typeof padding === "number"
+				? [padding, padding, padding, padding]
+				: padding;
+		if (!Array.isArray(pads) || pads.length !== 4)
+			throw new Error(
+				"Group.padding: expected a number or [top, right, bottom, left]",
+			);
+		const stroke = props.stroke;
+		if (
+			stroke !== undefined &&
+			(!stroke || typeof stroke !== "object" || Array.isArray(stroke))
+		)
+			throw new Error("Group.stroke: expected { color, width }");
+		const st = stroke as Record<string, unknown> | undefined;
+		if (st && Object.keys(st).some((k) => k !== "color" && k !== "width"))
+			throw new Error("Group.stroke: unsupported property");
+		if (props.clip !== undefined && typeof props.clip !== "boolean")
+			throw new Error("Group.clip: expected boolean");
+		const mask = readMask(props.mask);
+        const sources = mask ? maskChildren(props.children) : null;
+        const sourceIndex = mask ? maskSourceIndex(sources!, mask) : -1;
+        const children: SceneNode[] = [];
+        let maskIndex = -1;
+        if (sources) for (const [i, source] of sources.entries()) {
+            const isMask = i === sourceIndex;
+            const evaluated = visit(isMask && mask!.mode === "vector" ? vectorMask(source) : source, context, depth + 1, scope);
+            if (isMask) {
+                if (evaluated.length !== 1 || evaluated[0].type === "audio") throw new Error("Group.mask: source must be a visual layer");
+                maskIndex = children.length;
+                // A matte controls visibility only; video/audio descendants are silent.
+                silence(evaluated[0]);
+            }
+            children.push(...evaluated);
+        }
+        const node: GroupNode = {
+				type: "group",
+				...base,
+                ...(controls ? { controls } : {}),
+				...(width === undefined ? {} : { width }),
+				...(height === undefined ? {} : { height }),
+				layout,
+				shape,
+				gap: number(props.gap ?? 0, "Group.gap", 0),
+				padding: pads.map((v) => number(v, "Group.padding", 0)),
+				align: choice(
+					props.align ?? "start",
+					["start", "center", "end", "stretch"],
+					"Group.align",
+				),
+				justify: choice(
+					props.justify ?? "start",
+					["start", "center", "end", "spaceBetween", "spaceAround"],
+					"Group.justify",
+				),
+				fill: color(props.fill ?? "transparent", "Group.fill"),
+				depth: number(props.depth ?? 0, "Group.depth", 0),
+				sideFill: color(props.sideFill ?? props.fill ?? "transparent", "Group.sideFill"),
+				...(st
+					? {
+							stroke: {
+								color: color(st.color, "Group.stroke.color"),
+								width: number(st.width, "Group.stroke.width", 0),
+							},
+						}
+					: {}),
+				rounding: number(props.rounding ?? 0, "Group.rounding", 0),
+				clip: props.clip !== false,
+				...(props.clip === true ? { clipEffects: true } : {}),
+				children: isolateGroups(sources ? children : visit(props.children, context, depth + 1, scope)),
+                ...(mask ? {mask:{index:maskIndex,mode:mask.mode,invert:mask.invert}} : {}),
+			};
+        if (props.hidden) node.transform.opacity = 0;
+        if (props.solo) soloGroups.add(node);
+        return [node];
+	}
+	if (type === "shader") {
+		checkProps(props, "Shader", ["src", "backdrop", "width", "height", "rounding", "uniforms"]);
+		if (props.backdrop !== undefined && typeof props.backdrop !== "boolean" && props.backdrop !== "replace")
+			throw new Error('Shader.backdrop: expected a boolean or "replace"');
+		if (typeof props.src !== "string" || !props.src.trim() || /^[a-z]+:/i.test(props.src) || !/\.wgsl$/i.test(props.src))
+			throw new Error("Shader.src: expected a local .wgsl file path");
+		const inputs = props.uniforms ?? {};
+		if (!inputs || typeof inputs !== "object" || Array.isArray(inputs))
+			throw new Error("Shader.uniforms: expected named numbers or vectors");
+		if (Object.keys(inputs).length > 32) throw new Error("Shader.uniforms: maximum 32 fields");
+		const uniforms: Record<string, UniformValue> = {};
+		for (const [name, value] of Object.entries(inputs)) {
+			if (!/^[a-zA-Z][a-zA-Z0-9_]*$/.test(name)) throw new Error(`Shader.uniforms: invalid name "${name}"`);
+			const values = Array.isArray(value) ? value : [value];
+			if (Array.isArray(value) && (value.length < 2 || value.length > 4))
+				throw new Error(`Shader.uniforms.${name}: expected a number or vector of 2–4 numbers`);
+			for (const v of values) {
+				number(v, `Shader.uniforms.${name}`);
+				if (!Number.isFinite(Math.fround(v))) throw new Error(`Shader.uniforms.${name}: exceeds f32 range`);
+			}
+			Object.defineProperty(uniforms, name, { value, enumerable: true });
+		}
+		return [{ type: "shader", ...base, src: props.src, backdrop: props.backdrop ?? false,
+			...(child.sourceFile ? { sourceFile: child.sourceFile } : {}),
+			width: positive(props.width, "Shader.width"), height: positive(props.height, "Shader.height"),
+			rounding: number(props.rounding ?? 0, "Shader.rounding", 0), uniforms }];
+	}
+	if (type === "image" || type === "video" || type === "audio") {
+		const visual = type !== "audio",
+			timed = type !== "image";
+		checkProps(
+			props,
+			type,
+			[
+				"src",
+				...(visual ? ["width", "height", "fit", "rounding"] : []),
+				...(timed
+					? ["start", "duration", "trimIn", "playbackRate", "volume"]
+					: []),
+			],
+			visual,
+		);
+		if (
+			typeof props.src !== "string" ||
+			!props.src.trim() ||
+			/^[a-z]+:/i.test(props.src)
+		)
+			throw new Error(`${type}.src: expected a local file path`);
+		const node: MediaNode = {
+			type,
+			...base,
+			src: props.src,
+			...(child.sourceFile ? { sourceFile: child.sourceFile } : {}),
+		};
+		if (visual)
+			Object.assign(node, {
+				width: positive(props.width, `${type}.width`),
+				height: positive(props.height, `${type}.height`),
+				fit: choice(
+					props.fit ?? "cover",
+					["cover", "contain", "fill"],
+					`${type}.fit`,
+				),
+				rounding: number(props.rounding ?? 0, `${type}.rounding`, 0),
+			});
+		if (timed) {
+            const localStart = number(props.start ?? 0, `${type}.start`, 0);
+            const authoredStart = (parentContext.offset ?? 0) + localStart;
+            const start = Math.max(authoredStart, parentContext.windowStart ?? 0);
+            const authoredDuration = positive(props.duration ?? Math.max(parentContext.duration - localStart, 1 / context.fps), `${type}.duration`);
+            const end = Math.min(authoredStart + authoredDuration, parentContext.windowEnd ?? Infinity);
+			const volume = number(props.volume ?? 1, `${type}.volume`, 0);
+			if (volume > 1) throw new Error(`${type}.volume: must be <= 1`);
+			const rate = positive(props.playbackRate ?? 1, `${type}.playbackRate`);
+			if (rate < 0.25 || rate > 4)
+				throw new Error(`${type}.playbackRate: expected 0.25 through 4`);
+			Object.assign(node, {
+				start,
+                duration: Math.max(1 / context.fps, end - start),
+                trimIn: number(props.trimIn ?? 0, `${type}.trimIn`, 0) + (start - authoredStart) * rate,
+				playbackRate: rate,
+				volume: end > start ? volume : 0,
+			});
+		}
+		return [node];
+	}
+	if (type === "path") {
+    checkProps(props, "Path", ["width", "height", "viewBox", "fit", "d", "fill", "fillRule", "stroke"]);
+    if (typeof props.d !== "string" || !props.d.trim() || props.d.length > 65536)
+      throw new Error("Path.d: expected nonempty SVG path data, at most 64 KiB");
+    let stroke: PathNode["stroke"];
+    if (props.stroke !== undefined) {
+      const st = props.stroke as Record<string, unknown>;
+      if (!st || typeof st !== "object" || Array.isArray(st) || Object.keys(st).some(k => !["color", "width", "cap", "join", "miterLimit", "trimStart", "trimEnd"].includes(k)))
+        throw new Error("Path.stroke: expected color, width and optional cap/join/miterLimit/trimStart/trimEnd");
+      const width = number(st.width, "Path.stroke.width", 0), miterLimit = number(st.miterLimit ?? 4, "Path.stroke.miterLimit", 1);
+      if (width > 2048 || miterLimit > 100) throw new Error("Path.stroke: width must be <= 2048 and miterLimit <= 100");
+      const trimStart = number(st.trimStart ?? 0, "Path.stroke.trimStart", 0), trimEnd = number(st.trimEnd ?? 1, "Path.stroke.trimEnd", 0);
+      if (trimStart > 1 || trimEnd > 1) throw new Error("Path.stroke: trimStart and trimEnd are fractions from 0 to 1");
+      stroke = { color: color(st.color, "Path.stroke.color"), width, miterLimit, trimStart, trimEnd,
+        cap: choice(st.cap ?? "butt", ["butt", "round", "square"], "Path.stroke.cap"),
+        join: choice(st.join ?? "miter", ["miter", "round", "bevel"], "Path.stroke.join") };
+    }
+    const sizing: Pick<PathNode, "width" | "height" | "viewBox" | "fit"> = {};
+    for (const key of ["width", "height"] as const) if (props[key] !== undefined) sizing[key] = positive(props[key], `Path.${key}`);
+    if (props.viewBox !== undefined) {
+      const box = props.viewBox;
+      if (!Array.isArray(box) || box.length !== 4) throw new Error("Path.viewBox: expected [minX, minY, width, height]");
+      sizing.viewBox = [number(box[0], "Path.viewBox.x"), number(box[1], "Path.viewBox.y"), positive(box[2], "Path.viewBox.width"), positive(box[3], "Path.viewBox.height")];
+    }
+    if (props.fit !== undefined) {
+      sizing.fit = choice(props.fit, ["contain", "fill"], "Path.fit");
+      if (sizing.width === undefined && sizing.height === undefined && sizing.viewBox === undefined) throw new Error("Path.fit requires width, height or viewBox");
+    }
+    return [{ type: "path", ...base, ...sizing, d: props.d, fill: color(props.fill ?? "#ffffff", "Path.fill"),
+      fillRule: choice(props.fillRule ?? "nonzero", ["nonzero", "evenodd"], "Path.fillRule"), ...(stroke ? { stroke } : {}) }];
+  }
+	if (type === "rect") {
+		checkProps(props, "Rect", [
+			"width",
+			"height",
+			"fill",
+			"radius",
+			"children",
+		]);
+		if (props.children !== undefined)
+			throw new Error("Rect does not accept children");
+		const width = number(props.width, "Rect.width", 0);
+		const height = number(props.height, "Rect.height", 0);
+		return [
+			{
+				type: "rect",
+				...base,
+				width,
+				height,
+				fill: color(props.fill ?? "#ffffff", "Rect.fill"),
+				radius: Math.min(
+					number(props.radius ?? 0, "Rect.radius", 0),
+					width / 2,
+					height / 2,
+				),
+			},
+		];
+	}
+	if (type === "text") {
+		checkProps(props, "Text", ["height", "verticalAlign", "alignBounds",
+			"children",
+			"font",
+			"fontSize",
+			"fontWeight",
+			"color",
+			"width",
+			"align",
+			"lineHeight",
+			"letterSpacing",
+			"path",
+		]);
+		let path: TextPath | undefined;
+		if (props.path !== undefined) {
+			if (!props.path || typeof props.path !== "object" || Array.isArray(props.path))
+				throw new Error("Text.path: expected a path object");
+			for (const key of ["width", "height", "verticalAlign", "alignBounds", "align", "lineHeight"])
+				if (props[key] !== undefined) throw new Error(`Text.${key} cannot be used with Text.path`);
+			const p = props.path as Record<string, unknown>;
+			const progress = number(p.progress ?? 0, "Text.path.progress");
+			if (p.shape === "ellipse") {
+				checkProps(p, "Text.path", ["shape", "radius", "progress"], false);
+				const radius = pair(p.radius, "Text.path.radius");
+				path = { shape: "ellipse", radius: [positive(radius[0], "Text.path.radius[0]"), positive(radius[1], "Text.path.radius[1]")], progress };
+			} else if (p.shape === "svg") {
+				checkProps(p, "Text.path", ["shape", "d", "progress"], false);
+				if (typeof p.d !== "string" || !p.d.trim() || p.d.length > 65536)
+					throw new Error("Text.path.d: expected nonempty SVG path data (up to 65536 characters)");
+				path = { shape: "svg", d: p.d, progress };
+			} else throw new Error('Text.path.shape: expected "ellipse" or "svg"');
+			if (/[\r\n\u2028\u2029]/u.test(String(props.children)))
+				throw new Error("Text.path requires single-line text");
+		}
+		if (
+			typeof props.children !== "string" &&
+			typeof props.children !== "number"
+		)
+			throw new Error("Text requires string or number children");
+		if (typeof props.children === "number")
+			number(props.children, "Text.children");
+		const font = props.font ?? "Inter";
+		if (typeof font !== "string" || font.length === 0)
+			throw new Error("Text.font must be a nonempty string");
+        if (props.verticalAlign !== undefined && props.height === undefined) throw new Error("Text.verticalAlign requires height");
+        const box = {
+          ...(props.height === undefined ? {} : {height: positive(props.height, "Text.height")}),
+          ...(props.verticalAlign === undefined ? {} : {verticalAlign: choice(props.verticalAlign, ["top", "center", "bottom"], "Text.verticalAlign")}),
+          ...(props.alignBounds === undefined ? {} : {alignBounds: choice(props.alignBounds, ["lineBox", "glyphs"], "Text.alignBounds")}),
+        };
+		const align = props.align ?? "left";
+		if (align !== "left" && align !== "center" && align !== "right")
+			throw new Error("Text.align must be left, center or right");
+		return [
+			{
+				type: "text",
+				...base, ...box,
+				...(path ? { path } : {}),
+				text: String(props.children),
+				font,
+				...(child.sourceFile ? { fontSource: child.sourceFile } : {}),
+				...(props.fontWeight === undefined
+					? {}
+					: {
+							fontWeight: choice(
+								props.fontWeight,
+								[400, 500, 600, 700],
+								"Text.fontWeight",
+							),
+						}),
+				fontSize: positive(props.fontSize ?? 48, "Text.fontSize"),
+				color: color(props.color ?? "#ffffff", "Text.color"),
+				...(props.width === undefined
+					? {}
+					: { width: positive(props.width, "Text.width") }),
+				align,
+				lineHeight: positive(props.lineHeight ?? 1.2, "Text.lineHeight"),
+				letterSpacing: number(props.letterSpacing ?? 0, "Text.letterSpacing"),
+			},
+		];
+	}
+	throw new Error(`Unsupported primitive: ${String(child.type)}`);
+}
+
+function fail(message: string): never {
+	throw new Error(message);
+}
+function choice<const T extends string | number>(
+	value: unknown,
+	options: readonly T[],
+	label: string,
+): T {
+	if (!options.includes(value as T))
+		throw new Error(`${label}: expected ${options.join(", ")}`);
+	return value as T;
+}
+function checkProps(
+	props: Record<string, unknown>,
+	label: string,
+	allowed: string[],
+	visual = true,
+) {
+	const names = new Set([
+        "id",
+        ...(isClipPrimitive(label) ? clipFields : []),
+			...allowed,
+		...(visual ? ["position", "z", "rotation", "scale", "origin", "opacity", "effects"] : []),
+	]);
+    if (props.id !== undefined && (typeof props.id !== "string" || !props.id.trim())) throw new Error(`${label}.id: expected a nonempty string`);
+	for (const name of Object.keys(props))
+		if (!names.has(name))
+			throw new Error(`${label}: unsupported prop "${name}"`);
+}