@hypersocial/decks-cli 0.2.2 → 0.3.0

package/README.md

@@ -2,12 +2,16 @@
 
 Command-line client for Hypersocial Decks live analytics and share management.
 
-Most users should install the friendlier package name:
+Most users should start with the friendlier package name:
 
 ```bash
-npx hyperdecks whoami
+npx hyperdecks init
 ```
 
+`init` signs you in, installs the skill into your agents, sets up a voice,
+builds and narrates a three-slide hello deck and prints its link. Re-running it
+resumes where it stopped; `--json --yes` is the agent form.
+
 This package targets production by default:
 
 ```bash
@@ -128,7 +132,7 @@ normalize: hyper desk=hyperdecks
 ---
 
 ## hello
-hold: 1.1
+hold: 1.5
 presenter: wave
 
 Hi, I'm Selçuk's mini avatar. [wave] This is Hyperdecks. [mood: excited]
@@ -137,6 +141,7 @@ Hi, I'm Selçuk's mini avatar. [wave] This is Hyperdecks. [mood: excited]
 - `## <slide-id>` is the slide's `<section id>` in `index.html`. Text before the first
   heading is notes for people and is ignored.
 - `hold`, `presenter` and `voice` lines directly under a heading are slide options.
+  `hold` is the pause in seconds after the line before the next slide (0.4 by default).
 - Sentences are the caption units, 4–85 characters each.
 - Stage tags (`[wave]`, `[mood: x]`, `[emote: x]`, `[reveal: x]`, `[play: x]`,
   `[pause: s]`, `[custom: name …]`) are not spoken. Each becomes a cue at the start

package/package.json

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

package/skills/hyperdecks/SKILL.md

@@ -11,6 +11,32 @@ Hyperdecks is the CLI and MCP surface for Hypersocial Decks live analytics,
 recipient links, and deck activity. Treat real recipient activity, live deck
 stats, customer-facing links, and "what happened" questions as production work.
 
+## First run
+
+When `hyperdecks whoami` says not authenticated, or `hyperdecks voice list`
+shows no ready voice, run the first-run command instead of working around it:
+
+```bash
+npx hyperdecks init --json --yes [--voice dash] [--name "<name>" --about "<one line>" --ask "<the ask>"]
+```
+
+It signs in, installs this skill, scaffolds a three-slide hello deck from the
+three answers, narrates it, releases one QA link and prints one JSON object
+(`status`, `steps`, `slug`, `deckDir`, `shareUrl`, `next`). Re-running it
+resumes where it stopped. Signed out, it first opens the sign-in page in the
+user's browser and waits up to 3 minutes: tell them to finish signing in there
+(a new account can be made on that page) before you run it, or have them run
+`npx hyperdecks login` first. Inside a git repository it puts the deck in
+`~/hyperdecks` rather than committing into that repository; `--dir` picks the
+folder. Relay every step whose `status` is `needs-human` to the user, word for
+word, and wait for them:
+
+- deck: it needs `--name`, `--about` and `--ask`; ask the user, do not invent them;
+- voice: cloning needs them to type their consent in a terminal (`hyperdecks
+  voice clone <file> --name <name>`), or to agree to the statement before you
+  call `clone_voice`. Never type or confirm consent for them. `--voice dash`
+  lets D.A.S.H., a character voice, present instead.
+
 ## Target Selection
 
 - Prefer production for real-world questions and actions. The published CLI is
@@ -81,6 +107,7 @@ Write `decks/<slug>/evidence.md` as you go: one row per fact with the slide, the
 claim, the source (file path, thread, doc title) and its date. Never put a
 number on a slide that has no row.
 
