@hypersocial/decks-cli 0.9.8 → 0.9.10

package/README.md

@@ -58,6 +58,7 @@ whoami [--json]
 deck list [--json]
 deck stats <slug> [--json]
 deck open <slug>
+deck link <slug> [--json]   # the owner link: present or check your own deck, untracked
 
 share new <slug> <recipient> [--email e] [--note n] [--require-email] [--expires iso] [--limit n] [--qa] [--no-notify]
 share list <slug> [--json]

package/package.json

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

package/skills/hyperdecks/SKILL.md

@@ -146,14 +146,22 @@ Hyperdecks server; use the CLI where you have a shell and the tool otherwise.
 | PDF for a data room or attachment | `hyperdecks export <slug> --pdf [--notes] --out deck.pdf`, `hyperdecks export list` | `export_deck`, `list_exports` |
 | Video (MP4) for YouTube, LinkedIn or an attachment | `hyperdecks export <slug\|deck-dir> --video [--size 1080p\|720p\|4k] [--shape 16:9\|9:16\|1:1] [--title-card] [--end-card] [--no-captions] [--no-avatar] [--upload] --out deck.mp4`: records the narrated player in real time (a 4-minute deck takes about 5), avatar, voice and captions, no player chrome; a slug records the released copy, a deck folder its working copy; `--upload` lists it with the deck's exports | `export_deck { kind: "mp4" }` renders it on our render worker (the dashboard's Export → Video); poll `check_export`, or `hyperdecks export status <exportId>` |
 | Import only | `hyperdecks import <file> --slug <slug>` | `import_deck_from_url` |
-| One more link | `hyperdecks share new <slug> "<name>" [--no-forward]` | `create_share` (`allowForward`) |
+| One more link | `hyperdecks share new <slug> "<name>" [--no-forward] [--pace auto\|slide\|step]` | `create_share` (`allowForward`, `pace`) |
 | Forwarding, one link | `hyperdecks share forward on\|off\|default <token>` | `set_share_forwarding` |
 | Forwarding, whole deck | `hyperdecks deck forward on\|off <slug>` | `set_deck_forwarding` |
-| Slides or scroll, viewer toggle, pace | `hyperdecks deck view <slug> [slides\|scroll\|default] [--toggle on\|off] [--pace auto\|slide\|step\|default]` | `set_deck_view` |
+| Slides or scroll, viewer toggle, pace, AI-readable version | `hyperdecks deck view <slug> [slides\|scroll\|default] [--toggle on\|off] [--pace auto\|slide\|step\|default] [--ai-readable on\|off]` | `set_deck_view` |
+| Present or check your own deck (owner link) | `hyperdecks deck link <slug>` (`deck open` opens it) | `ownerUrl` from `list_decks` or `check_deck` |
 | 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` |
 
+To present or check your own deck, use the owner link (`deck link`,
+`ownerUrl`): the released deck as recipients get it, for the owner only
+(signed in), with nothing tracked. Anyone else gets a sign-in notice, so a
+leaked owner link shows nothing. Its toolbar's Present (or H) hides the owner
+tools for a screen share. QA links are only for testing what a recipient sees;
+never make one to present on a call.
+
 Forwarding is on by default: a viewer can forward the deck to someone, which
 makes a child link tracked on its own ("Dana via Peter"; `share list` shows it
 indented under Peter's, `list_shares` gives `parentToken` and `forwardedBy`).
@@ -266,17 +274,27 @@ 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
+**The CLI writes the face into the tag; leave it alone.** `deck new --narrated`
+writes the narrator's face on the player tag (`data-presenter="head"
+data-avatar="…" data-presenter-from="narrator"`): the account's default
+narrator's, else D.A.S.H.'s. `deck narrator <slug> <name>` and `narrate`
+rewrite it to the narrator's face and print `presenter: …, written to
+index.html`; `deck narrator <slug> none` (or `deck new --captions-only`)
+writes captions only on purpose. So the file plays with its face however it is
+opened, a static server included. `release` (and `release_deck`) follows the
+narrator: a `data-presenter-from="narrator"` face is replaced by the current
+narrator's (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 and no `data-presenter-from`:
+`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.
+captions only, and so does a `data-avatar` beside `data-presenter="none"`, and
+so does a plain `data-presenter="none"` from an older scaffold.
+`check` warns on all three, and `release` leaves a hand-set `data-avatar` alone.
+A hosted draft (`new_deck`) stores the tag as the template wrote it; its draft
+link and `release_deck` add the narrator's face, so `check_deck` does not warn on its plain none.
 
 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
