dsh-coding-sidebar 1.0.0

package/lib/invariant.js

@@ -0,0 +1,22 @@
+//#region src/invariant.ts
+const PACKAGE_NAME = "dsh-coding-sidebar";
+/** Cordis companion plugin name. */
+const name = "dsh-coding-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-opens.d.ts

@@ -0,0 +1,65 @@
+import type { Context } from './context-types.ts';
+import type { SidebarPrefs } from './prefs-shared.ts';
+/** What the model asked to open. */
+export type AgentOpenKind = 'file' | 'folder' | 'url';
+/** One pending/broadcast open request (the wire face over the push socket). */
+export interface AgentOpenRequest {
+    /** Opaque id (host-generated; the client ignores it beyond dedupe/debug). */
+    id: string;
+    /** The session whose sidebar the open is targeted at. */
+    sessionId: string;
+    kind: AgentOpenKind;
+    /** Absolute local path (file/folder) or http(s) URL. */
+    target: string;
+    /** Tab title the client should use (basename / hostname / caller-supplied). */
+    title: string;
+}
+/** One subscribed sidebar view's sender. */
+type Sender = (request: AgentOpenRequest) => void;
+/**
+ * Per-session queue of open requests plus the connected sidebar views.
+ *
+ * Lifecycle: `enqueue` adds a request and — when at least one view for the
+ * session is attached — pushes it immediately and removes it from the queue
+ * (consume-on-send: a reconnect must never replay an open the client already
+ * applied, and the browser tab type has no per-URL dedupe, so replaying
+ * would mint duplicate tabs). With no attached view the request stays queued
+ * and `attach` replays it on connect. `drainAll` drops every queued request
+ * (the feature was turned off); `dispose` also drops every subscriber.
+ */
+export declare class AgentOpenRegistry {
+    private pending;
+    private subscribers;
+    /** Queue one open and deliver it immediately when a view is attached.
+     * @returns the request id and whether a connected view received it now. */
+    enqueue(sessionId: string, kind: AgentOpenKind, target: string, title: string): {
+        id: string;
+        delivered: boolean;
+    };
+    /** Attach one sidebar view (replays queued requests; consume-on-send).
+     * @returns the disposer detaching the view. */
+    attach(sessionId: string, send: Sender): () => void;
+    /** Drop every queued request (the feature was turned off mid-session). */
+    drainAll(): void;
+    /** Drop the queue and every subscriber (plugin teardown). */
+    dispose(): void;
+}
+/**
+ * Register the `sidebar_open` tool against the host tool registry. The tool
+ * is gated by the side-card setting `agentOpenTools` (the caller registers
+ * and unregisters it); `readPrefs` supplies the live prefs so a disabled
+ * target tab type (editor/browser) is reported to the model instead of
+ * silently no-oping on the client. `resolveCwd` threads the calling
+ * session's live cwd so relative paths resolve the same way the sidebar's
+ * own routes do.
+ * @param ctx - host plugin context (carries the tools service).
+ * @param registry - the open-request registry (per-session queue + views).
+ * @param resolveCwd - async cwd resolver for one session id. Resolves through
+ *  the session header, the client-supplied cwd, and the persistence index
+ *  before falling back to the host process cwd (production always provides
+ *  persistence, so the fallback is reached only in tests / stripped-down hosts).
+ * @param readPrefs - live resolved side card prefs (for tab enable gates).
+ * @returns a disposer that unregisters the tool.
+ */
+export declare function registerOpenTool(ctx: Context, registry: AgentOpenRegistry, resolveCwd: (sessionId: string) => Promise<string>, readPrefs: () => SidebarPrefs): () => void;
+export {};

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,39 @@
+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";
+/**
+ * The sandbox tokens for one URL: allowlisted loopback addresses (local dev
+ * servers the user explicitly trusts) additionally get `allow-same-origin`
+ * so Vite/module/HMR pipelines that need a real origin work; every other
+ * site keeps the opaque-origin sandbox. `allow-same-origin` does NOT give
+ * the page access to the GUI — it stays cross-origin to it and to every
+ * other site — but it does give it its OWN origin privileges (localStorage,
+ * fetch without CORS), so it is only granted for the explicit allowlist.
+ *
+ * The GUI itself is the one hard exception: even when its own host is
+ * allowlisted (a bare-host entry covers every port, so the GUI origin
+ * matches), a page at the GUI's exact origin must never get
+ * `allow-same-origin` — that would make it same-origin with its parent and
+ * hand it the GUI's storage/API (and the ability to shed the sandbox). The
+ * GUI keeps the opaque-origin sandbox no matter what the allowlist says.
+ */
+export declare function iframeSandboxFor(url: string | undefined, allowedLoopback: string, selfOrigin?: string): string | undefined;
+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,13 @@
+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[];
+    revealed: string[];
+    onToggleDir: (path: string) => void;
+    onReferenceFile: (path: string) => void;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,38 @@
+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[];
+    /** Files highlighted by a "Show in folder" reveal (absolute paths). */
+    revealed: 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/FreeWindow.d.ts

