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

package/lib/types/client/markdown-html.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Raw-HTML block detection for the markdown preview. The shared `MarkdownText`
+ * renders raw HTML as literal text (a chat-security stance), so a GitHub-style
+ * README (`<div align="center">` badge walls, `<details>` collapsibles with
+ * markdown inside, table cells full of inline tags) previews as source soup.
+ * This module's pure splitter lifts those HTML runs OUT of the markdown stream
+ * before rendering: markdown runs keep flowing through `MarkdownText` (shiki /
+ * KaTeX / GFM intact, mermaid chunk path unchanged) while HTML runs render as
+ * sanitized DOM (see markdown-html.tsx).
+ *
+ * Splitting follows CommonMark's shape closely enough for real-world READMEs:
+ * a line outside code fences that starts with a block-level tag (type-6 list
+ * below) or `<!--` opens an HTML run that extends to the next blank line
+ * (comments end at the line containing `-->`). Inline-only tags (`<b>`, `<br>`,
+ * `<a>`…) never open a run — they stay in the markdown stream and are handled
+ * by the inline pass instead. Unclosed block tags (`<details>` … markdown …
+ * `</details>`) are surfaced by {@link analyzeHtmlSegment} as ordered parts so
+ * the renderer can nest the in-between markdown inside the open element, the
+ * way GitHub's linear HTML output nests.
+ */
+/** A run of raw HTML lines lifted out of the markdown stream. */
+export interface HtmlSegment {
+    kind: 'html';
+    text: string;
+}
+/** A run of markdown source (may contain non-mermaid fences, inline HTML…). */
+export interface MarkdownHtmlSegment {
+    kind: 'markdown';
+    text: string;
+}
+export type MdHtmlSegment = MarkdownHtmlSegment | HtmlSegment;
+/** The doc-wide analysis the preview consumes (all pure, unit-tested here). */
+export interface AnalyzedMarkdownHtml {
+    /** The document split into markdown / html runs (empty input → []). */
+    segments: MdHtmlSegment[];
+    /** True when at least one html run was lifted out. */
+    hasBlockHtml: boolean;
+    /** True when the source contains any tag-like text (block OR inline). */
+    hasInlineHtml: boolean;
+    /** Every reference definition found in the markdown runs (`[label]: dest`
+     *  lines), joined — appended to each markdown run so `[text][id]` keeps
+     *  resolving across the lifted HTML runs (first-match wins makes the
+     *  appended copy inert inside runs that already define it). */
+    referenceDefinitions: string;
+}
+/**
+ * CommonMark HTML-block type-6 tag names (block-level elements), lowercased.
+ * A line starting with one of these (open or close) outside a fence begins an
+ * HTML run. `<summary>` is CommonMark-inline but intentionally included: it is
+ * the idiomatic first child of a `<details>` run in GitHub-flavored READMEs.
+ */
+export declare const HTML_BLOCK_TAGS: ReadonlySet<string>;
+/** One structural piece of a lifted HTML run, in document order. */
+export type HtmlPart = {
+    kind: 'html';
+    html: string;
+} | {
+    kind: 'open';
+    tag: string;
+    attrs: string;
+} | {
+    kind: 'close';
+    tag: string;
+};
+/** The run's structure relative to the surrounding document nesting. */
+export interface HtmlSegmentShape {
+    parts: HtmlPart[];
+}
+/**
+ * Reduce a lifted HTML run to ordered parts: balanced spans become `html`
+ * leaves, unclosed open tags become `open` (a wrapper the renderer lowers
+ * following markdown runs into), unmatched closes become `close` (pops one
+ * wrapper level). A mismatched close pops through the matching open — the
+ * HTML parser's implicit-close behavior. Runs with no structural tags reduce
+ * to a single `html` part.
+ */
+export declare function analyzeHtmlSegment(source: string): HtmlSegmentShape;
+/**
+ * Split markdown source into markdown / html runs (fence-aware: an HTML-looking
+ * line inside any fenced code block is content, not a run start). Blank lines
+ * terminate HTML runs and are dropped between segments (they carry no markdown
+ * semantics the preview needs); everything else stays byte-identical.
+ */
+export declare function splitHtmlBlocks(text: string): MdHtmlSegment[];
+/**
+ * Collect the reference definitions of every markdown run (HTML runs cannot
+ * define them), in document order, newline-joined for appending.
+ */
+export declare function collectReferenceDefinitions(segments: readonly MdHtmlSegment[]): string;
+/**
+ * The whole-document gate + split the preview consumes. `hasInlineHtml` is a
+ * cheap source-level regex (code-fence content may false-positive; the inline
+ * pass skips rendered code blocks anyway, so a false positive only costs the
+ * enhanced render path, never a behavior change).
+ */
+export declare function analyzeMarkdownHtml(text: string): AnalyzedMarkdownHtml;

