voila-recorder 0.4.0 → 0.5.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,8 @@ 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>
 ```
 
 ## The loop — always follow it
@@ -45,13 +47,19 @@ npx -y voila-recorder review demo.mp4
   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).
+- `--device mobile` and `--device tablet` record real portrait viewports. Zoom is disabled on both because narrow 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.
+- 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

@@ -1,5 +1,11 @@
 # voila.
 
+[![ci](https://github.com/anzal1/voila/actions/workflows/ci.yml/badge.svg)](https://github.com/anzal1/voila/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/voila-recorder)](https://www.npmjs.com/package/voila-recorder)
+
+Verified on Linux, macOS, and Windows in CI: every push records a real demo on
+all three and checks the on-device narration track.
+
 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

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) =>
@@ -29,15 +30,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 +92,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 +107,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 +119,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
 
@@ -17,8 +19,10 @@ function arg(name, fallback = null) {
 
 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 record <url> [--steps f.yaml] [--device mobile] [--voice name] [--speed 1] [--no-narrate] [--headful] [--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 skill   (install the voila skill into ~/.claude/skills)
   voila serve   (web UI, PORT env or --port)
   voila mcp     (stdio MCP server)`;
@@ -35,6 +39,10 @@ const USAGE = `usage:
     require('./mcp');
     return;
   }
+  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.
@@ -61,7 +69,7 @@ const USAGE = `usage:
   }
 
   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);
   }
@@ -75,7 +83,13 @@ const USAGE = `usage:
   });
 
   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 +100,7 @@ const USAGE = `usage:
         url, steps, workDir,
         narrate: !process.argv.includes('--no-narrate'),
         voice: arg('--voice'),
+        speed: Number(arg('--speed', '1')) || 1,
         onStatus: s => console.error('[voila]', s),
       });
       console.log(result.video);

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.5.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voila-recorder",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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.",
   "license": "MIT",
   "main": "pipeline.js",
@@ -8,9 +8,23 @@
     "voila": "./cli.js"
   },
   "files": [
-    "cli.js", "server.js", "mcp.js", "pipeline.js", "recorder.js", "tour.js",
-    "overlay.js", "render.js", "audio.js", "review.js", "public/", "skills/",
-    "AGENTS.md", "README.md", "RECIPE.md"
+    "cli.js",
+    "server.js",
+    "mcp.js",
+    "pipeline.js",
+    "recorder.js",
+    "tour.js",
+    "overlay.js",
+    "render.js",
+    "audio.js",
+    "review.js",
+    "voices.js",
+    "auth.js",
+    "public/",
+    "skills/",
+    "AGENTS.md",
+    "README.md",
+    "RECIPE.md"
   ],
   "repository": {
     "type": "git",
@@ -25,7 +39,16 @@
     "start": "node server.js",
     "test:record": "node test.js"
   },
-  "keywords": ["demo", "screen-recording", "playwright", "mcp", "agent", "tts", "product-demo", "demos-as-code"],
+  "keywords": [
+    "demo",
+    "screen-recording",
+    "playwright",
+    "mcp",
+    "agent",
+    "tts",
+    "product-demo",
+    "demos-as-code"
+  ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "express": "^4.19.2",

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, 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 });

package/recorder.js

@@ -23,7 +23,7 @@ const DEVICES = {
     userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Mobile/15E148 Safari/604.1',
   },
   tablet: {
-    viewport: { width: 834, height: 1112 }, dpr: 2, isMobile: true, hasTouch: true, maxZoom: 1.25,
+    viewport: { width: 834, height: 1112 }, dpr: 2, isMobile: true, hasTouch: true, maxZoom: 1,
     userAgent: 'Mozilla/5.0 (iPad; CPU OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Mobile/15E148 Safari/604.1',
   },
 };
@@ -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,9 +47,14 @@ 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;
   }
 }
 
@@ -108,6 +114,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 = [];

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/skills/voila/SKILL.md

@@ -31,7 +31,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
@@ -48,12 +49,21 @@ Reference: https://voila.anzalabidi.dev/llms.txt · https://github.com/anzal1/vo
   (desktop + mobile nav).
 - On selector failure the error includes the live page outline — use it to
   patch, don't retry blindly.
-- Devices: desktop (1280×800), mobile (390×844, iPhone emulation, zoom
-  auto-disabled — mobile layouts crop badly), tablet (834×1112). Portrait
-  output on mobile.
+- Devices: desktop (1280x800), mobile (390x844, iPhone emulation), tablet
+  (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.
 - 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 };