Skip to content

Code-first video & image, rendered natively on WebGPU.

30.8 KB
Raw Blame
import { resolveLayerDuration } from "@framefields/compositions";
import {
	type AnimationTrack,
	collectNodeOps,
	evaluateTrackAtFrame,
	type LayerAnimationSpec,
	mappedEase,
	sampleTrack,
} from "@framefields/compositions/program";
import {
	DEFAULT_DURATION_MS,
	getActiveMediaMetadata,
	reportRenderDiagnostic,
	type VirtualMediaData,
} from "@framefields/core";
import gsapModule from "gsap";

const gsap = (gsapModule as any).timeline
	? gsapModule
	: (gsapModule as any).default || gsapModule;

export interface LayerStub {
	id: string;
	inputHandleId: string;
	trackId?: string;
	x: number;
	y: number;
	scale: number;
	rotation: number;
	opacity: number;
	volume: number;
	width?: number;
	height?: number;
	hidden: boolean;
	muted: boolean;
	text?: number;
	fontSize?: number;
	fill?: string;
	borderColor?: string;
	backgroundColor?: string;
	rotateX?: number;
	rotateY?: number;
	rotateZ?: number;
	perspective?: number;
	perspectiveOriginX?: number;
	perspectiveOriginY?: number;
	translateZ?: number;
	backfaceVisibility?: "visible" | "hidden";
	transformStyle?: "flat" | "preserve-3d";
	// 3D Layer Props
	is3D?: boolean;
	z?: number;
	scaleZ?: number;
	twoSided?: boolean;
	// 3D Material Props
	material?: "lit" | "unlit" | "toon";
	shininess?: number;
	roughness?: number;
	specularIntensity?: number;
	ambientIntensity?: number;
	metallic?: number;
	emissive?: string;
	emissiveIntensity?: number;
	clearcoat?: number;
	clearcoatRoughness?: number;
	anisotropy?: number;
	anisotropyRotation?: number;
	subsurface?: number;
	subsurfaceColor?: string;
	sheen?: number;
	sheenColor?: string;
	sheenRoughness?: number;
	iridescence?: number | Record<string, unknown>;
	iridescenceThickness?: number;
	iridescenceIor?: number;
	triplanar?: boolean | Record<string, unknown>;
	triplanarScale?: number;
	triplanarSharpness?: number;
	// 3D Camera Props
	cameraX?: number;
	cameraY?: number;
	cameraZ?: number;
	targetX?: number;
	targetY?: number;
	targetZ?: number;
	cameraPitch?: number;
	cameraYaw?: number;
	cameraRoll?: number;
	cameraFov?: number;
	cameraZoom?: number;
	focalLength?: number;
	focusDistance?: number;
	fStop?: number;
	maxBlurRadius?: number;
	shakeTranslation?: number;
	shakeRotation?: number;
	relativitySpeed?: number;
	orbitRadius?: number;
	orbitAzimuth?: number;
	orbitElevation?: number;
	// 3D Model Props
	animationProgress?: number;
	animationTime?: number;
	animationSpeed?: number;
	wireframe?: boolean;
	scaleX?: number;
	scaleY?: number;
	// 3D Light Props
	lightType?: string;
	color?: string;
	intensity?: number;
	radius?: number;
	angle?: number;
	penumbra?: number;
	decay?: number;
	exposure?: number;
	volumetricFogDensity?: number;
	volumetricFogAnisotropy?: number;
	volumetricFogNoiseStrength?: number;
	[key: string]: unknown;
}

export type CompilerVirtualMedia = {
	metadata?: Partial<VirtualMediaData["metadata"]>;
	operation?: Partial<VirtualMediaData["operation"]> & Record<string, any>;
	children?: CompilerNodeVM[];
};

/** A node op inside the render tree (CompositorLayer). */
export type CompilerNodeVM = CompilerVirtualMedia;

export interface CompileResult {
	/** Render id plus a hash of the compiled nodes: one composition's identity across frames. */
	key: string;
	tl: gsap.core.Timeline;
	targetsById: Record<string, LayerStub>;
	/** Node ops the timeline was compiled from (tree order). */
	nodes: CompilerNodeVM[];
	/**
	 * Signal-driven tracks, evaluated at draw time instead of baked into the
	 * timeline: a signal may be filled while rendering (a live physics world,
	 * on-demand vision), so its value is read when its frame is drawn.
	 */
	live: LiveTrack[];
	signals?: Record<string, any>;
}

interface LiveTrack {
	stub: Record<string, any>;
	track: AnimationTrack;
	startFrame: number;
	endFrame: number;
	/** Stepped timing: the track is read only every `step` frames. */
	step?: number;
}

