@cloudhal/mcp-server 0.0.0-stage → 0.1.1

package/dist/src/render/checks/contrast.d.ts

@@ -0,0 +1,5 @@
+/**
+ * In-page checks, part of `RENDER_CHECK_SCRIPT`: contrast: text against what is painted beneath it, band by band.
+ * Plain source text, run inside the page; it shares the script's locals (see ./index.ts).
+ */
+export declare const CONTRAST_CHECKS = "  // contrast: text against what is painted beneath it (elementsFromPoint), band by band.\n  const canvas = document.createElement(\"canvas\");\n  canvas.width = canvas.height = 1;\n  const g = canvas.getContext(\"2d\", { willReadFrequently: true });\n  const rgba = (css) => {\n    g.clearRect(0, 0, 1, 1);\n    g.fillStyle = \"rgba(0,0,0,0)\";\n    g.fillStyle = css;\n    g.fillRect(0, 0, 1, 1);\n    const d = g.getImageData(0, 0, 1, 1).data;\n    return [d[0], d[1], d[2], d[3] / 255];\n  };\n  const over = (top, under) => [0, 1, 2].map((i) => top[i] * top[3] + under[i] * (1 - top[3]));\n  const lum = (c) => {\n    const [r, gg, b] = c.map((v) => {\n      v /= 255;\n      return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);\n    });\n    return 0.2126 * r + 0.7152 * gg + 0.0722 * b;\n  };\n  const ratio = (a, b) => {\n    const [x, y] = [lum(a), lum(b)].sort((p, q) => q - p);\n    return (x + 0.05) / (y + 0.05);\n  };\n  const texts = [];\n  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);\n  const seen = new Set();\n  while (walker.nextNode() && texts.length < 800) {\n    const n = walker.currentNode;\n    const el = n.parentElement;\n    if (!el || seen.has(el) || !n.nodeValue.trim()) continue;\n    if (el.closest(\"script,style,noscript,template,svg\")) continue;\n    seen.add(el);\n    if (visible(el)) texts.push(el);\n  }\n  const pending = new Set(texts);\n  const page = Math.max(document.documentElement.scrollHeight, H);\n  for (let y = 0; y < page && pending.size; y += H) {\n    window.scrollTo(0, y);\n    for (const el of [...pending]) {\n      const r = el.getBoundingClientRect();\n      const cx = r.left + Math.min(r.width / 2, 12), cy = r.top + Math.min(r.height / 2, 10);\n      if (cy < 0 || cy >= H || cx < 0 || cx >= W) continue;\n      const stack = document.elementsFromPoint(cx, cy);\n      const at = stack.indexOf(el);\n      if (at < 0) continue;\n      pending.delete(el);\n      const layers = [];\n      let known = true;\n      for (const e of stack.slice(at)) {\n        const s = getComputedStyle(e);\n        if (/^(IMG|VIDEO|CANVAS|IFRAME|PICTURE)$/.test(e.tagName) || e.tagName.toLowerCase() === \"svg\" || s.backgroundImage !== \"none\") { known = false; break; }\n        const c = rgba(s.backgroundColor);\n        if (c[3] > 0) { layers.push(c); if (c[3] >= 1) break; }\n      }\n      if (!known) continue;\n      let bg = [255, 255, 255];\n      for (const c of layers.reverse()) bg = over(c, bg);\n      const s = getComputedStyle(el);\n      const fg = over(rgba(s.color), bg);\n      const size = parseFloat(s.fontSize), weight = Number(s.fontWeight) || 400;\n      const need = size >= 24 || (size >= 18.66 && weight >= 700) ? 3 : 4.5;\n      const got = ratio(fg, bg);\n      if (got < need) add(\"contrast\", el, got.toFixed(1) + \":1, needs \" + need + \":1\");\n    }\n  }\n  window.scrollTo(0, 0);\n";

package/dist/src/render/checks/contrast.js

@@ -0,0 +1,72 @@
+/**
+ * In-page checks, part of `RENDER_CHECK_SCRIPT`: contrast: text against what is painted beneath it, band by band.
+ * Plain source text, run inside the page; it shares the script's locals (see ./index.ts).
+ */
+export const CONTRAST_CHECKS = `  // contrast: text against what is painted beneath it (elementsFromPoint), band by band.
+  const canvas = document.createElement("canvas");
+  canvas.width = canvas.height = 1;
+  const g = canvas.getContext("2d", { willReadFrequently: true });
+  const rgba = (css) => {
+    g.clearRect(0, 0, 1, 1);
+    g.fillStyle = "rgba(0,0,0,0)";
+    g.fillStyle = css;
+    g.fillRect(0, 0, 1, 1);
+    const d = g.getImageData(0, 0, 1, 1).data;
+    return [d[0], d[1], d[2], d[3] / 255];
+  };
+  const over = (top, under) => [0, 1, 2].map((i) => top[i] * top[3] + under[i] * (1 - top[3]));
+  const lum = (c) => {
+    const [r, gg, b] = c.map((v) => {
+      v /= 255;
+      return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+    });
+    return 0.2126 * r + 0.7152 * gg + 0.0722 * b;
+  };
+  const ratio = (a, b) => {
+    const [x, y] = [lum(a), lum(b)].sort((p, q) => q - p);
+    return (x + 0.05) / (y + 0.05);
+  };
+  const texts = [];
+  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+  const seen = new Set();
+  while (walker.nextNode() && texts.length < 800) {
+    const n = walker.currentNode;
+    const el = n.parentElement;
+    if (!el || seen.has(el) || !n.nodeValue.trim()) continue;
+    if (el.closest("script,style,noscript,template,svg")) continue;
+    seen.add(el);
+    if (visible(el)) texts.push(el);
+  }
+  const pending = new Set(texts);
+  const page = Math.max(document.documentElement.scrollHeight, H);
+  for (let y = 0; y < page && pending.size; y += H) {
+    window.scrollTo(0, y);
+    for (const el of [...pending]) {
+      const r = el.getBoundingClientRect();
+      const cx = r.left + Math.min(r.width / 2, 12), cy = r.top + Math.min(r.height / 2, 10);
+      if (cy < 0 || cy >= H || cx < 0 || cx >= W) continue;
+      const stack = document.elementsFromPoint(cx, cy);
+      const at = stack.indexOf(el);
+      if (at < 0) continue;
+      pending.delete(el);
+      const layers = [];
+      let known = true;
+      for (const e of stack.slice(at)) {
+        const s = getComputedStyle(e);
+        if (/^(IMG|VIDEO|CANVAS|IFRAME|PICTURE)$/.test(e.tagName) || e.tagName.toLowerCase() === "svg" || s.backgroundImage !== "none") { known = false; break; }
+        const c = rgba(s.backgroundColor);
+        if (c[3] > 0) { layers.push(c); if (c[3] >= 1) break; }
+      }
+      if (!known) continue;
+      let bg = [255, 255, 255];
+      for (const c of layers.reverse()) bg = over(c, bg);
+      const s = getComputedStyle(el);
+      const fg = over(rgba(s.color), bg);
+      const size = parseFloat(s.fontSize), weight = Number(s.fontWeight) || 400;
+      const need = size >= 24 || (size >= 18.66 && weight >= 700) ? 3 : 4.5;
+      const got = ratio(fg, bg);
+      if (got < need) add("contrast", el, got.toFixed(1) + ":1, needs " + need + ":1");
+    }
+  }
+  window.scrollTo(0, 0);
+`;

