dsh-coding-sidebar 1.0.0

package/src/client/pinned.ts

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

package/src/client/plugin-settings.ts

@@ -0,0 +1,43 @@
+/**
+ * Pending-writes queue for the file tree's open-with config: pin toggles and
+ * (outside the settings popup) config edits land in the sidebar prefs as
+ * `pluginSettings['editor']`. Writes are serialized through one promise chain
+ * so a quick burst of pin clicks can never read a stale pluginSettings map
+ * and drop an earlier toggle; each write pushes the whole open map patch
+ * through the revision-free settings route and adopts the returned document.
+ *
+ * (The settings popup has its own serialized commit — SideCardSection's —
+ * so its rows and this helper rarely race; the shared route's last-write-wins
+ * semantics cover the uncommon overlap.)
+ */
+import { api } from './api.ts'
+import { parsePrefs } from './prefs.ts'
+import type { SidebarStore } from './state.ts'
+
+let queue: Promise<void> = Promise.resolve()
+
+/**
+ * Merge one plugin-owned settings blob of one descriptor and persist it.
+ * @param store - the sidebar store (its prefs are replaced by the write result).
+ * @param descriptorId - the descriptor whose blob is patched ('editor' here).
+ * @param updater - pure patch function; receives a shallow copy of the blob.
+ */
+export function updatePluginSettings(
+  store: SidebarStore,
+  descriptorId: string,
+  updater: (blob: Record<string, unknown>) => Record<string, unknown>,
+): void {
+  queue = queue.then(async () => {
+    const prefs = store.getPrefs()
+    const blob = prefs.pluginSettings[descriptorId] ?? {}
+    const next = updater({ ...blob })
+    const view = await api.settingsUpdate({
+      pluginSettings: { ...prefs.pluginSettings, [descriptorId]: next },
+    })
+    store.setPrefs(parsePrefs(view.value))
+  }).catch((error: unknown) => {
+    // The pin stays visually unchanged (no optimistic flip) and the menu
+    // keeps working — the write failure is logged, not surfaced.
+    console.error('open-with settings write failed', error)
+  })
+}

package/src/client/plugins-shared.ts

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

package/src/client/plugins-tabs.ts

