uidex 0.9.0 → 0.11.0

package/dist/index.d.cts

@@ -17,8 +17,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];
@@ -36,34 +36,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`.
+     * 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.
      */
-    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>>;
+    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;
@@ -80,12 +106,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";

package/dist/index.d.ts

@@ -17,8 +17,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];
@@ -36,34 +36,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`.
+     * 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.
      */
-    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>>;
+    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;
@@ -80,12 +106,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";

package/dist/index.js

@@ -1018,6 +1018,9 @@ var tailwind_built_default = `/*! tailwindcss v4.2.2 | MIT License | https://tai
   .flex-1 {
     flex: 1;
   }
+  .shrink {
+    flex-shrink: 1;
+  }
   .shrink-0 {
     flex-shrink: 0;
   }
@@ -7326,7 +7329,10 @@ function createEntityDetailView(config) {
         sections.push({ id: "description", text: meta.description });
       }
       if (offerAcceptance && meta?.acceptance?.length) {
-        sections.push({ id: "acceptance", items: meta.acceptance });
+        sections.push({
+          id: "acceptance",
+          items: meta.acceptance.map((c) => c.text)
+        });
       }
       if (entity) {
         for (const s of config.extraSections?.(ctx, entity) ?? []) {