@brimveyn/aimux 1.3.0 → 1.4.0

package/src/terminal-manager/manager-client.ts

@@ -1,7 +1,12 @@
 import { EventEmitter } from 'node:events'
 import { connect, Socket } from 'node:net'
 
-import type { TerminalModeState, TerminalSnapshot, WorkspaceSnapshotV1 } from '../state/types'
+import type {
+  ScrollIntent,
+  TerminalModeState,
+  TerminalSnapshot,
+  WorkspaceSnapshotV1,
+} from '../state/types'
 
 import { getTerminalManagerSocketPath } from '../daemon/runtime-paths'
 import { logDebug } from '../debug/input-log'
@@ -298,18 +303,29 @@ export class TerminalManagerClient extends EventEmitter<ManagerClientEvents> {
     })
   }
 
-  resize(sessionId: string, cols: number, rows: number): Promise<void> {
+  resize(
+    sessionId: string,
+    cols: number,
+    rows: number,
+    intents?: Record<string, ScrollIntent>
+  ): Promise<void> {
     return this.sendExpectOk({
       id: crypto.randomUUID(),
-      payload: { cols, rows, sessionId },
+      payload: { cols, intents, rows, sessionId },
       type: 'resizeClient',
     })
   }
 
-  resizeTab(sessionId: string, tabId: string, cols: number, rows: number): Promise<void> {
+  resizeTab(
+    sessionId: string,
+    tabId: string,
+    cols: number,
+    rows: number,
+    intent?: ScrollIntent
+  ): Promise<void> {
     return this.sendExpectOk({
       id: crypto.randomUUID(),
-      payload: { cols, rows, sessionId, tabId },
+      payload: { cols, intent, rows, sessionId, tabId },
       type: 'resizeTab',
     })
   }
@@ -330,6 +346,14 @@ export class TerminalManagerClient extends EventEmitter<ManagerClientEvents> {
     })
   }
 