package/dist/src/render/checks/index.d.ts

@@ -0,0 +1 @@
+export declare const RENDER_CHECK_SCRIPT: string;

package/dist/src/render/checks/index.js

@@ -0,0 +1,29 @@
+/**
+ * The checks, run inside the page (kept as source text: Workers bundlers rename functions, and
+ * this must stay self-contained). Returns `PageCheck[]` in `RENDER_CHECK_IDS` order.
+ *
+ * One async function in the page, assembled from ordered parts that share its locals: the
+ * prelude defines the helpers (`add`, `describe`, `visible`, `imgs`, `W`, `H`); the motion part
+ * scrolls the page once and defines `frame`, which the navigation and component parts use; the
+ * component part ends back at the top. Keep the order.
+ */
+import { COMPONENT_CHECKS } from "./components.js";
+import { CONTENT_CHECKS } from "./content.js";
+import { CONTRAST_CHECKS } from "./contrast.js";
+import { LAYOUT_CHECKS } from "./layout.js";
+import { MOTION_CHECKS } from "./motion.js";
+import { NAVIGATION_CHECKS } from "./navigation.js";
+import { PRELUDE } from "./prelude.js";
+
+export const RENDER_CHECK_SCRIPT = [
+  "(async () => {",
+  PRELUDE,
+  LAYOUT_CHECKS,
+  CONTRAST_CHECKS,
+  CONTENT_CHECKS,
+  MOTION_CHECKS,
+  NAVIGATION_CHECKS,
+  COMPONENT_CHECKS,
+  "  return ids.map((id) => out[id]);",
+  "})()",
+].join("\n");

package/dist/src/render/checks/layout.d.ts

@@ -0,0 +1,5 @@
+/**
+ * In-page checks, part of `RENDER_CHECK_SCRIPT`: overflow-x, img-alt / img-broken, heading-order.
+ * Plain source text, run inside the page; it shares the script's locals (see ./index.ts).
+ */
+export declare const LAYOUT_CHECKS = "  // overflow-x: the outermost elements that stick out past the screen's right edge.\n  const sw = document.documentElement.scrollWidth;\n  if (sw > W + 1) {\n    const clipped = (el) => {\n      for (let e = el.parentElement; e && e !== document.body; e = e.parentElement) {\n        const o = getComputedStyle(e).overflowX;\n        if (o !== \"visible\") return true;\n      }\n      return false;\n    };\n    for (const el of document.body.querySelectorAll(\"*\")) {\n      const r = el.getBoundingClientRect();\n      if (r.width === 0 || r.right <= W + 1) continue;\n      const p = el.parentElement && el.parentElement.getBoundingClientRect();\n      if (p && p.right > W + 1) continue;\n      if (clipped(el)) continue;\n      add(\"overflow-x\", el, Math.round(r.right - W) + \" px past the edge\");\n    }\n    if (out[\"overflow-x\"].count === 0) add(\"overflow-x\", document.body, \"the page is \" + (sw - W) + \" px wider than the screen\");\n  }\n\n  // img-alt / img-broken\n  for (const img of imgs) {\n    if (!img.hasAttribute(\"alt\") && img.getAttribute(\"role\") !== \"presentation\" && img.getAttribute(\"aria-hidden\") !== \"true\")\n      add(\"img-alt\", img, \"no alt attribute\");\n    if (img.getAttribute(\"src\") && img.complete && img.naturalWidth === 0) add(\"img-broken\", img, \"did not load\");\n  }\n\n  // heading-order\n  const hs = [...document.querySelectorAll(\"h1,h2,h3,h4,h5,h6\")].filter(visible);\n  const h1 = hs.filter((h) => h.tagName === \"H1\");\n  if (h1.length === 0) add(\"heading-order\", document.body, \"no level-1 heading\");\n  for (const h of h1.slice(1)) add(\"heading-order\", h, \"a second level-1 heading\");\n  let prev = 0;\n  for (const h of hs) {\n    const level = Number(h.tagName[1]);\n    if (prev && level > prev + 1) add(\"heading-order\", h, \"h\" + prev + \" \u2192 h\" + level + \" skips a level\");\n    prev = level;\n  }\n";

package/dist/src/render/checks/layout.js

