@xingular/harness 0.1.6 → 2.0.0

package/src/terminal/tui/screen.test.ts

@@ -0,0 +1,143 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { type Theme } from '@earendil-works/pi-coding-agent'
+import { Container, TuiAltScreen, TuiMainScreen, VStack, stripTerminalSequences, type Component, type Terminal } from '@earendil-works/pi-tui'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { createDock, createTerminalScreen, mountTerminalLayout, readScreenPreferences, scrollbackLines, writeScrollback, type ScreenHooks, type ScreenPreferences } from './screen'
+import { createHarnessTheme } from './theme'
+
+const directories: string[] = []
+afterEach(async () => { for (const directory of directories.splice(0)) await rm(directory, { recursive: true, force: true }) })
+
+const theme = createHarnessTheme({ getColorMode: () => 'truecolor' } as Theme)
+const hooks: ScreenHooks = { theme: () => theme, latestKey: () => 'ctrl+end', openUrl: vi.fn(), pasteClipboard: vi.fn() }
+const defaults = readScreenPreferences(undefined)
+const prefs = (mode: ScreenPreferences['mode']): ScreenPreferences => ({ ...defaults, mode })
+
+function fakeTerminal(columns = 40, rows = 12): Terminal {
+  return {
+    columns, rows, kittyProtocolActive: false, start: vi.fn(), stop: vi.fn(), drainInput: vi.fn(async () => {}), write: vi.fn(),
+    moveBy: vi.fn(), hideCursor: vi.fn(), showCursor: vi.fn(), clearLine: vi.fn(), clearFromCursor: vi.fn(), clearScreen: vi.fn(),
+    setTitle: vi.fn(), setProgress: vi.fn(), setProgramStatus: vi.fn()
+  } as unknown as Terminal
+}
+
+/** A transcript whose rows the test changes, and a three-row dock standing in for the rule, prompt and footer. */
+function panes(initial: string[]) {
+  let transcript = initial
+  const document = new Container()
+  document.addChild({ render: () => [...transcript], invalidate: () => {} })
+  const dock = new VStack([{ component: { render: () => ['─'.repeat(40), '❯ prompt', '? for shortcuts'], invalidate: () => {} }, shrink: 1, minSize: 0 }])
+  return { document, dock, set(lines: string[]) { transcript = lines } }
+}
+
+function rowOf(lines: string[]): Component {
+  return { render: () => [...lines], invalidate: () => {} }
+}
+
+function screenRows(tui: TuiAltScreen): string[] {
+  return tui.getScreenLines().map(line => stripTerminalSequences(line).trimEnd())
+}
+
+describe('terminal screen preferences', () => {
+  it('follows Pi fullscreen defaults when no account folder is prepared', () => {
+    expect(defaults).toEqual({ mode: 'fullscreen', exitOutput: 'transcript', scrollbar: 'auto', wheelScrollLines: 'auto', copyOnSelect: true })
+  })
+
+  it('reads the regular screen from the account settings', async () => {
+    const directory = await mkdtemp(join(tmpdir(), 'harness-screen-'))
+    directories.push(directory)
+    await writeFile(join(directory, 'settings.json'), JSON.stringify({ tuiMode: 'regular' }))
+    expect(readScreenPreferences(directory).mode).toBe('regular')
+  })
+})
+
+describe('terminal screen layout', () => {
+  it('keeps the dock on the last rows while the transcript is short', () => {
+    const tui = createTerminalScreen(fakeTerminal(40, 12), prefs('fullscreen'), hooks) as TuiAltScreen
+    const { document, dock } = panes(['Welcome'])
+    mountTerminalLayout(tui, { document, dock }, prefs('fullscreen'), hooks)
+    tui.start()
+    tui.renderNow(true)
+    const rows = screenRows(tui)
+    expect(rows).toHaveLength(12)
+    expect(rows[0]).toBe('Welcome')
+    expect(rows.slice(-3)).toEqual(['─'.repeat(40), '❯ prompt', '? for shortcuts'])
+    tui.stop()
+  })
+
+  it('does not move the dock as the transcript grows', () => {
+    const tui = createTerminalScreen(fakeTerminal(40, 12), prefs('fullscreen'), hooks) as TuiAltScreen
+    const { document, dock, set } = panes(['Welcome'])
+    mountTerminalLayout(tui, { document, dock }, prefs('fullscreen'), hooks)
+    tui.start()
+    tui.renderNow(true)
+    set(Array.from({ length: 30 }, (_, index) => `message ${index}`))
+    tui.renderNow(true)
+    const rows = screenRows(tui)
+    expect(rows).toHaveLength(12)
+    expect(rows.slice(-3)).toEqual(['─'.repeat(40), '❯ prompt', '? for shortcuts'])
+    expect(rows[8]).toBe('message 29')
+    tui.stop()
+  })
+
+  it('scrolls the transcript above a dock that stays where it is', () => {
+    const tui = createTerminalScreen(fakeTerminal(40, 12), prefs('fullscreen'), hooks) as TuiAltScreen
+    const { document, dock, set } = panes(Array.from({ length: 30 }, (_, index) => `message ${index}`))
+    mountTerminalLayout(tui, { document, dock }, prefs('fullscreen'), hooks)
+    tui.start()
+    tui.renderNow(true)
+    expect(tui.isFollowingOutput).toBe(true)
+    tui.scrollBy(-10)
+    tui.renderNow(true)
+    expect(tui.isFollowingOutput).toBe(false)
+    const rows = screenRows(tui)
+    expect(rows.slice(-3)).toEqual(['─'.repeat(40), '❯ prompt', '? for shortcuts'])
+    expect(rows.some(row => row === 'message 29')).toBe(false)
+    set(['message 0'])
+    tui.stop()
+  })
+
+  it('shows the first rows of a long queue while the prompt and status stay whole', () => {
+    const tui = createTerminalScreen(fakeTerminal(40, 12), prefs('fullscreen'), hooks) as TuiAltScreen
+    const queued = Array.from({ length: 20 }, (_, index) => `queued ${index}`)
+    const dock = createDock({
+      title: rowOf(['title']), above: rowOf([]), queue: rowOf(queued), below: rowOf([]), footer: rowOf(['status']),
+      editor: rowOf(['─'.repeat(40), '❯ prompt', '─'.repeat(40), '? for shortcuts'])
+    })
+    const document = new Container()
+    document.addChild(rowOf(['Welcome']))
+    mountTerminalLayout(tui, { document, dock }, prefs('fullscreen'), hooks)
+    tui.start()
+    tui.renderNow(true)
+    const rows = screenRows(tui)
+    expect(rows).toHaveLength(12)
+    expect(rows.slice(-5)).toEqual(['─'.repeat(40), '❯ prompt', '─'.repeat(40), '? for shortcuts', 'status'])
+    expect(rows).toContain('queued 0')
+    expect(rows).not.toContain('queued 19')
+    tui.stop()
+  })
+
+  it('flows the regular screen in order without a viewport', () => {
+    const tui = createTerminalScreen(fakeTerminal(), prefs('regular'), hooks)
+    expect(tui).toBeInstanceOf(TuiMainScreen)
+    const { document, dock } = panes(['Welcome'])
+    expect(mountTerminalLayout(tui, { document, dock }, prefs('regular'), hooks)).toBeUndefined()
+    expect(tui.children).toEqual([document, dock])
+  })
+})
+
+describe('terminal scrollback on exit', () => {
+  it('truncates the conversation to the terminal width', () => {
+    const component: Component = { render: () => ['x'.repeat(30)], invalidate: () => {} }
+    expect(scrollbackLines(component, 10).map(line => stripTerminalSequences(line))).toEqual(['x'.repeat(10)])
+  })
+
+  it('writes each line with its styles reset and CRLF endings', () => {
+    const terminal = fakeTerminal()
+    writeScrollback(terminal, ['first', 'second'])
+    expect(terminal.write).toHaveBeenCalledWith('first\x1b[0m\r\nsecond\x1b[0m\r\n')
+  })
+})

