@recursica/adapter-tester 5.0.1 → 5.1.0

package/dist/cli.js

@@ -1,17 +1,17 @@
 #!/usr/bin/env node
-import { spawn as _, spawnSync as q } from "node:child_process";
-import { readFileSync as S, mkdirSync as F, writeFileSync as O, existsSync as I } from "node:fs";
-import { dirname as D, join as a, resolve as j } from "node:path";
-import { fileURLToPath as M, pathToFileURL as H } from "node:url";
-import W from "express";
-import { createProxyMiddleware as B } from "http-proxy-middleware";
-import K from "node:net";
-import { m as X } from "./mantineSourceOfTruth-DE7XOgea.js";
-import { a as Y, i as z } from "./index-DqQzFSAH.js";
-const Q = /\x1b\[[0-9;]*m/g, Z = /Local:\s*(https?:\/\/localhost:\d+)/;
-function ee(e) {
+import { spawn as _, spawnSync as W } from "node:child_process";
+import { readFileSync as S, mkdirSync as I, writeFileSync as x, existsSync as M } from "node:fs";
+import { dirname as j, join as a, resolve as $ } from "node:path";
+import { fileURLToPath as U, pathToFileURL as B } from "node:url";
+import K from "express";
+import { createProxyMiddleware as X } from "http-proxy-middleware";
+import Y from "node:net";
+import { m as z } from "./mantineSourceOfTruth-DE7XOgea.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) {
   return new Promise((t) => {
-    const r = new K.Socket();
+    const r = new Y.Socket();
     r.setTimeout(200), r.once("connect", () => {
       r.destroy(), t(!0);
     }), r.once("timeout", () => {
@@ -21,7 +21,7 @@ function ee(e) {
     }), r.connect(e, "127.0.0.1");
   });
 }
-function te(e) {
+function oe(e) {
   try {
     const t = JSON.parse(S(e, "utf8")).port;
     return typeof t == "number" ? t : void 0;
@@ -29,10 +29,10 @@ function te(e) {
     return;
   }
 }
-function re(e, t) {
-  F(D(e), { recursive: !0 }), O(e, JSON.stringify({ port: t }));
+function se(e, t) {
+  I(j(e), { recursive: !0 }), x(e, JSON.stringify({ port: t }));
 }
-function oe(e, t) {
+function ne(e, t) {
   return new Promise((r, o) => {
     var y, w;
     const s = _(e.command, {
@@ -41,32 +41,32 @@ function oe(e, t) {
       shell: !0
     });
     let n = !1;
-    const d = setTimeout(() => {
+    const l = setTimeout(() => {
       n || (n = !0, s.kill(), o(
         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), h = (i, u) => {
-      const l = i.toString();
-      for (const c of l.split(`
+    }, t), f = (i, u) => {
+      const p = i.toString();
+      for (const c of p.split(`
 `))
         if (c.trim()) {
-          const p = u ? `${e.name} SB ERROR` : `${e.name} SB`;
-          (u ? console.error : console.log)(`[${p}] ${c.trim()}`);
+          const h = u ? `${e.name} SB ERROR` : `${e.name} SB`;
+          (u ? console.error : console.log)(`[${h}] ${c.trim()}`);
         }
       if (n) return;
-      const v = l.replace(Q, "").match(Z);
+      const v = p.replace(ee, "").match(te);
       if (v) {
-        n = !0, clearTimeout(d);
-        const c = v[1], p = Number(new URL(c).port);
-        re(e.cacheFile, p), r({ url: c, port: p, process: s });
+        n = !0, clearTimeout(l);
+        const c = v[1], h = Number(new URL(c).port);
+        se(e.cacheFile, h), r({ url: c, port: h, process: s });
       }
     };
-    (y = s.stdout) == null || y.on("data", (i) => h(i, !1)), (w = s.stderr) == null || w.on("data", (i) => h(i, !0)), s.on("error", (i) => {
-      n || (n = !0, clearTimeout(d), o(i));
+    (y = s.stdout) == null || y.on("data", (i) => f(i, !1)), (w = s.stderr) == null || w.on("data", (i) => f(i, !0)), s.on("error", (i) => {
+      n || (n = !0, clearTimeout(l), o(i));
     }), s.on("exit", (i) => {
-      n || (n = !0, clearTimeout(d), o(
+      n || (n = !0, clearTimeout(l), o(
         new Error(
           `${e.name}'s Storybook exited (code ${i}) before reporting its URL.`
         )
@@ -74,7 +74,7 @@ function oe(e, t) {
     });
   });
 }
-function x(e, t) {
+function E(e, t) {
   return {
     name: e,
     command: t.command,
@@ -84,10 +84,10 @@ function x(e, t) {
     timeoutMs: t.timeout
   };
 }
-async function E(e) {
+async function A(e) {
   if (e.reuseExistingServer) {
-    const t = te(e.cacheFile);
-    if (t !== void 0 && await ee(t))
+    const t = oe(e.cacheFile);
+    if (t !== void 0 && await re(t))
       return console.log(
         `[Dev Launcher] ${e.name} is already running on port ${t} (reused).`
       ), {
@@ -96,10 +96,10 @@ async function E(e) {
         process: null
       };
   }
-  return console.log(`[Dev Launcher] Launching Storybook for ${e.name}...`), oe(e, e.timeoutMs ?? 120 * 1e3);
+  return console.log(`[Dev Launcher] Launching Storybook for ${e.name}...`), ne(e, e.timeoutMs ?? 120 * 1e3);
 }
-const N = D(M(import.meta.url));
-function se(e) {
+const N = j(U(import.meta.url));
+function ie(e) {
   const t = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
   console.log(`[Dev Launcher] Auto-launching browser: ${e}`), _(t, [e], { shell: process.platform === "win32" }).on(
     "error",
@@ -108,32 +108,32 @@ function se(e) {
     }
   );
 }
-async function ne(e, t, r = {}) {
-  const [o, s] = e.targets, [n, d] = t;
-  if (!(o != null && o.sourceOfTruth) || !s || s.sourceOfTruth || !n || !d)
+async function ae(e, t, r = {}) {
+  const [o, s] = e.targets, [n, l] = t;
+  if (!(o != null && o.sourceOfTruth) || !s || s.sourceOfTruth || !n || !l)
     throw new Error(
       "adapter-tester dev mode requires exactly two targets: [sourceOfTruth, target] — check adapter-tester.config.json."
     );
-  const h = r.port ?? 6010;
+  const f = r.port ?? 6010;
   console.log(
     `[Dev Launcher] Resolving ${o.name} and ${s.name} Storybooks...`
   );
   const [y, w] = await Promise.all([
-    E(
-      x(o.name, n)
+    A(
+      E(o.name, n)
     ),
-    E(x(s.name, d))
+    A(E(s.name, l))
   ]);
   console.log("[Dev Launcher] Both Storybooks are active and responsive!");
   const i = [y.process, w.process].filter(
-    (f) => f !== null
-  ), u = W(), l = a(N, "../public"), v = a(N, "../report-header.txt");
-  u.get("/", (f, T, b) => {
-    if (f.query.path) {
-      b();
+    (m) => m !== null
+  ), u = K(), p = a(N, "../public"), v = a(N, "../report-header.txt");
+  u.get("/", (m, b, T) => {
+    if (m.query.path) {
+      T();
       return;
     }
-    const J = S(a(l, "index.html"), "utf8").replace(
+    const q = S(a(p, "index.html"), "utf8").replace(
       "<head>",
       `<head>
   <script>window.__ADAPTER_TESTER__ = ${JSON.stringify({
@@ -142,55 +142,59 @@ async function ne(e, t, r = {}) {
         sourceOfTruthPort: y.port
       })};<\/script>`
     );
-    T.send(J);
-  }), u.get("/report-header.txt", (f, T) => {
+    b.send(q);
+  }), u.get("/report-header.txt", (m, b) => {
+    if (e.reportHeader !== void 0) {
+      b.type("text/plain").send(e.reportHeader);
+      return;
+    }
     try {
-      T.type("text/plain").send(S(v, "utf8"));
+      b.type("text/plain").send(S(v, "utf8"));
     } catch {
-      T.status(500).send("Error loading report-header.txt");
+      b.status(500).send("Error loading report-header.txt");
     }
   }), u.use(
     "/",
-    B({
+    X({
       target: w.url,
       changeOrigin: !0,
       ws: !0
     })
   );
   let c = !1;
-  const p = () => {
+  const h = () => {
     if (!c) {
       c = !0, console.log(
         `
 [Dev Launcher] Shutting down Dev Mode server and spawned Storybooks...`
       );
-      for (const f of i) f.kill("SIGINT");
+      for (const m of i) m.kill("SIGINT");
       process.exit(0);
     }
   };
-  process.on("SIGINT", p), process.on("SIGTERM", p), u.listen(h, () => {
+  process.on("SIGINT", h), process.on("SIGTERM", h), u.listen(f, () => {
     console.log(`
 ====================================================
 🚀 Adapter Dev Mode proxy running at:
-   http://localhost:${h}
+   http://localhost:${f}
 ====================================================
-`), se(`http://localhost:${h}`);
+`), ie(`http://localhost:${f}`);
   });
 }
-const ie = "http://json-schema.org/draft-07/schema#", ae = "https://github.com/borderux/recursica/tree/main/packages/adapter-tester/src/adapter-tester.schema.json", ce = "adapter-tester.config.json", ue = "Configuration for @recursica/adapter-tester. All fields are optional — an adapter repo with a normal `storybook` npm script needs no config file at all.", de = "object", le = !1, pe = { $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/mantine-adapter 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/mantine-adapter 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`." } } }, { 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 (mantine-adapter). 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`." }, 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`)." } }, he = {
-  $schema: ie,
-  $id: ae,
-  title: ce,
-  description: ue,
-  type: de,
-  additionalProperties: le,
-  properties: pe
-}, fe = z, U = new Y.Ajv({ allErrors: !0, strict: !0 });
-fe(U);
-const $ = U.compile(he);
-function me(e, t) {
-  if ($(e)) return;
-  const r = ($.errors ?? []).map((o) => {
+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", le = "Configuration for @recursica/adapter-tester. All fields are optional — an adapter repo with a normal `storybook` npm script needs no config file at all.", pe = "object", he = !1, fe = { $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/mantine-adapter 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/mantine-adapter 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`." } } }, { 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 (mantine-adapter). 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`." }, 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`.' } }, me = {
+  $schema: ce,
+  $id: de,
+  title: ue,
+  description: le,
+  type: pe,
+  additionalProperties: he,
+  properties: fe
+}, ge = Z, G = new Q.Ajv({ allErrors: !0, strict: !0 });
+ge(G);
+const L = G.compile(me);
+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}`;
@@ -199,57 +203,58 @@ function me(e, t) {
   throw new Error(`Invalid ${t}:
 ${r}`);
 }
-const ge = "@recursica/mantine-adapter", ye = "adapter-tester.config.json", L = "npm run storybook", we = 6006, C = 6011, R = "Mantine", ve = 10, Te = 3500;
-function G(e) {
+const we = "@recursica/mantine-adapter", ve = "adapter-tester.config.json", F = "npm run storybook", be = 6006, R = 6011, C = "Mantine", Te = 10, Se = 3500;
+function V(e) {
   const t = a(e, "package.json");
-  if (!I(t))
+  if (!M(t))
     throw new Error(
       `No package.json found in ${e} — run adapter-tester from the root of the project being tested.`
     );
   return JSON.parse(S(t, "utf8"));
 }
-function be(e) {
+function ke(e) {
   var s;
-  const r = (s = G(e).scripts) == null ? void 0 : s.storybook, o = r == null ? void 0 : r.match(/(?:-p|--port)[ =](\d+)/);
-  return o ? Number(o[1]) : we;
+  const r = (s = V(e).scripts) == null ? void 0 : s.storybook, o = r == null ? void 0 : r.match(/(?:-p|--port)[ =](\d+)/);
+  return o ? Number(o[1]) : be;
 }
-function Se(e) {
-  const r = G(e).name;
+function Oe(e) {
+  const r = V(e).name;
   return r ? r.split("/").pop() : "Adapter";
 }
-function ke(e) {
-  const t = a(e, ye);
-  if (!I(t))
+function xe(e) {
+  const t = a(e, ve);
+  if (!M(t))
     return {};
   const r = JSON.parse(S(t, "utf8"));
-  return me(r, t), r;
+  return ye(r, t), r;
 }
-function Oe(e, t = {}) {
-  var p, f, T;
-  const r = ke(e), o = r.isSourceOfTruthAdapter ?? !1;
+function Ee(e, t = {}) {
+  var h, m, b;
+  const r = xe(e), o = r.isSourceOfTruthAdapter ?? !1;
   if (t.mantineAdapterVersion && o)
     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 ?? Se(e), n = ((p = r.storybook) == null ? void 0 : p.port) ?? be(e), d = ((f = r.storybook) == null ? void 0 : f.command) ?? L, h = j(e, ((T = r.storybook) == null ? void 0 : T.cwd) ?? "."), y = {
-    command: d,
+  const s = r.name ?? Oe(e), n = ((h = r.storybook) == null ? void 0 : h.port) ?? ke(e), l = ((m = r.storybook) == null ? void 0 : m.command) ?? F, f = $(e, ((b = r.storybook) == null ? void 0 : b.cwd) ?? "."), y = {
+    command: l,
     port: n,
-    cwd: h,
+    cwd: f,
     reuseExistingServer: !process.env.CI,
     cacheFile: a(e, ".adapter-tester", "last-port-own.json"),
     timeout: 120 * 1e3
   }, w = {
-    goldenThresholdPixels: r.goldenThresholdPixels ?? ve,
-    sourceOfTruthThresholdPixels: r.sourceOfTruthThresholdPixels ?? Te,
+    goldenThresholdPixels: r.goldenThresholdPixels ?? Te,
+    sourceOfTruthThresholdPixels: r.sourceOfTruthThresholdPixels ?? Se,
     stories: r.stories,
     excludeTitlePrefixes: r.excludeTitlePrefixes,
+    reportHeader: r.reportHeader,
     // Keyed off `ownCwd`, not `cwd` — the project actually being tested, not
     // wherever the config file happens to live. Matters whenever
     // `storybook.cwd` points at a sibling package: its goldens must resolve
     // 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(h, "test", "golden"),
+    goldenDir: a(f, "test", "golden"),
     isSourceOfTruthAdapter: o,
     // Overwritten by the CLI from --update-golden/--approve-divergence.
     goldenMode: "check",
@@ -267,37 +272,37 @@ function Oe(e, t = {}) {
   const i = r.sourceOfTruth ?? {
     type: "mantine-harness"
   };
-  let u, l, v, c;
+  let u, p, v, c;
   if (i.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 ?? R, l = i.port ?? C;
-    const b = j(e, i.cwd ?? ".");
+    u = i.name ?? C, p = i.port ?? R;
+    const T = $(e, i.cwd ?? ".");
     v = {
-      command: i.command ?? L,
-      port: l,
-      cwd: b,
+      command: i.command ?? F,
+      port: p,
+      cwd: T,
       reuseExistingServer: !process.env.CI,
       cacheFile: a(e, ".adapter-tester", "last-port-source-of-truth.json"),
       timeout: 120 * 1e3
     }, c = {
       type: "local",
-      dir: a(b, "test", "golden")
+      dir: a(T, "test", "golden")
     };
   } else {
-    u = R, l = i.port ?? C;
-    const b = t.mantineAdapterVersion ?? i.mantineAdapterVersion;
-    v = X({
+    u = C, p = i.port ?? R;
+    const T = t.mantineAdapterVersion ?? i.mantineAdapterVersion;
+    v = z({
       dir: a(e, ".adapter-tester/mantine-harness"),
-      port: l,
-      mantineAdapterVersion: b,
+      port: p,
+      mantineAdapterVersion: T,
       storybookTemplateVersion: i.storybookTemplateVersion
     }), c = {
       type: "npm",
-      packageName: ge,
-      versionSpec: b ?? "latest",
+      packageName: we,
+      versionSpec: T ?? "latest",
       cacheDir: a(e, ".adapter-tester/mantine-golden-cache")
     };
   }
@@ -307,7 +312,7 @@ function Oe(e, t = {}) {
       targets: [
         {
           name: u,
-          url: `http://localhost:${l}`,
+          url: `http://localhost:${p}`,
           sourceOfTruth: !0
         },
         { name: s, url: `http://localhost:${n}` }
@@ -320,66 +325,76 @@ function Oe(e, t = {}) {
     webServers: [v, y]
   };
 }
-const xe = D(M(import.meta.url)), Ee = H(a(xe, "testing.js")).href, g = process.argv.slice(2);
-let V;
-const k = g.indexOf("--source-of-truth-version");
+const Ae = j(U(import.meta.url)), De = B(a(Ae, "testing.js")).href, d = process.argv.slice(2);
+let H;
+const k = d.indexOf("--source-of-truth-version");
 if (k !== -1) {
-  const e = g[k + 1];
+  const e = d[k + 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"
     );
-  V = e, g.splice(k, 2);
+  H = e, d.splice(k, 2);
+}
+let J;
+const O = d.indexOf("--story");
+if (O !== -1) {
+  const e = d[O + 1];
+  if (e === void 0 || e.startsWith("--"))
+    throw new Error(
+      "--story requires a story id, e.g. --story ui-kit-button--loading"
+    );
+  J = e, d.splice(O, 2);
 }
-const A = process.cwd(), { engineConfig: m, webServers: P } = Oe(A, {
-  mantineAdapterVersion: V
+const D = process.cwd(), { engineConfig: g, webServers: P } = Ee(D, {
+  mantineAdapterVersion: H
 });
-g.includes("--update-golden") ? m.goldenMode = "update-golden" : g.includes("--approve-divergence") && (m.goldenMode = "approve-divergence");
-if (g.includes("--divergence-only")) {
-  if (m.isSourceOfTruthAdapter)
+d.includes("--update-golden") ? g.goldenMode = "update-golden" : d.includes("--approve-divergence") && (g.goldenMode = "approve-divergence");
+if (d.includes("--divergence-only")) {
+  if (g.isSourceOfTruthAdapter)
     throw new Error(
       "--divergence-only has nothing to diverge from — isSourceOfTruthAdapter is true in this project's adapter-tester.config.json."
     );
-  m.checkMode = "divergence";
-} else if (m.goldenMode === "approve-divergence")
+  g.checkMode = "divergence";
+} else if (g.goldenMode === "approve-divergence")
   throw new Error(
     "--approve-divergence only makes sense with --divergence-only — there's nothing to approve without the divergence check running."
   );
-g.includes("--dry-run") && (console.log(JSON.stringify({ engineConfig: m, webServers: P }, null, 2)), process.exit(0));
-const Ae = /* @__PURE__ */ new Set([
+d.includes("--dry-run") && (console.log(JSON.stringify({ engineConfig: g, webServers: P }, null, 2)), process.exit(0));
+const Pe = /* @__PURE__ */ new Set([
   "--dry-run",
   "--serve",
   "--update-golden",
   "--approve-divergence",
   "--divergence-only"
-]), Pe = g.filter((e) => !Ae.has(e));
-De().catch((e) => {
+]), je = d.filter((e) => !Pe.has(e));
+$e().catch((e) => {
   console.error(e), process.exitCode = 1;
 });
-async function De() {
-  if (g.includes("--serve")) {
-    if (m.isSourceOfTruthAdapter)
+async function $e() {
+  if (d.includes("--serve")) {
+    if (g.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 ne(m, P);
+    await ae(g, P);
   } else {
     const e = P.at(-1);
     if (!e)
       throw new Error("resolveConfig() returned no webServers to boot.");
-    await je(e, m);
+    await Ne(e, g);
   }
 }
-async function je(e, t) {
-  const r = a(A, ".adapter-tester/run");
-  F(r, { recursive: !0 });
+async function Ne(e, t) {
+  const r = a(D, ".adapter-tester/run");
+  I(r, { recursive: !0 });
   const o = t.targets.at(-1);
   if (!o)
     throw new Error("resolveConfig() returned no targets to check.");
-  const { url: s, process: n } = await E(
-    x(o.name, e)
+  const { url: s, process: n } = await A(
+    E(o.name, e)
   );
-  o.url = s, O(
+  o.url = s, x(
     a(r, "playwright.config.js"),
     `// Generated by \`adapter-tester\` — do not edit, regenerated on every run.
 import { defineConfig, devices } from "@playwright/test";
@@ -402,11 +417,11 @@ export default defineConfig({
   // the time this config is used (see runAutomated() in cli.ts).
 });
 `
-  ), O(
+  ), x(
     a(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(Ee)};
+import { resolveVisualRegressionPlan } from ${JSON.stringify(De)};
 
 // \`test.describe\`/\`test\` are called here, not inside resolveVisualRegressionPlan,
 // so Playwright's HTML report groups the suite under this file instead of a
@@ -414,8 +429,18 @@ import { resolveVisualRegressionPlan } from ${JSON.stringify(Ee)};
 const { ownTargetName, suiteLabel, stories, missingFromSourceOfTruth, checkStory } =
   await resolveVisualRegressionPlan(${JSON.stringify(t, null, 2)});
 
+// 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(J ?? null)};
+const scopedStories = storyId
+  ? stories.filter((story) => story.id === storyId)
+  : stories;
+if (storyId && scopedStories.length === 0) {
+  throw new Error(\`--story "\${storyId}" matched no story in this Storybook.\`);
+}
+
 test.describe(\`\${ownTargetName} — \${suiteLabel}\`, () => {
-  if (missingFromSourceOfTruth.length > 0) {
+  if (!storyId && missingFromSourceOfTruth.length > 0) {
     test("story parity with source of truth", () => {
       expect(
         missingFromSourceOfTruth,
@@ -423,7 +448,7 @@ test.describe(\`\${ownTargetName} — \${suiteLabel}\`, () => {
       ).toEqual([]);
     });
   }
-  for (const story of stories) {
+  for (const story of scopedStories) {
     test(story.id, async ({ browser }, testInfo) => {
       await checkStory(story, browser, testInfo);
     });
@@ -432,18 +457,18 @@ test.describe(\`\${ownTargetName} — \${suiteLabel}\`, () => {
 `
   );
   try {
-    const d = q(
+    const l = W(
       "npx",
       [
         "playwright",
         "test",
         "--config",
         a(r, "playwright.config.js"),
-        ...Pe
+        ...je
       ],
-      { stdio: "inherit", cwd: A, shell: process.platform === "win32" }
+      { stdio: "inherit", cwd: D, shell: process.platform === "win32" }
     );
-    process.exitCode = d.status ?? 1;
+    process.exitCode = l.status ?? 1;
   } finally {
     n == null || n.kill("SIGTERM");
   }