package/lib/types/client/markdown-images.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Markdown-preview local-image resolution. The shared `MarkdownText` (from
+ * @deepseek-ai/dsh-client-ui-primitives) only renders absolute http(s) image
+ * URLs — relative links are disabled for chat security — so a local image in
+ * a previewed `.md` (`![alt](./img.png)`, an absolute `/cwd/img.png`, or a
+ * reference definition) would otherwise fall back to its alt text. This
+ * dependency-free helper rewrites those destinations into absolute
+ * `/sidebar/file` media URLs (prefixed with the GUI's own origin) so
+ * `MarkdownText` accepts them; the host media route then serves the bytes,
+ * still restricted to files under the session cwd.
+ */
+import type { SessionScope } from './api.ts';
+/**
+ * Rewrite markdown image destinations that point at local files into
+ * absolute `/sidebar/file` media URLs. Relative destinations resolve against
+ * the opened file's directory (normalizing `.`/`..` segments); absolute
+ * local paths pass through. Remote (http/https/data/mailto) and `#`-anchor
+ * destinations are left untouched for `MarkdownText`. Reference-style images
+ * (`![x][id]` + `[id]: url`) are covered by rewriting their definition lines.
+ *
+ * Code spans (`` `...` ``) and fenced code blocks (``` ```...``` ```) are
+ * masked before rewriting so documentation that demonstrates `![alt](./img.png)`
+ * is not mutated into a `/sidebar/file` URL. Reference definitions are only
+ * rewritten when their label is actually referenced by an image (collapsed
+ * `[![][id]]`, full `![alt][id]`, or shortcut `![]` referencing the next
+ * definition) — a plain link `[text][id]` must not have its destination
+ * redirected to the media route.
+ * @param text - The raw markdown source (inline + reference images).
+ * @param scope - The session scope (sessionId + cwd) for the media route.
+ * @param filePath - The absolute path of the opened `.md` file.
+ * @param origin - The GUI's own origin (`window.location.origin`); injected
+ * so the core rewrite stays pure and unit-testable.
+ * @returns The markdown with local image destinations rewritten in place.
+ */
+/**
+ * Resolve one media destination against the session's media route: local
+ * (relative or absolute) paths become absolute `/sidebar/file` URLs (prefixed
+ * with the GUI's own origin so the shared MarkdownText http(s) allowlist
+ * accepts them), while remote URLs, `#`-anchors and empty destinations are
+ * returned untouched. Shared by the markdown image rewriter below and by the
+ * preview's raw-HTML sanitizer (`markdown-html.tsx`, which meets the same
+ * allowlist when rendering `<img src="./x.png">` inside HTML blocks).
+ */
+export declare function resolveLocalMediaDest(dest: string, scope: SessionScope, filePath: string, origin: string): string;
+export declare function rewriteLocalImageUrls(text: string, scope: SessionScope, filePath: string, origin: string): string;

package/lib/types/client/markdown-labels.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Copy-button / chrome labels for DSH's shared `MarkdownText` (DSH
+ * 0.1.2-alpha contract): the renderer takes a REQUIRED nested `labels` prop
+ * — `labels.code.copyLabel` / `labels.code.copiedLabel` for the fence copy
+ * buttons plus a screen-reader-only `labels.footnotes` heading — and the
+ * MarkdownText/CodeBlock are cordis-free, falling back to HARDCODED Chinese
+ * when the labels are omitted, so every render site threads the plugin
+ * dictionary's localized pair through here (re-evaluated per render).
+ * `footnotes` is left empty (the heading is sr-only; give it a real string
+ * only if a locale key ever earns its place in all 19 dictionaries).
+ */
+import type { ComponentProps } from 'react';
+import { MarkdownText } from '@deepseek-ai/dsh-client-ui-primitives';
+/** The flat copy-button pair the plugin threads through its own props (e.g.
+ *  MermaidMarkdownProps.codeLabels — the chunk contract stays put). */
+export interface MarkdownCopyLabels {
+    copyLabel: string;
+    copiedLabel: string;
+}
+/** MarkdownText props carrying the nested chrome labels. */
+export declare function markdownTextProps(text: string, labels: MarkdownCopyLabels): ComponentProps<typeof MarkdownText>;

