uidex 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 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';
 
 declare const ENTITY_KINDS: readonly ["route", "page", "feature", "widget", "region", "element", "primitive", "flow"];
@@ -34,11 +37,16 @@ interface Route {
     path: string;
     page: string;
 }
+interface FlowStep {
+    entityId: string;
+    action?: string;
+}
 interface Flow {
     kind: "flow";
     id: string;
     loc: Location;
     touches: string[];
+    steps: FlowStep[];
 }
 interface Page extends EntityWithMetaBase {
     kind: "page";
@@ -71,6 +79,26 @@ declare class UnknownEntityKindError extends Error {
 }
 declare function assertEntityKind(kind: string): asserts kind is EntityKind;
 
+interface ReportRecord {
+    id: string;
+    entity?: string;
+    reporter?: {
+        id?: string;
+        email?: string;
+        name?: string;
+    };
+    title?: string;
+    body: string;
+    type: string;
+    severity: string;
+    status: string;
+    labels?: string[];
+    url: string;
+    route?: string;
+    pageTitle?: string;
+    screenshot?: string;
+    createdAt: string;
+}
 interface Registry {
     add(entity: Entity): void;
     get<K extends EntityKind>(kind: K, id: string): EntityByKind<K> | undefined;
@@ -78,6 +106,11 @@ interface Registry {
     query(predicate: (entity: Entity) => boolean): Entity[];
     byScope(scope: Scope): Entity[];
     touchedBy(flowId: string): Entity[];
+    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>;
+    onReportsChange(cb: () => void): () => void;
 }
 declare function createRegistry(): Registry;
 
@@ -93,11 +126,10 @@ declare const KIND_STYLE: Record<EntityKind, KindStyleEntry>;
 declare function prettify(id: string): string;
 declare function displayName(entity: Entity, node?: Element | null): string;
 
-interface HighlightContext {
-    ref: EntityRef | null;
-    element: HTMLElement | null;
-    pinnedRef: EntityRef | null;
-    color: string | null;
+interface UserIdentity {
+    id: string;
+    name?: string;
+    avatar?: string;
 }
 
 type ThemePreference = "light" | "dark" | "auto";
@@ -116,114 +148,84 @@ interface SessionSnapshot {
     theme: ThemePreference;
     resolvedTheme: ResolvedTheme;
     ingestActive: boolean;
-}
-interface SessionActions {
-    hover(ref: EntityRef | null): void;
-    select(ref: EntityRef | null): void;
     /**
-     * Append a view onto the view stack. Pure: never resolves defaults.
+     * Identity for the local user. Set once at session creation; gates realtime
+     * features (cursor labels, presence) and auto-populates report attribution.
      */
-    pushStack(entry: ViewStackEntry): void;
-    /**
-     * Remove the top entry from the view stack. No-op when the stack is empty.
-     */
-    popStack(): void;
-    /**
-     * Empty the view stack.
-     */
-    clearStack(): void;
-    /**
-     * Open a view by id. If `ref` is omitted, the current `selection` is captured;
-     * pass `null` explicitly to open the view with no ref context. Thin wrapper
-     * around `pushStack`.
-     */
-    openView(id: string, ref?: EntityRef | null): void;
-    /**
-     * Clear the entire view stack. Thin wrapper around `clearStack`.
-     */
-    closeView(): void;
-    setInspectorActive(active: boolean): void;
-    toggleInspector(): void;
-    /** Pin the overlay to `ref` until `clearPinnedHighlight` is called. */
-    pinHighlight(ref: EntityRef): void;
-    clearPinnedHighlight(): void;
-    setTheme(theme: ThemePreference, resolved?: ResolvedTheme): void;
-    setIngest(active: boolean): void;
-}
-interface SessionState extends SessionSnapshot {
-    actions: SessionActions;
+    user: UserIdentity | null;
 }
+type SessionState = SessionSnapshot;
 
-type SurfaceEvent = {
-    type: "TOGGLE_INSPECTOR";
-} | {
-    type: "OPEN_PALETTE";
-} | {
-    type: "PUSH_VIEW";
-    entry: ViewStackEntry;
-} | {
-    type: "POP_VIEW";
-} | {
-    type: "CLOSE";
-} | {
-    type: "ESC";
-} | {
-    type: "CMD_K";
-} | {
-    type: "SELECT";
-    ref: EntityRef | null;
-    entry: ViewStackEntry;
-} | {
-    type: "SET_SELECTION";
-    ref: EntityRef | null;
-} | {
-    type: "HOVER";
-    ref: EntityRef;
-    element: HTMLElement | null;
-    color?: string | null;
-} | {
-    type: "UNHOVER";
-} | {
-    type: "PIN";
-    ref?: EntityRef;
-} | {
-    type: "UNPIN";
-} | {
-    type: "SET_THEME";
-    theme: ThemePreference;
-    resolvedTheme: ResolvedTheme;
-} | {
-    type: "SET_INGEST";
-    active: boolean;
+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 SessionStore = StoreApi<SessionState> & {
-    send(event: SurfaceEvent): void;
-};
-interface SurfaceBindings {
+type SurfaceMode = "idle" | "inspecting" | "palette" | "viewing";
+interface ModeSnapshot {
+    mode: SurfaceMode;
+    inspectorActive: boolean;
+}
+interface ModeBindings {
     mountInspector?: () => void;
     destroyInspector?: () => void;
-    openActionsPopup?: () => void;
-    closePopup?: () => void;
 }
-interface HighlightBindings {
-    showOverlay?: (context: HighlightContext) => void;
-    hideOverlay?: () => void;
-    updateOverlay?: (context: HighlightContext) => void;
+interface ModeTransitions {
+    openPalette(): void;
+    openInspector(): void;
+    closeInspector(): void;
+    toggleInspector(): void;
+    enterViewing(initialStack: ViewStackEntry[]): void;
+    dismiss(): void;
+    popOrTransition(): void;
+    pushView(entry: ViewStackEntry): void;
 }
-interface SessionBindings {
-    surface?: SurfaceBindings;
-    highlight?: HighlightBindings;
+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;
-    /**
-     * Action implementations injected into the surface machine and its
-     * highlight child actor. Implementations may be closures that read from
-     * mutable refs filled in after `createSession` returns (e.g., the SDK's
-     * shell isn't available until `mount`).
-     */
-    bindings?: SessionBindings;
+    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;
@@ -274,92 +276,46 @@ declare function createNetworkCapture(options?: NetworkCaptureOptions): NetworkC
 declare const nativeFetch: typeof fetch | undefined;
 declare function getNativeFetch(): typeof fetch | undefined;
 
-interface ConsoleLogEntry {
-    level: "log" | "warn" | "error" | "info";
-    message: string;
-    timestamp: string;
-}
-interface NetworkErrorEntry {
-    url: string;
-    method: string;
-    status: number | null;
-    statusText: string | null;
-    timestamp: string;
-}
-interface Viewport {
-    width: number;
-    height: number;
-}
-interface SourceRef {
-    filePath: string;
-    line: number;
-}
-interface FeedbackSuggestedTarget {
-    integrationId: string;
-    targetConfig: Record<string, unknown>;
-}
-interface FeedbackPayload {
-    type: "bug" | "feature" | "improvement" | "question";
-    severity: "low" | "medium" | "high" | "critical";
-    title?: string;
-    description: string;
-    componentId: string;
-    element?: string | null;
-    sources?: SourceRef[];
-    url: string;
-    path: string;
-    route?: string | null;
-    pageTitle?: string;
-    sessionId?: string;
-    reporterEmail?: string;
-    reporterName?: string;
-    timestamp: string;
-    viewport: Viewport;
-    screen: Viewport;
-    userAgent: string;
-    locale?: string;
-    environment?: string;
-    appVersion?: string;
-    consoleLogs?: ConsoleLogEntry[];
-    networkErrors?: NetworkErrorEntry[];
-    metadata?: Record<string, string>;
-    screenshot?: string;
-    suggestedTarget?: FeedbackSuggestedTarget;
-}
-interface FeedbackExternalLink {
-    ok: boolean;
-    url?: string;
-    key?: string;
-    error?: string;
-}
-interface FeedbackResult {
-    id: string;
-    sequenceNumber: number;
-    externalLink?: FeedbackExternalLink;
-}
-interface IngestConfigEpic {
-    key: string;
-    summary: string;
-    status: string;
-}
-interface IngestConfig {
-    hasJira: boolean;
-    integrationId?: string;
-    epics?: IngestConfigEpic[];
-}
-/**
- * Generic so third-party adapters (e.g. `uidex-cloud`) can plug in their own
- * payload/result/integration shapes. SDK-bundled `cloud()` returns the
- * defaulted form. `ViewContext.cloud` uses the fully-open variant; consumers
- * that need the SDK shape narrow with `as CloudAdapter`.
- */
-interface CloudAdapter<TPayload = FeedbackPayload, TResult = FeedbackResult, TIntegrations = {
+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 feedback: {
+    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 {
@@ -410,6 +366,10 @@ interface CleanupStack {
 type CursorTooltipContent = {
     entity: Entity;
     node?: Element | null;
+    layer?: {
+        index: number;
+        total: number;
+    };
 } | string;
 interface CursorTooltip {
     destroy(): void;
@@ -432,15 +392,17 @@ interface OverlayShowOptions {
     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;
+    container: Element | ShadowRoot;
 }
 declare function createOverlay(deps: OverlayDeps): Overlay;
 
@@ -451,11 +413,16 @@ interface InspectorMatch {
     /** Display name resolved via `displayName(entity, element)`. */
     label: string;
 }
+interface InspectorMatchStack {
+    matches: InspectorMatch[];
+    index: number;
+    current: InspectorMatch;
+}
 interface InspectorOptions {
     session: SessionStore;
     registry?: Registry;
-    resolve?: (target: Element) => InspectorMatch | null;
-    onHover?: (match: InspectorMatch | null, cursor: {
+    resolveAll?: (target: Element) => InspectorMatch[];
+    onHover?: (stack: InspectorMatchStack | null, cursor: {
         x: number;
         y: number;
     } | null) => void;
@@ -463,6 +430,10 @@ interface InspectorOptions {
         x: number;
         y: number;
     }) => void;
+    onCycle?: (stack: InspectorMatchStack, cursor: {
+        x: number;
+        y: number;
+    }) => void;
 }
 interface Inspector {
     mount(): void;
@@ -477,17 +448,67 @@ interface HighlightControllerLike {
 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;
+    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;
+    currentBranch?: string | null;
+}
+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;
 }
@@ -511,13 +532,18 @@ 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
      * host.
      */
     inspector?: Pick<InspectorOptions, "onSelect"> & {
-        onAfterHover?: InspectorOptions["onHover"];
+        onAfterHover?: (match: InspectorMatch | null, cursor: {
+            x: number;
+            y: number;
+        } | null) => void;
     };
 }
 interface SurfaceShell {
@@ -538,7 +564,29 @@ interface SurfaceShell {
  */
 declare function createSurfaceShell(options: CreateSurfaceShellOptions): SurfaceShell;
 
-type ViewSurface = ListSurface | DetailSurface | FormSurface | CustomSurface;
+interface RouteMatch {
+    view: View;
+    priority: number;
+}
+interface Router {
+    resolve(ref: EntityRef): RouteMatch | null;
+    add(view: View, priority?: number): void;
+    remove(id: string): void;
+    get(id: string): View | undefined;
+    list(): readonly View[];
+    buildStack(entry: ViewStackEntry): ViewStackEntry[];
+    navigate(ref: EntityRef): void;
+    recents(): readonly EntityRef[];
+    favorites(): readonly EntityRef[];
+    toggleFavorite(ref: EntityRef): void;
+    isFavorite(ref: EntityRef): boolean;
+}
+interface CreateRouterOptions {
+    session: SessionStore;
+}
+declare function createRouter(options: CreateRouterOptions): Router;
+
+type ViewSurface = ListSurface | DetailSurface | FormSurface;
 interface ListSurface {
     kind: "list";
     id: string;
@@ -547,6 +595,12 @@ interface ListSurface {
     emptyLabel?: string;
     defaultHighlight?: string;
     filter?(item: ListItem, query: string): boolean;
+    /**
+     * When false, the search input is hidden and the content element receives
+     * focus directly for keyboard navigation.
+     * @default true
+     */
+    searchable?: boolean;
 }
 interface ListItem {
     value: string;
@@ -566,12 +620,15 @@ interface ListItem {
     };
     /**
      * Optional leading-icon factory used for non-entity rows (e.g. a palette
-     * "Feedback" command). Called per-render so the returned Node is fresh.
+     * "Report" command). Called per-render so the returned Node is fresh.
      * The shell wraps whatever is returned in a rounded-square tile.
      */
     leading?: () => Node;
     /** Raw data attribute tag appended to the row (for test/e2e hooks). */
     tag?: string;
+    trailing?: TemplateResult;
+    /** Contextual actions surfaced in the footer popup when this row is highlighted. */
+    actions?: readonly ShellAction[];
 }
 interface DetailSurface {
     kind: "detail";
@@ -595,6 +652,7 @@ interface DetailActionBase {
     ariaLabel?: string;
     hint?: string;
     intent?: ShellActionIntent;
+    group?: string;
 }
 type DetailAction = (DetailActionBase & {
     copy: string;
@@ -612,19 +670,21 @@ type DetailAction = (DetailActionBase & {
 }) | (DetailActionBase & {
     run: (ctx: DetailActionRunContext) => void | Promise<void>;
 });
-type DetailActionIcon = "copy" | "message-circle" | "chevron-down" | "target";
+type DetailActionIcon = "archive-x" | "copy" | "camera" | "inbox" | "message-circle-warning" | "chevron-down" | "highlighter" | "sticky-note" | "ticket-plus" | "view";
 interface DetailActionRunContext {
     setLabel(next: string, durationMs?: number): void;
 }
+interface ResolvedFlowStep {
+    ordinal: number;
+    entity: Entity;
+    action?: string;
+}
 type DetailSection = {
     id: "description";
     text: string;
 } | {
     id: "acceptance";
     items: readonly string[];
-} | {
-    id: "scopes";
-    scopes: readonly string[];
 } | {
     id: "composes";
     label: string;
@@ -642,13 +702,26 @@ type DetailSection = {
 } | {
     id: "touches";
     entities: readonly Entity[];
-    unresolved: readonly string[];
+    filterable?: boolean;
+} | {
+    id: "steps";
+    steps: readonly ResolvedFlowStep[];
     filterable?: boolean;
 } | {
     id: "routes";
     paths: readonly string[];
     filterable?: boolean;
+} | {
+    id: "screenshot";
+    url: string;
+} | {
+    id: "metadata";
+    entries: readonly MetadataEntry[];
 };
+interface MetadataEntry {
+    label: string;
+    value: string;
+}
 interface FormSurface {
     kind: "form";
     id: string;
@@ -661,6 +734,11 @@ interface FormSurface {
      * 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
@@ -740,10 +818,6 @@ type FormField = (FormFieldBase & {
     kind: "checkbox";
     value?: boolean;
 });
-interface CustomSurface {
-    kind: "custom";
-    render: (ctx: ViewContext, root: HTMLElement) => Cleanup | void;
-}
 
 interface ViewPalette {
     label: string;
@@ -754,9 +828,7 @@ interface ViewPalette {
      */
     icon?: () => Node;
     shortcut?: string;
-}
-interface ViewDirectory {
-    list(): readonly View[];
+    subtitle?: string | (() => string);
 }
 interface ViewPushTarget {
     id: string;
@@ -770,16 +842,19 @@ interface ViewContext {
     ref: EntityRef | null;
     registry: Registry;
     cloud: CloudAdapter<unknown, unknown, unknown> | null;
-    sdkCloud: CloudAdapter;
-    views: ViewDirectory;
+    /**
+     * 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;
     /** Pop the top view off the stack. No-op when the stack is empty. */
     pop: () => void;
     /** Clear the entire view stack. */
     close: () => void;
-    /** Resolve the first view matching `ref` and push it onto the stack. */
-    navigate: (ref: EntityRef) => void;
     /** Pin the overlay to `ref` until the user presses Esc. */
     pinHighlight: (ref: EntityRef) => void;
     /** Shell-owned search input. The shell dispatches its value into the active surface. */
@@ -788,6 +863,11 @@ 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;
@@ -812,6 +892,7 @@ interface ShellAction {
     id: string;
     label: string;
     shortcut?: string;
+    icon?: () => Node;
     perform: () => void | Promise<void>;
     intent?: ShellActionIntent;
 }
@@ -832,51 +913,56 @@ interface View {
      */
     focusTarget?: (root: HTMLElement, ctx: ViewContext) => HTMLElement | null;
     surface: (ctx: ViewContext) => ViewSurface;
+    /** Direct render for integration adapters (React, etc.). Mutually exclusive with surface renderers. */
+    render?: (ctx: ViewContext, root: HTMLElement) => Cleanup | void;
+    parent?: (ref: EntityRef | null) => ViewStackEntry | null;
 }
 declare class ViewValidationError extends Error {
     constructor(message: string);
 }
 
 interface ActionsPopupHandle {
+    readonly trigger: HTMLButtonElement;
     readonly element: HTMLElement;
-    open(actions: ShellAction[]): void;
+    setActions(actions: ShellAction[]): void;
+    open(): void;
     close(): void;
     isOpen(): boolean;
-    handleKey(e: KeyboardEvent): boolean;
     destroy(): void;
 }
 
+interface PaletteShortcut {
+    /** The key value (e.g. "k", "j", ";"). Matched case-insensitively. */
+    key: string;
+    /** Require Cmd (Mac) / Ctrl (Win/Linux). Default: true. */
+    mod?: boolean;
+    /** Require Shift. Default: false. */
+    shift?: boolean;
+}
+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 = 2147483644;
-declare const Z_OVERLAY = 2147483645;
-declare const Z_CHROME = 2147483646;
+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";
 
-interface ViewRegistrar {
-    register(view: View): void;
-    unregister(id: string): void;
-    list(): readonly View[];
-    get(id: string): View | undefined;
-    findMatch(ref: EntityRef): View | null;
-    navigate(ref: EntityRef): void;
-}
-interface ViewRegistrarOptions {
-    session: SessionStore;
-    dev?: boolean;
-}
-declare function createViewRegistrar(options: ViewRegistrarOptions): ViewRegistrar;
-
 interface ViewStackOptions {
     container: HTMLElement;
-    views: ViewRegistrar;
+    views: Router;
     session: SessionStore;
     registry: Registry;
     cloud?: CloudAdapter | null;
-    sdkCloud: CloudAdapter;
     highlight: HighlightController;
     globalActions?: (ctx: ViewContext) => ShellAction[];
+    shortcut?: PaletteShortcut;
     dev?: boolean;
+    pushEscapeLayer?: ViewContext["pushEscapeLayer"];
+    onAfterSubmit?: () => void;
+    getRoute?: () => string;
 }
 interface ViewStack {
     /**
@@ -889,7 +975,7 @@ interface ViewStack {
 }
 declare function createViewStack(options: ViewStackOptions): ViewStack;
 
-declare const commandPaletteView: View;
+declare function createCommandPaletteView(shortcut?: PaletteShortcut): View;
 
 declare const componentDetailView: View;
 declare const featureDetailView: View;
@@ -898,11 +984,13 @@ declare const widgetDetailView: View;
 declare const primitiveDetailView: View;
 declare const pageDetailView: View;
 
-declare const feedbackView: View;
+declare const reportView: View;
 
 declare const flowDetailView: View;
 
-declare const DEFAULT_VIEWS: readonly [View, View, View, View, View, View, View, View, View, View, View, View];
+declare const pinSettingsView: View;
+
+declare function buildDefaultViews(shortcut?: PaletteShortcut): View[];
 
 interface CreateUidexOptions {
     theme?: ThemePreference;
@@ -923,17 +1011,37 @@ interface CreateUidexOptions {
      * 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;
     unmount(): void;
     readonly registry: Registry;
     readonly session: SessionStore;
-    readonly views: ViewRegistrar;
+    readonly views: Router;
     readonly cloud: CloudAdapter | null;
     readonly ingest: Ingest | null;
     readonly shadowRoot: ShadowRoot | null;
 }
 declare function createUidex(options?: CreateUidexOptions): Uidex;
 
-export { type Cleanup, type CloudAdapter, type ConsoleCapture, type ConsoleEntry, type ConsoleLevel, type ConsoleLogEntry, type Corner, type CreateSessionOptions, type CreateSurfaceShellOptions, type CreateUidexOptions, type CursorTooltip, type CursorTooltipDeps, type CustomSurface, DEFAULT_VIEWS, 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 FeedbackExternalLink, type FeedbackPayload, type FeedbackResult, type FeedbackSuggestedTarget, type Flow, type FormField, type FormSubmit, type FormSubmitResult, type FormSurface, type FormValue, type HighlightController, type Ingest, type IngestConfig, type IngestConfigEpic, type IngestOptions, type Inspector, type InspectorMatch, type InspectorOptions, KIND_STYLE, type KindStyleEntry, type ListItem, type ListSurface, type Location, type MenuBar, type MenuBarOptions, type MetaEntityKind, type Metadata, type NetworkCapture, type NetworkEntry, type NetworkErrorEntry, type Overlay, type OverlayShowOptions, type Page, type Primitive, type Region, type Registry, type ResolvedTheme, type Route, SURFACE_CONTAINER_CLASS, SURFACE_HOST_CLASS, SURFACE_IGNORE_SELECTOR, type Scope, type SessionActions, type SessionSnapshot, type SessionState, type SessionStore, type ShellAction, type ShellHint, type SourceRef, type SurfaceHost, type SurfaceHostOptions, type SurfaceShell, type ThemeDetector, type ThemeDetectorDeps, type ThemePreference, type Uidex, UnknownEntityKindError, type View, type ViewContext, type ViewDirectory, type ViewPalette, type ViewPushTarget, type ViewRegistrar, type ViewRegistrarOptions, type ViewStack, type ViewStackEntry, type ViewStackOptions, type ViewSurface, ViewValidationError, type Viewport, type Widget, Z_BASE, Z_CHROME, Z_OVERLAY, assertEntityKind, commandPaletteView, componentDetailView, createConsoleCapture, createCursorTooltip, createHighlightController, createIngest, createInspector, createMenuBar, createNetworkCapture, createOverlay, createRegistry, createSession, createSurfaceHost, createSurfaceShell, createThemeDetector, createUidex, createViewRegistrar, createViewStack, defaultResolveMatch, displayName, entityKey, featureDetailView, feedbackView, flowDetailView, getNativeFetch, isMetaKind, nativeFetch, pageDetailView, prettify, primitiveDetailView, regionDetailView, 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_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 };