basis-design 0.1.1 → 0.2.0

package/server/verify-kit/compare.mjs

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+/*
+ * Compares the implementation's screenshots with the design's, pixel for pixel. Part of the verification kit
+ * Basis exports; it needs Node 22 and nothing else.
+ *
+ *   node basis-verify/compare.mjs [--expected <dir>] [--actual <dir>] [--diff <dir>] [--max-diff <percent>]
+ *                                 [--tolerance <0-255>]
+ *
+ * Expected images come from expected/ (the design captured on this machine by `capture.mjs design`), or from
+ * screens/ (captured by Basis) when expected/ has none. Actual images come from actual/ (`capture.mjs app`).
+ * Every shot in basis-verify.json is compared; named exceptions in exceptions.json leave regions, or whole
+ * shots, out. The command exits with 1 when any shot differs by more than --max-diff (default 0).
+ */
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { crc32, deflateSync, inflateSync } from "node:zlib";
+
+const SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+const CHANNELS = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
+
+function paeth(a, b, c) {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+}
+
+/** Decodes an 8-bit, non-interlaced PNG (what browsers' screenshots are) into RGBA pixels. */
+export function decodePng(buffer) {
+  if (!buffer.subarray(0, 8).equals(SIGNATURE)) throw new Error("Not a PNG file.");
+  let width = 0;
+  let height = 0;
+  let depth = 0;
+  let type = 0;
+  let interlace = 0;
+  let palette;
+  let transparency;
+  const idat = [];
+  for (let offset = 8; offset < buffer.length;) {
+    const length = buffer.readUInt32BE(offset);
+    const kind = buffer.toString("ascii", offset + 4, offset + 8);
+    const data = buffer.subarray(offset + 8, offset + 8 + length);
+    offset += 12 + length;
+    if (kind === "IHDR") {
+      width = data.readUInt32BE(0);
+      height = data.readUInt32BE(4);
+      depth = data[8];
+      type = data[9];
+      interlace = data[12];
+    } else if (kind === "PLTE") palette = data;
+    else if (kind === "tRNS") transparency = data;
+    else if (kind === "IDAT") idat.push(data);
+    else if (kind === "IEND") break;
+  }
+  const channels = CHANNELS[type];
+  if (depth !== 8 || interlace !== 0 || !channels) {
+    throw new Error("Only 8-bit, non-interlaced PNG files are supported.");
+  }
+  const stride = width * channels;
+  const raw = inflateSync(Buffer.concat(idat));
+  const pixels = Buffer.alloc(stride * height);
+  let previous = Buffer.alloc(stride);
+  for (let y = 0; y < height; y++) {
+    const filter = raw[y * (stride + 1)];
+    const line = raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1));
+    const out = pixels.subarray(y * stride, (y + 1) * stride);
+    for (let i = 0; i < stride; i++) {
+      const a = i >= channels ? out[i - channels] : 0;
+      const b = previous[i];
+      const c = i >= channels ? previous[i - channels] : 0;
+      const x = line[i];
+      out[i] =
+        filter === 0
+          ? x
+          : filter === 1
+            ? x + a
+            : filter === 2
+              ? x + b
+              : filter === 3
+                ? x + ((a + b) >> 1)
+                : x + paeth(a, b, c);
+    }
+    previous = out;
+  }
+  const data = Buffer.alloc(width * height * 4);
+  for (let p = 0; p < width * height; p++) {
+    const s = p * channels;
+    const d = p * 4;
+    if (type === 6) pixels.copy(data, d, s, s + 4);
+    else if (type === 2) {
+      data[d] = pixels[s];
+      data[d + 1] = pixels[s + 1];
+      data[d + 2] = pixels[s + 2];
+      data[d + 3] = 255;
+    } else if (type === 0 || type === 4) {
+      data[d] = data[d + 1] = data[d + 2] = pixels[s];
+      data[d + 3] = type === 4 ? pixels[s + 1] : 255;
+    } else {
+      const index = pixels[s];
+      data[d] = palette[index * 3];
+      data[d + 1] = palette[index * 3 + 1];
+      data[d + 2] = palette[index * 3 + 2];
+      data[d + 3] = transparency && index < transparency.length ? transparency[index] : 255;
+    }
+  }
+  return { width, height, data };
+}
+
+function chunk(kind, data) {
+  const head = Buffer.alloc(8);
+  head.writeUInt32BE(data.length, 0);
+  head.write(kind, 4, "ascii");
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(Buffer.concat([head.subarray(4), data])) >>> 0, 0);
+  return Buffer.concat([head, data, crc]);
+}
+
+/** Encodes RGBA pixels as a PNG. */
+export function encodePng({ width, height, data }) {
+  const stride = width * 4;
+  const raw = Buffer.alloc((stride + 1) * height);
+  for (let y = 0; y < height; y++) data.copy(raw, y * (stride + 1) + 1, y * stride, (y + 1) * stride);
+  const header = Buffer.alloc(13);
+  header.writeUInt32BE(width, 0);
+  header.writeUInt32BE(height, 4);
+  header[8] = 8;
+  header[9] = 6;
+  return Buffer.concat([
+    SIGNATURE,
+    chunk("IHDR", header),
+    chunk("IDAT", deflateSync(raw)),
+    chunk("IEND", Buffer.alloc(0)),
+  ]);
+}
+
+/**
+ * Compares two images on a canvas as large as both. A pixel differs when any channel differs by more than
+ * `tolerance`; where only one image has pixels, they differ. Pixels inside `regions` are left out of the count.
+ * The diff image shows the expected image faded, differing pixels red and left-out regions blue.
+ */
+export function compareImages(expected, actual, { tolerance = 0, regions = [] } = {}) {
+  const width = Math.max(expected.width, actual.width);
+  const height = Math.max(expected.height, actual.height);
+  const diff = Buffer.alloc(width * height * 4);
+  const inRegion = (x, y) => regions.some((r) => x >= r.x && x < r.x + r.width && y >= r.y && y < r.y + r.height);
+  let differing = 0;
+  let excluded = 0;
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const d = (y * width + x) * 4;
+      const inExpected = x < expected.width && y < expected.height;
+      const inActual = x < actual.width && y < actual.height;
+      const e = (y * expected.width + x) * 4;
+      const a = (y * actual.width + x) * 4;
+      if (inRegion(x, y)) {
+        excluded++;
+        diff[d] = 120;
+        diff[d + 1] = 160;
+        diff[d + 2] = 255;
+        diff[d + 3] = 255;
+        continue;
+      }
+      let same = inExpected && inActual;
+      for (let c = 0; same && c < 4; c++) {
+        if (Math.abs(expected.data[e + c] - actual.data[a + c]) > tolerance) same = false;
+      }
+      if (same) {
+        const gray = Math.round(
+          (expected.data[e] * 0.299 + expected.data[e + 1] * 0.587 + expected.data[e + 2] * 0.114) * 0.25 + 191,
+        );
+        diff[d] = diff[d + 1] = diff[d + 2] = gray;
+      } else {
+        differing++;
+        diff[d] = 230;
+        diff[d + 1] = 20;
+        diff[d + 2] = 60;
+      }
+      diff[d + 3] = 255;
+    }
+  }
+  const counted = width * height - excluded;
+  return {
+    width,
+    height,
+    sameSize: expected.width === actual.width && expected.height === actual.height,
+    differing,
+    counted,
+    percent: counted ? (differing / counted) * 100 : 0,
+    diff: { width, height, data: diff },
+  };
+}
+
+/** The exceptions that apply to one shot: those naming its view, and its screen, widths and themes if they say. */
+export function exceptionsFor(exceptions, shot) {
+  return exceptions.filter(
+    (exception) =>
+      exception.view === shot.view &&
+      (exception.screen === undefined || exception.screen === shot.screen) &&
+      (exception.widths === undefined || exception.widths.includes(shot.width)) &&
+      (exception.themes === undefined || exception.themes.includes(shot.theme)),
+  );
+}
+
+function option(args, name, fallback) {
+  const index = args.indexOf(name);
+  return index === -1 ? fallback : args[index + 1];
+}
+
+async function main() {
+  const kit = path.dirname(fileURLToPath(import.meta.url));
+  const args = process.argv.slice(2);
+  const resolve = (name, fallback) => {
+    const value = option(args, name);
+    return value ? path.resolve(value) : path.join(kit, fallback);
+  };
+  const expectedDir = resolve("--expected", "expected");
+  const shippedDir = path.join(kit, "screens");
+  const actualDir = resolve("--actual", "actual");
+  const diffDir = resolve("--diff", "diff");
+  const maxDiff = Number(option(args, "--max-diff", "0"));
+  const tolerance = Number(option(args, "--tolerance", "0"));
+  const manifest = JSON.parse(await readFile(path.join(kit, "basis-verify.json"), "utf8"));
+  const exceptionsFile = path.join(kit, "exceptions.json");
+  const exceptions = existsSync(exceptionsFile)
+    ? (JSON.parse(await readFile(exceptionsFile, "utf8")).exceptions ?? [])
+    : [];
+
+  const results = [];
+  for (const view of manifest.views) {
+    for (const screen of view.screens) {
+      for (const shot of screen.shots) {
+        const file = shot.file;
+        const name = file.replace(/^screens\//, "");
+        const own = path.join(expectedDir, name);
+        const expectedPath = existsSync(own) ? own : path.join(shippedDir, name);
+        const actualPath = path.join(actualDir, name);
+        const result = { file: name, view: view.id, screen: screen.id, width: shot.width, theme: shot.theme };
+        const applying = exceptionsFor(exceptions, result);
+        const whole = applying.find((exception) => !exception.region);
+        if (whole) {
+          results.push({ ...result, status: "excepted", exception: whole.name });
+          continue;
+        }
+        if (!existsSync(actualPath)) {
+          results.push({ ...result, status: "missing", message: `No ${path.relative(process.cwd(), actualPath)}` });
+          continue;
+        }
+        const expected = decodePng(await readFile(expectedPath));
+        const actual = decodePng(await readFile(actualPath));
+        const outcome = compareImages(expected, actual, {
+          tolerance,
+          regions: applying.map((exception) => exception.region),
+        });
+        const passed = outcome.sameSize && outcome.percent <= maxDiff;
+        if (!passed) {
+          const target = path.join(diffDir, name);
+          await mkdir(path.dirname(target), { recursive: true });
+          await writeFile(target, encodePng(outcome.diff));
+        }
+        results.push({
+          ...result,
+          status: passed ? "pass" : "fail",
+          percent: Number(outcome.percent.toFixed(4)),
+          differingPixels: outcome.differing,
+          expectedSize: `${expected.width}x${expected.height}`,
+          actualSize: `${actual.width}x${actual.height}`,
+          exceptions: applying.map((exception) => exception.name),
+          reference: path.relative(kit, expectedPath).split(path.sep).join("/"),
+        });
+      }
+    }
+  }
+
+  for (const result of results) {
+    const label = result.status.toUpperCase().padEnd(8);
+    let detail = "";
+    if (result.status === "excepted") detail = `exception "${result.exception}"`;
+    else if (result.status === "missing") detail = result.message;
+    else {
+      detail = `${result.percent.toFixed(4)}% (${result.differingPixels} px)`;
+      if (result.expectedSize !== result.actualSize) {
+        detail += `, size ${result.actualSize}, expected ${result.expectedSize}`;
+      }
+      if (result.exceptions.length) detail += `, regions left out: ${result.exceptions.join(", ")}`;
+    }
+    console.log(`${label} ${result.file.padEnd(48)} ${detail}`);
+  }
+  const failed = results.filter((result) => result.status === "fail" || result.status === "missing");
+  await mkdir(diffDir, { recursive: true });
+  await writeFile(path.join(diffDir, "report.json"), `${JSON.stringify({ maxDiff, tolerance, results }, null, 2)}\n`);
+  console.log(
+    failed.length
+      ? `\n${failed.length} of ${results.length} shots do not match. Diff images are in ${path.relative(process.cwd(), diffDir) || "."}.`
+      : `\nAll ${results.length} shots match.`,
+  );
+  process.exitCode = failed.length ? 1 : 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 2;
+  });
+}

