@keith9681/dsh-sidebar 0.15.2

package/lib/types/fs-tree.d.ts

@@ -0,0 +1,51 @@
+/** One explorer row. */
+export interface SidebarFsEntry {
+    name: string;
+    path: string;
+    isDir: boolean;
+    hidden: boolean;
+    /** Whether the row is a symlink; `isDir` then describes the link's target. */
+    isSymlink: boolean;
+    /** For symlinks: the target is missing or unreadable (stat failed). */
+    broken: boolean;
+}
+/** One listed level. */
+export interface SidebarFsListing {
+    path: string;
+    entries: SidebarFsEntry[];
+    truncated: boolean;
+}
+/** Directory-first, case-insensitive name ordering (VSCode explorer order). */
+export declare function compareEntries(a: SidebarFsEntry, b: SidebarFsEntry): number;
+/**
+ * List one directory level.
+ * @param path - absolute directory path.
+ * @param maxEntries - row bound of one level (extra rows flag `truncated`).
+ * @returns the sorted listing.
+ * @throws {SidebarError} fs-error when the level is unreadable or not a directory.
+ */
+export declare function listDirectory(path: string, maxEntries?: number): Promise<SidebarFsListing>;
+/** The root row label of a listing: the last path segment (or the full path at the filesystem root). */
+export declare function rootLabel(path: string): string;
+/** Parent of a path, or undefined at the filesystem root (the explorer's "up" target). */
+export declare function parentOf(path: string): string | undefined;
+/**
+ * Normalize a caller-supplied path to an absolute, resolved path or throw
+ * fs-error. `path.isAbsolute()` is the OS's own notion of absolute: POSIX
+ * roots (`/...`), Windows drive letters (`C:\...`) and — on win32 — UNC
+ * network shares (`\\server\share\...`); drive-relative forms (`C:foo`)
+ * stay rejected.
+ */
+export declare function requireAbsolute(path: string): string;
+/**
+ * Whether `target` lies under `base` (or equals it), tolerant of separator
+ * style and — on Windows, where the filesystem is case-insensitive — of
+ * letter case. The media route uses this instead of a raw `startsWith` so a
+ * case-mismatched or mixed-separator path can never be misclassified
+ * (e.g. `C:\Users\Me` vs `c:/users/me/file.png`).
+ * @param platform - filesystem semantics; injectable so both branches are
+ * unit-testable on any host.
+ */
+export declare function isWithin(base: string, target: string, platform?: NodeJS.Platform): boolean;
+/** Message text of an unknown thrown value. */
+export declare function messageOf(error: unknown): string;

package/lib/types/git.d.ts

