reframe-video 0.6.17 → 0.6.19

package/dist/compile.js

@@ -0,0 +1,477 @@
+#!/usr/bin/env tsx
+
+// ../render-cli/src/compile.ts
+import { writeFile } from "node:fs/promises";
+
+// ../render-cli/src/loadScene.ts
+import { build } from "esbuild";
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ../core/src/validate.ts
+var FX_PROPS = ["blur", "shadowColor", "shadowBlur", "shadowX", "shadowY", "blend"];
+var BLEND_MODES = /* @__PURE__ */ new Set([
+  "normal",
+  "multiply",
+  "screen",
+  "overlay",
+  "lighten",
+  "darken",
+  "add",
+  "color-dodge",
+  "soft-light",
+  "hard-light",
+  "difference"
+]);
+var IMAGE_FITS = /* @__PURE__ */ new Set(["fill", "cover"]);
+var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "z", "rotateX", "rotateY", "anchor", "fixed", ...FX_PROPS];
+var CAMERA_PROPS = ["x", "y", "zoom", "rotation", "perspective", "focus", "aperture"];
+var PROPS_BY_TYPE = {
+  rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
+  ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
+  line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress", ...FX_PROPS],
+  text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "prefix", "suffix", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
+  image: [...COMMON_PROPS, "src", "width", "height", "fit"],
+  video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume", "fadeIn", "pan"],
+  path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
+  group: COMMON_PROPS
+};
+var SceneValidationError = class extends Error {
+  constructor(problems) {
+    super(`Scene validation failed:
+${problems.map((p) => `  - ${p}`).join("\n")}`);
+    this.problems = problems;
+    this.name = "SceneValidationError";
+  }
+  problems;
+};
+function validateScene(ir) {
+  const problems = [];
+  const nodeById = /* @__PURE__ */ new Map();
+  const checkPaint = (where, value) => {
+    if (typeof value !== "object" || value === null) return;
+    const g = value;
+    if (g.kind !== "linear" && g.kind !== "radial" && g.kind !== "conic") {
+      problems.push(`${where}: a paint object must be a gradient with kind "linear" / "radial" / "conic"`);
+      return;
+    }
+    if (!Array.isArray(g.stops) || g.stops.length === 0) {
+      problems.push(`${where}: gradient "${g.kind}" needs at least one color stop`);
+      return;
+    }
+    g.stops.forEach((s, i) => {
+      const st = s;
+      if (typeof st?.color !== "string") problems.push(`${where}: gradient stop ${i} needs a color string`);
+      if (typeof st?.offset !== "number" || st.offset < 0 || st.offset > 1) {
+        problems.push(`${where}: gradient stop ${i} "offset" must be a number in 0..1`);
+      }
+    });
+  };
+  const collect = (nodes) => {
+    for (const node of nodes) {
+      if (nodeById.has(node.id)) {
+        problems.push(`duplicate node id "${node.id}" \u2014 every node id must be unique`);
+      }
+      nodeById.set(node.id, node);
+      const props = node.props;
+      checkPaint(`node "${node.id}" fill`, props.fill);
+      checkPaint(`node "${node.id}" stroke`, props.stroke);
+      if (typeof props.blur === "number" && props.blur < 0) problems.push(`node "${node.id}": blur must be >= 0`);
+      if (typeof props.shadowBlur === "number" && props.shadowBlur < 0) problems.push(`node "${node.id}": shadowBlur must be >= 0`);
+      if (typeof props.blend === "string" && !BLEND_MODES.has(props.blend)) problems.push(`node "${node.id}": unknown blend "${props.blend}" \u2014 use ${[...BLEND_MODES].join(", ")}`);
+      if (typeof props.fit === "string" && !IMAGE_FITS.has(props.fit)) problems.push(`node "${node.id}": unknown fit "${props.fit}" \u2014 use ${[...IMAGE_FITS].join(", ")}`);
+      if (node.type === "group") {
+        const clip = node.props.clip;
+        if (clip) {
+          if (clip.kind !== "rect" && clip.kind !== "ellipse") {
+            problems.push(`group "${node.id}" clip: unknown kind "${clip.kind}" \u2014 use "rect" or "ellipse"`);
+          }
+          if (!(clip.width > 0) || !(clip.height > 0)) {
+            problems.push(`group "${node.id}" clip: width and height must be > 0`);
+          }
+        }
+        const matte = node.props.matte;
+        if (matte !== void 0) {
+          if (matte !== "alpha" && matte !== "luma") {
+            problems.push(`group "${node.id}" matte: unknown mode "${String(matte)}" \u2014 use "alpha" or "luma"`);
+          } else if (node.children.length < 2) {
+            problems.push(`group "${node.id}" matte: needs \u22652 children (first masks the rest)`);
+          }
+        }
+        collect(node.children);
+      }
+    }
+  };
+  collect(ir.nodes);
+  const checkProps = (where, nodeId, props) => {
+    if (nodeId === "camera" && !nodeById.has("camera")) {
+      for (const key of Object.keys(props)) {
+        if (!CAMERA_PROPS.includes(key)) {
+          problems.push(`${where}: "${key}" is not a camera prop \u2014 valid props: ${CAMERA_PROPS.join(", ")}`);
+        }
+      }
+      return;
+    }
+    const node = nodeById.get(nodeId);
+    if (!node) {
+      problems.push(
+        `${where} targets unknown node "${nodeId}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
+      );
+      return;
+    }
+    const allowed = PROPS_BY_TYPE[node.type];
+    for (const key of Object.keys(props)) {
+      if (!allowed.includes(key)) {
+        problems.push(
+          `${where}: "${key}" is not a prop of ${node.type} "${nodeId}" \u2014 valid props: ${allowed.join(", ")}`
+        );
+      }
+    }
+  };
+  const states = ir.states ?? {};
+  for (const [stateName, overrides] of Object.entries(states)) {
+    for (const [nodeId, props] of Object.entries(overrides)) {
+      checkProps(`state "${stateName}"`, nodeId, props);
+    }
+  }
+  if (ir.initial !== void 0 && !(ir.initial in states)) {
+    problems.push(
+      `initial state "${ir.initial}" is not defined \u2014 defined states: ${Object.keys(states).join(", ") || "(none)"}`
+    );
+  }
+  const labels = /* @__PURE__ */ new Set();
+  const checkTimeline = (tl, path2) => {
+    if ("label" in tl && tl.label !== void 0) {
+      if (labels.has(tl.label)) {
+        problems.push(
+          `${path2}: duplicate timeline label "${tl.label}" \u2014 labels are overlay addresses and must be unique`
+        );
+      }
+      labels.add(tl.label);
+    }
+    switch (tl.kind) {
+      case "seq":
+      case "par":
+        tl.children.forEach((c, i) => checkTimeline(c, `${path2}.${tl.kind}[${i}]`));
+        break;
+      case "stagger":
+        if (tl.interval < 0) problems.push(`${path2}: stagger interval must be >= 0`);
+        tl.children.forEach((c, i) => checkTimeline(c, `${path2}.stagger[${i}]`));
+        break;
+      case "to":
+        if (!(tl.state in states)) {
+          problems.push(
+            `${path2}: to("${tl.state}") references an undefined state \u2014 defined states: ${Object.keys(states).join(", ") || "(none)"}`
+          );
+        }
+        if (tl.duration !== void 0 && tl.duration <= 0) {
+          problems.push(`${path2}: to("${tl.state}") duration must be > 0`);
+        }
+        for (const id of tl.filter ?? []) {
+          if (!nodeById.has(id)) problems.push(`${path2}: filter contains unknown node "${id}"`);
+        }
+        break;
+      case "tween":
+        checkProps(path2, tl.target, tl.props);
+        if (tl.duration !== void 0 && tl.duration <= 0) {
+          problems.push(`${path2}: tween duration must be > 0`);
+        }
+        break;
+      case "motionPath": {
+        const node = nodeById.get(tl.target);
+        const isSceneCamera = tl.target === "camera" && !node;
+        if (!isSceneCamera) {
+          if (!node) {
+            problems.push(
+              `${path2}: motionPath targets unknown node "${tl.target}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
+            );
+          } else if (node.type === "line") {
+            problems.push(`${path2}: motionPath cannot target a line (no x/y) \u2014 "${tl.target}"`);
+          }
+        }
+        if (tl.points.length < 1) problems.push(`${path2}: motionPath "${tl.target}" needs at least 1 point`);
+        if (tl.duration !== void 0 && tl.duration <= 0) {
+          problems.push(`${path2}: motionPath "${tl.target}" duration must be > 0`);
+        }
+        if (tl.curviness !== void 0 && tl.curviness < 0) {
+          problems.push(`${path2}: motionPath "${tl.target}" curviness must be >= 0`);
+        }
+        break;
+      }
+      case "wait":
+        if (tl.duration < 0) problems.push(`${path2}: wait duration must be >= 0`);
+        break;
+      case "beat":
+        if (labels.has(tl.name)) {
+          problems.push(
+            `${path2}: duplicate timeline label "${tl.name}" (beat name) \u2014 labels are overlay addresses and must be unique`
+          );
+        }
+        labels.add(tl.name);
+        if (tl.duration !== void 0 && tl.duration <= 0) {
+          problems.push(`${path2}: beat "${tl.name}" duration must be > 0`);
+        }
+        if (tl.scale !== void 0 && tl.scale <= 0) {
+          problems.push(`${path2}: beat "${tl.name}" scale must be > 0`);
+        }
+        for (const id of tl.nodes ?? []) {
+          if (!nodeById.has(id)) {
+            problems.push(
+              `${path2}: beat "${tl.name}" owns unknown node "${id}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
+            );
+          }
+        }
+        tl.children.forEach((c, i) => checkTimeline(c, `${path2}.beat(${tl.name})[${i}]`));
+        break;
+    }
+  };
+  if (ir.timeline) checkTimeline(ir.timeline, "timeline");
+  for (const [i, b] of (ir.behaviors ?? []).entries()) {
+    checkProps(`behaviors[${i}]`, b.target, { [b.prop]: 0 });
+  }
+  if (ir.duration !== void 0 && ir.duration <= 0) {
+    problems.push("scene duration must be > 0");
+  }
+  if (ir.camera) {
+    if (nodeById.has("camera")) {
+      problems.push(`camera: a node is already named "camera" \u2014 rename that node or drop the scene camera (the id "camera" can't be both)`);
+    }
+    for (const [key, value] of Object.entries(ir.camera)) {
+      if (key === "zSort") {
+        if (typeof value !== "boolean") problems.push(`camera.zSort must be a boolean`);
+      } else if (!CAMERA_PROPS.includes(key)) {
+        problems.push(`camera: "${key}" is not a camera prop \u2014 valid props: ${CAMERA_PROPS.join(", ")}, zSort`);
+      } else if (typeof value !== "number") {
+        problems.push(`camera.${key} must be a number`);
+      } else if (key === "perspective" && value <= 0) {
+        problems.push(`camera.perspective must be > 0 (focal distance in px) \u2014 drop it to disable perspective`);
+      } else if (key === "aperture" && value < 0) {
+        problems.push(`camera.aperture must be >= 0 (blur px per unit depth) \u2014 0 disables depth of field`);
+      }
+    }
+  }
+  const SFX_NAMES = ["whoosh", "pop", "tick", "rise", "shimmer", "thud"];
+  for (const [i, cue] of (ir.audio?.cues ?? []).entries()) {
+    if (typeof cue.at === "string" && !labels.has(cue.at)) {
+      problems.push(
+        `audio.cues[${i}]: unknown timeline label "${cue.at}" \u2014 known labels: ${[...labels].join(", ") || "(none)"}`
+      );
+    }
+    if (typeof cue.at === "number" && cue.at < 0) {
+      problems.push(`audio.cues[${i}]: "at" must be >= 0`);
+    }
+    if (cue.sfx === void 0 === (cue.file === void 0)) {
+      problems.push(`audio.cues[${i}]: exactly one of "sfx" or "file" is required`);
+    }
+    if (cue.sfx !== void 0 && !SFX_NAMES.includes(cue.sfx)) {
+      problems.push(`audio.cues[${i}]: unknown sfx "${cue.sfx}" \u2014 valid: ${SFX_NAMES.join(", ")}`);
+    }
+    if (cue.gain !== void 0 && cue.gain < 0) {
+      problems.push(`audio.cues[${i}]: gain must be >= 0`);
+    }
+    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)) {
+    problems.push("audio.bgm.duck.depth must be in [0, 1]");
+  }
+  if (ir.audio?.bgm?.file !== void 0 && ir.audio.bgm.synth !== void 0) {
+    problems.push('audio.bgm: use either "file" or "synth", not both');
+  }
+  if (problems.length > 0) throw new SceneValidationError(problems);
+}
+
+// ../core/src/presets.ts
+var SET = 1 / 120;
+
+// ../core/src/interpolate.ts
+var BACK_C1 = 1.70158;
+var BACK_C2 = BACK_C1 * 1.525;
+var BACK_C3 = BACK_C1 + 1;
+var ELASTIC_C4 = 2 * Math.PI / 3;
+var ELASTIC_C5 = 2 * Math.PI / 4.5;
+function springEase(stiffness, damping, velocity) {
+  const K = 5;
+  const zeta = Math.min(0.999, Math.max(0.05, damping / (2 * Math.sqrt(Math.max(1e-6, stiffness)))));
+  const wd = K / zeta * Math.sqrt(1 - zeta * zeta);
+  const coef = (K - velocity) / wd;
+  return (u) => {
+    if (u <= 0) return 0;
+    if (u >= 1) return 1;
+    return 1 - Math.exp(-K * u) * (Math.cos(wd * u) + coef * Math.sin(wd * u));
+  };
+}
+function easeOutBounce(u) {
+  const n1 = 7.5625;
+  const d1 = 2.75;
+  if (u < 1 / d1) return n1 * u * u;
+  if (u < 2 / d1) return n1 * (u -= 1.5 / d1) * u + 0.75;
+  if (u < 2.5 / d1) return n1 * (u -= 2.25 / d1) * u + 0.9375;
+  return n1 * (u -= 2.625 / d1) * u + 0.984375;
+}
+var EASE_TABLE = {
+  linear: (u) => u,
+  easeInQuad: (u) => u * u,
+  easeOutQuad: (u) => 1 - (1 - u) * (1 - u),
+  easeInOutQuad: (u) => u < 0.5 ? 2 * u * u : 1 - (-2 * u + 2) ** 2 / 2,
+  easeInCubic: (u) => u ** 3,
+  easeOutCubic: (u) => 1 - (1 - u) ** 3,
+  easeInOutCubic: (u) => u < 0.5 ? 4 * u ** 3 : 1 - (-2 * u + 2) ** 3 / 2,
+  easeInQuart: (u) => u ** 4,
+  easeOutQuart: (u) => 1 - (1 - u) ** 4,
+  easeInOutQuart: (u) => u < 0.5 ? 8 * u ** 4 : 1 - (-2 * u + 2) ** 4 / 2,
+  easeInExpo: (u) => u === 0 ? 0 : 2 ** (10 * u - 10),
+  easeOutExpo: (u) => u === 1 ? 1 : 1 - 2 ** (-10 * u),
+  easeInOutExpo: (u) => u === 0 ? 0 : u === 1 ? 1 : u < 0.5 ? 2 ** (20 * u - 10) / 2 : (2 - 2 ** (-20 * u + 10)) / 2,
+  // --- expressive eases (GSAP's signature feel) — standard Penner equations ---
+  // back: overshoots past the target then settles (pop / snap)
+  easeInBack: (u) => BACK_C3 * u ** 3 - BACK_C1 * u * u,
+  easeOutBack: (u) => 1 + BACK_C3 * (u - 1) ** 3 + BACK_C1 * (u - 1) ** 2,
+  easeInOutBack: (u) => u < 0.5 ? (2 * u) ** 2 * ((BACK_C2 + 1) * 2 * u - BACK_C2) / 2 : ((2 * u - 2) ** 2 * ((BACK_C2 + 1) * (2 * u - 2) + BACK_C2) + 2) / 2,
+  // elastic: rings around the target before settling (playful spring)
+  easeInElastic: (u) => u === 0 ? 0 : u === 1 ? 1 : -(2 ** (10 * u - 10)) * Math.sin((u * 10 - 10.75) * ELASTIC_C4),
+  easeOutElastic: (u) => u === 0 ? 0 : u === 1 ? 1 : 2 ** (-10 * u) * Math.sin((u * 10 - 0.75) * ELASTIC_C4) + 1,
+  easeInOutElastic: (u) => u === 0 ? 0 : u === 1 ? 1 : u < 0.5 ? -(2 ** (20 * u - 10) * Math.sin((20 * u - 11.125) * ELASTIC_C5)) / 2 : 2 ** (-20 * u + 10) * Math.sin((20 * u - 11.125) * ELASTIC_C5) / 2 + 1,
+  // bounce: drops and bounces to rest (lands without overshoot)
+  easeInBounce: (u) => 1 - easeOutBounce(1 - u),
+  easeOutBounce,
+  easeInOutBounce: (u) => u < 0.5 ? (1 - easeOutBounce(1 - 2 * u)) / 2 : (1 + easeOutBounce(2 * u - 1)) / 2,
+  // damped-spring presets (ζ from damping/(2√stiffness)): 0.5 / 0.30 / 0.90
+  spring: springEase(100, 10, 0),
+  springBouncy: springEase(180, 8, 0),
+  springStiff: springEase(210, 26, 0)
+};
+var EASE_NAMES = Object.keys(EASE_TABLE);
+
+// ../core/src/evaluate.ts
+var DEG = Math.PI / 180;
+
+// ../render-cli/src/loadScene.ts
+var HERE = dirname(fileURLToPath(import.meta.url));
+var CORE_ENTRY = true ? resolve(HERE, "index.js") : resolve(HERE, "..", "..", "core", "src", "index.ts");
+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(
+      "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) {
+    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 readFile(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 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>");
+}
+
+// ../render-cli/src/compile.ts
+var args = process.argv.slice(2);
+var flag = (n) => args.includes(n);
+var opt = (n) => {
+  const i = args.indexOf(n);
+  return i !== -1 ? args[i + 1] : void 0;
+};
+var jsonMode = flag("--json");
+async function readStdin() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8");
+}
+function withTimeout(p, ms) {
+  return Promise.race([
+    p,
+    new Promise((_, rej) => {
+      const t = setTimeout(() => rej(new SceneLoadError("eval", `compile timed out after ${ms}ms`)), ms);
+      t.unref();
+    })
+  ]);
+}
+async function main() {
+  const out = opt("-o");
+  const timeoutMs = Number(opt("--timeout") ?? 8e3);
+  const code = opt("--code");
+  const input = args.find((a, i) => !a.startsWith("-") && !["-o", "--code", "--timeout"].includes(args[i - 1] ?? ""));
+  const load = code !== void 0 ? loadSceneFromCode(code) : flag("--stdin") ? readStdin().then((src) => loadSceneFromCode(src)) : input ? loadScene(input) : Promise.reject(new SceneLoadError("eval", 'compile needs a scene file, --stdin, or --code "<src>"'));
+  const ir = await withTimeout(load, timeoutMs);
+  const text2 = JSON.stringify(ir);
+  if (out) await writeFile(out, `${text2}
+`);
+  else process.stdout.write(`${text2}
+`);
+}
+main().catch((err) => {
+  const kind = err instanceof SceneLoadError ? err.kind : "eval";
+  const message = err instanceof Error ? err.message : String(err);
+  if (jsonMode) process.stdout.write(`${JSON.stringify({ ok: false, error: message, kind })}
+`);
+  else console.error(`error: ${message}`);
+  process.exit(1);
+});

package/dist/diff.js

@@ -361,7 +361,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
 };
@@ -598,6 +598,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)) {
@@ -745,42 +754,84 @@ function collectVideoSrcs(ir) {
 // ../render-cli/src/loadScene.ts
 var HERE = dirname(fileURLToPath(import.meta.url));
 var CORE_ENTRY = true ? resolve(HERE, "index.js") : resolve(HERE, "..", "..", "core", "src", "index.ts");
-async function loadDefault(path2) {
-  if (path2.endsWith(".json")) return JSON.parse(await readFile(path2, "utf8"));
-  let code;
+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: [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 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 ${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 readFile(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/frameLoop.ts
@@ -1046,11 +1097,11 @@ async function renderFrameAt(ir, t, opts = {}) {
   const assets = await buildImageAssets(ir, sceneDir);
   const { fps, duration } = resolveTiming(ir, {});
   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]

package/dist/index.js

@@ -365,7 +365,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
 };
@@ -602,6 +602,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)) {
@@ -2690,7 +2699,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);
     }
@@ -2732,6 +2741,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 }
     });
   }
@@ -2809,6 +2821,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 }
     });
   }