reframe-video 0.6.17 → 0.6.19

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

@@ -578,6 +578,15 @@ function validateScene(ir) {
     if (cue.gain !== void 0 && cue.gain < 0) {
       problems.push(`audio.cues[${i}]: gain must be >= 0`);
     }
+    if (cue.fadeIn !== void 0 && cue.fadeIn < 0) {
+      problems.push(`audio.cues[${i}]: fadeIn must be >= 0`);
+    }
+    if (cue.fadeOut !== void 0 && cue.fadeOut < 0) {
+      problems.push(`audio.cues[${i}]: fadeOut must be >= 0`);
+    }
+    if (cue.pan !== void 0 && (cue.pan < -1 || cue.pan > 1)) {
+      problems.push(`audio.cues[${i}]: pan must be in [-1, 1] (-1 left \u2026 +1 right)`);
+    }
   }
   const duck = ir.audio?.bgm?.duck;
   if (typeof duck === "object" && duck !== null && duck.depth !== void 0 && (duck.depth < 0 || duck.depth > 1)) {
@@ -644,7 +653,7 @@ var init_validate = __esm({
       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"],
+      video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume", "fadeIn", "pan"],
       path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
       group: COMMON_PROPS
     };
@@ -1251,7 +1260,7 @@ function collectClipAudio(ir, duration, warnings) {
           warnings.push(`video "${node.id}": start ${start.toFixed(2)}s past the scene end \u2014 audio dropped`);
           continue;
         }
-        out.push({ nodeId: node.id, src: node.props.src, start, rate: node.props.rate ?? 1, clipStart: node.props.clipStart ?? 0, gain });
+        out.push({ nodeId: node.id, src: node.props.src, start, rate: node.props.rate ?? 1, clipStart: node.props.clipStart ?? 0, gain, fadeIn: node.props.fadeIn ?? 0, pan: node.props.pan ?? 0 });
       }
       if (node.type === "group") walk(node.children);
     }
@@ -1293,6 +1302,9 @@ function resolveAudioPlan(compiled) {
       t,
       gain: cue.gain ?? 1,
       duration: cueDuration,
+      fadeIn: cue.fadeIn ?? 0,
+      fadeOut: cue.fadeOut ?? 0,
+      pan: cue.pan ?? 0,
       source: cue.sfx ? { kind: "sfx", name: cue.sfx, params: cue.params ?? {} } : { kind: "file", path: cue.file }
     });
   }
@@ -1985,6 +1997,10 @@ function atempoChain(rate) {
   out.push(`atempo=${r.toFixed(4)}`);
   return out;
 }
+function panFilter(pan) {
+  const clamp = (v) => Math.max(0, Math.min(1, v)).toFixed(4);
+  return `pan=stereo|c0=${clamp(1 - pan)}*c0|c1=${clamp(1 + pan)}*c1`;
+}
 function buildFilterGraph(plan, inputs) {
   const lines = [];
   const mixIn = ["[anchor]"];
@@ -2013,7 +2029,14 @@ function buildFilterGraph(plan, inputs) {
   }
   plan.cues.forEach((cue, i) => {
     const delayMs = Math.round(cue.t * 1e3);
-    lines.push(`[${inputIndex}:a]${FORMAT},volume=${cue.gain},adelay=${delayMs}:all=1[c${i}]`);
+    const chain = [FORMAT, `volume=${cue.gain}`];
+    if (cue.fadeIn > 0) chain.push(`afade=t=in:st=0:d=${cue.fadeIn}`);
+    if (cue.fadeOut > 0) {
+      chain.push(`afade=t=out:st=${Math.max(0, cue.duration - cue.fadeOut).toFixed(3)}:d=${cue.fadeOut}`);
+    }
+    if (cue.pan !== 0) chain.push(panFilter(cue.pan));
+    chain.push(`adelay=${delayMs}:all=1`);
+    lines.push(`[${inputIndex}:a]${chain.join(",")}[c${i}]`);
     mixIn.push(`[c${i}]`);
     inputIndex++;
   });
@@ -2021,6 +2044,8 @@ function buildFilterGraph(plan, inputs) {
     const chain = [];
     if (audio.clipStart > 0) chain.push(`atrim=start=${audio.clipStart.toFixed(3)}`, "asetpts=PTS-STARTPTS");
     chain.push(...atempoChain(audio.rate), FORMAT, `volume=${audio.gain}`);
+    if (audio.fadeIn > 0) chain.push(`afade=t=in:st=0:d=${audio.fadeIn}`);
+    if (audio.pan !== 0) chain.push(panFilter(audio.pan));
     const delayMs = Math.round(audio.start * 1e3);
     if (delayMs > 0) chain.push(`adelay=${delayMs}:all=1`);
     lines.push(`[${inputIndex}:a]${chain.join(",")}[k${i}]`);
@@ -2455,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]
@@ -2654,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 };
   }
 });
 
