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

package/src/invariant.ts

@@ -0,0 +1,32 @@
+/**
+ * Package-owned invariant companion for `dsh-better-sidebar`.
+ * @module dsh-better-sidebar/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from './context-types.ts'
+
+const PACKAGE_NAME = 'dsh-better-sidebar'
+
+/** Cordis companion plugin name. */
+export const name = 'dsh-better-sidebar-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: the sidebar owns no service state or event protocol
+ * of its own — every route is mounted under the host's webServer fence, the
+ * pty lifecycle is exercised by the smoke spec, and the panel's store is a
+ * plain snapshot registry asserted by the behavior specs. The route fence,
+ * pty quota, and store semantics are each observed through their seams.
+ */
+const install: () => void = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

package/src/login-route.ts

@@ -0,0 +1,26 @@
+import { readFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Context, SidebarHttpRequest, SidebarHttpResponse } from './context-types.ts'
+
+const assetPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'assets', 'logo.svg')
+
+function page(logo: string): string {
+  return `<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>请登录 ChatCode</title><style>
+*{box-sizing:border-box}body{margin:0;min-width:320px;min-height:100vh;display:grid;place-items:center;font-family:Inter,"Microsoft YaHei",system-ui,sans-serif;color:#172b4d;background:radial-gradient(circle at 18% 18%,#e5edff 0,transparent 30rem),linear-gradient(135deg,#edf2fb,#dfe8f7)}.card{width:min(490px,calc(100vw - 40px));padding:34px 44px 36px;border:1px solid #dce4ef;border-radius:18px;background:#fff;box-shadow:0 20px 48px rgba(36,62,103,.18),0 2px 8px rgba(36,62,103,.06)}.brand{display:flex;align-items:center;justify-content:center;gap:12px;padding-bottom:27px;border-bottom:1px solid #edf0f5}.brand img{width:34px;height:34px}.brand strong{font-size:22px;letter-spacing:-.02em}.content{padding-top:40px;text-align:center}.content h1{margin:0;font-size:28px;line-height:1.3;font-weight:650}.content p{min-height:24px;margin:12px 0 30px;color:#71809a;font-size:14px;line-height:1.7}.action{width:100%;min-height:46px;border:0;border-radius:8px;background:#9B0B09;color:#fff;font:600 15px/1 Inter,"Microsoft YaHei",sans-serif;cursor:pointer;box-shadow:0 8px 18px rgba(155,11,9,.25);transition:transform .18s ease,box-shadow .18s ease,background .18s ease}.action:hover:not(:disabled){transform:translateY(-2px);background:#b20d0a;box-shadow:0 12px 24px rgba(155,11,9,.38)}.action:focus-visible{outline:3px solid #f0b7b5;outline-offset:3px}.action:disabled{cursor:default;opacity:.7}.error{color:#b42318}@media(max-width:480px){.card{padding:30px 26px}.content{padding-top:32px}}
+</style></head><body><main class="card"><div class="brand"><img src="data:image/svg+xml;base64,${logo}" alt=""><strong>ChatCode</strong></div><section class="content"><h1>请登录 ChatCode</h1><p id="message">请登录后继续使用。</p><button id="login" class="action" type="button">去登录</button></section></main><script>
+const message=document.getElementById('message'),button=document.getElementById('login');const current=new URL(location.href);const returnTo=(()=>{const v=current.searchParams.get('return');return v&&v.startsWith('/')&&!v.startsWith('//')?v:'/'} )();const call=async(name,body={})=>{const r=await fetch('/sidebar/api/'+name,{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify(body)});const d=await r.json();if(!r.ok||!d.ok)throw new Error(d.error?.message||'操作失败');return d.value};let waiting=false;async function status(){try{const s=await call('chatcode.status');if(s.available&&s.validation==='valid'&&!s.expired){location.replace(returnTo);return}if(waiting)message.textContent='正在等待浏览器完成登录…'}catch{message.textContent='无法读取登录状态，请稍后重试。';message.classList.add('error')}}async function login(){const tab=window.open('','_blank');button.disabled=true;button.textContent='正在打开登录页…';message.classList.remove('error');try{const s=await call('chatcode.start');waiting=true;if(tab&&!tab.closed){tab.opener=null;tab.location.href=s.url;message.textContent='请在新打开的浏览器窗口完成登录…'}else{message.innerHTML='浏览器拦截了登录窗口，请 <a href="'+s.url+'" target="_blank" rel="noopener noreferrer">打开登录页</a> 后完成登录。'}}catch{try{tab&&tab.close()}catch{}button.disabled=false;button.textContent='去登录';message.textContent='登录页打开失败，请重试。';message.classList.add('error')}}button.addEventListener('click',login);status();setInterval(status,2000);
+</script></body></html>`
+}
+
+export function registerLoginRoute(ctx: Context, fence: (req: SidebarHttpRequest) => boolean): () => void {
+  return ctx.webServer.register({ kind: 'exact', path: '/sidebar/login', handler: async (req, res) => {
+    if (!fence(req)) { res.writeHead(403); res.end('forbidden'); return }
+    if (req.method !== 'GET' && req.method !== 'HEAD') { res.writeHead(405); res.end(); return }
+    try {
+      const logo = (await readFile(assetPath)).toString('base64')
+      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'content-security-policy': "default-src 'self'; img-src 'self' data:; style-src 'unsafe-inline'; script-src 'unsafe-inline'" })
+      res.end(req.method === 'HEAD' ? undefined : page(logo))
+    } catch { res.writeHead(500); res.end('login page unavailable') }
+  } })
+}

