@brimveyn/aimux 1.21.0 → 1.22.2

package/src/session-backend/remote-session-backend.ts

@@ -1,8 +1,8 @@
 import { EventEmitter } from 'node:events'
 import { connect, type Socket } from 'node:net'
 
-import type { AssistantId, WorkspaceSnapshotV1 } from '../state/types'
-import type { ResizeOptions, SessionBackend, SessionBackendEvents } from './types'
+import type { AssistantId, ProjectSnapshotV1 } from '../state/types'
+import type { ProjectBackendEvents, ResizeOptions, SessionBackend } from './types'
 
 import { getIpcDaemonSocketPath } from '../daemon/runtime-paths'
 import { logDebug } from '../debug/input-log'
@@ -24,7 +24,7 @@ const IPC_REQUEST_TIMEOUT_MS = 10_000
 const RECONNECT_DELAY_MS = 250
 
 export class RemoteSessionBackend
-  extends EventEmitter<SessionBackendEvents>
+  extends EventEmitter<ProjectBackendEvents>
   implements SessionBackend
 {
   private socket: Socket | null = null
@@ -38,12 +38,12 @@ export class RemoteSessionBackend
   >()
   private decoder = new MessageDecoder<ServerResponse | ServerEvent>(parseServerMessage)
   private attached = false
-  private currentSessionId: string | null = null
+  private currentProjectId: string | null = null
   private attachOptions: {
-    sessionId: string
+    projectId: string
     cols: number
     rows: number
-    workspaceSnapshot?: WorkspaceSnapshotV1
+    projectSnapshot?: ProjectSnapshotV1
   } | null = null
   private selectedProtocolVersion: number | null = null
   private daemonCapabilities: ReadonlySet<string> = new Set()
@@ -68,7 +68,7 @@ export class RemoteSessionBackend
     }
   }
 
