dsh-better-sidebar 0.10.0

package/lib/types/client/service.d.ts

@@ -0,0 +1,214 @@
+/**
+ * The BetterSidebar client service: a registry that external plugins use
+ * to contribute sidebar tab types and file previewers. The service is
+ * published to the cordis context as `ctx.betterSidebar` (see
+ * {@link ../context-types.ts}); consumers declare it in `inject` and call
+ * `registerTab` / `registerFileViewer`, both returning a disposer that
+ * cordis auto-invokes on fiber disposal (HMR-safe).
+ *
+ * Design notes:
+ * - The registry is synchronous-snapshot (Map + listener set) so React
+ *   can read it through `useSyncExternalStore` without tearing.
+ * - `dedupeKey` unifies the three open-tab strategies the builtins used to
+ *   hardcode: single-instance (`() => type`), per-path (`tab => tab.path`),
+ *   and per-id (`tab => tab.id` for diff tabs whose id is change-derived).
+ *   `single: true` is sugar for `dedupeKey: () => id`.
+ * - `createTab` lets a descriptor own tab instantiation (the terminal
+ *   builtin uses it to mint `terminal:<n>` ids and bump `nextTerminal`).
+ * - `matchFileViewer` walks descriptors in priority order (desc, stable):
+ *   per descriptor it tries `detect` first (when `head` bytes are given),
+ *   then `exts`; `exts: []` is a catch-all that matches any path.
+ */
+import type { ReactNode } from 'react';
+import type { Context } from '../context-types.ts';
+import { type SidebarState, type SidebarStore, type SidebarTab } from './state.ts';
+import type { SessionScope } from './api.ts';
+/** One declarative boolean setting of a tab/viewer, rendered as a nested
+ *  switch row in the Side card settings page (e.g. the Subagent page's
+ *  "auto-open when a subagent appears"). */
+export interface SidebarSettingToggle {
+    /** The SidebarPrefs field this toggle reads and writes ('autoOpenSubagent'). */
+    key: string;
+    /** Row title (i18n friendly: string or () => string). */
+    title: string | (() => string);
+    /** Row description (i18n friendly). */
+    desc?: string | (() => string);
+}
+/** Declarative settings of one registered tab or file viewer. */
+export interface SidebarSettingsDeclaration {
+    /**
+     * Extra boolean toggles rendered under the feature's own row in the
+     * settings page (only while the feature is enabled). Keys must be fields
+     * of the host's PrefsSchema (built-ins: 'autoOpenSubagent',
+     * 'agentTerminalTools'); unknown keys are dropped by the settings seam.
+     */
+    toggles?: readonly SidebarSettingToggle[];
+}
+/** Props every tab component receives (builtins and external alike). */
+export interface TabComponentProps {
+    ctx: Context;
+    store: SidebarStore;
+    scope: SessionScope;
+    tab: SidebarTab;
+    /** Whether this tab is the active one AND the panel is open (live views pause otherwise). */
+    visible: boolean;
+    /** The explorer's expanded directory set (ExplorerView). */
+    expanded?: string[];
+    onToggleDir?: (path: string) => void;
+    onReferenceFile?: (path: string) => void;
+    onOpenFile?: (path: string) => void;
+    onOpenDiff?: (tab: SidebarTab) => void;
+    onSubagentJump?: (childSessionId: string) => void;
+}
+/** Describes one kind of sidebar tab (builtins register themselves too). */
+export interface TabDescriptor {
+    /** Unique id; also the `SidebarTab.type` value (`'explorer'`, `'my-plugin:db'`). */
+    id: string;
+    title: string | (() => string);
+    icon?: ReactNode | ((size: number) => ReactNode);
+    /** + menu sort order (ascending); default 100. */
+    order?: number;
+    /** Hide from the + menu (the editor tab is opened by file-open, not by the menu). */
+    hidden?: boolean;
+    /**
+     * + menu disabled predicate (e.g. terminal at capacity). Receives the
+     * session scope and the live sidebar state (counts, expansions).
+     */
+    available?: (ctx: Context, scope: SessionScope, state: SidebarState) => boolean;
+    /**
+     * Single-instance sugar: `true` is shorthand for `dedupeKey: () => id`
+     * (opening the tab focuses an existing one of the same type instead of
+     * creating a duplicate). An explicit `dedupeKey` always wins when both
+     * are given. Builtins: explorer/git/subagent use `single: true`.
+     */
+    single?: boolean;
+    /**
+     * If provided, opening a tab whose `dedupeKey(tab)` matches an existing
+     * tab's key focuses the existing one instead of creating a new one.
+     * Returning `undefined` means "no dedup — always open a new tab".
+     * Builtins: editor uses `tab => tab.path`; diff uses `tab => tab.id`
+     * (openDiffTab mints change-derived ids).
+     */
+    dedupeKey?: (tab: SidebarTab) => string | undefined;
+    /**
+     * Custom tab creation (minting the `SidebarTab` and any state patches).
+     * Return `null` to refuse creation. The terminal builtin uses this to
+     * mint `terminal:<n>` ids and bump `nextTerminal`.
+     * When omitted, a default `{ id, type, title }` tab is created.
+     */
+    createTab?: (state: SidebarState) => {
+        tab: SidebarTab;
+        patch?: Partial<SidebarState>;
+    } | null;
+    /**
+     * Declarative settings shown in the Side card settings page: every
+     * registered tab gets an enable/disable switch (icon + title + id), and
+     * `settings.toggles` adds nested switches tied to SidebarPrefs fields
+     * (e.g. the subagent tab's 'autoOpenSubagent').
+     */
+    settings?: SidebarSettingsDeclaration;
+    component: (props: TabComponentProps) => ReactNode;
+}
+/** How the host loads a file's bytes for one viewer. */
+export type FileFetchStrategy = 'none' | 'fsRead' | 'mediaUrl' | 'custom' | 'binary-download';
+/** Props every file viewer component receives. */
+export interface FileViewerProps {
+    ctx: Context;
+    store: SidebarStore;
+    scope: SessionScope;
+    path: string;
+    title: string;
+    /** The matching descriptor's id (`'code'`, `'my-plugin:csv'`). */
+    viewerId: string;
+    /** fsRead text content (fetchStrategy='fsRead'). */
+    content?: string;
+    truncated?: boolean;
+    /** mediaUrl for the path (fetchStrategy='mediaUrl'). */
+    mediaUrl?: string;
+    /** custom load() return value (fetchStrategy='custom'). */
+    customData?: unknown;
+}
+/** Describes one file previewer (builtins register themselves too). */
+export interface FileViewerDescriptor {
+    /** Unique id (`'image'`, `'pdf'`, `'my-plugin:csv'`). */
+    id: string;
+    /** Display name for the settings inventory (falls back to `id` when absent). */
+    title?: string | (() => string);
+    /** Icon shown in the settings inventory. */
+    icon?: ReactNode | ((size: number) => ReactNode);
+    /** Lowercase extensions without leading dot (`['png','jpg']`). `[]` = match any (catch-all). */
+    exts: readonly string[];
+    /** Higher wins; default 0. Builtins use 0; the catch-all `code` viewer uses -100. */
+    priority?: number;
+    fetchStrategy: FileFetchStrategy;
+    /**
+     * Content sniff: when `head` bytes are available the descriptor's `detect`
+     * is consulted before its `exts` (per-descriptor, in priority order).
+     */
+    detect?: (path: string, head: Uint8Array) => boolean;
+    /** fetchStrategy='custom' loader. */
+    load?: (path: string, scope: SessionScope) => Promise<unknown>;
+    /**
+     * Declarative settings shown in the Side card settings page: every
+     * registered viewer gets an enable/disable switch (icon + title + exts).
+     */
+    settings?: SidebarSettingsDeclaration;
+    component: (props: FileViewerProps) => ReactNode;
+}
+/** The registry service published as `ctx.betterSidebar`. */
+export interface BetterSidebarService {
+    registerTab(descriptor: TabDescriptor): () => void;
+    registerFileViewer(descriptor: FileViewerDescriptor): () => void;
+    getTabs(): readonly TabDescriptor[];
+    getFileViewers(): readonly FileViewerDescriptor[];
+    /** Find a tab descriptor by id (undefined if not registered). */
+    getTab(id: string): TabDescriptor | undefined;
+    /**
+     * Whether a tab type is enabled in the side card prefs. An absent
+     * `tabsEnabled[id]` entry means enabled — only an explicit `false`
+     * disables the type (hidden from the + menu, `openTab` refuses, and
+     * derived flows gate on it).
+     */
+    isTabEnabled(id: string): boolean;
+    /** Whether a file viewer is enabled (absent `viewersEnabled[id]` = enabled). */
+    isViewerEnabled(id: string): boolean;
+    /**
+     * Find a file viewer for a path (priority desc; detect first, then exts).
+     * Disabled viewers are skipped, so files fall through to the next match.
+     */
+    matchFileViewer(path: string, head?: Uint8Array): FileViewerDescriptor | undefined;
+    /**
+     * Open a tab (used by external tabs and the + menu). `title` overrides
+     * the descriptor's title when given (the editor tab shows the file name);
+     * when the descriptor provides `createTab` it mints the tab itself and
+     * `title`/`path`/`id` are ignored. `url` lands the tab with its `path`
+     * pre-set to the URL (the browser tab's navigation seed; the caller
+     * usually pairs it with a hostname `title`). A disabled tab type is a
+     * no-op.
+     *
+     * A CONTENT open (a `path` or `url` seed) must land in sight: when the
+     * panel hosting the landing pane is collapsed, it is expanded
+     * automatically (the right panel by default, the bottom panel when the
+     * active pane lives there; on narrow viewports the merged drawer opens).
+     * Type-only opens (the + menu, agent-terminal auto-tabs) never expand —
+     * the panel behavior is their caller's business.
+     */
+    openTab(seed: {
+        type: string;
+        title?: string;
+        path?: string;
+        diff?: SidebarTab['diff'];
+        id?: string;
+        url?: string;
+    }): void;
+    /** Close a tab by id. */
+    closeTab(tabId: string): void;
+    /** Subscribe to registry changes (register/dispose). */
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * Create one BetterSidebar service bound to a store. The service owns the
+ * tab/viewer registries (Map + listener set) and proxies openTab/closeTab
+ * to the store's reducer. One instance per client plugin activation.
+ */
+export declare function createBetterSidebarService(store: SidebarStore): BetterSidebarService;

package/lib/types/client/split-pane.d.ts

@@ -0,0 +1,29 @@
+import type { ReactNode } from 'react';
+import type { SidebarState, SidebarTab, SplitNode } from './state.ts';
+import type { DropZone } from './state.ts';
+import { type NewTabOption, type TabDragPayload } from './TabBar.tsx';
+/** Actions the workbench needs (bound to the store by the sidebar shell). */
+export interface WorkbenchActions {
+    closeTab: (paneId: string, tabId: string) => void;
+    activateTab: (paneId: string, tabId: string) => void;
+    /** Make a pane the target of newly opened tabs (click focus). */
+    focusPane: (paneId: string) => void;
+    /** VSCode drag gesture: edge → split the target pane, center → merge. */
+    moveTabToEdge: (payload: TabDragPayload, toPane: string, zone: DropZone) => void;
+    /** Reorder within a pane (drop onto another tab inserts before it). */
+    moveTabBefore: (payload: TabDragPayload, toPane: string, beforeTabId: string) => void;
+    resizeSplit: (splitId: string, index: number, deltaFrac: number) => void;
+}
+/** The workbench: the split tree filling the sidebar body. `tree` selects
+ *  which tree renders (the right panel's by default; the bottom panel passes
+ *  `state.bottomSplits` — the actions route by pane id, so one action set
+ *  serves both). */
+export declare function Workbench(props: {
+    state: SidebarState;
+    tree?: SplitNode;
+    newTabOptions: NewTabOption[];
+    actions: WorkbenchActions;
+    onNewTab: (optionId: string) => void;
+    renderTab: (tab: SidebarTab, active: boolean, paneId: string) => ReactNode;
+    getTabIcon?: (tab: SidebarTab) => ReactNode;
+}): import("react").JSX.Element;

package/lib/types/client/state.d.ts

@@ -0,0 +1,322 @@
+/**
+ * Per-session sidebar state: the panel geometry, the split-pane workbench
+ * tree, open tabs, and the explorer expansion set. One state instance per
+ * conversation id, persisted to localStorage under `dsh-sidebar:v1:<id>` so
+ * a reload restores the exact layout of the session it belongs to — switching
+ * conversations swaps the whole state (memory + isolation).
+ *
+ * The split tree is a recursive structure: a leaf holds a tab group, a split
+ * divides the space row- or column-wise with fractional sizes. All tree
+ * operations are pure functions over the node, unit-tested in tests/state.spec.ts.
+ */
+import { type SidebarPrefs } from '../prefs-shared.ts';
+/**
+ * Tab type identifier. Builtins register their ids (explorer / git / editor
+ * / terminal / subagent / diff) through the sidebar service; external
+ * plugins register their own (e.g. `'my-plugin:db'`). Kept as `string` so
+ * the registry stays open.
+ */
+export type TabType = string;
+/** What a diff tab shows: a worktree/index change of one path, or one commit's full patch. */
+export type SidebarDiffRef = {
+    kind: 'worktree';
+    path: string;
+    staged: boolean;
+    untracked?: boolean;
+} | {
+    kind: 'commit';
+    hash: string;
+    hashFull: string;
+    subject: string;
+};
+/** One open tab. `path` carries the file (editor) or is absent (explorer/git);
+ *  `diff` carries the change a diff tab shows. */
+export interface SidebarTab {
+    id: string;
+    type: TabType;
+    title: string;
+    path?: string;
+    diff?: SidebarDiffRef;
+}
+/** A tab group. */
+export interface SidebarLeaf {
+    kind: 'leaf';
+    id: string;
+    tabs: SidebarTab[];
+    active: string | null;
+}
+/** A recursive split between child panes (fractional sizes summing to 1). */
+export interface SidebarSplit {
+    kind: 'split';
+    id: string;
+    dir: 'row' | 'col';
+    sizes: number[];
+    children: SplitNode[];
+}
+export type SplitNode = SidebarLeaf | SidebarSplit;
+/** The full per-session state. */
+export interface SidebarState {
+    panelOpen: boolean;
+    width: number;
+    /** The pane receiving newly opened tabs (last pane the user touched).
+     *  Pane ids are globally unique across BOTH trees (shared uid counter), so
+     *  one field resolves into either tree — see {@link treeOf}. */
+    activePane: string | null;
+    /** Monotonic terminal tab counter (ids survive reloads). */
+    nextTerminal: number;
+    /** Monotonic browser tab counter (ids survive reloads; mirrors nextTerminal). */
+    nextBrowser: number;
+    /** Explorer expansion set (absolute directory paths). */
+    expanded: string[];
+    /** The right sidebar's split tree (the original workbench). */
+    splits: SplitNode;
+    /** Whether the bottom panel (a second, independent workbench) is open. */
+    bottomOpen: boolean;
+    /** The bottom panel's height (clamped to the contract range). */
+    bottomHeight: number;
+    /**
+     * Whether the bottom panel has been expanded at least once in this
+     * session — the FIRST expansion tries to auto-open a terminal tab (gated
+     * on the bottomPanelAutoTerminal pref); later expansions never do.
+     */
+    bottomOpenedOnce: boolean;
+    /** The bottom panel's own split tree (panes/tabs live only in ONE tree;
+     *  tabs never cross panels — the two panels only share panel-size drags). */
+    bottomSplits: SplitNode;
+}
+export declare const PANEL_MIN = 280;
+export declare const PANEL_MAX = 640;
+export declare const PANEL_DEFAULT = 400;
+export declare const TAB_MAX_WIDTH = 160;
+/** Bottom panel geometry contract (mirrors the width contract; the upper
+ * bound is the viewport, enforced by {@link setBottomHeight}). */
+export declare const BOTTOM_MIN = 120;
+export declare const BOTTOM_DEFAULT = 220;
+/** A fresh default state: one explorer tab in one pane, open per the caller's
+ * preference. `width` is the caller's preferred panel width (default
+ * PANEL_DEFAULT) and `panelOpen` whether the panel starts expanded (default
+ * true); the store seeds new sessions from the user's side card prefs.
+ * `seedExplorer` places the default explorer tab — the store passes false
+ * when the user disabled the explorer tab type in settings, so a fresh
+ * session starts with an empty pane instead of a tab they turned off. */
+export declare function makeDefaultState(width?: number, panelOpen?: boolean, seedExplorer?: boolean): SidebarState;
+/** Which tree owns a pane/split id: 'bottomSplits' when the id lives in the
+ *  bottom panel's tree, else 'splits' (the right panel's tree). Ids are
+ *  globally unique (the shared uid counter), so an id in neither tree falls
+ *  back to the right tree, where tree operations no-op on a missing node —
+ *  the pre-bottom-panel behavior. */
+export declare function treeOf(state: SidebarState, id: string): 'splits' | 'bottomSplits';
+/** Walk the tree and apply `visit` to the leaf with the given id. */
+export declare function mapLeaf(node: SplitNode, paneId: string, visit: (leaf: SidebarLeaf) => void): SplitNode;
+/** The first leaf of the tree (fallback pane when activePane is gone). */
+export declare function firstLeaf(node: SplitNode): SidebarLeaf;
+/**
+ * Narrow-viewport migration: the bottom panel's tabs are thrown INTO the
+ * right sidebar — the "merged display" on mobile is the right panel alone,
+ * whose tab strips now carry the bottom tree's tabs (depth-first order,
+ * appended to the right tree's FIRST leaf). The bottom tree is emptied (its
+ * structure stays — the desktop bottom panel re-renders its welcome cards)
+ * and the panel closes. The active pane moves to the right tree's first
+ * leaf so every new tab lands in the visible panel.
+ *
+ * Idempotent: a bottom tree with no tabs and a closed panel returns the
+ * same reference. Runs when the viewport enters narrow (see the Sidebar
+ * shell); migrating is permanent for the session — the tabs now live in the
+ * right tree, exactly like the user "threw them in".
+ */
+export declare function migrateBottomTabs(state: SidebarState): SidebarState;
+/** Find the leaf containing a tab id, if any. */
+export declare function leafWithTab(node: SplitNode, tabId: string): SidebarLeaf | undefined;
+/** All leaves of the tree, depth-first. */
+export declare function allLeaves(node: SplitNode): SidebarLeaf[];
+/** Whether a tab exists anywhere in a state (either tree, any pane). */
+export declare function tabOpenIn(state: SidebarState, tabId: string): boolean;
+/** Replace a leaf with a split of it plus a fresh empty leaf. */
+export declare function splitLeafAt(node: SplitNode, paneId: string, dir: 'row' | 'col'): SplitNode;
+/**
+ * Split a leaf by inserting a fresh leaf holding `tab` beside it — the
+ * VSCode drag-to-edge gesture. `dir` is the split direction ('row' for
+ * left/right, 'col' for up/down); `front` places the new leaf first (left/
+ * up) or second (right/down).
+ * @returns the new tree plus the fresh leaf's id (the drop's active pane).
+ */
+export declare function insertLeafAt(node: SplitNode, paneId: string, dir: 'row' | 'col', tab: SidebarTab, front: boolean): {
+    node: SplitNode;
+    leafId: string;
+};
+/** Where a tab drop lands on a pane: an edge creates a split, center merges. */
+export type DropZone = 'left' | 'right' | 'up' | 'down' | 'center';
+/**
+ * The VSCode drag gesture: move a tab out of its pane and either merge it
+ * into the target pane (center) or split the target pane with the tab in a
+ * fresh leaf (edge). The source pane collapses when it empties.
+ *
+ * The panes may live in DIFFERENT trees (dragging a tab between the two
+ * panels): the tab then leaves its own tree and lands in the other one.
+ */
+export declare function moveTabToEdge(state: SidebarState, fromPane: string, tabId: string, toPane: string, zone: DropZone): SidebarState;
+/**
+ * Remove a leaf from the tree. A split left with one child promotes that
+ * child; removing the last leaf yields an empty leaf.
+ */
+export declare function removeLeafAt(node: SplitNode, paneId: string): SplitNode;
+/** Close a tab; an emptied leaf is removed (unless it is the only pane). */
+export declare function closeTab(state: SidebarState, paneId: string, tabId: string): SidebarState;
+/** Activate a tab in its pane (the pane's own tree). */
+export declare function activateTab(state: SidebarState, paneId: string, tabId: string): SidebarState;
+/** Update the display fields of one open tab (title / path) without
+ *  re-opening it. The browser tab persists its current URL and hostname
+ *  title through this reducer so a reload restores the visited page. A
+ *  missing tab id is a no-op. The tab may live in either tree. */
+export declare function patchTab(state: SidebarState, tabId: string, patch: {
+    title?: string;
+    path?: string;
+}): SidebarState;
+/**
+ * Land a tab in the active pane (or focus its existing instance by id).
+ * Dedup strategies (single-instance, per-path, per-change) are owned by the
+ * tab descriptor through {@link BetterSidebarService.openTab} / `dedupeKey`;
+ * this reducer only handles the id-based safety net (reconcile and
+ * openDiffTab already check existence before calling) and the landing
+ * itself — the service's dedupe path delegates here after its dedupeKey
+ * check misses.
+ *
+ * The active pane may live in EITHER tree (pane ids are globally unique):
+ * a stale id that survives in neither tree falls back to the right tree's
+ * first pane instead of swallowing the open.
+ */
+export declare function openTabInActivePane(state: SidebarState, tab: SidebarTab): SidebarState;
+/** Move a tab from one pane to another (insert at index; -1 appends).
+ *  The panes may live in DIFFERENT trees — dragging a tab between the two
+ *  panels removes it from its own tree and lands it in the other one. */
+export declare function moveTab(state: SidebarState, fromPane: string, tabId: string, toPane: string, index?: number): SidebarState;
+/** Split the active pane (or the pane containing the active tab). */
+export declare function splitPane(state: SidebarState, dir: 'row' | 'col'): SidebarState;
+/**
+ * Open a diff tab the VSCode way: an existing instance of the same change is
+ * focused wherever it lives; otherwise the tab joins the first pane that
+ * already holds diff tabs (diff panes are sticky — repeated clicks stack
+ * there); on the FIRST diff of a layout the source pane splits vertically so
+ * the diff lands in a fresh pane below it ("默认在下半栏新增一个").
+ *
+ * This is split-tree placement surgery, not registry dispatch: the diff tab
+ * descriptor's `dedupeKey` is `(tab) => tab.id`, and the existing-instance
+ * check below is exactly that rule — the two agree by construction (asserted
+ * in tests). Diff tabs minted by the Git view carry change-derived ids, so
+ * the id check is the per-change dedupe.
+ * @returns the new state, with the diff pane active.
+ */
+export declare function openDiffTab(state: SidebarState, sourcePaneId: string, tab: SidebarTab): SidebarState;
+/** Toggle the panel open/closed (opening restores the previous layout). */
+export declare function togglePanel(state: SidebarState): SidebarState;
+/** Toggle the bottom panel open/closed (independent of the right panel). */
+export declare function toggleBottomPanel(state: SidebarState): SidebarState;
+/** Set the panel width (clamped to the contract range; the upper bound is
+ * the viewport so the fullscreen expansion can fill the window). */
+export declare function setWidth(state: SidebarState, width: number): SidebarState;
+/** Set the bottom panel height (clamped to the contract range). The upper
+ * bound leaves the center column (the agent output area) at least PANEL_MIN
+ * tall — without the cap the bottom panel could swallow the whole viewport
+ * and squeeze the conversation to zero height. */
+export declare function setBottomHeight(state: SidebarState, height: number): SidebarState;
+/** Toggle a directory in the explorer expansion set. */
+export declare function toggleExpanded(state: SidebarState, path: string): SidebarState;
+/** Adjust one split divider: `i` is the left/top child index, delta in fractions. */
+export declare function resizeSplit(node: SplitNode, splitId: string, index: number, delta: number): SplitNode;
+/** State-level {@link resizeSplit} route: the divider may live in either
+ *  tree (split ids are globally unique). */
+export declare function resizeSplitIn(state: SidebarState, splitId: string, index: number, delta: number): SidebarState;
+/** Prefix marking a tab id as an agent-owned terminal (suffix is the uuid). */
+export declare const AGENT_TAB_PREFIX = "agent:";
+/** Whether a tab id refers to an agent-owned terminal. */
+export declare function isAgentTabId(tabId: string): boolean;
+/** Extract the agent terminal uuid from an `agent:<uuid>` tab id. */
+export declare function agentUuidOf(tabId: string): string;
+/** Build the sidebar tab id for one agent terminal uuid. */
+export declare function agentTabId(uuid: string): string;
+/**
+ * Reconcile the sidebar's agent-terminal tabs with the host's live list.
+ * The host pushes the current list of agent terminals (created by the model
+ * through the `terminal_create` tool) over a dedicated WebSocket; this
+ * reducer mirrors that list into tabs: new uuids get a tab, vanished uuids
+ * lose theirs. The agent owns the lifetime — the user closing a tab sends a
+ * WS close frame that kills the pty, which fires a change, which converges
+ * the view. Idempotent: a no-op when the lists already match.
+ * @param state - the current per-session sidebar state.
+ * @param agentTerminals - the live agent terminal snapshots from the host.
+ * @returns the next state (or the same reference if no change was needed).
+ */
+export declare function reconcileAgentTerminals(state: SidebarState, agentTerminals: ReadonlyArray<{
+    uuid: string;
+    title: string;
+}>): SidebarState;
+/** Immutable snapshot handed to React (replaced only on real changes). */
+export interface SidebarSnapshot {
+    sessionId: string | undefined;
+    state: SidebarState | undefined;
+    /**
+     * The current side card prefs. Carried IN the snapshot (not a separate
+     * subscription) so prefs changes re-render the consumers that gate on
+     * them — the + menu hides a tab type the moment its switch flips.
+     */
+    prefs: SidebarPrefs;
+}
+/** Default panel width for one viewport: the prefs percent of the window,
+ * clamped to the panel floor (a tiny percent must stay usable) and to the
+ * viewport (a large one must never cover the whole window). */
+export declare function defaultWidthFor(viewport: number, percent: number): number;
+/**
+ * Structural validation of one persisted state. A malformed or stale shape
+ * (older layouts, hand-edited storage) must fall back to the default instead
+ * of crashing the panel on every reload; the restored width is also clamped
+ * to the current viewport so a stale fullscreen width can never crush the
+ * app shell (margin-right larger than the window) or cover the whole screen.
+ * @returns a clean state, or undefined to fall back to the default.
+ */
+export declare function sanitizeState(parsed: unknown): SidebarState | undefined;
+/** The session-scoped store: one state per conversation, localStorage-backed. */
+export declare class SidebarStore {
+    private readonly bySession;
+    private snapshot;
+    private readonly listeners;
+    private persistTimer;
+    /** User-facing side card prefs seeding brand-new session states (defaults until the settings RPC resolves). */
+    private prefs;
+    /**
+     * Replace the side card prefs (the settings RPC result / settings page
+     * write). Notifies like any store change: the snapshot carries the prefs,
+     * so consumers that gate on enable switches (the + menu, derived flows)
+     * re-render with the new values immediately.
+     */
+    setPrefs(prefs: SidebarPrefs): void;
+    /** The current side card prefs (seeds new sessions; persisted states win). */
+    getPrefs(): SidebarPrefs;
+    /** Select a session (or none); loads its persisted state. */
+    setSession(sessionId: string | undefined): void;
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): SidebarSnapshot;
+    /** Mutate the current session's state (no-op without a session). */
+    update(mutator: (draft: SidebarState) => void): void;
+    /**
+     * Whether a tab still exists in its session's state. Views use this on
+     * unmount to tell "the tab was closed" (release the terminal now) from
+     * "the tree re-rendered / the conversation switched" (the tab is still
+     * open — keep the terminal alive through the host's reconnect grace).
+     * Checks the session's own map entry (the current snapshot may already
+     * point at another session when a conversation switch unmounts the old
+     * one's tabs).
+     */
+    tabOpen(sessionId: string, tabId: string): boolean;
+    /** Apply a pure reducer (returns the next state). */
+    reduce(reducer: (state: SidebarState) => SidebarState): void;
+    private schedulePersist;
+    private notify;
+}
+/**
+ * Create one sidebar store instance. Production code calls this only from
+ * the client plugin's `apply` (the instance is handed to components as a
+ * prop); tests call it directly. No module-level singleton: the store's
+ * lifetime belongs to the plugin activation, exactly like the official
+ * `createXXXStore()` factory rule.
+ */
+export declare function createSidebarStore(): SidebarStore;

