@hypersocial/decks-cli 0.2.1 → 0.3.0

package/src/check.mjs

@@ -1,4 +1,4 @@
-// hyperdecks check <slug|deck-dir> [--forbid "<phrase>,<phrase>"] [--max-duration <s>] [--json]
+// hyperdecks check <slug|deck-dir> [--forbid "<phrase>,<phrase>"] [--max-duration <s>] [--layout] [--json]
 //
 // The narrated-deck integrity gate, ported from the Netflix presentation's
 // scripts/check.mjs and its variant builders. Every rule returns its message from
@@ -6,171 +6,103 @@
 // 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";
-
-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;
-
-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="…">',
-  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}: caption words do not match the clip text (the captions must cover the whole narration)`,
-  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`,
-};
-
-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();
-
-// 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 and poster (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)\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("/")))];
+import { PHONE, PRESENTER_FOOTPRINT, checkSources, overlapWarnings, phoneOverflowErrors, slideStyles, stageSize, MESSAGES } from "./checkRules.mjs";
+
+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
+// measure it against the title's text. Needs `hyperdecks preview setup`.
+export async function measureLayout(deckDir, styles, { width = 1600, height = 900 } = {}) {
+  return withDeckPage(deckDir, { width, height }, (page) => page.evaluate(({ styles, footprint, width, height }) => {
+    const box = (r) => ({ x: r.left, y: r.top, width: r.width, height: r.height });
+    const sections = [...document.querySelectorAll("section.slide")];
+    const host = sections[0]?.parentElement ?? document.body;
+    Object.assign(host.style, { position: "relative", width: `${width}px`, height: `${height}px`, overflow: "hidden", margin: "0" });
+    document.body.style.margin = "0";
+    return sections.map((slide, i) => {
+      sections.forEach((s) => { s.style.display = s === slide ? "" : "none"; Object.assign(s.style, { position: "absolute", inset: "0" }); });
+      const { id, style } = styles[i] ?? { id: slide.id, style: "bubble" };
+      const size = footprint[style];
+      const probe = document.createElement("div");
+      Object.assign(probe.style, { width: `${size.width}px`, height: `${size.height}px`, flex: "none" });
+      const slot = slide.querySelector(".narration-slot");
+      let presenter = null;
+      if (style === "corner" || !slot) {
+        const right = size.right ?? 56, bottom = size.bottom ?? 56;
+        presenter = { x: width - right - size.width, y: height - bottom - size.height, width: size.width, height: size.height };
+      } else {
+        slot.append(probe);
+        presenter = box(probe.getBoundingClientRect());
+        probe.remove();
+      }
+      const heading = slide.querySelector("h1, h2");
+      let title = null;
+      if (heading) {
+        const range = document.createRange();
+        range.selectNodeContents(heading);
+        const rects = [...range.getClientRects()].filter((r) => r.width && r.height);
+        if (rects.length) {
+          const [x0, y0] = [Math.min(...rects.map((r) => r.left)), Math.min(...rects.map((r) => r.top))];
+          title = { x: x0, y: y0, width: Math.max(...rects.map((r) => r.right)) - x0, height: Math.max(...rects.map((r) => r.bottom)) - y0 };
+        }
+      }
+      return { id, style, presenter, title };
+    });
+  }, { styles, footprint: PRESENTER_FOOTPRINT, width, height }));
 }
 
