reelson 0.7.0

package/demo.config.example.json

@@ -0,0 +1,51 @@
+{
+    "$schema": "./skills/reelson-record/schemas/demo.config.schema.json",
+    "$comment": "Copy to <project>/demo.config.json (or run `reelson init`). Every field is optional; defaults in skills/reelson-record/scripts/config.ts.",
+    "videosDir": "docs/videos",
+    "language": "en",
+    "locale": "en-US",
+    "brand": {
+        "name": "YOUR BRAND",
+        "tagline": "PRODUCT",
+        "eyebrow": "Your Brand",
+        "color": "#dc2626",
+        "colorSoft": "#f87171",
+        "logo": null
+    },
+    "template": "classic",
+    "sections": {
+        "intro": "poster",
+        "recap": "steps",
+        "outro": "wordmark"
+    },
+    "strings": {
+        "recapTitle": "In short",
+        "stepsLabel": {
+            "one": "step",
+            "other": "steps"
+        },
+        "secondsLabel": {
+            "one": "second",
+            "other": "seconds"
+        }
+    },
+    "music": {
+        "file": null,
+        "lufs": -28,
+        "lufsUnderNarration": -34
+    },
+    "record": {
+        "viewport": {
+            "width": 1440,
+            "height": 900
+        },
+        "deviceScaleFactor": 2,
+        "extraHTTPHeaders": {
+            "X-Demo-Recording": "1"
+        },
+        "hideSelectors": [],
+        "personaDomain": "example.com",
+        "cursor": "layer",
+        "capture": "screencast"
+    }
+}

package/docs/prompting.md

@@ -0,0 +1,72 @@
+# How to ask for a video
+
+The prompt is the spec. A complete prompt has six parts; the more you give, the fewer guesses
+Claude makes and the fewer re-renders you need.
+
+```
+Make a demo video of <FEATURE>.
+
+Where:      <URL / area + account>            e.g. the admin area on https://app.test as the admin user
+Steps:      1. ... 2. ... 3. ...              what the viewer should see happen, in order
+Callouts:   <one short imperative per step>   in the UI's language, matching its labels
+Cards:      title "...", subtitle "..."        recap title, intro/recap/outro sections optional
+Emphasis:   zoom on <what> during step <n>     only where the UI is small
+Output:     mp4 (default) / also gif           slug: <kebab-case>
+```
+
+Claude writes the scenario, records, verifies frames, builds the composition, words the
+callouts in video.json, checks, renders, and reports the file path with a few extracted frames.
+
+## Example prompts
+
+**A first video for a feature**
+
+> Make a demo video of searching a customer. Admin area on https://app.test as the admin.
+> Steps: open Customers, type the first customer's first name in the table search, hover the
+> matching row. Callouts: "Open Customers", "Type the name in Search". Title "Find a customer",
+> subtitle "Search any customer from the list". Zoom on the search box while typing.
+> Slug customers-search.
+
+**A create flow with a modal**
+
+> Demo video: creating a customer. Customers → New customer, fill name/email/phone with a
+> persona, save, show the success notification and the new row. One callout per step, zoom on
+> the form while filling. Title "Add a customer". Trim the login away.
+
+**A two-actor flow**
+
+> Demo of a document approval: a manager sends a document from the admin area, then the
+> employee accepts it in their personal area. One scenario; switch accounts inside
+> `demo.transition()` with a "Manager → Employee" card. ~40 s max.
+
+**Through an external payment page**
+
+> Demo of the shop checkout paid by card, no login: product → add to cart → checkout → card
+> payment on the gateway's test page with its test card → cut the 3-D Secure wait → success
+> page. Accept the cookie banner first. Zoom on the payment-method choice and the card form.
+
+**Re-record after a UI change**
+
+> The customers table got new columns. Re-record <videosDir>/customers-search with the
+> existing scenario, re-render with the current video.json, and show me
+> frames at each callout.
+
+**Tweak an existing video (no re-record)**
+
+> In <videosDir>/customers-search, change callout 2 to "Search by name or email", make the zoom
+> tighter (scale 2.0) and 1 s shorter, then re-render.
+
+**Different output**
+
+> Render <videosDir>/customers-search also as a 15 fps GIF for the README.
+
+**Another intro or outro**
+
+> Render <videosDir>/customers-search with the `minimal` intro, no recap and the `endcard`
+> outro, next to the current one so I can compare.
+
+**Narrated recording (manual, OpenScreen)**
+
+> I recorded <videosDir>/onboarding-tour/recording.mp4 myself with OpenScreen, with voiceover.
+> Build the composition around it: title "Platform tour", callouts at 0:04 "Main menu",
+> 0:12 "Company settings", 0:21 "Invite colleagues". Keep the narration.

