@hypersocial/decks-cli 0.2.1 → 0.3.0

package/src/layouts.mjs

@@ -0,0 +1,71 @@
+// The deck templates as text: the narrated outline and the layout library, filled
+// for a slug and title. No file I/O beyond reading the packaged templates, so the
+// hosted MCP route (new_deck) and the CLI (deck new) assemble the same deck.
+import { packageText } from "./files.mjs";
+
+export const NARRATED_FILES = { "index.html": "narrated-deck.html", "script.md": "script.md", "evidence.md": "evidence.md" };
+// The library, in a sensible deck order; `--layouts` takes any order and repeats.
+export const LAYOUTS = ["hero", "number", "product", "quote", "compare", "timeline", "features", "chart", "team", "closer"];
+const LAYOUT_ALIASES = { "big-number": "number", "product-shot": "product", comparison: "compare", "three-up": "features" };
+
+const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+
+// Template text with __SLUG__ / __TITLE__ filled; HTML gets an escaped title.
+// Without a presenter style the player tag carries none (the player's default).
+export function fillTemplate(file, { slug, title, presenterStyle }) {
+  const text = packageText(`templates/${file}`);
+  const t = /\.html$/.test(file) ? escapeHtml(title) : title;
+  const styled = presenterStyle ? text.split("__PRESENTER_STYLE__").join(presenterStyle) : text.replace(/\s*data-presenter-style="__PRESENTER_STYLE__"/g, "");
+  return styled.split("__SLUG__").join(slug).split("__TITLE__").join(t);
+}
+
+// One layout file: a leading comment of `key: value` lines (layout, summary,
+// use, slot, presenter, cues, script), its <style> and its <section>.
+export function readLayout(name) {
+  const text = packageText(`templates/layouts/${name}.html`);
+  const head = /^<!--([\s\S]*?)-->/.exec(text);
+  const style = /<style>[\s\S]*?<\/style>/.exec(text);
+  const section = /<section\b[\s\S]*<\/section>/.exec(text);
+  if (!head || !style || !section) throw new Error(`layout ${name}: needs a leading comment, a <style> and a <section>`);
+  const meta = {};
+  for (const line of head[1].split("\n")) {
+    const m = /^([a-z]+):\s*(.*)$/.exec(line.trim());
+    if (m) meta[m[1]] = m[2];
+  }
+  return { name, meta, style: style[0], section: section[0] };
+}
+
+export function parseLayouts(list) {
+  const names = String(list).split(",").map((n) => n.trim().toLowerCase()).filter(Boolean).map((n) => LAYOUT_ALIASES[n] ?? n);
+  const unknown = names.filter((n) => !LAYOUTS.includes(n));
+  if (unknown.length) throw new Error(`unknown layout${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")}: pick from ${LAYOUTS.join(", ")}`);
+  if (!names.length) throw new Error(`--layouts needs at least one of ${LAYOUTS.join(", ")}`);
+  return names;
+}
+
+// index.html, script.md and evidence.md for a deck of `layouts`, one slide
+// each, in order. A layout used twice gets ids hero, hero-2, …; ids inside a
+// slide start with its id, so its cues stay unique.
+export function assembleLayoutDeck({ slug, title, presenterStyle, layouts }) {
+  const names = parseLayouts(layouts);
+  const used = new Map();
+  const slides = names.map((name) => {
+    const n = (used.get(name) ?? 0) + 1;
+    used.set(name, n);
+    return { layout: readLayout(name), id: n === 1 ? name : `${name}-${n}` };
+  });
+  const fill = (text, id, t) => text.split("__ID__").join(id).split("__SLUG__").join(slug).split("__TITLE__").join(t);
+  const sections = slides.map(({ layout, id }, i) => {
+    let html = fill(layout.section, id, escapeHtml(title));
+    if (i === 0 && !/\sdata-intro=/.test(html.slice(0, html.indexOf(">")))) html = html.replace("<section ", '<section data-intro="Hi! Press play." ');
+    return `<!-- layout: ${layout.name}. ${layout.meta.summary ?? ""} -->\n${html}`;
+  });
+  const styles = [...new Set(names)].map((name) => `<!-- layout: ${name} -->\n${readLayout(name).style}`);
+  const shell = fillTemplate("layouts/_deck.html", { slug, title, presenterStyle });
+  // Function replacements: a "$" in the title or a layout is text, not a replacement pattern.
+  const html = shell.replace("<!-- LAYOUT STYLES -->", () => styles.join("\n")).replace("<!-- SLIDES -->", () => sections.join("\n\n"));
+  const intro = fillTemplate("script.md", { slug, title }).split(/\n## /)[0].trimEnd();
+  const script = `${intro}\n\n${slides.map(({ layout, id }) => `## ${id}\n${fill(layout.meta.script ?? "", id, title)}`).join("\n\n")}\n`;
+  return { "index.html": html, "script.md": script, "evidence.md": fillTemplate("evidence.md", { slug, title }) };
+}
+

package/src/narrate.mjs

@@ -8,18 +8,8 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import * as ops from "./ops.mjs";
-
-// Same rule as sectionIds() in lib/deckScript.ts (the published CLI cannot import it).
-export const sectionIds = (html) => [...html.matchAll(/<section\b[^>]*?\sid\s*=\s*["']([^"']+)["']/gi)].map((m) => m[1]);
-
-// Set data-manifest on the hosted player's <script> tag; html is unchanged when
-// there is no player tag or it already names this URL.
-export function setManifestUrl(html, url) {
-  return html.replace(/<script\b[^>]*\/player\/v\d+\/player\.js"[^>]*>/, (tag) =>
-    /\sdata-manifest\s*=\s*"[^"]*"/.test(tag)
-      ? tag.replace(/(\sdata-manifest\s*=\s*)"[^"]*"/, (_, lead) => `${lead}"${url}"`)
-      : tag.replace(/\s*>$/, () => ` data-manifest="${url}">`));
-}
+export { sectionIds, setManifestUrl } from "./checkRules.mjs";
+import { sectionIds, setManifestUrl } from "./checkRules.mjs";
 
 function slideList(value) {
   const ids = value.split(",").map((s) => s.trim()).filter(Boolean);
@@ -52,7 +42,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;

package/src/ops.mjs

@@ -36,7 +36,8 @@ export async function activityOverview(opts = {}) {
   return (await client(opts)).query(api.activity.overview, {});
 }
 
-// Generate an image via fal (GPT Image 2 t2i/i2i, optional BiRefNet transparency),
+// Generate an image via fal (GPT Image 2.5 by default, or Nano Banana 2.1 / GPT
+// Image 2 with `model`; t2i/i2i, optional BiRefNet transparency),
 // store it in Convex, and return the hosted URL. Runs the imagegen action as the
 // authenticated user (injected client supported via opts.client).
 export async function generateImage(opts, fields = {}) {
@@ -51,6 +52,8 @@ export async function generateImage(opts, fields = {}) {
   if (fields.quality) args.quality = String(fields.quality);
   if (fields.count != null && fields.count !== "") args.count = Number(fields.count);
   if (fields.format) args.format = String(fields.format);
+  if (fields.model) args.model = String(fields.model);
+  if (fields.seed != null && fields.seed !== "") args.seed = Number(fields.seed);
   // Returns { images } for fast requests, or { jobId, status, count } for slow ones
   // (high/auto quality, transparent, count>1). The MCP tool returns this as-is so it
   // never blocks; the CLI polls with pollImageJob to stay one-command (see commands).
@@ -99,8 +102,9 @@ export async function pollImageJob(opts, jobId, { intervalMs = 3000, timeoutMs =
 
 // ---- video (convex/videogen.ts) ------------------------------------------
 
-// Generate a short clip via fal (Kling v3: text→video, or image→video when an image
-// URL is given as the first frame). Always a background job: returns
+// 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
 // tool never blocks; the CLI polls with pollVideoJob.
 export async function generateVideo(opts, fields = {}) {
@@ -110,11 +114,100 @@ export async function generateVideo(opts, fields = {}) {
   if (img) args.imageUrl = String(img);
   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.slug) args.slug = String(fields.slug);
   if (fields.name) args.name = String(fields.name);
   return (await client(opts)).action(api.videogen.generateVideo, args);
 }
 
+// ---- deck assets: screenshots, charts, icon sets --------------------------
+
+// Screenshot a public URL (convex/screenshots.ts) and store it as a PNG asset.
+// Returns { url, storageId, contentType, name?, width, height, creditsRemaining? }.
+export async function captureUrl(opts, fields = {}) {
+  if (!fields.url) throw new Error("url is required");
+  const args = { url: String(fields.url) };
+  if (fields.width != null && fields.width !== "") args.width = Number(fields.width);
+  if (fields.height != null && fields.height !== "") args.height = Number(fields.height);
+  if (fields.fullPage) args.fullPage = true;
+  if (fields.slug) args.slug = String(fields.slug);
+  if (fields.name) args.name = String(fields.name);
+  return (await client(opts)).action(api.screenshots.captureUrl, args);
+}
+
+const CHART_FIELDS = ["kind", "title", "subtitle", "labels", "series", "values", "value", "label", "delta", "prefix", "suffix", "palette", "width", "height", "slug", "name"];
+
+// Render a chart spec (convex/charts.ts) to a branded SVG asset. Unknown keys are
+// dropped so a spec file may carry notes of its own.
+export async function renderChart(opts, spec = {}) {
+  if (!spec.kind) throw new Error("kind is required (bar, line, donut or number)");
+  const args = {};
+  for (const k of CHART_FIELDS) if (spec[k] !== undefined && spec[k] !== null) args[k] = spec[k];
+  return (await client(opts)).action(api.charts.renderChart, args);
+}
+
+// Queue a style-consistent transparent icon set (convex/imagegen.ts
+// generateIconSet). Returns { jobId, status, count, subjects }; poll it like any
+// image job (checkImageJob / pollImageJob).
+export async function generateIconSet(opts, fields = {}) {
+  const subjects = (fields.subjects || []).map(String).filter(Boolean);
+  if (!subjects.length) throw new Error("subjects is required (one or more things to draw)");
+  if (!fields.style) throw new Error("style is required");
+  const args = { subjects, style: String(fields.style) };
+  if (fields.palette?.length) args.palette = fields.palette.map(String);
+  if (fields.slug) args.slug = String(fields.slug);
+  if (fields.name) args.name = String(fields.name);
+  if (fields.model) args.model = String(fields.model);
+  return (await client(opts)).action(api.imagegen.generateIconSet, args);
+}
+
+// ---- share-link poster (convex/posters.ts) -------------------------------
+
+// Regenerate the deck's share-link poster (release and import already make
+// one). Returns { slug, url, unchanged }: unchanged when the poster already
+// shows the deck's current HTML, unless `force`.
+export async function generatePoster(opts, fields = {}) {
+  if (!fields.slug) throw new Error("slug is required");
+  const args = { slug: String(fields.slug) };
+  if (fields.force) args.force = true;
+  return (await client(opts)).action(api.posters.generatePoster, args);
+}
+
+// ---- deck review (convex/review.ts) --------------------------------------
+
+// Queue a GPT-6 Luna review of every slide (desktop + phone screenshots of the
+// deck's QA share). Returns { jobId, status, slides, shareToken, creditsRequired }.
+export async function reviewDeck(opts, fields = {}) {
+  if (!fields.slug) throw new Error("slug is required");
+  const args = { slug: String(fields.slug) };
+  if (fields.script) args.script = String(fields.script);
+  if (fields.draft) args.draft = true;
+  return (await client(opts)).action(api.review.reviewDeck, args);
+}
+
+export async function checkReviewJob(opts, jobId) {
+  if (!jobId) throw new Error("jobId is required");
+  return (await client(opts)).query(api.review.checkReviewJob, { jobId: String(jobId) });
+}
+
+// Poll a review job until it finishes; returns the job (findings and all).
+// Throws on job error or timeout.
+export async function pollReviewJob(opts, jobId, { intervalMs = 4000, timeoutMs = 1_800_000, onProgress } = {}) {
+  const c = await client(opts);
+  const start = Date.now();
+  for (;;) {
+    const job = await c.query(api.review.checkReviewJob, { jobId: String(jobId) });
+    if (job.status === "done") return job;
+    if (job.status === "error") {
+      const done = job.findings?.length ? ` (${job.progress} slides reviewed, ${job.findings.length} finding(s) so far: review-job ${jobId})` : "";
+      throw new Error(`${job.error || "review failed"}${done}`);
+    }
+    if (Date.now() - start > timeoutMs) throw new Error(`review ${jobId} is still running; check it later with: review-job ${jobId}`);
+    if (onProgress) onProgress(job);
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+}
+
 // Read one video job's status (and the hosted MP4 once done). Shared by the MCP
 // check_video_job tool and the CLI poller.
 export async function checkVideoJob(opts, jobId) {
@@ -153,8 +246,9 @@ export async function pollVideoJob(opts, jobId, { intervalMs = 5000, timeoutMs =
 // thin client calls shared by the CLI `narrate` command and the MCP tools.
 function narrationArgs(fields = {}) {
   if (!fields.slug) throw new Error("slug is required");
-  if (!fields.script) throw new Error("script is required (the deck's script.md)");
-  const args = { slug: String(fields.slug), script: String(fields.script) };
+  // No script: narrate the deck's hosted script.md (deckSources), and the
+  // finished job writes the manifest URL into the hosted draft.
+  const args = fields.script ? { slug: String(fields.slug), script: String(fields.script) } : { slug: String(fields.slug), fromSource: true };
   if (fields.voice) args.voice = String(fields.voice);
   if (fields.slides) {
     if (!fields.slides.length) throw new Error("slides is empty; omit it to narrate every slide");
@@ -613,7 +707,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, srcset, <script>/<link>,
+// ext-resource-dependency manifest, src/href/poster/data-presenter-image, 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) {
@@ -625,7 +719,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)\s*=\s*["']([^"']+)["']/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(/\bsrcset\s*=\s*["']([^"']+)["']/gi)) {
     for (const part of m[1].split(",")) add(part.trim().split(/\s+/)[0]);
   }

package/src/runtime.mjs

@@ -8,7 +8,7 @@ import { fileURLToPath } from "node:url";
 import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
 
-export const VERSION = "0.1.12";
+export const VERSION = "0.3.0";
 const UPLOAD_TIMEOUT_MS = 125_000;
 
 export const PROD = {
@@ -24,6 +24,16 @@ export const api = {
     generateUploadUrl: makeFunctionReference("assets:generateUploadUrl"),
     saveAsset: makeFunctionReference("assets:saveAsset"),
   },
+  assetsNode: {
+    importAssetFromUrl: makeFunctionReference("assetsNode:importAssetFromUrl"),
+  },
+  deckSources: {
+    create: makeFunctionReference("deckSources:create"),
+    get: makeFunctionReference("deckSources:get"),
+    write: makeFunctionReference("deckSources:write"),
+    check: makeFunctionReference("deckSources:check"),
+    release: makeFunctionReference("deckSources:release"),
+  },
   activity: {
     overview: makeFunctionReference("activity:overview"),
     setArchived: makeFunctionReference("activity:setArchived"),
@@ -50,6 +60,20 @@ export const api = {
   imagegen: {
     generateImage: makeFunctionReference("imagegen:generateImage"),
     checkImageJob: makeFunctionReference("imagegen:checkImageJob"),
+    generateIconSet: makeFunctionReference("imagegen:generateIconSet"),
+  },
+  screenshots: {
+    captureUrl: makeFunctionReference("screenshots:captureUrl"),
+  },
+  charts: {
+    renderChart: makeFunctionReference("charts:renderChart"),
+  },
+  posters: {
+    generatePoster: makeFunctionReference("posters:generatePoster"),
+  },
+  review: {
+    reviewDeck: makeFunctionReference("review:reviewDeck"),
+    checkReviewJob: makeFunctionReference("review:checkReviewJob"),
   },
   videogen: {
     generateVideo: makeFunctionReference("videogen:generateVideo"),
@@ -75,7 +99,7 @@ export const api = {
   },
 };
 
-const BOOL = new Set(["prod", "dev", "admin", "json", "require-email", "qa", "no-notify", "help", "version", "all-agents", "global", "project", "transparent", "upload", "dry-run", "narrated"]);
+const BOOL = new Set(["prod", "dev", "admin", "json", "require-email", "qa", "no-notify", "help", "version", "all-agents", "global", "project", "transparent", "upload", "dry-run", "narrated", "layout", "full-page", "force", "hosted", "yes", "no-voice", "no-skill", "no-release", "no-open"]);
 // release's recipients, in order: each --to starts one, and an --email right
 // after it belongs to it (`--to A --email a --to B`). Collected as opts.recipients;
 // opts.email stays the last --email for the other commands (share new).
@@ -260,7 +284,42 @@ function splitAgents(value) {
   return String(value || "").split(/[,\s]+/).filter(Boolean);
 }
 
-export function installHyperdecksSkill(opts = {}, extraArgs = []) {
+export const DEFAULT_AGENTS = ["codex", "claude-code"];
+
+// Agents `npx skills` installs into, keyed by its agent id: the directory whose
+// presence means the agent is installed (the same test `npx skills` uses) and
+// where its global skills live. From skills@1.7 (dist/cli.mjs, agent table).
+export function agentTable({ home = homedir(), env = process.env } = {}) {
+  const config = env.XDG_CONFIG_HOME || join(home, ".config");
+  const claude = env.CLAUDE_CONFIG_DIR || join(home, ".claude");
+  return [
+    { id: "claude-code", label: "Claude Code", home: claude, skills: join(claude, "skills") },
+    { id: "codex", label: "Codex", home: env.CODEX_HOME || join(home, ".codex"), skills: join(home, ".agents", "skills") },
+    { id: "cursor", label: "Cursor", home: join(home, ".cursor"), skills: join(home, ".cursor", "skills") },
+    { id: "gemini-cli", label: "Gemini CLI", home: join(home, ".gemini"), skills: join(home, ".gemini", "skills") },
+    { id: "opencode", label: "OpenCode", home: join(config, "opencode"), skills: join(config, "opencode", "skills") },
+    { id: "windsurf", label: "Windsurf", home: join(home, ".codeium", "windsurf"), skills: join(home, ".codeium", "windsurf", "skills") },
+    { id: "github-copilot", label: "GitHub Copilot", home: join(home, ".copilot"), skills: join(home, ".copilot", "skills") },
+  ];
+}
+
+// The agents whose home directory exists on this machine.
+export function detectAgents({ home, env, exists = existsSync } = {}) {
+  return agentTable({ home, env }).filter((a) => exists(a.home)).map((a) => a.id);
+}
+
+// Which agents an install targets: --all-agents, --agent, or the detected ones
+// (today's codex,claude-code when none is found).
+export function chooseAgents(opts = {}, extraArgs = [], detect = {}) {
+  if (opts["all-agents"]) return { agents: ["*"], source: "all" };
+  if (opts.agent) return { agents: [...splitAgents(opts.agent), ...extraArgs.flatMap(splitAgents)], source: "flag" };
+  const found = detectAgents(detect);
+  return found.length ? { agents: found, source: "detected" } : { agents: DEFAULT_AGENTS, source: "default" };
+}
+
+// `quiet` pipes `npx skills` output instead of inheriting the terminal (init
+// --json keeps stdout for its one JSON object); a failure then carries its tail.
+export function installHyperdecksSkill(opts = {}, extraArgs = [], { spawn = spawnSync, quiet = false, log = (line) => console.log(line), home, env } = {}) {
   const skillDir = join(PACKAGED_SKILLS_DIR, "hyperdecks");
   if (!existsSync(skillDir)) {
     throw new Error(`packaged hyperdecks skill not found at ${skillDir}`);
@@ -278,19 +337,19 @@ export function installHyperdecksSkill(opts = {}, extraArgs = []) {
     throw new Error(`unexpected argument(s): ${extraArgs.join(" ")}; pass agent ids with --agent`);
   }
 
-  const agents = opts["all-agents"]
-    ? ["*"]
-    : [...splitAgents(opts.agent || "codex,claude-code"), ...extraArgs.flatMap(splitAgents)];
+  const { agents, source } = chooseAgents(opts, extraArgs, { home, env });
+  if (source === "default" && !quiet) log(`no agent found in your home directory; installing for ${agents.join(", ")}`);
   const args = ["-y", "skills@latest", "add", PACKAGED_SKILLS_DIR, "-g"];
   args.push("-a", ...agents, "-s", "hyperdecks", "--copy", "-y", "--full-depth");
 
   const command = process.platform === "win32" ? "npx.cmd" : "npx";
-  const result = spawnSync(command, args, { stdio: "inherit" });
+  const result = spawn(command, args, quiet ? { stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" } : { stdio: "inherit" });
   if (result.error) throw result.error;
   if (result.status !== 0) {
-    throw new Error(`skills add failed with exit code ${result.status}`);
+    const tail = quiet ? `${result.stdout || ""}\n${result.stderr || ""}`.trim().split("\n").filter((l) => l.trim() && !/^npm warn/i.test(l)).slice(-3).join(" ") : "";
+    throw new Error(`skills add failed with exit code ${result.status}${tail ? `: ${tail}` : ""}`);
   }
-  return { installed: true };
+  return { installed: true, agents, source };
 }
 
 async function verifyAndStampEmail(t, opts) {
@@ -302,14 +361,14 @@ async function verifyAndStampEmail(t, opts) {
   return who;
 }
 
-export async function login(opts) {
+export async function login(opts, { log = (line) => console.log(line), open = openBrowser } = {}) {
   const t = target(opts);
 
   if (opts.token) {
     saveCred(t.name, { refreshToken: opts.token, convexUrl: t.convexUrl, brokerBase: t.brokerBase });
     try {
       const who = await verifyAndStampEmail(t, opts);
-      console.log(`OK logged in to ${t.name}${who.email ? ` as ${who.email}` : ""}`);
+      log(`OK logged in to ${t.name}${who.email ? ` as ${who.email}` : ""}`);
     } catch (e) {
       clearCred(t.name);
       throw e;
@@ -367,14 +426,14 @@ export async function login(opts) {
     server.listen(0, "127.0.0.1", () => {
       const { port } = server.address();
       const url = `${t.brokerBase}/cli/authorize?port=${port}&state=${state}`;
-      console.log(`Opening your browser to sign in (${t.name})...\n  ${url}\nIf it does not open, paste that URL into your browser.`);
-      openBrowser(url);
+      log(`Opening your browser to sign in (${t.name})...\n  ${url}\nIf it does not open, paste that URL into your browser.`);
+      open(url);
     });
     timer = setTimeout(() => finish(new Error("login timed out after 3 min")), 180000);
   });
 
   const who = await verifyAndStampEmail(t, opts);
-  console.log(`OK logged in to ${t.name}${who.email ? ` as ${who.email}` : ""}`);
+  log(`OK logged in to ${t.name}${who.email ? ` as ${who.email}` : ""}`);
 }
 
 export async function logout(opts) {

package/src/scaffold.mjs

@@ -1,39 +1,40 @@
-// hyperdecks deck new <slug> "<title>" --narrated [--dir <path>]
+// hyperdecks deck new <slug> "<title>" --narrated [--layouts hero,product,…] [--presenter-style stage|bubble|glass|corner] [--dir <path>]
 //
 // Writes decks/<slug>/ (or --dir) from the packaged templates: index.html (eight
-// slides for the hosted player/v1), script.md (the narration) and evidence.md
-// (where each fact comes from), then registers the deck as a draft you own so
-// narrate can render into it.
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+// slides for the hosted player/v1, or one slide per --layouts entry from
+// templates/layouts/), script.md (the narration) and evidence.md (where each
+// fact comes from), then registers the deck as a draft you own so narrate can
+// render into it.
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
 import * as ops from "./ops.mjs";
+import { PRESENTER_STYLES } from "./checkRules.mjs";
+import { LAYOUTS, NARRATED_FILES, assembleLayoutDeck, fillTemplate } from "./layouts.mjs";
 
-export const TEMPLATE_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "templates");
-export const NARRATED_FILES = { "index.html": "narrated-deck.html", "script.md": "script.md", "evidence.md": "evidence.md" };
-const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
-
-const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+export { LAYOUTS, NARRATED_FILES, assembleLayoutDeck, fillTemplate, parseLayouts, readLayout } from "./layouts.mjs";
 
-// Template text with __SLUG__ / __TITLE__ filled; HTML gets an escaped title.
-export function fillTemplate(file, { slug, title }) {
-  const text = readFileSync(join(TEMPLATE_DIR, file), "utf8");
-  const t = /\.html$/.test(file) ? escapeHtml(title) : title;
-  return text.split("__SLUG__").join(slug).split("__TITLE__").join(t);
-}
+const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const USAGE = 'usage: deck new <slug> "<title>" --narrated [--layouts hero,product,number,closer] [--presenter-style <stage|bubble|glass|corner>] [--dir <path>]';
 
 export async function deckNew(pos, opts = {}, { log = (line) => console.log(line), cwd = process.cwd() } = {}) {
   const [slug, title] = pos;
-  if (!slug || !title) throw new Error('usage: deck new <slug> "<title>" --narrated [--dir <path>]');
+  if (!slug || !title) throw new Error(USAGE);
   if (!opts.narrated) throw new Error("the published CLI scaffolds narrated decks only: add --narrated");
+  const presenterStyle = opts["presenter-style"];
+  if (presenterStyle !== undefined && !PRESENTER_STYLES.includes(presenterStyle)) {
+    throw new Error(`--presenter-style must be one of ${PRESENTER_STYLES.join(", ")}`);
+  }
   if (!SLUG.test(slug)) throw new Error("slug must be lowercase letters, digits and dashes (max 64)");
-  const dir = resolve(cwd, typeof opts.dir === "string" ? opts.dir : join("decks", slug));
+  const dir = resolve(/*turbopackIgnore: true*/ cwd, typeof opts.dir === "string" ? opts.dir : join("decks", slug));
   if (existsSync(dir)) throw new Error(`${dir} already exists; pick another slug or --dir`);
-  const files = Object.entries(NARRATED_FILES).map(([out, file]) => [out, fillTemplate(file, { slug, title })]);
+  if (opts.layouts === true) throw new Error(`--layouts needs a list, e.g. --layouts ${LAYOUTS.slice(0, 3).join(",")},closer`);
+  const files = opts.layouts !== undefined
+    ? Object.entries(assembleLayoutDeck({ slug, title, presenterStyle, layouts: opts.layouts }))
+    : Object.entries(NARRATED_FILES).map(([out, file]) => [out, fillTemplate(file, { slug, title, presenterStyle })]);
   await ops.createDeck(opts, { slug, title });
   try {
     mkdirSync(dir, { recursive: true });
-    for (const [out, text] of files) writeFileSync(join(dir, out), text);
+    for (const [out, text] of files) writeFileSync(join(/*turbopackIgnore: true*/ dir, out), text);
   } catch (e) {
     rmSync(dir, { recursive: true, force: true });
     throw new Error(`deck ${slug} is registered but its files could not be written (${e.message}); remove the draft with \`hyperdecks deck rm ${slug}\` and run deck new again`);

package/src/source.mjs

@@ -0,0 +1,69 @@
+// The hosted deck source (convex/deckSources.ts): a deck's files kept on
+// Hyperdecks as a draft, for chat agents on the remote MCP and for
+//   hyperdecks deck new <slug> "<title>" --narrated --hosted [--layouts …]
+//   hyperdecks source pull <slug> [dir]     the draft into a folder
+//   hyperdecks source push <slug> [dir] [--base-rev N]   a folder's files to the draft
+//   hyperdecks check <slug> --hosted
+//   hyperdecks release <slug> --hosted [--to "<name>" [--email e]]... [--qa]
+//   hyperdecks asset add <slug> <file|url> [--name n]
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, extname, join, resolve } from "node:path";
+import { api, client, uploadBytes } from "./runtime.mjs";
+import { SOURCE_FILES, getDeckSource, uploadDeckAsset, writeDeckSource } from "./hosted.mjs";
+
+export * from "./hosted.mjs";
+
+// ---- CLI ------------------------------------------------------------------
+
+export async function sourcePull(pos, opts = {}, { log = (line) => console.log(line), cwd = process.cwd() } = {}) {
+  const [slug, dirArg] = pos;
+  if (!slug) throw new Error("usage: source pull <slug> [dir]");
+  const dir = resolve(/*turbopackIgnore: true*/ cwd, dirArg ?? join("decks", slug));
+  const got = await getDeckSource(opts, { slug });
+  mkdirSync(dir, { recursive: true });
+  const written = [];
+  for (const [file, text] of Object.entries(got.files)) {
+    if (typeof text !== "string") continue;
+    writeFileSync(join(/*turbopackIgnore: true*/ dir, file), text);
+    written.push(file);
+  }
+  log(`✓ pulled ${slug} rev ${got.rev} → ${dir} (${written.join(", ")})\n  push it back with: hyperdecks source push ${slug} ${dirArg ?? dir} --base-rev ${got.rev}`);
+  return { slug, rev: got.rev, dir, files: written };
+}
+
+export async function sourcePush(pos, opts = {}, { log = (line) => console.log(line), cwd = process.cwd() } = {}) {
+  const [slug, dirArg] = pos;
+  if (!slug) throw new Error("usage: source push <slug> [dir] [--base-rev N]");
+  const dir = resolve(/*turbopackIgnore: true*/ cwd, dirArg ?? join("decks", slug));
+  const files = SOURCE_FILES.filter((f) => existsSync(join(/*turbopackIgnore: true*/ dir, f)));
+  if (!files.includes("index.html")) throw new Error(`no index.html in ${dir}`);
+  let baseRev = opts["base-rev"] !== undefined ? Number(opts["base-rev"]) : undefined;
+  let rev;
+  for (const file of files) {
+    ({ rev } = await writeDeckSource(opts, { slug, file, content: readFileSync(join(/*turbopackIgnore: true*/ dir, file), "utf8"), baseRev }));
+    baseRev = baseRev === undefined ? undefined : rev; // each write moves the rev
+  }
+  log(`✓ pushed ${files.join(", ")} to ${slug}: rev ${rev}`);
+  return { slug, rev, files };
+}
+
+const TYPES = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp", ".avif": "image/avif", ".svg": "image/svg+xml", ".mp4": "video/mp4", ".webm": "video/webm", ".woff2": "font/woff2", ".woff": "font/woff" };
+
+export async function assetAdd(pos, opts = {}, { log = (line) => console.log(line), cwd = process.cwd() } = {}) {
+  const [slug, from] = pos;
+  if (!slug || !from) throw new Error("usage: asset add <slug> <file|url> [--name <name>]");
+  let out;
+  if (/^https?:\/\//i.test(from)) out = await uploadDeckAsset(opts, { slug, name: opts.name, url: from });
+  else {
+    const path = resolve(/*turbopackIgnore: true*/ cwd, from);
+    const contentType = TYPES[extname(path).toLowerCase()];
+    if (!contentType) throw new Error(`${from}: asset add takes images, video and fonts (${Object.keys(TYPES).join(" ")})`);
+    const c = await client(opts);
+    const bytes = readFileSync(path);
+    const storageId = await uploadBytes(c, bytes, contentType);
+    const saved = await c.mutation(api.assets.saveAsset, { name: String(opts.name || basename(path)), storageId, contentType, deckSlug: slug });
+    out = { url: saved.url, name: saved.name, contentType, bytes: bytes.byteLength };
+  }
+  log(out.url);
+  return out;
+}

package/src/voice.mjs

@@ -11,6 +11,17 @@ import * as ops from "./ops.mjs";
 // Same text as convex/lib/voice/consent.ts (the published CLI cannot import it).
 export const CONSENT_STATEMENT = "I confirm this is my own voice and I consent to it being cloned for narrating my decks";
 export const CONSENT_PHRASE = "I consent";
+// About 45 s read aloud at an easy pace (init prints it to record). Plain
+// sentences with varied sounds, questions and numbers give the clone range.
+export const READING_PASSAGE = [
+  "Hi, this is a recording of my own voice, for my Hyperdecks presenter.",
+  "I'm reading at my normal pace, the way I would talk to a friend across the table.",
+  "Some days start slowly, with coffee and a long list. Others start with a phone call at seven thirty.",
+  "Either way, I like to get to the point: what's the problem, who has it, and what would make it better?",
+  "When I show people my work, I want them to hear me, not a robot.",
+  "So here are a few numbers, said clearly: twelve, forty-five, three hundred, and two thousand and six.",
+  "Thanks for listening. That's the end of my sample.",
+].join(" ");
 export const MAX_SAMPLES = 3;
 export const MAX_SAMPLE_BYTES = 10 * 1024 * 1024;
 const TYPES = { ".mp3": "audio/mpeg", ".m4a": "audio/mp4", ".wav": "audio/wav" };

package/templates/first-deck/character.json

@@ -0,0 +1,26 @@
+{
+  "about": "The first deck `hyperdecks init` makes when D.A.S.H. presents: the same three slides, introduced in the third person. D.A.S.H. quotes the answers rather than rephrasing them, so no pronoun is guessed from a name.",
+  "hero": {
+    "kicker": "Meet",
+    "title": "Meet __NAME__.",
+    "lead": "__WHAT__",
+    "script": "Hi, [wave] I'm D.A.S.H. [look: h1] I'm here to introduce __NAME__."
+  },
+  "features": {
+    "kicker": "In short",
+    "title": "Three things to know.",
+    "cards": [
+      { "name": "Who", "line": "__NAME__" },
+      { "name": "What", "line": "__WHAT__" },
+      { "name": "The ask", "line": "__ASK__" }
+    ],
+    "script": "Three quick things. [go: #features-f1] Who this is. [go: #features-f2] What __NAME__ does, in their own words. __WHAT__ [go: #features-f3] And what __NAME__ would love from you. [go: slot]"
+  },
+  "closer": {
+    "title": "Thanks.",
+    "lead": "What __NAME__ would love from you:",
+    "cta": "__ASK__",
+    "contact": "Presented by D.A.S.H. on hyperdecks.ai",
+    "script": "Here's the ask. [go: #closer-cta] __ASK__ Thanks [go: slot] for watching! [wave]"
+  }
+}

package/templates/first-deck/self.json

@@ -0,0 +1,26 @@
+{
+  "about": "The first deck `hyperdecks init` makes, in your own voice: three slides from your three answers. __NAME__, __WHAT__ and __ASK__ are the answers; text is escaped before it goes into index.html.",
+  "hero": {
+    "kicker": "Hello",
+    "title": "Hi, I'm __NAME__.",
+    "lead": "__WHAT__",
+    "script": "Hi, [wave] I'm __NAME__. [look: h1] Thanks for taking a minute to watch this."
+  },
+  "features": {
+    "kicker": "In short",
+    "title": "Me, in three cards.",
+    "cards": [
+      { "name": "Who", "line": "__NAME__" },
+      { "name": "What I do", "line": "__WHAT__" },
+      { "name": "My ask", "line": "__ASK__" }
+    ],
+    "script": "Here's me, in three cards. [go: #features-f1] Who I am. [go: #features-f2] What I do. __WHAT__ [go: #features-f3] And what I'd love from you. [go: slot]"
+  },
+  "closer": {
+    "title": "Thanks.",
+    "lead": "One thing I'd love from you:",
+    "cta": "__ASK__",
+    "contact": "Made with hyperdecks.ai",
+    "script": "So here's my ask. [go: #closer-cta] __ASK__ Thanks [go: slot] for watching! [wave]"
+  }
+}