reframe-video 0.1.0

package/guides/edsl-guide.md

@@ -0,0 +1,202 @@
+# reframe eDSL guide
+
+You write a motion-graphics scene as **declarative data** using the reframe
+TypeScript eDSL. Your output is a single `.ts` file that default-exports a
+`scene({...})` call. Everything imports from `@reframe/core`.
+
+```ts
+import { scene, group, rect, ellipse, line, text,
+         seq, par, stagger, to, tween, wait,
+         oscillate, wiggle } from "@reframe/core";
+
+export default scene({
+  id: "my-scene",
+  size: { width: 1920, height: 1080 },
+  fps: 30,
+  background: "#101014",
+  nodes: [/* ... */],
+  states: {/* ... */},
+  initial: "hidden",
+  timeline: seq(/* ... */),
+  behaviors: [/* optional */],
+});
+```
+
+## Nodes
+
+Factories return plain data. Every node needs a unique `id`.
+
+- `rect({ id, x, y, width, height, fill?, stroke?, strokeWidth?, radius?, opacity?, rotation?, scale?, anchor? })`
+- `ellipse({ id, x, y, width, height, fill?, stroke?, strokeWidth?, ... })`
+- `line({ id, x1, y1, x2, y2, stroke, strokeWidth?, opacity?, progress? })` —
+  `progress` 0..1 draws the line on (1 = full line).
+- `text({ id, x, y, content, contentDecimals?, fontFamily, fontSize, fontWeight?, fill?, letterSpacing?, ... })` —
+  `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`.
+- `group({ id, x, y, opacity?, rotation?, scale?, anchor? }, children)` — children's
+  coordinates are relative to the group; group opacity/transform multiply down.
+
+`anchor` controls placement and scale/rotation origin:
+`"top-left"` (default) | `"top-center"` | `"top-right"` | `"center-left"` |
+`"center"` | `"center-right"` | `"bottom-left"` | `"bottom-center"` | `"bottom-right"`.
+Example: a bar that grows upward = `anchor: "bottom-left"` + animate `height`.
+Font: use `fontFamily: "Inter"` (weights 400/700/800 are available).
+
+## States: declare looks, not motion
+
+Base props on nodes describe the **finished design**. A state is a sparse
+override — only the props that differ:
+
+```ts
+states: {
+  hidden: { title: { opacity: 0, y: 560 }, bar: { height: 0 } },
+  shown:  { title: { opacity: 1, y: 540 }, bar: { height: 300 } },
+},
+initial: "hidden",
+```
+
+`to("shown", { duration, ease, stagger?, filter? })` synthesizes a transition
+from each node's *current* value to the state's value. `stagger: 0.1` offsets
+the affected nodes 0.1s apart in declaration order. `filter: ["a", "b"]`
+restricts the transition to those nodes. States are plain objects — generate
+them with normal TS (`Object.fromEntries`, `.map`) for data-driven scenes.
+
+## Timeline: compose time
+
+- `seq(...steps)` — one after another.
+- `par(...steps)` — all start together; ends when the longest ends.
+- `stagger(interval, ...steps)` — like `par` but each child starts `interval` later.
+- `to(stateName, opts)` — transition into a named state (see above).
+- `tween(nodeId, { prop: value, ... }, { duration, ease })` — low-level escape hatch
+  for one node. Colors (`"#rrggbb"`) interpolate; numbers interpolate.
+- `wait(seconds)` — hold.
+
+Eases: `linear`, `easeIn/Out/InOutQuad`, `easeIn/Out/InOutCubic`,
+`easeIn/Out/InOutQuart`, `easeIn/Out/InOutExpo`, or `{ cubicBezier: [x1,y1,x2,y2] }`.
+Decelerating entrances = `easeOut*`, accelerating exits = `easeIn*`.
+Scene duration is inferred from the timeline.
+
+## Behaviors: continuous motion during holds
+
+Composed additively on top of the timeline:
+
+- `oscillate(nodeId, prop, { amplitude, frequency, phase? }, window?)` — sine.
+- `wiggle(nodeId, prop, { amplitude, frequency, seed }, window?)` — smooth seeded noise.
+
+The optional 4th argument `{ from?, until?, ramp? }` limits the behavior to a
+time window (seconds) with a linear fade of `ramp` (default 0.2s) at each
+bound — e.g. a pulse only during the hold:
+`oscillate("title", "scale", { amplitude: 0.04, frequency: 1.2 }, { from: 1.5, until: 3.5 })`.
+Omit the window to run for the whole scene.
+
+## Audio (optional)
+
+Label-anchored sound design — cues follow retiming and regeneration:
+
+```ts
+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/
+  ],
+}
+```
+
+Procedural sfx names: `whoosh` `pop` `tick` `rise` `shimmer` `thud` (deterministic,
+seedable via `params: { seed }`). Exactly one of `sfx`/`file` per cue.
+
+## Rules
+
+- Everything must be a pure function of time: no `Math.random()` (use `wiggle`
+  with a seed), no `Date`, no async.
+- Node ids must be unique; states/tweens may only reference existing ids and
+  real props of that node type.
+- Overshoot pops are two steps: tween scale past 1 (`1.15`), then settle to 1.
+- When a node enters by scaling from 0, start it at `opacity: 0` too and fade
+  in alongside — a scale-0 shape can still rasterize as a 1px dot at frame 0.
+
+## Worked example A — countdown (3, 2, 1, GO!)
+
+```ts
+import { scene, ellipse, text, seq, par, tween, wait } from "@reframe/core";
+
+const numbers = ["3", "2", "1"];
+
+export default scene({
+  id: "countdown",
+  size: { width: 1920, height: 1080 },
+  fps: 30,
+  background: "#101014",
+  nodes: [
+    ellipse({ id: "ring", x: 960, y: 540, width: 360, height: 360,
+      anchor: "center", stroke: "#3B82F6", strokeWidth: 10, opacity: 0 }),
+    ...numbers.map((n, i) =>
+      text({ id: `num-${i}`, x: 960, y: 540, anchor: "center", content: n,
+        fontFamily: "Inter", fontSize: 220, fontWeight: 800, fill: "#FFFFFF",
+        opacity: 0, scale: 0.5 })),
+    text({ id: "go", x: 960, y: 540, anchor: "center", content: "GO!",
+      fontFamily: "Inter", fontSize: 320, fontWeight: 800, fill: "#FF4D00",
+      opacity: 0, scale: 0.5 }),
+  ],
+  timeline: seq(
+    tween("ring", { opacity: 1 }, { duration: 0.3, ease: "easeOutCubic" }),
+    ...numbers.map((_, i) =>
+      seq(
+        par(
+          tween(`num-${i}`, { opacity: 1 }, { duration: 0.15, ease: "easeOutQuad" }),
+          tween(`num-${i}`, { scale: 1.1 }, { duration: 0.2, ease: "easeOutCubic" }),
+        ),
+        tween(`num-${i}`, { scale: 1 }, { duration: 0.1, ease: "easeInOutQuad" }),
+        wait(0.45),
+        tween(`num-${i}`, { opacity: 0, scale: 0.7 }, { duration: 0.1, ease: "easeInQuad" }),
+      )),
+    par(
+      tween("go", { opacity: 1 }, { duration: 0.15, ease: "easeOutQuad" }),
+      tween("go", { scale: 1.15 }, { duration: 0.25, ease: "easeOutCubic" }),
+      tween("ring", { scale: 1.6, opacity: 0 }, { duration: 0.4, ease: "easeOutCubic" }),
+    ),
+    tween("go", { scale: 1 }, { duration: 0.15, ease: "easeInOutQuad" }),
+    wait(0.6),
+  ),
+});
+```
+
+## Worked example B — badge pop (overshoot + wiggle + drop)
+
+```ts
+import { scene, group, rect, text, seq, par, tween, wait, oscillate } from "@reframe/core";
+
+export default scene({
+  id: "badge-pop",
+  size: { width: 1920, height: 1080 },
+  fps: 30,
+  background: "#15151A",
+  nodes: [
+    group({ id: "badge", x: 960, y: 540, scale: 0, opacity: 0 }, [
+      rect({ id: "plate", x: 0, y: 0, width: 420, height: 160,
+        anchor: "center", fill: "#E11D48", radius: 28 }),
+      text({ id: "label", x: 0, y: 6, anchor: "center", content: "NEW",
+        fontFamily: "Inter", fontSize: 88, fontWeight: 800, fill: "#FFFFFF",
+        letterSpacing: 6 }),
+    ]),
+  ],
+  timeline: seq(
+    wait(0.2),
+    par(
+      tween("badge", { opacity: 1 }, { duration: 0.15, ease: "easeOutQuad" }),
+      tween("badge", { scale: 1.18 }, { duration: 0.28, ease: "easeOutCubic" }),
+    ),
+    tween("badge", { scale: 1 }, { duration: 0.18, ease: "easeInOutQuad" }),
+    wait(1.6),
+    par(
+      tween("badge", { y: 720 }, { duration: 0.35, ease: "easeInCubic" }),
+      tween("badge", { opacity: 0 }, { duration: 0.35, ease: "easeInQuad" }),
+    ),
+    wait(0.2),
+  ),
+  behaviors: [oscillate("badge", "rotation", { amplitude: 2.5, frequency: 0.8 })],
+});
+```

