dsh-better-sidebar 0.10.0

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

@@ -0,0 +1,12 @@
+/**
+ * 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;
+/** 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/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,35 @@
+/**
+ * Chat/GUI external-link interception: clicking an http(s) link that points
+ * OUTSIDE the GUI (chat messages, tool rows, prose mentions) opens the
+ * sidebar browser instead of a new browser tab. Gated by BOTH the
+ * `browserInterceptLinks` pref and the browser tab's enable switch; 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). */
+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 browser. Returns the disposer (HMR-safe).
+ */
+export declare function registerLinkInterception(opts: {
+    takeoverEnabled: () => boolean;
+    /** Open the sidebar browser tab at `url` (the caller resolves the session). */
+    openInSidebar: (url: string) => void;
+    /** The GUI's own origin (window.location.origin at registration). */
+    selfOrigin: string;
+}): () => void;

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

@@ -0,0 +1,237 @@
+/**
+ * Minimal zh/en copy for the sidebar. The copy follows the DSH i18n system:
+ * the client apply attaches the locale service (`ctx.locale`, provided by
+ * `@deepseek-ai/dsh-client-locale`) through {@link attachLocale}, and
+ * `t()`/`isZh()` resolve the active locale from it — the Host-backed
+ * `locale.preference` wins over the raw browser language and switches live.
+ * Without an attached service (standalone/test compositions) the browser
+ * language is used, matching the previous behavior. The dictionaries are
+ * also registered into the DSH locale registry under {@link LOCALE_NS}.
+ */
+/** The zh dictionary (also registered into the DSH locale registry under {@link LOCALE_NS}). */
+export declare const zh: {
+    explorer: string;
+    git: string;
+    terminal: string;
+    editor: string;
+    newTab: string;
+    openExplorer: string;
+    openGit: string;
+    newTerminal: string;
+    terminalLimit: string;
+    close: string;
+    collapse: string;
+    expand: string;
+    collapseBottomPanel: string;
+    expandBottomPanel: string;
+    terminalError: string;
+    terminalConnectFailed: string;
+    terminalRetry: string;
+    preview: string;
+    edit: string;
+    refresh: string;
+    save: string;
+    saved: string;
+    unsaved: string;
+    saveFailed: string;
+    truncation: string;
+    binary: string;
+    loading: string;
+    error: string;
+    retry: string;
+    splitLeft: string;
+    splitRight: string;
+    splitUp: string;
+    splitDown: string;
+    notRepo: string;
+    noChanges: string;
+    stage: string;
+    unstage: string;
+    stageAll: string;
+    unstageAll: string;
+    commitPlaceholder: string;
+    commit: string;
+    commitError: string;
+    branch: string;
+    checkoutError: string;
+    history: string;
+    changes: string;
+    staged: string;
+    unstaged: string;
+    cancel: string;
+    diffEmpty: string;
+    diffLoadError: string;
+    diffBinary: string;
+    diffAdded: string;
+    diffDeleted: string;
+    diffRenamed: string;
+    diffExpand: string;
+    diffCollapse: string;
+    discard: string;
+    discardTitle: string;
+    discardDesc: string;
+    viewCommitDiff: string;
+    copyShortHash: string;
+    copyFullHash: string;
+    copySubject: string;
+    revertCommit: string;
+    revertTitle: string;
+    revertDesc: string;
+    cherryPickCommit: string;
+    cherryPickTitle: string;
+    cherryPickDesc: string;
+    timeJustNow: string;
+    timeMinutesAgo: string;
+    timeHoursAgo: string;
+    timeYesterday: string;
+    loadMore: string;
+    historyLoadError: string;
+    produced: string;
+    producedOpen: string;
+    disconnected: string;
+    exited: string;
+    noSession: string;
+    pluginNotLoaded: string;
+    hiddenFiles: string;
+    parent: string;
+    copied: string;
+    copy: string;
+    newFile: string;
+    openEditor: string;
+    gitDetail: string;
+    referenceFile: string;
+    addToConversation: string;
+    copyRelative: string;
+    copyAbsolute: string;
+    download: string;
+    settingsNav: string;
+    settingsOpenTitle: string;
+    settingsOpenDesc: string;
+    settingsWidthTitle: string;
+    settingsWidthDesc: string;
+    settingsWidthSuffix: string;
+    settingsOpenPathTitle: string;
+    settingsOpenPathDesc: string;
+    settingsSaveFailed: string;
+    settingsConflict: string;
+    binaryNoPreview: string;
+    downloadToView: string;
+    officeTooLarge: string;
+    officeCorrupt: string;
+    officeEncrypted: string;
+    officeLoadFailed: string;
+    previousSlide: string;
+    nextSlide: string;
+    zoom: string;
+    zoomHint: string;
+    settingsSubagentTitle: string;
+    settingsSubagentDesc: string;
+    settingsJobsTitle: string;
+    settingsJobsDesc: string;
+    settingsToolsTitle: string;
+    settingsToolsDesc: string;
+    settingsBottomTerminalTitle: string;
+    settingsBottomTerminalDesc: string;
+    settingsTabsTitle: string;
+    settingsViewersTitle: string;
+    settingsGeneralTitle: string;
+    settingsPopup: string;
+    settingsViewerCatchAll: string;
+    viewerImage: string;
+    viewerPdf: string;
+    viewerDocx: string;
+    viewerXlsx: string;
+    viewerPptx: string;
+    viewerMarkdown: string;
+    viewerCode: string;
+    viewerBinary: string;
+    viewerHtml: string;
+    browser: string;
+    browserPlaceholder: string;
+    browserGo: string;
+    browserBack: string;
+    browserForward: string;
+    browserStart: string;
+    browserBlockedScheme: string;
+    browserBlockedLoopback: string;
+    browserInvalid: string;
+    browserNoSandboxWarning: string;
+    htmlNoSandboxWarning: string;
+    sandboxStatusOn: string;
+    sandboxUnlock: string;
+    sandboxRestore: string;
+    settingsHtmlDefaultUnsafeTitle: string;
+    settingsHtmlDefaultUnsafeDesc: string;
+    settingsHtmlSandboxTitle: string;
+    settingsHtmlSandboxDesc: string;
+    settingsBrowserSandboxTitle: string;
+    settingsBrowserSandboxDesc: string;
+    settingsBrowserLinksTitle: string;
+    settingsBrowserLinksDesc: string;
+    browserOpenExternal: string;
+    browserEmbedBlocked: string;
+    browserEmbedBlockedDesc: string;
+    browserEmbedAnyway: string;
+    subagent: string;
+    openSubagent: string;
+    subagentMainAgent: string;
+    subagentEmpty: string;
+    subagentEmptyDesc: string;
+    subagentRunning: string;
+    subagentInactive: string;
+    subagentModeOneShot: string;
+    subagentModeContinuable: string;
+    subagentCount: string;
+    subagentCountRunning: string;
+    subagentDiagCorrupt: string;
+    subagentDiagUnsupported: string;
+    subagentDiagUnavailable: string;
+    subagentThinking: string;
+    jobs: string;
+    jobsCount: string;
+    jobsCountRunning: string;
+    jobStatusRunning: string;
+    jobStatusStopping: string;
+    jobStatusCompleted: string;
+    jobStatusKilled: string;
+    jobStatusFailed: string;
+    jobDurationSeconds: string;
+    jobDurationMinutes: string;
+    jobDurationHours: string;
+    jobViewOutput: string;
+    jobHideOutput: string;
+    jobNoOutput: string;
+    jobNotReadYet: string;
+    jobOutputTruncated: string;
+    jobOutputError: string;
+    jobKill: string;
+    jobKillConfirm: string;
+    jobKillError: string;
+};
+/** The en dictionary (key-set-equal to zh, enforced by the type annotation). */
+export declare const en: Record<keyof typeof zh, string>;
+/**
+ * The dictionary namespace this plugin owns in the DSH locale registry
+ * (`'sidebar'` is taken by DSH's own ui-sidebar, hence this distinct name).
+ */
+export declare const LOCALE_NS = "betterSidebar";
+/**
+ * Attach (or detach, with undefined) the DSH locale service. The sidebar
+ * mounts its own React root outside the slot system's locale seat, so the
+ * service rides this module-level holder: components keep calling the plain
+ * `t()` function, and the Sidebar root's locale subscription re-renders the
+ * whole tree on switches.
+ */
+export declare function attachLocale(service: {
+    getSnapshot(): {
+        active: string;
+    };
+} | undefined): void;
+/** Translate a copy key in the active locale (zh → zh, else en). */
+export type CopyKey = keyof typeof zh;
+/** Translate a copy key; `{name}` placeholders interpolate from `params`. */
+export declare function t(key: CopyKey, params?: Record<string, string | number>): string;
+/** Whether the active locale is Chinese (used for selectors). */
+export declare function isZh(): boolean;
+/** Format an ISO 8601 author date relative to now (刚刚 / N 分钟前 / N 小时前 / 昨天 / date). */
+export declare function relativeTime(iso: string): string;

