reframe-video 0.6.20 → 0.6.21

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reframe-video",
-  "version": "0.6.20",
+  "version": "0.6.21",
   "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)
 
@@ -86,6 +94,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.