-  private closeSocket(reason: string, preserveSession = false): void {
+  private closeSocket(reason: string, preserveProject = false): void {
     const socket = this.socket
     this.socket = null
     this.attached = false
@@ -77,8 +77,8 @@ export class RemoteSessionBackend
     this.decoder.reset()
     this.rejectPendingRequests(new Error(reason))
 
-    if (!preserveSession) {
-      this.currentSessionId = null
+    if (!preserveProject) {
+      this.currentProjectId = null
       this.attachOptions = null
     }
 
@@ -94,7 +94,7 @@ export class RemoteSessionBackend
   }
 
   private handleConnectionLoss(reason: string): void {
-    logDebug('backend.remote.connectionLoss', { reason, sessionId: this.currentSessionId })
+    logDebug('backend.remote.connectionLoss', { projectId: this.currentProjectId, reason })
     this.closeSocket(reason, true)
     if (this.shouldReconnect && this.attachOptions) {
       void this.scheduleReconnect()
@@ -187,59 +187,71 @@ export class RemoteSessionBackend
         break
       case 'tabStatus':
         logDebug('backend.remote.tabStatus', {
-          sessionId: message.payload.sessionId,
+          projectId: message.payload.projectId,
           status: message.payload.status,
           tabId: message.payload.tabId,
         })
-        this.emit('tabActivity', message.payload.tabId, message.payload.status)
+        this.emit(
+          'tabActivity',
+          message.payload.tabId,
+          message.payload.status,
+          message.payload.workspaceId
+        )
         break
       case 'tabTurnComplete':
+        this.emit(
+          'tabTurnComplete',
+          message.payload.tabId,
+          message.payload.projectId,
+          message.payload.workspaceId
+        )
+        break
       case 'tabQuestion':
-        // v13 orchestration signals — consumed by the headless CLI, not the UI
-        // backend. Enumerated so the switch stays exhaustive; no UI wiring yet.
+        // v13 orchestration signal — consumed by the headless CLI, not the UI
+        // backend. Enumerated so the switch stays exhaustive.
         break
-      case 'sessionStatus':
-        logDebug('backend.remote.sessionStatus', {
-          sessionId: message.payload.sessionId,
+      case 'projectStatus':
+        logDebug('backend.remote.projectStatus', {
+          projectId: message.payload.projectId,
           status: message.payload.status,
         })
-        this.emit('sessionActivity', message.payload.sessionId, message.payload.status)
+        this.emit('projectActivity', message.payload.projectId, message.payload.status)
         break
       case 'tabAdded':
         logDebug('backend.remote.tabAdded', {
-          sessionId: message.payload.sessionId,
+          projectId: message.payload.projectId,
           tabId: message.payload.tab.id,
         })
-        this.emit('tabAdded', message.payload.sessionId, message.payload.tab)
+        this.emit('tabAdded', message.payload.projectId, message.payload.tab)
         break
       case 'tabMetadataUpdated':
-        this.emit('tabMetadataUpdated', message.payload.sessionId, message.payload.tabId, {
+        this.emit('tabMetadataUpdated', message.payload.projectId, message.payload.tabId, {
           autoRenameStatus: message.payload.autoRenameStatus,
           title: message.payload.title,
         })
         break
-      case 'workspaceCreateRequested':
+      case 'projectCreateRequested':
         this.emit(
-          'workspaceCreateRequested',
+          'projectCreateRequested',
           message.payload.name,
           message.payload.projectPath,
           message.payload.switch === true
         )
         break
-      case 'workspaceSwitchRequested':
-        this.emit('workspaceSwitchRequested', message.payload.targetSessionId)
+      case 'projectSwitchRequested':
+        this.emit('projectSwitchRequested', message.payload.targetProjectId)
         break
-      case 'workspaceCloseRequested':
-        this.emit('workspaceCloseRequested', message.payload.targetSessionId)
+      case 'projectCloseRequested':
+        this.emit('projectCloseRequested', message.payload.targetProjectId)
         break
-      case 'workspaceSwitched':
-        this.emit('workspaceSwitched', message.payload.sessionId)
+      case 'projectSwitched':
+        this.emit('projectSwitched', message.payload.projectId)
         break
-      case 'worktreeAdded':
-        this.emit('worktreeAdded', message.payload.sessionId, message.payload.worktree)
+      case 'workspaceAdded':
+        this.emit('workspaceAdded', message.payload.projectId, message.payload.workspace)
         break
-      case 'worktreeRemoved':
-        this.emit('worktreeRemoved', message.payload.sessionId, message.payload.worktreeId)
+      case 'workspaceRemoved':
+        this.emit('workspaceRemoved', message.payload.projectId, message.payload.workspaceId)
         break
     }
   }
@@ -314,10 +326,10 @@ export class RemoteSessionBackend
   }
 
   private async performAttach(options: {
-    sessionId: string
+    projectId: string
     cols: number
     rows: number
-    workspaceSnapshot?: WorkspaceSnapshotV1
+    projectSnapshot?: ProjectSnapshotV1
   }): Promise<AttachResult> {
     await this.connectAndHandshake()
 
@@ -360,13 +372,13 @@ export class RemoteSessionBackend
         try {
           await this.performAttach(reconnectOptions)
           logDebug('backend.remote.reconnect.success', {
-            sessionId: reconnectOptions.sessionId,
+            projectId: reconnectOptions.projectId,
           })
           return
         } catch (error) {
           logDebug('backend.remote.reconnect.retry', {
             error: error instanceof Error ? error.message : String(error),
-            sessionId: reconnectOptions.sessionId,
+            projectId: reconnectOptions.projectId,
           })
           await Bun.sleep(RECONNECT_DELAY_MS)
         }
@@ -381,27 +393,27 @@ export class RemoteSessionBackend
   }
 
   async attach(options: {
-    sessionId: string
+    projectId: string
     cols: number
     rows: number
-    workspaceSnapshot?: WorkspaceSnapshotV1
+    projectSnapshot?: ProjectSnapshotV1
   }): Promise<AttachResult> {
     this.shouldReconnect = true
-    this.currentSessionId = options.sessionId
+    this.currentProjectId = options.projectId
     this.attachOptions = options
 
     logDebug('backend.remote.attach.start', {
       cols: options.cols,
+      projectId: options.projectId,
       rows: options.rows,
-      sessionId: options.sessionId,
-      snapshotTabs: options.workspaceSnapshot?.tabs.length ?? 0,
+      snapshotTabs: options.projectSnapshot?.tabs.length ?? 0,
       socketPath: getIpcDaemonSocketPath(),
     })
 
     const result = await this.performAttach(options)
     logDebug('backend.remote.attach.success', {
       activeTabId: result.activeTabId,
-      sessionId: options.sessionId,
+      projectId: options.projectId,
       tabs: result.tabs.length,
     })
 
@@ -417,7 +429,7 @@ export class RemoteSessionBackend
     cols: number
     rows: number
     cwd?: string
-    worktreeId?: string
+    workspaceId?: string
     autoRenameCandidate?: boolean
   }): void {
     if (!this.attached) {
@@ -490,7 +502,7 @@ export class RemoteSessionBackend
       logDebug('backend.remote.skipResizeBeforeAttach', { cols, rows })
       return
     }
-    logDebug('backend.remote.resize', { cols, rows, sessionId: this.currentSessionId })
+    logDebug('backend.remote.resize', { cols, projectId: this.currentProjectId, rows })
     this.dispatchCommand(
       { id: crypto.randomUUID(), payload: { cols, rows }, type: 'resizeClient' },
       'resizeClient'
@@ -533,17 +545,17 @@ export class RemoteSessionBackend
     this.dispatchCommand({ id: crypto.randomUUID(), payload: {}, type: 'disposeAll' }, 'disposeAll')
   }
 
-  announceWorkspaceSwitched(sessionId: string): void {
-    // Fire-and-forget so `handleSwitchSessionEffect` doesn't block waiting on
-    // the daemon roundtrip. The daemon relays this as a `workspaceSwitched`
-    // broadcast that unblocks any `aimux workspace switch --wait` CLI.
+  announceProjectSwitched(projectId: string): void {
+    // Fire-and-forget so `handleSwitchProjectEffect` doesn't block waiting on
+    // the daemon roundtrip. The daemon relays this as a `projectSwitched`
+    // broadcast that unblocks any `aimux project switch --wait` CLI.
     this.dispatchCommand(
       {
         id: crypto.randomUUID(),
-        payload: { sessionId },
-        type: 'announceWorkspaceSwitched',
+        payload: { projectId },
+        type: 'announceProjectSwitched',
       },
-      'announceWorkspaceSwitched'
+      'announceProjectSwitched'
     )
   }
 

package/src/session-backend/types.ts

@@ -1,60 +1,71 @@
 import type { EventEmitter } from 'node:events'
 
 import type {
-  SessionStatus,
+  ProjectSnapshotV1,
+  ProjectStatus,
   TabActivity,
   TabSession,
   TerminalModeState,
   TerminalSnapshot,
-  WorkspaceSnapshotV1,
-  WorktreeRecord,
+  WorkspaceRecord,
 } from '../state/types'
 
-export interface SessionBackendEvents {
+export interface ProjectBackendEvents {
   render: [tabId: string, viewport: TerminalSnapshot, terminalModes: TerminalModeState]
   exit: [tabId: string, exitCode: number]
   error: [tabId: string, message: string]
-  sessionActivity: [sessionId: string, status: SessionStatus]
-  tabActivity: [tabId: string, activity: TabActivity]
+  projectActivity: [projectId: string, status: ProjectStatus]
+  /**
+   * `workspaceId` is present when the backend knows which workspace the tab
+   * belongs to. The UI holds tabs for the attached project only, so this is
+   * what lets a *foreign* project's workspace row show a status glyph.
+   */
+  tabActivity: [tabId: string, activity: TabActivity, workspaceId?: string]
+  /**
+   * A tab's turn ended: its `idle` held for the daemon's settle window. Edge
+   * triggered, once per turn — the honest "the agent has finished" signal,
+   * unlike a raw `idle` which flickers between tool calls.
+   */
+  tabTurnComplete: [tabId: string, projectId: string, workspaceId?: string]
   /**
    * Fired when a tab was added by a sibling client (e.g. the CLI control
-   * plane creating a tab in the same session). The UI subscribes and
+   * plane creating a tab in the same project). The UI subscribes and
    * dispatches `add-tab` so its store learns about the new tab before any
    * `tabRender` event lands.
    */
-  tabAdded: [sessionId: string, tab: TabSession]
+  tabAdded: [projectId: string, tab: TabSession]
   tabMetadataUpdated: [
-    sessionId: string,
+    projectId: string,
     tabId: string,
     patch: { title?: string; autoRenameStatus?: 'eligible' | 'attempted' },
   ]
   /**
-   * v12 workspace-lifecycle events. Fired when a CLI issued
-   * `createWorkspace` / `switchWorkspace` / `closeWorkspace` and the daemon
+   * v12 project-lifecycle events. Fired when a CLI issued
+   * `createProject` / `switchProject` / `closeProject` and the daemon
    * relays as an event because a UI is attached. The UI reducer owns the
    * catalog write; see `backend-runtime-events.ts` for the wiring.
    */
-  workspaceCreateRequested: [name: string, projectPath: string | undefined, doSwitch: boolean]
-  workspaceSwitchRequested: [targetSessionId: string]
-  workspaceCloseRequested: [targetSessionId: string]
-  workspaceSwitched: [sessionId: string]
+  projectCreateRequested: [name: string, projectPath: string | undefined, doSwitch: boolean]
+  projectSwitchRequested: [targetProjectId: string]
+  projectCloseRequested: [targetProjectId: string]
+  projectSwitched: [projectId: string]
   /**
-   * v12 worktree-lifecycle events. Fired when a CLI issued
-   * `addWorktreeRecord` / `removeWorktreeRecord` and the daemon relays.
+   * v12 workspace-lifecycle events. Fired when a CLI issued
+   * `addWorkspaceRecord` / `removeWorkspaceRecord` and the daemon relays.
    */
-  worktreeAdded: [sessionId: string, worktree: WorktreeRecord]
-  worktreeRemoved: [sessionId: string, worktreeId: string]
+  workspaceAdded: [projectId: string, workspace: WorkspaceRecord]
+  workspaceRemoved: [projectId: string, workspaceId: string]
 }
 
 export interface ResizeOptions {
   /** When set, opentui's flush is invoked synchronously so the resize lands
    *  in the same commit. Used by the chrome cascade to keep the cols/rows
-   *  state and the backend buffer in lockstep on sidebar/session-bar toggles. */
+   *  state and the backend buffer in lockstep on sidebar/project-bar toggles. */
   sync?: boolean
   /** When true, this resize is the closed-loop measurement of the rendered
    *  content box — the authoritative size for the visible viewport. The
    *  `LocalSessionBackend` uses this to lift the per-tab snapshot gate that
-   *  suppresses renders between session/attach time and the first measurement,
+   *  suppresses renders between project/attach time and the first measurement,
    *  so the frontend never paints a snapshot whose row count disagrees with
    *  the pane's actual height. */
   confirmedFromMeasurement?: boolean
@@ -64,19 +75,19 @@ export interface BackendAttachResult {
   tabs: TabSession[]
   activeTabId: string | null
   /**
-   * Per-session status snapshot taken at attach time and applied
+   * Per-project status snapshot taken at attach time and applied
    * atomically with tab hydration to prevent an unknown-tab race on
-   * separate `sessionActivity` events.
+   * separate `projectActivity` events.
    */
-  initialSessionStatuses: { sessionId: string; status: SessionStatus }[]
+  initialProjectStatuses: { projectId: string; status: ProjectStatus }[]
 }
 
-export interface SessionBackend extends EventEmitter<SessionBackendEvents> {
+export interface SessionBackend extends EventEmitter<ProjectBackendEvents> {
   attach(options: {
-    sessionId: string
+    projectId: string
     cols: number
     rows: number
-    workspaceSnapshot?: WorkspaceSnapshotV1
+    projectSnapshot?: ProjectSnapshotV1
   }): Promise<BackendAttachResult | null>
   createSession(options: {
     tabId: string
@@ -87,10 +98,10 @@ export interface SessionBackend extends EventEmitter<SessionBackendEvents> {
     cols: number
     rows: number
     cwd?: string
-    /** Worktree the tab belongs to. Passed through to the daemon so its
+    /** Workspace the tab belongs to. Passed through to the daemon so its
      *  registry surfaces the right grouping in `listTabs` for headless
      *  consumers (CLI control plane). */
-    worktreeId?: string
+    workspaceId?: string
     autoRenameCandidate?: boolean
   }): void
   write(tabId: string, input: string): void
@@ -104,9 +115,9 @@ export interface SessionBackend extends EventEmitter<SessionBackendEvents> {
   disposeAll(): void
   destroy(keepSessions?: boolean): Promise<void> | void
   /**
-   * v12 — the UI calls this after `handleSwitchSessionEffect` finishes so the
-   * daemon can broadcast `workspaceSwitched` and any `aimux workspace switch
+   * v12 — the UI calls this after `handleSwitchProjectEffect` finishes so the
+   * daemon can broadcast `projectSwitched` and any `aimux project switch
    * --wait` CLI can exit. No-op on local backends (no daemon).
    */
-  announceWorkspaceSwitched(sessionId: string): void
+  announceProjectSwitched(projectId: string): void
 }

package/src/settings/live.ts

@@ -0,0 +1,90 @@
+import type { AIUsageToolConfig, AutoCommitConfig } from '@brimveyn/aimux-config'
+
+import { useMemo } from 'react'
+
+import { AUTO_COMMIT_ENABLED, AUTO_COMMIT_TIMEOUT } from './sections/automation'
+import { AUTO_COMMIT_MODEL_PREFIX, SNIPPET_TRIGGER_CHAR } from './sections/commands'
+import { ACTIVITY_SPRITES, HARMONIZE_CLAUDE_THEME } from './sections/experimental'
+import { AI_USAGE_ENABLED, AI_USAGE_POLL_SECONDS } from './sections/status-bar'
+import { useSettingsStore } from './settings-store'
+
+/**
+ * The read side of the settings screen: where a consumer used to take a value
+ * straight off the resolved config, it takes it from here instead, and the change
+ * lands without a restart.
+ *
+ * One hook per consumer, all in this file, so the row ids are read in exactly one
+ * place — and the ids themselves come from the section that defines them.
+ */
+export function useAutoCommitConfig(fromConfigFile: AutoCommitConfig): AutoCommitConfig {
+  const values = useSettingsStore((s) => s.values)
+  const timeoutMs = values[AUTO_COMMIT_TIMEOUT]
+  const models = { ...fromConfigFile.models }
+  for (const [id, value] of Object.entries(values)) {
+    if (!id.startsWith(AUTO_COMMIT_MODEL_PREFIX)) continue
+    // An empty row means "leave the default alone", not "use no model".
+    if (typeof value === 'string' && value !== '') {
+      models[id.slice(AUTO_COMMIT_MODEL_PREFIX.length)] = value
+    }
+  }
+  return {
+    enabled: values[AUTO_COMMIT_ENABLED] === true,
+    models,
+    timeoutMs: typeof timeoutMs === 'number' ? timeoutMs : fromConfigFile.timeoutMs,
+  }
+}
+
+/**
+ * The character that opens an inline snippet trigger. Clamped to one character,
+ * the same rule the config resolver applies — a two-character value would simply
+ * never match.
+ */
+export function useSnippetTriggerChar(fromConfigFile: string): string {
+  const stored = useSettingsStore((s) => s.values[SNIPPET_TRIGGER_CHAR])
+  if (typeof stored === 'string' && stored.length === 1) return stored
+  return fromConfigFile
+}
+
+/**
+ * Memoized on purpose: its consumer restarts the polling service whenever this
+ * object changes, so a fresh identity per render would restart it per render.
+ */
+export function useAIUsageConfig(fromConfigFile: AIUsageToolConfig | undefined): AIUsageToolConfig {
+  const values = useSettingsStore((s) => s.values)
+  const enabled = values[AI_USAGE_ENABLED] === true
+  const poll = values[AI_USAGE_POLL_SECONDS]
+  const pollSeconds = typeof poll === 'number' ? poll : fromConfigFile?.pollSeconds
+  return useMemo(
+    () => ({ ...fromConfigFile, enabled, pollSeconds }),
+    [enabled, fromConfigFile, pollSeconds]
+  )
+}
+
+/**
+ * The model that would write the commit message for this assistant, or undefined
+ * when nothing overrides the built-in default. The generating overlay names it, so
+ * an override set on the settings screen is visible where it applies.
+ */
+export function useAutoCommitModel(assistant: string | undefined): string | undefined {
+  const stored = useSettingsStore((s) =>
+    assistant == null || assistant === ''
+      ? undefined
+      : s.values[`${AUTO_COMMIT_MODEL_PREFIX}${assistant}`]
+  )
+  return typeof stored === 'string' && stored !== '' ? stored : undefined
+}
+
+/**
+ * Whether agent state is drawn as a sprite. Read straight off the store rather
+ * than through the resolved config: hydration already folds in whatever
+ * `aimux.config.ts` declares, and this way the toggle lands without a restart.
+ */
+export function useActivitySprites(): boolean {
+  return useSettingsStore((s) => s.values[ACTIVITY_SPRITES] === true)
+}
+
+/** Whether to keep Claude Code's theme in step with the active aimux theme. */
+export function useHarmonizeClaudeTheme(fromConfigFile: boolean | undefined): boolean {
+  const stored = useSettingsStore((s) => s.values[HARMONIZE_CLAUDE_THEME])
+  return typeof stored === 'boolean' ? stored : fromConfigFile === true
+}

package/src/settings/search.ts

@@ -0,0 +1,43 @@
+import type { ProjectRecord } from '../state/types'
+import type { SettingRow } from './types'
+
+import { sectionRows, SETTING_SECTIONS } from './sections'
+
+export interface SettingSearchHit {
+  row: SettingRow
+  sectionId: string
+  sectionLabel: string
+  /** Index within its own section, which is what the cursor is expressed in. */
+  rowIndex: number
+}
+
+/**
+ * Every setting the query matches, across every section. Ten sections is more
+ * than anyone will scan, and this is the only list in the app you could not type
+ * into to find something.
+ *
+ * Shared with `getModalOptionCount` so the picker and the reducer that moves its
+ * cursor count the same list — two filters would drift the moment one changed.
+ */
+export function filterSettingRows(
+  projects: readonly ProjectRecord[],
+  query: string | null
+): SettingSearchHit[] {
+  const needle = (query ?? '').trim().toLowerCase()
+  const hits: SettingSearchHit[] = []
+
+  for (const section of SETTING_SECTIONS) {
+    const rows = sectionRows(section, projects)
+    for (let rowIndex = 0; rowIndex < rows.length; rowIndex++) {
+      const row = rows[rowIndex]
+      if (!row) continue
+      // The id is in the haystack deliberately: it is the key in `aimux.json`, so
+      // someone who saw it in that file can search for it.
+      const haystack = `${row.label} ${row.description ?? ''} ${row.id} ${section.label}`
+      if (needle !== '' && !haystack.toLowerCase().includes(needle)) continue
+      hits.push({ row, rowIndex, sectionId: section.id, sectionLabel: section.label })
+    }
+  }
+
+  return hits
+}

package/src/settings/sections/about.ts

@@ -0,0 +1,49 @@
+import type { SettingSection } from '../types'
+
+import { version as APP_VERSION } from '../../../package.json'
+import { getConfigPath } from '../../config'
+import { getProfileConfigDir, getProfileName } from '../../profile-paths'
+import { settingsStore } from '../settings-store'
+
+/**
+ * Read-only. Everything here answers a question you would otherwise answer by
+ * digging through `~/.config`: which build is running, which profile, where its
+ * files are, and how many settings your own config file is holding onto.
+ */
+export const ABOUT_SECTION: SettingSection = {
+  id: 'about',
+  label: 'About',
+  rows: [
+    { id: 'about.version', kind: 'info', label: 'Version', value: () => APP_VERSION },
+    {
+      description: 'Set with --profile, or AIMUX_PROFILE in the environment.',
+      id: 'about.profile',
+      kind: 'info',
+      label: 'Profile',
+      value: () => getProfileName(),
+    },
+    {
+      id: 'about.configDir',
+      kind: 'info',
+      label: 'Config directory',
+      value: () => getProfileConfigDir(),
+    },
+    {
+      description: 'Settings written here land in this file.',
+      id: 'about.configFile',
+      kind: 'info',
+      label: 'App config',
+      value: () => getConfigPath(),
+    },
+    {
+      description: 'Those come back from your config file every launch.',
+      id: 'about.fromConfigFile',
+      kind: 'info',
+      label: 'Set in aimux.config.ts',
+      value: () => {
+        const count = settingsStore.getState().fromConfigFile.size
+        return count === 0 ? 'nothing' : `${String(count)} setting(s)`
+      },
+    },
+  ],
+}

package/src/settings/sections/appearance.ts

@@ -0,0 +1,54 @@
+import type { SettingSection } from '../types'
+
+import { dispatchGlobal, runSideEffectGlobal } from '../../state/dispatch-ref'
+import { getCurrentMode, getCurrentThemeId, getTransparent } from '../../ui/theme'
+
+/**
+ * The theme lives in its own store, not in `AppState`. Rows over it read it
+ * directly and write through the side effects that already apply it live and
+ * persist it — every row on this screen calls `useTheme`, so a theme change
+ * re-renders them all and these reads never go stale.
+ */
+export const APPEARANCE_SECTION: SettingSection = {
+  id: 'appearance',
+  label: 'Appearance',
+  rows: [
+    {
+      // Hands over to the picker rather than being a list of 30-odd options on
+      // this screen: it filters as you type and previews each theme as you move.
+      // It comes back here when it closes, which is what `returnTo` is for.
+      description: 'Filters as you type, and previews as you move.',
+      id: 'appearance.theme',
+      kind: 'action',
+      label: 'Theme',
+      run: () => {
+        dispatchGlobal({ returnTo: 'settings', type: 'open-theme-picker' })
+        runSideEffectGlobal({ action: 'open', type: 'apply-theme' })
+      },
+      value: () => `${getCurrentThemeId()} ›`,
+    },
+    {
+      id: 'appearance.mode',
+      kind: 'select',
+      label: 'Mode',
+      options: [
+        { label: 'dark', value: 'dark' },
+        { label: 'light', value: 'light' },
+      ],
+      read: () => getCurrentMode(),
+      storage: 'app',
+      // Flips rather than sets, which is safe because `writeRow` never hands a
+      // row the value it already has.
+      write: () => runSideEffectGlobal({ type: 'toggle-mode' }),
+    },
+    {
+      description: "Let the host terminal's own background show through.",
+      id: 'appearance.transparent',
+      kind: 'toggle',
+      label: 'Transparent background',
+      read: () => getTransparent(),
+      storage: 'app',
+      write: () => runSideEffectGlobal({ type: 'toggle-transparent' }),
+    },
+  ],
+}