reframe-video 0.6.12 → 0.6.13

package/dist/bin.js

@@ -2706,6 +2706,7 @@ var ROOT2 = PACKAGED ? resolve6(HERE2, "..") : resolve6(HERE2, "..", "..", "..")
 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 DIFF = PACKAGED ? join9(ROOT2, "dist", "diff.js") : join9(ROOT2, "packages", "render-cli", "src", "diff.ts");
 var PLAYER = PACKAGED ? join9(ROOT2, "dist", "player.js") : join9(ROOT2, "packages", "render-cli", "src", "player.ts");
 var ANALYZE = PACKAGED ? join9(ROOT2, "dist", "analyze.js") : join9(ROOT2, "benchmark", "harness", "motion", "analyze.ts");
 var TRACE = PACKAGED ? join9(ROOT2, "dist", "trace-cli.js") : join9(ROOT2, "benchmark", "harness", "motion", "trace-cli.ts");
@@ -2725,7 +2726,8 @@ usage:
   ${CMD} labels <scene.ts|.json>  print the event clock (label \u2192 exact seconds; for sound design / timing)
   ${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} diff <ref-image> [<scene.ts>] [--t S] [--mode side|blend|diff|grid]  compare/measure a render against a reference image
+  ${CMD} guide [--regen|--directing]  print a guide (--regen: stable-address contract; --directing: high-end workflow)
   ${CMD} demo                    run the edit-survival demo (3 mp4s into out/)
 `;
 var userPath = (p) => isAbsolute5(p) ? p : resolve6(USER_CWD, p);
@@ -3024,8 +3026,30 @@ ${results.length - failed} rendered (${orphaned} with orphans), ${failed} failed
         await (PACKAGED ? run2(process.execPath, [TRACE, userPath(input), ...args]) : run2("npx", ["tsx", TRACE, userPath(input), ...args]))
       );
     }
+    case "diff": {
+      const input = rest[0];
+      if (!input || input.startsWith("-")) {
+        fail(`usage: ${CMD} diff <ref-image> [<scene.ts>] [--t <sec>] [--mode side|blend|diff|grid] [-o out.png]`);
+      }
+      let seenScene = false;
+      const args = rest.map((a, i) => {
+        if (i === 0) return userPath(a);
+        if (rest[i - 1] === "-o") return userPath(a);
+        if (!a.startsWith("-") && rest[i - 1] !== "--t" && rest[i - 1] !== "--mode" && !seenScene) {
+          seenScene = true;
+          return userPath(a);
+        }
+        return a;
+      });
+      process.exit(
+        await (PACKAGED ? run2(process.execPath, [DIFF, ...args]) : run2("npx", ["tsx", DIFF, ...args]))
+      );
+    }
     case "guide": {
-      const file = rest.includes("--regen") ? PACKAGED ? join9(ROOT2, "guides", "regen-contract.md") : join9(ROOT2, "docs", "regen-contract.md") : PACKAGED ? join9(ROOT2, "guides", "edsl-guide.md") : join9(ROOT2, "benchmark", "guides", "edsl-guide.md");
+      const which = rest.includes("--regen") ? "regen" : rest.includes("--directing") ? "directing" : "edsl";
+      const repoFile = { regen: join9(ROOT2, "docs", "regen-contract.md"), directing: join9(ROOT2, "benchmark", "guides", "directing-guide.md"), edsl: join9(ROOT2, "benchmark", "guides", "edsl-guide.md") };
+      const pkgFile = { regen: join9(ROOT2, "guides", "regen-contract.md"), directing: join9(ROOT2, "guides", "directing-guide.md"), edsl: join9(ROOT2, "guides", "edsl-guide.md") };
+      const file = (PACKAGED ? pkgFile : repoFile)[which];
       const { readFile: readFile7 } = await import("node:fs/promises");
       process.stdout.write(await readFile7(file, "utf8"));
       return;

package/dist/diff.js

@@ -0,0 +1,1188 @@
+#!/usr/bin/env tsx
+
+// ../render-cli/src/diff.ts
+import { readFile as readFile5, writeFile } from "node:fs/promises";
+import { dirname as dirname4, extname as extname3, resolve as resolve4 } from "node:path";
+import { pathToFileURL as pathToFileURL2 } from "node:url";
+import { chromium as chromium2 } from "playwright";
+
+// ../render-cli/src/loadScene.ts
+import { build } from "esbuild";
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ../core/src/ir.ts
+var DEFAULT_TO_DURATION = 0.5;
+var DEFAULT_TWEEN_DURATION = 0.5;
+var 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, curviness = 1) {
+  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;
+  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, 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;
+  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;
+}
+
+// ../core/src/compile.ts
+var key = (target, prop) => `${target}.${prop}`;
+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 = [];
+  const collect = (nodes) => {
+    for (const node of nodes) {
+      nodeById.set(node.id, node);
+      nodeOrder.push(node.id);
+      if (node.type === "group") collect(node.children);
+    }
+  };
+  collect(ir.nodes);
+  const initialValues = /* @__PURE__ */ new Map();
+  for (const [id, node] of nodeById) {
+    for (const [prop, value] of Object.entries(node.props)) {
+      if (typeof value === "number" || typeof value === "string") {
+        initialValues.set(key(id, prop), value);
+      }
+    }
+  }
+  if (ir.initial !== void 0) {
+    const override = ir.states?.[ir.initial] ?? {};
+    for (const [id, props] of Object.entries(override)) {
+      for (const [prop, value] of Object.entries(props)) {
+        initialValues.set(key(id, prop), value);
+      }
+    }
+  }
+  const cameraIsNode = nodeById.has("camera");
+  if (!cameraIsNode) {
+    const cam = ir.camera ?? {};
+    initialValues.set(key("camera", "x"), cam.x ?? ir.size.width / 2);
+    initialValues.set(key("camera", "y"), cam.y ?? ir.size.height / 2);
+    initialValues.set(key("camera", "zoom"), cam.zoom ?? 1);
+    initialValues.set(key("camera", "rotation"), cam.rotation ?? 0);
+    if (cam.perspective !== void 0) initialValues.set(key("camera", "perspective"), cam.perspective);
+  }
+  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);
+    let list = segments.get(k);
+    if (!list) segments.set(k, list = []);
+    list.push(seg);
+    current.set(k, seg.to);
+  };
+  const currentValue = (target, prop) => {
+    const v = current.get(key(target, prop));
+    if (v !== void 0) return v;
+    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();
+  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 });
+    return end;
+  };
+  const walkInner = (tl, start) => {
+    switch (tl.kind) {
+      case "seq": {
+        let t = start;
+        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));
+        return end;
+      }
+      case "stagger": {
+        let end = start;
+        tl.children.forEach((child, i) => {
+          end = Math.max(end, walk(child, start + i * tl.interval));
+        });
+        return end;
+      }
+      case "wait":
+        return start + tl.duration;
+      case "tween": {
+        const duration = tl.duration ?? DEFAULT_TWEEN_DURATION;
+        for (const [prop, toValue] of Object.entries(tl.props)) {
+          pushSegment({
+            target: tl.target,
+            prop,
+            t0: start,
+            t1: start + duration,
+            from: currentValue(tl.target, prop),
+            to: toValue,
+            ...tl.ease !== void 0 && { ease: tl.ease }
+          });
+        }
+        return start + duration;
+      }
+      case "motionPath": {
+        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, curviness, autoRotate, rotateOffset, ...tl.ease !== void 0 && { ease: tl.ease } });
+        if (points.length > 0) {
+          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, curviness) + rotateOffset);
+        }
+        return start + duration;
+      }
+      case "to": {
+        const override = ir.states?.[tl.state] ?? {};
+        const duration = tl.duration ?? DEFAULT_TO_DURATION;
+        const staggerInterval = tl.stagger ?? 0;
+        const targets = nodeOrder.filter(
+          (id) => id in override && (tl.filter === void 0 || tl.filter.includes(id))
+        );
+        targets.forEach((id, i) => {
+          const t0 = start + i * staggerInterval;
+          for (const [prop, toValue] of Object.entries(override[id])) {
+            pushSegment({
+              target: id,
+              prop,
+              t0,
+              t1: t0 + duration,
+              from: currentValue(id, prop),
+              to: toValue,
+              ...tl.ease !== void 0 && { ease: tl.ease }
+            });
+          }
+        });
+        const last = Math.max(0, targets.length - 1);
+        return start + duration + last * staggerInterval;
+      }
+    }
+  };
+  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);
+  const hasCamera = !cameraIsNode && (ir.camera !== void 0 || motionPaths.has("camera") || [...segments.keys()].some((k) => k.startsWith("camera.")));
+  const hasPerspective = !cameraIsNode && (ir.camera?.perspective !== void 0 || segments.has("camera.perspective"));
+  return {
+    ir,
+    duration: ir.duration ?? inferredEnd,
+    segments,
+    motionPaths,
+    initialValues,
+    nodeById,
+    nodeOrder,
+    labelTimes,
+    beatTimes,
+    hasCamera,
+    hasPerspective
+  };
+}
+
+// ../core/src/validate.ts
+var FX_PROPS = ["blur", "shadowColor", "shadowBlur", "shadowX", "shadowY", "blend"];
+var BLEND_MODES = /* @__PURE__ */ new Set([
+  "normal",
+  "multiply",
+  "screen",
+  "overlay",
+  "lighten",
+  "darken",
+  "add",
+  "color-dodge",
+  "soft-light",
+  "hard-light",
+  "difference"
+]);
+var IMAGE_FITS = /* @__PURE__ */ new Set(["fill", "cover"]);
+var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "z", "rotateX", "rotateY", "anchor", "fixed", ...FX_PROPS];
+var CAMERA_PROPS = ["x", "y", "zoom", "rotation", "perspective"];
+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", ...FX_PROPS],
+  text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "prefix", "suffix", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
+  image: [...COMMON_PROPS, "src", "width", "height", "fit"],
+  video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume"],
+  path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
+  group: COMMON_PROPS
+};
+var SceneValidationError = class extends Error {
+  constructor(problems) {
+    super(`Scene validation failed:
+${problems.map((p) => `  - ${p}`).join("\n")}`);
+    this.problems = problems;
+    this.name = "SceneValidationError";
+  }
+  problems;
+};
+function validateScene(ir) {
+  const problems = [];
+  const nodeById = /* @__PURE__ */ new Map();
+  const checkPaint = (where, value) => {
+    if (typeof value !== "object" || value === null) return;
+    const g = value;
+    if (g.kind !== "linear" && g.kind !== "radial" && g.kind !== "conic") {
+      problems.push(`${where}: a paint object must be a gradient with kind "linear" / "radial" / "conic"`);
+      return;
+    }
+    if (!Array.isArray(g.stops) || g.stops.length === 0) {
+      problems.push(`${where}: gradient "${g.kind}" needs at least one color stop`);
+      return;
+    }
+    g.stops.forEach((s, i) => {
+      const st = s;
+      if (typeof st?.color !== "string") problems.push(`${where}: gradient stop ${i} needs a color string`);
+      if (typeof st?.offset !== "number" || st.offset < 0 || st.offset > 1) {
+        problems.push(`${where}: gradient stop ${i} "offset" must be a number in 0..1`);
+      }
+    });
+  };
+  const collect = (nodes) => {
+    for (const node of nodes) {
+      if (nodeById.has(node.id)) {
+        problems.push(`duplicate node id "${node.id}" \u2014 every node id must be unique`);
+      }
+      nodeById.set(node.id, node);
+      const props = node.props;
+      checkPaint(`node "${node.id}" fill`, props.fill);
+      checkPaint(`node "${node.id}" stroke`, props.stroke);
+      if (typeof props.blur === "number" && props.blur < 0) problems.push(`node "${node.id}": blur must be >= 0`);
+      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 === "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`);
+          }
+        }
+        const matte = node.props.matte;
+        if (matte !== void 0) {
+          if (matte !== "alpha" && matte !== "luma") {
+            problems.push(`group "${node.id}" matte: unknown mode "${String(matte)}" \u2014 use "alpha" or "luma"`);
+          } else if (node.children.length < 2) {
+            problems.push(`group "${node.id}" matte: needs \u22652 children (first masks the rest)`);
+          }
+        }
+        collect(node.children);
+      }
+    }
+  };
+  collect(ir.nodes);
+  const checkProps = (where, nodeId, props) => {
+    if (nodeId === "camera" && !nodeById.has("camera")) {
+      for (const key2 of Object.keys(props)) {
+        if (!CAMERA_PROPS.includes(key2)) {
+          problems.push(`${where}: "${key2}" is not a camera prop \u2014 valid props: ${CAMERA_PROPS.join(", ")}`);
+        }
+      }
+      return;
+    }
+    const node = nodeById.get(nodeId);
+    if (!node) {
+      problems.push(
+        `${where} targets unknown node "${nodeId}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
+      );
+      return;
+    }
+    const allowed = PROPS_BY_TYPE[node.type];
+    for (const key2 of Object.keys(props)) {
+      if (!allowed.includes(key2)) {
+        problems.push(
+          `${where}: "${key2}" is not a prop of ${node.type} "${nodeId}" \u2014 valid props: ${allowed.join(", ")}`
+        );
+      }
+    }
+  };
+  const states = ir.states ?? {};
+  for (const [stateName, overrides] of Object.entries(states)) {
+    for (const [nodeId, props] of Object.entries(overrides)) {
+      checkProps(`state "${stateName}"`, nodeId, props);
+    }
+  }
+  if (ir.initial !== void 0 && !(ir.initial in states)) {
+    problems.push(
+      `initial state "${ir.initial}" is not defined \u2014 defined states: ${Object.keys(states).join(", ") || "(none)"}`
+    );
+  }
+  const labels = /* @__PURE__ */ new Set();
+  const checkTimeline = (tl, path2) => {
+    if ("label" in tl && tl.label !== void 0) {
+      if (labels.has(tl.label)) {
+        problems.push(
+          `${path2}: duplicate timeline label "${tl.label}" \u2014 labels are overlay addresses and must be unique`
+        );
+      }
+      labels.add(tl.label);
+    }
+    switch (tl.kind) {
+      case "seq":
+      case "par":
+        tl.children.forEach((c, i) => checkTimeline(c, `${path2}.${tl.kind}[${i}]`));
+        break;
+      case "stagger":
+        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(
+            `${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(`${path2}: to("${tl.state}") duration must be > 0`);
+        }
+        for (const id of tl.filter ?? []) {
+          if (!nodeById.has(id)) problems.push(`${path2}: filter contains unknown node "${id}"`);
+        }
+        break;
+      case "tween":
+        checkProps(path2, tl.target, tl.props);
+        if (tl.duration !== void 0 && tl.duration <= 0) {
+          problems.push(`${path2}: tween duration must be > 0`);
+        }
+        break;
+      case "motionPath": {
+        const node = nodeById.get(tl.target);
+        const isSceneCamera = tl.target === "camera" && !node;
+        if (!isSceneCamera) {
+          if (!node) {
+            problems.push(
+              `${path2}: motionPath targets unknown node "${tl.target}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
+            );
+          } else if (node.type === "line") {
+            problems.push(`${path2}: motionPath cannot target a line (no x/y) \u2014 "${tl.target}"`);
+          }
+        }
+        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(`${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(`${path2}: wait duration must be >= 0`);
+        break;
+      case "beat":
+        if (labels.has(tl.name)) {
+          problems.push(
+            `${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(`${path2}: beat "${tl.name}" duration must be > 0`);
+        }
+        if (tl.scale !== void 0 && tl.scale <= 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, `${path2}.beat(${tl.name})[${i}]`));
+        break;
+    }
+  };
+  if (ir.timeline) checkTimeline(ir.timeline, "timeline");
+  for (const [i, b] of (ir.behaviors ?? []).entries()) {
+    checkProps(`behaviors[${i}]`, b.target, { [b.prop]: 0 });
+  }
+  if (ir.duration !== void 0 && ir.duration <= 0) {
+    problems.push("scene duration must be > 0");
+  }
+  if (ir.camera) {
+    if (nodeById.has("camera")) {
+      problems.push(`camera: a node is already named "camera" \u2014 rename that node or drop the scene camera (the id "camera" can't be both)`);
+    }
+    for (const [key2, value] of Object.entries(ir.camera)) {
+      if (!CAMERA_PROPS.includes(key2)) {
+        problems.push(`camera: "${key2}" is not a camera prop \u2014 valid props: ${CAMERA_PROPS.join(", ")}`);
+      } else if (typeof value !== "number") {
+        problems.push(`camera.${key2} must be a number`);
+      } else if (key2 === "perspective" && value <= 0) {
+        problems.push(`camera.perspective must be > 0 (focal distance in px) \u2014 drop it to disable perspective`);
+      }
+    }
+  }
+  const SFX_NAMES = ["whoosh", "pop", "tick", "rise", "shimmer", "thud"];
+  for (const [i, cue] of (ir.audio?.cues ?? []).entries()) {
+    if (typeof cue.at === "string" && !labels.has(cue.at)) {
+      problems.push(
+        `audio.cues[${i}]: unknown timeline label "${cue.at}" \u2014 known labels: ${[...labels].join(", ") || "(none)"}`
+      );
+    }
+    if (typeof cue.at === "number" && cue.at < 0) {
+      problems.push(`audio.cues[${i}]: "at" must be >= 0`);
+    }
+    if (cue.sfx === void 0 === (cue.file === void 0)) {
+      problems.push(`audio.cues[${i}]: exactly one of "sfx" or "file" is required`);
+    }
+    if (cue.sfx !== void 0 && !SFX_NAMES.includes(cue.sfx)) {
+      problems.push(`audio.cues[${i}]: unknown sfx "${cue.sfx}" \u2014 valid: ${SFX_NAMES.join(", ")}`);
+    }
+    if (cue.gain !== void 0 && cue.gain < 0) {
+      problems.push(`audio.cues[${i}]: gain must be >= 0`);
+    }
+  }
+  const duck = ir.audio?.bgm?.duck;
+  if (typeof duck === "object" && duck !== null && duck.depth !== void 0 && (duck.depth < 0 || duck.depth > 1)) {
+    problems.push("audio.bgm.duck.depth must be in [0, 1]");
+  }
+  if (ir.audio?.bgm?.file !== void 0 && ir.audio.bgm.synth !== void 0) {
+    problems.push('audio.bgm: use either "file" or "synth", not both');
+  }
+  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/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/evaluate.ts
+var DEG = Math.PI / 180;
+
+// ../core/src/assets.ts
+function collectSrcs(ir, type) {
+  const srcs = /* @__PURE__ */ new Set();
+  const ids = /* @__PURE__ */ new Set();
+  const walkNodes = (nodes) => {
+    for (const node of nodes) {
+      if (node.type === type) {
+        ids.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 (ids.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" && ids.has(step.target)) {
+      const src = step.props.src;
+      if (typeof src === "string") srcs.add(src);
+    }
+  };
+  walkTimeline(ir.timeline);
+  return [...srcs];
+}
+function collectImageSrcs(ir) {
+  return collectSrcs(ir, "image");
+}
+function collectVideoSrcs(ir) {
+  return collectSrcs(ir, "video");
+}
+
+// ../render-cli/src/loadScene.ts
+var HERE = dirname(fileURLToPath(import.meta.url));
+var CORE_ENTRY = true ? resolve(HERE, "index.js") : resolve(HERE, "..", "..", "core", "src", "index.ts");
+async function loadDefault(path2) {
+  if (path2.endsWith(".json")) return JSON.parse(await readFile(path2, "utf8"));
+  let code;
+  try {
+    const out = await build({
+      entryPoints: [path2],
+      bundle: true,
+      format: "esm",
+      platform: "neutral",
+      write: false,
+      logLevel: "silent",
+      sourcemap: "inline",
+      // both specifiers accepted: the guide's canonical "@reframe/core" and
+      // the published package name
+      alias: { "@reframe/core": CORE_ENTRY, "reframe-video": CORE_ENTRY }
+    });
+    code = out.outputFiles[0].text;
+  } catch (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 === 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/frameLoop.ts
+import { join as join3, dirname as dirname3 } from "node:path";
+import { fileURLToPath as fileURLToPath3, pathToFileURL } from "node:url";
+import { build as build2 } from "esbuild";
+import { chromium } from "playwright";
+
+// ../render-cli/src/fonts.ts
+import { readFile as readFile2 } from "node:fs/promises";
+import { dirname as dirname2, join } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+var FONTS_DIR = true ? join(dirname2(fileURLToPath2(import.meta.url)), "..", "assets", "fonts") : join(dirname2(fileURLToPath2(import.meta.url)), "..", "..", "..", "assets", "fonts");
+var WEIGHTS = [400, 700, 800];
+var cssCache = null;
+async function fontFaceCss() {
+  if (cssCache) return cssCache;
+  const rules = await Promise.all(
+    WEIGHTS.map(async (weight) => {
+      const data = await readFile2(join(FONTS_DIR, `inter-${weight}.woff2`));
+      return `@font-face {
+  font-family: "Inter";
+  font-style: normal;
+  font-weight: ${weight};
+  src: url(data:font/woff2;base64,${data.toString("base64")}) format("woff2");
+}`;
+    })
+  );
+  cssCache = rules.join("\n");
+  return cssCache;
+}
+
+// ../render-cli/src/images.ts
+import { readFile as readFile3 } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { extname, isAbsolute, resolve as resolve2 } from "node:path";
+var MIME = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp"
+};
+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 = [isAbsolute(src) ? src : null, resolve2(sceneDir, src)].filter(
+      (c) => c !== null
+    );
+    const found = candidates.find((c) => existsSync(c));
+    if (!found) {
+      throw new Error(`image "${src}" not found (tried: ${candidates.join(", ")})`);
+    }
+    const data = await readFile3(found);
+    assets[src] = `data:${mime};base64,${data.toString("base64")}`;
+  }
+  return assets;
+}
+
+// ../render-cli/src/videos.ts
+import { spawn } from "node:child_process";
+import { mkdtemp, readFile as readFile4, readdir, rm } from "node:fs/promises";
+import { existsSync as existsSync2 } from "node:fs";
+import { tmpdir } from "node:os";
+import { extname as extname2, isAbsolute as isAbsolute2, join as join2, resolve as resolve3 } from "node:path";
+var VIDEO_EXT = /* @__PURE__ */ new Set([".mp4", ".mov", ".webm", ".m4v", ".mkv"]);
+function runFfmpeg(args) {
+  return new Promise((resolve5, reject) => {
+    const proc = spawn("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);
+  });
+}
+function neededSeconds(node, duration) {
+  const start = 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;
+}
+function videoNodes(ir) {
+  const out = [];
+  const walk = (nodes) => {
+    for (const n of nodes) {
+      if (n.type === "video") out.push(n);
+      if (n.type === "group") walk(n.children);
+    }
+  };
+  walk(ir.nodes);
+  return out;
+}
+async function buildVideoFrameAssets(ir, sceneDir, fps, duration) {
+  const srcs = collectVideoSrcs(ir);
+  if (srcs.length === 0) return {};
+  const nodes = videoNodes(ir);
+  const reachBySrc = /* @__PURE__ */ new Map();
+  for (const n of nodes) {
+    const reach = neededSeconds(n, duration);
+    reachBySrc.set(n.props.src, Math.max(reachBySrc.get(n.props.src) ?? 0, reach));
+  }
+  const assets = {};
+  for (const src of srcs) {
+    if (!VIDEO_EXT.has(extname2(src).toLowerCase())) {
+      throw new Error(
+        `video "${src}": unsupported format "${extname2(src)}" \u2014 supported: ${[...VIDEO_EXT].join(" ")}`
+      );
+    }
+    const candidates = [isAbsolute2(src) ? src : null, resolve3(sceneDir, src)].filter(
+      (c) => c !== null
+    );
+    const found = candidates.find((c) => existsSync2(c));
+    if (!found) throw new Error(`video "${src}" not found (tried: ${candidates.join(", ")})`);
+    const dir = await mkdtemp(join2(tmpdir(), "reframe-vframes-"));
+    try {
+      const seconds = Math.max(1 / fps, reachBySrc.get(src) ?? duration);
+      await runFfmpeg([
+        "-y",
+        "-i",
+        found,
+        "-t",
+        seconds.toFixed(3),
+        "-vf",
+        `fps=${fps},scale='min(iw,1280)':-2`,
+        "-q:v",
+        "4",
+        join2(dir, "%05d.jpg")
+      ]);
+      const files = (await readdir(dir)).filter((f) => f.endsWith(".jpg")).sort();
+      assets[src] = await Promise.all(
+        files.map(async (f) => `data:image/jpeg;base64,${(await readFile4(join2(dir, f))).toString("base64")}`)
+      );
+      if (assets[src].length === 0) throw new Error(`video "${src}": ffmpeg extracted no frames`);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  }
+  return assets;
+}
+function resolveTiming(ir, opts) {
+  const fps = opts.fps ?? ir.fps ?? 30;
+  const duration = opts.duration ?? compileScene(ir).duration;
+  return { fps, duration };
+}
+
+// ../render-cli/src/vclock.ts
+var VCLOCK_SOURCE = String.raw`
+(() => {
+  let now = 0;
+  let nextId = 1;
+  let rafQueue = [];
+  const timers = [];
+
+  Date.now = () => now;
+  performance.now = () => now;
+
+  window.requestAnimationFrame = (cb) => {
+    const id = nextId++;
+    rafQueue.push({ id, cb });
+    return id;
+  };
+  window.cancelAnimationFrame = (id) => {
+    rafQueue = rafQueue.filter((r) => r.id !== id);
+  };
+
+  const addTimer = (cb, delay, args, interval) => {
+    const id = nextId++;
+    timers.push({
+      id,
+      cb: () => cb(...args),
+      due: now + Math.max(Number(delay) || 0, 0),
+      interval: interval ? Math.max(Number(delay) || 0, 1) : undefined,
+    });
+    return id;
+  };
+  const removeTimer = (id) => {
+    const i = timers.findIndex((t) => t.id === id);
+    if (i >= 0) timers.splice(i, 1);
+  };
+  window.setTimeout = (cb, delay = 0, ...args) =>
+    typeof cb === "function" ? addTimer(cb, delay, args, false) : 0;
+  window.setInterval = (cb, delay = 0, ...args) =>
+    typeof cb === "function" ? addTimer(cb, delay, args, true) : 0;
+  window.clearTimeout = removeTimer;
+  window.clearInterval = removeTimer;
+
+  window.__vclock = {
+    now: () => now,
+    advanceTo(targetMs) {
+      // Fire due timers in order, letting fired callbacks schedule new ones.
+      for (;;) {
+        timers.sort((a, b) => a.due - b.due);
+        const next = timers[0];
+        if (!next || next.due > targetMs) break;
+        now = next.due;
+        if (next.interval !== undefined) next.due += next.interval;
+        else timers.shift();
+        next.cb();
+      }
+      now = targetMs;
+      // One rAF batch per frame; callbacks registered during the batch run
+      // on the next advanceTo (matching real browser semantics).
+      const batch = rafQueue;
+      rafQueue = [];
+      for (const { cb } of batch) cb(now);
+    },
+  };
+})();
+`;
+
+// ../render-cli/src/frameLoop.ts
+async function injectFonts(page) {
+  await page.addStyleTag({ content: await fontFaceCss() });
+  await page.evaluate(async () => {
+    await Promise.all([...document.fonts].map((f) => f.load()));
+    await document.fonts.ready;
+  });
+}
+async function withPage(size, fn) {
+  const browser = await chromium.launch({
+    args: ["--force-color-profile=srgb", "--font-render-hinting=none"]
+  });
+  try {
+    const page = await browser.newPage({ viewport: size, deviceScaleFactor: 1 });
+    return await fn(page);
+  } finally {
+    await browser.close();
+  }
+}
+var bundleCache = null;
+async function browserBundle() {
+  if (bundleCache) return bundleCache;
+  if (true) {
+    const { readFile: readFile6 } = await import("node:fs/promises");
+    bundleCache = await readFile6(
+      join3(dirname3(fileURLToPath3(import.meta.url)), "browserEntry.js"),
+      "utf8"
+    );
+    return bundleCache;
+  }
+  const entry = join3(dirname3(fileURLToPath3(import.meta.url)), "browserEntry.ts");
+  const result = await build2({
+    entryPoints: [entry],
+    bundle: true,
+    write: false,
+    format: "iife",
+    target: "es2022"
+  });
+  bundleCache = result.outputFiles[0].text;
+  return bundleCache;
+}
+async function renderFrameAt(ir, t, opts = {}) {
+  const sceneDir = opts.sceneDir ?? process.cwd();
+  const assets = await buildImageAssets(ir, sceneDir);
+  const { fps, duration } = resolveTiming(ir, {});
+  const videoAssets = await buildVideoFrameAssets(ir, sceneDir, fps, duration);
+  const bundle = await browserBundle();
+  return withPage(ir.size, async (page) => {
+    await page.setContent(`<!DOCTYPE html><html><body style="margin:0;background:#000"></body></html>`);
+    await injectFonts(page);
+    await page.addScriptTag({ content: bundle });
+    await page.evaluate(
+      ([sceneIr, imageAssets, vAssets]) => window.__reframe.init(sceneIr, imageAssets, vAssets),
+      [ir, assets, videoAssets]
+    );
+    const dataUrl2 = await page.evaluate((tt) => window.__reframe.renderFrame(tt), t);
+    return Buffer.from(dataUrl2.slice(22), "base64");
+  });
+}
+
+// ../render-cli/src/diff.ts
+var MODES = ["side", "blend", "diff", "grid"];
+var dataUrl = (buf, ext) => `data:image/${ext === ".jpg" || ext === ".jpeg" ? "jpeg" : ext === ".webp" ? "webp" : "png"};base64,${buf.toString("base64")}`;
+async function composite(refUrl, renderUrl, mode, outPath) {
+  const browser = await chromium2.launch({ args: ["--force-color-profile=srgb"] });
+  try {
+    const page = await browser.newPage({ deviceScaleFactor: 1 });
+    await page.evaluate("globalThis.__name = globalThis.__name || ((f) => f)");
+    const png = await page.evaluate(
+      async ([ref, render, m]) => {
+        const load = (src) => new Promise((res, rej) => {
+          const im = new Image();
+          im.onload = () => res(im);
+          im.onerror = rej;
+          im.src = src;
+        });
+        const refImg = await load(ref);
+        const canvas = document.createElement("canvas");
+        const ctx = canvas.getContext("2d");
+        const tag = (s, x, y) => {
+          ctx.save();
+          ctx.font = "600 18px sans-serif";
+          const w = ctx.measureText(s).width + 16;
+          ctx.fillStyle = "rgba(0,0,0,0.6)";
+          ctx.fillRect(x, y, w, 28);
+          ctx.fillStyle = "#fff";
+          ctx.fillText(s, x + 8, y + 20);
+          ctx.restore();
+        };
+        if (m === "grid") {
+          canvas.width = refImg.width;
+          canvas.height = refImg.height;
+          ctx.drawImage(refImg, 0, 0);
+          ctx.save();
+          ctx.font = "14px sans-serif";
+          ctx.lineWidth = 1;
+          for (let x = 0; x <= canvas.width; x += 100) {
+            ctx.strokeStyle = x % 500 === 0 ? "rgba(255,90,90,0.85)" : "rgba(255,90,90,0.4)";
+            ctx.beginPath();
+            ctx.moveTo(x, 0);
+            ctx.lineTo(x, canvas.height);
+            ctx.stroke();
+            ctx.fillStyle = "rgba(255,150,150,0.95)";
+            ctx.fillText(String(x), x + 3, 15);
+          }
+          for (let y = 0; y <= canvas.height; y += 100) {
+            ctx.strokeStyle = y % 500 === 0 ? "rgba(255,90,90,0.85)" : "rgba(255,90,90,0.4)";
+            ctx.beginPath();
+            ctx.moveTo(0, y);
+            ctx.lineTo(canvas.width, y);
+            ctx.stroke();
+            ctx.fillStyle = "rgba(255,150,150,0.95)";
+            ctx.fillText(String(y), 3, y + 15);
+          }
+          ctx.restore();
+        } else {
+          const rImg = render ? await load(render) : null;
+          if (m === "side") {
+            const H = Math.min(refImg.height, rImg ? rImg.height : refImg.height, 1e3);
+            const rw = refImg.width * (H / refImg.height);
+            const rrw = rImg ? rImg.width * (H / rImg.height) : 0;
+            const gap = rImg ? 24 : 0;
+            canvas.width = Math.round(rw + (rImg ? gap + rrw : 0));
+            canvas.height = Math.round(H);
+            ctx.fillStyle = "#0a0a0a";
+            ctx.fillRect(0, 0, canvas.width, canvas.height);
+            ctx.drawImage(refImg, 0, 0, rw, H);
+            if (rImg) ctx.drawImage(rImg, rw + gap, 0, rrw, H);
+            tag("reference", 10, 10);
+            if (rImg) tag("render", Math.round(rw + gap) + 10, 10);
+          } else {
+            canvas.width = refImg.width;
+            canvas.height = refImg.height;
+            ctx.drawImage(refImg, 0, 0);
+            if (rImg) {
+              ctx.globalAlpha = m === "blend" ? 0.5 : 1;
+              ctx.globalCompositeOperation = m === "diff" ? "difference" : "source-over";
+              ctx.drawImage(rImg, 0, 0, canvas.width, canvas.height);
+              ctx.globalAlpha = 1;
+              ctx.globalCompositeOperation = "source-over";
+            }
+            tag(m, 10, 10);
+          }
+        }
+        return canvas.toDataURL("image/png");
+      },
+      [refUrl, renderUrl, mode]
+    );
+    await writeFile(outPath, Buffer.from(png.slice(22), "base64"));
+  } finally {
+    await browser.close();
+  }
+}
+async function main() {
+  const argv = process.argv.slice(2);
+  const ref = argv[0];
+  if (!ref || ref.startsWith("-")) {
+    console.error("usage: reframe diff <ref-image> [<scene.ts>] [--t <sec>] [--mode side|blend|diff|grid] [-o out.png]");
+    process.exit(2);
+  }
+  let scene;
+  let t = 0;
+  let mode = "side";
+  let out = "";
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--t") t = Number(argv[++i]);
+    else if (a === "--mode") mode = argv[++i];
+    else if (a === "-o") out = argv[++i];
+    else if (!a.startsWith("-") && !scene) scene = a;
+    else {
+      console.error(`unknown argument: ${a}`);
+      process.exit(2);
+    }
+  }
+  if (!MODES.includes(mode)) {
+    console.error(`unknown --mode "${mode}" \u2014 use ${MODES.join(", ")}`);
+    process.exit(2);
+  }
+  const refPath = resolve4(ref);
+  const refUrl = dataUrl(await readFile5(refPath), extname3(refPath).toLowerCase());
+  let renderUrl = null;
+  if (mode !== "grid") {
+    if (!scene) {
+      console.error(`--mode ${mode} needs a scene file (only --mode grid works on the reference alone)`);
+      process.exit(2);
+    }
+    const scenePath = resolve4(scene);
+    const loaded = await loadModule(scenePath);
+    if (loaded.kind !== "scene") {
+      console.error("diff needs a single scene (not a composition)");
+      process.exit(2);
+    }
+    const buf = await renderFrameAt(loaded.ir, t, { sceneDir: dirname4(scenePath) });
+    renderUrl = dataUrl(buf, ".png");
+  }
+  const outPath = out ? resolve4(out) : resolve4(`diff-${mode}.png`);
+  await composite(refUrl, renderUrl, mode, outPath);
+  console.log(outPath);
+}
+if (process.argv[1] && import.meta.url === pathToFileURL2(process.argv[1]).href) {
+  main().catch((e) => {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  });
+}
+export {
+  composite,
+  dataUrl
+};

package/guides/directing-guide.md

@@ -0,0 +1,96 @@
+# reframe directing guide — high-end, reference-heavy pieces
+
+Read this (after the syntax guide, `reframe guide`) when the ask is a CINEMATIC or
+REFERENCE-FAITHFUL piece — a product teaser, a UI/session reproduction, a title
+sequence, a data story — not a simple lower-third or KPI card (those you just write).
+Simple jobs render first-try; the ceiling needs a process. This is that process.
+
+## What to get from the user (before writing anything)
+
+Ask for / confirm these — vague prompts are why these pieces take many rounds:
+
+- **Concept** in one line ("a faithful Claude Code session that builds a logo", "an app
+  that goes viral, everywhere").
+- **References** — screenshots / a reference video / pasted real content (terminal output,
+  copy, data). For fidelity work, the reference IS the spec. Save them to disk so you can
+  `diff` against them.
+- **Brand** — exact colors (hex), the wordmark, the font feel.
+- **Format** — length (~10–20s is a good ceiling clip), aspect (16:9 / 9:16), with or
+  without sound.
+- **Tone** — "Apple teaser" (slow, premium, lots of negative space) vs "faithful UI sim"
+  (exact, dense) vs "kinetic/energetic". This sets pacing and camera.
+
+## The loop
+
+### 1. Storyboard the beats FIRST (structure, not a flat timeline)
+
+Name the acts with `beat("...", {}, [ ... ])` before animating. A beat is a labeled,
+retimable narrative unit; its label anchors audio and lets you restructure whole sections.
+A reliable arc: **setup → inciting beat → rising → climax → resolution.** Decide what each
+beat shows and how long, THEN fill in motion. (See `device-hero.ts`: `beat("ki"/"seung"/
+"jeon"/"gyeol", …)` — entrance → it-takes-off → everywhere → resolve.)
+
+### 2. Match references with `diff` (stop eyeballing)
+
+Reproducing a screenshot pixel-faithfully is the hardest part. Use the tool:
+
+```
+reframe diff ref.png --mode grid            # labelled 100px grid over the screenshot → read coords, place nodes
+reframe diff ref.png scene.ts --mode side   # reference | your render, side by side
+reframe diff ref.png scene.ts --mode diff   # absolute difference — bright where you're off
+reframe diff ref.png scene.ts --mode blend  # 50% overlay — spot drift
+```
+
+Loop: `--mode grid` to measure → write the node tree → `--mode side`/`diff` to compare →
+fix coordinates/sizes/colors → repeat until faithful. Pick the frame with `--t <sec>`.
+
+### 3. Apply the cinematic-craft checklist
+
+These are what make a piece read as premium, not a slideshow. Patterns proven in the
+flagship scenes — reuse the technique, vary the content:
+
+- **Camera moves with the story.** Push in on each beat: a `cameraTo(...)` running in `par`
+  with the beat's content. Frame the detail that matters, pull back to resolve. (See
+  `terminal-claude.ts` helpers `cam()`/`scroll()`/`show()` — focus + scroll + reveal as
+  parameterized eased moves.)
+- **Curved entrances, not straight slides.** A hero enters on a `motionPath` arc with
+  `easeOutBack` (overshoot, then settle). (`device-hero.ts` `motionPath("phone-cam", [[…]],
+  { ease: "easeOutBack" })`.)
+- **Fake depth.** Layer a backdrop of many faint concentric ellipses (a smooth glow, no hard
+  edge) + a spotlight + a cast shadow that tracks the hero + an impact ring on landing.
+  (`device-hero.ts` backdrop/spot/shadow/ring rig.) Or use real depth: `camera.perspective`
+  + per-node `z` (see the syntax guide's "Depth & perspective").
+- **Layered idle motion.** Nothing should sit perfectly still. `oscillate` a few nodes at
+  DIFFERENT frequencies (slow float, slower tilt, a fast accent) for life during holds.
+- **Sound on the beats.** `scene.audio` cues anchor to your beat/timeline labels, so they
+  survive retiming: `{ at: "land", file: "bong_001.ogg" }`, `{ at: "viral", offset: 0.4,
+  sfx: "pop" }`. An `ambient-pad` bgm with `duck` under the hits. Quote `reframe labels` to
+  see exact seconds.
+
+### 4. Verify objectively (don't argue about "more dynamic")
+
+- `reframe labels scene.ts` — every label → exact seconds. The timing source for audio + a
+  sanity check that beats land when you think.
+- `reframe motion out.mp4` — speeds, static fraction, oscillation rhythm, spikes. A vague
+  note like "make it punchier" becomes measurable: compare `meanSpeed`/`peakSpeed` before
+  and after; `staticFraction` too high = it drags.
+- `reframe trace ref.mp4 --apply scene.ts` — when you have a reference VIDEO (not image),
+  extract its timing/easing and re-apply it onto YOUR node ids. Borrow the motion, keep your
+  assets.
+
+### 5. Hand-tune via preview → overlay
+
+`reframe preview` to scrub, drag motionPath waypoints, and retime steps; export the overlay
+JSON and render with `--overlay`. Those nudges survive a later regeneration (stable
+addresses), so the human's polish isn't lost when you redo the base.
+
+## Pitfalls
+
+- Don't animate before the structure is right — fixing pacing after everything is keyframed
+  is painful. Beats first.
+- Reference fidelity is coordinates + color + type, mostly STATIC layout; get the held frame
+  matching with `diff` before adding motion.
+- Keep `id`s/labels stable across rewrites (see `reframe guide --regen`) so the user's
+  overlay edits survive.
+- It's still iterative. The tools cut the rounds; they don't remove the loop. Render, look,
+  adjust — the agent should render frames and read them, not guess.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reframe-video",
-  "version": "0.6.12",
+  "version": "0.6.13",
   "description": "Declarative motion graphics that AI can write and humans can tweak — human edits survive AI regeneration. Deterministic mp4 renders from a plain-data scene format.",
   "keywords": [
     "motion-graphics",