@hypersocial/decks-cli 0.9.2 → 0.9.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypersocial/decks-cli",
-  "version": "0.9.2",
+  "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,6 +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" }` 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,6 +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): `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

@@ -10,6 +10,7 @@ import {
   VERSION,
 } from "./runtime.mjs";
 import * as ops from "./ops.mjs";
+import { exportVideo } from "./export-video.mjs";
 import { presenterLine } from "./presenter.mjs";
 
 export const playbackLabel = (p) => p.narrationFinished ? "narration finished"
@@ -413,7 +414,17 @@ commands:
   export <slug|deck-dir> --pdf [--notes] [--out <file.pdf>] [--share <token>] [--json]
                    a PDF of the released deck: one 1600x900 page per slide (a script page after each
                    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, 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
@@ -679,12 +690,18 @@ export function exportTarget(arg, opts = {}, cwd = process.cwd()) {
   return { slug: opts.slug || basename(dir), script: existsSync(scriptPath) ? readFileSync(scriptPath, "utf8") : undefined };
 }
 
+export const EXPORT_USAGE = "usage: export <slug|deck-dir> --pdf [--notes] [--out <file.pdf>] [--share <token>]\n" +
+  "       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>]";
+
 async function exportCmd(pos, opts) {
   const [arg] = pos;
-  const usage = "usage: export <slug|deck-dir> --pdf [--notes] [--out <file.pdf>] [--share <token>]";
+  const usage = EXPORT_USAGE;
   if (!arg) throw new Error(usage);
-  if (opts.mp4 || opts.gif) throw new Error("only --pdf exports are available so far (video comes later; the email GIF is `hyperdecks preview create`)");
-  if (!opts.pdf) throw new Error(`${usage}\n(--pdf is the only format so far)`);
+  if (opts.gif) throw new Error("the email GIF is `hyperdecks preview create`");
+  const video = opts.video || opts.mp4;
+  if (video && opts.pdf) throw new Error("pick one of --pdf and --video");
+  if (video) return void (await exportVideo(arg, opts));
+  if (!opts.pdf) throw new Error(`${usage}\n(pick --pdf or --video)`);
   const { slug, script } = exportTarget(arg, opts);
   if (slug !== arg) process.stderr.write(`deck folder ${arg} → slug ${slug} (pass --slug to change it)\n`);
   process.stderr.write(`rendering ${slug} as a PDF${opts.notes ? " with notes" : ""}…\n`);
@@ -698,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));
@@ -979,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

