reframe-video 0.6.18 → 0.6.20

package/dist/labels.js

@@ -678,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 Error(`failed to bundle ${path3}:
-${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(`${path3} 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(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];
@@ -721,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reframe-video",
-  "version": "0.6.18",
+  "version": "0.6.20",
   "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,13 +28,24 @@
     ".": {
       "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",
     "assets",
     "guides",
-    "preview"
+    "preview",
+    ".claude-plugin",
+    "skills"
   ],
   "engines": {
     "node": ">=20"

package/skills/reframe/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: reframe
+description: Create and iterate motion-graphics videos (mp4) — title cards, lower thirds, kinetic typography, product teasers, data-driven video batches. Use when the user asks to make, edit, retime, personalize, or add sound to an animated video. Scenes are declarative data; renders are deterministic; human edits survive regeneration.
+---
+
+# reframe — motion graphics as addressable data
+
+All commands run through npx; no install or project setup is needed. The
+runtime needs ffmpeg on PATH and a one-time `npx playwright install chromium`
+(the render command prints an actionable hint if either is missing).
+
+## Creating a scene
+
+1. **Read the guide first** — it is the complete, current syntax (~1,700
+   tokens) and one read is enough to write valid scenes:
+   `npx -y reframe-video guide`
+2. Write a single self-contained `<name>.ts` in the user's directory
+   (`npx -y reframe-video new <name>` scaffolds a documented starter).
+   Scenes must be pure functions of time: no `Math.random()`/`Date` — use
+   `wiggle` with a seed. Give every node a meaningful stable `id` and label
+   the key timeline moments — those names are addresses for everything below.
+3. Render and verify: `npx -y reframe-video render <name>.ts` → `out/<name>.mp4`.
+
+## Directing a high-end piece (cinematic / reference-faithful)
+
+Simple jobs (a lower-third, a logo sting, a KPI card) just work from the guide.
+But a CINEMATIC or REFERENCE-FAITHFUL piece (a product teaser, a UI/session
+reproduction, a title sequence) needs a director's process — **read it first**:
+`npx -y reframe-video guide --directing`. The short version:
+
+1. Get the spec from the user: concept, **references** (screenshots / a reference
+   video / pasted real content — save them to disk), exact brand colors, length +
+   aspect, and tone. Vague prompts are why these take many rounds.
+2. **Storyboard the beats** with `beat("setup"/"rising"/"climax"/…)` BEFORE animating.
+3. **Match references with the `diff` tool** instead of eyeballing:
+   `npx -y reframe-video diff ref.png --mode grid` (measure a screenshot),
+   then `... diff ref.png scene.ts --mode side|diff` (compare a render) → fix → repeat.
+4. Apply cinematic craft: camera push-in per beat (`cameraTo` in `par`), curved
+   entrances (`motionPath` + `easeOutBack`), fake/real depth, layered `oscillate`
+   idle, and label-anchored sound.
+5. **Verify objectively**: `... labels` (exact beat seconds), `... motion out.mp4`
+   (makes "more dynamic" measurable), `... trace ref.mp4 --apply scene.ts` (borrow a
+   reference VIDEO's timing), `... preview` (hand-tune → overlay that survives regen).
+
+## Modifying an existing scene — the contract
+
+Before rewriting any existing scene, read the regeneration contract:
+`npx -y reframe-video guide --regen`. The core rule: **never rename node ids,
+state names, or timeline labels for concepts that survive the redesign** —
+the user's overlay documents hold their hand edits at those addresses.
+
+The user may keep personal edits in an overlay JSON and render with
+`--overlay <file>`. Check the conversation for overlay usage. Two situations
+to handle explicitly:
+
+- After your rewrite, the render's compose report lists orphaned edits for
+  concepts that were genuinely removed — relay that report to the user; never
+  let an edit disappear silently.
+- If the user asks you to change a property their overlay already overrides,
+  editing the scene alone will be invisible in their renders. Resolve the
+  mask (update the scene AND remove/update the superseded overlay entry) and
+  tell them why.
+
+## Other capabilities
+
+- **Batch**: `npx -y reframe-video batch scene.ts data.json` — one mp4 per
+  data row; row keys are overlay addresses (`nodes.<id>.<prop>`,
+  `timeline.<label>.duration`, ...). CSV works too (headers = addresses).
+- **Preview editor**: `npx -y reframe-video preview` — scrub/play/knobs for
+  scenes in the current directory; the user's knob edits export as an overlay
+  JSON they can pass to render.
+- **Audio**: `scene.audio` cues anchor to timeline labels, so sound follows
+  retiming and regeneration. Procedural sfx (whoosh/pop/tick/rise/shimmer/
+  thud) plus bundled CC0 samples (mechanical keypresses, clicks). The guide's
+  Audio section has the schema.
+- **Motion check**: `npx -y reframe-video motion out/<name>.mp4` prints a
+  calibrated motion profile (speeds, static fraction, discontinuities) —
+  useful to verify a vague request like "make it more dynamic" objectively.
+- **Image sequences** (the "glyph reveal" / stop-motion format): generated
+  stills become `image` nodes stacked in painter's order; hard cuts are
+  0.01s opacity steps every ~0.15s, a slow camera-group scale tween adds the
+  push-in, `wiggle` adds shake, and a label per cut anchors a tick sfx.
+  Keep frame ids stable (`frame-0..N`) so the user can swap any plate via
+  overlay or batch row (`nodes.frame-3.src`). Image `src` paths resolve
+  relative to the scene file.
+
+## Verification habits
+
+Render after every change. For visual checks, extract a few frames with
+ffmpeg and look at them. Same input renders byte-identically, so "it changed"
+or "it didn't change" is always provable.