package/src/open-external.ts

@@ -0,0 +1,90 @@
+/**
+ * External open actions for the file tree's "open with" menu: hand a path to
+ * the OS file manager (reveal/select) or launch a URL scheme's registered
+ * handler (vscode://, cursor://, zed://, custom schemes).
+ *
+ * The client runs in a browser / DSH Desktop renderer where a raw `vscode://`
+ * navigation is unreliable, so both actions fan out through this host route
+ * and spawn the platform opener with an argv array (no shell interpolation).
+ * The command builders are pure — the platform is injectable — so every
+ * per-platform branch is unit-testable without spawning anything.
+ */
+import { spawn } from 'node:child_process'
+import { parentOf, requireAbsolute } from './fs-tree.ts'
+import { SidebarError } from './wire.ts'
+
+/** 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 function revealCommand(path: string, platform: NodeJS.Platform = process.platform): ExternalCommand {
+  switch (platform) {
+    case 'darwin':
+      return { command: 'open', args: ['-R', path] }
+    // `explorer /select,<path>` — the classic "show in folder" incantation.
+    // Passed as separate argv entries (no shell); verify on Windows, with
+    // `cmd /c start "" explorer.exe "/select,<path>"` as the fallback.
+    case 'win32':
+      return { command: 'explorer.exe', args: ['/select,', path] }
+    default: {
+      const parent = parentOf(path)
+      return { command: 'xdg-open', args: [parent ?? path] }
+    }
+  }
+}
+
+/** Hand a custom-scheme URL to the OS protocol handler. */
+export function urlCommand(url: string, platform: NodeJS.Platform = process.platform): ExternalCommand {
+  switch (platform) {
+    case 'darwin':
+      return { command: 'open', args: [url] }
+    // url.dll,FileProtocolHandler launches the registered protocol handler;
+    // `cmd /c start "" <url>` is the fallback if rundll32 misbehaves.
+    case 'win32':
+      return { command: 'rundll32.exe', args: ['url.dll,FileProtocolHandler', url] }
+    default:
+      return { command: 'xdg-open', args: [url] }
+  }
+}
+
+/** 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 function validateExternalUrl(raw: string): string {
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) {
+    throw new SidebarError('bad-request', 'url must be a custom-scheme URL')
+  }
+  let url: URL
+  try {
+    url = new URL(raw)
+  } catch {
+    throw new SidebarError('bad-request', 'invalid url')
+  }
+  if (url.protocol === 'http:' || url.protocol === 'https:') {
+    throw new SidebarError('bad-request', 'only custom-scheme urls can be opened externally')
+  }
+  return raw
+}
+
+/**
+ * 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 function launchExternal(action: OpenExternalAction, value: string): { started: true } {
+  const platform = process.platform
+  const spec = action === 'reveal'
+    ? revealCommand(requireAbsolute(value), platform)
+    : urlCommand(validateExternalUrl(value), platform)
+  const child = spawn(spec.command, spec.args, { detached: true, stdio: 'ignore' })
+  child.on('error', () => { /* opener missing/denied: handled by the OS */ })
+  child.unref()
+  return { started: true }
+}

