@hypersocial/decks-cli 0.1.12 → 0.2.1

package/src/release.mjs

@@ -0,0 +1,133 @@
+// hyperdecks release <slug|deck-dir> [--to "<name>" [--email <e>]]... [--qa] [--no-notify] [--title t] [--voice v] [--forbid "…"]
+//
+// check → narrate → import → share new, from a committed deck folder:
+//   1. refuses while the deck folder has uncommitted changes, so every release
+//      corresponds to a commit;
+//   2. runs check (the same rules as `hyperdecks check`) and stops on any issue;
+//   3. runs narrate, which re-renders only changed slides. If that changes the
+//      deck folder (a new manifest URL in index.html), release stops and asks for
+//      a commit, then a second release goes through;
+//   4. imports index.html plus the local files it references (nothing else in the
+//      folder: script.md, evidence.md and narration/ stay private);
+//   5. creates one share per --to (paired in order with --email) and prints the URLs.
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join, posix } from "node:path";
+import { zipSync } from "fflate";
+import * as ops from "./ops.mjs";
+import { target } from "./runtime.mjs";
+import { checkDeck, localRefs, resolveDeckDir } from "./check.mjs";
+import { narrate as runNarrate } from "./narrate.mjs";
+
+const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+// `git status --porcelain` for the deck folder; throws outside a repository.
+export function deckChanges(deckDir) {
+  try {
+    return execFileSync("git", ["-C", deckDir, "status", "--porcelain", "--untracked-files=all", "--", "."], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trimEnd();
+  } catch (e) {
+    throw new Error(`release needs the deck in a git repository, so a release corresponds to a commit (${String(e.stderr || e.message).trim()})`);
+  }
+}
+
+// Files git does not track (ignored, or never added) can't be part of a commit.
+export function untrackedFiles(deckDir, files) {
+  return files.filter((f) => {
+    try {
+      execFileSync("git", ["-C", deckDir, "ls-files", "--error-unmatch", "--", f], { stdio: "ignore" });
+      return false;
+    } catch {
+      return true;
+    }
+  });
+}
+
+export function deckCommit(deckDir) {
+  return execFileSync("git", ["-C", deckDir, "rev-parse", "--short", "HEAD"], { encoding: "utf8" }).trim();
+}
+
+// What import uploads: the page alone, or a zip of the page and its local files.
+export function releaseBundle(deckDir) {
+  const html = readFileSync(join(deckDir, "index.html"));
+  // check has already refused refs that leave the folder or do not decode.
+  const refs = [...new Set(localRefs(html.toString("utf8")).map((r) => posix.normalize(decodeURIComponent(r)).replace(/^(\.?\/)+/, "")))];
+  if (!refs.length) return { bytes: html, filename: "index.html", files: ["index.html"] };
+  const files = { "index.html": html };
+  for (const ref of refs) files[ref] = readFileSync(join(deckDir, ref));
+  return { bytes: Buffer.from(zipSync(files)), filename: "deck.zip", htmlFile: "index.html", files: Object.keys(files) };
+}
+
+// From the CLI, parse() collects opts.recipients in order (each --email follows
+// its --to); MCP passes the same shape.
+export function recipients(opts) {
+  const list = opts.recipients ?? [];
+  if (!Array.isArray(list)) throw new Error("recipients must be a list");
+  if (list.some((r) => !String(r?.recipient ?? "").trim())) throw new Error("every recipient needs a name");
+  return list.map((r) => ({ recipient: String(r.recipient).trim(), email: r.email ? String(r.email) : undefined }));
+}
+
+export async function release(pos, opts = {}, io = {}) {
+  const { log = (line) => console.log(line), changes = deckChanges, untracked = untrackedFiles, commit = deckCommit, narrate = runNarrate, fetch, cwd } = io;
+  const deckDir = resolveDeckDir(pos[0], cwd);
+  const to = recipients(opts);
+
+  const dirty = changes(deckDir);
+  if (dirty) throw new Error(`refusing to release: ${deckDir} has uncommitted changes\n${dirty}\ncommit them first so the release corresponds to a commit`);
+
+  const checked = await checkDeck(deckDir, opts, { fetch, cwd });
+  const slug = opts.slug || checked.slug;
+  if (!SLUG.test(slug)) throw new Error(`"${slug}" is not a deck slug (lowercase letters, digits, dashes): rename the folder or pass --slug`);
+  if (checked.errors.length) throw new Error(`check failed for ${slug}:\n${checked.errors.map((e) => `  - ${e}`).join("\n")}`);
+  const bundle = releaseBundle(deckDir);
+  const loose = untracked(deckDir, bundle.files);
+  if (loose.length) throw new Error(`refusing to release: git does not track ${loose.join(", ")} (ignored or never added); commit them so the release corresponds to a commit`);
+  log(`✓ check passed: ${checked.slides} slides, ${checked.totalDuration}s`);
+
+  // Cached slides cost nothing, so this only renders what changed since the commit.
+  // Only the options narrate understands: an undefined --slide/--voice key would fail its flag check.
+  const narrateOpts = { ...opts, slug };
+  for (const k of ["slide", "json", "dry-run", "to", "email", "recipients"]) delete narrateOpts[k];
+  if (narrateOpts.voice === undefined) delete narrateOpts.voice;
+  const job = await narrate([deckDir], narrateOpts, { log });
+  if (!job?.manifestUrl) throw new Error(`narration finished without a manifest (${job?.notice || "no manifest URL"}); fix it and release again`);
+  const after = changes(deckDir);
+  if (after) {
+    throw new Error(`narration changed the deck (${after.split("\n").length} file(s)):\n${after}\n` +
+      `run \`hyperdecks check ${pos[0]}\`, look at it, commit (index.html and narration/), then run release again`);
+  }
+  const imported = await ops.importDeckFromBytes(opts, {
+    slug,
+    title: opts.title,
+    status: opts.status || "live",
+    bytes: bundle.bytes,
+    filename: bundle.filename,
+    htmlFile: bundle.htmlFile,
+  });
+  const sha = commit(deckDir);
+  log(`✓ imported "${imported.title}" as ${imported.slug} (${bundle.files.length} file(s), commit ${sha})\n  deck: ${imported.deckUrl}`);
+
+  const base = target(opts).shareBase;
+  const shares = [];
+  for (const r of to) {
+    let token;
+    try {
+      ({ token } = await ops.createShare(opts, {
+        slug: imported.slug,
+        recipient: r.recipient,
+        email: r.email,
+        qa: opts.qa || undefined,
+        notify: opts["no-notify"] ? false : undefined,
+      }));
+    } catch (e) {
+      // The deck is already live and earlier links exist: say so, so a retry does not duplicate them.
+      const made = shares.map((s) => `  ${s.recipient}: ${s.url}`).join("\n") || "  (none)";
+      throw new Error(`share for "${r.recipient}" failed: ${ops.errorText(e)}\nthe deck is imported (${imported.deckUrl}); links already created:\n${made}\n` +
+        `create the rest with \`hyperdecks share new ${imported.slug} "<name>"\` rather than releasing again`);
+    }
+    const share = { recipient: r.recipient, email: r.email, qa: !!opts.qa, url: `${base}/v/${token}` };
+    shares.push(share);
+    log(`✓ share for "${r.recipient}"${share.qa ? " (QA, untracked)" : ""} → ${share.url}`);
+  }
+  if (!shares.length) log(`  no --to given: \`hyperdecks share new ${imported.slug} "Me" --qa\` makes a link for your own viewing`);
+  return { slug: imported.slug, deckDir, commit: sha, deckUrl: imported.deckUrl, totalDuration: checked.totalDuration, files: bundle.files, shares };
+}

package/src/runtime.mjs

@@ -51,13 +51,42 @@ export const api = {
     generateImage: makeFunctionReference("imagegen:generateImage"),
     checkImageJob: makeFunctionReference("imagegen:checkImageJob"),
   },
+  videogen: {
+    generateVideo: makeFunctionReference("videogen:generateVideo"),
+    checkVideoJob: makeFunctionReference("videogen:checkVideoJob"),
+  },
+  narration: {
+    preview: makeFunctionReference("narration:preview"),
+    narrateDeck: makeFunctionReference("narration:narrateDeck"),
+    getJob: makeFunctionReference("narration:getJob"),
+    listVoices: makeFunctionReference("narration:listVoices"),
+  },
+  voices: {
+    listVoices: makeFunctionReference("voices:listVoices"),
+    getVoice: makeFunctionReference("voices:getVoice"),
+    addSample: makeFunctionReference("voices:addSample"),
+    cloneVoice: makeFunctionReference("voices:cloneVoice"),
+    renameVoice: makeFunctionReference("voices:renameVoice"),
+    deleteVoice: makeFunctionReference("voices:deleteVoice"),
+  },
   credits: {
     getBalance: makeFunctionReference("credits:getBalance"),
     getLedger: makeFunctionReference("credits:getLedger"),
   },
 };
 
