@hypersocial/decks-cli 0.9.10 → 0.9.12

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/files.mjs

@@ -13,6 +13,9 @@ const FILES = {
   "templates/layouts/closer.html": () => new URL("../templates/layouts/closer.html", import.meta.url),
   "templates/layouts/compare.html": () => new URL("../templates/layouts/compare.html", import.meta.url),
   "templates/layouts/features.html": () => new URL("../templates/layouts/features.html", import.meta.url),
+  "templates/layouts/cover-band.html": () => new URL("../templates/layouts/cover-band.html", import.meta.url),
+  "templates/layouts/cover-poster.html": () => new URL("../templates/layouts/cover-poster.html", import.meta.url),
+  "templates/layouts/cover-type.html": () => new URL("../templates/layouts/cover-type.html", import.meta.url),
   "templates/layouts/hero.html": () => new URL("../templates/layouts/hero.html", import.meta.url),
   "templates/layouts/number.html": () => new URL("../templates/layouts/number.html", import.meta.url),
   "templates/layouts/product.html": () => new URL("../templates/layouts/product.html", import.meta.url),

package/src/layouts.mjs

@@ -4,8 +4,9 @@
 import { packageText } from "./files.mjs";
 
 export const NARRATED_FILES = { "index.html": "narrated-deck.html", "script.md": "script.md", "evidence.md": "evidence.md" };
-// The library, in a sensible deck order; `--layouts` takes any order and repeats.
-export const LAYOUTS = ["hero", "number", "product", "split", "phones", "quote", "compare", "timeline", "features", "chart", "team", "closer"];
+// The library: the four covers first (hero is the default; a deck opens on one), then
+// the rest in a sensible deck order. `--layouts` takes any order and repeats.
+export const LAYOUTS = ["hero", "cover-band", "cover-poster", "cover-type", "number", "product", "split", "phones", "quote", "compare", "timeline", "features", "chart", "team", "closer"];
 const LAYOUT_ALIASES = { "big-number": "number", "product-shot": "product", "phone-row": "phones", comparison: "compare", "three-up": "features", "image-copy": "split", "image-text": "split" };
 
 const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");

package/src/loadingBlock.mjs

@@ -4,11 +4,17 @@
 // (lib/loadingBlock.test.ts keeps the three in step). A JS string, not a read of
 // the template, because Convex (the hosted draft's write) cannot read package files.
 // No Node imports: the CLI and Convex (and so the MCP route's writes) use it.
+// The opening card (opening.mjs) is the loader: its rules in the style, and the
+// <script data-hd-opening> after it that builds it once the page is parsed. A
+// frame or ?thumb (data-hd-frame) gets the quiet dots instead; an export neither.
+import { OPENING_CSS, OPENING_PAGE_SCRIPT } from "./opening.mjs";
+
 export const LOADING_BLOCK = [
   "<!-- Loading state (keep verbatim; `hyperdecks check` requires it). Until the",
   "     player marks body[data-hd-ready] the page shows only the slide card, at its",
   "     final size, in the deck's --hd-ground (its first slide's colour) on the",
-  "     page's brand colour, with a quiet loader in --hd-ground-ink; then the",
+  "     page's brand colour, with the opening card over it (the title and the",
+  "     presenter's still), or in a frame quiet dots in --hd-ground-ink; then the",
   "     slides fade in. If the player never arrives, the slides show after 10 s",
   "     rather than never. Put data-layout=\"overlay\" on <html> for the overlay. -->",
   "<link rel=\"modulepreload\" href=\"https://hyperdecks.ai/player/v1/player.js\">",
@@ -22,7 +28,7 @@ export const LOADING_BLOCK = [
   "  /* The card as the player draws it (player.css, framed): 16:9, scaled to fit",
   "     between the 64px masthead and the 56px dock, 24px in from the sides. */",
   "  body::before { inset: 64px 24px 56px; margin: auto; width: min(100vw - 48px, (100dvh - 120px) * 16 / 9); height: min(100dvh - 120px, (100vw - 48px) * 9 / 16); border-radius: calc(min(100vw - 48px, (100dvh - 120px) * 16 / 9) * .01125); background: var(--hd-ground, #fff); box-shadow: 0 0 0 1px color-mix(in srgb, var(--hd-ground-ink, #0b0b0f) 16%, transparent); }",
-  "  body::after { left: 50%; top: 50%; width: 12px; height: 12px; margin: -6px 0 0 -6px; border-radius: 50%; color: var(--hd-ground-ink, #0b0b0f); background: currentColor; box-shadow: -24px 0 currentColor, 24px 0 currentColor; opacity: 0; animation: hd-dots .7s ease-in-out .6s infinite alternate; }",
+  "  [data-hd-frame] body::after { left: 50%; top: 50%; width: 12px; height: 12px; margin: -6px 0 0 -6px; border-radius: 50%; color: var(--hd-ground-ink, #0b0b0f); background: currentColor; box-shadow: -24px 0 currentColor, 24px 0 currentColor; opacity: 0; animation: hd-dots .7s ease-in-out .6s infinite alternate; }",
   "  body[data-hd-ready]::before, body[data-hd-ready]::after { opacity: 0; animation: none; }",
   "  /* The overlay (embedded, ?thumb, or data-layout=\"overlay\"): the stage fills the window. */",
   "  :is([data-hd-frame], [data-layout=\"overlay\"]) body::before { inset: 0; width: min(100vw, 100dvh * 16 / 9); height: min(100dvh, 100vw * 9 / 16); border-radius: calc(min(100vw, 100dvh * 16 / 9) * .01125); box-shadow: none; }",
@@ -42,21 +48,28 @@ export const LOADING_BLOCK = [
   "  @keyframes hd-in { from { opacity: 0; } }",
   "  @keyframes hd-dots { from { opacity: .15; } to { opacity: .6; } }",
   "  @keyframes hd-fail-open { to { visibility: visible; overflow: auto; } }",
+  ...OPENING_CSS.replace(/\n$/, "").split("\n"),
   "</style>",
+  OPENING_PAGE_SCRIPT,
 ].join("\n");
 
 const STYLE = /<style\b[^>]*\sdata-hd-loading(?=[\s>=])[^>]*>[\s\S]*?<\/style>/i;
 const HEAD = /<head\b[^>]*>[\s\S]*?<\/head>/i;
 const PLAYER = /<script\b[^>]*\/player\/v\d+\/player\.js"[^>]*>/;
 const LOADING_STYLE = STYLE.exec(LOADING_BLOCK)[0];
-// The block's pieces besides its style, on any player host: the two preloads and
-// the frame flag (each kept once), and its own comment (matched only as a whole
+const OPENING_SCRIPT = /<script data-hd-opening>[\s\S]*?<\/script>/;
+const OPENING_SCRIPT_PIECE = new RegExp(`${OPENING_SCRIPT.source}[ \\t]*\\n?`, "g");
+// The script with the line break before it (as the block writes it after the style).
+const OPENING_SCRIPT_LINE = new RegExp(`\\n?[ \\t]*${OPENING_SCRIPT.source}`, "g");
+// The block's pieces besides its style, on any player host: the two preloads,
+// the frame flag and the card's <script data-hd-opening> (each kept once), and its own comment (matched only as a whole
 // comment, so a person's comments in <head> are never touched).
 const PIECES = [
   /<link rel="modulepreload" href="[^"]*\/player\/v\d+\/player\.js">[ \t]*\n?/g,
   /<link rel="preload" as="style" href="[^"]*\/player\/v\d+\/player\.css">[ \t]*\n?/g,
   /<script>if \(self !== top \|\| [^<]*document\.documentElement\.dataset\.hdFrame = "";<\/script>[ \t]*\n?/g,
   new RegExp(`${STYLE.source}[ \\t]*\\n?`, "gi"),
+  OPENING_SCRIPT_PIECE,
 ];
 const BLOCK_COMMENT = /^<!-- Loading state \(keep verbatim/;
 
@@ -93,11 +106,13 @@ export function withLoadingBlock(html) {
     const at = title ? title.index + title[0].length : /^<head\b[^>]*>/i.exec(cleaned)[0].length;
     return { html: splice(`${cleaned.slice(0, at)}\n${LOADING_BLOCK}${cleaned.slice(at)}`), fixed: "inserted" };
   }
-  const deduped = trimPieces(rawHead, 1);
+  // The card's script goes right after the style, as the template's (a block
+  // from before the card gets it; a stray copy elsewhere goes).
+  const deduped = trimPieces(rawHead, 1).split(/(<!--[\s\S]*?-->)/).map((part, i) => (i % 2 ? part : part.replace(OPENING_SCRIPT_LINE, ""))).join("");
   // The one style left, outside comments, made the template's.
   const blank = deduped.replace(/<!--[\s\S]*?-->/g, (c) => " ".repeat(c.length));
   const style = STYLE.exec(blank);
-  const fresh = deduped.slice(0, style.index) + LOADING_STYLE + deduped.slice(style.index + style[0].length);
+  const fresh = deduped.slice(0, style.index) + LOADING_STYLE + "\n" + OPENING_PAGE_SCRIPT + deduped.slice(style.index + style[0].length);
   if (fresh === rawHead) return { html, fixed: null };
-  return { html: splice(fresh), fixed: deduped !== rawHead ? "deduped" : "refreshed" };
+  return { html: splice(fresh), fixed: trimPieces(rawHead, 1) !== rawHead ? "deduped" : "refreshed" };
 }

package/src/opening.mjs

@@ -0,0 +1,117 @@
+// The opening card a deck shows while its player loads (#207): the first
+// slide blurred and breathing where the slide will be, and a glass card with
+// the presenter's still hopping, the title and the player's real boot steps
+// (body[data-hd-boot], player.js). When the player marks body[data-hd-ready]
+// the presenter jumps, the card fades and the slide sharpens.
+//
+// One card, two ways in: a route that serves the deck adds it with the deck's
+// poster and narrator (lib/deckLoadingOverlay.ts), and every deck's own
+// loading state (loadingBlock.mjs, the templates) builds it in the page from
+// what the file has (its <title>, the player tag's data-presenter-image), so a
+// raw deck file opens on it too. The page's own card steps aside when a route
+// already added one. Never in a frame, a thumbnail (?thumb,
+// data-hyperdecks-thumb) or an export (?export); a deck ready within FAST_MS
+// never shows it; if the player never says ready it goes after FAIL_OPEN_MS.
+// No Node imports: the CLI, Convex and the app all use it.
+
+export const FAST_MS = 150;
+export const FAIL_OPEN_MS = 10000;
+
+// The boot steps player.js reports on body[data-hd-boot], in the order it
+// reaches them: [progress %, copy]. {name} is the presenter's.
+export const BOOT_STEPS = Object.freeze({
+  page: [10, "Opening the deck…"],
+  player: [38, "Loading the player…"],
+  presenter: [62, "Waking up {name}…"],
+  narration: [84, "Getting the narration…"],
+});
+
+// The card's rules (the route wraps them in <style data-hd-opening>; the
+// loading block carries them in its <style data-hd-loading>).
+export const OPENING_CSS = `#hd-open{position:fixed;inset:0;z-index:2147483000;pointer-events:none;visibility:visible!important;animation:none!important;opacity:0;font-family:var(--hd-ui-font,"Space Grotesk",system-ui,sans-serif);color:#0b0b0f}
+#hd-open.is-shown{opacity:1;transition:opacity .2s ease-out}
+#hd-open.is-gone{opacity:0;transition:opacity .45s ease-out}
+#hd-open .hdo-slide{position:absolute;inset:64px 24px 56px;margin:auto;width:min(100vw - 48px,(100dvh - 120px)*16/9);height:min(100dvh - 120px,(100vw - 48px)*9/16);border-radius:calc(min(100vw - 48px,(100dvh - 120px)*16/9)*.01125);overflow:hidden;container-type:inline-size;background:var(--hd-ground,#fff)}
+#hd-open .hdo-slide img{position:absolute;inset:0;width:100%;height:100%;object-fit:cover;display:block;filter:blur(2.2cqi) saturate(1.15);transform:scale(1.12);animation:hdo-breathe 2.4s ease-in-out infinite}
+#hd-open .hdo-slide::after{content:"";position:absolute;inset:0;background:linear-gradient(100deg,transparent 30%,rgba(255,255,255,.3) 50%,transparent 70%);background-size:250% 100%;animation:hdo-shim 1.8s ease-in-out infinite;mix-blend-mode:soft-light}
+#hd-open.is-done .hdo-slide img{animation:hdo-deblur .5s cubic-bezier(.2,.8,.2,1) .5s forwards}
+#hd-open.is-done .hdo-slide::after{opacity:0;transition:opacity .3s}
+.hdo-card{position:absolute;left:50%;top:50%;translate:-50% -50%;width:min(86vw,420px);display:grid;justify-items:center;gap:.6em;padding:1.3em 1.5em 1.2em;border-radius:22px;background:rgba(255,255,255,.74);-webkit-backdrop-filter:blur(14px) saturate(1.3);backdrop-filter:blur(14px) saturate(1.3);box-shadow:4px 4px 0 #0b0b0f;border:1.5px solid #0b0b0f;text-align:center;box-sizing:border-box}
+#hd-open.is-done .hdo-card{opacity:0;transform:scale(.96);transition:opacity .25s .5s,transform .25s .5s}
+.hdo-buddy{position:relative;width:92px;height:96px;margin-top:-62px;display:grid;justify-items:center}
+.hdo-hop{width:86px;height:80px;transform-origin:50% 100%;animation:hdo-hop 1.15s cubic-bezier(.3,0,.4,1) infinite}
+.hdo-look{width:100%;height:100%;animation:hdo-look 4.6s ease-in-out infinite}
+.hdo-buddy img{width:100%;height:100%;object-fit:contain;display:block;filter:drop-shadow(0 3px 0 rgba(11,11,15,.18))}
+.hdo-shadow{position:absolute;bottom:4px;width:46px;height:8px;border-radius:50%;background:rgba(11,11,15,.22);animation:hdo-shadow 1.15s cubic-bezier(.3,0,.4,1) infinite}
+.hdo-think{position:absolute;right:-30px;top:-6px;display:flex;gap:3px;padding:5px 8px;border-radius:14px;background:#fff;border:1.5px solid #0b0b0f;box-shadow:2px 2px 0 #0b0b0f}
+.hdo-think::after{content:"";position:absolute;left:4px;bottom:-7px;width:7px;height:7px;border-radius:50%;background:#fff;border:1.5px solid #0b0b0f}
+.hdo-think i{width:5px;height:5px;border-radius:50%;background:#0b0b0f;animation:hdo-tdot 1s ease-in-out infinite}
+.hdo-think i:nth-child(2){animation-delay:.15s}.hdo-think i:nth-child(3){animation-delay:.3s}
+.hdo-spark{position:absolute;left:50%;top:40%;width:8px;height:8px;margin:-4px;opacity:0}
+.hdo-spark::before{content:"";position:absolute;inset:0;background:#0b0b0f;clip-path:polygon(50% 0,62% 38%,100% 50%,62% 62%,50% 100%,38% 62%,0 50%,38% 38%)}
+#hd-open.is-done .hdo-hop{animation:hdo-yay .55s cubic-bezier(.2,1.4,.4,1) forwards}
+#hd-open.is-done :is(.hdo-look,.hdo-shadow){animation:none}
+#hd-open.is-done .hdo-think{opacity:0;transition:opacity .15s}
+#hd-open.is-done .hdo-spark{animation:hdo-spark .6s ease-out forwards}
+.hdo-title{font-weight:700;font-size:18px;line-height:1.2;text-wrap:balance;overflow-wrap:anywhere}
+.hdo-by{font:12.5px/1.3 var(--hd-ui-mono,"JetBrains Mono",ui-monospace,monospace);color:#3d3b35}
+.hdo-bar{width:100%;height:5px;border-radius:999px;background:rgba(11,11,15,.12);overflow:hidden}
+.hdo-bar i{display:block;height:100%;width:8%;background:#0b0b0f;border-radius:999px;transition:width .35s ease-out}
+.hdo-step{font:12px/1.3 var(--hd-ui-mono,"JetBrains Mono",ui-monospace,monospace);color:#55534b;min-height:1.3em}
+@keyframes hdo-breathe{50%{filter:blur(2.6cqi) saturate(1.25) brightness(1.05)}}
+@keyframes hdo-shim{0%{background-position:120% 0}100%{background-position:-120% 0}}
+@keyframes hdo-deblur{to{filter:blur(0);transform:none}}
+@keyframes hdo-hop{0%,100%{transform:translateY(0) scale(1.06,.92)}12%{transform:translateY(0) scale(.95,1.06)}45%{transform:translateY(-14px) scale(1,1)}70%{transform:translateY(0) scale(1.04,.95)}82%{transform:translateY(0) scale(1,1)}}
+@keyframes hdo-shadow{0%,100%{transform:scale(1.05);opacity:.9}45%{transform:scale(.62);opacity:.45}70%{transform:scale(1);opacity:.85}}
+@keyframes hdo-look{0%,18%{transform:rotate(0)}24%,38%{transform:rotate(-9deg) translateX(-2px)}44%,58%{transform:rotate(8deg) translateX(2px)}64%,100%{transform:rotate(0)}}
+@keyframes hdo-tdot{0%,100%{opacity:.25;transform:translateY(0)}40%{opacity:1;transform:translateY(-2px)}}
+@keyframes hdo-yay{0%{transform:translateY(0) scale(1.08,.9)}40%{transform:translateY(-26px) scale(.94,1.08) rotate(-6deg)}100%{transform:translateY(-6px) scale(1) rotate(0)}}
+@keyframes hdo-spark{0%{opacity:0;transform:translate(0,0) scale(.4)}30%{opacity:1}100%{opacity:0;transform:translate(var(--x),var(--y)) scale(1.2) rotate(90deg)}}
+:is([data-hd-frame],[data-layout="overlay"]) #hd-open .hdo-slide{inset:0;width:min(100vw,100dvh*16/9);height:min(100dvh,100vw*9/16)}
+@media (max-width:650px){#hd-open .hdo-slide{inset:52px 8px calc(56px + env(safe-area-inset-bottom));width:auto;height:auto;border-radius:14px}.hdo-card{width:min(84vw,320px);padding:1em 1.1em .95em}.hdo-title{font-size:15.5px}.hdo-buddy{transform:scale(.85);margin-top:-58px}}
+@media (prefers-reduced-motion:reduce){#hd-open *,#hd-open *::before,#hd-open *::after{animation:none!important;transition:none!important}#hd-open .hdo-slide::after{display:none}#hd-open.is-done .hdo-card{opacity:1;transform:none}}
+@media print{#hd-open{display:none!important}}
+`;
+
+// Runs the card `o` (#hd-open): shows it after FAST_MS unless the deck is
+// ready, follows data-hd-boot, and on data-hd-ready jumps, fades and removes
+// itself. In a frame, a thumbnail or an export it removes itself at once.
+export const OPENING_RUN = `function(o){var b=document.body,d=document.documentElement;if(!o||!b)return;
+if(self!==top||/[?&](thumb|export)\\b/.test(location.search)||d.hasAttribute("data-hyperdecks-thumb")){o.remove();return}
+var S=${JSON.stringify(BOOT_STEPS)},bar=o.querySelector(".hdo-bar i"),step=o.querySelector(".hdo-step"),who=o.getAttribute("data-name")||"the presenter",at=0,shown=false,done=false,mo;
+var rm=window.matchMedia&&matchMedia("(prefers-reduced-motion: reduce)").matches;
+function boot(){var s=S[b.getAttribute("data-hd-boot")];if(!s||s[0]<=at)return;at=s[0];bar.style.width=s[0]+"%";step.textContent=s[1].split("{name}").join(who)}
+function finish(){if(done)return;done=true;if(mo)mo.disconnect();clearTimeout(t1);clearTimeout(t2);
+if(!shown){o.remove();return}bar.style.width="100%";step.textContent="Ready";
+o.classList.add("is-done");setTimeout(function(){o.classList.add("is-gone")},rm?0:500);setTimeout(function(){o.remove()},rm?500:1000)}
+function check(){if(b.hasAttribute("data-hd-ready"))finish();else boot()}
+var t1=setTimeout(function(){if(!done){shown=true;o.classList.add("is-shown")}},${FAST_MS});
+var t2=setTimeout(finish,${FAIL_OPEN_MS});
+step.textContent=S.page[1];
+if(window.MutationObserver){mo=new MutationObserver(check);mo.observe(b,{attributes:true,attributeFilter:["data-hd-ready","data-hd-boot"]})}
+check()}`;
+
+// Five sparks around the presenter for the jump at ready.
+export const OPENING_SPARKS = [[-40, -30], [42, -34], [-30, 10], [36, 6], [0, -46]]
+  .map(([x, y]) => `<span class="hdo-spark" style="--x:${x}px;--y:${y}px"></span>`).join("");
+// The presenter's still in the card (its src set by whoever builds it).
+export const OPENING_BUDDY = `<div class="hdo-buddy"><div class="hdo-hop"><div class="hdo-look"><img src="" alt=""></div></div><div class="hdo-shadow"></div><div class="hdo-think"><i></i><i></i><i></i></div>${OPENING_SPARKS}</div>`;
+
+// The page's own card (the loading block's <script data-hd-opening>): once the
+// page is parsed (readyState "interactive", before the player module runs),
+// unless a route already added a card, the player is ready, or the page is
+// framed, a thumbnail or an export, it puts a card at the top of <body> with
+// the page's <title> and the player tag's presenter still (none when it
+// presents nobody), with no poster and no narrator's name, and runs it.
+export const OPENING_PAGE_SCRIPT = `<script data-hd-opening>(function(){var d=document;
+if(self!==top||/[?&](thumb|export)\\b/.test(location.search))return;
+function go(){if(d.readyState==="loading")return;d.removeEventListener("readystatechange",go);
+var b=d.body,p=d.querySelector('script[src*="/player/v"][src*="/player.js"]');
+if(!b||!p||d.getElementById("hd-open")||b.hasAttribute("data-hd-ready")||d.documentElement.hasAttribute("data-hyperdecks-thumb"))return;
+var o=d.createElement("div"),img=p.getAttribute("data-presenter")!=="none"&&p.getAttribute("data-presenter-image");
+o.id="hd-open";o.setAttribute("aria-hidden","true");
+o.innerHTML='<div class="hdo-slide"></div><div class="hdo-card">'+(img?${JSON.stringify(OPENING_BUDDY)}:'')+'<div class="hdo-title"></div><div class="hdo-bar"><i></i></div><div class="hdo-step"></div></div>';
+if(img){var i=o.querySelector(".hdo-buddy img");i.addEventListener("error",function(){var y=o.querySelector(".hdo-buddy");if(y)y.remove()});i.src=img}
+o.querySelector(".hdo-title").textContent=(d.title||"").replace(/\\s+/g," ").trim();
+b.insertBefore(o,b.firstChild);(${OPENING_RUN})(o)}
+d.addEventListener("readystatechange",go);go()})();</script>`;

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 {