package/lib/types/client/subagent-activity.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Pure derivation of the compact LIVE line shown on a running subagent card:
+ * the last text output and the last tool call of the child's history tail
+ * (`subagent.history` events, oldest → newest). Renders nothing itself — the
+ * SubagentLiveLine component turns this into the card's status lines.
+ * Kept framework-free so the parser is unit-testable in the node environment.
+ */
+import type { SidebarHistoryEntry } from '../context-types.ts';
+/**
+ * Extract the concatenated plain text of a content-block list (the durable
+ * `ContentBlock[]` shape, structurally: blocks with `type: 'text'` carry
+ * `text`; anything else — tool_use, image, … — contributes nothing).
+ * @param content - the raw `content` field of a message event.
+ * @returns the joined text, or undefined when the message carries no text.
+ */
+export declare function contentText(content: unknown): string | undefined;
+/** The live status of one subagent card (both fields optional). */
+export interface LastActivity {
+    /** The latest assembled assistant text output in the tail. */
+    text?: string;
+    /** The latest tool call in the tail. */
+    tool?: {
+        name: string;
+        args: string;
+    };
+}
+/**
+ * Fold a history tail into the last text output + last tool call (each is
+ * the LAST occurrence in event order). Lifecycle events and raw
+ * `assistant/chunk` rows are ignored — the card shows what the subagent is
+ * doing right now, not its plumbing.
+ * @param entries - the tail page from `subagent.history` (oldest → newest).
+ * @returns the last text and/or tool call; an empty object when the tail has neither.
+ */
+export declare function lastActivity(entries: SidebarHistoryEntry[]): LastActivity;

