reframe-video 0.6.21 → 0.6.23

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "reframe",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "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/README.md

@@ -23,10 +23,12 @@ npx reframe-video render hello.ts    # → out/hello.mp4
 | `reframe render <scene.ts> [--overlay edits.json] [-o out.mp4]` | deterministic mp4 |
 | `reframe batch <scene.ts> <data.json\|csv>` | one mp4 per data row (row keys are overlay addresses) |
 | `reframe compile <scene.ts> [-o out.json] [--json]` | bundle + validate a scene to SceneIR JSON, no render (fast; no ffmpeg/chromium) |
+| `reframe frame <scene.ts> [--t <sec>] [-o out.png]` | render one frame at time `t` to a PNG (chromium only, no mux) — for a render-and-look loop |
 | `reframe preview` | scrub/play/edit UI for scenes in the current directory; edits export as overlay JSON |
 | `reframe new <name>` | scaffold a documented starter scene |
 | `reframe motion <mp4>` | calibrated motion profile of a rendered clip |
-| `reframe guide [--regen]` | the scene-authoring guide / regeneration contract — **feed this to your AI** |
+| `reframe guide [--directing\|--regen\|--html]` | the authoring guide (default eDSL syntax; directing workflow; regeneration contract; HTML/GSAP) — **feed this to your AI** |
+| `reframe skill [--path]` | print the authoring skill for an agent; `--path` prints the plugin dir to load |
 
 (Installed as both `reframe` and `reframe-video`; with npx use `npx reframe-video <cmd>`.)
 

package/dist/bin.js

@@ -2804,6 +2804,18 @@ 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", "guides", "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 PLUGIN_DIR = PACKAGED ? ROOT2 : join9(ROOT2, "plugin");
 var USAGE = `reframe \u2014 declarative motion graphics
 
 usage:
@@ -2824,7 +2836,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,22 +3197,21 @@ ${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;
     }
     case "skill": {
       if (rest.includes("--path")) {
-        process.stdout.write(`${ROOT2}
+        process.stdout.write(`${PLUGIN_DIR}
 `);
         return;
       }
       const { readFile: readFile7 } = await import("node:fs/promises");
-      process.stdout.write(await readFile7(join9(ROOT2, "skills", "reframe", "SKILL.md"), "utf8"));
+      process.stdout.write(await readFile7(join9(PLUGIN_DIR, "skills", "reframe", "SKILL.md"), "utf8"));
       return;
     }
     case "demo":

package/guides/edsl-guide.md

@@ -475,6 +475,31 @@ group({ id: "burst", x, y, blend: "screen" }, [ disc1, disc2, disc3 ])
   with the effect). It wraps a matte group and nests. The effects are screen-pixel space.
   See `examples/scenes/group-fx-demo.ts`.
 
+## Device frames (phone / browser / laptop …)
+
+To put a **phone, browser, laptop, …** on screen, use the preset — don't hand-draw
+a device out of rects. `devicePreset(name, opts) → NodeIR` returns a parametric
+vector frame (bezel, rounded body, phone notch / dynamic island, browser chrome).
+
+- `devicePreset(name, { id, x, y, scale?, opacity?, orientation?, content })` —
+  names: `phone` `tablet` `laptop` `browser` `watch` `monitor` `tv` `foldable`
+  `terminal` `car`. **There is no `"iphone"` — `"phone"` IS the iOS-style frame**
+  (notch + dynamic island). `browser`/`terminal` take an `address` string.
+- `content` nodes are authored in **screen-LOCAL centre coords** (0,0 = screen
+  centre) and clipped to the screen. Stable ids `${id}-screen` / `${id}-content`
+  (overlay/regen addresses) — keep `id` across rewrites.
+- It's one node: animate the device group for the float/entrance (`tween`/
+  `motionPath` its `x`/`y`/`scale`/`rotation`, `oscillate` for an idle drift).
+
+```ts
+// a phone floating centre, a chat bubble inside the screen:
+devicePreset("phone", { id: "hero", x: 960, y: 540, scale: 0.92, opacity: 0,
+  content: [ rect({ id: "b1", x: 80, y: -120, width: 300, height: 64, radius: 22, fill: "#2563EB" }) ] })
+// timeline: par(tween("hero", { opacity: 1, scale: 1 }, { ease: "easeOutBack" }))
+```
+
+Pair with `cursor` + `deviceScreenPoint` (below) to click UI *inside* the device.
+
 ## Cursor (UI demos)
 
 A vector mouse pointer that glides across the scene and clicks things — for app

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.21",
+  "version": "0.6.23",
   "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

@@ -74,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.

package/.claude-plugin/marketplace.json

@@ -1,14 +0,0 @@
-{
-  "name": "reframe",
-  "owner": {
-    "name": "Kiyeon Jeon",
-    "url": "https://github.com/kiyeonjeon21"
-  },
-  "plugins": [
-    {
-      "name": "reframe",
-      "source": "./",
-      "description": "Motion-graphics videos as addressable data — generate, tweak, regenerate without losing human edits."
-    }
-  ]
-}