uidex 0.6.0 → 0.8.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;
@@ -98,16 +139,10 @@ 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;
 }
 
-interface UserIdentity {
-    id: string;
-    name?: string;
-    avatar?: string;
-}
-
 type ThemePreference = "light" | "dark" | "auto";
 type ResolvedTheme = "light" | "dark";
 interface ViewStackEntry {
@@ -115,20 +150,13 @@ interface ViewStackEntry {
     ref: EntityRef | null;
 }
 interface SessionSnapshot {
-    hover: EntityRef | null;
-    selection: EntityRef | null;
     stack: ViewStackEntry[];
     /** Sticky overlay highlight. Set by "Highlight Element" actions; cleared on Esc. */
     pinnedHighlight: EntityRef | null;
-    inspectorActive: boolean;
+    /** Mirrored from the mode store; the surface mode the session is currently in. */
+    mode: SurfaceMode;
     theme: ThemePreference;
     resolvedTheme: ResolvedTheme;
-    ingestActive: boolean;
-    /**
-     * 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;
 
@@ -138,7 +166,6 @@ interface NavigationState {
 interface NavigationActions {
     push(entry: ViewStackEntry): void;
     pop(): void;
-    replace(entry: ViewStackEntry): void;
     clear(): void;
     reset(stack: ViewStackEntry[]): void;
 }
@@ -149,7 +176,6 @@ type NavigationStore = StoreApi<NavigationState> & {
 type SurfaceMode = "idle" | "inspecting" | "palette" | "viewing";
 interface ModeSnapshot {
     mode: SurfaceMode;
-    inspectorActive: boolean;
 }
 interface ModeTransitions {
     openPalette(): void;
@@ -175,11 +201,11 @@ type SessionStore = StoreApi<SessionState> & {
     readonly nav: NavigationStore;
     readonly mode: ModeStore;
     readonly highlight: HighlightActions;
-    select(ref: EntityRef | null): void;
     setTheme(theme: ThemePreference, resolved?: ResolvedTheme): void;
-    setIngest(active: boolean): void;
 };
 
+type Corner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+
 interface OverlayShowOptions {
     label?: string;
     color?: string;
@@ -190,8 +216,6 @@ interface OverlayShowOptions {
     backdrop?: boolean;
 }
 
-type Corner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
-
 interface CreateHeadlessOptions {
     theme?: ThemePreference;
     resolvedTheme?: ResolvedTheme;

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;
@@ -98,16 +139,10 @@ 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;
 }
 
-interface UserIdentity {
-    id: string;
-    name?: string;
-    avatar?: string;
-}
-
 type ThemePreference = "light" | "dark" | "auto";
 type ResolvedTheme = "light" | "dark";
 interface ViewStackEntry {
@@ -115,20 +150,13 @@ interface ViewStackEntry {
     ref: EntityRef | null;
 }
 interface SessionSnapshot {
-    hover: EntityRef | null;
-    selection: EntityRef | null;
     stack: ViewStackEntry[];
     /** Sticky overlay highlight. Set by "Highlight Element" actions; cleared on Esc. */
     pinnedHighlight: EntityRef | null;
-    inspectorActive: boolean;
+    /** Mirrored from the mode store; the surface mode the session is currently in. */
+    mode: SurfaceMode;
     theme: ThemePreference;
     resolvedTheme: ResolvedTheme;
-    ingestActive: boolean;
-    /**
-     * 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;
 
@@ -138,7 +166,6 @@ interface NavigationState {
 interface NavigationActions {
     push(entry: ViewStackEntry): void;
     pop(): void;
-    replace(entry: ViewStackEntry): void;
     clear(): void;
     reset(stack: ViewStackEntry[]): void;
 }
@@ -149,7 +176,6 @@ type NavigationStore = StoreApi<NavigationState> & {
 type SurfaceMode = "idle" | "inspecting" | "palette" | "viewing";
 interface ModeSnapshot {
     mode: SurfaceMode;
-    inspectorActive: boolean;
 }
 interface ModeTransitions {
     openPalette(): void;
@@ -175,11 +201,11 @@ type SessionStore = StoreApi<SessionState> & {
     readonly nav: NavigationStore;
     readonly mode: ModeStore;
     readonly highlight: HighlightActions;
-    select(ref: EntityRef | null): void;
     setTheme(theme: ThemePreference, resolved?: ResolvedTheme): void;
-    setIngest(active: boolean): void;
 };
 
+type Corner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+
 interface OverlayShowOptions {
     label?: string;
     color?: string;
@@ -190,8 +216,6 @@ interface OverlayShowOptions {
     backdrop?: boolean;
 }
 
-type Corner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
-
 interface CreateHeadlessOptions {
     theme?: ThemePreference;
     resolvedTheme?: ResolvedTheme;