reframe-video 0.1.0 → 0.1.2

package/dist/bin.js

@@ -10,16 +10,100 @@ var __export = (target, all) => {
 };
 
 // ../core/src/ir.ts
-var DEFAULT_TO_DURATION, DEFAULT_TWEEN_DURATION;
+var DEFAULT_TO_DURATION, DEFAULT_TWEEN_DURATION, DEFAULT_MOTIONPATH_DURATION;
 var init_ir = __esm({
   "../core/src/ir.ts"() {
     "use strict";
     DEFAULT_TO_DURATION = 0.5;
     DEFAULT_TWEEN_DURATION = 0.5;
+    DEFAULT_MOTIONPATH_DURATION = 1;
+  }
+});
+
+// ../core/src/path.ts
+function locate(segCount, u) {
+  if (segCount <= 0) return { i: 0, t: 0 };
+  const clamped = Math.max(0, Math.min(1, u));
+  const scaled = clamped * segCount;
+  let i = Math.floor(scaled);
+  if (i >= segCount) i = segCount - 1;
+  return { i, t: scaled - i };
+}
+function controls(points, closed, i) {
+  const n = points.length;
+  const at = (k) => {
+    if (closed) return points[(k % n + n) % n];
+    return points[Math.max(0, Math.min(n - 1, k))];
+  };
+  return [at(i - 1), at(i), at(i + 1), at(i + 2)];
+}
+function segCountOf(points, closed) {
+  const n = points.length;
+  if (n < 2) return 0;
+  return closed ? n : n - 1;
+}
+function pathPoint(points, closed, u) {
+  const n = points.length;
+  if (n === 0) return [0, 0];
+  if (n === 1) return [points[0][0], points[0][1]];
+  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 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])];
+}
+function pathTangentAngle(points, closed, u) {
+  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]);
+  if (dx === 0 && dy === 0) return 0;
+  return Math.atan2(dy, dx) * 180 / Math.PI;
+}
+var init_path = __esm({
+  "../core/src/path.ts"() {
+    "use strict";
   }
 });
 
 // ../core/src/compile.ts
+function scaleTimeline(tl, k) {
+  switch (tl.kind) {
+    case "seq":
+    case "par":
+      return { ...tl, children: tl.children.map((c) => scaleTimeline(c, k)) };
+    case "stagger":
+      return { ...tl, interval: tl.interval * k, children: tl.children.map((c) => scaleTimeline(c, k)) };
+    case "wait":
+      return { ...tl, duration: tl.duration * k };
+    case "tween":
+      return { ...tl, duration: (tl.duration ?? DEFAULT_TWEEN_DURATION) * k };
+    case "motionPath":
+      return { ...tl, duration: (tl.duration ?? DEFAULT_MOTIONPATH_DURATION) * k };
+    case "to":
+      return {
+        ...tl,
+        duration: (tl.duration ?? DEFAULT_TO_DURATION) * k,
+        ...tl.stagger !== void 0 && { stagger: tl.stagger * k }
+      };
+    case "beat":
+      return {
+        ...tl,
+        children: tl.children.map((c) => scaleTimeline(c, k)),
+        ...tl.gap !== void 0 && { gap: tl.gap * k }
+      };
+  }
+}
+function orderBeats(children) {
+  return children.map((c, i) => ({ c, i, key: c.kind === "beat" && c.order !== void 0 ? c.order : i })).sort((a, b) => a.key - b.key || a.i - b.i).map((x) => x.c);
+}
 function compileScene(ir) {
   const nodeById = /* @__PURE__ */ new Map();
   const nodeOrder = [];
@@ -48,6 +132,7 @@ function compileScene(ir) {
     }
   }
   const segments = /* @__PURE__ */ new Map();
