luckiest-co 1.0.39 → 1.0.41

package/skills/video-studio-motion/SKILL.md

@@ -16,7 +16,7 @@ user-invocable: true
 license: MIT. See ATTRIBUTION.md
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 metadata:
-  version: "1.1.0"
+  version: "1.2.0"
   listing_id: luckiest-video-studio-motion
   author: luckiest
 ---
@@ -32,11 +32,11 @@ interruption, and how often a user triggers something.
 ## Staying current
 
 On activation, call the Luckiest MCP `check_updates` tool with
-`{ listingId: "luckiest-video-studio-motion", installedSemver: "1.1.0" }`. If
+`{ listingId: "luckiest-video-studio-motion", installedSemver: "1.2.0" }`. If
 `upToDate: false`, surface the `notice` once and continue. Never block on it.
 
 When done, call `report_usage` once with
-`{ listing_id: "luckiest-video-studio-motion", skill_version: "1.1.0", matched: true, success: <true|false> }`.
+`{ listing_id: "luckiest-video-studio-motion", skill_version: "1.2.0", matched: true, success: <true|false> }`.
 Metadata only, never prompt text. Skip silently if unavailable.
 
 ## Modes
@@ -87,6 +87,20 @@ Match overshoot to the tone in
 [tones.md](../luckiest-video-studio/references/tones.md): crisp for polished, bouncy
 only for playful or chaotic.
 
+**Land decelerates, leave accelerates.** On professional films most of an
+entrance's travel happens in its first 4 to 8 frames, then a long tail with no
+bounce; exits ease in, then leave or shrink. One visible overshoot or spring per
+film, 4 to 12% past the target, spent on the hero moment. Everything else lands
+clean.
+
+| Role | GSAP | CSS cubic-bezier (for stills and editors) |
+|---|---|---|
+| Soft land (most entrances) | `expo.out` | `cubic-bezier(0.16, 1, 0.3, 1)` |
+| Snap and settle (CTA, toggles, counters) | `power4.out` | `cubic-bezier(0.165, 0.84, 0.44, 1)` |
+| A to B on screen | `power3.inOut` | `cubic-bezier(0.645, 0.045, 0.355, 1)` |
+| Accelerating exit | `power2.in` to `power3.in` | `cubic-bezier(0.55, 0.055, 0.675, 0.19)` |
+| The one overshoot | `back.out(1.4)` or a spring | n/a |
+
 ## 3. Duration and hold
 
 | Element | Duration |
