@hypersocial/decks-cli 0.5.0 → 0.7.0

package/src/brandPreview.mjs

@@ -0,0 +1,24 @@
+// 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 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"];
+  // 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.",
+  );
+  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,12 +41,16 @@ 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})`,
   morphPair: (id, prev) => `slide ${id}: morph needs an element with the same data-morph="<name>" on this slide and the one before it (${prev})`,
   transitionStale: (where, script, manifest) => `${where}: script.md says transition "${script}" but the manifest has "${manifest}": run \`hyperdecks narrate\` so the player gets it`,
   flyTwice: (ids) => `fly is for the deck's one big moment, but slides ${ids.join(", ")} all use it`,
+  // A layout's stand-in left in: `how` is the tool (hosted) or command (CLI) that makes the real file.
+  placeholder: (id, what, el, how, img) => `slide ${id}: ${what} is still the layout's placeholder (${el}); ${how}, then put it in as ${img}`,
   // Warnings (check --layout): the deck still passes.
   layoutUnchecked: (why) => `layout not checked: ${why}`,
   hotlink: (url) => `${url} is hotlinked from another site and can vanish after release; upload it with upload_deck_asset`,
@@ -215,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 = [];
@@ -225,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));
     }
   });
@@ -250,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]),
   ];
@@ -271,10 +301,40 @@ export function phraseList(value) {
   return value.map((s) => String(s).trim()).filter(Boolean);
 }
 
+// Layout stand-ins a deck must swap for its own file, found by the templates'
+// own markers: the empty div (or the chart's labelled svg). A div that holds
+// its own picture, or gets one from a url() in its style or a <style> rule
+// naming its class, is the deck's art. A deck that wants none removes it.
+const PLACEHOLDERS = [
+  {
+    layout: "l-hero", tag: "div", cls: "art", what: "the hero's art", img: '<img class="art" src="…" alt="">, or delete the div for no art (the presenter is the visual)',
+    how: { hosted: "make a picture of the real subject with generate_image", cli: "make a picture of the real subject with `hyperdecks gen-image \"<prompt>\"`" },
+  },
+  {
+    layout: "l-product", tag: "div", cls: "shot", what: "the product screenshot", img: '<img class="shot" src="…" alt="…">',
+    how: { hosted: "capture the real page with capture_url", cli: "capture the real page with `hyperdecks screenshot <url>`" },
+  },
+  {
+    layout: "l-chart", tag: "svg", cls: "chart", label: /placeholder/i, what: "the chart (made-up numbers)", img: '<img class="chart" src="…" alt="…">',
+    how: { hosted: "draw the real data with render_chart", cli: "draw the real data with `hyperdecks chart <spec.json>`" },
+  },
+];
+const classes = (tag) => (attr(tag, "class") ?? "").split(/\s+/).filter(Boolean);
+export function placeholderErrors(html, { hosted = false } = {}) {
+  const css = [...uncommented(html).matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)].map((m) => m[1].replace(/\/\*[\s\S]*?\*\//g, "")).join("\n");
+  const styled = (cls) => [...css.matchAll(/([^{}]*)\{([^{}]*)\}/g)].some(([, sel, body]) => new RegExp(`\\.${cls}(?![\\w-])`).test(sel) && /url\(/i.test(body));
+  return slides(html).flatMap((s, i) => {
+    const layouts = classes(s.tag);
+    return PLACEHOLDERS.filter((p) => layouts.includes(p.layout) && !(p.tag === "div" && styled(p.cls)) && [...s.body.matchAll(new RegExp(`(<${p.tag}\\b[^>]*>)([\\s\\S]*?)</${p.tag}>`, "gi"))].some(([, tag, inner]) =>
+      classes(tag).includes(p.cls) && (p.label ? p.label.test(attr(tag, "aria-label") ?? "") : !inner.trim() && !/url\(/i.test(attr(tag, "style") ?? ""))))
+      .map((p) => MESSAGES.placeholder(s.id || `${i + 1}`, p.what, `<${p.tag} class="${p.cls}">`, hosted ? p.how.hosted : p.how.cli, p.img));
+  });
+}
+
 // 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 = "" } = {}) {
-  const errs = [...presenterStyleErrors(html, script), ...transitionErrors(html, script), ...cueSelectorErrors(html, script)];
+export function htmlErrors(html, { exists = () => true, forbid = [], script = "", hosted = false } = {}) {
+  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));
@@ -455,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]),
   ];
