reframe-video 0.1.2 → 0.2.0

package/dist/cli.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env tsx
 
 // ../render-cli/src/cli.ts
-import { mkdtemp as mkdtemp2, readFile as readFile4, rm as rm2 } from "node:fs/promises";
-import { tmpdir as tmpdir3 } from "node:os";
-import { basename, dirname as dirname6, join as join5, resolve as resolve4 } from "node:path";
+import { mkdtemp as mkdtemp3, readFile as readFile4, rm as rm3 } from "node:fs/promises";
+import { tmpdir as tmpdir4 } from "node:os";
+import { basename, dirname as dirname7, join as join6, resolve as resolve4 } from "node:path";
 
 // ../core/src/ir.ts
+var DEFAULT_CROSSFADE = 0.5;
 var DEFAULT_TO_DURATION = 0.5;
 var DEFAULT_TWEEN_DURATION = 0.5;
 var DEFAULT_MOTIONPATH_DURATION = 1;
@@ -32,7 +33,7 @@ function segCountOf(points, closed) {
   if (n < 2) return 0;
   return closed ? n : n - 1;
 }
-function pathPoint(points, closed, u) {
+function pathPoint(points, closed, u, curviness = 1) {
   const n = points.length;
   if (n === 0) return [0, 0];
   if (n === 1) return [points[0][0], points[0][1]];
@@ -41,19 +42,41 @@ function pathPoint(points, closed, u) {
   const [p0, p1, p2, p3] = controls(points, closed, i);
   const t2 = t * t;
   const t3 = t2 * t;
-  const f = (a, b, c, d) => 0.5 * (2 * b + (-a + c) * t + (2 * a - 5 * b + 4 * c - d) * t2 + (-a + 3 * b - 3 * c + d) * t3);
-  return [f(p0[0], p1[0], p2[0], p3[0]), f(p0[1], p1[1], p2[1], p3[1])];
+  if (curviness === 1) {
+    const f = (a, b, c, d) => 0.5 * (2 * b + (-a + c) * t + (2 * a - 5 * b + 4 * c - d) * t2 + (-a + 3 * b - 3 * c + d) * t3);
+    return [f(p0[0], p1[0], p2[0], p3[0]), f(p0[1], p1[1], p2[1], p3[1])];
+  }
+  const h00 = 2 * t3 - 3 * t2 + 1;
+  const h10 = t3 - 2 * t2 + t;
+  const h01 = -2 * t3 + 3 * t2;
+  const h11 = t3 - t2;
+  const k = curviness * 0.5;
+  const H = (a, b, c, d) => h00 * b + h10 * k * (c - a) + h01 * c + h11 * k * (d - b);
+  return [H(p0[0], p1[0], p2[0], p3[0]), H(p0[1], p1[1], p2[1], p3[1])];
 }
-function pathTangentAngle(points, closed, u) {
+function pathTangentAngle(points, closed, u, curviness = 1) {
   const n = points.length;
   if (n < 2) return 0;
   const segs = segCountOf(points, closed);
   const { i, t } = locate(segs, u);
   const [p0, p1, p2, p3] = controls(points, closed, i);
   const t2 = t * t;
-  const d = (a, b, c, e) => 0.5 * (-a + c + 2 * (2 * a - 5 * b + 4 * c - e) * t + 3 * (-a + 3 * b - 3 * c + e) * t2);
-  const dx = d(p0[0], p1[0], p2[0], p3[0]);
-  const dy = d(p0[1], p1[1], p2[1], p3[1]);
+  let dx;
+  let dy;
+  if (curviness === 1) {
+    const d = (a, b, c, e) => 0.5 * (-a + c + 2 * (2 * a - 5 * b + 4 * c - e) * t + 3 * (-a + 3 * b - 3 * c + e) * t2);
+    dx = d(p0[0], p1[0], p2[0], p3[0]);
+    dy = d(p0[1], p1[1], p2[1], p3[1]);
+  } else {
+    const g00 = 6 * t2 - 6 * t;
+    const g10 = 3 * t2 - 4 * t + 1;
+    const g01 = -6 * t2 + 6 * t;
+    const g11 = 3 * t2 - 2 * t;
+    const k = curviness * 0.5;
+    const D = (a, b, c, e) => g00 * b + g10 * k * (c - a) + g01 * c + g11 * k * (e - b);
+    dx = D(p0[0], p1[0], p2[0], p3[0]);
+    dy = D(p0[1], p1[1], p2[1], p3[1]);
+  }
   if (dx === 0 && dy === 0) return 0;
   return Math.atan2(dy, dx) * 180 / Math.PI;
 }
@@ -130,8 +153,8 @@ function compileScene(ir) {
   const currentValue = (target, prop) => {
     const v = current.get(key(target, prop));
     if (v !== void 0) return v;
-    if (prop === "opacity" || prop === "scale" || prop === "progress") return 1;
-    if (prop === "rotation") return 0;
+    if (prop === "opacity" || prop === "scale" || prop === "progress" || prop === "scaleX" || prop === "scaleY") return 1;
+    if (prop === "rotation" || prop === "skewX" || prop === "skewY") return 0;
     throw new Error(`cannot animate "${prop}" of "${target}": no base value to start from`);
   };
   const labelTimes = /* @__PURE__ */ new Map();
@@ -234,16 +257,17 @@ function compileScene(ir) {
         const duration = tl.duration ?? DEFAULT_MOTIONPATH_DURATION;
         const points = tl.points;
         const closed = tl.closed ?? false;
+        const curviness = tl.curviness ?? 1;
         const autoRotate = tl.autoRotate ?? false;
         const rotateOffset = tl.rotateOffset ?? 0;
         let list = motionPaths.get(tl.target);
         if (!list) motionPaths.set(tl.target, list = []);
-        list.push({ t0: start, t1: start + duration, points, closed, autoRotate, rotateOffset, ...tl.ease !== void 0 && { ease: tl.ease } });
+        list.push({ t0: start, t1: start + duration, points, closed, curviness, autoRotate, rotateOffset, ...tl.ease !== void 0 && { ease: tl.ease } });
         if (points.length > 0) {
-          const [ex, ey] = pathPoint(points, closed, 1);
+          const [ex, ey] = pathPoint(points, closed, 1, curviness);
           current.set(key(tl.target, "x"), ex);
           current.set(key(tl.target, "y"), ey);
-          if (autoRotate) current.set(key(tl.target, "rotation"), pathTangentAngle(points, closed, 1) + rotateOffset);
+          if (autoRotate) current.set(key(tl.target, "rotation"), pathTangentAngle(points, closed, 1, curviness) + rotateOffset);
         }
         return start + duration;
       }
@@ -290,7 +314,7 @@ function compileScene(ir) {
 }
 
 // ../core/src/validate.ts
-var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "anchor"];
+var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor"];
 var PROPS_BY_TYPE = {
   rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
   ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
@@ -318,7 +342,18 @@ function validateScene(ir) {
         problems.push(`duplicate node id "${node.id}" \u2014 every node id must be unique`);
       }
       nodeById.set(node.id, node);
-      if (node.type === "group") collect(node.children);
+      if (node.type === "group") {
+        const clip = node.props.clip;
+        if (clip) {
+          if (clip.kind !== "rect" && clip.kind !== "ellipse") {
+            problems.push(`group "${node.id}" clip: unknown kind "${clip.kind}" \u2014 use "rect" or "ellipse"`);
+          }
+          if (!(clip.width > 0) || !(clip.height > 0)) {
+            problems.push(`group "${node.id}" clip: width and height must be > 0`);
+          }
+        }
+        collect(node.children);
+      }
     }
   };
   collect(ir.nodes);
@@ -351,11 +386,11 @@ function validateScene(ir) {
     );
   }
   const labels = /* @__PURE__ */ new Set();
-  const checkTimeline = (tl, path) => {
+  const checkTimeline = (tl, path2) => {
     if ("label" in tl && tl.label !== void 0) {
       if (labels.has(tl.label)) {
         problems.push(
-          `${path}: duplicate timeline label "${tl.label}" \u2014 labels are overlay addresses and must be unique`
+          `${path2}: duplicate timeline label "${tl.label}" \u2014 labels are overlay addresses and must be unique`
         );
       }
       labels.add(tl.label);
@@ -363,63 +398,73 @@ function validateScene(ir) {
     switch (tl.kind) {
       case "seq":
       case "par":
-        tl.children.forEach((c, i) => checkTimeline(c, `${path}.${tl.kind}[${i}]`));
+        tl.children.forEach((c, i) => checkTimeline(c, `${path2}.${tl.kind}[${i}]`));
         break;
       case "stagger":
-        if (tl.interval < 0) problems.push(`${path}: stagger interval must be >= 0`);
-        tl.children.forEach((c, i) => checkTimeline(c, `${path}.stagger[${i}]`));
+        if (tl.interval < 0) problems.push(`${path2}: stagger interval must be >= 0`);
+        tl.children.forEach((c, i) => checkTimeline(c, `${path2}.stagger[${i}]`));
         break;
       case "to":
         if (!(tl.state in states)) {
           problems.push(
-            `${path}: to("${tl.state}") references an undefined state \u2014 defined states: ${Object.keys(states).join(", ") || "(none)"}`
+            `${path2}: to("${tl.state}") references an undefined state \u2014 defined states: ${Object.keys(states).join(", ") || "(none)"}`
           );
         }
         if (tl.duration !== void 0 && tl.duration <= 0) {
-          problems.push(`${path}: to("${tl.state}") duration must be > 0`);
+          problems.push(`${path2}: to("${tl.state}") duration must be > 0`);
         }
         for (const id of tl.filter ?? []) {
-          if (!nodeById.has(id)) problems.push(`${path}: filter contains unknown node "${id}"`);
+          if (!nodeById.has(id)) problems.push(`${path2}: filter contains unknown node "${id}"`);
         }
         break;
       case "tween":
-        checkProps(path, tl.target, tl.props);
+        checkProps(path2, tl.target, tl.props);
         if (tl.duration !== void 0 && tl.duration <= 0) {
-          problems.push(`${path}: tween duration must be > 0`);
+          problems.push(`${path2}: tween duration must be > 0`);
         }
         break;
       case "motionPath": {
         const node = nodeById.get(tl.target);
         if (!node) {
           problems.push(
-            `${path}: motionPath targets unknown node "${tl.target}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
+            `${path2}: motionPath targets unknown node "${tl.target}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
           );
         } else if (node.type === "line") {
-          problems.push(`${path}: motionPath cannot target a line (no x/y) \u2014 "${tl.target}"`);
+          problems.push(`${path2}: motionPath cannot target a line (no x/y) \u2014 "${tl.target}"`);
         }
-        if (tl.points.length < 1) problems.push(`${path}: motionPath "${tl.target}" needs at least 1 point`);
+        if (tl.points.length < 1) problems.push(`${path2}: motionPath "${tl.target}" needs at least 1 point`);
         if (tl.duration !== void 0 && tl.duration <= 0) {
-          problems.push(`${path}: motionPath "${tl.target}" duration must be > 0`);
+          problems.push(`${path2}: motionPath "${tl.target}" duration must be > 0`);
+        }
+        if (tl.curviness !== void 0 && tl.curviness < 0) {
+          problems.push(`${path2}: motionPath "${tl.target}" curviness must be >= 0`);
         }
         break;
       }
       case "wait":
-        if (tl.duration < 0) problems.push(`${path}: wait duration must be >= 0`);
+        if (tl.duration < 0) problems.push(`${path2}: wait duration must be >= 0`);
         break;
       case "beat":
         if (labels.has(tl.name)) {
           problems.push(
-            `${path}: duplicate timeline label "${tl.name}" (beat name) \u2014 labels are overlay addresses and must be unique`
+            `${path2}: duplicate timeline label "${tl.name}" (beat name) \u2014 labels are overlay addresses and must be unique`
           );
         }
         labels.add(tl.name);
         if (tl.duration !== void 0 && tl.duration <= 0) {
-          problems.push(`${path}: beat "${tl.name}" duration must be > 0`);
+          problems.push(`${path2}: beat "${tl.name}" duration must be > 0`);
         }
         if (tl.scale !== void 0 && tl.scale <= 0) {
-          problems.push(`${path}: beat "${tl.name}" scale must be > 0`);
+          problems.push(`${path2}: beat "${tl.name}" scale must be > 0`);
+        }
+        for (const id of tl.nodes ?? []) {
+          if (!nodeById.has(id)) {
+            problems.push(
+              `${path2}: beat "${tl.name}" owns unknown node "${id}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
+            );
+          }
         }
-        tl.children.forEach((c, i) => checkTimeline(c, `${path}.beat(${tl.name})[${i}]`));
+        tl.children.forEach((c, i) => checkTimeline(c, `${path2}.beat(${tl.name})[${i}]`));
         break;
     }
   };
@@ -459,12 +504,78 @@ function validateScene(ir) {
   }
   if (problems.length > 0) throw new SceneValidationError(problems);
 }
+var TRANSITIONS = ["cut", "crossfade"];
+function validateComposition(comp) {
+  const problems = [];
+  if (comp.scenes.length === 0) problems.push("composition has no scenes");
+  const seen = /* @__PURE__ */ new Set();
+  for (const [i, entry] of comp.scenes.entries()) {
+    const where = `scenes[${i}]`;
+    try {
+      validateScene(entry.scene);
+    } catch (err) {
+      if (err instanceof SceneValidationError) {
+        for (const p of err.problems) problems.push(`${where} (scene "${entry.scene.id}"): ${p}`);
+      } else throw err;
+    }
+    if (seen.has(entry.scene.id)) {
+      problems.push(`${where}: duplicate scene id "${entry.scene.id}" \u2014 scene ids must be unique in a composition`);
+    }
+    seen.add(entry.scene.id);
+    if (entry.transition !== void 0 && !TRANSITIONS.includes(entry.transition)) {
+      problems.push(`${where}: unknown transition "${entry.transition}" \u2014 valid: ${TRANSITIONS.join(", ")}`);
+    }
+    if (typeof entry.at === "string" && Number.isNaN(Number(entry.at))) {
+      problems.push(`${where}: "at" string "${entry.at}" is not a number (use "-0.5"/"+0.5" or a number)`);
+    }
+    if (typeof entry.at === "number" && entry.at < 0) {
+      problems.push(`${where}: absolute "at" must be >= 0`);
+    }
+  }
+  if (problems.length > 0) throw new SceneValidationError(problems);
+}
+
+// ../core/src/composeComposition.ts
+function compileComposition(comp) {
+  const scenes = [];
+  let prevEnd = 0;
+  comp.scenes.forEach((entry, i) => {
+    const compiled = compileScene(entry.scene);
+    const duration2 = compiled.duration;
+    const transition = entry.transition ?? "cut";
+    const append = i === 0 ? 0 : prevEnd;
+    let start;
+    if (typeof entry.at === "number") {
+      start = entry.at;
+    } else if (typeof entry.at === "string") {
+      start = append + Number(entry.at);
+    } else if (transition === "crossfade" && i > 0) {
+      start = append - DEFAULT_CROSSFADE;
+    } else {
+      start = append;
+    }
+    start = Math.max(0, start);
+    const overlap = i > 0 ? Math.max(0, prevEnd - start) : 0;
+    scenes.push({ id: entry.scene.id, scene: entry.scene, compiled, start, duration: duration2, transition, overlap });
+    prevEnd = start + duration2;
+  });
+  const duration = scenes.reduce((max, s) => Math.max(max, s.start + s.duration), 0);
+  return { ir: comp, scenes, duration };
+}
 
 // ../core/src/compose.ts
 var SCENE_PATCHABLE = ["background", "duration", "fps"];
 function composeScene(base, ...overlays) {
   const ir = structuredClone(base);
   const report = { applied: [], orphans: [], warnings: [] };
+  const baseNodeIds = /* @__PURE__ */ new Set();
+  const collectBase = (nodes) => {
+    for (const node of nodes) {
+      baseNodeIds.add(node.id);
+      if (node.type === "group") collectBase(node.children);
+    }
+  };
+  collectBase(base.nodes);
   overlays.forEach((overlay, index) => {
     const layer = overlay.name ?? `overlay-${index}`;
     if (overlay.target !== void 0 && overlay.target !== ir.id) {
@@ -472,12 +583,12 @@ function composeScene(base, ...overlays) {
         `${layer}: authored against scene "${overlay.target}" but composing onto "${ir.id}"`
       );
     }
-    applyOverlay(ir, overlay, layer, report);
+    applyOverlay(ir, overlay, layer, report, baseNodeIds);
   });
   validateScene(ir);
   return { ir, report };
 }
-function applyOverlay(ir, overlay, layer, report) {
+function applyOverlay(ir, overlay, layer, report, baseNodeIds) {
   const nodeById = /* @__PURE__ */ new Map();
   const collect = (nodes) => {
     for (const node of nodes) {
@@ -592,7 +703,7 @@ function applyOverlay(ir, overlay, layer, report) {
       to: ["duration", "ease", "stagger"],
       tween: ["duration", "ease"],
       wait: ["duration"],
-      motionPath: ["points", "duration", "ease"],
+      motionPath: ["points", "duration", "ease", "curviness", "autoRotate"],
       beat: ["at", "gap", "scale", "duration", "order"]
     };
     let timingPatched = false;
@@ -630,6 +741,49 @@ function applyOverlay(ir, overlay, layer, report) {
     nodeById.set(node.id, node);
     applied(`addNodes.${node.id}`, "add-node");
   }
+  for (const id of overlay.removeNodes ?? []) {
+    if (baseNodeIds.has(id)) {
+      orphan(
+        `removeNodes.${id}`,
+        `"${id}" is a base scene node \u2014 the scene owns it; hide it with opacity: 0 instead of removing`
+      );
+      continue;
+    }
+    const index = ir.nodes.findIndex((n) => n.id === id);
+    if (index < 0) {
+      orphan(
+        `removeNodes.${id}`,
+        `unknown overlay-added node "${id}" \u2014 nothing to remove`
+      );
+      continue;
+    }
+    ir.nodes.splice(index, 1);
+    nodeById.delete(id);
+    applied(`removeNodes.${id}`, "remove-node");
+  }
+  if (overlay.addTimeline && overlay.addTimeline.length > 0) {
+    const collectTargets = (tl, out) => {
+      if (tl.kind === "tween" || tl.kind === "motionPath") out.add(tl.target);
+      if ("children" in tl) tl.children.forEach((c) => collectTargets(c, out));
+    };
+    const valid = [];
+    overlay.addTimeline.forEach((frag, i) => {
+      const targets = /* @__PURE__ */ new Set();
+      collectTargets(frag, targets);
+      const missing = [...targets].filter((id) => !nodeById.has(id));
+      if (missing.length > 0) {
+        orphan(`addTimeline[${i}]`, `targets unknown node(s) ${missing.join(", ")} \u2014 known ids: ${knownIds()}`);
+        return;
+      }
+      valid.push(structuredClone(frag));
+      applied(`addTimeline[${i}]`, "add-timeline");
+    });
+    if (valid.length > 0) {
+      ir.timeline = ir.timeline ? { kind: "par", children: [ir.timeline, ...valid] } : valid.length === 1 ? valid[0] : { kind: "par", children: valid };
+      delete ir.duration;
+      ir.duration = compileScene(ir).duration;
+    }
+  }
 }
 function formatComposeReport(report) {
   const lines = [];
@@ -690,6 +844,15 @@ function resolveAudioPlan(compiled) {
     });
   }
   cues.sort((a, b) => a.t - b.t);
+  return {
+    duration,
+    bgm: resolveBgm(audio.bgm),
+    cues,
+    duckWindows: mergeDuckWindows(cues, duration),
+    warnings
+  };
+}
+function mergeDuckWindows(cues, duration) {
   const duckWindows = [];
   for (const cue of cues) {
     const window2 = { t0: cue.t, t1: Math.min(duration, cue.t + cue.duration) };
@@ -697,23 +860,68 @@ function resolveAudioPlan(compiled) {
     if (last && window2.t0 <= last.t1 + 0.1) last.t1 = Math.max(last.t1, window2.t1);
     else duckWindows.push(window2);
   }
-  let bgm = null;
-  if (audio.bgm) {
-    const b = audio.bgm;
-    const duck = b.duck === false ? null : {
-      depth: b.duck?.depth ?? 0.5,
-      attack: b.duck?.attack ?? 0.05,
-      release: b.duck?.release ?? 0.25
-    };
-    bgm = {
-      source: b.file ? { kind: "file", path: b.file } : { kind: "synth", name: b.synth ?? "ambient-pad" },
-      gain: b.gain ?? 0.5,
-      fadeIn: b.fadeIn ?? 0,
-      fadeOut: b.fadeOut ?? 0,
-      duck
-    };
+  return duckWindows;
+}
+function resolveBgm(b) {
+  if (!b) return null;
+  const duck = b.duck === false ? null : {
+    depth: b.duck?.depth ?? 0.5,
+    attack: b.duck?.attack ?? 0.05,
+    release: b.duck?.release ?? 0.25
+  };
+  return {
+    source: b.file ? { kind: "file", path: b.file } : { kind: "synth", name: b.synth ?? "ambient-pad" },
+    gain: b.gain ?? 0.5,
+    fadeIn: b.fadeIn ?? 0,
+    fadeOut: b.fadeOut ?? 0,
+    duck
+  };
+}
+function resolveCompositionAudioPlan(comp) {
+  const audio = comp.ir.audio;
+  const duration = comp.duration;
+  const warnings = [];
+  const cues = [];
+  for (const placement of comp.scenes) {
+    const plan = resolveAudioPlan(placement.compiled);
+    if (!plan) continue;
+    if (plan.bgm) {
+      warnings.push(`scene "${placement.id}": per-scene bgm ignored \u2014 set bgm at the composition level`);
+    }
+    for (const w of plan.warnings) warnings.push(`scene "${placement.id}": ${w}`);
+    for (const cue of plan.cues) {
+      const t = cue.t + placement.start;
+      if (t >= duration) continue;
+      cues.push({ ...cue, t });
+    }
   }
-  return { duration, bgm, cues, duckWindows, warnings };
+  for (const [index, cue] of (audio?.cues ?? []).entries()) {
+    if (typeof cue.at !== "number") {
+      warnings.push(`composition cue[${index}]: "at" must be an absolute number (no composition labels) \u2014 dropped`);
+      continue;
+    }
+    const t = Math.max(0, cue.at + (cue.offset ?? 0));
+    const cueDuration = cue.sfx ? SFX_DURATION[cue.sfx] : FILE_CUE_DURATION;
+    if (t >= duration) {
+      warnings.push(`composition cue[${index}] at ${t.toFixed(2)}s past the composition end \u2014 dropped`);
+      continue;
+    }
+    cues.push({
+      t,
+      gain: cue.gain ?? 1,
+      duration: cueDuration,
+      source: cue.sfx ? { kind: "sfx", name: cue.sfx, params: cue.params ?? {} } : { kind: "file", path: cue.file }
+    });
+  }
+  if (!audio?.bgm && cues.length === 0) return null;
+  cues.sort((a, b) => a.t - b.t);
+  return {
+    duration,
+    bgm: resolveBgm(audio?.bgm),
+    cues,
+    duckWindows: mergeDuckWindows(cues, duration),
+    warnings
+  };
 }
 
 // ../core/src/interpolate.ts
@@ -968,22 +1176,22 @@ function synthAmbientPad(duration, seed = 0) {
 var ROOT = true ? resolve(dirname(fileURLToPath(import.meta.url)), "..") : resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..");
 var VENDORED = join(ROOT, "assets", "sfx");
 var CACHE = join(tmpdir(), "reframe-sfx-cache");
-function fnv1a(text) {
+function fnv1a(text2) {
   let h = 2166136261;
-  for (let i = 0; i < text.length; i++) {
-    h ^= text.charCodeAt(i);
+  for (let i = 0; i < text2.length; i++) {
+    h ^= text2.charCodeAt(i);
     h = Math.imul(h, 16777619);
   }
   return (h >>> 0).toString(16);
 }
 async function writeCached(key2, make) {
-  const path = join(CACHE, `${key2}.wav`);
-  if (existsSync(path)) return path;
+  const path2 = join(CACHE, `${key2}.wav`);
+  if (existsSync(path2)) return path2;
   await mkdir(CACHE, { recursive: true });
-  const temp = `${path}.${process.pid}.${fnv1a(String(performance.now()))}.tmp`;
+  const temp = `${path2}.${process.pid}.${fnv1a(String(performance.now()))}.tmp`;
   await writeFile(temp, encodeWavMono16(make()));
-  await rename(temp, path);
-  return path;
+  await rename(temp, path2);
+  return path2;
 }
 async function resolveCueFile(cue, sceneDir) {
   if (cue.source.kind === "file") {
@@ -1110,6 +1318,12 @@ async function buildAudioTrack(plan, scenePath, videoIn, outFile) {
   await muxAudio(videoIn, plan, { cueFiles, bgmFile }, outFile);
 }
 
+// ../render-cli/src/composition.ts
+import { spawn as spawn3 } from "node:child_process";
+import { copyFile, mkdtemp as mkdtemp2, rm as rm2, writeFile as writeFile4 } from "node:fs/promises";
+import { tmpdir as tmpdir3 } from "node:os";
+import { dirname as dirname5, join as join5 } from "node:path";
+
 // ../render-cli/src/encode.ts
 import { spawn as spawn2 } from "node:child_process";
 async function encodeMp4(framesDir, fps, outFile) {
@@ -1353,31 +1567,149 @@ async function captureHtml(htmlPath, opts) {
         (ms) => window.__vclock.advanceTo(ms),
         f / opts.fps * 1e3
       );
-      const path = framePath(opts.framesDir, f);
-      if (hasStage) await stage.screenshot({ path, animations: "allow" });
-      else await page.screenshot({ path, animations: "allow" });
+      const path2 = framePath(opts.framesDir, f);
+      if (hasStage) await stage.screenshot({ path: path2, animations: "allow" });
+      else await page.screenshot({ path: path2, animations: "allow" });
     }
     return { framesDir: opts.framesDir, frameCount, fps: opts.fps };
   });
 }
 
+// ../render-cli/src/composition.ts
+function runFfmpeg(args) {
+  return new Promise((resolve5, reject) => {
+    const proc = spawn3("ffmpeg", args, { stdio: ["ignore", "ignore", "pipe"] });
+    let stderr = "";
+    proc.stderr.on("data", (d) => stderr += d.toString());
+    proc.on("close", (code) => code === 0 ? resolve5() : reject(new Error(`ffmpeg exited ${code}:
+${stderr.slice(-2e3)}`)));
+    proc.on("error", reject);
+  });
+}
+var sanitize = (id) => id.replace(/[^a-z0-9_-]/gi, "_");
+async function renderSceneVideo(scene, sceneDir, fps, out) {
+  const framesDir = await mkdtemp2(join5(tmpdir3(), "reframe-frames-"));
+  try {
+    const result = await captureIr(scene, { framesDir, sceneDir, ...fps !== void 0 && { fps } });
+    await encodeMp4(result.framesDir, result.fps, out);
+    return { fps: result.fps, frameCount: result.frameCount };
+  } finally {
+    await rm2(framesDir, { recursive: true, force: true });
+  }
+}
+async function renderStandaloneScene(scene, sceneDir, fps, noAudio, out) {
+  const plan = noAudio ? null : resolveAudioPlan(compileScene(scene));
+  if (plan) {
+    const videoOut = `${out}.video.mp4`;
+    await renderSceneVideo(scene, sceneDir, fps, videoOut);
+    await buildAudioTrack(plan, join5(sceneDir, "scene"), videoOut, out);
+    await rm2(videoOut, { force: true });
+  } else {
+    await renderSceneVideo(scene, sceneDir, fps, out);
+  }
+}
+async function concatVideos(files, out) {
+  if (files.length === 1) {
+    await copyFile(files[0], out);
+    return;
+  }
+  const list = `${out}.concat.txt`;
+  await writeFile4(list, files.map((f) => `file '${f.replace(/'/g, "'\\''")}'`).join("\n"));
+  await runFfmpeg(["-y", "-f", "concat", "-safe", "0", "-i", list, "-c", "copy", "-movflags", "+faststart", out]);
+}
+async function xfade2(a, b, overlap, offset, out) {
+  await runFfmpeg([
+    "-y",
+    "-i",
+    a,
+    "-i",
+    b,
+    "-filter_complex",
+    `[0:v][1:v]xfade=transition=fade:duration=${overlap.toFixed(4)}:offset=${offset.toFixed(4)}[v]`,
+    "-map",
+    "[v]",
+    "-c:v",
+    "libx264",
+    "-preset",
+    "slow",
+    "-crf",
+    "18",
+    "-pix_fmt",
+    "yuv420p",
+    "-movflags",
+    "+faststart",
+    out
+  ]);
+}
+async function combineWithTransitions(videos, out, tmp) {
+  let acc = videos[0].file;
+  let accDur = videos[0].placement.duration;
+  for (let i = 1; i < videos.length; i++) {
+    const { overlap, duration } = videos[i].placement;
+    const step = join5(tmp, `step${i}.mp4`);
+    if (overlap <= 0) {
+      await concatVideos([acc, videos[i].file], step);
+      accDur += duration;
+    } else {
+      const offset = Math.max(0, accDur - overlap);
+      await xfade2(acc, videos[i].file, overlap, offset, step);
+      accDur = offset + duration;
+    }
+    acc = step;
+  }
+  await copyFile(acc, out);
+}
+async function renderComposition(comp, opts) {
+  const cc = compileComposition(comp);
+  const sceneDir = dirname5(opts.compositionPath);
+  if (opts.onlyScene) {
+    const p = cc.scenes.find((s) => s.id === opts.onlyScene);
+    if (!p) throw new Error(`--scene "${opts.onlyScene}" not in composition; scenes: ${cc.scenes.map((s) => s.id).join(", ")}`);
+    await renderStandaloneScene(p.scene, sceneDir, opts.fps, opts.noAudio, opts.out);
+    return { duration: p.duration, sceneCount: 1 };
+  }
+  const tmp = await mkdtemp2(join5(tmpdir3(), "reframe-comp-"));
+  try {
+    const videos = [];
+    for (const p of cc.scenes) {
+      const file = join5(tmp, `${sanitize(p.id)}.mp4`);
+      const { fps } = await renderSceneVideo(p.scene, sceneDir, opts.fps, file);
+      videos.push({ id: p.id, file, placement: p, fps });
+    }
+    const combined = join5(tmp, "combined.mp4");
+    const allCut = cc.scenes.every((s) => s.overlap === 0);
+    if (allCut) await concatVideos(videos.map((v) => v.file), combined);
+    else await combineWithTransitions(videos, combined, tmp);
+    if (!opts.noAudio) {
+      const plan = resolveCompositionAudioPlan(cc);
+      if (plan) {
+        for (const w of plan.warnings) console.error(`audio: ${w}`);
+        await buildAudioTrack(plan, opts.compositionPath, combined, opts.out);
+      } else {
+        await copyFile(combined, opts.out);
+      }
+    } else {
+      await copyFile(combined, opts.out);
+    }
+    return { duration: cc.duration, sceneCount: cc.scenes.length };
+  } finally {
+    await rm2(tmp, { recursive: true, force: true });
+  }
+}
+
 // ../render-cli/src/loadScene.ts
 import { build as build2 } from "esbuild";
 import { readFile as readFile3 } from "node:fs/promises";
-import { dirname as dirname5, resolve as resolve3 } from "node:path";
+import { dirname as dirname6, resolve as resolve3 } from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
-var HERE = dirname5(fileURLToPath4(import.meta.url));
+var HERE = dirname6(fileURLToPath4(import.meta.url));
 var CORE_ENTRY = true ? resolve3(HERE, "index.js") : resolve3(HERE, "..", "..", "core", "src", "index.ts");
-async function loadScene(path) {
-  if (path.endsWith(".json")) {
-    const ir = JSON.parse(await readFile3(path, "utf8"));
-    validateScene(ir);
-    return ir;
-  }
+async function loadDefault(path2) {
+  if (path2.endsWith(".json")) return JSON.parse(await readFile3(path2, "utf8"));
   let code;
   try {
     const out = await build2({
-      entryPoints: [path],
+      entryPoints: [path2],
       bundle: true,
       format: "esm",
       platform: "neutral",
@@ -1390,15 +1722,25 @@ async function loadScene(path) {
     });
     code = out.outputFiles[0].text;
   } catch (err) {
-    throw new Error(
-      `failed to bundle ${path}:
-${err instanceof Error ? err.message : String(err)}`
-    );
+    throw new Error(`failed to bundle ${path2}:
+${err instanceof Error ? err.message : String(err)}`);
   }
   const mod = await import(`data:text/javascript;base64,${Buffer.from(code).toString("base64")}`);
-  if (!mod.default) throw new Error(`${path} must default-export a scene`);
+  if (mod.default === void 0) throw new Error(`${path2} must default-export a scene or composition`);
   return mod.default;
 }
+function isComposition(def) {
+  return typeof def === "object" && def !== null && Array.isArray(def.scenes);
+}
+async function loadModule(path2) {
+  const def = await loadDefault(path2);
+  if (isComposition(def)) {
+    validateComposition(def);
+    return { kind: "composition", ir: def };
+  }
+  validateScene(def);
+  return { kind: "scene", ir: def };
+}
 
 // ../render-cli/src/cli.ts
 function parseArgs(argv) {
@@ -1426,6 +1768,7 @@ function parseArgs(argv) {
     else if (a === "--frames-dir") args.framesDir = resolve4(rest[++i]);
     else if (a === "--overlay") args.overlays.push(resolve4(rest[++i]));
     else if (a === "--no-audio") args.noAudio = true;
+    else if (a === "--scene") args.scene = rest[++i];
     else {
       console.error(`unknown flag ${a}`);
       process.exit(2);
@@ -1435,11 +1778,28 @@ function parseArgs(argv) {
 }
 async function main() {
   const args = parseArgs(process.argv.slice(2));
-  const framesDir = args.framesDir ?? await mkdtemp2(join5(tmpdir3(), "reframe-frames-"));
+  const loaded = args.mode === "ir" ? await loadModule(args.input) : null;
+  if (loaded?.kind === "composition") {
+    if (args.overlays.length > 0) {
+      console.error("note: overlays apply per-scene, not to a composition \u2014 ignored here");
+    }
+    const { duration, sceneCount } = await renderComposition(loaded.ir, {
+      compositionPath: args.input,
+      out: args.out,
+      noAudio: args.noAudio,
+      ...args.fps !== void 0 && { fps: args.fps },
+      ...args.scene !== void 0 && { onlyScene: args.scene }
+    });
+    console.log(
+      args.scene !== void 0 ? `${args.out} (scene "${args.scene}", ${duration.toFixed(2)}s)` : `${args.out} (composition: ${sceneCount} scene${sceneCount > 1 ? "s" : ""}, ${duration.toFixed(2)}s)`
+    );
+    return;
+  }
+  const framesDir = args.framesDir ?? await mkdtemp3(join6(tmpdir4(), "reframe-frames-"));
   let result;
   let audioJob = null;
   if (args.mode === "ir") {
-    let ir = await loadScene(args.input);
+    let ir = loaded.ir;
     if (args.overlays.length > 0) {
       const docs = await Promise.all(
         args.overlays.map(async (p) => JSON.parse(await readFile4(p, "utf8")))
@@ -1457,7 +1817,7 @@ async function main() {
     }
     result = await captureIr(ir, {
       framesDir,
-      sceneDir: dirname6(args.input),
+      sceneDir: dirname7(args.input),
       ...args.fps !== void 0 && { fps: args.fps },
       ...args.duration !== void 0 && { duration: args.duration }
     });
@@ -1474,10 +1834,10 @@ async function main() {
   await encodeMp4(result.framesDir, result.fps, audioJob ? audioJob.videoOut : args.out);
   if (audioJob) {
     await buildAudioTrack(audioJob.plan, args.input, audioJob.videoOut, args.out);
-    await rm2(audioJob.videoOut, { force: true });
+    await rm3(audioJob.videoOut, { force: true });
   }
   if (!args.keepFrames && args.framesDir === void 0) {
-    await rm2(framesDir, { recursive: true, force: true });
+    await rm3(framesDir, { recursive: true, force: true });
   }
   console.log(
     `${args.out} (${result.frameCount} frames @ ${result.fps}fps${audioJob ? `, ${audioJob.plan.cues.length} audio cues` : ""})`