basis-design 0.1.0 → 0.2.0

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.
+`;
+}

package/server/workspace.ts

@@ -4,7 +4,7 @@ import { readdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { DEFAULT_DESIGN, parseDesignText, type Design } from "../shared/design.ts";
 import { fixedColorFindings } from "../shared/fixed-colors.ts";
-import type { DesignState, HistoryEntry, Snapshot } from "../shared/protocol.ts";
+import type { DesignState, HistoryEntry, Snapshot, TemplateUpdate } from "../shared/protocol.ts";
 import { REVIEW_FILE, type ReviewState } from "../shared/review.ts";
 import { git, lines, typecheck } from "./exec.ts";
 import { commitToHistory, describeSource, loadHistory, type EntryMeta, type Source } from "./history.ts";
@@ -12,6 +12,7 @@ import { DESIGN_FILE, isSourcePath, PRODUCT_FILE, relativeInside, SOURCE_DIRS }
 import { reachedSpecimens } from "./reach.ts";
 import { Reviews } from "./reviews.ts";
 import { claimWorkspaceFormat, seedWorkspace, writeGeneratedFiles } from "./setup.ts";
+import { recordTemplateVersion, templateUpdate, writeTemplateCopy } from "./template.ts";
 import { Snapshots } from "./snapshots.ts";
 
 const DIFF_LIMIT = 400_000;
@@ -46,6 +47,8 @@ export class Workspace extends EventEmitter<Events> {
   /** A hand edit being checked and recorded (see onFsEvent); close() waits for it. */
   private settling: Promise<void> = Promise.resolve();
   private closed = false;
+  /** A newer starter template this workspace has not caught up with (see server/template.ts). */
+  private template: TemplateUpdate | null = null;
   /** True while an agent turn runs; its changes are committed once, when the turn ends. */
   agentActive = false;
 
@@ -73,6 +76,8 @@ export class Workspace extends EventEmitter<Events> {
     const hasCommits = (await git(this.dir, ["rev-list", "-n", "1", "--all"]).catch(() => "")).trim() !== "";
     await this.commit(hasCommits ? (note ? "upgrade" : "external") : "init", note ? { label: note } : {});
     this.history = await loadHistory(this.dir);
+    this.template = await templateUpdate(this.dir);
+    if (this.template) await writeTemplateCopy(this.dir);
     // Copies of past versions from earlier runs, except the open review's starting point.
     await this.snapshots.prune(this.reviews.state?.baseline);
     await this.readReviewRequest();
@@ -101,9 +106,22 @@ export class Workspace extends EventEmitter<Events> {
       reviewErrors: this.reviews.errors,
       colorFindings: this.colorFindings,
       workspace: this.dir,
+      templateUpdate: this.template,
     };
   }
 
+  get templateUpdate(): TemplateUpdate | null {
+    return this.template;
+  }
+
+  /** Records the newer template as caught up with, whether its changes were brought in or skipped. */
+  async settleTemplateUpdate(): Promise<void> {
+    if (!this.template) return;
+    await recordTemplateVersion(this.dir, this.template.to);
+    this.template = null;
+    this.emit("design", this.state);
+  }
+
   get entries(): HistoryEntry[] {
     return this.history;
   }

package/shared/capture.ts

@@ -0,0 +1,75 @@
+/*
+ * Capturing views for verification: each screen of a view is photographed at fixed sizes, and the implementation
+ * of the feature is later checked against those screenshots pixel for pixel. Shared by the capture page (which
+ * renders one screen) and the server (which takes the screenshots).
+ */
+
+export type CaptureTheme = "light" | "dark";
+
+/** What a flow block may say about capturing (template/components/specimen.ts, `Capture`). */
+export interface CaptureOptions {
+  widths?: number[];
+  height?: "full" | number;
+  themes?: CaptureTheme[];
+}
+
+/** One screenshot of one screen. */
+export interface CaptureShot {
+  width: number;
+  /** The viewport's height. With `fullPage` the image is as tall as the page; without, exactly this tall. */
+  viewportHeight: number;
+  fullPage: boolean;
+  theme: CaptureTheme;
+}
+
+export const DEFAULT_CAPTURE_WIDTHS = [375, 768, 1440];
+
+/**
+ * The viewport height that goes with a width, for full-page captures too: elements sized in vh (an app shell,
+ * a full-height hero) take it, so the design and the implementation must be photographed with the same one.
+ */
+export function viewportHeightFor(width: number): number {
+  if (width <= 480) return 812;
+  if (width <= 1024) return 1024;
+  return 900;
+}
+
+const MIN_SIZE = 200;
+const MAX_SIZE = 4000;
+
+/** The screenshots a flow block asks for, with Basis' defaults filled in and nonsense left out. */
+export function captureShots(options: CaptureOptions | undefined): CaptureShot[] {
+  const widths = [...new Set((options?.widths?.length ? options.widths : DEFAULT_CAPTURE_WIDTHS).map(Math.round))]
+    .filter((width) => width >= MIN_SIZE && width <= MAX_SIZE)
+    .sort((a, b) => a - b);
+  const themes = [...new Set(options?.themes?.length ? options.themes : (["light"] as CaptureTheme[]))].filter(
+    (theme) => theme === "light" || theme === "dark",
+  );
+  const fixed = typeof options?.height === "number" ? Math.round(options.height) : null;
+  const height = fixed !== null && fixed >= MIN_SIZE && fixed <= MAX_SIZE ? fixed : null;
+  return themes.flatMap((theme) =>
+    widths.map((width) => ({
+      width,
+      viewportHeight: height ?? viewportHeightFor(width),
+      fullPage: height === null,
+      theme,
+    })),
+  );
+}
+
+/** The file name of a shot inside the kit: "screens/<view>/<screen>@<width>[-dark].png". */
+export function shotFile(view: string, screen: string, shot: CaptureShot): string {
+  const theme = shot.theme === "light" ? "" : `-${shot.theme}`;
+  const height = shot.fullPage ? "" : `x${shot.viewportHeight}`;
+  return `screens/${view}/${screen}@${shot.width}${height}${theme}.png`;
+}
+
+/** What the capture page reports about the views it can render (`?list`). */
+export interface CaptureView {
+  id: string;
+  title: string;
+  screens: { id: string; label: string; shots: CaptureShot[] }[];
+}
+
+/** The attribute the capture page sets on <html> once a screen has settled and can be photographed. */
+export const READY_ATTRIBUTE = "data-basis-ready";

package/shared/protocol.ts

@@ -115,6 +115,29 @@ export interface ExportWriteResult {
   error?: string;
 }
 
+/** What a finished verification kit holds, for the Export dialog to report. */
+export interface VerifyKitSummary {
+  /** The browser that took the screenshots, with its version. */
+  browser: string;
+  views: number;
+  screens: number;
+  shots: number;
+  /** Shots whose two captures differed: those screens do not render the same twice. */
+  unstable: string[];
+  /** Shots of screens that threw while rendering. */
+  failed: string[];
+  /** Specimen files that could not be loaded. */
+  problems: string[];
+}
+
+export type VerifyKitResult =
+  | {
+      ok: true;
+      summary: VerifyKitSummary;
+      /** Where it was written; absent for a zip, which is then ready to download. */ dir?: string;
+    }
+  | { ok: false; error: string };
+
 export interface DesignState {
   design: Design;
   /** Validation errors for the file on disk; null when it is valid. The preview keeps the last valid design. */
@@ -126,6 +149,17 @@ export interface DesignState {
   /** Colours in tokens and stylesheets that stay the same in both themes (see shared/fixed-colors.ts). */
   colorFindings: string[];
   workspace: string;
+  /** A newer starter template whose changes the agent can bring into this workspace; null when caught up. */
+  templateUpdate: TemplateUpdate | null;
+}
+
+/** A newer starter template the workspace has not caught up with (see server/template.ts). */
+export interface TemplateUpdate {
+  /** The template version the workspace last caught up with (0: before versions were recorded). */
+  from: number;
+  to: number;
+  /** Starter files the workspace has changed, which differ from the current template. */
+  files: string[];
 }
 
 /** A past version materialised for a review: its tokens, and where the preview can import its source. */
@@ -175,7 +209,10 @@ export type ServerMessage =
   | { type: "chat-remove"; id: string }
   | { type: "snapshot"; snapshot: Snapshot }
   | { type: "export-manifest"; folder: string; files: { path: string; bytes: number }[] }
-  | { type: "export-result"; result: ExportWriteResult };
+  | { type: "export-result"; result: ExportWriteResult }
+  /** How far the verification kit has come; `done`/`total` while it takes screenshots. */
+  | { type: "verify-progress"; step: string; done?: number; total?: number }
+  | { type: "verify-result"; result: VerifyKitResult };
 
 export type ClientMessage =
   /** With `alternatives` (2 or 3), the agent makes that many takes on the prompt to choose between. */
@@ -207,6 +244,8 @@ export type ClientMessage =
   | { type: "preview-errors"; errors: string[]; visible: boolean; checks?: string[]; checking?: boolean }
   | { type: "export-manifest" }
   | { type: "export-write"; target: string; overwrite: boolean }
+  /** Builds the verification kit: into `<project>/basis-verify/` with `project`, else as a zip to download. */
+  | { type: "verify-kit"; project?: string }
   | { type: "project-switch"; id: string }
   /** Creates a project from Basis' defaults, or as a copy of the open project's design system, and opens it. */
   /**
@@ -223,4 +262,8 @@ export type ClientMessage =
    */
   | { type: "project-repo"; id: string; repo: string | null; bringIn?: boolean }
   /** Starts the guided turn that brings the open project's product repo design system into the workspace. */
-  | { type: "import-design" };
+  | { type: "import-design" }
+  /** Starts the guided turn that brings the newer starter template's changes into the workspace. */
+  | { type: "template-update" }
+  /** Marks the newer template as seen without bringing its changes in. */
+  | { type: "template-skip" };

package/src/Workbench.tsx

@@ -214,9 +214,10 @@ export function Workbench({ state, send }: { state: BridgeState; send: (message:
         picking={picking}
         onTogglePick={() => (picking ? finishPicking() : setPicking(true))}
         reviewing={Boolean(review)}
+        resizer={!chatHidden && <ChatResizer width={chatWidth} onResize={setChatWidth} />}
       />
-      {!chatHidden && <ChatResizer width={chatWidth} onResize={setChatWidth} />}
       <main className={styles.main}>
+        <h1 className="visually-hidden">Basis</h1>
         <TopBar
           chatHidden={chatHidden}
           onToggleChat={() => setChatHidden((hidden) => !hidden)}
@@ -236,6 +237,7 @@ export function Workbench({ state, send }: { state: BridgeState; send: (message:
               projects={state.projects}
               agentBusy={state.agent?.status === "busy"}
               error={state.projectError}
+              templateUpdate={state.design?.templateUpdate ?? null}
               send={send}
             />
           }
@@ -334,6 +336,7 @@ export function Workbench({ state, send }: { state: BridgeState; send: (message:
           result={state.exportResult}
           send={send}
           onClose={() => setExporting(false)}
+          verify={{ repo: state.project?.repo, progress: state.verifyProgress, result: state.verifyResult }}
         />
       )}
     </div>