konpeki 0.3.0 → 0.4.0

package/html/README.md

@@ -0,0 +1,140 @@
+# HTML, files, theme, and CLI
+
+This is the reference for Konpeki's source contract and runtime behavior. The
+[skill](../skills/konpeki/SKILL.md) owns workflow, its [floor](../skills/konpeki/floor.md)
+owns bans and defaults, and [AUTHORING.md](../AUTHORING.md) owns editorial and
+visual judgment.
+
+## Document and file contract
+
+- Author static HTML/CSS and inline SVG. Do not author JavaScript, applications,
+  interactive controls, or remote resources.
+- Each page is an explicit direct child of `<body>` with `data-page` and a
+  globally unique, stable `id`. Targetable HTML and SVG elements also need
+  globally unique, stable IDs.
+- CSS defines fixed page width and height, at most 8192 CSS px per side. Pages
+  may differ in size. Page breaks are explicit; overflow is not paginated.
+- Keep images, stylesheets, and licensed fonts beside the HTML with relative
+  paths, or embed them. The only remote exception is Google Fonts from
+  `fonts.googleapis.com/css2` and `fonts.gstatic.com`; it requires network access.
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <link rel="stylesheet" href="theme.css">
+  </head>
+  <body>
+    <main id="page-1" data-page data-size="link">
+      <h1 id="title">A clear headline</h1>
+    </main>
+  </body>
+</html>
+```
+
+## Themes
+
+Link `theme.css` for the default light-blue theme. Read [Use a theme](theme.md)
+for its `--kp-`-prefixed public tokens, complete type roles, page presets, and asset
+requirements. A compatible entry point sets `--kp-theme: 1`; the base alone does
+not. Keep the imported `theme-base.css` and referenced fonts beside the entry
+point. Adapt a copy of the default when a brief brings its own look.
+
+For deliberately unthemed content, set `data-theme="custom"` on its ancestor.
+This skips theme-value checks in that subtree and definition checks on an
+opted-out page, but keeps layout and resource checks. An alternative implementing
+the contract does not need this opt-out.
+
+## Diagnostics
+
+`inspect` detects page and text overflow, clipped text, missing resources,
+inter-element text line-box overlap, and opaque sRGB HTML text contrast against
+solid ancestor backgrounds. Contrast thresholds are 3:1 for large text and
+4.5:1 otherwise. Contrast inspection skips SVG text, gradients, images,
+transparency, and compositing it cannot evaluate reliably.
+
+Floor warnings use the rule ID from the [authoring floor](../skills/konpeki/floor.md)
+as their code. `label-above-headline` flags a short, smaller line directly above
+a title, display or section heading in the same column; running heads repeated
+across A4 pages, full sentences and metric figures are not flagged, and
+`data-kp-allow="label-above-headline"` on the label records a deliberate
+exception. `stranded-word` flags a headline line that holds one word after a fuller
+line, within each `<br>`-separated part; a line a `<br>` isolates is deliberate. The base balances headline roles and
+sets `text-wrap: pretty` on pages to avoid most stranded words.
+
+`small-text` warns below 24 CSS px on screen presets and 11 CSS px on A4,
+including unthemed HTML and SVG text. The default preset is presentation.
+These are computed font-size floors, not a guarantee of legibility after SVG
+viewBox scaling, CSS transforms, or reduction to the final viewing size. Unknown
+custom presets have no assumed floor. Review screen graphics at their intended
+size and print pages at actual size; warnings do not block export.
+
+For opted-in themes, it also checks the active definition and compares used
+size/leading pairs, colors and shape treatments to its tokens. See the [theme diagnostics](theme-authoring.md#verify-a-theme)
+for required roles and contrast pairs. `inspect` includes each page's resolved
+type treatments under `theme.type`, so authors can plan with the actual sizes.
+
+CLI inspection checks which fonts actually drew the text. Installed-font fallback
+is an error, including on unthemed pages. Both CLI and preview check declared
+weight/style coverage; only CLI can audit actual glyph fallback. Load the required
+licensed faces and subsets from Google Fonts, local files, or embedded data
+instead of relying on the machine. The default theme uses Google Fonts and needs
+network access during preview and export; finished PNGs and PDFs do not.
+
+HTML overlap uses estimated line-height boxes rather than raw font rectangles;
+SVG, normal leading and transformed text retain range bounds. These are not glyph
+ink measurements, and automated checks cannot establish factual
+correctness or visual quality. Inspect rendered output. A render with diagnostic
+errors exits nonzero and writes no output.
+
+## CLI
+
+```text
+konpeki validate document.html
+konpeki inspect document.html [--page N] [--details]
+konpeki check document.html
+konpeki render document.html [--page N] [--format png|pdf] [--scale 2] [--output file]
+konpeki preview document.html [--host host] [--port port] [--json]
+konpeki browser install
+```
+
+Pages are one-based. HTML export supports PNG and PDF only. PNG defaults to page
+1; PDF includes all pages unless `--page N` is supplied and preserves mixed page
+sizes. `--scale` affects PNG only. Outputs are exclusive and never overwritten.
+
+Inspection and export require the pinned Chromium installed by `browser install`;
+preview does not. Preview chooses another available port when its default is
+busy, while an explicit `--port` is strict.
+
+Preview comments remain browser-local. **Copy & clear** copies the full local
+document path, comments, and target IDs for pasting into an agent conversation.
+Small moves edit translation only; they do not reorder source. Deletion may
+reflow content. Reread current source and preserve unrelated edits when applying
+feedback.
+
+## Keyboard review
+
+Open **Keyboard shortcuts** (`?`) and enable **Vim review mode**. The preference
+is remembered in this browser. With it off, the existing mouse and comment
+shortcuts are unchanged.
+
+| Context | Keys | Action |
+| --- | --- | --- |
+| Canvas | `f`, then hint letters | Comment on a visible element of the current page |
+| Canvas | `c` / `Shift+C` | Comment on the selection / entire current page |
+| Canvas | `h j k l` | Pan left, down, up, right |
+| Canvas | `[` / `]`, `gg` / `G` | Previous / next page, first / last page; keep zoom |
+| Canvas | `+` or `=`, `-`, `0` | Zoom in, zoom out, fit and center current page |
+| Canvas | `q` | Open all pending comments |
+| Comment | `⌘/Ctrl+Enter` | Add and return to the canvas without changing the viewport |
+| Pending comments | `j` / `k`, `Enter` | Select a comment, reveal its target and notes |
+| Pending comments | `⌘/Ctrl+Enter` | Copy & clear; comments stay intact if copying fails |
+| Review | `Esc` | Back one level, preserving unfinished drafts until reload |
+
+The current page follows navigation and panning. Hints use stable element IDs,
+exclude hidden/offscreen targets, and keep their codes while filtering.
+`Backspace` corrects a hint prefix; `Esc` cancels. Moving the viewport or updating
+the source cancels hints rather than reusing stale geometry. Letter shortcuts are
+suspended inside text inputs and during IME composition. Review mode does not
+add Vim text editing or bare-letter source-deletion commands.

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>