dsh-better-sidebar 0.10.0

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

@@ -0,0 +1,170 @@
+import type { BrowserProbeResult } from './browser.ts';
+/** One wire failure. */
+export declare class SidebarApiError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Explorer row (host fs-tree shape). */
+export interface FsEntry {
+    name: string;
+    path: string;
+    isDir: boolean;
+    hidden: boolean;
+}
+/** Git status entry (host git shape). */
+export interface GitStatusEntry {
+    path: string;
+    xy: string;
+}
+/** Git status snapshot. */
+export interface GitStatusResult {
+    isRepo: boolean;
+    branch?: string;
+    entries: GitStatusEntry[];
+}
+/** One git log row. */
+export interface GitLogEntry {
+    /** Short hash (7+ chars, display). */
+    hash: string;
+    /** Full 40-char hash (advanced operations). */
+    hashFull: string;
+    subject: string;
+    author: string;
+    /** ISO 8601 author date (`%ai`). */
+    date: string;
+    /** Ref decorations (--decorate=short), e.g. `HEAD -> main, origin/main`; '' when none. */
+    refs: string;
+}
+/** Text read result. */
+export interface FsTextResult {
+    kind: 'text';
+    content: string;
+    truncated: boolean;
+}
+/** Binary read result (no content; images load through the media route).
+ *  `head` carries the first bytes (base64) for viewer detect sniffing. */
+export interface FsBinaryResult {
+    kind: 'binary';
+    size: number;
+    truncated: boolean;
+    head: string;
+}
+/**
+ * One jobs.output response: the output the MODEL has read so far for the
+ * job (replayed from the owner session's event log — the model's
+ * job_output cursor is never touched, so the pane can never steal the
+ * agent's bytes). `read` is false until the model actually called
+ * job_output for the job.
+ */
+export interface JobOutputResult {
+    text: string;
+    /** True when the host capped the text at its output limit. */
+    truncated: boolean;
+    /** Whether the model has read the job at least once. */
+    read: boolean;
+}
+/** One request's session scope: the conversation id plus its cwd when known. */
+export interface SessionScope {
+    sessionId: string;
+    /** The session's working directory from the client list summary (optional). */
+    cwd?: string;
+}
+/** The sidebar API surface (session scope threaded through every call). */
+export declare const api: {
+    sessionCwd: (scope: SessionScope, signal?: AbortSignal) => Promise<{
+        sessionId: string;
+        cwd: string;
+        root: string;
+        parent: string | null;
+    }>;
+    fsTree: (scope: SessionScope, path: string, signal?: AbortSignal) => Promise<{
+        path: string;
+        entries: FsEntry[];
+        truncated: boolean;
+    }>;
+    fsRead: (scope: SessionScope, path: string, signal?: AbortSignal) => Promise<FsTextResult | FsBinaryResult>;
+    fsWrite: (scope: SessionScope, path: string, content: string) => Promise<{
+        ok: true;
+    }>;
+    gitStatus: (scope: SessionScope, signal?: AbortSignal) => Promise<GitStatusResult>;
+    gitDiff: (scope: SessionScope, path: string | undefined, staged: boolean, signal?: AbortSignal) => Promise<{
+        diff: string;
+    }>;
+    gitStage: (scope: SessionScope, path?: string) => Promise<{
+        ok: true;
+    }>;
+    gitUnstage: (scope: SessionScope, path?: string) => Promise<{
+        ok: true;
+    }>;
+    gitCommit: (scope: SessionScope, message: string) => Promise<{
+        ok: true;
+    }>;
+    gitBranch: (scope: SessionScope, signal?: AbortSignal) => Promise<{
+        current: string;
+        names: string[];
+    }>;
+    gitCheckout: (scope: SessionScope, branch: string) => Promise<{
+        ok: true;
+    }>;
+    /** Recent commit history, lazily pageable (skip/count; defaults 0/30). */
+    gitLog: (scope: SessionScope, count?: number, skip?: number, signal?: AbortSignal) => Promise<GitLogEntry[]>;
+    /** Full patch text of one commit (diff display for the history rows). */
+    gitCommitDiff: (scope: SessionScope, hash: string, signal?: AbortSignal) => Promise<{
+        diff: string;
+    }>;
+    /** Discard the worktree changes of one file (the index is untouched). */
+    gitDiscard: (scope: SessionScope, path: string) => Promise<{
+        ok: true;
+    }>;
+    /** Revert one commit onto the current branch. */
+    gitRevert: (scope: SessionScope, hash: string) => Promise<{
+        ok: true;
+    }>;
+    /** Cherry-pick one commit onto the current branch. */
+    gitCherryPick: (scope: SessionScope, hash: string) => Promise<{
+        ok: true;
+    }>;
+    /** Release a terminal's process immediately (tab closed; the WS close frame
+     *  may be unreachable while the socket is down, so the host also accepts
+     *  this explicit route). */
+    ptyClose: (scope: SessionScope, tab: string) => Promise<{
+        ok: true;
+    }>;
+    /** Release an agent terminal by uuid (tab closed while WS was down). */
+    agentPtyClose: (uuid: string) => Promise<{
+        ok: true;
+    }>;
+    /**
+     * The output the model has read so far for one background job (replayed
+     * from the owner session's event log — never the model's job_output
+     * cursor). The scope MUST be the job's OWNER session.
+     */
+    jobOutput: (scope: SessionScope, id: string, signal?: AbortSignal) => Promise<JobOutputResult>;
+    /** Request cancellation of one background job (live jobs flip to stopping). */
+    jobKill: (scope: SessionScope, id: string, reason?: string) => Promise<{
+        ok: true;
+        outcome: "requested" | "already-finished";
+    }>;
+    /** Read the side card preferences (plugin-global, no session scope). */
+    settingsGet: () => Promise<{
+        value?: unknown;
+        revision?: number;
+    }>;
+    /** Merge a patch into the side card preferences (revision-guarded). */
+    settingsUpdate: (patch: Record<string, unknown>, expectedRevision?: number) => Promise<{
+        value?: unknown;
+        revision?: number;
+    }>;
+    /** Probe a URL's response headers (the sidebar browser's embeddability
+     *  check; see the host's browser.probe route). */
+    browserProbe: (url: string, signal?: AbortSignal) => Promise<BrowserProbeResult>;
+};
+/** Absolute URL of the media route for one path (images only). */
+export declare function mediaUrl(scope: SessionScope, path: string): string;
+/** Absolute URL of the download route: serves raw bytes (binary-safe) with
+ *  `Content-Disposition: attachment`, so the browser saves the file. */
+export declare function downloadUrl(scope: SessionScope, path: string): string;
+/** Absolute URL of the HTML preview route (see html-route.ts): the path is
+ *  fully encoded so the previewed page's relative assets resolve back into
+ *  the same route with the session scope intact. */
+export declare function htmlUrl(scope: SessionScope, path: string): string;