@@ -0,0 +1,29 @@
+/**
+ * One free window: a tab dragged out of the workbench floating over the
+ * conversation area at viewport coordinates (rendered inside the panel host,
+ * so desktop-shell transforms can never hijack its fixed containing block).
+ *
+ * The header drags the window with the panel-resize pattern — pointer
+ * capture + per-frame direct DOM writes + a store commit on release — and
+ * doubling as the DOCK-BACK gesture: while the pointer is over a workbench
+ * pane ([data-dsh-pane], either panel), that pane highlights live and
+ * releasing docks the tab into it (center merge); releasing anywhere else
+ * just moves the window. The SE corner resizes, any press raises (the
+ * floats array's order is the stacking order), the header right-click menu
+ * and the X button dock / close. The tab content reuses the regular tab
+ * renderer, so every tab type (terminal, editor, plugin tabs) floats
+ * unchanged.
+ */
+import { type ReactNode } from 'react';
+import type { FloatWindow, SidebarTab } from './state.ts';
+export declare function FreeWindow(props: {
+    float: FloatWindow;
+    renderTab: (tab: SidebarTab, active: boolean, paneId: string) => ReactNode;
+    getTabIcon?: (tab: SidebarTab) => ReactNode;
+    onRaise: () => void;
+    onMove: (x: number, y: number) => void;
+    onResize: (w: number, h: number) => void;
+    /** Dock the tab back; the pane id, or null for the active pane. */
+    onDock: (paneId: string | null) => void;
+    onClose: () => void;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,10 @@
+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;
+    /** Poll only while the tab is actually visible. */
+    visible: boolean;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,32 @@
+import { type ReactNode } from 'react';
+import { type AnalyzedMarkdownHtml } from './markdown-html.ts';
+import { type MermaidMarkdownProps } from './mermaid-blocks.ts';
+import type { SessionScope } from './api.ts';
+/** The chunk-resident markdown renderer (mermaid lazy chunk), shared with the
+ *  legacy no-HTML preview path in TextEditor. */
+export declare const LazyMermaidMarkdown: (props: MermaidMarkdownProps) => ReactNode;
+/** Everything the sanitizers need to resolve local media + scope the route. */
+export interface MarkdownHtmlMedia {
+    scope: SessionScope;
+    path: string;
+    origin: string;
+}
+interface MarkdownDocumentProps {
+    info: AnalyzedMarkdownHtml;
+    media: MarkdownHtmlMedia;
+    codeLabels: {
+        copyLabel: string;
+        copiedLabel: string;
+    };
+}
+/**
+ * The split-document renderer: markdown runs render through MarkdownSegment,
+ * HTML runs render as sanitized leaves, and unclosed block elements lower the
+ * following runs into themselves until their close part pops the frame (the
+ * renderer's frame stack persists across segments). Stray closes at the top
+ * level render nothing (the sanitizer/parser would drop them anyway), and
+ * frames still open at the end of the document are closed like a browser
+ * parser would. Sanitization runs once per prepared change, in a memo.
+ */
+export declare function MarkdownDocument({ info, media, codeLabels }: MarkdownDocumentProps): ReactNode;
+export {};

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;