package/src/terminal/tui/screen.ts

@@ -0,0 +1,121 @@
+// Screen mode and layout. Pi's fullscreen settings still choose the mode; Harness supplies its own composition.
+import { SettingsManager, copyToClipboard, type FullscreenExitOutput, type Theme, type TuiMode } from '@earendil-works/pi-coding-agent'
+import { ScrollView, TuiAltScreen, TuiMainScreen, VStack, isViewportTUI, truncateToWidth, type Component, type Terminal, type TuiAltScreenOptions } from '@earendil-works/pi-tui'
+
+export interface DockSlots {
+  readonly title: Component
+  readonly above: Component
+  readonly queue: Component
+  readonly editor: Component
+  readonly below: Component
+  readonly footer: Component
+}
+
+export type TerminalScreen = TuiMainScreen | TuiAltScreen
+
+export interface ScreenPreferences {
+  readonly mode: TuiMode
+  readonly exitOutput: FullscreenExitOutput
+  readonly scrollbar: ReturnType<SettingsManager['getFullscreenScrollbar']>
+  readonly wheelScrollLines: ReturnType<SettingsManager['getFullscreenWheelScrollLines']>
+  readonly copyOnSelect: boolean
+}
+
+export interface ScreenHooks {
+  theme(): Theme
+  latestKey(): string | undefined
+  openUrl(url: string): void
+  pasteClipboard(): void
+}
+
+export interface TerminalPanes {
+  readonly document: Component
+  readonly dock: Component
+}
+
+export function readScreenPreferences(agentDir: string | undefined): ScreenPreferences {
+  // Without an account folder there is no settings file to read, so Pi's defaults apply.
+  const settings = agentDir ? SettingsManager.create(process.cwd(), agentDir) : SettingsManager.inMemory()
+  return {
+    mode: settings.getTuiMode(),
+    exitOutput: settings.getFullscreenExitOutput(),
+    scrollbar: settings.getFullscreenScrollbar(),
+    wheelScrollLines: settings.getFullscreenWheelScrollLines(),
+    copyOnSelect: settings.getFullscreenCopyOnSelect()
+  }
+}
+
+export function createTerminalScreen(terminal: Terminal, preferences: ScreenPreferences, hooks: ScreenHooks): TerminalScreen {
+  if (preferences.mode === 'regular') return new TuiMainScreen(terminal)
+  const { theme } = hooks
+  const options: TuiAltScreenOptions = {
+    wheelScrollLines: preferences.wheelScrollLines,
+    copyOnSelect: preferences.copyOnSelect,
+    searchMatchStyle: text => theme().underline(theme().bg('searchMatchBg', theme().fg('searchMatchText', text))),
+    searchCurrentMatchStyle: text => theme().bold(theme().inverse(theme().bg('searchMatchBg', theme().fg('searchMatchText', text)))),
+    searchNavigationButtonStyle: (text, hovered) => hovered ? theme().underline(text) : text,
+    scrollToEndIndicator: () => {
+      const key = hooks.latestKey()
+      return theme().bg('selectedBg', theme().fg('text', ` ↓ Jump to latest message${key ? ` · ${keyLabel(key)}` : ''} `))
+    },
+    openUrl: hooks.openUrl,
+    onRightClickPaste: hooks.pasteClipboard,
+    copySelection: copySelectionText
+  }
+  return new TuiAltScreen(terminal, undefined, undefined, options)
+}
+
+/** The prompt and status keep their full height; when the screen is short, queued messages and widgets show their first rows and scroll for the rest. */
+export function createDock(slots: DockSlots): VStack {
+  const region = (component: Component) => new ScrollView(component)
+  return new VStack([
+    { component: slots.title, shrink: 0 },
+    { component: region(slots.above), shrink: 1, minSize: 0 },
+    { component: region(slots.queue), shrink: 1, minSize: 0 },
+    { component: slots.editor, shrink: 0 },
+    { component: region(slots.below), shrink: 1, minSize: 0 },
+    { component: slots.footer, shrink: 0 }
+  ])
+}
+
+/** Fullscreen keeps the dock on the last rows and scrolls only the transcript above it; regular mode flows in order. */
+export function mountTerminalLayout(tui: TerminalScreen, panes: TerminalPanes, preferences: ScreenPreferences, hooks: ScreenHooks): ScrollView | undefined {
+  if (!isViewportTUI(tui)) {
+    tui.addChild(panes.document)
+    tui.addChild(panes.dock)
+    return undefined
+  }
+  const transcript = new ScrollView(panes.document, {
+    follow: 'end', primary: true, overscroll: 'chain', scrollbar: preferences.scrollbar,
+    scrollbarTrackStyle: text => hooks.theme().fg('scrollbarTrack', text),
+    scrollbarThumbStyle: text => hooks.theme().fg('scrollbarThumb', text)
+  })
+  tui.setLayoutRoot(new VStack([
+    { component: transcript, basis: 0, grow: 1, shrink: 1, minSize: 1 },
+    { component: panes.dock, basis: 'auto', grow: 0, shrink: 1, minSize: 1 }
+  ]))
+  return transcript
+}
+
+/** Rendered before the alternate screen is left, because the components are disposed afterwards. */
+export function scrollbackLines(component: Component, width: number): string[] {
+  return component.render(width).map(line => truncateToWidth(line, width, ''))
+}
+
+/** Leaving fullscreen discards the alternate screen, so the conversation is copied into normal scrollback. */
+export function writeScrollback(terminal: Terminal, lines: string[]): void {
+  terminal.write(lines.map(line => `${line}\x1b[0m`).join('\r\n') + '\r\n')
+}
+
+function keyLabel(key: string): string {
+  return key.replace(/(^|\+)([a-z])/g, (_match, separator: string, letter: string) => separator + letter.toUpperCase())
+}
+
+async function copySelectionText(text: string): Promise<boolean | string> {
+  try {
+    await copyToClipboard(text)
+    return true
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error)
+  }
+}