package/guides/regen-contract.md

@@ -0,0 +1,18 @@
+# Regeneration contract
+
+Overlay documents address nodes by `id` and states by name. For human edits to
+survive an AI regeneration of the base scene, the regeneration prompt must
+include the contract below, alongside the current scene IR (JSON or eDSL
+source):
+
+> You are regenerating an existing reframe scene. The current scene is
+> provided. You may change layout, timing, styling, and add new nodes freely —
+> but for every node whose concept survives your redesign, you MUST keep its
+> `id` unchanged, and you MUST keep state names unchanged. The same applies to
+> timeline step `label`s. Node ids, state names, and timeline labels are
+> stable addresses that external edit layers reference; renaming one silently
+> orphans a human's edit.
+
+When the contract is broken anyway, `composeScene` skips the affected edits
+and reports them as orphans with the known-ids list — loud, diagnosable,
+never a silent drop and never a render failure.

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "reframe-video",
+  "version": "0.1.0",
+  "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",
+    "video",
+    "animation",
+    "generative",
+    "ai",
+    "deterministic",
+    "claude",
+    "ffmpeg"
+  ],
+  "license": "MIT",
+  "author": "Kiyeon Jeon",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kiyeonjeon21/reframe.git"
+  },
+  "homepage": "https://github.com/kiyeonjeon21/reframe#readme",
+  "type": "module",
+  "bin": {
+    "reframe": "./dist/bin.js",
+    "reframe-video": "./dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "assets",
+    "guides",
+    "preview"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsx scripts/build.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "esbuild": "^0.27.0",
+    "playwright": "^1.60.0",
+    "vite": "^6.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0"
+  }
+}

