@hypersocial/decks-cli 0.9.8 → 0.9.10

package/src/commands.mjs

@@ -72,12 +72,23 @@ async function deckStats(pos, opts) {
   }
 }
 
+// The owner link: present or check your own deck (untracked, owner-only).
+function deckLink(pos, opts) {
+  const [slug] = pos;
+  if (!slug) throw new Error("usage: deck link <slug> [--json]");
+  const out = ops.ownerLink(opts, slug);
+  if (opts.json) return console.log(JSON.stringify(out, null, 2));
+  console.log(out.ownerUrl);
+  if (out.backupUrl) console.log(`backup (other domain): ${out.backupUrl}`);
+  console.log("Only you can open it, signed in; nothing is tracked. Present (or H) hides your owner tools for a screen share.");
+}
+
 function deckOpen(pos, opts) {
   const [slug] = pos;
   if (!slug) throw new Error("usage: deck open <slug>");
-  const url = `${target(opts).brokerBase}/d/${slug}`;
-  console.log(url);
-  openBrowser(url);
+  const { ownerUrl } = ops.ownerLink(opts, slug);
+  console.log(ownerUrl);
+  openBrowser(ownerUrl);
 }
 
 async function deckRemove(pos, opts) {
@@ -89,8 +100,11 @@ async function deckRemove(pos, opts) {
 
 async function shareNew(pos, opts) {
   const [slug, recipient] = pos;
-  if (!slug || !recipient) throw new Error("usage: share new <slug> <recipient> [--email e] [--note n] [--require-email] [--expires iso] [--limit n] [--qa] [--no-notify] [--allow-forward|--no-forward]");
+  const usage = "usage: share new <slug> <recipient> [--email e] [--note n] [--require-email] [--expires iso] [--limit n] [--qa] [--no-notify] [--allow-forward|--no-forward] [--pace auto|slide|step]";
+  if (!slug || !recipient) throw new Error(usage);
   if (opts["allow-forward"] && opts["no-forward"]) throw new Error("pick one of --allow-forward and --no-forward");
+  // The link's own pace; without it the link follows the deck's.
+  if ("pace" in opts && !ops.DECK_PACES.includes(opts.pace)) throw new Error(usage);
   const { token } = await ops.createShare(opts, {
     slug,
     recipient,
@@ -100,6 +114,7 @@ async function shareNew(pos, opts) {
     qa: opts.qa || undefined,
     notify: opts["no-notify"] ? false : undefined,
     allowForward: opts["allow-forward"] ? true : opts["no-forward"] ? false : undefined,
+    pace: opts.pace,
     expires: opts.expires,
     limit: opts.limit,
   });
@@ -123,7 +138,7 @@ async function shareList(pos, opts) {
   // Rows arrive with each link's forwards right after it; indent those.
   for (const r of rows) {
     const who = r.parentToken ? `  ↳ ${r.recipient} via ${r.forwardedBy ?? "?"}` : r.recipient;
-    console.log(`${r.enabled ? "on " : "off"}\t${r.token}\t${who}\topens:${r.opens}\tfwd:${r.allowForward ? "on" : "off"}${r.qa ? "\tQA (untracked)" : ""}${r.notify === false ? "\tmuted" : ""}${r.probablyForwarded ? "\tprobably forwarded" : ""}${r.archived ? "\t(archived)" : ""}`);
+    console.log(`${r.enabled ? "on " : "off"}\t${r.token}\t${who}\topens:${r.opens}\tfwd:${r.allowForward ? "on" : "off"}${r.pace ? `\tpace:${r.pace}` : ""}${r.qa ? "\tQA (untracked)" : ""}${r.notify === false ? "\tmuted" : ""}${r.probablyForwarded ? "\tprobably forwarded" : ""}${r.archived ? "\t(archived)" : ""}`);
   }
   if (!rows.length) console.log("(no shares)");
 }
@@ -158,28 +173,32 @@ async function deckForward(pos, opts) {
   console.log(`OK forwarding ${mode} for deck ${slug} (links with their own setting keep it)`);
 }
 
-const VIEW_USAGE = "usage: deck view <slug> [slides|scroll|default] [--toggle on|off] [--pace auto|slide|step|default]";
+const VIEW_USAGE = "usage: deck view <slug> [slides|scroll|default] [--toggle on|off] [--pace auto|slide|step|default] [--ai-readable on|off]";
 const VIEWS = { slides: "slides", scroll: "scroll", default: null };
 const PACES = { auto: "auto", slide: "slide", step: "step", default: null };
 async function deckView(pos, opts) {
   const [slug, mode] = pos;
   const toggle = opts.toggle;
   const pace = opts.pace;
-  if (!slug || (mode === undefined && !Object.hasOwn(opts, "toggle") && !Object.hasOwn(opts, "pace"))) throw new Error(VIEW_USAGE);
+  const ai = opts["ai-readable"];
+  if (!slug || (mode === undefined && !["toggle", "pace", "ai-readable"].some((k) => Object.hasOwn(opts, k)))) throw new Error(VIEW_USAGE);
   if (mode !== undefined && !Object.hasOwn(VIEWS, mode)) throw new Error(VIEW_USAGE);
   // A trailing --toggle with no value is a mistake, not "leave it".
   if (Object.hasOwn(opts, "toggle") && toggle !== "on" && toggle !== "off") throw new Error(VIEW_USAGE);
   if (Object.hasOwn(opts, "pace") && !Object.hasOwn(PACES, pace)) throw new Error(VIEW_USAGE);
+  if (Object.hasOwn(opts, "ai-readable") && ai !== "on" && ai !== "off") throw new Error(VIEW_USAGE);
   const out = await ops.setDeckView(opts, slug, {
     view: mode === undefined ? undefined : VIEWS[mode],
     viewToggle: toggle === undefined ? undefined : toggle === "on",
     pace: pace === undefined ? undefined : PACES[pace],
+    aiReadable: ai === undefined ? undefined : ai === "on",
   });
   if (opts.json) return void console.log(JSON.stringify(out, null, 2));
   const said = [];
   if (mode !== undefined) said.push(mode === "default" ? "opens as its HTML says" : `opens as ${mode}`);
   if (toggle !== undefined) said.push(`viewer toggle ${toggle}`);
   if (pace !== undefined) said.push(pace === "default" ? "paces as its HTML says" : `pace ${pace}`);
+  if (ai !== undefined) said.push(`AI-readable version (/v/<token>/md) ${ai}`);
   if (out.applies === false) {
     console.log(`OK deck ${slug} ${said.join(", ")} (saved)`);
     console.warn(`warning: ${out.warning}`);
@@ -256,7 +275,7 @@ async function engagement(pos, opts) {
     console.log(`  visits:      ${s.visits} (last ${new Date(s.lastSeenAt).toISOString().slice(0, 16).replace("T", " ")}) · ${fmtMs(s.totalMs)} engaged`);
     console.log(`  narration:   ${s.narration.finished ? "finished" : s.narration.started ? "started" : "not started"} · heard ${pct(s.narration.heardPct)}${s.narration.telemetry === "v3" ? "" : " (playback detail unavailable)"}`);
     console.log(`  reached:     slide ${s.furthestSlide}${e.deck.slides ? ` of ${e.deck.slides}` : ""}${s.droppedOffOn ? ` · dropped off on ${slideName(s.droppedOffOn)}` : ""}`);
-    console.log(`  replayed:    ${list(s.replayedSlides)}`);
+    console.log(`  replayed:    ${list(s.replayedSlides)}${s.replayNote ? ` · ${s.replayNote}` : ""}`);
     console.log(`  skipped:     ${list(s.skippedSlides)}`);
     console.log(`  most time:   ${s.mostTime.map((m) => `${slideName(m)} (${fmtMs(m.ms)})`).join(", ") || "none"}`);
     if (!s.slideData) console.log("  slide data unavailable (this deck reports time only)");
@@ -344,12 +363,16 @@ commands:
   login [--token <pat>] [--broker <url>] [--dev]
   logout [--dev]
   whoami [--json] [--dev]
-  deck list|stats|open|rm|forward|view
+  deck list|stats|open|link|rm|forward|view
+  deck link <slug> [--json]
+                   the owner link: present or check your own deck (only you, signed in; untracked;
+                   Present or H hides your owner tools). Use it instead of a QA link. deck open opens it.
   deck forward on|off <slug>
                    whether viewers can forward the deck's links (on by default; a link's own setting wins)
-  deck view <slug> [slides|scroll|default] [--toggle on|off] [--pace auto|slide|step|default]
+  deck view <slug> [slides|scroll|default] [--toggle on|off] [--pace auto|slide|step|default] [--ai-readable on|off]
                    how the deck opens in the player (default: as its HTML says, data-view or slides) and
                    whether viewers get the slides/scroll toggle (on by default). Every link, next load; no re-release.
+                   --ai-readable: whether each link + /md serves the deck as markdown for AI assistants (on by default).
   deck new <slug> "<title>" --narrated [--layouts hero,product,number,closer] [--presenter-style stage|bubble|glass|corner] [--no-brand] [--dir <path>]
                    scaffold decks/<slug>/: index.html (8 slides, or one per layout, player/v1), script.md, evidence.md,
                    in your saved brand's colours, fonts and logo (--no-brand: the template's look)
@@ -364,7 +387,7 @@ commands:
   source pull <slug> [dir] | source push <slug> [dir] [--base-rev N]
                    move a hosted draft (index.html, script.md, evidence.md) to a folder and back
   asset add <slug> <file|url> [--name n]
-                   file an image, video or font under the deck; prints its hosted URL
+                   file an image, video, audio (mp3, m4a), font or JSON under the deck; prints its URL
   guide [workflow|format|script|scripts|design|layouts|presenter|transitions|check]
                    the skill, one topic at a time (what deck_guide serves)
   play <slug|deck-dir> [--voice <the voice it was narrated in>] [--slug <slug>] [--port <n>] [--no-open] [--json]
@@ -373,7 +396,7 @@ commands:
   release <slug|deck-dir> [--to "<name>" [--email <e>]]... [--qa] [--no-notify] [--title t] [--voice v] [--captions-only (--hosted)]
                    on a committed deck: check → narrate → import → share new per --to
   share new|list|on|off|forward|mute|unmute|rm|url
-    share new <slug> <recipient> [--qa] [--no-notify] [--allow-forward|--no-forward]
+    share new <slug> <recipient> [--qa] [--no-notify] [--allow-forward|--no-forward] [--pace auto|slide|step]
     share forward on|off|default <token>
                    let this link's viewer forward it as their own tracked link ("Dana via Peter",
                    one hop); default follows the deck. share off on a link also turns off its forwards.
@@ -898,8 +921,11 @@ function commandTable(pos, rest, opts) {
     },
     "avatar from-photo": async () => {
       const { avatarFromPhoto } = await import("./avatar.mjs");
-      const out = await avatarFromPhoto(rest[0], opts);
+      const { askLine } = await import("./init.mjs");
+      const out = await avatarFromPhoto(rest[0], opts, { ask: askLine });
       if (opts.json) console.log(JSON.stringify(out, null, 2));
+      // A pet photo is still a failed drawing: the offer is printed, the exit says so.
+      if (out?.status === "failed") process.exitCode = 1;
     },
     "avatar connect": async () => {
       const { avatarConnect } = await import("./avatar.mjs");
@@ -964,9 +990,20 @@ function commandTable(pos, rest, opts) {
       console.log(opts.json ? JSON.stringify(out, null, 2) : `"${out.caption}"\n  ${out.url}`);
     },
     "deck narrator": async () => {
-      if (rest.length < 2) throw new Error("usage: deck narrator <slug> <name|id|none|default>");
+      if (rest.length < 2) throw new Error("usage: deck narrator <slug> <name|id|none|default> [--dir <deck folder>]");
       const out = await ops.setDeckNarrator(opts, rest[0], rest.slice(1).join(" "));
-      console.log(opts.json ? JSON.stringify(out, null, 2) : `OK ${out.slug} → ${out.narrator} (voice at its next narrate; face in play and the draft link now, on share links at its next release)`);
+      const log = opts.json ? (line) => console.error(line) : (line) => console.log(line);
+      log(`OK ${out.slug} → ${out.narrator} (voice at its next narrate; face in play and the draft link now, on share links at its next release)`);
+      // The local file names the face too, so the draft opened from disk shows it.
+      const { writeDraftFace } = await import("./draftFace.mjs");
+      const dir = resolve(typeof opts.dir === "string" ? opts.dir : join("decks", out.slug));
+      let local = { wrote: false };
+      try {
+        local = await writeDraftFace(opts, out.slug, join(dir, "index.html"), { log });
+      } catch (e) {
+        log(`⚠ presenter: the server was updated but index.html was not (${e.message})`);
+      }
+      if (opts.json) console.log(JSON.stringify({ ...out, indexHtml: local.wrote ? join(dir, "index.html") : null }, null, 2));
     },
     "preview setup": async () => {
       const { setupCapture } = await import("./preview-capture.mjs");
@@ -978,6 +1015,7 @@ function commandTable(pos, rest, opts) {
     "deck list": () => deckList(opts),
     "deck stats": () => deckStats(rest, opts),
     "deck open": () => deckOpen(rest, opts),
+    "deck link": () => deckLink(rest, opts),
     "deck rm": () => deckRemove(rest, opts),
     "deck forward": () => deckForward(rest, opts),
     "deck view": () => deckView(rest, opts),

package/src/draftFace.mjs

@@ -0,0 +1,56 @@
+// The narrator's face written into a draft's index.html on disk (roadmap:
+// a-narrated-draft-shows-its-narrator-s-face-from-the-file-on-), so the file
+// plays with its face however it is opened, not only through play and release.
+// deck new, deck narrator and narrate use it.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import * as ops from "./ops.mjs";
+import { DASH_PRESENTER, withNarrator, writeNarratorFace } from "./presenter.mjs";
+
+// What to write for `slug`: { face } (null: captions only on purpose), or
+// { face: undefined, why } when the narrator has no face and nobody chose captions
+// only (writeDraftFace then takes a CLI-written face off), or the lookup failed
+// (`failed`: nothing is decided, the file stays).
+export async function draftFace(opts, slug) {
+  let found;
+  try {
+    found = await ops.presenterWithReason(opts, slug, undefined, { draft: true });
+  } catch (e) {
+    return { face: undefined, why: `could not look up the narrator's face (${e.message})`, failed: true };
+  }
+  if (found?.presenter) return { face: found.presenter, name: found.who?.face ?? null };
+  // Captions only on purpose only when the deck says so; faces off or a missing face stays unwritten.
+  if (!found?.presenter && found?.captionsOnly) return { face: null, name: null };
+  return { face: undefined, why: found?.who?.reason ?? "no narrator with a face" };
+}
+
+// Write `slug`'s face into `htmlPath`. `fallback`: the face to write when the
+// lookup fails (deck new writes D.A.S.H.). Logs one line; returns what it wrote.
+export async function writeDraftFace(opts, slug, htmlPath, { log = () => {}, fallback } = {}) {
+  if (!existsSync(htmlPath)) {
+    log(`⚠ presenter: ${htmlPath} not found, so the file was not updated (the server was); pass --dir <deck folder>`);
+    return { wrote: false };
+  }
+  const got = await draftFace(opts, slug);
+  const face = got.face === undefined && got.failed && fallback ? fallback : got.face;
+  const html = readFileSync(htmlPath, "utf8");
+  if (face === undefined) {
+    // The narrator has no face now: a face the CLI wrote for an earlier one comes off, as play and release do.
+    const off = got.failed ? html : withNarrator(html, null, { face: null });
+    if (off !== html) {
+      writeFileSync(htmlPath, off);
+      log(`⚠ presenter: no face (${got.why}); the earlier narrator's face was taken off index.html`);
+      return { wrote: true, face: null, why: got.why };
+    }
+    log(`⚠ presenter: index.html left as written: ${got.why}`);
+    return { wrote: false, why: got.why };
+  }
+  const out = writeNarratorFace(html, face);
+  if (!out.wrote) {
+    log(`⚠ presenter: index.html left as written: ${out.why}`);
+    return { wrote: false, why: out.why };
+  }
+  if (out.html !== html) writeFileSync(htmlPath, out.html);
+  const who = face === null ? "captions only" : face === DASH_PRESENTER && got.failed ? `D.A.S.H. (${got.why}; deck narrator <name> fixes it)` : got.name ?? "the narrator's face";
+  log(`  presenter: ${who}, written to index.html`);
+  return { wrote: true, face };
+}

package/src/export-video.mjs

@@ -115,7 +115,8 @@ export function planTimeline(plan) {
 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) }))
+    // A guest line's entry names its own audio; `seek`: the slide's track picking up again after one.
+    .map((c) => ({ id: c.id, audio: c.audio ?? audioOf.get(c.id) ?? null, offset: lead + Math.max(0, (c.at - markMs) / 1000), ...(c.seek > 0 ? { seek: c.seek } : {}) }))
     .filter((c) => c.audio);
 }
 
@@ -125,7 +126,8 @@ export function audioTimeline(log, markMs, lead = 0) {
 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) }));
