@hypersocial/decks-cli 0.9.7 → 0.9.9

package/src/guide.mjs

@@ -29,7 +29,7 @@ export function skillSection(skill, topic) {
 function layoutsTopic() {
   const rows = LAYOUTS.map((name) => {
     const { meta } = readLayout(name);
-    return [`### ${name}`, meta.summary, meta.use && `Use: ${meta.use}`, meta.slot && `Slots: ${meta.slot}`, meta.cues && `Cues: ${meta.cues}`].filter(Boolean).join("\n");
+    return [`### ${name}`, meta.summary, meta.use && `Use: ${meta.use}`, meta.slot && `Slots: ${meta.slot}`, meta.nopresenter && `Without a presenter: ${meta.nopresenter}`, meta.cues && `Cues: ${meta.cues}`].filter(Boolean).join("\n");
   });
   return `# Layouts\n\nPass any of these, in order, as new_deck's \`layouts\` (repeat one for more of the same: number, number gives slides number and number-2).\n\n${rows.join("\n\n")}`;
 }

package/src/init.mjs

@@ -17,7 +17,7 @@ import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import * as ops from "./ops.mjs";
 import { ANSWER_MAX, DASH_AVATAR, FIRST_DECK_LAYOUTS, cleanAnswer, fillFirstDeck, firstDeckCopy, firstDeckSlug } from "./firstDeck.mjs";
-import { agentTable, api, chooseAgents, client, CRED_DIR, installHyperdecksSkill, login as runLogin, openBrowser, target } from "./runtime.mjs";
+import { agentTable, api, chooseAgents, client, CRED_DIR, installHyperdecksSkill, linkBase, login as runLogin, openBrowser, target } from "./runtime.mjs";
 import { READING_PASSAGE, voiceClone as runVoiceClone } from "./voice.mjs";
 import { assembleLayoutDeck, deckNew as runDeckNew } from "./scaffold.mjs";
 import { narrate as runNarrate } from "./narrate.mjs";
@@ -450,9 +450,13 @@ async function presenterStep(base, opts, { interactive, ask, log, sub, avatars,
   }
 }
 
+// decks:get answers only for decks the caller owns, so whether the slug is
+// taken at all comes from slugTaken.
 async function deckOwnedBy(base, slug, who) {
-  const deck = await (await client(base)).query(api.decks.get, { slug });
-  return deck ? { exists: true, mine: deck.ownerId === who.subject } : { exists: false, mine: false };
+  const c = await client(base);
+  if (!(await c.query(api.decks.slugTaken, { slug }))) return { exists: false, mine: false };
+  const deck = await c.query(api.decks.get, { slug });
+  return { exists: true, mine: !!deck && deck.ownerId === who.subject };
 }
 
 async function scaffoldStep(base, opts, { state, who, voice, presenter, interactive, ask, deckNew, cwd, home, random, sub, log, save }) {
@@ -544,7 +548,7 @@ async function releaseStep(base, opts, state, { release, sub, save, fetch }) {
   // A run killed after release made its link but before init.json recorded it.
   const mine = !state.releasedAt && shares.find((s) => s.qa && s.recipient === "Me" && s.enabled);
   if (mine) {
-    const url = `${target(base).shareBase}/v/${mine.token}`;
+    const url = `${await linkBase(base)}/v/${mine.token}`;
     save({ releasedAt: new Date().toISOString(), shareUrl: url, shareToken: mine.token });
     return step("release", "done", `released: ${url}`);
   }

package/src/layouts.mjs

@@ -20,7 +20,7 @@ export function fillTemplate(file, { slug, title, presenterStyle }) {
 }
 
 // One layout file: a leading comment of `key: value` lines (layout, summary,
-// use, slot, presenter, cues, script), its <style> and its <section>.
+// use, slot, presenter, nopresenter, cues, script), its <style> and its <section>.
 export function readLayout(name) {
   const text = packageText(`templates/layouts/${name}.html`);
   const head = /^<!--([\s\S]*?)-->/.exec(text);

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,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, target, uploadBytes as runtimeUploadBytes } from "./runtime.mjs";
+import { api, client, linkBase, target, uploadBytes as runtimeUploadBytes } from "./runtime.mjs";
 import {
   bytesFromText,
   isTextAsset,
@@ -19,8 +20,9 @@ export async function whoami(opts = {}) {
   return (await client(opts)).query(api.decks.whoami, {});
 }
 
-export async function listDecks(opts = {}) {
-  const rows = await (await client(opts)).query(api.decks.listForViewer, {});
+// Your own decks. `all: true` lists every deck, for admins only (support tools).
+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) => ({
     slug: d.slug,
     title: d.title,
@@ -30,6 +32,10 @@ export async function listDecks(opts = {}) {
     // How it opens (null: as its HTML says) and whether viewers may switch.
     view: d.view ?? null,
     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,
@@ -50,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) {
@@ -264,7 +274,11 @@ export async function ownedDeck(opts, slug) {
   const c = await client(opts);
   const [deck, me] = await Promise.all([c.query(api.decks.get, { slug }), c.query(api.decks.whoami, {})]);
   if (!me) throw new Error("not logged in: run `hyperdecks login` first");
-  if (!deck) throw new Error(`deck not found: ${slug} (register it first, or pass --slug)`);
+  if (!deck) {
+    // get answers only for your own decks; say so when the slug is someone else's.
+    if (await c.query(api.decks.slugTaken, { slug })) throw new Error(`forbidden: ${slug} is not your deck`);
+    throw new Error(`deck not found: ${slug} (register it first, or pass --slug)`);
+  }
   if (!me.isAdmin && deck.ownerId !== me.subject) throw new Error(`forbidden: ${slug} is not your deck`);
   return deck;
 }
@@ -288,7 +302,7 @@ export const VIDEO_RECIPIENT = "Video viewers";
 export async function videoShareLink(opts, slug) {
   const live = (await listShares(opts, slug)).find((s) => s.recipient === VIDEO_RECIPIENT && s.enabled && !s.qa && !s.archived && !s.requireEmail && (s.expiresAt == null || s.expiresAt > Date.now()) && (s.viewLimit == null || s.opens < s.viewLimit));
   const token = live?.token ?? (await createShare(opts, { slug, recipient: VIDEO_RECIPIENT })).token;
-  return `${target(opts).shareBase}/v/${token}`;
+  return `${await linkBase(opts)}/v/${token}`;
 }
 
 // `export --video --upload`: file the MP4 with the deck's exports (30 days).
@@ -428,10 +442,24 @@ export async function checkNarrationJob(opts, jobId) {
   return (await client(opts)).query(api.narration.getJob, { jobId: String(jobId) });
 }
 
+// Your own voices (what clone, rename and delete act on).
 export async function listVoices(opts = {}) {
   return (await client(opts)).query(api.voices.listVoices, {});
 }
 
+// Every voice you can narrate with: yours, then the built-in ones (builtin: true,
+// id stock:<id>), which any account may use. What list_voices shows.
+export async function listAllVoices(opts = {}) {
+  const c = await client(opts);
+  try {
+    return await c.query(api.voices.listVoices, { builtin: true });
+  } catch (e) {
+    // A backend from before built-in voices refuses the argument: your own voices, then.
+    if (!/builtin|extra field|Validator/i.test(errorText(e))) throw e;
+    return c.query(api.voices.listVoices, {});
+  }
+}
+
 // ---- voice cloning (convex/voices.ts) ---------------------------------------
 
 // The text of a backend error: ConvexError data (production redacts the rest), else the message.
@@ -603,25 +631,36 @@ export async function setDeckForwarding(opts, slug, allowForward) {
 
 // How a deck opens in the player and whether viewers may switch: view is
 // "slides", "scroll", or null to follow the deck's own HTML again; viewToggle
-// true/false. Either may be left out; both go in one owner-only mutation, so a
-// failure changes neither.
+// 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. 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 async function setDeckView(opts, slug, { view, viewToggle } = {}) {
+export const DECK_PACES = ["auto", "slide", "step"];
+export async function setDeckView(opts, slug, { view, viewToggle, pace, aiReadable } = {}) {
   if (!slug) throw new Error("slug is required");
-  if (view === undefined && viewToggle === undefined) throw new Error("give a view (slides, scroll or default) and/or a viewToggle");
+  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, {
     slug,
     ...(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) }),
   };
@@ -631,7 +670,7 @@ export async function setDeckView(opts, slug, { view, viewToggle } = {}) {
 // upsert would otherwise reset your own live deck to a draft and rename it.
 export async function createDeck(opts, { slug, title }) {
   const c = await client(opts);
-  if (await c.query(api.decks.get, { slug })) throw new Error(`deck ${slug} already exists; pick another slug`);
+  if (await c.query(api.decks.slugTaken, { slug })) throw new Error(`deck ${slug} already exists; pick another slug`);
   await c.mutation(api.decks.upsert, { slug, title, status: "draft" });
   return { slug, title, status: "draft" };
 }
@@ -1087,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.
@@ -1102,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 };
 }
@@ -1146,7 +1205,7 @@ export async function listNarrators(opts = {}) {
     default: out.defaultId,
     ...(out.unpickedVoice ? { note: `no default narrator yet: decks narrate in your voice "${out.unpickedVoice}"` } : {}),
     narrators: out.narrators.map((n) => ({ id: n.id, name: n.name, spokenName: n.spokenName ?? null, isDefault: n.isDefault, builtin: n.builtin, face: n.face?.name ?? null, voice: n.voice?.name ?? null, voiceReady: !!n.voice?.ready })),
-    voices: out.voices.map((x) => ({ id: x.ref, name: x.name, status: x.status, character: x.character, narrators: x.narrators })),
+    voices: out.voices.map((x) => ({ id: x.ref, name: x.name, status: x.status, character: x.character, builtin: !!x.builtin, narrators: x.narrators })),
   };
 }
 
@@ -1188,7 +1247,8 @@ export async function removeNarrator(opts, ref) {
   return { ...(await (await client(opts)).mutation(api.narrators.remove, { narrator: n.id })), id: n.id };
 }
 
-// voice: one of your ready voices (name or id) or dash.
+// voice: one of your ready voices (name or id), a built-in voice (name or
+// stock:<id>, list_voices), or dash.
 export async function setNarratorVoice(opts, ref, voice) {
   if (!voice) throw new Error("usage: narrator voice <narrator> <voice>");
   const n = await findNarrator(opts, ref);
@@ -1259,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/presenter.mjs

@@ -12,32 +12,118 @@
 export const DASH_AVATAR = "https://hyperdecks.ai/player/v1/dash-avatar.json";
 export const DASH_PRESENTER = Object.freeze({ avatarUrl: DASH_AVATAR, imageUrl: "https://hyperdecks.ai/avatars/dash.png" });
 
-const PLAYER_TAG = /<script\b[^>]*\bsrc="[^"]*\/player\/v1\/player\.js"[^>]*>/i;
+const PLAYER_TAG = /<script\b[^>]*\bsrc="[^"]*\/player\/v1\/player\.js"[^>]*>/gi;
 
 const attr = (s) => String(s).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
 
-// Whether this tag plays captions only: data-presenter="none", or no presenter
-// at all (the player's default when there is no data-presenter-image either).
-const noPresenter = (tag) => /\sdata-presenter="none"/.test(tag) || (!/\sdata-presenter=/.test(tag) && !/\sdata-presenter-image=/.test(tag));
+// The live player tag: the first one outside an HTML comment (a commented-out
+// copy is not what plays), with where it starts. check's playerScript reads it
+// the same way (closed comments only, so a stray "<!--" in a script hides nothing).
+function playerTag(html) {
+  const comments = [...html.matchAll(/<!--[\s\S]*?-->/g)].map((m) => [m.index, m.index + m[0].length]);
+  for (const m of html.matchAll(PLAYER_TAG)) {
+    if (!comments.some(([a, b]) => m.index >= a && m.index < b)) return { tag: m[0], index: m.index };
+  }
+  return null;
+}
+
+const value = (tag, name) => {
+  const m = new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s"'=<>\`]+))`).exec(tag);
+  return m ? (m[1] ?? m[2] ?? m[3]) : null;
+};
+
+// The face this tag shows, decided as packages/player/player.js does: data-presenter
+// head|static|none, else static when there is a still, else none. head draws
+// data-avatar (and falls back to the still without one); static draws the
+// still. Null: the deck plays the voice and captions with no face.
+function tagFace(tag) {
+  const presenter = value(tag, "data-presenter");
+  const avatarUrl = value(tag, "data-avatar") || null;
+  const imageUrl = value(tag, "data-presenter-image") || null;
+  const mode = ["head", "static", "none"].includes(presenter) ? presenter : imageUrl ? "static" : "none";
+  if (mode === "head" && (avatarUrl || imageUrl)) return { avatarUrl, imageUrl };
+  if (mode === "static" && imageUrl) return { avatarUrl: null, imageUrl };
+  return null;
+}
+
+// The face the page's player shows ({ avatarUrl, imageUrl }, either may be
+// null), or null when it plays captions only or has no player tag.
+export function presentedFace(html) {
+  const found = playerTag(html);
+  return found ? tagFace(found.tag) : null;
+}
 
-// Whether the page's player tag names nobody, so without a face it has captions only.
+// Whether the page's player tag shows no face, so it has captions only.
 export function playsCaptionsOnly(html) {
-  const tag = PLAYER_TAG.exec(html)?.[0];
-  return !!tag && !/\sdata-avatar=/.test(tag) && noPresenter(tag);
+  const found = playerTag(html);
+  return !!found && !tagFace(found.tag);
 }
 
 // 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 or it already has a presenter.
+// 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.
 export function withAvatar(html, { avatarUrl, imageUrl }) {
-  const tag = PLAYER_TAG.exec(html)?.[0];
-  if (!tag || /\sdata-avatar=/.test(tag)) return html;
-  if (!noPresenter(tag)) return html;
-  const none = /\sdata-presenter="none"/.test(tag);
-  const image = imageUrl && !/\sdata-presenter-image=/.test(tag) ? ` data-presenter-image="${attr(imageUrl)}"` : "";
+  const found = playerTag(html);
+  if (!found) return html;
+  const { tag, index } = found;
+  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 next = none ? tag.replace(/\sdata-presenter="none"/, face) : tag.replace(/>$/, `${face}>`);
-  return html.replace(tag, () => next);
+  const named = /\sdata-presenter\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'=<>`]+)/;
+  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);
+}
+
+// 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.
+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;
+}
+
+// Why a resolved face did not land on the page: withAvatar leaves a tag with
+// its own data-avatar alone, and a page with no live player tag has nowhere to put it.
+function keptOutReason(html) {
+  const found = playerTag(html);
+  if (!found) return "the page has no live player tag to put the face on";
+  const mode = value(found.tag, "data-presenter");
+  return `the player tag names its own data-avatar, but data-presenter=${mode === null ? " is missing" : `"${mode}"`} so it plays no face, and release leaves a hand-set data-avatar alone: set data-presenter="head", or remove data-avatar`;
+}
+
+// What a release says about the face, from the page as written (`html`), the
+// face it puts on (`presenter`, from avatars.presenterFor; null for none), who
+// the backend says presents (`who`: { narrator, voice, face, reason }) and, when
+// the face lookup itself failed, `lookupError`. Returns the page that ships, a
+// line for the terminal and the summary to report: "presented by" only when
+// that page shows a face, and with no resolved face on it, the tag's own.
+// 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 captions = (reason) => ({ page, line: `⚠ releasing captions only: ${reason}`, summary: who ? { ...who, face: null, reason } : null });
+  const shown = presentedFace(page);
+  if (shown) {
+    // Left as written, with no resolved face or another one: whatever the tag names is what shows.
+    if (page === html && shown.avatarUrl !== presenter?.avatarUrl) {
+      return { page, line: `✓ presented by ${TAG_FACE} (${shown.avatarUrl ? "data-avatar" : "data-presenter-image"})`, summary: who ? { ...who, face: TAG_FACE } : null };
+    }
+    return { page, line: `✓ presented by ${who?.face ?? "your avatar"}`, summary: who ?? null };
+  }
+  if (lookupError) return captions(`could not look up your avatar (${lookupError}); release again to try once more`);
+  if (presenter) return captions(keptOutReason(page));
+  if (who && !who.face) return { page, line: `⚠ releasing captions only: ${who.reason ?? "no face"}`, summary: who };
+  if (who?.face) return captions(`no face for "${who.face}" came back to put on the player tag`);
+  return { page, line: "", summary: null };
 }
 
 // One line for who presents a deck, from narrate's or release's `presenter`