+<!-- topic: format -->
 ### 2. Scaffold
 
 ```bash
@@ -126,6 +153,7 @@ The deck contract (`check` enforces each line):
 - Local images and files sit inside the deck folder and are referenced
   relatively (`img/chart.png`). Hosted images (`gen-image` URLs) are fine too.
 
+<!-- topic: presenter -->
 #### Which presenter style
 
 Set the deck's on the player tag (`data-presenter-style="stage"`) or in
@@ -144,6 +172,45 @@ Below 650 px stage and glass become corner on their own. Run
 `hyperdecks check <deck> --layout` to be warned about any slide whose presenter
 would cover its title.
 
+<!-- topic: transitions -->
+#### Transitions
+
+Every slide enters with `drift` unless it says otherwise. Use another only
+where the slide's job matches its "use for"; never hand-write slide-change
+animation in the deck's own JS (it fights the player's timing).
+
+| Transition | Use for | What it does |
+|---|---|---|
+| `drift` (default) | most slides | the old slide drifts out, the new one in, its parts arriving title first |
+| `cut` | a punchline, a fast beat | instant |
+| `push` | the next step in a sequence | the new slide slides over; the old one sinks back and darkens |
+| `wipe` | a new section | a band in the deck's second colour, then one in ink, sweeps across and leaves the new slide |
+| `zoom <selector>` | going into the detail of one row, bar or card | the new slide opens out of that element on the slide before |
+| `morph` (carry over) | a number or title on both slides | the element travels into its new place and size |
+| `fly` | the deck's one big reveal | the presenter flies across and the new slide appears behind it |
+
+Set the deck's in script.md's front matter (`transition: drift`) or on the
+player tag (`data-transition`); a slide's under its `##` heading
+(`transition: push`) or as `data-transition` on its `<section>`, which wins.
+A slide's transition is how it enters; going back plays it in reverse.
+A `transition:` in script.md reaches the player through the manifest, so it
+takes effect after `narrate` (release runs it; nothing re-renders);
+`data-transition` in index.html takes effect at once. Zoom
+names its target on the slide before: `transition: zoom #dash-row`. Morph
+pairs elements by name: put `data-morph="saved"` on the element on both
+slides. Reduced motion turns every one into a short crossfade, and the
+narration never waits for a transition.
+
+`check` fails an unknown name, a `zoom` with no selector or one that matches
+nothing on the slide before, a `morph` with no `data-morph` name on both
+slides, and a second `fly`. It warns when a deck uses more than two kinds
+besides its default: pick one or two and keep them for the same job.
+
+Viewers can poke the live head: a click or tap makes it react (an "oof", a
+flinch) and a drag pulls it a little before it springs back, without pausing
+the narration.
+
+<!-- topic: design -->
 ### Design: make it look good
 
 A narrated deck is only as convincing as it looks. Design before you write the
@@ -256,6 +323,7 @@ If review cannot run (no credits, the service is down), say so to the user and
 do the step 6 screenshot pass yourself as the reviewer: the same desktop and
 phone screenshots, the same `fix` bar.
 
+<!-- topic: script -->
 ### 3. Write slides and script
 
 - One idea per slide; the title states it.
@@ -264,7 +332,7 @@ phone screenshots, the same `fix` bar.
 - Narration: short phrases, each sentence one caption of 4 to 85 characters
   (two lines in the bubble). Aim for 2.5 to 3 minutes in all; `maxTotalSeconds`
   in the front matter is the cap check uses (180 in the scaffold).
-- Holds: 1.1 s by default; `hold: 2` under the heading on interactive slides.
+- Holds: 0.4 s by default. Give a slide `hold: 1.5` when the viewer needs time to read a number, a chart or a reveal, and `hold: 2` on interactive slides.
 - Cues: `[reveal: #id]` reveals `.reveal#id` at the word before it; also
   `[wave]`, `[mood: excited]`, `[pause: 0.5]`, `[custom: name]`.
 - Moves, to point at part of a slide: `[go: <selector>]` flies the presenter
@@ -305,6 +373,7 @@ A slide fails when the transcript does not match the script: read the error,
 reword the sentence (spell numbers and names the way they are said, or add a
 `normalize:` entry), and narrate again; only that slide re-renders.
 
+<!-- topic: check -->
 ### 5. Check
 
 ```bash
@@ -340,6 +409,12 @@ an internal codename). Messages and what to do:
 | `slide <id>: title … needs a data-title-mobile` | add a shorter title |
 | `… 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 |
+| `slide <id>: zoom target "…" matches nothing on the slide before it` | point the zoom at an element of the previous slide, or give that element the id |
+| `slide <id>: morph needs an element with the same data-morph` | put `data-morph="<name>"` on the carried element on both slides, or use drift |
+| `script.md says transition "…" but the manifest has "…"` | run `narrate` (no audio re-renders), or release, which runs it |
+| `fly is for the deck's one big moment` | keep `fly` on one slide; use drift or push on the others |
+| ⚠ `N kinds of transition besides the default` | use one or two kinds, each for its own job |
 | `slide <id>: its content runs …px past the slide on a 390×844 phone` | trim that slide on phones: smaller type, fewer items, or hide decoration in its `@media (max-width: 650px)` rules (an `#id` rule outranks them; restate it there) |
 | ⚠ `slide <id>: the … presenter would overlap the title` | move that slide's `.narration-slot`, pad the text away from it, or use `corner` |
 
@@ -396,6 +471,16 @@ hyperdecks activity --deck <slug> --limit 10
 Tell the user who opened it, how far they got and whether the narration
 finished. QA links never count.
 
+### Hosted source (chat agents and the connector)
+
+A deck can also live on Hyperdecks with no folder: chat agents build it through
+the hosted MCP (`deck_guide`, `new_deck`, `get_deck_source`, `write_deck_source`,
+`upload_deck_asset`, `check_deck`, `release_deck`; see `chat.md`). Move between
+the two with `hyperdecks source pull <slug> [dir]` (the hosted draft into a
+folder) and `hyperdecks source push <slug> [dir]` (a folder's files back to the
+draft), `hyperdecks asset add <slug> <file|url>` for an image, `hyperdecks guide
+[topic]` for these sections, and `--hosted` on `deck new`, `check` and `release`.
+
 ## Safety
 
 - For read-only inspection, run commands directly and summarize the important

package/skills/hyperdecks/chat.md