package/lib/types/client/subagent-detect.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Pure subagent-membership helpers over the sessions list feed (structural
+ * mirror world — no runtime imports). Used by the sidebar's auto-activation
+ * effect and the Subagent page:
+ *
+ * - {@link directSubagentCount}: direct durable children of one session,
+ * - {@link detectNewDirectSubagent}: the 0 → N transition that means "a new
+ *   subagent just spawned under the current session" (the auto-open trigger),
+ * - {@link countSubagentDescendants}: uninterrupted subagent-origin lineage
+ *   totals (mirror of the official `indexSubagentDescendants` over the
+ *   plugin's own summary rows).
+ */
+import type { SidebarSessionList, SidebarSubagentCatalog } from '../context-types.ts';
+/** Count the direct subagent children of one session (durable `origin` rows). */
+export declare function directSubagentCount(byId: SidebarSessionList['byId'], sessionId: string): number;
+/**
+ * The main agent of the current session's tree: walk the durable parent
+ * chain upward until the first non-subagent session. The Subagent page shows
+ * THIS root's full topology regardless of how deep the current selection is
+ * (a session whose row is still hydrating, or a broken chain, degrades to
+ * the session itself).
+ */
+export declare function rootAncestor(byId: SidebarSessionList['byId'], sessionId: string | undefined): string | undefined;
+/**
+ * Collect every catalog branch (an entry with `hasChildren`) reachable from
+ * the root — the set of catalogs the always-expanded topology consumes.
+ * Cycles fail soft.
+ */
+export declare function collectBranchIds(catalogs: Readonly<Record<string, SidebarSubagentCatalog>>, rootId: string | undefined): string[];
+/**
+ * Whether a new direct subagent appeared under `sessionId` between two
+ * consecutive list snapshots (the count crossed 0 → >0). Switching to a
+ * session that already has subagents yields `false` (its baseline starts at
+ * the current count), so the auto-open never fights an existing layout.
+ */
+export declare function detectNewDirectSubagent(prev: SidebarSessionList, next: SidebarSessionList, sessionId: string): boolean;
+/** Descendant totals of one session through an uninterrupted subagent-origin chain. */
+export interface SubagentDescendantTotals {
+    count: number;
+    runningCount: number;
+}
+/**
+ * Index every subagent descendant under each ancestor it reaches through an
+ * uninterrupted subagent-origin chain (same semantics as the official
+ * `indexSubagentDescendants`; cycles fail soft).
+ */
+export declare function countSubagentDescendants(byId: SidebarSessionList['byId'], sessionId: string): SubagentDescendantTotals;