uidex 0.6.0 → 0.8.0

package/dist/react/index.d.cts

@@ -1,7 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, ComponentType, ReactElement } from 'react';
 import { StoreApi } from 'zustand/vanilla';
-import { ReportPayload, ReportResult, IngestConfig, ReportListResponse, PinRecord, ArchiveReason } from '@uidex/api-client';
 import { TemplateResult } from 'lit-html';
 
 declare const ENTITY_KINDS: readonly ["route", "page", "feature", "widget", "region", "element", "primitive", "flow"];
@@ -16,6 +15,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;
@@ -25,6 +50,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,16 +142,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 {
@@ -119,20 +153,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;
 
@@ -142,7 +169,6 @@ interface NavigationState {
 interface NavigationActions {
     push(entry: ViewStackEntry): void;
     pop(): void;
-    replace(entry: ViewStackEntry): void;
     clear(): void;
     reset(stack: ViewStackEntry[]): void;
 }
@@ -153,7 +179,6 @@ type NavigationStore = StoreApi<NavigationState> & {
 type SurfaceMode = "idle" | "inspecting" | "palette" | "viewing";
 interface ModeSnapshot {
     mode: SurfaceMode;
-    inspectorActive: boolean;
 }
 interface ModeTransitions {
     openPalette(): void;
@@ -179,110 +204,10 @@ 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 ConsoleLevel = "warn" | "error";
-interface ConsoleEntry {
-    level: ConsoleLevel;
-    message: string;
-    timestamp: string;
-}
-interface ConsoleCaptureOptions {
-    limit?: number;
-    target?: Console;
-    now?: () => Date;
-}
-interface ConsoleCapture {
-    start(): void;
-    stop(): void;
-    readonly isActive: boolean;
-    entries(): readonly ConsoleEntry[];
-    clear(): void;
-}
-
-interface NetworkEntry {
-    method: string;
-    url: string;
-    status: number;
-    timestamp: string;
-    error?: string;
-}
-interface NetworkCaptureOptions {
-    limit?: number;
-    target?: {
-        fetch?: typeof fetch;
-    };
-    now?: () => Date;
-}
-interface NetworkCapture {
-    start(): void;
-    stop(): void;
-    readonly isActive: boolean;
-    entries(): readonly NetworkEntry[];
-    clear(): void;
-}
-
-type RealtimePresenceUser = {
-    userId: string;
-    name: string;
-    avatar: string | null;
 };
-type RealtimeChannelState = "connecting" | "connected" | "disconnected";
-interface RealtimeConnectOpts {
-    user: UserIdentity;
-    route: string;
-}
-interface RealtimeChannel {
-    readonly state: RealtimeChannelState;
-    connect(): void;
-    disconnect(): void;
-    joinRoute(route: string): void;
-    onPresence(cb: (users: RealtimePresenceUser[]) => void): () => void;
-    onPin(cb: (pin: PinRecord) => void): () => void;
-}
-interface CloudAdapter<TPayload = ReportPayload, TResult = ReportResult, TIntegrations = {
-    getConfig(): Promise<IngestConfig>;
-    getCachedConfig(): IngestConfig | null;
-}> {
-    readonly reports: {
-        submit(payload: TPayload): Promise<TResult>;
-        list?(opts?: {
-            page?: number;
-            limit?: number;
-        }): Promise<ReportListResponse>;
-    };
-    readonly integrations: TIntegrations;
-    readonly realtime: {
-        connect(opts: RealtimeConnectOpts): RealtimeChannel;
-    };
-    readonly pins: {
-        list(params: {
-            route?: string;
-            entities?: string;
-        }): Promise<PinRecord[]>;
-        archive(reportId: string, reason?: ArchiveReason): Promise<void>;
-    };
-}
 
-interface IngestOptions {
-    captureConsole?: boolean;
-    captureNetwork?: boolean;
-    consoleLimit?: number;
-    networkLimit?: number;
-    consoleTarget?: ConsoleCaptureOptions["target"];
-    networkTarget?: NetworkCaptureOptions["target"];
-    now?: () => Date;
-}
-interface Ingest {
-    start(): void;
-    stop(): void;
-    readonly isActive: boolean;
-    readonly console: ConsoleCapture | null;
-    readonly network: NetworkCapture | null;
-}
+type Corner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
 
 interface OverlayShowOptions {
     label?: string;
@@ -294,8 +219,6 @@ interface OverlayShowOptions {
     backdrop?: boolean;
 }
 
-type Corner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
-
 interface RouteMatch {
     view: View;
     priority: number;
@@ -314,7 +237,7 @@ interface Router {
     isFavorite(ref: EntityRef): boolean;
 }
 
-type ViewSurface = ListSurface | DetailSurface | FormSurface;
+type ViewSurface = ListSurface | DetailSurface;
 interface ListSurface {
     kind: "list";
     id: string;
@@ -441,9 +364,16 @@ type DetailSection = {
     id: "routes";
     paths: readonly string[];
     filterable?: boolean;
-} | {
+}
+/**
+ * `url` renders immediately; `load` fetches lazily (cloud pins travel
+ * without their screenshot) and the section stays hidden until — and
+ * unless — the promise resolves with a data URL.
+ */
+ | {
     id: "screenshot";
-    url: string;
+    url?: string;
+    load?: () => Promise<string | null>;
 } | {
     id: "metadata";
     entries: readonly MetadataEntry[];
@@ -452,102 +382,6 @@ interface MetadataEntry {
     label: string;
     value: string;
 }
-interface FormSurface {
-    kind: "form";
-    id: string;
-    fields: readonly FormField[];
-    submit: FormSubmit;
-    initial?: Record<string, FormValue>;
-    /**
-     * Optional Standard Schema (Zod v4, Valibot, ArkType, etc.) run against the
-     * collected form values before `submit.onSubmit`. On failure, issues are
-     * routed to the matching `<FieldError>` and submission is skipped.
-     */
-    schema?: StandardSchemaV1<Record<string, unknown>>;
-    /**
-     * Promise resolving to a base64 screenshot data URL. When provided, the
-     * form renderer shows a thumbnail preview above the fields.
-     */
-    screenshotPreview?: Promise<string | null>;
-}
-/**
- * Minimal StandardSchemaV1 surface — kept inline so the SDK doesn't need a
- * type-level dep on any specific validator package.
- */
-interface StandardSchemaV1<Input = unknown, Output = Input> {
-    readonly "~standard": {
-        readonly version: 1;
-        readonly vendor: string;
-        readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
-        readonly types?: {
-            readonly input: Input;
-            readonly output: Output;
-        };
-    };
-}
-type StandardSchemaResult<Output> = {
-    readonly value: Output;
-    readonly issues?: undefined;
-} | {
-    readonly issues: ReadonlyArray<StandardSchemaIssue>;
-};
-interface StandardSchemaIssue {
-    readonly message: string;
-    readonly path?: ReadonlyArray<PropertyKey | {
-        readonly key: PropertyKey;
-    }>;
-}
-interface FormSubmit {
-    label: string;
-    onSubmit: (values: Record<string, FormValue>) => FormSubmitResult | void | Promise<FormSubmitResult | void>;
-}
-type FormSubmitResult = {
-    status: "success";
-    message?: string;
-    link?: {
-        url: string;
-        label?: string;
-    };
-    resetFields?: readonly string[];
-} | {
-    status: "error";
-    message: string;
-    /** Per-field error messages keyed by field `name`. */
-    fieldErrors?: Record<string, string>;
-};
-type FormValue = string | boolean;
-interface FormFieldBase {
-    name: string;
-    label: string;
-}
-type FormField = (FormFieldBase & {
-    kind: "select";
-    options: readonly {
-        value: string;
-        label: string;
-    }[];
-    required?: boolean;
-    value?: string;
-}) | (FormFieldBase & {
-    kind: "text";
-    placeholder?: string;
-    required?: boolean;
-    value?: string;
-}) | (FormFieldBase & {
-    kind: "email";
-    placeholder?: string;
-    required?: boolean;
-    value?: string;
-}) | (FormFieldBase & {
-    kind: "textarea";
-    placeholder?: string;
-    required?: boolean;
-    rows?: number;
-    value?: string;
-}) | (FormFieldBase & {
-    kind: "checkbox";
-    value?: boolean;
-});
 
 interface ViewPalette {
     label: string;
@@ -571,13 +405,6 @@ interface HighlightController {
 interface ViewContext {
     ref: EntityRef | null;
     registry: Registry;
-    cloud: CloudAdapter<unknown, unknown, unknown> | null;
-    /**
-     * Local user identity from `createUidex`'s `user` option, or `null` when
-     * unconfigured. Views that auto-populate attribution (e.g. report
-     * `reporterName`) read this here instead of touching the session store.
-     */
-    user: UserIdentity | null;
     views: Router;
     /** Push a view onto the stack. Unregistered ids are a no-op. */
     push: (target: ViewPushTarget) => void;
@@ -593,11 +420,6 @@ interface ViewContext {
     highlight: HighlightController;
     /** Snapshot of the current view stack (top-most last). */
     getStack: () => readonly ViewStackEntry[];
-    pushEscapeLayer(handler: EscapeHandler): Cleanup;
-    /** Called after a report submission succeeds, to refresh pins etc. */
-    onAfterSubmit?: () => void;
-    /** Return the current route pattern. Falls back to `location.pathname`. */
-    getRoute?: () => string;
 }
 interface ShellHint {
     key: string;
@@ -642,8 +464,9 @@ interface View {
      * when the declared target has been removed from the host.
      */
     focusTarget?: (root: HTMLElement, ctx: ViewContext) => HTMLElement | null;
-    surface: (ctx: ViewContext) => ViewSurface;
-    /** Direct render for integration adapters (React, etc.). Mutually exclusive with surface renderers. */
+    /** Required unless `render` is provided. */
+    surface?: (ctx: ViewContext) => ViewSurface;
+    /** Direct render for integration adapters (React, etc.). Takes precedence over `surface` when both are present. */
     render?: (ctx: ViewContext, root: HTMLElement) => Cleanup | void;
     parent?: (ref: EntityRef | null) => ViewStackEntry | null;
 }
@@ -656,7 +479,6 @@ interface PaletteShortcut {
     /** Require Shift. Default: false. */
     shift?: boolean;
 }
-type EscapeHandler = () => boolean;
 
 interface CreateUidexOptions {
     theme?: ThemePreference;
@@ -665,38 +487,13 @@ interface CreateUidexOptions {
     initialCorner?: Corner;
     /** Shown as a label at the start of the menu bar. */
     appTitle?: string;
-    cloud?: CloudAdapter | null;
     dev?: boolean;
     /** Register bundled default views. Defaults to `true`. */
     defaultViews?: boolean;
     /** Additional views to register (after defaults). */
     views?: readonly View[];
-    /**
-     * Override ingest behaviour. When `cloud` is non-null, ingest auto-enables
-     * (both console and network capture). Pass `null` to disable entirely, or
-     * an options object to override either channel.
-     */
-    ingest?: IngestOptions | null;
     /** Keyboard shortcut for the command palette. Defaults to Cmd+K / Ctrl+K. */
     shortcut?: PaletteShortcut;
-    /**
-     * Identity for the local user. Required to opt into realtime collaborative
-     * features (peer cursors, presence). When omitted, realtime stays
-     * disconnected and report attribution falls back to whatever the user
-     * types in the report form.
-     */
-    user?: UserIdentity;
-    /** Git context for pin filtering. Typically mirrors `cloud({ git })`. */
-    git?: {
-        branch?: string;
-        commit?: string;
-    };
-    /**
-     * Return the current route pattern (e.g. `/users/:id`). Used for
-     * route-based pin matching and report attribution. When omitted, the SDK
-     * falls back to `location.pathname`.
-     */
-    getRoute?: () => string;
 }
 interface Uidex {
     mount(target?: Element): void;
@@ -704,24 +501,19 @@ interface Uidex {
     readonly registry: Registry;
     readonly session: SessionStore;
     readonly views: Router;
-    readonly cloud: CloudAdapter | null;
-    readonly ingest: Ingest | null;
     readonly shadowRoot: ShadowRoot | null;
 }
 
 interface UidexProviderProps {
     /**
      * Pre-built uidex instance (e.g. the `uidex` export from `uidex.gen.ts`).
-     * When provided, `projectKey`, `cloud`, `user`, and `config` are ignored.
+     * When provided, `config` is ignored.
      */
     instance?: Uidex;
-    projectKey?: string;
-    cloud?: CloudAdapter | null;
-    user?: UserIdentity;
-    config?: Omit<CreateUidexOptions, "cloud" | "user">;
+    config?: CreateUidexOptions;
     children?: ReactNode;
 }
-declare function UidexProvider({ instance: externalInstance, projectKey, cloud, user, config, children, }: UidexProviderProps): react_jsx_runtime.JSX.Element;
+declare function UidexProvider({ instance: externalInstance, config, children, }: UidexProviderProps): react_jsx_runtime.JSX.Element;
 
 declare class UidexContextError extends Error {
     constructor(hookName: string);
@@ -752,16 +544,24 @@ interface KindChipProps {
 declare function KindChip({ kind, label, withKindName, className, }: KindChipProps): ReactElement;
 
 interface UidexDevtoolsProps {
+    /**
+     * Populates the entity registry (typically `loadRegistry` from `uidex.gen.ts`).
+     * Must be idempotent: it is called once per created instance, and under React
+     * StrictMode the effect runs setup→cleanup→setup, so it may be invoked against
+     * a short-lived instance that is discarded before mount.
+     */
     loadRegistry: (target: Registry) => Registry;
-    projectKey?: string;
-    endpoint?: string;
-    user?: UserIdentity;
-    git?: {
-        branch?: string;
-        commit?: string;
-    };
-    config?: Omit<CreateUidexOptions, "cloud" | "user" | "git">;
+    /**
+     * Optional deferred hydration — populate the registry with data that need not
+     * be present at mount (typically the thin element/region source locations from
+     * `uidex.gen.locs.ts`, dynamic-imported so they land in a separate chunk). Run
+     * on an idle callback after mount, so the initial devtools chunk stays small
+     * and the copy-source-path metadata streams in shortly after. Idempotent, like
+     * `loadRegistry`.
+     */
+    loadDeferred?: (target: Registry) => void | Promise<void>;
+    config?: CreateUidexOptions;
 }
-declare function UidexDevtools({ loadRegistry, projectKey, endpoint, user, git, config, }: UidexDevtoolsProps): react_jsx_runtime.JSX.Element | null;
+declare function UidexDevtools({ loadRegistry, loadDeferred, config, }: UidexDevtoolsProps): react_jsx_runtime.JSX.Element | null;
 
 export { KindChip, type KindChipProps, type ReactViewDef, UidexContextError, UidexDevtools, type UidexDevtoolsProps, UidexMount, type UidexMountProps, UidexProvider, type UidexProviderProps, createReactView, useUidex };