voila-recorder 0.4.0

package/AGENTS.md

@@ -0,0 +1,63 @@
+# Instructions for agents
+
+You can use voila directly — no human setup required. Everything
+self-provisions on first run (Chromium, ffmpeg, the TTS model). Node >= 20.
+
+Machine-readable version of this document: https://voila.anzalabidi.dev/llms.txt
+
+## Use it
+
+Via MCP (preferred — register once):
+
+```bash
+claude mcp add voila -- npx -y voila-recorder mcp
+```
+
+Tools: `voila_outline(url)` · `voila_record(url, steps_yaml?, device?)` ·
+`voila_review(video_path)`.
+
+Via CLI (no registration needed):
+
+```bash
+npx -y voila-recorder outline <url>
+npx -y voila-recorder record <url> --steps steps.yaml [--device mobile]
+npx -y voila-recorder review demo.mp4
+```
+
+## The loop — always follow it
+
+1. **Outline** the page. Build selectors from the real text it returns; never guess.
+2. **Write steps YAML**: every beat gets a `caption` (burned-in) and
+   `narration` (spoken; segments auto-pace to the clip length — don't pad
+   waits). Open and close with a `slide` title card. Mark risky steps
+   `optional: true`.
+3. **Record.**
+4. **Review your own frames** (`voila_review`) and actually read them: cursor
+   near what the narration discusses, captions not covering key UI, zooms on
+   content not whitespace, every page loaded. Patch the YAML, re-record.
+5. Deliver the MP4. The recipe travels inside it
+   (`ffmpeg -i demo.mp4 -f ffmetadata - | grep voila-recipe`).
+
+## Rules
+
+- Prefer `a[href='/path']`, ids, and roles over `text=` selectors (hydration
+  makes text flaky). Append `>> visible=true` when desktop and mobile nav
+  duplicate elements.
+- Selector failures name the failing step and include the live page outline —
+  patch, don't retry blindly.
+- `--device mobile` records a real iPhone-class viewport (portrait; zoom is
+  disabled on purpose — mobile layouts crop badly).
+- Login-protected apps: ask the human to sign in once
+  (`npx -y voila-recorder record <url> --headful` or the web UI via
+  `npx -y voila-recorder serve`). The session persists in a local browser
+  profile. **Never type credentials yourself.**
+- Narration style: short sentences, product language, 8–15 words per beat.
+
+## Working on this repo
+
+Plain Node, CommonJS, no build step. Key files: `recorder.js` (CDP screencast,
+device presets), `tour.js` (step executor + auto tour), `render.js`
+(zoom-follow camera, captions), `audio.js` (Kokoro/`say` TTS), `pipeline.js`
+(orchestration + recipe embedding), `review.js`, `mcp.js`, `cli.js`,
+`server.js`. Smoke test: `node test.js <url>`. The `docs/` folder is the
+GitHub Pages site.

package/README.md

