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

package/src/client/lang.ts

@@ -0,0 +1,225 @@
+/**
+ * Syntax highlighting for the file editor: extension → CodeMirror language
+ * mapping. The key derivation is pure and unit-tested; the factories pull in
+ * the CodeMirror language packages (bundled into the client).
+ */
+import { Language, LanguageSupport, StreamLanguage } from '@codemirror/language'
+import { javascript, jsxLanguage, typescriptLanguage, tsxLanguage } from '@codemirror/lang-javascript'
+import { json } from '@codemirror/lang-json'
+import { markdown } from '@codemirror/lang-markdown'
+import { python } from '@codemirror/lang-python'
+import { html } from '@codemirror/lang-html'
+import { css, cssLanguage } from '@codemirror/lang-css'
+import { xml } from '@codemirror/lang-xml'
+import { yaml } from '@codemirror/lang-yaml'
+import { sql } from '@codemirror/lang-sql'
+import { java } from '@codemirror/lang-java'
+import { cpp } from '@codemirror/lang-cpp'
+import { rust } from '@codemirror/lang-rust'
+import { go } from '@codemirror/lang-go'
+import { php } from '@codemirror/lang-php'
+import { vue } from '@codemirror/lang-vue'
+import { shell } from '@codemirror/legacy-modes/mode/shell'
+import { toml } from '@codemirror/legacy-modes/mode/toml'
+import { nginx } from '@codemirror/legacy-modes/mode/nginx'
+import { dockerFile } from '@codemirror/legacy-modes/mode/dockerfile'
+import { properties } from '@codemirror/legacy-modes/mode/properties'
+import { csharp, kotlin, dart, scala, objectiveCpp } from '@codemirror/legacy-modes/mode/clike'
+import { swift } from '@codemirror/legacy-modes/mode/swift'
+import { sCSS, less } from '@codemirror/legacy-modes/mode/css'
+import { sass } from '@codemirror/legacy-modes/mode/sass'
+import { stylus } from '@codemirror/legacy-modes/mode/stylus'
+import { ruby } from '@codemirror/legacy-modes/mode/ruby'
+import { lua } from '@codemirror/legacy-modes/mode/lua'
+import { perl } from '@codemirror/legacy-modes/mode/perl'
+import { r } from '@codemirror/legacy-modes/mode/r'
+import { groovy } from '@codemirror/legacy-modes/mode/groovy'
+import { powerShell } from '@codemirror/legacy-modes/mode/powershell'
+import { diff } from '@codemirror/legacy-modes/mode/diff'
+import { protobuf } from '@codemirror/legacy-modes/mode/protobuf'
+import { cmake } from '@codemirror/legacy-modes/mode/cmake'
+import { pug } from '@codemirror/legacy-modes/mode/pug'
+import { tcl } from '@codemirror/legacy-modes/mode/tcl'
+import { haskell } from '@codemirror/legacy-modes/mode/haskell'
+import { clojure } from '@codemirror/legacy-modes/mode/clojure'
+import { erlang } from '@codemirror/legacy-modes/mode/erlang'
+import { julia } from '@codemirror/legacy-modes/mode/julia'
+import { pascal } from '@codemirror/legacy-modes/mode/pascal'
+import { vb } from '@codemirror/legacy-modes/mode/vb'
+import { vhdl } from '@codemirror/legacy-modes/mode/vhdl'
+import { stex } from '@codemirror/legacy-modes/mode/stex'
+
+/** The lowercased file extension of a path ('' when none). */
+export function extOf(path: string): string {
+  const at = path.lastIndexOf('.')
+  if (at === -1) return ''
+  const base = path.slice(at + 1).toLowerCase()
+  return base.includes('/') || base.includes('\\') ? '' : base
+}
+
+/** Language key for an extension, or null for plain text. Pure (tested). */
+export function languageKeyForExt(ext: string): string | null {
+  switch (ext) {
+    case 'js': case 'mjs': case 'cjs': return 'js'
+    case 'jsx': return 'jsx'
+    case 'ts': case 'mts': case 'cts': return 'ts'
+    case 'tsx': return 'tsx'
+    case 'json': case 'jsonc': return 'json'
+    case 'md': case 'markdown': return 'md'
+    case 'py': case 'pyw': return 'python'
+    case 'html': case 'htm': return 'html'
+    case 'css': return 'css'
+    case 'xml': case 'xsl': return 'xml'
+    case 'yaml': case 'yml': return 'yaml'
+    case 'sql': return 'sql'
+    case 'java': return 'java'
+    case 'cs': return 'csharp'
+    case 'kt': case 'kts': return 'kotlin'
+    case 'swift': return 'swift'
+    case 'c': case 'h': return 'c'
+    case 'cc': case 'cpp': case 'cxx': case 'hpp': case 'hh': case 'hxx': return 'cpp'
+    case 'rs': return 'rust'
+    case 'go': return 'go'
+    case 'php': return 'php'
+    case 'sh': case 'bash': case 'zsh': return 'shell'
+    case 'toml': return 'toml'
+    case 'nginx': case 'conf': return 'nginx'
+    case 'dockerfile': case 'docker': return 'dockerfile'
+    case 'properties': case 'env': return 'properties'
+    case 'vue': return 'vue'
+    case 'scss': return 'scss'
+    case 'sass': return 'sass'
+    case 'less': return 'less'
+    case 'styl': return 'stylus'
+    case 'rb': return 'ruby'
+    case 'lua': return 'lua'
+    case 'pl': case 'pm': return 'perl'
+    case 'r': return 'r'
+    case 'dart': return 'dart'
+    case 'scala': case 'sc': return 'scala'
+    case 'groovy': return 'groovy'
+    case 'ps1': case 'psm1': return 'powershell'
+    case 'diff': case 'patch': return 'diff'
+    case 'proto': return 'protobuf'
+    case 'cmake': return 'cmake'
+    case 'pug': return 'pug'
+    case 'tcl': return 'tcl'
+    case 'hs': return 'haskell'
+    case 'clj': case 'cljs': return 'clojure'
+    case 'erl': return 'erlang'
+    case 'jl': return 'julia'
+    case 'pas': return 'pascal'
+    case 'vb': return 'vb'
+    case 'vhd': return 'vhdl'
+    case 'tex': return 'stex'
+    case 'mm': return 'objectivecpp'
+    // '.v' (Verilog/Coq/V) 与 '.m' (Objective-C/MATLAB) 存在跨语言歧义，
+    // 故意不映射——错配高亮比纯文本更误导。
+    default: return null
+  }
+}
+
+/** Per-lang `<style>` parsers for the Vue SFC factory (built once, shared). */
+const VUE_STYLE_PARSERS = {
+  scss: StreamLanguage.define(sCSS).parser,
+  sass: StreamLanguage.define(sass).parser,
+  less: StreamLanguage.define(less).parser,
+  stylus: StreamLanguage.define(stylus).parser,
+}
+
+const FACTORIES: Record<string, () => Language | LanguageSupport> = {
+  js: () => javascript({ jsx: true }),
+  jsx: () => javascript({ jsx: true }),
+  ts: () => javascript({ typescript: true }),
+  tsx: () => javascript({ typescript: true, jsx: true }),
+  json: () => json(),
+  md: () => markdown(),
+  python: () => python(),
+  html: () => html(),
+  css: () => css(),
+  xml: () => xml(),
+  yaml: () => yaml(),
+  sql: () => sql(),
+  java: () => java(),
+  csharp: () => StreamLanguage.define(csharp),
+  kotlin: () => StreamLanguage.define(kotlin),
+  swift: () => StreamLanguage.define(swift),
+  c: () => cpp(),
+  cpp: () => cpp(),
+  rust: () => rust(),
+  go: () => go(),
+  php: () => php(),
+  shell: () => StreamLanguage.define(shell),
+  toml: () => StreamLanguage.define(toml),
+  nginx: () => StreamLanguage.define(nginx),
+  dockerfile: () => StreamLanguage.define(dockerFile),
+  properties: () => StreamLanguage.define(properties),
+  // Vue SFC: lang-html's default html() base ALREADY parses <script>
+  // (no type → JS, type="module" → JS, lang="ts" → TS, JSON/importmap MIME
+  // types) and <style> → CSS through its built-in defaultNesting. The
+  // explicit entries only ADD what the defaults miss — case-insensitive
+  // lang="ts", lang="tsx"/"jsx" (the defaults only recognize the text/jsx &
+  // text/typescript-jsx MIME types), and per-lang <style> preprocessor
+  // dispatch. Same-tag entries are first-match wins and ours precede the
+  // defaults, so the predicates stay narrow: a constant-true entry would
+  // shadow the default JSON/importmap script handling and force the CSS
+  // parser onto <style lang="stylus">.
+  vue: () => vue({
+    base: html({
+      nestedLanguages: [
+        { tag: 'script', attrs: a => (a.lang ?? '').toLowerCase() === 'ts', parser: typescriptLanguage.parser },
+        { tag: 'script', attrs: a => (a.lang ?? '').toLowerCase() === 'tsx', parser: tsxLanguage.parser },
+        { tag: 'script', attrs: a => (a.lang ?? '').toLowerCase() === 'jsx', parser: jsxLanguage.parser },
+        { tag: 'style', attrs: a => (a.lang ?? '').toLowerCase() === 'css', parser: cssLanguage.parser },
+        { tag: 'style', attrs: a => (a.lang ?? '').toLowerCase() === 'scss', parser: VUE_STYLE_PARSERS.scss },
+        { tag: 'style', attrs: a => (a.lang ?? '').toLowerCase() === 'sass', parser: VUE_STYLE_PARSERS.sass },
+        { tag: 'style', attrs: a => (a.lang ?? '').toLowerCase() === 'less', parser: VUE_STYLE_PARSERS.less },
+        { tag: 'style', attrs: a => (a.lang ?? '').toLowerCase() === 'stylus', parser: VUE_STYLE_PARSERS.stylus },
+      ],
+    }),
+  }),
+  scss: () => StreamLanguage.define(sCSS),
+  sass: () => StreamLanguage.define(sass),
+  less: () => StreamLanguage.define(less),
+  stylus: () => StreamLanguage.define(stylus),
+  ruby: () => StreamLanguage.define(ruby),
+  lua: () => StreamLanguage.define(lua),
+  perl: () => StreamLanguage.define(perl),
+  r: () => StreamLanguage.define(r),
+  dart: () => StreamLanguage.define(dart),
+  scala: () => StreamLanguage.define(scala),
+  groovy: () => StreamLanguage.define(groovy),
+  powershell: () => StreamLanguage.define(powerShell),
+  diff: () => StreamLanguage.define(diff),
+  protobuf: () => StreamLanguage.define(protobuf),
+  cmake: () => StreamLanguage.define(cmake),
+  pug: () => StreamLanguage.define(pug),
+  tcl: () => StreamLanguage.define(tcl),
+  haskell: () => StreamLanguage.define(haskell),
+  clojure: () => StreamLanguage.define(clojure),
+  erlang: () => StreamLanguage.define(erlang),
+  julia: () => StreamLanguage.define(julia),
+  pascal: () => StreamLanguage.define(pascal),
+  vb: () => StreamLanguage.define(vb),
+  vhdl: () => StreamLanguage.define(vhdl),
+  stex: () => StreamLanguage.define(stex),
+  objectivecpp: () => StreamLanguage.define(objectiveCpp),
+}
+
+/** Every language key the extension table can produce (test seam). */
+export function supportedLanguageKeys(): readonly string[] {
+  return Object.keys(FACTORIES)
+}
+
+/** The CodeMirror language support for a path, or null for plain text. */
+export function languageForPath(path: string): Language | LanguageSupport | null {
+  const key = languageKeyForExt(extOf(path))
+  if (key === null) return null
+  try {
+    return FACTORIES[key]!()
+  } catch (error) {
+    // A broken factory degrades to plain text, never crashes the editor.
+    console.warn(`[dsh-better-sidebar] language factory "${key}" failed:`, error)
+    return null
+  }
+}

