@hypersocial/decks-cli 0.9.11 → 0.9.12

package/README.md

@@ -259,6 +259,8 @@ Generate locally, select an existing same-deck recipient share, then explicitly
 
 Capture defaults to the initial slide, 4 seconds, 600px width and 10 fps, with a play/watch badge on GIF, PNG and silent MP4. `--duration` accepts 1–10 seconds, `--width` 240–1200 pixels (odd widths round up for MP4), `--delay` 0–10000 milliseconds (default 1000), and `--label "Watch · 2:41"` supplies an explicit label; no whole-deck narration duration is inferred. Aspect comes from `--aspect-ratio W:H`, `<meta name="preview-aspect-ratio" content="16:9">`, or the first slide/canvas bounds; otherwise 16:9. Output height rounds to an even pixel. Fonts get up to 5 seconds to settle. Inspect readiness warnings/poster for slow modules or media and increase the bounded delay if needed.
 
+To show the slide that sells the deck instead of its opening, name it and a moment of its narration: `hyperdecks preview create my-deck --scene chars --start 3.2 --share EXISTING_TOKEN --out ./preview-chars --upload --json`. `--scene` is the slide's id (its `<section class="slide" id>`; an unknown id fails and lists the deck's ids); `--start` is seconds into that slide's narration (default 0; it must fall inside the slide's clip plus its hold). The GIF then starts on exactly that moment: the guest speaking then, with its mouth and caption bubble, and every cue fired by then. It records frame by frame on the player's page clock (as `export --video` does), silently, after the slide's character heads finish loading; `--delay` still adds settle time first. Private character heads use the same in-memory, deck-scoped view grant; nothing is written to disk. `manifest.json` gets a `moment` saying which slide, which guest and which caption the first frame shows. Needs a deck on player/v1.
+
 `--json` prints one line on stdout, identical to `<out>/manifest.json`:
 
 ```json

package/package.json

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

package/skills/hyperdecks/SKILL.md

@@ -150,6 +150,8 @@ Hyperdecks server; use the CLI where you have a shell and the tool otherwise.
 | Forwarding, one link | `hyperdecks share forward on\|off\|default <token>` | `set_share_forwarding` |
 | Forwarding, whole deck | `hyperdecks deck forward on\|off <slug>` | `set_deck_forwarding` |
 | Slides or scroll, viewer toggle, pace, AI-readable version | `hyperdecks deck view <slug> [slides\|scroll\|default] [--toggle on\|off] [--pace auto\|slide\|step\|default] [--ai-readable on\|off]` | `set_deck_view` |
+| Give a deck to another account (only when asked; confirm the email) | `hyperdecks deck transfer <slug> --to <email>` (`deck transfers cancel <slug>` takes it back) | `transfer_deck` (`cancel: true`) |
+| Transfers waiting on you, and accepting one (ask who narrates and, for each guest that needsPick, a voice and avatar of theirs) | `hyperdecks deck transfers`, then `deck transfers accept <id> --narrator <name\|dash\|none\|default> [--guest <n>=<voice>/<avatar>]` (or `decline <id>`) | `list_transfers`, then `accept_transfer` (`decline: true`) |
 | Present or check your own deck (owner link) | `hyperdecks deck link <slug>` (`deck open` opens it) | `ownerUrl` from `list_decks` or `check_deck` |
 | Who watched | `hyperdecks deck stats <slug>` | `deck_stats` |
 | All activity | `hyperdecks activity --deck <slug>` | `activity_overview` |
@@ -1012,6 +1014,8 @@ Generate locally, select an existing same-deck recipient share, then explicitly
 
 Capture defaults to the initial slide, 4 seconds, 600px width and 10 fps, with a play/watch badge on GIF, PNG and silent MP4. `--duration` accepts 1–10 seconds, `--width` 240–1200 pixels (odd widths round up for MP4), `--delay` 0–10000 milliseconds (default 1000), and `--label "Watch · 2:41"` supplies an explicit label; no whole-deck narration duration is inferred. Aspect comes from `--aspect-ratio W:H`, `<meta name="preview-aspect-ratio" content="16:9">`, or the first slide/canvas bounds; otherwise 16:9. Output height rounds to an even pixel. Fonts get up to 5 seconds to settle. Inspect readiness warnings/poster for slow modules or media and increase the bounded delay if needed.
 
+To show the slide that sells the deck instead of its opening, name it and a moment of its narration: `hyperdecks preview create my-deck --scene chars --start 3.2 --share EXISTING_TOKEN --out ./preview-chars --upload --json`. `--scene` is the slide's id (its `<section class="slide" id>`; an unknown id fails and lists the deck's ids); `--start` is seconds into that slide's narration (default 0; it must fall inside the slide's clip plus its hold). The GIF then starts on exactly that moment: the guest speaking then, with its mouth and caption bubble, and every cue fired by then. It records frame by frame on the player's page clock (as `export --video` does), silently, after the slide's character heads finish loading; `--delay` still adds settle time first. Private character heads use the same in-memory, deck-scoped view grant; nothing is written to disk. `manifest.json` gets a `moment` saying which slide, which guest and which caption the first frame shows. Needs a deck on player/v1.
+
 `--json` prints one line on stdout, identical to `<out>/manifest.json`:
 
 ```json

package/skills/hyperdecks/chat.md

@@ -128,6 +128,19 @@ makes the hello deck; continue from step 5 below.
    worker it answers with the `hyperdecks export <slug> --video` command
    instead; give that to the user to run.
 
+## Giving a deck to another account
+
+Like moving a GitHub repo. Only when the person asks: confirm the
+recipient's email, then `transfer_deck { slug, to }`. They get an email and
+have 7 days; nothing moves until they accept, and `transfer_deck { slug,
+cancel: true }` takes it back. On the other side, `list_transfers` shows what
+waits. Before `accept_transfer`, ask who narrates it for them when
+`needsNarrator` (`list_narrators`: theirs, dash, none or default), and a
+voice and avatar of theirs for each guest with `needsPick`; the sender's
+voice and face never move. Accepting moves the deck with its share links
+(links already sent keep working), recipients and stats, and starts narrating
+their picks; `release_deck` puts them on the links.
+
 ## Rules that matter
 
 - Every slide is `<section class="slide" id="…" data-note="<source of its facts>">`,

package/src/avatar-packs.mjs

