@wrongstack/webui 0.319.1 → 1.0.0

package/dist/components/ChatInput/session-draft.d.ts

@@ -0,0 +1,46 @@
+import type React from 'react';
+import { useFileReferenceStore } from '@/stores';
+import type { FileMentionState } from './file-mention-picker.js';
+import type { ImageAttachment } from './image-attachments.js';
+import type { PasteHintState } from './use-paste-drop.js';
+export declare function resolveCancelInput(prev: string, original: string): string;
+export interface SessionDraftRecord {
+    input: string;
+    images: ImageAttachment[];
+    refs: ReturnType<typeof useFileReferenceStore.getState>['refs'];
+}
+/**
+ * One unsent draft per tab: text, image attachments and file chips.
+ *
+ * There is a single ChatInput for all four tabs (the chat surface is parked,
+ * never unmounted), so without this the tab you switch to inherits the text
+ * you were typing in the tab you left.
+ *
+ * Keyed by session id and freed with the lane, so a closed tab's draft cannot
+ * come back on a session that is later handed the same id — and the map does
+ * not grow for the life of the page.
+ */
+export declare const sessionDraftMap: Map<string, SessionDraftRecord>;
+export declare function clearSessionDraft(sessionId?: string | null): void;
+export interface UseSessionDraftOptions {
+    sessionId: string | null;
+    input: string;
+    setInput: React.Dispatch<React.SetStateAction<string>>;
+    pendingImages: ImageAttachment[];
+    setPendingImages: (images: ImageAttachment[]) => void;
+    clearPendingImages: () => void;
+    fileRefs: ReturnType<typeof useFileReferenceStore.getState>['refs'];
+    clearRefs: () => void;
+    setHistoryIdx: (idx: number) => void;
+    stickyDraftRef: React.MutableRefObject<string | null>;
+    setAtMention: (mention: FileMentionState | null) => void;
+    setPasteHint: (hint: PasteHintState | null) => void;
+    stopSpeech: () => void;
+    topicCheckAbortRef: React.MutableRefObject<AbortController | null>;
+    topicCheckBusyRef: React.MutableRefObject<boolean>;
+    setTopicCheckBusy: (busy: boolean) => void;
+    refineBackstopTimerRef: React.MutableRefObject<ReturnType<typeof setTimeout> | null>;
+    textareaRef: React.RefObject<HTMLTextAreaElement | null>;
+}
+export declare function useSessionDraft({ sessionId, input, setInput, pendingImages, setPendingImages, clearPendingImages, fileRefs, clearRefs, setHistoryIdx, stickyDraftRef, setAtMention, setPasteHint, stopSpeech, topicCheckAbortRef, topicCheckBusyRef, setTopicCheckBusy, refineBackstopTimerRef, textareaRef, }: UseSessionDraftOptions): void;
+//# sourceMappingURL=session-draft.d.ts.map

package/dist/components/ChatInput/use-chat-keydown.d.ts

@@ -0,0 +1,21 @@
+import type React from 'react';
+import type { FileMentionState } from './file-mention-picker.js';
+export interface UseChatKeyDownOptions {
+    input: string;
+    setInput: React.Dispatch<React.SetStateAction<string>>;
+    textareaRef: React.RefObject<HTMLTextAreaElement | null>;
+    atMention: FileMentionState | null;
+    promptHistory: string[];
+    runSlashCommand: (raw: string) => boolean;
+    handleSubmit: (e: React.FormEvent) => void;
+}
+export declare function useChatKeyDown({ input, setInput, textareaRef, atMention, promptHistory, runSlashCommand, handleSubmit, }: UseChatKeyDownOptions): {
+    slashIndex: number;
+    setSlashIndex: React.Dispatch<React.SetStateAction<number>>;
+    slashSuggestions: import("./slash-commands.js").SlashCommandDef[];
+    historyIdx: number;
+    setHistoryIdx: React.Dispatch<React.SetStateAction<number>>;
+    stickyDraftRef: React.RefObject<string | null>;
+    handleKeyDown: (e: React.KeyboardEvent<HTMLTextAreaElement>) => void;
+};
+//# sourceMappingURL=use-chat-keydown.d.ts.map

