@keith9681/dsh-sidebar 0.15.2

package/lib/invariant.js

@@ -0,0 +1,22 @@
+//#region src/invariant.ts
+const PACKAGE_NAME = "dsh-better-sidebar";
+/** Cordis companion plugin name. */
+const name = "dsh-better-sidebar-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the sidebar owns no service state or event protocol
+* of its own — every route is mounted under the host's webServer fence, the
+* pty lifecycle is exercised by the smoke spec, and the panel's store is a
+* plain snapshot registry asserted by the behavior specs. The route fence,
+* pty quota, and store semantics are each observed through their seams.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/agent-pty.d.ts

@@ -0,0 +1,226 @@
+import type { IPty } from 'node-pty';
+import { type NodePtyModule } from './pty-deps.ts';
+/** POSIX signals the registry forwards to a live pty. */
+export declare const ALLOWED_SIGNALS: readonly ["SIGINT", "SIGTERM", "SIGKILL", "SIGHUP", "SIGTSTP"];
+/** Signal name accepted by `signal()`. */
+export type AgentTerminalSignal = (typeof ALLOWED_SIGNALS)[number];
+/** Default read page size (lines) when the caller omits `count`. */
+export declare const DEFAULT_READ_COUNT = 500;
+/** Smallest pty dimension the registry accepts (mirrors the tool contract). */
+export declare const TERMINAL_DIM_MIN = 2;
+/** Largest pty dimension the registry accepts (mirrors the tool contract). */
+export declare const TERMINAL_DIM_MAX = 1024;
+/** Clamp one cols×rows pair into the supported pty range (flooring decimals). */
+export declare function clampDims(cols: number, rows: number): {
+    cols: number;
+    rows: number;
+};
+/**
+ * Serializable snapshot of one agent terminal — the shape the model sees
+ * through `terminal_list` and the sidebar sees through the push endpoint.
+ * Carries no pty reference and no transcript (those are reached through
+ * dedicated read/attach paths), and no sessionId: ownership is registry
+ * internals, scoped by the caller (list filters by session, the push
+ * endpoint scopes by its query param), never part of the serialized view.
+ */
+export interface AgentTerminalSnapshot {
+    /** Stable opaque handle the model passes back to other terminal_* tools. */
+    uuid: string;
+    /** Display title the model chose at create time. */
+    title: string;
+    /** The command the model asked to run at create time (verbatim). */
+    command: string;
+    /** Whether the top-level process has exited. */
+    exited: boolean;
+    /** Exit code if exited normally; absent until the process exits. */
+    exitCode?: number | null;
+    /** Exit signal name if the process was killed by a signal; null otherwise. */
+    exitSignal?: string | null;
+}
+/** One live agent terminal. */
+export interface AgentTerminalHandle {
+    /** Stable opaque handle. */
+    uuid: string;
+    /** Owning conversation id. */
+    sessionId: string;
+    /** Display title. */
+    title: string;
+    /** The command written to stdin right after spawn. */
+    command: string;
+    /** The working directory the process was spawned with. */
+    cwd: string;
+    /** The live pty process. */
+    pty: IPty;
+    /** Output accumulated since spawn (bounded; head dropped when over the limit). */
+    transcript: string;
+    /** Whether the top-level process exited (transcript stays replayable). */
+    exited: boolean;
+    /** Exit code once known. */
+    exitCode?: number | null;
+    /** Exit signal number once known (POSIX only; undefined on Windows). */
+    exitSignal?: number | null;
+}
+/** Read result shape (mirrors the official tool-pty terminal_read contract). */
+export interface AgentTerminalReadResult {
+    /** The slice of transcript text for the requested page. */
+    text: string;
+    /** Total lines in the retained transcript (the page may be a subset). */
+    totalLines: number;
+    /** 0-based index of the first line in `text` (inclusive). */
+    lineBegin: number;
+    /** 0-based index of the last line in `text` (exclusive). */
+    lineEnd: number;
+}
+/** Outcome of {@link AgentPtyRegistry.waitFor}. */
+export type AgentTerminalWaitResult = {
+    /** The needle was found in the transcript. */
+    kind: 'found';
+    /** The matched substring. */
+    needle: string;
+    /** 0-based line index (in the retained transcript) where the needle first appeared. */
+    line: number;
+    /** 0-based column index within that line where the match starts. */
+    column: number;
+    /** Elapsed wall-clock milliseconds from the wait start to the match. */
+    elapsedMs: number;
+} | {
+    /** The needle did not appear before the timeout. */
+    kind: 'timeout';
+    /** The needle that was awaited. */
+    needle: string;
+    /** The configured timeout in milliseconds. */
+    timeoutMs: number;
+    /** Total lines retained when the timeout fired (call terminal_read to inspect). */
+    totalLines: number;
+} | {
+    /** The terminal exited before the needle appeared. */
+    kind: 'exited';
+    /** The needle that was awaited. */
+    needle: string;
+    /** The exit code, if known. */
+    exitCode?: number | null;
+    /** The exit signal name, if the process was killed by a signal. */
+    exitSignal?: string | null;
+};
+/** Snapshot projection of a handle (drops the pty reference and transcript). */
+export declare function snapshotOf(handle: AgentTerminalHandle): AgentTerminalSnapshot;
+/**
+ * The agent terminal registry. The constructor takes the resolved shell
+ * binary (the same `defaultShell()` the UI-tab registry uses) and runs the
+ * spawn-helper chmod fix once at construction so the first agent terminal
+ * does not race a lazy fixer.
+ */
+export declare class AgentPtyRegistry {
+    private readonly shell;
+    private readonly shellArgs;
+    /** The loaded node-pty module (injected so a broken install degrades instead of crashing the plugin). */
+    private readonly nodePty;
+    private readonly sessions;
+    private readonly changeListeners;
+    constructor(shell: string, shellArgs?: string[], 
+    /** The loaded node-pty module (injected so a broken install degrades instead of crashing the plugin). */
+    nodePty?: NodePtyModule);
+    /**
+     * Spawn one agent terminal: start the shell in `cwd`, then write
+     * `command + '\n'` to stdin so the command runs in the fresh shell. The
+     * terminal stays alive after the command exits — the model can send more
+     * input through `terminal_send` until it calls `terminal_close` or the
+     * user closes the sidebar tab. An empty `command` spawns a bare shell.
+     * @returns the new handle's uuid (the model-facing opaque id).
+     */
+    create(sessionId: string, title: string, command: string, cwd: string, cols?: number, rows?: number, shell?: string, shellArgs?: string[]): string;
+    /** All live agent terminals belonging to one conversation. */
+    list(sessionId: string): AgentTerminalSnapshot[];
+    /** Resolve a live handle by uuid, or throw `not-found`. */
+    private expect;
+    /**
+     * Resolve a live handle that belongs to `sessionId`, or throw `not-found`.
+     * The model-facing tools call this before every uuid-keyed operation: a
+     * uuid from another session is indistinguishable from an unknown one, so a
+     * model can never reach (or probe) a terminal it does not own.
+     */
+    assertOwned(uuid: string, sessionId: string): AgentTerminalHandle;
+    /** Resolve a handle's snapshot, or undefined if it does not exist. */
+    snapshot(uuid: string): AgentTerminalSnapshot | undefined;
+    /** Write raw text to a terminal's stdin (tmux `send-keys` semantics). */
+    send(uuid: string, text: string): void;
+    /**
+     * Read one bounded page of the retained transcript. `offset` is a 0-based
+     * line index from the start of the retained transcript (default 0);
+     * `count` caps the page size (default 500). A negative `offset` reads
+     * from the end (e.g. -50 reads the last 50 lines). Returns `totalLines`
+     * so the model can paginate.
+     */
+    read(uuid: string, offset?: number, count?: number): AgentTerminalReadResult;
+    /**
+     * Resize a terminal's pty, clamped to the 2..1024 sane range.
+     * @returns the dimensions actually applied (the caller echoes these, so the
+     * reported value always matches the pty).
+     */
+    resize(uuid: string, cols: number, rows: number): {
+        cols: number;
+        rows: number;
+    };
+    /**
+     * Wait for `needle` to appear in a terminal's transcript, or for the
+     * terminal to exit, or for the timeout to elapse — whichever happens
+     * first. The wait polls the live transcript every ~50ms and short-circuits
+     * on `signal` abort (re-thrown as the abort reason so the tool layer
+     * surfaces cancellation).
+     *
+     * The match scans the FULL retained transcript on each poll, not just the
+     * delta since the last poll — a needle that scrolled past the most recent
+     * chunk but is still within the ~1 MiB bound is still a match. The
+     * returned line/column locate the FIRST occurrence (oldest), which is what
+     * a user watching the terminal would have seen first.
+     *
+     * The implementation uses polling (not pty onData subscription) because
+     * node-pty's onData fires before the registry's own onData listener
+     * updates the transcript (listener order is not guaranteed), and on
+     * Windows ConPTY output can arrive in bursts with batching delays that
+     * make event-driven wakeups unreliable. A 50ms poll is fast enough for
+     * interactive use and simple enough to be obviously correct.
+     * @param uuid - terminal to watch.
+     * @param needle - substring to search for (case-sensitive, verbatim).
+     * @param timeoutMs - max wait; default 10000 (10s). Clamped to ≥100ms.
+     * @param signal - caller-owned cancellation; aborts the wait re-throwing.
+     * @returns one of `found` / `timeout` / `exited`.
+     */
+    waitFor(uuid: string, needle: string, timeoutMs?: number, signal?: AbortSignal): Promise<AgentTerminalWaitResult>;
+    /**
+     * Send a POSIX signal to a terminal's foreground process.
+     *
+     * Two delivery paths, by signal kind:
+     * - **Interactive control signals** (SIGINT, SIGTSTP) are delivered by
+     *   writing the corresponding control character to the pty stdin. This is
+     *   how a real terminal sends Ctrl+C / Ctrl+Z: the byte hits the kernel
+     *   line discipline (POSIX ISIG mode) or the ConPTY input pipeline
+     *   (Windows), which translates it into a SIGINT/SIGTSTP for the
+     *   foreground process group. This works on every platform — calling
+     *   `node-pty.kill('SIGINT')` throws on Windows and is fragile on POSIX,
+     *   but writing `\x03` is universally correct.
+     * - **Termination signals** (SIGKILL, SIGTERM, SIGHUP) use `pty.kill()`,
+     *   which maps to the platform's process-termination path (POSIX
+     *   `kill(2)`, Windows `TerminateProcess`). These cannot be faked with
+     *   control characters.
+     */
+    signal(uuid: string, signal: AgentTerminalSignal): void;
+    /**
+     * Close a terminal and drop its state. Idempotent: a second close of the
+     * same uuid is a no-op. Returns true iff a live handle was actually
+     * dropped.
+     */
+    close(uuid: string): boolean;
+    /** Resolve a live handle by uuid (for the WS attach path). */
+    get(uuid: string): AgentTerminalHandle | undefined;
+    /**
+     * Subscribe to registry changes (create / close / exit). The sidebar push
+     * endpoint uses this to forward snapshots to the connected view. Returns
+     * the unsubscribe function.
+     */
+    subscribe(listener: () => void): () => void;
+    /** Close every agent terminal (plugin teardown). */
+    disposeAll(): void;
+    /** Fire every change listener (callers wrap in try/catch if needed). */
+    private notify;
+}