package/src/terminal/tui/sessionUi.ts

@@ -0,0 +1,24 @@
+import type { ExtensionUIContext } from '@earendil-works/pi-coding-agent'
+
+const dialogs = new Set(['select', 'input', 'editor', 'custom'])
+
+/** Retained UI methods belong to the resource generation that received them. */
+export function sessionUiContext(ui: ExtensionUIContext, current: () => boolean): ExtensionUIContext {
+  return new Proxy(ui, {
+    get(target, key, receiver) {
+      const value = Reflect.get(target, key, receiver)
+      if (typeof value !== 'function') return value
+      return (...args: unknown[]) => {
+        if (current()) return Reflect.apply(value, target, args)
+        if (key === 'confirm') return Promise.resolve(false)
+        if (dialogs.has(String(key))) return Promise.resolve(undefined)
+        if (key === 'onTerminalInput') return () => {}
+        if (key === 'setTheme') return { success: false, error: 'This terminal session has ended.' }
+        if (key === 'getEditorText') return ''
+        if (key === 'getToolsExpanded') return false
+        if (key === 'getAllThemes') return []
+        return undefined
+      }
+    }
+  })
+}

package/src/terminal/tui/settings.test.ts

@@ -0,0 +1,150 @@
+import type { Theme } from '@earendil-works/pi-coding-agent'
+import { CURSOR_MARKER, stripTerminalSequences, visibleWidth, type TUI } from '@earendil-works/pi-tui'
+import { describe, expect, it, vi } from 'vitest'
+
+import { SettingsPanel, type TerminalSettingItem } from './settings'
+import { createHarnessTheme } from './theme'
+
+const theme = createHarnessTheme({ getColorMode: () => 'truecolor' } as Theme)
+const items: TerminalSettingItem[] = [
+  { id: 'theme', tab: 'appearance', group: 'Theme', label: 'Dark Theme', value: 'Titanium', description: 'Theme used with dark terminal backgrounds.' },
+  { id: 'composer', tab: 'appearance', group: 'Composer', label: 'Composer Shape', value: 'Band', description: 'Choose the terminal input layout.' },
+  { id: 'expanded', tab: 'appearance', group: 'Display', label: 'Expand Tool Output', value: 'Off', description: 'Expand actual output from tools.' },
+  { id: 'thinking', tab: 'model', group: 'Thinking', label: 'Thinking Level', value: 'High', description: 'Control reasoning effort for the current model.' },
+  { id: 'input', tab: 'interaction', group: 'Input', label: 'Autocomplete', value: 'On' },
+  { id: 'compact', tab: 'context', group: 'Compaction', label: 'Auto Compact', value: 'On', description: 'Compact the context when the supported token threshold is reached.' }
+]
+function setup(initialId?: string, rows = 30, source = items) {
+  const terminal = { rows }
+  const done = vi.fn()
+  const panel = new SettingsPanel({ terminal } as unknown as TUI, () => theme, source, done, initialId)
+  panel.focused = true
+  return { panel, done, terminal }
+}
+const plain = (panel: SettingsPanel, width = 100) => panel.render(width).map(stripTerminalSequences)
+
+describe('the supported settings terminal panel', () => {
+  it('fills the terminal with the upstream rounded settings frame, supported tabs and group rail', () => {
+    const { panel } = setup()
+    const rows = plain(panel)
+    expect(rows).toHaveLength(30)
+    expect(rows[0]).toMatch(/^╭─ Settings /)
+    expect(rows[0]).toMatch(/╮$/)
+    expect(rows.at(-1)).toMatch(/^╰─.*╯$/)
+    expect(rows[1]).toContain('🎨 Appearance')
+    expect(rows[1]).toContain('Model')
+    expect(rows[1]).toContain('Interaction')
+    expect(rows[1]).toContain('Context')
+    expect(rows.join('\n')).not.toMatch(/Providers|Advisor|Preview:|Tasks|Memory/)
+    expect(rows.some(row => row.includes('│   Theme') && row.slice(25).includes('│'))).toBe(true)
+    expect(rows.join('\n')).toContain('❯ Dark Theme')
+    expect(rows.join('\n')).toContain('Titanium')
+    expect(rows.join('\n')).toContain('Theme used with dark terminal backgrounds.')
+    expect(panel.render(100).join('')).toContain(theme.getBgAnsi('selectedBg'))
+    const compactTabs = plain(panel, 40)[1]
+    for (const icon of ['🎨', '🤖', '⌨', '📋']) expect(compactTabs).toContain(icon)
+  })
+
+  it('uses flat rows at 80 columns and a section rail only when the value pane fits', () => {
+    const { panel } = setup()
+    const narrow = plain(panel, 80).find(row => row.includes('❯ Dark Theme'))!
+    const wide = plain(panel, 100).find(row => row.includes('❯ Dark Theme'))!
+    expect(narrow.match(/│/g)).toHaveLength(2)
+    expect(wide.match(/│/g)).toHaveLength(3)
+  })
+
+  it('moves through tabs and items and resolves only an actual selected setting id', () => {
+    const { panel, done } = setup()
+    panel.handleInput('\x1b[B')
+    expect(panel.selectedId).toBe('composer')
+    panel.handleInput('\r')
+    expect(done).toHaveBeenLastCalledWith('composer')
+    panel.handleInput('\x1b[C')
+    expect(panel.selectedId).toBe('thinking')
+    panel.handleInput(' ')
+    expect(done).toHaveBeenLastCalledWith('thinking')
+    panel.handleInput('\x1b[D')
+    expect(panel.selectedId).toBe('composer')
+    panel.handleInput('\x1b')
+    expect(done).toHaveBeenLastCalledWith(undefined)
+  })
+
+  it('moves group focus through the rail and returns to item editing without triggering an action', () => {
+    const { panel, done } = setup()
+    panel.handleInput('\t')
+    panel.handleInput('\x1b[B')
+    expect(panel.selectedId).toBe('composer')
+    expect(plain(panel).join('\n')).toContain('❯ Composer')
+    panel.handleInput('\r')
+    expect(done).not.toHaveBeenCalled()
+    panel.handleInput('\r')
+    expect(done).toHaveBeenCalledWith('composer')
+  })
+
+  it('restores the last selected tab, group and item from initialId', () => {
+    const { panel } = setup('compact')
+    expect(panel.selectedId).toBe('compact')
+    expect(plain(panel)[1]).toContain('Context')
+    expect(plain(panel).join('\n')).toContain('❯ Auto Compact')
+    expect(plain(panel).join('\n')).not.toContain('Dark Theme')
+    expect(setup('missing').panel.selectedId).toBe('theme')
+  })
+
+  it('searches across supported tabs using labels, values and descriptions with a visible cursor', () => {
+    const { panel, done } = setup()
+    panel.handleInput('reasoning')
+    const rows = plain(panel).join('\n')
+    expect(rows).toContain('1 match')
+    expect(rows).toContain('Thinking Level')
+    expect(rows).not.toContain('Dark Theme')
+    expect(panel.render(100).join('')).toContain(CURSOR_MARKER)
+    panel.handleInput('\r')
+    expect(done).toHaveBeenCalledWith('thinking')
+    panel.handleInput('\x1b')
+    expect(done).toHaveBeenLastCalledWith(undefined)
+  })
+
+  it('renders explicit empty search results and never selects a hidden item', () => {
+    const { panel, done } = setup()
+    panel.handleInput('zzzzzzzzzzz')
+    expect(plain(panel).join('\n')).toContain('No matching settings')
+    expect(panel.selectedId).toBeUndefined()
+    panel.handleInput('\r')
+    panel.handleInput(' ')
+    expect(done).not.toHaveBeenCalled()
+    panel.handleInput('\x7f')
+    expect(panel.selectedId).toBeUndefined()
+  })
+
+  it('keeps the selected setting visible as lists grow and the terminal resizes', () => {
+    const source = Array.from({ length: 100 }, (_, index) => ({ id: `item${index}`, tab: 'appearance', group: 'Display', label: `Setting ${index}`, value: String(index) }))
+    const { panel, terminal } = setup('item85', 20, source)
+    for (const height of [40, 20, 10, 7]) {
+      terminal.rows = height
+      expect(plain(panel).join('\n'), `height ${height}`).toContain('❯ Setting 85')
+      expect(panel.render(80)).toHaveLength(height)
+    }
+    expect(panel.selectedId).toBe('item85')
+  })
+
+  it('bounds every row and terminal height for narrow Unicode labels and descriptions', () => {
+    const source = [{ id: 'cjk', tab: 'appearance', group: '日本語 🧠', label: '知識設定 日本語', value: '🧠 有効', description: '日本語の説明を長く表示します。'.repeat(20) }]
+    const { panel, terminal } = setup('cjk', 30, source)
+    for (const height of [0, 1, 3, 6, 10, 20, 40]) {
+      terminal.rows = height
+      for (let width = 0; width <= 130; width++) {
+        const rows = panel.render(width)
+        expect(rows.length, `${width}x${height}`).toBeLessThanOrEqual(height)
+        for (const row of rows) expect(visibleWidth(row), `${width}x${height}`).toBeLessThanOrEqual(width)
+      }
+    }
+    expect(panel.selectedId).toBe('cjk')
+  })
+
+  it('does not expose unsupported categories or mutate caller setting data', () => {
+    const source = Object.freeze([...items, Object.freeze({ id: 'fake', tab: 'tasks', group: 'Agents', label: 'Invented feature', value: 'Off' })])
+    const { panel } = setup(undefined, 30, source as unknown as TerminalSettingItem[])
+    expect(plain(panel).join('\n')).not.toContain('Invented feature')
+    expect(source[0].value).toBe('Titanium')
+  })
+})

