@hypersocial/decks-cli 0.9.9 → 0.9.11

package/src/commands.mjs

@@ -72,12 +72,23 @@ async function deckStats(pos, opts) {
   }
 }
 
+// The owner link: present or check your own deck (untracked, owner-only).
+function deckLink(pos, opts) {
+  const [slug] = pos;
+  if (!slug) throw new Error("usage: deck link <slug> [--json]");
+  const out = ops.ownerLink(opts, slug);
+  if (opts.json) return console.log(JSON.stringify(out, null, 2));
+  console.log(out.ownerUrl);
+  if (out.backupUrl) console.log(`backup (other domain): ${out.backupUrl}`);
+  console.log("Only you can open it, signed in; nothing is tracked. Present (or H) hides your owner tools for a screen share.");
+}
+
 function deckOpen(pos, opts) {
   const [slug] = pos;
   if (!slug) throw new Error("usage: deck open <slug>");
-  const url = `${target(opts).brokerBase}/d/${slug}`;
-  console.log(url);
-  openBrowser(url);
+  const { ownerUrl } = ops.ownerLink(opts, slug);
+  console.log(ownerUrl);
+  openBrowser(ownerUrl);
 }
 
 async function deckRemove(pos, opts) {
@@ -89,8 +100,11 @@ async function deckRemove(pos, opts) {
 
 async function shareNew(pos, opts) {
   const [slug, recipient] = pos;
-  if (!slug || !recipient) throw new Error("usage: share new <slug> <recipient> [--email e] [--note n] [--require-email] [--expires iso] [--limit n] [--qa] [--no-notify] [--allow-forward|--no-forward]");
+  const usage = "usage: share new <slug> <recipient> [--email e] [--note n] [--require-email] [--expires iso] [--limit n] [--qa] [--no-notify] [--allow-forward|--no-forward] [--pace auto|slide|step]";
+  if (!slug || !recipient) throw new Error(usage);
   if (opts["allow-forward"] && opts["no-forward"]) throw new Error("pick one of --allow-forward and --no-forward");
+  // The link's own pace; without it the link follows the deck's.
+  if ("pace" in opts && !ops.DECK_PACES.includes(opts.pace)) throw new Error(usage);
   const { token } = await ops.createShare(opts, {
     slug,
     recipient,
@@ -100,6 +114,7 @@ async function shareNew(pos, opts) {
     qa: opts.qa || undefined,
     notify: opts["no-notify"] ? false : undefined,
     allowForward: opts["allow-forward"] ? true : opts["no-forward"] ? false : undefined,
+    pace: opts.pace,
     expires: opts.expires,
     limit: opts.limit,
   });
@@ -123,7 +138,7 @@ async function shareList(pos, opts) {
   // Rows arrive with each link's forwards right after it; indent those.
   for (const r of rows) {
     const who = r.parentToken ? `  ↳ ${r.recipient} via ${r.forwardedBy ?? "?"}` : r.recipient;
-    console.log(`${r.enabled ? "on " : "off"}\t${r.token}\t${who}\topens:${r.opens}\tfwd:${r.allowForward ? "on" : "off"}${r.qa ? "\tQA (untracked)" : ""}${r.notify === false ? "\tmuted" : ""}${r.probablyForwarded ? "\tprobably forwarded" : ""}${r.archived ? "\t(archived)" : ""}`);
+    console.log(`${r.enabled ? "on " : "off"}\t${r.token}\t${who}\topens:${r.opens}\tfwd:${r.allowForward ? "on" : "off"}${r.pace ? `\tpace:${r.pace}` : ""}${r.qa ? "\tQA (untracked)" : ""}${r.notify === false ? "\tmuted" : ""}${r.probablyForwarded ? "\tprobably forwarded" : ""}${r.archived ? "\t(archived)" : ""}`);
   }
   if (!rows.length) console.log("(no shares)");
 }
@@ -348,7 +363,10 @@ commands:
   login [--token <pat>] [--broker <url>] [--dev]
   logout [--dev]
   whoami [--json] [--dev]
-  deck list|stats|open|rm|forward|view
+  deck list|stats|open|link|rm|forward|view
+  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 view <slug> [slides|scroll|default] [--toggle on|off] [--pace auto|slide|step|default] [--ai-readable on|off]
@@ -378,7 +396,7 @@ commands:
   release <slug|deck-dir> [--to "<name>" [--email <e>]]... [--qa] [--no-notify] [--title t] [--voice v] [--captions-only (--hosted)]
                    on a committed deck: check → narrate → import → share new per --to
   share new|list|on|off|forward|mute|unmute|rm|url
-    share new <slug> <recipient> [--qa] [--no-notify] [--allow-forward|--no-forward]
+    share new <slug> <recipient> [--qa] [--no-notify] [--allow-forward|--no-forward] [--pace auto|slide|step]
     share forward on|off|default <token>
                    let this link's viewer forward it as their own tracked link ("Dana via Peter",
                    one hop); default follows the deck. share off on a link also turns off its forwards.
@@ -972,9 +990,20 @@ function commandTable(pos, rest, opts) {
       console.log(opts.json ? JSON.stringify(out, null, 2) : `"${out.caption}"\n  ${out.url}`);
     },
     "deck narrator": async () => {
-      if (rest.length < 2) throw new Error("usage: deck narrator <slug> <name|id|none|default>");
+      if (rest.length < 2) throw new Error("usage: deck narrator <slug> <name|id|none|default> [--dir <deck folder>]");
       const out = await ops.setDeckNarrator(opts, rest[0], rest.slice(1).join(" "));
-      console.log(opts.json ? JSON.stringify(out, null, 2) : `OK ${out.slug} → ${out.narrator} (voice at its next narrate; face in play and the draft link now, on share links at its next release)`);
+      const log = opts.json ? (line) => console.error(line) : (line) => console.log(line);
+      log(`OK ${out.slug} → ${out.narrator} (voice at its next narrate; face in play and the draft link now, on share links at its next release)`);
+      // The local file names the face too, so the draft opened from disk shows it.
+      const { writeDraftFace } = await import("./draftFace.mjs");
+      const dir = resolve(typeof opts.dir === "string" ? opts.dir : join("decks", out.slug));
+      let local = { wrote: false };
+      try {
+        local = await writeDraftFace(opts, out.slug, join(dir, "index.html"), { log });
+      } catch (e) {
+        log(`⚠ presenter: the server was updated but index.html was not (${e.message})`);
+      }
+      if (opts.json) console.log(JSON.stringify({ ...out, indexHtml: local.wrote ? join(dir, "index.html") : null }, null, 2));
     },
     "preview setup": async () => {
       const { setupCapture } = await import("./preview-capture.mjs");
@@ -986,6 +1015,7 @@ function commandTable(pos, rest, opts) {
     "deck list": () => deckList(opts),
     "deck stats": () => deckStats(rest, opts),
     "deck open": () => deckOpen(rest, opts),
+    "deck link": () => deckLink(rest, opts),
     "deck rm": () => deckRemove(rest, opts),
     "deck forward": () => deckForward(rest, opts),
     "deck view": () => deckView(rest, opts),

package/src/draftFace.mjs

@@ -0,0 +1,56 @@
+// The narrator's face written into a draft's index.html on disk (roadmap:
+// a-narrated-draft-shows-its-narrator-s-face-from-the-file-on-), so the file
+// plays with its face however it is opened, not only through play and release.
+// deck new, deck narrator and narrate use it.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import * as ops from "./ops.mjs";
+import { DASH_PRESENTER, withNarrator, writeNarratorFace } from "./presenter.mjs";
+
+// What to write for `slug`: { face } (null: captions only on purpose), or
+// { face: undefined, why } when the narrator has no face and nobody chose captions
+// only (writeDraftFace then takes a CLI-written face off), or the lookup failed
+// (`failed`: nothing is decided, the file stays).
+export async function draftFace(opts, slug) {
+  let found;
+  try {
+    found = await ops.presenterWithReason(opts, slug, undefined, { draft: true });
+  } catch (e) {
+    return { face: undefined, why: `could not look up the narrator's face (${e.message})`, failed: true };
+  }
+  if (found?.presenter) return { face: found.presenter, name: found.who?.face ?? null };
+  // Captions only on purpose only when the deck says so; faces off or a missing face stays unwritten.
+  if (!found?.presenter && found?.captionsOnly) return { face: null, name: null };
+  return { face: undefined, why: found?.who?.reason ?? "no narrator with a face" };
+}
+
+// Write `slug`'s face into `htmlPath`. `fallback`: the face to write when the
+// lookup fails (deck new writes D.A.S.H.). Logs one line; returns what it wrote.
+export async function writeDraftFace(opts, slug, htmlPath, { log = () => {}, fallback } = {}) {
+  if (!existsSync(htmlPath)) {
+    log(`⚠ presenter: ${htmlPath} not found, so the file was not updated (the server was); pass --dir <deck folder>`);
+    return { wrote: false };
+  }
+  const got = await draftFace(opts, slug);
+  const face = got.face === undefined && got.failed && fallback ? fallback : got.face;
+  const html = readFileSync(htmlPath, "utf8");
+  if (face === undefined) {
+    // The narrator has no face now: a face the CLI wrote for an earlier one comes off, as play and release do.
+    const off = got.failed ? html : withNarrator(html, null, { face: null });
+    if (off !== html) {
+      writeFileSync(htmlPath, off);
+      log(`⚠ presenter: no face (${got.why}); the earlier narrator's face was taken off index.html`);
+      return { wrote: true, face: null, why: got.why };
+    }
+    log(`⚠ presenter: index.html left as written: ${got.why}`);
+    return { wrote: false, why: got.why };
+  }
+  const out = writeNarratorFace(html, face);
+  if (!out.wrote) {
+    log(`⚠ presenter: index.html left as written: ${out.why}`);
+    return { wrote: false, why: out.why };
+  }
+  if (out.html !== html) writeFileSync(htmlPath, out.html);
+  const who = face === null ? "captions only" : face === DASH_PRESENTER && got.failed ? `D.A.S.H. (${got.why}; deck narrator <name> fixes it)` : got.name ?? "the narrator's face";
+  log(`  presenter: ${who}, written to index.html`);
+  return { wrote: true, face };
+}

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

@@ -9,6 +9,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import * as ops from "./ops.mjs";
 import { presenterLine } from "./presenter.mjs";
+import { writeDraftFace } from "./draftFace.mjs";
 export { sectionIds, setManifestUrl } from "./checkRules.mjs";
 import { sectionIds, setManifestUrl } from "./checkRules.mjs";
 
@@ -39,7 +40,8 @@ export function narrationRequest(pos, opts) {
   };
 }
 
-export async function narrate(pos, opts = {}, { log = (line) => console.log(line) } = {}) {
+// writeFace false: leave the presenter as written (release narrates, then puts the face on the upload itself).
+export async function narrate(pos, opts = {}, { log = (line) => console.log(line), writeFace = true } = {}) {
   const { deckDir, fields } = narrationRequest(pos, opts);
   if (opts["dry-run"]) {
     const preview = await ops.previewNarration(opts, fields);
@@ -85,6 +87,9 @@ export async function narrate(pos, opts = {}, { log = (line) => console.log(line
       writeFileSync(htmlPath, next);
       log(`  index.html: data-manifest → ${job.manifestUrl}`);
     }
+    // The narrator's face too, so the file opened as written shows what play and release show.
+    // The narration is paid for and saved: a failed face write warns and never fails narrate.
+    if (writeFace) await writeDraftFace(opts, fields.slug, htmlPath, { log }).catch((e) => log(`⚠ presenter: index.html not updated (${e?.message ?? e})`));
   }
   log(`✓ ${job.manifest.clips.length} clips, ${job.manifest.spokenDuration}s spoken, ${job.manifest.totalDuration}s with holds; ${job.renderedChars} characters rendered`);
   log(`  manifest: ${job.manifestUrl}\n  saved:    ${join(out, "manifest.json")}`);

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

@@ -3,7 +3,7 @@ import { zipSync } from "fflate";
 import { SPECIES } from "./species.mjs";
 import { COLOR_KEYS, FONT_PAIRINGS, FONT_ROLES, findPairing, googleFontsUrl } from "./brand.mjs";
 import { MAX_IMPORT_FILE_BYTES, draftArgs, extractFile } from "./brandImport.mjs";
-import { api, client, linkBase, target, uploadBytes as runtimeUploadBytes } from "./runtime.mjs";
+import { api, backupLinkUrl, client, linkBase, target, uploadBytes as runtimeUploadBytes } from "./runtime.mjs";
 import {
   bytesFromText,
   isTextAsset,
@@ -21,6 +21,17 @@ export async function whoami(opts = {}) {
 }
 
 // Your own decks. `all: true` lists every deck, for admins only (support tools).
+// The owner link (/d/<slug>, app/d/[slug]): the released deck for its owner
+// only, untracked, with the owner toolbar (Present hides it for a screen
+// share). How an owner or their agent presents or checks a deck; anyone else
+// gets a sign-in notice. QA links are only for testing what a recipient sees.
+// `backupUrl`: the same link on the other app host (null in dev).
+export function ownerLink(opts, slug) {
+  if (!slug) throw new Error("slug is required");
+  const url = `${target(opts).brokerBase}/d/${encodeURIComponent(slug)}`;
+  return { slug, ownerUrl: url, backupUrl: backupLinkUrl(url) };
+}
+
 export async function listDecks(opts = {}, { all = false } = {}) {
   const rows = await (await client(opts)).query(all ? api.decks.listAll : api.decks.listForViewer, {});
   return rows.map((d) => ({
@@ -39,6 +50,9 @@ export async function listDecks(opts = {}, { all = false } = {}) {
     // false: the deck runs its own player, so view/viewToggle do not apply
     // (null: not known yet, treated as on).
     usesPlayer: d.usesPlayer ?? null,
+    // Present or check it yourself here (owner-only, untracked); not a link to
+    // send. Null with nothing released, or on someone else's deck (admins' all).
+    ownerUrl: !all && (d.html || d.htmlStorageId || d.hasHtml) ? ownerLink(opts, d.slug).ownerUrl : null,
   }));
 }
 
@@ -568,6 +582,8 @@ export async function listShares(opts, slug) {
     // viewer who forwarded it. Rows come back with each link's forwards after it.
     allowForward: !!r.allowForward,
     allowForwardOverride: r.allowForwardOverride ?? null,
+    // The link's own pace (auto, slide, step); null = it follows the deck.
+    pace: r.pace ?? null,
     parentToken: r.parentToken ?? null,
     forwardedBy: r.forwardedBy ?? null,
     probablyForwarded: !!r.probablyForwarded,
@@ -584,6 +600,11 @@ export async function createShare(opts, fields) {
   if (fields.note) args.note = fields.note;
   if (fields.requireEmail) args.requireEmail = true;
   if (fields.allowForward !== undefined) args.allowForward = !!fields.allowForward;
+  // The link's own pace; absent = it follows the deck's.
+  if (fields.pace !== undefined) {
+    if (!DECK_PACES.includes(fields.pace)) throw new Error(`pace must be auto, slide or step (got ${JSON.stringify(fields.pace)})`);
+    args.pace = fields.pace;
+  }
   if (fields.expires) {
     const t = Date.parse(fields.expires);
     if (Number.isNaN(t)) throw new Error(`expires must be an ISO date; got ${fields.expires}`);
@@ -1191,8 +1212,9 @@ export async function presenterFor(opts, slug, voice) {
 }
 
 // The same answer as presenterFor plus who presents in words: { presenter, who }.
-export async function presenterWithReason(opts, slug, voice) {
-  return (await client(opts)).query(api.avatars.presenterWithReason, { slug, ...(voice ? { voice: String(voice) } : {}) });
+// `draft`: also answer for a deck not narrated yet, from the voice its narrate would use.
+export async function presenterWithReason(opts, slug, voice, { draft = false } = {}) {
+  return (await client(opts)).query(api.avatars.presenterWithReason, { slug, ...(voice ? { voice: String(voice) } : {}), ...(draft ? { draft: true } : {}) });
 }
 
 // ---- narrators (convex/narrators.ts) ------------------------------------------

package/src/play.mjs

@@ -12,7 +12,7 @@ import { basename, join, relative } from "node:path";
 import { playerScript, sectionIds } from "./checkRules.mjs";
 import { resolveDeckDir } from "./check.mjs";
 import * as ops from "./ops.mjs";
-import { playsCaptionsOnly, presenterLine, withAvatar } from "./presenter.mjs";
+import { playsCaptionsOnly, presenterLine, withNarrator } from "./presenter.mjs";
 import { serveSource } from "./preview-capture.mjs";
 import { openBrowser } from "./runtime.mjs";
 
@@ -88,7 +88,7 @@ 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 = presenter ? withAvatar(html, presenter) : html;
+  const page = withNarrator(html, presenter, who);
   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 });