reframe-video 0.6.20 → 0.6.22

package/.claude-plugin/marketplace.json

@@ -1,5 +1,5 @@
 {
-  "name": "reframe",
+  "name": "kiyeonjeon21",
   "owner": {
     "name": "Kiyeon Jeon",
     "url": "https://github.com/kiyeonjeon21"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "reframe",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Create and iterate motion-graphics videos as addressable data: deterministic mp4 renders, human edits that survive AI regeneration, label-anchored audio, data-driven batch rendering.",
   "author": {
     "name": "Kiyeon Jeon",

package/dist/bin.js

@@ -2804,6 +2804,17 @@ var PLAYER = PACKAGED ? join9(ROOT2, "dist", "player.js") : join9(ROOT2, "packag
 var ANALYZE = PACKAGED ? join9(ROOT2, "dist", "analyze.js") : join9(ROOT2, "benchmark", "harness", "motion", "analyze.ts");
 var TRACE = PACKAGED ? join9(ROOT2, "dist", "trace-cli.js") : join9(ROOT2, "benchmark", "harness", "motion", "trace-cli.ts");
 var CMD = PACKAGED ? "reframe" : "pnpm reframe";
+var GUIDE = PACKAGED ? {
+  regen: join9(ROOT2, "guides", "regen-contract.md"),
+  directing: join9(ROOT2, "guides", "directing-guide.md"),
+  html: join9(ROOT2, "guides", "html-guide.md"),
+  edsl: join9(ROOT2, "guides", "edsl-guide.md")
+} : {
+  regen: join9(ROOT2, "docs", "regen-contract.md"),
+  directing: join9(ROOT2, "docs", "guides", "directing-guide.md"),
+  html: join9(ROOT2, "docs", "guides", "html-guide.md"),
+  edsl: join9(ROOT2, "docs", "guides", "edsl-guide.md")
+};
 var USAGE = `reframe \u2014 declarative motion graphics
 
 usage:
@@ -2824,7 +2835,7 @@ usage:
   ${CMD} motion <mp4|framesDir>  motion-profile a rendered clip
   ${CMD} trace <ref.mp4> [--apply scene.ts]  extract a video's motion structure \u2192 MotionSketch / timeline
   ${CMD} diff <ref-image> [<scene.ts>] [--t S] [--mode side|blend|diff|grid]  compare/measure a render against a reference image
-  ${CMD} guide [--regen|--directing]  print a guide (--regen: stable-address contract; --directing: high-end workflow)
+  ${CMD} guide [--directing|--regen|--html]  print a guide (default: eDSL syntax; --directing: high-end workflow; --regen: stable-address contract; --html: HTML/GSAP scenes)
   ${CMD} demo                    run the edit-survival demo (3 mp4s into out/)
 `;
 var userPath = (p) => isAbsolute5(p) ? p : resolve6(USER_CWD, p);
@@ -3185,10 +3196,9 @@ ${results.length - failed} rendered (${orphaned} with orphans), ${failed} failed
       );
     }
     case "guide": {
-      const which = rest.includes("--regen") ? "regen" : rest.includes("--directing") ? "directing" : "edsl";
-      const repoFile = { regen: join9(ROOT2, "docs", "regen-contract.md"), directing: join9(ROOT2, "benchmark", "guides", "directing-guide.md"), edsl: join9(ROOT2, "benchmark", "guides", "edsl-guide.md") };
-      const pkgFile = { regen: join9(ROOT2, "guides", "regen-contract.md"), directing: join9(ROOT2, "guides", "directing-guide.md"), edsl: join9(ROOT2, "guides", "edsl-guide.md") };
-      const file = (PACKAGED ? pkgFile : repoFile)[which];
+      const which = rest.includes("--regen") ? "regen" : rest.includes("--directing") ? "directing" : rest.includes("--html") ? "html" : "edsl";
+      const file = GUIDE[which];
+      if (!existsSync6(file)) fail(`guide not found: ${file}`);
       const { readFile: readFile7 } = await import("node:fs/promises");
       process.stdout.write(await readFile7(file, "utf8"));
       return;

package/guides/directing-guide.md

@@ -74,6 +74,11 @@ flagship scenes — reuse the technique, vary the content:
 
 ### 4. Verify objectively (don't argue about "more dynamic")
 
+Mind the tiers so you're not full-rendering to check small things: `compile`
+(validate eDSL → IR, ~1s) and `labels` are cheap, no render; `frame --t <sec>`
+is the cheap visual look (one PNG, ~1s); `motion`/`trace` below need a finished
+render or reference video, so they're end-stage measurement, not the per-edit loop.
+
 - `reframe labels scene.ts` — every label → exact seconds. The timing source for audio + a
   sanity check that beats land when you think.
 - `reframe motion out.mp4` — speeds, static fraction, oscillation rhythm, spikes. A vague
@@ -97,5 +102,6 @@ addresses), so the human's polish isn't lost when you redo the base.
   matching with `diff` before adding motion.
 - Keep `id`s/labels stable across rewrites (see `reframe guide --regen`) so the user's
   overlay edits survive.
-- It's still iterative. The tools cut the rounds; they don't remove the loop. Render, look,
-  adjust — the agent should render frames and read them, not guess.
+- It's still iterative. The tools cut the rounds; they don't remove the loop. `compile` to
+  validate (~1s), `frame --t <sec>` to look at a held moment (~1s), adjust — the agent should
+  read frames, not guess. Full `render` is the last step, not the per-edit check.

package/guides/html-guide.md

@@ -0,0 +1,180 @@
+# HTML + GSAP motion guide
+
+You write a motion-graphics scene as a **single self-contained `.html` file**
+using HTML, CSS, and GSAP. The page is rendered to video frame-by-frame by a
+deterministic capture harness.
+
+## Required structure
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8" />
+<style>
+  body { margin: 0; }
+  #stage {
+    position: relative; width: 1920px; height: 1080px;
+    background: #101014; overflow: hidden;
+    font-family: Inter, sans-serif;
+  }
+  /* static styling for your elements */
+</style>
+</head>
+<body>
+<div id="stage">
+  <!-- your elements -->
+</div>
+<script src="./gsap.min.js"></script>
+<script>
+  // your animation code
+</script>
+</body>
+</html>
+```
+
+- The video frame is exactly the `#stage` element — keep it `1920px × 1080px`
+  with `overflow: hidden`, and put everything inside it.
+- GSAP 3 is available locally at `./gsap.min.js` (already next to your file).
+  Do not load anything else from the network — no CDNs, no images, no iframes.
+- Font: use `font-family: Inter` (weights 400/700/800 are pre-installed by the
+  harness; no @font-face needed). Fallback `sans-serif`.
+
+## Animation rules (important)
+
+The harness virtualizes time: `requestAnimationFrame`, `setTimeout`,
+`setInterval`, `performance.now()` and `Date.now()` all follow a virtual
+clock, so GSAP timelines and hand-rolled rAF loops are captured exactly.
+
+- **All motion must be driven by GSAP or JavaScript.** CSS `animation`,
+  CSS `transition`, and SMIL run on the compositor clock and will NOT be
+  captured — a scene that relies on them renders as a frozen frame.
+  Static CSS styling (layout, colors, border-radius, flex...) is fine.
+- No `Math.random()` unless seeded yourself deterministically; no `<video>`;
+  no user interaction. The page must play by itself from t=0.
+- Match the brief's total duration: time your timeline so the action completes
+  within it (trailing hold is fine).
+
+## GSAP quick reference
+
+```js
+const tl = gsap.timeline({ delay: 0.2 });
+tl.to("#el", { x: 300, opacity: 1, duration: 0.5, ease: "power2.out" })
+  .fromTo("#el2", { scale: 0.5 }, { scale: 1.1, duration: 0.2, ease: "power2.out" })
+  .to("#el2", { scale: 1, duration: 0.1, ease: "power1.inOut" })   // settle
+  .to("#el3", { y: -40, duration: 0.3 }, "<")      // "<" = start with previous
+  .to("#el4", { opacity: 0, duration: 0.3 }, "+=1.5"); // "+=" = gap after previous
+
+gsap.to(".items", { opacity: 1, stagger: 0.1, duration: 0.4 }); // staggered
+gsap.to("#el", { rotation: 3, yoyo: true, repeat: -1, duration: 0.6,
+                 ease: "sine.inOut" }); // continuous wiggle during holds
+```
+
+Eases: `power1/2/3/4.out` (decelerate — entrances), `.in` (accelerate — exits),
+`.inOut`, `sine.inOut`, `back.out(1.7)` (overshoot), `expo.out`.
+Position params: `"<"` start with previous, `"+=0.5"` gap, absolute `1.2`.
+
+Useful patterns:
+
+```js
+// Count-up number label
+const counter = { value: 0 };
+gsap.to(counter, { value: 14.0, duration: 1, ease: "power2.out",
+  onUpdate: () => { el.textContent = counter.value.toFixed(1); } });
+
+// Center an element at a point (so scale/rotation pivot around its center)
+// CSS: position:absolute; left:960px; top:540px; transform:translate(-50%,-50%)
+// Then animate with xPercent/yPercent preserved:
+gsap.fromTo("#el", { xPercent: -50, yPercent: -50, scale: 0.5 },
+                   { xPercent: -50, yPercent: -50, scale: 1, duration: 0.3 });
+
+// Grow a bar upward: anchor it with bottom CSS, animate height
+gsap.fromTo("#bar", { height: 0 }, { height: 320, duration: 0.7, ease: "power3.out" });
+```
+
+## Worked example A — countdown (3, 2, 1, GO!)
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8" />
+<style>
+  body { margin: 0; }
+  #stage { position: relative; width: 1920px; height: 1080px;
+    background: #101014; overflow: hidden; font-family: Inter, sans-serif; }
+  #ring { position: absolute; left: 960px; top: 540px;
+    width: 360px; height: 360px; margin: -180px 0 0 -180px;
+    border: 10px solid #3B82F6; border-radius: 50%; opacity: 0; }
+  .num, #go { position: absolute; left: 960px; top: 540px;
+    transform: translate(-50%, -50%); font-weight: 800; color: #fff; opacity: 0; }
+  .num { font-size: 220px; }
+  #go { font-size: 320px; color: #FF4D00; }
+</style>
+</head>
+<body>
+<div id="stage">
+  <div id="ring"></div>
+  <div class="num" id="num-3">3</div>
+  <div class="num" id="num-2">2</div>
+  <div class="num" id="num-1">1</div>
+  <div id="go">GO!</div>
+</div>
+<script src="./gsap.min.js"></script>
+<script>
+  const tl = gsap.timeline();
+  tl.to("#ring", { opacity: 1, duration: 0.3, ease: "power2.out" });
+  for (const n of ["3", "2", "1"]) {
+    tl.fromTo(`#num-${n}`,
+      { opacity: 0, scale: 0.5 },
+      { opacity: 1, scale: 1.1, duration: 0.2, ease: "power2.out" })
+      .to(`#num-${n}`, { scale: 1, duration: 0.1, ease: "power1.inOut" })
+      .to(`#num-${n}`, { opacity: 0, scale: 0.7, duration: 0.1, ease: "power1.in" }, "+=0.45");
+  }
+  tl.fromTo("#go",
+    { opacity: 0, scale: 0.5 },
+    { opacity: 1, scale: 1.15, duration: 0.25, ease: "power2.out" })
+    .to("#ring", { scale: 1.6, opacity: 0, duration: 0.4, ease: "power2.out" }, "<")
+    .to("#go", { scale: 1, duration: 0.15, ease: "power1.inOut" });
+</script>
+</body>
+</html>
+```
+
+## Worked example B — badge pop (overshoot + wiggle + drop)
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8" />
+<style>
+  body { margin: 0; }
+  #stage { position: relative; width: 1920px; height: 1080px;
+    background: #15151A; overflow: hidden; font-family: Inter, sans-serif; }
+  #badge { position: absolute; left: 960px; top: 540px;
+    width: 420px; height: 160px; margin: -80px 0 0 -210px;
+    background: #E11D48; border-radius: 28px;
+    display: flex; align-items: center; justify-content: center;
+    opacity: 0; transform: scale(0); }
+  #badge span { color: #fff; font-size: 88px; font-weight: 800; letter-spacing: 6px; }
+</style>
+</head>
+<body>
+<div id="stage">
+  <div id="badge"><span>NEW</span></div>
+</div>
+<script src="./gsap.min.js"></script>
+<script>
+  const tl = gsap.timeline({ delay: 0.2 });
+  tl.to("#badge", { opacity: 1, duration: 0.15, ease: "power1.out" })
+    .to("#badge", { scale: 1.18, duration: 0.28, ease: "power2.out" }, "<")
+    .to("#badge", { scale: 1, duration: 0.18, ease: "power1.inOut" })
+    .to("#badge", { y: 180, opacity: 0, duration: 0.35, ease: "power2.in" }, "+=1.6");
+
+  gsap.to("#badge", { rotation: 2.5, duration: 0.625, yoyo: true, repeat: -1,
+                      ease: "sine.inOut" });
+</script>
+</body>
+</html>
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reframe-video",
-  "version": "0.6.20",
+  "version": "0.6.22",
   "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/skills/reframe/SKILL.md

@@ -19,7 +19,15 @@ runtime needs ffmpeg on PATH and a one-time `npx playwright install chromium`
    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`.
+3. Iterate on the cheap commands; full-render once at the end:
+   - `npx -y reframe-video compile <name>.ts` — validate eDSL → IR in ~1s, no
+     browser, no ffmpeg. Fix the classified error it prints, repeat. Catch every
+     syntax/validation error here before launching anything heavier.
+   - `npx -y reframe-video frame <name>.ts --t <sec> -o frame.png` — render ONE
+     PNG at a key moment in ~1s (chromium only, no mp4 mux) and LOOK at it. This
+     is your visual check; sample a few times across the timeline.
+   - `npx -y reframe-video render <name>.ts` → `out/<name>.mp4` — the full mp4 is
+     ~10x slower; run it once the frames look right, not per edit.
 
 ## Directing a high-end piece (cinematic / reference-faithful)
 
@@ -66,6 +74,9 @@ to handle explicitly:
 - **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).
+- **HTML/GSAP scenes**: `render` also accepts a self-contained `.html` scene and
+  captures it deterministically via a virtual clock — read
+  `npx -y reframe-video guide --html` before writing one.
 - **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.
@@ -86,6 +97,8 @@ to handle explicitly:
 
 ## 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.
+Verify on the cheap commands, not by full-rendering. `compile` (validate, ~1s)
+then `frame --t <sec>` (one PNG, ~1s) is the inner loop; `render` is for the
+final mp4. Don't pull frames out of an mp4 with ffmpeg just to look — `frame`
+writes the PNG directly and skips the mux. Same input renders byte-identically,
+so "it changed" or "it didn't change" is always provable from a single frame.