@@ -101,10 +115,30 @@ After the move, hold. A short label settles about 0.8s and a sentence about
 0.3s per word (the main skill's readability law). Fast in, long hold beats slow in,
 short hold.
 
+Measured on professional films at 30fps (use as the default when the tone gives
+no reason otherwise):
+
+| Move | Frames | Seconds |
+|---|---|---|
+| Median move | 10 | 0.33 |
+| Translate in | 12 | 0.4 |
+| Opacity on a single object | 6 | 0.2 |
+| Blur resolve | 7 | 0.23 |
+| Translate out | 13-14 | 0.45 |
+| Scale out | 10 | 0.33 |
+| CTA entrance | 6 | 0.2 |
+
+A held frame is never dead: keep one living thing (a slow drift of 1 to 3px per
+frame, a caret, moving light). Something new every 0.3 seconds at most, a major
+change about every 0.8 seconds.
+
 ## 4. Physicality and origin
 
 - **Nothing appears from nothing.** Cards, panels, text blocks, and screenshots
-  enter from `scale: 0.9-0.97` with `autoAlpha: 0`, never `scale: 0`. A small accent
+  enter from `scale: 0.9-0.97` with `autoAlpha: 0`, never `scale: 0`. Hero
+  arrivals decelerate from oversize instead: a logo crashes in from about 3.5x to
+  1.0 within 20 frames, a cursor enters 1.5 to 5x its size, a thesis word shrinks
+  into place. A small accent
   (a dot, badge, or icon) may pop from `scale: 0` only with a `back.out` or
   `steps()` ease, where the overshoot is the point.
 - **Scale from the source.** A callout over demo footage grows from the point it
@@ -131,14 +165,71 @@ short hold.
   cut instead.
 - **Stagger groups.** Items entering together stagger 40-100ms (30-80ms for mock
   UI). Everything at once reads as a slide change. A long stagger reads as slow.
+  Measured: the gap is about half the move's duration (a 3-frame median); a CTA
+  wave uses 8-frame gaps and finishes inside 0.6s.
+- **Never crossfade scenes.** Things arrive by moving, cutting, unmasking or
+  focusing. Fades are for single objects (calm brands and privacy dissolves are
+  the exceptions, stated in the plan).
 - **Asymmetric timing.** Slow where the viewer should take something in, snappy
   where the system responds: a 1.2s linear progress fill, then a 0.2s `power3.out`
   confirmation.
 - **Sound on the same frame.** An SFX lands on the frame its visual cause lands,
   never a frame early or late ([audio.md](../luckiest-video-studio/references/audio.md)).
 
+### Handoffs between scenes
+
+The last frame of scene A is the first frame of scene B. For each cut, write:
+
+1. What carries across (an object, a shape, a colour, or nothing).
+2. A's exit state over its last 1 to 3 frames: position, size as % of frame
+   height, speed, blur, ground colour.
+3. B's frame 0 matches that state within 2% of the frame, and something in B is
+   already moving.
+4. A ground colour change is caused by an object (a card fills the frame), never
+   a flat swap.
+5. Cut at peak speed, never on rest. A speeds up over its last 3 to 8 frames; 0 to
+   3 empty frames between are fine.
+6. Which spoken word lands on the cut.
+
+An object pinned at the same coordinates through three or more scenes is a
+defect. A carrier travels at every cut.
+
+| What changes from A to B | Use |
+|---|---|
+| Same object, new state | Match cut on the object (morph, scale, recolor) |
+| New subject, same world | Cut on motion, or a whip (8 frames, peak speed a quarter in, about 13% of frame width per frame) |
+| Soft change of topic | Blur-matched cut: A blurs out to about 18px, B starts at about 80px and resolves in about 8 frames |
+| New ground colour | Feathered wipe painted in B's ground (feather 30 to 40% of the axis, 0.56 to 0.6s, starting 0.1 to 0.2s before the voice line ends) |
+| Light to dark theme | A 4-frame grey dip hides the flip |
+| Into the product | A camera push into the UI, then cut inside it |
+
+Cuts fall every 0.3 to 2.3 seconds. Transitions start 3 to 6 frames before the
+voice line ends.
+
+### Camera
+
+- **Push** size by duration: 1.25x over 6 frames, 1.4x over 12 to 18, 1.5x over
+  20 to 45. 2.4x only on a slow drift.
+- **Snap zoom:** one jump frame changes scale by a ratio of 0.56 to 0.77 (or its
+  inverse), then a 9 to 18 frame tail settles it.
+- **Parallax:** near layers move 2 to 2.4x the far ones.
+- **Drift:** 1 to 3px per frame keeps a hold alive.
+
+### One system per film
+
+One frame clock (smooth, or on twos for a hand-made look), one blur grammar
+(motion blur, or smear frames, or crisp steps), one accent colour with one
+meaning (for example "done"). Mixing clocks or blur styles inside one film reads
+as two films.
+
 ## 6. Type and depth
 
+Read [references/kinetic-type.md](references/kinetic-type.md) when a scene
+animates words, a counter, or typing. Read
+[references/ui-demo.md](references/ui-demo.md) when a scene shows product UI, a
+cursor, a click, or a toggle.
+
+
 - Display text tracks tight (`letter-spacing: -0.02em` and below as size grows,
   `line-height` about 1.05). Captions and small labels track slightly open.
 - Build hierarchy with weight, size, and leading together, not size alone.
@@ -161,7 +252,9 @@ has been read. For each scene in `storyboard.json`, read its composition and wri
 2. **Verdict per scene: Block or Approve.** Default to flagging; approval is
    earned. Block on: a motion beat with no purpose, an `.in` ease on an entrance,
    `scale: 0` on a card or text block, a full-frame opacity crossfade, drifting text
-   the viewer is reading, or overshoot that fights the tone.
+   the viewer is reading, overshoot that fights the tone, a second visible
+   overshoot in the film, a cut on rest, an object pinned through three scenes, or
+   a headline typed letter by letter.
 
 Fix in this order, preferring earlier moves: delete the motion, reduce it, fix the
 easing, fix the origin, mask the transition (blur or clip-path), stagger the

package/skills/video-studio-motion/references/kinetic-type.md

@@ -0,0 +1,89 @@
+# Kinetic type
+
+Numbers for words on screen, measured on professional films at 30fps. Ideas and
+values from Tejas Makwana's `motionmaxxing` (Apache-2.0), restated for HyperFrames
+and GSAP. See `../ATTRIBUTION.md`.
+
+## Words arrive at speech rhythm
+
+Animate whole words, not letters. Gap between word onsets:
+
+| Pace | Gap |
+|---|---|
+| Fast hook | 2-4 frames |
+| Headline | 4-6 frames |
+| Voice-led line | 8-12 frames |
+
+- The stinger (the last, most important word) waits 1.5 to 2x the normal gap.
+- Vary each gap by up to 40% so it does not tick like a metronome.
+- Each word rises 3 to 7% of the frame height, with most of its travel in the
+  first 5 frames (`expo.out`).
+- An accent colour on a word lasts 0.13 to 0.28 seconds, then decays to the ink
+  colour. One accent word per line at most.
+
+```js
+// gaps in frames at 30fps; pick the row for the pace
+const gaps = [4, 5, 4, 8]; // last gap is the stinger
+let t = 0;
+words.forEach((w, i) => {
+  tl.from(w, { yPercent: 60, autoAlpha: 0, duration: 0.33, ease: "expo.out" }, t);
+  t += (gaps[i] ?? 5) / 30;
+});
+```
+
+## Reading holds
+
+| Text | Hold after it lands |
+|---|---|
+| Any text | 0.45 s minimum |
+| Per word | about 0.2 s |
+| 6 to 8 words | 1.7 to 2.0 s |
+| A number | 0.5 to 1.2 s |
+| About 20 characters | 1.2 s |
+
+The studio's readability law (about 0.3 s per word for a sentence) is the safe
+ceiling for narration-free videos; these are the floor. Never cut a line before
+its floor.
+
+## On-screen words and the voice
+
+- Words land 0 to 2 frames before they are heard (up to 5 frames for names).
+- At most about 7 words on screen at once. Claims are 2 to 6 words.
+
+## Typing
+
+Type only into the product's own input field. A headline is never typed letter
+by letter with a caret: it reads as a template.
+
+- 14 to 30 characters per second when the viewer must read it, bursts of 70 to 85
+  otherwise.
+- Pause 6 to 10 frames after a space or a comma.
+- The caret appears 1 frame before the first letter and stays solid (no blink)
+  while typing.
+- Use a real query or prompt from the product, 20 to 70 characters.
+
+## Counters
+
+- Step once per frame, 15 to 23 steps over 0.5 to 0.9 seconds, decelerating.
+- Land on a round value for a claim ("2x"), an un-round value for data
+  ("1,284"). The number must be real (the `facts` gate).
+- Spend the hero number once per film, at 22 to 29% of the frame height.
+
+## Sizes and weights
+
+| Role | Size (share of frame height) |
+|---|---|
+| Headline | 7-11% (9% typical) |
+| Supporting line | 5-7% |
+| Hero number | 22-29%, once per film |
+| Readable floor | 4% (under 2% reads as texture) |
+
+- Weights 400 to 550. 600 only on a wordmark.
+- Track display sizes tight, -1.5% to -5.5%. Sentence case.
+- Use the brand's own face, a serif if the brand uses one.
+- Most type is small. Scale is spent once; the ending usually gets smaller.
+
+At 1080p these map onto the studio's type tokens (22, 30, 42, 60, 84px, checked
+by `qa.mjs tokens`): headline 84px (7.8%), supporting 60px (5.6%), readable floor
+42px (3.9%). A hero number is off the default scale: add its one size to the run's
+tokens file and pass it with `qa.mjs tokens --tokens <file>`.

