uidex 0.6.0 → 0.8.0

package/dist/scan/index.js

@@ -3,7 +3,6 @@ import * as fs from "fs";
 import * as path from "path";
 
 // src/scanner/scan/config.ts
-var DEFAULT_TYPE_MODE = "strict";
 var WELL_KNOWN_FILES = {
   page: "uidex.page.ts",
   feature: "uidex.feature.ts"
@@ -28,11 +27,11 @@ var ALLOWED_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
   "exclude",
   "output",
   "flows",
-  "typeMode",
   "audit",
-  "conventions"
+  "conventions",
+  "statesManifest",
+  "coverageBaseline"
 ]);
-var ALLOWED_TYPE_MODES = /* @__PURE__ */ new Set(["strict", "loose"]);
 var ALLOWED_SOURCE_KEYS = /* @__PURE__ */ new Set(["rootDir", "include", "exclude", "prefix"]);
 var ALLOWED_CONVENTIONS_KEYS = /* @__PURE__ */ new Set([
   "primitives",
@@ -41,18 +40,25 @@ 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}`);
 }
-function assertObject(value, path10) {
+function assertObject(value, path12) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    fail(`${path10} must be an object`);
+    fail(`${path12} must be an object`);
   }
 }
-function assertStringArray(value, path10) {
+function assertStringArray(value, path12) {
   if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) {
-    fail(`${path10} must be a string[]`);
+    fail(`${path12} must be a string[]`);
   }
 }
 function validateConfig(raw) {
@@ -100,10 +106,11 @@ function validateConfig(raw) {
   }
   if (raw.exclude !== void 0) assertStringArray(raw.exclude, `exclude`);
   if (raw.flows !== void 0) assertStringArray(raw.flows, `flows`);
-  if (raw.typeMode !== void 0) {
-    if (typeof raw.typeMode !== "string" || !ALLOWED_TYPE_MODES.has(raw.typeMode)) {
-      fail(`"typeMode" must be "strict" or "loose"`);
-    }
+  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");
@@ -143,9 +150,10 @@ function validateConfig(raw) {
     exclude: raw.exclude,
     output: raw.output,
     flows: raw.flows,
-    typeMode: raw.typeMode ?? DEFAULT_TYPE_MODE,
     audit: raw.audit,
-    conventions: raw.conventions
+    conventions: raw.conventions,
+    statesManifest: raw.statesManifest,
+    coverageBaseline: raw.coverageBaseline
   };
 }
 function parseConfig(json) {
@@ -234,7 +242,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",
@@ -350,6 +363,285 @@ function* walkDir(root, dir) {
   }
 }
 
+// src/scanner/scan/ast.ts
+import * as path3 from "path";
+import { parseSync } from "oxc-parser";
+function langFor(sourcePath) {
+  switch (path3.extname(sourcePath)) {
+    case ".tsx":
+      return "tsx";
+    case ".ts":
+    case ".mts":
+    case ".cts":
+      return "ts";
+    default:
+      return "jsx";
+  }
+}
+function makeLineAt(content) {
+  const starts = [0];
+  for (let i = 0; i < content.length; i++) {
+    if (content[i] === "\n") starts.push(i + 1);
+  }
+  return (offset) => {
+    let lo = 0;
+    let hi = starts.length - 1;
+    while (lo < hi) {
+      const mid = lo + hi + 1 >> 1;
+      if (starts[mid] <= offset) lo = mid;
+      else hi = mid - 1;
+    }
+    return lo + 1;
+  };
+}
+function parseSource(file) {
+  const lineAt = makeLineAt(file.content);
+  try {
+    const result = parseSync(file.sourcePath, file.content, {
+      lang: langFor(file.sourcePath),
+      sourceType: "module"
+    });
+    return {
+      program: result.program,
+      hasErrors: result.errors.length > 0,
+      comments: result.comments ?? [],
+      lineAt
+    };
+  } catch {
+    return { program: null, hasErrors: true, comments: [], lineAt };
+  }
+}
+function isNode(value) {
+  return typeof value === "object" && value !== null && typeof value.type === "string";
+}
+function walkAst(root, visit) {
+  if (!isNode(root)) return;
+  if (visit(root) === false) return;
+  for (const key of Object.keys(root)) {
+    if (key === "type" || key === "start" || key === "end") continue;
+    const value = root[key];
+    if (Array.isArray(value)) {
+      for (const item of value) walkAst(item, visit);
+    } else if (isNode(value)) {
+      walkAst(value, visit);
+    }
+  }
+}
+function unwrapTsExpression(expr) {
+  let node = expr;
+  for (; ; ) {
+    switch (node.type) {
+      case "TSAsExpression":
+      case "TSSatisfiesExpression":
+      case "TSNonNullExpression":
+      case "TSTypeAssertion":
+      case "ParenthesizedExpression": {
+        const inner = node.expression;
+        if (!isNode(inner)) return node;
+        node = inner;
+        break;
+      }
+      default:
+        return node;
+    }
+  }
+}
+
+// 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",
@@ -367,26 +659,51 @@ 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",
   "primitive",
   "region"
 ]);
+var SATISFIES_NAMES = {
+  page: "Page",
+  feature: "Feature",
+  primitive: "Primitive",
+  widget: "Widget",
+  region: "Region",
+  flow: "Flow",
+  notFlow: "NotFlow"
+};
+var KNOWN_SATISFIES = new Set(Object.values(SATISFIES_NAMES));
 var ExtractError = class extends Error {
   code;
   hint;
@@ -398,649 +715,285 @@ var ExtractError = class extends Error {
     this.hint = hint;
   }
 };
-function extractUidexExports(file) {
+function extractUidexExports(file, parsed) {
   const exports = [];
   const diagnostics = [];
   const { content, displayPath } = file;
-  for (const header of findExportHeaders(content)) {
-    try {
-      const value = parseExpression(content, header.exprStart);
-      const metadata = buildMetadata(
-        value,
-        displayPath,
-        header.headerPos,
-        diagnostics
-      );
-      exports.push(metadata);
-    } catch (e) {
-      if (e instanceof ExtractError) {
-        diagnostics.push({
-          code: e.code,
-          severity: "error",
-          message: e.message,
-          file: displayPath,
-          line: e.pos.line,
-          hint: e.hint
-        });
-      } else {
-        throw e;
+  const p2 = parsed ?? parseSource(file);
+  if (p2.program === null) return { exports, diagnostics };
+  for (const stmt of p2.program.body) {
+    if (stmt.type !== "ExportNamedDeclaration") continue;
+    const decl = stmt.declaration;
+    if (!isNode2(decl) || decl.type !== "VariableDeclaration") continue;
+    if (decl.kind !== "const") continue;
+    for (const declarator of decl.declarations ?? []) {
+      const id = declarator.id;
+      if (!id || id.type !== "Identifier" || String(id.name) !== "uidex") {
+        continue;
+      }
+      const headerPos = posAt(content, stmt.start, p2);
+      try {
+        const init = declarator.init;
+        if (!isNode2(init)) {
+          throw new ExtractError(
+            "uidex-export-invalid-literal",
+            "`export const uidex` must be assigned an object literal.",
+            headerPos
+          );
+        }
+        const value = toLitValue(unwrapTsExpression(init), content, p2);
+        const metadata = buildMetadata(
+          value,
+          displayPath,
+          file.sourcePath,
+          headerPos,
+          diagnostics
+        );
+        metadata.span = statementSpan(stmt, content);
+        checkSatisfies(init, metadata, displayPath, p2, diagnostics);
+        exports.push(metadata);
+      } catch (e) {
+        if (e instanceof ExtractError) {
+          diagnostics.push({
+            code: e.code,
+            severity: "error",
+            message: e.message,
+            file: displayPath,
+            line: e.pos.line,
+            hint: e.hint
+          });
+        } else {
+          throw e;
+        }
       }
     }
   }
   return { exports, diagnostics };
 }
-var HEADER_RE = /(?:^|\n)[\t ]*export\s+const\s+uidex\b(?:\s*:\s*[^=\n]+?)?\s*=\s*/g;
-function findExportHeaders(content) {
-  const out2 = [];
-  HEADER_RE.lastIndex = 0;
-  let m;
-  while ((m = HEADER_RE.exec(content)) !== null) {
-    const leadingNewline = m[0].startsWith("\n") ? 1 : 0;
-    const headerOffset = m.index + leadingNewline;
-    const exprStart = m.index + m[0].length;
-    if (isInsideCommentOrString(content, headerOffset)) continue;
-    out2.push({
-      headerPos: posAt(content, headerOffset),
-      exprStart
-    });
-  }
-  return out2;
-}
-function isInsideCommentOrString(content, target) {
-  let i = 0;
-  let inLineComment = false;
-  let inBlockComment = false;
-  let stringDelim = null;
-  let inTemplate = false;
-  let templateDepth = 0;
-  while (i < target) {
-    const c = content[i];
-    const n = content[i + 1];
-    if (inLineComment) {
-      if (c === "\n") inLineComment = false;
-      i++;
-      continue;
+function toLitValue(node, content, p2) {
+  const unwrapped = unwrapTsExpression(node);
+  const pos = posAt(content, unwrapped.start, p2);
+  const span = { start: unwrapped.start, end: unwrapped.end };
+  switch (unwrapped.type) {
+    case "Literal": {
+      const v = unwrapped.value;
+      if (typeof v === "string") return { kind: "string", value: v, pos, span };
+      if (typeof v === "number") {
+        if (!Number.isFinite(v)) {
+          throw new ExtractError(
+            "uidex-export-invalid-literal",
+            `Invalid numeric literal in \`export const uidex\`.`,
+            pos
+          );
+        }
+        return { kind: "number", value: v, pos, span };
+      }
+      if (typeof v === "boolean") {
+        return { kind: "boolean", value: v, pos, span };
+      }
+      if (v === null && unwrapped.raw === "null") {
+        return { kind: "null", pos, span };
+      }
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        `Unsupported literal in \`export const uidex\`; only strings, numbers, booleans, and null are allowed.`,
+        pos
+      );
     }
-    if (inBlockComment) {
-      if (c === "*" && n === "/") {
-        inBlockComment = false;
-        i += 2;
-        continue;
+    case "UnaryExpression": {
+      const arg = unwrapped.argument;
+      if (unwrapped.operator === "-" && isNode2(arg) && arg.type === "Literal" && typeof arg.value === "number") {
+        return { kind: "number", value: -arg.value, pos, span };
       }
-      i++;
-      continue;
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        "Unary expressions are not allowed in `export const uidex`.",
+        pos
+      );
     }
-    if (stringDelim !== null) {
-      if (c === "\\") {
-        i += 2;
-        continue;
+    case "TemplateLiteral": {
+      const expressions = unwrapped.expressions ?? [];
+      if (expressions.length > 0) {
+        throw new ExtractError(
+          "uidex-export-invalid-literal",
+          "Template literal with expression parts is not allowed in `export const uidex`; use a plain string literal.",
+          pos
+        );
       }
-      if (c === stringDelim) stringDelim = null;
-      i++;
-      continue;
+      const quasis = unwrapped.quasis ?? [];
+      const cooked = quasis[0]?.value?.cooked ?? "";
+      return { kind: "string", value: cooked, pos, span };
     }
-    if (inTemplate) {
-      if (c === "\\") {
-        i += 2;
-        continue;
-      }
-      if (c === "$" && n === "{") {
-        templateDepth++;
-        i += 2;
-        continue;
-      }
-      if (c === "`" && templateDepth === 0) {
-        inTemplate = false;
-        i++;
-        continue;
-      }
-      if (templateDepth > 0 && c === "}") {
-        templateDepth--;
-        i++;
-        continue;
+    case "Identifier": {
+      const name = String(unwrapped.name);
+      if (name === "undefined") {
+        throw new ExtractError(
+          "uidex-export-invalid-literal",
+          "`undefined` is not allowed as a value in `export const uidex`; omit the field instead.",
+          pos
+        );
       }
-      i++;
-      continue;
-    }
-    if (c === "/" && n === "/") {
-      inLineComment = true;
-      i += 2;
-      continue;
-    }
-    if (c === "/" && n === "*") {
-      inBlockComment = true;
-      i += 2;
-      continue;
-    }
-    if (c === '"' || c === "'") {
-      stringDelim = c;
-      i++;
-      continue;
-    }
-    if (c === "`") {
-      inTemplate = true;
-      i++;
-      continue;
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        `Identifier reference "${name}" is not allowed in \`export const uidex\`; the right-hand side must be a plain literal.`,
+        pos
+      );
     }
-    i++;
+    case "ObjectExpression":
+      return objectLit(unwrapped, content, p2, pos, span);
+    case "ArrayExpression":
+      return arrayLit(unwrapped, content, p2, pos, span);
+    case "SpreadElement":
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        "Spread (`...`) is not allowed in `export const uidex`; the right-hand side must be a plain literal.",
+        pos
+      );
+    case "CallExpression":
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        "Function calls are not allowed in `export const uidex`; the right-hand side must be a plain literal.",
+        pos
+      );
+    case "ConditionalExpression":
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        "Conditional expressions are not allowed in `export const uidex`; the right-hand side must be a plain literal.",
+        pos
+      );
+    default:
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        `Computed expressions are not allowed in \`export const uidex\`; the right-hand side must be a plain literal.`,
+        pos
+      );
   }
-  return inLineComment || inBlockComment || stringDelim !== null || inTemplate;
 }