package/dist/components/ChatInput/use-chat-submit.d.ts

@@ -0,0 +1,40 @@
+import type React from 'react';
+import type { useWebSocket } from '@/hooks/useWebSocket';
+import { useChatStore } from '@/stores';
+import type { QueueMode } from '@/stores/chat-store';
+import { type ImageAttachment } from './image-attachments.js';
+export interface UseChatSubmitOptions {
+    input: string;
+    setInput: React.Dispatch<React.SetStateAction<string>>;
+    sessionId: string | null;
+    textareaRef: React.RefObject<HTMLTextAreaElement | null>;
+    pendingImagesRef: React.MutableRefObject<ImageAttachment[]>;
+    clearPendingImages: () => void;
+    isLoading: boolean;
+    setLoading: (loading: boolean) => void;
+    addMessage: ReturnType<typeof useChatStore.getState>['addMessage'];
+    enqueue: ReturnType<typeof useChatStore.getState>['enqueue'];
+    ws: ReturnType<typeof useWebSocket>;
+    enhanceEnabled: boolean;
+    pushPrompt: (prompt: string) => void;
+    setHistoryIdx: (idx: number) => void;
+    stickyDraftRef: React.MutableRefObject<string | null>;
+    refineBackstopTimerRef: React.MutableRefObject<ReturnType<typeof setTimeout> | null>;
+    topicCheckBusyRef: React.MutableRefObject<boolean>;
+    topicCheckAbortRef: React.MutableRefObject<AbortController | null>;
+    setTopicCheckBusy: (busy: boolean) => void;
+    runSlashCommand: (raw: string) => boolean;
+    clearTextarea: () => void;
+    t: (key: string, options?: Record<string, unknown>) => string;
+}
+export declare function useChatSubmit({ input, setInput, sessionId, textareaRef, pendingImagesRef, clearPendingImages, isLoading, setLoading, addMessage, enqueue, ws, enhanceEnabled, pushPrompt, setHistoryIdx, stickyDraftRef, refineBackstopTimerRef, topicCheckBusyRef, topicCheckAbortRef, setTopicCheckBusy, runSlashCommand, clearTextarea, t, }: UseChatSubmitOptions): {
+    sendMsg: (content: string, mode?: QueueMode) => void;
+    submitWith: (mode: QueueMode) => Promise<void>;
+    handleSubmit: (e: React.FormEvent) => void;
+    handleBtw: () => void;
+    handleSteer: () => void;
+    handleAddQueue: () => void;
+    handleAbort: () => void;
+    handleStopAndEdit: () => void;
+};
+//# sourceMappingURL=use-chat-submit.d.ts.map

package/dist/components/ChatInput/use-paste-drop.d.ts

@@ -1,6 +1,6 @@
 import type React from 'react';
 import { type ImageAttachment } from './image-attachments.js';
-interface PasteHintState {
+export interface PasteHintState {
     chars: number;
     lines: number;
     /** Detected language if code was auto-fenced. */

package/dist/components/ChatInput.d.ts

@@ -1,6 +1,6 @@
-import type React from 'react';
-export declare function resolveCancelInput(prev: string, original: string): string;
+import { resolveCancelInput } from './ChatInput/session-draft.js';
+export { resolveCancelInput };
 export declare function ChatInput({ onOpenBreakdown, }?: {
     onOpenBreakdown?: (() => void) | undefined;
-}): React.JSX.Element;
+}): import("react").JSX.Element;
 //# sourceMappingURL=ChatInput.d.ts.map

package/dist/components/FileActivityDrawer/ContextTab.d.ts