package/skills/video-studio-motion/references/ui-demo.md

@@ -0,0 +1,59 @@
+# UI demos
+
+How to show a real product on screen so it reads as proof, measured on
+professional films at 30fps. Ideas and values from Tejas Makwana's
+`motionmaxxing` (Apache-2.0), restated for HyperFrames and GSAP. See
+`../ATTRIBUTION.md`.
+
+## Magnify with the camera, not the type
+
+- Keep the UI at its real size (15 to 17pt text in the product) and push the
+  camera in: crop 1.4 to 4.4x.
+- Proof is readable when UI text is at least 4% of the frame height and the
+  fragment is at least 55% of the frame width, or cropped by the frame edge.
+- Keep the top and bottom 28% of the frame clear of UI when a line of copy shares
+  the shot.
+- Show a magnified fragment with identity (the product's own colours, icons and
+  copy), lit and placed in a world, not a small card on a flat colour.
+- Captured screens follow the studio's standing rule: no real customer data,
+  emails, keys or tokens on screen. Swap them for the product's demo data before
+  the capture, never blur them after.
+- Never invent the UI. A rounded card with a status dot and "label . $value", a
+  "Good morning" card, grey skeleton bars, or made-up names and numbers read as
+  generic web components. Use the captured screens.
+
+## Cursor
+
+| Step | Value |
+|---|---|
+| Size | 4 to 6% of the frame width |
+| Entry | 1.5 to 5x its size, 60% of the travel in the first frame, over 0.5 to 0.9 s |
+| Park | Still for 2 to 15 frames before it acts |
+| Press | Squeezes to 0.71 to 0.9 scale over 2 frames |
+| Target | Answers 0 to 1 frame after the press, dipping to 0.63 to 0.81 scale |
+| Release | Cut before it; the release is never shown |
+
+The cursor arrives, parks, then acts. It never clicks while still moving.
+
+## States
+
+- A toggle flips in 2 frames.
+- A cascade (rows reacting to one action) starts 5 frames after the action, then
+  2 to 3 frames per item, all done within 0.6 s.
+- A checklist row takes about 0.9 s.
+- "Working" shimmer: a light band about 23% of the frame width sweeps for 13
+  frames, twice, with a 6-frame gap.
+- A log or feed scroll accelerates from about 6 to 250px per frame over about
+  1.8 s, then holds 0.8 s.
+
+## Depth behind UI
+
+- Backdrop blur: 4px keeps the background readable, 7 to 15px for panels that
+  are not the hero, at most 11px behind a headline.
+- Two panels in one frame only when one is at least twice the other's area, or
+  the camera moves between them. One hero per frame.
+
+## Typing in the product
+
+See [kinetic-type.md](kinetic-type.md#typing): real queries, 14 to 30 characters
+per second, a solid caret.

package/skills/video-studio-review/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog: luckiest-video-studio-review
 
+## 1.1.0 (2026-10-10)
+- `build-reel.mjs --storyboard`: review the storyboard before any render. Joins
+  each scene's still (`scenes[].still`, default `storyboard/<id>.png`) into
+  `storyboard/animatic.mp4` and writes `reel.json` with `"stage": "storyboard"`.
+  Each scene's `line` (and `prompt` for `ai` scenes) is an editable field.
+  No `final.mp4` needed. Without the flag, nothing changes.
+- Player: in the storyboard stage it draws the scene's still with its line and
+  length over the frame, Send to Claude works with no edits, and the Do line
+  says it is the storyboard. Render prompts are unchanged.
+- `apply-feedback.md`: a storyboard stage section.
+
 ## 1.0.0 (2026-10-07)
 Built from Motion OS (`jasonlee-breadcrumb/motion-os`, MIT) as the review player
 sub-skill of luckiest-video-studio. Replaces the default Concat handoff and the

package/skills/video-studio-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: video-studio-review
 description: >-
-  Open a rendered luckiest-video-studio run in the review player, a local
+  Open a luckiest-video-studio storyboard (before render) or a rendered run in the review player, a local
   scene-by-scene player (built on Motion OS) where the user edits each scene's
   copy and colors, pins notes on the exact frame, marks scenes approved, and
   copies one prompt back. Then apply that prompt: edits land in storyboard.json,
@@ -18,7 +18,7 @@ user-invocable: true
 license: MIT. See ATTRIBUTION.md
 allowed-tools: Bash, Read, Write, Edit, Glob, AskUserQuestion
 metadata:
-  version: "1.0.0"
+  version: "1.1.0"
   listing_id: luckiest-video-studio-review
   author: luckiest
 ---
@@ -36,11 +36,11 @@ so the run stays the source of truth and untouched scenes never re-render.
 ## Staying current
 
 On activation, call the Luckiest MCP `check_updates` tool with
-`{ listingId: "luckiest-video-studio-review", installedSemver: "1.0.0" }`. If
+`{ listingId: "luckiest-video-studio-review", installedSemver: "1.1.0" }`. If
 `upToDate: false`, surface the `notice` once and continue. Never block on it.
 
 When done, call `report_usage` once with
-`{ listing_id: "luckiest-video-studio-review", skill_version: "1.0.0", matched: true, success: <true|false> }`.
+`{ listing_id: "luckiest-video-studio-review", skill_version: "1.1.0", matched: true, success: <true|false> }`.
 Metadata only, never prompt text. Skip silently if unavailable.
 
 ## Standing rules
@@ -57,7 +57,8 @@ Metadata only, never prompt text. Skip silently if unavailable.
 ## Step 1: Open the player
 
 Needs `node` 18+ and `ffprobe`. Run `render-scenes.mjs` first: the player shows
-`final.mp4`.
+`final.mp4`. To review a storyboard before anything renders, see **Storyboard
+review** below.
 
 ```bash
 node <skill-dir>/scripts/build-reel.mjs <run-dir>     # writes <run-dir>/reel.json
@@ -102,6 +103,31 @@ node <skill-dir>/scripts/build-reel.mjs <run-dir>
 `build-reel.mjs` bumps `version`; the open player reloads within about 3 seconds.
 Reply with a short list of what changed and anything you could not do.
 
+## Storyboard review
+
+Before the render, the studio's Step 2 reviews the plan scene by scene in the
+same player. No `final.mp4` is needed:
+
+```bash
+node <skill-dir>/scripts/build-reel.mjs <run-dir> --storyboard
+node <skill-dir>/editor/serve.mjs <run-dir>
+```
+
+It needs one still per scene (`scenes[].still`, default `storyboard/<id>.png`)
+and `ffmpeg`. It joins the stills, each held for its scene's `duration`, into
+`storyboard/animatic.mp4` and writes `reel.json` with `"stage": "storyboard"`.
+The player draws each scene's still with its line and length over the frame.
+Each scene's `line` is an editable field (and `prompt` for `ai` scenes), so the
+Script tab holds the whole script. Edit, notes, Timing, and Approved work as on
+a render. A missing still stops the build and names the file.
+
+Send to Claude works even with no edits, so the user can send "all approved".
+Its prompt has the same format as a render's, with a Do line that says it is the
+storyboard. Apply it as the storyboard section of
+[references/apply-feedback.md](references/apply-feedback.md) says, then rerun
+`build-reel.mjs --storyboard`. When the prompt says every scene is approved, hand
+back to the studio for Step 2b.
+
 ## Talking-head cuts
 
 `luckiest-video-studio-cuts` reviews its silence cut in the same player. Its

package/skills/video-studio-review/editor/index.html

@@ -75,6 +75,10 @@ button{cursor:pointer}
 .viewer video{position:absolute;inset:0;width:100%;height:100%;display:block;background:#fff}
 #live{position:absolute;left:0;top:0;width:1920px;height:1080px;transform-origin:0 0;overflow:hidden}
 .overlay{position:absolute;inset:0}
+/* storyboard stage: the scene's still and its script line over the frame */
+.sb-still{position:absolute;inset:0;width:100%;height:100%;object-fit:contain;display:block}
+.sb-cap{position:absolute;left:0;right:0;bottom:0;padding:10px 14px;background:linear-gradient(transparent,rgba(0,0,0,.78));color:#fff;font-size:15px;line-height:1.35;pointer-events:none}
+.sb-cap small{display:block;font-family:var(--mono);font-size:11px;opacity:.75;margin-bottom:2px}
 .overlay.note-mode{cursor:crosshair}
 .hot{position:absolute;border:2px solid var(--accent);border-radius:6px;pointer-events:none;background:color-mix(in srgb,var(--accent) 7%,transparent)}
 .hot.hover{border-style:dashed;background:none}
@@ -291,6 +295,7 @@ button{cursor:pointer}
       <div class="viewer-wrap">
         <div class="viewer" id="viewer">
           <video id="vid" playsinline preload="auto"></video>
+          <img class="sb-still" id="sbStill" alt="" hidden><div class="sb-cap" id="sbCap" hidden></div>
           <div class="overlay" id="overlay"><div id="ghosts"></div><div id="hots"></div><div id="popLayer"></div></div>
         </div>
       </div>
@@ -362,6 +367,7 @@ function loadProject(){
   ui = {...ui, scene:P.scenes[0].id, sel:null, pop:null, selNote:null};
   $('#projTitle').textContent = P.title; $('#projVer').textContent = 'v' + ver; document.title = P.title + ' · Motion OS';
   vid.src = P.src + '?v=' + ver; vid.currentTime = 0.7;
+  $('#sbStill').hidden = $('#sbCap').hidden = P.stage !== 'storyboard';
   setupMusic(); renderAll(); tick();
 }
 
@@ -389,6 +395,7 @@ function markDirty(){
   if (!P) return;
   try { localStorage.setItem(KEY(), JSON.stringify(st)); } catch (e) {}
   $('#sendN').textContent = pendingEdits() + openNotes().length;
+  if (P.stage === 'storyboard') storyboardFrame(sceneAt(now()));
 }
 
 /* ================= playback ================= */
@@ -439,7 +446,15 @@ function tick(){
   const t = now(), s = sceneAt(t);
   if (s.id !== ui.scene && playing() && !ui.loop) { ui.scene = s.id; if (ui.sel && elById(ui.sel)?.s !== s.id) ui.sel = null; renderTL(); if (ui.tab === 'scene') renderPane(); }
   $('#tc').innerHTML = `${fmt(t)} <small>/ ${fmt(P.duration)} · ${s.id} ${esc(s.name)}</small>`;
-  placePH(); renderHots();
+  placePH(); renderHots(); if (P.stage === 'storyboard') storyboardFrame(s);
+}
+// Storyboard stage (reel.json "stage": "storyboard"): nothing is rendered yet, so draw the scene's still with its
+// line and length on the frame. The line shows the user's unsent edit, so they see what they will send.
+function storyboardFrame(s){
+  const e = s.els[0], img = $('#sbStill'), src = s.still + '?v=' + (P.version || 1);
+  if (img.getAttribute('src') !== src) img.setAttribute('src', src);
+  const [a, b] = elTime(e), kind = e.props.motion?.v || '';
+  $('#sbCap').innerHTML = `<small>${esc(s.id)} · ${esc(kind)} · ${(b - a).toFixed(1)}s</small>${esc(e.props.line ? pv(e, 'line') : e.label)}`;
 }
 function setupMusic(){
   if (music) { music.pause(); music = null; }
@@ -801,13 +816,16 @@ function prompt(){
   const links = st.links.filter(l => !l.sent);
   if (links.length) { L.push('## Links to download into assets/'); links.forEach(l => L.push('- ' + l.url)); L.push(''); }
   L.push('## Scenes', P.scenes.map(s => `${s.id} ${s.name} (${fmt(s.t[0])}-${fmt(s.t[1])}): ${st.status[s.id] === 'approved' ? 'approved, do not touch' : st.status[s.id] === 'changes' ? 'needs changes' : 'in review'}`).join('\n'), '');
-  L.push('## Do', `Use the luckiest-video-studio-review skill. Apply the edits exactly and work through the notes. Leave approved scenes alone. Re-render, check it, then update reel.json and set "version" to ${ver + 1} so Motion OS reloads.`);
+  if (P.stage === 'storyboard') L.push('## Do', P.scenes.every(s => st.status[s.id] === 'approved')
+    ? 'Use the luckiest-video-studio-review skill. This is the storyboard and every scene is approved. Apply any edits above to storyboard.json, then go on to the assets, the style frame, and the render.'
+    : `Use the luckiest-video-studio-review skill. This is the storyboard, nothing is rendered yet. Apply the edits exactly to storyboard.json and work through the notes. Leave approved scenes alone. Redraw only the changed stills, then rerun build-reel.mjs --storyboard so Motion OS reloads at version ${ver + 1}.`);
+  else L.push('## Do', `Use the luckiest-video-studio-review skill. Apply the edits exactly and work through the notes. Leave approved scenes alone. Re-render, check it, then update reel.json and set "version" to ${ver + 1} so Motion OS reloads.`);
   return L.join('\n');
 }
 function sheet(html){ const d = document.createElement('div'); d.className = 'scrim'; d.innerHTML = `<div class="sheet" role="dialog" aria-modal="true">${html}</div>`;
   d.addEventListener('click', e => { if (e.target === d || e.target.closest('[data-close]')) d.remove(); }); document.body.appendChild(d); return d; }
 $('#sendBtn').onclick = () => {
-  if (!(pendingEdits() + openNotes().length)) return toast('Nothing to send yet. Edit something, or press N to pin a note.');
+  if (!(pendingEdits() + openNotes().length) && P.stage !== 'storyboard') return toast('Nothing to send yet. Edit something, or press N to pin a note.');
   const text = prompt();
   const d = sheet(`<h3>Send to Claude</h3><p>Copy this, then paste it into Claude.</p><textarea class="out" readonly></textarea><div class="row"><button class="btn ghost" data-close>Close</button><button class="btn primary" id="doCopy">Copy prompt</button></div>`);
   d.querySelector('textarea').value = text;

package/skills/video-studio-review/references/apply-feedback.md

@@ -69,3 +69,22 @@ look at a contact sheet before showing anything:
 Then rerun `build-reel.mjs`. The prompt
 asks for version `N+1`; `build-reel.mjs` sets it. Reply with what changed, what
 was skipped and why, and anything you could not do.
+
+## Storyboard stage
+
+A prompt whose Do line says "This is the storyboard" comes from a reel built with
+`build-reel.mjs --storyboard`. Nothing is rendered yet, so:
+
+- `Line` edits set `scenes[N].line`, and `Prompt` edits set `scenes[N].prompt`,
+  with the same before-value check. When the run has a `script.md`, write the new
+  line there too (the script sub-skill's Step 5).
+- `timing (s)` edits set the scene's `duration`.
+- Notes are read against the scene's still (`storyboard/<id>.png`), not a frame
+  of `final.mp4`. A note about the idea (the hook is weak, a beat is missing)
+  goes back to `luckiest-video-studio-director` to fix the shot list.
+- A scene marked approved that also carries an edit was approved as edited:
+  apply that edit, then leave the scene alone.
+- Never render. Redraw only the stills whose scene changed, then rerun
+  `build-reel.mjs --storyboard` so the player reloads at the next version.
+- When every scene in the Scenes block is approved, apply any edits, then hand
+  back to `luckiest-video-studio` for Step 2b. That is the storyboard gate.

package/skills/video-studio-review/scripts/build-reel.mjs

@@ -3,7 +3,10 @@
 // per storyboard scene, in storyboard order, with each scene's variables as editable fields. Rerunning bumps
 // "version" so an open player reloads itself. <run-dir>/qa/review-notes.json ([{ t, x, y, text, scene? }]), when
 // present, is pinned on the frame as Claude's own notes. Then serve it: node <skill-dir>/editor/serve.mjs <run-dir>
-// Usage: node build-reel.mjs <run-dir>
+// Usage: node build-reel.mjs <run-dir> [--storyboard]
+// --storyboard: review the plan before anything renders. Joins each scene's hold-frame still (scenes[].still, default
+// storyboard/<id>.png) for its duration into storyboard/animatic.mp4 with ffmpeg and serves that instead of final.mp4.
+// Each scene's line and (for "ai" scenes) its prompt become editable fields.
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
@@ -12,6 +15,8 @@ import { fileURLToPath } from "node:url";
 const MEDIA = { image: /\.(png|jpe?g|webp|gif|svg)$/i, video: /\.(mp4|mov|webm)$/i, audio: /\.(mp3|wav|m4a)$/i };
 const mediaType = (v) => Object.keys(MEDIA).find((k) => MEDIA[k].test(v));
 const slug = (v) => v.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+export const stillOf = (s) => s.still ?? `storyboard/${s.id}.png`;
+const ANIMATIC = "storyboard/animatic.mp4";
 const words = (id) => id.replace(/-/g, " ").replace(/^./, (c) => c.toUpperCase());
 
 // One field per variable: hex -> color, file path -> media, number -> number, other strings -> text.
@@ -26,7 +31,7 @@ function field(k, v) {
 }
 
 // Pure: the reel for a storyboard. prevVersion is the version of the reel.json already in the run, or 0.
-export function buildReel(sb, runDir, prevVersion = 0, duration = 0, qaNotes = []) {
+export function buildReel(sb, runDir, prevVersion = 0, duration = 0, qaNotes = [], storyboard = false) {
   const assets = new Map();
   // The player's color fields pick from the brand palette, so every distinct hex becomes a palette entry and the
   // field links to it. Editing a palette color in the Style tab then changes every scene that uses it.
@@ -48,12 +53,17 @@ export function buildReel(sb, runDir, prevVersion = 0, duration = 0, qaNotes = [
       props[k] = f;
       if (f.type === "media") asset(v, "Run");
     }
+    if (storyboard) {
+      props.line = { type: "longtext", label: "Line", v: s.line ?? "" };
+      if (s.prompt) props.prompt = { type: "longtext", label: "Prompt", v: s.prompt };
+      asset(stillOf(s), "Storyboard");
+    }
     if (s.kind === "demo" && s.source) { props.source = { type: "media", label: "Footage", v: s.source }; asset(s.source, "Footage"); }
     for (const a of s.assets ?? []) asset(a, "Run");
     props.motion = { type: "motion", label: "Motion", v: [s.kind, s.recipe].filter(Boolean).join(", ") };
-    const src = s.kind === "demo" ? s.source : `composition/${s.composition ?? `compositions/${s.id}.html`}`;
+    const src = storyboard ? stillOf(s) : s.kind === "demo" ? s.source : `composition/${s.composition ?? `compositions/${s.id}.html`}`;
     return {
-      id: s.id, name: words(s.id), t: range,
+      id: s.id, name: words(s.id), t: range, ...(storyboard && { still: stillOf(s) }),
       els: [{ id: s.id, label: s.line || words(s.id), t: range, box: null, src: `storyboard.json scenes[${i}] · ${src}`, props }],
     };
   });
@@ -64,7 +74,8 @@ export function buildReel(sb, runDir, prevVersion = 0, duration = 0, qaNotes = [
     title: sb.title,
     version: prevVersion + 1,
     path: runDir,
-    src: "final.mp4",
+    src: storyboard ? ANIMATIC : "final.mp4",
+    ...(storyboard && { stage: "storyboard" }),
     w: sb.format.width, h: sb.format.height, fps: sb.format.fps,
     // The joined file can run a frame or two off the storyboard sum; trust the file when it was probed.
     duration: duration || +t.toFixed(3),
@@ -79,18 +90,32 @@ export function buildReel(sb, runDir, prevVersion = 0, duration = 0, qaNotes = [
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  const runDir = resolve(process.argv[2] ?? ".");
+  const args = process.argv.slice(2);
+  const storyboard = args.includes("--storyboard");
+  const runDir = resolve(args.find((a) => !a.startsWith("--")) ?? ".");
   const fail = (m) => { console.error(`error: ${m}`); process.exit(1); };
   if (!existsSync(join(runDir, "storyboard.json"))) fail(`no storyboard.json in ${runDir}`);
-  if (!existsSync(join(runDir, "final.mp4"))) fail(`no final.mp4 in ${runDir}; run render-scenes.mjs first`);
   const sb = JSON.parse(readFileSync(join(runDir, "storyboard.json"), "utf8"));
+  const video = storyboard ? ANIMATIC : "final.mp4";
+  if (storyboard) {
+    const missing = sb.scenes.map(stillOf).filter((f) => !existsSync(join(runDir, f)));
+    if (missing.length) fail(`missing storyboard stills: ${missing.join(", ")}`);
+    const { width: W, height: H, fps } = sb.format;
+    // One still per scene, held for its duration, letterboxed to the master size, joined in order.
+    const inputs = sb.scenes.flatMap((s) => ["-loop", "1", "-t", String(s.duration), "-i", join(runDir, stillOf(s))]);
+    const fit = sb.scenes.map((_, i) => `[${i}:v]scale=${W}:${H}:force_original_aspect_ratio=decrease,pad=${W}:${H}:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=${fps},format=yuv420p[v${i}]`);
+    const filter = `${fit.join(";")};${sb.scenes.map((_, i) => `[v${i}]`).join("")}concat=n=${sb.scenes.length}:v=1:a=0[out]`;
+    const ff = spawnSync("ffmpeg", ["-v", "error", "-y", ...inputs, "-filter_complex", filter, "-map", "[out]", "-c:v", "libx264", "-tune", "stillimage", "-movflags", "+faststart", join(runDir, video)], { encoding: "utf8" });
+    if (ff.status !== 0) fail(`ffmpeg could not build ${video}: ${ff.stderr || ff.error?.message}`);
+  } else if (!existsSync(join(runDir, "final.mp4"))) fail(`no final.mp4 in ${runDir}; run render-scenes.mjs first, or pass --storyboard to review the plan`);
   const reelFile = join(runDir, "reel.json");
   const prev = existsSync(reelFile) ? JSON.parse(readFileSync(reelFile, "utf8")).version ?? 0 : 0;
-  const probe = spawnSync("ffprobe", ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", join(runDir, "final.mp4")], { encoding: "utf8" });
+  const probe = spawnSync("ffprobe", ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", join(runDir, video)], { encoding: "utf8" });
   const notesFile = join(runDir, "qa", "review-notes.json");
   const qaNotes = existsSync(notesFile) ? JSON.parse(readFileSync(notesFile, "utf8")) : [];
-  const reel = buildReel(sb, runDir, prev, +(Number(probe.stdout?.trim()) || 0).toFixed(3), qaNotes);
+  // The animatic is built from the storyboard, so its scene sum is exact; probe only the rendered final.mp4.
+  const reel = buildReel(sb, runDir, prev, storyboard ? 0 : +(Number(probe.stdout?.trim()) || 0).toFixed(3), qaNotes, storyboard);
   writeFileSync(reelFile, JSON.stringify(reel, null, 1) + "\n");
   const serve = join(dirname(fileURLToPath(import.meta.url)), "..", "editor", "serve.mjs");
-  console.log(`wrote ${reelFile} v${reel.version} (${reel.scenes.length} scenes, ${reel.duration}s). Open it: node "${resolve(serve)}" "${runDir}"`);
+  console.log(`wrote ${reelFile} v${reel.version}${storyboard ? " storyboard" : ""} (${reel.scenes.length} scenes, ${reel.duration}s). Open it: node "${resolve(serve)}" "${runDir}"`);
 }

package/skills/video-studio-review/scripts/build-reel.test.mjs

@@ -60,3 +60,18 @@ test("rerunning bumps the version so an open player reloads", () => {
   assert.equal(buildReel(sb, "/r").version, 1);
   assert.equal(buildReel(sb, "/r", 4).version, 5);
 });
+
+test("storyboard mode plays the animatic and makes each line and ai prompt editable", () => {
+  const withAi = { ...sb, scenes: [...sb.scenes, { id: "city", kind: "ai", duration: 4, line: "The city wakes up", prompt: "Aerial dawn over a city", still: "storyboard/city-sketch.png" }] };
+  const reel = buildReel(withAi, "/r", 0, 0, [], true);
+  assert.equal(reel.src, "storyboard/animatic.mp4");
+  assert.equal(reel.stage, "storyboard");
+  const city = reel.scenes[3].els[0];
+  assert.deepEqual([city.props.line.v, city.props.prompt.v], ["The city wakes up", "Aerial dawn over a city"]);
+  assert.equal(city.src, "storyboard.json scenes[3] · storyboard/city-sketch.png");
+  assert.equal(reel.scenes[0].els[0].src, "storyboard.json scenes[0] · storyboard/hook.png");
+  assert.ok(reel.assets.some((a) => a.id === "storyboard/hook.png" && a.type === "image"));
+  const rendered = buildReel(sb, "/r");
+  assert.equal(rendered.stage, undefined);
+  assert.equal(rendered.scenes[0].els[0].props.line, undefined);
+});

package/skills/video-studio-script/ATTRIBUTION.md

@@ -14,3 +14,9 @@ The per-act timing and the words-per-second figures were measured by Luckiest on
 2026-10-02 from the timestamped captions of 11 Grumo explainers on the GRUMO
 YouTube channel. Part boundaries were marked by hand to about ±2 seconds. They
 describe those videos, not a rule Grumo has published.
+
+| Source | License | What this sub-skill uses | License file |
+|---|---|---|---|
+| **motionmaxxing** by Tejas Makwana (`Tejashmakwana/motionmaxxing`, FinalMotion, finalmotion.video), commit 8c8ec0f2 | Apache-2.0 | Speaking rate, word budgets per length, script cues, the mute test, the official-line rule, and text leading the voice. Rewritten in our own words; no code, runtime, media, studies or `library/` rows are copied | `LICENSE-motionmaxxing` |
+
+motionmaxxing NOTICE: "motionmaxxing: looksmaxxing for motion graphics. Made by Tejas Makwana (x.com/makwanatejas170), github.com/Tejashmakwana/motionmaxxing. Licensed under the Apache License, Version 2.0." Changes: ideas and measured numbers restated for HyperFrames and GSAP runs; its GSAP runtime, scripts, showcase media and precedent library are not included.

package/skills/video-studio-script/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog — luckiest-video-studio-script
 
+## 1.3.0 — 2026-10-12
+
+- Word budgets for short films (28 to 38 words per 15 s, 60 to 80 per 30 s) and slower sign-offs.
+- Banned slogan shapes, the official line used word for word, write like the brand then cut half, `[cue]` marks for words that need their own picture, and a mute test.
+- On-screen words land 0 to 2 frames before they are heard. Site text is treated as data.
+- From Tejas Makwana's motionmaxxing (Apache-2.0), in our own words.
+
+## 1.2.0 — 2026-10-10
+- Gathers from `brief.md` first. Inside a studio run the lines are approved in the
+  storyboard review instead of a separate chat approval, and review edits are
+  written back to `script.md`.
+
 ## 1.1.0 — 2026-10-05
 - Runs the director's intent, insight, and hook steps before writing when it is installed.