+  reapplyScrollIntent(sessionId: string, tabId: string, intent: ScrollIntent): Promise<void> {
+    return this.sendExpectOk({
+      id: crypto.randomUUID(),
+      payload: { intent, sessionId, tabId },
+      type: 'reapplyScrollIntent',
+    })
+  }
+
   setActiveTab(sessionId: string, tabId: string | null): Promise<void> {
     return this.sendExpectOk({
       id: crypto.randomUUID(),

package/src/terminal-manager/terminal-manager.ts

@@ -166,22 +166,29 @@ export async function runTerminalManager(): Promise<void> {
                 )
                 sendOk(socket, message.id)
                 break
-              case 'resizeClient':
+              case 'resizeClient': {
                 requireNegotiatedVersion(socket, negotiatedVersions)
+                const intentsRecord = message.payload.intents
+                const intentsMap = intentsRecord
+                  ? new Map(Object.entries(intentsRecord))
+                  : undefined
                 sessionManager.resize(
                   message.payload.sessionId,
                   message.payload.cols,
-                  message.payload.rows
+                  message.payload.rows,
+                  intentsMap
                 )
                 sendOk(socket, message.id)
                 break
+              }
               case 'resizeTab':
                 requireNegotiatedVersion(socket, negotiatedVersions)
                 sessionManager.resizeTab(
                   message.payload.sessionId,
                   message.payload.tabId,
                   message.payload.cols,
-                  message.payload.rows
+                  message.payload.rows,
+                  message.payload.intent
                 )
                 sendOk(socket, message.id)
                 break
@@ -199,6 +206,15 @@ export async function runTerminalManager(): Promise<void> {
                 sessionManager.scrollToBottom(message.payload.sessionId, message.payload.tabId)
                 sendOk(socket, message.id)
                 break
+              case 'reapplyScrollIntent':
+                requireNegotiatedVersion(socket, negotiatedVersions)
+                sessionManager.reapplyScrollIntent(
+                  message.payload.sessionId,
+                  message.payload.tabId,
+                  message.payload.intent
+                )
+                sendOk(socket, message.id)
+                break
               case 'setActiveTab':
                 requireNegotiatedVersion(socket, negotiatedVersions)
                 sessionManager.setActiveTab(message.payload.sessionId, message.payload.tabId)

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

@@ -1,5 +1,6 @@
 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'
@@ -50,13 +51,10 @@ export function CreateSessionModal({
 }: CreateSessionModalProps) {
   const dirActive = activeField === 'directory'
   const nameActive = activeField === 'name'
+  const help = useModalHelp('modal.create-session')
 
   return (
-    <ModalShell
-      title="Create session"
-      help="Tab switch field. Ctrl+n/p nav. Esc cancel."
-      width={uiTokens.modalWidth.xl}
-    >
+    <ModalShell title="Create session" help={help} 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,3 +1,4 @@
+import { useModalHelp } from '../keymap-context'
 import { theme } from '../theme'
 import { uiTokens } from '../ui-tokens'
 import { InputField } from './input-field'
@@ -13,13 +14,10 @@ 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="Tab switch · ←→ move cursor · Enter newline (body) · Ctrl+Enter commit · Esc cancel"
-      width={uiTokens.modalWidth.xl}
-    >
+    <ModalShell title="Commit" help={help} width={uiTokens.modalWidth.xl}>
       <box flexDirection="column">
         <text fg={titleActive ? theme.text : theme.textMuted}>Title</text>
         <InputField

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

@@ -1,79 +1,60 @@
+import type { ModeId } from '@brimveyn/aimux-config'
+
+import { describeBindings, groupDescribedBindings } from '../../input/keymap/describe-bindings'
+import { useKeymap, useModalHelp } from '../keymap-context'
 import { theme } from '../theme'
 import { uiTokens } from '../ui-tokens'
 import { ModalShell } from './modal-shell'
 
-const SECTIONS = [
-  {
-    bindings: [
-      ['j / k', 'Move between tabs'],
-      ['Shift+J / K', 'Reorder tabs'],
-      ['i', 'Focus terminal input'],
-      ['r', 'Rename tab'],
-      ['?', 'Show this help'],
-    ],
-    title: 'Navigation',
-  },
-  {
-    bindings: [
-      ['Ctrl+n', 'New tab'],
-      ['Ctrl+w', 'Close tab'],
-      ['Ctrl+r', 'Restart tab'],
-      ['Ctrl+g', 'Session picker'],
-      ['Ctrl+s', 'Snippet picker'],
-      ['Ctrl+t', 'Theme picker'],
-    ],
-    title: 'Tabs & Sessions',
-  },
-  {
-    bindings: [
-      ['Ctrl+b', 'Toggle sidebar'],
-      ['Ctrl+h / l', 'Resize sidebar'],
-      ['Shift+G', 'Toggle git panel'],
-      ['Ctrl+j / k', 'Resize git panel'],
-    ],
-    title: 'Sidebar',
-  },
-  {
-    bindings: [
-      ['Ctrl+z', 'Back to navigation'],
-      ['Ctrl+w', 'Enter layout mode'],
-      ['Ctrl+b', 'Toggle sidebar'],
-    ],
-    title: 'Terminal Input',
-  },
-  {
-    bindings: [
-      ['|', 'Split vertical'],
-      ['-', 'Split horizontal'],
-      ['h / j / k / l', 'Focus pane'],
-      ['Shift+H/J/K/L', 'Resize pane'],
-      ['q', 'Close pane'],
-      ['Esc', 'Cancel'],
-    ],
-    title: 'Layout Mode (Ctrl+w)',
-  },
-  {
-    bindings: [['Ctrl+c', 'Quit']],
-    title: 'General',
-  },
-] as const
+interface ModeSection {
+  modeId: ModeId
+  title: string
+}
+
+const SECTIONS: ModeSection[] = [
+  { modeId: 'navigation', title: 'Navigation' },
+  { modeId: 'terminal-input', title: 'Terminal input' },
+  { modeId: 'layout', title: 'Layout' },
+  { modeId: 'git-mode', title: 'Git mode' },
+]
+
+const KEYS_COLUMN_WIDTH = 22
 
 export function HelpModal() {
+  const config = useKeymap()
+  const help = useModalHelp('modal.help', 1)
+
   return (
-    <ModalShell title="Keybindings" help="Press Esc to close." width={uiTokens.modalWidth.lg}>
-      {SECTIONS.map((section) => (
-        <box key={section.title} flexDirection="column">
-          <text fg={theme.text}>{section.title}</text>
-          {section.bindings.map(([key, desc]) => (
-            <box key={key} flexDirection="row">
-              <box width={18}>
-                <text fg={theme.accentAlt}> {key}</text>
+    <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) => (
+              <box
+                key={`${section.modeId}-${group.group ?? 'root'}-${groupIdx}`}
+                flexDirection="column"
+              >
+                {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>
-              <text fg={theme.textMuted}>{desc}</text>
-            </box>
-          ))}
-        </box>
-      ))}
+            ))}
+          </box>
+        )
+      })}
     </ModalShell>
   )
 }

package/src/ui/components/list-item.tsx