+  const motionPaths = /* @__PURE__ */ new Map();
   const current = new Map(initialValues);
   const pushSegment = (seg) => {
     const k = key(seg.target, seg.prop);
@@ -64,6 +149,50 @@ function compileScene(ir) {
     throw new Error(`cannot animate "${prop}" of "${target}": no base value to start from`);
   };
   const labelTimes = /* @__PURE__ */ new Map();
+  const beatTimes = /* @__PURE__ */ new Map();
+  const durationOf = (tl, start) => {
+    switch (tl.kind) {
+      case "seq": {
+        let t = start;
+        for (const child of orderBeats(tl.children)) t = durationOf(child, t);
+        return t;
+      }
+      case "par": {
+        let end = start;
+        for (const child of tl.children) end = Math.max(end, durationOf(child, start));
+        return end;
+      }
+      case "stagger": {
+        let end = start;
+        tl.children.forEach((child, i) => {
+          end = Math.max(end, durationOf(child, start + i * tl.interval));
+        });
+        return end;
+      }
+      case "wait":
+        return start + tl.duration;
+      case "tween":
+        return start + (tl.duration ?? DEFAULT_TWEEN_DURATION);
+      case "motionPath":
+        return start + (tl.duration ?? DEFAULT_MOTIONPATH_DURATION);
+      case "to": {
+        const override = ir.states?.[tl.state] ?? {};
+        const duration = tl.duration ?? DEFAULT_TO_DURATION;
+        const si = tl.stagger ?? 0;
+        const targets = nodeOrder.filter(
+          (id) => id in override && (tl.filter === void 0 || tl.filter.includes(id))
+        );
+        return start + duration + Math.max(0, targets.length - 1) * si;
+      }
+      case "beat": {
+        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);
+        return beatStart + k * natural;
+      }
+    }
+  };
   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 });
@@ -73,9 +202,19 @@ function compileScene(ir) {
     switch (tl.kind) {
       case "seq": {
         let t = start;
-        for (const child of tl.children) t = walk(child, t);
+        for (const child of orderBeats(tl.children)) t = walk(child, t);
         return t;
       }
+      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 beatStart = tl.at ?? 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 });
+        return end;
+      }
       case "par": {
         let end = start;
         for (const child of tl.children) end = Math.max(end, walk(child, start));
@@ -105,6 +244,23 @@ function compileScene(ir) {
         }
         return start + duration;
       }
+      case "motionPath": {
+        const duration = tl.duration ?? DEFAULT_MOTIONPATH_DURATION;
+        const points = tl.points;
+        const closed = tl.closed ?? false;
+        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 } });
+        if (points.length > 0) {
+          const [ex, ey] = pathPoint(points, closed, 1);
+          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);
+        }
+        return start + duration;
+      }
       case "to": {
         const override = ir.states?.[tl.state] ?? {};
         const duration = tl.duration ?? DEFAULT_TO_DURATION;
@@ -133,14 +289,17 @@ function compileScene(ir) {
   };
   const inferredEnd = ir.timeline ? walk(ir.timeline, 0) : 0;
   for (const list of segments.values()) list.sort((a, b) => a.t0 - b.t0);
+  for (const list of motionPaths.values()) list.sort((a, b) => a.t0 - b.t0);
   return {
     ir,
     duration: ir.duration ?? inferredEnd,
     segments,
+    motionPaths,
     initialValues,
     nodeById,
     nodeOrder,
-    labelTimes
+    labelTimes,
+    beatTimes
   };
 }
 var key;
@@ -148,6 +307,7 @@ var init_compile = __esm({
   "../core/src/compile.ts"() {
     "use strict";
     init_ir();
+    init_path();
     key = (target, prop) => `${target}.${prop}`;
   }
 });
