uidex 0.7.0 → 0.9.0

package/dist/headless/index.d.cts

@@ -12,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;
@@ -21,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;
@@ -102,12 +143,6 @@ interface Registry {
     onReportsChange(cb: () => void): () => void;
 }
 
-interface UserIdentity {
-    id: string;
-    name?: string;
-    avatar?: string;
-}
-
 type ThemePreference = "light" | "dark" | "auto";
 type ResolvedTheme = "light" | "dark";
 interface ViewStackEntry {
@@ -122,11 +157,6 @@ interface SessionSnapshot {
     mode: SurfaceMode;
     theme: ThemePreference;
     resolvedTheme: ResolvedTheme;
-    /**
-     * Identity for the local user. Set once at session creation; gates realtime
-     * features (cursor labels, presence) and auto-populates report attribution.
-     */
-    user: UserIdentity | null;
 }
 type SessionState = SessionSnapshot;
 

package/dist/headless/index.d.ts

@@ -12,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;
@@ -21,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;
@@ -102,12 +143,6 @@ interface Registry {
     onReportsChange(cb: () => void): () => void;
 }
 
-interface UserIdentity {
-    id: string;
-    name?: string;
-    avatar?: string;
-}
-
 type ThemePreference = "light" | "dark" | "auto";
 type ResolvedTheme = "light" | "dark";
 interface ViewStackEntry {
@@ -122,11 +157,6 @@ interface SessionSnapshot {
     mode: SurfaceMode;
     theme: ThemePreference;
     resolvedTheme: ResolvedTheme;
-    /**
-     * Identity for the local user. Set once at session creation; gates realtime
-     * features (cursor labels, presence) and auto-populates report attribution.
-     */
-    user: UserIdentity | null;
 }
 type SessionState = SessionSnapshot;