+  // Only each slide's own start: guest lines and resumes (entries with their own audio) are inside it.
+  return (log.clips ?? []).filter((c) => startOf.has(c.id) && !c.audio).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
@@ -147,7 +149,9 @@ export function audioMixArgs({ inputs, seconds, out }) {
   }
   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}]`);
+    // `seek`: start that far into the file (a slide's track resuming after a guest line).
+    const from = c.seek > 0 ? `,atrim=start=${Number(c.seek).toFixed(3)},asetpts=PTS-STARTPTS` : '';
+    parts.push(`[${n}:a]${fmt}${from},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]`);
@@ -185,7 +189,7 @@ export const SEAM_SECONDS = 2;
 export const SEAM_FRAMES = SEAM_SECONDS * VIDEO_FPS;
 export const MAX_SPLIT_CLIPS = 200;
 export function splittableAudio(plan) {
-  const audio = plan.map((s) => s.audio).filter(Boolean);
+  const audio = plan.flatMap((s) => [s.audio, ...(Array.isArray(s.guests) ? s.guests : [])]).filter(Boolean);
   return audio.length <= MAX_SPLIT_CLIPS && audio.every((a) => typeof a === 'string' && a.length <= MAX_SPLIT_AUDIO_URL && /^https?:\/\//i.test(a));
 }
 
@@ -223,7 +227,7 @@ export function joinTimeline(segments, fps = VIDEO_FPS) {
   let frames = 0;
   const clips = [];
   for (const s of segments) {
-    for (const c of s.clips ?? []) clips.push({ id: c.id, audio: c.audio, offset: Math.max(0, frames / fps + (Number(c.offset) || 0)) });
+    for (const c of s.clips ?? []) clips.push({ id: c.id, audio: c.audio, offset: Math.max(0, frames / fps + (Number(c.offset) || 0)), ...(c.seek > 0 ? { seek: c.seek } : {}) });
     frames += s.frames;
   }
   return { clips, frames, seconds: frames / fps };
@@ -503,8 +507,9 @@ export async function recordVideo(config, { log = () => {}, chromium: injected,
     // A range needs only its own slides' clips.
     const audioFiles = new Map(), clipLengths = {};
     const wanted = (state.plan ?? []).filter((s) => inRange(s.id));
-    for (const [n, url] of [...new Set(wanted.map((s) => s.audio).filter(Boolean))].entries()) {
-      const id = wanted.find((s) => s.audio === url).id;
+    // A slide's guest lines are audio of their own.
+    for (const [n, url] of [...new Set(wanted.flatMap((s) => [s.audio, ...(Array.isArray(s.guests) ? s.guests : [])]).filter(Boolean))].entries()) {
+      const id = wanted.find((s) => s.audio === url || s.guests?.includes(url)).id;
       const path = clipPath(temp, n, url);
       await downloadClip(url, path, { id, entryUrl: pageUrl });
       audioFiles.set(url, path);
@@ -643,13 +648,13 @@ export async function recordVideo(config, { log = () => {}, chromium: injected,
         file: out, seconds: kept / VIDEO_FPS, width: geometry.width, height: geometry.height, bytes, slides: to - from + 1, clips: own.length, render, warnings,
         // frames: in the file. A clip's offset is from the file's first frame:
         // after a dropped seam, a slide's clip may start (just) before it.
-        segment: { from, to, frames: kept, tail, clips: own.map((c) => ({ id: c.id, audio: c.audio, offset: c.offset - skip / VIDEO_FPS })) },
+        segment: { from, to, frames: kept, tail, clips: own.map((c) => ({ id: c.id, audio: c.audio, offset: c.offset - skip / VIDEO_FPS, ...(c.seek ? { seek: c.seek } : {}) })) },
       };
     }
     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 };
+      return { path, offset: c.offset, seek: c.seek };
     });
     const audio = join(temp, 'audio.wav');
     await ffmpeg(ff, audioMixArgs({ inputs, seconds: total, out: audio }), 300000);
@@ -695,7 +700,7 @@ export async function joinVideo({ segments, out, origin = null }, { log = () =>
     }
     phase = 'audio';
     const audio = join(temp, 'audio.wav');
-    await ffmpeg(ff, audioMixArgs({ inputs: timeline.clips.map((c) => ({ path: files.get(c.audio), offset: c.offset })), seconds: timeline.seconds, out: audio }), 300000);
+    await ffmpeg(ff, audioMixArgs({ inputs: timeline.clips.map((c) => ({ path: files.get(c.audio), offset: c.offset, seek: c.seek })), seconds: timeline.seconds, out: audio }), 300000);
     phase = 'join';
     const list = join(temp, 'segments.txt');
     await writeFile(list, concatList(segments.map((s) => s.file)));

package/src/mediaPreviewMake.mjs

@@ -0,0 +1,72 @@
+// The pixels behind mediaPreviews.mjs: ffmpeg (the @ffmpeg-installer build the
+// CLI's video export and Convex's videoStack already use) reads one image or a
+// video's first frame and writes
+//   - a ~20 px wide JPEG as a data URL (the blur preview, well under 1 KB), and
+//   - for a video, a poster: its first frame as a JPEG at most 1280 px wide.
+// Used by the CLI release (local files) and convex/mediaPreviewsNode.ts (fetched
+// bytes written to a temp file). The size comes from ffmpeg's own stream line.
+import { execFile } from "node:child_process";
+import { streamSize } from "./mediaPreviews.mjs";
+
+export const PREVIEW_WIDTH = 20;
+const TIMEOUT_MS = 30_000;
+
+function run(ffmpeg, args) {
+  return new Promise((resolve, reject) => {
+    execFile(ffmpeg, args, { encoding: "buffer", maxBuffer: 16 * 1024 * 1024, timeout: TIMEOUT_MS }, (err, stdout, stderr) => {
+      const text = stderr.toString("utf8");
+      if (err) {
+        const why = err.killed ? `ffmpeg timed out after ${TIMEOUT_MS / 1000}s` : text.trim().split("\n").slice(-2).join(" ") || err.message;
+        return reject(new Error(why.slice(0, 300)));
+      }
+      resolve({ stdout, stderr: text });
+    });
+  });
+}
+
+// Only local files by default: a "video" that is really a playlist (HLS) would
+// otherwise make ffmpeg fetch its segment URLs itself, past any SSRF guard.
+// Nested demuxers inherit the whitelist. The CLI widens it for an https input.
+export const LOCAL_ONLY = "file,pipe";
+export const HTTPS_TOO = "file,pipe,https,tls,tcp,crypto";
+// A picture with more pixels than this (a "pixel bomb": a small file that
+// decodes to gigabytes) is refused by the decoder instead of exhausting memory.
+export const MAX_PIXELS = 64 * 1024 * 1024;
+const frameArgs = (input, allow, vf, q, codec = "mjpeg") => ["-hide_banner", "-nostdin", "-protocol_whitelist", allow, "-max_pixels", String(MAX_PIXELS), "-i", input, "-map", "0:v:0", "-frames:v", "1", "-vf", vf, ...(codec === "mjpeg" ? ["-q:v", String(q)] : []), "-f", "image2pipe", "-c:v", codec, "pipe:1"];
+// A picture with an alpha channel (a background-removed cutout) keeps it: a
+// JPEG preview would put a black box behind the cutout while it loads.
+export const hasAlpha = (stderr) => /Stream #[^\n]*?Video:[^\n]*?\b(rgba|bgra|argb|abgr|ya8|ya16\w*|yuva\w*|gbrap\w*|rgba64\w*|pal8)\b/.test(stderr ?? "");
+
+// { w, h, blur, poster? } for one file (a path, or a URL ffmpeg can open).
+// `poster` (video only) is the JPEG bytes; the caller stores it and swaps in its URL.
+// A picture or video container by its first bytes: JPEG, PNG, GIF, WebP, ISO
+// BMFF (MP4/MOV/AVIF/HEIC) or EBML (WebM). Anything else (an HLS playlist, an
+// HTML error page) never reaches ffmpeg.
+export function knownMedia(bytes) {
+  const b = bytes.subarray(0, 12), ascii = (from, to) => String.fromCharCode(...b.subarray(from, to));
+  return (b[0] === 0xff && b[1] === 0xd8) || ascii(1, 4) === "PNG" || ascii(0, 3) === "GIF"
+    || (ascii(0, 4) === "RIFF" && ascii(8, 12) === "WEBP") || ascii(4, 8) === "ftyp"
+    || (b[0] === 0x1a && b[1] === 0x45 && b[2] === 0xdf && b[3] === 0xa3);
+}
+
+export async function makePreview(ffmpeg, input, { video = false, allow = LOCAL_ONLY } = {}) {
+  let small = await run(ffmpeg, frameArgs(input, allow, `scale=${PREVIEW_WIDTH}:-2:flags=area,format=yuvj420p`, 12));
+  const size = streamSize(small.stderr);
+  if (!size) throw new Error(`no picture in ${input}`);
+  let type = "image/jpeg";
+  if (!video && hasAlpha(small.stderr)) {
+    small = await run(ffmpeg, frameArgs(input, allow, `scale=${PREVIEW_WIDTH}:-2:flags=area,format=rgba`, 0, "png"));
+    type = "image/png";
+  }
+  if (!small.stdout.length) throw new Error(`ffmpeg wrote no preview for ${input}`);
+  const out = { ...size, blur: `data:${type};base64,${small.stdout.toString("base64")}` };
+  if (!video) return out;
+  const frame = await run(ffmpeg, frameArgs(input, allow, "scale='min(1280,iw)':-2,format=yuvj420p", 4));
+  if (!frame.stdout.length) throw new Error(`ffmpeg wrote no poster for ${input}`);
+  return { ...out, poster: frame.stdout };
+}
+
+// The bundled ffmpeg's path, loaded only when release needs it.
+export async function bundledFfmpeg() {
+  return (await import("@ffmpeg-installer/ffmpeg")).default.path;
+}

package/src/mediaPreviews.mjs

@@ -0,0 +1,160 @@
+// Blur previews for a deck's media, added at release (CLI release.mjs and the
+// hosted release in convex/deckSources.ts). Pure string work, no Node APIs, so
+// the Convex mutation can run it; the pixels come from mediaPreviewMake.mjs.
+//
+// mediaRefs(html) lists what needs a preview: each <img>, each <video> without
+// a poster (its first frame becomes one) and each inline background image.
+// withMediaPreviews(html, previews) writes them onto the tags:
+//   data-hd-blur="data:image/jpeg;base64,…"   a ~20 px wide preview (< 1 KB)
+//   style="--hd-ar:W/H;…"                      so the box has its shape before the pixels arrive
+//                                              (player.css: :where([data-hd-blur]) { aspect-ratio: var(--hd-ar) })
+//   poster="…"                                 a <video> that had none
+// The player (packages/player/media-load.js) shows the preview, blurred and
+// shimmering, until the real media is ready. Idempotent: a tag that already has
+// data-hd-blur (or opts out with data-hd-no-blur) is left as it is, so a
+// re-release changes nothing.
+
+// Media this small is an icon: a blurred icon is noise, not a preview.
+export const MIN_PREVIEW_SIDE = 64;
+// The longest data URL written onto a tag; a bigger preview is dropped.
+export const MAX_BLUR_CHARS = 1600;
+
+const SKIP = /^(data:|blob:|javascript:|#)/i;
+const VECTOR = /\.svg(?:[?#]|$)/i;
+
+export function tagAttr(tag, name) {
+  const m = new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s"'=<>\`]+))`, "i").exec(tag);
+  if (!m) return null;
+  return (m[1] ?? m[2] ?? m[3]).replace(/&amp;/g, "&").replace(/&quot;/g, '"').replace(/&#39;/g, "'");
+}
+const hasAttr = (tag, name) => new RegExp(`\\s${name}(?:\\s*=|[\\s/>])`, "i").test(tag);
+
+function usable(src) {
+  const s = (src ?? "").trim();
+  return s && !SKIP.test(s) && !VECTOR.test(s) ? s : null;
+}
+// A tag the author sized as an icon (both sides given and small) is skipped up front.
+function iconSized(tag) {
+  const w = Number(tagAttr(tag, "width")), h = Number(tagAttr(tag, "height"));
+  return w > 0 && h > 0 && Math.max(w, h) < MIN_PREVIEW_SIDE;
+}
+const done = (tag) => hasAttr(tag, "data-hd-blur") || hasAttr(tag, "data-hd-no-blur");
+
+// Tags are matched quote-aware, so a `>` inside an attribute value (alt="a > b") does not end the tag.
+const ATTRS = `(?:[^>"']|"[^"]*"|'[^']*')*`;
+const IMG = new RegExp(`<img\\b${ATTRS}>`, "gi");
+const VIDEO_OPEN = new RegExp(`^<video\\b${ATTRS}>`, "i");
+const VIDEO = new RegExp(`<video\\b${ATTRS}>([\\s\\S]*?)<\\/video\\s*>`, "gi");
+const STYLED = new RegExp(`<[a-z][\\w-]*\\b(?:[^>"']|"[^"]*"|'[^']*')*?\\sstyle\\s*=\\s*(?:"[^"]*"|'[^']*')${ATTRS}>`, "gi");
+// Script, style, comment and template text is code, not markup: never read or rewritten.
+const OPAQUE = /<script\b[\s\S]*?<\/script\s*>|<style\b[\s\S]*?<\/style\s*>|<!--[\s\S]*?-->|<template\b[\s\S]*?<\/template\s*>/gi;
+function markupOnly(html, rewrite) {
+  const kept = [];
+  const masked = html.replace(OPAQUE, (m) => `\u0000${kept.push(m) - 1}\u0000`);
+  return rewrite(masked).replace(/\u0000(\d+)\u0000/g, (_, i) => kept[Number(i)]);
+}
+const BG_URL = /background(?:-image)?\s*:[^;]*?url\(\s*(?:"([^"]+)"|'([^']+)'|([^)\s]+))\s*\)/i;
+
+function videoSrc(open, body) {
+  return usable(tagAttr(open, "src")) ?? usable([...body.matchAll(/<source\b[^>]*>/gi)].map((m) => tagAttr(m[0], "src")).find(usable));
+}
+function bgSrc(tag) {
+  const m = BG_URL.exec(tagAttr(tag, "style") ?? "");
+  return m ? usable(m[1] ?? m[2] ?? m[3]) : null;
+}
+
+// What release must make previews for: { images: [src], videos: [src] }, each
+// src once, as written in the page (relative or absolute).
+export function mediaRefs(page) {
+  const images = new Set(), videos = new Set();
+  const html = page.replace(OPAQUE, "");
+  for (const [tag] of html.matchAll(IMG)) {
+    const src = usable(tagAttr(tag, "src"));
+    if (src && !done(tag) && !iconSized(tag)) images.add(src);
+  }
+  for (const m of html.matchAll(VIDEO)) {
+    const open = VIDEO_OPEN.exec(m[0])[0];
+    // A transparent clip (alpha-video.js swaps it for a canvas) has no frame to blur.
+    if (done(open) || hasAttr(open, "data-alpha-stacked")) continue;
+    const src = videoSrc(open, m[1]);
+    if (src) videos.add(src);
+  }
+  for (const [tag] of html.matchAll(STYLED)) {
+    if (/^<(img|video)\b/i.test(tag) || done(tag)) continue;
+    const src = bgSrc(tag);
+    if (src) images.add(src);
+  }
+  return { images: [...images], videos: [...videos] };
+}
+
+// A preview is usable when it is a small data URL and its media is not an icon.
+export function usablePreview(p) {
+  return !!p && typeof p.blur === "string" && p.blur.startsWith("data:image/") && p.blur.length <= MAX_BLUR_CHARS && !/["'<>\s]/.test(p.blur)
+    && Number.isFinite(p.w) && Number.isFinite(p.h) && Math.min(p.w, p.h) > 0 && Math.max(p.w, p.h) >= MIN_PREVIEW_SIDE;
+}
+
+const escapeAttr = (s) => String(s).replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+
+// Add attributes before the tag's closing `>` (or `/>`). The shape goes in as
+// --hd-ar, which player.css applies with zero specificity, so any aspect-ratio
+// the deck sets (in a stylesheet or the tag) still wins.
+function annotate(tag, p, { ratio = true, poster = null } = {}) {
+  let out = tag;
+  if (ratio) {
+    const rule = `--hd-ar:${Math.round(p.w)}/${Math.round(p.h)};`;
+    const m = /\sstyle\s*=\s*(?:"([^"]*)"|'([^']*)')/i.exec(out);
+    if (m) {
+      const q = m[1] !== undefined ? '"' : "'";
+      out = out.replace(m[0], ` style=${q}${rule}${m[1] ?? m[2]}${q}`);
+    } else out = out.replace(/\s*\/?>$/, (end) => ` style="${rule}"${end}`);
+  }
+  const extra = `${poster ? ` poster="${escapeAttr(poster)}"` : ""} data-hd-blur="${p.blur}"`;
+  return out.replace(/\s*(\/?)>$/, (_, slash) => `${extra}${slash ? " /" : ""}>`);
+}
+
+// previews: { [src]: { w, h, blur, poster? } } keyed by the src as mediaRefs
+// returned it. Media without a usable preview is left as written. Returns the
+// new page and how many tags it changed.
+export function withMediaPreviews(page, previews) {
+  const get = (src) => (src && usablePreview(previews[src]) ? previews[src] : null);
+  let count = 0;
+  const html = markupOnly(page, (html) => {
+  let out = html.replace(IMG, (tag) => {
+    const p = done(tag) || iconSized(tag) ? null : get(usable(tagAttr(tag, "src")));
+    if (!p) return tag;
+    count++;
+    // An author who sized both sides chose the shape already.
+    return annotate(tag, p, { ratio: !(hasAttr(tag, "width") && hasAttr(tag, "height")) });
+  });
+  out = out.replace(VIDEO, (whole, body) => {
+    const open = VIDEO_OPEN.exec(whole)[0];
+    if (done(open) || hasAttr(open, "data-alpha-stacked")) return whole;
+    const p = get(videoSrc(open, body));
+    if (!p) return whole;
+    count++;
+    const poster = hasAttr(open, "poster") ? null : p.poster ?? null;
+    return annotate(open, p, { ratio: !(hasAttr(open, "width") && hasAttr(open, "height")), poster }) + whole.slice(open.length);
+  });
+  out = out.replace(STYLED, (tag) => {
+    if (/^<(img|video)\b/i.test(tag) || done(tag)) return tag;
+    const p = get(bgSrc(tag));
+    if (!p) return tag;
+    count++;
+    // A background's box is the element's own layout, never the image's shape.
+    return annotate(tag, p, { ratio: false });
+  });
+  return out;
+  });
+  return { html, count };
+}
+
+// The size ffmpeg reports for the first video stream ("Stream #0:0: Video: …, 1920x1080").
+export function streamSize(stderr) {
+  const m = /Stream #[^\n]*?Video:[^\n]*?\b(\d{2,5})x(\d{2,5})\b/.exec(stderr ?? "");
+  if (!m) return null;
+  let w = Number(m[1]), h = Number(m[2]);
+  // A phone video stored sideways carries a rotation: its shown shape is swapped.
+  const rot = /rotate\s*:\s*-?(90|270)\b|rotation of -?(90|270)/.exec(stderr ?? "");
+  if (rot) [w, h] = [h, w];
+  return { w, h };
+}