@@ -0,0 +1,44 @@
+/**
+ * In-page checks, part of `RENDER_CHECK_SCRIPT`: overflow-x, img-alt / img-broken, heading-order.
+ * Plain source text, run inside the page; it shares the script's locals (see ./index.ts).
+ */
+export const LAYOUT_CHECKS = `  // overflow-x: the outermost elements that stick out past the screen's right edge.
+  const sw = document.documentElement.scrollWidth;
+  if (sw > W + 1) {
+    const clipped = (el) => {
+      for (let e = el.parentElement; e && e !== document.body; e = e.parentElement) {
+        const o = getComputedStyle(e).overflowX;
+        if (o !== "visible") return true;
+      }
+      return false;
+    };
+    for (const el of document.body.querySelectorAll("*")) {
+      const r = el.getBoundingClientRect();
+      if (r.width === 0 || r.right <= W + 1) continue;
+      const p = el.parentElement && el.parentElement.getBoundingClientRect();
+      if (p && p.right > W + 1) continue;
+      if (clipped(el)) continue;
+      add("overflow-x", el, Math.round(r.right - W) + " px past the edge");
+    }
+    if (out["overflow-x"].count === 0) add("overflow-x", document.body, "the page is " + (sw - W) + " px wider than the screen");
+  }
+
+  // img-alt / img-broken
+  for (const img of imgs) {
+    if (!img.hasAttribute("alt") && img.getAttribute("role") !== "presentation" && img.getAttribute("aria-hidden") !== "true")
+      add("img-alt", img, "no alt attribute");
+    if (img.getAttribute("src") && img.complete && img.naturalWidth === 0) add("img-broken", img, "did not load");
+  }
+
+  // heading-order
+  const hs = [...document.querySelectorAll("h1,h2,h3,h4,h5,h6")].filter(visible);
+  const h1 = hs.filter((h) => h.tagName === "H1");
+  if (h1.length === 0) add("heading-order", document.body, "no level-1 heading");
+  for (const h of h1.slice(1)) add("heading-order", h, "a second level-1 heading");
+  let prev = 0;
+  for (const h of hs) {
+    const level = Number(h.tagName[1]);
+    if (prev && level > prev + 1) add("heading-order", h, "h" + prev + " → h" + level + " skips a level");
+    prev = level;
+  }
+`;

package/dist/src/render/checks/motion.d.ts

@@ -0,0 +1,5 @@
+/**
+ * In-page checks, part of `RENDER_CHECK_SCRIPT`: The reader's scroll pass, then motion-cls, reduced-motion, motion-budget, flash; defines `frame`.
+ * Plain source text, run inside the page; it shares the script's locals (see ./index.ts).
+ */
+export declare const MOTION_CHECKS = "  // RFC-0024 \u00A78: scroll through the page once, as a reader would, so reveals play, then measure.\n  let shift = 0;\n  let po;\n  try {\n    po = new PerformanceObserver((list) => {\n      for (const e of list.getEntries()) if (!e.hadRecentInput) shift += e.value;\n    });\n    po.observe({ type: \"layout-shift\", buffered: true });\n  } catch {}\n  const pageH = document.documentElement.scrollHeight;\n  for (let y = 0; y < pageH; y += Math.round(H * 0.8)) {\n    window.scrollTo(0, y);\n    await new Promise((r) => setTimeout(r, 90));\n  }\n  window.scrollTo(0, pageH);\n  await new Promise((r) => setTimeout(r, 700));\n  if (po) {\n    for (const e of po.takeRecords()) if (!e.hadRecentInput) shift += e.value;\n    po.disconnect();\n  }\n  // motion-cls: more layout shift than Core Web Vitals' \"good\" threshold.\n  if (shift > 0.1) add(\"motion-cls\", document.body, \"layout shift \" + shift.toFixed(2) + \" while loading and scrolling (good is 0.1 or less)\");\n  // reduced-motion: with the reader asking for less, nothing stays hidden and nothing travels.\n  if (matchMedia(\"(prefers-reduced-motion: reduce)\").matches) {\n    for (const el of document.querySelectorAll(\"[data-ch-reveal]\"))\n      if (el.classList.contains(\"ch-pre\") || Number(getComputedStyle(el).opacity) === 0)\n        add(\"reduced-motion\", el, \"stays hidden for readers who ask for reduced motion\");\n    const moving = /transform|translate|scale|rotate|^top$|^left$|^right$|^bottom$|offset/;\n    for (const a of document.getAnimations ? document.getAnimations() : []) {\n      if (a.playState !== \"running\" || !a.effect || !a.effect.getKeyframes) continue;\n      const props = a.effect.getKeyframes().flatMap((k) => Object.keys(k));\n      if (!props.some((p) => moving.test(p))) continue;\n      const el = a.effect.target;\n      if (el) add(\"reduced-motion\", el, \"moves for readers who ask for reduced motion\");\n    }\n  }\n  // motion-budget: a page carries a few scroll effects and one scroll story, not a show.\n  const scrolls = document.querySelectorAll(\"[data-ch-scroll]\");\n  if (scrolls.length > 6) add(\"motion-budget\", scrolls[6], scrolls.length + \" scroll effects on the page; keep to 6 or fewer, the strongest ones\");\n  const stories = document.querySelectorAll(\".ch-scrolly\");\n  if (stories.length > 1) add(\"motion-budget\", stories[1], stories.length + \" scroll stories on the page; keep to one\");\n  const splits = document.querySelectorAll('[data-ch-reveal^=\"split-\"]');\n  if (splits.length > 2) add(\"motion-budget\", splits[2], splits.length + \" split headings or texts; keep to 2, for the lines that matter most\");\n  const ambients = document.querySelectorAll(\"[data-ch-ambient]\");\n  if (ambients.length > 2) add(\"motion-budget\", ambients[2], ambients.length + \" ambient backgrounds on the page; keep to 2, best one on the hero\");\n  const loops = document.querySelectorAll(\"[data-ch-loop], .ch-marquee, [data-ch-rotate]\");\n  if (loops.length > 2) add(\"motion-budget\", loops[2], loops.length + \" things that loop on the page; keep to 2\");\n  // flash: a running animation that repeats faster than three times a second and changes how\n  // bright something is (opacity, color, background, filter, visibility).\n  const bright = /opacity|color|background|filter|visibility|fill/i;\n  for (const a of document.getAnimations ? document.getAnimations() : []) {\n    if (a.playState !== \"running\" || !a.effect || !a.effect.getComputedTiming) continue;\n    const t = a.effect.getComputedTiming();\n    const each = Number(t.duration) / Math.max(0.0001, Math.abs(a.playbackRate || 1));\n    if (!(t.iterations > 1) || !(each > 0) || each >= 1000 / 3) continue;\n    const props = a.effect.getKeyframes ? a.effect.getKeyframes().flatMap((k) => Object.keys(k)) : [];\n    if (props.some((p) => bright.test(p)) && a.effect.target) add(\"flash\", a.effect.target, \"repeats \" + Math.round(1000 / each) + \" times a second\");\n  }\n  window.scrollTo(0, 0);\n  const frame = () => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)));\n  await frame();\n";

