uidex 0.7.0 → 0.9.0

package/dist/cli/cli.cjs

@@ -181,14 +181,14 @@ ${helpText()}`);
   const provider = await selectProvider(opts, flags.provider);
   if (!provider) return out(0, "Cancelled.\n");
   if (sub === "install") {
-    const result3 = await provider.install({
+    const result2 = await provider.install({
       cwd,
       force: flags.force === true
     });
-    return out(0, formatChanges(provider, "Installed", result3));
+    return out(0, formatChanges(provider, "Installed", result2));
   }
-  const result2 = await provider.uninstall({ cwd });
-  return out(0, formatChanges(provider, "Uninstalled", result2));
+  const result = await provider.uninstall({ cwd });
+  return out(0, formatChanges(provider, "Uninstalled", result));
 }
 async function selectProvider(opts, explicit) {
   if (explicit) {
@@ -231,9 +231,9 @@ function parseFlags(args) {
   }
   return flags;
 }
-function formatChanges(provider, verb, result2) {
+function formatChanges(provider, verb, result) {
   const lines = [`${verb} ${provider.label}:`];
-  for (const c of result2.changes) lines.push(`  ${describe(c)}`);
+  for (const c of result.changes) lines.push(`  ${describe(c)}`);
   return lines.join("\n") + "\n";
 }
 function describe(c) {
@@ -300,7 +300,9 @@ var ALLOWED_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
   "output",
   "flows",
   "audit",
-  "conventions"
+  "conventions",
+  "statesManifest",
+  "coverageBaseline"
 ]);
 var ALLOWED_SOURCE_KEYS = /* @__PURE__ */ new Set(["rootDir", "include", "exclude", "prefix"]);
 var ALLOWED_CONVENTIONS_KEYS = /* @__PURE__ */ new Set([
@@ -310,7 +312,14 @@ var ALLOWED_CONVENTIONS_KEYS = /* @__PURE__ */ new Set([
   "flows",
   "regions"
 ]);
-var ALLOWED_AUDIT_KEYS = /* @__PURE__ */ new Set(["scopeLeak", "coverage", "acceptance"]);
+var ALLOWED_AUDIT_KEYS = /* @__PURE__ */ new Set([
+  "scopeLeak",
+  "coverage",
+  "acceptance",
+  "states",
+  "pageCoverage",
+  "stateMatrix"
+]);
 function fail(msg) {
   throw new ConfigError(`Invalid .uidex.json: ${msg}`);
 }
@@ -369,6 +378,12 @@ function validateConfig(raw) {
   }
   if (raw.exclude !== void 0) assertStringArray(raw.exclude, `exclude`);
   if (raw.flows !== void 0) assertStringArray(raw.flows, `flows`);
+  if (raw.statesManifest !== void 0 && typeof raw.statesManifest !== "string") {
+    fail(`"statesManifest" must be a string`);
+  }
+  if (raw.coverageBaseline !== void 0 && typeof raw.coverageBaseline !== "string") {
+    fail(`"coverageBaseline" must be a string`);
+  }
   if (raw.audit !== void 0) {
     assertObject(raw.audit, "audit");
     for (const key of Object.keys(raw.audit)) {
@@ -392,7 +407,13 @@ function validateConfig(raw) {
       fail(`conventions.features must be a string or false`);
     }
     if (c.pages !== void 0 && c.pages !== false && c.pages !== "auto") {
-      fail(`conventions.pages must be "auto" or false`);
+      const p2 = c.pages;
+      const routesDir = typeof p2 === "object" && p2 !== null && !Array.isArray(p2) ? p2.routesDir : void 0;
+      if (typeof p2 !== "object" || p2 === null || Array.isArray(p2) || Object.keys(p2).some((k) => k !== "routesDir") || typeof routesDir !== "string" || routesDir.length === 0) {
+        fail(
+          `conventions.pages must be "auto", false, or { routesDir: string }`
+        );
+      }
     }
     if (c.flows !== void 0 && c.flows !== false) {
       assertStringArray(c.flows, "conventions.flows");
@@ -408,7 +429,9 @@ function validateConfig(raw) {
     output: raw.output,
     flows: raw.flows,
     audit: raw.audit,
-    conventions: raw.conventions
+    conventions: raw.conventions,
+    statesManifest: raw.statesManifest,
+    coverageBaseline: raw.coverageBaseline
   };
 }
 function parseConfig(json) {
@@ -598,6 +621,12 @@ var ENTITY_KINDS = [
   "primitive",
   "flow"
 ];
+var CORE_STATE_KINDS = [
+  "loading",
+  "empty",
+  "populated",
+  "error"
+];
 function isMetaKind(kind) {
   return kind !== "route" && kind !== "flow";
 }
@@ -731,11 +760,11 @@ function createRegistry() {
   };
   const query = (predicate) => {
     const flows = getFlows();
-    const result2 = [];
+    const result = [];
     for (const entity of allEntities()) {
-      if (predicate(entity)) result2.push(freezeEntity(entity, flows));
+      if (predicate(entity)) result.push(freezeEntity(entity, flows));
     }
-    return result2;
+    return result;
   };
   const byScope = (scope) => query(
     (entity) => "scopes" in entity && Array.isArray(entity.scopes) && entity.scopes.includes(scope)
@@ -776,6 +805,295 @@ function createRegistry() {
   };
 }
 
+// src/scanner/scan/page-coverage.ts
+function compileRoute(pattern) {
+  const segs = pattern.split("/").filter(Boolean);
+  let specificity = 0;
+  const optionalTail = segs.length > 0 && /^\[\[\.{3}.+\]\]$/.test(segs[segs.length - 1]);
+  const effective = optionalTail ? segs.slice(0, -1) : segs;
+  const parts = effective.map((seg) => {
+    const catchAll = /^\[\.{3}.+\]$/.test(seg);
+    const dynamic = /^\[.+\]$/.test(seg);
+    if (catchAll) return "(?:[^/]+)(?:/[^/]+)*";
+    if (dynamic) return "[^/]+";
+    specificity++;
+    return seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  });
+  let body = parts.length === 0 ? "" : "/" + parts.join("/");
+  if (optionalTail) body += "(?:/[^/]+)*";
+  if (body === "") body = "/";
+  const re = new RegExp(`^${body}/?$`);
+  return { test: (url) => re.test(url), specificity };
+}
+function matchUrlToRoute(url, routePaths) {
+  const path12 = stripQuery(url);
+  let best = null;
+  for (const rp of routePaths) {
+    const { test, specificity } = compileRoute(rp);
+    if (!test(path12)) continue;
+    if (!best || specificity > best.specificity)
+      best = { path: rp, specificity };
+  }
+  return best?.path ?? null;
+}
+function stripQuery(url) {
+  const q = url.indexOf("?");
+  const h = url.indexOf("#");
+  let end = url.length;
+  if (q !== -1) end = Math.min(end, q);
+  if (h !== -1) end = Math.min(end, h);
+  return url.slice(0, end);
+}
+function routeForCapture(c, routes, routePaths) {
+  if (c.route && routePaths.includes(c.route)) return c.route;
+  if (c.url) {
+    const m = matchUrlToRoute(c.url, routePaths);
+    if (m) return m;
+  }
+  if (c.kind === "page") {
+    const r = routes.find((r2) => r2.page === c.entity);
+    if (r) return r.path;
+  }
+  return null;
+}
+function checkPageCoverage(registry, manifest, baseline) {
+  const routes = registry.list("route");
+  if (routes.length === 0) return [];
+  const routePaths = routes.map((r) => r.path);
+  const captured = manifest.captured ?? [];
+  const optedOut = /* @__PURE__ */ new Set();
+  for (const r of routes) {
+    const page = registry.get("page", r.page);
+    if (page?.meta?.capture === false) optedOut.add(r.path);
+  }
+  const covered = /* @__PURE__ */ new Set();
+  for (const c of captured) {
+    const route = routeForCapture(c, routes, routePaths);
+    if (route) covered.add(route);
+  }
+  const baselineSet = new Set(baseline?.uncapturedPages ?? []);
+  const diagnostics = [];
+  for (const r of routes) {
+    if (covered.has(r.path) || optedOut.has(r.path)) continue;
+    const loc = registry.get("page", r.page)?.loc;
+    if (baselineSet.has(r.path)) {
+      diagnostics.push({
+        code: "page-backlog",
+        severity: "info",
+        message: `route "${r.path}" has no visual-states capture (acknowledged backlog)`,
+        file: loc?.file,
+        line: loc?.line,
+        hint: `Capture it (drive the route in a states spec) and it drops off the baseline, or opt it out with \`export const uidex = { page: "${r.page}", capture: false }\`.`
+      });
+      continue;
+    }
+    diagnostics.push({
+      code: "page-no-capture",
+      severity: "error",
+      message: `route "${r.path}" has no visual-states capture and is not accounted for`,
+      file: loc?.file,
+      line: loc?.line,
+      entity: { kind: "route", id: r.path },
+      hint: `Capture the route in a states spec, opt it out with \`export const uidex = { page: "${r.page}", capture: false }\`, or grandfather it as acknowledged backlog with \`uidex scan --update-baseline\` (the baseline change lands in the diff for review).`
+    });
+  }
+  for (const b of baselineSet) {
+    if (!routePaths.includes(b)) {
+      diagnostics.push({
+        code: "stale-page-baseline",
+        severity: "warning",
+        message: `coverage baseline lists "${b}", which is not a route in the registry`,
+        hint: `Remove it from the baseline (\`uidex scan --update-baseline\`); the route no longer exists.`
+      });
+    } else if (covered.has(b) || optedOut.has(b)) {
+      diagnostics.push({
+        code: "page-captured",
+        severity: "warning",
+        message: `route "${b}" is now captured but is still in the coverage baseline`,
+        hint: `Prune it with \`uidex scan --update-baseline\` so the backlog reflects reality.`
+      });
+    }
+  }
+  return diagnostics;
+}
+function computePageBaseline(registry, manifest) {
+  const uncaptured = [];
+  for (const d of checkPageCoverage(registry, manifest, {
+    uncapturedPages: []
+  })) {
+    if (d.code === "page-no-capture" && d.entity) uncaptured.push(d.entity.id);
+  }
+  return { uncapturedPages: uncaptured.sort() };
+}
+
+// src/scanner/scan/state-coverage.ts
+var STATE_KINDS = ["page", "feature", "widget"];
+function declaredStateEntities(registry) {
+  const out2 = [];
+  for (const kind of STATE_KINDS) {
+    for (const e of registry.list(kind)) {
+      const states = e.meta?.states;
+      if (!states || states.length === 0) continue;
+      out2.push({
+        kind,
+        id: e.id,
+        states: states.map((s) => s.name),
+        loc: e.loc
+      });
+    }
+  }
+  return out2;
+}
+function captureMatchesEntity(cap, ent) {
+  if (cap.entity !== ent.id) return false;
+  return cap.kind === void 0 || cap.kind === ent.kind;
+}
+function checkStateCoverage(registry, manifest) {
+  const diagnostics = [];
+  const declared = declaredStateEntities(registry);
+  const captured = manifest.captured ?? [];
+  for (const ent of declared) {
+    for (const state of ent.states) {
+      const hit = captured.some(
+        (c) => captureMatchesEntity(c, ent) && c.state === state
+      );
+      if (hit) continue;
+      diagnostics.push({
+        code: "missing-state-capture",
+        severity: "warning",
+        message: `${ent.kind} "${ent.id}" declares state "${state}" but no capture produced it`,
+        file: ent.loc?.file,
+        line: ent.loc?.line,
+        entity: { kind: ent.kind, id: ent.id },
+        hint: `Add a capture for "${ent.id}/${state}" to the states matrix, or remove the state from \`export const uidex = { states: [...] }\` if it no longer exists.`
+      });
+    }
+  }
+  for (const cap of captured) {
+    const candidates = declared.filter((ent2) => captureMatchesEntity(cap, ent2));
+    if (candidates.length === 0) continue;
+    const declaredSomewhere = candidates.some(
+      (ent2) => ent2.states.includes(cap.state)
+    );
+    if (declaredSomewhere) continue;
+    const ent = candidates[0];
+    diagnostics.push({
+      code: "orphan-state-capture",
+      severity: "warning",
+      message: `Capture produced state "${cap.state}" for ${ent.kind} "${ent.id}", which is not in its declared states [${ent.states.join(", ")}]`,
+      file: ent.loc?.file,
+      line: ent.loc?.line,
+      entity: { kind: ent.kind, id: ent.id },
+      hint: `Declare "${cap.state}" in \`export const uidex = { states: [...] }\` for "${ent.id}", or rename the capture to a declared state.`
+    });
+  }
+  return diagnostics;
+}
+
+// src/scanner/scan/state-matrix.ts
+var CORE_KINDS = CORE_STATE_KINDS;
+var STATE_ENTITY_KINDS = ["page", "feature", "widget"];
+function resolveMatrixKind(registry, c) {
+  if (c.stateKind) return c.stateKind;
+  for (const kind of STATE_ENTITY_KINDS) {
+    const declared = registry.get(kind, c.entity)?.meta?.states?.find((s) => s.name === c.state)?.kind;
+    if (declared) return declared;
+  }
+  return CORE_KINDS.includes(c.state) ? c.state : "variant";
+}
+function coreKindsByRoute(registry, manifest) {
+  const routes = registry.list("route");
+  const routePaths = routes.map((r) => r.path);
+  const byRoute = /* @__PURE__ */ new Map();
+  for (const c of manifest.captured ?? []) {
+    const route = routeForCapture(c, routes, routePaths);
+    if (!route) continue;
+    if (!byRoute.has(route)) byRoute.set(route, /* @__PURE__ */ new Set());
+    const kind = resolveMatrixKind(registry, c);
+    if (CORE_KINDS.includes(kind)) byRoute.get(route).add(kind);
+  }
+  return byRoute;
+}
+function pageWaivers(registry, routePage) {
+  return registry.get("page", routePage)?.meta?.waivers ?? {};
+}
+function isOptedOut(registry, page) {
+  return page ? registry.get("page", page)?.meta?.capture === false : false;
+}
+function checkStateMatrix(registry, manifest, baseline) {
+  const routes = registry.list("route");
+  if (routes.length === 0) return [];
+  const pageOf = new Map(routes.map((r) => [r.path, r.page]));
+  const captured = coreKindsByRoute(registry, manifest);
+  const baselined = baseline?.missingKinds ?? {};
+  const diagnostics = [];
+  for (const [route, kinds] of captured) {
+    const page = pageOf.get(route);
+    if (isOptedOut(registry, page)) continue;
+    const waivers = page ? pageWaivers(registry, page) : {};
+    const loc = page ? registry.get("page", page)?.loc : void 0;
+    const baselinedKinds = new Set(baselined[route] ?? []);
+    for (const kind of CORE_KINDS) {
+      if (kinds.has(kind)) continue;
+      if (waivers[kind]) continue;
+      if (baselinedKinds.has(kind)) {
+        diagnostics.push({
+          code: "matrix-backlog",
+          severity: "info",
+          message: `route "${route}" does not render core kind "${kind}" (acknowledged MISSING_KINDS backlog)`,
+          file: loc?.file,
+          line: loc?.line,
+          hint: `Capture the "${kind}" state for "${route}", waive it (\`waivers: { ${kind}: "why it can't" }\` on the page), or leave it in the baseline.`
+        });
+        continue;
+      }
+      diagnostics.push({
+        code: "core-kind",
+        severity: "error",
+        message: `route "${route}" is captured but never renders core kind "${kind}"`,
+        file: loc?.file,
+        line: loc?.line,
+        entity: { kind: "route", id: route },
+        hint: `Capture the "${kind}" state, or if the route cannot render it add \`export const uidex = { page: "${page}", waivers: { ${kind}: "why it can't" } }\`, or grandfather it via \`uidex scan --update-baseline\` (the baseline change lands in the diff for review).`
+      });
+    }
+  }
+  for (const [route, kinds] of captured) {
+    const page = pageOf.get(route);
+    if (!page || isOptedOut(registry, page)) continue;
+    const waivers = pageWaivers(registry, page);
+    const loc = registry.get("page", page)?.loc;
+    for (const kind of Object.keys(waivers)) {
+      if (kinds.has(kind)) {
+        diagnostics.push({
+          code: "stale-waiver",
+          severity: "warning",
+          message: `page "${page}" waives core kind "${kind}", but route "${route}" does render it`,
+          file: loc?.file,
+          line: loc?.line,
+          entity: { kind: "page", id: page },
+          hint: `Remove the "${kind}" waiver \u2014 the route renders that kind, so the waiver's reason is stale.`
+        });
+      }
+    }
+  }
+  return diagnostics;
+}
+function computeMissingKinds(registry, manifest) {
+  const routes = registry.list("route");
+  const pageOf = new Map(routes.map((r) => [r.path, r.page]));
+  const captured = coreKindsByRoute(registry, manifest);
+  const out2 = {};
+  for (const [route, kinds] of captured) {
+    const page = pageOf.get(route);
+    if (isOptedOut(registry, page)) continue;
+    const waivers = page ? pageWaivers(registry, page) : {};
+    const missing = CORE_KINDS.filter((k) => !kinds.has(k) && !waivers[k]);
+    if (missing.length > 0) out2[route] = missing;
+  }
+  return out2;
+}
+
 // src/scanner/scan/audit.ts
 function audit(opts) {
   const diagnostics = [];
@@ -785,6 +1103,9 @@ function audit(opts) {
   const acceptanceEnabled = config.audit?.acceptance ?? true;
   const scopeLeakEnabled = config.audit?.scopeLeak ?? true;
   const coverageEnabled = config.audit?.coverage ?? true;
+  const statesEnabled = config.audit?.states ?? true;
+  const pageCoverageEnabled = config.audit?.pageCoverage ?? true;
+  const stateMatrixEnabled = config.audit?.stateMatrix ?? true;
   if (opts.resolveDiagnostics) diagnostics.push(...opts.resolveDiagnostics);
   for (const ef of extracted) {
     if (ef.diagnostics) diagnostics.push(...ef.diagnostics);
@@ -818,6 +1139,48 @@ function audit(opts) {
       }
     }
   }
+  if (check && opts.typesGenerated !== void 0) {
+    const outRel = opts.typesOutputPath ?? config.output;
+    const fresh = normalizeForCheck(opts.typesGenerated);
+    if (opts.typesOnDisk === null || opts.typesOnDisk === void 0) {
+      diagnostics.push({
+        code: "gen-missing",
+        severity: "error",
+        message: `Generated file "${outRel}" does not exist on disk; run \`uidex scan\` and commit the result`,
+        file: outRel,
+        hint: "Run `uidex scan` (without --check) to regenerate"
+      });
+    } else if (normalizeForCheck(opts.typesOnDisk) !== fresh) {
+      diagnostics.push({
+        code: "gen-stale",
+        severity: "error",
+        message: `Generated file "${outRel}" is stale`,
+        file: outRel,
+        hint: "Run `uidex scan` (without --check) to regenerate and commit the result"
+      });
+    }
+  }
+  if (check && opts.locsGenerated !== void 0) {
+    const outRel = opts.locsOutputPath ?? config.output;
+    const fresh = normalizeForCheck(opts.locsGenerated);
+    if (opts.locsOnDisk === null || opts.locsOnDisk === void 0) {
+      diagnostics.push({
+        code: "gen-missing",
+        severity: "error",
+        message: `Generated file "${outRel}" does not exist on disk; run \`uidex scan\` and commit the result`,
+        file: outRel,
+        hint: "Run `uidex scan` (without --check) to regenerate"
+      });
+    } else if (normalizeForCheck(opts.locsOnDisk) !== fresh) {
+      diagnostics.push({
+        code: "gen-stale",
+        severity: "error",
+        message: `Generated file "${outRel}" is stale`,
+        file: outRel,
+        hint: "Run `uidex scan` (without --check) to regenerate and commit the result"
+      });
+    }
+  }
   if (lint && acceptanceEnabled) {
     for (const kind of ["widget", "feature", "page"]) {
       for (const e of registry.list(kind)) {
@@ -1077,6 +1440,21 @@ function audit(opts) {
       }
     }
   }
+  if (lint && statesEnabled && opts.capturedStates) {
+    diagnostics.push(...checkStateCoverage(registry, opts.capturedStates));
+  }
+  if (lint && pageCoverageEnabled && opts.capturedStates) {
+    diagnostics.push(
+      ...checkPageCoverage(registry, opts.capturedStates, opts.pageBaseline)
+    );
+  }
+  if (lint && stateMatrixEnabled && opts.capturedStates) {
+    diagnostics.push(
+      ...checkStateMatrix(registry, opts.capturedStates, {
+        missingKinds: opts.pageBaseline?.missingKinds ?? {}
+      })
+    );
+  }
   const summary = {
     errors: diagnostics.filter((d) => d.severity === "error").length,
     warnings: diagnostics.filter((d) => d.severity === "warning").length
@@ -1241,6 +1619,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));
 }