@@ -0,0 +1,82 @@
+/** A parsed `git status --porcelain=v1 -z` entry. */
+export interface GitStatusEntry {
+    path: string;
+    /** Two-letter index/worktree status (X Y), e.g. 'M ', ' M', 'A ', '??'. */
+    xy: string;
+}
+/** The source-control panel 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: revert / cherry-pick). */
+    hashFull: string;
+    subject: string;
+    author: string;
+    /** ISO 8601 author date (`%ai`), e.g. `2024-01-01 10:00:00 +0800`. */
+    date: string;
+    /** Ref decorations (`%D` with --decorate=short), e.g. `HEAD -> main, origin/main`; '' when none. */
+    refs: string;
+}
+/** One git failure (stderr text as the message). */
+export declare class GitCommandError extends Error {
+    readonly code: string;
+    readonly command: string;
+    constructor(message: string, code: string | undefined, command: string);
+}
+/** Parse porcelain v1 -z output into entries (rename/copy pairs collapse to one row). */
+export declare function parsePorcelainZ(output: string): GitStatusEntry[];
+/** Parse `git log --pretty=format:%h%x1f%s%x1f%an%x1f%ai%x1f%H%x1f%D` rows. */
+export declare function parseLogLines(output: string): GitLogEntry[];
+/** Whether the directory is inside a git work tree (exit-0 `git rev-parse`). */
+export declare function isGitRepo(cwd: string): Promise<boolean>;
+/** The repository top level containing `cwd` (`git rev-parse --show-toplevel`). */
+export declare function repoRoot(cwd: string): Promise<string>;
+/** The current branch name (`git rev-parse --abbrev-ref HEAD`; 'HEAD' when detached). */
+export declare function currentBranch(cwd: string): Promise<string>;
+/**
+ * Working-tree status (untracked included). `--untracked-files=all` lists
+ * the CONTENTS of new directories as individual entries (`?? newdir/a.ts`
+ * rather than a collapsed `?? newdir/`), so every row in the source-control
+ * panel is a real file whose diff tab can load. With `=normal`, git folds a
+ * new folder into one trailing-slash entry that has no diff output and
+ * cannot be read as a file.
+ */
+export declare function status(cwd: string): Promise<GitStatusResult>;
+/** Diff text of the worktree (unstaged) or the index (staged). */
+export declare function diff(cwd: string, path: string | undefined, staged: boolean): Promise<string>;
+/** Stage paths (all when path is undefined). */
+export declare function stage(cwd: string, path: string | undefined): Promise<void>;
+/** Unstage paths (all when path is undefined). */
+export declare function unstage(cwd: string, path: string | undefined): Promise<void>;
+/** Commit the staged changes with a message (global identity untouched). */
+export declare function commit(cwd: string, message: string): Promise<void>;
+/** Branch names (current first). */
+export declare function branches(cwd: string): Promise<{
+    current: string;
+    names: string[];
+}>;
+/** Switch to an existing branch. */
+export declare function checkout(cwd: string, branch: string): Promise<void>;
+/** Recent commit history (newest first), lazily pageable via skip/count. */
+export declare function log(cwd: string, count?: number, skip?: number): Promise<GitLogEntry[]>;
+/**
+ * Content of a file at a revision (`git show <rev>:<path>`), or null when the
+ * revision has no such path (a new/untracked file has no HEAD side).
+ */
+export declare function show(cwd: string, rev: string, path: string): Promise<string | null>;
+/** Full patch text of one commit (`git show` with the commit header suppressed).
+ *  Merge commits show their diff against the first parent (`-m --first-parent`
+ *  is a no-op for regular commits), so a history click always has content. */
+export declare function commitDiff(cwd: string, hash: string): Promise<string>;
+/** Discard the worktree changes of one path (`git checkout -- <path>`; the index is untouched). */
+export declare function discard(cwd: string, path: string): Promise<void>;
+/** Revert one commit onto the current branch with an auto-generated message. */
+export declare function revert(cwd: string, hash: string): Promise<void>;
+/** Cherry-pick one commit onto the current branch. */
+export declare function cherryPick(cwd: string, hash: string): Promise<void>;

