basis-design 0.1.0 → 0.2.0

package/server/verify-kit/capture.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/*
+ * Takes the verification kit's screenshots on this machine, with the settings Basis used (basis-verify.json):
+ *
+ *   node basis-verify/capture.mjs design [--out <dir>]                     the design, into expected/
+ *   node basis-verify/capture.mjs app [--targets <file>] [--out <dir>]     the implementation, into actual/
+ *
+ * Options for both: --only <view>[/<screen>] to capture part of the kit, --channel chrome|msedge to use an
+ * installed browser instead of Playwright's Chromium.
+ *
+ * Needs Playwright in the project (`npm i -D playwright` and `npx playwright install chromium`). Capture both
+ * sides with the same machine and browser: fonts and antialiasing differ between systems, so only images taken
+ * the same way can match pixel for pixel. Compare them with compare.mjs.
+ */
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import http from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const kit = path.dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+const mode = args[0];
+
+function option(name, fallback) {
+  const index = args.indexOf(name);
+  return index === -1 ? fallback : args[index + 1];
+}
+
+async function playwright() {
+  for (const name of ["playwright", "playwright-core", "@playwright/test"]) {
+    try {
+      const module = await import(name);
+      return module.chromium ?? module.default?.chromium;
+    } catch {
+      // Not installed here; try the next one.
+    }
+  }
+  throw new Error(
+    "Playwright is not installed in this project. Run `npm i -D playwright` and `npx playwright install chromium`.",
+  );
+}
+
+const TYPES = {
+  ".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",
+  ".jpg": "image/jpeg",
+  ".woff2": "font/woff2",
+  ".woff": "font/woff",
+};
+
+/** Serves the kit's copy of the design on a free local port. */
+async function serveDesign() {
+  const root = path.join(kit, "design");
+  const server = http.createServer(async (req, res) => {
+    const pathname = decodeURIComponent(new URL(req.url ?? "/", "http://local").pathname);
+    const file = path.join(root, pathname === "/" ? "index.html" : pathname);
+    if (!file.startsWith(root + path.sep)) {
+      res.writeHead(403).end();
+      return;
+    }
+    try {
+      const body = await readFile(file);
+      res.writeHead(200, { "Content-Type": TYPES[path.extname(file)] ?? "application/octet-stream" });
+      res.end(body);
+    } catch {
+      res.writeHead(404).end();
+    }
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  return { server, url: `http://127.0.0.1:${server.address().port}/index.html` };
+}
+
+/** Waits until fonts are loaded, images decoded and the layout keeps its size, as the design's page does. */
+async function settle(page) {
+  await page.evaluate(async () => {
+    const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+    await document.fonts.ready;
+    await Promise.all([...document.images].map((image) => image.decode().catch(() => undefined)));
+    let last = "";
+    for (let attempt = 0; attempt < 40; attempt++) {
+      await wait(50);
+      const size = `${document.documentElement.scrollWidth}x${document.documentElement.scrollHeight}`;
+      if (size === last) break;
+      last = size;
+    }
+  });
+}
+
+function targetFor(targets, view, screen) {
+  const entry = targets.screens?.[`${view}/${screen}`];
+  if (!entry) return undefined;
+  const target = typeof entry === "string" ? { url: entry } : entry;
+  return { ...target, url: new URL(target.url, targets.baseUrl ?? undefined).href };
+}
+
+async function main() {
+  if (mode !== "design" && mode !== "app") {
+    console.error("Usage: node capture.mjs design|app [--targets <file>] [--out <dir>] [--only <view>[/<screen>]]");
+    process.exitCode = 2;
+    return;
+  }
+  const manifest = JSON.parse(await readFile(path.join(kit, "basis-verify.json"), "utf8"));
+  const { render } = manifest;
+  const out = option("--out")
+    ? path.resolve(option("--out"))
+    : path.join(kit, mode === "design" ? "expected" : "actual");
+  const only = option("--only");
+  let targets = {};
+  const targetsFile = option("--targets") ? path.resolve(option("--targets")) : path.join(kit, "targets.json");
+  if (mode === "app") {
+    if (!existsSync(targetsFile)) {
+      throw new Error(`No targets file at ${targetsFile}. See README.md, "Capture the implementation".`);
+    }
+    targets = JSON.parse(await readFile(targetsFile, "utf8"));
+  }
+
+  const chromium = await playwright();
+  const browser = await chromium.launch({ headless: true, args: render.args, channel: option("--channel") });
+  console.log(
+    `Browser: ${browser.version()}${browser.version() === manifest.browser.version ? "" : ` (Basis used ${manifest.browser.version})`}`,
+  );
+  const design = mode === "design" ? await serveDesign() : undefined;
+  const context = await browser.newContext({
+    deviceScaleFactor: render.deviceScaleFactor,
+    reducedMotion: render.reducedMotion,
+    colorScheme: render.colorScheme,
+    viewport: { width: 1440, height: 900 },
+    ...(mode === "app" && targets.storageState
+      ? { storageState: path.resolve(path.dirname(targetsFile), targets.storageState) }
+      : {}),
+  });
+  const page = await context.newPage();
+  let taken = 0;
+  let skipped = 0;
+  const unstable = [];
+  try {
+    for (const view of manifest.views) {
+      for (const screen of view.screens) {
+        const key = `${view.id}/${screen.id}`;
+        if (only && only !== view.id && only !== key) continue;
+        const target = mode === "app" ? targetFor(targets, view.id, screen.id) : undefined;
+        if (mode === "app" && !target) {
+          console.log(`skip     ${key}: no target in targets.json`);
+          skipped++;
+          continue;
+        }
+        for (const shot of screen.shots) {
+          await page.setViewportSize({ width: shot.width, height: shot.viewportHeight });
+          await page.emulateMedia({ colorScheme: shot.theme });
+          const take = async () => {
+            if (design) {
+              const query = `?view=${encodeURIComponent(view.id)}&screen=${encodeURIComponent(screen.id)}&theme=${shot.theme}`;
+              await page.goto(design.url + query);
+              await page.waitForSelector(manifest.design.ready, { state: "attached", timeout: 60_000 });
+            } else {
+              await page.goto(target.url, { waitUntil: "networkidle" });
+              if (target.waitFor) await page.waitForSelector(target.waitFor, { timeout: 60_000 });
+              if (targets.themeAttribute) {
+                await page.evaluate(
+                  ([name, value]) => document.documentElement.setAttribute(name, value),
+                  [targets.themeAttribute, shot.theme],
+                );
+              }
+              await page.addStyleTag({ content: render.neutralCss });
+              await settle(page);
+            }
+            return page.screenshot({ fullPage: shot.fullPage, animations: "disabled", caret: "hide" });
+          };
+          const first = await take();
+          const second = await take();
+          const name = shot.file.replace(/^screens\//, "");
+          const file = path.join(out, name);
+          await mkdir(path.dirname(file), { recursive: true });
+          await writeFile(file, first);
+          taken++;
+          const stable = first.equals(second);
+          if (!stable) unstable.push(name);
+          console.log(`${stable ? "ok      " : "UNSTABLE"} ${name}`);
+        }
+      }
+    }
+  } finally {
+    await context.close();
+    await browser.close();
+    design?.server.close();
+  }
+  console.log(
+    `\n${taken} shots in ${path.relative(process.cwd(), out) || "."}${skipped ? `, ${skipped} screens without a target` : ""}.`,
+  );
+  if (unstable.length) {
+    console.log(
+      `${unstable.length} shots differed between two captures, so they can never match exactly: ${unstable.join(", ")}. ` +
+        "Look for clocks, random values, animations or content that loads late.",
+    );
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 2;
+});

package/server/verify-kit/compare.d.mts

@@ -0,0 +1,39 @@
+export interface Image {
+  width: number;
+  height: number;
+  data: Buffer;
+}
+export interface Region {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+export interface Exception {
+  name: string;
+  reason?: string;
+  view: string;
+  screen?: string;
+  widths?: number[];
+  themes?: string[];
+  region?: Region;
+}
+export function decodePng(buffer: Buffer): Image;
+export function encodePng(image: Image): Buffer;
+export function compareImages(
+  expected: Image,
+  actual: Image,
+  options?: { tolerance?: number; regions?: Region[] },
+): {
+  width: number;
+  height: number;
+  sameSize: boolean;
+  differing: number;
+  counted: number;
+  percent: number;
+  diff: Image;
+};
+export function exceptionsFor<T extends Exception>(
+  exceptions: T[],
+  shot: { view: string; screen: string; width: number; theme: string },
+): T[];

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;
+  });
+}