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

package/src/client/session-pins.tsx

@@ -0,0 +1,334 @@
+/**
+ * A non-invasive extension of DSH's native Workspace browser.
+ *
+ * `sidebar.workspaces` is a single-owner host slot, so replacing its occupant
+ * would also mean reimplementing search, workspace creation, ordering and all
+ * of the native dialogs. Instead this module mounts one small React island as
+ * a PEER of that slot and augments the existing row menu. The native browser
+ * therefore continues to own every pre-existing action.
+ */
+import { createRoot, type Root } from 'react-dom/client'
+import { useEffect, useState, useSyncExternalStore } from 'react'
+import type { Context, SidebarSessionSummary } from '../context-types.ts'
+import type { SidebarStore } from './state.ts'
+import { api } from './api.ts'
+import { parsePrefs } from './prefs.ts'
+import { t } from './locales.ts'
+import { IconPinOutline16 } from './icons.tsx'
+import css from './sidebar.module.css'
+
+const PIN_SETTINGS_KEY = 'session-pins'
+
+/** Read and sanitize the plugin-owned durable pin order. */
+export function pinnedSessionIdsOf(value: { pluginSettings: Record<string, Record<string, unknown>> }): string[] {
+  const raw = value.pluginSettings[PIN_SETTINGS_KEY]?.ids
+  if (!Array.isArray(raw)) return []
+  const seen = new Set<string>()
+  return raw.filter((id): id is string => {
+    if (typeof id !== 'string' || id === '' || seen.has(id)) return false
+    seen.add(id)
+    return true
+  })
+}
+
+function pinSettings(ids: readonly string[]): Record<string, unknown> {
+  return { ids: [...ids] }
+}
+
+/** A small current-color pin icon for the menu row injected into DSH's menu. */
+function pinIconMarkup(): string {
+  return '<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true"><path d="M9.5 1.5 14.5 6.5 12.5 8.5 10 6 5.5 10.5 6 12 4.5 13.5 2.5 11.5 4 10 5.5 10.5 10 6 7.5 8.5 6.5Z" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round"/></svg>'
+}
+
+function isSessionRow(element: Element | null): element is HTMLElement {
+  return element instanceof HTMLElement && element.matches('[class*="_sessionRow"]')
+}
+
+/**
+ * The native row deliberately has no session-id DOM attribute. React retains
+ * the row component's `node` prop on its fiber, however; read that identity
+ * rather than guessing from the title (automatic titles can be duplicated).
+ */
+function sessionIdFromReactRow(row: HTMLElement): string | undefined {
+  const record = row as unknown as Record<string, unknown>
+  const fiberKey = Object.keys(record).find(key => key.startsWith('__reactFiber$'))
+  let fiber = fiberKey === undefined ? undefined : record[fiberKey] as Record<string, unknown> | undefined
+  const seen = new Set<object>()
+  while (fiber !== undefined && !seen.has(fiber)) {
+    seen.add(fiber)
+    const props = fiber.memoizedProps as Record<string, unknown> | undefined
+    const node = props?.node as Record<string, unknown> | undefined
+    if (typeof node?.id === 'string') return node.id
+    fiber = fiber.return as Record<string, unknown> | undefined
+  }
+  return undefined
+}
+
+/** Keep native Workspace rows hidden only while their session is pinned. */
+function syncNativePinnedRows(ids: readonly string[]): void {
+  const pinned = new Set(ids)
+  for (const row of document.querySelectorAll<HTMLElement>('[data-slot="sidebar.workspaces"] [class*="_sessionRow"]')) {
+    const sessionId = sessionIdFromReactRow(row)
+    if (sessionId !== undefined && pinned.has(sessionId)) row.dataset.dshSessionPinned = ''
+    else delete row.dataset.dshSessionPinned
+  }
+}
+
+function menuNear(anchor: HTMLElement): HTMLElement | undefined {
+  const rect = anchor.getBoundingClientRect()
+  return [...document.querySelectorAll<HTMLElement>('[role="menu"]')].find((menu) => {
+    if (menu.dataset.dshSessionPinMenu === 'true') return false
+    const items = menu.querySelectorAll(':scope button[role="menuitem"]')
+    if (items.length !== 3 || menu.getClientRects().length === 0) return false
+    const menuRect = menu.getBoundingClientRect()
+    return Math.abs(menuRect.top - rect.top) < 260 && Math.abs(menuRect.left - rect.right) < 360
+  })
+}
+
+/**
+ * Mount the separate pinned group and append a fourth item to DSH's native
+ * three-item row menu. The group is inserted beside (not inside) the host
+ * Workspace slot, so it is a top-level left-sidebar section. Both DOM seams
+ * are explicitly scoped to the current alpha host's stable slot and row class
+ * suffixes; failure is fail-open and leaves the native Workspace UI untouched.
+ */
+export function installSessionPins(ctx: Context, store: SidebarStore): () => void {
+  let root: Root | undefined
+  let mount: HTMLDivElement | undefined
+  let observer: MutationObserver | undefined
+  let write = Promise.resolve()
+  let rowSyncFrame: number | undefined
+
+  const scheduleNativeRowSync = (): void => {
+    if (rowSyncFrame !== undefined) return
+    rowSyncFrame = requestAnimationFrame(() => {
+      rowSyncFrame = undefined
+      syncNativePinnedRows(pinnedSessionIdsOf(store.getPrefs()))
+    })
+  }
+
+  const updatePins = (nextIds: readonly string[]): void => {
+    const before = store.getPrefs()
+    const next = {
+      ...before,
+      pluginSettings: {
+        ...before.pluginSettings,
+        [PIN_SETTINGS_KEY]: pinSettings(nextIds),
+      },
+    }
+    store.setPrefs(next)
+    write = write.catch(() => undefined).then(async () => {
+      const current = store.getPrefs()
+      const view = await api.settingsUpdate({
+        pluginSettings: {
+          ...current.pluginSettings,
+          [PIN_SETTINGS_KEY]: pinSettings(nextIds),
+        },
+      })
+      store.setPrefs(parsePrefs(view.value))
+    }).catch((error: unknown) => {
+      // Do not roll back a later toggle if this older write fails.
+      if (pinnedSessionIdsOf(store.getPrefs()).join('\0') === nextIds.join('\0')) store.setPrefs(before)
+      console.warn('[dsh-better-sidebar] persist session pins failed:', error)
+    })
+  }
+
+  const sessionForRow = (row: HTMLElement): SidebarSessionSummary | undefined => {
+    const id = sessionIdFromReactRow(row)
+    if (id === undefined) return undefined
+    const list = ctx.sessions.list.getSnapshot()
+    const session = list.byId[id]
+    return session?.origin === 'subagent' ? undefined : session
+  }
+
+  const decorateMenu = (anchor: HTMLElement, sessionId: string): void => {
+    const menu = menuNear(anchor)
+    if (menu === undefined) return
+    const template = menu.querySelector<HTMLButtonElement>(':scope button[role="menuitem"]')
+    if (template === null || template === undefined) return
+    menu.dataset.dshSessionPinMenu = 'true'
+    const item = template.cloneNode(true) as HTMLButtonElement
+    item.dataset.dshSessionPinAction = sessionId
+    const pinned = pinnedSessionIdsOf(store.getPrefs()).includes(sessionId)
+    const label = item.querySelector<HTMLElement>('span[class*="_itemLabel"]')
+    if (label !== null) label.textContent = pinned ? t('unpinSession') : t('pinSession')
+    else item.textContent = pinned ? t('unpinSession') : t('pinSession')
+    const icon = item.querySelector<HTMLElement>('span[class*="_itemIcon"]')
+    if (icon !== null) icon.innerHTML = pinIconMarkup()
+    item.addEventListener('click', (event) => {
+      event.preventDefault()
+      event.stopPropagation()
+      const ids = pinnedSessionIdsOf(store.getPrefs())
+      updatePins(ids.includes(sessionId) ? ids.filter(id => id !== sessionId) : [...ids, sessionId])
+      // The portal is owned by DSH React.  Never remove it ourselves: doing
+      // so leaves React attempting to unmount an already-detached node and
+      // can take the whole Workspace browser down on its next render.  Its
+      // standard outside-pointer listener closes the menu safely.
+      document.body.dispatchEvent(new Event('pointerdown', { bubbles: true }))
+    })
+    menu.appendChild(item)
+  }
+
+  const onDocumentClick = (event: MouseEvent): void => {
+    const button = (event.target as Element | null)?.closest('button')
+    const row = button?.closest('[class*="_sessionRow"]')
+    if (row === null || row === undefined || !isSessionRow(row) || button === null || button === undefined) return
+    const session = sessionForRow(row)
+    if (session === undefined) return
+    // DSH creates its portalled menu during this click's React update.
+    requestAnimationFrame(() => { decorateMenu(button, session.id) })
+  }
+
+  const attach = (): void => {
+    const slot = document.querySelector<HTMLElement>('[data-slot="sidebar.workspaces"]')
+    const region = slot?.parentElement
+    if (slot === null || slot === undefined || !(region instanceof HTMLElement) || mount?.parentElement === region) return
+    root?.unmount()
+    mount?.remove()
+    mount = document.createElement('div')
+    mount.dataset.dshPinnedSessions = ''
+    // The slot wrapper is `display: contents`; placing this mount immediately
+    // before it makes the pin group a peer of the Workspace browser in the
+    // sidebar's flex column, not a child of the browser's session list.
+    region.insertBefore(mount, slot)
+    root = createRoot(mount)
+    root.render(<PinnedSessions ctx={ctx} store={store} onChange={updatePins} />)
+  }
+
+  observer = new MutationObserver(() => {
+    // Conversation streaming mutates the page continuously.  Once our island
+    // is attached there is nothing to scan; only a host re-render that removes
+    // it needs a fresh lookup.
+    if (!mount?.isConnected) attach()
+    if (pinnedSessionIdsOf(store.getPrefs()).length > 0) scheduleNativeRowSync()
+  })
+  observer.observe(document.body, { childList: true, subtree: true })
+  attach()
+  document.addEventListener('click', onDocumentClick, true)
+  return () => {
+    document.removeEventListener('click', onDocumentClick, true)
+    observer?.disconnect()
+    if (rowSyncFrame !== undefined) cancelAnimationFrame(rowSyncFrame)
+    syncNativePinnedRows([])
+    root?.unmount()
+    mount?.remove()
+  }
+}
+
+function PinnedSessions({ ctx, store, onChange }: {
+  ctx: Context
+  store: SidebarStore
+  onChange: (ids: readonly string[]) => void
+}) {
+  const list = useSyncExternalStore(ctx.sessions.list.subscribe, ctx.sessions.list.getSnapshot, ctx.sessions.list.getSnapshot)
+  const prefs = useSyncExternalStore(store.subscribe.bind(store), store.getSnapshot.bind(store), store.getSnapshot.bind(store)).prefs
+  const ids = pinnedSessionIdsOf(prefs)
+  const pinKey = ids.join('\0')
+  const sessions = ids.flatMap((id) => {
+    const session = list.byId[id]
+    return session === undefined || session.origin === 'subagent' ? [] : [session]
+  })
+  const [menuFor, setMenuFor] = useState<string | undefined>()
+
+  // Purge only definitively vanished rows; a temporarily warming list must
+  // never erase a durable pin just after startup.
+  useEffect(() => {
+    if (sessions.length === ids.length || Object.keys(list.byId).length === 0) return
+    onChange(sessions.map(session => session.id))
+  }, [ids.length, list.byId, onChange, sessions])
+
+  useEffect(() => {
+    syncNativePinnedRows(ids)
+    return () => { syncNativePinnedRows([]) }
+  }, [pinKey])
+
+  const closeMenu = (): void => { setMenuFor(undefined) }
+
+  const renameSession = (session: SidebarSessionSummary): void => {
+    const title = window.prompt(t('pinnedSessionRenamePrompt'), session.displayTitle)?.trim()
+    if (title === undefined || title === '') return
+    closeMenu()
+    void ctx.sessions.binding?.(session.id)?.session.rename(title).catch((error: unknown) => {
+      console.warn('[dsh-better-sidebar] rename pinned session failed:', error)
+    })
+  }
+
+  const forkSession = (sessionId: string): void => {
+    closeMenu()
+    void ctx.sessions.fork?.({ sessionId, increaseTitle: true }).then((childId) => {
+      ctx.sessions.open?.(childId)
+    }).catch((error: unknown) => {
+      console.warn('[dsh-better-sidebar] fork pinned session failed:', error)
+    })
+  }
+
+  const archiveSession = (sessionId: string): void => {
+    closeMenu()
+    // `archiveSession` is a native Workspace browser verb. It is intentionally
+    // structural here: this island reuses the host action rather than owning
+    // a parallel archive implementation.
+    const archive = (ctx.workspaces as typeof ctx.workspaces & {
+      archiveSession?: (id: string) => Promise<void>
+    }).archiveSession
+    if (archive === undefined) return
+    void archive(sessionId).then(() => {
+      onChange(ids.filter(id => id !== sessionId))
+    }).catch((error: unknown) => {
+      console.warn('[dsh-better-sidebar] archive pinned session failed:', error)
+    })
+  }
+
+  if (sessions.length === 0) return null
+  return (
+    <section className={css.pinnedSessions} aria-label={t('pinnedSessions')}>
+      <div className={css.pinnedSessionsHeading}>
+        <span>{t('pinnedSessions')}</span>
+      </div>
+      <div className={css.pinnedSessionsList} role="list">
+        {sessions.map(session => (
+          <div className={css.pinnedSessionRow} key={session.id} role="listitem">
+            <button
+              type="button"
+              className={css.pinnedSessionOpen}
+              aria-current={session.id === list.current ? 'page' : undefined}
+              onClick={() => { ctx.sessions.open?.(session.id) }}
+            >
+              <span className={css.pinnedSessionDot} data-running={session.running || undefined} aria-hidden="true" />
+              <span className={css.pinnedSessionTitle}>{session.displayTitle}</span>
+            </button>
+            <button
+              type="button"
+              className={css.pinnedSessionMore}
+              aria-label={t('unpinSession')}
+              aria-expanded={menuFor === session.id}
+              onClick={() => { setMenuFor(menuFor === session.id ? undefined : session.id) }}
+            >
+              <span aria-hidden="true">•••</span>
+            </button>
+            {menuFor === session.id && (
+              <div className={css.pinnedSessionMenu} role="menu">
+                <button type="button" role="menuitem" onClick={() => { renameSession(session) }}>
+                  {t('pinnedSessionRename')}
+                </button>
+                <button type="button" role="menuitem" onClick={() => { forkSession(session.id) }}>
+                  {t('pinnedSessionFork')}
+                </button>
+                <button type="button" role="menuitem" onClick={() => { archiveSession(session.id) }}>
+                  {t('pinnedSessionArchive')}
+                </button>
+                <div className={css.pinnedSessionMenuDivider} role="separator" />
+                <button type="button" role="menuitem" onClick={() => {
+                  onChange(ids.filter(id => id !== session.id))
+                  closeMenu()
+                }}>
+                  <IconPinOutline16 size={16} />
+                  {t('unpinSession')}
+                </button>
+              </div>
+            )}
+          </div>
+        ))}
+      </div>
+    </section>
+  )
+}

