uidex 0.6.0 → 0.8.0

package/dist/playwright/states-reporter.cjs

@@ -0,0 +1,123 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/integrations/playwright/states-reporter.ts
+var states_reporter_exports = {};
+__export(states_reporter_exports, {
+  aggregateStates: () => aggregateStates,
+  default: () => UidexStatesReporter
+});
+module.exports = __toCommonJS(states_reporter_exports);
+var fs = __toESM(require("fs"), 1);
+var path = __toESM(require("path"), 1);
+
+// src/integrations/playwright/states.ts
+var STATES_ATTACHMENT = "uidex-states";
+
+// src/integrations/playwright/states-reporter.ts
+function keyOf(r) {
+  return JSON.stringify([
+    r.kind ?? null,
+    r.entity,
+    r.state,
+    r.route ?? null,
+    r.url ?? null,
+    r.stateKind ?? null
+  ]);
+}
+function aggregateStates(variants) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const v of variants) {
+    const k = keyOf(v);
+    if (seen.has(k)) continue;
+    seen.set(k, {
+      entity: v.entity,
+      state: v.state,
+      ...v.kind ? { kind: v.kind } : {},
+      ...v.stateKind ? { stateKind: v.stateKind } : {},
+      ...v.route ? { route: v.route } : {},
+      ...v.url ? { url: v.url } : {}
+    });
+  }
+  const captured = [...seen.values()].sort(
+    (a, b) => a.entity.localeCompare(b.entity) || a.state.localeCompare(b.state)
+  );
+  const sortedVariants = [...variants].sort(
+    (a, b) => a.entity.localeCompare(b.entity) || a.state.localeCompare(b.state) || (a.theme ?? "").localeCompare(b.theme ?? "") || (a.width ?? "").localeCompare(b.width ?? "")
+  );
+  return { captured, variants: sortedVariants };
+}
+function parsePayload(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || !Array.isArray(parsed.records)) return [];
+    return parsed.records.filter(
+      (r) => !!r && typeof r.entity === "string" && typeof r.state === "string"
+    );
+  } catch {
+    return [];
+  }
+}
+var UidexStatesReporter = class {
+  outputPath;
+  silent;
+  variants = [];
+  constructor(options = {}) {
+    this.outputPath = options.outputPath ?? "uidex-states.json";
+    this.silent = options.silent ?? false;
+  }
+  onTestEnd(_test, result) {
+    for (const attachment of result.attachments) {
+      if (attachment.name !== STATES_ATTACHMENT) continue;
+      if (!attachment.body) continue;
+      this.variants.push(...parsePayload(attachment.body.toString()));
+    }
+  }
+  async onEnd(_result) {
+    const manifest = aggregateStates(this.variants);
+    fs.mkdirSync(path.dirname(path.resolve(this.outputPath)), {
+      recursive: true
+    });
+    fs.writeFileSync(
+      path.resolve(this.outputPath),
+      JSON.stringify(manifest, null, 2) + "\n"
+    );
+    if (!this.silent) {
+      const entities = new Set(manifest.captured.map((c) => c.entity)).size;
+      console.log(
+        `uidex states: captured ${manifest.captured.length} state(s) across ${entities} entit${entities === 1 ? "y" : "ies"} (${manifest.variants.length} variants) \u2192 ${this.outputPath}`
+      );
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  aggregateStates
+});
+//# sourceMappingURL=states-reporter.cjs.map

package/dist/playwright/states-reporter.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/integrations/playwright/states-reporter.ts","../../src/integrations/playwright/states.ts"],"sourcesContent":["import * as fs from \"node:fs\"\nimport * as path from \"node:path\"\nimport type {\n  FullResult,\n  Reporter,\n  TestCase,\n  TestResult,\n} from \"@playwright/test/reporter\"\nimport {\n  STATES_ATTACHMENT,\n  type StateRecord,\n  type StatesPayload,\n} from \"./states\"\n\n/**\n * Aggregates `uidex-states` attachments across a run into `uidex-states.json` —\n * the manifest the scanner's state-capture completeness gate reads. The shape\n * matches the scanner's `CapturedStatesManifest` structurally (kept decoupled:\n * no cross-subpath import, so the playwright bundle stays free of scan code).\n *\n * Variants collapse: many theme × width shots of one `entity/state` become a\n * single captured entry, because the gate asks \"was this state produced at\n * all?\", not \"how many variants?\".\n */\n\nexport interface CapturedStateEntry {\n  entity: string\n  kind?: string\n  state: string\n  /** Canonical matrix kind (loading/empty/populated/error/variant). */\n  stateKind?: string\n  /** Observed URL pathname (first variant); the page-coverage gate matches it. */\n  url?: string\n  /** Explicit route pattern, when the capture supplied one. */\n  route?: string\n}\n\nexport interface CapturedStatesManifestOut {\n  captured: CapturedStateEntry[]\n  /** Every distinct theme/width/path variant, for tooling that wants detail. */\n  variants: StateRecord[]\n}\n\nexport interface UidexStatesReporterOptions {\n  outputPath?: string\n  silent?: boolean\n}\n\nfunction keyOf(r: StateRecord): string {\n  // Collapses pure theme/width variants, but keeps distinct routes/urls/kinds\n  // so a state captured on two routes (or with vs. without stateKind) is not lost.\n  return JSON.stringify([\n    r.kind ?? null,\n    r.entity,\n    r.state,\n    r.route ?? null,\n    r.url ?? null,\n    r.stateKind ?? null,\n  ])\n}\n\n/** Pure aggregation — the reporter's core, exported for tests. */\nexport function aggregateStates(\n  variants: StateRecord[]\n): CapturedStatesManifestOut {\n  const seen = new Map<string, CapturedStateEntry>()\n  for (const v of variants) {\n    const k = keyOf(v)\n    if (seen.has(k)) continue\n    seen.set(k, {\n      entity: v.entity,\n      state: v.state,\n      ...(v.kind ? { kind: v.kind } : {}),\n      ...(v.stateKind ? { stateKind: v.stateKind } : {}),\n      ...(v.route ? { route: v.route } : {}),\n      ...(v.url ? { url: v.url } : {}),\n    })\n  }\n  const captured = [...seen.values()].sort(\n    (a, b) => a.entity.localeCompare(b.entity) || a.state.localeCompare(b.state)\n  )\n  const sortedVariants = [...variants].sort(\n    (a, b) =>\n      a.entity.localeCompare(b.entity) ||\n      a.state.localeCompare(b.state) ||\n      (a.theme ?? \"\").localeCompare(b.theme ?? \"\") ||\n      (a.width ?? \"\").localeCompare(b.width ?? \"\")\n  )\n  return { captured, variants: sortedVariants }\n}\n\nfunction parsePayload(raw: string): StateRecord[] {\n  try {\n    const parsed = JSON.parse(raw) as Partial<StatesPayload>\n    if (!parsed || !Array.isArray(parsed.records)) return []\n    return parsed.records.filter(\n      (r): r is StateRecord =>\n        !!r && typeof r.entity === \"string\" && typeof r.state === \"string\"\n    )\n  } catch {\n    return []\n  }\n}\n\nexport default class UidexStatesReporter implements Reporter {\n  private readonly outputPath: string\n  private readonly silent: boolean\n  private readonly variants: StateRecord[] = []\n\n  constructor(options: UidexStatesReporterOptions = {}) {\n    this.outputPath = options.outputPath ?? \"uidex-states.json\"\n    this.silent = options.silent ?? false\n  }\n\n  onTestEnd(_test: TestCase, result: TestResult): void {\n    for (const attachment of result.attachments) {\n      if (attachment.name !== STATES_ATTACHMENT) continue\n      if (!attachment.body) continue\n      this.variants.push(...parsePayload(attachment.body.toString()))\n    }\n  }\n\n  async onEnd(_result: FullResult): Promise<void> {\n    const manifest = aggregateStates(this.variants)\n    fs.mkdirSync(path.dirname(path.resolve(this.outputPath)), {\n      recursive: true,\n    })\n    fs.writeFileSync(\n      path.resolve(this.outputPath),\n      JSON.stringify(manifest, null, 2) + \"\\n\"\n    )\n    if (!this.silent) {\n      const entities = new Set(manifest.captured.map((c) => c.entity)).size\n      console.log(\n        `uidex states: captured ${manifest.captured.length} state(s) across ${entities} entit${entities === 1 ? \"y\" : \"ies\"} (${manifest.variants.length} variants) → ${this.outputPath}`\n      )\n    }\n  }\n}\n","import type { Page, TestInfo } from \"@playwright/test\"\n\n/**\n * Deterministic render-state capture for `uidex/playwright`.\n *\n * Two jobs, deliberately split:\n *   1. RECORD which `entity/state` a test captured (a `uidex-states`\n *      attachment) — the reporter aggregates these into `uidex-states.json`,\n *      which the scanner's completeness gate cross-checks against the states\n *      declared in `export const uidex = { states: [...] }`.\n *   2. SHOOT the pixels — a thin wrapper over native `page.screenshot`. The\n *      determinism knobs are Playwright's own: `animations: \"disabled\"` and\n *      `caret: \"hide\"` are defaults, `style`/`stylePath` pierces the shadow DOM\n *      to hide dev chrome, `mask` covers non-deterministic regions, and the\n *      frozen clock / locale / timezone / colour-scheme live in the project's\n *      `use` block. uidex does not re-implement `settle()`.\n *\n * The recording is the load-bearing half: even a spec that shoots nothing can\n * call `recordState` so the gate knows the state exists.\n */\n\nexport const STATES_ATTACHMENT = \"uidex-states\"\n\n/** Default light + dark; many surfaces use theme-dependent colours. */\nexport const THEMES = [\"light\", \"dark\"] as const\n/** Desktop is primary; narrow exercises the responsive reflow. */\nexport const WIDTHS = { desktop: 1440, narrow: 430 } as const\n\nexport type Theme = (typeof THEMES)[number]\nexport type WidthLabel = keyof typeof WIDTHS\nexport type StateEntityKind = \"page\" | \"feature\" | \"widget\"\n\n/** The four kinds the state-matrix gate expects every captured route to cover. */\nexport const CORE_STATE_KINDS = [\n  \"loading\",\n  \"empty\",\n  \"populated\",\n  \"error\",\n] as const\nexport type CoreStateKind = (typeof CORE_STATE_KINDS)[number]\n/** `variant` = any state outside the matrix (dialog, wizard step, multi-currency…). */\nexport type StateKind = CoreStateKind | \"variant\"\n\n/** One captured `entity/state` variant. */\nexport interface StateRecord {\n  /** Registry entity id whose state was rendered (e.g. \"products\"). */\n  entity: string\n  /** Entity kind, so the gate can disambiguate a page vs feature of the same id. */\n  kind?: StateEntityKind\n  /** Declared state name (e.g. \"new-filled\"). */\n  state: string\n  /** Canonical kind for the state-matrix axis (defaults inferred from the name). */\n  stateKind?: StateKind\n  theme?: string\n  width?: string\n  /** Screenshot path, when one was written. */\n  path?: string\n  /**\n   * The URL pathname the capture ran against, observed from `page.url()`. The\n   * page-coverage gate normalizes it to a derived route pattern — so which route\n   * a capture exercised is observed, never hand-declared. A `/shots/*` harness\n   * URL matches no real route and gates nothing (correct for component captures).\n   */\n  url?: string\n  /** Explicit route pattern override, when the observed URL can't be trusted. */\n  route?: string\n}\n\n/** The `uidex-states` attachment body — an array of records from one test. */\nexport interface StatesPayload {\n  records: StateRecord[]\n}\n\ntype TestInfoLike = Pick<TestInfo, \"attach\">\n\n/**\n * Attach one or more captured-state records to the test. Idempotent per call;\n * the reporter concatenates every test's records. Use directly when you shoot\n * with your own screenshot call and only need the state registered for the gate.\n */\nexport async function recordStates(\n  testInfo: TestInfoLike,\n  records: StateRecord[]\n): Promise<void> {\n  if (records.length === 0) return\n  const payload: StatesPayload = { records }\n  await testInfo.attach(STATES_ATTACHMENT, {\n    body: JSON.stringify(payload),\n    contentType: \"application/json\",\n  })\n}\n\nexport interface CaptureStateOptions {\n  /** Registry entity id whose state this is. */\n  entity: string\n  kind?: StateEntityKind\n  /** Declared state name (must match a name in the entity's `states`). */\n  state: string\n  /**\n   * Canonical state kind for the matrix. Defaults to the state name when it is\n   * itself a core kind (`loading`/`empty`/`populated`/`error`), else `variant`.\n   */\n  stateKind?: StateKind\n  /**\n   * Output dir for PNGs; defaults to `process.env.UIDEX_SHOTS_DIR`. When unset\n   * the capture only RECORDS the state (no screenshot) — so a spec left in the\n   * normal suite is a no-op beyond the attachment.\n   */\n  dir?: string\n  themes?: readonly Theme[]\n  widths?: readonly WidthLabel[]\n  /** Awaited after each theme/width change, before the shutter (the state's tell). */\n  ready?: (page: Page) => Promise<unknown>\n  /**\n   * Switch the app's theme. App-specific (next-themes uses localStorage + a\n   * reload; others a class or cookie), so it is injected. Defaults to\n   * Playwright's `emulateMedia({ colorScheme })`, which suits prefers-color-scheme.\n   */\n  setTheme?: (page: Page, theme: Theme) => Promise<void>\n  /** CSS selectors to mask (opaque box) — for legitimately non-deterministic regions. */\n  mask?: string[]\n  /** Path to a stylesheet injected before the shot (hide dev chrome; pierces shadow DOM). */\n  stylePath?: string\n  fullPage?: boolean\n  /**\n   * Explicit route pattern this capture covers (e.g. \"/[scope]/products\"). By\n   * default the observed `page.url()` pathname is recorded and the gate matches\n   * it; pass `route` only when the observed URL is unreliable (e.g. a `/shots`\n   * harness standing in for a real route).\n   */\n  route?: string\n}\n\n/** The URL pathname the page is currently on, for route observation. */\nfunction currentPathname(page: Page): string | undefined {\n  try {\n    return new URL(page.url()).pathname\n  } catch {\n    return undefined\n  }\n}\n\nasync function defaultSetTheme(page: Page, theme: Theme): Promise<void> {\n  await page.emulateMedia({ colorScheme: theme })\n}\n\n/** Infer the matrix kind: the state name if it is itself a core kind, else variant. */\nfunction inferStateKind(state: string, explicit?: StateKind): StateKind {\n  if (explicit) return explicit\n  return (CORE_STATE_KINDS as readonly string[]).includes(state)\n    ? (state as StateKind)\n    : \"variant\"\n}\n\nfunction shotName(\n  opts: CaptureStateOptions,\n  theme: Theme,\n  label: WidthLabel,\n  suffixWidth: boolean\n): string {\n  const base = `${opts.entity}/${opts.state}`\n  return suffixWidth ? `${base}-${theme}-${label}` : `${base}-${theme}`\n}\n\n/**\n * Capture one declared state across themes × widths, then record every variant\n * for the gate. Screenshot mechanics are native Playwright; determinism knobs\n * come from the project `use` block and the options above. Returns the records\n * it attached (also handy in tests).\n */\nexport async function captureState(\n  page: Page,\n  testInfo: TestInfoLike,\n  opts: CaptureStateOptions\n): Promise<StateRecord[]> {\n  const themes = opts.themes ?? THEMES\n  const widths = opts.widths ?? ([\"desktop\"] as WidthLabel[])\n  const suffixWidth = widths.length > 1\n  const dir = opts.dir ?? process.env.UIDEX_SHOTS_DIR\n  const setTheme = opts.setTheme ?? defaultSetTheme\n  const observedUrl = currentPathname(page)\n  const records: StateRecord[] = []\n\n  for (const theme of themes) {\n    await setTheme(page, theme)\n    if (opts.ready) await opts.ready(page)\n    for (const label of widths) {\n      await page.setViewportSize({ width: WIDTHS[label], height: 900 })\n      if (opts.ready) await opts.ready(page)\n      const record: StateRecord = {\n        entity: opts.entity,\n        state: opts.state,\n        stateKind: inferStateKind(opts.state, opts.stateKind),\n        theme,\n        width: label,\n        ...(opts.kind ? { kind: opts.kind } : {}),\n        ...(opts.route ? { route: opts.route } : {}),\n        ...(observedUrl ? { url: observedUrl } : {}),\n      }\n      if (dir) {\n        const path = `${dir}/${shotName(opts, theme, label, suffixWidth)}.png`\n        await page.screenshot({\n          path,\n          fullPage: opts.fullPage ?? true,\n          ...(opts.stylePath ? { stylePath: opts.stylePath } : {}),\n          ...(opts.mask?.length\n            ? {\n                mask: opts.mask.map((s) => page.locator(s)),\n                maskColor: \"#000000\",\n              }\n            : {}),\n        })\n        record.path = path\n      }\n      records.push(record)\n    }\n  }\n\n  await recordStates(testInfo, records)\n  return records\n}\n"],"mappings":"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","names":[]}