package/src/terminal/tui/settings.ts

@@ -0,0 +1,188 @@
+/**
+ * Settings chrome adapted from Oh My Pi 18.11.3 settings-selector.ts and
+ * settings-list.ts (MIT; see NOTICE-oh-my-pi). Values and actions belong to the host.
+ */
+import type { Theme } from '@earendil-works/pi-coding-agent'
+import { Input, fuzzyFilter, matchesKey, stripTerminalSequences, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component, type Focusable, type TUI } from '@earendil-works/pi-tui'
+
+export interface TerminalSettingItem {
+  id: string
+  tab: string
+  group: string
+  label: string
+  value: string
+  description?: string
+}
+const categories = ['appearance', 'model', 'interaction', 'context'] as const
+const categoryIcon: Record<string, string> = { appearance: '🎨', model: '🤖', interaction: '⌨', context: '📋' }
+const categoryName = (value: string) => value.charAt(0).toUpperCase() + value.slice(1)
+const plain = (value: string) => stripTerminalSequences(value).replace(/[\x00-\x1f\x7f]/g, ' ')
+const tabOf = (item: TerminalSettingItem) => item.tab.toLowerCase()
+
+/** A full terminal settings view. It describes existing host settings without owning them. */
+export class SettingsPanel implements Component, Focusable {
+  private search = new Input({ prompt: '' })
+  private query = ''
+  private currentTab = ''
+  private selected: string | undefined
+  private groupFocus = false
+  private focusedValue = false
+  private remembered = new Map<string, string>()
+  private readonly items: TerminalSettingItem[]
+  private readonly tabs: string[]
+  constructor(private readonly tui: TUI, private readonly theme: () => Theme, items: TerminalSettingItem[], private readonly done: (id: string | undefined) => void, initialId?: string) {
+    this.items = items.filter(item => categories.includes(tabOf(item) as typeof categories[number]))
+    this.tabs = categories.filter(tab => this.items.some(item => tabOf(item) === tab))
+    const initial = this.items.find(item => item.id === initialId)
+    this.currentTab = initial ? tabOf(initial) : this.tabs[0] ?? ''
+    this.selected = initial?.id ?? this.visibleItems()[0]?.id
+  }
+  get selectedId(): string | undefined { return this.selected }
+  get focused(): boolean { return this.focusedValue }
+  set focused(value: boolean) { this.focusedValue = value; this.search.focused = value && this.query.length > 0 }
+  invalidate(): void { this.search.invalidate() }
+  private visibleItems(): TerminalSettingItem[] {
+    return this.query
+      ? fuzzyFilter(this.items, this.query, item => `${item.label} ${item.id} ${item.value} ${item.description ?? ''} ${item.group} ${item.tab}`)
+      : this.items.filter(item => tabOf(item) === this.currentTab)
+  }
+  private select(item: TerminalSettingItem | undefined): void {
+    this.selected = item?.id
+    if (item) { this.currentTab = tabOf(item); this.remembered.set(this.currentTab, item.id) }
+  }
+  private switchTab(direction: number): void {
+    const tabs = this.query ? this.tabs.filter(tab => this.visibleItems().some(item => tabOf(item) === tab)) : this.tabs
+    if (!tabs.length) return
+    const at = Math.max(0, tabs.indexOf(this.currentTab))
+    this.currentTab = tabs[(at + direction + tabs.length) % tabs.length]
+    const items = this.visibleItems().filter(item => tabOf(item) === this.currentTab)
+    this.select(items.find(item => item.id === this.remembered.get(this.currentTab)) ?? items[0])
+    this.groupFocus = false
+  }
+  private jumpGroup(direction: number): void {
+    const items = this.visibleItems()
+    const groups = [...new Set(items.map(item => item.group))]
+    const current = items.find(item => item.id === this.selected)?.group
+    const index = Math.max(0, groups.indexOf(current ?? ''))
+    const group = groups[(index + direction + groups.length) % groups.length]
+    this.select(items.find(item => item.group === group))
+  }
+  handleInput(data: string): void {
+    if (matchesKey(data, 'escape') || matchesKey(data, 'ctrl+c')) { this.done(undefined); return }
+    if (matchesKey(data, 'left') || matchesKey(data, 'right')) { this.switchTab(matchesKey(data, 'left') ? -1 : 1); return }
+    if (matchesKey(data, 'tab') || matchesKey(data, 'shift+tab')) {
+      if (this.query) this.switchTab(matchesKey(data, 'shift+tab') ? -1 : 1)
+      else if (new Set(this.visibleItems().map(item => item.group)).size > 1) this.groupFocus = !this.groupFocus
+      else this.switchTab(matchesKey(data, 'shift+tab') ? -1 : 1)
+      return
+    }
+    if (matchesKey(data, 'up') || matchesKey(data, 'down') || matchesKey(data, 'pageUp') || matchesKey(data, 'pageDown')) {
+      const direction = matchesKey(data, 'up') || matchesKey(data, 'pageUp') ? -1 : 1
+      if (this.groupFocus || matchesKey(data, 'pageUp') || matchesKey(data, 'pageDown')) this.jumpGroup(direction)
+      else {
+        const items = this.visibleItems()
+        const at = Math.max(0, items.findIndex(item => item.id === this.selected))
+        this.select(items[Math.max(0, Math.min(items.length - 1, at + direction))])
+      }
+      return
+    }
+    if (matchesKey(data, 'enter') || data === ' ') {
+      if (this.groupFocus) this.groupFocus = false
+      else if (this.selected) this.done(this.selected)
+      return
+    }
+    this.search.handleInput(data)
+    if (this.search.getValue() !== this.query) {
+      this.query = this.search.getValue()
+      this.groupFocus = false
+      this.search.focused = this.focusedValue && !!this.query
+      const items = this.visibleItems()
+      this.select(items.find(item => item.id === this.selected) ?? items[0])
+    }
+  }
+
+  render(width: number): string[] {
+    const height = Math.max(0, Math.trunc(this.tui.terminal.rows))
+    width = Math.max(0, Math.trunc(width))
+    if (!width || !height) return []
+    const theme = this.theme()
+    const inner = Math.max(0, width - 4)
+    const clip = (value: string, columns = width) => truncateToWidth(value, columns, '')
+    const pad = (value: string, columns: number) => clip(value, columns) + ' '.repeat(Math.max(0, columns - Math.min(columns, visibleWidth(value))))
+    const border = (value: string) => theme.fg('border', value)
+    const row = (value: string) => clip(border('│') + ' ' + pad(value, inner) + ' ' + border('│'))
+    const rule = () => clip(border('├' + '─'.repeat(Math.max(0, width - 2)) + '┤'))
+    const title = clip(' Settings ', Math.max(0, width - 4))
+    const top = clip(border('╭─') + theme.bold(theme.fg('accent', title)) + border('─'.repeat(Math.max(0, width - visibleWidth(title) - 3)) + '╮'))
+    const bottom = clip(border('╰' + '─'.repeat(Math.max(0, width - 2)) + '╯'))
+    const tabRow = (compact: boolean) => this.tabs.map(tab => {
+      const label = ` ${categoryIcon[tab]}${compact ? '' : ` ${categoryName(tab)}`} `
+      return tab === this.currentTab ? theme.bg('selectedBg', theme.fg('accent', label)) : theme.fg('muted', label)
+    }).join('  ')
+    let tabs = tabRow(false)
+    if (visibleWidth(tabs) > inner) tabs = tabRow(true)
+    if (visibleWidth(tabs) > inner) tabs = theme.fg('accent', `‹ ${categoryIcon[this.currentTab] ?? ''} ${categoryName(this.currentTab)} ›`)
+    const lines = [top, row(tabs), rule()]
+    const items = this.visibleItems()
+    const current = items.find(item => item.id === this.selected)
+    if (this.query) {
+      const count = `${items.length} ${items.length === 1 ? 'match' : 'matches'}`
+      const prefix = theme.fg('accent', '🔍 ')
+      const queryWidth = Math.max(2, inner - visibleWidth(prefix) - count.length - 1)
+      lines.push(row(prefix + (this.search.render(queryWidth)[0] ?? '') + ' ' + theme.fg('dim', count)))
+    }
+    const contentRows = Math.max(0, height - lines.length - 3)
+    const descriptionRows = Math.min(3, Math.max(0, contentRows - 2))
+    const listRows = Math.max(0, contentRows - descriptionRows - (descriptionRows ? 1 : 0))
+    const groups = [...new Set(items.map(item => item.group))]
+    // The shipped SettingsList keeps at least 60 columns for editable rows.
+    const sidebar = !this.query && groups.length > 1 && inner - 28 >= 60 ? 26 : 0
+    const paneWidth = Math.max(0, inner - (sidebar ? sidebar + 2 : 0))
+    const entries: { item?: TerminalSettingItem; heading?: string }[] = []
+    let lastGroup: string | undefined
+    for (const item of items) {
+      const group = this.query ? `${categoryName(tabOf(item))} / ${item.group}` : item.group
+      if (group !== lastGroup) { entries.push({ heading: group }); lastGroup = group }
+      entries.push({ item })
+    }
+    const selectedRow = entries.findIndex(entry => entry.item?.id === this.selected)
+    const start = Math.max(0, Math.min(Math.max(0, entries.length - listRows), selectedRow - Math.floor(listRows / 2)))
+    const maxLabel = Math.min(30, Math.max(0, ...items.map(item => visibleWidth(plain(item.label)))))
+    const labelWidth = Math.min(maxLabel, Math.max(0, Math.floor((paneWidth - 4) * 0.6)))
+    for (let index = 0; index < listRows; index++) {
+      const entry = entries[start + index]
+      let right = ''
+      if (entry?.heading) right = theme.fg(entry.heading.includes(current?.group ?? '\u0000') ? 'accent' : 'dim', plain(entry.heading))
+      if (entry?.item) {
+        const item = entry.item
+        const selected = item.id === this.selected && !this.groupFocus
+        const active = this.query || item.group === current?.group
+        const prefix = selected ? '❯ ' : '  '
+        const labelText = prefix + pad(plain(item.label), labelWidth)
+        const text = labelText + '  ' + clip(plain(item.value), Math.max(0, paneWidth - visibleWidth(labelText) - 2))
+        right = selected
+          ? theme.bg('selectedBg', theme.fg('accent', pad(text, paneWidth)))
+          : theme.fg(active ? 'text' : 'dim', text)
+      }
+      if (!entries.length && index === 0) right = theme.fg('warning', this.query ? 'No matching settings' : 'No settings')
+      if (sidebar) {
+        const name = groups[index]
+        const active = name === current?.group
+        const left = name ? (active && this.groupFocus ? '❯ ' : '  ') + plain(name) : ''
+        const styled = active && this.groupFocus
+          ? theme.bg('selectedBg', theme.fg('accent', pad(left, sidebar)))
+          : theme.fg(active ? 'accent' : 'dim', pad(left, sidebar))
+        lines.push(row(styled + theme.fg('dim', '│ ') + right))
+      } else lines.push(row(right))
+    }
+    if (descriptionRows) lines.push(row(''))
+    const description = current?.description && inner > 1 ? wrapTextWithAnsi(plain(current.description), inner) : []
+    for (let index = 0; index < descriptionRows; index++) lines.push(row(theme.fg('muted', description[index] ?? '')))
+    const footer = this.groupFocus
+      ? '↑/↓ jump sections · Tab/Enter to settings · ←/→ switch tabs · Esc close'
+      : this.query ? 'Enter/Space change · Tab jump tabs · Esc close'
+        : `Enter/Space change · ${groups.length > 1 ? 'Tab jump sections · ←/→ switch tabs' : 'Tab/←/→ switch tabs'} · Type to search · Esc close`
+    lines.push(rule(), row(theme.fg('dim', footer)), bottom)
+    return lines.slice(0, height).map(value => clip(value))
+  }
+}