uidex 0.5.2 → 0.7.0

package/dist/react/index.d.cts

@@ -94,6 +94,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[];
@@ -101,88 +102,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 {
-    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;
-};
-
-type SurfaceMode = "idle" | "inspecting" | "palette" | "viewing";
-interface ModeSnapshot {
-    mode: SurfaceMode;
-    inspectorActive: boolean;
-}
-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 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;
-};
-
 type ConsoleLevel = "warn" | "error";
 interface ConsoleEntry {
     level: ConsoleLevel;
@@ -224,6 +147,12 @@ interface NetworkCapture {
     clear(): void;
 }
 
+interface UserIdentity {
+    id: string;
+    name?: string;
+    avatar?: string;
+}
+
 type RealtimePresenceUser = {
     userId: string;
     name: string;
@@ -241,6 +170,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>;
@@ -262,8 +193,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 {
@@ -283,6 +223,74 @@ interface Ingest {
     readonly network: NetworkCapture | 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;
+};
+
+type SurfaceMode = "idle" | "inspecting" | "palette" | "viewing";
+interface ModeSnapshot {
+    mode: SurfaceMode;
+}
+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 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;
+};
+
+type Corner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+
 interface OverlayShowOptions {
     label?: string;
     color?: string;
@@ -293,8 +301,6 @@ interface OverlayShowOptions {
     backdrop?: boolean;
 }
 
-type Corner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
-
 interface RouteMatch {
     view: View;
     priority: number;
@@ -362,6 +368,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;
@@ -438,9 +446,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[];
@@ -639,8 +654,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;
 }

package/dist/react/index.d.ts

@@ -94,6 +94,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[];
@@ -101,88 +102,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 {
-    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;
-};
-
-type SurfaceMode = "idle" | "inspecting" | "palette" | "viewing";
-interface ModeSnapshot {
-    mode: SurfaceMode;
-    inspectorActive: boolean;
-}
-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 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;
-};
-
 type ConsoleLevel = "warn" | "error";
 interface ConsoleEntry {
     level: ConsoleLevel;
@@ -224,6 +147,12 @@ interface NetworkCapture {
     clear(): void;
 }
 
+interface UserIdentity {
+    id: string;
+    name?: string;
+    avatar?: string;
+}
+
 type RealtimePresenceUser = {
     userId: string;
     name: string;
@@ -241,6 +170,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>;
@@ -262,8 +193,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 {
@@ -283,6 +223,74 @@ interface Ingest {
     readonly network: NetworkCapture | 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;
+};
+
+type SurfaceMode = "idle" | "inspecting" | "palette" | "viewing";
+interface ModeSnapshot {
+    mode: SurfaceMode;
+}
+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 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;
+};
+
+type Corner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+
 interface OverlayShowOptions {
     label?: string;
     color?: string;
@@ -293,8 +301,6 @@ interface OverlayShowOptions {
     backdrop?: boolean;
 }
 
-type Corner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
-
 interface RouteMatch {
     view: View;
     priority: number;
@@ -362,6 +368,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;
@@ -438,9 +446,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[];
@@ -639,8 +654,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;
 }