package/dist/playwright/states-reporter.d.cts

@@ -0,0 +1,46 @@
+import { Reporter, TestCase, TestResult, FullResult } from '@playwright/test/reporter';
+import { StateRecord } from './states.cjs';
+import '@playwright/test';
+
+/**
+ * Aggregates `uidex-states` attachments across a run into `uidex-states.json` —
+ * the manifest the scanner's state-capture completeness gate reads. The shape
+ * matches the scanner's `CapturedStatesManifest` structurally (kept decoupled:
+ * no cross-subpath import, so the playwright bundle stays free of scan code).
+ *
+ * Variants collapse: many theme × width shots of one `entity/state` become a
+ * single captured entry, because the gate asks "was this state produced at
+ * all?", not "how many variants?".
+ */
+interface CapturedStateEntry {
+    entity: string;
+    kind?: string;
+    state: string;
+    /** Canonical matrix kind (loading/empty/populated/error/variant). */
+    stateKind?: string;
+    /** Observed URL pathname (first variant); the page-coverage gate matches it. */
+    url?: string;
+    /** Explicit route pattern, when the capture supplied one. */
+    route?: string;
+}
+interface CapturedStatesManifestOut {
+    captured: CapturedStateEntry[];
+    /** Every distinct theme/width/path variant, for tooling that wants detail. */
+    variants: StateRecord[];
+}
+interface UidexStatesReporterOptions {
+    outputPath?: string;
+    silent?: boolean;
+}
+/** Pure aggregation — the reporter's core, exported for tests. */
+declare function aggregateStates(variants: StateRecord[]): CapturedStatesManifestOut;
+declare class UidexStatesReporter implements Reporter {
+    private readonly outputPath;
+    private readonly silent;
+    private readonly variants;
+    constructor(options?: UidexStatesReporterOptions);
+    onTestEnd(_test: TestCase, result: TestResult): void;
+    onEnd(_result: FullResult): Promise<void>;
+}
+
+export { type CapturedStateEntry, type CapturedStatesManifestOut, type UidexStatesReporterOptions, aggregateStates, UidexStatesReporter as default };

