uidex 0.9.0 → 0.11.0

package/dist/scan/index.d.ts

@@ -15,8 +15,8 @@ interface EntityRef {
 /**
  * The four kinds every captured route is expected to render — the state-matrix
  * axis. A capture that only shoots the happy path leaves most of the value on
- * the table, so a missing core kind must be captured, waived (the page CANNOT
- * render it), or acknowledged in the MISSING_KINDS baseline.
+ * the table, so a missing core kind must be captured or ACKNOWLEDGED (see
+ * `Metadata.acknowledge`).
  */
 declare const CORE_STATE_KINDS: readonly ["loading", "empty", "populated", "error"];
 type CoreStateKind = (typeof CORE_STATE_KINDS)[number];
@@ -34,34 +34,60 @@ interface StateDecl {
     name: string;
     /** Canonical kind for the state-matrix axis (defaults to `variant`). */
     kind?: StateKind;
-    /** Acceptance criteria that only this state can evidence. */
-    acceptance?: string[];
+    /**
+     * Acceptance criteria that only this state can evidence. Normalized into the
+     * same `{ id, rev, text }` regime as entity-level `acceptance` (one
+     * criterion-id namespace per entity), so per-state criteria are claimable by
+     * `uidexCovers` and visible to every acceptance gate.
+     */
+    acceptance?: AcceptanceCriterion[];
     description?: string;
 }
+/**
+ * A normalized acceptance criterion. Authored either as a bare string (sugar:
+ * `id` is a deterministic kebab slug of the text, `rev` is 1) or as an object
+ * `{ id, rev?, text }`; parse-time normalization means everything downstream —
+ * audit, scaffold, the devtools — always sees this object shape. `rev` is the
+ * pin flows cover against (`uidexCovers("entity", "id@rev")`): bumping it when
+ * the criterion's meaning changes is what makes outdated-coverage detectable.
+ */
+interface AcceptanceCriterion {
+    id: string;
+    rev: number;
+    text: string;
+}
 interface Metadata {
     name?: string;
     description?: string;
-    acceptance?: string[];
+    acceptance?: AcceptanceCriterion[];
     notes?: string;
     composes?: EntityRef[];
     flows?: readonly string[];
     features?: string[];
     widgets?: string[];
+    /** Page ids a feature declares it must be mounted on (feature kind only). */
+    surfaces?: string[];
     /** Declared render states (see StateDecl); the capture-completeness gate. */
     states?: StateDecl[];
     /**
-     * `false` opts this page/feature/widget out of visual-states capture forever
-     * (a redirect, a static notice, an internal target). The page-coverage gate
-     * treats an opted-out route as accounted-for. Reason belongs in `description`.
-     */
-    capture?: boolean;
-    /**
-     * Per-core-kind waivers: a core kind this page's route legitimately CANNOT
-     * render (a create form has no `empty`), mapped to a substantive reason. The
-     * state-matrix gate treats a waived kind as accounted-for. A waiver is a
-     * permanent design statement — unlike MISSING_KINDS backlog, which is debt.
+     * The ONE way to say "don't complain about this gap": scope → typed reason.
+     *
+     *   - scope `"*"` covers the whole entity (a redirect page that can never be
+     *     captured, a component whose states are not gated here);
+     *   - a core-kind scope covers that one cell of this page's route matrix.
+     *
+     * `type: "impossible"` is a permanent design statement and needs a `reason`;
+     * `type: "backlog"` is debt and does not. Keeping both as values of one field
+     * is what makes mislabeling debt as impossible a visible, reviewable edit.
+     * `captured-elsewhere` is computed by the workspace and never authored here.
      */
-    waivers?: Partial<Record<CoreStateKind, string>>;
+    acknowledge?: Partial<Record<AcknowledgeScope, MetaAcknowledgment>>;
+}
+/** Scope of an acknowledgment: one core kind, or the whole entity. */
+type AcknowledgeScope = CoreStateKind | "*";
+interface MetaAcknowledgment {
+    type: "impossible" | "backlog";
+    reason?: string;
 }
 interface EntityWithMetaBase {
     id: string;
@@ -78,12 +104,25 @@ interface FlowStep {
     entityId: string;
     action?: string;
 }
+/**
+ * A per-criterion coverage claim a flow makes via
+ * `uidexCovers("<entityId>", "<criterionId>@<rev>")`. The rev is REQUIRED at
+ * the claim site — a rev-less claim could never go stale, which would defeat
+ * the outdated-detection the pin exists for.
+ */
+interface FlowCover {
+    entity: string;
+    criterion: string;
+    rev: number;
+}
 interface Flow {
     kind: "flow";
     id: string;
     loc: Location;
     touches: string[];
     steps: FlowStep[];
+    /** Acceptance-criterion coverage claims made inside this flow's describe. */
+    covers?: FlowCover[];
 }
 interface Page extends EntityWithMetaBase {
     kind: "page";
@@ -172,12 +211,38 @@ interface AuditConfig {
     scopeLeak?: boolean;
     coverage?: boolean;
     acceptance?: boolean;
+    /** Feature `surfaces` mount verification (default on; only fires when a feature declares `surfaces`). */
+    surfaces?: boolean;
+    /**
+     * Require every feature to declare at least one acceptance criterion
+     * (default ON — a bare `uidex.feature.ts` is a warning, escalatable to
+     * error via `severity` or disabled with `requireAcceptance: false`).
+     */
+    requireAcceptance?: boolean;
     /** State-capture completeness gate (default on when a manifest is present). */
     states?: boolean;
     /** Page-capture coverage gate (default on when a manifest is present). */
     pageCoverage?: boolean;
     /** State-matrix (core-kind) gate (default on when a manifest is present). */
     stateMatrix?: boolean;
+    /**
+     * Per-diagnostic-code severity overrides, e.g.
+     * `{ "missing-state-capture": "error" }`. A code's built-in severity is a
+     * default, not a policy — this is how a repo escalates an advisory gate into
+     * a build-failing ratchet, or silences one it has consciously accepted.
+     * `"off"` drops the diagnostic entirely. Unknown codes are rejected by
+     * config validation, so a typo can't silently disable a gate.
+     */
+    severity?: Record<string, DiagnosticSeverity | "off">;
+}
+/** Declared module-resolution hints for the import-graph checks. */
+interface ResolveConfig {
+    /**
+     * Specifier-prefix → config-dir-relative path-prefix aliases
+     * (e.g. `{ "@/": "src/" }`). Longest matching prefix wins. When declared,
+     * these replace the scanner's zero-config `@/` / `~/` → `src/` fallback.
+     */
+    aliases: Record<string, string>;
 }
 interface UidexConfig {
     $schema?: string;
@@ -185,6 +250,7 @@ interface UidexConfig {
     exclude?: string[];
     output: string;
     flows?: string[];
+    resolve?: ResolveConfig;
     audit?: AuditConfig;
     conventions?: ConventionsConfig;
     /**
@@ -194,11 +260,21 @@ interface UidexConfig {
      */
     statesManifest?: string;
     /**
-     * Path (relative to the config dir) of the page-coverage baseline — the
-     * tool-managed, shrink-only backlog written by `uidex scan --update-baseline`.
-     * Defaults to `uidex-coverage-baseline.json`.
+     * Path (relative to the config dir) of the coverage baseline — the
+     * tool-managed, shrink-only `acknowledge` backlog written by
+     * `uidex scan --update-baseline`. Defaults to `uidex-coverage-baseline.json`.
      */
     coverageBaseline?: string;
+    /**
+     * The workspace this app belongs to — the level that answers "did a SIBLING
+     * app capture this shared declaration?" exactly, instead of guessing.
+     *
+     *   - omitted (default): auto-detect by walking up for a workspace marker
+     *     (`pnpm-workspace.yaml`, `turbo.json`, `.git`, …). Costs a few JSON reads.
+     *   - a path (relative to the config dir): use exactly this root.
+     *   - `false`: closed world — never look at siblings.
+     */
+    workspace?: string | false;
 }
 interface DiscoveredConfig {
     configPath: string;
@@ -238,7 +314,8 @@ interface MetadataExport {
     kind: MetadataExportKind;
     id: string | false;
     name?: string;
-    acceptance?: string[];
+    /** Entity-level criteria, normalized at parse time (string sugar → object). */
+    acceptance?: AcceptanceCriterion[];
     description?: string;
     features?: string[];
     widgets?: string[];
@@ -253,16 +330,29 @@ interface MetadataExport {
      * one adjacent comma) keyed by field name. Used by `--fix` codemods.
      */
     fieldSpans?: Record<string, Span>;
+    /**
+     * Spans of top-level fields WITHOUT the comma extension (key start → value
+     * end), keyed by field name. `fieldSpans` deletes a property; this one
+     * replaces it in place, which is what the `acknowledge` codemod needs.
+     */
+    fieldPropSpans?: Record<string, Span>;
     /** Spans of the string-literal items in `features`, parallel to `features`. */
     featureSpans?: Span[];
     /** Spans of the string-literal items in `widgets`, parallel to `widgets`. */
     widgetSpans?: Span[];
+    /** Declared surface page ids (feature kind only). */
+    surfaces?: string[];
+    /** Spans of the string-literal items in `surfaces`, parallel to `surfaces`. */
+    surfaceSpans?: Span[];
     /** Declared render states (page/feature/widget); see ParsedState. */
     states?: ParsedState[];
-    /** `capture: false` opts the entity out of the page-coverage gate. */
-    capture?: boolean;
-    /** Per-core-kind waivers: kind → reason the route cannot render it. */
-    waivers?: Record<string, string>;
+    /** Scope (`"*"` | core kind) → typed acknowledgment. See `acknowledge.ts`. */
+    acknowledge?: Record<string, ParsedAcknowledgment>;
+}
+/** A parsed `acknowledge` entry from `export const uidex`. */
+interface ParsedAcknowledgment {
+    type: "impossible" | "backlog";
+    reason?: string;
 }
 /**
  * A parsed `states` entry from `export const uidex`. The authored form is a
@@ -273,7 +363,8 @@ interface ParsedState {
     name: string;
     /** Canonical kind: loading | empty | populated | error | variant. */
     kind?: string;
-    acceptance?: string[];
+    /** Per-state criteria, normalized like entity-level `acceptance`. */
+    acceptance?: AcceptanceCriterion[];
     description?: string;
     /** Span of the state's name string literal. */
     nameSpan?: Span;
@@ -290,16 +381,23 @@ interface LandmarkFact {
     tag: string;
     line: number;
 }
-/** A static import binding (import / export-from), for the scope-leak check. */
+/** An import binding (import / export-from / dynamic `import()`). */
 interface ImportFact {
     specifier: string;
     line: number;
-    /** span of the whole import/export statement */
+    /** span of the whole import/export statement (or the import() expression) */
     span: Span;
     /** `import type` or an export-from with type-only kind */
     isTypeOnly: boolean;
     /** imported local binding names (default + named + namespace) */
     names: string[];
+    /**
+     * A dynamic `import("literal")` expression. Dynamic facts are real runtime
+     * edges (React.lazy is a mount edge) so the surfaces reach-check uses them,
+     * but the scope-leak check skips them — it is about static module
+     * dependency structure, which a dynamic import doesn't declare.
+     */
+    dynamic?: true;
 }
 /** An interactive host element (`button`, `a`, …) with no data-uidex* attribute. */
 interface InteractiveElementFact {
@@ -326,6 +424,18 @@ interface FlowCallFact {
 interface DynamicFlowCallFact {
     line: number;
 }
+/**
+ * A parsed `uidexCovers("<entityId>", "<criterionId>@<rev>")` claim inside a
+ * tagged flow describe. The rev is REQUIRED at the claim site (parse
+ * diagnostic `covers-missing-rev` otherwise) — rev-pinning is what makes
+ * outdated-coverage detection possible.
+ */
+interface FlowCoverFact {
+    entity: string;
+    criterion: string;
+    rev: number;
+    line: number;
+}
 /** A tagged `test.describe(..., { tag: "@uidex:flow" }, ...)` occurrence. */
 interface FlowFact {
     title: string;
@@ -333,6 +443,8 @@ interface FlowFact {
     calls: FlowCallFact[];
     /** uidex() calls inside this describe whose ids could not be resolved */
     dynamicCalls?: DynamicFlowCallFact[];
+    /** uidexCovers() acceptance-coverage claims inside this describe */
+    covers?: FlowCoverFact[];
 }
 interface ExtractedFile {
     file: ScannedFile;
@@ -340,6 +452,8 @@ interface ExtractedFile {
     metadata?: MetadataExport[];
     diagnostics?: Diagnostic[];
     flows?: FlowFact[];
+    /** true when the file contains any JSX element or fragment */
+    hasJsx?: boolean;
     dynamicAttrs?: DynamicAttrFact[];
     unannotatedInteractive?: InteractiveElementFact[];
     landmarks?: LandmarkFact[];
@@ -405,6 +519,13 @@ declare const CONFIG_FILENAME = ".uidex.json";
 interface DiscoverOptions {
     cwd?: string;
     maxDepth?: number;
+    /**
+     * Keep descending past a config found at `cwd` itself, so the result is EVERY
+     * config in the tree rather than the innermost one. The workspace level needs
+     * the whole set; a plain `uidex scan` wants the nearest, which is why that
+     * stays the default.
+     */
+    all?: boolean;
 }
 declare function discover(options?: DiscoverOptions): DiscoveredConfig[];
 
@@ -474,6 +595,142 @@ interface ResolveOutput {
  */
 declare function resolve(ctx: ResolveContext): ResolveOutput;
 
+/**
+ * ACKNOWLEDGMENT — the single primitive for "don't complain about this".
+ *
+ * There used to be four mechanisms plus an implicit fifth (`waivers`, the
+ * baseline's `missingKinds` / `uncapturedPages`, `capture: false`, and a
+ * borrowed-entity inference). They overlapped, lived in unrelated files with
+ * unrelated shapes, and the rule keeping them straight — "don't fold capturable
+ * debt into a waiver" — was enforced socially, in prose, because nothing
+ * structural stopped you reaching for the wrong one.
+ *
+ * They are now one map from a SCOPE to a typed REASON:
+ *
+ *     acknowledge: {
+ *       empty: { type: "impossible", reason: "a create form has no empty state" },
+ *       "*":   { type: "backlog" },
+ *     }
+ *
+ * SCOPE is a core kind (that kind of this route) or `"*"` (the whole entity —
+ * every axis of it). TYPE is why:
+ *
+ *   - `impossible` — human-authored. The surface CANNOT render this; a
+ *     substantive `reason` is REQUIRED. Contradicted by an actual capture →
+ *     `stale-acknowledgment`.
+ *   - `backlog` — debt. It CAN render this and nobody has captured it yet.
+ *     `reason` is optional. Tool-managed in the coverage baseline
+ *     (`--update-baseline`, shrink-only), and authorable in source when you want
+ *     the debt to sit next to the declaration.
+ *   - `captured-elsewhere` — COMPUTED by the workspace level, never authored: a
+ *     sibling app that registers this same declaration captured it. Replaces the
+ *     borrowed-entity guess with an exact answer.
+ *
+ * The anti-laundering property is now structural rather than social:
+ * `impossible` and `backlog` are sibling values of ONE field, so choosing wrongly
+ * is a one-token, greppable, reviewable edit — not a choice between two
+ * unrelated files. And the reason rule points the lazy path at the honest
+ * answer: `impossible` costs you a sentence, `backlog` is free.
+ */
+/** The scope key meaning "the whole entity", not one core kind. */
+declare const ACK_ALL = "*";
+/** Every valid scope key: the four core kinds plus `"*"`. */
+declare const ACK_SCOPES: readonly string[];
+type AcknowledgeType = "impossible" | "backlog" | "captured-elsewhere";
+interface Acknowledgment {
+    type: AcknowledgeType;
+    /** Why. Required for `impossible`, optional for `backlog`. */
+    reason?: string;
+    /** `captured-elsewhere` only: the workspace app whose capture covers this. */
+    by?: string;
+}
+/** scope (`"*"` | core kind) → why it is acknowledged. */
+type AcknowledgeMap = Record<string, Acknowledgment>;
+/** Where an acknowledgment came from, so diagnostics can point at the right file. */
+type AcknowledgeOrigin = "source" | "baseline" | "workspace";
+interface ResolvedAcknowledgment extends Acknowledgment {
+    scope: string;
+    origin: AcknowledgeOrigin;
+}
+/**
+ * The committed, tool-managed coverage backlog. Same `Acknowledgment` shape as
+ * the source-authored field, keyed by route pattern — so the two really are the
+ * same primitive in two homes, not two lookalikes.
+ */
+interface CoverageBaseline {
+    version: 2;
+    /** route pattern → scope → acknowledgment (always `type: "backlog"`). */
+    acknowledge: Record<string, AcknowledgeMap>;
+}
+/**
+ * The acknowledgments in force for one ROUTE: the baseline's entry for the route
+ * layered UNDER the page's own `acknowledge`. Source wins — a human statement
+ * outranks tool-recorded debt, and `--update-baseline` drops the shadowed entry
+ * on its next run.
+ */
+declare function routeAcknowledge(registry: Registry, baseline: CoverageBaseline | undefined, route: string, page: string | undefined): Map<string, ResolvedAcknowledgment>;
+/**
+ * The acknowledgments in force for one ENTITY (page/feature/widget). Only `"*"`
+ * is meaningful here — the core-kind axis is route-scoped. `capturedElsewhere`
+ * is the workspace's computed verdict; source still wins, so an explicit
+ * `impossible` is never silently reinterpreted.
+ */
+declare function entityAcknowledge(meta: Metadata | undefined, capturedElsewhereBy?: string): ResolvedAcknowledgment | undefined;
+/**
+ * Parse a v2 baseline. Malformed entries are dropped rather than thrown on: a
+ * hand-mangled baseline must not crash the scan, and every dropped entry simply
+ * re-appears as an unacknowledged gap the gate reports.
+ */
+declare function parseCoverageBaseline(raw: unknown): CoverageBaseline | null;
+/** Serialize a baseline with stable key order, so its diff is reviewable. */
+declare function serializeCoverageBaseline(baseline: CoverageBaseline): string;
+
+interface WorkspaceApp {
+    /** Display name — the config dir's basename (e.g. "platform-web"). */
+    name: string;
+    configDir: string;
+    configPath: string;
+    /** Whether this app's configured sources would register `absFile`. */
+    registers: (absFile: string) => boolean;
+    /** `captureKey` values this app's manifest captured. */
+    captured: ReadonlySet<string>;
+}
+interface Workspace {
+    root: string;
+    /** Every OTHER app in the workspace; the scanning app is excluded. */
+    siblings: WorkspaceApp[];
+}
+interface ResolveWorkspaceOptions {
+    configDir: string;
+    config: UidexConfig;
+    /** Overrides discovery; used by tests to avoid touching the real filesystem. */
+    configs?: DiscoveredConfig[];
+}
+/**
+ * Walk up from the app looking for a workspace marker. Returns `undefined` when
+ * there is none — a standalone app then keeps today's closed-world behavior
+ * rather than silently treating its parent directory as a workspace.
+ */
+declare function findWorkspaceRoot(configDir: string): string | undefined;
+/**
+ * Resolve the workspace an app participates in.
+ *
+ * `config.workspace` selects the root: a path (relative to the config dir),
+ * `false` for an explicit closed world, or omitted for auto-detect via
+ * `findWorkspaceRoot`. Returns `undefined` when there is no workspace or no
+ * sibling in it — callers then behave exactly as a single-app scan does.
+ */
+declare function resolveWorkspace(opts: ResolveWorkspaceOptions): Workspace | undefined;
+/**
+ * The sibling app that already captured this declaration, if any — the exact
+ * answer that replaces the borrowed-entity guess. `absFile` is the declaring
+ * file's real path (a display path cannot be resolved back across a `prefix`).
+ *
+ * A capture recording no `kind` matches on id alone, mirroring how the
+ * state-coverage gate treats an unlabeled capture.
+ */
+declare function capturedElsewhere(workspace: Workspace | undefined, absFile: string | undefined, kind: string, id: string): string | undefined;
+
 /**
  * State-capture completeness — the deterministic replacement for a bespoke
  * `check-states.mjs`. Cross-checks the states DECLARED on registry entities
@@ -487,8 +744,17 @@ declare function resolve(ctx: ResolveContext): ResolveOutput;
  *   - `orphan-state-capture` — a run captured a state the entity never declared,
  *     so the contact sheet shows a state the registry doesn't know about.
  *
- * Pure: same (registry, manifest) → same diagnostics. Only runs when a manifest
- * is present, so a plain `uidex scan` (no capture run) never fails on it.
+ * Two things take an entity out of the gate, and both are acknowledgments:
+ * a SOURCE `acknowledge: { "*": … }`, or the WORKSPACE observing that a sibling
+ * app which registers this same declaration captured it (`captured-elsewhere`).
+ *
+ * The workspace answer replaces a heuristic this module used to carry: a
+ * "borrowed" entity (one declared under a shared source `prefix`) that this app
+ * captured nothing for was ASSUMED to be a sibling's responsibility. That guess
+ * could not tell a genuinely shared component from an id that merely collided
+ * with a sibling's, and it silenced real gaps whenever an app captured nothing.
+ * The workspace checks the sibling's actual source set and actual manifest, so
+ * the answer is exact and the guess is gone.
  */
 /** One `entity/state` a capture run recorded. */
 interface CapturedState {
@@ -507,49 +773,21 @@ interface CapturedState {
 }
 interface CapturedStatesManifest {
     captured: CapturedState[];
+    /** ISO timestamp the reporter stamped; drives the staleness check. */
+    generatedAt?: string;
 }
-declare function checkStateCoverage(registry: Registry, manifest: CapturedStatesManifest): Diagnostic[];
-
-/**
- * Page-capture coverage — the coarse gate above the per-state gate. Every
- * derived route must be accounted for: captured (a run drove it), opted out
- * (`export const uidex = { page, capture: false }`), or acknowledged backlog (a
- * tool-managed, shrink-only baseline). A route in none of those is a *new*
- * uncaptured page and fails hard — the ratchet that keeps debt from growing.
- *
- * uidex derives the route set (route groups stripped, dynamic segments kept), so
- * unlike a hand-rolled `src/app/**` walk there is no page list to enumerate or
- * keep from rotting: a route exists in the registry or it doesn't. And captures
- * observe the URL they ran against, so which route a capture covers is matched,
- * never hand-declared.
- */
-/** The committed, tool-managed backlog. Shrinks as pages/kinds get captured. */
-interface PageCoverageBaseline {
-    /** Route patterns acknowledged as uncaptured (e.g. "/[scope]/collections"). */
-    uncapturedPages: string[];
-    /** route → core kinds acknowledged as not-yet-captured (the matrix backlog). */
-    missingKinds?: Record<string, string[]>;
+interface StateCoverageOptions {
+    /** The workspace, when one is resolved; enables `captured-elsewhere`. */
+    workspace?: Workspace;
+    /**
+     * Maps an entity's `loc.file` (a DISPLAY path, which a `prefix` makes
+     * unresolvable on its own) back to its real path on disk. Supplied by
+     * `audit()` from the scanned-file list, so the workspace can test the file
+     * against a sibling's source roots.
+     */
+    resolveSourcePath?: (displayPath: string) => string | undefined;
 }
-/**
- * Turn a Next-style route pattern into an anchored matcher.
- *   `/[scope]/products/[productId]/edit` → matches `/acme/products/p1/edit`
- *   `/[...slug]` (catch-all) → matches one or more segments
- * Returns the literal-segment count as a specificity score, so the most literal
- * matching pattern wins when several match (e.g. `/x/new` beats `/x/[id]`).
- */
-declare function compileRoute(pattern: string): {
-    test: (url: string) => boolean;
-    specificity: number;
-};
-/** The route pattern (from the given set) that most-specifically matches a URL. */
-declare function matchUrlToRoute(url: string, routePaths: string[]): string | null;
-declare function checkPageCoverage(registry: Registry, manifest: CapturedStatesManifest, baseline?: PageCoverageBaseline): Diagnostic[];
-/**
- * Compute the shrink-only baseline for `--update-baseline`: every route with no
- * capture and no opt-out. Seeds on first run and prunes on later runs; growth
- * only ever happens through this explicit command, visible in the file's diff.
- */
-declare function computePageBaseline(registry: Registry, manifest: CapturedStatesManifest): PageCoverageBaseline;
+declare function checkStateCoverage(registry: Registry, manifest: CapturedStatesManifest, opts?: StateCoverageOptions): Diagnostic[];
 
 interface AuditOptions {
     registry: Registry;
@@ -581,8 +819,10 @@ interface AuditOptions {
     locsOutputPath?: string;
     /** Captured-states manifest for the completeness gate; absent → gate skipped. */
     capturedStates?: CapturedStatesManifest;
-    /** Page-coverage baseline (the shrink-only backlog); absent → empty baseline. */
-    pageBaseline?: PageCoverageBaseline;
+    /** Coverage baseline (the shrink-only `acknowledge` backlog). */
+    coverageBaseline?: CoverageBaseline;
+    /** The resolved workspace; enables `captured-elsewhere`. */
+    workspace?: Workspace;
 }
 declare function audit(opts: AuditOptions): AuditSummary;
 
@@ -688,11 +928,13 @@ interface RunScanOptions {
     configs?: DiscoveredConfig[];
     /** Captured-states manifest for the completeness gate; overrides on-disk load. */
     capturedStates?: CapturedStatesManifest;
-    /** Page-coverage baseline; overrides on-disk load. */
-    pageBaseline?: PageCoverageBaseline;
+    /** Coverage baseline (the shrink-only backlog); overrides on-disk load. */
+    coverageBaseline?: CoverageBaseline;
+    /** Workspace override; skips auto-detection (used by tests). */
+    workspace?: Workspace;
 }
-/** Load the page-coverage baseline from disk, if present + well-formed. */
-declare function loadPageBaseline(configDir: string, config: UidexConfig): PageCoverageBaseline | undefined;
+/** Load the coverage baseline from disk, if present + well-formed. */
+declare function loadCoverageBaseline(configDir: string, config: UidexConfig): CoverageBaseline | undefined;
 /** One generated artifact: its bytes plus where it lands (abs + repo-relative). */
 interface ScanArtifact {
     generated: string;
@@ -724,33 +966,97 @@ declare function runScan(opts?: RunScanOptions): ScanResult[];
  * actually moved. Returns `true` if any file was written.
  */
 declare function writeScanResult(result: ScanResult): boolean;
-/** Absolute path of the page-coverage baseline for a scan result. */
-declare function pageBaselinePath(result: ScanResult): string;
+/** Absolute path of the coverage baseline for a scan result. */
+declare function coverageBaselinePath(result: ScanResult): string;
+
+/**
+ * Page-capture coverage — the coarse gate above the per-state gate. Every
+ * derived route must be accounted for: captured (a run drove it), or
+ * ACKNOWLEDGED at `"*"` scope — either `impossible` (a redirect, a static
+ * notice, an internal target — the old `capture: false`, which now has to say
+ * WHY) or `backlog` (tool-managed, shrink-only). A route in none of those is a
+ * *new* uncaptured page and fails hard — the ratchet that keeps debt growing.
+ *
+ * uidex derives the route set (route groups stripped, dynamic segments kept), so
+ * unlike a hand-rolled `src/app/**` walk there is no page list to enumerate or
+ * keep from rotting: a route exists in the registry or it doesn't. And captures
+ * observe the URL they ran against, so which route a capture covers is matched,
+ * never hand-declared.
+ */
+/**
+ * Turn a Next-style route pattern into an anchored matcher.
+ *   `/[scope]/products/[productId]/edit` → matches `/acme/products/p1/edit`
+ *   `/[...slug]` (catch-all) → matches one or more segments
+ * Returns the literal-segment count as a specificity score, so the most literal
+ * matching pattern wins when several match (e.g. `/x/new` beats `/x/[id]`).
+ */
+declare function compileRoute(pattern: string): {
+    test: (url: string) => boolean;
+    specificity: number;
+};
+/** The route pattern (from the given set) that most-specifically matches a URL. */
+declare function matchUrlToRoute(url: string, routePaths: string[]): string | null;
+declare function checkPageCoverage(registry: Registry, manifest: CapturedStatesManifest, baseline?: CoverageBaseline): Diagnostic[];
+/**
+ * The page half of the shrink-only baseline for `--update-baseline`: every route
+ * with no capture and no SOURCE acknowledgment. Seeds on first run and prunes on
+ * later runs; growth only ever happens through this explicit command, visible in
+ * the file's diff.
+ */
+declare function computePageBacklog(registry: Registry, manifest: CapturedStatesManifest): Record<string, AcknowledgeMap>;
 
+declare function checkStateMatrix(registry: Registry, manifest: CapturedStatesManifest, baseline?: CoverageBaseline): Diagnostic[];
 /**
- * State-matrix coverage — the second completeness axis. A capture that only ever
- * shoots the happy path leaves most of the harness's value on the table, so
- * every *captured* route must render each of the four core kinds
- * (loading / empty / populated / error), or account for the gap:
+ * The matrix half of the shrink-only baseline for `--update-baseline`: every
+ * (captured route, core kind) that is neither captured nor already acknowledged
+ * in SOURCE. Source acknowledgments are excluded so the same gap is never
+ * recorded twice, in two files, saying two things.
+ */
+declare function computeMatrixBacklog(registry: Registry, manifest: CapturedStatesManifest): Record<string, AcknowledgeMap>;
+
+declare function checkComponentCoverage(registry: Registry, manifest: CapturedStatesManifest): Diagnostic[];
+
+/**
+ * Fold a PARTIAL capture manifest into the committed one.
  *
- *   - a **waiver** (`export const uidex = { page, waivers: { empty: "…" } }`) —
- *     the route CANNOT render that kind (a create form has no empty state);
- *   - the **MISSING_KINDS baseline** — the route CAN render it and nobody has
- *     captured it yet (a per-(route, kind) shrink-only backlog).
+ * A filtered run (`--grep`) legitimately captures a subset, so the reporter's
+ * shrink guard diverts it to `<name>.partial.json` rather than overwriting a
+ * fuller manifest. Without a merge path the only ways forward are re-running the
+ * FULL suite or hand-editing JSON — both of which make scoped re-capture
+ * expensive enough that people skip it and let the manifest drift.
  *
- * Anything else is a `core-kind` error. Only *captured* routes are in scope: a
- * route with no capture at all is a page-coverage concern, not a matrix hole.
+ * Merge is by `(kind, entity, state)`: rows in the partial REPLACE their
+ * counterparts (that run is the newer evidence) and rows absent from it are
+ * preserved (it never claimed to cover them). So merging is purely additive to
+ * coverage — it can never drop a state, which is what makes it safe to run
+ * without re-reading the whole manifest.
  */
-/** route → core kinds acknowledged as not-yet-captured (the finer ratchet). */
-interface StateMatrixBaseline {
-    missingKinds: Record<string, string[]>;
+interface MergeResult {
+    manifest: CapturedStatesManifest;
+    /** `(kind, entity, state)` keys the partial replaced. */
+    updated: string[];
+    /** Keys the partial contributed that the committed manifest lacked. */
+    added: string[];
+}
+declare function mergeStates(committed: CapturedStatesManifest, partial: CapturedStatesManifest): MergeResult;
+
+declare class ConfigError extends Error {
+    constructor(message: string);
 }
-declare function checkStateMatrix(registry: Registry, manifest: CapturedStatesManifest, baseline?: StateMatrixBaseline): Diagnostic[];
 /**
- * Compute the shrink-only MISSING_KINDS baseline for `--update-baseline`: every
- * (captured route, core kind) that is neither captured nor waived.
+ * Every diagnostic code the scanner can emit — the allow-list `audit.severity`
+ * validates against, so a typo'd key fails loudly instead of silently leaving
+ * the gate it was meant to govern at its default severity.
+ *
+ * Keep in sync when adding a diagnostic; `tests/scan/severity-codes.test.ts`
+ * asserts this set matches the codes actually emitted by the source — a code
+ * missing here cannot be softened/disabled by any repo (validateConfig
+ * rejects unknown `audit.severity` keys).
  */
-declare function computeMissingKinds(registry: Registry, manifest: CapturedStatesManifest): Record<string, string[]>;
+declare const DIAGNOSTIC_CODES: readonly ["acceptance-ambiguous", "acceptance-duplicate-id", "acceptance-orphaned", "acceptance-outdated", "acceptance-uncovered", "acknowledged-elsewhere", "competing-uidex-export", "component-state-uncaptured", "core-kind", "covers-missing-rev", "duplicate-id", "dynamic-attr", "dynamic-flow-reference", "feature-missing-acceptance", "feature-surface-uncaptured", "feature-surface-unreferenced", "gen-missing", "gen-stale", "matrix-backlog", "missing-element-annotation", "missing-state-capture", "orphan-state-capture", "page-backlog", "page-captured", "page-no-capture", "parse-error", "placeholder-reason", "prefer-well-known-file", "rename", "scope-leak", "spread-attr", "stale-acknowledgment", "stale-page-baseline", "uidex-export-ambiguous-kind", "uidex-export-duplicate-field", "uidex-export-duplicate-state", "uidex-export-empty-name", "uidex-export-invalid-field", "uidex-export-invalid-literal", "uidex-export-missing-kind", "uidex-export-satisfies-mismatch", "uidex-export-unknown-field", "unknown-reference", "widget-id-mismatch", "widget-missing-acceptance", "widget-missing-dom"];
+declare function validateConfig(raw: unknown): UidexConfig;
+declare function parseConfig(json: string): UidexConfig;
+declare const DEFAULT_CONVENTIONS: Required<Pick<NonNullable<UidexConfig["conventions"]>, "primitives" | "features" | "pages" | "flows" | "regions">>;
 
 /**
  * Applies the machine-generated fixes attached to diagnostics.
@@ -816,13 +1122,6 @@ interface CliOptions {
 }
 declare function run(opts: CliOptions): Promise<CliResult>;
 
-declare class ConfigError extends Error {
-    constructor(message: string);
-}
-declare function validateConfig(raw: unknown): UidexConfig;
-declare function parseConfig(json: string): UidexConfig;
-declare const DEFAULT_CONVENTIONS: Required<Pick<NonNullable<UidexConfig["conventions"]>, "primitives" | "features" | "pages" | "flows" | "regions">>;
-
 /**
  * Authoring-surface shape types for `export const uidex = { ... }` declarations.
  *
@@ -842,32 +1141,74 @@ declare const DEFAULT_CONVENTIONS: Required<Pick<NonNullable<UidexConfig["conven
 declare namespace Uidex {
     type CoreStateKind = "loading" | "empty" | "populated" | "error";
     type StateKind = CoreStateKind | "variant";
+    /**
+     * An acceptance criterion as authored. A bare string is sugar: its `id`
+     * becomes a deterministic kebab slug of the text and `rev` defaults to 1.
+     * The object form pins an explicit `id` (stable across copy edits) and an
+     * optional `rev` (bump it when the criterion's meaning changes so flow
+     * coverage pinned to the old rev surfaces as outdated).
+     */
+    interface AcceptanceCriterion {
+        id: string;
+        rev?: number;
+        text: string;
+    }
+    type Acceptance = readonly (string | AcceptanceCriterion)[];
     /** A declared render state, as authored in `states: [{ name, ... }]`. */
     interface State {
         name: string;
         kind?: StateKind;
-        acceptance?: readonly string[];
+        /** Per-state criteria; same authoring sugar as entity-level `acceptance`. */
+        acceptance?: Acceptance;
         description?: string;
     }
-    /** Per-core-kind waivers: a kind this route cannot render → reason. */
-    type Waivers = Partial<Record<CoreStateKind, string>>;
+    /** Scope of an acknowledgment: one core kind, or the whole entity. */
+    type AcknowledgeScope = CoreStateKind | "*";
+    /** A permanent design statement — so it has to say why. */
+    interface Impossible {
+        type: "impossible";
+        reason: string;
+    }
+    /** Debt: capturable, not captured yet. No reason required. */
+    interface Backlog {
+        type: "backlog";
+        reason?: string;
+    }
+    type Acknowledgment = Impossible | Backlog;
+    type Acknowledge = Partial<Record<AcknowledgeScope, Acknowledgment>>;
+    /** A component has no route, so only the `"*"` scope applies to one. */
+    type ComponentAcknowledge = {
+        "*"?: Acknowledgment;
+    };
     interface Page<PageIds extends string = string, FeatureIds extends string = string, WidgetIds extends string = string> {
         page: PageIds | false;
         name?: string;
         features?: readonly FeatureIds[];
         widgets?: readonly WidgetIds[];
-        acceptance?: readonly string[];
+        acceptance?: Acceptance;
         states?: readonly (string | State)[];
-        capture?: boolean;
-        waivers?: Waivers;
+        acknowledge?: Acknowledge;
         description?: string;
     }
-    interface Feature<FeatureIds extends string = string> {
+    interface Feature<FeatureIds extends string = string, PageIds extends string = string> {
         feature: FeatureIds | false;
         name?: string;
         features?: readonly FeatureIds[];
-        acceptance?: readonly string[];
+        /**
+         * Pages this feature MUST be mounted on. Each id is verified by the audit
+         * in two halves: the page must exist and its import closure must reference
+         * a component file in the feature's directory (the static
+         * `feature-surface-unreferenced` tripwire), and — when a captured-states
+         * manifest is present — a capture must have rendered the feature on the
+         * page's route (`feature-surface-uncaptured`, the runtime evidence). This
+         * is how a cross-cutting feature (a gate editor, a share panel) states
+         * "every one of these editors owes me a mount" and a forgotten mount fails
+         * the scan instead of shipping.
+         */
+        surfaces?: readonly PageIds[];
+        acceptance?: Acceptance;
         states?: readonly (string | State)[];
+        acknowledge?: ComponentAcknowledge;
         description?: string;
     }
     interface Primitive<PrimitiveIds extends string = string> {
@@ -878,8 +1219,14 @@ declare namespace Uidex {
     interface Widget<WidgetIds extends string = string> {
         widget: WidgetIds;
         name?: string;
-        acceptance?: readonly string[];
+        acceptance?: Acceptance;
         states?: readonly (string | State)[];
+        acknowledge?: ComponentAcknowledge;
+        description?: string;
+    }
+    interface Region<RegionIds extends string = string> {
+        region: RegionIds | false;
+        name?: string;
         description?: string;
     }
     interface Flow<FlowIds extends string = string> {
@@ -892,4 +1239,4 @@ declare namespace Uidex {
     }
 }
 
-export { type Annotation, type AnnotationKind, type AppliedFix, type ApplyFixesResult, type AuditConfig, type AuditSummary, CONFIG_FILENAME, type CapturedState, type CapturedStatesManifest, type CliOptions, type CliResult, ConfigError, type ConventionsConfig, DEFAULT_CONVENTIONS, type DetectedRoute, type Diagnostic, type DiagnosticFix, type DiagnosticSeverity, type DiscoveredConfig, type ExtractedFile, type FixEdit, type GitContext, type ImportFact, type LandmarkFact, type MetadataExport, type MetadataExportKind, type PageCoverageBaseline, type ParsedState, type RenameKind, type RenameOptions, type RenameResult, type RunScanOptions, type ScaffoldKind, type ScaffoldOptions, type ScaffoldResult, type ScaffoldSpecOptions, type ScanResult, type ScannedFile, type SourceConfig, type Span, type StateMatrixBaseline, Uidex, type UidexConfig, applyFixes, audit, checkPageCoverage, checkStateCoverage, checkStateMatrix, compileRoute, computeMissingKinds, computePageBaseline, detectRoutes, discover, emit, extract, extractUidexExports, globToRegExp, loadPageBaseline, matchUrlToRoute, pageBaselinePath, parseConfig, pathToId, renameEntity, resolve, resolveGitContext, run as runCli, runScan, scaffoldSpec, scaffoldWidgetSpec, validateConfig, walk, writeScanResult };
+export { ACK_ALL, ACK_SCOPES, type AcknowledgeMap, type AcknowledgeOrigin, type AcknowledgeType, type Acknowledgment, type Annotation, type AnnotationKind, type AppliedFix, type ApplyFixesResult, type AuditConfig, type AuditSummary, CONFIG_FILENAME, type CapturedState, type CapturedStatesManifest, type CliOptions, type CliResult, ConfigError, type ConventionsConfig, type CoverageBaseline, DEFAULT_CONVENTIONS, DIAGNOSTIC_CODES, type DetectedRoute, type Diagnostic, type DiagnosticFix, type DiagnosticSeverity, type DiscoveredConfig, type ExtractedFile, type FixEdit, type GitContext, type ImportFact, type LandmarkFact, type MergeResult, type MetadataExport, type MetadataExportKind, type ParsedAcknowledgment, type ParsedState, type RenameKind, type RenameOptions, type RenameResult, type ResolvedAcknowledgment, type RunScanOptions, type ScaffoldKind, type ScaffoldOptions, type ScaffoldResult, type ScaffoldSpecOptions, type ScanResult, type ScannedFile, type SourceConfig, type Span, type StateCoverageOptions, Uidex, type UidexConfig, type Workspace, type WorkspaceApp, applyFixes, audit, capturedElsewhere, checkComponentCoverage, checkPageCoverage, checkStateCoverage, checkStateMatrix, compileRoute, computeMatrixBacklog, computePageBacklog, coverageBaselinePath, detectRoutes, discover, emit, entityAcknowledge, extract, extractUidexExports, findWorkspaceRoot, globToRegExp, loadCoverageBaseline, matchUrlToRoute, mergeStates, parseConfig, parseCoverageBaseline, pathToId, renameEntity, resolve, resolveGitContext, resolveWorkspace, routeAcknowledge, run as runCli, runScan, scaffoldSpec, scaffoldWidgetSpec, serializeCoverageBaseline, validateConfig, walk, writeScanResult };