package/src/client/layout-push.ts

@@ -0,0 +1,37 @@
+/**
+ * Size written to `--dsh-sidebar-width` / `--dsh-sidebar-height`.
+ * The conversation column (output + composer) must keep at least
+ * {@link PANEL_MIN} of the viewport after the bottom panel claims height.
+ */
+import { PANEL_MIN } from './state.ts'
+
+export interface LayoutPushInput {
+  narrow: boolean
+  panelOpen: boolean
+  bottomOpen: boolean
+  width: number
+  bottomHeight: number
+  viewportWidth: number
+  viewportHeight: number
+}
+
+export interface LayoutPushSize {
+  width: number
+  height: number
+}
+
+function finiteNonNegative(value: number): number {
+  return Number.isFinite(value) ? Math.max(0, value) : 0
+}
+
+/** Compute the live layout-push size. Narrow drawers float and push 0. */
+export function layoutPushSize(input: LayoutPushInput): LayoutPushSize {
+  if (input.narrow) return { width: 0, height: 0 }
+  const viewportWidth = finiteNonNegative(input.viewportWidth)
+  const viewportHeight = finiteNonNegative(input.viewportHeight)
+  const maxHeight = Math.max(0, viewportHeight - Math.min(PANEL_MIN, viewportHeight))
+  return {
+    width: input.panelOpen ? Math.min(finiteNonNegative(input.width), viewportWidth) : 0,
+    height: input.bottomOpen ? Math.min(finiteNonNegative(input.bottomHeight), maxHeight) : 0,
+  }
+}

