@hypersocial/decks-cli 0.7.0 → 0.8.0

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.0",
   "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` |
@@ -318,6 +322,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
@@ -539,7 +547,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/checkRules.mjs

@@ -414,9 +414,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));

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/ops.mjs

@@ -964,6 +964,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 +1160,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/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.0";
 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"),