@hypersocial/decks-cli 0.9.7 → 0.9.9

package/README.md

@@ -64,7 +64,7 @@ share list <slug> [--json]
 share on|off <token>
 share mute|unmute <token>
 share rm <token>
-share url <token>
+share url <token> [--backup]
 
 recipient archive|unarchive <name>
 import <html-or-zip-or-url> --slug <slug> [--title title] [--status draft|live|archived]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypersocial/decks-cli",
-  "version": "0.9.7",
+  "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 | `hyperdecks deck view <slug> [slides\|scroll\|default] [--toggle on\|off]` | `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` |
@@ -169,7 +169,15 @@ HTML says. Viewers get a slides/scroll toggle in the player, remembered per
 link, unless you turn it off (`--toggle off`, `viewToggle: false`). A viewer
 who already switched keeps their own choice while the toggle is on; turn the
 toggle off to make every viewer see the deck's view.
-`deck list --json` / `list_decks` and `deck stats` / `deck_stats` show both.
+Pace is the third: `--pace auto` (`pace: "auto"`, the default) plays itself,
+`slide` waits for Next (the Continue pill, →, a swipe) after each slide's
+narration, and `step` also stops the narration before each `[reveal]` cue,
+so a slide's reveals are the steps the viewer clicks through: group what
+belongs together at one word, so each stop is a meaningful step. Viewers can
+switch pace (and slides/scroll) in the player's Preferences, in its top bar
+(remembered per link); a video export always plays straight through. Pace
+waits apply side to side (slides) only: scroll keeps its own flow.
+`deck list --json` / `list_decks` and `deck stats` / `deck_stats` show all three.
 
 ### 1. Ground it in the user's own material
 
@@ -258,6 +266,18 @@ The deck contract (`check` enforces or warns on each line):
 <!-- topic: presenter -->
 #### Which presenter style
 
+**Who presents is set at release; leave the tag alone.** `deck new --narrated`
+writes `data-presenter="none"` on the player tag, and `release` (and
+`release_deck`) puts the narrator's face on the copy it publishes: your own
+narrator's avatar, or D.A.S.H.'s live head for a deck in D.A.S.H.'s voice. It
+says `presented by …` only when the published page has that face; otherwise
+it warns `releasing captions only` with the reason. To pick the face by hand,
+set both attributes: `data-presenter="head" data-avatar="…"`. D.A.S.H.'s is
+`data-presenter="head" data-avatar="https://hyperdecks.ai/player/v1/dash-avatar.json"`
+(it loads from any host). `data-presenter="head"` with no `data-avatar` plays
+captions only, and so does a `data-avatar` beside `data-presenter="none"`.
+`check` warns on both, and `release` leaves a hand-set `data-avatar` alone.
+
 Set the deck's on the player tag (`data-presenter-style="stage"`) or in
 script.md's front matter (`presenterStyle: stage`); override one slide with
 `data-presenter-style` on its `<section>` or `presenter-style: corner` under
@@ -596,6 +616,20 @@ with a real screen. Proof: `number` (huge, sourced) or `chart`. Plan:
 `timeline` on a tint. People: `team` with real faces. Closer: `on-ink`, the
 one action, stickers again.
 
+**No presenter.** When nothing stands in the corner, no face (presenter
+`none`) *and* no captions (`data-silent`, or an export with captions off), or
+when a host calls `window.hyperdecks.setPresenterOff(true)`, the player puts
+`hd-no-presenter` on `<html>` and hides every `.narration-slot`. Each layout
+has a variant for that in its own `<style>` (`deck_guide layouts` says what
+each does): compare and chart widen; features, team and timeline centre
+vertically; split, product and phones centre their copy; number, quote,
+closer and a hero without art re-centre. Type sizes stay. A deck with
+captions keeps the slot (the bubble lives there). For a custom slide, keep it
+compatible: the presenter's corner is the slide's `.narration-slot`, never a
+hard-coded gutter (`padding-right: 400px`); if it needs one, override it in a
+`:root.hd-no-presenter .l-yours …` rule (check warns on a right gutter until
+you do).
+
 <!-- topic: script -->
 ### 3. Write slides and script
 