package/lib/types/client/md-toc.d.ts

@@ -0,0 +1,4 @@
+import type { ReactNode } from 'react';
+/** Fewer headings than this and the button stays hidden (no outline value). */
+export declare const TOC_MIN_HEADINGS = 3;
+export declare function MdToc(): ReactNode;

package/lib/types/client/mermaid-blocks.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Markdown/mermaid fence detection for the markdown preview. The preview
+ * renders the WHOLE document through one DSH `MarkdownText` pass (so
+ * cross-fence semantics — reference-style links, footnotes, list
+ * continuity — stay intact) and the mermaid lazy chunk then swaps the
+ * rendered `language-mermaid` code blocks for diagrams. This module's pure
+ * splitter exists to detect whether the source contains a mermaid fence at
+ * all, so the mermaid chunk is only fetched when needed (unit-tested in
+ * tests/mermaid-blocks.spec.ts).
+ */
+/** One fenced mermaid diagram lifted out of the markdown source. */
+export interface MermaidBlock {
+    kind: 'mermaid';
+    /** The raw diagram source between the fences (info string stripped). */
+    code: string;
+}
+/** A span of plain markdown source (may itself contain non-mermaid fences). */
+export interface MarkdownBlock {
+    kind: 'markdown';
+    text: string;
+}
+export type MdBlock = MarkdownBlock | MermaidBlock;
+/** Props of the chunk-resident `MermaidMarkdown` component (shared contract). */
+export interface MermaidMarkdownProps {
+    /** The full markdown source (rendered in a single MarkdownText pass). */
+    text: string;
+    codeLabels: {
+        copyLabel: string;
+        copiedLabel: string;
+    };
+}
+/** CommonMark opening fence: 0-3 spaces indent + a run of 3+ backticks or tildes. */
+export declare const OPEN_FENCE_RE: RegExp;
+/** A closing-fence line: 0-3 spaces indent + 3+ backticks/tildes + trailing spaces only. */
+export declare const CLOSE_FENCE_RE: RegExp;
+/** Parse the info string from the line tail after the fence run; null when invalid. */
+export declare function fenceInfo(rest: string, fence: string): string | null;
+/**
+ * Split markdown source into md/mermaid blocks for detection: only fences
+ * whose info string names mermaid are lifted; every other line stays in the
+ * markdown stream untouched. CommonMark fence rules are honored — opening
+ * fences of 3+ backticks OR tildes, and a closing fence must use the same
+ * character with at least as many characters as the opening fence. An
+ * unterminated mermaid fence swallows the rest of the file (the same
+ * recovery CommonMark applies to open fences).
+ */
+export declare function splitMermaidBlocks(text: string): MdBlock[];

package/lib/types/client/mermaid-sanitize.d.ts

@@ -0,0 +1,2 @@
+/** A parse failure keeps nothing of the input: the caller shows the error. */
+export declare function sanitizeSvg(svg: string): string;

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

@@ -0,0 +1,12 @@
+import type { MermaidMarkdownProps } from './mermaid-blocks.ts';
+/**
+ * The chunk-resident markdown preview renderer: ONE MarkdownText pass over
+ * the full source (cross-fence reference/footnote/list semantics intact),
+ * then every rendered `language-mermaid` code block is swapped for a
+ * `MermaidDiagram`. The `.md-code-block` host stays in the React tree —
+ * only its children are replaced — so reconciliation never loses the host;
+ * a block that stops being a mermaid fence gets its original children back.
+ * Only mounted when the source contains at least one mermaid fence (see
+ * TextEditor.tsx).
+ */
+export declare function MermaidMarkdown({ text, codeLabels }: MermaidMarkdownProps): React.ReactNode;