@@ -0,0 +1,96 @@
+/**
+ * The built-in catalog of TAB-registration plugins (sidebar pages),
+ * shown in the "add tab plugin" modal (Side card settings → 侧边栏内容 grid
+ * → the dashed card). Adding an entry: append one object here (unique
+ * `id` = npm package name, `url` = GitHub repo, `description` =
+ * i18n-friendly (add a `pluginXxxDesc` key in locales.ts), `install` = the
+ * full one-line install script — it starts with `cd ~/.dsh` so the install
+ * runs with the DSH home as the working directory). Data integrity is
+ * guarded by `tests/plugin-list.spec.ts`.
+ */
+import { t } from './locales.ts'
+import type { PluginEntry } from './plugins-shared.ts'
+
+/** Tab-registration plugins (alphabetical order). */
+export const builtinTabPlugins: readonly PluginEntry[] = [
+  {
+    id: '@dsh-external/dsh-sentinel',
+    name: 'dsh-sentinel 唤醒系统',
+    url: 'https://github.com/fuhefei/dsh-sentinel',
+    description: () => t('pluginSentinelDesc'),
+    // The official one-line bundle-channel install (git source, build
+    // artifacts committed — no build step needed). The `github:…` form is
+    // the upstream's documented command, `cd ~/.dsh` keeps the profile
+    // context consistent with the other entries.
+    install: 'cd ~/.dsh && dsh plugin --profile web add "github:fuhefei/dsh-sentinel#v0.7.0"',
+  },
+  {
+    id: '@dsh-external/ego-browser',
+    name: 'ego-browser Agent 浏览器',
+    url: 'https://github.com/Fisfzy/ego-browser',
+    description: () => t('pluginEgoBrowserDesc'),
+    // Registers a sidebar tab for the agent browser; optional peer of
+    // dsh-coding-sidebar (auto-tab when present, floating bubble when not).
+    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-coding-sidebar && dsh plugin --profile web add git+https://github.com/Fisfzy/ego-browser.git',
+  },
+  {
+    id: 'dsh-docs-panel',
+    name: 'dsh-docs-panel 全局文档',
+    url: 'https://github.com/mlosun/dsh-docs-panel',
+    description: () => t('pluginDocsPanelDesc'),
+    // dsh-docs-panel hard-depends on dsh-coding-sidebar (required peer), so
+    // the install line installs the prerequisite first, then the plugin.
+    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-coding-sidebar && dsh plugin --profile web add dsh-docs-panel',
+  },
+  {
+    id: 'dsh-flowglass',
+    name: 'dsh-flowglass 流镜',
+    url: 'https://github.com/Iwctwbh/dsh-flowglass',
+    description: () => t('pluginFlowglassDesc'),
+    // Flowglass keeps its standalone drawer as a fallback and registers the
+    // native tab automatically when dsh-coding-sidebar is present.
+    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-coding-sidebar && dsh plugin --profile web add dsh-flowglass',
+  },
+  {
+    id: 'dsh-git-forge',
+    name: 'dsh-git-forge Git 凭据',
+    url: 'https://github.com/thirsty5034/dsh-git-forge',
+    description: () => t('pluginGitForgeDesc'),
+    // Peer-depends on dsh-coding-sidebar (Git Forge tab). Install the
+    // prerequisite first; package is GitHub-sourced until npm publish.
+    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-coding-sidebar && dsh plugin --profile web add "dsh-git-forge@github:thirsty5034/dsh-git-forge"',
+  },
+  {
+    id: 'dsh-git-remotes',
+    name: 'dsh-git-remotes Git 远程',
+    url: 'https://github.com/yq04/dsh-git-remotes',
+    description: () => t('pluginGitRemotesDesc'),
+    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-coding-sidebar && dsh plugin --profile web add git+https://github.com/yq04/dsh-git-remotes.git',
+  },
+  {
+    id: 'dsh-sidebar-qa',
+    name: 'dsh-sidebar-qa 划选追问',
+    url: 'https://github.com/ChenRuoT/dsh-sidebar-qa',
+    description: () => t('pluginSidebarQaDesc'),
+    // dsh-sidebar-qa hard-depends on dsh-coding-sidebar (required peer), so
+    // the install line installs the prerequisite first, then the plugin.
+    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-coding-sidebar && dsh plugin --profile web add git+https://github.com/ChenRuoT/dsh-sidebar-qa.git',
+  },
+  {
+    id: 'dsh-ssh-tunnel',
+    name: 'dsh-ssh-tunnel SSH 隧道',
+    url: 'https://github.com/thirsty5034/dsh-ssh-tunnel',
+    description: () => t('pluginSshTunnelDesc'),
+    // Peer-depends on dsh-coding-sidebar (SSH Tunnel tab + center terminal/SFTP).
+    // Install the prerequisite first; package is GitHub-sourced until npm publish.
+    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-coding-sidebar && dsh plugin --profile web add "dsh-ssh-tunnel@github:thirsty5034/dsh-ssh-tunnel"',
+  },
+  {
+    id: 'dsh-turn-review',
+    name: 'dsh-turn-review 本轮审查',
+    url: 'https://github.com/yq04/dsh-turn-review',
+    description: () => t('pluginTurnReviewDesc'),
+    // Needs dsh-coding-sidebar (optional peer) for the tab; no model tools.
+    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-coding-sidebar && dsh plugin --profile web add git+https://github.com/yq04/dsh-turn-review.git',
+  },
+]

package/src/client/plugins-viewers.ts

