uidex 0.7.0 → 0.8.0

package/dist/scan/index.cjs

@@ -35,12 +35,21 @@ __export(scan_exports, {
   DEFAULT_CONVENTIONS: () => DEFAULT_CONVENTIONS,
   applyFixes: () => applyFixes,
   audit: () => audit,
+  checkPageCoverage: () => checkPageCoverage,
+  checkStateCoverage: () => checkStateCoverage,
+  checkStateMatrix: () => checkStateMatrix,
+  compileRoute: () => compileRoute,
+  computeMissingKinds: () => computeMissingKinds,
+  computePageBaseline: () => computePageBaseline,
   detectRoutes: () => detectRoutes,
   discover: () => discover,
   emit: () => emit,
   extract: () => extract,
   extractUidexExports: () => extractUidexExports,
   globToRegExp: () => globToRegExp,
+  loadPageBaseline: () => loadPageBaseline,
+  matchUrlToRoute: () => matchUrlToRoute,
+  pageBaselinePath: () => pageBaselinePath,
   parseConfig: () => parseConfig,
   pathToId: () => pathToId,
   renameEntity: () => renameEntity,
@@ -86,7 +95,9 @@ var ALLOWED_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
   "output",
   "flows",
   "audit",
-  "conventions"
+  "conventions",
+  "statesManifest",
+  "coverageBaseline"
 ]);
 var ALLOWED_SOURCE_KEYS = /* @__PURE__ */ new Set(["rootDir", "include", "exclude", "prefix"]);
 var ALLOWED_CONVENTIONS_KEYS = /* @__PURE__ */ new Set([
@@ -96,7 +107,14 @@ var ALLOWED_CONVENTIONS_KEYS = /* @__PURE__ */ new Set([
   "flows",
   "regions"
 ]);
-var ALLOWED_AUDIT_KEYS = /* @__PURE__ */ new Set(["scopeLeak", "coverage", "acceptance"]);
+var ALLOWED_AUDIT_KEYS = /* @__PURE__ */ new Set([
+  "scopeLeak",
+  "coverage",
+  "acceptance",
+  "states",
+  "pageCoverage",
+  "stateMatrix"
+]);
 function fail(msg) {
   throw new ConfigError(`Invalid .uidex.json: ${msg}`);
 }
@@ -155,6 +173,12 @@ function validateConfig(raw) {
   }
   if (raw.exclude !== void 0) assertStringArray(raw.exclude, `exclude`);
   if (raw.flows !== void 0) assertStringArray(raw.flows, `flows`);
+  if (raw.statesManifest !== void 0 && typeof raw.statesManifest !== "string") {
+    fail(`"statesManifest" must be a string`);
+  }
+  if (raw.coverageBaseline !== void 0 && typeof raw.coverageBaseline !== "string") {
+    fail(`"coverageBaseline" must be a string`);
+  }
   if (raw.audit !== void 0) {
     assertObject(raw.audit, "audit");
     for (const key of Object.keys(raw.audit)) {
@@ -194,7 +218,9 @@ function validateConfig(raw) {
     output: raw.output,
     flows: raw.flows,
     audit: raw.audit,
-    conventions: raw.conventions
+    conventions: raw.conventions,
+    statesManifest: raw.statesManifest,
+    coverageBaseline: raw.coverageBaseline
   };
 }
 function parseConfig(json) {
@@ -283,7 +309,12 @@ var BASE_EXCLUDES = [
   "**/dist/**",
   "**/build/**",
   "**/.next/**",
-  "**/*.gen.ts"
+  // Exclude the scanner's own generated siblings so a scan never re-ingests its
+  // output. Enumerated (not `*.gen.*`) so a hand-written file that merely contains
+  // a `.gen.` segment, e.g. `foo.gen.helpers.ts`, is still scanned.
+  "**/*.gen.ts",
+  "**/*.gen.data.ts",
+  "**/*.gen.locs.ts"
 ];
 var TEST_EXCLUDES = [
   "**/*.test.ts",
@@ -483,6 +514,201 @@ function unwrapTsExpression(expr) {
   }
 }
 
+// src/shared/entities/types.ts
+var ENTITY_KINDS = [
+  "route",
+  "page",
+  "feature",
+  "widget",
+  "region",
+  "element",
+  "primitive",
+  "flow"
+];
+var CORE_STATE_KINDS = [
+  "loading",
+  "empty",
+  "populated",
+  "error"
+];
+function isMetaKind(kind) {
+  return kind !== "route" && kind !== "flow";
+}
+function isMetaEntity(entity) {
+  return isMetaKind(entity.kind);
+}
+function entityKey(entity) {
+  return entity.kind === "route" ? entity.path : entity.id;
+}
+var UnknownEntityKindError = class extends Error {
+  kind;
+  constructor(kind) {
+    super(`Unknown entity kind: ${kind}`);
+    this.name = "UnknownEntityKindError";
+    this.kind = kind;
+  }
+};
+var KIND_SET = new Set(ENTITY_KINDS);
+function assertEntityKind(kind) {
+  if (!KIND_SET.has(kind)) throw new UnknownEntityKindError(kind);
+}
+
+// src/shared/entities/registry.ts
+function emptyStore() {
+  return {
+    route: /* @__PURE__ */ new Map(),
+    page: /* @__PURE__ */ new Map(),
+    feature: /* @__PURE__ */ new Map(),
+    widget: /* @__PURE__ */ new Map(),
+    region: /* @__PURE__ */ new Map(),
+    element: /* @__PURE__ */ new Map(),
+    primitive: /* @__PURE__ */ new Map(),
+    flow: /* @__PURE__ */ new Map()
+  };
+}
+function computeFlowIds(flows, targetId) {
+  const ids = [];
+  for (const flow of flows) {
+    if (flow.touches.includes(targetId)) ids.push(flow.id);
+  }
+  return ids;
+}
+function freezeEntity(entity, flows) {
+  if (!isMetaKind(entity.kind)) return entity;
+  const withMeta = entity;
+  if (withMeta.meta === void 0) return entity;
+  const computedFlows = Object.freeze(computeFlowIds(flows, withMeta.id));
+  const mergedMeta = { ...withMeta.meta, flows: computedFlows };
+  return { ...entity, meta: Object.freeze(mergedMeta) };
+}
+function createRegistry() {
+  const store = emptyStore();
+  let flowsCache = null;
+  const patternCache = /* @__PURE__ */ new Map();
+  const getFlows = () => {
+    if (flowsCache === null) flowsCache = Array.from(store.flow.values());
+    return flowsCache;
+  };
+  const add = (entity) => {
+    assertEntityKind(entity.kind);
+    const key = entityKey(entity);
+    store[entity.kind].set(key, entity);
+    flowsCache = null;
+    patternCache.delete(entity.kind);
+  };
+  const get = (kind, id) => {
+    assertEntityKind(kind);
+    const raw = store[kind].get(id);
+    if (raw === void 0) return void 0;
+    return freezeEntity(raw, getFlows());
+  };
+  const getPatternsForKind = (kind) => {
+    const cached = patternCache.get(kind);
+    if (cached !== void 0) return cached;
+    const patterns = [];
+    for (const [key, entity] of store[kind]) {
+      if (key.includes("*")) {
+        const segments = key.split("*");
+        patterns.push({
+          segments,
+          staticLength: segments.reduce((n, s) => n + s.length, 0),
+          entity
+        });
+      }
+    }
+    patternCache.set(
+      kind,
+      patterns
+    );
+    return patterns;
+  };
+  const matchesSegments = (segments, id) => {
+    const first = segments[0];
+    const last = segments[segments.length - 1];
+    if (!id.startsWith(first)) return false;
+    let pos = first.length;
+    for (let i = 1; i < segments.length - 1; i++) {
+      const idx = id.indexOf(segments[i], pos);
+      if (idx === -1) return false;
+      pos = idx + segments[i].length;
+    }
+    return id.endsWith(last) && id.length - last.length >= pos;
+  };
+  const matchPattern = (kind, id) => {
+    assertEntityKind(kind);
+    const patterns = getPatternsForKind(kind);
+    if (patterns.length === 0) return void 0;
+    let best;
+    for (const entry of patterns) {
+      if (matchesSegments(entry.segments, id) && (best === void 0 || entry.staticLength > best.staticLength)) {
+        best = entry;
+      }
+    }
+    if (best === void 0) return void 0;
+    return freezeEntity(best.entity, getFlows());
+  };
+  const list = (kind) => {
+    assertEntityKind(kind);
+    const flows = getFlows();
+    return Array.from(
+      store[kind].values(),
+      (e) => freezeEntity(e, flows)
+    );
+  };
+  const allEntities = function* () {
+    for (const kind of Object.keys(store)) {
+      for (const entity of store[kind].values()) {
+        yield entity;
+      }
+    }
+  };
+  const query = (predicate) => {
+    const flows = getFlows();
+    const result = [];
+    for (const entity of allEntities()) {
+      if (predicate(entity)) result.push(freezeEntity(entity, flows));
+    }
+    return result;
+  };
+  const byScope = (scope) => query(
+    (entity) => "scopes" in entity && Array.isArray(entity.scopes) && entity.scopes.includes(scope)
+  );
+  const touchedBy = (flowId) => {
+    const flow = store.flow.get(flowId);
+    if (flow === void 0) return [];
+    const ids = new Set(flow.touches);
+    return query((entity) => {
+      if (!isMetaEntity(entity)) return false;
+      return ids.has(entity.id);
+    });
+  };
+  const reports = /* @__PURE__ */ new Map();
+  const reportsCbs = /* @__PURE__ */ new Set();
+  const setReports = (kind, id, records) => {
+    reports.set(`${kind}:${id}`, records);
+    for (const cb of reportsCbs) cb();
+  };
+  const getReports = (kind, id) => reports.get(`${kind}:${id}`) ?? [];
+  const listReportKeys = () => Array.from(reports.keys());
+  const onReportsChange = (cb) => {
+    reportsCbs.add(cb);
+    return () => reportsCbs.delete(cb);
+  };
+  return {
+    add,
+    get,
+    matchPattern,
+    list,
+    query,
+    byScope,
+    touchedBy,
+    setReports,
+    getReports,
+    listReportKeys,
+    onReportsChange
+  };
+}
+
 // src/scanner/scan/extract-uidex-export.ts
 var KIND_DISCRIMINATORS = [
   "page",
@@ -500,20 +726,35 @@ var ALLOWED_FIELDS = {
     "features",
     "widgets",
     "acceptance",
+    "states",
+    "capture",
+    "waivers",
     "description"
   ]),
+  // `capture` / `waivers` are route-scoped, and only a page maps to a route — so
+  // they are page-only (the gates read them off the page). A feature/widget that
+  // sets them gets an `uidex-export-unknown-field` error rather than a silent no-op.
   feature: /* @__PURE__ */ new Set([
     "feature",
     "name",
     "features",
     "acceptance",
+    "states",
     "description"
   ]),
   primitive: /* @__PURE__ */ new Set(["primitive", "name", "description"]),
-  widget: /* @__PURE__ */ new Set(["widget", "name", "acceptance", "description"]),
+  widget: /* @__PURE__ */ new Set(["widget", "name", "acceptance", "states", "description"]),
   region: /* @__PURE__ */ new Set(["region", "name", "description"]),
   flow: /* @__PURE__ */ new Set(["flow", "notFlow", "name", "description"])
 };
+var STATE_FIELDS = /* @__PURE__ */ new Set([
+  "name",
+  "kind",
+  "acceptance",
+  "description"
+]);
+var CORE_STATE_KINDS2 = new Set(CORE_STATE_KINDS);
+var STATE_KINDS = /* @__PURE__ */ new Set([...CORE_STATE_KINDS, "variant"]);
 var FALSEABLE = /* @__PURE__ */ new Set([
   "page",
   "feature",
@@ -903,6 +1144,9 @@ function buildMetadata(value, file, sourcePath, headerPos, diagnostics) {
   }
   const featuresField = kind === "page" || kind === "feature" ? readStringArrayField(byKey, "features") : void 0;
   const widgetsField = kind === "page" ? readStringArrayField(byKey, "widgets") : void 0;
+  const states = kind === "page" || kind === "feature" || kind === "widget" ? readStatesField(byKey) : void 0;
+  const capture = kind === "page" ? readBooleanField(byKey, "capture") : void 0;
+  const waivers = kind === "page" ? readWaiversField(byKey) : void 0;
   const notFlow = kind === "flow" && discriminator === "notFlow" ? true : void 0;
   const metadata = {
     source: "ts-export",
@@ -925,6 +1169,9 @@ function buildMetadata(value, file, sourcePath, headerPos, diagnostics) {
     metadata.widgets = widgetsField.values;
     metadata.widgetSpans = widgetsField.spans;
   }
+  if (states?.length) metadata.states = states;
+  if (capture !== void 0) metadata.capture = capture;
+  if (waivers && Object.keys(waivers).length > 0) metadata.waivers = waivers;
   if (notFlow) metadata.notFlow = true;
   if (typeof id === "string" && idValue.kind === "string") {
     metadata.idSpan = idValue.span;
@@ -961,6 +1208,48 @@ function readIdField(value, kind, fieldName) {
     value.pos
   );
 }
+function readWaiversField(byKey) {
+  const entry = byKey.get("waivers");
+  if (!entry) return void 0;
+  if (entry.value.kind !== "object") {
+    throw new ExtractError(
+      "uidex-export-invalid-field",
+      "`waivers` must be an object mapping a core kind to a reason.",
+      entry.value.pos
+    );
+  }
+  const waivers = {};
+  for (const e of entry.value.entries) {
+    if (!CORE_STATE_KINDS2.has(e.key)) {
+      throw new ExtractError(
+        "uidex-export-invalid-field",
+        `waiver key "${e.key}" is not a core kind; only ${[...CORE_STATE_KINDS2].join(", ")} participate in the matrix.`,
+        e.keyPos
+      );
+    }
+    if (e.value.kind !== "string" || e.value.value.length === 0) {
+      throw new ExtractError(
+        "uidex-export-invalid-field",
+        `waiver "${e.key}" needs a non-empty reason (why the route cannot render this kind).`,
+        e.value.pos
+      );
+    }
+    waivers[e.key] = e.value.value;
+  }
+  return waivers;
+}
+function readBooleanField(byKey, name) {
+  const entry = byKey.get(name);
+  if (!entry) return void 0;
+  if (entry.value.kind !== "boolean") {
+    throw new ExtractError(
+      "uidex-export-invalid-field",
+      `\`${name}\` must be a boolean.`,
+      entry.value.pos
+    );
+  }
+  return entry.value.value;
+}
 function readStringField(byKey, name) {
   const entry = byKey.get(name);
   if (!entry) return void 0;
@@ -998,6 +1287,86 @@ function readStringArrayField(byKey, name) {
   }
   return { values, spans };
 }
+function readStatesField(byKey) {
+  const entry = byKey.get("states");
+  if (!entry) return void 0;
+  if (entry.value.kind !== "array") {
+    throw new ExtractError(
+      "uidex-export-invalid-field",
+      "`states` must be an array of state names or `{ name, acceptance?, description? }` objects.",
+      entry.value.pos
+    );
+  }
+  const states = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const item of entry.value.items) {
+    let state;
+    if (item.kind === "string") {
+      state = { name: item.value, nameSpan: item.span };
+    } else if (item.kind === "object") {
+      const fieldByKey = /* @__PURE__ */ new Map();
+      for (const e of item.entries) fieldByKey.set(e.key, e);
+      for (const e of item.entries) {
+        if (!STATE_FIELDS.has(e.key)) {
+          throw new ExtractError(
+            "uidex-export-invalid-field",
+            `Unknown field "${e.key}" in a \`states\` entry. Allowed: ${Array.from(
+              STATE_FIELDS
+            ).sort().join(", ")}.`,
+            e.value.pos
+          );
+        }
+      }
+      const nameEntry = fieldByKey.get("name");
+      if (!nameEntry || nameEntry.value.kind !== "string") {
+        throw new ExtractError(
+          "uidex-export-invalid-field",
+          "Each object `states` entry must have a string `name`.",
+          item.pos
+        );
+      }
+      state = { name: nameEntry.value.value, nameSpan: nameEntry.value.span };
+      const kind = readStringField(fieldByKey, "kind");
+      if (kind !== void 0) {
+        if (!STATE_KINDS.has(kind)) {
+          throw new ExtractError(
+            "uidex-export-invalid-field",
+            `state \`kind\` must be one of ${[...STATE_KINDS].join(", ")} (got "${kind}").`,
+            fieldByKey.get("kind").value.pos
+          );
+        }
+        state.kind = kind;
+      }
+      const acceptance = readStringArrayField(fieldByKey, "acceptance")?.values;
+      if (acceptance) state.acceptance = acceptance;
+      const description = readStringField(fieldByKey, "description");
+      if (description) state.description = description;
+    } else {
+      throw new ExtractError(
+        "uidex-export-invalid-field",
+        "`states` items must be strings or `{ name, ... }` objects.",
+        item.pos
+      );
+    }
+    if (state.name.length === 0) {
+      throw new ExtractError(
+        "uidex-export-invalid-field",
+        "A `states` entry has an empty `name`.",
+        item.pos
+      );
+    }
+    if (seen.has(state.name)) {
+      throw new ExtractError(
+        "uidex-export-duplicate-state",
+        `Duplicate state "${state.name}" in \`states\`; each state name must be unique within the entity.`,
+        item.pos
+      );
+    }
+    seen.add(state.name);
+    states.push(state);
+  }
+  return states;
+}
 function posAt(content, offset, p2) {
   const lineStart = content.lastIndexOf("\n", offset - 1) + 1;
   return { offset, line: p2.lineAt(offset), column: offset - lineStart + 1 };
@@ -1498,211 +1867,22 @@ function collectImportFacts(parsed) {
     } else {
       continue;
     }
-    if (!source || source.type !== "Literal") continue;
-    if (typeof source.value !== "string") continue;
-    out2.push({
-      specifier: source.value,
-      line: parsed.lineAt(stmt.start),
-      span: { start: stmt.start, end: stmt.end },
-      isTypeOnly,
-      names
-    });
-  }
-  return out2;
-}
-
-// src/scanner/scan/resolve.ts
-var path4 = __toESM(require("path"), 1);
-
-// src/shared/entities/types.ts
-var ENTITY_KINDS = [
-  "route",
-  "page",
-  "feature",
-  "widget",
-  "region",
-  "element",
-  "primitive",
-  "flow"
-];
-function isMetaKind(kind) {
-  return kind !== "route" && kind !== "flow";
-}
-function isMetaEntity(entity) {
-  return isMetaKind(entity.kind);
-}
-function entityKey(entity) {
-  return entity.kind === "route" ? entity.path : entity.id;
-}
-var UnknownEntityKindError = class extends Error {
-  kind;
-  constructor(kind) {
-    super(`Unknown entity kind: ${kind}`);
-    this.name = "UnknownEntityKindError";
-    this.kind = kind;
-  }
-};
-var KIND_SET = new Set(ENTITY_KINDS);
-function assertEntityKind(kind) {
-  if (!KIND_SET.has(kind)) throw new UnknownEntityKindError(kind);
-}
-
-// src/shared/entities/registry.ts
-function emptyStore() {
-  return {
-    route: /* @__PURE__ */ new Map(),
-    page: /* @__PURE__ */ new Map(),
-    feature: /* @__PURE__ */ new Map(),
-    widget: /* @__PURE__ */ new Map(),
-    region: /* @__PURE__ */ new Map(),
-    element: /* @__PURE__ */ new Map(),
-    primitive: /* @__PURE__ */ new Map(),
-    flow: /* @__PURE__ */ new Map()
-  };
-}
-function computeFlowIds(flows, targetId) {
-  const ids = [];
-  for (const flow of flows) {
-    if (flow.touches.includes(targetId)) ids.push(flow.id);
-  }
-  return ids;
-}
-function freezeEntity(entity, flows) {
-  if (!isMetaKind(entity.kind)) return entity;
-  const withMeta = entity;
-  if (withMeta.meta === void 0) return entity;
-  const computedFlows = Object.freeze(computeFlowIds(flows, withMeta.id));
-  const mergedMeta = { ...withMeta.meta, flows: computedFlows };
-  return { ...entity, meta: Object.freeze(mergedMeta) };
-}
-function createRegistry() {
-  const store = emptyStore();
-  let flowsCache = null;
-  const patternCache = /* @__PURE__ */ new Map();
-  const getFlows = () => {
-    if (flowsCache === null) flowsCache = Array.from(store.flow.values());
-    return flowsCache;
-  };
-  const add = (entity) => {
-    assertEntityKind(entity.kind);
-    const key = entityKey(entity);
-    store[entity.kind].set(key, entity);
-    flowsCache = null;
-    patternCache.delete(entity.kind);
-  };
-  const get = (kind, id) => {
-    assertEntityKind(kind);
-    const raw = store[kind].get(id);
-    if (raw === void 0) return void 0;
-    return freezeEntity(raw, getFlows());
-  };
-  const getPatternsForKind = (kind) => {
-    const cached = patternCache.get(kind);
-    if (cached !== void 0) return cached;
-    const patterns = [];
-    for (const [key, entity] of store[kind]) {
-      if (key.includes("*")) {
-        const segments = key.split("*");
-        patterns.push({
-          segments,
-          staticLength: segments.reduce((n, s) => n + s.length, 0),
-          entity
-        });
-      }
-    }
-    patternCache.set(
-      kind,
-      patterns
-    );
-    return patterns;
-  };
-  const matchesSegments = (segments, id) => {
-    const first = segments[0];
-    const last = segments[segments.length - 1];
-    if (!id.startsWith(first)) return false;
-    let pos = first.length;
-    for (let i = 1; i < segments.length - 1; i++) {
-      const idx = id.indexOf(segments[i], pos);
-      if (idx === -1) return false;
-      pos = idx + segments[i].length;
-    }
-    return id.endsWith(last) && id.length - last.length >= pos;
-  };
-  const matchPattern = (kind, id) => {
-    assertEntityKind(kind);
-    const patterns = getPatternsForKind(kind);
-    if (patterns.length === 0) return void 0;
-    let best;
-    for (const entry of patterns) {
-      if (matchesSegments(entry.segments, id) && (best === void 0 || entry.staticLength > best.staticLength)) {
-        best = entry;
-      }
-    }
-    if (best === void 0) return void 0;
-    return freezeEntity(best.entity, getFlows());
-  };
-  const list = (kind) => {
-    assertEntityKind(kind);
-    const flows = getFlows();
-    return Array.from(
-      store[kind].values(),
-      (e) => freezeEntity(e, flows)
-    );
-  };
-  const allEntities = function* () {
-    for (const kind of Object.keys(store)) {
-      for (const entity of store[kind].values()) {
-        yield entity;
-      }
-    }
-  };
-  const query = (predicate) => {
-    const flows = getFlows();
-    const result = [];
-    for (const entity of allEntities()) {
-      if (predicate(entity)) result.push(freezeEntity(entity, flows));
-    }
-    return result;
-  };
-  const byScope = (scope) => query(
-    (entity) => "scopes" in entity && Array.isArray(entity.scopes) && entity.scopes.includes(scope)
-  );
-  const touchedBy = (flowId) => {
-    const flow = store.flow.get(flowId);
-    if (flow === void 0) return [];
-    const ids = new Set(flow.touches);
-    return query((entity) => {
-      if (!isMetaEntity(entity)) return false;
-      return ids.has(entity.id);
+    if (!source || source.type !== "Literal") continue;
+    if (typeof source.value !== "string") continue;
+    out2.push({
+      specifier: source.value,
+      line: parsed.lineAt(stmt.start),
+      span: { start: stmt.start, end: stmt.end },
+      isTypeOnly,
+      names
     });
-  };
-  const reports = /* @__PURE__ */ new Map();
-  const reportsCbs = /* @__PURE__ */ new Set();
-  const setReports = (kind, id, records) => {
-    reports.set(`${kind}:${id}`, records);
-    for (const cb of reportsCbs) cb();
-  };
-  const getReports = (kind, id) => reports.get(`${kind}:${id}`) ?? [];
-  const listReportKeys = () => Array.from(reports.keys());
-  const onReportsChange = (cb) => {
-    reportsCbs.add(cb);
-    return () => reportsCbs.delete(cb);
-  };
-  return {
-    add,
-    get,
-    matchPattern,
-    list,
-    query,
-    byScope,
-    touchedBy,
-    setReports,
-    getReports,
-    listReportKeys,
-    onReportsChange
-  };
+  }
+  return out2;
 }
 
+// src/scanner/scan/resolve.ts
+var path4 = __toESM(require("path"), 1);
+
 // src/scanner/scan/routes.ts
 var PAGE_BASENAME = /^page\.(tsx|ts|jsx|js|mjs|cjs)$/;
 var PAGES_ROUTER_BASENAME = /\.(tsx|ts|jsx|js|mjs|cjs)$/;
@@ -1802,6 +1982,18 @@ function buildMetaFromExport(exp) {
   if (exp.acceptance?.length) meta.acceptance = exp.acceptance;
   if (exp.features?.length) meta.features = exp.features;
   if (exp.widgets?.length) meta.widgets = exp.widgets;
+  if (exp.states?.length) {
+    meta.states = exp.states.map((s) => ({
+      name: s.name,
+      ...s.kind ? { kind: s.kind } : {},
+      ...s.acceptance?.length ? { acceptance: s.acceptance } : {},
+      ...s.description ? { description: s.description } : {}
+    }));
+  }
+  if (exp.capture === false) meta.capture = false;
+  if (exp.waivers && Object.keys(exp.waivers).length > 0) {
+    meta.waivers = exp.waivers;
+  }
   return Object.keys(meta).length > 0 ? meta : void 0;
 }
 function resolve2(ctx) {
@@ -2221,6 +2413,297 @@ function dedupe(arr) {
 
 // src/scanner/scan/audit.ts
 var path5 = __toESM(require("path"), 1);
+
+// src/scanner/scan/page-coverage.ts
+function compileRoute(pattern) {
+  const segs = pattern.split("/").filter(Boolean);
+  let specificity = 0;
+  const optionalTail = segs.length > 0 && /^\[\[\.{3}.+\]\]$/.test(segs[segs.length - 1]);
+  const effective = optionalTail ? segs.slice(0, -1) : segs;
+  const parts = effective.map((seg) => {
+    const catchAll = /^\[\.{3}.+\]$/.test(seg);
+    const dynamic = /^\[.+\]$/.test(seg);
+    if (catchAll) return "(?:[^/]+)(?:/[^/]+)*";
+    if (dynamic) return "[^/]+";
+    specificity++;
+    return seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  });
+  let body = parts.length === 0 ? "" : "/" + parts.join("/");
+  if (optionalTail) body += "(?:/[^/]+)*";
+  if (body === "") body = "/";
+  const re = new RegExp(`^${body}/?$`);
+  return { test: (url) => re.test(url), specificity };
+}
+function matchUrlToRoute(url, routePaths) {
+  const path12 = stripQuery(url);
+  let best = null;
+  for (const rp of routePaths) {
+    const { test, specificity } = compileRoute(rp);
+    if (!test(path12)) continue;
+    if (!best || specificity > best.specificity)
+      best = { path: rp, specificity };
+  }
+  return best?.path ?? null;
+}
+function stripQuery(url) {
+  const q = url.indexOf("?");
+  const h = url.indexOf("#");
+  let end = url.length;
+  if (q !== -1) end = Math.min(end, q);
+  if (h !== -1) end = Math.min(end, h);
+  return url.slice(0, end);
+}
+function routeForCapture(c, routes, routePaths) {
+  if (c.route && routePaths.includes(c.route)) return c.route;
+  if (c.url) {
+    const m = matchUrlToRoute(c.url, routePaths);
+    if (m) return m;
+  }
+  if (c.kind === "page") {
+    const r = routes.find((r2) => r2.page === c.entity);
+    if (r) return r.path;
+  }
+  return null;
+}
+function checkPageCoverage(registry, manifest, baseline) {
+  const routes = registry.list("route");
+  if (routes.length === 0) return [];
+  const routePaths = routes.map((r) => r.path);
+  const captured = manifest.captured ?? [];
+  const optedOut = /* @__PURE__ */ new Set();
+  for (const r of routes) {
+    const page = registry.get("page", r.page);
+    if (page?.meta?.capture === false) optedOut.add(r.path);
+  }
+  const covered = /* @__PURE__ */ new Set();
+  for (const c of captured) {
+    const route = routeForCapture(c, routes, routePaths);
+    if (route) covered.add(route);
+  }
+  const baselineSet = new Set(baseline?.uncapturedPages ?? []);
+  const diagnostics = [];
+  for (const r of routes) {
+    if (covered.has(r.path) || optedOut.has(r.path)) continue;
+    const loc = registry.get("page", r.page)?.loc;
+    if (baselineSet.has(r.path)) {
+      diagnostics.push({
+        code: "page-backlog",
+        severity: "info",
+        message: `route "${r.path}" has no visual-states capture (acknowledged backlog)`,
+        file: loc?.file,
+        line: loc?.line,
+        hint: `Capture it (drive the route in a states spec) and it drops off the baseline, or opt it out with \`export const uidex = { page: "${r.page}", capture: false }\`.`
+      });
+      continue;
+    }
+    diagnostics.push({
+      code: "page-no-capture",
+      severity: "error",
+      message: `route "${r.path}" has no visual-states capture and is not accounted for`,
+      file: loc?.file,
+      line: loc?.line,
+      entity: { kind: "route", id: r.path },
+      hint: `Capture the route in a states spec, opt it out with \`export const uidex = { page: "${r.page}", capture: false }\`, or grandfather it as acknowledged backlog with \`uidex scan --update-baseline\` (the baseline change lands in the diff for review).`
+    });
+  }
+  for (const b of baselineSet) {
+    if (!routePaths.includes(b)) {
+      diagnostics.push({
+        code: "stale-page-baseline",
+        severity: "warning",
+        message: `coverage baseline lists "${b}", which is not a route in the registry`,
+        hint: `Remove it from the baseline (\`uidex scan --update-baseline\`); the route no longer exists.`
+      });
+    } else if (covered.has(b) || optedOut.has(b)) {
+      diagnostics.push({
+        code: "page-captured",
+        severity: "warning",
+        message: `route "${b}" is now captured but is still in the coverage baseline`,
+        hint: `Prune it with \`uidex scan --update-baseline\` so the backlog reflects reality.`
+      });
+    }
+  }
+  return diagnostics;
+}
+function computePageBaseline(registry, manifest) {
+  const uncaptured = [];
+  for (const d of checkPageCoverage(registry, manifest, {
+    uncapturedPages: []
+  })) {
+    if (d.code === "page-no-capture" && d.entity) uncaptured.push(d.entity.id);
+  }
+  return { uncapturedPages: uncaptured.sort() };
+}
+
+// src/scanner/scan/state-coverage.ts
+var STATE_KINDS2 = ["page", "feature", "widget"];
+function declaredStateEntities(registry) {
+  const out2 = [];
+  for (const kind of STATE_KINDS2) {
+    for (const e of registry.list(kind)) {
+      const states = e.meta?.states;
+      if (!states || states.length === 0) continue;
+      out2.push({
+        kind,
+        id: e.id,
+        states: states.map((s) => s.name),
+        loc: e.loc
+      });
+    }
+  }
+  return out2;
+}
+function captureMatchesEntity(cap, ent) {
+  if (cap.entity !== ent.id) return false;
+  return cap.kind === void 0 || cap.kind === ent.kind;
+}
+function checkStateCoverage(registry, manifest) {
+  const diagnostics = [];
+  const declared = declaredStateEntities(registry);
+  const captured = manifest.captured ?? [];
+  for (const ent of declared) {
+    for (const state of ent.states) {
+      const hit = captured.some(
+        (c) => captureMatchesEntity(c, ent) && c.state === state
+      );
+      if (hit) continue;
+      diagnostics.push({
+        code: "missing-state-capture",
+        severity: "warning",
+        message: `${ent.kind} "${ent.id}" declares state "${state}" but no capture produced it`,
+        file: ent.loc?.file,
+        line: ent.loc?.line,
+        entity: { kind: ent.kind, id: ent.id },
+        hint: `Add a capture for "${ent.id}/${state}" to the states matrix, or remove the state from \`export const uidex = { states: [...] }\` if it no longer exists.`
+      });
+    }
+  }
+  for (const cap of captured) {
+    const candidates = declared.filter((ent2) => captureMatchesEntity(cap, ent2));
+    if (candidates.length === 0) continue;
+    const declaredSomewhere = candidates.some(
+      (ent2) => ent2.states.includes(cap.state)
+    );
+    if (declaredSomewhere) continue;
+    const ent = candidates[0];
+    diagnostics.push({
+      code: "orphan-state-capture",
+      severity: "warning",
+      message: `Capture produced state "${cap.state}" for ${ent.kind} "${ent.id}", which is not in its declared states [${ent.states.join(", ")}]`,
+      file: ent.loc?.file,
+      line: ent.loc?.line,
+      entity: { kind: ent.kind, id: ent.id },
+      hint: `Declare "${cap.state}" in \`export const uidex = { states: [...] }\` for "${ent.id}", or rename the capture to a declared state.`
+    });
+  }
+  return diagnostics;
+}
+
+// src/scanner/scan/state-matrix.ts
+var CORE_KINDS = CORE_STATE_KINDS;
+var STATE_ENTITY_KINDS = ["page", "feature", "widget"];
+function resolveMatrixKind(registry, c) {
+  if (c.stateKind) return c.stateKind;
+  for (const kind of STATE_ENTITY_KINDS) {
+    const declared = registry.get(kind, c.entity)?.meta?.states?.find((s) => s.name === c.state)?.kind;
+    if (declared) return declared;
+  }
+  return CORE_KINDS.includes(c.state) ? c.state : "variant";
+}
+function coreKindsByRoute(registry, manifest) {
+  const routes = registry.list("route");
+  const routePaths = routes.map((r) => r.path);
+  const byRoute = /* @__PURE__ */ new Map();
+  for (const c of manifest.captured ?? []) {
+    const route = routeForCapture(c, routes, routePaths);
+    if (!route) continue;
+    if (!byRoute.has(route)) byRoute.set(route, /* @__PURE__ */ new Set());
+    const kind = resolveMatrixKind(registry, c);
+    if (CORE_KINDS.includes(kind)) byRoute.get(route).add(kind);
+  }
+  return byRoute;
+}
+function pageWaivers(registry, routePage) {
+  return registry.get("page", routePage)?.meta?.waivers ?? {};
+}
+function isOptedOut(registry, page) {
+  return page ? registry.get("page", page)?.meta?.capture === false : false;
+}
+function checkStateMatrix(registry, manifest, baseline) {
+  const routes = registry.list("route");
+  if (routes.length === 0) return [];
+  const pageOf = new Map(routes.map((r) => [r.path, r.page]));
+  const captured = coreKindsByRoute(registry, manifest);
+  const baselined = baseline?.missingKinds ?? {};
+  const diagnostics = [];
+  for (const [route, kinds] of captured) {
+    const page = pageOf.get(route);
+    if (isOptedOut(registry, page)) continue;
+    const waivers = page ? pageWaivers(registry, page) : {};
+    const loc = page ? registry.get("page", page)?.loc : void 0;
+    const baselinedKinds = new Set(baselined[route] ?? []);
+    for (const kind of CORE_KINDS) {
+      if (kinds.has(kind)) continue;
+      if (waivers[kind]) continue;
+      if (baselinedKinds.has(kind)) {
+        diagnostics.push({
+          code: "matrix-backlog",
+          severity: "info",
+          message: `route "${route}" does not render core kind "${kind}" (acknowledged MISSING_KINDS backlog)`,
+          file: loc?.file,
+          line: loc?.line,
+          hint: `Capture the "${kind}" state for "${route}", waive it (\`waivers: { ${kind}: "why it can't" }\` on the page), or leave it in the baseline.`
+        });
+        continue;
+      }
+      diagnostics.push({
+        code: "core-kind",
+        severity: "error",
+        message: `route "${route}" is captured but never renders core kind "${kind}"`,
+        file: loc?.file,
+        line: loc?.line,
+        entity: { kind: "route", id: route },
+        hint: `Capture the "${kind}" state, or if the route cannot render it add \`export const uidex = { page: "${page}", waivers: { ${kind}: "why it can't" } }\`, or grandfather it via \`uidex scan --update-baseline\` (the baseline change lands in the diff for review).`
+      });
+    }
+  }
+  for (const [route, kinds] of captured) {
+    const page = pageOf.get(route);
+    if (!page || isOptedOut(registry, page)) continue;
+    const waivers = pageWaivers(registry, page);
+    const loc = registry.get("page", page)?.loc;
+    for (const kind of Object.keys(waivers)) {
+      if (kinds.has(kind)) {
+        diagnostics.push({
+          code: "stale-waiver",
+          severity: "warning",
+          message: `page "${page}" waives core kind "${kind}", but route "${route}" does render it`,
+          file: loc?.file,
+          line: loc?.line,
+          entity: { kind: "page", id: page },
+          hint: `Remove the "${kind}" waiver \u2014 the route renders that kind, so the waiver's reason is stale.`
+        });
+      }
+    }
+  }
+  return diagnostics;
+}
+function computeMissingKinds(registry, manifest) {
+  const routes = registry.list("route");
+  const pageOf = new Map(routes.map((r) => [r.path, r.page]));
+  const captured = coreKindsByRoute(registry, manifest);
+  const out2 = {};
+  for (const [route, kinds] of captured) {
+    const page = pageOf.get(route);
+    if (isOptedOut(registry, page)) continue;
+    const waivers = page ? pageWaivers(registry, page) : {};
+    const missing = CORE_KINDS.filter((k) => !kinds.has(k) && !waivers[k]);
+    if (missing.length > 0) out2[route] = missing;
+  }
+  return out2;
+}
+
+// src/scanner/scan/audit.ts
 function audit(opts) {
   const diagnostics = [];
   const { registry, extracted, files, config } = opts;
@@ -2229,6 +2712,9 @@ function audit(opts) {
   const acceptanceEnabled = config.audit?.acceptance ?? true;
   const scopeLeakEnabled = config.audit?.scopeLeak ?? true;
   const coverageEnabled = config.audit?.coverage ?? true;
+  const statesEnabled = config.audit?.states ?? true;
+  const pageCoverageEnabled = config.audit?.pageCoverage ?? true;
+  const stateMatrixEnabled = config.audit?.stateMatrix ?? true;
   if (opts.resolveDiagnostics) diagnostics.push(...opts.resolveDiagnostics);
   for (const ef of extracted) {
     if (ef.diagnostics) diagnostics.push(...ef.diagnostics);
@@ -2262,6 +2748,48 @@ function audit(opts) {
       }
     }
   }
+  if (check && opts.typesGenerated !== void 0) {
+    const outRel = opts.typesOutputPath ?? config.output;
+    const fresh = normalizeForCheck(opts.typesGenerated);
+    if (opts.typesOnDisk === null || opts.typesOnDisk === void 0) {
+      diagnostics.push({
+        code: "gen-missing",
+        severity: "error",
+        message: `Generated file "${outRel}" does not exist on disk; run \`uidex scan\` and commit the result`,
+        file: outRel,
+        hint: "Run `uidex scan` (without --check) to regenerate"
+      });
+    } else if (normalizeForCheck(opts.typesOnDisk) !== fresh) {
+      diagnostics.push({
+        code: "gen-stale",
+        severity: "error",
+        message: `Generated file "${outRel}" is stale`,
+        file: outRel,
+        hint: "Run `uidex scan` (without --check) to regenerate and commit the result"
+      });
+    }
+  }
+  if (check && opts.locsGenerated !== void 0) {
+    const outRel = opts.locsOutputPath ?? config.output;
+    const fresh = normalizeForCheck(opts.locsGenerated);
+    if (opts.locsOnDisk === null || opts.locsOnDisk === void 0) {
+      diagnostics.push({
+        code: "gen-missing",
+        severity: "error",
+        message: `Generated file "${outRel}" does not exist on disk; run \`uidex scan\` and commit the result`,
+        file: outRel,
+        hint: "Run `uidex scan` (without --check) to regenerate"
+      });
+    } else if (normalizeForCheck(opts.locsOnDisk) !== fresh) {
+      diagnostics.push({
+        code: "gen-stale",
+        severity: "error",
+        message: `Generated file "${outRel}" is stale`,
+        file: outRel,
+        hint: "Run `uidex scan` (without --check) to regenerate and commit the result"
+      });
+    }
+  }
   if (lint && acceptanceEnabled) {
     for (const kind of ["widget", "feature", "page"]) {
       for (const e of registry.list(kind)) {
@@ -2521,6 +3049,21 @@ function audit(opts) {
       }
     }
   }
+  if (lint && statesEnabled && opts.capturedStates) {
+    diagnostics.push(...checkStateCoverage(registry, opts.capturedStates));
+  }
+  if (lint && pageCoverageEnabled && opts.capturedStates) {
+    diagnostics.push(
+      ...checkPageCoverage(registry, opts.capturedStates, opts.pageBaseline)
+    );
+  }
+  if (lint && stateMatrixEnabled && opts.capturedStates) {
+    diagnostics.push(
+      ...checkStateMatrix(registry, opts.capturedStates, {
+        missingKinds: opts.pageBaseline?.missingKinds ?? {}
+      })
+    );
+  }
   const summary = {
     errors: diagnostics.filter((d) => d.severity === "error").length,
     warnings: diagnostics.filter((d) => d.severity === "warning").length
@@ -2685,6 +3228,148 @@ function stableReplacer(_key, value) {
 }
 
 // src/scanner/scan/emit.ts
+var AUTHORED_KINDS = /* @__PURE__ */ new Set([
+  "route",
+  "page",
+  "feature",
+  "widget",
+  "primitive",
+  "flow"
+]);
+function internedPayload(entities) {
+  const fileIndex = /* @__PURE__ */ new Map();
+  const files = [];
+  const compact = entities.map((e) => {
+    const loc = e.loc;
+    if (!loc || typeof loc.file !== "string") return e;
+    let idx = fileIndex.get(loc.file);
+    if (idx === void 0) {
+      idx = files.length;
+      files.push(loc.file);
+      fileIndex.set(loc.file, idx);
+    }
+    const rest = { ...loc };
+    delete rest.file;
+    return { ...e, loc: { f: idx, ...rest } };
+  });
+  return {
+    filesDecl: `const files: readonly string[] = ${jsonStable(files)}`,
+    parseExpr: `(JSON.parse(${JSON.stringify(
+      JSON.stringify(compact, replacerSorted)
+    )}) as any[]).map(hydrate)`
+  };
+}
+var HYDRATE_FN = [
+  "function hydrate(e: any): any {",
+  '  if (e.loc && typeof e.loc.f === "number") {',
+  "    const { f, ...rest } = e.loc",
+  "    e.loc = { file: files[f], ...rest }",
+  "  }",
+  "  return e",
+  "}"
+].join("\n");
+function compactMeta(meta) {
+  if (!meta || typeof meta !== "object") return meta;
+  const composes = meta.composes;
+  if (!Array.isArray(composes)) return meta;
+  return {
+    ...meta,
+    composes: composes.map(
+      (c) => c && typeof c === "object" && c.kind === "element" && Object.keys(c).length === 2 && typeof c.id === "string" ? c.id : c
+    )
+  };
+}
+function emitLocsModule(thin, uidexImport) {
+  const kinds = [...new Set(thin.map((e) => e.kind))].sort();
+  const kindIdx = new Map(kinds.map((k, i) => [k, i]));
+  const fileIndex = /* @__PURE__ */ new Map();
+  const files = [];
+  const fi = (f) => {
+    let i = fileIndex.get(f);
+    if (i === void 0) {
+      i = files.length;
+      files.push(f);
+      fileIndex.set(f, i);
+    }
+    return i;
+  };
+  const bare = [];
+  const rich = [];
+  for (const e of thin) {
+    const loc = e.loc;
+    const topOnlyKindIdLoc = Object.keys(e).every(
+      (k) => k === "kind" || k === "id" || k === "loc"
+    );
+    const locOnlyKnown = !!loc && typeof loc.file === "string" && Object.keys(loc).every(
+      (k) => k === "file" || k === "line" || k === "column"
+    );
+    if (topOnlyKindIdLoc && locOnlyKnown) {
+      const row = [
+        kindIdx.get(e.kind),
+        e.id,
+        fi(loc.file)
+      ];
+      if (loc.line != null || loc.column != null)
+        row.push(Number(loc.line ?? 0));
+      if (loc.column != null) row.push(Number(loc.column));
+      bare.push(row);
+    } else {
+      const richEntity = { ...e };
+      if (loc && typeof loc.file === "string") {
+        const { file, ...rest } = loc;
+        richEntity.loc = { f: fi(file), ...rest };
+      }
+      if (richEntity.meta) richEntity.meta = compactMeta(richEntity.meta);
+      rich.push(richEntity);
+    }
+  }
+  const str = (v) => JSON.stringify(JSON.stringify(v, replacerSorted));
+  const l = [];
+  l.push("// THIS FILE IS AUTO-GENERATED BY `uidex scan`. DO NOT EDIT.");
+  l.push(
+    "// Deferred element/region source locations for the inspector's copy-path."
+  );
+  l.push("// @ts-nocheck");
+  l.push("/* eslint-disable */");
+  l.push(`import type { Entity, Registry } from ${JSON.stringify(uidexImport)}`);
+  l.push("");
+  l.push(`const files: readonly string[] = ${jsonStable(files)}`);
+  l.push(`const kinds: readonly string[] = ${jsonStable(kinds)}`);
+  l.push("function loc(fi: number, line?: number, col?: number) {");
+  l.push("  const o: any = { file: files[fi] }");
+  l.push("  if (line) o.line = line");
+  l.push("  if (col) o.column = col");
+  l.push("  return o");
+  l.push("}");
+  l.push(`const bare: any[] = JSON.parse(${str(bare)})`);
+  l.push(`const rich: any[] = JSON.parse(${str(rich)})`);
+  l.push("");
+  l.push(
+    "/** Add the thin element/region entities (source locations) to a registry. */"
+  );
+  l.push("export function loadLocs(target: Registry): Registry {");
+  l.push("  for (const r of bare)");
+  l.push(
+    "    target.add({ kind: kinds[r[0]], id: r[1], loc: loc(r[2], r[3], r[4]) } as Entity)"
+  );
+  l.push("  for (const e of rich) {");
+  l.push("    const out: any = { ...e }");
+  l.push('    if (e.loc && typeof e.loc.f === "number") {');
+  l.push("      const { f, ...rest } = e.loc");
+  l.push("      out.loc = { file: files[f], ...rest }");
+  l.push("    }");
+  l.push("    if (e.meta && Array.isArray(e.meta.composes)) {");
+  l.push(
+    '      out.meta = { ...e.meta, composes: e.meta.composes.map((c: any) => typeof c === "string" ? { id: c, kind: "element" } : c) }'
+  );
+  l.push("    }");
+  l.push("    target.add(out)");
+  l.push("  }");
+  l.push("  return target");
+  l.push("}");
+  l.push("");
+  return l.join("\n");
+}
 function sortById(arr) {
   return [...arr].sort((a, b) => a.id.localeCompare(b.id));
 }
@@ -2710,6 +3395,20 @@ function emitIdUnion(name, ids) {
 ${body}
 `;
 }
+var OPAQUE_ID_UNIONS = /* @__PURE__ */ new Set(["ElementId"]);
+function emitId(name, ids) {
+  if (OPAQUE_ID_UNIONS.has(name)) {
+    return `export type ${name} = string & { readonly __uidex?: ${JSON.stringify(name)} }
+`;
+  }
+  return emitIdUnion(name, ids);
+}
+function dataOutputPath(output) {
+  return output.replace(/\.(d\.ts|ts|tsx|mts|cts|js|mjs|cjs)$/, ".data.$1");
+}
+function locsOutputPath(output) {
+  return output.replace(/\.(d\.ts|ts|tsx|mts|cts|js|mjs|cjs)$/, ".locs.$1");
+}
 function emit(opts) {
   const { registry, gitContext, uidexImport = "uidex" } = opts;
   const routes = [...registry.list("route")].sort(
@@ -2718,112 +3417,131 @@ function emit(opts) {
   const pages = sortById(registry.list("page"));
   const features = sortById(registry.list("feature"));
   const widgets = sortById(registry.list("widget"));
+  const stateNames = /* @__PURE__ */ new Set();
+  for (const e of [...pages, ...features, ...widgets]) {
+    for (const s of e.meta?.states ?? []) stateNames.add(s.name);
+  }
   const regions = sortById(registry.list("region"));
   const elements = sortById(registry.list("element"));
   const primitives = sortById(registry.list("primitive"));
   const flows = sortById(registry.list("flow"));
-  const lines = [];
-  lines.push("// THIS FILE IS AUTO-GENERATED BY `uidex scan`. DO NOT EDIT.");
-  lines.push("/* eslint-disable */");
-  lines.push(`import { createUidex } from ${JSON.stringify(uidexImport)}`);
-  lines.push(
-    `import type { Entity, Registry } from ${JSON.stringify(uidexImport)}`
+  const t = [];
+  t.push("// THIS FILE IS AUTO-GENERATED BY `uidex scan`. DO NOT EDIT.");
+  t.push(
+    "// Types only \u2014 the runtime registry lives in the sibling `.data` module."
   );
-  lines.push("");
-  lines.push("// ---- id unions ----");
-  lines.push(
-    emitIdUnion(
+  t.push("/* eslint-disable */");
+  t.push("");
+  t.push("// ---- id unions ----");
+  t.push(
+    emitId(
       "PageId",
       pages.map((e) => e.id)
     )
   );
-  lines.push(
-    emitIdUnion(
+  t.push(
+    emitId(
       "FeatureId",
       features.map((e) => e.id)
     )
   );
-  lines.push(
-    emitIdUnion(
+  t.push(
+    emitId(
       "WidgetId",
       widgets.map((e) => e.id)
     )
   );
-  lines.push(
-    emitIdUnion(
+  t.push(
+    emitId(
       "RegionId",
       regions.map((e) => e.id)
     )
   );
-  lines.push(
-    emitIdUnion(
+  t.push(
+    emitId(
       "ElementId",
       elements.map((e) => e.id)
     )
   );
-  lines.push(
-    emitIdUnion(
+  t.push(
+    emitId(
       "PrimitiveId",
       primitives.map((e) => e.id)
     )
   );
-  lines.push(
-    emitIdUnion(
+  t.push(
+    emitId(
       "FlowId",
       flows.map((e) => e.id)
     )
   );
-  lines.push(
-    emitIdUnion(
+  t.push(
+    emitId(
       "RouteId",
       routes.map((e) => e.path)
     )
   );
-  lines.push("");
-  lines.push("// ---- authoring-surface shape types ----");
-  lines.push("export namespace Uidex {");
-  lines.push("  export interface Page {");
-  lines.push("    page: PageId | false");
-  lines.push("    name?: string");
-  lines.push("    features?: readonly FeatureId[]");
-  lines.push("    widgets?: readonly WidgetId[]");
-  lines.push("    acceptance?: readonly string[]");
-  lines.push("    description?: string");
-  lines.push("  }");
-  lines.push("  export interface Feature {");
-  lines.push("    feature: FeatureId | false");
-  lines.push("    name?: string");
-  lines.push("    features?: readonly FeatureId[]");
-  lines.push("    acceptance?: readonly string[]");
-  lines.push("    description?: string");
-  lines.push("  }");
-  lines.push("  export interface Primitive {");
-  lines.push("    primitive: PrimitiveId");
-  lines.push("    name?: string");
-  lines.push("    description?: string");
-  lines.push("  }");
-  lines.push("  export interface Widget {");
-  lines.push("    widget: WidgetId");
-  lines.push("    name?: string");
-  lines.push("    acceptance?: readonly string[]");
-  lines.push("    description?: string");
-  lines.push("  }");
-  lines.push("  export interface Region {");
-  lines.push("    region: RegionId | false");
-  lines.push("    name?: string");
-  lines.push("    description?: string");
-  lines.push("  }");
-  lines.push("  export interface Flow {");
-  lines.push("    flow: FlowId");
-  lines.push("    name?: string");
-  lines.push("    description?: string");
-  lines.push("  }");
-  lines.push("  export interface NotFlow {");
-  lines.push("    notFlow: true");
-  lines.push("  }");
-  lines.push("}");
-  lines.push("");
-  lines.push("// ---- entities ----");
+  t.push(emitId("StateId", [...stateNames]));
+  t.push("");
+  t.push("// ---- authoring-surface shape types ----");
+  t.push("export namespace Uidex {");
+  t.push(
+    '  export type CoreStateKind = "loading" | "empty" | "populated" | "error"'
+  );
+  t.push('  export type StateKind = CoreStateKind | "variant"');
+  t.push("  export interface State {");
+  t.push("    name: string");
+  t.push("    kind?: StateKind");
+  t.push("    acceptance?: readonly string[]");
+  t.push("    description?: string");
+  t.push("  }");
+  t.push("  export type Waivers = Partial<Record<CoreStateKind, string>>");
+  t.push("  export interface Page {");
+  t.push("    page: PageId | false");
+  t.push("    name?: string");
+  t.push("    features?: readonly FeatureId[]");
+  t.push("    widgets?: readonly WidgetId[]");
+  t.push("    acceptance?: readonly string[]");
+  t.push("    states?: readonly (string | State)[]");
+  t.push("    capture?: boolean");
+  t.push("    waivers?: Waivers");
+  t.push("    description?: string");
+  t.push("  }");
+  t.push("  export interface Feature {");
+  t.push("    feature: FeatureId | false");
+  t.push("    name?: string");
+  t.push("    features?: readonly FeatureId[]");
+  t.push("    acceptance?: readonly string[]");
+  t.push("    states?: readonly (string | State)[]");
+  t.push("    description?: string");
+  t.push("  }");
+  t.push("  export interface Primitive {");
+  t.push("    primitive: PrimitiveId");
+  t.push("    name?: string");
+  t.push("    description?: string");
+  t.push("  }");
+  t.push("  export interface Widget {");
+  t.push("    widget: WidgetId");
+  t.push("    name?: string");
+  t.push("    acceptance?: readonly string[]");
+  t.push("    states?: readonly (string | State)[]");
+  t.push("    description?: string");
+  t.push("  }");
+  t.push("  export interface Region {");
+  t.push("    region: RegionId | false");
+  t.push("    name?: string");
+  t.push("    description?: string");
+  t.push("  }");
+  t.push("  export interface Flow {");
+  t.push("    flow: FlowId");
+  t.push("    name?: string");
+  t.push("    description?: string");
+  t.push("  }");
+  t.push("  export interface NotFlow {");
+  t.push("    notFlow: true");
+  t.push("  }");
+  t.push("}");
+  t.push("");
   const allEntities = [
     ...routes,
     ...pages,
@@ -2834,25 +3552,39 @@ function emit(opts) {
     ...primitives,
     ...flows
   ];
-  lines.push(
-    `export const entities: ReadonlyArray<Entity> = ${jsonStable(allEntities)}`
-  );
-  lines.push("");
-  lines.push("// ---- git context ----");
+  const authored = allEntities.filter((e) => AUTHORED_KINDS.has(e.kind));
+  const thin = allEntities.filter((e) => !AUTHORED_KINDS.has(e.kind));
   const gc = gitContext ?? { branch: null, commit: null, pr: null };
-  lines.push(`export const gitContext = ${jsonStable(gc)} as const`);
-  lines.push("");
-  lines.push("// ---- registry factory ----");
-  lines.push("export function loadRegistry(target: Registry): Registry {");
-  lines.push("  for (const entity of entities) target.add(entity)");
-  lines.push("  return target");
-  lines.push("}");
-  lines.push("");
-  lines.push("// ---- preconfigured uidex instance ----");
-  lines.push("export const uidex = createUidex()");
-  lines.push("for (const entity of entities) uidex.registry.add(entity)");
-  lines.push("");
-  return lines.join("\n");
+  const authoredPayload = internedPayload(authored);
+  const d = [];
+  d.push("// THIS FILE IS AUTO-GENERATED BY `uidex scan`. DO NOT EDIT.");
+  d.push(
+    "// Authored-metadata registry. The thin element/region entities (source"
+  );
+  d.push(
+    "// locations only) live in the sibling `.locs` module, loaded lazily."
+  );
+  d.push("// @ts-nocheck");
+  d.push("/* eslint-disable */");
+  d.push(`import { createUidex } from ${JSON.stringify(uidexImport)}`);
+  d.push(`import type { Registry } from ${JSON.stringify(uidexImport)}`);
+  d.push("");
+  d.push(authoredPayload.filesDecl);
+  d.push(HYDRATE_FN);
+  d.push(`export const entities = ${authoredPayload.parseExpr}`);
+  d.push("");
+  d.push(`export const gitContext = ${jsonStable(gc)} as const`);
+  d.push("");
+  d.push("export function loadRegistry(target: Registry): Registry {");
+  d.push("  for (const entity of entities) target.add(entity)");
+  d.push("  return target");
+  d.push("}");
+  d.push("");
+  d.push("export const uidex = createUidex()");
+  d.push("for (const entity of entities) uidex.registry.add(entity)");
+  d.push("");
+  const locs = emitLocsModule(thin, uidexImport);
+  return { types: t.join("\n"), data: d.join("\n"), locs };
 }
 
 // src/scanner/scan/git.ts
@@ -2963,6 +3695,68 @@ function renderSpec(args) {
 // src/scanner/scan/pipeline.ts
 var fs4 = __toESM(require("fs"), 1);
 var path7 = __toESM(require("path"), 1);
+var DEFAULT_STATES_MANIFEST = "uidex-states.json";
+var DEFAULT_COVERAGE_BASELINE = "uidex-coverage-baseline.json";
+function loadPageBaseline(configDir, config) {
+  const rel = config.coverageBaseline ?? DEFAULT_COVERAGE_BASELINE;
+  const abs = path7.resolve(configDir, rel);
+  let raw;
+  try {
+    raw = fs4.readFileSync(abs, "utf8");
+  } catch {
+    return void 0;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || !Array.isArray(parsed.uncapturedPages)) return void 0;
+    const uncapturedPages = parsed.uncapturedPages.filter(
+      (p2) => typeof p2 === "string"
+    );
+    let missingKinds;
+    const mkRaw = parsed.missingKinds;
+    if (mkRaw && typeof mkRaw === "object" && !Array.isArray(mkRaw)) {
+      const mk = {};
+      for (const [route, kinds] of Object.entries(mkRaw)) {
+        if (Array.isArray(kinds)) {
+          mk[route] = kinds.filter((k) => typeof k === "string");
+        }
+      }
+      missingKinds = mk;
+    }
+    return { uncapturedPages, ...missingKinds ? { missingKinds } : {} };
+  } catch {
+    return void 0;
+  }
+}
+function loadCapturedStates(configDir, config) {
+  const rel = config.statesManifest ?? DEFAULT_STATES_MANIFEST;
+  const abs = path7.resolve(configDir, rel);
+  let raw;
+  try {
+    raw = fs4.readFileSync(abs, "utf8");
+  } catch {
+    return void 0;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || !Array.isArray(parsed.captured)) return void 0;
+    const captured = [];
+    for (const entry of parsed.captured) {
+      if (!entry || typeof entry !== "object") continue;
+      const c = entry;
+      if (typeof c.entity !== "string" || typeof c.state !== "string") continue;
+      const rec = { entity: c.entity, state: c.state };
+      if (typeof c.kind === "string") rec.kind = c.kind;
+      if (typeof c.stateKind === "string") rec.stateKind = c.stateKind;
+      if (typeof c.url === "string") rec.url = c.url;
+      if (typeof c.route === "string") rec.route = c.route;
+      captured.push(rec);
+    }
+    return { captured };
+  } catch {
+    return void 0;
+  }
+}
 function runScan(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
   const configs = opts.configs ?? discover({ cwd });
@@ -2989,23 +3783,29 @@ function runOne(dc, opts) {
     flowFiles: extractedFlows
   });
   const gitContext = resolveGitContext({ cwd: configDir });
-  const generated = emit({
+  const emitted = emit({
     registry: resolved.registry,
     gitContext
   });
-  const outputPath = path7.resolve(configDir, config.output);
-  const outputRel = config.output;
-  let existingOnDisk = null;
+  const typesRel = config.output;
+  const typesPath = path7.resolve(configDir, typesRel);
+  const dataRel = dataOutputPath(config.output);
+  const dataPath = path7.resolve(configDir, dataRel);
+  const locsRel = locsOutputPath(config.output);
+  const locsPath = path7.resolve(configDir, locsRel);
+  let typesOnDisk = null;
+  let dataOnDisk = null;
+  let locsOnDisk = null;
   if (opts.check) {
-    try {
-      existingOnDisk = fs4.readFileSync(outputPath, "utf8");
-    } catch {
-      existingOnDisk = null;
-    }
+    typesOnDisk = readOrNull(typesPath);
+    dataOnDisk = readOrNull(dataPath);
+    locsOnDisk = readOrNull(locsPath);
   }
   const hasExtractDiagnostics = [...extracted, ...extractedFlows].some(
     (ef) => (ef.diagnostics?.length ?? 0) > 0
   );
+  const capturedStates = opts.capturedStates ?? loadCapturedStates(configDir, config);
+  const pageBaseline = opts.pageBaseline ?? loadPageBaseline(configDir, config);
   let auditResult;
   if (opts.check || opts.lint || resolved.diagnostics.length > 0 || hasExtractDiagnostics) {
     auditResult = audit({
@@ -3017,9 +3817,20 @@ function runOne(dc, opts) {
       check: opts.check,
       lint: opts.lint,
       resolveDiagnostics: resolved.diagnostics,
-      generated,
-      existingOnDisk,
-      outputPath: outputRel
+      // The entity array (and thus the meaningful drift) lives in the data file,
+      // so the entity-aware gen-stale diff runs against it; the types file gets a
+      // plain content compare (see audit()).
+      generated: emitted.data,
+      existingOnDisk: dataOnDisk,
+      outputPath: dataRel,
+      typesGenerated: emitted.types,
+      typesOnDisk,
+      typesOutputPath: typesRel,
+      locsGenerated: emitted.locs,
+      locsOnDisk,
+      locsOutputPath: locsRel,
+      capturedStates,
+      pageBaseline
     });
   }
   return {
@@ -3028,13 +3839,38 @@ function runOne(dc, opts) {
     registry: resolved.registry,
     gitContext,
     audit: auditResult,
-    generated,
-    outputPath
+    types: {
+      generated: emitted.types,
+      outputPath: typesPath,
+      outputRel: typesRel
+    },
+    data: { generated: emitted.data, outputPath: dataPath, outputRel: dataRel },
+    locs: { generated: emitted.locs, outputPath: locsPath, outputRel: locsRel },
+    capturedStates
   };
 }
+function readOrNull(p2) {
+  try {
+    return fs4.readFileSync(p2, "utf8");
+  } catch {
+    return null;
+  }
+}
+function writeArtifact(artifact) {
+  if (readOrNull(artifact.outputPath) === artifact.generated) return false;
+  fs4.mkdirSync(path7.dirname(artifact.outputPath), { recursive: true });
+  fs4.writeFileSync(artifact.outputPath, artifact.generated, "utf8");
+  return true;
+}
 function writeScanResult(result) {
-  fs4.mkdirSync(path7.dirname(result.outputPath), { recursive: true });
-  fs4.writeFileSync(result.outputPath, result.generated, "utf8");
+  const wroteTypes = writeArtifact(result.types);
+  const wroteData = writeArtifact(result.data);
+  const wroteLocs = writeArtifact(result.locs);
+  return wroteTypes || wroteData || wroteLocs;
+}
+function pageBaselinePath(result) {
+  const rel = result.config.coverageBaseline ?? DEFAULT_COVERAGE_BASELINE;
+  return path7.resolve(result.configDir, rel);
 }
 
 // src/scanner/scan/fix.ts
@@ -3607,16 +4443,13 @@ function helpText2() {
     "  scaffold <widget|page|feature> <id>  Emit a Playwright spec from declared acceptance",
     "  rename <element|widget|region> <old-id> <new-id>  Rename an id everywhere (DOM attr, flows, exports)",
     "  ai <install|uninstall|providers>  Manage AI assistant integrations",
-    "  api <METHOD> <PATH>              Call the uidex API",
-    "  api --list                       Show available API routes",
-    "  api login                        Authenticate via browser",
-    "  api login --token <tok>          Store an auth token directly",
     "",
     "Flags:",
     "  --check               Verify the on-disk gen file matches a fresh scan; exit non-zero on drift (read-only)",
     "  --lint                Run lint diagnostics (missing annotations, scope leak, duplicate ids, coverage)",
     "  --audit               Equivalent to --check --lint (read-only)",
     "  --fix                 Apply machine-generated fixes (add data-uidex to unannotated interactive elements, drop empty names), then rescan and write",
+    "  --update-baseline     Regenerate the page-coverage baseline (uidex-coverage-baseline.json) from the current uncaptured routes",
     "  --json                Emit JSON diagnostics on stdout",
     "  --force               (scaffold) overwrite existing spec",
     ""
@@ -3636,7 +4469,7 @@ function runInit(cwd, w) {
   fs8.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
   w.out(`Created ${configPath}`);
   const gitignorePath = path11.join(cwd, ".gitignore");
-  const entry = "*.gen.ts";
+  const entry = "*.gen.*";
   if (fs8.existsSync(gitignorePath)) {
     const existing = fs8.readFileSync(gitignorePath, "utf8");
     const hasEntry = existing.split("\n").some((line) => line.trim() === entry);
@@ -3659,8 +4492,9 @@ function runInit(cwd, w) {
 }
 function runScanCommand(cwd, flags, w) {
   const fix = Boolean(flags.fix);
-  const check = !fix && Boolean(flags.check || flags.audit);
-  const lint = Boolean(flags.lint || flags.audit || fix);
+  const updateBaseline = Boolean(flags["update-baseline"]);
+  const check = !fix && !updateBaseline && Boolean(flags.check || flags.audit);
+  const lint = Boolean(flags.lint || flags.audit || fix || updateBaseline);
   const asJson = Boolean(flags.json);
   let configs = discover({ cwd });
   if (configs.length === 0) {
@@ -3679,8 +4513,33 @@ function runScanCommand(cwd, flags, w) {
     configs = discover({ cwd });
   }
   const results = runScan({ cwd, check, lint, configs });
+  const artifacts = results.flatMap((r) => [r.types, r.data, r.locs]);
+  const wrote = /* @__PURE__ */ new Set();
   if (!check) {
-    for (const r of results) writeScanResult(r);
+    for (const a of artifacts) {
+      if (writeArtifact(a)) wrote.add(a);
+    }
+  }
+  if (updateBaseline) {
+    for (const r of results) {
+      const manifest = r.capturedStates ?? { captured: [] };
+      const pageBaseline = computePageBaseline(r.registry, manifest);
+      const missingKinds = computeMissingKinds(r.registry, manifest);
+      const baseline = {
+        ...pageBaseline,
+        ...Object.keys(missingKinds).length > 0 ? { missingKinds } : {}
+      };
+      const p2 = pageBaselinePath(r);
+      fs8.writeFileSync(p2, JSON.stringify(baseline, null, 2) + "\n");
+      const kindGaps = Object.values(missingKinds).reduce(
+        (n, ks) => n + ks.length,
+        0
+      );
+      w.out(
+        `Wrote ${p2} \u2014 ${baseline.uncapturedPages.length} uncaptured page(s), ${kindGaps} missing core-kind(s) baselined`
+      );
+    }
+    return w.result(0);
   }
   const allDiagnostics = results.flatMap((r) => r.audit?.diagnostics ?? []);
   const summary = results.reduce(
@@ -3708,10 +4567,14 @@ function runScanCommand(cwd, flags, w) {
       );
     }
     for (const r of results) {
-      if (check) {
-        w.out(`Checked ${r.outputPath}`);
-      } else {
-        w.out(`Wrote ${r.outputPath}`);
+      for (const art of [r.types, r.data, r.locs]) {
+        if (check) {
+          w.out(`Checked ${art.outputPath}`);
+        } else if (wrote.has(art)) {
+          w.out(`Wrote ${art.outputPath}`);
+        } else {
+          w.out(`Unchanged ${art.outputPath}`);
+        }
       }
       for (const d of r.audit?.diagnostics ?? []) {
         const loc = d.file ? `${d.file}${d.line ? `:${d.line}` : ""}` : "";
@@ -3820,12 +4683,21 @@ function createWriter() {
   DEFAULT_CONVENTIONS,
   applyFixes,
   audit,
+  checkPageCoverage,
+  checkStateCoverage,
+  checkStateMatrix,
+  compileRoute,
+  computeMissingKinds,
+  computePageBaseline,
   detectRoutes,
   discover,
   emit,
   extract,
   extractUidexExports,
   globToRegExp,
+  loadPageBaseline,
+  matchUrlToRoute,
+  pageBaselinePath,
   parseConfig,
   pathToId,
   renameEntity,