@recursica/adapter-tester 5.3.0 → 5.4.0

package/dist/cli.js

@@ -1,17 +1,18 @@
 #!/usr/bin/env node
-import { spawn as I, spawnSync as W } from "node:child_process";
-import { readFileSync as T, mkdirSync as M, writeFileSync as E, existsSync as U } from "node:fs";
-import { dirname as N, join as a, resolve as $ } from "node:path";
-import { fileURLToPath as G, pathToFileURL as B } from "node:url";
+import { spawn as W, spawnSync as re } from "node:child_process";
+import { readFileSync as O, mkdirSync as B, writeFileSync as E, existsSync as A } from "node:fs";
+import { dirname as M, join as l, resolve as C } from "node:path";
+import { fileURLToPath as z, pathToFileURL as oe } from "node:url";
+import { chromium as se } from "@playwright/test";
 import K from "express";
-import { createProxyMiddleware as X } from "http-proxy-middleware";
-import Y from "node:net";
-import { m as z } from "./mantineSourceOfTruth-CAKhcVCT.js";
-import { a as Q, i as Z } from "./index-DqQzFSAH.js";
-const ee = /\x1b\[[0-9;]*m/g, te = /Local:\s*(https?:\/\/localhost:\d+)/;
-function re(e) {
+import { createProxyMiddleware as ne } from "http-proxy-middleware";
+import { a as ie, b as ae, c as ce, d as de, e as ue, f as le, i as pe } from "./runVisualRegression-CQk97Qkv.js";
+import he from "node:net";
+import { m as fe } from "./mantineSourceOfTruth-xUEi1k8U.js";
+const me = /\x1b\[[0-9;]*m/g, ge = /Local:\s*(https?:\/\/localhost:\d+)/;
+function ye(e) {
   return new Promise((t) => {
-    const r = new Y.Socket();
+    const r = new he.Socket();
     r.setTimeout(200), r.once("connect", () => {
       r.destroy(), t(!0);
     }), r.once("timeout", () => {
@@ -21,60 +22,60 @@ function re(e) {
     }), r.connect(e, "127.0.0.1");
   });
 }
-function oe(e) {
+function we(e) {
   try {
-    const t = JSON.parse(T(e, "utf8")).port;
+    const t = JSON.parse(O(e, "utf8")).port;
     return typeof t == "number" ? t : void 0;
   } catch {
     return;
   }
 }
-function se(e, t) {
-  M(N(e), { recursive: !0 }), E(e, JSON.stringify({ port: t }));
+function ve(e, t) {
+  B(M(e), { recursive: !0 }), E(e, JSON.stringify({ port: t }));
 }
-function ne(e, t) {
-  return new Promise((r, o) => {
-    var y, w;
-    const s = I(e.command, {
+function be(e, t) {
+  return new Promise((r, s) => {
+    var w, u;
+    const a = W(e.command, {
       cwd: e.cwd,
       stdio: "pipe",
       shell: !0
     });
-    let n = !1;
-    const p = setTimeout(() => {
-      n || (n = !0, s.kill(), o(
+    let i = !1;
+    const g = setTimeout(() => {
+      i || (i = !0, a.kill(), s(
         new Error(
           `Timed out after ${t}ms waiting for ${e.name}'s Storybook to report its URL (no "Local: http://localhost:<port>" line seen in its output).`
         )
       ));
-    }, t), l = (i, u) => {
-      const h = i.toString();
-      for (const c of h.split(`
+    }, t), y = (o, n) => {
+      const c = o.toString();
+      for (const p of c.split(`
 `))
-        if (c.trim()) {
-          const m = u ? `${e.name} SB ERROR` : `${e.name} SB`;
-          (u ? console.error : console.log)(`[${m}] ${c.trim()}`);
+        if (p.trim()) {
+          const f = n ? `${e.name} SB ERROR` : `${e.name} SB`;
+          (n ? console.error : console.log)(`[${f}] ${p.trim()}`);
         }
-      if (n) return;
-      const v = h.replace(ee, "").match(te);
-      if (v) {
-        n = !0, clearTimeout(p);
-        const c = v[1], m = Number(new URL(c).port);
-        se(e.cacheFile, m), r({ url: c, port: m, process: s });
+      if (i) return;
+      const d = c.replace(me, "").match(ge);
+      if (d) {
+        i = !0, clearTimeout(g);
+        const p = d[1], f = Number(new URL(p).port);
+        ve(e.cacheFile, f), r({ url: p, port: f, process: a });
       }
     };
-    (y = s.stdout) == null || y.on("data", (i) => l(i, !1)), (w = s.stderr) == null || w.on("data", (i) => l(i, !0)), s.on("error", (i) => {
-      n || (n = !0, clearTimeout(p), o(i));
-    }), s.on("exit", (i) => {
-      n || (n = !0, clearTimeout(p), o(
+    (w = a.stdout) == null || w.on("data", (o) => y(o, !1)), (u = a.stderr) == null || u.on("data", (o) => y(o, !0)), a.on("error", (o) => {
+      i || (i = !0, clearTimeout(g), s(o));
+    }), a.on("exit", (o) => {
+      i || (i = !0, clearTimeout(g), s(
         new Error(
-          `${e.name}'s Storybook exited (code ${i}) before reporting its URL.`
+          `${e.name}'s Storybook exited (code ${o}) before reporting its URL.`
         )
       ));
     });
   });
 }
-function A(e, t) {
+function L(e, t) {
   return {
     name: e,
     command: t.command,
@@ -84,10 +85,10 @@ function A(e, t) {
     timeoutMs: t.timeout
   };
 }
-async function D(e) {
+async function R(e) {
   if (e.reuseExistingServer) {
-    const t = oe(e.cacheFile);
-    if (t !== void 0 && await re(t))
+    const t = we(e.cacheFile);
+    if (t !== void 0 && await ye(t))
       return console.log(
         `[Dev Launcher] ${e.name} is already running on port ${t} (reused).`
       ), {
@@ -96,155 +97,285 @@ async function D(e) {
         process: null
       };
   }
-  return console.log(`[Dev Launcher] Launching Storybook for ${e.name}...`), ne(e, e.timeoutMs ?? 120 * 1e3);
+  return console.log(`[Dev Launcher] Launching Storybook for ${e.name}...`), be(e, e.timeoutMs ?? 120 * 1e3);
 }
-const _ = N(G(import.meta.url));
-function ie(e) {
+const G = M(z(import.meta.url));
+function Te(e) {
   const t = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-  console.log(`[Dev Launcher] Auto-launching browser: ${e}`), I(t, [e], { shell: process.platform === "win32" }).on(
+  console.log(`[Dev Launcher] Auto-launching browser: ${e}`), W(t, [e], { shell: process.platform === "win32" }).on(
     "error",
     (r) => {
       console.error("[Dev Launcher] Failed to auto-launch browser:", r);
     }
   );
 }
-async function ae(e, t, r = {}) {
-  const [o, s] = e.targets, [n, p] = t;
-  if (!(o != null && o.sourceOfTruth) || !s || s.sourceOfTruth || !n || !p)
+function ke(e) {
+  const t = l(
+    e,
+    "node_modules/@recursica/adapter-mantine-v8/package.json"
+  ), r = A(t) ? t : l(e, "package.json");
+  return JSON.parse(O(r, "utf8")).version;
+}
+const Se = 6010, U = (e) => `data:image/png;base64,${e.toString("base64")}`;
+function Oe(e, t, r, s, a) {
+  let i, g = Promise.resolve();
+  const y = (u) => ue(
+    u,
+    Object.fromEntries(
+      Object.entries(t.stories ?? {}).filter(([, o]) => o.sourceOfTruthThreshold !== void 0).map(([o, n]) => [o, n.sourceOfTruthThreshold])
+    ),
+    t.sourceOfTruthThresholdPixels
+  ), w = async (u) => {
+    i ?? (i = se.launch());
+    const o = await (await i).newPage(), n = ae(u, t.stories ?? {});
+    try {
+      await o.setViewportSize(n), await o.goto(`${r}/iframe.html?id=${u}&viewMode=story`, {
+        waitUntil: "networkidle"
+      });
+      const c = await ce(o), d = await s.readImage(u), p = y(u);
+      if (!d)
+        return {
+          status: "no-golden",
+          diffPixels: null,
+          threshold: p,
+          viewport: n,
+          golden: null,
+          diff: null
+        };
+      const { diffPixels: f, diffImage: v } = de(c, d);
+      return {
+        status: v ? "ok" : "size-mismatch",
+        diffPixels: v ? f : null,
+        threshold: p,
+        viewport: n,
+        golden: U(d),
+        diff: v ? U(v) : null
+      };
+    } finally {
+      await o.close();
+    }
+  };
+  return e.get("/__golden/diff", (u, o) => {
+    if (s instanceof Error) {
+      o.status(503).json({ error: s.message });
+      return;
+    }
+    const n = String(u.query.id ?? "");
+    if (!n) {
+      o.status(400).json({ error: "id is required" });
+      return;
+    }
+    const c = g.then(() => w(n));
+    g = c.catch(() => {
+    }), c.then(
+      (d) => o.json(d),
+      (d) => o.status(500).json({ error: d.message })
+    );
+  }), e.get("/__golden/image", async (u, o) => {
+    const n = s instanceof Error ? null : await s.readImage(String(u.query.id ?? ""));
+    if (!n) {
+      o.status(404).end();
+      return;
+    }
+    o.type("image/png").send(n);
+  }), e.post("/__golden/threshold", K.json(), (u, o) => {
+    var p, f;
+    const { id: n, value: c } = u.body ?? {};
+    if (typeof n != "string" || !n || !Number.isInteger(c) || c < 0) {
+      o.status(400).json({ error: "id (string) and value (integer >= 0) are required" });
+      return;
+    }
+    const d = A(a) ? JSON.parse(O(a, "utf8")) : {};
+    d.stories = {
+      ...d.stories,
+      [n]: { ...(p = d.stories) == null ? void 0 : p[n], sourceOfTruthThreshold: c }
+    }, E(a, JSON.stringify(d, null, 2) + `
+`), t.stories = {
+      ...t.stories,
+      [n]: { ...(f = t.stories) == null ? void 0 : f[n], sourceOfTruthThreshold: c }
+    }, o.json({ id: n, value: c });
+  }), {
+    close: async () => {
+      i && await (await i).close();
+    }
+  };
+}
+async function xe(e, t, r) {
+  const [s, a] = e.targets, [i, g] = t;
+  if (!(s != null && s.sourceOfTruth) || !a || a.sourceOfTruth || !g || !i)
     throw new Error(
       "adapter-tester dev mode requires exactly two targets: [sourceOfTruth, target] — check adapter-tester.config.json."
     );
-  const l = r.port ?? 6010;
+  if (!e.sourceOfTruthGolden)
+    throw new Error(
+      "adapter-tester dev mode needs a sourceOfTruthGolden location to diff against — check adapter-tester.config.json."
+    );
   console.log(
-    `[Dev Launcher] Resolving ${o.name} and ${s.name} Storybooks...`
+    `[Dev Launcher] Resolving ${s.name} and ${a.name} Storybooks...`
   );
-  const [y, w] = await Promise.all([
-    D(
-      A(o.name, n)
+  const [y, w, u] = await Promise.all([
+    R(
+      L(s.name, i)
     ),
-    D(A(s.name, p))
+    R(L(a.name, g)),
+    // The live Storybooks still work without the golden (e.g. offline), so
+    // a failure here only disables Golden/Compute Diff, loudly.
+    ie(e.sourceOfTruthGolden).catch(
+      (m) => (console.warn(
+        `[Dev Launcher] WARNING: source-of-truth golden unavailable — Golden and Compute Diff are disabled: ${m.message}`
+      ), m)
+    )
   ]);
-  console.log("[Dev Launcher] Both Storybooks are active and responsive!");
-  const i = [y.process, w.process].filter(
-    (f) => f !== null
-  ), u = K(), h = a(_, "../public"), v = a(_, "../report-header.txt");
-  u.get("/", (f, b, k) => {
-    if (f.query.path) {
-      k();
+  console.log("[Dev Launcher] Dev Mode is ready!");
+  const o = [y.process, w.process].filter(
+    (m) => !!m
+  ), n = K(), c = l(G, "../public"), d = l(G, "../report-header.txt"), p = ke(
+    i.cwd
+  ), f = Oe(
+    n,
+    e,
+    w.url,
+    u,
+    r.configPath
+  );
+  n.get("/", (m, S, x) => {
+    if (m.query.path) {
+      x();
       return;
     }
-    const S = T(a(h, "index.html"), "utf8").replace(
+    const te = O(l(c, "index.html"), "utf8").replace(
       "<head>",
       `<head>
   <script>window.__ADAPTER_TESTER__ = ${JSON.stringify({
-        ownName: s.name,
-        sourceOfTruthName: o.name,
+        ownName: a.name,
+        sourceOfTruthName: s.name,
+        sourceOfTruthVersion: p,
         sourceOfTruthPort: y.port
       })};<\/script>`
     );
-    b.send(S);
-  }), u.get("/report-header.txt", (f, b) => {
+    S.send(te);
+  }), n.get("/report-header.txt", (m, S) => {
     if (e.reportHeader !== void 0) {
-      b.type("text/plain").send(e.reportHeader);
+      S.type("text/plain").send(e.reportHeader);
       return;
     }
     try {
-      b.type("text/plain").send(T(v, "utf8"));
+      S.type("text/plain").send(O(d, "utf8"));
     } catch {
-      b.status(500).send("Error loading report-header.txt");
+      S.status(500).send("Error loading report-header.txt");
     }
-  }), u.use(
+  }), n.use(
     "/",
-    X({
+    ne({
       target: w.url,
       changeOrigin: !0,
       ws: !0
     })
   );
-  let c = !1;
-  const m = () => {
-    if (!c) {
-      c = !0, console.log(
+  let v = !1;
+  const P = () => {
+    if (!v) {
+      v = !0, console.log(
         `
 [Dev Launcher] Shutting down Dev Mode server and spawned Storybooks...`
       );
-      for (const f of i) f.kill("SIGINT");
-      process.exit(0);
+      for (const m of o) m.kill("SIGINT");
+      f.close().finally(() => process.exit(0));
     }
   };
-  process.on("SIGINT", m), process.on("SIGTERM", m), u.listen(l, () => {
-    console.log(`
+  process.on("SIGINT", P), process.on("SIGTERM", P);
+  const b = r.port ?? Se, N = r.port ? b : b + 19;
+  let k = b;
+  for (; ; )
+    try {
+      await new Promise((m, S) => {
+        const x = n.listen(k);
+        x.once("listening", () => m()), x.once("error", S);
+      });
+      break;
+    } catch (m) {
+      if (m.code !== "EADDRINUSE" || k >= N) {
+        console.error(
+          `[Dev Launcher] Dev Mode server failed to listen on port ${k}: ${m.message}. Pass --port <n> to use another port.`
+        );
+        for (const x of o) x.kill("SIGINT");
+        process.exit(1);
+      }
+      console.log(
+        `[Dev Launcher] Port ${k} is in use, trying ${k + 1}...`
+      ), k++;
+    }
+  console.log(`
 ====================================================
 🚀 Adapter Dev Mode proxy running at:
-   http://localhost:${l}
+   http://localhost:${k}
 ====================================================
-`), ie(`http://localhost:${l}`);
-  });
+`), Te(`http://localhost:${k}`);
 }
-const ce = "http://json-schema.org/draft-07/schema#", de = "https://github.com/borderux/recursica/tree/main/packages/adapter-tester/src/adapter-tester.schema.json", ue = "adapter-tester.config.json", pe = "Configuration for @recursica/adapter-tester. All fields are optional — an adapter repo with a normal `storybook` npm script needs no config file at all.", le = "object", he = !1, me = { $schema: { type: "string", description: 'Optional pointer to this schema for editor autocomplete, e.g. "https://raw.githubusercontent.com/borderux/recursica/main/packages/adapter-tester/src/adapter-tester.schema.json".' }, name: { type: "string", description: `Label for this project's own target. Defaults to the unscoped name in this project's package.json (e.g. "@recursica/some-adapter" -> "some-adapter").` }, storybook: { type: "object", additionalProperties: !1, description: "This project's own Storybook target.", properties: { port: { type: "integer", minimum: 1, maximum: 65535, description: "First-guess port only, not authoritative — the real port is auto-detected from this Storybook's own startup output, since Storybook silently falls back to an OS-assigned port whenever this one is taken. Auto-detected from this project's own `scripts.storybook` (a `-p <port>`/`--port <port>` flag) when omitted, falling back to 6006." }, command: { type: "string", description: "Command that boots the target's Storybook. Defaults to `npm run storybook`." }, cwd: { type: "string", description: 'Directory the command runs in, relative to the config file. Defaults to ".".' } } }, sourceOfTruth: { description: 'The comparison target. Defaults to `{ "type": "mantine-harness" }`.', oneOf: [{ type: "object", additionalProperties: !1, description: "Default mode: boots a throwaway harness that installs the published @recursica/adapter-mantine-v8 from npm — no monorepo checkout required.", properties: { type: { const: "mantine-harness" }, port: { type: "integer", minimum: 1, maximum: 65535, description: "First-guess port only, not authoritative — the real port is auto-detected from the throwaway harness's Storybook's own startup output." }, mantineAdapterVersion: { type: "string", description: "npm version/tag of @recursica/adapter-mantine-v8 to install in the harness. Defaults to `latest`." }, storybookTemplateVersion: { type: "string", description: "npm version/tag of @recursica/storybook-template to install in the harness. Defaults to `latest`." }, tokensSource: { type: "string", enum: ["target", "mantine-package"], description: `Which Recursica token snapshot the harness's Mantine components render with. "target" (default): this project's own committed recursica_variables_scoped.css/recursica_tokens.json/recursica_brand.json/recursica_ui-kit.json — makes the divergence check mean exactly "given the same tokens this project is using, does it render the same as Mantine's own components," isolating adapter-mapping correctness from any token-snapshot drift between repos. "mantine-package": @recursica/adapter-mantine-v8's own bundled token files instead (whatever it was last published with) — also flags, as a side effect, a project whose own committed tokens have gone stale relative to Mantine's. Never the deprecated @recursica/official-release package.` } } }, { type: "object", additionalProperties: !1, description: "Non-standard mode: points at an already-addressable Storybook — e.g. a sibling workspace package's own Storybook inside this monorepo.", required: ["type"], properties: { type: { const: "url" }, name: { type: "string", description: 'Label for the source-of-truth target. Defaults to "Mantine".' }, port: { type: "integer", minimum: 1, maximum: 65535, description: "First-guess port only, not authoritative — the real port is auto-detected from the source-of-truth Storybook's own startup output. Defaults to 6011." }, command: { type: "string", description: "Command that boots the source-of-truth Storybook. Defaults to `npm run storybook`." }, cwd: { type: "string", description: 'Directory the command runs in, relative to the config file. Defaults to ".".' } } }] }, isSourceOfTruthAdapter: { type: "boolean", description: "True only for the source-of-truth adapter's own config (@recursica/adapter-mantine-v8). Skips `sourceOfTruth` entirely — there's nothing above it to diverge from — and runs the own-drift golden check standalone, against just this project's own Storybook. Defaults to false." }, goldenThresholdPixels: { type: "number", minimum: 0, description: "Global visual diff threshold for the own-drift check (this project's live render vs. its own committed `test/golden/` image), in mismatched pixels, before a story is considered a failure. Same library/component on both sides, so this should stay tight. Defaults to 10. AI agents must not modify this field — see AGENT.md.", default: 10 }, sourceOfTruthThresholdPixels: { type: "number", minimum: 0, description: "Global visual diff threshold for the source-of-truth divergence check (this project's golden vs. the source-of-truth adapter's golden), in mismatched pixels, before a difference is flagged. Comparing across two different component libraries has legitimate structural variation (native control widgets, font rendering, etc.), so this is expected to be set much higher than `goldenThresholdPixels`. Ignored on the source-of-truth adapter's own config (`isSourceOfTruthAdapter: true`), which has no divergence check. Defaults to 3500. AI agents must not modify this field — see AGENT.md.", default: 3500 }, stories: { type: "object", additionalProperties: { type: "object", additionalProperties: !1, properties: { goldenThreshold: { type: "number", minimum: 0, description: "Diff threshold override for matching stories' own-drift check, in mismatched pixels. Overrides `goldenThresholdPixels`." }, sourceOfTruthThreshold: { type: "number", minimum: 0, description: "Diff threshold override for matching stories' source-of-truth divergence check, in mismatched pixels. Overrides `sourceOfTruthThresholdPixels`." }, viewport: { type: "object", additionalProperties: !1, required: ["width", "height"], description: "Browser viewport (CSS pixels) matching stories are captured at, instead of the default 800x600. For stories whose rendering depends on the page width itself, such as `@media` breakpoints, which a story can't change from inside.", properties: { width: { type: "integer", minimum: 1 }, height: { type: "integer", minimum: 1 } } }, exclude: { type: "boolean", description: "Skip matching stories entirely — no own-drift check, no divergence check, no golden captured. For stories that don't have a cross-adapter counterpart; use `excludeTitlePrefixes` to drop a whole title instead." } } }, description: "Per-story overrides, keyed by story id prefix (a story matches if its id equals the key or starts with it). When more than one key matches a story, the longest (most specific) key wins." }, excludeTitlePrefixes: { type: "array", items: { type: "string" }, description: "Storybook title prefixes to exclude from comparison, in addition to the built-in denylist (`Theme/*`, `Tokens/*`, `Introduction`)." }, reportHeader: { type: "string", description: 'Overrides the AI report header text shown in Dev Mode\'s "Full Report" export. Defaults to the contents of `report-header.txt`.' } }, fe = {
-  $schema: ce,
-  $id: de,
-  title: ue,
-  description: pe,
-  type: le,
-  additionalProperties: he,
-  properties: me
-}, ge = Z, V = new Q.Ajv({ allErrors: !0, strict: !0 });
-ge(V);
-const L = V.compile(fe);
-function ye(e, t) {
-  if (L(e)) return;
-  const r = (L.errors ?? []).map((o) => {
-    var n;
-    const s = (n = o.params) != null && n.additionalProperty ? ` '${o.params.additionalProperty}'` : "";
-    return `  - ${o.instancePath || "root"} ${o.message}${s}`;
+const Pe = "http://json-schema.org/draft-07/schema#", De = "https://github.com/borderux/recursica/tree/main/packages/adapter-tester/src/adapter-tester.schema.json", Ee = "adapter-tester.config.json", je = "Configuration for @recursica/adapter-tester. All fields are optional — an adapter repo with a normal `storybook` npm script needs no config file at all.", Ae = "object", Ne = !1, _e = { $schema: { type: "string", description: 'Optional pointer to this schema for editor autocomplete, e.g. "https://raw.githubusercontent.com/borderux/recursica/main/packages/adapter-tester/src/adapter-tester.schema.json".' }, name: { type: "string", description: `Label for this project's own target. Defaults to the unscoped name in this project's package.json (e.g. "@recursica/some-adapter" -> "some-adapter").` }, storybook: { type: "object", additionalProperties: !1, description: "This project's own Storybook target.", properties: { port: { type: "integer", minimum: 1, maximum: 65535, description: "First-guess port only, not authoritative — the real port is auto-detected from this Storybook's own startup output, since Storybook silently falls back to an OS-assigned port whenever this one is taken. Auto-detected from this project's own `scripts.storybook` (a `-p <port>`/`--port <port>` flag) when omitted, falling back to 6006." }, command: { type: "string", description: "Command that boots the target's Storybook. Defaults to `npm run storybook`." }, cwd: { type: "string", description: 'Directory the command runs in, relative to the config file. Defaults to ".".' } } }, sourceOfTruth: { description: 'The comparison target. Defaults to `{ "type": "mantine-harness" }`.', oneOf: [{ type: "object", additionalProperties: !1, description: "Default mode: boots a throwaway harness that installs the published @recursica/adapter-mantine-v8 from npm — no monorepo checkout required.", properties: { type: { const: "mantine-harness" }, port: { type: "integer", minimum: 1, maximum: 65535, description: "First-guess port only, not authoritative — the real port is auto-detected from the throwaway harness's Storybook's own startup output." }, mantineAdapterVersion: { type: "string", description: "npm version/tag of @recursica/adapter-mantine-v8 to install in the harness. Defaults to `latest`." }, storybookTemplateVersion: { type: "string", description: "npm version/tag of @recursica/storybook-template to install in the harness. Defaults to `latest`." }, tokensSource: { type: "string", enum: ["target", "mantine-package"], description: `Which Recursica token snapshot the harness's Mantine components render with. "target" (default): this project's own committed recursica_variables_scoped.css/recursica_tokens.json/recursica_brand.json/recursica_ui-kit.json — makes the divergence check mean exactly "given the same tokens this project is using, does it render the same as Mantine's own components," isolating adapter-mapping correctness from any token-snapshot drift between repos. "mantine-package": @recursica/adapter-mantine-v8's own bundled token files instead (whatever it was last published with) — also flags, as a side effect, a project whose own committed tokens have gone stale relative to Mantine's. Never the deprecated @recursica/official-release package.` } } }, { type: "object", additionalProperties: !1, description: "Non-standard mode: points at an already-addressable Storybook — e.g. a sibling workspace package's own Storybook inside this monorepo.", required: ["type"], properties: { type: { const: "url" }, name: { type: "string", description: 'Label for the source-of-truth target. Defaults to "Mantine".' }, port: { type: "integer", minimum: 1, maximum: 65535, description: "First-guess port only, not authoritative — the real port is auto-detected from the source-of-truth Storybook's own startup output. Defaults to 6011." }, command: { type: "string", description: "Command that boots the source-of-truth Storybook. Defaults to `npm run storybook`." }, cwd: { type: "string", description: 'Directory the command runs in, relative to the config file. Defaults to ".".' } } }] }, isSourceOfTruthAdapter: { type: "boolean", description: "True only for the source-of-truth adapter's own config (@recursica/adapter-mantine-v8). Skips `sourceOfTruth` entirely — there's nothing above it to diverge from — and runs the own-drift golden check standalone, against just this project's own Storybook. Defaults to false." }, goldenThresholdPixels: { type: "number", minimum: 0, description: "Global visual diff threshold for the own-drift check (this project's live render vs. its own committed `test/golden/` image), in mismatched pixels, before a story is considered a failure. Same library/component on both sides, so this should stay tight. Defaults to 10. AI agents must not modify this field — see AGENT.md.", default: 10 }, sourceOfTruthThresholdPixels: { type: "number", minimum: 0, description: "Global visual diff threshold for the source-of-truth divergence check (this project's golden vs. the source-of-truth adapter's golden), in mismatched pixels, before a difference is flagged. Comparing across two different component libraries has legitimate structural variation (native control widgets, font rendering, etc.), so this is expected to be set much higher than `goldenThresholdPixels`. Ignored on the source-of-truth adapter's own config (`isSourceOfTruthAdapter: true`), which has no divergence check. Defaults to 3500. AI agents must not modify this field — see AGENT.md.", default: 3500 }, stories: { type: "object", additionalProperties: { type: "object", additionalProperties: !1, properties: { goldenThreshold: { type: "number", minimum: 0, description: "Diff threshold override for matching stories' own-drift check, in mismatched pixels. Overrides `goldenThresholdPixels`." }, sourceOfTruthThreshold: { type: "number", minimum: 0, description: "Diff threshold override for matching stories' source-of-truth divergence check, in mismatched pixels. Overrides `sourceOfTruthThresholdPixels`." }, viewport: { type: "object", additionalProperties: !1, required: ["width", "height"], description: "Browser viewport (CSS pixels) matching stories are captured at, instead of the default 800x600. For stories whose rendering depends on the page width itself, such as `@media` breakpoints, which a story can't change from inside.", properties: { width: { type: "integer", minimum: 1 }, height: { type: "integer", minimum: 1 } } }, exclude: { type: "boolean", description: "Skip matching stories entirely — no own-drift check, no divergence check, no golden captured. For stories that don't have a cross-adapter counterpart; use `excludeTitlePrefixes` to drop a whole title instead." } } }, description: "Per-story overrides, keyed by story id prefix (a story matches if its id equals the key or starts with it). When more than one key matches a story, the longest (most specific) key wins." }, excludeTitlePrefixes: { type: "array", items: { type: "string" }, description: "Storybook title prefixes to exclude from comparison, in addition to the built-in denylist (`Theme/*`, `Tokens/*`, `Introduction`)." }, reportHeader: { type: "string", description: 'Overrides the AI report header text shown in Dev Mode\'s "Full Report" export. Defaults to the contents of `report-header.txt`.' } }, $e = {
+  $schema: Pe,
+  $id: De,
+  title: Ee,
+  description: je,
+  type: Ae,
+  additionalProperties: Ne,
+  properties: _e
+}, Ie = pe, X = new le.Ajv({ allErrors: !0, strict: !0 });
+Ie(X);
+const V = X.compile($e);
+function Le(e, t) {
+  if (V(e)) return;
+  const r = (V.errors ?? []).map((s) => {
+    var i;
+    const a = (i = s.params) != null && i.additionalProperty ? ` '${s.params.additionalProperty}'` : "";
+    return `  - ${s.instancePath || "root"} ${s.message}${a}`;
   }).join(`
 `);
   throw new Error(`Invalid ${t}:
 ${r}`);
 }
-const we = "@recursica/adapter-mantine-v8", ve = "adapter-tester.config.json", F = "npm run storybook", be = 6006, R = 6011, C = "Mantine", ke = 10, Te = 3500;
-function H(e) {
-  const t = a(e, "package.json");
-  if (!U(t))
+const Re = "@recursica/adapter-mantine-v8", Y = "adapter-tester.config.json", q = "npm run storybook", Fe = 6006, J = 6011, H = "Mantine", Me = 10, Ce = 3500;
+function Q(e) {
+  const t = l(e, "package.json");
+  if (!A(t))
     throw new Error(
       `No package.json found in ${e} — run adapter-tester from the root of the project being tested.`
     );
-  return JSON.parse(T(t, "utf8"));
+  return JSON.parse(O(t, "utf8"));
 }
-function Se(e) {
-  var s;
-  const r = (s = H(e).scripts) == null ? void 0 : s.storybook, o = r == null ? void 0 : r.match(/(?:-p|--port)[ =](\d+)/);
-  return o ? Number(o[1]) : be;
+function Ge(e) {
+  var a;
+  const r = (a = Q(e).scripts) == null ? void 0 : a.storybook, s = r == null ? void 0 : r.match(/(?:-p|--port)[ =](\d+)/);
+  return s ? Number(s[1]) : Fe;
 }
-function Oe(e) {
-  const r = H(e).name;
+function Ue(e) {
+  const r = Q(e).name;
   return r ? r.split("/").pop() : "Adapter";
 }
-function xe(e) {
-  const t = a(e, ve);
-  if (!U(t))
+function Ve(e) {
+  const t = l(e, Y);
+  if (!A(t))
     return {};
-  const r = JSON.parse(T(t, "utf8"));
-  return ye(r, t), r;
+  const r = JSON.parse(O(t, "utf8"));
+  return Le(r, t), r;
 }
-function Ee(e, t = {}) {
-  var m, f, b;
-  const r = xe(e), o = r.isSourceOfTruthAdapter ?? !1;
-  if (t.mantineAdapterVersion && o)
+function qe(e, t = {}) {
+  var f, v, P;
+  const r = Ve(e), s = r.isSourceOfTruthAdapter ?? !1;
+  if (t.mantineAdapterVersion && s)
     throw new Error(
       "--source-of-truth-version has no effect on the source-of-truth adapter's own config (isSourceOfTruthAdapter: true) — there's nothing to pin a version for."
     );
-  const s = r.name ?? Oe(e), n = ((m = r.storybook) == null ? void 0 : m.port) ?? Se(e), p = ((f = r.storybook) == null ? void 0 : f.command) ?? F, l = $(e, ((b = r.storybook) == null ? void 0 : b.cwd) ?? "."), y = {
-    command: p,
-    port: n,
-    cwd: l,
+  const a = r.name ?? Ue(e), i = ((f = r.storybook) == null ? void 0 : f.port) ?? Ge(e), g = ((v = r.storybook) == null ? void 0 : v.command) ?? q, y = C(e, ((P = r.storybook) == null ? void 0 : P.cwd) ?? "."), w = {
+    command: g,
+    port: i,
+    cwd: y,
     reuseExistingServer: !process.env.CI,
-    cacheFile: a(e, ".adapter-tester", "last-port-own.json"),
+    cacheFile: l(e, ".adapter-tester", "last-port-own.json"),
     timeout: 120 * 1e3
-  }, w = {
-    goldenThresholdPixels: r.goldenThresholdPixels ?? ke,
-    sourceOfTruthThresholdPixels: r.sourceOfTruthThresholdPixels ?? Te,
+  }, u = {
+    goldenThresholdPixels: r.goldenThresholdPixels ?? Me,
+    sourceOfTruthThresholdPixels: r.sourceOfTruthThresholdPixels ?? Ce,
     stories: r.stories,
     excludeTitlePrefixes: r.excludeTitlePrefixes,
     reportHeader: r.reportHeader,
@@ -254,153 +385,164 @@ function Ee(e, t = {}) {
     // to that package's own `test/golden/` (the same directory used when
     // that package runs adapter-tester directly), not a directory under
     // wherever this config file lives.
-    goldenDir: a(l, "test", "golden"),
-    isSourceOfTruthAdapter: o,
+    goldenDir: l(y, "test", "golden"),
+    isSourceOfTruthAdapter: s,
     // Overwritten by the CLI from --update-golden/--approve-divergence.
     goldenMode: "check",
     // Overwritten by the CLI from --divergence-only.
     checkMode: "own"
   };
-  if (o)
+  if (s)
     return {
       engineConfig: {
-        ...w,
-        targets: [{ name: s, url: `http://localhost:${n}` }]
+        ...u,
+        targets: [{ name: a, url: `http://localhost:${i}` }]
       },
-      webServers: [y]
+      webServers: [w]
     };
-  const i = r.sourceOfTruth ?? {
+  const o = r.sourceOfTruth ?? {
     type: "mantine-harness"
   };
-  let u, h, v, c;
-  if (i.type === "url") {
+  let n, c, d, p;
+  if (o.type === "url") {
     if (t.mantineAdapterVersion)
       throw new Error(
         `--source-of-truth-version has no effect with sourceOfTruth.type: "url" — that mode reads a sibling package's local checkout directly, not a published version.`
       );
-    u = i.name ?? C, h = i.port ?? R;
-    const k = $(e, i.cwd ?? ".");
-    v = {
-      command: i.command ?? F,
-      port: h,
-      cwd: k,
+    n = o.name ?? H, c = o.port ?? J;
+    const b = C(e, o.cwd ?? ".");
+    d = {
+      command: o.command ?? q,
+      port: c,
+      cwd: b,
       reuseExistingServer: !process.env.CI,
-      cacheFile: a(e, ".adapter-tester", "last-port-source-of-truth.json"),
+      cacheFile: l(e, ".adapter-tester", "last-port-source-of-truth.json"),
       timeout: 120 * 1e3
-    }, c = {
+    }, p = {
       type: "local",
-      dir: a(k, "test", "golden")
+      dir: l(b, "test", "golden")
     };
   } else {
-    u = C, h = i.port ?? R;
-    const k = t.mantineAdapterVersion ?? i.mantineAdapterVersion, S = i.tokensSource ?? "target";
-    v = z({
-      dir: a(e, ".adapter-tester/mantine-harness"),
-      port: h,
-      mantineAdapterVersion: k,
-      storybookTemplateVersion: i.storybookTemplateVersion,
-      tokensSource: S,
+    n = H, c = o.port ?? J;
+    const b = t.mantineAdapterVersion ?? o.mantineAdapterVersion, N = o.tokensSource ?? "target";
+    d = fe({
+      dir: l(e, ".adapter-tester/mantine-harness"),
+      port: c,
+      mantineAdapterVersion: b,
+      storybookTemplateVersion: o.storybookTemplateVersion,
+      tokensSource: N,
       // `ownCwd`, not `cwd` — the project actually being tested (same
       // reasoning `goldenDir` above uses), source of the 4 token files
       // copied into the harness when `tokensSource` is "target".
-      targetDir: l
-    }), c = {
+      targetDir: y
+    }), p = {
       type: "npm",
-      packageName: we,
-      versionSpec: k ?? "latest",
-      cacheDir: a(e, ".adapter-tester/mantine-golden-cache")
+      packageName: Re,
+      versionSpec: b ?? "latest",
+      cacheDir: l(e, ".adapter-tester/mantine-golden-cache")
     };
   }
   return {
     engineConfig: {
-      ...w,
+      ...u,
       targets: [
         {
-          name: u,
-          url: `http://localhost:${h}`,
+          name: n,
+          url: `http://localhost:${c}`,
           sourceOfTruth: !0
         },
-        { name: s, url: `http://localhost:${n}` }
+        { name: a, url: `http://localhost:${i}` }
       ],
-      sourceOfTruthGolden: c
+      sourceOfTruthGolden: p
     },
     // [sourceOfTruth, own] — Dev Mode needs both; the automated golden run
     // (cli.ts) only ever boots the last entry, since its divergence check
     // reads stored golden files, not a live source-of-truth page.
-    webServers: [v, y]
+    webServers: [d, w]
   };
 }
-const Ae = N(G(import.meta.url)), De = B(a(Ae, "testing.js")).href, d = process.argv.slice(2);
-let J;
-const O = d.indexOf("--source-of-truth-version");
-if (O !== -1) {
-  const e = d[O + 1];
+const Je = M(z(import.meta.url)), He = oe(l(Je, "testing.js")).href, h = process.argv.slice(2);
+let Z;
+const _ = h.indexOf("--source-of-truth-version");
+if (_ !== -1) {
+  const e = h[_ + 1];
   if (e === void 0 || e.startsWith("--"))
     throw new Error(
       "--source-of-truth-version requires a value, e.g. --source-of-truth-version 0.53.0"
     );
-  J = e, d.splice(O, 2);
+  Z = e, h.splice(_, 2);
+}
+let D;
+const $ = h.indexOf("--port");
+if ($ !== -1) {
+  const e = h[$ + 1];
+  if (D = Number(e), e === void 0 || !Number.isInteger(D) || D <= 0)
+    throw new Error("--port requires a port number, e.g. --port 6020");
+  h.splice($, 2);
 }
-let q;
-const x = d.indexOf("--story");
-if (x !== -1) {
-  const e = d[x + 1];
+let ee;
+const I = h.indexOf("--story");
+if (I !== -1) {
+  const e = h[I + 1];
   if (e === void 0 || e.startsWith("--"))
     throw new Error(
       "--story requires a story id, e.g. --story ui-kit-button--loading"
     );
-  q = e, d.splice(x, 2);
+  ee = e, h.splice(I, 2);
 }
-const P = process.cwd(), { engineConfig: g, webServers: j } = Ee(P, {
-  mantineAdapterVersion: J
+const j = process.cwd(), { engineConfig: T, webServers: F } = qe(j, {
+  mantineAdapterVersion: Z
 });
-d.includes("--update-golden") ? g.goldenMode = "update-golden" : d.includes("--approve-divergence") && (g.goldenMode = "approve-divergence");
-if (d.includes("--divergence-only")) {
-  if (g.isSourceOfTruthAdapter)
+h.includes("--update-golden") ? T.goldenMode = "update-golden" : h.includes("--approve-divergence") && (T.goldenMode = "approve-divergence");
+if (h.includes("--divergence-only")) {
+  if (T.isSourceOfTruthAdapter)
     throw new Error(
       "--divergence-only has nothing to diverge from — isSourceOfTruthAdapter is true in this project's adapter-tester.config.json."
     );
-  g.checkMode = "divergence";
-} else if (g.goldenMode === "approve-divergence")
+  T.checkMode = "divergence";
+} else if (T.goldenMode === "approve-divergence")
   throw new Error(
     "--approve-divergence only makes sense with --divergence-only — there's nothing to approve without the divergence check running."
   );
-d.includes("--dry-run") && (console.log(JSON.stringify({ engineConfig: g, webServers: j }, null, 2)), process.exit(0));
-const Pe = /* @__PURE__ */ new Set([
+h.includes("--dry-run") && (console.log(JSON.stringify({ engineConfig: T, webServers: F }, null, 2)), process.exit(0));
+const We = /* @__PURE__ */ new Set([
   "--dry-run",
   "--serve",
   "--update-golden",
   "--approve-divergence",
   "--divergence-only"
-]), je = d.filter((e) => !Pe.has(e));
-Ne().catch((e) => {
+]), Be = h.filter((e) => !We.has(e));
+ze().catch((e) => {
   console.error(e), process.exitCode = 1;
 });
-async function Ne() {
-  if (d.includes("--serve")) {
-    if (g.isSourceOfTruthAdapter)
+async function ze() {
+  if (h.includes("--serve")) {
+    if (T.isSourceOfTruthAdapter)
       throw new Error(
         "Dev Mode (--serve) has nothing to sync this project's Storybook against — isSourceOfTruthAdapter is true in this project's adapter-tester.config.json."
       );
-    await ae(g, j);
+    await xe(T, F, {
+      port: D,
+      configPath: l(j, Y)
+    });
   } else {
-    const e = j.at(-1);
+    const e = F.at(-1);
     if (!e)
       throw new Error("resolveConfig() returned no webServers to boot.");
-    await $e(e, g);
+    await Ke(e, T);
   }
 }
-async function $e(e, t) {
-  const r = a(P, ".adapter-tester/run");
-  M(r, { recursive: !0 });
-  const o = t.targets.at(-1);
-  if (!o)
+async function Ke(e, t) {
+  const r = l(j, ".adapter-tester/run");
+  B(r, { recursive: !0 });
+  const s = t.targets.at(-1);
+  if (!s)
     throw new Error("resolveConfig() returned no targets to check.");
-  const { url: s, process: n } = await D(
-    A(o.name, e)
+  const { url: a, process: i } = await R(
+    L(s.name, e)
   );
-  o.url = s, E(
-    a(r, "playwright.config.js"),
+  s.url = a, E(
+    l(r, "playwright.config.js"),
     `// Generated by \`adapter-tester\` — do not edit, regenerated on every run.
 import { defineConfig, devices } from "@playwright/test";
 
@@ -423,10 +565,10 @@ export default defineConfig({
 });
 `
   ), E(
-    a(r, "visual-regression.spec.js"),
+    l(r, "visual-regression.spec.js"),
     `// Generated by \`adapter-tester\` — do not edit, regenerated on every run.
 import { test, expect } from "@playwright/test";
-import { resolveVisualRegressionPlan } from ${JSON.stringify(De)};
+import { resolveVisualRegressionPlan } from ${JSON.stringify(He)};
 
 // \`test.describe\`/\`test\` are called here, not inside resolveVisualRegressionPlan,
 // so Playwright's HTML report groups the suite under this file instead of a
@@ -436,7 +578,7 @@ const { ownTargetName, suiteLabel, stories, missingFromSourceOfTruth, checkStory
 
 // Set from \`--story <story-id>\` — scopes this run to exactly one story and
 // skips the (suite-wide) parity check, which has nothing to do with it.
-const storyId = ${JSON.stringify(q ?? null)};
+const storyId = ${JSON.stringify(ee ?? null)};
 const scopedStories = storyId
   ? stories.filter((story) => story.id === storyId)
   : stories;
@@ -462,20 +604,20 @@ test.describe(\`\${ownTargetName} — \${suiteLabel}\`, () => {
 `
   );
   try {
-    const p = W(
+    const g = re(
       "npx",
       [
         "playwright",
         "test",
         "--config",
-        a(r, "playwright.config.js"),
-        ...je
+        l(r, "playwright.config.js"),
+        ...Be
       ],
-      { stdio: "inherit", cwd: P, shell: process.platform === "win32" }
+      { stdio: "inherit", cwd: j, shell: process.platform === "win32" }
     );
-    process.exitCode = p.status ?? 1;
+    process.exitCode = g.status ?? 1;
   } finally {
-    n == null || n.kill("SIGTERM");
+    i == null || i.kill("SIGTERM");
   }
 }
 //# sourceMappingURL=cli.js.map