@hypersocial/decks-cli 0.7.0 → 0.8.1

package/README.md

@@ -79,6 +79,7 @@ voice list|clone|upload|rm
 
 deck new <slug> "<title>" --narrated [--dir <path>]
 check <slug|deck-dir> [--forbid "<phrase>,<phrase>"] [--max-duration <s>] [--json]
+play <slug|deck-dir> [--voice <v>] [--slug <slug>] [--port <n>] [--no-open] [--json]
 release <slug|deck-dir> [--to "<name>" [--email <e>]]... [--qa] [--no-notify] [--title t] [--voice v]
 ```
 
@@ -93,7 +94,12 @@ clip's audio and timeline resolve with the right type; captions are in time,
 cover the clip text and run 4 to 85 characters; local `src`/`href` resolve inside
 the folder; the player is the pinned `player/v1`; `--forbid` phrases appear
 nowhere; every slide has a `data-note` and long titles a `data-title-mobile`.
-`release` refuses uncommitted changes in the deck folder, runs check and narrate
+`play` plays the folder as it is, committed or not, with the real face and voice:
+the face goes on the served copy in memory, on 127.0.0.1 behind a random path, until
+Ctrl-C. It writes no file, uploads nothing, creates no share and renders no audio, so
+changed lines need `narrate` first. The hosted draft link `/p/<token>` shows the same face.
+`release` refuses uncommitted changes in the deck folder (`--qa` too: a release
+replaces what every link to the deck plays), runs check and narrate
 (stopping for a commit if narration changed the folder), imports `index.html` with
 the local files it references, and creates one share per `--to`. The agent
 procedure is the "Author a narrated deck" section of the bundled skill.

package/package.json

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

package/skills/hyperdecks/SKILL.md

@@ -66,7 +66,8 @@ returns a link; hand it to them, word for word, and wait.
 The faces narrators wear; these commands still work as before.
 
 A deck narrated in the user's own voice is presented by their default avatar
-(a cartoon Minimoji, never a photo) from its next release; with none it plays
+(a cartoon Minimoji, never a photo): in `play` and the draft link at once, on
+share links from its next release. With none it plays
 captions only. D.A.S.H. presents only in its own voice. **Never pick or approve
 a face for the person.** Every command that needs a choice returns a link (and,
 for an import, a code): hand it to them, word for word, and wait.
@@ -125,6 +126,8 @@ Hyperdecks server; use the CLI where you have a shell and the tool otherwise.
 |---|---|---|
 | Brand (once; every new deck starts from it) | `hyperdecks brand show` / `brand set` / `brand edit` | `get_brand` / `set_brand` |
 | Import a brand (website, .pptx/.potx, .pdf, a deck; preview first) | `hyperdecks brand import <url\|file\|slug>` | `import_brand` |
+| Revise the brand with a prompt (preview first) | `hyperdecks brand revise "<change>"` | `revise_brand` |
+| Brand history / undo a brand change | `hyperdecks brand history` / `brand undo [<version>]` | `brand_history` / `undo_brand` |
 | Scaffold | `hyperdecks deck new <slug> "<title>" --narrated [--layouts hero,product,number,closer]` | `new_deck` (`layouts`) |
 | Images | `hyperdecks gen-image "<prompt>" --slug <slug>` | `generate_image` |
 | Video clips | `hyperdecks gen-video "<prompt>" --slug <slug>` | `generate_video` |
@@ -137,6 +140,7 @@ Hyperdecks server; use the CLI where you have a shell and the tool otherwise.
 | Who narrates (ask the person first; see *Narrators*) | `hyperdecks deck narrator <slug> <name\|none\|default>` | `list_narrators`, then `set_deck_narrator` |
 | Narrate | `hyperdecks narrate decks/<slug>` | `narrate_deck` |
 | Check | `hyperdecks check decks/<slug>` | `check_deck` |
+| Watch a draft with its real face | `hyperdecks play decks/<slug>` | the `previewUrl` from `get_deck_source` |
 | Ship | `hyperdecks release decks/<slug> --to "<name>" --email <e>` | `release_deck` |
 | Share-link poster | `hyperdecks poster <slug>` | `generate_deck_poster` |
 | Import only | `hyperdecks import <file> --slug <slug>` | `import_deck_from_url` |
@@ -211,6 +215,13 @@ The deck contract (`check` enforces each line):
   `narrate` fills `data-manifest`; do not edit it by hand.
 - Local images and files sit inside the deck folder and are referenced
   relatively (`img/chart.png`). Hosted images (`gen-image` URLs) are fine too.
+- A file the deck's own JavaScript loads (`fetch('media/data.json')`, a clip
+  for `new Audio(…)`) is written out as a quoted path, in an inline `<script>`
+  or in a `.js` or `.json` file the deck loads. Release follows those paths and ships the files
+  (`play` serves the whole folder, the `/v/` link only what release shipped).
+  A path built at runtime (`` `media/lines/${id}.mp3` ``) can't be followed:
+  list each file literally (`{ otter: "media/lines/otter.mp3" }`) and pick from
+  that.
 
 <!-- topic: presenter -->
 #### Which presenter style
@@ -318,6 +329,10 @@ fonts and logo (a PowerPoint's theme exactly) and returns a preview link, a
 sample slide in that brand, and a token. Always show them the preview and
 ask; save with `brand set --draft <token>` (`set_brand { draft }`) only after
 they say yes.
+To change it in words ("darker accent, serif titles"), `hyperdecks brand
+revise "<change>"` (`revise_brand`) gives a draft and preview the same way.
+Every brand save is kept in its history: `brand history` (`brand_history`)
+lists the last changes and `brand undo [<version>]` (`undo_brand`) goes back.
 
 **Fonts: pick a pairing.** Fonts load from Google Fonts. Use one of the
 curated pairings below (display for titles, body for text, mono for kickers
@@ -439,13 +454,32 @@ phone screenshots, the same `fix` bar.
 - Narration: short phrases, each sentence one caption of 4 to 85 characters
   (two lines in the bubble). Aim for 2.5 to 3 minutes in all; `maxTotalSeconds`
   in the front matter is the cap check uses (180 in the scaffold).
-- Holds: 0.4 s by default. Give a slide `hold: 1.5` when the viewer needs time to read a number, a chart or a reveal, and `hold: 2` on interactive slides.
-- Cues: `[reveal: #id]` reveals `.reveal#id` at the word before it; also
+- Holds: 0.4 s by default. Give a slide `hold: 1.5` when the viewer needs time to read a number, a chart or a reveal.
+- Interactive slides (something the viewer taps or plays with): add
+  `data-interactive` to the slide's `<section>`. The presenter finishes the
+  line, then the deck waits with a Continue button instead of advancing, and
+  taps inside the slide don't pause the narration. The slide hears the
+  presenter through `deck:presenter { slide, state }` on `window` (or a
+  controller's `onNarration(state, ctx)`), ducks its own audio while `state`
+  is `playing`, and can quiet the presenter with `ctx.player.pause()` /
+  `resume()` (or `window.hyperdecks.pauseNarration()` / `resumeNarration()`).
+- Anything the viewer clicks on a slide (interactive or not) gets
+  `data-hd-tap` (or `cursor: pointer`), so the click doesn't also pause the
+  presenter. Buttons, links, canvases and focusable elements are exempt already.
+- Cues: `[reveal: #id]` reveals `.reveal#id` at the word before it (going
+  back or replaying the slide replays its reveals from the first, and the
+  live head glances at each, unless a `[look]`/`[go]` is beside it or a
+  `go` has it docked; `data-reveal-glance="off"` on the slide or `<body>`
+  stops the glance); also
   `[wave]`, `[mood: excited]`, `[pause: 0.5]`, `[custom: name]`.
 - Moves, to point at part of a slide: `[go: <selector>]` flies the presenter
   beside that element (the side with room) until the next `go`, the slide's
-  end, or `[go: slot]`; `[look: <selector>]` turns the head toward it without
-  moving. One selector each, matched inside that slide; check fails one that
+  end, or `[go: slot]`. The element grows a little and, when it is one item
+  of a list or grid, the other items fade back (`.hd-dimmed`); the presenter
+  never covers them, so with no room beside it it stays put and looks at it.
+  Put `data-focus="ring"` on the element or slide for an accent ring instead,
+  or restyle `.hd-focus` / `.hd-dimmed` in the deck's CSS.
+  `[look: <selector>]` turns the head toward an element without moving. One selector each, matched inside that slide; check fails one that
   matches nothing. Use `go` when the narration walks through a list or chart,
   `look` for a glance at a title or number. Not in `corner` style. The best
   showcase is a slide of stacked cards, one point each, with a `go` to each
@@ -462,10 +496,10 @@ phone screenshots, the same `fix` bar.
 |---|---|
 | `[wave]` | the presenter greets (the live head's joy emote) |
 | `[mood: excited]` / `[emote: name]` | the head's mood or emote |
-| `[reveal: #id]` | adds `is-revealed` to `#id` |
+| `[reveal: #id]` | adds `is-revealed` to `#id` (reset when the slide is left or replays); the live head glances at it unless a `[look]`/`[go]` is beside it |
 | `[pause: 0.5]` | a beat of silence (≤ 5 s) |
 | `[play: video]` / `[pause: video]` | play or pause the slide's video |
-| `[go: .list]` / `[go: slot]` | fly beside `.list` / back to the slot |
+| `[go: #step-2]` / `[go: slot]` | fly beside that item, grow it, fade the other items / back to the slot |
 | `[look: h2]` / `[look #card]` | look at the title / the card, then back |
 | `[look viewer]` / `[look away]` | look back at the viewer / glance aside |
 | `[nod]` / `[shake]` | a nod or head shake that suits the mood |
@@ -519,6 +553,9 @@ an internal codename). Messages and what to do:
 | `clip <id>: captions do not cover the clip text` | narrate that slide again |
 | `clip <id>: caption N is … characters` | split or join sentences in that block |
 | `local reference does not resolve` / `leaves the deck folder` | move the file into the deck folder or fix the path |
+| `<file> names <path>, which is not in the deck folder` | add the file, or fix the path in that script |
+| ⚠ `<file> builds file paths at runtime` | list each file as a quoted path (an object or array, in a script or a `.json` it fetches) and pick from it |
+| ⚠ `<file> loads files from computed values` | fine when every file it can load is also written out as a quoted path; otherwise list them so release ships them |
 | `player script must be` / `no player script` | restore the player/v1 script tag |
 | `the player script has no data-manifest` | run `narrate` |
 | `no loading state` | copy the template's `<style data-hd-loading>` block (and the preload lines above it) into `<head>`; set `--hd-ground` / `--hd-ground-ink` to the first slide's colours |
@@ -539,7 +576,16 @@ an internal codename). Messages and what to do:
 
 ### 6. Look at it, at both widths
 
-Serve the folder (`npx serve decks/<slug>` or `python3 -m http.server -d decks/<slug>`)
+To watch it as it will really play, run `hyperdecks play decks/<slug>`. It plays
+the folder as it is, committed or not, with the real face and voice, on
+127.0.0.1 until Ctrl-C. It writes nothing, uploads nothing, creates no share and
+spends nothing, so it plays the last narration: changed lines need `narrate`
+first. It prints who presents, or why it is captions only. `--no-open` skips the
+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.
+
+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
 clear of the text, the mobile titles in use. Fix and repeat until both read well.

package/skills/hyperdecks/chat.md

@@ -29,9 +29,14 @@ makes the hello deck; continue from step 5 below.
    a `previewUrl` (a sample slide in that brand) and a `token`. Always give
    them the preview link, say what it found (and its notes), and ask; only
    after a yes call `set_brand { draft: token }`. Never save without the yes.
+   To change the brand in words ("less yellow", "serif titles"),
+   `revise_brand { instruction }` gives a draft and preview the same way.
+   Any brand change can be undone: `brand_history`, then `undo_brand`.
    (`deck_guide { topic: "design" }` lists the font pairings.)
 2. `new_deck { slug, title, layouts }`: registers your draft and returns the
-   full text of every file plus a `previewUrl` (the draft, untracked). It
+   full text of every file plus a `previewUrl` (the draft, untracked; once
+   narrated it plays with the face its release would have, so the person can
+   watch it before anything ships). It
    starts in the saved brand's colours, fonts and logo (`brand` in the result
    says what it took); `brand: false` gives the template's look.
 3. Images: `generate_image`, `render_chart`, `capture_url`, or
