@hypersocial/decks-cli 0.9.8 → 0.9.10

package/src/ops.mjs

@@ -1,8 +1,9 @@
 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";
+import { api, backupLinkUrl, client, linkBase, target, uploadBytes as runtimeUploadBytes } from "./runtime.mjs";
 import {
   bytesFromText,
   isTextAsset,
@@ -20,6 +21,17 @@ export async function whoami(opts = {}) {
 }
 
 // Your own decks. `all: true` lists every deck, for admins only (support tools).
+// The owner link (/d/<slug>, app/d/[slug]): the released deck for its owner
+// only, untracked, with the owner toolbar (Present hides it for a screen
+// share). How an owner or their agent presents or checks a deck; anyone else
+// gets a sign-in notice. QA links are only for testing what a recipient sees.
+// `backupUrl`: the same link on the other app host (null in dev).
+export function ownerLink(opts, slug) {
+  if (!slug) throw new Error("slug is required");
+  const url = `${target(opts).brokerBase}/d/${encodeURIComponent(slug)}`;
+  return { slug, ownerUrl: url, backupUrl: backupLinkUrl(url) };
+}
+
 export async function listDecks(opts = {}, { all = false } = {}) {
   const rows = await (await client(opts)).query(all ? api.decks.listAll : api.decks.listForViewer, {});
   return rows.map((d) => ({
@@ -33,9 +45,14 @@ 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,
+    // Present or check it yourself here (owner-only, untracked); not a link to
+    // send. Null with nothing released, or on someone else's deck (admins' all).
+    ownerUrl: !all && (d.html || d.htmlStorageId || d.hasHtml) ? ownerLink(opts, d.slug).ownerUrl : null,
   }));
 }
 
@@ -53,7 +70,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) {
@@ -561,6 +582,8 @@ export async function listShares(opts, slug) {
     // viewer who forwarded it. Rows come back with each link's forwards after it.
     allowForward: !!r.allowForward,
     allowForwardOverride: r.allowForwardOverride ?? null,
+    // The link's own pace (auto, slide, step); null = it follows the deck.
+    pace: r.pace ?? null,
     parentToken: r.parentToken ?? null,
     forwardedBy: r.forwardedBy ?? null,
     probablyForwarded: !!r.probablyForwarded,
@@ -577,6 +600,11 @@ export async function createShare(opts, fields) {
   if (fields.note) args.note = fields.note;
   if (fields.requireEmail) args.requireEmail = true;
   if (fields.allowForward !== undefined) args.allowForward = !!fields.allowForward;
+  // The link's own pace; absent = it follows the deck's.
+  if (fields.pace !== undefined) {
+    if (!DECK_PACES.includes(fields.pace)) throw new Error(`pace must be auto, slide or step (got ${JSON.stringify(fields.pace)})`);
+    args.pace = fields.pace;
+  }
   if (fields.expires) {
     const t = Date.parse(fields.expires);
     if (Number.isNaN(t)) throw new Error(`expires must be an ISO date; got ${fields.expires}`);
@@ -626,14 +654,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 +671,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 +1147,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 +1178,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 };
 }
@@ -1159,8 +1212,9 @@ export async function presenterFor(opts, slug, voice) {
 }
 
 // The same answer as presenterFor plus who presents in words: { presenter, who }.
-export async function presenterWithReason(opts, slug, voice) {
-  return (await client(opts)).query(api.avatars.presenterWithReason, { slug, ...(voice ? { voice: String(voice) } : {}) });
+// `draft`: also answer for a deck not narrated yet, from the voice its narrate would use.
+export async function presenterWithReason(opts, slug, voice, { draft = false } = {}) {
+  return (await client(opts)).query(api.avatars.presenterWithReason, { slug, ...(voice ? { voice: String(voice) } : {}), ...(draft ? { draft: true } : {}) });
 }
 
 // ---- narrators (convex/narrators.ts) ------------------------------------------
@@ -1287,7 +1341,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/play.mjs

@@ -12,7 +12,7 @@ import { basename, join, relative } from "node:path";
 import { playerScript, sectionIds } from "./checkRules.mjs";
 import { resolveDeckDir } from "./check.mjs";
 import * as ops from "./ops.mjs";
-import { playsCaptionsOnly, presenterLine, withAvatar } from "./presenter.mjs";
+import { playsCaptionsOnly, presenterLine, withNarrator } from "./presenter.mjs";
 import { serveSource } from "./preview-capture.mjs";
 import { openBrowser } from "./runtime.mjs";
 
@@ -88,7 +88,7 @@ export async function startPlay(pos, opts = {}, { log = (line) => console.log(li
   const html = readFileSync(file, "utf8");
 
   const { presenter, who } = await lookUpPresenter(opts, { slug, path, html, log });
-  const page = presenter ? withAvatar(html, presenter) : html;
+  const page = withNarrator(html, presenter, who);
   sayWhoPresents({ html, page, presenter, who, log });
   // --voice names the voice it was narrated in, so there is nothing to compare it to.
   if (who && !opts.voice) await warnIfScriptChanged(opts, { slug, deckDir, path, html, who, log });

package/src/presenter.mjs

@@ -3,8 +3,10 @@
 // captions-only (data-presenter="none"); at release, when the owner has an
 // avatar, its player tag gets that face instead. Shared by both releases
 // (convex/deckSources.ts, release.mjs), `hyperdecks play` and the /p draft
-// preview, so all rewrite the tag the same way; only a release stores it. A tag that already names a presenter (D.A.S.H.
-// on a character-voice deck, or one set by hand) is left alone.
+// preview, so all rewrite the tag the same way; only a release stores it. A tag
+// that already names a presenter by hand is left alone. deck new, deck narrator
+// and narrate write the narrator's face into the file itself (writeNarratorFace),
+// marked, so a draft on disk shows its face and release still follows the narrator.
 
 // D.A.S.H.'s face: the head doc and still that ship with the player. A deck
 // narrated in its character voice gets this face at release, even when the
@@ -59,36 +61,98 @@ export function playsCaptionsOnly(html) {
   return !!found && !tagFace(found.tag);
 }
 
+// Who wrote the tag's face: data-presenter-from="narrator" is a face the CLI
+// (deck new, deck narrator, narrate) wrote from the deck's narrator,
+// so it follows the narrator at release and in play; "captions-only" is captions
+// only on purpose (deck new --captions-only, deck narrator none). No marker: the
+// tag is as its author wrote it, and a face there is hand-set. The player ignores it.
+export const PRESENTER_FROM = "data-presenter-from";
+const FACE_ATTRS = ["data-presenter", "data-avatar", "data-presenter-image", PRESENTER_FROM];
+const attrRe = (name) => new RegExp(`\\s${name}\\s*=\\s*(?:"[^"]*"|'[^']*'|[^\\s"'=<>\`]+)`);
+
+// The tag with its face attributes replaced by `face` (an ordered [name, value] list), in place of
+// the first one it had (else before the closing >), leaving every other attribute as written.
+function setFace(tag, face) {
+  const at = FACE_ATTRS.map((n) => attrRe(n).exec(tag)).filter(Boolean).sort((a, b) => a.index - b.index)[0];
+  let next = tag;
+  for (const n of FACE_ATTRS) next = next.replace(attrRe(n), at && attrRe(n).exec(tag)?.index === at.index ? "\u0000" : "");
+  const text = face.map(([n, v]) => ` ${n}="${attr(v)}"`).join("");
+  return next.includes("\u0000") ? next.replace("\u0000", text) : next.replace(/\s*\/?>$/, (end) => `${text}${end}`);
+}
+
+const replaceTag = (html, found, tag) => (tag === found.tag ? html : html.slice(0, found.index) + tag + html.slice(found.index + found.tag.length));
+
 // html with the player tag set to present `avatarUrl` (the /avatar/<token> doc
 // the player loads) and `imageUrl` (its still, for thumbnails and no-WebGL), or
 // html unchanged when there is no such tag, the tag already shows a face, or it
 // names a non-empty data-avatar of its own (set by hand: left alone even beside "none").
 // Anything else the player would play captions only (data-presenter none or
-// missing, head with no data-avatar, static with no still) gets the face.
+// missing, head with no data-avatar, static with no still) gets the face. A face
+// the CLI wrote from the narrator (data-presenter-from="narrator") is replaced by
+// this one, so a narrator changed since follows; captions only on purpose stays.
 export function withAvatar(html, { avatarUrl, imageUrl }) {
   const found = playerTag(html);
   if (!found) return html;
-  const { tag, index } = found;
+  const { tag } = found;
+  const from = value(tag, PRESENTER_FROM);
+  if (from === "captions-only") return html;
+  if (from === "narrator") return replaceTag(html, found, setFace(tag, narratorFace({ avatarUrl, imageUrl })));
   if (tagFace(tag) || value(tag, "data-avatar")) return html;
   const image = imageUrl && value(tag, "data-presenter-image") === null ? ` data-presenter-image="${attr(imageUrl)}"` : "";
   const face = ` data-presenter="head" data-avatar="${attr(avatarUrl)}"${image}`;
-  const named = /\sdata-presenter\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'=<>`]+)/;
+  const named = attrRe("data-presenter");
   const next = named.test(tag) ? tag.replace(named, face) : tag.replace(/\s*\/?>$/, (end) => `${face}${end}`);
-  return html.slice(0, index) + next + html.slice(index + tag.length);
+  return replaceTag(html, found, next);
+}
+
+// The page as its narrator presents it, for play, /p and both releases: the
+// resolved face put on (withAvatar), or, when the narration is on record and
+// resolves to no face (`who.face` null: narrator none, faces off, a face
+// removed), a face the CLI wrote from an earlier narrator taken off again, so
+// it never shows someone who no longer presents. A hand-set face is kept.
+export function withNarrator(html, presenter, who) {
+  if (presenter) return withAvatar(html, presenter);
+  const found = playerTag(html);
+  if (!who || who.face || !found || value(found.tag, PRESENTER_FROM) !== "narrator") return html;
+  return replaceTag(html, found, setFace(found.tag, [["data-presenter", "none"], [PRESENTER_FROM, "narrator"]]));
+}
+
+const narratorFace = ({ avatarUrl, imageUrl }) => [
+  ["data-presenter", "head"], ["data-avatar", avatarUrl], ...(imageUrl ? [["data-presenter-image", imageUrl]] : []), [PRESENTER_FROM, "narrator"],
+];
+
+// Write the narrator's face into the page as a file on disk plays it: `face`
+// ({ avatarUrl, imageUrl }) as a marked head, or null for captions only on
+// purpose. For deck new, deck narrator and narrate, so a draft opened with any
+// static server shows what play and release show. A face set by hand (a face or
+// data-avatar with no marker) is left alone. Returns { html, wrote }, and with
+// wrote false a `why`.
+export function writeNarratorFace(html, face) {
+  const found = playerTag(html);
+  if (!found) return { html, wrote: false, why: "the page has no live player tag" };
+  const { tag } = found;
+  if (!value(tag, PRESENTER_FROM) && (tagFace(tag) || value(tag, "data-avatar"))) {
+    return { html, wrote: false, why: "the player tag names a face of its own (set by hand), so it is left as written" };
+  }
+  const next = setFace(tag, face ? narratorFace(face) : [["data-presenter", "none"], [PRESENTER_FROM, "captions-only"]]);
+  return { html: replaceTag(html, found, next), wrote: true };
 }
 
 // What is wrong with the player tag's presenter as written, for check: null, or
 // { kind, presenter }. "unfilled": it asks for a face (head or static) but names
 // none, so it plays captions only until release fills it in. "kept": it has a
 // data-avatar the player ignores (data-presenter="none"), and release leaves it.
-// A plain "none" or no data-presenter is not an issue: release adds the face.
+// "captions": data-presenter none or missing, so a file opened as written (a
+// static server, the screenshot pass) plays captions only though release adds a
+// face. Captions only on purpose (data-presenter-from="captions-only") is not an issue.
 export function presenterTagIssue(html) {
   const found = playerTag(html);
   if (!found || tagFace(found.tag)) return null;
   const presenter = value(found.tag, "data-presenter");
   if (value(found.tag, "data-avatar")) return { kind: "kept", presenter };
   if (presenter === "head" || presenter === "static") return { kind: "unfilled", presenter };
-  return null;
+  if (value(found.tag, PRESENTER_FROM) === "captions-only") return null;
+  return { kind: "captions", presenter };
 }
 
 // Why a resolved face did not land on the page: withAvatar leaves a tag with
@@ -109,7 +173,7 @@ function keptOutReason(html) {
 // Both releases use it: release.mjs and convex/deckSources.ts.
 export const TAG_FACE = "the face set on the player tag";
 export function releasedPresenter(html, presenter, who, { lookupError } = {}) {
-  const page = presenter ? withAvatar(html, presenter) : html;
+  const page = withNarrator(html, presenter, who);
   const captions = (reason) => ({ page, line: `⚠ releasing captions only: ${reason}`, summary: who ? { ...who, face: null, reason } : null });
   const shown = presentedFace(page);
   if (shown) {

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 { releasedPresenter, withNarrator } 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}$/;
@@ -53,20 +56,81 @@ export function deckCommit(deckDir) {
 // turn (deckFiles). `added` maps each bundled script or stylesheet to the files
 // 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) {
+// uploaded page's player tag; the committed index.html is never changed. `who`
+// (narrate's presenter summary) takes a CLI-written face off when nobody presents now.
+// `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, who = null) {
   const raw = readFileSync(join(deckDir, "index.html"));
-  const html = presenter ? Buffer.from(withAvatar(raw.toString("utf8"), presenter)) : raw;
+  const page = withNarrator(raw.toString("utf8"), presenter, who);
   // 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) : page !== raw.toString("utf8") ? 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 +141,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,13 +161,21 @@ 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 };
   for (const k of ["slide", "json", "dry-run", "to", "email", "recipients"]) delete narrateOpts[k];
   if (narrateOpts.voice === undefined) delete narrateOpts.voice;
-  const job = await narrate([deckDir], narrateOpts, { log });
+  const job = await narrate([deckDir], narrateOpts, { log, writeFace: false });
   if (!job?.manifestUrl) throw new Error(`narration finished without a manifest (${job?.notice || "no manifest URL"}); fix it and release again`);
   const after = changes(deckDir);
   if (after) {
@@ -118,7 +190,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, job.presenter);
   // 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.10";
 const UPLOAD_TIMEOUT_MS = 125_000;
 
 // The app's home. HYPERDECKS_HOST points the prod target's broker and share

package/src/scaffold.mjs

@@ -1,21 +1,25 @@
-// hyperdecks deck new <slug> "<title>" --narrated [--layouts hero,product,…] [--presenter-style stage|bubble|glass|corner] [--dir <path>]
+// hyperdecks deck new <slug> "<title>" --narrated [--layouts hero,product,…] [--presenter-style stage|bubble|glass|corner] [--captions-only] [--dir <path>]
 //
 // Writes decks/<slug>/ (or --dir) from the packaged templates: index.html (eight
 // slides for the hosted player/v1, or one slide per --layouts entry from
 // templates/layouts/), script.md (the narration) and evidence.md (where each
 // fact comes from), then registers the deck as a draft you own so narrate can
-// render into it.
-import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+// render into it. The player tag gets the narrator's face (the account's default
+// narrator, else D.A.S.H.), so the file plays with a face however it is opened;
+// --captions-only writes data-presenter="none" on purpose instead.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import * as ops from "./ops.mjs";
 import { PRESENTER_STYLES } from "./checkRules.mjs";
 import { LAYOUTS, NARRATED_FILES, assembleLayoutDeck, fillTemplate, parseLayouts } from "./layouts.mjs";
 import { applyBrand, brandForNewDeck, brandSummary } from "./brand.mjs";
+import { writeDraftFace } from "./draftFace.mjs";
+import { DASH_PRESENTER, writeNarratorFace } from "./presenter.mjs";
 
 export { LAYOUTS, NARRATED_FILES, assembleLayoutDeck, fillTemplate, parseLayouts, readLayout } from "./layouts.mjs";
 
 const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
-const USAGE = 'usage: deck new <slug> "<title>" --narrated [--layouts hero,product,number,closer] [--presenter-style <stage|bubble|glass|corner>] [--no-brand] [--dir <path>]';
+const USAGE = 'usage: deck new <slug> "<title>" --narrated [--layouts hero,product,number,closer] [--presenter-style <stage|bubble|glass|corner>] [--captions-only] [--no-brand] [--dir <path>]';
 
 export async function deckNew(pos, opts = {}, { log = (line) => console.log(line), cwd = process.cwd() } = {}) {
   const [slug, title] = pos;
@@ -46,7 +50,24 @@ export async function deckNew(pos, opts = {}, { log = (line) => console.log(line
     rmSync(dir, { recursive: true, force: true });
     throw new Error(`deck ${slug} is registered but its files could not be written (${e.message}); remove the draft with \`hyperdecks deck rm ${slug}\` and run deck new again`);
   }
+  // The face goes into the file now the deck is registered (the server answers whose).
+  const htmlPath = join(/*turbopackIgnore: true*/ dir, "index.html");
+  const lines = [];
+  let presenter;
+  if (opts["captions-only"]) {
+    writeFileSync(htmlPath, writeNarratorFace(readFileSync(htmlPath, "utf8"), null).html);
+    // The server too, so release, play and /p agree the deck has no face.
+    try {
+      await ops.setDeckNarrator(opts, slug, "none");
+      lines.push("  presenter: captions only (--captions-only), written to index.html and set on the deck");
+    } catch (e) {
+      lines.push(`⚠ presenter: captions only written to index.html, but the deck could not be set to none (${e.message}): run \`hyperdecks deck narrator ${slug} none\``);
+    }
+    presenter = { face: null };
+  } else {
+    presenter = await writeDraftFace(opts, slug, htmlPath, { log: (line) => lines.push(line), fallback: DASH_PRESENTER });
+  }
   const summary = brandSummary(brand, readError);
-  log(`✓ created deck "${slug}" → ${dir}\n  files: ${Object.keys(NARRATED_FILES).join(", ")}\n  brand: ${summary.error ? `could not read it (${summary.error}); template look` : summary.applied.length ? summary.applied.join(", ") : "none applied (hyperdecks brand set)"}\n  next:  hyperdecks narrate ${dir} --dry-run`);
-  return { slug, title, dir, files: Object.keys(NARRATED_FILES), brand: summary };
+  log(`✓ created deck "${slug}" → ${dir}\n  files: ${Object.keys(NARRATED_FILES).join(", ")}\n  brand: ${summary.error ? `could not read it (${summary.error}); template look` : summary.applied.length ? summary.applied.join(", ") : "none applied (hyperdecks brand set)"}\n${lines.map((l) => (l.startsWith(" ") ? l : `  ${l}`)).join("\n")}\n  next:  hyperdecks narrate ${dir} --dry-run`);
+  return { slug, title, dir, files: Object.keys(NARRATED_FILES), brand: summary, presenter: presenter.face ?? null };
 }

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);