@@ -232,9 +392,39 @@ function validateScene(ir) {
           problems.push(`${path}: 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(", ")}`
+          );
+        } else if (node.type === "line") {
+          problems.push(`${path}: 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.duration !== void 0 && tl.duration <= 0) {
+          problems.push(`${path}: motionPath "${tl.target}" duration must be > 0`);
+        }
+        break;
+      }
       case "wait":
         if (tl.duration < 0) problems.push(`${path}: 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`
+          );
+        }
+        labels.add(tl.name);
+        if (tl.duration !== void 0 && tl.duration <= 0) {
+          problems.push(`${path}: 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`);
+        }
+        tl.children.forEach((c, i) => checkTimeline(c, `${path}.beat(${tl.name})[${i}]`));
+        break;
     }
   };
   if (ir.timeline) checkTimeline(ir.timeline, "timeline");
@@ -283,6 +473,8 @@ var init_validate = __esm({
       ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
       line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress"],
       text: [...COMMON_PROPS, "content", "contentDecimals", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
+      image: [...COMMON_PROPS, "src", "width", "height"],
+      path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
       group: COMMON_PROPS
     };
     SceneValidationError = class extends Error {
@@ -429,13 +621,16 @@ function applyOverlay(ir, overlay, layer, report) {
     const byLabel = /* @__PURE__ */ new Map();
     const walkTimeline = (tl) => {
       if ("label" in tl && tl.label !== void 0) byLabel.set(tl.label, tl);
+      if (tl.kind === "beat") byLabel.set(tl.name, tl);
       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"]
+      wait: ["duration"],
+      motionPath: ["points", "duration", "ease"],
+      beat: ["at", "gap", "scale", "duration", "order"]
     };
     let timingPatched = false;
     for (const [label, patch] of Object.entries(overlay.timeline)) {
@@ -459,7 +654,7 @@ function applyOverlay(ir, overlay, layer, report) {
         }
         step[key2] = value;
         applied(`timeline.${label}.${key2}`, "set");
-        if (key2 === "duration" || key2 === "stagger") timingPatched = true;
+        if (["duration", "stagger", "at", "gap", "scale", "order"].includes(key2)) timingPatched = true;
       }
     }
     if (timingPatched && overlay.scene?.duration === void 0) {
@@ -483,6 +678,16 @@ var init_compose = __esm({
   }
 });
 
+// ../core/src/presets.ts
+var SET;
+var init_presets = __esm({
+  "../core/src/presets.ts"() {
+    "use strict";
+    init_dsl();
+    SET = 1 / 120;
+  }
+});
+
 // ../core/src/audio.ts
 function resolveAudioPlan(compiled) {
   const audio = compiled.ir.audio;
@@ -568,10 +773,23 @@ var init_behaviors = __esm({
 });
 
 // ../core/src/interpolate.ts
-var EASE_TABLE, EASE_NAMES;
+function easeOutBounce(u) {
+  const n1 = 7.5625;
+  const d1 = 2.75;
+  if (u < 1 / d1) return n1 * u * u;
+  if (u < 2 / d1) return n1 * (u -= 1.5 / d1) * u + 0.75;
+  if (u < 2.5 / d1) return n1 * (u -= 2.25 / d1) * u + 0.9375;
+  return n1 * (u -= 2.625 / d1) * u + 0.984375;
+}
+var BACK_C1, BACK_C2, BACK_C3, ELASTIC_C4, ELASTIC_C5, EASE_TABLE, EASE_NAMES;
 var init_interpolate = __esm({
   "../core/src/interpolate.ts"() {
     "use strict";
+    BACK_C1 = 1.70158;
+    BACK_C2 = BACK_C1 * 1.525;
+    BACK_C3 = BACK_C1 + 1;
+    ELASTIC_C4 = 2 * Math.PI / 3;
+    ELASTIC_C5 = 2 * Math.PI / 4.5;
     EASE_TABLE = {
       linear: (u) => u,
       easeInQuad: (u) => u * u,
@@ -585,7 +803,20 @@ var init_interpolate = __esm({
       easeInOutQuart: (u) => u < 0.5 ? 8 * u ** 4 : 1 - (-2 * u + 2) ** 4 / 2,
       easeInExpo: (u) => u === 0 ? 0 : 2 ** (10 * u - 10),
       easeOutExpo: (u) => u === 1 ? 1 : 1 - 2 ** (-10 * u),
-      easeInOutExpo: (u) => u === 0 ? 0 : u === 1 ? 1 : u < 0.5 ? 2 ** (20 * u - 10) / 2 : (2 - 2 ** (-20 * u + 10)) / 2
+      easeInOutExpo: (u) => u === 0 ? 0 : u === 1 ? 1 : u < 0.5 ? 2 ** (20 * u - 10) / 2 : (2 - 2 ** (-20 * u + 10)) / 2,
+      // --- expressive eases (GSAP's signature feel) — standard Penner equations ---
+      // back: overshoots past the target then settles (pop / snap)
+      easeInBack: (u) => BACK_C3 * u ** 3 - BACK_C1 * u * u,
+      easeOutBack: (u) => 1 + BACK_C3 * (u - 1) ** 3 + BACK_C1 * (u - 1) ** 2,
+      easeInOutBack: (u) => u < 0.5 ? (2 * u) ** 2 * ((BACK_C2 + 1) * 2 * u - BACK_C2) / 2 : ((2 * u - 2) ** 2 * ((BACK_C2 + 1) * (2 * u - 2) + BACK_C2) + 2) / 2,
+      // elastic: rings around the target before settling (playful spring)
+      easeInElastic: (u) => u === 0 ? 0 : u === 1 ? 1 : -(2 ** (10 * u - 10)) * Math.sin((u * 10 - 10.75) * ELASTIC_C4),
+      easeOutElastic: (u) => u === 0 ? 0 : u === 1 ? 1 : 2 ** (-10 * u) * Math.sin((u * 10 - 0.75) * ELASTIC_C4) + 1,
+      easeInOutElastic: (u) => u === 0 ? 0 : u === 1 ? 1 : u < 0.5 ? -(2 ** (20 * u - 10) * Math.sin((20 * u - 11.125) * ELASTIC_C5)) / 2 : 2 ** (-20 * u + 10) * Math.sin((20 * u - 11.125) * ELASTIC_C5) / 2 + 1,
+      // bounce: drops and bounces to rest (lands without overshoot)
+      easeInBounce: (u) => 1 - easeOutBounce(1 - u),
+      easeOutBounce,
+      easeInOutBounce: (u) => u < 0.5 ? (1 - easeOutBounce(1 - 2 * u)) / 2 : (1 + easeOutBounce(2 * u - 1)) / 2
     };
     EASE_NAMES = Object.keys(EASE_TABLE);
   }
@@ -597,6 +828,52 @@ var init_evaluate = __esm({
     "use strict";
     init_behaviors();
     init_interpolate();
+    init_path();
+  }
+});
+
+// ../core/src/assets.ts
+function collectImageSrcs(ir) {
+  const srcs = /* @__PURE__ */ new Set();
+  const imageIds = /* @__PURE__ */ new Set();
+  const walkNodes = (nodes) => {
+    for (const node of nodes) {
+      if (node.type === "image") {
+        imageIds.add(node.id);
+        srcs.add(node.props.src);
+      }
+      if (node.type === "group") walkNodes(node.children);
+    }
+  };
+  walkNodes(ir.nodes);
+  for (const overrides of Object.values(ir.states ?? {})) {
+    for (const [nodeId, props] of Object.entries(overrides)) {
+      if (imageIds.has(nodeId) && typeof props.src === "string") srcs.add(props.src);
+    }
+  }
+  const walkTimeline = (step) => {
+    if (!step) return;
+    if (step.kind === "seq" || step.kind === "par" || step.kind === "stagger") {
+      for (const child of step.children) walkTimeline(child);
+    } else if (step.kind === "tween" && imageIds.has(step.target)) {
+      const src = step.props.src;
+      if (typeof src === "string") srcs.add(src);
+    }
+  };
+  walkTimeline(ir.timeline);
+  return [...srcs];
+}
+var init_assets = __esm({
+  "../core/src/assets.ts"() {
+    "use strict";
+  }
+});
+
+// ../core/src/motion.ts
+var init_motion = __esm({
+  "../core/src/motion.ts"() {
+    "use strict";
+    init_dsl();
   }
 });
 
@@ -609,10 +886,14 @@ var init_src = __esm({
     init_validate();
     init_compose();
     init_compile();
+    init_path();
+    init_presets();
     init_audio();
     init_evaluate();
     init_interpolate();
     init_behaviors();
+    init_assets();
+    init_motion();
   }
 });
 
@@ -988,12 +1269,12 @@ async function encodeMp4(framesDir, fps, outFile) {
     "+faststart",
     outFile
   ];
-  await new Promise((resolve4, reject) => {
+  await new Promise((resolve5, reject) => {
     const proc = spawn2("ffmpeg", args, { stdio: ["ignore", "ignore", "pipe"] });
     let stderr = "";
     proc.stderr.on("data", (d) => stderr += d.toString());
     proc.on("close", (code) => {
-      if (code === 0) resolve4();
+      if (code === 0) resolve5();
       else reject(new Error(`ffmpeg exited with ${code}:
 ${stderr.slice(-2e3)}`));
     });
@@ -1036,6 +1317,45 @@ var init_fonts = __esm({
   }
 });
 
+// ../render-cli/src/images.ts
+import { readFile as readFile2 } from "node:fs/promises";
+import { existsSync as existsSync2 } from "node:fs";
+import { extname, isAbsolute as isAbsolute2, resolve as resolve2 } from "node:path";
+async function buildImageAssets(ir, sceneDir) {
+  const assets = {};
+  for (const src of collectImageSrcs(ir)) {
+    const mime = MIME[extname(src).toLowerCase()];
+    if (!mime) {
+      throw new Error(
+        `image "${src}": unsupported format "${extname(src)}" \u2014 supported: ${Object.keys(MIME).join(" ")}`
+      );
+    }
+    const candidates = [isAbsolute2(src) ? src : null, resolve2(sceneDir, src)].filter(
+      (c) => c !== null
+    );
+    const found = candidates.find((c) => existsSync2(c));
+    if (!found) {
+      throw new Error(`image "${src}" not found (tried: ${candidates.join(", ")})`);
+    }
+    const data = await readFile2(found);
+    assets[src] = `data:${mime};base64,${data.toString("base64")}`;
+  }
+  return assets;
+}
+var MIME;
+var init_images = __esm({
+  "../render-cli/src/images.ts"() {
+    "use strict";
+    init_src();
+    MIME = {
+      ".png": "image/png",
+      ".jpg": "image/jpeg",
+      ".jpeg": "image/jpeg",
+      ".webp": "image/webp"
+    };
+  }
+});
+
 // ../render-cli/src/vclock.ts
 var VCLOCK_SOURCE;
 var init_vclock = __esm({
@@ -1141,8 +1461,8 @@ async function withPage(size, fn) {
 async function browserBundle() {
   if (bundleCache) return bundleCache;
   if (true) {
-    const { readFile: readFile4 } = await import("node:fs/promises");
-    bundleCache = await readFile4(
+    const { readFile: readFile5 } = await import("node:fs/promises");
+    bundleCache = await readFile5(
       join4(dirname4(fileURLToPath3(import.meta.url)), "browserEntry.js"),
       "utf8"
     );
@@ -1161,6 +1481,7 @@ async function browserBundle() {
 }
 async function captureIr(ir, opts) {
   await mkdir2(opts.framesDir, { recursive: true });
+  const assets = await buildImageAssets(ir, opts.sceneDir ?? process.cwd());
   const bundle = await browserBundle();
   return withPage(ir.size, async (page) => {
     await page.setContent(
@@ -1169,8 +1490,8 @@ async function captureIr(ir, opts) {
     await injectFonts(page);
     await page.addScriptTag({ content: bundle });
     const info = await page.evaluate(
-      (sceneIr) => window.__reframe.init(sceneIr),
-      ir
+      ([sceneIr, imageAssets]) => window.__reframe.init(sceneIr, imageAssets),
+      [ir, assets]
     );
     const fps = opts.fps ?? info.fps;
     const duration = opts.duration ?? info.duration;
@@ -1187,6 +1508,7 @@ var init_frameLoop = __esm({
   "../render-cli/src/frameLoop.ts"() {
     "use strict";
     init_fonts();
+    init_images();
     init_vclock();
     init_reframeGlobal();
     framePath = (dir, i) => join4(dir, `${String(i).padStart(5, "0")}.png`);
@@ -1202,9 +1524,9 @@ __export(batch_exports, {
   parseCsv: () => parseCsv,
   runBatch: () => runBatch
 });
-import { mkdir as mkdir3, mkdtemp as mkdtemp2, readFile as readFile2, rm as rm2, writeFile as writeFile4 } from "node:fs/promises";
+import { mkdir as mkdir3, mkdtemp as mkdtemp2, readFile as readFile3, rm as rm2, writeFile as writeFile4 } from "node:fs/promises";
 import { tmpdir as tmpdir3 } from "node:os";
-import { join as join5 } from "node:path";
+import { join as join5, dirname as dirname5 } from "node:path";
 function overlayFromFlat(row, name) {
   const doc = { reframeOverlay: 1, name };
   for (const [key2, raw] of Object.entries(row)) {
@@ -1278,7 +1600,7 @@ function parseCsv(text) {
   });
 }
 async function loadRows(path) {
-  const text = await readFile2(path, "utf8");
+  const text = await readFile3(path, "utf8");
   if (path.endsWith(".csv")) return parseCsv(text);
   const parsed = JSON.parse(text);
   if (!Array.isArray(parsed)) throw new Error(`${path}: expected a JSON array of row objects`);
@@ -1304,6 +1626,7 @@ async function runBatch(scene, rows, opts) {
         try {
           const captured = await captureIr(ir, {
             framesDir,
+            ...opts.scenePath !== void 0 && { sceneDir: dirname5(opts.scenePath) },
             ...opts.fps !== void 0 && { fps: opts.fps }
           });
           if (plan) {
@@ -1362,12 +1685,12 @@ __export(loadScene_exports, {
   loadScene: () => loadScene
 });
 import { build as build2 } from "esbuild";
-import { readFile as readFile3 } from "node:fs/promises";
-import { dirname as dirname5, resolve as resolve2 } from "node:path";
+import { readFile as readFile4 } from "node:fs/promises";
+import { dirname as dirname6, resolve as resolve3 } from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 async function loadScene(path) {
   if (path.endsWith(".json")) {
-    const ir = JSON.parse(await readFile3(path, "utf8"));
+    const ir = JSON.parse(await readFile4(path, "utf8"));
     validateScene(ir);
     return ir;
   }
@@ -1401,24 +1724,25 @@ var init_loadScene = __esm({
   "../render-cli/src/loadScene.ts"() {
     "use strict";
     init_src();
-    HERE = dirname5(fileURLToPath4(import.meta.url));
-    CORE_ENTRY = true ? resolve2(HERE, "index.js") : resolve2(HERE, "..", "..", "core", "src", "index.ts");
+    HERE = dirname6(fileURLToPath4(import.meta.url));
+    CORE_ENTRY = true ? resolve3(HERE, "index.js") : resolve3(HERE, "..", "..", "core", "src", "index.ts");
   }
 });
 
 // ../render-cli/src/reframe.ts
 import { spawn as spawn3, spawnSync } from "node:child_process";
-import { existsSync as existsSync2 } from "node:fs";
+import { existsSync as existsSync3 } from "node:fs";
 import { mkdir as mkdir4, writeFile as writeFile5 } from "node:fs/promises";
-import { basename, isAbsolute as isAbsolute2, join as join6, resolve as resolve3 } from "node:path";
-import { dirname as dirname6 } from "node:path";
+import { basename, isAbsolute as isAbsolute3, join as join6, resolve as resolve4 } from "node:path";
+import { dirname as dirname7 } from "node:path";
 import { fileURLToPath as fileURLToPath5 } from "node:url";
 var PACKAGED = true;
-var HERE2 = dirname6(fileURLToPath5(import.meta.url));
-var ROOT2 = PACKAGED ? resolve3(HERE2, "..") : resolve3(HERE2, "..", "..", "..");
+var HERE2 = dirname7(fileURLToPath5(import.meta.url));
+var ROOT2 = PACKAGED ? resolve4(HERE2, "..") : resolve4(HERE2, "..", "..", "..");
 var USER_CWD = process.env.INIT_CWD ?? process.cwd();
 var RENDER_CLI = PACKAGED ? join6(ROOT2, "dist", "cli.js") : join6(ROOT2, "packages", "render-cli", "src", "cli.ts");
 var ANALYZE = PACKAGED ? join6(ROOT2, "dist", "analyze.js") : join6(ROOT2, "benchmark", "harness", "motion", "analyze.ts");
+var TRACE = PACKAGED ? join6(ROOT2, "dist", "trace-cli.js") : join6(ROOT2, "benchmark", "harness", "motion", "trace-cli.ts");
 var CMD = PACKAGED ? "reframe" : "pnpm reframe";
 var USAGE = `reframe \u2014 declarative motion graphics
 
@@ -1428,10 +1752,11 @@ usage:
   ${CMD} preview                 open the scrub/edit UI (lists scenes in your directory)
   ${CMD} new <scene-name>        scaffold <scene-name>.ts in your directory
   ${CMD} motion <mp4|framesDir>  motion-profile a rendered clip
+  ${CMD} trace <ref.mp4> [--apply scene.ts]  extract a video's motion structure \u2192 MotionSketch / timeline
   ${CMD} guide [--regen]         print the scene-authoring guide (for you or your AI)
   ${CMD} demo                    run the edit-survival demo (3 mp4s into out/)
 `;
-var userPath = (p) => isAbsolute2(p) ? p : resolve3(USER_CWD, p);
+var userPath = (p) => isAbsolute3(p) ? p : resolve4(USER_CWD, p);
 function fail(message) {
   console.error(`error: ${message}`);
   process.exit(2);
@@ -1533,7 +1858,7 @@ async function main() {
 
 ${USAGE}`);
       const inputPath = userPath(input);
-      if (!existsSync2(inputPath)) fail(`no such file: ${inputPath}`);
+      if (!existsSync3(inputPath)) fail(`no such file: ${inputPath}`);
       const mode = /\.(ts|json)$/.test(input) ? "ir" : /\.html$/.test(input) ? "html" : null;
       if (!mode) {
         fail(`cannot infer render mode from "${input}" \u2014 expected .ts/.json (reframe scene) or .html (GSAP page)`);
@@ -1561,7 +1886,7 @@ ${USAGE}`);
       if (!sceneArg || !dataArg) fail(`usage: ${CMD} batch <scene.ts> <data.json|csv> [...]`);
       const scenePath = userPath(sceneArg);
       const dataPath = userPath(dataArg);
-      for (const p of [scenePath, dataPath]) if (!existsSync2(p)) fail(`no such file: ${p}`);
+      for (const p of [scenePath, dataPath]) if (!existsSync3(p)) fail(`no such file: ${p}`);
       preflightFfmpeg();
       let outDir = PACKAGED ? join6(USER_CWD, "out", "batch") : join6(ROOT2, "out", "batch");
       let concurrency = 3;
@@ -1576,10 +1901,10 @@ ${USAGE}`);
       }
       const { loadRows: loadRows2, runBatch: runBatch2 } = await Promise.resolve().then(() => (init_batch(), batch_exports));
       const { loadScene: loadScene2 } = await Promise.resolve().then(() => (init_loadScene(), loadScene_exports));