@@ -69,9 +74,9 @@ makes the hello deck; continue from step 5 below.
    `[smile]`, `[gesture: lightbulb]`; `deck_guide script` lists them) and
    narrate again.
 8. `check_deck { slug }` again, then `review_deck { slug, draft: true }` and
-   `check_review_job`: it shoots desktop and 390×844 phone frames, which is how
-   you catch a slide that overflows a phone (the hosted check cannot measure
-   layout).
+   `check_review_job`: it shoots desktop and 390×844 phone frames, face included,
+   which is how you catch a slide that overflows a phone (the hosted check cannot
+   measure layout).
 9. `release_deck { slug, qa: true }` gives the user a QA link to watch first.
    `release_deck { slug, recipients: [{ recipient, email }] }` makes one
    tracked link each. Release creates live links: confirm the recipients with

package/src/avatar.mjs

@@ -86,6 +86,6 @@ export async function avatarConnect(opts, { log = console.log, interactive = int
   log("Waiting for you to pick a face…");
   const done = await ops.waitForConnect(opts, out.connectId);
   if (done.status !== "added") throw new Error(done.status === "denied" ? "not shared on minimoji.com" : done.status === "expired" ? "the code expired; run avatar connect again" : done.error || `the import ended (${done.status})`);
-  log("✓ Presenter: your Minimoji. Your decks use it from the next release.");
+  log("✓ Presenter: your Minimoji. Your drafts show it now; share links get it from the next release.");
   return { status: "added", avatarId: done.avatarId };
 }

package/src/brandCli.mjs

@@ -10,6 +10,9 @@
 //             [--draft <token>]      (a brand import, saved after you saw its preview)
 //   brand import <url|file|slug>     read a brand from a website, a .pptx / .potx /
 //                                    .pdf or one of your decks into a draft + preview
+//   brand revise "<change>"          a draft + preview of the brand with that change
+//   brand history                    the last changes (from any surface)
+//   brand undo [<version>]           undo the last change, or go back to a version
 //   brand edit                       design.md in $VISUAL / $EDITOR, saved on exit
 //   brand fonts                      the curated font pairings
 //   brand clear                      forget the brand (new decks get the template look)
@@ -135,7 +138,7 @@ export function importLines(d) {
   const colors = Object.entries(d.colors ?? {}).map(([k, v]) => `${k} ${v}`).join(", ");
   const fonts = Object.entries(d.fonts ?? {}).map(([k, v]) => `${k} ${v}`).join(", ");
   return [
-    `read from ${d.source?.kind} ${d.source?.ref}`,
+    d.source?.kind === "revise" ? `revised: ${d.source.ref}` : `read from ${d.source?.kind} ${d.source?.ref}`,
     ...(d.name ? [`name:      ${d.name}`] : []),
     `colours:   ${colors || "(none found)"}`,
     `fonts:     ${fonts || "(none found)"}`,
@@ -164,3 +167,45 @@ export async function brandImport(from, opts = {}, { log = (line) => console.log
   else for (const line of importLines(d)) log(line);
   return d;
 }
+
+// brand revise "<change>": the model's take on the brand, as a draft + preview.
+export async function brandRevise(words, opts = {}, { log = (line) => console.log(line) } = {}) {
+  const instruction = (Array.isArray(words) ? words.join(" ") : String(words ?? "")).trim();
+  if (!instruction) throw new Error('usage: brand revise "<change>", e.g. brand revise "make the accent darker and use a serif for titles"');
+  const d = await ops.reviseBrand(opts, { instruction });
+  if (opts.json) log(JSON.stringify(d, null, 2));
+  else for (const line of importLines(d)) log(line);
+  return d;
+}
+
+const ago = (at, now = Date.now()) => {
+  const m = Math.round((now - at) / 60000);
+  if (m < 1) return "just now";
+  if (m < 60) return `${m} min ago`;
+  const h = Math.round(m / 60);
+  return h < 48 ? `${h} h ago` : `${Math.round(h / 24)} days ago`;
+};
+
+export function historyLines(versions, now = Date.now()) {
+  if (!versions.length) return ["no brand changes yet"];
+  return [
+    ...versions.map((v) => `${v.current ? "* " : "  "}${v.label.padEnd(48)} ${ago(v.at, now).padEnd(12)} ${v.id}`),
+    "",
+    "hyperdecks brand undo            undo the last change",
+    "hyperdecks brand undo <version>  go back to one of these",
+  ];
+}
+
+export async function brandHistory(opts = {}, { log = (line) => console.log(line) } = {}) {
+  const out = await ops.brandHistory(opts);
+  if (opts.json) log(JSON.stringify(out, null, 2));
+  else for (const line of historyLines(out.versions)) log(line);
+  return out;
+}
+
+export async function brandUndo(version, opts = {}, { log = (line) => console.log(line) } = {}) {
+  const b = await ops.undoBrand(opts, { version });
+  if (opts.json) log(JSON.stringify(b, null, 2));
+  else for (const line of [version ? "✓ brand restored" : "✓ last change undone", ...brandLines(b)]) log(line);
+  return b;
+}

package/src/brandImport.mjs

@@ -488,9 +488,11 @@ export function extractSite({ html, css = [], url }) {
     if (card) colors.card = card.hex;
   }
   const named = Object.keys(from);
-  if (named.length) notes.push(`Colours ${named.map((k) => `${k} from ${from[k]}`).join(", ")}; the rest sampled from the site's CSS.`);
-  else if (Object.keys(colors).length) notes.push("Colours sampled from the site's CSS (it names no colour tokens); check them in the preview.");
-  else notes.push("No colours found in the site's static CSS (it may draw them with JavaScript); set them with set_brand, or capture_url the page to read them by eye.");
+  // For people, plain words; for the logs (details), which token gave what.
+  const details = /** @type {string[]} */ ([]);
+  if (named.length) details.push(`colours ${named.map((k) => `${k} from ${from[k]}`).join(", ")}; the rest sampled from the site's CSS`);
+  if (!named.length && Object.keys(colors).length) notes.push("The site doesn't name its colours, so they were picked from its styles: check them in the sample.");
+  else if (!Object.keys(colors).length) notes.push("No colours were found on the site (it may draw them with JavaScript): pick them by hand.");
 
   // Fonts: Google Fonts links, @font-face, then font-family by role.
   const linked = [];
@@ -530,7 +532,7 @@ export function extractSite({ html, css = [], url }) {
 
   const candidates = logoCandidates(doc, url);
   const name = siteName(doc);
-  return { name, colors, fonts, logoCandidates: candidates, notes, source: { kind: "url", ref: url } };
+  return { name, colors, fonts, logoCandidates: candidates, notes, details, source: { kind: "url", ref: url } };
 }
 
 // ---- a Hyperdecks deck -----------------------------------------------------
@@ -559,10 +561,13 @@ export function extractDeck(html, slug) {
   const alt = logoTag && attr(logoTag.tag, "alt");
   const name = alt && / logo$/i.test(alt) ? decodeEntities(alt).replace(/ logo$/i, "").trim() : undefined;
   const notes = /** @type {string[]} */ ([]);
-  notes.push(`Colours and fonts are deck ${slug}'s own :root tokens.`);
-  if (!src) notes.push("The deck has no brand logo; add one with set_brand { logoUrl }.");
-  else if (!/^https:\/\//.test(src)) notes.push(`The deck's logo (${src.slice(0, 80)}) is not a hosted https URL, so it was not copied; add it with set_brand { logoUrl }.`);
-  return { name, colors, fonts, logoCandidates: src && /^https:\/\//.test(src) ? [{ url: src, via: "deck" }] : [], notes, source: { kind: "deck", ref: slug } };
+  const details = [`colours and fonts are deck ${slug}'s :root tokens`];
+  if (!src) notes.push("The deck has no logo: add one.");
+  else if (!/^https:\/\//.test(src)) {
+    notes.push("The deck's logo is not hosted online, so it was not copied: add it.");
+    details.push(`deck logo src ${src.slice(0, 80)} is not an https URL`);
+  }
+  return { name, colors, fonts, logoCandidates: src && /^https:\/\//.test(src) ? [{ url: src, via: "deck" }] : [], notes, details, source: { kind: "deck", ref: slug } };
 }
 
 // ---- PowerPoint ------------------------------------------------------------
@@ -648,8 +653,8 @@ export function extractPptx(bytes, fileName = "presentation.pptx") {
   if (major) fonts.display = major;
   if (minor) fonts.body = minor;
   const notes = /** @type {string[]} */ ([]);
-  notes.push(`Colours and fonts are the exact theme of ${fileName}${scheme ? ` (colour scheme "${scheme}")` : ""}: ink dk1, paper lt1, accent accent1, accent2 accent2, card lt2; titles the major font, body the minor.`);
-  if (/^office/i.test(scheme ?? "") && /^(calibri|aptos)/i.test(minor ?? "")) notes.push("This is PowerPoint's default Office theme, not a custom one: the colours may not be the brand's.");
+  const details = [`theme of ${fileName}${scheme ? ` (colour scheme "${scheme}")` : ""}: ink dk1, paper lt1, accent accent1, accent2 accent2, card lt2; titles the major font, body the minor`];
+  if (/^office/i.test(scheme ?? "") && /^(calibri|aptos)/i.test(minor ?? "")) notes.push("This is PowerPoint's default theme, not a custom one, so the colours may not be your brand's.");
 
   // The logo: the first picture on the slide master, else on its first layout.
   let logo;
@@ -673,14 +678,15 @@ export function extractPptx(bytes, fileName = "presentation.pptx") {
     // Only a picture under the logo limit is unpacked (its declared size; fflate inflates into exactly that).
     let declared = 0;
     const got = type ? unzipSync(bytes, { filter: (f) => f.name === media && (declared = f.originalSize) <= MAX_LOGO_BYTES })[media] : null;
-    if (!type) notes.push(`The slide master's picture is a .${ext} file, which a deck cannot show; add the logo with set_brand { logoUrl }.`);
-    else if (declared > MAX_LOGO_BYTES) notes.push(`The slide master's picture is ${Math.ceil(declared / 1024)} KB, over the 2 MB logo limit; add a smaller logo.`);
-    else if (!got) notes.push("The slide master names a picture the file does not contain.");
-    else if (got.byteLength > MAX_LOGO_BYTES) notes.push(`The slide master's picture is ${Math.ceil(got.byteLength / 1024)} KB, over the 2 MB logo limit; add a smaller logo.`);
+    if (!type) notes.push(`The logo in the file is a .${ext} picture, which a deck cannot show: add it as PNG or SVG.`);
+    else if (declared > MAX_LOGO_BYTES) notes.push(`The logo in the file is ${Math.ceil(declared / 1024)} KB, over the 2 MB limit: add a smaller one.`);
+    else if (!got) notes.push("No logo was found in the file: add one.");
+    else if (got.byteLength > MAX_LOGO_BYTES) notes.push(`The logo in the file is ${Math.ceil(got.byteLength / 1024)} KB, over the 2 MB limit: add a smaller one.`);
     else logo = { bytes: got, type, via: "slide master" };
-  } else notes.push("The slide master has no picture, so no logo was found; add one with set_brand { logoUrl }.");
+    if (!logo) details.push(`slide master picture ${media}`);
+  } else notes.push("No logo was found in the file: add one.");
   const company = files["docProps/app.xml"] && /<Company>([^<]+)<\/Company>/.exec(xmlText(files["docProps/app.xml"]))?.[1]?.trim();
-  return { name: company ? decodeEntities(company).slice(0, 60) : undefined, colors, fonts, logo, logoCandidates: [], notes, source: { kind: "pptx", ref: fileName } };
+  return { name: company ? decodeEntities(company).slice(0, 60) : undefined, colors, fonts, logo, logoCandidates: [], notes, details, source: { kind: "pptx", ref: fileName } };
 }
 
 // ---- PDF -------------------------------------------------------------------
@@ -849,12 +855,13 @@ export function extractPdf(bytes, fileName = "document.pdf") {
   if (second) colors.accent2 = second.hex;
 
   const notes = /** @type {string[]} */ ([]);
-  notes.push(families.size ? `Fonts are the ones embedded in ${fileName}.` : `${fileName} embeds no fonts we could read.`);
-  const skipped = undecoded ? ` (${undecoded} compressed stream${undecoded > 1 ? "s" : ""} could not be decoded)` : "";
-  if (painted) notes.push(`Colours sampled from what the first pages paint${paper ? "" : "; no page background was drawn, so paper is white"}${skipped}: check them in the preview.`);
-  else notes.push(`No colours could be read from ${fileName}'s pages${skipped}; set them with set_brand.`);
-  notes.push("A PDF does not say which picture is the logo; add one with set_brand { logoUrl } or --logo.");
-  return { colors, fonts, logoCandidates: [], notes, source: { kind: "pdf", ref: fileName } };
+  const details = [];
+  if (!families.size) notes.push("No fonts could be read from the file: pick them by hand.");
+  if (undecoded) details.push(`${undecoded} compressed stream${undecoded > 1 ? "s" : ""} could not be decoded`);
+  if (painted) notes.push(`Colours were picked from the first pages${paper ? "" : " (they draw no background, so it is white)"}: check them in the sample.`);
+  else notes.push("No colours could be read from the file: pick them by hand.");
+  notes.push("A PDF doesn't say which picture is the logo: add one.");
+  return { colors, fonts, logoCandidates: [], notes, details, source: { kind: "pdf", ref: fileName } };
 }
 
 // Whether a draft read anything worth saving: a colour (beyond the white page
@@ -914,6 +921,8 @@ const CLASS_PAIRING = { serif: "editorial", geometric: "geometric", friendly: "f
 // A serif body reads best as the literary pairing's body.
 const BODY_PAIRING = { serif: "literary" };
 
+const ROLE_WORDS = { display: "titles", body: "body text", mono: "labels" };
+
 // The draft's fonts as Google Fonts families. A family Google serves is kept
 // (with Google's spelling); any other maps to the closest pairing's family for
 // that role, with a note saying so. isGoogleFont(family) -> boolean | Promise.
@@ -949,7 +958,7 @@ export async function resolveFonts(fonts = {}, { isGoogleFont } = {}) {
     const p = FONT_PAIRINGS.find((x) => x.id === id);
     pairing ??= p;
     out[role] = p[role];
-    notes.push(`${family} is not on Google Fonts, so ${role} uses ${p[role]} (the "${p.id}" pairing), the closest match.`);
+    notes.push(`${family} isn't a Google Font, so ${ROLE_WORDS[role]} use${role === "body" ? "s" : ""} ${p[role]}, the closest match.`);
   }
   if (!out.mono) {
     const p =
@@ -959,9 +968,9 @@ export async function resolveFonts(fonts = {}, { isGoogleFont } = {}) {
       FONT_PAIRINGS.find((x) => x.body === out.body) ??
       FONT_PAIRINGS.find((x) => x.id === "inter");
     out.mono = p.mono;
-    notes.push(`No monospace font found; labels use ${p.mono} (the "${p.id}" pairing).`);
+    notes.push(`No label font was found, so labels use ${p.mono}.`);
   }
-  for (const f of new Set(unconfirmed)) notes.push(`Could not check that ${f} is on Google Fonts (the check failed), so it is kept as found; if the preview shows a fallback font, pick another.`);
+  for (const f of new Set(unconfirmed)) notes.push(`Couldn't check that ${f} is a Google Font, so it is kept: if the sample shows a fallback font, pick another.`);
   // A role the source left empty takes the other's family.
   if (!out.display && out.body) out.display = out.body;
   if (!out.body && out.display) out.body = out.display;
@@ -972,6 +981,7 @@ export async function resolveFonts(fonts = {}, { isGoogleFont } = {}) {
 // fields: Convex refuses them).
 export function draftArgs(x) {
   const args = { source: x.source, colors: x.colors, fonts: x.fonts, notes: x.notes };
+  if (x.details?.length) args.details = x.details;
   if (x.name) args.name = x.name;
   if (x.logo?.bytes) {
     args.logoBytes = x.logo.bytes.slice().buffer;

package/src/brandPreview.mjs

@@ -7,11 +7,15 @@
 import { applyBrand } from "./brand.mjs";
 import { assembleLayoutDeck } from "./layouts.mjs";
 
+const SAMPLE_CSS = ".hd-embedded :is(.hd-gate, .hd-controls, .hd-chapters, .hd-presenter, .hd-slide-note, .hd-note, .hd-flash) { display: none !important; }";
+// The slides a sample shows, each whole in its own 16:9 frame.
+export const SAMPLE_SLIDES = ["hero", "features"];
+
 const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 
 export function brandPreviewHtml(draft, { saved = false } = {}) {
   const name = (draft?.name ?? "").trim() || "Your brand";
-  let html = assembleLayoutDeck({ slug: "brand-preview", title: name, layouts: ["hero", "features"] })["index.html"];
+  let html = assembleLayoutDeck({ slug: "brand-preview", title: name, layouts: SAMPLE_SLIDES })["index.html"];
   // The hero's art slot is a stand-in a real deck fills; the preview has no art.
   html = html.replace(/\s*<div class="art" role="presentation"><\/div>/, "");
   html = html.replace(/(<div class="kicker">)brand-preview(<\/div>)/, saved ? "$1Your brand$2" : "$1Brand preview$2");
@@ -19,6 +23,9 @@ export function brandPreviewHtml(draft, { saved = false } = {}) {
     "One sentence on what this deck is about.",
     saved ? "Your colours, fonts and logo on a sample slide. Every new deck starts from this." : "Your colours, fonts and logo on a sample slide. Nothing is saved until you say yes.",
   );
+  // Framed on the Brand page (one iframe per slide, #scene=hero / #scene=features),
+  // the sample is a picture of the slide: no play gate, controls or presenter.
+  html = html.replace("</head>", () => `<style data-brand-sample>${SAMPLE_CSS}</style>\n</head>`);
   html = html.replace(/<title>[^<]*<\/title>/, () => `<title>${escapeHtml(name)} · ${saved ? "brand" : "brand preview"}</title>`);
   return applyBrand(html, { name: draft?.name ?? undefined, colors: draft?.colors ?? {}, fonts: draft?.fonts ?? {}, logoUrl: draft?.logoUrl ?? undefined });
 }

package/src/check.mjs

@@ -119,7 +119,7 @@ export function resolveDeckDir(arg, cwd = process.cwd()) {
 // following symlinks). Anything that climbs out is refused, so release never
 // uploads a file from elsewhere on the machine.
 export function deckFileResolver(deckDir) {
-  const root = realpathSync(deckDir);
+  const pathExists = deckPathResolver(deckDir);
   return (ref) => {
     let clean;
     try {
@@ -127,6 +127,14 @@ export function deckFileResolver(deckDir) {
     } catch {
       return false;
     }
+    return pathExists(clean);
+  };
+}
+
+// The same answer for an already-decoded path; `kind: "dir"` asks about a folder instead.
+export function deckPathResolver(deckDir, { kind = "file" } = {}) {
+  const root = realpathSync(deckDir);
+  return (clean) => {
     const path = isAbsolute(clean) ? join(root, clean) : resolve(root, clean);
     const inside = (p) => p === root || p.startsWith(root + sep);
     if (!inside(path)) return "outside";
@@ -134,7 +142,17 @@ export function deckFileResolver(deckDir) {
     const real = realpathSync(path);
     if (!inside(real)) return "outside";
     if (relative(root, real).split(sep).some((part) => part.startsWith("."))) return "outside";
-    return lstatSync(real).isFile();
+    return kind === "dir" ? lstatSync(real).isDirectory() : lstatSync(real).isFile();
+  };
+}
+
+// What deckFiles needs to walk a deck folder: whether a path is a file or a
+// folder inside it, and a file's text.
+export function deckFolder(deckDir) {
+  return {
+    pathExists: deckPathResolver(deckDir),
+    isDir: deckPathResolver(deckDir, { kind: "dir" }),
+    read: (path) => readFileSync(join(deckDir, path), "utf8"),
   };
 }
 
@@ -144,7 +162,7 @@ export async function checkDeck(dirArg, opts = {}, { fetch: fetchImpl = globalTh
   const html = readFileSync(join(deckDir, "index.html"), "utf8");
   const scriptPath = join(deckDir, "script.md");
   const script = existsSync(scriptPath) ? readFileSync(scriptPath, "utf8") : "";
-  const { manifest, ...result } = await checkSources({ html, script }, { ...opts, hosted: false, exists: deckFileResolver(deckDir) }, { fetch: fetchImpl });
+  const { manifest, ...result } = await checkSources({ html, script }, { ...opts, hosted: false, exists: deckFileResolver(deckDir), ...deckFolder(deckDir) }, { fetch: fetchImpl });
   const { errors, warnings } = result;
   // A presenter over the title is a warning, not a failure: only a person can
   // judge it. A slide that overflows the phone card is an error. Both need a

package/src/checkRules.mjs

@@ -36,6 +36,10 @@ export const MESSAGES = {
   localRef: (ref) => `local reference does not resolve: ${ref}`,
   outsideRef: (ref) => `local reference leaves the deck folder: ${ref}`,
   hostedRef: (ref) => `local reference ${ref}: a hosted deck has no folder, so every file must be a URL; upload it with upload_deck_asset and use the URL it returns`,
+  scriptRef: (ref, from) => `${from} names ${ref}, which is not in the deck folder; add the file or fix the path`,
+  // Warnings: deliberate sometimes (a path built from a CDN base), so the deck still passes.
+  scriptTemplate: (from, samples) => `${from} builds file paths at runtime (${samples.slice(0, 3).join(", ")}${samples.length > 3 ? ", …" : ""}); release can't see them, so they 404 on the shared link. Write each file out as a quoted path (an object or array of "media/…" strings, in a script or a .json file it fetches) and pick from that`,
+  scriptComputed: (from, calls) => `${from} loads files from computed values (${calls.join(", ")}); release only ships files the deck names literally, so make sure each file it can load is written out as a quoted path in index.html, a script or a .json file the deck loads`,
   forbidden: (phrase, where) => `forbidden phrase "${phrase}" appears in ${where}`,
   note: (id) => `slide ${id}: needs a data-note naming the source of its facts`,
   mobileTitle: (id, title) => `slide ${id}: title "${title}" is over ${MOBILE_TITLE_CHARS} characters and needs a data-title-mobile`,
@@ -61,7 +65,7 @@ export const MESSAGES = {
 };
 
 // The framed player's slide card on a phone (player.css): the screen less the
-// 52px masthead, the 56px dock and 8px gutters.
+// 60px masthead, the 48px dock and 8px gutters.
 export const HOSTED_LAYOUT_WHY = "presenter overlap and phone fit need a browser: run review_deck with draft=true";
 export const PHONE = { width: 390, height: 844, card: { width: 374, height: 736 } };
 
@@ -295,6 +299,173 @@ export function localRefs(html) {
   return [...new Set(refs.filter((r) => !/^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(r) && !r.endsWith("/")))];
 }
 
+// Files a deck's own scripts load. `play` serves the folder, so any path a
+// script asks for resolves; a released deck is uploaded file by file and its
+// text rewritten to storage URLs, so a file only a script names has to be found
+// here to ship, and a path built at runtime can't be rewritten at all.
+
+// Extensions a quoted string must end in to count as a deck file.
+const ASSET_EXT = /\.(?:json|csv|txt|vtt|mp3|m4a|aac|wav|ogg|opus|flac|mp4|m4v|webm|mov|png|jpe?g|webp|avif|gif|svg|ico|pdf|glb|gltf|bin|wasm|m?js|css|woff2?|ttf|otf|eot)$/i;
+const SCHEME = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
+const stripQuery = (s) => s.split("#")[0].split("?")[0];
+const isScriptPath = (s) => !/[\s<>"'`(){}|\\^*]/.test(s) && !SCHEME.test(s) && ASSET_EXT.test(stripQuery(s));
+const dirOf = (path) => path.slice(0, path.lastIndexOf("/") + 1);
+
+// `ref` against the folder `dir` ("" for the deck root), as a decoded path
+// inside the deck; null when it climbs out or does not decode. A leading "/"
+// means the deck root, which is where `play` serves it from.
+export function deckPath(dir, ref) {
+  let clean;
+  try {
+    clean = decodeURIComponent(stripQuery(ref.trim()));
+  } catch {
+    return null;
+  }
+  const parts = clean.startsWith("/") ? [] : dir.split("/").filter(Boolean);
+  for (const p of clean.split("/")) {
+    if (!p || p === ".") continue;
+    if (p !== "..") parts.push(p);
+    else if (!parts.pop()) return null;
+  }
+  return parts.join("/") || null;
+}
+
+// A JavaScript source's string literals, comments skipped: { value, interpolated }
+// for each, plus `code`, the source with every string emptied, so a call can be
+// read without its arguments' text getting in the way.
+export function jsStrings(src) {
+  const strings = [];
+  let code = "";
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i];
+    if (c === "/" && src[i + 1] === "/") {
+      const end = src.indexOf("\n", i);
+      i = end < 0 ? src.length : end;
+    } else if (c === "/" && src[i + 1] === "*") {
+      const end = src.indexOf("*/", i + 2);
+      i = end < 0 ? src.length : end + 2;
+    } else if (c === '"' || c === "'" || c === "`") {
+      let j = i + 1;
+      let depth = 0;
+      let interpolated = false;
+      while (j < src.length) {
+        const d = src[j];
+        if (d === "\\") j += 2;
+        else if (c === "`" && depth === 0 && d === "$" && src[j + 1] === "{") { interpolated = true; depth = 1; j += 2; }
+        else if (depth > 0) { depth += d === "{" ? 1 : d === "}" ? -1 : 0; j++; }
+        else if (d === c || (c !== "`" && d === "\n")) break;
+        else j++;
+      }
+      strings.push({ value: src.slice(i + 1, j), interpolated });
+      code += c + c;
+      i = j + 1;
+    } else {
+      code += c;
+      i++;
+    }
+  }
+  return { strings, code };
+}
+
+// A template string that builds a local file path: every static piece is
+// path-like, and there is a folder in front of the interpolation or a file
+// extension after it (`media/lines/${id}.mp3`, `${dir}/clip.mp4`).
+function templatePath(raw) {
+  const pieces = raw.split(/\$\{(?:[^{}]|\{[^{}]*\})*\}/);
+  if (pieces.length < 2 || pieces.some((p) => !/^[\w./-]*$/.test(p))) return false;
+  const [head, tail] = [pieces[0], pieces.at(-1)];
+  if (SCHEME.test(head)) return false;
+  return head.includes("/") || ASSET_EXT.test(tail);
+}
+
+// Calls that load a file from a value check can't read.
+// `code` has every string emptied, so a value starts with a name or call, or
+// with an emptied string joined by + ('media/' + id + '.mp3').
+const COMPUTED = "(?:(?![\\s)\"'`])|([\"'`])\\1\\s*\\+)";
+const COMPUTED_LOADS = [
+  { name: "fetch(…)", re: new RegExp(String.raw`(?<![\w$.])fetch\s*\(\s*` + COMPUTED) },
+  { name: "new Audio(…)", re: new RegExp(String.raw`\bnew\s+Audio\s*\(\s*` + COMPUTED) },
+  { name: ".src = …", re: new RegExp(String.raw`\.src\s*=\s*(?!=)(?!URL\.createObjectURL)` + COMPUTED) },
+];
+
+// Every file the released page needs, following references through the files
+// it bundles: index.html's own refs (localRefs), the paths quoted in its inline
+// scripts, and in each bundled .js or .json the quoted paths, in each .css its
+// url()s and @imports, until nothing new turns up. A script path resolves against
+// the page first (that is how fetch() and Audio resolve; an ES import resolves
+// against its module, so a same-named file at the root wins, as it does in the
+// importer's rewrite) and then the script's own folder; a stylesheet's against
+// its own folder first. A quoted path counts only when it names a real file, so
+// ordinary strings never get bundled.
+//
+// `pathExists(path)` answers for a decoded deck-relative path: true, false, "outside"
+// or "hosted"; `read(path)` returns a file's text (omitted for a hosted deck,
+// which has no folder); `isDir(path)` lets a quoted path in a real subfolder
+// that names no file be reported as missing (one at the deck root could be
+// anything, a vendored library's own "./worker.js" say, so it is left alone).
+// Returns { files: [{ path, from }], missing: [{ ref, from }], templates: [{ from, samples }], computed: [{ from, calls }] }:
+// `from` is "html" for index.html's own attribute refs, "index.html" for a path
+// quoted in its inline scripts, or the bundled file that named it.
+export function deckFiles(html, { pathExists: exists = () => false, read, isDir = () => false } = {}) {
+  const files = new Map();
+  const queue = [];
+  const missing = [];
+  const templates = [];
+  const computed = [];
+  const add = (path, from) => {
+    if (files.has(path)) return;
+    files.set(path, from);
+    queue.push(path);
+  };
+  for (const ref of localRefs(html)) {
+    const path = deckPath("", ref);
+    if (path) add(path, "html");
+  }
+  // `url` is true for a CSS url()/@import, which is a file reference whatever its extension.
+  const quoted = (value, from, dirs, { url = false } = {}) => {
+    if (url ? !value || SCHEME.test(value) || value.startsWith("#") : !isScriptPath(value)) return;
+    const candidates = [...new Set(dirs.map((d) => deckPath(d, value)).filter(Boolean))];
+    const found = candidates.find((p) => exists(p) === true);
+    // Missing only where the browser would look (the page for a script, the
+    // stylesheet's folder for CSS), and only in a real subfolder there.
+    if (found) add(found, from);
+    else if (candidates.length && candidates.every((p) => exists(p) === false) && dirOf(candidates[0]) && isDir(dirOf(candidates[0])) && !missing.some((m) => m.ref === value && m.from === from)) missing.push({ ref: value, from });
+  };
+  const scanJs = (src, from, dir, { json = false } = {}) => {
+    const { strings, code } = jsStrings(src);
+    if (json) {
+      for (const s of strings) quoted(s.value, from, ["", dir]);
+      return;
+    }
+    const built = [];
+    for (const s of strings) {
+      if (!s.interpolated) quoted(s.value, from, ["", dir]);
+      else if (templatePath(s.value)) built.push(`\`${s.value}\``);
+    }
+    if (built.length) templates.push({ from, samples: [...new Set(built)] });
+    const calls = COMPUTED_LOADS.filter((l) => l.re.test(code)).map((l) => l.name);
+    if (calls.length) computed.push({ from, calls });
+  };
+  for (const [, attrs, body] of uncommented(html).matchAll(/<script\b([^>]*)>([\s\S]*?)<\/script>/gi)) {
+    if (!/\ssrc\s*=/i.test(attrs) && !/\stype\s*=\s*["']?(?:application\/(?:ld\+)?json|importmap)/i.test(attrs)) scanJs(body, "index.html", "");
+  }
+  while (read && queue.length) {
+    const path = queue.shift();
+    if (!/\.(?:m?js|css|json)$/i.test(path) || exists(path) !== true) continue;
+    const text = read(path);
+    const dir = dirOf(path);
+    if (/\.css$/i.test(path)) {
+      const css = text.replace(/\/\*[\s\S]*?\*\//g, "");
+      for (const m of css.matchAll(/url\(\s*(?:"([^"]*)"|'([^']*)'|([^)'"\s]+))\s*\)|@import\s+(?:"([^"]*)"|'([^']*)')/gi)) {
+        const ref = m[1] ?? m[2] ?? m[3] ?? m[4] ?? m[5];
+        quoted(ref.trim(), path, [dir, ""], { url: true });
+      }
+    } else scanJs(text, path, dir, { json: /\.json$/i.test(path) });
+  }
+  return { files: [...files].map(([path, from]) => ({ path, from })), missing, templates, computed };
+}
+
 export function phraseList(value) {
   if (!value) return [];
   if (typeof value === "string") return value.split(",").map((s) => s.trim()).filter(Boolean);
@@ -414,9 +585,9 @@ export function timelineErrors(clip, timeline) {
   captions.forEach((c, i) => {
     if (!(c.start >= 0 && c.end > c.start && c.end <= duration + 0.1)) errs.push(MESSAGES.timing(clip.id, i, c.start, c.end, duration));
   });
-  // Caption text carries the script's spelling; the timed words carry the
-  // transcript's (which may spell a name differently, as the narrate guard's
-  // pronunciation map allows), so coverage is checked on the text.
+  // Caption text carries the script's spelling; the timed words of an older
+  // clip carry the transcript's (which may spell a name differently, as the
+  // narrate guard's pronunciation map allows), so coverage is checked on the text.
   const covered = captions.map((c) => String(c.text ?? "")).join(" ");
   const timed = captions.every((c) => Array.isArray(c.words) && c.words.length);
   if (!timed || normalizeWords(covered) !== normalizeWords(String(clip.text ?? ""))) errs.push(MESSAGES.words(clip.id));
@@ -547,6 +718,9 @@ export async function checkSources({ html, script = "" }, opts = {}, { fetch: fe
   }
   const exists = opts.hosted ? () => "hosted" : (opts.exists ?? (() => true));
   const errors = htmlErrors(html, { exists, forbid, script, hosted: !!opts.hosted });
+  // 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));
   const ids = slides(html).map((s) => s.id);
   const player = playerScript(html);
   let manifest = null;
@@ -602,6 +776,8 @@ export async function checkSources({ html, script = "" }, opts = {}, { fetch: fe
     }
   }
   const warnings = transitionWarnings(html, script, manifest);
+  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) {
     for (const url of absoluteRefs(html)) if (!isHostedAsset(url) && /\.(png|jpe?g|gif|webp|avif|svg|mp4|webm|mov)(\?|#|$)/i.test(url)) warnings.push(MESSAGES.hotlink(url));
     warnings.push(MESSAGES.layoutUnchecked(HOSTED_LAYOUT_WHY));

package/src/commands.mjs

@@ -322,6 +322,9 @@ commands:
                    file an image, video or font under the deck; prints its hosted URL
   guide [workflow|format|script|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]
+                   play the folder as it is, committed or not, with its real face and voice, on 127.0.0.1
+                   until Ctrl-C; nothing is written, uploaded or shared, and changed lines need narrate first
   release <slug|deck-dir> [--to "<name>" [--email <e>]]... [--qa] [--no-notify] [--title t] [--voice v] [--captions-only (--hosted)]
                    on a committed deck: check → narrate → import → share new per --to
   share new|list|on|off|forward|mute|unmute|rm|url
@@ -362,6 +365,12 @@ commands:
   brand import <url|file|slug> [--json]
                    read a brand from your website, a .pptx / .potx / .pdf or one of your decks: shows its
                    colours, fonts and logo and a preview link; save it with brand set --draft <token>
+  brand revise "<change>" [--json]
+                   a draft of your brand with that change ("darker accent, serif titles") and a
+                   preview link; save it with brand set --draft <token>
+  brand history    the brand's last changes, from the dashboard, chat or here
+  brand undo [<version>]
+                   undo the last change, or go back to a version from brand history
   brand edit       edit design.md (voice, do and don't) in $EDITOR
   brand fonts      the curated font pairings (display + body + mono)
   brand clear      forget the brand; new decks get the template look
@@ -393,7 +402,7 @@ commands:
   avatar connect           import your avatar from Minimoji with a code you enter on minimoji.com
   avatar default <name|id|dash>   make it the default
   avatar remove <name|id>  remove it; decks already shared keep working, captions only
-  deck avatar <slug> <name|id|none|default>   the deck's own presenter (applies at its next release)
+  deck avatar <slug> <name|id|none|default>   the deck's own presenter (play and the draft link now; share links at its next release)
   narrator [--json]        who narrates your decks (a face plus a voice) and the default
   narrator new             a link where you pick a face and a voice; it becomes the default
   narrator default <name|id|dash>   make it the default
@@ -693,6 +702,13 @@ function commandTable(pos, rest, opts) {
       const out = await release(pos.slice(1), opts, opts.json ? { log: (line) => console.error(line) } : {});
       if (opts.json) console.log(JSON.stringify(out, null, 2));
     },
+    play: async () => {
+      const { play } = await import("./play.mjs");
+      await play(pos.slice(1), opts, opts.json ? {
+        log: (line) => console.error(line),
+        started: ({ url, slug, deckDir, presenter, who }) => console.log(JSON.stringify({ url, slug, deckDir, presenter, who })),
+      } : {});
+    },
     narrate: async () => {
       const { narrate } = await import("./narrate.mjs");
       const result = await narrate(pos.slice(1), opts, opts.json ? { log: (line) => console.error(line) } : {});
@@ -774,7 +790,7 @@ function commandTable(pos, rest, opts) {
     "deck avatar": async () => {
       if (rest.length < 2) throw new Error("usage: deck avatar <slug> <name|id|none|default>");
       const out = await ops.setDeckAvatar(opts, rest[0], rest.slice(1).join(" "));
-      console.log(opts.json ? JSON.stringify(out, null, 2) : `OK ${out.slug} → ${out.avatar} (applies at its next release)`);
+      console.log(opts.json ? JSON.stringify(out, null, 2) : `OK ${out.slug} → ${out.avatar} (play and the draft link now; share links at its next release)`);
     },
     narrator: async () => {
       const { narratorList } = await import("./narrator.mjs");
@@ -819,7 +835,7 @@ function commandTable(pos, rest, opts) {
     "deck narrator": async () => {
       if (rest.length < 2) throw new Error("usage: deck narrator <slug> <name|id|none|default>");
       const out = await ops.setDeckNarrator(opts, rest[0], rest.slice(1).join(" "));
-      console.log(opts.json ? JSON.stringify(out, null, 2) : `OK ${out.slug} → ${out.narrator} (applies at its next narrate and release)`);
+      console.log(opts.json ? JSON.stringify(out, null, 2) : `OK ${out.slug} → ${out.narrator} (voice at its next narrate; face in play and the draft link now, on share links at its next release)`);
     },
     "preview setup": async () => {
       const { setupCapture } = await import("./preview-capture.mjs");
@@ -872,6 +888,9 @@ function commandTable(pos, rest, opts) {
     "brand fonts": async () => (await import("./brandCli.mjs")).brandFonts(opts),
     "brand clear": async () => (await import("./brandCli.mjs")).brandClear(opts),
     "brand import": async () => (await import("./brandCli.mjs")).brandImport(rest[0], opts),
+    "brand revise": async () => (await import("./brandCli.mjs")).brandRevise(rest, opts),
+    "brand history": async () => (await import("./brandCli.mjs")).brandHistory(opts),
+    "brand undo": async () => (await import("./brandCli.mjs")).brandUndo(rest[0], opts),
     review: () => review(pos.slice(1), opts),
     "review-job": () => reviewJob(pos.slice(1), opts),
     poster: () => poster(pos.slice(1), opts),

package/src/importer.mjs

@@ -180,6 +180,33 @@ export function rewriteHtmlAssetUrls(html, htmlEntry, assets, uploadedByName) {
   return rewriteTextRefs(rewriteCssUrls(out, assetMap), assetMap);
 }
 
+// One text asset rewritten against the uploaded URLs.
+export function rewriteTextAsset(asset, assets, uploadedByName) {
+  const text = textFromBytes(asset.data);
+  return asset.contentType === "text/css"
+    ? rewriteCssAssetUrls(text, asset.sourcePath, assets, uploadedByName)
+    : rewriteTextAssetUrls(text, asset.sourcePath, assets, uploadedByName);
+}
+
+// The text assets in the order they can be saved: each round holds the ones
+// that name no text asset still unsaved. Saving a name again deletes its old
+// copy, so a script rewritten before the file it fetches is saved would embed a
+// dead URL. A cycle (two scripts naming each other) goes last as one round, its
+// refs to each other left relative.
+export function textAssetRounds(assets) {
+  const PENDING = "hd-pending:";
+  const rounds = [];
+  let pending = assets.filter(isTextAsset);
+  while (pending.length) {
+    const marks = new Map(pending.map((a) => [a.name, PENDING + a.name]));
+    const ready = pending.filter((a) => !rewriteTextAsset(a, assets, marks).split(PENDING + a.name).join("").includes(PENDING));
+    const round = ready.length ? ready : pending;
+    rounds.push(round);
+    pending = pending.filter((a) => !round.includes(a));
+  }
+  return rounds;
+}
+
 export function isTextAsset(asset) {
   const type = String(asset.contentType || "").split(";")[0].trim().toLowerCase();
   return type.startsWith("text/") || TEXT_TYPES.has(type);
@@ -206,12 +233,23 @@ function rewriteCssUrls(input, assetMap) {
   });
 }
 
+// Quoted strings that name an uploaded file. A pair that names nothing gives
+// up only its opening quote, so one apostrophe ("Don't stop", a data-note's
+// "company's") can't throw the pairing off for every path after it.
 function rewriteTextRefs(input, assetMap) {
-  return rewriteEscapedTextRefs(input, assetMap).replace(/(["'`])([^"'`]+)\1/g, (match, quote, raw) => {
-    if (quote === "`" && raw.includes("${")) return match;
-    const url = resolveLocalUrl(raw, assetMap);
-    return url ? `${quote}${url}${quote}` : match;
-  });
+  const text = rewriteEscapedTextRefs(input, assetMap);
+  const pair = /(["'`])([^"'`]+)\1/g;
+  let out = "";
+  let from = 0;
+  for (let m = pair.exec(text); m; m = pair.exec(text)) {
+    const [match, quote, raw] = m;
+    const url = !(quote === "`" && raw.includes("${")) && resolveLocalUrl(raw, assetMap);
+    if (url) {
+      out += `${text.slice(from, m.index)}${quote}${url}${quote}`;
+      from = m.index + match.length;
+    } else pair.lastIndex = m.index + 1;
+  }
+  return out + text.slice(from);
 }
 
 function rewriteEscapedTextRefs(input, assetMap) {

package/src/ops.mjs

@@ -6,10 +6,10 @@ import {
   bytesFromText,
   isTextAsset,
   prepareDeckImport,
-  rewriteCssAssetUrls,
   rewriteHtmlAssetUrls,
-  rewriteTextAssetUrls,
+  rewriteTextAsset,
   slugify,
+  textAssetRounds,
   textFromBytes,
   titleFromFilename,
 } from "./importer.mjs";
@@ -585,23 +585,24 @@ export async function importDeckFromBytes(opts = {}, fields = {}, adapter = {})
       deckCreated = true;
     }
 
-    // Phase 1: upload every asset and fully populate uploadedByName.
-    await mapWithConcurrency(parsed.assets, concurrency, async (asset, index) => {
+    // Phase 1: upload every binary asset.
+    const binary = parsed.assets.filter((a) => !isTextAsset(a));
+    await mapWithConcurrency(binary, concurrency, async (asset, index) => {
       onStage(`uploading asset ${index + 1}/${parsed.assets.length}: ${asset.name}`);
       await saveDeckAsset(asset);
     });
 
-    // Phase 2 (hard barrier after phase 1): rewrite text assets against the now-
-    // complete URL map and re-upload them under the same name. Must not interleave
-    // with phase 1 or refs could resolve against a half-built map.
-    const textAssets = parsed.assets.filter(isTextAsset);
-    await mapWithConcurrency(textAssets, concurrency, async (asset, index) => {
-      onStage(`rewriting asset ${index + 1}/${textAssets.length}: ${asset.name}`);
-      const text = asset.contentType === "text/css"
-        ? rewriteCssAssetUrls(textFromBytes(asset.data), asset.sourcePath, parsed.assets, uploadedByName)
-        : rewriteTextAssetUrls(textFromBytes(asset.data), asset.sourcePath, parsed.assets, uploadedByName);
-      await saveDeckAsset(asset, bytesFromText(text), asset.contentType);
-    });
+    // Phase 2 (after phase 1): text assets, rewritten against the URLs saved so
+    // far, each after the text assets it names (textAssetRounds). Saving a name
+    // twice deletes the first copy, so a script must never embed a URL from a
+    // save that a later save replaces.
+    let done = binary.length;
+    for (const round of textAssetRounds(parsed.assets)) {
+      await mapWithConcurrency(round, concurrency, async (asset) => {
+        onStage(`uploading asset ${++done}/${parsed.assets.length}: ${asset.name}`);
+        await saveDeckAsset(asset, bytesFromText(rewriteTextAsset(asset, parsed.assets, uploadedByName)), asset.contentType);
+      });
+    }
 
     onStage("storing deck HTML");
     const html = rewriteHtmlAssetUrls(parsed.html, parsed.htmlEntry, parsed.assets, uploadedByName);
@@ -964,6 +965,11 @@ export async function presenterFor(opts, slug, voice) {
   return (await client(opts)).query(api.avatars.presenterFor, { slug, ...(voice ? { voice: String(voice) } : {}) });
 }
 
+// The same answer as presenterFor plus who presents in words: { presenter, who }.
+export async function presenterWithReason(opts, slug, voice) {
+  return (await client(opts)).query(api.avatars.presenterWithReason, { slug, ...(voice ? { voice: String(voice) } : {}) });
+}
+
 // ---- narrators (convex/narrators.ts) ------------------------------------------
 // Who narrates your decks: a face plus a voice. D.A.S.H. is built in. As with
 // avatars, an agent never adds one: `narrator new` hands back a link.
@@ -1155,6 +1161,26 @@ export async function importBrand(opts, { url, slug, bytes, fileName } = {}) {
   return c.action(api.brandNode.createDraft, draftArgs(extractFile(data, fileName)));
 }
 
+// Revise the brand with a prompt ("darker accent, serif titles"): a draft
+// like importBrand's, with a previewUrl; nothing is saved until
+// setBrand({ draft: token }).
+export async function reviseBrand(opts, { instruction } = {}) {
+  const ask = String(instruction ?? "").trim();
+  if (!ask) throw new Error('say what to change, e.g. "make the accent darker and use a serif for titles"');
+  return (await client(opts)).action(api.brandRevise.revise, { instruction: ask });
+}
+
+// The brand's last changes, newest first (the first is the brand now).
+export async function brandHistory(opts = {}) {
+  return { versions: await (await client(opts)).query(api.brand.history, {}) };
+}
+
+// Undo the brand's last change, or go back to one version from brandHistory.
+export async function undoBrand(opts = {}, { version } = {}) {
+  const c = await client(opts);
+  return version ? c.mutation(api.brand.restore, { version: String(version) }) : c.mutation(api.brand.undo, {});
+}
+
 export async function clearBrand(opts = {}) {
   await (await client(opts)).mutation(api.brand.clear, {});
   return { cleared: true };

package/src/play.mjs

@@ -0,0 +1,119 @@
+// hyperdecks play <slug|deck-dir> [--voice v] [--slug s] [--port n] [--no-open] [--json]
+//
+// Plays the working folder as it is, committed or not, the way it will play once
+// released: the owner's face goes on the player tag of the page it serves, in
+// memory only. It writes no file, uploads nothing, creates no share and renders
+// no audio, so it plays the manifest index.html already points at; changed lines
+// need `narrate` first. The server listens on 127.0.0.1 behind a random path until
+// Ctrl-C. The deck's script.md and evidence.md are not served (preview-capture.mjs
+// serves only the file types a page loads).
+import { readFileSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+import { playerScript, sectionIds } from "./checkRules.mjs";
+import { resolveDeckDir } from "./check.mjs";
+import * as ops from "./ops.mjs";
+import { playsCaptionsOnly, presenterLine, withAvatar } from "./presenter.mjs";
+import { serveSource } from "./preview-capture.mjs";
+import { openBrowser } from "./runtime.mjs";
+
+const USAGE = "usage: play <slug|deck-dir> [--voice <name|id>] [--slug <slug>] [--port <n>] [--no-open]";
+
+function portOf(value) {
+  if (value === undefined) return 0;
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`--port must be a port number (got ${value})`);
+  return port;
+}
+
+// A path `narrate` and `import` take: the argument to play may be a slug.
+function pathFrom(cwd, deckDir) {
+  const rel = relative(cwd ?? process.cwd(), deckDir);
+  return !rel ? "." : rel.startsWith("..") ? deckDir : rel;
+}
+
+// The face to add, and { who } in words. Never stops the play: without an answer
+// the page plays as written, as a release does when this lookup fails.
+async function lookUpPresenter(opts, { slug, path, html, log }) {
+  const narrate = `hyperdecks narrate ${path}`;
+  const lead = playsCaptionsOnly(html) ? "captions only" : "playing as written";
+  if (!playerScript(html)?.manifest) {
+    log(`⚠ no narration yet, so this plays silent: run \`${narrate}\` first`);
+    return { presenter: null, who: null };
+  }
+  try {
+    const found = await ops.presenterWithReason(opts, slug, opts.voice);
+    if (!found.who) log(`⚠ ${lead}: no finished narration on this account for "${slug}": run \`${narrate}\` first`);
+    return found;
+  } catch (e) {
+    const why = ops.errorText(e);
+    if (/deck not found/.test(why)) log(`⚠ ${lead}: "${slug}" is not on this account yet, so it has no presenter. Register it (\`hyperdecks import ${join(path, "index.html")} --slug ${slug} --status draft\`), then run \`${narrate}\``);
+    else if (/forbidden/.test(why)) log(`⚠ ${lead}: the deck "${slug}" belongs to another account. Log in as its owner, or pass --slug with yours`);
+    else log(`⚠ ${lead}: could not ask who presents (${why}). Your avatar is not the problem; try again, and if it keeps failing this CLI may be newer than the backend`);
+    return { presenter: null, who: null };
+  }
+}
+
+// Says what the served page does, not what the lookup answered.
+function sayWhoPresents({ html, page, presenter, who, log }) {
+  if (presenter && page === html) log("⚠ the player tag already names a presenter, so it plays as written");
+  else if (who?.face && !presenter && playsCaptionsOnly(html)) log(`⚠ captions only: the page names no presenter, and a face for voice "${who.voice}" is not added here`);
+  else if (who) log(presenterLine(who));
+}
+
+// A warning only. An error with text is the backend's answer (the local script
+// differs from the hosted one, a line that won't compile), so it is shown; no
+// script.md, or a backend that could not say, is not worth a line.
+async function warnIfScriptChanged(opts, { slug, deckDir, path, html, who, log }) {
+  try {
+    const script = readFileSync(join(deckDir, "script.md"), "utf8");
+    const plan = await ops.previewNarration(opts, { slug, script, voice: who.voice, sectionIds: sectionIds(html) });
+    const changed = plan.slides.filter((s) => s.render).map((s) => s.id);
+    if (changed.length) log(`⚠ script.md changed since the last narration (${changed.join(", ")}); this plays the old audio. Run \`hyperdecks narrate ${path}\` to hear the new lines`);
+  } catch (e) {
+    if (typeof e?.data === "string") log(`⚠ could not compare script.md with the last narration: ${e.data}`);
+  }
+}
+
+// Starts serving and returns; the caller closes it. `play` is the command.
+export async function startPlay(pos, opts = {}, { log = (line) => console.log(line), open = openBrowser, cwd } = {}) {
+  const [deckDirArg] = pos;
+  if (!deckDirArg) throw new Error(USAGE);
+  for (const k of ["voice", "slug", "port"]) if (k in opts && typeof opts[k] !== "string") throw new Error(`--${k} requires a value`);
+  const port = portOf(opts.port);
+  const deckDir = resolveDeckDir(deckDirArg, cwd);
+  const path = pathFrom(cwd, deckDir);
+  const slug = opts.slug || basename(deckDir);
+  const file = join(deckDir, "index.html");
+  const html = readFileSync(file, "utf8");
+
+  const { presenter, who } = await lookUpPresenter(opts, { slug, path, html, log });
+  const page = presenter ? withAvatar(html, presenter) : html;
+  sayWhoPresents({ html, page, presenter, who, log });
+  // --voice names the voice it was narrated in, so there is nothing to compare it to.
+  if (who && !opts.voice) await warnIfScriptChanged(opts, { slug, deckDir, path, html, who, log });
+
+  let server;
+  try {
+    server = await serveSource({ file, html: page, port });
+  } catch (e) {
+    throw new Error(e?.code === "EADDRINUSE" ? `port ${port} is in use; pick another with --port` : e?.message || String(e));
+  }
+  log(`▶ playing ${slug}: ${server.url}\n  Ctrl-C to stop. Nothing is written, uploaded or shared.`);
+  if (!opts["no-open"]) open(server.url);
+  return { url: server.url, close: server.close, deckDir, slug, presenter: page === html ? null : presenter, who: who ?? null };
+}
+
+export async function play(pos, opts = {}, io = {}) {
+  const session = await startPlay(pos, opts, io);
+  await new Promise((stopped) => {
+    const stop = () => {
+      process.off("SIGINT", stop);
+      process.off("SIGTERM", stop);
+      stopped();
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+    io.started?.(session);
+  });
+  await session.close();
+}

package/src/presenter.mjs

@@ -1,26 +1,33 @@
 // The released deck's presenter (roadmap: avatars-pick-make-from-a-selfie-or-
 // import-your-minimoji). A deck narrated in the owner's own voice is written
 // captions-only (data-presenter="none"); at release, when the owner has an
-// avatar, its player tag gets that face instead. Shared by the hosted release
-// (convex/deckSources.ts) and the CLI's local release (release.mjs), so both
-// rewrite the tag the same way. A tag that already names a presenter (D.A.S.H.
+// avatar, its player tag gets that face instead. Shared by both releases
+// (convex/deckSources.ts, release.mjs), `hyperdecks play` and the /p draft
+// preview, so all rewrite the tag the same way; only a release stores it. A tag that already names a presenter (D.A.S.H.
 // on a character-voice deck, or one set by hand) is left alone.
 
 const PLAYER_TAG = /<script\b[^>]*\bsrc="[^"]*\/player\/v1\/player\.js"[^>]*>/i;
 
 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));
+
+// Whether the page's player tag names nobody, so without a face it has captions only.
+export function playsCaptionsOnly(html) {
+  const tag = PLAYER_TAG.exec(html)?.[0];
+  return !!tag && !/\sdata-avatar=/.test(tag) && noPresenter(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.
 export function withAvatar(html, { avatarUrl, imageUrl }) {
   const tag = PLAYER_TAG.exec(html)?.[0];
   if (!tag || /\sdata-avatar=/.test(tag)) return html;
-  // Captions only: data-presenter="none", or no presenter at all (the player's
-  // default when there is no data-presenter-image either).
+  if (!noPresenter(tag)) return html;
   const none = /\sdata-presenter="none"/.test(tag);
-  const unset = !/\sdata-presenter=/.test(tag) && !/\sdata-presenter-image=/.test(tag);
-  if (!none && !unset) return html;
   const image = imageUrl && !/\sdata-presenter-image=/.test(tag) ? ` 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}>`);

package/src/preview-capture.mjs

@@ -19,7 +19,9 @@ export async function setupCapture(pos, opts) {
 }
 
 // Capability URL + realpath containment; captured code gets no general file server.
-export async function serveSource({ file, html }) {
+// `html` alone serves that page; with `file` it replaces the page and the file's
+// folder still serves the rest (play's in-memory copy with the face on it).
+export async function serveSource({ file, html, port = 0 }) {
   const root = file ? await realpath(dirname(file)) : null;
   const prefix = '/' + randomUUID() + '/';
   const entry = prefix + (file ? encodeURIComponent(resolve(file).split(sep).pop()) : 'index.html');
@@ -27,7 +29,7 @@ export async function serveSource({ file, html }) {
     try {
       const path = decodeURIComponent(new URL(req.url, 'http://localhost').pathname);
       if (req.method !== 'GET' || !path.startsWith(prefix)) { res.writeHead(404).end(); return; }
-      if (!file && path === entry) { res.writeHead(200, { 'Content-Type':'text/html; charset=utf-8', 'Cache-Control':'no-store' }).end(html); return; }
+      if (html != null && path === entry) { res.writeHead(200, { 'Content-Type':'text/html; charset=utf-8', 'Cache-Control':'no-store' }).end(html); return; }
       const rel = path.slice(prefix.length);
       if (!root || rel.split('/').some(s => s.startsWith('.') || s.includes('\\')) || !MIME[extname(rel).toLowerCase()]) { res.writeHead(404).end(); return; }
       const full = await realpath(resolve(root, rel));
@@ -36,7 +38,7 @@ export async function serveSource({ file, html }) {
       res.end(await readFile(full));
     } catch { res.writeHead(404).end(); }
   });
-  await new Promise((ok, fail) => { server.once('error', fail); server.listen(0, '127.0.0.1', ok); });
+  await new Promise((ok, fail) => { server.once('error', fail); server.listen(port, '127.0.0.1', ok); });
   const url = `http://127.0.0.1:${server.address().port}${entry}`;
   return { url, close: () => new Promise((ok, fail) => { server.close(e => e ? fail(e) : ok()); server.closeAllConnections(); }) };
 }

package/src/release.mjs

@@ -12,12 +12,12 @@
 //   5. creates one share per --to (paired in order with --email) and prints the URLs.
 import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
-import { join, posix } from "node:path";
+import { join } from "node:path";
 import { zipSync } from "fflate";
 import * as ops from "./ops.mjs";
 import { withAvatar } from "./presenter.mjs";
 import { target } from "./runtime.mjs";
-import { checkDeck, localRefs, resolveDeckDir } from "./check.mjs";
+import { checkDeck, deckFiles, deckFolder, resolveDeckDir } from "./check.mjs";
 import { narrate as runNarrate } from "./narrate.mjs";
 
 const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
@@ -47,18 +47,23 @@ export function deckCommit(deckDir) {
   return execFileSync("git", ["-C", deckDir, "rev-parse", "--short", "HEAD"], { encoding: "utf8" }).trim();
 }
 
-// What import uploads: the page alone, or a zip of the page and its local files.
+// What import uploads: the page alone, or a zip of the page and its local files:
+// what index.html names, and what the scripts and stylesheets it bundles name in
+// turn (deckFiles). `added` maps each bundled script or stylesheet to the files
+// it brought in, so release can say what came from where.
 // `presenter` (from avatars.presenterFor) puts the owner's avatar on the
 // uploaded page's player tag; the committed index.html is never changed.
 export function releaseBundle(deckDir, presenter = null) {
   const raw = readFileSync(join(deckDir, "index.html"));
   const html = presenter ? Buffer.from(withAvatar(raw.toString("utf8"), presenter)) : raw;
-  // check has already refused refs that leave the folder or do not decode.
-  const refs = [...new Set(localRefs(html.toString("utf8")).map((r) => posix.normalize(decodeURIComponent(r)).replace(/^(\.?\/)+/, "")))];
-  if (!refs.length) return { bytes: html, filename: "index.html", files: ["index.html"] };
+  // check has already refused refs that leave the folder or do not resolve.
+  const found = deckFiles(html.toString("utf8"), deckFolder(deckDir)).files.filter((f) => f.path !== "index.html");
+  const added = {};
+  for (const f of found) if (f.from !== "html") (added[f.from] ??= []).push(f.path);
+  if (!found.length) return { bytes: html, filename: "index.html", files: ["index.html"], added };
   const files = { "index.html": html };
-  for (const ref of refs) files[ref] = readFileSync(join(deckDir, ref));
-  return { bytes: Buffer.from(zipSync(files)), filename: "deck.zip", htmlFile: "index.html", files: Object.keys(files) };
+  for (const f of found) files[f.path] = readFileSync(join(deckDir, f.path));
+  return { bytes: Buffer.from(zipSync(files)), filename: "deck.zip", htmlFile: "index.html", files: Object.keys(files), added };
 }
 
 // From the CLI, parse() collects opts.recipients in order (each --email follows
@@ -86,6 +91,7 @@ export async function release(pos, opts = {}, io = {}) {
   const loose = untracked(deckDir, bundle.files);
   if (loose.length) throw new Error(`refusing to release: git does not track ${loose.join(", ")} (ignored or never added); commit them so the release corresponds to a commit`);
   log(`✓ check passed: ${checked.slides} slides, ${checked.totalDuration}s`);
+  for (const [from, paths] of Object.entries(bundle.added)) log(`  +${paths.length} file(s) referenced from ${from}: ${paths.join(", ")}`);
 
   // Cached slides cost nothing, so this only renders what changed since the commit.
   // Only the options narrate understands: an undefined --slide/--voice key would fail its flag check.

package/src/runtime.mjs

@@ -8,7 +8,7 @@ import { fileURLToPath } from "node:url";
 import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
 
-export const VERSION = "0.7.0";
+export const VERSION = "0.8.1";
 const UPLOAD_TIMEOUT_MS = 125_000;
 
 export const PROD = {
@@ -32,6 +32,7 @@ export const api = {
     createLink: makeFunctionReference("avatars:createLink"),
     getLink: makeFunctionReference("avatars:getLink"),
     presenterFor: makeFunctionReference("avatars:presenterFor"),
+    presenterWithReason: makeFunctionReference("avatars:presenterWithReason"),
   },
   narrators: {
     list: makeFunctionReference("narrators:list"),
@@ -47,7 +48,11 @@ export const api = {
     get: makeFunctionReference("brand:get"),
     set: makeFunctionReference("brand:set"),
     clear: makeFunctionReference("brand:clear"),
+    history: makeFunctionReference("brand:history"),
+    undo: makeFunctionReference("brand:undo"),
+    restore: makeFunctionReference("brand:restore"),
   },
+  brandRevise: { revise: makeFunctionReference("brandRevise:revise") },
   brandNode: {
     importLogo: makeFunctionReference("brandNode:importLogo"),
     uploadLogo: makeFunctionReference("brandNode:uploadLogo"),

package/templates/script.md

@@ -10,8 +10,11 @@ One `## <slide-id>` block per slide, in slide order; the id is the slide's
 phrase (4 to 85 characters, two lines in the bubble). Aim for 150 to 180 s in
 all. Holds: 0.4 s by default, `hold: 1.5` for a number, chart or reveal,
 `hold: 2` on interactive slides. Stage tags become
-cues at the word before them: [wave], [mood: excited], [reveal: #detail],
-[go: #detail] (the presenter flies beside it; [go: slot] brings it home),
+cues at the word before them: [wave], [mood: excited], [reveal: #detail]
+(replays from the start when the slide does; the head glances at it unless
+a [look] or [go] is right beside it),
+[go: #detail] (it grows, its siblings fade and the presenter flies beside it,
+or looks at it when there is no room; [go: slot] brings it home),
 [look: h2] (the head looks at it), [custom: confetti]. `presenterStyle: stage`
 above sets the deck's presenter; `presenter-style: corner` under a heading sets
 one slide's. `transition: drift` above is how every slide enters;