konpeki 0.3.1 → 0.4.0

package/html/browser.ts

@@ -0,0 +1,103 @@
+import { chromium } from "playwright";
+import { PDFDocument } from "pdf-lib";
+import { documentServer } from "./server.ts";
+import { inspectHTMLPage, type Diagnostic } from "./inspect.ts";
+import { isGoogleFontResource } from "./document.ts";
+
+export async function browserDocument(input: string, options: { page?: number; format?: string; scale?: number; details?: boolean } = {}) {
+  if (options.format !== undefined && !["png", "pdf"].includes(options.format)) throw new Error("HTML exports support PNG and PDF. Whole-page SVG export is not supported.");
+  const scale = options.scale ?? 2;
+  if (!Number.isFinite(scale) || scale <= 0 || scale > 8) throw new Error("Scale must be greater than 0 and at most 8.");
+  const server = await documentServer(input);
+  let browser;
+  try {
+    const snapshot = await server.store.read();
+    const selected = options.page;
+    if (selected !== undefined && (!Number.isInteger(selected) || selected < 1 || selected > snapshot.pages.length))
+      throw new Error(`Page must be an integer from 1 to ${snapshot.pages.length}.`);
+    try { browser = await chromium.launch({ headless: true }); }
+    catch { throw new Error("Chromium could not start. Run `konpeki browser install` to install the pinned browser; Linux also needs Chromium's system libraries."); }
+    const context = await browser.newContext({ viewport: { width: 794, height: 1123 }, deviceScaleFactor: scale, serviceWorkers: "block" });
+    // Local document assets plus Google Fonts; other external requests, including
+    // those hidden in CSS, remain blocked.
+    await context.route("**/*", route => {
+      const request = route.request();
+      return request.url().startsWith(`${server.origin}${server.prefix}/`) || isGoogleFontResource(request.url(), request.resourceType()) ? route.continue() : route.abort();
+    });
+    const tab = await context.newPage(), pages = [], diagnostics: Diagnostic[] = [];
+    const cdp = await context.newCDPSession(tab);
+    await cdp.send("DOM.enable"); await cdp.send("CSS.enable");
+    const failed = new Set<string>();
+    tab.on("requestfailed", request => failed.add(request.url()));
+    tab.on("response", response => { if (!response.ok()) failed.add(response.url()); });
+    const pdf = options.format === "pdf" ? await PDFDocument.create() : undefined;
+    let bytes: Uint8Array | undefined;
+    for (let index = 0; index < snapshot.pages.length; index++) {
+      if (selected !== undefined && selected !== index + 1) continue;
+      if (options.format === "png" && selected === undefined && index > 0) break;
+      const id = snapshot.pages[index];
+      await tab.goto("about:blank");
+      await tab.setViewportSize({ width: 794, height: 1123 });
+      failed.clear();
+      const response = await tab.goto(`${server.origin}${server.prefix}/document/?page=${encodeURIComponent(id)}&revision=${snapshot.revision}`);
+      if (!response?.ok()) throw new Error("The HTML changed while rendering. Inspect and retry the latest source.");
+      await tab.evaluate(async () => {
+        await document.fonts.ready;
+        await Promise.all(Array.from(document.images).map(image => image.decode().catch(() => {})));
+      });
+      const element = tab.locator("[data-konpeki-current]");
+      const initial = await element.boundingBox();
+      if (!initial || initial.width <= 0 || initial.height <= 0 || initial.width > 8192 || initial.height > 8192) throw new Error("Invalid page dimensions. Use an explicit width and height up to 8192 CSS px.");
+      await tab.setViewportSize({ width: Math.ceil(initial.width), height: Math.ceil(initial.height) });
+      await tab.evaluate(async () => { await document.fonts.ready; await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve))); });
+      await tab.waitForLoadState("networkidle");
+      const report = await element.evaluate(inspectHTMLPage);
+      // CSS font-family and FontFaceSet cannot tell which font supplied a glyph.
+      // Chromium can: inspect direct text children, retaining their nearest ID
+      // even when an inline span has no ID. Include generated text as well.
+      const { root } = await cdp.send("DOM.getDocument", { depth: -1, pierce: true });
+      const { nodeId } = await cdp.send("DOM.querySelector", { nodeId: root.nodeId, selector: "[data-konpeki-current]" });
+      const { node } = await cdp.send("DOM.describeNode", { nodeId, depth: -1, pierce: true });
+      const fallbacks = new Map<string, Set<string>>();
+      async function auditFonts(node: typeof root, target: string) {
+        if (node.nodeType !== 1) return;
+        const attrs = node.attributes ?? [], idIndex = attrs.indexOf("id");
+        if (idIndex >= 0) target = attrs[idIndex + 1];
+        const { computedStyle } = await cdp.send("CSS.getComputedStyleForNode", { nodeId: node.nodeId });
+        const style = Object.fromEntries(computedStyle.map(s => [s.name, s.value]));
+        if (style.display === "none" || Number(style.opacity) === 0) return;
+        if (style.visibility === "visible" && (node.pseudoType || node.children?.some(child => child.nodeType === 3 && child.nodeValue.trim()))) {
+          const { fonts } = await cdp.send("CSS.getPlatformFontsForNode", { nodeId: node.nodeId });
+          for (const font of fonts) if (font.glyphCount > 0 && !font.isCustomFont) {
+            if (!fallbacks.has(target)) fallbacks.set(target, new Set());
+            fallbacks.get(target)!.add(font.familyName);
+          }
+        }
+        for (const child of [...node.children ?? [], ...node.pseudoElements ?? []]) await auditFonts(child, target);
+      }
+      await auditFonts(node, id);
+      for (const [target, fonts] of fallbacks) report.diagnostics.push({ code: "font-fallback", severity: "error", page: id, target,
+        message: `Text was drawn with installed fonts: ${[...fonts].join(", ")}. Load webfonts covering its families, styles, weights and glyphs from Google Fonts, local files or embedded data instead of relying on this machine.` });
+      if (Math.abs(report.width - initial.width) > .75 || Math.abs(report.height - initial.height) > .75)
+        throw new Error("Page dimensions depend on the viewport. Give pages a fixed CSS width and height; their content may use responsive layout.");
+      for (const resource of failed) report.diagnostics.push({ code: "missing-resource", severity: "error", page: id, target: id, message: `Resource did not load: ${resource.startsWith(`${server.origin}${server.prefix}/document/`) ? resource.slice(`${server.origin}${server.prefix}/document/`.length) : new URL(resource).origin + new URL(resource).pathname}. Use local assets or check access to Google Fonts.` });
+      diagnostics.push(...report.diagnostics);
+      pages.push({ pageNumber: index + 1, ...report, ...(options.details ? {} : { text: undefined }) });
+      if (options.format === "png") {
+        if (report.width * report.height * scale * scale > 64_000_000) throw new Error("PNG exceeds 64 million pixels; reduce --scale.");
+        bytes = await element.screenshot({ type: "png", animations: "disabled" });
+      } else if (pdf) {
+        // Print the screen layout on exactly one authored page, then merge pages
+        // to retain mixed paper sizes. Never invent document pagination.
+        await tab.emulateMedia({ media: "screen" });
+        await tab.addStyleTag({ content: `@page { size: ${report.width}px ${report.height}px; margin: 0; } body { print-color-adjust: exact; }` });
+        const part = await PDFDocument.load(await tab.pdf({ preferCSSPageSize: true, printBackground: true, margin: { top: 0, left: 0, right: 0, bottom: 0 } }));
+        if (part.getPageCount() !== 1) throw new Error(`Page ${index + 1} printed onto multiple sheets. Fix its overflow before exporting PDF.`);
+        for (const page of await pdf.copyPages(part, [0])) pdf.addPage(page);
+      }
+    }
+    if ((await server.store.read()).revision !== snapshot.revision) throw new Error("The source changed during rendering. Retry the latest revision.");
+    if (pdf) bytes = await pdf.save();
+    return { bytes, report: { schema: "konpeki-html-inspection/v1", revision: snapshot.revision, units: "css-pixels", ok: !diagnostics.some(d => d.severity === "error"), pages, diagnostics } };
+  } finally { await browser?.close(); await server.close(); }
+}