package/dist/src/render/checks/motion.js

@@ -0,0 +1,66 @@
+/**
+ * In-page checks, part of `RENDER_CHECK_SCRIPT`: The reader's scroll pass, then motion-cls, reduced-motion, motion-budget, flash; defines `frame`.
+ * Plain source text, run inside the page; it shares the script's locals (see ./index.ts).
+ */
+export const MOTION_CHECKS = `  // RFC-0024 §8: scroll through the page once, as a reader would, so reveals play, then measure.
+  let shift = 0;
+  let po;
+  try {
+    po = new PerformanceObserver((list) => {
+      for (const e of list.getEntries()) if (!e.hadRecentInput) shift += e.value;
+    });
+    po.observe({ type: "layout-shift", buffered: true });
+  } catch {}
+  const pageH = document.documentElement.scrollHeight;
+  for (let y = 0; y < pageH; y += Math.round(H * 0.8)) {
+    window.scrollTo(0, y);
+    await new Promise((r) => setTimeout(r, 90));
+  }
+  window.scrollTo(0, pageH);
+  await new Promise((r) => setTimeout(r, 700));
+  if (po) {
+    for (const e of po.takeRecords()) if (!e.hadRecentInput) shift += e.value;
+    po.disconnect();
+  }
+  // motion-cls: more layout shift than Core Web Vitals' "good" threshold.
+  if (shift > 0.1) add("motion-cls", document.body, "layout shift " + shift.toFixed(2) + " while loading and scrolling (good is 0.1 or less)");
+  // reduced-motion: with the reader asking for less, nothing stays hidden and nothing travels.
+  if (matchMedia("(prefers-reduced-motion: reduce)").matches) {
+    for (const el of document.querySelectorAll("[data-ch-reveal]"))
+      if (el.classList.contains("ch-pre") || Number(getComputedStyle(el).opacity) === 0)
+        add("reduced-motion", el, "stays hidden for readers who ask for reduced motion");
+    const moving = /transform|translate|scale|rotate|^top$|^left$|^right$|^bottom$|offset/;
+    for (const a of document.getAnimations ? document.getAnimations() : []) {
+      if (a.playState !== "running" || !a.effect || !a.effect.getKeyframes) continue;
+      const props = a.effect.getKeyframes().flatMap((k) => Object.keys(k));
+      if (!props.some((p) => moving.test(p))) continue;
+      const el = a.effect.target;
+      if (el) add("reduced-motion", el, "moves for readers who ask for reduced motion");
+    }
+  }
+  // motion-budget: a page carries a few scroll effects and one scroll story, not a show.
+  const scrolls = document.querySelectorAll("[data-ch-scroll]");
+  if (scrolls.length > 6) add("motion-budget", scrolls[6], scrolls.length + " scroll effects on the page; keep to 6 or fewer, the strongest ones");
+  const stories = document.querySelectorAll(".ch-scrolly");
+  if (stories.length > 1) add("motion-budget", stories[1], stories.length + " scroll stories on the page; keep to one");
+  const splits = document.querySelectorAll('[data-ch-reveal^="split-"]');
+  if (splits.length > 2) add("motion-budget", splits[2], splits.length + " split headings or texts; keep to 2, for the lines that matter most");
+  const ambients = document.querySelectorAll("[data-ch-ambient]");
+  if (ambients.length > 2) add("motion-budget", ambients[2], ambients.length + " ambient backgrounds on the page; keep to 2, best one on the hero");
+  const loops = document.querySelectorAll("[data-ch-loop], .ch-marquee, [data-ch-rotate]");
+  if (loops.length > 2) add("motion-budget", loops[2], loops.length + " things that loop on the page; keep to 2");
+  // flash: a running animation that repeats faster than three times a second and changes how
+  // bright something is (opacity, color, background, filter, visibility).
+  const bright = /opacity|color|background|filter|visibility|fill/i;
+  for (const a of document.getAnimations ? document.getAnimations() : []) {
+    if (a.playState !== "running" || !a.effect || !a.effect.getComputedTiming) continue;
+    const t = a.effect.getComputedTiming();
+    const each = Number(t.duration) / Math.max(0.0001, Math.abs(a.playbackRate || 1));
+    if (!(t.iterations > 1) || !(each > 0) || each >= 1000 / 3) continue;
+    const props = a.effect.getKeyframes ? a.effect.getKeyframes().flatMap((k) => Object.keys(k)) : [];
+    if (props.some((p) => bright.test(p)) && a.effect.target) add("flash", a.effect.target, "repeats " + Math.round(1000 / each) + " times a second");
+  }
+  window.scrollTo(0, 0);
+  const frame = () => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)));
+  await frame();
+`;

package/dist/src/render/checks/navigation.d.ts