package/lib/types/client/open-when-sized.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Deferred one-shot open for hosts that may not have a real size yet.
+ *
+ * xterm's `Terminal.open()` must not run in a zero-size container: the
+ * renderer creation fails there (the DomRenderer is built from the host's
+ * dimensions), leaving the render service's renderer `undefined`, and the
+ * next Viewport refresh crashes reading `.dimensions` off it. WebKit-based
+ * hosts (WKWebView) reliably report zero while the bottom panel's expand
+ * slide is in flight; any `display:none`-hidden ancestor does the same.
+ *
+ * The caller's `open` callback (open + fit + resize) is invoked exactly
+ * once, on the first frame where the host reports a real size. While the
+ * host stays zero-sized the polling continues every frame; it stops when
+ * the host leaves the document (`isConnected`), so a pending open never
+ * fires after unmount. The returned cancel function drops a pending frame
+ * immediately (idempotent).
+ *
+ * `raf`/`caf` are injectable so tests can drive the polling deterministically.
+ */
+export declare function openWhenSized(host: HTMLElement, open: () => void, raf?: (cb: FrameRequestCallback) => number, caf?: (id: number) => void): () => void;

package/lib/types/client/open-with-settings.d.ts

@@ -0,0 +1,4 @@
+export declare function OpenWithSettings(props: {
+    pluginSettings: Record<string, unknown>;
+    updatePluginSetting: (key: string, value: unknown) => void;
+}): import("react").JSX.Element;

package/lib/types/client/open-with.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The file tree's "open with" vocabulary: which external editors / file
+ * managers the context menu can hand a row's path to, how the per-user
+ * configuration (custom editors, SSH host, pinned ids) is parsed out of the
+ * persisted blob, and how the external URL is built (local `file` URLs and
+ * VSCode-family SSH-remote URLs).
+ *
+ * Pure by design (no React / no `api`), so the whole surface is unit-testable
+ * without a DOM or a host route. The menu and the settings panel only consume
+ * the exported types and functions.
+ */
+import type { CopyKey } from './locales.ts';
+/** One user-configured editor (persisted in `pluginSettings['editor'].openWith`). */
+export interface CustomEditor {
+    id: string;
+    /** Human label shown in the menu (e.g. "Windsurf"). */
+    name: string;
+    /** URL template with a `{path}` placeholder (e.g. `cursor://file/{path}`). */
+    urlTemplate: string;
+    /** Whether the editor speaks the VSCode URL dialect — the only editors
+     *  with an SSH-remote form (`<scheme>://vscode-remote/ssh-remote+<host>/…`). */
+    isVscodeFamily: boolean;
+}
+/** The per-user "open with" configuration (one key of the editor blob). */
+export interface OpenWithConfig {
+    /** SSH host (user@host or an ~/.ssh/config alias); '' = local workspace. */
+    sshHost: string;
+    /** User-defined editors, appended after the built-ins. */
+    customEditors: CustomEditor[];
+    /** Ids of open-with targets pinned to the menu's top level
+     *  ('explorer' | 'vscode' | 'cursor' | 'zed' | 'custom:<id>'). */
+    pinned: string[];
+}
+/** One menu-visible open target (built-in or custom, SSH-filtered). */
+export interface OpenWithTarget {
+    /** Stable id (`explorer` / `vscode` / `cursor` / `zed` / `custom:<id>`). */
+    id: string;
+    /** Locale key of a built-in label (custom editors carry `name` instead). */
+    nameKey?: CopyKey;
+    /** User-defined label (custom editors only; '' for built-ins). */
+    name: string;
+    /** 'reveal' = show in the OS file manager; 'url' = open a URL. */
+    kind: 'reveal' | 'url';
+    /** URL template with `{path}`; undefined for reveal targets. */
+    urlTemplate?: string;
+    /** Whether the editor talks the VSCode URL dialect. */
+    isVscodeFamily: boolean;
+    /** Hidden in SSH mode (a host-local opener cannot reach a remote path). */
+    localOnly: boolean;
+}
+/** The default open-with configuration (fresh documents). */
+export declare const OPEN_WITH_DEFAULTS: OpenWithConfig;
+/** The built-in open targets, in menu order. */
+export declare const OPEN_WITH_BUILTINS: readonly OpenWithTarget[];
+/**
+ * Parse the persisted `openWith` blob (tolerant): malformed fields fall back
+ * to the defaults, malformed custom-editor rows are dropped, and pinned ids
+ * are kept verbatim (unknown ids are pruned when the targets are resolved —
+ * the menu is the only consumer of the resolved list).
+ */
+export declare function parseOpenWithConfig(raw: unknown): OpenWithConfig;
+/**
+ * The menu-visible open targets, in order (built-ins then custom editors).
+ * In SSH mode the local-only targets (the OS file manager, Zed, custom
+ * editors without the VSCode dialect) are dropped — they cannot reach a
+ * remote path. Unknown pinned ids are pruned here too.
+ */
+export declare function resolveOpenWithTargets(config: OpenWithConfig): OpenWithTarget[];
+/** The SSH hint appended to a target's label in remote mode. */
+export declare function openWithSshActive(config: OpenWithConfig): boolean;
+/**
+ * The URL to open for one resolved target, or undefined when the target has
+ * no URL form (reveal) or the template is malformed. The path is inserted
+ * RAW into the template (browsers percent-encode as needed; VSCode-family
+ * URL parsers consume the absolute path with its leading slash, e.g.
+ * `vscode://file//home/u/f.ts` or `vscode://file/C:/Users/u/f.ts`).
+ */
+export declare function openWithUrl(target: OpenWithTarget, path: string, config: OpenWithConfig): string | undefined;
+/** Normalize a filesystem path for embedding in a URL (backslashes → '/'). */
+export declare function normalizeUrlPath(path: string): string;
+/** A fresh custom-editor id (uuid when available, time-based fallback). */
+export declare function newCustomEditorId(): string;
+/** Validate one custom-editor row before the settings panel accepts it. */
+export declare function isValidCustomEditor(row: {
+    name: string;
+    urlTemplate: string;
+}): boolean;

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