@@ -0,0 +1,21 @@
+import { type ActivityRecord } from './types.js';
+export declare function ContextItem({ title, subtitle, raw, }: {
+    title: string;
+    subtitle: string;
+    raw?: string | undefined;
+}): import("react").JSX.Element;
+export declare function ContextColumn({ icon, title, empty, children, }: {
+    icon: React.ReactNode;
+    title: string;
+    empty: string;
+    children: React.ReactNode;
+}): import("react").JSX.Element;
+export declare function ContextTab({ sessions, agents, tasks, records, taskLabel, boardTitle, }: {
+    sessions: string[];
+    agents: string[];
+    tasks: string[];
+    records: ActivityRecord[];
+    taskLabel: (id: string) => string;
+    boardTitle?: string | undefined;
+}): import("react").JSX.Element;
+//# sourceMappingURL=ContextTab.d.ts.map

package/dist/components/FileActivityDrawer/LogsTab.d.ts

@@ -0,0 +1,13 @@
+import { type ActivityRecord } from './types.js';
+export declare function EmptyRow({ text }: {
+    text: string;
+}): import("react").JSX.Element;
+export declare function ActivityRow({ record, raw }: {
+    record: ActivityRecord;
+    raw?: boolean;
+}): import("react").JSX.Element;
+export declare function LogsTab({ records, loading }: {
+    records: ActivityRecord[];
+    loading: boolean;
+}): import("react").JSX.Element;
+//# sourceMappingURL=LogsTab.d.ts.map

package/dist/components/FileActivityDrawer/OverviewTab.d.ts

@@ -0,0 +1,14 @@
+import type { ActivityRecord, FileActivityAnalysis, FileLineageSummary } from './types.js';
+export declare function LifetimeLineage({ lifetime }: {
+    lifetime: FileLineageSummary;
+}): import("react").JSX.Element;
+export declare function OverviewTab({ analysis, lifetime, records, sessions, agents, tasks, taskLabel, }: {
+    analysis: FileActivityAnalysis;
+    lifetime: FileLineageSummary;
+    records: ActivityRecord[];
+    sessions: string[];
+    agents: string[];
+    tasks: string[];
+    taskLabel: (id: string) => string;
+}): import("react").JSX.Element;
+//# sourceMappingURL=OverviewTab.d.ts.map

package/dist/components/FileActivityDrawer/SkeletonTab.d.ts

@@ -0,0 +1,5 @@
+import { type OpenFile } from '@/stores';
+export declare function SkeletonTab({ file }: {
+    file: OpenFile;
+}): import("react").JSX.Element;
+//# sourceMappingURL=SkeletonTab.d.ts.map

package/dist/components/FileActivityDrawer/types.d.ts