@@ -0,0 +1,5 @@
+/**
+ * In-page checks, part of `RENDER_CHECK_SCRIPT`: skip-link, landmarks, header-contrast, focus-obscured.
+ * Plain source text, run inside the page; it shares the script's locals (see ./index.ts).
+ */
+export declare const NAVIGATION_CHECKS = "  // skip-link: the first focusable element is a link to the main content (or inside it).\n  const shown = (e) => e.getClientRects().length > 0 && getComputedStyle(e).visibility !== \"hidden\";\n  const focusables = [...document.querySelectorAll('a[href],button,input,select,textarea,summary,[tabindex]:not([tabindex=\"-1\"])')]\n    .filter((e) => !e.disabled && !e.closest(\"[inert],dialog:not([open]),[popover]:not(:popover-open)\") && shown(e));\n  const firstFocus = focusables[0];\n  if (firstFocus) {\n    const href = firstFocus.tagName === \"A\" ? firstFocus.getAttribute(\"href\") || \"\" : \"\";\n    const target = href.startsWith(\"#\") && href.length > 1 ? document.getElementById(decodeURIComponent(href.slice(1))) : null;\n    if (!target) add(\"skip-link\", firstFocus, \"the first thing Tab reaches is not a link to the main content\");\n    else if (!target.matches(\"main,[role=main]\") && !target.closest(\"main,[role=main]\")) add(\"skip-link\", firstFocus, \"it points at #\" + target.id + \", outside the main content\");\n  }\n\n  // landmarks: one banner header, one main, one footer (outside articles and sections), named menus.\n  const top = (sel) => [...document.querySelectorAll(sel)].filter((e) => shown(e) && !(e.parentElement && e.parentElement.closest(\"article,aside,main,nav,section,dialog\")));\n  const banners = top(\"header\"), mains = [...document.querySelectorAll(\"main,[role=main]\")].filter(shown), infos = top(\"footer\");\n  if (banners.length !== 1) add(\"landmarks\", banners[1] || document.body, banners.length + \" page headers (one is right)\");\n  if (mains.length !== 1) add(\"landmarks\", mains[1] || document.body, mains.length + \" main regions (one is right)\");\n  if (infos.length !== 1) add(\"landmarks\", infos[1] || document.body, infos.length + \" page footers (one is right)\");\n  const navs = [...document.querySelectorAll(\"nav\")].filter(shown);\n  if (navs.length > 1) for (const n of navs) if (!n.getAttribute(\"aria-label\") && !n.getAttribute(\"aria-labelledby\")) add(\"landmarks\", n, \"a menu without a name (aria-label), among \" + navs.length);\n\n  // header-contrast: a transparent header's text against what is under it, at the top of the page.\n  const clear = document.querySelector(\"header[data-transparent]\");\n  if (clear && !clear.hasAttribute(\"data-ch-scrolled\")) {\n    const done = new Set();\n    const tw = document.createTreeWalker(clear, NodeFilter.SHOW_TEXT);\n    while (tw.nextNode()) {\n      const el = tw.currentNode.parentElement;\n      if (!el || done.has(el) || !tw.currentNode.nodeValue.trim() || !visible(el)) continue;\n      done.add(el);\n      if (el.closest(\"[popover],dialog,.ch-menu__panel\")) continue;\n      const r = el.getBoundingClientRect();\n      if (r.width <= 1 || r.height <= 1) continue;\n      const cx = r.left + Math.min(r.width / 2, 12), cy = r.top + Math.min(r.height / 2, 10);\n      if (cy < 0 || cy >= H || cx < 0 || cx >= W) continue;\n      // Text on a fill of its own inside the header (a button, a field) is the contrast check's.\n      let own = false;\n      for (let e = el; e && e !== clear; e = e.parentElement) if (rgba(getComputedStyle(e).backgroundColor)[3] > 0.5) { own = true; break; }\n      if (own) continue;\n      let bg = null;\n      for (const e of document.elementsFromPoint(cx, cy)) {\n        if (clear.contains(e)) continue;\n        if (/^(IMG|VIDEO|CANVAS|IFRAME|PICTURE)$/.test(e.tagName)) break;\n        const c = rgba(getComputedStyle(e).backgroundColor);\n        if (c[3] > 0) { bg = over(c, [255, 255, 255]); break; }\n      }\n      if (!bg) bg = [255, 255, 255];\n      const st = getComputedStyle(el);\n      const got = ratio(over(rgba(st.color), bg), bg);\n      const big = parseFloat(st.fontSize) >= 24 || (parseFloat(st.fontSize) >= 18.66 && Number(st.fontWeight) >= 700);\n      if (got < (big ? 3 : 4.5)) add(\"header-contrast\", el, got.toFixed(1) + \":1 over the first band, needs \" + (big ? 3 : 4.5) + \":1\");\n    }\n  }\n\n  // focus-obscured: tabbing back up the page, a sticky or fixed header never covers the focused element.\n  const stuck = [...document.querySelectorAll(\"header,[data-ch-bar]\")].filter((e) => shown(e) && /sticky|fixed/.test(getComputedStyle(e).position));\n  if (stuck.length) {\n    const targets = [...document.querySelectorAll(\"main a[href],main button,main input,main summary,body > footer a[href]\")]\n      .filter((e) => shown(e) && visible(e)).slice(-40).reverse();\n    window.scrollTo(0, document.documentElement.scrollHeight);\n    await frame();\n    for (const el of targets) {\n      el.focus();\n      await frame();\n      const r = el.getBoundingClientRect();\n      const cx = Math.min(Math.max(r.left + r.width / 2, 0), W - 1), cy = Math.min(Math.max(r.top + r.height / 2, 0), H - 1);\n      const at = document.elementFromPoint(cx, cy);\n      const cover = at && !el.contains(at) && stuck.find((s) => s.contains(at));\n      if (cover) add(\"focus-obscured\", el, \"under the \" + (cover.tagName === \"HEADER\" ? \"sticky header\" : \"bar\") + \" when it has focus\");\n    }\n    if (document.activeElement && document.activeElement.blur) document.activeElement.blur();\n    window.scrollTo(0, 0);\n  }\n";

package/dist/src/render/checks/navigation.js

