@hypersocial/decks-cli 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypersocial/decks-cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Command-line client for Hypersocial Decks live analytics and share management.",
   "type": "module",
   "main": "./src/commands.mjs",

package/skills/hyperdecks/SKILL.md

@@ -56,6 +56,9 @@ returns a link; hand it to them, word for word, and wait.
 | Make one the default (the person named it) | `hyperdecks narrator default <name>` | `set_default_narrator` |
 | Remove one (confirm first) | `hyperdecks narrator remove <name>` | `remove_narrator` |
 | Change its voice (the person asked) | `hyperdecks narrator voice <name> <voice>` | `set_narrator_voice` |
+| Rename it (the person asked) | `hyperdecks narrator rename <name> <new name>` | `rename_narrator` |
+| Change its face to one of their avatars (the person named it) | `hyperdecks narrator face <name> <avatar>` | `set_narrator_face` |
+| Hear a voice or a narrator | `hyperdecks voice hear <voice>` (`--narrator <name>`) → `url`, `caption` | `hear_voice` |
 | One deck's own narrator | `hyperdecks deck narrator <slug> <name\|none\|default>` | `set_deck_narrator` |
 
 ### Avatars: who presents a deck in the user's voice

package/skills/hyperdecks/chat.md

@@ -7,6 +7,18 @@ reaches a recipient until `release_deck`. Topics: call `deck_guide` with
 `format`, `script`, `design`, `layouts`, `presenter`, `transitions` or `check`
 before the step that needs it.
 
+## First time here?
+
+`get_started` with no answers says where the person stands (ready voices,
+narrators, credits) and the steps. No voice of their own: `clone_voice_link`
+(they record in the browser), or `clone_voice` with 1-3 recordings they attach
+in the chat, only after they agree to the consent statement, word for word.
+`hear_voice` plays a voice or a narrator in the chat. A face from a photo they
+attach: `avatar_from_photo { file }`, then `check_avatar_draft` until it hands
+back the link they approve it on. `rename_narrator` and `set_narrator_face`
+change a narrator when they ask. Then `get_started { name, about, ask, voice }`
+makes the hello deck; continue from step 5 below.
+
 ## The loop
 
 1. `deck_guide` (this page), then `deck_guide { topic: "layouts" }` to pick slides.
@@ -31,8 +43,17 @@ before the step that needs it.
 8. `release_deck { slug, qa: true }` gives the user a QA link to watch first.
    `release_deck { slug, recipients: [{ recipient, email }] }` makes one
    tracked link each. Release creates live links: confirm the recipients with
-   the user before you call it.
-9. Later: `list_shares`, `deck_stats`, `activity_overview`.
+   the user before you call it. In Claude and ChatGPT the result shows as a
+   deck card: the deck playing from its QA link (the draft before release),
+   with each share link and its opens. Never paste a recipient's link to "test"
+   it: opening it counts as their open.
+9. Later: `list_shares` and `deck_stats` (both show the card),
+   `activity_overview`; `email_embed { token }` for the HTML that pastes into an
+   email as the deck's moving preview (it needs a recipient's link, not a QA
+   one); `set_share_notify` to mute a link's "opened" alerts;
+   `set_recipient_archived` to tidy the activity feed; `credits` for the
+   balance. `remove_deck` deletes a deck and breaks every link to it: confirm
+   with the user first.
 
 ## Rules that matter
 

package/src/commands.mjs

@@ -368,6 +368,8 @@ commands:
                    asks you to type "I consent" before anything is uploaded
   voice upload <file...>   upload recordings and print their sample ids (for the MCP clone_voice tool)
   voice rm <name|id>       delete a voice, also at the provider
+  voice hear <voice> | voice hear --narrator <name|id>
+                   a short sample of the voice: its clip URL and the line it says
   avatar [--json]          your avatars (who presents decks in your voice) and the default
   avatar new [--species <s>]   pick a species, then an avatar (s shuffles); --json or an agent gets a pick link
   avatar from-photo [file] [--save-to-minimoji]
