dsh-coding-sidebar 1.0.0

package/src/client/subagent-detect.ts

@@ -0,0 +1,137 @@
+/**
+ * Pure subagent-membership helpers over the sessions list feed (structural
+ * mirror world — no runtime imports). Used by the sidebar's auto-activation
+ * effect and the Subagent page:
+ *
+ * - {@link directSubagentCount}: direct durable children of one session,
+ * - {@link detectNewDirectSubagent}: the 0 → N transition that means "a new
+ *   subagent just spawned under the current session" (the auto-open trigger),
+ * - {@link countSubagentDescendants}: uninterrupted subagent-origin lineage
+ *   totals (mirror of the official `indexSubagentDescendants` over the
+ *   plugin's own summary rows).
+ */
+import type {
+  SidebarSessionList,
+  SidebarSessionSummary,
+  SidebarSubagentCatalog,
+} from '../context-types.ts'
+import { SIDE_LABEL_PREFIX } from '../sidechat-core.ts'
+
+/**
+ * Side Chat threads ride the subagent origin (main-list hiding + the RPC
+ * ownership fence) but they are NOT subagent topology: they carry the
+ * durable 'Side: ' label and live as sidebar tabs. Excluding them here
+ * keeps the auto-open trigger and the Subagent page counts clean.
+ */
+export function isSideThreadSummary(summary: SidebarSessionSummary): boolean {
+  return summary.origin === 'subagent' && summary.displayTitle.startsWith(SIDE_LABEL_PREFIX)
+}
+
+/** Count the direct subagent children of one session (durable `origin` rows). */
+export function directSubagentCount(
+  byId: SidebarSessionList['byId'],
+  sessionId: string,
+): number {
+  let count = 0
+  for (const summary of Object.values(byId)) {
+    if (summary.origin === 'subagent' && summary.parentId === sessionId
+      && !isSideThreadSummary(summary)) count += 1
+  }
+  return count
+}
+
+/**
+ * The main agent of the current session's tree: walk the durable parent
+ * chain upward until the first non-subagent session. The Subagent page shows
+ * THIS root's full topology regardless of how deep the current selection is
+ * (a session whose row is still hydrating, or a broken chain, degrades to
+ * the session itself).
+ */
+export function rootAncestor(
+  byId: SidebarSessionList['byId'],
+  sessionId: string | undefined,
+): string | undefined {
+  if (sessionId === undefined) return undefined
+  const seen = new Set<string>()
+  let current: SidebarSessionSummary | undefined = byId[sessionId]
+  while (current !== undefined && current.origin === 'subagent'
+    && current.parentId !== undefined && !seen.has(current.id)) {
+    seen.add(current.id)
+    current = byId[current.parentId]
+  }
+  return current?.id ?? sessionId
+}
+
+/**
+ * Collect every catalog branch (an entry with `hasChildren`) reachable from
+ * the root — the set of catalogs the always-expanded topology consumes.
+ * Cycles fail soft.
+ */
+export function collectBranchIds(
+  catalogs: Readonly<Record<string, SidebarSubagentCatalog>>,
+  rootId: string | undefined,
+): string[] {
+  const out: string[] = []
+  const seen = new Set<string>()
+  const visit = (parentId: string): void => {
+    if (seen.has(parentId)) return
+    seen.add(parentId)
+    for (const entry of catalogs[parentId]?.entries ?? []) {
+      if (entry.kind === 'child' && entry.hasChildren) {
+        out.push(entry.id)
+        visit(entry.id)
+      }
+    }
+  }
+  if (rootId !== undefined) visit(rootId)
+  return out
+}
+
+/**
+ * Whether a new direct subagent appeared under `sessionId` between two
+ * consecutive list snapshots (the count crossed 0 → >0). Switching to a
+ * session that already has subagents yields `false` (its baseline starts at
+ * the current count), so the auto-open never fights an existing layout.
+ */
+export function detectNewDirectSubagent(
+  prev: SidebarSessionList,
+  next: SidebarSessionList,
+  sessionId: string,
+): boolean {
+  return directSubagentCount(prev.byId, sessionId) === 0
+    && directSubagentCount(next.byId, sessionId) > 0
+}
+
+/** Descendant totals of one session through an uninterrupted subagent-origin chain. */
+export interface SubagentDescendantTotals {
+  count: number
+  runningCount: number
+}
+
+/**
+ * Index every subagent descendant under each ancestor it reaches through an
+ * uninterrupted subagent-origin chain (same semantics as the official
+ * `indexSubagentDescendants`; cycles fail soft).
+ */
+export function countSubagentDescendants(
+  byId: SidebarSessionList['byId'],
+  sessionId: string,
+): SubagentDescendantTotals {
+  const totals: SubagentDescendantTotals = { count: 0, runningCount: 0 }
+  for (const descendant of Object.values(byId)) {
+    if (descendant.origin !== 'subagent' || isSideThreadSummary(descendant)) continue
+    const seen = new Set<string>()
+    let current: SidebarSessionSummary | undefined = descendant
+    while (current?.origin === 'subagent' && current.parentId !== undefined
+      && !seen.has(current.id)) {
+      seen.add(current.id)
+      if (current.parentId === sessionId) {
+        totals.count += 1
+        if (descendant.running === true) totals.runningCount += 1
+        break
+      }
+      current = byId[current.parentId]
+    }
+  }
+  return totals
+}