@@ -658,6 +692,43 @@ one action, stickers again.
 | `[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`.
@@ -833,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
@@ -855,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.
 
@@ -91,9 +93,15 @@ makes the hello deck; continue from step 5 below.
 10. Later: `list_shares` and `deck_stats` (both show the card),
    `activity_overview`; `email_embed { token }` for the HTML that pastes into an
    email as the deck's moving preview (it needs a recipient's link, not a QA
-   one); `set_deck_view { slug, view: "scroll" | "slides" | null, viewToggle }`
-   for how the deck opens and whether viewers may switch (every link, next
-   load, no re-release); `set_share_notify` to mute a link's "opened" alerts;
+   one); `set_deck_view { slug, view: "scroll" | "slides" | null, viewToggle, pace }`
+   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). 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

@@ -5,6 +5,8 @@
 // the deck's index.html and script.md as text, with the manifest and clip fetches
 // injected.
 
+import { DASH_AVATAR, presenterTagIssue } from "./presenter.mjs";
+
 export const PLAYER_V1 = "https://hyperdecks.ai/player/v1/player.js";
 // Decks released before the app moved to hyperdecks.ai load the same player
 // from the old host, which serves it forever; both pass.
@@ -35,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)`,
@@ -58,6 +61,8 @@ export const MESSAGES = {
   selector: (line, cue, selector, id) => `script.md line ${line}: [${cue}: ${selector}] matches nothing in slide ${id}`,
   gestureColon: (line, id) => `script.md line ${line}: [gesture ${id}] needs a colon: [gesture: ${id}]`,
   gesture: (line, id) => `script.md line ${line}: [gesture: ${id}] is not one of the head's gestures: ${GESTURES.join(", ")}`,
+  presenterUnfilled: (mode) => `the player tag says data-presenter="${mode}" but names no face (${mode === "head" ? "data-avatar" : "data-presenter-image"}), so as written it plays captions only. release puts the narrator's face on it; to set one by hand, D.A.S.H. is data-presenter="head" data-avatar="${DASH_AVATAR}" (deck_guide topic presenter)`,
+  presenterKept: (mode) => `the player tag has a data-avatar but data-presenter="${mode ?? "none"}", so it plays captions only and release leaves it that way: set data-presenter="head" to show that face, or remove data-avatar so release adds the narrator's`,
   presenterSize: (where, value) => `${where}: data-presenter-size "${value}" is not one of ${PRESENTER_SIZES.join(", ")}; the presenter keeps its default size`,
   presenterStyle: (where, value) => `${where}: presenter style "${value}" is not one of ${PRESENTER_STYLES.join(", ")}`,
   transition: (where, value) => `${where}: transition "${value}" is not one of ${TRANSITIONS.join(", ")} (zoom takes a selector: "zoom #row")`,