package/lib/types/client/office-shared.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared pieces of the Office preview views (docx / xlsx): the load-state
+ * union, the shared props, and the download fallback. The two views live in
+ * their own modules (docx-view.tsx / xlsx-view.tsx) so the bundler can emit
+ * them as separate lazy chunks — docx-preview and the Univer family (several
+ * MB) must never share a script (see docs/plans/2026-08-12-lazy-chunks-design.md).
+ */
+import { type SessionScope } from './api.ts';
+/** Loading / ready / error state shared by both views. */
+export type LoadState = {
+    status: 'loading';
+} | {
+    status: 'ready';
+} | {
+    status: 'error';
+    message: string;
+};
+/** Shared props. */
+export interface OfficeViewProps {
+    scope: SessionScope;
+    path: string;
+    title: string;
+}
+/**
+ * The shared error / fallback affordance: the failure reason plus a download
+ * link, so the user always has a path to the file. Used by both DocxView and
+ * XlsxView, and matches the binary placeholder download link.
+ */
+export declare function BinaryFallback(props: {
+    scope: SessionScope;
+    path: string;
+    message: string;
+}): JSX.Element;

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

@@ -0,0 +1,36 @@
+/**
+ * Office file type dispatch — pure functions mapping file extensions to
+ * preview kinds. Kept separate from the editor host so the mapping is
+ * unit-testable without mounting React or pulling in docx-preview / Univer.
+ *
+ * The host side never inspects Office extensions: the binary NUL probe in
+ * {@link ../index.ts} (readText) tags every Office file as binary, and the
+ * /sidebar/file media route serves raw bytes for any extension. This module
+ * is the client's sole source of truth for "is this previewable here".
+ */
+/** Extensions rendered with docx-preview (preserved styles/images/tables). */
+export declare const OFFICE_DOCX_EXT: ".docx";
+/** Extensions rendered with Univer (sheets: data + formulas + formatting). */
+export declare const OFFICE_XLSX_EXT: ".xlsx";
+/** Extensions rendered with the browser-native PPTX viewer. */
+export declare const OFFICE_PPTX_EXT: ".pptx";
+/** Extensions that get a download-only affordance (no client-side renderer). */
+export declare const OFFICE_DOWNLOAD_ONLY_EXT: readonly string[];
+/**
+ * The preview strategy for one path's extension.
+ * - `'docx'` — render via docx-preview.
+ * - `'xlsx'` — render via Univer.
+ * - `'pptx'` — render via pptx-renderer.
+ * - `'download-only'` — show the binary download button (no preview renderer
+ *   covers legacy OLE .doc/.xls/.ppt on the client).
+ * - `null` — not an Office file; the caller's existing image / md / text / binary
+ *   pipeline handles it.
+ */
+export type OfficeKind = 'docx' | 'xlsx' | 'pptx' | 'download-only' | null;
+/**
+ * Map a lowercased extension (with leading dot) to its preview kind.
+ *
+ * @param ext - the path extension (with leading dot) (`.docx`,
+ *   `.xlsx`, `.pptx`, `.doc`, `.xls`, `.ppt`, …); `''` when the path has none.
+ */
+export declare function officeKindForExt(ext: string): OfficeKind;

