uidex 0.8.0 → 0.10.0

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

@@ -1 +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":[]}
+{"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   * ISO timestamp of the run that wrote this manifest. The scanner compares it\n   * to the mtimes of the files declaring states, so a manifest that predates a\n   * declaration edit is reported as stale rather than silently trusted.\n   */\n  generatedAt?: string\n}\n\nexport interface UidexStatesReporterOptions {\n  outputPath?: string\n  silent?: boolean\n  /**\n   * Write to `<outputPath>` even when the run captured FEWER states than the\n   * manifest already on disk. Off by default: a filtered (`--grep`) or flaky\n   * run legitimately produces a subset, and blindly overwriting turns that into\n   * silent coverage loss — the run exits non-zero, but the manifest is already\n   * gone. See the shrink guard in `onEnd`.\n   */\n  allowShrink?: boolean\n}\n\n/** Identity of a captured state for shrink comparison. */\nfunction capturedKey(c: CapturedStateEntry): string {\n  return `${c.kind ?? \"page\"}\u0000${c.entity}\u0000${c.state}`\n}\n\nfunction readExisting(p: string): CapturedStatesManifestOut | null {\n  try {\n    const parsed = JSON.parse(fs.readFileSync(p, \"utf8\")) as unknown\n    if (!parsed || typeof parsed !== \"object\") return null\n    const m = parsed as Partial<CapturedStatesManifestOut>\n    return Array.isArray(m.captured)\n      ? { captured: m.captured, variants: m.variants ?? [] }\n      : null\n  } catch {\n    return null // absent or unreadable → nothing to protect\n  }\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 allowShrink: 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    this.allowShrink = options.allowShrink ?? 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    manifest.generatedAt = new Date().toISOString()\n    const target = path.resolve(this.outputPath)\n    fs.mkdirSync(path.dirname(target), { recursive: true })\n\n    // ---- Shrink guard ----\n    // A filtered or flaky run captures a SUBSET. Writing it over the committed\n    // manifest silently deletes coverage: the states simply vanish, the gate\n    // then agrees nothing is missing, and the only signal is a state count you\n    // had to be watching. So when the run would drop states, divert it to\n    // `<name>.partial.json`, leave the committed manifest untouched, and name\n    // the dropped keys — the caller decides whether it was flake or a real\n    // removal (for a deliberate removal, copy the partial over, or re-run with\n    // `allowShrink`).\n    const existing = this.allowShrink ? null : readExisting(target)\n    const dropped = existing\n      ? (() => {\n          const now = new Set(manifest.captured.map(capturedKey))\n          return existing.captured\n            .map(capturedKey)\n            .filter((k) => !now.has(k))\n            .sort()\n        })()\n      : []\n\n    const shrunk = dropped.length > 0\n    const out = shrunk\n      ? target.replace(/\\.json$/i, \"\") + \".partial.json\"\n      : target\n    fs.writeFileSync(out, JSON.stringify(manifest, null, 2) + \"\\n\")\n\n    if (shrunk) {\n      console.error(\n        `uidex states: ⚠ run captured ${manifest.captured.length} state(s) but ${existing!.captured.length} are committed — ${dropped.length} would be DROPPED, so ${path.basename(target)} was left untouched and this run went to ${path.basename(out)}.`\n      )\n      console.error(`  dropped: ${dropped.join(\", \")}`)\n      console.error(\n        `  A consistent count across two runs is a genuinely broken spec; a varying one is flake. For a deliberate removal, copy the partial over or set allowShrink.`\n      )\n      return\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\n/**\n * The declared state space a generated `UidexStates` describes: entity kind →\n * entity id → that entity's own state names.\n */\nexport type StateSpace = {\n  [K in StateEntityKind]: Record<string, string> | never\n}\n\n/**\n * Capture options narrowed to ONE entity of one kind, with only the states that\n * entity actually declares. Built as a union over (kind, entity) pairs so the\n * three fields are checked together — picking `widget`/`gate-badge` restricts\n * `state` to gate-badge's own names, and a page id is not assignable at all.\n */\nexport type TypedCaptureOptions<M> = {\n  [K in keyof M & StateEntityKind]: M[K] extends Record<string, string>\n    ? {\n        [E in keyof M[K] & string]: Omit<\n          CaptureStateOptions,\n          \"entity\" | \"kind\" | \"state\"\n        > & { kind: K; entity: E; state: M[K][E] }\n      }[keyof M[K] & string]\n    : never\n}[keyof M & StateEntityKind]\n\nexport interface TypedStateCapture<M> {\n  captureState(\n    page: Page,\n    testInfo: TestInfoLike,\n    opts: TypedCaptureOptions<M>\n  ): Promise<StateRecord[]>\n  recordStates(testInfo: TestInfoLike, records: StateRecord[]): Promise<void>\n}\n\n/**\n * Bind the capture helpers to a project's generated state space:\n *\n * ```ts\n * // e2e/states/capture.ts — the ONE place e2e meets the registry\n * import { createStateCapture } from \"uidex/playwright\"\n * import type { UidexStates } from \"@/uidex.gen\"\n * export const { captureState } = createStateCapture<UidexStates>()\n * ```\n *\n * Purely a type-level narrowing — the runtime is the untyped `captureState`.\n * Its value is closing the loop that let capture ids drift from the registry:\n * before this, `entity` was a free string, so a spec could invent a name the\n * registry had never heard of and nothing failed until a lint pass noticed the\n * mismatch (or, when the entity kind was also wrong, never noticed at all).\n */\nexport function createStateCapture<\n  M extends Partial<StateSpace>,\n>(): TypedStateCapture<M> {\n  return {\n    captureState: (page, testInfo, opts) =>\n      captureState(page, testInfo, opts as unknown as CaptureStateOptions),\n    recordStates,\n  }\n}\n"],"mappings":"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","names":[]}

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

