@clawpump/claw-agent 0.1.4 → 0.1.6

package/agent/apps/desktop/src/app/right-sidebar/index.tsx

@@ -1,21 +1,24 @@
 import { useStore } from '@nanostores/react'
 import type { ReactNode } from 'react'
 
+import { ErrorBoundary } from '@/components/error-boundary'
 import { Button } from '@/components/ui/button'
 import { Codicon } from '@/components/ui/codicon'
 import { Loader } from '@/components/ui/loader'
+import { useI18n } from '@/i18n'
+import { selectDesktopPaths } from '@/lib/desktop-fs'
 import { normalizeOrLocalPreviewTarget } from '@/lib/local-preview'
 import { cn } from '@/lib/utils'
+import { $panesFlipped } from '@/store/layout'
 import { notifyError } from '@/store/notifications'
 import { setCurrentSessionPreviewTarget } from '@/store/preview'
-import { $currentBranch, $currentCwd } from '@/store/session'
+import { $currentCwd } from '@/store/session'
 
 import { SidebarPanelLabel } from '../shell/sidebar-label'
 
+import { RemoteFolderPicker } from './files/remote-picker'
 import { ProjectTree } from './files/tree'
 import { useProjectTree } from './files/use-project-tree'
-import { $rightSidebarTab, $terminalTakeover, type RightSidebarTabId, setRightSidebarTab } from './store'
-import { TerminalSlot } from './terminal/persistent'
 
 interface RightSidebarPaneProps {
   onActivateFile: (path: string) => void
@@ -23,44 +26,41 @@ interface RightSidebarPaneProps {
   onChangeCwd: (path: string) => Promise<void> | void
 }
 
-interface RightSidebarTab {
-  icon: string
-  id: RightSidebarTabId
-  label: string
-}
-
-const RIGHT_SIDEBAR_TABS: readonly RightSidebarTab[] = [
-  { id: 'files', label: 'File system', icon: 'files' },
-  { id: 'terminal', label: 'Terminal', icon: 'terminal' }
-]
-
-export function RightSidebarPane({
-  onActivateFile,
-  onActivateFolder,
-  onChangeCwd
-}: RightSidebarPaneProps) {
-  const activeTab = useStore($rightSidebarTab)
-  const terminalTakeover = useStore($terminalTakeover)
-  const currentBranch = useStore($currentBranch).trim()
+export function RightSidebarPane({ onActivateFile, onActivateFolder, onChangeCwd }: RightSidebarPaneProps) {
+  const { t } = useI18n()
+  const r = t.rightSidebar
+  const panesFlipped = useStore($panesFlipped)
   const currentCwd = useStore($currentCwd).trim()
   const hasCwd = currentCwd.length > 0
 
+  const {
+    collapseAll,
+    collapseNonce,
+    data,
+    effectiveCwd,
+    loadChildren,
+    openState,
+    refreshRoot,
+    rootError,
+    rootLoading,
+    setNodeOpen
+  } = useProjectTree(currentCwd)
+
   const cwdName = hasCwd
-    ? (currentCwd
+    ? (effectiveCwd
         .split(/[\\/]+/)
         .filter(Boolean)
-        .pop() ?? currentCwd)
-    : 'No folder selected'
+        .pop() ?? effectiveCwd)
+    : r.noFolderSelected
 
-  const { data, loadChildren, openState, refreshRoot, rootError, rootLoading, setNodeOpen } = useProjectTree(currentCwd)
-  const effectiveTab: RightSidebarTabId = terminalTakeover ? 'files' : activeTab
+  const canCollapse = Object.values(openState).some(Boolean)
 
   const chooseFolder = async () => {
-    const selected = await window.hermesDesktop?.selectPaths({
-      defaultPath: hasCwd ? currentCwd : undefined,
+    const selected = await selectDesktopPaths({
+      defaultPath: hasCwd ? effectiveCwd : undefined,
       directories: true,
       multiple: false,
-      title: 'Change working directory'
+      title: r.changeCwdTitle
     })
 
     if (selected?.[0]) {
@@ -70,103 +70,72 @@ export function RightSidebarPane({
 
   const previewFile = async (path: string) => {
     try {
-      const preview = await normalizeOrLocalPreviewTarget(path, currentCwd || undefined)
+      const preview = await normalizeOrLocalPreviewTarget(path, effectiveCwd || undefined)
 
       if (!preview) {
-        throw new Error(`Could not preview ${path}`)
+        throw new Error(r.couldNotPreview(path))
       }
 
       setCurrentSessionPreviewTarget(preview, 'file-browser', path)
     } catch (error) {
-      notifyError(error, 'Preview unavailable')
+      notifyError(error, r.previewUnavailable)
     }
   }
 
-  const tabs = terminalTakeover
-    ? RIGHT_SIDEBAR_TABS.filter(tab => tab.id !== 'terminal')
-    : RIGHT_SIDEBAR_TABS
-
   return (
     <aside
-      aria-label="Right sidebar"
-      className="before:pointer-events-none relative flex h-full w-full min-w-0 flex-col overflow-hidden border-l border-(--ui-stroke-secondary) bg-(--ui-sidebar-surface-background) pt-(--titlebar-height) text-(--ui-text-tertiary) shadow-[inset_0.0625rem_0_0_color-mix(in_srgb,white_18%,transparent)] before:absolute before:inset-x-0 before:top-(--titlebar-height) before:z-1 before:h-px before:bg-(--ui-stroke-tertiary)"
+      aria-label={r.aria}
+      className={cn(
+        'before:pointer-events-none relative flex h-full w-full min-w-0 flex-col overflow-hidden border-(--ui-stroke-secondary) bg-(--ui-sidebar-surface-background) pt-(--titlebar-height) text-(--ui-text-tertiary)',
+        panesFlipped
+          ? 'border-r shadow-[inset_-0.0625rem_0_0_color-mix(in_srgb,white_18%,transparent)]'
+          : 'border-l shadow-[inset_0.0625rem_0_0_color-mix(in_srgb,white_18%,transparent)]'
+      )}
     >
-      <RightSidebarChrome activeTab={effectiveTab} branch={currentBranch} tabs={tabs} />
+      <RemoteFolderPicker />
 
-      {effectiveTab === 'terminal' ? (
-        <TerminalSlot />
-      ) : (
-        <FilesystemTab
-          cwd={currentCwd}
-          cwdName={cwdName}
-          data={data}
-          error={rootError}
-          hasCwd={hasCwd}
-          loading={rootLoading}
-          onActivateFile={onActivateFile}
-          onActivateFolder={onActivateFolder}
-          onChangeFolder={chooseFolder}
-          onLoadChildren={loadChildren}
-          onNodeOpenChange={setNodeOpen}
-          onPreviewFile={previewFile}
-          onRefresh={() => void refreshRoot()}
-          openState={openState}
-        />
-      )}
+      <FilesystemTab
+        canCollapse={canCollapse}
+        collapseNonce={collapseNonce}
+        cwd={effectiveCwd}
+        cwdName={cwdName}
+        data={data}
+        error={rootError}
+        hasCwd={hasCwd}
+        loading={rootLoading}
+        onActivateFile={onActivateFile}
+        onActivateFolder={onActivateFolder}
+        onChangeFolder={chooseFolder}
+        onCollapseAll={collapseAll}
+        onLoadChildren={loadChildren}
+        onNodeOpenChange={setNodeOpen}
+        onPreviewFile={previewFile}
+        onRefresh={() => void refreshRoot()}
+        openState={openState}
+      />
     </aside>
   )
 }
 
-function RightSidebarChrome({
-  activeTab,
-  branch,
-  tabs
-}: {
-  activeTab: RightSidebarTabId
-  branch: string
-  tabs: readonly RightSidebarTab[]
-}) {
-  return (
-    <header className="shrink-0 bg-transparent text-[0.75rem]">
-      <div className="flex items-center gap-2 border-b border-(--ui-stroke-tertiary) px-2.5 py-1">
-        <nav aria-label="Right sidebar panels" className="flex min-w-0 items-center gap-1">
-          {tabs.map(tab => (
-            <button
-              aria-label={tab.label}
-              aria-pressed={tab.id === activeTab}
-              className={cn(
-                'grid size-6 shrink-0 place-items-center rounded-lg text-(--ui-text-tertiary) transition-colors hover:bg-(--ui-control-hover-background) hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-sidebar-ring active:bg-(--ui-control-active-background) active:text-foreground',
-                'data-[active=true]:bg-(--ui-control-active-background) data-[active=true]:text-foreground'
-              )}
-              data-active={tab.id === activeTab}
-              key={tab.id}
-              onClick={() => setRightSidebarTab(tab.id)}
-              title={tab.label}
-              type="button"
-            >
-              <Codicon name={tab.icon} size="0.875rem" />
-            </button>
-          ))}
-        </nav>
-        {branch && (
-          <span className="ml-auto flex min-w-0 items-center gap-1 text-[0.6875rem] text-(--ui-text-tertiary)">
-            <Codicon className="shrink-0" name="git-branch" size="0.75rem" />
-            <span className="truncate">{branch}</span>
-          </span>
-        )}
-      </div>
-    </header>
-  )
-}
-
 interface FilesystemTabProps extends FileTreeBodyProps {
+  canCollapse: boolean
   cwdName: string
   hasCwd: boolean
   onChangeFolder: () => Promise<void> | void
+  onCollapseAll: () => void
   onRefresh: () => void
 }
 
+// Sidebar palette + hover-reveal: header actions stay reachable while moving
+// from the project label to the action buttons.
+const HEADER_ACTION_CLASS =
+  'text-sidebar-foreground/70 hover:bg-sidebar-accent! hover:text-sidebar-accent-foreground! focus-visible:ring-sidebar-ring'
+
+const HEADER_ACTION_LABEL_REVEAL = `${HEADER_ACTION_CLASS} pointer-events-none opacity-0 transition-opacity focus-visible:pointer-events-auto focus-visible:opacity-100 group-focus-within/project-header:pointer-events-auto group-focus-within/project-header:opacity-100 group-hover/project-header:pointer-events-auto group-hover/project-header:opacity-100`
+
 function FilesystemTab({
+  canCollapse,
+  collapseNonce,
   cwd,
   cwdName,
   data,
@@ -176,36 +145,60 @@ function FilesystemTab({
   onActivateFile,
   onActivateFolder,
   onChangeFolder,
+  onCollapseAll,
   onLoadChildren,
   onNodeOpenChange,
   onPreviewFile,
   onRefresh,
   openState
 }: FilesystemTabProps) {
+  const { t } = useI18n()
+  const r = t.rightSidebar
+
   return (
-    <div className="group/project-header flex min-h-0 flex-1 flex-col">
+    <div className="flex min-h-0 flex-1 flex-col">
       <RightSidebarSectionHeader>
-        <button
-          className="flex min-w-0 flex-1 items-center rounded-md text-left hover:text-(--ui-text-secondary)"
-          onClick={() => void onChangeFolder()}
-          title={hasCwd ? cwd : 'No folder selected'}
-          type="button"
-        >
-          <SidebarPanelLabel>{cwdName}</SidebarPanelLabel>
-        </button>
+        <div className="flex min-w-0 flex-1">
+          <button
+            className="flex w-full min-w-0 items-center rounded-md text-left hover:text-(--ui-text-secondary)"
+            onClick={() => void onChangeFolder()}
+            type="button"
+          >
+            <SidebarPanelLabel>{cwdName}</SidebarPanelLabel>
+          </button>
+        </div>
         <Button
-          aria-label="Refresh tree"
-          className="pointer-events-none size-6 shrink-0 rounded-md text-sidebar-foreground/70 opacity-0 transition-opacity hover:bg-sidebar-accent! hover:text-sidebar-accent-foreground! focus-visible:opacity-100 focus-visible:ring-2 focus-visible:ring-sidebar-ring group-focus-within/project-header:pointer-events-auto group-focus-within/project-header:opacity-100 group-hover/project-header:pointer-events-auto group-hover/project-header:opacity-100"
+          aria-label={r.refreshTree}
+          className={HEADER_ACTION_LABEL_REVEAL}
           disabled={!hasCwd || loading}
           onClick={onRefresh}
-          size="icon"
-          title="Refresh tree"
+          size="icon-xs"
           variant="ghost"
         >
           <Codicon name="refresh" size="0.8125rem" spinning={loading} />
         </Button>
+        <Button
+          aria-label={r.openFolder}
+          className={HEADER_ACTION_CLASS}
+          onClick={() => void onChangeFolder()}
+          size="icon-xs"
+          variant="ghost"
+        >
+          <Codicon name="folder-opened" size="0.8125rem" />
+        </Button>
+        <Button
+          aria-label={r.collapseAll}
+          className={cn(HEADER_ACTION_CLASS, !canCollapse && 'pointer-events-none opacity-0')}
+          disabled={!hasCwd || !canCollapse}
+          onClick={onCollapseAll}
+          size="icon-xs"
+          variant="ghost"
+        >
+          <Codicon name="collapse-all" size="0.8125rem" />
+        </Button>
       </RightSidebarSectionHeader>
       <FileTreeBody
+        collapseNonce={collapseNonce}
         cwd={cwd}
         data={data}
         error={error}
@@ -215,6 +208,7 @@ function FilesystemTab({
         onLoadChildren={onLoadChildren}
         onNodeOpenChange={onNodeOpenChange}
         onPreviewFile={onPreviewFile}
+        onRetry={onRefresh}
         openState={openState}
       />
     </div>
@@ -222,10 +216,11 @@ function FilesystemTab({
 }
 
 export function RightSidebarSectionHeader({ children }: { children: ReactNode }) {
-  return <div className="flex h-7 shrink-0 items-center px-2">{children}</div>
+  return <div className="group/project-header flex h-7 shrink-0 items-center px-2.5">{children}</div>
 }
 
 interface FileTreeBodyProps {
+  collapseNonce: number
   cwd: string
   data: ReturnType<typeof useProjectTree>['data']
   error: string | null
@@ -235,10 +230,14 @@ interface FileTreeBodyProps {
   onLoadChildren: (id: string) => void | Promise<void>
   onNodeOpenChange: (id: string, open: boolean) => void
   onPreviewFile?: (path: string) => void
+  /** Force-reload the root. The hook also auto-retries while errored, so this
+   *  is the impatient-user path. */
+  onRetry?: () => void
   openState: ReturnType<typeof useProjectTree>['openState']
 }
 
 function FileTreeBody({
+  collapseNonce,
   cwd,
   data,
   error,
@@ -248,14 +247,31 @@ function FileTreeBody({
   onLoadChildren,
   onNodeOpenChange,
   onPreviewFile,
+  onRetry,
   openState
 }: FileTreeBodyProps) {
+  const { t } = useI18n()
+  const r = t.rightSidebar
+
   if (!cwd) {
-    return <EmptyState body="Set a working directory from the status bar to browse files." title="No project" />
+    return <EmptyState body={r.noProjectBody} title={r.noProjectTitle} />
   }
 
   if (error) {
-    return <EmptyState body={`Could not read this folder (${error}).`} title="Unreadable" />
+    return (
+      <div className="flex min-h-0 flex-1 flex-col items-center justify-center gap-2 px-4 text-center">
+        <EmptyState body={r.unreadableBody(error)} title={r.unreadableTitle} />
+        {onRetry && (
+          <button
+            className="text-[0.68rem] font-medium text-muted-foreground transition hover:text-foreground"
+            onClick={onRetry}
+            type="button"
+          >
+            {r.tryAgain}
+          </button>
+        )}
+      </div>
+    )
   }
 
   if (loading && data.length === 0) {
@@ -263,25 +279,46 @@ function FileTreeBody({
   }
 
   if (data.length === 0) {
-    return <EmptyState body="This folder is empty." title="Empty" />
+    return <EmptyState body={r.emptyBody} title={r.emptyTitle} />
   }
 
   return (
-    <ProjectTree
-      data={data}
-      onActivateFile={onActivateFile}
-      onActivateFolder={onActivateFolder}
-      onLoadChildren={onLoadChildren}
-      onNodeOpenChange={onNodeOpenChange}
-      onPreviewFile={onPreviewFile}
-      openState={openState}
-    />
+    <ErrorBoundary
+      fallback={({ reset }) => (
+        <div className="flex min-h-0 flex-1 flex-col items-center justify-center gap-2 px-4 text-center">
+          <EmptyState body={r.treeErrorBody} title={r.treeErrorTitle} />
+          <button
+            className="text-[0.68rem] font-medium text-muted-foreground transition hover:text-foreground"
+            onClick={reset}
+            type="button"
+          >
+            {r.tryAgain}
+          </button>
+        </div>
+      )}
+      key={cwd}
+      label="file-tree"
+    >
+      <ProjectTree
+        collapseNonce={collapseNonce}
+        cwd={cwd}
+        data={data}
+        onActivateFile={onActivateFile}
+        onActivateFolder={onActivateFolder}
+        onLoadChildren={onLoadChildren}
+        onNodeOpenChange={onNodeOpenChange}
+        onPreviewFile={onPreviewFile}
+        openState={openState}
+      />
+    </ErrorBoundary>
   )
 }
 
 function FileTreeLoadingState() {
+  const { t } = useI18n()
+
   return (
-    <div aria-label="Loading file tree" className="grid min-h-0 flex-1 place-items-center px-3" role="status">
+    <div aria-label={t.rightSidebar.loadingTree} className="grid min-h-0 flex-1 place-items-center px-3" role="status">
       <Loader
         aria-hidden="true"
         className="size-8 text-(--ui-text-tertiary)"

package/agent/apps/desktop/src/app/right-sidebar/store.ts

@@ -2,14 +2,29 @@ import { atom } from 'nanostores'
 
 import { persistBoolean, storedBoolean } from '@/lib/storage'
 
-export type RightSidebarTabId = 'files' | 'git' | 'terminal' | 'web'
-
 const TAKEOVER_KEY = 'hermes.desktop.terminalTakeover'
 
-export const $rightSidebarTab = atom<RightSidebarTabId>('files')
 export const $terminalTakeover = atom(storedBoolean(TAKEOVER_KEY, false))
 
 $terminalTakeover.subscribe(active => persistBoolean(TAKEOVER_KEY, active))
 
-export const setRightSidebarTab = (tab: RightSidebarTabId) => $rightSidebarTab.set(tab)
 export const setTerminalTakeover = (active: boolean) => $terminalTakeover.set(active)
+
+/** A command queued to run in the embedded terminal. The terminal pane flushes
+ *  (and clears) it once its session is live, so a value set before the pane
+ *  mounts still runs. Cleared after flush so a later remount can't replay it. */
+export const $terminalInjection = atom<null | string>(null)
+
+/** Open the terminal pane and run a command in it. Used to disconnect external
+ *  (CLI-managed) providers, which Hermes can't clear via the API — the user
+ *  sees exactly what runs instead of Hermes silently deleting their creds. */
+export const runInTerminal = (command: string) => {
+  const trimmed = command.trim()
+
+  if (!trimmed) {
+    return
+  }
+
+  setTerminalTakeover(true)
+  $terminalInjection.set(trimmed)
+}

package/agent/apps/desktop/src/app/right-sidebar/terminal/buffer.ts

@@ -0,0 +1,65 @@
+import type { Terminal } from '@xterm/xterm'
+
+// Serialized view of the in-app terminal, handed to the agent's `read_terminal`
+// tool. Line indices are absolute into xterm's buffer (0 = oldest scrollback
+// line), so the agent can page with start_line/count against `total_lines`.
+export interface TerminalReadResult {
+  total_lines: number
+  start: number
+  end: number
+  viewport_rows: number
+  cursor_row: number
+  text: string
+}
+
+export interface TerminalReadOptions {
+  start?: number
+  count?: number
+}
+
+type Reader = (opts: TerminalReadOptions) => TerminalReadResult
+
+// The persistent terminal is a singleton (one xterm mounted forever), so a
+// module-level slot is enough — set while the session is live, cleared on
+// dispose. The gateway `terminal.read.request` handler reads through this.
+let activeReader: Reader | null = null
+
+export function setActiveTerminalReader(reader: Reader | null): void {
+  activeReader = reader
+}
+
+export function readActiveTerminal(opts: TerminalReadOptions = {}): TerminalReadResult | null {
+  return activeReader ? activeReader(opts) : null
+}
+
+export function makeTerminalReader(term: Terminal): Reader {
+  return ({ start, count }) => {
+    const buf = term.buffer.active
+    const total = buf.length
+    const rows = term.rows
+    // Default window = the visible screen; baseY is the viewport's top row.
+    const from = Math.max(0, Math.min(start ?? buf.baseY, total))
+    const to = Math.max(from, Math.min(from + Math.max(1, count ?? rows), total))
+
+    const lines: string[] = []
+
+    // translateToString(true) right-trims and resolves wide chars, dropping SGR
+    // colors — exactly what the agent wants.
+    for (let i = from; i < to; i += 1) {
+      lines.push(buf.getLine(i)?.translateToString(true) ?? '')
+    }
+
+    while (lines.length && !lines[lines.length - 1].trim()) {
+      lines.pop()
+    }
+
+    return {
+      total_lines: total,
+      start: from,
+      end: to,
+      viewport_rows: rows,
+      cursor_row: buf.baseY + buf.cursorY,
+      text: lines.join('\n')
+    }
+  }
+}

package/agent/apps/desktop/src/app/right-sidebar/terminal/index.tsx

@@ -1,15 +1,15 @@
 import '@xterm/xterm/css/xterm.css'
 
-import { useStore } from '@nanostores/react'
-
 import { Button } from '@/components/ui/button'
 import { Codicon } from '@/components/ui/codicon'
 import { Loader } from '@/components/ui/loader'
+import { Tip } from '@/components/ui/tooltip'
+import { useI18n } from '@/i18n'
 
 import { SidebarPanelLabel } from '../../shell/sidebar-label'
-import { $terminalTakeover, setRightSidebarTab, setTerminalTakeover } from '../store'
+import { setTerminalTakeover } from '../store'
 
-import { addSelectionShortcutLabel } from './selection'
+import { KbdCombo } from '@/components/ui/kbd'
 import { useTerminalSession } from './use-terminal-session'
 
 interface TerminalTabProps {
@@ -18,39 +18,33 @@ interface TerminalTabProps {
 }
 
 export function TerminalTab({ cwd, onAddSelectionToChat }: TerminalTabProps) {
+  const { t } = useI18n()
+
   const { addSelectionToChat, hostRef, selection, selectionStyle, shellName, status } = useTerminalSession({
     cwd,
     onAddSelectionToChat
   })
 
-  const takeover = useStore($terminalTakeover)
-  const label = takeover ? 'Return to split view' : 'Focus terminal view'
-
-  const toggleTakeover = () => {
-    // Pre-select the Terminal tab so the slot is ready to host us on return.
-    if (takeover) {
-      setRightSidebarTab('terminal')
-    }
-    setTerminalTakeover(!takeover)
-  }
+  const label = t.rightSidebar.terminalHide
 
   return (
     <div className="relative flex min-h-0 min-w-0 flex-1 flex-col">
       <div className="flex h-8 shrink-0 items-center gap-2 px-2.5">
-        <SidebarPanelLabel className="text-white!">{shellName}</SidebarPanelLabel>
-        <Button
-          aria-label={label}
-          className="ml-auto size-6 rounded-md text-white!"
-          onClick={toggleTakeover}
-          size="icon"
-          title={label}
-          type="button"
-          variant="ghost"
-        >
-          <Codicon name={takeover ? 'screen-normal' : 'screen-full'} size="0.875rem" />
-        </Button>
+        <SidebarPanelLabel className="text-(--ui-text-secondary)!">{shellName}</SidebarPanelLabel>
+        <Tip label={label}>
+          <Button
+            aria-label={label}
+            className="ml-auto size-6 rounded-md text-(--ui-text-secondary)!"
+            onClick={() => setTerminalTakeover(false)}
+            size="icon"
+            type="button"
+            variant="ghost"
+          >
+            <Codicon name="close" size="0.875rem" />
+          </Button>
+        </Tip>
       </div>
-      <div className="relative min-h-0 flex-1 bg-[#002b36] p-2">
+      <div className="relative min-h-0 flex-1 bg-(--ui-editor-surface-background) p-2">
         {status === 'starting' && (
           <div className="pointer-events-none absolute inset-0 z-10 grid place-items-center">
             <Loader
@@ -74,17 +68,18 @@ export function TerminalTab({ cwd, onAddSelectionToChat }: TerminalTabProps) {
               type="button"
               variant="secondary"
             >
-              Add to chat
-              <span className="ml-1 text-[0.6rem] text-(--ui-text-tertiary)">{addSelectionShortcutLabel()}</span>
+              {t.rightSidebar.addToChat}
+              <KbdCombo className="ml-1 opacity-70" combo="mod+l" size="sm" />
             </Button>
           </div>
         )}
-        {/* Outer div paints the dark inset; inner div is the xterm host so the
-            canvas sizes to the *content* area and p-2 shows as terminal padding.
-            Forcing screen/viewport bg avoids xterm's default black peeking
-            through the unused pixels below the last full row. */}
+        {/* Outer div paints terminal inset; inner div is the xterm host so the
+            canvas sizes to the content area and p-2 stays as terminal padding.
+            Screen/viewport inherit the live skin surface so the terminal blends
+            with the app and follows light/dark; the xterm canvas itself is
+            painted the resolved surface color in use-terminal-session. */}
         <div
-          className="h-full min-h-0 overflow-hidden text-(--ui-text-secondary) [&_.xterm]:h-full [&_.xterm-screen]:bg-[#002b36]! [&_.xterm-viewport]:bg-[#002b36]!"
+          className="h-full min-h-0 overflow-hidden text-(--ui-text-secondary) [&_.xterm]:h-full [&_.xterm-screen]:bg-(--ui-editor-surface-background)! [&_.xterm-viewport]:bg-(--ui-editor-surface-background)!"
           ref={hostRef}
         />
       </div>