package/src/client/subagent-jobs.ts

@@ -0,0 +1,161 @@
+/**
+ * Pure derivations for the Subagent page's background-job section. Kept
+ * framework-free so the node test environment can unit-test them: the job
+ * rows arrive through the harness `session/jobs` push mirror
+ * (`jobsBySession` in the sessions list feed) — nothing here issues
+ * requests, and the row ordering / status mapping mirror the official
+ * ui-jobs header list.
+ */
+import type {
+  SidebarSessionList,
+  SidebarSessionSummary,
+  SidebarJobStatus,
+  SidebarJobView,
+} from '../context-types.ts'
+import type { CopyKey } from './locales.ts'
+
+/** One row of the jobs section: the job plus its owning session's title. */
+export interface TreeJob {
+  ownerSessionId: string
+  ownerTitle: string
+  job: SidebarJobView
+}
+
+/** Whether the registry still holds the job open (its duration ticks). */
+export function isJobLive(job: SidebarJobView): boolean {
+  return job.status === 'running' || job.status === 'stopping'
+}
+
+/**
+ * Every session id of the topology tree rooted at `rootId` (the root plus
+ * each session whose uninterrupted subagent-origin chain reaches it — same
+ * lineage semantics as {@link countSubagentDescendants}; cycles fail soft).
+ * Sessions outside the tree (orphans, other trees) are excluded, so the
+ * jobs section never shows foreign work.
+ */
+export function treeSessionIds(
+  byId: SidebarSessionList['byId'],
+  rootId: string | undefined,
+): Set<string> {
+  const ids = new Set<string>()
+  if (rootId === undefined) return ids
+  for (const summary of Object.values(byId)) {
+    const seen = new Set<string>()
+    let current: SidebarSessionSummary | undefined = summary
+    let reachesRoot = false
+    while (current !== undefined && !seen.has(current.id)) {
+      seen.add(current.id)
+      if (current.id === rootId) {
+        reachesRoot = true
+        break
+      }
+      if (current.origin !== 'subagent' || current.parentId === undefined) break
+      current = byId[current.parentId]
+    }
+    if (reachesRoot) ids.add(summary.id)
+  }
+  return ids
+}
+
+/**
+ * Whether a NEW background job appeared for one session between two
+ * consecutive list snapshots (a job id the previous snapshot lacked).
+ * Unlike the subagent auto-open (0 → N only), ANY new job id triggers: the
+ * agent may start several jobs over a session, and each new one should
+ * surface the Jobs page (a fresh page load never triggers — its baseline
+ * starts at the current snapshot).
+ */
+export function detectNewJob(
+  prev: SidebarSessionList,
+  next: SidebarSessionList,
+  sessionId: string,
+): boolean {
+  const prevIds = new Set((prev.jobsBySession?.[sessionId] ?? []).map(job => job.id))
+  return (next.jobsBySession?.[sessionId] ?? []).some(job => !prevIds.has(job.id))
+}
+
+/**
+ * Collect the background jobs of the whole current tree, owner-labeled.
+ * Sessions without a mirror entry contribute nothing; an absent mirror
+ * (runtime older than the jobs feed) yields an empty list.
+ */
+export function collectTreeJobs(
+  byId: SidebarSessionList['byId'],
+  jobsBySession: Readonly<Record<string, readonly SidebarJobView[]>> | undefined,
+  rootId: string | undefined,
+): TreeJob[] {
+  const rows: TreeJob[] = []
+  if (jobsBySession === undefined) return rows
+  for (const sessionId of treeSessionIds(byId, rootId)) {
+    const jobs = jobsBySession[sessionId]
+    if (jobs === undefined || jobs.length === 0) continue
+    const ownerTitle = byId[sessionId]?.displayTitle ?? sessionId
+    for (const job of jobs) rows.push({ ownerSessionId: sessionId, ownerTitle, job })
+  }
+  return rows
+}
+
+/**
+ * Live rows first in start order, then settled rows newest-first (mirror of
+ * the official ui-jobs ordering); a tie falls back to start order so the
+ * sort never depends on the host's map iteration.
+ */
+export function orderJobs(rows: readonly TreeJob[]): TreeJob[] {
+  return [...rows].sort((left, right) => {
+    const liveLeft = isJobLive(left.job)
+    if (liveLeft !== isJobLive(right.job)) return liveLeft ? -1 : 1
+    if (liveLeft) return left.job.startedAt - right.job.startedAt
+    const finished = (right.job.finishedAt ?? right.job.startedAt) - (left.job.finishedAt ?? left.job.startedAt)
+    return finished !== 0 ? finished : left.job.startedAt - right.job.startedAt
+  })
+}
+
+/** The sidebar's StateDot states for the five wire statuses. */
+export type JobDotState = 'ongoing' | 'warning' | 'done' | 'error'
+
+/**
+ * Status marker semantics. `stopping` and `killed` share the attention
+ * color: both mean the work ended (or is ending) on request rather than on
+ * its own.
+ */
+export function jobDotState(status: SidebarJobStatus): JobDotState {
+  switch (status) {
+    case 'running': return 'ongoing'
+    case 'stopping': return 'warning'
+    case 'completed': return 'done'
+    case 'killed': return 'warning'
+    case 'failed': return 'error'
+  }
+}
+
+/** Human status word of one wire status (localized through the passed translator). */
+export function jobStatusLabel(
+  status: SidebarJobStatus,
+  t: (key: CopyKey, params?: Record<string, string | number>) => string,
+): string {
+  switch (status) {
+    case 'running': return t('jobStatusRunning')
+    case 'stopping': return t('jobStatusStopping')
+    case 'completed': return t('jobStatusCompleted')
+    case 'killed': return t('jobStatusKilled')
+    case 'failed': return t('jobStatusFailed')
+  }
+}
+
+/**
+ * Elapsed time in at most two adjacent units (mirror of the official
+ * ui-jobs duration wording). A background job that outlives an hour is
+ * already exceptional, so hours is the widest unit.
+ */
+export function formatJobDuration(
+  elapsedMs: number,
+  t: (key: CopyKey, params?: Record<string, string | number>) => string,
+): string {
+  const total = Math.max(0, Math.floor(elapsedMs / 1_000))
+  const seconds = total % 60
+  const minutes = Math.floor(total / 60) % 60
+  const hours = Math.floor(total / 3_600)
+  if (hours > 0) return t('jobDurationHours', { hours, minutes })
+  if (minutes > 0) return t('jobDurationMinutes', { minutes, seconds })
+  return t('jobDurationSeconds', { seconds })
+}