@@ -381,6 +383,8 @@ commands:
   narrator default <name|id|dash>   make it the default
   narrator remove <name|id>         remove it; decks already shared keep working
   narrator voice <name|id> <voice>  change its voice (one of yours, or dash)
+  narrator rename <name|id> <new name>   rename it
+  narrator face <name|id> <avatar>  change its face (one of your avatars)
   deck narrator <slug> <name|id|none|default>   the deck's own narrator (none: captions only)
 
 global:
@@ -766,6 +770,21 @@ function commandTable(pos, rest, opts) {
       const out = await ops.setNarratorVoice(opts, rest[0], rest.slice(1).join(" "));
       console.log(opts.json ? JSON.stringify(out, null, 2) : `OK ${out.name} speaks in ${out.voice} now`);
     },
+    "narrator rename": async () => {
+      if (rest.length < 2) throw new Error("usage: narrator rename <name|id> <new name>");
+      const out = await ops.renameNarrator(opts, rest[0], rest.slice(1).join(" "));
+      console.log(opts.json ? JSON.stringify(out, null, 2) : `OK ${out.was} is ${out.name} now`);
+    },
+    "narrator face": async () => {
+      if (rest.length < 2) throw new Error("usage: narrator face <name|id> <avatar>");
+      const out = await ops.setNarratorFace(opts, rest[0], rest.slice(1).join(" "));
+      console.log(opts.json ? JSON.stringify(out, null, 2) : `OK ${out.name} wears ${out.face} now`);
+    },
+    "voice hear": async () => {
+      if (!rest[0] && !opts.narrator) throw new Error("usage: voice hear <voice> | voice hear --narrator <name|id>");
+      const out = await ops.hearVoice(opts, opts.narrator ? { narrator: opts.narrator } : { voice: rest.join(" ") });
+      console.log(opts.json ? JSON.stringify(out, null, 2) : `"${out.caption}"\n  ${out.url}`);
+    },
     "deck narrator": async () => {
       if (rest.length < 2) throw new Error("usage: deck narrator <slug> <name|id|none|default>");
       const out = await ops.setDeckNarrator(opts, rest[0], rest.slice(1).join(" "));

package/src/files.mjs

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

package/src/firstDeck.mjs

@@ -0,0 +1,105 @@
+// The first deck `hyperdecks init` (and the hosted get_started tool) makes: a
+// three-slide hello deck (hero, features, closer) filled from three answers.
+// No file or process I/O beyond the packaged templates, so the hosted MCP route
+// can bundle it.
+import { packageText } from "./files.mjs";
+import { slugify } from "./importer.mjs";
+
+export const FIRST_DECK_LAYOUTS = "hero,features,closer";
+export const DASH_AVATAR = "https://decks.hypersocial.ai/player/v1/dash-avatar.json";
+export const ANSWER_MAX = { name: 40, about: 80, ask: 80 };
+
+// One answer as it goes on a slide and into the script: one line, no stage-tag
+// brackets, ending in a full stop so it is its own caption.
+export function cleanAnswer(key, value) {
+  const text = String(value ?? "").replace(/[[\]]/g, "").replace(/\s+/g, " ").trim();
+  if (text.length < 2) throw new Error(`--${key} needs an answer`);
+  if (text.length > ANSWER_MAX[key]) throw new Error(`--${key} is ${text.length} characters; keep it to ${ANSWER_MAX[key]} so it fits a caption`);
+  return key === "name" ? text.replace(/[.!?]+$/, "") : /[.!?…]$/.test(text) ? text : `${text}.`;
+}
+
+export const firstDeckSlug = (email) => `hello-${slugify(String(email ?? "").split("@")[0]) || "there"}`.slice(0, 58).replace(/-+$/, "");
+
+const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+
+export function firstDeckCopy(presenter) {
+  return JSON.parse(packageText(`templates/first-deck/${presenter === "dash" ? "character" : "self"}.json`));
+}
+
+function slots(text, answers, html) {
+  const map = { __NAME__: answers.name, __WHAT__: answers.about, __ASK__: answers.ask };
+  return text.replace(/__NAME__|__WHAT__|__ASK__/g, (k) => (html ? escapeHtml(map[k]) : map[k]));
+}
+
+// Replace exactly one match, or fail loudly: a layout change must not ship a deck
+// that still says "One sentence on what this deck is about."
+function swap(html, pattern, to, what) {
+  let hit = 0;
+  const out = html.replace(pattern, (...m) => (hit++, typeof to === "function" ? to(...m) : to));
+  if (hit !== 1) throw new Error(`first deck: the ${what} in the layout template changed (${hit} matches); update init's first-deck fill`);
+  return out;
+}
+
+function section(html, id, edit) {
+  return swap(html, new RegExp(`<section\\b[^>]*\\sid="${id}"[\\s\\S]*?</section>`), (s) => edit(s), `#${id} slide`);
+}
+
+// index.html and script.md of the scaffolded hero,features,closer deck, filled
+// with the answers: no template copy is left, and no generated imagery.
+export function fillFirstDeck({ html, title, answers, presenter, voice }) {
+  const copy = firstDeckCopy(presenter);
+  const h = (t) => slots(t, answers, true);
+  const note = (s) => swap(s, /\sdata-note="[^"]*"/, ' data-note="From your init answers."', "data-note");
+  let out = section(html, "hero", (s) => {
+    s = note(s);
+    s = swap(s, /<div class="kicker">[^<]*<\/div>/, `<div class="kicker">${h(copy.hero.kicker)}</div>`, "hero kicker");
+    s = swap(s, /<h1 class="tt"[^>]*>[\s\S]*?<\/h1>/, `<h1 class="tt" data-title-mobile="${h(copy.hero.title)}">${h(copy.hero.title)}</h1>`, "hero title");
+    return swap(s, /<p class="lead">[\s\S]*?<\/p>/, `<p class="lead">${h(copy.hero.lead)}</p>`, "hero lead");
+  });
+  out = section(out, "features", (s) => {
+    s = note(s);
+    s = swap(s, /<div class="kicker">[^<]*<\/div>/, `<div class="kicker">${h(copy.features.kicker)}</div>`, "features kicker");
+    s = swap(s, /<h2 class="tt"[^>]*>[\s\S]*?<\/h2>/, `<h2 class="tt" data-title-mobile="${h(copy.features.title)}">${h(copy.features.title)}</h2>`, "features title");
+    copy.features.cards.forEach((card, i) => {
+      s = swap(s, new RegExp(`(<li class="card" id="features-f${i + 1}">[\\s\\S]*?</svg>)<b>[^<]*</b><p>[^<]*</p>`), (_, icon) => `${icon}<b>${h(card.name)}</b><p>${h(card.line)}</p>`, `features card ${i + 1}`);
+    });
+    return s;
+  });
+  out = section(out, "closer", (s) => {
+    s = note(s);
+    s = swap(s, /<h2 class="tt"[^>]*>[\s\S]*?<\/h2>/, `<h2 class="tt" data-title-mobile="${h(copy.closer.title)}">${h(copy.closer.title)}</h2>`, "closer title");
+    s = swap(s, /<p class="lead">[\s\S]*?<\/p>/, `<p class="lead">${h(copy.closer.lead)}</p>`, "closer lead");
+    s = swap(s, /<a class="cta"[^>]*>[\s\S]*?<\/a>/, `<p class="cta" id="closer-cta">${h(copy.closer.cta)}</p>`, "closer call to action");
+    return swap(s, /<div class="contact muted">[^<]*<\/div>/, `<div class="contact muted">${h(copy.closer.contact)}</div>`, "closer contact");
+  });
+  // A character's live head presents its own deck; a person's voice ships with
+  // captions only (data-presenter="none"), never on a character's face.
+  if (presenter === "dash") {
+    out = swap(out, /(<script type="module" src="https:\/\/decks\.hypersocial\.ai\/player\/v1\/player\.js"[^>]*?)\sdata-presenter="none"/, (_, tag) => `${tag} data-presenter="head" data-avatar="${DASH_AVATAR}"`, "player tag");
+  }
+  const s = (t) => slots(t, answers, false);
+  const script = `---
+voice: ${voice}
+maxTotalSeconds: 90
+transition: drift
+---
+
+# ${title} — narration script
+
+Written by \`hyperdecks init\` from your three answers. Make it yours: rewrite
+these lines and the slides in index.html, then
+
+    hyperdecks narrate .
+    hyperdecks release . --to "<name>"
+
+## hero
+${s(copy.hero.script)}
+
+## features
+${s(copy.features.script)}
+
+## closer
+${s(copy.closer.script)}
+`;
+  return { html: out, script };
+}

package/src/init.mjs

@@ -6,7 +6,8 @@
 // QA link and print it. Every step checks real state before it acts, so running
 // init again resumes where it stopped and changes nothing once it is complete.
 // Each step returns { step, status: "done" | "skipped" | "ran" | "needs-human", detail }.
-// CLI-only, like login: there is no MCP tool for it.
+// In chat (no folder, no git) the hosted MCP's get_started tool walks the same
+// steps on a hosted draft (lib/getStarted.ts); the deck fill is shared (firstDeck.mjs).
 import { execFileSync } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
@@ -15,7 +16,7 @@ import { dirname, join, relative, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import * as ops from "./ops.mjs";
-import { slugify } from "./importer.mjs";
+import { ANSWER_MAX, DASH_AVATAR, FIRST_DECK_LAYOUTS, cleanAnswer, fillFirstDeck, firstDeckCopy, firstDeckSlug } from "./firstDeck.mjs";
 import { agentTable, api, chooseAgents, client, CRED_DIR, installHyperdecksSkill, login as runLogin, openBrowser, target } from "./runtime.mjs";
 import { READING_PASSAGE, voiceClone as runVoiceClone } from "./voice.mjs";
 import { assembleLayoutDeck, deckNew as runDeckNew } from "./scaffold.mjs";
@@ -23,17 +24,13 @@ import { narrate as runNarrate } from "./narrate.mjs";
 import { release as runRelease } from "./release.mjs";
 
 export const STATE_FILE = join(CRED_DIR, "init.json");
-export const FIRST_DECK_LAYOUTS = "hero,features,closer";
-export const DASH_AVATAR = "https://decks.hypersocial.ai/player/v1/dash-avatar.json";
 // Same numbers as convex/lib/tokenCost.ts (the published CLI cannot import it).
 export const VOICE_CLONE_COST = 10;
 export const STARTER_GRANT = 30;
-export const ANSWER_MAX = { name: 40, about: 80, ask: 80 };
 const SKILL_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "skills", "hyperdecks");
-// CLI-only, so read next to the package rather than through files.mjs (the hosted route's list).
-const FIRST_DECK_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "templates", "first-deck");
 const CHARACTERS = ["dash", "d.a.s.h."];
 const RESUME = "npx hyperdecks init";