@@ -0,0 +1,89 @@
+// Pack management never changes avatar IDs or the user's default presenter.
+// Publication is a distinct command; there is no public flag on create/import.
+import { makeFunctionReference } from "convex/server";
+import { client } from "./runtime.mjs";
+
+const ref = (name) => makeFunctionReference(`avatarPacks:${name}`);
+const PACK_USAGE = "usage: avatar pack list | create <name> [--private-only] [--description text] | get <pack-id> | add <pack-id> <avatar-id> | grant <pack-id> --account <id>|--email <email>|--team <id> | grants <pack-id> | revoke <grant-id> | publish <pack-id> | unpublish <pack-id> | invitations | claim | catalog";
+const TEAM_USAGE = "usage: avatar team list | create <name> | members <team-id> | add <team-id> --account <id>|--email <email> | remove <membership-id>";
+const text = (value, label) => {
+  if (typeof value !== "string" || !value.trim() || value.startsWith("--")) throw new Error(`${label} requires a value`);
+  return value.trim();
+};
+function exactly(pos, count, usage) {
+  if (pos.length !== count || pos.some(value => !value)) throw new Error(usage);
+  return pos;
+}
+function recipient(opts, allowTeam) {
+  const names = allowTeam ? ["account", "email", "team"] : ["account", "email"];
+  const selected = names.filter(name => Object.hasOwn(opts, name));
+  if (selected.length !== 1 || (!allowTeam && Object.hasOwn(opts, "team"))) throw new Error(`choose exactly one of ${names.map(name => `--${name}`).join(", ")}`);
+  const key = selected[0], value = text(opts[key], `--${key}`);
+  return { [{ account: "accountId", email: "email", team: "teamId" }[key]]: value };
+}
+function output(result, opts, log) {
+  if (opts.json) log(JSON.stringify(result, null, 2));
+  else if (Array.isArray(result)) {
+    if (!result.length) log("(none)");
+    for (const item of result) log(`${item.id ?? item._id}\t${item.name ?? item.granteeId ?? item.memberId ?? item.email ?? item.teamId ?? ""}${item.visibility ? `\t${item.visibility}` : ""}${item.access ? ` (${item.access})` : ""}${item.privateOnly ? " · permanently private-only" : ""}${item.status ? `\t${item.status}` : ""}`);
+  } else log(JSON.stringify(result, null, 2));
+  return result;
+}
+
+export async function avatarPacksCommand(pos = [], opts = {}, { log = console.log } = {}) {
+  const [action = "list", ...args] = pos;
+  let method = "query", apiName, payload;
+  switch (action) {
+    case "list": exactly(args, 0, PACK_USAGE); apiName = "list"; payload = {}; break;
+    case "create":
+      if (!args.length) throw new Error(PACK_USAGE);
+      if (Object.hasOwn(opts, "public") || Object.hasOwn(opts, "publish")) throw new Error("packs are created private; use the separate publish command for an eligible pack");
+      apiName = "create"; method = "mutation";
+      payload = { name: text(args.join(" "), "pack name"), privateOnly: opts["private-only"] === true };
+      if (Object.hasOwn(opts, "description")) payload.description = text(opts.description, "--description");
+      break;
+    case "get": case "grants":
+      exactly(args, 1, PACK_USAGE); apiName = action; payload = { packId: args[0] }; break;
+    case "add":
+      exactly(args, 2, PACK_USAGE); apiName = "addAvatar"; method = "mutation";
+      payload = { packId: args[0], avatarId: args[1] }; break;
+    case "grant":
+      exactly(args, 1, PACK_USAGE); apiName = "grant"; method = "mutation";
+      payload = { packId: args[0], ...recipient(opts, true) }; break;
+    case "revoke":
+      exactly(args, 1, PACK_USAGE); apiName = "revoke"; method = "mutation"; payload = { grantId: args[0] }; break;
+    case "publish": case "unpublish":
+      exactly(args, 1, PACK_USAGE); apiName = action; method = "mutation"; payload = { packId: args[0] }; break;
+    case "invitations": case "claim":
+      exactly(args, 0, PACK_USAGE); apiName = action === "claim" ? "claimInvitations" : "invitations";
+      method = action === "claim" ? "mutation" : "query"; payload = {}; break;
+    case "catalog":
+      exactly(args, 0, PACK_USAGE); apiName = "publicCatalog";
+      payload = { paginationOpts: { numItems: 32, cursor: Object.hasOwn(opts, "cursor") ? text(opts.cursor, "--cursor") : null } }; break;
+    default: throw new Error(PACK_USAGE);
+  }
+  const result = await (await client(opts))[method](ref(apiName), payload);
+  if (action === "get" && !result) throw new Error("pack not found or unavailable to your account");
+  if (!opts.json && action === "create") log(result.privateOnly ? "Created privately. The private-only lock is permanent; this pack cannot be published." : "Created privately. Only an explicit publish command makes this pack public.");
+  return output(result, opts, log);
+}
+
+export async function avatarTeamsCommand(pos = [], opts = {}, { log = console.log } = {}) {
+  const [action = "list", ...args] = pos;
+  let method = "query", apiName, payload;
+  switch (action) {
+    case "list": exactly(args, 0, TEAM_USAGE); apiName = "teams"; payload = {}; break;
+    case "create":
+      if (!args.length) throw new Error(TEAM_USAGE);
+      apiName = "createTeam"; method = "mutation"; payload = { name: text(args.join(" "), "team name") }; break;
+    case "members":
+      exactly(args, 1, TEAM_USAGE); apiName = "teamMembers"; payload = { teamId: args[0] }; break;
+    case "add":
+      exactly(args, 1, TEAM_USAGE); apiName = "addTeamMember"; method = "mutation";
+      payload = { teamId: args[0], ...recipient(opts, false) }; break;
+    case "remove":
+      exactly(args, 1, TEAM_USAGE); apiName = "removeTeamMember"; method = "mutation"; payload = { membershipId: args[0] }; break;
+    default: throw new Error(TEAM_USAGE);
+  }
+  return output(await (await client(opts))[method](ref(apiName), payload), opts, log);
+}

package/src/avatar-view.mjs

@@ -0,0 +1,34 @@
+// Ephemeral HTML transform for play/capture/export. Never write its output to
+// source push, release source, disk caches, or logs: it contains a view grant.
+import { makeFunctionReference } from "convex/server";
+const ISSUE_OWNER_VIEW = makeFunctionReference("avatarAccess:issueOwnerView");
+const VIEW_META = /<meta\b[^>]*\bname\s*=\s*(?:"hd-avatar-view"|'hd-avatar-view'|hd-avatar-view(?=\s|\/?>))[^>]*>/gi;
+const PRIVATE_REFS = /\/avatar\/private\/|\bdata-hd-avatar\b/i;
+
+export async function withAvatarView(client, slug, html, scope = "draft") {
+  if (typeof html !== "string") throw new Error("avatar preview requires HTML text");
+  if (scope !== "draft" && scope !== "released") throw new Error("avatar preview scope must be draft or released");
+  const hadView = /<meta\b[^>]*\bname\s*=\s*(?:"hd-avatar-view"|'hd-avatar-view'|hd-avatar-view(?=\s|\/?>))/i.test(html);
+  const needsView = hadView || PRIVATE_REFS.test(html);
+  // Always request a session: guest URLs may live only in the narration
+  // manifest. Offline ordinary playback remains usable without a grant;
+  // protected endpoints still reject private models without authorization.
+  const clean = html.replace(VIEW_META, "");
+  if (!needsView && !/\bdata-(?:manifest|hd-speaker)\b/i.test(html)) return clean;
+  let grant;
+  try {
+    if (typeof slug !== "string" || !slug.trim()) throw new Error("a deck slug is required");
+    grant = await client.mutation(ISSUE_OWNER_VIEW, { slug, scope });
+  } catch (error) {
+    if (needsView) throw new Error("Cannot authorize private avatars for this preview. Sign in as the deck owner, verify pack access, and push the current deck source before retrying.", { cause: error });
+    return clean;
+  }
+  if (!grant) {
+    if (needsView) throw new Error("No current private-avatar view grant. Push the deck source and script so their avatar IDs are registered, then retry.");
+    return clean;
+  }
+  if (!/^[a-f0-9]{64}$/.test(grant.token) || !Number.isFinite(grant.expiresAt) || grant.expiresAt <= Date.now()) throw new Error("The server returned an invalid or expired avatar view grant");
+  const meta = `<meta name="hd-avatar-view" content="${grant.token}">`;
+  // Put the grant before any player script; the HTML string stays in memory.
+  return /<head\b[^>]*>/i.test(clean) ? clean.replace(/<head\b[^>]*>/i, match => `${match}\n${meta}`) : `${meta}\n${clean}`;
+}

package/src/commands.mjs

@@ -173,6 +173,65 @@ async function deckForward(pos, opts) {
   console.log(`OK forwarding ${mode} for deck ${slug} (links with their own setting keep it)`);
 }
 
