Code-first video & image, rendered natively on WebGPU.
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;
}