package/lib/types/html-route.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Pure URL vocabulary of the /sidebar/html route (HTML previewer).
+ *
+ * Why path-encoded parameters instead of a query string: the previewed
+ * page resolves its relative assets (./style.css, img/x.png) against the
+ * document URL, and the WHATWG URL algorithm DROPS the query of a
+ * path-relative reference — `/sidebar/html?a=1&path=/a/b/` + `./style.css`
+ * would lose the session scope and the route would reject the asset.
+ * Encoding everything into the URL path keeps relative resolution inside
+ * the same route with every request self-contained:
+ *
+ *   /sidebar/html/<sessionId>/<absolute-path segments, encodeURIComponent'd>
+ *   /sidebar/html/S/Users/me/proj/index.html
+ *     + ./style.css → /sidebar/html/S/Users/me/proj/style.css
+ *   Windows: C:\Users\me\a.html → /sidebar/html/S/C%3A/Users/me/a.html
+ *   UNC (\\server\share\... or //server/share/...):
+ *     → /sidebar/html/S//server/share/proj/a.html  ('//' right after the
+ *       sessionId marks the UNC prefix; the WHATWG URL keeps '//' intact so
+ *       relative assets still resolve inside the same route)
+ *
+ * The decoder rebuilds the marker as a forward-slash `//server/share/...`
+ * path. That form is intentionally platform-neutral: `node:path` resolves it
+ * to `\\server\share\...` on win32 and `/server/share/...` on POSIX, so the
+ * host's existing requireAbsolute + isWithin fence needs no platform signal
+ * (a leading `//` is a legal POSIX absolute path, so no data is lost on
+ * either platform).
+ *
+ * This module is intentionally dependency-free (no node imports, no wire
+ * helpers) so the client bundle can import `encodeHtmlUrl` without tripping
+ * the build-time purity gate; the host converts decode failures into
+ * SidebarError responses at the route boundary.
+ */
+/** One decoded route reference. */
+export interface HtmlRouteRef {
+    sessionId: string;
+    /** Absolute file path (leading slash; Windows drives keep their colon). */
+    path: string;
+}
+/** Decode outcome: the reference, or a client-error description. */
+export type HtmlDecodeResult = {
+    ok: true;
+    ref: HtmlRouteRef;
+} | {
+    ok: false;
+    status: 400 | 404;
+    message: string;
+};
+/** The route prefix both encoders/decoders agree on. */
+export declare const HTML_ROUTE_PREFIX = "/sidebar/html/";
+/** Build the route URL for one absolute file path (client + tests). */
+export declare function encodeHtmlUrl(sessionId: string, path: string): string;
+/**
+ * Decode a route pathname into the session + absolute file path. Rejects
+ * a wrong prefix (404), an empty path, malformed percent encoding, and a
+ * missing sessionId or file path (400). The caller still must bound the
+ * decoded path with requireAbsolute + isWithin(cwd) — a decoded `..`
+ * segment resolves outside the cwd and is refused there.
+ */
+export declare function decodeHtmlUrl(pathname: string): HtmlDecodeResult;

package/lib/types/index.d.ts

@@ -0,0 +1,47 @@
+import type { Context } from './context-types.ts';
+import { Config, type ResolvedSidebarConfig, type SidebarConfig } from './config.ts';
+export { Config };
+export type { SidebarConfig, ResolvedSidebarConfig };
+export type { Context } from './context-types.ts';
+export type { BetterSidebarService, TabDescriptor, TabComponentProps, FileViewerDescriptor, FileViewerProps, FileFetchStrategy, } from './client/service.ts';
+/** Plugin identity for cordis.yml rows. */
+export declare const name = "dsh-better-sidebar";
+/** Services required before mounting: the webserver routes, the session store, the web runtime's trusted hosts, and the tool registry. */
+export declare const inject: string[];
+/** Content type served by /sidebar/file (binary-safe fallback for unknowns). */
+export declare function mediaTypeForPath(path: string): string;
+/**
+ * The live face of the side card settings namespace, bound to the settings
+ * service when it is mounted. The DSH settings RPC domain only serves
+ * allowlisted namespaces (api-proxy exposedNamespaces), so the client reads
+ * and writes THIS namespace through the plugin's own fenced /sidebar routes,
+ * which call the seam in-process — no configuration-client gate involved.
+ */
+export interface SidebarSettingsFace {
+    /** The current resolved value + revision (undefined while the settings service is absent). */
+    get(): {
+        value?: unknown;
+        revision?: number;
+    };
+    /**
+     * Whether the dsh-web-ui family's aionui-panel has been selected as the
+     * right-panel provider (the `aionui-panel` settings namespace resolves
+     * `rightPanel: 'aionui-panel'`). While true the sidebar must not mount —
+     * the two right panels are mutually exclusive. False when the namespace is
+     * absent (no aionui installed) or the provider is anything else.
+     */
+    externalDisable(): boolean;
+    /** Merge a patch (revision-guarded) and return the fresh resolved view. */
+    update(patch: Record<string, unknown>, expectedRevision?: number): Promise<{
+        value?: unknown;
+        revision?: number;
+    }>;
+}
+/**
+ * Plugin body: mount the fenced routes and the pty lifecycle.
+ * @param ctx - host plugin context (webServer, sessions, webRuntime).
+ * @param config - deployment-provided limits; the Loader validates against
+ * {@link Config} and fills defaults, direct callers get them from
+ * {@link resolveSidebarConfig}.
+ */
+export declare function apply(ctx: Context, config?: SidebarConfig): void;