@@ -0,0 +1,52 @@
+/**
+ * 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;
+    /** Route a folder-reveal gesture ("Show in folder" passes '.') into the sidebar explorer. */
+    revealInExplorer(path: string, sessionId: string): void;
+}
+/**
+ * Whether a path is the "Show in folder" folder-reveal gesture. The stock
+ * ui-deliverables row passes `'.'` (the session workspace root, resolved by
+ * the chat view to `"<cwd>/."`); any path whose final segment is `.` is the
+ * same gesture. A directory has no editor content, so these opens must reach
+ * the explorer instead of an editor tab.
+ */
+export declare function isFolderRevealPath(path: string): boolean;
+/**
+ * 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. The one exception is the folder-reveal gesture,
+ * which is routed to {@link OpenPathInterceptDeps.revealInExplorer} instead.
+ * @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,43 @@
+/**
+ * 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.
+ *
+ * This module is dependency-free (no node:path in the client bundle): the
+ * host is the authority for path semantics, so this mirror deliberately
+ * accepts a SUPERSET of absolute forms — anything a Windows host would emit
+ * (drive letters, UNC) plus POSIX roots. A form the host would reject
+ * (e.g. a backslash UNC path on a POSIX host) passes through here and then
+ * fails loudly in the host's requireAbsolute instead of being silently
+ * joined onto the cwd.
+ */
+/**
+ * Mirror of the host's absolute-path notion (see fs-tree.requireAbsolute):
+ * POSIX roots, Windows drive letters, and Windows UNC network shares in
+ * both backslash (`\\server\share\...`) and forward-slash
+ * (`//server/share/...`) form. Deliberately a superset — see the module
+ * comment — so a produced UNC path is never joined onto the cwd.
+ */
+export declare function isAbsolutePath(path: string): boolean;
+/**
+ * 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;
+/**
+ * Whether `target` lies under `base` (or equals it), tolerant of separator
+ * style and — on Windows-style drive paths — of letter case. A client-side
+ * mirror of the host's `isWithin` (fs-tree.ts) used to decide whether a
+ * git-derived path can be opened in the editor (a linked worktree outside
+ * the session workspace cannot: the host's workspace fence would reject it).
+ */
+export declare function isWithinWorkspace(base: string, target: string): boolean;

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

