@hypersocial/decks-cli 0.6.0 → 0.8.0

package/src/brandPreview.mjs

@@ -0,0 +1,31 @@
+// The page a brand import (brandImport.mjs, convex/brandDrafts.ts) is shown on
+// before it is saved: a hero and a features slide from the layout library, in
+// the draft's colours, fonts and logo (applyBrand, the same code new decks
+// use). Served at /p/brand/<token> (app/p/brand/[token]/route.ts), and with
+// { saved: true } for the saved brand on the dashboard's Brand tab
+// (app/dashboard/brand/sample/route.ts).
+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: 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");
+  html = html.replace(
+    "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

@@ -41,6 +41,8 @@ export const MESSAGES = {
   mobileTitle: (id, title) => `slide ${id}: title "${title}" is over ${MOBILE_TITLE_CHARS} characters and needs a data-title-mobile`,
   slideId: (n) => `slide ${n} has no id`,
   selector: (line, cue, selector, id) => `script.md line ${line}: [${cue}: ${selector}] matches nothing in slide ${id}`,
+  gestureColon: (line, id) => `script.md line ${line}: [gesture ${id}] needs a colon: [gesture: ${id}]`,
+  gesture: (line, id) => `script.md line ${line}: [gesture: ${id}] is not one of the head's gestures: ${GESTURES.join(", ")}`,
   presenterStyle: (where, value) => `${where}: presenter style "${value}" is not one of ${PRESENTER_STYLES.join(", ")}`,
   transition: (where, value) => `${where}: transition "${value}" is not one of ${TRANSITIONS.join(", ")} (zoom takes a selector: "zoom #row")`,
   zoomTarget: (id, target, prev) => `slide ${id}: zoom target "${target}" matches nothing on the slide before it (${prev})`,
@@ -217,8 +219,33 @@ export function selectorMatches(body, selector) {
   });
 }
 
-// [go: <selector>] and [look: <selector>] in script.md must match something in
-// their slide ([go: slot] returns home and always resolves).
+// The Minimoji head's gestures, for [gesture: <id>]: lib/deckScript.ts GESTURES
+// (the published CLI cannot import it; a test keeps the two equal).
+export const GESTURES = [
+  "big-double-laugh", "boiling-point", "bright-tilt", "buoyant-pop", "chuckle-bob", "clipped-huff", "comfort-tilt",
+  "curious-glance", "deep-snore", "delighted-sway", "dodge-glance", "double-take", "dream-twitch", "final-flop",
+  "fold-inward", "freeze-and-shiver", "hard-recoil", "head-shake", "knowing-nod", "lean-out-laugh", "lightbulb",
+  "look-away", "low-simmer", "nervous-scan", "nod-on-the-beat", "one-sided-lean", "other-side", "party-bounce",
+  "ponder-tilt", "pop-back", "pressure-build", "quiet-sigh", "radiant-lift", "shaky-sniff", "sharp-glare",
+  "side-eye-hmm", "sideways-flinch", "sleepy-sway", "slow-droop", "snap-and-fume", "sob-heave", "soft-reset",
+  "spark-salute", "sunny-nod", "thinking-it-over", "tiny-aftershock", "tiny-double-take", "tiny-wince", "uneasy-sway",
+];
+
+// [gesture: <id>] in script.md must name one of the head's gestures.
+export function cueGestureErrors(script = "") {
+  const errs = [];
+  script.replace(/\r\n?/g, "\n").split("\n").forEach((line, i) => {
+    for (const [, colon, raw] of line.matchAll(/\[\s*gesture\b\s*(:?)\s*([^\]]*?)\s*\]/gi)) {
+      if (!GESTURES.includes(raw.toLowerCase())) errs.push(MESSAGES.gesture(i + 1, raw));
+      else if (!colon) errs.push(MESSAGES.gestureColon(i + 1, raw));
+    }
+  });
+  return errs;
+}
+
+// [go: <selector>] and [look: <selector>] (or [look <selector>]) in script.md
+// must match something in their slide ([go: slot] returns home, and [look
+// viewer], [look away] and [look back] need no element).
 export function cueSelectorErrors(html, script = "") {
   const bodies = new Map(slides(html).map((s) => [s.id, s.body]));
   const errs = [];
@@ -227,8 +254,9 @@ export function cueSelectorErrors(html, script = "") {
     const heading = /^##\s+(\S+)/.exec(line);
     if (heading) { id = heading[1]; return; }
     if (!id || !bodies.has(id)) return;
-    for (const [, cue, raw] of line.matchAll(/\[\s*(go|look)\s*:\s*([^\]]*?)\s*\]/gi)) {
-      if (raw === "slot" || !raw) continue;
+    for (const [, colon, spaced, raw] of line.matchAll(/\[\s*(?:(go|look)\s*:\s*|(look)\s+)([^\]]*?)\s*\]/gi)) {
+      const cue = colon ?? spaced;
+      if (!raw || raw === "slot" || (cue.toLowerCase() === "look" && /^(viewer|away|back)$/i.test(raw))) continue;
       if (selectorMatches(bodies.get(id), raw) === false) errs.push(MESSAGES.selector(i + 1, cue.toLowerCase(), raw, id));
     }
   });
