reframe-video 0.6.18 → 0.6.20

package/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "reframe",
+  "owner": {
+    "name": "Kiyeon Jeon",
+    "url": "https://github.com/kiyeonjeon21"
+  },
+  "plugins": [
+    {
+      "name": "reframe",
+      "source": "./",
+      "description": "Motion-graphics videos as addressable data — generate, tweak, regenerate without losing human edits."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "reframe",
+  "version": "0.1.0",
+  "description": "Create and iterate motion-graphics videos as addressable data: deterministic mp4 renders, human edits that survive AI regeneration, label-anchored audio, data-driven batch rendering.",
+  "author": {
+    "name": "Kiyeon Jeon",
+    "url": "https://github.com/kiyeonjeon21"
+  }
+}

package/README.md

@@ -22,6 +22,7 @@ npx reframe-video render hello.ts    # → out/hello.mp4
 |---|---|
 | `reframe render <scene.ts> [--overlay edits.json] [-o out.mp4]` | deterministic mp4 |
 | `reframe batch <scene.ts> <data.json\|csv>` | one mp4 per data row (row keys are overlay addresses) |
+| `reframe compile <scene.ts> [-o out.json] [--json]` | bundle + validate a scene to SceneIR JSON, no render (fast; no ffmpeg/chromium) |
 | `reframe preview` | scrub/play/edit UI for scenes in the current directory; edits export as overlay JSON |
 | `reframe new <name>` | scaffold a documented starter scene |
 | `reframe motion <mp4>` | calibrated motion profile of a rendered clip |
@@ -63,6 +64,50 @@ Audio is label-anchored (`audio: { cues: [{ at: "enter", sfx: "whoosh" }] }`)
 so sound design follows retiming and regeneration. Full syntax:
 `npx reframe-video guide`.
 
+## Rendering to a canvas (live preview)
+
+The same renderer that produces the mp4 is exported as a subpath for drawing
+frames to a 2D canvas in the browser — so an editor or preview can render a
+scene live and match the export. Compile once, draw any time `t`:
+
+```ts
+import { compileScene, evaluate } from "reframe-video";
+import { renderFrame, drawDisplayList } from "reframe-video/renderer";
+
+const compiled = compileScene(myScene);          // myScene: SceneIR
+const ctx = canvas.getContext("2d")!;
+
+renderFrame(ctx, compiled, t);                    // clears + paints the frame at time t
+// or drive the DisplayList yourself (you own the clear/background):
+drawDisplayList(ctx, evaluate(compiled, t));
+```
+
+Camera, clips, track mattes, group effects, gradients and text are handled
+exactly like the mp4 path — `renderFrame` bakes the scene camera in, so don't
+apply one yourself. Images and video need registries: pass `images`
+(`{ get(src) }`) and `videos` (`{ frame(src, i) }`) returning decoded
+`CanvasImageSource`s. The default entry (scene authoring + `compileScene` /
+`evaluate`) is unchanged.
+
+## Compiling source to IR in-process (server)
+
+For a backend that has an LLM author eDSL source and needs the **SceneIR** back
+(to preview, diff, or self-correct) without rendering, the loader is exported as
+a Node-only subpath:
+
+```ts
+import { loadSceneFromCode, loadScene, SceneLoadError } from "reframe-video/compile";
+
+const ir = await loadSceneFromCode(generatedSource);   // bundle + validate, no ffmpeg/chromium
+// errors are classified + sanitized (no base64 bundle dump):
+try { await loadSceneFromCode(badSource); }
+catch (e) { if (e instanceof SceneLoadError) console.log(e.kind, e.message); } // "eval" | "bundle" | "validation"
+```
+
+This runs the scene module in-process — bound untrusted/model-authored source
+(a timeout) and run it where it can't do harm. The same thing on the CLI is
+`reframe compile … --json`.
+
 ## Why this instead of generating Remotion/HTML?
 
 One-shot generation quality is a wash (we measured it). The difference is the

package/dist/bin.js

@@ -2480,13 +2480,13 @@ async function captureIr(ir, opts) {
   const assets = await buildImageAssets(ir, sceneDir);
   const { fps, duration } = resolveTiming(ir, opts);
   const videoAssets = await buildVideoFrameAssets(ir, sceneDir, fps, duration);
-  const bundle = await browserBundle();
+  const bundle2 = 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.addScriptTag({ content: bundle2 });
     await page.evaluate(
       ([sceneIr, imageAssets, vAssets]) => window.__reframe.init(sceneIr, imageAssets, vAssets),
       [ir, assets, videoAssets]
@@ -2679,66 +2679,108 @@ var init_batch = __esm({
 // ../render-cli/src/loadScene.ts
 var loadScene_exports = {};
 __export(loadScene_exports, {
+  SceneLoadError: () => SceneLoadError,
   isComposition: () => isComposition,
   loadModule: () => loadModule,
-  loadScene: () => loadScene
+  loadScene: () => loadScene,
+  loadSceneFromCode: () => loadSceneFromCode
 });
 import { build as build2 } from "esbuild";
 import { readFile as readFile6 } from "node:fs/promises";
 import { dirname as dirname6, resolve as resolve5 } from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
-async function loadDefault(path2) {
-  if (path2.endsWith(".json")) return JSON.parse(await readFile6(path2, "utf8"));
-  let code;
+async function bundle(input) {
+  const common = {
+    bundle: true,
+    format: "esm",
+    platform: "neutral",
+    write: false,
+    logLevel: "silent",
+    sourcemap: "inline",
+    alias: ALIAS
+  };
   try {
-    const out = await build2({
-      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;
+    const out = await build2(
+      "path" in input ? { ...common, entryPoints: [input.path] } : { ...common, stdin: { contents: input.code, resolveDir: input.resolveDir, loader: "ts", sourcefile: "scene.ts" } }
+    );
+    return out.outputFiles[0].text;
   } catch (err) {
-    throw new Error(`failed to bundle ${path2}:
-${err instanceof Error ? err.message : String(err)}`);
+    throw new SceneLoadError("bundle", clean(err), { cause: 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`);
+}
+async function importDefault(code, label) {
+  let mod;
+  try {
+    mod = await import(`data:text/javascript;base64,${Buffer.from(code).toString("base64")}`);
+  } catch (err) {
+    const kind = err instanceof Error && err.name === "SceneValidationError" ? "validation" : "eval";
+    throw new SceneLoadError(kind, clean(err), { cause: err });
+  }
+  if (mod.default === void 0) throw new SceneLoadError("eval", `${label} must default-export a scene or composition`);
   return mod.default;
 }
+async function loadDefault(path2) {
+  if (path2.endsWith(".json")) {
+    try {
+      return JSON.parse(await readFile6(path2, "utf8"));
+    } catch (err) {
+      throw new SceneLoadError("eval", `failed to read ${path2}: ${clean(err)}`, { cause: err });
+    }
+  }
+  return importDefault(await bundle({ path: path2 }), path2);
+}
 function isComposition(def) {
   return typeof def === "object" && def !== null && Array.isArray(def.scenes);
 }
-async function loadScene(path2) {
-  const def = await loadDefault(path2);
+function asScene(def, label) {
   if (isComposition(def)) {
-    throw new Error(`${path2} is a composition \u2014 render it directly, not as a single scene`);
+    throw new SceneLoadError("validation", `${label} is a composition \u2014 render it directly, not as a single scene`);
+  }
+  try {
+    validateScene(def);
+  } catch (err) {
+    throw new SceneLoadError("validation", clean(err), { cause: err });
   }
-  validateScene(def);
   return def;
 }
+async function loadScene(path2) {
+  return asScene(await loadDefault(path2), path2);
+}
+async function loadSceneFromCode(code, resolveDir = process.cwd()) {
+  return asScene(await importDefault(await bundle({ code, resolveDir }), "<source>"), "<source>");
+}
 async function loadModule(path2) {
   const def = await loadDefault(path2);
   if (isComposition(def)) {
-    validateComposition(def);
+    try {
+      validateComposition(def);
+    } catch (err) {
+      throw new SceneLoadError("validation", clean(err), { cause: err });
+    }
     return { kind: "composition", ir: def };
   }
-  validateScene(def);
-  return { kind: "scene", ir: def };
+  return { kind: "scene", ir: asScene(def, path2) };
 }
-var HERE, CORE_ENTRY;
+var HERE, CORE_ENTRY, SceneLoadError, clean, ALIAS;
 var init_loadScene = __esm({
   "../render-cli/src/loadScene.ts"() {
     "use strict";
     init_src();
     HERE = dirname6(fileURLToPath4(import.meta.url));
     CORE_ENTRY = true ? resolve5(HERE, "index.js") : resolve5(HERE, "..", "..", "core", "src", "index.ts");
+    SceneLoadError = class extends Error {
+      kind;
+      constructor(kind, message, options) {
+        super(message, options);
+        this.name = "SceneLoadError";
+        this.kind = kind;
+      }
+    };
+    clean = (err) => (err instanceof Error ? err.message : String(err)).replace(
+      /data:text\/javascript;base64,[A-Za-z0-9+/=]+/g,
+      "<scene bundle>"
+    );
+    ALIAS = { "@reframe/core": CORE_ENTRY, "reframe-video": CORE_ENTRY };
   }
 });
 
@@ -2755,7 +2797,9 @@ 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 COMPILE = PACKAGED ? join9(ROOT2, "dist", "compile.js") : join9(ROOT2, "packages", "render-cli", "src", "compile.ts");
 var DIFF = PACKAGED ? join9(ROOT2, "dist", "diff.js") : join9(ROOT2, "packages", "render-cli", "src", "diff.ts");
+var FRAME = PACKAGED ? join9(ROOT2, "dist", "frame.js") : join9(ROOT2, "packages", "render-cli", "src", "frame.ts");
 var PLAYER = PACKAGED ? join9(ROOT2, "dist", "player.js") : join9(ROOT2, "packages", "render-cli", "src", "player.ts");
 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");
@@ -2773,6 +2817,10 @@ 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} labels <scene.ts|.json>  print the event clock (label \u2192 exact seconds; for sound design / timing)
+  ${CMD} compile <scene.ts|.json> [-o out.json] [--stdin] [--code "<src>"] [--json]
+                                 bundle + validate a scene to SceneIR JSON, no render (fast; no ffmpeg/chromium)
+  ${CMD} frame <scene.ts|.json> [--t <sec>] [-o out.png]  render ONE frame at time t to a PNG (no mp4; for a render-and-look loop)
+  ${CMD} skill [--path]          print the authoring skill (SKILL.md) for an agent; --path prints the plugin dir to load
   ${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} diff <ref-image> [<scene.ts>] [--t S] [--mode side|blend|diff|grid]  compare/measure a render against a reference image
@@ -2921,6 +2969,42 @@ ${USAGE}`);
         await (PACKAGED ? run2(process.execPath, [LABELS, inputPath]) : run2("npx", ["tsx", LABELS, inputPath]))
       );
     }
+    case "compile": {
+      const hasInlineSource = rest.includes("--stdin") || rest.includes("--code");
+      const fileArg = rest.find((a, i) => !a.startsWith("-") && !["-o", "--code", "--timeout"].includes(rest[i - 1] ?? ""));
+      if (!fileArg && !hasInlineSource) fail(`compile needs a scene file, --stdin, or --code "<src>"
+
+${USAGE}`);
+      const passed = rest.map((a, i) => {
+        if (a === fileArg) return userPath(a);
+        if (rest[i - 1] === "-o") return userPath(a);
+        return a;
+      });
+      if (fileArg && !existsSync6(userPath(fileArg))) fail(`no such file: ${userPath(fileArg)}`);
+      process.exit(
+        await (PACKAGED ? run2(process.execPath, [COMPILE, ...passed]) : run2("npx", ["tsx", COMPILE, ...passed]))
+      );
+    }
+    case "frame": {
+      const input = rest[0];
+      if (!input || input.startsWith("-")) fail(`frame needs a scene file
+
+${USAGE}`);
+      const inputPath = userPath(input);
+      if (!existsSync6(inputPath)) fail(`no such file: ${inputPath}`);
+      const args = rest.slice(1);
+      const outBase = PACKAGED ? join9(USER_CWD, "out") : join9(ROOT2, "out");
+      const stem = `${basename(input).replace(/\.[^.]+$/, "")}.png`;
+      let outArgs = args;
+      if (args.indexOf("-o") === -1) {
+        await mkdir4(outBase, { recursive: true });
+        outArgs = [...args, "-o", join9(outBase, stem)];
+      }
+      outArgs = outArgs.map((a, i) => outArgs[i - 1] === "-o" ? userPath(a) : a);
+      process.exit(
+        await (PACKAGED ? run2(process.execPath, [FRAME, inputPath, ...outArgs]) : run2("npx", ["tsx", FRAME, inputPath, ...outArgs]))
+      );
+    }
     case "player": {
       const input = rest[0];
       if (!input || input.startsWith("-")) fail(`player needs a scene file
@@ -3109,6 +3193,16 @@ ${results.length - failed} rendered (${orphaned} with orphans), ${failed} failed
       process.stdout.write(await readFile7(file, "utf8"));
       return;
     }
+    case "skill": {
+      if (rest.includes("--path")) {
+        process.stdout.write(`${ROOT2}
+`);
+        return;
+      }
+      const { readFile: readFile7 } = await import("node:fs/promises");
+      process.stdout.write(await readFile7(join9(ROOT2, "skills", "reframe", "SKILL.md"), "utf8"));
+      return;
+    }
     case "demo":
       if (PACKAGED) {
         fail(

package/dist/cli.js

@@ -1906,13 +1906,13 @@ async function captureIr(ir, opts) {
   const assets = await buildImageAssets(ir, sceneDir);
   const { fps, duration } = resolveTiming(ir, opts);
   const videoAssets = await buildVideoFrameAssets(ir, sceneDir, fps, duration);
-  const bundle = await browserBundle();
+  const bundle2 = 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.addScriptTag({ content: bundle2 });
     await page.evaluate(
       ([sceneIr, imageAssets, vAssets]) => window.__reframe.init(sceneIr, imageAssets, vAssets),
       [ir, assets, videoAssets]
@@ -2077,42 +2077,84 @@ import { dirname as dirname6, resolve as resolve5 } from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 var HERE = dirname6(fileURLToPath4(import.meta.url));
 var CORE_ENTRY = true ? resolve5(HERE, "index.js") : resolve5(HERE, "..", "..", "core", "src", "index.ts");
-async function loadDefault(path2) {
-  if (path2.endsWith(".json")) return JSON.parse(await readFile4(path2, "utf8"));
-  let code;
+var SceneLoadError = class extends Error {
+  kind;
+  constructor(kind, message, options) {
+    super(message, options);
+    this.name = "SceneLoadError";
+    this.kind = kind;
+  }
+};
+var clean = (err) => (err instanceof Error ? err.message : String(err)).replace(
+  /data:text\/javascript;base64,[A-Za-z0-9+/=]+/g,
+  "<scene bundle>"
+);
+var ALIAS = { "@reframe/core": CORE_ENTRY, "reframe-video": CORE_ENTRY };
+async function bundle(input) {
+  const common = {
+    bundle: true,
+    format: "esm",
+    platform: "neutral",
+    write: false,
+    logLevel: "silent",
+    sourcemap: "inline",
+    alias: ALIAS
+  };
   try {
-    const out = await build2({
-      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;
+    const out = await build2(
+      "path" in input ? { ...common, entryPoints: [input.path] } : { ...common, stdin: { contents: input.code, resolveDir: input.resolveDir, loader: "ts", sourcefile: "scene.ts" } }
+    );
+    return out.outputFiles[0].text;
   } catch (err) {
-    throw new Error(`failed to bundle ${path2}:
-${err instanceof Error ? err.message : String(err)}`);
+    throw new SceneLoadError("bundle", clean(err), { cause: 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`);
+}
+async function importDefault(code, label) {
+  let mod;
+  try {
+    mod = await import(`data:text/javascript;base64,${Buffer.from(code).toString("base64")}`);
+  } catch (err) {
+    const kind = err instanceof Error && err.name === "SceneValidationError" ? "validation" : "eval";
+    throw new SceneLoadError(kind, clean(err), { cause: err });
+  }
+  if (mod.default === void 0) throw new SceneLoadError("eval", `${label} must default-export a scene or composition`);
   return mod.default;
 }
+async function loadDefault(path2) {
+  if (path2.endsWith(".json")) {
+    try {
+      return JSON.parse(await readFile4(path2, "utf8"));
+    } catch (err) {
+      throw new SceneLoadError("eval", `failed to read ${path2}: ${clean(err)}`, { cause: err });
+    }
+  }
+  return importDefault(await bundle({ path: path2 }), path2);
+}
 function isComposition(def) {
   return typeof def === "object" && def !== null && Array.isArray(def.scenes);
 }
+function asScene(def, label) {
+  if (isComposition(def)) {
+    throw new SceneLoadError("validation", `${label} is a composition \u2014 render it directly, not as a single scene`);
+  }
+  try {
+    validateScene(def);
+  } catch (err) {
+    throw new SceneLoadError("validation", clean(err), { cause: err });
+  }
+  return def;
+}
 async function loadModule(path2) {
   const def = await loadDefault(path2);
   if (isComposition(def)) {
-    validateComposition(def);
+    try {
+      validateComposition(def);
+    } catch (err) {
+      throw new SceneLoadError("validation", clean(err), { cause: err });
+    }
     return { kind: "composition", ir: def };
   }
-  validateScene(def);
-  return { kind: "scene", ir: def };
+  return { kind: "scene", ir: asScene(def, path2) };
 }
 
 // ../render-cli/src/cli.ts

package/dist/compile-api.d.ts

@@ -0,0 +1,6 @@
+import type { CompositionIR, SceneIR } from "./index.js";
+export declare class SceneLoadError extends Error { readonly kind: "bundle" | "eval" | "validation"; }
+export declare function loadScene(path: string): Promise<SceneIR>;
+export declare function loadSceneFromCode(code: string, resolveDir?: string): Promise<SceneIR>;
+export declare function isComposition(def: unknown): def is CompositionIR;
+export declare function loadModule(path: string): Promise<{ kind: "scene"; ir: SceneIR } | { kind: "composition"; ir: CompositionIR }>;