uidex 0.6.0 → 0.8.0

package/dist/scan/index.d.ts

@@ -1,3 +1,5 @@
+import { Program } from 'oxc-parser';
+
 declare const ENTITY_KINDS: readonly ["route", "page", "feature", "widget", "region", "element", "primitive", "flow"];
 type EntityKind = (typeof ENTITY_KINDS)[number];
 type Scope = string;
@@ -10,6 +12,32 @@ interface EntityRef {
     kind: EntityKind;
     id: string;
 }
+/**
+ * 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.
+ */
+declare const CORE_STATE_KINDS: readonly ["loading", "empty", "populated", "error"];
+type CoreStateKind = (typeof CORE_STATE_KINDS)[number];
+/** `variant` is any state outside the matrix (a dialog, wizard step, multi-currency…). */
+type StateKind = CoreStateKind | "variant";
+/**
+ * A declared render state of an entity — the "story"-like unit: a named
+ * condition the page/feature/widget can render in (loading / empty / error /
+ * multi-currency / …). Enumerated on the entity (not derived from syntax), it
+ * is the contract the visual-states capture must satisfy and the anchor for
+ * per-state acceptance criteria. Fixtures + capture mechanics stay in the spec;
+ * the registry holds only the name (+ optional kind / per-state acceptance).
+ */
+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[];
+    description?: string;
+}
 interface Metadata {
     name?: string;
     description?: string;
@@ -19,6 +47,21 @@ interface Metadata {
     flows?: readonly string[];
     features?: string[];
     widgets?: 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.
+     */
+    waivers?: Partial<Record<CoreStateKind, string>>;
 }
 interface EntityWithMetaBase {
     id: string;
@@ -64,6 +107,7 @@ type Entity = Route | Page | Feature | Widget | Region | Element | Primitive | F
 type EntityByKind<K extends EntityKind> = Extract<Entity, {
     kind: K;
 }>;
+type MetaEntityKind = Exclude<EntityKind, "route" | "flow">;
 
 interface ReportRecord {
     id: string;
@@ -96,7 +140,7 @@ interface Registry {
     setReports(kind: EntityKind, id: string, reports: readonly ReportRecord[]): void;
     getReports(kind: EntityKind, id: string): readonly ReportRecord[];
     listReportKeys(): readonly string[];
-    archiveReport?: (reportId: string, reason?: string) => void | Promise<void>;
+    closeReport?: (reportId: string, status?: string) => void | Promise<void>;
     onReportsChange(cb: () => void): () => void;
 }
 
@@ -117,17 +161,33 @@ interface AuditConfig {
     scopeLeak?: boolean;
     coverage?: boolean;
     acceptance?: 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;
 }
-type TypeMode = "strict" | "loose";
 interface UidexConfig {
     $schema?: string;
     sources: SourceConfig[];
     exclude?: string[];
     output: string;
     flows?: string[];
-    typeMode?: TypeMode;
     audit?: AuditConfig;
     conventions?: ConventionsConfig;
+    /**
+     * Path (relative to the config dir) of the captured-states manifest the
+     * Playwright states reporter writes. The completeness gate reads it when
+     * present. Defaults to `uidex-states.json`.
+     */
+    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`.
+     */
+    coverageBaseline?: string;
 }
 interface DiscoveredConfig {
     configPath: string;
@@ -140,7 +200,12 @@ interface ScannedFile {
     displayPath: string;
     content: string;
 }
-type AnnotationKind = "element" | "region" | "widget" | "primitive" | "page-doc" | "feature-doc" | "widget-doc" | "not-flow" | "orphan-acceptance";
+/** Byte-offset range into a ScannedFile's content (UTF-16 code units, like oxc spans). */
+interface Span {
+    start: number;
+    end: number;
+}
+type AnnotationKind = "element" | "region" | "widget" | "primitive";
 type DomAttrKind = "element" | "region" | "widget" | "primitive";
 interface AnnotationAncestor {
     kind: DomAttrKind;
@@ -151,10 +216,10 @@ interface Annotation {
     id: string;
     file: string;
     line: number;
-    description?: string;
-    acceptance?: string[];
-    /** JSX ancestor chain, outermost to innermost. Only populated for DOM-attribute kinds. */
+    /** JSX ancestor chain, outermost to innermost. */
     ancestors?: AnnotationAncestor[];
+    /** The span of the attribute's value literal. */
+    span?: Span;
 }
 type MetadataExportKind = "page" | "feature" | "primitive" | "widget" | "region" | "flow";
 interface MetadataExport {
@@ -168,12 +233,106 @@ interface MetadataExport {
     widgets?: string[];
     notFlow?: boolean;
     loc: Location;
+    /** Span of the whole `export const uidex = ...` statement (incl. trailing `;`). */
+    span?: Span;
+    /** Span of the id string literal (the discriminator field's value). */
+    idSpan?: Span;
+    /**
+     * Removal-ready spans of top-level fields (key through value, extended over
+     * one adjacent comma) keyed by field name. Used by `--fix` codemods.
+     */
+    fieldSpans?: 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 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>;
+}
+/**
+ * A parsed `states` entry from `export const uidex`. The authored form is a
+ * string (bare name) or an object `{ name, acceptance?, description? }`; both
+ * normalize to this. `nameSpan` powers a future `uidex rename state`.
+ */
+interface ParsedState {
+    name: string;
+    /** Canonical kind: loading | empty | populated | error | variant. */
+    kind?: string;
+    acceptance?: string[];
+    description?: string;
+    /** Span of the state's name string literal. */
+    nameSpan?: Span;
+}
+/** A data-uidex* attribute whose value the scanner could not resolve. */
+interface DynamicAttrFact {
+    kind: DomAttrKind;
+    attrName: string;
+    line: number;
+}
+/** An HTML5 landmark element (`<header>`, `<nav>`, …, or `role="region"`). */
+interface LandmarkFact {
+    /** the host tag, or "region" for role="region" */
+    tag: string;
+    line: number;
+}
+/** A static import binding (import / export-from), for the scope-leak check. */
+interface ImportFact {
+    specifier: string;
+    line: number;
+    /** span of the whole import/export statement */
+    span: Span;
+    /** `import type` or an export-from with type-only kind */
+    isTypeOnly: boolean;
+    /** imported local binding names (default + named + namespace) */
+    names: string[];
+}
+/** An interactive host element (`button`, `a`, …) with no data-uidex* attribute. */
+interface InteractiveElementFact {
+    tag: string;
+    line: number;
+    /** the element carries a `{...props}` spread that may deliver the annotation */
+    hasSpread: boolean;
+    /** offset just after the tag name; where `--fix` inserts the generated attribute */
+    nameEnd: number;
+    /**
+     * Best static label for deriving an id (aria-label, visible text, title,
+     * name, placeholder). Absent when nothing usable is statically available.
+     */
+    nameHint?: string;
+}
+interface FlowCallFact {
+    id: string;
+    action?: string;
+    line: number;
+    /** span of the id string literal argument */
+    span?: Span;
+}
+/** A `uidex(expr)` call whose argument is not a static string literal. */
+interface DynamicFlowCallFact {
+    line: number;
+}
+/** A tagged `test.describe(..., { tag: "@uidex:flow" }, ...)` occurrence. */
+interface FlowFact {
+    title: string;
+    line: number;
+    calls: FlowCallFact[];
+    /** uidex() calls inside this describe whose ids could not be resolved */
+    dynamicCalls?: DynamicFlowCallFact[];
 }
 interface ExtractedFile {
     file: ScannedFile;
     annotations: Annotation[];
     metadata?: MetadataExport[];
     diagnostics?: Diagnostic[];
+    flows?: FlowFact[];
+    dynamicAttrs?: DynamicAttrFact[];
+    unannotatedInteractive?: InteractiveElementFact[];
+    landmarks?: LandmarkFact[];
+    imports?: ImportFact[];
 }
 interface DetectedRoute {
     id: string;
@@ -181,6 +340,30 @@ interface DetectedRoute {
     file: string;
 }
 type DiagnosticSeverity = "error" | "warning" | "info";
+/** A single text replacement; offsets index the file's content at scan time. */
+interface FixEdit {
+    /** absolute path of the file to edit */
+    path: string;
+    start: number;
+    end: number;
+    replacement: string;
+}
+/**
+ * A machine-applicable fix attached to a diagnostic. Applied by
+ * `uidex scan --fix`; edits are computed against the exact content the
+ * scanner read, so they must be applied before any other modification.
+ */
+interface DiagnosticFix {
+    description: string;
+    edits?: FixEdit[];
+    /** files to create (absolute path → content); skipped if the file exists */
+    createFiles?: Array<{
+        path: string;
+        content: string;
+    }>;
+    /** absolute paths of files to delete */
+    deleteFiles?: string[];
+}
 interface Diagnostic {
     code: string;
     severity: DiagnosticSeverity;
@@ -192,6 +375,7 @@ interface Diagnostic {
         id: string;
     };
     hint?: string;
+    fix?: DiagnosticFix;
 }
 interface AuditSummary {
     diagnostics: Diagnostic[];
@@ -231,11 +415,36 @@ declare function walk(sources: SourceConfig[], options: WalkOptions): ScannedFil
 
 declare function extract(files: ScannedFile[]): ExtractedFile[];
 
+/**
+ * Shared parse layer for the scanner. Each file is parsed exactly once in
+ * the extract phase; the resulting AST never leaves it (ExtractedFile must
+ * stay JSON-serializable for the bundler-plugin watchers).
+ *
+ * oxc spans are UTF-16 code-unit offsets, i.e. they index directly into the
+ * JS source string (verified against oxc-parser@0.135.0).
+ */
+interface ParsedComment {
+    type: "Line" | "Block";
+    value: string;
+    start: number;
+    end: number;
+}
+interface ParsedSource {
+    /** null when parsing failed catastrophically — callers degrade to empty facts */
+    program: Program | null;
+    /** true when oxc reported recoverable errors (program is still usable) */
+    hasErrors: boolean;
+    /** all comments in source order; empty when parsing failed */
+    comments: ParsedComment[];
+    /** offset → 1-based line */
+    lineAt(offset: number): number;
+}
+
 interface UidexExportExtractResult {
     exports: MetadataExport[];
     diagnostics: Diagnostic[];
 }
-declare function extractUidexExports(file: ScannedFile): UidexExportExtractResult;
+declare function extractUidexExports(file: ScannedFile, parsed?: ParsedSource): UidexExportExtractResult;
 
 interface ResolveContext {
     config: UidexConfig;
@@ -254,20 +463,115 @@ interface ResolveOutput {
  */
 declare function resolve(ctx: ResolveContext): ResolveOutput;
 
+/**
+ * State-capture completeness — the deterministic replacement for a bespoke
+ * `check-states.mjs`. Cross-checks the states DECLARED on registry entities
+ * (`export const uidex = { states: [...] }`) against the states a capture run
+ * actually produced (a `uidex-states.json` manifest written by the Playwright
+ * states reporter):
+ *
+ *   - `missing-state-capture` — a declared state no run captured. The gap the
+ *     acceptance-grounded analysis surfaces (a promised behavior with no pixel
+ *     evidence) becomes a mechanical audit failure.
+ *   - `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.
+ */
+/** One `entity/state` a capture run recorded. */
+interface CapturedState {
+    /** Registry entity id the capture rendered (e.g. "products"). */
+    entity: string;
+    /** Entity kind, when the capture recorded it (page/feature/widget). */
+    kind?: MetaEntityKind;
+    /** The declared state name captured (e.g. "new-filled"). */
+    state: string;
+    /** Canonical matrix kind (loading/empty/populated/error/variant). */
+    stateKind?: string;
+    /** URL pathname the capture ran against (page-coverage gate matches it to a route). */
+    url?: string;
+    /** Explicit route pattern the capture covers, when supplied. */
+    route?: string;
+}
+interface CapturedStatesManifest {
+    captured: CapturedState[];
+}
+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[]>;
+}
+/**
+ * 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;
+
 interface AuditOptions {
     registry: Registry;
     extracted: ExtractedFile[];
     files: ScannedFile[];
+    /** Extract output for flow spec files; enables per-call reference checks. */
+    flowExtracted?: ExtractedFile[];
     config: UidexConfig;
     check?: boolean;
     lint?: boolean;
     resolveDiagnostics?: Diagnostic[];
-    /** Freshly-emitted gen-file bytes, required for --check. */
+    /** Freshly-emitted DATA-file bytes (the entity array), required for --check. */
     generated?: string;
-    /** On-disk contents of the gen file at scan time; `null` if the file does not exist. */
+    /** On-disk contents of the data file at scan time; `null` if it does not exist. */
     existingOnDisk?: string | null;
-    /** Relative path of the configured `output` file; used in diagnostics. */
+    /** Relative path of the data file; used in diagnostics. */
     outputPath?: string;
+    /** Freshly-emitted TYPES-file bytes; enables the types-file --check compare. */
+    typesGenerated?: string;
+    /** On-disk contents of the types file at scan time; `null` if it does not exist. */
+    typesOnDisk?: string | null;
+    /** Relative path of the configured `output` (types) file; used in diagnostics. */
+    typesOutputPath?: string;
+    /** Freshly-emitted LOCS-file bytes; enables the locs-file --check compare. */
+    locsGenerated?: string;
+    /** On-disk contents of the locs file at scan time; `null` if it does not exist. */
+    locsOnDisk?: string | null;
+    /** Relative path of the `.locs` file; used in diagnostics. */
+    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;
 }
 declare function audit(opts: AuditOptions): AuditSummary;
 
@@ -276,10 +580,32 @@ interface EmitOptions {
     gitContext?: GitContext;
     /** The import source for `createUidex` in the generated preconfigured export. */
     uidexImport?: string;
-    /** Controls id-union emission: "strict" emits literal unions, "loose" emits `string`. */
-    typeMode?: TypeMode;
 }
-declare function emit(opts: EmitOptions): string;
+/**
+ * The scanner emits THREE artifacts, split by consumer:
+ *
+ * - `types` — the id unions + the `Uidex` authoring-shape namespace. Pure types,
+ *   no runtime, no `@ts-nocheck`. This is the file the ~dozens of
+ *   `import type { Uidex } from "@/uidex.gen"` sites resolve, so it must stay
+ *   small: an `import type` still forces tsc/tsserver to fully parse the target
+ *   module, so keeping the runtime entity data out of it is what keeps the editor
+ *   and type-checker responsive across every consumer file.
+ * - `data` — the AUTHORED registry (route/page/feature/widget/primitive/flow) +
+ *   `gitContext` + `loadRegistry` + the preconfigured `uidex` instance. Runtime,
+ *   `@ts-nocheck`. Loaded eagerly by the devtools on mount.
+ * - `locs` — the thin element/region `{ id, loc }` entities, emitted as positional
+ *   tuples (see `emitLocsModule`). Loaded lazily by the devtools (idle / first
+ *   inspect) via `loadLocs`, so ~90% of the entity count stays out of the initial
+ *   devtools chunk.
+ */
+interface EmitResult {
+    types: string;
+    /** Authored-metadata registry (pages/features/widgets/flows/…). */
+    data: string;
+    /** Deferred `id → loc` module for the thin element/region entities. */
+    locs: string;
+}
+declare function emit(opts: EmitOptions): EmitResult;
 
 /**
  * Detect framework-aware routes:
@@ -297,6 +623,15 @@ interface GitResolveOptions {
 }
 declare function resolveGitContext(opts?: GitResolveOptions): GitContext;
 
+type ScaffoldKind = "widget" | "page" | "feature";
+interface ScaffoldSpecOptions {
+    registry: Registry;
+    kind: ScaffoldKind;
+    id: string;
+    outDir: string;
+    force?: boolean;
+    fixtureImport?: string;
+}
 interface ScaffoldOptions {
     registry: Registry;
     widgetId: string;
@@ -311,12 +646,33 @@ interface ScaffoldResult {
     reason?: string;
 }
 declare function scaffoldWidgetSpec(opts: ScaffoldOptions): ScaffoldResult;
+/**
+ * Emits a tagged Playwright stub from an entity's declared acceptance
+ * criteria — one `test()` per criterion. Widgets keep the historical
+ * `widget-<id>.spec.ts` name; pages and features emit `flow-<id>.spec.ts`
+ * per the one-tagged-describe-per-flow-spec convention.
+ */
+declare function scaffoldSpec(opts: ScaffoldSpecOptions): ScaffoldResult;
 
 interface RunScanOptions {
     cwd?: string;
     check?: boolean;
     lint?: boolean;
     configs?: DiscoveredConfig[];
+    /** Captured-states manifest for the completeness gate; overrides on-disk load. */
+    capturedStates?: CapturedStatesManifest;
+    /** Page-coverage baseline; overrides on-disk load. */
+    pageBaseline?: PageCoverageBaseline;
+}
+/** Load the page-coverage baseline from disk, if present + well-formed. */
+declare function loadPageBaseline(configDir: string, config: UidexConfig): PageCoverageBaseline | undefined;
+/** One generated artifact: its bytes plus where it lands (abs + repo-relative). */
+interface ScanArtifact {
+    generated: string;
+    /** Absolute path on disk. */
+    outputPath: string;
+    /** Path relative to the config dir, for diagnostics. */
+    outputRel: string;
 }
 interface ScanResult {
     config: UidexConfig;
@@ -324,11 +680,103 @@ interface ScanResult {
     registry: Registry;
     gitContext: GitContext;
     audit?: AuditSummary;
-    generated: string;
-    outputPath: string;
+    /** Pure-types artifact (`config.output`, e.g. `uidex.gen.ts`). */
+    types: ScanArtifact;
+    /** Authored-registry artifact (the sibling `.data` module). */
+    data: ScanArtifact;
+    /** Deferred element/region source-location artifact (the sibling `.locs` module). */
+    locs: ScanArtifact;
+    /** The captured-states manifest in effect this run, if any (for --update-baseline). */
+    capturedStates?: CapturedStatesManifest;
 }
 declare function runScan(opts?: RunScanOptions): ScanResult[];
-declare function writeScanResult(result: ScanResult): void;
+/**
+ * Write all three generated artifacts (types + data + locs), each only if
+ * changed. Splitting them means a change confined to one (e.g. adding an element
+ * only touches `.locs`) never rewrites the others, so watchers recompile only what
+ * 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;
+
+/**
+ * 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:
+ *
+ *   - 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).
+ *
+ * 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.
+ */
+/** route → core kinds acknowledged as not-yet-captured (the finer ratchet). */
+interface StateMatrixBaseline {
+    missingKinds: Record<string, 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.
+ */
+declare function computeMissingKinds(registry: Registry, manifest: CapturedStatesManifest): Record<string, string[]>;
+
+/**
+ * Applies the machine-generated fixes attached to diagnostics.
+ *
+ * Edits are offset-based against the content the scanner read, so this must
+ * run before anything else touches the files. Within a file, edits apply
+ * last-to-first; an edit overlapping one already applied is skipped. Identical
+ * edits are deduped — two fixes in one file emitting the same edit collapse to
+ * one application.
+ */
+interface AppliedFix {
+    code: string;
+    description: string;
+    file?: string;
+}
+interface ApplyFixesResult {
+    applied: AppliedFix[];
+    /** fixes skipped because of overlapping edits or existing target files */
+    skipped: Array<AppliedFix & {
+        reason: string;
+    }>;
+}
+declare function applyFixes(diagnostics: Diagnostic[]): ApplyFixesResult;
+
+/**
+ * Cross-file id rename. The registry knows every reference surface for an
+ * id — the DOM attribute, `uidex("…")` calls in flow specs, the widget
+ * export's discriminator, and `widgets:` arrays — so the rename rewrites all
+ * of them in one pass and regenerates the gen file. Occurrences the scanner
+ * can't edit mechanically (const indirection, ternaries, patterns) are
+ * reported for manual follow-up instead of being guessed at.
+ */
+type RenameKind = "element" | "widget" | "region";
+interface RenameOptions {
+    cwd: string;
+    kind: RenameKind;
+    oldId: string;
+    newId: string;
+    /** allow renaming onto an id that already exists */
+    force?: boolean;
+}
+interface RenameResult {
+    /** number of source edits applied */
+    edits: number;
+    /** occurrences that need a human (no static literal to rewrite) */
+    manual: Array<{
+        file: string;
+        line: number;
+        reason: string;
+    }>;
+    errors: string[];
+}
+declare function renameEntity(opts: RenameOptions): RenameResult;
 
 interface CliResult {
     exitCode: number;
@@ -341,7 +789,6 @@ interface CliOptions {
 }
 declare function run(opts: CliOptions): Promise<CliResult>;
 
-declare const DEFAULT_TYPE_MODE: TypeMode;
 declare class ConfigError extends Error {
     constructor(message: string);
 }
@@ -366,12 +813,26 @@ declare const DEFAULT_CONVENTIONS: Required<Pick<NonNullable<UidexConfig["conven
  * bootstrapping before the first scan).
  */
 declare namespace Uidex {
+    type CoreStateKind = "loading" | "empty" | "populated" | "error";
+    type StateKind = CoreStateKind | "variant";
+    /** A declared render state, as authored in `states: [{ name, ... }]`. */
+    interface State {
+        name: string;
+        kind?: StateKind;
+        acceptance?: readonly string[];
+        description?: string;
+    }
+    /** Per-core-kind waivers: a kind this route cannot render → reason. */
+    type Waivers = Partial<Record<CoreStateKind, string>>;
     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[];
+        states?: readonly (string | State)[];
+        capture?: boolean;
+        waivers?: Waivers;
         description?: string;
     }
     interface Feature<FeatureIds extends string = string> {
@@ -379,6 +840,7 @@ declare namespace Uidex {
         name?: string;
         features?: readonly FeatureIds[];
         acceptance?: readonly string[];
+        states?: readonly (string | State)[];
         description?: string;
     }
     interface Primitive<PrimitiveIds extends string = string> {
@@ -390,6 +852,7 @@ declare namespace Uidex {
         widget: WidgetIds;
         name?: string;
         acceptance?: readonly string[];
+        states?: readonly (string | State)[];
         description?: string;
     }
     interface Flow<FlowIds extends string = string> {
@@ -402,4 +865,4 @@ declare namespace Uidex {
     }
 }
 
-export { type Annotation, type AnnotationKind, type AuditConfig, type AuditSummary, CONFIG_FILENAME, type CliOptions, type CliResult, ConfigError, type ConventionsConfig, DEFAULT_CONVENTIONS, DEFAULT_TYPE_MODE, type DetectedRoute, type Diagnostic, type DiagnosticSeverity, type DiscoveredConfig, type ExtractedFile, type GitContext, type MetadataExport, type MetadataExportKind, type RunScanOptions, type ScaffoldOptions, type ScaffoldResult, type ScanResult, type ScannedFile, type SourceConfig, type TypeMode, Uidex, type UidexConfig, audit, detectRoutes, discover, emit, extract, extractUidexExports, globToRegExp, parseConfig, pathToId, resolve, resolveGitContext, run as runCli, runScan, scaffoldWidgetSpec, validateConfig, walk, writeScanResult };
+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 };