basis-design 0.1.1 → 0.2.0

package/README.md

@@ -37,7 +37,7 @@ To work on Basis itself, clone the repository and run `npm install` and `npm run
 
 Each project is a workspace of its own: its own design system, history, chat and review. Switch, create and open projects from the menu with the project's name at the top left.
 
-A project can link the **product repo** it designs for (project menu, **Link product repo…**). The agent reads and searches it without asking, to match the product's look, components and terms, and never writes there: writes outside the workspace are refused. **New project…** can also start from a product repo: the project takes the repo folder's name unless you give one, links the repo and starts by bringing in its design. **Bring in its design** (offered when you link, and in the project menu) starts a guided turn: the agent maps the repo's tokens onto `design-system.json`, restyles the components and patterns to resemble the product's, writes what it learned to `product.md` (where the tokens live, an inventory of the product's components and their Basis counterparts, terms to reuse) and opens a review.
+A project can link the **product repo** it designs for (project menu, **Link product repo…**): pick it from the repos Basis finds in your usual code folders, choose it with **Browse…** in your system's folder dialog, or paste its path. The agent reads and searches it without asking, to match the product's look, components and terms, and never writes there: writes outside the workspace are refused. **New project…** can also start from a product repo: the project takes the repo folder's name unless you give one, links the repo and starts by bringing in its design. **Bring in its design** (offered when you link, and in the project menu) starts a guided turn: the agent maps the repo's tokens onto `design-system.json`, restyles the components and patterns to resemble the product's, writes what it learned to `product.md` (where the tokens live, an inventory of the product's components and their Basis counterparts, terms to reuse) and opens a review.
 
 - **New project** starts from Basis' defaults, or as a copy of the open project's tokens and components (not its history). It lives in `~/.basis/workspaces/`.
 - **Open folder** adds a workspace from anywhere, or an empty or new folder for Basis to set up, inside a product repo for instance. Basis refuses a folder that already has other files, so it never starts a history in someone's project.
@@ -107,6 +107,7 @@ Every `components/*.specimen.tsx` file becomes a gallery section and a sidebar e
   - a README on wiring it up.
 
   The kit needs React 18+ and CSS Modules, nothing else. The other tabs export the token formats one at a time.
+- **Verification kit:** proof that a feature was built as its view shows. The **Verification kit** tab photographs every screen of every view at fixed widths (375, 768 and 1440 pixels, full page, unless the view's flow block sets `capture`) and packages the screenshots with a static, clickable copy of the design and two scripts, as a zip or into `basis-verify/` in the product's folder (the linked repo by default). The agent that implements the feature runs `capture.mjs` to photograph the design and its implementation on the same machine with the same settings, and `compare.mjs` to compare them pixel for pixel, aiming at 0% difference. Parts allowed to differ are named exceptions in `exceptions.json`, each with a reason. Basis takes the screenshots with Playwright's Chromium when it is installed (`npx playwright install chromium`), otherwise with Chrome or Edge; each screen is captured twice, and screens that render differently each time are reported, since nothing can match them.
 
 ## Privacy
 

package/capture.html

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

package/package.json

@@ -1,70 +1,72 @@
-{
-  "name": "basis-design",
-  "version": "0.1.1",
-  "description": "Prompt a complete design system into existence with your own coding agent over ACP.",
-  "keywords": [
-    "design-system",
-    "design-tokens",
-    "react",
-    "claude-code",
-    "codex",
-    "agent-client-protocol"
-  ],
-  "license": "Apache-2.0",
-  "author": "Lucas Skog",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/sockulags/basis-design.git"
-  },
-  "type": "module",
-  "bin": {
-    "basis": "bin/basis.js"
-  },
-  "files": [
-    "bin",
-    "server",
-    "shared",
-    "src",
-    "template",
-    "index.html",
-    "preview.html",
-    "vite.config.ts",
-    "NOTICE"
-  ],
-  "engines": {
-    "node": ">=22.12.0"
-  },
-  "scripts": {
-    "dev": "tsx server/index.ts",
-    "start": "tsx server/index.ts",
-    "typecheck": "tsc --noEmit",
-    "test": "node --import tsx --test \"test/*.test.ts\"",
-    "test:e2e": "playwright test",
-    "template:history": "tsx scripts/template-history.ts",
-    "lint": "oxlint",
-    "format": "prettier --write .",
-    "check": "tsc --noEmit && oxlint && prettier --check . && npm test"
-  },
-  "dependencies": {
-    "@agentclientprotocol/sdk": "^1.9.0",
-    "@types/react": "^19.3.0",
-    "@types/react-dom": "^19.3.0",
-    "@vitejs/plugin-react": "^6.1.2",
-    "axe-core": "^4.14.0",
-    "fflate": "^0.8.3",
-    "react": "^19.3.1",
-    "react-dom": "^19.3.1",
-    "tsx": "^4.23.15",
-    "typescript": "^7.0.2",
-    "vite": "^8.3.4",
-    "ws": "^8.22.0",
-    "zod": "^4.6.7"
-  },
-  "devDependencies": {
-    "@playwright/test": "^1.64.1",
-    "@types/node": "^26.6.5",
-    "@types/ws": "^8.18.2",
-    "oxlint": "1.88.0",
-    "prettier": "3.9.10"
-  }
-}
+{
+  "name": "basis-design",
+  "version": "0.2.0",
+  "description": "Prompt a complete design system into existence with your own coding agent over ACP.",
+  "keywords": [
+    "design-system",
+    "design-tokens",
+    "react",
+    "claude-code",
+    "codex",
+    "agent-client-protocol"
+  ],
+  "license": "Apache-2.0",
+  "author": "Lucas Skog",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sockulags/basis-design.git"
+  },
+  "type": "module",
+  "bin": {
+    "basis": "bin/basis.js"
+  },
+  "files": [
+    "bin",
+    "server",
+    "shared",
+    "src",
+    "template",
+    "index.html",
+    "preview.html",
+    "capture.html",
+    "vite.config.ts",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "dev": "tsx server/index.ts",
+    "start": "tsx server/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test \"test/*.test.ts\"",
+    "test:e2e": "playwright test",
+    "template:history": "tsx scripts/template-history.ts",
+    "lint": "oxlint",
+    "format": "prettier --write .",
+    "check": "tsc --noEmit && oxlint && prettier --check . && npm test"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^1.9.0",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.2",
+    "axe-core": "^4.14.0",
+    "fflate": "^0.8.3",
+    "playwright-core": "1.64.1",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.4",
+    "ws": "^8.22.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.64.1",
+    "@types/node": "^26.6.5",
+    "@types/ws": "^8.18.2",
+    "oxlint": "1.88.0",
+    "prettier": "3.9.10"
+  }
+}

package/server/brief.ts

@@ -160,9 +160,20 @@ The rules that always apply:
   restyle or copy them inside a view: if a screen needs something they lack, extend the component or pattern,
   or add a pattern. A view's own code is layout and wiring; a small layout style inline or in a
   \`.module.css\` next to it is fine.
-- Fill views with realistic made-up data, consistent across the screens (the row you open is the one the
-  detail shows), in the product's language when a product repo is linked. Keep sample data in the view file or
-  a \`views/*-data.ts\` file.
+- A screen is the whole page as the product shows it at that size: its shell, navigation and page padding
+  included, filling the window. The verification kit photographs each screen alone at fixed widths, and the
+  implementation of the feature must match those images pixel for pixel.
+- Fill views with realistic data, consistent across the screens (the row you open is the one the detail
+  shows). When a product repo is linked, use the product's own data where you can find it (fixtures, seeds,
+  example responses, its wording), so the implementation can show exactly the same records. Otherwise make it
+  up in the product's language. Keep data in the view file or a \`views/*-data.ts\` file.
+- Screens must render the same every time: no \`Date.now()\`, \`new Date()\` without a fixed date, random
+  values, or animations and loading states that never settle. Basis captures each screen twice and reports
+  the ones that differ.
+- A flow block may say how its screens are captured: \`capture: { widths: [375, 768, 1440], height: "full",
+  themes: ["light"] }\` (those are the defaults). \`height\` is \`"full"\` for the whole page or a number for
+  exactly one viewport; add \`"dark"\` to \`themes\` when the product has a dark theme. Set widths to the
+  product's breakpoints when you know them.
 - Views are not exported with the design system and need no contract or index.
 - To review a view, show its specimen; \`rows\` picks screens by label or id (\`"rows": ["Shipment"]\`). The panes
   of a review move through the flow together, so before and after always show the same screen.

package/server/capture.ts

@@ -0,0 +1,128 @@
+import { chromium, type Browser, type LaunchOptions } from "playwright-core";
+import { READY_ATTRIBUTE, shotFile, type CaptureShot, type CaptureView } from "../shared/capture.ts";
+
+/*
+ * Taking the verification kit's screenshots: a headless browser opens each screen of each view on the capture
+ * page (capture.html) at the size its shots ask for. Everything that could make two runs differ is fixed: the
+ * device scale, the colour profile, text antialiasing, reduced motion. Each shot is taken twice, and a screen
+ * whose two images differ is reported as unstable, since nothing could ever match it pixel for pixel.
+ */
+
+/** Chromium flags that keep rendering the same between runs and machines of one platform. */
+export const CAPTURE_ARGS = [
+  "--force-color-profile=srgb",
+  "--font-render-hinting=none",
+  "--disable-lcd-text",
+  "--hide-scrollbars",
+];
+
+export interface CaptureBrowser {
+  browser: Browser;
+  name: string;
+  version: string;
+}
+
+/**
+ * Playwright's own Chromium when it is installed (`npx playwright install chromium`): the same build on every
+ * machine, which is what comparing screenshots wants. Otherwise the Chrome or Edge already on this computer.
+ */
+export async function launchCaptureBrowser(): Promise<CaptureBrowser> {
+  const candidates: { name: string; options: LaunchOptions }[] = [
+    { name: "Playwright Chromium", options: {} },
+    { name: "Google Chrome", options: { channel: "chrome" } },
+    { name: "Microsoft Edge", options: { channel: "msedge" } },
+  ];
+  for (const { name, options } of candidates) {
+    try {
+      const browser = await chromium.launch({ ...options, headless: true, args: CAPTURE_ARGS });
+      return { browser, name, version: browser.version() };
+    } catch {
+      // Not installed; try the next one.
+    }
+  }
+  throw new Error(
+    "No browser to take the screenshots with. Install Google Chrome or Microsoft Edge, or run `npx playwright install chromium`.",
+  );
+}
+
+export interface Shot extends CaptureShot {
+  view: string;
+  screen: string;
+  file: string;
+  png: Buffer;
+  /** The image's height in pixels: the page's height for full-page shots. */
+  imageHeight: number;
+  /** False when two captures of the shot differed, so the screen does not render the same every time. */
+  stable: boolean;
+  /** Set when the screen threw while rendering. */
+  failed: boolean;
+}
+
+export interface CaptureResult {
+  views: CaptureView[];
+  problems: string[];
+  shots: Shot[];
+}
+
+/** The height stored in a PNG's IHDR chunk. */
+function pngHeight(png: Buffer): number {
+  return png.length >= 24 ? png.readUInt32BE(20) : 0;
+}
+
+/**
+ * Captures every shot of every view the capture page at `pageUrl` lists. `pageUrl` is the page without a query
+ * (".../capture.html" on the preview server, ".../index.html" in the kit's copy of the design).
+ */
+export async function captureViews(
+  pageUrl: string,
+  browser: Browser,
+  onProgress?: (done: number, total: number) => void,
+): Promise<CaptureResult> {
+  const context = await browser.newContext({
+    deviceScaleFactor: 1,
+    reducedMotion: "reduce",
+    colorScheme: "light",
+    viewport: { width: 1440, height: 900 },
+  });
+  try {
+    const page = await context.newPage();
+    await page.goto(`${pageUrl}?list`);
+    await page.waitForSelector(`html[${READY_ATTRIBUTE}]`, { state: "attached", timeout: 60_000 });
+    const listed = await page.evaluate(() => window.__basisViews);
+    const views = listed?.views ?? [];
+    const problems = listed?.problems ?? [];
+    const total = views.reduce((sum, view) => sum + view.screens.reduce((count, s) => count + s.shots.length, 0), 0);
+    const shots: Shot[] = [];
+    for (const view of views) {
+      for (const screen of view.screens) {
+        for (const shot of screen.shots) {
+          const url = `${pageUrl}?view=${encodeURIComponent(view.id)}&screen=${encodeURIComponent(screen.id)}&theme=${shot.theme}`;
+          await page.setViewportSize({ width: shot.width, height: shot.viewportHeight });
+          const take = async () => {
+            await page.goto(url);
+            await page.waitForSelector(`html[${READY_ATTRIBUTE}]`, { state: "attached", timeout: 60_000 });
+            const failed = await page.evaluate(() => document.documentElement.hasAttribute("data-basis-error"));
+            const png = await page.screenshot({ fullPage: shot.fullPage, animations: "disabled", caret: "hide" });
+            return { png, failed };
+          };
+          const first = await take();
+          const second = await take();
+          shots.push({
+            ...shot,
+            view: view.id,
+            screen: screen.id,
+            file: shotFile(view.id, screen.id, shot),
+            png: first.png,
+            imageHeight: pngHeight(first.png),
+            stable: first.png.equals(second.png),
+            failed: first.failed,
+          });
+          onProgress?.(shots.length, total);
+        }
+      }
+    }
+    return { views, problems, shots };
+  } finally {
+    await context.close();
+  }
+}