package/html/document.ts

@@ -0,0 +1,38 @@
+import { parse, parseFragment, serialize, type DefaultTreeAdapterMap } from "parse5";
+
+export const documentPolicy = "default-src 'none'; script-src 'none'; style-src 'unsafe-inline' 'self' https://fonts.googleapis.com; font-src 'self' data: https://fonts.gstatic.com; img-src 'self' data:; base-uri 'none'; form-action 'none'";
+
+/** The only external resources permitted by CLI inspection/export. */
+export function isGoogleFontResource(url: string, resourceType: string) {
+  const resource = new URL(url);
+  if (resource.protocol !== "https:" || resource.port || resource.username || resource.password) return false;
+  return resourceType === "stylesheet" && resource.hostname === "fonts.googleapis.com" && ["/css", "/css2"].includes(resource.pathname)
+    || resourceType === "font" && resource.hostname === "fonts.gstatic.com" && resource.pathname.startsWith("/s/");
+}
+
+/** A view of the source, never a serialization written back to it. Keep every
+ * page in the DOM so nth-child selectors and shared SVG definitions stay stable. */
+export function documentHTML(source: string, pageId: string) {
+  const tree = parse(source);
+  const html = tree.childNodes.find(n => n.nodeName === "html") as DefaultTreeAdapterMap["element"];
+  const head = html.childNodes.find(n => n.nodeName === "head") as DefaultTreeAdapterMap["element"];
+  const body = html.childNodes.find(n => n.nodeName === "body") as DefaultTreeAdapterMap["element"];
+  for (const child of body.childNodes) {
+    if (!("attrs" in child)) continue;
+    child.attrs = child.attrs.filter(a => a.name !== "data-konpeki-current");
+    if (child.attrs.some(a => a.name === "data-page") && child.attrs.some(a => a.name === "id" && a.value === pageId))
+      child.attrs.push({ name: "data-konpeki-current", value: "" });
+  }
+  // Serve at a directory URL: relative assets and SVG #fragments then retain
+  // their native meaning without a <base> that redirects fragment references.
+  head.childNodes.unshift(...parseFragment(`<meta http-equiv="Content-Security-Policy" content="${documentPolicy}">`).childNodes);
+  head.childNodes.push(...parseFragment(`<style>
+    html, body { margin: 0 !important; padding: 0 !important; }
+    body { display: flex !important; flex-direction: column !important; align-items: flex-start !important; }
+    body > [data-page] { margin: 0 !important; flex: none !important; }
+    body > [data-page]:not([data-konpeki-current]) { display: none !important; }
+    *, *::before, *::after { animation: none !important; transition: none !important; }
+    @media print { body > [data-page] { break-before: auto !important; break-after: auto !important; } }
+  </style>`).childNodes);
+  return serialize(tree);
+}

package/html/floor.ts

