@hypersocial/decks-cli 0.9.10 → 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.10",
+  "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` |
@@ -308,6 +310,20 @@ its `##` heading.
 | `glass` | dark or busy slides: head and captions on one frosted panel |
 | `corner` | the slide is the point (a product shot, a chart, a demo): small head bottom-right, subtitles along the bottom |
 
+**Loading and buffering.** A deck opens on its loading card (the title and
+the presenter's still), and a line still loading shows as a small waiting
+pill. Once the deck has spoken, a line that stalls on the network for more
+than 0.3 s makes the slide play a short
+"signal" glitch in the deck's accents (`--accent-2` / `--accent-3`, else
+`--accent`; set `--hd-signal-1` / `--hd-signal-2` to choose others): the
+title's colour splits, thin scanlines and a slice pass over the slide, and a
+`SIGNAL // BUFFERING` tag sits in the top-left corner.
+Body text never moves; it calms to scanlines after 6 s and stops the moment
+sound plays. It never shows in thumbnails, exports, present mode or while the
+owner presents, and reduced motion gets a still dim and the tag. Where it
+doesn't fit the deck, turn it off with `data-loading="calm"` on the player tag
+(or on `<html>`, or `"loading": "calm"` in the manifest).
+
 Size it per slide with `data-presenter-size="s|m|l|xl"` on the `<section>`
 (0.7×, 1×, 1.3×, 1.6× the style's head; on the player tag it is the deck's
 default): `xl` on a slide with empty space, `s` on a busy product slide. Phones
@@ -431,8 +447,8 @@ slide that overflows a 390×844 phone.
 
 #### House style (preferences)
 
-Everything below is the owner's house style, not a rule: follow it by
-default, and depart from it when the brief asks for something else.
+The owner's house style, not rules: follow it by default; depart from it
+when the brief asks.
 
 **One idea per slide.** The title states the idea as a sentence a listener
 could repeat ("Narration renders in two minutes", not "Speed"). Everything
@@ -451,16 +467,15 @@ new sizes:
 | `--t-body` | 24px | 15px | list items, card text |
 | `--t-label` | 17px | 12px | kickers, sources, captions (mono, uppercase) |
 