@@ -0,0 +1,49 @@
+# Hyperdecks from a chat app (hosted MCP)
+
+You are building a narrated deck through the Hyperdecks connector: no terminal,
+no git, no folder. The deck's files (`index.html`, `script.md`, `evidence.md`)
+live on Hyperdecks as a draft; you read and edit them with tools, and nothing
+reaches a recipient until `release_deck`. Topics: call `deck_guide` with
+`format`, `script`, `design`, `layouts`, `presenter`, `transitions` or `check`
+before the step that needs it.
+
+## The loop
+
+1. `deck_guide` (this page), then `deck_guide { topic: "layouts" }` to pick slides.
+2. `new_deck { slug, title, layouts }`: registers your draft and returns the
+   full text of every file plus a `previewUrl` (the draft, untracked).
+3. Images: `generate_image`, `render_chart`, `capture_url`, or
+   `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.
+4. `write_deck_source` to change a file: `edits: [{ find, replace }]` with
+   exact text that occurs once (copy it from `get_deck_source`), or `content`
+   to replace the file. Pass `baseRev` (the `rev` you last read) so a
+   concurrent edit fails instead of being overwritten.
+5. `check_deck { slug }` until it passes (the narration errors clear in step 6).
+6. `narrate_deck { slug }` with no `script` narrates the stored `script.md`;
+   poll `check_narration_job` until `done`. The draft's player tag then has its
+   `data-manifest`. No voice of their own yet? Pass `voice: "dash"`.
+7. `check_deck { slug }` again, then `review_deck { slug, draft: true }` and
+   `check_review_job`: it shoots desktop and 390×844 phone frames, which is how
+   you catch a slide that overflows a phone (the hosted check cannot measure
+   layout).
+8. `release_deck { slug, qa: true }` gives the user a QA link to watch first.
+   `release_deck { slug, recipients: [{ recipient, email }] }` makes one
+   tracked link each. Release creates live links: confirm the recipients with
+   the user before you call it.
+9. Later: `list_shares`, `deck_stats`, `activity_overview`.
+
+## Rules that matter
+
+- Every slide is `<section class="slide" id="…" data-note="<source of its facts>">`,
+  in the same order as the `## <id>` blocks in `script.md`.
+- Keep the player script tag and the `<style data-hd-loading>` block the
+  scaffold wrote; never write `data-manifest` yourself.
+- Edit the draft freely: recipients keep seeing the last release until you call
+  `release_deck` again. A release is refused when the check fails, when
+  narration is stale (narrate again first), or when the draft changed after
+  the check.
+- Files are capped at 800 KB each: use hosted image URLs, never inline base64.
+- Facts come from the user's material; put the source of each in `evidence.md`
+  and the slide's `data-note`.

package/src/check.mjs

@@ -6,279 +6,13 @@
 // The rules are pure (htmlErrors, manifestErrors, timelineErrors); checkDeck does
 // the I/O: it reads the deck folder, fetches the manifest the player names and
 // every clip's audio and timeline. `fetch` and `exists` are injectable for tests.
+// The rules themselves live in checkRules.mjs (no Node imports, shared with the
+// hosted check); this file adds the folder I/O and the Chromium measurements.
 import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
 import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { PHONE, PRESENTER_FOOTPRINT, checkSources, overlapWarnings, phoneOverflowErrors, slideStyles, stageSize, MESSAGES } from "./checkRules.mjs";
 