@@ -486,7 +546,7 @@ export async function checkSources({ html, script = "" }, opts = {}, { fetch: fe
     throw new Error(flagCap !== undefined ? "--max-duration needs a number of seconds" : "maxTotalSeconds in script.md must be a number of seconds");
   }
   const exists = opts.hosted ? () => "hosted" : (opts.exists ?? (() => true));
-  const errors = htmlErrors(html, { exists, forbid, script });
+  const errors = htmlErrors(html, { exists, forbid, script, hosted: !!opts.hosted });
   const ids = slides(html).map((s) => s.id);
   const player = playerScript(html);
   let manifest = null;

package/src/commands.mjs

@@ -9,6 +9,7 @@ import {
   VERSION,
 } from "./runtime.mjs";
 import * as ops from "./ops.mjs";
+import { presenterLine } from "./presenter.mjs";
 
 export const playbackLabel = (p) => p.narrationFinished ? "narration finished"
   : p.narrationStarted ? "narration started"
@@ -306,8 +307,9 @@ commands:
   deck list|stats|open|rm|forward
   deck forward on|off <slug>
                    whether viewers can forward the deck's links (on by default; a link's own setting wins)
-  deck new <slug> "<title>" --narrated [--layouts hero,product,number,closer] [--presenter-style stage|bubble|glass|corner] [--dir <path>]
-                   scaffold decks/<slug>/: index.html (8 slides, or one per layout, player/v1), script.md, evidence.md
+  deck new <slug> "<title>" --narrated [--layouts hero,product,number,closer] [--presenter-style stage|bubble|glass|corner] [--no-brand] [--dir <path>]
+                   scaffold decks/<slug>/: index.html (8 slides, or one per layout, player/v1), script.md, evidence.md,
+                   in your saved brand's colours, fonts and logo (--no-brand: the template's look)
                    layouts: hero, number, product, quote, compare, timeline, features, chart, team, closer
   check <slug|deck-dir> [--forbid "<phrase>,<phrase>"] [--max-duration <s>] [--layout] [--json]
                    the narrated-deck gate: slides vs manifest, timing, captions, clip URLs,
@@ -320,7 +322,7 @@ 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)
-  release <slug|deck-dir> [--to "<name>" [--email <e>]]... [--qa] [--no-notify] [--title t] [--voice v]
+  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
     share new <slug> <recipient> [--qa] [--no-notify] [--allow-forward|--no-forward]
@@ -340,15 +342,29 @@ 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)
   chart <spec.json|-> [--slug <deck>] [--name <name>] [--download <file>]
                    a branded SVG: { "kind": "bar|line|donut|number", "labels", "series", "values", "value", "palette" }
+  icons search <word...> [--limit 8] [--stroke-width 2] [--json]
+                   real icons from the Lucide library as inline SVG in currentColor (free, offline)
   icons <subject...> --style "<style>" [--palette "#hex,#hex"] [--slug <deck>] [--name <prefix>]
-                   a style-consistent set of transparent icons, one per subject (max 12)
+                   a style-consistent set of generated (illustrated) icons, one per subject (max 12)
+  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>"] [--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 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
   review <slug> [--script <script.md>] [--json]
                    GPT-6 Luna reviews every slide (desktop + phone screenshots) and lists what to fix
   review-job <jobId> [--json]
@@ -461,7 +477,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,
@@ -469,12 +485,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`),
   });
@@ -482,13 +501,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`);
+    }
   }
 }
 