@@ -2730,6 +2797,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 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 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");
@@ -2748,6 +2816,8 @@ 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} 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
@@ -2896,6 +2966,22 @@ ${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 "player": {
       const input = rest[0];
       if (!input || input.startsWith("-")) fail(`player needs a scene file

package/dist/browserEntry.js

@@ -350,7 +350,7 @@
     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"],
+    video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume", "fadeIn", "pan"],
     path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
     group: COMMON_PROPS
   };

package/dist/cli.js

@@ -355,7 +355,7 @@ var PROPS_BY_TYPE = {
   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"],
+  video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume", "fadeIn", "pan"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
   group: COMMON_PROPS
 };
@@ -592,6 +592,15 @@ function validateScene(ir) {
     if (cue.gain !== void 0 && cue.gain < 0) {
       problems.push(`audio.cues[${i}]: gain must be >= 0`);
     }
+    if (cue.fadeIn !== void 0 && cue.fadeIn < 0) {
+      problems.push(`audio.cues[${i}]: fadeIn must be >= 0`);
+    }
+    if (cue.fadeOut !== void 0 && cue.fadeOut < 0) {
+      problems.push(`audio.cues[${i}]: fadeOut must be >= 0`);
+    }
+    if (cue.pan !== void 0 && (cue.pan < -1 || cue.pan > 1)) {
+      problems.push(`audio.cues[${i}]: pan must be in [-1, 1] (-1 left \u2026 +1 right)`);
+    }
   }
   const duck = ir.audio?.bgm?.duck;
   if (typeof duck === "object" && duck !== null && duck.depth !== void 0 && (duck.depth < 0 || duck.depth > 1)) {
@@ -919,7 +928,7 @@ function collectClipAudio(ir, duration, warnings) {
           warnings.push(`video "${node.id}": start ${start.toFixed(2)}s past the scene end \u2014 audio dropped`);
           continue;
         }
-        out.push({ nodeId: node.id, src: node.props.src, start, rate: node.props.rate ?? 1, clipStart: node.props.clipStart ?? 0, gain });
+        out.push({ nodeId: node.id, src: node.props.src, start, rate: node.props.rate ?? 1, clipStart: node.props.clipStart ?? 0, gain, fadeIn: node.props.fadeIn ?? 0, pan: node.props.pan ?? 0 });
       }
       if (node.type === "group") walk(node.children);
     }
@@ -961,6 +970,9 @@ function resolveAudioPlan(compiled) {
       t,
       gain: cue.gain ?? 1,
       duration: cueDuration,
+      fadeIn: cue.fadeIn ?? 0,
+      fadeOut: cue.fadeOut ?? 0,
+      pan: cue.pan ?? 0,
       source: cue.sfx ? { kind: "sfx", name: cue.sfx, params: cue.params ?? {} } : { kind: "file", path: cue.file }
     });
   }
@@ -1038,6 +1050,9 @@ function resolveCompositionAudioPlan(comp) {
       t,
       gain: cue.gain ?? 1,
       duration: cueDuration,
+      fadeIn: cue.fadeIn ?? 0,
+      fadeOut: cue.fadeOut ?? 0,
+      pan: cue.pan ?? 0,
       source: cue.sfx ? { kind: "sfx", name: cue.sfx, params: cue.params ?? {} } : { kind: "file", path: cue.file }
     });
   }
@@ -1457,6 +1472,10 @@ function atempoChain(rate) {
   out.push(`atempo=${r.toFixed(4)}`);
   return out;
 }
+function panFilter(pan) {
+  const clamp = (v) => Math.max(0, Math.min(1, v)).toFixed(4);
+  return `pan=stereo|c0=${clamp(1 - pan)}*c0|c1=${clamp(1 + pan)}*c1`;
+}
 function buildFilterGraph(plan, inputs) {
   const lines = [];
   const mixIn = ["[anchor]"];
@@ -1485,7 +1504,14 @@ function buildFilterGraph(plan, inputs) {
   }
   plan.cues.forEach((cue, i) => {
     const delayMs = Math.round(cue.t * 1e3);
-    lines.push(`[${inputIndex}:a]${FORMAT},volume=${cue.gain},adelay=${delayMs}:all=1[c${i}]`);
+    const chain = [FORMAT, `volume=${cue.gain}`];
+    if (cue.fadeIn > 0) chain.push(`afade=t=in:st=0:d=${cue.fadeIn}`);
+    if (cue.fadeOut > 0) {
+      chain.push(`afade=t=out:st=${Math.max(0, cue.duration - cue.fadeOut).toFixed(3)}:d=${cue.fadeOut}`);
+    }
+    if (cue.pan !== 0) chain.push(panFilter(cue.pan));
+    chain.push(`adelay=${delayMs}:all=1`);
+    lines.push(`[${inputIndex}:a]${chain.join(",")}[c${i}]`);
     mixIn.push(`[c${i}]`);
     inputIndex++;
   });
@@ -1493,6 +1519,8 @@ function buildFilterGraph(plan, inputs) {
     const chain = [];
     if (audio.clipStart > 0) chain.push(`atrim=start=${audio.clipStart.toFixed(3)}`, "asetpts=PTS-STARTPTS");
     chain.push(...atempoChain(audio.rate), FORMAT, `volume=${audio.gain}`);
+    if (audio.fadeIn > 0) chain.push(`afade=t=in:st=0:d=${audio.fadeIn}`);
+    if (audio.pan !== 0) chain.push(panFilter(audio.pan));
     const delayMs = Math.round(audio.start * 1e3);
     if (delayMs > 0) chain.push(`adelay=${delayMs}:all=1`);
     lines.push(`[${inputIndex}:a]${chain.join(",")}[k${i}]`);
@@ -1878,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]
@@ -2049,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 SceneLoadError("bundle", clean(err), { cause: err });
+  }
+}
+async function importDefault(code, label) {
+  let mod;
+  try {
+    mod = await import(`data:text/javascript;base64,${Buffer.from(code).toString("base64")}`);
   } catch (err) {
-    throw new Error(`failed to bundle ${path2}:
-${err instanceof Error ? err.message : String(err)}`);
+    const kind = err instanceof Error && err.name === "SceneValidationError" ? "validation" : "eval";
+    throw new SceneLoadError(kind, 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`);
+  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 }>;