@hypersocial/decks-cli 0.9.8 → 0.9.9

package/package.json

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

package/skills/hyperdecks/SKILL.md

@@ -149,7 +149,7 @@ Hyperdecks server; use the CLI where you have a shell and the tool otherwise.
 | 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` |
 | Forwarding, whole deck | `hyperdecks deck forward on\|off <slug>` | `set_deck_forwarding` |
-| Slides or scroll, viewer toggle, pace | `hyperdecks deck view <slug> [slides\|scroll\|default] [--toggle on\|off] [--pace auto\|slide\|step\|default]` | `set_deck_view` |
+| Slides or scroll, viewer toggle, pace, AI-readable version | `hyperdecks deck view <slug> [slides\|scroll\|default] [--toggle on\|off] [--pace auto\|slide\|step\|default] [--ai-readable on\|off]` | `set_deck_view` |
 | Who watched | `hyperdecks deck stats <slug>` | `deck_stats` |
 | All activity | `hyperdecks activity --deck <slug>` | `activity_overview` |
 | What one person watched | `hyperdecks engagement "<name>" --deck <slug> --json` | `recipient_engagement` |
@@ -692,6 +692,43 @@ you do).
 | `[smile]` / `[think]` | `[mood: happy]` / `[mood: thinking]` |
 | `[gesture: <id>]` | one of the head's tracks: `knowing-nod`, `ponder-tilt`, `lightbulb`, `side-eye-hmm`, `chuckle-bob`, `sunny-nod`, `double-take`… (check lists them all) |
 | `[custom: name]` | only the slide's controller sees it |
+| `[after: reveal #id]` | any stage cue above, fired at the END of the word before it (reveal at the end of a phrase) instead of its start |
+- Guest speakers: other avatars that speak their own lines on a slide, no
+  slide JS. A `[speaker: <selector> voice=<voice> avatar=<face> name=<caption name>]`
+  line runs to the end of its paragraph; the narrator takes the next one:
+
+  ```
+  ## own
+  Let's hear them.
+
+  [speaker: #own-c1 voice=stock:sarah avatar=cat] Ooh, nice move!
+
+  [speaker: #own-c2 voice=matilda avatar=monkey name="Mono"] [reveal: #own-c2] Hola, ¿qué tal?
+
+  That's the idea.
+  ```
+
+  `voice` is one of the user's voices, a built-in `stock:<id>` or a character
+  voice. `avatar` is a cast id (`cat`, `kitty`, `monkey`, `dog`, `rabbit`,
+  `penguin`, `ghost`, `alien`, `agent`…), one of the user's avatars or a
+  narrator's name; without one the guest speaks with captions only. `name`
+  labels its captions (default: the avatar, capitalised). The guest's head
+  fills the element the selector names, or the `[data-hd-speaker]` spot
+  inside it, so give each card a face box (e.g. 140×140). Narrate renders
+  each line in its own voice (cached, transcript-checked) into the slide's
+  timeline: the narrator pauses, the guests speak in turn with lip-sync and a
+  caption bubble by their element, its tail at their face, the spoken word
+  highlighted ("Cat: Ooh, nice move!"), only while they talk; the speaker's
+  element is spotlit and the other guests dim. The player draws that bubble:
+  don't put static speech bubbles or the guest's line on the slide too. The presenter
+  glances at whoever speaks, then the narrator goes on. A cue may open a
+  guest's line and fires as it starts. Inside a guest's line, `[nod]`,
+  `[shake]`, `[brow]` and `[gesture]` move the guest's head; the other cues
+  (`[reveal]`, `[go]`, `[mood]`, `[wave]`…) act on the slide and the presenter. Replay, Per step (each guest line is a
+  step), mute, You present and video export all include them.
+- Audio and data files a slide uses itself (a sound effect, a chart's JSON):
+  `hyperdecks asset add` / `upload_deck_asset` take `.mp3`, `.m4a` and
+  `.json` as well as images, video and fonts.
 - `voice: dash` narrates with D.A.S.H.'s own robot voice, a synthetic
   character voice (not a clone of anyone) any account may use, for decks that
   D.A.S.H. presents. It works once the deployment sets `CHARACTER_VOICE_DASH`.
@@ -867,8 +904,10 @@ hyperdecks engagement "<name>" --deck <slug> --json   # MCP: recipient_engagemen
 Then draft the email:
 
 1. Lead with the slide they spent most time on (`summary.mostTime`) or
-   replayed (`replayedSlides`), and answer what that slide raises. Each
-   slide's `title` says what it is about.
+   replayed (`replayedSlides`; `slideReplays` are the ones they replayed on
+   purpose, most first, and `replayNote` says it in one line), and answer what
+   that slide raises. Each slide's `title` says what it is about. Watching it
+   again from the start (`watchedAgain`) is strong interest.
 2. If they dropped off (`droppedOffOn`), offer the rest briefly, or a
    2-minute call, rather than asking them to rewatch.
 3. If they never opened it (`summary.visits` is 0), write a short nudge
@@ -889,7 +928,7 @@ the hosted MCP (`deck_guide`, `new_deck`, `get_deck_source`, `write_deck_source`
 `upload_deck_asset`, `check_deck`, `release_deck`; see `chat.md`). Move between
 the two with `hyperdecks source pull <slug> [dir]` (the hosted draft into a
 folder) and `hyperdecks source push <slug> [dir]` (a folder's files back to the
-draft), `hyperdecks asset add <slug> <file|url>` for an image, `hyperdecks guide
+draft), `hyperdecks asset add <slug> <file|url>` for an image, video, audio (.mp3, .m4a), font or JSON file, `hyperdecks guide
 [topic]` for these sections, and `--hosted` on `deck new`, `check` and `release`.
 
 ## After you ship: say what cost you

package/skills/hyperdecks/chat.md

@@ -15,7 +15,9 @@ narrators, credits) and the steps. No voice of their own: `clone_voice_link`
 in the chat, only after they agree to the consent statement, word for word.
 `hear_voice` plays a voice or a narrator in the chat. A face from a photo they
 attach: `avatar_from_photo { file }`, then `check_avatar_draft` until it hands
-back the link they approve it on. `rename_narrator` and `set_narrator_face`
+back the link they approve it on (a pet photo comes back with an `offer`, say
+"That looks like a cat. Make a cat avatar?": ask them, and on a yes
+`new_avatar_link { species }`). `rename_narrator` and `set_narrator_face`
 change a narrator when they ask. Then `get_started { name, about, ask, voice }`
 makes the hello deck; continue from step 5 below.
 
@@ -95,7 +97,11 @@ makes the hello deck; continue from step 5 below.
    for how the deck opens, whether viewers may switch, and its pace (`auto`
    plays itself, `slide` waits for Next after each slide, `step` also stops
    before each `[reveal]`, so group a slide's reveals into meaningful steps)
-   (every link, next load, no re-release); `set_share_notify` to mute a link's "opened" alerts;
+   (every link, next load, no re-release). Any share link + `/md` (e.g.
+   https://decks.hypersocial.ai/v/<token>/md) returns the deck as markdown
+   (slide text, image descriptions and the narration), honouring the link's
+   gates; owners can turn it off with `set_deck_view { slug, aiReadable: false }`.
+   `set_share_notify` to mute a link's "opened" alerts;
    `set_recipient_archived` to tidy the activity feed; `credits` for the
    balance. `remove_deck` deletes a deck and breaks every link to it: confirm
    with the user first.

package/src/avatar.mjs

@@ -59,7 +59,7 @@ export async function avatarNew(opts, { ask, log = console.log, interactive = in
 
 // A face from a photo file, or (no file) a selfie in the browser. Either way the
 // person approves it on the link before it is used.
-export async function avatarFromPhoto(file, opts, { log = console.log, interactive = interactiveOf(opts) } = {}) {
+export async function avatarFromPhoto(file, opts, { ask, log = console.log, interactive = interactiveOf(opts) } = {}) {
   let photo = {};
   if (file) {
     const contentType = PHOTO_TYPES[extname(file).toLowerCase()];
@@ -67,8 +67,19 @@ export async function avatarFromPhoto(file, opts, { log = console.log, interacti
     photo = { bytes: readFileSync(file), contentType };
   }
   const out = await ops.avatarFromPhoto(opts, photo, { onProgress: (m) => !opts.json && log(m) });
-  const url = out.reviewUrl ?? out.selfieUrl;
   if (opts.json) return out;
+  if (out.status === "failed" && out.suggestedSpecies) {
+    // No human face, but a pet: offer that species' faces instead.
+    log(out.offer);
+    if (!interactive || !ask) {
+      log(`  hyperdecks avatar new --species ${out.suggestedSpecies}`);
+      return out;
+    }
+    const a = (await ask("Make one? [Y/n]: ")).trim().toLowerCase();
+    if (a && a !== "y" && a !== "yes") throw new Error(out.error || "no face was found in that photo");
+    return avatarNew({ ...opts, species: out.suggestedSpecies }, { ask, log, interactive });
+  }
+  const url = out.reviewUrl ?? out.selfieUrl;
   log(file ? `✓ Drew a cartoon of you. Check it before it's used:\n  ${url}` : `No photo given. Take a selfie in your browser:\n  ${url}`);
   if (opts["save-to-minimoji"]) log("  (tick \"Also save it to my Minimoji account\" there)");
   if (!interactive) return out;

package/src/checkRules.mjs

@@ -37,6 +37,7 @@ export const MESSAGES = {
   noLoading: () => "no loading state: run `hyperdecks check <deck> --fix` (`check <slug> --hosted --fix`; over the MCP, write index.html again with write_deck_source), which needs a <head>…</head> and the player script; or copy the <style data-hd-loading> block and the lines above it from the narrated template into <head>; set --hd-ground to the first slide's colour",
   clipField: (id, field) => `clip ${id}: ${field}`,
   noCaptions: (id) => `clip ${id}: timeline has no captions`,
+  speakerMissing: (id, name, selector) => `slide ${id}: guest ${name} speaks from "${selector}", which is not on the slide, so its lines play with captions only and no face`,
   order: (slides, clips) => `slide ids (${slides.join(", ")}) must equal the manifest clip ids (${clips.join(", ")}), in order`,
   total: (sum, declared) => `clip durations plus holds add up to ${sum}s but the manifest declares totalDuration ${declared}s`,
   cap: (total, cap) => `narration runs ${total}s, over the ${cap}s cap (aim for 150 to 180 s)`,
@@ -605,6 +606,23 @@ export function htmlErrors(html, { exists = () => true, forbid = [], script = ""
 const isNum = (v) => typeof v === "number" && Number.isFinite(v);
 const isStr = (v) => typeof v === "string" && v.trim().length > 0;
 
+// Whether a guest's selector names something on its slide: an #id, or a
+// .class or [attr] inside that <section>. Other selectors are taken on trust.
+export function speakerOnSlide(html, slideId, selector) {
+  const page = uncommented(html);
+  const open = new RegExp(`<section\\b[^>]*\\sid\\s*=\\s*["']${slideId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}["'][^>]*>`, "i").exec(page);
+  if (!open) return false;
+  const end = page.indexOf("</section>", open.index);
+  const section = page.slice(open.index, end < 0 ? undefined : end);
+  const id = /^#([\w-]+)$/.exec(selector.trim());
+  if (id) return new RegExp(`\\sid\\s*=\\s*["']${id[1]}["']`).test(section);
+  const cls = /^\.([\w-]+)$/.exec(selector.trim());
+  if (cls) return new RegExp(`\\sclass\\s*=\\s*["'][^"']*\\b${cls[1]}\\b`).test(section);
+  const attr = /^\[([\w-]+)/.exec(selector.trim());
+  if (attr) return new RegExp(`\\s${attr[1]}(\\s*=|[\\s>])`).test(section);
+  return true;
+}
+
 // Fields every clip needs before its other rules mean anything.
 export function clipFieldErrors(clip, i) {
   const id = isStr(clip?.id) ? clip.id : `#${i + 1}`;
@@ -937,6 +955,17 @@ export async function checkSources({ html, script = "" }, opts = {}, { fetch: fe
         continue;
       }
       errors.push(...timelineErrors(clip, timeline));
+      // Guest lines ([speaker: …]): each is audio of its own, and each speaker needs its element on the slide.
+      for (const [g, guest] of (Array.isArray(clip.guests) ? clip.guests : []).entries()) {
+        let url;
+        try { url = new URL(guest?.audio, player.manifest).href; } catch { errors.push(MESSAGES.clipField(clip.id, `guest line ${g + 1} needs an audio URL`)); continue; }
+        const got = await fetchCheck(fetchImpl, url, AUDIO);
+        if (got.why) errors.push(MESSAGES.url(clip.id, `guest line ${g + 1} audio`, url, got.why));
+        else await got.response.body?.cancel?.().catch(() => {});
+      }
+      for (const sp of Array.isArray(clip.speakers) ? clip.speakers : []) {
+        if (sp?.selector && !speakerOnSlide(html, clip.id, sp.selector)) warnings.push(MESSAGES.speakerMissing(clip.id, sp.name ?? "a guest", sp.selector));
+      }
     }
   }
   warnings.push(...transitionWarnings(html, script, manifest), ...presenterSizeWarnings(html));

package/src/commands.mjs

@@ -158,28 +158,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 +260,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)");
@@ -347,9 +351,10 @@ commands:
   deck list|stats|open|rm|forward|view
   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 +369,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]
@@ -898,8 +903,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");

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/ops.mjs

@@ -1,5 +1,6 @@
 import { deckPlayer, importPlayerWarning, viewPlayerWarning } from "./deckPlayer.mjs";
 import { zipSync } from "fflate";
+import { SPECIES } from "./species.mjs";
 import { COLOR_KEYS, FONT_PAIRINGS, FONT_ROLES, findPairing, googleFontsUrl } from "./brand.mjs";
 import { MAX_IMPORT_FILE_BYTES, draftArgs, extractFile } from "./brandImport.mjs";
 import { api, client, linkBase, target, uploadBytes as runtimeUploadBytes } from "./runtime.mjs";
@@ -33,6 +34,8 @@ export async function listDecks(opts = {}, { all = false } = {}) {
     viewToggle: d.viewToggle !== false,
     // How the player moves on: auto, slide or step (null: as its HTML says, else auto).
     pace: d.pace ?? null,
+    // Whether each link's AI-readable version (/v/<token>/md) serves (on unless set off).
+    aiReadable: d.aiReadable !== false,
     // false: the deck runs its own player, so view/viewToggle do not apply
     // (null: not known yet, treated as on).
     usesPlayer: d.usesPlayer ?? null,
@@ -53,7 +56,11 @@ export async function activityOverview(opts = {}) {
 // looked up as a token; anything else is a recipient name.
 export const RECIPIENT_ENGAGEMENT_DESCRIPTION =
   "What one recipient watched, per deck link: visits, narration heard (%), replayed / skipped slides, " +
-  "where they dropped off, time per slide, each visit, and forwards. Use it to draft a follow-up: lead " +
+  "the slides they replayed on purpose and how often (summary.slideReplays), whether they watched it again " +
+  "from the start (summary.watchedAgain), a one-line read of both (summary.replayNote), " +
+  "where they dropped off, time per slide, each visit, and forwards. Each link's aiReads lists the AI " +
+  "assistants (ChatGPT, Claude, ...) that read its text version (/v/<token>/md), separately: those are " +
+  "not views. Use it to draft a follow-up: lead " +
   "with what they spent time on, and never tell the recipient they were tracked.";
 export const SHARE_TOKEN = /^[a-f0-9]{16}$/;
 export async function recipientEngagement(opts, who, deck) {
@@ -626,14 +633,16 @@ export async function setDeckForwarding(opts, slug, allowForward) {
 // "slides", "scroll", or null to follow the deck's own HTML again; viewToggle
 // true/false; pace is "auto" (plays itself), "slide" (waits for Next after each
 // slide), "step" (also stops before each [reveal] cue), or null for the deck's
-// own HTML. Any may be left out; all go in one owner-only mutation, so a
-// failure changes none.
+// own HTML. aiReadable true/false: whether each link's AI-readable version
+// (/v/<token>/md) serves (on by default; off is a 404 there). Any may be left
+// out; all go in one owner-only mutation, so a failure changes none.
 // Applies on every link's next load (the route injects it), with no re-release.
 export const DECK_VIEWS = ["slides", "scroll"];
 export const DECK_PACES = ["auto", "slide", "step"];
-export async function setDeckView(opts, slug, { view, viewToggle, pace } = {}) {
+export async function setDeckView(opts, slug, { view, viewToggle, pace, aiReadable } = {}) {
   if (!slug) throw new Error("slug is required");
-  if (view === undefined && viewToggle === undefined && pace === undefined) throw new Error("give a view (slides, scroll or default), a viewToggle and/or a pace (auto, slide, step or default)");
+  const player = view !== undefined || viewToggle !== undefined || pace !== undefined;
+  if (!player && aiReadable === undefined) throw new Error("give a view (slides, scroll or default), a viewToggle, a pace (auto, slide, step or default) and/or aiReadable");
   if (view !== undefined && view !== null && !DECK_VIEWS.includes(view)) throw new Error(`view must be slides, scroll or null (got ${JSON.stringify(view)})`);
   if (pace !== undefined && pace !== null && !DECK_PACES.includes(pace)) throw new Error(`pace must be auto, slide, step or null (got ${JSON.stringify(pace)})`);
   const res = await (await client(opts)).mutation(api.decks.setViewSettings, {
@@ -641,14 +650,17 @@ export async function setDeckView(opts, slug, { view, viewToggle, pace } = {}) {
     ...(view !== undefined ? { view } : {}),
     ...(viewToggle !== undefined ? { viewToggle: !!viewToggle } : {}),
     ...(pace !== undefined ? { pace } : {}),
+    ...(aiReadable !== undefined ? { aiReadable: !!aiReadable } : {}),
   });
-  // Saved either way; a deck on its own player says the setting won't apply.
-  const applies = res?.applies !== false;
+  // Saved either way; a deck on its own player says the setting won't apply
+  // (aiReadable alone always applies: /md doesn't need the player).
+  const applies = !player || res?.applies !== false;
   return {
     slug,
     ...(view !== undefined ? { view } : {}),
     ...(viewToggle !== undefined ? { viewToggle: !!viewToggle } : {}),
     ...(pace !== undefined ? { pace } : {}),
+    ...(aiReadable !== undefined ? { aiReadable: !!aiReadable } : {}),
     applies,
     ...(applies ? {} : { warning: viewPlayerWarning(slug, res?.ownScript ?? null) }),
   };
@@ -1114,6 +1126,22 @@ export async function addPickedAvatar(opts, avatarKey) {
   return (await client(opts)).mutation(api.avatars.addPicked, { avatarKey });
 }
 
+// A drawing that failed on a pet photo (no human face, but Minimoji saw a cat,
+// a dog…): the offer to make that species' avatar instead, or null. The
+// person still picks the face (new_avatar_link with the species).
+export function petOffer(draft) {
+  const s = SPECIES.find((x) => x.id === draft?.suggestedSpecies && x.id !== "human");
+  if (!s) return null;
+  const word = s.label.toLowerCase();
+  return {
+    status: "failed",
+    error: draft.error ?? null,
+    suggestedSpecies: s.id,
+    offer: `That looks like a ${word}. Make a ${word} avatar?`,
+    next: `if they want one: new_avatar_link with species "${s.id}" (a link to pick from the ${word} faces), or \`hyperdecks avatar new --species ${s.id}\``,
+  };
+}
+
 // A face from a photo. With bytes: upload and draw it, then hand back the link
 // where the person approves it (nothing is used before). Without: the link
 // where the person takes a selfie in their browser.
@@ -1129,7 +1157,11 @@ export async function avatarFromPhoto(opts, { bytes, contentType } = {}, { onPro
   onProgress?.("drawing…");
   const draft = await pollUntil(() => c.query(api.avatars.getDraft, { draftId }), (d) => !d || d.status !== "drawing", { timeoutMs: 6 * 60_000 });
   if (!draft) throw new Error("the drawing is gone; run the command again");
-  if (draft.status === "failed") throw new Error(draft.error || "the drawing failed; try another photo");
+  if (draft.status === "failed") {
+    const offer = petOffer(draft);
+    if (offer) return { ...offer, draftId };
+    throw new Error(draft.error || "the drawing failed; try another photo");
+  }
   const link = await c.mutation(api.avatars.createLink, { kind: "review", draftId });
   return { status: "waiting", reviewUrl: link.url, token: link.token, draftId, expiresAt: link.expiresAt };
 }
@@ -1287,7 +1319,11 @@ export async function avatarDraftStatus(opts, draftId) {
   const draft = await c.query(api.avatars.getDraft, { draftId: String(draftId) });
   if (!draft) throw new Error("the drawing is gone; start again with avatar_from_photo");
   if (draft.status === "drawing") return { status: "drawing", draftId };
-  if (draft.status === "failed") throw new Error(draft.error || "the drawing failed; try another photo");
+  if (draft.status === "failed") {
+    const offer = petOffer(draft);
+    if (offer) return { ...offer, draftId };
+    throw new Error(draft.error || "the drawing failed; try another photo");
+  }
   if (draft.status === "added") return { status: "added", draftId, avatarId: draft.avatarId ?? null };
   if (draft.status !== "drawn") throw new Error(`the drawing is in an unexpected state (${draft.status}); start again with avatar_from_photo`);
   const link = await c.mutation(api.avatars.createLink, { kind: "review", draftId });

package/src/release.mjs

@@ -12,13 +12,16 @@
 //      folder: script.md, evidence.md and narration/ stay private);
 //   5. creates one share per --to (paired in order with --email) and prints the URLs.
 import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { zipSync } from "fflate";
 import * as ops from "./ops.mjs";
 import { releasedPresenter, withAvatar } from "./presenter.mjs";
 import { linkBase } from "./runtime.mjs";
-import { checkDeck, deckFiles, deckFolder, resolveDeckDir } from "./check.mjs";
+import { checkDeck, deckFiles, deckFolder, deckPathResolver, resolveDeckDir } from "./check.mjs";
+import { mediaRefs, withMediaPreviews } from "./mediaPreviews.mjs";
+import { bundledFfmpeg, HTTPS_TOO, makePreview } from "./mediaPreviewMake.mjs";
 import { narrate as runNarrate } from "./narrate.mjs";
 
 const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
@@ -54,19 +57,79 @@ export function deckCommit(deckDir) {
 // it brought in, so release can say what came from where.
 // `presenter` (from avatars.presenterFor) puts the owner's avatar on the
 // uploaded page's player tag; the committed index.html is never changed.
-export function releaseBundle(deckDir, presenter = null) {
+// `media` (from mediaPreviewsFor) writes the blur previews onto the uploaded
+// page and adds the posters it made; like the avatar, never to the commit.
+export function releaseBundle(deckDir, presenter = null, media = null) {
   const raw = readFileSync(join(deckDir, "index.html"));
-  const html = presenter ? Buffer.from(withAvatar(raw.toString("utf8"), presenter)) : raw;
+  const page = presenter ? withAvatar(raw.toString("utf8"), presenter) : raw.toString("utf8");
   // check has already refused refs that leave the folder or do not resolve.
-  const found = deckFiles(html.toString("utf8"), deckFolder(deckDir)).files.filter((f) => f.path !== "index.html");
+  const found = deckFiles(page, deckFolder(deckDir)).files.filter((f) => f.path !== "index.html");
+  const html = media ? Buffer.from(withMediaPreviews(page, media.previews).html) : presenter ? Buffer.from(page) : raw;
+  const made = Object.entries(media?.files ?? {});
   const added = {};
   for (const f of found) if (f.from !== "html") (added[f.from] ??= []).push(f.path);
-  if (!found.length) return { bytes: html, filename: "index.html", files: ["index.html"], added };
+  if (!found.length && !made.length) return { bytes: html, filename: "index.html", files: ["index.html"], added };
   const files = { "index.html": html };
   for (const f of found) files[f.path] = readFileSync(join(deckDir, f.path));
+  for (const [path, bytes] of made) files[path] = bytes;
   return { bytes: Buffer.from(zipSync(files)), filename: "deck.zip", htmlFile: "index.html", files: Object.keys(files), added };
 }
 
+// Blur previews (and posters for videos without one) for the media the page
+// shows: local files inside the deck folder and https URLs, read by ffmpeg.
+// Returns { previews, files, failed }: previews keyed by src as written, the
+// poster files to bundle (hd-media/<hash>.jpg), and what could not be read. A
+// preview is an extra, never a reason to stop a release.
+export async function mediaPreviewsFor(deckDir, html, { make = makePreview, ffmpeg } = {}) {
+  const { images, videos } = mediaRefs(html);
+  const previews = {}, files = {}, failed = [];
+  if (!images.length && !videos.length) return { previews, files, failed };
+  let bin = ffmpeg;
+  try {
+    bin ??= await bundledFfmpeg();
+  } catch (e) {
+    return { previews, files, failed: [...images, ...videos].map((src) => ({ src, why: `no ffmpeg (${e.message})` })) };
+  }
+  const inside = deckPathResolver(deckDir);
+  const inputOf = (src) => {
+    if (/^https:\/\//i.test(src)) return src;
+    if (/^[a-z][a-z0-9+.-]*:|^\/\//i.test(src)) return null; // http:, file:, protocol-relative: not read
+    let path;
+    try {
+      path = decodeURIComponent(src.split(/[?#]/)[0]).replace(/^\.\//, "");
+    } catch {
+      return null;
+    }
+    return inside(path) === true ? join(deckDir, path) : null;
+  };
+  const jobs = [...images.map((src) => ({ src, video: false })), ...videos.map((src) => ({ src, video: true }))];
+  const work = async ({ src, video }) => {
+    const input = inputOf(src);
+    if (!input) return failed.push({ src, why: "not a file in the deck folder or an https URL" });
+    try {
+      // A URL input may use https (the user's own machine reads it); a file stays local-only.
+      const p = await make(bin, input, { video, ...(input === src ? { allow: HTTPS_TOO } : {}) });
+      if (p.poster) {
+        const path = `hd-media/${createHash("sha256").update(src).digest("hex").slice(0, 16)}.jpg`;
+        files[path] = p.poster;
+        p.poster = path;
+      }
+      previews[src] = p;
+    } catch (e) {
+      failed.push({ src, why: e.message });
+    }
+  };
+  // A few at a time: each is an ffmpeg process.
+  for (let i = 0; i < jobs.length; i += 4) await Promise.all(jobs.slice(i, i + 4).map(work));
+  return { previews, files, failed };
+}
+
+function logPreviews(log, media) {
+  const n = Object.keys(media.previews).length;
+  if (n) log(`✓ blur previews for ${n} image(s)/video(s)${Object.keys(media.files).length ? `, ${Object.keys(media.files).length} poster(s) made` : ""}`);
+  for (const f of media.failed) log(`  ⚠ no blur preview for ${f.src}: ${f.why}`);
+}
+
 // From the CLI, parse() collects opts.recipients in order (each --email follows
 // its --to); MCP passes the same shape.
 export function recipients(opts) {
@@ -77,7 +140,7 @@ export function recipients(opts) {
 }
 
 export async function release(pos, opts = {}, io = {}) {
-  const { log = (line) => console.log(line), changes = deckChanges, untracked = untrackedFiles, commit = deckCommit, narrate = runNarrate, fetch, cwd, measure, measureFit } = io;
+  const { log = (line) => console.log(line), changes = deckChanges, untracked = untrackedFiles, commit = deckCommit, narrate = runNarrate, previews = mediaPreviewsFor, fetch, cwd, measure, measureFit } = io;
   const deckDir = resolveDeckDir(pos[0], cwd);
   const to = recipients(opts);
 
@@ -97,7 +160,15 @@ export async function release(pos, opts = {}, io = {}) {
   for (const w of checked.warnings) log(`  ⚠ ${w}`);
   for (const [from, paths] of Object.entries(bundle.added)) log(`  +${paths.length} file(s) referenced from ${from}: ${paths.join(", ")}`);
 
-  if (checked.silent) return publish({ opts, io: { log, commit }, deckDir, slug, to, checked, bundle, released: bundle, summary: null });
+  let media;
+  try {
+    media = await previews(deckDir, readFileSync(join(deckDir, "index.html"), "utf8"));
+    logPreviews(log, media);
+  } catch (e) {
+    media = null; // a preview is an extra: the release goes on without them
+    log(`  ⚠ no blur previews: ${e.message}`);
+  }
+  if (checked.silent) return publish({ opts, io: { log, commit }, deckDir, slug, to, checked, bundle, released: releaseBundle(deckDir, null, media), summary: null });
   // Cached slides cost nothing, so this only renders what changed since the commit.
   // Only the options narrate understands: an undefined --slide/--voice key would fail its flag check.
   const narrateOpts = { ...opts, slug };
@@ -118,7 +189,7 @@ export async function release(pos, opts = {}, io = {}) {
   } catch (e) {
     lookupError = ops.errorText(e);
   }
-  const released = presenter ? releaseBundle(deckDir, presenter) : bundle;
+  const released = releaseBundle(deckDir, presenter, media);
   // Say who presents from the page that ships, never from the lookup alone: a
   // resolved face that did not land on the player tag must not be claimed, and
   // a failed lookup is captions only only when the tag names no face of its own.

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.8";
+export const VERSION = "0.9.9";
 const UPLOAD_TIMEOUT_MS = 125_000;
 
 // The app's home. HYPERDECKS_HOST points the prod target's broker and share

package/src/source.mjs

@@ -112,7 +112,7 @@ export async function sourcePush(pos, opts = {}, { log = (line) => console.log(l
   return { slug, rev, files };
 }
 
-const TYPES = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp", ".avif": "image/avif", ".svg": "image/svg+xml", ".mp4": "video/mp4", ".webm": "video/webm", ".woff2": "font/woff2", ".woff": "font/woff" };
+const TYPES = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp", ".avif": "image/avif", ".svg": "image/svg+xml", ".mp4": "video/mp4", ".webm": "video/webm", ".woff2": "font/woff2", ".woff": "font/woff", ".mp3": "audio/mpeg", ".m4a": "audio/mp4", ".json": "application/json" };
 
 export async function assetAdd(pos, opts = {}, { log = (line) => console.log(line), cwd = process.cwd() } = {}) {
   const [slug, from] = pos;
@@ -122,7 +122,7 @@ export async function assetAdd(pos, opts = {}, { log = (line) => console.log(lin
   else {
     const path = resolve(/*turbopackIgnore: true*/ cwd, from);
     const contentType = TYPES[extname(path).toLowerCase()];
-    if (!contentType) throw new Error(`${from}: asset add takes images, video and fonts (${Object.keys(TYPES).join(" ")})`);
+    if (!contentType) throw new Error(`${from}: asset add takes images, video, audio, fonts and JSON (${Object.keys(TYPES).join(" ")})`);
     const c = await client(opts);
     const bytes = readFileSync(path);
     const storageId = await uploadBytes(c, bytes, contentType);