@@ -0,0 +1,78 @@
+/**
+ * In-page checks, part of `RENDER_CHECK_SCRIPT`: skip-link, landmarks, header-contrast, focus-obscured.
+ * Plain source text, run inside the page; it shares the script's locals (see ./index.ts).
+ */
+export const NAVIGATION_CHECKS = `  // skip-link: the first focusable element is a link to the main content (or inside it).
+  const shown = (e) => e.getClientRects().length > 0 && getComputedStyle(e).visibility !== "hidden";
+  const focusables = [...document.querySelectorAll('a[href],button,input,select,textarea,summary,[tabindex]:not([tabindex="-1"])')]
+    .filter((e) => !e.disabled && !e.closest("[inert],dialog:not([open]),[popover]:not(:popover-open)") && shown(e));
+  const firstFocus = focusables[0];
+  if (firstFocus) {
+    const href = firstFocus.tagName === "A" ? firstFocus.getAttribute("href") || "" : "";
+    const target = href.startsWith("#") && href.length > 1 ? document.getElementById(decodeURIComponent(href.slice(1))) : null;
+    if (!target) add("skip-link", firstFocus, "the first thing Tab reaches is not a link to the main content");
+    else if (!target.matches("main,[role=main]") && !target.closest("main,[role=main]")) add("skip-link", firstFocus, "it points at #" + target.id + ", outside the main content");
+  }
+
+  // landmarks: one banner header, one main, one footer (outside articles and sections), named menus.
+  const top = (sel) => [...document.querySelectorAll(sel)].filter((e) => shown(e) && !(e.parentElement && e.parentElement.closest("article,aside,main,nav,section,dialog")));
+  const banners = top("header"), mains = [...document.querySelectorAll("main,[role=main]")].filter(shown), infos = top("footer");
+  if (banners.length !== 1) add("landmarks", banners[1] || document.body, banners.length + " page headers (one is right)");
+  if (mains.length !== 1) add("landmarks", mains[1] || document.body, mains.length + " main regions (one is right)");
+  if (infos.length !== 1) add("landmarks", infos[1] || document.body, infos.length + " page footers (one is right)");
+  const navs = [...document.querySelectorAll("nav")].filter(shown);
+  if (navs.length > 1) for (const n of navs) if (!n.getAttribute("aria-label") && !n.getAttribute("aria-labelledby")) add("landmarks", n, "a menu without a name (aria-label), among " + navs.length);
+
+  // header-contrast: a transparent header's text against what is under it, at the top of the page.
+  const clear = document.querySelector("header[data-transparent]");
+  if (clear && !clear.hasAttribute("data-ch-scrolled")) {
+    const done = new Set();
+    const tw = document.createTreeWalker(clear, NodeFilter.SHOW_TEXT);
+    while (tw.nextNode()) {
+      const el = tw.currentNode.parentElement;
+      if (!el || done.has(el) || !tw.currentNode.nodeValue.trim() || !visible(el)) continue;
+      done.add(el);
+      if (el.closest("[popover],dialog,.ch-menu__panel")) continue;
+      const r = el.getBoundingClientRect();
+      if (r.width <= 1 || r.height <= 1) continue;
+      const cx = r.left + Math.min(r.width / 2, 12), cy = r.top + Math.min(r.height / 2, 10);
+      if (cy < 0 || cy >= H || cx < 0 || cx >= W) continue;
+      // Text on a fill of its own inside the header (a button, a field) is the contrast check's.
+      let own = false;
+      for (let e = el; e && e !== clear; e = e.parentElement) if (rgba(getComputedStyle(e).backgroundColor)[3] > 0.5) { own = true; break; }
+      if (own) continue;
+      let bg = null;
+      for (const e of document.elementsFromPoint(cx, cy)) {
+        if (clear.contains(e)) continue;
+        if (/^(IMG|VIDEO|CANVAS|IFRAME|PICTURE)$/.test(e.tagName)) break;
+        const c = rgba(getComputedStyle(e).backgroundColor);
+        if (c[3] > 0) { bg = over(c, [255, 255, 255]); break; }
+      }
+      if (!bg) bg = [255, 255, 255];
+      const st = getComputedStyle(el);
+      const got = ratio(over(rgba(st.color), bg), bg);
+      const big = parseFloat(st.fontSize) >= 24 || (parseFloat(st.fontSize) >= 18.66 && Number(st.fontWeight) >= 700);
+      if (got < (big ? 3 : 4.5)) add("header-contrast", el, got.toFixed(1) + ":1 over the first band, needs " + (big ? 3 : 4.5) + ":1");
+    }
+  }
+
+  // focus-obscured: tabbing back up the page, a sticky or fixed header never covers the focused element.
+  const stuck = [...document.querySelectorAll("header,[data-ch-bar]")].filter((e) => shown(e) && /sticky|fixed/.test(getComputedStyle(e).position));
+  if (stuck.length) {
+    const targets = [...document.querySelectorAll("main a[href],main button,main input,main summary,body > footer a[href]")]
+      .filter((e) => shown(e) && visible(e)).slice(-40).reverse();
+    window.scrollTo(0, document.documentElement.scrollHeight);
+    await frame();
+    for (const el of targets) {
+      el.focus();
+      await frame();
+      const r = el.getBoundingClientRect();
+      const cx = Math.min(Math.max(r.left + r.width / 2, 0), W - 1), cy = Math.min(Math.max(r.top + r.height / 2, 0), H - 1);
+      const at = document.elementFromPoint(cx, cy);
+      const cover = at && !el.contains(at) && stuck.find((s) => s.contains(at));
+      if (cover) add("focus-obscured", el, "under the " + (cover.tagName === "HEADER" ? "sticky header" : "bar") + " when it has focus");
+    }
+    if (document.activeElement && document.activeElement.blur) document.activeElement.blur();
+    window.scrollTo(0, 0);
+  }
+`;

package/dist/src/render/checks/prelude.d.ts

@@ -0,0 +1 @@
+export declare const PRELUDE: string;

package/dist/src/render/checks/prelude.js

