npm - reelson - Versions diffs - 0.7.0 - Mend

reelson 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (105) hide show

package/CHANGELOG.md +99 -0
package/LICENSE +21 -0
package/NOTICE.md +15 -0
package/README.md +180 -0
package/bin/reelson.js +649 -0
package/bin/reelson.ts +676 -0
package/bin/run.js +5 -0
package/demo.config.example.json +51 -0
package/docs/demo.webp +0 -0
package/docs/prompting.md +72 -0
package/docs/style-guide.md +117 -0
package/examples/demo.config.json +18 -0
package/examples/todo-add-item/scenario.ts +45 -0
package/examples/todo-add-item/video.json +35 -0
package/music/README.md +7 -0
package/package.json +68 -0
package/skills/reelson-compose/SKILL.md +226 -0
package/skills/reelson-compose/schemas/video.schema.json +172 -0
package/skills/reelson-compose/scripts/build.js +424 -0
package/skills/reelson-compose/scripts/build.ts +532 -0
package/skills/reelson-compose/scripts/captions.js +24 -0
package/skills/reelson-compose/scripts/captions.ts +40 -0
package/skills/reelson-compose/scripts/check.js +80 -0
package/skills/reelson-compose/scripts/check.ts +93 -0
package/skills/reelson-compose/scripts/composition.js +163 -0
package/skills/reelson-compose/scripts/composition.ts +241 -0
package/skills/reelson-compose/scripts/hyperframes.js +138 -0
package/skills/reelson-compose/scripts/hyperframes.ts +157 -0
package/skills/reelson-compose/scripts/portrait.js +150 -0
package/skills/reelson-compose/scripts/portrait.ts +218 -0
package/skills/reelson-compose/scripts/project.js +238 -0
package/skills/reelson-compose/scripts/project.ts +324 -0
package/skills/reelson-compose/scripts/studio.js +330 -0
package/skills/reelson-compose/scripts/studio.ts +394 -0
package/skills/reelson-compose/scripts/timeline.js +271 -0
package/skills/reelson-compose/scripts/timeline.ts +514 -0
package/skills/reelson-compose/scripts/tts.js +303 -0
package/skills/reelson-compose/scripts/tts.ts +371 -0
package/skills/reelson-compose/scripts/verify.js +190 -0
package/skills/reelson-compose/scripts/verify.ts +209 -0
package/skills/reelson-compose/scripts/voice.js +178 -0
package/skills/reelson-compose/scripts/voice.ts +224 -0
package/skills/reelson-compose/scripts/zooms.js +259 -0
package/skills/reelson-compose/scripts/zooms.ts +333 -0
package/skills/reelson-compose/sections/README.md +5 -0
package/skills/reelson-compose/sections/intro/minimal/section.css +27 -0
package/skills/reelson-compose/sections/intro/minimal/section.html +12 -0
package/skills/reelson-compose/sections/intro/minimal/section.js +16 -0
package/skills/reelson-compose/sections/intro/minimal/section.json +9 -0
package/skills/reelson-compose/sections/intro/poster/section.css +27 -0
package/skills/reelson-compose/sections/intro/poster/section.html +14 -0
package/skills/reelson-compose/sections/intro/poster/section.js +28 -0
package/skills/reelson-compose/sections/intro/poster/section.json +9 -0
package/skills/reelson-compose/sections/intro/split/section.css +30 -0
package/skills/reelson-compose/sections/intro/split/section.html +12 -0
package/skills/reelson-compose/sections/intro/split/section.js +19 -0
package/skills/reelson-compose/sections/intro/split/section.json +9 -0
package/skills/reelson-compose/sections/outro/compact/section.css +23 -0
package/skills/reelson-compose/sections/outro/compact/section.html +10 -0
package/skills/reelson-compose/sections/outro/compact/section.js +11 -0
package/skills/reelson-compose/sections/outro/compact/section.json +8 -0
package/skills/reelson-compose/sections/outro/endcard/section.css +25 -0
package/skills/reelson-compose/sections/outro/endcard/section.html +13 -0
package/skills/reelson-compose/sections/outro/endcard/section.js +13 -0
package/skills/reelson-compose/sections/outro/endcard/section.json +8 -0
package/skills/reelson-compose/sections/outro/wordmark/section.css +11 -0
package/skills/reelson-compose/sections/outro/wordmark/section.html +5 -0
package/skills/reelson-compose/sections/outro/wordmark/section.js +12 -0
package/skills/reelson-compose/sections/outro/wordmark/section.json +8 -0
package/skills/reelson-compose/sections/recap/compact/section.css +26 -0
package/skills/reelson-compose/sections/recap/compact/section.html +8 -0
package/skills/reelson-compose/sections/recap/compact/section.js +23 -0
package/skills/reelson-compose/sections/recap/compact/section.json +11 -0
package/skills/reelson-compose/sections/recap/steps/section.css +36 -0
package/skills/reelson-compose/sections/recap/steps/section.html +8 -0
package/skills/reelson-compose/sections/recap/steps/section.js +27 -0
package/skills/reelson-compose/sections/recap/steps/section.json +11 -0
package/skills/reelson-compose/studio/index.html +81 -0
package/skills/reelson-compose/studio/studio.css +142 -0
package/skills/reelson-compose/studio/studio.js +1031 -0
package/skills/reelson-compose/templates/README.md +193 -0
package/skills/reelson-compose/templates/classic/assets/vendor/Inter-OFL.txt +93 -0
package/skills/reelson-compose/templates/classic/assets/vendor/gsap.min.js +11 -0
package/skills/reelson-compose/templates/classic/assets/vendor/inter-latin-ext-wght-normal.woff2 +0 -0
package/skills/reelson-compose/templates/classic/assets/vendor/inter-latin-wght-normal.woff2 +0 -0
package/skills/reelson-compose/templates/classic/stage.html +447 -0
package/skills/reelson-compose/templates/classic/template.json +5 -0
package/skills/reelson-record/SKILL.md +220 -0
package/skills/reelson-record/schemas/demo.config.schema.json +269 -0
package/skills/reelson-record/scripts/capture.js +142 -0
package/skills/reelson-record/scripts/capture.ts +190 -0
package/skills/reelson-record/scripts/config.js +148 -0
package/skills/reelson-record/scripts/config.ts +264 -0
package/skills/reelson-record/scripts/cursor-overlay.js +111 -0
package/skills/reelson-record/scripts/cursor-overlay.ts +122 -0
package/skills/reelson-record/scripts/doctor.js +128 -0
package/skills/reelson-record/scripts/doctor.ts +147 -0
package/skills/reelson-record/scripts/languages.js +29 -0
package/skills/reelson-record/scripts/languages.ts +41 -0
package/skills/reelson-record/scripts/record.js +365 -0
package/skills/reelson-record/scripts/record.ts +451 -0
package/skills/reelson-record/scripts/scenario.js +356 -0
package/skills/reelson-record/scripts/scenario.ts +570 -0
package/skills/reelson-record/scripts/validate.js +143 -0
package/skills/reelson-record/scripts/validate.ts +179 -0