package/lib/types/invariant.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Package-owned invariant companion for `dsh-better-sidebar`.
+ * @module dsh-better-sidebar/invariant
+ */
+import type { Context } from './context-types.ts';
+/** Cordis companion plugin name. */
+export declare const name = "dsh-better-sidebar-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;

package/lib/types/jobs-routes.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Background-job routes of the /sidebar JSON API ('jobs.output' /
+ * 'jobs.kill'). The job LIST needs no route: it arrives through the
+ * harness's `session/jobs` push mirror (`jobsBySession` in the sessions
+ * list feed). The routes:
+ *
+ * - 'jobs.output' — REPLAYS the output the MODEL has read so far for one
+ *   job. The source is the owner session's own event log: `tool/call` rows
+ *   of `job_output` name the job via `arguments.job_id`, and the paired
+ *   `tool/result` rows carry the finalized content the model received.
+ *   Because the session store's in-memory log can lag the live append feed
+ *   after a host restart (the store session stays frozen at its
+ *   rehydration boundary), the plugin ALSO mirrors job_output events from
+ *   the live `session/event` feed and merges both sources (deduped by seq).
+ *   This touches NO DSH source: the model's `job_output` cursor is never
+ *   consumed, and the pane stays empty until the agent reads the job.
+ * - 'jobs.kill' — the registry's stock `kill` (a pristine DSH API),
+ *   fenced by the owning session via the live agent caller. Absent registry
+ *   → 503, mirroring the settings routes' optional-service downgrade.
+ */
+import type { Context } from './context-types.ts';
+/** The two background-job routes of the sidebar API. */
+export interface SidebarJobsRoutes {
+    /** The output the model has read so far for one job (event replay, capped). */
+    output(payload: unknown): {
+        text: string;
+        truncated: boolean;
+        read: boolean;
+    };
+    /** Request cancellation of one job (live jobs flip to stopping). */
+    kill(payload: unknown): {
+        ok: true;
+        outcome: 'requested' | 'already-finished';
+    };
+}
+/**
+ * Build the jobs routes bound to the plugin context. `output` merges the
+ * owner session's own event log with the live job_output mirror; `kill`
+ * reads the jobs/agents services lazily and degrades to a 503 when the
+ * deployment lacks the registry.
+ * @param ctx - host plugin context.
+ * @param outputLimit - response cap for one output replay in bytes; longer
+ *   texts are sliced and flagged `truncated` (mirrors the fs.read cap).
+ */
+export declare function buildJobsApi(ctx: Context, outputLimit: number): SidebarJobsRoutes;

package/lib/types/open-external.d.ts

@@ -0,0 +1,24 @@
+/** The two external open actions the route accepts. */
+export type OpenExternalAction = 'reveal' | 'url';
+/** One platform opener invocation (argv array — never a shell string). */
+export interface ExternalCommand {
+    command: string;
+    args: string[];
+}
+/** Reveal/select a path in the OS file manager. On Linux there is no common
+ *  select protocol — the containing directory is opened instead (KISS). */
+export declare function revealCommand(path: string, platform?: NodeJS.Platform): ExternalCommand;
+/** Hand a custom-scheme URL to the OS protocol handler. */
+export declare function urlCommand(url: string, platform?: NodeJS.Platform): ExternalCommand;
+/** Validate a URL-scheme open target: a parseable custom-scheme URL (never
+ *  http/https — those would only dump the URL into a browser tab). */
+export declare function validateExternalUrl(raw: string): string;
+/**
+ * Launch one external open action and return immediately (detached, no
+ * stdio). Spawn failures are reported through the child's 'error' event —
+ * by then the route already returned, so the event is swallowed (the OS
+ * dialog about a missing handler is the user-visible outcome either way).
+ */
+export declare function launchExternal(action: OpenExternalAction, value: string): {
+    started: true;
+};