package/preview/index.html

@@ -0,0 +1,60 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8" />
+<title>reframe preview</title>
+<style>
+  @font-face { font-family: "Inter"; font-weight: 400; src: url("../assets/fonts/inter-400.woff2") format("woff2"); }
+  @font-face { font-family: "Inter"; font-weight: 700; src: url("../assets/fonts/inter-700.woff2") format("woff2"); }
+  @font-face { font-family: "Inter"; font-weight: 800; src: url("../assets/fonts/inter-800.woff2") format("woff2"); }
+  body { margin: 0; background: #1b1b20; color: #ddd; font: 13px system-ui; display: flex; flex-direction: column; height: 100vh; }
+  #content { flex: 1; display: flex; min-height: 0; }
+  #stage-wrap { flex: 1; display: flex; align-items: center; justify-content: center; min-width: 0; padding: 16px; }
+  canvas { max-width: 100%; max-height: 100%; box-shadow: 0 4px 32px rgba(0,0,0,.5); }
+  #bar { display: flex; gap: 12px; align-items: center; padding: 12px 16px; background: #232329; }
+  #scrub { flex: 1; }
+  select, button, input[type=text], input[type=number] { background: #2e2e36; color: #ddd; border: 1px solid #444; border-radius: 4px; padding: 3px 8px; font: 12px system-ui; }
+  input[type=number] { width: 64px; }
+  input[type=color] { width: 40px; height: 22px; padding: 0; border: 1px solid #444; background: none; }
+  #time { font-variant-numeric: tabular-nums; min-width: 96px; text-align: right; }
+
+  /* inspector */
+  #panel { width: 320px; overflow-y: auto; background: #202026; border-left: 1px solid #333; padding: 10px 12px 24px; }
+  #panel h3 { font-size: 11px; text-transform: uppercase; letter-spacing: 1px; color: #8a8a96; margin: 16px 0 6px; }
+  .tree-item { padding: 2px 6px; border-radius: 4px; cursor: pointer; display: flex; justify-content: space-between; }
+  .tree-item:hover { background: #2a2a32; }
+  .tree-item.selected { background: #31313c; color: #fff; }
+  .badge { color: #ffb454; font-size: 11px; }
+  .prop-row { display: flex; align-items: center; gap: 6px; margin: 3px 0; }
+  .prop-row label { flex: 1; color: #aab; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .prop-row label .scope { color: #7d9aff; }
+  .prop-row.edited input, .prop-row.edited select { border-color: #ffb454; }
+  .prop-row.dead { opacity: 0.45; }
+  .hint { font-size: 11px; color: #777; margin: -2px 0 4px; }
+  .revert { background: none; border: none; color: #888; cursor: pointer; padding: 0 2px; }
+  .revert:hover { color: #ff6b6b; }
+  .step-card, .behavior-card { background: #26262d; border-radius: 6px; padding: 6px 8px; margin: 6px 0; }
+  .step-card .kind { color: #8a8a96; font-size: 11px; }
+  #report { font-size: 12px; }
+  #report .orphan { color: #ff7b72; margin: 2px 0; }
+  #report .warning { color: #ffb454; margin: 2px 0; }
+  #report .error { color: #ff7b72; background: #3a2226; border-radius: 4px; padding: 6px; margin: 4px 0; white-space: pre-wrap; }
+  #report details { color: #8a8a96; }
+  #io { display: flex; gap: 6px; flex-wrap: wrap; margin-top: 8px; }
+  #overlay-name { width: 100%; margin-bottom: 6px; box-sizing: border-box; }
+</style>
+</head>
+<body>
+  <div id="content">
+    <div id="stage-wrap"><canvas id="canvas"></canvas></div>
+    <div id="panel"></div>
+  </div>
+  <div id="bar">
+    <select id="scene-select"></select>
+    <button id="play">play</button>
+    <input id="scrub" type="range" min="0" max="1" step="0.001" value="0" />
+    <span id="time">0.000 / 0.000</span>
+  </div>
+  <script type="module" src="/src/main.ts"></script>
+</body>
+</html>

package/preview/src/main.ts

@@ -0,0 +1,162 @@
+/**
+ * Preview + editor shell: scene picker, scrub/play, canvas, selection
+ * highlight. Edits live in EditorStore as an OverlayDoc draft; everything
+ * here only reads store.compiled. rAF lives ONLY in this file — the export
+ * path never uses wall-clock time.
+ */
+
+import { 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";
+import { EditorStore } from "./store.js";
+
+interface SceneEntry {
+  label: 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]! };
+}
+// scenes from the directory `reframe preview` was invoked in
+for (const { name, load } of userScenes) {
+  modules[`user:${name}`] ??= { label: `${name} (cwd)`, load };
+}
+
+const canvas = document.getElementById("canvas") as HTMLCanvasElement;
+const ctx = canvas.getContext("2d")!;
+const select = document.getElementById("scene-select") as HTMLSelectElement;
+const playBtn = document.getElementById("play") as HTMLButtonElement;
+const scrub = document.getElementById("scrub") as HTMLInputElement;
+const timeLabel = document.getElementById("time") as HTMLSpanElement;
+const panelRoot = document.getElementById("panel") as HTMLDivElement;
+
+let store: EditorStore | null = null;
+let panel: ReturnType<typeof buildPanel> | null = null;
+let t = 0;
+let playing = false;
+let lastTick = 0;
+
+for (const [key, entry] of Object.entries(modules)) {
+  const option = document.createElement("option");
+  option.value = key;
+  option.textContent = entry.label;
+  select.appendChild(option);
+}
+
+async function loadScene(path: string) {
+  const mod = await modules[path]!.load();
+  store = new EditorStore(mod.default);
+  (window as unknown as { __store: EditorStore }).__store = store; // debug/testing hook
+  panel = buildPanel(store, panelRoot);
+  canvas.width = store.compiled.ir.size.width;
+  canvas.height = store.compiled.ir.size.height;
+  store.subscribe((kind) => {
+    t = Math.min(t, store!.compiled.duration);
+    if (kind === "structure") panel!.rebuild();
+    else panel!.refreshReport();
+    draw();
+  });
+  await document.fonts.ready;
+  t = 0;
+  panel.rebuild();
+  draw();
+}
+
+function applyMat(m: number[], x: number, y: number): [number, number] {
+  return [m[0]! * x + m[2]! * y + m[4]!, m[1]! * x + m[3]! * y + m[5]!];
+}
+
+function opCorners(op: DisplayOp): [number, number][] {
+  switch (op.type) {
+    case "rect":
+    case "ellipse": {
+      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!),
+      );
+    }
+    case "line":
+      return [applyMat(op.transform, op.x1, op.y1), applyMat(op.transform, op.x2, op.y2)];
+    case "text": {
+      ctx.font = `${op.fontWeight} ${op.fontSize}px ${op.fontFamily}`;
+      const w = ctx.measureText(op.content).width;
+      const h = op.fontSize * 1.2;
+      const x0 = op.align === "right" ? -w : op.align === "center" ? -w / 2 : 0;
+      const y0 = op.baseline === "bottom" ? -h : op.baseline === "middle" ? -h / 2 : 0;
+      return [[x0, y0], [x0 + w, y0], [x0 + w, y0 + h], [x0, y0 + h]].map(([px, py]) =>
+        applyMat(op.transform, px!, py!),
+      );
+    }
+  }
+}
+
+function draw() {
+  if (!store) return;
+  renderFrame(ctx, store.compiled, t);
+
+  if (store.selectedId) {
+    const ops = evaluate(store.compiled, t).filter((op) => op.id === store!.selectedId);
+    ctx.save();
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.strokeStyle = "#7d9aff";
+    ctx.lineWidth = 2;
+    ctx.setLineDash([6, 4]);
+    for (const op of ops) {
+      const corners = opCorners(op);
+      ctx.beginPath();
+      corners.forEach(([x, y], i) => (i === 0 ? ctx.moveTo(x, y) : ctx.lineTo(x, y)));
+      if (corners.length > 2) ctx.closePath();
+      ctx.stroke();
+    }
+    ctx.restore();
+  }
+
+  const duration = store.compiled.duration;
+  scrub.value = String(duration ? t / duration : 0);
+  timeLabel.textContent = `${t.toFixed(3)} / ${duration.toFixed(3)}`;
+}
+
+function tick(now: number) {
+  if (playing && store) {
+    t += (now - lastTick) / 1000;
+    if (t > store.compiled.duration) t = 0; // loop
+    draw();
+  }
+  lastTick = now;
+  requestAnimationFrame(tick);
+}
+requestAnimationFrame(tick);
+
+playBtn.addEventListener("click", () => {
+  playing = !playing;
+  playBtn.textContent = playing ? "pause" : "play";
+});
+
+scrub.addEventListener("input", () => {
+  if (!store) return;
+  playing = false;
+  playBtn.textContent = "play";
+  t = Number(scrub.value) * store.compiled.duration;
+  draw();
+});
+
+let currentPath = "";
+select.addEventListener("change", () => {
+  if (store?.dirty && !confirm("Discard unsaved overlay edits?")) {
+    select.value = currentPath;
+    return;
+  }
+  currentPath = select.value;
+  void loadScene(select.value);
+});
+if (Object.keys(modules).length === 0) {
+  panelRoot.innerHTML =
+    "<p style='padding:12px;color:#aab'>No scenes found. Scaffold one in this directory with <code>reframe new my-scene</code>, then reload.</p>";
+} else {
+  currentPath = select.value || Object.keys(modules)[0]!;
+  void loadScene(currentPath);
+}