package/src/client/settings-nav-icon.ts

@@ -0,0 +1,55 @@
+/**
+ * Mark this plugin's row in the DSH settings navigation so its bundled CSS
+ * can replace the shell's fallback gear with the Side card glyph.
+ *
+ * DSH 0.1.x projects only `id`, `order`, and `label` from a
+ * `settings.section` registration, then chooses icons inside the settings
+ * shell from a closed list of built-in ids. Until that public contract grows
+ * an icon field, the plugin identifies only its own localized row after the
+ * dialog mounts. The marker owns no shell structure and is removed on fiber
+ * disposal, so the adaptation remains HMR-safe.
+ */
+
+export const SETTINGS_NAV_MARKER = 'data-dsh-better-sidebar-settings-nav'
+
+/** Marker of the "Token 用量" (usage heatmap) settings nav row. */
+export const USAGE_NAV_MARKER = 'data-dsh-better-sidebar-usage-nav'
+export const AI_RATIO_NAV_MARKER = 'data-dsh-better-sidebar-ai-ratio-nav'
+
+/** Marker of the "更新" (update) settings nav row. */
+export const UPDATE_NAV_MARKER = 'data-dsh-better-sidebar-update-nav'
+
+/**
+ * Keep the marker on the settings-nav button whose visible text is this
+ * plugin's current localized section label.
+ * @param label - locale-aware label resolver used by the section registration.
+ * @param marker - the marker attribute this registration owns (each icon gets
+ *  its own so several sections can mark their rows without stripping each
+ *  other's markers).
+ * @returns disposer that disconnects observation and removes owned markers.
+ */
+export function registerSettingsNavIcon(label: () => string, marker: string = SETTINGS_NAV_MARKER): () => void {
+  let disposed = false
+
+  const sync = (): void => {
+    if (disposed) return
+    const currentLabel = label().trim()
+    const buttons = document.querySelectorAll<HTMLButtonElement>('[role="dialog"] nav button')
+    for (const button of buttons) {
+      const matches = currentLabel.length > 0 && button.textContent?.trim() === currentLabel
+      if (matches) button.setAttribute(marker, '')
+      else button.removeAttribute(marker)
+    }
+  }
+
+  sync()
+  const observer = new MutationObserver(sync)
+  observer.observe(document.body, { childList: true, subtree: true, characterData: true })
+
+  return () => {
+    disposed = true
+    observer.disconnect()
+    document.querySelectorAll(`[${marker}]`)
+      .forEach(element => { element.removeAttribute(marker) })
+  }
+}

