reframe-video 0.6.33 → 0.6.39

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "reframe",
-  "version": "0.1.5",
+  "version": "0.1.8",
   "description": "Create and iterate motion-graphics videos as addressable data: deterministic mp4 renders, human edits that survive AI regeneration, label-anchored audio, data-driven batch rendering.",
   "author": {
     "name": "Kiyeon Jeon",

package/dist/assemble.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env tsx
+
+// ../render-cli/src/assemble.ts
+import { writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
+
+// ../render-cli/src/media/probe.ts
+import { spawn } from "node:child_process";
+var VIDEO_EXT = /\.(mp4|mov|webm|m4v|mkv)$/i;
+function run(cmd, args) {
+  return new Promise((res, reject) => {
+    const proc = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "", stderr = "";
+    proc.stdout.on("data", (d) => stdout += d.toString());
+    proc.stderr.on("data", (d) => stderr += d.toString());
+    proc.on("close", (code) => res({ code: code ?? 1, stdout, stderr }));
+    proc.on("error", reject);
+  });
+}
+async function probeMedia(file) {
+  const isVideo = VIDEO_EXT.test(file);
+  let out;
+  try {
+    out = await run("ffprobe", [
+      "-v",
+      "error",
+      "-show_entries",
+      "format=duration:stream=width,height",
+      "-of",
+      "json",
+      file
+    ]);
+  } catch {
+    throw new Error("ffprobe not found on PATH \u2014 install ffmpeg (macOS: brew install ffmpeg, debian: apt install ffmpeg)");
+  }
+  if (out.code !== 0) return { isVideo };
+  try {
+    const j = JSON.parse(out.stdout);
+    const d = j.format?.duration ? Number(j.format.duration) : NaN;
+    const stream = (j.streams ?? []).find((s) => s.width && s.height);
+    return {
+      isVideo,
+      ...Number.isFinite(d) && d > 0 ? { duration: d } : {},
+      ...stream ? { width: Number(stream.width), height: Number(stream.height) } : {}
+    };
+  } catch {
+    return { isVideo };
+  }
+}
+
+// ../render-cli/src/assemble.ts
+var BGM_SYNTHS = ["ambient-pad", "lofi", "pulse", "tension", "uplift"];
+function parseArgs(argv) {
+  const media = [];
+  const a = { media, hold: 3.5, seed: 0 };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = () => argv[++i] ?? fail(`${arg} needs a value`);
+    if (arg === "-o" || arg === "--out") a.out = next();
+    else if (arg === "--title") a.title = next();
+    else if (arg === "--bgm") a.bgm = next();
+    else if (arg === "--hold") a.hold = Number(next());
+    else if (arg === "--seed") a.seed = Number(next());
+    else if (arg.startsWith("-")) fail(`unknown flag "${arg}"`);
+    else media.push(arg);
+  }
+  return a;
+}
+function fail(msg) {
+  console.error(`error: ${msg}`);
+  process.exit(1);
+}
+var CWD = process.env.INIT_CWD ?? process.cwd();
+var userPath = (p) => isAbsolute(p) ? p : resolve(CWD, p);
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.media.length === 0) {
+    fail('assemble needs at least one media file\nusage: reframe assemble <media...> [-o name] [--title "\u2026"] [--bgm <synth>] [--hold s] [--seed N]');
+  }
+  if (args.bgm && !BGM_SYNTHS.includes(args.bgm)) fail(`unknown --bgm "${args.bgm}" \u2014 valid: ${BGM_SYNTHS.join(", ")}`);
+  const outArg = (args.out ?? "media-story").replace(/\.ts$/, "");
+  const outPath = userPath(`${outArg}.ts`);
+  const name = basename(outPath, ".ts");
+  if (existsSync(outPath)) fail(`${outArg}.ts already exists`);
+  const outDir = dirname(outPath);
+  const shots = [];
+  for (const m of args.media) {
+    const abs = userPath(m);
+    if (!existsSync(abs)) fail(`no such file: ${abs}`);
+    const info = await probeMedia(abs);
+    const rel = relative(outDir, abs) || basename(abs);
+    const src = rel.split("\\").join("/");
+    const hold = info.isVideo && info.duration ? Math.min(10, Math.max(0.5, info.duration)) : args.hold;
+    const portrait = !!(info.width && info.height && info.height > info.width);
+    shots.push({ src, hold: Number(hold.toFixed(3)), isVideo: info.isVideo, ...portrait ? { ken: "pan" } : {} });
+  }
+  await writeFile(outPath, sceneSource(name, shots, args));
+  const vids = shots.filter((s) => s.isVideo).length;
+  console.log(`created ${name}.ts \u2014 ${shots.length} shots (${vids} video, ${shots.length - vids} image)`);
+  console.log(`  next: reframe render ${name}.ts`);
+}
+function sceneSource(name, shots, args) {
+  const imports = ["scene", "photoMontage", "seq", "par"];
+  if (args.title) imports.push("title");
+  const shotLines = shots.map((s) => `  { src: ${JSON.stringify(s.src)}, hold: ${s.hold}${s.ken ? `, ken: ${JSON.stringify(s.ken)}` : ""} },`).join("\n");
+  const titleBlock = args.title ? `
+const ttl = title({ text: ${JSON.stringify(args.title)}, id: "ttl", x: W / 2, y: H / 2, fontSize: 110, entrance: "cascade", exit: "dissolve", hold: 1.6 });
+` : "";
+  const nodes = args.title ? "[...m.nodes, ...ttl.nodes]" : "[...m.nodes]";
+  const timeline = args.title ? "par(m.timeline, ttl.timeline)" : "seq(m.timeline)";
+  const audio = args.bgm ? `
+  audio: { bgm: { synth: ${JSON.stringify(args.bgm)}, gain: 0.18, fadeIn: 1.2, fadeOut: 2 } },` : "";
+  return `import { ${imports.join(", ")} } from "@reframe/core";
+
+// Assembled by \`reframe assemble\`. Clip holds were probed from the media (baked
+// in, so the render is deterministic). Edit freely \u2014 change order/holds, the
+// title, swap a src; node ids \`shot-0\`, \`shot-1\`\u2026 and \`ttl-*\` are stable.
+const W = 1920, H = 1080;
+
+const m = photoMontage([
+${shotLines}
+], { id: "shot", size: { width: W, height: H }, transition: 0.6, seed: ${args.seed} });
+${titleBlock}
+export default scene({
+  id: ${JSON.stringify(name)},
+  size: { width: W, height: H },
+  fps: 30,
+  background: "#000000",
+  nodes: ${nodes},
+  timeline: ${timeline},${audio}
+});
+`;
+}
+main().catch((err) => {
+  console.error(`error: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});

package/dist/bin.js

@@ -258,11 +258,68 @@ function compileScene(ir) {
         const grouping = { kind: tl.parallel ? "par" : "seq", children: tl.children };
         const natural = durationOf(grouping, 0);
         const k = tl.scale ?? (tl.duration !== void 0 ? tl.duration / Math.max(1e-9, natural) : 1);
-        const beatStart = tl.at ?? start + (tl.gap ?? 0);
+        const at = typeof tl.at === "number" ? tl.at : void 0;
+        const beatStart = at ?? start + (tl.gap ?? 0);
         return beatStart + k * natural;
       }
     }
   };
+  let labelClock;
+  const anyAnchor = (tl) => tl.kind === "beat" && typeof tl.at === "string" || "children" in tl && tl.children.some(anyAnchor);
+  if (ir.timeline && anyAnchor(ir.timeline)) {
+    const clock = /* @__PURE__ */ new Map();
+    const clockWalk = (tl, start) => {
+      let end = start;
+      switch (tl.kind) {
+        case "seq": {
+          let t = start;
+          for (const c of orderBeats(tl.children)) t = clockWalk(c, t);
+          end = t;
+          break;
+        }
+        case "par": {
+          for (const c of tl.children) end = Math.max(end, clockWalk(c, start));
+          break;
+        }
+        case "stagger": {
+          tl.children.forEach((c, i) => {
+            end = Math.max(end, clockWalk(c, start + i * tl.interval));
+          });
+          break;
+        }
+        case "wait":
+          end = start + tl.duration;
+          break;
+        case "tween":
+          end = start + (tl.duration ?? DEFAULT_TWEEN_DURATION);
+          break;
+        case "motionPath":
+          end = start + (tl.duration ?? DEFAULT_MOTIONPATH_DURATION);
+          break;
+        case "to": {
+          const override = ir.states?.[tl.state] ?? {};
+          const si = tl.stagger ?? 0;
+          const targets = nodeOrder.filter((id) => id in override && (tl.filter === void 0 || tl.filter.includes(id)));
+          end = start + (tl.duration ?? DEFAULT_TO_DURATION) + Math.max(0, targets.length - 1) * si;
+          break;
+        }
+        case "beat": {
+          const grouping = { kind: tl.parallel ? "par" : "seq", children: tl.children };
+          const k = tl.scale ?? (tl.duration !== void 0 ? tl.duration / Math.max(1e-9, durationOf(grouping, 0)) : 1);
+          const inner = k === 1 ? grouping : scaleTimeline(grouping, k);
+          const at = typeof tl.at === "number" ? tl.at : void 0;
+          const beatStart = at ?? start + (tl.gap ?? 0);
+          end = clockWalk(inner, beatStart);
+          clock.set(tl.name, { t0: beatStart, t1: end });
+          break;
+        }
+      }
+      if ("label" in tl && tl.label !== void 0) clock.set(tl.label, { t0: start, t1: end });
+      return end;
+    };
+    clockWalk(ir.timeline, 0);
+    labelClock = clock;
+  }
   const walk = (tl, start) => {
     const end = walkInner(tl, start);
     if ("label" in tl && tl.label !== void 0) labelTimes.set(tl.label, { t0: start, t1: end });
@@ -279,7 +336,8 @@ function compileScene(ir) {
         const grouping = { kind: tl.parallel ? "par" : "seq", children: tl.children };
         const k = tl.scale ?? (tl.duration !== void 0 ? tl.duration / Math.max(1e-9, durationOf(grouping, 0)) : 1);
         const inner = k === 1 ? grouping : scaleTimeline(grouping, k);
-        const beatStart = tl.at ?? start + (tl.gap ?? 0);
+        const anchored = typeof tl.at === "string" ? labelClock?.get(tl.at)?.t0 : tl.at;
+        const beatStart = anchored !== void 0 ? anchored + (typeof tl.at === "string" ? tl.gap ?? 0 : 0) : start + (tl.gap ?? 0);
         const end = walk(inner, beatStart);
         beatTimes.set(tl.name, { t0: beatStart, t1: end });
         labelTimes.set(tl.name, { t0: beatStart, t1: end });
@@ -577,6 +635,7 @@ var init_interpolate = __esm({
 function validateScene(ir) {
   const problems = [];
   const nodeById = /* @__PURE__ */ new Map();
+  const startAnchors = [];
   const checkPaint = (where, value) => {
     if (typeof value !== "object" || value === null) return;
     const g = value;
@@ -609,6 +668,7 @@ function validateScene(ir) {
       if (typeof props.shadowBlur === "number" && props.shadowBlur < 0) problems.push(`node "${node.id}": shadowBlur must be >= 0`);
       if (typeof props.blend === "string" && !BLEND_MODES.has(props.blend)) problems.push(`node "${node.id}": unknown blend "${props.blend}" \u2014 use ${[...BLEND_MODES].join(", ")}`);
       if (typeof props.fit === "string" && !IMAGE_FITS.has(props.fit)) problems.push(`node "${node.id}": unknown fit "${props.fit}" \u2014 use ${[...IMAGE_FITS].join(", ")}`);
+      if (node.type === "video" && typeof node.props.start === "string") startAnchors.push({ id: node.id, at: node.props.start });
       if (node.type === "group") {
         const clip = node.props.clip;
         if (clip) {
@@ -669,6 +729,7 @@ function validateScene(ir) {
     );
   }
   const labels = /* @__PURE__ */ new Set();
+  const beatAnchors = [];
   const checkEase = (path2, ease) => {
     if (ease === void 0) return;
     if (typeof ease === "string") {
@@ -760,6 +821,7 @@ function validateScene(ir) {
           );
         }
         labels.add(tl.name);
+        if (typeof tl.at === "string") beatAnchors.push({ name: tl.name, at: tl.at, path: path2 });
         if (tl.duration !== void 0 && tl.duration <= 0) {
           problems.push(`${path2}: beat "${tl.name}" duration must be > 0`);
         }
@@ -778,6 +840,22 @@ function validateScene(ir) {
     }
   };
   if (ir.timeline) checkTimeline(ir.timeline, "timeline");
+  for (const a of beatAnchors) {
+    if (a.at === a.name) {
+      problems.push(`${a.path}: beat "${a.name}" at: "${a.at}" cannot anchor to itself`);
+    } else if (!labels.has(a.at)) {
+      problems.push(
+        `${a.path}: beat "${a.name}" at: "${a.at}" \u2014 unknown timeline label \u2014 known labels: ${[...labels].join(", ") || "(none)"}`
+      );
+    }
+  }
+  for (const a of startAnchors) {
+    if (!labels.has(a.at)) {
+      problems.push(
+        `video "${a.id}" start: "${a.at}" \u2014 unknown timeline label \u2014 known labels: ${[...labels].join(", ") || "(none)"}`
+      );
+    }
+  }
   for (const [i, b] of (ir.behaviors ?? []).entries()) {
     checkProps(`behaviors[${i}]`, b.target, { [b.prop]: 0 });
   }
@@ -1117,13 +1195,6 @@ function applyOverlay(ir, overlay, layer, report, baseNodeIds) {
       if ("children" in tl) tl.children.forEach(walkTimeline);
     };
     if (ir.timeline) walkTimeline(ir.timeline);
-    const PATCHABLE = {
-      to: ["duration", "ease", "stagger"],
-      tween: ["duration", "ease"],
-      wait: ["duration"],
-      motionPath: ["points", "duration", "ease", "curviness", "autoRotate"],
-      beat: ["at", "gap", "scale", "duration", "order"]
-    };
     let timingPatched = false;
     for (const [label, patch] of Object.entries(overlay.timeline)) {
       const step = byLabel.get(label);
@@ -1134,7 +1205,7 @@ function applyOverlay(ir, overlay, layer, report, baseNodeIds) {
         );
         continue;
       }
-      const allowed = PATCHABLE[step.kind] ?? [];
+      const allowed = TIMELINE_PATCHABLE[step.kind] ?? [];
       for (const [key2, value] of Object.entries(patch)) {
         if (value === void 0) continue;
         if (!allowed.includes(key2)) {
@@ -1203,13 +1274,29 @@ function applyOverlay(ir, overlay, layer, report, baseNodeIds) {
     }
   }
 }
-var SCENE_PATCHABLE;
+var SCENE_PATCHABLE, TIMELINE_PATCHABLE;
 var init_compose = __esm({
   "../core/src/compose.ts"() {
     "use strict";
     init_compile();
     init_validate();
     SCENE_PATCHABLE = ["background", "duration", "fps"];
+    TIMELINE_PATCHABLE = {
+      to: ["duration", "ease", "stagger"],
+      tween: ["duration", "ease"],
+      wait: ["duration"],
+      motionPath: ["points", "duration", "ease", "curviness", "autoRotate"],
+      beat: ["at", "gap", "scale", "duration", "order"]
+    };
+  }
+});
+
+// ../core/src/manifest.ts
+var init_manifest = __esm({
+  "../core/src/manifest.ts"() {
+    "use strict";
+    init_compose();
+    init_validate();
   }
 });
 
@@ -1263,6 +1350,33 @@ var init_gradient = __esm({
 });
 
 // ../core/src/evaluate.ts
+function multiply(m, n) {
+  return [
+    m[0] * n[0] + m[2] * n[1],
+    m[1] * n[0] + m[3] * n[1],
+    m[0] * n[2] + m[2] * n[3],
+    m[1] * n[2] + m[3] * n[3],
+    m[0] * n[4] + m[2] * n[5] + m[4],
+    m[1] * n[4] + m[3] * n[5] + m[5]
+  ];
+}
+function localMatrix(x, y, rotationDeg, scale, scaleX = 1, scaleY = 1, skewXDeg = 0, skewYDeg = 0) {
+  const r = rotationDeg * Math.PI / 180;
+  if (scaleX === 1 && scaleY === 1 && skewXDeg === 0 && skewYDeg === 0) {
+    const cos = Math.cos(r) * scale;
+    const sin = Math.sin(r) * scale;
+    return [cos, sin, -sin, cos, x, y];
+  }
+  const c = Math.cos(r);
+  const s = Math.sin(r);
+  const tx = Math.tan(skewXDeg * Math.PI / 180);
+  const ty = Math.tan(skewYDeg * Math.PI / 180);
+  const R = [c, s, -s, c, 0, 0];
+  const K = [1, ty, tx, 1, 0, 0];
+  const S = [scale * scaleX, 0, 0, scale * scaleY, 0, 0];
+  const m = multiply(R, multiply(K, S));
+  return [m[0], m[1], m[2], m[3], x, y];
+}
 function behaviorEnvelope(b, t) {
   const from = b.from ?? Number.NEGATIVE_INFINITY;
   const until = b.until ?? Number.POSITIVE_INFINITY;
@@ -1318,7 +1432,39 @@ function sampleProp(compiled, t, target, prop, fallback) {
   }
   return value;
 }
-var DEG;
+function nodeParentMatrix(compiled, id, t) {
+  const num2 = (target, prop, fallback) => {
+    const v = sampleProp(compiled, t, target, prop, fallback);
+    return typeof v === "number" ? v : fallback;
+  };
+  let result = null;
+  const walk = (node, parent) => {
+    if (node.id === id) {
+      result = parent;
+      return true;
+    }
+    if (node.type === "group") {
+      const m = multiply(
+        parent,
+        localMatrix(
+          num2(node.id, "x", node.props.x),
+          num2(node.id, "y", node.props.y),
+          num2(node.id, "rotation", node.props.rotation ?? 0),
+          num2(node.id, "scale", node.props.scale ?? 1),
+          num2(node.id, "scaleX", node.props.scaleX ?? 1),
+          num2(node.id, "scaleY", node.props.scaleY ?? 1),
+          num2(node.id, "skewX", node.props.skewX ?? 0),
+          num2(node.id, "skewY", node.props.skewY ?? 0)
+        )
+      );
+      for (const child of node.children) if (walk(child, m)) return true;
+    }
+    return false;
+  };
+  for (const node of compiled.ir.nodes) if (walk(node, IDENTITY)) break;
+  return result;
+}
+var IDENTITY, DEG;
 var init_evaluate = __esm({
   "../core/src/evaluate.ts"() {
     "use strict";
@@ -1327,6 +1473,7 @@ var init_evaluate = __esm({
     init_gradient();
     init_interpolate();
     init_path();
+    IDENTITY = [1, 0, 0, 1, 0, 0];
     DEG = Math.PI / 180;
   }
 });
@@ -1364,6 +1511,10 @@ function autoFoley(compiled, opts = {}) {
       os.push(num(compiled, t, id, "opacity", node.props.opacity ?? 1));
     }
     const speed = (i2) => i2 <= 0 ? 0 : Math.hypot(xs[i2] - xs[i2 - 1], ys[i2] - ys[i2 - 1]) * fps;
+    const worldX = (frame) => {
+      const m = nodeParentMatrix(compiled, id, frame / fps);
+      return m ? m[0] * xs[frame] + m[2] * ys[frame] + m[4] : xs[frame];
+    };
     let i = 1;
     while (i <= N) {
       if (speed(i) <= vMin) {
@@ -1386,19 +1537,20 @@ function autoFoley(compiled, opts = {}) {
       if (peakV > vMin && durS >= MIN_DUR && visible) {
         if (wantWhoosh) {
           const quickFlick = durS < 0.25;
-          cands.push({ t: peak / fps, sfx: quickFlick ? "swish" : "whoosh", gain: master * loud(peakV), pan: panOf(xs[peak]), rank: peakV });
+          cands.push({ t: peak / fps, sfx: quickFlick ? "swish" : "whoosh", gain: master * loud(peakV), pan: panOf(worldX(peak)), rank: peakV });
         }
         const stopped = b >= N || speed(b + 1) < vStop && speed(Math.min(N, b + 2)) < vStop;
-        const landsOnScreen = xs[b] >= 0 && xs[b] <= W && os[b] > 0.1;
+        const wxb = worldX(b);
+        const landsOnScreen = wxb >= 0 && wxb <= W && os[b] > 0.1;
         if (wantImpact && peakV > vDecel && stopped && landsOnScreen && b < N) {
-          cands.push({ t: (b + 1) / fps, sfx: size > 220 ? "thud" : "knock", gain: master * loud(peakV), pan: panOf(xs[b]), rank: peakV * 1.1 });
+          cands.push({ t: (b + 1) / fps, sfx: size > 220 ? "thud" : "knock", gain: master * loud(peakV), pan: panOf(worldX(b)), rank: peakV * 1.1 });
         }
       }
     }
     if (wantPop && ss[0] < 0.25) {
       for (let k = 1; k <= N; k++) {
         if (ss[k - 1] < 0.5 && ss[k] >= 0.5 && os[k] > 0.05) {
-          cands.push({ t: k / fps, sfx: "pop", gain: master * 0.7, pan: panOf(xs[k]), rank: 600 });
+          cands.push({ t: k / fps, sfx: "pop", gain: master * 0.7, pan: panOf(worldX(k)), rank: 600 });
           break;
         }
       }
@@ -1461,6 +1613,31 @@ var init_montage = __esm({
   }
 });
 
+// ../core/src/textMetrics.ts
+var init_textMetrics = __esm({
+  "../core/src/textMetrics.ts"() {
+    "use strict";
+  }
+});
+
+// ../core/src/textFx.ts
+var init_textFx = __esm({
+  "../core/src/textFx.ts"() {
+    "use strict";
+    init_dsl();
+    init_textMetrics();
+  }
+});
+
+// ../core/src/titles.ts
+var init_titles = __esm({
+  "../core/src/titles.ts"() {
+    "use strict";
+    init_dsl();
+    init_textFx();
+  }
+});
+
 // ../core/src/presets.ts
 function makeRng(seed) {
   let a = seed >>> 0 || 2654435769;
@@ -1645,6 +1822,8 @@ var init_devicePreset = __esm({
   "../core/src/devicePreset.ts"() {
     "use strict";
     init_dsl();
+    init_effects();
+    init_gradient();
   }
 });
 
@@ -1682,22 +1861,6 @@ var init_figure = __esm({
   }
 });
 
-// ../core/src/textMetrics.ts
-var init_textMetrics = __esm({
-  "../core/src/textMetrics.ts"() {
-    "use strict";
-  }
-});
-
-// ../core/src/textFx.ts
-var init_textFx = __esm({
-  "../core/src/textFx.ts"() {
-    "use strict";
-    init_dsl();
-    init_textMetrics();
-  }
-});
-
 // ../core/src/motionOps.ts
 var init_motionOps = __esm({
   "../core/src/motionOps.ts"() {
@@ -1707,13 +1870,14 @@ var init_motionOps = __esm({
 });
 
 // ../core/src/audio.ts
-function collectClipAudio(ir, duration, warnings) {
+function collectClipAudio(ir, duration, labelTimes, warnings) {
   const out = [];
   const walk = (nodes) => {
     for (const node of nodes) {
       if (node.type === "video") {
         const gain = node.props.volume ?? 1;
-        const start = node.props.start ?? 0;
+        const startRaw = node.props.start;
+        const start = typeof startRaw === "string" ? labelTimes.get(startRaw)?.t0 ?? 0 : startRaw ?? 0;
         if (gain <= 0) continue;
         if (start >= duration) {
           warnings.push(`video "${node.id}": start ${start.toFixed(2)}s past the scene end \u2014 audio dropped`);
@@ -1731,7 +1895,7 @@ function resolveAudioPlan(compiled) {
   const audio = compiled.ir.audio;
   const warnings = [];
   const duration = compiled.duration;
-  const clipAudio = collectClipAudio(compiled.ir, duration, warnings);
+  const clipAudio = collectClipAudio(compiled.ir, duration, compiled.labelTimes, warnings);
   const autoCues = audio?.autoFoley ? autoFoley(compiled, audio.autoFoley === true ? {} : audio.autoFoley) : [];
   const manualCues = [...audio?.cues ?? [], ...autoCues];
   if (!audio || !audio.bgm && manualCues.length === 0) {
@@ -1919,6 +2083,7 @@ var init_src = __esm({
     init_validate();
     init_composeComposition();
     init_compose();
+    init_manifest();
     init_compile();
     init_path();
     init_camera();
@@ -1927,6 +2092,7 @@ var init_src = __esm({
     init_effects();
     init_layout();
     init_montage();
+    init_titles();
     init_presets();
     init_devicePreset();
     init_cursor();
@@ -3154,7 +3320,7 @@ ${stderr.slice(-2e3)}`))
   });
 }
 function neededSeconds(node, duration) {
-  const start = node.props.start ?? 0;
+  const start = typeof node.props.start === "string" ? 0 : node.props.start ?? 0;
   const rate = node.props.rate ?? 1;
   const clipStart = node.props.clipStart ?? 0;
   return clipStart + Math.max(0, duration - start) * Math.max(0, rate) + 1 / 30;
@@ -3678,6 +3844,10 @@ var USER_CWD = process.env.INIT_CWD ?? process.cwd();
 var RENDER_CLI = PACKAGED ? join9(ROOT2, "dist", "cli.js") : join9(ROOT2, "packages", "render-cli", "src", "cli.ts");
 var LABELS = PACKAGED ? join9(ROOT2, "dist", "labels.js") : join9(ROOT2, "packages", "render-cli", "src", "labels.ts");
 var COMPILE = PACKAGED ? join9(ROOT2, "dist", "compile.js") : join9(ROOT2, "packages", "render-cli", "src", "compile.ts");
+var ASSEMBLE = PACKAGED ? join9(ROOT2, "dist", "assemble.js") : join9(ROOT2, "packages", "render-cli", "src", "assemble.ts");
+var MANIFEST = PACKAGED ? join9(ROOT2, "dist", "manifest.js") : join9(ROOT2, "packages", "render-cli", "src", "manifest.ts");
+var LINT = PACKAGED ? join9(ROOT2, "dist", "lint.js") : join9(ROOT2, "packages", "render-cli", "src", "lint.ts");
+var VERIFY_OVERLAY = PACKAGED ? join9(ROOT2, "dist", "verifyOverlay.js") : join9(ROOT2, "packages", "render-cli", "src", "verifyOverlay.ts");
 var DIFF = PACKAGED ? join9(ROOT2, "dist", "diff.js") : join9(ROOT2, "packages", "render-cli", "src", "diff.ts");
 var FRAME = PACKAGED ? join9(ROOT2, "dist", "frame.js") : join9(ROOT2, "packages", "render-cli", "src", "frame.ts");
 var PLAYER = PACKAGED ? join9(ROOT2, "dist", "player.js") : join9(ROOT2, "packages", "render-cli", "src", "player.ts");
@@ -3708,7 +3878,12 @@ usage:
                                  player (plays live in any browser or a Claude.ai artifact; visual only)
   ${CMD} preview                 open the scrub/edit UI (lists scenes in your directory)
   ${CMD} new <scene-name>        scaffold <scene-name>.ts in your directory
+  ${CMD} assemble <media...> [-o name] [--title "\u2026"] [--bgm <synth>] [--hold s] [--seed N]
+                                 probe images/videos \u2192 scaffold a clip-aware montage scene .ts (then render it)
   ${CMD} labels <scene.ts|.json>  print the event clock (label \u2192 exact seconds; for sound design / timing)
+  ${CMD} manifest <scene.ts|.json> [--json]  list the editable surface (node/state/label/beat/behavior addresses + patchable props)
+  ${CMD} lint <scene.ts|.json> [--json] [--strict]  flag un-addressable motion (regen-unsafe) + an addressability summary
+  ${CMD} verify-overlay <base.ts|.json> <overlay.json>... [--json]  compose an overlay onto a base, report survival (no render; non-zero exit on orphans)
   ${CMD} compile <scene.ts|.json> [-o out.json] [--stdin] [--code "<src>"] [--json]
                                  bundle + validate a scene to SceneIR JSON, no render (fast; no ffmpeg/chromium)
   ${CMD} frame <scene.ts|.json> [--t <sec>] [-o out.png]  render ONE frame at time t to a PNG (no mp4; for a render-and-look loop)
@@ -3861,6 +4036,43 @@ ${USAGE}`);
         await (PACKAGED ? run2(process.execPath, [LABELS, inputPath]) : run2("npx", ["tsx", LABELS, inputPath]))
       );
     }
+    case "assemble": {
+      if (rest.length === 0) fail(`assemble needs at least one media file
+
+${USAGE}`);
+      process.exit(
+        await (PACKAGED ? run2(process.execPath, [ASSEMBLE, ...rest]) : run2("npx", ["tsx", ASSEMBLE, ...rest]))
+      );
+    }
+    case "manifest":
+    case "lint": {
+      const input = rest.find((a) => !a.startsWith("-"));
+      if (!input) fail(`${command} needs a scene file
+
+${USAGE}`);
+      const inputPath = userPath(input);
+      if (!existsSync6(inputPath)) fail(`no such file: ${inputPath}`);
+      const flags = rest.filter((a) => a.startsWith("-"));
+      const entry = command === "manifest" ? MANIFEST : LINT;
+      process.exit(
+        await (PACKAGED ? run2(process.execPath, [entry, inputPath, ...flags]) : run2("npx", ["tsx", entry, inputPath, ...flags]))
+      );
+    }
+    case "verify-overlay": {
+      const fileArgs = rest.filter((a) => !a.startsWith("-"));
+      const flags = rest.filter((a) => a.startsWith("-"));
+      if (fileArgs.length < 2) fail(`verify-overlay needs a base scene and at least one overlay
+
+${USAGE}`);
+      const paths = fileArgs.map((p) => {
+        const ap = userPath(p);
+        if (!existsSync6(ap)) fail(`no such file: ${ap}`);
+        return ap;
+      });
+      process.exit(
+        await (PACKAGED ? run2(process.execPath, [VERIFY_OVERLAY, ...paths, ...flags]) : run2("npx", ["tsx", VERIFY_OVERLAY, ...paths, ...flags]))
+      );
+    }
     case "compile": {
       const hasInlineSource = rest.includes("--stdin") || rest.includes("--code");
       const fileArg = rest.find((a, i) => !a.startsWith("-") && !["-o", "--code", "--timeout"].includes(rest[i - 1] ?? ""));