/** Seeks the compiled timeline to a frame and applies its live signal tracks. */
export function seekTimeline(
	result: CompileResult,
	frame: number,
	fps: number,
): void {
	result.tl.seek(frame / fps);
	for (const live of result.live) {
		let f = Math.max(live.startFrame, Math.min(live.endFrame, frame));
		if (live.step && live.step > 1) {
			f =
				live.startFrame +
				Math.floor((f - live.startFrame) / live.step) * live.step;
		}
		live.stub[live.track.prop] = sampleTrack(live.track, f, fps, {
			startFrame: live.startFrame,
			base: live.stub,
			signals: result.signals,
		});
	}
}

// L2: compiled timelines and their LayerStubs are cached per cacheKey and
// SHARED across frames — `tl.seek()` mutates the stubs in place. This is safe
// because frame rendering is strictly single-threaded per renderId, and the
// 10s TTL bounds staleness. Do NOT render two frames of the same renderId
// concurrently without cloning `tl` + stubs first.
const cache = new Map<string, { cacheTime: number; value: CompileResult }>();

// L1: hashing the layer ops stringifies every keyframe of every layer, which
// costs tens of ms per frame on a full film. Programs are rebuilt (not mutated)
// when a composition changes, so that hash is memoized on the children array:
// the operation itself is shallow-copied each frame to bake in signal values,
// but `children` keeps its identity. Signals are cheap to key and may be plain
// data mutated in place, so they are re-keyed on every call.
const nodesHashMemo = new WeakMap<
	object,
	{
		width: number;
		height: number;
		fps: number;
		durationSec: number;
		hash: string;
	}
>();

/** Entries untouched for this long are dropped (and their timeline killed). */
const CACHE_TTL_MS = 10000;
/** Max compiled timelines retained per cache. */
const TIMELINE_CACHE_MAX = 50;
const LAYER_TIMELINE_CACHE_MAX = 50;

function fnv1a(str: string): string {
	let hash = 2166136261;
	for (let i = 0; i < str.length; i++) {
		hash ^= str.charCodeAt(i);
		hash +=
			(hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24);
	}
	return (hash >>> 0).toString(16);
}

// Signal objects carry per-frame caches (last frame, last value), so hashing
// their contents gives a new key every frame: the timeline would recompile
// each frame and the cache would never hit. Key live signals by identity.
const signalIds = new WeakMap<object, number>();
let nextSignalId = 0;

function signalsKey(signals: unknown): string {
	if (!signals || typeof signals !== "object") return stableStringify(signals);
	return Object.keys(signals)
		.sort()
		.map((name) => {
			const s = (signals as Record<string, unknown>)[name];
			if (
				s &&
				typeof s === "object" &&
				typeof (s as { get?: unknown }).get === "function"
			) {
				let id = signalIds.get(s);
				if (id === undefined) {
					id = nextSignalId++;
					signalIds.set(s, id);
				}
				return `${JSON.stringify(name)}:#${id}`;
			}
			return `${JSON.stringify(name)}:${stableStringify(s)}`;
		})
		.join(",");
}

/**
 * Paused gsap timelines stay attached to gsap's global timeline until killed,
 * so anything dropped from a cache must be killed or it is never collected.
 */
function release(value: { tl: gsap.core.Timeline }): void {
	value.tl.kill();
}

/**
 * Make room for one insertion: drop and kill TTL-expired entries, then evict
 * the least-recently-used entry if the cache is at capacity. Every dropped
 * timeline MUST be killed — see `release`.
 */
function evictForInsert<T extends { tl: gsap.core.Timeline }>(
	cache: Map<string, { cacheTime: number; value: T }>,
	maxSize: number,
): void {
	const now = Date.now();
	for (const [key, entry] of cache.entries()) {
		if (now - entry.cacheTime > CACHE_TTL_MS) {
			cache.delete(key);
			release(entry.value);
		}
	}
	if (cache.size >= maxSize) {
		const oldestKey = cache.keys().next().value;
		if (oldestKey !== undefined) {
			const oldest = cache.get(oldestKey);
			cache.delete(oldestKey);
			if (oldest) release(oldest.value);
		}
	}
}

function stableStringify(obj: any): string {
	if (obj === null) return "null";
	if (obj === undefined) return "undefined";
	if (typeof obj !== "object") return JSON.stringify(obj);
	if (ArrayBuffer.isView(obj)) {
		return `[TypedArray:${(obj as ArrayBufferView).byteLength}]`;
	}
	if (Array.isArray(obj)) {
		return "[" + obj.map(stableStringify).join(",") + "]";
	}
	const sortedKeys = Object.keys(obj).sort();
	const parts = sortedKeys.map((key) => {
		return `${JSON.stringify(key)}:${stableStringify(obj[key])}`;
	});
	return "{" + parts.join(",") + "}";
}