@@ -0,0 +1,86 @@
+/**
+ * Cross-session pinned-terminal resolution (v0.17.0+).
+ *
+ * A pinned terminal tab lives in its HOME session's state (the only
+ * authoritative copy) — switching sessions never copies or projects it.
+ * The viewer session's TabBar renders the tabs OTHER sessions have pinned
+ * as VIRTUAL tabs appended to the first leaf's tab list, so the user sees
+ * them inline with their own tabs. Clicking a virtual tab activates it
+ * in-place: TerminalView connects to the home session's PTY via WebSocket
+ * (sessionId + tab query params resolve to the home PTY on the host side),
+ * so the terminal renders in the current workbench without jumping sessions.
+ *
+ * Visibility rule:
+ *
+ * | pin.scope | visible when |
+ * |-----------|--------------|
+ * | `global`  | any session (cwd-independent) |
+ * | `workspace` | `viewer.cwd === tab.pin.homeCwd` (both undefined match; viewer.cwd unknown → conservative visible) |
+ *
+ * The "viewer.cwd unknown → visible" branch is intentional: during
+ * hydration the session summary may carry no cwd yet, and hiding pinned
+ * workspace tabs on first paint would flash them away. Once the cwd
+ * resolves, the next store notify re-runs the resolver with the real cwd.
+ *
+ * The viewer's OWN session is excluded: its pinned tabs are already on its
+ * own tab strip, so rendering them again as virtual tabs would double-show.
+ * Tabs whose `pin` field is missing or whose `type` is not `'terminal'` are
+ * ignored — only terminal tabs can be pinned.
+ */
+import type { SidebarState, SidebarTab, SplitNode } from './state.ts';
+/** A pinned terminal surfaced to the viewer, paired with its home session. */
+export interface PinnedTabEntry {
+    tab: SidebarTab;
+    homeSessionId: string;
+}
+/** A viewer's session identity for visibility resolution. */
+export interface PinnedViewer {
+    sessionId: string;
+    cwd: string | undefined;
+}
+/** The home-session scope stored on a pinned virtual tab's meta, so
+ *  TerminalView connects to the home session's PTY (not the viewer's). */
+export interface PinnedHomeScope {
+    sessionId: string;
+    cwd: string | undefined;
+    /** The original tab id in the home session (TerminalView's `tab` param). */
+    tabId: string;
+}
+/** Whether a tab id is a pinned virtual id (prefixed). */
+export declare function isPinnedVirtualId(tabId: string): boolean;
+/** Parse a pinned virtual id into its home session id and original tab id.
+ *  Format: `pinned:<homeSessionId>:<originalTabId>` — session ids are UUIDs
+ *  (no colons), so the first colon after the prefix delimits the session. */
+export declare function parsePinnedVirtualId(tabId: string): {
+    homeSessionId: string;
+    tabId: string;
+};
+/** Extract the home scope from a pinned virtual tab's meta (undefined for
+ *  regular tabs). */
+export declare function getPinnedHomeScope(tab: SidebarTab): PinnedHomeScope | undefined;
+/** Whether a tab is a pinned virtual tab (injected from another session). */
+export declare function isPinnedVirtualTab(tab: SidebarTab): boolean;
+/** Create a virtual SidebarTab for a pinned entry. The virtual id is unique
+ *  (prefixed with home session) to avoid collision with the viewer's own
+ *  tab ids; the original id is stored in meta for TerminalView. */
+export declare function createPinnedVirtualTab(entry: PinnedTabEntry): SidebarTab;
+/** Inject pinned virtual tabs into the first leaf of a split tree, and
+ *  override that leaf's `active` when a pinned tab is activated. Returns
+ *  the original tree when there are no pinned tabs and no active override. */
+export declare function injectPinnedIntoTree(tree: SplitNode, pinned: readonly SidebarTab[], activePinnedId: string | null): SplitNode;
+/**
+ * Whether a pinned tab is visible to the viewer session. Conservative on
+ * unknown cwd: a `workspace` pin with no `homeCwd` is visible everywhere
+ * (the pin was set before the home session's cwd resolved), and a viewer
+ * whose cwd is unknown sees every workspace pin (avoids hydration flash).
+ */
+export declare function pinnedVisibleTo(tab: SidebarTab, viewer: PinnedViewer): boolean;
+/**
+ * Collect every pinned terminal visible to the viewer across ALL cached
+ * session states. Excludes the viewer's own session (those tabs are on its
+ * own strip). Order is stable: sessions in the cache's insertion order,
+ * tabs in tree order (splits → bottomSplits → floats) within each session
+ * — the order tabs were opened/pinned, so the rail never reorders between
+ * renders.
+ */
+export declare function collectPinnedTabs(bySession: ReadonlyMap<string, SidebarState>, viewer: PinnedViewer): PinnedTabEntry[];