package/src/path-security.ts

@@ -0,0 +1,81 @@
+/** Filesystem path guards shared by sidebar APIs that access a session workspace. */
+import { realpath } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
+import { isWithin, requireAbsolute } from './fs-tree.ts'
+import { SidebarError } from './wire.ts'
+
+/** Resolve a path and convert filesystem resolution failures to an API error. */
+async function resolveRealPath(path: string, label: string): Promise<string> {
+  try {
+    return await realpath(path)
+  } catch (error) {
+    throw new SidebarError('fs-error', `cannot resolve ${label} "${path}": ${error instanceof Error ? error.message : String(error)}`, 400)
+  }
+}
+
+/** Reject a resolved path whose real filesystem target escapes the workspace. */
+function assertWithinWorkspace(workspace: string, target: string): void {
+  if (!isWithin(workspace, target)) {
+    throw new SidebarError('forbidden', `path "${target}" is outside workspace`, 403)
+  }
+}
+
+/**
+ * Resolve an existing workspace path through symlinks and (unless disarmed)
+ * enforce containment.
+ *
+ * @param cwd - Session workspace directory.
+ * @param target - Client-supplied absolute path.
+ * @param fence - Whether containment is enforced (the settings-page
+ * `workspaceFence` switch). Even when false the paths are still resolved
+ * through symlinks so callers always receive the canonical target.
+ * @returns The canonical absolute path used for the filesystem operation.
+ */
+export async function ensureWorkspacePath(cwd: string, target: string, fence = true): Promise<string> {
+  const absolute = requireAbsolute(target)
+  const [realCwd, realTarget] = await Promise.all([
+    resolveRealPath(cwd, 'workspace'),
+    resolveRealPath(absolute, 'target'),
+  ])
+  if (fence) assertWithinWorkspace(realCwd, realTarget)
+  return realTarget
+}
+
+/**
+ * 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.
+ * @param fence - Whether containment is enforced (the settings-page
+ * `workspaceFence` switch). Resolution/canonicalization is identical either way.
+ * @returns A canonical path for an existing target or its nearest existing ancestor.
+ */
+export async function ensureWorkspaceWritePath(cwd: string, target: string, fence = true): Promise<string> {
+  const absolute = requireAbsolute(target)
+  const realCwd = await resolveRealPath(cwd, 'workspace')
+  let existingPath = absolute
+  const missingSegments: string[] = []
+
+  for (;;) {
+    try {
+      const realTarget = await realpath(existingPath)
+      if (fence) assertWithinWorkspace(realCwd, realTarget)
+      return missingSegments.reduce((path, segment) => join(path, segment), realTarget)
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+        if (error instanceof SidebarError) throw error
+        throw new SidebarError('fs-error', `cannot resolve target "${existingPath}": ${error instanceof Error ? error.message : String(error)}`, 400)
+      }
+      const parent = dirname(existingPath)
+      if (parent === existingPath) {
+        throw new SidebarError('fs-error', `cannot resolve target "${absolute}"`, 400)
+      }
+      missingSegments.unshift(basename(existingPath))
+      existingPath = parent
+    }
+  }
+}

package/src/prefs-shared.ts