@@ -67,6 +72,7 @@ export const MESSAGES = {
   flyTwice: (ids) => `fly is for the deck's one big moment, but slides ${ids.join(", ")} all use it`,
   // Warnings from the look topic (deck_guide look): the deck passes, but a person should look.
   fewPictures: (shown, total) => `only ${shown} of ${total} slides show a picture (a screenshot, a recording, a photo, a chart); aim for a real one on every other slide (deck_guide topic look)`,
+  presenterGutter: (where, decl) => `${where}: ${decl} keeps a right gutter for the presenter; leave that corner to the slide's .narration-slot so a deck without a presenter can use it (deck_guide topic look)`,
   mixedIcons: (sets) => `the deck mixes icon sets (${sets.join(" and ")}); keep one set per deck (deck_guide topic look)`,
   // A layout's stand-in left in: `how` is the tool (hosted) or command (CLI) that makes the real file.
   placeholder: (id, what, el, how, img) => `slide ${id}: ${what} is still the layout's placeholder (${el}); ${how}, then put it in as ${img}`,
@@ -600,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}`;
@@ -790,6 +813,68 @@ export function lookWarnings(html) {
   return out;
 }
 
+// A wide right padding or margin (PRESENTER_GUTTER px or more, and wider than
+// the left: a centred column is not a gutter) is a gutter held for the
+// presenter outside its .narration-slot: without a presenter
+// (:root.hd-no-presenter) it stays empty. Read from inline styles on a slide
+// and its elements, and from the deck's <style> rules (by selector). Skipped:
+// rules in a phone media query (max-width, no min-width), in @keyframes and
+// the like, on the slot itself, the no-presenter rules, and a selector whose
+// gutter a :root.hd-no-presenter rule overrides (the variant the guide asks for).
+// One linear pass over the text: a malformed paste must not stall check.
+export const PRESENTER_GUTTER = 240;
+const sides = (prop, value) => {
+  const px = (v) => { const m = /^(\d+(?:\.\d+)?)(px|rem|em)$/i.exec(v ?? ""); return m ? Number(m[1]) * (m[2].toLowerCase() === "px" ? 1 : 16) : 0; };
+  const parts = value.trim().split(/\s+/);
+  if (/-(right|inline-end)$/i.test(prop)) return { right: px(parts[0]), left: 0 };
+  return { right: px(parts[1] ?? parts[0]), left: px(parts[3] ?? parts[1] ?? parts[0]) };
+};
+const gutters = (decls) => decls.split(";").map((d) => /^\s*((?:padding|margin)(?:-right|-inline-end)?)\s*:\s*([^!]+)/i.exec(d)).filter(Boolean)
+  .filter(([, prop, value]) => { const { right, left } = sides(prop, value); return right >= PRESENTER_GUTTER && right > left; })
+  .map(([, prop, value]) => `${prop.toLowerCase()}: ${value.trim()}`);
+// Each style rule of a stylesheet: { selector, decls, at } where `at` lists the
+// @-rule preludes around it. Comments drop out; braces nest.
+function cssRules(css) {
+  const out = [], stack = [];
+  let start = 0, i = 0;
+  let text = "";
+  while (i < css.length) {
+    if (css.startsWith("/*", i)) { const end = css.indexOf("*/", i + 2); text += css.slice(start, i); i = start = end === -1 ? css.length : end + 2; continue; }
+    const ch = css[i];
+    if (ch === "{" || ch === "}") {
+      text += css.slice(start, i);
+      if (ch === "{") stack.push(text.trim());
+      else {
+        const head = stack.pop();
+        if (head !== undefined && !head.startsWith("@")) out.push({ selector: head, decls: text, at: stack.filter((h) => h.startsWith("@")) });
+      }
+      text = "";
+      start = i + 1;
+    }
+    i++;
+  }
+  return out;
+}
+const phoneOnly = (at) => at.some((h) => /^@media\b/i.test(h) && /max-width/i.test(h) && !/min-width/i.test(h));
+const NO_PRESENTER = /^:root\.hd-no-presenter\s+/;
+export function presenterGutterWarnings(html) {
+  const out = [];
+  for (const [i, s] of slides(html).entries()) {
+    const where = `slide ${s.id || i + 1}`;
+    for (const [, value] of `${s.tag}\n${uncommented(s.body)}`.matchAll(/\sstyle\s*=\s*("[^"]*"|'[^']*')/gi)) {
+      for (const decl of gutters(value.slice(1, -1))) out.push(MESSAGES.presenterGutter(where, decl));
+    }
+  }
+  const rules = [...uncommented(html).matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)].flatMap(([, css]) => cssRules(css));
+  const overridden = new Set(rules.filter((r) => NO_PRESENTER.test(r.selector) && /(padding|margin)/i.test(r.decls)).map((r) => r.selector.replace(NO_PRESENTER, "")));
+  for (const r of rules) {
+    if (r.at.some((h) => !/^@(media|supports|layer|container)\b/i.test(h)) || phoneOnly(r.at)) continue;
+    if (NO_PRESENTER.test(r.selector) || /\.narration-slot\b/.test(r.selector) || overridden.has(r.selector)) continue;
+    for (const decl of gutters(r.decls)) out.push(MESSAGES.presenterGutter(`rule ${r.selector}`, decl));
+  }
+  return out;
+}
+
 // Every rule on the deck's text. `exists(ref)` answers whether a local reference
 // resolves (true, false or "outside"); `hosted: true` means there is no folder,
 // so every local reference is an error naming upload_deck_asset, a hotlinked
@@ -809,7 +894,7 @@ export async function checkSources({ html, script = "" }, opts = {}, { fetch: fe
   const errors = htmlErrors(html, { exists, forbid, script, hosted: !!opts.hosted, strict });
   const warnings = [];
   if (!notesRequired(html, { strict })) for (const id of slidesWithoutNotes(html)) warnings.push(MESSAGES.noteSoft(id));
-  warnings.push(...lookWarnings(html));
+  warnings.push(...lookWarnings(html), ...presenterGutterWarnings(html));
   // Without a folder (hosted, or a caller that passes no reader) only the inline scripts are read.
   const walked = deckFiles(html, opts.hosted ? {} : { pathExists: opts.pathExists, read: opts.read, isDir: opts.isDir });
   for (const m of walked.missing) errors.push(MESSAGES.scriptRef(m.ref, m.from));
@@ -870,9 +955,23 @@ 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));
+  // A narrated deck's tag that shows no face and says otherwise (a silent deck has no presenter).
+  const tagIssue = silent ? null : presenterTagIssue(html);
+  if (tagIssue) warnings.push(tagIssue.kind === "kept" ? MESSAGES.presenterKept(tagIssue.presenter) : MESSAGES.presenterUnfilled(tagIssue.presenter));
   for (const t of walked.templates) warnings.push(MESSAGES.scriptTemplate(t.from, t.samples));
   for (const c of walked.computed) warnings.push(MESSAGES.scriptComputed(c.from, c.calls));
   if (opts.hosted) {

package/src/commands.mjs

@@ -1,10 +1,12 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import {
+  backupLinkUrl,
   installHyperdecksSkill,
   login,
   logout,
   openBrowser,
+  linkBase,
   parse,
   target,
   VERSION,
@@ -60,7 +62,7 @@ async function deckStats(pos, opts) {
   console.log(`  unique viewers: ${s.viewers}`);
   console.log(`  avg engaged:    ${fmtMs(s.avgMs)}`);
   console.log(`  total engaged:  ${fmtMs(s.totalMs)}`);
-  if (s.view !== undefined) console.log(`  plays as:       ${s.view ?? "as its HTML says"}${s.viewToggle === false ? " (viewer toggle off)" : ""}${s.usesPlayer === false ? " (won't apply: the deck doesn't load player/v1)" : ""}`);
+  if (s.view !== undefined) console.log(`  plays as:       ${s.view ?? "as its HTML says"}${s.viewToggle === false ? " (viewer toggle off)" : ""}${s.pace ? `, pace ${s.pace}` : ""}${s.usesPlayer === false ? " (won't apply: the deck doesn't load player/v1)" : ""}`);
   if (s.recent?.length) {
     console.log("  recent:");
     for (const r of s.recent) {
@@ -85,10 +87,6 @@ async function deckRemove(pos, opts) {
   console.log(`OK removed deck ${slug}`);
 }
 
-function shareBase(opts) {
-  return target(opts).shareBase;
-}
-
 async function shareNew(pos, opts) {
   const [slug, recipient] = pos;
   if (!slug || !recipient) throw new Error("usage: share new <slug> <recipient> [--email e] [--note n] [--require-email] [--expires iso] [--limit n] [--qa] [--no-notify] [--allow-forward|--no-forward]");
@@ -105,9 +103,13 @@ async function shareNew(pos, opts) {
     expires: opts.expires,
     limit: opts.limit,
   });
-  const url = `${shareBase(opts)}/v/${token}`;
-  if (opts.json) console.log(JSON.stringify({ token, url }, null, 2));
-  else console.log(`OK share for "${recipient}" -> ${url}`);
+  const url = `${await linkBase(opts)}/v/${token}`;
+  const backupUrl = backupLinkUrl(url);
+  if (opts.json) console.log(JSON.stringify({ token, url, backupUrl }, null, 2));
+  else {
+    console.log(`OK share for "${recipient}" -> ${url}`);
+    if (backupUrl) console.log(`   backup link (same link, other domain, if their network blocks it): ${backupUrl}`);
+  }
 }
 
 async function shareList(pos, opts) {
@@ -156,23 +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]";
+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;
-  if (!slug || (mode === undefined && !Object.hasOwn(opts, "toggle"))) throw new Error(VIEW_USAGE);
+  const pace = opts.pace;
+  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}`);
@@ -181,10 +192,14 @@ async function deckView(pos, opts) {
   console.log(`OK deck ${slug} ${said.join(", ")} (every link, on its next load)`);
 }
 
