@hypersocial/decks-cli 0.9.3 → 0.9.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypersocial/decks-cli",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "Command-line client for Hypersocial Decks live analytics and share management.",
   "type": "module",
   "main": "./src/commands.mjs",

package/skills/hyperdecks/SKILL.md

@@ -144,7 +144,7 @@ Hyperdecks server; use the CLI where you have a shell and the tool otherwise.
 | Ship | `hyperdecks release decks/<slug> --to "<name>" --email <e>` | `release_deck` |
 | Share-link poster | `hyperdecks poster <slug>` | `generate_deck_poster` |
 | PDF for a data room or attachment | `hyperdecks export <slug> --pdf [--notes] --out deck.pdf`, `hyperdecks export list` | `export_deck`, `list_exports` |
-| Video (MP4) for YouTube, LinkedIn or an attachment | `hyperdecks export <slug\|deck-dir> --video [--size 1080p\|720p\|4k] [--shape 16:9\|9:16\|1:1] [--title-card] [--end-card] [--no-captions] [--no-avatar] [--upload] --out deck.mp4`: records the narrated player in real time (a 4-minute deck takes about 5), avatar, voice and captions, no player chrome; a slug records the released copy, a deck folder its working copy; `--upload` lists it with the deck's exports | `export_deck { kind: "mp4" }` answers with this command (CLI only until the render worker ships) |
+| Video (MP4) for YouTube, LinkedIn or an attachment | `hyperdecks export <slug\|deck-dir> --video [--size 1080p\|720p\|4k] [--shape 16:9\|9:16\|1:1] [--title-card] [--end-card] [--no-captions] [--no-avatar] [--upload] --out deck.mp4`: records the narrated player in real time (a 4-minute deck takes about 5), avatar, voice and captions, no player chrome; a slug records the released copy, a deck folder its working copy; `--upload` lists it with the deck's exports | `export_deck { kind: "mp4" }` renders it on our render worker (the dashboard's Export → Video); poll `check_export`, or `hyperdecks export status <exportId>` |
 | Import only | `hyperdecks import <file> --slug <slug>` | `import_deck_from_url` |
 | One more link | `hyperdecks share new <slug> "<name>" [--no-forward]` | `create_share` (`allowForward`) |
 | Forwarding, one link | `hyperdecks share forward on\|off\|default <token>` | `set_share_forwarding` |

package/skills/hyperdecks/chat.md

@@ -103,9 +103,14 @@ makes the hello deck; continue from step 5 below.
    days; `notes: true` adds the slide's script after each slide.
    `list_exports` shows what was exported. Release first: it prints the live
    deck, not the draft.
-   A video (MP4) is recorded by the CLI for now: `export_deck { kind: "mp4" }`
-   answers with the `hyperdecks export <slug> --video` command; give it to the
-   user to run (it records in real time, so a 4-minute deck takes about 5).
+   A video (MP4): `export_deck { slug, kind: "mp4", size?, shape?, titleCard?,
+   endCard? }` queues it on our render worker and returns an `exportId` at once.
+   It records in real time (a 4-minute deck takes about 5), so tell the user it
+   is on its way, then poll `check_export { exportId }` every 20-30 s: it shows
+   the slide it is on, and once `ready` a `url` plus a `title` and `description`
+   for YouTube. The owner is emailed the link too. On a server with no render
+   worker it answers with the `hyperdecks export <slug> --video` command
+   instead; give that to the user to run.
 
 ## Rules that matter
 

package/src/commands.mjs

@@ -416,12 +416,15 @@ commands:
                    with --notes), a footer with the deck's tracked link; kept 30 days
   export <slug|deck-dir> --video [--size 1080p|720p|4k] [--shape 16:9|9:16|1:1] [--no-captions]
          [--no-avatar] [--title-card] [--end-card [--link <url>]] [--upload] [--out <file.mp4>] [--json]
-                   an MP4 of the narrated deck, recorded in real time (a 4-minute deck takes about
-                   5): the avatar, voice and captions, none of the player's chrome. A slug records
+                   an MP4 of the narrated deck, drawn frame by frame so the avatar is smooth (slower
+                   than real time: a 4-minute deck takes about 25 minutes with the live head on a
+                   laptop): the avatar, voice and captions, none of the player's chrome. A slug records
                    the released copy, a deck folder its working copy. --title-card adds the title
                    and presenter (2s), --end-card the deck's "Video viewers" link (3s); --upload
                    keeps it with the deck's exports for 30 days
   export list [<slug>] [--json]    your exports and their download links
+  export status <exportId> [--json]  one export: a hosted video's progress, its link when done
+  export cancel <exportId>         stop a hosted video export (Export → Video, export_deck mp4)
   export rm <exportId>             delete an export now
   poster <slug> [--force] [--json]
                    regenerate the share-link poster (release makes one) and print its URL
@@ -712,6 +715,18 @@ async function exportCmd(pos, opts) {
   console.log(`  download (30 days): ${out.url}`);
 }
 