-const BOOL = new Set(["prod", "dev", "admin", "json", "require-email", "qa", "no-notify", "help", "version", "all-agents", "global", "project", "transparent", "upload"]);
+const BOOL = new Set(["prod", "dev", "admin", "json", "require-email", "qa", "no-notify", "help", "version", "all-agents", "global", "project", "transparent", "upload", "dry-run", "narrated"]);
+// 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).
+function addRecipient(opts, k, v) {
+  if (v === undefined || v.startsWith("--")) throw new Error(`--${k} requires a value`);
+  const list = (opts.recipients ||= []);
+  if (k === "to") return void list.push({ recipient: v });
+  const last = list[list.length - 1];
+  if (!last || last.email !== undefined) throw new Error("each --email must follow the --to it belongs to");
+  last.email = v;
+}
 
 export const CRED_DIR = join(homedir(), ".config", "hypersocial-decks");
 export const CRED_FILE = join(CRED_DIR, "credentials.json");
@@ -74,7 +103,9 @@ export function parse(args) {
       if (BOOL.has(k)) opts[k] = true;
       else {
         const v = args[++i];
-        opts[k] = k === "agent" && opts[k] ? `${opts[k]},${v}` : v;
+        if (k === "to" || (k === "email" && opts.recipients)) addRecipient(opts, k, v);
+        if (k === "agent" && opts[k]) opts[k] = `${opts[k]},${v}`;
+        else opts[k] = v;
       }
     } else {
       pos.push(a);

package/src/scaffold.mjs

@@ -0,0 +1,43 @@
+// hyperdecks deck new <slug> "<title>" --narrated [--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";
+import * as ops from "./ops.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;");
+
+// 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);
+}
+
+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 (!opts.narrated) throw new Error("the published CLI scaffolds narrated decks only: add --narrated");
+  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));
+  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 })]);
+  await ops.createDeck(opts, { slug, title });
+  try {
+    mkdirSync(dir, { recursive: true });
+    for (const [out, text] of files) writeFileSync(join(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`);
+  }
+  log(`✓ created deck "${slug}" → ${dir}\n  files: ${Object.keys(NARRATED_FILES).join(", ")}\n  next:  hyperdecks narrate ${dir} --dry-run`);
+  return { slug, title, dir, files: Object.keys(NARRATED_FILES) };
+}

package/src/voice.mjs

@@ -0,0 +1,87 @@
+// hyperdecks voice clone <file...> --name <name> | voice upload <file...> | voice list | voice rm <name|id>
+//
+// Cloning runs on the backend with the platform ElevenLabs key (convex/voices.ts).
+// This checks the files, asks for consent, uploads the samples, starts the clone
+// and polls it. Nothing is uploaded until the user has typed the consent phrase.
+import { readFileSync, statSync } from "node:fs";
+import { extname, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+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";
+export const MAX_SAMPLES = 3;
+export const MAX_SAMPLE_BYTES = 10 * 1024 * 1024;
+const TYPES = { ".mp3": "audio/mpeg", ".m4a": "audio/mp4", ".wav": "audio/wav" };
+
+// The checks that need no server: count, extension and size. Length (30 s to 3
+// min in total) and the real format are checked on the server before any
+// provider call.
+export function sampleFiles(paths) {
+  if (!paths.length) throw new Error("usage: voice clone <file...> --name <name>   (1 to 3 mp3, m4a or wav recordings, 30 s to 3 min in total)");
+  if (paths.length > MAX_SAMPLES) throw new Error(`at most ${MAX_SAMPLES} recordings per voice (got ${paths.length})`);
+  return paths.map((p) => {
+    const path = resolve(p);
+    const contentType = TYPES[extname(path).toLowerCase()];
+    if (!contentType) throw new Error(`${p}: recordings must be .mp3, .m4a or .wav`);
+    let size;
+    try {
+      size = statSync(path).size;
+    } catch {
+      throw new Error(`${p}: no such file`);
+    }
+    if (size > MAX_SAMPLE_BYTES) throw new Error(`${p}: ${(size / 1024 / 1024).toFixed(1)} MB; each recording must be at most 10 MB`);
+    return { path, contentType, size };
+  });
+}
+
+async function askLine(question) {
+  // Consent is the person's to type: piped input is refused, not read.
+  if (!process.stdin.isTTY) throw new Error("voice clone needs a terminal to ask for consent; agents use voice upload and the MCP clone_voice tool");
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    return await rl.question(question);
+  } catch {
+    return ""; // stdin closed
+  } finally {
+    rl.close();
+  }
+}
+
+async function upload(opts, files, log) {
+  const ids = [];
+  for (const f of files) {
+    const { sampleId } = await ops.uploadVoiceSample(opts, { bytes: readFileSync(f.path), contentType: f.contentType });
+    log(`  uploaded ${f.path} (${(f.size / 1024 / 1024).toFixed(1)} MB)`);
+    ids.push(sampleId);
+  }
+  return ids;
+}
+
+export async function voiceClone(pos, opts = {}, { ask = askLine, log = (line) => console.error(line) } = {}) {
+  if (typeof opts.name !== "string" || !opts.name.trim()) throw new Error("usage: voice clone <file...> --name <name>");
+  const files = sampleFiles(pos);
+  const name = opts.name.trim();
+  if ((await ops.listVoices(opts)).some((x) => x.name.toLowerCase() === name.toLowerCase())) {
+    throw new Error(`you already have a voice called "${name}"; pick another --name or voice rm it first`);
+  }
+  log(`Cloning a voice named "${name}" from ${files.length} recording(s).\n`);
+  log(`  "${CONSENT_STATEMENT}"\n`);
+  const answer = await ask(`Type "${CONSENT_PHRASE}" to agree and upload: `);
+  if (answer.trim() !== CONSENT_PHRASE) throw new Error("consent not given; nothing was uploaded");
+  const sampleIds = await upload(opts, files, log);
+  const { voiceId, cost } = await ops.cloneVoice(opts, {
+    name, sampleIds, consent: { method: "cli-typed-phrase", statement: CONSENT_STATEMENT },
+  });
+  log(`cloning voice ${voiceId}${cost ? ` (${cost} credits, refunded if it fails)` : ""}…`);
+  const voice = await ops.pollVoice(opts, voiceId);
+  if (voice.status === "failed") throw new Error(`voice clone failed: ${voice.error}`);
+  log(`✓ voice "${voice.name}" is ready: hyperdecks narrate <deck-dir> --voice "${voice.name}"`);
+  return voice;
+}
+
+// For agents using the MCP clone_voice tool: upload recordings, print sample ids.
+export async function voiceUpload(pos, opts = {}, { log = (line) => console.error(line) } = {}) {
+  return { sampleIds: await upload(opts, sampleFiles(pos), log) };
+}

package/templates/evidence.md

@@ -0,0 +1,16 @@
+# __TITLE__ — evidence
+
+Every fact on a slide traces to a source the deck's author can open. One row per
+fact: the slide id, the claim as it appears, where it came from and when. The
+slide's `data-note` names the same source in a few words. This file stays in the
+deck folder; `hyperdecks release` does not upload it.
+
+| Slide | Claim | Source | Date |
+|---|---|---|---|
+| problem | | | |
+| why-now | | | |
+| proof | | | |
+
+Proposed (not yet agreed): list every slide that proposes rather than reports.
+
+- ask

package/templates/narrated-deck.html

@@ -0,0 +1,125 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>__TITLE__</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@500;700&family=Space+Mono:wght@400;700&display=swap">
+<style>
+  /* A narrated deck: slides only. The hosted player (player/v1) scales the
+     stage, draws the chrome and the presenter, and plays the narration. */
+  :root { --ink: #0b0b0f; --paper: #fafaf7; --accent: #ffda1b; --font: "Space Grotesk", system-ui, sans-serif; --mono: "Space Mono", ui-monospace, monospace; }
+  body { color: var(--ink); font-family: var(--font); --hd-font: var(--font); --hd-mono: var(--mono); }
+  .slide { display: flex; flex-direction: column; gap: 28px; padding: 64px 72px 56px; background: var(--paper); }
+  .slide.accent { background: var(--accent); }
+  .kicker { font: 18px var(--mono); letter-spacing: .16em; text-transform: uppercase; }
+  .tt { font-size: 104px; line-height: .95; letter-spacing: -.045em; margin: 0; text-wrap: balance; }
+  .lead { font-size: 32px; line-height: 1.3; max-width: 30em; margin: 0; }
+  .content { flex: 1; display: flex; flex-direction: column; justify-content: center; gap: 28px; padding-right: 320px; }
+  /* The presenter (face + caption bubble) moves into each slide's slot. */
+  .narration-slot { position: absolute; right: 56px; bottom: 72px; }
+  .reveal { opacity: 0; transition: opacity .4s; }
+  .reveal.is-revealed { opacity: 1; }
+  @media (max-width: 650px) {
+    .slide { padding: 40px 20px 150px; }
+    .tt { font-size: 40px; }
+    .lead { font-size: 18px; }
+    .content { padding-right: 0; justify-content: flex-start; }
+    .narration-slot { right: 12px; left: 12px; bottom: 72px; }
+  }
+</style>
+</head>
+<body>
+
+<!-- One <section class="slide" id> per slide, one idea each. The id joins the
+     slide to its narration (`## <id>` in script.md), #scene=<id> links and the events.
+     data-note:         where this slide's facts come from (a file, a thread, a doc).
+                        `hyperdecks check` fails a slide without one.
+     data-intro:        the bubble's text before the narration plays.
+     data-title-mobile: shorter text below 650px; check requires it on any title
+                        over 28 characters. Every slide here carries one. -->
+<section class="slide accent" id="hello" data-chapter="Hello" data-intro="Hi! Press play." data-note="Title slide: no facts.">
+  <div class="content">
+    <div class="kicker">__SLUG__</div>
+    <h1 class="tt" data-title-mobile="__TITLE__">__TITLE__</h1>
+  </div>
+  <div class="narration-slot"></div>
+</section>
+
+<section class="slide" id="problem" data-chapter="Problem" data-note="Source: name the document, email or thread the problem comes from.">
+  <div class="content">
+    <div class="kicker">The problem</div>
+    <h2 class="tt" data-title-mobile="The problem.">The problem, in one line.</h2>
+    <p class="lead">One sentence on who has it and what it costs them.</p>
+  </div>
+  <div class="narration-slot"></div>
+</section>
+
+<section class="slide accent" id="why-now" data-chapter="Why now" data-note="Source: name where the timing evidence comes from.">
+  <div class="content">
+    <div class="kicker">Why now</div>
+    <h2 class="tt" data-title-mobile="Why now.">Why this matters now.</h2>
+    <p class="lead">The change that makes this the moment.</p>
+  </div>
+  <div class="narration-slot"></div>
+</section>
+
+<section class="slide" id="idea" data-chapter="The idea" data-note="Source: name the doc or conversation the idea is drawn from.">
+  <div class="content">
+    <div class="kicker">The idea</div>
+    <h2 class="tt" data-title-mobile="The idea.">One idea per slide.</h2>
+    <p class="lead reveal" id="detail">Revealed by a [reveal: #detail] cue in script.md.</p>
+  </div>
+  <div class="narration-slot"></div>
+</section>
+
+<section class="slide accent" id="how" data-chapter="How" data-note="Source: name the spec, repo or notes this is based on.">
+  <div class="content">
+    <div class="kicker">How it works</div>
+    <h2 class="tt" data-title-mobile="How it works.">How it works.</h2>
+    <p class="lead">Three steps at most, in the audience's words.</p>
+  </div>
+  <div class="narration-slot"></div>
+</section>
+
+<section class="slide" id="proof" data-chapter="Proof" data-note="Source: name the metric's dashboard, report or email, with its date.">
+  <div class="content">
+    <div class="kicker">Proof</div>
+    <h2 class="tt" data-title-mobile="The proof.">The evidence so far.</h2>
+    <p class="lead">A number with its source and date, never an estimate shown as fact.</p>
+  </div>
+  <div class="narration-slot"></div>
+</section>
+
+<section class="slide accent" id="ask" data-chapter="The ask" data-note="Proposed: not agreed with anyone yet.">
+  <div class="content">
+    <div class="kicker">Proposed</div>
+    <h2 class="tt" data-title-mobile="The ask.">What we propose next.</h2>
+    <p class="lead">Label anything not yet agreed as proposed.</p>
+  </div>
+  <div class="narration-slot"></div>
+</section>
+
+<section class="slide" id="bye" data-chapter="Bye" data-note="Closing slide: no facts.">
+  <div class="content">
+    <h2 class="tt" data-title-mobile="Thanks.">Thanks for watching.</h2>
+  </div>
+  <div class="narration-slot"></div>
+</section>
+
+<!-- `hyperdecks narrate decks/__SLUG__` fills data-manifest with the manifest
+     URL it writes. data-presenter: head (live Minimoji, needs
+     data-avatar), static (data-presenter-image) or none (captions only). -->
+<script type="module" src="https://decks.hypersocial.ai/player/v1/player.js"
+        data-manifest="" data-stage="1600x900" data-presenter="none"></script>
+<!-- Slide controllers for anything the built-in cues don't cover:
+<script type="module">
+  window.hyperdecks.register("point", {
+    onEnter(ctx) {}, onExit(ctx) {}, prebuild(ctx) {},
+    onCue(cue, ctx) { if (cue.action === "custom:confetti") { /* … */ } },
+  });
+</script> -->
+</body>
+</html>

package/templates/script.md

@@ -0,0 +1,42 @@
+---
+maxTotalSeconds: 180
+---
+
+# __TITLE__ — narration script
+
+One `## <slide-id>` block per slide, in slide order; the id is the slide's
+`<section id>` in index.html. Each sentence is one caption: keep it a short
+phrase (4 to 85 characters, two lines in the bubble). Aim for 150 to 180 s in
+all. Holds: 1.1 s by default, `hold: 2` on interactive slides. Stage tags become
+cues at the word before them: [wave], [mood: excited], [reveal: #detail],
+[custom: confetti]. With no `voice:` above, your first ready voice narrates.
+
+    hyperdecks narrate decks/__SLUG__ --dry-run
+    hyperdecks narrate decks/__SLUG__
+    hyperdecks check decks/__SLUG__
+
+## hello
+Hi, [wave] this is __TITLE__. Let me walk you through it.
+
+## problem
+Here is the problem. It costs people real time.
+
+## why-now
+Why now? Something just changed.
+
+## idea
+Every slide makes one point. Here is the detail. [reveal: #detail]
+
+## how
+It works in three steps. Each one is simple.
+
+## proof
+Here is the evidence so far. Every number has a source.
+
+## ask
+hold: 2
+
+This part is a proposal. Nothing here is agreed yet.
+
+## bye
+That's it. Thanks for watching! [wave]