package/lib/types/client/office-view.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Compat re-export shim for the historical `src/client/office-view.tsx`
+ * path. The office preview views were split into docx-view.tsx /
+ * xlsx-view.tsx (+ office-shared.tsx) so the bundler can emit each library
+ * as its own lazy chunk (see docs/plans/2026-08-12-lazy-chunks-design.md).
+ * This module keeps deep imports of this path resolvable through the
+ * `./src/*` exports subpath — it deliberately re-exports BOTH views, so it
+ * must never be imported from the core bundle or a chunk entry (it would
+ * drag both libraries into that bundle).
+ */
+export { DocxView } from './docx-view.tsx';
+export { XlsxView } from './xlsx-view.tsx';

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

@@ -0,0 +1,41 @@
+/**
+ * Interception of the chat's file-open funnel. The client runtime's
+ * `ctx.workspaces.openPath` is the SINGLE door every chat-side file open goes
+ * through — ui-conversation's apply.ts resolves the path against the session
+ * cwd and calls it for tool-row path links, the produced-files row, and
+ * prose file mentions alike (verified against the DSH source:
+ * `packages/client/ui-conversation/src/client/apply.ts` is the only
+ * production caller). Wrapping that one method reroutes those opens into the
+ * sidebar editor instead of the Host OS — no DSH modification needed.
+ *
+ * The wrapper is dependency-free by design (no React / ui-primitives), so
+ * the takeover logic is unit-testable and the file stays importable from the
+ * test runtime.
+ */
+/** The one service method the wrapper replaces (mirror of the runtime IWorkspaces). */
+export interface OpenPathService {
+    openPath(path: string): Promise<void>;
+}
+/** Per-call decisions the wrapper needs (wired to the store + ctx in the client half). */
+export interface OpenPathInterceptDeps {
+    /**
+     * Whether to take over this call: the `interceptOpenPath` pref AND the
+     * editor tab's own enable switch must both be on (an editor that cannot
+     * open must not swallow opens — they fall through to the Host).
+     */
+    takeoverEnabled(): boolean;
+    /** The session whose scope the sidebar editor loads the file in (current session). */
+    currentSessionId(): string | undefined;
+    /** Route the open into the sidebar editor (the established openSidebarFile). */
+    openInSidebar(path: string, sessionId: string): void;
+}
+/**
+ * Wrap `workspaces.openPath`: intercepted calls open the file in the sidebar
+ * editor instead of the Host OS and resolve as success (the original's
+ * callers ignore the result); anything that declines falls through to the
+ * original method untouched.
+ * @param workspaces - the client workspaces service to wrap.
+ * @param deps - per-call takeover decisions.
+ * @returns the disposer restoring the original method (HMR-safe).
+ */
+export declare function wrapOpenPath(workspaces: OpenPathService, deps: OpenPathInterceptDeps): () => void;

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

