uidex 0.5.2 → 0.7.0

package/dist/index.d.cts

@@ -102,6 +102,7 @@ interface ReportRecord {
 interface Registry {
     add(entity: Entity): void;
     get<K extends EntityKind>(kind: K, id: string): EntityByKind<K> | undefined;
+    matchPattern<K extends EntityKind>(kind: K, id: string): EntityByKind<K> | undefined;
     list<K extends EntityKind>(kind: K): ReadonlyArray<EntityByKind<K>>;
     query(predicate: (entity: Entity) => boolean): Entity[];
     byScope(scope: Scope): Entity[];
@@ -109,7 +110,7 @@ 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;
 }
 declare function createRegistry(): Registry;
@@ -126,110 +127,6 @@ declare const KIND_STYLE: Record<EntityKind, KindStyleEntry>;
 declare function prettify(id: string): string;
 declare function displayName(entity: Entity, node?: Element | null): string;
 
-interface UserIdentity {
-    id: string;
-    name?: string;
-    avatar?: string;
-}
-
-type ThemePreference = "light" | "dark" | "auto";
-type ResolvedTheme = "light" | "dark";
-interface ViewStackEntry {
-    id: string;
-    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;
-    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;
-
-interface NavigationState {
-    stack: ViewStackEntry[];
-}
-interface NavigationActions {
-    push(entry: ViewStackEntry): void;
-    pop(): void;
-    replace(entry: ViewStackEntry): void;
-    clear(): void;
-    reset(stack: ViewStackEntry[]): void;
-}
-type NavigationStore = StoreApi<NavigationState> & {
-    nav: NavigationActions;
-};
-declare function createNavigationStore(): NavigationStore;
-
-type SurfaceMode = "idle" | "inspecting" | "palette" | "viewing";
-interface ModeSnapshot {
-    mode: SurfaceMode;
-    inspectorActive: boolean;
-}
-interface ModeBindings {
-    mountInspector?: () => void;
-    destroyInspector?: () => void;
-}
-interface ModeTransitions {
-    openPalette(): void;
-    openInspector(): void;
-    closeInspector(): void;
-    toggleInspector(): void;
-    enterViewing(initialStack: ViewStackEntry[]): void;
-    dismiss(): void;
-    popOrTransition(): void;
-    pushView(entry: ViewStackEntry): void;
-}
-type ModeStore = StoreApi<ModeSnapshot> & {
-    transition: ModeTransitions;
-};
-interface CreateModeStoreOptions {
-    nav: NavigationStore;
-    bindings?: ModeBindings;
-}
-declare function createModeStore(options: CreateModeStoreOptions): ModeStore;
-
-interface HighlightContext {
-    ref: EntityRef | null;
-    element: HTMLElement | null;
-    pinnedRef: EntityRef | null;
-    color: string | null;
-}
-interface HighlightActions {
-    hover(ref: EntityRef, element?: HTMLElement | null, color?: string | null): void;
-    unhover(): void;
-    pin(ref?: EntityRef): void;
-    unpin(): void;
-}
-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;
-};
-interface CreateSessionOptions extends Partial<SessionSnapshot> {
-    detectTheme?: () => ResolvedTheme;
-    onMountInspector?: () => void;
-    onDestroyInspector?: () => void;
-    onShowOverlay?: (context: HighlightContext) => void;
-    onHideOverlay?: () => void;
-    onUpdateOverlay?: (context: HighlightContext) => void;
-}
-declare function resolveTheme(preference: ThemePreference, detect?: () => ResolvedTheme): ResolvedTheme;
-declare function createSession(options?: CreateSessionOptions): SessionStore;
-
 type ConsoleLevel = "warn" | "error";
 interface ConsoleEntry {
     level: ConsoleLevel;
@@ -274,7 +171,12 @@ interface NetworkCapture {
 declare function createNetworkCapture(options?: NetworkCaptureOptions): NetworkCapture;
 
 declare const nativeFetch: typeof fetch | undefined;
-declare function getNativeFetch(): typeof fetch | undefined;
+
+interface UserIdentity {
+    id: string;
+    name?: string;
+    avatar?: string;
+}
 
 type RealtimePresenceUser = {
     userId: string;
@@ -293,6 +195,8 @@ interface RealtimeChannel {
     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>;
@@ -314,8 +218,17 @@ interface CloudAdapter<TPayload = ReportPayload, TResult = ReportResult, TIntegr
             route?: string;
             entities?: string;
         }): Promise<PinRecord[]>;
-        archive(reportId: string, reason?: ArchiveReason): Promise<void>;
+        /**
+         * 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 {
@@ -334,12 +247,104 @@ interface Ingest {
     readonly console: ConsoleCapture | null;
     readonly network: NetworkCapture | null;
 }
-interface CreateIngestOptions extends IngestOptions {
-    session?: SessionStore;
-}
+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 {
+    id: string;
+    ref: EntityRef | null;
+}
+interface SessionSnapshot {
+    stack: ViewStackEntry[];
+    /** Sticky overlay highlight. Set by "Highlight Element" actions; cleared on Esc. */
+    pinnedHighlight: EntityRef | null;
+    /** Mirrored from the mode store; the surface mode the session is currently in. */
+    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;
+
+interface NavigationState {
+    stack: ViewStackEntry[];
+}
+interface NavigationActions {
+    push(entry: ViewStackEntry): void;
+    pop(): void;
+    clear(): void;
+    reset(stack: ViewStackEntry[]): void;
+}
+type NavigationStore = StoreApi<NavigationState> & {
+    nav: NavigationActions;
+};
+declare function createNavigationStore(): NavigationStore;
+
+type SurfaceMode = "idle" | "inspecting" | "palette" | "viewing";
+interface ModeSnapshot {
+    mode: SurfaceMode;
+}
+interface ModeBindings {
+    mountInspector?: () => void;
+    destroyInspector?: () => void;
+}
+interface ModeTransitions {
+    openPalette(): void;
+    openInspector(): void;
+    closeInspector(): void;
+    toggleInspector(): void;
+    enterViewing(initialStack: ViewStackEntry[]): void;
+    dismiss(): void;
+    popOrTransition(): void;
+    pushView(entry: ViewStackEntry): void;
+}
+type ModeStore = StoreApi<ModeSnapshot> & {
+    transition: ModeTransitions;
+};
+interface CreateModeStoreOptions {
+    nav: NavigationStore;
+    bindings?: ModeBindings;
+}
+declare function createModeStore(options: CreateModeStoreOptions): ModeStore;
+
+interface HighlightContext {
+    ref: EntityRef | null;
+    element: HTMLElement | null;
+    pinnedRef: EntityRef | null;
+    color: string | null;
+}
+interface HighlightActions {
+    hover(ref: EntityRef, element?: HTMLElement | null, color?: string | null): void;
+    unhover(): void;
+    pin(ref?: EntityRef): void;
+    unpin(): void;
+}
+type SessionStore = StoreApi<SessionState> & {
+    readonly nav: NavigationStore;
+    readonly mode: ModeStore;
+    readonly highlight: HighlightActions;
+    setTheme(theme: ThemePreference, resolved?: ResolvedTheme): void;
+};
+interface CreateSessionOptions extends Partial<SessionSnapshot> {
+    detectTheme?: () => ResolvedTheme;
+    onMountInspector?: () => void;
+    onDestroyInspector?: () => void;
+    onShowOverlay?: (context: HighlightContext) => void;
+    onHideOverlay?: () => void;
+    onUpdateOverlay?: (context: HighlightContext) => void;
+    /** When true, start the session in inspector mode. */
+    inspectorActive?: boolean;
+}
+declare function resolveTheme(preference: ThemePreference, detect?: () => ResolvedTheme): ResolvedTheme;
+declare function createSession(options?: CreateSessionOptions): SessionStore;
+
 interface SurfaceHost {
     readonly hostEl: HTMLElement;
     readonly shadowRoot: ShadowRoot;
@@ -381,31 +386,9 @@ interface CursorTooltip {
 }
 interface CursorTooltipDeps {
     container: Element;
-    session: SessionStore;
 }
 declare function createCursorTooltip(deps: CursorTooltipDeps): CursorTooltip;
 
-interface OverlayShowOptions {
-    label?: string;
-    color?: string;
-    padding?: number;
-    borderStyle?: string;
-    borderWidth?: number;
-    fillOpacity?: number;
-    backdrop?: boolean;
-}
-interface Overlay {
-    show(target: Element, options?: OverlayShowOptions): void;
-    hide(): void;
-    destroy(): void;
-    onDismiss: (() => void) | null;
-    readonly isVisible: boolean;
-}
-interface OverlayDeps {
-    container: Element | ShadowRoot;
-}
-declare function createOverlay(deps: OverlayDeps): Overlay;
-
 interface InspectorMatch {
     element: HTMLElement;
     ref: EntityRef;
@@ -444,39 +427,20 @@ interface Inspector {
     mount(): void;
     destroy(): void;
 }
-declare function defaultResolveMatch(target: Element, registry?: Registry): InspectorMatch | null;
 declare function resolveEntityElement(ref: EntityRef): HTMLElement | null;
-interface HighlightControllerLike {
-    show(ref: EntityRef, opts?: OverlayShowOptions): void;
-    hide(): void;
-}
-declare function createHighlightController(overlay: Overlay): HighlightControllerLike;
 declare function createInspector(options: InspectorOptions): Inspector;
 
 type PinMatchMode = "route" | "pathname" | "component";
-interface PinFilter {
-    branch: string | null;
-    commit: string | null;
-}
-interface PinFilterState extends PinFilter {
-    readonly commits: readonly string[];
-    readonly commitIndex: number;
-}
 interface PinLayer {
     setPins(pins: readonly PinRecord[]): void;
     addPin(pin: PinRecord): void;
     removePin(reportId: string): void;
     clear(): void;
     getPinsForElement(componentId: string): readonly PinRecord[];
-    getAllPinsForElement(componentId: string): readonly PinRecord[];
     getAllPins(): readonly PinRecord[];
     attachChannel(channel: RealtimeChannel): () => void;
     attachCloud(opts: AttachCloudOpts): () => void;
     refresh(): Promise<void>;
-    readonly filterState: PinFilterState;
-    setFilter(filter: Partial<PinFilter>): void;
-    nextCommit(): void;
-    prevCommit(): void;
     onFilterChange(cb: () => void): () => void;
     readonly visible: boolean;
     setVisible(visible: boolean): void;
@@ -496,7 +460,6 @@ interface PinLayerOptions {
     onOpenPinDetail?: (componentId: string, reportId: string) => void;
     onHoverPin?: (anchor: HTMLElement | null, componentId: string | null) => void;
     onPinsChanged?: () => void;
-    currentBranch?: string | null;
 }
 declare function createPinLayer(options: PinLayerOptions): PinLayer;
 
@@ -519,6 +482,27 @@ interface MenuBar {
 }
 declare function createMenuBar(options: MenuBarOptions): MenuBar;
 
+interface OverlayShowOptions {
+    label?: string;
+    color?: string;
+    padding?: number;
+    borderStyle?: string;
+    borderWidth?: number;
+    fillOpacity?: number;
+    backdrop?: boolean;
+}
+interface Overlay {
+    show(target: Element, options?: OverlayShowOptions): void;
+    hide(): void;
+    destroy(): void;
+    onDismiss: (() => void) | null;
+    readonly isVisible: boolean;
+}
+interface OverlayDeps {
+    container: Element | ShadowRoot;
+}
+declare function createOverlay(deps: OverlayDeps): Overlay;
+
 interface ThemeDetector {
     destroy(): void;
     /** Resolve the current theme preference against the environment. */
@@ -640,6 +624,8 @@ interface DetailSurface {
     entityKind: EntityKind;
     /** Registry lookup failed — renders the "not found" placeholder. */
     notFound?: EntityRef;
+    /** Entity exists in the DOM but not in the registry (gen file). */
+    unregistered?: boolean;
     /** Entity display name, rendered as the heading. */
     title?: string;
     subtitle?: DetailSubtitle;
@@ -716,9 +702,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[];
@@ -917,8 +910,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;
 }
@@ -948,12 +942,11 @@ declare function formatShortcutLabel(shortcut: PaletteShortcut): string;
 type EscapeHandler = () => boolean;
 
 declare const SURFACE_HOST_CLASS = "uidex-surface-host";
-declare const SURFACE_CONTAINER_CLASS = "uidex-container";
 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,.uidex-container";
+declare const SURFACE_IGNORE_SELECTOR = ".uidex-surface-host";
 
 interface ViewStackOptions {
     container: HTMLElement;
@@ -962,7 +955,6 @@ interface ViewStackOptions {
     registry: Registry;
     cloud?: CloudAdapter | null;
     highlight: HighlightController;
-    globalActions?: (ctx: ViewContext) => ShellAction[];
     shortcut?: PaletteShortcut;
     dev?: boolean;
     pushEscapeLayer?: ViewContext["pushEscapeLayer"];
@@ -1049,4 +1041,4 @@ interface Uidex {
 }
 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_CONTAINER_CLASS, 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, createHighlightController, createIngest, createInspector, createMenuBar, createModeStore, createNavigationStore, createNetworkCapture, createOverlay, createPinLayer, createRegistry, createRouter, createSession, createSurfaceHost, createSurfaceShell, createThemeDetector, createUidex, createViewStack, defaultResolveMatch, displayName, entityKey, featureDetailView, flowDetailView, formatShortcutLabel, getNativeFetch, isMetaKind, nativeFetch, pageDetailView, pinSettingsView, prettify, primitiveDetailView, regionDetailView, reportView, resolveEntityElement, resolveIngestOptions, resolveTheme, widgetDetailView };
+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 };