-var Tokenizer = class {
-  constructor(src, start) {
-    this.src = src;
-    this.pos = start;
-    let line = 1;
-    let lineStart = 0;
-    for (let i = 0; i < start; i++) {
-      if (src[i] === "\n") {
-        line++;
-        lineStart = i + 1;
-      }
-    }
-    this.line = line;
-    this.lineStart = lineStart;
-  }
-  src;
-  pos;
-  line;
-  lineStart;
-  currentPos() {
-    return {
-      offset: this.pos,
-      line: this.line,
-      column: this.pos - this.lineStart + 1
-    };
-  }
-  advance(n = 1) {
-    for (let i = 0; i < n; i++) {
-      if (this.pos < this.src.length && this.src[this.pos] === "\n") {
-        this.line++;
-        this.lineStart = this.pos + 1;
-      }
-      this.pos++;
-    }
-  }
-  skipTrivia() {
-    while (this.pos < this.src.length) {
-      const c = this.src[this.pos];
-      const n = this.src[this.pos + 1];
-      if (c === " " || c === "	" || c === "\r" || c === "\n") {
-        this.advance();
-        continue;
-      }
-      if (c === "/" && n === "/") {
-        while (this.pos < this.src.length && this.src[this.pos] !== "\n") {
-          this.advance();
-        }
-        continue;
-      }
-      if (c === "/" && n === "*") {
-        this.advance(2);
-        while (this.pos < this.src.length) {
-          if (this.src[this.pos] === "*" && this.src[this.pos + 1] === "/") {
-            this.advance(2);
-            break;
-          }
-          this.advance();
-        }
-        continue;
-      }
-      break;
-    }
-  }
-  next() {
-    this.skipTrivia();
-    if (this.pos >= this.src.length) {
-      return { kind: "eof", value: "", pos: this.currentPos(), end: this.pos };
-    }
-    const pos = this.currentPos();
-    const c = this.src[this.pos];
-    switch (c) {
-      case "{":
-        this.advance();
-        return { kind: "lbrace", value: c, pos, end: this.pos };
-      case "}":
-        this.advance();
-        return { kind: "rbrace", value: c, pos, end: this.pos };
-      case "[":
-        this.advance();
-        return { kind: "lbracket", value: c, pos, end: this.pos };
-      case "]":
-        this.advance();
-        return { kind: "rbracket", value: c, pos, end: this.pos };
-      case "(":
-        this.advance();
-        return { kind: "lparen", value: c, pos, end: this.pos };
-      case ")":
-        this.advance();
-        return { kind: "rparen", value: c, pos, end: this.pos };
-      case ",":
-        this.advance();
-        return { kind: "comma", value: c, pos, end: this.pos };
-      case ":":
-        this.advance();
-        return { kind: "colon", value: c, pos, end: this.pos };
-    }
-    if (c === "." && this.src[this.pos + 1] === "." && this.src[this.pos + 2] === ".") {
-      this.advance(3);
-      return { kind: "spread", value: "...", pos, end: this.pos };
-    }
-    if (c === '"' || c === "'") {
-      return this.readString(pos, c);
-    }
-    if (c === "`") {
-      return this.readTemplate(pos);
-    }
-    if (isDigit(c) || c === "-" && isDigit(this.src[this.pos + 1])) {
-      return this.readNumber(pos);
-    }
-    if (isIdentStart(c)) {
-      return this.readIdent(pos);
-    }
-    this.advance();
-    return { kind: "punct", value: c, pos, end: this.pos };
-  }
-  readString(pos, delim) {
-    this.advance();
-    let value = "";
-    while (this.pos < this.src.length) {
-      const c = this.src[this.pos];
-      if (c === "\\") {
-        const esc = this.src[this.pos + 1];
-        this.advance(2);
-        value += decodeEscape(esc);
-        continue;
-      }
-      if (c === delim) {
-        this.advance();
-        return { kind: "string", value, pos, end: this.pos };
-      }
-      if (c === "\n") {
-        return { kind: "punct", value: delim, pos, end: this.pos };
-      }
-      value += c;
-      this.advance();
-    }
-    return { kind: "punct", value: delim, pos, end: this.pos };
-  }
-  readTemplate(pos) {
-    this.advance();
-    let value = "";
-    let hasExpression = false;
-    while (this.pos < this.src.length) {
-      const c = this.src[this.pos];
-      const n = this.src[this.pos + 1];
-      if (c === "\\") {
-        const esc = this.src[this.pos + 1];
-        this.advance(2);
-        value += decodeEscape(esc);
-        continue;
-      }
-      if (c === "$" && n === "{") {
-        hasExpression = true;
-        this.advance(2);
-        let depth = 1;
-        while (this.pos < this.src.length && depth > 0) {
-          const ch = this.src[this.pos];
-          if (ch === "{") depth++;
-          else if (ch === "}") depth--;
-          this.advance();
-        }
-        continue;
-      }
-      if (c === "`") {
-        this.advance();
-        if (hasExpression) {
-          return { kind: "template", value, pos, end: this.pos };
-        }
-        return { kind: "string", value, pos, end: this.pos };
-      }
-      value += c;
-      this.advance();
-    }
-    return { kind: "template", value, pos, end: this.pos };
-  }
-  readNumber(pos) {
-    const start = this.pos;
-    if (this.src[this.pos] === "-") this.advance();
-    while (this.pos < this.src.length && isDigit(this.src[this.pos])) {
-      this.advance();
-    }
-    if (this.src[this.pos] === ".") {
-      this.advance();
-      while (this.pos < this.src.length && isDigit(this.src[this.pos])) {
-        this.advance();
-      }
-    }
-    if (this.src[this.pos] === "e" || this.src[this.pos] === "E") {
-      this.advance();
-      if (this.src[this.pos] === "+" || this.src[this.pos] === "-") {
-        this.advance();
-      }
-      while (this.pos < this.src.length && isDigit(this.src[this.pos])) {
-        this.advance();
-      }
+function objectLit(node, content, p2, pos, span) {
+  const entries = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const prop of node.properties ?? []) {
+    if (prop.type === "SpreadElement") {
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        "Spread (`...`) is not allowed inside `export const uidex`.",
+        posAt(content, prop.start, p2)
+      );
     }
-    const value = this.src.slice(start, this.pos);
-    return { kind: "number", value, pos, end: this.pos };
-  }
-  readIdent(pos) {
-    const start = this.pos;
-    while (this.pos < this.src.length && isIdentPart(this.src[this.pos])) {
-      this.advance();
+    if (prop.type !== "Property") {
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        "Unexpected member inside `export const uidex` object.",
+        posAt(content, prop.start, p2)
+      );
     }
-    const value = this.src.slice(start, this.pos);
-    return { kind: "ident", value, pos, end: this.pos };
-  }
-};
-function isDigit(c) {
-  return c !== void 0 && c >= "0" && c <= "9";
-}
-function isIdentStart(c) {
-  if (c === void 0) return false;
-  return c >= "a" && c <= "z" || c >= "A" && c <= "Z" || c === "_" || c === "$";
-}
-function isIdentPart(c) {
-  return isIdentStart(c) || isDigit(c);
-}
-function decodeEscape(esc) {
-  switch (esc) {
-    case "n":
-      return "\n";
-    case "t":
-      return "	";
-    case "r":
-      return "\r";
-    case "\\":
-      return "\\";
-    case "'":
-      return "'";
-    case '"':
-      return '"';
-    case "`":
-      return "`";
-    case "0":
-      return "\0";
-    case "b":
-      return "\b";
-    case "f":
-      return "\f";
-    case "v":
-      return "\v";
-    default:
-      return esc ?? "";
-  }
-}
-function parseExpression(content, start) {
-  const tokenizer = new Tokenizer(content, start);
-  const parser = new Parser(tokenizer);
-  const value = parser.parseValue();
-  parser.consumeTrailingAssertions();
-  return value;
-}
-var Parser = class {
-  constructor(tok) {
-    this.tok = tok;
-  }
-  tok;
-  lookahead = null;
-  peek() {
-    if (this.lookahead === null) this.lookahead = this.tok.next();
-    return this.lookahead;
-  }
-  consume() {
-    const t = this.peek();
-    this.lookahead = null;
-    return t;
-  }
-  parseValue() {
-    const t = this.peek();
-    switch (t.kind) {
-      case "lbrace":
-        return this.parseObject();
-      case "lbracket":
-        return this.parseArray();
-      case "string":
-        this.consume();
-        return { kind: "string", value: t.value, pos: t.pos };
-      case "template":
-        throw new ExtractError(
-          "uidex-export-invalid-literal",
-          "Template literal with expression parts is not allowed in `export const uidex`; use a plain string literal.",
-          t.pos
-        );
-      case "number": {
-        this.consume();
-        const n = Number(t.value);
-        if (!Number.isFinite(n)) {
-          throw new ExtractError(
-            "uidex-export-invalid-literal",
-            `Invalid numeric literal "${t.value}" in \`export const uidex\`.`,
-            t.pos
-          );
-        }
-        return { kind: "number", value: n, pos: t.pos };
-      }
-      case "ident":
-        if (t.value === "true" || t.value === "false") {
-          this.consume();
-          return {
-            kind: "boolean",
-            value: t.value === "true",
-            pos: t.pos
-          };
-        }
-        if (t.value === "null") {
-          this.consume();
-          return { kind: "null", pos: t.pos };
-        }
-        if (t.value === "undefined") {
-          throw new ExtractError(
-            "uidex-export-invalid-literal",
-            "`undefined` is not allowed as a value in `export const uidex`; omit the field instead.",
-            t.pos
-          );
-        }
-        throw new ExtractError(
-          "uidex-export-invalid-literal",
-          `Identifier reference "${t.value}" is not allowed in \`export const uidex\`; the right-hand side must be a plain literal.`,
-          t.pos
-        );
-      case "spread":
-        throw new ExtractError(
-          "uidex-export-invalid-literal",
-          "Spread (`...`) is not allowed in `export const uidex`; the right-hand side must be a plain literal.",
-          t.pos
-        );
-      case "lparen":
-        throw new ExtractError(
-          "uidex-export-invalid-literal",
-          "Parenthesised or grouped expressions are not allowed in `export const uidex`.",
-          t.pos
-        );
-      case "punct":
-        throw new ExtractError(
-          "uidex-export-invalid-literal",
-          `Unexpected token "${t.value}" in \`export const uidex\`.`,
-          t.pos
-        );
-      case "eof":
-        throw new ExtractError(
-          "uidex-export-invalid-literal",
-          "Expected a value for `export const uidex` but reached end of file.",
-          t.pos
-        );
-      default:
-        throw new ExtractError(
-          "uidex-export-invalid-literal",
-          `Unexpected token in \`export const uidex\`.`,
-          t.pos
-        );
+    const keyNode = prop.key;
+    const keyPos = posAt(content, keyNode.start, p2);
+    if (prop.shorthand) {
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        `Shorthand property "${String(keyNode.name)}" is not allowed; write "${String(keyNode.name)}: ..." with a literal value.`,
+        keyPos
+      );
     }
-  }
-  parseObject() {
-    const open = this.consume();
-    const entries = [];
-    const seen = /* @__PURE__ */ new Set();
-    while (true) {
-      const t = this.peek();
-      if (t.kind === "rbrace") {
-        this.consume();
-        break;
-      }
-      if (t.kind === "spread") {
-        throw new ExtractError(
-          "uidex-export-invalid-literal",
-          "Spread (`...`) is not allowed inside `export const uidex`.",
-          t.pos
-        );
-      }
-      if (t.kind === "lbracket") {
-        this.consume();
-        const keyTok = this.peek();
-        if (keyTok.kind !== "string") {
-          throw new ExtractError(
-            "uidex-export-invalid-literal",
-            "Computed property keys must be string literals in `export const uidex`.",
-            keyTok.pos
-          );
-        }
-        this.consume();
-        const close = this.peek();
-        if (close.kind !== "rbracket") {
-          throw new ExtractError(
-            "uidex-export-invalid-literal",
-            "Expected `]` after computed property key.",
-            close.pos
-          );
-        }
-        this.consume();
-        const colon = this.peek();
-        if (colon.kind !== "colon") {
-          throw new ExtractError(
-            "uidex-export-invalid-literal",
-            "Expected `:` after computed property key.",
-            colon.pos
-          );
-        }
-        this.consume();
-        const value = this.parseValue();
-        this.recordEntry(entries, seen, keyTok.value, value, keyTok.pos);
-      } else if (t.kind === "ident" || t.kind === "string") {
-        const keyTok = this.consume();
-        const next = this.peek();
-        if (next.kind === "colon") {
-          this.consume();
-          const value = this.parseValue();
-          this.recordEntry(entries, seen, keyTok.value, value, keyTok.pos);
-        } else {
-          throw new ExtractError(
-            "uidex-export-invalid-literal",
-            keyTok.kind === "ident" ? `Shorthand property "${keyTok.value}" is not allowed; write "${keyTok.value}: ..." with a literal value.` : "Expected `:` after property key.",
-            keyTok.pos
-          );
-        }
-      } else if (t.kind === "number") {
-        throw new ExtractError(
-          "uidex-export-invalid-literal",
-          "Numeric property keys are not allowed in `export const uidex`.",
-          t.pos
-        );
-      } else {
+    let key;
+    if (prop.computed) {
+      if (keyNode.type !== "Literal" || typeof keyNode.value !== "string") {
         throw new ExtractError(
           "uidex-export-invalid-literal",
-          `Unexpected token "${t.value}" inside object.`,
-          t.pos
+          "Computed property keys must be string literals in `export const uidex`.",
+          keyPos
         );
       }
-      const after = this.peek();
-      if (after.kind === "comma") {
-        this.consume();
-        continue;
-      }
-      if (after.kind === "rbrace") {
-        this.consume();
-        break;
-      }
+      key = keyNode.value;
+    } else if (keyNode.type === "Identifier") {
+      key = String(keyNode.name);
+    } else if (keyNode.type === "Literal" && typeof keyNode.value === "string") {
+      key = keyNode.value;
+    } else {
       throw new ExtractError(
         "uidex-export-invalid-literal",
-        `Expected \`,\` or \`}\`, got "${after.value}".`,
-        after.pos
+        "Numeric property keys are not allowed in `export const uidex`.",
+        keyPos
       );
     }
-    return { kind: "object", entries, pos: open.pos };
-  }
-  recordEntry(entries, seen, key, value, pos) {
     if (seen.has(key)) {
       throw new ExtractError(
         "uidex-export-duplicate-field",
         `Duplicate field "${key}" in \`export const uidex\`.`,
-        pos
+        keyPos
       );
     }
     seen.add(key);
-    entries.push([key, value]);
-  }
-  parseArray() {
-    const open = this.consume();
-    const items = [];
-    while (true) {
-      const t = this.peek();
-      if (t.kind === "rbracket") {
-        this.consume();
-        break;
-      }
-      if (t.kind === "spread") {
-        throw new ExtractError(
-          "uidex-export-invalid-literal",
-          "Spread (`...`) is not allowed inside `export const uidex`.",
-          t.pos
-        );
-      }
-      const value = this.parseValue();
-      if (value.kind === "object") {
-      }
-      items.push(value);
-      const after = this.peek();
-      if (after.kind === "comma") {
-        this.consume();
-        continue;
-      }
-      if (after.kind === "rbracket") {
-        this.consume();
-        break;
-      }
+    const value = toLitValue(prop.value, content, p2);
+    entries.push({
+      key,
+      value,
+      keyPos,
+      span: removalSpan(content, prop.start, prop.end)
+    });
+  }
+  return { kind: "object", entries, pos, span };
+}
+function arrayLit(node, content, p2, pos, span) {
+  const items = [];
+  for (const el of node.elements ?? []) {
+    if (el === null) {
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        "Array holes are not allowed in `export const uidex`.",
+        pos
+      );
+    }
+    if (el.type === "SpreadElement") {
       throw new ExtractError(
         "uidex-export-invalid-literal",
-        `Expected \`,\` or \`]\`, got "${after.value}".`,
-        after.pos
+        "Spread (`...`) is not allowed inside `export const uidex`.",
+        posAt(content, el.start, p2)
       );
     }
-    return { kind: "array", items, pos: open.pos };
+    items.push(toLitValue(el, content, p2));
   }
-  consumeTrailingAssertions() {
-    const first = this.peek();
-    if (first.kind === "ident" && first.value === "as") {
-      this.consume();
-      const next = this.peek();
-      if (next.kind === "ident" && next.value === "const") {
-        this.consume();
-      } else {
-        throw new ExtractError(
-          "uidex-export-invalid-literal",
-          "Only `as const` is allowed after the `export const uidex` value.",
-          next.pos
-        );
-      }
+  return { kind: "array", items, pos, span };
+}
+function checkSatisfies(init, metadata, file, p2, diagnostics) {
+  let node = init;
+  let satisfiesType;
+  while (isNode2(node)) {
+    if (node.type === "TSSatisfiesExpression") {
+      satisfiesType = node.typeAnnotation;
+      break;
     }
-    const maybeSatisfies = this.peek();
-    if (maybeSatisfies.kind === "ident" && maybeSatisfies.value === "satisfies") {
-      return;
+    if (node.type === "TSAsExpression" || node.type === "TSNonNullExpression" || node.type === "TSTypeAssertion" || node.type === "ParenthesizedExpression") {
+      node = node.expression;
+      continue;
     }
+    break;
   }
-};
-function buildMetadata(value, file, headerPos, diagnostics) {
+  if (!isNode2(satisfiesType) || satisfiesType.type !== "TSTypeReference") return;
+  const typeName = satisfiesType.typeName;
+  if (!isNode2(typeName) || typeName.type !== "TSQualifiedName") return;
+  const left = typeName.left;
+  const right = typeName.right;
+  if (!isNode2(left) || left.type !== "Identifier" || left.name !== "Uidex") {
+    return;
+  }
+  if (!isNode2(right) || right.type !== "Identifier") return;
+  const actual = String(right.name);
+  if (!KNOWN_SATISFIES.has(actual)) return;
+  const discriminator = metadata.notFlow ? "notFlow" : metadata.kind;
+  const expected = SATISFIES_NAMES[discriminator];
+  if (actual === expected) return;
+  diagnostics.push({
+    code: "uidex-export-satisfies-mismatch",
+    severity: "warning",
+    message: `\`export const uidex\` declares kind "${discriminator}" but is annotated \`satisfies Uidex.${actual}\`; expected \`Uidex.${expected}\`.`,
+    file,
+    line: p2.lineAt(satisfiesType.start),
+    hint: `Change the annotation to \`satisfies Uidex.${expected}\` or fix the kind discriminator.`
+  });
+}
+function buildMetadata(value, file, sourcePath, headerPos, diagnostics) {
   if (value.kind !== "object") {
     throw new ExtractError(
       "uidex-export-invalid-literal",
@@ -1049,7 +1002,7 @@ function buildMetadata(value, file, headerPos, diagnostics) {
     );
   }
   const byKey = /* @__PURE__ */ new Map();
-  for (const [k, v] of value.entries) byKey.set(k, v);
+  for (const entry of value.entries) byKey.set(entry.key, entry);
   const presentKinds = KIND_DISCRIMINATORS.filter(
     (k) => byKey.has(k)
   );
@@ -1072,49 +1025,61 @@ function buildMetadata(value, file, headerPos, diagnostics) {
   const discriminator = presentKinds[0];
   const kind = discriminator === "notFlow" ? "flow" : discriminator;
   const allowed = ALLOWED_FIELDS[kind];
-  for (const [k] of value.entries) {
-    if (!allowed.has(k)) {
-      const fieldVal = byKey.get(k);
+  for (const entry of value.entries) {
+    if (!allowed.has(entry.key)) {
       throw new ExtractError(
         "uidex-export-unknown-field",
-        `Unknown field "${k}" in \`export const uidex\` for kind "${kind}". Allowed: ${Array.from(
+        `Unknown field "${entry.key}" in \`export const uidex\` for kind "${kind}". Allowed: ${Array.from(
           allowed
         ).sort().join(", ")}.`,
-        fieldVal.pos
+        entry.value.pos
       );
     }
   }
   const idField = discriminator === "notFlow" ? "flow" : discriminator;
-  const idValue = byKey.get(discriminator);
+  const idValue = byKey.get(discriminator).value;
   let id;
   if (discriminator === "notFlow") {
-    const v = idValue;
-    if (v.kind !== "boolean" || v.value !== true) {
+    if (idValue.kind !== "boolean" || idValue.value !== true) {
       throw new ExtractError(
         "uidex-export-invalid-field",
         "`notFlow` must be `true`.",
-        v.pos
+        idValue.pos
       );
     }
     id = false;
   } else {
     id = readIdField(idValue, kind, idField);
   }
-  const acceptance = readStringArrayField(byKey, "acceptance");
+  const acceptance = readStringArrayField(byKey, "acceptance")?.values;
   const description = readStringField(byKey, "description");
   const name = readStringField(byKey, "name");
   if (name === "") {
-    const pos = byKey.get("name").pos;
+    const entry = byKey.get("name");
     diagnostics.push({
       code: "uidex-export-empty-name",
       severity: "info",
       message: "`name` is an empty string; treating as unset.",
       file,
-      line: pos.line
+      line: entry.value.pos.line,
+      fix: {
+        description: "Remove the empty `name` field",
+        edits: [
+          {
+            path: sourcePath,
+            start: entry.span.start,
+            end: entry.span.end,
+            replacement: ""
+          }
+        ]
+      }
     });
   }
-  const features = kind === "page" || kind === "feature" ? readStringArrayField(byKey, "features") : void 0;
-  const widgets = kind === "page" ? readStringArrayField(byKey, "widgets") : void 0;
+  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",
@@ -1129,9 +1094,24 @@ function buildMetadata(value, file, headerPos, diagnostics) {
   if (name) metadata.name = name;
   if (acceptance) metadata.acceptance = acceptance;
   if (description) metadata.description = description;
-  if (features) metadata.features = features;
-  if (widgets) metadata.widgets = widgets;
+  if (featuresField) {
+    metadata.features = featuresField.values;
+    metadata.featureSpans = featuresField.spans;
+  }
+  if (widgetsField) {
+    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;
+  }
+  const fieldSpans = {};
+  for (const entry of value.entries) fieldSpans[entry.key] = entry.span;
+  metadata.fieldSpans = fieldSpans;
   return metadata;
 }
 function readIdField(value, kind, fieldName) {
@@ -1161,30 +1141,73 @@ 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 v = byKey.get(name);
-  if (!v) return void 0;
-  if (v.kind !== "string") {
+  const entry = byKey.get(name);
+  if (!entry) return void 0;
+  if (entry.value.kind !== "string") {
     throw new ExtractError(
       "uidex-export-invalid-field",
       `\`${name}\` must be a string.`,
-      v.pos
+      entry.value.pos
     );
   }
-  return v.value;
+  return entry.value.value;
 }
 function readStringArrayField(byKey, name) {
-  const v = byKey.get(name);
-  if (!v) return void 0;
-  if (v.kind !== "array") {
+  const entry = byKey.get(name);
+  if (!entry) return void 0;
+  if (entry.value.kind !== "array") {
     throw new ExtractError(
       "uidex-export-invalid-field",
       `\`${name}\` must be an array of strings.`,
-      v.pos
+      entry.value.pos
     );
   }
-  const out2 = [];
-  for (const item of v.items) {
+  const values = [];
+  const spans = [];
+  for (const item of entry.value.items) {
     if (item.kind !== "string") {
       throw new ExtractError(
         "uidex-export-invalid-field",
@@ -1192,498 +1215,606 @@ function readStringArrayField(byKey, name) {
         item.pos
       );
     }
-    out2.push(item.value);
-  }
-  return out2;
-}
-function posAt(content, offset) {
-  let line = 1;
-  let lineStart = 0;
-  for (let i = 0; i < offset && i < content.length; i++) {
-    if (content[i] === "\n") {
-      line++;
-      lineStart = i + 1;
-    }
+    values.push(item.value);
+    spans.push(item.span);
   }
-  return { offset, line, column: offset - lineStart + 1 };
+  return { values, spans };
 }
-
-// src/scanner/scan/jsx-ancestry.ts
-var DATA_ATTR_RE = /\bdata-uidex(?:-(region|widget|primitive))?\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
-var PATTERN_ATTR_RE = /\bdata-uidex(?:-(region|widget|primitive))?\s*=\s*\{\s*`([^`$]+)\$\{/g;
-function parseDataAttrs(tagSource) {
-  if (!tagSource.includes("data-uidex")) return [];
-  const out2 = [];
-  for (const m of tagSource.matchAll(DATA_ATTR_RE)) {
-    const kind = m[1] ?? "element";
-    const id = m[2] ?? m[3];
-    if (id) out2.push({ kind, id });
-  }
-  for (const m of tagSource.matchAll(PATTERN_ATTR_RE)) {
-    const kind = m[1] ?? "element";
-    const prefix = m[2];
-    if (prefix) out2.push({ kind, id: `${prefix}*` });
+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
+    );
   }
-  return out2;
-}
-function collectJSXAncestry(content) {
-  if (!content.includes("data-uidex")) return [];
-  const out2 = [];
-  const ancestors = [];
-  const stack = [];
-  const N = content.length;
-  let i = 0;
-  let line = 1;
-  const advanceLines = (from, to) => {
-    for (let k = from; k < to; k++) {
-      if (content.charCodeAt(k) === 10) line++;
-    }
-  };
-  while (i < N) {
-    const c = content[i];
-    if (c === "\n") {
-      line++;
-      i++;
-      continue;
-    }
-    if (c === "/" && content[i + 1] === "/") {
-      while (i < N && content[i] !== "\n") i++;
-      continue;
-    }
-    if (c === "/" && content[i + 1] === "*") {
-      const end = content.indexOf("*/", i + 2);
-      const next = end === -1 ? N : end + 2;
-      advanceLines(i, next);
-      i = next;
-      continue;
-    }
-    if (c === '"' || c === "'") {
-      const next = skipString(content, i, c);
-      advanceLines(i, next);
-      i = next;
-      continue;
-    }
-    if (c === "`") {
-      const next = skipTemplate(content, i);
-      advanceLines(i, next);
-      i = next;
-      continue;
-    }
-    if (c === "<") {
-      const nextCh = content[i + 1];
-      if (nextCh === "/") {
-        const end = content.indexOf(">", i);
-        if (end === -1) break;
-        const tagName = content.slice(i + 2, end).match(/^\s*([\w.-]*)/)?.[1] ?? "";
-        if (tagName) {
-          for (let k = stack.length - 1; k >= 0; k--) {
-            if (stack[k].tagName === tagName) {
-              for (let j = stack.length - 1; j >= k; j--) {
-                ancestors.length -= stack[j].pushed;
-              }
-              stack.length = k;
-              break;
-            }
-          }
+  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
+          );
         }
-        advanceLines(i, end + 1);
-        i = end + 1;
-        continue;
       }
-      if (nextCh && /[A-Za-z_]/.test(nextCh)) {
-        const end = findTagEnd(content, i + 1);
-        if (end === -1) break;
-        const tagSource = content.slice(i, end + 1);
-        const tagName = tagSource.match(/^<\s*([\w.-]*)/)?.[1] ?? "";
-        const isSelf = content[end - 1] === "/";
-        if (tagName) {
-          const attrs = parseDataAttrs(tagSource);
-          if (attrs.length > 0) {
-            const snapshot = ancestors.slice();
-            for (const a of attrs) {
-              out2.push({ kind: a.kind, id: a.id, line, ancestors: snapshot });
-            }
-          }
-          if (!isSelf) {
-            for (const a of attrs) ancestors.push(a);
-            stack.push({ tagName, pushed: attrs.length });
-          }
-        }
-        advanceLines(i, end + 1);
-        i = end + 1;
-        continue;
+      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
+        );
       }
-    }
-    i++;
-  }
-  return out2;
-}
-function skipString(content, start, quote) {
-  const N = content.length;
-  let i = start + 1;
-  while (i < N) {
-    const c = content[i];
-    if (c === "\\") {
-      i += 2;
-      continue;
-    }
-    if (c === quote) return i + 1;
-    i++;
-  }
-  return N;
-}
-function skipTemplate(content, start) {
-  const N = content.length;
-  let i = start + 1;
-  while (i < N) {
-    const c = content[i];
-    if (c === "\\") {
-      i += 2;
-      continue;
-    }
-    if (c === "`") return i + 1;
-    if (c === "$" && content[i + 1] === "{") {
-      i += 2;
-      let depth = 1;
-      while (i < N && depth > 0) {
-        const cj = content[i];
-        if (cj === '"' || cj === "'") {
-          i = skipString(content, i, cj);
-          continue;
-        }
-        if (cj === "`") {
-          i = skipTemplate(content, i);
-          continue;
+      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
+          );
         }
-        if (cj === "{") depth++;
-        else if (cj === "}") depth--;
-        i++;
+        state.kind = kind;
       }
-      continue;
-    }
-    i++;
-  }
-  return N;
-}
-function findTagEnd(content, start) {
-  const N = content.length;
-  let i = start;
-  while (i < N) {
-    const c = content[i];
-    if (c === '"' || c === "'") {
-      i = skipString(content, i, c);
-      continue;
+      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 (c === "`") {
-      i = skipTemplate(content, i);
-      continue;
+    if (state.name.length === 0) {
+      throw new ExtractError(
+        "uidex-export-invalid-field",
+        "A `states` entry has an empty `name`.",
+        item.pos
+      );
     }
-    if (c === "{") {
-      let depth = 1;
-      i++;
-      while (i < N && depth > 0) {
-        const cj = content[i];
-        if (cj === '"' || cj === "'") {
-          i = skipString(content, i, cj);
-          continue;
-        }
-        if (cj === "`") {
-          i = skipTemplate(content, i);
-          continue;
-        }
-        if (cj === "{") depth++;
-        else if (cj === "}") depth--;
-        i++;
-      }
-      continue;
+    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
+      );
     }
-    if (c === ">") return i;
-    i++;
+    seen.add(state.name);
+    states.push(state);
   }
-  return -1;
+  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 };
+}
+function removalSpan(content, start, end) {
+  let e = end;
+  while (e < content.length && /[ \t]/.test(content[e])) e++;
+  if (content[e] === ",") return { start, end: e + 1 };
+  let s = start;
+  while (s > 0 && /[\s]/.test(content[s - 1])) s--;
+  if (content[s - 1] === ",") return { start: s - 1, end };
+  return { start, end };
+}
+function statementSpan(stmt, content) {
+  let end = stmt.end;
+  while (end < content.length && /[ \t]/.test(content[end])) end++;
+  if (content[end] === ";") end++;
+  while (end < content.length && /[ \t]/.test(content[end])) end++;
+  if (content[end] === "\r") end++;
+  if (content[end] === "\n") end++;
+  return { start: stmt.start, end };
+}
+function isNode2(value) {
+  return typeof value === "object" && value !== null && typeof value.type === "string";
 }
 
-// src/scanner/scan/extract.ts
-var JSDOC_BLOCK = /\/\*\*([\s\S]*?)\*\//g;
-function lineAt(content, index) {
-  let line = 1;
-  for (let i = 0; i < index && i < content.length; i++) {
-    if (content[i] === "\n") line++;
-  }
-  return line;
+// src/scanner/scan/flow-facts.ts
+function collectFlowFacts(parsed, content) {
+  if (parsed.program === null || !content.includes("test.describe")) {
+    return [];
+  }
+  const facts = [];
+  walkAst(parsed.program, (node) => {
+    if (node.type !== "CallExpression") return void 0;
+    const fact = readTaggedDescribe(node, parsed);
+    if (fact) facts.push(fact);
+    return void 0;
+  });
+  return facts;
 }
-function parseJSDoc(block) {
-  const lines = block.split("\n").map((l) => l.replace(/^\s*\*\s?/, "").replace(/^\s*\/?\*+/, ""));
-  let kind = null;
-  let id = null;
-  const acceptance = [];
-  const desc = [];
-  let notFlow = false;
-  for (const raw of lines) {
-    const line = raw.trim();
-    if (!line) continue;
-    const uidex = line.match(
-      /^@uidex\s+(page|feature|widget)\s+(\S+)(?:\s+-\s+(.+))?/
-    );
-    if (uidex) {
-      kind = uidex[1];
-      id = uidex[2];
-      if (uidex[3]) desc.push(uidex[3].trim());
-      continue;
-    }
-    if (/^@uidex:not-flow\b/.test(line)) {
-      notFlow = true;
-      continue;
-    }
-    const accept = line.match(/^@acceptance\s+(.+)$/);
-    if (accept) {
-      acceptance.push(accept[1].trim());
-      continue;
-    }
-    if (line.startsWith("@")) continue;
-    desc.push(line);
+function readTaggedDescribe(call, parsed) {
+  const callee = call.callee;
+  if (!callee || callee.type !== "MemberExpression" || !isIdentifier(callee.object, "test") || !isIdentifier(callee.property, "describe")) {
+    return null;
   }
+  const args = call.arguments ?? [];
+  const title = stringLiteralValue(args[0]);
+  if (title === null) return null;
+  if (!hasFlowTag(args[1])) return null;
+  const body = args[2];
+  const { calls, dynamicCalls } = body ? collectUidexCalls(body, parsed) : { calls: [], dynamicCalls: [] };
   return {
-    kind,
-    id,
-    description: desc.join(" ").trim(),
-    acceptance,
-    notFlow
+    title,
+    line: parsed.lineAt(call.start),
+    calls,
+    ...dynamicCalls.length > 0 ? { dynamicCalls } : {}
   };
 }
-function extract(files) {
-  return files.map((file) => {
-    const { exports, diagnostics } = extractUidexExports(file);
-    const out2 = {
-      file,
-      annotations: extractOne(file)
-    };
-    if (exports.length > 0) out2.metadata = exports;
-    if (diagnostics.length > 0) out2.diagnostics = diagnostics;
-    return out2;
-  });
-}
-function extractOne(file) {
-  const annotations = [];
-  const { content, displayPath } = file;
-  for (const occ of collectJSXAncestry(content)) {
-    annotations.push({
-      kind: occ.kind,
-      id: occ.id,
-      file: displayPath,
-      line: occ.line,
-      ...occ.ancestors.length > 0 ? { ancestors: occ.ancestors } : {}
-    });
-  }
-  JSDOC_BLOCK.lastIndex = 0;
-  let jm;
-  while ((jm = JSDOC_BLOCK.exec(content)) !== null) {
-    const parsed = parseJSDoc(jm[1]);
-    const line = lineAt(content, jm.index);
-    if (parsed.notFlow) {
-      annotations.push({ kind: "not-flow", id: "", file: displayPath, line });
-    }
-    if (parsed.kind && parsed.id) {
-      const kind = parsed.kind === "page" ? "page-doc" : parsed.kind === "feature" ? "feature-doc" : "widget-doc";
-      annotations.push({
-        kind,
-        id: parsed.id,
-        file: displayPath,
-        line,
-        description: parsed.description || void 0,
-        acceptance: parsed.acceptance.length ? parsed.acceptance : void 0
-      });
-    } else if (parsed.acceptance.length > 0) {
-      annotations.push({
-        kind: "orphan-acceptance",
-        id: "",
-        file: displayPath,
-        line,
-        acceptance: parsed.acceptance
-      });
+function hasFlowTag(node) {
+  if (!node || node.type !== "ObjectExpression") return false;
+  for (const prop of node.properties ?? []) {
+    if (prop.type !== "Property") continue;
+    const key = prop.key;
+    const keyName = key?.type === "Identifier" ? String(key.name) : key?.type === "Literal" ? String(key.value) : null;
+    if (keyName !== "tag") continue;
+    const value = prop.value;
+    if (!value) return false;
+    if (stringLiteralValue(value) === "@uidex:flow") return true;
+    if (value.type === "ArrayExpression") {
+      for (const el of value.elements ?? []) {
+        if (el && stringLiteralValue(el) === "@uidex:flow") return true;
+      }
     }
+    return false;
   }
-  return annotations;
+  return false;
 }
-
-// src/scanner/scan/resolve.ts
-import * as path3 from "path";
-
-// 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 collectUidexCalls(body, parsed) {
+  const calls = [];
+  const dynamicCalls = [];
+  const claimed = /* @__PURE__ */ new Set();
+  const record = (node, action) => {
+    if (claimed.has(node)) return;
+    claimed.add(node);
+    const resolved = uidexCallId(node);
+    if (resolved === null) {
+      dynamicCalls.push({ line: parsed.lineAt(node.start) });
+      return;
+    }
+    calls.push({
+      id: resolved.id,
+      ...action ? { action } : {},
+      line: parsed.lineAt(node.start),
+      span: resolved.span
+    });
+  };
+  walkAst(body, (node) => {
+    if (node.type !== "CallExpression") return void 0;
+    const callee = node.callee;
+    if (callee?.type === "MemberExpression") {
+      const inner = callee.object;
+      if (inner && isUidexCall(inner)) {
+        const property = callee.property;
+        const action = property?.type === "Identifier" ? String(property.name) : void 0;
+        record(inner, action);
+      }
+      return void 0;
+    }
+    if (isUidexCall(node)) record(node);
+    return void 0;
+  });
+  return { calls, dynamicCalls };
 }
-function isMetaEntity(entity) {
-  return isMetaKind(entity.kind);
+function isUidexCall(node) {
+  if (node.type !== "CallExpression") return false;
+  if (!isIdentifier(node.callee, "uidex")) return false;
+  return (node.arguments ?? []).length >= 1;
 }
-function entityKey(entity) {
-  return entity.kind === "route" ? entity.path : entity.id;
+function uidexCallId(node) {
+  const args = node.arguments ?? [];
+  const arg = args[0];
+  const id = stringLiteralValue(arg);
+  if (id === null) return null;
+  return { id, span: { start: arg.start, end: arg.end } };
 }
-var UnknownEntityKindError = class extends Error {
-  kind;
-  constructor(kind) {
-    super(`Unknown entity kind: ${kind}`);
-    this.name = "UnknownEntityKindError";
-    this.kind = kind;
+function stringLiteralValue(node) {
+  if (!node) return null;
+  if (node.type === "Literal" && typeof node.value === "string") {
+    return node.value.length > 0 ? node.value : null;
+  }
+  if (node.type === "TemplateLiteral") {
+    const expressions = node.expressions ?? [];
+    if (expressions.length > 0) return null;
+    const quasis = node.quasis ?? [];
+    const cooked = quasis[0]?.value?.cooked;
+    return cooked && cooked.length > 0 ? cooked : null;
   }
-};
-var KIND_SET = new Set(ENTITY_KINDS);
-function assertEntityKind(kind) {
-  if (!KIND_SET.has(kind)) throw new UnknownEntityKindError(kind);
+  return null;
+}
+function isIdentifier(node, name) {
+  return typeof node === "object" && node !== null && node.type === "Identifier" && String(node.name) === name;
 }
 
-// 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()
-  };
+// src/scanner/scan/jsx-ancestry.ts
+var ATTR_NAME_RE = /^data-uidex(?:-(region|widget|primitive))?$/;
+var INTERACTIVE_TAGS = /* @__PURE__ */ new Set(["button", "a", "input", "select", "textarea"]);
+var LANDMARK_TAGS = /* @__PURE__ */ new Set(["header", "nav", "main", "aside", "footer"]);
+function attrKind(node) {
+  const name = node.name;
+  if (!name || name.type !== "JSXIdentifier") return null;
+  const m = ATTR_NAME_RE.exec(String(name.name));
+  if (!m) return null;
+  return m[1] ?? "element";
 }
-function computeFlowIds(flows, targetId) {
-  const ids = [];
-  for (const flow of flows) {
-    if (flow.touches.includes(targetId)) ids.push(flow.id);
+function collectConstStrings(program) {
+  const consts = /* @__PURE__ */ new Map();
+  const seen = /* @__PURE__ */ new Set();
+  walkAst(program, (node) => {
+    if (node.type !== "VariableDeclaration" || node.kind !== "const") {
+      return void 0;
+    }
+    for (const decl of node.declarations ?? []) {
+      const id = decl.id;
+      if (!id || id.type !== "Identifier") continue;
+      const name = String(id.name);
+      if (seen.has(name)) {
+        consts.delete(name);
+        continue;
+      }
+      seen.add(name);
+      const init = decl.init;
+      if (!init) continue;
+      const value = staticString(unwrapTsExpression(init));
+      if (value !== null) consts.set(name, value);
+    }
+    return void 0;
+  });
+  return consts;
+}
+function staticString(node) {
+  if (node.type === "Literal" && typeof node.value === "string") {
+    return node.value;
   }
-  return ids;
+  if (node.type === "TemplateLiteral") {
+    const expressions = node.expressions ?? [];
+    if (expressions.length > 0) return null;
+    const quasis = node.quasis ?? [];
+    return quasis[0]?.value?.cooked ?? "";
+  }
+  return null;
 }
-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) };
+var UNRESOLVED = { resolved: false };
+function evalIdExpression(expr, consts) {
+  const node = unwrapTsExpression(expr);
+  const literal = staticString(node);
+  if (literal !== null) {
+    return literal.length > 0 ? { resolved: true, ids: [literal] } : UNRESOLVED;
+  }
+  if (node.type === "TemplateLiteral") {
+    const quasis = node.quasis ?? [];
+    const expressions = node.expressions ?? [];
+    let out2 = "";
+    for (let i = 0; i < quasis.length; i++) {
+      out2 += quasis[i].value?.cooked ?? "";
+      if (i < expressions.length) {
+        const part = evalIdExpression(expressions[i], consts);
+        out2 += part.resolved && part.ids.length === 1 ? part.ids[0] : "*";
+      }
+    }
+    out2 = out2.replace(/\*{2,}/g, "*");
+    if (!out2.includes("*")) {
+      return out2.length > 0 ? { resolved: true, ids: [out2] } : UNRESOLVED;
+    }
+    return out2.replace(/\*/g, "").length > 0 ? { resolved: true, ids: [out2] } : UNRESOLVED;
+  }
+  if (node.type === "Identifier") {
+    const value = consts.get(String(node.name));
+    return value !== void 0 && value.length > 0 ? { resolved: true, ids: [value] } : UNRESOLVED;
+  }
+  if (node.type === "ConditionalExpression") {
+    const left = evalIdExpression(node.consequent, consts);
+    const right = evalIdExpression(node.alternate, consts);
+    if (!left.resolved || !right.resolved) return UNRESOLVED;
+    return { resolved: true, ids: [.../* @__PURE__ */ new Set([...left.ids, ...right.ids])] };
+  }
+  return UNRESOLVED;
 }
-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.endsWith("*")) {
-        patterns.push({
-          prefix: key.slice(0, -1),
-          entity
+function collectElementAttrs(opening, consts, dynamicAttrs, lineAt) {
+  const statics = [];
+  const patterns = [];
+  const attributes = opening.attributes ?? [];
+  for (const attr of attributes) {
+    if (attr.type !== "JSXAttribute") continue;
+    const kind = attrKind(attr);
+    if (!kind) continue;
+    const value = attr.value;
+    if (!value) continue;
+    let result = UNRESOLVED;
+    let valueSpan;
+    if (value.type === "Literal") {
+      const v = staticString(value);
+      result = v !== null && v.length > 0 ? { resolved: true, ids: [v] } : UNRESOLVED;
+      if (result.resolved) valueSpan = { start: value.start, end: value.end };
+    } else if (value.type === "JSXExpressionContainer") {
+      const expr = value.expression;
+      if (expr && expr.type !== "JSXEmptyExpression") {
+        result = evalIdExpression(expr, consts);
+        const inner = unwrapTsExpression(expr);
+        if (result.resolved && staticString(inner) !== null) {
+          valueSpan = { start: inner.start, end: inner.end };
+        }
+      }
+      if (!result.resolved) {
+        dynamicAttrs.push({
+          kind,
+          attrName: kind === "element" ? "data-uidex" : `data-uidex-${kind}`,
+          line: lineAt(attr.start)
         });
+        continue;
       }
     }
-    patternCache.set(
-      kind,
-      patterns
-    );
-    return patterns;
-  };
-  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 (id.startsWith(entry.prefix) && (best === void 0 || entry.prefix.length > best.prefix.length)) {
-        best = entry;
+    if (!result.resolved) continue;
+    for (const id of result.ids) {
+      const resolved = {
+        kind,
+        id,
+        start: attr.start,
+        isPattern: id.includes("*"),
+        // Only a single plain string literal is renameable in place.
+        ...result.ids.length === 1 && valueSpan ? { span: valueSpan } : {}
+      };
+      if (resolved.isPattern) patterns.push(resolved);
+      else statics.push(resolved);
+    }
+  }
+  return [...statics, ...patterns];
+}
+function collectJSXFacts(parsed) {
+  const occurrences = [];
+  const dynamicAttrs = [];
+  const unannotatedInteractive = [];
+  const landmarks = [];
+  if (parsed.program === null) {
+    return { occurrences, dynamicAttrs, unannotatedInteractive, landmarks };
+  }
+  const consts = collectConstStrings(parsed.program);
+  const ancestors = [];
+  const visit = (node) => {
+    if (!isNode3(node)) return;
+    if (node.type === "JSXElement") {
+      const opening = node.openingElement;
+      const attrs = collectElementAttrs(
+        opening,
+        consts,
+        dynamicAttrs,
+        parsed.lineAt
+      );
+      const interactive = readInteractive(node, parsed.lineAt);
+      if (interactive) unannotatedInteractive.push(interactive);
+      if (attrs.length > 0) {
+        const snapshot = ancestors.slice();
+        for (const a of attrs) {
+          occurrences.push({
+            kind: a.kind,
+            id: a.id,
+            line: parsed.lineAt(a.start),
+            ancestors: snapshot,
+            ...a.span ? { span: a.span } : {}
+          });
+        }
+      }
+      let pushed = attrs.length;
+      for (const a of attrs) ancestors.push({ kind: a.kind, id: a.id });
+      const landmark = readLandmark(opening, parsed.lineAt);
+      if (landmark) {
+        landmarks.push(landmark);
+        if (!attrs.some((a) => a.kind === "region")) {
+          ancestors.push({ kind: "region", id: landmark.tag });
+          pushed++;
+        }
       }
+      visitChildren(opening);
+      for (const child of node.children ?? []) {
+        visit(child);
+      }
+      const closing = node.closingElement;
+      if (isNode3(closing)) visitChildren(closing);
+      ancestors.length -= pushed;
+      return;
     }
-    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)
-    );
+    visitChildren(node);
   };
-  const allEntities = function* () {
-    for (const kind of Object.keys(store)) {
-      for (const entity of store[kind].values()) {
-        yield entity;
+  const visitChildren = (node) => {
+    for (const key of Object.keys(node)) {
+      if (key === "type" || key === "start" || key === "end") continue;
+      const value = node[key];
+      if (Array.isArray(value)) {
+        for (const item of value) visit(item);
+      } else {
+        visit(value);
       }
     }
   };
-  const query = (predicate) => {
-    const flows = getFlows();
-    const result = [];
-    for (const entity of allEntities()) {
-      if (predicate(entity)) result.push(freezeEntity(entity, flows));
+  visit(parsed.program);
+  return { occurrences, dynamicAttrs, unannotatedInteractive, landmarks };
+}
+function readLandmark(opening, lineAt) {
+  const name = opening.name;
+  if (!name || name.type !== "JSXIdentifier") return null;
+  const tag = String(name.name);
+  if (LANDMARK_TAGS.has(tag)) {
+    return { tag, line: lineAt(opening.start) };
+  }
+  for (const attr of opening.attributes ?? []) {
+    if (attr.type !== "JSXAttribute") continue;
+    const attrName = attr.name;
+    if (!attrName || String(attrName.name) !== "role") continue;
+    const value = attr.value;
+    if (value && value.type === "Literal" && value.value === "region") {
+      return { tag: "region", line: lineAt(opening.start) };
     }
-    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 null;
+}
+function readInteractive(element, lineAt) {
+  const opening = element.openingElement;
+  const name = opening.name;
+  if (!name || name.type !== "JSXIdentifier") return null;
+  const tag = String(name.name);
+  if (!INTERACTIVE_TAGS.has(tag)) return null;
+  let hasSpread = false;
+  for (const attr of opening.attributes ?? []) {
+    if (attr.type === "JSXSpreadAttribute") {
+      hasSpread = true;
+      continue;
+    }
+    if (attr.type === "JSXAttribute" && attrKind(attr) !== null) return null;
+  }
+  const nameHint = interactiveNameHint(element, opening);
   return {
-    add,
-    get,
-    matchPattern,
-    list,
-    query,
-    byScope,
-    touchedBy,
-    setReports,
-    getReports,
-    listReportKeys,
-    onReportsChange
+    tag,
+    line: lineAt(opening.start),
+    hasSpread,
+    nameEnd: name.end,
+    ...nameHint ? { nameHint } : {}
+  };
+}
+function staticAttrValue(opening, attrName) {
+  for (const attr of opening.attributes ?? []) {
+    if (attr.type !== "JSXAttribute") continue;
+    const n = attr.name;
+    if (!n || String(n.name) !== attrName) continue;
+    const value = attr.value;
+    if (!value) return null;
+    if (value.type === "Literal") return staticString(value);
+    if (value.type === "JSXExpressionContainer") {
+      const expr = value.expression;
+      return expr ? staticString(unwrapTsExpression(expr)) : null;
+    }
+    return null;
+  }
+  return null;
+}
+function staticChildText(element) {
+  const parts = [];
+  for (const child of element.children ?? []) {
+    if (child.type === "JSXText") {
+      parts.push(String(child.value ?? ""));
+    }
+  }
+  return parts.join(" ").replace(/\s+/g, " ").trim();
+}
+function interactiveNameHint(element, opening) {
+  const ariaLabel = staticAttrValue(opening, "aria-label");
+  if (ariaLabel) return ariaLabel;
+  const text = staticChildText(element);
+  if (text) return text;
+  for (const attr of ["title", "name", "placeholder"]) {
+    const v = staticAttrValue(opening, attr);
+    if (v) return v;
+  }
+  return void 0;
+}
+function isNode3(value) {
+  return typeof value === "object" && value !== null && typeof value.type === "string";
+}
+
+// src/scanner/scan/extract.ts
+function parseFailureDiagnostic(file, parsed) {
+  const fatal = parsed.program === null || parsed.hasErrors && parsed.program.body.length === 0;
+  if (!fatal) return null;
+  return {
+    code: "parse-error",
+    severity: "warning",
+    message: "File could not be parsed \u2014 data-uidex attributes and flow facts in it were skipped, and their ids will drop out of the gen file",
+    file: file.displayPath,
+    line: 1,
+    hint: "Fix the file's syntax (or exclude it from .uidex.json sources) so the scanner can read its annotations"
   };
 }
+function extract(files) {
+  return files.map((file) => {
+    const parsed = parseSource(file);
+    const { exports, diagnostics } = extractUidexExports(file, parsed);
+    const parseFailure = parseFailureDiagnostic(file, parsed);
+    if (parseFailure) diagnostics.push(parseFailure);
+    const out2 = { file, annotations: [] };
+    out2.annotations = extractOne(file, parsed, out2);
+    if (exports.length > 0) out2.metadata = exports;
+    if (diagnostics.length > 0) out2.diagnostics = diagnostics;
+    const flows = collectFlowFacts(parsed, file.content);
+    if (flows.length > 0) out2.flows = flows;
+    const imports = collectImportFacts(parsed);
+    if (imports.length > 0) out2.imports = imports;
+    return out2;
+  });
+}
+function extractOne(file, parsed, out2) {
+  const annotations = [];
+  const { displayPath } = file;
+  const jsx = collectJSXFacts(parsed);
+  if (jsx.dynamicAttrs.length > 0) out2.dynamicAttrs = jsx.dynamicAttrs;
+  if (jsx.unannotatedInteractive.length > 0) {
+    out2.unannotatedInteractive = jsx.unannotatedInteractive;
+  }
+  if (jsx.landmarks.length > 0) out2.landmarks = jsx.landmarks;
+  for (const occ of jsx.occurrences) {
+    annotations.push({
+      kind: occ.kind,
+      id: occ.id,
+      file: displayPath,
+      line: occ.line,
+      ...occ.ancestors.length > 0 ? { ancestors: occ.ancestors } : {},
+      ...occ.span ? { span: occ.span } : {}
+    });
+  }
+  return annotations;
+}
+function collectImportFacts(parsed) {
+  if (parsed.program === null) return [];
+  const out2 = [];
+  for (const stmt of parsed.program.body) {
+    let source;
+    let isTypeOnly = false;
+    const names = [];
+    if (stmt.type === "ImportDeclaration") {
+      source = stmt.source;
+      isTypeOnly = stmt.importKind === "type";
+      for (const spec of stmt.specifiers ?? []) {
+        const local = spec.local;
+        if (local && local.type === "Identifier") {
+          names.push(String(local.name));
+        }
+      }
+    } else if ((stmt.type === "ExportNamedDeclaration" || stmt.type === "ExportAllDeclaration") && stmt.source) {
+      source = stmt.source;
+      isTypeOnly = stmt.exportKind === "type";
+    } 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
+import * as path4 from "path";
 
 // src/scanner/scan/routes.ts
 var PAGE_BASENAME = /^page\.(tsx|ts|jsx|js|mjs|cjs)$/;
@@ -1771,21 +1902,9 @@ function kebab(str) {
   return str.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[_\s]+/g, "-").replace(/[^a-zA-Z0-9-]/g, "").toLowerCase();
 }
 function baseName(file) {
-  const b = path3.posix.basename(file);
+  const b = path4.posix.basename(file);
   return b.replace(/\.(tsx|ts|jsx|js|mjs|cjs)$/, "");
 }
-var LANDMARK_RE = /<(header|nav|main|aside|footer)(\s[^>]*)?>|role=["']region["']/gi;
-function extractLandmarks(file) {
-  const out2 = [];
-  LANDMARK_RE.lastIndex = 0;
-  let m;
-  while ((m = LANDMARK_RE.exec(file.content)) !== null) {
-    const tag = m[1] ?? "region";
-    const line = 1 + file.content.slice(0, m.index).split("\n").length - 1;
-    out2.push({ tag, line });
-  }
-  return out2;
-}
 function fileMatchesAny(displayPath, patterns) {
   return patterns.some((g) => globToRegExp(g).test(displayPath));
 }
@@ -1796,6 +1915,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) {
@@ -1846,7 +1977,7 @@ function resolve2(ctx) {
   const routes = conventions.pages === "auto" ? detectRoutes(ctx.extracted.map((e) => e.file)) : [];
   const handledPageFiles = /* @__PURE__ */ new Set();
   for (const route of routes) {
-    const routeDir = path3.posix.dirname(route.file);
+    const routeDir = path4.posix.dirname(route.file);
     const wellKnownPath = `${routeDir}/${WELL_KNOWN_FILES.page}`;
     const wellKnownExp = exportFor(wellKnownPath, "page");
     const routeExp = exportFor(route.file, "page");
@@ -1900,7 +2031,7 @@ function resolve2(ctx) {
       const dir = extractFeatureDir(ef.file.displayPath, featureGlob);
       if (!dir) continue;
       conventionalFeatureDirs.add(dir);
-      const isWellKnown = path3.posix.basename(ef.file.displayPath) === WELL_KNOWN_FILES.feature;
+      const isWellKnown = path4.posix.basename(ef.file.displayPath) === WELL_KNOWN_FILES.feature;
       if (isWellKnown) wellKnownFeatureFileByDir.set(dir, ef.file.displayPath);
       const exp = exportFor(ef.file.displayPath, "feature");
       if (exp) {
@@ -1937,7 +2068,7 @@ function resolve2(ctx) {
       } else if (allExports.length > 0) {
         exp = allExports[0].exp;
       }
-      const id = exp && typeof exp.id === "string" ? exp.id : path3.posix.basename(dir);
+      const id = exp && typeof exp.id === "string" ? exp.id : path4.posix.basename(dir);
       const meta = exp ? buildMetaFromExport(exp) : void 0;
       const feature = {
         kind: "feature",
@@ -2033,8 +2164,8 @@ function resolve2(ctx) {
   }
   if (conventions.regions === "landmarks") {
     for (const ef of ctx.extracted) {
-      for (const lm of extractLandmarks(ef.file)) {
-        const id = kebab(`${lm.tag}`);
+      for (const lm of ef.landmarks ?? []) {
+        const id = lm.tag;
         if (!registry.get("region", id)) {
           const meta = metaWithComposes("region", id);
           const region = {
@@ -2145,7 +2276,7 @@ function resolve2(ctx) {
       const flowExport = (ff.metadata ?? []).find(
         (m) => m.kind === "flow" && typeof m.id === "string"
       );
-      const derived = extractFlowsFromSource(ff.file);
+      const derived = flowsFromFacts(ff);
       if (flowExport && typeof flowExport.id === "string" && derived.length === 1) {
         const base = derived[0];
         const flow = {
@@ -2200,60 +2331,312 @@ function computeScope(displayPath) {
   }
   return null;
 }
-function extractFlowsFromSource(file) {
-  const flows = [];
-  const source = file.content;
-  const describeRe = /test\.describe\(\s*(?:'([^']*)'|"([^"]*)")\s*,\s*\{[^}]*tag:\s*(?:'@uidex:flow'|"@uidex:flow"|\[[^\]]*@uidex:flow[^\]]*\])[^}]*\}/g;
-  let m;
-  while ((m = describeRe.exec(source)) !== null) {
-    const title = m[1] ?? m[2];
-    const id = kebab(title);
-    const line = 1 + source.slice(0, m.index).split("\n").length - 1;
-    const after = source.slice(m.index + m[0].length);
-    const arrow = after.match(/=>\s*\{/);
-    if (!arrow || arrow.index === void 0) continue;
-    const bodyStart = m.index + m[0].length + arrow.index + arrow[0].length;
-    let depth = 1;
-    let bodyEnd = -1;
-    for (let i = bodyStart; i < source.length; i++) {
-      if (source[i] === "{") depth++;
-      else if (source[i] === "}") {
-        depth--;
-        if (depth === 0) {
-          bodyEnd = i;
-          break;
-        }
-      }
+function flowsFromFacts(ff) {
+  return (ff.flows ?? []).map((fact) => ({
+    kind: "flow",
+    id: kebab(fact.title),
+    loc: { file: ff.file.displayPath, line: fact.line },
+    touches: dedupe(fact.calls.map((c) => c.id)),
+    steps: fact.calls.filter((c) => c.action).map((c) => ({ entityId: c.id, action: c.action }))
+  }));
+}
+function dedupe(arr) {
+  return Array.from(new Set(arr));
+}
+
+// src/scanner/scan/audit.ts
+import * as path5 from "path";
+
+// 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;
     }
-    if (bodyEnd === -1) continue;
-    const body = source.slice(bodyStart, bodyEnd);
-    const touches = captureUidexIds(body);
-    flows.push({
-      kind: "flow",
-      id,
-      loc: { file: file.displayPath, line },
-      touches: dedupe(touches.map((t) => t.id)),
-      steps: touches.filter((t) => t.action).map((t) => ({ entityId: t.id, action: t.action }))
+    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).`
     });
   }
-  return flows;
+  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 captureUidexIds(body) {
+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 = [];
-  const re = /uidex\(\s*(?:'([^']+)'|"([^"]+)"|`([^`$]+)`)\s*\)(?:\.(\w+)\s*\()?/g;
-  let m;
-  while ((m = re.exec(body)) !== null) {
-    out2.push({ id: m[1] || m[2] || m[3], action: m[4] });
+  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 dedupe(arr) {
-  return Array.from(new Set(arr));
+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
-import * as path4 from "path";
-var MARKER_FILENAMES = ["UIDEX_PAGE.md", "UIDEX_FEATURE.md"];
 function audit(opts) {
   const diagnostics = [];
   const { registry, extracted, files, config } = opts;
@@ -2262,23 +2645,19 @@ 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);
-  if (check) {
-    for (const f of files) {
-      const base = f.displayPath.split("/").pop() ?? "";
-      if (MARKER_FILENAMES.includes(base)) {
-        diagnostics.push({
-          code: "marker-md-ignored",
-          severity: "warning",
-          message: `Marker file "${base}" is ignored in v2; migrate to \`export const uidex\``,
-          file: f.displayPath
-        });
-      }
-    }
+  for (const ef of extracted) {
+    if (ef.diagnostics) diagnostics.push(...ef.diagnostics);
+  }
+  for (const ef of opts.flowExtracted ?? []) {
+    if (ef.diagnostics) diagnostics.push(...ef.diagnostics);
   }
   if (check && opts.generated !== void 0) {
     const outRel = opts.outputPath ?? config.output;
-    const fresh = normalizeLineEndings(opts.generated);
+    const fresh = normalizeForCheck(opts.generated);
     if (opts.existingOnDisk === null || opts.existingOnDisk === void 0) {
       diagnostics.push({
         code: "gen-missing",
@@ -2288,7 +2667,7 @@ function audit(opts) {
         hint: "Run `uidex scan` (without --check) to regenerate"
       });
     } else {
-      const existing = normalizeLineEndings(opts.existingOnDisk);
+      const existing = normalizeForCheck(opts.existingOnDisk);
       if (existing !== fresh) {
         const changed = diffEntities(existing, opts.generated, registry);
         const summary2 = formatChangedSummary(changed);
@@ -2302,20 +2681,46 @@ function audit(opts) {
       }
     }
   }
-  if (lint) {
-    for (const ef of extracted) {
-      for (const a of ef.annotations) {
-        const migration = legacyJsdocMigration(a);
-        if (!migration) continue;
-        diagnostics.push({
-          code: "legacy-jsdoc",
-          severity: "warning",
-          message: migration.message,
-          file: a.file,
-          line: a.line,
-          hint: migration.hint
-        });
-      }
+  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) {
@@ -2363,8 +2768,8 @@ function audit(opts) {
         if (typeof m.id !== "string") continue;
         const filePath = ef.file.displayPath;
         const wellKnownName = WELL_KNOWN_FILES[m.kind];
-        if (path4.posix.basename(filePath) === wellKnownName) continue;
-        const dir = path4.posix.dirname(filePath);
+        if (path5.posix.basename(filePath) === wellKnownName) continue;
+        const dir = path5.posix.dirname(filePath);
         const wellKnownPath = dir === "." ? wellKnownName : `${dir}/${wellKnownName}`;
         if (scannedPaths.has(wellKnownPath)) continue;
         const kindLabel = m.kind === "page" ? "Page" : "Feature";
@@ -2381,53 +2786,55 @@ function audit(opts) {
     }
   }
   if (lint) {
-    const dynamicAttrRe = /\bdata-uidex(?:-(region|widget|primitive))?\s*=\s*\{/g;
-    const templateWithPrefixRe = /\bdata-uidex(?:-(region|widget|primitive))?\s*=\s*\{\s*`[^`$]+\$\{/g;
-    for (const f of files) {
-      const templatePrefixPositions = /* @__PURE__ */ new Set();
-      templateWithPrefixRe.lastIndex = 0;
-      let tm;
-      while ((tm = templateWithPrefixRe.exec(f.content)) !== null) {
-        templatePrefixPositions.add(tm.index);
-      }
-      let m;
-      dynamicAttrRe.lastIndex = 0;
-      while ((m = dynamicAttrRe.exec(f.content)) !== null) {
-        if (templatePrefixPositions.has(m.index)) continue;
-        const kind = m[1] ?? "element";
-        let line = 1;
-        for (let i = 0; i < m.index; i++) if (f.content[i] === "\n") line++;
-        const attrName = m[1] ? `data-uidex-${m[1]}` : "data-uidex";
+    for (const ef of extracted) {
+      for (const fact of ef.dynamicAttrs ?? []) {
         diagnostics.push({
           code: "dynamic-attr",
           severity: "warning",
-          message: `\`${attrName}={\u2026}\` uses a dynamic expression; the scanner cannot resolve the ${kind} id statically`,
-          file: f.displayPath,
-          line,
-          hint: dynamicAttrHint(kind)
+          message: `\`${fact.attrName}={\u2026}\` uses a dynamic expression; the scanner cannot resolve the ${fact.kind} id statically`,
+          file: ef.file.displayPath,
+          line: fact.line,
+          hint: dynamicAttrHint(fact.kind)
         });
       }
     }
   }
   if (lint) {
-    for (const f of files) {
-      const tagRe = /<(button|a|input|select|textarea)(?=[\s/>])/g;
-      let m;
-      while ((m = tagRe.exec(f.content)) !== null) {
-        const afterTag = m.index + m[0].length;
-        const closeIdx = findJsxOpeningEnd(f.content, afterTag);
-        if (closeIdx === -1) continue;
-        const attrs = f.content.slice(afterTag, closeIdx);
-        if (attrs.includes("data-uidex")) continue;
-        let line = 1;
-        for (let i = 0; i < m.index; i++) if (f.content[i] === "\n") line++;
-        diagnostics.push({
-          code: "missing-element-annotation",
-          severity: "info",
-          message: `Interactive <${m[1].toLowerCase()}> without data-uidex annotation`,
-          file: f.displayPath,
-          line
-        });
+    const usedElementIds = new Set(registry.list("element").map((e) => e.id));
+    for (const ef of extracted) {
+      for (const fact of ef.unannotatedInteractive ?? []) {
+        if (fact.hasSpread) {
+          diagnostics.push({
+            code: "spread-attr",
+            severity: "info",
+            message: `Interactive <${fact.tag}> spreads dynamic props and has no static data-uidex attribute; if the annotation is forwarded via props the scanner cannot register it`,
+            file: ef.file.displayPath,
+            line: fact.line,
+            hint: "Prefer a string-literal data-uidex on the element itself, or annotate at the call site."
+          });
+        } else {
+          const id = uniqueElementId(fact, usedElementIds);
+          usedElementIds.add(id);
+          diagnostics.push({
+            code: "missing-element-annotation",
+            severity: "info",
+            message: `Interactive <${fact.tag}> without data-uidex annotation`,
+            file: ef.file.displayPath,
+            line: fact.line,
+            hint: `Add \`data-uidex="${id}"\` (or run \`uidex scan --fix\`).`,
+            fix: {
+              description: `Add data-uidex="${id}" to <${fact.tag}>`,
+              edits: [
+                {
+                  path: ef.file.sourcePath,
+                  start: fact.nameEnd,
+                  end: fact.nameEnd,
+                  replacement: ` data-uidex="${id}"`
+                }
+              ]
+            }
+          });
+        }
       }
     }
   }
@@ -2444,12 +2851,11 @@ function audit(opts) {
         }
       }
     }
-    for (const f of files) {
-      const importRe = /import\s+(?:[^'"]+)\s+from\s+['"]([^'"]+)['"]/g;
-      let m;
-      while ((m = importRe.exec(f.content)) !== null) {
-        const spec = m[1];
-        const baseName2 = spec.split("/").pop() ?? "";
+    for (const ef of extracted) {
+      const displayPath = ef.file.displayPath;
+      for (const imp of ef.imports ?? []) {
+        if (imp.isTypeOnly) continue;
+        const baseName2 = imp.specifier.split("/").pop() ?? "";
         const primitive = byName.get(
           baseName2.replace(/\.(tsx|ts|jsx|js|mjs|cjs)$/, "").replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase()
         );
@@ -2457,25 +2863,37 @@ function audit(opts) {
         const scope = primitive.scopes?.[0];
         if (!scope) continue;
         const [kind, id] = scope.split(":");
-        const importerSegments = f.displayPath.split("/");
+        const importerSegments = displayPath.split("/");
         if (importerSegments.includes(id) && importerSegments.includes(kind + "s")) {
           continue;
         }
         if (kind === "feature" && importerSegments.includes(id)) continue;
-        if (kind === "feature" && declaredFeatures.get(f.displayPath)?.has(id)) {
+        if (kind === "feature" && declaredFeatures.get(displayPath)?.has(id)) {
           continue;
         }
         diagnostics.push({
           code: "scope-leak",
           severity: "warning",
-          message: `Primitive "${primitive.id}" is scoped to ${scope} but is imported from ${f.displayPath}`,
-          file: f.displayPath
+          message: `Primitive "${primitive.id}" is scoped to ${scope} but is imported from ${displayPath}`,
+          file: displayPath,
+          line: imp.line
         });
       }
     }
   }
   if (lint && coverageEnabled) {
+    const factsByLoc = /* @__PURE__ */ new Map();
+    for (const ef of opts.flowExtracted ?? []) {
+      for (const fact of ef.flows ?? []) {
+        const lines = /* @__PURE__ */ new Map();
+        for (const call of fact.calls) {
+          if (!lines.has(call.id)) lines.set(call.id, call.line);
+        }
+        factsByLoc.set(`${ef.file.displayPath}:${fact.line}`, lines);
+      }
+    }
     for (const flow of registry.list("flow")) {
+      const callLines = factsByLoc.get(`${flow.loc.file}:${flow.loc.line}`);
       for (const touchedId of flow.touches) {
         const found = registry.get("element", touchedId) ?? registry.get("widget", touchedId) ?? registry.get("region", touchedId) ?? registry.matchPattern("element", touchedId) ?? registry.matchPattern("widget", touchedId) ?? registry.matchPattern("region", touchedId);
         if (!found) {
@@ -2484,54 +2902,146 @@ function audit(opts) {
             severity: "warning",
             message: `Flow "${flow.id}" references unknown entity "${touchedId}"`,
             file: flow.loc.file,
-            line: flow.loc.line
+            // Point at the uidex() call itself when the spec facts are
+            // available; the describe line is the fallback.
+            line: callLines?.get(touchedId) ?? flow.loc.line
+          });
+        }
+      }
+    }
+  }
+  if (lint) {
+    const occurrences = /* @__PURE__ */ new Map();
+    for (const ef of extracted) {
+      for (const a of ef.annotations) {
+        if (a.kind !== "element" && a.kind !== "region" && a.kind !== "widget" && a.kind !== "primitive") {
+          continue;
+        }
+        const key = `${a.kind}:${a.id}`;
+        let list = occurrences.get(key);
+        if (!list) {
+          list = [];
+          occurrences.set(key, list);
+        }
+        list.push({ file: a.file, line: a.line });
+      }
+    }
+    for (const [key, list] of occurrences) {
+      const filesSeen = new Set(list.map((o) => o.file));
+      if (filesSeen.size < 2) continue;
+      const [kind, id] = key.split(/:(.*)/s);
+      const others = list.slice(1).map((o) => `${o.file}:${o.line}`).join(", ");
+      diagnostics.push({
+        code: "duplicate-id",
+        severity: kind === "widget" || kind === "primitive" ? "warning" : "info",
+        message: `${kind} id "${id}" is declared in ${filesSeen.size} files (also at ${others}); the registry keeps only one entry`,
+        file: list[0].file,
+        line: list[0].line,
+        entity: { kind, id },
+        hint: kind === "element" || kind === "region" ? "If these are variants of the same logical element this is fine; otherwise rename one (`uidex rename` updates flow references too)." : "Rename one of the definitions; two definitions with the same id silently merge."
+      });
+    }
+  }
+  if (lint && coverageEnabled) {
+    for (const ef of opts.flowExtracted ?? []) {
+      for (const fact of ef.flows ?? []) {
+        for (const dyn of fact.dynamicCalls ?? []) {
+          diagnostics.push({
+            code: "dynamic-flow-reference",
+            severity: "warning",
+            message: `\`uidex(\u2026)\` call in flow "${fact.title}" uses a dynamic expression; the id is invisible to coverage and registry validation`,
+            file: ef.file.displayPath,
+            line: dyn.line,
+            hint: "Use a string-literal id (component ids inside uidex() must be statically analysable)."
           });
         }
       }
     }
   }
+  if (lint && coverageEnabled) {
+    for (const ef of extracted) {
+      if (!ef.metadata) continue;
+      for (const m of ef.metadata) {
+        const check2 = (refKind, ids, spans) => {
+          for (let i = 0; i < (ids?.length ?? 0); i++) {
+            const refId = ids[i];
+            const found = registry.get(refKind, refId) ?? registry.matchPattern(refKind, refId);
+            if (found) continue;
+            diagnostics.push({
+              code: "unknown-reference",
+              severity: "warning",
+              message: `\`export const uidex\` in ${ef.file.displayPath} references unknown ${refKind} "${refId}"`,
+              file: ef.file.displayPath,
+              line: spans?.[i] ? lineOfOffset(ef.file.content, spans[i].start) : m.loc.line,
+              hint: `No ${refKind} with id "${refId}" exists in the registry; fix the reference or add the ${refKind}.`
+            });
+          }
+        };
+        check2("feature", m.features, m.featureSpans);
+        check2("widget", m.widgets, m.widgetSpans);
+      }
+    }
+  }
+  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
   };
   return { diagnostics, summary };
 }
-function legacyJsdocMigration(a) {
-  const quote = (s) => JSON.stringify(s);
-  const arr = (xs) => xs && xs.length > 0 ? `[${xs.map(quote).join(", ")}]` : "";
-  const entityHint = (kind) => {
-    const uidexKind = kind.charAt(0).toUpperCase() + kind.slice(1);
-    const parts = [`${kind}: ${quote(a.id)}`];
-    if (a.acceptance?.length) parts.push(`acceptance: ${arr(a.acceptance)}`);
-    return {
-      message: `Legacy JSDoc tag \`@uidex ${kind} ${a.id}\` is no longer recognised; migrate to \`export const uidex\``,
-      hint: `Replace with: export const uidex = { ${parts.join(", ")} } as const satisfies Uidex.${uidexKind}`
-    };
-  };
-  switch (a.kind) {
-    case "page-doc":
-      return entityHint("page");
-    case "feature-doc":
-      return entityHint("feature");
-    case "widget-doc":
-      return entityHint("widget");
-    case "not-flow":
-      return {
-        message: `Legacy JSDoc tag \`@uidex:not-flow\` is no longer recognised; migrate to \`export const uidex\``,
-        hint: `Replace with: export const uidex = { notFlow: true } as const satisfies Uidex.NotFlow`
-      };
-    case "orphan-acceptance":
-      return {
-        message: `Legacy JSDoc tag \`@acceptance\` is no longer recognised; migrate to the \`acceptance\` field on \`export const uidex\``,
-        hint: `Replace with: export const uidex = { /* kind */, acceptance: ${arr(a.acceptance)} } as const`
-      };
-    default:
-      return null;
+function lineOfOffset(content, offset) {
+  let line = 1;
+  for (let i = 0; i < offset && i < content.length; i++) {
+    if (content[i] === "\n") line++;
+  }
+  return line;
+}
+var TAG_FALLBACK_ID = {
+  a: "link",
+  button: "button",
+  input: "input",
+  select: "select",
+  textarea: "textarea"
+};
+function kebabId(str) {
+  return str.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-+|-+$/g, "").toLowerCase();
+}
+function deriveElementId(fact) {
+  const fromHint = fact.nameHint ? kebabId(fact.nameHint) : "";
+  const capped = fromHint.split("-").filter(Boolean).slice(0, 5).join("-");
+  return capped || TAG_FALLBACK_ID[fact.tag] || fact.tag;
+}
+function uniqueElementId(fact, used) {
+  const base = deriveElementId(fact);
+  if (!used.has(base)) return base;
+  for (let n = 2; ; n++) {
+    const candidate = `${base}-${n}`;
+    if (!used.has(candidate)) return candidate;
   }
 }
 function normalizeLineEndings(s) {
   return s.replace(/\r\n/g, "\n");
 }
+function normalizeForCheck(s) {
+  return normalizeLineEndings(s).replace(
+    /export const gitContext = \{[\s\S]*?\} as const/,
+    "export const gitContext = {} as const"
+  );
+}
 function formatChangedSummary(change) {
   const parts = [];
   const fmt = (kind, names) => {
@@ -2615,77 +3125,26 @@ function extractEntitiesArray(source) {
       inStr = c;
       continue;
     }
-    if (c === "[") depth++;
-    else if (c === "]") {
-      depth--;
-      if (depth === 0) {
-        const json = source.slice(start, i + 1);
-        try {
-          return JSON.parse(json);
-        } catch {
-          return null;
-        }
-      }
-    }
-  }
-  return null;
-}
-function findJsxOpeningEnd(src, start) {
-  let i = start;
-  while (i < src.length) {
-    const ch = src[i];
-    if (ch === ">" || ch === "/" && src[i + 1] === ">") return i;
-    if (ch === '"' || ch === "'" || ch === "`") {
-      i = skipString2(src, i);
-    } else if (ch === "{") {
-      i = skipBraces(src, i);
-    } else {
-      i++;
-    }
-  }
-  return -1;
-}
-function skipString2(src, start) {
-  const quote = src[start];
-  let i = start + 1;
-  while (i < src.length) {
-    if (src[i] === "\\" && quote !== "`") {
-      i += 2;
-      continue;
-    }
-    if (quote === "`" && src[i] === "$" && src[i + 1] === "{") {
-      i = skipBraces(src, i + 1);
-      continue;
-    }
-    if (src[i] === quote) return i + 1;
-    i++;
-  }
-  return i;
-}
-function skipBraces(src, start) {
-  let depth = 1;
-  let i = start + 1;
-  while (i < src.length && depth > 0) {
-    const ch = src[i];
-    if (ch === "{") {
-      depth++;
-      i++;
-    } else if (ch === "}") {
+    if (c === "[") depth++;
+    else if (c === "]") {
       depth--;
-      i++;
-    } else if (ch === '"' || ch === "'" || ch === "`") {
-      i = skipString2(src, i);
-    } else {
-      i++;
+      if (depth === 0) {
+        const json = source.slice(start, i + 1);
+        try {
+          return JSON.parse(json);
+        } catch {
+          return null;
+        }
+      }
     }
   }
-  return i;
+  return null;
 }
 function dynamicAttrHint(kind) {
   if (kind === "region") {
     return `Use a string literal: \`data-uidex-region="id"\`, or declare the region via \`export const uidex = { region: "id" } as const satisfies Uidex.Region\` on the file that passes the region value`;
   }
-  return `The scanner requires string-literal attribute values. If this component forwards the annotation via a prop, restructure so the caller provides the annotated element directly (e.g. via a slot or render prop) with a string-literal \`data-uidex\` attribute`;
+  return `The scanner resolves string literals, same-file const references, ternaries with literal branches, and template literals with static text (dynamic parts become \`*\` patterns). If this component forwards the annotation via a prop, restructure so the caller provides the annotated element directly (e.g. via a slot or render prop)`;
 }
 function stableStringify(value) {
   return JSON.stringify(value, stableReplacer);
@@ -2702,6 +3161,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));
 }
@@ -2718,9 +3319,7 @@ function replacerSorted(_key, value) {
   }
   return value;
 }
-function emitIdUnion(name, ids, typeMode) {
-  if (typeMode === "loose") return `export type ${name} = string
-`;
+function emitIdUnion(name, ids) {
   if (ids.length === 0) return `export type ${name} = never
 `;
   const sorted = [...ids].sort();
@@ -2729,133 +3328,153 @@ function emitIdUnion(name, ids, typeMode) {
 ${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",
-    typeMode = "strict"
-  } = opts;
+  const { registry, gitContext, uidexImport = "uidex" } = opts;
   const routes = [...registry.list("route")].sort(
     (a, b) => a.path.localeCompare(b.path)
   );
   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),
-      typeMode
+      pages.map((e) => e.id)
     )
   );
-  lines.push(
-    emitIdUnion(
+  t.push(
+    emitId(
       "FeatureId",
-      features.map((e) => e.id),
-      typeMode
+      features.map((e) => e.id)
     )
   );
-  lines.push(
-    emitIdUnion(
+  t.push(
+    emitId(
       "WidgetId",
-      widgets.map((e) => e.id),
-      typeMode
+      widgets.map((e) => e.id)
     )
   );
-  lines.push(
-    emitIdUnion(
+  t.push(
+    emitId(
       "RegionId",
-      regions.map((e) => e.id),
-      typeMode
+      regions.map((e) => e.id)
     )
   );
-  lines.push(
-    emitIdUnion(
+  t.push(
+    emitId(
       "ElementId",
-      elements.map((e) => e.id),
-      typeMode
+      elements.map((e) => e.id)
     )
   );
-  lines.push(
-    emitIdUnion(
+  t.push(
+    emitId(
       "PrimitiveId",
-      primitives.map((e) => e.id),
-      typeMode
+      primitives.map((e) => e.id)
     )
   );
-  lines.push(
-    emitIdUnion(
+  t.push(
+    emitId(
       "FlowId",
-      flows.map((e) => e.id),
-      typeMode
+      flows.map((e) => e.id)
     )
   );
-  lines.push(
-    emitIdUnion(
+  t.push(
+    emitId(
       "RouteId",
-      routes.map((e) => e.path),
-      typeMode
+      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,
@@ -2866,25 +3485,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
@@ -2921,22 +3554,33 @@ function parseGitHubRef(ref) {
 
 // src/scanner/scan/scaffold.ts
 import * as fs3 from "fs";
-import * as path5 from "path";
+import * as path6 from "path";
 function scaffoldWidgetSpec(opts) {
+  return scaffoldSpec({
+    registry: opts.registry,
+    kind: "widget",
+    id: opts.widgetId,
+    outDir: opts.outDir,
+    force: opts.force,
+    fixtureImport: opts.fixtureImport
+  });
+}
+function scaffoldSpec(opts) {
   const {
     registry,
-    widgetId,
+    kind,
+    id,
     outDir,
     force = false,
     fixtureImport = "./fixtures"
   } = opts;
-  const widget = registry.get("widget", widgetId);
-  if (!widget) {
-    throw new Error(`Widget "${widgetId}" not found in registry`);
+  const entity = registry.get(kind, id);
+  if (!entity) {
+    throw new Error(`${capitalize(kind)} "${id}" not found in registry`);
   }
-  const criteria = widget.meta?.acceptance ?? [];
-  const filename = `widget-${widgetId}.spec.ts`;
-  const outputPath = path5.resolve(outDir, filename);
+  const criteria = entity.meta?.acceptance ?? [];
+  const filename = kind === "widget" ? `widget-${id}.spec.ts` : `flow-${id}.spec.ts`;
+  const outputPath = path6.resolve(outDir, filename);
   if (fs3.existsSync(outputPath) && !force) {
     return {
       outputPath,
@@ -2945,15 +3589,14 @@ function scaffoldWidgetSpec(opts) {
       reason: `spec already exists at ${outputPath}; pass --force to overwrite`
     };
   }
-  const content = renderSpec({
-    widgetId,
-    criteria,
-    fixtureImport
-  });
-  fs3.mkdirSync(path5.dirname(outputPath), { recursive: true });
+  const content = renderSpec({ id, criteria, fixtureImport });
+  fs3.mkdirSync(path6.dirname(outputPath), { recursive: true });
   fs3.writeFileSync(outputPath, content, "utf8");
   return { outputPath, written: true, skipped: false };
 }
+function capitalize(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
 function renderSpec(args) {
   const lines = [];
   lines.push(
@@ -2961,7 +3604,7 @@ function renderSpec(args) {
   );
   lines.push("");
   lines.push(
-    `test.describe(${JSON.stringify(args.widgetId)}, { tag: "@uidex:flow" }, () => {`
+    `test.describe(${JSON.stringify(args.id)}, { tag: "@uidex:flow" }, () => {`
   );
   if (args.criteria.length === 0) {
     lines.push(`  test("TODO: add acceptance criteria", async () => {`);
@@ -2984,7 +3627,69 @@ function renderSpec(args) {
 
 // src/scanner/scan/pipeline.ts
 import * as fs4 from "fs";
-import * as path6 from "path";
+import * as path7 from "path";
+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 });
@@ -3011,34 +3716,54 @@ function runOne(dc, opts) {
     flowFiles: extractedFlows
   });
   const gitContext = resolveGitContext({ cwd: configDir });
-  const generated = emit({
+  const emitted = emit({
     registry: resolved.registry,
-    gitContext,
-    typeMode: config.typeMode
+    gitContext
   });
-  const outputPath = path6.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) {
+  if (opts.check || opts.lint || resolved.diagnostics.length > 0 || hasExtractDiagnostics) {
     auditResult = audit({
       registry: resolved.registry,
       extracted,
       files: sourceFiles,
+      flowExtracted: extractedFlows,
       config,
       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 {
@@ -3047,39 +3772,311 @@ 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(path6.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
+import * as fs5 from "fs";
+import * as path8 from "path";
+function applyFixes(diagnostics) {
+  const entries = [];
+  for (const d of diagnostics) {
+    if (!d.fix) continue;
+    entries.push({
+      code: d.code,
+      description: d.fix.description,
+      file: d.file,
+      edits: d.fix.edits ?? [],
+      createFiles: d.fix.createFiles ?? [],
+      deleteFiles: d.fix.deleteFiles ?? []
+    });
+  }
+  if (entries.length === 0) return { applied: [], skipped: [] };
+  const seenEdits = /* @__PURE__ */ new Set();
+  const editsByFile = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    for (const edit of entry.edits) {
+      const key = `${edit.path}:${edit.start}:${edit.end}:${edit.replacement}`;
+      if (seenEdits.has(key)) continue;
+      seenEdits.add(key);
+      let list = editsByFile.get(edit.path);
+      if (!list) {
+        list = [];
+        editsByFile.set(edit.path, list);
+      }
+      list.push({ ...edit, entry });
+    }
+  }
+  for (const [filePath, edits] of editsByFile) {
+    let content;
+    try {
+      content = fs5.readFileSync(filePath, "utf8");
+    } catch {
+      for (const e of edits) e.entry.skippedReason ??= "file is unreadable";
+      continue;
+    }
+    edits.sort((a, b) => a.start - b.start || a.end - b.end);
+    const kept = [];
+    let prevEnd = -1;
+    for (const edit of edits) {
+      if (edit.start < prevEnd) {
+        edit.entry.skippedReason ??= "overlapping edit";
+        continue;
+      }
+      kept.push(edit);
+      prevEnd = edit.end;
+    }
+    for (let i = kept.length - 1; i >= 0; i--) {
+      const edit = kept[i];
+      content = content.slice(0, edit.start) + edit.replacement + content.slice(edit.end);
+    }
+    if (kept.length > 0) fs5.writeFileSync(filePath, content, "utf8");
+  }
+  for (const entry of entries) {
+    if (entry.skippedReason) continue;
+    for (const create of entry.createFiles) {
+      if (fs5.existsSync(create.path)) {
+        entry.skippedReason = `${path8.basename(create.path)} already exists`;
+        continue;
+      }
+      fs5.mkdirSync(path8.dirname(create.path), { recursive: true });
+      fs5.writeFileSync(create.path, create.content, "utf8");
+    }
+    if (entry.skippedReason) continue;
+    for (const del of entry.deleteFiles) {
+      try {
+        fs5.unlinkSync(del);
+      } catch {
+      }
+    }
+  }
+  const applied = [];
+  const skipped = [];
+  for (const entry of entries) {
+    const summary = {
+      code: entry.code,
+      description: entry.description,
+      file: entry.file
+    };
+    if (entry.skippedReason) {
+      skipped.push({ ...summary, reason: entry.skippedReason });
+    } else {
+      applied.push(summary);
+    }
+  }
+  return { applied, skipped };
+}
+
+// src/scanner/scan/rename.ts
+var ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function renameEntity(opts) {
+  const { cwd, kind, oldId, newId, force = false } = opts;
+  const manual = [];
+  const errors = [];
+  if (!ID_RE.test(newId)) {
+    return {
+      edits: 0,
+      manual,
+      errors: [`New id "${newId}" is not kebab-case`]
+    };
+  }
+  const configs = discover({ cwd });
+  if (configs.length === 0) {
+    return { edits: 0, manual, errors: [`No .uidex.json found under ${cwd}`] };
+  }
+  const edits = [];
+  for (const dc of configs) {
+    const { config, configDir } = dc;
+    const sourceFiles = walk(config.sources, {
+      cwd: configDir,
+      globalExcludes: config.exclude
+    });
+    const extracted = extract(sourceFiles);
+    const flowFiles = config.flows ? walk(
+      config.flows.map((glob) => ({ rootDir: ".", include: [glob] })),
+      { cwd: configDir, includeTests: true }
+    ) : [];
+    const extractedFlows = extract(flowFiles);
+    const scan = runScan({ cwd: configDir, configs: [dc] })[0];
+    const registry = scan.registry;
+    if (!registry.get(kind, oldId)) {
+      if (registry.matchPattern(kind, oldId)) {
+        errors.push(
+          `${kind} "${oldId}" only matches via a pattern id; pattern-backed ids cannot be renamed mechanically`
+        );
+      } else {
+        errors.push(`${kind} "${oldId}" not found in registry`);
+      }
+      continue;
+    }
+    if (registry.get(kind, newId) && !force) {
+      errors.push(
+        `${kind} "${newId}" already exists; pass --force to merge the ids`
+      );
+      continue;
+    }
+    const quoteAs = (content, start) => {
+      const q = content[start];
+      return q === '"' || q === "'" || q === "`" ? `${q}${newId}${q}` : `"${newId}"`;
+    };
+    for (const ef of extracted) {
+      for (const a of ef.annotations) {
+        if (a.kind !== kind || a.id !== oldId) continue;
+        if (a.span) {
+          edits.push({
+            path: ef.file.sourcePath,
+            start: a.span.start,
+            end: a.span.end,
+            replacement: quoteAs(ef.file.content, a.span.start)
+          });
+        } else {
+          manual.push({
+            file: a.file,
+            line: a.line,
+            reason: "attribute value is not a plain string literal (const reference, ternary, or template)"
+          });
+        }
+      }
+      for (const m of ef.metadata ?? []) {
+        if (kind === "widget" && m.kind === "widget" && m.id === oldId) {
+          if (m.idSpan) {
+            edits.push({
+              path: ef.file.sourcePath,
+              start: m.idSpan.start,
+              end: m.idSpan.end,
+              replacement: quoteAs(ef.file.content, m.idSpan.start)
+            });
+          } else {
+            manual.push({
+              file: ef.file.displayPath,
+              line: m.loc.line ?? 1,
+              reason: "widget export id is not a plain string literal"
+            });
+          }
+        }
+        if (kind === "widget" && m.widgets) {
+          for (let i = 0; i < m.widgets.length; i++) {
+            if (m.widgets[i] !== oldId) continue;
+            const span = m.widgetSpans?.[i];
+            if (span) {
+              edits.push({
+                path: ef.file.sourcePath,
+                start: span.start,
+                end: span.end,
+                replacement: quoteAs(ef.file.content, span.start)
+              });
+            }
+          }
+        }
+      }
+    }
+    for (const ef of extractedFlows) {
+      for (const fact of ef.flows ?? []) {
+        for (const call of fact.calls) {
+          if (call.id !== oldId) continue;
+          if (call.span) {
+            edits.push({
+              path: ef.file.sourcePath,
+              start: call.span.start,
+              end: call.span.end,
+              replacement: quoteAs(ef.file.content, call.span.start)
+            });
+          } else {
+            manual.push({
+              file: ef.file.displayPath,
+              line: call.line,
+              reason: "uidex() argument is not a plain string literal"
+            });
+          }
+        }
+      }
+    }
+  }
+  if (errors.length > 0) {
+    return { edits: 0, manual, errors };
+  }
+  if (edits.length === 0 && manual.length === 0) {
+    return {
+      edits: 0,
+      manual,
+      errors: [
+        `${kind} "${oldId}" has no editable occurrences (convention-derived ids like landmarks cannot be renamed)`
+      ]
+    };
+  }
+  const result = applyFixes([
+    {
+      code: "rename",
+      severity: "info",
+      message: "",
+      fix: {
+        description: `Rename ${kind} "${oldId}" to "${newId}"`,
+        edits
+      }
+    }
+  ]);
+  if (result.skipped.length > 0) {
+    errors.push(`Some edits were skipped: ${result.skipped[0].reason}`);
+  }
+  for (const r of runScan({ cwd })) writeScanResult(r);
+  return { edits: edits.length, manual, errors };
 }
 
 // src/scanner/scan/cli.ts
-import * as fs7 from "fs";
-import * as path9 from "path";
+import * as fs8 from "fs";
+import * as path11 from "path";
 
 // src/scanner/scan/ai/index.ts
 import * as p from "@clack/prompts";
 
 // src/scanner/scan/ai/providers/claude.ts
-import * as fs6 from "fs";
-import * as path8 from "path";
+import * as fs7 from "fs";
+import * as path10 from "path";
 
 // src/scanner/scan/ai/templates.ts
-import * as fs5 from "fs";
-import * as path7 from "path";
+import * as fs6 from "fs";
+import * as path9 from "path";
 function templatePath(rel) {
   const candidates = [
-    path7.resolve(__dirname, "../../templates", rel),
-    // dist/cli/cli.cjs    → ../../templates
-    path7.resolve(__dirname, "../../../templates", rel)
-    // src/scan/ai/foo.ts → ../../../templates
+    path9.resolve(__dirname, "../../templates", rel),
+    // dist/cli/cli.cjs         → ../../templates
+    path9.resolve(__dirname, "../../../../templates", rel)
+    // src/scanner/scan/ai → ../../../../templates
   ];
   for (const c of candidates) {
     try {
-      fs5.accessSync(c, fs5.constants.R_OK);
+      fs6.accessSync(c, fs6.constants.R_OK);
       return c;
     } catch {
       continue;
@@ -3091,24 +4088,39 @@ function templatePath(rel) {
   );
 }
 function readTemplate(rel) {
-  return fs5.readFileSync(templatePath(rel), "utf8");
+  return fs6.readFileSync(templatePath(rel), "utf8");
 }
 
 // src/scanner/scan/ai/providers/claude.ts
-var CLAUDE_FILES = [
-  { dest: ".claude/rules/uidex.md", template: "claude/rules.md" },
-  { dest: ".claude/commands/uidex/audit.md", template: "claude/audit.md" },
-  { dest: ".claude/commands/uidex/api.md", template: "claude/api.md" }
+var SKILL_FILES = [
+  { dest: ".claude/skills/uidex/SKILL.md", template: "claude/SKILL.md" },
+  {
+    dest: ".claude/skills/uidex/references/conventions.md",
+    template: "claude/references/conventions.md"
+  },
+  {
+    dest: ".claude/skills/uidex/references/audit.md",
+    template: "claude/references/audit.md"
+  },
+  {
+    dest: ".claude/skills/uidex/references/api.md",
+    template: "claude/references/api.md"
+  }
+];
+var LEGACY_FILES = [
+  ".claude/rules/uidex.md",
+  ".claude/commands/uidex/audit.md",
+  ".claude/commands/uidex/api.md"
 ];
 var claudeProvider = {
   id: "claude",
   label: "Claude Code",
-  description: "Adds .claude/rules/uidex.md, /uidex:audit, and /uidex:api slash commands.",
+  description: "Adds .claude/skills/uidex/ skill with conventions, audit, and API references.",
   async install({ cwd, force }) {
     const changes = [];
-    for (const file of CLAUDE_FILES) {
-      const dest = path8.join(cwd, file.dest);
-      const exists = fs6.existsSync(dest);
+    for (const file of SKILL_FILES) {
+      const dest = path10.join(cwd, file.dest);
+      const exists = fs7.existsSync(dest);
       if (exists && !force) {
         changes.push({
           path: file.dest,
@@ -3117,36 +4129,56 @@ var claudeProvider = {
         });
         continue;
       }
-      fs6.mkdirSync(path8.dirname(dest), { recursive: true });
-      fs6.writeFileSync(dest, readTemplate(file.template));
+      fs7.mkdirSync(path10.dirname(dest), { recursive: true });
+      fs7.writeFileSync(dest, readTemplate(file.template));
       changes.push({
         path: file.dest,
         action: exists ? "overwritten" : "created"
       });
     }
+    for (const rel of LEGACY_FILES) {
+      const dest = path10.join(cwd, rel);
+      if (fs7.existsSync(dest)) {
+        fs7.unlinkSync(dest);
+        changes.push({ path: rel, action: "removed" });
+      }
+    }
+    cleanupEmpty(path10.join(cwd, ".claude/commands/uidex"));
+    cleanupEmpty(path10.join(cwd, ".claude/commands"));
+    cleanupEmpty(path10.join(cwd, ".claude/rules"));
     return { changes };
   },
   async uninstall({ cwd }) {
     const changes = [];
-    for (const file of CLAUDE_FILES) {
-      const dest = path8.join(cwd, file.dest);
-      if (!fs6.existsSync(dest)) {
+    for (const file of SKILL_FILES) {
+      const dest = path10.join(cwd, file.dest);
+      if (!fs7.existsSync(dest)) {
         changes.push({ path: file.dest, action: "skipped", reason: "absent" });
         continue;
       }
-      fs6.unlinkSync(dest);
+      fs7.unlinkSync(dest);
       changes.push({ path: file.dest, action: "removed" });
     }
-    cleanupEmpty(path8.join(cwd, ".claude/commands/uidex"));
-    cleanupEmpty(path8.join(cwd, ".claude/commands"));
-    cleanupEmpty(path8.join(cwd, ".claude/rules"));
+    cleanupEmpty(path10.join(cwd, ".claude/skills/uidex/references"));
+    cleanupEmpty(path10.join(cwd, ".claude/skills/uidex"));
+    cleanupEmpty(path10.join(cwd, ".claude/skills"));
+    for (const rel of LEGACY_FILES) {
+      const dest = path10.join(cwd, rel);
+      if (fs7.existsSync(dest)) {
+        fs7.unlinkSync(dest);
+        changes.push({ path: rel, action: "removed" });
+      }
+    }
+    cleanupEmpty(path10.join(cwd, ".claude/commands/uidex"));
+    cleanupEmpty(path10.join(cwd, ".claude/commands"));
+    cleanupEmpty(path10.join(cwd, ".claude/rules"));
     return { changes };
   }
 };
 function cleanupEmpty(dir) {
   try {
-    const entries = fs6.readdirSync(dir);
-    if (entries.length === 0) fs6.rmdirSync(dir);
+    const entries = fs7.readdirSync(dir);
+    if (entries.length === 0) fs7.rmdirSync(dir);
   } catch {
   }
 }
@@ -3313,6 +4345,8 @@ async function run(opts) {
         return runScanCommand(cwd, flags, writer);
       case "scaffold":
         return runScaffold(cwd, positional.slice(1), flags, writer);
+      case "rename":
+        return runRename(cwd, positional.slice(1), flags, writer);
       case "ai": {
         const result = await runAiCommand({
           cwd,
@@ -3339,25 +4373,24 @@ function helpText2() {
     "Commands:",
     "  init                  Create a .uidex.json",
     "  scan [flags]          Run the scanner pipeline",
-    "  scaffold widget <id>  Emit a Playwright spec from a widget's acceptance",
+    "  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, legacy JSDoc)",
+    "  --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",
     ""
   ].join("\n");
 }
 function runInit(cwd, w) {
-  const configPath = path9.join(cwd, CONFIG_FILENAME);
-  if (fs7.existsSync(configPath)) {
+  const configPath = path11.join(cwd, CONFIG_FILENAME);
+  if (fs8.existsSync(configPath)) {
     w.err(`.uidex.json already exists at ${configPath}`);
     return w.result(1);
   }
@@ -3366,16 +4399,16 @@ function runInit(cwd, w) {
     sources: [{ rootDir: "src" }],
     output: "src/uidex.gen.ts"
   };
-  fs7.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+  fs8.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
   w.out(`Created ${configPath}`);
-  const gitignorePath = path9.join(cwd, ".gitignore");
-  const entry = "*.gen.ts";
-  if (fs7.existsSync(gitignorePath)) {
-    const existing = fs7.readFileSync(gitignorePath, "utf8");
+  const gitignorePath = path11.join(cwd, ".gitignore");
+  const entry = "*.gen.*";
+  if (fs8.existsSync(gitignorePath)) {
+    const existing = fs8.readFileSync(gitignorePath, "utf8");
     const hasEntry = existing.split("\n").some((line) => line.trim() === entry);
     if (!hasEntry) {
       const needsNewline = existing.length > 0 && !existing.endsWith("\n");
-      fs7.appendFileSync(
+      fs8.appendFileSync(
         gitignorePath,
         `${needsNewline ? "\n" : ""}${entry}
 `,
@@ -3384,24 +4417,62 @@ function runInit(cwd, w) {
       w.out(`Appended ${entry} to ${gitignorePath}`);
     }
   } else {
-    fs7.writeFileSync(gitignorePath, `${entry}
+    fs8.writeFileSync(gitignorePath, `${entry}
 `, "utf8");
     w.out(`Created ${gitignorePath} with ${entry}`);
   }
   return w.result(0);
 }
 function runScanCommand(cwd, flags, w) {
-  const check = Boolean(flags.check || flags.audit);
-  const lint = Boolean(flags.lint || flags.audit);
+  const fix = Boolean(flags.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);
-  const configs = discover({ cwd });
+  let configs = discover({ cwd });
   if (configs.length === 0) {
     w.err(`No ${CONFIG_FILENAME} found under ${cwd}`);
     return w.result(1);
   }
+  let fixed = [];
+  let fixSkipped = [];
+  if (fix) {
+    const discovery = runScan({ cwd, check: true, lint: true, configs });
+    const result = applyFixes(
+      discovery.flatMap((r) => r.audit?.diagnostics ?? [])
+    );
+    fixed = result.applied;
+    fixSkipped = result.skipped;
+    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(
@@ -3413,19 +4484,38 @@ function runScanCommand(cwd, flags, w) {
     { errors: 0, warnings: 0 }
   );
   if (asJson) {
-    const out2 = { diagnostics: allDiagnostics, summary };
+    const out2 = {
+      diagnostics: allDiagnostics.map(jsonDiagnostic),
+      summary,
+      ...fix ? { fixed, fixSkipped } : {}
+    };
     w.out(JSON.stringify(out2, null, 2));
   } else {
+    for (const f of fixed) {
+      w.out(`FIXED [${f.code}] ${f.file ?? ""} ${f.description}`);
+    }
+    for (const s of fixSkipped) {
+      w.out(
+        `SKIPPED [${s.code}] ${s.file ?? ""} ${s.description} (${s.reason})`
+      );
+    }
     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}` : ""}` : "";
         const stream = d.severity === "error" ? w.err : w.out;
-        stream(`${d.severity.toUpperCase()} [${d.code}] ${loc} ${d.message}`);
+        const fixable = d.fix && !fix ? " [fixable: run with --fix]" : "";
+        stream(
+          `${d.severity.toUpperCase()} [${d.code}] ${loc} ${d.message}${fixable}`
+        );
         if (d.hint) stream(`  hint: ${d.hint}`);
       }
     }
@@ -3436,20 +4526,27 @@ function runScanCommand(cwd, flags, w) {
   const exit = summary.errors > 0 ? 1 : 0;
   return w.result(exit);
 }
+function jsonDiagnostic(d) {
+  const { fix, ...rest } = d;
+  return fix ? { ...rest, fixable: true } : rest;
+}
+var SCAFFOLD_KINDS = /* @__PURE__ */ new Set(["widget", "page", "feature"]);
 function runScaffold(cwd, args, flags, w) {
   const [kind, id] = args;
-  if (kind !== "widget" || !id) {
-    w.err("Usage: uidex scaffold widget <id> [--force]");
+  if (!kind || !SCAFFOLD_KINDS.has(kind) || !id) {
+    w.err("Usage: uidex scaffold <widget|page|feature> <id> [--force]");
     return w.result(1);
   }
+  const scaffoldKind = kind;
   const results = runScan({ cwd });
   for (const r of results) {
-    const widget = r.registry.get("widget", id);
-    if (!widget) continue;
-    const outDir = path9.resolve(r.configDir, "e2e");
-    const result = scaffoldWidgetSpec({
+    const entity = r.registry.get(scaffoldKind, id);
+    if (!entity) continue;
+    const outDir = path11.resolve(r.configDir, "e2e");
+    const result = scaffoldSpec({
       registry: r.registry,
-      widgetId: id,
+      kind: scaffoldKind,
+      id,
       outDir,
       force: Boolean(flags.force)
     });
@@ -3460,9 +4557,43 @@ function runScaffold(cwd, args, flags, w) {
     w.out(`Wrote ${result.outputPath}`);
     return w.result(0);
   }
-  w.err(`Widget "${id}" not found in registry`);
+  w.err(
+    `${scaffoldKind.charAt(0).toUpperCase() + scaffoldKind.slice(1)} "${id}" not found in registry`
+  );
   return w.result(1);
 }
+var RENAME_KINDS = /* @__PURE__ */ new Set(["element", "widget", "region"]);
+function runRename(cwd, args, flags, w) {
+  const [kind, oldId, newId] = args;
+  if (!kind || !RENAME_KINDS.has(kind) || !oldId || !newId) {
+    w.err(
+      "Usage: uidex rename <element|widget|region> <old-id> <new-id> [--force]"
+    );
+    return w.result(1);
+  }
+  const result = renameEntity({
+    cwd,
+    kind,
+    oldId,
+    newId,
+    force: Boolean(flags.force)
+  });
+  for (const e of result.errors) w.err(e);
+  for (const m of result.manual) {
+    w.err(`MANUAL ${m.file}:${m.line} \u2014 ${m.reason}`);
+  }
+  if (result.errors.length > 0) return w.result(1);
+  w.out(
+    `Renamed ${kind} "${oldId}" \u2192 "${newId}" (${result.edits} edit(s)); gen file regenerated`
+  );
+  if (result.manual.length > 0) {
+    w.err(
+      `${result.manual.length} occurrence(s) need manual follow-up (listed above)`
+    );
+    return w.result(1);
+  }
+  return w.result(0);
+}
 function createWriter() {
   let stdout = "";
   let stderr = "";
@@ -3482,20 +4613,31 @@ export {
   CONFIG_FILENAME,
   ConfigError,
   DEFAULT_CONVENTIONS,
-  DEFAULT_TYPE_MODE,
+  applyFixes,
   audit,
+  checkPageCoverage,
+  checkStateCoverage,
+  checkStateMatrix,
+  compileRoute,
+  computeMissingKinds,
+  computePageBaseline,
   detectRoutes,
   discover,
   emit,
   extract,
   extractUidexExports,
   globToRegExp,
+  loadPageBaseline,
+  matchUrlToRoute,
+  pageBaselinePath,
   parseConfig,
   pathToId,
+  renameEntity,
   resolve2 as resolve,
   resolveGitContext,
   run as runCli,
   runScan,
+  scaffoldSpec,
   scaffoldWidgetSpec,
   validateConfig,
   walk,