@@ -0,0 +1,30 @@
+/**
+ * The built-in catalog of FILE-PREVIEWER plugins (file-type previewers),
+ * shown in the "add preview plugin" modal (Side card settings → 文件预览
+ * grid → the dashed card). Adding an entry: append one object here (unique
+ * `id` = npm package name, `url` = GitHub repo, `description` =
+ * i18n-friendly, `install` = the full shell command pre-filled into the
+ * install terminal — it starts with `cd ~/.dsh` so the install runs with
+ * the DSH home as the working directory). Data integrity is guarded by
+ * `tests/plugin-list.spec.ts`.
+ */
+import { t } from './locales.ts'
+import type { PluginEntry } from './plugins-shared.ts'
+
+/** File-previewer plugins (alphabetical order). */
+export const builtinViewerPlugins: readonly PluginEntry[] = [
+  {
+    id: '@huanlin/dsh-plugin-better-sidebar-plugin-office',
+    name: 'Office 预览插件',
+    url: 'https://github.com/HuanLinOTO/dsh-plugin-better-sidebar-plugin-office',
+    description: () => t('pluginOfficeDesc'),
+    install: 'cd ~/.dsh && dsh plugin --profile web add @huanlin/dsh-plugin-better-sidebar-plugin-office',
+  },
+  {
+    id: 'dsh-video-preview',
+    name: '视频预览插件',
+    url: 'https://github.com/zemul/dsh-video-preview',
+    description: () => t('pluginVideoPreviewDesc'),
+    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-video-preview',
+  },
+]

package/src/client/prefs.ts