package/dist/playwright/states-reporter.d.ts

@@ -0,0 +1,46 @@
+import { Reporter, TestCase, TestResult, FullResult } from '@playwright/test/reporter';
+import { StateRecord } from './states.js';
+import '@playwright/test';
+
+/**
+ * Aggregates `uidex-states` attachments across a run into `uidex-states.json` —
+ * the manifest the scanner's state-capture completeness gate reads. The shape
+ * matches the scanner's `CapturedStatesManifest` structurally (kept decoupled:
+ * no cross-subpath import, so the playwright bundle stays free of scan code).
+ *
+ * Variants collapse: many theme × width shots of one `entity/state` become a
+ * single captured entry, because the gate asks "was this state produced at
+ * all?", not "how many variants?".
+ */
+interface CapturedStateEntry {
+    entity: string;
+    kind?: string;
+    state: string;
+    /** Canonical matrix kind (loading/empty/populated/error/variant). */
+    stateKind?: string;
+    /** Observed URL pathname (first variant); the page-coverage gate matches it. */
+    url?: string;
+    /** Explicit route pattern, when the capture supplied one. */
+    route?: string;
+}
+interface CapturedStatesManifestOut {
+    captured: CapturedStateEntry[];
+    /** Every distinct theme/width/path variant, for tooling that wants detail. */
+    variants: StateRecord[];
+}
+interface UidexStatesReporterOptions {
+    outputPath?: string;
+    silent?: boolean;
+}
+/** Pure aggregation — the reporter's core, exported for tests. */
+declare function aggregateStates(variants: StateRecord[]): CapturedStatesManifestOut;
+declare class UidexStatesReporter implements Reporter {
+    private readonly outputPath;
+    private readonly silent;
+    private readonly variants;
+    constructor(options?: UidexStatesReporterOptions);
+    onTestEnd(_test: TestCase, result: TestResult): void;
+    onEnd(_result: FullResult): Promise<void>;
+}
+
+export { type CapturedStateEntry, type CapturedStatesManifestOut, type UidexStatesReporterOptions, aggregateStates, UidexStatesReporter as default };

package/dist/playwright/states-reporter.js

@@ -0,0 +1,88 @@
+// src/integrations/playwright/states-reporter.ts
+import * as fs from "fs";
+import * as path from "path";
+
+// src/integrations/playwright/states.ts
+var STATES_ATTACHMENT = "uidex-states";
+
+// src/integrations/playwright/states-reporter.ts
+function keyOf(r) {
+  return JSON.stringify([
+    r.kind ?? null,
+    r.entity,
+    r.state,
+    r.route ?? null,
+    r.url ?? null,
+    r.stateKind ?? null
+  ]);
+}
+function aggregateStates(variants) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const v of variants) {
+    const k = keyOf(v);
+    if (seen.has(k)) continue;
+    seen.set(k, {
+      entity: v.entity,
+      state: v.state,
+      ...v.kind ? { kind: v.kind } : {},
+      ...v.stateKind ? { stateKind: v.stateKind } : {},
+      ...v.route ? { route: v.route } : {},
+      ...v.url ? { url: v.url } : {}
+    });
+  }
+  const captured = [...seen.values()].sort(
+    (a, b) => a.entity.localeCompare(b.entity) || a.state.localeCompare(b.state)
+  );
+  const sortedVariants = [...variants].sort(
+    (a, b) => a.entity.localeCompare(b.entity) || a.state.localeCompare(b.state) || (a.theme ?? "").localeCompare(b.theme ?? "") || (a.width ?? "").localeCompare(b.width ?? "")
+  );
+  return { captured, variants: sortedVariants };
+}
+function parsePayload(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || !Array.isArray(parsed.records)) return [];
+    return parsed.records.filter(
+      (r) => !!r && typeof r.entity === "string" && typeof r.state === "string"
+    );
+  } catch {
+    return [];
+  }
+}
+var UidexStatesReporter = class {
+  outputPath;
+  silent;
+  variants = [];
+  constructor(options = {}) {
+    this.outputPath = options.outputPath ?? "uidex-states.json";
+    this.silent = options.silent ?? false;
+  }
+  onTestEnd(_test, result) {
+    for (const attachment of result.attachments) {
+      if (attachment.name !== STATES_ATTACHMENT) continue;
+      if (!attachment.body) continue;
+      this.variants.push(...parsePayload(attachment.body.toString()));
+    }
+  }
+  async onEnd(_result) {
+    const manifest = aggregateStates(this.variants);
+    fs.mkdirSync(path.dirname(path.resolve(this.outputPath)), {
+      recursive: true
+    });
+    fs.writeFileSync(
+      path.resolve(this.outputPath),
+      JSON.stringify(manifest, null, 2) + "\n"
+    );
+    if (!this.silent) {
+      const entities = new Set(manifest.captured.map((c) => c.entity)).size;
+      console.log(
+        `uidex states: captured ${manifest.captured.length} state(s) across ${entities} entit${entities === 1 ? "y" : "ies"} (${manifest.variants.length} variants) \u2192 ${this.outputPath}`
+      );
+    }
+  }
+};
+export {
+  aggregateStates,
+  UidexStatesReporter as default
+};
+//# sourceMappingURL=states-reporter.js.map

