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

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-better-sidebar`. */
+export const PLUGIN_TOPIC_URL = 'https://github.com/topics/dsh-better-sidebar'
+
+/** One curated plugin entry (name / url / description / install script). */
+export interface PluginEntry {
+  /** Unique id (the npm package name). */
+  id: string
+  /** Short display name. */
+  name: string
+  /** GitHub repository URL. */
+  url: string
+  /** One-line description (i18n friendly: string or () => string). */
+  description: string | (() => string)
+  /** Optional catalog group heading (i18n friendly); entries without one
+   *  render under the plain list (a flat catalog stays flat). */
+  category?: string | (() => string)
+  /** The full shell command pre-filled into the install terminal (not
+   *  executed until the user presses Enter). */
+  install: string
+}

package/src/client/plugins-tabs.ts

@@ -0,0 +1,153 @@
+/**
+ * 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 ~/.chatcode-cli` so the install
+ * runs with the ChatCode CLI 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 ~/.chatcode-cli` keeps the profile
+    // context consistent with the other entries.
+    install: 'cd ~/.chatcode-cli && cco 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
+    // better-sidebar (auto-tab when present, floating bubble when not).
+    install: 'cd ~/.chatcode-cli && cco plugin --profile web add dsh-better-sidebar && cco plugin --profile web add git+https://github.com/Fisfzy/ego-browser.git',
+  },
+  {
+    id: 'dsh-better-overleaf',
+    name: 'dsh-better-overleaf Overleaf 标签页',
+    url: 'https://github.com/Hoemr/dsh-better-overleaf',
+    description: () => t('pluginBetterOverleafDesc'),
+    // Published on npm; peer-depends on dsh-better-sidebar (Overleaf tab),
+    // so the install line installs the prerequisite first.
+    install: 'cd ~/.chatcode-cli && cco plugin --profile web add dsh-better-sidebar && cco plugin --profile web add dsh-better-overleaf',
+  },
+  {
+    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-better-sidebar (required peer), so
+    // the install line installs the prerequisite first, then the plugin.
+    install: 'cd ~/.chatcode-cli && cco plugin --profile web add dsh-better-sidebar && cco 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 better-sidebar is present.
+    install: 'cd ~/.chatcode-cli && cco plugin --profile web add dsh-better-sidebar && cco 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-better-sidebar (Git Forge tab). Install the
+    // prerequisite first; package is GitHub-sourced until npm publish.
+    install: 'cd ~/.chatcode-cli && cco plugin --profile web add dsh-better-sidebar && cco 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 ~/.chatcode-cli && cco plugin --profile web add dsh-better-sidebar && cco plugin --profile web add git+https://github.com/yq04/dsh-git-remotes.git',
+  },
+  {
+    id: 'dsh-github-workbench',
+    name: 'dsh-github-workbench GitHub 工作台',
+    url: 'https://github.com/meyaomiao/dsh-github-workbench',
+    description: () => t('pluginGithubWorkbenchDesc'),
+    // Full GitHub workbench tab: remote repo tree + Issues/PRs/Actions tabs
+    // with write support (create/comment/merge/re-run). lib/ is committed,
+    // so the pinned github:-form install works without a local build.
+    install: 'cd ~/.chatcode-cli && cco plugin --profile web add "github:meyaomiao/dsh-github-workbench#v0.1.0"',
+  },
+  {
+    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-better-sidebar (required peer), so
+    // the install line installs the prerequisite first, then the plugin.
+    install: 'cd ~/.chatcode-cli && cco plugin --profile web add dsh-better-sidebar && cco plugin --profile web add git+https://github.com/ChenRuoT/dsh-sidebar-qa.git',
+  },
+  {
+    id: 'dsh-sidenote',
+    name: 'dsh-sidenote 侧边聊天',
+    url: 'https://github.com/g-yixuan/dsh-sidenote',
+    description: () => t('pluginSidenoteDesc'),
+    // dsh-sidenote hard-depends on dsh-better-sidebar (required peer), so
+    // the install line installs the prerequisite first, then the plugin.
+    install: 'cd ~/.chatcode-cli && cco plugin --profile web add dsh-better-sidebar && cco plugin --profile web add dsh-sidenote',
+  },
+  {
+    id: 'dsh-server-deck',
+    name: 'dsh-server-deck 服务器甲板',
+    url: 'https://github.com/meyaomiao/DSH-server-deck',
+    description: () => t('pluginServerDeckDesc'),
+    // Published on npm; dual-mount like flowglass — registers the native
+    // "Servers" tab when better-sidebar is present, standalone drawer
+    // otherwise. Install the prerequisite first.
+    install: 'cd ~/.chatcode-cli && cco plugin --profile web add dsh-better-sidebar && cco plugin --profile web add dsh-server-deck@latest',
+  },
+  {
+    id: 'dsh-suhuang-scroll',
+    name: 'dsh-suhuang-scroll 苏黄共阅',
+    url: 'https://github.com/YZDame/dsh-suhuang-scroll',
+    description: () => t('pluginSuhuangScrollDesc'),
+    // Suhuang Scroll is a DSH Web plugin whose runtime console registers in
+    // better-sidebar. Install the sidebar prerequisite before the npm package.
+    install: 'cd ~/.chatcode-cli && cco plugin --profile web add dsh-better-sidebar && cco plugin --profile web add dsh-suhuang-scroll',
+  },
+  {
+    id: 'dsh-ssh-tunnel',
+    name: 'dsh-ssh-tunnel SSH 隧道',
+    url: 'https://github.com/thirsty5034/dsh-ssh-tunnel',
+    description: () => t('pluginSshTunnelDesc'),
+    // Peer-depends on dsh-better-sidebar (SSH Tunnel tab + center terminal/SFTP).
+    // Install the prerequisite first; package is GitHub-sourced until npm publish.
+    install: 'cd ~/.chatcode-cli && cco plugin --profile web add dsh-better-sidebar && cco 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-better-sidebar (optional peer) for the tab; no model tools.
+    install: 'cd ~/.chatcode-cli && cco plugin --profile web add dsh-better-sidebar && cco plugin --profile web add git+https://github.com/yq04/dsh-turn-review.git',
+  },
+  {
+    id: 'dsh-bilingual-reader',
+    name: 'dsh-bilingual-reader 双语阅读',
+    url: 'https://github.com/Johnblur/dsh-bilingual-reader',
+    description: () => t('pluginBilingualReaderDesc'),
+    // Bilingual paper reading: a native-PDF tab with LLM selection translation,
+    // isolated from the main conversation context. Hard-depends on the
+    // better-sidebar tab service, so install the prerequisite first.
+    install: 'cd ~/.chatcode-cli && cco plugin --profile web add dsh-better-sidebar && cco plugin --profile web add github:Johnblur/dsh-bilingual-reader',
+  },
+]

package/src/client/plugins-viewers.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 ~/.chatcode-cli` so the install runs with
+ * the ChatCode CLI 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 ~/.chatcode-cli && cco plugin --profile web add @huanlin/dsh-plugin-better-sidebar-plugin-office',
+  },
+  {
+    id: 'dsh-md-export',
+    name: 'Markdown 导出插件',
+    url: 'https://github.com/AnakinCao/dsh-md-export',
+    description: () => t('pluginMdExportDesc'),
+    install: 'cd ~/.chatcode-cli && cco plugin --profile web add dsh-md-export',
+  },
+  {
+    id: 'dsh-code-nav',
+    name: '代码预览导航',
+    url: 'https://github.com/AnakinCao/dsh-code-nav',
+    description: () => t('pluginCodeNavDesc'),
+    install: 'cd ~/.chatcode-cli && cco plugin --profile web add https://github.com/AnakinCao/dsh-code-nav.git',
+  },
+  {
+    id: 'dsh-video-preview',
+    name: '视频预览插件',
+    url: 'https://github.com/zemul/dsh-video-preview',
+    description: () => t('pluginVideoPreviewDesc'),
+    install: 'cd ~/.chatcode-cli && cco plugin --profile web add dsh-video-preview',
+  },
+]

