framefields 2.13.1 → 2.15.0

package/dist/{src-DrP7fGJX.mjs → src-CoHAjviq.mjs}

@@ -1,12 +1,12 @@
 import { G as ProgrammaticSignal, K as Signal, Mt as frameArraySignal, N as MediaSignalRecorder, St as createVirtualMedia, pt as appendOperation, rn as mediaSourceTime, tn as mediaSourceRange, y as Effect$1, yn as resolveFrameRequest } from "./dist-C8XSqfTx.mjs";
-import { F as getPrimitiveGeometry, K as mediaDecoderCache, N as generateExtrudedTextGeometry, Q as parseSvgPathToSegments, _ as buildShapeSvgPath, bt as Path3D, p as SlugFontCache, q as parseColor$1, z as inputStore } from "./dist-DtPPPsZV.mjs";
-import { n as decodeAudioSource, o as preflightMediaTime } from "./dist-CCrYOkcc.mjs";
-import { t as FontManager } from "./fonts-k5ll8NTE.mjs";
+import { B as fractureModel, C as buildShapeSvgPath, D as createTerrainSampler, Lt as Matrix4Math, Rt as Path3D, U as getPrimitiveGeometry, Ut as createRandom, V as generateExtrudedTextGeometry, et as mediaDecoderCache, ht as scatterOnSurface, m as SlugFontCache, ot as parseSvgPathToSegments, q as inputStore, tt as parseColor$1, xt as terrainSegments } from "./dist-XqlFM2a8.mjs";
+import { n as decodeAudioSource, o as preflightMediaTime } from "./dist-COOpgG9G.mjs";
+import { t as FontManager } from "./fonts-BWYcXjyK.mjs";
 import { s as TensorPipeline } from "./dist-DgZpN6IK.mjs";
-import { E as pinNodeToObject, S as maskObject, T as pinNodeToLandmark, d as VisionNode, f as VisionRunner, i as COCO17_KEYPOINT_NAMES, l as VisionBundle, p as analyzeSequence, t as CLIP_SUBJECT, w as mergeSubjectMask } from "./src-BU6vm9sP-DdTHmCr4.mjs";
-import { G as mediaSignalSampler, K as mergeAnimationTracks, N as collectNodeOps, P as compositorToProgram, W as lintComposition, f as LayerAnimation, q as sampleMediaTimeSignal } from "./program-BfiB9ttP.mjs";
-import { C as effectFactories, H as Dither, I as ColorBalance, K as Iridescence, L as ColorKey, M as CRT, R as Contour, S as Vision, T as Ascii, Y as LayerStyle, _ as SelectiveColor, a as CustomEffect, at as Posterize, b as TileOffset, c as GradientMap, d as Levels, et as OpArt, f as Modulate, g as SSAO, h as Relight3D, ht as Vignette, i as Curves, it as Pixelate, l as HalftoneScreen, m as PBRGlass, nt as Painterly, o as DepthOfField, ot as ProceduralVFX, p as MotionBlur, pt as Toon, q as Kaleidoscope, r as Crop, s as FilmGrain, st as RGBSplit, t as ApplyLUT, u as HighPass, v as ShadowsHighlights, w as Blur, x as UnsharpMask, y as TemporalDeflicker } from "./effects-B-L3rLs6.mjs";
-import { n as renderFrameGrid, s as HeadlessMediaRenderer } from "./renderer-CO4NGvAh.mjs";
+import { C as maskObject, D as pinNodeToObject, E as pinNodeToLandmark, T as mergeSubjectMask, d as VisionNode, f as VisionRunner, g as defaultMatteBand, i as COCO17_KEYPOINT_NAMES, l as VisionBundle, p as analyzeSequence, t as CLIP_SUBJECT } from "./src-B23p_eh7-Cj6-lvV6.mjs";
+import { $ as mergeAnimationTracks, Q as mediaSignalSampler, V as compositorToProgram, X as lintComposition, _ as LayerAnimation, et as numberAt, nt as sampleMediaTimeSignal, tt as sampleLayerProp, z as collectLayersOnClock } from "./program-CMigyfso.mjs";
+import { C as effectFactories, H as Dither, I as ColorBalance, K as Iridescence, L as ColorKey, M as CRT, R as Contour, S as Vision, T as Ascii, Y as LayerStyle, _ as SelectiveColor, a as CustomEffect, at as Posterize, b as TileOffset, c as GradientMap, d as Levels, et as OpArt, f as Modulate, g as SSAO, h as Relight3D, ht as Vignette, i as Curves, it as Pixelate, l as HalftoneScreen, m as PBRGlass, nt as Painterly, o as DepthOfField, ot as ProceduralVFX, p as MotionBlur, pt as Toon, q as Kaleidoscope, r as Crop, s as FilmGrain, st as RGBSplit, t as ApplyLUT, u as HighPass, v as ShadowsHighlights, w as Blur, x as UnsharpMask, y as TemporalDeflicker } from "./effects-DlRMovU5.mjs";
+import { n as renderFrameGrid, s as HeadlessMediaRenderer } from "./renderer-tvYj306A.mjs";
 import { z, z as z$2 } from "zod";
 import path from "node:path";
 import fs from "node:fs/promises";
@@ -223,7 +223,7 @@ const sleep = (ms, signal) => new Promise((resolve$1, reject) => {
 	}, { once: true });
 });
 /** Reads (status, result) are free and idempotent, so transient failures are retried. */