@@ -0,0 +1,303 @@
+/**
+ * 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 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
+  /**
+   * 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 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
+  /**
+   * Whether the sidebar's filesystem routes enforce the workspace fence:
+   * every client-supplied path must resolve (through symlinks) inside the
+   * session workspace, else the route answers 403 "outside workspace". On
+   * by default; turning it OFF lets the file tree / editor read+write /
+   * media / HTML preview / upload routes reach ANY host path (e.g. the
+   * global ~/.chatcode-cli/AGENTS.md or a linked worktree outside the session cwd)
+   * — the trade-off being that any same-origin script (including
+   * third-party consumer plugins) can read/write outside the workspace
+   * through those routes while it is off. The switch lives under the files
+   * tab's gear in the Side card settings; the fence error surfaces offer a
+   * one-click global off + retry.
+   */
+  workspaceFence: 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 "ChatCode CLI 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 const WIDTH_PERCENT_MIN = 20
+export const WIDTH_PERCENT_MAX = 60
+export const WIDTH_PERCENT_DEFAULT = 35
+
+/** Range contract of {@link SidebarPrefs.terminalFontSize}. */
+export const TERMINAL_FONT_SIZE_MIN = 9
+export const TERMINAL_FONT_SIZE_MAX = 32
+export const TERMINAL_FONT_SIZE_DEFAULT = 13
+
+/** Range contract of {@link SidebarPrefs.titleBarStripPx}. */
+export const TITLE_BAR_STRIP_MIN = 0
+export const TITLE_BAR_STRIP_MAX = 120
+export const TITLE_BAR_STRIP_DEFAULT = 40
+
+/** The title-bar / shell compatibility schemes (see {@link SidebarPrefs.titleBarScheme}). */
+export const TITLE_BAR_SCHEMES = ['auto', 'web', 'preset', 'custom'] as const
+export type TitleBarScheme = typeof TITLE_BAR_SCHEMES[number]
+
+/** Fallback prefs used whenever the settings document is unreachable or malformed. */
+export const SIDEBAR_PREFS_DEFAULTS: SidebarPrefs = {
+  openByDefault: false,
+  defaultWidthPercent: WIDTH_PERCENT_DEFAULT,
+  autoOpenSubagent: true,
+  autoOpenJobs: true,
+  agentTerminalTools: false,
+  agentOpenTools: false,
+  bottomPanelAutoTerminal: true,
+  terminalFontFamily: '',
+  terminalFontSize: TERMINAL_FONT_SIZE_DEFAULT,
+  interceptOpenPath: true,
+  editorExplorer: false,
+  workspaceFence: true,
+  terminalShell: '',
+  terminalShellArgs: '',
+  titleBarScheme: 'auto',
+  titleBarPresetId: '',
+  customCss: '',
+  titleBarCompat: false,
+  titleBarStripPx: TITLE_BAR_STRIP_DEFAULT,
+  htmlViewerNoSandbox: false,
+  htmlViewerDefaultUnsafe: false,
+  browserNoSandbox: false,
+  browserInterceptLinks: true,
+  browserInterceptHttp: true,
+  browserInterceptHttps: false,
+  browserAllowedLoopback: '',
+  tabsEnabled: {},
+  viewersEnabled: {},
+  pluginSettings: {},
+}
+
+/** Clamp one width percent into the contract range (shared by schema and client reads). */
+export function clampWidthPercent(value: number): number {
+  return Math.min(WIDTH_PERCENT_MAX, Math.max(WIDTH_PERCENT_MIN, Math.round(value)))
+}
+
+/** Clamp one terminal font size into the contract range (shared by schema and client reads). */
+export function clampTerminalFontSize(value: number): number {
+  return Math.min(TERMINAL_FONT_SIZE_MAX, Math.max(TERMINAL_FONT_SIZE_MIN, Math.round(value)))
+}
+
+/** Clamp one title-bar strip height into the contract range (shared by schema and client reads). */
+export function clampTitleBarStrip(value: number): number {
+  return Math.min(TITLE_BAR_STRIP_MAX, Math.max(TITLE_BAR_STRIP_MIN, Math.round(value)))
+}