@@ -0,0 +1,551 @@
+// hyperdecks export <slug|deck-dir> --video: a narrated deck as an MP4.
+//
+// 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.
+import { copyFile, mkdtemp, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+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, installChromium, isMissingBrowser, routeCaptureRequest } from './preview-capture.mjs';
+import { installFrameClock } from './frame-clock.mjs';
+
+const run = promisify(execFile);
+
+export const VIDEO_FPS = 30;
+export const VIDEO_SIZES = Object.freeze({ '720p': 720, '1080p': 1080, '4k': 2160 });
+export const VIDEO_SHAPES = Object.freeze(['16:9', '9:16', '1:1']);
+export const TITLE_CARD_SECONDS = 2;
+export const END_CARD_SECONDS = 3;
+// 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
+// device scale 2, so a slide is laid out the same and drawn sharper. 9:16 and
+// 1:1 are viewports of that shape; the player's overlay layout letterboxes the
+// 16:9 stage on the deck's page colour.
+export function videoGeometry(size = '1080p', shape = '16:9') {
+  const short = VIDEO_SIZES[size];
+  if (!short) throw new Error(`--size must be one of ${Object.keys(VIDEO_SIZES).join(', ')} (got ${size})`);
+  if (!VIDEO_SHAPES.includes(shape)) throw new Error(`--shape must be one of ${VIDEO_SHAPES.join(', ')} (got ${shape})`);
+  const long = Math.round((short * 16) / 9);
+  const [width, height] = shape === '16:9' ? [long, short] : shape === '9:16' ? [short, long] : [short, short];
+  const scale = size === '4k' ? 2 : 1;
+  return { size, shape, width, height, scale, viewport: { width: width / scale, height: height / scale } };
+}
+
+// The command's options, checked before anything launches.
+export function videoOptions(opts = {}) {
+  for (const k of ['size', 'shape', 'out', 'link', 'slug']) if (k in opts && typeof opts[k] !== 'string') throw new Error(`--${k} requires a value`);
+  const geometry = videoGeometry(opts.size ?? '1080p', opts.shape ?? '16:9');
+  if (opts.out && extname(opts.out).toLowerCase() !== '.mp4') throw new Error(`--out must name an .mp4 file (got ${opts.out})`);
+  if (opts.link !== undefined) {
+    let u;
+    try { u = new URL(opts.link); } catch { throw new Error(`--link must be a URL (got ${opts.link})`); }
+    if (!['http:', 'https:'].includes(u.protocol)) throw new Error('--link must be an http(s) URL');
+  }
+  if (opts.notes || opts.share) throw new Error('--notes and --share are PDF options; a video has neither');
+  return {
+    geometry,
+    captions: !opts['no-captions'],
+    avatar: !opts['no-avatar'],
+    titleCard: !!opts['title-card'],
+    endCard: !!opts['end-card'],
+    link: opts.link ?? null,
+    out: opts.out ?? null,
+    upload: !!opts.upload,
+  };
+}
+
+// The page the recorder opens: the deck in export mode.
+export function exportPageUrl(url, { captions = true, avatar = true } = {}) {
+  const u = new URL(url);
+  u.searchParams.set('export', '1');
+  if (!captions) u.searchParams.set('captions', '0');
+  if (!avatar) u.searchParams.set('avatar', '0');
+  return u.href;
+}
+
+// The player's own timeline (navigation.js deckTimeline): each slide runs its
+// clip then its hold, back to back. `plan` is what the player logged at ready:
+// [{ id, duration, hold }] in slide order.
+export function planTimeline(plan) {
+  const seconds = plan.map((s) => Math.max(0, (Number(s.duration) || 0) + (Number(s.hold) || 0)));
+  const starts = seconds.map((_, i) => seconds.slice(0, i).reduce((a, b) => a + b, 0));
+  return { ids: plan.map((s) => s.id), seconds, starts, total: seconds.reduce((a, b) => a + b, 0) };
+}
+
+// Each clip's audio and where it goes in the video, in seconds: when the
+// player started it, measured from the first recorded frame (`markMs`), after
+// a title card of `lead` seconds. A clip the player never started (the tour
+// stopped early) is left out; the caller warns.
+export function audioTimeline(log, markMs, lead = 0) {
+  const audioOf = new Map((log.plan ?? []).map((s) => [s.id, s.audio]));
+  return (log.clips ?? [])
+    .map((c) => ({ id: c.id, audio: c.audio ?? audioOf.get(c.id) ?? null, offset: lead + Math.max(0, (c.at - markMs) / 1000) }))
+    .filter((c) => c.audio);
+}
+
+// How far each clip started from where the manifest's timeline puts it, for a
+// warning: a slow clip load pushes everything after it later (the audio still
+// follows the player, so the video stays in sync).
+export function timelineDrift(log, markMs) {
+  const plan = planTimeline(log.plan ?? []);
+  const startOf = new Map(plan.ids.map((id, i) => [id, plan.starts[i]]));
+  return (log.clips ?? []).filter((c) => startOf.has(c.id)).map((c) => ({ id: c.id, drift: (c.at - markMs) / 1000 - startOf.get(c.id) }));
+}
+
+// ffmpeg args for the audio track, `seconds` long: silence up to the first
+// clip, then each clip padded with silence (or cut) to where the next one
+// starts, joined end to end. Clips never overlap (the player plays one at a
+// time), so nothing is mixed or normalised, and it needs no clip durations.
+// Only filters FFmpeg 4.1 has (the CLI's bundled build on Linux, Windows and
+// Intel Macs): aevalsrc, aresample, aformat, apad, atrim, asetpts, concat.
+export function audioMixArgs({ inputs, seconds, out }) {
+  const fmt = 'aresample=48000,aformat=sample_fmts=s16:channel_layouts=stereo';
+  const clips = [...inputs].filter((i) => i.offset < seconds).sort((a, b) => a.offset - b.offset);
+  const args = [];
+  for (const c of clips) args.push('-i', c.path);
+  const parts = [], labels = [];
+  const lead = clips.length ? clips[0].offset : seconds;
+  if (lead >= 0.001) {
+    parts.push(`aevalsrc=0|0:c=stereo:s=48000:d=${lead.toFixed(3)},${fmt}[lead]`);
+    labels.push('[lead]');
+  }
+  clips.forEach((c, n) => {
+    const end = n + 1 < clips.length ? clips[n + 1].offset : seconds;
+    parts.push(`[${n}:a]${fmt},apad,atrim=0:${Math.max(0.001, end - c.offset).toFixed(3)},asetpts=N/SR/TB[c${n}]`);
+    labels.push(`[c${n}]`);
+  });
+  parts.push(`${labels.join('')}concat=n=${labels.length}:v=0:a=1[mix]`);
+  return [...args, '-filter_complex', parts.join(';'), '-map', '[mix]', '-c:a', 'pcm_s16le', '-y', out];
+}
+
+// ffmpeg args for the MP4: the numbered frames at `fps` and the mixed audio.
+export function encodeArgs({ frames, fps = VIDEO_FPS, audio, width, height, out }) {
+  return [
+    '-framerate', String(fps), '-i', frames,
+    '-i', audio,
+    '-map', '0:v', '-map', '1:a',
+    '-vf', `scale=${width}:${height}:flags=lanczos,format=yuv420p`,
+    '-c:v', 'libx264', '-preset', 'fast', '-crf', '20', '-r', String(fps),
+    '-c:a', 'aac', '-b:a', '192k',
+    '-shortest', '-movflags', '+faststart', '-y', out,
+  ];
+}
+
+// A computed style value inside <style>: entities are not decoded there, so it
+// is not HTML-escaped; anything that could end the rule or the element goes.
+const cssValue = (s) => String(s ?? '').replace(/[<>{};\\]/g, '');
+const escapeHtml = (s) => String(s ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+
+// A title or end card: the first slide's colour, ink and heading font, centred
+// text. `fonts` carries the deck's web fonts: its font stylesheet links and the
+// @font-face rules it could read, resolved against `base` (the deck's page).
+export function cardHtml({ lines, background = '#0b0b0f', color = '#ffffff', font = 'system-ui, sans-serif', width, height, fonts = { links: [], faces: '' }, base = null }) {
+  const [first, ...rest] = lines.filter(Boolean);
+  const unit = Math.min(width, height) / 1080;
+  const links = (fonts.links ?? []).filter((h) => /^https:\/\//.test(h)).map((h) => `<link rel="stylesheet" href="${escapeHtml(h)}">`).join('');
+  const faces = String(fonts.faces ?? '').replace(/<\/style/gi, '');
+  return `<!doctype html><html><head><meta charset="utf-8">${base ? `<base href="${escapeHtml(base)}">` : ''}${links}<style>${faces}
+html,body{margin:0;height:100%;background:${cssValue(background)};color:${cssValue(color)};font-family:${cssValue(font)}}
+body{display:flex;flex-direction:column;align-items:center;justify-content:center;gap:${Math.round(28 * unit)}px;text-align:center;padding:0 8%;box-sizing:border-box}
+h1{font-size:${Math.round(84 * unit)}px;line-height:1.1;margin:0;font-weight:700;max-width:100%;overflow-wrap:anywhere}
+p{font-size:${Math.round(40 * unit)}px;margin:0;opacity:.8;max-width:100%;overflow-wrap:anywhere}
+</style></head><body><h1>${escapeHtml(first ?? '')}</h1>${rest.map((l) => `<p>${escapeHtml(l)}</p>`).join('')}</body></html>`;
+}
+
+const pad = (n) => String(n).padStart(6, '0');
+const frameName = (n) => `frame-${pad(n)}.jpg`;
+const clock = (s) => `${Math.floor(s / 60)}:${String(Math.floor(s % 60)).padStart(2, '0')}`;
+
+async function ffmpegPath() {
+  try {
+    const path = (await import('@ffmpeg-installer/ffmpeg')).default.path;
+    await run(path, ['-version'], { timeout: 10000 });
+    return path;
+  } catch {
+    throw new Error('Portable FFmpeg missing. Reinstall the CLI with optional dependencies and install scripts enabled (`npm install -g hyperdecks --include=optional`); pnpm users must approve @ffmpeg-installer platform build scripts.');
+  }
+}
+
+async function ffmpeg(path, args, timeoutMs) {
+  try {
+    await run(path, ['-hide_banner', '-loglevel', 'error', '-nostdin', ...args], { timeout: Math.round(timeoutMs), maxBuffer: 4 * 1024 * 1024, env: { PATH: dirname(path), ...(process.platform === 'win32' ? { SystemRoot: process.env.SystemRoot } : {}) } });
+  } catch (e) {
+    throw new Error(`FFmpeg failed${e.killed ? ` (timed out after ${Math.round(timeoutMs / 1000)}s)` : ''}: ${String(e.stderr || e.message).trim().split('\n').slice(-3).join(' ')}`);
+  }
+}
+
+// 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(() => {});
+  let timer;
+  try { return await Promise.race([promise, new Promise((ok) => { timer = setTimeout(() => ok(fallback), ms); })]); }
+  finally { clearTimeout(timer); }
+}
+
+// The player's export log, read without trusting the page to answer quickly.
+// 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;
+}), 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, install } = {}) {
+  const { geometry, out } = config;
+  const ff = await ffmpegPath();
+  const chromium = injected ?? (await import('playwright')).chromium;
+  const warnings = [];
+  let browser, temp, phase = 'launch';
+  try {
+    temp = await mkdtemp(join(tmpdir(), 'hyperdecks-video-'));
+    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 });
+    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) => {
+        const name = new URL(route.request().url()).pathname.replace(/^.*\/player\/v1\//, '');
+        if (name.split('/').some((s) => s === '..' || s.startsWith('.'))) return route.abort();
+        const type = { '.js': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.png': 'image/png' }[extname(name)] ?? 'application/octet-stream';
+        try { await route.fulfill({ body: await readFile(join(config.playerDir, name)), contentType: type }); }
+        catch { await route.abort(); }
+      });
+    }
+    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;
+      // The player's export mode waits for this before it plays (export-mode.js).
+      window.__hdExportWait = new Promise((go) => { window.__hdExportGo = go; });
+    });
+    const page = await context.newPage();
+    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()}${readySaw({ blocked: blockedUrls, failed })}; is it on player/v1 (https://decks.hypersocial.ai/player/v1/player.js)?`);
+    });
+    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');
+      const cs = (n) => n && getComputedStyle(n);
+      const solid = (c) => c && c !== 'rgba(0, 0, 0, 0)' && c !== 'transparent';
+      const slide = cs(first), body = cs(document.body), heading = cs(first?.querySelector('h1, h2, h3'));
+      const background = [slide?.backgroundColor, body?.backgroundColor].find(solid);
+      // Font stylesheets on another origin can't be read: link them; read the rest's @font-face rules.
+      const links = [...document.querySelectorAll('link[rel~="stylesheet"]')].map((l) => l.href).filter((h) => /^https:\/\/fonts\.(googleapis|bunny)\.net\//.test(h) || /^https:\/\/use\.typekit\.net\//.test(h));
+      const faces = [];
+      for (const sheet of document.styleSheets) {
+        try { for (const rule of sheet.cssRules) if (rule instanceof CSSFontFaceRule) faces.push(rule.cssText); } catch { /* cross-origin */ }
+      }
+      return { background: background ?? '#0b0b0f', color: heading?.color ?? slide?.color ?? '#ffffff', font: heading?.fontFamily ?? slide?.fontFamily ?? 'system-ui, sans-serif', fonts: { links, faces: faces.join('\n') } };
+    }), 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(), 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}`);
+      let res;
+      try { res = await fetch(url, { redirect: 'error', signal: AbortSignal.timeout(30000) }); }
+      catch (e) { throw new Error(`could not download clip ${id}'s audio (${url}): ${e.cause?.message ?? e.message}`); }
+      if (!res.ok) throw new Error(`could not download clip ${id}'s audio (${res.status} from ${url})`);
+      const bytes = Buffer.from(await res.arrayBuffer());
+      if (bytes.length > MAX_CLIP_BYTES) throw new Error(`clip ${id}'s audio is over ${MAX_CLIP_BYTES / 1024 / 1024} MB`);
+      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)} 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;
+    const card = async (lines) => {
+      const p = await context.newPage();
+      await p.setContent(cardHtml({ lines, ...look, base: pageUrl, width: geometry.viewport.width, height: geometry.viewport.height }), { waitUntil: 'load', timeout: 15000 }).catch((e) => warnings.push(`a card's fonts did not finish loading (${e.message.split('\n')[0]}); it may show a fallback font`));
+      await within(p.evaluate(() => document.fonts.ready.then(() => true)), 5000, false);
+      const shot = await p.screenshot({ type: 'jpeg', quality: 92 });
+      await p.close();
+      return shot;
+    };
+    let frameCount = 0;
+    const repeat = async (image, seconds) => {
+      const first = join(temp, frameName(frameCount));
+      await writeFile(first, image);
+      const n = Math.round(seconds * VIDEO_FPS);
+      for (let i = 1; i < n; i++) await copyFile(first, join(temp, frameName(frameCount + i)));
+      frameCount += n;
+    };
+    if (config.titleCard) {
+      phase = 'title card';
+      await repeat(await card([config.title, config.presenter ? `Presented by ${config.presenter}` : null]), TITLE_CARD_SECONDS);
+    }
+
+    phase = 'recording';
+    const session = await context.newCDPSession(page);
+    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 = 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));
+      }
+      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()}`);
+    }
+    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';
+      await repeat(await card([config.title, config.link]), END_CARD_SECONDS);
+    }
+    phase = 'browser close';
+    await context.close();
+    await browser.close();
+    browser = null;
+    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);
+    const missing = plan.ids.filter((id) => !clips.some((c) => c.id === id) && (state.plan.find((s) => s.id === id)?.audio));
+    if (missing.length) warnings.push(`no audio started for ${missing.join(', ')}`);
+    const inputs = clips.map((c) => {
+      const path = audioFiles.get(c.audio);
+      if (!path) throw new Error(`clip ${c.id} played audio the plan did not list (${c.audio})`);
+      return { path, offset: c.offset };
+    });
+    const total = frameCount / VIDEO_FPS;
+    const audio = join(temp, 'audio.wav');
+    await ffmpeg(ff, audioMixArgs({ inputs, seconds: total, out: audio }), 300000);
+
+    phase = 'encode';
+    log(`encoding ${clock(total)} of video…`);
+    // Encoded beside the temp frames, then moved into place: a failed encode never leaves a broken file at `out`.
+    const encoded = join(temp, 'video.mp4');
+    await ffmpeg(ff, encodeArgs({ frames: join(temp, 'frame-%06d.jpg'), audio, width: geometry.width, height: geometry.height, out: encoded }), Math.round(Math.max(300000, total * 20000) * geometry.scale));
+    await rename(encoded, out).catch(async (e) => {
+      if (e.code !== 'EXDEV') throw e;
+      await copyFile(encoded, out);
+    });
+    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, render, warnings };
+  } catch (e) {
+    throw new Error(`Video export failed during ${phase}: ${e.message}`);
+  } finally {
+    if (browser) await browser.close().catch(() => {});
+    if (temp) await rm(temp, { recursive: true, force: true });
+  }
+}
+
+// ---- the command ------------------------------------------------------------
+
+const titleOf = (html) => (/<title[^>]*>([^<]*)<\/title>/i.exec(html)?.[1] ?? '').replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'").trim();
+const mb = (n) => `${(n / 1e6).toFixed(1)} MB`;
+
+// hyperdecks export <slug|deck-dir> --video: a deck folder records its working
+// copy as `hyperdecks play` serves it (the owner's face added in memory, the
+// manifest index.html points at); a slug records the released copy. Progress
+// goes to stderr, the result to stdout.
+export async function exportVideo(arg, opts = {}, { log = (l) => process.stderr.write(`${l}\n`), print = (l) => console.log(l), cwd = process.cwd(), deps = {} } = {}) {
+  const o = videoOptions(opts);
+  const { existsSync, readFileSync } = await import('node:fs');
+  const { resolve, join: joinPath, basename } = await import('node:path');
+  const ops = deps.ops ?? await import('./ops.mjs');
+  const local = [resolve(cwd, arg), joinPath(cwd, 'decks', arg)].find((d) => existsSync(joinPath(d, 'index.html')));
+  // --upload files the MP4 under a deck you own: checked before minutes of recording.
+  if (o.upload) await ops.ownedDeck(opts, local ? (opts.slug || basename(local)) : arg);
+  let source;
+  if (local) {
+    const { startPlay } = deps.play ?? await import('./play.mjs');
+    const html = readFileSync(joinPath(local, 'index.html'), 'utf8');
+    const session = await startPlay([local], { ...opts, 'no-open': true }, { log: (l) => { if (!l.startsWith('▶')) log(l); }, cwd });
+    source = { slug: session.slug, title: titleOf(html) || session.slug, url: session.url, close: session.close, presenter: session.who?.face ?? null };
+  } else {
+    const deck = await ops.releasedDeck(opts, arg);
+    const { serveSource } = await import('./preview-capture.mjs');
+    const server = await serveSource({ html: deck.html });
+    source = { slug: arg, title: deck.title, url: server.url, close: server.close, presenter: null };
+  }
+  try {
+    let link = o.link;
+    if (o.endCard && !link) {
+      try { link = await ops.videoShareLink(opts, source.slug); }
+      catch (e) { throw new Error(`the end card needs the deck's link: ${ops.errorText?.(e) ?? e.message}. Pass --link <url> to name one`); }
+    }
+    const out = resolve(cwd, o.out ?? `${source.slug}.mp4`);
+    log(`recording ${source.slug}${local ? ' (working copy)' : ' (released copy)'} → ${out}`);
+    const result = await recordVideo({
+      url: source.url, geometry: o.geometry, captions: o.captions, avatar: o.avatar, titleCard: o.titleCard, endCard: o.endCard,
+      title: source.title, presenter: source.presenter, link, out, playerDir: process.env.HYPERDECKS_PLAYER_DIR || null,
+    }, { log });
+    let uploaded = null;
+    if (o.upload) {
+      log(`uploading ${mb(result.bytes)}…`);
+      try {
+        uploaded = await ops.uploadVideoExport(opts, { slug: source.slug, bytes: await readFile(out), seconds: result.seconds, width: result.width, height: result.height });
+      } catch (e) {
+        throw new Error(`${ops.errorText?.(e) ?? e.message}. The MP4 is saved at ${out}: share the file itself, or fix that and re-run with --upload (it records again)`);
+      }
+    }
+    const summary = { ...result, slug: source.slug, link: link ?? null, ...(uploaded ? { exportId: uploaded.exportId, url: uploaded.url, expiresAt: uploaded.expiresAt } : {}) };
+    if (opts.json) { print(JSON.stringify(summary, null, 2)); return summary; }
+    print(`✓ ${clock(result.seconds)} at ${result.width}×${result.height}, ${mb(result.bytes)} → ${out}`);
+    if (link && o.endCard) print(`  end card link: ${link}`);
+    for (const w of result.warnings) print(`  ⚠ ${w}`);
+    if (uploaded) print(`  on the deck page, and download (30 days): ${uploaded.url}`);
+    return summary;
+  } finally {
+    await source.close();
+  }
+}

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,10 +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 !== "pdf") throw new Error(`kind "${kind}" is not supported yet: only "pdf" (video export comes from \`hyperdecks export --mp4\` later)`);
+  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);
@@ -217,6 +220,101 @@ export async function exportDeck(opts, fields = {}) {
   return (await client(opts)).action(api.exports.create, args);
 }
 