@@ -0,0 +1,64 @@
+/**
+ * In-page checks, part of `RENDER_CHECK_SCRIPT`: Shared helpers (W, H, ids, out, describe, add, visible), lazy images, fonts, finished entrances.
+ * Plain source text, run inside the page; it shares the script's locals (see ./index.ts).
+ */
+import { RENDER_CHECK_IDS } from "../types.js";
+
+export const PRELUDE = `  const W = document.documentElement.clientWidth || window.innerWidth, H = window.innerHeight, MAX = 5;
+  const ids = ${JSON.stringify(RENDER_CHECK_IDS)};
+  const out = Object.fromEntries(ids.map((id) => [id, { id, count: 0, examples: [] }]));
+  const clip = (s, n) => (s.length > n ? s.slice(0, n - 1) + "…" : s);
+  const describe = (el) => {
+    if (el === document.body || el === document.documentElement) return "the page";
+    const parts = [];
+    const sec = el.closest && el.closest("[data-section-id]");
+    const comp = el.closest && el.closest("[data-component-id]");
+    if (sec) parts.push("section " + sec.getAttribute("data-section-id"));
+    else {
+      const mark = el.closest && el.closest("header,footer,nav,aside");
+      if (mark) parts.push("theme " + mark.tagName.toLowerCase() + " (not a section)");
+    }
+    if (comp) parts.push("component " + comp.getAttribute("data-component-id"));
+    let tag = el.tagName.toLowerCase();
+    if (el.id) tag += "#" + el.id;
+    else if (typeof el.className === "string" && el.className.trim())
+      tag += "." + el.className.trim().split(/\\s+/).slice(0, 2).join(".");
+    parts.push(tag);
+    const text = ((el.innerText || "").trim() || el.getAttribute("alt") || el.getAttribute("src") || "").replace(/\\s+/g, " ");
+    if (text) parts.push(JSON.stringify(clip(text, 48)));
+    return parts.join(" ");
+  };
+  const add = (id, el, note) => {
+    const c = out[id];
+    c.count++;
+    if (c.examples.length < MAX) c.examples.push(describe(el) + (note ? " — " + note : ""));
+  };
+  const visible = (el) => {
+    const r = el.getBoundingClientRect();
+    if (r.width === 0 && r.height === 0) return false;
+    const s = getComputedStyle(el);
+    // RFC-0024: content waiting for its reveal (.ch-pre) is content, whatever its opacity now.
+    const waiting = el.closest && el.closest(".ch-pre");
+    return s.visibility !== "hidden" && s.display !== "none" && (Number(s.opacity) > 0 || !!waiting);
+  };
+
+  // Lazy images load first, so broken ones show and the screenshots are complete.
+  const imgs = [...document.images];
+  // (which ones the page asked to be lazy is kept for carousel-lcp)
+  const wasLazy = new Set(imgs.filter((i) => i.loading === "lazy"));
+  for (const img of imgs) if (img.loading === "lazy") img.loading = "eager";
+  await Promise.race([
+    Promise.all(imgs.map((i) => i.complete ? null : new Promise((r) => {
+      i.addEventListener("load", r, { once: true });
+      i.addEventListener("error", r, { once: true });
+    }))),
+    new Promise((r) => setTimeout(r, 4000)),
+  ]);
+  if (document.fonts) await Promise.race([document.fonts.ready, new Promise((r) => setTimeout(r, 2000))]);
+  // RFC-0024: entrances that play on load finish first, so checks see the page's final state.
+  if (document.getAnimations)
+    await Promise.race([
+      Promise.all(document.getAnimations().map((a) => a.finished.catch(() => null))),
+      new Promise((r) => setTimeout(r, 2500)),
+    ]);
+`;

package/dist/src/render/limiter.d.ts

@@ -0,0 +1,11 @@
+/** Render budgets: per key per minute and per site per day, in memory. */
+/** Per key per minute and per site per day, in memory (each Worker isolate counts on its own). */
+export declare class RenderLimiter {
+    #private;
+    constructor(limits?: {
+        perKeyPerMinute?: number;
+        perSitePerDay?: number;
+    });
+    /** Counts one render, or says why not. */
+    take(key: string, site: string, now: Date): string | undefined;
+}

package/dist/src/render/limiter.js