package/lib/types/browser-probe.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Pure helpers for the `browser.probe` route (sidebar browser): the host
+ * fetches the response HEADERS of a URL the user is browsing and the client
+ * decides whether the target site forbids being embedded (X-Frame-Options /
+ * CSP frame-ancestors are exactly the signals the browser enforces when it
+ * refuses an iframe load). Kept dependency-free so the parser is
+ * unit-testable.
+ */
+/**
+ * Extract the `frame-ancestors` source list of a Content-Security-Policy
+ * header, or undefined when the directive is absent (or empty). The
+ * directive is the only one with a source list; sources are space-separated
+ * tokens (`'none'`, `'self'`, `*`, or origins).
+ */
+export declare function extractFrameAncestors(csp: string | null): string[] | undefined;

package/lib/types/bundle-route.d.ts

@@ -0,0 +1,12 @@
+import type { Context, SidebarHttpRequest, SidebarHttpResponse } from './context-types.ts';
+/** The chunk names the client may request (mirror of src/client/chunk-loader.ts). */
+export declare const CHUNK_NAMES: readonly ["terminal", "editor", "mermaid"];
+export type ChunkName = (typeof CHUNK_NAMES)[number];
+/**
+ * Build the /sidebar/bundle route handler. `fence` is the shared browser-
+ * trust check every /sidebar route applies; `chunkDir` is the directory the
+ * chunk scripts live in (overridable for tests).
+ */
+export declare function createBundleRouteHandler(fence: (req: SidebarHttpRequest) => boolean, chunkDir?: string): (req: SidebarHttpRequest, res: SidebarHttpResponse) => Promise<void>;
+/** Register the /sidebar/bundle route (disposed with the fiber). */
+export declare function registerBundleRoute(ctx: Context, fence: (req: SidebarHttpRequest) => boolean): () => void;

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

