@brimveyn/aimux 1.23.0 → 1.23.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux",
-  "version": "1.23.0",
+  "version": "1.23.2",
   "description": "A terminal multiplexer for AI CLIs. Run Claude, Codex, OpenCode, Kimi side-by-side with tabbed navigation, split panes, and persistent sessions.",
   "keywords": [
     "ai",
@@ -66,7 +66,7 @@
     "bump:terminal_manager": "bun run scripts/bump-protocol.ts terminal-manager"
   },
   "dependencies": {
-    "@brimveyn/aimux-config": "0.10.2",
+    "@brimveyn/aimux-config": "0.10.3",
     "@opentui/core": "^0.1.90",
     "@opentui/react": "^0.1.90",
     "@resvg/resvg-wasm": "^2.6.2",

package/src/app-runtime/settings-actions.ts

@@ -3,7 +3,7 @@ import type { AppState } from '../state/types'
 import type { SideEffectContext } from './side-effect-context'
 
 import { filterSettingRows } from '../settings/search'
-import { findSettingRow, getSectionRows } from '../settings/sections'
+import { findSettingRow } from '../settings/sections'
 import { readRow, resetRow, settingsStore, writeRow } from '../settings/settings-store'
 import { dispatchGlobal } from '../state/dispatch-ref'
 import { toast } from '../state/toast-store'
@@ -30,14 +30,20 @@ function nextOptionValue(
   return options[(index + delta + size) % size]?.value
 }
 
+/**
+ * One press, one step. Deliberately not a fraction of the range: every number
+ * row here crosses its own range in under sixty presses, because each declares
+ * a `step` scaled to what it measures — so a "drag the gauge" stride would be
+ * arithmetic wrapped around a number the row already got right.
+ */
 function nextNumberValue(
   row: Extract<SettingRow, { kind: 'number' }>,
   current: SettingValue,
   delta: 1 | -1
 ): number {
   const base = typeof current === 'number' ? current : row.min
-  // Clamped, never wrapped: `-`/`+` name a direction, and holding + on a width
-  // until it snaps to the narrowest is not what anyone meant.
+  // Clamped, never wrapped: a direction is a direction, and holding `l` on a
+  // width until it snaps to the narrowest is not what anyone meant.
   return Math.min(row.max, Math.max(row.min, round(base + delta * row.step)))
 }
 
@@ -55,6 +61,15 @@ function readCtx(state: AppState): SettingCtx {
   return { state, values: settingsStore.getState().values }
 }
 
+/**
+ * The row under the cursor. Unfiltered, because the cursor counts every row on
+ * the screen — the same list `filterSettingRows` numbers its hits against.
+ */
+function selectedRow(state: AppState): SettingRow | undefined {
+  if (state.focusMode !== 'settings') return undefined
+  return filterSettingRows(state.projects, null)[state.settings.rowIndex]?.row
+}
+
 /**
  * One entry point for every kind of row. `delta` is the direction asked for
  * (`-`/`+`); without it the row advances the way activating it should — a toggle
@@ -62,9 +77,7 @@ function readCtx(state: AppState): SettingCtx {
  */
 export function changeSelectedSetting(runtime: SettingsContext, delta?: 1 | -1): void {
   const state = runtime.getState()
-  if (state.focusMode !== 'settings' || state.settings.pane !== 'rows') return
-
-  const row = getSectionRows(state.settings.sectionId, state.projects)[state.settings.rowIndex]
+  const row = selectedRow(state)
   if (!row || row.kind === 'info') return
 
   const ctx = readCtx(state)
@@ -102,9 +115,10 @@ export function changeSelectedSetting(runtime: SettingsContext, delta?: 1 | -1):
 }
 
 /**
- * Move the screen's cursor onto the setting the search had highlighted, wherever
- * it turned out to live. The list is recomputed from the same filter the picker
- * drew, so the index still means what it meant.
+ * Move the screen's cursor onto the setting the search had highlighted. The hit
+ * carries its position in the screen's list, so there is nothing to look up —
+ * and the list is recomputed from the same filter the picker drew, so the index
+ * still means what it meant.
  */
 export function confirmSettingsSearch(runtime: SettingsContext): void {
   const state = runtime.getState()
@@ -112,15 +126,12 @@ export function confirmSettingsSearch(runtime: SettingsContext): void {
   const hit = filterSettingRows(state.projects, state.modal.editBuffer)[state.modal.selectedIndex]
   dispatchGlobal({ type: 'close-modal' })
   if (!hit) return
-  dispatchGlobal({ sectionId: hit.sectionId, type: 'settings-select-section' })
   dispatchGlobal({ rowIndex: hit.rowIndex, type: 'settings-select-row' })
 }
 
 /** Puts the selected row back to what it would be if this screen had never run. */
 export function resetSelectedSetting(runtime: SettingsContext): void {
-  const state = runtime.getState()
-  if (state.focusMode !== 'settings' || state.settings.pane !== 'rows') return
-  const row = getSectionRows(state.settings.sectionId, state.projects)[state.settings.rowIndex]
+  const row = selectedRow(runtime.getState())
   if (row) resetRow(row)
 }
 

package/src/settings/search.ts

@@ -7,17 +7,21 @@ export interface SettingSearchHit {
   row: SettingRow
   sectionId: string
   sectionLabel: string
-  /** Index within its own section, which is what the cursor is expressed in. */
+  /**
+   * Position in the screen's list — counted across every section, matches or
+   * not, because the screen is one list and that is what its cursor holds. So a
+   * search result can be jumped to with the index it already carries.
+   */
   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.
+ * Every setting the query matches, across every section. With no query it is
+ * the screen's own list, which is why both go through here: one filter, so the
+ * list you search and the list you scroll can never disagree.
  *
- * 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.
+ * Shared with `getModalOptionCount` too, so the picker and the reducer that
+ * moves its cursor count the same list.
  */
 export function filterSettingRows(
   projects: readonly ProjectRecord[],
@@ -25,12 +29,12 @@ export function filterSettingRows(
 ): SettingSearchHit[] {
   const needle = (query ?? '').trim().toLowerCase()
   const hits: SettingSearchHit[] = []
+  let rowIndex = -1
 
   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
+    for (const row of rows) {
+      rowIndex++
       // 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}`

package/src/settings/sections/index.ts

@@ -44,8 +44,6 @@ export const ALL_SETTING_ROWS: readonly SettingRow[] = SETTING_SECTIONS.flatMap(
   Array.isArray(section.rows) ? section.rows : []
 )
 
-export const DEFAULT_SECTION_ID = SETTING_SECTIONS[0]?.id ?? 'about'
-
 export function getSection(sectionId: string): SettingSection | undefined {
   return SETTING_SECTIONS.find((section) => section.id === sectionId)
 }
@@ -70,18 +68,31 @@ export function sectionRowCount(
   return Array.isArray(section.rows) ? section.rows.length : section.rows(projects).length
 }
 
-/** Rows of the given section, or an empty list when the id is unknown. */
-export function getSectionRows(
-  sectionId: string,
-  projects: readonly ProjectRecord[]
-): readonly SettingRow[] {
-  const section = getSection(sectionId)
-  return section ? sectionRows(section, projects) : []
+/**
+ * How many rows the screen holds in total. The screen is one list, so this is
+ * what clamps its cursor — and like `sectionRowCount`, it counts without
+ * building, which is what keeps the reducer off the disk.
+ */
+export function totalRowCount(projects: readonly ProjectRecord[]): number {
+  let total = 0
+  for (const section of SETTING_SECTIONS) total += sectionRowCount(section, projects)
+  return total
 }
 
-export function getSectionRowCount(sectionId: string, projects: readonly ProjectRecord[]): number {
-  const section = getSection(sectionId)
-  return section ? sectionRowCount(section, projects) : 0
+/**
+ * The flat index of each section's first row, in screen order. What `}` and `{`
+ * jump between, and the reason they can: an empty section contributes no index,
+ * so the cursor never lands on a heading with nothing under it.
+ */
+export function sectionStartIndexes(projects: readonly ProjectRecord[]): number[] {
+  const starts: number[] = []
+  let index = 0
+  for (const section of SETTING_SECTIONS) {
+    const count = sectionRowCount(section, projects)
+    if (count > 0) starts.push(index)
+    index += count
+  }
+  return starts
 }
 
 /** The row with this id, dynamic ones included. */

package/src/state/actions.ts

@@ -219,9 +219,8 @@ export type UIAction =
 export type SettingsAction =
   | { type: 'enter-settings' }
   | { type: 'exit-settings' }
-  | { type: 'settings-focus-pane'; pane: 'nav' | 'rows' }
   | { type: 'settings-move-selection'; delta: -1 | 1 }
-  | { type: 'settings-select-section'; sectionId: string }
+  | { type: 'settings-jump-section'; delta: -1 | 1 }
   | { type: 'settings-select-row'; rowIndex: number }
   | { type: 'open-settings-search' }
   | { type: 'open-setting-text-modal'; settingId: string; label: string; value: string }

package/src/state/reducers/settings-state.ts

@@ -1,10 +1,10 @@
 import type { AppAction } from '../actions'
 import type { AppState, SettingsUIState } from '../types'
 
-import { DEFAULT_SECTION_ID, getSectionRowCount, SETTING_SECTIONS } from '../../settings/sections'
+import { sectionStartIndexes, totalRowCount } from '../../settings/sections'
 
 export function emptySettingsUI(): SettingsUIState {
-  return { pane: 'nav', rowIndex: 0, sectionId: DEFAULT_SECTION_ID }
+  return { rowIndex: 0 }
 }
 
 function clamp(value: number, max: number): number {
@@ -12,68 +12,46 @@ function clamp(value: number, max: number): number {
   return Math.max(0, Math.min(max, value))
 }
 
-function withSettings(state: AppState, patch: Partial<SettingsUIState>): AppState {
-  return { ...state, settings: { ...state.settings, ...patch } }
-}
-
-function moveSelection(state: AppState, delta: -1 | 1): AppState {
-  const { pane, rowIndex, sectionId } = state.settings
-
-  if (pane === 'nav') {
-    const index = SETTING_SECTIONS.findIndex((section) => section.id === sectionId)
-    const next = clamp((index === -1 ? 0 : index) + delta, SETTING_SECTIONS.length - 1)
-    const nextId = SETTING_SECTIONS[next]?.id
-    if (nextId == null || nextId === sectionId) return state
-    // A new section has its own rows, so the row cursor from the old one means
-    // nothing here.
-    return withSettings(state, { rowIndex: 0, sectionId: nextId })
+function withRowIndex(state: AppState, rowIndex: number): AppState {
+  return {
+    ...state,
+    settings: { ...state.settings, rowIndex: clamp(rowIndex, totalRowCount(state.projects) - 1) },
   }
+}
 
-  return withSettings(state, {
-    rowIndex: clamp(rowIndex + delta, getSectionRowCount(sectionId, state.projects) - 1),
-  })
+/**
+ * The first row of the next section down, or of the one the cursor is already
+ * inside when going up and it is not on its first row — the paragraph motion `}`
+ * and `{` are named after, rather than a plain "section ± 1" that would skip the
+ * heading you were standing under.
+ */
+function jumpSection(state: AppState, delta: -1 | 1): AppState {
+  const starts = sectionStartIndexes(state.projects)
+  const current = state.settings.rowIndex
+  const next =
+    delta === 1
+      ? starts.find((start) => start > current)
+      : starts.filter((start) => start < current).at(-1)
+  if (next === undefined) return state
+  return withRowIndex(state, next)
 }
 
 export function reduceSettingsState(state: AppState, action: AppAction): AppState | null {
   switch (action.type) {
     case 'enter-settings':
       if (state.focusMode === 'settings') return state
-      // The section is remembered across a close/open within the session; the
-      // cursor inside it is not — reopening lands you at the top of it.
-      return {
-        ...state,
-        focusMode: 'settings',
-        settings: { ...state.settings, pane: 'nav', rowIndex: 0 },
-      }
+      // Reopening lands at the top: the list is one column now, so the top of it
+      // is where the search and the first section both are.
+      return { ...state, focusMode: 'settings', settings: { ...state.settings, rowIndex: 0 } }
     case 'exit-settings':
       if (state.focusMode !== 'settings') return state
       return { ...state, focusMode: 'navigation' }
-    case 'settings-focus-pane': {
-      // A section with no rows has nothing to focus, so `l` stays put rather
-      // than parking the cursor in an empty column.
-      if (
-        action.pane === 'rows' &&
-        getSectionRowCount(state.settings.sectionId, state.projects) === 0
-      ) {
-        return state
-      }
-      return withSettings(state, { pane: action.pane })
-    }
     case 'settings-move-selection':
-      return moveSelection(state, action.delta)
-    case 'settings-select-section':
-      if (action.sectionId === state.settings.sectionId) {
-        return withSettings(state, { pane: 'nav' })
-      }
-      return withSettings(state, { pane: 'nav', rowIndex: 0, sectionId: action.sectionId })
+      return withRowIndex(state, state.settings.rowIndex + action.delta)
+    case 'settings-jump-section':
+      return jumpSection(state, action.delta)
     case 'settings-select-row':
-      return withSettings(state, {
-        pane: 'rows',
-        rowIndex: clamp(
-          action.rowIndex,
-          getSectionRowCount(state.settings.sectionId, state.projects) - 1
-        ),
-      })
+      return withRowIndex(state, action.rowIndex)
     default:
       return null
   }

package/src/state/types.ts

@@ -734,9 +734,11 @@ export const EMPTY_MULTI_REPO_STATE: MultiRepoState = { prefixes: {}, repos: []
  * two of them.
  */
 export interface SettingsUIState {
-  sectionId: string
-  /** Which of the two columns has the keyboard: the section list, or its rows. */
-  pane: 'nav' | 'rows'
+  /**
+   * Where the cursor is in the screen's one list, counted across every section.
+   * The sections are headings in that list, not a column you move into, so this
+   * is the whole of the screen's state.
+   */
   rowIndex: number
 }
 

package/src/ui/components/settings/row-value.tsx

@@ -5,6 +5,7 @@ import type { SettingRow, SettingValue } from '../../../settings/types'
 import { readRow, useSettingsStore } from '../../../settings/settings-store'
 import { useAppStore } from '../../../state/app-store'
 import { type ResolvedTuiTheme, useTheme } from '../../theme'
+import { truncate } from '../../truncate'
 
 /** Filled means on. Both are one cell wide in a Latin-width terminal. */
 const ON = '●'
@@ -51,11 +52,17 @@ export function describeValue(row: SettingRow, value: SettingValue): string {
   }
 }
 
+/**
+ * Text wears text tokens, the way it does on the stats screen — a value is not a
+ * status. The two exceptions earn it: a toggle whose colour *is* its state, and
+ * an action row, where the colour is the affordance saying it does something.
+ */
 function valueColor(row: SettingRow, value: SettingValue, t: ResolvedTuiTheme): string {
   // A toggle is read at a glance or not at all, so its state is the colour as much
   // as the glyph: lit when on, as quiet as the rest of the row when off.
   if (row.kind === 'toggle') return value === true ? t.success : t.textMuted
-  return row.kind === 'info' ? t.textMuted : t.primary
+  if (row.kind === 'action') return t.primary
+  return row.kind === 'info' ? t.textMuted : t.text
 }
 
 /**
@@ -66,9 +73,21 @@ function valueColor(row: SettingRow, value: SettingValue, t: ResolvedTuiTheme):
  * renders nothing. A parent subscribing to the whole store for every row in the
  * list would repaint it at the rate the terminals print.
  */
-export const RowValue = memo(function RowValue({ row }: { row: SettingRow }) {
+export const RowValue = memo(function RowValue({
+  maxWidth,
+  row,
+}: {
+  /** Cropped rather than wrapped: a row that grows a line shifts the list. */
+  maxWidth?: number
+  row: SettingRow
+}) {
   const t = useTheme()
   const values = useSettingsStore((s) => s.values)
   const value = useAppStore((s) => readRow(row, { state: s, values }))
-  return <text fg={valueColor(row, value, t)}>{formatValue(row, value)}</text>
+  const text = formatValue(row, value)
+  return (
+    <text fg={valueColor(row, value, t)} wrapMode="none">
+      {maxWidth === undefined ? text : truncate(text, maxWidth)}
+    </text>
+  )
 })

package/src/ui/components/settings/settings-footer.tsx

@@ -0,0 +1,170 @@
+import { memo, useCallback } from 'react'
+
+import type { SettingRow } from '../../../settings/types'
+
+import { readRow, storedRow, useSettingsStore } from '../../../settings/settings-store'
+import { useAppStore } from '../../../state/app-store'
+import { dispatchGlobal } from '../../../state/dispatch-ref'
+import { useTheme } from '../../theme'
+import { truncate } from '../../truncate'
+import { Rule } from '../stats/shared'
+import { describeValue } from './row-value'
+
+/**
+ * Everything the rows used to carry on a second line of their own, moved to the
+ * foot of the screen and shown for the selected row only.
+ *
+ * Three lines, always, whatever the row is: a footer that grows and shrinks
+ * moves the list above it, and a list that shifts while you walk down it is the
+ * thing this screen was rebuilt to stop doing.
+ */
+
+/**
+ * `[key, what it does]`, so the keys can wear the theme and the prose cannot.
+ *
+ * Cut to what works on the row you are standing on: `←/→` does nothing to a
+ * text field, and a hint for a key that does nothing is worse than no hint.
+ */
+function hintsFor(row: SettingRow | null): [string, string][] {
+  const hints: [string, string][] = []
+  if (row?.kind === 'number' || row?.kind === 'select' || row?.kind === 'toggle') {
+    hints.push(['←/→', 'adjust'])
+  }
+  if (row != null && row.kind !== 'info') {
+    hints.push(['↵', row.kind === 'number' || row.kind === 'text' ? 'type a value' : 'change'])
+  }
+  hints.push(['r', 'reset'], ['/', 'search'], ['} {', 'section'], ['esc', 'close'])
+  return hints
+}
+
+/**
+ * What the row itself does not say. Not its description — the row carries that
+ * under its own label now — but where its value comes from and when it takes
+ * effect, which belong to the row you are on rather than to the setting.
+ */
+function notesFor(row: SettingRow, fromConfigFile: boolean): string {
+  if (fromConfigFile) return 'set in aimux.config.ts — comes back on restart'
+  return storedRow(row)?.restart === true ? 'applies on restart' : ''
+}
+
+/**
+ * The options of a select, spelled out with the current one lit. The row can
+ * only show the one it is on, and stepping through the rest to find out what
+ * they are is not reading, it is guessing.
+ */
+function OptionStrip({ row }: { row: Extract<SettingRow, { kind: 'select' }> }) {
+  const t = useTheme()
+  const values = useSettingsStore((s) => s.values)
+  const current = useAppStore((s) => readRow(row, { state: s, values }))
+  return (
+    <box flexDirection="row" gap={1}>
+      {row.options.map((option) => (
+        <text
+          key={String(option.value)}
+          fg={option.value === current ? t.text : t.textMuted}
+          selectable={false}
+          wrapMode="none"
+        >
+          {option.value === current ? `[${option.label}]` : option.label}
+        </text>
+      ))}
+    </box>
+  )
+}
+
+/** What the second line says when the row is not one with options to list. */
+function rangeOf(row: SettingRow): string {
+  if (row.kind === 'number') return `${String(row.min)} – ${String(row.max)}`
+  if (row.kind === 'toggle') return 'on · off'
+  return ''
+}
+
+/**
+ * The whole of a value the row could only show the start of. A command or a
+ * path is the one kind of value that does not fit its column, and it is also
+ * the one you most need to read before changing it.
+ */
+function FullValue({ row }: { row: Extract<SettingRow, { kind: 'text' | 'action' | 'info' }> }) {
+  const t = useTheme()
+  const values = useSettingsStore((s) => s.values)
+  const value = useAppStore((s) => readRow(row, { state: s, values }))
+  return (
+    <text fg={t.textMuted} selectable={false} wrapMode="none">
+      {String(value)}
+    </text>
+  )
+}
+
+export const SettingsFooter = memo(function SettingsFooter({
+  pad,
+  row,
+  width,
+}: {
+  pad: number
+  row: SettingRow | null
+  width: number
+}) {
+  const t = useTheme()
+  const fromConfigFile = useSettingsStore((s) => (row ? s.fromConfigFile.has(row.id) : false))
+  const touched = useSettingsStore((s) => (row ? s.touched.has(row.id) : false))
+  const defaultValue = useSettingsStore((s) => (row ? s.defaults[row.id] : undefined))
+
+  const handleClose = useCallback(() => dispatchGlobal({ type: 'exit-settings' }), [])
+
+  const notes = row ? notesFor(row, fromConfigFile) : ''
+  // Only once the row has been changed — `r` is otherwise a key you press to
+  // find out what it does.
+  const resetHint =
+    row && touched && defaultValue !== undefined
+      ? `default: ${describeValue(row, defaultValue)}`
+      : null
+
+  return (
+    <box flexDirection="column" flexShrink={0} paddingLeft={pad} paddingRight={pad}>
+      <Rule width={width} />
+      <box width={width} flexDirection="row" flexShrink={0}>
+        <box flexGrow={1} flexShrink={1}>
+          <text fg={t.textMuted} selectable={false} wrapMode="none">
+            {truncate(notes, Math.max(0, width - (resetHint?.length ?? 0) - 2))}
+          </text>
+        </box>
+        {resetHint != null ? (
+          <text fg={t.textMuted} selectable={false} wrapMode="none">
+            {resetHint}
+          </text>
+        ) : null}
+      </box>
+      <box height={1} flexShrink={0} overflow="hidden">
+        {row?.kind === 'select' ? <OptionStrip row={row} /> : null}
+        {row?.kind === 'text' || row?.kind === 'action' || row?.kind === 'info' ? (
+          <FullValue row={row} />
+        ) : null}
+        {row?.kind === 'number' || row?.kind === 'toggle' ? (
+          <text fg={t.textMuted} selectable={false} wrapMode="none">
+            {rangeOf(row)}
+          </text>
+        ) : null}
+      </box>
+      {/* Clipped rather than squeezed: a row of hints allowed to shrink loses
+          the spaces *inside* the words first, and `↵change  -/+step` is worse
+          than the same line with its tail cut off on a narrow terminal. */}
+      <box width={width} flexDirection="row" flexShrink={0} gap={2} overflow="hidden">
+        {hintsFor(row).map(([key, what]) => (
+          <box key={key} flexDirection="row" flexShrink={0}>
+            <text
+              fg={t.primary}
+              selectable={false}
+              wrapMode="none"
+              onMouseDown={key === 'esc' ? handleClose : undefined}
+            >
+              {key}
+            </text>
+            <text fg={t.textMuted} selectable={false} wrapMode="none">
+              {` ${what}`}
+            </text>
+          </box>
+        ))}
+      </box>
+    </box>
+  )
+})

package/src/ui/components/settings/settings-row.tsx

@@ -2,53 +2,118 @@ import { memo } from 'react'
 
 import type { SettingRow } from '../../../settings/types'
 
-import { storedRow, useSettingsStore } from '../../../settings/settings-store'
+import { readRow, useSettingsStore } from '../../../settings/settings-store'
+import { useAppStore } from '../../../state/app-store'
 import { useTheme } from '../../theme'
+import { truncate } from '../../truncate'
 import { ListItem } from '../primitives/list-item'
-import { describeValue, RowValue } from './row-value'
+import { Bar } from '../stats/shared'
+import { RowValue } from './row-value'
 
-/** Where the value comes from, on the left, out of the value column's way. */
-const CONFIG_FILE_MARK = '*'
-const TOUCHED_MARK = '~'
+/**
+ * Where the value comes from, on the left, out of the value column's way. Both
+ * are legended by the headline row at the top of the screen, which counts them.
+ */
+export const CONFIG_FILE_MARK = '*'
+export const TOUCHED_MARK = '~'
+
+/** The cursor, the mark, their spaces, and the row's own padding either side. */
+const ROW_CHROME = 6
+/** The column every value ends on, and the least the widest of them needs. */
+const VALUE_WIDTH = 12
+/**
+ * Uncapped, unlike the stats bars, which stop at 32.
+ *
+ * That cap is there because those bars share a scale and get compared to each
+ * other, and comparing two lengths gets harder as they grow. These do not: each
+ * one is a position inside its own row's range, read on its own. So it runs to
+ * the value column and the row has no gap in the middle of it.
+ */
+const BAR_MAX = Infinity
+/**
+ * Every label there is fits in this, so nothing on the screen is cropped when
+ * the column is wide enough to give it — which is what the column layout is
+ * sized around. (`Auto-rename minimum words` is the longest at 25.)
+ */
+const LABEL_MAX = 28
 
 interface SettingsRowProps {
   row: SettingRow
   active: boolean
   index: number
+  /** The column this row stands in — it fills it, edge to edge. */
+  width: number
   onSelect: (index: number) => void
 }
 
+/**
+ * The gauge on a row that has a floor and a ceiling.
+ *
+ * A bar is honest here for the same reason it is honest on a quota and dishonest
+ * on a headline number: `min` and `max` are a real scale, so the fraction means
+ * something. It is measured from `min`, not from zero — a delay that runs 60s to
+ * 3600s sitting at 60 is at the bottom of its range, not at 2% of it.
+ */
+function RangeGauge({
+  row,
+  width,
+}: {
+  row: Extract<SettingRow, { kind: 'number' }>
+  width: number
+}) {
+  const t = useTheme()
+  const values = useSettingsStore((s) => s.values)
+  const value = useAppStore((s) => readRow(row, { state: s, values }))
+  const span = row.max - row.min
+  if (span <= 0) return null
+  return (
+    <Bar
+      color={t.primary}
+      max={span}
+      segments={width}
+      value={Math.max(0, (typeof value === 'number' ? value : row.min) - row.min)}
+    />
+  )
+}
+
+/**
+ * What it is, what it is set to, where that sits in its range, and what it does
+ * underneath. It can afford the second line because the screen shows one section
+ * at a time — fifty rows in one scroll could not, which is what made the old
+ * two-line row a wall rather than a paragraph.
+ *
+ * The same three-part geometry as a stats bar row: label on the left, the gauge
+ * in the middle, the column's right edge on the right. Every value on the screen
+ * therefore ends on one column, which is what makes a page of them read as a
+ * page rather than as rows that happen to sit above each other.
+ *
+ * Both columns at full strength, unlike a stats row, which mutes its label. On
+ * that screen the number is the content and the label only says which number it
+ * is; here you are scanning the labels to find the one you came for.
+ */
 export const SettingsRow = memo(function SettingsRow({
   active,
   index,
   onSelect,
   row,
+  width,
 }: SettingsRowProps) {
   const t = useTheme()
   const fromConfigFile = useSettingsStore((s) => s.fromConfigFile.has(row.id))
   const touched = useSettingsStore((s) => s.touched.has(row.id))
-  const defaultValue = useSettingsStore((s) => s.defaults[row.id])
-  const editable = row.kind !== 'info'
   // A blank when neither applies, never nothing: a marker that comes and goes
   // would shift the label of every row it is missing from.
   let mark = ' '
   if (fromConfigFile) mark = CONFIG_FILE_MARK
   else if (touched) mark = TOUCHED_MARK
 
-  // Always, never only on the focused row: a row that grows a line when you land
-  // on it shifts everything under it, so the list moves under the cursor the
-  // whole way down. A taller list that holds still reads better than a compact
-  // one that does not.
-  const notes: string[] = []
-  if (row.description != null && row.description !== '') notes.push(row.description)
-  if (fromConfigFile) notes.push('set in aimux.config.ts — comes back on restart')
-  else if (storedRow(row)?.restart === true) notes.push('applies on restart')
-  // Right-aligned on the same line rather than tacked onto the end of the
-  // description: it is about the row, not about what the setting does, and the
-  // value column above it is on that edge too. Only once the row has been
-  // changed — `r` is otherwise a key you press to find out what it does.
-  const resetHint =
-    touched && defaultValue !== undefined ? `r resets to ${describeValue(row, defaultValue)}` : null
+  // The label gets first call on the column and the gauge takes what is left,
+  // not the other way round: a bar two cells shorter still reads as the same
+  // proportion, where `Transparent bac…` and `Transparent bak…` do not read as
+  // different settings.
+  const inner = Math.max(12, width - ROW_CHROME)
+  const labelWidth = Math.max(10, Math.min(LABEL_MAX, inner - VALUE_WIDTH))
+  const barWidth = Math.min(BAR_MAX, inner - labelWidth - VALUE_WIDTH - 1)
 
   return (
     <ListItem
@@ -57,22 +122,33 @@ export const SettingsRow = memo(function SettingsRow({
       index={index}
       onClickIndex={onSelect}
       leading={<text fg={fromConfigFile ? t.warning : t.secondary}>{mark}</text>}
-      title={<text fg={editable ? t.text : t.textMuted}>{row.label}</text>}
       subtitle={
-        notes.length > 0 || resetHint != null ? (
-          <box flexDirection="row">
-            <box flexGrow={1} flexShrink={1}>
-              <text fg={t.textMuted}>{notes.join(' · ')}</text>
-            </box>
-            {resetHint != null ? (
-              <text fg={t.textMuted} wrapMode="none">
-                {resetHint}
-              </text>
-            ) : null}
+        row.description != null && row.description !== '' ? (
+          <box width={inner}>
+            <text fg={t.textMuted} selectable={false}>
+              {row.description}
+            </text>
           </box>
         ) : undefined
       }
-      trailing={<RowValue row={row} />}
+      title={
+        <box width={inner} flexDirection="row" flexShrink={0}>
+          <box width={labelWidth} flexShrink={0}>
+            <text fg={row.kind === 'info' ? t.textMuted : t.text} wrapMode="none">
+              {truncate(row.label, labelWidth - 1)}
+            </text>
+          </box>
+          {row.kind === 'number' && barWidth > 0 ? <RangeGauge row={row} width={barWidth} /> : null}
+          {/* Grows into whatever the label and the gauge left, so the value ends
+              on the column's edge whether or not the row has a gauge. */}
+          <box flexGrow={1} flexDirection="row" justifyContent="flex-end">
+            <RowValue
+              row={row}
+              maxWidth={inner - labelWidth - (barWidth > 0 && row.kind === 'number' ? barWidth : 0)}
+            />
+          </box>
+        </box>
+      }
     />
   )
 })

package/src/ui/components/settings/settings-search-bar.tsx

@@ -0,0 +1,61 @@
+import { memo, useCallback } from 'react'
+
+import { dispatchGlobal } from '../../../state/dispatch-ref'
+import { useTheme } from '../../theme'
+
+const SEARCH_GLYPH = '\u{2315}'
+
+/**
+ * The way into the search, drawn rather than remembered.
+ *
+ * `/` opened the picker long before this existed, and the footer said so — but a
+ * key you have to read a hint to know about is a key nobody presses. A field you
+ * can see and click is the only version of this that gets used, so the screen
+ * spends three rows on it and keeps it out of the scroll.
+ *
+ * It never holds text. Clicking it opens the picker, which is where the typing
+ * and the filtering actually happen; this is its handle.
+ */
+export const SettingsSearchBar = memo(function SettingsSearchBar({ width }: { width: number }) {
+  const t = useTheme()
+  const handleOpen = useCallback(() => {
+    dispatchGlobal({ type: 'open-settings-search' })
+  }, [])
+
+  // Filled, bordered in the active colour, and the prompt at full strength: it
+  // is the one control on a read-mostly screen, and a control drawn like the
+  // text around it is a control nobody sees.
+  return (
+    <box
+      border
+      borderStyle="rounded"
+      borderColor={t.borderActive}
+      backgroundColor={t.backgroundElement}
+      width={width}
+      flexShrink={0}
+      flexDirection="row"
+      paddingLeft={1}
+      paddingRight={1}
+      onMouseDown={handleOpen}
+    >
+      <text fg={t.primary} selectable={false} wrapMode="none">
+        {`${SEARCH_GLYPH} `}
+      </text>
+      <box flexGrow={1} flexShrink={1}>
+        <text fg={t.text} selectable={false} wrapMode="none">
+          Search every setting…
+        </text>
+      </box>
+      {/* The key drawn as the cap you press, not as a letter in a sentence. */}
+      <text fg={t.textMuted} selectable={false} wrapMode="none">
+        {'[ '}
+      </text>
+      <text fg={t.primary} selectable={false} wrapMode="none">
+        /
+      </text>
+      <text fg={t.textMuted} selectable={false} wrapMode="none">
+        {' ]'}
+      </text>
+    </box>
+  )
+})

package/src/ui/components/settings/settings-view.tsx

@@ -3,7 +3,8 @@ import type { ScrollBoxRenderable } from '@opentui/core'
 import { useTerminalDimensions } from '@opentui/react'
 import { memo, useCallback, useMemo, useRef } from 'react'
 
-import { getSectionRows, SETTING_SECTIONS } from '../../../settings/sections'
+import { filterSettingRows, type SettingSearchHit } from '../../../settings/search'
+import { getSection } from '../../../settings/sections'
 import { useSettingsStore } from '../../../settings/settings-store'
 import { useAppStore } from '../../../state/app-store'
 import { clampBarWidth } from '../../../state/bars'
@@ -11,84 +12,144 @@ import { dispatchGlobal, runSideEffectGlobal } from '../../../state/dispatch-ref
 import { useScrollActiveIntoView } from '../../hooks/use-scroll-active-into-view'
 import { useTheme } from '../../theme'
 import { ListItem } from '../primitives/list-item'
-import { SettingsRow } from './settings-row'
+import { Muted, Rule, Section, TileRow } from '../stats/shared'
+import { SettingsFooter } from './settings-footer'
+import { CONFIG_FILE_MARK, SettingsRow, TOUCHED_MARK } from './settings-row'
+import { SettingsSearchBar } from './settings-search-bar'
 
 const COLUMN_CONTENT_OPTIONS = { flexDirection: 'column' as const, gap: 0 }
 
+const SETTINGS_GLYPH = '\u{2699}'
+
+/** One padding column either side, the same inset the stats pages sit in. */
+const PAGE_PAD = 1
+
+/** A section and the rows it owns, each keeping the index the cursor holds. */
+interface Group {
+  sectionId: string
+  label: string
+  glyph: string
+  note: string
+  /** `[cursor index, hit]`, in screen order. */
+  rows: [number, SettingSearchHit][]
+}
+
+function groupBySection(hits: SettingSearchHit[]): Group[] {
+  const groups: Group[] = []
+  for (const [index, hit] of hits.entries()) {
+    const last = groups.at(-1)
+    if (last?.sectionId === hit.sectionId) {
+      last.rows.push([index, hit])
+      continue
+    }
+    const section = getSection(hit.sectionId)
+    groups.push({
+      glyph: section?.glyph ?? ' ',
+      label: hit.sectionLabel,
+      note: section?.description ?? '',
+      rows: [[index, hit]],
+      sectionId: hit.sectionId,
+    })
+  }
+  return groups
+}
+
 /**
- * Share of the window the settings themselves are allowed. Without a cap the
- * value sits on the far edge of a wide terminal, a hundred columns from the label
- * it belongs to, and the pair stops reading as a pair.
+ * The settings screen.
+ *
+ * Same shape as the stats screen — a nav column exactly where the left bar
+ * stands, so opening it does not shift the column under the cursor, and a
+ * bordered content pane where the terminal would be, showing one section at a
+ * time.
  *
- * A share of the window rather than a fixed column count, so it holds whatever
- * the window is; the floor is there for the narrow ones, where the pane is
- * smaller than the cap anyway and this stops binding.
+ * One section at a time, but still one cursor: the pane is a view of whatever
+ * section the cursor is standing in, so `j` off the end of a section simply
+ * lands in the next one and the pane follows. That is what lets a row afford
+ * three lines — the setting, what it does, and a gap — where fifty rows in one
+ * scroll could only afford one, and what keeps the nav column from being a
+ * place you have to move into and back out of.
  */
-const CONTENT_WIDTH_RATIO = 0.45
-const CONTENT_MIN_WIDTH = 56
-
 export const SettingsView = memo(function SettingsView() {
   const t = useTheme()
   // The cursor is all this component needs from the app state. Rows read their
   // own values, so nothing here re-renders at the rate the terminals print.
-  const settings = useAppStore((s) => s.settings)
-  // The section list stands exactly where the left bar stands, so opening the
-  // screen does not shift the column under the cursor. Its configured width, not
-  // `getBarWidth`: a hidden bar still says how wide the sidebar is.
-  const navWidth = useAppStore((s) => clampBarWidth(s.bars.left.width))
+  const rowIndex = useAppStore((s) => s.settings.rowIndex)
   // Which rows exist can depend on the projects — Setup has one per project — and
   // building a Setup row reads its script off disk. So the list is rebuilt when
-  // the section changes, when the projects change, and after any write; not on
-  // every render, which at the rate this store changes would mean reading files
-  // at the rate the terminals print.
+  // the projects change and after any write; not on every render, which at the
+  // rate this store changes would mean reading files at the rate the terminals
+  // print.
   const projects = useAppStore((s) => s.projects)
   const revision = useSettingsStore((s) => s.revision)
-  const rows = useMemo(
-    () => getSectionRows(settings.sectionId, projects),
+  const touchedCount = useSettingsStore((s) => s.touched.size)
+  const configCount = useSettingsStore((s) => s.fromConfigFile.size)
+  // The section list stands exactly where the left bar stands. Its configured
+  // width, not `getBarWidth`: a hidden bar still says how wide the sidebar is.
+  const navWidth = useAppStore((s) => clampBarWidth(s.bars.left.width))
+  const dimensions = useTerminalDimensions()
+  const hits = useMemo(
+    // No query: this is the whole list, and the same function the search filters
+    // with — so the index a hit carries is the index this cursor holds.
+    () => filterSettingRows(projects, null),
     // `revision` is an invalidation key, not an input: it says a value the builder
     // read from disk may have changed under it.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [settings.sectionId, projects, revision]
-  )
-  const dimensions = useTerminalDimensions()
-  const contentMaxWidth = Math.max(
-    CONTENT_MIN_WIDTH,
-    Math.round(dimensions.width * CONTENT_WIDTH_RATIO)
+    [projects, revision]
   )
+  const groups = useMemo(() => groupBySection(hits), [hits])
   const scrollRef = useRef<ScrollBoxRenderable | null>(null)
+  const selected = hits[rowIndex]
+  const current = groups.find((group) => group.sectionId === selected?.sectionId)
 
   useScrollActiveIntoView({
-    activeId: settings.pane === 'rows' ? (rows[settings.rowIndex]?.id ?? null) : null,
+    activeId: selected?.row.id ?? null,
     idPrefix: 'setting-row-',
     scrollRef,
     visible: true,
   })
 
-  const handleSectionClick = useCallback((index: number) => {
-    const sectionId = SETTING_SECTIONS[index]?.id
-    if (sectionId == null) return
-    dispatchGlobal({ sectionId, type: 'settings-select-section' })
-  }, [])
-
   // One click selects the row and changes it — a checkbox you have to select
   // first and then click again is not a checkbox.
-  const handleRowClick = useCallback((rowIndex: number) => {
-    dispatchGlobal({ rowIndex, type: 'settings-select-row' })
+  const handleRowClick = useCallback((index: number) => {
+    dispatchGlobal({ rowIndex: index, type: 'settings-select-row' })
     runSideEffectGlobal({ type: 'activate-settings-row' })
   }, [])
 
+  const handleSectionClick = useCallback(
+    (index: number) => {
+      const first = groups[index]?.rows[0]?.[0]
+      if (first === undefined) return
+      dispatchGlobal({ rowIndex: first, type: 'settings-select-row' })
+    },
+    [groups]
+  )
+
   const handleClose = useCallback(() => {
     dispatchGlobal({ type: 'exit-settings' })
   }, [])
 
-  const section = SETTING_SECTIONS.find((s) => s.id === settings.sectionId)
-  // The glyph rides with the label: a section that could not be found has
-  // neither, and the fallback title stands on its own.
-  const sectionTitle = section === undefined ? 'Settings' : `${section.glyph} ${section.label}`
-  const sectionNote = section?.description
+  // The headline row doubles as the legend for the two marks the rows wear —
+  // the counts are the only reason anyone would need to know what they mean.
+  const tiles = useMemo(
+    () =>
+      [
+        { glyph: SETTINGS_GLYPH, label: 'settings', value: String(hits.length) },
+        // A mark no row is wearing needs no legend, and a count of zero is not
+        // news — so the tile only exists while the mark does.
+        touchedCount === 0
+          ? null
+          : { glyph: TOUCHED_MARK, label: 'changed', value: String(touchedCount) },
+        configCount === 0
+          ? null
+          : { glyph: CONFIG_FILE_MARK, label: 'from config', value: String(configCount) },
+      ].filter((tile) => tile !== null),
+    [hits.length, touchedCount, configCount]
+  )
+
   // Same 1-cell seam the bar draws between itself and the terminal, so the two
   // views line up to the column.
   const navContentWidth = Math.max(1, navWidth - 1)
+  const usable = Math.max(24, dimensions.width - navWidth - 2 - PAGE_PAD * 2)
 
   return (
     <box flexDirection="row" flexGrow={1} overflow="hidden">
@@ -97,22 +158,23 @@ export const SettingsView = memo(function SettingsView() {
           <box paddingLeft={1} paddingRight={1}>
             <text fg={t.textMuted}>Settings</text>
           </box>
+          {/* A jump list, not a column you move into: it says which section the
+              cursor is in and takes it somewhere. Nothing here holds focus,
+              which is why the screen needs no notion of which pane has it. */}
           <box flexGrow={1} flexShrink={1} flexDirection="column" overflow="hidden">
-            {SETTING_SECTIONS.map((section, index) => (
+            {groups.map((group, index) => (
               <ListItem
-                key={section.id}
-                active={section.id === settings.sectionId}
+                key={group.sectionId}
+                active={group.sectionId === current?.sectionId}
                 index={index}
                 onClickIndex={handleSectionClick}
                 title={
-                  <text fg={section.id === settings.sectionId ? t.text : t.textMuted}>
-                    {`${section.glyph} ${section.label}`}
+                  <text fg={group.sectionId === current?.sectionId ? t.text : t.textMuted}>
+                    {`${group.glyph} ${group.label}`}
                   </text>
                 }
                 trailing={
-                  section.id === settings.sectionId && settings.pane === 'nav' ? (
-                    <text fg={t.primary}>›</text>
-                  ) : undefined
+                  group.sectionId === current?.sectionId ? <text fg={t.primary}>›</text> : undefined
                 }
               />
             ))}
@@ -126,46 +188,67 @@ export const SettingsView = memo(function SettingsView() {
         <box width={1} flexShrink={0} backgroundColor={t.border} />
       </box>
       {/* The pane the terminal would be in, with the same border — the content
-          keeps the inset it had, instead of jumping to the edge of the screen. */}
+          keeps the inset it had instead of jumping to the edge of the screen. */}
       <box
         border
-        borderColor={settings.pane === 'rows' ? t.borderActive : t.border}
-        title={sectionTitle}
+        borderColor={t.borderActive}
+        title={`${SETTINGS_GLYPH} Settings`}
         padding={0}
         flexDirection="column"
         flexGrow={1}
         backgroundColor={t.background}
       >
-        <box flexDirection="column" flexGrow={1} flexShrink={1} maxWidth={contentMaxWidth}>
-          {sectionNote != null && sectionNote !== '' ? (
-            <box flexShrink={0} paddingLeft={1} paddingRight={1}>
-              <text fg={t.textMuted}>{sectionNote}</text>
+        {/* Outside the scroll: the way to find a setting should not be a thing
+            you have to scroll back up to. */}
+        <box flexShrink={0} paddingLeft={PAGE_PAD} paddingRight={PAGE_PAD} paddingTop={1}>
+          <SettingsSearchBar width={usable} />
+        </box>
+        <scrollbox
+          ref={scrollRef}
+          scrollY
+          flexGrow={1}
+          flexShrink={1}
+          contentOptions={COLUMN_CONTENT_OPTIONS}
+        >
+          <box flexDirection="column" paddingLeft={PAGE_PAD} paddingRight={PAGE_PAD}>
+            <TileRow tiles={tiles} usable={usable} />
+            <box paddingTop={1} paddingBottom={1} flexShrink={0}>
+              <Rule width={usable} />
             </box>
-          ) : null}
-          <scrollbox
-            ref={scrollRef}
-            scrollY
-            flexGrow={1}
-            flexShrink={1}
-            contentOptions={COLUMN_CONTENT_OPTIONS}
-          >
-            {rows.length === 0 ? (
-              <box paddingLeft={1}>
-                <text fg={t.textMuted}>Nothing to configure here yet.</text>
-              </box>
+            {current === undefined ? (
+              <Muted>Nothing to configure here yet.</Muted>
             ) : (
-              rows.map((row, index) => (
-                <SettingsRow
-                  key={row.id}
-                  row={row}
-                  index={index}
-                  active={settings.pane === 'rows' && index === settings.rowIndex}
-                  onSelect={handleRowClick}
-                />
-              ))
+              <Section
+                glyph={current.glyph}
+                title={current.label}
+                // Pinned to the same right edge every note on the screen lands on.
+                note={String(current.rows.length)}
+                width={usable}
+              >
+                {current.note === '' ? null : (
+                  <box width={usable} paddingBottom={1}>
+                    <text fg={t.textMuted} selectable={false}>
+                      {current.note}
+                    </text>
+                  </box>
+                )}
+                <box flexDirection="column" gap={1}>
+                  {current.rows.map(([index, hit]) => (
+                    <SettingsRow
+                      key={hit.row.id}
+                      row={hit.row}
+                      index={index}
+                      active={index === rowIndex}
+                      onSelect={handleRowClick}
+                      width={usable}
+                    />
+                  ))}
+                </box>
+              </Section>
             )}
-          </scrollbox>
-        </box>
+          </box>
+        </scrollbox>
+        <SettingsFooter row={selected?.row ?? null} width={usable} pad={PAGE_PAD} />
       </box>
     </box>
   )

package/src/ui/components/stats/shared.tsx

@@ -6,7 +6,8 @@ import { truncate } from '../../truncate'
 import { type BarShape, buildChart, buildRuler, strideOf } from './chart'
 
 /**
- * The stats screen's building blocks.
+ * The building blocks of a full-screen view — the stats pages, and the settings
+ * screen, which is laid out against the same grid so the two read as one app.
  *
  * Every page is the same grid: a headline row of tiles, a rule, then sections
  * measured against the page's own width rather than against their content. A
@@ -418,6 +419,28 @@ export interface PageTile {
   value: string
 }
 
+/**
+ * The headline row: equal slots across the page's width, the last one taking
+ * whatever the division left over so the row ends on the page's right edge
+ * rather than a column or two short.
+ */
+export function TileRow({ tiles, usable }: { tiles: PageTile[]; usable: number }) {
+  const tileWidth = Math.floor(usable / Math.max(1, tiles.length))
+  return (
+    <box flexDirection="row" flexShrink={0}>
+      {tiles.map((tile, index) => (
+        <StatTile
+          key={tile.label}
+          glyph={tile.glyph}
+          label={tile.label}
+          value={tile.value}
+          width={index === tiles.length - 1 ? usable - tileWidth * (tiles.length - 1) : tileWidth}
+        />
+      ))}
+    </box>
+  )
+}
+
 /**
  * Every page's frame: the headline row, the rule under it, and the padding they
  * both sit in.
@@ -436,23 +459,9 @@ export function StatsPage({
   tiles: PageTile[]
   usable: number
 }) {
-  const tileWidth = Math.floor(usable / Math.max(1, tiles.length))
-
   return (
     <box flexDirection="column" paddingLeft={PAGE_PAD} paddingRight={PAGE_PAD}>
-      <box flexDirection="row" flexShrink={0}>
-        {tiles.map((tile, index) => (
-          <StatTile
-            key={tile.label}
-            glyph={tile.glyph}
-            label={tile.label}
-            value={tile.value}
-            // The last slot takes whatever the division left over, so the row
-            // ends on the page's right edge rather than a column or two short.
-            width={index === tiles.length - 1 ? usable - tileWidth * (tiles.length - 1) : tileWidth}
-          />
-        ))}
-      </box>
+      <TileRow tiles={tiles} usable={usable} />
       <box paddingTop={1} paddingBottom={1} flexShrink={0}>
         <Rule width={usable} />
       </box>