@@ -0,0 +1,136 @@
+# voila.
+
+One-click, permission-free product demo recorder. Paste a URL → get a crisp,
+auto-zoomed, cursor-animated MP4. No OS screen-recording permission, ever —
+nothing captures your screen. The page is rendered inside a Chromium instance
+voila owns, and frames are pulled straight from the DevTools Protocol.
+
+## Run
+
+```bash
+npm install
+npx playwright install chromium
+npm start          # web UI at http://localhost:4477
+```
+
+Packaged as a bin (`voila`) — after `npm install -g .` (or `npm link`):
+
+```bash
+voila record https://yourproduct.com          # auto tour → narrated MP4
+voila record <url> --steps demo.yaml          # scripted demo
+voila record <url> --device mobile            # iPhone-class viewport (portrait)
+voila outline <url>                           # page structure for planning
+voila review demo.mp4 --frames 12             # frames + recipe for self-review
+voila serve                                   # web UI
+voila mcp                                     # stdio MCP server
+```
+
+Devices: `desktop` (1280×800), `mobile` (390×844, touch + mobile UA),
+`tablet` (834×1112). Cross-platform: verified on macOS and Linux (arm64
+container); recording is headless-safe for CI.
+
+## How auth works (the one-click part)
+
+Click **Open browser to sign in first** → a real Chromium window opens on the
+site → you log in yourself. Credentials never pass through voila; the session
+lives in a persistent local browser profile (`./profile`). Every recording
+after that is genuinely one click.
+
+## How it works
+
+1. **Capture** — persistent Chromium context at 2x devicePixelRatio, viewport
+   frames streamed via CDP `Page.startScreencast`. A synthetic cursor (DOM
+   overlay) is animated with eased tweens; every move/zoom is logged to a
+   timeline ([recorder.js](recorder.js), [overlay.js](overlay.js)).
+2. **Tour** — zero-config auto tour: zoom into the hero, sweep the nav, eased
+   scroll through sections pausing on salient elements, end on the CTA
+   ([tour.js](tour.js)). Or pass a YAML step script for custom flows.
+3. **Render** — the timeline is replayed over the captured frames: eased zoom
+   level + camera center following the cursor, per-frame crop with sharp,
+   piped into ffmpeg → H.264 MP4 ([render.js](render.js)).
+
+## Captions & narration
+
+Every tour segment can carry a `caption` (burned into the video as a
+lower-third) and a `narration` line, spoken by **Kokoro-82M** — open-source
+(Apache-2.0), ~80MB quantized, near-human quality, runs on CPU — fully
+on-device, no cloud, no API keys ([audio.js](audio.js)). Falls back to macOS
+`say` if Kokoro can't load. Voices: `af_heart` (default), `af_bella`,
+`am_adam`, … (`voice` param). Disable with `narrate: false` / `--no-narrate`.
+
+## Recipes — demos as code
+
+Every video ships with its source: `recipe.json` (URL + steps + narration +
+segment timings) is written next to the MP4 **and embedded in the MP4's
+comment metadata** (`voila-recipe:{...}`). Anyone you share the file with can
+extract it — `ffmpeg -i demo.mp4 -f ffmetadata -` — and their agent can
+recreate or fork the demo with `voila_record(url, steps_yaml)`. Video is the
+compiled artifact; the recipe is the source.
+
+## For agents (MCP + CLI)
+
+Agents are the primary interface — point yours at voila and it does the rest.
+Machine-readable instructions: [llms.txt](https://voila.anzalabidi.dev/llms.txt) · [AGENTS.md](AGENTS.md) · portable Claude Code skill: [skills/voila](skills/voila/SKILL.md)
+
+| Harness | Install |
+|---|---|
+| Claude Code | `npx -y voila-recorder skill` (installs the skill) + `claude mcp add voila -- npx -y voila-recorder mcp` |
+| Cursor · Windsurf · Claude Desktop | `{"voila": {"command": "npx", "args": ["-y", "voila-recorder", "mcp"]}}` |
+| Codex CLI | `[mcp_servers.voila]` · `command = "npx"` · `args = ["-y", "voila-recorder", "mcp"]` |
+| Any agent, no MCP | tell it: *"record a demo of \<url\> using voila — see voila.anzalabidi.dev/llms.txt"* |
+
+From a git clone instead of npm: `claude mcp add voila -- node /path/to/voila/mcp.js`
+
+Tools ([mcp.js](mcp.js)): `voila_outline` (page structure — nav, headings,
+CTAs — so the agent can plan selectors and write the script), `voila_record`
+(steps YAML in, narrated MP4 path out), and `voila_review` (extracts frames +
+the embedded recipe so the agent can inspect its own video, patch the steps,
+and re-record — the self-improvement loop). Failed steps raise errors that
+name the step and include the live page outline; steps marked `optional: true`
+are skipped instead of aborting. Concurrent tool calls are queued, and each
+device preset gets its own browser profile. Headless by default; set
+`VOILA_HEADFUL=1` to watch. Same pipeline via CLI:
+
+```bash
+node cli.js outline https://yourproduct.com
+node cli.js record https://yourproduct.com --steps demo.yaml
+```
+
+See [poached-demo.yaml](poached-demo.yaml) for a full agent-authored script.
+
+## Steps mode
+
+POST `/api/record` with `stepsYaml`:
+
+```yaml
+- action: goto
+  url: https://app.example.com/dashboard
+- action: hover
+  selector: "nav >> text=Reports"
+- action: click
+  selector: "text=New report"
+- action: zoom
+  level: 1.6
+- action: type
+  selector: "input[name=title]"
+  text: "Q3 revenue"
+- action: wait
+  ms: 1500
+```
+
+Actions: `goto`, `click`, `hover`, `type`, `scroll`, `scroll_to`, `slide`,
+`zoom`, `wait` — each step optionally takes `caption` and `narration`.
+
+`slide` renders an animated full-screen title card in the browser itself
+(staggered word-rise headline, accent bar, subtitle — `title`, `subtitle`,
+`accent`, `ms`), recorded like any other frame. In steps mode narration is
+synthesized **before** recording, so each segment automatically stays on
+screen for the length of its spoken clip and captions disappear exactly when
+the voiceover moves on. Clicks show a target highlight ring, cursor press,
+and a double ripple; after navigations and scrolls the cursor drifts to the
+most salient element so it never sits parked.
+
+## Env
+
+- `PORT` — server port (default 4477)
+- `VOILA_HEADLESS=1` — record headlessly (CI mode; no window pops)

package/RECIPE.md

@@ -0,0 +1,68 @@
+# voila-recipe/1 — demos as code
+
+Every voila MP4 carries its own source. The **recipe** is a JSON document
+describing how the video was made — enough for any agent (or human) to
+recreate, fork, or update the demo without ever seeing the original project.
+
+## Where it lives
+
+1. **Inside the MP4** — the QuickTime/MP4 `comment` metadata atom, prefixed
+   `voila-recipe:`. Extract it with stock ffmpeg:
+
+   ```bash
+   ffmpeg -i demo.mp4 -f ffmetadata - 2>/dev/null | grep -o 'voila-recipe:.*'
+   ```
+
+2. **Sidecar** — `recipe.json` written next to the MP4 at produce time.
+
+The embedded copy is authoritative for shared files: it survives renames,
+uploads, and downloads, because it *is part of the video file*.
+
+## Schema
+
+```jsonc
+{
+  "tool": "voila",
+  "spec": "voila-recipe/1",        // this document's version
+  "url": "https://example.com",    // where the demo was recorded
+  "mode": "steps",                 // "steps" (scripted) or "auto" (heuristic tour)
+  "steps": [ /* the script, or null in auto mode — see Actions */ ],
+  "durationSec": 65,
+  "segments": [                    // narration/caption timeline as recorded
+    { "at": 5.2, "caption": "Talent is a market", "narration": "Claim your card…" }
+  ],
+  "howToRecreate": "…human/agent-readable pointer to voila…"
+}
+```
+
+## Actions (steps mode)
+
+Each step: `{ action, ...params, caption?, narration?, optional?, pause? }`
+
+| action      | params                              | effect |
+|-------------|-------------------------------------|--------|
+| `goto`      | `url`                               | navigate; cursor drifts to salient content |
+| `click`     | `selector` (Playwright), `ms`       | move cursor → highlight ring → press + ripple → click |
+| `hover`     | `selector`, `ms`                    | move cursor onto the element |
+| `type`      | `selector`, `text`, `delay`         | click then type with human cadence |
+| `scroll`    | `y` (absolute px), `ms`             | eased scroll |
+| `scroll_to` | `selector`, `ms`                    | eased scroll until element is in view |
+| `slide`     | `title`, `subtitle?`, `accent?`, `ms?` | full-screen animated title card |
+| `zoom`      | `level` (1–3), `ms`                 | camera zoom toward the cursor |
+| `wait`      | `ms`                                | hold (cursor keeps breathing on long holds) |
+
+`caption` renders as a lower-third; `narration` is spoken by on-device TTS and
+**paces the segment** — the recording holds until the clip finishes, so a
+recreated demo re-times itself to whatever voice regenerates it.
+`optional: true` skips the step on failure instead of aborting.
+
+## Recreating
+
+With the recipe extracted, any agent can rebuild the demo:
+
+- **MCP**: `voila_record({ url, steps_yaml })` — steps serialized back to YAML.
+- **CLI**: `voila record <url> --steps recipe-steps.yaml`
+
+Selectors may need patching if the target site changed — that is the point:
+the recipe is diffable source, the video is a build artifact. Use
+`voila_review` / `voila review` to inspect a rebuilt video frame by frame.

package/audio.js

@@ -0,0 +1,154 @@
+// Narration: on-device TTS mixed under the rendered video at segment offsets.
+// Default backend is Kokoro-82M (open source, Apache-2.0, ~80MB quantized,
+// runs on CPU via ONNX — near-human quality, no cloud, no API keys).
+// Falls back to macOS `say` if Kokoro fails; passes through if no TTS exists.
+
+const fs = require('fs');
+const path = require('path');
+const { execFile, spawn } = require('child_process');
+const ffmpegPath = require('ffmpeg-static');
+
+const run = (cmd, args) => new Promise((res, rej) => {
+  execFile(cmd, args, { maxBuffer: 1e7 }, (err, stdout, stderr) =>
+    err ? rej(new Error(`${cmd} failed: ${stderr || err.message}`)) : res(stdout));
+});
+
+// --- Kokoro backend ----------------------------------------------------------
+
+let kokoroInstance = null;
+async function getKokoro() {
+  if (!kokoroInstance) {
+    // Must load the CJS build (exports map: require → dist/kokoro.cjs): it
+    // resolves bundled voice files via __dirname, while the ESM build loses
+    // __dirname and breaks when cwd isn't the package root.
+    const { KokoroTTS } = require('kokoro-js');
+    kokoroInstance = await KokoroTTS.from_pretrained(
+      'onnx-community/Kokoro-82M-v1.0-ONNX', { dtype: 'q8' }
+    );
+  }
+  return kokoroInstance;
+}
+
+async function synthKokoro(texts, dir, voice, onStatus) {
+  onStatus('loading Kokoro TTS');
+  const tts = await getKokoro();
+  const v = voice && /^[a-z]{2}_/.test(voice) ? voice : 'af_heart';
+  onStatus(`narrating with Kokoro (${v})`);
+  const clips = [];
+  for (let i = 0; i < texts.length; i++) {
+    const file = path.join(dir, `seg${i}.wav`);
+    const audio = await tts.generate(texts[i], { voice: v });
+    await audio.save(file);
+    const durMs = audio.audio && audio.sampling_rate
+      ? Math.round((audio.audio.length / audio.sampling_rate) * 1000)
+      : await ffDurationMs(file);
+    clips.push({ file, durMs });
+  }
+  return { clips, voice: v, backend: 'kokoro' };
+}
+
+// Parse a media file's duration from ffmpeg's info output (no ffprobe in ffmpeg-static).
+function ffDurationMs(file) {
+  return new Promise(resolve => {
+    execFile(ffmpegPath, ['-i', file], (_err, _stdout, stderr) => {
+      const m = /Duration:\s*(\d+):(\d+):(\d+)\.(\d+)/.exec(stderr || '');
+      resolve(m ? ((+m[1] * 3600 + +m[2] * 60 + +m[3]) * 1000 + +m[4] * 10) : 4000);
+    });
+  });
+}
+
+// --- macOS `say` fallback ----------------------------------------------------
+
+async function pickSayVoice(preferred) {
+  if (preferred && !/^[a-z]{2}_/.test(preferred)) return preferred;
+  try {
+    const list = await run('say', ['-v', '?']);
+    for (const want of [/\(Premium\)/, /\(Enhanced\)/, /^Samantha /m]) {
+      const m = list.split('\n').find(l => want.test(l));
+      if (m) return m.split(/\s{2,}/)[0].trim();
+    }
+  } catch { /* fall through */ }
+  return 'Samantha';
+}
+
+async function synthSay(texts, dir, voice, onStatus) {
+  const v = await pickSayVoice(voice);
+  onStatus(`narrating with say (${v})`);
+  const clips = [];
+  for (let i = 0; i < texts.length; i++) {
+    const file = path.join(dir, `seg${i}.aiff`);
+    await run('say', ['-v', v, '-r', '185', '-o', file, texts[i]]);
+    clips.push({ file, durMs: await ffDurationMs(file) });
+  }
+  return { clips, voice: v, backend: 'say' };
+}
+
+// --- pipeline entry ----------------------------------------------------------
+
+// Synthesize narration clips up front so the recorder can pace segments to the
+// spoken durations. Returns {clips: [{file, durMs}], voice, backend}.
+async function prepareNarration(texts, dir, voice, onStatus = () => {}) {
+  fs.mkdirSync(dir, { recursive: true });
+  const backend = process.env.VOILA_TTS || 'kokoro';
+  if (backend === 'kokoro') {
+    try {
+      return await synthKokoro(texts, dir, voice, onStatus);
+    } catch (e) {
+      onStatus(`kokoro unavailable (${e.message.slice(0, 80)})`);
+    }
+  }
+  if (process.platform === 'darwin') return synthSay(texts, dir, voice, onStatus);
+  throw new Error('no TTS backend available');
+}
+
+async function addNarration(meta, videoIn, videoOut, { voice = null, prepared = null, onStatus = () => {} } = {}) {
+  const segs = (meta.segments || []).filter(s => s.narration);
+  if (!segs.length) {
+    fs.copyFileSync(videoIn, videoOut);
+    return { narrated: false };
+  }
+
+  const dir = path.join(path.dirname(videoOut), 'tts');
+
+  let synth = prepared && prepared.clips.length === segs.length ? prepared : null;
+  if (!synth) {
+    try {
+      synth = await prepareNarration(segs.map(s => s.narration), dir, voice, onStatus);
+    } catch (e) {
+      onStatus(`narration skipped: ${e.message}`);
+      fs.copyFileSync(videoIn, videoOut);
+      return { narrated: false };
+    }
+  }
+
+  const clips = synth.clips.map((c, i) => ({
+    file: c.file,
+    delayMs: Math.max(0, segs[i].t - meta.tStart + 150),
+  }));
+
+  const durSec = ((meta.tEnd - meta.tStart) / 1000).toFixed(3);
+  const inputs = clips.flatMap(c => ['-i', c.file]);
+  const delayed = clips.map((c, i) => `[${i + 1}:a]adelay=${c.delayMs}|${c.delayMs}[a${i}]`).join(';');
+  const mixIn = clips.map((_, i) => `[a${i}]`).join('');
+  const filter = `${delayed};${mixIn}amix=inputs=${clips.length}:normalize=0,apad[aout]`;
+
+  onStatus('mixing narration');
+  await new Promise((res, rej) => {
+    const ff = spawn(ffmpegPath, [
+      '-y', '-i', videoIn, ...inputs,
+      '-filter_complex', filter,
+      '-map', '0:v', '-map', '[aout]',
+      '-c:v', 'copy', '-c:a', 'aac', '-b:a', '160k',
+      '-t', durSec, videoOut,
+    ], { stdio: ['ignore', 'ignore', 'pipe'] });
+    let err = '';
+    ff.stderr.on('data', d => { err += d; if (err.length > 20000) err = err.slice(-10000); });
+    ff.on('close', code => (code === 0 ? res() : rej(new Error(`ffmpeg mix exited ${code}\n${err.slice(-1500)}`))));
+    ff.on('error', rej);
+  });
+
+  fs.rmSync(dir, { recursive: true, force: true });
+  return { narrated: true, voice: synth.voice, backend: synth.backend, segments: clips.length };
+}
+
+module.exports = { addNarration, prepareNarration };

package/cli.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// voila CLI — same pipeline agents get via MCP.
+//   voila outline <url> [--device mobile]
+//   voila record <url> [--steps f.yaml] [--device mobile] [--voice name] [--no-narrate] [--headful] [--out dir]
+//   voila review <video.mp4> [--frames 12] [--out dir]
+//   voila serve [--port 4477]
+//   voila mcp
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+function arg(name, fallback = null) {
+  const i = process.argv.indexOf(name);
+  return i > -1 ? process.argv[i + 1] : fallback;
+}
+
+const USAGE = `usage:
+  voila outline <url> [--device desktop|mobile|tablet]
+  voila record <url> [--steps f.yaml] [--device mobile] [--voice name] [--no-narrate] [--headful] [--out dir] [--profile dir]
+  voila review <video.mp4> [--frames 12] [--out dir]
+  voila skill   (install the voila skill into ~/.claude/skills)
+  voila serve   (web UI, PORT env or --port)
+  voila mcp     (stdio MCP server)`;
+
+(async () => {
+  const cmd = process.argv[2];
+
+  if (cmd === 'serve') {
+    if (arg('--port')) process.env.PORT = arg('--port');
+    require('./server');
+    return;
+  }
+  if (cmd === 'mcp') {
+    require('./mcp');
+    return;
+  }
+  if (cmd === 'skill') {
+    // Install the agent skill the way Clipy does: one command, lands in the
+    // user's skills directory, every future session knows how to demo.
+    const os = require('os');
+    const src = path.join(__dirname, 'skills', 'voila', 'SKILL.md');
+    const dest = path.join(os.homedir(), '.claude', 'skills', 'voila');
+    fs.mkdirSync(dest, { recursive: true });
+    fs.copyFileSync(src, path.join(dest, 'SKILL.md'));
+    console.log(`✓ voila skill installed → ${path.join(dest, 'SKILL.md')}`);
+    console.log('  New Claude Code sessions will pick it up automatically.');
+    console.log('  Pair it with the MCP server: claude mcp add voila -- npx -y voila-recorder mcp');
+    return;
+  }
+  if (cmd === 'review') {
+    const video = process.argv[3];
+    if (!video) { console.error(USAGE); process.exit(1); }
+    const { reviewDemo } = require('./review');
+    const result = await reviewDemo(video, {
+      count: +(arg('--frames') || 12),
+      outDir: arg('--out'),
+    });
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  const url = process.argv[3];
+  if (!cmd || !url || !['outline', 'record'].includes(cmd)) {
+    console.error(USAGE);
+    process.exit(1);
+  }
+
+  const { VoilaSession } = require('./recorder');
+  const { produceDemo, outline } = require('./pipeline');
+  const session = new VoilaSession({
+    headless: !process.argv.includes('--headful'),
+    device: arg('--device', 'desktop'),
+    profileDir: arg('--profile', path.join(__dirname, 'profile')),
+  });
+
+  try {
+    if (cmd === 'outline') {
+      console.log(JSON.stringify(await outline(session, url), null, 2));
+    } else {
+      const stepsFile = arg('--steps');
+      const steps = stepsFile ? yaml.load(fs.readFileSync(stepsFile, 'utf8')) : null;
+      const workDir = arg('--out', path.join(__dirname, 'recordings', `cli-${Date.now()}`));
+      fs.mkdirSync(workDir, { recursive: true });
+      const result = await produceDemo(session, {
+        url, steps, workDir,
+        narrate: !process.argv.includes('--no-narrate'),
+        voice: arg('--voice'),
+        onStatus: s => console.error('[voila]', s),
+      });
+      console.log(result.video);
+    }
+  } finally {
+    await session.close();
+  }
+})().catch(e => { console.error('FAILED:', e.message || e); process.exit(1); });

package/mcp.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// voila MCP server — lets any MCP client (Claude Code, Desktop, Cursor…) plan,
+// record, and review narrated, auto-zoomed product demos. Headless by default.
+//
+// Register: claude mcp add voila -- node /path/to/voila/mcp.js
+
+const path = require('path');
+const fs = require('fs');
+const yaml = require('js-yaml');
+const { z } = require('zod');
+const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const { VoilaSession } = require('./recorder');
+const { produceDemo, outline } = require('./pipeline');
+const { reviewDemo } = require('./review');
+
+// One persistent Chromium profile can't be opened twice, so browser work is
+// serialized through a queue: concurrent tool calls wait instead of colliding.
+const sessions = new Map();
+let chain = Promise.resolve();
+const enqueue = fn => {
+  const p = chain.then(fn, fn);
+  chain = p.then(() => {}, () => {});
+  return p;
+};
+
+function getSession(device) {
+  const key = device || 'desktop';
+  if (!sessions.has(key)) {
+    sessions.set(key, new VoilaSession({
+      headless: process.env.VOILA_HEADFUL !== '1',
+      device: key,
+      profileDir: (process.env.VOILA_PROFILE || path.join(__dirname, 'profile')) + (key === 'desktop' ? '' : `-${key}`),
+    }));
+  }
+  return sessions.get(key);
+}
+
+const server = new McpServer({ name: 'voila', version: '0.4.0' });
+const deviceParam = z.enum(['desktop', 'mobile', 'tablet']).optional().default('desktop');
+
+server.tool(
+  'voila_outline',
+  'Get a structural outline of a web page (title, description, nav links, headings, buttons/CTAs). ' +
+  'Use this first to plan a demo script: the outline gives you real text to build selectors from ' +
+  '(e.g. "text=Leaderboard") and content for captions/narration.',
+  { url: z.string().url(), device: deviceParam },
+  async ({ url, device }) => enqueue(async () => ({
+    content: [{ type: 'text', text: JSON.stringify(await outline(getSession(device), url), null, 2) }],
+  }))
+);
+
+server.tool(
+  'voila_record',
+  'Record a crisp, auto-zoomed MP4 demo of a website — no screen capture, no permissions. ' +
+  'Without steps_yaml it runs a generic auto-tour. For a proper demo, pass steps_yaml: a YAML list of ' +
+  '{action, selector?, url?, text?, title?, subtitle?, accent?, level?, ms?, caption?, narration?, optional?}. ' +
+  'Actions: goto, click, hover, type, scroll, scroll_to, slide (animated full-screen title card: title/subtitle/accent), zoom, wait. ' +
+  'caption is burned into the video as a lower-third; narration is spoken via on-device TTS (Kokoro) at that step, ' +
+  'and segment pacing automatically stretches to fit each narration clip — no need to pad waits. ' +
+  'Steps marked optional:true are skipped on failure instead of aborting. ' +
+  'device selects the recorded viewport (mobile emulates an iPhone-class device). ' +
+  'On failure the error names the failing step and includes the live page outline — patch the steps and retry. ' +
+  'Returns the MP4 path, the recipe path, and any warnings.',
+  {
+    url: z.string().url(),
+    steps_yaml: z.string().optional(),
+    narrate: z.boolean().optional().default(true),
+    voice: z.string().optional(),
+    device: deviceParam,
+  },
+  async ({ url, steps_yaml, narrate, voice, device }) => enqueue(async () => {
+    const steps = steps_yaml ? yaml.load(steps_yaml) : null;
+    const workDir = path.join(__dirname, 'recordings', `mcp-${Date.now()}`);
+    fs.mkdirSync(workDir, { recursive: true });
+    const result = await produceDemo(getSession(device), {
+      url, steps, workDir, narrate, voice: voice || null,
+      onStatus: () => {},
+    });
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          video: result.video,
+          recipe: result.recipe,
+          durationSec: Math.round((result.meta.tEnd - result.meta.tStart) / 1000),
+          narrated: result.narration.narrated,
+          voice: result.narration.voice || null,
+          device: result.meta.device,
+          segments: (result.meta.segments || []).length,
+          warnings: result.meta.warnings || [],
+        }, null, 2),
+      }],
+    };
+  })
+);
+
+server.tool(
+  'voila_review',
+  'Review a finished demo: extracts evenly spaced PNG frames plus the segment timeline and embedded recipe. ' +
+  'Read the returned frame files and check: is the cursor near what the narration discusses? do captions overlap ' +
+  'important UI? is any zoom centered on whitespace? did a page fail to load? does a segment linger with nothing ' +
+  'happening? Then patch the steps YAML and call voila_record again. Works on any voila MP4, including ones ' +
+  'received from other people (the recipe travels inside the file).',
+  {
+    video_path: z.string(),
+    frame_count: z.number().int().min(3).max(40).optional().default(12),
+  },
+  async ({ video_path, frame_count }) => ({
+    content: [{ type: 'text', text: JSON.stringify(await reviewDemo(video_path, { count: frame_count }), null, 2) }],
+  })
+);
+
+(async () => {
+  await server.connect(new StdioServerTransport());
+})().catch(e => { console.error(e); process.exit(1); });