export function getCachedTimeline(cacheKey: string): CompileResult | undefined {
	const entry = cache.get(cacheKey);
	if (entry) {
		if (Date.now() - entry.cacheTime > CACHE_TTL_MS) {
			cache.delete(cacheKey);
			release(entry.value);
			return undefined;
		}
		entry.cacheTime = Date.now();
		cache.delete(cacheKey);
		cache.set(cacheKey, entry);
		return entry.value;
	}
	return undefined;
}

export function setCachedTimeline(cacheKey: string, value: CompileResult) {
	evictForInsert(cache, TIMELINE_CACHE_MAX);
	cache.set(cacheKey, { cacheTime: Date.now(), value });
}

/** Props that switch rather than tween: each key is a set from its frame on. */
const DISCRETE_PROPS: ReadonlySet<string> = new Set(["hidden", "muted"]);

function compileTrackToTimeline(
	tl: gsap.core.Timeline,
	stub: Record<string, any>,
	track: AnimationTrack,
	startFrame: number,
	fps: number,
	durationFrames: number,
	signals?: Record<string, any>,
	live?: LiveTrack[],
	step?: number,
): { dropped: number; maxAuthoredFrame: number } {
	const prop = track.prop;
	const source = track.source ?? { type: "keyframe" };
	const stepped = step !== undefined && step > 1;

	// Signal tracks, path morphs (GSAP cannot tween an SVG path) and every
	// track of a stepped layer are evaluated at draw time rather than baked
	// into the GSAP timeline.
	if (
		(source.type === "signal" || stepped || prop === "d") &&
		live &&
		!track.repeat
	) {
		const endF = Number.isFinite(durationFrames)
			? durationFrames
			: Math.round(fps * 5);
		const entry: LiveTrack = {
			stub,
			track,
			startFrame,
			endFrame: startFrame + endF,
			...(stepped && { step }),
		};
		stub[prop] = sampleTrack(track, startFrame, fps, {
			startFrame,
			base: stub,
			signals,
		});
		live.push(entry);
		return { dropped: 0, maxAuthoredFrame: 0 };
	}

	if (source.type !== "keyframe") {
		const endF = Number.isFinite(durationFrames)
			? durationFrames
			: Math.round(fps * 5);
		const frameStepSec = 1 / fps;
		const kfList: Array<Record<string, unknown>> = [];

		const firstVal = evaluateTrackAtFrame(track, startFrame, fps, {
			startFrame,
			baseValues: stub,
			signals,
		});
		stub[prop] = firstVal;
		kfList.push({
			[prop]: firstVal,
			duration: 0,
		});

		for (let f = 1; f <= endF; f++) {
			const val = evaluateTrackAtFrame(track, startFrame + f, fps, {
				startFrame,
				baseValues: stub,
				signals,
			});
			kfList.push({
				[prop]: val,
				duration: frameStepSec,
				ease: "none",
			});
		}

		tl.to(
			stub,
			{
				keyframes: kfList,
				repeat: track.repeat ?? 0,
				yoyo: !!track.yoyo,
				lazy: false,
				overwrite: false,
				immediateRender: false,
			},
			startFrame / fps,
		);

		return { dropped: 0, maxAuthoredFrame: 0 };
	}

	const sortedKeyframes = [...track.keyframes].sort(
		(a, b) => a.frame - b.frame,
	);
	// M8: keyframes outside the clip window [0, durationFrames] cannot play —
	// keep the clamp (the renderer's temporal gate clips the same window) but
	// REPORT it: an author who keys past the node's duration otherwise gets a
	// silent static mid-animation with no diagnostic.
	const validKeyframes = sortedKeyframes.filter(
		(kf) => kf.frame >= 0 && kf.frame <= durationFrames,
	);
	const dropped = sortedKeyframes.length - validKeyframes.length;
	const maxAuthoredFrame =
		dropped > 0 ? sortedKeyframes[sortedKeyframes.length - 1].frame : 0;

	if (validKeyframes.length === 0) {
		return { dropped, maxAuthoredFrame };
	}

	const isDiscrete = DISCRETE_PROPS.has(prop);

	if (isDiscrete) {
		for (const kf of validKeyframes) {
			const absoluteSec = (startFrame + kf.frame) / fps;
			tl.set(
				stub,
				{
					[prop]: kf.value,
					immediateRender: false,
				},
				absoluteSec,
			);
		}
	} else {
		const repeat = track.repeat ?? 0;
		const yoyo = !!track.yoyo;

		if (validKeyframes.length === 1) {
			const kf0 = validKeyframes[0];
			const absoluteSec = (startFrame + kf0.frame) / fps;
			tl.set(
				stub,
				{
					[prop]: kf0.value,
					immediateRender: false,
				},
				absoluteSec,
			);
		} else if (validKeyframes.length === 2) {
			const kf0 = validKeyframes[0];
			const kf1 = validKeyframes[1];
			const val0 = kf0.value;
			const val1 = kf1.value;
			const startSec = (startFrame + kf0.frame) / fps;
			const durSec = (kf1.frame - kf0.frame) / fps;
			const trackDurationFrames = track.durationFrames ?? kf1.frame - kf0.frame;
			const easeRef = kf1.ease ?? kf0.ease;
			const easeVal = mappedEase(easeRef, trackDurationFrames, fps);

			if (val0 === stub[prop]) {
				tl.to(
					stub,
					{
						[prop]: val1,
						duration: durSec,
						ease: easeVal,
						repeat,
						yoyo,
						lazy: false,
						overwrite: false,
						immediateRender: false,
					},
					startSec,
				);
			} else {
				tl.fromTo(
					stub,
					{
						[prop]: val0,
					},
					{
						[prop]: val1,
						duration: durSec,
						ease: easeVal,
						repeat,
						yoyo,
						lazy: false,
						overwrite: false,
						immediateRender: false,
					},
					startSec,
				);
			}
		} else {
			const kf0 = validKeyframes[0];
			const startSec = (startFrame + kf0.frame) / fps;

			const kfList: Array<Record<string, unknown>> = [];
			kfList.push({
				[prop]: kf0.value,
				duration: 0,
			});

			for (let i = 1; i < validKeyframes.length; i++) {
				const prevKf = validKeyframes[i - 1];
				const currKf = validKeyframes[i];
				const deltaFrames = currKf.frame - prevKf.frame;
				const durSec = deltaFrames / fps;
				const easeVal = mappedEase(currKf.ease, deltaFrames, fps);

				kfList.push({
					[prop]: currKf.value,
					duration: durSec,
					ease: easeVal,
				});
			}

			tl.to(
				stub,
				{
					keyframes: kfList,
					repeat,
					yoyo,
					lazy: false,
					overwrite: false,
					immediateRender: false,
				},
				startSec,
			);
		}
	}

	return { dropped, maxAuthoredFrame };
}

