@brimveyn/aimux 1.4.0 → 1.5.0

package/src/state/types.ts

@@ -6,13 +6,7 @@ export type TabStatus = 'starting' | 'running' | 'disconnected' | 'exited' | 'er
 
 export type TabActivity = 'busy' | 'idle'
 
-export type FocusMode =
-  | 'navigation'
-  | 'terminal-input'
-  | 'modal'
-  | 'command-edit'
-  | 'layout'
-  | 'git'
+export type FocusMode = 'navigation' | 'terminal-input' | 'modal' | 'command-edit' | 'git'
 
 export type ModalType =
   | 'new-tab'
@@ -89,8 +83,6 @@ export interface WorkspaceSnapshotV1 {
   sidebar: {
     visible: boolean
     width: number
-    gitPanelVisible?: boolean
-    gitPanelRatio?: number
   }
   tabs: PersistedTabSnapshot[]
   layoutTree?: import('./layout-tree').LayoutNode
@@ -136,8 +128,24 @@ export interface SidebarState {
   width: number
   minWidth: number
   maxWidth: number
-  gitPanelVisible: boolean
-  gitPanelRatio: number
+}
+
+export type GitPaneMode = 'embedded' | 'pane'
+export type GitPanePosition = 'top' | 'bottom' | 'left' | 'right'
+
+export type GitPanePathConfig =
+  | { enabled: false }
+  | { enabled: true; pathFn?: (path: string) => string }
+
+export type GitPaneDiffCountConfig = { enabled: boolean }
+
+export interface GitPaneState {
+  visible: boolean
+  mode: GitPaneMode
+  position: GitPanePosition
+  ratio: number
+  path: GitPanePathConfig
+  diffCount: GitPaneDiffCountConfig
 }
 
 export type GitFileStatus = 'M' | 'A' | 'D' | 'R' | 'C' | 'U' | '?'
@@ -222,6 +230,7 @@ export interface ModalThemePicker extends ModalBase {
 
 export interface ModalHelp extends ModalBase {
   type: 'help'
+  entryCount: number
 }
 
 export interface ModalSplitPicker extends ModalBase {
@@ -300,6 +309,7 @@ export interface AppState {
   snippets: SnippetRecord[]
   focusMode: FocusMode
   sidebar: SidebarState
+  gitPane: GitPaneState
   modal: ModalState
   layout: LayoutState
   customCommands: Record<AssistantId, string>
@@ -332,6 +342,8 @@ export type ModalAction =
   | { type: 'open-snippet-picker' }
   | { type: 'open-snippet-editor'; snippetId?: string }
   | { type: 'begin-snippet-filter' }
+  | { type: 'begin-help-filter' }
+  | { type: 'set-help-entry-count'; count: number }
   | { type: 'open-theme-picker' }
   | { type: 'open-update-available-modal'; currentVersion: string; latestVersion: string }
 
@@ -407,8 +419,10 @@ export type UIAction =
   | { type: 'resize-sidebar'; delta: number }
   | { type: 'set-focus-mode'; focusMode: FocusMode }
   | { type: 'set-terminal-size'; cols: number; rows: number }
-  | { type: 'toggle-git-panel' }
-  | { type: 'resize-git-panel'; delta: number }
+  | { type: 'toggle-git-pane' }
+  | { type: 'resize-git-pane'; delta: number }
+  | { type: 'set-git-pane-mode'; mode: GitPaneMode }
+  | { type: 'set-git-pane-position'; position: GitPanePosition }
   | { type: 'set-pending-chords'; chords: string[] | null }
   | { type: 'toggle-session-bar' }
   | { type: 'set-session-bar-position'; position: SessionBarPosition }

package/src/state/validation.ts

@@ -114,8 +114,6 @@ export function isWorkspaceSnapshotV1(value: unknown): value is WorkspaceSnapsho
     isObjectRecord(value.sidebar) &&
     isBoolean(value.sidebar.visible) &&
     isFiniteNumber(value.sidebar.width) &&
-    (value.sidebar.gitPanelVisible === undefined || isBoolean(value.sidebar.gitPanelVisible)) &&
-    (value.sidebar.gitPanelRatio === undefined || isFiniteNumber(value.sidebar.gitPanelRatio)) &&
     Array.isArray(value.tabs) &&
     value.tabs.every(
       (tab) =>

package/src/state/workspace-save.ts

@@ -24,8 +24,12 @@ export function saveCurrentWorkspace(state: AppState): void {
   saveConfig({
     ...loadConfig(),
     customCommands: state.customCommands,
-    gitPanelRatio: state.sidebar.gitPanelRatio,
-    gitPanelVisible: state.sidebar.gitPanelVisible,
+    gitPane: {
+      mode: state.gitPane.mode,
+      position: state.gitPane.position,
+      ratio: state.gitPane.ratio,
+      visible: state.gitPane.visible,
+    },
     sessionBarPosition: state.sessionBar.position,
     sessionBarVisible: state.sessionBar.visible,
   })

package/src/ui/components/create-session-modal.tsx

@@ -1,6 +1,5 @@
 import type { DirectoryResult } from '../../state/types'
 
-import { useModalHelp } from '../keymap-context'
 import { abbreviatePath } from '../path-format'
 import { theme } from '../theme'
 import { uiTokens } from '../ui-tokens'
@@ -51,10 +50,13 @@ export function CreateSessionModal({
 }: CreateSessionModalProps) {
   const dirActive = activeField === 'directory'
   const nameActive = activeField === 'name'
-  const help = useModalHelp('modal.create-session')
 
   return (
-    <ModalShell title="Create session" help={help} width={uiTokens.modalWidth.xl}>
+    <ModalShell
+      title="Create session"
+      keybindsModeId="modal.create-session"
+      width={uiTokens.modalWidth.xl}
+    >
       <box flexDirection="column">
         <text fg={dirActive ? theme.text : theme.textMuted}>Search projects</text>
         <InputField

package/src/ui/components/git-commit-modal.tsx

@@ -1,4 +1,3 @@
-import { useModalHelp } from '../keymap-context'
 import { theme } from '../theme'
 import { uiTokens } from '../ui-tokens'
 import { InputField } from './input-field'
@@ -14,10 +13,9 @@ interface GitCommitModalProps {
 export function GitCommitModal({ activeField, body, cursorPos, title }: GitCommitModalProps) {
   const titleActive = activeField === 'title'
   const bodyActive = activeField === 'body'
-  const help = useModalHelp('modal.git-commit')
 
   return (
-    <ModalShell title="Commit" help={help} width={uiTokens.modalWidth.xl}>
+    <ModalShell title="Commit" keybindsModeId="modal.git-commit" width={uiTokens.modalWidth.xl}>
       <box flexDirection="column">
         <text fg={titleActive ? theme.text : theme.textMuted}>Title</text>
         <InputField

package/src/ui/components/git-pane-widget.tsx

@@ -0,0 +1,46 @@
+import { memo, useRef } from 'react'
+
+import type { GitPanelState } from '../../state/types'
+
+import { useGitPanelPolling } from '../../git/git-poller'
+import { useAppStore } from '../../state/app-store'
+import { GitPanel } from './git-panel'
+
+interface GitPaneWidgetProps {
+  pollingEnabled: boolean
+}
+
+export const GitPaneWidget = memo(function GitPaneWidget({ pollingEnabled }: GitPaneWidgetProps) {
+  const gitPanel = useAppStore((s) => s.gitPanel)
+  const pathConfig = useAppStore((s) => s.gitPane.path)
+  const diffCountConfig = useAppStore((s) => s.gitPane.diffCount)
+  const currentSessionId = useAppStore((s) => s.currentSessionId)
+  const sessions = useAppStore((s) => s.sessions)
+  const currentSession = currentSessionId
+    ? sessions.find((s) => s.id === currentSessionId)
+    : undefined
+  const projectPath = currentSession?.projectPath
+
+  useGitPanelPolling({ enabled: pollingEnabled, projectPath })
+
+  const lastGoodRef = useRef<GitPanelState | null>(null)
+  const prevProjectPathRef = useRef(projectPath)
+  if (prevProjectPathRef.current !== projectPath) {
+    prevProjectPathRef.current = projectPath
+    lastGoodRef.current = null
+  }
+  const isGood = gitPanel.error === null && gitPanel.branch !== null
+  if (isGood) {
+    lastGoodRef.current = gitPanel
+  }
+  const display = lastGoodRef.current ?? gitPanel
+
+  return (
+    <GitPanel
+      diffCountConfig={diffCountConfig}
+      gitPanel={display}
+      pathConfig={pathConfig}
+      projectPath={projectPath}
+    />
+  )
+})

package/src/ui/components/git-panel.tsx

@@ -1,6 +1,12 @@
 import { memo, type ReactNode, useMemo } from 'react'
 
-import type { GitFileEntry, GitFileSection, GitPanelState } from '../../state/types'
+import type {
+  GitFileEntry,
+  GitFileSection,
+  GitPaneDiffCountConfig,
+  GitPanelState,
+  GitPanePathConfig,
+} from '../../state/types'
 
 import { theme } from '../theme'
 
@@ -8,6 +14,8 @@ interface GitPanelProps {
   gitPanel: GitPanelState
   projectPath: string | undefined
   selectedFileKey?: string | null
+  pathConfig?: GitPanePathConfig
+  diffCountConfig?: GitPaneDiffCountConfig
 }
 
 export function fileKey(file: Pick<GitFileEntry, 'path' | 'section'>): string {
@@ -69,36 +77,69 @@ function stripTrailingSlash(prefix: string): string {
   return prefix.endsWith('/') ? prefix.slice(0, -1) : prefix
 }
 
-function renderPath(file: GitFileEntry): ReactNode {
-  const { basename, prefix } = splitPath(file.path)
+function renderPath(file: GitFileEntry, pathConfig: GitPanePathConfig): ReactNode {
+  const showDir = pathConfig.enabled
+  const transform = pathConfig.enabled ? pathConfig.pathFn : undefined
+  const displayPath = transform ? transform(file.path) : file.path
+  const { basename, prefix } = splitPath(displayPath)
   const dir = stripTrailingSlash(prefix)
   if (file.renamedFrom) {
-    const renamed = splitPath(file.renamedFrom)
+    const renamedDisplay = transform ? transform(file.renamedFrom) : file.renamedFrom
+    const renamed = splitPath(renamedDisplay)
     const renamedDir = stripTrailingSlash(renamed.prefix)
     return (
       <text wrapMode="none">
         <span fg={theme.text}>{renamed.basename}</span>
-        {renamedDir ? <span fg={theme.textMuted}> {renamedDir}</span> : null}
+        {showDir && renamedDir ? <span fg={theme.textMuted}> {renamedDir}</span> : null}
         <span fg={theme.textMuted}> → </span>
         <span fg={theme.text}>{basename}</span>
-        {dir ? <span fg={theme.textMuted}> {dir}</span> : null}
+        {showDir && dir ? <span fg={theme.textMuted}> {dir}</span> : null}
       </text>
     )
   }
   return (
     <text wrapMode="none">
       <span fg={theme.text}>{basename}</span>
-      {dir ? <span fg={theme.textMuted}> {dir}</span> : null}
+      {showDir && dir ? <span fg={theme.textMuted}> {dir}</span> : null}
     </text>
   )
 }
 
+function renderDiffCount(
+  file: GitFileEntry,
+  addedW: number,
+  removedW: number,
+  bg: string | undefined,
+  diffCountConfig: GitPaneDiffCountConfig,
+  hasNumstat: boolean
+): ReactNode {
+  if (!diffCountConfig.enabled) return null
+  if (!hasNumstat) {
+    return (
+      <text fg={theme.textMuted} bg={bg} flexShrink={0}>
+        —
+      </text>
+    )
+  }
+  return (
+    <box flexDirection="row" flexShrink={0}>
+      <text fg={theme.success} bg={bg}>{`+${padRight(file.added, addedW)}`}</text>
+      <text fg={theme.dim} bg={bg}>
+        {' '}
+      </text>
+      <text fg={theme.danger} bg={bg}>{`−${padRight(file.removed, removedW)}`}</text>
+    </box>
+  )
+}
+
 function renderFileRow(
   file: GitFileEntry,
   key: string,
   addedW: number,
   removedW: number,
-  isSelected: boolean
+  isSelected: boolean,
+  pathConfig: GitPanePathConfig,
+  diffCountConfig: GitPaneDiffCountConfig
 ): ReactNode {
   const hasNumstat = file.added !== null || file.removed !== null
   const bg = isSelected ? theme.panelHighlight : undefined
@@ -108,21 +149,9 @@ function renderFileRow(
         <strong>{displayStatus(file)}</strong>
       </text>
       <box flexGrow={1} overflow="hidden">
-        {renderPath(file)}
+        {renderPath(file, pathConfig)}
       </box>
-      {hasNumstat ? (
-        <box flexDirection="row" flexShrink={0}>
-          <text fg={theme.success} bg={bg}>{`+${padRight(file.added, addedW)}`}</text>
-          <text fg={theme.dim} bg={bg}>
-            {' '}
-          </text>
-          <text fg={theme.danger} bg={bg}>{`−${padRight(file.removed, removedW)}`}</text>
-        </box>
-      ) : (
-        <text fg={theme.textMuted} bg={bg} flexShrink={0}>
-          —
-        </text>
-      )}
+      {renderDiffCount(file, addedW, removedW, bg, diffCountConfig, hasNumstat)}
     </box>
   )
 }
@@ -133,7 +162,9 @@ function renderSection(
   files: GitFileEntry[],
   addedW: number,
   removedW: number,
-  selectedFileKey: string | null | undefined
+  selectedFileKey: string | null | undefined,
+  pathConfig: GitPanePathConfig,
+  diffCountConfig: GitPaneDiffCountConfig
 ): ReactNode {
   if (files.length === 0) return null
   return (
@@ -149,7 +180,9 @@ function renderSection(
           `${section}-${i}`,
           addedW,
           removedW,
-          !!selectedFileKey && fileKey(file) === selectedFileKey
+          !!selectedFileKey && fileKey(file) === selectedFileKey,
+          pathConfig,
+          diffCountConfig
         )
       )}
     </box>
@@ -190,8 +223,13 @@ function computeStatusPlaceholder(
   return null
 }
 
+const DEFAULT_PATH_CONFIG: GitPanePathConfig = { enabled: true }
+const DEFAULT_DIFF_COUNT_CONFIG: GitPaneDiffCountConfig = { enabled: true }
+
 export const GitPanel = memo(function GitPanel({
+  diffCountConfig = DEFAULT_DIFF_COUNT_CONFIG,
   gitPanel,
+  pathConfig = DEFAULT_PATH_CONFIG,
   projectPath,
   selectedFileKey,
 }: GitPanelProps) {
@@ -220,7 +258,16 @@ export const GitPanel = memo(function GitPanel({
           contentOptions={{ flexDirection: 'column', gap: 0 }}
         >
           {SECTION_ORDER.map((s) =>
-            renderSection(s.key, s.title, groups[s.key], addedW, removedW, selectedFileKey)
+            renderSection(
+              s.key,
+              s.title,
+              groups[s.key],
+              addedW,
+              removedW,
+              selectedFileKey,
+              pathConfig,
+              diffCountConfig
+            )
           )}
         </scrollbox>
       )}

package/src/ui/components/help-modal.tsx

@@ -1,60 +1,174 @@
-import type { ModeId } from '@brimveyn/aimux-config'
+import { useTerminalDimensions } from '@opentui/react'
+import { useLayoutEffect, useMemo, useRef } from 'react'
 
-import { describeBindings, groupDescribedBindings } from '../../input/keymap/describe-bindings'
-import { useKeymap, useModalHelp } from '../keymap-context'
+import { collectHelpEntries, type HelpEntry } from '../../input/keymap/help-entries'
+import { dispatchGlobal } from '../../state/dispatch-ref'
+import { useKeymap } from '../keymap-context'
 import { theme } from '../theme'
 import { uiTokens } from '../ui-tokens'
+import { ModalFilterBar } from './modal-filter-bar'
 import { ModalShell } from './modal-shell'
 
-interface ModeSection {
-  modeId: ModeId
-  title: string
+interface HelpModalProps {
+  filter: string | null
+  selectedIndex: number
 }
 
-const SECTIONS: ModeSection[] = [
-  { modeId: 'navigation', title: 'Navigation' },
-  { modeId: 'terminal-input', title: 'Terminal input' },
-  { modeId: 'layout', title: 'Layout' },
-  { modeId: 'git-mode', title: 'Git mode' },
-]
+function matchesFilter(entry: HelpEntry, needle: string): boolean {
+  if (!needle) return true
+  const lower = needle.toLowerCase()
+  return (
+    (entry.description?.toLowerCase().includes(lower) ?? false) ||
+    entry.modeLabel.toLowerCase().includes(lower) ||
+    entry.keysDisplay.toLowerCase().includes(lower) ||
+    (entry.group?.toLowerCase().includes(lower) ?? false)
+  )
+}
+
+type Row =
+  | { kind: 'header'; label: string }
+  | { kind: 'entry'; entry: HelpEntry; entryIndex: number }
 
-const KEYS_COLUMN_WIDTH = 22
+function buildRows(entries: HelpEntry[]): Row[] {
+  const rows: Row[] = []
+  let lastLabel: string | null = null
+  for (let entryIndex = 0; entryIndex < entries.length; entryIndex++) {
+    const entry = entries[entryIndex]
+    if (!entry) continue
+    if (entry.modeLabel !== lastLabel) {
+      rows.push({ kind: 'header', label: entry.modeLabel })
+      lastLabel = entry.modeLabel
+    }
+    rows.push({ entry, entryIndex, kind: 'entry' })
+  }
+  return rows
+}
+
+const KEYS_COLUMN_WIDTH = 24
+const VIEWPORT_HEIGHT_RATIO = 0.6
+const MODAL_CHROME_ROWS = 6
+
+function clampSelection(index: number, count: number): number {
+  if (count === 0) return 0
+  return Math.max(0, Math.min(count - 1, index))
+}
 
-export function HelpModal() {
+/**
+ * Pick a window start that (a) keeps the selected row on screen and
+ * (b) only scrolls when the selection leaves the margin — avoids jumpy
+ * recentering on every keypress.
+ */
+function computeWindowStart(
+  prevStart: number,
+  selectedRowIndex: number,
+  total: number,
+  windowSize: number
+): number {
+  if (total <= windowSize) return 0
+  const margin = 1
+  const maxStart = total - windowSize
+  let start = Math.max(0, Math.min(maxStart, prevStart))
+  const topThreshold = start + margin
+  const bottomThreshold = start + windowSize - 1 - margin
+  if (selectedRowIndex < topThreshold) {
+    start = Math.max(0, selectedRowIndex - margin)
+  } else if (selectedRowIndex > bottomThreshold) {
+    start = Math.min(maxStart, selectedRowIndex - windowSize + 1 + margin)
+  }
+  return start
+}
+
+export function HelpModal({ filter, selectedIndex }: HelpModalProps) {
   const config = useKeymap()
-  const help = useModalHelp('modal.help', 1)
+  const dimensions = useTerminalDimensions()
+  const allEntries = useMemo(() => collectHelpEntries(config), [config])
+  const filtered = useMemo(
+    () => allEntries.filter((e) => matchesFilter(e, filter ?? '')),
+    [allEntries, filter]
+  )
+  const rows = useMemo(() => buildRows(filtered), [filtered])
+
+  useLayoutEffect(() => {
+    dispatchGlobal({ count: filtered.length, type: 'set-help-entry-count' })
+  }, [filtered.length])
+
+  const effectiveIndex = clampSelection(selectedIndex, filtered.length)
+  const selectedRowIndex = Math.max(
+    0,
+    rows.findIndex((r) => r.kind === 'entry' && r.entryIndex === effectiveIndex)
+  )
+  const maxHeight = Math.max(6, Math.floor(dimensions.height * VIEWPORT_HEIGHT_RATIO))
+  const listHeight = Math.max(1, maxHeight - MODAL_CHROME_ROWS)
+
+  const prevStartRef = useRef(0)
+  const prevFilterRef = useRef<string | null>(filter)
+  // Reset scroll when filter changes; selection goes back to index 0.
+  if (prevFilterRef.current !== filter) {
+    prevFilterRef.current = filter
+    prevStartRef.current = 0
+  }
+  const start = computeWindowStart(prevStartRef.current, selectedRowIndex, rows.length, listHeight)
+  prevStartRef.current = start
+  const visible = rows.slice(start, start + listHeight)
 
   return (
-    <ModalShell title="Keybindings" help={help} width={uiTokens.modalWidth.lg}>
-      {SECTIONS.map((section) => {
-        const bindings = describeBindings(config, section.modeId, {
-          dedupeByDescription: true,
-          withDescriptionOnly: true,
-        })
-        if (bindings.length === 0) return null
-        const groups = groupDescribedBindings(bindings)
-        return (
-          <box key={section.modeId} flexDirection="column">
-            <text fg={theme.text}>{section.title}</text>
-            {groups.map((group, groupIdx) => (
+    <ModalShell
+      title="Keybindings"
+      keybindsModeId="modal.help"
+      width={uiTokens.modalWidth.lg}
+      footer={
+        <box flexDirection="column" gap={0}>
+          <text fg={theme.dim}>
+            {filtered.length === 0
+              ? ''
+              : ` ${effectiveIndex + 1} / ${filtered.length}${filter ? '' : ' — type / to filter'}`}
+          </text>
+          <ModalFilterBar filter={filter} />
+        </box>
+      }
+    >
+      {filtered.length === 0 ? (
+        <text fg={theme.textMuted}>
+          {filter ? 'No matching bindings.' : 'No bindings registered.'}
+        </text>
+      ) : (
+        <box height={listHeight} flexDirection="column" overflow="hidden">
+          {visible.map((row, i) => {
+            const rowIndex = start + i
+            if (row.kind === 'header') {
+              return (
+                <box key={`h-${rowIndex}`} paddingLeft={1} paddingTop={i === 0 ? 0 : 1}>
+                  <text fg={theme.warning} wrapMode="none">
+                    <strong>{row.label}</strong>
+                  </text>
+                </box>
+              )
+            }
+            const active = row.entryIndex === effectiveIndex
+            const bg = active ? theme.panelHighlight : undefined
+            return (
               <box
-                key={`${section.modeId}-${group.group ?? 'root'}-${groupIdx}`}
-                flexDirection="column"
+                key={`e-${rowIndex}`}
+                flexDirection="row"
+                paddingLeft={2}
+                paddingRight={1}
+                backgroundColor={bg}
               >
-                {group.group ? <text fg={theme.textMuted}> {group.group}</text> : null}
-                {group.bindings.map((binding) => (
-                  <box key={`${binding.keys}-${binding.description}`} flexDirection="row">
-                    <box width={KEYS_COLUMN_WIDTH}>
-                      <text fg={theme.accentAlt}> {binding.keysDisplay}</text>
-                    </box>
-                    <text fg={theme.textMuted}>{binding.description ?? ''}</text>
-                  </box>
-                ))}
+                <box width={KEYS_COLUMN_WIDTH} flexShrink={0}>
+                  <text fg={active ? theme.accent : theme.accentAlt} bg={bg} wrapMode="none">
+                    {row.entry.keysDisplay}
+                  </text>
+                </box>
+                <box flexGrow={1} overflow="hidden">
+                  <text fg={active ? theme.text : theme.textMuted} bg={bg} wrapMode="none">
+                    {row.entry.description ?? ''}
+                  </text>
+                </box>
               </box>
-            ))}
-          </box>
-        )
-      })}
+            )
+          })}
+        </box>
+      )}
     </ModalShell>
   )
 }

package/src/ui/components/modal-keybinds-overlay.tsx

@@ -0,0 +1,39 @@
+import type { ModeId } from '@brimveyn/aimux-config'
+
+import { describeBindings } from '../../input/keymap/describe-bindings'
+import { useKeymap } from '../keymap-context'
+import { theme } from '../theme'
+import { Surface } from './surface'
+
+const KEYS_COLUMN_WIDTH = 12
+
+interface ModalKeybindsOverlayProps {
+  modeId: ModeId
+  limit?: number
+}
+
+export function ModalKeybindsOverlay({ limit, modeId }: ModalKeybindsOverlayProps) {
+  const config = useKeymap()
+  const bindings = describeBindings(config, modeId, {
+    dedupeByDescription: true,
+    withDescriptionOnly: true,
+  })
+
+  if (bindings.length === 0) return null
+  const entries = typeof limit === 'number' ? bindings.slice(0, limit) : bindings
+
+  return (
+    <box position="absolute" bottom={3} right={5}>
+      <Surface tone="elevated" paddingLeft={2} paddingRight={2} paddingTop={1} paddingBottom={1}>
+        {entries.map((binding) => (
+          <box key={`${binding.keys}-${binding.description}`} flexDirection="row">
+            <box width={KEYS_COLUMN_WIDTH}>
+              <text fg={theme.accentAlt}>{binding.keysDisplay}</text>
+            </box>
+            <text fg={theme.textMuted}>{binding.description ?? ''}</text>
+          </box>
+        ))}
+      </Surface>
+    </box>
+  )
+}

package/src/ui/components/modal-shell.tsx

@@ -1,18 +1,29 @@
+import type { ModeId } from '@brimveyn/aimux-config'
 import type { ReactNode } from 'react'
 
 import { theme } from '../theme'
+import { ModalKeybindsOverlay } from './modal-keybinds-overlay'
 import { Surface } from './surface'
 
 interface ModalShellProps {
   children: ReactNode
   footer?: ReactNode
   listGap?: number
-  help?: string
+  subtitle?: string
+  keybindsModeId?: ModeId
   title: string
   width: number | `${number}%`
 }
 
-export function ModalShell({ children, footer, help, listGap = 1, title, width }: ModalShellProps) {
+export function ModalShell({
+  children,
+  footer,
+  keybindsModeId,
+  listGap = 1,
+  subtitle,
+  title,
+  width,
+}: ModalShellProps) {
   return (
     <box
       position="absolute"
@@ -36,12 +47,13 @@ export function ModalShell({ children, footer, help, listGap = 1, title, width }
         <box width="100%" flexDirection="column" gap={listGap}>
           <box flexDirection="column">
             <text fg={theme.accentAlt}>{title}</text>
-            {help ? <text fg={theme.textMuted}>{help}</text> : null}
+            {subtitle ? <text fg={theme.textMuted}>{subtitle}</text> : null}
           </box>
           {children}
           {footer ? <box>{footer}</box> : null}
         </box>
       </Surface>
+      {keybindsModeId ? <ModalKeybindsOverlay modeId={keybindsModeId} /> : null}
     </box>
   )
 }