package/lib/types/client/binary-download.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The "no preview — download instead" pane: shown by the editor host when no
+ * viewer can render a file (binary without a registered renderer, or the
+ * `binary-download` strategy) and registered as the `binary-download` viewer
+ * component so the declarative route and the host fallback share one UI.
+ */
+import type { ReactNode } from 'react';
+import type { SessionScope } from './api.ts';
+export declare function BinaryDownload(props: {
+    scope: SessionScope;
+    path: string;
+}): ReactNode;

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

@@ -0,0 +1,12 @@
+/** Viewport widths strictly below this are "mobile" (paired CSS: max-width: 767px). */
+export declare const NARROW_MAX_WIDTH = 768;
+/** Whether a viewport width is narrow (mobile). */
+export declare function isNarrowWidth(width: number): boolean;
+/**
+ * Live narrow-viewport flag for components. Reads `window.innerWidth` and
+ * re-measures on resize (rAF-throttled, the repo's existing drag pattern).
+ * Deliberately avoids `matchMedia` (jsdom does not implement it) — the
+ * resize listener is equally exact for a breakpoint that never changes
+ * while the page is open.
+ */
+export declare function useNarrowViewport(): boolean;

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

@@ -0,0 +1,50 @@
+/**
+ * Pure URL policy for the built-in browser tab: normalize user input into
+ * an http(s) URL, and refuse destinations that would be dangerous to embed
+ * in the sidebar iframe. Kept dependency-free so it is unit-testable.
+ *
+ * The iframe sandbox (opaque origin, no allow-same-origin / top-navigation)
+ * is the primary security boundary; this module is the address-bar gate on
+ * top of it: only http/https may be navigated, and loopback addresses are
+ * refused so a browsed page cannot probe local services by user action.
+ * The GUI's OWN origin is explicitly ALLOWED — the user may open the GUI
+ * itself in the sidebar (debugging, mirroring); the sandbox still renders
+ * it in an opaque origin with no same-origin privileges, exactly like any
+ * other site.
+ */
+/** Why a navigation attempt was refused. */
+export type BrowserBlockReason = 'scheme' | 'loopback';
+/** Result of normalizing one address-bar input. */
+export type BrowserNavigateResult = {
+    kind: 'ok';
+    url: string;
+} | {
+    kind: 'blocked';
+    reason: BrowserBlockReason;
+} | {
+    kind: 'invalid';
+};
+/** One browser.probe wire result (host fetch of the target's headers). */
+export interface BrowserProbeResult {
+    reachable: boolean;
+    /** The final (post-redirect) URL; present when reachable. */
+    url?: string;
+    status?: number;
+    xFrameOptions?: string;
+    /** The CSP frame-ancestors source list; present when the directive exists. */
+    frameAncestors?: string[];
+}
+/** Embeddability verdict of one probe. */
+export type Embeddability = 'embeddable' | 'blocked' | 'unknown';
+/**
+ * Decide whether a site can render inside the sidebar iframe. The signals
+ * are exactly the ones the BROWSER enforces when it refuses an iframe load:
+ * X-Frame-Options DENY/SAMEORIGIN, or a frame-ancestors directive that does
+ * not allow `*` ('self' here means the SITE's own origin — never ours, so
+ * it also blocks the sidebar). A site we could not reach yields 'unknown'
+ * and the plain iframe stays.
+ */
+export declare function embeddabilityOf(probe: BrowserProbeResult): Embeddability;
+/** A loopback hostname (localhost, IPv6 ::1, 127.0.0.0/8, 0.0.0.0). */
+export declare function isLoopbackHostname(hostname: string): boolean;
+export declare function normalizeBrowserUrl(input: string, selfOrigin: string): BrowserNavigateResult;

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