// ── M8: truncated-track diagnostics ───────────────────────────────────

export interface TruncationInfo {
	layerId: string;
	trackId: string;
	prop: string;
	dropped: number;
	maxAuthoredFrame: number;
}

/** A camera's `x` / `y` / `z` are its eye, the same as `cameraX` / `cameraY` / `cameraZ`. */
const CAMERA_EYE: Readonly<Record<string, AnimationTrack["prop"]>> = {
	x: "cameraX",
	y: "cameraY",
	z: "cameraZ",
};

/**
 * A layer's tracks, with a camera's `x` / `y` / `z` tracks driving its eye:
 * the eye is read from `cameraX` / `cameraY` / `cameraZ`, which the static
 * `x` / `y` / `z` seed, so a track left on `x` would never move it.
 */
function layerTracks(lop: {
	kind?: string;
	animation?: { tracks?: AnimationTrack[] };
}): AnimationTrack[] {
	const tracks = lop.animation?.tracks ?? [];
	if (lop.kind !== "camera") return tracks;
	return tracks.map((t) => {
		const eye = CAMERA_EYE[t.prop];
		return eye ? { ...t, prop: eye } : t;
	});
}

/**
 * Dedupe per compiled cache key — a fresh render of the same broken doc SHOULD
 * re-warn. Single-frame renders are the exception: each `renderFrame` call has
 * its own `img-` render id, so probing a doc frame by frame would repeat the
 * warning on every frame; those dedupe per document instead.
 */
const truncationWarnedKeys = new Set<string>();
const TRUNCATION_WARNED_CAP = 100;

function warnTruncationOnce(cacheKey: string, truncations: TruncationInfo[]) {
	if (truncationWarnedKeys.has(cacheKey)) return;
	if (truncationWarnedKeys.size >= TRUNCATION_WARNED_CAP) {
		truncationWarnedKeys.clear();
	}
	truncationWarnedKeys.add(cacheKey);

	const details = truncations
		.map(
			(t) =>
				`'${t.prop}' (track '${t.trackId}') on '${t.layerId}': ${t.dropped} keyframe(s) past the clip window (last authored frame ${t.maxAuthoredFrame})`,
		)
		.join("; ");
	console.warn(
		`[compositor] ${truncations.length} track(s) truncated — animation tails will not play: ${details}. Extend durationFrames or move those keyframes.`,
	);
}

