@hypersocial/decks-cli 0.9.9 → 0.9.11

package/README.md

@@ -58,6 +58,7 @@ whoami [--json]
 deck list [--json]
 deck stats <slug> [--json]
 deck open <slug>
+deck link <slug> [--json]   # the owner link: present or check your own deck, untracked
 
 share new <slug> <recipient> [--email e] [--note n] [--require-email] [--expires iso] [--limit n] [--qa] [--no-notify]
 share list <slug> [--json]

package/package.json

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

package/skills/hyperdecks/SKILL.md

@@ -146,14 +146,22 @@ Hyperdecks server; use the CLI where you have a shell and the tool otherwise.
 | PDF for a data room or attachment | `hyperdecks export <slug> --pdf [--notes] --out deck.pdf`, `hyperdecks export list` | `export_deck`, `list_exports` |
 | Video (MP4) for YouTube, LinkedIn or an attachment | `hyperdecks export <slug\|deck-dir> --video [--size 1080p\|720p\|4k] [--shape 16:9\|9:16\|1:1] [--title-card] [--end-card] [--no-captions] [--no-avatar] [--upload] --out deck.mp4`: records the narrated player in real time (a 4-minute deck takes about 5), avatar, voice and captions, no player chrome; a slug records the released copy, a deck folder its working copy; `--upload` lists it with the deck's exports | `export_deck { kind: "mp4" }` renders it on our render worker (the dashboard's Export → Video); poll `check_export`, or `hyperdecks export status <exportId>` |
 | Import only | `hyperdecks import <file> --slug <slug>` | `import_deck_from_url` |
-| One more link | `hyperdecks share new <slug> "<name>" [--no-forward]` | `create_share` (`allowForward`) |
+| One more link | `hyperdecks share new <slug> "<name>" [--no-forward] [--pace auto\|slide\|step]` | `create_share` (`allowForward`, `pace`) |
 | 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` |
+| 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` |
 | What one person watched | `hyperdecks engagement "<name>" --deck <slug> --json` | `recipient_engagement` |
 
