@brimveyn/aimux 1.3.0 → 1.4.0

package/src/daemon/daemon.ts

@@ -256,7 +256,12 @@ export async function runDaemon(): Promise<void> {
                 case 'resizeClient': {
                   const sessionId = requireSession(socket, attachedSessions)
                   requireNegotiatedVersion(socket, negotiatedVersions)
-                  await manager.resize(sessionId, message.payload.cols, message.payload.rows)
+                  await manager.resize(
+                    sessionId,
+                    message.payload.cols,
+                    message.payload.rows,
+                    message.payload.intents
+                  )
                   sendOk(socket, message.id)
                   break
                 }
@@ -267,7 +272,8 @@ export async function runDaemon(): Promise<void> {
                     sessionId,
                     message.payload.tabId,
                     message.payload.cols,
-                    message.payload.rows
+                    message.payload.rows,
+                    message.payload.intent
                   )
                   sendOk(socket, message.id)
                   break
@@ -286,6 +292,17 @@ export async function runDaemon(): Promise<void> {
                   sendOk(socket, message.id)
                   break
                 }
+                case 'reapplyScrollIntent': {
+                  const sessionId = requireSession(socket, attachedSessions)
+                  requireNegotiatedVersion(socket, negotiatedVersions)
+                  await manager.reapplyScrollIntent(
+                    sessionId,
+                    message.payload.tabId,
+                    message.payload.intent
+                  )
+                  sendOk(socket, message.id)
+                  break
+                }
                 case 'setActiveTab': {
                   const sessionId = requireSession(socket, attachedSessions)
                   requireNegotiatedVersion(socket, negotiatedVersions)

package/src/daemon/session-manager.ts

@@ -1,6 +1,11 @@
 import { EventEmitter } from 'node:events'
 
-import type { TerminalModeState, TerminalSnapshot, WorkspaceSnapshotV1 } from '../state/types'
+import type {
+  ScrollIntent,
+  TerminalModeState,
+  TerminalSnapshot,
+  WorkspaceSnapshotV1,
+} from '../state/types'
 
 import { logDebug } from '../debug/input-log'
 import { SessionRegistry } from './session-registry'
@@ -62,12 +67,18 @@ export class SessionManager extends EventEmitter<SessionManagerEvents> {
     this.getOrCreateRegistry(sessionId).write(tabId, data)
   }
 
-  resize(sessionId: string, cols: number, rows: number): void {
-    this.getOrCreateRegistry(sessionId).resizeAll(cols, rows)
+  resize(sessionId: string, cols: number, rows: number, intents?: Map<string, ScrollIntent>): void {
+    this.getOrCreateRegistry(sessionId).resizeAll(cols, rows, intents)
   }
 
-  resizeTab(sessionId: string, tabId: string, cols: number, rows: number): void {
-    this.getOrCreateRegistry(sessionId).resizeTab(tabId, cols, rows)
+  resizeTab(
+    sessionId: string,
+    tabId: string,
+    cols: number,
+    rows: number,
+    intent?: ScrollIntent
+  ): void {
+    this.getOrCreateRegistry(sessionId).resizeTab(tabId, cols, rows, intent)
   }
 
   scroll(sessionId: string, tabId: string, deltaLines: number): void {
@@ -78,6 +89,10 @@ export class SessionManager extends EventEmitter<SessionManagerEvents> {
     this.getOrCreateRegistry(sessionId).scrollViewportToBottom(tabId)
   }
 
+  reapplyScrollIntent(sessionId: string, tabId: string, intent: ScrollIntent): void {
+    this.getOrCreateRegistry(sessionId).reapplyScrollIntent(tabId, intent)
+  }
+
   setActiveTab(sessionId: string, tabId: string | null): void {
     this.getOrCreateRegistry(sessionId).setActiveTab(tabId)
   }

package/src/daemon/session-registry.ts

@@ -1,12 +1,5 @@
 import { EventEmitter } from 'node:events'
 
-import type {
-  TabSession,
-  TerminalModeState,
-  TerminalSnapshot,
-  WorkspaceSnapshotV1,
-} from '../state/types'
-
 import { logDebug } from '../debug/input-log'
 import { PtyManager } from '../pty/pty-manager'
 import {
@@ -15,6 +8,14 @@ import {
   restoreTabsFromWorkspace,
 } from '../state/session-persistence'
 import { createDefaultTerminalModes } from '../state/terminal-modes'
+import {
+  DEFAULT_SCROLL_INTENT,
+  type ScrollIntent,
+  type TabSession,
+  type TerminalModeState,
+  type TerminalSnapshot,
+  type WorkspaceSnapshotV1,
+} from '../state/types'
 
 type SessionRegistryEvents = {
   render: [tabId: string, viewport: TerminalSnapshot, terminalModes: TerminalModeState]
@@ -138,6 +139,7 @@ export class SessionRegistry extends EventEmitter<SessionRegistryEvents> {
         buffer: '',
         command: [options.command, ...(options.args ?? [])].join(' '),
         id: options.tabId,
+        scrollIntent: DEFAULT_SCROLL_INTENT,
         status: 'starting',
         terminalModes: createDefaultTerminalModes(),
         title: options.title,
@@ -149,6 +151,7 @@ export class SessionRegistry extends EventEmitter<SessionRegistryEvents> {
       existing.exitCode = undefined
       existing.viewport = undefined
       existing.terminalModes = createDefaultTerminalModes()
+      existing.scrollIntent = DEFAULT_SCROLL_INTENT
       existing.assistant = options.assistant
       existing.title = options.title
       existing.command = [options.command, ...(options.args ?? [])].join(' ')
@@ -162,12 +165,12 @@ export class SessionRegistry extends EventEmitter<SessionRegistryEvents> {
     this.ptyManager.write(tabId, data)
   }
 
-  resizeAll(cols: number, rows: number): void {
-    this.ptyManager.resizeAll(cols, rows)
+  resizeAll(cols: number, rows: number, intents?: Map<string, ScrollIntent>): void {
+    this.ptyManager.resizeAll(cols, rows, intents)
   }
 
-  resizeTab(tabId: string, cols: number, rows: number): void {
-    this.ptyManager.resizeSession(tabId, cols, rows)
+  resizeTab(tabId: string, cols: number, rows: number, intent?: ScrollIntent): void {
+    this.ptyManager.resizeSession(tabId, cols, rows, intent)
   }
 
   scrollViewport(tabId: string, deltaLines: number): void {
@@ -178,6 +181,10 @@ export class SessionRegistry extends EventEmitter<SessionRegistryEvents> {
     this.ptyManager.scrollViewportToBottom(tabId)
   }
 
+  reapplyScrollIntent(tabId: string, intent: ScrollIntent): void {
+    this.ptyManager.reapplyScrollIntent(tabId, intent)
+  }
+
   setActiveTab(tabId: string | null): void {
     if (tabId === null) {
       this.activeTabId = null

package/src/index.tsx

@@ -3,6 +3,7 @@ import { createCliRenderer } from '@opentui/core'
 import { createRoot } from '@opentui/react'
 
 import { App } from './app'
+import { loadUserConfig } from './config/loader'
 import { runDaemon } from './daemon/daemon'
 import { getRuntimeProfile } from './daemon/runtime-paths'
 import { logDebug } from './debug/input-log'
@@ -61,4 +62,10 @@ const renderer = await createCliRenderer({
 const backend = await createSessionBackend()
 logDebug('index.backendReady', { backend: backend.constructor.name, runtimeProfile })
 
-createRoot(renderer).render(<App backend={backend} />)
+const resolvedConfig = await loadUserConfig()
+logDebug('index.userConfigLoaded', {
+  leader: resolvedConfig.keymaps.leader,
+  modeCount: resolvedConfig.keymaps.modes.size,
+})
+
+createRoot(renderer).render(<App backend={backend} resolvedConfig={resolvedConfig} />)

package/src/input/keymap/describe-bindings.ts

@@ -0,0 +1,68 @@
+import type { ModeId, ResolvedKeymapConfig } from '@brimveyn/aimux-config'
+
+import { parseKeyNotation } from './key-chord'
+import { formatNotationForDisplay } from './key-format'
+
+export interface DescribedBinding {
+  keys: string
+  keysDisplay: string
+  description?: string
+  group?: string
+}
+
+export interface DescribedBindingGroup {
+  group?: string
+  bindings: DescribedBinding[]
+}
+
+interface DescribeOptions {
+  withDescriptionOnly?: boolean
+  dedupeByDescription?: boolean
+}
+
+export function describeBindings(
+  config: ResolvedKeymapConfig,
+  modeId: ModeId,
+  options: DescribeOptions = {}
+): DescribedBinding[] {
+  const mode = config.modes.get(modeId)
+  if (!mode) return []
+
+  const leaderChord = parseKeyNotation(config.leader)[0]
+  const seenDescriptions = new Set<string>()
+  const result: DescribedBinding[] = []
+
+  for (const binding of mode.bindings) {
+    if (options.withDescriptionOnly && !binding.description) continue
+    if (options.dedupeByDescription && binding.description) {
+      if (seenDescriptions.has(binding.description)) continue
+      seenDescriptions.add(binding.description)
+    }
+    result.push({
+      description: binding.description,
+      group: binding.group,
+      keys: binding.keys,
+      keysDisplay: formatNotationForDisplay(binding.keys, leaderChord),
+    })
+  }
+
+  return result
+}
+
+export function groupDescribedBindings(bindings: DescribedBinding[]): DescribedBindingGroup[] {
+  const groups: DescribedBindingGroup[] = []
+  const indexByLabel = new Map<string | undefined, number>()
+
+  for (const binding of bindings) {
+    const label = binding.group
+    const existing = indexByLabel.get(label)
+    if (existing === undefined) {
+      indexByLabel.set(label, groups.length)
+      groups.push({ bindings: [binding], group: label })
+    } else {
+      groups[existing]?.bindings.push(binding)
+    }
+  }
+
+  return groups
+}

package/src/input/keymap/key-format.ts

@@ -0,0 +1,67 @@
+import { type KeyChord, parseKeyNotation } from './key-chord'
+
+const SPECIAL_DISPLAY: Record<string, string> = {
+  backspace: 'Backspace',
+  down: '↓',
+  escape: 'Esc',
+  left: '←',
+  return: 'Enter',
+  right: '→',
+  space: 'Space',
+  tab: 'Tab',
+  up: '↑',
+}
+
+function formatModifierKey(baseName: string): string {
+  const special = SPECIAL_DISPLAY[baseName]
+  if (special) return special
+  if (baseName.length === 1) return baseName.toUpperCase()
+  return baseName.charAt(0).toUpperCase() + baseName.slice(1)
+}
+
+/** Convert a single canonical KeyChord back to a human-readable label. */
+export function formatChord(chord: KeyChord, leader?: KeyChord): string {
+  if (leader && chord === leader) return '<leader>'
+
+  let ctrl = false
+  let meta = false
+  let rest = chord
+
+  while (true) {
+    if (rest.startsWith('C-')) {
+      ctrl = true
+      rest = rest.slice(2)
+      continue
+    }
+    if (rest.startsWith('M-')) {
+      meta = true
+      rest = rest.slice(2)
+      continue
+    }
+    break
+  }
+
+  if (!ctrl && !meta) {
+    if (rest.length === 1 && /^[A-Z]$/.test(rest)) {
+      return `Shift+${rest}`
+    }
+    return SPECIAL_DISPLAY[rest] ?? rest
+  }
+
+  const parts: string[] = []
+  if (ctrl) parts.push('Ctrl')
+  if (meta) parts.push('Alt')
+  parts.push(formatModifierKey(rest))
+  return parts.join('+')
+}
+
+/** Convert a raw key notation string (e.g. `<C-n>`, `dd`) to a human label. */
+export function formatNotationForDisplay(notation: string, leader?: KeyChord): string {
+  let chords: KeyChord[]
+  try {
+    chords = parseKeyNotation(notation, leader)
+  } catch {
+    return notation
+  }
+  return chords.map((c) => formatChord(c, leader)).join(' ')
+}

package/src/input/modes/bridge.ts

@@ -28,6 +28,7 @@ const MODAL_MODE_IDS: Partial<Record<SupportedModalType, ModeId>> = {
   'snippet-picker': 'modal.snippet-picker',
   'split-picker': 'modal.split-picker',
   'theme-picker': 'modal.theme-picker',
+  'update-available': 'modal.update-available',
 }
 
 export function deriveModeId(state: AppState): ModeId {

package/src/input/modes/transitions.ts

@@ -22,6 +22,7 @@ const TRANSITIONS: Record<ModeId, readonly ModeId[]> = {
   'modal.snippet-picker.filtering': ['modal.snippet-picker'],
   'modal.split-picker': ['navigation'],
   'modal.theme-picker': ['navigation'],
+  'modal.update-available': ['navigation'],
   'navigation': [
     'terminal-input',
     'modal.new-tab',
@@ -30,6 +31,7 @@ const TRANSITIONS: Record<ModeId, readonly ModeId[]> = {
     'modal.snippet-picker',
     'modal.theme-picker',
     'modal.rename-tab',
+    'modal.update-available',
     'git-mode',
   ],
   'terminal-input': ['navigation', 'layout'],

package/src/input/modes/types.ts

@@ -21,6 +21,7 @@ export type ModeId =
   | 'modal.help'
   | 'modal.split-picker'
   | 'modal.git-commit'
+  | 'modal.update-available'
 
 export type SideEffect =
   | { type: 'quit'; state: AppState }
@@ -51,6 +52,8 @@ export type SideEffect =
   | { type: 'git-rm'; path: string }
   | { type: 'git-commit'; title: string; body: string }
   | { type: 'git-push' }
+  | { type: 'confirm-update-selection' }
+  | { type: 'switch-session-by-index'; index: number }
 
 export interface KeyResult {
   actions: AppAction[]

package/src/ipc/manager-protocol.ts

@@ -1,4 +1,5 @@
 import type {
+  ScrollIntent,
   TabSession,
   TerminalModeState,
   TerminalSnapshot,
@@ -61,11 +62,26 @@ export type ManagerRequest =
       }
     }
   | { id: string; type: 'write'; payload: { sessionId: string; tabId: string; data: string } }
-  | { id: string; type: 'resizeClient'; payload: { sessionId: string; cols: number; rows: number } }
+  | {
+      id: string
+      type: 'resizeClient'
+      payload: {
+        sessionId: string
+        cols: number
+        rows: number
+        intents?: Record<string, ScrollIntent>
+      }
+    }
   | {
       id: string
       type: 'resizeTab'
-      payload: { sessionId: string; tabId: string; cols: number; rows: number }
+      payload: {
+        sessionId: string
+        tabId: string
+        cols: number
+        rows: number
+        intent?: ScrollIntent
+      }
     }
   | {
       id: string
@@ -77,6 +93,11 @@ export type ManagerRequest =
       type: 'scroll'
       payload: { sessionId: string; tabId: string; deltaLines: number }
     }
+  | {
+      id: string
+      type: 'reapplyScrollIntent'
+      payload: { sessionId: string; tabId: string; intent: ScrollIntent }
+    }
   | { id: string; type: 'setActiveTab'; payload: { sessionId: string; tabId: string | null } }
   | { id: string; type: 'closeTab'; payload: { sessionId: string; tabId: string } }
   | { id: string; type: 'disposeSession'; payload: { sessionId: string } }
@@ -150,6 +171,18 @@ function isTerminalSnapshot(value: unknown): value is TerminalSnapshot {
   )
 }
 
+function isScrollIntent(value: unknown): value is ScrollIntent {
+  if (!isObjectRecord(value)) return false
+  if (value.kind === 'bottom') return true
+  if (value.kind === 'anchor') return isFiniteNumber(value.absoluteLine)
+  return false
+}
+
+function isScrollIntentRecord(value: unknown): value is Record<string, ScrollIntent> {
+  if (!isObjectRecord(value)) return false
+  return Object.values(value).every(isScrollIntent)
+}
+
 function isTerminalModeState(value: unknown): value is TerminalModeState {
   return (
     isObjectRecord(value) &&
@@ -263,12 +296,20 @@ export function parseManagerRequest(value: unknown): ManagerRequest {
       assert(isString(value.payload.sessionId), 'resizeClient.sessionId must be a string')
       assert(isFiniteNumber(value.payload.cols), 'resizeClient.cols must be a number')
       assert(isFiniteNumber(value.payload.rows), 'resizeClient.rows must be a number')
+      assert(
+        value.payload.intents === undefined || isScrollIntentRecord(value.payload.intents),
+        'resizeClient.intents must be a scroll-intent record'
+      )
       return value as ManagerRequest
     case 'resizeTab':
       assert(isString(value.payload.sessionId), 'resizeTab.sessionId must be a string')
       assert(isString(value.payload.tabId), 'resizeTab.tabId must be a string')
       assert(isFiniteNumber(value.payload.cols), 'resizeTab.cols must be a number')
       assert(isFiniteNumber(value.payload.rows), 'resizeTab.rows must be a number')
+      assert(
+        value.payload.intent === undefined || isScrollIntent(value.payload.intent),
+        'resizeTab.intent must be a scroll intent'
+      )
       return value as ManagerRequest
     case 'scroll':
       assert(isString(value.payload.sessionId), 'scroll.sessionId must be a string')
@@ -279,6 +320,14 @@ export function parseManagerRequest(value: unknown): ManagerRequest {
       assert(isString(value.payload.sessionId), 'scrollToBottom.sessionId must be a string')
       assert(isString(value.payload.tabId), 'scrollToBottom.tabId must be a string')
       return value as ManagerRequest
+    case 'reapplyScrollIntent':
+      assert(isString(value.payload.sessionId), 'reapplyScrollIntent.sessionId must be a string')
+      assert(isString(value.payload.tabId), 'reapplyScrollIntent.tabId must be a string')
+      assert(
+        isScrollIntent(value.payload.intent),
+        'reapplyScrollIntent.intent must be a scroll intent'
+      )
+      return value as ManagerRequest
     case 'setActiveTab':
       assert(isString(value.payload.sessionId), 'setActiveTab.sessionId must be a string')
       assert(isNullableString(value.payload.tabId), 'setActiveTab.tabId must be a string or null')

package/src/ipc/protocol.ts

@@ -1,4 +1,5 @@
 import type {
+  ScrollIntent,
   TabSession,
   TerminalModeState,
   TerminalSnapshot,
@@ -54,10 +55,23 @@ export type ClientRequest =
       }
     }
   | { id: string; type: 'write'; payload: { tabId: string; data: string } }
-  | { id: string; type: 'resizeClient'; payload: { cols: number; rows: number } }
-  | { id: string; type: 'resizeTab'; payload: { tabId: string; cols: number; rows: number } }
+  | {
+      id: string
+      type: 'resizeClient'
+      payload: { cols: number; rows: number; intents?: Record<string, ScrollIntent> }
+    }
+  | {
+      id: string
+      type: 'resizeTab'
+      payload: { tabId: string; cols: number; rows: number; intent?: ScrollIntent }
+    }
   | { id: string; type: 'scrollToBottom'; payload: { tabId: string } }
   | { id: string; type: 'scroll'; payload: { tabId: string; deltaLines: number } }
+  | {
+      id: string
+      type: 'reapplyScrollIntent'
+      payload: { tabId: string; intent: ScrollIntent }
+    }
   | { id: string; type: 'setActiveTab'; payload: { tabId: string | null } }
   | { id: string; type: 'closeTab'; payload: { tabId: string } }
   | { id: string; type: 'disposeAll'; payload: Record<string, never> }
@@ -143,6 +157,18 @@ function isTerminalSnapshot(value: unknown): value is TerminalSnapshot {
   )
 }
 
+function isScrollIntent(value: unknown): value is ScrollIntent {
+  if (!isObjectRecord(value)) return false
+  if (value.kind === 'bottom') return true
+  if (value.kind === 'anchor') return isFiniteNumber(value.absoluteLine)
+  return false
+}
+
+function isScrollIntentRecord(value: unknown): value is Record<string, ScrollIntent> {
+  if (!isObjectRecord(value)) return false
+  return Object.values(value).every(isScrollIntent)
+}
+
 function isTerminalModeState(value: unknown): value is TerminalModeState {
   return (
     isObjectRecord(value) &&
@@ -273,11 +299,19 @@ export function parseClientRequest(value: unknown): ClientRequest {
     case 'resizeClient':
       assert(isFiniteNumber(value.payload.cols), 'resizeClient.cols must be a number')
       assert(isFiniteNumber(value.payload.rows), 'resizeClient.rows must be a number')
+      assert(
+        value.payload.intents === undefined || isScrollIntentRecord(value.payload.intents),
+        'resizeClient.intents must be a scroll-intent record'
+      )
       return value as ClientRequest
     case 'resizeTab':
       assert(isString(value.payload.tabId), 'resizeTab.tabId must be a string')
       assert(isFiniteNumber(value.payload.cols), 'resizeTab.cols must be a number')
       assert(isFiniteNumber(value.payload.rows), 'resizeTab.rows must be a number')
+      assert(
+        value.payload.intent === undefined || isScrollIntent(value.payload.intent),
+        'resizeTab.intent must be a scroll intent'
+      )
       return value as ClientRequest
     case 'scroll':
       assert(isString(value.payload.tabId), 'scroll.tabId must be a string')
@@ -286,6 +320,13 @@ export function parseClientRequest(value: unknown): ClientRequest {
     case 'scrollToBottom':
       assert(isString(value.payload.tabId), 'scrollToBottom.tabId must be a string')
       return value as ClientRequest
+    case 'reapplyScrollIntent':
+      assert(isString(value.payload.tabId), 'reapplyScrollIntent.tabId must be a string')
+      assert(
+        isScrollIntent(value.payload.intent),
+        'reapplyScrollIntent.intent must be a scroll intent'
+      )
+      return value as ClientRequest
     case 'setActiveTab':
       assert(isNullableString(value.payload.tabId), 'setActiveTab.tabId must be a string or null')
       return value as ClientRequest

package/src/pty/pty-manager.ts

@@ -2,7 +2,7 @@ import { Terminal as XTerm } from '@xterm/headless'
 import { type IPty, spawn } from 'bun-pty'
 import { EventEmitter } from 'node:events'
 
-import type { TerminalModeState, TerminalSnapshot } from '../state/types'
+import type { ScrollIntent, TerminalModeState, TerminalSnapshot } from '../state/types'
 
 import { logDebug } from '../debug/input-log'
 import { areTerminalSnapshotsEqual, snapshotTerminal } from './terminal-snapshot'
@@ -247,18 +247,34 @@ export class PtyManager extends EventEmitter<PtyManagerEvents> {
     this.emitRenderIfChanged(session)
   }
 
-  resizeAll(cols: number, rows: number): void {
+  private applyScrollIntent(session: SessionHandle, intent: ScrollIntent | undefined): void {
+    if (!intent || intent.kind === 'bottom') {
+      session.emulator.scrollToBottom()
+      return
+    }
+
+    const baseY = session.emulator.buffer.active.baseY
+    if (intent.absoluteLine >= baseY) {
+      session.emulator.scrollToBottom()
+      return
+    }
+
+    session.emulator.scrollToLine(Math.max(0, intent.absoluteLine))
+  }
+
+  resizeAll(cols: number, rows: number, intents?: Map<string, ScrollIntent>): void {
     const safeCols = Math.max(20, cols)
     const safeRows = Math.max(8, rows)
 
     for (const session of this.sessions.values()) {
       session.pty.resize(safeCols, safeRows)
       session.emulator.resize(safeCols, safeRows)
+      this.applyScrollIntent(session, intents?.get(session.tabId))
       this.emitRenderIfChanged(session)
     }
   }
 
-  resizeSession(tabId: string, cols: number, rows: number): void {
+  resizeSession(tabId: string, cols: number, rows: number, intent?: ScrollIntent): void {
     const session = this.sessions.get(tabId)
     if (!session) {
       return
@@ -267,6 +283,16 @@ export class PtyManager extends EventEmitter<PtyManagerEvents> {
     const safeRows = Math.max(8, rows)
     session.pty.resize(safeCols, safeRows)
     session.emulator.resize(safeCols, safeRows)
+    this.applyScrollIntent(session, intent)
+    this.emitRenderIfChanged(session)
+  }
+
+  reapplyScrollIntent(tabId: string, intent: ScrollIntent): void {
+    const session = this.sessions.get(tabId)
+    if (!session) {
+      return
+    }
+    this.applyScrollIntent(session, intent)
     this.emitRenderIfChanged(session)
   }