framefields 2.13.1 → 2.15.0

package/dist/{program-BfiB9ttP.mjs → program-CMigyfso.mjs}

@@ -1,8 +1,9 @@
 import { Dn as sampleMediaSignal, Et as emojiPresentation, F as MediaTimeRemapInputSchema, It as getActiveMediaMetadata, St as createVirtualMedia, Xt as isSignal, _t as compositionFrameContext, dn as parseCssGradient, ht as assertNever, in as mixColors, l as Color, mt as assertFps, un as parseCssColor, y as Effect, zn as validateMediaTimeRemap } from "./dist-C8XSqfTx.mjs";
 import { t as ColorSchema } from "./dist-BSKAbyea.mjs";
-import { Dt as AdvancedTextAnimatorSchema, Hn as signalRegistry, Tt as AETextAnimatorSchema, Vt as KineticMarqueeConfigSchema, dn as TypewriterAnimatorSchema, in as TextPathOptionsSchema } from "./dist-DtPPPsZV.mjs";
+import { Cr as signalRegistry, Kn as TypewriterAnimatorSchema, Sn as KineticMarqueeConfigSchema, cn as AdvancedTextAnimatorSchema, on as AETextAnimatorSchema, zn as TextPathOptionsSchema } from "./dist-XqlFM2a8.mjs";
 import { z } from "zod";
 import { loadYoga } from "yoga-layout/load";
+import gsapModule from "gsap";
 
 //#region ../compositions/dist/program/index.mjs
 let yogaInstance = null;
@@ -391,6 +392,14 @@ function collectInlineSignals(nodes, out = {}) {
 	}
 	return out;
 }
+const PROP_ALIASES = {
+	rotationX: "rotateX",
+	rotationY: "rotateY",
+	rotationZ: "rotateZ"
+};
+function normalizeAnimatableProp(prop) {
+	return PROP_ALIASES[prop] ?? prop;
+}
 const isKeyframeTrack = (t) => !t.source || t.source.type === "keyframe";
 /**
 * Merges keyframe tracks that animate the same prop into one sorted track,
@@ -577,6 +586,15 @@ var LayerAnimation = class LayerAnimation$1 {
 	static rotateZ(fromAngle, toAngle, options = {}) {
 		return new LayerAnimation$1().fromTo("rotateZ", fromAngle, toAngle, options);
 	}
+	static rotationX(fromAngle, toAngle, options = {}) {
+		return new LayerAnimation$1().fromTo("rotateX", fromAngle, toAngle, options);
+	}
+	static rotationY(fromAngle, toAngle, options = {}) {
+		return new LayerAnimation$1().fromTo("rotateY", fromAngle, toAngle, options);
+	}
+	static rotationZ(fromAngle, toAngle, options = {}) {
+		return new LayerAnimation$1().fromTo("rotateZ", fromAngle, toAngle, options);
+	}
 	static rotation(fromAngle, toAngle, options = {}) {
 		return new LayerAnimation$1().fromTo("rotation", fromAngle, toAngle, options);
 	}
@@ -599,16 +617,18 @@ var LayerAnimation = class LayerAnimation$1 {
 	* - `N`: repeats N times after the initial iteration (total N + 1 iterations).
 	*/
 	repeat(count = -1, prop) {
+		const canonical = prop ? normalizeAnimatableProp(prop) : void 0;
 		this.defaultRepeat = count;
-		for (const track of this.tracks) if (!prop || track.prop === prop) track.repeat = count;
+		for (const track of this.tracks) if (!canonical || track.prop === canonical) track.repeat = count;
 		return this;
 	}
 	/**
 	* Enables or disables yoyo (alternate playback direction on each repeat iteration).
 	*/
 	yoyo(enable = true, prop) {
+		const canonical = prop ? normalizeAnimatableProp(prop) : void 0;
 		this.defaultYoyo = enable;
-		for (const track of this.tracks) if (!prop || track.prop === prop) track.yoyo = enable;
+		for (const track of this.tracks) if (!canonical || track.prop === canonical) track.yoyo = enable;
 		return this;
 	}
 	/**
@@ -623,7 +643,8 @@ var LayerAnimation = class LayerAnimation$1 {
 	/**
 	* Creates a keyframed track animating from fromValue to toValue.
 	*/