package/src/client/layout.css

@@ -0,0 +1,156 @@
+/**
+ * Layout push: when a panel is open it OCCUPIES the layout instead of
+ * floating over it — the app shell (#root, the AppFrame three-column grid)
+ * gives up space. Only the center column is flexible (1fr), so the right
+ * panel's width squeeze (margin-right on #root) lands exactly on the
+ * conversation output and the input bar, like a VSCode sidebar.
+ *
+ * The width rides `calc(100% - var(...))` instead of a bare margin on a
+ * full-width box: some desktop shells (DSH Desktop, #208) set #root to
+ * width:100%, where a margin would overflow the viewport additively —
+ * the calc keeps the box at exactly 100% minus the push in every shell.
+ * Width and margin transition in lockstep (same variable, same duration
+ * and easing), so expand/collapse animates the content width exactly as
+ * the bare-margin version did.
+ *
+ * The bottom panel squeezes ONLY the center column — it must not cover the
+ * app's own left sidebar or the right panel. The anchor is the frame's
+ * center grid item through stable slot/data attributes, not a positional
+ * path: current hosts put [data-slot="main"] directly inside the center
+ * column, while earlier hosts exposed [data-pane="conversation"] or a
+ * [data-slot="conversation"] child. A stretched grid item shrinks by its
+ * margins, so the conversation content (output + input bar) lifts without
+ * touching the sidebars.
+ *
+ * The sizes ride CSS variables updated by the Sidebar shell (0 while
+ * collapsed); expand/collapse animates both the margins and the panel
+ * slides on the same theme duration. Drags disable the transition so the
+ * layout tracks the pointer.
+ */
+#root {
+  margin-right: var(--dsh-sidebar-width, 0px);
+  width: calc(100% - var(--dsh-sidebar-width, 0px));
+  transition:
+    margin-right var(--ds-transition-duration-slow) var(--ds-ease-in-out),
+    width var(--ds-transition-duration-slow) var(--ds-ease-in-out);
+}
+
+/* The AppFrame's center column, anchored by data attributes (see above).
+   Composite selector: current DSH puts `[data-slot="main"]` directly inside
+   the center grid item; earlier shells name the item
+   `[data-pane="conversation"]` or put `[data-slot="conversation"]` inside it.
+   Every selector resolves to that same center element. */
+#root :has(> [data-slot="main"]),
+#root [data-dsh-frame] > [data-pane="conversation"],
+#root :has(> [data-slot="conversation"]) {
+  margin-bottom: var(--dsh-sidebar-height, 0px);
+  /* Grid/flex items default to min-height:auto. A long unbreakable token
+     (OAuth URL) then grows this column past the viewport and clips the
+     composer + left-rail Settings row. min-height:0 lets the cell shrink;
+     overflow-wrap lets the token wrap instead of forcing its intrinsic
+     size. The host's own descendants remain responsible for scrolling. */
+  min-height: 0;
+  overflow-wrap: anywhere;
+  transition: margin-bottom var(--ds-transition-duration-slow) var(--ds-ease-in-out);
+}
+
+/* On older hosts, a collapsed sidebar puts the fallback cluster in the
+   top-right corner. Push the DSH session header's right padding out so its
+   utilities yield instead of hiding under the cluster. Current DSH hosts put
+   the controls directly beside the Session log action and set
+   data-dsh-native-sidebar-toggle, so this rule stays inactive. The Sidebar
+   shell publishes the required reserve; 188px is the older-host fallback. Anchor on
+   the header's slot host wrapper ([data-slot="conversation.session.header"])
+   rather than a positional path: DSH 0.1.x nests the header several levels
+   under the center column. The Sidebar shell toggles the body attributes with
+   the host capability and panel open state. */
+body[data-dsh-sidebar-collapsed]:not([data-dsh-native-sidebar-toggle]) [data-slot="conversation.session.header"] > header {
+  padding-right: var(--dsh-sidebar-toggle-reserve, 188px);
+}
+
+body[data-dsh-sidebar-dragging] #root,
+body[data-dsh-sidebar-dragging] #root :has(> [data-slot="main"]),
+body[data-dsh-sidebar-dragging] #root [data-dsh-frame] > [data-pane="conversation"],
+body[data-dsh-sidebar-dragging] #root :has(> [data-slot="conversation"]) {
+  transition: none;
+}
+
+/* DSH 0.1.x gives external settings sections a generic gear and exposes no
+   icon field in the settings.section contract. settings-nav-icon.ts marks
+   only this plugin's localized row; render the requested Lucide
+   gallery-horizontal-end SVG as a currentColor mask so it follows the native
+   nav hover/active colors without changing the shell's 16px icon rhythm. */
+[data-dsh-better-sidebar-settings-nav] > svg:first-child {
+  display: none;
+}
+
+[data-dsh-better-sidebar-settings-nav]::before {
+  content: '';
+  flex: none;
+  width: 16px;
+  height: 16px;
+  background: currentColor;
+  -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M2 7v10'/%3E%3Cpath d='M6 5v14'/%3E%3Crect width='12' height='18' x='10' y='3' rx='2'/%3E%3C/svg%3E") center / contain no-repeat;
+  mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M2 7v10'/%3E%3Cpath d='M6 5v14'/%3E%3Crect width='12' height='18' x='10' y='3' rx='2'/%3E%3C/svg%3E") center / contain no-repeat;
+}
+
+/* The "Token 用量" heatmap section's nav row: same marker scheme as above,
+   painting a calendar glyph (Lucide calendar-days) — a month of days is the
+   section's whole subject. */
+[data-dsh-better-sidebar-usage-nav] > svg:first-child {
+  display: none;
+}
+
+[data-dsh-better-sidebar-usage-nav]::before {
+  content: '';
+  flex: none;
+  width: 16px;
+  height: 16px;
+  background: currentColor;
+  -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Crect width='18' height='18' x='3' y='4' rx='2'/%3E%3Cpath d='M16 2v4'/%3E%3Cpath d='M8 2v4'/%3E%3Cpath d='M3 10h18'/%3E%3Cpath d='M8 14h.01'/%3E%3Cpath d='M12 14h.01'/%3E%3Cpath d='M16 14h.01'/%3E%3Cpath d='M8 18h.01'/%3E%3Cpath d='M12 18h.01'/%3E%3Cpath d='M16 18h.01'/%3E%3C/svg%3E") center / contain no-repeat;
+  mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Crect width='18' height='18' x='3' y='4' rx='2'/%3E%3Cpath d='M16 2v4'/%3E%3Cpath d='M8 2v4'/%3E%3Cpath d='M3 10h18'/%3E%3Cpath d='M8 14h.01'/%3E%3Cpath d='M12 14h.01'/%3E%3Cpath d='M16 14h.01'/%3E%3Cpath d='M8 18h.01'/%3E%3Cpath d='M12 18h.01'/%3E%3Cpath d='M16 18h.01'/%3E%3C/svg%3E") center / contain no-repeat;
+}
+
+[data-dsh-better-sidebar-ai-ratio-nav] > svg:first-child {
+  display: none;
+}
+
+[data-dsh-better-sidebar-ai-ratio-nav]::before {
+  content: '';
+  flex: none;
+  width: 16px;
+  height: 16px;
+  background: currentColor;
+  -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='none'%3E%3Cpath d='M2.25 13.75h11.5M4.5 13.75v-3.5M7.5 13.75v-6.5M10.5 13.75v-4.5' stroke='black' stroke-width='1.5' stroke-linecap='round'/%3E%3Cpath d='M13 .9l.5 1.6 1.6.5-1.6.5-.5 1.6-.5-1.6-1.6-.5 1.6-.5z' fill='black'/%3E%3C/svg%3E") center / contain no-repeat;
+  mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='none'%3E%3Cpath d='M2.25 13.75h11.5M4.5 13.75v-3.5M7.5 13.75v-6.5M10.5 13.75v-4.5' stroke='black' stroke-width='1.5' stroke-linecap='round'/%3E%3Cpath d='M13 .9l.5 1.6 1.6.5-1.6.5-.5 1.6-.5-1.6-1.6-.5 1.6-.5z' fill='black'/%3E%3C/svg%3E") center / contain no-repeat;
+}
+
+/* The "更新" section's nav row: same marker scheme, painting an upward
+   arrow (Lucide arrow-up) — an upgrade/one-click-update is the section's
+   whole purpose. */
+[data-dsh-better-sidebar-update-nav] > svg:first-child {
+  display: none;
+}
+
+[data-dsh-better-sidebar-update-nav]::before {
+  content: '';
+  flex: none;
+  width: 16px;
+  height: 16px;
+  background: currentColor;
+  -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='m5 12 7-7 7 7'/%3E%3Cpath d='M12 19V5'/%3E%3C/svg%3E") center / contain no-repeat;
+  mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='m5 12 7-7 7 7'/%3E%3Cpath d='M12 19V5'/%3E%3C/svg%3E") center / contain no-repeat;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  #root,
+  #root :has(> [data-slot="main"]),
+  #root [data-dsh-frame] > [data-pane="conversation"],
+  #root :has(> [data-slot="conversation"]) {
+    transition: none;
+  }
+}
+
+[data-dsh-hidden-runtime-context] {
+  display: none !important;
+}

