@kabmo-labs/kabmo 0.3.1 → 0.4.0

package/src/client/components/workspace/chat-timeline/index.tsx

@@ -5,7 +5,7 @@ import type { ExtensionUiDialogRequest } from '@/shared/types/omp/agent';
 import type { Attachment } from '@/shared/types';
 import type { UserTurnRef } from '@/shared/types/chat';
 import type { ExtensionDialogResponse } from '@/client/components/workspace/chat-timeline/tool-renderers/extension-dialog/Lazy';
-import { EmptyWorkspacePrompt } from '@/client/components/workspace/chat-timeline/EmptyWorkspacePrompt';
+import { PendingChatView } from '@/client/components/workspace/chat-timeline/PendingChatView';
 import { SessionSkeleton } from '@/client/components/workspace/chat-timeline/SessionSkeleton';
 import { SubagentView } from '@/client/components/workspace/chat-timeline/SubagentView';
 import { TimelineBody } from '@/client/components/workspace/chat-timeline/TimelineBody';
@@ -15,12 +15,14 @@ import { useSessionTitle } from '@/client/hooks/chat/timeline/session-title';
 import { useSubagentView } from '@/client/hooks/chat/timeline/subagent-view';
 import { useUndoConfirmation } from '@/client/hooks/chat/timeline/undo-confirmation';
 import { useModelNames } from '@/client/hooks/models/use-model-names';
+import { useRunIdentity } from '@/client/hooks/chat/timeline/run-identity';
 import { useProviderNames } from '@/client/hooks/models/use-provider-names';
 import { useToasts } from '@/client/hooks/ui/toasts';
 import { ChatOverlays } from '@/client/components/workspace/chat-timeline/ChatOverlays';
 import { ToastStack } from '@/client/components/common/ToastStack';
 import { composerRootFor } from '@/shared/lib/workspace/active-project';
 import { useSidebarData } from '@/client/hooks/chat/omp/session-list';