package/dist/playwright/states-reporter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/integrations/playwright/states-reporter.ts","../../src/integrations/playwright/states.ts"],"sourcesContent":["import * as fs from \"node:fs\"\nimport * as path from \"node:path\"\nimport type {\n  FullResult,\n  Reporter,\n  TestCase,\n  TestResult,\n} from \"@playwright/test/reporter\"\nimport {\n  STATES_ATTACHMENT,\n  type StateRecord,\n  type StatesPayload,\n} from \"./states\"\n\n/**\n * Aggregates `uidex-states` attachments across a run into `uidex-states.json` —\n * the manifest the scanner's state-capture completeness gate reads. The shape\n * matches the scanner's `CapturedStatesManifest` structurally (kept decoupled:\n * no cross-subpath import, so the playwright bundle stays free of scan code).\n *\n * Variants collapse: many theme × width shots of one `entity/state` become a\n * single captured entry, because the gate asks \"was this state produced at\n * all?\", not \"how many variants?\".\n */\n\nexport interface CapturedStateEntry {\n  entity: string\n  kind?: string\n  state: string\n  /** Canonical matrix kind (loading/empty/populated/error/variant). */\n  stateKind?: string\n  /** Observed URL pathname (first variant); the page-coverage gate matches it. */\n  url?: string\n  /** Explicit route pattern, when the capture supplied one. */\n  route?: string\n}\n\nexport interface CapturedStatesManifestOut {\n  captured: CapturedStateEntry[]\n  /** Every distinct theme/width/path variant, for tooling that wants detail. */\n  variants: StateRecord[]\n}\n\nexport interface UidexStatesReporterOptions {\n  outputPath?: string\n  silent?: boolean\n}\n\nfunction keyOf(r: StateRecord): string {\n  // Collapses pure theme/width variants, but keeps distinct routes/urls/kinds\n  // so a state captured on two routes (or with vs. without stateKind) is not lost.\n  return JSON.stringify([\n    r.kind ?? null,\n    r.entity,\n    r.state,\n    r.route ?? null,\n    r.url ?? null,\n    r.stateKind ?? null,\n  ])\n}\n\n/** Pure aggregation — the reporter's core, exported for tests. */\nexport function aggregateStates(\n  variants: StateRecord[]\n): CapturedStatesManifestOut {\n  const seen = new Map<string, CapturedStateEntry>()\n  for (const v of variants) {\n    const k = keyOf(v)\n    if (seen.has(k)) continue\n    seen.set(k, {\n      entity: v.entity,\n      state: v.state,\n      ...(v.kind ? { kind: v.kind } : {}),\n      ...(v.stateKind ? { stateKind: v.stateKind } : {}),\n      ...(v.route ? { route: v.route } : {}),\n      ...(v.url ? { url: v.url } : {}),\n    })\n  }\n  const captured = [...seen.values()].sort(\n    (a, b) => a.entity.localeCompare(b.entity) || a.state.localeCompare(b.state)\n  )\n  const sortedVariants = [...variants].sort(\n    (a, b) =>\n      a.entity.localeCompare(b.entity) ||\n      a.state.localeCompare(b.state) ||\n      (a.theme ?? \"\").localeCompare(b.theme ?? \"\") ||\n      (a.width ?? \"\").localeCompare(b.width ?? \"\")\n  )\n  return { captured, variants: sortedVariants }\n}\n\nfunction parsePayload(raw: string): StateRecord[] {\n  try {\n    const parsed = JSON.parse(raw) as Partial<StatesPayload>\n    if (!parsed || !Array.isArray(parsed.records)) return []\n    return parsed.records.filter(\n      (r): r is StateRecord =>\n        !!r && typeof r.entity === \"string\" && typeof r.state === \"string\"\n    )\n  } catch {\n    return []\n  }\n}\n\nexport default class UidexStatesReporter implements Reporter {\n  private readonly outputPath: string\n  private readonly silent: boolean\n  private readonly variants: StateRecord[] = []\n\n  constructor(options: UidexStatesReporterOptions = {}) {\n    this.outputPath = options.outputPath ?? \"uidex-states.json\"\n    this.silent = options.silent ?? false\n  }\n\n  onTestEnd(_test: TestCase, result: TestResult): void {\n    for (const attachment of result.attachments) {\n      if (attachment.name !== STATES_ATTACHMENT) continue\n      if (!attachment.body) continue\n      this.variants.push(...parsePayload(attachment.body.toString()))\n    }\n  }\n\n  async onEnd(_result: FullResult): Promise<void> {\n    const manifest = aggregateStates(this.variants)\n    fs.mkdirSync(path.dirname(path.resolve(this.outputPath)), {\n      recursive: true,\n    })\n    fs.writeFileSync(\n      path.resolve(this.outputPath),\n      JSON.stringify(manifest, null, 2) + \"\\n\"\n    )\n    if (!this.silent) {\n      const entities = new Set(manifest.captured.map((c) => c.entity)).size\n      console.log(\n        `uidex states: captured ${manifest.captured.length} state(s) across ${entities} entit${entities === 1 ? \"y\" : \"ies\"} (${manifest.variants.length} variants) → ${this.outputPath}`\n      )\n    }\n  }\n}\n","import type { Page, TestInfo } from \"@playwright/test\"\n\n/**\n * Deterministic render-state capture for `uidex/playwright`.\n *\n * Two jobs, deliberately split:\n *   1. RECORD which `entity/state` a test captured (a `uidex-states`\n *      attachment) — the reporter aggregates these into `uidex-states.json`,\n *      which the scanner's completeness gate cross-checks against the states\n *      declared in `export const uidex = { states: [...] }`.\n *   2. SHOOT the pixels — a thin wrapper over native `page.screenshot`. The\n *      determinism knobs are Playwright's own: `animations: \"disabled\"` and\n *      `caret: \"hide\"` are defaults, `style`/`stylePath` pierces the shadow DOM\n *      to hide dev chrome, `mask` covers non-deterministic regions, and the\n *      frozen clock / locale / timezone / colour-scheme live in the project's\n *      `use` block. uidex does not re-implement `settle()`.\n *\n * The recording is the load-bearing half: even a spec that shoots nothing can\n * call `recordState` so the gate knows the state exists.\n */\n\nexport const STATES_ATTACHMENT = \"uidex-states\"\n\n/** Default light + dark; many surfaces use theme-dependent colours. */\nexport const THEMES = [\"light\", \"dark\"] as const\n/** Desktop is primary; narrow exercises the responsive reflow. */\nexport const WIDTHS = { desktop: 1440, narrow: 430 } as const\n\nexport type Theme = (typeof THEMES)[number]\nexport type WidthLabel = keyof typeof WIDTHS\nexport type StateEntityKind = \"page\" | \"feature\" | \"widget\"\n\n/** The four kinds the state-matrix gate expects every captured route to cover. */\nexport const CORE_STATE_KINDS = [\n  \"loading\",\n  \"empty\",\n  \"populated\",\n  \"error\",\n] as const\nexport type CoreStateKind = (typeof CORE_STATE_KINDS)[number]\n/** `variant` = any state outside the matrix (dialog, wizard step, multi-currency…). */\nexport type StateKind = CoreStateKind | \"variant\"\n\n/** One captured `entity/state` variant. */\nexport interface StateRecord {\n  /** Registry entity id whose state was rendered (e.g. \"products\"). */\n  entity: string\n  /** Entity kind, so the gate can disambiguate a page vs feature of the same id. */\n  kind?: StateEntityKind\n  /** Declared state name (e.g. \"new-filled\"). */\n  state: string\n  /** Canonical kind for the state-matrix axis (defaults inferred from the name). */\n  stateKind?: StateKind\n  theme?: string\n  width?: string\n  /** Screenshot path, when one was written. */\n  path?: string\n  /**\n   * The URL pathname the capture ran against, observed from `page.url()`. The\n   * page-coverage gate normalizes it to a derived route pattern — so which route\n   * a capture exercised is observed, never hand-declared. A `/shots/*` harness\n   * URL matches no real route and gates nothing (correct for component captures).\n   */\n  url?: string\n  /** Explicit route pattern override, when the observed URL can't be trusted. */\n  route?: string\n}\n\n/** The `uidex-states` attachment body — an array of records from one test. */\nexport interface StatesPayload {\n  records: StateRecord[]\n}\n\ntype TestInfoLike = Pick<TestInfo, \"attach\">\n\n/**\n * Attach one or more captured-state records to the test. Idempotent per call;\n * the reporter concatenates every test's records. Use directly when you shoot\n * with your own screenshot call and only need the state registered for the gate.\n */\nexport async function recordStates(\n  testInfo: TestInfoLike,\n  records: StateRecord[]\n): Promise<void> {\n  if (records.length === 0) return\n  const payload: StatesPayload = { records }\n  await testInfo.attach(STATES_ATTACHMENT, {\n    body: JSON.stringify(payload),\n    contentType: \"application/json\",\n  })\n}\n\nexport interface CaptureStateOptions {\n  /** Registry entity id whose state this is. */\n  entity: string\n  kind?: StateEntityKind\n  /** Declared state name (must match a name in the entity's `states`). */\n  state: string\n  /**\n   * Canonical state kind for the matrix. Defaults to the state name when it is\n   * itself a core kind (`loading`/`empty`/`populated`/`error`), else `variant`.\n   */\n  stateKind?: StateKind\n  /**\n   * Output dir for PNGs; defaults to `process.env.UIDEX_SHOTS_DIR`. When unset\n   * the capture only RECORDS the state (no screenshot) — so a spec left in the\n   * normal suite is a no-op beyond the attachment.\n   */\n  dir?: string\n  themes?: readonly Theme[]\n  widths?: readonly WidthLabel[]\n  /** Awaited after each theme/width change, before the shutter (the state's tell). */\n  ready?: (page: Page) => Promise<unknown>\n  /**\n   * Switch the app's theme. App-specific (next-themes uses localStorage + a\n   * reload; others a class or cookie), so it is injected. Defaults to\n   * Playwright's `emulateMedia({ colorScheme })`, which suits prefers-color-scheme.\n   */\n  setTheme?: (page: Page, theme: Theme) => Promise<void>\n  /** CSS selectors to mask (opaque box) — for legitimately non-deterministic regions. */\n  mask?: string[]\n  /** Path to a stylesheet injected before the shot (hide dev chrome; pierces shadow DOM). */\n  stylePath?: string\n  fullPage?: boolean\n  /**\n   * Explicit route pattern this capture covers (e.g. \"/[scope]/products\"). By\n   * default the observed `page.url()` pathname is recorded and the gate matches\n   * it; pass `route` only when the observed URL is unreliable (e.g. a `/shots`\n   * harness standing in for a real route).\n   */\n  route?: string\n}\n\n/** The URL pathname the page is currently on, for route observation. */\nfunction currentPathname(page: Page): string | undefined {\n  try {\n    return new URL(page.url()).pathname\n  } catch {\n    return undefined\n  }\n}\n\nasync function defaultSetTheme(page: Page, theme: Theme): Promise<void> {\n  await page.emulateMedia({ colorScheme: theme })\n}\n\n/** Infer the matrix kind: the state name if it is itself a core kind, else variant. */\nfunction inferStateKind(state: string, explicit?: StateKind): StateKind {\n  if (explicit) return explicit\n  return (CORE_STATE_KINDS as readonly string[]).includes(state)\n    ? (state as StateKind)\n    : \"variant\"\n}\n\nfunction shotName(\n  opts: CaptureStateOptions,\n  theme: Theme,\n  label: WidthLabel,\n  suffixWidth: boolean\n): string {\n  const base = `${opts.entity}/${opts.state}`\n  return suffixWidth ? `${base}-${theme}-${label}` : `${base}-${theme}`\n}\n\n/**\n * Capture one declared state across themes × widths, then record every variant\n * for the gate. Screenshot mechanics are native Playwright; determinism knobs\n * come from the project `use` block and the options above. Returns the records\n * it attached (also handy in tests).\n */\nexport async function captureState(\n  page: Page,\n  testInfo: TestInfoLike,\n  opts: CaptureStateOptions\n): Promise<StateRecord[]> {\n  const themes = opts.themes ?? THEMES\n  const widths = opts.widths ?? ([\"desktop\"] as WidthLabel[])\n  const suffixWidth = widths.length > 1\n  const dir = opts.dir ?? process.env.UIDEX_SHOTS_DIR\n  const setTheme = opts.setTheme ?? defaultSetTheme\n  const observedUrl = currentPathname(page)\n  const records: StateRecord[] = []\n\n  for (const theme of themes) {\n    await setTheme(page, theme)\n    if (opts.ready) await opts.ready(page)\n    for (const label of widths) {\n      await page.setViewportSize({ width: WIDTHS[label], height: 900 })\n      if (opts.ready) await opts.ready(page)\n      const record: StateRecord = {\n        entity: opts.entity,\n        state: opts.state,\n        stateKind: inferStateKind(opts.state, opts.stateKind),\n        theme,\n        width: label,\n        ...(opts.kind ? { kind: opts.kind } : {}),\n        ...(opts.route ? { route: opts.route } : {}),\n        ...(observedUrl ? { url: observedUrl } : {}),\n      }\n      if (dir) {\n        const path = `${dir}/${shotName(opts, theme, label, suffixWidth)}.png`\n        await page.screenshot({\n          path,\n          fullPage: opts.fullPage ?? true,\n          ...(opts.stylePath ? { stylePath: opts.stylePath } : {}),\n          ...(opts.mask?.length\n            ? {\n                mask: opts.mask.map((s) => page.locator(s)),\n                maskColor: \"#000000\",\n              }\n            : {}),\n        })\n        record.path = path\n      }\n      records.push(record)\n    }\n  }\n\n  await recordStates(testInfo, records)\n  return records\n}\n"],"mappings":";AAAA,YAAY,QAAQ;AACpB,YAAY,UAAU;;;ACoBf,IAAM,oBAAoB;;;AD2BjC,SAAS,MAAM,GAAwB;AAGrC,SAAO,KAAK,UAAU;AAAA,IACpB,EAAE,QAAQ;AAAA,IACV,EAAE;AAAA,IACF,EAAE;AAAA,IACF,EAAE,SAAS;AAAA,IACX,EAAE,OAAO;AAAA,IACT,EAAE,aAAa;AAAA,EACjB,CAAC;AACH;AAGO,SAAS,gBACd,UAC2B;AAC3B,QAAM,OAAO,oBAAI,IAAgC;AACjD,aAAW,KAAK,UAAU;AACxB,UAAM,IAAI,MAAM,CAAC;AACjB,QAAI,KAAK,IAAI,CAAC,EAAG;AACjB,SAAK,IAAI,GAAG;AAAA,MACV,QAAQ,EAAE;AAAA,MACV,OAAO,EAAE;AAAA,MACT,GAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;AAAA,MACjC,GAAI,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,IAAI,CAAC;AAAA,MAChD,GAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAAA,MACpC,GAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,IAAI,CAAC;AAAA,IAChC,CAAC;AAAA,EACH;AACA,QAAM,WAAW,CAAC,GAAG,KAAK,OAAO,CAAC,EAAE;AAAA,IAClC,CAAC,GAAG,MAAM,EAAE,OAAO,cAAc,EAAE,MAAM,KAAK,EAAE,MAAM,cAAc,EAAE,KAAK;AAAA,EAC7E;AACA,QAAM,iBAAiB,CAAC,GAAG,QAAQ,EAAE;AAAA,IACnC,CAAC,GAAG,MACF,EAAE,OAAO,cAAc,EAAE,MAAM,KAC/B,EAAE,MAAM,cAAc,EAAE,KAAK,MAC5B,EAAE,SAAS,IAAI,cAAc,EAAE,SAAS,EAAE,MAC1C,EAAE,SAAS,IAAI,cAAc,EAAE,SAAS,EAAE;AAAA,EAC/C;AACA,SAAO,EAAE,UAAU,UAAU,eAAe;AAC9C;AAEA,SAAS,aAAa,KAA4B;AAChD,MAAI;AACF,UAAM,SAAS,KAAK,MAAM,GAAG;AAC7B,QAAI,CAAC,UAAU,CAAC,MAAM,QAAQ,OAAO,OAAO,EAAG,QAAO,CAAC;AACvD,WAAO,OAAO,QAAQ;AAAA,MACpB,CAAC,MACC,CAAC,CAAC,KAAK,OAAO,EAAE,WAAW,YAAY,OAAO,EAAE,UAAU;AAAA,IAC9D;AAAA,EACF,QAAQ;AACN,WAAO,CAAC;AAAA,EACV;AACF;AAEA,IAAqB,sBAArB,MAA6D;AAAA,EAC1C;AAAA,EACA;AAAA,EACA,WAA0B,CAAC;AAAA,EAE5C,YAAY,UAAsC,CAAC,GAAG;AACpD,SAAK,aAAa,QAAQ,cAAc;AACxC,SAAK,SAAS,QAAQ,UAAU;AAAA,EAClC;AAAA,EAEA,UAAU,OAAiB,QAA0B;AACnD,eAAW,cAAc,OAAO,aAAa;AAC3C,UAAI,WAAW,SAAS,kBAAmB;AAC3C,UAAI,CAAC,WAAW,KAAM;AACtB,WAAK,SAAS,KAAK,GAAG,aAAa,WAAW,KAAK,SAAS,CAAC,CAAC;AAAA,IAChE;AAAA,EACF;AAAA,EAEA,MAAM,MAAM,SAAoC;AAC9C,UAAM,WAAW,gBAAgB,KAAK,QAAQ;AAC9C,IAAG,aAAe,aAAa,aAAQ,KAAK,UAAU,CAAC,GAAG;AAAA,MACxD,WAAW;AAAA,IACb,CAAC;AACD,IAAG;AAAA,MACI,aAAQ,KAAK,UAAU;AAAA,MAC5B,KAAK,UAAU,UAAU,MAAM,CAAC,IAAI;AAAA,IACtC;AACA,QAAI,CAAC,KAAK,QAAQ;AAChB,YAAM,WAAW,IAAI,IAAI,SAAS,SAAS,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE;AACjE,cAAQ;AAAA,QACN,0BAA0B,SAAS,SAAS,MAAM,oBAAoB,QAAQ,SAAS,aAAa,IAAI,MAAM,KAAK,KAAK,SAAS,SAAS,MAAM,qBAAgB,KAAK,UAAU;AAAA,MACjL;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/playwright/states.cjs