@@ -0,0 +1,22 @@
+import type { TabComponentProps } from './service.ts';
+/**
+ * The browser iframe sandbox tokens. NO allow-same-origin (opaque origin —
+ * no GUI storage/API access), NO allow-top-navigation (a browsed page must
+ * not hijack the GUI). allow-forms/allow-popups/allow-downloads/allow-modals
+ * keep login flows working; allow-popups-to-escape-sandbox lets OAuth
+ * popups open as normal tabs (they are cross-origin to the GUI either way).
+ */
+export declare const BROWSER_IFRAME_SANDBOX = "allow-scripts allow-forms allow-popups allow-downloads allow-modals allow-popups-to-escape-sandbox";
+export declare function BrowserView(props: TabComponentProps): import("react").JSX.Element;
+/**
+ * The embed-refusal panel: shown when the probed site forbids being
+ * displayed inside other pages (X-Frame-Options / frame-ancestors) — the
+ * iframe would only show the browser's "refused to connect" blank. Explains
+ * the reason and offers the real-browser open plus a load-anyway escape.
+ * Exported so the copy and the actions are testable without a DOM.
+ */
+export declare function BrowserEmbedBlocked(props: {
+    url: string;
+    onOpenInBrowser: () => void;
+    onLoadAnyway: () => void;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,6 @@
+import type { SidebarDiffRef } from './state.ts';
+export declare function DiffTab(props: {
+    sessionId: string;
+    cwd: string | undefined;
+    diff: SidebarDiffRef;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,51 @@
+/** One rendered diff line. */
+export interface DiffLine {
+    kind: 'ctx' | 'del' | 'add' | 'meta';
+    /** The line content without its diff marker ('' for the no-newline marker). */
+    text: string;
+    /** Old-side line number (null for pure additions / metadata). */
+    oldNum: number | null;
+    /** New-side line number (null for pure deletions / metadata). */
+    newNum: number | null;
+}
+/** One parsed hunk. */
+export interface DiffHunk {
+    /** The old-side start line (`-a[,b]`). */
+    oldStart: number;
+    /** The new-side start line (`+c[,d]`). */
+    newStart: number;
+    /** The section text after the trailing `@@` (may be empty). */
+    header: string;
+    lines: DiffLine[];
+}
+/** One parsed file section of a unified diff. */
+export interface DiffFile {
+    /** The `---` path verbatim ('/dev/null' for a new file). */
+    oldPath: string;
+    /** The `+++` path verbatim ('/dev/null' for a deleted file). */
+    newPath: string;
+    /** The file changed with binary content: no hunks to draw. */
+    binary: boolean;
+    hunks: DiffHunk[];
+}
+/** The parsed unified diff. */
+export interface ParsedDiff {
+    files: DiffFile[];
+}
+/**
+ * Parse `git diff --no-color` output into file sections and hunks. Rows
+ * outside a file section (leading noise) and metadata rows between the
+ * `diff --git`/`---`/`+++` headers and the first hunk (index lines, mode
+ * changes, rename/similarity lines) are skipped; a section that never
+ * reaches a hunk (a mode/rename-only change) stays hunkless so the caller
+ * can still draw its path.
+ */
+export declare function parseUnifiedDiff(text: string): ParsedDiff;
+export interface DiffViewProps {
+    /** Unified diff text (`git.diff` or `git.commit-diff` payloads). */
+    diff: string;
+    /** Untracked-file content: when present, renders as a full-file addition instead of parsing. */
+    untrackedPath?: string;
+    untrackedContent?: string;
+}
+export declare function DiffView({ diff, untrackedPath, untrackedContent }: DiffViewProps): import("react").JSX.Element | null;

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

@@ -0,0 +1,12 @@
+import type { Context } from '../context-types.ts';
+import { type SessionScope } from './api.ts';
+import { type SidebarStore, type SidebarTab } from './state.ts';
+export declare function EditorHost(props: {
+    ctx: Context;
+    store: SidebarStore;
+    scope: SessionScope;
+    tab: SidebarTab;
+    expanded: string[];
+    onToggleDir: (path: string) => void;
+    onReferenceFile: (path: string) => void;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,36 @@
+import type { OpenWithTarget } from './open-with.ts';
+import { type UploadItem } from './upload.ts';
+/** Root label: the last path segment (mirror of the host rootLabel). */
+export declare function baseName(path: string): string;
+export declare function FileTree(props: {
+    sessionId: string;
+    cwd: string | undefined;
+    expanded: string[];
+    onToggle: (path: string) => void;
+    onOpenFile: (path: string) => void;
+    /** Context-menu "open in a new tab" (file rows; absent → no entry). */
+    onOpenFileNewTab?: (path: string) => void;
+    /** Context-menu "open to the side" (file rows; absent → no entry). */
+    onOpenFileSide?: (path: string) => void;
+    /**
+     * The "open with" menu: resolved external targets (already SSH-filtered
+     * and in menu order). Absent → the whole section is hidden.
+     */
+    openWithTargets?: OpenWithTarget[];
+    /** Ids of targets pinned to the menu's top level (subset of the ids). */
+    openWithPinned?: string[];
+    /** Whether the workspace is remote (appends the SSH hint to target labels). */
+    openWithSsh?: boolean;
+    /** Open one target externally (reveal or URL — the caller decides). */
+    onOpenWith?: (targetId: string, path: string) => void;
+    /** Toggle one target's pinned state (the submenu row's pushpin). */
+    onToggleOpenWithPin?: (targetId: string) => void;
+    /** Insert `@<relative path>` into the composer draft. */
+    onReferenceFile: (path: string) => void;
+    /** Bump to wipe the level cache and reload the visible set. */
+    refreshTick: number;
+    /** Upload into `dir` (absolute, inside the workspace); runs in the caller. */
+    onUploadRequest: (dir: string, items: UploadItem[]) => void;
+    /** True while an upload is in flight (drops are ignored). */
+    busy: boolean;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,8 @@
+import type { SessionScope } from './api.ts';
+import type { SidebarTab } from './state.ts';
+export declare function GitView(props: {
+    scope: SessionScope;
+    onOpenFile: (path: string) => void;
+    /** Open a diff tab (the shell places it below the git pane on first use). */
+    onOpenDiff: (tab: SidebarTab) => void;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,11 @@
+/**
+ * Placeholder shown when a persisted tab's type is not registered (the
+ * contributing plugin is not installed / not yet loaded). The tab is kept
+ * in state so it can recover if the plugin loads later; the user can close
+ * it through the tab bar's X button as usual. This is the graceful-
+ * degradation path for the open tab-type set: {@link Sidebar} renders this
+ * instead of crashing on an unknown type.
+ */
+import type { ReactNode } from 'react';
+import type { TabComponentProps } from './service.ts';
+export declare function OrphanedTab(props: TabComponentProps): ReactNode;

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

@@ -0,0 +1,6 @@
+import { type SessionScope } from './api.ts';
+export declare function PdfView(props: {
+    scope: SessionScope;
+    path: string;
+    title: string;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,32 @@
+/**
+ * The generic render error boundary for the sidebar tree: a render error in
+ * the wrapped subtree shows a dismissible error strip (retry re-renders the
+ * children) instead of blanking the shell. Used at two scopes:
+ *
+ * - ROOT (index.tsx, `css.boundaryError`): last-resort containment for
+ *   errors in the sidebar shell itself (Workbench, drag layout, …) — a full
+ *   swap keeps the page alive.
+ * - PER-TAB (Sidebar.tsx TabContent, `css.tabBoundaryError`): a crashing
+ *   viewer/editor shows a strip inside ITS OWN pane; the toggle cluster, the
+ *   other tabs, and the panel itself stay alive (issue #31 — a tab crash
+ *   must never take down the whole sidebar).
+ *
+ * The className prop selects the strip's geometry: the root's full-height
+ * fixed rail vs. the tab's pane-filling block.
+ */
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+export declare class RenderBoundary extends Component<{
+    children?: ReactNode;
+    className?: string;
+}, {
+    error: string | null;
+}> {
+    state: {
+        error: string | null;
+    };
+    static getDerivedStateFromError(error: unknown): {
+        error: string;
+    };
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    render(): ReactNode;
+}

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

@@ -0,0 +1,10 @@
+export declare function SandboxStatusBar(props: {
+    /** The effective sandbox state (global pref OR the local temporary unlock). */
+    sandboxed: boolean;
+    /** Whether the sandbox is off due to the LOCAL temporary unlock (shows the restore action). */
+    local: boolean;
+    /** The red-state explanation (e.g. "the page runs with full GUI privileges"). */
+    dangerCopy: string;
+    onUnlock: () => void;
+    onRestore: () => void;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,74 @@
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import { type SidebarPrefs } from '../prefs-shared.ts';
+import type { SidebarStore } from './state.ts';
+import type { BetterSidebarService, FileViewerDescriptor, SidebarSettingToggle, TabDescriptor } from './service.ts';
+/** Injected business face: the shared store (prefs cache) + the sidebar service (registries). */
+export interface SideCardSectionInjected {
+    store: SidebarStore;
+    service: BetterSidebarService;
+}
+/** Full section props: the runtime share plus the injected face. */
+export type SideCardSectionProps = PropsRuntime<'settings.section'> & SideCardSectionInjected;
+/**
+ * Merge one plugin-owned setting into a pluginSettings map (pure, v0.12.0+).
+ * Sequential merges are additive: each call spreads the map it was GIVEN,
+ * so building from the latest optimistic map keeps earlier keys intact
+ * (two same-tick writes must not drop each other).
+ */
+export declare function mergePluginSetting(pluginSettings: Record<string, Record<string, unknown>>, descriptorId: string, key: string, value: unknown): Record<string, Record<string, unknown>>;
+/**
+ * The body of a feature's secondary settings popup: one row (title/desc +
+ * control) per declared setting. Switches render the custom switch; text and
+ * number rows render a free-form / numeric input committed on blur/Enter
+ * (clamped to the declared min/max). Extracted so the rows are testable
+ * without opening the Modal (the Modal portal renders only while open).
+ */
+export declare function FeatureSettingsRows(props: {
+    toggles: readonly SidebarSettingToggle[];
+    prefs: SidebarPrefs;
+    onToggle: (toggle: SidebarSettingToggle, next: boolean) => void;
+    /** Commit one text/number row; returns the canonical value the row should
+     *  display (clamped for numbers, the current pref when the input is
+     *  invalid). Optional: rows with no handler keep their draft. */
+    onCommit?: (toggle: SidebarSettingToggle, raw: string) => string;
+    /** Commit one select row: the picked option's value (single) or the array
+     *  of picked values (`multi: true`). Optional: rows with no handler are
+     *  display-only. */
+    onSelectValue?: (toggle: SidebarSettingToggle, next: unknown) => void;
+    /** Explicit value source (v0.12.0+): when given, rows read their values
+     *  from it instead of the `prefs` face — plugin-owned rows read their
+     *  own blob, so a plugin key can never collide with (or silently read)
+     *  a host pref of the same name. (Named `valueSource`, not `valueOf`:
+     *  the latter collides with the inherited Object.prototype.valueOf.) */
+    valueSource?: (key: string) => unknown;
+}): import("react").JSX.Element;
+/**
+ * The secondary settings popup body of one feature (tab or viewer):
+ * - the host-prefs `toggles` rows, then the plugin-owned `pluginToggles`
+ *   rows (their values live in `pluginSettings[feature.id]`, projected onto
+ *   the prefs face so the shared row renderer reads them);
+ * - `settings.render` (custom panel) AFTER those rows when declared — the
+ *   custom panel is an extension of the row list, not a replacement, so a
+ *   feature can keep its declarative rows (e.g. the editor's
+ *   open-behavior picker) and still ship a custom configuration area.
+ */
+export declare function SettingsBody(props: {
+    feature: TabDescriptor | FileViewerDescriptor;
+    prefs: SidebarPrefs;
+    store: SidebarStore;
+    service: BetterSidebarService;
+    onToggle: (toggle: SidebarSettingToggle, next: boolean) => void;
+    onCommit: (toggle: SidebarSettingToggle, raw: string) => string;
+    onSelectValue: (toggle: SidebarSettingToggle, next: unknown) => void;
+    onPluginToggle: (toggle: SidebarSettingToggle, next: boolean) => void;
+    onPluginCommit: (toggle: SidebarSettingToggle, raw: string) => string;
+    onPluginSelectValue: (toggle: SidebarSettingToggle, next: unknown) => void;
+    onPluginWrite: (key: string, value: unknown) => void;
+    onClose: () => void;
+}): import("react").JSX.Element | null;
+/**
+ * Render the Side card preferences section.
+ * @param props - composed slot props (runtime share + injected store/service).
+ * @returns the section element tree.
+ */
+export declare function SideCardSection({ store, service }: SideCardSectionProps): import("react").JSX.Element;

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

@@ -0,0 +1,16 @@
+import type { Context } from '../context-types.ts';
+import type { SessionScope } from './api.ts';
+import type { SidebarTab } from './state.ts';
+/** The thread a tab is bound to (durable in tab.meta across refreshes). */
+export declare function sidechatThreadIdOf(tab: SidebarTab): string | undefined;
+/** Park a thread id for the NEXT sidechat openTab to reattach. */
+export declare function parkSidechatReopen(threadId: string): void;
+/** Consume the parked reopen target (undefined = mint a fresh thread tab). */
+export declare function consumeSidechatSeed(): string | undefined;
+/** One side conversation tab (one thread per tab, Codex-style). */
+export declare function SideChatView(props: {
+    ctx: Context;
+    scope: SessionScope;
+    tab: SidebarTab;
+    visible: boolean;
+}): React.ReactNode;

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

@@ -0,0 +1,6 @@
+import type { Context } from '../context-types.ts';
+import { type SidebarStore } from './state.ts';
+export declare function Sidebar(props: {
+    ctx: Context;
+    store: SidebarStore;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,16 @@
+import type { Context, SidebarSubagentAddress } from '../context-types.ts';
+/**
+ * The sidebar's Subagent topology page.
+ * @param props - current session id, whether the page is actually visible
+ *   (active tab + open panel), the client context, and an optional
+ *   jump-notify hook fired right before `openSubagent` (lets the sidebar
+ *   shell re-open the Subagent page after the conversation switch lands on
+ *   the child session).
+ * @returns the main agent's topology tree, or the empty/error/loading states.
+ */
+export declare function SubagentView(props: {
+    sessionId: string;
+    active: boolean;
+    ctx: Context;
+    onOpenChild?: (address: SidebarSubagentAddress) => void;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,43 @@
+/**
+ * The tab strip of one pane: tabs capped at TAB_MAX_WIDTH (ellipsized),
+ * overflow scrolls horizontally, a close button per tab, a four-way split
+ * button cluster, and the + menu that opens new tabs (explorer / git /
+ * terminal). Tabs are draggable; dropping onto another tab inserts before it,
+ * dropping on the strip background appends to this pane. Right-clicking a
+ * tab opens the tab context menu (close / close others / close to the left /
+ * close to the right, all scoped to this pane).
+ */
+import { type ReactNode } from 'react';
+import type { SidebarTab } from './state.ts';
+/** One + menu option. */
+export interface NewTabOption {
+    id: string;
+    label: string;
+    disabled?: boolean;
+    /** Leading icon (Menu row). */
+    icon?: ReactNode;
+}
+/** Drag payload for tab moves (HTML5 DnD dataTransfer). */
+export declare const TAB_DRAG_TYPE = "application/x-dsh-tab";
+export interface TabDragPayload {
+    tabId: string;
+    paneId: string;
+}
+export declare function serializeDrag(payload: TabDragPayload): string;
+export declare function parseDrag(raw: string): TabDragPayload | null;
+export declare function TabBar(props: {
+    paneId: string;
+    tabs: SidebarTab[];
+    active: string | null;
+    onActivate: (tabId: string) => void;
+    onClose: (tabId: string) => void;
+    onNewTab: (optionId: string) => void;
+    newTabOptions: NewTabOption[];
+    /** Drop of a tab from any pane: (payload, insertBeforeTabId | null). */
+    onDropTab: (payload: TabDragPayload, before: string | null) => void;
+    /** Icon resolver for tab labels (reads from the tab descriptor registry). */
+    getTabIcon?: (tab: SidebarTab) => ReactNode;
+    /** Badge resolver for tab labels (reads the descriptor's `badge`; the
+     *  resolver returns the rendered pill or null). */
+    getTabBadge?: (tab: SidebarTab) => ReactNode;
+}): import("react").JSX.Element;