reframe-video 0.1.0 → 0.1.1

package/assets/sfx/LICENSE.md

@@ -6,6 +6,11 @@ Verified against each asset page's license field on 2026-06-11.
 |---|---|---|---|
 | keypress-001/004/007/010/014.wav | [Keyboard Soundpack #1](https://opengameart.org/content/keyboard-soundpack-1-typing-and-single-keystrokes) (Cherry KC 1000 recordings) | unicaegames | CC0 |
 | click_002/003/004.ogg, confirmation_001.ogg | [Interface Sounds](https://opengameart.org/content/interface-sounds) | Kenney (kenney.nl) | CC0 |
+| tick.wav (tick_001), pop.wav (drop_002), shimmer.wav (glass_002 + echo tail) | [Interface Sounds](https://opengameart.org/content/interface-sounds) | Kenney (kenney.nl) | CC0 |
+| whoosh.wav (wind body), rise.wav (reversed slice) | [Air whoosh](https://opengameart.org/content/air-whoosh) | qubodup | CC0 |
+| whoosh.wav (transient layer: swish-9) | [Swishes Sound Pack](https://opengameart.org/content/swishes-sound-pack) | artisticdude | CC0 |
+| thud.wav (trimmed) | [Muffled Distant Explosion](https://opengameart.org/content/muffled-distant-explosion) | NenadSimic | CC0 |
+| bgm-song21.mp3 | [Mysterious Ambience (song21)](https://opengameart.org/content/mysterious-ambience-song21) | cynicmusic (pixelsphere.org) | multi-licensed; used under its CC0 option |
 
 CC0 requires no attribution; this file records provenance anyway.
 Files placed here named after a procedural SFX (e.g. `whoosh.wav`) override

package/dist/bin.js

@@ -283,6 +283,7 @@ var init_validate = __esm({
       ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
       line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress"],
       text: [...COMMON_PROPS, "content", "contentDecimals", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
+      image: [...COMMON_PROPS, "src", "width", "height"],
       group: COMMON_PROPS
     };
     SceneValidationError = class extends Error {
@@ -600,6 +601,43 @@ var init_evaluate = __esm({
   }
 });
 
+// ../core/src/assets.ts
+function collectImageSrcs(ir) {
+  const srcs = /* @__PURE__ */ new Set();
+  const imageIds = /* @__PURE__ */ new Set();
+  const walkNodes = (nodes) => {
+    for (const node of nodes) {
+      if (node.type === "image") {
+        imageIds.add(node.id);
+        srcs.add(node.props.src);
+      }
+      if (node.type === "group") walkNodes(node.children);
+    }
+  };
+  walkNodes(ir.nodes);
+  for (const overrides of Object.values(ir.states ?? {})) {
+    for (const [nodeId, props] of Object.entries(overrides)) {
+      if (imageIds.has(nodeId) && typeof props.src === "string") srcs.add(props.src);
+    }
+  }
+  const walkTimeline = (step) => {
+    if (!step) return;
+    if (step.kind === "seq" || step.kind === "par" || step.kind === "stagger") {
+      for (const child of step.children) walkTimeline(child);
+    } else if (step.kind === "tween" && imageIds.has(step.target)) {
+      const src = step.props.src;
+      if (typeof src === "string") srcs.add(src);
+    }
+  };
+  walkTimeline(ir.timeline);
+  return [...srcs];
+}
+var init_assets = __esm({
+  "../core/src/assets.ts"() {
+    "use strict";
+  }
+});
+
 // ../core/src/index.ts
 var init_src = __esm({
   "../core/src/index.ts"() {
@@ -613,6 +651,7 @@ var init_src = __esm({
     init_evaluate();
     init_interpolate();
     init_behaviors();
+    init_assets();
   }
 });
 
@@ -988,12 +1027,12 @@ async function encodeMp4(framesDir, fps, outFile) {
     "+faststart",
     outFile
   ];
-  await new Promise((resolve4, reject) => {
+  await new Promise((resolve5, reject) => {
     const proc = spawn2("ffmpeg", args, { stdio: ["ignore", "ignore", "pipe"] });
     let stderr = "";
     proc.stderr.on("data", (d) => stderr += d.toString());
     proc.on("close", (code) => {
-      if (code === 0) resolve4();
+      if (code === 0) resolve5();
       else reject(new Error(`ffmpeg exited with ${code}:
 ${stderr.slice(-2e3)}`));
     });
@@ -1036,6 +1075,45 @@ var init_fonts = __esm({
   }
 });
 
+// ../render-cli/src/images.ts
+import { readFile as readFile2 } from "node:fs/promises";
+import { existsSync as existsSync2 } from "node:fs";
+import { extname, isAbsolute as isAbsolute2, resolve as resolve2 } from "node:path";
+async function buildImageAssets(ir, sceneDir) {
+  const assets = {};
+  for (const src of collectImageSrcs(ir)) {
+    const mime = MIME[extname(src).toLowerCase()];
+    if (!mime) {
+      throw new Error(
+        `image "${src}": unsupported format "${extname(src)}" \u2014 supported: ${Object.keys(MIME).join(" ")}`
+      );
+    }
+    const candidates = [isAbsolute2(src) ? src : null, resolve2(sceneDir, src)].filter(
+      (c) => c !== null
+    );
+    const found = candidates.find((c) => existsSync2(c));
+    if (!found) {
+      throw new Error(`image "${src}" not found (tried: ${candidates.join(", ")})`);
+    }
+    const data = await readFile2(found);
+    assets[src] = `data:${mime};base64,${data.toString("base64")}`;
+  }
+  return assets;
+}
+var MIME;
+var init_images = __esm({
+  "../render-cli/src/images.ts"() {
+    "use strict";
+    init_src();
+    MIME = {
+      ".png": "image/png",
+      ".jpg": "image/jpeg",
+      ".jpeg": "image/jpeg",
+      ".webp": "image/webp"
+    };
+  }
+});
+
 // ../render-cli/src/vclock.ts
 var VCLOCK_SOURCE;
 var init_vclock = __esm({
@@ -1141,8 +1219,8 @@ async function withPage(size, fn) {
 async function browserBundle() {
   if (bundleCache) return bundleCache;
   if (true) {
-    const { readFile: readFile4 } = await import("node:fs/promises");
-    bundleCache = await readFile4(
+    const { readFile: readFile5 } = await import("node:fs/promises");
+    bundleCache = await readFile5(
       join4(dirname4(fileURLToPath3(import.meta.url)), "browserEntry.js"),
       "utf8"
     );
@@ -1161,6 +1239,7 @@ async function browserBundle() {
 }
 async function captureIr(ir, opts) {
   await mkdir2(opts.framesDir, { recursive: true });
+  const assets = await buildImageAssets(ir, opts.sceneDir ?? process.cwd());
   const bundle = await browserBundle();
   return withPage(ir.size, async (page) => {
     await page.setContent(
@@ -1169,8 +1248,8 @@ async function captureIr(ir, opts) {
     await injectFonts(page);
     await page.addScriptTag({ content: bundle });
     const info = await page.evaluate(
-      (sceneIr) => window.__reframe.init(sceneIr),
-      ir
+      ([sceneIr, imageAssets]) => window.__reframe.init(sceneIr, imageAssets),
+      [ir, assets]
     );
     const fps = opts.fps ?? info.fps;
     const duration = opts.duration ?? info.duration;
@@ -1187,6 +1266,7 @@ var init_frameLoop = __esm({
   "../render-cli/src/frameLoop.ts"() {
     "use strict";
     init_fonts();
+    init_images();
     init_vclock();
     init_reframeGlobal();
     framePath = (dir, i) => join4(dir, `${String(i).padStart(5, "0")}.png`);
@@ -1202,9 +1282,9 @@ __export(batch_exports, {
   parseCsv: () => parseCsv,
   runBatch: () => runBatch
 });
-import { mkdir as mkdir3, mkdtemp as mkdtemp2, readFile as readFile2, rm as rm2, writeFile as writeFile4 } from "node:fs/promises";
+import { mkdir as mkdir3, mkdtemp as mkdtemp2, readFile as readFile3, rm as rm2, writeFile as writeFile4 } from "node:fs/promises";
 import { tmpdir as tmpdir3 } from "node:os";
-import { join as join5 } from "node:path";
+import { join as join5, dirname as dirname5 } from "node:path";
 function overlayFromFlat(row, name) {
   const doc = { reframeOverlay: 1, name };
   for (const [key2, raw] of Object.entries(row)) {
@@ -1278,7 +1358,7 @@ function parseCsv(text) {
   });
 }
 async function loadRows(path) {
-  const text = await readFile2(path, "utf8");
+  const text = await readFile3(path, "utf8");
   if (path.endsWith(".csv")) return parseCsv(text);
   const parsed = JSON.parse(text);
   if (!Array.isArray(parsed)) throw new Error(`${path}: expected a JSON array of row objects`);
@@ -1304,6 +1384,7 @@ async function runBatch(scene, rows, opts) {
         try {
           const captured = await captureIr(ir, {
             framesDir,
+            ...opts.scenePath !== void 0 && { sceneDir: dirname5(opts.scenePath) },
             ...opts.fps !== void 0 && { fps: opts.fps }
           });
           if (plan) {
@@ -1362,12 +1443,12 @@ __export(loadScene_exports, {
   loadScene: () => loadScene
 });
 import { build as build2 } from "esbuild";
-import { readFile as readFile3 } from "node:fs/promises";
-import { dirname as dirname5, resolve as resolve2 } from "node:path";
+import { readFile as readFile4 } from "node:fs/promises";
+import { dirname as dirname6, resolve as resolve3 } from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 async function loadScene(path) {
   if (path.endsWith(".json")) {
-    const ir = JSON.parse(await readFile3(path, "utf8"));
+    const ir = JSON.parse(await readFile4(path, "utf8"));
     validateScene(ir);
     return ir;
   }
@@ -1401,21 +1482,21 @@ var init_loadScene = __esm({
   "../render-cli/src/loadScene.ts"() {
     "use strict";
     init_src();
-    HERE = dirname5(fileURLToPath4(import.meta.url));
-    CORE_ENTRY = true ? resolve2(HERE, "index.js") : resolve2(HERE, "..", "..", "core", "src", "index.ts");
+    HERE = dirname6(fileURLToPath4(import.meta.url));
+    CORE_ENTRY = true ? resolve3(HERE, "index.js") : resolve3(HERE, "..", "..", "core", "src", "index.ts");
   }
 });
 
 // ../render-cli/src/reframe.ts
 import { spawn as spawn3, spawnSync } from "node:child_process";
-import { existsSync as existsSync2 } from "node:fs";
+import { existsSync as existsSync3 } from "node:fs";
 import { mkdir as mkdir4, writeFile as writeFile5 } from "node:fs/promises";
-import { basename, isAbsolute as isAbsolute2, join as join6, resolve as resolve3 } from "node:path";
-import { dirname as dirname6 } from "node:path";
+import { basename, isAbsolute as isAbsolute3, join as join6, resolve as resolve4 } from "node:path";
+import { dirname as dirname7 } from "node:path";
 import { fileURLToPath as fileURLToPath5 } from "node:url";
 var PACKAGED = true;
-var HERE2 = dirname6(fileURLToPath5(import.meta.url));
-var ROOT2 = PACKAGED ? resolve3(HERE2, "..") : resolve3(HERE2, "..", "..", "..");
+var HERE2 = dirname7(fileURLToPath5(import.meta.url));
+var ROOT2 = PACKAGED ? resolve4(HERE2, "..") : resolve4(HERE2, "..", "..", "..");
 var USER_CWD = process.env.INIT_CWD ?? process.cwd();
 var RENDER_CLI = PACKAGED ? join6(ROOT2, "dist", "cli.js") : join6(ROOT2, "packages", "render-cli", "src", "cli.ts");
 var ANALYZE = PACKAGED ? join6(ROOT2, "dist", "analyze.js") : join6(ROOT2, "benchmark", "harness", "motion", "analyze.ts");
@@ -1431,7 +1512,7 @@ usage:
   ${CMD} guide [--regen]         print the scene-authoring guide (for you or your AI)
   ${CMD} demo                    run the edit-survival demo (3 mp4s into out/)
 `;
-var userPath = (p) => isAbsolute2(p) ? p : resolve3(USER_CWD, p);
+var userPath = (p) => isAbsolute3(p) ? p : resolve4(USER_CWD, p);
 function fail(message) {
   console.error(`error: ${message}`);
   process.exit(2);
@@ -1533,7 +1614,7 @@ async function main() {
 
 ${USAGE}`);
       const inputPath = userPath(input);
-      if (!existsSync2(inputPath)) fail(`no such file: ${inputPath}`);
+      if (!existsSync3(inputPath)) fail(`no such file: ${inputPath}`);
       const mode = /\.(ts|json)$/.test(input) ? "ir" : /\.html$/.test(input) ? "html" : null;
       if (!mode) {
         fail(`cannot infer render mode from "${input}" \u2014 expected .ts/.json (reframe scene) or .html (GSAP page)`);
@@ -1561,7 +1642,7 @@ ${USAGE}`);
       if (!sceneArg || !dataArg) fail(`usage: ${CMD} batch <scene.ts> <data.json|csv> [...]`);
       const scenePath = userPath(sceneArg);
       const dataPath = userPath(dataArg);
-      for (const p of [scenePath, dataPath]) if (!existsSync2(p)) fail(`no such file: ${p}`);
+      for (const p of [scenePath, dataPath]) if (!existsSync3(p)) fail(`no such file: ${p}`);
       preflightFfmpeg();
       let outDir = PACKAGED ? join6(USER_CWD, "out", "batch") : join6(ROOT2, "out", "batch");
       let concurrency = 3;
@@ -1576,10 +1657,10 @@ ${USAGE}`);
       }
       const { loadRows: loadRows2, runBatch: runBatch2 } = await Promise.resolve().then(() => (init_batch(), batch_exports));
       const { loadScene: loadScene2 } = await Promise.resolve().then(() => (init_loadScene(), loadScene_exports));
-      const { readFile: readFile4 } = await import("node:fs/promises");
+      const { readFile: readFile5 } = await import("node:fs/promises");
       const scene = await loadScene2(scenePath);
       const baseOverlays = await Promise.all(
-        baseOverlayPaths.map(async (p) => JSON.parse(await readFile4(p, "utf8")))
+        baseOverlayPaths.map(async (p) => JSON.parse(await readFile5(p, "utf8")))
       );
       const rows = await loadRows2(dataPath);
       if (rows.length === 0) fail(`${dataPath}: no data rows`);
@@ -1610,7 +1691,7 @@ ${results.length - failed} rendered (${orphaned} with orphans), ${failed} failed
       if (PACKAGED) {
         const { createRequire } = await import("node:module");
         const vitePkg = createRequire(import.meta.url).resolve("vite/package.json");
-        const viteBin = join6(dirname6(vitePkg), "bin", "vite.js");
+        const viteBin = join6(dirname7(vitePkg), "bin", "vite.js");
         process.exit(
           await run(process.execPath, [viteBin, join6(ROOT2, "preview")], {
             env: { REFRAME_SCENE_DIR: USER_CWD }
@@ -1633,7 +1714,7 @@ ${results.length - failed} rendered (${orphaned} with orphans), ${failed} failed
       const targetDir = inRepo ? join6(ROOT2, "examples", "scenes") : USER_CWD;
       const target = join6(targetDir, `${name}.ts`);
       const shown = inRepo ? `examples/scenes/${name}.ts` : `${name}.ts`;
-      if (existsSync2(target)) fail(`${shown} already exists`);
+      if (existsSync3(target)) fail(`${shown} already exists`);
       const id = name.split("-")[0] ?? name;
       await writeFile5(target, SCENE_TEMPLATE(name, id));
       console.log(`created ${shown}
@@ -1652,8 +1733,8 @@ ${results.length - failed} rendered (${orphaned} with orphans), ${failed} failed
     }
     case "guide": {
       const file = rest.includes("--regen") ? PACKAGED ? join6(ROOT2, "guides", "regen-contract.md") : join6(ROOT2, "docs", "regen-contract.md") : PACKAGED ? join6(ROOT2, "guides", "edsl-guide.md") : join6(ROOT2, "benchmark", "guides", "edsl-guide.md");
-      const { readFile: readFile4 } = await import("node:fs/promises");
-      process.stdout.write(await readFile4(file, "utf8"));
+      const { readFile: readFile5 } = await import("node:fs/promises");
+      process.stdout.write(await readFile5(file, "utf8"));
       return;
     }
     case "demo":

package/dist/browserEntry.js

@@ -137,6 +137,7 @@
     ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
     line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress"],
     text: [...COMMON_PROPS, "content", "contentDecimals", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
+    image: [...COMMON_PROPS, "src", "width", "height"],
     group: COMMON_PROPS
   };
 
@@ -394,6 +395,23 @@
           });
           return;
         }
+        case "image": {
+          const width = num(id, "width", node.props.width);
+          const height = num(id, "height", node.props.height);
+          const [ax, ay] = ANCHOR_FACTORS[node.props.anchor ?? "top-left"];
+          ops.push({
+            type: "image",
+            id,
+            transform: matrix,
+            opacity,
+            src: str(id, "src", node.props.src),
+            width,
+            height,
+            offsetX: -width * ax,
+            offsetY: -height * ay
+          });
+          return;
+        }
         case "text": {
           const [ax, ay] = ANCHOR_FACTORS[node.props.anchor ?? "top-left"];
           const raw = valueAt(id, "content", node.props.content);
@@ -424,7 +442,7 @@
   }
 
   // ../renderer-canvas/src/index.ts
-  function renderFrame(ctx2, compiled2, t) {
+  function renderFrame(ctx2, compiled2, t, images2) {
     const { size, background } = compiled2.ir;
     ctx2.setTransform(1, 0, 0, 1, 0, 0);
     ctx2.clearRect(0, 0, size.width, size.height);
@@ -432,9 +450,9 @@
       ctx2.fillStyle = background;
       ctx2.fillRect(0, 0, size.width, size.height);
     }
-    drawDisplayList(ctx2, evaluate(compiled2, t));
+    drawDisplayList(ctx2, evaluate(compiled2, t), images2);
   }
-  function drawDisplayList(ctx2, ops) {
+  function drawDisplayList(ctx2, ops, images2) {
     for (const op of ops) {
       ctx2.save();
       ctx2.setTransform(...op.transform);
@@ -490,6 +508,25 @@
           ctx2.stroke();
           break;
         }
+        case "image": {
+          const img = images2?.get(op.src);
+          if (img) {
+            ctx2.drawImage(img, op.offsetX, op.offsetY, op.width, op.height);
+          } else {
+            ctx2.fillStyle = "#2A2A30";
+            ctx2.fillRect(op.offsetX, op.offsetY, op.width, op.height);
+            ctx2.strokeStyle = "#FF00FF";
+            ctx2.lineWidth = 2;
+            ctx2.strokeRect(op.offsetX, op.offsetY, op.width, op.height);
+            ctx2.beginPath();
+            ctx2.moveTo(op.offsetX, op.offsetY);
+            ctx2.lineTo(op.offsetX + op.width, op.offsetY + op.height);
+            ctx2.moveTo(op.offsetX + op.width, op.offsetY);
+            ctx2.lineTo(op.offsetX, op.offsetY + op.height);
+            ctx2.stroke();
+          }
+          break;
+        }
         case "text": {
           ctx2.font = `${op.fontWeight} ${op.fontSize}px ${quoteFamily(op.fontFamily)}`;
           if (op.letterSpacing) ctx2.letterSpacing = `${op.letterSpacing}px`;
@@ -512,8 +549,10 @@
   var compiled = null;
   var ctx = null;
   var canvas = null;
+  var images = /* @__PURE__ */ new Map();
   window.__reframe = {
-    init(ir) {
+    // fully decode every image before the first frame — renderFrame is sync
+    async init(ir, assets = {}) {
       compiled = compileScene(ir);
       canvas = document.createElement("canvas");
       canvas.width = ir.size.width;
@@ -521,11 +560,19 @@
       document.body.appendChild(canvas);
       ctx = canvas.getContext("2d", { willReadFrequently: true });
       if (!ctx) throw new Error("could not create 2d context");
+      await Promise.all(
+        Object.entries(assets).map(async ([src, dataUrl]) => {
+          const img = new Image();
+          img.src = dataUrl;
+          await img.decode();
+          images.set(src, img);
+        })
+      );
       return { duration: compiled.duration, fps: ir.fps ?? 30 };
     },
     renderFrame(t) {
       if (!compiled || !ctx || !canvas) throw new Error("init() not called");
-      renderFrame(ctx, compiled, t);
+      renderFrame(ctx, compiled, t, images);
       return canvas.toDataURL("image/png");
     }
   };

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env tsx
 
 // ../render-cli/src/cli.ts
-import { mkdtemp as mkdtemp2, readFile as readFile3, rm as rm2 } from "node:fs/promises";
+import { mkdtemp as mkdtemp2, readFile as readFile4, rm as rm2 } from "node:fs/promises";
 import { tmpdir as tmpdir3 } from "node:os";
-import { basename, join as join5, resolve as resolve3 } from "node:path";
+import { basename, dirname as dirname6, join as join5, resolve as resolve4 } from "node:path";
 
 // ../core/src/ir.ts
 var DEFAULT_TO_DURATION = 0.5;
@@ -142,6 +142,7 @@ var PROPS_BY_TYPE = {
   ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
   line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress"],
   text: [...COMMON_PROPS, "content", "contentDecimals", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
+  image: [...COMMON_PROPS, "src", "width", "height"],
   group: COMMON_PROPS
 };
 var SceneValidationError = class extends Error {
@@ -542,6 +543,38 @@ var EASE_TABLE = {
 };
 var EASE_NAMES = Object.keys(EASE_TABLE);
 
+// ../core/src/assets.ts
+function collectImageSrcs(ir) {
+  const srcs = /* @__PURE__ */ new Set();
+  const imageIds = /* @__PURE__ */ new Set();
+  const walkNodes = (nodes) => {
+    for (const node of nodes) {
+      if (node.type === "image") {
+        imageIds.add(node.id);
+        srcs.add(node.props.src);
+      }
+      if (node.type === "group") walkNodes(node.children);
+    }
+  };
+  walkNodes(ir.nodes);
+  for (const overrides of Object.values(ir.states ?? {})) {
+    for (const [nodeId, props] of Object.entries(overrides)) {
+      if (imageIds.has(nodeId) && typeof props.src === "string") srcs.add(props.src);
+    }
+  }
+  const walkTimeline = (step) => {
+    if (!step) return;
+    if (step.kind === "seq" || step.kind === "par" || step.kind === "stagger") {
+      for (const child of step.children) walkTimeline(child);
+    } else if (step.kind === "tween" && imageIds.has(step.target)) {
+      const src = step.props.src;
+      if (typeof src === "string") srcs.add(src);
+    }
+  };
+  walkTimeline(ir.timeline);
+  return [...srcs];
+}
+
 // ../render-cli/src/audio/index.ts
 import { dirname as dirname2 } from "node:path";
 
@@ -881,12 +914,12 @@ async function encodeMp4(framesDir, fps, outFile) {
     "+faststart",
     outFile
   ];
-  await new Promise((resolve4, reject) => {
+  await new Promise((resolve5, reject) => {
     const proc = spawn2("ffmpeg", args, { stdio: ["ignore", "ignore", "pipe"] });
     let stderr = "";
     proc.stderr.on("data", (d) => stderr += d.toString());
     proc.on("close", (code) => {
-      if (code === 0) resolve4();
+      if (code === 0) resolve5();
       else reject(new Error(`ffmpeg exited with ${code}:
 ${stderr.slice(-2e3)}`));
     });
@@ -925,6 +958,38 @@ async function fontFaceCss() {
   return cssCache;
 }
 
+// ../render-cli/src/images.ts
+import { readFile as readFile2 } from "node:fs/promises";
+import { existsSync as existsSync2 } from "node:fs";
+import { extname, isAbsolute as isAbsolute2, resolve as resolve2 } from "node:path";
+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 = [isAbsolute2(src) ? src : null, resolve2(sceneDir, src)].filter(
+      (c) => c !== null
+    );
+    const found = candidates.find((c) => existsSync2(c));
+    if (!found) {
+      throw new Error(`image "${src}" not found (tried: ${candidates.join(", ")})`);
+    }
+    const data = await readFile2(found);
+    assets[src] = `data:${mime};base64,${data.toString("base64")}`;
+  }
+  return assets;
+}
+
 // ../render-cli/src/vclock.ts
 var VCLOCK_SOURCE = String.raw`
 (() => {
@@ -1014,8 +1079,8 @@ var bundleCache = null;
 async function browserBundle() {
   if (bundleCache) return bundleCache;
   if (true) {
-    const { readFile: readFile4 } = await import("node:fs/promises");
-    bundleCache = await readFile4(
+    const { readFile: readFile5 } = await import("node:fs/promises");
+    bundleCache = await readFile5(
       join4(dirname4(fileURLToPath3(import.meta.url)), "browserEntry.js"),
       "utf8"
     );
@@ -1034,6 +1099,7 @@ async function browserBundle() {
 }
 async function captureIr(ir, opts) {
   await mkdir2(opts.framesDir, { recursive: true });
+  const assets = await buildImageAssets(ir, opts.sceneDir ?? process.cwd());
   const bundle = await browserBundle();
   return withPage(ir.size, async (page) => {
     await page.setContent(
@@ -1042,8 +1108,8 @@ async function captureIr(ir, opts) {
     await injectFonts(page);
     await page.addScriptTag({ content: bundle });
     const info = await page.evaluate(
-      (sceneIr) => window.__reframe.init(sceneIr),
-      ir
+      ([sceneIr, imageAssets]) => window.__reframe.init(sceneIr, imageAssets),
+      [ir, assets]
     );
     const fps = opts.fps ?? info.fps;
     const duration = opts.duration ?? info.duration;
@@ -1080,14 +1146,14 @@ async function captureHtml(htmlPath, opts) {
 
 // ../render-cli/src/loadScene.ts
 import { build as build2 } from "esbuild";
-import { readFile as readFile2 } from "node:fs/promises";
-import { dirname as dirname5, resolve as resolve2 } from "node:path";
+import { readFile as readFile3 } from "node:fs/promises";
+import { dirname as dirname5, resolve as resolve3 } from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 var HERE = dirname5(fileURLToPath4(import.meta.url));
-var CORE_ENTRY = true ? resolve2(HERE, "index.js") : resolve2(HERE, "..", "..", "core", "src", "index.ts");
+var CORE_ENTRY = true ? resolve3(HERE, "index.js") : resolve3(HERE, "..", "..", "core", "src", "index.ts");
 async function loadScene(path) {
   if (path.endsWith(".json")) {
-    const ir = JSON.parse(await readFile2(path, "utf8"));
+    const ir = JSON.parse(await readFile3(path, "utf8"));
     validateScene(ir);
     return ir;
   }
@@ -1128,7 +1194,7 @@ function parseArgs(argv) {
   }
   const args = {
     mode,
-    input: resolve3(input),
+    input: resolve4(input),
     out: `${basename(input).replace(/\.[^.]+$/, "")}.mp4`,
     keepFrames: false,
     overlays: [],
@@ -1140,8 +1206,8 @@ function parseArgs(argv) {
     else if (a === "--fps") args.fps = Number(rest[++i]);
     else if (a === "--duration") args.duration = Number(rest[++i]);
     else if (a === "--keep-frames") args.keepFrames = true;
-    else if (a === "--frames-dir") args.framesDir = resolve3(rest[++i]);
-    else if (a === "--overlay") args.overlays.push(resolve3(rest[++i]));
+    else if (a === "--frames-dir") args.framesDir = resolve4(rest[++i]);
+    else if (a === "--overlay") args.overlays.push(resolve4(rest[++i]));
     else if (a === "--no-audio") args.noAudio = true;
     else {
       console.error(`unknown flag ${a}`);
@@ -1159,7 +1225,7 @@ async function main() {
     let ir = await loadScene(args.input);
     if (args.overlays.length > 0) {
       const docs = await Promise.all(
-        args.overlays.map(async (p) => JSON.parse(await readFile3(p, "utf8")))
+        args.overlays.map(async (p) => JSON.parse(await readFile4(p, "utf8")))
       );
       const composed = composeScene(ir, ...docs);
       console.error(formatComposeReport(composed.report));
@@ -1174,6 +1240,7 @@ async function main() {
     }
     result = await captureIr(ir, {
       framesDir,
+      sceneDir: dirname6(args.input),
       ...args.fps !== void 0 && { fps: args.fps },
       ...args.duration !== void 0 && { duration: args.duration }
     });

package/dist/index.js

@@ -136,6 +136,7 @@ var PROPS_BY_TYPE = {
   ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
   line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress"],
   text: [...COMMON_PROPS, "content", "contentDecimals", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
+  image: [...COMMON_PROPS, "src", "width", "height"],
   group: COMMON_PROPS
 };
 var SceneValidationError = class extends Error {
@@ -293,6 +294,10 @@ function text(props) {
   const { id, ...rest } = props;
   return { type: "text", id, props: rest };
 }
+function image(props) {
+  const { id, ...rest } = props;
+  return { type: "image", id, props: rest };
+}
 function group(props, children) {
   const { id, ...rest } = props;
   return { type: "group", id, props: rest, children };
@@ -826,6 +831,23 @@ function evaluate(compiled, t) {
         });
         return;
       }
+      case "image": {
+        const width = num(id, "width", node.props.width);
+        const height = num(id, "height", node.props.height);
+        const [ax, ay] = ANCHOR_FACTORS[node.props.anchor ?? "top-left"];
+        ops.push({
+          type: "image",
+          id,
+          transform: matrix,
+          opacity,
+          src: str(id, "src", node.props.src),
+          width,
+          height,
+          offsetX: -width * ax,
+          offsetY: -height * ay
+        });
+        return;
+      }
       case "text": {
         const [ax, ay] = ANCHOR_FACTORS[node.props.anchor ?? "top-left"];
         const raw = valueAt(id, "content", node.props.content);
@@ -854,6 +876,38 @@ function evaluate(compiled, t) {
   for (const node of compiled.ir.nodes) walk(node, IDENTITY, 1);
   return ops;
 }
+
+// ../core/src/assets.ts
+function collectImageSrcs(ir) {
+  const srcs = /* @__PURE__ */ new Set();
+  const imageIds = /* @__PURE__ */ new Set();
+  const walkNodes = (nodes) => {
+    for (const node of nodes) {
+      if (node.type === "image") {
+        imageIds.add(node.id);
+        srcs.add(node.props.src);
+      }
+      if (node.type === "group") walkNodes(node.children);
+    }
+  };
+  walkNodes(ir.nodes);
+  for (const overrides of Object.values(ir.states ?? {})) {
+    for (const [nodeId, props] of Object.entries(overrides)) {
+      if (imageIds.has(nodeId) && typeof props.src === "string") srcs.add(props.src);
+    }
+  }
+  const walkTimeline = (step) => {
+    if (!step) return;
+    if (step.kind === "seq" || step.kind === "par" || step.kind === "stagger") {
+      for (const child of step.children) walkTimeline(child);
+    } else if (step.kind === "tween" && imageIds.has(step.target)) {
+      const src = step.props.src;
+      if (typeof src === "string") srcs.add(src);
+    }
+  };
+  walkTimeline(ir.timeline);
+  return [...srcs];
+}
 export {
   DEFAULT_FPS,
   DEFAULT_TO_DURATION,
@@ -862,12 +916,14 @@ export {
   PROPS_BY_TYPE,
   SFX_DURATION,
   SceneValidationError,
+  collectImageSrcs,
   compileScene,
   composeScene,
   ellipse,
   evaluate,
   formatComposeReport,
   group,
+  image,
   isColor,
   lerpValue,
   line,

package/dist/renderer-canvas.js

@@ -1,6 +1,6 @@
 // ../renderer-canvas/src/index.ts
 import { evaluate } from "@reframe/core";
-function renderFrame(ctx, compiled, t) {
+function renderFrame(ctx, compiled, t, images) {
   const { size, background } = compiled.ir;
   ctx.setTransform(1, 0, 0, 1, 0, 0);
   ctx.clearRect(0, 0, size.width, size.height);
@@ -8,9 +8,9 @@ function renderFrame(ctx, compiled, t) {
     ctx.fillStyle = background;
     ctx.fillRect(0, 0, size.width, size.height);
   }
-  drawDisplayList(ctx, evaluate(compiled, t));
+  drawDisplayList(ctx, evaluate(compiled, t), images);
 }
-function drawDisplayList(ctx, ops) {
+function drawDisplayList(ctx, ops, images) {
   for (const op of ops) {
     ctx.save();
     ctx.setTransform(...op.transform);
@@ -66,6 +66,25 @@ function drawDisplayList(ctx, ops) {
         ctx.stroke();
         break;
       }
+      case "image": {
+        const img = images?.get(op.src);
+        if (img) {
+          ctx.drawImage(img, op.offsetX, op.offsetY, op.width, op.height);
+        } else {
+          ctx.fillStyle = "#2A2A30";
+          ctx.fillRect(op.offsetX, op.offsetY, op.width, op.height);
+          ctx.strokeStyle = "#FF00FF";
+          ctx.lineWidth = 2;
+          ctx.strokeRect(op.offsetX, op.offsetY, op.width, op.height);
+          ctx.beginPath();
+          ctx.moveTo(op.offsetX, op.offsetY);
+          ctx.lineTo(op.offsetX + op.width, op.offsetY + op.height);
+          ctx.moveTo(op.offsetX + op.width, op.offsetY);
+          ctx.lineTo(op.offsetX, op.offsetY + op.height);
+          ctx.stroke();
+        }
+        break;
+      }
       case "text": {
         ctx.font = `${op.fontWeight} ${op.fontSize}px ${quoteFamily(op.fontFamily)}`;
         if (op.letterSpacing) ctx.letterSpacing = `${op.letterSpacing}px`;

package/dist/types/assets.d.ts

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

package/dist/types/dsl.d.ts

@@ -2,7 +2,7 @@
  * The eDSL surface: thin factories that build plain IR objects.
  * `scene()` validates and returns the IR — the return value is the document.
  */
-import type { AudioIR, BehaviorIR, Ease, EllipseProps, GroupProps, LineProps, NodeIR, PropValue, RectProps, SceneIR, Size, StateOverride, TextProps, TimelineIR } from "./ir.js";
+import type { AudioIR, BehaviorIR, Ease, EllipseProps, GroupProps, ImageProps, LineProps, NodeIR, PropValue, RectProps, SceneIR, Size, StateOverride, TextProps, TimelineIR } from "./ir.js";
 export interface SceneInput {
     id: string;
     size: Size;
@@ -30,6 +30,9 @@ export declare function line(props: {
 export declare function text(props: {
     id: string;
 } & TextProps): NodeIR;
+export declare function image(props: {
+    id: string;
+} & ImageProps): NodeIR;
 export declare function group(props: {
     id: string;
 } & GroupProps, children: NodeIR[]): NodeIR;

package/dist/types/evaluate.d.ts

@@ -53,6 +53,14 @@ export type DisplayOp = (OpBase & {
     letterSpacing: number;
     align: TextAlign;
     baseline: TextBaseline;
+}) | (OpBase & {
+    type: "image";
+    /** Raw src string as authored in the IR — consumers resolve it. */
+    src: string;
+    width: number;
+    height: number;
+    offsetX: number;
+    offsetY: number;
 });
 export type DisplayList = DisplayOp[];
 export declare function evaluate(compiled: CompiledScene, t: number): DisplayList;

package/dist/types/index.d.ts

@@ -7,3 +7,4 @@ export { resolveAudioPlan, SFX_DURATION, type AudioPlan, type ResolvedCue, } fro
 export { evaluate, type DisplayList, type DisplayOp, type Mat2D, type TextAlign, type TextBaseline, } from "./evaluate.js";
 export { resolveEase, lerpValue, isColor, EASE_NAMES } from "./interpolate.js";
 export { sampleBehavior } from "./behaviors.js";
+export { collectImageSrcs } from "./assets.js";

package/dist/types/ir.d.ts

@@ -65,6 +65,17 @@ export interface TextProps extends BaseProps {
 }
 export interface GroupProps extends BaseProps {
 }
+export interface ImageProps extends BaseProps {
+    /**
+     * Image file path: absolute, or relative to the scene file. Drawn
+     * stretched to width×height. As a string prop it switches discretely at
+     * segment start (no crossfade) — for hard-cut sequences stack image
+     * nodes and step their opacity instead.
+     */
+    src: string;
+    width: number;
+    height: number;
+}
 export type NodeIR = {
     type: "rect";
     id: string;
@@ -81,6 +92,10 @@ export type NodeIR = {
     type: "text";
     id: string;
     props: TextProps;
+} | {
+    type: "image";
+    id: string;
+    props: ImageProps;
 } | {
     type: "group";
     id: string;

package/guides/edsl-guide.md

@@ -34,6 +34,11 @@ Factories return plain data. Every node needs a unique `id`.
   `content` may be a number; numeric content interpolates (count-up) and renders
   via `toFixed(contentDecimals ?? 0)`. For a "8.2"-style label, set
   `contentDecimals: 1`.
+- `image({ id, src, x, y, width, height, opacity?, rotation?, scale?, anchor? })` —
+  `src` is a file path, absolute or relative to the scene file; drawn stretched
+  to `width`×`height` (png/jpg/webp). `src` switches discretely (no crossfade) —
+  for hard-cut frame sequences stack image nodes and step their `opacity`; for
+  a dissolve, crossfade two nodes' opacity.
 - `group({ id, x, y, opacity?, rotation?, scale?, anchor? }, children)` — children's
   coordinates are relative to the group; group opacity/transform multiply down.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reframe-video",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",

package/preview/src/main.ts

@@ -5,7 +5,7 @@
  * path never uses wall-clock time.
  */
 
-import { evaluate, type DisplayOp, type SceneIR } from "@reframe/core";
+import { collectImageSrcs, evaluate, type DisplayOp, type SceneIR } from "@reframe/core";
 import { renderFrame } from "@reframe/renderer-canvas";
 import { userScenes } from "virtual:reframe-user-scenes";
 import { buildPanel } from "./panel.js";
@@ -13,17 +13,23 @@ import { EditorStore } from "./store.js";
 
 interface SceneEntry {
   label: string;
+  /** Absolute directory of the scene file — relative image srcs resolve here. */
+  dir: string;
   load: () => Promise<{ default: SceneIR }>;
 }
 
 const exampleModules = ({} as Record<string, () => Promise<{ default: SceneIR }>>);
 const modules: Record<string, SceneEntry> = {};
 for (const path of Object.keys(exampleModules).sort()) {
-  modules[path] = { label: path.split("/").pop()!.replace(".ts", ""), load: exampleModules[path]! };
+  modules[path] = {
+    label: path.split("/").pop()!.replace(".ts", ""),
+    dir: __REFRAME_EXAMPLES_DIR__,
+    load: exampleModules[path]!,
+  };
 }
 // scenes from the directory `reframe preview` was invoked in
-for (const { name, load } of userScenes) {
-  modules[`user:${name}`] ??= { label: `${name} (cwd)`, load };
+for (const { name, dir, load } of userScenes) {
+  modules[`user:${name}`] ??= { label: `${name} (cwd)`, dir, load };
 }
 
 const canvas = document.getElementById("canvas") as HTMLCanvasElement;
@@ -47,9 +53,43 @@ for (const [key, entry] of Object.entries(modules)) {
   select.appendChild(option);
 }
 
+// decoded images keyed by raw src; missing entries render as a placeholder
+const images = new Map<string, CanvasImageSource>();
+const imageLoads = new Map<string, Promise<void>>();
+let sceneDir = "";
+
+/** Load any not-yet-loaded srcs of the current scene via /@fs. */
+function ensureImages(): Promise<void> {
+  if (!store) return Promise.resolve();
+  const pending: Promise<void>[] = [];
+  for (const src of collectImageSrcs(store.compiled.ir)) {
+    if (images.has(src) || imageLoads.has(src)) continue;
+    const url = `/@fs${src.startsWith("/") ? src : `${sceneDir}/${src}`}`;
+    const load = new Promise<void>((done) => {
+      const img = new Image();
+      img.onload = () => {
+        images.set(src, img);
+        done();
+        draw();
+      };
+      img.onerror = () => {
+        console.warn(`image "${src}" failed to load (${url}) — rendering placeholder`);
+        done();
+      };
+      img.src = url;
+    });
+    imageLoads.set(src, load);
+    pending.push(load);
+  }
+  return Promise.all(pending).then(() => undefined);
+}
+
 async function loadScene(path: string) {
   const mod = await modules[path]!.load();
   store = new EditorStore(mod.default);
+  sceneDir = modules[path]!.dir;
+  images.clear();
+  imageLoads.clear();
   (window as unknown as { __store: EditorStore }).__store = store; // debug/testing hook
   panel = buildPanel(store, panelRoot);
   canvas.width = store.compiled.ir.size.width;
@@ -58,9 +98,11 @@ async function loadScene(path: string) {
     t = Math.min(t, store!.compiled.duration);
     if (kind === "structure") panel!.rebuild();
     else panel!.refreshReport();
+    void ensureImages(); // an edited src loads lazily, then redraws
     draw();
   });
   await document.fonts.ready;
+  await ensureImages();
   t = 0;
   panel.rebuild();
   draw();
@@ -73,7 +115,8 @@ function applyMat(m: number[], x: number, y: number): [number, number] {
 function opCorners(op: DisplayOp): [number, number][] {
   switch (op.type) {
     case "rect":
-    case "ellipse": {
+    case "ellipse":
+    case "image": {
       const { offsetX: x, offsetY: y, width: w, height: h } = op;
       return [[x, y], [x + w, y], [x + w, y + h], [x, y + h]].map(([px, py]) =>
         applyMat(op.transform, px!, py!),
@@ -96,7 +139,7 @@ function opCorners(op: DisplayOp): [number, number][] {
 
 function draw() {
   if (!store) return;
-  renderFrame(ctx, store.compiled, t);
+  renderFrame(ctx, store.compiled, t, images);
 
   if (store.selectedId) {
     const ops = evaluate(store.compiled, t).filter((op) => op.id === store!.selectedId);

package/preview/src/virtual.d.ts

@@ -1,4 +1,12 @@
 declare module "virtual:reframe-user-scenes" {
   import type { SceneIR } from "@reframe/core";
-  export const userScenes: { name: string; load: () => Promise<{ default: SceneIR }> }[];
+  export const userScenes: {
+    name: string;
+    /** Absolute directory containing the scene file. */
+    dir: string;
+    load: () => Promise<{ default: SceneIR }>;
+  }[];
 }
+
+/** Absolute path of examples/scenes (injected by vite define; "" when packaged). */
+declare const __REFRAME_EXAMPLES_DIR__: string;

package/preview/vite.config.ts

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { basename, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { defineConfig, type Plugin } from "vite";
 
 const PKG_ROOT = resolve(__dirname, "..");
@@ -31,7 +31,7 @@ const userScenesPlugin: Plugin = {
     if (id !== "\0reframe-user-scenes") return undefined;
     const entries = userScenes().map(
       (s) =>
-        `  { name: ${JSON.stringify(s.name)}, load: () => import(${JSON.stringify(`/@fs${s.path}`)}) },`,
+        `  { name: ${JSON.stringify(s.name)}, dir: ${JSON.stringify(dirname(s.path))}, load: () => import(${JSON.stringify(`/@fs${s.path}`)}) },`,
     );
     return `export const userScenes = [\n${entries.join("\n")}\n];\n`;
   },
@@ -39,6 +39,7 @@ const userScenesPlugin: Plugin = {
 
 export default defineConfig({
   plugins: [userScenesPlugin],
+  define: { __REFRAME_EXAMPLES_DIR__: '""' }, // packaged preview ships no examples
   resolve: {
     alias: {
       "@reframe/core": resolve(PKG_ROOT, "dist", "index.js"),