package/lib/types/client/plugin-settings.d.ts

@@ -0,0 +1,8 @@
+import type { SidebarStore } from './state.ts';
+/**
+ * Merge one plugin-owned settings blob of one descriptor and persist it.
+ * @param store - the sidebar store (its prefs are replaced by the write result).
+ * @param descriptorId - the descriptor whose blob is patched ('editor' here).
+ * @param updater - pure patch function; receives a shallow copy of the blob.
+ */
+export declare function updatePluginSettings(store: SidebarStore, descriptorId: string, updater: (blob: Record<string, unknown>) => Record<string, unknown>): void;

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

@@ -0,0 +1,27 @@
+/**
+ * Shared vocabulary of the recommended plugin catalogs: the entry shape and
+ * the GitHub topic URL. The two catalogs live in sibling modules —
+ * `plugins-tabs.ts` (tab registrations) and `plugins-viewers.ts` (file
+ * previewer registrations) — and are shown in the two "add plugin" modals
+ * (Side card settings → the dashed cards at the end of the 侧边栏内容 /
+ * 文件预览 grids).
+ */
+/** The GitHub topic page listing every repo tagged `dsh-better-sidebar`. */
+export declare const PLUGIN_TOPIC_URL = "https://github.com/topics/dsh-better-sidebar";
+/** One curated plugin entry (name / url / description / install script). */
+export interface PluginEntry {
+    /** Unique id (the npm package name). */
+    id: string;
+    /** Short display name. */
+    name: string;
+    /** GitHub repository URL. */
+    url: string;
+    /** One-line description (i18n friendly: string or () => string). */
+    description: string | (() => string);
+    /** Optional catalog group heading (i18n friendly); entries without one
+     *  render under the plain list (a flat catalog stays flat). */
+    category?: string | (() => string);
+    /** The full shell command pre-filled into the install terminal (not
+     *  executed until the user presses Enter). */
+    install: string;
+}

package/lib/types/client/plugins-tabs.d.ts

@@ -0,0 +1,3 @@
+import type { PluginEntry } from './plugins-shared.ts';
+/** Tab-registration plugins (alphabetical order). */
+export declare const builtinTabPlugins: readonly PluginEntry[];

package/lib/types/client/plugins-viewers.d.ts

@@ -0,0 +1,3 @@
+import type { PluginEntry } from './plugins-shared.ts';
+/** File-previewer plugins (alphabetical order). */
+export declare const builtinViewerPlugins: readonly PluginEntry[];

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

@@ -0,0 +1,41 @@
+/**
+ * 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 { clampTerminalFontSize, clampTitleBarStrip, clampWidthPercent, SIDEBAR_PREFS_DEFAULTS, TITLE_BAR_SCHEMES, TITLE_BAR_STRIP_DEFAULT, type SidebarPrefs, type TitleBarScheme } from '../prefs-shared.ts';
+export { SIDEBAR_PREFS_DEFAULTS, TITLE_BAR_SCHEMES, TITLE_BAR_STRIP_DEFAULT, clampTerminalFontSize, clampTitleBarStrip, clampWidthPercent, };
+export type { SidebarPrefs, TitleBarScheme };
+/** 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>;
+/**
+ * Read the external-disable flag from the same settings route: the
+ * dsh-web-ui family's aionui-panel provider choice. True only when the host
+ * resolved `aionui-panel.rightPanel` to 'aionui-panel' — while true the
+ * sidebar must not mount (the two right panels are mutually exclusive). Any
+ * failure (route rejected, aionui absent, malformed response) reads false,
+ * so a missing family never hides the sidebar.
+ * @param settings - the settings wire face (the plugin api by default).
+ * @returns the external-disable flag (false on any failure).
+ */
+export declare function loadExternalDisable(settings: SidebarSettingsClient): Promise<boolean>;