dsh-coding-sidebar 1.0.0

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,124 @@
+/** 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[];
+    /** True when the working tree had more rows than `GIT_STATUS_LIMIT`; the
+     *  panel shows a truncation notice instead of freezing on a huge untracked
+     *  set (issue #369). */
+    truncated?: boolean;
+    /** Selected repository root, or the discovered roots when the cwd is a container. */
+    root?: string;
+    repositories?: string[];
+}
+/** One linked checkout returned by `git worktree list --porcelain`. */
+export interface GitWorktree {
+    /** Absolute checkout root. */
+    path: string;
+    /** Branch name without `refs/heads/`, or `HEAD` when detached. */
+    branch: string;
+    /** Whether this checkout contains the session cwd. */
+    current: boolean;
+    /** Number of staged + unstaged status rows (a file changed on both sides counts once). */
+    changes: number;
+}
+/** 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[];
+/** One raw porcelain worktree record. Prunable checkouts are retained by
+ * Git's administrative metadata after their directory disappears and must not
+ * become selectable command targets. Locked checkouts remain usable. */
+export interface GitWorktreeRecord {
+    path: string;
+    branch: string;
+    locked: boolean;
+    prunable: boolean;
+}
+/** Parse `git worktree list --porcelain` records. Production requests use
+ * `-z` so even newlines and non-ASCII bytes in checkout paths stay lossless;
+ * newline framing remains accepted for small fixtures and older Git output. */
+export declare function parseWorktreeList(output: string): GitWorktreeRecord[];
+/** 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`).
+ *  Probe timeout is short: a cwd on a stalled mount must not hold the panel
+ *  hostage for the full command budget (issue #369). */
+export declare function isGitRepo(cwd: string): Promise<boolean>;
+/** Discover the current repository or direct child repositories. Results are
+ *  cached per cwd and concurrent callers share one in-flight scan, so opening
+ *  the panel (three parallel git.* requests) costs a single discovery pass. */
+export declare function repoRoots(cwd: string): Promise<string[]>;
+/** Resolve the selected repository, defaulting to the first discovered root. */
+export declare function repoRoot(cwd: string, selected?: 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, while preserving
+ * repository discovery and explicit repository selection for workspace roots.
+ */
+export declare function status(cwd: string, selected?: string): Promise<GitStatusResult>;
+/** All linked checkouts of the repository containing `cwd`, enriched with a
+ * live change count. The current checkout is first so a single-worktree repo
+ * preserves the old UI ordering. */
+export declare function worktrees(cwd: string): Promise<GitWorktree[]>;
+/** Resolve an optional client-selected linked checkout. A caller may never use
+ * this seam to point Git operations at an unrelated repository: the target
+ * must occur in the authoritative session repository's worktree list. */
+export declare function resolveWorktree(cwd: string, requested?: string): Promise<string>;
+/** Diff text of the worktree (unstaged) or the index (staged). */
+export declare function diff(cwd: string, path: string | undefined, staged: boolean, selected?: string): Promise<string>;
+/** Stage paths (all when path is undefined). */
+export declare function stage(cwd: string, path: string | undefined, selected?: string): Promise<void>;
+/** Unstage paths (all when path is undefined). */
+export declare function unstage(cwd: string, path: string | undefined, selected?: string): Promise<void>;
+/** Commit the staged changes with a message (global identity untouched). */
+export declare function commit(cwd: string, message: string, selected?: string): Promise<void>;
+/** Branch names (current first). */
+export declare function branches(cwd: string, selected?: string): Promise<{
+    current: string;
+    names: string[];
+}>;
+/** Switch to an existing branch. */
+export declare function checkout(cwd: string, branch: string, selected?: string): Promise<void>;
+/** Recent commit history (newest first), lazily pageable via skip/count. */
+export declare function log(cwd: string, count?: number, skip?: number, selected?: string): 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, selected?: 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, selected?: 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, selected?: string): Promise<void>;
+/** Revert one commit onto the current branch with an auto-generated message. */
+export declare function revert(cwd: string, hash: string, selected?: string): Promise<void>;
+/** Cherry-pick one commit onto the current branch. */
+export declare function cherryPick(cwd: string, hash: string, selected?: 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 the workspace real-path guard — 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-coding-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-coding-sidebar`.
+ * @module dsh-coding-sidebar/invariant
+ */
+import type { Context } from './context-types.ts';
+/** Cordis companion plugin name. */
+export declare const name = "dsh-coding-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/path-security.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Resolve an existing workspace path through symlinks and enforce containment.
+ *
+ * @param cwd - Session workspace directory.
+ * @param target - Client-supplied absolute path.
+ * @returns The canonical absolute path used for the filesystem operation.
+ */
+export declare function ensureWorkspacePath(cwd: string, target: string): Promise<string>;
+/**
+ * Validate a write destination, including destinations that do not exist yet.
+ * Existing targets are resolved to catch symlinks; missing targets are checked
+ * against the nearest existing ancestor before the caller creates or renames.
+ * The returned path is rebuilt from that canonical ancestor, so an existing
+ * symlink is never left in the path passed to the write operation.
+ *
+ * @param cwd - Session workspace directory.
+ * @param target - Client-supplied absolute destination path.
+ * @returns A canonical path for an existing target or its nearest existing ancestor.
+ */
+export declare function ensureWorkspaceWritePath(cwd: string, target: string): Promise<string>;

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

@@ -0,0 +1,236 @@
+/**
+ * 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-coding-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;
+    /**
+     * Whether the model-facing `sidebar_open` tool is injected into the
+     * model's toolset — one tool that lets the model actively open a local
+     * file, a local folder (as a tree rooted there), or an HTTP(S) page in
+     * the calling session's sidebar. Off by default: the feature stays
+     * dormant until the user explicitly enables it in the side card settings.
+     */
+    agentOpenTools: 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 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;
+    /**
+     * Comma-separated allowlist of local (loopback) authorities the browser
+     * tab may navigate to — `localhost`, `127.0.0.1`, `127.0.0.1:5174`, or
+     * host:port pairs. Empty by default: loopback addresses stay blocked so a
+     * browsed page cannot probe local services. Each entry is either a bare
+     * hostname (all ports) or host:port; the GUI's own origin is always
+     * allowed regardless. The iframe sandbox still renders allowed local
+     * pages in an opaque origin, exactly like any other site.
+     */
+    browserAllowedLoopback: string;
+    /**
+     * 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;