@@ -0,0 +1,17 @@
+/**
+ * Built-in registration: the plugin registers its own tab pages and file
+ * previewers through the same {@link BetterSidebarService} external plugins
+ * use — eating its own dogfood. The descriptors live next to their feature
+ * modules (tabs.tsx / viewers.tsx); this module only aggregates them and
+ * owns the disposer lifecycle (cordis auto-invokes it on fiber disposal,
+ * HMR-safe).
+ */
+import type { Context } from '../../context-types.ts';
+import type { BetterSidebarService } from '../service.ts';
+/**
+ * Register all built-in tabs and viewers with the service. Returns a
+ * disposer that unregisters everything (cordis auto-invokes it on fiber
+ * disposal). The `ctx` is threaded into tab descriptors that need it
+ * (EditorHost reads `ctx.betterSidebar` for file-viewer matching).
+ */
+export declare function registerBuiltins(ctx: Context, service: BetterSidebarService): () => void;

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

@@ -0,0 +1,6 @@
+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;
+/** The 7 built-in tab descriptors. */
+export declare function builtinTabs(ctx: Context): readonly TabDescriptor[];

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

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

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

@@ -0,0 +1,74 @@
+/**
+ * Lazy chunk loader for the client bundle. The heavy preview/terminal
+ * libraries (Univer, docx-preview, pptx-renderer, CodeMirror, xterm — the
+ * office/terminal/editor stacks, tens of 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.
+ *
+ * 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.
+ * - 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 resetChunks}, which drops the
+ * in-memory cache (and any test registry), so a hot-reloaded core bundle
+ * re-fetches and re-executes the current chunk scripts on the next lazy
+ * open. Chunk-only source edits still need a manual page refresh (the HMR
+ * poll watches only client.js).
+ */
+export type ChunkName = 'docx' | 'xlsx' | 'pptx' | 'terminal' | 'editor';
+/** 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.
+ */
+export declare const CHUNK_EXTERNALS: readonly string[];
+/** 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).
+ */
+export declare function resetChunks(): void;

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