package/server/folders.ts

@@ -0,0 +1,125 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+/*
+ * Choosing folders without typing their path: the operating system's own folder dialog (Basis runs on the same
+ * computer as the browser), and the git repos found in the usual places for code.
+ */
+
+/** The folder the user chose, or null when they cancelled. Throws when this system has no folder dialog. */
+export async function pickFolder(title: string, start?: string): Promise<string | null> {
+  const from = start && existsSync(start) ? start : os.homedir();
+  // Title and start folder travel as variables, so no quoting can break the scripts.
+  const env = { ...process.env, BASIS_TITLE: title, BASIS_START: from };
+  if (process.platform === "win32") {
+    const shell = (await has("pwsh")) ? "pwsh" : "powershell";
+    return run(shell, ["-NoProfile", "-NonInteractive", "-STA", "-Command", WINDOWS_DIALOG], env);
+  }
+  if (process.platform === "darwin") {
+    const chosen = await run("osascript", ["-e", MAC_DIALOG], env);
+    return chosen && chosen.length > 1 ? chosen.replace(/\/$/, "") : chosen;
+  }
+  if (await has("zenity")) {
+    return run("zenity", ["--file-selection", "--directory", `--title=${title}`, `--filename=${from}/`], env);
+  }
+  if (await has("kdialog")) return run("kdialog", ["--getexistingdirectory", from, "--title", title], env);
+  throw new Error("This system has no folder dialog Basis can open (install zenity or kdialog), so type the path.");
+}
+
+// A hidden, topmost owner window keeps the dialog in front of the browser.
+const WINDOWS_DIALOG = `
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+Add-Type -AssemblyName System.Windows.Forms
+$owner = New-Object System.Windows.Forms.Form -Property @{ TopMost = $true; ShowInTaskbar = $false; Opacity = 0 }
+$owner.Show()
+$dialog = New-Object System.Windows.Forms.FolderBrowserDialog
+$dialog.Description = $env:BASIS_TITLE
+$dialog.SelectedPath = $env:BASIS_START
+try { $dialog.UseDescriptionForTitle = $true } catch {}
+if ($dialog.ShowDialog($owner) -eq [System.Windows.Forms.DialogResult]::OK) { [Console]::Out.Write($dialog.SelectedPath) }
+$owner.Close()
+`;
+
+const MAC_DIALOG = `POSIX path of (choose folder with prompt (system attribute "BASIS_TITLE") default location (POSIX file (system attribute "BASIS_START")))`;
+
+/** Runs a dialog: its output is the chosen path; cancelling exits non-zero with nothing printed. */
+function run(command: string, args: string[], env: NodeJS.ProcessEnv): Promise<string | null> {
+  return new Promise((resolve, reject) => {
+    execFile(command, args, { env, windowsHide: true, encoding: "utf8" }, (error, stdout) => {
+      const chosen = stdout.trim();
+      if (chosen) return resolve(chosen);
+      if (error && "code" in error && typeof error.code === "string") return reject(error); // Not found, not run.
+      resolve(null);
+    });
+  });
+}
+
+function has(command: string): Promise<boolean> {
+  const probe = process.platform === "win32" ? "where" : "which";
+  return new Promise((resolve) => execFile(probe, [command], { windowsHide: true }, (error) => resolve(!error)));
+}
+
+export interface RepoSuggestion {
+  name: string;
+  dir: string;
+}
+
+/** Folders under the home folder where people usually keep their code. */
+const CODE_FOLDERS = [
+  "Code",
+  "code",
+  "Projects",
+  "projects",
+  "dev",
+  "Dev",
+  "Developer",
+  "src",
+  "repos",
+  "Repos",
+  "git",
+  "GitHub",
+  "workspace",
+  path.join("Documents", "GitHub"),
+  path.join("source", "repos"),
+];
+
+/**
+ * Git repos in the usual places for code, up to two levels down, the most recently used first (by the git index,
+ * which changes with every checkout and commit). `skip` leaves out folders such as Basis' own.
+ */
+export async function suggestRepos(home = os.homedir(), skip: string[] = [], limit = 12): Promise<RepoSuggestion[]> {
+  const found = new Map<string, number>();
+  const visit = async (dir: string, depth: number) => {
+    if (found.size >= 200) return;
+    const git = path.join(dir, ".git");
+    // The code folder itself is never the suggestion, even when someone made it a repo.
+    if (depth < 2 && existsSync(git)) {
+      const index = await stat(path.join(git, "index")).catch(() => stat(git));
+      found.set(dir, index.mtimeMs);
+      return;
+    }
+    if (depth === 0) return;
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith(".") || entry.name === "node_modules") continue;
+      await visit(path.join(dir, entry.name), depth - 1);
+    }
+  };
+  // One folder once, also when a case-insensitive disk finds it as both "Code" and "code".
+  const roots = new Map<string, string>();
+  for (const folder of CODE_FOLDERS) {
+    const dir = path.join(home, folder);
+    const info = await stat(dir).catch(() => null);
+    if (info?.isDirectory() && !roots.has(`${info.dev}:${info.ino}`)) roots.set(`${info.dev}:${info.ino}`, dir);
+  }
+  for (const root of roots.values()) await visit(root, 2);
+  const skipped = skip.map((dir) => path.resolve(dir).toLowerCase());
+  return [...found]
+    .filter(([dir]) => !skipped.some((other) => path.resolve(dir).toLowerCase() === other))
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, limit)
+    .map(([dir]) => ({ name: path.basename(dir), dir }));
+}

