@hypersocial/decks-cli 0.2.0 → 0.2.2

package/src/check.mjs

@@ -1,4 +1,4 @@
-// hyperdecks check <slug|deck-dir> [--forbid "<phrase>,<phrase>"] [--max-duration <s>] [--json]
+// hyperdecks check <slug|deck-dir> [--forbid "<phrase>,<phrase>"] [--max-duration <s>] [--layout] [--json]
 //
 // The narrated-deck integrity gate, ported from the Netflix presentation's
 // scripts/check.mjs and its variant builders. Every rule returns its message from
@@ -14,6 +14,8 @@ export const DEFAULT_MAX_DURATION = 180;
 export const MOBILE_TITLE_CHARS = 28;
 export const CAPTION_MIN_CHARS = 4;
 export const CAPTION_MAX_CHARS = 85;
+// Same names as PRESENTER_STYLES in lib/deckManifest.ts (the published CLI cannot import it).
+export const PRESENTER_STYLES = ["stage", "bubble", "glass", "corner"];
 
 export const MESSAGES = {
   noPlayer: () => `no player script: add <script type="module" src="${PLAYER_V1}" data-manifest="…">`,
@@ -21,6 +23,7 @@ export const MESSAGES = {
   noManifest: () => "the player script has no data-manifest: run `hyperdecks narrate <deck-dir>`, which sets it",
   manifestUnavailable: (url, why) => `manifest ${url} could not be read (${why})`,
   noSlides: () => 'no slides: each slide is a <section class="slide" id="…">',
+  noLoading: () => "no loading state: copy the <style data-hd-loading> block and the lines above it from the narrated template into <head>, and set --hd-ground to the first slide's colour",
   clipField: (id, field) => `clip ${id}: ${field}`,
   noCaptions: (id) => `clip ${id}: timeline has no captions`,
   order: (slides, clips) => `slide ids (${slides.join(", ")}) must equal the manifest clip ids (${clips.join(", ")}), in order`,
@@ -28,7 +31,7 @@ export const MESSAGES = {
   cap: (total, cap) => `narration runs ${total}s, over the ${cap}s cap (aim for 150 to 180 s)`,
   url: (id, key, url, why) => `clip ${id}: ${key} ${url} ${why}`,
   timing: (id, i, start, end, duration) => `clip ${id}: caption ${i + 1} runs ${start}s to ${end}s, outside 0 ≤ start < end ≤ ${duration}s + 0.1`,
-  words: (id) => `clip ${id}: caption words do not match the clip text (the captions must cover the whole narration)`,
+  words: (id) => `clip ${id}: captions do not cover the clip text, or a caption has no timed words`,
   captionLength: (id, i, text) => `clip ${id}: caption ${i + 1} is ${text.length} characters ("${text}"); captions must be ${CAPTION_MIN_CHARS} to ${CAPTION_MAX_CHARS}`,
   localRef: (ref) => `local reference does not resolve: ${ref}`,
   outsideRef: (ref) => `local reference leaves the deck folder: ${ref}`,
@@ -36,8 +39,19 @@ export const MESSAGES = {
   note: (id) => `slide ${id}: needs a data-note naming the source of its facts`,
   mobileTitle: (id, title) => `slide ${id}: title "${title}" is over ${MOBILE_TITLE_CHARS} characters and needs a data-title-mobile`,
   slideId: (n) => `slide ${n} has no id`,
+  selector: (line, cue, selector, id) => `script.md line ${line}: [${cue}: ${selector}] matches nothing in slide ${id}`,
+  presenterStyle: (where, value) => `${where}: presenter style "${value}" is not one of ${PRESENTER_STYLES.join(", ")}`,
+  // Warnings (check --layout): the deck still passes.
+  layoutUnchecked: (why) => `layout not checked: ${why}`,
+  overlap: (id, style, stage) => `slide ${id}: the ${style} presenter would overlap the title at ${stage}; move the .narration-slot or pick another style`,
+  // An error, though only check --layout can see it.
+  phoneOverflow: (id, px) => `slide ${id}: its content runs ${px}px past the slide on a ${PHONE.width}×${PHONE.height} phone; a slide must fit one screen without scrolling, so trim it or tighten its @media (max-width: 650px) rules`,
 };
 
+// The framed player's slide card on a phone (player.css): the screen less the
+// 52px masthead, the 56px dock and 8px gutters.
+export const PHONE = { width: 390, height: 844, card: { width: 374, height: 736 } };
+
 const uncommented = (html) => html.replace(/<!--[\s\S]*?-->/g, "");
 const attr = (tag, name) => {
   const m = new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`).exec(tag);
@@ -47,6 +61,62 @@ const round = (n) => Math.round(n * 100) / 100;
 const decode = (s) => s.replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;|&apos;/g, "'");
 const textOf = (html) => decode(html.replace(/<[^>]+>/g, " ")).replace(/\s+/g, " ").trim();
 
+// Comments blanked but newlines kept, so line numbers still match the file.
+const blankComments = (text) => text.replace(/<!--[\s\S]*?-->/g, (c) => c.replace(/[^\n]/g, " "));
+const lineAt = (text, index) => text.slice(0, index).split("\n").length;
+
+// Unknown presenter styles, with their line: data-presenter-style in index.html,
+// presenterStyle in script.md's front matter and presenter-style under a heading.
+export function presenterStyleErrors(html, script = "") {
+  const errs = [];
+  const page = blankComments(html);
+  for (const m of page.matchAll(/\sdata-presenter-style\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) {
+    const value = m[1] ?? m[2];
+    if (!PRESENTER_STYLES.includes(value)) errs.push(MESSAGES.presenterStyle(`index.html line ${lineAt(page, m.index)}`, value));
+  }
+  const lines = script.replace(/\r\n?/g, "\n").split("\n");
+  const frontEnd = lines[0]?.trim() === "---" ? lines.indexOf("---", 1) : -1;
+  lines.forEach((line, i) => {
+    const m = (i > 0 && i < frontEnd ? /^\s*presenterStyle\s*:\s*(.*?)\s*$/ : /^\s*presenter-style\s*:\s*(.*?)\s*$/).exec(line);
+    if (m && !PRESENTER_STYLES.includes(m[1])) errs.push(MESSAGES.presenterStyle(`script.md line ${i + 1}`, m[1]));
+  });
+  return errs;
+}
+
+// Does a simple selector (tag, #id, .class, or one compound of them) match
+// anything in this slide's markup? null when the selector is too complex to
+// tell without a browser.
+export function selectorMatches(body, selector) {
+  const m = /^([a-zA-Z][a-zA-Z0-9-]*)?(?:#([\w-]+))?((?:\.[\w-]+)*)$/.exec(selector.trim());
+  if (!m || !(m[1] || m[2] || m[3])) return null;
+  const [, tag, id, cls] = m;
+  const classes = cls.split(".").filter(Boolean);
+  return [...uncommented(body).matchAll(/<([a-zA-Z][a-zA-Z0-9-]*)\b[^>]*>/g)].some(([open, name]) => {
+    if (tag && name.toLowerCase() !== tag.toLowerCase()) return false;
+    if (id && attr(open, "id") !== id) return false;
+    const have = (attr(open, "class") ?? "").split(/\s+/);
+    return classes.every((c) => have.includes(c));
+  });
+}
+
+// [go: <selector>] and [look: <selector>] in script.md must match something in
+// their slide ([go: slot] returns home and always resolves).
+export function cueSelectorErrors(html, script = "") {
+  const bodies = new Map(slides(html).map((s) => [s.id, s.body]));
+  const errs = [];
+  let id = null;
+  script.replace(/\r\n?/g, "\n").split("\n").forEach((line, i) => {
+    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;
+      if (selectorMatches(bodies.get(id), raw) === false) errs.push(MESSAGES.selector(i + 1, cue.toLowerCase(), raw, id));
+    }
+  });
+  return errs;
+}
+
 // Same normalization as the source check: accents folded, case and punctuation dropped.
 export const normalizeWords = (text) => text.normalize("NFKD").replace(/\p{Diacritic}/gu, "").toLowerCase().replace(/[^a-z0-9]/g, "");
 
@@ -64,13 +134,13 @@ export function playerScript(html) {
   return tag ? { src: attr(tag, "src"), manifest: attr(tag, "data-manifest") || null } : null;
 }
 
-// Relative references: src, href and poster (either quote), srcset candidates and
+// Relative references: src, href, poster and data-presenter-image (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)\s*=\s*(?:"([^"]*)"|'([^']*)')/gi)].map((m) => m[1] ?? m[2]),
+    ...[...doc.matchAll(/\s(?:src|href|poster|data-presenter-image)\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]),
   ];
@@ -88,10 +158,14 @@ function phraseList(value) {
 // 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 = [];
+  const errs = [...presenterStyleErrors(html, script), ...cueSelectorErrors(html, script)];
   const player = playerScript(html);
   if (!player) errs.push(MESSAGES.noPlayer());
   else if (player.src !== PLAYER_V1) errs.push(MESSAGES.player(player.src));
+  // The loading state must be in <head> to hold the page from its first paint,
+  // with its fail-open so a deck whose player never loads still shows.
+  const loading = /<style\b[^>]*\sdata-hd-loading(?=[\s>=])[^>]*>([\s\S]*?)<\/style>/i.exec(/<head\b[\s\S]*?<\/head>/i.exec(uncommented(html))?.[0] ?? "");
+  if (player && !loading?.[1].includes("hd-fail-open")) errs.push(MESSAGES.noLoading());
   const all = slides(html);
   if (!all.length) errs.push(MESSAGES.noSlides());
   all.forEach((s, i) => {
@@ -142,6 +216,9 @@ export function manifestErrors(manifest, slideIds, { maxDuration = DEFAULT_MAX_D
   const declared = Number(manifest?.totalDuration);
   if (!(Math.abs(sum - declared) < 0.01)) errs.push(MESSAGES.total(sum, manifest?.totalDuration));
   if (Number.isFinite(declared) && declared > maxDuration) errs.push(MESSAGES.cap(round(declared), maxDuration));
+  const badStyle = (v) => v !== undefined && !PRESENTER_STYLES.includes(v);
+  if (badStyle(manifest?.presenterStyle)) errs.push(MESSAGES.presenterStyle("manifest", manifest.presenterStyle));
+  for (const c of clips) if (badStyle(c?.presenterStyle)) errs.push(MESSAGES.presenterStyle(`clip ${c.id}`, c.presenterStyle));
   for (const phrase of phraseList(forbid)) {
     for (const c of clips) if (String(c?.text ?? "").toLowerCase().includes(phrase.toLowerCase())) errs.push(MESSAGES.forbidden(phrase, `clip ${c.id}`));
   }
@@ -157,8 +234,12 @@ 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));
   });
-  const spoken = captions.flatMap((c) => (Array.isArray(c.words) ? c.words.map((w) => w?.text ?? "") : [])).join(" ");
-  if (normalizeWords(spoken) !== normalizeWords(String(clip.text ?? ""))) errs.push(MESSAGES.words(clip.id));
+  // 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.
+  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));
   captions.forEach((c, i) => {
     const text = String(c.text ?? "");
     if (text.length < CAPTION_MIN_CHARS || text.length > CAPTION_MAX_CHARS) errs.push(MESSAGES.captionLength(clip.id, i, text));
@@ -166,6 +247,130 @@ export function timelineErrors(clip, timeline) {
   return errs;
 }
 
+// Each slide's presenter style, as the player resolves it at desktop size: the
+// slide's data-presenter-style, its clip's, the player tag's, the manifest's,
+// then stage for the live head and bubble otherwise.
+export function slideStyles(html, manifest = null) {
+  const page = uncommented(html);
+  const tag = [...page.matchAll(/<script\b[^>]*>/g)].map((m) => m[0]).find((t) => /\/player\/v\d+\/player\.js"/.test(t)) ?? "";
+  const known = (v) => (PRESENTER_STYLES.includes(v) ? v : null);
+  const deck = known(attr(tag, "data-presenter-style")) ?? known(manifest?.presenterStyle) ?? (attr(tag, "data-presenter") === "head" ? "stage" : "bubble");
+  const clips = new Map((Array.isArray(manifest?.clips) ? manifest.clips : []).map((c) => [c?.id, c]));
+  return slides(html).map((s) => ({ id: s.id, style: known(attr(s.tag, "data-presenter-style")) ?? known(clips.get(s.id)?.presenterStyle) ?? deck }));
+}
+
+// What each style occupies at desktop size, in stage pixels (player.css): the
+// head plus two caption lines. Corner sits in the stage's corner, not the slot.
+export const PRESENTER_FOOTPRINT = {
+  stage: { width: 480, height: 490 },
+  glass: { width: 522, height: 534 },
+  bubble: { width: 446, height: 304 },
+  corner: { width: 400, height: 330, right: 28, bottom: 28 },
+};
+
+// Measured boxes → warnings. Each entry: { id, style, presenter, title } with
+// { x, y, width, height } boxes (title null when the slide has none).
+export function overlapWarnings(measured, stage = "1600×900") {
+  const hit = (a, b) => a && b && Math.min(a.x + a.width, b.x + b.width) - Math.max(a.x, b.x) > 4 && Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y) > 4;
+  return measured.filter((m) => hit(m.presenter, m.title)).map((m) => MESSAGES.overlap(m.id, m.style, stage));
+}
+
+// Slides whose content overflows the phone card, as errors. Each entry: { id, overflow } in px.
+export function phoneOverflowErrors(measured) {
+  return measured.filter((m) => m.overflow > 1).map((m) => MESSAGES.phoneOverflow(m.id, Math.ceil(m.overflow)));
+}
+
+// Lay each slide out in Chromium at the deck's stage size with JavaScript off
+// (no player, no deck scripts), put the style's footprint in its slot, and
+// measure it against the title's text. Needs `hyperdecks preview setup`.
+export async function measureLayout(deckDir, styles, { width = 1600, height = 900 } = {}) {
+  return withDeckPage(deckDir, { width, height }, (page) => page.evaluate(({ styles, footprint, width, height }) => {
+    const box = (r) => ({ x: r.left, y: r.top, width: r.width, height: r.height });
+    const sections = [...document.querySelectorAll("section.slide")];
+    const host = sections[0]?.parentElement ?? document.body;
+    Object.assign(host.style, { position: "relative", width: `${width}px`, height: `${height}px`, overflow: "hidden", margin: "0" });
+    document.body.style.margin = "0";
+    return sections.map((slide, i) => {
+      sections.forEach((s) => { s.style.display = s === slide ? "" : "none"; Object.assign(s.style, { position: "absolute", inset: "0" }); });
+      const { id, style } = styles[i] ?? { id: slide.id, style: "bubble" };
+      const size = footprint[style];
+      const probe = document.createElement("div");
+      Object.assign(probe.style, { width: `${size.width}px`, height: `${size.height}px`, flex: "none" });
+      const slot = slide.querySelector(".narration-slot");
+      let presenter = null;
+      if (style === "corner" || !slot) {
+        const right = size.right ?? 56, bottom = size.bottom ?? 56;
+        presenter = { x: width - right - size.width, y: height - bottom - size.height, width: size.width, height: size.height };
+      } else {
+        slot.append(probe);
+        presenter = box(probe.getBoundingClientRect());
+        probe.remove();
+      }
+      const heading = slide.querySelector("h1, h2");
+      let title = null;
+      if (heading) {
+        const range = document.createRange();
+        range.selectNodeContents(heading);
+        const rects = [...range.getClientRects()].filter((r) => r.width && r.height);
+        if (rects.length) {
+          const [x0, y0] = [Math.min(...rects.map((r) => r.left)), Math.min(...rects.map((r) => r.top))];
+          title = { x: x0, y: y0, width: Math.max(...rects.map((r) => r.right)) - x0, height: Math.max(...rects.map((r) => r.bottom)) - y0 };
+        }
+      }
+      return { id, style, presenter, title };
+    });
+  }, { styles, footprint: PRESENTER_FOOTPRINT, width, height }));
+}
+
+// Lay each slide out as the framed player shows it on a phone: the deck's own
+// phone rules at a 390×844 viewport, its mobile titles, inside the card, with
+// JavaScript off. Returns { id, overflow } per slide: how far its content runs
+// past the slide's bottom (≤ 0 when it fits).
+export async function measurePhoneFit(deckDir) {
+  return withDeckPage(deckDir, { width: PHONE.width, height: PHONE.height }, (page) => page.evaluate((card) => {
+    for (const n of document.querySelectorAll("[data-title-mobile]")) n.textContent = n.dataset.titleMobile;
+    const sections = [...document.querySelectorAll("section.slide")];
+    const host = sections[0]?.parentElement ?? document.body;
+    Object.assign(host.style, { position: "relative", width: `${card.width}px`, height: `${card.height}px`, overflow: "hidden", margin: "0" });
+    document.body.style.margin = "0";
+    return sections.map((slide) => {
+      sections.forEach((s) => { s.style.display = s === slide ? "" : "none"; Object.assign(s.style, { position: "absolute", inset: "0", overflow: "hidden" }); });
+      return { id: slide.id, overflow: slide.scrollHeight - slide.clientHeight };
+    });
+  }, PHONE.card));
+}
+
+// Open the deck's index.html in Chromium at `viewport` with JavaScript off and
+// hand the page to `measure`. Needs `hyperdecks preview setup`.
+async function withDeckPage(deckDir, viewport, measure) {
+  const { chromium } = await import("playwright");
+  const { serveSource, routeCaptureRequest } = await import("./preview-capture.mjs");
+  const { mkdtemp, rm } = await import("node:fs/promises");
+  const { tmpdir } = await import("node:os");
+  // The same isolation as preview capture: a throwaway HOME, the sandbox on
+  // Linux, and its request filter (no loopback, private or metadata hosts).
+  const temp = await mkdtemp(join(tmpdir(), "hyperdecks-layout-"));
+  let browser, server;
+  try {
+    try {
+      browser = await chromium.launch({ headless: true, timeout: 30000, chromiumSandbox: process.platform === "linux", env: { ...(process.platform === "win32" ? { SystemRoot: process.env.SystemRoot } : {}), PATH: process.env.PATH, TMPDIR: temp, HOME: temp } });
+    } catch {
+      throw new Error("check --layout needs Chromium: run `hyperdecks preview setup`");
+    }
+    server = await serveSource({ file: join(deckDir, "index.html") });
+    const context = await browser.newContext({ viewport, javaScriptEnabled: false, serviceWorkers: "block" });
+    await context.route("**/*", (route) => routeCaptureRequest(route, server.url));
+    const page = await context.newPage();
+    await page.goto(server.url, { waitUntil: "load", timeout: 30000 });
+    await page.evaluate(() => document.fonts.ready);
+    return await measure(page);
+  } finally {
+    await server?.close().catch(() => {});
+    await browser?.close().catch(() => {});
+    await rm(temp, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
 // The deck's own cap: `maxTotalSeconds` in script.md's front matter.
 export function scriptCap(script) {
   const front = /^---\r?\n([\s\S]*?)\r?\n---/.exec(script)?.[1] ?? "";
@@ -228,7 +433,7 @@ const FETCH_TIMEOUT_MS = 30_000;
 const JSON_TYPE = /json/;
 
 // Run every rule on a deck folder. Returns { deckDir, slug, slides, totalDuration, errors }.
-export async function checkDeck(dirArg, opts = {}, { fetch: fetchImpl = globalThis.fetch, cwd } = {}) {
+export async function checkDeck(dirArg, opts = {}, { fetch: fetchImpl = globalThis.fetch, cwd, measure = measureLayout, measureFit = measurePhoneFit } = {}) {
   const deckDir = resolveDeckDir(dirArg, cwd);
   const html = readFileSync(join(deckDir, "index.html"), "utf8");
   const scriptPath = join(deckDir, "script.md");
@@ -292,6 +497,24 @@ export async function checkDeck(dirArg, opts = {}, { fetch: fetchImpl = globalTh
       errors.push(...timelineErrors(clip, timeline));
     }
   }
+  // A presenter over the title is a warning, not a failure: only a person can
+  // judge it. A slide that overflows the phone card is an error. Both need a
+  // browser, so they run only with --layout.
+  const warnings = [];
+  if (opts.layout) {
+    const [w, h] = /^(\d{3,4})x(\d{3,4})$/.exec(attr([...uncommented(html).matchAll(/<script\b[^>]*>/g)].map((m) => m[0]).find((t) => /\/player\/v\d+\/player\.js"/.test(t)) ?? "", "data-stage") ?? "")?.slice(1).map(Number) ?? [1600, 900];
+    try {
+      warnings.push(...overlapWarnings(await measure(deckDir, slideStyles(html, manifest), { width: w, height: h }), `${w}×${h}`));
+    } catch (e) {
+      warnings.push(MESSAGES.layoutUnchecked(e.message));
+    }
+    // A slide that scrolls on a phone fails: the player never scrolls a slide.
+    try {
+      errors.push(...phoneOverflowErrors(await measureFit(deckDir)));
+    } catch (e) {
+      warnings.push(MESSAGES.layoutUnchecked(e.message));
+    }
+  }
   return {
     deckDir,
     slug: opts.slug || basename(deckDir),
@@ -300,6 +523,7 @@ export async function checkDeck(dirArg, opts = {}, { fetch: fetchImpl = globalTh
     manifestUrl: player?.manifest ?? null,
     passed: errors.length === 0,
     errors,
+    warnings: [...new Set(warnings)],
   };
 }
 
@@ -311,6 +535,7 @@ export async function check(pos, opts = {}, { log = (line) => console.log(line),
       log(`✗ ${result.errors.length} issue(s):`);
       for (const e of result.errors) log(`  - ${e}`);
     } else log("✓ check passed");
+    for (const w of result.warnings) log(`  ⚠ ${w}`);
   }
   return result;
 }

package/src/commands.mjs

@@ -241,9 +241,10 @@ commands:
   logout [--dev]
   whoami [--json] [--dev]
   deck list|stats|open|rm
-  deck new <slug> "<title>" --narrated [--dir <path>]
-                   scaffold decks/<slug>/: index.html (8 slides, player/v1), script.md, evidence.md
-  check <slug|deck-dir> [--forbid "<phrase>,<phrase>"] [--max-duration <s>] [--json]
+  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
+                   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,
                    local refs, pinned player, a data-note per slide, mobile titles
   release <slug|deck-dir> [--to "<name>" [--email <e>]]... [--qa] [--no-notify] [--title t] [--voice v]
@@ -256,11 +257,24 @@ commands:
   skill install [--agent codex,claude-code] [--all-agents]
   skills install [--agent codex,claude-code] [--all-agents]
   activity [--deck <slug>] [--limit <n>] [--json]
-  gen-image "<prompt>" [--transparent] [--image <url>] [--size <s>] [--quality <q>] [--count <n>] [--slug <deck>] [--download <file>]
+  gen-image "<prompt>" [--model gpt-image-2.5|nano-banana-2.1|gpt-image-2] [--transparent] [--image <url>] [--size <s>]
+            [--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>" [--image <url>] [--seconds 5] [--aspect 16:9|9:16] [--slug <deck>] [--name <name>] [--download <file>]
-                   a 3–10s clip (no audio) via fal; --image animates that still and keeps its aspect
+  gen-video "<prompt>" [--model h3-max|kling-v3] [--image <url>] [--seconds 5] [--aspect 16:9|9:16] [--slug <deck>] [--name <name>] [--download <file>]
+                   a 3–10s clip via fal (default MiniMax H3 Max); --image animates that still and keeps its aspect
   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 <subject...> --style "<style>" [--palette "#hex,#hex"] [--slug <deck>] [--name <prefix>]
+                   a style-consistent set of transparent icons, one per subject (max 12)
+  review <slug> [--script <script.md>] [--json]
+                   GPT-6 Luna reviews every slide (desktop + phone screenshots) and lists what to fix
+  review-job <jobId> [--json]
+  poster <slug> [--force] [--json]
+                   regenerate the share-link poster (release makes one) and print its URL
   credits [--limit <n>] [--json]   show your credit balance and recent history
 
   preview create <slug> --out <directory> [--share <token>] [--upload] [--json]
@@ -289,7 +303,7 @@ async function genImage(pos, opts) {
   const prompt = pos.join(" ").trim() || opts.prompt;
   if (!prompt) {
     throw new Error(
-      'usage: gen-image "<prompt>" [--image <url>] [--transparent] [--size <s>] [--quality <q>] [--count <n>] [--format png|jpeg|webp] [--slug <deck>] [--name <name>] [--download <file>]',
+      'usage: gen-image "<prompt>" [--model gpt-image-2.5|nano-banana-2.1|gpt-image-2] [--image <url>] [--transparent] [--size <s>] [--quality <q>] [--count <n>] [--format png|jpeg|webp] [--seed <n>] [--slug <deck>] [--name <name>] [--download <file>]',
     );
   }
   let out = await ops.generateImage(opts, {
@@ -300,6 +314,8 @@ async function genImage(pos, opts) {
     quality: opts.quality,
     count: opts.count,
     format: opts.format,
+    model: opts.model,
+    seed: opts.seed,
     slug: opts.slug,
     name: opts.name,
   });
@@ -348,19 +364,20 @@ 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>" [--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] [--slug <deck>] [--name <name>] [--download <file>]');
   }
   const queued = await ops.generateVideo(opts, {
     prompt,
     image: opts.image,
     seconds: opts.seconds,
     aspect: opts.aspect,
+    model: opts.model,
     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 clip — job ${queued.jobId}\n`);
+  process.stderr.write(`queued a ${queued.seconds}s ${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`),
   });
@@ -391,6 +408,112 @@ async function videoJob(pos, opts) {
   if (job.video?.url) console.log(job.video.url);
 }
 
+async function screenshot(pos, opts) {
+  const [url] = pos;
+  if (!url) throw new Error("usage: screenshot <url> [--width 1440] [--height 900] [--full-page] [--slug <deck>] [--name <name>] [--download <file>]");
+  const out = await ops.captureUrl(opts, {
+    url,
+    width: opts.width,
+    height: opts.height,
+    fullPage: opts["full-page"],
+    slug: opts.slug,
+    name: opts.name,
+  });
+  // Print the paid asset's URL before downloading, so a failed download never hides it.
+  console.log(opts.json ? JSON.stringify(out, null, 2) : out.url);
+  if (out.creditsRemaining != null) process.stderr.write(`credits left: ${out.creditsRemaining}\n`);
+  await saveTo(opts.download, out.url);
+}
+
+async function chart(pos, opts) {
+  const [file] = pos;
+  if (!file) throw new Error("usage: chart <spec.json> [--slug <deck>] [--name <name>] [--download <file>]");
+  let spec;
+  try {
+    spec = JSON.parse(file === "-" ? readFileSync(0, "utf8") : readFileSync(file, "utf8"));
+  } catch (e) {
+    throw new Error(`could not read chart spec ${file}: ${e.message}`);
+  }
+  const out = await ops.renderChart(opts, { ...spec, slug: opts.slug ?? spec.slug, name: opts.name ?? spec.name });
+  console.log(opts.json ? JSON.stringify(out, null, 2) : out.url);
+  if (out.creditsRemaining != null) process.stderr.write(`credits left: ${out.creditsRemaining}\n`);
+  await saveTo(opts.download, out.url);
+}
+
+async function icons(pos, opts) {
+  if (!pos.length || !opts.style) {
+    throw new Error('usage: icons <subject...> --style "<style>" [--palette "#hex,#hex"] [--model nano-banana-2.1|gpt-image-2.5|gpt-image-2] [--slug <deck>] [--name <prefix>]');
+  }
+  const queued = await ops.generateIconSet(opts, {
+    subjects: pos,
+    style: opts.style,
+    palette: opts.palette ? String(opts.palette).split(",").map((c) => c.trim()).filter(Boolean) : undefined,
+    model: opts.model,
+    slug: opts.slug,
+    name: opts.name,
+  });
+  process.stderr.write(`queued ${queued.count} icon(s) — job ${queued.jobId}\n`);
+  const out = await ops.pollImageJob(opts, queued.jobId, {
+    onProgress: (job) => process.stderr.write(`  ${job.progress} (${job.status})…\r`),
+  });
+  process.stderr.write("\n");
+  if (opts.json) return void console.log(JSON.stringify({ ...out, subjects: queued.subjects }, null, 2));
+  (out.images || []).forEach((im, i) => console.log(`${queued.subjects[i] ?? im.name}\t${im.url}`));
+  if (out.creditsRemaining != null) process.stderr.write(`credits left: ${out.creditsRemaining}\n`);
+}
+
+function printReview(job) {
+  console.log(`review of ${job.slug}: ${job.fix} to fix, ${job.consider} to consider (${job.progress} slides, ${job.model})`);
+  for (const f of job.findings) {
+    console.log(`  [${f.severity}] ${f.slide} (${f.viewport}, ${f.category}): ${f.issue}`);
+    console.log(`         → ${f.suggestion}`);
+  }
+  for (const s of job.failedSlides || []) console.log(`  ! ${s.slide}: not reviewed (${s.error}); not charged`);
+  if (!job.findings.length && !job.failedSlides?.length) console.log("  no findings: every slide looks clean");
+}
+
+async function review(pos, opts) {
+  const [slug] = pos;
+  if (!slug) throw new Error("usage: review <slug> [--script <script.md>] [--json]");
+  const script = opts.script ? readFileSync(opts.script, "utf8") : undefined;
+  const queued = await ops.reviewDeck(opts, { slug, script });
+  process.stderr.write(`reviewing ${queued.slides} slide(s) on desktop and phone — job ${queued.jobId}\n`);
+  const job = await ops.pollReviewJob(opts, queued.jobId, {
+    onProgress: (j) => process.stderr.write(`  ${j.progress} slides…\r`),
+  });
+  process.stderr.write("\n");
+  if (opts.json) console.log(JSON.stringify(job, null, 2));
+  else printReview(job);
+}
+
+async function reviewJob(pos, opts) {
+  const [jobId] = pos;
+  if (!jobId) throw new Error("usage: review-job <jobId>");
+  const job = await ops.checkReviewJob(opts, jobId);
+  if (opts.json) return void console.log(JSON.stringify(job, null, 2));
+  console.log(`status:   ${job.status}`);
+  if (job.error) console.log(`error:    ${job.error}`);
+  printReview(job);
+}
+
+async function poster(pos, opts) {
+  const [slug] = pos;
+  if (!slug) throw new Error("usage: poster <slug> [--force] [--json]");
+  const out = await ops.generatePoster(opts, { slug, force: opts.force });
+  if (opts.json) return void console.log(JSON.stringify(out, null, 2));
+  if (out.unchanged) process.stderr.write("poster already matches the deck (pass --force to re-render)\n");
+  console.log(out.url);
+}
+
+// Download a hosted asset to `file` when --download was given.
+async function saveTo(file, url) {
+  if (!file || !url) return;
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`download of ${url} failed (${res.status})`);
+  writeFileSync(file, Buffer.from(await res.arrayBuffer()));
+  process.stderr.write(`saved to ${file}\n`);
+}
+
 // The command table: "<group> <cmd>" or "<group>" → handler. Exported (via
 // COMMANDS) so the CLI/MCP parity test can enumerate it.
 function commandTable(pos, rest, opts) {
@@ -473,6 +596,12 @@ function commandTable(pos, rest, opts) {
     "image-job": () => imageJob(pos.slice(1), opts),
     "gen-video": () => genVideo(pos.slice(1), opts),
     "video-job": () => videoJob(pos.slice(1), opts),
+    screenshot: () => screenshot(pos.slice(1), opts),
+    chart: () => chart(pos.slice(1), opts),
+    icons: () => icons(pos.slice(1), opts),
+    review: () => review(pos.slice(1), opts),
+    "review-job": () => reviewJob(pos.slice(1), opts),
+    poster: () => poster(pos.slice(1), opts),
     credits: () => credits(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)\s*=\s*(["'])([^"']+)\2/gi,
+    /\b(src|href|poster|data-presenter-image)\s*=\s*(["'])([^"']+)\2/gi,
     (match, attr, quote, raw) => {
       const url = resolveLocalUrl(raw, assetMap);
       return url ? `${attr}=${quote}${url}${quote}` : match;

package/src/narrate.mjs

@@ -52,7 +52,8 @@ export async function narrate(pos, opts = {}, { log = (line) => console.log(line
   const { deckDir, fields } = narrationRequest(pos, opts);
   if (opts["dry-run"]) {
     const preview = await ops.previewNarration(opts, fields);
-    for (const s of preview.slides) log(`${s.render ? "render" : s.cached ? "cached" : "skip  "}  ${s.id}  ${s.hash.slice(0, 12)}  ${s.chars} chars`);
+    if (preview.presenterStyle) log(`presenter style: ${preview.presenterStyle}`);
+    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`);
     return preview;