@@ -0,0 +1,19 @@
+/**
+ * Path projection helpers shared by the explorer rows: a path relative to
+ * the session cwd (for the @-reference button and "copy relative path").
+ * The fs-tree joins with '/' even on Windows, so both separators normalize
+ * to '/' before comparison.
+ */
+/**
+ * The path relative to the session's working directory.
+ * @param cwd - the explorer root (absolute).
+ * @param path - an absolute entry path from the fs-tree.
+ * @returns the relative path with '/' separators ('.' for the cwd itself),
+ * or `path` unchanged when it lies outside the cwd.
+ *
+ * The prefix test is case-insensitive: Windows paths (and macOS's
+ * case-insensitive volumes) may arrive with different casing than the cwd
+ * row, and the containment decision must not depend on it. The returned
+ * relative text keeps the caller's own casing.
+ */
+export declare function relativeTo(cwd: string, path: string): string;

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

@@ -0,0 +1,2 @@
+/** Pure PDF extension dispatch, separate from React for unit testing. */
+export declare function isPdfExt(ext: string): boolean;

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

@@ -0,0 +1,30 @@
+/**
+ * Client-side read of the user-facing "Side card" preferences. The host owns
+ * the namespace through the settings seam (in-process); the DSH settings RPC
+ * domain only serves allowlisted namespaces to configuration clients, so the
+ * client reads and writes THIS namespace through the plugin's own fenced
+ * /sidebar routes instead (api.settingsGet/settingsUpdate). Any failure
+ * (route rejected, namespace absent, a field of the wrong type, a value out
+ * of the contract range) falls back to the schema defaults — the side card
+ * must keep working exactly as composed when the settings surface is missing.
+ */
+import type { api } from './api.ts';
+import { clampWidthPercent, SIDEBAR_PREFS_DEFAULTS, type SidebarPrefs } from '../prefs-shared.ts';
+export { SIDEBAR_PREFS_DEFAULTS, clampWidthPercent };
+export type { SidebarPrefs };
+/** The settings wire face the preferences need (a subset of the plugin api). */
+export type SidebarSettingsClient = Pick<typeof api, 'settingsGet' | 'settingsUpdate'>;
+/** Validate one raw resolved value into {@link SidebarPrefs}. Used for the
+ * settings.get payload AND the settings.update response (both carry the
+ * layered resolved value); any malformed field falls back to its default.
+ * @param value - the raw resolved section from the settings wire.
+ * @returns validated prefs (always well-formed).
+ */
+export declare function parsePrefs(value: unknown): SidebarPrefs;
+/**
+ * Read the resolved side card preferences through the plugin's settings route.
+ * @param settings - the settings wire face (the plugin api by default).
+ * @returns validated prefs, or the schema defaults when the route rejects,
+ * the namespace is absent, or a stored value violates the contract.
+ */
+export declare function loadPrefs(settings: SidebarSettingsClient): Promise<SidebarPrefs>;