@@ -492,7 +510,7 @@ suit it.
 
 **Phones and backgrounds.** One phone: `product`'s `.frame.card`; a flow of
 two to four: `phones` (`--tilt`, `--shadow` on a card). A few slides at most:
-`bg-dots` (never under text), a `.deco` of inked tiles.
+`bg-stage` (never under text), a `.deco` of inked tiles.
 
 Presenter style follows the deck (step 2): `stage` when the presenter carries
 the story (the layouts keep the slot's corner clear); `corner` where a big
@@ -552,7 +570,8 @@ still.
 - `[go]` when the narration walks through items (cards, milestones, people,
   the action on the closer): one `go` per item at the word that starts it,
   then `[go: slot]` before the slide ends. Never more than one `go` per
-  sentence; never a `go` on a slide in `corner` style.
+  sentence; never a `go` on a slide in `corner` style. A `go` keeps off
+  the picture; with no room it stays home.
 - `[look]` for a glance: the title as it is read, a number as it is said, a
   screenshot as the narration turns to it.
 - `[reveal]` for the one detail that should not be read before it is said (a
@@ -564,8 +583,8 @@ still.
 <!-- topic: look -->
 #### Look: textures, icons, pictures
 
-What the house decks do that a plain agent deck doesn't. Decide these three
-once per deck, before writing slides, and say them in your plan.
+What the house decks do. Decide these three once per deck, before writing
+slides, and say them in your plan.
 
 **1. A picture on at least every other slide**, the most real one you have:
 
@@ -579,18 +598,22 @@ once per deck, before writing slides, and say them in your plan.
 No product to show (a plan, a strategy)? Make the slides visual with type
 and the kit below: a `number` slide, stickers, ticks on a `panel`.
 
-**2. One texture**, on two or three slides (an opener, a closer, a slide
-with a visual), never under body text. On the section:
+**2. Plain grounds; texture only behind objects.** Alternate plain,
+`on-tint`, `on-tint-2`, `on-tint-3`, `on-accent`, `on-ink`. On the section:
 
 | Class | Looks like | For |
 |---|---|---|
-| `bg-lines` | diagonal speed lines fading toward `--fade-at` | product slides, beside a picture |
-| `bg-halftone` | a corner of halftone dots | openers, numbers |
-| `bg-rays` | rays from `--rays-at` | an opener or a closer |
-| `bg-dots` | a fading dot grid | a phones row |
-
-Grounds carry the rest: alternate `on-accent`, plain, `on-ink` and the soft
-washes `on-tint`, `on-tint-2`, `on-tint-3` so each slide change reads.
+| `bg-pool` | a soft light behind the picture | any picture |
+| `bg-corner` | a halftone quarter-disc, top-right | cover, closer |
+| `bg-stage` | a dot plate under a mockup | product, phones |
+| `bg-mark` | the slide number, huge, faint (`--mark:'04'`) | cover, opener, closer |
+
+- One signature per deck (`bg-corner` or `bg-mark`), on three slides at
+  most: the cover, an opener or the ask, the closer.
+- `bg-pool` and `bg-stage` are picture helpers: only beside an image.
+- Nothing under text, a chart or a photo; the presenter's corner stays clear.
+- Your own is fine in the deck's `<style>`: tokens only, behind the content
+  in an isolated slide, off with nothing to back.
 
 **3. One icon set.** Pick one source and keep it for every icon in the deck:
 Lucide (`search_icons`, same `strokeWidth` throughout); or one
@@ -610,7 +633,7 @@ palette <ink hex> <accent hex> <paper hex>, no text, no logos`
 (`generate_image { brand: true }` adds the palette and the "no text" for
 you). Generate at the slide's shape (wide for a hero), in one batch.
 
-**Slide recipes.** Opener: `on-accent` + `bg-rays` or `bg-halftone`, the logo
+**Slide recipes.** Opener: `on-accent` + `bg-corner`, the logo
 or a few app-icon stickers, one display line. Product or feature: `split`
 with a real screen. Proof: `number` (huge, sourced) or `chart`. Plan:
 `timeline` on a tint. People: `team` with real faces. Closer: `on-ink`, the
@@ -692,6 +715,43 @@ you do).
 | `[smile]` / `[think]` | `[mood: happy]` / `[mood: thinking]` |
 | `[gesture: <id>]` | one of the head's tracks: `knowing-nod`, `ponder-tilt`, `lightbulb`, `side-eye-hmm`, `chuckle-bob`, `sunny-nod`, `double-take`… (check lists them all) |
 | `[custom: name]` | only the slide's controller sees it |
+| `[after: reveal #id]` | any stage cue above, fired at the END of the word before it (reveal at the end of a phrase) instead of its start |
+- Guest speakers: other avatars that speak their own lines on a slide, no
+  slide JS. A `[speaker: <selector> voice=<voice> avatar=<face> name=<caption name>]`
+  line runs to the end of its paragraph; the narrator takes the next one:
+
+  ```
+  ## own
+  Let's hear them.
+
+  [speaker: #own-c1 voice=stock:sarah avatar=cat] Ooh, nice move!
+
+  [speaker: #own-c2 voice=matilda avatar=monkey name="Mono"] [reveal: #own-c2] Hola, ¿qué tal?
+
+  That's the idea.
+  ```
+
+  `voice` is one of the user's voices, a built-in `stock:<id>` or a character
+  voice. `avatar` is a cast id (`cat`, `kitty`, `monkey`, `dog`, `rabbit`,
+  `penguin`, `ghost`, `alien`, `agent`…), one of the user's avatars or a
+  narrator's name; without one the guest speaks with captions only. `name`
+  labels its captions (default: the avatar, capitalised). The guest's head
+  fills the element the selector names, or the `[data-hd-speaker]` spot
+  inside it, so give each card a face box (e.g. 140×140). Narrate renders
+  each line in its own voice (cached, transcript-checked) into the slide's
+  timeline: the narrator pauses, the guests speak in turn with lip-sync and a
+  caption bubble by their element, its tail at their face, the spoken word
+  highlighted ("Cat: Ooh, nice move!"), only while they talk; the speaker's
+  element is spotlit and the other guests dim. The player draws that bubble:
+  don't put static speech bubbles or the guest's line on the slide too. The presenter
+  glances at whoever speaks, then the narrator goes on. A cue may open a
+  guest's line and fires as it starts. Inside a guest's line, `[nod]`,
+  `[shake]`, `[brow]` and `[gesture]` move the guest's head; the other cues
+  (`[reveal]`, `[go]`, `[mood]`, `[wave]`…) act on the slide and the presenter. Replay, Per step (each guest line is a
+  step), mute, You present and video export all include them.
+- Audio and data files a slide uses itself (a sound effect, a chart's JSON):
+  `hyperdecks asset add` / `upload_deck_asset` take `.mp3`, `.m4a` and
+  `.json` as well as images, video and fonts.
 - `voice: dash` narrates with D.A.S.H.'s own robot voice, a synthetic
   character voice (not a clone of anyone) any account may use, for decks that
   D.A.S.H. presents. It works once the deployment sets `CHARACTER_VOICE_DASH`.
@@ -803,6 +863,10 @@ browser (an agent reads the URL; `--json` prints it as one line).
 `release --qa` is not a preview: it needs a commit, and it changes what every
 link to this deck plays.
 
+Watch a draft with `hyperdecks play`: it shows the face the deck will ship
+with. A plain static server shows the file as written: the face named in the
+tag (the narrator's, since `deck new`, `deck narrator` and `narrate` write it
+there), or none for a tag that says `data-presenter="none"` (`check` warns).
 For the layout pass, serve the folder (`npx serve decks/<slug>` or `python3 -m http.server -d decks/<slug>`)
 and screenshot it with Playwright at 1440×900 and 390×844, every slide
 (`#scene=<id>`). Look at both: nothing clipped, the presenter and its captions
@@ -867,8 +931,10 @@ hyperdecks engagement "<name>" --deck <slug> --json   # MCP: recipient_engagemen
 Then draft the email:
 
 1. Lead with the slide they spent most time on (`summary.mostTime`) or
-   replayed (`replayedSlides`), and answer what that slide raises. Each
-   slide's `title` says what it is about.
+   replayed (`replayedSlides`; `slideReplays` are the ones they replayed on
+   purpose, most first, and `replayNote` says it in one line), and answer what
+   that slide raises. Each slide's `title` says what it is about. Watching it
+   again from the start (`watchedAgain`) is strong interest.
 2. If they dropped off (`droppedOffOn`), offer the rest briefly, or a
    2-minute call, rather than asking them to rewatch.
 3. If they never opened it (`summary.visits` is 0), write a short nudge
@@ -889,7 +955,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.
 
@@ -88,6 +90,11 @@ makes the hello deck; continue from step 5 below.
    only, when nobody chose that, is refused: hand the person its Add narrator
    link, or offer D.A.S.H., and pass `captionsOnly: true` only if they say so.
    The result's `presenter` names who presents.
+   To present or check your own deck (on a call, say), give the user its
+   owner link, `ownerUrl` from `list_decks` or `check_deck`: only they can
+   open it, signed in, and nothing is tracked; Present (or H) hides their
+   owner tools for a screen share. QA links are only for testing what a
+   recipient sees, not for presenting.
 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
@@ -95,7 +102,11 @@ makes the hello deck; continue from step 5 below.
    for how the deck opens, whether viewers may switch, and its pace (`auto`
    plays itself, `slide` waits for Next after each slide, `step` also stops
    before each `[reveal]`, so group a slide's reveals into meaningful steps)
-   (every link, next load, no re-release); `set_share_notify` to mute a link's "opened" alerts;
+   (every link, next load, no re-release). Any share link + `/md` (e.g.
+   https://decks.hypersocial.ai/v/<token>/md) returns the deck as markdown
+   (slide text, image descriptions and the narration), honouring the link's
+   gates; owners can turn it off with `set_deck_view { slug, aiReadable: false }`.
+   `set_share_notify` to mute a link's "opened" alerts;
    `set_recipient_archived` to tidy the activity feed; `credits` for the
    balance. `remove_deck` deletes a deck and breaks every link to it: confirm
    with the user first.

package/src/avatar.mjs

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

package/src/brand.mjs

@@ -8,7 +8,8 @@
 // only the tokens here touch the deck.
 
 // Weights each role loads: the templates set body text at 500, titles at 700
-// and labels in mono at 400/700. Every family below has these on Google Fonts.
+// and labels in mono at 400/700. Every pairing family has these on Google Fonts;
+// a display family outside the pairings loads what displayFace says it has.
 const ROLE_WEIGHTS = { display: "600;700", body: "400;500;700", mono: "400;700" };
 
 // 16 pairings, display + body + mono, each a family Google Fonts serves at the
@@ -32,8 +33,35 @@ export const FONT_PAIRINGS = [
   { id: "grotesk", display: "Schibsted Grotesk", body: "Work Sans", mono: "Roboto Mono", use: "Marketplaces and media brands; confident and newsy." },
 ];
 
-// Weights for families that do not have every role weight (load what exists).
-const FAMILY_WEIGHTS = { "Space Mono": "400;700", "DM Mono": "400;500", "Libre Baskerville": "400;700", "Courier Prime": "400;700", "Syne": "600;700" };
+// Weights for families that do not have every role weight (load what exists),
+// including single-weight display faces a brand may name (Google Fonts refuses
+// a stylesheet that asks for a weight the family lacks).
+const SINGLE_WEIGHT = ["Bangers", "Bebas Neue", "Anton", "Luckiest Guy", "Permanent Marker", "Pacifico", "Lobster", "Abril Fatface", "Alfa Slab One", "Righteous", "Press Start 2P", "Black Ops One", "Bungee", "Russo One", "Shrikhand", "Monoton", "Creepster", "Special Elite"];
+const FAMILY_WEIGHTS = {
+  "Space Mono": "400;700", "DM Mono": "400;500", "Libre Baskerville": "400;700", "Courier Prime": "400;700", "Syne": "600;700",
+  ...Object.fromEntries(SINGLE_WEIGHT.map((f) => [f, "400"])),
+};
+
+// The template's titles (700, -.045em) were tuned for the pairings' sans
+// display faces. Any other display face gets tracking 0; a face with a known
+// weight table is set at its heaviest weight. A face we know nothing about stays
+// at 700 and loads 400;700: Google Fonts' css2 serves whichever of the asked
+// weights exist (it fails only when none do), and the templates' font-synthesis:
+// none means a face without a 700 draws its real 400, never a faked bold.
+const SERIF_DISPLAY = new Set(["Fraunces", "Playfair Display", "Newsreader", "Libre Baskerville"]);
+const TUNED_DISPLAY = new Set(FONT_PAIRINGS.map((p) => p.display).filter((f) => !SERIF_DISPLAY.has(f)));
+// Any family a pairing names (display or body) has the display weights.
+const PAIRED_DISPLAY = new Set(FONT_PAIRINGS.flatMap((p) => [p.display, p.body]));
+
+// { weights, weight, tracking } for a display family: the weights to load, and
+// the --display-weight / --display-tracking to write (null: the template's).
+export function displayFace(family) {
+  const f = String(family ?? "").trim();
+  const weights = FAMILY_WEIGHTS[f] ?? (PAIRED_DISPLAY.has(f) ? ROLE_WEIGHTS.display : "400;700");
+  if (TUNED_DISPLAY.has(f)) return { weights, weight: null, tracking: null };
+  const heaviest = Math.max(...weights.split(";").map(Number));
+  return { weights, weight: heaviest === 700 ? null : String(heaviest), tracking: "0" };
+}
 
 const HEX = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
 // A Google Fonts family name: letters, digits and spaces (e.g. "Source Sans 3").
@@ -54,7 +82,7 @@ export function findPairing(id) {
 // The Google Fonts stylesheet URL for one family at the weights its roles use
 // (a family that is both display and body loads both roles' weights).
 export function googleFontsUrl(family, roles = "body") {
-  const wanted = [roles].flat().flatMap((r) => (ROLE_WEIGHTS[r] ?? "400;700").split(";"));
+  const wanted = [roles].flat().flatMap((r) => (r === "display" ? displayFace(family).weights : ROLE_WEIGHTS[r] ?? "400;700").split(";"));
   const weights = FAMILY_WEIGHTS[family] ?? [...new Set(wanted)].sort().join(";");
   return `https://fonts.googleapis.com/css2?family=${family.trim().replace(/ /g, "+")}:wght@${weights}&display=swap`;
 }
@@ -115,7 +143,12 @@ export function applyBrand(html, brand) {
   for (const [k, v] of Object.entries(b.colors)) set(CSS_VAR[k], v);
   if (b.fonts.body) set("--font", fontStack(b.fonts.body, "body"));
   if (b.fonts.mono) set("--mono", fontStack(b.fonts.mono, "mono"));
-  if (b.fonts.display) set("--display", fontStack(b.fonts.display, "display"));
+  if (b.fonts.display) {
+    set("--display", fontStack(b.fonts.display, "display"));
+    const face = displayFace(b.fonts.display);
+    if (face.weight) set("--display-weight", face.weight);
+    if (face.tracking) set("--display-tracking", face.tracking);
+  }
   let out = html.slice(0, root.index) + block + html.slice(root.index + root[0].length);
 
   const families = FONT_ROLES.filter((r) => b.fonts[r]).map((r) => [b.fonts[r], r]);

package/src/checkRules.mjs

@@ -37,6 +37,7 @@ export const MESSAGES = {
   noLoading: () => "no loading state: run `hyperdecks check <deck> --fix` (`check <slug> --hosted --fix`; over the MCP, write index.html again with write_deck_source), which needs a <head>…</head> and the player script; or copy the <style data-hd-loading> block and the lines above it from the narrated template into <head>; set --hd-ground to the first slide's colour",
   clipField: (id, field) => `clip ${id}: ${field}`,
   noCaptions: (id) => `clip ${id}: timeline has no captions`,
+  speakerMissing: (id, name, selector) => `slide ${id}: guest ${name} speaks from "${selector}", which is not on the slide, so its lines play with captions only and no face`,
   order: (slides, clips) => `slide ids (${slides.join(", ")}) must equal the manifest clip ids (${clips.join(", ")}), in order`,
   total: (sum, declared) => `clip durations plus holds add up to ${sum}s but the manifest declares totalDuration ${declared}s`,
   cap: (total, cap) => `narration runs ${total}s, over the ${cap}s cap (aim for 150 to 180 s)`,
@@ -62,6 +63,7 @@ export const MESSAGES = {
   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`,
+  presenterCaptions: () => `the player tag plays captions only as written (data-presenter="none" or none set), so the file served as is (npx serve, python3 -m http.server, the screenshot pass) shows no face: run \`hyperdecks deck narrator <slug> <name>\` (or narrate again) to write the narrator's face into index.html, or watch it with \`hyperdecks play <deck>\`; release adds the face either way. Captions only on purpose: \`hyperdecks deck narrator <slug> none\``,
   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")`,
@@ -73,6 +75,9 @@ export const MESSAGES = {
   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)`,
+  retiredTexture: (where, cls, instead, inlined) => `${where}: ${cls} is a whole-slide texture the kit no longer ships ${inlined ? "(this deck still carries its rule, so it runs under the text)" : "(it ran under the text), so it paints nothing"}; ${instead} (deck_guide topic look)`,
+  tooManySignatures: (n) => `${n} slides carry a signature background (bg-corner or bg-mark); keep it to three at most: the cover, one opener or the ask, the closer (deck_guide topic look)`,
+  textureOff: (where, cls, layout) => `${where}: ${cls} does nothing on ${layout} (the shell switches it off there: nothing to back); remove it, or use bg-pool behind the picture (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}`,
   // Warnings (check --layout): the deck still passes.
@@ -605,6 +610,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}`;
@@ -792,6 +814,44 @@ export function lookWarnings(html) {
     if (iconImg(tag)) sets.add("image icons");
   }
   if (sets.size > 1) out.push(MESSAGES.mixedIcons([...sets].sort()));
+  out.push(...textureWarnings(all, html));
+  return out;
+}
+
+// Backgrounds (the look topic): the kit's textures are confined to the object they
+// back. The retired whole-slide textures warn rather than vanish silently (a deck made
+// before keeps their rules in its own inlined shell, where they still paint). Read from each slide's class attribute; a texture on a layout whose shell
+// rule switches it off (TEXTURE_OFF, pinned to _deck.html by lib/deckLayouts.test.ts) did nothing, and a custom
+// slide (no l-* class) is never judged on that. Commented-out slides do not count.
+const RETIRED_TEXTURES = {
+  "bg-rays": "use a plain ground, or bg-corner on the cover and the closer",
+  "bg-lines": "use a plain ground, or bg-pool behind the picture",
+  "bg-halftone": "use bg-corner on the cover and the closer",
+  "bg-dots": "use bg-stage under the mockup or the phones",
+};
+const SIGNATURES = ["bg-corner", "bg-mark"];
+export const MAX_SIGNATURE_SLIDES = 3;
+const BUSY_LAYOUTS = ["l-number", "l-features", "l-team", "l-timeline", "l-compare"]; // full-width content: nothing to back
+export const TEXTURE_OFF = {
+  "bg-corner": ["l-split", "l-product", "l-chart", "l-quote", ...BUSY_LAYOUTS],
+  "bg-stage": ["l-split", "l-chart", "l-quote", "l-closer", ...BUSY_LAYOUTS],
+  "bg-mark": ["l-split", "l-product", "l-chart", "l-phones", ...BUSY_LAYOUTS],
+};
+function textureWarnings(all, html) {
+  const css = [...uncommented(html).matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)].map((m) => m[1].replace(/\/\*[\s\S]*?\*\//g, "")).join("\n");
+  const inlined = (c) => new RegExp(`\\.${c}(?![\\w-])[^{}]*\\{`).test(css);
+  const out = [];
+  let signatures = 0;
+  all.forEach((s, i) => {
+    const where = `slide ${s.id || i + 1}`;
+    const cls = classes(s.tag);
+    for (const [c, instead] of Object.entries(RETIRED_TEXTURES)) if (cls.includes(c)) out.push(MESSAGES.retiredTexture(where, c, instead, inlined(c)));
+    if (SIGNATURES.some((c) => cls.includes(c))) signatures++;
+    const layout = cls.find((c) => /^l-[\w-]+$/.test(c));
+    if (!layout) return;
+    for (const [c, off] of Object.entries(TEXTURE_OFF)) if (cls.includes(c) && off.includes(layout)) out.push(MESSAGES.textureOff(where, c, layout));
+  });
+  if (signatures > MAX_SIGNATURE_SLIDES) out.push(MESSAGES.tooManySignatures(signatures));
   return out;
 }
 
@@ -937,12 +997,29 @@ 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));
+  // A hosted draft plays only through its draft link and release_deck, which add the face, so a plain none is no issue there.
+  const found = silent ? null : presenterTagIssue(html);
+  const tagIssue = found?.kind === "captions" && opts.hosted ? null : found;
+  if (tagIssue) {
+    warnings.push(tagIssue.kind === "kept" ? MESSAGES.presenterKept(tagIssue.presenter)
+      : tagIssue.kind === "captions" ? MESSAGES.presenterCaptions()
+      : 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) {