package/skills/reelson-record/SKILL.md ADDED Viewed

@@ -0,0 +1,220 @@
+---
+name: reelson-record
+description: Use when the user wants a screen recording / walkthrough video of a feature of their web app — "record a demo of X", "make a video showing how to Y", "screen capture the Z flow", "docs video". Drives the app with Playwright via `reelson record`, draws a visible human-paced cursor, hides dev chrome, and writes recording.mp4 + markers.json into <videosDir>/<slug>/. Pair with the reelson-compose skill (HyperFrames) for the intro/outro/callouts and the final MP4. Also covers the manual OpenScreen path.
+---
+# reelson-record
+Produces the raw footage for a demo video: a scripted, repeatable browser walkthrough of
+the app, captured as video, with timestamps for every step you want to call out later.
+**Read `docs/style-guide.md` in the kit first** (next to this skill's real path: `../../docs/`
+— resolve the symlink with `realpath` if the skill is linked into a project). Its rules are
+the house style every video follows; the scripts implement them, so don't work around them
+with raw Playwright calls.
+```
+<videosDir>/<slug>/
+├── scenario.ts      ← you write this (committed)
+├── recording.mp4    ← generated: H.264, 30 fps, 2x viewport, no audio (git-ignored)
+└── markers.json     ← generated: duration, viewport, markers, clicks, cuts (committed)
+```
+`recording.mp4` + `markers.json` are the input contract of the `reelson-compose` skill. Everything
+runs through the `reelson` CLI (`reelson help`); if it is missing, install it: `npm install -g reelson && reelson install` (or the kit checkout's `install.sh`).
+## Project config
+Everything project-specific lives in `demo.config.json` at the project root (found by
+walking up from the scenario). Read it before writing a scenario — it tells you the videos
+directory, the UI language (callouts and personas follow it), the brand, and what to hide.
+If it is missing, run `reelson init` and ask the user for the brand name/colour and UI
+language. It is validated against `schemas/demo.config.schema.json` — a mistyped key is an
+error with a "did you mean" hint. Fields (all optional, see `scripts/config.ts`):
+| Field                          | Used for                                                          |
+|--------------------------------|-------------------------------------------------------------------|
+| `videosDir`                    | where `<slug>/` folders live (default `docs/videos`)              |
+| `language`, `locale`           | persona names, browser locale, `<html lang>`, and the built-in recap title + chip plurals (en, ro, de, fr, es, it, pt, nl, pl, ru, uk, cs, sv, da, nb, fi, hu, tr; `strings` overrides) |
+| `brand.color`                  | click-ring colour (and the cards in reelson-compose)                   |
+| `record.viewport`              | default 1440x900; keep 16:10 or 16:9                              |
+| `record.hideSelectors`         | extra local-only UI to hide (e.g. an app's env badge); Laravel Debugbar, Filament developer logins, Symfony/Django toolbars, rack-mini-profiler, Vite/Next/Nuxt/Astro dev UI are always hidden |
+| `record.extraHTTPHeaders`      | default `X-Demo-Recording: 1`, so the app can skip dev prefills   |
+| `record.personaDomain`         | email domain for `demo.persona()` (must resolve if a gateway checks) |
+Common dev overlays (Laravel Debugbar, Vite/Next.js/webpack error overlays) are always hidden.
+## What the recorder adds on top of plain Playwright video
+- **Smooth footage**: the page is filmed with Chrome's screencast — every frame it paints
+  (up to 60 fps, full 2x pixels, stamped on the same clock as the markers and the cursor) —
+  and assembled into a constant 30 fps recording.mp4, so scrolls, hovers and transitions don't
+  stutter. `record.capture: "playwright"` falls back to Playwright's 25 fps video.
+- **Visible cursor**: a large black macOS-style arrow with a press squash and a brand-coloured
+  double ring on click (Playwright's synthetic mouse is otherwise invisible). By default
+  (`record.cursor: "layer"`) the page only *logs* it: every move and press goes into
+  markers.json `cursor` (video seconds, ~40 ms capture latency already added), and the video
+  draws it — smooth, the same size under zooms, and restyled (size, ripple, brand colour)
+  without re-recording. `"recorded"` films it into recording.mp4 instead (the pre-0.4 way).
+  Clicks land where the glide ended (no snap to the element's centre).
+- **Human pacing**: curved, eased glides with a faint tremor, landing slightly off-centre;
+  typing with uneven delays and beats after spaces/punctuation. Seeded per scenario, so
+  re-records are identical. Never slow.
+- **Cursor starts mid-screen**: parked at a random point in the middle third before the first
+  action and before every `demo.goto()`, so the video never opens with a jump from a corner.
+  Raw `page.click()`/`fill()` (e.g. a login helper) move the mouse without telling `demo`; the
+  next `demo.goto()` re-syncs, so keep such raw steps before a goto.
+- **Markers**: `demo.marker('label')` stamps the video time; `reelson-compose` turns each into a
+  pre-timed callout and a row in the recap.
+- **Cuts**: `demo.cut(fn)` removes slow waits (3-D Secure, spinners, queued jobs) from the
+  video and shifts the markers.
+- **Personas**: `demo.persona()` gives a believable customer in the UI's language (name,
+  unique email, phone, company) — never `test@` or `e2e-123` strings on camera.
+- **2x capture + MP4 transcode** (ffmpeg, CRF 15, yuv420p, 30 fps, keyframe every second).
+## Prerequisites
+- The app running and reachable at the scenario's `baseURL`.
+- reelson installed once per machine (`npm install -g reelson`, then `reelson install` in the
+  project: Playwright's Chromium and the skill links; a kit checkout's `install.sh` does both).
+- `ffmpeg` on PATH (`brew install ffmpeg`). Node 22.18+ (TypeScript runs directly).
+- `reelson doctor` checks the tools and films a local test page to confirm the cursor layer
+  lines up with the footage on this machine (offset and px error; run it on a new machine).
+## Workflow
+1. **Pick the origin, panel and account.** Look for existing e2e helpers in the project
+   (login, table/modal locators) and reuse them from the scenario — a scenario is mostly an
+   e2e test with a cursor. Check the project's CLAUDE.md / e2e docs for seeded accounts.
+2. **Write `<videosDir>/<slug>/scenario.ts`.** `reelson new <slug> --url <origin>` creates a
+   stub with the right type import; the kit's `examples/todo-add-item/scenario.ts` is a full
+   example. Rules:
+   - `demo.marker('...')` right **after** the UI reaches each state worth a callout: it ends
+     that step, and its callout is shown from the step's first glide/click (after the previous
+     marker) until just past the marker — so it names what the viewer is watching. Labels
+     become the callouts in video.json (and its `marker` keys) — write them in the UI language
+     as imperative steps, and keep them stable: video.json refers to them by label.
+     **At most 10 markers** (the recap holds ten); fold small steps together.
+   - **Don't pause for zooms.** Zooms ride along with the cursor's glide; `demo.click` /
+     `demo.type` log every glide and click into `markers.json` (`clicks`), and a zoom in
+     video.json is anchored to click numbers and timed from them.
+   - Hold ~2–3 s after the last marker so its callout can be read.
+   - Nothing pre-filled on camera: if the app pre-fills forms or ticks consents locally,
+     gate that on the `X-Demo-Recording` header in the app rather than working around it.
+     Tick checkboxes with `demo.click` on camera.
+   - Keep it 10–40 s of footage, one feature per video. Login is recorded and trimmed away
+     later (video.json `trim.start`, suggested automatically).
+   - Use `demo.click` / `demo.type` / `demo.moveTo` / `demo.scroll`, not raw `page.click` or
+     `fill()` (those teleport the cursor and paste text). Raw `demo.page` is for waits, reads
+     and `selectOption` (glide there with `demo.moveTo` first).
+   - Data hygiene: read real values from the page instead of hard-coding seeded names; type
+     `demo.persona()` data into forms.
+   - Cookie banners mount after load: `waitFor({ timeout: 3000 })` then `demo.click` it.
+   - Wrap slow waits in `demo.cut(() => page.waitForURL(...), { keepMs: 900 })`.
+   - External pages (payment gateways, OAuth) are fair game; use their test modes and cut
+     the waits.
+3. **Record.**
+   ```bash
+   reelson record <slug>
+   reelson record <slug> --headed     # watch it
+   ```
+   Prints the duration and marker count. On a scenario error the partial capture is kept as
+   `recording.failed.mp4`. Flows that create records do so for real — point scenarios at a
+   local environment, never staging/prod.
+4. **Verify before handing off.** Pull frames at the marker times and look at them:
+   ```bash
+   ffmpeg -y -loglevel error -ss <marker at> -i <videosDir>/<slug>/recording.mp4 -frames:v 1 /tmp/m1.png
+   ```
+   Check: the intended state is on screen, no dev toolbars/env badges/dev-login buttons,
+   nothing personal (real emails, tokens), cursor where the callout will point. New dev UI
+   on screen → add its selector to `record.hideSelectors`.
+5. **Compose** with the `reelson-compose` skill (`reelson build <slug> --title "..."`).
+## Scenario API (`scripts/scenario.ts`)
+```ts
+export default {
+    name: 'slug',
+    baseURL: 'https://app.test',
+    viewport: { width: 1440, height: 900 },   // default from config; keep 16:10 or 16:9
+    leadInMs: 800, leadOutMs: 1200,           // silence at both ends
+    async run(demo) {
+        demo.page          // Playwright Page for anything else
+        demo.marker(label) // stamp current video time
+        demo.persona()     // { firstName, lastName, fullName, email, phone, company }
+        demo.cut(fn, { keepMs })   // run fn; drop that stretch from the video
+        demo.transition(fn, { title, subtitle, from, to })  // actor hand-off, see below
+        demo.pause(ms)
+        demo.goto(path)    // waits for networkidle + settle
+        demo.moveTo(loc)   // glide cursor to the element (scrolls into view)
+        demo.click(loc, { settleMs })
+        demo.type(loc, text)
+        demo.scroll(deltaY, { stepPx })
+        demo.popup(() => demo.click(link))   // continue in the tab/pop-up it opens (returned)
+        demo.switchTo(page)                  // continue on another page of the context
+    },
+} satisfies Scenario
+```
+**Two actors (e.g. manager → employee)**: wrap the account switch in `demo.transition()`.
+Everything inside `fn` (clear cookies, log in as the other account, `demo.goto` their first
+page) is cut, and `markers.json` gets a `transitions` entry; reelson-compose splits the footage
+there and shows a hand-off card (`from` → `to`, title, subtitle). Leave ~3 s after the last
+marker before it.
+**Phone take (for the portrait video)**: `reelson record <slug> --mobile` runs the same
+scenario on a phone — the Playwright device `record.mobile.device` (default "Pixel 7": its
+viewport, touch, mobile user agent) — into `recording.mobile.mp4` + `markers.mobile.json`
+(commit the markers like the desktop ones). `render --portrait` then shows it whole in a phone
+frame, with the taps as ripples: real mobile layout, nothing cropped. Use the same marker labels
+so video.json's callouts fit both takes; branch on `demo.mobile` where the mobile UI differs
+(`if (demo.mobile) await demo.click(page.getByRole('button', { name: 'Menu' }))`). The page
+needs `<meta name="viewport" content="width=device-width">` — without it a phone lays it out
+at desktop width, tiny.
+**Square take (for the square video)**: `reelson record <slug> --square` runs the same scenario
+in a square browser (`record.square.viewport`, default 1080x1080 — shown 1:1 on the square
+stage) into `recording.square.mp4` + `markers.square.json` (commit the markers). `render --square`
+fills the whole 1080x1080 frame with it. Branch on `demo.square` where the narrower window
+changes the UI; keep the same clicks where you can, so video.json's zooms (anchored by click
+number) carry over. Go below 1080 (for bigger text) only if the app keeps its desktop layout at
+that width — many collapse their sidebar under ~1024 px, which loses the menu steps.
+`reelson record <slug> --all-takes` records the desktop, phone and square takes one after the
+other; `reelson verify` re-records and checks every take a demo has.
+**Pop-ups and new tabs** (target="_blank", OAuth, a PDF preview): `const tab = await
+demo.popup(() => demo.click(link))`. From then on `demo.page` and every demo action use the new
+page, and the video cuts to it; when it closes (`window.close()`, `tab.close()`) the demo and
+the video return to the page that opened it. A page opened any other way is filmed but never
+shown — the recorder warns about it. (`record.capture: "playwright"` films the first page
+only.)
+Uploading a file on camera: generate it (e.g. a PDF via
+`browser.newPage().pdf()`) and answer the `filechooser` event.
+## Alternative: OpenScreen (manual recordings)
+[OpenScreen](https://github.com/getopenscreen/openscreen) is a free desktop recorder with
+auto-zoom, cursor smoothing and on-device captions. Use it when a human narrates, or the flow
+can't be scripted (native dialogs, hardware keys).
+```bash
+OS=/Applications/Openscreen.app/Contents/MacOS/Openscreen
+$OS sources --json
+$OS record --window "Chrome" --duration 30 --project <videosDir>/<slug>/demo.openscreen --json
+$OS export <videosDir>/<slug>/demo.openscreen -o <videosDir>/<slug>/recording.mp4 --auto-zoom --json
+```
+Then `reelson build <slug>` as usual — without `markers.json` it probes the file; give the
+callouts an `at` (recording seconds) in video.json. Zooms need manual `at`/`x`/`y` (no clicks
+are logged). **Don't combine OpenScreen with the Playwright recorder**: its
+effects follow the OS cursor, which Playwright never moves.

package/skills/reelson-record/schemas/demo.config.schema.json ADDED Viewed

@@ -0,0 +1,269 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "reelson project config (demo.config.json)",
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+        "videosDir": {
+            "type": "string",
+            "description": "Where <slug>/ folders live, relative to the project root. Default docs/videos."
+        },
+        "language": {
+            "type": "string",
+            "description": "BCP 47 language of the product UI (en, ro, de-DE…). Drives <html lang>, plural rules and persona names."
+        },
+        "locale": {
+            "type": "string",
+            "description": "Browser locale while recording (Accept-Language, Intl formatting). Default en-US."
+        },
+        "brand": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "Wordmark on the cover and the closing card."
+                },
+                "tagline": {
+                    "type": "string",
+                    "description": "Small spaced line under the wordmark. Empty hides it."
+                },
+                "eyebrow": {
+                    "type": "string",
+                    "description": "Label above the recap title."
+                },
+                "color": {
+                    "type": "string",
+                    "description": "Primary accent: numbers, lines, click ring. Any CSS colour."
+                },
+                "colorSoft": {
+                    "type": "string",
+                    "description": "Lighter accent for gradients."
+                },
+                "logo": {
+                    "type": [
+                        "string",
+                        "null"
+                    ],
+                    "description": "Logo image (.svg, .png or .webp; relative to the project root) drawn instead of the text wordmark. SVG stays sharpest; a PNG should be ≥ 340 px tall. null = text wordmark."
+                }
+            }
+        },
+        "template": {
+            "type": "string",
+            "description": "Template (the stage: background, frame, callouts) folder name: skills/reelson-compose/templates/<name> or <videosDir>/_templates/<name>. Default classic."
+        },
+        "sections": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "Section per slot, over the template's defaults (classic: poster / steps / wordmark). Run `reelson templates` for the list.",
+            "properties": {
+                "intro": {
+                    "type": "string",
+                    "description": "Opening section; frame 0 is the poster. Kit: poster, minimal, split."
+                },
+                "recap": {
+                    "type": "string",
+                    "description": "Steps card after the recording, or \"none\". Kit: steps, compact, none."
+                },
+                "outro": {
+                    "type": "string",
+                    "description": "Closing brand card. Kit: wordmark, compact, endcard."
+                }
+            }
+        },
+        "strings": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "recapTitle": {
+                    "type": "string",
+                    "description": "Title of the recap card."
+                },
+                "stepsLabel": {
+                    "$ref": "#/definitions/label",
+                    "description": "Cover chip noun after the step count: a string, or plural forms (see definitions.plural)."
+                },
+                "secondsLabel": {
+                    "$ref": "#/definitions/label",
+                    "description": "Cover chip noun after the length in seconds; same forms as stepsLabel."
+                }
+            }
+        },
+        "voice": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "Voice-over, for videos with \"voice\": true in video.json: each callout (its `say`, else its text) spoken by a text-to-speech provider. Lines are trimmed and cached in <demo>/voice/, so each is made once.",
+            "properties": {
+                "provider": { "enum": ["openai", "elevenlabs", "piper", "command"], "description": "openai (default; OPENAI_API_KEY — or a local OpenAI-compatible server via baseURL), elevenlabs (ELEVENLABS_API_KEY), piper (a local neural voice: pipx install piper-tts; the voice downloads on first use), command (any local program). Keys can live in a .env next to demo.config.json." },
+                "model": { "type": "string", "description": "The provider's model. Defaults: openai gpt-4o-mini-tts, elevenlabs eleven_multilingual_v2 (eleven_flash_v2_5 is faster and cheaper, eleven_v3 the most expressive)." },
+                "voice": { "type": "string", "description": "The provider's voice. openai: alloy (default), ash, ballad, cedar, coral, echo, fable, marin, nova, onyx, sage, shimmer, verse. elevenlabs: a voice id or the name of a voice in your account (default George). piper: a voice name like ro_RO-mihai-medium (default: one for `language`)." },
+                "instructions": { "type": "string", "description": "How to speak: tone, pace, accent (gpt-4o-mini-tts; other providers ignore it)." },
+                "speed": { "type": "number", "minimum": 0.5, "maximum": 2, "description": "Speaking rate, 1 = normal. openai: tts-1 / tts-1-hd (for gpt-4o-mini-tts describe the pace in instructions); elevenlabs: 0.7–1.2; piper; command: {speed}." },
+                "baseURL": { "type": "string", "description": "openai: the API root of a local OpenAI-compatible server, e.g. http://localhost:8880/v1 (Kokoro-FastAPI). No key needed unless the server wants one." },
+                "command": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "command: the program and its arguments; {text} {out} {voice} {model} {speed} {language} are filled in and the text also comes on stdin. It must write the line to {out} (any audio ffmpeg reads)." },
+                "options": { "type": "object", "description": "Passed through: extra request fields (openai; elevenlabs, e.g. {\"voice_settings\": {\"stability\": 0.4}}) or --flags (piper, e.g. {\"sentence-silence\": 0.1})." },
+                "lufs": { "type": "number", "maximum": 0, "description": "Loudness of the voice track. Default -16." }
+            }
+        },
+        "music": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "file": {
+                    "type": [
+                        "string",
+                        "null"
+                    ],
+                    "description": "Music bed under every video, relative to the project root. null = no music."
+                },
+                "lufs": {
+                    "type": "number",
+                    "maximum": 0,
+                    "description": "Bed loudness under silent footage. Default -28."
+                },
+                "lufsUnderNarration": {
+                    "type": "number",
+                    "maximum": 0,
+                    "description": "Bed loudness under narration. Default -34."
+                }
+            }
+        },
+        "record": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "viewport": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                        "width",
+                        "height"
+                    ],
+                    "properties": {
+                        "width": {
+                            "type": "integer",
+                            "minimum": 320
+                        },
+                        "height": {
+                            "type": "integer",
+                            "minimum": 240
+                        }
+                    }
+                },
+                "deviceScaleFactor": {
+                    "type": "number",
+                    "minimum": 1,
+                    "maximum": 4
+                },
+                "extraHTTPHeaders": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    },
+                    "description": "Sent with every request while recording. Default { \"X-Demo-Recording\": \"1\" }."
+                },
+                "cursor": {
+                    "enum": [
+                        "layer",
+                        "recorded"
+                    ],
+                    "description": "layer (default): the cursor is logged, not filmed, and the video draws it — same size under zooms, restyled without re-recording. recorded: drawn into the page and filmed (the pre-0.4 behaviour)."
+                },
+                "mobile": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "device": {
+                            "type": "string",
+                            "description": "Playwright device for `reelson record --mobile` (the phone take behind the portrait video), e.g. \"Pixel 7\" (default), \"iPhone 14\", \"Galaxy S9+\"."
+                        }
+                    }
+                },
+                "square": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "viewport": {
+                            "type": "object",
+                            "additionalProperties": false,
+                            "required": [
+                                "width",
+                                "height"
+                            ],
+                            "properties": {
+                                "width": {
+                                    "type": "integer",
+                                    "minimum": 320
+                                },
+                                "height": {
+                                    "type": "integer",
+                                    "minimum": 320
+                                }
+                            },
+                            "description": "Browser size (CSS px) for `reelson record --square` (the take behind the square video). Default 1080x1080: shown at 1:1 on the 1080x1080 stage. Keep it square; go smaller (e.g. 900x900) for bigger text if the app still shows its desktop layout at that width."
+                        }
+                    }
+                },
+                "capture": {
+                    "enum": [
+                        "screencast",
+                        "playwright"
+                    ],
+                    "description": "screencast (default): every frame Chrome paints, up to 60 fps, assembled into a smooth 30 fps recording. playwright: Playwright's own 25 fps video (stutters one frame in six at 30 fps)."
+                },
+                "hideSelectors": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "CSS selectors hidden on every recorded page (dev toolbars, env badges)."
+                },
+                "personaDomain": {
+                    "type": "string",
+                    "description": "Email domain for demo.persona()."
+                }
+            }
+        }
+    },
+    "definitions": {
+        "label": {
+            "anyOf": [
+                {
+                    "type": "string"
+                },
+                {
+                    "$ref": "#/definitions/plural"
+                }
+            ]
+        },
+        "plural": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "other"
+            ],
+            "properties": {
+                "zero": {
+                    "type": "string"
+                },
+                "one": {
+                    "type": "string"
+                },
+                "two": {
+                    "type": "string"
+                },
+                "few": {
+                    "type": "string"
+                },
+                "many": {
+                    "type": "string"
+                },
+                "other": {
+                    "type": "string"
+                }
+            },
+            "description": "Plural forms keyed by Intl.PluralRules category, e.g. { \"one\": \"step\", \"other\": \"steps\" }."
+        }
+    }
+}