+import { useHeldWait } from '@/client/hooks/chat/waiting/held';
 
 interface ChatTimelineProps {
   className?: string;
@@ -36,7 +38,7 @@ interface ChatTimelineProps {
 }
 
 export function ChatTimeline({ className = '', appSettings = {}, onSessionTitle, variant = 'desktop' }: ChatTimelineProps) {
-  const { folders, streamStatusMap } = useSidebarData();
+  const { folders, streamStatusMap, titleHint } = useSidebarData();
   const isMobile = variant === 'mobile';
   const { toasts, pushToast, dismissToast } = useToasts();
   const {
@@ -82,6 +84,7 @@ export function ChatTimeline({ className = '', appSettings = {}, onSessionTitle,
     planReview,
     composerModelRef,
     deferredComposerPickRef,
+    waitingDependency,
     extensionDialogs,
     resolveExtensionDialog,
     respondToExtensionUi,
@@ -151,24 +154,14 @@ export function ChatTimeline({ className = '', appSettings = {}, onSessionTitle,
 
   const modelNames = useModelNames();
   const providerNames = useProviderNames();
-  // The run's model is persisted beside the stream status and rides the sidebar
-  // payload, so the indicator names the real provider/model even for a run this
-  // page never started — the transcript is the fallback, not the source.
-  const runModel = useMemo(
-    () => folders.flatMap((f) => f.sessions ?? []).find((s) => String(s.id) === String(sessionId))?.runModel ?? null,
-    [folders, sessionId],
-  );
-  const fallbackModel = typeof sessionData?.model === 'object' ? sessionData.model : null;
-  const sessionProvider = runModel?.provider ?? fallbackModel?.provider;
-  const sessionModelId = runModel?.modelId ?? fallbackModel?.modelId;
-  const sessionModelName = sessionModelId
-    ? (modelNames[sessionModelId] ?? sessionModelId)
-    : (typeof sessionData?.model === 'string' ? sessionData.model : undefined);
+  const { sessionProvider, sessionModelName } = useRunIdentity({ folders, sessionId, sessionData, modelNames });
 
   // A pending "new-…" session has no messages yet, so the workspace picker
   // must stay available until the first chat is sent (which spawns the real
   // omp session). Never lock the user into a folder before sending.
   const isPendingSession = Boolean(sessionId?.startsWith('new-'));
+
+  const { heldWait, cancelHeldWait } = useHeldWait(sessionId, isPendingSession, pushToast);
   const composerRoot = composerRootFor(folders, sessionId, selectedFolderId);
 
   // The chat-level "a run is in flight" flag is computed in `useChatTimeline`
@@ -184,7 +177,7 @@ export function ChatTimeline({ className = '', appSettings = {}, onSessionTitle,
 
   if (!sessionId || isPendingSession) {
     return (
-      <EmptyWorkspacePrompt
+      <PendingChatView
         className={className}
         folders={folders}
         selectedFolderId={selectedFolderId}
@@ -216,6 +209,12 @@ export function ChatTimeline({ className = '', appSettings = {}, onSessionTitle,
         onUndo={handleRequestUndo}
         onRetry={handleRetry}
         onNewChat={handleNewChat}
+        streamStatusMap={streamStatusMap}
+        titleForSession={titleHint}
+        waitingFor={waitingDependency.value}
+        onWaitingForChange={waitingDependency.set}
+        heldWait={heldWait ? { title: heldWait.dependsOnTitle } : null}
+        onCancelWait={cancelHeldWait}
       />
     );
   }

package/src/client/components/workspace/editor/PluginRail.tsx

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The editor column's switcher: files, or one of the plugins that took the
+ * column over.
+ *
+ * The `panel` slot is a TAKEOVER — the plugin draws the whole column, with no tab
+ * strip, no file tree and no chrome — so a file tab cannot represent it and the
+ * tab strip cannot switch to it. This narrow strip is that switch, and it is why
+ * the slot is reachable at all: until it existed the slot was registered and
+ * never rendered (`activeEditorPanelKey` was a hard-coded `null`), so a plugin
+ * like `session-info` shipped a Scratchpad nobody could open.
+ *
+ * Two rules:
+ *
+ * - **Nothing is drawn when no plugin contributes a `panel`.** A rail with one
+ *   button would be a control that only ever says "you are already here", so a
+ *   Kabmo with no such plugin looks exactly as it did before the slot.
+ * - **Files is the first entry and always present**, because the takeover has to
+ *   be reversible: without it a plugin that owns the column would leave no way
+ *   back to the editor.
+ */
+
+import { Files } from 'lucide-preact';
+import { PluginMark } from '@/client/components/settings/categories/panel-plugins/PluginMark';
+import type { ResolvedPluginPanel } from '@/client/components/workspace/plugin-panel/resolve';
+
+interface EditorPluginRailProps {
+  /** The `plugin:<id>` whose panel owns the column, or null for the files view. */
+  activeKey: string | null;
+  onSelect: (panelKey: string | null) => void;
+  plugins: readonly ResolvedPluginPanel[];
+}
+
+export function EditorPluginRail({ activeKey, onSelect, plugins }: EditorPluginRailProps) {
+  if (plugins.length === 0) return null;
+
+  const entryClass = (active: boolean) =>
+    `relative w-full h-9 flex items-center justify-center transition-colors border-l-2 ${
+      active ? 'text-ink border-ink bg-ink/5' : 'text-ink/40 border-transparent hover:text-ink hover:bg-ink/5'
+    } cursor-pointer`;
+
+  return (
+    <nav
+      aria-label="Editor panel views"
+      className="w-9 flex-shrink-0 border-r border-ink/10 bg-paper flex flex-col items-center py-2 space-y-1 z-10"
+    >
+      <button
+        type="button"
+        className={entryClass(activeKey === null)}
+        onClick={() => onSelect(null)}
+        title="Files"
+        aria-label="Files"
+        aria-pressed={activeKey === null}
+      >
+        <Files size={16} />
+      </button>
+      {plugins.map((plugin) => {
+        const active = activeKey === plugin.panelKey;
+        return (
+          <button
+            key={plugin.panelKey}
+            type="button"
+            className={entryClass(active)}
+            onClick={() => onSelect(plugin.panelKey)}
+            title={plugin.title}
+            aria-label={plugin.title}
+            aria-pressed={active}
+          >
+            <PluginMark name={plugin.name} iconUrl={plugin.iconUrl} size={16} />
+          </button>
+        );
+      })}
+    </nav>
+  );
+}

package/src/client/components/workspace/editor/index.tsx

@@ -271,6 +271,7 @@ export function Editor({
     );
   }
 
+
   if (openedFiles.length === 0) {
     return (
       <div className={`flex flex-col h-full bg-canvas items-center justify-center text-ink/40 ${className}`}>

package/src/client/components/workspace/editor/plugin-rail.test.tsx

@@ -0,0 +1,126 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The editor column's plugin slot (`app.panel`).
+ *
+ * The slot was registered and NEVER rendered: `WorkspacePanels` passed
+ * `activeEditorPanelKey={null}` hard-coded and no call site ever wrote it, so a
+ * plugin that shipped two panels — `marketplace/plugins/session-info` registers a
+ * `rightPanel` and a `panel` — had exactly one of them reachable. These cases pin
+ * the two halves that make it reachable: a rail that can switch to it, and a
+ * column that stays open for it with no file behind it.
+ *
+ * The rail is a plain component, so it is asserted directly. The open/closed
+ * decision belongs to the layout and is asserted through `showEditor`'s own rule
+ * (`openedFiles.length > 0 || an editor plugin is chosen`), which this file
+ * reproduces rather than mounts the whole desktop for.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import { act } from 'preact/test-utils';
+import { EditorPluginRail } from '@/client/components/workspace/editor/PluginRail';
+import type { ResolvedPluginPanel } from '@/client/components/workspace/plugin-panel/resolve';
+import { installDomGlobals } from '@/test-support/pristine-globals';
+
+let container: HTMLElement | null = null;
+
+// Installed per CASE: another suite's teardown can strip `window` mid-file when
+// the runner interleaves files, and this hook's first render would then throw.
+beforeEach(() => {
+  installDomGlobals(new Window({ url: 'http://127.0.0.1:1' }));
+});
+
+function panel(pluginId: string, title: string): ResolvedPluginPanel {
+  return {
+    panelKey: `plugin:${pluginId}`,
+    pluginId,
+    name: pluginId,
+    title,
+    Component: () => null,
+  };
+}
+
+async function mountRail(props: {
+  activeKey: string | null;
+  plugins: ResolvedPluginPanel[];
+  onSelect?: (key: string | null) => void;
+}) {
+  const host = document.createElement('div');
+  document.body.appendChild(host);
+  container = host;
+  await act(async () => {
+    render(
+      h(EditorPluginRail, {
+        activeKey: props.activeKey,
+        onSelect: props.onSelect ?? (() => {}),
+        plugins: props.plugins,
+      }),
+      host,
+    );
+  });
+}
+
+const buttons = () =>
+  [...(container?.querySelectorAll('nav[aria-label="Editor panel views"] button') ?? [])].map((el) => ({
+    label: el.getAttribute('aria-label'),
+    pressed: el.getAttribute('aria-pressed'),
+  }));
+
+afterEach(() => {
+  if (container) {
+    render(null, container);
+    container.remove();
+    container = null;
+  }
+});
+
+describe('editor plugin rail', () => {
+  test('draws nothing when no plugin took the column over', async () => {
+    await mountRail({ activeKey: null, plugins: [] });
+    // A rail with only "Files" would be a control that never changes anything,
+    // so a Kabmo without such a plugin looks exactly as it did.
+    expect(container!.querySelector('nav')).toBeNull();
+  });
+
+  test('offers Files and every takeover, with the active one pressed', async () => {
+    await mountRail({ activeKey: 'plugin:session-info', plugins: [panel('session-info', 'Scratchpad')] });
+    expect(buttons()).toEqual([
+      { label: 'Files', pressed: 'false' },
+      { label: 'Scratchpad', pressed: 'true' },
+    ]);
+  });
+
+  test('Files is always an entry, so a takeover is reversible', async () => {
+    const selected: (string | null)[] = [];
+    await mountRail({
+      activeKey: 'plugin:demo',
+      plugins: [panel('demo', 'Demo')],
+      onSelect: (key) => selected.push(key),
+    });
+    const files = [...container!.querySelectorAll('nav button')].find(
+      (el) => el.getAttribute('aria-label') === 'Files',
+    ) as HTMLButtonElement;
+    await act(async () => files.click());
+    // `null`, not a sentinel: the layout's own state spells "no plugin" that way.
+    expect(selected).toEqual([null]);
+  });
+
+  test('choosing a takeover reports its panel key', async () => {
+    const selected: (string | null)[] = [];
+    await mountRail({
+      activeKey: null,
+      plugins: [panel('demo', 'Demo')],
+      onSelect: (key) => selected.push(key),
+    });
+    const takeover = [...container!.querySelectorAll('nav button')].find(
+      (el) => el.getAttribute('aria-label') === 'Demo',
+    ) as HTMLButtonElement;
+    await act(async () => takeover.click());
+    expect(selected).toEqual(['plugin:demo']);
+  });
+});

package/src/client/components/workspace/model-dropdown/groups.test.ts

@@ -0,0 +1,60 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The picker's derived grouping, with the row shapes that have actually arrived.
+ *
+ * The case that matters is a model entry with NO provider. `/api/models` is a
+ * projection of omp's registry, and a partial entry (a custom provider whose
+ * field never landed) reached `buildPickerGroups` as `undefined` and threw
+ * `model.provider.toUpperCase` — which took the whole composer down, because
+ * the model pill renders inside `ChatInput`. Measured: eight `compact composer`
+ * cases failed with exactly that stack, in a suite that never mentions models.
+ *
+ * The guard is `String(… ?? 'unknown')`, so the row stays visible under a
+ * stable section instead of vanishing from a list the user may have selected.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { buildPickerGroups } from '@/client/components/workspace/model-dropdown/groups';
+import type { AIModelOption } from '@/shared/types';
+
+function model(overrides: Partial<AIModelOption> & { id: string }): AIModelOption {
+  return { name: overrides.id, provider: 'p', ...overrides } as AIModelOption;
+}
+
+describe('buildPickerGroups', () => {
+  test('a row with no provider does not throw, and keeps its section', () => {
+    const rows = [model({ id: 'a' }), { id: 'b', name: 'B' } as AIModelOption];
+    const groups = buildPickerGroups(rows, '', {}, [], []);
+    expect(Object.keys(groups.byProvider).sort()).toEqual(['P', 'UNKNOWN']);
+    expect(groups.byProvider.UNKNOWN?.map((m) => m.id)).toEqual(['b']);
+    // It is still a row the user can see and pick.
+    expect(groups.visibleFlatList.map((m) => m.id).sort()).toEqual(['a', 'b']);
+  });
+
+  test('an empty provider string lands in the same section as a missing one', () => {
+    const groups = buildPickerGroups([model({ id: 'a', provider: '' })], '', {}, [], []);
+    expect(Object.keys(groups.byProvider)).toEqual(['UNKNOWN']);
+  });
+
+  test('a search still narrows a guarded row rather than crashing on it', () => {
+    const rows = [model({ id: 'a', name: 'Alpha' }), { id: 'b', name: 'Beta' } as AIModelOption];
+    const groups = buildPickerGroups(rows, 'beta', {}, [], []);
+    expect(groups.filtered.map((m) => m.id)).toEqual(['b']);
+  });
+
+  test('rows group by upper-cased provider and keep catalog order', () => {
+    const groups = buildPickerGroups(
+      [model({ id: 'a', provider: 'anthropic' }), model({ id: 'b', provider: 'Anthropic' })],
+      '',
+      {},
+      [],
+      [],
+    );
+    expect(Object.keys(groups.byProvider)).toEqual(['ANTHROPIC']);
+    expect(groups.byProvider.ANTHROPIC?.map((m) => m.id)).toEqual(['a', 'b']);
+  });
+});

package/src/client/components/workspace/model-dropdown/groups.ts

@@ -75,7 +75,13 @@ export function buildPickerGroups(
 
   const byProvider: Record<string, AIModelOption[]> = {};
   for (const model of filtered) {
-    const provider = model.provider.toUpperCase();
+    // `String(…)` rather than a bare call: this is the composer's picker, and a
+    // row whose provider never landed must not take the chat input down. Rows
+    // that reach here from `/api/models` are normalized in `toOption`; this is
+    // the guard for every other caller (a plugin panel, a stored snapshot).
+    // An EMPTY string is the same problem as a missing one — it would render a
+    // heading with no name — so both land in `unknown`.
+    const provider = String(model.provider || 'unknown').toUpperCase();
     (byProvider[provider] ??= []).push(model);
   }
 

package/src/client/components/workspace/model-dropdown/use-catalog.ts

@@ -12,8 +12,14 @@ function toOption(m: ModelEntry): AIModelOption {
   const cost = m.cost;
   return {
     id: m.id,
-    name: m.name,
-    provider: m.provider,
+    name: m.name || m.id,
+    // A row without a provider still has to render. `/api/models` is read from
+    // omp's registry, and a partial entry (a custom provider whose `provider`
+    // field never landed) used to crash the whole picker — `buildPickerGroups`
+    // upper-cased `undefined` and the composer's model pill took the chat input
+    // down with it. `unknown` keeps the row visible and gives it a stable
+    // section instead of dropping a model the user may have selected.
+    provider: m.provider || 'unknown',
     contextWindow: m.contextWindow,
     thinkingLevel: ladder[0] ?? 'off',
     thinkingLevels: ladder,

package/src/client/components/workspace/panels/builtin.tsx

@@ -22,6 +22,7 @@ import {
   RIGHT_PANEL_TYPES,
   type RightPanelType,
 } from '@/shared/lib/workspace/right-panels';
+import type { AgentStreamStatus } from '@/shared/lib/chat/omp/status';
 
 /**
  * Props a panel BODY may receive.
@@ -51,6 +52,13 @@ export interface PanelBodyProps {
   onClose?: () => void;
   /** The phone's drawer hides a view's own header; the desktop stack does not. */
   showHeader?: boolean;
+  /**
+   * The boot settings snapshot, for the views that read it (the session list
+   * passes it to its own Settings modal and to the prewarm's access mode).
+   */
+  appSettings?: Record<string, any>;
+  /** The live agent stream status, for the session list's wordmark badge. */
+  streamStatus?: AgentStreamStatus;
 }
 
 /**

package/src/client/components/workspace/plugin-panel/catalog.tsx

@@ -0,0 +1,237 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The panel catalog: one list, two columns.
+ *
+ * The built-in views and the installed plugins travel the SAME path — one
+ * merged list, one enablement set, one entry shape — so the activity bars, the
+ * desktop panel stacks and the phone's tab strip cannot disagree about what
+ * exists or what it is called.
+ *
+ * Two axes are decided here and nowhere else:
+ *
+ * - **SIDE.** A built-in view is `right` by construction; a plugin panel is
+ *   `left` only while the user placed it there (`left-dock.ts`). A caller asks
+ *   for the column it draws (`usePanelCatalog('left')`), or for everything
+ *   (`usePanelCatalog('all')`, which is what the phone's drawer reads — a panel
+ *   placed on the left must stay reachable on a phone, which has one drawer).
+ * - **ORDER.** The right column keeps the user's dragged order
+ *   (`omp_right_panel_order`); the left column is ordered by the placement list
+ *   itself, because placing a panel there IS the arrangement.
+ *
+ * The left column also carries a view of its own — `sessions`, the session list
+ * that used to BE the column. It is a catalog entry like any other so the bar
+ * draws it with the same button, the same active state and the same visibility
+ * menu; it is never removable, because a chat with no way back to the session
+ * list is a dead end.
+ */
+
+import { lazy } from 'preact/compat';
+import type { ReactNode } from 'preact/compat';
+import { MessagesSquare } from 'lucide-preact';
+import { useMemo } from 'preact/hooks';
+import { usePanelRegistry, usePanelSlots } from '@/client/hooks/workspace/panel-registry';
+import { usePanelOrder } from '@/client/hooks/workspace/panel-order';
+import { useLeftDock } from '@/client/hooks/workspace/left-dock';
+import { PluginIdProvider } from '@kabmo-labs/kabmo-ui';
+import { rightPanelOf } from '@/client/lib/plugins/slots';
+import { pluginEnablementKey, pluginPanelKey } from '@/shared/lib/workspace/panel-ids';
+import { SESSIONS_VIEW_ID, panelSideOf, type PanelSide } from '@/shared/lib/workspace/left-dock';
+import { resolvePluginPanelWidths } from '@/shared/lib/workspace/panel-widths';
+import { DEFAULT_LEFT_PANEL_WIDTH, MIN_LEFT_PANEL_WIDTH } from '@/shared/lib/workspace/sidebar-width';
+import {
+  enabledBuiltinPanels,
+  type BuiltinPanelView,
+  type PanelBodyProps,
+} from '@/client/components/workspace/panels/builtin';
+
+/** `left`, `right`, or both — `all` is the phone's drawer and the settings pane. */
+export type PanelCatalogSide = PanelSide | 'all';
+
+/** One panel in the merged catalog — a built-in view, the dock's view, or a plugin. */
+export interface ResolvedPanel {
+  /** The panel id: a bare built-in view id, `sessions`, or `plugin:<pluginId>`. */
+  id: string;
+  /** The column it is drawn in. */
+  side: PanelSide;
+  /** The activity bar's tooltip. */
+  title: string;
+  /** The phone's chip label. */
+  label: string;
+  /** A built-in view's own icon; a plugin draws its mark instead. */
+  icon?: ReactNode;
+  /** A plugin's icon URL, when its manifest declares one. */
+  iconUrl?: string;
+  /** The plugin's display name; empty for a built-in view. */
+  name: string;
+  builtin: boolean;
+  requiresWorkspace: boolean;
+  liveWhileHidden: boolean;
+  minWidth: number;
+  /** The px width the view opens at before the group's area is measured. */
+  defaultWidth: number;
+  defaultFraction: number;
+  /** Render the body. One call, so every layout draws a view the same way. */
+  render: (props: PanelBodyProps) => ReactNode;
+}
+
+const SessionsView = lazy(() =>
+  import('@/client/components/layout/session-sidebar/SessionsView').then((m) => ({ default: m.SessionsView })),
+);
+
+/** The dock's own view. Never removable, never placed anywhere else. */
+const SESSIONS_PANEL: ResolvedPanel = {
+  id: SESSIONS_VIEW_ID,
+  side: 'left',
+  title: 'Sessions',
+  label: 'Sessions',
+  icon: <MessagesSquare size={16} />,
+  name: '',
+  builtin: true,
+  // The list is the workspace's own navigation: it reads folders and sessions,
+  // not the working tree of the active folder.
+  requiresWorkspace: false,
+  liveWhileHidden: false,
+  minWidth: MIN_LEFT_PANEL_WIDTH,
+  defaultWidth: DEFAULT_LEFT_PANEL_WIDTH,
+  // The left column is px-sized (a session list does not get more useful on a
+  // wider monitor), so the fraction is only what a phone's drawer would use.
+  defaultFraction: 0.25,
+  // The column's title row and footer are NOT this view's: `LeftColumn` draws
+  // them, so the rail and the list sit under ONE title and above ONE strip.
+  render: (props) => <SessionsView className={props.className} appSettings={props.appSettings} />,
+};
+
+/** A built-in view's catalog entry, with its renderer closed over its component. */
+function builtinEntry(view: BuiltinPanelView): ResolvedPanel {
+  const View = view.Component;
+  return {
+    id: view.id,
+    // A built-in view is a RIGHT-column view by construction: its floor, width
+    // slot and workspace gate were all declared for that column.
+    side: 'right',
+    title: view.title,
+    label: view.label,
+    icon: view.icon,
+    name: '',
+    builtin: true,
+    requiresWorkspace: view.requiresWorkspace,
+    liveWhileHidden: view.liveWhileHidden === true,
+    minWidth: view.minWidth,
+    defaultWidth: view.defaultWidth,
+    defaultFraction: view.defaultFraction,
+    render: (props) => <View {...props} />,
+  };
+}
+
+/**
+ * The panel catalog the activity bars and the panel stacks render.
+ *
+ * `side` selects the column. `all` is deliberately a first-class value rather
+ * than "no filter": the phone's drawer and the settings pane both need every
+ * panel in one list, and a caller that forgot to pass a side would otherwise get
+ * a silently halved catalog.
+ */
+export function usePanelCatalog(side: PanelCatalogSide = 'right'): ResolvedPanel[] {
+  const { panels, disabledPanels } = usePanelRegistry();
+  const { slots } = usePanelSlots();
+  const { apply } = usePanelOrder();
+  const dock = useLeftDock();
+
+  return useMemo(() => {
+    const out: ResolvedPanel[] = [];
+
+    if (side !== 'left') {
+      for (const view of enabledBuiltinPanels(disabledPanels)) out.push(builtinEntry(view));
+    }
+
+    const placed = new Map(dock.panels.map((id, index) => [id, index]));
+    const left: ResolvedPanel[] = [];
+
+    for (const panel of panels) {
+      const entry = slots.get(panel.pluginId);
+      const Component = entry ? rightPanelOf(entry) : undefined;
+      if (!Component) continue;
+      const key = pluginPanelKey(panel.pluginId, 'rightPanel');
+      if (disabledPanels.includes(pluginEnablementKey(panel.pluginId))) continue;
+      const size = entry?.sizing.rightPanel;
+      const widths = resolvePluginPanelWidths({ ...size });
+      const resolved: ResolvedPanel = {
+        id: key,
+        // Where the USER put it, keyed per PANEL INSTANCE. A plugin that also
+        // contributes a takeover has a second, independent key, so placing this
+        // one on the left never moves that one.
+        side: panelSideOf(key, dock),
+        title: `${entry?.titles.rightPanel ?? panel.name} — ${panel.name}`,
+        label: entry?.titles.rightPanel ?? panel.name,
+        name: panel.name,
+        builtin: false,
+        // A plugin reads whatever the host published and draws what it can, so
+        // gating it on a workspace folder would hide a panel that works.
+        requiresWorkspace: false,
+        liveWhileHidden: false,
+        minWidth: widths.min,
+        defaultWidth: widths.px,
+        defaultFraction: widths.fraction,
+        ...(panel.iconUrl ? { iconUrl: panel.iconUrl } : {}),
+        // Wrapped so the kit's participant hooks resolve THIS plugin's id while
+        // its panel renders — the scope is what `useRpc`/`useRealtime` read.
+        render: (props) => (
+          <PluginIdProvider pluginId={panel.pluginId}>
+            <Component sessionId={props.sessionId ?? null} workspacePath={null} />
+          </PluginIdProvider>
+        ),
+      };
+      // `editor` is not a column this catalog draws: the takeover has its own
+      // list (`usePanelSlotPlugins`) and its own rail in the editor column.
+      if (resolved.side === 'editor') continue;
+      if (resolved.side === 'left') left.push(resolved);
+      else if (side !== 'left') out.push(resolved);
+    }
+
+    if (side !== 'right') {
+      // The dock's own view first, then the placed plugins in PLACEMENT order:
+      // on the left, putting a panel there IS the arrangement, so the right
+      // column's dragged order would be a second answer to the same question.
+      left.sort((a, b) => (placed.get(a.id) ?? 0) - (placed.get(b.id) ?? 0));
+      out.unshift(SESSIONS_PANEL, ...left);
+    }
+
+    return side === 'left' ? out : apply(out);
+  }, [panels, slots, disabledPanels, apply, dock, side]);
+}
+
+/** Whether a panel id names the dock's own session list. */
+export function isSessionsPanel(id: string): boolean {
+  return id === SESSIONS_VIEW_ID;
+}
+
+/**
+ * Which view the dock actually shows, given the stored selection.
+ *
+ * Three answers, and they are different states a blank column would conflate:
+ *
+ * - the stored id is a LEFT panel → draw it;
+ * - the stored id names a panel that still exists but lives on the RIGHT (the
+ *   user moved it back, or it was never placed here) → the dock's own view,
+ *   because that is not an error;
+ * - the stored id names nothing at all (uninstalled, switched off) → the id is
+ *   returned as-is so the dock can say WHY, which is what the panel position's
+ *   notice exists for.
+ */
+export function useLeftDockView(stored: string, railEnabled: boolean): string {
+  const left = usePanelCatalog('left');
+  const all = usePanelCatalog('all');
+  return useMemo(() => {
+    // With no rail there is no control that switches views, so the dock shows
+    // its own view: leaving a plugin panel up would strand the user there with
+    // no way back to the session list.
+    if (!railEnabled) return SESSIONS_VIEW_ID;
+    if (left.some((panel) => panel.id === stored)) return stored;
+    if (all.some((panel) => panel.id === stored)) return SESSIONS_VIEW_ID;
+    return stored;
+  }, [left, all, stored, railEnabled]);
+}