@@ -27,16 +27,31 @@ interface CapturedStatesManifestOut {
     captured: CapturedStateEntry[];
     /** Every distinct theme/width/path variant, for tooling that wants detail. */
     variants: StateRecord[];
+    /**
+     * ISO timestamp of the run that wrote this manifest. The scanner compares it
+     * to the mtimes of the files declaring states, so a manifest that predates a
+     * declaration edit is reported as stale rather than silently trusted.
+     */
+    generatedAt?: string;
 }
 interface UidexStatesReporterOptions {
     outputPath?: string;
     silent?: boolean;
+    /**
+     * Write to `<outputPath>` even when the run captured FEWER states than the
+     * manifest already on disk. Off by default: a filtered (`--grep`) or flaky
+     * run legitimately produces a subset, and blindly overwriting turns that into
+     * silent coverage loss — the run exits non-zero, but the manifest is already
+     * gone. See the shrink guard in `onEnd`.
+     */
+    allowShrink?: 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 allowShrink;
     private readonly variants;
     constructor(options?: UidexStatesReporterOptions);
     onTestEnd(_test: TestCase, result: TestResult): void;

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

@@ -27,16 +27,31 @@ interface CapturedStatesManifestOut {
     captured: CapturedStateEntry[];
     /** Every distinct theme/width/path variant, for tooling that wants detail. */
     variants: StateRecord[];
+    /**
+     * ISO timestamp of the run that wrote this manifest. The scanner compares it
+     * to the mtimes of the files declaring states, so a manifest that predates a
+     * declaration edit is reported as stale rather than silently trusted.
+     */
+    generatedAt?: string;
 }
 interface UidexStatesReporterOptions {
     outputPath?: string;
     silent?: boolean;
+    /**
+     * Write to `<outputPath>` even when the run captured FEWER states than the
+     * manifest already on disk. Off by default: a filtered (`--grep`) or flaky
+     * run legitimately produces a subset, and blindly overwriting turns that into
+     * silent coverage loss — the run exits non-zero, but the manifest is already
+     * gone. See the shrink guard in `onEnd`.
+     */
+    allowShrink?: 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 allowShrink;
     private readonly variants;
     constructor(options?: UidexStatesReporterOptions);
     onTestEnd(_test: TestCase, result: TestResult): void;

package/dist/playwright/states-reporter.js

@@ -6,6 +6,19 @@ import * as path from "path";
 var STATES_ATTACHMENT = "uidex-states";
 
 // src/integrations/playwright/states-reporter.ts
+function capturedKey(c) {
+  return `${c.kind ?? "page"}\0${c.entity}\0${c.state}`;
+}
+function readExisting(p) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(p, "utf8"));
+    if (!parsed || typeof parsed !== "object") return null;
+    const m = parsed;
+    return Array.isArray(m.captured) ? { captured: m.captured, variants: m.variants ?? [] } : null;
+  } catch {
+    return null;
+  }
+}
 function keyOf(r) {
   return JSON.stringify([
     r.kind ?? null,
@@ -52,10 +65,12 @@ function parsePayload(raw) {
 var UidexStatesReporter = class {
   outputPath;
   silent;
+  allowShrink;
   variants = [];
   constructor(options = {}) {
     this.outputPath = options.outputPath ?? "uidex-states.json";
     this.silent = options.silent ?? false;
+    this.allowShrink = options.allowShrink ?? false;
   }
   onTestEnd(_test, result) {
     for (const attachment of result.attachments) {
@@ -66,13 +81,27 @@ var UidexStatesReporter = class {
   }
   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"
-    );
+    manifest.generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const target = path.resolve(this.outputPath);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const existing = this.allowShrink ? null : readExisting(target);
+    const dropped = existing ? (() => {
+      const now = new Set(manifest.captured.map(capturedKey));
+      return existing.captured.map(capturedKey).filter((k) => !now.has(k)).sort();
+    })() : [];
+    const shrunk = dropped.length > 0;
+    const out = shrunk ? target.replace(/\.json$/i, "") + ".partial.json" : target;
+    fs.writeFileSync(out, JSON.stringify(manifest, null, 2) + "\n");
+    if (shrunk) {
+      console.error(
+        `uidex states: \u26A0 run captured ${manifest.captured.length} state(s) but ${existing.captured.length} are committed \u2014 ${dropped.length} would be DROPPED, so ${path.basename(target)} was left untouched and this run went to ${path.basename(out)}.`
+      );
+      console.error(`  dropped: ${dropped.join(", ")}`);
+      console.error(
+        `  A consistent count across two runs is a genuinely broken spec; a varying one is flake. For a deliberate removal, copy the partial over or set allowShrink.`
+      );
+      return;
+    }
     if (!this.silent) {
       const entities = new Set(manifest.captured.map((c) => c.entity)).size;
       console.log(

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

@@ -1 +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":[]}
+{"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   * ISO timestamp of the run that wrote this manifest. The scanner compares it\n   * to the mtimes of the files declaring states, so a manifest that predates a\n   * declaration edit is reported as stale rather than silently trusted.\n   */\n  generatedAt?: string\n}\n\nexport interface UidexStatesReporterOptions {\n  outputPath?: string\n  silent?: boolean\n  /**\n   * Write to `<outputPath>` even when the run captured FEWER states than the\n   * manifest already on disk. Off by default: a filtered (`--grep`) or flaky\n   * run legitimately produces a subset, and blindly overwriting turns that into\n   * silent coverage loss — the run exits non-zero, but the manifest is already\n   * gone. See the shrink guard in `onEnd`.\n   */\n  allowShrink?: boolean\n}\n\n/** Identity of a captured state for shrink comparison. */\nfunction capturedKey(c: CapturedStateEntry): string {\n  return `${c.kind ?? \"page\"}\u0000${c.entity}\u0000${c.state}`\n}\n\nfunction readExisting(p: string): CapturedStatesManifestOut | null {\n  try {\n    const parsed = JSON.parse(fs.readFileSync(p, \"utf8\")) as unknown\n    if (!parsed || typeof parsed !== \"object\") return null\n    const m = parsed as Partial<CapturedStatesManifestOut>\n    return Array.isArray(m.captured)\n      ? { captured: m.captured, variants: m.variants ?? [] }\n      : null\n  } catch {\n    return null // absent or unreadable → nothing to protect\n  }\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 allowShrink: 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    this.allowShrink = options.allowShrink ?? 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    manifest.generatedAt = new Date().toISOString()\n    const target = path.resolve(this.outputPath)\n    fs.mkdirSync(path.dirname(target), { recursive: true })\n\n    // ---- Shrink guard ----\n    // A filtered or flaky run captures a SUBSET. Writing it over the committed\n    // manifest silently deletes coverage: the states simply vanish, the gate\n    // then agrees nothing is missing, and the only signal is a state count you\n    // had to be watching. So when the run would drop states, divert it to\n    // `<name>.partial.json`, leave the committed manifest untouched, and name\n    // the dropped keys — the caller decides whether it was flake or a real\n    // removal (for a deliberate removal, copy the partial over, or re-run with\n    // `allowShrink`).\n    const existing = this.allowShrink ? null : readExisting(target)\n    const dropped = existing\n      ? (() => {\n          const now = new Set(manifest.captured.map(capturedKey))\n          return existing.captured\n            .map(capturedKey)\n            .filter((k) => !now.has(k))\n            .sort()\n        })()\n      : []\n\n    const shrunk = dropped.length > 0\n    const out = shrunk\n      ? target.replace(/\\.json$/i, \"\") + \".partial.json\"\n      : target\n    fs.writeFileSync(out, JSON.stringify(manifest, null, 2) + \"\\n\")\n\n    if (shrunk) {\n      console.error(\n        `uidex states: ⚠ run captured ${manifest.captured.length} state(s) but ${existing!.captured.length} are committed — ${dropped.length} would be DROPPED, so ${path.basename(target)} was left untouched and this run went to ${path.basename(out)}.`\n      )\n      console.error(`  dropped: ${dropped.join(\", \")}`)\n      console.error(\n        `  A consistent count across two runs is a genuinely broken spec; a varying one is flake. For a deliberate removal, copy the partial over or set allowShrink.`\n      )\n      return\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\n/**\n * The declared state space a generated `UidexStates` describes: entity kind →\n * entity id → that entity's own state names.\n */\nexport type StateSpace = {\n  [K in StateEntityKind]: Record<string, string> | never\n}\n\n/**\n * Capture options narrowed to ONE entity of one kind, with only the states that\n * entity actually declares. Built as a union over (kind, entity) pairs so the\n * three fields are checked together — picking `widget`/`gate-badge` restricts\n * `state` to gate-badge's own names, and a page id is not assignable at all.\n */\nexport type TypedCaptureOptions<M> = {\n  [K in keyof M & StateEntityKind]: M[K] extends Record<string, string>\n    ? {\n        [E in keyof M[K] & string]: Omit<\n          CaptureStateOptions,\n          \"entity\" | \"kind\" | \"state\"\n        > & { kind: K; entity: E; state: M[K][E] }\n      }[keyof M[K] & string]\n    : never\n}[keyof M & StateEntityKind]\n\nexport interface TypedStateCapture<M> {\n  captureState(\n    page: Page,\n    testInfo: TestInfoLike,\n    opts: TypedCaptureOptions<M>\n  ): Promise<StateRecord[]>\n  recordStates(testInfo: TestInfoLike, records: StateRecord[]): Promise<void>\n}\n\n/**\n * Bind the capture helpers to a project's generated state space:\n *\n * ```ts\n * // e2e/states/capture.ts — the ONE place e2e meets the registry\n * import { createStateCapture } from \"uidex/playwright\"\n * import type { UidexStates } from \"@/uidex.gen\"\n * export const { captureState } = createStateCapture<UidexStates>()\n * ```\n *\n * Purely a type-level narrowing — the runtime is the untyped `captureState`.\n * Its value is closing the loop that let capture ids drift from the registry:\n * before this, `entity` was a free string, so a spec could invent a name the\n * registry had never heard of and nothing failed until a lint pass noticed the\n * mismatch (or, when the entity kind was also wrong, never noticed at all).\n */\nexport function createStateCapture<\n  M extends Partial<StateSpace>,\n>(): TypedStateCapture<M> {\n  return {\n    captureState: (page, testInfo, opts) =>\n      captureState(page, testInfo, opts as unknown as CaptureStateOptions),\n    recordStates,\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/playwright/states.cjs

@@ -25,6 +25,7 @@ __export(states_exports, {
   THEMES: () => THEMES,
   WIDTHS: () => WIDTHS,
   captureState: () => captureState,
+  createStateCapture: () => createStateCapture,
   recordStates: () => recordStates
 });
 module.exports = __toCommonJS(states_exports);
@@ -106,6 +107,12 @@ async function captureState(page, testInfo, opts) {
   await recordStates(testInfo, records);
   return records;
 }
+function createStateCapture() {
+  return {
+    captureState: (page, testInfo, opts) => captureState(page, testInfo, opts),
+    recordStates
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CORE_STATE_KINDS,
@@ -113,6 +120,7 @@ async function captureState(page, testInfo, opts) {
   THEMES,
   WIDTHS,
   captureState,
+  createStateCapture,
   recordStates
 });
 //# sourceMappingURL=states.cjs.map

package/dist/playwright/states.cjs.map

@@ -1 +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":[]}
+{"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\n/**\n * The declared state space a generated `UidexStates` describes: entity kind →\n * entity id → that entity's own state names.\n */\nexport type StateSpace = {\n  [K in StateEntityKind]: Record<string, string> | never\n}\n\n/**\n * Capture options narrowed to ONE entity of one kind, with only the states that\n * entity actually declares. Built as a union over (kind, entity) pairs so the\n * three fields are checked together — picking `widget`/`gate-badge` restricts\n * `state` to gate-badge's own names, and a page id is not assignable at all.\n */\nexport type TypedCaptureOptions<M> = {\n  [K in keyof M & StateEntityKind]: M[K] extends Record<string, string>\n    ? {\n        [E in keyof M[K] & string]: Omit<\n          CaptureStateOptions,\n          \"entity\" | \"kind\" | \"state\"\n        > & { kind: K; entity: E; state: M[K][E] }\n      }[keyof M[K] & string]\n    : never\n}[keyof M & StateEntityKind]\n\nexport interface TypedStateCapture<M> {\n  captureState(\n    page: Page,\n    testInfo: TestInfoLike,\n    opts: TypedCaptureOptions<M>\n  ): Promise<StateRecord[]>\n  recordStates(testInfo: TestInfoLike, records: StateRecord[]): Promise<void>\n}\n\n/**\n * Bind the capture helpers to a project's generated state space:\n *\n * ```ts\n * // e2e/states/capture.ts — the ONE place e2e meets the registry\n * import { createStateCapture } from \"uidex/playwright\"\n * import type { UidexStates } from \"@/uidex.gen\"\n * export const { captureState } = createStateCapture<UidexStates>()\n * ```\n *\n * Purely a type-level narrowing — the runtime is the untyped `captureState`.\n * Its value is closing the loop that let capture ids drift from the registry:\n * before this, `entity` was a free string, so a spec could invent a name the\n * registry had never heard of and nothing failed until a lint pass noticed the\n * mismatch (or, when the entity kind was also wrong, never noticed at all).\n */\nexport function createStateCapture<\n  M extends Partial<StateSpace>,\n>(): TypedStateCapture<M> {\n  return {\n    captureState: (page, testInfo, opts) =>\n      captureState(page, testInfo, opts as unknown as CaptureStateOptions),\n    recordStates,\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/playwright/states.d.cts

@@ -116,5 +116,48 @@ interface CaptureStateOptions {
  * it attached (also handy in tests).
  */
 declare function captureState(page: Page, testInfo: TestInfoLike, opts: CaptureStateOptions): Promise<StateRecord[]>;
+/**
+ * The declared state space a generated `UidexStates` describes: entity kind →
+ * entity id → that entity's own state names.
+ */
+type StateSpace = {
+    [K in StateEntityKind]: Record<string, string> | never;
+};
+/**
+ * Capture options narrowed to ONE entity of one kind, with only the states that
+ * entity actually declares. Built as a union over (kind, entity) pairs so the
+ * three fields are checked together — picking `widget`/`gate-badge` restricts
+ * `state` to gate-badge's own names, and a page id is not assignable at all.
+ */
+type TypedCaptureOptions<M> = {
+    [K in keyof M & StateEntityKind]: M[K] extends Record<string, string> ? {
+        [E in keyof M[K] & string]: Omit<CaptureStateOptions, "entity" | "kind" | "state"> & {
+            kind: K;
+            entity: E;
+            state: M[K][E];
+        };
+    }[keyof M[K] & string] : never;
+}[keyof M & StateEntityKind];
+interface TypedStateCapture<M> {
+    captureState(page: Page, testInfo: TestInfoLike, opts: TypedCaptureOptions<M>): Promise<StateRecord[]>;
+    recordStates(testInfo: TestInfoLike, records: StateRecord[]): Promise<void>;
+}
+/**
+ * Bind the capture helpers to a project's generated state space:
+ *
+ * ```ts
+ * // e2e/states/capture.ts — the ONE place e2e meets the registry
+ * import { createStateCapture } from "uidex/playwright"
+ * import type { UidexStates } from "@/uidex.gen"
+ * export const { captureState } = createStateCapture<UidexStates>()
+ * ```
+ *
+ * Purely a type-level narrowing — the runtime is the untyped `captureState`.
+ * Its value is closing the loop that let capture ids drift from the registry:
+ * before this, `entity` was a free string, so a spec could invent a name the
+ * registry had never heard of and nothing failed until a lint pass noticed the
+ * mismatch (or, when the entity kind was also wrong, never noticed at all).
+ */
+declare function createStateCapture<M extends Partial<StateSpace>>(): TypedStateCapture<M>;
 
-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 };
+export { CORE_STATE_KINDS, type CaptureStateOptions, type CoreStateKind, STATES_ATTACHMENT, type StateEntityKind, type StateKind, type StateRecord, type StateSpace, type StatesPayload, THEMES, type Theme, type TypedCaptureOptions, type TypedStateCapture, WIDTHS, type WidthLabel, captureState, createStateCapture, recordStates };

package/dist/playwright/states.d.ts

@@ -116,5 +116,48 @@ interface CaptureStateOptions {
  * it attached (also handy in tests).
  */
 declare function captureState(page: Page, testInfo: TestInfoLike, opts: CaptureStateOptions): Promise<StateRecord[]>;
+/**
+ * The declared state space a generated `UidexStates` describes: entity kind →
+ * entity id → that entity's own state names.
+ */
+type StateSpace = {
+    [K in StateEntityKind]: Record<string, string> | never;
+};
+/**
+ * Capture options narrowed to ONE entity of one kind, with only the states that
+ * entity actually declares. Built as a union over (kind, entity) pairs so the
+ * three fields are checked together — picking `widget`/`gate-badge` restricts
+ * `state` to gate-badge's own names, and a page id is not assignable at all.
+ */
+type TypedCaptureOptions<M> = {
+    [K in keyof M & StateEntityKind]: M[K] extends Record<string, string> ? {
+        [E in keyof M[K] & string]: Omit<CaptureStateOptions, "entity" | "kind" | "state"> & {
+            kind: K;
+            entity: E;
+            state: M[K][E];
+        };
+    }[keyof M[K] & string] : never;
+}[keyof M & StateEntityKind];
+interface TypedStateCapture<M> {
+    captureState(page: Page, testInfo: TestInfoLike, opts: TypedCaptureOptions<M>): Promise<StateRecord[]>;
+    recordStates(testInfo: TestInfoLike, records: StateRecord[]): Promise<void>;
+}
+/**
+ * Bind the capture helpers to a project's generated state space:
+ *
+ * ```ts
+ * // e2e/states/capture.ts — the ONE place e2e meets the registry
+ * import { createStateCapture } from "uidex/playwright"
+ * import type { UidexStates } from "@/uidex.gen"
+ * export const { captureState } = createStateCapture<UidexStates>()
+ * ```
+ *
+ * Purely a type-level narrowing — the runtime is the untyped `captureState`.
+ * Its value is closing the loop that let capture ids drift from the registry:
+ * before this, `entity` was a free string, so a spec could invent a name the
+ * registry had never heard of and nothing failed until a lint pass noticed the
+ * mismatch (or, when the entity kind was also wrong, never noticed at all).
+ */
+declare function createStateCapture<M extends Partial<StateSpace>>(): TypedStateCapture<M>;
 
-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 };
+export { CORE_STATE_KINDS, type CaptureStateOptions, type CoreStateKind, STATES_ATTACHMENT, type StateEntityKind, type StateKind, type StateRecord, type StateSpace, type StatesPayload, THEMES, type Theme, type TypedCaptureOptions, type TypedStateCapture, WIDTHS, type WidthLabel, captureState, createStateCapture, recordStates };

package/dist/playwright/states.js

@@ -77,12 +77,19 @@ async function captureState(page, testInfo, opts) {
   await recordStates(testInfo, records);
   return records;
 }
+function createStateCapture() {
+  return {
+    captureState: (page, testInfo, opts) => captureState(page, testInfo, opts),
+    recordStates
+  };
+}
 export {
   CORE_STATE_KINDS,
   STATES_ATTACHMENT,
   THEMES,
   WIDTHS,
   captureState,
+  createStateCapture,
   recordStates
 };
 //# sourceMappingURL=states.js.map

package/dist/playwright/states.js.map

@@ -1 +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":";AAqBO,IAAM,oBAAoB;AAG1B,IAAM,SAAS,CAAC,SAAS,MAAM;AAE/B,IAAM,SAAS,EAAE,SAAS,MAAM,QAAQ,IAAI;AAO5C,IAAM,mBAAmB;AAAA,EAC9B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AA0CA,eAAsB,aACpB,UACA,SACe;AACf,MAAI,QAAQ,WAAW,EAAG;AAC1B,QAAM,UAAyB,EAAE,QAAQ;AACzC,QAAM,SAAS,OAAO,mBAAmB;AAAA,IACvC,MAAM,KAAK,UAAU,OAAO;AAAA,IAC5B,aAAa;AAAA,EACf,CAAC;AACH;AA4CA,SAAS,gBAAgB,MAAgC;AACvD,MAAI;AACF,WAAO,IAAI,IAAI,KAAK,IAAI,CAAC,EAAE;AAAA,EAC7B,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEA,eAAe,gBAAgB,MAAY,OAA6B;AACtE,QAAM,KAAK,aAAa,EAAE,aAAa,MAAM,CAAC;AAChD;AAGA,SAAS,eAAe,OAAe,UAAiC;AACtE,MAAI,SAAU,QAAO;AACrB,SAAQ,iBAAuC,SAAS,KAAK,IACxD,QACD;AACN;AAEA,SAAS,SACP,MACA,OACA,OACA,aACQ;AACR,QAAM,OAAO,GAAG,KAAK,MAAM,IAAI,KAAK,KAAK;AACzC,SAAO,cAAc,GAAG,IAAI,IAAI,KAAK,IAAI,KAAK,KAAK,GAAG,IAAI,IAAI,KAAK;AACrE;AAQA,eAAsB,aACpB,MACA,UACA,MACwB;AACxB,QAAM,SAAS,KAAK,UAAU;AAC9B,QAAM,SAAS,KAAK,UAAW,CAAC,SAAS;AACzC,QAAM,cAAc,OAAO,SAAS;AACpC,QAAM,MAAM,KAAK,OAAO,QAAQ,IAAI;AACpC,QAAM,WAAW,KAAK,YAAY;AAClC,QAAM,cAAc,gBAAgB,IAAI;AACxC,QAAM,UAAyB,CAAC;AAEhC,aAAW,SAAS,QAAQ;AAC1B,UAAM,SAAS,MAAM,KAAK;AAC1B,QAAI,KAAK,MAAO,OAAM,KAAK,MAAM,IAAI;AACrC,eAAW,SAAS,QAAQ;AAC1B,YAAM,KAAK,gBAAgB,EAAE,OAAO,OAAO,KAAK,GAAG,QAAQ,IAAI,CAAC;AAChE,UAAI,KAAK,MAAO,OAAM,KAAK,MAAM,IAAI;AACrC,YAAM,SAAsB;AAAA,QAC1B,QAAQ,KAAK;AAAA,QACb,OAAO,KAAK;AAAA,QACZ,WAAW,eAAe,KAAK,OAAO,KAAK,SAAS;AAAA,QACpD;AAAA,QACA,OAAO;AAAA,QACP,GAAI,KAAK,OAAO,EAAE,MAAM,KAAK,KAAK,IAAI,CAAC;AAAA,QACvC,GAAI,KAAK,QAAQ,EAAE,OAAO,KAAK,MAAM,IAAI,CAAC;AAAA,QAC1C,GAAI,cAAc,EAAE,KAAK,YAAY,IAAI,CAAC;AAAA,MAC5C;AACA,UAAI,KAAK;AACP,cAAM,OAAO,GAAG,GAAG,IAAI,SAAS,MAAM,OAAO,OAAO,WAAW,CAAC;AAChE,cAAM,KAAK,WAAW;AAAA,UACpB;AAAA,UACA,UAAU,KAAK,YAAY;AAAA,UAC3B,GAAI,KAAK,YAAY,EAAE,WAAW,KAAK,UAAU,IAAI,CAAC;AAAA,UACtD,GAAI,KAAK,MAAM,SACX;AAAA,YACE,MAAM,KAAK,KAAK,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC;AAAA,YAC1C,WAAW;AAAA,UACb,IACA,CAAC;AAAA,QACP,CAAC;AACD,eAAO,OAAO;AAAA,MAChB;AACA,cAAQ,KAAK,MAAM;AAAA,IACrB;AAAA,EACF;AAEA,QAAM,aAAa,UAAU,OAAO;AACpC,SAAO;AACT;","names":[]}
+{"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\n/**\n * The declared state space a generated `UidexStates` describes: entity kind →\n * entity id → that entity's own state names.\n */\nexport type StateSpace = {\n  [K in StateEntityKind]: Record<string, string> | never\n}\n\n/**\n * Capture options narrowed to ONE entity of one kind, with only the states that\n * entity actually declares. Built as a union over (kind, entity) pairs so the\n * three fields are checked together — picking `widget`/`gate-badge` restricts\n * `state` to gate-badge's own names, and a page id is not assignable at all.\n */\nexport type TypedCaptureOptions<M> = {\n  [K in keyof M & StateEntityKind]: M[K] extends Record<string, string>\n    ? {\n        [E in keyof M[K] & string]: Omit<\n          CaptureStateOptions,\n          \"entity\" | \"kind\" | \"state\"\n        > & { kind: K; entity: E; state: M[K][E] }\n      }[keyof M[K] & string]\n    : never\n}[keyof M & StateEntityKind]\n\nexport interface TypedStateCapture<M> {\n  captureState(\n    page: Page,\n    testInfo: TestInfoLike,\n    opts: TypedCaptureOptions<M>\n  ): Promise<StateRecord[]>\n  recordStates(testInfo: TestInfoLike, records: StateRecord[]): Promise<void>\n}\n\n/**\n * Bind the capture helpers to a project's generated state space:\n *\n * ```ts\n * // e2e/states/capture.ts — the ONE place e2e meets the registry\n * import { createStateCapture } from \"uidex/playwright\"\n * import type { UidexStates } from \"@/uidex.gen\"\n * export const { captureState } = createStateCapture<UidexStates>()\n * ```\n *\n * Purely a type-level narrowing — the runtime is the untyped `captureState`.\n * Its value is closing the loop that let capture ids drift from the registry:\n * before this, `entity` was a free string, so a spec could invent a name the\n * registry had never heard of and nothing failed until a lint pass noticed the\n * mismatch (or, when the entity kind was also wrong, never noticed at all).\n */\nexport function createStateCapture<\n  M extends Partial<StateSpace>,\n>(): TypedStateCapture<M> {\n  return {\n    captureState: (page, testInfo, opts) =>\n      captureState(page, testInfo, opts as unknown as CaptureStateOptions),\n    recordStates,\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/react/index.cjs

@@ -1056,6 +1056,9 @@ var tailwind_built_default = `/*! tailwindcss v4.2.2 | MIT License | https://tai
   .flex-1 {
     flex: 1;
   }
+  .shrink {
+    flex-shrink: 1;
+  }
   .shrink-0 {
     flex-shrink: 0;
   }