@@ -0,0 +1,8 @@
+/**
+ * Lazy chunk entry: the .docx preview (docx-preview + jszip). Built as
+ * `lib/client-docx.js` and registered under `dsh-better-sidebar/docx` —
+ * fetched only when a .docx 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 the office library into the startup path.
+ */
+export { DocxView } from '../docx-view.tsx';

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-better-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/pptx.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Lazy chunk entry: the .pptx preview (pptx-renderer). Built as
+ * `lib/client-pptx.js` and registered under `dsh-better-sidebar/pptx` —
+ * fetched only when a .pptx 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 the renderer into the startup path.
+ */
+export { PptxView } from '../PptxView.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-better-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/chunks/xlsx.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Lazy chunk entry: the .xlsx preview (Univer family + SheetJS, several MB).
+ * Built as `lib/client-xlsx.js` and registered under
+ * `dsh-better-sidebar/xlsx` — fetched only when a .xlsx 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 Univer into the
+ * startup path.
+ */
+export { XlsxView } from '../xlsx-view.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/docx-view.d.ts

@@ -0,0 +1,8 @@
+import { type OfficeViewProps } from './office-shared.tsx';
+/**
+ * Render a .docx file via docx-preview. The library renders into a container
+ * div (no canvas); images and styles are inlined. Unmounting clears the
+ * container's innerHTML — docx-preview has no dispose API, but tearing down
+ * the DOM is enough.
+ */
+export declare function DocxView(props: OfficeViewProps): JSX.Element;

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/icons.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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;
+/**
+ * Bottom-panel toggle glyph (the "底栏" button): a frame with a filled strip
+ * along its BOTTOM edge, in the app's outline style.
+ */
+export declare const IconPanelBottomOutline16: ({ 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;
+/** 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;
+/** Word viewer glyph: a document frame with a "W". */
+export declare const IconDocxOutline16: ({ size, className }: IconProps) => import("react").JSX.Element;
+/** Excel viewer glyph: a spreadsheet grid. */
+export declare const IconXlsxOutline16: ({ size, className }: IconProps) => import("react").JSX.Element;
+/** PowerPoint viewer glyph: a chart with rising bars. */
+export declare const IconPptxOutline16: ({ 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;

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,10 @@
+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). */
+export declare const inject: string[];
+/**
+ * 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,20 @@
+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;
+/** The intercepted produced-files row (visual twin of the deliverables chips). */
+export declare function SidebarProducedFiles(props: {
+    matched: readonly string[];
+    openInSidebar: (path: string) => void;
+}): import("react").JSX.Element;
+/** Register the turn-tail interception (returns the disposer). */
+export declare function registerTurnTailInterception(ctx: Context, store: SidebarStore): () => void;
+/**
+ * Register the chat file-open interception: wraps `ctx.workspaces.openPath`
+ * — the single funnel every chat-side file open goes through (tool-row path
+ * links, the produced-files row, prose mentions) — so opens land in the
+ * sidebar editor instead of the Host OS. 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 the original (HMR-safe).
+ */
+export declare function registerOpenPathInterception(ctx: Context, store: SidebarStore): () => void;