-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);
+// Lay each slide out as the framed player shows it on a phone: the deck's own
+// phone rules at a 390×844 viewport, its mobile titles, inside the card, with
+// JavaScript off. Returns { id, overflow } per slide: how far its content runs
+// past the slide's bottom (≤ 0 when it fits).
+export async function measurePhoneFit(deckDir) {
+  return withDeckPage(deckDir, { width: PHONE.width, height: PHONE.height }, (page) => page.evaluate((card) => {
+    for (const n of document.querySelectorAll("[data-title-mobile]")) n.textContent = n.dataset.titleMobile;
+    const sections = [...document.querySelectorAll("section.slide")];
+    const host = sections[0]?.parentElement ?? document.body;
+    Object.assign(host.style, { position: "relative", width: `${card.width}px`, height: `${card.height}px`, overflow: "hidden", margin: "0" });
+    document.body.style.margin = "0";
+    return sections.map((slide) => {
+      sections.forEach((s) => { s.style.display = s === slide ? "" : "none"; Object.assign(s.style, { position: "absolute", inset: "0", overflow: "hidden" }); });
+      return { id: slide.id, overflow: slide.scrollHeight - slide.clientHeight };
+    });
+  }, PHONE.card));
 }
 
-// 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 = [];
-  const player = playerScript(html);
-  if (!player) errs.push(MESSAGES.noPlayer());
-  else if (player.src !== PLAYER_V1) errs.push(MESSAGES.player(player.src));
-  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));
+// Open the deck's index.html in Chromium at `viewport` with JavaScript off and
+// hand the page to `measure`. Needs `hyperdecks preview setup`.
+async function withDeckPage(deckDir, viewport, measure) {
+  const { chromium } = await import("playwright");
+  const { serveSource, routeCaptureRequest } = await import("./preview-capture.mjs");
+  const { mkdtemp, rm } = await import("node:fs/promises");
+  const { tmpdir } = await import("node:os");
+  // The same isolation as preview capture: a throwaway HOME, the sandbox on
+  // Linux, and its request filter (no loopback, private or metadata hosts).
+  const temp = await mkdtemp(join(tmpdir(), "hyperdecks-layout-"));
+  let browser, server;
+  try {
+    try {
+      browser = await chromium.launch({ headless: true, timeout: 30000, chromiumSandbox: process.platform === "linux", env: { ...(process.platform === "win32" ? { SystemRoot: process.env.SystemRoot } : {}), PATH: process.env.PATH, TMPDIR: temp, HOME: temp } });
+    } catch {
+      throw new Error("check --layout needs Chromium: run `hyperdecks preview setup`");
     }
-  });
-  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));
-  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}`));
+    server = await serveSource({ file: join(deckDir, "index.html") });
+    const context = await browser.newContext({ viewport, javaScriptEnabled: false, serviceWorkers: "block" });
+    await context.route("**/*", (route) => routeCaptureRequest(route, server.url));
+    const page = await context.newPage();
+    await page.goto(server.url, { waitUntil: "load", timeout: 30000 });
+    await page.evaluate(() => document.fonts.ready);
+    return await measure(page);
+  } finally {
+    await server?.close().catch(() => {});
+    await browser?.close().catch(() => {});
+    await rm(temp, { recursive: true, force: true }).catch(() => {});
   }
-  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));
-  });
-  const spoken = captions.flatMap((c) => (Array.isArray(c.words) ? c.words.map((w) => w?.text ?? "") : [])).join(" ");
-  if (normalizeWords(spoken) !== 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;
-}
-
-// 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.
@@ -206,100 +138,37 @@ 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 } = {}) {
+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"));
-      }
+  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.
+  if (opts.layout) {
+    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) {
+      warnings.push(MESSAGES.layoutUnchecked(e.message));
     }
-  }
-  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));
+    // A slide that scrolls on a phone fails: the player never scrolls a slide.
+    try {
+      errors.push(...phoneOverflowErrors(await measureFit(deckDir)));
+    } catch (e) {
+      warnings.push(MESSAGES.layoutUnchecked(e.message));
     }
   }
   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)],
   };
 }
 
@@ -311,6 +180,7 @@ export async function check(pos, opts = {}, { log = (line) => console.log(line),
       log(`✗ ${result.errors.length} issue(s):`);
       for (const e of result.errors) log(`  - ${e}`);
     } else log("✓ check passed");
+    for (const w of result.warnings) log(`  ⚠ ${w}`);
   }
   return result;
 }