+To present or check your own deck, use the owner link (`deck link`,
+`ownerUrl`): the released deck as recipients get it, for the owner only
+(signed in), with nothing tracked. Anyone else gets a sign-in notice, so a
+leaked owner link shows nothing. Its toolbar's Present (or H) hides the owner
+tools for a screen share. QA links are only for testing what a recipient sees;
+never make one to present on a call.
+
 Forwarding is on by default: a viewer can forward the deck to someone, which
 makes a child link tracked on its own ("Dana via Peter"; `share list` shows it
 indented under Peter's, `list_shares` gives `parentToken` and `forwardedBy`).
@@ -266,17 +274,27 @@ The deck contract (`check` enforces or warns on each line):
 <!-- topic: presenter -->
 #### Which presenter style
 
-**Who presents is set at release; leave the tag alone.** `deck new --narrated`
-writes `data-presenter="none"` on the player tag, and `release` (and
-`release_deck`) puts the narrator's face on the copy it publishes: your own
-narrator's avatar, or D.A.S.H.'s live head for a deck in D.A.S.H.'s voice. It
-says `presented by …` only when the published page has that face; otherwise
-it warns `releasing captions only` with the reason. To pick the face by hand,
-set both attributes: `data-presenter="head" data-avatar="…"`. D.A.S.H.'s is
+**The CLI writes the face into the tag; leave it alone.** `deck new --narrated`
+writes the narrator's face on the player tag (`data-presenter="head"
+data-avatar="…" data-presenter-from="narrator"`): the account's default
+narrator's, else D.A.S.H.'s. `deck narrator <slug> <name>` and `narrate`
+rewrite it to the narrator's face and print `presenter: …, written to
+index.html`; `deck narrator <slug> none` (or `deck new --captions-only`)
+writes captions only on purpose. So the file plays with its face however it is
+opened, a static server included. `release` (and `release_deck`) follows the
+narrator: a `data-presenter-from="narrator"` face is replaced by the current
+narrator's (your own narrator's avatar, or D.A.S.H.'s live head for a deck in
+D.A.S.H.'s voice). It says `presented by …` only when the published page has
+that face; otherwise it warns `releasing captions only` with the reason. To pick
+the face by hand, set both attributes and no `data-presenter-from`:
+`data-presenter="head" data-avatar="…"`. D.A.S.H.'s is
 `data-presenter="head" data-avatar="https://hyperdecks.ai/player/v1/dash-avatar.json"`
 (it loads from any host). `data-presenter="head"` with no `data-avatar` plays
-captions only, and so does a `data-avatar` beside `data-presenter="none"`.
-`check` warns on both, and `release` leaves a hand-set `data-avatar` alone.
+captions only, and so does a `data-avatar` beside `data-presenter="none"`, and
+so does a plain `data-presenter="none"` from an older scaffold.
+`check` warns on all three, and `release` leaves a hand-set `data-avatar` alone.
+A hosted draft (`new_deck`) stores the tag as the template wrote it; its draft
+link and `release_deck` add the narrator's face, so `check_deck` does not warn on its plain none.
 
 Set the deck's on the player tag (`data-presenter-style="stage"`) or in
 script.md's front matter (`presenterStyle: stage`); override one slide with
@@ -290,6 +308,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
@@ -413,8 +445,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
@@ -433,16 +465,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
@@ -450,16 +481,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
@@ -471,13 +500,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` |
@@ -492,7 +527,7 @@ suit it.
 
 **Phones and backgrounds.** One phone: `product`'s `.frame.card`; a flow of
 two to four: `phones` (`--tilt`, `--shadow` on a card). A few slides at most:
-`bg-dots` (never under text), a `.deco` of inked tiles.
+`bg-stage` (never under text), a `.deco` of inked tiles.
 
 Presenter style follows the deck (step 2): `stage` when the presenter carries
 the story (the layouts keep the slot's corner clear); `corner` where a big
@@ -552,7 +587,8 @@ still.
 - `[go]` when the narration walks through items (cards, milestones, people,
   the action on the closer): one `go` per item at the word that starts it,
   then `[go: slot]` before the slide ends. Never more than one `go` per
-  sentence; never a `go` on a slide in `corner` style.
+  sentence; never a `go` on a slide in `corner` style. A `go` keeps off
+  the picture; with no room it stays home.
 - `[look]` for a glance: the title as it is read, a number as it is said, a
   screenshot as the narration turns to it.
 - `[reveal]` for the one detail that should not be read before it is said (a
@@ -564,8 +600,8 @@ still.
 <!-- topic: look -->
 #### Look: textures, icons, pictures
 
-What the house decks do that a plain agent deck doesn't. Decide these three
-once per deck, before writing slides, and say them in your plan.
+What the house decks do. Decide these three once per deck, before writing
+slides, and say them in your plan.
 
 **1. A picture on at least every other slide**, the most real one you have:
 
@@ -579,18 +615,22 @@ once per deck, before writing slides, and say them in your plan.
 No product to show (a plan, a strategy)? Make the slides visual with type
 and the kit below: a `number` slide, stickers, ticks on a `panel`.
 
-**2. One texture**, on two or three slides (an opener, a closer, a slide
-with a visual), never under body text. On the section:
+**2. Plain grounds; texture only behind objects.** Alternate plain,
+`on-tint`, `on-tint-2`, `on-tint-3`, `on-accent`, `on-ink`. On the section:
 
 | Class | Looks like | For |
 |---|---|---|
-| `bg-lines` | diagonal speed lines fading toward `--fade-at` | product slides, beside a picture |
-| `bg-halftone` | a corner of halftone dots | openers, numbers |
-| `bg-rays` | rays from `--rays-at` | an opener or a closer |
-| `bg-dots` | a fading dot grid | a phones row |
-
-Grounds carry the rest: alternate `on-accent`, plain, `on-ink` and the soft
-washes `on-tint`, `on-tint-2`, `on-tint-3` so each slide change reads.
+| `bg-pool` | a soft light behind the picture | any picture |
+| `bg-corner` | a halftone quarter-disc, top-right | cover, closer |
+| `bg-stage` | a dot plate under a mockup | product, phones |
+| `bg-mark` | the slide number, huge, faint (`--mark:'04'`) | cover, opener, closer |
+
+- One signature per deck (`bg-corner` or `bg-mark`), on three slides at
+  most: the cover, an opener or the ask, the closer.
+- `bg-pool` and `bg-stage` are picture helpers: only beside an image.
+- Nothing under text, a chart or a photo; the presenter's corner stays clear.
+- Your own is fine in the deck's `<style>`: tokens only, behind the content
+  in an isolated slide, off with nothing to back.
 
 **3. One icon set.** Pick one source and keep it for every icon in the deck:
 Lucide (`search_icons`, same `strokeWidth` throughout); or one
@@ -608,9 +648,9 @@ 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-rays` or `bg-halftone`, the logo
+**Slide recipes.** Opener: `on-accent` + `bg-corner`, the logo
 or a few app-icon stickers, one display line. Product or feature: `split`
 with a real screen. Proof: `number` (huge, sourced) or `chart`. Plan:
 `timeline` on a tint. People: `team` with real faces. Closer: `on-ink`, the
@@ -741,6 +781,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).
@@ -802,7 +844,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 |
@@ -840,6 +883,10 @@ browser (an agent reads the URL; `--json` prints it as one line).
 `release --qa` is not a preview: it needs a commit, and it changes what every
 link to this deck plays.
 
+Watch a draft with `hyperdecks play`: it shows the face the deck will ship
+with. A plain static server shows the file as written: the face named in the
+tag (the narrator's, since `deck new`, `deck narrator` and `narrate` write it
+there), or none for a tag that says `data-presenter="none"` (`check` warns).
 For the layout pass, serve the folder (`npx serve decks/<slug>` or `python3 -m http.server -d decks/<slug>`)
 and screenshot it with Playwright at 1440×900 and 390×844, every slide
 (`#scene=<id>`). Look at both: nothing clipped, the presenter and its captions

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
@@ -90,6 +92,11 @@ makes the hello deck; continue from step 5 below.
    only, when nobody chose that, is refused: hand the person its Add narrator
    link, or offer D.A.S.H., and pass `captionsOnly: true` only if they say so.
    The result's `presenter` names who presents.
+   To present or check your own deck (on a call, say), give the user its
+   owner link, `ownerUrl` from `list_decks` or `check_deck`: only they can
+   open it, signed in, and nothing is tracked; Present (or H) hides their
+   owner tools for a screen share. QA links are only for testing what a
+   recipient sees, not for presenting.
 10. Later: `list_shares` and `deck_stats` (both show the card),
    `activity_overview`; `email_embed { token }` for the HTML that pastes into an
    email as the deck's moving preview (it needs a recipient's link, not a QA

package/src/brand.mjs

@@ -8,7 +8,8 @@
 // only the tokens here touch the deck.
 
 // Weights each role loads: the templates set body text at 500, titles at 700
-// and labels in mono at 400/700. Every family below has these on Google Fonts.
+// and labels in mono at 400/700. Every pairing family has these on Google Fonts;
+// a display family outside the pairings loads what displayFace says it has.
 const ROLE_WEIGHTS = { display: "600;700", body: "400;500;700", mono: "400;700" };
 
 // 16 pairings, display + body + mono, each a family Google Fonts serves at the
@@ -32,8 +33,35 @@ export const FONT_PAIRINGS = [
   { id: "grotesk", display: "Schibsted Grotesk", body: "Work Sans", mono: "Roboto Mono", use: "Marketplaces and media brands; confident and newsy." },
 ];
 
-// Weights for families that do not have every role weight (load what exists).
-const FAMILY_WEIGHTS = { "Space Mono": "400;700", "DM Mono": "400;500", "Libre Baskerville": "400;700", "Courier Prime": "400;700", "Syne": "600;700" };
+// Weights for families that do not have every role weight (load what exists),
+// including single-weight display faces a brand may name (Google Fonts refuses
+// a stylesheet that asks for a weight the family lacks).
+const SINGLE_WEIGHT = ["Bangers", "Bebas Neue", "Anton", "Luckiest Guy", "Permanent Marker", "Pacifico", "Lobster", "Abril Fatface", "Alfa Slab One", "Righteous", "Press Start 2P", "Black Ops One", "Bungee", "Russo One", "Shrikhand", "Monoton", "Creepster", "Special Elite"];
+const FAMILY_WEIGHTS = {
+  "Space Mono": "400;700", "DM Mono": "400;500", "Libre Baskerville": "400;700", "Courier Prime": "400;700", "Syne": "600;700",
+  ...Object.fromEntries(SINGLE_WEIGHT.map((f) => [f, "400"])),
+};
+
+// The template's titles (700, -.045em) were tuned for the pairings' sans
+// display faces. Any other display face gets tracking 0; a face with a known
+// weight table is set at its heaviest weight. A face we know nothing about stays
+// at 700 and loads 400;700: Google Fonts' css2 serves whichever of the asked
+// weights exist (it fails only when none do), and the templates' font-synthesis:
+// none means a face without a 700 draws its real 400, never a faked bold.
+const SERIF_DISPLAY = new Set(["Fraunces", "Playfair Display", "Newsreader", "Libre Baskerville"]);
+const TUNED_DISPLAY = new Set(FONT_PAIRINGS.map((p) => p.display).filter((f) => !SERIF_DISPLAY.has(f)));
+// Any family a pairing names (display or body) has the display weights.
+const PAIRED_DISPLAY = new Set(FONT_PAIRINGS.flatMap((p) => [p.display, p.body]));
+
+// { weights, weight, tracking } for a display family: the weights to load, and
+// the --display-weight / --display-tracking to write (null: the template's).
+export function displayFace(family) {
+  const f = String(family ?? "").trim();
+  const weights = FAMILY_WEIGHTS[f] ?? (PAIRED_DISPLAY.has(f) ? ROLE_WEIGHTS.display : "400;700");
+  if (TUNED_DISPLAY.has(f)) return { weights, weight: null, tracking: null };
+  const heaviest = Math.max(...weights.split(";").map(Number));
+  return { weights, weight: heaviest === 700 ? null : String(heaviest), tracking: "0" };
+}
 
 const HEX = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
 // A Google Fonts family name: letters, digits and spaces (e.g. "Source Sans 3").
@@ -54,7 +82,7 @@ export function findPairing(id) {
 // The Google Fonts stylesheet URL for one family at the weights its roles use
 // (a family that is both display and body loads both roles' weights).
 export function googleFontsUrl(family, roles = "body") {
-  const wanted = [roles].flat().flatMap((r) => (ROLE_WEIGHTS[r] ?? "400;700").split(";"));
+  const wanted = [roles].flat().flatMap((r) => (r === "display" ? displayFace(family).weights : ROLE_WEIGHTS[r] ?? "400;700").split(";"));
   const weights = FAMILY_WEIGHTS[family] ?? [...new Set(wanted)].sort().join(";");
   return `https://fonts.googleapis.com/css2?family=${family.trim().replace(/ /g, "+")}:wght@${weights}&display=swap`;
 }
@@ -90,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 = `
@@ -113,9 +156,18 @@ 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) set("--display", fontStack(b.fonts.display, "display"));
+  if (b.fonts.display) {
+    set("--display", fontStack(b.fonts.display, "display"));
+    const face = displayFace(b.fonts.display);
+    if (face.weight) set("--display-weight", face.weight);
+    if (face.tracking) set("--display-tracking", face.tracking);
+  }
   let out = html.slice(0, root.index) + block + html.slice(root.index + root[0].length);
 
   const families = FONT_ROLES.filter((r) => b.fonts[r]).map((r) => [b.fonts[r], r]);

package/src/checkRules.mjs

@@ -63,6 +63,7 @@ export const MESSAGES = {
   gesture: (line, id) => `script.md line ${line}: [gesture: ${id}] is not one of the head's gestures: ${GESTURES.join(", ")}`,
   presenterUnfilled: (mode) => `the player tag says data-presenter="${mode}" but names no face (${mode === "head" ? "data-avatar" : "data-presenter-image"}), so as written it plays captions only. release puts the narrator's face on it; to set one by hand, D.A.S.H. is data-presenter="head" data-avatar="${DASH_AVATAR}" (deck_guide topic presenter)`,
   presenterKept: (mode) => `the player tag has a data-avatar but data-presenter="${mode ?? "none"}", so it plays captions only and release leaves it that way: set data-presenter="head" to show that face, or remove data-avatar so release adds the narrator's`,
+  presenterCaptions: () => `the player tag plays captions only as written (data-presenter="none" or none set), so the file served as is (npx serve, python3 -m http.server, the screenshot pass) shows no face: run \`hyperdecks deck narrator <slug> <name>\` (or narrate again) to write the narrator's face into index.html, or watch it with \`hyperdecks play <deck>\`; release adds the face either way. Captions only on purpose: \`hyperdecks deck narrator <slug> none\``,
   presenterSize: (where, value) => `${where}: data-presenter-size "${value}" is not one of ${PRESENTER_SIZES.join(", ")}; the presenter keeps its default size`,
   presenterStyle: (where, value) => `${where}: presenter style "${value}" is not one of ${PRESENTER_STYLES.join(", ")}`,
   transition: (where, value) => `${where}: transition "${value}" is not one of ${TRANSITIONS.join(", ")} (zoom takes a selector: "zoom #row")`,
@@ -71,9 +72,13 @@ 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)`,
+  retiredTexture: (where, cls, instead, inlined) => `${where}: ${cls} is a whole-slide texture the kit no longer ships ${inlined ? "(this deck still carries its rule, so it runs under the text)" : "(it ran under the text), so it paints nothing"}; ${instead} (deck_guide topic look)`,
+  tooManySignatures: (n) => `${n} slides carry a signature background (bg-corner or bg-mark); keep it to three at most: the cover, one opener or the ask, the closer (deck_guide topic look)`,
+  textureOff: (where, cls, layout) => `${where}: ${cls} does nothing on ${layout} (the shell switches it off there: nothing to back); remove it, or use bg-pool behind the picture (deck_guide topic look)`,
   // A layout's stand-in left in: `how` is the tool (hosted) or command (CLI) that makes the real file.
   placeholder: (id, what, el, how, img) => `slide ${id}: ${what} is still the layout's placeholder (${el}); ${how}, then put it in as ${img}`,
   // Warnings (check --layout): the deck still passes.
@@ -312,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.
@@ -531,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>`" },
@@ -810,6 +836,62 @@ 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), ...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
+// rule switches it off (TEXTURE_OFF, pinned to _deck.html by lib/deckLayouts.test.ts) did nothing, and a custom
+// slide (no l-* class) is never judged on that. Commented-out slides do not count.
+const RETIRED_TEXTURES = {
+  "bg-rays": "use a plain ground, or bg-corner on the cover and the closer",
+  "bg-lines": "use a plain ground, or bg-pool behind the picture",
+  "bg-halftone": "use bg-corner on the cover and the closer",
+  "bg-dots": "use bg-stage under the mockup or the phones",
+};
+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, ...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");
+  const inlined = (c) => new RegExp(`\\.${c}(?![\\w-])[^{}]*\\{`).test(css);
+  const out = [];
+  let signatures = 0;
+  all.forEach((s, i) => {
+    const where = `slide ${s.id || i + 1}`;
+    const cls = classes(s.tag);
+    for (const [c, instead] of Object.entries(RETIRED_TEXTURES)) if (cls.includes(c)) out.push(MESSAGES.retiredTexture(where, c, instead, inlined(c)));
+    if (SIGNATURES.some((c) => cls.includes(c))) signatures++;
+    const layout = cls.find((c) => /^l-[\w-]+$/.test(c));
+    if (!layout) return;
+    for (const [c, off] of Object.entries(TEXTURE_OFF)) if (cls.includes(c) && off.includes(layout)) out.push(MESSAGES.textureOff(where, c, layout));
+  });
+  if (signatures > MAX_SIGNATURE_SLIDES) out.push(MESSAGES.tooManySignatures(signatures));
   return out;
 }
 
@@ -970,8 +1052,14 @@ export async function checkSources({ html, script = "" }, opts = {}, { fetch: fe
   }
   warnings.push(...transitionWarnings(html, script, manifest), ...presenterSizeWarnings(html));
   // A narrated deck's tag that shows no face and says otherwise (a silent deck has no presenter).
-  const tagIssue = silent ? null : presenterTagIssue(html);
-  if (tagIssue) warnings.push(tagIssue.kind === "kept" ? MESSAGES.presenterKept(tagIssue.presenter) : MESSAGES.presenterUnfilled(tagIssue.presenter));
+  // A hosted draft plays only through its draft link and release_deck, which add the face, so a plain none is no issue there.
+  const found = silent ? null : presenterTagIssue(html);
+  const tagIssue = found?.kind === "captions" && opts.hosted ? null : found;
+  if (tagIssue) {
+    warnings.push(tagIssue.kind === "kept" ? MESSAGES.presenterKept(tagIssue.presenter)
+      : tagIssue.kind === "captions" ? MESSAGES.presenterCaptions()
+      : MESSAGES.presenterUnfilled(tagIssue.presenter));
+  }
   for (const t of walked.templates) warnings.push(MESSAGES.scriptTemplate(t.from, t.samples));
   for (const c of walked.computed) warnings.push(MESSAGES.scriptComputed(c.from, c.calls));
   if (opts.hosted) {