@@ -0,0 +1,118 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/integrations/playwright/states.ts
+var states_exports = {};
+__export(states_exports, {
+  CORE_STATE_KINDS: () => CORE_STATE_KINDS,
+  STATES_ATTACHMENT: () => STATES_ATTACHMENT,
+  THEMES: () => THEMES,
+  WIDTHS: () => WIDTHS,
+  captureState: () => captureState,
+  recordStates: () => recordStates
+});
+module.exports = __toCommonJS(states_exports);
+var STATES_ATTACHMENT = "uidex-states";
+var THEMES = ["light", "dark"];
+var WIDTHS = { desktop: 1440, narrow: 430 };
+var CORE_STATE_KINDS = [
+  "loading",
+  "empty",
+  "populated",
+  "error"
+];
+async function recordStates(testInfo, records) {
+  if (records.length === 0) return;
+  const payload = { records };
+  await testInfo.attach(STATES_ATTACHMENT, {
+    body: JSON.stringify(payload),
+    contentType: "application/json"
+  });
+}
+function currentPathname(page) {
+  try {
+    return new URL(page.url()).pathname;
+  } catch {
+    return void 0;
+  }
+}
+async function defaultSetTheme(page, theme) {
+  await page.emulateMedia({ colorScheme: theme });
+}
+function inferStateKind(state, explicit) {
+  if (explicit) return explicit;
+  return CORE_STATE_KINDS.includes(state) ? state : "variant";
+}
+function shotName(opts, theme, label, suffixWidth) {
+  const base = `${opts.entity}/${opts.state}`;
+  return suffixWidth ? `${base}-${theme}-${label}` : `${base}-${theme}`;
+}
+async function captureState(page, testInfo, opts) {
+  const themes = opts.themes ?? THEMES;
+  const widths = opts.widths ?? ["desktop"];
+  const suffixWidth = widths.length > 1;
+  const dir = opts.dir ?? process.env.UIDEX_SHOTS_DIR;
+  const setTheme = opts.setTheme ?? defaultSetTheme;
+  const observedUrl = currentPathname(page);
+  const records = [];
+  for (const theme of themes) {
+    await setTheme(page, theme);
+    if (opts.ready) await opts.ready(page);
+    for (const label of widths) {
+      await page.setViewportSize({ width: WIDTHS[label], height: 900 });
+      if (opts.ready) await opts.ready(page);
+      const record = {
+        entity: opts.entity,
+        state: opts.state,
+        stateKind: inferStateKind(opts.state, opts.stateKind),
+        theme,
+        width: label,
+        ...opts.kind ? { kind: opts.kind } : {},
+        ...opts.route ? { route: opts.route } : {},
+        ...observedUrl ? { url: observedUrl } : {}
+      };
+      if (dir) {
+        const path = `${dir}/${shotName(opts, theme, label, suffixWidth)}.png`;
+        await page.screenshot({
+          path,
+          fullPage: opts.fullPage ?? true,
+          ...opts.stylePath ? { stylePath: opts.stylePath } : {},
+          ...opts.mask?.length ? {
+            mask: opts.mask.map((s) => page.locator(s)),
+            maskColor: "#000000"
+          } : {}
+        });
+        record.path = path;
+      }
+      records.push(record);
+    }
+  }
+  await recordStates(testInfo, records);
+  return records;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CORE_STATE_KINDS,
+  STATES_ATTACHMENT,
+  THEMES,
+  WIDTHS,
+  captureState,
+  recordStates
+});
+//# sourceMappingURL=states.cjs.map