package/server/index.ts

@@ -15,8 +15,10 @@ import {
 } from "../shared/protocol.ts";
 import { createInstruction, importInstruction, templateInstruction, viewInstruction } from "./brief.ts";
 import { buildStarterKit, slug, writeStarterKit, zipStarterKit } from "./export.ts";
+import { buildVerificationKit, writeVerificationKit, zipVerificationKit } from "./verify.ts";
 import { PreviewReports } from "./previews.ts";
 import { guard, isLocalHost, OpenProject, refuseHost, type ProjectOptions } from "./project.ts";
+import { pickFolder, suggestRepos } from "./folders.ts";
 import { checkRepo, Projects } from "./projects.ts";
 import { templateChanges } from "./template.ts";
 
@@ -98,16 +100,62 @@ const chromeVite = await createVite({
   // Vite forwards browser console errors to the terminal when it thinks an agent runs it; for Basis that is noise.
   server: { middlewareMode: true, hmr: { server: chromeServer }, forwardConsole: false },
 });
-const chromeGuard = guard((url) => url === "/preview.html");
+const chromeGuard = guard((url) => url === "/preview.html" || url === "/capture.html");
 chromeServer.on("request", (req, res) => {
   if (!isLocalHost(req, port)) return refuseHost(res);
   if (req.method === "GET" && req.url === "/export/starter-kit.zip") {
     void sendStarterKitZip(res);
     return;
   }
+  if (req.method === "GET" && req.url === "/export/verification-kit.zip") {
+    sendVerificationZip(res);
+    return;
+  }
+  if (req.url?.startsWith("/api/")) {
+    void handleApi(req, res);
+    return;
+  }
   chromeGuard(req, res, () => chromeVite.middlewares(req, res));
 });
 
