reelson 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+All notable changes to reelson. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+versions follow [Semantic Versioning](https://semver.org/) (before 1.0, a minor version may change
+`video.json` or `demo.config.json`; the notes say how to update).
+
+## 0.7.0 — 2026-09-23
+
+The first release on npm.
+
+### Changed
+- **Renamed reelkit → reelson**: the `reelson` command, the `reelson-record` / `reelson-compose`
+  skills, the Piper cache in `~/.cache/reelson`. Re-run `reelson install` (or `install.sh`) for each
+  project: it drops the old `reelkit` command and `reelkit-*` skill links. Then point scenario
+  imports and `$schema` paths at `.claude/skills/reelson-*`.
+
+### Added
+- **npm package** (MIT): `npm install -g reelson`. It ships JavaScript compiled beside the
+  TypeScript sources; a checkout still runs the sources directly.
+- **`reelson install [<dir> | --global] [--no-browser]`**: links the skills into a project (or
+  `~/.claude/skills`), creates `demo.config.json` and downloads Playwright's Chromium.
+  `install.sh` now `npm link`s a checkout and calls it.
+- **Voice-over providers**: `voice.provider` picks `openai` (or an OpenAI-compatible server via
+  `baseURL`), `elevenlabs`, `piper` (a local neural voice, downloaded on first use) or `command` (any
+  local program); speed, options and per-video provider/model/voice overrides. Lines are trimmed of
+  the silence around them. `reelson voices` lists the voices (`--library`: the ElevenLabs Voice Library);
+  `reelson doctor` says whether the provider can speak here.
+- A spoken callout stays up until its line is said, and the next step waits for it (`build` and `check`
+  warn when a line cannot fit). API keys are read from a `.env` beside `demo.config.json` or in the
+  reelson install; the environment wins.
+
+### Fixed
+- `render --gif` works again: the GIF (720 px, 12 fps) is now cut from the rendered MP4 with ffmpeg
+  instead of HyperFrames' GIF encoder, which failed with ffmpeg 7.0 and rendered every frame a second
+  time. It is skipped while the MP4 is unchanged.
+- `moveTo` scrolls an out-of-sight target into view smoothly instead of jumping.
+- The voice track is resampled to 48 kHz and padded so it never falls short of its slot.
+
+## 0.6.0 — 2026-09-22
+
+### Added
+- **Portrait** (1080×1920): a phone take (`record --mobile`, a Playwright device) in a phone frame,
+  or a camera that frames each element of the desktop take; `video.json` `"portrait": auto|mobile|desktop`.
+  Every kit section has its own portrait layout.
+- **Square** (1080×1080): a square take (`record --square`) filling the frame, with square layouts for
+  every section.
+- `record --all-takes`, `verify` covers every take, `render --all-formats` and `--only <format>`.
+- **Voice-over**: `"voice": true` speaks each callout (its `say`, else its text) with OpenAI
+  text-to-speech, cached in `<demo>/voice/`; the build mixes the track and ducks the music.
+- Pop-ups and new tabs: `demo.popup()` / `switchTo()` move the demo and the camera there and back.
+
+### Changed
+- Callouts start with their step (not after its marker), get a minimum reading time, and move to the
+  top over action at the bottom of the screen.
+- `reelson check` lints each composition on its own.
+
+## 0.5.0 — 2026-09-22
+
+### Added
+- **Screencast capture**: Chrome's screencast films every painted frame on the cursor's clock →
+  a smooth 30 fps recording (`record.capture "playwright"` keeps the old 25 fps video).
+- Zooms can follow the cursor (`"follow"`); the cursor fades when idle (`"cursor": { "idle": s }`).
+- Trims follow the footage (`"auto"`, marker and click anchors); `check` warns about fixed times.
+- `render --draft` (15 fps, ~2× faster); renders are skipped when nothing changed (`--force`).
+- `.srt` / `.vtt` captions; `--square` / `--portrait` social versions.
+- `reelson doctor`: the tools, plus a measured cursor-to-footage sync on this machine.
+- `reelson verify`: re-records every demo into a scratch folder and checks `video.json` still fits.
+- Built-in recap strings and plural forms for 18 languages; more dev toolbars hidden by default.
+
+## 0.4.0 — 2026-09-22
+
+### Added
+- **Cursor as a layer**: logged by the page, drawn by the video, so it stays smooth and the same
+  size under zooms, and can be restyled without re-recording. Clicks land where the glide ends.
+- **Studio** (`reelson studio`): a preview with a layer timeline; edit callouts, trims, zooms, sections
+  and titles (saved to `video.json`, with undo).
+
+### Fixed
+- Dev-chrome hiding works again (the injected script had a syntax error since 0.2).
+- Scenarios use the project's Playwright, so they can import its helpers.
+
+## 0.3.0 — 2026-09-22
+
+### Added
+- Templates are a stage plus mix-and-match sections per slot: intro (`poster`, `minimal`, `split`),
+  recap (`steps`, `compact`, `none`), outro (`wordmark`, `compact`, `endcard`), chosen in
+  `demo.config.json`, `video.json` or with `--intro` / `--recap` / `--outro`.
+- `brand.logo` replaces the text wordmark; `reelson templates` lists what is available.
+
+## 0.2.0 — 2026-09-21
+
+### Added
+- `video.json` as the source of truth for a video (zooms anchored by click number, auto-timed).
+- The CLI: `init`, `new`, `record`, `build`, `check`, `snapshot`, `preview`, `render`.
+- Validation against JSON Schemas with "did you mean" hints, unit and golden tests, CI.
+
+## 0.1.0 — 2026-09-21
+
+- The first kit: a recording skill and a composing skill, the classic template, branding from config.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ion Caliman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,15 @@
+# Third-party notices
+
+reelson ships or downloads the following. Check each licence before using reelson output
+commercially or redistributing it.
+
+| Component | Where | Licence |
+|---|---|---|
+| **GSAP 3.14.2** (GreenSock) | vendored: `skills/reelson-compose/templates/classic/assets/vendor/gsap.min.js` | GreenSock Standard "No Charge" License — https://gsap.com/standard-license (not an OSI licence) |
+| **Inter** variable font 4.x (Rasmus Andersson), via `@fontsource-variable/inter` 5.3.0 | vendored: `…/classic/assets/vendor/inter-*.woff2` | SIL Open Font License 1.1 — `…/classic/assets/vendor/Inter-OFL.txt` |
+| **Playwright** (Microsoft) | npm dependency | Apache-2.0 |
+| **HyperFrames** (HeyGen) | fetched by `npx` at render/check time | see https://hyperframes.heygen.com |
+| **FFmpeg** | system dependency, not bundled | LGPL/GPL depending on the build |
+| **TypeScript**, **@types/node** | dev dependencies | Apache-2.0 / MIT |
+
+Music is not included: stock-music licences are registered per project (see `music/README.md`).

