konpeki 0.3.0 → 0.4.0

package/html/server.ts

@@ -0,0 +1,99 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { createServer as createHTTPServer } from "node:http";
+import { readFile, realpath } from "node:fs/promises";
+import { dirname, extname, isAbsolute, relative, resolve } from "node:path";
+import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { createServer } from "vite";
+import { fileSource } from "./source.ts";
+import { documentHTML, documentPolicy } from "./document.ts";
+
+const types: Record<string, string> = { ".css": "text/css", ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif", ".svg": "image/svg+xml", ".woff": "font/woff", ".woff2": "font/woff2", ".ttf": "font/ttf", ".otf": "font/otf" };
+export const sessionRoute = "/__konpeki/html";
+
+/** Same authenticated document/asset surface for preview and browser exports. */
+export function htmlSession(path: string, token = randomBytes(24).toString("base64url")) {
+  const store = fileSource(resolve(path));
+  const prefix = `${sessionRoute}/${token}`;
+  function send(res: ServerResponse, status: number, value: unknown) {
+    res.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store", "Referrer-Policy": "no-referrer" });
+    res.end(JSON.stringify(value));
+  }
+  async function handler(req: IncomingMessage, res: ServerResponse, next: () => void) {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    if (!url.pathname.startsWith(sessionRoute)) return next();
+    try {
+      if (url.pathname === sessionRoute) {
+        if (req.headers["x-konpeki-session"] !== token) return send(res, 403, { error: "Invalid preview session." });
+        if (req.method === "GET") return send(res, 200, await store.read());
+        if (req.method !== "PATCH") return send(res, 405, { error: "Method not allowed." });
+        let size = 0; const chunks: Buffer[] = [];
+        for await (const chunk of req) {
+          size += chunk.length;
+          if (size > 16384) throw Object.assign(new Error("Correction is too large."), { status: 413 });
+          chunks.push(chunk);
+        }
+        const body = JSON.parse(Buffer.concat(chunks).toString());
+        if (!body || typeof body.revision !== "string" || !body.edit || !["move", "delete", "undo"].includes(body.edit.kind))
+          return send(res, 400, { error: "Invalid correction." });
+        return send(res, 200, await store.edit(body.revision, body.edit));
+      }
+      if (!url.pathname.startsWith(`${prefix}/`)) return send(res, 403, { error: "Invalid preview session." });
+      if (req.method !== "GET") return send(res, 405, { error: "Method not allowed." });
+      if (url.pathname === `${prefix}/document/`) {
+        const snapshot = await store.read();
+        if (url.searchParams.has("revision") && url.searchParams.get("revision") !== snapshot.revision)
+          return send(res, 409, { error: "The source changed. Retry with its latest revision." });
+        const page = url.searchParams.get("page") ?? snapshot.pages[0];
+        if (!snapshot.pages.includes(page)) return send(res, 404, { error: "Unknown page." });
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Content-Security-Policy": documentPolicy, "Cache-Control": "no-store", "Referrer-Policy": "no-referrer", "X-Content-Type-Options": "nosniff" });
+        return res.end(documentHTML(snapshot.source, page));
+      }
+      const assets = `${prefix}/document/`;
+      if (!url.pathname.startsWith(assets)) return send(res, 404, { error: "Unknown resource." });
+      const name = decodeURIComponent(url.pathname.slice(assets.length));
+      const type = types[extname(name).toLowerCase()];
+      if (!type || name.split(/[\\/]/).some(part => part.startsWith("."))) return send(res, 403, { error: "Only local image, font and CSS assets are served." });
+      let base = await realpath(dirname(resolve(path))), file: string;
+      try { file = await realpath(resolve(base, name)); }
+      catch (error) {
+        // A linked default theme is available in previews and fixtures. Copies
+        // made by prepare-document carry these assets beside the HTML instead.
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT" || !/^theme(?:-base)?\.css$/.test(name)) throw error;
+        base = fileURLToPath(new URL("../", import.meta.url));
+        file = await realpath(resolve(base, name));
+      }
+      const within = relative(base, file);
+      if (isAbsolute(within) || within.startsWith("..")) return send(res, 403, { error: "Asset is outside the document directory." });
+      const bytes = await readFile(file);
+      res.writeHead(200, { "Content-Type": type, "Cache-Control": "no-store", "Content-Security-Policy": documentPolicy, "X-Content-Type-Options": "nosniff" });
+      res.end(bytes);
+    } catch (error) {
+      const status = error instanceof SyntaxError || error instanceof URIError ? 400 : (error as { code?: string }).code === "ENOENT" ? 404 : Number((error as { status?: number }).status ?? 500);
+      send(res, status, { error: error instanceof Error ? error.message : "Preview failed." });
+    }
+  }
+  return { token, prefix, store, handler };
+}
+
+export async function documentServer(path: string) {
+  const session = htmlSession(path);
+  await session.store.read();
+  const server = createHTTPServer((req, res) => void session.handler(req, res, () => { res.writeHead(404); res.end(); }));
+  await new Promise<void>((resolve, reject) => { server.once("error", reject); server.listen(0, "127.0.0.1", () => resolve()); });
+  const address = server.address() as { port: number };
+  return { ...session, origin: `http://127.0.0.1:${address.port}`, close: () => new Promise<void>((resolve, reject) => server.close(e => e ? reject(e) : resolve())) };
+}
+
+export async function previewHTML(path: string, host: string, port: number, root: string, strictPort = false) {
+  const session = htmlSession(path);
+  await session.store.read();
+  const server = await createServer({ root, configFile: false, logLevel: "silent", server: {
+    host, port, strictPort,
+    fs: { allow: [root, dirname(fileURLToPath(import.meta.resolve("@fontsource/ibm-plex-sans/package.json")))], deny: [".env", ".env.*", "*.{crt,pem,key,p12,pfx}", ".npmrc", "**/.git/**"] },
+  }, plugins: [{ name: "konpeki-html", configureServer(server) { server.middlewares.use((req, res, next) => void session.handler(req, res, next)); } }] });
+  try { await server.listen(); } catch (e) { await server.close(); throw e; }
+  const address = server.httpServer!.address() as { port: number };
+  const displayHost = host === "0.0.0.0" || host === "::" ? "localhost" : host;
+  return { server, url: `http://${displayHost.includes(":") ? `[${displayHost}]` : displayHost}:${address.port}/html/?session=${session.token}` };
+}

package/html/source.ts

@@ -0,0 +1,104 @@
+import { createHash, randomBytes } from "node:crypto";
+import { readFile, writeFile, rename, rm } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { parse, type DefaultTreeAdapterMap } from "parse5";
+import postcss from "postcss";
+
+type Element = DefaultTreeAdapterMap["element"];
+export type Edit = { page: string; id: string } & ({ kind: "move"; translate: string } | { kind: "delete" });
+export const revision = (source: string) => createHash("sha256").update(source).digest("hex");
+const attr = (node: Element, name: string) => node.attrs.find(a => a.name === name)?.value;
+function fail(message: string, status = 422): never { throw Object.assign(new Error(message), { status }); }
+
+export function inspectSource(source: string) {
+  const tree = parse(source, { sourceCodeLocationInfo: true, onParseError(error) {
+    if (error.code === "duplicate-attribute") fail("Duplicate HTML attributes are ambiguous; remove them before editing.");
+  } });
+  const elements: Element[] = [];
+  function visit(node: DefaultTreeAdapterMap["node"]) {
+    if ("tagName" in node) elements.push(node);
+    if ("childNodes" in node) node.childNodes.forEach(visit);
+  }
+  visit(tree);
+  const pages = elements.filter(node => attr(node, "data-page") !== undefined);
+  if (!pages.length) fail("Add an id and data-page to each page element.");
+  const ids = new Set<string>();
+  for (const node of elements) {
+    if (["script", "iframe", "object", "embed", "base", "template", "form", "input", "button", "textarea", "select", "animate", "animatetransform", "set"].includes(node.tagName.toLowerCase()) ||
+        node.tagName === "meta" && attr(node, "http-equiv") !== undefined ||
+        node.attrs.some(a => /^on/i.test(a.name) || ["href", "src", "action"].includes(a.name) && /^\s*javascript:/i.test(a.value)))
+      fail("Documents must be static HTML/CSS and inline SVG, without scripts, event handlers, embedded applications or controls.");
+    const id = attr(node, "id");
+    if (id !== undefined && (!id || ids.has(id))) fail("Element IDs must be nonempty and unique within the HTML file.");
+    if (id) ids.add(id);
+  }
+  for (const page of pages) {
+    if (!attr(page, "id") || page.parentNode?.nodeName !== "body")
+      fail("Pages need an id and must be direct children of body.");
+  }
+  return { pages, elements };
+}
+
+export function patchSource(source: string, edit: Edit) {
+  const { pages, elements } = inspectSource(source);
+  const page = pages.find(node => attr(node, "id") === edit.page);
+  const node = elements.find(node => attr(node, "id") === edit.id);
+  if (!page || !node) fail("The selected page or element no longer exists.");
+  let ancestor: DefaultTreeAdapterMap["node"] | undefined = node;
+  while (ancestor && ancestor !== page) ancestor = "parentNode" in ancestor ? ancestor.parentNode ?? undefined : undefined;
+  if (!ancestor || node === page) fail("Select an element inside the page.");
+  const location = node.sourceCodeLocation;
+  if (!location?.startTag) fail("This element does not have an unambiguous source location.");
+  if (edit.kind === "delete") return source.slice(0, location.startOffset) + source.slice(location.endOffset);
+  if (edit.kind !== "move" || typeof edit.translate !== "string" || !/^-?\d+(?:\.\d+)?px -?\d+(?:\.\d+)?px$/.test(edit.translate) || edit.translate.length > 100)
+    fail("Invalid correction.");
+  // Parse the authored CSS, not CSSOM's normalized serialization. PostCSS keeps
+  // unrelated declaration values, comments and whitespace, including hex colors.
+  // Inline styles have no source maps; never follow authored sourceMappingURLs.
+  let css;
+  try { css = postcss.parse(attr(node, "style") ?? "", { map: false }); }
+  catch { fail("The inline style could not be parsed. Correct it in source before moving."); }
+  const declarations = css.nodes.filter(n => n.type === "decl" && n.prop.toLowerCase() === "translate");
+  for (const declaration of declarations) if (declaration.type === "decl") declaration.value = edit.translate;
+  if (!declarations.length) css.append({ prop: "translate", value: edit.translate });
+  css.raws.semicolon = true;
+  const escaped = css.toString().replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;");
+  const style = location.attrs?.style;
+  const start = style?.startOffset ?? location.startTag.endOffset - (source[location.startTag.endOffset - 2] === "/" ? 2 : 1);
+  const end = style?.endOffset ?? start;
+  return source.slice(0, start) + `${style ? "" : " "}style="${escaped}"` + source.slice(end);
+}
+
+export function fileSource(path: string) {
+  path = resolve(path);
+  let queue: Promise<unknown> = Promise.resolve();
+  const history: { before: string; after: string }[] = [];
+  async function read() {
+    const source = await readFile(path, "utf8");
+    const { pages } = inspectSource(source);
+    return { source, revision: revision(source), name: basename(path), path, key: revision(path), pages: pages.map(p => attr(p, "id")!) };
+  }
+  function edit(expected: string, change: Edit | { kind: "undo" }) {
+    const result = queue.then(async () => {
+      const current = await read();
+      if (current.revision !== expected) fail("Source changed outside this preview. Reloaded the latest file; retry your correction.", 409);
+      const previous = history.at(-1);
+      if (change.kind === "undo" && (!previous || previous.after !== current.revision))
+        fail("Nothing safe to undo: the source may have changed externally.", 409);
+      const next = change.kind === "undo" ? previous!.before : patchSource(current.source, change);
+      inspectSource(next);
+      const temporary = join(dirname(path), `.${basename(path)}.${randomBytes(8).toString("hex")}.tmp`);
+      try {
+        await writeFile(temporary, next, { flag: "wx" });
+        if (revision(await readFile(path, "utf8")) !== current.revision) fail("Source changed while saving. Retry your correction.", 409);
+        await rename(temporary, path);
+      } finally { await rm(temporary, { force: true }); }
+      if (change.kind === "undo") history.pop();
+      else { history.push({ before: current.source, after: revision(next) }); if (history.length > 30) history.shift(); }
+      return read();
+    });
+    queue = result.catch(() => {});
+    return result;
+  }
+  return { read, edit };
+}

package/html/starter.ts

@@ -0,0 +1,6 @@
+import starter from "../skills/konpeki/assets/blank.html?raw";
+import themeURL from "../theme.css?url";
+
+export function starterSource() {
+  return starter.replace('href="theme.css"', `href="${new URL(themeURL, location.href).href}"`);
+}

package/html/theme-authoring.md

@@ -0,0 +1,176 @@
+# Author a theme: contract v1
+
+A theme is a local CSS entry point plus its fonts and other licensed assets.
+Documents use the names below rather than depending on a particular palette or
+font. Replace `theme.css` to change the visual treatment without rewriting HTML.
+Different font metrics can still change wrapping and fit: inspect every page
+after a swap.
+
+Every public theme custom property uses the `--kp-` prefix. A compatible theme
+entry point sets `--kp-theme: 1` on `:root`; the shared base intentionally does
+not set this marker, so loading `theme-base.css` alone does not opt into theme
+checks.
+
+`theme.css` supplies reusable appearance. [AUTHORING.md](../AUTHORING.md) and
+design skills supply judgment: what to emphasize, how to arrange evidence, and
+when a treatment is appropriate. Document CSS owns composition and data geometry.
+
+Document authors only need [Use a theme](theme.md). Read this full contract when
+creating or changing a stylesheet. A theme may carry short optional `NOTES.md`
+beside its CSS for look-specific judgment; keep general authoring guidance in
+AUTHORING.md. Notes do not add tokens or change the checks.
+
+## Type roles
+
+Every role has `--kp-font-ROLE`, `--kp-leading-ROLE`, `--kp-weight-ROLE`, and
+`--kp-tracking-ROLE`. Sizes and leading resolve through custom properties to
+literal positive pixel lengths such as `24px`; v1 does not accept `rem` or `calc()`
+for these slots. Weights must have declared webfont faces; tracking uses `em` or `px`.
+These names form complete treatments, not independent invitations to mix seven
+sizes with seven line heights.
+
+| Role / `data-type` | Semantic default | Family | Default color role |
+| --- | --- | --- | --- |
+| `fine` | Explicit hook only | `--kp-font-family` | `--kp-muted` |
+| `caption` | `figcaption` | `--kp-font-family` | `--kp-muted` |
+| `body` | Page text | `--kp-font-family` | `--kp-fg` |
+| `lead` | `h3` | `--kp-font-family` | Inherited |
+| `heading` | `h2` | `--kp-font-family-heading` | Inherited |
+| `title` | `h1` | `--kp-font-family-heading` | `--kp-accent` |
+| `display` | Explicit hook only | `--kp-font-family-display` | `--kp-accent` |
+
+An explicit role replaces an element's semantic default: `h2 data-type="caption"`
+uses the caption treatment, and remains an `h2`. An unmarked paragraph inherits
+its context. `strong` uses `--kp-weight-strong`. Inline `code` keeps its context's
+size and leading but uses `--kp-font-family-mono`, `--kp-weight-mono`, and the
+accent. All four family slots are required; they may refer to the same face.
+
+`inspect` reports the resolved `theme.type` for each page, including size, leading,
+weight, tracking, and family. Use those measurements to plan line lengths without
+opening CSS: Cobalt's link preset has body 32/44 and title 72/80 CSS px.
+
+## Color roles
+
+Konpeki's only bundled theme is cobalt blue on a light canvas, independent of OS
+preference. Define every token below when adapting it for a brief.
+
+| Tokens | Meaning |
+| --- | --- |
+| `--kp-bg`, `--kp-fg`, `--kp-muted` | Canvas, primary ink, supporting ink |
+| `--kp-surface` | Secondary surface |
+| `--kp-line-subtle`, `--kp-line`, `--kp-line-strong` | Three boundary strengths |
+| `--kp-contrast`, `--kp-on-contrast`, `--kp-on-contrast-muted` | Contrasting surface and its primary/supporting ink |
+| `--kp-accent`, `--kp-wash`, `--kp-inverse` | Primary accent, tinted surface, ink for an accent field |
+| `--kp-emphasis`, `--kp-emphasis-wash` | Secondary emphasis and its surface |
+| `--kp-complete`, `--kp-attention`, `--kp-blocked` | Status, always paired with a non-color cue |
+| `--kp-category-1` … `--kp-category-6` | Unordered identities; keep identity consistent across the document |
+| `--kp-sequence-1` … `--kp-sequence-5` | Ordered amounts, from least to most emphasized |
+
+Palette membership is not contrast approval. Check actual text/background pairs;
+chart fills and subtle boundaries need not be suitable text colors. In particular,
+`inverse` is ink for `accent`, not for every category or sequential fill. Pale
+sequential steps and washes need direct labels or contrasting outlines when used
+as chart marks. A contrasting surface owns its ink: set both its background and
+its text colors in document CSS rather than inheriting the canvas's ink.
+
+## Rhythm, shape, and output geometry
+
+- `--kp-unit` is the theme's spacing unit. The base derives `--kp-space-1`, `-2`, `-3`,
+  `-4`, `-5`, `-6`, `-8`, `-10`, `-12`, and `-16` as multiples on each page.
+  Choose gaps by relationship.
+- `--kp-rule-width`, `--kp-stroke`, and `--kp-stroke-heavy` describe rules, diagram
+  strokes, and heavy marks. `--kp-radius-small` and `--kp-radius` describe corners.
+  `hr` uses the rule width and `--kp-line`; other boundaries, strokes, and corners
+  are applied by document CSS. These tokens do not mandate panels or rounded pages.
+- `--kp-page-width`, `--kp-page-height`, and `--kp-page-margin` describe the output canvas.
+  The shared [base stylesheet](../theme-base.css) provides these presets:
+
+| `data-size` | Width × height | Default margin |
+| --- | --- | --- |
+| `presentation` or omitted | 1920 × 1080 px | 72 px |
+| `portrait` | 1080 × 1350 px | 60 px |
+| `square` | 1080 × 1080 px | 60 px |
+| `link` | 1200 × 630 px | 48 px |
+| `article` | 1600 × 600 px | 48 px |
+| `a4` | 210 × 297 mm | 56 px |
+| `explainer` | 1200 × 1600 px | 60 px |
+| `gallery` | 1600 × 1000 px | 64 px |
+
+The base also supplies the existing seven-step type sizes and leading per
+preset, box sizing, margin resets, and role application. It does not choose page
+layout. Theme authors may tune type steps and margins on `[data-page]` or
+`[data-size="…"]` after the import; changing them on `:root` will not override
+the page's own values. Keep preset dimensions stable across themes.
+
+## Create a theme
+
+When a brief brings its own look, adapt a copy of [`theme.css`](../theme.css).
+Keep `theme-base.css` and any local font files and their licenses beside it.
+Change token values and font declarations in the copy.
+The HTML continues to link only `theme.css`; its first rule imports the local
+base. Keep that import before font faces and other rules.
+
+The default requests IBM Plex Sans normal 400/600/700, italic 400, and Plex Mono
+normal 400 from Google Fonts. Preview and export need access to
+`fonts.googleapis.com` and `fonts.gstatic.com`; remote updates may change font
+metrics. Use licensed local files or embedded font data for offline or
+reproducible rendering.
+
+Supply additional subsets, weights, and styles when needed. Loading a font does
+not prove it covers every glyph. Do not depend on a machine's installed fonts
+or synthesized faces for required content. Font-load failures and installed-font
+fallback remain export errors regardless of where the declared fonts are hosted.
+
+## Verify a theme
+
+Define every listed token, directly or through the shared base. Run `konpeki check`
+on a specimen for each supported page size. Use all font families and weights in
+the specimen to exercise their loading. The existing inspector validates the
+active definition on each page, including unused tokens.
+
+For example, start a specimen beside the theme and its assets with:
+
+```html
+<!doctype html>
+<html lang="en">
+<head><link rel="stylesheet" href="theme.css"></head>
+<body>
+  <main id="specimen" data-page data-size="link">
+    <h1>Theme specimen</h1><p>Body, <strong>emphasis</strong>, and <code>code</code>.</p>
+  </main>
+</body>
+</html>
+```
+
+Theme diagnostics require `--kp-theme: 1`. Other versions warn and skip these
+checks; a stylesheet without the marker does not opt in.
+
+- **Errors:** missing required tokens, invalid colors or type treatments,
+  non-increasing type sizes, leading smaller than its size, and text-role contrast
+  below 4.5:1. Text pairs are `fg`/`muted` on `bg`/`surface`/`wash`, the two
+  `on-contrast` inks on `contrast`, `accent` on `bg`, and `inverse` on `accent`.
+  Each role, strong and mono need a declared normal face at their requested weight.
+  Declared weight ranges are supported. Used text must have its requested style
+  and weight when its primary family has font-face declarations.
+- **Warnings:** category marks below 3:1 against `bg`, exact duplicate category
+  colors, unknown `data-type` roles, root type/page values shadowed on a page,
+  and used colors, size/leading pairs, nonzero CSS corner radii, border widths or
+  painted SVG stroke widths outside the active theme. Zero corners and SVG circle
+  radii are allowed: tokens do not require every box to be rounded or forbid
+  circular chart marks. SVG text checks size only, because coordinates own its
+  line placement. SVG `line` fill is ignored because it does not paint.
+
+The CLI also audits actual glyph fonts through Chromium. Installed-font use is
+an error, including undeclared families and missing glyphs that fall back to a
+system font. This audit runs on unthemed content too. Browser preview cannot run
+CDP and only checks declarations and loading; run CLI inspection before delivery.
+Face coverage checks declarations, not font-binary metadata: do not mislabel a
+static font as a weight range. Include every family, weight, style and script
+used in a theme specimen to exercise the actual files.
+
+Contrast checks cover opaque sRGB only. Duplicate detection is not a test for
+perceptual distinguishability or color-vision accessibility. Inspection cannot
+prove a value was written with `var()` or establish good composition. Line-height
+overlap boxes are estimates, not glyph-ink measurements. Render and review every page, including wrapping, chart labels,
+and meaning. Compatible alternatives need no `data-theme="custom"` opt-out;
+reserve that for deliberately unthemed content.

package/html/theme.md

@@ -0,0 +1,61 @@
+# Use a theme
+
+Link `theme.css` and keep `theme-base.css` beside it. The default loads Google
+Fonts and needs network access. A document may instead use local or embedded
+fonts; keep any local files and their licenses beside it.
+Use the tokens below without reading their CSS values. `inspect` reports resolved
+type sizes, leading, weights and families under each page's `theme.type`.
+Theme construction and diagnostics are in [Author a theme](theme-authoring.md).
+
+## Type
+
+Use semantic HTML. `data-type` changes appearance without changing reading order.
+An explicit role replaces the semantic default; unmarked paragraphs inherit.
+
+| `data-type` | Default | Purpose |
+| --- | --- | --- |
+| `fine` | Explicit only | Small supporting detail |
+| `caption` | `figcaption` | Captions and sources |
+| `body` | Page text | Main reading text |
+| `lead` | `h3` | Lead or minor heading |
+| `heading` | `h2` | Section heading |
+| `title` | `h1` | Main headline |
+| `display` | Explicit only | Large headline |
+
+Custom SVG can use `--kp-font-ROLE`, `--kp-leading-ROLE`, `--kp-weight-ROLE` and
+`--kp-tracking-ROLE`. Keep each size/leading pair together. Font slots are
+`--kp-font-family`, `-heading`, `-display`, and `-mono`. `strong`, `code` and `em`
+work directly; unsupported weights/styles and system-font fallback are errors.
+
+## Color and shape
+
+All names below start with `--kp-`:
+
+| Tokens | Use |
+| --- | --- |
+| `bg`, `fg`, `muted`, `surface` | Canvas, main/supporting ink, secondary surface |
+| `accent`, `wash`, `inverse` | Accent, tint, ink on the accent |
+| `contrast`, `on-contrast`, `on-contrast-muted` | Contrasting surface and its inks |
+| `line-subtle`, `line`, `line-strong` | Boundary strengths |
+| `emphasis`, `emphasis-wash` | Secondary emphasis and tint |
+| `complete`, `attention`, `blocked` | Status, paired with a non-color cue |
+| `category-1` … `-6`; `sequence-1` … `-5` | Identities; ordered amounts |
+| `space-1`, `-2`, `-3`, `-4`, `-5`, `-6`, `-8`, `-10`, `-12`, `-16` | Gaps/padding by relationship |
+| `rule-width`, `stroke`, `stroke-heavy`; `radius-small`, `radius` | Boundaries, strokes; corners |
+
+Palette membership is not contrast approval. Set a contrasting surface's ink
+explicitly. Pale chart marks need labels or outlines; `inverse` is not universal
+ink for every fill. Document CSS owns layout and data geometry.
+
+## Page presets
+
+Set `data-size` on each `[data-page]`: `presentation` (default, 1920×1080),
+`portrait` (1080×1350), `square` (1080×1080), `link` (1200×630), `article`
+(1600×600), `a4` (210×297 mm), `explainer` (1200×1600), or `gallery` (1600×1000).
+Dimensions otherwise use CSS px. `--kp-page-width`, `-height`, and `-margin`
+describe the canvas. Override page/type sizes on `[data-page]`, not `:root`.
+
+Keep theme changes separate from composition. Read a theme's optional `NOTES.md`
+for its taste; general judgment stays in AUTHORING.md. After a swap, inspect and
+render every page. Reserve `data-theme="custom"` for deliberately unthemed
+content; it does not disable layout or font checks.

package/index.html

@@ -7,27 +7,27 @@
     <link rel="icon" type="image/png" sizes="128x128" href="/src/assets/konpeki-mark.png" />
     <meta
       name="description"
-      content="Try Konpeki's editable canvas. Edit an example, create a page, export PNG or download editable JSON. No account needed; changes stay in your browser."
+      content="Review agent-authored HTML visuals. Select an element, leave a comment, and copy feedback for your agent. No account needed."
     />
     <meta property="og:type" content="website" />
     <meta property="og:site_name" content="Konpeki" />
-    <meta property="og:title" content="Konpeki — Browser playground" />
-    <meta property="og:description" content="Try Konpeki's editable canvas. Edit an example, create a page, export PNG or download editable JSON. No account needed; changes stay in your browser." />
-    <meta property="og:url" content="https://vcfgdev.github.io/konpeki/?example=introducing-konpeki" />
+    <meta property="og:title" content="Konpeki — Visual review" />
+    <meta property="og:description" content="Review agent-authored HTML visuals. Select an element, leave a comment, and copy feedback for your agent. No account needed." />
+    <meta property="og:url" content="https://vcfgdev.github.io/konpeki/" />
     <meta property="og:image" content="https://vcfgdev.github.io/konpeki/og.png" />
     <meta property="og:image:type" content="image/png" />
     <meta property="og:image:width" content="1280" />
     <meta property="og:image:height" content="640" />
-    <meta property="og:image:alt" content="Konpeki — Create clear visuals with your coding agent. Blue brush mark and editable canvas illustrations." />
+    <meta property="og:image:alt" content="Create clear visuals with your coding agent. Blue brush mark on warm paper, with the konpeki wordmark below." />
     <meta name="twitter:card" content="summary_large_image" />
-    <meta name="twitter:title" content="Konpeki — Browser playground" />
-    <meta name="twitter:description" content="Try Konpeki's editable canvas. Edit an example, create a page, export PNG or download editable JSON. No account needed; changes stay in your browser." />
+    <meta name="twitter:title" content="Konpeki — Visual review" />
+    <meta name="twitter:description" content="Review agent-authored HTML visuals. Select an element, leave a comment, and copy feedback for your agent. No account needed." />
     <meta name="twitter:image" content="https://vcfgdev.github.io/konpeki/og.png" />
-    <meta name="twitter:image:alt" content="Konpeki — Create clear visuals with your coding agent. Blue brush mark and editable canvas illustrations." />
+    <meta name="twitter:image:alt" content="Create clear visuals with your coding agent. Blue brush mark on warm paper, with the konpeki wordmark below." />
     <title>Konpeki</title>
   </head>
   <body>
     <div id="root"></div>
-    <script type="module" src="/src/main.tsx"></script>
+    <script type="module" src="/html/preview.tsx"></script>
   </body>
 </html>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "konpeki",
-  "version": "0.3.0",
-  "description": "A shared editable canvas for agent-made visuals",
+  "version": "0.4.0",
+  "description": "Agent-first HTML visual authoring and review",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -23,33 +23,27 @@
     "CONTRIBUTING.md",
     "SECURITY.md",
     "SETUP.md",
+    "README.md",
+    "LICENSE",
+    "theme.css",
+    "theme-base.css",
     "docs/workflow.md",
     "docs/development.md",
     "plugin.json",
     "skills/konpeki/SKILL.md",
+    "skills/konpeki/floor.md",
+    "skills/konpeki/references/*.md",
     "skills/konpeki/scripts/*.mjs",
-    "skills/konpeki/assets/blank.json",
-    "runtime/konpeki.mjs",
+    "skills/konpeki/assets/blank.html",
+    "html/*.{ts,tsx,css,html,md}",
+    "runtime/**/*.{mjs,js}",
     "index.html",
     "vite.config.ts",
     "public/og.png",
-    "src/main.tsx",
-    "src/app/*.tsx",
-    "src/components/*.tsx",
-    "src/lib/*.ts",
-    "src/lib/examples/react-page-migration.json",
-    "src/styles/*.css",
+    "src/components/PageBoard.tsx",
+    "src/lib/{page-board,alignment,review-position}.ts",
+    "src/styles/{base,shell,feedback}.css",
     "src/assets/konpeki-mark.png",
-    "composition/{README.md,compile.ts,document.ts,schema.json,schema.ts,theme-tokens.ts,types.ts,validate.ts,vector.ts,visualizations.ts}",
-    "design/*.md",
-    "design/{palettes,themes}/*.{md,ts}",
-    "design/review/*.md",
-    "design/visual-languages/technical-product.md",
-    "lib/{assets.d.ts,charts.ts,contrast.ts,layouts.ts,slide.tsx,taste.ts,text.tsx,typeface.ts}",
-    "scripts/migrate-react-page.ts",
-    "slides/README.md",
-    "slides/{architecture,article-brief,bar-chart,comparison,decision-memo,delivery-plan,experiment,incident-workflow,line-chart,migration,og-images,product-introduction,research-brief,results-explanation,retrospective,sankey,teaching,vertical-bar-charts}/{PROMPT.md,index.tsx}",
-    "slides/introducing-konpeki/{README.md,PROMPT.md,SOURCE.md,composition.json,author.ts}",
     "!**/*.test.ts"
   ],
   "engines": {
@@ -61,31 +55,23 @@
     "prepack": "node scripts/build-cli.mjs",
     "preview": "vite preview --host 0.0.0.0 --port 4318",
     "check": "tsc --noEmit",
-    "test": "node --test lib/*.test.ts composition/*.test.ts src/lib/*.test.ts bin/*.test.ts",
+    "test": "node --test html/*.test.ts src/lib/*.test.ts scripts/*.test.mjs",
     "check:package": "node scripts/check-package.mjs",
-    "konpeki": "node bin/konpeki.mjs",
-    "composition:generate": "node composition/generate.ts",
-    "example:migrate-page": "node scripts/migrate-react-page.ts"
+    "konpeki": "node bin/konpeki.mjs"
   },
   "dependencies": {
-    "@fontsource/hanken-grotesk": "5.3.0",
     "@fontsource/ibm-plex-sans": "5.3.0",
-    "@fontsource/ibm-plex-serif": "5.3.0",
-    "@fontsource/newsreader": "5.3.0",
-    "@fontsource/noto-sans": "5.3.0",
-    "@nivo/bar": "0.99.0",
-    "@nivo/line": "0.99.0",
-    "@nivo/sankey": "0.99.0",
-    "@xmldom/xmldom": "0.9.12",
-    "ajv": "^8.20.0",
-    "proper-lockfile": "4.1.2",
+    "parse5": "8.0.0",
+    "pdf-lib": "1.17.1",
+    "playwright": "1.63.0",
+    "postcss": "8.5.28",
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "vite": "^8.3.0"
   },
   "devDependencies": {
+    "@fontsource/ibm-plex-mono": "5.3.0",
     "@types/node": "^24.0.0",
-    "@types/proper-lockfile": "4.1.4",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.5",
     "typescript": "^5.9.3"

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "konpeki",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Create editable visuals with your coding agent.",
   "repository": "https://github.com/vcfgdev/konpeki",
   "license": "Apache-2.0",