dsh-coding-sidebar 1.0.0

package/lib/types/client/builtins/tabs.d.ts

@@ -0,0 +1,11 @@
+import type { Context } from '../../context-types.ts';
+import type { TabDescriptor } from '../service.ts';
+/** How many UI-owned terminals may be open at once (agent-owned ones are uncapped). */
+export declare const TERMINAL_LIMIT = 3;
+/** Optional per-registration builtin behavior (currently terminal title). */
+export interface BuiltinTabOptions {
+    /** Returns the display title for newly opened terminal tabs. */
+    terminalTitle?: () => string;
+}
+/** The 6 built-in tab descriptors. */
+export declare function builtinTabs(ctx: Context, options?: BuiltinTabOptions): readonly TabDescriptor[];

package/lib/types/client/builtins/viewers.d.ts

@@ -0,0 +1,3 @@
+import type { FileViewerDescriptor } from '../service.ts';
+/** The 6 built-in file viewer descriptors. */
+export declare function builtinViewers(): readonly FileViewerDescriptor[];

package/lib/types/client/chunk-loader.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Lazy chunk loader for the client bundle. The heavy preview/terminal
+ * libraries (CodeMirror, xterm — the editor/terminal stacks, several MB)
+ * live in separate build-time bundles (`lib/client-<name>.js`) fetched only
+ * on first use of the feature that needs them, so startup downloads/parses
+ * only the ~1MB core bundle. (The office stack — Univer / docx-preview /
+ * pptx-renderer — is no longer bundled here: Office previews moved to the
+ * recommended office plugin, see plugins-viewers.ts.)
+ *
+ * How a chunk script works (see tsdown.config.ts chunkBundle):
+ *
+ *   globalThis.__dshChunks__ = globalThis.__dshChunks__ || {};
+ *   globalThis.__dshChunks__["terminal"] = (require) => { ...exports };
+ *
+ * The script registers its factory on a plugin-owned global registry (NOT
+ * through window.__ModuleLoader__.load — the module loader's import() only
+ * resolves seed words, shell-own modules, registered factories, and boot
+ * graph rows; a chunk id is none of those, so resolution would be version-
+ * dependent). Materialization is plugin-owned:
+ *
+ * 1. inject <script src="/sidebar/bundle/<name>.js"> (classic same-origin
+ *    script; the official /plugins/<id>/client.js route cannot serve
+ *    arbitrary file names, so the plugin's own host route serves the chunks),
+ * 2. read the factory from the global registry,
+ * 3. call it with a require that resolves the platform externals through
+ *    `__DSH_MODULES__.import(spec)` — the seed-word branch, the one part of
+ *    the module system that is stable across versions.
+ *
+ * Caching contract (three layers, each with a failure path):
+ * - In-memory: one in-flight promise per chunk, memoized until
+ *   {@link resetChunks}; a failed load removes its entry so the next call
+ *   retries from scratch. HMR re-activation keeps the resolved exports of
+ *   unchanged chunks (ETag revalidation via
+ *   {@link revalidateChunksOnReactivate}) — the next lazy open skips the
+ *   re-inject / re-execute.
+ * - Script execution: each re-execution overwrites the global registry slot
+ *   (assignment, never registration) — no "duplicate factory registration"
+ *   class of errors; a failed materialization clears the cache so the retry
+ *   re-injects and re-executes.
+ * - HTTP: the bundle route revalidates every request (`cache-control:
+ *   no-cache` + ETag, 304 when unchanged), so page refreshes and HMR
+ *   re-activations never re-download a multi-MB chunk that did not change.
+ *
+ * HMR: each plugin activation calls {@link revalidateChunksOnReactivate},
+ * which HEADs every loaded chunk against the bundle route and keeps the
+ * in-memory cache for the ones whose ETag is unchanged (a hot-reloaded core
+ * bundle therefore does not re-execute multi-MB chunk scripts). Chunk-only
+ * source edits still need a manual page refresh (the HMR poll watches only
+ * client.js); an edit that does land while a core HMR happens is caught by
+ * the ETag comparison on the next activation.
+ */
+export type ChunkName = 'terminal' | 'editor' | 'mermaid';
+/** The module exports a chunk factory provides (namespace-ish record). */
+export type ChunkExports = Record<string, unknown>;
+/**
+ * The platform externals a chunk bundle may require (mirror of
+ * CLIENT_EXTERNALS in tsdown.config.ts — the chunk builds keep these
+ * external and the loader resolves them here). A superset is safe: the
+ * require only answers what the chunk actually asks for. The shell's static
+ * module table seeds React, Cordis, and the UI libraries (primitives/slots);
+ * `dsh-client-runtime/client` normalizes onto the runtime package row
+ * (stripClientSuffix). dsh-client-web-react / dsh-client-schema-form were
+ * dropped in DSH 0.1.0-rc.8 (no rc.8 publish, nothing requires them) — the
+ * chunks never asked for them, so they no longer belong here.
+ *
+ * DSH 0.1.2-alpha.1 removed the `dsh-client-runtime` package outright (the
+ * seed table gained bare-name `@deepseek-ai/dsh-client-store` instead); the
+ * runtime/client row below stays for 0.1.1-rc.x hosts — no chunk requires
+ * it, and {@link buildExternalsRequire} keeps an unresolvable spec
+ * undefined until a chunk actually asks (only then is it a loud error), so
+ * the entry is inert on 0.1.2-alpha.1+.
+ */
+export declare const CHUNK_EXTERNALS: readonly string[];
+/**
+ * The client module system surface this loader needs to resolve externals.
+ * DSH 0.1.0-rc.8 provides it as the `ctx.modules` service (no page global
+ * anymore); the plugin injects it at activation via
+ * {@link setChunkModuleSystem}. The rc.7-era `window.__DSH_MODULES__` global
+ * remains as a fallback so older hosts and the test harness keep working.
+ */
+export interface ChunkModuleSystem {
+    import(specifier: string): Promise<unknown>;
+}
+/**
+ * Inject the client module system the chunk externals resolve through.
+ * Called by the client half's apply() with `ctx.modules` (rc.8+); pass
+ * undefined to clear (tests). Survives {@link resetChunks} — the module
+ * system is shell state, not chunk state, and stays live across HMR.
+ */
+export declare function setChunkModuleSystem(system: ChunkModuleSystem | undefined): void;
+/** Script-load hook; tests replace it with a stub (the default needs a real DOM + network). */
+export type ChunkScriptLoader = (src: string) => Promise<void>;
+/** Test hook: replace the chunk-script loader (pass null to restore the default). */
+export declare function setChunkScriptLoaderForTests(loader: ChunkScriptLoader | null): void;
+export declare function registerChunkForTests(name: ChunkName, loader: () => Promise<ChunkExports>): void;
+/**
+ * Load (once) and materialize a lazy chunk, returning its module exports.
+ * Concurrent callers share one in-flight load; a failure clears the cache
+ * entry so the next call retries (the script re-executes and overwrites its
+ * global registry slot — assignments are idempotent).
+ * @param name - the chunk to load.
+ */
+export declare function loadChunk(name: ChunkName): Promise<ChunkExports>;
+/**
+ * Drop all chunk state for a fresh plugin activation (HMR-safe): clear the
+ * in-memory cache and any test-registry entries, so the next lazy open
+ * re-fetches and re-executes the current chunk scripts (the registry slots
+ * are overwritten by the re-execution — no cleanup needed). A pending
+ * revalidation barrier is cleared too: it was only guarding the cache reads
+ * of the state being dropped, so the next load must not wait on it (the
+ * orphaned task still settles and its identity-guarded `finally` no-ops).
+ */
+export declare function resetChunks(): void;
+/**
+ * HMR-safe re-activation hook (index.tsx calls this instead of a full
+ * reset): keep the resolved exports of every loaded chunk and drop only the
+ * ones whose script changed on disk — the bundle route revalidates every
+ * request (cache-control: no-cache + ETag), so an unchanged chunk keeps its
+ * memory cache and the next lazy open skips the re-inject / re-execute.
+ * Fail-open: an unreachable, ETag-less, or timed-out chunk is dropped
+ * (re-fetch on next open). Test-registry entries are always cleared
+ * (per-test fixtures).
+ * A page refresh remains the authoritative reset (the HMR poll watches only
+ * client.js; chunk-only edits surface here on the next core re-activation).
+ *
+ * The returned promise is also a BARRIER for {@link loadChunk}: while a
+ * revalidation is pending, every chunk load awaits it before serving cache,
+ * so a lazy tab opening mid-revalidation can never render stale exports
+ * that the sweep is about to invalidate (CR #232 P1).
+ */
+export declare function revalidateChunksOnReactivate(): Promise<void>;

package/lib/types/client/chunks/editor.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Lazy chunk entry: the code/markdown/html text editor (CodeMirror 6 + the
+ * language packages). Built as `lib/client-editor.js` and registered under
+ * `dsh-coding-sidebar/editor` — fetched only when a text file is first
+ * opened (see chunk-loader.ts and docs/plans/2026-08-12-lazy-chunks-design.md).
+ * Never import this module from the core bundle: it pulls CodeMirror into
+ * the startup path.
+ */
+export { TextEditor } from '../TextEditor.tsx';

package/lib/types/client/chunks/mermaid.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Lazy chunk entry: the mermaid diagram renderer for the markdown preview
+ * (mermaid + its d3/dagre/cytoscape graph deps). Built as
+ * lib/client-mermaid.js and registered under the `mermaid` global chunk
+ * slot — fetched only when a previewed markdown file contains a mermaid
+ * fence (see chunk-loader.ts and the mermaid markdown preview design doc).
+ * Never import this module from the core bundle: it pulls mermaid into the
+ * startup path.
+ */
+export { MermaidMarkdown } from '../mermaid.tsx';

package/lib/types/client/chunks/terminal.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Lazy chunk entry: the interactive terminal (xterm + fit addon). Built as
+ * `lib/client-terminal.js` and registered under
+ * `dsh-coding-sidebar/terminal` — fetched only when a terminal tab is first
+ * opened (see chunk-loader.ts and docs/plans/2026-08-12-lazy-chunks-design.md).
+ * Never import this module from the core bundle: it pulls xterm (and its
+ * stylesheet) into the startup path.
+ */
+export { TerminalView } from '../TerminalView.tsx';

package/lib/types/client/cm-themes.d.ts

@@ -0,0 +1,24 @@
+/**
+ * CodeMirror 6 theme pieces for the sidebar editor. The editor surface
+ * (background, caret, gutter) rides the DSH theme tokens so it blends with
+ * the panel in both schemes; only the syntax token colors need concrete
+ * values, and those come from the same designed palettes the app's code
+ * surfaces use — the one-dark family for dark, the one-light family for
+ * light. The scheme flip reconfigures these via a compartment (see
+ * TextEditor), so the document, undo history and scroll survive re-theming.
+ */
+import { Compartment } from '@codemirror/state';
+/** Token-driven surface shared by both schemes (pure CSS values). */
+export declare const cmSurfaceTheme: import("@codemirror/state").Extension;
+/**
+ * A Compartment holding the two scheme-dependent extensions. Created once
+ * per editor view; a scheme flip dispatches `reconfigure(dark)` on it, so
+ * the document, undo history, scroll and keymaps survive re-theming.
+ */
+export declare class CmThemeCompartment {
+    private readonly compartment;
+    /** `of(...)` payload for EditorState.create. */
+    of(dark: boolean): ReturnType<Compartment['of']>;
+    /** Reconfigure for a new scheme. */
+    reconfigure(dark: boolean): ReturnType<Compartment['reconfigure']>;
+}

package/lib/types/client/conversation-draft.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Append text to the current session's composer draft through the
+ * conversation service — the shared path behind the explorer's @-reference
+ * button and the viewer selection popup. The service is resolved lazily
+ * through `ctx.get` (the inject-free read the app's own plugins use); a
+ * missing service or scope degrades to a logged no-op, never a crash.
+ */
+import type { Context } from '../context-types.ts';
+/**
+ * Append `text` to the session's composer draft (space-separated, like the
+ * @-mentions). Returns false — and logs — when the conversation service or
+ * the session scope is unavailable.
+ */
+export declare function appendToDraft(ctx: Context, sessionId: string, text: string): boolean;

package/lib/types/client/desktop-env.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Desktop-shell detection for the sidebar. Shells may stamp the render URL
+ * with `dsh-desktop-mode` / `dsh-desktop-platform` (the official Electron
+ * shell does) and expose `window.__DSH_DESKTOP_FILE_PATH__` through a
+ * preload. Parsed once per page and memoized (the URL never changes
+ * mid-session); `resetDesktopEnvForTests` clears the memo for unit tests.
+ *
+ * GEOMETRY POLICY: this module only REPORTS shell facts — it never decides
+ * how to adapt. The strip height comes from standard signals first (the
+ * Window Controls Overlay API, see wco.ts), then the documented contract
+ * parameter `dsh-desktop-titlebar-inset` (a shell may stamp the real pixels
+ * it reserves at the top), then the user's chosen scheme (preset / custom).
+ * The legacy win32-advanced 32px constant is gone from the core: it lives
+ * in the opt-in shell preset (shell-presets.ts) as a fallback for shells
+ * without the WCO API.
+ */
+export interface DesktopEnv {
+    /** Running inside a desktop shell (any URL stamp or preload marker). */
+    readonly desktop: boolean;
+    /** `advanced` = frameless/custom-titlebar shell; `compatibility` = native frame. */
+    readonly mode: 'compatibility' | 'advanced' | null;
+    /** Shell platform stamp ('darwin' | 'win32' | …), lowercased, or null. */
+    readonly platform: string | null;
+    /**
+     * Contract parameter `dsh-desktop-titlebar-inset`: pixels the shell
+     * reserves at the top of the web content for its own chrome (0–120,
+     * clamped; 0 when absent). Standard WCO geometry takes precedence over
+     * this whenever the API is available.
+     */
+    readonly titlebarInset: number;
+}
+/** Read the shell's desktop stamps (memoized per page; SSR-safe). */
+export declare function parseDesktopEnv(): DesktopEnv;
+/** Test hook: drop the memo so the next parse re-reads the URL/globals. */
+export declare function resetDesktopEnvForTests(): void;

package/lib/types/client/editor-load.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Pure editor-load planning: the decision logic the editor host needs to
+ * turn a matched file viewer + a host fs.read result into a render action.
+ * Kept dependency-free (no React, no fetch) so the strategy dispatch is
+ * unit-testable and the wire contract (head bytes, binary flag) is pinned.
+ *
+ * The host flow this module drives:
+ *   1. `matchFileViewer(path)` picks a viewer by extension/priority.
+ *   2. `planFirstMatch` dispatches its fetchStrategy.
+ *   3. An fsRead viewer fetches through the host; `planFsReadOutcome`
+ *      decides what to do with the result — including the head-based
+ *      re-match that lets a `detect` viewer claim a binary the extension
+ *      match could not see (the builtin NUL probe on `binary-download`).
+ */
+import type { FileViewerDescriptor } from './service.ts';
+/** One host fs.read result (mirror of the wire; `head` present when binary). */
+export interface FsReadOutcome {
+    binary: boolean;
+    content: string;
+    truncated: boolean;
+    /** base64 of the first bytes (present on binary reads; sniffing material). */
+    head?: string;
+}
+/** What the editor host should do next. */
+export type EditorLoadAction = 
+/** No renderer: show the download UI. */
+{
+    kind: 'binary';
+}
+/** Render `viewer`'s component with the carried payload. */
+ | {
+    kind: 'render';
+    viewer: FileViewerDescriptor;
+    content?: string;
+    truncated?: boolean;
+    mediaUrl?: string;
+    customData?: unknown;
+}
+/** Fetch the file through the host (fsRead strategy). */
+ | {
+    kind: 'fetchFsRead';
+    viewer: FileViewerDescriptor;
+}
+/** Call the viewer's load() and render with its return value. */
+ | {
+    kind: 'customLoad';
+    viewer: FileViewerDescriptor;
+};
+/** Decode the host's base64 head bytes into the sniffing buffer. */
+export declare function decodeHead(headBase64: string): Uint8Array;
+/**
+ * Dispatch one matched viewer's fetchStrategy. A missing viewer or a
+ * `binary-download` strategy both mean "no client-side renderer" → the
+ * download UI. `mediaUrlOf` builds the media URL for `mediaUrl`/`none`
+ * strategies (pure, but scope-bound — injected by the host).
+ */
+export declare function planFirstMatch(viewer: FileViewerDescriptor | undefined, mediaUrlOf: () => string): EditorLoadAction;
+/**
+ * Decide what an fsRead result means for the editor.
+ * - Text: the first match stands (content is valid for any fsRead viewer).
+ * - Binary: the host head bytes enable a re-match — a `detect` viewer (e.g.
+ *   a plugin sniffing a binary format) may claim the file. `custom` viewers
+ *   load their own bytes; `mediaUrl`/`none` viewers render the media route;
+ *   an fsRead viewer or nothing cannot render binary → download UI.
+ */
+export declare function planFsReadOutcome(viewer: FileViewerDescriptor, result: FsReadOutcome, rematch: (head: Uint8Array) => FileViewerDescriptor | undefined, mediaUrlOf: () => string): EditorLoadAction;

package/lib/types/client/frame-batcher.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Per-frame task coalescing for pointer-driven interactions.
+ *
+ * Pointer streams fire several times faster than the display refresh, and
+ * applying every event (a React setState, a store reduce) re-renders whole
+ * trees at event cadence — the visible drag lag on slower CPUs (#315). This
+ * batcher keeps the LATEST scheduled task, runs it at most once per
+ * animation frame, and lets the caller flush synchronously on release (so
+ * the final pointer position is never lost to a cancelled frame).
+ *
+ * Callers compose the pending value in a ref before scheduling; the
+ * scheduled task reads that ref, so replacing the task on every event is
+ * cheap (one ref write + one rAF check).
+ */
+export interface FrameBatcher {
+    /** Schedule (or replace) the per-frame task. Safe to call on every event. */
+    schedule(task: () => void): void;
+    /** Cancel any pending frame and run the scheduled task synchronously
+     *  (no-op when nothing is scheduled). */
+    flushNow(): void;
+    /** Cancel any pending frame and drop the task without running it. */
+    dispose(): void;
+}
+export declare function createFrameBatcher(): FrameBatcher;

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

@@ -0,0 +1,59 @@
+/**
+ * Icons the sidebar needs beyond the primitives set: a terminal glyph (the
+ * icon library has none), a diff glyph, and the two panel-toggle glyphs for
+ * the top-right cluster. Per-tab icons live on the tab descriptors
+ * (`descriptor.icon`), not in a type-keyed switch — the icon mapping was
+ * registry-ized with the tab types.
+ */
+import type { IconProps } from '@deepseek-ai/dsh-client-ui-primitives';
+/**
+ * Right-panel toggle glyph (the "侧拉" button): a frame with a filled strip
+ * along its RIGHT edge, in the app's outline style (1.5px stroke,
+ * currentColor).
+ */
+export declare const IconPanelRightOutline16: ({ size, className }: IconProps) => import("react").JSX.Element;
+/**
+ * Terminal glyph in the app's outline style (1.5px stroke, currentColor):
+ * a rounded frame with a prompt chevron and underscore cursor.
+ */
+export declare const IconTerminalOutline16: ({ size, className }: IconProps) => import("react").JSX.Element;
+/** Diff glyph in the app's outline style: a file frame with a plus and a minus row. */
+export declare const IconDiffOutline16: ({ size, className }: IconProps) => import("react").JSX.Element;
+/**
+ * Stop glyph for the background-job kill button: a filled square in the
+ * app's outline scale (16), the universal "halt this work" mark.
+ */
+export declare const IconStopOutline16: ({ size, className }: IconProps) => import("react").JSX.Element;
+/** Upload glyph in the app's outline style: an arrow rising into a tray
+ *  (the file-manager "upload into the workspace" action). */
+export declare const IconUploadOutline16: ({ size, className }: IconProps) => import("react").JSX.Element;
+/**
+ * Pin glyph in the app's outline style (1.5px stroke, currentColor): a pushpin
+ * tilted to the lower-right. Used by the PinnedRail and the tab context menu's
+ * pin entry (v0.17.0+).
+ */
+export declare const IconPinOutline16: ({ size, className }: IconProps) => import("react").JSX.Element;
+/** Image viewer glyph: a picture frame with a sun and a mountain. */
+export declare const IconImageOutline16: ({ size, className }: IconProps) => import("react").JSX.Element;
+/** PDF viewer glyph: a document frame with the "PDF" label. */
+export declare const IconPdfOutline16: ({ size, className }: IconProps) => import("react").JSX.Element;
+/** Markdown viewer glyph: the classic "M with a down arrow" badge. */
+export declare const IconMarkdownOutline16: ({ size, className }: IconProps) => import("react").JSX.Element;
+/** HTML viewer glyph: a document frame with a "‹/›" tag pair. */
+export declare const IconHtmlOutline16: ({ size, className }: IconProps) => import("react").JSX.Element;
+/** Browser tab glyph: a globe with meridians. */
+export declare const IconGlobeOutline16: ({ size, className }: IconProps) => import("react").JSX.Element;
+/** History glyph (thread switcher): a clock with a counterclockwise arrow,
+ *  in the app's outline style — the "past conversations" mark. */
+export declare const IconHistoryOutline16: ({ size, className }: IconProps) => import("react").JSX.Element;
+/** Save glyph (save-as-new-session): the classic floppy disk, in the app's
+ *  outline style. */
+export declare const IconSaveOutline16: ({ size, className }: IconProps) => import("react").JSX.Element;
+/**
+ * Visual Studio Code brand mark for the file-tree "open with" menu. The
+ * path is the Simple Icons `visualstudiocode` glyph (CC0 1.0,
+ * simple-icons@11.0.0 — later releases dropped it over Microsoft's brand
+ * policy, so it is inlined here rather than pulled from react-icons),
+ * rendered monochrome via currentColor to follow the active skin.
+ */
+export declare const IconVscode16: ({ size, className }: IconProps) => import("react").JSX.Element;

package/lib/types/client/image-types.d.ts

@@ -0,0 +1,3 @@
+/** Image extension dispatch, separate from React for unit testing. */
+export declare const IMAGE_EXTENSIONS: readonly string[];
+export declare function isImageExt(ext: string): boolean;

package/lib/types/client/ime-guard.d.ts

@@ -0,0 +1,36 @@
+/**
+ * IME-composition key guard.
+ *
+ * While a Chinese/Japanese/Korean input method is composing (the user is
+ * picking a candidate from the IME window), every pressed key BELONGS to the
+ * input method: arrows move the candidate highlight, Enter/Space confirm the
+ * composition, Escape cancels it. Page code must not process those keys —
+ * a component that does (a number stepper calling preventDefault() on
+ * ArrowUp/ArrowDown, a submit handler reacting to Enter, ...) silently
+ * breaks the IME: candidates stop responding, the composition gets torn
+ * apart, and only bare letters come out.
+ *
+ * This guard enforces that rule at the document boundary: a capture-phase
+ * keydown/keyup listener that stops the event from propagating further
+ * whenever a composition is in progress. Because it runs in the capture
+ * phase on `document` — the outermost node — it fires BEFORE React's
+ * delegated handlers (attached at the root container) and before any native
+ * target/bubble listener, so an inlined third-party component (e.g. the
+ * Univer office UI bundled into this plugin) can never intercept
+ * composition keys. The browser's native IME processing is untouched:
+ * stopPropagation only silences page JS, not the default action.
+ *
+ * The composition signal follows the DSH core convention (InputBar's IME
+ * guard, issue #535): `isComposing` for modern engines, keyCode 229 as the
+ * legacy signal engines emit without isComposing.
+ */
+/** The pure decision: is this keyboard event part of an IME composition? */
+export declare function isImeComposition(event: {
+    isComposing: boolean;
+    keyCode: number;
+}): boolean;
+/**
+ * Register the document-level capture guard. Returns the disposer
+ * (HMR-safe; call through `ctx.effect`).
+ */
+export declare function registerImeGuard(): () => void;

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

@@ -0,0 +1,25 @@
+import type { Context } from '../context-types.ts';
+import './layout.css';
+/** Services required before mounting (provided by the client runtime; the
+ *  locale service backs the sidebar's copy — see locales.ts). `modules`
+ *  (rc.8+) is the client module system the chunk loader resolves its
+ *  externals through — Cordis guards service access without inject.
+ *  `remote` + `remote.session` pin this build to the 0.1.2-alpha.1+ carrier:
+ *  the open-path interception wraps the session namespace, and the deep path
+ *  is validated AS A WHOLE by the traceable service proxy (a bare ctx.get
+ *  clears the first hop, then `cannot get property "remote.session" without
+ *  inject` on the second). Cordis inject is all-required, so a carrier
+ *  without these never mounts this plugin — same policy as `modules`. */
+export declare const inject: string[];
+/**
+ * Error boundary over the sidebar tree (root scope): a render error in the
+ * sidebar SHELL itself must never blank the page silently — the shared
+ * RenderBoundary shows a dismissible error strip and logs the stack. The
+ * per-tab scope (Sidebar.tsx) catches viewer/editor crashes first; this root
+ * boundary stays as the last resort for Workbench/shell errors.
+ */
+/**
+ * Client plugin body.
+ * @param ctx - the client cordis context (slots, sessions).
+ */
+export declare function apply(ctx: Context): void;

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

@@ -0,0 +1,46 @@
+import type { Context } from '../context-types.ts';
+import { type SidebarStore } from './state.ts';
+/** Open a file in the sidebar's editor (used by the intercepted row and the explorer). */
+export declare function openSidebarFile(ctx: Context, store: SidebarStore, sessionId: string, path: string): void;
+/**
+ * Reveal the produced files in the sidebar explorer: expand their parent
+ * directories, highlight the rows, and focus the explorer tab (expanding the
+ * hosting panel when it is collapsed). Unknown files fall back to revealing
+ * the workspace root itself.
+ */
+export declare function revealInExplorer(ctx: Context, store: SidebarStore, sessionId: string, files: readonly string[]): void;
+/** The intercepted produced-files row (visual twin of the deliverables chips). */
+export declare function SidebarProducedFiles(props: {
+    matched: readonly string[];
+    openInSidebar: (path: string) => void;
+    /** Reveal the produced files in the explorer ("Show in folder" twin). */
+    onShowInFolder: (files: readonly string[]) => void;
+}): import("react").JSX.Element;
+/**
+ * Register the turn-tail interception (returns the disposer).
+ *
+ * The slot is a CHILD slot the host's ui-conversation declares in its
+ * `conversation.chat.node` children table (kind: chain, scope: session).
+ * Registering it directly races the declaration — the ui-slots core's
+ * load-time validation throws "not declared (a parent entry's children
+ * table must declare it)" when the parent entry is not on the ledger yet.
+ * slots.inject waits for the declaration: the callback runs synchronously
+ * when the slot is already declared, otherwise it runs inside the declaring
+ * register() call once the declaration commits; declaration collapse
+ * disposes the entry and a later declaration re-registers it. This mirrors
+ * @deepseek-ai/dsh-client-ui-deliverables' registration of the same slot.
+ */
+export declare function registerTurnTailInterception(ctx: Context, store: SidebarStore): () => void;
+/**
+ * Register the chat file-open interception: wraps BOTH file-open doors so
+ * opens land in the sidebar editor instead of the Host OS — the folder-reveal
+ * gesture ("Show in folder" passes `'.'`) is the one exception, routed to the
+ * explorer. The doors: `ctx.workspaces.openPath` (the pre-0.1.2 funnel) and
+ * `ctx.remote.session.openWorkspacePath` (the 0.1.2-alpha.1 funnel, a direct
+ * RPC that left the old door dead); each is wrapped only when present, so one
+ * build intercepts baselines on either side of the migration. Gated by BOTH
+ * the `interceptOpenPath` pref and the editor tab's enable switch; declined
+ * opens fall through to the original method. Returns the disposer restoring
+ * both doors (HMR-safe).
+ */
+export declare function registerOpenPathInterception(ctx: Context, store: SidebarStore): () => void;

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

@@ -0,0 +1,14 @@
+/**
+ * Syntax highlighting for the file editor: extension → CodeMirror language
+ * mapping. The key derivation is pure and unit-tested; the factories pull in
+ * the CodeMirror language packages (bundled into the client).
+ */
+import { Language, LanguageSupport } from '@codemirror/language';
+/** The lowercased file extension of a path ('' when none). */
+export declare function extOf(path: string): string;
+/** Language key for an extension, or null for plain text. Pure (tested). */
+export declare function languageKeyForExt(ext: string): string | null;
+/** Every language key the extension table can produce (test seam). */
+export declare function supportedLanguageKeys(): readonly string[];
+/** The CodeMirror language support for a path, or null for plain text. */
+export declare function languageForPath(path: string): Language | LanguageSupport | null;

package/lib/types/client/layout-push.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Width written to `--dsh-sidebar-width`: the app shell gives up this much
+ * of the viewport while the sidebar is open (0 while collapsed), so the
+ * conversation column (output + composer) is squeezed instead of covered.
+ * The value is capped at the viewport so a stale persisted size (e.g.
+ * fullscreen on a bigger window) can never crush the app shell to zero.
+ */
+export interface LayoutPushInput {
+    narrow: boolean;
+    panelOpen: boolean;
+    width: number;
+    viewportWidth: number;
+}
+/** Compute the live layout-push width. Narrow drawers float and push 0. */
+export declare function layoutPushSize(input: LayoutPushInput): number;

package/lib/types/client/lazy-chunk.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Lazy chunk view wrapper: mounts a component that lives in a lazy chunk,
+ * showing a loading placeholder while the chunk script loads and an error +
+ * retry affordance on failure. Used by the built-in tab/viewer descriptors.
+ *
+ * Contract note: {@link lazyChunkComponent} returns a plain render-prop
+ * function — the descriptor contract is `component: (props) => ReactNode`,
+ * and the repo renders descriptors BOTH ways: Sidebar calls
+ * `descriptor.component(props)` directly, EditorHost renders it via
+ * `createElement`. The wrapper function body therefore contains no hooks;
+ * all state lives in the inner {@link LazyChunkView} component.
+ */
+import { type ComponentType, type ReactNode } from 'react';
+import { type ChunkExports, type ChunkName } from './chunk-loader.ts';
+/**
+ * Build a descriptor-compatible lazy wrapper for a chunk-resident component.
+ * The returned function is the descriptor `component` itself: it returns an
+ * element and never calls hooks, so both invocation styles (plain function
+ * call and createElement/JSX render) work. `pick` must be a module-level
+ * function (stable identity) — an inline lambda would re-trigger the load
+ * effect on every render.
+ * @param chunk - the chunk name (see chunk-loader.ts).
+ * @param pick - select the component from the chunk's exports.
+ */
+export declare function lazyChunkComponent<P extends object>(chunk: ChunkName, pick: (mod: ChunkExports) => ComponentType<P> | undefined): (props: P) => ReactNode;

package/lib/types/client/link-intercept.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Chat/GUI external-link interception: clicking an http(s) link that points
+ * OUTSIDE the GUI (chat messages, tool rows, prose mentions) opens the
+ * sidebar instead of a new browser tab. Gated by the caller through
+ * `takeoverEnabled(url)` — the `browserInterceptLinks` master, the URL's
+ * protocol flag (`browserInterceptHttp` / `browserInterceptHttps`) and the
+ * target tab's enable switch — and a Ctrl/Cmd/Shift/Alt-modified click
+ * always bypasses the takeover so the user can still force a real browser
+ * tab.
+ *
+ * Only the GUI's OWN document is watched — links inside the browser tab's
+ * sandboxed iframe live in another document and never bubble here (and
+ * their clicks must keep working inside the sidebar).
+ */
+/** The pure decision: the URL to open in the sidebar, or null to let the
+ *  click fall through. Extracted so the policy is unit-testable without a
+ *  DOM. `anchorHref` must be the ABSOLUTE href (`<a>.href` already is).
+ *  The protocol/same-origin policy lives HERE; the prefs gates (master +
+ *  protocol flags + target enablement) live in the caller's
+ *  `takeoverEnabled(url)` callback. */
+export declare function shouldInterceptLink(anchorHref: string, selfOrigin: string): string | null;
+/** Whether a left-click may be taken over (unmodified left click only). */
+export declare function isPlainLeftClick(event: {
+    button: number;
+    metaKey: boolean;
+    ctrlKey: boolean;
+    shiftKey: boolean;
+    altKey: boolean;
+}): boolean;
+/**
+ * Register the document-level click capture that funnels external links
+ * into the sidebar. Returns the disposer (HMR-safe).
+ */
+export declare function registerLinkInterception(opts: {
+    /** Whether the takeover may happen for THIS url (the caller's prefs
+     *  gates: master switch, protocol flag, target enablement). */
+    takeoverEnabled: (url: URL) => boolean;
+    /** Open the sidebar tab at `url` (the caller resolves the target type). */
+    openInSidebar: (url: string) => void;
+    /** The GUI's own origin (window.location.origin at registration). */
+    selfOrigin: string;
+}): () => void;

package/lib/types/client/locales-ar.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The ar (Arabic) dictionary for the betterSidebar namespace.
+ *
+ * Mirrors the key set of `zh` in `locales.ts`. The sidebar's `t()`
+ * consults this dict when `attachBetterLocale(store)` has been called
+ * with an active better-locale store whose `active` is `'ar'`; absent
+ * that, the existing zh/en chain runs unchanged.
+ *
+ * Translation conventions:
+ * - Modern Standard Arabic (فصحى); UI text is RTL-ready (the framework
+ *   handles direction).
+ * - Git vocabulary follows standard Arabic localizations (إدراج، تثبيت، فرع).
+ * - Placeholders keep `{name}` verbatim (interpolation runs after lookup).
+ * - English brand names (VS Code, Cursor, Zed, SSH, Git, HTML, PDF, Markdown)
+ *   stay as-is.
+ */
+/** The ar dictionary (key-set-equal to zh, enforced by the type annotation in locales.ts). */
+export declare const ar: Record<string, string>;