@@ -252,13 +280,13 @@ export function playerScript(html) {
   return tag ? { src: attr(tag, "src"), manifest: attr(tag, "data-manifest") || null } : null;
 }
 
-// Relative references: src, href, poster and data-presenter-image (either quote), srcset candidates and
+// Relative references: src, href, poster, data-presenter-image and data-alpha-stacked (either quote), srcset candidates and
 // CSS url(…) in style attributes and <style> blocks; everything that is not a URL
 // scheme, protocol-relative or a fragment. Query strings and fragments dropped.
 export function localRefs(html) {
   const doc = uncommented(html);
   const raw = [
-    ...[...doc.matchAll(/\s(?:src|href|poster|data-presenter-image)\s*=\s*(?:"([^"]*)"|'([^']*)')/gi)].map((m) => m[1] ?? m[2]),
+    ...[...doc.matchAll(/\s(?:src|href|poster|data-presenter-image|data-alpha-stacked)\s*=\s*(?:"([^"]*)"|'([^']*)')/gi)].map((m) => m[1] ?? m[2]),
     ...[...doc.matchAll(/\ssrcset\s*=\s*(?:"([^"]*)"|'([^']*)')/gi)].flatMap((m) => (m[1] ?? m[2]).split(",").map((c) => c.trim().split(/\s+/)[0])),
     ...[...doc.matchAll(/url\(\s*(?:"([^"]*)"|'([^']*)'|([^)'"\s]+))\s*\)/gi)].map((m) => m[1] ?? m[2] ?? m[3]),
   ];
