voila-recorder 0.4.1 → 0.6.0

package/AGENTS.md

@@ -13,8 +13,8 @@ Via MCP (preferred — register once):
 claude mcp add voila -- npx -y voila-recorder mcp
 ```
 
-Tools: `voila_outline(url)` · `voila_record(url, steps_yaml?, device?)` ·
-`voila_review(video_path)`.
+Tools: `voila_outline(url)` · `voila_record(url, steps_yaml?, device?, voice?, speed?)` ·
+`voila_review(video_path)` · `voila_voices()` · `voila_login(url)`.
 
 Via CLI (no registration needed):
 
@@ -22,6 +22,11 @@ Via CLI (no registration needed):
 npx -y voila-recorder outline <url>
 npx -y voila-recorder record <url> --steps steps.yaml [--device mobile]
 npx -y voila-recorder review demo.mp4
+npx -y voila-recorder voices
+npx -y voila-recorder login <url>
+npx -y voila-recorder doctor
+npx -y voila-recorder fork demo.mp4 [--url other] [--print]
+npx -y voila-recorder rerender <dir> --voice bf_emma
 ```
 
 ## The loop — always follow it
@@ -50,7 +55,14 @@ npx -y voila-recorder review demo.mp4
   (`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.
+- Narration style: short sentences, product language, 8-15 words per beat.
+- Prefer `zoom` with a `selector` over a raw `level`: voila measures the element
+  and picks the level and camera centre so nothing gets cropped.
+- Voices: 28 English (US/UK). af_heart (A) is the default, af_bella (A-) and
+  bf_emma (British) are the other good ones. `speed` 0.5-1.6 sets pace.
+- Sign-in walls: recording refuses to film a login page. Run `voila login <url>`
+  (or the voila_login tool), let the HUMAN sign in in the window that opens, and
+  the session persists in a local profile for every later recording.
 
 ## Working on this repo
 

package/README.md

@@ -28,9 +28,18 @@ 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 doctor                                  # check + pre-download chromium and the voice model
+voila fork demo.mp4 --url https://other.app   # rebuild any voila demo from the recipe inside it
+voila rerender <dir> --voice bf_emma          # new voice, no re-recording (needs --keep-frames)
+voila login https://app.example.com           # you sign in; session saved locally
+voila voices                                  # 28 narration voices, graded
 voila mcp                                     # stdio MCP server
 ```
 
+First run downloads Chromium (~150MB) and the voice model (~90MB) into
+`~/.cache/voila`, so upgrades do not re-download. Consent banners are dismissed
+before recording, preferring "reject" over "accept".
+
 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.

package/RECIPE.md

@@ -48,7 +48,7 @@ Each step: `{ action, ...params, caption?, narration?, optional?, pause? }`
 | `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 |
+| `zoom`      | `level` (1-3) or `selector`, `ms`   | camera zoom; with a selector it frames that element |
 | `wait`      | `ms`                                | hold (cursor keeps breathing on long holds) |
 
 `caption` renders as a lower-third; `narration` is spoken by on-device TTS and

package/audio.js

@@ -7,6 +7,7 @@ const fs = require('fs');
 const path = require('path');
 const { execFile, spawn } = require('child_process');
 const ffmpegPath = require('ffmpeg-static');
+const voices = require('./voices');
 
 const run = (cmd, args) => new Promise((res, rej) => {
   execFile(cmd, args, { maxBuffer: 1e7 }, (err, stdout, stderr) =>
@@ -21,6 +22,7 @@ async function getKokoro() {
     // 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.
+    require('./modelcache').useStableCache();
     const { KokoroTTS } = require('kokoro-js');
     kokoroInstance = await KokoroTTS.from_pretrained(
       'onnx-community/Kokoro-82M-v1.0-ONNX', { dtype: 'q8' }
@@ -29,15 +31,19 @@ async function getKokoro() {
   return kokoroInstance;
 }
 
-async function synthKokoro(texts, dir, voice, onStatus) {
+async function synthKokoro(texts, dir, voice, onStatus, speed = 1) {
+  // Fail loudly on a bad voice name rather than silently using the default.
+  if (voice && /^[a-z]{2}_/.test(voice) && !voices.isValid(voice)) {
+    throw new Error(`unknown voice "${voice}". Try: ${voices.suggest(voice).join(', ')} (run \`voila voices\` for all ${voices.ranked().length})`);
+  }
   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 v = voice && voices.isValid(voice) ? voice : 'af_heart';
+  onStatus(`narrating with Kokoro (${v}${speed !== 1 ? ` @${speed}x` : ''})`);
   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 });
+    const audio = await tts.generate(texts[i], { voice: v, speed });
     await audio.save(file);
     const durMs = audio.audio && audio.sampling_rate
       ? Math.round((audio.audio.length / audio.sampling_rate) * 1000)
