@hypersocial/decks-cli 0.1.12 → 0.2.0

package/src/commands.mjs

@@ -241,6 +241,13 @@ commands:
   logout [--dev]
   whoami [--json] [--dev]
   deck list|stats|open|rm
+  deck new <slug> "<title>" --narrated [--dir <path>]
+                   scaffold decks/<slug>/: index.html (8 slides, player/v1), script.md, evidence.md
+  check <slug|deck-dir> [--forbid "<phrase>,<phrase>"] [--max-duration <s>] [--json]
+                   the narrated-deck gate: slides vs manifest, timing, captions, clip URLs,
+                   local refs, pinned player, a data-note per slide, mobile titles
+  release <slug|deck-dir> [--to "<name>" [--email <e>]]... [--qa] [--no-notify] [--title t] [--voice v]
+                   on a committed deck: check → narrate → import → share new per --to
   share new|list|on|off|mute|unmute|rm|url
     share new <slug> <recipient> [--qa] [--no-notify]
   recipient archive|unarchive
@@ -251,12 +258,24 @@ commands:
   activity [--deck <slug>] [--limit <n>] [--json]
   gen-image "<prompt>" [--transparent] [--image <url>] [--size <s>] [--quality <q>] [--count <n>] [--slug <deck>] [--download <file>]
   image-job <jobId> [--json]
+  gen-video "<prompt>" [--image <url>] [--seconds 5] [--aspect 16:9|9:16] [--slug <deck>] [--name <name>] [--download <file>]
+                   a 3–10s clip (no audio) via fal; --image animates that still and keeps its aspect
+  video-job <jobId> [--json]
   credits [--limit <n>] [--json]   show your credit balance and recent history
 
   preview create <slug> --out <directory> [--share <token>] [--upload] [--json]
   preview create --file <index.html> --out <directory> [--duration 4] [--width 600] [--delay 1000] [--label "Watch"] [--aspect-ratio 16:9]
   preview setup    install isolated Chromium (Linux: see README for system dependencies)
 
+  narrate <deck-dir> [--slide <id>] [--voice <name|id>] [--slug <slug>] [--dry-run] [--json]
+                   script.md → voiced clips, timelines and a manifest, rendered server-side; only changed slides re-render
+  voice list [--json]   your voices and their status
+  voice clone <file...> --name <name>
+                   clone your voice from 1-3 mp3/m4a/wav recordings (30 s to 3 min in total, 10 MB each);
+                   asks you to type "I consent" before anything is uploaded
+  voice upload <file...>   upload recordings and print their sample ids (for the MCP clone_voice tool)
+  voice rm <name|id>       delete a voice, also at the provider
+
 global:
   --json
   --prod        production target (default)
@@ -326,25 +345,104 @@ async function imageJob(pos, opts) {
   for (const im of job.results || []) if (im.url) console.log(im.url);
 }
 