@@ -0,0 +1,29 @@
+/** Render budgets: per key per minute and per site per day, in memory. */
+
+/** Per key per minute and per site per day, in memory (each Worker isolate counts on its own). */
+export class RenderLimiter {
+           #perKeyPerMinute        ;
+           #perSitePerDay        ;
+           #keys = new Map                  ();
+           #sites = new Map                                        ();
+  constructor(limits                                                       = {}) {
+    this.#perKeyPerMinute = limits.perKeyPerMinute ?? 10;
+    this.#perSitePerDay = limits.perSitePerDay ?? 200;
+  }
+  /** Counts one render, or says why not. */
+  take(key        , site        , now      )                     {
+    const t = now.getTime();
+    const recent = (this.#keys.get(key) ?? []).filter((x) => t - x < 60_000);
+    if (recent.length >= this.#perKeyPerMinute)
+      return `at most ${this.#perKeyPerMinute} renders a minute per key; try again in a minute`;
+    const day = now.toISOString().slice(0, 10);
+    const used = this.#sites.get(site);
+    const count = used?.day === day ? used.count : 0;
+    if (count >= this.#perSitePerDay)
+      return `at most ${this.#perSitePerDay} renders a day per site; use preview_page until tomorrow (UTC)`;
+    recent.push(t);
+    this.#keys.set(key, recent);
+    this.#sites.set(site, { day, count: count + 1 });
+    return undefined;
+  }
+}

package/dist/src/render/page.d.ts

@@ -0,0 +1,19 @@
+import { type PageRenderer, type RenderCheck, type RenderCheckId, type RenderOptions, type RenderResult } from "./types.js";
+export declare const sleep: (ms: number) => Promise<unknown>;
+/** Renders `url` at each width: checks first (they load lazy images), then the screenshots. */
+export declare function renderPage(renderer: PageRenderer, url: string, options: RenderOptions): Promise<RenderResult>;
+/**
+ * The content's height. Not the document's scrollHeight: a phone layout that overflows sideways
+ * widens the layout viewport and stretches it.
+ */
+export declare const PAGE_HEIGHT = "(() => {\n  const b = document.body;\n  if (!b) return document.documentElement.scrollHeight;\n  const s = getComputedStyle(b);\n  return b.scrollHeight + parseFloat(s.marginTop) + parseFloat(s.marginBottom);\n})()";
+/** What the in-page script returns for one width. */
+export interface PageCheck {
+    id: RenderCheckId;
+    count: number;
+    examples: string[];
+}
+export declare function mergeChecks(perWidth: readonly {
+    width: number;
+    checks: PageCheck[];
+}[]): RenderCheck[];

package/dist/src/render/page.js

@@ -0,0 +1,135 @@
+/** `renderPage`: checks at each width (one page per width), then the screenshots. */
+import { RENDER_CHECK_SCRIPT } from "./checks/index.js";
+import {
+                    
+  RENDER_CHECK_IDS,
+                   
+                     
+  RenderError,
+                     
+                    
+                     
+                  
+  VIEWPORT_HEIGHT,
+} from "./types.js";
+
+export const sleep = (ms        ) => new Promise((r) => setTimeout(r, ms));
+
+/** Renders `url` at each width: checks first (they load lazy images), then the screenshots. */
+export async function renderPage(
+  renderer              ,
+  url        ,
+  options               ,
+)                        {
+  const timeoutMs = options.timeoutMs ?? 20_000;
+  let session                           ;
+  let timer                                           ;
+  let done = false;
+  // Where a slow render was when it timed out, for the error.
+  let stage = "starting a browser";
+  const work = (async () => {
+    const opened = await renderer.session();
+    if (done) {
+      await opened.close().catch(() => {});
+      throw new RenderError("timed out");
+    }
+    session = opened;
+    const shots               = [];
+    const perWidth                                           = [];
+    for (const width of options.widths) {
+      if (done) throw new RenderError("timed out");
+      const vh = VIEWPORT_HEIGHT[width];
+      stage = `opening the page at ${width} px`;
+      const tab = await session.open(url, {
+        width,
+        height: vh,
+        scheme: options.scheme ?? "light",
+        reducedMotion: (options.motion ?? "static") !== "full",
+      });
+      try {
+        stage = `checking the page at ${width} px`;
+        const checks = await tab.evaluate             (RENDER_CHECK_SCRIPT);
+        perWidth.push({ width, checks: Array.isArray(checks) ? checks : [] });
+        const height = Math.max(vh, Math.ceil((await tab.evaluate        (PAGE_HEIGHT)) ?? vh));
+        const max = Math.max(1, options.maxImages ?? 4);
+        const frames = options.frames ? Math.min(6, Math.max(1, Math.round(options.frames))) : 0;
+        const count = frames || (options.fullPage ? Math.min(max, Math.ceil(height / vh)) : 1);
+        const images               = [];
+        stage = `taking screenshots at ${width} px`;
+        for (let i = 0; i < count; i++) {
+          // Frames spread over the whole page; otherwise one viewport after another, the last
+          // ending at the page's end so nothing is cut in half there.
+          const y = frames
+            ? Math.round((Math.max(0, height - vh) * i) / Math.max(1, count - 1))
+            : i === count - 1 && count * vh >= height
+              ? Math.max(0, height - vh)
+              : i * vh;
+          const at = await tab.evaluate        (`(window.scrollTo(0, ${y}), window.scrollY)`);
+          // A phone layout that overflows sideways may not scroll at all: stop rather than repeat.
+          if (i > 0 && Math.abs((at ?? 0) - y) > 2) break;
+          await sleep(frames ? 450 : 150);
+          images.push(await tab.screenshot(options.quality ?? 60));
+        }
+        const seen = frames ? height : images.length >= count ? count * vh : images.length * vh;
+        shots.push({ width, height, truncated: seen < height, images });
+      } finally {
+        await tab.close().catch(() => {});
+      }
+    }
+    return { shots, checks: mergeChecks(perWidth) };
+  })();
+  const timeout = new Promise       ((_, reject) => {
+    timer = setTimeout(
+      () =>
+        reject(new RenderError(`the page did not render within ${timeoutMs / 1000} s (${stage})`)),
+      timeoutMs,
+    );
+  });
+  try {
+    return await Promise.race([work, timeout]);
+  } finally {
+    done = true;
+    clearTimeout(timer);
+    work.catch(() => {});
+    await (session                             )?.close().catch(() => {});
+  }
+}
+
+/**
+ * The content's height. Not the document's scrollHeight: a phone layout that overflows sideways
+ * widens the layout viewport and stretches it.
+ */
+export const PAGE_HEIGHT = `(() => {
+  const b = document.body;
+  if (!b) return document.documentElement.scrollHeight;
+  const s = getComputedStyle(b);
+  return b.scrollHeight + parseFloat(s.marginTop) + parseFloat(s.marginBottom);
+})()`;
+
+/** What the in-page script returns for one width. */
+                            
+                    
+                
+                     
+ 
+
+export function mergeChecks(
+  perWidth                                                   ,
+)                {
+  const multi = perWidth.length > 1;
+  return RENDER_CHECK_IDS.map((id) => {
+    const merged              = { id, ok: true, count: 0, examples: [], widths: [] };
+    for (const { width, checks } of perWidth) {
+      const c = checks.find((x) => x.id === id);
+      if (!c || c.count === 0) continue;
+      merged.ok = false;
+      merged.count += c.count;
+      merged.widths.push(width);
+      for (const e of c.examples) {
+        if (merged.examples.length >= 6) break;
+        merged.examples.push(multi ? `@${width}: ${e}` : e);
+      }
+    }
+    return merged;
+  });
+}