@@ -0,0 +1,58 @@
+import type { FileActivity } from '@/stores';
+import type { ChronicleEventView, ChronicleFileLineageRow } from '@/types';
+export type DrawerTab = 'overview' | 'changes' | 'skeleton' | 'context' | 'memory' | 'logs';
+export interface ActivityRecord {
+    id: string;
+    at: number;
+    action: string;
+    actor: string;
+    source: string;
+    summary: string;
+    sessionId?: string | undefined;
+    agentId?: string | undefined;
+    taskId?: string | undefined;
+    boardId?: string | undefined;
+    tool?: string | undefined;
+    status?: string | undefined;
+    raw?: unknown;
+}
+export interface FileActivityAnalysis {
+    level: 'quiet' | 'active' | 'churn';
+    mutationCount: number;
+    sessionCount: number;
+    actorCount: number;
+    taskCount: number;
+}
+/** Full-history rollup of a file's mutation lineage, sourced from the Chronicle
+ *  metrics store (indexed by path) rather than a bounded event scan. */
+export interface FileLineageSummary {
+    mutations: number;
+    sessions: number;
+    tasks: number;
+    boards: number;
+    tools: string[];
+    models: string[];
+    firstAt?: string | undefined;
+    lastAt?: string | undefined;
+}
+export declare function summarizeLineage(rows: ChronicleFileLineageRow[]): FileLineageSummary;
+export declare const MIN_DRAWER_HEIGHT = 150;
+export declare const DEFAULT_DRAWER_HEIGHT = 224;
+export declare const COLLAPSED_HEIGHT = 38;
+export declare const MUTATION_PATTERN: RegExp;
+export declare function normalizeTrackedPath(value: string): string;
+export declare function pathsReferToSameFile(left: string, right: string): boolean;
+export declare function analyzeFileActivity(records: Array<Pick<ActivityRecord, 'at' | 'action' | 'actor' | 'sessionId' | 'taskId'>>, now?: number): FileActivityAnalysis;
+export declare function chronicleRecord(event: ChronicleEventView): ActivityRecord;
+export declare function liveRecord(activity: FileActivity): ActivityRecord;
+export declare function uniqueRecords(records: ActivityRecord[]): ActivityRecord[];
+export declare function countLines(text: string): number;
+export declare function byteCount(text: string): number;
+export declare function formatBytes(bytes: number): string;
+export declare function compactId(value: string): string;
+export declare function changeCounts(oldText: string, newText: string): {
+    added: number;
+    removed: number;
+    large: boolean;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/components/FileActivityDrawer.d.ts

@@ -1,45 +1,6 @@
 import { type OpenFile } from '@/stores';
-import type { ChronicleFileLineageRow } from '@/types';
-interface ActivityRecord {
-    id: string;
-    at: number;
-    action: string;
-    actor: string;
-    source: string;
-    summary: string;
-    sessionId?: string | undefined;
-    agentId?: string | undefined;
-    taskId?: string | undefined;
-    boardId?: string | undefined;
-    tool?: string | undefined;
-    status?: string | undefined;
-    raw?: unknown;
-}
-interface FileActivityAnalysis {
-    level: 'quiet' | 'active' | 'churn';
-    mutationCount: number;
-    sessionCount: number;
-    actorCount: number;
-    taskCount: number;
-}
-/** Full-history rollup of a file's mutation lineage, sourced from the Chronicle
- *  metrics store (indexed by path) rather than a bounded event scan. */
-interface FileLineageSummary {
-    mutations: number;
-    sessions: number;
-    tasks: number;
-    boards: number;
-    tools: string[];
-    models: string[];
-    firstAt?: string | undefined;
-    lastAt?: string | undefined;
-}
-export declare function summarizeLineage(rows: ChronicleFileLineageRow[]): FileLineageSummary;
-export declare function normalizeTrackedPath(value: string): string;
-export declare function pathsReferToSameFile(left: string, right: string): boolean;
-export declare function analyzeFileActivity(records: Array<Pick<ActivityRecord, 'at' | 'action' | 'actor' | 'sessionId' | 'taskId'>>, now?: number): FileActivityAnalysis;
+export { type ActivityRecord, analyzeFileActivity, type DrawerTab, type FileActivityAnalysis, type FileLineageSummary, normalizeTrackedPath, pathsReferToSameFile, summarizeLineage, } from './FileActivityDrawer/types';
 export declare function FileActivityDrawer({ file }: {
     file: OpenFile;
 }): import("react").JSX.Element;
-export {};
 //# sourceMappingURL=FileActivityDrawer.d.ts.map

package/dist/components/MainViewSlot.d.ts

@@ -0,0 +1,16 @@
+import { type ViewMeta } from './view-registry';
+import type { View } from '@/stores/ui-store';
+interface MainViewSlotProps {
+    view: View;
+    onCloseToChat: () => void;
+}
+export declare function MainViewSlot({ view, onCloseToChat, }: MainViewSlotProps): React.ReactElement | null;
+/**
+ * Production `onClose` factory — identical to what the per-view `<button>`
+ * buttons wired by hand in the legacy ViewRouter did: clear the sidebar,
+ * surface chat. Exported so tests can import it without re-implementing the
+ * contract.
+ */
+export declare function defaultOnCloseToChat(): void;
+export type { ViewMeta };
+//# sourceMappingURL=MainViewSlot.d.ts.map

package/dist/components/MemoryManager/DeleteMemoryDialog.d.ts

@@ -2,11 +2,12 @@ import type { SageEntry } from '@/types';
 interface DeleteMemoryDialogProps {
     busyAction: 'create' | 'update' | 'delete' | null;
     deletingId: string | null;
-    memories: readonly SageEntry[];
+    /** Resolved target — may be a search hit or graph neighbor outside the loaded page. */
+    memory: SageEntry | null;
     onCancel: () => void;
     onConfirm: () => void;
     onOpenChange: (open: boolean) => void;
 }
-export declare function DeleteMemoryDialog({ busyAction, deletingId, memories, onCancel, onConfirm, onOpenChange, }: DeleteMemoryDialogProps): import("react").JSX.Element;
+export declare function DeleteMemoryDialog({ busyAction, deletingId, memory, onCancel, onConfirm, onOpenChange, }: DeleteMemoryDialogProps): import("react").JSX.Element;
 export {};
 //# sourceMappingURL=DeleteMemoryDialog.d.ts.map

package/dist/components/SettingsPanel/brain-section-options.d.ts

@@ -26,6 +26,12 @@ export declare const COUNCIL_CALL_TIMEOUTS: BrainOption[];
 export declare const COUNCIL_CONCURRENCY: BrainOption[];
 /** Per-seat output budget. Default 2000 — reasoning models think from this budget. */
 export declare const VOTER_MAX_TOKENS: BrainOption[];
+/**
+ * Deliberation rounds. Deliberately short: each step is another provider call
+ * PER SEAT on every council decision, which makes this the panel's steepest
+ * cost lever.
+ */
+export declare const DELIBERATION_ROUNDS: BrainOption[];
 export declare const JUDGE_MAX_TOKENS: BrainOption[];
 export declare const LEDGER_MEMORY_ENTRIES: BrainOption[];
 export declare const INTERVENTION_WINDOWS: BrainOption[];

package/dist/components/ViewRouter.d.ts

@@ -1,9 +1,17 @@
 /**
- * Main view router — switches the main content area based on `currentView`.
+ * Main view router — mounts every registered view at most once per session
+ * and parks each one when another comes to the front, so the chat virtual
+ * transcript + scroll position + composer draft are kept across trips.
  *
- * Extracted from App.tsx Phase 2 shell decomposition. Each view branch wraps
- * its component in an ErrorBoundary + Suspense. Lazy-loaded views get a
- * PanelSuspense fallback; eagerly-loaded views (chat, settings, context) do not.
+ * The per-view render used to be 26 hand-written `currentView === 'X' &&`
+ * branches here. They now live in `view-registry.ts` and are rendered by
+ * `MainViewSlot`. `chat` itself stays here because it is mounted for the
+ * session lifetime (not conditionally on `currentView`) and parked instead
+ * of remounted. The terminal bottom dock is also handled here because it is
+ * an overlay rather than a "main view" — it can come and go without
+ * swapping `currentView`.
+ *
+ * See docs/audit/webui-full-review-2026-09-03.md B-17.
  */
 export declare function ViewRouter({ sessionId, desktopShell, }: {
     sessionId: string | null;

package/dist/components/view-registry.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Single source of truth for the per-view main-area rendering.
+ *
+ * Each entry tells `MainViewSlot` how to render one `View`:
+ *
+ *  - `Component` — the lazy or eager component. Eager ones are still passed
+ *    through `<Suspense>` for symmetry; that's a no-op on a non-lazy module.
+ *  - `wrapperClassName` — the wrapping `<div>` class (most views use the
+ *    standard flex/min-h-0/min-w-0/overflow-hidden shell; some override it
+ *    for a different scroll axis).
+ *  - `boundaryNameKey` — i18n key for the ErrorBoundary `name` prop, so a
+ *    crash inside a panel is reported under that panel's name and not the
+ *    chat one.
+ *  - `loadingLabelKey` — optional i18n key for a named Suspense fallback.
+ *    When omitted, `PanelSuspense` renders its unlabeled spinner.
+ *  - `props` — extra props the entry's component expects (e.g. `onClose`
+ *    for panels that go back to chat on ×, or `className` for components
+ *    that have to fill a fixed-height parent).
+ *
+ * `chat` is not in this map because it is mounted for the session lifetime
+ * and rendered separately by `ViewRouter`. Anywhere `View` lands at runtime
+ * falls back to a "not registered" placeholder — `RoutedView` catches that
+ * during the one-time AssertNever check, so an entry can never fall through
+ * in CI.
+ *
+ * See docs/audit/webui-full-review-2026-09-03.md B-17 for the context and
+ * view-router/shell examples.
+ */
+import { type ComponentType } from 'react';
+import type { View } from '@/stores/ui-store';
+export interface ViewMeta {
+    /**
+     * The view component. Typed as `ComponentType<any>` because individual
+     * components take stricter prop shapes (e.g. `KanbanView` requires
+     * `onClose`); the registry entry is what guarantees runtime props match.
+     */
+    Component: ComponentType<any>;
+    /** Tailwind class for the wrapping `<div>`. Pass `''` for no wrapper. */
+    wrapperClassName: string;
+    /**
+     * i18n key under the `activity` namespace (e.g. `activity:panels.chat`)
+     * used as the ErrorBoundary's `name`. Crashes inside the view are reported
+     * under this name so the boundary log can attribute them to the panel.
+     */
+    boundaryNameKey: string;
+    /**
+     * Optional i18n key (without i18next quoting — the slot passes it through
+     * the hook itself) for a named Suspense fallback. The previous `ViewRouter`
+     * mixed both: some views passed a named label to `PanelSuspense`, others
+     * rendered the spinner bare. Centralising the choice here means adding a
+     * view can no longer omit the label and produce a silent flash.
+     *
+     * When `null`, the unlabeled spinner is used.
+     */
+    loadingLabelKey: string | null;
+    /**
+     * Extra props merged onto the view component at render time. `onClose`
+     * for views that × back to chat (Kanban, Goal), `className` for views that
+     * have to fill a fixed-height parent (Changes, Mailbox, DesignGallery,
+     * SkillDetail, Chimera Reviews).
+     */
+    props?: Record<string, unknown>;
+}
+/** Widened view for consumers: `VIEW_REGISTRY[view]` reads `ViewMeta | undefined`. */
+export declare const VIEW_REGISTRY: Partial<Record<View, ViewMeta>>;
+/**
+ * The runtime fallback for `onClose: 'PANEL_CLOSE_TO_CHAT'`. The registry
+ * uses a sentinel so the function identity can stay stable across re-renders
+ * (one closure per slot, not per registry lookup) while still pointing to a
+ * real handler owned by `ViewRouter`.
+ */
+export declare const PANEL_CLOSE_TO_CHAT_SENTINEL: 'PANEL_CLOSE_TO_CHAT';
+//# sourceMappingURL=view-registry.d.ts.map

package/dist/hooks/useServerMessage.d.ts

@@ -0,0 +1,71 @@
+import type { WSServerMessage } from '@/types';
+/**
+ * Lane-aware single-message subscription hook (B-03).
+ *
+ * The earlier design let every component that needed a server message reach
+ * into `getWSClient().on(type, handler)` directly — 118 ad-hoc call sites
+ * across the codebase. Each of those sites re-implements the same two
+ * concerns, both of which are easy to get wrong and almost impossible to
+ * audit in isolation:
+ *
+ *   1. teardown — forgetting to call the returned `off()` (or calling it
+ *      against a stale closure) leaves a stale listener on the socket that
+ *      keeps dispatching into an unmounted component;
+ *
+ *   2. lane filtering — a multi-tab window has up to MAX_LANES tabs sharing
+ *      one WS connection, and a message addressed to tab 2 must not be
+ *      acted on by tab 1's listener. Some sites filter on
+ *      `payload.sessionId`, some on `isActiveSessionMessage`, and many
+ *      forget to filter at all (every reply lands on every tab).
+ *
+ * `useServerMessage` collapses both: it registers exactly once, cleans up on
+ * unmount, and drops messages whose `payload.sessionId` doesn't match the
+ * `sessionId` passed in. Filtering is OPT-IN: a caller that passes no
+ * `sessionId` receives every frame of that type, exactly as a raw `ws.on`
+ * would. Pass the lane you care about whenever the state you update is
+ * tab-local.
+ *
+ * Typing follows the underlying `ws.on` narrowing — pass a literal `type`
+ * and the handler receives the matching union member of `WSServerMessage`,
+ * not the bare envelope.
+ *
+ * The handler is captured in a ref so re-renders don't churn the WS
+ * subscription. Pass `deps` when the handler closes over reactive state
+ * that should be fresh inside the handler (same contract as `useEffect`).
+ *
+ * Example migration of the three ad-hoc `context.editor.*` subscriptions
+ * inside `ContextWindowEditor.tsx`:
+ *
+ *   useServerMessage('context.editor.snapshot', (msg) => {
+ *     store.getState().loadSnapshot(msg.payload);
+ *   }, { sessionId: askedFor, deps: [store] });
+ */
+export interface UseServerMessageOptions {
+    /**
+     * If provided, the handler runs ONLY when the inbound message's
+     * `payload.sessionId` matches this value (or when the message has no
+     * sessionId stamp at all — boot-time broadcasts, project-wide events).
+     * If omitted, NO lane filter is applied and the handler sees every frame
+     * of this type, including replies addressed to another tab. Accepts
+     * `null` for sources that may yield a nullable pointer (Zustand
+     * selectors, etc.) — it is normalized to "no pin".
+     */
+    sessionId?: string | null | undefined;
+    /**
+     * Re-subscribe when these change. Same contract as `useEffect`. Defaults
+     * to `[]` — the subscription is mounted once.
+     */
+    deps?: ReadonlyArray<unknown>;
+    /**
+     * When `false`, the hook stays registered (so the deps contract is not
+     * violated) but the WS subscription is NOT installed — both the initial
+     * register and any dep-driven re-register are skipped. Defaults to
+     * `true`. Mirrors the `active` / `enabled` flag most consumers want to
+     * gate polling loops on without paying the cleanup + re-register cost.
+     */
+    enabled?: boolean;
+}
+export declare function useServerMessage<K extends WSServerMessage['type']>(type: K, handler: (msg: Extract<WSServerMessage, {
+    type: K;
+}>) => void, options?: UseServerMessageOptions): void;
+//# sourceMappingURL=useServerMessage.d.ts.map

package/dist/hooks/ws-handlers/session-context-handlers.d.ts

@@ -16,6 +16,26 @@ export declare const warnedCostModels: Map<string, Set<string>>;
  */
 export declare function flushThinkingLogForCurrentIteration(lane?: ChatLaneActions): void;
 export declare function handleContextDebug(msg: WSServerMessage): void;
+/**
+ * The server's general-purpose "did that work?" reply.
+ *
+ * Two things were wrong here, and both are about a socket that serves up to
+ * four tabs:
+ *
+ *  1. The toast was unconditional. A background tab's "commit failed" or
+ *     "provider key rejected" popped on whichever tab the user was looking at,
+ *     with no way to tell whose it was — and the tab that actually failed
+ *     showed nothing at all when switched to. The server now stamps the asking
+ *     tab (`sessionId`, see B-05), so the toast fires only for the tab in
+ *     front and a background tab gets an attention marker on its tab strip
+ *     instead — the same treatment `provider.fallback_pending` already gives.
+ *  2. EVERY result re-fetched the saved-provider list, including a prefs
+ *     validation error that has nothing to do with providers. The refetch is
+ *     kept (deciding from the message PROSE which results touch providers
+ *     would be a worse bug than the extra round trip) but it now runs only on
+ *     the foreground path, so a background tab's result no longer triggers it
+ *     at all.
+ */
 export declare function handleKeyOperationResult(msg: WSServerMessage): void;
 /**
  * A successful model switch is broadcast to every surface, so it has to be