-	fromTo(prop, fromValue, toValue, options = {}) {
+	fromTo(rawProp, fromValue, toValue, options = {}) {
+		const prop = normalizeAnimatableProp(rawProp);
 		const start = options.from ?? options.start ?? options.fromFrame ?? 0;
 		const end = options.to ?? options.end ?? options.toFrame ?? (options.durationFrames !== void 0 ? start + options.durationFrames : start + 24);
 		const ease = parseEase(options.ease);
@@ -665,7 +686,8 @@ var LayerAnimation = class LayerAnimation$1 {
 	/**
 	* Appends a keyframe to an existing track for prop, or creates a new track.
 	*/
-	keyframe(prop, frame, value, ease) {
+	keyframe(rawProp, frame, value, ease) {
+		const prop = normalizeAnimatableProp(rawProp);
 		let track = this.tracks.find((t) => t.prop === prop && (!t.source || t.source.type === "keyframe"));
 		if (!track) {
 			const newTrack = {
@@ -696,7 +718,8 @@ var LayerAnimation = class LayerAnimation$1 {
 	* `.keys("scale", [[0, 0], [12, 1.1, "back.out"], [20, 1]])`.
 	* Frames are rounded to whole frames, so beat math can be passed straight in.
 	*/
-	keys(prop, keyframes, options) {
+	keys(rawProp, keyframes, options) {
+		const prop = normalizeAnimatableProp(rawProp);
 		for (const [frame, value, ease] of keyframes) this.keyframe(prop, Math.round(frame), value, ease);
 		if (options) {
 			const track = this.tracks.find((t) => t.prop === prop && (!t.source || t.source.type === "keyframe"));
@@ -815,6 +838,18 @@ var LayerAnimation = class LayerAnimation$1 {
 	rotateZ(fromAngle, toAngle, options = {}) {
 		return this.fromTo("rotateZ", fromAngle, toAngle, options);
 	}
+	/** Alias for {@link rotateX}. */
+	rotationX(fromAngle, toAngle, options = {}) {
+		return this.fromTo("rotateX", fromAngle, toAngle, options);
+	}
+	/** Alias for {@link rotateY}. */
+	rotationY(fromAngle, toAngle, options = {}) {
+		return this.fromTo("rotateY", fromAngle, toAngle, options);
+	}
+	/** Alias for {@link rotateZ}. */
+	rotationZ(fromAngle, toAngle, options = {}) {
+		return this.fromTo("rotateZ", fromAngle, toAngle, options);
+	}
 	/**
 	* Animate scale along the X axis.
 	*/
@@ -883,7 +918,8 @@ var LayerAnimation = class LayerAnimation$1 {
 	* registered with the program automatically — or the name of a signal
 	* registered with `comp.addSignal(name, signal)`.
 	*/
-	signal(prop, signalOrHandleId, options = {}) {
+	signal(rawProp, signalOrHandleId, options = {}) {
+		const prop = normalizeAnimatableProp(rawProp);
 		const { handleId, inline } = resolveSignalArg(signalOrHandleId);
 		const id = `${prop}_sig_${handleId}_${this.tracks.length}`;
 		const source = {
@@ -896,7 +932,8 @@ var LayerAnimation = class LayerAnimation$1 {
 			threshold: options.threshold ?? .15,
 			accumulateThreshold: options.threshold ?? .15,
 			debounceFrames: options.debounceFrames ?? 2,
-			channel: options.channel ?? "primary"
+			channel: options.channel ?? "primary",
+			...options.clock && { clock: options.clock }
 		};
 		if (inline) attachInlineSignal(source, inline);
 		this.tracks.push({
@@ -911,7 +948,8 @@ var LayerAnimation = class LayerAnimation$1 {
 	* Modulates color interpolation based on an active signal (object or
 	* registered name, as in {@link LayerAnimation.signal}).
 	*/
-	colorSignal(prop, signalOrHandleId, options) {
+	colorSignal(rawProp, signalOrHandleId, options) {
+		const prop = normalizeAnimatableProp(rawProp);
 		const { handleId, inline } = resolveSignalArg(signalOrHandleId);
 		const id = `${prop}_colorSig_${handleId}_${this.tracks.length}`;
 		const source = {
@@ -938,7 +976,8 @@ var LayerAnimation = class LayerAnimation$1 {
 	/**
 	* Adds organic Perlin noise wiggling to a property.
 	*/
-	wiggle(prop, options = {}) {
+	wiggle(rawProp, options = {}) {
+		const prop = normalizeAnimatableProp(rawProp);
 		const id = `${prop}_wiggle_${this.tracks.length}`;
 		const source = {
 			type: "wiggle",
@@ -958,7 +997,8 @@ var LayerAnimation = class LayerAnimation$1 {
 	/**
 	* Adds physical harmonic spring overshoot behavior to a property transition.
 	*/
-	spring(prop, options = {}) {
+	spring(rawProp, options = {}) {
+		const prop = normalizeAnimatableProp(rawProp);
 		const id = `${prop}_spring_${this.tracks.length}`;
 		const source = {
 			type: "springOvershoot",
@@ -1260,6 +1300,132 @@ var CameraAnimation = class CameraAnimation$1 extends LayerAnimation {
 		return this;
 	}
 };
+/**
+* Schemas for character animation on model nodes: layered clips, two-bone
+* IK, look-at, spring bones, and skinned crowds on instance nodes.
+*
+* Time-varying values are tracks: a constant, keyframes `[[frame, …value]]`
+* (linear, in the layer's own frames), or, in process, a function of the
+* frame or a signal (anything with `get(ctx)`: audio, physics, vision,
+* `Signal.*`). Functions and signals are not serializable; a spec sent as
+* JSON keeps constants and keys.
+*/
+const Vec3Schema$1 = z.tuple([
+	z.number(),
+	z.number(),
+	z.number()
+]);
+const isFunction = (v) => typeof v === "function";
+const isSignal$1 = (v) => typeof v === "object" && v !== null && typeof v.get === "function";
+/**
+* A number over time: constant, `[[frame, value], …]` keys, `(frame) =>
+* value`, or a signal.
+*/
+const NumberTrackSchema = z.union([
+	z.number(),
+	z.array(z.tuple([z.number(), z.number()])).min(1),
+	z.custom(isFunction),
+	z.custom(isSignal$1)
+]);
+/**
+* A point over time: `[x, y, z]` where each axis is a {@link NumberTrack}
+* (so a constant, keys, a function or a signal per axis), `[[frame, x, y,
+* z], …]` keys, or `(frame) => [x, y, z]`.
+*/
+const Vec3TrackSchema = z.union([
+	z.tuple([
+		NumberTrackSchema,
+		NumberTrackSchema,
+		NumberTrackSchema
+	]),
+	z.array(z.tuple([
+		z.number(),
+		z.number(),
+		z.number(),
+		z.number()
+	])).min(1),
+	z.custom(isFunction)
+]);
+const ClipRefSchema = z.union([z.string(), z.number().int().min(0)]);
+const ModelAnimationLayerSchema = z.object({
+	clip: ClipRefSchema,
+	weight: NumberTrackSchema.optional(),
+	speed: z.number().optional(),
+	timeOffset: z.number().optional(),
+	mask: z.array(z.string()).optional(),
+	loop: z.boolean().optional()
+}).strict();
+const TwoBoneIkSchema = z.object({
+	chain: z.tuple([
+		z.string(),
+		z.string(),
+		z.string()
+	]),
+	target: Vec3TrackSchema,
+	poleTarget: Vec3TrackSchema.optional(),
+	weight: NumberTrackSchema.optional()
+}).strict();
+const LookAtSchema = z.object({
+	joint: z.string(),
+	target: Vec3TrackSchema,
+	weight: NumberTrackSchema.optional(),
+	maxAngleDeg: z.number().min(0).max(180).optional(),
+	axis: Vec3Schema$1.optional()
+}).strict();
+/**
+* A joint posed directly, in its own local frame: Euler degrees (applied
+* Z, then Y, then X, like layers) and a translation offset in model units,
+* on top of the animated pose (`"additive"`, default) or of the joint's rest
+* pose (`"rest"`: clips no longer move it).
+*/
+const JointPoseSchema = z.object({
+	rotateX: NumberTrackSchema.optional(),
+	rotateY: NumberTrackSchema.optional(),
+	rotateZ: NumberTrackSchema.optional(),
+	x: NumberTrackSchema.optional(),
+	y: NumberTrackSchema.optional(),
+	z: NumberTrackSchema.optional(),
+	weight: NumberTrackSchema.optional(),
+	mode: z.enum(["additive", "rest"]).optional()
+}).strict();
+/**
+* Points a bone along a scene direction (the joint turns so the bone,
+* toward its first child, or its local `axis` lies along it). Retargeting a
+* performer's pose is a chain of aims, parents first.
+*/
+const AimSchema = z.object({
+	joint: z.string(),
+	direction: Vec3TrackSchema,
+	weight: NumberTrackSchema.optional(),
+	axis: Vec3Schema$1.optional()
+}).strict();
+/**
+* A joint driven by another: it turns by a share of the source joint's turn
+* from its rest, per local axis (Euler degrees, Z then Y then X). Applied
+* after look-ats, before IK, so eyelids follow eyes a `lookAt` aims.
+*/
+const JointDriverSchema = z.object({
+	joint: z.string(),
+	from: z.string(),
+	rotate: z.object({
+		x: z.number().optional(),
+		y: z.number().optional(),
+		z: z.number().optional()
+	}).strict()
+}).strict();
+const SpringBoneChainSchema = z.object({
+	joints: z.array(z.string()).min(1),
+	stiffness: z.number().min(0).optional(),
+	damping: z.number().min(0).max(1).optional(),
+	gravity: Vec3Schema$1.optional()
+}).strict();
+const CrowdSchema = z.object({
+	clips: z.array(ClipRefSchema).min(1),
+	fps: z.number().min(1).max(120).optional(),
+	seed: z.number().optional(),
+	speedRange: z.tuple([z.number().min(0), z.number().min(0)]).optional(),
+	phase: z.enum(["random", "sync"]).optional()
+}).strict();
 const SAMPLES = 128;
 const CURVE_STEPS = 16;
 const NUM_RE = /-?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?/gi;
@@ -1975,7 +2141,10 @@ const COLOR_PROPS$1 = new Set([
 	"fillColor",
 	"strokeColor",
 	"textBackgroundColor",
-	"color"
+	"color",
+	"emissive",
+	"subsurfaceColor",
+	"sheenColor"
 ]);
 function computeRepeatFrame(track, localFrame, startFrame, lastFrame) {
 	const repeat = track.repeat ?? 0;
@@ -2059,7 +2228,7 @@ function evaluateTrackAtFrame(track, frame, fps = 24, context = {}) {
 			return evaluateSpringOvershoot(source, localFrame / (fps > 0 ? fps : 24), v0, v1);
 		}
 		case "signal": {
-			const sigVal = evaluateSignal(source, frame, fps, context.signals);
+			const sigVal = evaluateSignal(source, source.clock === "layer" ? localFrame : frame, fps, context.signals);
 			if (COLOR_PROPS$1.has(track.prop)) {
 				const src = source;
 				const colorA = src.colorA ?? "#ffffff";
@@ -2120,6 +2289,12 @@ function textOf(node) {
 	const spans = node.spans ?? [];
 	return [node.text, ...spans.map((s) => s.text)].filter((t) => typeof t === "string").join("");
 }
+const DIRECT_LIGHTS = new Set([
+	"directional",
+	"spot",
+	"point",
+	"rect"
+]);
 /** Contrast below this makes text hard to read (WCAG large-text minimum). */
 const MIN_TEXT_CONTRAST = 3;
 function tracksOf(node) {
@@ -2146,6 +2321,21 @@ function solidColor(value) {
 	const c = parseCssColor(value);
 	return c && c[3] > .99 ? value : null;
 }
+/**
+* Cube cameras (panoramic lenses, relativity) and what they cannot combine
+* with. Returns whether the camera draws a cube.
+*/
+function lintCamera(node, id, push) {
+	const lens = node.lens;
+	const projection = lens?.projection ?? "perspective";
+	if (projection === "perspective" && (lens?.fov ?? 0) > 160) push("error", "camera_fov_range", `'${id}' has a ${lens?.fov}° perspective lens: perspective goes up to 160°. Use projection "fisheye" for wider views.`, id);
+	const relativity = node.relativity;
+	const cube = projection !== "perspective" || (relativity?.speed ?? 0) > 0 || animates(node, ["relativitySpeed"]);
+	const dof = node.dof;
+	if (cube && (dof?.enabled || animates(node, ["focusDistance"]))) push("error", "camera_cube_dof", `'${id}' is a cube camera (${relativity ? "relativity" : projection}) with depth of field: depth of field needs a single perspective view.`, id);
+	if (cube && node.motionBlur) push("error", "camera_cube_motion_blur", `'${id}' is a cube camera (${relativity ? "relativity" : projection}) with motionBlur: shutter motion blur needs a single perspective view.`, id);
+	return cube;
+}
 function lintComposition(config, options = {}) {
 	const out = [];
 	const push = (severity, code, message, layerId) => out.push({
@@ -2161,8 +2351,17 @@ function lintComposition(config, options = {}) {
 	let has3D = false;
 	const pbrNodes = [];
 	const emojiText = [];
+	const seenIds = /* @__PURE__ */ new Set();
+	let directLights = 0;
+	let fogLight;
+	let cubeCamera;
+	let screenSpaceLight;
 	const visit = (node, backdrop, atRoot) => {
 		const id = String(node.id ?? "?");
+		if (typeof node.id === "string") {
+			if (seenIds.has(node.id)) push("error", "duplicate_id", `Two layers share the id '${id}': the renderer keeps one and drops the other. Give every layer its own id (scenes reused in one composition need their own prefix).`, id);
+			seenIds.add(node.id);
+		}
 		if (options.emojiFont === false && node.kind === "text" && hasEmoji(textOf(node))) emojiText.push(id);
 		for (const prop of COLOR_PROPS) {
 			const v = node[prop];
@@ -2175,12 +2374,18 @@ function lintComposition(config, options = {}) {
 			const type = node.lightType ?? "directional";
 			if (type === "environment") hasEnvironment = true;
 			if (type === "ambient") ambientLights.push(id);
+			if (DIRECT_LIGHTS.has(String(type))) directLights++;
+			if (type === "environment" && node.volumetricFog) fogLight = id;
+			if (type === "environment" && (node.ssr || node.gi)) screenSpaceLight = id;
 			if (node.castShadow) {
-				if (type !== "directional" && type !== "spot") push("warning", "shadow_unsupported_light", `'${id}' is a ${String(type)} light: only directional and spot lights cast shadows.`, id);
+				if (type !== "directional" && type !== "spot" && type !== "point" && type !== "rect") push("warning", "shadow_unsupported_light", `'${id}' is a ${String(type)} light: only directional, spot, point, and rect lights cast shadows.`, id);
 			}
 			return;
 		}
-		if (node.kind === "camera") return;
+		if (node.kind === "camera") {
+			if (lintCamera(node, id, push)) cubeCamera = id;
+			return;
+		}
 		if (node.kind === "media") {
 			const src = node.inputHandleId;
 			if (typeof src === "string") {
@@ -2193,7 +2398,9 @@ function lintComposition(config, options = {}) {
 		}
 		const is3D = Boolean(node.is3D) || typeof node.z === "number" && node.z !== 0;
 		if (is3D || node.kind === "model3d") has3D = true;
-		if (node.roughness !== void 0 || node.metallic !== void 0) pbrNodes.push(id);
+		const scatter = node.scatter3d;
+		if (scatter && scatter.count > 0 && options.scatterCoverage?.(scatter) === 0) push("warning", "scatter_filters_reject_all", `'${id}' scatters onto a surface its slopeRange / elevationRange filters reject entirely, so no instance is placed. Widen the ranges (slope is degrees from level, elevation 0..1 from the surface's lowest to highest point).`, id);
+		if (node.roughness !== void 0 || node.metallic !== void 0 || node.clearcoat !== void 0 || node.anisotropy !== void 0) pbrNodes.push(id);
 		if (node.kind === "text" && backdrop && !animates(node, ["fill", "color"])) {
 			const fg = solidColor(node.fill ?? node.color);
 			const behind = solidColor(node.background) ?? backdrop;
@@ -2240,7 +2447,9 @@ function lintComposition(config, options = {}) {
 		push("warning", "missing_emoji_font", `${emojiText.length === 1 ? "Text" : `${emojiText.length} text layers`} ${shown}${emojiText.length > 3 ? ", …" : ""} ${emojiText.length === 1 ? "has" : "have"} emoji, but no emoji font is registered, so the emoji draw nothing. Run \`npx framefields fonts add emoji\` and call the generated \`registerFonts()\`, or \`FontManager.registerEmojiFont(path)\` with a color emoji font.`, emojiText[0]);
 	}
 	if (hasEnvironment && ambientLights.length > 0) push("info", "ambient_with_environment", `The environment already fills shadows with light; ambient light ${ambientLights.join(", ")} adds flat light on top (remove it, or lower it, if the scene looks washed out).`);
-	if (has3D && pbrNodes.length > 0 && !hasEnvironment) push("info", "pbr_without_environment", `roughness / metallic are set (${pbrNodes.slice(0, 3).join(", ")}${pbrNodes.length > 3 ? ", …" : ""}) but the scene has no Layer.environment(): add one for physically based shading, reflections and tone mapping.`);
+	if (cubeCamera && screenSpaceLight) push("error", "camera_cube_screen_space", `'${cubeCamera}' is a cube camera, and '${screenSpaceLight}' turns on ssr / gi: screen-space reflections and GI need a single perspective view. Use the environment's floor for reflections.`, screenSpaceLight);
+	if (fogLight && directLights === 0) push("warning", "volumetric_fog_without_lights", `'${fogLight}' turns on volumetricFog, but the scene has no directional, spot, point or rect light: fog scatters only direct light, so there are no light shafts. Add a light (castShadow for shafts).`, fogLight);
+	if (has3D && pbrNodes.length > 0 && !hasEnvironment) push("info", "pbr_without_environment", `roughness / metallic / clearcoat / anisotropy are set (${pbrNodes.slice(0, 3).join(", ")}${pbrNodes.length > 3 ? ", …" : ""}) but the scene has no Layer.environment(): add one for physically based shading, the coat and brushed-metal reflections, and tone mapping.`);
 	return out;
 }
 const GEOMETRY = [
@@ -2266,12 +2475,27 @@ function companion(owner, src, suffix, tag) {
 	if (Array.isArray(node.children)) node.children = hoistMattes(node.children);
 	return node;
 }
-function hoistOne(owner) {
+function textureCompanion(owner, src, size) {
+	const node = companion(owner, src, "texture", {
+		textureOf: String(owner.id),
+		is3D: false,
+		z: 0
+	});
+	if (GEOMETRY.every((k) => src[k] === void 0)) {
+		node.x = 0;
+		node.y = 0;
+		if (size.width !== void 0) node.width = size.width;
+		if (size.height !== void 0) node.height = size.height;
+	}
+	return node;
+}
+function hoistOne(owner, size) {
 	const matte = owner.matte;
 	const relief = owner.relief;
-	const { matte: _matte, relief: _relief, ...rest } = owner;
+	const texture = owner.textureLayer;
+	const { matte: _matte, relief: _relief, textureLayer: _texture, ...rest } = owner;
 	const self = { ...rest };
-	if (Array.isArray(self.children)) self.children = hoistMattes(self.children);
+	if (Array.isArray(self.children)) self.children = hoistMattes(self.children, size);
 	const out = [self];
 	if (matte?.node) {
 		const node = companion(owner, matte.node, "matte", {
@@ -2291,11 +2515,16 @@ function hoistOne(owner) {
 		self.reliefAmount = relief.amount ?? 0;
 		out.push(node);
 	}
+	if (texture?.node) {
+		const node = textureCompanion(owner, texture.node, size);
+		self.textureLayerId = node.id;
+		out.push(node);
+	}
 	return out;
 }
-/** Returns the tree with every `matte` and `relief` turned into a sibling companion layer. */
-function hoistMattes(nodes) {
-	return nodes.flatMap((n) => hoistOne(n));
+/** Returns the tree with every `matte`, `relief` and `textureLayer` turned into a sibling companion layer. */
+function hoistMattes(nodes, size = {}) {
+	return nodes.flatMap((n) => hoistOne(n, size));
 }
 /**
 * Read a `timeRemap` signal at a composition frame: a signal instance, a named
@@ -2328,6 +2557,181 @@ function sampleMediaTimeSignal(binding, layer, clock) {
 	};
 }
 /**
+* Schemas for procedural 3D content: terrain, SDF sculptures, surface
+* scattering and wind. A model node's `primitive3d` is checked against the
+* terrain / SDF schema when it names one of them.
+*/
+const Vec3Schema = z.tuple([
+	z.number(),
+	z.number(),
+	z.number()
+]);
+const RangeSchema = (min, max) => z.tuple([z.number().min(min).max(max), z.number().min(min).max(max)]);
+const ShadingSchema = z.enum([
+	"lit",
+	"unlit",
+	"toon"
+]);
+const PrimitiveSurfaceFields = {
+	color: z.string().optional(),
+	material: ShadingSchema.optional(),
+	shininess: z.number().min(0).optional(),
+	roughness: z.number().min(0).max(1).optional(),
+	metallic: z.number().min(0).max(1).optional()
+};
+const TerrainNoiseSchema = z.object({
+	seed: z.number().optional(),
+	scale: z.number().positive().optional(),
+	octaves: z.number().int().min(1).max(10).optional(),
+	persistence: z.number().min(0).max(1).optional(),
+	lacunarity: z.number().min(1).max(4).optional(),
+	ridgeMode: z.enum([
+		"fbm",
+		"ridged",
+		"terrace"
+	]).optional(),
+	terraceSteps: z.number().int().min(2).max(32).optional()
+}).strict();
+const TerrainColorByElevationSchema = z.object({
+	lowColor: z.string(),
+	midColor: z.string().optional(),
+	highColor: z.string(),
+	cliffColor: z.string().optional(),
+	cliffThreshold: z.number().min(0).max(1).optional(),
+	bands: RangeSchema(0, 1).optional()
+}).strict();
+const TerrainGeometrySchema = z.object({
+	type: z.literal("terrain"),
+	width: z.number().positive(),
+	depth: z.number().positive(),
+	height: z.number().min(0).optional(),
+	segments: z.union([z.number().int().min(1).max(512), z.tuple([z.number().int().min(1).max(512), z.number().int().min(1).max(512)])]).optional(),
+	noise: TerrainNoiseSchema.optional(),
+	heights: z.array(z.number().min(0).max(1)).optional(),
+	overhangWarp: z.number().min(0).optional(),
+	colorByElevation: TerrainColorByElevationSchema.optional(),
+	flatShaded: z.boolean().optional(),
+	base: z.number().min(0).optional(),
+	...PrimitiveSurfaceFields
+}).strict();
+const SdfBaseFields = {
+	op: z.enum([
+		"union",
+		"subtract",
+		"intersect"
+	]).optional(),
+	smoothness: z.number().min(0).optional(),
+	center: Vec3Schema.optional(),
+	rotation: Vec3Schema.optional(),
+	color: z.string().optional()
+};
+const SdfPrimitiveSchema = z.discriminatedUnion("shape", [
+	z.object({
+		...SdfBaseFields,
+		shape: z.literal("sphere"),
+		radius: z.number().positive()
+	}).strict(),
+	z.object({
+		...SdfBaseFields,
+		shape: z.literal("box"),
+		size: z.tuple([
+			z.number().positive(),
+			z.number().positive(),
+			z.number().positive()
+		]),
+		radius: z.number().min(0).optional()
+	}).strict(),
+	z.object({
+		...SdfBaseFields,
+		shape: z.literal("cylinder"),
+		radius: z.number().positive(),
+		height: z.number().positive()
+	}).strict(),
+	z.object({
+		...SdfBaseFields,
+		shape: z.literal("capsule"),
+		radius: z.number().positive(),
+		height: z.number().positive()
+	}).strict(),
+	z.object({
+		...SdfBaseFields,
+		shape: z.literal("torus"),
+		radius: z.number().positive(),
+		tube: z.number().positive()
+	}).strict(),
+	z.object({
+		...SdfBaseFields,
+		shape: z.literal("gyroid"),
+		scale: z.number().positive(),
+		thickness: z.number().positive()
+	}).strict()
+]);
+const SdfGeometrySchema = z.object({
+	type: z.literal("sdf"),
+	primitives: z.array(SdfPrimitiveSchema).min(1),
+	bounds: z.tuple([
+		z.number().positive(),
+		z.number().positive(),
+		z.number().positive()
+	]),
+	resolution: z.number().int().min(16).max(160).optional(),
+	flatShaded: z.boolean().optional(),
+	...PrimitiveSurfaceFields
+}).strict();
+/** `primitive3d`: free-form for the classic primitives, strict for terrain and SDF. */
+const Primitive3DSpecSchema = z.unknown().superRefine((value, ctx) => {
+	const type = value?.type;
+	const schema = type === "terrain" ? TerrainGeometrySchema : type === "sdf" ? SdfGeometrySchema : void 0;
+	if (!schema) return;
+	const parsed = schema.safeParse(value);
+	if (parsed.success) return;
+	for (const issue$1 of parsed.error.issues) ctx.addIssue({
+		...issue$1,
+		code: "custom",
+		message: issue$1.message
+	});
+});
+const WindSchema = z.object({
+	amplitudeDeg: z.number().min(0).max(90).optional(),
+	frequency: z.number().min(0).max(20).optional(),
+	direction: z.tuple([z.number(), z.number()]).optional(),
+	waveScale: z.number().positive().optional()
+}).strict();
+const ScatterExclusionSchema = z.object({
+	x: z.number(),
+	z: z.number(),
+	radius: z.number().min(0),
+	falloff: z.number().min(0).optional()
+}).strict();
+const Scatter3DSchema = z.object({
+	surface: z.custom((v) => typeof v === "object" && v !== null),
+	count: z.number().int().min(0).max(2e5),
+	minDistance: z.number().min(0).optional(),
+	seed: z.number().optional(),
+	slopeRange: RangeSchema(0, 180).optional(),
+	elevationRange: RangeSchema(0, 1).optional(),
+	alignToNormal: z.number().min(0).max(1).optional(),
+	scaleRange: z.tuple([z.number().positive(), z.number().positive()]).optional(),
+	randomYaw: z.boolean().optional(),
+	exclude: z.array(ScatterExclusionSchema).optional(),
+	sink: z.number().optional()
+}).strict();
+/** A layer drawn offscreen every frame and wrapped onto a model's surface. */
+const TextureLayerSchema = z.object({ node: z.custom((v) => typeof v === "object" && v !== null) }).strict();
+/**
+* Voronoi destruction (`world.fracture`): the model is cut into `cells`
+* pieces, drawn as one rigidly skinned mesh posed per frame from `track`.
+* Without a track the pieces rest in place and the model looks whole.
+*/
+const Fracture3DSchema = z.object({
+	cells: z.number().int().min(2).max(256).optional(),
+	seed: z.number().optional(),
+	impactPoint: Vec3Schema.optional(),
+	interiorColor: z.string().optional(),
+	interiorRoughness: z.number().min(0).max(1).optional(),
+	track: z.array(z.number()).optional()
+}).strict();
+/**
 * Compositor program document v2 — THE single source of truth for a
 * composition (spec: `nodes/node-compositor/SKILL.md`).
 *
@@ -2431,6 +2835,7 @@ const AnimatablePropSchema = z.enum([
 	"maxBlurRadius",
 	"shakeTranslation",
 	"shakeRotation",
+	"relativitySpeed",
 	"orbitRadius",
 	"orbitAzimuth",
 	"orbitElevation",
@@ -2459,7 +2864,24 @@ const AnimatablePropSchema = z.enum([
 	"scaleY",
 	"emissive",
 	"emissiveIntensity",
-	"exposure"
+	"clearcoat",
+	"clearcoatRoughness",
+	"anisotropy",
+	"anisotropyRotation",
+	"subsurface",
+	"subsurfaceColor",
+	"sheen",
+	"sheenColor",
+	"sheenRoughness",
+	"iridescence",
+	"iridescenceThickness",
+	"iridescenceIor",
+	"triplanarScale",
+	"triplanarSharpness",
+	"exposure",
+	"volumetricFogDensity",
+	"volumetricFogAnisotropy",
+	"volumetricFogNoiseStrength"
 ]);
 const MatteModeSchema = z.enum([
 	"alpha",
@@ -2544,6 +2966,12 @@ const KeyframeSchema = z.object({
 	}).optional()
 }).strict();
 const SignalModeSchema = z.enum(["continuous", "accumulate"]);
+/**
+* Which clock a signal track reads: the composition's (default), as audio
+* analysis and shared signals need, or its layer's own, from the layer's
+* start frame, as keyframes do: motion authored for one scene of a sequence.
+*/
+const SignalClockSchema = z.enum(["composition", "layer"]);
 const RawTrackSourceSchema = z.discriminatedUnion("type", [
 	z.object({ type: z.literal("keyframe") }),
 	z.object({
@@ -2560,7 +2988,8 @@ const RawTrackSourceSchema = z.discriminatedUnion("type", [
 		threshold: z.number().optional(),
 		accumulateThreshold: z.number().optional(),
 		debounceFrames: z.number().int().min(0).optional(),
-		channel: z.string().optional()
+		channel: z.string().optional(),
+		clock: SignalClockSchema.optional()
 	}),
 	z.object({
 		type: z.literal("wiggle"),
@@ -2595,7 +3024,8 @@ const TrackSourceSchema = z.preprocess((val) => {
 			threshold: thresh,
 			accumulateThreshold: thresh,
 			debounceFrames: obj.debounceFrames ?? 2,
-			channel: typeof obj.channel === "string" ? obj.channel : "primary"
+			channel: typeof obj.channel === "string" ? obj.channel : "primary",
+			...obj.clock !== void 0 && { clock: obj.clock }
 		};
 	}
 	return val;
@@ -2717,6 +3147,30 @@ const LayerAnimationSchema = z.object({
 	tracks: z.array(AnimationTrackSchema).max(24),
 	frameStep: z.number().int().min(1).max(24).optional()
 }).strict().superRefine(animationInvariants);
+const ToonShadingSchema = z.object({
+	shadowColor: ColorSchema.optional(),
+	lightColor: ColorSchema.optional(),
+	threshold: z.number().min(-1).max(1).optional(),
+	softness: z.number().min(0).max(2).optional(),
+	diffuse: z.number().min(0).max(1).optional()
+}).strict();
+const GeometryOutlineOptionsSchema = z.object({
+	color: ColorSchema.optional(),
+	width: z.number().min(0).max(32).optional(),
+	referenceHeight: z.number().positive().optional(),
+	creaseAngle: z.number().min(0).max(180).optional(),
+	depthThreshold: z.number().positive().max(1).optional(),
+	opacity: z.number().min(0).max(1).optional()
+}).strict();
+const IridescenceConfigSchema = z.object({
+	intensity: z.number().min(0).max(1).optional(),
+	thickness: z.number().min(100).max(1200).optional(),
+	ior: z.number().min(1.05).max(2.5).optional()
+}).strict();
+const TriplanarConfigSchema = z.object({
+	scale: z.number().min(0).optional(),
+	sharpness: z.number().min(1).max(16).optional()
+}).strict();
 const BaseNodeFields = {
 	id: z.string().min(1),
 	inputHandleId: z.string().optional(),
@@ -2777,7 +3231,24 @@ const BaseNodeFields = {
 	envIntensity: z.number().min(0).max(10).optional(),
 	emissive: ColorSchema.optional(),
 	emissiveIntensity: z.number().min(0).optional(),
+	clearcoat: z.number().min(0).max(1).optional(),
+	clearcoatRoughness: z.number().min(0).max(1).optional(),
+	anisotropy: z.number().min(-1).max(1).optional(),
+	anisotropyRotation: z.number().optional(),
+	subsurface: z.number().min(0).max(1).optional(),
+	subsurfaceColor: ColorSchema.optional(),
+	sheen: z.number().min(0).max(1).optional(),
+	sheenColor: ColorSchema.optional(),
+	sheenRoughness: z.number().min(.05).max(1).optional(),
+	iridescence: z.union([z.number().min(0).max(1), IridescenceConfigSchema]).optional(),
+	iridescenceThickness: z.number().min(100).max(1200).optional(),
+	iridescenceIor: z.number().min(1.05).max(2.5).optional(),
+	triplanar: z.union([z.boolean(), TriplanarConfigSchema]).optional(),
+	triplanarScale: z.number().min(0).optional(),
+	triplanarSharpness: z.number().min(1).max(16).optional(),
 	castShadow: z.boolean().optional(),
+	toon: ToonShadingSchema.optional(),
+	outline: z.boolean().optional(),
 	matte: z.object({
 		node: z.custom((v) => typeof v === "object" && v !== null),
 		mode: MatteModeSchema.optional()
@@ -2792,6 +3263,7 @@ const BaseNodeFields = {
 	reliefId: z.string().optional(),
 	reliefOf: z.string().optional(),
 	reliefAmount: z.number().optional(),
+	textureOf: z.string().optional(),
 	animation: LayerAnimationSchema.default({ tracks: [] }),
 	vision: z.unknown().optional(),
 	relighting: z.unknown().optional()
@@ -2903,13 +3375,25 @@ const TextAnimator = {
 		};
 	}
 };
+/**
+* The picture a camera draws. `perspective` is an ordinary lens; the others
+* are cube cameras: the scene is drawn as six 90° faces around the eye and
+* remapped, so they can show what no single frustum holds.
+*/
+const CameraProjectionSchema = z.enum([
+	"perspective",
+	"equirectangular",
+	"fisheye"
+]);
 const CameraLensSchema = z.object({
 	focalLength: z.number().min(5).max(500).default(50),
-	fov: z.number().min(5).max(160).optional(),
+	fov: z.number().min(5).max(360).optional(),
 	sensorWidth: z.number().default(36),
 	near: z.number().min(.1).default(1),
 	far: z.number().min(10).default(5e4),
-	zoom: z.number().min(.01).default(1)
+	zoom: z.number().min(.01).default(1),
+	projection: CameraProjectionSchema.default("perspective"),
+	cubeSize: z.number().int().min(64).max(8192).optional()
 }).strict();
 const CameraDoFSchema = z.object({
 	enabled: z.boolean().default(false),
@@ -2926,6 +3410,33 @@ const CameraShakeSchema = z.object({
 	octaves: z.number().int().min(1).max(6).default(3),
 	seed: z.number().default(42)
 }).strict();
+/**
+* Per-object shutter motion blur for the 3D scene: every mesh, skinned
+* joint, instance and fractured piece streaks by its own motion over the
+* shutter (and the camera's), reconstructed from a velocity buffer.
+*/
+const CameraMotionBlurSchema = z.object({
+	shutter: z.number().min(1).max(720).default(180),
+	samples: z.number().int().min(4).max(64).default(20),
+	maxBlur: z.number().min(4).max(160).default(48)
+}).strict();
+/**
+* The camera moves through the scene near the speed of light. What it sees
+* is physics, not grading: rays crowd towards the direction of motion
+* (aberration), colours shift blue ahead and red behind (Doppler) and ahead
+* brightens (beaming). Always drawn by a cube camera.
+*/
+const CameraRelativitySchema = z.object({
+	speed: z.number().min(0).max(.9999).default(0),
+	direction: z.tuple([
+		z.number(),
+		z.number(),
+		z.number()
+	]).optional(),
+	doppler: z.boolean().default(true),
+	beaming: z.boolean().default(true),
+	exposure: z.union([z.literal("auto"), z.number().min(-64).max(16)]).default("auto")
+}).strict();
 const CameraNodeSchema = z.object({
 	id: z.string().min(1),
 	kind: z.literal("camera"),
@@ -2946,6 +3457,8 @@ const CameraNodeSchema = z.object({
 	lens: CameraLensSchema.optional(),
 	dof: CameraDoFSchema.optional(),
 	shake: CameraShakeSchema.optional(),
+	motionBlur: z.union([z.boolean(), CameraMotionBlurSchema]).optional(),
+	relativity: CameraRelativitySchema.optional(),
 	startFrame: z.number().int().min(0).default(0),
 	durationFrames: z.number().int().min(1).optional(),
 	animation: LayerAnimationSchema.default({ tracks: [] })
@@ -2955,13 +3468,16 @@ const LightTypeSchema = z.enum([
 	"directional",
 	"point",
 	"spot",
+	"rect",
 	"environment"
 ]);
 const EnvironmentPresetSchema = z.enum([
 	"studio",
 	"soft",
+	"warm",
 	"sunset",
 	"night",
+	"neon",
 	"neutral"
 ]);
 const ToneMappingSchema = z.enum([
@@ -2990,6 +3506,39 @@ const EnvironmentFloorSchema = z.object({
 	fadeDistance: z.number().min(0).optional(),
 	opacity: z.number().min(0).max(1).optional()
 }).strict();
+const EnvironmentVolumetricFogNoiseSchema = z.object({
+	scale: z.number().min(1e-4).optional(),
+	strength: z.number().min(0).max(1).optional(),
+	speed: z.tuple([
+		z.number(),
+		z.number(),
+		z.number()
+	]).optional(),
+	octaves: z.number().int().min(1).max(3).optional()
+}).strict();
+const EnvironmentVolumetricFogSchema = z.object({
+	density: z.number().min(0).optional(),
+	color: ColorSchema.optional(),
+	anisotropy: z.number().min(-.95).max(.95).optional(),
+	heightFalloff: z.number().min(0).optional(),
+	baseHeight: z.number().optional(),
+	steps: z.number().int().min(8).max(64).optional(),
+	maxDistance: z.number().min(100).optional(),
+	lightIntensity: z.number().min(0).optional(),
+	ambientIntensity: z.number().min(0).optional(),
+	noise: z.union([z.boolean(), EnvironmentVolumetricFogNoiseSchema]).optional()
+}).strict();
+const EnvironmentSsrSchema = z.object({
+	intensity: z.number().min(0).max(1).optional(),
+	maxRoughness: z.number().min(0).max(1).optional(),
+	thickness: z.number().min(1).optional(),
+	steps: z.number().int().min(16).max(64).optional()
+}).strict();
+const EnvironmentGiSchema = z.object({
+	intensity: z.number().min(0).max(4).optional(),
+	radius: z.number().min(1).optional(),
+	samples: z.number().int().min(4).max(16).optional()
+}).strict();
 const LightNodeSchema = z.object({
 	id: z.string().min(1),
 	kind: z.literal("light"),
@@ -3011,11 +3560,15 @@ const LightNodeSchema = z.object({
 	decay: z.number().min(0).default(2),
 	angle: z.number().min(0).max(180).default(45),
 	penumbra: z.number().min(0).max(1).default(.2),
+	width: z.number().min(0).optional(),
+	height: z.number().min(0).optional(),
+	twoSided: z.boolean().optional(),
 	castShadow: z.boolean().optional(),
 	shadowSoftness: z.number().min(0).max(64).optional(),
 	shadowDarkness: z.number().min(0).max(1).optional(),
 	shadowMapSize: z.number().int().min(256).max(8192).optional(),
 	preset: EnvironmentPresetSchema.optional(),
+	hdri: z.union([z.string(), z.custom((v) => v instanceof Uint8Array)]).optional(),
 	top: ColorSchema.optional(),
 	horizon: ColorSchema.optional(),
 	bottom: ColorSchema.optional(),
@@ -3025,6 +3578,13 @@ const LightNodeSchema = z.object({
 	toneMapping: ToneMappingSchema.optional(),
 	fog: EnvironmentFogSchema.optional(),
 	floor: EnvironmentFloorSchema.optional(),
+	volumetricFog: z.union([z.boolean(), EnvironmentVolumetricFogSchema]).optional(),
+	volumetricFogDensity: z.number().min(0).optional(),
+	volumetricFogAnisotropy: z.number().min(-.95).max(.95).optional(),
+	volumetricFogNoiseStrength: z.number().min(0).max(1).optional(),
+	ssr: z.union([z.boolean(), EnvironmentSsrSchema]).optional(),
+	gi: z.union([z.boolean(), EnvironmentGiSchema]).optional(),
+	outlines: z.union([z.boolean(), GeometryOutlineOptionsSchema]).optional(),
 	bloom: z.union([z.boolean(), BloomConfigSchema]).optional(),
 	startFrame: z.number().int().min(0).default(0),
 	durationFrames: z.number().int().min(1).optional(),
@@ -3057,7 +3617,7 @@ const FlexNodeSchema = z.object({
 		"reverse",
 		"center-out"
 	]).default("forward"),
-	overflow: z.enum(["visible", "hidden"]).default("hidden"),
+	overflow: z.enum(["visible", "hidden"]).default("visible"),
 	background: ColorSchema.optional(),
 	borderRadius: z.number().min(0).optional(),
 	borderColor: ColorSchema.optional(),
@@ -3087,7 +3647,7 @@ const BlockNodeSchema = z.object({
 		"reverse",
 		"center-out"
 	]).default("forward"),
-	overflow: z.enum(["visible", "hidden"]).default("hidden"),
+	overflow: z.enum(["visible", "hidden"]).default("visible"),
 	background: ColorSchema.optional(),
 	borderRadius: z.number().min(0).optional(),
 	borderColor: ColorSchema.optional(),
@@ -3112,7 +3672,7 @@ const BoxNodeSchema = z.object({
 		"reverse",
 		"center-out"
 	]).default("forward"),
-	overflow: z.enum(["visible", "hidden"]).default("hidden"),
+	overflow: z.enum(["visible", "hidden"]).default("visible"),
 	borderColor: ColorSchema.optional(),
 	borderWidth: z.number().min(0).optional(),
 	strokeAlign: z.enum([
@@ -3148,6 +3708,7 @@ const TextFields = {
 	fontSize: z.number().positive().optional(),
 	fontWeight: z.union([z.number().int(), z.string()]).optional(),
 	fontStyle: z.string().optional(),
+	fontVariations: z.record(z.string(), z.number()).optional(),
 	fill: ColorSchema,
 	align: z.enum([
 		"start",
@@ -3353,9 +3914,23 @@ const Model3DNodeSchema = z.object({
 	color: ColorSchema.optional(),
 	colorTint: ColorSchema.optional(),
 	text3dOptions: z.unknown().optional(),
-	primitive3d: z.unknown().optional(),
+	primitive3d: Primitive3DSpecSchema.optional(),
 	instances3d: z.unknown().optional(),
-	swarm3d: z.unknown().optional()
+	swarm3d: z.unknown().optional(),
+	scatter3d: Scatter3DSchema.optional(),
+	fracture3d: Fracture3DSchema.optional(),
+	wind: WindSchema.optional(),
+	textureLayer: TextureLayerSchema.optional(),
+	textureLayerId: z.string().optional(),
+	animationLayers: z.array(ModelAnimationLayerSchema).optional(),
+	ik: z.array(TwoBoneIkSchema).optional(),
+	lookAt: z.array(LookAtSchema).optional(),
+	springBones: z.array(SpringBoneChainSchema).optional(),
+	pose: z.record(z.string(), JointPoseSchema).optional(),
+	morphs: z.record(z.string(), NumberTrackSchema).optional(),
+	aim: z.array(AimSchema).optional(),
+	drive: z.array(JointDriverSchema).optional(),
+	crowd: CrowdSchema.optional()
 }).strict();
 /**
 * Dispatch on `kind`, not a plain union: a plain union tries every member,
@@ -3395,7 +3970,6 @@ const CompositorProgramSchema = z.object({
 * @module @framefields/compositions/program/sequence
 *
 * Multi-Scene Timeline Orchestration, Camera Choreography & Carrier Match Cuts.
-* Complies with specs/cinematic-sequencing.ts.
 */
 /**
 * Camera Transition Type across scene boundaries.
@@ -3636,6 +4210,40 @@ function applyStaggerToChildren(children, staggerFrames, direction = "forward",
 * Pure + deterministic: same doc → same tree. No width/height resolution
 * here — geometry comes from `computeLayout` at render time.
 */
+/**
+* A container holding a camera and the layers it films is a 3D scene of its
+* own: its camera, lights and environment see only its layers. It needs a
+* fixed size to render at. A container holding only a camera (and lights) is
+* a shot in a camera cut list over the shared world, and stays one.
+*/
+function isScene3D(node) {
+	if (node.kind !== "box" && node.kind !== "flex" && node.kind !== "block" || typeof node.width !== "number" || typeof node.height !== "number" || !Array.isArray(node.children)) return false;
+	const kids = node.children;
+	return kids.some((c) => c.kind === "camera") && kids.some((c) => c.kind !== "camera" && c.kind !== "light");
+}
+/**
+* `media` with `node`'s effects applied in order, each a pass over the
+* picture below it: a clip's frames, or a 3D scene's finished composition.
+*/
+function wrapEffects(media, node) {
+	if (!Array.isArray(node.effects)) return media;
+	let current = media;
+	for (const eff of node.effects) {
+		const effOp = eff && typeof eff.toOperation === "function" ? eff.toOperation() : eff;
+		current = {
+			metadata: { ...current.metadata },
+			operation: {
+				op: String(effOp.op ?? "effect"),
+				id: node.id ? `${node.id}-${effOp.op ?? "effect"}` : void 0,
+				effect: eff,
+				...effOp,
+				dataType: current.operation.dataType
+			},
+			children: [current]
+		};
+	}
+	return current;
+}
 function nodeToVirtualMedia(node, resolveMedia, fps, inheritedOffset = 0, compDurationMs, inheritedDurationFrames, resolveSignal) {
 	if (node.kind === "media" && node.timeRemap !== void 0) {
 		const parsed = MediaTimeRemapInputSchema.safeParse(node.timeRemap);
@@ -3665,24 +4273,7 @@ function nodeToVirtualMedia(node, resolveMedia, fps, inheritedOffset = 0, compDu
 				children: [media]
 			};
 		}
-		if (media && Array.isArray(node.effects)) {
-			let currentMedia = media;
-			for (const eff of node.effects) {
-				const effOp = eff && typeof eff.toOperation === "function" ? eff.toOperation() : eff;
-				currentMedia = {
-					metadata: { ...currentMedia.metadata },
-					operation: {
-						op: String(effOp.op ?? "effect"),
-						id: node.id ? `${node.id}-${effOp.op ?? "effect"}` : void 0,
-						effect: eff,
-						...effOp,
-						dataType: currentMedia.operation.dataType
-					},
-					children: [currentMedia]
-				};
-			}
-			media = currentMedia;
-		}
+		if (media) media = wrapEffects(media, node);
 		if (media && node.vision) {
 			const visionRaw = node.vision;
 			const visionOp = typeof visionRaw.toOperation === "function" ? visionRaw.toOperation() : visionRaw;
@@ -3706,10 +4297,48 @@ function nodeToVirtualMedia(node, resolveMedia, fps, inheritedOffset = 0, compDu
 		const nodeStart = typeof node.startFrame === "number" && Number.isFinite(node.startFrame) ? Math.round(node.startFrame) : 0;
 		const nodeDuration = typeof node.durationFrames === "number" && Number.isFinite(node.durationFrames) ? Math.round(node.durationFrames) : inheritedDurationFrames;
 		const nodeChildren = node.children;
+		const scene = isScene3D(node);
 		children = nodeChildren.map((c, idx) => {
 			const delay = computeStaggerDelay(idx, nodeChildren.length, staggerFrames, staggerDirection);
-			return nodeToVirtualMedia(c, resolveMedia, fps, inheritedOffset + nodeStart + delay, compDurationMs, c.durationFrames === void 0 ? nodeDuration : void 0, resolveSignal);
+			return nodeToVirtualMedia(c, resolveMedia, fps, scene ? delay : inheritedOffset + nodeStart + delay, compDurationMs, c.durationFrames === void 0 ? nodeDuration : void 0, resolveSignal);
 		});
+		if (scene) {
+			const frames = nodeDuration ?? Math.round((compDurationMs ?? 1e4) / 1e3 * fps);
+			const durationMs$1 = frames / fps * 1e3;
+			const background = typeof node.background === "string" ? node.background : void 0;
+			const clear = background && parseCssColor(background) ? background : void 0;
+			if (background && !clear) children.unshift(nodeToVirtualMedia({
+				kind: "box",
+				id: `${node.id ?? "scene"}-background`,
+				position: "absolute",
+				x: 0,
+				y: 0,
+				width: node.width,
+				height: node.height,
+				background
+			}, resolveMedia, fps, 0, compDurationMs, frames, resolveSignal));
+			media = {
+				metadata: {
+					width: node.width,
+					height: node.height,
+					fps,
+					durationMs: durationMs$1
+				},
+				operation: {
+					op: "Compositor",
+					width: node.width,
+					height: node.height,
+					fps,
+					mode: "Video",
+					dataType: "Video",
+					volume: 1,
+					...clear && { backgroundColor: clear }
+				},
+				children
+			};
+			media = wrapEffects(media, node);
+			children = [media];
+		}
 	}
 	let dataType = "Image";
 	let limit;
@@ -3724,7 +4353,8 @@ function nodeToVirtualMedia(node, resolveMedia, fps, inheritedOffset = 0, compDu
 	let dur = typeof node.durationFrames === "number" && Number.isFinite(node.durationFrames) && node.durationFrames > 0 ? Math.round(node.durationFrames) : void 0;
 	const defaultCompDuration = inheritedDurationFrames ?? Math.round((compDurationMs ?? 1e4) / 1e3 * fps);
 	if (isContainer && children.length > 0) {
-		if (dur === void 0) {
+		if (dur === void 0 && isScene3D(node)) dur = Math.max(1, defaultCompDuration);
+		else if (dur === void 0) {
 			const childEnds = children.map((c) => (c.operation.startFrame ?? 0) + (c.operation.durationFrames ?? defaultCompDuration));
 			dur = Math.max(1, Math.max(...childEnds) - startFrame);
 		}
@@ -3751,6 +4381,12 @@ function nodeToVirtualMedia(node, resolveMedia, fps, inheritedOffset = 0, compDu
 		operation: {
 			op: "CompositorLayer",
 			...node,
+			...isScene3D(node) && {
+				kind: "media",
+				background: void 0,
+				children: void 0,
+				effects: void 0
+			},
 			startFrame,
 			durationFrames: dur,
 			dataType,
@@ -3795,8 +4431,12 @@ function compositorToProgram(config, options) {
 			signals: programSignals,
 			...config.onRequestFrame || options.onRequestFrame ? { onRequestFrame: config.onRequestFrame ?? options.onRequestFrame } : {}
 		},
-		children: hoistMattes(config.layout).map((n) => nodeToVirtualMedia(n, resolveMedia, fps, 0, durationMs, void 0, resolveMediaSignal))
+		children: hoistMattes(config.layout, {
+			width: config.width,
+			height: config.height
+		}).map((n) => nodeToVirtualMedia(n, resolveMedia, fps, 0, durationMs, void 0, resolveMediaSignal))
 	};
+	shareSignals(rootMedia.children ?? [], programSignals);
 	const effectsList = Array.isArray(options.effects) ? options.effects : Array.isArray(config.effects) ? config.effects : [];
 	for (const eff of effectsList) {
 		const effOp = eff && typeof eff.toOperation === "function" ? eff.toOperation() : eff;
@@ -3824,17 +4464,238 @@ function compositorToProgram(config, options) {
 	}
 	return rootMedia;
 }
-/** Recursively gather every node op from a render tree (in order). */
+/** Hands every nested scene composition the program's signals, which its tracks read. */
+function shareSignals(nodes, signals) {
+	for (const vm of nodes) {
+		if (vm?.operation?.op === "Compositor") vm.operation.signals = signals;
+		shareSignals(vm?.children ?? [], signals);
+	}
+}
+/**
+* Recursively gather every node op from a render tree (in order), stopping at
+* nested scene compositions: their layers belong to their own render.
+*/
+/**
+* Every layer, 3D scenes' layers included, with its start on the
+* composition's clock. A scene's layers run on the scene's own clock, which
+* starts where the scene's layer does, so their starts are offset by it.
+*/
+function collectLayersOnClock(nodes) {
+	const out = [];
+	const walk = (vm, offset, layerStart) => {
+		const op = vm?.operation;
+		if (op?.op === "Compositor") {
+			for (const c of vm.children ?? []) walk(c, layerStart, layerStart);
+			return;
+		}
+		let start = layerStart;
+		if (op?.op === "CompositorLayer") {
+			start = offset + (op.startFrame ?? 0);
+			out.push({
+				vm,
+				startFrame: start
+			});
+		}
+		for (const c of vm?.children ?? []) walk(c, offset, start);
+	};
+	for (const n of nodes) walk(n, 0, 0);
+	return out;
+}
 function collectNodeOps(nodes) {
 	const out = [];
 	const walk = (vm) => {
+		if (vm?.operation?.op === "Compositor") return;
 		if (vm?.operation?.op === "CompositorLayer") out.push(vm);
 		for (const c of vm?.children ?? []) walk(c);
 	};
 	for (const n of nodes) walk(n);
 	return out;
 }
+/**
+* Sampling a layer's animation at a frame exactly as the compositor draws
+* it: keyframe segments shaped by GSAP's eases (what the compiled GSAP
+* timeline plays), other sources (wiggle, spring, signals) by the program
+* evaluator. The compositor's draw-time tracks and anything that must agree
+* with the picture outside a render (physics following a layer) share it.
+*/
+const gsap = gsapModule.default ?? gsapModule;
+/**
+* Solves a cubic bezier curve defined by control points (x1, y1) and (x2, y2)
+* for a given progress parameter t in [0, 1].
+*/
+function solveCubicBezier(x1, y1, x2, y2, t) {
+	if (t <= 0) return 0;
+	if (t >= 1) return 1;
+	if (x1 === y1 && x2 === y2) return t;
+	let u = t;
+	for (let i = 0; i < 8; i++) {
+		const oneMinusU$1 = 1 - u;
+		const oneMinusU2 = oneMinusU$1 * oneMinusU$1;
+		const u2 = u * u;
+		const diff = 3 * oneMinusU2 * u * x1 + 3 * oneMinusU$1 * u2 * x2 + u2 * u - t;
+		if (Math.abs(diff) < 1e-6) break;
+		const dx = 3 * oneMinusU2 * x1 + 6 * oneMinusU$1 * u * (x2 - x1) + 3 * u2 * (1 - x2);
+		if (Math.abs(dx) < 1e-6) break;
+		u -= diff / dx;
+		u = Math.max(0, Math.min(1, u));
+	}
+	const oneMinusU = 1 - u;
+	const checkX = 3 * oneMinusU * oneMinusU * u * x1 + 3 * oneMinusU * u * u * x2 + u * u * u;
+	if (Math.abs(checkX - t) > .001) {
+		let low = 0;
+		let high = 1;
+		u = t;
+		for (let i = 0; i < 16; i++) {
+			const mid = (low + high) * .5;
+			const oMid = 1 - mid;
+			const xMid = 3 * oMid * oMid * mid * x1 + 3 * oMid * mid * mid * x2 + mid * mid * mid;
+			if (Math.abs(xMid - t) < 1e-5) {
+				u = mid;
+				break;
+			}
+			if (xMid < t) low = mid;
+			else high = mid;
+			u = mid;
+		}
+	}
+	const oU = 1 - u;
+	return 3 * oU * oU * u * y1 + 3 * oU * u * u * y2 + u * u * u;
+}
+function mappedEase(ease, durationFrames, fps = 24) {
+	if (!ease) return "none";
+	const { name, dir, params } = ease;
+	if (name === "none") return "none";
+	if (name === "spring") {
+		const damping = Math.max(.001, params?.[0] ?? 10);
+		const stiffness = Math.max(.001, params?.[1] ?? 100);
+		const mass = Math.max(.001, params?.[2] ?? 1);
+		return (p) => {
+			const t = p * (durationFrames && durationFrames > 0 ? durationFrames / (fps > 0 ? fps : 24) : 1);
+			const m = mass;
+			const k = stiffness;
+			const c = damping;
+			const w0 = Math.sqrt(k / m);
+			const zeta = c / (2 * Math.sqrt(k * m));
+			let x = 0;
+			if (zeta < 1) {
+				const wd = w0 * Math.sqrt(1 - zeta * zeta);
+				const A = -1;
+				const B = -zeta * w0 / wd;
+				x = Math.exp(-zeta * w0 * t) * (A * Math.cos(wd * t) + B * Math.sin(wd * t));
+			} else if (zeta === 1) {
+				const A = -1;
+				const B = -w0;
+				x = Math.exp(-w0 * t) * (A + B * t);
+			} else {
+				const r1 = -w0 * (zeta - Math.sqrt(zeta * zeta - 1));
+				const r2 = -w0 * (zeta + Math.sqrt(zeta * zeta - 1));
+				const C1 = -1 / (1 - r1 / r2);
+				const C2 = -1 - C1;
+				x = C1 * Math.exp(r1 * t) + C2 * Math.exp(r2 * t);
+			}
+			return 1 + x;
+		};
+	}
+	if (name === "cubic") {
+		const x1 = params?.[0] ?? .25;
+		const y1 = params?.[1] ?? .1;
+		const x2 = params?.[2] ?? .25;
+		const y2 = params?.[3] ?? 1;
+		return (p) => solveCubicBezier(x1, y1, x2, y2, p);
+	}
+	if (name === "hold") return (p) => p >= .9999 ? 1 : 0;
+	const easeName = name;
+	let suffix = "";
+	if (params && params.length > 0) suffix = `(${params.join(", ")})`;
+	else if (name === "back") suffix = "(1.7)";
+	else if (name === "elastic") suffix = "(1, 0.3)";
+	return `${easeName}.${dir}${suffix}`;
+}
+/** GSAP's shaping for a keyframe segment, so draw-time tracks ease like baked ones. */
+function gsapEase(fps) {
+	return (ease, deltaFrames, t) => {
+		const e = mappedEase(ease, deltaFrames, fps);
+		const fn = typeof e === "function" ? e : gsap.parseEase(e);
+		return fn ? fn(t) : t;
+	};
+}
+/** A track's value at composition frame `frame`. */
+function sampleTrack(track, frame, fps, ctx = {}) {
+	const startFrame = ctx.startFrame ?? 0;
+	const step = ctx.step ?? 1;
+	const f = step > 1 ? startFrame + Math.floor((frame - startFrame) / step) * step : frame;
+	if ((track.source ?? { type: "keyframe" }).type === "keyframe") return evaluateKeyframes(track, f - startFrame, gsapEase(fps));
+	return evaluateTrackAtFrame(track, f, fps, {
+		startFrame,
+		baseValues: ctx.base,
+		signals: ctx.signals
+	});
+}
+/**
+* A layer's numeric prop at composition frame `frame`: its own value, then
+* each of its tracks on that prop in order (a later track overrides).
+*/
+function sampleLayerProp(layer, prop, frame, fps, fallback = 0) {
+	const own = layer[prop];
+	let value = typeof own === "number" && Number.isFinite(own) ? own : fallback;
+	const animation = layer.animation;
+	for (const track of animation?.tracks ?? []) {
+		if (track.prop !== prop) continue;
+		const v = sampleTrack(track, frame, fps, {
+			startFrame: layer.startFrame ?? 0,
+			step: animation?.frameStep,
+			base: layer
+		});
+		if (typeof v === "number" && Number.isFinite(v)) value = v;
+	}
+	return value;
+}
+const signalContext = (c) => ({
+	frame: c.frame,
+	fps: c.fps,
+	time: c.frame / c.fps,
+	duration: 0,
+	durationMs: 0,
+	progress: 0,
+	deltaTime: 1 / c.fps
+});
+/** A number track's value: constant, keys, function, or signal. */
+function numberAt(track, clock, fallback) {
+	if (track === void 0) return fallback;
+	if (typeof track === "number") return track;
+	if (typeof track === "function") return track(clock.frame);
+	if (Array.isArray(track)) return keyed(track, clock.frame, 1)[0] ?? fallback;
+	const v = track.get(signalContext(clock));
+	return Number.isFinite(v) ? v : fallback;
+}
+/** Whether a point track is `[[frame, x, y, z], …]` keys (not one track per axis). */
+const isPointKeys = (track) => Array.isArray(track[0]) && track[0].length === 4;
+/** A point track's value: per-axis tracks, keys, or a function. */
+function vec3At(track, clock) {
+	if (typeof track === "function") return track(clock.frame);
+	if (isPointKeys(track)) return keyed(track, clock.frame, 3);
+	const axes = track;
+	return [
+		numberAt(axes[0], clock, 0),
+		numberAt(axes[1], clock, 0),
+		numberAt(axes[2], clock, 0)
+	];
+}
+/** Linear interpolation over `[[frame, …values]]` keys, held past the ends. */
+function keyed(keys, frame, size) {
+	const sorted = keys;
+	const first = sorted[0];
+	const last = sorted[sorted.length - 1];
+	if (frame <= first[0]) return first.slice(1, 1 + size);
+	if (frame >= last[0]) return last.slice(1, 1 + size);
+	let k = 0;
+	while (k + 1 < sorted.length && sorted[k + 1][0] <= frame) k++;
+	const a = sorted[k];
+	const b = sorted[k + 1];
+	const u = (frame - a[0]) / Math.max(1e-9, b[0] - a[0]);
+	return a.slice(1, 1 + size).map((v, i) => v + (b[i + 1] - v) * u);
+}
 
 //#endregion
-export { ToneMappingSchema as A, evaluateKeyframes as B, Sequence as C, TextNodeSchema as D, TextAnimatorSchema as E, computeCarrierContinuity as F, mediaSignalSampler as G, hoistMattes as H, computeLayout as I, mergeAnimationTracks as K, computeLayoutSync as L, calculateSequenceTimeline as M, collectNodeOps as N, TextSpanMarkSchema as O, compositorToProgram as P, computeStaggerDelay as R, SceneTransitionTypeSchema as S, TextAnimator as T, initLayout as U, evaluateTrackAtFrame as V, lintComposition as W, MatteModeSchema as _, CarrierHandoffConfigSchema as a, Scene as b, EnvironmentFloorSchema as c, FlexNodeSchema as d, LayerAnimation as f, MaterialTypeSchema as g, LightTypeSchema as h, CameraNodeSchema as i, applyStaggerToChildren as j, TextSpanSchema as k, EnvironmentFogSchema as l, LightNodeSchema as m, BoxNodeSchema as n, ColorStopSchema as o, LayoutNodeSchema as p, sampleMediaTimeSignal as q, CameraAnimation as r, CompositorProgramSchema as s, BloomConfigSchema as t, EnvironmentPresetSchema as u, MediaNodeSchema as v, ShapeNodeSchema as w, SceneDefinitionSchema as x, Model3DNodeSchema as y, evaluateAnimationAtFrame as z };
-//# sourceMappingURL=program-BfiB9ttP.mjs.map
+export { mergeAnimationTracks as $, TextAnimator as A, collectNodeOps as B, MediaNodeSchema as C, SceneTransitionTypeSchema as D, SceneDefinitionSchema as E, ToneMappingSchema as F, computeStaggerDelay as G, computeCarrierContinuity as H, ToonShadingSchema as I, hoistMattes as J, evaluateAnimationAtFrame as K, applyStaggerToChildren as L, TextNodeSchema as M, TextSpanMarkSchema as N, Sequence as O, TextSpanSchema as P, mediaSignalSampler as Q, calculateSequenceTimeline as R, MatteModeSchema as S, Scene as T, computeLayout as U, compositorToProgram as V, computeLayoutSync as W, lintComposition as X, initLayout as Y, mappedEase as Z, LayerAnimation as _, CarrierHandoffConfigSchema as a, LightTypeSchema as b, EnvironmentFloorSchema as c, EnvironmentPresetSchema as d, numberAt as et, EnvironmentSsrSchema as f, GeometryOutlineOptionsSchema as g, FlexNodeSchema as h, CameraNodeSchema as i, vec3At as it, TextAnimatorSchema as j, ShapeNodeSchema as k, EnvironmentFogSchema as l, EnvironmentVolumetricFogSchema as m, BoxNodeSchema as n, sampleMediaTimeSignal as nt, ColorStopSchema as o, EnvironmentVolumetricFogNoiseSchema as p, evaluateTrackAtFrame as q, CameraAnimation as r, sampleTrack as rt, CompositorProgramSchema as s, BloomConfigSchema as t, sampleLayerProp as tt, EnvironmentGiSchema as u, LayoutNodeSchema as v, Model3DNodeSchema as w, MaterialTypeSchema as x, LightNodeSchema as y, collectLayersOnClock as z };
+//# sourceMappingURL=program-CMigyfso.mjs.map