function hashNodes(
	nodeOps: CompilerNodeVM[],
	width: number,
	height: number,
	fps: number,
	durationSec: number,
): string {
	const irHashInput = stableStringify({
		nodes: nodeOps.map((vm) => {
			const lop = (vm?.operation || {}) as any;
			return {
				id: lop.id,
				animation: lop.animation,
				startFrame: lop.startFrame,
				durationFrames: lop.durationFrames,
				x: lop.x,
				y: lop.y,
				scale: lop.scale,
				rotation: lop.rotation,
				opacity: lop.opacity,
				volume: lop.volume,
				width: lop.width,
				height: lop.height,
				hidden: lop.hidden,
				muted: lop.muted,
				backgroundColor: lop.backgroundColor,
				fill: lop.fill,
				borderColor: lop.borderColor,
				textBackgroundColor: lop.textBackgroundColor,
				rotateX: lop.rotateX,
				rotateY: lop.rotateY,
				rotateZ: lop.rotateZ,
				perspective: lop.perspective,
				perspectiveOriginX: lop.perspectiveOriginX,
				perspectiveOriginY: lop.perspectiveOriginY,
				translateZ: lop.translateZ,
				backfaceVisibility: lop.backfaceVisibility,
				transformStyle: lop.transformStyle,
				is3D: lop.is3D,
				z: lop.z,
				scaleZ: lop.scaleZ,
				twoSided: lop.twoSided,
				cameraX: lop.cameraX,
				cameraY: lop.cameraY,
				cameraZ: lop.cameraZ,
				targetX: lop.targetX,
				targetY: lop.targetY,
				targetZ: lop.targetZ,
				cameraPitch: lop.cameraPitch,
				cameraYaw: lop.cameraYaw,
				cameraRoll: lop.cameraRoll,
				cameraFov: lop.cameraFov,
				cameraZoom: lop.cameraZoom,
				focalLength: lop.focalLength,
				focusDistance: lop.focusDistance,
				fStop: lop.fStop,
				maxBlurRadius: lop.maxBlurRadius,
				shakeTranslation: lop.shakeTranslation,
				shakeRotation: lop.shakeRotation,
				relativitySpeed: lop.relativitySpeed,
				orbitRadius: lop.orbitRadius,
				orbitAzimuth: lop.orbitAzimuth,
				orbitElevation: lop.orbitElevation,
				// 3D Material Props
				material: lop.material,
				shininess: lop.shininess,
				roughness: lop.roughness,
				specularIntensity: lop.specularIntensity,
				ambientIntensity: lop.ambientIntensity,
				metallic: lop.metallic,
				emissive: lop.emissive,
				emissiveIntensity: lop.emissiveIntensity,
				clearcoat: lop.clearcoat,
				clearcoatRoughness: lop.clearcoatRoughness,
				anisotropy: lop.anisotropy,
				anisotropyRotation: lop.anisotropyRotation,
				subsurface: lop.subsurface,
				subsurfaceColor: lop.subsurfaceColor,
				sheen: lop.sheen,
				sheenColor: lop.sheenColor,
				sheenRoughness: lop.sheenRoughness,
				iridescence: lop.iridescence,
				iridescenceThickness: lop.iridescenceThickness,
				iridescenceIor: lop.iridescenceIor,
				triplanar: lop.triplanar,
				triplanarScale: lop.triplanarScale,
				triplanarSharpness: lop.triplanarSharpness,
				// 3D Light Props
				lightType: lop.lightType,
				color: lop.color,
				intensity: lop.intensity,
				radius: lop.radius,
				angle: lop.angle,
				penumbra: lop.penumbra,
				exposure: lop.exposure,
				hdri: typeof lop.hdri === "string" ? lop.hdri : Boolean(lop.hdri),
				volumetricFog: lop.volumetricFog,
				volumetricFogDensity: lop.volumetricFogDensity,
				volumetricFogAnisotropy: lop.volumetricFogAnisotropy,
				volumetricFogNoiseStrength: lop.volumetricFogNoiseStrength,
				// 3D Model Props
				animationProgress: lop.animationProgress,
				animationTime: lop.animationTime,
				animationSpeed: lop.animationSpeed,
				wireframe: lop.wireframe,
				scaleX: lop.scaleX,
				scaleY: lop.scaleY,
				// The LayerStub bakes fontSize (compiler.ts:425) and both the
				// layout measure and the text draw prefer the stub's value
				// over the live op — a fontSize change MUST bust the cache or
				// the rendered text keeps the stale size for the whole TTL.
				fontSize: lop.fontSize,
				text: lop.text,
			};
		}),
		width,
		height,
		fps,
		durationSec,
	});
	return fnv1a(irHashInput);
}