-async function read(run$1, signal) {
+async function read$1(run$1, signal) {
 	for (let attempt = 1;; attempt++) try {
 		return await run$1();
 	} catch (err) {
@@ -242,7 +242,7 @@ async function submit(model, { input, abortSignal }) {
 	return data;
 }
 function status(model, { requestId, logs, abortSignal }) {
-	return read(async () => {
+	return read$1(async () => {
 		const { data } = await gatewayJson({
 			service: "queue",
 			path: requestPath(model, requestId, "/status"),
@@ -253,7 +253,7 @@ function status(model, { requestId, logs, abortSignal }) {
 	}, abortSignal);
 }
 function result(model, { requestId, abortSignal }) {
-	return read(async () => {
+	return read$1(async () => {
 		const { data } = await gatewayJson({
 			service: "queue",
 			path: requestPath(model, requestId),
@@ -610,8 +610,8 @@ function parseMarkup(markup) {
 			} else if (tagName === "accent") style.fill = "#6366f1";
 			else if (tagName === "color") style.fill = attrs.value ?? attrs.hex ?? attrs.fill;
 			else if (tagName === "size") {
-				const num$4 = parseFloat(attrs.value ?? attrs.px ?? attrs.pt ?? "0");
-				if (num$4 > 0) style.fontSize = num$4;
+				const num$5 = parseFloat(attrs.value ?? attrs.px ?? attrs.pt ?? "0");
+				if (num$5 > 0) style.fontSize = num$5;
 			} else if (tagName === "mark") {
 				style.mark = {
 					background: attrs.bg ?? attrs.background ?? "#6366f133",
@@ -1332,12 +1332,170 @@ function translatePath(d, dx, dy) {
 	return out.join("");
 }
 
+//#endregion
+//#region src/retarget.ts
+/**
+* Pose retargeting: a performer's 2D pose (vision keypoints, or any source
+* of named points) drives a 3D character's bones. Each bone is aimed along
+* its segment in the picture (shoulder → elbow, hip → knee, …), parents
+* first, so the character copies the performer's silhouette at its own
+* proportions. Aims run after clips and `pose`, before `lookAt` and `ik`,
+* so clips can carry what the camera can't see and IK can plant the feet.
+*
+* ```ts
+* const dancer = comp.vision("dance.mp4").person.place({ width: W, height: H });
+* Layer.glb("robot.glb", { aim: retargetPose(dancer, { rig: "mixamo" }) });
+* ```
+*
+* The picture has no depth: limbs swing in the plane facing the camera.
+*/
+/** Joint names of common rigs. */
+const RIG_PRESETS = {
+	mixamo: {
+		spine: "Spine",
+		neck: "Neck",
+		leftUpperArm: "LeftArm",
+		leftLowerArm: "LeftForeArm",
+		rightUpperArm: "RightArm",
+		rightLowerArm: "RightForeArm",
+		leftUpperLeg: "LeftUpLeg",
+		leftLowerLeg: "LeftLeg",
+		rightUpperLeg: "RightUpLeg",
+		rightLowerLeg: "RightLeg"
+	},
+	humanoid: {
+		spine: "Spine",
+		neck: "Neck",
+		leftUpperArm: "LeftUpperArm",
+		leftLowerArm: "LeftLowerArm",
+		rightUpperArm: "RightUpperArm",
+		rightLowerArm: "RightLowerArm",
+		leftUpperLeg: "LeftUpperLeg",
+		leftLowerLeg: "LeftLowerLeg",
+		rightUpperLeg: "RightUpperLeg",
+		rightLowerLeg: "RightLowerLeg"
+	},
+	rigify: {
+		spine: "spine",
+		neck: "neck",
+		leftUpperArm: "upper_arm.L",
+		leftLowerArm: "forearm.L",
+		rightUpperArm: "upper_arm.R",
+		rightLowerArm: "forearm.R",
+		leftUpperLeg: "thigh.L",
+		leftLowerLeg: "shin.L",
+		rightUpperLeg: "thigh.R",
+		rightLowerLeg: "shin.R"
+	}
+};
+/** Each bone's segment in the picture, parents first. */
+const SEGMENTS = [
+	[
+		"spine",
+		["leftHip", "rightHip"],
+		["leftShoulder", "rightShoulder"]
+	],
+	[
+		"neck",
+		["leftShoulder", "rightShoulder"],
+		"nose"
+	],
+	[
+		"leftUpperArm",
+		"leftShoulder",
+		"leftElbow"
+	],
+	[
+		"leftLowerArm",
+		"leftElbow",
+		"leftWrist"
+	],
+	[
+		"rightUpperArm",
+		"rightShoulder",
+		"rightElbow"
+	],
+	[
+		"rightLowerArm",
+		"rightElbow",
+		"rightWrist"
+	],
+	[
+		"leftUpperLeg",
+		"leftHip",
+		"leftKnee"
+	],
+	[
+		"leftLowerLeg",
+		"leftKnee",
+		"leftAnkle"
+	],
+	[
+		"rightUpperLeg",
+		"rightHip",
+		"rightKnee"
+	],
+	[
+		"rightLowerLeg",
+		"rightKnee",
+		"rightAnkle"
+	]
+];
+const mirrored = (name) => name.startsWith("left") ? `right${name.slice(4)}` : name.startsWith("right") ? `left${name.slice(5)}` : name;
+/** A keypoint, or the midpoint of two, with the lesser visibility. */
+function read(source, p, frame, mirror) {
+	const name = (n) => mirror ? mirrored(n) : n;
+	if (typeof p === "string") return source.point(name(p), frame);
+	const a = source.point(name(p[0]), frame);
+	const b = source.point(name(p[1]), frame);
+	return {
+		x: (a.x + b.x) / 2,
+		y: (a.y + b.y) / 2,
+		visibility: Math.min(a.visibility, b.visibility)
+	};
+}
+const smoothstep$1 = (lo, hi, v) => {
+	const t = Math.min(1, Math.max(0, (v - lo) / (hi - lo)));
+	return t * t * (3 - 2 * t);
+};
+/**
+* Aim constraints that make a character copy `source`'s pose: put them on
+* a glTF model's `aim`. Bones whose joints the rig map doesn't name, or
+* whose keypoints the vision isn't sure of, keep the animated pose.
+*/
+function retargetPose(source, options = {}) {
+	const rig$1 = typeof options.rig === "object" ? options.rig : RIG_PRESETS[options.rig ?? "mixamo"];
+	const only = options.bones ? new Set(options.bones) : void 0;
+	const mirror = options.mirror ?? false;
+	const lo = options.minVisibility ?? .3;
+	return SEGMENTS.filter(([bone]) => rig$1[bone] && (!only || only.has(bone))).map(([bone, from, to]) => ({
+		joint: rig$1[bone],
+		direction: (frame) => {
+			const a = read(source, from, frame, mirror);
+			const b = read(source, to, frame, mirror);
+			return [
+				b.x - a.x,
+				b.y - a.y,
+				0
+			];
+		},
+		weight: { get: (ctx) => {
+			const clock = ctx;
+			const a = read(source, from, clock.frame, mirror);
+			const b = read(source, to, clock.frame, mirror);
+			return smoothstep$1(lo, lo + .2, Math.min(a.visibility, b.visibility)) * numberAt(options.weight, clock, 1);
+		} }
+	}));
+}
+
 //#endregion
 //#region src/clip-vision.ts
 /** Frames looked back over to bridge a gap where the person is lost. */
 const HOLD = 24;
 const CACHE_VERSION = 1;
 const DEPTH_CACHE_VERSION = 1;
+const MATTE_CACHE_VERSION = 1;
+const MATTE_MODEL = "vitmatte-s";
 const DEPTH_MODEL = "depth-anything-v2-s";
 /** Depth frames held in memory when they also live on disk (each is about 1 MB). */
 const DEPTH_MEMORY = 48;
@@ -1345,7 +1503,7 @@ let visionSam;
 let clipVisionIds = 0;
 /** SAM ships in its own chunk, loaded only when a clip asks for `sam2` or `sam3`. */
 function loadVisionSam() {
-	visionSam ??= import("./dist-B_rSWeOz.mjs");
+	visionSam ??= import("./dist-umQOWz0a.mjs");
 	return visionSam;
 }
 /**
@@ -1402,6 +1560,10 @@ var ClipVision = class {
 	subjects = /* @__PURE__ */ new Map();
 	wantSubjects = false;
 	subjectsLoaded;
+	/** Soft alpha per source frame (`matting`); null when the frame holds no subject. */
+	mattes = /* @__PURE__ */ new Map();
+	mattesLoaded;
+	unsavedMattes = 0;
 	/** Depth per source frame; null when the frame did not decode. Bounded when on disk. */
 	depths = /* @__PURE__ */ new Map();
 	/** Source frames whose depth is on disk. */
@@ -1441,7 +1603,7 @@ var ClipVision = class {
 		this.trimStartSec = options.trimStartSec ?? 0;
 		this.smoothing = Math.max(0, Math.round(options.smoothing ?? (options.sam2 || options.sam3 ? 0 : 2)));
 		this.cell = Math.max(1, Math.round(options.maskCell ?? 8));
-		if (options.sam2 || options.sam3) this.wantSubjects = true;
+		if (options.sam2 || options.sam3 || this.tracksMatting) this.wantSubjects = true;
 	}
 	/** @internal Explicit selections must never fall back to another detected subject. */
 	get exact() {
@@ -1538,9 +1700,11 @@ var ClipVision = class {
 		if (s === null || !this.sourceWidth) return null;
 		const width = this.sourceWidth;
 		const height = this.sourceHeight;
+		const mask = this.alpha(sourceFrame, s);
+		if (!mask) return void 0;
 		return {
 			category: s.category,
-			mask: subjectAlpha(s, width * height),
+			mask,
 			width,
 			height,
 			area: s.area,
@@ -1582,6 +1746,34 @@ var ClipVision = class {
 	get tracksMask() {
 		return this.options.mask ?? !this.tracksDepth;
 	}
+	/** Whether subjects are matted to soft alpha. */
+	get tracksMatting() {
+		return this.options.matting !== void 0 && this.options.matting !== false;
+	}
+	get matteSettings() {
+		const m = this.options.matting;
+		if (!m) return void 0;
+		const o = m === true ? {} : m;
+		return {
+			band: o.band ?? (this.sourceWidth ? defaultMatteBand(this.sourceWidth, this.sourceHeight) : 0),
+			resolution: o.resolution ?? 1024
+		};
+	}
+	/**
+	* A stored subject's alpha at a source frame: the matte when the clip mattes
+	* (undefined until matted), else the mask. With `id`, that track only.
+	*/
+	alpha(c, stored, id) {
+		const size$1 = this.sourceWidth * this.sourceHeight;
+		if (!this.tracksMatting) return subjectAlpha(stored, size$1, id);
+		const matte = this.mattes.get(c);
+		if (!matte) return void 0;
+		const alpha = decodeRuns(matte.alpha, size$1);
+		if (id === void 0 || !matte.labels) return alpha;
+		const labels = decodeRuns(matte.labels, size$1);
+		for (let i = 0; i < size$1; i++) if (labels[i] !== id) alpha[i] = 0;
+		return alpha;
+	}
 	/** Whether frames carry relative depth. */
 	get tracksDepth() {
 		return this.options.depth === true;
@@ -1636,7 +1828,7 @@ var ClipVision = class {
 		return [Math.max(0, a - HOLD - this.smoothing), Math.max(0, b + this.smoothing)];
 	}
 	analysed(c) {
-		return this.analysedSubject(c) && (!this.tracksDepth || this.hasDepth(c));
+		return this.analysedSubject(c) && (!this.tracksDepth || this.hasDepth(c)) && (!this.tracksMatting || this.mattes.has(c));
 	}
 	/** Everything but depth, which is a pass of its own. */
 	analysedSubject(c) {
@@ -1660,6 +1852,11 @@ var ClipVision = class {
 			await this.subjectsLoaded;
 		}
 		if (this.tracksDepth) await this.computeDepth(from, to);
+		await this.computeSubjects(from, to);
+		if (this.tracksMatting) await this.computeMattes(from, to);
+	}
+	/** Pose, silhouette and subject of every frame in `from…to` not analysed yet. */
+	async computeSubjects(from, to) {
 		let missing = false;
 		for (let c = from; c <= to; c++) if (!this.analysedSubject(c)) missing = true;
 		if (!missing) return;
@@ -1738,6 +1935,51 @@ var ClipVision = class {
 		});
 		return this.runner;
 	}
+	/**
+	* The soft alpha of every subject in `from…to` not matted yet: one
+	* ViTMatte pass per frame over every track's edge. Prompted label maps grow
+	* into the soft edge, so each track keeps its own alpha.
+	*/
+	async computeMattes(from, to) {
+		if (!this.sourceWidth) return;
+		this.mattesLoaded ??= this.loadMattes();
+		await this.mattesLoaded;
+		let decoder;
+		for (let c = from; c <= to; c++) {
+			if (this.mattes.has(c)) continue;
+			const stored = this.subjects.get(c);
+			if (stored === void 0) continue;
+			if (stored === null) {
+				this.mattes.set(c, null);
+				continue;
+			}
+			decoder ??= this.decoder();
+			const image = await decodedPixels(await decoder.getFrame(c / this.fps));
+			if (!image) {
+				this.mattes.set(c, null);
+				continue;
+			}
+			const size$1 = image.width * image.height;
+			const values = decodeRuns(stored, size$1);
+			const hard = stored.scores ? values.map((label) => label ? 255 : 0) : values;
+			const matte = await this.visionRunner().refineMatte(image, hard, this.matteSettings);
+			let labels;
+			if (stored.scores) {
+				labels = new Uint8Array(size$1);
+				for (let i = 0; i < size$1; i++) {
+					const nearest = matte.nearest[i];
+					if (matte.mask[i] && nearest >= 0) labels[i] = values[nearest];
+				}
+			}
+			this.mattes.set(c, {
+				alpha: encodeRuns(matte.mask),
+				...labels && { labels: encodeRuns(labels) }
+			});
+			this.signalMaskFrame = -1;
+			if (++this.unsavedMattes >= 24) await this.saveMattes();
+		}
+		if (this.unsavedMattes > 0) await this.saveMattes();
+	}
 	/** Depth of every source frame in `from…to` not analysed yet, saved one file per frame. */
 	async computeDepth(from, to) {
 		const dir = await this.depthCacheDir();
@@ -1996,11 +2238,13 @@ var ClipVision = class {
 		if (!this.results.has(c) || !this.sourceWidth) return void 0;
 		const stored = this.subjects.get(c);
 		const size$1 = this.sourceWidth * this.sourceHeight;
-		const data = stored ? subjectAlpha(stored, size$1, id) : new Uint8Array(size$1);
+		const alpha = stored ? this.alpha(c, stored, id) : new Uint8Array(size$1);
+		if (!alpha) return void 0;
+		const data = alpha;
 		let area$1 = stored?.area ?? 0;
 		if (id !== void 0 && stored?.scores) {
 			area$1 = 0;
-			for (const alpha of data) if (alpha) area$1++;
+			for (const alpha$1 of data) if (alpha$1) area$1++;
 		}
 		const mask = {
 			category: stored?.category ?? this.samCategory(),
@@ -2232,6 +2476,55 @@ var ClipVision = class {
 			}
 		} catch {}
 	}
+	/**
+	* Mattes live beside the subjects they refine, keyed by the matting model
+	* and settings, so toggling matting never recomputes the masks.
+	*/
+	async mattesPath() {
+		const file = await this.cachePath();
+		const node = await nodeModules();
+		const settings = this.matteSettings;
+		if (!file || !node || !settings) return null;
+		const hash = node.crypto.createHash("sha256").update(JSON.stringify([
+			MATTE_CACHE_VERSION,
+			MATTE_MODEL,
+			settings.band,
+			settings.resolution
+		])).digest("hex").slice(0, 12);
+		return file.replace(/\.json$/, `.matte-${hash}.json`);
+	}
+	async loadMattes() {
+		const file = await this.mattesPath();
+		if (!file) return;
+		try {
+			const fs$1 = await import("node:fs");
+			if (!fs$1.existsSync(file)) return;
+			const json = JSON.parse(fs$1.readFileSync(file, "utf8"));
+			if (json.width !== this.sourceWidth || json.height !== this.sourceHeight) return;
+			for (const [c, m] of Object.entries(json.frames)) this.mattes.set(Number(c), m && {
+				alpha: fromStoredRuns(m.alpha),
+				...m.labels && { labels: fromStoredRuns(m.labels) }
+			});
+		} catch {}
+	}
+	async saveMattes() {
+		this.unsavedMattes = 0;
+		const file = await this.mattesPath();
+		if (!file || !this.sourceWidth) return;
+		const frames = {};
+		for (const [c, m] of this.mattes) frames[c] = m && {
+			alpha: toStoredRuns(m.alpha),
+			...m.labels && { labels: toStoredRuns(m.labels) }
+		};
+		const fs$1 = await import("node:fs");
+		const tmp = `${file}.${process.pid}.tmp`;
+		fs$1.writeFileSync(tmp, JSON.stringify({
+			width: this.sourceWidth,
+			height: this.sourceHeight,
+			frames
+		}));
+		fs$1.renameSync(tmp, file);
+	}
 	async saveSubjects() {
 		this.unsavedSubjects = 0;
 		const file = await this.subjectsPath();
@@ -2310,16 +2603,24 @@ var PersonTrack = class PersonTrack {
 			visibility: a[2] + (b[2] - a[2]) * u
 		};
 	}
+	/**
+	* Aim constraints that make a 3D character copy this person's pose, for
+	* a glTF model's `aim`: `Layer.glb(src, { aim: person.retarget({ rig: "mixamo" }) })`.
+	* Place the person first (`place()`), so directions read in composition px.
+	*/
+	retarget(options) {
+		return retargetPose(this, options);
+	}
 	/** Signals for a keypoint, for `.signal("x", …)`; read while rendering. */
 	signals(name) {
-		const read$1 = (axis) => Signal.builder({
+		const read$2 = (axis) => Signal.builder({
 			type: "custom",
 			fn: (ctx) => this.point(name, ctx.frame)[axis]
 		});
 		return {
-			x: read$1("x"),
-			y: read$1("y"),
-			visibility: read$1("visibility")
+			x: read$2("x"),
+			y: read$2("y"),
+			visibility: read$2("visibility")
 		};
 	}
 	/**
@@ -2358,14 +2659,14 @@ var PersonTrack = class PersonTrack {
 		const t = this.transform();
 		const cx = (x - t.ox) / t.sx / cell - .5;
 		const cy = (y - t.oy) / t.sy / cell - .5;
-		const read$1 = (gx, gy) => gx < 0 || gy < 0 || gx >= w || gy >= h ? 0 : grid[gy * w + gx];
+		const read$2 = (gx, gy) => gx < 0 || gy < 0 || gx >= w || gy >= h ? 0 : grid[gy * w + gx];
 		const bil = (px, py) => {
 			const x0 = Math.floor(px);
 			const y0 = Math.floor(py);
 			const ux = px - x0;
 			const uy = py - y0;
-			const a = read$1(x0, y0) + (read$1(x0 + 1, y0) - read$1(x0, y0)) * ux;
-			return a + (read$1(x0, y0 + 1) + (read$1(x0 + 1, y0 + 1) - read$1(x0, y0 + 1)) * ux - a) * uy;
+			const a = read$2(x0, y0) + (read$2(x0 + 1, y0) - read$2(x0, y0)) * ux;
+			return a + (read$2(x0, y0 + 1) + (read$2(x0 + 1, y0 + 1) - read$2(x0, y0 + 1)) * ux - a) * uy;
 		};
 		return {
 			alpha: bil(cx, cy),
@@ -2465,6 +2766,19 @@ function downsampleMean(src, w, h, cell, dst, mw, mh) {
 		dst[my * mw + mx] = n ? Math.round(sum / n) : 0;
 	}
 }
+function toStoredRuns(runs) {
+	return {
+		values: Buffer.from(runs.values).toString("base64"),
+		lengths: Buffer.from(runs.lengths.buffer, runs.lengths.byteOffset, runs.lengths.byteLength).toString("base64")
+	};
+}
+function fromStoredRuns(stored) {
+	const lengths = Buffer.from(stored.lengths, "base64");
+	return {
+		values: new Uint8Array(Buffer.from(stored.values, "base64")),
+		lengths: new Uint32Array(lengths.buffer.slice(lengths.byteOffset, lengths.byteOffset + lengths.byteLength))
+	};
+}
 /** A mask as (value, run length) pairs: long flat runs with soft edges. */
 function encodeRuns(mask) {
 	let runs = 0;
@@ -2815,6 +3129,10 @@ var WorldCore = class {
 	forces = [];
 	impulses = [];
 	fields = [];
+	/** Run after each simulated frame with the pairs that started touching in it. */
+	stepHooks = [];
+	/** Run once the whole simulation has finished (not in live worlds). */
+	simulatedHooks = [];
 	worldRecording;
 	allCollisions = [];
 	/** No more bodies, joints or forces: the world has started (or finished). */
@@ -2869,6 +3187,7 @@ var WorldCore = class {
 	*/
 	live(comp, options = {}) {
 		if (this.locked) throw new Error("Physics: live() must come before simulate() or reading any body signal.");
+		if (this.simulatedHooks.length) throw new Error("Physics: fracture() needs the whole run up front; use simulate() instead of live().");
 		this.locked = true;
 		this.liveMode = true;
 		const prepare = async (frame) => {
@@ -2947,6 +3266,7 @@ var WorldCore = class {
 		st.freed = true;
 		this.sim.free();
 		for (const body of this.bodies) this.bind(body);
+		for (const hook of this.simulatedHooks) hook();
 	}
 	/** Records frame 0 and sets every channel to it, so frames not simulated yet hold the start pose. */
 	begin() {
@@ -3085,6 +3405,7 @@ var WorldCore = class {
 			if (level > loudest) loudest = level;
 		}
 		this.worldRecording.channel("impact")[frame] = loudest;
+		for (const hook of this.stepHooks) hook(f, pairs);
 		st.current = f;
 	}
 	bind(body) {
@@ -3184,15 +3505,15 @@ var Particles = class extends Effect$1 {
 	}
 	particleFrame(frame, fps) {
 		const o = this.options;
-		const read$1 = (d, fallback) => d === void 0 ? fallback : sampleDriver(d, frame, fps);
+		const read$2 = (d, fallback) => d === void 0 ? fallback : sampleDriver(d, frame, fps);
 		const layerFrame = frame - (o.startFrame ?? 0);
 		const burst = (o.emitter?.bursts ?? []).filter((b) => Math.round(b.frame) === layerFrame).reduce((n, b) => n + b.count, 0);
 		const g = o.gravity;
-		const gravity = Array.isArray(g) ? [read$1(g[0], 0), read$1(g[1], 0)] : [0, read$1(g, 0)];
+		const gravity = Array.isArray(g) ? [read$2(g[0], 0), read$2(g[1], 0)] : [0, read$2(g, 0)];
 		let push = null;
 		if (o.push) push = {
-			strength: read$1(o.push.strength, 6e3),
-			sweep: read$1(o.push.sweep, 6e4),
+			strength: read$2(o.push.strength, 6e3),
+			sweep: read$2(o.push.sweep, 6e4),
 			mask: o.push.person.silhouetteGrid(frame),
 			previous: o.push.person.silhouetteGrid(Math.max(0, frame - 1))
 		};
@@ -3216,19 +3537,19 @@ var Particles = class extends Effect$1 {
 		}
 		return {
 			...emitter && { emitter },
-			rate: read$1(o.emitter?.rate, 1e3),
+			rate: read$2(o.emitter?.rate, 1e3),
 			burst,
 			gravity,
-			drag: read$1(o.drag, .4),
+			drag: read$2(o.drag, .4),
 			noise: {
-				strength: read$1(o.noise?.strength, 0),
+				strength: read$2(o.noise?.strength, 0),
 				scale: o.noise?.scale ?? 300,
 				speed: o.noise?.speed ?? .3
 			},
 			attractors: (o.attractors ?? []).map((a) => ({
-				x: read$1(a.x, 0),
-				y: read$1(a.y, 0),
-				strength: read$1(a.strength, 0),
+				x: read$2(a.x, 0),
+				y: read$2(a.y, 0),
+				strength: read$2(a.strength, 0),
 				radius: a.radius ?? 200
 			})),
 			push
@@ -3236,6 +3557,172 @@ var Particles = class extends Effect$1 {
 	}
 };
 
+//#endregion
+//#region src/procedural3d.ts
+/** Where a model node's mesh sits: its static transform. */
+function staticMatrix(n) {
+	const rad = Math.PI / 180;
+	const s = n.scale ?? 1;
+	let m = Matrix4Math.translate(n.x ?? 0, n.y ?? 0, n.z ?? 0);
+	if (n.rotateZ) m = Matrix4Math.multiply(m, Matrix4Math.rotateZ(n.rotateZ * rad));
+	if (n.rotateY) m = Matrix4Math.multiply(m, Matrix4Math.rotateY(n.rotateY * rad));
+	if (n.rotateX) m = Matrix4Math.multiply(m, Matrix4Math.rotateX(n.rotateX * rad));
+	return Matrix4Math.multiply(m, Matrix4Math.scale(s * (n.scaleX ?? 1), s * (n.scaleY ?? 1), s * (n.scaleZ ?? 1)));
+}
+function defineHidden(target$1, values) {
+	for (const [key, value] of Object.entries(values)) Object.defineProperty(target$1, key, {
+		value,
+		enumerable: false,
+		configurable: true
+	});
+}
+function surfaceHelpers(sampler, o) {
+	const s = o.scale ?? 1;
+	const sx = s * (o.scaleX ?? 1);
+	const sy = s * (o.scaleY ?? 1);
+	const sz = s * (o.scaleZ ?? 1);
+	const local = (x, z$3) => [(x - (o.x ?? 0)) / sx, (z$3 - (o.z ?? 0)) / sz];
+	return {
+		heightAt: (x, z$3) => (o.y ?? 0) + sampler.heightAt(...local(x, z$3)) * sy,
+		elevationAt: (x, z$3) => sampler.elevationAt(...local(x, z$3)),
+		normalAt(x, z$3) {
+			const n = sampler.normalAt(...local(x, z$3));
+			const m = [
+				n[0] / sx,
+				n[1] / sy,
+				n[2] / sz
+			];
+			const len = Math.hypot(m[0], m[1], m[2]) || 1;
+			return [
+				m[0] / len,
+				m[1] / len,
+				m[2] / len
+			];
+		}
+	};
+}
+/** Procedural terrain (see `Layer3D.terrain`). */
+function terrain3d(options) {
+	const { heightFn, ...o } = options;
+	const geometry = {
+		type: "terrain",
+		width: o.width,
+		depth: o.depth,
+		height: o.height,
+		segments: o.segments,
+		noise: o.noise,
+		heights: o.heights,
+		overhangWarp: o.overhangWarp,
+		colorByElevation: o.colorByElevation,
+		flatShaded: o.flatShaded,
+		base: o.base
+	};
+	if (heightFn) {
+		const [cols, rows] = terrainSegments(geometry);
+		const heights = [];
+		for (let j = 0; j <= rows; j++) for (let i = 0; i <= cols; i++) heights.push(heightFn(i / cols, j / rows));
+		geometry.heights = heights;
+	}
+	const node = primitiveNode("terrain", geometry, o);
+	defineHidden(node, surfaceHelpers(createTerrainSampler(geometry), options));
+	return node;
+}
+/** A signed-distance sculpture (see `Layer3D.sdf`). */
+function sdf3d(options) {
+	return primitiveNode("sdf", {
+		type: "sdf",
+		primitives: options.primitives,
+		bounds: options.bounds,
+		resolution: options.resolution,
+		flatShaded: options.flatShaded
+	}, options);
+}
+const SURFACE_KEYS = [
+	"x",
+	"y",
+	"z",
+	"rotateX",
+	"rotateY",
+	"rotateZ",
+	"scale",
+	"scaleX",
+	"scaleY",
+	"scaleZ",
+	"primitive3d",
+	"src",
+	"modelFormat",
+	"center",
+	"normalizeSize"
+];
+/** What the renderer rebuilds and places the surface from. */
+function surfaceSpec(surface) {
+	const out = {};
+	for (const k of SURFACE_KEYS) if (surface[k] !== void 0) out[k] = surface[k];
+	if (!surface.primitive3d && !surface.src && surface.modelData) out.modelData = surface.modelData;
+	return out;
+}
+/** The surface's mesh when it is already in memory (primitives, terrain, SDF). */
+function surfaceModel(surface) {
+	const data = surface.modelData;
+	if (data && "meshes" in data) return data;
+	if (surface.primitive3d) return getPrimitiveGeometry(surface.primitive3d);
+}
+const SCATTER_KEYS = [
+	"count",
+	"minDistance",
+	"seed",
+	"slopeRange",
+	"elevationRange",
+	"alignToNormal",
+	"scaleRange",
+	"randomYaw",
+	"exclude",
+	"sink"
+];
+/** Instances scattered on a surface (see `Layer3D.scatter`). */
+function scatter3d(options) {
+	const { surface, wind, ...rest } = options;
+	const spec$1 = { surface: surfaceSpec(surface) };
+	const instanceOptions = { ...rest };
+	for (const k of SCATTER_KEYS) {
+		if (rest[k] !== void 0) spec$1[k] = rest[k];
+		delete instanceOptions[k];
+	}
+	const node = Layer3D.instances(instanceOptions);
+	const target$1 = node;
+	target$1.scatter3d = spec$1;
+	if (wind) target$1.wind = wind;
+	defineHidden(node, { points: () => {
+		const model = surfaceModel(surface);
+		if (!model) return [];
+		return scatterOnSurface({
+			model,
+			matrix: staticMatrix(surface)
+		}, spec$1).points;
+	} });
+	return node;
+}
+/**
+* Share of a scatter's surface its slope / altitude filters keep (for
+* `lint`), or undefined when the surface is a file not loaded yet.
+*/
+function scatterCoverage(spec$1) {
+	const surface = spec$1.surface;
+	const model = surfaceModel(surface);
+	if (!model) return void 0;
+	return scatterOnSurface({
+		model,
+		matrix: staticMatrix(surface)
+	}, {
+		...spec$1,
+		count: 0
+	}).acceptedArea;
+}
+/** `texture` on a Layer3D mesh: an image path, or any layer drawn each frame. */
+function textureLayerOf(texture, image) {
+	return { node: typeof texture === "string" ? image(texture) : texture };
+}
+
 //#endregion
 //#region src/swarm3d.ts
 function createSwarm3D(options) {
@@ -3302,6 +3789,8 @@ function createSwarm3D(options) {
 //#endregion
 //#region src/shapes3d.ts
 const MATERIAL_KEYS = [
+	"toon",
+	"outline",
 	"material",
 	"shininess",
 	"roughness",
@@ -3315,7 +3804,22 @@ const MATERIAL_KEYS = [
 	"envIntensity",
 	"emissive",
 	"emissiveIntensity",
-	"castShadow"
+	"castShadow",
+	"clearcoat",
+	"clearcoatRoughness",
+	"anisotropy",
+	"anisotropyRotation",
+	"subsurface",
+	"subsurfaceColor",
+	"sheen",
+	"sheenColor",
+	"sheenRoughness",
+	"iridescence",
+	"iridescenceThickness",
+	"iridescenceIor",
+	"triplanar",
+	"triplanarScale",
+	"triplanarSharpness"
 ];
 /** The material and surface options that were actually given. */
 function materialProps(o) {
@@ -3332,6 +3836,7 @@ function normalizePathSpec(input) {
 	if (input instanceof Path3D) return input.getPoints(96);
 	return input;
 }
+/** A Layer3D mesh node built from a procedural geometry spec. */
 function primitiveNode(prefix, geometry, o) {
 	const spec$1 = Object.fromEntries(Object.entries({
 		...geometry,
@@ -3349,9 +3854,9 @@ function primitiveNode(prefix, geometry, o) {
 		x: o.x ?? 0,
 		y: o.y ?? 0,
 		z: o.z ?? 0,
-		rotateX: o.rotateX ?? 0,
-		rotateY: o.rotateY ?? 0,
-		rotateZ: o.rotateZ ?? 0,
+		rotateX: o.rotateX ?? o.rotationX ?? 0,
+		rotateY: o.rotateY ?? o.rotationY ?? 0,
+		rotateZ: o.rotateZ ?? o.rotationZ ?? 0,
 		scale: o.scale ?? 1,
 		scaleX: o.scaleX ?? 1,
 		scaleY: o.scaleY ?? 1,
@@ -3368,7 +3873,9 @@ function primitiveNode(prefix, geometry, o) {
 		twoSided: o.twoSided ?? false,
 		wireframe: o.wireframe,
 		startFrame: o.startFrame,
-		durationFrames: o.durationFrames
+		durationFrames: o.durationFrames,
+		...o.wind && { wind: o.wind },
+		...o.texture !== void 0 && { textureLayer: textureLayerOf(o.texture, (src) => Layer.image(src)) }
 	});
 }
 /**
@@ -3426,7 +3933,10 @@ const Layer3D = {
 				if (options.roughness !== void 0 && node.roughness === void 0) node.roughness = options.roughness;
 				if (options.metallic !== void 0 && node.metallic === void 0) node.metallic = options.metallic;
 				if (options.ambientIntensity !== void 0 && node.ambientIntensity === void 0) node.ambientIntensity = options.ambientIntensity;
-				Object.assign(node, faceProps);
+				Object.assign(node, {
+					...materialProps(options),
+					...materialProps(node)
+				}, faceProps);
 				return node;
 			}
 			const cfg = typeof input === "string" ? { background: input } : input ?? { background: defaultColor };
@@ -3519,9 +4029,9 @@ const Layer3D = {
 			height: h,
 			is3D: true,
 			transformStyle: "preserve-3d",
-			rotateX: options.rotateX ?? 0,
-			rotateY: options.rotateY ?? 0,
-			rotateZ: options.rotateZ ?? 0,
+			rotateX: options.rotateX ?? options.rotationX ?? 0,
+			rotateY: options.rotateY ?? options.rotationY ?? 0,
+			rotateZ: options.rotateZ ?? options.rotationZ ?? 0,
 			opacity: options.opacity ?? 1,
 			background: "transparent",
 			children: faces
@@ -3557,18 +4067,20 @@ const Layer3D = {
 			height: options.itemHeight ?? 200,
 			is3D: true,
 			transformStyle: "preserve-3d",
-			rotateX: options.rotateX ?? 0,
-			rotateY: options.rotateY ?? 0,
-			rotateZ: options.rotateZ ?? 0,
+			rotateX: options.rotateX ?? options.rotationX ?? 0,
+			rotateY: options.rotateY ?? options.rotationY ?? 0,
+			rotateZ: options.rotateZ ?? options.rotationZ ?? 0,
 			opacity: options.opacity ?? 1,
 			background: "transparent",
 			children: transformedItems
 		}), { items: transformedItems });
 	},
-	prism(options) {
-		const n = Math.max(3, Math.round(options.sides));
+	prism(options = {}) {
+		const n = Math.max(3, Math.round(options.sides ?? 6));
+		const radius = options.radius ?? 60;
+		const height = options.height ?? 100;
 		if (options.sideConfigs && options.sideConfigs.length > 0) {
-			const { radius, height, twoSided = true } = options;
+			const { twoSided = true } = options;
 			const sideWidth = 2 * radius * Math.tan(Math.PI / n);
 			const angleStep = 360 / n;
 			const panels = [];
@@ -3630,20 +4142,23 @@ const Layer3D = {
 				height,
 				is3D: true,
 				transformStyle: "preserve-3d",
-				rotateX: options.rotateX ?? 0,
-				rotateY: options.rotateY ?? 0,
-				rotateZ: options.rotateZ ?? 0,
+				rotateX: options.rotateX ?? options.rotationX ?? 0,
+				rotateY: options.rotateY ?? options.rotationY ?? 0,
+				rotateZ: options.rotateZ ?? options.rotationZ ?? 0,
 				opacity: options.opacity ?? 1,
 				background: "transparent",
 				children: panels
-			}), { faces: panels });
+			}), {
+				faces: panels,
+				items: panels
+			});
 		}
 		const modelNode = primitiveNode("prism", {
 			type: "cylinder",
-			radius: options.radius,
-			radiusTop: options.radiusTop ?? options.radius,
-			radiusBottom: options.radiusBottom ?? options.radius,
-			height: options.height,
+			radius,
+			radiusTop: options.radiusTop ?? options.topRadius ?? radius,
+			radiusBottom: options.radiusBottom ?? options.bottomRadius ?? radius,
+			height,
 			segments: n,
 			openEnded: options.openEnded ?? false,
 			flatShaded: options.flatShaded ?? true
@@ -3657,14 +4172,14 @@ const Layer3D = {
 			items: [modelNode]
 		});
 	},
-	pyramid(options) {
+	pyramid(options = {}) {
 		const n = Math.max(3, Math.round(options.sides ?? 4));
 		return primitiveNode("pyramid", {
 			type: "cylinder",
 			radius: options.radius ?? 60,
-			radiusTop: options.radiusTop ?? 0,
+			radiusTop: options.radiusTop ?? options.topRadius ?? 0,
 			radiusBottom: options.radius ?? 60,
-			height: options.height,
+			height: options.height ?? 100,
 			segments: n,
 			openEnded: options.openEnded ?? false,
 			flatShaded: options.flatShaded ?? true
@@ -3685,9 +4200,9 @@ const Layer3D = {
 			z: options.z ?? 0,
 			is3D: true,
 			twoSided: options.twoSided ?? true,
-			rotateX: options.rotateX ?? 0,
-			rotateY: options.rotateY ?? 0,
-			rotateZ: options.rotateZ ?? 0,
+			rotateX: options.rotateX ?? options.rotationX ?? 0,
+			rotateY: options.rotateY ?? options.rotationY ?? 0,
+			rotateZ: options.rotateZ ?? options.rotationZ ?? 0,
 			background: options.background ?? "#3b82f6",
 			borderRadius: options.borderRadius ?? 0,
 			opacity: options.opacity ?? 1,
@@ -3741,9 +4256,9 @@ const Layer3D = {
 			z: options.z ?? 0,
 			is3D: true,
 			transformStyle: "preserve-3d",
-			rotateX: options.rotateX ?? 90,
-			rotateY: options.rotateY ?? 0,
-			rotateZ: options.rotateZ ?? 0,
+			rotateX: options.rotateX ?? options.rotationX ?? 90,
+			rotateY: options.rotateY ?? options.rotationY ?? 0,
+			rotateZ: options.rotateZ ?? options.rotationZ ?? 0,
 			background: "transparent",
 			opacity: options.opacity ?? 1,
 			children: lines
@@ -3762,9 +4277,9 @@ const Layer3D = {
 			z: options.z ?? 0,
 			is3D: true,
 			twoSided: options.twoSided ?? true,
-			rotateX: options.rotateX ?? 0,
-			rotateY: options.rotateY ?? 0,
-			rotateZ: options.rotateZ ?? 0,
+			rotateX: options.rotateX ?? options.rotationX ?? 0,
+			rotateY: options.rotateY ?? options.rotationY ?? 0,
+			rotateZ: options.rotateZ ?? options.rotationZ ?? 0,
 			fontSize: options.fontSize ?? 48,
 			fontFamily: options.fontFamily,
 			fontWeight: options.fontWeight ?? "bold",
@@ -3820,9 +4335,9 @@ const Layer3D = {
 			x: options.x ?? 0,
 			y: options.y ?? 0,
 			z: options.z ?? 0,
-			rotateX: options.rotateX ?? 0,
-			rotateY: options.rotateY ?? 0,
-			rotateZ: options.rotateZ ?? 0,
+			rotateX: options.rotateX ?? options.rotationX ?? 0,
+			rotateY: options.rotateY ?? options.rotationY ?? 0,
+			rotateZ: options.rotateZ ?? options.rotationZ ?? 0,
 			scale: options.scale ?? 1,
 			scaleX: options.scaleX ?? 1,
 			scaleY: options.scaleY ?? 1,
@@ -3852,7 +4367,7 @@ const Layer3D = {
 			width: options.width,
 			height: options.height,
 			depth: options.depth,
-			radius: options.radius,
+			radius: options.radius ?? options.cornerRadius ?? options.borderRadius,
 			segments: options.segments,
 			taper: options.taper
 		}, options);
@@ -3868,8 +4383,8 @@ const Layer3D = {
 		return primitiveNode("cylinder", {
 			type: "cylinder",
 			radius: options.radius,
-			radiusTop: options.radiusTop,
-			radiusBottom: options.radiusBottom,
+			radiusTop: options.radiusTop ?? options.topRadius,
+			radiusBottom: options.radiusBottom ?? options.bottomRadius,
 			height: options.height,
 			segments: options.segments,
 			openEnded: options.openEnded,
@@ -3882,8 +4397,8 @@ const Layer3D = {
 	torus(options = {}) {
 		return primitiveNode("torus", {
 			type: "torus",
-			radius: options.radius,
-			tube: options.tube,
+			radius: options.radius ?? options.majorRadius,
+			tube: options.tube ?? options.minorRadius ?? options.tubeRadius,
 			radialSegments: options.radialSegments,
 			tubularSegments: options.tubularSegments,
 			arc: options.arc
@@ -4025,6 +4540,15 @@ const Layer3D = {
 			irregularity: options.irregularity
 		}, options);
 	},
+	terrain(options) {
+		return terrain3d(options);
+	},
+	sdf(options) {
+		return sdf3d(options);
+	},
+	scatter(options) {
+		return scatter3d(options);
+	},
 	instances(options) {
 		const primaryMesh = Array.isArray(options.mesh) ? options.mesh[0] : options.mesh;
 		const node = {
@@ -4033,9 +4557,9 @@ const Layer3D = {
 			x: options.x ?? 0,
 			y: options.y ?? 0,
 			z: options.z ?? 0,
-			rotateX: options.rotateX ?? 0,
-			rotateY: options.rotateY ?? 0,
-			rotateZ: options.rotateZ ?? 0,
+			rotateX: options.rotateX ?? options.rotationX ?? 0,
+			rotateY: options.rotateY ?? options.rotationY ?? 0,
+			rotateZ: options.rotateZ ?? options.rotationZ ?? 0,
 			scale: options.scale ?? 1,
 			color: options.color,
 			colorTint: options.colorTint,
@@ -4050,6 +4574,8 @@ const Layer3D = {
 			startFrame: options.startFrame,
 			durationFrames: options.durationFrames,
 			instances3d: { ...options },
+			...options.wind && { wind: options.wind },
+			...options.crowd && { crowd: options.crowd },
 			...materialProps(options)
 		};
 		if (primaryMesh) {
@@ -4486,6 +5012,9 @@ function rig(name, options) {
 		exposure: options.exposure,
 		toneMapping: options.toneMapping,
 		fog: options.fog,
+		volumetricFog: options.volumetricFog,
+		ssr: options.ssr,
+		gi: options.gi,
 		bloom: options.bloom
 	}), Light.directional({
 		id: `${id}-key`,
@@ -4597,6 +5126,20 @@ var RapierWorld2D = class {
 				x,
 				y
 			}, true),
+			setPose: ([x, y], angle) => {
+				body.setTranslation({
+					x,
+					y
+				}, true);
+				body.setRotation(angle, true);
+			},
+			setVelocity: ([x, y], w) => {
+				body.setLinvel({
+					x,
+					y
+				}, true);
+				body.setAngvel(w, true);
+			},
 			setKinematicTarget: ([x, y], angle) => {
 				body.setNextKinematicTranslation({
 					x,
@@ -4725,6 +5268,19 @@ var RapierWorld3D = class {
 			mass: () => body.mass(),
 			setEnabled: (on) => body.setEnabled(on),
 			applyImpulse: (v) => body.applyImpulse(vec3(v), true),
+			setPose: (p, [x, y, z$3, w]) => {
+				body.setTranslation(vec3(p), true);
+				body.setRotation({
+					x,
+					y,
+					z: z$3,
+					w
+				}, true);
+			},
+			setVelocity: (v, w) => {
+				body.setLinvel(vec3(v), true);
+				body.setAngvel(vec3(w), true);
+			},
 			setKinematicTarget: (p, [x, y, z$3, w]) => {
 				body.setNextKinematicTranslation(vec3(p));
 				body.setNextKinematicRotation({
@@ -4832,6 +5388,7 @@ function shapeDesc3D(R, shape$1) {
 			if (!desc) throw new Error("Physics: could not build a convex hull for this shape.");
 			return desc;
 		}
+		case "trimesh": return R.ColliderDesc.trimesh(new Float32Array(shape$1.vertices), new Uint32Array(shape$1.indices));
 	}
 }
 
@@ -5025,6 +5582,8 @@ var PhysicsWorld2D = class extends WorldCore {
 		};
 		const simBody = this.sim.addBody(spec$1);
 		const body = new PhysicsBody2D(this, simBody, type, layer, geom, options, this.newRecording());
+		const start = body.kinematicTarget(this.startFrame);
+		if (start) simBody.setPose(start.position, start.rotation);
 		return this.addBody(body);
 	}
 	/** A fixed, very wide floor whose top edge sits at `y`. */
@@ -5219,7 +5778,7 @@ function effectiveMass(a, b) {
 	if (ma > 0 && mb > 0) return ma * mb / (ma + mb);
 	return Math.max(ma, mb, .001);
 }
-function num$3(v, fallback) {
+function num$4(v, fallback) {
 	return typeof v === "number" && Number.isFinite(v) ? v : fallback;
 }
 function layerGeometry(layer, options) {
@@ -5230,31 +5789,31 @@ function layerGeometry(layer, options) {
 	if ((width === void 0 || height === void 0) && layer.kind === "text") {
 		const m = FontManager.measure(String(layer.text ?? ""), {
 			fontFamily: String(layer.fontFamily ?? "Inter"),
-			fontSize: num$3(layer.fontSize, 48),
+			fontSize: num$4(layer.fontSize, 48),
 			fontWeight: layer.fontWeight,
-			letterSpacing: num$3(layer.letterSpacing, 0),
+			letterSpacing: num$4(layer.letterSpacing, 0),
 			lineHeight: typeof layer.lineHeight === "number" ? layer.lineHeight : void 0
 		});
 		width ??= m.width;
 		height ??= m.height;
 	}
 	if (width === void 0 || height === void 0 || width <= 0 || height <= 0) throw new Error(`Physics: layer${id} needs a numeric \`width\` and \`height\` (or the \`size\` option) to become a body.`);
-	const scale = num$3(layer.scale, 1);
+	const scale = num$4(layer.scale, 1);
 	return {
 		x: layer.x,
 		y: layer.y,
 		width,
 		height,
 		scale,
-		anchorX: num$3(layer.anchorX, .5),
-		anchorY: num$3(layer.anchorY, .5),
-		rotation: num$3(layer.rotation, 0),
+		anchorX: num$4(layer.anchorX, .5),
+		anchorY: num$4(layer.anchorY, .5),
+		rotation: num$4(layer.rotation, 0),
 		shape: scaleShape$1(colliderShape(layer, width, height, options.shape ?? "auto"), scale)
 	};
 }
 function colliderShape(layer, w, h, mode) {
 	const shapeType = layer.kind === "shape" ? String(layer.shapeType ?? "rect") : "rect";
-	const radius = num$3(layer.borderRadius, num$3(layer.cornerRadius, 0));
+	const radius = num$4(layer.borderRadius, num$4(layer.cornerRadius, 0));
 	const box = {
 		kind: "box",
 		hx: w / 2,
@@ -5282,7 +5841,7 @@ function outlinePoints(layer, shapeType, w, h) {
 		shapeType,
 		width: w,
 		height: h,
-		cornerRadius: num$3(layer.cornerRadius, num$3(layer.borderRadius, 0)),
+		cornerRadius: num$4(layer.cornerRadius, num$4(layer.borderRadius, 0)),
 		polygonSides: layer.polygonSides,
 		starPoints: layer.starPoints,
 		starInnerRadiusRatio: layer.starInnerRadiusRatio,
@@ -5331,6 +5890,275 @@ function centerToLayer(cx, cy, rotationDeg, f) {
 	return [cx - ox - f.anchorX * f.width, cy - oy - f.anchorY * f.height];
 }
 
+//#endregion
+//#region src/physics/fracture3d.ts
+/**
+* Voronoi destruction: a mesh layer stays whole (a fixed collider of its
+* own shape) until its fracture frame, or until a body hits it, then its
+* pieces wake as rigid bodies and fly apart. The pieces' recorded poses go
+* into the node (`fracture3d.track`), where the renderer turns them into
+* the joints of one rigidly skinned mesh.
+*/
+/** A fractured layer: its pieces, and the collider that stands in for it while whole. */
+var Fracture3D = class {
+	/** @internal */ brokeAt;
+	/** @internal */
+	constructor(node, pieces, intact, world) {
+		this.node = node;
+		this.pieces = pieces;
+		this.intact = intact;
+		this.world = world;
+	}
+	/** Composition frame it broke at (after simulating); undefined if it never did. */
+	get frame() {
+		return this.brokeAt === void 0 ? void 0 : this.world.startFrame + this.brokeAt;
+	}
+};
+const NEVER = Number.MAX_SAFE_INTEGER;
+const num$3 = (v, fallback) => typeof v === "number" && Number.isFinite(v) ? v : fallback;
+/** The node's placement as the renderer builds it: T · Rz · Ry · Rx · S. */
+function nodePose(t) {
+	const position = [
+		num$3(t.x, 0),
+		num$3(t.y, 0),
+		num$3(t.z, 0)
+	];
+	const rotation = [
+		num$3(t.rotateX, 0),
+		num$3(t.rotateY, 0),
+		num$3(t.rotateZ, num$3(t.rotation, 0))
+	];
+	const s = num$3(t.scale, 1);
+	const scale = [
+		s * num$3(t.scaleX, 1),
+		s * num$3(t.scaleY, 1),
+		s * num$3(t.scaleZ, 1)
+	];
+	const rad = (d) => d * Math.PI / 180;
+	let m = Matrix4Math.translate(...position);
+	m = Matrix4Math.multiply(m, Matrix4Math.rotateZ(rad(rotation[2])));
+	m = Matrix4Math.multiply(m, Matrix4Math.rotateY(rad(rotation[1])));
+	m = Matrix4Math.multiply(m, Matrix4Math.rotateX(rad(rotation[0])));
+	m = Matrix4Math.multiply(m, Matrix4Math.scale(...scale));
+	return {
+		position,
+		rotation,
+		scale,
+		matrix: m
+	};
+}
+const apply = (m, p) => [
+	m[0] * p[0] + m[4] * p[1] + m[8] * p[2] + m[12],
+	m[1] * p[0] + m[5] * p[1] + m[9] * p[2] + m[13],
+	m[2] * p[0] + m[6] * p[1] + m[10] * p[2] + m[14]
+];
+const SCALE_PROPS = [
+	"scale",
+	"scaleX",
+	"scaleY",
+	"scaleZ"
+];
+/** The animated props among `props` (tracks on them). */
+function animatedProps(node, props) {
+	const tracks = node.animation?.tracks ?? [];
+	return props.filter((p) => tracks.some((t) => t.prop === p));
+}
+/** Rigid pieces cannot change size: a fractured layer's scale holds still. */
+function assertRigid(node) {
+	const scaling = animatedProps(node, SCALE_PROPS);
+	if (!scaling.length) return;
+	const id = typeof node.id === "string" ? ` "${node.id}"` : "";
+	throw new Error(`Physics.fracture: layer${id} animates ${scaling.join(", ")}; rigid pieces cannot change size. Keep a fractured layer's scale still (position and rotation may animate).`);
+}
+/**
+* The layer's animated position and rotation as kinematic drivers, sampled
+* as the compositor draws them (GSAP eases, stepped timing, signals), so the
+* stand-in collider is where the layer is; undefined when it holds still.
+* Read lazily: animation added after `fracture()` counts.
+*/
+function followLayer(node, fps) {
+	const layer = node;
+	const at = (prop) => (frame) => sampleLayerProp(layer, prop, frame, fps);
+	const rotateZ = (frame) => animatedProps(node, ["rotateZ"]).length || typeof node.rotateZ === "number" ? sampleLayerProp(layer, "rotateZ", frame, fps) : sampleLayerProp(layer, "rotation", frame, fps);
+	return {
+		x: at("x"),
+		y: at("y"),
+		z: at("z"),
+		rotateX: at("rotateX"),
+		rotateY: at("rotateY"),
+		rotateZ
+	};
+}
+const MOVING_PROPS = [
+	"x",
+	"y",
+	"z",
+	"rotateX",
+	"rotateY",
+	"rotateZ",
+	"rotation"
+];
+/** @internal */
+function createFracture(world, target$1, options) {
+	const node = target$1;
+	const model = node.modelData;
+	if (!model?.meshes?.length) {
+		const id = typeof node.id === "string" ? ` "${node.id}"` : "";
+		throw new Error(`Physics.fracture: layer${id} has no mesh. Fracture a Layer3D primitive, extruded text, or a model node that carries modelData.`);
+	}
+	assertRigid(node);
+	const pose = nodePose(node);
+	const toObject = Matrix4Math.invert(pose.matrix) ?? Matrix4Math.identity();
+	const spec$1 = {
+		cells: Math.max(2, Math.min(256, Math.round(options.cells ?? 48))),
+		seed: options.seed ?? 1,
+		...options.impactPoint && { impactPoint: apply(toObject, options.impactPoint) },
+		...options.interiorColor && { interiorColor: options.interiorColor },
+		...options.interiorRoughness !== void 0 && { interiorRoughness: options.interiorRoughness }
+	};
+	const { cells } = fractureModel(model, spec$1);
+	node.fracture3d = spec$1;
+	const moving = animatedProps(node, MOVING_PROPS).length > 0;
+	const intact = world.body(target$1, moving ? {
+		type: "kinematic",
+		output: "none",
+		follow: followLayer(node, world.fps)
+	} : {
+		type: "fixed",
+		output: "none"
+	});
+	const pieces = cells.map((cell) => world.shapedBody(void 0, apply(pose.matrix, cell.centroid), pose.rotation, {
+		kind: "hull",
+		points: cell.hull.map((v, i) => v * pose.scale[i % 3] * .97)
+	}, {
+		type: "dynamic",
+		startFrame: NEVER,
+		output: "none",
+		density: options.density,
+		friction: options.friction,
+		restitution: options.restitution ?? .2
+	}));
+	const fracture = new Fracture3D(target$1, pieces, intact, world);
+	const radius = model.bounds.boundingSphereRadius * Math.max(...pose.scale);
+	world.onStep((f, pairs) => {
+		if (fracture.brokeAt !== void 0) return;
+		const ff = options.fractureFrame ?? "onImpact";
+		const hit = pairs.find(([a, b]) => a === intact && b.type === "dynamic" || b === intact && a.type === "dynamic");
+		const hitter = hit ? hit[0] === intact ? hit[1] : hit[0] : void 0;
+		if (!(ff === "onImpact" ? Boolean(hitter) : f >= ff - world.startFrame)) return;
+		fracture.brokeAt = f;
+		intact.sim.setEnabled(false);
+		breakApart(world, pieces, options, radius, intact, pose, hitter, f);
+	});
+	world.onSimulated(() => {
+		assertRigid(node);
+		spec$1.track = recordTrack(pieces, world.startFrame + world.frames);
+	});
+	return fracture;
+}
+/** Where the stand-in is and how it moves (px, quaternion, px/s, rad/s). */
+function standInState(world, intact) {
+	const ppm = world.pixelsPerMeter;
+	return {
+		position: intact.sim.position().map((v) => v * ppm),
+		rotation: intact.sim.rotation(),
+		velocity: intact.sim.velocity().map((v) => v * ppm),
+		spin: intact.sim.angularVelocity()
+	};
+}
+/**
+* Wakes every piece where the layer is now (the stand-in's pose, which
+* follows its animation), carrying the layer's own motion, plus a burst
+* outward from the impact and some of the hitter's momentum.
+*/
+function breakApart(world, pieces, options, radius, intact, rest, hitter, frame) {
+	const ppm = world.pixelsPerMeter;
+	const layer = standInState(world, intact);
+	const q0 = quatFromEuler(...rest.rotation);
+	const undoRest = [
+		-q0[0],
+		-q0[1],
+		-q0[2],
+		q0[3]
+	];
+	const hitAt = hitter?.sim.position().map((v) => v * ppm);
+	const transfer = options.momentumTransfer ?? .35;
+	const hitVel = [
+		0,
+		0,
+		0
+	];
+	if (hitter) {
+		const at = world.startFrame + frame - 1;
+		const rec = hitter.recording;
+		hitVel[0] = rec.channel("vx")[at] ?? 0;
+		hitVel[1] = rec.channel("vy")[at] ?? 0;
+		hitVel[2] = rec.channel("vz")[at] ?? 0;
+		hitter.sim.setVelocity(hitVel.map((v) => v * (1 - transfer) / ppm), hitter.sim.angularVelocity());
+	}
+	const impact = options.impactPoint ?? hitAt ?? layer.position;
+	const speed = options.explosionSpeed ?? 0;
+	const spin = options.spin ?? speed / 3;
+	const rand = createRandom((options.seed ?? 1) * 7717 + 3);
+	for (const piece of pieces) {
+		const c = piece.center();
+		const arm = rotateByQuat(rotateByQuat([
+			c[0] - rest.position[0],
+			c[1] - rest.position[1],
+			c[2] - rest.position[2]
+		], undoRest), layer.rotation);
+		const p = [
+			layer.position[0] + arm[0],
+			layer.position[1] + arm[1],
+			layer.position[2] + arm[2]
+		];
+		const w0 = layer.spin;
+		const carried = [
+			layer.velocity[0] + w0[1] * arm[2] - w0[2] * arm[1],
+			layer.velocity[1] + w0[2] * arm[0] - w0[0] * arm[2],
+			layer.velocity[2] + w0[0] * arm[1] - w0[1] * arm[0]
+		];
+		const d = [
+			p[0] - impact[0],
+			p[1] - impact[1],
+			p[2] - impact[2]
+		];
+		const dist$2 = Math.hypot(...d) || 1;
+		const falloff = 1 / (1 + (dist$2 / Math.max(1, radius)) ** 2);
+		const v = d.map((x, i) => carried[i] + x / dist$2 * speed * falloff + hitVel[i] * transfer * falloff);
+		const axis = [
+			rand() - .5,
+			rand() - .5,
+			rand() - .5
+		];
+		const len = Math.hypot(...axis) || 1;
+		const w = axis.map((a, i) => a / len * spin * (.5 + rand()) + w0[i] * 180 / Math.PI);
+		piece.wake(frame, v, w, {
+			position: p,
+			rotation: layer.rotation
+		});
+	}
+}
+/** Every piece's pose per composition frame: [x, y, z, qx, qy, qz, qw] each. */
+function recordTrack(pieces, frames) {
+	const channels = pieces.map((b) => [
+		"x",
+		"y",
+		"z",
+		"qx",
+		"qy",
+		"qz",
+		"qw"
+	].map((c) => b.recording.channel(c)));
+	const out = new Array(frames * pieces.length * 7);
+	let k = 0;
+	for (let f = 0; f < frames; f++) for (const ch of channels) for (let c = 0; c < 7; c++) {
+		const v = ch[c][f] ?? 0;
+		out[k++] = c < 3 ? Math.round(v * 1e5) / 1e5 : Math.round(v * 1e7) / 1e7;
+	}
+	return out;
+}
+
 //#endregion
 //#region src/physics/world3d.ts
 const DEG = Math.PI / 180;
@@ -5356,6 +6184,7 @@ function quatFromEuler(rx, ry, rz) {
 		Math.cos(half(rz))
 	], qy), qx);
 }
+/** @internal */
 function quatMul(a, b) {
 	const [ax, ay, az, aw] = a;
 	const [bx, by, bz, bw] = b;
@@ -5435,7 +6264,32 @@ var PhysicsBody3D = class {
 		this.recording = recording;
 	}
 	get startFrame() {
-		return Math.max(0, Math.round(this.options.startFrame ?? 0));
+		return this.wokeAt ?? Math.max(0, Math.round(this.options.startFrame ?? 0));
+	}
+	wokeAt;
+	/**
+	* @internal Starts the body now, mid-simulation (`frame` relative to the
+	* world's start): it moves from the next frame, at this velocity (px/s,
+	* degrees per second), from `pose` (px) when given.
+	*/
+	wake(frame, velocity, angularVelocity, pose) {
+		this.wokeAt = frame;
+		const ppm = this.world.pixelsPerMeter;
+		this.sim.setEnabled(true);
+		if (pose) this.sim.setPose([
+			pose.position[0] / ppm,
+			pose.position[1] / ppm,
+			pose.position[2] / ppm
+		], pose.rotation);
+		this.sim.setVelocity([
+			velocity[0] / ppm,
+			velocity[1] / ppm,
+			velocity[2] / ppm
+		], [
+			angularVelocity[0] * DEG,
+			angularVelocity[1] * DEG,
+			angularVelocity[2] * DEG
+		]);
 	}
 	get gravityScale() {
 		return this.options.gravityScale ?? 1;
@@ -5489,17 +6343,17 @@ var PhysicsBody3D = class {
 		const follow = this.options.follow;
 		if (this.type !== "kinematic" || !follow) return void 0;
 		const fps = this.world.fps;
-		const read$1 = (d, fallback) => d === void 0 ? fallback : sampleDriver(d, frame, fps);
+		const read$2 = (d, fallback) => d === void 0 ? fallback : sampleDriver(d, frame, fps);
 		const p = this.start.position;
 		const r = this.start.rotation;
 		const ppm = this.world.pixelsPerMeter;
 		return {
 			position: [
-				read$1(follow.x, p[0]) / ppm,
-				read$1(follow.y, p[1]) / ppm,
-				read$1(follow.z, p[2]) / ppm
+				read$2(follow.x, p[0]) / ppm,
+				read$2(follow.y, p[1]) / ppm,
+				read$2(follow.z, p[2]) / ppm
 			],
-			rotation: quatFromEuler(read$1(follow.rotateX, r[0]), read$1(follow.rotateY, r[1]), read$1(follow.rotateZ, r[2]))
+			rotation: quatFromEuler(read$2(follow.rotateX, r[0]), read$2(follow.rotateY, r[1]), read$2(follow.rotateZ, r[2]))
 		};
 	}
 	/** @internal */
@@ -5518,7 +6372,12 @@ var PhysicsBody3D = class {
 			ry[previous],
 			rz[previous]
 		];
-		const e = eulerFromQuat(this.sim.rotation(), prev);
+		const q = this.sim.rotation();
+		rec.channel("qx")[index] = q[0];
+		rec.channel("qy")[index] = q[1];
+		rec.channel("qz")[index] = q[2];
+		rec.channel("qw")[index] = q[3];
+		const e = eulerFromQuat(q, prev);
 		rx[index] = e[0];
 		ry[index] = e[1];
 		rz[index] = e[2];
@@ -5571,6 +6430,7 @@ var PhysicsBody3D = class {
 		];
 	}
 };
+/** @internal */
 function rotateByQuat(v, q) {
 	const r = quatMul(quatMul(q, [
 		v[0],
@@ -5626,6 +6486,11 @@ var PhysicsWorld3D = class extends WorldCore {
 			num$2(options.rotateY ?? t.rotateY, 0),
 			num$2(options.rotateZ ?? t.rotateZ, 0)
 		];
+		return this.shapedBody(layer, position, rotation, colliderShape3D(t, options), options);
+	}
+	/** @internal A body with an explicit collider (px), at a pose in px and degrees. */
+	shapedBody(layer, position, rotation, shape$1, options) {
+		this.assertOpen();
 		const ppm = this.pixelsPerMeter;
 		const type = options.type ?? "dynamic";
 		const v = options.velocity ?? [
@@ -5671,15 +6536,37 @@ var PhysicsWorld3D = class extends WorldCore {
 			density: options.density ?? 1,
 			friction: options.friction ?? .6,
 			restitution: options.restitution ?? .3,
-			shape: scaleShape(colliderShape3D(t, options), 1 / ppm)
+			shape: scaleShape(shape$1, 1 / ppm)
 		};
 		const simBody = this.sim.addBody(spec$1);
 		const body = new PhysicsBody3D(this, simBody, type, layer, {
 			position,
 			rotation
 		}, options, this.newRecording());
+		const start = body.kinematicTarget(this.startFrame);
+		if (start) simBody.setPose(start.position, start.rotation);
 		return this.addBody(body);
 	}
+	/** @internal Runs after each simulated frame (frame relative to the world's start). */
+	onStep(hook) {
+		this.assertOpen();
+		this.stepHooks.push(hook);
+	}
+	/** @internal Runs once the simulation has finished. */
+	onSimulated(hook) {
+		this.assertOpen();
+		this.simulatedHooks.push(hook);
+	}
+	/**
+	* Breaks a Layer3D primitive, extruded text or loaded model into Voronoi
+	* pieces that stay together, looking intact, until the fracture frame (or
+	* until something hits it), then fly apart as rigid bodies. The node is
+	* changed in place: add it to the composition as usual. All pieces draw
+	* in one call per material, the cut faces in `interiorColor`.
+	*/
+	fracture(target$1, options = {}) {
+		return createFracture(this, target$1, options);
+	}
 	/** A fixed, very large floor whose top face sits at `y`. */
 	ground(options) {
 		const t = 2e3;
@@ -5828,11 +6715,11 @@ var PhysicsWorld3D = class extends WorldCore {
 	/** A steady push, px/s² (mass-independent). Drivers are read every frame. */
 	force(body, accel) {
 		const ppm = this.pixelsPerMeter;
-		const read$1 = (d, frame) => d === void 0 ? 0 : sampleDriver(d, frame, this.fps) / ppm;
+		const read$2 = (d, frame) => d === void 0 ? 0 : sampleDriver(d, frame, this.fps) / ppm;
 		this.addForce(body, (frame) => [
-			read$1(accel.x, frame),
-			read$1(accel.y, frame),
-			read$1(accel.z, frame)
+			read$2(accel.x, frame),
+			read$2(accel.y, frame),
+			read$2(accel.z, frame)
 		]);
 		return this;
 	}
@@ -5937,6 +6824,10 @@ function colliderShape3D(t, options) {
 			points: pts.map((v, i) => v * scale[i % 3])
 		};
 	};
+	if (mode === "mesh" || mode === "auto" && (options.type ?? "dynamic") !== "dynamic" && (prim.type === "terrain" || prim.type === "sdf")) {
+		const mesh = meshTriangles(t.modelData, scale);
+		if (mesh) return mesh;
+	}
 	if (options.size || mode === "box") {
 		const [w, h$1, d] = options.size ?? boxSize(t, prim) ?? [
 			0,
@@ -6049,6 +6940,25 @@ function boxSize(t, prim) {
 		t.depth
 	];
 }
+/** All of a model's triangles, scaled: an exact (non-convex) collider. */
+function meshTriangles(modelData, scale) {
+	const meshes = modelData?.meshes;
+	if (!meshes?.length) return void 0;
+	const vertices = [];
+	const indices = [];
+	for (const m of meshes) {
+		if (!m.positions || !m.indices) continue;
+		if (m.topology && m.topology !== "triangle-list") continue;
+		const base = vertices.length / 3;
+		for (let i = 0; i < m.positions.length; i++) vertices.push(m.positions[i] * scale[i % 3]);
+		for (let i = 0; i < m.indices.length; i++) indices.push(m.indices[i] + base);
+	}
+	return indices.length >= 3 ? {
+		kind: "trimesh",
+		vertices,
+		indices
+	} : void 0;
+}
 /** Every vertex of a model, flat xyz, at most ~4k points (the hull needs no more). */
 function meshPoints(modelData) {
 	const meshes = modelData?.meshes;
@@ -6088,6 +6998,11 @@ function scaleShape(shape$1, s) {
 			kind: "hull",
 			points: shape$1.points.map((v) => v * s)
 		};
+		case "trimesh": return {
+			kind: "trimesh",
+			vertices: shape$1.vertices.map((v) => v * s),
+			indices: shape$1.indices
+		};
 	}
 }
 
@@ -8662,7 +9577,7 @@ var Media = class Media {
 		return this.virtualMedia;
 	}
 	/**
-	* Renders a single frame from this media pipeline to a PNG Buffer.
+	* Renders a single frame from this media pipeline to an image or raw RGBA Buffer.
 	* Can render either by timestamp in milliseconds (`atMs`) or by frame index (`frame`).
 	*/
 	async renderFrame(options = {}) {
@@ -8775,7 +9690,11 @@ var Composition = class Composition {
 	vision(sourceOrLayer, options = {}) {
 		const source = typeof sourceOrLayer === "string" ? sourceOrLayer : sourceOrLayer.src ?? sourceOrLayer.inputHandleId;
 		if (typeof sourceOrLayer !== "string") {
-			const layer = collectNodeOps(this.toVirtualMedia({ resolveMediaSignal: this.mediaSignalResolver(true) }).children).find((node) => node.operation.id === sourceOrLayer.id);
+			const found = collectLayersOnClock(this.toVirtualMedia({ resolveMediaSignal: this.mediaSignalResolver(true) }).children).find(({ vm: node }) => node.operation.id === sourceOrLayer.id);
+			const layer = found && { operation: {
+				...found.vm.operation,
+				startFrame: found.startFrame
+			} };
 			if (!layer) throw new Error("Add the media layer to the composition before calling comp.vision(layer)");
 			options = {
 				startFrame: layer.operation.startFrame ?? sourceOrLayer.startFrame,
@@ -8818,9 +9737,12 @@ var Composition = class Composition {
 			if (!node || typeof node !== "object") return;
 			const n = node;
 			if (n.kind === "media" && n.dataType === "Video" && typeof n.inputHandleId === "string" && n.vision instanceof Vision && !(CLIP_SUBJECT in n.vision)) {
-				layers ??= new Map(collectNodeOps(this.toVirtualMedia().children).map((node$1) => {
-					const op = node$1.operation;
-					return [op.id, op];
+				layers ??= new Map(collectLayersOnClock(this.toVirtualMedia().children).map(({ vm, startFrame }) => {
+					const op = vm.operation;
+					return [op.id, {
+						startFrame,
+						timeRemap: op.timeRemap
+					}];
 				}));
 				const layer = layers.get(n.id);
 				const clip = this.clipForLayer(n.src ?? n.inputHandleId, n.vision, {
@@ -9373,10 +10295,11 @@ var Composition = class Composition {
 		return vm;
 	}
 	/**
-	* Renders a single frame from the composition to a PNG Buffer.
+	* Renders a single frame from the composition to an image or raw RGBA Buffer.
 	* Can render either by timestamp in milliseconds (`atMs`) or by frame index (`frame`).
 	*/
-	async renderFrame(options = {}) {
+	async renderFrame(frameOrOptions = {}) {
+		const options = typeof frameOrOptions === "number" ? { frame: frameOrOptions } : frameOrOptions;
 		const { frame } = resolveFrameRequest(options, this.fps);
 		if (options.fps !== void 0 && options.fps !== this.fps) throw new Error(`Composition fps is ${this.fps}; cannot render at fps ${options.fps}.`);
 		const vm = this.toVirtualMedia();
@@ -9394,7 +10317,9 @@ var Composition = class Composition {
 		}
 		return (options.renderer ?? new HeadlessMediaRenderer()).renderFrame(vm, {
 			fps: this.fps,
-			frame
+			frame,
+			renderId: options.renderId,
+			format: options.format
 		});
 	}
 	/**
@@ -9437,11 +10362,27 @@ var Composition = class Composition {
 	* never change. `renderVideo({ qa })` includes these automatically.
 	*/
 	lint() {
-		return lintComposition(this.toSpec(), { emojiFont: FontManager.hasEmojiFont() });
+		return lintComposition(this.toSpec(), {
+			emojiFont: FontManager.hasEmojiFont(),
+			scatterCoverage
+		});
 	}
 };
 function withAnimation(node) {
 	const target$1 = node;
+	const raw = target$1;
+	if (raw.rotationX !== void 0) {
+		if (raw.rotateX === void 0) raw.rotateX = raw.rotationX;
+		delete raw.rotationX;
+	}
+	if (raw.rotationY !== void 0) {
+		if (raw.rotateY === void 0) raw.rotateY = raw.rotationY;
+		delete raw.rotationY;
+	}
+	if (raw.rotationZ !== void 0) {
+		if (raw.rotateZ === void 0) raw.rotateZ = raw.rotationZ;
+		delete raw.rotationZ;
+	}
 	if (target$1.animation instanceof LayerAnimation) target$1.animation = target$1.animation.toSpec();
 	Object.defineProperty(target$1, "animate", {
 		value: (...anims) => {
@@ -9628,8 +10569,89 @@ function withAnimation(node) {
 		writable: true,
 		configurable: true
 	});
+	bindMaterialSignals(target$1);
 	return target$1;
 }
+/**
+* Numeric surface props a live `Signal` may drive directly (`clearcoat: sig`):
+* the value written to the node is the static fallback, the signal becomes a
+* draw-time signal track. `iridescence` counts only when it is the number form.
+*/
+const MATERIAL_SIGNAL_PROPS = [
+	{
+		prop: "roughness",
+		fallback: .5
+	},
+	{
+		prop: "metallic",
+		fallback: 0
+	},
+	{
+		prop: "emissiveIntensity",
+		fallback: 1
+	},
+	{
+		prop: "clearcoat",
+		fallback: 0
+	},
+	{
+		prop: "clearcoatRoughness",
+		fallback: .08
+	},
+	{
+		prop: "anisotropy",
+		fallback: 0
+	},
+	{
+		prop: "anisotropyRotation",
+		fallback: 0
+	},
+	{
+		prop: "subsurface",
+		fallback: 0
+	},
+	{
+		prop: "sheen",
+		fallback: 0
+	},
+	{
+		prop: "sheenRoughness",
+		fallback: .5
+	},
+	{
+		prop: "iridescence",
+		fallback: 0
+	},
+	{
+		prop: "iridescenceThickness",
+		fallback: 400
+	},
+	{
+		prop: "iridescenceIor",
+		fallback: 1.3
+	},
+	{
+		prop: "triplanarScale",
+		fallback: 1
+	},
+	{
+		prop: "triplanarSharpness",
+		fallback: 4
+	}
+];
+/** Moves signal-valued material props of a node onto signal tracks. */
+function bindMaterialSignals(target$1) {
+	const raw = target$1;
+	let anim;
+	for (const { prop, fallback } of MATERIAL_SIGNAL_PROPS) {
+		const val = raw[prop];
+		if (!isSignalLike(val)) continue;
+		anim ??= LayerAnimation.create();
+		anim.signal(prop, val);
+		raw[prop] = fallback;
+	}
+	if (anim) target$1.animate(anim);
+}
 const Layer = {
 	video: (src, options = {}) => withAnimation({
 		id: options.id ?? autoId("video"),
@@ -9907,29 +10929,42 @@ const Layer = {
 		});
 	},
 	chart: (options, props = {}) => buildChart(options, props, FontManager.getAll()[0]?.family ?? "Inter"),
-	camera: (options = {}) => withAnimation({
-		id: options.id ?? autoId("camera"),
-		kind: "camera",
-		mode: options.mode ?? "lookAt",
-		pitch: options.pitch ?? 0,
-		yaw: options.yaw ?? 0,
-		roll: options.roll ?? 0,
-		...options
-	}),
-	light: (options = {}) => withAnimation({
+	camera: (options = {}) => {
+		const { fov, focalLength, sensorWidth, near, far, zoom, lens: existingLens, ...rest } = options;
+		const mergedLens = fov !== void 0 || focalLength !== void 0 || sensorWidth !== void 0 || near !== void 0 || far !== void 0 || zoom !== void 0 || existingLens !== void 0 ? {
+			...existingLens,
+			...fov !== void 0 && { fov },
+			...focalLength !== void 0 && { focalLength },
+			...sensorWidth !== void 0 && { sensorWidth },
+			...near !== void 0 && { near },
+			...far !== void 0 && { far },
+			...zoom !== void 0 && { zoom }
+		} : void 0;
+		return withAnimation({
+			id: rest.id ?? autoId("camera"),
+			kind: "camera",
+			mode: rest.mode ?? "lookAt",
+			pitch: rest.pitch ?? 0,
+			yaw: rest.yaw ?? 0,
+			roll: rest.roll ?? 0,
+			...rest,
+			...mergedLens !== void 0 && { lens: mergedLens }
+		});
+	},
+	light: (options = {}) => buildLightNode({
 		id: options.id ?? autoId("light"),
 		kind: "light",
 		lightType: options.lightType ?? "point",
 		color: options.color ?? "#ffffff",
-		intensity: options.intensity ?? 1,
-		...options
-	}),
+		intensity: 1
+	}, options),
 	ambientLight: (color$1 = "#ffffff", intensity = .5, options = {}) => Light.ambient(color$1, intensity, options),
 	sequence: (entries, options) => sequence(entries, options),
 	environment: (presetOrOptions = "studio", options = {}) => Light.environment(presetOrOptions, options),
 	directionalLight: (options = {}) => Light.directional(options),
 	pointLight: (options = {}) => Light.point(options),
 	spotLight: (options = {}) => Light.spot(options),
+	rectLight: (options = {}) => Light.rect(options),
 	cube: (options) => Layer3D.cube(options),
 	carousel3d: (options) => Layer3D.carousel(options),
 	plane3d: (options) => Layer3D.plane(options),
@@ -9993,78 +11028,220 @@ const Layer = {
 		...options
 	})
 };
+function isHdriPath(value) {
+	return /\.(hdr|exr)$/i.test(value);
+}
+const LIGHT_SIGNAL_PROPS = [
+	{
+		prop: "intensity",
+		fallback: 1
+	},
+	{
+		prop: "x",
+		fallback: 0
+	},
+	{
+		prop: "y",
+		fallback: 0
+	},
+	{
+		prop: "z",
+		fallback: 0
+	},
+	{
+		prop: "targetX",
+		fallback: 0
+	},
+	{
+		prop: "targetY",
+		fallback: 0
+	},
+	{
+		prop: "targetZ",
+		fallback: 0
+	},
+	{
+		prop: "radius",
+		fallback: 1e3
+	},
+	{
+		prop: "angle",
+		fallback: 45
+	},
+	{
+		prop: "penumbra",
+		fallback: .2
+	},
+	{
+		prop: "decay",
+		fallback: 1
+	},
+	{
+		prop: "width",
+		fallback: 240
+	},
+	{
+		prop: "height",
+		fallback: 140
+	},
+	{
+		prop: "rotation",
+		fallback: 0
+	},
+	{
+		prop: "exposure",
+		fallback: 0
+	},
+	{
+		prop: "volumetricFogDensity",
+		fallback: .02
+	},
+	{
+		prop: "volumetricFogAnisotropy",
+		fallback: .55
+	},
+	{
+		prop: "volumetricFogNoiseStrength",
+		fallback: .45
+	}
+];
+function isSignalLike(val) {
+	if (!val || typeof val !== "object") return false;
+	const obj = val;
+	return typeof obj.get === "function" || typeof obj.inputHandleId === "string" || typeof obj.gpuBinding === "object";
+}
+function buildLightNode(defaults, rawOpts) {
+	const cleaned = {
+		...defaults,
+		...rawOpts
+	};
+	const signalBindings = [];
+	for (const { prop, fallback } of LIGHT_SIGNAL_PROPS) {
+		const val = cleaned[prop];
+		if (isSignalLike(val)) {
+			signalBindings.push([prop, val]);
+			const defVal = defaults[prop];
+			cleaned[prop] = typeof defVal === "number" ? defVal : fallback;
+		}
+	}
+	const rawVf = cleaned.volumetricFog;
+	if (rawVf && typeof rawVf === "object") {
+		const vfCopy = { ...rawVf };
+		if (isSignalLike(vfCopy.density)) {
+			signalBindings.push(["volumetricFogDensity", vfCopy.density]);
+			vfCopy.density = .02;
+		}
+		if (isSignalLike(vfCopy.anisotropy)) {
+			signalBindings.push(["volumetricFogAnisotropy", vfCopy.anisotropy]);
+			vfCopy.anisotropy = .55;
+		}
+		if (vfCopy.noise && typeof vfCopy.noise === "object") {
+			const noiseCopy = { ...vfCopy.noise };
+			if (isSignalLike(noiseCopy.strength)) {
+				signalBindings.push(["volumetricFogNoiseStrength", noiseCopy.strength]);
+				noiseCopy.strength = .45;
+			}
+			vfCopy.noise = noiseCopy;
+		}
+		cleaned.volumetricFog = vfCopy;
+	}
+	let node = withAnimation(cleaned);
+	if (signalBindings.length > 0) {
+		const anim = LayerAnimation.create();
+		for (const [prop, sig] of signalBindings) anim.signal(prop, sig);
+		node = node.animate(anim);
+	}
+	return node;
+}
 const Light = {
 	environment: (presetOrOptions = "studio", options = {}) => {
-		const opts = typeof presetOrOptions === "string" ? {
-			preset: presetOrOptions,
-			...options
-		} : {
-			...presetOrOptions,
+		const opts = {
+			...typeof presetOrOptions !== "string" ? presetOrOptions : isHdriPath(presetOrOptions) ? { hdri: presetOrOptions } : { preset: presetOrOptions },
 			...options
 		};
-		return withAnimation({
+		return buildLightNode({
+			id: opts.id ?? autoId("environment"),
 			kind: "light",
 			lightType: "environment",
 			preset: "studio",
-			intensity: 1,
-			...opts,
-			id: opts.id ?? autoId("environment")
-		});
+			intensity: 1
+		}, opts);
 	},
-	ambient: (color$1 = "#ffffff", intensity = .5, options = {}) => withAnimation({
-		id: options.id ?? autoId("light-ambient"),
-		kind: "light",
-		lightType: "ambient",
-		color: typeof color$1 === "string" ? color$1 : color$1.color ?? "#ffffff",
-		intensity,
-		...typeof color$1 === "object" && color$1,
-		...options
-	}),
-	directional: (options = {}) => withAnimation({
+	ambient: (color$1 = "#ffffff", intensity = .5, options = {}) => {
+		const merged = {
+			color: typeof color$1 === "string" ? color$1 : color$1.color ?? "#ffffff",
+			intensity,
+			...typeof color$1 === "object" && color$1,
+			...options
+		};
+		return buildLightNode({
+			id: merged.id ?? autoId("light-ambient"),
+			kind: "light",
+			lightType: "ambient",
+			color: "#ffffff",
+			intensity: .5
+		}, merged);
+	},
+	directional: (options = {}) => buildLightNode({
 		id: options.id ?? autoId("light-directional"),
 		kind: "light",
 		lightType: "directional",
 		color: options.color ?? "#ffffff",
-		intensity: options.intensity ?? 1,
-		x: options.x ?? 0,
-		y: options.y ?? -1e3,
-		z: options.z ?? -1e3,
-		targetX: options.targetX ?? 0,
-		targetY: options.targetY ?? 0,
-		targetZ: options.targetZ ?? 0,
-		...options
-	}),
-	point: (options = {}) => withAnimation({
+		intensity: 1,
+		x: 0,
+		y: -1e3,
+		z: -1e3,
+		targetX: 0,
+		targetY: 0,
+		targetZ: 0
+	}, options),
+	point: (options = {}) => buildLightNode({
 		id: options.id ?? autoId("light-point"),
 		kind: "light",
 		lightType: "point",
 		color: options.color ?? "#ffffff",
-		intensity: options.intensity ?? 1,
-		x: options.x ?? 0,
-		y: options.y ?? 0,
-		z: options.z ?? -500,
-		radius: options.radius ?? 1e3,
-		decay: options.decay ?? 1,
-		...options
-	}),
-	spot: (options = {}) => withAnimation({
+		intensity: 1,
+		x: 0,
+		y: 0,
+		z: -500,
+		radius: 1e3,
+		decay: 1
+	}, options),
+	spot: (options = {}) => buildLightNode({
 		id: options.id ?? autoId("light-spot"),
 		kind: "light",
 		lightType: "spot",
 		color: options.color ?? "#ffffff",
-		intensity: options.intensity ?? 1,
-		x: options.x ?? 0,
-		y: options.y ?? -500,
-		z: options.z ?? -1e3,
-		targetX: options.targetX ?? 0,
-		targetY: options.targetY ?? 0,
-		targetZ: options.targetZ ?? 0,
-		angle: options.angle ?? 45,
-		penumbra: options.penumbra ?? .2,
-		radius: options.radius ?? 2e3,
-		decay: options.decay ?? 1,
-		...options
-	})
+		intensity: 1,
+		x: 0,
+		y: -500,
+		z: -1e3,
+		targetX: 0,
+		targetY: 0,
+		targetZ: 0,
+		angle: 45,
+		penumbra: .2,
+		radius: 2e3,
+		decay: 1
+	}, options),
+	rect: (options = {}) => buildLightNode({
+		id: options.id ?? autoId("light-rect"),
+		kind: "light",
+		lightType: "rect",
+		color: options.color ?? "#ffffff",
+		intensity: 1,
+		x: 0,
+		y: -300,
+		z: -800,
+		targetX: 0,
+		targetY: 0,
+		targetZ: 0,
+		width: 240,
+		height: 140,
+		twoSided: false,
+		radius: 2e3,
+		decay: 1.5
+	}, options)
 };
 function section(source, targetOrOptions = {}, options = {}) {
 	return Layer.section(source, targetOrOptions, options);
@@ -10105,5 +11282,5 @@ const Effect = Object.assign(Effect$1, effectFactories, {
 });
 
 //#endregion
-export { glyphAnimator as $, wordRanges as $t, boilKeys as A, squigglePath as At, defineTheme as B, themes as Bt, audioLevelsSchema as C, span as Cn, scaleFrames as Ct, basePropsSchema as D, FRAMEFIELDS_AI_PROXY_URL as Dn, springKeys as Dt, bandEdges as E, ApiError as En, springAt as Et, constantExpression as F, surfaceFill as Ft, elevationStyle as G, transparent as Gt, drawOnKeys as H, toPathData as Ht, contrastRatio as I, targetPoint as It, evaluateEase as J, windowExpression as Jt, ellipsePath as K, typingFrames as Kt, cover as L, targetSchema as Lt, boxPath as M, staggerRanks as Mt, catmullRom as N, stepExpression as Nt, beats as O, ValidationError as On, springSettleFrames as Ot, chain as P, supersede as Pt, frameSpan as Q, wobblePoints as Qt, defineComponent as R, textLayout as Rt, ascending as S, size as Sn, safeArea as St, bakeSamples as T, sup as Tn, smoothRelease as Tt, ease as U, toSeconds as Ut, dist as V, toFrames as Vt, elevate as W, transformPathData as Wt, exitAnimation as X, withDefaults as Xt, evaluateGlyphExpression as Y, withAlpha as Yt, findRange as Z, within as Zt, after as _, italic as _n, resampleBands as _t, Media as a, PhysicsWorld2D as an, last as at, arcPath as b, parseMarkup as bn, rng as bt, section as c, Layer3D as cn, lineShift as ct, analyzeAudio as d, PersonTrack as dn, offsetCues as dt, Styles as en, hashRng as et, KeyBook as f, DEFAULT_CHART_COLORS as fn, parseColor as ft, UNIT_INDEX as g, color as gn, rendererChars as gt, Track as h, code as hn, rangeRects as ht, Light as i, PhysicsBody2D as in, isLight as it, boundsOf as j, staggerOffsets as jt, bind as k, ai as kn, springTrack as kt, bindComponent as l, Particles as ln, luminance as lt, SAFE_INSETS as m, bold as mn, quantize as mt, Effect as n, PhysicsBody3D as nn, holdFirstKeys as nt, blurRegion as o, Lighting as on, lerp2 as ot, MOTION_PRESETS as p, accent as pn, pulseKeys as pt, enterAnimation as q, valueAt as qt, Layer as r, PhysicsWorld3D as rn, inkOn as rt, editTrackedRegion as s, Transition as sn, linePath as st, Composition as t, Physics as tn, hashString as tt, z$2 as u, ClipVision as un, mix as ut, analyzeChannels as v, mark as vn, resolveMotion as vt, bakeFunction as w, sub as wn, scheduleExpression as wt, arrowPaths as x, rich as xn, round as xt, anchorPoint as y, normalizeTextSpans as yn, resolveTarget as yt, defineMeta as z, themeFrames as zt };
-//# sourceMappingURL=src-DrP7fGJX.mjs.map
+export { glyphAnimator as $, wordRanges as $t, boilKeys as A, FRAMEFIELDS_AI_PROXY_URL as An, squigglePath as At, defineTheme as B, themes as Bt, audioLevelsSchema as C, parseMarkup as Cn, scaleFrames as Ct, basePropsSchema as D, sub as Dn, springKeys as Dt, bandEdges as E, span as En, springAt as Et, constantExpression as F, surfaceFill as Ft, elevationStyle as G, transparent as Gt, drawOnKeys as H, toPathData as Ht, contrastRatio as I, targetPoint as It, evaluateEase as J, windowExpression as Jt, ellipsePath as K, typingFrames as Kt, cover as L, targetSchema as Lt, boxPath as M, ai as Mn, staggerRanks as Mt, catmullRom as N, stepExpression as Nt, beats as O, sup as On, springSettleFrames as Ot, chain as P, supersede as Pt, frameSpan as Q, wobblePoints as Qt, defineComponent as R, textLayout as Rt, ascending as S, normalizeTextSpans as Sn, safeArea as St, bakeSamples as T, size as Tn, smoothRelease as Tt, ease as U, toSeconds as Ut, dist as V, toFrames as Vt, elevate as W, transformPathData as Wt, exitAnimation as X, withDefaults as Xt, evaluateGlyphExpression as Y, withAlpha as Yt, findRange as Z, within as Zt, after as _, bold as _n, resampleBands as _t, Media as a, PhysicsBody2D as an, last as at, arcPath as b, italic as bn, rng as bt, section as c, Transition as cn, lineShift as ct, analyzeAudio as d, ClipVision as dn, offsetCues as dt, Styles as en, hashRng as et, KeyBook as f, PersonTrack as fn, parseColor as ft, UNIT_INDEX as g, accent as gn, rendererChars as gt, Track as h, DEFAULT_CHART_COLORS as hn, rangeRects as ht, Light as i, Fracture3D as in, isLight as it, boundsOf as j, ValidationError as jn, staggerOffsets as jt, bind as k, ApiError as kn, springTrack as kt, bindComponent as l, Layer3D as ln, luminance as lt, SAFE_INSETS as m, retargetPose as mn, quantize as mt, Effect as n, PhysicsBody3D as nn, holdFirstKeys as nt, blurRegion as o, PhysicsWorld2D as on, lerp2 as ot, MOTION_PRESETS as p, RIG_PRESETS as pn, pulseKeys as pt, enterAnimation as q, valueAt as qt, Layer as r, PhysicsWorld3D as rn, inkOn as rt, editTrackedRegion as s, Lighting as sn, linePath as st, Composition as t, Physics as tn, hashString as tt, z$2 as u, Particles as un, mix as ut, analyzeChannels as v, code as vn, resolveMotion as vt, bakeFunction as w, rich as wn, scheduleExpression as wt, arrowPaths as x, mark as xn, round as xt, anchorPoint as y, color as yn, resolveTarget as yt, defineMeta as z, themeFrames as zt };
+//# sourceMappingURL=src-CoHAjviq.mjs.map