@@ -1266,6 +1786,20 @@ function emitIdUnion(name, ids) {
 ${body}
 `;
 }
+var OPAQUE_ID_UNIONS = /* @__PURE__ */ new Set(["ElementId"]);
+function emitId(name, ids) {
+  if (OPAQUE_ID_UNIONS.has(name)) {
+    return `export type ${name} = string & { readonly __uidex?: ${JSON.stringify(name)} }
+`;
+  }
+  return emitIdUnion(name, ids);
+}
+function dataOutputPath(output) {
+  return output.replace(/\.(d\.ts|ts|tsx|mts|cts|js|mjs|cjs)$/, ".data.$1");
+}
+function locsOutputPath(output) {
+  return output.replace(/\.(d\.ts|ts|tsx|mts|cts|js|mjs|cjs)$/, ".locs.$1");
+}
 function emit(opts) {
   const { registry, gitContext, uidexImport = "uidex" } = opts;
   const routes = [...registry.list("route")].sort(
@@ -1274,112 +1808,131 @@ function emit(opts) {
   const pages = sortById(registry.list("page"));
   const features = sortById(registry.list("feature"));
   const widgets = sortById(registry.list("widget"));
+  const stateNames = /* @__PURE__ */ new Set();
+  for (const e of [...pages, ...features, ...widgets]) {
+    for (const s of e.meta?.states ?? []) stateNames.add(s.name);
+  }
   const regions = sortById(registry.list("region"));
   const elements = sortById(registry.list("element"));
   const primitives = sortById(registry.list("primitive"));
   const flows = sortById(registry.list("flow"));
-  const lines = [];
-  lines.push("// THIS FILE IS AUTO-GENERATED BY `uidex scan`. DO NOT EDIT.");
-  lines.push("/* eslint-disable */");
-  lines.push(`import { createUidex } from ${JSON.stringify(uidexImport)}`);
-  lines.push(
-    `import type { Entity, Registry } from ${JSON.stringify(uidexImport)}`
+  const t = [];
+  t.push("// THIS FILE IS AUTO-GENERATED BY `uidex scan`. DO NOT EDIT.");
+  t.push(
+    "// Types only \u2014 the runtime registry lives in the sibling `.data` module."
   );
-  lines.push("");
-  lines.push("// ---- id unions ----");
-  lines.push(
-    emitIdUnion(
+  t.push("/* eslint-disable */");
+  t.push("");
+  t.push("// ---- id unions ----");
+  t.push(
+    emitId(
       "PageId",
       pages.map((e) => e.id)
     )
   );
-  lines.push(
-    emitIdUnion(
+  t.push(
+    emitId(
       "FeatureId",
       features.map((e) => e.id)
     )
   );
-  lines.push(
-    emitIdUnion(
+  t.push(
+    emitId(
       "WidgetId",
       widgets.map((e) => e.id)
     )
   );
-  lines.push(
-    emitIdUnion(
+  t.push(
+    emitId(
       "RegionId",
       regions.map((e) => e.id)
     )
   );
-  lines.push(
-    emitIdUnion(
+  t.push(
+    emitId(
       "ElementId",
       elements.map((e) => e.id)
     )
   );
-  lines.push(
-    emitIdUnion(
+  t.push(
+    emitId(
       "PrimitiveId",
       primitives.map((e) => e.id)
     )
   );
-  lines.push(
-    emitIdUnion(
+  t.push(
+    emitId(
       "FlowId",
       flows.map((e) => e.id)
     )
   );
-  lines.push(
-    emitIdUnion(
+  t.push(
+    emitId(
       "RouteId",
       routes.map((e) => e.path)
     )
   );
-  lines.push("");
-  lines.push("// ---- authoring-surface shape types ----");
-  lines.push("export namespace Uidex {");
-  lines.push("  export interface Page {");
-  lines.push("    page: PageId | false");
-  lines.push("    name?: string");
-  lines.push("    features?: readonly FeatureId[]");
-  lines.push("    widgets?: readonly WidgetId[]");
-  lines.push("    acceptance?: readonly string[]");
-  lines.push("    description?: string");
-  lines.push("  }");
-  lines.push("  export interface Feature {");
-  lines.push("    feature: FeatureId | false");
-  lines.push("    name?: string");
-  lines.push("    features?: readonly FeatureId[]");
-  lines.push("    acceptance?: readonly string[]");
-  lines.push("    description?: string");
-  lines.push("  }");
-  lines.push("  export interface Primitive {");
-  lines.push("    primitive: PrimitiveId");
-  lines.push("    name?: string");
-  lines.push("    description?: string");
-  lines.push("  }");
-  lines.push("  export interface Widget {");
-  lines.push("    widget: WidgetId");
-  lines.push("    name?: string");
-  lines.push("    acceptance?: readonly string[]");
-  lines.push("    description?: string");
-  lines.push("  }");
-  lines.push("  export interface Region {");
-  lines.push("    region: RegionId | false");
-  lines.push("    name?: string");
-  lines.push("    description?: string");
-  lines.push("  }");
-  lines.push("  export interface Flow {");
-  lines.push("    flow: FlowId");
-  lines.push("    name?: string");
-  lines.push("    description?: string");
-  lines.push("  }");
-  lines.push("  export interface NotFlow {");
-  lines.push("    notFlow: true");
-  lines.push("  }");
-  lines.push("}");
-  lines.push("");
-  lines.push("// ---- entities ----");
+  t.push(emitId("StateId", [...stateNames]));
+  t.push("");
+  t.push("// ---- authoring-surface shape types ----");
+  t.push("export namespace Uidex {");
+  t.push(
+    '  export type CoreStateKind = "loading" | "empty" | "populated" | "error"'
+  );
+  t.push('  export type StateKind = CoreStateKind | "variant"');
+  t.push("  export interface State {");
+  t.push("    name: string");
+  t.push("    kind?: StateKind");
+  t.push("    acceptance?: readonly string[]");
+  t.push("    description?: string");
+  t.push("  }");
+  t.push("  export type Waivers = Partial<Record<CoreStateKind, string>>");
+  t.push("  export interface Page {");
+  t.push("    page: PageId | false");
+  t.push("    name?: string");
+  t.push("    features?: readonly FeatureId[]");
+  t.push("    widgets?: readonly WidgetId[]");
+  t.push("    acceptance?: readonly string[]");
+  t.push("    states?: readonly (string | State)[]");
+  t.push("    capture?: boolean");
+  t.push("    waivers?: Waivers");
+  t.push("    description?: string");
+  t.push("  }");
+  t.push("  export interface Feature {");
+  t.push("    feature: FeatureId | false");
+  t.push("    name?: string");
+  t.push("    features?: readonly FeatureId[]");
+  t.push("    acceptance?: readonly string[]");
+  t.push("    states?: readonly (string | State)[]");
+  t.push("    description?: string");
+  t.push("  }");
+  t.push("  export interface Primitive {");
+  t.push("    primitive: PrimitiveId");
+  t.push("    name?: string");
+  t.push("    description?: string");
+  t.push("  }");
+  t.push("  export interface Widget {");
+  t.push("    widget: WidgetId");
+  t.push("    name?: string");
+  t.push("    acceptance?: readonly string[]");
+  t.push("    states?: readonly (string | State)[]");
+  t.push("    description?: string");
+  t.push("  }");
+  t.push("  export interface Region {");
+  t.push("    region: RegionId | false");
+  t.push("    name?: string");
+  t.push("    description?: string");
+  t.push("  }");
+  t.push("  export interface Flow {");
+  t.push("    flow: FlowId");
+  t.push("    name?: string");
+  t.push("    description?: string");
+  t.push("  }");
+  t.push("  export interface NotFlow {");
+  t.push("    notFlow: true");
+  t.push("  }");
+  t.push("}");
+  t.push("");
   const allEntities = [
     ...routes,
     ...pages,
@@ -1390,25 +1943,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/ast.ts
@@ -1445,14 +2012,14 @@ function makeLineAt(content) {
 function parseSource(file) {
   const lineAt = makeLineAt(file.content);
   try {
-    const result2 = (0, import_oxc_parser.parseSync)(file.sourcePath, file.content, {
+    const result = (0, import_oxc_parser.parseSync)(file.sourcePath, file.content, {
       lang: langFor(file.sourcePath),
       sourceType: "module"
     });
     return {
-      program: result2.program,
-      hasErrors: result2.errors.length > 0,
-      comments: result2.comments ?? [],
+      program: result.program,
+      hasErrors: result.errors.length > 0,
+      comments: result.comments ?? [],
       lineAt
     };
   } catch {
@@ -1512,20 +2079,35 @@ var ALLOWED_FIELDS = {
     "features",
     "widgets",
     "acceptance",
+    "states",
+    "capture",
+    "waivers",
     "description"
   ]),
+  // `capture` / `waivers` are route-scoped, and only a page maps to a route — so
+  // they are page-only (the gates read them off the page). A feature/widget that
+  // sets them gets an `uidex-export-unknown-field` error rather than a silent no-op.
   feature: /* @__PURE__ */ new Set([
     "feature",
     "name",
     "features",
     "acceptance",
+    "states",
     "description"
   ]),
   primitive: /* @__PURE__ */ new Set(["primitive", "name", "description"]),
-  widget: /* @__PURE__ */ new Set(["widget", "name", "acceptance", "description"]),
+  widget: /* @__PURE__ */ new Set(["widget", "name", "acceptance", "states", "description"]),
   region: /* @__PURE__ */ new Set(["region", "name", "description"]),
   flow: /* @__PURE__ */ new Set(["flow", "notFlow", "name", "description"])
 };
+var STATE_FIELDS = /* @__PURE__ */ new Set([
+  "name",
+  "kind",
+  "acceptance",
+  "description"
+]);
+var CORE_STATE_KINDS2 = new Set(CORE_STATE_KINDS);
+var STATE_KINDS2 = /* @__PURE__ */ new Set([...CORE_STATE_KINDS, "variant"]);
 var FALSEABLE = /* @__PURE__ */ new Set([
   "page",
   "feature",
@@ -1915,6 +2497,9 @@ function buildMetadata(value, file, sourcePath, headerPos, diagnostics) {
   }
   const featuresField = kind === "page" || kind === "feature" ? readStringArrayField(byKey, "features") : void 0;
   const widgetsField = kind === "page" ? readStringArrayField(byKey, "widgets") : void 0;
+  const states = kind === "page" || kind === "feature" || kind === "widget" ? readStatesField(byKey) : void 0;
+  const capture = kind === "page" ? readBooleanField(byKey, "capture") : void 0;
+  const waivers = kind === "page" ? readWaiversField(byKey) : void 0;
   const notFlow = kind === "flow" && discriminator === "notFlow" ? true : void 0;
   const metadata = {
     source: "ts-export",
@@ -1937,6 +2522,9 @@ function buildMetadata(value, file, sourcePath, headerPos, diagnostics) {
     metadata.widgets = widgetsField.values;
     metadata.widgetSpans = widgetsField.spans;
   }
+  if (states?.length) metadata.states = states;
+  if (capture !== void 0) metadata.capture = capture;
+  if (waivers && Object.keys(waivers).length > 0) metadata.waivers = waivers;
   if (notFlow) metadata.notFlow = true;
   if (typeof id === "string" && idValue.kind === "string") {
     metadata.idSpan = idValue.span;
@@ -1973,6 +2561,48 @@ function readIdField(value, kind, fieldName) {
     value.pos
   );
 }
+function readWaiversField(byKey) {
+  const entry = byKey.get("waivers");
+  if (!entry) return void 0;
+  if (entry.value.kind !== "object") {
+    throw new ExtractError(
+      "uidex-export-invalid-field",
+      "`waivers` must be an object mapping a core kind to a reason.",
+      entry.value.pos
+    );
+  }
+  const waivers = {};
+  for (const e of entry.value.entries) {
+    if (!CORE_STATE_KINDS2.has(e.key)) {
+      throw new ExtractError(
+        "uidex-export-invalid-field",
+        `waiver key "${e.key}" is not a core kind; only ${[...CORE_STATE_KINDS2].join(", ")} participate in the matrix.`,
+        e.keyPos
+      );
+    }
+    if (e.value.kind !== "string" || e.value.value.length === 0) {
+      throw new ExtractError(
+        "uidex-export-invalid-field",
+        `waiver "${e.key}" needs a non-empty reason (why the route cannot render this kind).`,
+        e.value.pos
+      );
+    }
+    waivers[e.key] = e.value.value;
+  }
+  return waivers;
+}
+function readBooleanField(byKey, name) {
+  const entry = byKey.get(name);
+  if (!entry) return void 0;
+  if (entry.value.kind !== "boolean") {
+    throw new ExtractError(
+      "uidex-export-invalid-field",
+      `\`${name}\` must be a boolean.`,
+      entry.value.pos
+    );
+  }
+  return entry.value.value;
+}
 function readStringField(byKey, name) {
   const entry = byKey.get(name);
   if (!entry) return void 0;
@@ -2010,6 +2640,86 @@ function readStringArrayField(byKey, name) {
   }
   return { values, spans };
 }