package/server/verify.ts

@@ -0,0 +1,383 @@
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import { strToU8, zipSync, type Zippable } from "fflate";
+import { build } from "vite";
+import { READY_ATTRIBUTE, shotFile } from "../shared/capture.ts";
+import type { Design } from "../shared/design.ts";
+import type { VerifyKitSummary } from "../shared/protocol.ts";
+import { CAPTURE_ARGS, captureViews, launchCaptureBrowser } from "./capture.ts";
+
+/*
+ * The verification kit: what an agent implementing a feature needs to prove the implementation looks like the
+ * design. A static, runnable copy of the design (design/), the screenshots Basis took of every screen of every
+ * view (screens/), the settings they were taken with (basis-verify.json), and two scripts that capture the
+ * implementation the same way and compare the two pixel for pixel (capture.mjs, compare.mjs).
+ */
+
+const repoRoot = path.resolve(import.meta.dirname, "..");
+const kitSource = path.join(import.meta.dirname, "verify-kit");
+
+/** The kit's folder inside a project, and the folder inside its zip. */
+export const KIT_FOLDER = "basis-verify";
+export const MANIFEST = "basis-verify.json";
+/** What Basis writes and replaces; everything else in the kit's folder (targets.json, exceptions.json, actual/) is the project's. */
+const GENERATED = [
+  "design",
+  "screens",
+  "expected",
+  "diff",
+  MANIFEST,
+  "README.md",
+  "capture.mjs",
+  "compare.mjs",
+  "targets.example.json",
+  "exceptions.example.json",
+];
+
+/** Rules the implementation's pages get while they are captured, so nothing moves between two captures. */
+export const NEUTRAL_CSS =
+  "*,*::before,*::after{transition:none!important;animation:none!important;caret-color:transparent!important}";
+
+export interface KitFile {
+  path: string;
+  data: Uint8Array;
+}
+
+const TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".woff2": "font/woff2",
+};
+
+/** Builds the capture page with the workspace's components into `outDir`, as index.html beside design.json. */
+async function buildDesign(design: Design, workspaceDir: string, outDir: string): Promise<void> {
+  await build({
+    root: repoRoot,
+    configFile: path.join(repoRoot, "vite.config.ts"),
+    base: "./",
+    logLevel: "silent",
+    resolve: {
+      alias: {
+        "@ds": path.join(workspaceDir, "components", "index.ts"),
+        "@workspace": workspaceDir,
+      },
+      dedupe: ["react", "react-dom"],
+    },
+    build: {
+      outDir,
+      emptyOutDir: true,
+      reportCompressedSize: false,
+      chunkSizeWarningLimit: 100_000,
+      rolldownOptions: { input: path.join(repoRoot, "capture.html") },
+    },
+  });
+  await rename(path.join(outDir, "capture.html"), path.join(outDir, "index.html"));
+  await writeFile(path.join(outDir, "design.json"), `${JSON.stringify(design, null, 2)}\n`);
+}
+
+/** Serves a folder on a free local port, for the browser to open the built design from. */
+async function serve(dir: string): Promise<{ url: string; close: () => void }> {
+  const server = http.createServer((req, res) => {
+    const pathname = decodeURIComponent(new URL(req.url ?? "/", "http://local").pathname);
+    const file = path.join(dir, pathname === "/" ? "index.html" : pathname);
+    if (!file.startsWith(dir + path.sep)) {
+      res.writeHead(403).end();
+      return;
+    }
+    readFile(file).then(
+      (body) => {
+        res.writeHead(200, { "Content-Type": TYPES[path.extname(file)] ?? "application/octet-stream" });
+        res.end(body);
+      },
+      () => res.writeHead(404).end(),
+    );
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const { port } = server.address() as { port: number };
+  return {
+    url: `http://127.0.0.1:${port}/index.html`,
+    close: () => {
+      server.closeAllConnections();
+      server.close();
+    },
+  };
+}
+
+async function filesIn(dir: string, prefix: string): Promise<KitFile[]> {
+  const entries = (await readdir(dir, { recursive: true })).sort();
+  const files: KitFile[] = [];
+  for (const entry of entries) {
+    const full = path.join(dir, entry);
+    if (!(await stat(full)).isFile()) continue;
+    files.push({ path: `${prefix}/${entry.split(path.sep).join("/")}`, data: await readFile(full) });
+  }
+  return files;
+}
+
+async function packageVersion(): Promise<string> {
+  return (JSON.parse(await readFile(path.join(repoRoot, "package.json"), "utf8")) as { version: string }).version;
+}
+
+export interface BuildKitOptions {
+  design: Design;
+  workspaceDir: string;
+  onProgress?: (step: string, done?: number, total?: number) => void;
+}
+
+/** Builds the design, photographs every screen and returns the kit's files with a summary for the user. */
+export async function buildVerificationKit({
+  design,
+  workspaceDir,
+  onProgress,
+}: BuildKitOptions): Promise<{ files: KitFile[]; summary: VerifyKitSummary }> {
+  const temp = await mkdtemp(path.join(os.tmpdir(), "basis-verify-"));
+  const designDir = path.join(temp, "design");
+  try {
+    onProgress?.("Building the design");
+    await buildDesign(design, workspaceDir, designDir);
+    onProgress?.("Starting the browser");
+    const { browser, name, version } = await launchCaptureBrowser();
+    const server = await serve(designDir);
+    let result;
+    try {
+      result = await captureViews(server.url, browser, (done, total) =>
+        onProgress?.("Taking screenshots", done, total),
+      );
+    } finally {
+      server.close();
+      await browser.close();
+    }
+    const { views, problems, shots } = result;
+    const byFile = new Map(shots.map((shot) => [shot.file, shot]));
+    const generator = `basis-design ${await packageVersion()}`;
+    const manifest = {
+      format: 1,
+      generator,
+      createdAt: new Date().toISOString(),
+      designSystem: design.name,
+      browser: { name, version, platform: process.platform },
+      render: {
+        deviceScaleFactor: 1,
+        reducedMotion: "reduce",
+        colorScheme: "light",
+        args: CAPTURE_ARGS,
+        neutralCss: NEUTRAL_CSS,
+        base: await readFile(path.join(repoRoot, "src", "capture", "capture.css"), "utf8"),
+      },
+      design: {
+        entry: "design/index.html",
+        query: "?view={view}&screen={screen}&theme={theme}",
+        ready: `html[${READY_ATTRIBUTE}]`,
+        error: "html[data-basis-error]",
+      },
+      views: views.map((view) => ({
+        id: view.id,
+        title: view.title,
+        screens: view.screens.map((screen) => ({
+          id: screen.id,
+          label: screen.label,
+          shots: screen.shots.map((planned) => {
+            const shot = byFile.get(shotFile(view.id, screen.id, planned));
+            return {
+              ...planned,
+              file: shot?.file,
+              imageHeight: shot?.imageHeight,
+              stable: shot?.stable,
+              failed: shot?.failed,
+            };
+          }),
+        })),
+      })),
+      problems,
+    };
+    const targets = {
+      baseUrl: "http://localhost:3000",
+      screens: Object.fromEntries(
+        views.flatMap((view) => view.screens.map((screen) => [`${view.id}/${screen.id}`, "/"])),
+      ),
+    };
+    const exceptions = {
+      exceptions: [
+        {
+          name: "example-avatar",
+          reason: "Why this part may differ, in a sentence the reviewer can check.",
+          view: views[0]?.id ?? "<view id>",
+          screen: views[0]?.screens[0]?.id,
+          widths: [375],
+          region: { x: 16, y: 16, width: 40, height: 40 },
+        },
+      ],
+    };
+    const text = (file: string, content: string): KitFile => ({ path: file, data: strToU8(content) });
+    const files: KitFile[] = [
+      text(MANIFEST, `${JSON.stringify(manifest, null, 2)}\n`),
+      text("README.md", readme(design.name, generator, name, version)),
+      text("capture.mjs", await readFile(path.join(kitSource, "capture.mjs"), "utf8")),
+      text("compare.mjs", await readFile(path.join(kitSource, "compare.mjs"), "utf8")),
+      text("targets.example.json", `${JSON.stringify(targets, null, 2)}\n`),
+      text("exceptions.example.json", `${JSON.stringify(exceptions, null, 2)}\n`),
+      ...(await filesIn(designDir, "design")),
+      ...shots.map((shot) => ({ path: shot.file, data: new Uint8Array(shot.png) })),
+    ];
+    const summary: VerifyKitSummary = {
+      browser: `${name} ${version}`,
+      views: views.length,
+      screens: views.reduce((sum, view) => sum + view.screens.length, 0),
+      shots: shots.length,
+      unstable: shots.filter((shot) => !shot.stable).map((shot) => shot.file),
+      failed: shots.filter((shot) => shot.failed).map((shot) => shot.file),
+      problems,
+    };
+    return { files, summary };
+  } finally {
+    await rm(temp, { recursive: true, force: true });
+  }
+}
+
+export function zipVerificationKit(files: KitFile[]): Uint8Array {
+  const entries: Zippable = {};
+  // PNGs are compressed already; deflating them again only costs time.
+  for (const file of files)
+    entries[`${KIT_FOLDER}/${file.path}`] = [file.data, { level: file.path.endsWith(".png") ? 0 : 6 }];
+  return zipSync(entries);
+}
+
+/**
+ * Writes the kit into `<project>/basis-verify/`. A folder by that name that is not a kit (no manifest) is left
+ * alone; in a kit, the files Basis generates are replaced and the project's own (targets.json, exceptions.json,
+ * actual/) are kept.
+ */
+export async function writeVerificationKit(
+  files: KitFile[],
+  project: string,
+): Promise<{ ok: true; dir: string } | { ok: false; error: string }> {
+  const trimmed = project.trim();
+  if (!trimmed || !path.isAbsolute(trimmed)) return { ok: false, error: "Enter an absolute folder path." };
+  const root = path.resolve(trimmed);
+  const relativeToBasis = path.relative(repoRoot, root);
+  if (!relativeToBasis.startsWith("..") && !path.isAbsolute(relativeToBasis)) {
+    return { ok: false, error: "That folder is inside Basis itself. Pick your project's folder." };
+  }
+  if (!existsSync(root) || !(await stat(root)).isDirectory())
+    return { ok: false, error: "That folder does not exist." };
+  const dir = path.join(root, KIT_FOLDER);
+  if (existsSync(dir) && !existsSync(path.join(dir, MANIFEST)) && (await readdir(dir)).length > 0) {
+    return { ok: false, error: `${dir} exists and is not a verification kit. Move it away or pick another folder.` };
+  }
+  for (const entry of GENERATED) await rm(path.join(dir, entry), { recursive: true, force: true });
+  for (const file of files) {
+    const destination = path.join(dir, file.path);
+    await mkdir(path.dirname(destination), { recursive: true });
+    await writeFile(destination, file.data);
+  }
+  return { ok: true, dir };
+}
+
+function readme(name: string, generator: string, browser: string, version: string): string {
+  return `# Verification kit: ${name}
+
+Generated by ${generator} with ${browser} ${version}. Basis replaces this folder's generated files
+(\`design/\`, \`screens/\`, \`expected/\`, \`diff/\`, \`basis-verify.json\`, the scripts and the examples) each
+time it writes the kit; \`targets.json\`, \`exceptions.json\` and \`actual/\` are yours and stay.
+
+The kit says what each screen of each view must look like, pixel for pixel, at fixed sizes. The target is
+0% difference. Anything allowed to differ is a named exception in \`exceptions.json\`, so a reviewer can read
+every one of them.
+
+## Contents
+
+- \`design/\`: the design as a static site. Serve the folder and open
+  \`index.html?view=<view>&screen=<screen>&theme=light\` to see one screen alone, at the size of the window.
+  The screens are clickable where the design moves between them.
+- \`screens/\`: what Basis captured, named \`<view>/<screen>@<width>[x<height>][-dark].png\`.
+- \`basis-verify.json\`: every view, screen and shot (width, viewport height, full page or not, theme), and the
+  settings the shots were taken with: device scale 1, reduced motion, light color scheme, the Chromium flags in
+  \`render.args\`, and the CSS every captured page gets (\`render.neutralCss\`).
+- \`capture.mjs\`: takes the same shots of the design or of the implementation, on this machine.
+- \`compare.mjs\`: compares the two sets and writes diff images.
+
+## Check an implementation
+
+Both scripts need Node 22 and Playwright in the project:
+
+\`\`\`bash
+npm i -D playwright
+npx playwright install chromium
+\`\`\`
+
+1. Capture the design on this machine. Fonts and antialiasing differ between operating systems, so compare
+   images taken on the same machine with the same browser. \`screens/\` is the reference only when nothing
+   else is there.
+
+   \`\`\`bash
+   node basis-verify/capture.mjs design
+   \`\`\`
+
+2. Point each screen at the page that implements it: copy \`targets.example.json\` to \`targets.json\` and fill
+   in the URLs (relative to \`baseUrl\`, or absolute). An entry is a URL, or
+   \`{ "url": "/team/42", "waitFor": "[data-loaded]" }\` to wait for an element before capturing. Optional:
+   \`"storageState": "auth.json"\` (a Playwright storage state, for pages behind a login) and
+   \`"themeAttribute": "data-theme"\` (set on \`<html>\` to the shot's theme, for apps that switch themes with an
+   attribute rather than the color scheme).
+
+3. Start the app and capture it:
+
+   \`\`\`bash
+   node basis-verify/capture.mjs app
+   \`\`\`
+
+4. Compare:
+
+   \`\`\`bash
+   node basis-verify/compare.mjs
+   \`\`\`
+
+   Each shot prints PASS, FAIL (with the share of differing pixels), MISSING or EXCEPTED. Failures get a diff
+   image in \`diff/\`: matching pixels faded, differing pixels red, excepted regions blue. \`diff/report.json\` has
+   the same results for tools. The command exits with 1 when any shot fails or is missing.
+
+A screen is the whole page as the product shows it. The page's size matters too: a full-page shot that is
+taller or shorter than the design fails even when the top matches.
+
+## Make it match
+
+- Use the design's tokens and the same page structure. Compare against \`design/\` in a browser at the same
+  width when a diff is hard to read.
+- Data must be the same as in the design. The design uses the product's real data where it could; where the
+  implementation loads data, point it at the same records, or seed them.
+- Anything that changes between two loads (clocks, random values, animations, content that arrives late)
+  makes a shot unstable: \`capture.mjs\` says so, and such a shot can never match.
+
+## Exceptions
+
+When part of a screen cannot match for a reason you can name, add it to \`exceptions.json\` (start from
+\`exceptions.example.json\`):
+
+\`\`\`json
+{
+  "exceptions": [
+    {
+      "name": "avatar-photo",
+      "reason": "Real profile photos replace the design's initials.",
+      "view": "team-members",
+      "screen": "list",
+      "widths": [375],
+      "themes": ["light"],
+      "region": { "x": 16, "y": 16, "width": 40, "height": 40 }
+    }
+  ]
+}
+\`\`\`
+
+\`screen\`, \`widths\` and \`themes\` narrow where it applies; without them it applies to every screen, width or
+theme of the view. \`region\` is in the image's pixels; without it the whole shot is excepted. Keep exceptions
+few and specific: every one is a part of the design nobody checks.
+`;
+}