uidex 0.10.0 → 0.11.0

package/dist/headless/index.d.cts

@@ -34,19 +34,39 @@ 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[];
     /**
@@ -84,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";

package/dist/headless/index.d.ts

@@ -34,19 +34,39 @@ 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[];
     /**
@@ -84,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";