export function compileTimeline(
	renderId: string,
	virtualMedia: CompilerVirtualMedia | null | undefined,
	options: { fps: number; durationSec: number },
): CompileResult {
	const fps = options.fps;
	const durationSec = options.durationSec;
	const width = virtualMedia?.metadata?.width ?? 1920;
	const height = virtualMedia?.metadata?.height ?? 1080;

	// Collect node ops from the render tree (pre-order: parents first).
	const nodeOps = collectNodeOps((virtualMedia?.children as any) ?? []);

	// LRU cache check
	const memoKey = virtualMedia?.children as object | undefined;
	const memo = memoKey ? nodesHashMemo.get(memoKey) : undefined;
	let nodesHash: string;
	if (
		memo &&
		memo.width === width &&
		memo.height === height &&
		memo.fps === fps &&
		memo.durationSec === durationSec
	) {
		nodesHash = memo.hash;
	} else {
		nodesHash = hashNodes(nodeOps, width, height, fps, durationSec);
		if (memoKey) {
			nodesHashMemo.set(memoKey, {
				width,
				height,
				fps,
				durationSec,
				hash: nodesHash,
			});
		}
	}
	const irHash = fnv1a(
		`${nodesHash}|${signalsKey((virtualMedia as any)?.operation?.signals ?? (virtualMedia as any)?.signals)}`,
	);
	const cacheKey = `${renderId}_${irHash}`;

	const cached = getCachedTimeline(cacheKey);
	if (cached) {
		return cached;
	}

	const tl = gsap.timeline({ paused: true, smoothChildTiming: false });
	const targetsById: Record<string, LayerStub> = {};
	const signals =
		(virtualMedia as any)?.operation?.signals ??
		(virtualMedia as any)?.signals ??
		{};

	nodeOps.forEach((vm, index: number) => {
		const lop = (vm?.operation || {}) as any;
		const layerId = lop.id || lop.inputHandleId || `layer_${index}`;

		const stub: LayerStub = {
			id: layerId,
			inputHandleId: lop.inputHandleId || `layer_${index}`,
			trackId: layerId,
			x:
				lop.kind === "camera" || lop.kind === "light"
					? (lop.x ?? lop.cameraX)
					: (lop.x ?? 0),
			y:
				lop.kind === "camera" || lop.kind === "light"
					? (lop.y ?? lop.cameraY)
					: (lop.y ?? 0),
			scale: lop.scale ?? 1,
			rotation: lop.rotation ?? 0,
			opacity: lop.opacity ?? 1,
			volume: lop.volume ?? 1,
			width: lop.width,
			height: lop.height,
			hidden: !!lop.hidden,
			muted: !!lop.muted,
			rotateX: lop.rotateX ?? 0,
			rotateY: lop.rotateY ?? 0,
			rotateZ: lop.rotateZ ?? 0,
			perspective: lop.perspective ?? 0,
			perspectiveOriginX: lop.perspectiveOriginX ?? 0.5,
			perspectiveOriginY: lop.perspectiveOriginY ?? 0.5,
			translateZ: lop.translateZ ?? 0,
			backfaceVisibility: lop.backfaceVisibility ?? "visible",
			transformStyle: lop.transformStyle ?? "flat",
			fontSize: lop.fontSize,
			text: 1,
			fill: lop.fill,
			fillColor: lop.fillColor ?? lop.fill,
			strokeColor: lop.strokeColor ?? lop.stroke,
			strokeWidth: lop.strokeWidth,
			letterSpacing: lop.letterSpacing,
			firstMargin: lop.firstMargin ?? lop.pathOptions?.firstMargin,
			lastMargin: lop.lastMargin ?? lop.pathOptions?.lastMargin,
			baselineShift: lop.baselineShift ?? lop.pathOptions?.baselineShift,
			offset: lop.offset,
			rangeStart: lop.rangeStart,
			rangeEnd: lop.rangeEnd,
			animators: lop.animators,
			pathOptions: lop.pathOptions,
			typewriter: lop.typewriter,
			marquee: lop.marquee,
			// 3D Layer Props
			is3D:
				lop.is3D ??
				(lop.kind === "camera" || lop.kind === "light" || lop.kind === "model3d"
					? true
					: false),
			z: lop.z ?? (lop.kind === "camera" ? (lop.z ?? -1500) : 0),
			scaleZ: lop.scaleZ ?? 1,
			twoSided: lop.twoSided ?? lop.kind !== "light",
			// 3D Material Props
			material: lop.material,
			shininess: lop.shininess,
			roughness: lop.roughness,
			specularIntensity: lop.specularIntensity,
			ambientIntensity: lop.ambientIntensity,
			metallic: lop.metallic,
			emissive: lop.emissive,
			emissiveIntensity: lop.emissiveIntensity,
			clearcoat: lop.clearcoat,
			clearcoatRoughness: lop.clearcoatRoughness,
			anisotropy: lop.anisotropy,
			anisotropyRotation: lop.anisotropyRotation,
			subsurface: lop.subsurface,
			subsurfaceColor: lop.subsurfaceColor,
			sheen: lop.sheen,
			sheenColor: lop.sheenColor,
			sheenRoughness: lop.sheenRoughness,
			iridescence: lop.iridescence,
			iridescenceThickness: lop.iridescenceThickness,
			iridescenceIor: lop.iridescenceIor,
			triplanar: lop.triplanar,
			triplanarScale: lop.triplanarScale,
			triplanarSharpness: lop.triplanarSharpness,
			// 3D Model Props
			animationProgress: lop.animationProgress ?? 0,
			animationTime: lop.animationTime ?? 0,
			animationSpeed: lop.animationSpeed ?? 1,
			wireframe: lop.wireframe ?? false,
			scaleX: lop.scaleX ?? 1,
			scaleY: lop.scaleY ?? 1,
			// 3D Camera Props
			cameraX: lop.cameraX ?? (lop.kind === "camera" ? lop.x : undefined),
			cameraY: lop.cameraY ?? (lop.kind === "camera" ? lop.y : undefined),
			cameraZ: lop.cameraZ ?? (lop.kind === "camera" ? lop.z : undefined),
			targetX: lop.targetX,
			targetY: lop.targetY,
			targetZ: lop.targetZ,
			cameraPitch: lop.cameraPitch ?? lop.pitch ?? 0,
			cameraYaw: lop.cameraYaw ?? lop.yaw ?? 0,
			cameraRoll: lop.cameraRoll ?? lop.roll ?? 0,
			cameraFov: lop.cameraFov ?? lop.lens?.fov ?? 50,
			cameraZoom: lop.cameraZoom ?? lop.lens?.zoom ?? 1,
			focalLength: lop.focalLength ?? lop.lens?.focalLength ?? 50,
			focusDistance: lop.focusDistance ?? lop.dof?.focusDistance,
			fStop: lop.fStop ?? lop.dof?.fStop ?? 2.8,
			maxBlurRadius: lop.maxBlurRadius ?? lop.dof?.maxBlurRadius ?? 24,
			shakeTranslation:
				lop.shakeTranslation ??
				(lop.shake?.enabled ? (lop.shake?.translationAmplitude ?? 0) : 0),
			shakeRotation:
				lop.shakeRotation ??
				(lop.shake?.enabled ? (lop.shake?.rotationAmplitude ?? 0) : 0),
			relativitySpeed: lop.relativitySpeed ?? lop.relativity?.speed ?? 0,
			orbitRadius: lop.orbitRadius,
			orbitAzimuth: lop.orbitAzimuth,
			orbitElevation: lop.orbitElevation,
			// 3D Light Props
			lightType: lop.lightType,
			color: lop.color,
			intensity: lop.intensity ?? (lop.kind === "light" ? 1 : undefined),
			radius: lop.radius,
			angle: lop.angle,
			penumbra: lop.penumbra,
			decay: lop.decay,
			exposure: lop.exposure,
			volumetricFogDensity: lop.volumetricFogDensity,
			volumetricFogAnisotropy: lop.volumetricFogAnisotropy,
			volumetricFogNoiseStrength: lop.volumetricFogNoiseStrength,
		};

		for (const track of layerTracks(lop)) {
			const source = track.source ?? { type: "keyframe" };
			if (source.type !== "keyframe") {
				(stub as Record<string, unknown>)[track.prop] = evaluateTrackAtFrame(
					track,
					lop.startFrame ?? 0,
					fps,
					{ startFrame: lop.startFrame ?? 0, baseValues: stub, signals },
				);
			} else if (track.keyframes && track.keyframes.length > 0) {
				const keyframes: AnimationTrack["keyframes"] = track.keyframes;
				const first = keyframes.reduce((a, b) => (b.frame < a.frame ? b : a));
				const seeded = stub as Record<string, unknown>;
				if (!DISCRETE_PROPS.has(track.prop) || first.frame === 0) {
					// Until its first key a track holds that key's value, as the
					// program evaluator does for draw-time tracks: an entrance keyed
					// at frame 40 waits in its first pose, it doesn't show the
					// layer's resting value and then jump.
					seeded[track.prop] = first.value;
				} else if (seeded[track.prop] === undefined) {
					// Discrete props step like sets: the node's own value until the
					// first key. GSAP only tweens props its target has.
					seeded[track.prop] = lop[track.prop] ?? first.value;
				}
			}
		}

		targetsById[layerId] = stub;
	});

	// M8: keyframes beyond the clip window are clamped, but silently — a track
	// whose tail was truncated plays a static value with no diagnostic. Collect
	// them here and warn ONCE per compiled cache key (per-frame seeks hit the
	// cache, so this is naturally once per render/preview session).
	const truncations: TruncationInfo[] = [];
	const live: LiveTrack[] = [];

	nodeOps.forEach((vm) => {
		const lop = (vm?.operation || {}) as any;
		const layerId = lop.id || lop.inputHandleId;
		const stub = layerId ? targetsById[layerId] : undefined;
		if (!stub) return;

		const startFrame = lop.startFrame ?? 0;
		let durationFrames = lop.durationFrames;
		if (durationFrames === undefined) {
			const child = vm.children?.[0];
			const childMeta = child ? getActiveMediaMetadata(child as any) : null;
			const composeDuration =
				(virtualMedia as any)?.metadata?.durationMs ?? DEFAULT_DURATION_MS;
			const layerType =
				lop.type ??
				(lop.kind === "text"
					? "Text"
					: lop.kind === "media"
						? child
							? (child.operation as any)?.dataType
							: undefined
						: undefined);
			const durationMs = resolveLayerDuration(
				undefined,
				childMeta?.durationMs ?? undefined,
				composeDuration,
				layerType,
			);
			durationFrames = Math.max(1, Math.round((durationMs / 1000) * fps));
		}

		for (const track of layerTracks(lop)) {
			const { dropped, maxAuthoredFrame } = compileTrackToTimeline(
				tl,
				stub,
				track,
				startFrame,
				fps,
				durationFrames,
				signals,
				live,
				lop.animation?.frameStep,
			);
			if (dropped > 0) {
				truncations.push({
					layerId,
					trackId: track.id,
					prop: track.prop,
					dropped,
					maxAuthoredFrame,
				});
			}
		}
	});

	if (truncations.length > 0) {
		warnTruncationOnce(
			renderId.startsWith("img-") ? `frame_${irHash}` : cacheKey,
			truncations,
		);
		for (const t of truncations) {
			reportRenderDiagnostic(renderId, {
				severity: "warning",
				code: "animation_truncated",
				layerId: t.layerId,
				message: `'${t.prop}' on '${t.layerId}': ${t.dropped} keyframe(s) past the clip window (last authored frame ${t.maxAuthoredFrame}) never play`,
			});
		}
	}

	tl.seek(1e-6);
	tl.seek(0);

	const compileResult: CompileResult = {
		key: cacheKey,
		tl,
		targetsById,
		nodes: nodeOps,
		live,
		signals,
	};

	setCachedTimeline(cacheKey, compileResult);

	return compileResult;
}