@@ -503,6 +530,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) {
@@ -629,7 +658,7 @@ function commandTable(pos, rest, opts) {
       if (opts.hosted) {
         const { hostedNewDeck } = await import("./source.mjs");
         if (!opts.narrated) throw new Error("the published CLI scaffolds narrated decks only: add --narrated");
-        const out = await hostedNewDeck(opts, { slug: rest[0], title: rest[1], layouts: opts.layouts, presenterStyle: opts["presenter-style"] });
+        const out = await hostedNewDeck(opts, { slug: rest[0], title: rest[1], layouts: opts.layouts, presenterStyle: opts["presenter-style"], brand: !opts["no-brand"] });
         return void console.log(opts.json ? JSON.stringify(out, null, 2) : `✓ created hosted deck "${out.slug}" (rev ${out.rev})\n  preview: ${out.previewUrl}\n  edit locally: hyperdecks source pull ${out.slug}`);
       }
       const { deckNew } = await import("./scaffold.mjs");
@@ -652,9 +681,11 @@ function commandTable(pos, rest, opts) {
     release: async () => {
       if (opts.hosted) {
         const { hostedRelease } = await import("./source.mjs");
-        const out = await hostedRelease(opts, { slug: pos[1], recipients: opts.recipients, qa: opts.qa, title: opts.title, forbid: opts.forbid });
+        const out = await hostedRelease(opts, { slug: pos[1], recipients: opts.recipients, qa: opts.qa, title: opts.title, forbid: opts.forbid, captionsOnly: opts["captions-only"] });
         if (opts.json) return void console.log(JSON.stringify(out, null, 2));
         console.log(`✓ released ${out.slug} rev ${out.rev}\n  deck: ${out.deckUrl}`);
+        const who = presenterLine(out.presenter);
+        if (who) console.log(who);
         for (const s of out.shares) console.log(`✓ share for "${s.recipient}"${s.qa ? " (QA, untracked)" : ""} → ${s.url}`);
         return;
       }
@@ -826,6 +857,21 @@ function commandTable(pos, rest, opts) {
     screenshot: () => screenshot(pos.slice(1), opts),
     chart: () => chart(pos.slice(1), opts),
     icons: () => icons(pos.slice(1), opts),
+    // The icon library (Lucide); `icons search … --style` still generates.
+    "icons search": async () => {
+      if (opts.style) return icons(pos.slice(1), opts);
+      if (!rest.length) throw new Error("usage: icons search <word...> [--limit N] [--stroke-width N] [--json]");
+      const { icons: searchIcons } = await import("./icons.mjs");
+      const out = await searchIcons(rest, opts);
+      if (opts.json) console.log(JSON.stringify(out, null, 2));
+    },
+    brand: async () => (await import("./brandCli.mjs")).brandShow(opts),
+    "brand show": async () => (await import("./brandCli.mjs")).brandShow(opts),
+    "brand set": async () => (await import("./brandCli.mjs")).brandSet(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),
     review: () => review(pos.slice(1), opts),
     "review-job": () => reviewJob(pos.slice(1), opts),
     poster: () => poster(pos.slice(1), opts),

package/src/files.mjs

@@ -19,6 +19,7 @@ const FILES = {
   "templates/layouts/quote.html": () => new URL("../templates/layouts/quote.html", import.meta.url),
   "templates/layouts/team.html": () => new URL("../templates/layouts/team.html", import.meta.url),
   "templates/layouts/timeline.html": () => new URL("../templates/layouts/timeline.html", import.meta.url),
+  "templates/icons/lucide.json": () => new URL("../templates/icons/lucide.json", import.meta.url),
   "templates/first-deck/self.json": () => new URL("../templates/first-deck/self.json", import.meta.url),
   "templates/first-deck/character.json": () => new URL("../templates/first-deck/character.json", import.meta.url),
   "skills/hyperdecks/SKILL.md": () => new URL("../skills/hyperdecks/SKILL.md", import.meta.url),

package/src/firstDeck.mjs

@@ -52,6 +52,8 @@ export function fillFirstDeck({ html, title, answers, presenter, voice }) {
   const note = (s) => swap(s, /\sdata-note="[^"]*"/, ' data-note="From your init answers."', "data-note");
   let out = section(html, "hero", (s) => {
     s = note(s);
+    // No art: the presenter is the opening's visual, and check fails on the stand-in.
+    s = swap(s, /\s*<div class="art"[^>]*><\/div>/, "", "hero art");
     s = swap(s, /<div class="kicker">[^<]*<\/div>/, `<div class="kicker">${h(copy.hero.kicker)}</div>`, "hero kicker");
     s = swap(s, /<h1 class="tt"[^>]*>[\s\S]*?<\/h1>/, `<h1 class="tt" data-title-mobile="${h(copy.hero.title)}">${h(copy.hero.title)}</h1>`, "hero title");
     return swap(s, /<p class="lead">[\s\S]*?<\/p>/, `<p class="lead">${h(copy.hero.lead)}</p>`, "hero lead");

package/src/guide.mjs

@@ -6,6 +6,7 @@
 // each layout file's leading comment.
 import { packageText } from "./files.mjs";
 import { LAYOUTS, readLayout } from "./layouts.mjs";
+import { fontPairingsMarkdown } from "./brand.mjs";
 
 export const GUIDE_TOPICS = ["workflow", "format", "script", "design", "layouts", "presenter", "transitions", "check"];
 const CLI_NOTE = "_Written for the CLI. On the hosted MCP there is no folder: use the tool names in `deck_guide` (workflow), hosted URLs for every file, and write_deck_source for edits._\n\n";
@@ -43,7 +44,8 @@ export function deckGuide(topic = "workflow") {
   else {
     const section = skillSection(packageText("skills/hyperdecks/SKILL.md"), t);
     if (!section) throw new Error(`SKILL.md has no <!-- topic: ${t} --> section`);
-    text = CLI_NOTE + section;
+    // The design topic carries the curated font pairings (brand.mjs) in place of its marker.
+    text = CLI_NOTE + section.replace("<!-- font pairings -->", () => fontPairingsMarkdown());
   }
   return { topic: t, topics: GUIDE_TOPICS, text };
 }

package/src/hosted.mjs

@@ -3,7 +3,9 @@
 // (source.mjs) share these; no local file I/O, so the route can bundle them.
 import { api, client, target } from "./runtime.mjs";
 import { PRESENTER_STYLES } from "./checkRules.mjs";
-import { NARRATED_FILES, assembleLayoutDeck, fillTemplate } from "./layouts.mjs";
+import { NARRATED_FILES, assembleLayoutDeck, fillTemplate, parseLayouts } from "./layouts.mjs";
+import { applyBrand, brandForNewDeck, brandSummary } from "./brand.mjs";
+import { getBrand } from "./ops.mjs";
 
 export const SOURCE_FILES = Object.keys(NARRATED_FILES);
 const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
@@ -13,16 +15,22 @@ const urls = (opts, slug, previewToken) => {
 };
 
 // Scaffold the files (the same templates as deck new) and register the draft.
-export async function hostedNewDeck(opts, { slug, title, layouts, presenterStyle } = {}) {
+// The account's brand (colours, fonts, logo, presenter style) goes on the
+// template unless brand is false; an explicit presenterStyle wins over it.
+export async function hostedNewDeck(opts, { slug, title, layouts, presenterStyle, brand: useBrand } = {}) {
   if (!slug || !title) throw new Error("slug and title are required");
   if (!SLUG.test(slug)) throw new Error("slug must be lowercase letters, digits and dashes (max 64)");
   if (presenterStyle !== undefined && !PRESENTER_STYLES.includes(presenterStyle)) throw new Error(`presenterStyle must be one of ${PRESENTER_STYLES.join(", ")}`);
   const list = Array.isArray(layouts) ? layouts.join(",") : layouts;
+  if (list) parseLayouts(list);
+  const { brand, readError } = await brandForNewDeck(() => getBrand(opts), useBrand);
+  const style = presenterStyle ?? (PRESENTER_STYLES.includes(brand?.presenterStyle) ? brand.presenterStyle : undefined);
   const files = list
-    ? assembleLayoutDeck({ slug, title, presenterStyle, layouts: list })
-    : Object.fromEntries(Object.entries(NARRATED_FILES).map(([out, file]) => [out, fillTemplate(file, { slug, title, presenterStyle })]));
+    ? assembleLayoutDeck({ slug, title, presenterStyle: style, layouts: list })
+    : Object.fromEntries(Object.entries(NARRATED_FILES).map(([out, file]) => [out, fillTemplate(file, { slug, title, presenterStyle: style })]));
+  files["index.html"] = applyBrand(files["index.html"], brand);
   const made = await (await client(opts)).mutation(api.deckSources.create, { slug, title, files });
-  return { slug, rev: made.rev, files, ...urls(opts, slug, made.previewToken) };
+  return { slug, rev: made.rev, files, brand: brandSummary(brand, readError), ...urls(opts, slug, made.previewToken) };
 }
 
 export async function getDeckSource(opts, { slug, file } = {}) {
@@ -59,7 +67,7 @@ export async function hostedCheck(opts, { slug, forbid, maxDuration } = {}) {
   return (await client(opts)).action(api.deckSources.check, { slug, ...(list?.length ? { forbid: list } : {}), ...(maxDuration ? { maxDuration: Number(maxDuration) } : {}) });
 }
 
-export async function hostedRelease(opts, { slug, recipients, qa, title, forbid, rev, voice } = {}) {
+export async function hostedRelease(opts, { slug, recipients, qa, title, forbid, rev, voice, captionsOnly } = {}) {
   if (!slug) throw new Error("slug is required");
   const list = typeof forbid === "string" ? forbid.split(",").map((s) => s.trim()).filter(Boolean) : forbid;
   const args = { slug };
@@ -69,6 +77,7 @@ export async function hostedRelease(opts, { slug, recipients, qa, title, forbid,
   if (list?.length) args.forbid = list;
   if (rev !== undefined && rev !== null) args.rev = Number(rev);
   if (voice) args.voice = String(voice);
+  if (captionsOnly) args.captionsOnly = true;
   return (await client(opts)).action(api.deckSources.release, args);
 }
 

package/src/icons.mjs

@@ -0,0 +1,66 @@
+// hyperdecks icons search <word> [--limit N] [--stroke-width N]
+//
+// The icon library: Lucide's open-source line icons (ISC licence, vendored in
+// templates/icons/lucide.json by scripts/sync-icons.mjs). A search returns
+// inline SVG stroked in currentColor, so a pasted icon takes the colour of the
+// text around it, i.e. the deck's palette. No network and no credits; for
+// illustrated icons in a style of your own, `hyperdecks icons <subject...>
+// --style` (generate_icon_set) still draws them.
+import { packageText } from "./files.mjs";
+
+export const MAX_ICON_RESULTS = 24;
+const DEFAULT_RESULTS = 8;
+let library;
+const lib = () => (library ??= JSON.parse(packageText("templates/icons/lucide.json")));
+
+export function iconSvg(name, { strokeWidth = 2 } = {}) {
+  const icon = lib().icons[name];
+  if (!icon) return null;
+  const sw = Number(strokeWidth);
+  const width = Number.isFinite(sw) && sw > 0 && sw <= 4 ? sw : 2;
+  return `<svg class="icon lucide-${name}" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="${width}" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${icon[0]}</svg>`;
+}
+
+// Best matches first: the exact name, a name starting with or containing a
+// word, then an exact tag, then a tag containing a word. Several words rank by
+// how many of them match.
+export function searchIcons({ query, limit, strokeWidth } = {}) {
+  const words = String(query ?? "").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+  if (!words.length) throw new Error("search needs a word, e.g. rocket");
+  const n = Math.min(Math.max(Number(limit) || DEFAULT_RESULTS, 1), MAX_ICON_RESULTS);
+  const phrase = words.join("-");
+  const scored = [];
+  for (const [name, [, tagText]] of Object.entries(lib().icons)) {
+    const parts = name.split("-");
+    const tags = tagText ? tagText.split(",") : [];
+    let score = name === phrase ? 100 : 0;
+    for (const w of words) {
+      if (parts[0] === w) score += 12;
+      else if (parts.includes(w)) score += 10;
+      else if (name.includes(w)) score += 6;
+      else if (tags.includes(w)) score += 5;
+      else if (tags.some((t) => t.split(" ").includes(w))) score += 3;
+      else if (tags.some((t) => t.includes(w))) score += 1;
+    }
+    // Plainer icons first among equals: rocket before rocket-launch.
+    if (score) scored.push({ name, tags, score: score - parts.length * 0.1 });
+  }
+  scored.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+  return {
+    query: words.join(" "),
+    library: lib().source,
+    license: lib().license,
+    total: scored.length,
+    icons: scored.slice(0, n).map(({ name, tags }) => ({ name, tags, svg: iconSvg(name, { strokeWidth }) })),
+    usage: "Paste svg inline (e.g. in .l-features .card). It is stroked in currentColor: set `color` on it or its parent to put it in the deck's palette.",
+  };
+}
+
+export async function icons(pos, opts = {}, { log = (line) => console.log(line) } = {}) {
+  const out = searchIcons({ query: pos.join(" "), limit: opts.limit, strokeWidth: opts["stroke-width"] });
+  if (opts.json) return out;
+  if (!out.icons.length) log(`no icons match "${out.query}"; try a plainer word (e.g. chart, user, lock)`);
+  for (const icon of out.icons) log(`${icon.name}${icon.tags.length ? `  (${icon.tags.slice(0, 5).join(", ")})` : ""}\n${icon.svg}\n`);
+  if (out.icons.length) log(`${out.icons.length} of ${out.total} from ${out.library}. ${out.usage}`);
+  return out;
+}

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

@@ -8,6 +8,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import * as ops from "./ops.mjs";
+import { presenterLine } from "./presenter.mjs";
 export { sectionIds, setManifestUrl } from "./checkRules.mjs";
 import { sectionIds, setManifestUrl } from "./checkRules.mjs";
 
@@ -46,10 +47,14 @@ export async function narrate(pos, opts = {}, { log = (line) => console.log(line
     for (const s of preview.slides) log(`${s.render ? "render" : s.cached ? "cached" : "skip  "}  ${s.id}  ${s.hash.slice(0, 12)}  ${s.chars} chars${s.presenterStyle ? `  presenter-style: ${s.presenterStyle}` : ""}`);
     const render = preview.slides.filter((s) => s.render);
     log(`${render.length} of ${preview.slides.length} slide(s) would render in voice "${preview.voice}", ~${render.reduce((n, s) => n + s.chars, 0)} characters of TTS`);
+    const who = presenterLine(preview.presenter);
+    if (who) log(who);
     return preview;
   }
-  const { jobId, slides } = await ops.narrateDeck(opts, fields);
+  const { jobId, slides, presenter } = await ops.narrateDeck(opts, fields);
   log(`narration job ${jobId}: ${slides.filter((s) => s.status === "render").length} to render, ${slides.filter((s) => s.status === "cached").length} cached`);
+  const who = presenterLine(presenter);
+  if (who) log(who);
   const seen = new Map();
   const job = await ops.pollNarrationJob(opts, jobId, {
     onProgress: (j) => {
@@ -63,6 +68,8 @@ export async function narrate(pos, opts = {}, { log = (line) => console.log(line
     },
   });
   if (job.status === "error") throw new Error(job.error || "narration failed");
+  // release reads who presents from here (older backends send no presenter).
+  if (presenter) job.presenter = presenter;
   if (!job.manifest) {
     log(`⚠ ${job.notice || "done, but no manifest was written"}`);
     return job;