package/src/client/shell-presets.ts

@@ -0,0 +1,83 @@
+/**
+ * Built-in desktop-shell presets for the "位置兼容模式" secondary setting
+ * (scheme `preset`). DATA-DRIVEN by design: each shell's adaptation lives
+ * in one entry (strip values / optional CSS), the core applies it through
+ * the SAME generic strip variable and CSS-injection mechanism — adding a
+ * shell is adding data, never a code path.
+ *
+ * Inclusion rule (maintained in docs/external-plugin-guide.md §12): only shells that (a) appear
+ * in this repo's issues/PRs (a user actually hit a problem) and (b) have
+ * 100+ GitHub stars (a real user base). The mechanism is opt-in: auto
+ * detection never applies a preset — the settings badge only SUGGESTS it.
+ */
+import type { DesktopEnv } from './desktop-env.ts'
+
+export interface ShellPreset {
+  /** Stable preset id (persisted in `titleBarPresetId`). */
+  readonly id: string
+  /** User-facing name of the shell. */
+  readonly title: string
+  /** One-line description shown in the settings popup. */
+  readonly desc: string
+  /**
+   * The top strip (px) this shell reserves over web content, per
+   * environment — the fallback used when neither the standard WCO API nor
+   * the `dsh-desktop-titlebar-inset` contract parameter is available.
+   * Return undefined when the shell needs no strip in that environment.
+   * MUST be pure (called during render).
+   */
+  readonly stripFor?: (env: DesktopEnv) => number | undefined
+  /**
+   * Extra CSS applied while the preset is enabled (injected last, after the
+   * plugin's own styles). Targets the plugin's stable data attributes and
+   * shell-declared body/URL markers only — never other shells' class names.
+   * Empty for presets fully covered by the strip variable.
+   */
+  readonly css?: string
+  /**
+   * Whether this shell's marker is currently visible (URL stamps / preload
+   * markers — see desktop-env.ts). Used ONLY for the settings "已检测"
+   * badge; never auto-applies anything. MUST be pure.
+   */
+  readonly detect?: (env: DesktopEnv) => boolean
+}
+
+/**
+ * DeepSeek Harness Desktop (anywhere-labs, Electron, 16k+ stars — the most
+ * reported shell in this repo's issues/PRs). Advanced mode: macOS reserves
+ * a 20px caption row (traffic lights top-left), win32 draws the native
+ * window controls in a ~32px overlay (WCO reports the real height when
+ * available, which the auto scheme already consumes; the 32 is the
+ * no-WCO fallback). Compatibility mode keeps the native frame — nothing.
+ */
+const DSH_DESKTOP: ShellPreset = {
+  id: 'dsh-desktop',
+  title: 'DeepSeek Harness Desktop',
+  desc: 'Electron 高级模式（无边框）：macOS 顶栏 20px、Windows 无 WCO 时 32px 标题栏让位',
+  stripFor: (env) => {
+    if (env.mode !== 'advanced') return undefined
+    if (env.platform === 'darwin') return 20
+    if (env.platform === 'win32') return 32
+    return undefined
+  },
+  detect: (env) => env.mode === 'advanced',
+}
+
+const PRESETS: readonly ShellPreset[] = [
+  DSH_DESKTOP,
+]
+
+/** All built-in shell presets (registration order = settings list order). */
+export function getShellPresets(): readonly ShellPreset[] {
+  return PRESETS
+}
+
+/** One preset by id, or undefined for an unknown/empty id. */
+export function getShellPreset(id: string): ShellPreset | undefined {
+  return PRESETS.find(preset => preset.id === id)
+}
+
+/** The strip the active preset contributes for the given environment. */
+export function presetStripFor(preset: ShellPreset | undefined, env: DesktopEnv): number | undefined {
+  return preset?.stripFor?.(env)
+}