package/dist/playwright/states.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/integrations/playwright/states.ts"],"sourcesContent":["import type { Page, TestInfo } from \"@playwright/test\"\n\n/**\n * Deterministic render-state capture for `uidex/playwright`.\n *\n * Two jobs, deliberately split:\n *   1. RECORD which `entity/state` a test captured (a `uidex-states`\n *      attachment) — the reporter aggregates these into `uidex-states.json`,\n *      which the scanner's completeness gate cross-checks against the states\n *      declared in `export const uidex = { states: [...] }`.\n *   2. SHOOT the pixels — a thin wrapper over native `page.screenshot`. The\n *      determinism knobs are Playwright's own: `animations: \"disabled\"` and\n *      `caret: \"hide\"` are defaults, `style`/`stylePath` pierces the shadow DOM\n *      to hide dev chrome, `mask` covers non-deterministic regions, and the\n *      frozen clock / locale / timezone / colour-scheme live in the project's\n *      `use` block. uidex does not re-implement `settle()`.\n *\n * The recording is the load-bearing half: even a spec that shoots nothing can\n * call `recordState` so the gate knows the state exists.\n */\n\nexport const STATES_ATTACHMENT = \"uidex-states\"\n\n/** Default light + dark; many surfaces use theme-dependent colours. */\nexport const THEMES = [\"light\", \"dark\"] as const\n/** Desktop is primary; narrow exercises the responsive reflow. */\nexport const WIDTHS = { desktop: 1440, narrow: 430 } as const\n\nexport type Theme = (typeof THEMES)[number]\nexport type WidthLabel = keyof typeof WIDTHS\nexport type StateEntityKind = \"page\" | \"feature\" | \"widget\"\n\n/** The four kinds the state-matrix gate expects every captured route to cover. */\nexport const CORE_STATE_KINDS = [\n  \"loading\",\n  \"empty\",\n  \"populated\",\n  \"error\",\n] as const\nexport type CoreStateKind = (typeof CORE_STATE_KINDS)[number]\n/** `variant` = any state outside the matrix (dialog, wizard step, multi-currency…). */\nexport type StateKind = CoreStateKind | \"variant\"\n\n/** One captured `entity/state` variant. */\nexport interface StateRecord {\n  /** Registry entity id whose state was rendered (e.g. \"products\"). */\n  entity: string\n  /** Entity kind, so the gate can disambiguate a page vs feature of the same id. */\n  kind?: StateEntityKind\n  /** Declared state name (e.g. \"new-filled\"). */\n  state: string\n  /** Canonical kind for the state-matrix axis (defaults inferred from the name). */\n  stateKind?: StateKind\n  theme?: string\n  width?: string\n  /** Screenshot path, when one was written. */\n  path?: string\n  /**\n   * The URL pathname the capture ran against, observed from `page.url()`. The\n   * page-coverage gate normalizes it to a derived route pattern — so which route\n   * a capture exercised is observed, never hand-declared. A `/shots/*` harness\n   * URL matches no real route and gates nothing (correct for component captures).\n   */\n  url?: string\n  /** Explicit route pattern override, when the observed URL can't be trusted. */\n  route?: string\n}\n\n/** The `uidex-states` attachment body — an array of records from one test. */\nexport interface StatesPayload {\n  records: StateRecord[]\n}\n\ntype TestInfoLike = Pick<TestInfo, \"attach\">\n\n/**\n * Attach one or more captured-state records to the test. Idempotent per call;\n * the reporter concatenates every test's records. Use directly when you shoot\n * with your own screenshot call and only need the state registered for the gate.\n */\nexport async function recordStates(\n  testInfo: TestInfoLike,\n  records: StateRecord[]\n): Promise<void> {\n  if (records.length === 0) return\n  const payload: StatesPayload = { records }\n  await testInfo.attach(STATES_ATTACHMENT, {\n    body: JSON.stringify(payload),\n    contentType: \"application/json\",\n  })\n}\n\nexport interface CaptureStateOptions {\n  /** Registry entity id whose state this is. */\n  entity: string\n  kind?: StateEntityKind\n  /** Declared state name (must match a name in the entity's `states`). */\n  state: string\n  /**\n   * Canonical state kind for the matrix. Defaults to the state name when it is\n   * itself a core kind (`loading`/`empty`/`populated`/`error`), else `variant`.\n   */\n  stateKind?: StateKind\n  /**\n   * Output dir for PNGs; defaults to `process.env.UIDEX_SHOTS_DIR`. When unset\n   * the capture only RECORDS the state (no screenshot) — so a spec left in the\n   * normal suite is a no-op beyond the attachment.\n   */\n  dir?: string\n  themes?: readonly Theme[]\n  widths?: readonly WidthLabel[]\n  /** Awaited after each theme/width change, before the shutter (the state's tell). */\n  ready?: (page: Page) => Promise<unknown>\n  /**\n   * Switch the app's theme. App-specific (next-themes uses localStorage + a\n   * reload; others a class or cookie), so it is injected. Defaults to\n   * Playwright's `emulateMedia({ colorScheme })`, which suits prefers-color-scheme.\n   */\n  setTheme?: (page: Page, theme: Theme) => Promise<void>\n  /** CSS selectors to mask (opaque box) — for legitimately non-deterministic regions. */\n  mask?: string[]\n  /** Path to a stylesheet injected before the shot (hide dev chrome; pierces shadow DOM). */\n  stylePath?: string\n  fullPage?: boolean\n  /**\n   * Explicit route pattern this capture covers (e.g. \"/[scope]/products\"). By\n   * default the observed `page.url()` pathname is recorded and the gate matches\n   * it; pass `route` only when the observed URL is unreliable (e.g. a `/shots`\n   * harness standing in for a real route).\n   */\n  route?: string\n}\n\n/** The URL pathname the page is currently on, for route observation. */\nfunction currentPathname(page: Page): string | undefined {\n  try {\n    return new URL(page.url()).pathname\n  } catch {\n    return undefined\n  }\n}\n\nasync function defaultSetTheme(page: Page, theme: Theme): Promise<void> {\n  await page.emulateMedia({ colorScheme: theme })\n}\n\n/** Infer the matrix kind: the state name if it is itself a core kind, else variant. */\nfunction inferStateKind(state: string, explicit?: StateKind): StateKind {\n  if (explicit) return explicit\n  return (CORE_STATE_KINDS as readonly string[]).includes(state)\n    ? (state as StateKind)\n    : \"variant\"\n}\n\nfunction shotName(\n  opts: CaptureStateOptions,\n  theme: Theme,\n  label: WidthLabel,\n  suffixWidth: boolean\n): string {\n  const base = `${opts.entity}/${opts.state}`\n  return suffixWidth ? `${base}-${theme}-${label}` : `${base}-${theme}`\n}\n\n/**\n * Capture one declared state across themes × widths, then record every variant\n * for the gate. Screenshot mechanics are native Playwright; determinism knobs\n * come from the project `use` block and the options above. Returns the records\n * it attached (also handy in tests).\n */\nexport async function captureState(\n  page: Page,\n  testInfo: TestInfoLike,\n  opts: CaptureStateOptions\n): Promise<StateRecord[]> {\n  const themes = opts.themes ?? THEMES\n  const widths = opts.widths ?? ([\"desktop\"] as WidthLabel[])\n  const suffixWidth = widths.length > 1\n  const dir = opts.dir ?? process.env.UIDEX_SHOTS_DIR\n  const setTheme = opts.setTheme ?? defaultSetTheme\n  const observedUrl = currentPathname(page)\n  const records: StateRecord[] = []\n\n  for (const theme of themes) {\n    await setTheme(page, theme)\n    if (opts.ready) await opts.ready(page)\n    for (const label of widths) {\n      await page.setViewportSize({ width: WIDTHS[label], height: 900 })\n      if (opts.ready) await opts.ready(page)\n      const record: StateRecord = {\n        entity: opts.entity,\n        state: opts.state,\n        stateKind: inferStateKind(opts.state, opts.stateKind),\n        theme,\n        width: label,\n        ...(opts.kind ? { kind: opts.kind } : {}),\n        ...(opts.route ? { route: opts.route } : {}),\n        ...(observedUrl ? { url: observedUrl } : {}),\n      }\n      if (dir) {\n        const path = `${dir}/${shotName(opts, theme, label, suffixWidth)}.png`\n        await page.screenshot({\n          path,\n          fullPage: opts.fullPage ?? true,\n          ...(opts.stylePath ? { stylePath: opts.stylePath } : {}),\n          ...(opts.mask?.length\n            ? {\n                mask: opts.mask.map((s) => page.locator(s)),\n                maskColor: \"#000000\",\n              }\n            : {}),\n        })\n        record.path = path\n      }\n      records.push(record)\n    }\n  }\n\n  await recordStates(testInfo, records)\n  return records\n}\n"],"mappings":"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","names":[]}