package/src/client/lazy-chunk.tsx

@@ -0,0 +1,89 @@
+/**
+ * Lazy chunk view wrapper: mounts a component that lives in a lazy chunk,
+ * showing a loading placeholder while the chunk script loads and an error +
+ * retry affordance on failure. Used by the built-in tab/viewer descriptors.
+ *
+ * Contract note: {@link lazyChunkComponent} returns a plain render-prop
+ * function — the descriptor contract is `component: (props) => ReactNode`,
+ * and the repo renders descriptors BOTH ways: Sidebar calls
+ * `descriptor.component(props)` directly, EditorHost renders it via
+ * `createElement`. The wrapper function body therefore contains no hooks;
+ * all state lives in the inner {@link LazyChunkView} component.
+ */
+import { createElement, useEffect, useState, type ComponentType, type ReactNode } from 'react'
+import { loadChunk, type ChunkExports, type ChunkName } from './chunk-loader.ts'
+import { t } from './locales.ts'
+import css from './sidebar.module.css'
+
+interface LazyChunkViewProps<P> {
+  chunk: ChunkName
+  /** Module-level-stable selector (an inline lambda would re-trigger the effect). */
+  pick: (mod: ChunkExports) => ComponentType<P> | undefined
+  props: P
+}
+
+function LazyChunkView<P>({ chunk, pick, props }: LazyChunkViewProps<P>): ReactNode {
+  const [attempt, setAttempt] = useState(0)
+  const [state, setState] = useState<
+    | { status: 'loading' }
+    | { status: 'error'; message: string }
+    | { status: 'ready'; Comp: ComponentType<any> }
+  >({ status: 'loading' })
+
+  useEffect(() => {
+    let cancelled = false
+    setState({ status: 'loading' })
+    loadChunk(chunk).then((mod) => {
+      if (cancelled) return
+      const Comp = pick(mod)
+      if (Comp === undefined) {
+        setState({ status: 'error', message: `[dsh-better-sidebar] chunk "${chunk}" is missing its component` })
+        return
+      }
+      setState({ status: 'ready', Comp })
+    }).catch((error: unknown) => {
+      if (cancelled) return
+      setState({ status: 'error', message: error instanceof Error ? error.message : String(error) })
+    })
+    return () => { cancelled = true }
+  }, [chunk, pick, attempt])
+
+  if (state.status === 'loading') {
+    return <div className={css.editorPlaceholder}>{t('loading')}</div>
+  }
+  if (state.status === 'error') {
+    return (
+      <div className={css.editorError}>
+        <span>{state.message}</span>
+        <button
+          type="button"
+          className={css.terminalRetry}
+          onClick={() => { setAttempt(current => current + 1) }}
+        >
+          {t('terminalRetry')}
+        </button>
+      </div>
+    )
+  }
+  return createElement(state.Comp, props)
+}
+
+/**
+ * Build a descriptor-compatible lazy wrapper for a chunk-resident component.
+ * The returned function is the descriptor `component` itself: it returns an
+ * element and never calls hooks, so both invocation styles (plain function
+ * call and createElement/JSX render) work. `pick` must be a module-level
+ * function (stable identity) — an inline lambda would re-trigger the load
+ * effect on every render.
+ * @param chunk - the chunk name (see chunk-loader.ts).
+ * @param pick - select the component from the chunk's exports.
+ */
+export function lazyChunkComponent<P extends object>(
+  chunk: ChunkName,
+  pick: (mod: ChunkExports) => ComponentType<P> | undefined,
+): (props: P) => ReactNode {
+  return (props: P) => createElement(
+    LazyChunkView as ComponentType<LazyChunkViewProps<P>>,
+    { chunk, pick, props },
+  )
+}