-export const PLAYER_V1 = "https://decks.hypersocial.ai/player/v1/player.js";
-export const DEFAULT_MAX_DURATION = 180;
-export const MOBILE_TITLE_CHARS = 28;
-export const CAPTION_MIN_CHARS = 4;
-export const CAPTION_MAX_CHARS = 85;
-// Same names as PRESENTER_STYLES in lib/deckManifest.ts (the published CLI cannot import it).
-export const PRESENTER_STYLES = ["stage", "bubble", "glass", "corner"];
-
-export const MESSAGES = {
-  noPlayer: () => `no player script: add <script type="module" src="${PLAYER_V1}" data-manifest="…">`,
-  player: (src) => `player script must be ${PLAYER_V1} (got ${src})`,
-  noManifest: () => "the player script has no data-manifest: run `hyperdecks narrate <deck-dir>`, which sets it",
-  manifestUnavailable: (url, why) => `manifest ${url} could not be read (${why})`,
-  noSlides: () => 'no slides: each slide is a <section class="slide" id="…">',
-  noLoading: () => "no loading state: copy the <style data-hd-loading> block and the lines above it from the narrated template into <head>, and set --hd-ground to the first slide's colour",
-  clipField: (id, field) => `clip ${id}: ${field}`,
-  noCaptions: (id) => `clip ${id}: timeline has no captions`,
-  order: (slides, clips) => `slide ids (${slides.join(", ")}) must equal the manifest clip ids (${clips.join(", ")}), in order`,
-  total: (sum, declared) => `clip durations plus holds add up to ${sum}s but the manifest declares totalDuration ${declared}s`,
-  cap: (total, cap) => `narration runs ${total}s, over the ${cap}s cap (aim for 150 to 180 s)`,
-  url: (id, key, url, why) => `clip ${id}: ${key} ${url} ${why}`,
-  timing: (id, i, start, end, duration) => `clip ${id}: caption ${i + 1} runs ${start}s to ${end}s, outside 0 ≤ start < end ≤ ${duration}s + 0.1`,
-  words: (id) => `clip ${id}: captions do not cover the clip text, or a caption has no timed words`,
-  captionLength: (id, i, text) => `clip ${id}: caption ${i + 1} is ${text.length} characters ("${text}"); captions must be ${CAPTION_MIN_CHARS} to ${CAPTION_MAX_CHARS}`,
-  localRef: (ref) => `local reference does not resolve: ${ref}`,
-  outsideRef: (ref) => `local reference leaves the deck folder: ${ref}`,
-  forbidden: (phrase, where) => `forbidden phrase "${phrase}" appears in ${where}`,
-  note: (id) => `slide ${id}: needs a data-note naming the source of its facts`,
-  mobileTitle: (id, title) => `slide ${id}: title "${title}" is over ${MOBILE_TITLE_CHARS} characters and needs a data-title-mobile`,
-  slideId: (n) => `slide ${n} has no id`,
-  selector: (line, cue, selector, id) => `script.md line ${line}: [${cue}: ${selector}] matches nothing in slide ${id}`,
-  presenterStyle: (where, value) => `${where}: presenter style "${value}" is not one of ${PRESENTER_STYLES.join(", ")}`,
-  // Warnings (check --layout): the deck still passes.
-  layoutUnchecked: (why) => `layout not checked: ${why}`,
-  overlap: (id, style, stage) => `slide ${id}: the ${style} presenter would overlap the title at ${stage}; move the .narration-slot or pick another style`,
-  // An error, though only check --layout can see it.
-  phoneOverflow: (id, px) => `slide ${id}: its content runs ${px}px past the slide on a ${PHONE.width}×${PHONE.height} phone; a slide must fit one screen without scrolling, so trim it or tighten its @media (max-width: 650px) rules`,
-};
-
-// The framed player's slide card on a phone (player.css): the screen less the
-// 52px masthead, the 56px dock and 8px gutters.
-export const PHONE = { width: 390, height: 844, card: { width: 374, height: 736 } };
-
-const uncommented = (html) => html.replace(/<!--[\s\S]*?-->/g, "");
-const attr = (tag, name) => {
-  const m = new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`).exec(tag);
-  return m ? (m[1] ?? m[2]) : null;
-};
-const round = (n) => Math.round(n * 100) / 100;
-const decode = (s) => s.replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;|&apos;/g, "'");
-const textOf = (html) => decode(html.replace(/<[^>]+>/g, " ")).replace(/\s+/g, " ").trim();
-
-// Comments blanked but newlines kept, so line numbers still match the file.
-const blankComments = (text) => text.replace(/<!--[\s\S]*?-->/g, (c) => c.replace(/[^\n]/g, " "));
-const lineAt = (text, index) => text.slice(0, index).split("\n").length;
-
-// Unknown presenter styles, with their line: data-presenter-style in index.html,
-// presenterStyle in script.md's front matter and presenter-style under a heading.
-export function presenterStyleErrors(html, script = "") {
-  const errs = [];
-  const page = blankComments(html);
-  for (const m of page.matchAll(/\sdata-presenter-style\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) {
-    const value = m[1] ?? m[2];
-    if (!PRESENTER_STYLES.includes(value)) errs.push(MESSAGES.presenterStyle(`index.html line ${lineAt(page, m.index)}`, value));
-  }
-  const lines = script.replace(/\r\n?/g, "\n").split("\n");
-  const frontEnd = lines[0]?.trim() === "---" ? lines.indexOf("---", 1) : -1;
-  lines.forEach((line, i) => {
-    const m = (i > 0 && i < frontEnd ? /^\s*presenterStyle\s*:\s*(.*?)\s*$/ : /^\s*presenter-style\s*:\s*(.*?)\s*$/).exec(line);
-    if (m && !PRESENTER_STYLES.includes(m[1])) errs.push(MESSAGES.presenterStyle(`script.md line ${i + 1}`, m[1]));
-  });
-  return errs;
-}
-
-// Does a simple selector (tag, #id, .class, or one compound of them) match
-// anything in this slide's markup? null when the selector is too complex to
-// tell without a browser.
-export function selectorMatches(body, selector) {
-  const m = /^([a-zA-Z][a-zA-Z0-9-]*)?(?:#([\w-]+))?((?:\.[\w-]+)*)$/.exec(selector.trim());
-  if (!m || !(m[1] || m[2] || m[3])) return null;
-  const [, tag, id, cls] = m;
-  const classes = cls.split(".").filter(Boolean);
-  return [...uncommented(body).matchAll(/<([a-zA-Z][a-zA-Z0-9-]*)\b[^>]*>/g)].some(([open, name]) => {
-    if (tag && name.toLowerCase() !== tag.toLowerCase()) return false;
-    if (id && attr(open, "id") !== id) return false;
-    const have = (attr(open, "class") ?? "").split(/\s+/);
-    return classes.every((c) => have.includes(c));
-  });
-}
-
-// [go: <selector>] and [look: <selector>] in script.md must match something in
-// their slide ([go: slot] returns home and always resolves).
-export function cueSelectorErrors(html, script = "") {
-  const bodies = new Map(slides(html).map((s) => [s.id, s.body]));
-  const errs = [];
-  let id = null;
-  script.replace(/\r\n?/g, "\n").split("\n").forEach((line, i) => {
-    const heading = /^##\s+(\S+)/.exec(line);
-    if (heading) { id = heading[1]; return; }
-    if (!id || !bodies.has(id)) return;
-    for (const [, cue, raw] of line.matchAll(/\[\s*(go|look)\s*:\s*([^\]]*?)\s*\]/gi)) {
-      if (raw === "slot" || !raw) continue;
-      if (selectorMatches(bodies.get(id), raw) === false) errs.push(MESSAGES.selector(i + 1, cue.toLowerCase(), raw, id));
-    }
-  });
-  return errs;
-}
-
-// Same normalization as the source check: accents folded, case and punctuation dropped.
-export const normalizeWords = (text) => text.normalize("NFKD").replace(/\p{Diacritic}/gu, "").toLowerCase().replace(/[^a-z0-9]/g, "");
-
-// `<section class="slide …">` blocks in document order: id, the opening tag, the
-// title (first <h1>/<h2>) and its opening tag.
-export function slides(html) {
-  return [...uncommented(html).matchAll(/(<section\b[^>]*\sclass="(?:[^"]*\s)?slide(?:\s[^"]*)?"[^>]*>)([\s\S]*?)<\/section>/g)].map(([, tag, body]) => {
-    const heading = /(<h[12]\b[^>]*>)([\s\S]*?)<\/h[12]>/.exec(body);
-    return { id: attr(tag, "id") ?? "", tag, body, title: heading ? textOf(heading[2]) : "", titleTag: heading?.[1] ?? "" };
-  });
-}
-
-export function playerScript(html) {
-  const tag = [...uncommented(html).matchAll(/<script\b[^>]*>/g)].map((m) => m[0]).find((t) => /\/player\/v\d+\/player\.js"/.test(t));
-  return tag ? { src: attr(tag, "src"), manifest: attr(tag, "data-manifest") || null } : null;
-}
-
-// Relative references: src, href, poster and data-presenter-image (either quote), srcset candidates and
-// CSS url(…) in style attributes and <style> blocks; everything that is not a URL
-// scheme, protocol-relative or a fragment. Query strings and fragments dropped.
-export function localRefs(html) {
-  const doc = uncommented(html);
-  const raw = [
-    ...[...doc.matchAll(/\s(?:src|href|poster|data-presenter-image)\s*=\s*(?:"([^"]*)"|'([^']*)')/gi)].map((m) => m[1] ?? m[2]),
-    ...[...doc.matchAll(/\ssrcset\s*=\s*(?:"([^"]*)"|'([^']*)')/gi)].flatMap((m) => (m[1] ?? m[2]).split(",").map((c) => c.trim().split(/\s+/)[0])),
-    ...[...doc.matchAll(/url\(\s*(?:"([^"]*)"|'([^']*)'|([^)'"\s]+))\s*\)/gi)].map((m) => m[1] ?? m[2] ?? m[3]),
-  ];
-  const refs = raw.map((r) => decode(String(r ?? "")).trim().split("#")[0].split("?")[0]).filter(Boolean);
-  // Folder links (href="/", "./") are navigation, not files.
-  return [...new Set(refs.filter((r) => !/^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(r) && !r.endsWith("/")))];
-}
-
-function phraseList(value) {
-  if (!value) return [];
-  if (typeof value === "string") return value.split(",").map((s) => s.trim()).filter(Boolean);
-  return value.map((s) => String(s).trim()).filter(Boolean);
-}
-
-// Everything checkable from the deck's own files. `exists(ref)` answers whether a
-// local reference resolves inside the deck folder: true, false or "outside".
-export function htmlErrors(html, { exists = () => true, forbid = [], script = "" } = {}) {
-  const errs = [...presenterStyleErrors(html, script), ...cueSelectorErrors(html, script)];
-  const player = playerScript(html);
-  if (!player) errs.push(MESSAGES.noPlayer());
-  else if (player.src !== PLAYER_V1) errs.push(MESSAGES.player(player.src));
-  // The loading state must be in <head> to hold the page from its first paint,
-  // with its fail-open so a deck whose player never loads still shows.
-  const loading = /<style\b[^>]*\sdata-hd-loading(?=[\s>=])[^>]*>([\s\S]*?)<\/style>/i.exec(/<head\b[\s\S]*?<\/head>/i.exec(uncommented(html))?.[0] ?? "");
-  if (player && !loading?.[1].includes("hd-fail-open")) errs.push(MESSAGES.noLoading());
-  const all = slides(html);
-  if (!all.length) errs.push(MESSAGES.noSlides());
-  all.forEach((s, i) => {
-    const id = s.id || `${i + 1}`;
-    if (!s.id) errs.push(MESSAGES.slideId(i + 1));
-    if (!attr(s.tag, "data-note")?.trim()) errs.push(MESSAGES.note(id));
-    if (s.title.length > MOBILE_TITLE_CHARS && !attr(s.titleTag, "data-title-mobile") && !attr(s.tag, "data-title-mobile")) {
-      errs.push(MESSAGES.mobileTitle(id, s.title));
-    }
-  });
-  for (const ref of localRefs(html)) {
-    const found = exists(ref);
-    if (found === "outside") errs.push(MESSAGES.outsideRef(ref));
-    else if (!found) errs.push(MESSAGES.localRef(ref));
-  }
-  const page = textOf(uncommented(html).replace(/<(script|style)\b[\s\S]*?<\/\1>/g, " ")).toLowerCase();
-  for (const phrase of phraseList(forbid)) {
-    const p = phrase.toLowerCase();
-    if (page.includes(p) || uncommented(html).toLowerCase().includes(p)) errs.push(MESSAGES.forbidden(phrase, "index.html"));
-    if (script.toLowerCase().includes(p)) errs.push(MESSAGES.forbidden(phrase, "script.md"));
-  }
-  return errs;
-}
-
-// The manifest against the deck: order, total and cap. Clip text is checked for
-// forbidden phrases too, since that is what the audience hears.
-const isNum = (v) => typeof v === "number" && Number.isFinite(v);
-const isStr = (v) => typeof v === "string" && v.trim().length > 0;
-
-// Fields every clip needs before its other rules mean anything.
-export function clipFieldErrors(clip, i) {
-  const id = isStr(clip?.id) ? clip.id : `#${i + 1}`;
-  const errs = [];
-  if (!isStr(clip?.id)) errs.push(MESSAGES.clipField(id, "needs an id"));
-  if (!(isNum(clip?.duration) && clip.duration > 0)) errs.push(MESSAGES.clipField(id, "duration must be a positive number of seconds"));
-  if (!(isNum(clip?.hold) && clip.hold >= 0)) errs.push(MESSAGES.clipField(id, "hold must be a number of seconds, 0 or more"));
-  if (!isStr(clip?.text)) errs.push(MESSAGES.clipField(id, "needs its text"));
-  for (const k of ["audio", "timeline"]) if (!isStr(clip?.[k])) errs.push(MESSAGES.clipField(id, `needs an ${k} URL`));
-  return errs;
-}
-
-export function manifestErrors(manifest, slideIds, { maxDuration = DEFAULT_MAX_DURATION, forbid = [] } = {}) {
-  const clips = Array.isArray(manifest?.clips) ? manifest.clips : [];
-  const clipIds = clips.map((c) => c?.id ?? "");
-  const errs = clips.flatMap(clipFieldErrors);
-  if (slideIds.length !== clipIds.length || slideIds.some((id, i) => id !== clipIds[i])) errs.push(MESSAGES.order(slideIds, clipIds));
-  const sum = round(clips.reduce((n, c) => n + (Number(c?.duration) || 0) + (Number(c?.hold) || 0), 0));
-  const declared = Number(manifest?.totalDuration);
-  if (!(Math.abs(sum - declared) < 0.01)) errs.push(MESSAGES.total(sum, manifest?.totalDuration));
-  if (Number.isFinite(declared) && declared > maxDuration) errs.push(MESSAGES.cap(round(declared), maxDuration));
-  const badStyle = (v) => v !== undefined && !PRESENTER_STYLES.includes(v);
-  if (badStyle(manifest?.presenterStyle)) errs.push(MESSAGES.presenterStyle("manifest", manifest.presenterStyle));
-  for (const c of clips) if (badStyle(c?.presenterStyle)) errs.push(MESSAGES.presenterStyle(`clip ${c.id}`, c.presenterStyle));
-  for (const phrase of phraseList(forbid)) {
-    for (const c of clips) if (String(c?.text ?? "").toLowerCase().includes(phrase.toLowerCase())) errs.push(MESSAGES.forbidden(phrase, `clip ${c.id}`));
-  }
-  return errs;
-}
-
-// One clip's timeline: caption timing, coverage of the clip text, and length.
-export function timelineErrors(clip, timeline) {
-  const errs = [];
-  if (!Array.isArray(timeline?.captions) || !timeline.captions.length) return [MESSAGES.noCaptions(clip.id)];
-  const captions = timeline.captions.map((c) => (c && typeof c === "object" ? c : {}));
-  const duration = Number(clip.duration) || 0;
-  captions.forEach((c, i) => {
-    if (!(c.start >= 0 && c.end > c.start && c.end <= duration + 0.1)) errs.push(MESSAGES.timing(clip.id, i, c.start, c.end, duration));
-  });
-  // Caption text carries the script's spelling; the timed words carry the
-  // transcript's (which may spell a name differently, as the narrate guard's
-  // pronunciation map allows), so coverage is checked on the text.
-  const covered = captions.map((c) => String(c.text ?? "")).join(" ");
-  const timed = captions.every((c) => Array.isArray(c.words) && c.words.length);
-  if (!timed || normalizeWords(covered) !== normalizeWords(String(clip.text ?? ""))) errs.push(MESSAGES.words(clip.id));
-  captions.forEach((c, i) => {
-    const text = String(c.text ?? "");
-    if (text.length < CAPTION_MIN_CHARS || text.length > CAPTION_MAX_CHARS) errs.push(MESSAGES.captionLength(clip.id, i, text));
-  });
-  return errs;
-}
-
-// Each slide's presenter style, as the player resolves it at desktop size: the
-// slide's data-presenter-style, its clip's, the player tag's, the manifest's,
-// then stage for the live head and bubble otherwise.
-export function slideStyles(html, manifest = null) {
-  const page = uncommented(html);
-  const tag = [...page.matchAll(/<script\b[^>]*>/g)].map((m) => m[0]).find((t) => /\/player\/v\d+\/player\.js"/.test(t)) ?? "";
-  const known = (v) => (PRESENTER_STYLES.includes(v) ? v : null);
-  const deck = known(attr(tag, "data-presenter-style")) ?? known(manifest?.presenterStyle) ?? (attr(tag, "data-presenter") === "head" ? "stage" : "bubble");
-  const clips = new Map((Array.isArray(manifest?.clips) ? manifest.clips : []).map((c) => [c?.id, c]));
-  return slides(html).map((s) => ({ id: s.id, style: known(attr(s.tag, "data-presenter-style")) ?? known(clips.get(s.id)?.presenterStyle) ?? deck }));
-}
-
-// What each style occupies at desktop size, in stage pixels (player.css): the
-// head plus two caption lines. Corner sits in the stage's corner, not the slot.
-export const PRESENTER_FOOTPRINT = {
-  stage: { width: 480, height: 490 },
-  glass: { width: 522, height: 534 },
-  bubble: { width: 446, height: 304 },
-  corner: { width: 400, height: 330, right: 28, bottom: 28 },
-};
-
-// Measured boxes → warnings. Each entry: { id, style, presenter, title } with
-// { x, y, width, height } boxes (title null when the slide has none).
-export function overlapWarnings(measured, stage = "1600×900") {
-  const hit = (a, b) => a && b && Math.min(a.x + a.width, b.x + b.width) - Math.max(a.x, b.x) > 4 && Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y) > 4;
-  return measured.filter((m) => hit(m.presenter, m.title)).map((m) => MESSAGES.overlap(m.id, m.style, stage));
-}
-
-// Slides whose content overflows the phone card, as errors. Each entry: { id, overflow } in px.
-export function phoneOverflowErrors(measured) {
-  return measured.filter((m) => m.overflow > 1).map((m) => MESSAGES.phoneOverflow(m.id, Math.ceil(m.overflow)));
-}
+export * from "./checkRules.mjs";
 
 // Lay each slide out in Chromium at the deck's stage size with JavaScript off
 // (no player, no deck scripts), put the style's footprint in its slot, and