+/** True while a folder dialog is open: one at a time. */
+let picking = false;
+
+/**
+ * Small requests the chrome makes and waits for: a folder from the system's dialog, repos to suggest. Only POSTs
+ * from the chrome's own origin, so another web page can neither open dialogs on this computer nor read the answer.
+ */
+async function handleApi(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+  const reply = (status: number, body: unknown) => {
+    res.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+    res.end(JSON.stringify(body));
+  };
+  if (req.method !== "POST" || !chromeOrigins.includes(req.headers.origin ?? "")) return reply(403, {});
+  let body: { title?: string; start?: string };
+  try {
+    let raw = "";
+    for await (const chunk of req) raw += chunk;
+    body = raw ? JSON.parse(raw) : {};
+  } catch {
+    return reply(400, {});
+  }
+  if (req.url === "/api/pick-folder") {
+    if (picking) return reply(409, { error: "A folder dialog is already open." });
+    picking = true;
+    try {
+      return reply(200, { path: await pickFolder(body.title ?? "Choose a folder", body.start) });
+    } catch (error) {
+      return reply(200, { path: null, error: (error as Error).message });
+    } finally {
+      picking = false;
+    }
+  }
+  if (req.url === "/api/repos") {
+    return reply(200, { repos: await suggestRepos(undefined, [root, current.entry.dir]) });
+  }
+  reply(404, {});
+}
+
 async function starterKit() {
   return buildStarterKit(current.workspace.state.design, current.workspace.dir);
 }
