belt-trailer 0.1.0

data/skills/belt-trailer/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: belt-trailer
+license: MIT
+description: >-
+  Make a launch trailer of a web app from the app itself with belt-trailer:
+  write the storyboard, build the showcase and its story fixtures, script the
+  beats (camera, titles, sounds) in trailer.config.mjs, film, review the frames,
+  cut with music, and pass `belt trailer check`. Use when asked to make, film,
+  re-film, fix or review a trailer, launch video, promo video or App Store
+  preview of a web app, or when working with trailer.config.mjs, a showcase,
+  `belt generate trailer`, `belt trailer film|cut|check`, or the belt-trailer
+  engine (engine/bin/trailer.mjs). Do NOT activate for movie trailers, video
+  editing of footage that wasn't filmed from the app, or vehicle trailers.
+metadata:
+  author: stowzilla
+  version: "0.1.0"
+---
+
+# belt-trailer
+
+belt-trailer films a web app's real screens a frame at a time (1080p, 30 fps),
+with a camera that pushes and pans, titles in the app's own fonts, and the sound
+effects the app plays as it's filmed. It cuts the shots together with music,
+levelled to −14 LUFS, and `check` says whether the result is fit to publish.
+
+Your job as the agent is the part the engine can't do: **decide what the trailer
+says, build the states it films, script every shot, and look at the result with
+a critical eye.** The engine handles the plumbing. Don't reimplement any of it.
+
+## First: orient yourself
+
+0. Find the gem: `bundle show belt-trailer` prints its directory, written
+   `<gem>` here.
+   If this skill was installed with `npx skills add` and the gem is a different
+   version, `belt trailer guide` prints the copy that matches the gem; prefer it.
+1. Is there a `trailer.config.mjs` in the frontend (usually `frontend/`)? If not,
+   run `belt generate trailer --url <the app's address>`. Outside Belt, copy
+   the config and showcase from `<gem>/lib/belt/trailer/templates/`.
+2. Is there a showcase? Look for `scripts/showcase/` or `scripts/screenshots/`
+   with a `build.mjs`, and `?view=` handling in a showcase page. The generator
+   finds an existing one and films that.
+3. Is there a storyboard? `trailer-storyboard.md` beside the config (the
+   generator writes a template). **If it's empty, write it first and get it
+   agreed with a person before scripting beats.** A storyboard is cheap to
+   change; filmed beats aren't.
+4. Can it film? `belt trailer film --only <first beat> --format wide` must get
+   past the requirements check (Node, ffmpeg, Playwright's Chromium in the
+   frontend). It names whatever is missing.
+
+`<gem>/examples/posh-nosh/` is a finished, reviewed trailer. Read it before
+writing beats; most problems you'll meet are solved there.
+
+## The workflow
+
+| Step | You produce | Reference |
+|---|---|---|
+| 1. Storyboard | `trailer-storyboard.md`: 5–7 beats, 20–30 s, each with what's on screen, the camera, the words, why | [references/storyboard.md](references/storyboard.md) |
+| 2. Showcase + story | Fixtures for every state each beat shows, as one session moving forward, plus the `?sound=1` hook and any triggers | [references/showcase-and-fixtures.md](references/showcase-and-fixtures.md) |
+| 3. Beats | `beats: [...]` in `trailer.config.mjs`: `play()` scripts | [references/beats.md](references/beats.md) |
+| 4. Film, look, fix | One beat at a time, wide first, reviewed from contact sheets and frames | [references/reviewing.md](references/reviewing.md) |
+| 5. Cut + check | `belt trailer cut`, `belt trailer check` until PASS, then a person watches it | [references/reviewing.md](references/reviewing.md) |
+
+Iterate on one beat in one format: `belt trailer film --only hook --format wide`.
+A beat takes about a minute to film; the whole trailer in both formats takes
+10+. Film both formats only once the wide one is right, and check tall framing
+separately (`cam.tall` branches).
+
+## Golden rules
+
+- **You can't watch video. Look at frames.** Every claim that a shot "works" must
+  come from images you've looked at: the contact sheet, then single frames around
+  every cut, move and title. Never report a trailer as done from `check` alone.
+  `check` measures sound, length and title clearance, not whether the shot is good.
+- **Film the real app.** No mock components drawn for the trailer, no faked
+  numbers the app can't produce, no sounds added that the app doesn't play. If
+  a shot needs a state, make a fixture with the data the server would really send.
+- **One story.** Every gameplay/product shot is the same session at a later
+  moment: same records, same people, same names. Build fixtures from one function.
+- **Pace for reading.** Each title is up, fully landed, about 2 s. A moment the
+  viewer has to follow gets 2–3 s. Titles leave 0.8 s before the cut (built in).
+- **Words go where nothing important is**, and in the product's voice. Never on
+  the subject or the controls.
+- **Music on the first frame.** A silent cold open reads as a broken video.
+- **Don't fight the engine.** If a beat seems to need something the config
+  can't express, say so (a Fizzy card on belt-trailer) rather than patching
+  around it in the app or forking engine code into the app.
+- **Ask a person before publishing.** Rights to every audio file (`check` lists
+  them), and the end card names only what's live.
+
+## Commands
+
+```bash
+belt generate trailer [--url ADDRESS] [--frontend NAME]   # scaffold
+belt trailer film  [--only a,b] [--format wide|tall|both] [--clean] [--keep-frames] [--sounds bundled]
+belt trailer cut   [--format …] [--music PLAN]
+belt trailer check [--format …] [--music PLAN]            # exit 1 on FAIL
+belt trailer guide                                        # print this skill
+```
+
+Output goes to `<frontend>/tmp/trailer/`: `<beat>-<format>.mp4` (titled),
+`-clean.mp4` (no titles), `.json` (sounds captured with their times, marks),
+`trailer-<format>.mp4`, `trailer-<format>.json` and `trailer-<format>-sheet.png`.
+
+Outside Belt: `node <gem>/engine/bin/trailer.mjs film --app <frontend dir> …`
+with the same options.
+
+## When something goes wrong
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `drag: nothing matches …` / camera doesn't move | Selector matches nothing, or the element isn't rendered yet in that fixture | Check the selector against the fixture; `cam.boxOf(sel)` returns null when nothing matches |
+| Camera "moves" but frame stays wide | The padded box is wider than the page, so it fits to the whole page | Smaller `pad`; a full-width element (an `h1`) needs `pad` ≈ 0.1 |
+| Push-in snaps | Push of >1.5× in under 0.9 s | `ms: 900` or more, eased |
+| Framed the wrong place | Measured mid-entrance-animation | `cam.hold()` until it lands, then `focus` |
+| A sound is missing | The fixture change doesn't include the event that triggers it | Make the next fixture carry the data the server would send (the log line, the event) |
+| Sound plays but `check` says it's off its frame | Usually the source file has a long or quiet lead-in | Look at the file; a masked sound (under another) is reported, not failed |
+| `check` loudness fails | No music, or a very quiet/loud plan | Add tracks to `music.plan`; don't hand-tune gains, the cut levels it |
+| Title on screen at a cut | A title cued too late in the beat | Cue it earlier or lengthen the beat; ~2 s landed + 0.8 s before the cut |
+| Same beat looks different each take | Drag beats can differ run to run (known) | Judge from the take you have; re-film if a take is bad |
+| Fonts wrong in titles | `@font-face` URLs don't resolve from the showcase build | Point them at files in `public/` (served at `/`) |
+
+## Deeper references
+
+- [references/storyboard.md](references/storyboard.md): writing the storyboard, a template, timing budget, words
+- [references/showcase-and-fixtures.md](references/showcase-and-fixtures.md): the showcase, story fixtures, sound hook, triggers, canned API
+- [references/beats.md](references/beats.md): the `play()` API, camera recipes, tall vs wide, config options
+- [references/reviewing.md](references/reviewing.md): looking at frames, the review checklist, reading `check`, when it's done
+- `<gem>/README.md` ([on GitHub](https://github.com/stowzilla/belt-trailer#readme)): the full config reference and how the engine works

data/skills/belt-trailer/references/beats.md

@@ -0,0 +1,136 @@
+# Scripting beats
+
+A beat is one entry in `beats` in `trailer.config.mjs`:
+
+```js
+{ name: 'dragon', view: 'trailer-dragon-offer', query: 'chat=off', css: '…', settle: 800,
+  play: async ({ page, cam, setView, drag, fire, ease, tall, format }) => { … } }
+```
+
+The page opens on `view`, settles, and `play` films it. **Frames are only
+filmed by `cam.hold`, `cam.move` and `cam.shoot`.** Everything else
+(`focus`, `title`, `setView`) happens between frames, so the timing of a beat
+is the sum of its holds and moves.
+
+## The API
+
+| Call | Does |
+|---|---|
+| `await cam.hold(ms)` | Film for `ms` |
+| `await cam.focus(sel, { ms, pad, top, right, bottom, ease })` | Frame the union of everything matching `sel` (a selector or array) over `ms`; `ms: 0` (default) cuts |
+| `await cam.punch(sel, opts)` | A fast focus: 260 ms, ease out |
+| `cam.look(rect, ms, ease)` | Frame a page rect `{ x, y, w, h }` |
+| `cam.shake(ms, px)` | Shake, fading out over `ms` |
+| `await cam.move(from, to, ms)` | Move the pointer `{x, y}` → `{x, y}`, filming |
+| `cam.title({ kicker, line, place })` | Title in from this frame; `place`: `side`, `band`, `top`, `bottom`, or `{ wide, tall }` |
+| `cam.untitle()` | Send the title out now |
+| `cam.endCard()` | The end card (from `titles.endCard`) |
+| `cam.mark('hush')` | Music stops here in the cut |
+| `await cam.boxOf(sel)` | `{ x, y, w, h }` or null |
+| `cam.tall` / `tall` | Filming the tall format |
+| `await setView(name)` | Switch fixture without reloading |
+| `await drag(from, to, { ms, hold })` | Press `from`, carry to `to` over `ms`, hold, release (filmed) |
+| `await fire(name, ...args)` | `window[name](...args)` on the page |
+| `ease.inOut`, `ease.out`, `ease.linear` | Curves for `focus` |
+| `page` | The Playwright page, for anything else |
+
+`pad`, `top`, `right` and `bottom` are **fractions of the subject's size**.
+`pad: 0.1` is 10% all round; `right: 0.6` adds 60% of its width on the right
+(room for a `side` title). The result is fitted to the format's aspect and kept
+on the page, so a padded box wider than the page means the whole page.
+
+## Recipes
+
+**Open wide, push in.** Cut to the establishing frame, hold, then move:
+
+```js
+await cam.focus(['.board'], { pad: 0.03 });               // cut
+await cam.hold(300);
+await cam.focus('.card.active', { ms: 1000, pad: 0.3 });  // >1.5× push: ≥0.9 s
+await cam.hold(400);
+```
+
+**A hit.** Change state, punch in, shake, hold long enough to read the result:
+
+```js
+await setView('trailer-hit');
+await cam.punch('.enemy >> nth=1', { pad: 0.3 });
+cam.shake(400, 10);
+await cam.hold(1600);
+```
+
+**A title beside the subject (wide) or in the band (tall):**
+
+```js
+await cam.focus('.chart', { ms: 900, pad: 0.1, right: tall ? 0 : 0.7, top: tall ? 0.9 : 0 });
+await cam.hold(300);                       // let the move land first
+cam.title({ kicker: 'Every number, live', line: 'Watch it move', place: { tall: 'top' } });
+await cam.hold(2900);                      // ~0.6 s landing + 2 s read + the 0.8 s exit
+```
+
+**A dialog the viewer has to follow:** frame the dialog, slow drift (linear),
+hold each step ~0.5–1.3 s, and only title the result:
+
+```js
+await cam.focus('.dialog', { pad: 0.12 });
+await cam.focus('.dialog', { ms: 2600, pad: 0.04, ease: ease.linear });
+await cam.hold(700);
+await page.mouse.move(2, 2);               // pointer off anything with a hover state
+await setView('trailer-dialog-done');
+await cam.hold(1300);
+```
+
+**Hand over to the next beat.** End on the framing the next beat opens with:
+
+```js
+// end of beat A
+await cam.focus(['.ally', '.foe'], { ms: 1000, pad: 0.06, right: 0.6 });
+await cam.hold(1100);
+// start of beat B: same selectors, same options, ms 0
+await cam.focus(['.ally', '.foe'], { pad: 0.06, right: 0.6 });
+```
+
+**Something arriving on cue** (a message, a notification):
+
+```js
+await fire('__say', 'Is that all you’ve got?', '1');
+await cam.hold(450);                       // let the bubble pop before framing it
+await cam.focus(['.bubble.theirs', '.foe >> nth=3'], { ms: 450, pad: 0.35, ease: ease.out });
+await cam.hold(1300);
+```
+
+**The end card:**
+
+```js
+{ name: 'end', view: 'home', css: '#root { filter: blur(5px) brightness(0.6) saturate(0.8); }',
+  play: async ({ cam, ease }) => {
+    await cam.focus('#root', { pad: -0.08, ms: 3800, ease: ease.linear });
+    cam.endCard();
+    await cam.hold(3800);
+  } },
+```
+
+## Wide and tall
+
+The same beat films both formats: wide from a 1280×720 page, tall from a
+432×768 phone layout. The app's layout differs between them, so selectors and
+room for words differ too. Branch on `tall`:
+
+- Wide: words `side`, camera leaves `right` room.
+- Tall: words in the `band` across the middle, or `top` when the camera is in
+  close; the camera leaves `top` room instead of `right`.
+
+Get wide right first, then film `--format tall` and review it separately.
+
+## Rules that are easy to break
+
+- **Frame after entrance animations finish.** `boxOf` measures now; mid-pop the
+  box is the wrong size. `hold` first.
+- **Keep the pointer off hover states** unless the hover is the point:
+  `page.mouse.move(2, 2)`. A hovered card lifts, then lifts again when picked.
+  There's no cursor in the video anyway.
+- **Hide the app's heading** (`beat.css`) when a title replaces it.
+- **Don't wait on wall time** (`page.waitForTimeout`) inside `play`. The page's
+  clock only moves with frames; use `cam.hold`.
+- **Throwing is fine.** `drag` throws when a selector matches nothing. Fix the
+  selector or the fixture; don't wrap it in try/catch to film around it.

data/skills/belt-trailer/references/reviewing.md

@@ -0,0 +1,90 @@
+# Reviewing what you filmed
+
+You can't watch the video. You review it as images, and that's enough if you
+look in the right places. **Never call a beat done without looking at its frames.**
+Read a few images at a time, not dozens at once.
+
+## The loop for one beat
+
+```bash
+belt trailer film --only dragon --format wide
+cd frontend/tmp/trailer
+# 1. The whole beat at a glance: 3 frames a second, with timestamps
+ffmpeg -y -loglevel error -i dragon-wide.mp4 \
+  -vf "fps=3,scale=320:-2,drawtext=text='%{pts\:hms}':x=4:y=4:fontsize=14:fontcolor=yellow,tile=6x4" \
+  -frames:v 1 dragon-sheet.png
+# 2. Single frames where it matters (seconds)
+ffmpeg -y -loglevel error -ss 2.1 -i dragon-wide.mp4 -frames:v 1 dragon-2.1.png
+# 3. What it played, and when
+cat dragon-wide.json
+```
+
+Look at the sheet first, then single full-size frames at:
+
+- **the first and last frame** (compare the last with the next beat's first frame),
+- **every camera move**, its start, middle and end (a 0.9 s move is ~27
+  frames; look at 3 of them),
+- **every title** once fully landed (~0.8 s after its cue) and as it leaves,
+- **every state change** (`setView`, `drag`, `fire`): the frame before and ~0.5 s after,
+- **every sound** in the `.json`: the frame at its time should show its cause.
+
+For a move that looks wrong, step through it frame by frame:
+`ffmpeg -ss 1.8 -t 1 -i dragon-wide.mp4 -vf "fps=15,scale=480:-2,tile=5x3" -frames:v 1 move.png`.
+
+## The checklist per beat
+
+Answer each one from the frames:
+
+- [ ] The first frame is a picture, not a blank, a spinner or a half-rendered page.
+- [ ] The subject is in frame and sharp, and nothing important is cut off at the edges.
+- [ ] Every move is smooth: no snap (a push covering the distance in 2–3
+      frames), no flash of the wide view on a cut.
+- [ ] The words are fully on screen, readable at the sheet's size, and not on
+      the subject, a hand of cards, the controls or a face.
+- [ ] Each title is fully landed for ~2 s (count frames: 60 at 30 fps).
+- [ ] No title is on screen in the last 0.8 s.
+- [ ] The app's own heading isn't showing through under a title.
+- [ ] No hover lift, tooltip or focus ring the shot isn't about.
+- [ ] Same records, people and numbers as the beats either side.
+- [ ] The last frame matches the next beat's first frame in framing.
+- [ ] Every expected sound is in the `.json` (and nothing odd, like a sound from
+      the page loading).
+- [ ] **Tall:** the same again; the words are in the band or at the top, not on
+      the hand or the controls.
+
+Fix the beat or its fixture, re-film just that beat, and look again. When a
+fix is about pacing, change hold lengths; when it's about framing, change
+`pad`, `top`, `right` or `bottom`; when a sound or animation is missing, the
+fixture is missing data.
+
+## The cut
+
+```bash
+belt trailer cut --format wide
+belt trailer check --format wide
+```
+
+`check` exits 1 on FAIL and prints a line per measurement:
+
+| Line | When it fails |
+|---|---|
+| audio starts at 0 / audio vs video length | The cut is broken; re-run `cut`. If it persists, report it on belt-trailer |
+| loudness −14 ±1 LUFS | Usually no music (−70 LUFS is silence): add tracks to `music.plan` |
+| true peak below −1 dBFS | A clipped source file; find it in the audio list and tell a person |
+| at most 30 s | Cut a beat or shorten holds; don't speed up the reading time |
+| `<beat>`: effects n/m on their frame | A sound landed late: look at the source file's lead-in. "Under another sound" is reported, not failed |
+| `<beat>`: no title in the last 0.5 s | A title is still up at the cut: cue it earlier or lengthen the beat |
+
+Then look at `trailer-wide-sheet.png` (2 fps, the whole trailer) and at the
+frames either side of **every cut** (the cut times are in
+`trailer-wide.json`, `beats[].start`).
+
+## When it's done
+
+- `check` passes in both formats.
+- You've looked at every beat's frames against the checklist, in both formats.
+- You report: the length, the check output, the sheets (attach them), every
+  audio file in the cut with where it came from, and anything you weren't sure
+  about.
+- **A person watches it with sound before it's published**, and answers the
+  rights question for every audio file. You don't publish it.

data/skills/belt-trailer/references/showcase-and-fixtures.md

@@ -0,0 +1,80 @@
+# The showcase and the story
+
+belt-trailer films a **showcase**: the app's screens rendered from hand-written
+states (fixtures), with no backend and no one clicking. This is where most of a
+trailer's work is, and it's app-specific: the engine can't write it for you.
+
+## What a showcase is
+
+- A page built with Vite (`scripts/showcase/build.mjs`, `showcase.html`,
+  `showcase.jsx`) that renders one fixture, chosen by `?view=<name>`.
+- `window.__setView(name)` switches to another fixture **without reloading**.
+  This matters: the app's components see a state change, as when a real update
+  arrives, so they run their own animations and play their own sounds. A beat
+  is mostly "open on fixture A, `setView('B')`, film what the app does".
+- API calls never reach a server. The generated showcase answers them from the
+  current fixture's `api` map; anything left goes to `api` in
+  `trailer.config.mjs` (Playwright route interception). Modules that need the
+  network (sign-in, analytics) are swapped for mocks in `build.mjs` (Posh Nosh
+  swaps its Cognito module with a Vite `resolveId` plugin).
+
+`belt generate trailer` writes a minimal one for a Belt React frontend (the app
+inside a `MemoryRouter`, one `home` fixture). If the app already has a showcase
+for screenshots, the generator films that instead. Extend it; don't build a
+second one.
+
+## Fixtures for a trailer
+
+1. **One story.** Write a function that builds the session at any moment
+   (Posh Nosh: `storyG(options)` in `fixtures.js`) and make every trailer
+   fixture from it: `trailer-start`, `trailer-hit`, `trailer-won`. Never borrow
+   a screenshot fixture with different records: a unit, person or number that
+   changes between cuts reads as a different session, and viewers notice.
+2. **One fixture per state change**, holding **the data the server would really
+   send** after it. Sounds and animations come from the difference between two
+   states: if the app plays a knockout sound when a log line says "fell", the
+   next fixture needs that log line. A missing event is a missing sound.
+3. **Realistic content.** Real-looking names, amounts and dates in the product's
+   voice. No lorem ipsum, no "Test User", no numbers the product can't produce.
+4. **Name them for the beat**: `trailer-<what happens>`, so the config reads
+   as the storyboard.
+
+## The two hooks a trailer needs
+
+Both behind query flags, so screenshots are unaffected:
+
+- **`?sound=1`** mounts the app's own sound hooks or provider in the showcase,
+  so it plays what it would. The config sets `showcase.query: { sound: 1 }`.
+  Without this, the trailer has no effects.
+- **A trigger for timed events.** Anything the app does on a timer or from a
+  socket (a message arriving, a notification) should be fired on cue instead:
+  expose it on `window` in the showcase (Posh Nosh: `window.__say(text, from)`)
+  and call it from a beat with `fire('__say', 'Hello', '1')`.
+
+## Page setup in the config
+
+- `page.css`: CSS for every beat (hide a chat panel that's never the subject).
+- `page.init`: runs before the app on every page; set the `localStorage` that
+  skips welcome screens and turns sound on. It's serialised into the page, so it
+  can't use variables from the config file.
+- `beat.css`: CSS for one beat (hide the heading a title replaces; blur the
+  background of the end card).
+- `unlock`: how the app's audio gets unlocked (default: a key press, as a first
+  tap). Change it only if the app waits for a click on something specific.
+- `settle`: how long the page's own clock runs before filming (default
+  1500 ms). Shorten it for a beat whose moment is on a timer from load.
+
+## Sounds the app gets from somewhere else
+
+If someone can replace the app's sounds on the live site, set
+`sounds.live: { origin, paths }`: those paths are answered from the live site
+and its files cached, so the trailer plays what the live app plays.
+`--sounds bundled` uses the files in `sounds.bundled` (default `public/`)
+instead. List music URLs in `sounds.ignore` so they aren't captured as effects:
+music is laid under the cut from `music.tracks`.
+
+## Checking a fixture before filming
+
+Build and open the showcase in a browser (or a quick Playwright script) at
+`?view=<fixture>` and look at it. A fixture that doesn't render is much faster
+to find there than in a filmed beat.

data/skills/belt-trailer/references/storyboard.md

@@ -0,0 +1,87 @@
+# Writing the storyboard
+
+Write it before any beat, in `trailer-storyboard.md` beside `trailer.config.mjs`,
+and get a person to agree it. Everything after (fixtures, beats, filming) follows
+from it, and changing it later means re-filming.
+
+## Before the shots: who and what
+
+Answer these in the storyboard's first section, from the app's own site, README,
+store listing and meta description. Don't invent a pitch the product doesn't make.
+
+- **Who is it for**, in one sentence, and what are they doing when they'd want it?
+- **The offer in one line.** Usually already written: the meta description, the
+  store subtitle. The trailer proves it rather than replacing it.
+- **What makes it different, in order of how fast it reads on screen.** Motion
+  and visuals read in a second; "no sign-up" reads in two; depth takes a shot of
+  its own. That order is roughly the order of the beats.
+- **What not to lead with.** Usually the rules, settings or onboarding. Nobody
+  learns an app from a 25-second trailer; they decide whether it looks worth trying.
+
+## The shots
+
+Five to seven beats, 20–30 s in all (30 s is the App Store preview limit,
+and `check` enforces it). One table, a row per beat:
+
+| Time | Beat | Fixture(s) | Camera | On screen (words) | Why it's here |
+|---|---|---|---|---|---|
+| 0–2.8 s | `hook` | `board-fresh` → `board-hit` | wide on the board, slams in on the hit, shake | no words | something happens in the first second |
+| … | | | | | |
+| last 3.5–4 s | `end` | `home` (blurred) | slow drift | logo · the offer · terms · the address | the call to action, held long enough to type |
+
+The beat names are yours (`--only` takes them), lower-case, one word.
+
+### The shape that works
+
+1. **Hook (2–3 s), no words.** The most striking thing the app does, mid-action
+   on the first frame. Not a logo, not a title card, not a loading screen.
+2. **Two to four beats, each one idea**, each with one title: the choice
+   that makes it yours, the depth, the biggest moment, the tone.
+3. **The payoff.** The result the viewer wants (the win, the finished report,
+   the shipped thing), earned by the beats before it.
+4. **End card (3.5–4 s).** Logo, the offer, the terms ("Free · No account
+   needed") and the address, on the app softened behind it.
+
+### Timing budget
+
+- A titled beat: ~0.5 s to settle, ~0.6 s for the words to land, **2 s fully
+  landed**, then out **0.8 s before the cut**. That's about 4 s minimum.
+- A moment to follow (a dialog, a choice, its result): **2–3 s on its own**,
+  with its title held back until the result is on screen.
+- A push-in of more than 1.5× takes **at least 0.9 s**.
+- Add the beats up in the table's Time column. Over 30 s means cut a beat, not
+  speed them all up: Posh Nosh's first cut at 22 s was too fast to read, and
+  the finished one is 29.2 s.
+
+### Continuity
+
+- Every product shot is **the same session at a later moment**: the same
+  records, people, names and numbers moving forward. Say so in the
+  storyboard and name the fixture function that builds them.
+- **Match framing across cuts**: end a shot on the framing the next one opens
+  with. Write the end framing and the next opening framing in the Camera column.
+
+## Words
+
+- **Short enough to read twice in 2 s**: a kicker of 2–5 words over a line of
+  2–4 words. "Every unit has an ability" over "Out-play your rival".
+- **In the product's voice.** Read the app's own copy first. Words that don't
+  fit get noticed straight away ("darling" didn't fit Posh Nosh).
+- **Where nothing important is.** Say where in the table: `side` (a panel on
+  the right of a wide frame, the camera leaving room), `band` (across the
+  middle of a tall frame), `top` or `bottom`. Never on the subject or the controls.
+- The app's own text can be the words (Posh Nosh's chat bubbles were its
+  banter beat's words). Hide the app's own heading when a title replaces it.
+
+## Sound
+
+Write one line per beat: which music, and which effects the viewer should hear
+(they come from the app; if a beat needs a sound the app doesn't play there, the
+beat is wrong, not the sound). Music from the first frame; a `hush` mark where
+the music should stop (a win, say). Note where every audio file comes from:
+**rights for advertising need a person's answer before anything is published.**
+
+## Open questions
+
+End with what a person has to decide: rights, paid content on screen, which line
+of copy, where it launches. Don't decide these yourself.

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: belt-trailer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Stowzilla
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: belt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.4
+description: Belt plugin that films an app's real screens a frame at a time with Playwright,
+  at 1080p and 30 fps, with a moving camera, titles in the app's own fonts and the
+  sound effects the app plays; cuts the beats together with music levelled to -14
+  LUFS; and checks whether the cut is fit to publish. The engine is plain Node and
+  works for any website.
+email:
+- andy@stowzilla.com
+- adam@stowzilla.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- AGENTS.md
+- CHANGELOG.md
+- LICENSE
+- README.md
+- engine/bin/trailer.mjs
+- engine/lib/args.mjs
+- engine/lib/camera.mjs
+- engine/lib/check.mjs
+- engine/lib/clock.mjs
+- engine/lib/config.mjs
+- engine/lib/cut.mjs
+- engine/lib/ease.mjs
+- engine/lib/ffmpeg.mjs
+- engine/lib/film.mjs
+- engine/lib/index.mjs
+- engine/lib/showcase.mjs
+- engine/lib/sound.mjs
+- engine/lib/titles.mjs
+- engine/package.json
+- engine/titles.html
+- examples/posh-nosh/trailer-titles.css
+- examples/posh-nosh/trailer.config.mjs
+- lib/belt-trailer.rb
+- lib/belt/commands/trailer_command.rb
+- lib/belt/generators/trailer_generator.rb
+- lib/belt/trailer.rb
+- lib/belt/trailer/templates/showcase/build.mjs
+- lib/belt/trailer/templates/showcase/fixtures.js.erb
+- lib/belt/trailer/templates/showcase/showcase.html
+- lib/belt/trailer/templates/showcase/showcase.jsx
+- lib/belt/trailer/templates/trailer-storyboard.md.erb
+- lib/belt/trailer/templates/trailer-titles.css
+- lib/belt/trailer/templates/trailer.config.mjs.erb
+- lib/belt/trailer/version.rb
+- skills/belt-trailer/SKILL.md
+- skills/belt-trailer/references/beats.md
+- skills/belt-trailer/references/reviewing.md
+- skills/belt-trailer/references/showcase-and-fixtures.md
+- skills/belt-trailer/references/storyboard.md
+homepage: https://github.com/stowzilla/belt-trailer
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/stowzilla/belt-trailer
+  source_code_uri: https://github.com/stowzilla/belt-trailer
+  changelog_uri: https://github.com/stowzilla/belt-trailer/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.24
+specification_version: 4
+summary: Film a launch trailer of a web app from its own screens and sounds
+test_files: []