package/lib/types/prefs-shared.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Shared "Side card" preference vocabulary (types + constants), consumed by
+ * BOTH halves: the host registers the schemastery schema over these values
+ * (config.ts) and the client reads/writes them through the settings RPC
+ * (client/prefs.ts, client/SideCardSection.tsx). Kept free of schemastery so
+ * the browser bundle never pulls the schema runtime in.
+ */
+/** The user-settings namespace holding the side card preferences. */
+export declare const SIDEBAR_PREFS_NS = "dsh-better-sidebar";
+/** User-facing side card preferences (new-conversation defaults). */
+export interface SidebarPrefs {
+    /** Whether a brand-new conversation opens the side card by default. */
+    openByDefault: boolean;
+    /** Default panel width as a percent of the window width (20–60). */
+    defaultWidthPercent: number;
+    /**
+     * Whether the sidebar auto-activates (opens the panel) and expands the
+     * Subagent page when the current conversation spawns a new subagent.
+     */
+    autoOpenSubagent: boolean;
+    /**
+     * Whether the sidebar auto-activates (opens the panel) and expands the
+     * Jobs page when a NEW background job appears for the current
+     * conversation (any new job id, not just the first one).
+     */
+    autoOpenJobs: boolean;
+    /**
+     * Whether the model-facing agent terminal tools (terminal_create / list /
+     * send / read / wait_for / resize / signal / close) are injected into the
+     * model's toolset. Off by default: the feature stays dormant until the
+     * user explicitly enables it in the side card settings.
+     */
+    agentTerminalTools: boolean;
+    /**
+     * Custom terminal font-family stack (a CSS font-family value, e.g.
+     * `'JetBrains Mono', monospace`). Empty string follows the app's theme
+     * monospace font (`--ds-font-family-code`). Applied live to every
+     * terminal tab; configured under the terminal card's secondary settings.
+     */
+    terminalFontFamily: string;
+    /**
+     * Custom terminal font size in px (9–32). Applied live to every terminal
+     * tab; configured under the terminal card's secondary settings.
+     */
+    terminalFontSize: number;
+    /**
+     * Whether expanding the bottom panel for the FIRST time in a session tries
+     * to open a fresh terminal tab there (the terminal quota/type still gates
+     * the attempt). On by default; the switch lives under the terminal tab's
+     * row in the Side card settings.
+     */
+    bottomPanelAutoTerminal: boolean;
+    /**
+     * Whether chat-side file opens (tool-row path links, the produced-files
+     * row, prose file mentions — every path that funnels through the client
+     * runtime's `ctx.workspaces.openPath`) open in the sidebar editor instead
+     * of the Host OS's default application. On by default; the editor tab's
+     * own enable switch gates it too (both must be on for the takeover).
+     */
+    interceptOpenPath: boolean;
+    /**
+     * Whether the editor tab runs in merged mode: a path input replaces the
+     * plain header and a toggleable file-tree panel (with a global name
+     * search) docks at the tab's right edge. On by default; also makes brand
+     * new sessions seed an empty editor tab (tree panel open) instead of the
+     * explorer tab. The switch lives under the editor card's gear in the
+     * Side card settings; off restores the pre-merge editor exactly.
+     */
+    editorExplorer: boolean;
+    /**
+     * The shell the UI and agent terminals spawn (absolute path or bare
+     * executable name). Empty (default) keeps the legacy resolution order:
+     * `cordis.patch.yml` `config.shell`, then `$SHELL` / login shell /
+     * `powershell.exe` on Windows. Set it from the terminal card's gear in
+     * the Side card settings (or the yaml) to pin a specific shell — takes
+     * effect for terminals opened afterwards.
+     */
+    terminalShell: string;
+    /**
+     * Explicit arguments for `terminalShell`, space-separated (empty keeps
+     * the platform defaults; when set, they fully replace them — same
+     * contract as the yaml `shellArgs`).
+     */
+    terminalShellArgs: string;
+    /**
+     * Title-bar / shell compatibility scheme (the "位置兼容模式" setting):
+     * - `auto` (default): CONSERVATIVE — only the standard Window Controls
+     *   Overlay API (present in frameless Chromium shells that draw the
+     *   native caption buttons over web content) contributes real geometry;
+     *   without it nothing is modified, so plain-browser (web) behavior is
+     *   untouched.
+     * - `web`: EXPLICIT "DSH official web" — never adapt, not even WCO
+     *   geometry (the user declares they run the plain web UI).
+     * - `preset`: apply the built-in shell preset named by
+     *   `titleBarPresetId` (data-driven, opt-in — see shell-presets.ts).
+     * - `custom`: apply the free-form `customCss` (and the legacy
+     *   `titleBarStripPx` strip).
+     */
+    titleBarScheme: TitleBarScheme;
+    /**
+     * The built-in shell preset id applied while `titleBarScheme` is
+     * `preset` ('' = no preset — nothing extra is applied).
+     */
+    titleBarPresetId: string;
+    /**
+     * Free-form CSS injected into the page (last in the cascade, so it can
+     * override the plugin's styles; use `!important` to override JS-written
+     * inline CSS variables). Applied while `titleBarScheme` is `custom`.
+     */
+    customCss: string;
+    /**
+     * LEGACY (kept for read-migration and downgrade mirroring only): position
+     * compatibility mode flag. The UI writes `titleBarScheme` instead; a
+     * stored `true` without a scheme migrates to the `custom` scheme (with
+     * `titleBarStripPx` preserved).
+     */
+    titleBarCompat: boolean;
+    /**
+     * LEGACY (kept for read-migration and downgrade mirroring only): the
+     * reserved top strip height in px used by the `custom` scheme (0–120,
+     * default 40). Drives the `--dsh-title-bar-strip` CSS variable: the
+     * toggle cluster drops `strip + 3px` and the right panel's content
+     * starts `strip` px below its top edge.
+     */
+    titleBarStripPx: number;
+    /**
+     * Whether the HTML previewer drops its sandboxed iframe. Sandbox ON (the
+     * default) renders previewed HTML in an opaque-origin iframe that cannot
+     * touch the GUI; turning it OFF runs the previewed page with the GUI's
+     * own origin — full read/write access to session files and internal
+     * APIs. Only for trusted local content; the setting copy warns.
+     */
+    htmlViewerNoSandbox: boolean;
+    /**
+     * Whether a newly opened HTML preview starts UNSANDBOXED (the per-surface
+     * temporary unlock pre-applied). Off by default: previews open sandboxed
+     * and the status row offers the one-tap unlock; when on, previews open
+     * in the red unsandboxed state and the status row offers a one-tap
+     * restore for the current file.
+     */
+    htmlViewerDefaultUnsafe: boolean;
+    /**
+     * Whether the browser tab drops its sandboxed iframe. Sandbox ON (the
+     * default) keeps browsed sites in an opaque origin with no GUI access;
+     * turning it OFF runs any visited site with the GUI's own origin — it
+     * can read session data and act as the logged-in GUI. Only for trusted
+     * sites; the setting copy warns.
+     */
+    browserNoSandbox: boolean;
+    /**
+     * MASTER switch: whether clicking an EXTERNAL link in the GUI (chat
+     * messages, tool rows, prose mentions) is taken over into the sidebar at
+     * all. On by default; the per-protocol granularity lives in
+     * `browserInterceptHttp` / `browserInterceptHttps` (the protocol flag
+     * must also be on), and the target tab's own enable switch gates it too.
+     * Ctrl/Cmd+click always bypasses the takeover. Kept as the master so old
+     * documents keep their meaning with no migration (an explicit `false`
+     * stays "never take over").
+     */
+    browserInterceptLinks: boolean;
+    /**
+     * Whether clicking an http EXTERNAL link in the GUI opens the sidebar
+     * (the built-in browser tab, or a plugin tab that declares `urlTarget`)
+     * instead of a new browser tab. On by default; gated on the
+     * `browserInterceptLinks` master and the target tab's own enable switch.
+     */
+    browserInterceptHttp: boolean;
+    /**
+     * Whether clicking an https EXTERNAL link in the GUI opens the sidebar
+     * instead of a new browser tab. OFF by default — most https sites (e.g.
+     * GitHub) refuse iframe embedding, so the system browser is the smoother
+     * default; gated on the `browserInterceptLinks` master and the target
+     * tab's own enable switch.
+     */
+    browserInterceptHttps: boolean;
+    /**
+     * Per-tab enable switches, keyed by tab descriptor id (`'explorer'`,
+     * `'my-plugin:db'`). An ABSENT key means enabled — only an explicit
+     * `false` disables a tab type (hidden from the + menu, `openTab` refuses,
+     * and derived flows like subagent auto-open / agent-terminal tabs stop).
+     * Already-open tabs of a disabled type keep rendering (closing one
+     * prevents reopening), matching the "existing conversations keep their
+     * own layouts" rule.
+     */
+    tabsEnabled: Record<string, boolean>;
+    /**
+     * Per-viewer enable switches, keyed by file viewer descriptor id
+     * (`'image'`, `'my-plugin:csv'`). An ABSENT key means enabled; a disabled
+     * viewer is skipped by `matchFileViewer` so files fall through to the
+     * next matching viewer (or the download button when none match).
+     */
+    viewersEnabled: Record<string, boolean>;
+    /**
+     * Plugin-owned settings blobs (v0.12.0+), keyed by descriptor id: each
+     * registered tab/viewer that declares `settings.pluginToggles` (or writes
+     * through `settings.render`'s `updatePluginSetting`) persists its values
+     * here — an open map, so third-party keys need no host PrefsSchema field.
+     * Values are JSON-serializable (the row controls produce strings /
+     * numbers / booleans; custom panels are responsible for their own).
+     */
+    pluginSettings: Record<string, Record<string, unknown>>;
+}
+/** Range contract of {@link SidebarPrefs.defaultWidthPercent}. */
+export declare const WIDTH_PERCENT_MIN = 20;
+export declare const WIDTH_PERCENT_MAX = 60;
+export declare const WIDTH_PERCENT_DEFAULT = 35;
+/** Range contract of {@link SidebarPrefs.terminalFontSize}. */
+export declare const TERMINAL_FONT_SIZE_MIN = 9;
+export declare const TERMINAL_FONT_SIZE_MAX = 32;
+export declare const TERMINAL_FONT_SIZE_DEFAULT = 13;
+/** Range contract of {@link SidebarPrefs.titleBarStripPx}. */
+export declare const TITLE_BAR_STRIP_MIN = 0;
+export declare const TITLE_BAR_STRIP_MAX = 120;
+export declare const TITLE_BAR_STRIP_DEFAULT = 40;
+/** The title-bar / shell compatibility schemes (see {@link SidebarPrefs.titleBarScheme}). */
+export declare const TITLE_BAR_SCHEMES: readonly ["auto", "web", "preset", "custom"];
+export type TitleBarScheme = typeof TITLE_BAR_SCHEMES[number];
+/** Fallback prefs used whenever the settings document is unreachable or malformed. */
+export declare const SIDEBAR_PREFS_DEFAULTS: SidebarPrefs;
+/** Clamp one width percent into the contract range (shared by schema and client reads). */
+export declare function clampWidthPercent(value: number): number;
+/** Clamp one terminal font size into the contract range (shared by schema and client reads). */
+export declare function clampTerminalFontSize(value: number): number;
+/** Clamp one title-bar strip height into the contract range (shared by schema and client reads). */
+export declare function clampTitleBarStrip(value: number): number;

