motigenjs 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 crocone
+
+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/README.md

@@ -1,3 +1,192 @@
-# Temporary Holding Version
+# motigen
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Video as code, for developers and their coding agents.
+
+A web page is the film: it draws frame `t` on demand, in plain HTML, Canvas or anything else a browser runs.
+motigen opens it headless, renders every frame in order and pipes them into ffmpeg, so one project gives the same
+MP4 on every run. Real terminals and real browsers are recorded and replayed inside the same page; the narration,
+the sound effects and the music are mixed from the timeline the page exports; the subtitles come from the same
+cues. Everything is a file in git and every step is one command, which is exactly what a coding agent needs to
+make a product video on its own.
+
+```bash
+npm i -g motigenjs && npx playwright install chromium   # Node 22+, ffmpeg in PATH; the command is `motigen`
+motigen init guide my-guide && cd my-guide
+motigen record take.mjs      # a real browser and a real terminal, recorded into take/
+motigen vo                   # narration from audio/lines.txt (ElevenLabs), one file per line
+motigen build                # events → mix → render → subtitles: out/my-guide.mp4 + .srt
+motigen preview              # scrub it, play it with sound, render from a button
+```
+
+## What you get
+
+- **Three kinds of film, one contract.** A page registers `window.__film = { ready, dur, renderAt(t) }`. The
+  `dom` template is that contract in 80 lines; the `guide` template is a screencast player (browser window,
+  terminal window, chapters, key badges, cards) driven by one edit list; the `canvas` template is a hand-drawn
+  2D engine (paper, letterpress type, ink strokes, a thread, cards, a pencil) with its own offline mix.
+- **A recorder for the real thing.** `Term` records a shell through a pty with `script`-style timing, so the
+  player replays the actual bytes through xterm.js; `Browser` records a CDP screencast with the mouse path, the
+  clicks, the keys and the URLs, and can serve a local folder or a local instance of your site under its real
+  domain.
+- **Sound from the timeline.** `motigen events` asks the page where the voice lines, clicks and key presses fall;
+  `motigen vo` makes the narration (one ElevenLabs call with timestamps, split per line, or your own recordings);
+  `motigen mix` lays everything out, ducks the music under the voice and masters to −14 LUFS / −1 dBTP;
+  `motigen srt` writes the subtitles.
+- **Deterministic, parallel rendering.** Every frame depends on `t` alone, so `-j 4` renders four slices at once
+  and joins them losslessly, and the preview scrubs to any moment instantly.
+- **Made for agents.** `skill/SKILL.md` tells a coding agent how to take a script to a finished video with these
+  commands; the whole project is text it can read and change.
+
+## Install
+
+Node 22 or newer and ffmpeg in your PATH. Playwright downloads its Chromium once; `--channel chrome` uses an
+installed Chrome instead.
+
+```bash
+npm i -g motigenjs
+npx playwright install chromium
+```
+
+The npm package is `motigenjs`; the command it installs is `motigen`. As a project dependency, `npx motigen …`
+works the same way.
+
+The terminal recorder uses `node-pty` (an optional dependency with prebuilt binaries for Windows, macOS and
+Linux). Without it, record in a container: `backend: 'docker'`.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `motigen init <guide\|dom\|canvas> <dir>` | A new project from a template. |
+| `motigen preview [--port 4310] [--open]` | A player over the project: scrub, play with `audio/mix.wav`, switch formats, render and export events from buttons. |
+| `motigen frames -t 1,2.5,10` | Stills into `shots/` (`--png`, `--every 5`, `--element '#terminal'` with a transparent background, `--scale 2`). |
+| `motigen render` | The video to `out/<name>.mp4`: `-j N` pages in parallel (default: half the cores, at most 4), `--range 10-20`, `--audio file.wav` or the project's `audio/mix.wav`, `--crf`, `--preset`. |
+| `motigen stability -t 3,10` | Renders consecutive frames at those moments and reports what changed between them (`--every 2`, `--frames 3`, `--still` to fail on any change). |
+| `motigen events` | The page's `events()` into `audio/events.json`: voice cues, clicks, keys, Enter presses, effects. |
+| `motigen record [take.mjs]` | Runs a take script; it imports `{ Term, Browser, sleep }` from `motigenjs/record`. |
+| `motigen vo [lines.txt]` | Narration: one ElevenLabs call for the whole script, split per line into `audio/vo/` with `vo.json`. `vo split` uses a saved response, `vo import` your own recordings, `vo check` flags breathy or garbled lines. |
+| `motigen mix` | `audio/mix.wav` from `events.json`, `vo/`, `sfx/` and `bed.*`; or the canvas kit's own mix when `"mix": {"engine": "page"}`. |
+| `motigen srt` | Subtitles from the voice cues, with the written forms from `"spellings"`. |
+| `motigen build` | `events` → `mix` → `render` (every format) → `srt`. |
+| `motigen skill [dir]` | Installs `skill/SKILL.md` into `.claude/skills/motigen/`, so a coding agent in that folder knows the workflow. |
+
+Common options: `-C dir` (the project), `-p page`, `--fmt name`, `--size WxH`, `--query "fmt=v"`, `--channel chrome`,
+`--no-gpu`, `--ffmpeg path`, `--timeout s`. `motigen help` lists everything.
+
+## The contract
+
+```js
+window.__film = {
+  ready: true,         // fonts and assets are loaded
+  dur: 38,             // seconds
+  fps: 30,             // optional
+  renderAt(t) {},      // draw the frame at t seconds; sync or async; a pure function of t
+  events() {},         // optional: { dur, vo: [{id, t}], clicks: [t], keys: [t], enters: [t], sfx: [{id, t, db}] }
+  canvas,              // optional: an HTMLCanvasElement to read frames from, at its own size
+};
+```
+
+A frame must depend on `t` alone: no `Date.now()`, no CSS animations or transitions, no random numbers without a
+seed, nothing that keeps running between calls. Then any frame can be rendered at any time in any order, which is
+what parallel rendering and scrubbing rely on.
+
+## A project
+
+```
+my-guide/
+  motigen.json      page, fps, size, formats, audio folder, out, vo / mix / spellings settings
+  film.html         the page; the guide template adds edit.js, theme.css, brand.svg, take.mjs, site/
+  take/             recordings: take/<clip>/ (frames + clip.json), take/term.out + term.tm
+  audio/            lines.txt → vo/ (L01.wav… + vo.json); bed.wav; sfx/; events.json, mix.wav (generated)
+  out/              renders and subtitles
+```
+
+```json
+{ "page": "film.html", "fps": 30, "size": [1920, 1080], "out": "out/my-film.mp4",
+  "formats": { "h": { "query": "fmt=h" }, "v": { "size": [1080, 1920], "query": "fmt=v" } },
+  "vo": { "voice": "<elevenlabs voice id>", "model": "eleven_v4", "seed": 7042 },
+  "mix": { "voiceDb": -3, "duckDb": -9, "target": { "lufs": -14, "dbtp": -1 } },
+  "spellings": [["Acme Cloud dot com", "acmecloud.com"], ["Pie", "Pi"]] }
+```
+
+## The three templates
+
+**guide** — a screencast. `take.mjs` records the demo site in `site/` (served inside the recorder as
+`https://demo.local`) and a shell on your machine; `edit.js` cuts them:
+
+```js
+export default {
+  cols: 112, rows: 30, take: 'take', term: 'take/term',
+  shots: [
+    { card: intro, dur: 4, vo: [['L01', -1, 0.5]] },
+    { browser: 'site', segs: [[0, 9.5]], chapter: ['Step 1', 'Connect'], zoom: [[0, 1, 800, 450], [1.4, 1.35, 700, 420]] },
+    { term: true, segs: [[0, 'edit.js|+1.2'], [null, 'node --version|+1.6']], keys: [['node --version|-0.2', 1.4, 'Enter', 'run it']] },
+    { card: outro, dur: 4 },
+  ],
+};
+```
+
+Segments play source seconds back to back and can be stretched or squeezed; terminal bounds can be text anchors
+(`'Installed|+0.8'` = the moment that text appears, plus 0.8 s); the window zooms along keyframes; cards, chapters,
+key badges and notes are overlays. [docs/guide.md](docs/guide.md) has the whole format and the recorder API.
+
+**dom** — the contract and nothing else: a title, a bar and three typed lines in one HTML file. Start here for a
+film in plain HTML and CSS.
+
+**canvas** — a 12-second film on the hand-drawn engine from a real promo series: paper, a letterpress title, an
+ink thread with a needle, a rule card with a highlighter, tally marks, a pencil that underlines, a stamped name.
+Both formats come from one `LAYOUTS` table. [docs/canvas.md](docs/canvas.md) lists the kit.
+
+## Sound
+
+`audio/lines.txt` is the script, one line per cue. `motigen vo` sends it to ElevenLabs in one call with character
+timestamps (`ELEVENLABS_API_KEY`, the voice id in `motigen.json`) and cuts the take at the quietest point between
+lines, so pauses sound natural and every line is its own file. Recorded your own? `motigen vo import` writes
+`vo.json` for the files in `audio/vo/`. Then `motigen mix` places each line where the edit put its cue, adds the
+click / key / Enter sounds for what the recorder logged (synthesised when `audio/sfx/` is empty), loops the music
+bed with a crossfade, ducks it under the voice and masters with ffmpeg's two-pass loudnorm. The levels, the
+ducking and the target live under `"mix"` in `motigen.json`. [docs/audio.md](docs/audio.md).
+
+## Stillness
+
+A still shot has to repeat the same pixels frame after frame; the smallest shimmer on text reads as jitter once
+it is encoded. motigen is built so that it does not happen, and ships the check:
+
+- Every frame is a pure function of `t`: nothing on screen may depend on the clock, on CSS animations or on
+  unseeded randomness.
+- The guide player snaps its camera to whole pixels and a fixed scale grid, so a slow pan moves in clean steps
+  and a hold repeats one transform; the canvas kit keeps hand-drawn strokes on one seed (no "line boil"); the
+  templates settle every animated value to an exact number.
+- The encoder puts keyframes every 2 s and nowhere else (`--gop`), so fine texture does not pulse on holds.
+- `motigen stability -t 3,10,20` renders consecutive frames at those moments and reports the share of pixels
+  that changed, with a box around the change and a `-diff.png` that shows it brightened; `--still` fails when a
+  moment is not perfectly still. A cursor, a caret or a spinner show up as small boxes; jitter shows up as a
+  small change spread across text that should not move.
+
+## Why not …
+
+- **Remotion**: React, a bundler and a licence with limits for companies. motigen takes any page, needs no build
+  step, and is MIT.
+- **Motion Canvas**: its own editor and generator syntax. motigen is a CLI over an ordinary HTML page.
+- **VHS, asciinema**: the terminal only. motigen puts a real terminal next to a real browser, cuts them with one
+  edit list, and adds narration, sound and subtitles from the same timeline.
+- **Screen recorders**: a GUI and one take. A motigen project is text in git; change one line and render again.
+
+## Where it comes from
+
+The format and the tools were extracted from a pipeline that produced a real series of product guides and promo
+films. Every port was checked against that pipeline's own output: the guide player gives the same events and the
+same frames (SSIM 0.99 against the earlier render), the mix the same loudness and the same waveform within the
+random jitter of the key clicks, the subtitles the same file byte for byte, the canvas films the same frames.
+
+## Development
+
+```bash
+git clone https://github.com/crocone/motigen && cd motigen
+npm i && npx playwright install chromium
+npm test
+node bin/motigen.js build -C examples/hello-dom
+cd examples/hello-guide && node ../../bin/motigen.js record take.mjs && node ../../bin/motigen.js build
+```
+
+MIT.

