@hypersocial/decks-cli 0.2.2 → 0.3.1

package/src/checkRules.mjs

@@ -0,0 +1,558 @@
+// The narrated-deck rules, with no Node imports: the CLI's check (check.mjs,
+// which adds the folder I/O and the Chromium measurements), the stdio MCP and
+// the hosted check (convex/deckSources.ts) all run these, so a deck gets the same
+// errors wherever it is checked. checkSources is the I/O-free core of checkDeck:
+// the deck's index.html and script.md as text, with the manifest and clip fetches
+// injected.
+
+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"];
+// Same names as TRANSITIONS in lib/deckManifest.ts and packages/player/transitions.js.
+export const TRANSITIONS = ["drift", "cut", "push", "wipe", "zoom", "morph", "fly"];
+export const MAX_TRANSITION_KINDS = 2;
+
+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",
+  noManifestHosted: () => "the player script has no data-manifest: call narrate_deck (no script) and wait for check_narration_job; it 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}`,
+  hostedRef: (ref) => `local reference ${ref}: a hosted deck has no folder, so every file must be a URL; upload it with upload_deck_asset and use the URL it returns`,
+  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(", ")}`,
+  transition: (where, value) => `${where}: transition "${value}" is not one of ${TRANSITIONS.join(", ")} (zoom takes a selector: "zoom #row")`,
+  zoomTarget: (id, target, prev) => `slide ${id}: zoom target "${target}" matches nothing on the slide before it (${prev})`,
+  morphPair: (id, prev) => `slide ${id}: morph needs an element with the same data-morph="<name>" on this slide and the one before it (${prev})`,
+  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 (check --layout): the deck still passes.
+  layoutUnchecked: (why) => `layout not checked: ${why}`,
+  hotlink: (url) => `${url} is hotlinked from another site and can vanish after release; upload it with upload_deck_asset`,
+  transitionKinds: (kinds, deck) => `${kinds.length} kinds of transition besides the default (${deck}): ${kinds.join(", ")}; keep to ${MAX_TRANSITION_KINDS} so the deck reads as designed`,
+  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 HOSTED_LAYOUT_WHY = "presenter overlap and phone fit need a browser: run review_deck with draft=true";
+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;
+}
+
+// "zoom #dash-row" → { name: "zoom", target: "#dash-row" }; null when it is not a transition.
+export function parseTransition(value) {
+  if (typeof value !== "string") return null;
+  const [name, ...rest] = value.trim().split(/\s+/);
+  const target = rest.join(" ");
+  if (!TRANSITIONS.includes(name)) return null;
+  if (name === "zoom") return target ? { name, target } : null;
+  return target ? null : { name };
+}
+
+// script.md's transitions, with their line: `transition:` in the front matter
+// (the deck's) and in the options right under a "## <id>" heading (a slide's).
+function scriptTransitions(script) {
+  const lines = script.replace(/\r\n?/g, "\n").split("\n");
+  const frontEnd = lines[0]?.trim() === "---" ? lines.indexOf("---", 1) : -1;
+  const out = { deck: null, slides: new Map() };
+  let id = null, inOptions = false;
+  lines.forEach((line, i) => {
+    if (i > 0 && i < frontEnd) {
+      const m = /^\s*transition\s*:\s*(.*?)\s*$/.exec(line);
+      if (m) out.deck = { value: m[1], line: i + 1 };
+      return;
+    }
+    const heading = /^##\s+(\S+)/.exec(line);
+    if (heading) { id = heading[1]; inOptions = true; return; }
+    const option = inOptions && /^\s*([A-Za-z][A-Za-z0-9-]*)\s*:\s*(.*?)\s*$/.exec(line);
+    if (!option) { inOptions = false; return; }
+    if (option[1] === "transition") out.slides.set(id, { value: option[2], line: i + 1 });
+  });
+  return out;
+}
+
+// How each slide enters, as the player resolves it: the slide's
+// data-transition, its own (script.md, else its manifest clip), the player
+// tag's, the deck's (script.md, else the manifest), then drift.
+export function slideTransitions(html, script = "", 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 fromScript = scriptTransitions(script);
+  const clips = new Map((Array.isArray(manifest?.clips) ? manifest.clips : []).map((c) => [c?.id, c]));
+  const first = (...values) => values.map(parseTransition).find(Boolean) ?? { name: "drift" };
+  const deck = [attr(tag, "data-transition"), fromScript.deck?.value, manifest?.transition];
+  return {
+    deck: first(...deck),
+    slides: slides(html).map((s) => ({
+      id: s.id,
+      body: s.body,
+      transition: first(attr(s.tag, "data-transition"), fromScript.slides.get(s.id)?.value, clips.get(s.id)?.transition, ...deck),
+    })),
+  };
+}
+
+const morphNames = (body) => new Set([...uncommented(body).matchAll(/\sdata-morph\s*=\s*(?:"([^"]*)"|'([^']*)')/g)].map((m) => m[1] ?? m[2]));
+
+// Unknown transitions (with their line), and the rules the moves need: a zoom's
+// target on the slide before it, a morph's pair on both slides, one fly a deck.
+// The first slide is never entered by a transition, so its own is not judged.
+export function transitionErrors(html, script = "", manifest = null) {
+  const errs = [];
+  const page = blankComments(html);
+  for (const m of page.matchAll(/\sdata-transition\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) {
+    const value = m[1] ?? m[2];
+    if (!parseTransition(value)) errs.push(MESSAGES.transition(`index.html line ${lineAt(page, m.index)}`, value));
+  }
+  const fromScript = scriptTransitions(script);
+  for (const t of [fromScript.deck, ...fromScript.slides.values()].filter(Boolean)) {
+    if (!parseTransition(t.value)) errs.push(MESSAGES.transition(`script.md line ${t.line}`, t.value));
+  }
+  const all = slideTransitions(html, script, manifest).slides;
+  all.forEach(({ id, body, transition }, i) => {
+    if (i === 0) return;
+    const prev = all[i - 1];
+    if (transition.name === "zoom" && selectorMatches(prev.body, transition.target) === false) errs.push(MESSAGES.zoomTarget(id, transition.target, prev.id));
+    if (transition.name === "morph") {
+      const before = morphNames(prev.body);
+      if (![...morphNames(body)].some((n) => before.has(n))) errs.push(MESSAGES.morphPair(id, prev.id));
+    }
+  });
+  const flies = all.slice(1).filter((s) => s.transition.name === "fly").map((s) => s.id);
+  if (flies.length > 1) errs.push(MESSAGES.flyTwice(flies));
+  return errs;
+}
+
+// The player reads script.md's transitions from the manifest only, which
+// narrate rebuilds: a script value the manifest does not carry yet is stale.
+export function transitionStaleErrors(script, manifest) {
+  if (!script.trim() || !manifest) return [];
+  const fromScript = scriptTransitions(script);
+  const canonical = (v) => (parseTransition(v) ? v.trim().split(/\s+/).join(" ") : null);
+  const errs = [];
+  const same = (where, mine, theirs) => {
+    const a = mine === undefined ? "drift" : canonical(mine), b = theirs === undefined ? "drift" : canonical(theirs);
+    if (a !== null && b !== null && a !== b) errs.push(MESSAGES.transitionStale(where, a, b));
+  };
+  same("script.md front matter", fromScript.deck?.value, manifest.transition);
+  for (const clip of Array.isArray(manifest.clips) ? manifest.clips : []) same(`slide ${clip?.id}`, fromScript.slides.get(clip?.id)?.value, clip?.transition);
+  return errs;
+}
+
+// More than MAX_TRANSITION_KINDS kinds besides the deck's default reads as a
+// sampler, not a design: a warning, since only a person can judge it.
+export function transitionWarnings(html, script = "", manifest = null) {
+  const { deck, slides: all } = slideTransitions(html, script, manifest);
+  const kinds = [...new Set(all.slice(1).map((s) => s.transition.name).filter((n) => n !== deck.name))];
+  return kinds.length > MAX_TRANSITION_KINDS ? [MESSAGES.transitionKinds(kinds, deck.name)] : [];
+}
+
+// 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("/")))];
+}
+
+export 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), ...transitionErrors(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 === "hosted") errs.push(MESSAGES.hostedRef(ref));
+    else 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));
+  const badTransition = (v) => v !== undefined && !parseTransition(v);
+  if (badTransition(manifest?.transition)) errs.push(MESSAGES.transition("manifest", manifest.transition));
+  for (const c of clips) if (badTransition(c?.transition)) errs.push(MESSAGES.transition(`clip ${c.id}`, c.transition));
+  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)));
+}
+
+// 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;
+}
+
+
+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/;
+
+
+
+// Same rule as sectionIds() in lib/deckScript.ts (the published CLI cannot import it).
+export const sectionIds = (html) => [...html.matchAll(/<section\b[^>]*?\sid\s*=\s*["']([^"']+)["']/gi)].map((m) => m[1]);
+
+// Set data-manifest on the hosted player's <script> tag; html is unchanged when
+// there is no player tag or it already names this URL.
+export function setManifestUrl(html, url) {
+  return html.replace(/<script\b[^>]*\/player\/v\d+\/player\.js"[^>]*>/, (tag) =>
+    /\sdata-manifest\s*=\s*"[^"]*"/.test(tag)
+      ? tag.replace(/(\sdata-manifest\s*=\s*)"[^"]*"/, (_, lead) => `${lead}"${url}"`)
+      : tag.replace(/\s*>$/, () => ` data-manifest="${url}">`));
+}
+
+// The stage size the player tag declares (data-stage="1600x900"), else 1600×900.
+export function stageSize(html) {
+  const tag = [...uncommented(html).matchAll(/<script\b[^>]*>/g)].map((m) => m[0]).find((t) => /\/player\/v\d+\/player\.js"/.test(t)) ?? "";
+  const [w, h] = /^(\d{3,4})x(\d{3,4})$/.exec(attr(tag, "data-stage") ?? "")?.slice(1).map(Number) ?? [1600, 900];
+  return { width: w, height: h };
+}
+
+// Absolute http(s) references (src, href, poster, srcset, url()), for the hosted
+// check's hotlink warning.
+export function absoluteRefs(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]),
+  ];
+  return [...new Set(raw.map((r) => decode(String(r ?? "")).trim()).filter((r) => /^https?:\/\//i.test(r)))];
+}
+
+// Hosts a released deck can rely on: our storage and app, the player, and fonts.
+const HOSTED_ASSET_HOSTS = [/\.convex\.cloud$/, /\.convex\.site$/, /(^|\.)hypersocial\.ai$/, /^fonts\.(googleapis|gstatic)\.com$/];
+const isHostedAsset = (url) => {
+  try {
+    const host = new URL(url).hostname;
+    return HOSTED_ASSET_HOSTS.some((re) => re.test(host));
+  } catch {
+    return false;
+  }
+};
+
+// Every rule on the deck's text. `exists(ref)` answers whether a local reference
+// resolves (true, false or "outside"); `hosted: true` means there is no folder,
+// so every local reference is an error naming upload_deck_asset, a hotlinked
+// image is a warning, and the layout rules (which need Chromium) are reported as
+// not checked. Returns { slides, totalDuration, manifestUrl, manifest, passed, errors, warnings }.
+export async function checkSources({ html, script = "" }, opts = {}, { fetch: fetchImpl = globalThis.fetch } = {}) {
+  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 exists = opts.hosted ? () => "hosted" : (opts.exists ?? (() => true));
+  const errors = htmlErrors(html, { exists, forbid, script });
+  const ids = slides(html).map((s) => s.id);
+  const player = playerScript(html);
+  let manifest = null;
+  if (player && !player.manifest) errors.push(opts.hosted ? MESSAGES.noManifestHosted() : 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 }));
+    // The moves' rules again, now counting the manifest's own transitions (a deck without script.md, or a stale one).
+    for (const e of transitionErrors(html, script, manifest)) if (!errors.includes(e)) errors.push(e);
+    errors.push(...transitionStaleErrors(script, manifest));
+    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 warnings = transitionWarnings(html, script, manifest);
+  if (opts.hosted) {
+    for (const url of absoluteRefs(html)) if (!isHostedAsset(url) && /\.(png|jpe?g|gif|webp|avif|svg|mp4|webm|mov)(\?|#|$)/i.test(url)) warnings.push(MESSAGES.hotlink(url));
+    warnings.push(MESSAGES.layoutUnchecked(HOSTED_LAYOUT_WHY));
+  }
+  return {
+    slides: ids.length,
+    totalDuration: manifest ? Number(manifest.totalDuration) : null,
+    manifestUrl: player?.manifest ?? null,
+    manifest,
+    passed: errors.length === 0,
+    errors,
+    warnings: [...new Set(warnings)],
+  };
+}