package/lib/types/client/produced-files.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Pure derivation of one turn's produced files from finalized conversation
+ * nodes — a structural replica of ui-deliverables' `producedForClosing`
+ * (the mutation tools' follow-along `locations`, by render intent: a diff
+ * card or a generic edit card; reads/deletes/failures produce nothing).
+ * Kept dependency-free so the takeover logic is unit-testable and the
+ * replica is easy to diff against upstream when it drifts.
+ */
+/** Paths a tool-result view reports as produced, by render intent. */
+export declare function producedPaths(view: unknown): readonly string[];
+/**
+ * Files produced by the turn the assistant at `seq` closes. Accumulation
+ * resets on turn boundaries (a user message, or a node reporting a different
+ * turn number); paths keep first-seen order and appear once.
+ * @param nodes - snapshot nodes in surface order (structural, unknown-safe).
+ * @param seq - the closing assistant's seq (the render site's anchor).
+ * @returns produced paths; empty when the turn wrote nothing.
+ */
+export declare function producedForClosing(nodes: readonly unknown[], seq: number): readonly string[];
+/**
+ * Claim the turn-tail chain only when the closing turn produced files.
+ * @param owner - the turn-tail owner currency ({nodes, seq}).
+ * @returns produced paths as the matched value, or null to decline.
+ */
+export declare function selectProducedFiles(owner: unknown): readonly string[] | null;
+/** Resolve a (possibly relative) path against the session cwd for the sidebar. */
+export declare function resolveSidebarPath(cwd: string | undefined, path: string): string;

package/lib/types/client/selection-payload.d.ts

@@ -0,0 +1,27 @@
+/** Max inserted selection length (UTF-16 code units, i.e. JS `.length`). */
+export declare const SELECTION_LIMIT = 500;
+/** The source line span a selection maps to (1-based, inclusive). */
+export interface SelectionLines {
+    start: number;
+    end: number;
+}
+/**
+ * The fence info line: `rel[:start[-end]]` — lines are omitted entirely
+ * when unknown (the preview reverse-search missed).
+ */
+export declare function headerOf(path: string, cwd: string | undefined, lines?: SelectionLines): string;
+/**
+ * The full text appended to the composer draft for one selection.
+ * Over the limit the content is dropped: the plain path line is the whole
+ * payload (an empty fenced block would just occupy the draft).
+ */
+export declare function buildSelectionInsert(path: string, cwd: string | undefined, lines: SelectionLines | undefined, selected: string): string;
+/**
+ * Reverse-map a rendered-DOM selection back to source line numbers. The
+ * preview selection is plain text (block boundaries come out as `\n`), so
+ * this is a best-effort substring search: a single trailing newline is
+ * stripped first (DOM block selections tend to carry one), and only an
+ * EXACTLY-ONE occurrence yields lines — an ambiguous or missing match
+ * returns null (the header then carries the path without line numbers).
+ */
+export declare function linesOfSelection(source: string, selected: string): SelectionLines | null;