package/dist/playwright/states.d.cts

@@ -0,0 +1,120 @@
+import { Page, TestInfo } from '@playwright/test';
+
+/**
+ * Deterministic render-state capture for `uidex/playwright`.
+ *
+ * Two jobs, deliberately split:
+ *   1. RECORD which `entity/state` a test captured (a `uidex-states`
+ *      attachment) — the reporter aggregates these into `uidex-states.json`,
+ *      which the scanner's completeness gate cross-checks against the states
+ *      declared in `export const uidex = { states: [...] }`.
+ *   2. SHOOT the pixels — a thin wrapper over native `page.screenshot`. The
+ *      determinism knobs are Playwright's own: `animations: "disabled"` and
+ *      `caret: "hide"` are defaults, `style`/`stylePath` pierces the shadow DOM
+ *      to hide dev chrome, `mask` covers non-deterministic regions, and the
+ *      frozen clock / locale / timezone / colour-scheme live in the project's
+ *      `use` block. uidex does not re-implement `settle()`.
+ *
+ * The recording is the load-bearing half: even a spec that shoots nothing can
+ * call `recordState` so the gate knows the state exists.
+ */
+declare const STATES_ATTACHMENT = "uidex-states";
+/** Default light + dark; many surfaces use theme-dependent colours. */
+declare const THEMES: readonly ["light", "dark"];
+/** Desktop is primary; narrow exercises the responsive reflow. */
+declare const WIDTHS: {
+    readonly desktop: 1440;
+    readonly narrow: 430;
+};
+type Theme = (typeof THEMES)[number];
+type WidthLabel = keyof typeof WIDTHS;
+type StateEntityKind = "page" | "feature" | "widget";
+/** The four kinds the state-matrix gate expects every captured route to cover. */
+declare const CORE_STATE_KINDS: readonly ["loading", "empty", "populated", "error"];
+type CoreStateKind = (typeof CORE_STATE_KINDS)[number];
+/** `variant` = any state outside the matrix (dialog, wizard step, multi-currency…). */
+type StateKind = CoreStateKind | "variant";
+/** One captured `entity/state` variant. */
+interface StateRecord {
+    /** Registry entity id whose state was rendered (e.g. "products"). */
+    entity: string;
+    /** Entity kind, so the gate can disambiguate a page vs feature of the same id. */
+    kind?: StateEntityKind;
+    /** Declared state name (e.g. "new-filled"). */
+    state: string;
+    /** Canonical kind for the state-matrix axis (defaults inferred from the name). */
+    stateKind?: StateKind;
+    theme?: string;
+    width?: string;
+    /** Screenshot path, when one was written. */
+    path?: string;
+    /**
+     * The URL pathname the capture ran against, observed from `page.url()`. The
+     * page-coverage gate normalizes it to a derived route pattern — so which route
+     * a capture exercised is observed, never hand-declared. A `/shots/*` harness
+     * URL matches no real route and gates nothing (correct for component captures).
+     */
+    url?: string;
+    /** Explicit route pattern override, when the observed URL can't be trusted. */
+    route?: string;
+}
+/** The `uidex-states` attachment body — an array of records from one test. */
+interface StatesPayload {
+    records: StateRecord[];
+}
+type TestInfoLike = Pick<TestInfo, "attach">;
+/**
+ * Attach one or more captured-state records to the test. Idempotent per call;
+ * the reporter concatenates every test's records. Use directly when you shoot
+ * with your own screenshot call and only need the state registered for the gate.
+ */
+declare function recordStates(testInfo: TestInfoLike, records: StateRecord[]): Promise<void>;
+interface CaptureStateOptions {
+    /** Registry entity id whose state this is. */
+    entity: string;
+    kind?: StateEntityKind;
+    /** Declared state name (must match a name in the entity's `states`). */
+    state: string;
+    /**
+     * Canonical state kind for the matrix. Defaults to the state name when it is
+     * itself a core kind (`loading`/`empty`/`populated`/`error`), else `variant`.
+     */
+    stateKind?: StateKind;
+    /**
+     * Output dir for PNGs; defaults to `process.env.UIDEX_SHOTS_DIR`. When unset
+     * the capture only RECORDS the state (no screenshot) — so a spec left in the
+     * normal suite is a no-op beyond the attachment.
+     */
+    dir?: string;
+    themes?: readonly Theme[];
+    widths?: readonly WidthLabel[];
+    /** Awaited after each theme/width change, before the shutter (the state's tell). */
+    ready?: (page: Page) => Promise<unknown>;
+    /**
+     * Switch the app's theme. App-specific (next-themes uses localStorage + a
+     * reload; others a class or cookie), so it is injected. Defaults to
+     * Playwright's `emulateMedia({ colorScheme })`, which suits prefers-color-scheme.
+     */
+    setTheme?: (page: Page, theme: Theme) => Promise<void>;
+    /** CSS selectors to mask (opaque box) — for legitimately non-deterministic regions. */
+    mask?: string[];
+    /** Path to a stylesheet injected before the shot (hide dev chrome; pierces shadow DOM). */
+    stylePath?: string;
+    fullPage?: boolean;
+    /**
+     * Explicit route pattern this capture covers (e.g. "/[scope]/products"). By
+     * default the observed `page.url()` pathname is recorded and the gate matches
+     * it; pass `route` only when the observed URL is unreliable (e.g. a `/shots`
+     * harness standing in for a real route).
+     */
+    route?: string;
+}
+/**
+ * Capture one declared state across themes × widths, then record every variant
+ * for the gate. Screenshot mechanics are native Playwright; determinism knobs
+ * come from the project `use` block and the options above. Returns the records
+ * it attached (also handy in tests).
+ */
+declare function captureState(page: Page, testInfo: TestInfoLike, opts: CaptureStateOptions): Promise<StateRecord[]>;
+
+export { CORE_STATE_KINDS, type CaptureStateOptions, type CoreStateKind, STATES_ATTACHMENT, type StateEntityKind, type StateKind, type StateRecord, type StatesPayload, THEMES, type Theme, WIDTHS, type WidthLabel, captureState, recordStates };