package/README.md

@@ -0,0 +1,180 @@
+# reelson
+
+Turn a prompt into a finished, branded demo video of a web app. Two
+[Claude Code](https://claude.com/claude-code) skills plus a `reelson` CLI:
+
+| Skill                                    | Does                                                                        | Output                                   |
+|------------------------------------------|-----------------------------------------------------------------------------|------------------------------------------|
+| [`reelson-record`](skills/reelson-record/)     | Playwright walkthrough with a visible human-paced cursor, dev chrome hidden, step markers and logged clicks | `<slug>/recording.mp4` + `markers.json` |
+| [`reelson-compose`](skills/reelson-compose/)       | [HyperFrames](https://hyperframes.heygen.com) composition from a template + mix-and-match intro/recap/outro sections: poster intro, framed recording, callouts, cursor-timed zooms, recap, brand outro, music | `<slug>/video/renders/<slug>.mp4` |
+
+The same prompt re-creates the video after a UI change: a scenario re-records in ~20 s,
+headless, with identical pacing, and callouts/zooms follow their markers and clicks.
+
+![The TodoMVC example: poster intro, the recorded walkthrough with callouts and zooms, recap and outro](https://cdn.jsdelivr.net/npm/reelson/docs/demo.webp)
+
+<sub>The [example](examples/todo-add-item/scenario.ts), rendered by CI on every push
+(`docs/demo.webp` is a 960 px cut of it).</sub>
+
+```
+scenario.ts ──reelson record──▶ recording.mp4 + markers.json
+                                          │
+video.json (title, trim, callouts, zooms) ┴──reelson build──▶ video/ ──reelson render──▶ .mp4 / .gif
+          demo.config.json (brand, logo, language, music) + template + sections ┘
+```
+
+## Requirements
+
+- Node 22.18+ and `ffmpeg` (`brew install ffmpeg`)
+- The app you record, running locally
+- HyperFrames is fetched by `npx` on first use (version pinned in
+  [hyperframes.ts](skills/reelson-compose/scripts/hyperframes.ts))
+
+## Install
+
+```bash
+npm install -g reelson
+reelson install ~/code/my-app     # or: reelson install --global  (~/.claude/skills, every project)
+```
+
+`reelson install` downloads Playwright's Chromium, links both skills into
+`my-app/.claude/skills/`, creates `my-app/demo.config.json` and prints the `.gitignore` lines.
+The links point at the installed package, so `npm update -g reelson` updates every project.
+
+To work on reelson itself, install from a checkout instead: the `reelson` command then runs the
+TypeScript sources directly and `git pull` updates every project.
+
+```bash
+git clone git@github.com:reelson/reelson.git ~/reelson
+~/reelson/install.sh ~/code/my-app     # npm link + reelson install
+```
+
+reelson was called reelkit before 0.7. Re-run `reelson install` (or `install.sh`) for each project: it drops the old
+`reelkit` command and `reelkit-*` skill links. Then point scenario imports and `$schema` paths
+at `.claude/skills/reelson-*`.
+
+## Configure per project — `demo.config.json`
+
+Everything project-specific lives in one file at the project root. It is validated against
+[a JSON Schema](skills/reelson-record/schemas/demo.config.schema.json) (editors autocomplete it; a
+typo is an error with a "did you mean" hint).
+
+```jsonc
+{
+    "videosDir": "docs/videos",          // where <slug>/ folders live
+    "language": "en", "locale": "en-US", // UI language: plurals, personas, <html lang>
+    "brand": { "name": "ACME", "tagline": "PLATFORM", "eyebrow": "Acme",
+               "color": "#dc2626", "colorSoft": "#f87171",
+               "logo": "docs/brand/logo.svg" },      // optional: replaces the text wordmark
+    "template": "classic",
+    "sections": { "intro": "poster", "recap": "steps", "outro": "wordmark" },  // the defaults
+    "strings": {                                       // optional: built in for en, ro, de, fr, es, it,
+        "recapTitle": "In short",                      // pt, nl, pl, ru, uk, cs, sv, da, nb, fi, hu, tr
+        "stepsLabel": { "one": "step", "other": "steps" },      // Intl.PluralRules categories
+        "secondsLabel": { "one": "second", "other": "seconds" } // e.g. ro: one/few/other
+    },
+    "music": { "file": "docs/videos/_music/track.mp3", "lufs": -28, "lufsUnderNarration": -34 },
+    "record": {
+        "viewport": { "width": 1440, "height": 900 },
+        "hideSelectors": [".environment-indicator"],   // local-only UI to hide on camera
+        "extraHTTPHeaders": { "X-Demo-Recording": "1" },
+        "personaDomain": "example.com",
+        "cursor": "layer",                             // or "recorded": film it into the footage
+        "capture": "screencast"                        // every painted frame → smooth 30 fps (or "playwright")
+    }
+}
+```
+
+## Use
+
+Ask Claude in the project, e.g.:
+
+> Make a demo video of searching a customer. Admin area on https://app.test as the admin.
+> Steps: open Customers, type a name in the table search, hover the match. Title "Find a
+> customer". Zoom on the search box while typing. Slug customers-search.
+
+More prompts in [docs/prompting.md](docs/prompting.md); the rules every video follows in
+[docs/style-guide.md](docs/style-guide.md). By hand:
+
+```bash
+reelson doctor                                          # tools + cursor/footage sync on this machine
+reelson new customers-search --url https://app.test    # scenario stub
+reelson record customers-search [--headed]            # --mobile / --square: the takes for --portrait / --square; --all-takes: all three
+reelson build customers-search --title "Find a customer"   # creates video.json on first run
+#   edit video.json: callout wording, { "clicks": [2, 3], "scale": 1.8 } zooms, trim ("auto" or a marker)
+reelson voice customers-search                          # "voice": true in video.json: speak the callouts (voice.provider: openai, elevenlabs, piper, command)
+reelson check customers-search                          # schemas, zoom timing, hyperframes lint
+reelson verify --all                                    # after an app change: every demo still records and fits
+reelson studio customers-search                         # preview + edit on a layer timeline (saves video.json)
+reelson templates                                       # templates and intro/recap/outro sections
+reelson render customers-search [--gif] [--square] [--portrait] [--all-formats] [--draft]   # + .srt/.vtt captions
+reelson render --all                                    # every demo; skips the unchanged ones
+```
+
+Per video, commit `scenario.ts`, `markers.json` and `video.json`; everything else is generated.
+
+## Templates and sections
+
+A video is a **template** (the stage: background, framed recording, callouts) plus one
+**section** per slot, chosen separately in demo.config.json or per video in video.json:
+
+| Slot    | Sections (first = default)                   |
+|---------|----------------------------------------------|
+| `intro` | `poster`, `minimal`, `split`                 |
+| `recap` | `steps`, `compact`, `none`                   |
+| `outro` | `wordmark`, `compact`, `endcard`             |
+
+```jsonc
+// video.json — this video only
+"sections": { "intro": "minimal", "recap": "none", "outro": "endcard" }
+```
+
+Every intro keeps frame 0 as the poster and every outro ends on the brand, so any mix keeps
+the house style. `brand.logo` (an SVG, or a PNG ≥ 340 px tall) replaces the text wordmark in all
+of them. `classic` is the only template today. The contract for new templates and sections is in
+[templates/README.md](skills/reelson-compose/templates/README.md); a project can keep its own under
+`<videosDir>/_templates/<name>/` and `<videosDir>/_sections/<slot>/<name>/`. Templates ship
+their scripts and fonts (no CDN).
+
+## Develop
+
+```bash
+npm run setup          # deps + Chromium
+npm run typecheck      # tsc --noEmit
+npm test               # unit + golden tests (node:test)
+npm run test:update-golden   # after an intended template/composition change — review the diff
+npm run example:record && npm run example:build && npm run example:check && npm run example:render
+```
+
+CI ([.github/workflows/ci.yml](.github/workflows/ci.yml)) runs the type check and tests, then
+records the TodoMVC example, builds, checks and renders it, and uploads the MP4 and frames.
+
+### Publish to npm
+
+Node will not run TypeScript from under `node_modules`, so the package ships `.js` compiled beside
+each `.ts` (`npm run build`; `npm pack` / `npm publish` build first and clean up after).
+`bin/run.js` picks the compiled CLI when installed from npm and the sources in a checkout.
+
+1. Bump `version` in package.json, commit, tag `vX.Y.Z` and push the tag.
+2. [.github/workflows/publish.yml](.github/workflows/publish.yml) runs the checks and publishes
+   with npm trusted publishing (OIDC, with provenance; no token). Set it up once on npmjs.com →
+   the package → Settings → Trusted publishing: GitHub Actions, `reelson/reelson`, `publish.yml`.
+
+The very first release has to be published by hand (trusted publishing needs the package to
+exist): `npm login && npm publish`. Check the contents first with `npm pack --dry-run`.
+
+## Layout
+
+```
+bin/reelson.ts  the CLI (run.js: the npm entry point)
+skills/
+  reelson-record/  SKILL.md, scripts/ (record, scenario, cursor-overlay, config, validate), schemas/
+  reelson-compose/   SKILL.md, scripts/ (build, check, timeline, zooms, composition, project, hyperframes),
+                schemas/, templates/<name>/ (stages), sections/<slot>/<name>/
+docs/           style-guide.md, prompting.md, demo.webp (the README clip)
+examples/       demo.config.json + todo-add-item/ (scenario, markers, video.json)
+test/           unit + golden tests, fixtures
+music/          local-only tracks (git-ignored; licences are per project)
+```
+
+MIT licence ([LICENSE](LICENSE)). Third-party code and fonts: [NOTICE.md](NOTICE.md).