uidex 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -1,6 +1,4 @@
 import { StoreApi } from 'zustand/vanilla';
-import { ReportPayload, ReportResult, IngestConfig, ReportListResponse, PinRecord, ArchiveReason } from '@uidex/api-client';
-export { ArchiveReason, IngestConfig, PinRecord, ReportListRecord, ReportListResponse, ReportPayload, ReportResult } from '@uidex/api-client';
 import { TemplateResult } from 'lit-html';
 import { IconNode } from 'lucide';
 
@@ -16,6 +14,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 +49,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;
@@ -127,130 +166,6 @@ declare const KIND_STYLE: Record<EntityKind, KindStyleEntry>;
 declare function prettify(id: string): string;
 declare function displayName(entity: Entity, node?: Element | null): string;
 
-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;
-}
-declare function createConsoleCapture(options?: ConsoleCaptureOptions): ConsoleCapture;
-
-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;
-}
-declare function createNetworkCapture(options?: NetworkCaptureOptions): NetworkCapture;
-
-declare const nativeFetch: typeof fetch | undefined;
-
-interface UserIdentity {
-    id: string;
-    name?: string;
-    avatar?: string;
-}
-
-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;
-    /** Optional so pre-existing channel stubs keep satisfying the interface. */
-    onPinArchived?(cb: (reportId: string) => 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[]>;
-        /**
-         * Pin records travel without their screenshot (kept out of `pins.list`
-         * so multi-MB frames don't stall the shared socket); the report detail
-         * view fetches it lazily through here. Optional for host-provided
-         * adapters that inline screenshots on the record instead.
-         */
-        screenshot?(reportId: string): Promise<string | null>;
-        close(reportId: string, reason?: ArchiveReason): Promise<void>;
-    };
-    /** Closes the adapter's shared socket. Any later RPC call revives it. */
-    dispose?(): 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 CreateIngestOptions = IngestOptions;
-declare function createIngest(options?: CreateIngestOptions): Ingest;
-declare function resolveIngestOptions(explicit: IngestOptions | null | undefined, hasCloud: boolean): IngestOptions | null;
-
 type ThemePreference = "light" | "dark" | "auto";
 type ResolvedTheme = "light" | "dark";
 interface ViewStackEntry {
@@ -265,11 +180,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;
 
@@ -430,53 +340,17 @@ interface Inspector {
 declare function resolveEntityElement(ref: EntityRef): HTMLElement | null;
 declare function createInspector(options: InspectorOptions): Inspector;
 
-type PinMatchMode = "route" | "pathname" | "component";
-interface PinLayer {
-    setPins(pins: readonly PinRecord[]): void;
-    addPin(pin: PinRecord): void;
-    removePin(reportId: string): void;
-    clear(): void;
-    getPinsForElement(componentId: string): readonly PinRecord[];
-    getAllPins(): readonly PinRecord[];
-    attachChannel(channel: RealtimeChannel): () => void;
-    attachCloud(opts: AttachCloudOpts): () => void;
-    refresh(): Promise<void>;
-    onFilterChange(cb: () => void): () => void;
-    readonly visible: boolean;
-    setVisible(visible: boolean): void;
-    destroy(): void;
-}
-interface AttachCloudOpts {
-    cloud: Pick<CloudAdapter, "pins">;
-    channel?: RealtimeChannel | null;
-    getRoute: () => string;
-    getPathname: () => string;
-    getVisibleEntities: () => string[];
-    getMatchMode: () => PinMatchMode;
-    onError?: (err: unknown) => void;
-}
-interface PinLayerOptions {
-    container: Element | ShadowRoot;
-    onOpenPinDetail?: (componentId: string, reportId: string) => void;
-    onHoverPin?: (anchor: HTMLElement | null, componentId: string | null) => void;
-    onPinsChanged?: () => void;
-}
-declare function createPinLayer(options: PinLayerOptions): PinLayer;
-
 type Corner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
 interface MenuBarOptions {
     container: Element;
     session: SessionStore;
     initialCorner?: Corner;
     appTitle?: string;
-    channel?: RealtimeChannel | null;
-    pinLayer?: PinLayer | null;
 }
 interface MenuBar {
     destroy(): void;
     snapTo(corner: Corner): void;
     snapToNearest(x: number, y: number): void;
-    setPinLayer(layer: PinLayer): void;
     readonly corner: Corner;
     readonly root: HTMLElement;
 }
@@ -521,8 +395,6 @@ interface CreateSurfaceShellOptions {
     stylesheets?: string[];
     initialCorner?: Corner;
     appTitle?: string;
-    channel?: RealtimeChannel | null;
-    pinLayer?: PinLayer | null;
     /**
      * Additional inspector wiring. Hover is pre-wired to overlay + tooltip; pass
      * `onSelect` (and `onAfterHover`) to extend behaviour without rebuilding the
@@ -575,7 +447,7 @@ interface CreateRouterOptions {
 }
 declare function createRouter(options: CreateRouterOptions): Router;
 
-type ViewSurface = ListSurface | DetailSurface | FormSurface;
+type ViewSurface = ListSurface | DetailSurface;
 interface ListSurface {
     kind: "list";
     id: string;
@@ -720,102 +592,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;
@@ -839,13 +615,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;
@@ -861,11 +630,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;
@@ -939,12 +703,10 @@ interface PaletteShortcut {
     shift?: boolean;
 }
 declare function formatShortcutLabel(shortcut: PaletteShortcut): string;
-type EscapeHandler = () => boolean;
 
 declare const SURFACE_HOST_CLASS = "uidex-surface-host";
 declare const Z_BASE = 2147483630;
 declare const Z_OVERLAY = 2147483635;
-declare const Z_PIN_LAYER = 2147483640;
 declare const Z_CHROME = 2147483645;
 declare const SURFACE_IGNORE_SELECTOR = ".uidex-surface-host";
 
@@ -953,13 +715,9 @@ interface ViewStackOptions {
     views: Router;
     session: SessionStore;
     registry: Registry;
-    cloud?: CloudAdapter | null;
     highlight: HighlightController;
     shortcut?: PaletteShortcut;
     dev?: boolean;
-    pushEscapeLayer?: ViewContext["pushEscapeLayer"];
-    onAfterSubmit?: () => void;
-    getRoute?: () => string;
 }
 interface ViewStack {
     /**
@@ -981,12 +739,8 @@ declare const widgetDetailView: View;
 declare const primitiveDetailView: View;
 declare const pageDetailView: View;
 
-declare const reportView: View;
-
 declare const flowDetailView: View;
 
-declare const pinSettingsView: View;
-
 declare function buildDefaultViews(shortcut?: PaletteShortcut): View[];
 
 interface CreateUidexOptions {
@@ -996,38 +750,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;
@@ -1035,10 +764,8 @@ interface Uidex {
     readonly registry: Registry;
     readonly session: SessionStore;
     readonly views: Router;
-    readonly cloud: CloudAdapter | null;
-    readonly ingest: Ingest | null;
     readonly shadowRoot: ShadowRoot | null;
 }
 declare function createUidex(options?: CreateUidexOptions): Uidex;
 
-export { type AttachCloudOpts, type Cleanup, type CloudAdapter, type ConsoleCapture, type ConsoleEntry, type ConsoleLevel, type Corner, type CreateRouterOptions, type CreateSessionOptions, type CreateSurfaceShellOptions, type CreateUidexOptions, type CursorTooltip, type CursorTooltipDeps, type DetailAction, type DetailActionIcon, type DetailActionRunContext, type DetailSection, type DetailSubtitle, type DetailSurface, ENTITY_KINDS, type Element$1 as Element, type Entity, type EntityByKind, type EntityKind, type EntityRef, type Feature, type Flow, type FormField, type FormSubmit, type FormSubmitResult, type FormSurface, type FormValue, type HighlightActions, type HighlightController, type Ingest, type IngestOptions, type Inspector, type InspectorMatch, type InspectorMatchStack, type InspectorOptions, KIND_STYLE, type KindStyleEntry, type ListItem, type ListSurface, type Location, type MenuBar, type MenuBarOptions, type MetaEntityKind, type Metadata, type ModeBindings, type ModeSnapshot, type ModeStore, type ModeTransitions, type NavigationActions, type NavigationState, type NavigationStore, type NetworkCapture, type NetworkEntry, type Overlay, type OverlayShowOptions, type Page, type PaletteShortcut, type PinLayer, type PinLayerOptions, type PinMatchMode, type Primitive, type RealtimeChannel, type RealtimeChannelState, type RealtimePresenceUser, type Region, type Registry, type ReportRecord, type ResolvedTheme, type Route, type RouteMatch, type Router, SURFACE_HOST_CLASS, SURFACE_IGNORE_SELECTOR, type Scope, type SessionSnapshot, type SessionState, type SessionStore, type ShellAction, type ShellHint, type SurfaceHost, type SurfaceHostOptions, type SurfaceMode, type SurfaceShell, type ThemeDetector, type ThemeDetectorDeps, type ThemePreference, type Uidex, UnknownEntityKindError, type UserIdentity, type View, type ViewContext, type ViewPalette, type ViewPushTarget, type ViewStack, type ViewStackEntry, type ViewStackOptions, type ViewSurface, ViewValidationError, type Widget, Z_BASE, Z_CHROME, Z_OVERLAY, Z_PIN_LAYER, assertEntityKind, buildDefaultViews, componentDetailView, createCommandPaletteView, createConsoleCapture, createCursorTooltip, createIngest, createInspector, createMenuBar, createModeStore, createNavigationStore, createNetworkCapture, createOverlay, createPinLayer, createRegistry, createRouter, createSession, createSurfaceHost, createSurfaceShell, createThemeDetector, createUidex, createViewStack, displayName, entityKey, featureDetailView, flowDetailView, formatShortcutLabel, isMetaKind, nativeFetch, pageDetailView, pinSettingsView, prettify, primitiveDetailView, regionDetailView, reportView, resolveEntityElement, resolveIngestOptions, resolveTheme, widgetDetailView };
+export { type Cleanup, type Corner, type CreateRouterOptions, type CreateSessionOptions, type CreateSurfaceShellOptions, type CreateUidexOptions, type CursorTooltip, type CursorTooltipDeps, type DetailAction, type DetailActionIcon, type DetailActionRunContext, type DetailSection, type DetailSubtitle, type DetailSurface, ENTITY_KINDS, type Element$1 as Element, type Entity, type EntityByKind, type EntityKind, type EntityRef, type Feature, type Flow, type HighlightActions, type HighlightController, type Inspector, type InspectorMatch, type InspectorMatchStack, type InspectorOptions, KIND_STYLE, type KindStyleEntry, type ListItem, type ListSurface, type Location, type MenuBar, type MenuBarOptions, type MetaEntityKind, type Metadata, type ModeBindings, type ModeSnapshot, type ModeStore, type ModeTransitions, type NavigationActions, type NavigationState, type NavigationStore, type Overlay, type OverlayShowOptions, type Page, type PaletteShortcut, type Primitive, type Region, type Registry, type ReportRecord, type ResolvedTheme, type Route, type RouteMatch, type Router, SURFACE_HOST_CLASS, SURFACE_IGNORE_SELECTOR, type Scope, type SessionSnapshot, type SessionState, type SessionStore, type ShellAction, type ShellHint, type SurfaceHost, type SurfaceHostOptions, type SurfaceMode, type SurfaceShell, type ThemeDetector, type ThemeDetectorDeps, type ThemePreference, type Uidex, UnknownEntityKindError, type View, type ViewContext, type ViewPalette, type ViewPushTarget, type ViewStack, type ViewStackEntry, type ViewStackOptions, type ViewSurface, ViewValidationError, type Widget, Z_BASE, Z_CHROME, Z_OVERLAY, assertEntityKind, buildDefaultViews, componentDetailView, createCommandPaletteView, createCursorTooltip, createInspector, createMenuBar, createModeStore, createNavigationStore, createOverlay, createRegistry, createRouter, createSession, createSurfaceHost, createSurfaceShell, createThemeDetector, createUidex, createViewStack, displayName, entityKey, featureDetailView, flowDetailView, formatShortcutLabel, isMetaKind, pageDetailView, prettify, primitiveDetailView, regionDetailView, resolveEntityElement, resolveTheme, widgetDetailView };