package/skills/reelson-record/scripts/capture.js ADDED Viewed

@@ -0,0 +1,142 @@
+import { spawn } from 'node:child_process';
+import { mkdirSync, readFileSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+/** Starts filming `page`; frames are written into `dir` as they arrive, tagged `pageId`. */
+export async function startScreencast(context, page, dir, pageId = 0, quality = 92) {
+    mkdirSync(dir, { recursive: true });
+    const cdp = await context.newCDPSession(page);
+    const frames = [];
+    const writes = [];
+    cdp.on('Page.screencastFrame', (event) => {
+        // Ack first: Chrome sends the next frame only after the previous one is acknowledged.
+        cdp.send('Page.screencastFrameAck', { sessionId: event.sessionId }).catch(() => { });
+        const file = resolve(dir, `${pageId ? `p${pageId}-` : ''}f${String(frames.length).padStart(6, '0')}.jpg`);
+        frames.push({ file, t: (event.metadata.timestamp ?? Date.now() / 1000) * 1000, page: pageId });
+        writes.push(writeFile(file, Buffer.from(event.data, 'base64')));
+    });
+    await cdp.send('Page.startScreencast', { format: 'jpeg', quality, everyNthFrame: 1 });
+    return {
+        stop: async () => {
+            await cdp.send('Page.stopScreencast').catch(() => { });
+            await Promise.all(writes);
+            await cdp.detach().catch(() => { });
+            return frames;
+        },
+    };
+}
+/**
+ * How long each frame stays on screen in the finished video (seconds), in order. Video
+ * time 0 is `startedAt` (the recording clock of createDemo); a frame shows from the moment
+ * it was painted until the next one; the first frame also covers anything before it.
+ * `cuts` are ranges of that clock (seconds) left out of the video. With `switches`, only
+ * the page the camera is on counts at each moment (a pop-up, then back to its opener, which
+ * shows its last frame from before); without, every frame counts.
+ */
+export function frameSchedule(frames, startedAt, endedAt, cuts, switches) {
+    const end = (endedAt - startedAt) / 1000;
+    const seconds = (t) => (t - startedAt) / 1000;
+    const camera = switches?.length
+        ? [...switches].sort((a, b) => a.t - b.t).map((s) => ({ at: Math.max(0, seconds(s.t)), page: s.page }))
+        : [{ at: 0, page: -1 }];
+    const pieces = camera.map((c, i) => ({ from: i === 0 ? 0 : c.at, to: i + 1 < camera.length ? camera[i + 1].at : end, page: c.page }));
+    const kept = keptRanges(cuts, end);
+    const out = [];
+    const add = (file, from, to) => {
+        for (const range of kept) {
+            const overlap = Math.min(to, range.to) - Math.max(from, range.from);
+            if (overlap <= 0) {
+                continue;
+            }
+            const last = out[out.length - 1];
+            if (last?.file === file) {
+                last.duration += overlap;
+            }
+            else {
+                out.push({ file, duration: overlap });
+            }
+        }
+    };
+    for (const piece of pieces.filter((p) => p.to > p.from)) {
+        const own = frames
+            .filter((f) => piece.page === -1 || (f.page ?? 0) === piece.page)
+            .sort((a, b) => a.t - b.t)
+            .map((f) => ({ file: f.file, t: seconds(f.t) }));
+        if (!own.length) {
+            continue;
+        }
+        // On screen at the start of the piece: the page's latest frame so far, else its first.
+        let i = Math.max(0, own.findLastIndex((f) => f.t <= piece.from));
+        for (; i < own.length && own[i].t < piece.to; i++) {
+            const from = Math.max(piece.from, own[i].t);
+            const to = Math.min(piece.to, i + 1 < own.length ? own[i + 1].t : piece.to);
+            if (to > from) {
+                add(own[i].file, i === 0 && own[i].t > piece.from ? piece.from : from, to);
+            }
+        }
+    }
+    return out;
+}
+/** [0, end] minus the cuts. */
+function keptRanges(cuts, end) {
+    const ranges = [];
+    let at = 0;
+    for (const c of [...cuts].sort((a, b) => a.from - b.from)) {
+        if (c.from > at) {
+            ranges.push({ from: at, to: Math.min(c.from, end) });
+        }
+        at = Math.max(at, c.to);
+    }
+    if (at < end) {
+        ranges.push({ from: at, to: end });
+    }
+    return ranges.filter((r) => r.to > r.from);
+}
+/** The finished recording's frame rate. */
+export const FPS = 30;
+/**
+ * Encodes the schedule as the H.264 recording.mp4 HyperFrames consumes: output frame k
+ * (at k / FPS s) is the latest frame painted by then, piped straight into ffmpeg at a
+ * constant rate. (ffmpeg's concat demuxer would snap image timestamps to 25 fps.)
+ */
+export async function encodeFrames(schedule, mp4) {
+    if (!schedule.length) {
+        return false;
+    }
+    const total = schedule.reduce((sum, e) => sum + e.duration, 0);
+    const count = Math.max(1, Math.round(total * FPS));
+    const ffmpeg = spawn('ffmpeg', [
+        '-y', '-loglevel', 'error',
+        '-f', 'image2pipe', '-framerate', String(FPS), '-c:v', 'mjpeg', '-i', '-',
+        '-vf', 'scale=trunc(iw/2)*2:trunc(ih/2)*2',
+        '-c:v', 'libx264', '-preset', 'slow', '-crf', '15', '-pix_fmt', 'yuv420p', '-r', String(FPS),
+        // A keyframe every second: HyperFrames seeks frame by frame.
+        '-g', String(FPS), '-keyint_min', String(FPS),
+        '-movflags', '+faststart', '-an', mp4,
+    ], { stdio: ['pipe', 'inherit', 'inherit'] });
+    const done = new Promise((resolveDone) => {
+        ffmpeg.on('error', () => resolveDone(false));
+        ffmpeg.on('close', (code) => resolveDone(code === 0));
+    });
+    ffmpeg.stdin.on('error', () => { }); // ffmpeg exiting early is reported by `done`
+    let index = 0;
+    let endOfCurrent = schedule[0].duration;
+    let loaded = -1;
+    let bytes = Buffer.alloc(0);
+    for (let k = 0; k < count; k++) {
+        const t = k / FPS;
+        while (index < schedule.length - 1 && t >= endOfCurrent - 1e-9) {
+            index++;
+            endOfCurrent += schedule[index].duration;
+        }
+        if (index !== loaded) {
+            bytes = readFileSync(schedule[index].file);
+            loaded = index;
+        }
+        if (!ffmpeg.stdin.write(bytes)) {
+            await new Promise((drained) => ffmpeg.stdin.once('drain', drained));
+        }
+    }
+    ffmpeg.stdin.end();
+    return done;
+}