@@ -3,24 +3,43 @@ import type { ReactNode } from 'react'
 import { theme } from '../theme'
 import { Surface } from './surface'
 
+export type ListItemDirection = 'row' | 'column'
+
 interface ListItemProps {
   active: boolean
+  direction?: ListItemDirection
   leading?: ReactNode
   subtitle?: ReactNode
   title: ReactNode
   trailing?: ReactNode
 }
 
-export function ListItem({ active, leading, subtitle, title, trailing }: ListItemProps) {
+export function ListItem({
+  active,
+  direction = 'column',
+  leading,
+  subtitle,
+  title,
+  trailing,
+}: ListItemProps) {
+  const isRow = direction === 'row'
   return (
-    <Surface tone={active ? 'selected' : 'elevated'} paddingLeft={1} paddingRight={1}>
+    <Surface
+      tone={active ? 'selected' : 'elevated'}
+      paddingLeft={isRow ? 2 : 1}
+      paddingRight={isRow ? 2 : 1}
+    >
       <box flexDirection="column">
         <box flexDirection="row">
-          <text fg={active ? theme.accent : theme.dim}>{active ? '›' : '·'}</text>
-          <text> </text>
+          {isRow ? null : (
+            <>
+              <text fg={active ? theme.accent : theme.dim}>{active ? '›' : '·'}</text>
+              <text> </text>
+            </>
+          )}
           {leading}
           {leading ? <text> </text> : null}
-          <box flexGrow={1}>{title}</box>
+          <box flexGrow={isRow ? 0 : 1}>{title}</box>
           {trailing ? <box>{trailing}</box> : null}
         </box>
         {subtitle ? <box paddingLeft={2}>{subtitle}</box> : null}

package/src/ui/components/new-tab-modal.tsx

@@ -1,4 +1,5 @@
 import { getAllAssistantOptions } from '../../pty/command-registry'
+import { useModalHelp } from '../keymap-context'
 import { theme } from '../theme'
 import { uiTokens } from '../ui-tokens'
 import { InputField } from './input-field'
@@ -14,17 +15,15 @@ interface NewTabModalProps {
 export function NewTabModal({ customCommands, editBuffer, selectedIndex }: NewTabModalProps) {
   const options = getAllAssistantOptions(customCommands)
   const selectedOption = options[selectedIndex]
+  const editingHelp = useModalHelp('modal.new-tab.command-edit')
+  const browsingHelp = useModalHelp('modal.new-tab')
+  const help =
+    editBuffer !== null
+      ? `Editing command for ${selectedOption?.label}. ${editingHelp}`
+      : browsingHelp
 
   return (
-    <ModalShell
-      title="New assistant tab"
-      help={
-        editBuffer !== null
-          ? `Editing command for ${selectedOption?.label}. Enter to confirm, Esc to cancel.`
-          : 'Use j/k or arrows, Enter to confirm, e to edit command, Esc to cancel.'
-      }
-      width={uiTokens.modalWidth.md}
-    >
+    <ModalShell title="New assistant tab" help={help} width={uiTokens.modalWidth.md}>
       {editBuffer !== null ? (
         <InputField active value={editBuffer} />
       ) : (

package/src/ui/components/pending-chord-overlay.tsx

@@ -0,0 +1,28 @@
+import { parseKeyNotation } from '../../input/keymap/key-chord'
+import { formatChord } from '../../input/keymap/key-format'
+import { useAppStore } from '../../state/app-store'
+import { useKeymap } from '../keymap-context'
+import { theme } from '../theme'
+import { Surface } from './surface'
+
+export function PendingChordOverlay() {
+  const pendingChords = useAppStore((s) => s.pendingChords)
+  const config = useKeymap()
+
+  if (!pendingChords || pendingChords.length === 0) return null
+
+  const leaderChord = parseKeyNotation(config.leader)[0]
+  const display = pendingChords.map((c) => formatChord(c, leaderChord)).join(' ')
+
+  return (
+    <box position="absolute" bottom={2} right={1}>
+      <Surface tone="elevated" paddingLeft={1} paddingRight={1}>
+        <box flexDirection="row">
+          <text fg={theme.textMuted}>pending: </text>
+          <text fg={theme.accent}>{display}</text>
+          <text fg={theme.textMuted}> …</text>
+        </box>
+      </Surface>
+    </box>
+  )
+}

package/src/ui/components/session-bar.tsx

@@ -0,0 +1,208 @@
+import type { BoxRenderable, MouseEvent as OtuiMouseEvent } from '@opentui/core'
+
+import { useMemo, useRef, useState } from 'react'
+
+import type { SessionRecord } from '../../state/types'
+
+import { useAppStore } from '../../state/app-store'
+import { dispatchGlobal, runSideEffectGlobal } from '../../state/dispatch-ref'
+import { useBusySpinner } from '../hooks/use-busy-spinner'
+import { moveIdToIdPosition, orderSessionsForDisplay } from '../session-ordering'
+import { theme } from '../theme'
+
+export function SessionBar() {
+  const sessions = useAppStore((s) => s.sessions)
+  const currentId = useAppStore((s) => s.currentSessionId)
+  const bar = useAppStore((s) => s.sessionBar)
+  const busyMap = useAppStore((s) => s.sessionsBusy)
+
+  const [draggingId, setDraggingId] = useState<string | null>(null)
+  const [dragOrder, setDragOrder] = useState<string[] | null>(null)
+  // Hysteresis: the id of the chip we most recently swapped with. While the
+  // cursor remains over that chip we refuse to swap back (prevents oscillation
+  // when a long chip's new bounds still cover the cursor after a swap).
+  const lastSwapWithRef = useRef<string | null>(null)
+  // Live bounds of each chip after render, keyed by session id.
+  const chipRefs = useRef(new Map<string, BoxRenderable>())
+
+  const ordered = useMemo(() => orderSessionsForDisplay(sessions), [sessions])
+  if (!bar.visible || ordered.length === 0) return null
+
+  const visibleSessions =
+    dragOrder !== null
+      ? dragOrder
+          .map((id) => ordered.find((s) => s.id === id))
+          .filter((s): s is SessionRecord => !!s)
+      : ordered
+
+  const baselineOrder = ordered.map((s) => s.id)
+
+  function setChipRef(id: string, ref: BoxRenderable | null): void {
+    if (ref) chipRefs.current.set(id, ref)
+    else chipRefs.current.delete(id)
+  }
+
+  function findChipAtX(x: number): string | null {
+    for (const [id, ref] of chipRefs.current) {
+      if (x >= ref.x && x < ref.x + ref.width) return id
+    }
+    return null
+  }
+
+  const handleMouseDown = (id: string) => {
+    setDraggingId(id)
+    setDragOrder(baselineOrder)
+    lastSwapWithRef.current = null
+  }
+
+  const handleMouseDrag = (event: OtuiMouseEvent) => {
+    if (!draggingId) return
+    const hit = findChipAtX(event.x)
+    if (hit === null) {
+      // Cursor left the bar entirely — allow the next hit to re-trigger a swap.
+      lastSwapWithRef.current = null
+      return
+    }
+    if (hit === draggingId) {
+      // Over the dragged chip itself — reset hysteresis so re-entering a
+      // neighbour can swap again.
+      lastSwapWithRef.current = null
+      return
+    }
+    if (hit === lastSwapWithRef.current) return
+    setDragOrder((prev) => (prev ? moveIdToIdPosition(prev, draggingId, hit) : prev))
+    lastSwapWithRef.current = hit
+  }
+
+  const commitDrop = () => {
+    const source = draggingId
+    const finalOrder = dragOrder
+    setDraggingId(null)
+    setDragOrder(null)
+    lastSwapWithRef.current = null
+
+    if (!source || !finalOrder) return
+
+    const changed = !arraysEqual(finalOrder, baselineOrder)
+    if (changed) {
+      dispatchGlobal({ orderedIds: finalOrder, type: 'reorder-sessions' })
+      return
+    }
+
+    // Drag did not change anything → treat as click, switch to that session.
+    const idx = baselineOrder.indexOf(source)
+    if (idx >= 0) {
+      runSideEffectGlobal({ index: idx + 1, type: 'switch-session-by-index' })
+    }
+  }
+
+  const cancelDrag = () => {
+    setDraggingId(null)
+    setDragOrder(null)
+    lastSwapWithRef.current = null
+  }
+
+  return (
+    <box
+      width="100%"
+      flexDirection="row"
+      paddingLeft={1}
+      paddingRight={1}
+      backgroundColor={theme.panelMuted}
+    >
+      {visibleSessions.map((session) => {
+        const displayIndex = baselineOrder.indexOf(session.id) + 1
+        return (
+          <SessionChip
+            key={session.id}
+            session={session}
+            index={displayIndex}
+            active={session.id === currentId}
+            busy={busyMap[session.id] ?? false}
+            dragging={draggingId === session.id}
+            onRef={(r) => setChipRef(session.id, r)}
+            onMouseDown={() => handleMouseDown(session.id)}
+            onMouseDrag={handleMouseDrag}
+            onMouseUp={commitDrop}
+            onMouseDragEnd={cancelDrag}
+          />
+        )
+      })}
+    </box>
+  )
+}
+
+function arraysEqual(a: string[], b: string[]): boolean {
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false
+  }
+  return true
+}
+
+interface SessionChipProps {
+  session: SessionRecord
+  index: number
+  active: boolean
+  busy: boolean
+  dragging: boolean
+  onRef: (ref: BoxRenderable | null) => void
+  onMouseDown: (event: OtuiMouseEvent) => void
+  onMouseDrag: (event: OtuiMouseEvent) => void
+  onMouseUp: (event: OtuiMouseEvent) => void
+  onMouseDragEnd: (event: OtuiMouseEvent) => void
+}
+
+function SessionChip({
+  active,
+  busy,
+  dragging,
+  index,
+  onMouseDown,
+  onMouseDrag,
+  onMouseDragEnd,
+  onMouseUp,
+  onRef,
+  session,
+}: SessionChipProps) {
+  const showSpinner = busy && !active
+  const spinner = useBusySpinner(showSpinner)
+  const indicator = showSpinner ? spinner : '●'
+  const indicatorColor = active || showSpinner ? theme.accent : theme.success
+  const labelColor = active ? theme.text : theme.textMuted
+  const bgColor = dragging || active ? theme.panelHighlight : undefined
+
+  return (
+    <box
+      ref={onRef}
+      flexDirection="row"
+      paddingLeft={1}
+      paddingRight={1}
+      backgroundColor={bgColor}
+      onMouseDown={(e) => {
+        e.preventDefault()
+        onMouseDown(e)
+      }}
+      onMouseDrag={(e) => {
+        onMouseDrag(e)
+      }}
+      onMouseUp={(e) => {
+        e.preventDefault()
+        onMouseUp(e)
+      }}
+      onMouseDragEnd={(e) => {
+        onMouseDragEnd(e)
+      }}
+    >
+      <text fg={indicatorColor} selectable={false}>
+        {indicator}{' '}
+      </text>
+      <text fg={labelColor} selectable={false}>
+        [{index}] {session.name}
+      </text>
+      <text fg={theme.dim} selectable={false}>
+        {' '}
+      </text>
+    </box>
+  )
+}

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

@@ -1,14 +1,12 @@
+import { useModalHelp } from '../keymap-context'
 import { uiTokens } from '../ui-tokens'
 import { InputField } from './input-field'
 import { ModalShell } from './modal-shell'
 
 export function SessionNameModal({ title, value }: { title: string; value: string }) {
+  const help = useModalHelp('modal.session-name')
   return (
-    <ModalShell
-      title={title}
-      help="Type a session name. Enter confirm, Esc cancel."
-      width={uiTokens.modalWidth.md}
-    >
+    <ModalShell title={title} help={help} width={uiTokens.modalWidth.md}>
       <InputField active value={value} />
     </ModalShell>
   )

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

@@ -1,6 +1,7 @@
 import type { SessionRecord } from '../../state/types'
 
 import { filterSessions } from '../../state/selectors'
+import { useModalHelp } from '../keymap-context'
 import { abbreviatePath } from '../path-format'
 import { theme } from '../theme'
 import { uiTokens } from '../ui-tokens'
@@ -47,11 +48,12 @@ export function SessionPickerModal({
   const hasFilter = !!filter
   const showFilteredEmptyState = filtered.length === 0 && sessions.length > 0
   const showInitialEmptyState = filtered.length === 0 && sessions.length === 0
+  const help = useModalHelp('modal.session-picker')
 
   return (
     <ModalShell
       title="Sessions"
-      help="j/k move, Enter resume, n new, r rename, d delete, / filter, Esc cancel."
+      help={help}
       width={uiTokens.modalWidth.lg}
       footer={<ModalFilterBar filter={filter} />}
     >

package/src/ui/components/snippet-editor-modal.tsx

@@ -1,3 +1,4 @@
+import { useModalHelp } from '../keymap-context'
 import { theme } from '../theme'
 import { uiTokens } from '../ui-tokens'
 import { InputField } from './input-field'
@@ -18,11 +19,12 @@ export function SnippetEditorModal({
 }: SnippetEditorModalProps) {
   const nameActive = activeField === 'name'
   const contentActive = activeField === 'content'
+  const help = useModalHelp('modal.snippet-editor')
 
   return (
     <ModalShell
       title={isEditing ? 'Edit snippet' : 'Create snippet'}
-      help="Tab switch field. Enter on content to save. Esc cancel."
+      help={help}
       width={uiTokens.modalWidth.xl}
     >
       <box flexDirection="column">