package/src/client/tab-content-memo.ts

@@ -0,0 +1,55 @@
+/**
+ * The memo comparator for one tab's content cell (TabContent in Sidebar.tsx).
+ *
+ * Kept as a pure module so the "what re-renders a tab cell" contract is unit
+ * testable: geometry/store re-renders of the Sidebar shell must NOT reconcile
+ * every mounted tab (xterm/CodeMirror/FileTree subtrees — issue #315), while
+ * locale switches (localeRevision), tab-registry updates (tabsVersion), and
+ * a tab MOVING BETWEEN PANES (paneId — onOpenDiff closes over the pane id,
+ * and moveTab reuses the SAME tab object, so only the pane id identifies the
+ * move) must re-render the cell.
+ */
+import type { SidebarTab } from './state.ts'
+
+/** The fields whose change invalidates a tab cell's memo. Anything a cell's
+ *  render (or its callbacks) depends on must be listed here. */
+export interface TabContentMemoKey {
+  tab: SidebarTab
+  /** The pane this tab currently lives in. onOpenDiff closes over it, and
+   *  moveTab reuses the same tab object when the tab moves panes — without
+   *  comparing paneId the cell would keep the source pane's callback. */
+  paneId: string
+  sessionId: string
+  cwd: string | undefined
+  visible: boolean
+  expanded: string[]
+  /** Files highlighted in the file tree (the "Show in folder" reveal). */
+  revealed: string[]
+  localeRevision: string
+  tabsVersion: number
+  /** When the tab is a pinned virtual tab (injected from another session),
+   *  this overrides `tab.id` passed to the tab descriptor's component so
+   *  TerminalView connects to the home session's PTY by the original id.
+   *  Undefined for regular tabs (no override). */
+  effectiveTabId: string | undefined
+}
+
+/** True when the cell may skip a re-render (all render-affecting fields
+ *  unchanged). Callback/context identities are deliberately ignored: their
+ *  captured dependencies are stable or covered by the compared fields
+ *  (onReferenceFile → sessionId/cwd, onSubagentJump/onToggleDir → stable
+ *  refs/closures, onOpenDiff → paneId). */
+export function tabContentCompare(prev: TabContentMemoKey, next: TabContentMemoKey): boolean {
+  return (
+    prev.tab === next.tab &&
+    prev.paneId === next.paneId &&
+    prev.sessionId === next.sessionId &&
+    prev.cwd === next.cwd &&
+    prev.visible === next.visible &&
+    prev.expanded === next.expanded &&
+    prev.revealed === next.revealed &&
+    prev.localeRevision === next.localeRevision &&
+    prev.tabsVersion === next.tabsVersion &&
+    prev.effectiveTabId === next.effectiveTabId
+  )
+}