const layerTimelineCache = new Map<
	string,
	{
		cacheTime: number;
		value: {
			tl: gsap.core.Timeline;
			stub: { volume: number; muted: boolean };
		};
	}
>();

export function compileLayerTimeline(
	layerId: string,
	animation: LayerAnimationSpec | undefined,
	baseVolume: number,
	baseMuted: boolean,
	fps: number,
): { tl: gsap.core.Timeline; stub: { volume: number; muted: boolean } } {
	const irHashInput = stableStringify({
		animation,
		baseVolume,
		baseMuted,
		fps,
	});
	const irHash = fnv1a(irHashInput);
	const cacheKey = `layer_${layerId}_${irHash}`;

	const cached = layerTimelineCache.get(cacheKey);
	if (cached) {
		if (Date.now() - cached.cacheTime <= CACHE_TTL_MS) {
			cached.cacheTime = Date.now();
			return cached.value;
		}
		layerTimelineCache.delete(cacheKey);
		release(cached.value);
	}

	const tl = gsap.timeline({ paused: true, smoothChildTiming: false });
	const stub = {
		volume: baseVolume,
		muted: baseMuted,
	};

	const tracks: AnimationTrack[] = animation?.tracks ?? [];
	for (const track of tracks) {
		const prop = track.prop;
		if (prop !== "volume" && prop !== "muted") continue;
		compileTrackToTimeline(tl, stub, track, 0, fps, Infinity);
	}

	tl.seek(1e-6);
	tl.seek(0);

	const result = { tl, stub };
	evictForInsert(layerTimelineCache, LAYER_TIMELINE_CACHE_MAX);
	layerTimelineCache.set(cacheKey, { cacheTime: Date.now(), value: result });
	return result;
}