-export async function runCli(argv = process.argv.slice(2)) {
-  const { pos, opts } = parse(argv);
-  if (opts.version) {
-    console.log(VERSION);
-    return 0;
+async function genVideo(pos, opts) {
+  const prompt = pos.join(" ").trim() || opts.prompt;
+  if (!prompt) {
+    throw new Error('usage: gen-video "<prompt>" [--image <url>] [--seconds 5] [--aspect 16:9|9:16] [--slug <deck>] [--name <name>] [--download <file>]');
   }
-  if (opts.help || pos.length === 0) {
-    help();
-    return opts.help || pos.length === 0 ? 0 : 1;
+  const queued = await ops.generateVideo(opts, {
+    prompt,
+    image: opts.image,
+    seconds: opts.seconds,
+    aspect: opts.aspect,
+    slug: opts.slug,
+    name: opts.name,
+  });
+  // A clip takes a minute or more; poll so gen-video stays one blocking command.
+  // Progress goes to stderr so stdout stays the URL (or --json).
+  process.stderr.write(`queued a ${queued.seconds}s clip — job ${queued.jobId}\n`);
+  const job = await ops.pollVideoJob(opts, queued.jobId, {
+    onProgress: (j, ms) => process.stderr.write(`  ${j.status} ${Math.round(ms / 1000)}s…\r`),
+  });
+  process.stderr.write("\n");
+  const url = job.video?.url;
+  if (!url) throw new Error(`video job ${queued.jobId} finished without a URL; check it with: video-job ${queued.jobId}`);
+  // Print the paid clip's URL before downloading, so a failed download never hides it.
+  console.log(opts.json ? JSON.stringify(job, null, 2) : url);
+  if (job.creditsRemaining != null) process.stderr.write(`credits left: ${job.creditsRemaining}\n`);
+  if (opts.download) {
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`download of ${url} failed (${res.status})`);
+    writeFileSync(opts.download, Buffer.from(await res.arrayBuffer()));
+    process.stderr.write(`saved to ${opts.download}\n`);
   }
+}
 
-  const [group, cmd] = pos;
-  const rest = pos.slice(2);
-  const handlers = {
+async function videoJob(pos, opts) {
+  const [jobId] = pos;
+  if (!jobId) throw new Error("usage: video-job <jobId>");
+  const job = await ops.checkVideoJob(opts, jobId);
+  if (opts.json) {
+    console.log(JSON.stringify(job, null, 2));
+    return;
+  }
+  console.log(`status:   ${job.status}`);
+  if (job.error) console.log(`error:    ${job.error}`);
+  if (job.video?.url) console.log(job.video.url);
+}
+
+// The command table: "<group> <cmd>" or "<group>" → handler. Exported (via
+// COMMANDS) so the CLI/MCP parity test can enumerate it.
+function commandTable(pos, rest, opts) {
+  return {
     "preview create": async () => {
       const { createPreview } = await import("./preview.mjs");
       const result = await createPreview(rest, opts);
       console.log(opts.json ? JSON.stringify(result) : `Preview saved: ${result.manifestPath}\n${result.email.sendable ? result.email.path : "Insert the GIF or PNG manually; upload with an existing share for linked email HTML."}`);
     },
+    "deck new": async () => {
+      const { deckNew } = await import("./scaffold.mjs");
+      const out = await deckNew(rest, opts, opts.json ? { log: (line) => console.error(line) } : {});
+      if (opts.json) console.log(JSON.stringify(out, null, 2));
+    },
+    check: async () => {
+      const { check } = await import("./check.mjs");
+      const result = await check(pos.slice(1), opts);
+      if (opts.json) console.log(JSON.stringify(result, null, 2));
+      if (result.errors.length) throw new Error(`check found ${result.errors.length} issue(s)`);
+    },
+    release: async () => {
+      const { release } = await import("./release.mjs");
+      const out = await release(pos.slice(1), opts, opts.json ? { log: (line) => console.error(line) } : {});
+      if (opts.json) console.log(JSON.stringify(out, null, 2));
+    },
+    narrate: async () => {
+      const { narrate } = await import("./narrate.mjs");
+      const result = await narrate(pos.slice(1), opts, opts.json ? { log: (line) => console.error(line) } : {});
+      if (opts.json) console.log(JSON.stringify(result, null, 2));
+    },
+    "voice list": async () => {
+      const voices = await ops.listVoices(opts);
+      if (opts.json) return void console.log(JSON.stringify(voices, null, 2));
+      for (const x of voices) console.log(`${x.name}\t${x.status}\t${x.handle ?? "-"}\t${x.id}${x.error ? `\t${x.error}` : ""}`);
+      if (!voices.length) console.log("(no voices; voice clone <file...> --name <name> makes one)");
+    },
+    "voice clone": async () => {
+      const { voiceClone } = await import("./voice.mjs");
+      const voice = await voiceClone(rest, opts);
+      if (opts.json) console.log(JSON.stringify(voice, null, 2));
+    },
+    "voice upload": async () => {
+      const { voiceUpload } = await import("./voice.mjs");
+      const out = await voiceUpload(rest, opts);
+      console.log(opts.json ? JSON.stringify(out, null, 2) : out.sampleIds.join("\n"));
+    },
+    "voice rm": async () => {
+      if (!rest[0]) throw new Error("usage: voice rm <name|id>");
+      const out = await ops.deleteVoice(opts, rest.join(" "));
+      if (opts.json) return void console.log(JSON.stringify(out, null, 2));
+      console.log(`OK removed voice "${out.name}"${out.removedAtProvider ? " (deleted at the provider; decks already narrated with it keep playing)" : ""}`);
+    },
     "preview setup": async () => {
       const { setupCapture } = await import("./preview-capture.mjs");
       await setupCapture(rest, opts);
@@ -373,9 +471,33 @@ export async function runCli(argv = process.argv.slice(2)) {
     activity: () => activity(pos.slice(1), opts),
     "gen-image": () => genImage(pos.slice(1), opts),
     "image-job": () => imageJob(pos.slice(1), opts),
+    "gen-video": () => genVideo(pos.slice(1), opts),
+    "video-job": () => videoJob(pos.slice(1), opts),
     credits: () => credits(pos.slice(1), opts),
   };
+}
+
+export const COMMANDS = Object.keys(commandTable([], [], {}));
+
+export async function runCli(argv = process.argv.slice(2)) {
+  let pos, opts;
+  try {
+    ({ pos, opts } = parse(argv));
+  } catch (e) {
+    console.error("Error:", e.message);
+    return 1;
+  }
+  if (opts.version) {
+    console.log(VERSION);
+    return 0;
+  }
+  if (opts.help || pos.length === 0) {
+    help();
+    return opts.help || pos.length === 0 ? 0 : 1;
+  }
 
+  const [group, cmd] = pos;
+  const handlers = commandTable(pos, pos.slice(2), opts);
   const handler = handlers[`${group} ${cmd}`] || handlers[group];
   if (!handler) {
     help();
@@ -386,7 +508,7 @@ export async function runCli(argv = process.argv.slice(2)) {
     await handler();
     return 0;
   } catch (e) {
-    console.error("Error:", e?.message || e);
+    console.error("Error:", ops.errorText(e));
     return 1;
   }
 }

package/src/narrate.mjs

@@ -0,0 +1,95 @@
+// hyperdecks narrate <deck-dir> [--slide <id>[,<id>]] [--voice <name|id>] [--slug <slug>] [--dry-run] [--json]
+//
+// A thin client: sends decks/<slug>/script.md (and the deck's <section id>s) to
+// the backend, which compiles it, renders the changed slides with the platform
+// ElevenLabs key and writes clips, timelines and the manifest as deck assets.
+// This polls the job, saves the manifest into <deck-dir>/narration/ and points the
+// player script's data-manifest in index.html at the new manifest URL.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import * as ops from "./ops.mjs";
+
+// Same rule as sectionIds() in lib/deckScript.ts (the published CLI cannot import it).
+export const sectionIds = (html) => [...html.matchAll(/<section\b[^>]*?\sid\s*=\s*["']([^"']+)["']/gi)].map((m) => m[1]);
+
+// Set data-manifest on the hosted player's <script> tag; html is unchanged when
+// there is no player tag or it already names this URL.
+export function setManifestUrl(html, url) {
+  return html.replace(/<script\b[^>]*\/player\/v\d+\/player\.js"[^>]*>/, (tag) =>
+    /\sdata-manifest\s*=\s*"[^"]*"/.test(tag)
+      ? tag.replace(/(\sdata-manifest\s*=\s*)"[^"]*"/, (_, lead) => `${lead}"${url}"`)
+      : tag.replace(/\s*>$/, () => ` data-manifest="${url}">`));
+}
+
+function slideList(value) {
+  const ids = value.split(",").map((s) => s.trim()).filter(Boolean);
+  if (!ids.length) throw new Error("--slide needs at least one slide id");
+  return ids;
+}
+
+export function narrationRequest(pos, opts) {
+  const [dirArg] = pos;
+  if (!dirArg) throw new Error("usage: narrate <deck-dir> [--slide <id>] [--voice <name|id>] [--slug <slug>] [--dry-run]");
+  for (const k of ["slide", "voice", "slug"]) if (k in opts && typeof opts[k] !== "string") throw new Error(`--${k} requires a value`);
+  const deckDir = resolve(dirArg);
+  const scriptPath = join(deckDir, "script.md");
+  if (!existsSync(scriptPath)) throw new Error(`no script.md in ${deckDir}`);
+  const htmlPath = join(deckDir, "index.html");
+  const ids = existsSync(htmlPath) ? sectionIds(readFileSync(htmlPath, "utf8")) : [];
+  return {
+    deckDir,
+    fields: {
+      slug: opts.slug || basename(deckDir),
+      script: readFileSync(scriptPath, "utf8"),
+      voice: opts.voice,
+      slides: opts.slide !== undefined ? slideList(opts.slide) : undefined,
+      sectionIds: ids.length ? ids : undefined,
+    },
+  };
+}
+
+export async function narrate(pos, opts = {}, { log = (line) => console.log(line) } = {}) {
+  const { deckDir, fields } = narrationRequest(pos, opts);
+  if (opts["dry-run"]) {
+    const preview = await ops.previewNarration(opts, fields);
+    for (const s of preview.slides) log(`${s.render ? "render" : s.cached ? "cached" : "skip  "}  ${s.id}  ${s.hash.slice(0, 12)}  ${s.chars} chars`);
+    const render = preview.slides.filter((s) => s.render);
+    log(`${render.length} of ${preview.slides.length} slide(s) would render in voice "${preview.voice}", ~${render.reduce((n, s) => n + s.chars, 0)} characters of TTS`);
+    return preview;
+  }
+  const { jobId, slides } = await ops.narrateDeck(opts, fields);
+  log(`narration job ${jobId}: ${slides.filter((s) => s.status === "render").length} to render, ${slides.filter((s) => s.status === "cached").length} cached`);
+  const seen = new Map();
+  const job = await ops.pollNarrationJob(opts, jobId, {
+    onProgress: (j) => {
+      for (const s of j.slides) {
+        if (seen.get(s.id) === s.status) continue;
+        seen.set(s.id, s.status);
+        if (s.status === "done") log(`  ✓ ${s.id}${s.duration ? `  ${s.duration.toFixed(2)}s` : ""}`);
+        else if (s.status === "error") log(`  ✗ ${s.id}`);
+        else if (s.status === "rendering" || s.status === "skipped") log(`  … ${s.id} ${s.status}`);
+      }
+    },
+  });
+  if (job.status === "error") throw new Error(job.error || "narration failed");
+  if (!job.manifest) {
+    log(`⚠ ${job.notice || "done, but no manifest was written"}`);
+    return job;
+  }
+  const out = join(deckDir, "narration");
+  mkdirSync(out, { recursive: true });
+  writeFileSync(join(out, "manifest.json"), JSON.stringify(job.manifest, null, 2) + "\n");
+  const htmlPath = join(deckDir, "index.html");
+  if (job.manifestUrl && existsSync(htmlPath)) {
+    const html = readFileSync(htmlPath, "utf8");
+    const next = setManifestUrl(html, job.manifestUrl);
+    if (next !== html) {
+      writeFileSync(htmlPath, next);
+      log(`  index.html: data-manifest → ${job.manifestUrl}`);
+    }
+  }
+  log(`✓ ${job.manifest.clips.length} clips, ${job.manifest.spokenDuration}s spoken, ${job.manifest.totalDuration}s with holds; ${job.renderedChars} characters rendered`);
+  log(`  manifest: ${job.manifestUrl}\n  saved:    ${join(out, "manifest.json")}`);
+  for (const c of job.manifest.clips) log(`  ${c.id}\t${c.audio}`);
+  return job;
+}

package/src/ops.mjs

@@ -97,6 +97,179 @@ export async function pollImageJob(opts, jobId, { intervalMs = 3000, timeoutMs =
   }
 }
 
+// ---- video (convex/videogen.ts) ------------------------------------------
+
+// Generate a short clip via fal (Kling v3: text→video, or image→video when an image
+// URL is given as the first frame). Always a background job: returns
+// { jobId, status, seconds, aspect?, creditsRemaining? } without waiting, so the MCP
+// tool never blocks; the CLI polls with pollVideoJob.
+export async function generateVideo(opts, fields = {}) {
+  if (!fields.prompt) throw new Error("prompt is required");
+  const args = { prompt: String(fields.prompt) };
+  const img = fields.image || fields.imageUrl;
+  if (img) args.imageUrl = String(img);
+  if (fields.seconds != null && fields.seconds !== "") args.seconds = Number(fields.seconds);
+  if (fields.aspect) args.aspect = String(fields.aspect);
+  if (fields.slug) args.slug = String(fields.slug);
+  if (fields.name) args.name = String(fields.name);
+  return (await client(opts)).action(api.videogen.generateVideo, args);
+}
+
+// Read one video job's status (and the hosted MP4 once done). Shared by the MCP
+// check_video_job tool and the CLI poller.
+export async function checkVideoJob(opts, jobId) {
+  if (!jobId) throw new Error("jobId is required");
+  return (await client(opts)).query(api.videogen.checkVideoJob, { jobId: String(jobId) });
+}
+
+// Poll a video job until it finishes. Returns the job (its `video` holds the hosted
+// URL); throws on job error or timeout. The server settles every job within 15
+// minutes, so the 16-minute default only trips if the job row itself stalls. A few
+// failed checks in a row (network, Convex hiccup) are tolerated: the job keeps
+// running server-side either way, so giving up early would only lose the result.
+export async function pollVideoJob(opts, jobId, { intervalMs = 5000, timeoutMs = 960_000, maxErrors = 5, onProgress } = {}) {
+  const c = await client(opts);
+  const start = Date.now();
+  const resume = `check it later with: video-job ${jobId}`;
+  let errors = 0;
+  for (;;) {
+    let job;
+    try {
+      job = await c.query(api.videogen.checkVideoJob, { jobId: String(jobId) });
+      errors = 0;
+    } catch (e) {
+      if (++errors >= maxErrors) throw new Error(`lost track of video job ${jobId} (${e?.message || e}); ${resume}`);
+    }
+    if (job?.status === "done") return job;
+    if (job?.status === "error") throw new Error(job.error || "video job failed");
+    if (Date.now() - start > timeoutMs) throw new Error(`video job ${jobId} is still running after ${Math.round(timeoutMs / 1000)}s; ${resume}`);
+    if (onProgress) onProgress(job, Date.now() - start);
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+}
+
+// ---- narration (convex/narration.ts) -------------------------------------
+// The pipeline runs server-side with the backend's ElevenLabs key; these are the
+// thin client calls shared by the CLI `narrate` command and the MCP tools.
+function narrationArgs(fields = {}) {
+  if (!fields.slug) throw new Error("slug is required");
+  if (!fields.script) throw new Error("script is required (the deck's script.md)");
+  const args = { slug: String(fields.slug), script: String(fields.script) };
+  if (fields.voice) args.voice = String(fields.voice);
+  if (fields.slides) {
+    if (!fields.slides.length) throw new Error("slides is empty; omit it to narrate every slide");
+    args.slides = fields.slides.map(String);
+  }
+  if (fields.sectionIds?.length) args.sectionIds = fields.sectionIds.map(String);
+  return args;
+}
+
+// Dry run: compile on the server and report which slides would render. Renders nothing.
+export async function previewNarration(opts, fields) {
+  return (await client(opts)).query(api.narration.preview, narrationArgs(fields));
+}
+
+// Start a narration job; returns { jobId, slides }. Poll with checkNarrationJob.
+export async function narrateDeck(opts, fields) {
+  return (await client(opts)).mutation(api.narration.narrateDeck, narrationArgs(fields));
+}
+
+export async function checkNarrationJob(opts, jobId) {
+  if (!jobId) throw new Error("jobId is required");
+  return (await client(opts)).query(api.narration.getJob, { jobId: String(jobId) });
+}
+
+export async function listVoices(opts = {}) {
+  return (await client(opts)).query(api.voices.listVoices, {});
+}
+
+// ---- voice cloning (convex/voices.ts) ---------------------------------------
+
+// The text of a backend error: ConvexError data (production redacts the rest), else the message.
+export const errorText = (e) => (typeof e?.data === "string" ? e.data : e?.message || String(e));
+
+// Upload one recording and bind it to you as a clone sample; returns { sampleId, size }.
+export async function uploadVoiceSample(opts, { bytes, contentType }, adapter = {}) {
+  const c = await client(opts);
+  const storageId = await (adapter.uploadBytes || runtimeUploadBytes)(c, bytes, contentType);
+  return c.mutation(api.voices.addSample, { storageId });
+}
+
+// Start a clone from uploaded sample ids. consent: { method, statement, confirmedBy? }.
+// Returns { voiceId, status: "pending", cost }; poll with pollVoice.
+export async function cloneVoice(opts, { name, sampleIds, consent }) {
+  if (!name) throw new Error("name is required");
+  if (!sampleIds?.length) throw new Error("at least one sample id is required");
+  if (!consent?.statement) throw new Error("consent is required: pass the consent statement the user confirmed");
+  return (await client(opts)).mutation(api.voices.cloneVoice, { name: String(name), samples: sampleIds.map(String), consent });
+}
+
+export async function getVoice(opts, voiceId) {
+  return (await client(opts)).query(api.voices.getVoice, { voiceId: String(voiceId) });
+}
+
+// A voice by id, name or handle among yours.
+export async function findVoice(opts, ref) {
+  const want = String(ref || "").trim().toLowerCase();
+  if (!want) throw new Error("which voice? pass its name or id");
+  const voices = await listVoices(opts);
+  const hit = voices.find((x) => x.id === ref || x.name.toLowerCase() === want || x.handle?.toLowerCase() === want);
+  if (!hit) throw new Error(`no voice "${ref}" (yours: ${voices.map((x) => x.name).join(", ") || "none"})`);
+  return hit;
+}
+
+export async function renameVoice(opts, ref, name) {
+  const voice = await findVoice(opts, ref);
+  return (await client(opts)).mutation(api.voices.renameVoice, { voiceId: voice.id, name: String(name) });
+}
+
+// Deletes it at the provider too; decks already narrated with it keep playing.
+export async function deleteVoice(opts, ref) {
+  const voice = await findVoice(opts, ref);
+  const out = await (await client(opts)).action(api.voices.deleteVoice, { voiceId: voice.id });
+  return { ...out, id: voice.id, name: voice.name };
+}
+
+// Poll a clone until it is ready or failed; returns the final voice.
+export async function pollVoice(opts, voiceId, { intervalMs = 2000, timeoutMs = 300_000, onProgress } = {}) {
+  const c = await client(opts);
+  const start = Date.now();
+  let misses = 0;
+  for (;;) {
+    let voice;
+    try {
+      voice = await c.query(api.voices.getVoice, { voiceId: String(voiceId) });
+      misses = 0;
+    } catch (e) {
+      // A blip should not end the wait: the clone keeps running (and is charged).
+      if (++misses >= 3) throw new Error(`lost track of voice ${voiceId} (${errorText(e)}); it may still be cloning, check voice list`);
+      await new Promise((r) => setTimeout(r, intervalMs));
+      continue;
+    }
+    if (onProgress) onProgress(voice);
+    if (voice.status !== "pending") return voice;
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(`voice ${voiceId} still cloning after ${Math.round(timeoutMs / 1000)}s; check it later with voice list`);
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+}
+
+// Poll a narration job until it is done or failed; returns the final job.
+export async function pollNarrationJob(opts, jobId, { intervalMs = 3000, timeoutMs = 900_000, onProgress } = {}) {
+  const c = await client(opts);
+  const start = Date.now();
+  for (;;) {
+    const job = await c.query(api.narration.getJob, { jobId: String(jobId) });
+    if (onProgress) onProgress(job);
+    if (job.status === "done" || job.status === "error") return job;
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(`narration job ${jobId} still ${job.status} after ${Math.round(timeoutMs / 1000)}s; it keeps running on the server, and running narrate again once it ends reuses every finished slide`);
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+}
+
 export async function listShares(opts, slug) {
   if (!slug) throw new Error("slug is required");
   const rows = await (await client(opts)).query(api.shares.listForDeck, { deckSlug: slug });
@@ -155,6 +328,15 @@ export async function removeShare(opts, token) {
   return { token, removed: true };
 }
 
+// Register a new deck (draft) you own. Refuses any slug that already exists:
+// upsert would otherwise reset your own live deck to a draft and rename it.
+export async function createDeck(opts, { slug, title }) {
+  const c = await client(opts);
+  if (await c.query(api.decks.get, { slug })) throw new Error(`deck ${slug} already exists; pick another slug`);
+  await c.mutation(api.decks.upsert, { slug, title, status: "draft" });
+  return { slug, title, status: "draft" };
+}
+
 export async function removeDeck(opts, slug) {
   if (!slug) throw new Error("slug is required");
   // Cascade delete (deck + its assets/shares/sessions + stored HTML) runs in

package/src/preview-capture.mjs

@@ -1,7 +1,7 @@
 import { lookup } from 'node:dns/promises';
 import { isIP } from 'node:net';
 import { createServer } from 'node:http';
-import { readFile, realpath, mkdtemp, rm, stat } from 'node:fs/promises';
+import { readFile, realpath, mkdtemp, rm, stat, writeFile } from 'node:fs/promises';
 import { resolve, dirname, extname, sep, join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { randomUUID } from 'node:crypto';
@@ -107,6 +107,59 @@ export async function routeCaptureRequest(route, entryUrl, origins = []) {
   } catch { await route.abort().catch(() => {}); return false; }
 }
 
+// Bounds a page.evaluate on the Node side: in-page timers cannot fire while the
+// deck holds the main thread. Resolves `fallback` instead of waiting further.
+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); }
+}
+
+// Records `frames` slots at `fps` from CDP screencast frames, which the
+// compositor pushes without waiting on the page's main thread. `ready()`
+// prepares the page and returns a fresh screenshot plus the time it finished:
+// screencast frames stamped earlier can predate the label overlay (the
+// compositor keeps drawing old commits while the main thread is busy) and are
+// dropped. Each slot holds the newest frame at or before its time; slots still
+// empty after the wall-clock window repeat the last frame. Returns how many
+// screencast frames were used (0 means the output is the poster alone).
+export async function recordFrames(session, { frames, fps, dir, ready, slack = 3000, onPhase = () => {} }) {
+  let mark = Infinity, last, used = 0, next = 0, writes = Promise.resolve(), done;
+  const finished = new Promise(ok => { done = ok; });
+  const fill = data => {
+    const path = join(dir, `frame-${String(next).padStart(4,'0')}.png`);
+    writes = writes.then(() => writeFile(path, data));
+    writes.catch(() => {});
+    onPhase(`frame ${Math.min(++next + 1, frames)} of ${frames}`);
+  };
+  session.on('Page.screencastFrame', ({ data, metadata, sessionId }) => {
+    session.send('Page.screencastFrameAck', { sessionId }).catch(() => {});
+    const ts = metadata.timestamp ?? Date.now() / 1000;
+    if (next >= frames || ts < mark) return;
+    while (next < frames && mark + next/fps < ts) fill(last);
+    last = Buffer.from(data, 'base64');
+    used++;
+    if (next >= frames) done();
+  });
+  try {
+    onPhase('screencast start');
+    await session.send('Page.startScreencast', { format:'png', everyNthFrame:1 });
+    ({ image: last, at: mark } = await ready());
+    let timer;
+    try { await Promise.race([finished, new Promise(ok => { timer = setTimeout(ok, frames/fps*1000 + slack); })]); }
+    finally { clearTimeout(timer); }
+    onPhase('screencast stop');
+    await session.send('Page.stopScreencast');
+    while (next < frames) fill(last);
+  } finally {
+    // The caller removes `dir` after this returns or throws; no write may still be pending.
+    await writes.catch(() => {});
+  }
+  await writes;
+  return used;
+}
+
 async function encode(ffmpeg, args) {
   try { await run(ffmpeg, ['-hide_banner', '-loglevel', 'error', '-nostdin', ...args], { timeout: 90000, maxBuffer: 1024 * 1024, env: { PATH: dirname(ffmpeg), ...(process.platform === 'win32' ? { SystemRoot: process.env.SystemRoot } : {}) } }); }
   catch (e) { throw new Error(`FFmpeg encoding failed (${e.killed ? '90s timeout' : 'check portable encoder installation'}); no global FFmpeg is used`); }
@@ -116,7 +169,7 @@ export async function capturePreview(config) {
   let ffmpeg;
   try { ffmpeg = (await import('@ffmpeg-installer/ffmpeg')).default.path; await run(ffmpeg, ['-version'], { timeout:10000 }); }
   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.'); }
-  let browser, server, temp, deadline, timedOut = false;
+  let browser, server, temp, deadline, timedOut = false, phase = 'launch';
   const warnings = [];
   try {
     temp = await mkdtemp(join(tmpdir(), 'hyperdecks-preview-'));
@@ -143,38 +196,58 @@ export async function capturePreview(config) {
     page.setDefaultTimeout(15000);
     page.on('pageerror', () => failed++);
     page.on('requestfailed', request => { if (request.failure()?.errorText !== 'net::ERR_FAILED') failed++; });
+    phase = 'page load';
     await page.goto(server.url, { waitUntil:'domcontentloaded', timeout:30000 });
-    const fontsReady = await page.evaluate(async () => Promise.race([document.fonts.ready.then(() => true), new Promise(ok => setTimeout(() => ok(false), 5000))]));
+    phase = 'fonts';
+    const fontsReady = await within(page.evaluate(() => document.fonts.ready.then(() => true)), 5000, false);
     if (!fontsReady) warnings.push('Fonts did not settle within 5s; inspect the poster or increase --delay.');
+    phase = 'delay';
     await page.waitForTimeout(config.delay);
-    const detected = await page.evaluate(() => {
+    phase = 'layout probe';
+    const probed = Date.now();
+    const detected = await within(page.evaluate(() => {
       const meta = document.querySelector('meta[name="preview-aspect-ratio"]')?.getAttribute('content');
       if (meta && /^\d+(?:\.\d+)?:\d+(?:\.\d+)?$/.test(meta)) { const [w,h] = meta.split(':').map(Number); return w/h; }
       const slide = document.querySelector('.slide, [data-slide], canvas');
       const rect = slide?.getBoundingClientRect();
       return rect && rect.width > 100 && rect.height > 100 ? rect.width/rect.height : null;
-    });
-    const aspect = config.aspect ?? (detected >= 0.5 && detected <= 3 ? detected : 16/9);
+    }), 15000, 'timeout');
+    // Software WebGL can hold the main thread for seconds; frames still come from the compositor.
+    const busy = (Date.now() - probed) / 1000;
+    if (detected === 'timeout') warnings.push(`The deck kept its main thread busy for over 15s; the layout probe gave up${config.aspect ? '' : ' and used 16:9 (pass --aspect-ratio W:H if the deck has another shape)'}.`);
+    else if (busy > 1) warnings.push(`The deck kept its main thread busy for ${busy.toFixed(1)}s; script-driven motion may look choppy.`);
     if (!config.aspect && !detected) warnings.push('Using 16:9 aspect ratio; use --aspect-ratio W:H or preview-aspect-ratio metadata for a different deck shape.');
+    const aspect = config.aspect ?? (detected >= 0.5 && detected <= 3 ? detected : 16/9);
     const width = config.width % 2 ? config.width + 1 : config.width;
     const height = Math.round(width / aspect / 2) * 2;
     await page.setViewportSize({ width:1280, height:Math.round(1280/aspect) });
-    await page.evaluate(label => {
-      const badge = document.createElement('div');
-      badge.textContent = '▶  ' + label;
-      badge.setAttribute('style', 'all:initial;position:fixed;bottom:28px;left:50%;transform:translateX(-50%);background:rgba(0,0,0,.85);color:white;font:600 25px sans-serif;padding:14px 24px;border-radius:40px;z-index:2147483647;white-space:nowrap;max-width:90%;overflow:hidden;text-overflow:ellipsis;pointer-events:none');
-      document.documentElement.appendChild(badge);
-    }, config.label);
     const fps = 10, frames = Math.round(config.duration * fps), duration = frames/fps;
-    // Screenshots capture the live WebGL compositor and CSS motion without
-    // starting a deck narration tour or waiting forever on looped media.
-    for (let i = 0; i < frames; i++) {
-      const start = Date.now();
-      await page.screenshot({ path: join(temp, `frame-${String(i).padStart(4,'0')}.png`), timeout:10000 });
-      if (i < frames-1) await page.waitForTimeout(Math.max(0, 1000/fps - (Date.now()-start)));
-    }
+    // Screencast captures the live WebGL compositor and CSS motion without
+    // starting a deck narration tour, and its frames keep coming while deck
+    // script saturates the main thread (where per-frame screenshots stall).
+    phase = 'screencast start';
+    const used = await recordFrames(await context.newCDPSession(page), { frames, fps, dir: temp, onPhase: p => { phase = p; }, ready: async () => {
+      phase = 'label overlay';
+      const labelled = await within(page.evaluate(label => {
+        const badge = document.createElement('div');
+        badge.textContent = '▶  ' + label;
+        badge.setAttribute('style', 'all:initial;position:fixed;bottom:28px;left:50%;transform:translateX(-50%);background:rgba(0,0,0,.85);color:white;font:600 25px sans-serif;padding:14px 24px;border-radius:40px;z-index:2147483647;white-space:nowrap;max-width:90%;overflow:hidden;text-overflow:ellipsis;pointer-events:none');
+        document.documentElement.appendChild(badge);
+        return true;
+      }, config.label), 15000, false);
+      if (!labelled) warnings.push('The deck kept its main thread busy for over 15s; the label may be missing from the preview.');
+      phase = 'poster frame';
+      // A screenshot forces a frame from the latest commit, so it and every
+      // later compositor frame show the badge.
+      const image = await page.screenshot({ timeout:15000 });
+      phase = `frame 1 of ${frames}`;
+      return { image, at: Date.now() / 1000 };
+    } });
+    if (!used) warnings.push('No motion was captured after the poster; the GIF and MP4 show a still image.');
+    phase = 'browser close';
     await context.close();
     clearTimeout(deadline);
+    phase = 'encode';
     const input = ['-framerate', String(fps), '-i', join(temp, 'frame-%04d.png')];
     const paths = Object.fromEntries(['png','gif','mp4'].map(t => [t, resolve(config.out, `preview.${t}`)]));
     await encode(ffmpeg, ['-i', join(temp,'frame-0000.png'), '-vf', `scale=${width}:${height}`, '-frames:v','1', paths.png]);
@@ -184,7 +257,7 @@ export async function capturePreview(config) {
     if (failed) warnings.push(`${failed} page/resource error(s); inspect the poster and increase --delay if necessary.`);
     const files = await Promise.all(['gif','png','mp4'].map(async type => ({ type, path: paths[type], contentType: type === 'mp4' ? 'video/mp4' : `image/${type}`, bytes: (await stat(paths[type])).size, width, height, ...(type === 'png' ? {} : { duration, fps, silent:true, ...(type === 'gif' ? { loop:0 } : {}) }) })));
     return { files, warnings };
-  } catch (e) { throw new Error(`Capture failed: ${timedOut ? '60s capture timeout; the renderer did not respond' : /Timeout/i.test(e.name) ? 'bounded capture timeout; inspect the deck or increase --delay' : e.message}`); }
+  } catch (e) { throw new Error(`Capture failed during ${phase}: ${timedOut ? '60s capture timeout; the renderer did not respond' : /Timeout/i.test(e.name) ? 'bounded capture timeout; inspect the deck or increase --delay' : e.message}`); }
   finally {
     clearTimeout(deadline);
     if (browser) await browser.close().catch(() => {});