@@ -0,0 +1,210 @@
+/**
+ * Client-side read of the user-facing "Side card" preferences. The host owns
+ * the namespace through the settings seam (in-process); the DSH settings RPC
+ * domain only serves allowlisted namespaces to configuration clients, so the
+ * client reads and writes THIS namespace through the plugin's own fenced
+ * /sidebar routes instead (api.settingsGet/settingsUpdate). Any failure
+ * (route rejected, namespace absent, a field of the wrong type, a value out
+ * of the contract range) falls back to the schema defaults — the side card
+ * must keep working exactly as composed when the settings surface is missing.
+ */
+import type { api } from './api.ts'
+import {
+  clampTerminalFontSize,
+  clampTitleBarStrip,
+  clampWidthPercent,
+  SIDEBAR_PREFS_DEFAULTS,
+  TITLE_BAR_SCHEMES,
+  TITLE_BAR_STRIP_DEFAULT,
+  type SidebarPrefs,
+  type TitleBarScheme,
+} from '../prefs-shared.ts'
+
+export {
+  SIDEBAR_PREFS_DEFAULTS,
+  TITLE_BAR_SCHEMES,
+  TITLE_BAR_STRIP_DEFAULT,
+  clampTerminalFontSize,
+  clampTitleBarStrip,
+  clampWidthPercent,
+}
+export type { SidebarPrefs, TitleBarScheme }
+
+/** The settings wire face the preferences need (a subset of the plugin api). */
+export type SidebarSettingsClient = Pick<typeof api, 'settingsGet' | 'settingsUpdate'>
+
+/** Validate one raw resolved value into {@link SidebarPrefs}. Used for the
+ * settings.get payload AND the settings.update response (both carry the
+ * layered resolved value); any malformed field falls back to its default.
+ * @param value - the raw resolved section from the settings wire.
+ * @returns validated prefs (always well-formed).
+ */
+export function parsePrefs(value: unknown): SidebarPrefs {
+  if (value === null || typeof value !== 'object') return { ...SIDEBAR_PREFS_DEFAULTS }
+  const record = value as Record<string, unknown>
+  return {
+    openByDefault: typeof record.openByDefault === 'boolean'
+      ? record.openByDefault
+      : SIDEBAR_PREFS_DEFAULTS.openByDefault,
+    defaultWidthPercent: typeof record.defaultWidthPercent === 'number' && Number.isFinite(record.defaultWidthPercent)
+      ? clampWidthPercent(record.defaultWidthPercent)
+      : SIDEBAR_PREFS_DEFAULTS.defaultWidthPercent,
+    autoOpenSubagent: typeof record.autoOpenSubagent === 'boolean'
+      ? record.autoOpenSubagent
+      : SIDEBAR_PREFS_DEFAULTS.autoOpenSubagent,
+    autoOpenJobs: typeof record.autoOpenJobs === 'boolean'
+      ? record.autoOpenJobs
+      : SIDEBAR_PREFS_DEFAULTS.autoOpenJobs,
+    agentTerminalTools: typeof record.agentTerminalTools === 'boolean'
+      ? record.agentTerminalTools
+      : SIDEBAR_PREFS_DEFAULTS.agentTerminalTools,
+    agentOpenTools: typeof record.agentOpenTools === 'boolean'
+      ? record.agentOpenTools
+      : SIDEBAR_PREFS_DEFAULTS.agentOpenTools,
+    terminalFontFamily: typeof record.terminalFontFamily === 'string'
+      ? record.terminalFontFamily
+      : SIDEBAR_PREFS_DEFAULTS.terminalFontFamily,
+    terminalShell: typeof record.terminalShell === 'string'
+      ? record.terminalShell
+      : SIDEBAR_PREFS_DEFAULTS.terminalShell,
+    terminalShellArgs: typeof record.terminalShellArgs === 'string'
+      ? record.terminalShellArgs
+      : SIDEBAR_PREFS_DEFAULTS.terminalShellArgs,
+    terminalFontSize: typeof record.terminalFontSize === 'number' && Number.isFinite(record.terminalFontSize)
+      ? clampTerminalFontSize(record.terminalFontSize)
+      : SIDEBAR_PREFS_DEFAULTS.terminalFontSize,
+    interceptOpenPath: typeof record.interceptOpenPath === 'boolean'
+      ? record.interceptOpenPath
+      : SIDEBAR_PREFS_DEFAULTS.interceptOpenPath,
+    editorExplorer: typeof record.editorExplorer === 'boolean'
+      ? record.editorExplorer
+      : SIDEBAR_PREFS_DEFAULTS.editorExplorer,
+    // The title-bar scheme (auto | web | preset | custom). The schema
+    // declares the field WITHOUT a default, so documents written by older
+    // plugin versions resolve without it — migrate from the legacy fields:
+    // a document that ALREADY HAS VALUES (the manual compat flag on, or a
+    // non-default strip px — both only reachable through the old gear
+    // popup) maps to the `custom` scheme so the user's numbers keep
+    // working; a pristine document keeps the conservative `auto` scheme.
+    titleBarScheme: isTitleBarScheme(record.titleBarScheme)
+      ? record.titleBarScheme
+      : (record.titleBarCompat === true || hasLegacyStripValue(record.titleBarStripPx) ? 'custom' : 'auto'),
+    titleBarPresetId: typeof record.titleBarPresetId === 'string'
+      ? record.titleBarPresetId
+      : SIDEBAR_PREFS_DEFAULTS.titleBarPresetId,
+    customCss: typeof record.customCss === 'string'
+      ? record.customCss
+      : SIDEBAR_PREFS_DEFAULTS.customCss,
+    titleBarCompat: typeof record.titleBarCompat === 'boolean'
+      ? record.titleBarCompat
+      : SIDEBAR_PREFS_DEFAULTS.titleBarCompat,
+    titleBarStripPx: typeof record.titleBarStripPx === 'number' && Number.isFinite(record.titleBarStripPx)
+      ? clampTitleBarStrip(record.titleBarStripPx)
+      : SIDEBAR_PREFS_DEFAULTS.titleBarStripPx,
+    htmlViewerNoSandbox: typeof record.htmlViewerNoSandbox === 'boolean'
+      ? record.htmlViewerNoSandbox
+      : SIDEBAR_PREFS_DEFAULTS.htmlViewerNoSandbox,
+    htmlViewerDefaultUnsafe: typeof record.htmlViewerDefaultUnsafe === 'boolean'
+      ? record.htmlViewerDefaultUnsafe
+      : SIDEBAR_PREFS_DEFAULTS.htmlViewerDefaultUnsafe,
+    browserNoSandbox: typeof record.browserNoSandbox === 'boolean'
+      ? record.browserNoSandbox
+      : SIDEBAR_PREFS_DEFAULTS.browserNoSandbox,
+    browserInterceptLinks: typeof record.browserInterceptLinks === 'boolean'
+      ? record.browserInterceptLinks
+      : SIDEBAR_PREFS_DEFAULTS.browserInterceptLinks,
+    browserInterceptHttp: typeof record.browserInterceptHttp === 'boolean'
+      ? record.browserInterceptHttp
+      : SIDEBAR_PREFS_DEFAULTS.browserInterceptHttp,
+    browserInterceptHttps: typeof record.browserInterceptHttps === 'boolean'
+      ? record.browserInterceptHttps
+      : SIDEBAR_PREFS_DEFAULTS.browserInterceptHttps,
+    browserAllowedLoopback: typeof record.browserAllowedLoopback === 'string'
+      ? record.browserAllowedLoopback
+      : SIDEBAR_PREFS_DEFAULTS.browserAllowedLoopback,
+    tabsEnabled: booleanMapOf(record.tabsEnabled),
+    viewersEnabled: booleanMapOf(record.viewersEnabled),
+    pluginSettings: pluginSettingsMapOf(record.pluginSettings),
+  }
+}
+
+/**
+ * Validate the plugin-owned settings map (v0.12.0+): `{ descriptorId: { key:
+ * value } }`, nested open maps. Any non-object value (or a malformed whole)
+ * falls back to the empty map — the schema defaults already guard the wire
+ * shape, this is the client's second line.
+ */
+function pluginSettingsMapOf(value: unknown): Record<string, Record<string, unknown>> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return {}
+  const out: Record<string, Record<string, unknown>> = {}
+  for (const [id, blob] of Object.entries(value as Record<string, unknown>)) {
+    if (blob !== null && typeof blob === 'object' && !Array.isArray(blob)) {
+      out[id] = blob as Record<string, unknown>
+    }
+  }
+  return out
+}
+
+/**
+ * Validate one enable-switch map (per-tab / per-viewer). Only boolean values
+ * survive; a non-object or a non-boolean entry falls back to the empty map /
+ * drops the entry — an absent key means the feature stays enabled.
+ */
+function booleanMapOf(value: unknown): Record<string, boolean> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return {}
+  const out: Record<string, boolean> = {}
+  for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+    if (typeof item === 'boolean') out[key] = item
+  }
+  return out
+}
+
+/** Type guard for the title-bar scheme union (anything else falls back). */
+function isTitleBarScheme(value: unknown): value is TitleBarScheme {
+  return typeof value === 'string' && (TITLE_BAR_SCHEMES as readonly string[]).includes(value)
+}
+
+/**
+ * Whether the legacy document carries an explicit strip value (only
+ * reachable through the old gear popup): a stored number different from the
+ * default counts as "the user already configured something" and migrates to
+ * the `custom` scheme.
+ */
+function hasLegacyStripValue(value: unknown): boolean {
+  return typeof value === 'number' && Number.isFinite(value) && value !== TITLE_BAR_STRIP_DEFAULT
+}
+
+/**
+ * Read the resolved side card preferences through the plugin's settings route.
+ * @param settings - the settings wire face (the plugin api by default).
+ * @returns validated prefs, or the schema defaults when the route rejects,
+ * the namespace is absent, or a stored value violates the contract.
+ */
+export async function loadPrefs(settings: SidebarSettingsClient): Promise<SidebarPrefs> {
+  try {
+    const view = await settings.settingsGet()
+    return parsePrefs(view.value)
+  } catch {
+    // Transport/fence rejection or a malformed response: keep the defaults.
+    return { ...SIDEBAR_PREFS_DEFAULTS }
+  }
+}
+
+/**
+ * Read the external-disable flag from the same settings route: the
+ * dsh-web-ui family's aionui-panel provider choice. True only when the host
+ * resolved `aionui-panel.rightPanel` to 'aionui-panel' — while true the
+ * sidebar must not mount (the two right panels are mutually exclusive). Any
+ * failure (route rejected, aionui absent, malformed response) reads false,
+ * so a missing family never hides the sidebar.
+ * @param settings - the settings wire face (the plugin api by default).
+ * @returns the external-disable flag (false on any failure).
+ */
+export async function loadExternalDisable(settings: SidebarSettingsClient): Promise<boolean> {
+  try {
+    const view = await settings.settingsGet()
+    return view.externalDisable === true
+  } catch {
+    return false
+  }
+}