+const TRANSFER_USAGE = "usage: deck transfer <slug> --to <email>";
+async function deckTransfer(pos, opts) {
+  const [slug] = pos;
+  if (!slug || !opts.to) throw new Error(TRANSFER_USAGE);
+  const out = await ops.transferDeck(opts, slug, opts.to);
+  if (opts.json) return void console.log(JSON.stringify(out, null, 2));
+  console.log(`OK ${out.existing ? "already offered" : "offered"} ${slug} to ${out.to}, until ${out.expiresAt.slice(0, 10)}`);
+  console.log("  Nothing moves until they accept (signed in to Hyperdecks with that email). Cancel: deck transfers cancel " + slug);
+}
+
+const TRANSFERS_USAGE = "usage: deck transfers [accept <id> [--narrator <name|dash|none|default>] [--guest <n>=<voice>[/<avatar>]]... [--no-narrate] | decline <id> | cancel <slug>]";
+// "1=Ana/Ana Face,2=stock:liam" → [{ guest: 1, voice: "Ana", avatar: "Ana Face" }, …]
+export function parseGuestPicks(spec) {
+  if (!spec) return [];
+  return String(spec).split(",").map((part) => {
+    const m = /^\s*(\d+)\s*=\s*([^/]+?)\s*(?:\/\s*(.+?)\s*)?$/.exec(part);
+    if (!m) throw new Error(`--guest ${part}: write <n>=<voice> or <n>=<voice>/<avatar>`);
+    return { guest: Number(m[1]), voice: m[2], ...(m[3] ? { avatar: m[3] } : {}) };
+  });
+}
+
+async function deckTransfers(pos, opts) {
+  const [action, arg] = pos;
+  if (action === "accept") {
+    if (!arg) throw new Error(TRANSFERS_USAGE);
+    const out = await ops.acceptTransfer(opts, arg, { narrator: opts.narrator, guests: parseGuestPicks(opts.guest), renarrate: !opts["no-narrate"] });
+    if (opts.json) return void console.log(JSON.stringify(out, null, 2));
+    console.log(`OK ${out.slug} is yours, with its share links and stats; links already sent keep working`);
+    if (out.narration?.jobId) console.log(`  narrating your picks: job ${out.narration.jobId} (narrate status), then release ${out.slug}`);
+    else if (out.narration?.error) console.log(`  ⚠ narration did not start: ${out.narration.error}\n  ${out.narration.note}`);
+    else if (out.narration?.note) console.log(`  ${out.narration.note}`);
+    return;
+  }
+  if (action === "decline") {
+    if (!arg) throw new Error(TRANSFERS_USAGE);
+    const out = await ops.declineTransfer(opts, arg);
+    return void console.log(opts.json ? JSON.stringify(out) : `OK declined ${out.slug}`);
+  }
+  if (action === "cancel") {
+    if (!arg) throw new Error(TRANSFERS_USAGE);
+    const out = await ops.cancelTransfer(opts, arg);
+    return void console.log(opts.json ? JSON.stringify(out) : `OK cancelled the transfer of ${out.slug} to ${out.to}`);
+  }
+  if (action) throw new Error(TRANSFERS_USAGE);
+  const out = await ops.listTransfers(opts);
+  if (opts.json) return void console.log(JSON.stringify(out, null, 2));
+  if (out.emailUnverified) console.log("⚠ your account's email is not verified, so transfers sent to it can't be shown or accepted");
+  if (!out.incoming.length && !out.outgoing.length) return void console.log("No transfers waiting.");
+  for (const t of out.incoming) {
+    console.log(`← ${t.slug} "${t.title}" from ${t.from ?? "someone"} (until ${t.expiresAt.slice(0, 10)})  id ${t.id}`);
+    if (t.needsNarrator) console.log("    narrated in the sender's narrator or voice: pick yours with --narrator <name|dash|none|default>");
+    for (const g of t.guests) {
+      console.log(`    guest ${g.guest} ${g.name} (${g.selector}): voice ${g.voice}${g.avatar ? `, avatar ${g.avatar}` : ""}${g.needsPick ? "  → pick with --guest " + g.guest + "=<voice>/<avatar>" : ""}`);
+    }
+    console.log(`    accept: deck transfers accept ${t.id}${t.needsNarrator ? " --narrator <…>" : ""}${t.guests.filter((g) => g.needsPick).map((g) => ` --guest ${g.guest}=<voice>/<avatar>`).join("")}`);
+  }
+  for (const t of out.outgoing) console.log(`→ ${t.slug} "${t.title}" to ${t.to} (until ${t.expiresAt.slice(0, 10)}); cancel: deck transfers cancel ${t.slug}`);
+}
+
 const VIEW_USAGE = "usage: deck view <slug> [slides|scroll|default] [--toggle on|off] [--pace auto|slide|step|default] [--ai-readable on|off]";
 const VIEWS = { slides: "slides", scroll: "scroll", default: null };
 const PACES = { auto: "auto", slide: "slide", step: "step", default: null };
@@ -363,12 +422,20 @@ commands:
   login [--token <pat>] [--broker <url>] [--dev]
   logout [--dev]
   whoami [--json] [--dev]
-  deck list|stats|open|link|rm|forward|view
+  deck list|stats|open|link|rm|forward|view|transfer|transfers
   deck link <slug> [--json]
                    the owner link: present or check your own deck (only you, signed in; untracked;
                    Present or H hides your owner tools). Use it instead of a QA link. deck open opens it.
   deck forward on|off <slug>
                    whether viewers can forward the deck's links (on by default; a link's own setting wins)
+  deck transfer <slug> --to <email>
+                   give the deck to another Hyperdecks account (like a GitHub repo transfer). Nothing moves until
+                   they accept, within 7 days; then its share links, recipients and stats are theirs, not yours.
+  deck transfers [accept <id> [--narrator <name|dash|none|default>] [--guest <n>=<voice>[/<avatar>]]... [--no-narrate]
+                 | decline <id> | cancel <slug>]
+                   transfers waiting on you and the ones you sent. Accepting picks your narrator and a voice and
+                   avatar for each guest in the sender's own voice or face, then narrates those lines as you;
+                   the deck plays as released until you release it.
   deck view <slug> [slides|scroll|default] [--toggle on|off] [--pace auto|slide|step|default] [--ai-readable on|off]
                    how the deck opens in the player (default: as its HTML says, data-view or slides) and
                    whether viewers get the slides/scroll toggle (on by default). Every link, next load; no re-release.
@@ -471,6 +538,9 @@ commands:
 
   preview create <slug> --out <directory> [--share <token>] [--upload] [--json]
   preview create --file <index.html> --out <directory> [--duration 4] [--width 600] [--delay 1000] [--label "Watch"] [--aspect-ratio 16:9]
+  preview create <slug> --out <directory> --scene <slide-id> [--start <seconds>] [--share <token> --upload]
+                   the email GIF of one slide, from <seconds> into its narration (default 0): the guest
+                   speaking then, its caption bubble and every cue fired by then; needs a player/v1 deck
   preview setup    install isolated Chromium (Linux: see README for system dependencies)
 
   narrate <deck-dir> [--slide <id>] [--voice <name|id>] [--slug <slug>] [--dry-run] [--json]
@@ -483,6 +553,9 @@ commands:
   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 pack [list|create|get|add|grant|grants|revoke|publish|unpublish|invitations|claim|catalog]
+                           owner-managed packs; create <name> --private-only permanently prevents publication
+  avatar team [list|create|members|add|remove]   owner-managed account groups for pack grants
   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]
