reframe-video 0.1.0 → 0.1.2

package/dist/trace-cli.js

@@ -0,0 +1,677 @@
+#!/usr/bin/env tsx
+
+// ../../benchmark/harness/motion/trace-cli.ts
+import { writeFile as writeFile2 } from "node:fs/promises";
+import { resolve as resolve2 } from "node:path";
+import { pathToFileURL } from "node:url";
+
+// ../core/src/validate.ts
+var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "anchor"];
+var PROPS_BY_TYPE = {
+  rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
+  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
+};
+
+// ../core/src/dsl.ts
+function seq(...children) {
+  return { kind: "seq", children };
+}
+function par(...children) {
+  return { kind: "par", children };
+}
+function tween(target, props, opts = {}) {
+  return { kind: "tween", target, props, ...opts };
+}
+function wait(duration, label) {
+  return { kind: "wait", duration, ...label !== void 0 && { label } };
+}
+
+// ../core/src/presets.ts
+var SET = 1 / 120;
+
+// ../core/src/interpolate.ts
+var BACK_C1 = 1.70158;
+var BACK_C2 = BACK_C1 * 1.525;
+var BACK_C3 = BACK_C1 + 1;
+var ELASTIC_C4 = 2 * Math.PI / 3;
+var ELASTIC_C5 = 2 * Math.PI / 4.5;
+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 EASE_TABLE = {
+  linear: (u) => u,
+  easeInQuad: (u) => u * u,
+  easeOutQuad: (u) => 1 - (1 - u) * (1 - u),
+  easeInOutQuad: (u) => u < 0.5 ? 2 * u * u : 1 - (-2 * u + 2) ** 2 / 2,
+  easeInCubic: (u) => u ** 3,
+  easeOutCubic: (u) => 1 - (1 - u) ** 3,
+  easeInOutCubic: (u) => u < 0.5 ? 4 * u ** 3 : 1 - (-2 * u + 2) ** 3 / 2,
+  easeInQuart: (u) => u ** 4,
+  easeOutQuart: (u) => 1 - (1 - u) ** 4,
+  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,
+  // --- 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
+};
+var EASE_NAMES = Object.keys(EASE_TABLE);
+
+// ../core/src/motion.ts
+var EASE_BY_CLASS = {
+  accelerating: "easeInCubic",
+  decelerating: "easeOutCubic",
+  linear: "linear"
+};
+function easeFor(easing) {
+  return EASE_BY_CLASS[easing.class] ?? "easeOutCubic";
+}
+function sketchToTimeline(sketch, nodeIds) {
+  if (nodeIds.length === 0) return seq();
+  const events = [...sketch.events].sort((a, b) => a.t0 - b.t0);
+  const steps = [];
+  events.forEach((ev, i) => {
+    const node = nodeIds[i % nodeIds.length];
+    const dur = Math.max(0.05, ev.t1 - ev.t0);
+    const ease = easeFor(ev.easing);
+    let motion;
+    switch (ev.kind) {
+      case "enter":
+        motion = tween(node, { opacity: 1 }, { duration: dur, ease });
+        break;
+      case "exit":
+        motion = tween(node, { opacity: 0 }, { duration: dur, ease });
+        break;
+      case "emphasis": {
+        const peak = 1 + Math.max(0.08, Math.min(0.5, ev.magnitude));
+        motion = seq(
+          tween(node, { scale: peak }, { duration: dur / 2, ease: "easeOutCubic" }),
+          tween(node, { scale: 1 }, { duration: dur / 2, ease: "easeInOutQuad" })
+        );
+        break;
+      }
+      case "scale":
+        motion = tween(node, { scale: 1 + Math.max(-0.5, Math.min(0.5, ev.magnitude)) }, { duration: dur, ease });
+        break;
+      case "move":
+        motion = tween(node, { opacity: 1 }, { duration: dur, ease });
+        break;
+    }
+    steps.push(ev.t0 > 0 ? seq(wait(ev.t0), motion) : motion);
+  });
+  return par(...steps);
+}
+
+// ../../benchmark/harness/motion/analyze.ts
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { readFileSync } from "node:fs";
+
+// ../../benchmark/harness/motion/blockflow.ts
+var DEFAULT_OPTIONS = {
+  scale: 4,
+  // 480x270 analysis of 1920x1080
+  blockSize: 16,
+  searchRadius: 12,
+  changedThreshold: 2,
+  blockActivityThreshold: 1.5,
+  movingThreshold: 0.3
+};
+function blockSad(prev, next, width, bx, by, dx, dy, size) {
+  let sad = 0;
+  for (let y = 0; y < size; y++) {
+    let nextRow = (by + y) * width + bx;
+    let prevRow = (by + y + dy) * width + bx + dx;
+    for (let x = 0; x < size; x++) {
+      sad += Math.abs(next[nextRow + x] - prev[prevRow + x]);
+    }
+  }
+  return sad;
+}
+function parabola(left, best, right) {
+  const denom = left - 2 * best + right;
+  if (denom <= 0) return 0;
+  return Math.max(-0.5, Math.min(0.5, (left - right) / (2 * denom)));
+}
+function analyzePair(prev, next, opts) {
+  const { width, height, scale, blockSize, searchRadius: R, changedThreshold } = opts;
+  let diffSum = 0;
+  let changed = 0;
+  const n = width * height;
+  for (let i = 0; i < n; i++) {
+    const d = Math.abs(next[i] - prev[i]);
+    diffSum += d;
+    if (d > changedThreshold) changed++;
+  }
+  const diffMean = diffSum / n;
+  const changedFraction = changed / n;
+  const speeds = [];
+  let movingCount = 0;
+  let saturatedCount = 0;
+  let residualSum = 0;
+  let zeroSadSum = 0;
+  let bestSadSum = 0;
+  let activeBlocks = 0;
+  const pxPerBlock = blockSize * blockSize;
+  for (let by = R; by + blockSize + R <= height; by += blockSize) {
+    for (let bx = R; bx + blockSize + R <= width; bx += blockSize) {
+      const zeroSad = blockSad(prev, next, width, bx, by, 0, 0, blockSize);
+      if (zeroSad / pxPerBlock < opts.blockActivityThreshold) continue;
+      activeBlocks++;
+      const PENALTY = 2;
+      let best = zeroSad;
+      let bestScore = zeroSad;
+      let bestDx = 0;
+      let bestDy = 0;
+      for (let dy = -R; dy <= R; dy++) {
+        for (let dx = -R; dx <= R; dx++) {
+          if (dx === 0 && dy === 0) continue;
+          const sad = blockSad(prev, next, width, bx, by, dx, dy, blockSize);
+          const score = sad + PENALTY * (Math.abs(dx) + Math.abs(dy));
+          if (score < bestScore) {
+            bestScore = score;
+            best = sad;
+            bestDx = dx;
+            bestDy = dy;
+          }
+        }
+      }
+      let fx = bestDx;
+      let fy = bestDy;
+      if (Math.abs(bestDx) < R) {
+        fx += parabola(
+          blockSad(prev, next, width, bx, by, bestDx - 1, bestDy, blockSize),
+          best,
+          blockSad(prev, next, width, bx, by, bestDx + 1, bestDy, blockSize)
+        );
+      }
+      if (Math.abs(bestDy) < R) {
+        fy += parabola(
+          blockSad(prev, next, width, bx, by, bestDx, bestDy - 1, blockSize),
+          best,
+          blockSad(prev, next, width, bx, by, bestDx, bestDy + 1, blockSize)
+        );
+      }
+      const speed = Math.hypot(fx, fy);
+      residualSum += best / pxPerBlock;
+      zeroSadSum += zeroSad;
+      bestSadSum += best;
+      if (Math.abs(bestDx) >= R || Math.abs(bestDy) >= R) saturatedCount++;
+      if ((bestDx !== 0 || bestDy !== 0) && speed > opts.movingThreshold && best < 0.6 * zeroSad) {
+        movingCount++;
+        speeds.push(speed * scale);
+      }
+    }
+  }
+  speeds.sort((a, b) => a - b);
+  const matchResidual = activeBlocks > 0 ? residualSum / activeBlocks : 0;
+  return {
+    blockSpeedMean: speeds.length ? speeds.reduce((a, b) => a + b, 0) / speeds.length : 0,
+    blockSpeedP95: speeds.length ? speeds[Math.min(speeds.length - 1, Math.floor(speeds.length * 0.95))] : 0,
+    movingFraction: activeBlocks > 0 ? movingCount / activeBlocks : 0,
+    diffMean,
+    changedFraction,
+    matchResidual,
+    nonGeometricRatio: zeroSadSum > 0 ? Math.min(1, bestSadSum / zeroSadSum) : 0,
+    saturatedFraction: activeBlocks > 0 ? saturatedCount / activeBlocks : 0,
+    activeBlocks
+  };
+}
+
+// ../../benchmark/harness/motion/frames.ts
+import { spawn } from "node:child_process";
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
+async function resolveSource(path) {
+  const s = await stat(path);
+  if (s.isDirectory()) return { kind: "png", input: join(path, "%05d.png") };
+  return { kind: "mp4", input: path };
+}
+async function* frameStream(source, opts) {
+  const frameBytes = opts.width * opts.height;
+  const args = [
+    "-loglevel",
+    "error",
+    ...source.kind === "png" ? ["-framerate", "30"] : [],
+    "-i",
+    source.input,
+    "-f",
+    "rawvideo",
+    "-pix_fmt",
+    "gray",
+    "-s",
+    `${opts.width}x${opts.height}`,
+    "-"
+  ];
+  const proc = spawn("ffmpeg", args, { stdio: ["ignore", "pipe", "pipe"] });
+  let stderr = "";
+  proc.stderr.on("data", (d) => stderr += d.toString());
+  let pending = Buffer.alloc(0);
+  for await (const chunk of proc.stdout) {
+    pending = pending.length === 0 ? chunk : Buffer.concat([pending, chunk]);
+    while (pending.length >= frameBytes) {
+      yield new Uint8Array(pending.subarray(0, frameBytes));
+      pending = pending.subarray(frameBytes);
+    }
+  }
+  const code = await new Promise((res) => proc.on("close", (c) => res(c ?? 1)));
+  if (code !== 0) throw new Error(`ffmpeg exited ${code}: ${stderr.slice(-1e3)}`);
+  if (pending.length !== 0) throw new Error(`trailing partial frame (${pending.length} bytes)`);
+}
+
+// ../../benchmark/harness/motion/grid.ts
+var DEFAULT_GRID = { cols: 8, rows: 5 };
+var cellOf = (x, y, w, h, spec) => {
+  const c = Math.min(spec.cols - 1, Math.floor(x * spec.cols / w));
+  const r = Math.min(spec.rows - 1, Math.floor(y * spec.rows / h));
+  return r * spec.cols + c;
+};
+function cellDiff(prev, next, w, h, spec) {
+  const n = spec.cols * spec.rows;
+  const sum = new Array(n).fill(0);
+  const cnt = new Array(n).fill(0);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const idx = cellOf(x, y, w, h, spec);
+      sum[idx] += Math.abs(next[y * w + x] - prev[y * w + x]);
+      cnt[idx]++;
+    }
+  }
+  return sum.map((s, i) => cnt[i] ? s / cnt[i] : 0);
+}
+function frameOccupancy(frame, w, h, spec) {
+  const n = spec.cols * spec.rows;
+  const sum = new Array(n).fill(0);
+  const cnt = new Array(n).fill(0);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const here = frame[y * w + x];
+      const gx = x + 1 < w ? Math.abs(frame[y * w + x + 1] - here) : 0;
+      const gy = y + 1 < h ? Math.abs(frame[(y + 1) * w + x] - here) : 0;
+      const idx = cellOf(x, y, w, h, spec);
+      sum[idx] += gx + gy;
+      cnt[idx]++;
+    }
+  }
+  return sum.map((s, i) => cnt[i] ? s / cnt[i] : 0);
+}
+
+// ../../benchmark/harness/motion/analyze.ts
+var ANALYSIS_WIDTH = 480;
+var ANALYSIS_HEIGHT = 270;
+var mean = (xs) => xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0;
+function rollingMedian(xs, i, w) {
+  const half = Math.floor(w / 2);
+  const window = [];
+  for (let j = Math.max(0, i - half); j <= Math.min(xs.length - 1, i + half); j++) {
+    if (j !== i) window.push(xs[j]);
+  }
+  window.sort((a, b) => a - b);
+  return window.length ? window[Math.floor(window.length / 2)] : 0;
+}
+function spearman(xs, ys) {
+  const n = xs.length;
+  if (n < 4) return null;
+  const rank = (vs) => {
+    const sorted = vs.map((v, i) => [v, i]).sort((a, b) => a[0] - b[0]);
+    const ranks = new Array(n);
+    sorted.forEach(([, originalIndex], r) => ranks[originalIndex] = r);
+    return ranks;
+  };
+  const rx = rank(xs);
+  const ry = rank(ys);
+  const mx = mean(rx);
+  const my = mean(ry);
+  let cov = 0;
+  let vx = 0;
+  let vy = 0;
+  for (let i = 0; i < n; i++) {
+    cov += (rx[i] - mx) * (ry[i] - my);
+    vx += (rx[i] - mx) ** 2;
+    vy += (ry[i] - my) ** 2;
+  }
+  return vx > 0 && vy > 0 ? cov / Math.sqrt(vx * vy) : null;
+}
+function dominantPeriodicity(xs, fps) {
+  const n = xs.length;
+  if (n < 24) return null;
+  const m = mean(xs);
+  const centered = xs.map((x) => x - m);
+  const var0 = mean(centered.map((x) => x * x));
+  if (var0 < 1e-6) return null;
+  const maxLag = Math.floor(n / 2);
+  const corr = [];
+  for (let lag = 0; lag <= maxLag; lag++) {
+    let c = 0;
+    for (let i = 0; i + lag < n; i++) c += centered[i] * centered[i + lag];
+    corr.push(c / ((n - lag) * var0));
+  }
+  let bestLag = 0;
+  let bestCorr = 0;
+  for (let lag = 4; lag < maxLag; lag++) {
+    const isLocalMax = corr[lag] > corr[lag - 1] && corr[lag] >= corr[lag + 1];
+    if (isLocalMax && corr[lag] > bestCorr) {
+      bestCorr = corr[lag];
+      bestLag = lag;
+    }
+  }
+  return bestCorr > 0.3 && bestLag > 0 ? fps / bestLag : null;
+}
+function classifyEasing(speeds, nonGeometricRatios, saturatedFractions) {
+  const reliable = speeds.length >= 6 && mean(nonGeometricRatios) < 0.5 && saturatedFractions.filter((s) => s > 0.3).length / saturatedFractions.length < 0.2 && mean(speeds) > 0.5;
+  if (!reliable) {
+    return { class: "unreliable", thirdsRatio: null, spearman: null, reliable: false };
+  }
+  const third = Math.max(1, Math.floor(speeds.length / 3));
+  const first = mean(speeds.slice(0, third));
+  const last = mean(speeds.slice(-third));
+  const R = last > 0.01 ? first / last : Infinity;
+  const rho = spearman(
+    speeds.map((_, i) => i),
+    speeds
+  );
+  let cls = "other";
+  if (R > 1.8 && rho !== null && rho < -0.5) cls = "decelerating";
+  else if (R < 0.55 && rho !== null && rho > 0.5) cls = "accelerating";
+  else if (R >= 0.7 && R <= 1.4 && rho !== null && Math.abs(rho) < 0.4) cls = "linear";
+  return { class: cls, thirdsRatio: Number.isFinite(R) ? R : null, spearman: rho, reliable: true };
+}
+async function analyzeMotion(inputPath, opts = {}) {
+  const fps = opts.fps ?? 30;
+  const blockOpts = {
+    ...DEFAULT_OPTIONS,
+    width: ANALYSIS_WIDTH,
+    height: ANALYSIS_HEIGHT,
+    ...opts.changedThreshold !== void 0 && { changedThreshold: opts.changedThreshold }
+  };
+  const gridSpec = opts.grid ? typeof opts.grid === "object" ? opts.grid : DEFAULT_GRID : null;
+  const source = await resolveSource(resolve(inputPath));
+  const keys = [
+    "blockSpeedMean",
+    "blockSpeedP95",
+    "movingFraction",
+    "diffMean",
+    "changedFraction",
+    "matchResidual",
+    "nonGeometricRatio",
+    "saturatedFraction",
+    "activeBlocks"
+  ];
+  const series = Object.fromEntries([...keys.map((k) => [k, []]), ["t", []]]);
+  const gridDiff = [];
+  const gridOcc = [];
+  let prev = null;
+  let pair = 0;
+  for await (const frame of frameStream(source, blockOpts)) {
+    if (gridSpec) gridOcc.push(frameOccupancy(frame, ANALYSIS_WIDTH, ANALYSIS_HEIGHT, gridSpec));
+    if (prev) {
+      const stats = analyzePair(prev, frame, blockOpts);
+      for (const k of keys) series[k].push(stats[k]);
+      series.t.push((pair + 0.5) / fps);
+      if (gridSpec) gridDiff.push(cellDiff(prev, frame, ANALYSIS_WIDTH, ANALYSIS_HEIGHT, gridSpec));
+      pair++;
+    }
+    prev = frame;
+  }
+  const d = series.diffMean;
+  const staticFlags = series.changedFraction.map((c) => c < 5e-3);
+  let longestRun = 0;
+  let run = 0;
+  for (const isStatic of staticFlags) {
+    run = isStatic ? run + 1 : 0;
+    longestRun = Math.max(longestRun, run);
+  }
+  const spikes = [];
+  for (let i = 0; i < d.length; i++) {
+    const med = rollingMedian(d, i, 9);
+    const neighbors = Math.max(i > 0 ? d[i - 1] : 0, i + 1 < d.length ? d[i + 1] : 0);
+    if (d[i] > Math.max(4 * med, 1) && series.changedFraction[i] > 0.01 && neighbors < d[i] / 2) {
+      spikes.push({ pair: i, t: series.t[i], ratio: med > 0 ? d[i] / med : Infinity });
+    }
+  }
+  const segments = (opts.segments ?? []).map((seg) => {
+    const idx = series.t.map((t, i) => t >= seg.t0 && t <= seg.t1 ? i : -1).filter((i) => i >= 0);
+    return {
+      ...seg,
+      easing: classifyEasing(
+        idx.map((i) => series.blockSpeedMean[i]),
+        idx.map((i) => series.nonGeometricRatio[i]),
+        idx.map((i) => series.saturatedFraction[i])
+      )
+    };
+  });
+  return {
+    params: { ...blockOpts, analysisWidth: ANALYSIS_WIDTH, analysisHeight: ANALYSIS_HEIGHT, source: source.kind },
+    fps,
+    framePairs: series.t.length,
+    series,
+    summary: {
+      meanSpeed: mean(series.blockSpeedMean.filter((s) => s > 0)),
+      peakSpeed: Math.max(0, ...series.blockSpeedP95),
+      meanDiff: mean(d),
+      staticFraction: staticFlags.filter(Boolean).length / Math.max(1, staticFlags.length),
+      longestStaticRunSec: longestRun / fps,
+      allStatic: staticFlags.every(Boolean),
+      spikes,
+      saturatedPairs: series.saturatedFraction.map((s, i) => s > 0.3 ? i : -1).filter((i) => i >= 0),
+      diffPeriodicityHz: dominantPeriodicity(d, fps)
+    },
+    segments,
+    ...gridSpec && { grid: { spec: gridSpec, diff: gridDiff, occupancy: gridOcc } }
+  };
+}
+async function main() {
+  const [input, ...rest] = process.argv.slice(2);
+  if (!input) {
+    console.error("usage: tsx analyze.ts <mp4|framesDir> [-o out.json] [--fps N] [--segments seg.json] [--changed-threshold N]");
+    process.exit(2);
+  }
+  let out = null;
+  const opts = {};
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === "-o") out = rest[++i];
+    else if (rest[i] === "--fps") opts.fps = Number(rest[++i]);
+    else if (rest[i] === "--segments") opts.segments = JSON.parse(readFileSync(rest[++i], "utf8"));
+    else if (rest[i] === "--changed-threshold") opts.changedThreshold = Number(rest[++i]);
+  }
+  const profile = await analyzeMotion(input, opts);
+  const json = JSON.stringify(profile, null, 1);
+  if (out) await writeFile(out, json);
+  else console.log(json);
+}
+if (/analyze\.(ts|js)$/.test(process.argv[1] ?? "")) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}
+
+// ../../benchmark/harness/motion/sketch.ts
+var HI_FLOOR = 1.5;
+var HI_LO_RATIO = 0.55;
+var NOISE_MARGIN = 1.5;
+var MIN_RUN_PAIRS = 2;
+var CONTINUOUS_FRAC = 0.35;
+var TEMPORAL_SLACK = 7;
+var MOVE_FRACTION = 0.04;
+var OCC_RATIO = 1.4;
+var INPLACE_RATIO = 0.3;
+var mean2 = (xs) => xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0;
+function backgroundLevel(diff) {
+  const flat = [];
+  for (const row of diff) for (const v of row) flat.push(v);
+  if (flat.length === 0) return 0;
+  flat.sort((a, b) => a - b);
+  return flat[Math.floor(flat.length / 2)];
+}
+function findRuns(diff, nCells, hi, lo) {
+  const runs = [];
+  const nPairs = diff.length;
+  for (let cell = 0; cell < nCells; cell++) {
+    let active = false;
+    let start = 0;
+    for (let p = 0; p < nPairs; p++) {
+      const v = diff[p][cell];
+      if (!active && v > hi) {
+        active = true;
+        start = p;
+      } else if (active && v < lo) {
+        if (p - start >= MIN_RUN_PAIRS) runs.push({ cell, p0: start, p1: p - 1 });
+        active = false;
+      }
+    }
+    if (active && nPairs - start >= MIN_RUN_PAIRS) runs.push({ cell, p0: start, p1: nPairs - 1 });
+  }
+  return runs;
+}
+function groupRuns(runs, cols) {
+  const parent = runs.map((_, i) => i);
+  const find = (i) => parent[i] === i ? i : parent[i] = find(parent[i]);
+  const union = (a, b) => {
+    parent[find(a)] = find(b);
+  };
+  const rc = (cell) => ({ r: Math.floor(cell / cols), c: cell % cols });
+  for (let i = 0; i < runs.length; i++) {
+    for (let j = i + 1; j < runs.length; j++) {
+      const a = runs[i];
+      const b = runs[j];
+      const ra = rc(a.cell);
+      const rb = rc(b.cell);
+      const sameCell = a.cell === b.cell;
+      const adjacent = sameCell || Math.abs(ra.r - rb.r) + Math.abs(ra.c - rb.c) === 1;
+      const slack = sameCell ? TEMPORAL_SLACK : 1;
+      const temporal = a.p0 <= b.p1 + slack && b.p0 <= a.p1 + slack;
+      if (adjacent && temporal) union(i, j);
+    }
+  }
+  const groups = /* @__PURE__ */ new Map();
+  runs.forEach((run, i) => {
+    const root = find(i);
+    (groups.get(root) ?? groups.set(root, []).get(root)).push(run);
+  });
+  return [...groups.values()];
+}
+function extractMotionSketch(profile) {
+  const fps = profile.fps;
+  const duration = (profile.framePairs + 1) / fps;
+  const rhythm = {
+    periodicityHz: profile.summary.diffPeriodicityHz,
+    beatCount: 0
+  };
+  if (!profile.grid) {
+    return { duration, fps, events: [], rhythm };
+  }
+  const { spec, diff, occupancy } = profile.grid;
+  const nCells = spec.cols * spec.rows;
+  const nFrames = occupancy.length;
+  const hi = Math.max(HI_FLOOR, backgroundLevel(diff) + NOISE_MARGIN);
+  const lo = hi * HI_LO_RATIO;
+  const groups = groupRuns(findRuns(diff, nCells, hi, lo), spec.cols);
+  const events = groups.map((group) => {
+    const cells = [...new Set(group.map((r) => r.cell))];
+    const p0 = Math.min(...group.map((r) => r.p0));
+    const p1 = Math.max(...group.map((r) => r.p1));
+    const cols = cells.map((c) => c % spec.cols);
+    const rows = cells.map((c) => Math.floor(c / spec.cols));
+    const minC = Math.min(...cols);
+    const maxC = Math.max(...cols);
+    const minR = Math.min(...rows);
+    const maxR = Math.max(...rows);
+    const region = {
+      x: minC / spec.cols,
+      y: minR / spec.rows,
+      w: (maxC - minC + 1) / spec.cols,
+      h: (maxR - minR + 1) / spec.rows
+    };
+    const win = (arr) => arr.slice(p0, p1 + 1);
+    const speeds = win(profile.series.blockSpeedMean);
+    const ngrs = win(profile.series.nonGeometricRatio);
+    const sats = win(profile.series.saturatedFraction);
+    const movingFrac = mean2(win(profile.series.movingFraction));
+    const occFrame = (f) => occupancy[Math.max(0, Math.min(nFrames - 1, f))];
+    const occAt = (f) => mean2(cells.map((c) => occFrame(f)[c]));
+    const occStart = occAt(p0);
+    const occEnd = occAt(p1 + 1);
+    const occStartF = occFrame(p0);
+    const occEndF = occFrame(p1 + 1);
+    const perCellDelta = mean2(cells.map((c) => Math.abs(occEndF[c] - occStartF[c])));
+    const inPlace = perCellDelta < INPLACE_RATIO * Math.max(occStart, occEnd, 1);
+    let kind;
+    if (occEnd > occStart * OCC_RATIO) kind = "enter";
+    else if (occStart > occEnd * OCC_RATIO) kind = "exit";
+    else if (inPlace) {
+      const occPeak = Math.max(...Array.from({ length: p1 - p0 + 1 }, (_, k) => occAt(p0 + k)));
+      const transient = occPeak > Math.max(occStart, occEnd) * 1.1 || Math.max(occStart, occEnd) > 1;
+      kind = transient ? "emphasis" : "scale";
+    } else if (movingFrac > MOVE_FRACTION) kind = "move";
+    else kind = "scale";
+    const e = classifyEasing(speeds, ngrs, sats);
+    const peakSpeed = Math.max(0, ...win(profile.series.blockSpeedP95));
+    const magnitude = kind === "enter" || kind === "exit" || kind === "move" ? Math.min(1, peakSpeed / 200) : Math.min(0.5, Math.abs(occEnd - occStart) / Math.max(1, occStart) + 0.1);
+    return {
+      t0: p0 / fps,
+      t1: (p1 + 1) / fps,
+      kind,
+      region,
+      magnitude,
+      easing: { class: e.class, thirdsRatio: e.thirdsRatio, reliable: e.reliable }
+    };
+  });
+  const maxEventSec = CONTINUOUS_FRAC * duration;
+  const discrete = events.filter((e) => e.t1 - e.t0 <= maxEventSec);
+  discrete.sort((a, b) => a.t0 - b.t0);
+  rhythm.beatCount = discrete.length;
+  return { duration, fps, events: discrete, rhythm };
+}
+
+// ../../benchmark/harness/motion/trace-cli.ts
+async function main2() {
+  const [input, ...rest] = process.argv.slice(2);
+  if (!input) {
+    console.error("usage: reframe trace <ref.mp4|framesDir> [--fps N] [--apply scene.ts] [-o out.json]");
+    process.exit(2);
+  }
+  let fps;
+  let apply;
+  let out;
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === "--fps") fps = Number(rest[++i]);
+    else if (rest[i] === "--apply") apply = rest[++i];
+    else if (rest[i] === "-o") out = rest[++i];
+  }
+  const profile = await analyzeMotion(resolve2(input), { grid: true, ...fps !== void 0 && { fps } });
+  const sketch = extractMotionSketch(profile);
+  let result = sketch;
+  if (apply) {
+    const ir = (await import(pathToFileURL(resolve2(apply)).href)).default;
+    result = sketchToTimeline(sketch, ir.nodes.map((n) => n.id));
+  }
+  const json = JSON.stringify(result, null, 2);
+  if (out) await writeFile2(resolve2(out), json);
+  else console.log(json);
+}
+main2().catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/dist/types/assets.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Asset discovery shared by every consumer that must preload images before
+ * rendering (the capture page and the preview). One walker means the two
+ * sides can never disagree about which srcs a scene uses — including srcs
+ * introduced only mid-scene by a state override or a tween.
+ */
+import type { SceneIR } from "./ir.js";
+/** All image srcs a scene can ever display, deduped, in discovery order. */
+export declare function collectImageSrcs(ir: SceneIR): string[];