+// One export, a line: "pitch mp4 rendering: slide 3/12" / "… ready, 4:31, 1920×1080, 48.2 MB".
+export function exportStatusLine(r) {
+  const p = r.progress;
+  const what = r.status === "rendering" && p
+    ? (p.slides ? `slide ${p.slide}/${p.slides}` : "starting") + (p.phase && !["recording", "starting"].includes(p.phase) ? ` (${p.phase})` : "")
+    : r.status === "queued" ? `${r.ahead ?? 0} ahead in line`
+    : r.status === "failed" ? r.error ?? "failed"
+    : r.status === "ready" ? [r.seconds ? `${Math.floor(r.seconds / 60)}:${String(Math.round(r.seconds % 60)).padStart(2, "0")}` : null, r.width ? `${r.width}×${r.height}` : null, r.pages ? `${r.pages} pages` : null, r.bytes ? `${(r.bytes / 1e6).toFixed(1)} MB` : null].filter(Boolean).join(", ")
+    : "";
+  return `${r.exportId}  ${r.slug}  ${r.kind}  ${r.status}${what ? `: ${what}` : ""}`;
+}
+
 async function exportList(pos, opts) {
   const rows = await ops.listExports(opts, { slug: pos[0] });
   if (opts.json) return void console.log(JSON.stringify(rows, null, 2));
@@ -993,6 +1008,18 @@ function commandTable(pos, rest, opts) {
     poster: () => poster(pos.slice(1), opts),
     export: () => exportCmd(pos.slice(1), opts),
     "export list": () => exportList(pos.slice(2), opts),
+    "export status": async () => {
+      if (!pos[2]) throw new Error("usage: export status <exportId>");
+      const r = await ops.checkExport(opts, pos[2]);
+      if (opts.json) return void console.log(JSON.stringify(r, null, 2));
+      console.log(exportStatusLine(r));
+      if (r.url) console.log(`  ${r.url}`);
+    },
+    "export cancel": async () => {
+      if (!pos[2]) throw new Error("usage: export cancel <exportId>");
+      const out = await ops.cancelExport(opts, pos[2]);
+      console.log(`✓ cancelled ${out.exportId}`);
+    },
     "export rm": async () => {
       if (!pos[2]) throw new Error("usage: export rm <exportId>");
       const out = await ops.removeExport(opts, { exportId: pos[2] });

package/src/export-video.mjs

@@ -1,12 +1,16 @@
 // hyperdecks export <slug|deck-dir> --video: a narrated deck as an MP4.
 //
-// Real time, as the email GIF preview records (preview-capture.mjs): Chromium
-// opens the deck in the player's export mode (?export=1: no chrome, autoplay,
-// no tracking; packages/player/export-mode.js) and the compositor's screencast
-// is written to disk at 30 fps until the tour ends. The screencast has no
-// sound, so the audio track is built from the clips themselves, each placed at
-// the moment the player really started it (window.__hdExport), so the voice
-// lands under the frames that show its captions and cues. An optional title
+// Frame by frame: Chromium opens the deck in the player's export mode
+// (?export=1: no chrome, autoplay, no tracking; packages/player/export-mode.js)
+// on a page clock the recorder controls (frame-clock.mjs). Once the deck is
+// ready the clock is frozen; then, per video frame, it is advanced 1/30 s and
+// a screenshot taken, so every frame is drawn, however slowly the live head
+// draws in headless Chromium (a real-time screencast got about 5 of 30 a
+// second). It runs slower than real time. The page plays no sound (its
+// narration runs on the same clock), so the audio track is built from the
+// clips themselves, each placed at the page-clock moment the player started it
+// (window.__hdExport), so the voice lands under the frames that show its
+// captions, cues and lip-sync. An optional title
 // card (2 s) and end card (3 s) are plain pages rendered the same size.
 // ffmpeg (the CLI's portable @ffmpeg-installer build) mixes and encodes:
 // H.264, AAC, +faststart.
@@ -15,7 +19,8 @@ import { tmpdir } from 'node:os';
 import { dirname, extname, join } from 'node:path';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { allowCaptureDestination, routeCaptureRequest } from './preview-capture.mjs';
+import { allowCaptureDestination, installChromium, isMissingBrowser, routeCaptureRequest } from './preview-capture.mjs';
+import { installFrameClock } from './frame-clock.mjs';
 
 const run = promisify(execFile);
 
@@ -24,9 +29,11 @@ export const VIDEO_SIZES = Object.freeze({ '720p': 720, '1080p': 1080, '4k': 216
 export const VIDEO_SHAPES = Object.freeze(['16:9', '9:16', '1:1']);
 export const TITLE_CARD_SECONDS = 2;
 export const END_CARD_SECONDS = 3;
-// What the player's clock may run past the manifest's total before the export
-// is called stuck: slow clip loads and transitions add a little per slide.
+// Page-clock seconds a slide may run past its planned clip and hold before the
+// export is called stuck: slow clip loads and transitions add a little.
 const STUCK_GRACE_SECONDS = 60;
+// Real seconds one frame (a clock step and a screenshot) may take.
+const FRAME_TIMEOUT_MS = 60000;
 const MAX_CLIP_BYTES = 50 * 1024 * 1024;
 
 // Output pixels, and the viewport that draws them: 4K is the 1080p layout at
@@ -186,6 +193,19 @@ async function ffmpeg(path, args, timeoutMs) {
   }
 }
 
+// A clip's real length in seconds, from its decoded samples (an MP3's header
+// can be off): the page's narration ends each clip there, as <audio> would.
+const LENGTH_RATE = 8000;
+export async function clipSeconds(path, file) {
+  let stdout;
+  try {
+    ({ stdout } = await run(path, ['-hide_banner', '-loglevel', 'error', '-nostdin', '-i', file, '-vn', '-ac', '1', '-ar', String(LENGTH_RATE), '-f', 's16le', '-'], { encoding: 'buffer', timeout: 60000, maxBuffer: 256 * 1024 * 1024, env: { PATH: dirname(path), ...(process.platform === 'win32' ? { SystemRoot: process.env.SystemRoot } : {}) } }));
+  } catch (e) { throw new Error(`could not read ${file}: ${String(e.stderr || e.message).trim().split('\n').at(-1)}`); }
+  const seconds = stdout.length / 2 / LENGTH_RATE;
+  if (!(seconds > 0)) throw new Error(`could not read ${file}: no audio in it`);
+  return seconds;
+}
+
 // Bounds a page.evaluate on the Node side (a busy main thread can hold it).
 async function within(promise, ms, fallback) {
   promise.catch(() => {});
@@ -194,54 +214,54 @@ async function within(promise, ms, fallback) {
   finally { clearTimeout(timer); }
 }
 
-// Screencast frames into numbered slots from `first`, one per 1/fps from
-// `mark` (epoch seconds): each slot holds the newest frame up to half a slot
-// past its time. `stop(seconds)` fills the slots up to that many seconds after `mark`
-// with the last frame and returns how many it wrote.
-function startFrameSlots(session, { dir, fps, first }) {
-  let mark = Infinity, last = null, next = 0, writes = Promise.resolve(), received = 0, stopped = false, failed = null;
-  // The first failed write (a full disk, say) is kept and thrown by check()/stop(), never left unhandled.
-  const write = (data) => {
-    const path = join(dir, frameName(first + next++));
-    writes = writes.then(() => (failed ? null : writeFile(path, data))).catch((e) => { failed ??= e; });
-  };
-  session.on('Page.screencastFrame', ({ data, metadata, sessionId }) => {
-    session.send('Page.screencastFrameAck', { sessionId }).catch(() => {});
-    const ts = metadata.timestamp ?? Date.now() / 1000;
-    if (stopped || ts < mark) return;
-    // A slot takes the frame nearest its time: one stamped up to half a slot after it beats the one before.
-    while (last && mark + (next + 0.5) / fps < ts) write(last);
-    last = Buffer.from(data, 'base64');
-    received++;
-  });
-  return {
-    get received() { return received; },
-    check() { if (failed) throw new Error(`could not write a frame: ${failed.message}`); },
-    get latest() { return mark + next / fps; },
-    begin(poster, at) { last = poster; mark = at; },
-    async stop(seconds) {
-      stopped = true;
-      const total = Math.max(1, Math.round(seconds * fps));
-      while (next < total) write(last);
-      await writes;
-      if (failed) throw new Error(`could not write a frame: ${failed.message}`);
-      return total;
-    },
-    settled: () => writes,
-  };
-}
-
 // The player's export log, read without trusting the page to answer quickly.
-const readLog = (page) => within(page.evaluate(() => {
+// undefined when it did not answer within `ms`.
+const readLog = (page, ms = 5000) => within(page.evaluate(() => {
   const l = window.__hdExport;
   return l ? JSON.parse(JSON.stringify(l)) : null;
-}), 5000, undefined);
+}), ms, undefined);
+
+// What the page's network did before a ready timeout, for the error message.
+// `blocked` holds the URLs the capture rules refused; `failed` is the last
+// request that failed for another reason ({ url, error }).
+export function readySaw({ blocked = [], failed = null } = {}) {
+  const cut = (u) => (u.length > 160 ? `${u.slice(0, 157)}…` : u);
+  const parts = [];
+  if (blocked.length) parts.push(`${blocked.length} request${blocked.length === 1 ? '' : 's'} blocked, last ${cut(blocked.at(-1))}`);
+  // requestfailed can fire before the route handler records the block.
+  if (failed && !blocked.includes(failed.url)) parts.push(`last failed request ${cut(failed.url)} (${failed.error})`);
+  return parts.length ? ` (${parts.join('; ')})` : '';
+}
+
+// Why a child process failed: the last line it printed, or its timeout.
+const reasonOf = (e) => (e?.killed ? 'timed out' : String(e?.stderr || '').trim().split('\n').filter(Boolean).at(-1) || String(e?.message ?? e).split('\n')[0]);
+
+// Launches the recorder's Chromium. On a first run the browser is not on disk
+// yet: install it (as `preview setup` does) with one line of notice and retry
+// once, instead of stopping at "run preview setup".
+export async function launchRecorder(chromium, options, { log = () => {}, install = installChromium } = {}) {
+  const first = (e) => String(e?.message ?? e).split('\n')[0];
+  const failed = (e) => new Error(`Could not launch isolated Chromium (${first(e)}). Run \`hyperdecks preview setup\` to install it.`);
+  try { return await chromium.launch(options); }
+  catch (e) {
+    if (!isMissingBrowser(e)) throw failed(e);
+    log('first run: installing the Chromium build video export records with (one time, about a minute)…');
+    try { await install(); }
+    catch (err) { throw new Error(`Could not install isolated Chromium (${reasonOf(err)}). Run \`hyperdecks preview setup\` to retry.`); }
+    try { return await chromium.launch(options); }
+    catch (err) {
+      // Installed, yet still not where this Playwright looks: another install will not help.
+      if (isMissingBrowser(err)) throw new Error(`Installed Chromium, but this CLI's Playwright still cannot find it (${first(err)}). Check PLAYWRIGHT_BROWSERS_PATH.`);
+      throw failed(err);
+    }
+  }
+}
 
 // Records `config.url` (a page that loads player/v1) and writes the MP4.
 // config: { url, geometry, captions, avatar, titleCard, endCard, title,
 // presenter, link, out, firstPartyOrigins, playerDir }. `log` gets progress
 // lines. Returns { file, seconds, width, height, bytes, slides, clips, warnings }.
-export async function recordVideo(config, { log = () => {}, chromium: injected } = {}) {
+export async function recordVideo(config, { log = () => {}, chromium: injected, install } = {}) {
   const { geometry, out } = config;
   const ff = await ffmpegPath();
   const chromium = injected ?? (await import('playwright')).chromium;
@@ -249,20 +269,19 @@ export async function recordVideo(config, { log = () => {}, chromium: injected }
   let browser, temp, phase = 'launch';
   try {
     temp = await mkdtemp(join(tmpdir(), 'hyperdecks-video-'));
-    try {
-      browser = await chromium.launch({
-        // config.sandbox: false only for CI runners whose AppArmor blocks Chromium's sandbox (the smoke suite).
-        headless: true, timeout: 30000, chromiumSandbox: config.sandbox ?? process.platform === 'linux',
-        args: ['--autoplay-policy=no-user-gesture-required', '--mute-audio', '--enable-unsafe-swiftshader'],
-        env: { ...(process.platform === 'win32' ? { SystemRoot: process.env.SystemRoot } : {}), PATH: process.env.PATH, TMPDIR: temp, HOME: temp },
-      });
-    } catch (e) {
-      throw new Error(`Could not launch isolated Chromium (${String(e?.message ?? e).split('\n')[0]}). Run \`hyperdecks preview setup\` to install it.`);
-    }
+    browser = await launchRecorder(chromium, {
+      // config.sandbox: false only for CI runners whose AppArmor blocks Chromium's sandbox (the smoke suite).
+      headless: true, timeout: 30000, chromiumSandbox: config.sandbox ?? process.platform === 'linux',
+      args: ['--autoplay-policy=no-user-gesture-required', '--mute-audio', '--enable-unsafe-swiftshader'],
+      env: { ...(process.platform === 'win32' ? { SystemRoot: process.env.SystemRoot } : {}), PATH: process.env.PATH, TMPDIR: temp, HOME: temp },
+    }, { log, ...(install ? { install } : {}) });
     const pageUrl = exportPageUrl(config.url, config);
     const context = await browser.newContext({ viewport: geometry.viewport, deviceScaleFactor: geometry.scale, serviceWorkers: 'block', acceptDownloads: false });
-    let blocked = 0;
-    await context.route('**/*', async (route) => { if (!await routeCaptureRequest(route, pageUrl, config.firstPartyOrigins)) blocked++; });
+    const blockedUrls = [];
+    let failed = null;
+    await context.route('**/*', async (route) => {
+      if (!await routeCaptureRequest(route, pageUrl, config.firstPartyOrigins)) blockedUrls.push(route.request().url());
+    });
     // A development checkout plays its own player/v1 (HYPERDECKS_PLAYER_DIR), not the released one.
     if (config.playerDir) {
       await context.route(/\/player\/v1\/[^?#]+/, async (route) => {
@@ -274,6 +293,8 @@ export async function recordVideo(config, { log = () => {}, chromium: injected }
       });
     }
     await context.routeWebSocket('**/*', (ws) => ws.close());
+    // The page clock goes in before any of the deck's scripts (frame-clock.mjs).
+    await context.addInitScript({ content: `(${installFrameClock.toString()})(window);` });
     await context.addInitScript(() => {
       navigator.sendBeacon = () => false;
       window.open = () => null;
@@ -284,18 +305,25 @@ export async function recordVideo(config, { log = () => {}, chromium: injected }
     page.setDefaultTimeout(30000);
     const pageErrors = [];
     page.on('pageerror', (e) => pageErrors.push(String(e?.message ?? e)));
+    // A refused request also fails in the page; only the others count here.
+    page.on('requestfailed', (r) => { if (!blockedUrls.includes(r.url())) failed = { url: r.url(), error: r.failure()?.errorText ?? 'failed' }; });
     phase = 'page load';
     await page.goto(pageUrl, { waitUntil: 'domcontentloaded', timeout: 60000 });
     phase = 'player ready';
     const pageSaid = () => (pageErrors.length ? ` (page errors: ${pageErrors.slice(0, 3).join('; ').slice(0, 400)})` : '');
     await page.waitForSelector('body[data-hd-ready="true"]', { timeout: 60000 }).catch((e) => {
-      throw new Error(`the deck never became ready (${e.message.split('\n')[0]})${pageSaid()}; is it on player/v1 (https://decks.hypersocial.ai/player/v1/player.js)?`);
+      throw new Error(`the deck never became ready (${e.message.split('\n')[0]})${pageSaid()}${readySaw({ blocked: blockedUrls, failed })}; is it on player/v1 (https://decks.hypersocial.ai/player/v1/player.js)?`);
     });
-    let state = await readLog(page);
+    let state = await readLog(page, 30000);
+    if (state === undefined) throw new Error(`the deck's player did not return its export log within 30s${pageSaid()}`);
     if (!state) throw new Error(`the deck's player has no export mode: it must load https://decks.hypersocial.ai/player/v1/player.js (an older copy, or its own runtime, cannot be recorded)${pageSaid()}`);
     if (state.manifestError) throw new Error(`the deck's narration manifest could not load (${state.manifestError.url}: ${state.manifestError.message}); nothing was recorded`);
     if (state.silent) throw new Error('the deck has no narration to record: run `hyperdecks narrate` first');
+    // An older player plays its narration on wall time, which a frame-by-frame recording cannot follow.
+    if (!(state.version >= 2 && state.clock === 'page')) throw new Error('the deck\'s player is older than this CLI (its narration cannot follow a frame-by-frame recording); reload https://decks.hypersocial.ai/player/v1/player.js, or update the deck\'s copy');
     const plan = planTimeline(state.plan ?? []);
+    const face = state.presenter;
+    if (config.avatar !== false && face?.wanted === 'head' && face.shown !== 'head') warnings.push(`the deck's live head did not load${face.why ? ` (${face.why})` : ''}; the video shows ${face.shown === 'static' ? 'its still image' : 'captions only'}`);
     // The cards wear the first slide's colours and its heading's font.
     const look = await within(page.evaluate(() => {
       const first = document.querySelector('section.slide');
@@ -313,7 +341,7 @@ export async function recordVideo(config, { log = () => {}, chromium: injected }
     }), 5000, {});
     // Every clip's audio is fetched before recording: a bad URL fails now, not after minutes of real time.
     phase = 'clip audio';
-    const audioFiles = new Map();
+    const audioFiles = new Map(), clipLengths = {};
     for (const [n, url] of [...new Set((state.plan ?? []).map((s) => s.audio).filter(Boolean))].entries()) {
       const id = state.plan.find((s) => s.audio === url).id;
       if (!await allowCaptureDestination(url, pageUrl)) throw new Error(`clip ${id}'s audio is not on a public address: ${url}`);
@@ -326,8 +354,9 @@ export async function recordVideo(config, { log = () => {}, chromium: injected }
       const path = join(temp, `clip-${n}${extname(new URL(url).pathname).slice(0, 6) || '.audio'}`);
       await writeFile(path, bytes);
       audioFiles.set(url, path);
+      clipLengths[url] = await clipSeconds(ff, path).catch((e) => { throw new Error(`clip ${id}'s audio: ${e.message}`); });
     }
-    log(`recording ${plan.ids.length} slides${plan.total ? `, about ${clock(plan.total)} in real time,` : ''} at ${geometry.width}×${geometry.height} (${geometry.shape})`);
+    log(`recording ${plan.ids.length} slides${plan.total ? `, about ${clock(plan.total)} of video,` : ''} at ${geometry.width}×${geometry.height} (${geometry.shape}), frame by frame`);
 
     // The title card's frames come first.
     const lead = config.titleCard ? TITLE_CARD_SECONDS : 0;
@@ -354,47 +383,67 @@ export async function recordVideo(config, { log = () => {}, chromium: injected }
 
     phase = 'recording';
     const session = await context.newCDPSession(page);
-    const slots = startFrameSlots(session, { dir: temp, fps: VIDEO_FPS, first: frameCount });
-    await session.send('Page.startScreencast', { format: 'jpeg', quality: 90, maxWidth: geometry.width, maxHeight: geometry.height, everyNthFrame: 1 });
-    // A screenshot forces a fresh frame: it, and every compositor frame after it, show the deck as it starts.
-    const poster = await page.screenshot({ type: 'jpeg', quality: 90 });
-    const markMs = Date.now();
-    slots.begin(poster, markMs / 1000);
-    await page.evaluate(() => window.__hdExportGo());
-    // Stuck: no slide landed and no clip started for longer than the current
-    // slide's planned clip and hold (unknown for a data-clip deck) plus a grace.
+    const fps = VIDEO_FPS;
+    const startedAt = Date.now();
+    let written = Promise.resolve();
+    const capture = async () => {
+      const { data } = await within(session.send('Page.captureScreenshot', { format: 'jpeg', quality: 90, optimizeForSpeed: true }), FRAME_TIMEOUT_MS, { data: null });
+      if (!data) throw new Error(`a frame took over ${FRAME_TIMEOUT_MS / 1000}s to capture${pageSaid()}`);
+      const path = join(temp, frameName(frameCount++));
+      // One write in flight while the next frame is drawn; a failed one (a full disk) throws at the next await.
+      await written;
+      written = writeFile(path, Buffer.from(data, 'base64')).catch((e) => { throw new Error(`could not write a frame: ${e.message}`); });
+      written.catch(() => {});
+    };
+    // Frame 0 is the deck as it starts; frame n shows it n/fps seconds later on the page clock.
+    const markMs = await page.evaluate(() => performance.timeOrigin + window.__hdFrameClock.freeze());
+    // Each clip ends where its real audio does (the manifest's length can be off), as <audio> would end it.
+    await page.evaluate((lengths) => { window.__hdExportClipLengths = lengths; window.__hdExportGo(); return window.__hdFrameClock.settle(); }, clipLengths);
+    const firstFrame = frameCount;
+    await capture();
     const secondsOf = new Map(plan.ids.map((id, i) => [id, plan.seconds[i]]));
-    let shown = 0, progress = 0, movedAt = Date.now();
-    for (;;) {
-      await new Promise((ok) => setTimeout(ok, 500));
-      slots.check();
-      const next = await readLog(page);
-      if (next) state = next;
-      const failedClip = state.errors?.[0];
-      if (failedClip) throw new Error(`narration failed on ${failedClip.id} (${failedClip.message}); the tour cannot go on`);
-      const moved = (state.slides?.length ?? 0) + (state.clips?.length ?? 0);
-      if (moved !== progress) { progress = moved; movedAt = Date.now(); }
-      for (; shown < (state.slides?.length ?? 0); shown++) {
-        const s = state.slides[shown];
-        const i = plan.ids.indexOf(s.id);
-        log(`  slide ${i + 1}/${plan.ids.length} ${s.id} · ${clock(Math.max(0, (s.at - markMs) / 1000))}${plan.total ? ` of ${clock(plan.total)}` : ''}`);
+    let shown = 0, progress = 0, movedAt = 0, end = Infinity;
+    // Stuck: no slide landed and no clip started for longer than the current
+    // slide's planned clip and hold (unknown for a data-clip deck) plus a grace, on the page clock.
+    for (let n = 1; n < end; n++) {
+      const step = await within(page.evaluate(async (ms) => {
+        const t = window.__hdFrameClock.step(ms);
+        await window.__hdFrameClock.settle();
+        const l = window.__hdExport;
+        return { t, moved: l.slides.length + l.clips.length, errors: l.errors.length, done: l.done };
+      }, 1000 / fps), FRAME_TIMEOUT_MS, null);
+      if (!step) throw new Error(`the page stopped answering (a frame took over ${FRAME_TIMEOUT_MS / 1000}s to draw)${pageSaid()}`);
+      await capture();
+      const at = n / fps;
+      if (step.moved !== progress || step.errors || (step.done && end === Infinity)) {
+        const next = await readLog(page, FRAME_TIMEOUT_MS);
+        if (!next) throw new Error(`the page did not return its export log within ${FRAME_TIMEOUT_MS / 1000}s${pageSaid()}`);
+        state = next;
+        const failedClip = state.errors?.[0];
+        if (failedClip) throw new Error(`narration failed on ${failedClip.id} (${failedClip.message}); the tour cannot go on`);
+        if (step.moved !== progress) { progress = step.moved; movedAt = at; }
+        for (; shown < (state.slides?.length ?? 0); shown++) {
+          const s = state.slides[shown];
+          const i = plan.ids.indexOf(s.id);
+          log(`  slide ${i + 1}/${plan.ids.length} ${s.id} · ${clock(Math.max(0, (s.at - markMs) / 1000))}${plan.total ? ` of ${clock(plan.total)}` : ''}`);
+        }
+        // The video ends on the frame where the tour ended.
+        if (state.done) end = Math.max(n + 1, Math.round(((state.doneAt - markMs) / 1000) * fps));
       }
-      if (state.done) break;
-      const at = state.slides?.at(-1)?.id ?? plan.ids[0];
-      const allowed = ((secondsOf.get(at) || 0) * 1.5 + STUCK_GRACE_SECONDS) * 1000;
-      if (Date.now() - movedAt > allowed) throw new Error(`the tour stopped on slide ${at}: nothing moved for ${Math.round(allowed / 1000)}s${pageSaid()}`);
+      const on = state.slides?.at(-1)?.id ?? plan.ids[0];
+      const allowed = (secondsOf.get(on) || 0) * 1.5 + STUCK_GRACE_SECONDS;
+      if (end === Infinity && at - movedAt > allowed) throw new Error(`the tour stopped on slide ${on}: nothing moved for ${Math.round(allowed)}s of the deck${pageSaid()}`);
     }
-    const seconds = Math.max(0.5, (state.doneAt - markMs) / 1000);
-    // Let the compositor deliver the frames up to the end before stopping.
-    const waitUntil = Date.now() + 1500;
-    while (slots.latest < markMs / 1000 + seconds && Date.now() < waitUntil) await new Promise((ok) => setTimeout(ok, 50));
-    await session.send('Page.stopScreencast').catch(() => {});
-    frameCount += await slots.stop(seconds);
-    if (!slots.received) throw new Error('the screencast delivered no frames after the first; the capture broke (nothing would move in the video)');
+    await written;
+    const frames = frameCount - firstFrame;
+    const seconds = frames / fps;
+    const wall = (Date.now() - startedAt) / 1000;
+    log(`rendered ${frames} frames (${clock(seconds)}) in ${clock(wall)}: ${(frames / Math.max(0.001, wall)).toFixed(1)} frames a second, ${(wall / Math.max(0.001, seconds)).toFixed(1)}× the video's length`);
     // Drift means something only when every clip's planned length is known (a data-clip deck's are not).
     const drift = (state.plan ?? []).every((s) => !s.audio || s.duration > 0) ? timelineDrift(state, markMs) : [];
     const worst = drift.reduce((a, d) => (Math.abs(d.drift) > Math.abs(a.drift) ? d : a), { drift: 0 });
     if (Math.abs(worst.drift) > 2) warnings.push(`the player ran up to ${worst.drift.toFixed(1)}s off the manifest's timeline (by ${worst.id}: clip loads, transitions); each clip's audio is placed where it really started, so the voice stays in sync`);
+    const render = { frames, seconds: wall };
 
     if (config.endCard) {
       phase = 'end card';
@@ -404,7 +453,7 @@ export async function recordVideo(config, { log = () => {}, chromium: injected }
     await context.close();
     await browser.close();
     browser = null;
-    if (blocked) warnings.push(`${blocked} request(s) blocked (tracking, navigation or unsafe destinations); nothing was recorded as a view.`);
+    if (blockedUrls.length) warnings.push(`${blockedUrls.length} request(s) blocked (tracking, navigation or unsafe destinations); nothing was recorded as a view.`);
 
     phase = 'audio';
     const clips = audioTimeline(state, markMs, lead);
@@ -430,7 +479,7 @@ export async function recordVideo(config, { log = () => {}, chromium: injected }
     });
     const bytes = (await stat(out)).size;
     if (pageErrors.length) warnings.push(`${pageErrors.length} page error(s) while recording: ${pageErrors.slice(0, 2).join('; ').slice(0, 300)}`);
-    return { file: out, seconds: total, width: geometry.width, height: geometry.height, bytes, slides: plan.ids.length, clips: clips.length, warnings };
+    return { file: out, seconds: total, width: geometry.width, height: geometry.height, bytes, slides: plan.ids.length, clips: clips.length, render, warnings };
   } catch (e) {
     throw new Error(`Video export failed during ${phase}: ${e.message}`);
   } finally {

package/src/exportHelp.mjs

@@ -0,0 +1,26 @@
+// What both MCP servers (app/api/mcp/route.ts, mcp/server.mjs) say about video
+// exports, so the two never drift.
+
+export const VIDEO_EXPORT_HELP =
+  "kind \"mp4\" records the narrated deck as a video on our render worker (drawn frame by frame, " +
+  "so it takes several times the deck's length: a 4-minute deck about half an hour), with the options size (720p, 1080p, 4k), shape (16:9, 9:16, 1:1), captions, avatar, " +
+  "titleCard and endCard (the deck's tracked link). It returns { exportId, status: \"queued\" } at once: poll " +
+  "check_export(exportId) every 20-30 seconds until status is ready (url is the MP4, kept 30 days; title and description " +
+  "are ready for YouTube) or failed (error says why). The owner is also emailed the link. One video per deck at a time, " +
+  "10 a day. Same as the dashboard's Export → Video; `hyperdecks export <slug> --video` records one locally instead.";
+
+export const CHECK_EXPORT_HELP =
+  "Check an export started by export_deck: status (queued | rendering | ready | failed | cancelled); for a video, " +
+  "progress { slide, slides, phase } and ahead (jobs before it in line); once ready, url (the file, 30 days), " +
+  "filename, bytes, seconds, width, height, and title and description for a YouTube upload (the description " +
+  "carries the deck's tracked link); error when it failed. Poll every 20-30 seconds.";
+
+// The video options as zod fields (each server passes its own zod).
+export const videoExportInputs = (z) => ({
+  size: z.enum(["720p", "1080p", "4k"]).optional().describe("mp4: frame size, default 1080p"),
+  shape: z.enum(["16:9", "9:16", "1:1"]).optional().describe("mp4: default 16:9"),
+  captions: z.boolean().optional().describe("mp4: burn in captions (default true)"),
+  avatar: z.boolean().optional().describe("mp4: show the presenter (default true)"),
+  titleCard: z.boolean().optional().describe("mp4: a 2 s title card first"),
+  endCard: z.boolean().optional().describe("mp4: a 3 s end card with the deck's tracked link"),
+});

package/src/frame-clock.mjs

@@ -0,0 +1,268 @@
+// The page clock video export records on (export-video.mjs).
+//
+// Recording in real time loses frames: in headless Chromium the live head
+// (WebGL) draws a few frames a second, so a screencast gets a few. Instead the
+// recorder installs this clock before any of the page's scripts run, freezes
+// it once the deck is ready, and then, per video frame, advances it by exactly
+// 1/fps and takes a screenshot. While frozen:
+//   - performance.now() and Date.now() read the page clock;
+//   - setTimeout/setInterval fire when the clock passes their time, in order;
+//   - requestAnimationFrame callbacks run once per step, with the clock's time;
+//   - Web Animations (CSS animations and transitions, element.animate()) are
+//     paused and seeked to the clock, and finished when it passes their end
+//     (so `animation.finished` and transitionend still come).
+// So a frame that takes the page 300 ms to draw is still one frame 33 ms after
+// the last, and nothing is skipped or repeated. Before freeze() everything runs
+// on real time, so loading (fonts, the head, clip downloads) is unaffected.
+//
+// Chromium's own virtual time (Emulation.setVirtualTimePolicy) was tried
+// first: it moves timers and performance.now(), but not requestAnimationFrame
+// (its callbacks keep their real-time stamps and run many times per step) or
+// CSS animations, so the head and transitions would still run on wall time.
+//
+// installFrameClock is serialised into the page (addInitScript): it must not
+// close over anything outside itself.
+export function installFrameClock(win) {
+  if (win.__hdFrameClock) return win.__hdFrameClock;
+  const perf = win.performance;
+  const native = {
+    now: perf.now.bind(perf),
+    dateNow: win.Date.now.bind(win.Date),
+    setTimeout: win.setTimeout.bind(win),
+    clearTimeout: win.clearTimeout.bind(win),
+    raf: win.requestAnimationFrame?.bind(win),
+    caf: win.cancelAnimationFrame?.bind(win),
+  };
+  let frozen = false, t = 0, seq = 0;
+  const timers = new Map(); // id → { due, fn, args, every, native }
+  const frames = new Map(); // id → { cb, native }
+  const tracked = new WeakMap(); // Animation → { origin: clock ms at its time 0, last: its time when last seen, ours }
+  let clock_takeVideos = () => {};
+  const now = () => (frozen ? t : native.now());
+  // A callback that throws must not stop the step: report it as the page would (a pageerror).
+  const report = (e) => native.setTimeout(() => { throw e; }, 0);
+  const call = (fn, args) => {
+    try { fn(...args); } catch (e) { report(e); }
+  };
+  const fire = (id) => {
+    const x = timers.get(id);
+    if (!x) return;
+    if (x.every == null) timers.delete(id);
+    else {
+      x.due += x.every;
+      if (!frozen) x.native = native.setTimeout(() => fire(id), x.every);
+    }
+    call(x.fn, x.args);
+  };
+  const schedule = (fn, ms, args, repeat) => {
+    // A string body is not run (the player uses none); a deck that does is told, as a page error.
+    if (typeof fn !== 'function') { report(new Error('the video recorder does not run a setTimeout/setInterval given a string')); return 0; }
+    const delay = Math.max(0, Number(ms) || 0);
+    const id = ++seq;
+    const x = { due: now() + delay, fn, args, every: repeat ? Math.max(1, delay) : null, native: null };
+    if (!frozen) x.native = native.setTimeout(() => fire(id), delay);
+    timers.set(id, x);
+    return id;
+  };
+  const unschedule = (id) => {
+    const x = timers.get(id);
+    if (!x) return;
+    if (x.native != null) native.clearTimeout(x.native);
+    timers.delete(id);
+  };
+  perf.now = now;
+  const dateOffset = native.dateNow() - native.now();
+  win.Date.now = () => (frozen ? Math.round(dateOffset + t) : native.dateNow());
+  win.setTimeout = (fn, ms, ...args) => schedule(fn, ms, args, false);
+  win.setInterval = (fn, ms, ...args) => schedule(fn, ms, args, true);
+  win.clearTimeout = unschedule;
+  win.clearInterval = unschedule;
+  win.requestAnimationFrame = (cb) => {
+    const id = ++seq;
+    const x = { cb, native: null };
+    if (!frozen && native.raf) x.native = native.raf((ts) => { frames.delete(id); call(cb, [ts]); });
+    frames.set(id, x);
+    return id;
+  };
+  win.cancelAnimationFrame = (id) => {
+    const x = frames.get(id);
+    if (!x) return;
+    if (x.native != null) native.caf?.(x.native);
+    frames.delete(id);
+  };
+
+  // Every running animation, paused and placed at the clock's time. One
+  // running when the clock froze keeps its place. One seen running later
+  // starts from where the clock last saw it (0 for a new or replayed one, its
+  // paused time for one the page paused and resumed), whatever real time
+  // passed before it was seen. One the page paused itself is left alone.
+  const animate = (atFreeze = false) => {
+    const doc = win.document;
+    if (typeof doc?.getAnimations !== 'function') return;
+    // getAnimations() also brings styles up to date, so a transition a class change just started is in it.
+    for (const a of doc.getAnimations()) {
+      const rate = a.playbackRate || 1;
+      let s = tracked.get(a);
+      if (a.playState === 'running') {
+        const from = atFreeze ? Number(a.currentTime) || 0 : s?.last ?? 0;
+        s = { origin: t - from / rate, last: from, ours: true };
+        tracked.set(a, s);
+        if (nativeAnim) nativeAnim.pause.call(a); else a.pause();
+      } else if (!s?.ours || a.playState !== 'paused') {
+        tracked.set(a, { ...s, ours: false, last: a.playState === 'finished' ? 0 : Number(a.currentTime) || 0 });
+        continue;
+      }
+      const at = (t - s.origin) * rate;
+      const end = a.effect?.getComputedTiming?.().endTime;
+      if (a.playbackRate > 0 && Number.isFinite(end) && at >= end) { a.finish(); s.ours = false; s.last = 0; }
+      else { a.currentTime = Math.max(0, at); s.last = Math.max(0, at); }
+    }
+  };
+
+  // The page pausing or cancelling an animation the clock has taken gives it
+  // back to the page (the clock pauses with the native method, not these).
+  const Anim = win.Animation?.prototype;
+  const nativeAnim = Anim && { pause: Anim.pause, cancel: Anim.cancel };
+  if (Anim) {
+    Anim.pause = function pause() { const s = tracked.get(this); if (s) s.ours = false; return nativeAnim.pause.call(this); };
+    Anim.cancel = function cancel() { const s = tracked.get(this); if (s) { s.ours = false; s.last = 0; } return nativeAnim.cancel.call(this); };
+  }
+
+  // Slide <video>s: while frozen, play() and pause() only say whether the page
+  // wants one playing, and settle() seeks each playing one to the clock (loop
+  // wraps; a clip that reaches its end stops and sends `ended`).
+  const Media = win.HTMLMediaElement?.prototype;
+  const isVideo = (m) => !!win.HTMLVideoElement && m instanceof win.HTMLVideoElement;
+  const videos = new Map(); // HTMLVideoElement → { playing, origin, base }
+  let nativeMedia = null;
+  if (Media) {
+    nativeMedia = { play: Media.play, pause: Media.pause, paused: Object.getOwnPropertyDescriptor(Media, 'paused')?.get };
+    const nativelyPlaying = (v) => nativeMedia.paused && !nativeMedia.paused.call(v);
+    const send = (v, type) => v.dispatchEvent(new Event(type));
+    const take = (v) => {
+      const s = { playing: true, origin: t, base: v.currentTime || 0 };
+      videos.set(v, s);
+      if (nativelyPlaying(v)) nativeMedia.pause.call(v);
+      return s;
+    };
+    Media.play = function play() {
+      if (!frozen || !isVideo(this)) return nativeMedia.play.call(this);
+      const s = videos.get(this);
+      if (!s?.playing) {
+        if (s?.ended) this.currentTime = 0;
+        // As a real play() does, start loading a video that has not (preload="none").
+        if (this.readyState === 0 && this.networkState !== 2) { this.preload = 'auto'; this.load(); }
+        take(this);
+        send(this, 'play');
+        send(this, 'playing');
+      }
+      return Promise.resolve();
+    };
+    Media.pause = function pause() {
+      if (!frozen || !isVideo(this)) return nativeMedia.pause.call(this);
+      const s = videos.get(this);
+      if (nativelyPlaying(this)) nativeMedia.pause.call(this);
+      else if (s?.playing) send(this, 'pause');
+      if (s) s.playing = false;
+    };
+    if (nativeMedia.paused) {
+      Object.defineProperty(Media, 'paused', {
+        configurable: true,
+        get() { const s = frozen && videos.get(this); return s ? !s.playing : nativeMedia.paused.call(this); },
+      });
+    }
+    clock_takeVideos = () => {
+      for (const v of win.document?.querySelectorAll?.('video') ?? []) {
+        if (nativelyPlaying(v)) { const s = videos.get(v); if (!s?.playing) take(v); else nativeMedia.pause.call(v); }
+      }
+    };
+  }
+  // Seeks every playing video to the clock; resolves when they show it. A
+  // video whose seek does not finish within 5 s (a host that stopped answering,
+  // a file that cannot seek) is left where it is from then on and reported, so
+  // one bad clip costs one wait, not one per frame.
+  const seekVideos = () => {
+    const waits = [];
+    for (const [v, s] of videos) {
+      if (!s.playing || s.stuck || !v.isConnected || v.readyState < 1 || v.error) continue;
+      let at = s.base + ((t - s.origin) / 1000) * (v.playbackRate || 1);
+      const d = v.duration;
+      let ended = false;
+      if (Number.isFinite(d) && d > 0) {
+        if (v.loop) at %= d;
+        else if (at >= d) { at = d; ended = true; }
+      }
+      // A hair past the frame's time, so rounding never lands it on the frame before.
+      if (!ended) at = Number.isFinite(d) ? Math.min(at + 0.001, d) : at + 0.001;
+      if (Math.abs(v.currentTime - at) > 0.0005) {
+        waits.push(new Promise((ok) => {
+          const done = () => { native.clearTimeout(timer); v.removeEventListener('seeked', done); v.removeEventListener('error', done); ok(); };
+          const timer = native.setTimeout(() => {
+            done();
+            s.stuck = true;
+            report(new Error(`a slide video stopped seeking (${String(v.currentSrc || v.src).slice(0, 120)}); it holds its frame for the rest of the video`));
+          }, 5000);
+          v.addEventListener('seeked', done);
+          v.addEventListener('error', done);
+        }));
+        v.currentTime = at;
+      }
+      if (ended) {
+        s.playing = false;
+        s.ended = true;
+        v.dispatchEvent(new Event('pause'));
+        v.dispatchEvent(new Event('ended'));
+      }
+    }
+    return Promise.all(waits);
+  };
+
+  const clock = {
+    get frozen() { return frozen; },
+    // From now on the page's time moves only with step().
+    freeze() {
+      if (frozen) return t;
+      t = native.now();
+      frozen = true;
+      for (const x of timers.values()) if (x.native != null) { native.clearTimeout(x.native); x.native = null; }
+      for (const x of frames.values()) if (x.native != null) { native.caf?.(x.native); x.native = null; }
+      clock_takeVideos();
+      animate(true);
+      return t;
+    },
+    // Advances the clock `ms`: due timers fire in time order (each at its own
+    // time), then this frame's requestAnimationFrame callbacks run. Returns the
+    // new time. settle() then finishes the frame.
+    step(ms) {
+      if (!frozen) throw new Error('the frame clock is not frozen');
+      const target = t + Math.max(0, Number(ms) || 0);
+      // A timer that keeps re-arming itself at 0 ms must not hang the step: it is reported, as a page error.
+      for (let guard = 0; ; guard++) {
+        let next = null, nextId = 0;
+        for (const [id, x] of timers) if (x.due <= target && (!next || x.due < next.due || (x.due === next.due && id < nextId))) { next = x; nextId = id; }
+        if (!next) break;
+        if (guard === 100000) { report(new Error('a timer re-armed itself 100000 times in one video frame; the rest wait for the next frame')); break; }
+        t = Math.max(t, next.due);
+        fire(nextId);
+      }
+      t = target;
+      const due = [...frames.values()];
+      frames.clear();
+      for (const x of due) call(x.cb, [t]);
+      return t;
+    },
+    // Lets what the step set off finish (promise continuations: a clip's
+    // `playing`, a class it adds), then places every animation and video at the
+    // clock's time and waits for the videos to show it. Call after each step,
+    // before the screenshot.
+    async settle() {
+      await new Promise((ok) => native.setTimeout(ok, 0));
+      clock_takeVideos();
+      animate();
+      await seekVideos();
+    },
+    now,
+  };
+  win.__hdFrameClock = clock;
+  return clock;
+}

package/src/ops.mjs

@@ -206,11 +206,13 @@ export async function generatePoster(opts, fields = {}) {
 // page after each with notes=true, a footer with the deck's tracked link) and
 // keep it 30 days. Returns { exportId, url, filename, bytes, pages, slides,
 // notes, link, expiresAt }. Waits for the file (about a second per slide).
+// kind "mp4" queues a video on the render worker (convex/videoExports.ts) and
+// returns { exportId, status: "queued" } at once: follow it with checkExport.
 export async function exportDeck(opts, fields = {}) {
   if (!fields.slug) throw new Error("slug is required");
   const kind = fields.kind ?? "pdf";
-  if (kind === "mp4") throw new Error(videoFromCli(String(fields.slug)));
-  if (kind !== "pdf") throw new Error(`kind "${kind}" is not supported: "pdf", or "mp4" from the CLI`);
+  if (kind === "mp4") return requestVideoExport(opts, fields);
+  if (kind !== "pdf") throw new Error(`kind "${kind}" is not supported: "pdf" or "mp4"`);
   const args = { slug: String(fields.slug), kind: "pdf" };
   if (fields.notes) args.notes = true;
   if (fields.script) args.script = String(fields.script);
@@ -218,10 +220,40 @@ export async function exportDeck(opts, fields = {}) {
   return (await client(opts)).action(api.exports.create, args);
 }
 
-// What export_deck { kind: "mp4" } answers (the same words as convex/exports.ts videoFromCli).
+const VIDEO_OPTIONS = ["size", "shape", "captions", "avatar", "titleCard", "endCard"];
+export async function requestVideoExport(opts, fields = {}) {
+  const slug = String(fields.slug);
+  for (const k of ["notes", "script", "shareToken"]) if (fields[k]) throw new Error(`${k} is a PDF option; a video has none`);
+  const options = {};
+  for (const k of VIDEO_OPTIONS) if (fields[k] !== undefined) options[k] = fields[k];
+  const c = await client(opts);
+  try {
+    const out = await c.mutation(api.videoExports.requestVideo, { slug, options });
+    return { ...out, next: `poll check_export { exportId: "${out.exportId}" } (or \`hyperdecks export status ${out.exportId}\`) every 20-30 s; a deck renders in about its own length` };
+  } catch (e) {
+    // A backend from before the render worker has no requestVideo.
+    if (/Could not find public function/i.test(errorText(e))) throw new Error(videoFromCli(slug));
+    throw e;
+  }
+}
+
+// One export by id (check_export / `export status`): status, a rendering
+// video's progress { slide, slides, phase }, its place in line, and the
+// download URL once ready.
+export async function checkExport(opts, exportId) {
+  if (!exportId) throw new Error("exportId is required");
+  return (await client(opts)).query(api.exports.get, { exportId: String(exportId) });
+}
+
+export async function cancelExport(opts, exportId) {
+  if (!exportId) throw new Error("exportId is required");
+  return (await client(opts)).mutation(api.videoExports.cancel, { exportId: String(exportId) });
+}
+
+// What a video request answers where no render worker is set up (the same words as convex/exports.ts videoFromCli).
 export const videoFromCli = (slug) =>
-  `video exports run from the CLI until the render worker ships: \`hyperdecks export ${slug} --video --out ${slug}.mp4\` ` +
-  "records the narrated deck in real time (add --upload to keep the MP4 with the deck's exports, --shape 9:16 or 1:1, --size 720p or 4k).";
+  `video exports from the dashboard and chat are not set up on this server yet; record it with the CLI: \`hyperdecks export ${slug} --video --out ${slug}.mp4\` ` +
+  "records the narrated deck frame by frame, slower than real time (add --upload to keep the MP4 with the deck's exports, --shape 9:16 or 1:1, --size 720p or 4k).";
 
 // The released copy of a deck you own, for `export --video <slug>`: { slug, title, html }.
 // Owner only, as export_deck is: a video is the owner's to make.

package/src/preview-capture.mjs

@@ -12,12 +12,35 @@ const run = promisify(execFile);
 const require = createRequire(import.meta.url);
 const MIME = { '.html':'text/html', '.htm':'text/html', '.js':'text/javascript', '.mjs':'text/javascript', '.css':'text/css', '.json':'application/json', '.png':'image/png', '.jpg':'image/jpeg', '.jpeg':'image/jpeg', '.gif':'image/gif', '.webp':'image/webp', '.svg':'image/svg+xml', '.woff':'font/woff', '.woff2':'font/woff2', '.ttf':'font/ttf', '.otf':'font/otf', '.mp4':'video/mp4', '.webm':'video/webm', '.mp3':'audio/mpeg', '.wav':'audio/wav', '.wasm':'application/wasm', '.glb':'model/gltf-binary', '.gltf':'model/gltf+json', '.bin':'application/octet-stream' };
 const SETUP = 'Run `hyperdecks preview setup` (or `decks preview setup`) to install the matching isolated Chromium. On Linux install system libraries with `npx playwright install-deps chromium` using the Playwright version in your installed CLI.';
+// Installs the Chromium this CLI's Playwright launches, into Playwright's shared
+// cache. PLAYWRIGHT_SKIP_BROWSER_GC keeps the installer from pruning builds that
+// other Playwright installs (a repo's own test runner) still use.
+export async function installChromium({ exec = run } = {}) {
+  await exec(process.execPath, [join(dirname(require.resolve('playwright/package.json')), 'cli.js'), 'install', 'chromium'], {
+    timeout: 240000, maxBuffer: 4 * 1024 * 1024, env: { ...process.env, PLAYWRIGHT_SKIP_BROWSER_GC: '1' },
+  });
+}
+// Playwright's launch error when the browser build is not on disk.
+export const isMissingBrowser = (e) => /Executable doesn't exist/.test(String(e?.message ?? e));
 export async function setupCapture(pos, opts) {
   if (pos.length || Object.keys(opts).some(k => !['json', 'dev', 'convex', 'prod'].includes(k))) throw new Error('usage: preview setup');
-  await run(process.execPath, [join(dirname(require.resolve('playwright/package.json')), 'cli.js'), 'install', 'chromium'], { timeout: 240000, maxBuffer: 4 * 1024 * 1024 });
+  await installChromium();
   console.log(opts.json ? JSON.stringify({ installed: 'chromium' }) : 'Chromium installed. Preview capture is ready.');
 }
 
+// One `bytes=a-b`, `bytes=a-` or `bytes=-n` range of a `size`-byte file:
+// { start, end } (inclusive), undefined when there is no (usable) Range header
+// (send it whole), null when it asks past the end (416).
+export function byteRange(header, size) {
+  const m = /^bytes=(\d*)-(\d*)$/.exec(String(header ?? '').trim());
+  if (!m || (m[1] === '' && m[2] === '')) return undefined;
+  let start, end;
+  if (m[1] === '') { start = Math.max(0, size - Number(m[2])); end = size - 1; }
+  else { start = Number(m[1]); end = m[2] === '' ? size - 1 : Math.min(Number(m[2]), size - 1); }
+  if (start >= size || start > end) return null;
+  return { start, end };
+}
+
 // Capability URL + realpath containment; captured code gets no general file server.
 // `html` alone serves that page; with `file` it replaces the page and the file's
 // folder still serves the rest (play's in-memory copy with the face on it).
@@ -34,8 +57,14 @@ export async function serveSource({ file, html, port = 0 }) {
       if (!root || rel.split('/').some(s => s.startsWith('.') || s.includes('\\')) || !MIME[extname(rel).toLowerCase()]) { res.writeHead(404).end(); return; }
       const full = await realpath(resolve(root, rel));
       if (!full.startsWith(root + sep) || !(await stat(full)).isFile()) { res.writeHead(404).end(); return; }
-      res.writeHead(200, { 'Content-Type': MIME[extname(full).toLowerCase()] + (MIME[extname(full).toLowerCase()].startsWith('text/') ? '; charset=utf-8' : ''), 'Cache-Control':'no-store' });
-      res.end(await readFile(full));
+      const type = MIME[extname(full).toLowerCase()] + (MIME[extname(full).toLowerCase()].startsWith('text/') ? '; charset=utf-8' : '');
+      const body = await readFile(full);
+      // A byte range, as any host answers one: a <video> can only seek with it (a frame-by-frame export seeks every frame).
+      const range = byteRange(req.headers.range, body.length);
+      if (range === null) { res.writeHead(416, { 'Content-Range': `bytes */${body.length}` }).end(); return; }
+      if (range) { res.writeHead(206, { 'Content-Type': type, 'Cache-Control':'no-store', 'Accept-Ranges':'bytes', 'Content-Range': `bytes ${range.start}-${range.end}/${body.length}` }).end(body.subarray(range.start, range.end + 1)); return; }
+      res.writeHead(200, { 'Content-Type': type, 'Cache-Control':'no-store', 'Accept-Ranges':'bytes' });
+      res.end(body);
     } catch { res.writeHead(404).end(); }
   });
   await new Promise((ok, fail) => { server.once('error', fail); server.listen(port, '127.0.0.1', ok); });
@@ -50,7 +79,9 @@ export function allowCaptureRequest(url, method, type, entryUrl, firstPartyOrigi
   if (type === 'document') return url === entryUrl;
   if (['websocket', 'eventsource', 'ping', 'other'].includes(type)) return false;
   if (firstPartyOrigins.some(v => new URL(v).origin === u.origin) || /\.convex\.(cloud|site)$/.test(u.hostname)) {
-    return /^\/api\/storage\//.test(path);
+    // Stored assets, and the hosted player a player/v1 deck loads (player.js, its
+    // modules, css, emote bursts). Views (/v/) and telemetry stay refused above.
+    return /^\/(api\/storage|player)\//.test(path);
   }
   // Prevent page code from reaching local services or cloud metadata. Only the
   // capability file server is available on loopback; redirects are checked too.

package/src/runtime.mjs

@@ -8,7 +8,7 @@ import { fileURLToPath } from "node:url";
 import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
 
-export const VERSION = "0.9.3";
+export const VERSION = "0.9.4";
 const UPLOAD_TIMEOUT_MS = 125_000;
 
 export const PROD = {
@@ -135,6 +135,11 @@ export const api = {
     startVideoUpload: makeFunctionReference("exports:startVideoUpload"),
     finishVideoUpload: makeFunctionReference("exports:finishVideoUpload"),
     failVideoUpload: makeFunctionReference("exports:failVideoUpload"),
+    get: makeFunctionReference("exports:get"),
+  },
+  videoExports: {
+    requestVideo: makeFunctionReference("videoExports:requestVideo"),
+    cancel: makeFunctionReference("videoExports:cancel"),
   },
   review: {
     reviewDeck: makeFunctionReference("review:reviewDeck"),