package/docs/style-guide.md

@@ -0,0 +1,117 @@
+# Style guide
+
+The house style for every video made with the kit. The scripts, the `classic` template and
+every kit section already implement it; this page exists so a fresh session knows *why* and doesn't undo it.
+A project can tighten these rules in its own docs (e.g. its payment test cards or seeded
+accounts), but should not loosen them without a reason.
+
+## Standing instructions
+
+1. **Structure**: intro → framed recording with numbered callouts and zooms → recap (optional)
+   → outro. Intro, recap and outro are sections picked per project or per video; the classic
+   set is the poster cover, a recap with the title left and ONE column of numbered steps right,
+   and a wordmark card (letters growing in from farther out, line wiping from the left). The
+   video **ends on the brand**, never on an empty frame: the last frame is what players show
+   when playback stops. `wordmark` and `compact` settle at 15 % opacity; `endcard` stays fully
+   readable. No URLs on any card.
+2. **Intro = poster**: **frame 0 shows the brand and the title legibly** — chat apps, GitHub
+   and Finder use it as the thumbnail — never hidden or blurred. The classic `poster`: wordmark,
+   accent line, tagline, then title, subtitle and the "N steps · S seconds" chip, centred; at
+   t=0 everything is big (130 %) and 60 % transparent. It "breathes" down into place (sine.inOut,
+   letters one after another from the centre), holds ~1.8 s, and at 3.0 s lifts out through
+   the top while the recording rides in from below on the same upward motion. Other intros
+   keep the poster rule and hand over with `stage.enter()`.
+3. **Background**: deep navy gradient with four soft glows (brand colour, blue, violet, teal)
+   drifting and breathing on 4–6.5 s loops — slow but perceptible — plus a faint dot grid.
+4. **Cursor**: large black macOS-style arrow with a white outline, press squash, and a
+   brand-coloured double ring on click. It never jumps on click, and it keeps its size
+   during zooms (the video draws it as a layer from the recorder's log).
+5. **Motion**: gently curved, eased mouse paths with a little tremor, landing slightly
+   off-centre; typing with uneven per-key delays. Human, never slow. The recording opens with
+   the cursor resting in the middle third of the screen, never jumping in from a corner.
+6. **People**: realistic names and emails in the UI's language from `demo.persona()`. Never
+   `test@`, `e2e-123` or seeded-looking data typed on camera.
+7. **Payments / external services**: use the provider's test mode and test data, the page in
+   the UI's language, and remove waits (3-D Secure, redirects) with `demo.cut()`.
+8. **Audio**: one music bed per project (`music.file`) under every video at −28 LUFS with
+   fades; −34 LUFS under narration. Don't pick a different track per video.
+9. **Quality**: capture at 2x (2880x1800 for 1440x900, CRF 15) so text stays sharp in the
+   1080p frame and under zooms; render with `--video-frame-format jpg -q delivery`; keep
+   `media.autoProxy: false` and no `will-change` on `#frame`.
+10. **Language**: the product UI's language. Callouts are imperative steps (≤ 6 words)
+    because they also become the recap. **At most 10 steps** per video.
+11. **Nothing pre-filled on camera**: the recorder sends `X-Demo-Recording: 1`; the app should
+    skip local-only prefills when it sees it. Checkboxes and consents are ticked on camera.
+12. **Verify with frames**, not logs: frame 0 (poster), settled intro, the hand-over to the
+    recording, a callout, a zoom, the recap, the last frame of a real render.
+13. **Zooms ride along with the cursor and finish before the click**: zoom in while the cursor
+    glides to the first click it frames (starting ≤ 0.35 s before the glide), fully in 0.1 s
+    before that click; zoom out while it glides to the next target, done before that click.
+    A zoom holds its own clicks (plus a click in view right after them, < 1 s), not everything
+    still on screen; when the next glide is > 3 s away it lingers 1.2 s and leaves. No easing during a click. No extra pauses in the scenario to make room
+    for zooms — shorten the ease (≥ 0.4 s) instead. A zoom anchored with `clicks` in video.json
+    is timed this way automatically; `reelson check` enforces it for every zoom.
+
+## What makes a video good
+
+**Plan the steps before the pixels.** One feature, 3–6 visible state changes, each a sentence a
+reader could follow without the video. If you can't write the callouts, the video isn't ready.
+
+**Recording**
+
+- `demo.marker()` right after the UI reaches the state, not before the click. The marker ends
+  its step: the callout starts as the step begins (the first glide or click after the previous
+  marker), stays through it and a moment on its result, so the viewer reads "Type the name"
+  while the name is typed.
+- Pause 1–1.5 s after anything the viewer must read (a modal, a notification, results). The
+  default settle after a click (0.7 s) is enough for menus only.
+- `demo.click` / `demo.type` / `demo.moveTo`, never raw `page.click` / `fill()`.
+- Small `demo.scroll()` steps over big jumps; or navigate straight to the section.
+- Read values from the page instead of hard-coding seeded data.
+- Wrap slow waits in `demo.cut()`; a short glimpse is kept so the cut doesn't feel like a glitch.
+- Trim the login off (video.json `"trim": { "start": "auto" }`, the default) unless the video
+  is about logging in. Tie trims to markers or clicks, never to plain seconds: a re-record
+  moves the footage.
+- Keep the 1440x900 viewport; wider makes text tiny inside the 1920x1080 frame.
+
+**Composition**
+
+- Callouts: imperative, in the UI's language, ≤ 6 words ("Click Save", not "Now the user
+  clicks the save button"). One on screen at a time, ≥ 2 s each.
+- Zoom only where the UI is small (a field, a toggle, a badge), scale 1.5–2.0, timed by the
+  cursor (rule 13).
+- Title = the task ("Find a customer"), subtitle = the benefit or context. Keep the intro at
+  its section's default (3 s for `poster`); longer intros get skipped.
+- Recap rows must read as steps on their own ("Choose Card"), not commentary ("Here is the form").
+- Length: 15–30 s is the sweet spot. Over 45 s, split into two videos.
+
+**Verify the artifact, not the log**
+
+1. `reelson check <slug>` says "ready to render" (schemas, zoom timing, `hyperframes check`).
+2. Extract and look at frames: t=0, settled intro, each callout, the zoom, the recap, the end.
+3. `ffprobe` duration matches the timeline the build printed.
+4. Watch it once at 1x. If a step is unreadable, pause longer in the scenario, not in the
+   composition.
+
+## Iterating
+
+| Want to change            | Do                                                                          |
+|---------------------------|-----------------------------------------------------------------------------|
+| Callout text, zoom, trims | Edit `video.json`, `reelson render <slug>` (it rebuilds).                   |
+| Pacing, missing step      | Edit `scenario.ts`, `reelson record`, add the new marker to video.json, render. |
+| UI changed                | `reelson record` then `reelson render`: callouts follow their markers, zooms their click numbers (re-check if the clicks changed). |
+| Look of intro/recap/outro | Pick another section (`reelson templates`), or make one (`templates/README.md`) — never per-video edits. |
+
+## Troubleshooting
+
+- **Scenario timed out on a locator**: open `recording.failed.mp4`, re-run with `--headed`.
+- **`video_nested_in_timed_element` lint error**: a timed `<video>` inside a timed wrapper.
+- **A callout flashes at t=0 or a zoom starts zoomed in**: an "out" tween without
+  `immediateRender: false`.
+- **Blurry UI text (worst in zooms)**: capture must be 2x (`ffprobe recording.mp4` →
+  2880x1800), `hyperframes.json` `autoProxy: false`, no `will-change` on `#frame`.
+- **Callout clipped during a zoom**: it ended up inside `#frame`; callouts live in `#callouts`.
+- **`Cannot find module '@playwright/test'`** or **`reelson: command not found`**: run
+  `npm install -g reelson && reelson install` (or the kit checkout's `install.sh`).
+- **`… is invalid: … unknown key — did you mean …`**: a typo in demo.config.json or video.json;
+  the message names the path. Editors autocomplete both through their `$schema`.

package/examples/demo.config.json

@@ -0,0 +1,18 @@
+{
+    "$schema": "../skills/reelson-record/schemas/demo.config.schema.json",
+    "$comment": "Config for the bundled examples. A real project keeps its own demo.config.json at its root (copy demo.config.example.json).",
+    "videosDir": ".",
+    "language": "en",
+    "locale": "en-US",
+    "brand": {
+        "name": "REELSON",
+        "tagline": "EXAMPLE",
+        "eyebrow": "Reelson",
+        "color": "#6366f1",
+        "colorSoft": "#a5b4fc"
+    },
+    "template": "classic",
+    "music": {
+        "file": null
+    }
+}

package/examples/todo-add-item/scenario.ts

@@ -0,0 +1,45 @@
+/**
+ * Example demo: adding and completing items in the public TodoMVC app.
+ * Runs anywhere with internet access, so it doubles as the kit's smoke test.
+ *
+ *   node skills/reelson-record/scripts/record.ts examples/todo-add-item/scenario.ts
+ *   node skills/reelson-compose/scripts/scaffold.ts examples/todo-add-item \
+ *       --title "Plan your day" --subtitle "Add tasks and tick them off"
+ *
+ * Every `demo.marker()` becomes a timed callout placeholder in the composition.
+ */
+import type { Scenario } from '../../skills/reelson-record/scripts/scenario.ts'
+
+export default {
+    name: 'todo-add-item',
+    baseURL: 'https://demo.playwright.dev',
+    async run(demo) {
+        await demo.goto('/todomvc/#/')
+        const input = demo.page.getByPlaceholder('What needs to be done?')
+
+        await demo.type(input, 'Book the team offsite')
+        await demo.page.keyboard.press('Enter')
+        await demo.pause(600)
+        demo.marker('Type a task and press Enter')
+
+        await demo.type(input, 'Send the weekly report')
+        await demo.page.keyboard.press('Enter')
+        await demo.pause(900)
+        demo.marker('Add as many as you need')
+
+        await demo.click(
+            demo.page
+                .getByTestId('todo-item')
+                .filter({ hasText: 'Send the weekly report' })
+                .getByRole('checkbox'),
+        )
+        await demo.pause(900)
+        demo.marker('Tick a task when it is done')
+
+        await demo.click(demo.page.getByRole('link', { name: 'Active' }))
+        await demo.pause(1200)
+        demo.marker('Filter what is left')
+        // Leave the last callout time to be read before the recording ends.
+        await demo.pause(2000)
+    },
+} satisfies Scenario

package/examples/todo-add-item/video.json

@@ -0,0 +1,35 @@
+{
+    "$schema": "../../skills/reelson-compose/schemas/video.schema.json",
+    "title": "Plan your day",
+    "subtitle": "Add tasks and tick them off",
+    "trim": {
+        "start": "auto"
+    },
+    "callouts": [
+        {
+            "marker": "Type a task and press Enter",
+            "text": "Type a task and press Enter"
+        },
+        {
+            "marker": "Add as many as you need",
+            "text": "Add as many as you need"
+        },
+        {
+            "marker": "Tick a task when it is done",
+            "text": "Tick a task when it is done"
+        },
+        {
+            "marker": "Filter what is left",
+            "text": "Filter what is left"
+        }
+    ],
+    "zooms": [
+        {
+            "clicks": [
+                3,
+                4
+            ],
+            "scale": 1.7
+        }
+    ]
+}

package/music/README.md

@@ -0,0 +1,7 @@
+# Music
+
+Licensed tracks are not committed (stock-music licences are usually registered per project).
+Keep each project's bed inside that project (e.g. `docs/videos/_music/<track>.mp3`, with its
+licence certificate) and point `music.file` in its `demo.config.json` at it.
+
+Files you drop here for local experiments are git-ignored.

package/package.json

@@ -0,0 +1,68 @@
+{
+    "name": "reelson",
+    "version": "0.7.0",
+    "type": "module",
+    "description": "Claude Code skills + CLI that turn a scripted Playwright walkthrough into a branded HyperFrames demo video.",
+    "keywords": [
+        "demo-video",
+        "screencast",
+        "playwright",
+        "hyperframes",
+        "claude-code",
+        "skills",
+        "product-demo",
+        "video"
+    ],
+    "license": "MIT",
+    "author": "Ion Caliman <icaliman92@gmail.com>",
+    "homepage": "https://github.com/reelson/reelson#readme",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/reelson/reelson.git"
+    },
+    "bugs": {
+        "url": "https://github.com/reelson/reelson/issues"
+    },
+    "bin": {
+        "reelson": "bin/run.js"
+    },
+    "files": [
+        "bin/",
+        "skills/",
+        "docs/",
+        "examples/demo.config.json",
+        "examples/todo-add-item/scenario.ts",
+        "examples/todo-add-item/video.json",
+        "demo.config.example.json",
+        "CHANGELOG.md",
+        "NOTICE.md",
+        "music/README.md"
+    ],
+    "engines": {
+        "node": ">=22.18"
+    },
+    "scripts": {
+        "setup": "npm install && npx playwright install chromium",
+        "test": "node --test --test-reporter=spec \"test/**/*.test.ts\"",
+        "test:update-golden": "UPDATE_GOLDEN=1 node --test \"test/**/*.test.ts\"",
+        "typecheck": "tsc --noEmit",
+        "build": "tsc -p tsconfig.build.json",
+        "clean": "find bin skills -name '*.js' -path '*/scripts/*' -delete; rm -f bin/reelson.js",
+        "prepack": "npm run clean && npm run build",
+        "postpack": "npm run clean",
+        "prepublishOnly": "npm run ci",
+        "ci": "npm run typecheck && npm test",
+        "example:verify": "cd examples && node ../bin/reelson.ts verify todo-add-item",
+        "example:record": "cd examples && node ../bin/reelson.ts record todo-add-item --all-takes",
+        "example:build": "cd examples && node ../bin/reelson.ts build todo-add-item",
+        "example:check": "cd examples && node ../bin/reelson.ts check todo-add-item",
+        "example:render": "cd examples && node ../bin/reelson.ts render todo-add-item --all-formats"
+    },
+    "dependencies": {
+        "@playwright/test": "^1.55.0"
+    },
+    "devDependencies": {
+        "@types/node": "^22.18.0",
+        "typescript": "^5.9.0"
+    }
+}