package/bin/motigen.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+main(process.argv.slice(2)).catch(e => {
+  console.error(process.env.MOTIGEN_DEBUG ? e?.stack || e : `motigen: ${e?.message || e}`);
+  process.exit(1);
+});

package/docs/audio.md

@@ -0,0 +1,54 @@
+# Sound: narration, the mix, subtitles
+
+Everything sits in the project's audio folder (`"audio"` in motigen.json, default `audio/`):
+
+```
+audio/
+  lines.txt        the script, one line per cue (L01, L02, …); blank lines and # comments are skipped
+  vo/              L01.wav … + vo.json [{id, dur, text, speechStart, speechEnd}]; resp.json (the TTS response)
+  bed.wav|mp3|…    the music, optional
+  sfx/             click.wav, key.wav, enter.wav and any id used in events.sfx; sfx.json with each file's `hit`
+  events.json      from `motigen events`
+  mix.wav          from `motigen mix` (mix-raw.wav is the unmastered sum)
+```
+
+## Narration
+
+`motigen vo` reads `lines.txt`, sends the whole script to ElevenLabs in one `with-timestamps` call
+(`ELEVENLABS_API_KEY`; `"vo": { "voice", "model", "seed", "settings" }` in motigen.json or `--voice`, `--model`,
+`--seed`), saves the response as `audio/vo/resp.json` and splits it: each line is cut at the quietest point between
+it and the next (the alignment runs a little late), silence is trimmed, and `vo.json` records the duration, the
+text and the measured speech span of every line.
+
+- `motigen vo split resp.json lines.txt` splits a saved response (no API call).
+- `motigen vo import [dir] [lines.txt]` takes files you recorded or generated elsewhere (any format, sorted by
+  name), renames them to L01…, and writes `vo.json`.
+- `motigen vo check` prints the spectral flatness of every line and flags the breathy or garbled ones (`--limit`,
+  default 0.12); exit code 2 when any is flagged.
+
+Spelling for the voice is not spelling for the screen: write "Acme Cloud dot com" in `lines.txt` and put
+`["Acme Cloud dot com", "acmecloud.com"]` under `"spellings"` so the subtitles read right.
+
+## The mix
+
+`motigen mix` builds `audio/mix.wav` from `events.json`:
+
+1. Voice: every line peak-normalised to `voiceDb` (−3 dBFS) and placed at its cue.
+2. Effects: `click` at every logged click (`clickDb` −14), `key` at every key press (`keyDb` −27 with a seeded
+   ±2.5 dB jitter), `enter` at every Enter badge (`enterDb` −18), plus `events.sfx` entries by id. Files come from
+   `audio/sfx/<id>.wav` (or `sfx.json`'s `file`, placed so the transient at `hit` lands on the event); missing
+   click / key / enter are synthesised.
+3. Music: the bed, looped from `bedLoopFrom` (8 s) with a `bedCrossfade` (2 s) when the film is longer, faded out
+   over `bedFadeOut` (3 s), levelled to `bedRmsDb` (−36 dB RMS), then ducked under the voice by `duckDb` (−9) with
+   `duckAttack` 120 ms and `duckRelease` 450 ms.
+4. Master: `"master": "loudnorm"` (default) runs ffmpeg's EBU R128 normaliser in two passes to `target.lufs` −14 /
+   `target.dbtp` −1 / `target.lra` 11; `"master": "limiter"` applies a linear gain and a look-ahead limiter instead
+   (no ffmpeg, flatter dynamics).
+
+All of these are keys under `"mix"` in motigen.json. The canvas kit mixes inside the page with its own levels and
+the effects library; `"mix": { "engine": "page" }` makes `motigen mix` save that instead.
+
+## Subtitles
+
+`motigen srt` writes one cue per voice line, from its event time to that plus its duration, with the written forms
+from `"spellings"` put back. `motigen build` runs it after the render, next to the video.

package/docs/canvas.md

@@ -0,0 +1,54 @@
+# The canvas template: ink.js and kit.js
+
+`motigen init canvas <dir>` makes a film on a 2D canvas. `film.js` imports two modules served by motigen:
+
+```js
+import * as K from '/_motigen/canvas/ink.js';     // drawing primitives
+import * as kit from '/_motigen/canvas/kit.js';   // the stage, cards, the mix, the contract
+await kit.boot({ id, load, render, mix, logo, fonts, paper, maxDur });
+```
+
+`load()` returns `{ dur }` after loading what the film needs; `render(ctx, f)` draws frame `f` (30 fps, so
+`f = t · 30`) and must be a pure function of `f`; `mix()` returns the sound spec. `boot` loads the fonts (Geist from
+the package by default), the optional logo, the sound library (`audio/sfx/sfx.json`), registers `window.__film` and
+draws frame 0. Formats: `?fmt=h` is 1920×1080, `?fmt=v` is 1080×1920 (`kit.FMT`, `kit.W`, `kit.H`); keep one
+`LAYOUTS` table per format.
+
+## ink.js
+
+Everything is a pure function of its inputs; strokes wobble by a seed, so a frame is the same every time.
+
+- Math: `clamp`, `lerp`, `prog(t, a, b)`, `ease.{out, inOut, outBack, …}`, `keys(t, ks)`, `mulberry32(seed)`, `noise1`.
+- Paths: `linePts`, `bezierPts`, `splinePts(pts, perSeg, tension)`, `ellipsePts`, `resample`, `pointAt(pts, u)` → `{x, y, a}`, `pathLength`.
+- Strokes: `inkStroke(ctx, pts, {w, seed, boilT, taper, alpha, color, wobble})`, `inkLine`, `inkRect`, `inkEllipse`, `hatch`.
+- The thread: `thread(ctx, pts, {to, w, color})`, `needle(ctx, x, y, a)`.
+- Paper and marks: `paperTexture(w, h, base, seed)`, `card(ctx, x, y, w, h, {r, seed, boilT, lw, shadow})`, `underline`, `highlight(ctx, x, y, w, h, {p, color, seed})`, `checkBadge`, `tally(ctx, x, y, n)`.
+- Type: `text(ctx, str, x, y, {kind: 'heavy'|'sans'|'serif'|'mono'|'hand', size, weight, color, align, track, alpha, spread})`, `measure`, `typed(str, t, cps)`, `typedTimes`, `stampWords`.
+- Images and camera: `drawImage`, `camera(ctx, W, H, {cx, cy, z, rot})`.
+- Colours `C` (paper, ink, muted, orange, yellow, blue, card, …) and fonts `F`.
+
+## kit.js
+
+- Stage: `bg(ctx, color)`, `label(ctx, text, {x, y, fs})`, `superLines(ctx, lines, x, y, f, f0, f1, {size, maxW, lift})` (letterpress landing, optional lift-off), `stampLine`, `stampScale(age)`, `fitSize`, `emphasis(ctx, x, y, angle, age, size, seed)`, `deckle`.
+- Images: `loadImg`, `tryImg`, `loadSvg`, `tryJson`, `feather(img, px)` (no rectangle edge), `inkLayer` / `drawInk` (art as ink on the paper, whatever its background), `warpImage(ctx, img, w, h, quad)`.
+- Logo: `drawLogo(ctx, x, y, w)`, `stampLogo(ctx, x, y, w, age)`, `logoH(w)` — when `boot({ logo })` was given an image.
+- Geometry: `place(ctx, {cx, cy, s, rot})`, `mapPt`, `lerpT`, `toScreen`, `applyCam`, `camPt`, `keyPose(f, ks)`.
+- Props and cards: `drawPencil(ctx, x, y, angle, boilT)`, `successChip`, `ruleCard(ctx, rect, age, f, label, body, {hl, hlText})`, `wordGroups`.
+- Sound: `mix(spec)` (below), `keyClicks`, `enterClick`; `boot` exposes `__film.buildMix()`, `__film.wav()` (what `motigen mix` saves when `"mix": {"engine": "page"}`), `__film.exportMP4()` (in-browser, WebCodecs through mediabunny) and `__film.events()` (derived from the spec: voice cues and effects on the output clock).
+
+### The mix spec
+
+```js
+const mixSpec = () => ({
+  music: { file: 'audio/bed.wav', lufs: -18.5 },     // levelled before ducking; null for none
+  duck: t => (t < 14 ? -6 : -10),                     // duck depth under the voice at that time
+  vo: { json: VO, cues: { L01: 10, L02: { end: 261 }, L03: { f: 280, db: 4 } } },   // frames: first word on it, or last sound ends on it
+  sfx: [['FX4', 130, -8, { align: 'enter', rate: 1, maxDur: 1, fadeIn: 0, fadeOut: 0, at0: false }]],
+  extra: async ({ ac, sfxBus, voBus, decode, lib }) => {},   // film-specific sound
+  target: { lufs: -14, dbtp: -1 },
+});
+```
+
+`VO` is `audio/vo/vo.json` from `motigen vo` (or the older `{ voices: { name: { lines } } }` shape); `speechStart`
+and `speechEnd` in it put the first word on the frame. The effects library `audio/sfx/sfx.json` maps an id to
+`{ file, hit, dur, keys?, enter? }`, where `hit` is the transient's position inside the file so it lands on the cue.

package/docs/guide.md

@@ -0,0 +1,100 @@
+# The guide template: recording and the edit
+
+A guide is a screencast of the real thing: a browser window and a terminal window on a 1920×1080 stage, cut by one
+edit list, with chapters, key badges, notes and full-screen cards. `motigen init guide <dir>` sets one up.
+
+## Recording a take
+
+`take.mjs` is a Node script run by `motigen record take.mjs`. It imports the recorder:
+
+```js
+import { Term, Browser, sleep, freshContainer, waitFile } from 'motigenjs/record';
+```
+
+### Browser
+
+```js
+const b = await Browser.open('take', {
+  width: 1600, height: 900, scale: 1.5,     // the viewport the player assumes (zoom coordinates are in these CSS px)
+  theme: 'light', headless: true, channel: undefined,
+  map: { 'example.com': '127.0.0.1' },      // film a local instance under its real domain (local certificate accepted)
+  proxy: 'http://127.0.0.1:2081',           // everything but the mapped hosts goes through it
+  blockAnalytics: true,                     // the usual analytics hosts are aborted
+  cookies: [{ name: 'consent', value: 'none', domain: 'example.com', path: '/', secure: true }],
+  guard: async page => { /* throw if example.com is not the local stack */ },
+  permissions: ['clipboard-read', 'clipboard-write'], origin: 'https://example.com',
+});
+await b.serve('https://demo.local', 'site');   // a folder as a site, inside this browser only
+await b.goto('https://demo.local/');
+const clip = await b.clip('site');             // frames + clip.json → take/site/
+await b.moveTo('#start', { ms: 900 });         // eased mouse path with a slight arc, logged
+await b.click('#start');                       // moveTo + a logged click
+await b.typeInto('#name', 'maya');             // each key logged for the mix
+await b.scroll(500, 1400);  await b.scrollTo('#more', 120, 1000);
+await clip.stop();
+await b.close();
+```
+
+A clip is a folder of JPEG screencast frames and `clip.json`: `frames: [{t, file, scrollY}]`, `mouse: [{t, x, y}]`,
+`clicks`, `keys`, `urls: [{t, url}]`, `viewport`, `scale`, `dur`. Times are seconds from the clip's start.
+
+### Terminal
+
+```js
+const t = new Term('take', { cols: 112, rows: 30, cwd: '/path', ps1: '\\w $ ' });
+await t.start();              // bash through node-pty (or $SHELL; PowerShell on Windows without bash)
+await t.waitFor('$');         // until the text appears after the previous match
+t.mark('install');            // a named moment, saved to term.marks.json
+await t.type('ls', { cps: 13 });   // like a person, with jitter
+await t.enter();  await t.paste('curl -fsSL https://example.com/install.sh | sh');
+await t.waitIdle(3000);       // until the stream is quiet (a TUI keeps redrawing while it works)
+t.send('\x03');               // raw bytes
+await t.stop();
+```
+
+Output: `take/term.out` (the raw stream after one header line) and `take/term.tm` (`script -T` timing: seconds
+since the previous chunk and its byte count, one line per chunk). The player replays this through xterm.js, so the
+screen is the real one at every moment.
+
+For a clean machine, record in a container: `freshContainer({ share: 'take', image: 'debian:bookworm-slim',
+setup: 'laptop/setup.sh' })` starts one with `take/` mounted at `/share`, and `new Term('take', { backend: 'docker',
+container: 'motigen-take' })` records through `script -T` inside it. Build your own image with the tools the guide
+shows.
+
+## The edit
+
+`edit.js` exports one object. Top level: `cols`, `rows` (the recorded terminal's size), `fps` (30), `take`
+('take'), `term` ('take/term'), `brand` (image url for the top-right mark), `termTitle`, `host` (the address bar;
+default: the clip's own), `maskPath` (`[[pattern, replacement]]` for the shown path), `shots`.
+
+Shots, in order:
+
+| Shot | Fields |
+|---|---|
+| `{ card: '<html>', dur }` | a full-screen card (fades in and out) |
+| `{ browser: '<clip>', segs, zoom?, chapter?, keys?, note?, vo?, typed? }` | a browser clip |
+| `{ term: true, segs, zoom?, chapter?, keys?, note?, vo?, typing? }` | the terminal stream |
+
+- `segs: [[src0, src1, dur?], …]` — source seconds played back to back; `dur` stretches or squeezes that piece.
+  For terminal shots a bound may be a text anchor: `'Installed acme|-0.3'` is the moment that text appears
+  in the stream (searched forward from the previous anchor, so repeated words resolve in order) plus an offset;
+  `null` is where the previous piece ended.
+- `zoom: [[t, scale, cx, cy], …]` — in shot time; `cx`, `cy` is the point brought to the middle of the window, in
+  page CSS px for browser shots (the recorded viewport) and in window px (1520×855) for terminal shots. Only the
+  window's content zooms.
+- `chapter: ['Step 1', 'Install']` — the pill and title top-left; it stays until the next chapter.
+- `keys: [[t0 | 'anchor|off', len, 'Enter', 'label']]` — a key badge for `len` seconds.
+- `note: 'text'` — a line at the bottom of the stage for the shot.
+- `vo: [[lineId, seg, offset]]` — voice cues: line `L03` starts `offset` seconds after segment `seg` begins
+  (`-1` = the shot's start). They become `events.vo` for the mix and the subtitles.
+- `typing: [[src0, src1]]` — terminal ranges where a TUI echoes typed keys (counted as key presses).
+- `typed: [[src0, src1, n]]` — browser shots: n key presses spread over that range, when the recorder did not log them.
+
+The sound events (`motigen events`) come out of the edit: voice cues, clicks (from the clip's log), key presses
+(from the terminal's one-byte echoes, the logged keys, or `typed`), and Enter badges.
+
+## Look
+
+`/_motigen/guide/player.css` holds the geometry and the defaults; `theme.css` in the project overrides the colours
+and fonts (`--paper`, `--ink`, `--accent`, `--term`, `--font-sans`, …). The stage is 1920×1080; the window is
+1520×901 at (200, 128) with a 46 px bar. Keep the geometry: the zoom coordinates refer to it.

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "motigenjs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Video as code for developers and their coding agents: a web page draws frame t, headless Chrome renders it to MP4; real terminals and browsers are recorded, narration and the mix come from the same timeline.",
+  "type": "module",
+  "bin": {
+    "motigen": "bin/motigen.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./render": "./src/render.js",
+    "./browser": "./src/browser.js",
+    "./serve": "./src/serve.js",
+    "./project": "./src/project.js",
+    "./record": "./src/record/index.js",
+    "./audio": "./src/audio/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "runtime",
+    "templates",
+    "README.md",
+    "LICENSE",
+    "skill",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@fontsource/geist-mono": "^5.3.0",
+    "@fontsource/geist-sans": "^5.3.0",
+    "@xterm/xterm": "^5.5.0",
+    "mediabunny": "^1.65.2",
+    "playwright": "^1.63.0"
+  },
+  "keywords": [
+    "video",
+    "render",
+    "headless",
+    "playwright",
+    "ffmpeg",
+    "screencast",
+    "terminal",
+    "canvas",
+    "motion",
+    "narration",
+    "tts"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crocone/motigen.git"
+  },
+  "license": "MIT",
+  "optionalDependencies": {
+    "node-pty": "^1.1.0"
+  }
+}