@chatcode/cco-better-sidebar 0.18.0-alpha.0

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

@@ -0,0 +1,11 @@
+export declare const RELEASE_NOTE_ACK_KEY = "dsh-better-sidebar:release-note:acknowledged-version";
+/** Detect an existing installation before createSidebarStore can write any state. */
+export declare function hasPriorSidebarInstall(storage: Storage): boolean;
+interface ReleaseNotesDialogProps {
+    packageName: string;
+    version: string;
+    priorInstall: boolean;
+}
+/** Upgrade-only, exact-version release-note dialog. Closing it acknowledges this version. */
+export declare function ReleaseNotesDialog({ packageName, version, priorInstall }: ReleaseNotesDialogProps): JSX.Element | null;
+export {};

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

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

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

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

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

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

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

@@ -0,0 +1,8 @@
+import type { Context } from '../context-types.ts';
+import { type SidebarStore } from './state.ts';
+/** Public CLI documentation opened by the persistent top-right manual action. */
+export declare const USER_MANUAL_URL = "https://chatcode.chinaunicom.cn/doc/cli/";
+export declare function Sidebar(props: {
+    ctx: Context;
+    store: SidebarStore;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,54 @@
+/**
+ * The tab strip of one pane: tabs capped at TAB_MAX_WIDTH (ellipsized),
+ * overflow scrolls horizontally, a close button per tab, a four-way split
+ * button cluster, and the + menu that opens new tabs (explorer / git /
+ * terminal). Tabs are draggable; dropping onto another tab inserts before it,
+ * dropping on the strip background appends to this pane. Right-clicking a
+ * tab opens the tab context menu (float as a free window / close / close
+ * others / close to the left / close to the right, the close ones scoped to
+ * this pane).
+ */
+import { type ReactNode } from 'react';
+import type { SidebarTab } from './state.ts';
+/** One + menu option. */
+export interface NewTabOption {
+    id: string;
+    label: string;
+    disabled?: boolean;
+    /** Leading icon (Menu row). */
+    icon?: ReactNode;
+}
+/** Drag payload for tab moves (HTML5 DnD dataTransfer). */
+export declare const TAB_DRAG_TYPE = "application/x-dsh-tab";
+export interface TabDragPayload {
+    tabId: string;
+    paneId: string;
+}
+export declare function serializeDrag(payload: TabDragPayload): string;
+export declare function parseDrag(raw: string): TabDragPayload | null;
+export declare function TabBar(props: {
+    paneId: string;
+    tabs: SidebarTab[];
+    active: string | null;
+    onActivate: (tabId: string) => void;
+    onClose: (tabId: string) => void;
+    onNewTab: (optionId: string) => void;
+    newTabOptions: NewTabOption[];
+    /** Drop of a tab from any pane: (payload, insertBeforeTabId | null). */
+    onDropTab: (payload: TabDragPayload, before: string | null) => void;
+    /** Float a tab out as a free window (the tab context menu's entry; the
+     *  drag-to-conversation gesture is handled at the Sidebar shell level). */
+    onFloatTab: (tabId: string) => void;
+    /**
+     * Pin/unpin a terminal tab (v0.17.0+). Called with `'workspace'` or
+     * `'global'` to pin (the shell snapshots the home cwd), or `null` to
+     * unpin. Non-terminal tabs never trigger this callback. Optional: the
+     * menu hides the pin entry when unset (legacy callers).
+     */
+    onPinTab?: (tabId: string, scope: 'workspace' | 'global' | null) => void;
+    /** Icon resolver for tab labels (reads from the tab descriptor registry). */
+    getTabIcon?: (tab: SidebarTab) => ReactNode;
+    /** Badge resolver for tab labels (reads the descriptor's `badge`; the
+     *  resolver returns the rendered pill or null). */
+    getTabBadge?: (tab: SidebarTab) => ReactNode;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,24 @@
+import '@xterm/xterm/css/xterm.css';
+import { type SessionScope, type TerminalDepsStatus } from './api.ts';
+import { type SidebarStore } from './state.ts';
+/** The degraded-mode payload rendered by {@link TerminalDepsBanner}. */
+type TerminalDepsInfo = Extract<TerminalDepsStatus, {
+    ok: false;
+}>;
+export declare function TerminalView(props: {
+    scope: SessionScope;
+    tabId: string;
+    store: SidebarStore;
+}): import("react").JSX.Element;
+/**
+ * The node-pty dependency failure banner (issue #140): explains that the
+ * terminal's native dependency failed to load and shows the PASTEABLE repair
+ * command (bash / cmd / PowerShell) with a copy button — the user pastes it
+ * into a terminal where their DSH profile lives and runs it, then retries.
+ * Extracted as a standalone component for direct testing.
+ */
+export declare function TerminalDepsBanner(props: {
+    deps: TerminalDepsInfo;
+    onRetry: () => void;
+}): import("react").JSX.Element;
+export {};

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

@@ -0,0 +1,10 @@
+import type { FileViewerProps } from './service.ts';
+/**
+ * The sandbox tokens of the HTML preview iframe. NO allow-same-origin (the
+ * preview must stay in an opaque origin — with the route's own origin it
+ * could read session data) and NO allow-top-navigation (a previewed page
+ * must not hijack the GUI). The user can disable the sandbox per-feature
+ * in the side card settings (warned); the toggle below reflects it.
+ */
+export declare const HTML_IFRAME_SANDBOX = "allow-scripts allow-popups allow-downloads allow-modals";
+export declare function TextEditor(props: FileViewerProps): import("react").JSX.Element;

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

@@ -0,0 +1,27 @@
+import type { SidebarStore } from './state.ts';
+import type { OpenWithTarget } from './open-with.ts';
+export declare function TreePanel(props: {
+    sessionId: string;
+    cwd: string | undefined;
+    /** The sidebar store (passed through to the tree's fence-refusal notice). */
+    store: SidebarStore;
+    expanded: string[];
+    revealed: string[];
+    onToggle: (path: string) => void;
+    onOpenFile: (path: string) => void;
+    /** File context-menu "open in a new tab" (passed through to FileTree). */
+    onOpenFileNewTab?: (path: string) => void;
+    /** File context-menu "open to the side" (passed through to FileTree). */
+    onOpenFileSide?: (path: string) => void;
+    /** The "open with" menu surface (passed through to FileTree; absent →
+     *  the whole section is hidden). */
+    openWithTargets?: OpenWithTarget[];
+    openWithPinned?: string[];
+    openWithSsh?: boolean;
+    onOpenWith?: (targetId: string, path: string) => void;
+    onToggleOpenWithPin?: (targetId: string) => void;
+    onReferenceFile: (path: string) => void;
+    /** Full-window presentation: the panel fills its host instead of docking
+     *  at a fixed width. */
+    full?: boolean;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,10 @@
+interface UpdateDialogProps {
+    open: boolean;
+    onClose: () => void;
+    /** 'dialog' wraps content in a full-screen overlay; 'inline' renders the
+     *  same content bare so it can sit inside the host Settings panel without
+     *  a second backdrop. */
+    variant?: 'dialog' | 'inline';
+}
+export declare function UpdateDialog({ open, onClose, variant }: UpdateDialogProps): JSX.Element | null;
+export {};

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

@@ -0,0 +1 @@
+export declare function UpdateSettingsPanel(): JSX.Element;

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

@@ -0,0 +1,10 @@
+/**
+ * The "更新" settings section: a dedicated nav entry in the DSH Settings
+ * shell (sibling of 侧边卡片 / Token 用量 / AI 代码占比) hosting the
+ * one-click ChatCode upgrade entry. It surfaces the reusable
+ * {@link UpdateSettingsPanel} row in the section body.
+ */
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+/** Full section props: the settings shell's runtime share (close, …). */
+export type UpdateSettingsSectionProps = PropsRuntime<'settings.section'>;
+export declare function UpdateSettingsSection(_props: UpdateSettingsSectionProps): JSX.Element;

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

@@ -0,0 +1,20 @@
+/**
+ * Full-window upload progress over the files tree: a blurred scrim (same mask
+ * token as the repo's Modal primitive) with a card showing the target
+ * directory, file-level progress, and a cancel button. Esc cancels too —
+ * clicking the scrim does not, so a stray click can never abort an upload.
+ * Rendered inside TreePanel (absolute inset-0), so it covers only the file
+ * window and never the conversation column.
+ */
+import { type ReactNode } from 'react';
+export declare function UploadOverlay(props: {
+    /** Absolute upload directory (the session workspace or a tree directory). */
+    dir: string;
+    done: number;
+    total: number;
+    /** Relative path of the file being uploaded ('' when none is in flight). */
+    current: string;
+    onCancel: () => void;
+    /** True while cancellation is in flight (disables the cancel button). */
+    cancelling?: boolean;
+}): ReactNode;

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

@@ -0,0 +1,4 @@
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+/** Full section props: the settings shell's runtime share (close, …). */
+export type UsageHeatmapSectionProps = PropsRuntime<'settings.section'>;
+export declare function UsageHeatmapSection(_props: UsageHeatmapSectionProps): import("react").JSX.Element;

package/lib/types/client/add-plugin-modal.d.ts

@@ -0,0 +1,15 @@
+import type { BetterSidebarService } from './service.ts';
+/** Which extension point the modal is adding a plugin for. */
+export type PluginKind = 'tab' | 'viewer';
+/** The modal body: the GitHub topic button + the recommended plugin list
+ *  with per-entry jump/copy buttons (extracted for direct testing). */
+export declare function PluginListBody(props: {
+    service: BetterSidebarService;
+    kind: PluginKind;
+}): import("react").JSX.Element;
+/** The modal itself (mounted only while open — see the module comment). */
+export declare function AddPluginModal(props: {
+    service: BetterSidebarService;
+    onClose: () => void;
+    kind: PluginKind;
+}): import("react").JSX.Element;