package/src/narrate.mjs

@@ -9,6 +9,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import * as ops from "./ops.mjs";
 import { presenterLine } from "./presenter.mjs";
+import { writeDraftFace } from "./draftFace.mjs";
 export { sectionIds, setManifestUrl } from "./checkRules.mjs";
 import { sectionIds, setManifestUrl } from "./checkRules.mjs";
 
@@ -39,7 +40,8 @@ export function narrationRequest(pos, opts) {
   };
 }
 
-export async function narrate(pos, opts = {}, { log = (line) => console.log(line) } = {}) {
+// writeFace false: leave the presenter as written (release narrates, then puts the face on the upload itself).
+export async function narrate(pos, opts = {}, { log = (line) => console.log(line), writeFace = true } = {}) {
   const { deckDir, fields } = narrationRequest(pos, opts);
   if (opts["dry-run"]) {
     const preview = await ops.previewNarration(opts, fields);
@@ -85,6 +87,9 @@ export async function narrate(pos, opts = {}, { log = (line) => console.log(line
       writeFileSync(htmlPath, next);
       log(`  index.html: data-manifest → ${job.manifestUrl}`);
     }
+    // The narrator's face too, so the file opened as written shows what play and release show.
+    // The narration is paid for and saved: a failed face write warns and never fails narrate.
+    if (writeFace) await writeDraftFace(opts, fields.slug, htmlPath, { log }).catch((e) => log(`⚠ presenter: index.html not updated (${e?.message ?? e})`));
   }
   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")}`);