package/lib/types/pty-deps.d.ts

@@ -0,0 +1,78 @@
+import type * as nodePtyNs from 'node-pty';
+/** The node-pty module surface the registries consume (spawn/kill/resize/…). */
+export type NodePtyModule = typeof nodePtyNs;
+/**
+ * The node-pty version range this plugin ships. MUST stay identical to the
+ * range DSH core declares (`@deepseek-ai/dsh-subprocess-local`): the same
+ * range keeps pnpm resolving both to one physical package.
+ */
+export declare const DSH_NODE_PTY_RANGE = "^1.1.0";
+/**
+ * The WebSocket close-code-1011 reason the host sends when node-pty is
+ * unavailable. The client recognizes this exact marker and fetches the full
+ * repair details from `/sidebar/api/terminal.deps` (a WS close reason is
+ * capped at 123 bytes, so the command itself cannot ride the close frame).
+ */
+export declare const PTY_DEPS_MISSING = "pty-deps-missing";
+/** A require-compatible loader, injectable for tests. */
+export type NodePtyRequire = (id: string) => unknown;
+/**
+ * Load node-pty once (synchronously) and cache the outcome. Returns null
+ * when the package or its native binding cannot be loaded; the cause stays
+ * queryable through {@link nodePtyLoadCause}. Never throws.
+ */
+export declare function loadNodePty(requireImpl?: NodePtyRequire): NodePtyModule | null;
+/** The recorded load failure (undefined when the load succeeded or never ran). */
+export declare function nodePtyLoadCause(): unknown;
+/** Forget the cached outcome (tests only — a real reload is otherwise one-shot). */
+export declare function resetNodePtyCache(): void;
+/** Load node-pty or throw the canonical degraded-mode error (class-constructor default). */
+export declare function loadRequiredNodePty(): NodePtyModule;
+/**
+ * Detect the DSH profile directory this plugin is installed into: the
+ * nearest ancestor of the plugin module that carries both `package.json`
+ * and `pnpm-workspace.yaml` (the profile root; the plugin resolves from the
+ * profile's node_modules). Falls back to `$DSH_HOME/profiles/web` (the
+ * standard web profile), then null.
+ */
+export declare function findProfileDir(fromFile?: string): string | null;
+/** The plugin package root (walk-up from the module; works for lib/ and src/ layouts). */
+export declare function findPluginRoot(fromFile?: string): string | null;
+/** Options for {@link buildRepairCommand}. */
+export interface RepairCommandOptions {
+    /** The plugin package root (where scripts/install.sh / install.ps1 live). */
+    pluginRoot: string | null;
+    /** The detected profile directory (null → the standard `web` profile). */
+    profileDir: string | null;
+    /** Platform override for tests; defaults to the live process. */
+    platform?: NodeJS.Platform;
+}
+/**
+ * The pasteable repair command for a broken node-pty install: rerun the
+ * plugin's own installer in `--repair` mode (idempotent: it re-writes the
+ * profile's `allowBuilds: node-pty: true` and re-installs/rebuilds the
+ * dependency). Falls back to DSH's plugin command when the scripts are not
+ * shipped (exotic layouts).
+ */
+export declare function buildRepairCommand(options: RepairCommandOptions): {
+    command: string;
+    note?: string;
+};
+/** Structured status served by the `/sidebar/api/terminal.deps` endpoint. */
+export type NodePtyDepsStatus = {
+    ok: true;
+} | {
+    ok: false;
+    /** The require-time error message (module missing, native binding broken…). */
+    cause: string;
+    /** The pasteable repair command (terminal/cmd). */
+    command: string;
+    /** The detected profile name (null when undetected → the command defaults to web). */
+    profile: string | null;
+    /** Optional supplementary hint (fallback command only). */
+    note?: string;
+};
+/** Current node-pty dependency status (loaded vs degraded + repair info). */
+export declare function depsStatus(options?: {
+    fromFile?: string;
+}): NodePtyDepsStatus;