package/src/client/prefs.ts

@@ -0,0 +1,216 @@
+/**
+ * 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,
+    bottomPanelAutoTerminal: typeof record.bottomPanelAutoTerminal === 'boolean'
+      ? record.bottomPanelAutoTerminal
+      : SIDEBAR_PREFS_DEFAULTS.bottomPanelAutoTerminal,
+    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,
+    workspaceFence: typeof record.workspaceFence === 'boolean'
+      ? record.workspaceFence
+      : SIDEBAR_PREFS_DEFAULTS.workspaceFence,
+    // 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
+  }
+}

package/src/client/produced-files.ts

@@ -0,0 +1,120 @@
+/**
+ * Pure derivation of one turn's produced files from finalized conversation
+ * nodes — a structural replica of ui-deliverables' `producedForClosing`
+ * (the mutation tools' follow-along `locations`, by render intent: a diff
+ * card or a generic edit card; reads/deletes/failures produce nothing).
+ * Kept dependency-free so the takeover logic is unit-testable and the
+ * replica is easy to diff against upstream when it drifts.
+ */
+import { isAbsolutePath } from './paths.ts'
+
+/** Paths a tool-result view reports as produced, by render intent. */
+export function producedPaths(view: unknown): readonly string[] {
+  if (view === null || typeof view !== 'object') return []
+  const record = view as { card?: unknown; kind?: unknown; locations?: unknown }
+  const isEdit = record.card === 'diff' || (record.card === 'generic' && record.kind === 'edit')
+  if (!isEdit) return []
+  if (!Array.isArray(record.locations)) return []
+  const paths: string[] = []
+  for (const location of record.locations) {
+    if (location !== null && typeof location === 'object' && typeof (location as { path?: unknown }).path === 'string') {
+      paths.push((location as { path: string }).path)
+    }
+  }
+  return paths
+}
+
+/**
+ * Files produced by the turn the assistant at `seq` closes. Accumulation
+ * resets on turn boundaries (a user message, or a node reporting a different
+ * turn number); paths keep first-seen order and appear once.
+ * @param nodes - snapshot nodes in surface order (structural, unknown-safe).
+ * @param seq - the closing assistant's seq (the render site's anchor).
+ * @returns produced paths; empty when the turn wrote nothing.
+ */
+export function producedForClosing(nodes: readonly unknown[], seq: number): readonly string[] {
+  let pending: string[] = []
+  let seen = new Set<string>()
+  let turn: number | undefined
+  for (const node of nodes) {
+    if (node === null || typeof node !== 'object') continue
+    const record = node as { kind?: unknown; isError?: unknown; callView?: unknown; turn?: unknown; seq?: unknown }
+    if (record.kind === 'tool-result') {
+      if (record.isError === true) continue
+      for (const path of producedPaths(record.callView)) {
+        if (seen.has(path)) continue
+        seen.add(path)
+        pending.push(path)
+      }
+      continue
+    }
+    if (record.kind === 'user') {
+      turn = undefined
+      pending = []
+      seen = new Set()
+    } else if (typeof record.turn === 'number') {
+      if (turn !== undefined && record.turn !== turn) {
+        pending = []
+        seen = new Set()
+      }
+      turn = record.turn
+    }
+    if (record.kind === 'assistant' && record.seq === seq) return pending
+  }
+  return []
+}
+
+/**
+ * Claim the turn-tail chain only when the closing turn produced files.
+ *
+ * The authoritative source is the engine Turn data — the same value
+ * ui-deliverables reads (`owner.turn.data.get('deliverables')`): a
+ * `{ produced: [{ seq, path }, ...] }` record accumulated per Turn. The
+ * node-based replica below stays as a fallback for compositions that do not
+ * publish it.
+ * @param owner - the turn-tail owner currency ({turn, seq, openFile}).
+ * @returns produced paths as the matched value, or null to decline.
+ */
+export function selectProducedFiles(owner: unknown): readonly string[] | null {
+  const record = owner as {
+    turn?: { data?: { get?: (key: string) => unknown } }
+    nodes?: unknown
+    seq?: unknown
+  } | null
+  if (record === null || typeof record !== 'object') return null
+  const seq = typeof record.seq === 'number' ? record.seq : Number.POSITIVE_INFINITY
+  const data = record.turn?.data?.get?.('deliverables') as
+    | { produced?: unknown }
+    | null
+    | undefined
+  if (data !== null && typeof data === 'object' && Array.isArray(data.produced)) {
+    const paths: string[] = []
+    const seen = new Set<string>()
+    for (const item of data.produced) {
+      if (item === null || typeof item !== 'object') continue
+      const produced = item as { path?: unknown; seq?: unknown }
+      if (typeof produced.path !== 'string' || produced.path === '') continue
+      if (typeof produced.seq === 'number' && produced.seq > seq) continue
+      if (seen.has(produced.path)) continue
+      seen.add(produced.path)
+      paths.push(produced.path)
+    }
+    return paths.length === 0 ? null : paths
+  }
+  if (!Array.isArray(record.nodes)) return null
+  const paths = producedForClosing(record.nodes, seq)
+  return paths.length === 0 ? null : paths
+}
+
+/**
+ * Resolve a (possibly relative) path against the session cwd for the sidebar.
+ * Absolute detection mirrors the host (see client/paths.isAbsolutePath):
+ * POSIX roots, drive letters and UNC shares must not be joined onto the cwd.
+ */
+export function resolveSidebarPath(cwd: string | undefined, path: string): string {
+  if (isAbsolutePath(path)) return path
+  const base = cwd ?? ''
+  if (base === '') return path
+  const separator = base.includes('\\') ? '\\' : '/'
+  return `${base.replace(/[\\/]+$/, '')}${separator}${path}`
+}