+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 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.
+export async function ownedDeck(opts, slug) {
+  const c = await client(opts);
+  const [deck, me] = await Promise.all([c.query(api.decks.get, { slug }), c.query(api.decks.whoami, {})]);
+  if (!me) throw new Error("not logged in: run `hyperdecks login` first");
+  if (!deck) throw new Error(`deck not found: ${slug} (register it first, or pass --slug)`);
+  if (!me.isAdmin && deck.ownerId !== me.subject) throw new Error(`forbidden: ${slug} is not your deck`);
+  return deck;
+}
+export async function releasedDeck(opts, slug) {
+  const deck = await ownedDeck(opts, slug);
+  if (deck.status === "archived") throw new Error(`${slug} is archived; restore it before exporting`);
+  let html = deck.html ?? null;
+  if (!html && deck.htmlUrl) {
+    const res = await fetch(deck.htmlUrl, { signal: AbortSignal.timeout(30000) });
+    if (!res.ok) throw new Error(`could not read ${slug}'s released HTML (${res.status})`);
+    html = await res.text();
+  }
+  if (!html) throw new Error(`${slug} has no released HTML yet; release it first`);
+  return { slug, title: deck.title ?? slug, html };
+}
+
+// The link a video's end card shows: the deck's own "Video viewers" link, made
+// on first use, so a viewer who types it in counts as a view of that link and
+// never as a recipient's (their views and view limit).
+export const VIDEO_RECIPIENT = "Video viewers";
+export async function videoShareLink(opts, slug) {
+  const live = (await listShares(opts, slug)).find((s) => s.recipient === VIDEO_RECIPIENT && s.enabled && !s.qa && !s.archived && !s.requireEmail && (s.expiresAt == null || s.expiresAt > Date.now()) && (s.viewLimit == null || s.opens < s.viewLimit));
+  const token = live?.token ?? (await createShare(opts, { slug, recipient: VIDEO_RECIPIENT })).token;
+  return `${target(opts).shareBase}/v/${token}`;
+}
+
+// `export --video --upload`: file the MP4 with the deck's exports (30 days).
+// Returns { exportId, url, expiresAt }.
+export async function uploadVideoExport(opts, { slug, bytes, seconds, width, height }, { fetchImpl = fetch, timeoutMs = 30 * 60_000 } = {}) {
+  const c = await client(opts);
+  const { exportId, uploadUrl } = await c.mutation(api.exports.startVideoUpload, { slug, bytes: bytes.length, seconds, width, height });
+  try {
+    let res;
+    try {
+      res = await fetchImpl(uploadUrl, { method: "POST", headers: { "Content-Type": "video/mp4" }, body: bytes, signal: AbortSignal.timeout(timeoutMs) });
+    } catch (e) {
+      throw new Error(`upload failed: ${e?.name === "TimeoutError" ? `no answer in ${Math.round(timeoutMs / 60000)} min` : e?.message || String(e)}`);
+    }
+    if (!res.ok) throw new Error(`upload failed: ${res.status} ${await res.text()}`);
+    const body = await res.text();
+    let storageId;
+    try { ({ storageId } = JSON.parse(body)); } catch { /* checked below */ }
+    if (!storageId) throw new Error(`upload failed: the storage answered without a file id (${body.slice(0, 200)})`);
+    const done = await c.mutation(api.exports.finishVideoUpload, { exportId, storageId });
+    if (!done.ok) throw new Error(`upload refused: ${done.error}`);
+    return { exportId, url: done.url, expiresAt: done.expiresAt };
+  } catch (e) {
+    // The row says so at once, rather than "uploading…" until the sweep.
+    await c.mutation(api.exports.failVideoUpload, { exportId, error: errorText(e) }).catch((err) => console.error(`[export] could not mark export ${exportId} failed: ${errorText(err)}`));
+    throw e;
+  }
+}
+
 // Your exports (newest first, 30 days), optionally for one deck.
 export async function listExports(opts, fields = {}) {
   return (await client(opts)).query(api.exports.list, fields.slug ? { slug: String(fields.slug) } : {});

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.2";
+export const VERSION = "0.9.4";
 const UPLOAD_TIMEOUT_MS = 125_000;
 
 export const PROD = {
@@ -132,6 +132,14 @@ export const api = {
     create: makeFunctionReference("exports:create"),
     list: makeFunctionReference("exports:list"),
     remove: makeFunctionReference("exports:remove"),
+    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"),
@@ -161,7 +169,7 @@ export const api = {
   },
 };
 
-const BOOL = new Set(["prod", "dev", "admin", "json", "require-email", "qa", "no-notify", "allow-forward", "no-forward", "help", "version", "all-agents", "global", "project", "transparent", "loop", "upload", "dry-run", "narrated", "layout", "strict", "fix", "full-page", "force", "hosted", "yes", "no-voice", "no-skill", "no-release", "no-open", "save-to-minimoji", "captions-only", "no-brand", "no-logo", "pdf", "notes", "mp4", "gif"]);
+const BOOL = new Set(["prod", "dev", "admin", "json", "require-email", "qa", "no-notify", "allow-forward", "no-forward", "help", "version", "all-agents", "global", "project", "transparent", "loop", "upload", "dry-run", "narrated", "layout", "strict", "fix", "full-page", "force", "hosted", "yes", "no-voice", "no-skill", "no-release", "no-open", "save-to-minimoji", "captions-only", "no-brand", "no-logo", "pdf", "notes", "mp4", "gif", "video", "no-captions", "no-avatar", "title-card", "end-card"]);
 // release's recipients, in order: each --to starts one, and an --email right
 // after it belongs to it (`--to A --email a --to B`). Collected as opts.recipients;
 // opts.email stays the last --email for the other commands (share new).