package/src/client/link-intercept.ts

@@ -0,0 +1,73 @@
+/**
+ * Chat/GUI external-link interception: clicking an http(s) link that points
+ * OUTSIDE the GUI (chat messages, tool rows, prose mentions) opens the
+ * sidebar instead of a new browser tab. Gated by the caller through
+ * `takeoverEnabled(url)` — the `browserInterceptLinks` master, the URL's
+ * protocol flag (`browserInterceptHttp` / `browserInterceptHttps`) and the
+ * target tab's enable switch — and a Ctrl/Cmd/Shift/Alt-modified click
+ * always bypasses the takeover so the user can still force a real browser
+ * tab.
+ *
+ * Only the GUI's OWN document is watched — links inside the browser tab's
+ * sandboxed iframe live in another document and never bubble here (and
+ * their clicks must keep working inside the sidebar).
+ */
+
+/** The pure decision: the URL to open in the sidebar, or null to let the
+ *  click fall through. Extracted so the policy is unit-testable without a
+ *  DOM. `anchorHref` must be the ABSOLUTE href (`<a>.href` already is).
+ *  The protocol/same-origin policy lives HERE; the prefs gates (master +
+ *  protocol flags + target enablement) live in the caller's
+ *  `takeoverEnabled(url)` callback. */
+export function shouldInterceptLink(anchorHref: string, selfOrigin: string): string | null {
+  let url: URL
+  try {
+    url = new URL(anchorHref)
+  } catch {
+    return null
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return null
+  // Same-origin links are GUI-internal navigation (settings pages, tool
+  // docs) — never routed into the sidebar.
+  try {
+    if (url.origin === new URL(selfOrigin).origin) return null
+  } catch {
+    // Unparsable selfOrigin (never in practice): intercept defensively.
+  }
+  return url.href
+}
+
+/** Whether a left-click may be taken over (unmodified left click only). */
+export function isPlainLeftClick(event: { button: number; metaKey: boolean; ctrlKey: boolean; shiftKey: boolean; altKey: boolean }): boolean {
+  return event.button === 0 && !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey
+}
+
+/**
+ * Register the document-level click capture that funnels external links
+ * into the sidebar. Returns the disposer (HMR-safe).
+ */
+export function registerLinkInterception(opts: {
+  /** Whether the takeover may happen for THIS url (the caller's prefs
+   *  gates: master switch, protocol flag, target enablement). */
+  takeoverEnabled: (url: URL) => boolean
+  /** Open the sidebar tab at `url` (the caller resolves the target type). */
+  openInSidebar: (url: string) => void
+  /** The GUI's own origin (window.location.origin at registration). */
+  selfOrigin: string
+}): () => void {
+  const onClick = (event: MouseEvent): void => {
+    if (!isPlainLeftClick(event)) return
+    if (event.defaultPrevented) return
+    const target = event.target
+    if (target === null || typeof (target as Element).closest !== 'function') return
+    const anchor = (target as Element).closest('a[href]') as HTMLAnchorElement | null
+    if (anchor === null || anchor.dataset.dshExternal === 'true') return
+    const url = shouldInterceptLink(anchor.href, opts.selfOrigin)
+    if (url === null) return
+    if (!opts.takeoverEnabled(new URL(url))) return
+    event.preventDefault()
+    opts.openInSidebar(url)
+  }
+  document.addEventListener('click', onClick, true)
+  return () => { document.removeEventListener('click', onClick, true) }
+}