@@ -129,6 +177,59 @@ async function sendStarterKitZip(res: http.ServerResponse): Promise<void> {
   }
 }
 
+/** The last verification kit built as a zip, until it is downloaded or another is built. */
+let verificationZip: { name: string; data: Uint8Array } | null = null;
+/** True while a verification kit is being built: one at a time, and no project switch meanwhile. */
+let verifying = false;
+
+function sendVerificationZip(res: http.ServerResponse): void {
+  if (!verificationZip) {
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("No verification kit has been built. Build one from the Export dialog.");
+    return;
+  }
+  res.writeHead(200, {
+    "Content-Type": "application/zip",
+    "Content-Disposition": `attachment; filename="${verificationZip.name}"`,
+    "Content-Length": verificationZip.data.byteLength,
+    "Cache-Control": "no-store",
+  });
+  res.end(verificationZip.data);
+}
+
+/** Builds the verification kit for the open project, reporting progress to every tab. */
+async function verificationKit(project: string | undefined, socket: WebSocket): Promise<void> {
+  if (verifying) {
+    send(socket, { type: "verify-result", result: { ok: false, error: "A verification kit is already being built." } });
+    return;
+  }
+  verifying = true;
+  try {
+    const { files, summary } = await buildVerificationKit({
+      design: current.workspace.state.design,
+      workspaceDir: current.workspace.dir,
+      onProgress: (step, done, total) => broadcast({ type: "verify-progress", step, done, total }),
+    });
+    if (project === undefined) {
+      verificationZip = {
+        name: `${slug(current.workspace.state.design.name)}-verification-kit.zip`,
+        data: zipVerificationKit(files),
+      };
+      broadcast({ type: "verify-result", result: { ok: true, summary } });
+      return;
+    }
+    const written = await writeVerificationKit(files, project);
+    broadcast({
+      type: "verify-result",
+      result: written.ok ? { ok: true, summary, dir: written.dir } : { ok: false, error: written.error },
+    });
+  } catch (error) {
+    broadcast({ type: "verify-result", result: { ok: false, error: (error as Error).message } });
+  } finally {
+    verifying = false;
+  }
+}
+
 chromeServer.on("upgrade", (req, socket, head) => {
   if (req.url !== "/bridge") return; // Vite's HMR socket handles its own upgrades.
   if (!chromeOrigins.includes(req.headers.origin ?? "")) {
@@ -171,6 +272,13 @@ async function switchTo(entry: ProjectEntry, socket: WebSocket): Promise<void> {
     send(socket, { type: "project-error", message: "The agent is working. Switch projects when it is done." });
     return;
   }
+  if (verifying) {
+    send(socket, {
+      type: "project-error",
+      message: "A verification kit is being built. Switch projects when it is done.",
+    });
+    return;
+  }
   switching = true;
   const previous = current.entry;
   broadcast({ type: "project-switching", project: entry });
@@ -314,6 +422,9 @@ async function handle(message: ClientMessage, socket: WebSocket): Promise<void>
       send(socket, { type: "export-result", result });
       return;
     }
+    case "verify-kit":
+      await verificationKit(typeof message.project === "string" ? message.project : undefined, socket);
+      return;
     case "project-switch": {
       const entry = projects.find(String(message.id ?? ""));
       if (entry) await switchTo(entry, socket);

package/server/project.ts

@@ -86,7 +86,7 @@ export class OpenProject {
       root,
       appType: "mpa",
       cacheDir: "node_modules/.vite/preview",
-      optimizeDeps: { entries: ["preview.html"] },
+      optimizeDeps: { entries: ["preview.html", "capture.html"] },
       plugins: [rebasePlugin(root, entry.dir)],
       resolve: {
         alias: {
@@ -112,6 +112,12 @@ export class OpenProject {
     const previewGuard = guard((url) => url === "/" || url === "/index.html");
     previewServer.on("request", (req, res) => {
       if (!isLocalHost(req, options.previewPort)) return refuseHost(res);
+      // The capture page (capture.html) reads the current tokens from here, as the kit's copy reads its own file.
+      if (req.method === "GET" && req.url?.split("?")[0] === "/design.json") {
+        res.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+        res.end(JSON.stringify(workspace.state.design));
+        return;
+      }
       previewGuard(req, res, () => previewVite.middlewares(req, res));
     });
     await new Promise<void>((resolve, reject) => {