@osmo.inc/cli 0.1.18 → 0.1.19

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

@@ -1,919 +0,0 @@
-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}"`);
-}