-Nothing on a slide below 17px at stage size (a screenshot's frame chrome aside). A title over 28 characters needs
-`data-title-mobile`; write the short version as a real sentence.
+Nothing on a slide below 17px at stage size (a screenshot's frame chrome aside). A title over
+28 characters needs `data-title-mobile`, written as a real sentence.
 
 **Colour and contrast.** Three colours do the work: `--ink`, `--paper` and one
-`--accent` (a second, `--accent-2`, only for a chart's other series, an
-illustration or a placeholder face). Text is ink on paper or accent, or paper on ink: never accent
+`--accent` (`--accent-2` only for a chart's second series or a placeholder
+face). Text is ink on paper or accent, or paper on ink: never accent
 on paper, never grey on a colour. Alternate slide grounds (`on-accent`,
 plain, `on-ink`) so the slide changes read, and keep every number, source and
-label at full contrast. Change the palette and fonts once, in `:root`; every
-layout reads them.
+label at full contrast. Set the palette and fonts once, in `:root`.
 
 **Start from the brand.** The account keeps a brand: colours, fonts, a logo,
 a presenter style and a design.md (voice, do and don't). `deck new` and
@@ -468,16 +483,14 @@ a presenter style and a design.md (voice, do and don't). `deck new` and
 it first (`hyperdecks brand show --json`, `get_brand`) and write in its voice.
 An explicit request for this deck wins over the brand; `--no-brand`
 (`brand: false`) starts from the template's look. No brand yet? Offer to
-import it from what they already have: `hyperdecks brand import
-<url|file.pptx|file.pdf|deck-slug>` (`import_brand`) reads the real colours,
-fonts and logo (a PowerPoint's theme exactly) and returns a preview link, a
-sample slide in that brand, and a token. Always show them the preview and
-ask; save with `brand set --draft <token>` (`set_brand { draft }`) only after
-they say yes.
-To change it in words ("darker accent, serif titles"), `hyperdecks brand
-revise "<change>"` (`revise_brand`) gives a draft and preview the same way.
-Every brand save is kept in its history: `brand history` (`brand_history`)
-lists the last changes and `brand undo [<version>]` (`undo_brand`) goes back.
+import it: `hyperdecks brand import <url|file.pptx|file.pdf|deck-slug>`
+(`import_brand`) reads the real colours, fonts and logo (a PowerPoint's theme
+exactly) and returns a preview link of a sample slide and a token. Show them
+the preview; save with `brand set --draft <token>` (`set_brand { draft }`)
+only after they say yes.
+To change it in words, `brand revise "<change>"` (`revise_brand`) gives a
+draft and preview the same way; `brand history` (`brand_history`) lists past
+saves and `brand undo [<version>]` (`undo_brand`) goes back.
 
 **Fonts: pick a pairing.** Fonts load from Google Fonts. Use one of the
 curated pairings below (display for titles, body for text, mono for kickers
@@ -489,13 +502,19 @@ saves one.
 **Textures, icons, pictures:** the `look` topic (one texture, one icon set
 from `search_icons` or `generate_icon_set`, a picture on every other slide).
 
-**Pick the layout from what the slide says.** Each layout's file in
-`templates/layouts/` opens with its slot side, presenter and the cues that
-suit it.
+**Pick the layout from what the slide says** (each file in
+`templates/layouts/` opens with its slot, presenter and cues).
+
+**The cover never puts text on the picture.** The title and lead sit on a
+solid ground, never on a picture or one faded
+with a gradient `mask-image` (`check` warns).
 
 | Layout | Use it for | Presenter, moves |
 |---|---|---|
-| `hero` | the opening, a section opener; the presenter is the visual, no `.art` unless it shows the real subject (check fails while the placeholder `<div class="art">` is in: swap it for an `<img class="art">` or delete it) | stage, bottom-right; `[wave]`, `[look: h1]` |
+| `hero` | the default cover, a section opener: title on the ground, the real subject framed beside it (no `.art`: the presenter is the visual) | stage; `[wave]`, `[look: h1]` |
+| `cover-band` | the picture is the story: full bleed, title on a panel | as `hero` |
+| `cover-poster` | a wide scene: picture on top, title below | as `hero` |
+| `cover-type` | no real picture yet: type only, presenter large | as `hero` |
 | `number` | one number with its source: proof, traction, a delta | stage; `[look: #<id>-figure]` as it is said |
 | `product` | a screenshot in a browser frame (`.frame.card` for a phone) with the point beside it | stage; `[look: #<id>-frame]`, `[reveal: #<id>-callout]` |
 | `split` | the workhorse: a real picture (phone, laptop, 16:9) beside sticker, title, three ticks | stage, bottom-left; `[look: #<id>-frame]`, `[go: #<id>-t1]` … `t3` |
@@ -631,7 +650,7 @@ an app icon or a face), `.ticks`, `.panel`, `.pill`, `.frame.card` (a phone),
 `<concrete subject>, <setting>, <medium: e.g. editorial photo, soft daylight>,
 palette <ink hex> <accent hex> <paper hex>, no text, no logos`
 (`generate_image { brand: true }` adds the palette and the "no text" for
-you). Generate at the slide's shape (wide for a hero), in one batch.
+you). Generate at the slide's shape (16:9; near-square for the hero), in one batch.
 
 **Slide recipes.** Opener: `on-accent` + `bg-corner`, the logo
 or a few app-icon stickers, one display line. Product or feature: `split`
@@ -764,6 +783,8 @@ you do).
   clip that says "Minimoji" but is transcribed as "Moji" needs
   `normalize: moji=minimoji`, and with a second entry
   `normalize: moji=minimoji, dash=D.A.S.H.` (one line, not a YAML list).
+  British and American spellings of a word (centre/center, colour/color,
+  organise/organize, travelled/traveled) already pass: no entry needed.
 - Write a narrator's name as it is spoken when the two differ, or leave it to
   the narrator's spoken name: `narrator list` shows it, and narrate reads
   "D.A.S.H." as "Dash" (captions keep what you wrote).
@@ -825,7 +846,8 @@ with the player's `hyperdecks.ai` script tag. Messages and what to do:
 | `forbidden phrase` | remove it from the page, script or narration |
 | `slide <id>: needs a data-note` / ⚠ `no data-note` | add the source (required on a `data-kind="pitch"` deck and with `--strict`) |
 | `slide <id>: title … needs a data-title-mobile` | add a shorter title |
-| `slide <id>: the hero's art` / `the product screenshot` / `the chart … is still the layout's placeholder` | make the real file (`gen-image`, `screenshot <url>`, `chart <spec.json>`) and swap the element for the `<img>` the message names; or delete the hero's `<div class="art">` for no art |
+| `slide <id>: the hero's art` / `the cover's picture` / `the product screenshot` / `the chart … is still the layout's placeholder` | make the real file (`gen-image`, `screenshot <url>`, `chart <spec.json>`) and swap the element for the `<img>` the message names; or delete the hero's `<div class="art">` for no art (on `cover-band` / `cover-poster`, switch to `cover-type` instead) |
+| ⚠ `slide <id>: the … cover fades its picture into the ground with a mask-image` | the old hero's look: the title sits on picture and colour mixed. Move the deck's opening to a current cover (`hero`, `cover-band`, `cover-poster`, `cover-type`), or drop the mask and keep the title off the picture |
 | `… presenter style "…" is not one of` | use stage, bubble, glass or corner |
 | `script.md line N: [go: …] matches nothing in slide <id>` | fix the selector, or add the element to that slide |
 | `… transition "…" is not one of` | use drift, cut, push, wipe, zoom `<selector>`, morph or fly |
@@ -992,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

@@ -46,9 +46,11 @@ makes the hello deck; continue from step 5 below.
    `upload_deck_asset` for a picture the user gave you (a URL, or a file they
    uploaded). Each returns a hosted URL: put that URL in the HTML. A hosted deck
    has no folder, so a relative path like `img/a.png` is an error. The
-   layouts' stand-ins (hero's `<div class="art">`, product's
+   layouts' stand-ins (the covers' `<div class="art">`, product's
    `<div class="shot">`, chart's placeholder `<svg>`) fail `check_deck` until
    you swap each for an `<img>` of its real file, or delete the hero's art.
+   Open on a cover (`hero`, `cover-band`, `cover-poster` or `cover-type`,
+   deck_guide topic layouts) and never put the title or lead on the picture.
    Icons: one set per deck (`look` topic): `search_icons { query }` for real
    line icons as inline `<svg>` in `currentColor`, or one `generate_icon_set`.
    For motion, `generate_video` (poll `check_video_job`): `loop: true` for a
@@ -126,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/brand.mjs

@@ -118,6 +118,21 @@ export function cleanBrand(brand) {
   return { name, colors, fonts, logoUrl, presenterStyle, hasDesignMd };
 }
 
+// The templates' own ink, paper and accent (layouts/_deck.html, narrated-deck.html), for a brand that sets only some colours.
+const TEMPLATE_INK = "#0b0b0f", TEMPLATE_PAPER = "#fafaf7", TEMPLATE_ACCENT = "#ffda1b";
+// WCAG relative luminance and contrast ratio of two #rgb / #rrggbb colours.
+function luminance(hex) {
+  const h = hex.replace("#", ""), full = h.length === 3 ? [...h].map((c) => c + c).join("") : h.slice(0, 6);
+  const [r, g, b] = [0, 2, 4].map((i) => parseInt(full.slice(i, i + 2), 16) / 255).map((c) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4));
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+export const contrast = (a, b) => { const [x, y] = [luminance(a), luminance(b)].sort((m, n) => n - m); return (x + 0.05) / (y + 0.05); };
+// Which of ink and paper the text on the accent is: ink unless it falls under 4.5:1 and paper reads better.
+export function accentInk(accent, ink, paper) {
+  const onInk = contrast(accent, ink);
+  return onInk < 4.5 && contrast(accent, paper) > onInk ? "paper" : "ink";
+}
+
 const escapeAttr = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 const fontStack = (family, role) => `"${family}", ${FALLBACK[role]}`;
 const LOGO_CSS = `
@@ -141,6 +156,10 @@ export function applyBrand(html, brand) {
     block = decl.test(block) ? block.replace(decl, (_, k) => `${k}${value}`) : block.replace(/\s*\}$/, (end) => ` ${name}: ${value};${end}`);
   };
   for (const [k, v] of Object.entries(b.colors)) set(CSS_VAR[k], v);
+  // Text on an accent ground reads --accent-ink (ink by default): a dark accent
+  // that ink cannot be read on takes the paper instead, so a cover on the accent stays legible.
+  const { accent = TEMPLATE_ACCENT, ink = TEMPLATE_INK, paper = TEMPLATE_PAPER } = b.colors;
+  if ((b.colors.accent || b.colors.ink || b.colors.paper) && accentInk(accent, ink, paper) === "paper") set("--accent-ink", "var(--paper)");
   if (b.fonts.body) set("--font", fontStack(b.fonts.body, "body"));
   if (b.fonts.mono) set("--mono", fontStack(b.fonts.mono, "mono"));
   if (b.fonts.display) {

package/src/checkRules.mjs

@@ -72,6 +72,7 @@ export const MESSAGES = {
   transitionStale: (where, script, manifest) => `${where}: script.md says transition "${script}" but the manifest has "${manifest}": run \`hyperdecks narrate\` so the player gets it`,
   flyTwice: (ids) => `fly is for the deck's one big moment, but slides ${ids.join(", ")} all use it`,
   // Warnings from the look topic (deck_guide look): the deck passes, but a person should look.
+  coverFade: (where, layout) => `${where}: the ${layout} cover fades its picture into the ground with a mask-image, so the title sits on a mix of picture and colour that is hard to read: keep the text off the picture (layouts hero, cover-band, cover-poster or cover-type; deck_guide topic layouts)`,
   fewPictures: (shown, total) => `only ${shown} of ${total} slides show a picture (a screenshot, a recording, a photo, a chart); aim for a real one on every other slide (deck_guide topic look)`,
   presenterGutter: (where, decl) => `${where}: ${decl} keeps a right gutter for the presenter; leave that corner to the slide's .narration-slot so a deck without a presenter can use it (deck_guide topic look)`,
   mixedIcons: (sets) => `the deck mixes icon sets (${sets.join(" and ")}); keep one set per deck (deck_guide topic look)`,
@@ -316,6 +317,19 @@ export function slides(html) {
   });
 }
 
+// Each slide's titles written short for phones: { id, titles: [{ desktop, phone }] },
+// only where the phone text differs. The player swaps data-title-mobile in below
+// 650px, so review must not read the shorter phone title as cut off.
+export function mobileTitles(html) {
+  return slides(html).map(({ id, body }) => ({
+    id,
+    titles: [...body.matchAll(/<([a-z][\w-]*)\b([^>]*\sdata-title-mobile\s*=[^>]*)>([\s\S]*?)<\/\1>/gi)]
+      .map(([, , attrs, inner]) => ({ desktop: textOf(inner), phone: attr(attrs, "data-title-mobile") }))
+      .filter((t) => t.phone != null && decode(t.phone).trim() && decode(t.phone).trim() !== t.desktop)
+      .map((t) => ({ desktop: t.desktop.slice(0, 200), phone: decode(t.phone).trim().slice(0, 200) })),
+  })).filter((s) => s.id && s.titles.length);
+}
+
 // The player tag also carries the deck's declarations: data-silent (no
 // narration, on purpose) and data-kind="pitch" (every slide sources its facts).
 // The check reads what the deck says, never guesses from its content.
@@ -535,6 +549,14 @@ const PLACEHOLDERS = [
     layout: "l-hero", tag: "div", cls: "art", what: "the hero's art", img: '<img class="art" src="…" alt="">, or delete the div for no art (the presenter is the visual)',
     how: { hosted: "make a picture of the real subject with generate_image", cli: "make a picture of the real subject with `hyperdecks gen-image \"<prompt>\"`" },
   },
+  {
+    layout: "l-cover-band", tag: "div", cls: "art", what: "the cover's picture", img: '<img class="art" src="…" alt="">, or use the cover-type layout for no picture',
+    how: { hosted: "make a wide picture of the real subject with generate_image", cli: "make a wide picture of the real subject with `hyperdecks gen-image \"<prompt>\"`" },
+  },
+  {
+    layout: "l-cover-poster", tag: "div", cls: "art", what: "the cover's picture", img: '<img class="art" src="…" alt="">, or use the cover-type layout for no picture',
+    how: { hosted: "make a wide picture of the real subject with generate_image", cli: "make a wide picture of the real subject with `hyperdecks gen-image \"<prompt>\"`" },
+  },
   {
     layout: "l-product", tag: "div", cls: "shot", what: "the product screenshot", img: '<img class="shot" src="…" alt="…">',
     how: { hosted: "capture the real page with capture_url", cli: "capture the real page with `hyperdecks screenshot <url>`" },
@@ -814,10 +836,27 @@ export function lookWarnings(html) {
     if (iconImg(tag)) sets.add("image icons");
   }
   if (sets.size > 1) out.push(MESSAGES.mixedIcons([...sets].sort()));
-  out.push(...textureWarnings(all, html));
+  out.push(...textureWarnings(all, html), ...coverFadeWarnings(all, html));
   return out;
 }
 
+// Covers never put text on the picture. Where the text overlaps a picture can only be
+// measured by rendering, so this reads the one source pattern that always does: a cover
+// layout whose CSS fades its picture with a gradient mask-image (the old hero's look,
+// still inlined in decks made from it). A deck's own picture and text placement beyond
+// that is left to the layouts and the review.
+export const COVER_LAYOUTS = ["l-hero", "l-cover-band", "l-cover-poster", "l-cover-type"];
+function coverFadeWarnings(all, html) {
+  const css = [...uncommented(html).matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)].map((m) => m[1].replace(/\/\*[\s\S]*?\*\//g, "")).join("\n");
+  const faded = new Set();
+  for (const [, sel, body] of css.matchAll(/([^{}]*)\{([^{}]*)\}/g)) {
+    if (!/(?:^|;|\s)(?:-webkit-)?mask(?:-image)?\s*:[^;]*gradient\(/i.test(body)) continue;
+    for (const l of COVER_LAYOUTS) if (new RegExp(`\\.${l}(?![\\w-])`).test(sel)) faded.add(l);
+  }
+  if (!faded.size) return [];
+  return all.flatMap((s, i) => classes(s.tag).filter((c) => faded.has(c)).map((c) => MESSAGES.coverFade(`slide ${s.id || i + 1}`, c.slice(2))));
+}
+
 // Backgrounds (the look topic): the kit's textures are confined to the object they
 // back. The retired whole-slide textures warn rather than vanish silently (a deck made
 // before keeps their rules in its own inlined shell, where they still paint). Read from each slide's class attribute; a texture on a layout whose shell
@@ -832,10 +871,11 @@ const RETIRED_TEXTURES = {
 const SIGNATURES = ["bg-corner", "bg-mark"];
 export const MAX_SIGNATURE_SLIDES = 3;
 const BUSY_LAYOUTS = ["l-number", "l-features", "l-team", "l-timeline", "l-compare"]; // full-width content: nothing to back
+const PICTURE_COVERS = ["l-cover-band", "l-cover-poster"]; // the picture is the ground: a texture would only sit under it
 export const TEXTURE_OFF = {
-  "bg-corner": ["l-split", "l-product", "l-chart", "l-quote", ...BUSY_LAYOUTS],
-  "bg-stage": ["l-split", "l-chart", "l-quote", "l-closer", ...BUSY_LAYOUTS],
-  "bg-mark": ["l-split", "l-product", "l-chart", "l-phones", ...BUSY_LAYOUTS],
+  "bg-corner": ["l-split", "l-product", "l-chart", "l-quote", ...BUSY_LAYOUTS, ...PICTURE_COVERS],
+  "bg-stage": ["l-split", "l-chart", "l-quote", "l-closer", ...BUSY_LAYOUTS, ...PICTURE_COVERS, "l-cover-type"],
+  "bg-mark": ["l-split", "l-product", "l-chart", "l-phones", ...BUSY_LAYOUTS, ...PICTURE_COVERS],
 };
 function textureWarnings(all, html) {
   const css = [...uncommented(html).matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)].map((m) => m[1].replace(/\/\*[\s\S]*?\*\//g, "")).join("\n");

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;