package/src/client/terminal-font.ts

@@ -0,0 +1,224 @@
+/**
+ * Terminal font resolution: the user's custom font prefs (SidebarPrefs,
+ * configured under the terminal card's secondary settings) turned into the
+ * xterm options. Kept as a pure module (no DOM, no xterm) so the fallback
+ * chain and clamping are unit-testable without mounting a terminal.
+ */
+import { clampTerminalFontSize, type SidebarPrefs } from '../prefs-shared.ts'
+
+/** The built-in fallback stack when neither the user nor the theme sets one. */
+export const DEFAULT_TERMINAL_FONT_FAMILY = '"SF Mono", Menlo, Consolas, "Liberation Mono", monospace'
+
+/**
+ * Icon fonts appended to whichever base stack wins, so shell prompts that
+ * draw glyphs from the Nerd Font Private Use Areas resolve to a real glyph
+ * instead of the missing-glyph box (aka tofu).
+ *
+ * Why this is needed even though the OS "should" fall back automatically:
+ * prompt frameworks (starship, powerlevel10k, oh-my-posh) take their icons
+ * from the PUA. Chromium's implicit system fallback reliably covers the
+ * *BMP* PUA (U+E000–U+F8FF — e.g. the U+E0B0 powerline separator) but NOT
+ * the *supplementary-plane* PUA-B (U+F0000+) where Nerd Fonts v3 relocated
+ * the Material Design icon set. Naming the families explicitly makes the
+ * browser consult them per character, which covers both planes.
+ *
+ * Deliberately NOT listed: color-emoji families. Chromium routes genuine
+ * emoji code points through a dedicated emoji fallback path (which is why
+ * emoji already render), so naming them buys nothing here — while placing a
+ * color font ahead of the generic family risks capturing BMP symbols the
+ * prompt expects in monospace (U+26A0 ⚠, U+2714 ✔ …) and rendering them as
+ * wide color glyphs that break the cell grid.
+ *
+ * Ordering rationale: the symbols-only patches ship glyphs without Latin,
+ * so they can never hijack ASCII metrics — the safest first hop. The
+ * fully-patched distributions follow for users who installed one of those
+ * instead. Both the `… Mono` and proportional family names are listed
+ * because the Nerd Fonts installers register them as distinct families.
+ *
+ * These are strictly *appended*, never prepended: xterm derives its cell
+ * metrics from the first entry, so the base font must stay in front or the
+ * whole grid would be re-measured against an icon font.
+ */
+export const ICON_FONT_FALLBACKS: readonly string[] = [
+  // Symbols-only patches (glyph coverage without Latin) — ideal fallbacks.
+  '"Symbols Nerd Font Mono"',
+  '"Symbols Nerd Font"',
+  // Common fully-patched Nerd Font distributions.
+  '"Hack Nerd Font Mono"',
+  '"Hack Nerd Font"',
+  '"JetBrainsMono Nerd Font Mono"',
+  '"JetBrainsMono Nerd Font"',
+  '"FiraCode Nerd Font Mono"',
+  '"FiraCode Nerd Font"',
+  '"CaskaydiaCove Nerd Font Mono"',
+  '"CaskaydiaCove Nerd Font"',
+  '"SauceCodePro Nerd Font Mono"',
+  '"UbuntuMono Nerd Font Mono"',
+  '"Iosevka Nerd Font Mono"',
+  '"MesloLGS Nerd Font Mono"',
+  '"MesloLGS NF"',
+]
+
+/** The symbols-only patch count at the head of {@link ICON_FONT_FALLBACKS}
+ *  (these carry no Latin glyphs, so they can never hijack ASCII metrics). */
+const SYMBOLS_ONLY_COUNT = 2
+
+/**
+ * CSS generic font families. A generic is a catch-all that always resolves,
+ * so icon fonts must be spliced in *before* the first one to stay reachable.
+ */
+const GENERIC_FAMILIES = new Set([
+  'monospace', 'serif', 'sans-serif', 'cursive', 'fantasy',
+  'system-ui', 'ui-monospace', 'ui-serif', 'ui-sans-serif', 'ui-rounded',
+  'math', 'emoji', 'fangsong',
+])
+
+/**
+ * CSS-wide keywords. These are only valid as an *entire* declaration value,
+ * so a stack cannot be appended to one.
+ */
+const CSS_WIDE_KEYWORDS = new Set(['inherit', 'initial', 'unset', 'revert', 'revert-layer'])
+
+/** Normalize one family name for comparison: unquote, collapse runs of
+ *  whitespace, casefold. */
+function normalizeFamily(family: string): string {
+  return family
+    .trim()
+    .replace(/^["']|["']$/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLowerCase()
+}
+
+/**
+ * Split a CSS font-family stack on its top-level commas.
+ *
+ * Naive `split(',')` would corrupt quoted family names containing a comma
+ * and function values such as `var(--x, monospace)`, so quotes (with
+ * backslash escapes) and parentheses are tracked.
+ *
+ * @param stack - a CSS font-family stack.
+ * @returns the trimmed, non-empty family entries in source order.
+ */
+function splitFamilies(stack: string): string[] {
+  const entries: string[] = []
+  let buffer = ''
+  let quote: string | null = null
+  let depth = 0
+  for (let i = 0; i < stack.length; i += 1) {
+    const char = stack[i] as string
+    if (quote !== null) {
+      // Escapes are copied verbatim so `\"` does not close the quote.
+      if (char === '\\' && i + 1 < stack.length) {
+        buffer += char + (stack[i + 1] as string)
+        i += 1
+        continue
+      }
+      buffer += char
+      if (char === quote) quote = null
+      continue
+    }
+    if (char === '"' || char === "'") {
+      quote = char
+      buffer += char
+      continue
+    }
+    if (char === '(') depth += 1
+    else if (char === ')') depth = Math.max(0, depth - 1)
+    else if (char === ',' && depth === 0) {
+      entries.push(buffer)
+      buffer = ''
+      continue
+    }
+    buffer += char
+  }
+  entries.push(buffer)
+  return entries.map(entry => entry.trim()).filter(entry => entry !== '')
+}
+
+/**
+ * Append {@link ICON_FONT_FALLBACKS} to a CSS font-family stack, keeping
+ * the caller's own entries and order intact.
+ *
+ * - Families already named in `stack` are not duplicated (quote-, case- and
+ *   whitespace-insensitive), so a user who already lists their Nerd Font
+ *   keeps their exact priority.
+ * - The icon fonts are spliced in ahead of the *first* generic family
+ *   (`monospace` etc.), because a generic always resolves: anything after it
+ *   would never be consulted. A stack that OPENS with a generic is the one
+ *   exception: only the symbols-only patches (no Latin) may precede it — a
+ *   fully-patched Nerd Font there would become xterm's measuring base font
+ *   and override the user/theme family precedence, so it is placed after the
+ *   generic instead.
+ * - Idempotent — re-applying to an already-topped-up stack is a no-op, which
+ *   matters because `TerminalView` diffs the resolved value against the live
+ *   `term.options.fontFamily` before reflowing.
+ *
+ * @param stack - a CSS font-family stack (base font first).
+ * @returns the stack with icon fallbacks merged in.
+ */
+export function withIconFontFallbacks(stack: string): string {
+  const entries = splitFamilies(stack)
+  if (entries.length === 0) return ICON_FONT_FALLBACKS.join(', ')
+
+  const present = new Set(entries.map(normalizeFamily))
+  const notPresent = (family: string): boolean => !present.has(normalizeFamily(family))
+  const symbolsOnly = ICON_FONT_FALLBACKS.slice(0, SYMBOLS_ONLY_COUNT).filter(notPresent)
+  const patched = ICON_FONT_FALLBACKS.slice(SYMBOLS_ONLY_COUNT).filter(notPresent)
+  if (symbolsOnly.length === 0 && patched.length === 0) return entries.join(', ')
+
+  const firstGeneric = entries.findIndex(entry => GENERIC_FAMILIES.has(normalizeFamily(entry)))
+  const cut = firstGeneric === -1 ? entries.length : firstGeneric
+  // A fully-patched distribution ships Latin glyphs: placed ahead of a
+  // LEADING generic (cut === 0) it would become xterm's measuring/base font
+  // and override the user/theme family precedence. Only the symbols-only
+  // patches — which carry no Latin — may precede it; the patched fonts go
+  // after the generic (still reachable per character, never the base).
+  if (cut === 0) {
+    return [...symbolsOnly, entries[0]!, ...patched, ...entries.slice(1)].join(', ')
+  }
+  return [...entries.slice(0, cut), ...symbolsOnly, ...patched, ...entries.slice(cut)].join(', ')
+}
+
+/**
+ * Reduce one link of the base-family chain to a usable stack, or `''` when
+ * it cannot carry appended fallbacks so the next link should win.
+ *
+ * Rejecting CSS-wide keywords matters because the theme font arrives as a
+ * raw token value (`tokenValue('--ds-font-family-code')`); skins do set
+ * tokens to `initial`/`inherit`/`unset` (see `effectiveTokenValue` in
+ * `theme.ts`, which guards the color tokens for the same reason). Appending
+ * to such a value yields an invalid `font-family`, which the CSSOM discards
+ * silently — the terminal would lose the theme font *and* the icon fonts.
+ */
+function usableBase(value: string | undefined): string {
+  const trimmed = (value ?? '').trim()
+  if (trimmed === '') return ''
+  if (CSS_WIDE_KEYWORDS.has(trimmed.toLowerCase())) return ''
+  return trimmed
+}
+
+/**
+ * Resolve the xterm font options for the given prefs.
+ *
+ * The base family keeps its existing precedence — user pref > theme code
+ * font > built-in stack — and then {@link withIconFontFallbacks} tops it up
+ * so prompt icons resolve regardless of which base won.
+ *
+ * @param prefs - the current side card preferences.
+ * @param themeFontFamily - the app's theme code font (`--ds-font-family-code`
+ *   token value, read live by the caller); undefined when the token is absent.
+ * @returns the `fontFamily` / `fontSize` xterm options.
+ */
+export function resolveTerminalFont(
+  prefs: SidebarPrefs,
+  themeFontFamily: string | undefined,
+): { fontFamily: string; fontSize: number } {
+  const base = usableBase(prefs.terminalFontFamily)
+    || usableBase(themeFontFamily)
+    || DEFAULT_TERMINAL_FONT_FAMILY
+  return {
+    fontFamily: withIconFontFallbacks(base),
+    fontSize: clampTerminalFontSize(prefs.terminalFontSize),
+  }
+}