+export { ANSWER_MAX, DASH_AVATAR, FIRST_DECK_LAYOUTS, cleanAnswer, fillFirstDeck, firstDeckCopy, firstDeckSlug };
 export const AGENT_VOICE_HELP = "ask the user to run `npx hyperdecks voice clone <file> --name <name>` in a terminal, " +
   "or upload with `voice upload` and call `clone_voice` after they agree to the statement; " +
   "or run init again with `--voice dash` to let D.A.S.H. present";
@@ -66,100 +63,6 @@ export function writeState(path, all) {
 
 // ---- answers and the first deck -------------------------------------------
 
-// One answer as it goes on a slide and into the script: one line, no stage-tag
-// brackets, ending in a full stop so it is its own caption.
-export function cleanAnswer(key, value) {
-  const text = String(value ?? "").replace(/[[\]]/g, "").replace(/\s+/g, " ").trim();
-  if (text.length < 2) throw new Error(`--${key} needs an answer`);
-  if (text.length > ANSWER_MAX[key]) throw new Error(`--${key} is ${text.length} characters; keep it to ${ANSWER_MAX[key]} so it fits a caption`);
-  return key === "name" ? text.replace(/[.!?]+$/, "") : /[.!?…]$/.test(text) ? text : `${text}.`;
-}
-
-export const firstDeckSlug = (email) => `hello-${slugify(String(email ?? "").split("@")[0]) || "there"}`.slice(0, 58).replace(/-+$/, "");
-
-const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
-
-export function firstDeckCopy(presenter) {
-  return JSON.parse(readFileSync(join(FIRST_DECK_DIR, `${presenter === "dash" ? "character" : "self"}.json`), "utf8"));
-}
-
-function slots(text, answers, html) {
-  const map = { __NAME__: answers.name, __WHAT__: answers.about, __ASK__: answers.ask };
-  return text.replace(/__NAME__|__WHAT__|__ASK__/g, (k) => (html ? escapeHtml(map[k]) : map[k]));
-}
-
-// Replace exactly one match, or fail loudly: a layout change must not ship a deck
-// that still says "One sentence on what this deck is about."
-function swap(html, pattern, to, what) {
-  let hit = 0;
-  const out = html.replace(pattern, (...m) => (hit++, typeof to === "function" ? to(...m) : to));
-  if (hit !== 1) throw new Error(`first deck: the ${what} in the layout template changed (${hit} matches); update init's first-deck fill`);
-  return out;
-}
-
-function section(html, id, edit) {
-  return swap(html, new RegExp(`<section\\b[^>]*\\sid="${id}"[\\s\\S]*?</section>`), (s) => edit(s), `#${id} slide`);
-}
-
-// index.html and script.md of the scaffolded hero,features,closer deck, filled
-// with the answers: no template copy is left, and no generated imagery.
-export function fillFirstDeck({ html, title, answers, presenter, voice }) {
-  const copy = firstDeckCopy(presenter);
-  const h = (t) => slots(t, answers, true);
-  const note = (s) => swap(s, /\sdata-note="[^"]*"/, ' data-note="From your init answers."', "data-note");
-  let out = section(html, "hero", (s) => {
-    s = note(s);
-    s = swap(s, /<div class="kicker">[^<]*<\/div>/, `<div class="kicker">${h(copy.hero.kicker)}</div>`, "hero kicker");
-    s = swap(s, /<h1 class="tt"[^>]*>[\s\S]*?<\/h1>/, `<h1 class="tt" data-title-mobile="${h(copy.hero.title)}">${h(copy.hero.title)}</h1>`, "hero title");
-    return swap(s, /<p class="lead">[\s\S]*?<\/p>/, `<p class="lead">${h(copy.hero.lead)}</p>`, "hero lead");
-  });
-  out = section(out, "features", (s) => {
-    s = note(s);
-    s = swap(s, /<div class="kicker">[^<]*<\/div>/, `<div class="kicker">${h(copy.features.kicker)}</div>`, "features kicker");
-    s = swap(s, /<h2 class="tt"[^>]*>[\s\S]*?<\/h2>/, `<h2 class="tt" data-title-mobile="${h(copy.features.title)}">${h(copy.features.title)}</h2>`, "features title");
-    copy.features.cards.forEach((card, i) => {
-      s = swap(s, new RegExp(`(<li class="card" id="features-f${i + 1}">[\\s\\S]*?</svg>)<b>[^<]*</b><p>[^<]*</p>`), (_, icon) => `${icon}<b>${h(card.name)}</b><p>${h(card.line)}</p>`, `features card ${i + 1}`);
-    });
-    return s;
-  });
-  out = section(out, "closer", (s) => {
-    s = note(s);
-    s = swap(s, /<h2 class="tt"[^>]*>[\s\S]*?<\/h2>/, `<h2 class="tt" data-title-mobile="${h(copy.closer.title)}">${h(copy.closer.title)}</h2>`, "closer title");
-    s = swap(s, /<p class="lead">[\s\S]*?<\/p>/, `<p class="lead">${h(copy.closer.lead)}</p>`, "closer lead");
-    s = swap(s, /<a class="cta"[^>]*>[\s\S]*?<\/a>/, `<p class="cta" id="closer-cta">${h(copy.closer.cta)}</p>`, "closer call to action");
-    return swap(s, /<div class="contact muted">[^<]*<\/div>/, `<div class="contact muted">${h(copy.closer.contact)}</div>`, "closer contact");
-  });
-  // A character's live head presents its own deck; a person's voice ships with
-  // captions only (data-presenter="none"), never on a character's face.
-  if (presenter === "dash") {
-    out = swap(out, /(<script type="module" src="https:\/\/decks\.hypersocial\.ai\/player\/v1\/player\.js"[^>]*?)\sdata-presenter="none"/, (_, tag) => `${tag} data-presenter="head" data-avatar="${DASH_AVATAR}"`, "player tag");
-  }
-  const s = (t) => slots(t, answers, false);
-  const script = `---
-voice: ${voice}
-maxTotalSeconds: 90
-transition: drift
----
-
-# ${title} — narration script
-
-Written by \`hyperdecks init\` from your three answers. Make it yours: rewrite
-these lines and the slides in index.html, then
-
-    hyperdecks narrate .
-    hyperdecks release . --to "<name>"
-
-## hero
-${s(copy.hero.script)}
-
-## features
-${s(copy.features.script)}
-
-## closer
-${s(copy.closer.script)}
-`;
-  return { html: out, script };
-}
 
 // ---- git ------------------------------------------------------------------
 

package/src/ops.mjs

@@ -1019,6 +1019,68 @@ export async function setNarratorVoice(opts, ref, voice) {
   return { narrator: n.id, name: n.name, voice: String(voice) };
 }
 
+export async function renameNarrator(opts, ref, name) {
+  if (!String(name ?? "").trim()) throw new Error("usage: narrator rename <name|id> <new name>");
+  const n = await findNarrator(opts, ref);
+  if (n.builtin) throw new Error("D.A.S.H. is built in; its name stays");
+  await (await client(opts)).mutation(api.narrators.rename, { narrator: n.id, name: String(name).trim() });
+  return { narrator: n.id, was: n.name, name: String(name).trim() };
+}
+
+// face: one of your avatars (name or id from `avatar`); D.A.S.H. keeps its own.
+export async function setNarratorFace(opts, ref, avatarRef) {
+  if (!avatarRef) throw new Error("usage: narrator face <name|id> <avatar>");
+  const n = await findNarrator(opts, ref);
+  if (n.builtin) throw new Error("D.A.S.H. is built in and keeps its face");
+  const a = await findAvatar(opts, avatarRef);
+  if (a.source === "dash") throw new Error("D.A.S.H.'s face is D.A.S.H.'s; pick one of your avatars");
+  await (await client(opts)).mutation(api.narrators.setFace, { narrator: n.id, avatarId: a.id });
+  return { narrator: n.id, name: n.name, face: a.name };
+}
+
+// A short sample of a voice, or of a narrator's voice: { url, caption } (what
+// the dashboard's play buttons play). A narrator also brings its face still.
+export async function hearVoice(opts, { voice, narrator } = {}) {
+  const c = await client(opts);
+  if (!voice && !narrator) throw new Error("name a voice or a narrator (list_voices / list_narrators)");
+  let ref = voice ? String(voice) : null;
+  let who = null;
+  if (narrator) {
+    const n = await findNarrator(opts, narrator);
+    const raw = (await c.query(api.narrators.list, {})).narrators.find((x) => x.id === n.id);
+    if (!raw?.voice) throw new Error(`${n.name} has no voice yet; give it one (narrator voice)`);
+    if (!raw.voice.ready) throw new Error(`${n.name}'s voice ${raw.voice.name} is not ready yet`);
+    ref = raw.voice.ref;
+    who = { narrator: n.id, name: n.name, faceUrl: raw.face?.thumbUrl ?? null, faceName: raw.face?.name ?? null };
+  }
+  const out = await c.action(api.narratorsNode.hear, { voice: ref });
+  return { ...out, voice: ref, ...(who ?? {}) };
+}
+
+// A photo drawing started from chat (avatar_from_photo with a photo): still
+// drawing, failed, or drawn, when it hands back the link where the person
+// approves it. Nothing is used before they do.
+export async function startAvatarDrawing(opts, { bytes, contentType }) {
+  if (!/^image\/(jpeg|png)$/.test(contentType ?? "")) throw new Error("the photo must be a .jpg or .png");
+  const c = await client(opts);
+  const storageId = await runtimeUploadBytes(c, bytes, contentType);
+  const { draftId } = await c.mutation(api.avatars.drawSelfie, { storageId });
+  return { status: "drawing", draftId };
+}
+
+export async function avatarDraftStatus(opts, draftId) {
+  if (!draftId) throw new Error("draftId is required");
+  const c = await client(opts);
+  const draft = await c.query(api.avatars.getDraft, { draftId: String(draftId) });
+  if (!draft) throw new Error("the drawing is gone; start again with avatar_from_photo");
+  if (draft.status === "drawing") return { status: "drawing", draftId };
+  if (draft.status === "failed") throw new Error(draft.error || "the drawing failed; try another photo");
+  if (draft.status === "added") return { status: "added", draftId, avatarId: draft.avatarId ?? null };
+  if (draft.status !== "drawn") throw new Error(`the drawing is in an unexpected state (${draft.status}); start again with avatar_from_photo`);
+  const link = await c.mutation(api.avatars.createLink, { kind: "review", draftId });
+  return { status: "waiting", reviewUrl: link.url, token: link.token, draftId, expiresAt: link.expiresAt };
+}
+
 // A deck's own narrator: a narrator, `none` (captions only) or `default`.
 export async function setDeckNarrator(opts, slug, ref) {
   if (!slug || !ref) throw new Error("usage: deck narrator <slug> <narrator|none|default>");

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.4.0";
+export const VERSION = "0.5.0";
 const UPLOAD_TIMEOUT_MS = 125_000;
 
 export const PROD = {
@@ -40,6 +40,11 @@ export const api = {
     setVoice: makeFunctionReference("narrators:setVoice"),
     setDeckNarrator: makeFunctionReference("narrators:setDeckNarrator"),
     newLink: makeFunctionReference("narrators:newLink"),
+    rename: makeFunctionReference("narrators:rename"),
+    setFace: makeFunctionReference("narrators:setFace"),
+  },
+  narratorsNode: {
+    hear: makeFunctionReference("narratorsNode:hear"),
   },
   avatarsNode: {
     options: makeFunctionReference("avatarsNode:options"),
@@ -49,6 +54,7 @@ export const api = {
   assets: {
     generateUploadUrl: makeFunctionReference("assets:generateUploadUrl"),
     saveAsset: makeFunctionReference("assets:saveAsset"),
+    list: makeFunctionReference("assets:list"),
   },
   assetsNode: {
     importAssetFromUrl: makeFunctionReference("assetsNode:importAssetFromUrl"),