@@ -805,7 +878,8 @@ function commandTable(pos, rest, opts) {
     "preview create": async () => {
       const { createPreview } = await import("./preview.mjs");
       const result = await createPreview(rest, opts);
-      console.log(opts.json ? JSON.stringify(result) : `Preview saved: ${result.manifestPath}\n${result.email.sendable ? result.email.path : "Insert the GIF or PNG manually; upload with an existing share for linked email HTML."}`);
+      const shows = result.moment ? `Shows ${result.moment.scene} at ${result.moment.start}s${result.moment.guest ? `: ${result.moment.guest.caption}` : ""}\n` : "";
+      console.log(opts.json ? JSON.stringify(result) : `Preview saved: ${result.manifestPath}\n${shows}${result.email.sendable ? result.email.path : "Insert the GIF or PNG manually; upload with an existing share for linked email HTML."}`);
     },
     init: async () => {
       const { init } = await import("./init.mjs");
@@ -913,6 +987,8 @@ function commandTable(pos, rest, opts) {
       const out = await avatarList(opts);
       if (opts.json) console.log(JSON.stringify(out, null, 2));
     },
+    "avatar pack": async () => (await import("./avatar-packs.mjs")).avatarPacksCommand(rest, opts),
+    "avatar team": async () => (await import("./avatar-packs.mjs")).avatarTeamsCommand(rest, opts),
     "avatar new": async () => {
       const { avatarNew } = await import("./avatar.mjs");
       const { askLine } = await import("./init.mjs");
@@ -1019,6 +1095,8 @@ function commandTable(pos, rest, opts) {
     "deck rm": () => deckRemove(rest, opts),
     "deck forward": () => deckForward(rest, opts),
     "deck view": () => deckView(rest, opts),
+    "deck transfer": () => deckTransfer(rest, opts),
+    "deck transfers": () => deckTransfers(rest, opts),
     "share new": () => shareNew(rest, opts),
     "share list": () => shareList(rest, opts),
     "share on": () => shareToggle(rest, opts, true),

package/src/deckPlayer.mjs

@@ -5,7 +5,8 @@
 // runs its own runtime (a legacy copy-and-swap deck.js, a plain HTML export)
 // gets none of them.
 
-export const loadsPlayer = (html) => /\/player\/v1\/player\.js\b/.test(String(html ?? ""));
+// A copy of a page our routes served names a pinned build (/player/v1/b/<hash>/player.js).
+export const loadsPlayer = (html) => /\/player\/v1\/(?:b\/[0-9a-f]+\/)?player\.js\b/.test(String(html ?? ""));
 
 const SCRIPT_SRC = /<script\b[^>]*\ssrc\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))[^>]*>/gi;
 const MAX_SCRIPT_NAME = 120;

package/src/export-video.mjs

@@ -424,7 +424,8 @@ export async function recordVideo(config, { log = () => {}, chromium: injected,
     // A development checkout plays its own player/v1 (HYPERDECKS_PLAYER_DIR), not the released one.
     if (config.playerDir) {
       await context.route(/\/player\/v1\/[^?#]+/, async (route) => {
-        const name = new URL(route.request().url()).pathname.replace(/^.*\/player\/v1\//, '');
+        // A pinned build (/player/v1/b/<hash>/, lib/deckPlayer.ts) is the checkout's files too.
+        const name = new URL(route.request().url()).pathname.replace(/^.*\/player\/v1\/(b\/[^/]+\/)?/, '');
         if (name.split('/').some((s) => s === '..' || s.startsWith('.'))) return route.abort();
         const type = { '.js': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.png': 'image/png' }[extname(name)] ?? 'application/octet-stream';
         try { await route.fulfill({ body: await readFile(join(config.playerDir, name)), contentType: type }); }
@@ -768,7 +769,11 @@ export async function exportVideo(arg, opts = {}, { log = (l) => process.stderr.
   } else {
     const deck = await ops.releasedDeck(opts, arg);
     const { serveSource } = await import('./preview-capture.mjs');
-    const server = await serveSource({ html: deck.html });
+    // The worker imports recordVideo with already-scoped HTML and no CLI auth dependencies.
+    const { withAvatarView } = await import("./avatar-view.mjs");
+    const { client: avatarClient } = await import("./runtime.mjs");
+    const html = await withAvatarView({ mutation: async (ref, args) => (await avatarClient(opts)).mutation(ref, args) }, arg, deck.html, "released");
+    const server = await serveSource({ html });
     source = { slug: arg, title: deck.title, url: server.url, close: server.close, presenter: null };
   }
   try {

package/src/ops.mjs

@@ -1359,6 +1359,112 @@ export async function setDeckNarrator(opts, slug, ref) {
   return (await client(opts)).mutation(api.narrators.setDeckNarrator, { slug, narrator: value });
 }
 
+// ---- deck transfers (convex/deckTransfers.ts) ----------------------------------
+
+// The tool descriptions, shared by the stdio and remote MCP servers.
+export const TRANSFER_DECK_DESCRIPTION =
+  "Give a deck to another Hyperdecks account, like transferring a GitHub repo: they get an email and accept within 7 days " +
+  "(list_transfers, accept_transfer); until then nothing changes. Accepting moves the deck with its share links (links already sent " +
+  "keep working), recipients and stats; you keep nothing. Only when the person asked for it, and confirm the email first. cancel: true takes the offer back.";
+export const LIST_TRANSFERS_DESCRIPTION =
+  "Deck transfers waiting on the user (incoming: id, deck, sender, whether they must pick a narrator, and guests, numbered, with needsPick " +
+  "when a guest speaks in the sender's own voice or face) and the ones they sent (outgoing).";
+export const ACCEPT_TRANSFER_DESCRIPTION =
+  "Accept (or decline: true) a deck transfer from list_transfers. Ask the person first: who narrates it for them (list_narrators: one of " +
+  "theirs, dash, none or default; required when needsNarrator), and a voice (list_voices) and avatar (list_avatars) for each guest with " +
+  "needsPick. The sender's voice and face never move. Then their picks are narrated as them (narration.jobId; poll check_narration_job); " +
+  "the deck keeps playing as released until they release_deck.";
+
+// Offer a deck to the Hyperdecks account signed in with `to`. Nothing moves
+// until they accept; the offer lasts 7 days.
+export async function transferDeck(opts, slug, to) {
+  if (!slug || !to) throw new Error("usage: deck transfer <slug> --to <email>");
+  const out = await (await client(opts)).mutation(api.deckTransfers.create, { slug, to: String(to) });
+  return { ...out, expiresAt: new Date(out.expiresAt).toISOString() };
+}
+
+export async function cancelTransfer(opts, slug) {
+  if (!slug) throw new Error("usage: deck transfers cancel <slug>");
+  return (await client(opts)).mutation(api.deckTransfers.cancel, { slug });
+}
+
+// Transfers waiting on you (incoming, numbered guests to pick for) and the
+// ones you sent (outgoing). A guest needs a pick when it speaks in the
+// sender's own voice or face (needsPick).
+export async function listTransfers(opts = {}) {
+  const out = await (await client(opts)).query(api.deckTransfers.list, {});
+  const when = (ms) => new Date(ms).toISOString();
+  return {
+    incoming: out.incoming.map((t) => ({
+      id: t.id,
+      slug: t.slug,
+      title: t.title,
+      from: t.from,
+      expiresAt: when(t.expiresAt),
+      needsNarrator: t.needsNarrator,
+      guests: t.guests.map((g, i) => ({
+        guest: i + 1,
+        name: g.name,
+        selector: g.selector,
+        voice: g.voice ?? "(the sender's own voice)",
+        avatar: g.personalAvatar ? "(the sender's own avatar)" : g.avatar,
+        needsPick: g.personalVoice || g.personalAvatar,
+      })),
+    })),
+    emailUnverified: !!out.emailUnverified,
+    outgoing: out.outgoing.map((t) => ({ id: t.id, slug: t.slug, title: t.title, to: t.to, expiresAt: when(t.expiresAt) })),
+  };
+}
+
+// Accept an incoming transfer. narrator: one of yours (name or id), dash, none
+// or default; required when the deck narrates in the sender's narrator or
+// voice. guests: [{ guest, voice, avatar? }], guest numbers from
+// listTransfers, one for each guest that needsPick. Then, unless
+// renarrate is false, narrates the rewritten draft as you (only the
+// re-picked lines render; the rest is cached). The live deck plays as
+// released until you release it.
+export async function acceptTransfer(opts, id, picks = {}) {
+  const { narrator, guests, renarrate = true } = picks;
+  if (!id) throw new Error("usage: deck transfers accept <id> [--narrator <name|dash|none|default>] [--guest <n>=<voice>[/<avatar>]]");
+  const c = await client(opts);
+  // Guest numbers are positions in list's guests; only then is the list needed.
+  let listed = null;
+  if (guests?.length) {
+    const all = await c.query(api.deckTransfers.list, {});
+    listed = all.incoming.find((t) => t.id === id);
+    if (!listed) throw new Error(`no transfer ${id} is waiting for you${all.emailUnverified ? " (your account's email is not verified)" : ""} (see deck transfers)`);
+  }
+  const speakers = (guests ?? []).map((p) => {
+    const g = listed.guests[Number(p.guest) - 1];
+    if (!g) throw new Error(`no guest ${p.guest} in ${listed.slug} (guests: 1..${listed.guests.length})`);
+    if (!p.voice) throw new Error(`guest ${p.guest}: name a voice`);
+    return { key: g.key, voice: String(p.voice), ...(p.avatar ? { avatar: String(p.avatar) } : {}) };
+  });
+  const narratorArg = narrator === undefined || narrator === null || narrator === "" ? undefined
+    : ["none", "default", "dash"].includes(String(narrator).toLowerCase()) ? String(narrator).toLowerCase()
+    : (await findNarrator(opts, narrator)).id;
+  const out = await c.mutation(api.deckTransfers.accept, { id, ...(narratorArg !== undefined ? { narrator: narratorArg } : {}), speakers });
+  const result = { ...out, narration: null };
+  if (out.renarrate && renarrate) {
+    try {
+      const job = await narrateDeck(opts, { slug: out.slug, fromSource: true });
+      result.narration = { jobId: job.jobId, note: "narrating the re-picked lines; then release the deck to put them on its links" };
+    } catch (e) {
+      result.narration = { error: errorText(e), note: "the deck is yours; narrate it again when this is fixed, then release" };
+    }
+  } else if (out.renarrate) {
+    result.narration = { note: "narrate the deck, then release it, to put your voice and face on its links" };
+  } else if (!out.hosted) {
+    result.narration = { note: "this deck has no hosted script, so nothing was re-narrated" };
+  }
+  return result;
+}
+
+export async function declineTransfer(opts, id) {
+  if (!id) throw new Error("usage: deck transfers decline <id>");
+  return (await client(opts)).mutation(api.deckTransfers.decline, { id });
+}
+
 // The account's brand (convex/brand.ts): what new_deck / deck new start from.
 export async function getBrand(opts = {}) {
   return (await client(opts)).query(api.brand.get, {});

package/src/play.mjs

@@ -1,3 +1,4 @@
+import { withAvatarView } from "./avatar-view.mjs";
 // hyperdecks play <slug|deck-dir> [--voice v] [--slug s] [--port n] [--no-open] [--json]
 //
 // Plays the working folder as it is, committed or not, the way it will play once
@@ -14,7 +15,7 @@ import { resolveDeckDir } from "./check.mjs";
 import * as ops from "./ops.mjs";
 import { playsCaptionsOnly, presenterLine, withNarrator } from "./presenter.mjs";
 import { serveSource } from "./preview-capture.mjs";
-import { openBrowser } from "./runtime.mjs";
+import { openBrowser, client } from "./runtime.mjs";
 
 const USAGE = "usage: play <slug|deck-dir> [--voice <name|id>] [--slug <slug>] [--port <n>] [--no-open]";
 
@@ -88,7 +89,8 @@ export async function startPlay(pos, opts = {}, { log = (line) => console.log(li
   const html = readFileSync(file, "utf8");
 
   const { presenter, who } = await lookUpPresenter(opts, { slug, path, html, log });
-  const page = withNarrator(html, presenter, who);
+  let page = withNarrator(html, presenter, who);
+  page = await withAvatarView({ mutation: async (ref, args) => (await client(opts)).mutation(ref, args) }, slug, page, "draft");
   sayWhoPresents({ html, page, presenter, who, log });
   // --voice names the voice it was narrated in, so there is nothing to compare it to.
   if (who && !opts.voice) await warnIfScriptChanged(opts, { slug, deckDir, path, html, who, log });

package/src/preview-capture.mjs

@@ -255,11 +255,36 @@ async function encode(ffmpeg, args) {
   try { await run(ffmpeg, ['-hide_banner', '-loglevel', 'error', '-nostdin', ...args], { timeout: 90000, maxBuffer: 1024 * 1024, env: { PATH: dirname(ffmpeg), ...(process.platform === 'win32' ? { SystemRoot: process.env.SystemRoot } : {}) } }); }
   catch (e) { throw new Error(`FFmpeg encoding failed (${e.killed ? '90s timeout' : 'check portable encoder installation'}); no global FFmpeg is used`); }
 }
+// The numbered frames in `dir` (frame-0000.png…) as the preview's PNG poster
+// (the first frame), looping GIF and silent MP4 in `out`.
+async function encodeOutputs(ffmpeg, { dir, out, width, height, fps, duration }) {
+  const input = ['-framerate', String(fps), '-i', join(dir, 'frame-%04d.png')];
+  const paths = Object.fromEntries(['png','gif','mp4'].map(t => [t, resolve(out, `preview.${t}`)]));
+  await encode(ffmpeg, ['-i', join(dir,'frame-0000.png'), '-vf', `scale=${width}:${height}`, '-frames:v','1', paths.png]);
+  await encode(ffmpeg, [...input, '-filter_complex', `scale=${width}:${height}:flags=lanczos,split[a][b];[a]palettegen[p];[b][p]paletteuse`, '-loop','0', paths.gif]);
+  await encode(ffmpeg, [...input, '-vf',`scale=${width}:${height}`, '-an','-c:v','libx264','-pix_fmt','yuv420p','-movflags','+faststart',paths.mp4]);
+  return Promise.all(['gif','png','mp4'].map(async type => ({ type, path: paths[type], contentType: type === 'mp4' ? 'video/mp4' : `image/${type}`, bytes: (await stat(paths[type])).size, width, height, ...(type === 'png' ? {} : { duration, fps, silent:true, ...(type === 'gif' ? { loop:0 } : {}) }) })));
+}
+// Even output dimensions for `width` at `aspect`, as the encoders need them.
+const outputSize = (width, aspect) => { const w = width % 2 ? width + 1 : width; return { width: w, height: Math.round(w / aspect / 2) * 2 }; };
+
+async function captureMoment(config, chromium, ffmpeg) {
+  const { recordMoment, withTempDir } = await import('./preview-moment.mjs');
+  const fps = 10, frames = Math.round(config.duration * fps);
+  return withTempDir(async dir => {
+    const recorded = await recordMoment({ ...config, frames, fps, playerDir: config.playerDir ?? process.env.HYPERDECKS_PLAYER_DIR ?? null }, { chromium, serveSource, dir });
+    const files = await encodeOutputs(ffmpeg, { dir, out: config.out, ...outputSize(config.width, recorded.aspect), fps, duration: frames / fps });
+    return { files, warnings: recorded.warnings, moment: recorded.moment };
+  });
+}
+
 export async function capturePreview(config) {
   const { chromium } = await import('playwright');
   let ffmpeg;
   try { ffmpeg = (await import('@ffmpeg-installer/ffmpeg')).default.path; await run(ffmpeg, ['-version'], { timeout:10000 }); }
   catch { throw new Error('Portable FFmpeg missing. Reinstall the CLI with optional dependencies and install scripts enabled (`npm install -g hyperdecks --include=optional`); pnpm users must approve @ffmpeg-installer platform build scripts.'); }
+  // --scene / --start: one moment of the narration, on the page clock (preview-moment.mjs).
+  if (config.scene != null || config.start != null) return captureMoment(config, chromium, ffmpeg);
   let browser, server, temp, deadline, timedOut = false, phase = 'launch';
   const warnings = [];
   try {
@@ -309,8 +334,7 @@ export async function capturePreview(config) {
     else if (busy > 1) warnings.push(`The deck kept its main thread busy for ${busy.toFixed(1)}s; script-driven motion may look choppy.`);
     if (!config.aspect && !detected) warnings.push('Using 16:9 aspect ratio; use --aspect-ratio W:H or preview-aspect-ratio metadata for a different deck shape.');
     const aspect = config.aspect ?? (detected >= 0.5 && detected <= 3 ? detected : 16/9);
-    const width = config.width % 2 ? config.width + 1 : config.width;
-    const height = Math.round(width / aspect / 2) * 2;
+    const { width, height } = outputSize(config.width, aspect);
     await page.setViewportSize({ width:1280, height:Math.round(1280/aspect) });
     const fps = 10, frames = Math.round(config.duration * fps), duration = frames/fps;
     // Screencast captures the live WebGL compositor and CSS motion without
@@ -339,14 +363,9 @@ export async function capturePreview(config) {
     await context.close();
     clearTimeout(deadline);
     phase = 'encode';
-    const input = ['-framerate', String(fps), '-i', join(temp, 'frame-%04d.png')];
-    const paths = Object.fromEntries(['png','gif','mp4'].map(t => [t, resolve(config.out, `preview.${t}`)]));
-    await encode(ffmpeg, ['-i', join(temp,'frame-0000.png'), '-vf', `scale=${width}:${height}`, '-frames:v','1', paths.png]);
-    await encode(ffmpeg, [...input, '-filter_complex', `scale=${width}:${height}:flags=lanczos,split[a][b];[a]palettegen[p];[b][p]paletteuse`, '-loop','0', paths.gif]);
-    await encode(ffmpeg, [...input, '-vf',`scale=${width}:${height}`, '-an','-c:v','libx264','-pix_fmt','yuv420p','-movflags','+faststart',paths.mp4]);
+    const files = await encodeOutputs(ffmpeg, { dir: temp, out: config.out, width, height, fps, duration });
     if (blocked) warnings.push(`${blocked} navigation/telemetry/unsafe request(s) blocked; no recipient page was visited.`);
     if (failed) warnings.push(`${failed} page/resource error(s); inspect the poster and increase --delay if necessary.`);
-    const files = await Promise.all(['gif','png','mp4'].map(async type => ({ type, path: paths[type], contentType: type === 'mp4' ? 'video/mp4' : `image/${type}`, bytes: (await stat(paths[type])).size, width, height, ...(type === 'png' ? {} : { duration, fps, silent:true, ...(type === 'gif' ? { loop:0 } : {}) }) })));
     return { files, warnings };
   } catch (e) { throw new Error(`Capture failed during ${phase}: ${timedOut ? '60s capture timeout; the renderer did not respond' : /Timeout/i.test(e.name) ? 'bounded capture timeout; inspect the deck or increase --delay' : e.message}`); }
   finally {

package/src/preview-moment.mjs

@@ -0,0 +1,243 @@
+// `preview create --scene <id> --start <seconds>`: the email GIF of one moment
+// of a narrated deck, not its opening.
+//
+// The ordinary preview (preview-capture.mjs capturePreview) opens the deck as
+// a recipient would and screencasts it in real time; its narration never
+// starts, so it can only show the opening. This one records the way the video
+// export does (export-video.mjs): the player's export mode (?export=1: no
+// chrome, plays without a tap, narration on a silent clock media element) on
+// a page clock the recorder steps (frame-clock.mjs). The deck opens on the
+// chosen slide (window.__hdExportFrom, export-mode.js), the clock is stepped
+// `start` seconds into its narration, so every cue, guest line, caption
+// bubble and mouth shape that would have happened by then has happened, and
+// then each GIF frame is the clock advanced 1/fps and a screenshot taken.
+// Nothing plays aloud; no view is counted (the capture request rules refuse
+// /v/ and telemetry, and export mode sends no engagement events).
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { extname, join } from 'node:path';
+import { installFrameClock } from './frame-clock.mjs';
+import { exportPageUrl, launchRecorder, planTimeline } from './export-video.mjs';
+import { recorderArgs, routeCaptureRequest } from './preview-capture.mjs';
+
+// Page-clock milliseconds per step while seeking to `start`: timers fire in
+// order within a step, so a coarser step only means fewer animation frames
+// drawn on the way. The GIF's own frames are 1/fps apart.
+const SEEK_STEP_MS = 100;
+// Real milliseconds the deck may take to become ready (the head loads in it).
+const READY_MS = 60000;
+// Real milliseconds a slide's heads may take to finish loading once on it.
+const HEADS_MS = 15000;
+
+// Where to start: the slide (`scene`, the first slide when omitted) and the
+// seconds into its narration, checked against the player's own plan
+// ([{ id, duration, hold }], the manifest's clip length plus its hold).
+export function seekTarget(plan, { scene, start = 0 } = {}) {
+  const timeline = planTimeline(plan ?? []);
+  if (!timeline.ids.length) throw new Error('the deck has no slides');
+  const index = scene == null ? 0 : timeline.ids.indexOf(scene);
+  if (index < 0) throw new Error(`Unknown scene "${scene}". This deck's slides: ${timeline.ids.join(', ')}`);
+  const id = timeline.ids[index], seconds = timeline.seconds[index], entry = plan[index];
+  // A clip whose length the plan doesn't know (a data-clip deck's): its start can't be bounded here.
+  const known = !entry.audio || entry.duration > 0;
+  if (known && start > 0 && !(start < seconds)) {
+    throw new Error(seconds > 0
+      ? `--start ${start} is past the end of slide ${id}: it runs ${seconds.toFixed(1)}s (${entry.audio ? 'its narration plus its hold' : 'its hold; it has no narration'}), so pick 0 to ${Math.max(0, seconds - 0.1).toFixed(1)}`
+      : `--start ${start}: slide ${id} has no narration to start into; use --start 0`);
+  }
+  return { index, id, start, seconds, narrated: !!entry.audio };
+}
+
+const within = async (promise, ms, fallback) => {
+  promise.catch(() => {});
+  let timer;
+  try { return await Promise.race([promise, new Promise((ok) => { timer = setTimeout(() => ok(fallback), ms); })]); }
+  finally { clearTimeout(timer); }
+};
+
+// What the first frame shows, read from the page: the slide the player is on,
+// the guest speaking and its caption bubble's words (null when none), and the
+// state of each character head on the slide (head-slots.js data-hd-head-state).
+function readMoment() {
+  const log = window.__hdExport;
+  const slide = log?.slides?.at(-1)?.id ?? null;
+  const bubble = document.querySelector('.hd-guest-bubble:not([hidden])');
+  const heads = [...(document.getElementById(slide)?.querySelectorAll('[data-hd-head-state]') ?? [])].map((e) => e.dataset.hdHeadState);
+  return {
+    slide,
+    // Every slide the player showed, in order: the scene alone when it opened there.
+    visited: (log?.slides ?? []).map((s) => s.id),
+    guest: bubble ? { speaker: bubble.dataset.speaker ?? null, caption: bubble.textContent.trim() } : null,
+    caption: document.querySelector('.hd-caption')?.textContent.trim() || null,
+    heads,
+  };
+}
+
+// Records `frames` PNGs (frame-0000.png…) into `dir` and returns
+// { aspect, moment, warnings }. config: { html | file, scene, start, frames,
+// fps, delay, label, aspect, firstPartyOrigins, playerDir }.
+export async function recordMoment(config, { chromium, serveSource, dir }) {
+  const warnings = [];
+  let browser, server, phase = 'launch';
+  try {
+    browser = await launchRecorder(chromium, {
+      headless: true, timeout: 30000, chromiumSandbox: config.sandbox ?? process.platform === 'linux',
+      args: ['--autoplay-policy=no-user-gesture-required', '--mute-audio', ...recorderArgs()],
+      env: { ...(process.platform === 'win32' ? { SystemRoot: process.env.SystemRoot } : {}), PATH: process.env.PATH, TMPDIR: dir, HOME: dir },
+    });
+    server = await serveSource(config);
+    const pageUrl = exportPageUrl(server.url);
+    const context = await browser.newContext({ viewport: { width: 1280, height: 720 }, deviceScaleFactor: 1, serviceWorkers: 'block', acceptDownloads: false });
+    let blocked = 0;
+    await context.route('**/*', async (route) => {
+      if (!await routeCaptureRequest(route, pageUrl, config.firstPartyOrigins)) blocked++;
+    });
+    // A development checkout (or a test) plays its own player/v1, as video export does.
+    const missingPlayer = [];
+    if (config.playerDir) {
+      await context.route(/\/player\/v1\/[^?#]+/, async (route) => {
+        const name = new URL(route.request().url()).pathname.replace(/^.*\/player\/v1\/(b\/[^/]+\/)?/, '');
+        if (name.split('/').some((s) => s === '..' || s.startsWith('.'))) return route.abort();
+        const type = { '.js': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.png': 'image/png' }[extname(name)] ?? 'application/octet-stream';
+        try { await route.fulfill({ body: await readFile(join(config.playerDir, name)), contentType: type }); }
+        catch { missingPlayer.push(name); await route.abort(); }
+      });
+    }
+    await context.routeWebSocket('**/*', (ws) => ws.close());
+    await context.addInitScript({ content: `(${installFrameClock.toString()})(window);` });
+    // The player opens on __hdExportFrom, read once its slides are in the page:
+    // the scene's index among them, as the player lists them (section.slide in order).
+    // An unknown scene opens the first slide; seekTarget then refuses it by name.
+    await context.addInitScript((scene) => {
+      navigator.sendBeacon = () => false;
+      window.open = () => null;
+      window.__hdExportWait = new Promise((go) => { window.__hdExportGo = go; });
+      if (scene == null) return;
+      Object.defineProperty(window, '__hdExportFrom', { configurable: true, get: () => Math.max(0, [...document.querySelectorAll('section.slide')].map((s) => s.id).indexOf(scene)) });
+    }, config.scene ?? null);
+    const page = await context.newPage();
+    page.setDefaultTimeout(30000);
+    const pageErrors = [];
+    page.on('pageerror', (e) => pageErrors.push(String(e?.message ?? e)));
+    // Every call into the page is bounded: a deck that holds its main thread fails, it doesn't hang the CLI.
+    const ask = async (fn, arg, what) => {
+      const none = Symbol('timeout');
+      const answer = await within(page.evaluate(fn, arg), 30000, none);
+      if (answer === none) throw new Error(`the page stopped answering ${what} (over 30s)`);
+      return answer;
+    };
+    const step = (ms, what) => ask(async (ms) => { window.__hdFrameClock.step(ms); await window.__hdFrameClock.settle(); return window.__hdExport; }, ms, what);
+    phase = 'page load';
+    await page.goto(pageUrl, { waitUntil: 'domcontentloaded', timeout: 30000 });
+    phase = 'player ready';
+    await page.waitForSelector('body[data-hd-ready="true"]', { timeout: READY_MS }).catch(() => {
+      const missing = missingPlayer.length ? ` (missing from the local player: ${missingPlayer.slice(0, 3).join(', ')})` : '';
+      throw new Error(`the deck was not ready after ${READY_MS / 1000}s${missing}; --scene and --start need a deck on player/v1 (https://hyperdecks.ai/player/v1/player.js)`);
+    });
+    const state = await ask(() => (window.__hdExport ? JSON.parse(JSON.stringify(window.__hdExport)) : null), undefined, 'for its export log');
+    if (!state) throw new Error('--scene and --start need a deck on player/v1 (https://hyperdecks.ai/player/v1/player.js); this deck has its own runtime');
+    if (state.manifestError) throw new Error(`the deck's narration manifest could not load (${state.manifestError.url}: ${state.manifestError.message})`);
+    if (!(state.version >= 3 && state.clock === 'page' && state.range === true)) throw new Error('the deck\'s player is too old to open on a slide; reload https://hyperdecks.ai/player/v1/player.js, or update the deck\'s copy');
+    phase = 'scene check';
+    const target = seekTarget(state.plan, { scene: config.scene, start: config.start ?? 0 });
+    if (state.silent && target.start > 0) throw new Error('--start needs a narrated deck: this one has no narration to start into (run `hyperdecks narrate`)');
+    const duration = config.frames / config.fps;
+    if (!state.silent && target.start + duration > target.seconds + 0.05) warnings.push(`slide ${target.id} ends ${Math.max(0, target.seconds - target.start).toFixed(1)}s after --start; the rest of the ${duration}s preview shows the deck moving on`);
+    const face = state.presenter;
+    if (face?.wanted === 'head' && face.shown !== 'head') warnings.push(`the deck's live head did not load${face.why ? ` (${face.why})` : ''}; the preview shows ${face.shown === 'static' ? 'its still image' : 'captions only'}`);
+
+    phase = 'layout probe';
+    // The deck's own shape, as the ordinary preview reads it (preview-capture.mjs), unless --aspect-ratio names one.
+    let aspect = config.aspect;
+    if (!aspect) {
+      const detected = await ask(() => {
+        const meta = document.querySelector('meta[name="preview-aspect-ratio"]')?.getAttribute('content');
+        if (meta && /^\d+(?:\.\d+)?:\d+(?:\.\d+)?$/.test(meta)) { const [w, h] = meta.split(':').map(Number); return w / h; }
+        const rect = document.querySelector('section.slide')?.getBoundingClientRect();
+        return rect && rect.width > 100 && rect.height > 100 ? rect.width / rect.height : null;
+      }, undefined, 'to the layout probe');
+      aspect = detected >= 0.5 && detected <= 3 ? detected : 16 / 9;
+      if (aspect !== detected) warnings.push('Using 16:9 aspect ratio; use --aspect-ratio W:H or preview-aspect-ratio metadata for a different deck shape.');
+    }
+    if (Math.abs(aspect - 16 / 9) > 0.001) {
+      await page.setViewportSize({ width: 1280, height: Math.round(1280 / aspect) });
+      await page.waitForTimeout(200); // the player refits on resize; the clock still runs in real time
+    }
+
+    // The slide's heads load before the tour starts: once it runs, the player gives late guest heads
+    // a budget on the page clock (player.js holdForGuestHeads), which the seek spends in moments.
+    // Polled from here: in-page waits run on timers and rAF, which the frozen clock holds.
+    const headsSettled = async () => {
+      for (const until = Date.now() + HEADS_MS; Date.now() < until; await new Promise((ok) => setTimeout(ok, 250))) {
+        const loading = await ask((id) => [...(document.getElementById(id)?.querySelectorAll('[data-hd-head-state="loading"]') ?? [])].length, target.id, 'while heads loaded');
+        if (!loading) return true;
+      }
+      return false;
+    };
+    phase = 'heads';
+    await headsSettled();
+
+    phase = 'seek';
+    // Clip lengths come from the manifest (player.js clipLength), as a recipient's <audio> would roughly end them.
+    await ask(async () => {
+      window.__hdFrameClock.freeze();
+      window.__hdExportGo();
+      await window.__hdFrameClock.settle();
+    }, undefined, 'as the tour started');
+    const failure = (l) => l.errors?.length && `narration failed on ${l.errors[0].id} (${l.errors[0].message})`;
+    // The start counts from when the slide's own clip plays (a clip that loads late starts late), or,
+    // for a slide with no narration of its own, from when it lands.
+    const arrived = (l) => l.silent || (target.narrated ? l.clips.some((c) => c.id === target.id && !c.audio) : l.slides.some((s) => s.id === target.id));
+    let log = await ask(() => window.__hdExport, undefined, 'for its export log');
+    for (let n = 0; !arrived(log); n++) {
+      if (failure(log)) throw new Error(failure(log));
+      if (n === 600) throw new Error(`slide ${target.id}'s narration did not start within 60s of the deck's time`);
+      log = await step(SEEK_STEP_MS, 'while the tour started');
+    }
+    for (let n = Math.round((target.start * 1000) / SEEK_STEP_MS); n > 0; n--) log = await step(SEEK_STEP_MS, 'while seeking');
+    if (failure(log)) throw new Error(failure(log));
+
+    phase = 'heads';
+    // The clock is frozen, so waiting changes nothing on the slide: it lets heads and images finish loading.
+    const headsLoaded = await headsSettled();
+    if (!headsLoaded) warnings.push(`a character head on ${target.id} was still loading after ${HEADS_MS / 1000}s; it shows as a still or silhouette`);
+    phase = 'delay';
+    await page.waitForTimeout(config.delay);
+    await step(0, 'after the delay');
+
+    phase = 'label overlay';
+    await ask((label) => {
+      const badge = document.createElement('div');
+      badge.textContent = '▶  ' + label;
+      badge.setAttribute('style', 'all:initial;position:fixed;bottom:28px;left:50%;transform:translateX(-50%);background:rgba(0,0,0,.85);color:white;font:600 25px sans-serif;padding:14px 24px;border-radius:40px;z-index:2147483647;white-space:nowrap;max-width:90%;overflow:hidden;text-overflow:ellipsis;pointer-events:none');
+      document.documentElement.appendChild(badge);
+    }, config.label, 'to the label overlay');
+    const moment = { scene: target.id, start: target.start, ...(await ask(readMoment, undefined, 'to the moment check')) };
+    if (moment.slide !== target.id) throw new Error(`the player showed ${moment.slide ?? 'no slide'}, not ${target.id}`);
+    const unready = moment.heads.filter((s) => s !== 'ready').length;
+    if (headsLoaded && unready) warnings.push(`${unready} character head(s) on ${target.id} are not live (${[...new Set(moment.heads.filter((s) => s !== 'ready'))].join(', ')}); they show as stills or silhouettes`);
+
+    phase = 'frames';
+    const session = await context.newCDPSession(page);
+    for (let n = 0; n < config.frames; n++) {
+      if (n) log = await step(1000 / config.fps, 'while recording (a frame took over 30s to draw)');
+      const shot = await within(session.send('Page.captureScreenshot', { format: 'png' }), 30000, null);
+      if (!shot?.data) throw new Error('a frame took over 30s to capture');
+      await writeFile(join(dir, `frame-${String(n).padStart(4, '0')}.png`), Buffer.from(shot.data, 'base64'));
+    }
+    if (failure(log)) warnings.push(`${failure(log)} while recording; the preview may stop moving there`);
+    if (blocked) warnings.push(`${blocked} navigation/telemetry/unsafe request(s) blocked; no recipient page was visited.`);
+    if (pageErrors.length) warnings.push(`${pageErrors.length} page error(s): ${pageErrors.slice(0, 2).join('; ').slice(0, 300)}`);
+    return { aspect, moment, warnings };
+  } catch (e) {
+    throw new Error(`Capture failed during ${phase}: ${e.message}`);
+  } finally {
+    if (browser) await browser.close().catch(() => {});
+    if (server) await server.close();
+  }
+}
+
+export async function withTempDir(fn) {
+  const dir = await mkdtemp(join(tmpdir(), 'hyperdecks-preview-'));
+  try { return await fn(dir); } finally { await rm(dir, { recursive: true, force: true }); }
+}

package/src/preview.mjs

@@ -1,3 +1,4 @@
+import { withAvatarView } from "./avatar-view.mjs";
 import { mkdir, readFile, writeFile, stat } from "node:fs/promises";
 import { resolve, extname } from "node:path";
 import { randomUUID } from "node:crypto";
@@ -15,7 +16,7 @@ function bounded(value, fallback, min, max, name, integer = false) {
   return n;
 }
 export function previewOptions(pos, opts) {
-  const allowed = new Set(['file', 'out', 'duration', 'width', 'delay', 'label', 'aspect-ratio', 'share', 'upload', 'json', 'prod', 'dev', 'admin', 'broker', 'convex', 'token', 'client']);
+  const allowed = new Set(['file', 'out', 'duration', 'width', 'delay', 'label', 'aspect-ratio', 'share', 'upload', 'scene', 'start', 'json', 'prod', 'dev', 'admin', 'broker', 'convex', 'token', 'client']);
   for (const k of Object.keys(opts)) if (!allowed.has(k)) throw new Error(`Unknown preview option --${k}`);
   for (const [k, v] of Object.entries(opts)) if (v === undefined) throw new Error(`--${k} requires a value`);
   if (pos.length > 1 || (opts.file ? pos.length !== 0 : pos.length !== 1)) throw new Error("usage: preview create <slug> --out <new-directory> OR preview create --file <index.html> --out <new-directory>");
@@ -33,7 +34,13 @@ export function previewOptions(pos, opts) {
     aspect = m ? Number(m[1]) / Number(m[2]) : NaN;
     bounded(aspect, null, 0.5, 3, '--aspect-ratio');
   }
-  return { slug: pos[0], file: opts.file && resolve(opts.file), out: resolve(opts.out), duration: bounded(opts.duration, 4, 1, 10, '--duration'), width: bounded(opts.width, 600, 240, 1200, '--width', true), delay: bounded(opts.delay, 1000, 0, 10000, '--delay', true), aspect, label };
+  // --scene <slide-id> / --start <seconds>: a moment of the narration, not the opening (preview-moment.mjs).
+  // The id is checked against the deck's slides, and the start against that slide's length, once it loads.
+  if (opts.scene !== undefined && (typeof opts.scene !== 'string' || !opts.scene.trim() || opts.scene.length > 200 || /[\x00-\x1f]/.test(opts.scene))) throw new Error('--scene must be a slide id (the id of its <section class="slide">)');
+  const moment = opts.scene !== undefined || opts.start !== undefined
+    ? { scene: opts.scene ?? null, start: bounded(opts.start, 0, 0, 3600, '--start (seconds into the slide\'s narration)') }
+    : {};
+  return { slug: pos[0], file: opts.file && resolve(opts.file), out: resolve(opts.out), duration: bounded(opts.duration, 4, 1, 10, '--duration'), width: bounded(opts.width, 600, 240, 1200, '--width', true), delay: bounded(opts.delay, 1000, 0, 10000, '--delay', true), aspect, label, ...moment };
 }
 export function validateShare(rows, slug, token, now = Date.now()) {
   const row = rows.find(s => s.token === token && s.deckSlug === slug);
@@ -67,6 +74,7 @@ export async function createPreview(pos, opts, adapters = {}) {
       html = await res.text();
     }
     if (!html) throw new Error('Deck has no HTML to capture');
+    html = await withAvatarView(c, config.slug, html, 'released');
   }
   // A new directory prevents replacing artifacts referenced by an earlier manifest.
   await mkdir(config.out, { recursive: false });
@@ -78,6 +86,8 @@ export async function createPreview(pos, opts, adapters = {}) {
     const capture = adapters.capture || (await import('./preview-capture.mjs')).capturePreview;
     const captured = await capture({ ...config, html, firstPartyOrigins: [targetForCapture(opts), 'https://hyperdecks.ai', 'https://decks.hypersocial.ai', 'https://dashing-snail-874.convex.cloud'] });
     result.files = captured.files;
+    // What the first frame shows (--scene/--start): the slide, the speaking guest and its caption.
+    if (captured.moment) result.moment = captured.moment;
     warnings.push(...captured.warnings);
     for (const f of result.files) if (f.bytes > 5 * 1024 * 1024) warnings.push(`${f.type} exceeds 5 MiB; shorten --duration or reduce --width for email`);
     result.status = 'exported';

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.9.11";
+export const VERSION = "0.9.12";
 const UPLOAD_TIMEOUT_MS = 125_000;
 
 // The app's home. HYPERDECKS_HOST points the prod target's broker and share
@@ -180,6 +180,13 @@ export const api = {
     getJob: makeFunctionReference("narration:getJob"),
     listVoices: makeFunctionReference("narration:listVoices"),
   },
+  deckTransfers: {
+    create: makeFunctionReference("deckTransfers:create"),
+    cancel: makeFunctionReference("deckTransfers:cancel"),
+    list: makeFunctionReference("deckTransfers:list"),
+    accept: makeFunctionReference("deckTransfers:accept"),
+    decline: makeFunctionReference("deckTransfers:decline"),
+  },
   voices: {
     listVoices: makeFunctionReference("voices:listVoices"),
     getVoice: makeFunctionReference("voices:getVoice"),
@@ -194,7 +201,7 @@ export const api = {
   },
 };
 
-const BOOL = new Set(["prod", "dev", "admin", "json", "require-email", "qa", "no-notify", "allow-forward", "no-forward", "help", "version", "all-agents", "global", "project", "transparent", "loop", "upload", "dry-run", "narrated", "layout", "strict", "fix", "full-page", "force", "hosted", "yes", "no-voice", "no-skill", "no-release", "no-open", "save-to-minimoji", "captions-only", "no-brand", "brand", "no-logo", "pdf", "notes", "mp4", "gif", "video", "no-captions", "no-avatar", "title-card", "end-card", "backup"]);
+const BOOL = new Set(["private-only", "prod", "dev", "admin", "json", "require-email", "qa", "no-notify", "allow-forward", "no-forward", "help", "version", "all-agents", "global", "project", "transparent", "loop", "upload", "dry-run", "narrated", "layout", "strict", "fix", "full-page", "force", "hosted", "yes", "no-voice", "no-skill", "no-release", "no-narrate", "no-open", "save-to-minimoji", "captions-only", "no-brand", "brand", "no-logo", "pdf", "notes", "mp4", "gif", "video", "no-captions", "no-avatar", "title-card", "end-card", "backup"]);
 // 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).
@@ -223,7 +230,7 @@ export function parse(args) {
       else {
         const v = args[++i];
         if (k === "to" || (k === "email" && opts.recipients)) addRecipient(opts, k, v);
-        if (k === "agent" && opts[k]) opts[k] = `${opts[k]},${v}`;
+        if ((k === "agent" || k === "guest") && opts[k]) opts[k] = `${opts[k]},${v}`;
         else opts[k] = v;
       }
     } else {