@@ -371,13 +105,6 @@ async function withDeckPage(deckDir, viewport, measure) {
   }
 }
 
-// The deck's own cap: `maxTotalSeconds` in script.md's front matter.
-export function scriptCap(script) {
-  const front = /^---\r?\n([\s\S]*?)\r?\n---/.exec(script)?.[1] ?? "";
-  const m = /^maxTotalSeconds:\s*([\d.]+)\s*$/m.exec(front);
-  return m ? Number(m[1]) : null;
-}
-
 // "<slug>" means ./decks/<slug> unless it names a folder itself.
 export function resolveDeckDir(arg, cwd = process.cwd()) {
   if (!arg) throw new Error("usage: check <slug|deck-dir>");
@@ -411,98 +138,19 @@ export function deckFileResolver(deckDir) {
   };
 }
 
-async function fetchCheck(fetchImpl, url, want) {
-  try {
-    const r = await fetchImpl(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
-    if (!r.ok) {
-      await r.body?.cancel?.();
-      return { why: `returned HTTP ${r.status}` };
-    }
-    const type = (r.headers.get("content-type") || "").split(";")[0].trim();
-    if (!want.test(type)) {
-      await r.body?.cancel?.();
-      return { why: `is ${type || "untyped"}, expected ${want === AUDIO ? "audio/*" : "JSON"}` };
-    }
-    return { response: r };
-  } catch (e) {
-    return { why: `could not be fetched (${e.message})` };
-  }
-}
-const AUDIO = /^audio\//;
-const FETCH_TIMEOUT_MS = 30_000;
-const JSON_TYPE = /json/;
-
 // Run every rule on a deck folder. Returns { deckDir, slug, slides, totalDuration, errors }.
 export async function checkDeck(dirArg, opts = {}, { fetch: fetchImpl = globalThis.fetch, cwd, measure = measureLayout, measureFit = measurePhoneFit } = {}) {
   const deckDir = resolveDeckDir(dirArg, cwd);
   const html = readFileSync(join(deckDir, "index.html"), "utf8");
   const scriptPath = join(deckDir, "script.md");
   const script = existsSync(scriptPath) ? readFileSync(scriptPath, "utf8") : "";
-  const forbid = phraseList(opts.forbid);
-  const flagCap = opts["max-duration"] ?? opts.maxDuration;
-  const maxDuration = Number(flagCap ?? scriptCap(script) ?? DEFAULT_MAX_DURATION);
-  if (!Number.isFinite(maxDuration) || maxDuration <= 0) {
-    throw new Error(flagCap !== undefined ? "--max-duration needs a number of seconds" : "maxTotalSeconds in script.md must be a number of seconds");
-  }
-
-  const errors = htmlErrors(html, { exists: deckFileResolver(deckDir), forbid, script });
-  const ids = slides(html).map((s) => s.id);
-  const player = playerScript(html);
-  let manifest = null;
-  if (player && !player.manifest) errors.push(MESSAGES.noManifest());
-  if (player?.manifest) {
-    const got = await fetchCheck(fetchImpl, player.manifest, JSON_TYPE);
-    if (got.why) errors.push(MESSAGES.manifestUnavailable(player.manifest, got.why));
-    else {
-      try {
-        manifest = await got.response.json();
-      } catch (e) {
-        errors.push(MESSAGES.manifestUnavailable(player.manifest, `not JSON: ${e.message}`));
-      }
-      if (manifest !== null && !(manifest && typeof manifest === "object" && Array.isArray(manifest.clips) && manifest.clips.length)) {
-        errors.push(MESSAGES.manifestUnavailable(player.manifest, "not a manifest: needs a non-empty clips array"));
-        manifest = null;
-      } else if (manifest === null && !errors.some((e) => e.startsWith(`manifest ${player.manifest}`))) {
-        errors.push(MESSAGES.manifestUnavailable(player.manifest, "not a manifest: needs a non-empty clips array"));
-      }
-    }
-  }
-  if (manifest) {
-    errors.push(...manifestErrors(manifest, ids, { maxDuration, forbid }));
-    for (const [i, clip] of manifest.clips.entries()) {
-      if (clipFieldErrors(clip, i).length) continue; // already reported
-      let audioUrl, timelineUrl;
-      try {
-        audioUrl = new URL(clip.audio, player.manifest).href;
-        timelineUrl = new URL(clip.timeline, player.manifest).href;
-      } catch {
-        errors.push(MESSAGES.clipField(clip.id, "audio and timeline must be URLs"));
-        continue;
-      }
-      const audio = await fetchCheck(fetchImpl, audioUrl, AUDIO);
-      if (audio.why) errors.push(MESSAGES.url(clip.id, "audio", audioUrl, audio.why));
-      else await audio.response.body?.cancel?.().catch(() => {});
-      const tl = await fetchCheck(fetchImpl, timelineUrl, JSON_TYPE);
-      if (tl.why) {
-        errors.push(MESSAGES.url(clip.id, "timeline", timelineUrl, tl.why));
-        continue;
-      }
-      let timeline;
-      try {
-        timeline = await tl.response.json();
-      } catch (e) {
-        errors.push(MESSAGES.url(clip.id, "timeline", timelineUrl, `is not JSON (${e.message})`));
-        continue;
-      }
-      errors.push(...timelineErrors(clip, timeline));
-    }
-  }
+  const { manifest, ...result } = await checkSources({ html, script }, { ...opts, hosted: false, exists: deckFileResolver(deckDir) }, { fetch: fetchImpl });
+  const { errors, warnings } = result;
   // A presenter over the title is a warning, not a failure: only a person can
   // judge it. A slide that overflows the phone card is an error. Both need a
   // browser, so they run only with --layout.
-  const warnings = [];
   if (opts.layout) {
-    const [w, h] = /^(\d{3,4})x(\d{3,4})$/.exec(attr([...uncommented(html).matchAll(/<script\b[^>]*>/g)].map((m) => m[0]).find((t) => /\/player\/v\d+\/player\.js"/.test(t)) ?? "", "data-stage") ?? "")?.slice(1).map(Number) ?? [1600, 900];
+    const { width: w, height: h } = stageSize(html);
     try {
       warnings.push(...overlapWarnings(await measure(deckDir, slideStyles(html, manifest), { width: w, height: h }), `${w}×${h}`));
     } catch (e) {
@@ -518,11 +166,8 @@ export async function checkDeck(dirArg, opts = {}, { fetch: fetchImpl = globalTh
   return {
     deckDir,
     slug: opts.slug || basename(deckDir),
-    slides: ids.length,
-    totalDuration: manifest ? Number(manifest.totalDuration) : null,
-    manifestUrl: player?.manifest ?? null,
+    ...result,
     passed: errors.length === 0,
-    errors,
     warnings: [...new Set(warnings)],
   };
 }