@@ -87,13 +93,14 @@ async function synthSay(texts, dir, voice, onStatus) {
 
 // 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 = () => {}) {
+async function prepareNarration(texts, dir, voice, onStatus = () => {}, speed = 1) {
   fs.mkdirSync(dir, { recursive: true });
   const backend = process.env.VOILA_TTS || 'kokoro';
   if (backend === 'kokoro') {
     try {
-      return await synthKokoro(texts, dir, voice, onStatus);
+      return await synthKokoro(texts, dir, voice, onStatus, speed);
     } catch (e) {
+      if (/unknown voice/.test(e.message)) throw e;   // user error, not a fallback case
       onStatus(`kokoro unavailable (${e.message.slice(0, 80)})`);
     }
   }
@@ -101,7 +108,7 @@ async function prepareNarration(texts, dir, voice, onStatus = () => {}) {
   throw new Error('no TTS backend available');
 }
 
-async function addNarration(meta, videoIn, videoOut, { voice = null, prepared = null, onStatus = () => {} } = {}) {
+async function addNarration(meta, videoIn, videoOut, { voice = null, speed = 1, prepared = null, onStatus = () => {} } = {}) {
   const segs = (meta.segments || []).filter(s => s.narration);
   if (!segs.length) {
     fs.copyFileSync(videoIn, videoOut);
@@ -113,7 +120,7 @@ async function addNarration(meta, videoIn, videoOut, { voice = null, prepared =
   let synth = prepared && prepared.clips.length === segs.length ? prepared : null;
   if (!synth) {
     try {
-      synth = await prepareNarration(segs.map(s => s.narration), dir, voice, onStatus);
+      synth = await prepareNarration(segs.map(s => s.narration), dir, voice, onStatus, speed);
     } catch (e) {
       onStatus(`narration skipped: ${e.message}`);
       fs.copyFileSync(videoIn, videoOut);

package/auth.js

@@ -0,0 +1,64 @@
+// Auth: voila never handles credentials. It opens a real browser window, the
+// person signs in themselves, and the logged-in session persists in a local
+// Chromium profile directory that only ever lives on their machine.
+
+// Heuristic: does this page look like a sign-in wall rather than the product?
+const LOGIN_MARKERS = /\b(sign in|log ?in|continue with|forgot password|create account)\b/i;
+
+async function detectAuthWall(page) {
+  try {
+    const url = page.url();
+    const signal = await page.evaluate(() => {
+      const pw = document.querySelectorAll('input[type="password"]').length;
+      const oauth = [...document.querySelectorAll('a,button')]
+        .filter(e => /continue with|sign in with/i.test(e.textContent || '')).length;
+      const bodyLen = (document.body?.innerText || '').length;
+      const head = (document.body?.innerText || '').slice(0, 400);
+      return { pw, oauth, bodyLen, head };
+    });
+    const urlLooksAuth = /\/(login|signin|sign-in|auth|account\/login)(\/|\?|$)/i.test(url);
+    // A password box, or an OAuth-only wall on a nearly empty page.
+    const isWall = signal.pw > 0
+      || (signal.oauth > 0 && signal.bodyLen < 1200)
+      || (urlLooksAuth && LOGIN_MARKERS.test(signal.head));
+    return isWall ? { isWall: true, url } : { isWall: false };
+  } catch {
+    return { isWall: false };
+  }
+}
+
+// Open a real browser window on `url` and hold it open until the person has
+// signed in. Returns once they confirm, or once the page leaves the auth wall.
+async function login(session, url, { onStatus = () => {} } = {}) {
+  session.headless = false;
+  const page = await session.open(url);
+  onStatus('browser open: sign in in that window');
+
+  const done = new Promise(resolve => {
+    // Preferred: the person presses Enter when finished.
+    if (process.stdin.isTTY) {
+      process.stdin.setEncoding('utf8');
+      process.stdin.resume();
+      const onData = () => { process.stdin.pause(); resolve('confirmed'); };
+      process.stdin.once('data', onData);
+    }
+  });
+
+  // Fallback for non-interactive callers: poll until the auth wall is gone.
+  const watched = (async () => {
+    for (let i = 0; i < 600; i++) {
+      await new Promise(r => setTimeout(r, 1000));
+      if (page.isClosed()) return 'window closed';
+      const wall = await detectAuthWall(page);
+      if (!wall.isWall && i > 3) return 'signed in';
+    }
+    return 'timed out after 10 minutes';
+  })();
+
+  const reason = await Promise.race([done, watched]);
+  const finalUrl = page.isClosed() ? url : page.url();
+  await session.close();
+  return { reason, profileDir: session.profileDir, finalUrl };
+}
+
+module.exports = { login, detectAuthWall };

package/cli.js

@@ -3,6 +3,8 @@
 //   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 login <url> [--profile dir]
+//   voila voices
 //   voila serve [--port 4477]
 //   voila mcp
 
@@ -16,9 +18,14 @@ function arg(name, fallback = null) {
 }
 
 const USAGE = `usage:
+  voila doctor                          (check + download everything voila needs)
   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 record <url> [--steps f.yaml] [--device mobile] [--voice name] [--speed 1] [--no-narrate] [--headful] [--keep-frames] [--no-dismiss] [--dismiss sel] [--out dir] [--profile dir]
   voila review <video.mp4> [--frames 12] [--out dir]
+  voila login <url> [--profile dir]     (sign in yourself; session is saved locally)
+  voila voices                          (list every narration voice, best first)
+  voila fork <video.mp4> [--url u] [--voice v] [--print] [--out dir]
+  voila rerender <dir> [--voice v] [--speed n]   (needs --keep-frames on the original)
   voila skill   (install the voila skill into ~/.claude/skills)
   voila serve   (web UI, PORT env or --port)
   voila mcp     (stdio MCP server)`;
@@ -35,6 +42,16 @@ const USAGE = `usage:
     require('./mcp');
     return;
   }
+  if (cmd === 'doctor' || cmd === '--version' || cmd === '-v') {
+    if (cmd !== 'doctor') { console.log(require('./package.json').version); return; }
+    console.error(`voila ${require('./package.json').version}\n`);
+    const r = await require('./doctor').doctor({ fix: !process.argv.includes('--check') });
+    process.exit(r.ready ? 0 : 1);
+  }
+  if (cmd === 'voices') {
+    console.log(require('./voices').format());
+    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.
@@ -60,8 +77,62 @@ const USAGE = `usage:
     return;
   }
 
+  if (cmd === 'fork') {
+    // The recipe inside a voila MP4 is its source. Turn it back into a script
+    // and, unless --print, record it again (optionally against another URL).
+    const video = process.argv[3];
+    if (!video) { console.error(USAGE); process.exit(1); }
+    const { reviewDemo } = require('./review');
+    const info = await reviewDemo(video, { count: 3 });
+    if (!info.recipe || !info.recipe.steps) {
+      console.error('FAILED: no voila recipe found in that file (was it made by voila?)');
+      process.exit(1);
+    }
+    const stepsYaml = yaml.dump(info.recipe.steps);
+    if (process.argv.includes('--print')) { console.log(stepsYaml); return; }
+
+    const target = arg('--url', info.recipe.url);
+    const workDir = arg('--out', path.join(__dirname, 'recordings', `fork-${Date.now()}`));
+    fs.mkdirSync(workDir, { recursive: true });
+    fs.writeFileSync(path.join(workDir, 'steps.yaml'), stepsYaml);
+    console.error(`[voila] forking ${info.recipe.steps.length} steps onto ${target}`);
+
+    const { VoilaSession } = require('./recorder');
+    const { produceDemo } = require('./pipeline');
+    const s2 = new VoilaSession({
+      headless: !process.argv.includes('--headful'),
+      device: arg('--device', 'desktop'),
+      profileDir: arg('--profile', path.join(__dirname, 'profile')),
+    });
+    try {
+      const r = await produceDemo(s2, {
+        url: target, steps: yaml.load(stepsYaml), workDir,
+        narrate: !process.argv.includes('--no-narrate'),
+        voice: arg('--voice'), speed: Number(arg('--speed', '1')) || 1,
+        keepFrames: process.argv.includes('--keep-frames'),
+        onStatus: m => console.error('[voila]', m),
+      });
+      console.log(r.video);
+    } finally { await s2.close(); }
+    return;
+  }
+
+  if (cmd === 'rerender') {
+    const dir = process.argv[3];
+    if (!dir) { console.error(USAGE); process.exit(1); }
+    const { rerender } = require('./pipeline');
+    const r = await rerender(dir, {
+      voice: arg('--voice'),
+      speed: Number(arg('--speed', '1')) || 1,
+      narrate: !process.argv.includes('--no-narrate'),
+      onStatus: m => console.error('[voila]', m),
+    });
+    console.log(r.video);
+    return;
+  }
+
   const url = process.argv[3];
-  if (!cmd || !url || !['outline', 'record'].includes(cmd)) {
+  if (!cmd || !url || !['outline', 'record', 'login'].includes(cmd)) {
     console.error(USAGE);
     process.exit(1);
   }
@@ -72,10 +143,18 @@ const USAGE = `usage:
     headless: !process.argv.includes('--headful'),
     device: arg('--device', 'desktop'),
     profileDir: arg('--profile', path.join(__dirname, 'profile')),
+    dismiss: !process.argv.includes('--no-dismiss'),
+    dismissSelector: arg('--dismiss'),
   });
 
   try {
-    if (cmd === 'outline') {
+    if (cmd === 'login') {
+      const { login } = require('./auth');
+      console.error('[voila] opening a browser window. Sign in there, then press Enter here.');
+      const r = await login(session, url, { onStatus: m => console.error('[voila]', m) });
+      console.error(`[voila] ${r.reason}. Session saved to ${r.profileDir}`);
+      console.log(r.profileDir);
+    } else if (cmd === 'outline') {
       console.log(JSON.stringify(await outline(session, url), null, 2));
     } else {
       const stepsFile = arg('--steps');
@@ -86,6 +165,8 @@ const USAGE = `usage:
         url, steps, workDir,
         narrate: !process.argv.includes('--no-narrate'),
         voice: arg('--voice'),
+        speed: Number(arg('--speed', '1')) || 1,
+        keepFrames: process.argv.includes('--keep-frames'),
         onStatus: s => console.error('[voila]', s),
       });
       console.log(result.video);

package/consent.js

@@ -0,0 +1,97 @@
+// Cookie and consent banners ruin a demo: they sit in frame for the whole
+// recording. Dismiss them before the camera rolls.
+//
+// Privacy first: we look for "reject" / "necessary only" before "accept", so
+// the recorded session declines non-essential cookies wherever that choice
+// exists. Accepting is only a last resort to clear the overlay.
+
+const REJECT = [
+  /^(reject|decline|refuse)( all)?$/i,
+  /necessary (cookies )?only/i,
+  /^only (essential|necessary|required)/i,
+  /^(essential|required) (cookies )?only/i,
+  /continue without accepting/i,
+  /^reject non-essential/i,
+];
+
+const ACCEPT = [
+  /^(accept|allow|agree)( all| cookies)?$/i,
+  /^(ok|got it|i understand|understood)$/i,
+  /^(dismiss|close)$/i,
+];
+
+// Runs in the page. Returns the label it clicked, or null.
+const dismissInPage = ([rejectSrc, acceptSrc]) => {
+  const toRe = arr => arr.map(([s, f]) => new RegExp(s, f));
+  const reject = toRe(rejectSrc), accept = toRe(acceptSrc);
+
+  const visible = el => {
+    const r = el.getBoundingClientRect();
+    const cs = getComputedStyle(el);
+    return r.width > 20 && r.height > 12 && cs.visibility !== 'hidden' && cs.opacity !== '0';
+  };
+
+  // Only consider controls that live inside something banner-shaped, so we
+  // never click an "Accept" button that is part of the product itself.
+  const looksLikeBanner = el => {
+    const box = el.closest('[class*="cookie" i],[id*="cookie" i],[class*="consent" i],[id*="consent" i],[class*="gdpr" i],[id*="gdpr" i],[aria-label*="cookie" i],[role="dialog"],[class*="banner" i]');
+    if (box) return true;
+    // Or a fixed-position bar pinned to an edge of the viewport.
+    let n = el;
+    for (let i = 0; i < 6 && n; i++, n = n.parentElement) {
+      const cs = getComputedStyle(n);
+      if (cs.position === 'fixed' || cs.position === 'sticky') {
+        const r = n.getBoundingClientRect();
+        if (r.width > innerWidth * 0.5 && (r.bottom > innerHeight * 0.6 || r.top < innerHeight * 0.4)) return true;
+      }
+    }
+    return false;
+  };
+
+  const controls = [...document.querySelectorAll('button,a[role="button"],[role="button"],input[type="button"],input[type="submit"]')]
+    .filter(visible).filter(looksLikeBanner);
+
+  for (const patterns of [reject, accept]) {
+    for (const el of controls) {
+      const label = (el.innerText || el.value || el.getAttribute('aria-label') || '').trim();
+      if (!label || label.length > 40) continue;
+      if (patterns.some(re => re.test(label))) { el.click(); return label; }
+    }
+  }
+  return null;
+};
+
+async function dismissConsent(page, { selector = null, timeout = 2500 } = {}) {
+  const results = [];
+  if (selector) {
+    const el = page.locator(selector).first();
+    try {
+      await el.waitFor({ state: 'visible', timeout });
+      await el.click({ timeout: 2000 });
+      results.push(`custom: ${selector}`);
+    } catch { /* nothing matched the override */ }
+  }
+
+  const src = [
+    REJECT.map(r => [r.source, r.flags]),
+    ACCEPT.map(r => [r.source, r.flags]),
+  ];
+
+  // Banners often mount late, and some sites stack two of them.
+  for (let attempt = 0; attempt < 3; attempt++) {
+    let clicked = null;
+    try {
+      clicked = await page.evaluate(dismissInPage, src);
+      for (const frame of page.frames()) {
+        if (clicked || frame === page.mainFrame()) continue;
+        clicked = await frame.evaluate(dismissInPage, src).catch(() => null);
+      }
+    } catch { /* page navigated mid-check */ }
+    if (clicked) results.push(clicked);
+    await page.waitForTimeout(attempt === 0 ? 700 : 500);
+    if (!clicked && attempt > 0) break;
+  }
+  return results;
+}
+
+module.exports = { dismissConsent };

package/doctor.js

@@ -0,0 +1,118 @@
+// Pre-flight: tell people what voila needs, what is already on disk, and
+// download the rest with visible progress. The first run used to be several
+// silent minutes, which reads as a hang.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFile, execFileSync } = require('child_process');
+
+const MB = n => `${(n / 1e6).toFixed(0)}MB`;
+
+function chromiumPath() {
+  try {
+    const { chromium } = require('playwright');
+    return chromium.executablePath();
+  } catch { return null; }
+}
+
+function chromiumReady() {
+  const p = chromiumPath();
+  return !!(p && fs.existsSync(p));
+}
+
+// transformers.js caches models under ~/.cache/huggingface by default.
+function kokoroCacheDir() {
+  return require('./modelcache').CACHE_DIR;
+}
+
+function kokoroReady() {
+  const dir = kokoroCacheDir();
+  if (!fs.existsSync(dir)) return false;
+  const hit = [];
+  const walk = (d, depth = 0) => {
+    if (depth > 4 || hit.length) return;
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      if (hit.length) return;
+      const full = path.join(d, e.name);
+      if (e.isDirectory()) walk(full, depth + 1);
+      else if (/\.onnx(_data)?$/.test(e.name) && fs.statSync(full).size > 5e6) hit.push(full);
+    }
+  };
+  try { walk(dir); } catch { /* unreadable cache */ }
+  return hit.length > 0;
+}
+
+function ffmpegReady() {
+  try { return fs.existsSync(require('ffmpeg-static')); } catch { return false; }
+}
+
+// Install Chromium with its progress bar visible instead of swallowed.
+function installChromium({ quiet = false } = {}) {
+  let cliPath;
+  try { cliPath = require.resolve('playwright/cli'); }
+  catch { cliPath = path.join(path.dirname(require.resolve('playwright')), 'cli.js'); }
+  execFileSync(process.execPath, [cliPath, 'install', 'chromium'], {
+    stdio: quiet ? 'pipe' : ['ignore', 'inherit', 'inherit'],
+    timeout: 900000,
+  });
+}
+
+async function warmKokoro(onStatus = () => {}) {
+  require('./modelcache').useStableCache();
+  const { KokoroTTS } = require('kokoro-js');
+  let lastPct = -5;
+  const tts = await KokoroTTS.from_pretrained('onnx-community/Kokoro-82M-v1.0-ONNX', {
+    dtype: 'q8',
+    progress_callback: p => {
+      if (p.status === 'download') return onStatus(`fetching ${p.file}`);
+      if (p.status !== 'progress') return;
+      // Hugging Face omits content-length on some files, so fall back to bytes.
+      if (typeof p.total === 'number' && p.total > 0) {
+        const pct = Math.floor((p.progress || 0) / 5) * 5;
+        if (pct > lastPct) { lastPct = pct; onStatus(`${p.file || 'model'} ${pct}% of ${MB(p.total)}`); }
+      } else if (typeof p.loaded === 'number') {
+        const step = Math.floor(p.loaded / 1e7);
+        if (step > lastPct) { lastPct = step; onStatus(`${p.file || 'model'} ${MB(p.loaded)} downloaded`); }
+      }
+    },
+  });
+  // Force one tiny synthesis so the voice files are fetched too.
+  await tts.generate('Ready.', { voice: 'af_heart' });
+  return true;
+}
+
+async function doctor({ fix = true, log = console.error } = {}) {
+  const nodeOk = Number(process.versions.node.split('.')[0]) >= 20;
+  log(`node        ${process.versions.node} ${nodeOk ? 'ok' : 'TOO OLD, voila needs >= 20'}`);
+  log(`ffmpeg      ${ffmpegReady() ? 'bundled, ok' : 'MISSING (reinstall voila-recorder)'}`);
+
+  let chrome = chromiumReady();
+  log(`chromium    ${chrome ? 'installed' : 'not installed (~150MB download)'}`);
+  if (!chrome && fix) {
+    log('\ndownloading chromium...');
+    installChromium();
+    chrome = chromiumReady();
+    log(`chromium    ${chrome ? 'installed' : 'FAILED'}`);
+  }
+
+  let voice = kokoroReady();
+  log(`voice model ${voice ? `cached in ${kokoroCacheDir()}` : 'not cached (~90MB download, first narration only)'}`);
+  if (!voice && fix) {
+    log('\nfetching the voice model...');
+    try {
+      await warmKokoro(m => log(`  ${m}`));
+      voice = true;
+      log('voice model cached');
+    } catch (e) {
+      log(`voice model FAILED: ${e.message.slice(0, 120)}`);
+      log('(recording still works with --no-narrate)');
+    }
+  }
+
+  const ready = nodeOk && ffmpegReady() && chrome;
+  log(`\n${ready ? 'voila is ready. Try: voila record https://example.com' : 'voila is not ready yet, see above.'}`);
+  return { nodeOk, ffmpeg: ffmpegReady(), chromium: chrome, voice, ready };
+}
+
+module.exports = { doctor, chromiumReady, kokoroReady, installChromium, warmKokoro };

package/mcp.js

@@ -13,6 +13,7 @@ const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio
 const { VoilaSession } = require('./recorder');
 const { produceDemo, outline } = require('./pipeline');
 const { reviewDemo } = require('./review');
+const voiceCatalogue = require('./voices');
 
 // One persistent Chromium profile can't be opened twice, so browser work is
 // serialized through a queue: concurrent tool calls wait instead of colliding.
@@ -36,7 +37,7 @@ function getSession(device) {
   return sessions.get(key);
 }
 
-const server = new McpServer({ name: 'voila', version: '0.4.0' });
+const server = new McpServer({ name: 'voila', version: '0.6.0' });
 const deviceParam = z.enum(['desktop', 'mobile', 'tablet']).optional().default('desktop');
 
 server.tool(
@@ -55,7 +56,8 @@ server.tool(
   '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. ' +
+  'Actions: goto, click, hover, type, scroll, scroll_to, slide (animated full-screen title card: title/subtitle/accent), zoom, wait. '  +
+  'zoom accepts either level (1-3) or, better, selector: it then frames that element, choosing the level and camera centre for you. ' +
   '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. ' +
@@ -66,15 +68,16 @@ server.tool(
     url: z.string().url(),
     steps_yaml: z.string().optional(),
     narrate: z.boolean().optional().default(true),
-    voice: z.string().optional(),
+    voice: z.string().optional().describe('narration voice id, e.g. af_heart (A), af_bella (A-), bf_emma (B-, British). Call voila_voices for the full list.'),
+    speed: z.number().min(0.5).max(1.6).optional().default(1).describe('narration speed; 0.9 reads calmer'),
     device: deviceParam,
   },
-  async ({ url, steps_yaml, narrate, voice, device }) => enqueue(async () => {
+  async ({ url, steps_yaml, narrate, voice, speed, 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,
+      url, steps, workDir, narrate, voice: voice || null, speed,
       onStatus: () => {},
     });
     return {
@@ -111,6 +114,37 @@ server.tool(
   })
 );
 
+server.tool(
+  'voila_voices',
+  'List every narration voice with its quality grade, best first. Use before voila_record when the ' +
+  'user asks for a different voice, an accent, or a male or female narrator.',
+  {},
+  async () => ({
+    content: [{ type: 'text', text: JSON.stringify(voiceCatalogue.ranked(), null, 2) }],
+  })
+);
+
+server.tool(
+  'voila_login',
+  'Open a real browser window so the PERSON can sign in to their product themselves. The session is ' +
+  'saved to a local Chromium profile and every later recording of that site is already logged in. ' +
+  'Call this when voila_record fails saying it hit a sign-in page. voila never sees or types ' +
+  'credentials: you are only opening the window for the human. Requires a desktop session; tell the ' +
+  'user to watch for the window.',
+  { url: z.string().url(), device: deviceParam },
+  async ({ url, device }) => enqueue(async () => {
+    const s = getSession(device);
+    const { login } = require('./auth');
+    const r = await login(s, url);
+    return {
+      content: [{ type: 'text', text: JSON.stringify({
+        result: r.reason, profile: r.profileDir, endedOn: r.finalUrl,
+        next: 'Re-run voila_record; the recording will reuse this signed-in profile.',
+      }, null, 2) }],
+    };
+  })
+);
+
 (async () => {
   await server.connect(new StdioServerTransport());
 })().catch(e => { console.error(e); process.exit(1); });

package/modelcache.js

@@ -0,0 +1,22 @@
+// transformers.js caches models inside its own node_modules folder by default,
+// so every voila upgrade (and every fresh npx hash) would re-download ~90MB.
+// Pin the cache to a stable per-user directory instead.
+
+const os = require('os');
+const path = require('path');
+
+const CACHE_DIR = process.env.VOILA_MODEL_DIR
+  || path.join(os.homedir(), '.cache', 'voila', 'models');
+
+let applied = false;
+function useStableCache() {
+  if (applied) return CACHE_DIR;
+  try {
+    const { env } = require('@huggingface/transformers');
+    env.cacheDir = CACHE_DIR;
+    applied = true;
+  } catch { /* transformers not resolvable; kokoro will use its default */ }
+  return CACHE_DIR;
+}
+
+module.exports = { useStableCache, CACHE_DIR };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "voila-recorder",
-  "version": "0.4.1",
-  "description": "Permission-free product demo recorder: URL in, narrated auto-zoomed MP4 out — with the recipe embedded in the video. Agent-native (MCP), fully on-device.",
+  "version": "0.6.0",
+  "description": "Permission-free product demo recorder: URL in, narrated auto-zoomed MP4 out \u2014 with the recipe embedded in the video. Agent-native (MCP), fully on-device.",
   "license": "MIT",
   "main": "pipeline.js",
   "bin": {
@@ -18,11 +18,17 @@
     "render.js",
     "audio.js",
     "review.js",
+    "modelcache.js",
+    "consent.js",
+    "doctor.js",
+    "voices.js",
+    "auth.js",
     "public/",
     "skills/",
     "AGENTS.md",
     "README.md",
-    "RECIPE.md"
+    "RECIPE.md",
+    "scripts/"
   ],
   "repository": {
     "type": "git",
@@ -56,4 +62,4 @@
     "playwright": "^1.48.0",
     "sharp": "^0.33.5"
   }
-}
+}

package/pipeline.js

@@ -44,7 +44,7 @@ function embedRecipe(videoIn, videoOut, recipe) {
   });
 }
 
-async function produceDemo(session, { url, mode = 'auto', steps = null, workDir, voice = null, narrate = true, onStatus = () => {} }) {
+async function produceDemo(session, { url, mode = 'auto', steps = null, workDir, voice = null, speed = 1, narrate = true, keepFrames = false, onStatus = () => {} }) {
   // Steps mode: synthesize narration BEFORE recording so segment pacing and
   // caption lifetimes match the spoken clip durations exactly.
   let prepared = null;
@@ -52,7 +52,7 @@ async function produceDemo(session, { url, mode = 'auto', steps = null, workDir,
     const texts = steps.filter(s => s.narration).map(s => s.narration);
     if (texts.length) {
       try {
-        prepared = await prepareNarration(texts, path.join(workDir, 'tts'), voice, onStatus);
+        prepared = await prepareNarration(texts, path.join(workDir, 'tts'), voice, onStatus, speed);
         let i = 0;
         for (const s of steps) if (s.narration) s._narrDurMs = prepared.clips[i++].durMs;
       } catch (e) {
@@ -69,7 +69,7 @@ async function produceDemo(session, { url, mode = 'auto', steps = null, workDir,
   await render(meta, raw, { onStatus });
 
   let narration = { narrated: false };
-  if (narrate) narration = await addNarration(meta, raw, narrated, { voice, prepared, onStatus });
+  if (narrate) narration = await addNarration(meta, raw, narrated, { voice, speed, prepared, onStatus });
   else fs.copyFileSync(raw, narrated);
 
   const recipe = buildRecipe({ url, mode, steps, meta });
@@ -77,10 +77,40 @@ async function produceDemo(session, { url, mode = 'auto', steps = null, workDir,
   onStatus('embedding recipe');
   await embedRecipe(narrated, out, recipe);
 
-  fs.rmSync(meta.framesDir, { recursive: true, force: true });
+  // Frames are the expensive part to recreate: keeping them lets `voila
+  // rerender` change the voice, speed or captions in seconds instead of
+  // re-driving the browser. They are large, so it is opt-in.
+  if (!keepFrames) fs.rmSync(meta.framesDir, { recursive: true, force: true });
   fs.rmSync(raw, { force: true });
   fs.rmSync(narrated, { force: true });
-  return { video: out, recipe: path.join(workDir, 'recipe.json'), meta, narration };
+  return { video: out, recipe: path.join(workDir, 'recipe.json'), meta, narration, framesKept: keepFrames };
+}
+
+// Re-produce the video from frames already on disk: no browser, no re-driving
+// the page. Used to swap the narration voice or speed after the fact.
+async function rerender(workDir, { voice = null, speed = 1, narrate = true, onStatus = () => {} } = {}) {
+  const metaPath = path.join(workDir, 'meta.json');
+  if (!fs.existsSync(metaPath)) throw new Error(`no meta.json in ${workDir}`);
+  const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+  if (!fs.existsSync(meta.framesDir) || !fs.readdirSync(meta.framesDir).length) {
+    throw new Error(`frames were not kept for this recording. Re-record with --keep-frames to enable rerender.`);
+  }
+
+  const raw = path.join(workDir, 'raw.mp4');
+  const narrated = path.join(workDir, 'narrated.mp4');
+  const out = path.join(workDir, 'demo.mp4');
+  await render(meta, raw, { onStatus });
+
+  let narration = { narrated: false };
+  if (narrate) narration = await addNarration(meta, raw, narrated, { voice, speed, onStatus });
+  else fs.copyFileSync(raw, narrated);
+
+  const recipe = JSON.parse(fs.readFileSync(path.join(workDir, 'recipe.json'), 'utf8'));
+  onStatus('embedding recipe');
+  await embedRecipe(narrated, out, recipe);
+  fs.rmSync(raw, { force: true });
+  fs.rmSync(narrated, { force: true });
+  return { video: out, meta, narration };
 }
 
 async function outline(session, url) {
@@ -88,4 +118,4 @@ async function outline(session, url) {
   return extractOutline(page);
 }
 
-module.exports = { produceDemo, outline };
+module.exports = { produceDemo, rerender, outline };

package/recorder.js

@@ -38,6 +38,7 @@ class Timeline {
     this.warnings = [];
     this.pos = { x: -60, y: -60 };
     this.zoom = 1;
+    this.center = null;
   }
   recordSegment(caption, narration, dur = null) {
     this.segments.push({ t: Date.now(), caption: caption || null, narration: narration || null, dur });
@@ -46,14 +47,21 @@ class Timeline {
     this.moves.push({ t: Date.now(), from: { ...this.pos }, to: { ...to }, dur });
     this.pos = { ...to };
   }
-  recordZoom(level, dur) {
-    this.zooms.push({ t: Date.now(), from: this.zoom, to: level, dur });
+  // center: {x,y} in CSS px to frame on, or null to follow the cursor.
+  recordZoom(level, dur, center = null) {
+    this.zooms.push({
+      t: Date.now(), from: this.zoom, to: level, dur,
+      fromCenter: this.center, toCenter: center,
+    });
     this.zoom = level;
+    this.center = center;
   }
 }
 
 class VoilaSession {
-  constructor({ profileDir, headless = false, device = 'desktop' } = {}) {
+  constructor({ profileDir, headless = false, device = 'desktop', dismiss = true, dismissSelector = null } = {}) {
+    this.dismiss = dismiss;
+    this.dismissSelector = dismissSelector;
     this.profileDir = profileDir || path.join(__dirname, 'profile');
     this.headless = headless;
     this.device = DEVICES[device] ? device : 'desktop';
@@ -79,11 +87,9 @@ class VoilaSession {
         // Zero-install path: fetch Chromium on first use instead of making the
         // user run `npx playwright install` themselves.
         if (!/Executable doesn't exist|missing dependencies|browser.*not found/i.test(String(e.message))) throw e;
-        const { execFileSync } = require('child_process');
-        let cliPath;
-        try { cliPath = require.resolve('playwright/cli'); }
-        catch { cliPath = path.join(path.dirname(require.resolve('playwright/package.json')), 'cli.js'); }
-        execFileSync(process.execPath, [cliPath, 'install', 'chromium'], { stdio: 'pipe', timeout: 600000 });
+        // Visible progress: a silent 150MB download reads as a hang.
+        process.stderr.write('[voila] first run: downloading Chromium (~150MB, one time)\n');
+        require('./doctor').installChromium();
         this.context = await launch();
       }
       await this.context.addInitScript(OVERLAY_SOURCE);
@@ -93,6 +99,10 @@ class VoilaSession {
     this.page.on('close', () => { this.page = null; });
     await this.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 45000 });
     await this.page.waitForLoadState('networkidle', { timeout: 8000 }).catch(() => {});
+    if (this.dismiss) {
+      const { dismissConsent } = require('./consent');
+      this.dismissed = await dismissConsent(this.page, { selector: this.dismissSelector });
+    }
     return this.page;
   }
 
@@ -108,6 +118,19 @@ class VoilaSession {
     this.page = page;
     await page.evaluate(OVERLAY_SOURCE);
 
+    // Recording a login screen is never what anyone wanted. Say so up front.
+    const { detectAuthWall } = require('./auth');
+    const wall = await detectAuthWall(page);
+    if (wall.isWall) {
+      throw new Error(
+        `this looks like a sign-in page, not your product (${wall.url}). ` +
+        `Sign in once with:  voila login ${new URL(url).origin}  ` +
+        `(a real browser window opens, you sign in yourself, the session is saved to ` +
+        `${this.profileDir}). Then re-run the recording. Pass --profile <dir> to keep ` +
+        `separate logins per product.`
+      );
+    }
+
     const client = await this.context.newCDPSession(page);
     const frames = [];
     const writes = [];
@@ -154,6 +177,7 @@ class VoilaSession {
       frames: frames.sort((a, b) => a.t - b.t),
       moves: tl.moves, zooms: tl.zooms, segments: tl.segments,
       warnings: tl.warnings || [],
+      dismissed: this.dismissed || [],
       framesDir,
     };
     fs.writeFileSync(path.join(workDir, 'meta.json'), JSON.stringify(meta));

package/render.js

@@ -20,6 +20,22 @@ function scalarAt(events, t, initial) {
   return v;
 }
 
+// Camera center: an explicit zoom target when one is set, otherwise the cursor.
+function centerAt(zooms, t, cursor) {
+  let active = null;
+  for (const e of zooms) {
+    if (t < e.t) break;
+    if (!e.toCenter) { active = null; continue; }
+    const p = cubicInOut(Math.min(1, (t - e.t) / e.dur));
+    const from = e.fromCenter || cursor;
+    active = {
+      x: from.x + (e.toCenter.x - from.x) * p,
+      y: from.y + (e.toCenter.y - from.y) * p,
+    };
+  }
+  return active || cursor;
+}
+
 function pointAt(events, t, initial) {
   let v = { ...initial };
   for (const e of events) {
@@ -125,10 +141,11 @@ async function render(meta, outFile, { fps = 30, outW = null, outH = null, onSta
 
     const z = Math.max(1, Math.min(3, scalarAt(zooms, t, 1)));
     const cur = pointAt(moves, t, { x: viewport.width / 2, y: viewport.height / 2 });
+    const cam = centerAt(zooms, t, cur);
     const caption = captionAt(meta.segments, t);
 
     const cropW = W / z, cropH = H / z;
-    let cx = cur.x * sx, cy = cur.y * sy;
+    let cx = cam.x * sx, cy = cam.y * sy;
     cx = Math.max(cropW / 2, Math.min(W - cropW / 2, cx));
     cy = Math.max(cropH / 2, Math.min(H - cropH / 2, cy));
 

package/scripts/check-audio.js

@@ -0,0 +1,14 @@
+// CI helper: assert the rendered demo actually carries a narration track.
+const { execFileSync } = require('child_process');
+const ffmpeg = require('ffmpeg-static');
+
+const file = process.argv[2];
+let out = '';
+try { execFileSync(ffmpeg, ['-i', file], { stdio: 'pipe' }); }
+catch (e) { out = String(e.stderr || ''); }
+
+if (!/Audio: aac/.test(out)) {
+  console.error(out || '(no ffmpeg output)');
+  throw new Error(`no narration track in ${file}`);
+}
+console.log(`narration track OK in ${file}`);

package/skills/voila/SKILL.md

@@ -14,9 +14,12 @@ Prefer the MCP tools if registered (`voila_outline`, `voila_record`,
 `voila_review`); otherwise use the CLI via npx:
 
 ```bash
+npx -y voila-recorder doctor            # first run: pre-downloads chromium + voice model
 npx -y voila-recorder outline <url>
 npx -y voila-recorder record <url> --steps steps.yaml [--device mobile]
 npx -y voila-recorder review demo.mp4
+npx -y voila-recorder fork demo.mp4 --url https://other.example
+npx -y voila-recorder rerender <dir> --voice bf_emma
 ```
 
 Register the MCP server once with: `claude mcp add voila -- npx -y voila-recorder mcp`
@@ -31,7 +34,8 @@ Reference: https://voila.anzalabidi.dev/llms.txt · https://github.com/anzal1/vo
    clip's length — do NOT pad waits for narration). Open and close with a
    `slide` (animated title card: `title`, `subtitle`, `accent` hex).
    Actions: goto, click, hover, type, scroll (y), scroll_to (selector),
-   slide, zoom (level), wait. Mark risky steps `optional: true`.
+   slide, zoom (level OR selector to frame an element), wait. Mark risky steps
+   `optional: true`.
 3. **Record** (`voila_record` / `record --steps`).
 4. **Review your own output** (`voila_review`) → frames + timeline. Read the
    frames. Check: cursor near what narration discusses; captions not covering
@@ -52,8 +56,24 @@ Reference: https://voila.anzalabidi.dev/llms.txt · https://github.com/anzal1/vo
   (834x1112). Zoom is auto-disabled on mobile and tablet because narrow
   layouts crop badly; both output portrait.
 - Zoom levels 1.3–1.6 on desktop; always return to 1 before ending.
-- Login-protected apps: ask the user to run the record once with `--headful`,
-  or open the web UI (`npx -y voila-recorder serve`, port 4477) and sign in —
-  the session persists in the local profile. NEVER type credentials yourself.
+- Login-protected apps: recording a sign-in page is refused with a clear error.
+  Run `voila login <url>` (or the voila_login tool): a real browser window
+  opens, the USER signs in themselves, and the session is saved to a local
+  Chromium profile every later recording reuses. Use `--profile <dir>` for
+  separate logins per product. NEVER type credentials yourself and never ask
+  for them in chat.
+- Prefer `zoom` with a `selector` over a bare `level`: voila measures the
+  element and picks the level and camera centre, so nothing is cropped.
+- Voices: `voila voices` lists 28 English voices with quality grades. af_heart
+  (A) default, af_bella (A-), af_nicole (B-), bf_emma (B-, British). `--speed`
+  or the speed param (0.5-1.6) changes pace; 0.9 reads calmer.
+- A failing step is retried once automatically; warnings appear in the result.
+- Iterating on narration? Record once with `--keep-frames`, then `rerender <dir>
+  --voice x --speed n`. It skips the browser entirely and finishes in seconds.
+- Consent banners are auto-dismissed (reject preferred over accept). Use
+  `--dismiss <selector>` for an unusual one, `--no-dismiss` to leave it alone.
+- First run on a new machine downloads ~240MB. Run `voila doctor` first and tell
+  the user it is downloading, so it does not look frozen.
+- `fork <video.mp4>` rebuilds any voila demo from the recipe inside the file.
 - Narration style: short sentences, product language, no "as you can see".
   8–15 words per beat reads best at Kokoro's pace.

package/tour.js

@@ -15,11 +15,33 @@ async function moveCursor(page, tl, x, y, dur = 700) {
   await page.evaluate(([x, y, d]) => window.__voila.moveTo(x, y, d), [x, y, dur]);
 }
 
-async function zoomTo(page, tl, level, dur = 800, { sleep, maxZoom = 3 }) {
-  tl.recordZoom(Math.min(level, maxZoom), dur);
+async function zoomTo(page, tl, level, dur = 800, { sleep, maxZoom = 3 }, center = null) {
+  tl.recordZoom(Math.min(level, maxZoom), dur, center);
   await sleep(dur);
 }
 
+// Frame an element: pick the zoom level that fits its box with breathing room,
+// and centre the camera on the element instead of wherever the cursor happens
+// to be. Returns {level, center} clamped so the crop never leaves the viewport.
+function frameElement(box, viewport, maxZoom, fill = 0.72) {
+  const padX = viewport.width * 0.06, padY = viewport.height * 0.06;
+  const level = Math.max(1, Math.min(
+    maxZoom,
+    Math.min(
+      (viewport.width * fill) / Math.max(80, box.width + padX * 2),
+      (viewport.height * fill) / Math.max(60, box.height + padY * 2)
+    )
+  ));
+  const halfW = viewport.width / level / 2, halfH = viewport.height / level / 2;
+  return {
+    level,
+    center: {
+      x: Math.max(halfW, Math.min(viewport.width - halfW, box.x + box.width / 2)),
+      y: Math.max(halfH, Math.min(viewport.height - halfH, box.y + box.height / 2)),
+    },
+  };
+}
+
 async function smoothScroll(page, tl, y, dur = 1100) {
   await ensureOverlay(page, tl);
   await page.evaluate(([y, d]) => window.__voila.scrollToY(y, d), [y, dur]);
@@ -181,11 +203,26 @@ async function autoTour(page, tl, opts) {
 // YAML: a list of {action, selector?, text?, url?, ms?, level?}
 // actions: goto, click, hover, type, scroll_to, wait, zoom
 
-async function targetBox(page, selector) {
-  let box = await page.locator(selector).first().boundingBox().catch(() => null);
-  if (!box) box = await page.locator(`${selector} >> visible=true`).first().boundingBox().catch(() => null);
-  if (!box) throw new Error(`selector not found or not visible: ${selector}`);
-  return { box, c: { x: box.x + box.width / 2, y: box.y + box.height / 2 } };
+// Resolve a selector into an on-screen box, giving the page a fair chance:
+// wait for it to attach and become visible, try the visible-only variant, and
+// scroll it into view. Only then give up.
+async function targetBox(page, selector, { timeout = 6000 } = {}) {
+  const tries = [selector, `${selector} >> visible=true`];
+  for (const sel of tries) {
+    const loc = page.locator(sel).first();
+    try {
+      await loc.waitFor({ state: 'visible', timeout: timeout / tries.length });
+    } catch { continue; }
+    let box = await loc.boundingBox().catch(() => null);
+    if (!box || box.y < 0 || box.y > page.viewportSize().height) {
+      await loc.scrollIntoViewIfNeeded({ timeout: 2000 }).catch(() => {});
+      box = await loc.boundingBox().catch(() => null);
+    }
+    if (box && box.width > 0 && box.height > 0) {
+      return { box, c: { x: box.x + box.width / 2, y: box.y + box.height / 2 } };
+    }
+  }
+  throw new Error(`selector not found or not visible: ${selector}`);
 }
 
 async function runSteps(page, tl, steps, opts) {
@@ -209,7 +246,7 @@ async function runSteps(page, tl, steps, opts) {
       segStart = Date.now();
       segMinMs = (step._narrDurMs || 0) + 600;
     }
-    try {
+    const runStep = async () => {
     switch (step.action) {
       case 'goto':
         await page.goto(step.url, { waitUntil: 'domcontentloaded' });
@@ -268,9 +305,19 @@ async function runSteps(page, tl, steps, opts) {
         });
         break;
       }
-      case 'zoom':
-        await zoomTo(page, tl, step.level || 1.5, step.ms || 800, opts);
+      case 'zoom': {
+        if (step.selector) {
+          const { box } = await targetBox(page, step.selector);
+          const vp = page.viewportSize();
+          const f = frameElement(box, vp, opts.maxZoom ?? 3, step.fill || 0.72);
+          await moveCursor(page, tl, f.center.x, f.center.y, 600);
+          await zoomTo(page, tl, step.level || f.level, step.ms || 900, opts, f.center);
+        } else {
+          // no selector: keep following the cursor
+          await zoomTo(page, tl, step.level || 1.5, step.ms || 800, opts, null);
+        }
         break;
+      }
       case 'wait': {
         const ms = step.ms || 1000;
         if (ms > 2600) {
@@ -287,6 +334,19 @@ async function runSteps(page, tl, steps, opts) {
       default:
         throw new Error(`unknown action: ${step.action}`);
     }
+    };
+
+    try {
+      try {
+        await runStep();
+      } catch (first) {
+        // Recovery: pages settle late, hydrate, animate. Give the step one
+        // more go after a beat before calling it a failure.
+        tl.warnings.push(`step ${si + 1} (${step.action}) retried after: ${first.message.slice(0, 120)}`);
+        await sleep(1200);
+        await ensureOverlay(page, tl).catch(() => {});
+        await runStep();
+      }
     } catch (e) {
       if (step.optional) {
         tl.warnings.push(`step ${si + 1} (${step.action}) skipped: ${e.message}`);

package/voices.js

@@ -0,0 +1,58 @@
+// The voice catalogue, read straight from the installed Kokoro package so it
+// can never drift from what the model can actually speak.
+
+let cache = null;
+
+function allVoices() {
+  if (cache) return cache;
+  const fs = require('fs');
+  // kokoro-js blocks deep subpath resolution, so locate the CJS bundle that
+  // `require` itself resolves to.
+  const bundle = require.resolve('kokoro-js');
+  const src = fs.readFileSync(bundle, 'utf8');
+  const re = /([a-z]{2}_[a-z]+):\{name:"([^"]+)",language:"([^"]+)",gender:"([^"]+)"(?:,traits:"[^"]*")?,targetQuality:"([^"]+)",overallGrade:"([^"]+)"\}/g;
+  const out = [];
+  let m;
+  while ((m = re.exec(src))) {
+    out.push({ id: m[1], name: m[2], language: m[3], gender: m[4], grade: m[6] });
+  }
+  cache = out;
+  return out;
+}
+
+const gradeRank = g => {
+  const base = { A: 0, B: 1, C: 2, D: 3, F: 4 }[g[0]] ?? 5;
+  const mod = g[1] === '+' ? -0.3 : g[1] === '-' ? 0.3 : 0;
+  return base + mod;
+};
+
+// Best first, so `voila voices` reads as a recommendation list.
+function ranked() {
+  return allVoices().slice().sort((a, b) => gradeRank(a.grade) - gradeRank(b.grade) || a.id.localeCompare(b.id));
+}
+
+function isValid(id) {
+  return allVoices().some(v => v.id === id);
+}
+
+function suggest(id) {
+  const near = allVoices().filter(v => v.id.includes(String(id).replace(/^[a-z]{2}_/, '')));
+  return (near.length ? near : ranked().slice(0, 4)).map(v => v.id);
+}
+
+function format() {
+  const rows = ranked();
+  const byLang = {};
+  for (const v of rows) (byLang[v.language] = byLang[v.language] || []).push(v);
+  const lines = [];
+  for (const [lang, vs] of Object.entries(byLang)) {
+    lines.push(`\n${lang}  (${vs.length} voices, best first)`);
+    for (const v of vs) {
+      lines.push(`  ${v.id.padEnd(13)} ${v.grade.padEnd(3)} ${v.gender.padEnd(7)} ${v.name}`);
+    }
+  }
+  lines.push('\nUse with: --voice af_bella   (also --speed 0.9 to slow the delivery)');
+  return lines.join('\n');
+}
+
+module.exports = { allVoices, ranked, isValid, suggest, format };