+function readStatesField(byKey) {
+  const entry = byKey.get("states");
+  if (!entry) return void 0;
+  if (entry.value.kind !== "array") {
+    throw new ExtractError(
+      "uidex-export-invalid-field",
+      "`states` must be an array of state names or `{ name, acceptance?, description? }` objects.",
+      entry.value.pos
+    );
+  }
+  const states = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const item of entry.value.items) {
+    let state;
+    if (item.kind === "string") {
+      state = { name: item.value, nameSpan: item.span };
+    } else if (item.kind === "object") {
+      const fieldByKey = /* @__PURE__ */ new Map();
+      for (const e of item.entries) fieldByKey.set(e.key, e);
+      for (const e of item.entries) {
+        if (!STATE_FIELDS.has(e.key)) {
+          throw new ExtractError(
+            "uidex-export-invalid-field",
+            `Unknown field "${e.key}" in a \`states\` entry. Allowed: ${Array.from(
+              STATE_FIELDS
+            ).sort().join(", ")}.`,
+            e.value.pos
+          );
+        }
+      }
+      const nameEntry = fieldByKey.get("name");
+      if (!nameEntry || nameEntry.value.kind !== "string") {
+        throw new ExtractError(
+          "uidex-export-invalid-field",
+          "Each object `states` entry must have a string `name`.",
+          item.pos
+        );
+      }
+      state = { name: nameEntry.value.value, nameSpan: nameEntry.value.span };
+      const kind = readStringField(fieldByKey, "kind");
+      if (kind !== void 0) {
+        if (!STATE_KINDS2.has(kind)) {
+          throw new ExtractError(
+            "uidex-export-invalid-field",
+            `state \`kind\` must be one of ${[...STATE_KINDS2].join(", ")} (got "${kind}").`,
+            fieldByKey.get("kind").value.pos
+          );
+        }
+        state.kind = kind;
+      }
+      const acceptance = readStringArrayField(fieldByKey, "acceptance")?.values;
+      if (acceptance) state.acceptance = acceptance;
+      const description = readStringField(fieldByKey, "description");
+      if (description) state.description = description;
+    } else {
+      throw new ExtractError(
+        "uidex-export-invalid-field",
+        "`states` items must be strings or `{ name, ... }` objects.",
+        item.pos
+      );
+    }
+    if (state.name.length === 0) {
+      throw new ExtractError(
+        "uidex-export-invalid-field",
+        "A `states` entry has an empty `name`.",
+        item.pos
+      );
+    }
+    if (seen.has(state.name)) {
+      throw new ExtractError(
+        "uidex-export-duplicate-state",
+        `Duplicate state "${state.name}" in \`states\`; each state name must be unique within the entity.`,
+        item.pos
+      );
+    }
+    seen.add(state.name);
+    states.push(state);
+  }
+  return states;
+}
 function posAt(content, offset, p2) {
   const lineStart = content.lastIndexOf("\n", offset - 1) + 1;
   return { offset, line: p2.lineAt(offset), column: offset - lineStart + 1 };
@@ -2247,22 +2957,22 @@ function collectElementAttrs(opening, consts, dynamicAttrs, lineAt) {
     if (!kind) continue;
     const value = attr.value;
     if (!value) continue;
-    let result2 = UNRESOLVED;
+    let result = UNRESOLVED;
     let valueSpan;
     if (value.type === "Literal") {
       const v = staticString(value);
-      result2 = v !== null && v.length > 0 ? { resolved: true, ids: [v] } : UNRESOLVED;
-      if (result2.resolved) valueSpan = { start: value.start, end: value.end };
+      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") {
-        result2 = evalIdExpression(expr, consts);
+        result = evalIdExpression(expr, consts);
         const inner = unwrapTsExpression(expr);
-        if (result2.resolved && staticString(inner) !== null) {
+        if (result.resolved && staticString(inner) !== null) {
           valueSpan = { start: inner.start, end: inner.end };
         }
       }
-      if (!result2.resolved) {
+      if (!result.resolved) {
         dynamicAttrs.push({
           kind,
           attrName: kind === "element" ? "data-uidex" : `data-uidex-${kind}`,
@@ -2271,15 +2981,15 @@ function collectElementAttrs(opening, consts, dynamicAttrs, lineAt) {
         continue;
       }
     }
-    if (!result2.resolved) continue;
-    for (const id of result2.ids) {
+    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.
-        ...result2.ids.length === 1 && valueSpan ? { span: valueSpan } : {}
+        ...result.ids.length === 1 && valueSpan ? { span: valueSpan } : {}
       };
       if (resolved.isPattern) patterns.push(resolved);
       else statics.push(resolved);
@@ -2562,13 +3272,26 @@ var path8 = __toESM(require("path"), 1);
 var PAGE_BASENAME = /^page\.(tsx|ts|jsx|js|mjs|cjs)$/;
 var PAGES_ROUTER_BASENAME = /\.(tsx|ts|jsx|js|mjs|cjs)$/;
 var ROUTE_BASENAME = /^route\.(tsx|ts|jsx|js|mjs|cjs)$/;
-function detectRoutes(files) {
+function detectRoutes(files, options = {}) {
   const out2 = [];
   const seen = /* @__PURE__ */ new Set();
+  const routesDir = options.routesDir ? options.routesDir.replace(/^\.?\/+/, "").replace(/\/+$/, "") : null;
+  const routesDirParts = routesDir ? routesDir.split("/") : null;
   for (const f of files) {
     const rel = f.displayPath;
     const parts = rel.split("/");
     const base = parts[parts.length - 1];
+    if (routesDirParts) {
+      const end = dirEndIndex(parts, routesDirParts);
+      if (end === -1 || end > parts.length - 1) continue;
+      if (!PAGES_ROUTER_BASENAME.test(base)) continue;
+      const routePath = routesStylePath(
+        parts.slice(end, parts.length - 1),
+        base
+      );
+      if (routePath !== null) push(out2, seen, routePath, f.displayPath);
+      continue;
+    }
     const appIdx = parts.indexOf("app");
     if (appIdx !== -1 && PAGE_BASENAME.test(base)) {
       const routeSegments = parts.slice(appIdx + 1, parts.length - 1);
@@ -2595,15 +3318,11 @@ function detectRoutes(files) {
     }
     const routesIdx = parts.indexOf("routes");
     if (routesIdx !== -1 && PAGES_ROUTER_BASENAME.test(base)) {
-      const segs = parts.slice(routesIdx + 1);
-      const last = segs[segs.length - 1];
-      if (last.startsWith("_")) continue;
-      const normalized = [
-        ...segs.slice(0, -1),
-        base.replace(/\.[^.]+$/, "")
-      ].filter((s) => s !== "index" && s !== "__root");
-      const routePath = formatNextAppPath(normalized);
-      push(out2, seen, routePath, f.displayPath);
+      const routePath = routesStylePath(
+        parts.slice(routesIdx + 1, parts.length - 1),
+        base
+      );
+      if (routePath !== null) push(out2, seen, routePath, f.displayPath);
       continue;
     }
   }
@@ -2619,6 +3338,63 @@ function formatNextAppPath(segments) {
   if (kept.length === 0) return "/";
   return "/" + kept.join("/");
 }
+function dirEndIndex(parts, dirParts) {
+  if (dirParts.length === 0) return 0;
+  for (let i = 0; i + dirParts.length <= parts.length; i++) {
+    let match = true;
+    for (let j = 0; j < dirParts.length; j++) {
+      if (parts[i + j] !== dirParts[j]) {
+        match = false;
+        break;
+      }
+    }
+    if (match) return i + dirParts.length;
+  }
+  return -1;
+}
+function routesStylePath(dirSegs, base) {
+  const fileSegs = splitFlatSegments(base.replace(/\.[^.]+$/, ""));
+  const leaf = fileSegs[fileSegs.length - 1];
+  if (leaf.startsWith("_")) return null;
+  const rawSegs = [...dirSegs, ...fileSegs];
+  if (rawSegs.some((s) => s.startsWith("-"))) return null;
+  if (rawSegs[0] === "api") return null;
+  return formatTanStackPath(rawSegs);
+}
+function splitFlatSegments(name) {
+  const segs = [];
+  let cur = "";
+  let depth = 0;
+  for (const ch of name) {
+    if (ch === "[") depth++;
+    else if (ch === "]") depth = Math.max(0, depth - 1);
+    if (ch === "." && depth === 0) {
+      segs.push(cur);
+      cur = "";
+      continue;
+    }
+    cur += ch;
+  }
+  segs.push(cur);
+  return segs;
+}
+function formatTanStackPath(segments) {
+  const kept = [];
+  for (const seg of segments) {
+    if (!seg) continue;
+    if (seg === "index" || seg === "route" || seg === "__root") continue;
+    if (seg.startsWith("_")) continue;
+    if (seg.startsWith("(") && seg.endsWith(")")) continue;
+    kept.push(normalizeTanStackSegment(seg.replace(/_$/, "")));
+  }
+  if (kept.length === 0) return "/";
+  return "/" + kept.join("/");
+}
+function normalizeTanStackSegment(seg) {
+  if (seg === "$") return "[...splat]";
+  if (seg.startsWith("$")) return `[${seg.slice(1)}]`;
+  return seg.replace(/\[([^\]]*)\]/g, "$1");
+}
 function pathToId(routePath) {
   if (routePath === "/") return "root";
   return routePath.replace(/^\/+/, "").replace(/\[\.{3}([^\]]+)\]/g, "$1").replace(/\[([^\]]+)\]/g, "$1").replace(/\//g, "-").replace(/[^a-zA-Z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
@@ -2633,7 +3409,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",
@@ -2782,6 +3563,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 resolve3(ctx) {
@@ -2827,9 +3620,12 @@ function resolve3(ctx) {
   function metaWithComposes(kind, id, base) {
     const composes = directChildren.get(`${kind}:${id}`);
     if (!composes || composes.length === 0) return base;
-    return { ...base ?? {}, composes };
+    return { ...base, composes };
   }
-  const routes = conventions.pages === "auto" ? detectRoutes(ctx.extracted.map((e) => e.file)) : [];
+  const routes = conventions.pages === false ? [] : detectRoutes(
+    ctx.extracted.map((e) => e.file),
+    conventions.pages === "auto" ? {} : { routesDir: conventions.pages.routesDir }
+  );
   const handledPageFiles = /* @__PURE__ */ new Set();
   for (const route of routes) {
     const routeDir = path8.posix.dirname(route.file);
@@ -3200,6 +3996,68 @@ function dedupe(arr) {
 }
 
 // src/scanner/scan/pipeline.ts
+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 = path9.resolve(configDir, rel);
+  let raw;
+  try {
+    raw = fs6.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 = path9.resolve(configDir, rel);
+  let raw;
+  try {
+    raw = fs6.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 });
@@ -3226,23 +4084,29 @@ function runOne(dc, opts) {
     flowFiles: extractedFlows
   });
   const gitContext = resolveGitContext({ cwd: configDir });
-  const generated = emit({
+  const emitted = emit({
     registry: resolved.registry,
     gitContext
   });
-  const outputPath = path9.resolve(configDir, config.output);
-  const outputRel = config.output;
-  let existingOnDisk = null;
+  const typesRel = config.output;
+  const typesPath = path9.resolve(configDir, typesRel);
+  const dataRel = dataOutputPath(config.output);
+  const dataPath = path9.resolve(configDir, dataRel);
+  const locsRel = locsOutputPath(config.output);
+  const locsPath = path9.resolve(configDir, locsRel);
+  let typesOnDisk = null;
+  let dataOnDisk = null;
+  let locsOnDisk = null;
   if (opts.check) {
-    try {
-      existingOnDisk = fs6.readFileSync(outputPath, "utf8");
-    } catch {
-      existingOnDisk = null;
-    }
+    typesOnDisk = readOrNull(typesPath);
+    dataOnDisk = readOrNull(dataPath);
+    locsOnDisk = readOrNull(locsPath);
   }
   const hasExtractDiagnostics = [...extracted, ...extractedFlows].some(
     (ef) => (ef.diagnostics?.length ?? 0) > 0
   );
+  const capturedStates = opts.capturedStates ?? loadCapturedStates(configDir, config);
+  const pageBaseline = opts.pageBaseline ?? loadPageBaseline(configDir, config);
   let auditResult;
   if (opts.check || opts.lint || resolved.diagnostics.length > 0 || hasExtractDiagnostics) {
     auditResult = audit({
@@ -3254,9 +4118,20 @@ function runOne(dc, opts) {
       check: opts.check,
       lint: opts.lint,
       resolveDiagnostics: resolved.diagnostics,
-      generated,
-      existingOnDisk,
-      outputPath: outputRel
+      // The entity array (and thus the meaningful drift) lives in the data file,
+      // so the entity-aware gen-stale diff runs against it; the types file gets a
+      // plain content compare (see audit()).
+      generated: emitted.data,
+      existingOnDisk: dataOnDisk,
+      outputPath: dataRel,
+      typesGenerated: emitted.types,
+      typesOnDisk,
+      typesOutputPath: typesRel,
+      locsGenerated: emitted.locs,
+      locsOnDisk,
+      locsOutputPath: locsRel,
+      capturedStates,
+      pageBaseline
     });
   }
   return {
@@ -3265,13 +4140,38 @@ function runOne(dc, opts) {
     registry: resolved.registry,
     gitContext,
     audit: auditResult,
-    generated,
-    outputPath
+    types: {
+      generated: emitted.types,
+      outputPath: typesPath,
+      outputRel: typesRel
+    },
+    data: { generated: emitted.data, outputPath: dataPath, outputRel: dataRel },
+    locs: { generated: emitted.locs, outputPath: locsPath, outputRel: locsRel },
+    capturedStates
   };
 }
-function writeScanResult(result2) {
-  fs6.mkdirSync(path9.dirname(result2.outputPath), { recursive: true });
-  fs6.writeFileSync(result2.outputPath, result2.generated, "utf8");
+function readOrNull(p2) {
+  try {
+    return fs6.readFileSync(p2, "utf8");
+  } catch {
+    return null;
+  }
+}
+function writeArtifact(artifact) {
+  if (readOrNull(artifact.outputPath) === artifact.generated) return false;
+  fs6.mkdirSync(path9.dirname(artifact.outputPath), { recursive: true });
+  fs6.writeFileSync(artifact.outputPath, artifact.generated, "utf8");
+  return true;
+}
+function writeScanResult(result) {
+  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 path9.resolve(result.configDir, rel);
 }
 
 // src/scanner/scan/rename.ts
@@ -3411,7 +4311,7 @@ function renameEntity(opts) {
       ]
     };
   }
-  const result2 = applyFixes([
+  const result = applyFixes([
     {
       code: "rename",
       severity: "info",
@@ -3422,8 +4322,8 @@ function renameEntity(opts) {
       }
     }
   ]);
-  if (result2.skipped.length > 0) {
-    errors.push(`Some edits were skipped: ${result2.skipped[0].reason}`);
+  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 };
@@ -3522,10 +4422,10 @@ function parseArgs(args) {
 async function run(opts) {
   const cwd = opts.cwd ?? process.cwd();
   const { positional, flags } = parseArgs(opts.argv);
-  const command2 = positional[0] ?? "help";
+  const command = positional[0] ?? "help";
   const writer = createWriter();
   try {
-    switch (command2) {
+    switch (command) {
       case "help":
       case "--help":
       case "-h":
@@ -3540,16 +4440,16 @@ async function run(opts) {
       case "rename":
         return runRename(cwd, positional.slice(1), flags, writer);
       case "ai": {
-        const result2 = await runAiCommand({
+        const result = await runAiCommand({
           cwd,
           argv: opts.argv.slice(1)
         });
-        if (result2.stdout) writer.out(result2.stdout.replace(/\n$/, ""));
-        if (result2.stderr) writer.err(result2.stderr.replace(/\n$/, ""));
-        return writer.result(result2.exitCode);
+        if (result.stdout) writer.out(result.stdout.replace(/\n$/, ""));
+        if (result.stderr) writer.err(result.stderr.replace(/\n$/, ""));
+        return writer.result(result.exitCode);
       }
       default:
-        writer.err(`Unknown command: ${command2}`);
+        writer.err(`Unknown command: ${command}`);
         writer.err(helpText2());
         return writer.result(1);
     }
@@ -3568,16 +4468,13 @@ function helpText2() {
     "  scaffold <widget|page|feature> <id>  Emit a Playwright spec from declared acceptance",
     "  rename <element|widget|region> <old-id> <new-id>  Rename an id everywhere (DOM attr, flows, exports)",
     "  ai <install|uninstall|providers>  Manage AI assistant integrations",
-    "  api <METHOD> <PATH>              Call the uidex API",
-    "  api --list                       Show available API routes",
-    "  api login                        Authenticate via browser",
-    "  api login --token <tok>          Store an auth token directly",
     "",
     "Flags:",
     "  --check               Verify the on-disk gen file matches a fresh scan; exit non-zero on drift (read-only)",
     "  --lint                Run lint diagnostics (missing annotations, scope leak, duplicate ids, coverage)",
     "  --audit               Equivalent to --check --lint (read-only)",
     "  --fix                 Apply machine-generated fixes (add data-uidex to unannotated interactive elements, drop empty names), then rescan and write",
+    "  --update-baseline     Regenerate the page-coverage baseline (uidex-coverage-baseline.json) from the current uncaptured routes",
     "  --json                Emit JSON diagnostics on stdout",
     "  --force               (scaffold) overwrite existing spec",
     ""
@@ -3597,7 +4494,7 @@ function runInit(cwd, w) {
   fs8.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
   w.out(`Created ${configPath}`);
   const gitignorePath = path11.join(cwd, ".gitignore");
-  const entry = "*.gen.ts";
+  const entry = "*.gen.*";
   if (fs8.existsSync(gitignorePath)) {
     const existing = fs8.readFileSync(gitignorePath, "utf8");
     const hasEntry = existing.split("\n").some((line) => line.trim() === entry);
@@ -3620,8 +4517,9 @@ function runInit(cwd, w) {
 }
 function runScanCommand(cwd, flags, w) {
   const fix = Boolean(flags.fix);
-  const check = !fix && Boolean(flags.check || flags.audit);
-  const lint = Boolean(flags.lint || flags.audit || fix);
+  const updateBaseline = Boolean(flags["update-baseline"]);
+  const check = !fix && !updateBaseline && Boolean(flags.check || flags.audit);
+  const lint = Boolean(flags.lint || flags.audit || fix || updateBaseline);
   const asJson = Boolean(flags.json);
   let configs = discover({ cwd });
   if (configs.length === 0) {
@@ -3632,16 +4530,41 @@ function runScanCommand(cwd, flags, w) {
   let fixSkipped = [];
   if (fix) {
     const discovery = runScan({ cwd, check: true, lint: true, configs });
-    const result2 = applyFixes(
+    const result = applyFixes(
       discovery.flatMap((r) => r.audit?.diagnostics ?? [])
     );
-    fixed = result2.applied;
-    fixSkipped = result2.skipped;
+    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(
@@ -3669,10 +4592,14 @@ function runScanCommand(cwd, flags, w) {
       );
     }
     for (const r of results) {
-      if (check) {
-        w.out(`Checked ${r.outputPath}`);
-      } else {
-        w.out(`Wrote ${r.outputPath}`);
+      for (const art of [r.types, r.data, r.locs]) {
+        if (check) {
+          w.out(`Checked ${art.outputPath}`);
+        } else if (wrote.has(art)) {
+          w.out(`Wrote ${art.outputPath}`);
+        } else {
+          w.out(`Unchanged ${art.outputPath}`);
+        }
       }
       for (const d of r.audit?.diagnostics ?? []) {
         const loc = d.file ? `${d.file}${d.line ? `:${d.line}` : ""}` : "";
@@ -3708,18 +4635,18 @@ function runScaffold(cwd, args, flags, w) {
     const entity = r.registry.get(scaffoldKind, id);
     if (!entity) continue;
     const outDir = path11.resolve(r.configDir, "e2e");
-    const result2 = scaffoldSpec({
+    const result = scaffoldSpec({
       registry: r.registry,
       kind: scaffoldKind,
       id,
       outDir,
       force: Boolean(flags.force)
     });
-    if (result2.skipped) {
-      w.err(result2.reason ?? "skipped");
+    if (result.skipped) {
+      w.err(result.reason ?? "skipped");
       return w.result(1);
     }
-    w.out(`Wrote ${result2.outputPath}`);
+    w.out(`Wrote ${result.outputPath}`);
     return w.result(0);
   }
   w.err(
@@ -3736,24 +4663,24 @@ function runRename(cwd, args, flags, w) {
     );
     return w.result(1);
   }
-  const result2 = renameEntity({
+  const result = renameEntity({
     cwd,
     kind,
     oldId,
     newId,
     force: Boolean(flags.force)
   });
-  for (const e of result2.errors) w.err(e);
-  for (const m of result2.manual) {
+  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 (result2.errors.length > 0) return w.result(1);
+  if (result.errors.length > 0) return w.result(1);
   w.out(
-    `Renamed ${kind} "${oldId}" \u2192 "${newId}" (${result2.edits} edit(s)); gen file regenerated`
+    `Renamed ${kind} "${oldId}" \u2192 "${newId}" (${result.edits} edit(s)); gen file regenerated`
   );
-  if (result2.manual.length > 0) {
+  if (result.manual.length > 0) {
     w.err(
-      `${result2.manual.length} occurrence(s) need manual follow-up (listed above)`
+      `${result.manual.length} occurrence(s) need manual follow-up (listed above)`
     );
     return w.result(1);
   }
@@ -3775,883 +4702,14 @@ function createWriter() {
   };
 }
 
-// src/scanner/cli/auth.ts
-function createMemoryTokenStorage(initial) {
-  let token = initial ?? null;
-  return {
-    get: () => token,
-    set: (t) => {
-      token = t;
-    },
-    clear: () => {
-      token = null;
-    }
-  };
-}
-function createFileTokenStorage(options) {
-  const nodeFs = require("fs");
-  const nodePath = require("path");
-  const file = options.path;
-  function read() {
-    if (!nodeFs.existsSync(file)) return null;
-    try {
-      const raw = nodeFs.readFileSync(file, "utf8");
-      const parsed = JSON.parse(raw);
-      if (parsed && typeof parsed === "object") {
-        return parsed;
-      }
-    } catch {
-      return null;
-    }
-    return null;
-  }
-  return {
-    get: () => read()?.token ?? null,
-    set: (token) => {
-      nodeFs.mkdirSync(nodePath.dirname(file), { recursive: true });
-      nodeFs.writeFileSync(file, JSON.stringify({ token }, null, 2));
-    },
-    clear: () => {
-      if (nodeFs.existsSync(file)) nodeFs.unlinkSync(file);
-    }
-  };
-}
-function defaultTokenPath() {
-  const os = require("os");
-  const path12 = require("path");
-  return path12.join(os.homedir(), ".uidex", "cloud-token.json");
-}
-
-// src/scanner/cli/http.ts
-function createHttpClient(options) {
-  const baseUrl = options.baseUrl.replace(/\/$/, "");
-  async function request(path12, opts = {}) {
-    let url = `${baseUrl}${path12.startsWith("/") ? path12 : `/${path12}`}`;
-    if (opts.query) {
-      url += (url.includes("?") ? "&" : "?") + opts.query;
-    }
-    const headers = {
-      Accept: "application/json",
-      ...opts.headers
-    };
-    const token = options.token();
-    if (token) headers.Authorization = `Bearer ${token}`;
-    if (opts.body !== void 0) {
-      headers["Content-Type"] ??= "application/json";
-    }
-    const res = await fetch(url, {
-      method: opts.method ?? (opts.body ? "POST" : "GET"),
-      headers,
-      body: opts.body
-    });
-    const raw = await res.text();
-    let body = raw;
-    try {
-      body = JSON.parse(raw);
-    } catch {
-    }
-    return { status: res.status, body, raw };
-  }
-  return { request };
-}
-
-// src/scanner/cli/json-highlight.ts
-var RESET = "\x1B[0m";
-var BOLD = "\x1B[1m";
-var DIM = "\x1B[2m";
-var RED = "\x1B[31m";
-var CYAN = "\x1B[36m";
-var GREEN = "\x1B[32m";
-var YELLOW = "\x1B[33m";
-var MAGENTA = "\x1B[35m";
-function highlightJson(value, color) {
-  const json = JSON.stringify(value, null, 2);
-  if (!color) return json;
-  return json.replace(
-    /("(?:\\.|[^"\\])*")\s*:|("(?:\\.|[^"\\])*")|(\b(?:true|false|null)\b)|(-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)/g,
-    (match, key, str, literal, num) => {
-      if (key) return `${CYAN}${key}${RESET}:`;
-      if (str) return `${GREEN}${str}${RESET}`;
-      if (literal) return `${MAGENTA}${literal}${RESET}`;
-      if (num) return `${YELLOW}${num}${RESET}`;
-      return match;
-    }
-  );
-}
-function formatStatus(status, color) {
-  if (!color) return `HTTP ${status}`;
-  const code = status >= 400 ? RED : status >= 300 ? YELLOW : GREEN;
-  return `${code}HTTP ${status}${RESET}`;
-}
-function boldText(text, color) {
-  if (!color) return text;
-  return `${BOLD}${text}${RESET}`;
-}
-function dimText(text, color) {
-  if (!color) return text;
-  return `${DIM}${text}${RESET}`;
-}
-
-// src/scanner/cli/api-routes.gen.ts
-var API_ROUTES = [
-  {
-    "method": "POST",
-    "path": "/api/ingest",
-    "operationId": "submitReport",
-    "summary": "Submit feedback from the SDK.",
-    "tag": "Ingest",
-    "params": []
-  },
-  {
-    "method": "GET",
-    "path": "/api/ingest/config",
-    "operationId": "getIngestConfig",
-    "summary": "Get integration configuration for the project.",
-    "tag": "Ingest",
-    "params": []
-  },
-  {
-    "method": "GET",
-    "path": "/api/ingest/reports",
-    "operationId": "listIngestReports",
-    "summary": "List feedback for the project (SDK view).",
-    "tag": "Ingest",
-    "params": []
-  },
-  {
-    "method": "GET",
-    "path": "/api/ingest/pins",
-    "operationId": "listPins",
-    "summary": "List pins by route and/or entity.",
-    "tag": "Ingest",
-    "params": []
-  },
-  {
-    "method": "POST",
-    "path": "/api/ingest/pins/archive",
-    "operationId": "archivePin",
-    "summary": "Archive a pin.",
-    "tag": "Ingest",
-    "params": []
-  },
-  {
-    "method": "POST",
-    "path": "/api/cli-auth/authorize",
-    "operationId": "authorizeCli",
-    "summary": "Authorize a CLI session by delivering a token.",
-    "tag": "CLI Auth",
-    "params": []
-  },
-  {
-    "method": "GET",
-    "path": "/api/organizations",
-    "operationId": "listOrganizations",
-    "summary": "List organizations for the current user.",
-    "tag": "Organizations",
-    "params": []
-  },
-  {
-    "method": "POST",
-    "path": "/api/organizations",
-    "operationId": "createOrganization",
-    "summary": "Create an organization.",
-    "tag": "Organizations",
-    "params": []
-  },
-  {
-    "method": "POST",
-    "path": "/api/organizations/switch",
-    "operationId": "switchOrganization",
-    "summary": "Switch the active organization.",
-    "tag": "Organizations",
-    "params": []
-  },
-  {
-    "method": "GET",
-    "path": "/api/organizations/{orgId}",
-    "operationId": "getOrganization",
-    "summary": "Get organization details.",
-    "tag": "Organizations",
-    "params": [
-      "orgId"
-    ]
-  },
-  {
-    "method": "PATCH",
-    "path": "/api/organizations/{orgId}",
-    "operationId": "updateOrganization",
-    "summary": "Update an organization.",
-    "tag": "Organizations",
-    "params": [
-      "orgId"
-    ]
-  },
-  {
-    "method": "DELETE",
-    "path": "/api/organizations/{orgId}",
-    "operationId": "deleteOrganization",
-    "summary": "Delete an organization.",
-    "tag": "Organizations",
-    "params": [
-      "orgId"
-    ]
-  },
-  {
-    "method": "GET",
-    "path": "/api/organizations/{orgId}/members",
-    "operationId": "listMembers",
-    "summary": "List organization members.",
-    "tag": "Members",
-    "params": [
-      "orgId"
-    ]
-  },
-  {
-    "method": "DELETE",
-    "path": "/api/organizations/{orgId}/members",
-    "operationId": "removeMember",
-    "summary": "Remove a member from the organization.",
-    "tag": "Members",
-    "params": [
-      "orgId"
-    ]
-  },
-  {
-    "method": "PATCH",
-    "path": "/api/organizations/{orgId}/members/{memberId}",
-    "operationId": "updateMember",
-    "summary": "Update a member's role.",
-    "tag": "Members",
-    "params": [
-      "orgId",
-      "memberId"
-    ]
-  },
-  {
-    "method": "GET",
-    "path": "/api/organizations/{orgId}/invitations",
-    "operationId": "listInvitations",
-    "summary": "List organization invitations.",
-    "tag": "Invitations",
-    "params": [
-      "orgId"
-    ]
-  },
-  {
-    "method": "POST",
-    "path": "/api/organizations/{orgId}/invitations",
-    "operationId": "createInvitation",
-    "summary": "Create an invitation link.",
-    "tag": "Invitations",
-    "params": [
-      "orgId"
-    ]
-  },
-  {
-    "method": "DELETE",
-    "path": "/api/organizations/{orgId}/invitations/{inviteId}",
-    "operationId": "deleteInvitation",
-    "summary": "Revoke an invitation.",
-    "tag": "Invitations",
-    "params": [
-      "orgId",
-      "inviteId"
-    ]
-  },
-  {
-    "method": "GET",
-    "path": "/api/organizations/{orgId}/projects",
-    "operationId": "listProjects",
-    "summary": "List projects in an organization.",
-    "tag": "Projects",
-    "params": [
-      "orgId"
-    ]
-  },
-  {
-    "method": "POST",
-    "path": "/api/organizations/{orgId}/projects",
-    "operationId": "createProject",
-    "summary": "Create a project.",
-    "tag": "Projects",
-    "params": [
-      "orgId"
-    ]
-  },
-  {
-    "method": "GET",
-    "path": "/api/organizations/{orgId}/projects/{projectId}",
-    "operationId": "getProject",
-    "summary": "Get project details.",
-    "tag": "Projects",
-    "params": [
-      "orgId",
-      "projectId"
-    ]
-  },
-  {
-    "method": "PATCH",
-    "path": "/api/organizations/{orgId}/projects/{projectId}",
-    "operationId": "updateProject",
-    "summary": "Update a project.",
-    "tag": "Projects",
-    "params": [
-      "orgId",
-      "projectId"
-    ]
-  },
-  {
-    "method": "DELETE",
-    "path": "/api/organizations/{orgId}/projects/{projectId}",
-    "operationId": "deleteProject",
-    "summary": "Delete a project.",
-    "tag": "Projects",
-    "params": [
-      "orgId",
-      "projectId"
-    ]
-  },
-  {
-    "method": "GET",
-    "path": "/api/projects/resolve",
-    "operationId": "resolveProject",
-    "summary": "Resolve an API key to its project and organization.",
-    "tag": "Projects",
-    "params": []
-  },
-  {
-    "method": "GET",
-    "path": "/api/organizations/{orgId}/projects/{projectId}/api-keys",
-    "operationId": "listApiKeys",
-    "summary": "List API keys for a project.",
-    "tag": "API Keys",
-    "params": [
-      "orgId",
-      "projectId"
-    ]
-  },
-  {
-    "method": "POST",
-    "path": "/api/organizations/{orgId}/projects/{projectId}/api-keys",
-    "operationId": "createApiKey",
-    "summary": "Create an API key.",
-    "tag": "API Keys",
-    "params": [
-      "orgId",
-      "projectId"
-    ]
-  },
-  {
-    "method": "PATCH",
-    "path": "/api/organizations/{orgId}/projects/{projectId}/api-keys/{keyId}",
-    "operationId": "revokeApiKey",
-    "summary": "Revoke an API key.",
-    "tag": "API Keys",
-    "params": [
-      "orgId",
-      "projectId",
-      "keyId"
-    ]
-  },
-  {
-    "method": "DELETE",
-    "path": "/api/organizations/{orgId}/projects/{projectId}/api-keys/{keyId}",
-    "operationId": "deleteApiKey",
-    "summary": "Permanently delete an API key.",
-    "tag": "API Keys",
-    "params": [
-      "orgId",
-      "projectId",
-      "keyId"
-    ]
-  },
-  {
-    "method": "GET",
-    "path": "/api/organizations/{orgId}/projects/{projectId}/reports",
-    "operationId": "listProjectReports",
-    "summary": "List feedback for a project.",
-    "tag": "Reports",
-    "params": [
-      "orgId",
-      "projectId"
-    ]
-  },
-  {
-    "method": "GET",
-    "path": "/api/organizations/{orgId}/projects/{projectId}/feedback/{reportId}",
-    "operationId": "getReport",
-    "summary": "Get feedback details.",
-    "tag": "Reports",
-    "params": [
-      "orgId",
-      "projectId",
-      "reportId"
-    ]
-  },
-  {
-    "method": "PATCH",
-    "path": "/api/organizations/{orgId}/projects/{projectId}/feedback/{reportId}",
-    "operationId": "updateReport",
-    "summary": "Update feedback status, priority, or assignment.",
-    "tag": "Reports",
-    "params": [
-      "orgId",
-      "projectId",
-      "reportId"
-    ]
-  },
-  {
-    "method": "DELETE",
-    "path": "/api/organizations/{orgId}/projects/{projectId}/feedback/{reportId}",
-    "operationId": "deleteReport",
-    "summary": "Delete a feedback record.",
-    "tag": "Reports",
-    "params": [
-      "orgId",
-      "projectId",
-      "reportId"
-    ]
-  },
-  {
-    "method": "POST",
-    "path": "/api/organizations/{orgId}/projects/{projectId}/reports/bulk-status",
-    "operationId": "bulkUpdateReportStatus",
-    "summary": "Update status on multiple feedback records.",
-    "tag": "Reports",
-    "params": [
-      "orgId",
-      "projectId"
-    ]
-  },
-  {
-    "method": "GET",
-    "path": "/api/organizations/{orgId}/integrations",
-    "operationId": "listIntegrations",
-    "summary": "List integrations for an organization.",
-    "tag": "Integrations",
-    "params": [
-      "orgId"
-    ]
-  },
-  {
-    "method": "POST",
-    "path": "/api/organizations/{orgId}/integrations",
-    "operationId": "createIntegration",
-    "summary": "Create an integration.",
-    "tag": "Integrations",
-    "params": [
-      "orgId"
-    ]
-  },
-  {
-    "method": "GET",
-    "path": "/api/organizations/{orgId}/integrations/{integrationId}",
-    "operationId": "getIntegration",
-    "summary": "Get integration details.",
-    "tag": "Integrations",
-    "params": [
-      "orgId",
-      "integrationId"
-    ]
-  },
-  {
-    "method": "DELETE",
-    "path": "/api/organizations/{orgId}/integrations/{integrationId}",
-    "operationId": "deleteIntegration",
-    "summary": "Delete an integration.",
-    "tag": "Integrations",
-    "params": [
-      "orgId",
-      "integrationId"
-    ]
-  },
-  {
-    "method": "GET",
-    "path": "/api/organizations/{orgId}/integrations/{integrationId}/targets",
-    "operationId": "listIntegrationTargets",
-    "summary": "List available targets (e.g. Jira projects/boards).",
-    "tag": "Integrations",
-    "params": [
-      "orgId",
-      "integrationId"
-    ]
-  },
-  {
-    "method": "POST",
-    "path": "/api/organizations/{orgId}/integrations/{integrationId}/test",
-    "operationId": "testIntegration",
-    "summary": "Test integration connectivity.",
-    "tag": "Integrations",
-    "params": [
-      "orgId",
-      "integrationId"
-    ]
-  },
-  {
-    "method": "GET",
-    "path": "/api/organizations/{orgId}/external-issues",
-    "operationId": "listExternalIssues",
-    "summary": "List external issues, optionally filtered by feedback.",
-    "tag": "External Issues",
-    "params": [
-      "orgId"
-    ]
-  },
-  {
-    "method": "GET",
-    "path": "/api/organizations/{orgId}/issue-drafts",
-    "operationId": "listIssueDrafts",
-    "summary": "List issue drafts for a project.",
-    "tag": "Issue Drafts",
-    "params": [
-      "orgId"
-    ]
-  },
-  {
-    "method": "POST",
-    "path": "/api/organizations/{orgId}/issue-drafts",
-    "operationId": "createIssueDraft",
-    "summary": "Manually create an issue draft.",
-    "tag": "Issue Drafts",
-    "params": [
-      "orgId"
-    ]
-  },
-  {
-    "method": "PATCH",
-    "path": "/api/organizations/{orgId}/issue-drafts/{draftId}",
-    "operationId": "updateIssueDraft",
-    "summary": "Update an issue draft.",
-    "tag": "Issue Drafts",
-    "params": [
-      "orgId",
-      "draftId"
-    ]
-  },
-  {
-    "method": "DELETE",
-    "path": "/api/organizations/{orgId}/issue-drafts/{draftId}",
-    "operationId": "deleteIssueDraft",
-    "summary": "Delete an issue draft.",
-    "tag": "Issue Drafts",
-    "params": [
-      "orgId",
-      "draftId"
-    ]
-  },
-  {
-    "method": "POST",
-    "path": "/api/organizations/{orgId}/issue-drafts/{draftId}/submit",
-    "operationId": "submitIssueDraft",
-    "summary": "Submit a draft to the configured integration.",
-    "tag": "Issue Drafts",
-    "params": [
-      "orgId",
-      "draftId"
-    ]
-  },
-  {
-    "method": "POST",
-    "path": "/api/organizations/{orgId}/projects/{projectId}/triage",
-    "operationId": "runTriage",
-    "summary": "Run LLM-powered triage on untriaged feedback.",
-    "tag": "Triage",
-    "params": [
-      "orgId",
-      "projectId"
-    ]
-  },
-  {
-    "method": "GET",
-    "path": "/api/user/tokens",
-    "operationId": "listUserTokens",
-    "summary": "List personal access tokens.",
-    "tag": "User Tokens",
-    "params": []
-  },
-  {
-    "method": "POST",
-    "path": "/api/user/tokens",
-    "operationId": "createUserToken",
-    "summary": "Create a personal access token.",
-    "tag": "User Tokens",
-    "params": []
-  },
-  {
-    "method": "DELETE",
-    "path": "/api/user/tokens/{tokenId}",
-    "operationId": "deleteUserToken",
-    "summary": "Revoke and delete a personal access token.",
-    "tag": "User Tokens",
-    "params": [
-      "tokenId"
-    ]
-  }
-];
-
-// src/scanner/cli/api.ts
-var METHODS = /* @__PURE__ */ new Set([
-  "GET",
-  "POST",
-  "PUT",
-  "PATCH",
-  "DELETE",
-  "HEAD",
-  "OPTIONS"
-]);
-var HELP = `uidex api \u2014 call the uidex API
-
-Usage:
-  uidex api <METHOD> <PATH> [flags]    Make an API request
-  uidex api --list [--tag <tag>]       List available routes
-  uidex api login                      Authenticate via browser
-  uidex api login --token <tok>        Store an auth token directly
-  uidex api status                     Check auth state
-
-Flags:
-  --body <json>       Request body (JSON string)
-  --query <params>    Query string (key=val&key2=val2)
-  --base-url <url>    Override the API base URL
-  --token <tok>       Use a specific token (instead of stored)
-  --raw               Disable JSON pretty-printing
-  --no-color          Disable colored output
-  --list              List available API routes
-  --tag <tag>         Filter --list by tag
-  --json              Emit --list as JSON
-`;
-async function runApiCommand(opts) {
-  const { positional, flags } = parseArgs(opts.argv);
-  const stdout = [];
-  const stderr = [];
-  const color = opts.color ?? (flags["no-color"] ? false : process.stdout.isTTY ?? false);
-  const ctx = { flags, opts, color, stdout, stderr };
-  const sub = positional[0];
-  if (!sub && !flags.list) {
-    stdout.push(HELP);
-    return result(0, stdout, stderr);
-  }
-  if (flags.list) return listRoutes(ctx);
-  if (sub === "help" || sub === "--help" || sub === "-h") {
-    stdout.push(HELP);
-    return result(0, stdout, stderr);
-  }
-  if (sub === "login") return runLogin(ctx);
-  if (sub === "status") return runStatus(ctx);
-  const method = sub?.toUpperCase();
-  const path12 = positional[1];
-  if (!method || !METHODS.has(method)) {
-    stderr.push(`Unknown command or method: ${sub}`);
-    stderr.push(HELP);
-    return result(1, stdout, stderr);
-  }
-  if (!path12) {
-    stderr.push("Missing path. Usage: uidex api GET /api/organizations");
-    return result(1, stdout, stderr);
-  }
-  return runRequest(ctx, method, path12);
-}
-function listRoutes(ctx) {
-  const { flags, color, stdout, stderr } = ctx;
-  let routes = API_ROUTES;
-  const tagFilter = flags.tag;
-  if (typeof tagFilter === "string") {
-    routes = routes.filter(
-      (r) => r.tag.toLowerCase() === tagFilter.toLowerCase()
-    );
-  }
-  if (flags.json) {
-    stdout.push(JSON.stringify(routes, null, 2));
-    return result(0, stdout, stderr);
-  }
-  const grouped = /* @__PURE__ */ new Map();
-  for (const r of routes) {
-    const tag = r.tag || "Other";
-    let list = grouped.get(tag);
-    if (!list) {
-      list = [];
-      grouped.set(tag, list);
-    }
-    list.push(r);
-  }
-  const methodPad = 7;
-  for (const [tag, tagRoutes] of grouped) {
-    stdout.push("");
-    stdout.push(boldText(tag, color));
-    for (const r of tagRoutes) {
-      const m = r.method.padEnd(methodPad);
-      const desc = r.summary ? dimText(` ${r.operationId} \u2014 ${r.summary}`, color) : dimText(` ${r.operationId}`, color);
-      stdout.push(`  ${m} ${r.path}${desc}`);
-    }
-  }
-  stdout.push("");
-  return result(0, stdout, stderr);
-}
-async function runLogin(ctx) {
-  const { flags, opts, stdout, stderr } = ctx;
-  const token = flags.token;
-  if (typeof token === "string" && token.length > 0) {
-    const storage = resolveTokenStorage(opts);
-    storage.set(token);
-    stdout.push("Token stored.");
-    return result(0, stdout, stderr);
-  }
-  return runBrowserLogin(ctx);
-}
-async function runBrowserLogin(ctx) {
-  const { flags, opts, color, stdout, stderr } = ctx;
-  const http = await import("http");
-  const crypto = await import("crypto");
-  const { exec } = await import("child_process");
-  const baseUrl = resolveBaseUrl(flags, opts);
-  const code = crypto.randomBytes(3).toString("hex").toUpperCase();
-  return new Promise((resolve7) => {
-    let settled = false;
-    const settle = (exitCode) => {
-      if (settled) return;
-      settled = true;
-      server.close();
-      clearTimeout(timeout);
-      resolve7(result(exitCode, stdout, stderr));
-    };
-    const timeout = setTimeout(() => {
-      stderr.push("Timed out waiting for browser authorization.");
-      settle(1);
-    }, 12e4);
-    const server = http.createServer((req, res) => {
-      if (!req.url?.startsWith("/callback")) {
-        res.writeHead(404);
-        res.end();
-        return;
-      }
-      const url = new URL(req.url, `http://127.0.0.1`);
-      const receivedToken = url.searchParams.get("token");
-      const receivedCode = url.searchParams.get("code");
-      if (receivedCode !== code) {
-        res.writeHead(400, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ error: "Code mismatch" }));
-        stderr.push("Received callback with mismatched code. Aborting.");
-        settle(1);
-        return;
-      }
-      if (!receivedToken) {
-        res.writeHead(400, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ error: "Missing token" }));
-        stderr.push("Received callback without token. Aborting.");
-        settle(1);
-        return;
-      }
-      res.writeHead(200, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ ok: true }));
-      const storage = resolveTokenStorage(opts);
-      storage.set(receivedToken);
-      stdout.push(dimText("Authenticated successfully.", color));
-      settle(0);
-    });
-    server.listen(0, "127.0.0.1", () => {
-      const addr = server.address();
-      if (!addr || typeof addr === "string") {
-        stderr.push("Failed to start local server.");
-        settle(1);
-        return;
-      }
-      const port = addr.port;
-      const authUrl = `${baseUrl}/cli-auth?code=${encodeURIComponent(code)}&port=${port}`;
-      stdout.push(dimText("Opening browser to authorize...", color));
-      stdout.push("");
-      stdout.push(`  Confirmation code: ${boldText(code, color)}`);
-      stdout.push("");
-      stdout.push(
-        dimText("If the browser doesn't open, visit this URL manually:", color)
-      );
-      stdout.push(`  ${authUrl}`);
-      stdout.push("");
-      process.stdout.write(result(0, stdout, stderr).stdout);
-      stdout.length = 0;
-      openBrowser(authUrl, exec);
-    });
-    server.on("error", (err2) => {
-      stderr.push(`Failed to start local server: ${err2.message}`);
-      settle(1);
-    });
-  });
-}
-function openBrowser(url, exec) {
-  const platform = process.platform;
-  const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
-  exec(`${cmd} ${JSON.stringify(url)}`);
-}
-function runStatus(ctx) {
-  const { flags, opts, stdout, stderr } = ctx;
-  const storage = resolveTokenStorage(opts);
-  const baseUrl = resolveBaseUrl(flags, opts);
-  const token = storage.get();
-  stdout.push(`baseUrl: ${baseUrl}`);
-  stdout.push(`auth:    ${token ? "authenticated" : "not authenticated"}`);
-  return result(token ? 0 : 1, stdout, stderr);
-}
-async function runRequest(ctx, method, path12) {
-  const { flags, opts, color, stdout, stderr } = ctx;
-  const tokenFromFlag = flags.token;
-  const token = typeof tokenFromFlag === "string" ? tokenFromFlag : resolveTokenStorage(opts).get();
-  if (!token) {
-    stderr.push("Not authenticated. Run: uidex api login --token <value>");
-    return result(1, stdout, stderr);
-  }
-  const baseUrl = resolveBaseUrl(flags, opts);
-  const http = opts.http ?? createHttpClient({ baseUrl, token: () => token });
-  const bodyStr = typeof flags.body === "string" ? flags.body : void 0;
-  if (bodyStr !== void 0) {
-    try {
-      JSON.parse(bodyStr);
-    } catch {
-      stderr.push("Invalid JSON in --body");
-      return result(1, stdout, stderr);
-    }
-  }
-  const res = await http.request(path12, {
-    method,
-    body: bodyStr,
-    query: typeof flags.query === "string" ? flags.query : void 0
-  });
-  const isSuccess = res.status >= 200 && res.status < 300;
-  if (!isSuccess) {
-    stderr.push(formatStatus(res.status, color));
-  }
-  if (res.body !== void 0 && res.body !== null && res.body !== "") {
-    if (flags.raw) {
-      stdout.push(res.raw);
-    } else {
-      stdout.push(highlightJson(res.body, color));
-    }
-  }
-  return result(isSuccess ? 0 : 1, stdout, stderr);
-}
-function resolveTokenStorage(opts) {
-  if (opts.tokenStorage) return opts.tokenStorage;
-  const envToken = opts.env?.UIDEX_TOKEN;
-  if (envToken) return createMemoryTokenStorage(envToken);
-  return createFileTokenStorage({ path: defaultTokenPath() });
-}
-function resolveBaseUrl(flags, opts) {
-  return (typeof flags["base-url"] === "string" ? flags["base-url"] : void 0) ?? opts.baseUrl ?? opts.env?.UIDEX_API_URL ?? "https://app.uidex.dev";
-}
-function result(exitCode, stdout, stderr) {
-  return {
-    exitCode,
-    stdout: stdout.join("\n") + (stdout.length ? "\n" : ""),
-    stderr: stderr.join("\n") + (stderr.length ? "\n" : "")
-  };
-}
-
 // src/scanner/cli/cli.ts
 var argv = process.argv.slice(2);
-var command = argv[0];
-var resultP = command === "api" ? runApiCommand({ argv: argv.slice(1) }) : run({ argv });
+var resultP = run({ argv });
 resultP.then(
-  (result2) => {
-    if (result2.stdout) process.stdout.write(result2.stdout);
-    if (result2.stderr) process.stderr.write(result2.stderr);
-    process.exit(result2.exitCode);
+  (result) => {
+    if (result.stdout) process.stdout.write(result.stdout);
+    if (result.stderr) process.stderr.write(result.stderr);
+    process.exit(result.exitCode);
   },
   (error) => {
     process.stderr.write(