@@ -306,7 +334,7 @@ export function placeholderErrors(html, { hosted = false } = {}) {
 // Everything checkable from the deck's own files. `exists(ref)` answers whether a
 // local reference resolves inside the deck folder: true, false or "outside".
 export function htmlErrors(html, { exists = () => true, forbid = [], script = "", hosted = false } = {}) {
-  const errs = [...presenterStyleErrors(html, script), ...transitionErrors(html, script), ...cueSelectorErrors(html, script), ...placeholderErrors(html, { hosted })];
+  const errs = [...presenterStyleErrors(html, script), ...transitionErrors(html, script), ...cueSelectorErrors(html, script), ...cueGestureErrors(script), ...placeholderErrors(html, { hosted })];
   const player = playerScript(html);
   if (!player) errs.push(MESSAGES.noPlayer());
   else if (player.src !== PLAYER_V1) errs.push(MESSAGES.player(player.src));
@@ -386,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));
@@ -487,7 +515,7 @@ export function stageSize(html) {
 export function absoluteRefs(html) {
   const doc = uncommented(html);
   const raw = [
-    ...[...doc.matchAll(/\s(?:src|href|poster|data-presenter-image)\s*=\s*(?:"([^"]*)"|'([^']*)')/gi)].map((m) => m[1] ?? m[2]),
+    ...[...doc.matchAll(/\s(?:src|href|poster|data-presenter-image|data-alpha-stacked)\s*=\s*(?:"([^"]*)"|'([^']*)')/gi)].map((m) => m[1] ?? m[2]),
     ...[...doc.matchAll(/\ssrcset\s*=\s*(?:"([^"]*)"|'([^']*)')/gi)].flatMap((m) => (m[1] ?? m[2]).split(",").map((c) => c.trim().split(/\s+/)[0])),
     ...[...doc.matchAll(/url\(\s*(?:"([^"]*)"|'([^']*)'|([^)'"\s]+))\s*\)/gi)].map((m) => m[1] ?? m[2] ?? m[3]),
   ];

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
@@ -342,8 +345,10 @@ commands:
             [--quality <q>] [--count <n>] [--seed <n>] [--slug <deck>] [--download <file>]
                    default model gpt-image-2.5; --seed applies to nano-banana-2.1
   image-job <jobId> [--json]
-  gen-video "<prompt>" [--model h3-max|kling-v3] [--image <url>] [--seconds 5] [--aspect 16:9|9:16] [--slug <deck>] [--name <name>] [--download <file>]
+  gen-video "<prompt>" [--model h3-max|kling-v3] [--image <url>] [--seconds 5] [--aspect 16:9|9:16] [--loop] [--transparent] [--slug <deck>] [--name <name>] [--download <file>]
                    a 3–10s clip via fal (default MiniMax H3 Max); --image animates that still and keeps its aspect
+                   --loop starts and ends on one frame (no jump at the seam); --transparent cuts the subject
+                   out as a WebM + a stacked-alpha MP4 for Safari (prints both URLs and the <video> markup)
   video-job <jobId> [--json]
   screenshot <url> [--width 1440] [--height 900] [--full-page] [--slug <deck>] [--name <name>] [--download <file>]
                    a PNG of a public web page (private and local addresses are refused)
@@ -356,7 +361,16 @@ commands:
   brand [show]     your saved brand (colours, fonts, logo, design.md) that every new deck starts from
   brand set [--accent "#hex"] [--ink|--paper|--accent-2|--card "#hex"] [--fonts <pairing>]
             [--display|--body|--mono "<Google Fonts family>"] [--logo <url|file>] [--no-logo]
-            [--presenter-style s] [--design <file.md|->] [--name "<company>"]
+            [--presenter-style s] [--design <file.md|->] [--name "<company>"] [--draft <token>]
+  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
@@ -388,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
@@ -472,7 +486,7 @@ async function imageJob(pos, opts) {
 async function genVideo(pos, opts) {
   const prompt = pos.join(" ").trim() || opts.prompt;
   if (!prompt) {
-    throw new Error('usage: gen-video "<prompt>" [--model h3-max|kling-v3] [--image <url>] [--seconds 5] [--aspect 16:9|9:16] [--slug <deck>] [--name <name>] [--download <file>]');
+    throw new Error('usage: gen-video "<prompt>" [--model h3-max|kling-v3] [--image <url>] [--seconds 5] [--aspect 16:9|9:16] [--loop] [--transparent] [--slug <deck>] [--name <name>] [--download <file>]');
   }
   const queued = await ops.generateVideo(opts, {
     prompt,
@@ -480,12 +494,15 @@ async function genVideo(pos, opts) {
     seconds: opts.seconds,
     aspect: opts.aspect,
     model: opts.model,
+    loop: opts.loop,
+    transparent: opts.transparent,
     slug: opts.slug,
     name: opts.name,
   });
   // A clip takes a minute or more; poll so gen-video stays one blocking command.
   // Progress goes to stderr so stdout stays the URL (or --json).
-  process.stderr.write(`queued a ${queued.seconds}s ${queued.model} clip — job ${queued.jobId}\n`);
+  const kind = [queued.loop && "looping", queued.transparent && "transparent"].filter(Boolean).join(" ");
+  process.stderr.write(`queued a ${queued.seconds}s ${kind ? `${kind} ` : ""}${queued.model} clip — job ${queued.jobId}\n`);
   const job = await ops.pollVideoJob(opts, queued.jobId, {
     onProgress: (j, ms) => process.stderr.write(`  ${j.status} ${Math.round(ms / 1000)}s…\r`),
   });
@@ -493,13 +510,21 @@ async function genVideo(pos, opts) {
   const url = job.video?.url;
   if (!url) throw new Error(`video job ${queued.jobId} finished without a URL; check it with: video-job ${queued.jobId}`);
   // Print the paid clip's URL before downloading, so a failed download never hides it.
+  // A transparent clip prints both files (WebM, then Safari's stacked MP4) and the markup.
   console.log(opts.json ? JSON.stringify(job, null, 2) : url);
+  if (!opts.json && job.video?.stacked?.url) console.log(job.video.stacked.url);
+  if (!opts.json && job.transparent && job.markup) process.stderr.write(`markup: ${job.markup}\n`);
   if (job.creditsRemaining != null) process.stderr.write(`credits left: ${job.creditsRemaining}\n`);
   if (opts.download) {
-    const res = await fetch(url);
-    if (!res.ok) throw new Error(`download of ${url} failed (${res.status})`);
-    writeFileSync(opts.download, Buffer.from(await res.arrayBuffer()));
-    process.stderr.write(`saved to ${opts.download}\n`);
+    // A transparent clip is two files: the WebM where asked, the stacked MP4 beside it.
+    const files = [[url, opts.download]];
+    if (job.video?.stacked?.url) files.push([job.video.stacked.url, `${String(opts.download).replace(/\.[^./]+$/, "")}-stacked.mp4`]);
+    for (const [from, to] of files) {
+      const res = await fetch(from);
+      if (!res.ok) throw new Error(`download of ${from} failed (${res.status})`);
+      writeFileSync(to, Buffer.from(await res.arrayBuffer()));
+      process.stderr.write(`saved to ${to}\n`);
+    }
   }
 }
 
@@ -514,6 +539,8 @@ async function videoJob(pos, opts) {
   console.log(`status:   ${job.status}`);
   if (job.error) console.log(`error:    ${job.error}`);
   if (job.video?.url) console.log(job.video.url);
+  if (job.video?.stacked?.url) console.log(job.video.stacked.url);
+  if (job.markup) console.log(`markup:   ${job.markup}`);
 }
 
 async function screenshot(pos, opts) {
@@ -675,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) } : {});
@@ -756,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");
@@ -801,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");
@@ -853,6 +887,10 @@ function commandTable(pos, rest, opts) {
     "brand edit": async () => (await import("./brandCli.mjs")).brandEdit(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

@@ -158,7 +158,7 @@ export function rewriteTextAssetUrls(text, sourcePath, assets, uploadedByName) {
 export function rewriteHtmlAssetUrls(html, htmlEntry, assets, uploadedByName) {
   const assetMap = buildAssetUrlMap(assets, uploadedByName, htmlEntry);
   let out = html.replace(
-    /\b(src|href|poster|data-presenter-image)\s*=\s*(["'])([^"']+)\2/gi,
+    /\b(src|href|poster|data-presenter-image|data-alpha-stacked)\s*=\s*(["'])([^"']+)\2/gi,
     (match, attr, quote, raw) => {
       const url = resolveLocalUrl(raw, assetMap);
       return url ? `${attr}=${quote}${url}${quote}` : match;

package/src/ops.mjs

@@ -1,5 +1,6 @@
 import { zipSync } from "fflate";
 import { COLOR_KEYS, FONT_PAIRINGS, FONT_ROLES, findPairing, googleFontsUrl } from "./brand.mjs";
+import { MAX_IMPORT_FILE_BYTES, draftArgs, extractFile } from "./brandImport.mjs";
 import { api, client, target, uploadBytes as runtimeUploadBytes } from "./runtime.mjs";
 import {
   bytesFromText,
@@ -120,8 +121,9 @@ export async function pollImageJob(opts, jobId, { intervalMs = 3000, timeoutMs =
 
 // Generate a short clip via fal (MiniMax H3 Max by default, Kling v3 with
 // model "kling-v3": text→video, or image→video when an image URL is given as the
-// first frame). Always a background job: returns
-// { jobId, status, seconds, aspect?, creditsRemaining? } without waiting, so the MCP
+// first frame; loop starts and ends on one frame, transparent mattes the background
+// out). Always a background job: returns
+// { jobId, status, seconds, aspect?, loop, transparent, creditsRemaining? } without waiting, so the MCP
 // tool never blocks; the CLI polls with pollVideoJob.
 export async function generateVideo(opts, fields = {}) {
   if (!fields.prompt) throw new Error("prompt is required");
@@ -131,6 +133,8 @@ export async function generateVideo(opts, fields = {}) {
   if (fields.seconds != null && fields.seconds !== "") args.seconds = Number(fields.seconds);
   if (fields.aspect) args.aspect = String(fields.aspect);
   if (fields.model) args.model = String(fields.model);
+  if (fields.loop === true || fields.loop === "true") args.loop = true;
+  if (fields.transparent === true || fields.transparent === "true") args.transparent = true;
   if (fields.slug) args.slug = String(fields.slug);
   if (fields.name) args.name = String(fields.name);
   return (await client(opts)).action(api.videogen.generateVideo, args);
@@ -232,11 +236,11 @@ export async function checkVideoJob(opts, jobId) {
 }
 
 // Poll a video job until it finishes. Returns the job (its `video` holds the hosted
-// URL); throws on job error or timeout. The server settles every job within 15
-// minutes, so the 16-minute default only trips if the job row itself stalls. A few
-// failed checks in a row (network, Convex hiccup) are tolerated: the job keeps
+// URL); throws on job error or timeout. A few failed checks in a row (network, Convex hiccup) are tolerated: the job keeps
 // running server-side either way, so giving up early would only lose the result.
-export async function pollVideoJob(opts, jobId, { intervalMs = 5000, timeoutMs = 960_000, maxErrors = 5, onProgress } = {}) {
+// 30 minutes: a transparent clip can take the render's 12 minutes, then up to 14
+// more to matte and store it (convex/videogen.ts gives the matte its own clock).
+export async function pollVideoJob(opts, jobId, { intervalMs = 5000, timeoutMs = 1_800_000, maxErrors = 5, onProgress } = {}) {
   const c = await client(opts);
   const start = Date.now();
   const resume = `check it later with: video-job ${jobId}`;
@@ -747,7 +751,7 @@ function designServeUrl(projectId, token, path) {
 }
 
 // Pull every local asset path a deck file references (HTML or CSS): the
-// ext-resource-dependency manifest, src/href/poster/data-presenter-image, srcset, <script>/<link>,
+// ext-resource-dependency manifest, src/href/poster/data-presenter-image/data-alpha-stacked, srcset, <script>/<link>,
 // and CSS url(). Mirrors the importer's rewrite surface so we fetch the same set
 // it will later rewrite. External/data/blob refs are skipped.
 function extractDesignRefs(text) {
@@ -759,7 +763,7 @@ function extractDesignRefs(text) {
     if (clean) out.add(clean);
   };
   for (const m of text.matchAll(/ext-resource-dependency"\s+content="([^"]+)"/gi)) add(m[1]);
-  for (const m of text.matchAll(/\b(?:src|href|poster|data-presenter-image)\s*=\s*["']([^"']+)["']/gi)) add(m[1]);
+  for (const m of text.matchAll(/\b(?:src|href|poster|data-presenter-image|data-alpha-stacked)\s*=\s*["']([^"']+)["']/gi)) add(m[1]);
   for (const m of text.matchAll(/\bsrcset\s*=\s*["']([^"']+)["']/gi)) {
     for (const part of m[1].split(",")) add(part.trim().split(/\s+/)[0]);
   }
@@ -960,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.
@@ -1097,8 +1106,10 @@ export async function getBrand(opts = {}) {
 // Merge into the saved brand: a field left out keeps its value, "" clears it.
 // fontPairing names one of FONT_PAIRINGS and fills the three fonts (an explicit
 // font still wins). logoUrl is fetched into our storage; logoBytes (with
-// logoType) is a file the CLI read. clearLogo removes the logo.
-export async function setBrand(opts, { name, designMd, colors, fonts, fontPairing, presenterStyle, logoUrl, logoBytes, logoType, clearLogo } = {}) {
+// logoType) is a file the CLI read. clearLogo removes the logo. draft is a
+// brand import's token (importBrand): its colours, fonts, name and logo,
+// saved after the person has seen the preview; other fields still win.
+export async function setBrand(opts, { name, designMd, colors, fonts, fontPairing, presenterStyle, logoUrl, logoBytes, logoType, clearLogo, draft } = {}) {
   const c = await client(opts);
   let fontSet = fonts;
   if (fontPairing) {
@@ -1115,9 +1126,9 @@ export async function setBrand(opts, { name, designMd, colors, fonts, fontPairin
   };
   known(colors, COLOR_KEYS, "colour");
   known(fontSet, FONT_ROLES, "font role");
-  const fields = { name, designMd, colors, fonts: fontSet, presenterStyle };
+  const fields = { name, designMd, colors, fonts: fontSet, presenterStyle, draft: draft ? String(draft).trim() : undefined };
   const defined = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined && v !== null));
-  if (!Object.keys(defined).length && !logoUrl && !logoBytes && !clearLogo) throw new Error("nothing to set: pass colors, fonts, fontPairing, logoUrl, designMd, name or presenterStyle");
+  if (!Object.keys(defined).length && !logoUrl && !logoBytes && !clearLogo) throw new Error("nothing to set: pass draft, colors, fonts, fontPairing, logoUrl, designMd, name or presenterStyle");
   let out = Object.keys(defined).length ? await c.mutation(api.brand.set, defined) : null;
   try {
     if (clearLogo) out = await c.mutation(api.brand.clear, { logoOnly: true });
@@ -1134,6 +1145,41 @@ export async function setBrand(opts, { name, designMd, colors, fonts, fontPairin
   return out ?? getBrand(opts);
 }
 
+// Read a brand from a website (url), one of your decks (slug) or a .pptx /
+// .potx / .pdf (bytes + fileName, read here with brandImport.mjs) into a
+// draft. Returns { token, colors, fonts, logoUrl, notes, previewUrl, … };
+// nothing is saved until setBrand({ draft: token }).
+export async function importBrand(opts, { url, slug, bytes, fileName } = {}) {
+  const given = [url, slug, bytes].filter((x) => x !== undefined && x !== null && x !== "");
+  if (given.length !== 1) throw new Error("import a brand from one of: a website url, a deck slug or a .pptx / .potx / .pdf file");
+  const c = await client(opts);
+  if (url) return c.action(api.brandNode.importFromUrl, { url: String(url) });
+  if (slug) return c.action(api.brandNode.importFromDeck, { slug: String(slug) });
+  const data = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  if (data.byteLength > MAX_IMPORT_FILE_BYTES) throw new Error(`${fileName ?? "the file"} is over ${MAX_IMPORT_FILE_BYTES / 1024 / 1024} MB`);
+  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(); }) };
 }