@@ -0,0 +1,34 @@
+import { readFileSync } from "node:fs";
+
+export type FloorRule = { ids: string[]; tier: "ban" | "default" | "verify"; check: "inspect" | "review"; text: string };
+
+const tiers: Record<string, FloorRule["tier"]> = { Bans: "ban", Defaults: "default", Verify: "verify" };
+
+/** The rules in skills/konpeki/floor.md, the single source for the review checklist. */
+export function floorRules(source = readFileSync(new URL("../skills/konpeki/floor.md", import.meta.url), "utf8")) {
+  const rules: FloorRule[] = [];
+  let tier: FloorRule["tier"] | undefined;
+  for (const line of source.split("\n")) {
+    const heading = /^## (\w+)/.exec(line);
+    if (heading) { tier = tiers[heading[1]]; continue; }
+    const rule = /^- ((?:`[a-z0-9-]+`(?:, )?)+) \((inspect|review)\):(?: (.*))?$/.exec(line);
+    if (rule && tier) rules.push({ ids: rule[1].match(/[a-z0-9-]+/g)!, tier, check: rule[2] as FloorRule["check"], text: rule[3] ?? "" });
+    else if (/^ {2}\S/.test(line) && rules.length) rules.at(-1)!.text = `${rules.at(-1)!.text} ${line.trim()}`.trim();
+  }
+  return rules;
+}
+
+/** The first sentence, ignoring full stops inside quoted examples. */
+function firstSentence(text: string) {
+  let quoted = false;
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === '"') quoted = !quoted;
+    else if (!quoted && text[i] === "." && (i + 1 === text.length || text[i + 1] === " ")) return text.slice(0, i + 1);
+  }
+  return text;
+}
+
+/** The first sentence of each rule that only a person looking at the page can check. */
+export function reviewChecklist(rules = floorRules()) {
+  return rules.filter(rule => rule.check === "review").map(rule => `${rule.ids[0]}: ${firstSentence(rule.text)}`);
+}

package/html/index.html

@@ -0,0 +1,5 @@
+<!doctype html>
+<html lang="en">
+<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Konpeki</title></head>
+<body><div id="root"></div><script type="module" src="./preview.tsx"></script></body>
+</html>

package/html/inspect.ts