-      const { readFile: readFile4 } = await import("node:fs/promises");
+      const { readFile: readFile5 } = await import("node:fs/promises");
       const scene = await loadScene2(scenePath);
       const baseOverlays = await Promise.all(
-        baseOverlayPaths.map(async (p) => JSON.parse(await readFile4(p, "utf8")))
+        baseOverlayPaths.map(async (p) => JSON.parse(await readFile5(p, "utf8")))
       );
       const rows = await loadRows2(dataPath);
       if (rows.length === 0) fail(`${dataPath}: no data rows`);
@@ -1610,7 +1935,7 @@ ${results.length - failed} rendered (${orphaned} with orphans), ${failed} failed
       if (PACKAGED) {
         const { createRequire } = await import("node:module");
         const vitePkg = createRequire(import.meta.url).resolve("vite/package.json");
-        const viteBin = join6(dirname6(vitePkg), "bin", "vite.js");
+        const viteBin = join6(dirname7(vitePkg), "bin", "vite.js");
         process.exit(
           await run(process.execPath, [viteBin, join6(ROOT2, "preview")], {
             env: { REFRAME_SCENE_DIR: USER_CWD }
@@ -1633,7 +1958,7 @@ ${results.length - failed} rendered (${orphaned} with orphans), ${failed} failed
       const targetDir = inRepo ? join6(ROOT2, "examples", "scenes") : USER_CWD;
       const target = join6(targetDir, `${name}.ts`);
       const shown = inRepo ? `examples/scenes/${name}.ts` : `${name}.ts`;
-      if (existsSync2(target)) fail(`${shown} already exists`);
+      if (existsSync3(target)) fail(`${shown} already exists`);
       const id = name.split("-")[0] ?? name;
       await writeFile5(target, SCENE_TEMPLATE(name, id));
       console.log(`created ${shown}
@@ -1650,10 +1975,21 @@ ${results.length - failed} rendered (${orphaned} with orphans), ${failed} failed
         await (PACKAGED ? run(process.execPath, [ANALYZE, userPath(input), ...rest.slice(1)]) : run("npx", ["tsx", ANALYZE, userPath(input), ...rest.slice(1)]))
       );
     }
+    case "trace": {
+      const input = rest[0];
+      if (!input || input.startsWith("-")) fail(`usage: ${CMD} trace <ref.mp4> [--apply scene.ts] [-o out.json]`);
+      preflightFfmpeg();
+      const args = rest.slice(1).map(
+        (a, i) => rest.slice(1)[i - 1] === "--apply" || rest.slice(1)[i - 1] === "-o" ? userPath(a) : a
+      );
+      process.exit(
+        await (PACKAGED ? run(process.execPath, [TRACE, userPath(input), ...args]) : run("npx", ["tsx", TRACE, userPath(input), ...args]))
+      );
+    }
     case "guide": {
       const file = rest.includes("--regen") ? PACKAGED ? join6(ROOT2, "guides", "regen-contract.md") : join6(ROOT2, "docs", "regen-contract.md") : PACKAGED ? join6(ROOT2, "guides", "edsl-guide.md") : join6(ROOT2, "benchmark", "guides", "edsl-guide.md");
-      const { readFile: readFile4 } = await import("node:fs/promises");
-      process.stdout.write(await readFile4(file, "utf8"));
+      const { readFile: readFile5 } = await import("node:fs/promises");
+      process.stdout.write(await readFile5(file, "utf8"));
       return;
     }
     case "demo":