package/skills/reelson-compose/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: reelson-compose
+description: Use when the user wants the finished demo video — intro/outro title cards, numbered callouts, zoom-ins, branded framing — rendered to MP4/GIF from a screen recording, or mentions HyperFrames or reelson. Takes <videosDir>/<slug>/recording.mp4 (+ markers.json) from the reelson-record skill; video.json is the per-video source of truth, and `reelson build` turns it into a HyperFrames composition from a template plus mix-and-match intro/recap/outro sections (brand, logo, language and music from demo.config.json); `reelson render` produces video/renders/<slug>.mp4.
+---
+
+# reelson-compose
+
+Turns raw footage from `reelson-record` into a finished video with
+[HyperFrames](https://hyperframes.heygen.com) (HTML + GSAP → deterministic MP4, rendered
+frame-by-frame in headless Chrome), driven by the `reelson` CLI. Needs Node 22.18+ and `ffmpeg`;
+HyperFrames is fetched by `npx` (pinned version).
+
+**Read the kit's `docs/style-guide.md` first** (`realpath` this skill to find the kit). The
+templates and sections implement it; design changes belong in a template or a section
+(`templates/README.md`), never in a video's generated files.
+
+```
+<videosDir>/<slug>/
+├── scenario.ts        ← reelson-record (committed)
+├── markers.json       ← reelson-record (committed)
+├── recording.mp4      ← reelson-record (ignored)
+├── video.json         ← THE source of truth for this video (committed) — edit this
+└── video/             ← generated by `reelson build` (ignored; delete any time)
+    ├── index.html, hyperframes.json, package.json
+    ├── assets/        recording, vendored GSAP + fonts, music.m4a, narration.m4a
+    └── renders/<slug>.mp4
+```
+
+## video.json
+
+Every time in it is a **recording time** (seconds in recording.mp4, as in markers.json), so
+changing the trim or the template never re-times anything. Validated against
+`schemas/video.schema.json` (editors autocomplete it through `$schema`); a typo is an error.
+
+```jsonc
+{
+    "title": "Find a customer",                 // cover title = the task
+    "subtitle": "Search any customer from the list",
+    "trim": { "start": "auto" },                // skip the login; optional "end"
+    "callouts": [                               // numbered steps; also the recap
+        { "marker": "customers-list", "text": "Open Customers" },
+        { "marker": "search-results", "text": "Type the name in Search" }
+    ],
+    "zooms": [
+        { "clicks": [2, 3], "scale": 1.8 }      // frame clicks #2–#3 of markers.json
+    ]
+    // optional: "template", "sections": { intro, recap, outro }, "recapTitle",
+    //           "brand": { name, tagline, eyebrow, logo }, "music": file | false
+}
+```
+
+- **Trim**: `start` is `"auto"` (just before the first logged glide or marker, i.e. after the
+  login — what a new video.json gets), or tied to the footage: `{ "marker": "customers-list",
+  "offset": -0.8 }`, `{ "click": 3, "offset": -0.5 }` (from the glide towards click 3). `end`
+  takes the same anchors; leave it out to keep the recording to its end. Plain seconds work too
+  but go stale when the demo is re-recorded (`reelson check` warns).
+- **Callouts** point at a `marker` label (or give an `at` for manual recordings). Word them as
+  imperative steps in the UI's language, ≤ 6 words. A marker callout starts **with its step** —
+  the first glide or click after the previous marker (the marker comes after the action) — and
+  `duration` is automatic (through the step and 1.2 s past its marker, at least 3 s, ending
+  before the next callout) unless given. `"anchor": "marker"` starts it on the marker instead
+  (for a callout about the result). `offset` (seconds, may be negative) nudges it from there and
+  keeps it tied to the marker, so it still follows a re-recording.
+- **Voice-over**: `"voice": true` speaks each callout as it appears, with demo.config.json
+  `voice.provider`:
+  - `openai` (default): `gpt-4o-mini-tts`, voice `alloy`, pace and tone from `instructions`;
+    needs `OPENAI_API_KEY`. With `baseURL` it talks to a local OpenAI-compatible server instead
+    (Kokoro-FastAPI `http://localhost:8880/v1`, Speaches, LocalAI) — no key needed.
+  - `elevenlabs`: `eleven_multilingual_v2` (or `eleven_flash_v2_5`, faster; `eleven_v3`, most
+    expressive), voice George by default — `voice` takes a voice id, or a name when the key may
+    read voices; needs `ELEVENLABS_API_KEY`.
+  - `piper`: a local neural voice (`pipx install piper-tts`), one per language by default
+    (`ro_RO-mihai-medium`, `en_US-lessac-medium`, …), downloaded once into ~/.cache/reelson/piper.
+  - `command`: any local program — `"command": ["my-tts", "--out", "{out}", "{text}"]`
+    ({voice} {model} {speed} {language} too; the text also comes on stdin).
+
+  `speed` uses the provider's own rate (ElevenLabs 0.7–1.2, Piper, OpenAI tts-1; for
+  gpt-4o-mini-tts ask for the pace in `instructions`); `options` passes extra request fields
+  (e.g. ElevenLabs `{"voice_settings": {"stability": 0.4}}`) or Piper flags. Keys come from the
+  environment or a `.env` next to demo.config.json or in the reelson install (a checkout or the npm package). A callout's `say`
+  replaces what is spoken (a full sentence for a terse pill — "→" reads as a pause; `false`:
+  silent); `"voice": { "intro": "…" }` adds a line over the intro, and `provider` / `model` /
+  `voice` / `instructions` / `speed` there override the project for one video. `reelson voice
+  <slug>` makes the missing lines (render and build do it for you), trimmed of the silence around
+  them, into `<demo>/voice/<hash>.mp3` — cached by words + every sound setting, so each line is
+  made once; commit the folder to render without a key. `reelson doctor` says whether the
+  provider can speak here. A spoken callout stays up until its line is said, and the next step's
+  callout waits for it; when the line cannot fit (the video ends, or an `at` callout comes
+  first), the build and check warn — shorten its `say` or pause longer in the scenario. The
+  music ducks under it.
+- **Zooms**: use `clicks: [first, last]` (1-based positions in markers.json `clicks`, which
+  `demo.click`/`demo.type` log). reelson computes the focus point and the timing from the
+  cursor — in with the glide to the first click, out with the glide to the next target,
+  never easing during a click or typing (style guide #13). `scale` 1.5–2.0; `x`/`y` (0..1)
+  override the focus; `in`/`out` override the eases. A manual zoom (`at`, `duration`, `x`, `y`)
+  is possible but rarely needed. Never add pauses to the scenario for a zoom. Two zooms must
+  not be on screen at once (`reelson check` flags it). A zoom holds its own clicks and ends at
+  the next pause (a click still in view < 1 s later joins it; > 3 s of nothing, it lingers and
+  leaves): to hold longer, widen `clicks`; for two overlapping zooms, use one over both ranges.
+  `"follow": true` pans with the cursor while zoomed (smoothed, aimed slightly ahead), so the
+  clicks need not fit in one view — good for a form filled top to bottom at a high `scale`.
+- To find click numbers, read `clicks` in markers.json (each has `at`, `x`, `y`, `kind`).
+- **Cursor**: recordings made with `record.cursor: "layer"` (the default) have their cursor
+  drawn by the video. `"cursor": { "size": 56, "ripple": false }` restyles it, `"idle": 3` fades
+  it out after 3 s without moving or clicking (back in as it moves), `"cursor": false` hides it. For a recording with the cursor filmed in, the build warns that `cursor` has no
+  effect.
+
+## Templates and sections
+
+A video = a **template** (the stage: background, framed recording, callouts, hand-off cards)
++ one **section** per slot: `intro`, `recap`, `outro`. Pick sections in demo.config.json
+(project default) or video.json (this video), or with `reelson build --intro/--recap/--outro`
+(written into video.json). `reelson templates` lists them all. Shipped with `classic`:
+
+```
+INTRO (0 → exit)                     RECORDING               RECAP                        OUTRO
+poster   wordmark over title, chip   framed clip, callouts,  steps    title left, one     wordmark  big, ends at 15%
+         centred, belt hand-over     zooms, hand-off cards            column of steps     compact   wordmark | title, short
+minimal  small brand row, big title,                         compact  centred chips,      endcard   brand + title + chip,
+         left-aligned, fades                                          shorter                       ends fully readable
+split    brand panel left, title                             none     (no recap)
+         right, doors open
+```
+
+Defaults are `poster` / `steps` / `wordmark`. Rules of thumb: `minimal` + `compact` + `compact`
+for short clips (< 15 s); `recap: none` when there are ≤ 2 steps; `endcard` when the video is
+embedded where it pauses on the last frame (docs pages, GitHub). Every intro keeps frame 0 as
+the poster (thumbnail in chat apps, GitHub, Finder); every outro ends on the brand.
+
+**Logo**: `brand.logo` (demo.config.json, or per video in video.json `brand`) — an .svg (best),
+.png (≥ 340 px tall) or .webp relative to the project root — replaces the text wordmark in
+every intro and outro.
+
+**Hand-offs**: when markers.json has `transitions` (from `demo.transition()`), the footage is
+split into one clip per actor with a hand-off card between them; callouts after it shift
+automatically and get the role as `group`, so the recap splits per role.
+
+## Workflow
+
+```bash
+reelson build <slug> --title "Find a customer" --subtitle "..."   # first run creates video.json
+#   edit video.json: word the callouts, add zooms (by click number), adjust trim
+reelson build <slug>                  # regenerate video/ from video.json
+reelson check <slug>                  # schemas, zoom timing, `hyperframes check`
+reelson studio <slug>                 # for the user: preview + edit on a layer timeline
+reelson snapshot <slug> --at 1.2,3.5,6,10 [--portrait | --square]   # PNGs in video/snapshots/ — read them
+reelson render <slug> [--gif] [--draft] [--portrait] [--square] [--all-formats]   # build + render video/renders/<slug>.mp4
+```
+
+1. **First build.** It creates video.json with one callout per marker (the label as text), a
+   `"trim": { "start": "auto" }` (just before the first logged glide, i.e. after the login) and no
+   zooms, then prints the timeline. `--title/--subtitle/--trim-start (s or auto)/--trim-end/--template/
+   --intro/--recap/--outro/--music/--no-music` edit video.json in place on any build.
+2. **Edit video.json**, rebuild. Nothing in `video/` is edited by hand; it is overwritten.
+3. **Check and look.** `reelson check` must report "ready to render" (0 problems). Layout
+   `info` items about the recap/brand cross-fade overlap and off-canvas glows are expected.
+   Then snapshot the poster (t=0), the intro's hand-over, a callout, a zoom and the recap, and
+   look at them. When the user wants to review or adjust it themselves, run `reelson studio <slug>
+   --no-open` in the background and give them the URL: it follows your video.json edits live,
+   and the user's edits there (drag callouts, trim, zooms, sections, titles) are saved to
+   video.json — so re-read video.json before each of your own edits while it runs.
+4. **Render.** `reelson render` rebuilds first. ~30–60 s per 12 s of video. `--all` renders
+   every demo in the project, skipping the ones unchanged since their last render (`--force`
+   renders anyway); `--gif` adds a 720 px, 12 fps GIF for READMEs (cut from the MP4 with ffmpeg), `--portrait` adds a phone-first
+   1080x1920 version (its own composition, video/portrait.html). Its source is video.json
+   `"portrait"`: `"mobile"` — the phone take (`reelson record <slug> --mobile`) whole in a phone
+   frame, taps as ripples; best for any responsive app; `"desktop"` — a camera over the desktop
+   recording that frames each element the demo works on (with its label/row) as close as it
+   fits, never cutting it — readable for compact UIs, small for wide admin screens; `"auto"`
+   (default) — the phone take when there is one. The intro, recap, outro and hand-off cards use
+   their portrait layouts: stacked, with bigger type. `--square` adds a 1080x1080 version (its own
+   composition, video/square.html) from the square take (`reelson record <slug> --square`: the app
+   in a square browser, `record.square.viewport`, default 1080x1080), filling the whole frame —
+   no bands; zooms carry over while the take has the same clicks as the desktop one; the cards
+   use their square layouts. Without a square take `--square` fails and says to record one.
+   `--all-formats` adds both (a missing square take is skipped with a note), and video.json
+   `"formats": ["portrait", "square"]` makes every plain `reelson render` add them. In landscape
+   and square the callouts sit over the bottom of the footage; one that would cover what the
+   cursor works on there moves to the top by itself. Every render also writes
+   `renders/<slug>.srt` and `.vtt` (and `<slug>.portrait.*` / `<slug>.square.*` for those
+   versions, timed to their takes): the title and the callouts as captions, timed to the video. For a quick look, `--draft` renders
+   15 fps at draft quality (about 2x faster) to `renders/<slug>.draft.mp4` — or skip rendering
+   altogether and scrub in `reelson studio`.
+5. **Verify the artifact**, not the log: `ffprobe` duration ≈ the printed total; extract frames
+   (`ffmpeg -ss <t> -i video/renders/<slug>.mp4 -frames:v 1 f.png`) at t=0, ~2 s, a callout, a
+   zoom, the recap, the end. Look at them. Then report the file path.
+
+After the app changes (a release, a redesign), run `reelson verify --all`: it re-records every
+demo — each of its takes: desktop, and the phone and square ones when it has them — into a scratch folder and reports scenarios that no longer run, callouts/trims whose
+marker is gone, and zoom/trim click numbers that now point at a different click. Fix those in
+scenario.ts / video.json, then `reelson verify <slug> --update` keeps the new take.
+
+Sharp UI text comes from the 2x capture; the build keeps it (`media.autoProxy: false`, no
+`will-change` on `#frame`, jpg frames — png at 2x can stall the renderer).
+
+## Audio
+
+The build handles audio; never add `<audio>` by hand.
+
+- **Music bed** from demo.config.json `music.file` (or video.json `music`: a file for this video,
+  or `false`): trimmed to the length, normalised to `music.lufs` (−28 LUFS), faded in 0.8 s /
+  out 3 s → `assets/music.m4a`. Cached; re-rendered when the source, length or loudness changes.
+  One track per project is part of the brand.
+- **Narration** when the recording has an audio track (OpenScreen): extracted and played in
+  sync; the bed drops to `music.lufsUnderNarration`. (It is not split at hand-off cards.)
+
+## HyperFrames rules that bite (when editing a template or section)
+
+- A timed `<video>` may not sit inside a timed element (`#screen` is untimed on purpose).
+- `fromTo()` renders its from-state at construction (`immediateRender`). Every "out" tween needs
+  `immediateRender: false` (`...later`); anything whose entry uses `...later` needs an explicit
+  hidden state in the section's closing `gsap.set`. Intro tweens that start at t=0 must NOT use
+  `later` (frame 0 is the poster).
+- Animate transforms/opacity only (`x`, `y`, `scale`, `scaleX`, `opacity`, `filter`).
+- One `gsap.timeline({ paused: true })`, registered as `window.__timelines[<composition id>]`;
+  explicit positions; no `.play()`, `Math.random()`, `Date.now()`, rAF, async.
+- `<video>` must be `muted`. No CSS `transform` on anything GSAP moves. Root `data-duration`
+  defines the output length.
+- Text from video.json goes in with `textContent`, never `innerHTML`.
+
+## Going beyond the template
+
+Narration (`npx hyperframes tts`), captions, shader transitions, device mockups: install the
+official skills (`npx skills add heygen-com/hyperframes`) or read
+https://hyperframes.heygen.com/llms.txt. A new opening or ending that should be reusable → a new
+section (`<videosDir>/_sections/<slot>/<name>/`); a new background or frame → a new template.