@@ -0,0 +1,313 @@
+export type Bounds = { x: number; y: number; width: number; height: number };
+export type Diagnostic = { code: string; severity: "error" | "warning"; page: string; target: string; message: string };
+
+/** Self-contained so the same measurement runs in the review iframe and CLI's
+ * Chromium page. Range bounds describe font metrics, not glyph ink or leading. */
+export function inspectHTMLPage(page: HTMLElement) {
+  const doc = page.ownerDocument, win = doc.defaultView!;
+  const origin = page.getBoundingClientRect();
+  const diagnostics: Diagnostic[] = [], seen = new Set<string>();
+  const bounds = (r: DOMRect): Bounds => ({ x: r.x - origin.x, y: r.y - origin.y, width: r.width, height: r.height });
+  const outside = (r: DOMRect, box: DOMRect, x = true, y = true) =>
+    x && (r.left < box.left - .75 || r.right > box.right + .75) || y && (r.top < box.top - .75 || r.bottom > box.bottom + .75);
+  function report(code: string, element: Element, message: string, severity: "error" | "warning" = "error") {
+    const target = element.closest("[id]")?.id ?? page.id, key = `${code}/${target}`;
+    if (!seen.has(key)) { seen.add(key); diagnostics.push({ code, severity, page: page.id, target, message }); }
+  }
+  function visible(element: Element) {
+    if (element.closest("defs,clipPath,mask,symbol,marker,pattern,linearGradient,radialGradient")) return false;
+    const style = win.getComputedStyle(element);
+    for (let ancestor: Element | null = element; ancestor; ancestor = ancestor.parentElement)
+      if (Number(win.getComputedStyle(ancestor).opacity) === 0) return false;
+    return style.visibility === "visible" && style.display !== "none" && element.getClientRects().length > 0;
+  }
+  if (origin.width <= 0 || origin.height <= 0 || origin.width > 8192 || origin.height > 8192)
+    report("page-size", page, "Use explicit positive page dimensions no larger than 8192 CSS px per side.");
+  const elements = Array.from(page.querySelectorAll("*"));
+  const blocks = elements.filter(el => el.id && visible(el)).map(el => ({ id: el.id, tag: el.tagName.toLowerCase(), bounds: bounds(el.getBoundingClientRect()) }));
+  for (const element of elements) {
+    if (!visible(element)) continue;
+    if (outside(element.getBoundingClientRect(), origin)) report("page-overflow", element, "This element extends beyond the page. Recompose it; content does not continue onto another page automatically.");
+    if (element.tagName === "IMG" && !(element as HTMLImageElement).naturalWidth)
+      report("missing-image", element, "An image did not load. Use a local asset beside the HTML or an embedded data URL.");
+  }
+  const text: { target: string; content: string; bounds: Bounds[] }[] = [];
+  const lines: { parent: Element; rect: DOMRect }[] = [];
+  const textElements = new Set<Element>();
+  const minimumSizes: Record<string, number> = { presentation: 24, portrait: 24, square: 24, link: 24, article: 24, a4: 11, explainer: 24, gallery: 24 };
+  const preset = page.getAttribute("data-size") ?? "presentation", minimumSize = minimumSizes[preset];
+  const walker = doc.createTreeWalker(page, 4); // NodeFilter.SHOW_TEXT across iframe realms
+  let node: Node | null;
+  while ((node = walker.nextNode())) {
+    const parent = node.parentElement;
+    if (!node.textContent?.trim() || !parent || !visible(parent) || parent.closest("style,defs,title,desc")) continue;
+    const range = doc.createRange(); range.selectNodeContents(node);
+    const rects = Array.from(range.getClientRects()).filter(r => r.width > 0 && r.height > 0);
+    if (rects.length) text.push({ target: parent.closest("[id]")?.id ?? page.id, content: node.textContent, bounds: rects.map(bounds) });
+    if (rects.length) textElements.add(parent);
+    const style = win.getComputedStyle(parent);
+    if (rects.length && parseFloat(style.fontSize) < minimumSize)
+      report("small-text", parent, `Text is ${style.fontSize}; use at least ${minimumSize}px for ${preset}. Reduce content or recompose for the viewing size, rather than shrinking it.`, "warning");
+    let leading = parseFloat(style.lineHeight);
+    // Center an estimated HTML line box on the font-metric rectangle. SVG uses
+    // coordinate placement. Keep raw bounds for normal leading or non-horizontal
+    // text, and for transforms where an axis-aligned estimate is misleading.
+    for (let ancestor: Element | null = parent; ancestor; ancestor = ancestor.parentElement) {
+      const s = win.getComputedStyle(ancestor);
+      if (s.transform !== "none" || s.scale !== "none" || s.rotate !== "none" || Number(s.zoom) !== 1) leading = NaN;
+    }
+    for (const rect of rects) {
+      const line = parent.namespaceURI === "http://www.w3.org/1999/xhtml" && style.writingMode === "horizontal-tb" && leading > 0
+        ? new DOMRect(rect.x, rect.y + (rect.height - leading) / 2, rect.width, leading) : rect;
+      for (const previous of lines) {
+        if (previous.parent === parent) continue;
+        const other = previous.rect;
+        if (Math.min(line.right, other.right) - Math.max(line.left, other.left) > 1 &&
+            Math.min(line.bottom, other.bottom) - Math.max(line.top, other.top) > 1)
+          report("text-overlap", parent, `Text overlaps text in #${previous.parent.closest("[id]")?.id ?? page.id}. Separate their line boxes.`);
+      }
+      lines.push({ parent, rect: line });
+      if (outside(rect, origin)) report("text-overflow", parent, "Text extends beyond the page. Do not hide it or shrink required copy to fit.");
+      for (let ancestor: Element | null = parent; ancestor; ancestor = ancestor.parentElement) {
+        const style = win.getComputedStyle(ancestor), box = ancestor.getBoundingClientRect();
+        if (outside(rect, box, style.overflowX !== "visible", style.overflowY !== "visible"))
+          report("clipped-text", parent, "Text crosses a clipping or scrolling boundary. Increase space or revise the layout.");
+        if (ancestor === page) break;
+      }
+    }
+  }
+  // Composition rules with IDs from skills/konpeki/floor.md. Headlines are the
+  // title, display and section-heading roles, explicit or semantic.
+  const xhtml = "http://www.w3.org/1999/xhtml";
+  const roleOf = (el: Element) => el.getAttribute("data-type") ?? (el.tagName === "H1" ? "title" : "heading");
+  const leading = (style: CSSStyleDeclaration) => parseFloat(style.lineHeight) || parseFloat(style.fontSize) * 1.2;
+  // A figure set in a headline role ("2,000") is a metric, not a headline.
+  const headlines = Array.from(page.querySelectorAll('h1:not([data-type]), h2:not([data-type]), [data-type="title"], [data-type="display"], [data-type="heading"]'))
+    .filter(el => el.namespaceURI === xhtml && visible(el) && (el.textContent?.match(/\p{L}/gu)?.length ?? 0) > (el.textContent?.match(/\d/g)?.length ?? 0));
+  function block(element: Element) {
+    let current = element;
+    while (current !== page && current.parentElement && win.getComputedStyle(current).display.startsWith("inline")) current = current.parentElement;
+    return current;
+  }
+  const textBlocks = [...new Set(Array.from(textElements, block))].filter(el => el.namespaceURI === xhtml);
+  // Horizontal extent of the text itself: a block box spans its whole column.
+  function extent(element: Element) {
+    const range = doc.createRange(); range.selectNodeContents(element);
+    const rects = Array.from(range.getClientRects()).filter(r => r.width > 0 && r.height > 0);
+    return rects.length ? { left: Math.min(...rects.map(r => r.left)), right: Math.max(...rects.map(r => r.right)) } : element.getBoundingClientRect();
+  }
+  // Running heads repeat on other print pages, apart from their numbers.
+  const normalize = (text: string) => text.replace(/\s+/g, " ").replace(/\d+/g, "#").trim();
+  const printPages = page.getAttribute("data-size") === "a4"
+    ? Array.from(doc.querySelectorAll("body > [data-page]")).filter(p => p !== page && p.getAttribute("data-size") === "a4").map(p => normalize(p.textContent ?? ""))
+    : [];
+  function labels(heading: Element) {
+    const box = heading.getBoundingClientRect(), style = win.getComputedStyle(heading), headingInk = extent(heading);
+    // compareDocumentPosition bit 2: the block precedes the heading. The nearest
+    // preceding block and its row peers (a kicker left, a date right) are candidates.
+    const before = textBlocks.filter(b => !b.contains(heading) && !heading.contains(b) && heading.compareDocumentPosition(b) & 2);
+    const nearest = before.at(-1)?.getBoundingClientRect();
+    if (!nearest) return [];
+    return before.filter(label => {
+      const rect = label.getBoundingClientRect(), labelStyle = win.getComputedStyle(label), labelInk = extent(label);
+      const text = (label.textContent ?? "").replace(/\s+/g, " ").trim(), gap = box.top - rect.bottom;
+      if (rect.top >= nearest.bottom || rect.bottom <= nearest.top) return false;
+      if (gap < -1 || labelInk.right <= headingInk.left || labelInk.left >= headingInk.right || text.length > 48 || /[.!?]$/.test(text) || rect.height > leading(labelStyle) * 1.5) return false;
+      if (parseFloat(labelStyle.fontSize) >= parseFloat(style.fontSize) * .8 || label.closest('[data-kp-allow~="label-above-headline"]')) return false;
+      // A section heading's label hugs it; a page headline's label may sit anywhere above.
+      if (roleOf(heading) === "heading" && gap > leading(style)) return false;
+      return !printPages.some(other => other.includes(normalize(text)));
+    });
+  }
+  for (const heading of headlines)
+    for (const label of labels(heading))
+      report("label-above-headline", label, `"${(label.textContent ?? "").replace(/\s+/g, " ").trim()}" labels the headline below it. Delete it, or move the product, date or source into the headline, supporting line, caption or footer.`, "warning");
+  for (const heading of headlines) {
+    const words: { node: Node; top: number; text: string }[] = [];
+    const walker = doc.createTreeWalker(heading, 4);
+    for (let node: Node | null; (node = walker.nextNode());) {
+      for (const match of (node.textContent ?? "").matchAll(/\S+/g)) {
+        const range = doc.createRange();
+        range.setStart(node, match.index); range.setEnd(node, match.index + match[0].length);
+        const rect = range.getClientRects()[0];
+        if (rect) words.push({ node, top: rect.top, text: match[0] });
+      }
+    }
+    // Each <br> starts a deliberate segment; a segment that wraps must not end
+    // on one word after a fuller line. compareDocumentPosition bit 4: follows.
+    const size = parseFloat(win.getComputedStyle(heading).fontSize), breaks = Array.from(heading.querySelectorAll("br"));
+    const segments = new Map<number, (typeof words)[]>();
+    for (const word of words) {
+      const segment = breaks.filter(br => br.compareDocumentPosition(word.node) & 4).length;
+      const lines = segments.get(segment) ?? [], line = lines.at(-1);
+      if (line && word.top <= line[0].top + size / 2) line.push(word); else lines.push([word]);
+      segments.set(segment, lines);
+    }
+    // One word per line is a deliberate stack, not a stranded word.
+    const stranded = [...segments.values()].find(lines => lines.length > 1 && lines.at(-1)!.length === 1 && lines.at(-2)!.length > 1);
+    if (stranded) report("stranded-word", heading, `A headline line ends on one stranded word, "${stranded.at(-1)![0].text}". Reword it or change its measure rather than shrinking it.`, "warning");
+  }
+  // Contrast is deliberately limited to opaque sRGB text on solid ancestor
+  // backgrounds. Images, gradients, compositing and SVG paint need visual review.
+  const rgb = (value: string) => /^rgba?\(/.test(value) ? value.match(/[\d.]+/g)!.map(Number) : undefined;
+  const opaque = (color: number[] | undefined) => color && (color.length === 3 || color[3] === 1);
+  const luminance = (color: number[]) => color.slice(0, 3).reduce((sum, channel, i) => {
+    const c = channel / 255;
+    return sum + (c <= .04045 ? c / 12.92 : ((c + .055) / 1.055) ** 2.4) * [.2126, .7152, .0722][i];
+  }, 0);
+  for (const element of textElements) {
+    if (element.namespaceURI !== "http://www.w3.org/1999/xhtml") continue;
+    const style = win.getComputedStyle(element), foreground = rgb(style.color);
+    if (!opaque(foreground)) continue;
+    let background: number[] | undefined, uncertain = false;
+    for (let ancestor: Element | null = element; ancestor; ancestor = ancestor.parentElement) {
+      const s = win.getComputedStyle(ancestor), color = rgb(s.backgroundColor);
+      if (Number(s.opacity) !== 1 || s.filter !== "none" || s.backdropFilter !== "none" || s.mixBlendMode !== "normal") uncertain = true;
+      if (!background) {
+        if (!color || s.backgroundImage !== "none" || color.length === 4 && color[3] > 0 && color[3] < 1) uncertain = true;
+        if (opaque(color)) background = color;
+      }
+    }
+    // With no authored background, a light-scheme browser canvas is white.
+    if (!background && !win.getComputedStyle(doc.documentElement).colorScheme.includes("dark")) background = [255, 255, 255];
+    if (uncertain || !background) continue;
+    const a = luminance(foreground!), b = luminance(background);
+    const ratio = (Math.max(a, b) + .05) / (Math.min(a, b) + .05);
+    const size = parseFloat(style.fontSize), large = size >= 24 || size >= 18.6667 && Number(style.fontWeight) >= 700;
+    const minimum = large ? 3 : 4.5;
+    if (ratio < minimum) report("low-contrast", element, `Text contrast is ${ratio.toFixed(2)}:1; use at least ${minimum}:1 on this solid background.`);
+  }
+  // Compare used values, including inherited styles, to the page's tokens. CSSOM
+  // cannot distinguish a literal equal to a token from a var() reference.
+  const probe = doc.createElement("span");
+  probe.style.display = "none"; doc.body.append(probe);
+  const roles = ["fine", "caption", "body", "lead", "heading", "title", "display"];
+  const faces = Array.from(doc.fonts);
+  const familyName = (family: string) => family.trim().replace(/^(["'])(.*)\1$/, "$2").toLowerCase();
+  const primaryFamily = (family: string) => familyName(family.match(/^\s*("[^"]*"|'[^']*'|[^,]+)/)?.[0] ?? "");
+  function hasFace(family: string, weight: number, style = "normal") {
+    return faces.some(face => {
+      if (familyName(face.family) !== primaryFamily(family)) return false;
+      const weights = face.weight.replace("normal", "400").replace("bold", "700").split(/\s+/).map(Number);
+      const angles = (value: string) => value.match(/-?[\d.]+(?=deg)/g)?.map(Number) ?? [14];
+      const requested = angles(style)[0], available = angles(face.style);
+      const sameStyle = face.style === style || style.startsWith("oblique") && face.style.startsWith("oblique") && requested >= available[0] && requested <= (available[1] ?? available[0]);
+      return sameStyle && weight >= weights[0] && weight <= (weights[1] ?? weights[0]);
+    });
+  }
+  for (const element of textElements) {
+    const s = win.getComputedStyle(element);
+    // An undeclared family may use installed fonts; only the CLI can audit the
+    // actual glyph source. Declared faces must cover the requested treatment.
+    if (faces.some(face => familyName(face.family) === primaryFamily(s.fontFamily)) && !hasFace(s.fontFamily, Number(s.fontWeight), s.fontStyle))
+      report("font-face", element, `No declared face for ${s.fontFamily}, weight ${s.fontWeight}, style ${s.fontStyle}. Declare the matching webfont face; substitution or synthesis changes the intended text.`);
+  }
+  const colorTokens = ["bg", "fg", "muted", "line", "line-subtle", "line-strong", "inverse", "accent", "wash", "surface", "contrast", "on-contrast", "on-contrast-muted", "emphasis", "emphasis-wash", "complete", "attention", "blocked", ...Array.from({ length: 6 }, (_, i) => `category-${i + 1}`), ...Array.from({ length: 5 }, (_, i) => `sequence-${i + 1}`)];
+  function themeColors(style: CSSStyleDeclaration) {
+    probe.style.colorScheme = style.colorScheme;
+    return Object.fromEntries(colorTokens.map(token => {
+      const value = style.getPropertyValue(`--kp-${token}`);
+      probe.style.color = ""; probe.style.color = value;
+      return [token, value && probe.style.color ? win.getComputedStyle(probe).color : undefined];
+    }));
+  }
+  const pageStyle = win.getComputedStyle(page), version = pageStyle.getPropertyValue("--kp-theme").trim();
+  const type = Object.fromEntries(roles.map(role => [role, {
+    size: parseFloat(pageStyle.getPropertyValue(`--kp-font-${role}`)),
+    lineHeight: parseFloat(pageStyle.getPropertyValue(`--kp-leading-${role}`)),
+    weight: Number(pageStyle.getPropertyValue(`--kp-weight-${role}`)),
+    tracking: pageStyle.getPropertyValue(`--kp-tracking-${role}`).trim(),
+    family: pageStyle.getPropertyValue(role === "display" ? "--kp-font-family-display" : role === "heading" || role === "title" ? "--kp-font-family-heading" : "--kp-font-family").trim(),
+  }]));
+  const theme = version === "1" ? { version: 1, mode: pageStyle.colorScheme, unit: parseFloat(pageStyle.getPropertyValue("--kp-unit")), type } : undefined;
+  if (version && version !== "1") report("theme-version", page, `Unsupported --kp-theme version ${version}; theme checks were skipped.`, "warning");
+  if (theme && !page.closest('[data-theme="custom"]')) {
+    // Validate the active definition even when a token is not used by this page.
+    const required = [...colorTokens, "font-family", "font-family-heading", "font-family-display", "font-family-mono", "weight-strong", "weight-mono", "unit", "rule-width", "stroke", "stroke-heavy", "radius", "radius-small", "page-width", "page-height", "page-margin", ...[1, 2, 3, 4, 5, 6, 8, 10, 12, 16].map(n => `space-${n}`), ...roles.flatMap(role => ["font", "leading", "weight", "tracking"].map(property => `${property}-${role}`))];
+    const invalid = required.filter(token => !pageStyle.getPropertyValue(`--kp-${token}`).trim()).map(token => `missing --kp-${token}`);
+    const rootStyle = win.getComputedStyle(doc.documentElement);
+    const shadowed = [...roles.flatMap(role => [`font-${role}`, `leading-${role}`]), "page-width", "page-height", "page-margin"]
+      .filter(token => rootStyle.getPropertyValue(`--kp-${token}`).trim() && rootStyle.getPropertyValue(`--kp-${token}`).trim() !== pageStyle.getPropertyValue(`--kp-${token}`).trim());
+    if (shadowed.length) report("theme-root", page, `Root values differ from this page: ${shadowed.map(token => `--kp-${token}`).join(", ")}. Apply type and page overrides to [data-page] or [data-size], not :root.`, "warning");
+    let previous = 0;
+    for (const role of roles) {
+      const t = type[role];
+      const pixels = ["font", "leading"].every(property => /^\d+(?:\.\d+)?px$/.test(pageStyle.getPropertyValue(`--kp-${property}-${role}`).trim()));
+      if (!pixels || !(t.size > previous && t.lineHeight >= t.size && t.weight >= 1 && t.weight <= 1000) || !win.CSS.supports("letter-spacing", t.tracking)) invalid.push(`invalid ${role} type treatment`);
+      if (/^\d+(?:\.\d+)?px$/.test(pageStyle.getPropertyValue(`--kp-font-${role}`).trim()) && t.size > 0) previous = t.size;
+    }
+    const treatments = [...roles.map(role => ({ role, ...type[role] })),
+      { role: "strong", family: pageStyle.getPropertyValue("--kp-font-family"), weight: Number(pageStyle.getPropertyValue("--kp-weight-strong")) },
+      { role: "mono", family: pageStyle.getPropertyValue("--kp-font-family-mono"), weight: Number(pageStyle.getPropertyValue("--kp-weight-mono")) }];
+    const missingFaces = treatments.filter(t => t.family && t.weight > 0 && !hasFace(t.family, t.weight));
+    if (missingFaces.length) report("theme-font", page, `Missing declared normal faces: ${missingFaces.map(t => `${t.role} (${t.family}, ${t.weight})`).join("; ")}. Declare webfonts with matching families and weights.`);
+    const colors = themeColors(pageStyle);
+    for (const token of colorTokens) if (!colors[token]) invalid.push(`invalid --kp-${token} color`);
+    if (invalid.length) report("theme-definition", page, invalid.join("; "));
+    const textContrast: string[] = [], chartContrast: string[] = [];
+    const contrast = (foreground: string, background: string, minimum: number, failures: string[]) => {
+      const a = rgb(colors[foreground] ?? ""), b = rgb(colors[background] ?? "");
+      if (!opaque(a) || !opaque(b)) return;
+      const x = luminance(a!), y = luminance(b!), ratio = (Math.max(x, y) + .05) / (Math.min(x, y) + .05);
+      if (ratio < minimum) failures.push(`${foreground} on ${background}: ${ratio.toFixed(2)}:1; needs ${minimum}:1`);
+    };
+    for (const surface of ["bg", "surface", "wash"]) for (const ink of ["fg", "muted"]) contrast(ink, surface, 4.5, textContrast);
+    for (const ink of ["on-contrast", "on-contrast-muted"]) contrast(ink, "contrast", 4.5, textContrast);
+    contrast("accent", "bg", 4.5, textContrast); contrast("inverse", "accent", 4.5, textContrast);
+    const categories = Array.from({ length: 6 }, (_, i) => `category-${i + 1}`);
+    for (const token of categories) contrast(token, "bg", 3, chartContrast);
+    if (textContrast.length) report("theme-contrast", page, textContrast.join("; "));
+    if (chartContrast.length) report("theme-chart-contrast", page, chartContrast.join("; "), "warning");
+    if (new Set(categories.map(token => colors[token])).size !== categories.length)
+      report("theme-categories", page, "Category colors contain exact duplicates. Use distinct identities or supply non-color encodings.", "warning");
+  }
+  for (const element of [page, ...elements]) {
+    if (!visible(element) || element.closest('[data-theme="custom"]')) continue;
+    const style = win.getComputedStyle(element);
+    if (style.getPropertyValue("--kp-theme").trim() !== "1") continue;
+    if (element.hasAttribute("data-type") && !roles.includes(element.getAttribute("data-type")!))
+      report("theme-role", element, `Unknown data-type="${element.getAttribute("data-type")}". Use ${roles.join(", ")}.`, "warning");
+    const deviations: string[] = [];
+    // SVG text uses explicit coordinates, not CSS line-height, for line spacing.
+    if (textElements.has(element) && !roles.some(role =>
+      Math.abs(parseFloat(style.getPropertyValue(`--kp-font-${role}`)) - parseFloat(style.fontSize)) < .1 &&
+      (element.namespaceURI !== "http://www.w3.org/1999/xhtml" || Math.abs(parseFloat(style.getPropertyValue(`--kp-leading-${role}`)) - parseFloat(style.lineHeight)) < .1)))
+      deviations.push(`type pair ${style.fontSize}/${style.lineHeight}`);
+    const colors = Object.values(themeColors(style));
+    const values = [style.backgroundColor];
+    if (textElements.has(element)) values.push(element.namespaceURI === "http://www.w3.org/2000/svg" ? style.fill : style.color);
+    probe.style.fontSize = style.fontSize;
+    function themedLength(property: "borderTopWidth" | "borderTopLeftRadius" | "strokeWidth", value: string, tokens: string[]) {
+      return tokens.some(token => {
+        probe.style[property] = ""; probe.style[property] = style.getPropertyValue(`--kp-${token}`);
+        return probe.style[property] && win.getComputedStyle(probe)[property] === value;
+      });
+    }
+    probe.style.borderTopStyle = "solid";
+    const widths = ["rule-width", "stroke", "stroke-heavy"];
+    for (const side of ["Top", "Right", "Bottom", "Left"] as const) {
+      const width = style[`border${side}Width`];
+      if (parseFloat(width) > 0) {
+        values.push(style[`border${side}Color`]);
+        if (!themedLength("borderTopWidth", width, widths)) deviations.push(`border width ${width}`);
+      }
+    }
+    for (const corner of ["TopLeft", "TopRight", "BottomLeft", "BottomRight"] as const) {
+      const radius = style[`border${corner}Radius`];
+      if (radius !== "0px" && !themedLength("borderTopLeftRadius", radius, ["radius", "radius-small"])) deviations.push(`corner radius ${radius}`);
+    }
+    if (element.matches("path,rect,circle,ellipse,polygon,polyline,line")) {
+      if (!element.matches("line")) values.push(style.fill);
+      values.push(style.stroke);
+      if (style.stroke !== "none" && parseFloat(style.strokeWidth) > 0 && !themedLength("strokeWidth", style.strokeWidth, widths)) deviations.push(`stroke width ${style.strokeWidth}`);
+    }
+    for (const value of new Set(values))
+      if (value !== "none" && value !== "rgba(0, 0, 0, 0)" && !colors.includes(value)) deviations.push(`color ${value}`);
+    if (deviations.length) report("theme-value", element, `Outside the active theme: ${[...new Set(deviations)].join(", ")}. Use complete type roles and theme color/shape tokens, or data-theme="custom" for deliberately unthemed content.`, "warning");
+  }
+  probe.remove();
+  for (const link of doc.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"]'))
+    if (!link.sheet && !link.disabled) report("missing-stylesheet", page, "A stylesheet did not load. Keep stylesheets beside the HTML or inline them.");
+  for (const font of doc.fonts) if (font.status === "error") report("missing-font", page, `Font failed to load: ${font.family}.`);
+  return { id: page.id, width: origin.width, height: origin.height, blocks, text, theme, diagnostics };
+}

package/html/preview.css

@@ -0,0 +1,62 @@
+.html-heading { display: flex; flex-wrap: wrap; align-items: center; gap: 20px; }
+.html-heading a { color: var(--ui-muted); font-size: 12px; text-underline-offset: 3px; }
+.html-page { position: relative; width: 100%; background: white; box-shadow: 0 1px 3px #00000016, 0 12px 40px #0000000a; touch-action: none; -webkit-user-select: none; user-select: none; }
+/* Component outlines indicate focus without making the page look selected too. */
+.html-page:has(.html-outline):focus-visible,
+.workspace:has(.review-hints) .html-page:focus-visible { outline: none; }
+.html-page iframe { position: absolute; inset: 0; border: 0; transform-origin: top left; pointer-events: none; }
+.html-outline { position: absolute; border: 1.5px solid var(--accent); background: #007bbb06; pointer-events: none; }
+.html-pin { position: absolute; z-index: 3; display: grid; place-items: center; border: 2px solid white; background: #007bbb; color: white; border-radius: 50%; min-width: 22px; height: 22px; padding: 0 4px; font-size: 11px; line-height: 1; }
+.html-pin:hover:not(:disabled) { border-color: white; background: #006da7; color: white; }
+.revision-note-list li { align-items: center; }
+.revision-note-label { min-width: 0; overflow: hidden; white-space: nowrap; text-overflow: ellipsis; }
+.toast-dismiss { display: grid; place-items: center; }
+.toast-dismiss svg { width: 16px; height: 16px; fill: none; stroke: currentColor; stroke-width: 1.75; stroke-linecap: round; }
+.revision-notes > form > textarea { margin-top: 10px; }
+.html-guide { position: absolute; z-index: 2; pointer-events: none; border-color: #d43c8a; border-style: dashed; border-width: 0; }
+.html-guide.x { top: 0; height: 100%; border-left-width: 1px; }
+.html-guide.y { left: 0; width: 100%; border-top-width: 1px; }
+.html-diagnostics { position: relative; margin-left: auto; flex: none; color: #92570c; font-size: 12px; }
+.html-diagnostics summary { cursor: pointer; }
+.html-diagnostics ul { position: absolute; right: 0; z-index: 10; width: min(340px, 70vw); max-height: 280px; overflow: auto; margin-top: 6px; padding: 14px 14px 14px 28px; border: 1px solid #efd5ab; border-radius: 10px; background: #fffcf7; box-shadow: 0 6px 20px #00000014; color: #4f402b; white-space: normal; }
+.html-diagnostics li + li { margin-top: 8px; }
+.shortcut-launcher { margin-left: auto; padding: 4px 9px; border-color: transparent; background: transparent; color: var(--ui-muted); }
+kbd { font: 11px ui-monospace, monospace; }
+.review-status { position: fixed; left: 24px; bottom: 24px; z-index: 35; display: flex; align-items: center; gap: 12px; max-width: calc(100vw - 112px); min-height: 34px; padding: 4px 12px 4px 4px; border: 1px solid var(--ui-border); border-radius: 8px; background: var(--ui-surface); box-shadow: 0 2px 8px #00000006; color: var(--ui-muted); font-size: 11px; }
+.review-status button { padding: 5px 8px; border-color: transparent; background: transparent; color: var(--ui-text); font: 11px ui-monospace, monospace; white-space: nowrap; }
+.review-status > kbd { color: var(--accent); font-weight: 600; }
+.review-page-number { padding-left: 12px; border-left: 1px solid var(--ui-border); white-space: nowrap; font-variant-numeric: tabular-nums; }
+.review-hints { position: fixed; inset: 0; z-index: 36; pointer-events: none; }
+.review-hints > svg { position: absolute; inset: 0; width: 100%; height: 100%; fill: none; stroke: var(--accent); stroke-width: 1; }
+.review-hints rect { stroke-opacity: .18; }
+.review-hints line { stroke-opacity: .7; }
+.review-hint { position: absolute; height: 22px; padding: 2px 4px; border: 1px solid #fff; border-radius: 4px; background: #006da7; color: white; box-shadow: 0 1px 4px #00000024; font: 600 12px/16px ui-monospace, monospace; text-transform: uppercase; pointer-events: auto; }
+.review-hint:hover:not(:disabled) { border-color: white; background: #005584; color: white; }
+.review-hint > span { color: #afdbf2; }
+.review-queue-heading { display: flex; flex-direction: column; gap: 4px; margin-bottom: 8px; }
+.review-queue-heading > span { color: var(--ui-muted); font-size: 11px; }
+.revision-note-list li.review-note-active { background: var(--ui-selected); box-shadow: -8px 0 var(--ui-selected), 8px 0 var(--ui-selected); }
+.revision-note-target:focus-visible { outline-offset: 2px; }
+.revision-notes .primary kbd { opacity: .85; font: inherit; font-weight: 400; }
+.shortcut-help { width: 510px; max-width: calc(100vw - 32px); max-height: calc(100dvh - 48px); padding: 24px; border: 1px solid var(--ui-border); border-radius: 14px; background: var(--ui-surface); color: var(--ui-text); box-shadow: var(--ui-shadow); font-size: 13px; overscroll-behavior: contain; }
+.shortcut-help::backdrop { background: #20202040; }
+.shortcut-help header { display: flex; align-items: center; justify-content: space-between; margin-bottom: 18px; }
+.shortcut-help h2 { font-size: 17px; }
+.shortcut-help header button { display: grid; place-items: center; width: 28px; height: 28px; padding: 0; border-color: transparent; background: transparent; font-size: 20px; color: var(--ui-muted); }
+.vim-toggle { display: flex; align-items: center; gap: 10px; font-weight: 500; cursor: pointer; }
+.vim-toggle input { width: 16px; height: 16px; margin: 0; accent-color: var(--accent); }
+.shortcut-help > p { margin: 8px 0 20px; color: var(--ui-muted); font-size: 12px; }
+.shortcut-help h3 { display: flex; align-items: baseline; justify-content: space-between; margin: 18px 0 10px; font-size: 13px; font-weight: 500; }
+.shortcut-help h3 span { color: var(--ui-muted); font-size: 11px; font-weight: 400; }
+.shortcut-help dl { display: grid; grid-template-columns: 128px 1fr; align-items: baseline; gap: 10px 12px; margin: 0; padding-top: 12px; border-top: 1px solid var(--ui-border); }
+.shortcut-help dt { color: var(--ui-muted); }
+.shortcut-help dd { margin: 0; }
+.shortcut-help kbd { padding: 2px 4px; border: 1px solid var(--ui-border); border-radius: 4px; background: var(--ui-subtle); color: var(--ui-text); white-space: nowrap; }
+@media (max-width: 600px) {
+  .review-status { left: 16px; bottom: 20px; gap: 6px; padding-right: 8px; max-width: calc(100vw - 96px); }
+  .review-status > span:not(.review-page-number) { display: none; }
+  .review-page-number { padding-left: 8px; }
+  .shortcut-help { padding: 18px; }
+  .shortcut-help dl { grid-template-columns: 110px 1fr; gap: 10px; font-size: 12px; }
+  .review-actions:has(kbd) { flex-wrap: wrap; }
+}