reframe-video 0.6.17 → 0.6.19

package/dist/labels.js

@@ -349,7 +349,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
 };
@@ -586,6 +586,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)) {
@@ -669,42 +678,76 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 var HERE = dirname(fileURLToPath(import.meta.url));
 var CORE_ENTRY = true ? resolve(HERE, "index.js") : resolve(HERE, "..", "..", "core", "src", "index.ts");
-async function loadDefault(path3) {
-  if (path3.endsWith(".json")) return JSON.parse(await readFile(path3, "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 build({
-      entryPoints: [path3],
-      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 build(
+      "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 ${path3}:
-${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(`${path3} 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(path3) {
+  if (path3.endsWith(".json")) {
+    try {
+      return JSON.parse(await readFile(path3, "utf8"));
+    } catch (err) {
+      throw new SceneLoadError("eval", `failed to read ${path3}: ${clean(err)}`, { cause: err });
+    }
+  }
+  return importDefault(await bundle({ path: path3 }), path3);
+}
 function isComposition(def) {
   return typeof def === "object" && def !== null && Array.isArray(def.scenes);
 }
-async function loadScene(path3) {
-  const def = await loadDefault(path3);
+function asScene(def, label) {
   if (isComposition(def)) {
-    throw new Error(`${path3} 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(path3) {
+  return asScene(await loadDefault(path3), path3);
+}
 
 // ../render-cli/src/labels.ts
 var path2 = process.argv[2];
@@ -712,11 +755,17 @@ if (!path2) {
   console.error("usage: reframe labels <scene.ts|.json>");
   process.exit(1);
 }
-var scene = await loadScene(path2);
-var compiled = compileScene(scene);
-var rows = [...compiled.labelTimes.entries()].sort((a, b) => a[1].t0 - b[1].t0 || a[0].localeCompare(b[0]));
-console.log(`# ${scene.id} \u2014 ${rows.length} labels \xB7 ${compiled.duration.toFixed(2)}s @ ${scene.fps ?? 30}fps`);
-console.log(`# ${"start".padStart(7)}  ${"end".padStart(7)}  label`);
-for (const [name, { t0, t1 }] of rows) {
-  console.log(`${`${t0.toFixed(2)}s`.padStart(8)}  ${`${t1.toFixed(2)}s`.padStart(8)}  ${name}`);
+async function main() {
+  const scene = await loadScene(path2);
+  const compiled = compileScene(scene);
+  const rows = [...compiled.labelTimes.entries()].sort((a, b) => a[1].t0 - b[1].t0 || a[0].localeCompare(b[0]));
+  console.log(`# ${scene.id} \u2014 ${rows.length} labels \xB7 ${compiled.duration.toFixed(2)}s @ ${scene.fps ?? 30}fps`);
+  console.log(`# ${"start".padStart(7)}  ${"end".padStart(7)}  label`);
+  for (const [name, { t0, t1 }] of rows) {
+    console.log(`${`${t0.toFixed(2)}s`.padStart(8)}  ${`${t1.toFixed(2)}s`.padStart(8)}  ${name}`);
+  }
 }
+main().catch((err) => {
+  console.error(`error: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});

package/dist/renderer-canvas.d.ts

@@ -0,0 +1 @@
+export * from "./types-renderer/index.js";

package/dist/renderer-canvas.js

@@ -1,5 +1,5 @@
 // ../renderer-canvas/src/index.ts
-import { evaluate } from "@reframe/core";
+import { evaluate } from "reframe-video";
 function resolvePaint(ctx, paint, box) {
   if (typeof paint === "string") return paint;
   const { x, y, w, h } = box;

package/dist/trace-cli.js

@@ -14,7 +14,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
 };

package/dist/types/audio.d.ts

@@ -15,6 +15,12 @@ export interface ResolvedCue {
     t: number;
     gain: number;
     duration: number;
+    /** Fade in over N seconds from the cue start (0 = none). */
+    fadeIn: number;
+    /** Fade out over N seconds before the cue end (0 = none). */
+    fadeOut: number;
+    /** Stereo balance: -1 left … 0 centre … +1 right. */
+    pan: number;
     source: {
         kind: "sfx";
         name: SfxName;
@@ -36,6 +42,10 @@ export interface ClipAudio {
     clipStart: number;
     /** Linear gain. */
     gain: number;
+    /** Fade in over N seconds from the clip's `start` (0 = none). */
+    fadeIn: number;
+    /** Stereo balance: -1 left … 0 centre … +1 right. */
+    pan: number;
 }
 export interface AudioPlan {
     duration: number;

package/dist/types/ir.d.ts

@@ -256,6 +256,10 @@ export interface VideoProps extends BaseProps {
      * (trimmed from `clipStart`, sped by `rate`). Default 1; `0` mutes the clip.
      */
     volume?: number;
+    /** Fade the clip audio in over N seconds from `start` (default 0 = hard in). */
+    fadeIn?: number;
+    /** Stereo balance for the clip audio: -1 full left, 0 centre, +1 full right. */
+    pan?: number;
 }
 export type NodeIR = {
     type: "rect";
@@ -420,6 +424,12 @@ export interface AudioCueIR {
     file?: string;
     /** Linear gain, default 1. */
     gain?: number;
+    /** Fade the cue in over N seconds from its start (default 0 = hard in). */
+    fadeIn?: number;
+    /** Fade the cue out over N seconds before its end (default 0 = hard out). */
+    fadeOut?: number;
+    /** Stereo balance: -1 full left, 0 centre (default), +1 full right. */
+    pan?: number;
     /** Synth parameter overrides (seed, duration, …) — numbers only. */
     params?: Record<string, number>;
 }

package/dist/types-renderer/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * DisplayList -> Canvas 2D. Drawing only — all animation math lives in
+ * @reframe/core's evaluate(). Restricted to the plain Canvas 2D API so the
+ * same code runs in the browser (preview), under Playwright (export), and
+ * could port to skia-canvas later.
+ */
+import type { CompiledScene, DisplayList, SceneIR } from "../types/index.js";
+/**
+ * Decoded images keyed by the RAW src string from the IR (never a resolved
+ * path/URL — the DisplayList stays machine-independent). Consumers populate
+ * it before the first frame; a plain Map satisfies the interface.
+ */
+export interface ImageRegistry {
+    get(src: string): CanvasImageSource | undefined;
+}
+/**
+ * Decoded video frames keyed by the RAW src string + frame index. A video is
+ * rendered as a frame sequence (extracted at the scene fps): `frame(src, i)`
+ * returns the i-th source frame, clamped to the available range by the consumer.
+ */
+export interface VideoRegistry {
+    frame(src: string, index: number): CanvasImageSource | undefined;
+}
+export declare function renderFrame(ctx: CanvasRenderingContext2D, compiled: CompiledScene, t: number, images?: ImageRegistry, videos?: VideoRegistry): void;
+export declare function drawDisplayList(ctx: CanvasRenderingContext2D, ops: DisplayList, images?: ImageRegistry, videos?: VideoRegistry): void;
+/** Center cover-crop: the source rect (in image pixels) that fills a dw×dh box at
+ *  the image's natural aspect — the larger axis is cropped equally on both sides. */
+export declare function coverRect(iw: number, ih: number, dw: number, dh: number): {
+    sx: number;
+    sy: number;
+    sw: number;
+    sh: number;
+};
+export type { SceneIR };

package/guides/edsl-guide.md

@@ -510,15 +510,19 @@ Label-anchored sound design — cues follow retiming and regeneration:
 audio: {
   bgm: { synth: "ambient-pad", gain: 0.3, fadeIn: 1, fadeOut: 2, duck: { depth: 0.5 } },
   cues: [
-    { at: "enter", sfx: "whoosh", gain: 0.8 },          // anchored to a timeline label
-    { at: "enter", offset: 0.2, sfx: "pop" },
-    { at: 5.0, file: "keypress-001.wav", gain: 0.5 },   // absolute seconds; file from assets/sfx/
+    { at: "enter", sfx: "whoosh", gain: 0.8, pan: -0.6 },     // anchored to a label; panned left
+    { at: "enter", offset: 0.2, sfx: "pop", fadeIn: 0.05, fadeOut: 0.1 },
+    { at: 5.0, file: "keypress-001.wav", gain: 0.5 },         // absolute seconds; file from assets/sfx/
   ],
 }
 ```
 
 Procedural sfx names: `whoosh` `pop` `tick` `rise` `shimmer` `thud` (deterministic,
 seedable via `params: { seed }`). Exactly one of `sfx`/`file` per cue.
+**Mixing**: any cue takes `fadeIn`/`fadeOut` (seconds) and `pan` (-1 left … 0 centre …
++1 right). A `video` clip's audio takes `fadeIn` and `pan` too (clip fade-out isn't
+supported yet — a clip has no fixed length in the plan). The bed auto-ducks under cues
+(`bgm.duck`).
 
 ## Rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reframe-video",
-  "version": "0.6.17",
+  "version": "0.6.19",
   "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",
@@ -28,7 +28,16 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
-    }
+    },
+    "./renderer": {
+      "types": "./dist/renderer-canvas.d.ts",
+      "import": "./dist/renderer-canvas.js"
+    },
+    "./compile": {
+      "types": "./dist/compile-api.d.ts",
+      "import": "./dist/compile-api.js"
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",