-function shareUrl(pos, opts) {
+async function shareUrl(pos, opts) {
   const [token] = pos;
-  if (!token) throw new Error("usage: share url <token>");
-  console.log(`${shareBase(opts)}/v/${token}`);
+  if (!token) throw new Error("usage: share url <token> [--backup]");
+  const url = `${await linkBase(opts)}/v/${token}`;
+  console.log(url);
+  // Second line: the same link on the other domain (stdout stays one URL per line).
+  const backupUrl = backupLinkUrl(url);
+  if (backupUrl && opts.backup) console.log(backupUrl);
 }
 
 async function recipientArchive(pos, opts, archived) {
@@ -245,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)");
@@ -336,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]
+  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)
@@ -353,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]
@@ -441,7 +457,7 @@ commands:
 
   narrate <deck-dir> [--slide <id>] [--voice <name|id>] [--slug <slug>] [--dry-run] [--json]
                    script.md → voiced clips, timelines and a manifest, rendered server-side; only changed slides re-render
-  voice list [--json]   your voices and their status
+  voice list [--json]   your voices and their status, then the built-in voices anyone can narrate with
   voice clone <file...> --name <name>
                    clone your voice from 1-3 mp3/m4a/wav recordings (30 s to 3 min in total, 10 MB each);
                    asks you to type "I consent" before anything is uploaded
@@ -851,10 +867,12 @@ function commandTable(pos, rest, opts) {
       if (opts.json) console.log(JSON.stringify(out, null, 2));
     },
     "voice list": async () => {
-      const voices = await ops.listVoices(opts);
+      const voices = await ops.listAllVoices(opts);
       if (opts.json) return void console.log(JSON.stringify(voices, null, 2));
-      for (const x of voices) console.log(`${x.name}\t${x.status}\t${x.handle ?? "-"}\t${x.id}${x.error ? `\t${x.error}` : ""}`);
-      if (!voices.length) console.log("(no voices; voice clone <file...> --name <name> makes one)");
+      const own = voices.filter((x) => !x.builtin);
+      for (const x of own) console.log(`${x.name}\t${x.status}\t${x.handle ?? "-"}\t${x.id}${x.error ? `\t${x.error}` : ""}`);
+      if (!own.length) console.log("(no voices of your own; voice clone <file...> --name <name> makes one)");
+      for (const x of voices.filter((x) => x.builtin)) console.log(`${x.name}\tbuilt in\t${x.description}\t${x.id}`);
     },
     "voice clone": async () => {
       const { voiceClone } = await import("./voice.mjs");
@@ -885,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)));