@brimveyn/aimux-config 0.2.5 → 0.3.0

package/README.md

@@ -77,7 +77,13 @@ defineConfig({
 ```ts
 k.leader(keys) // default: '<Space>'
   .timeout(ms) // default: 300
-  .mode(id, configure) // define bindings for a mode
+  .mode(id | ids[], configure) // define bindings for a mode (or several at once)
+```
+
+Pass an array of `ModeId`s to register the same bindings in every listed mode — handy for actions that should fire in both `navigation` and `terminal-input`, for example:
+
+```ts
+k.mode(['navigation', 'terminal-input'], (m) => m.map('<C-s>', actions.snippetPicker))
 ```
 
 ### Mode builder

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux-config",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "TypeScript configuration API for aimux — keymaps, themes, and backends with a fluent builder.",
   "keywords": [
     "aimux",

package/src/actions.ts

@@ -36,8 +36,13 @@ export const helpModal: KeyResult = r([{ type: 'open-help-modal' }], [], 'modal.
 
 export const toggleSidebar: KeyResult = r([{ type: 'toggle-sidebar' }])
 export const toggleGitPanel: KeyResult = r([{ type: 'toggle-git-panel' }])
+export const toggleSessionBar: KeyResult = r([{ type: 'toggle-session-bar' }])
 export const enterGitMode: KeyResult = r([{ type: 'enter-git-mode' }], [], 'git-mode')
 
+export function switchSessionByIndex(index: number): KeyResult {
+  return r([], [{ index, type: 'switch-session-by-index' }])
+}
+
 export const splitVertical: KeyResult = r(
   [{ direction: 'vertical', type: 'open-split-picker' }],
   [],
@@ -237,6 +242,16 @@ export const saveSnippetEditor: KeyResult = r(
   'navigation'
 )
 
+// ---------------------------------------------------------------------------
+// Update-available modal
+// ---------------------------------------------------------------------------
+
+export const confirmUpdateSelection: KeyResult = r(
+  [{ type: 'close-modal' }],
+  [{ type: 'confirm-update-selection' }],
+  'navigation'
+)
+
 // Layout-specific
 export const exitLayoutToInput: KeyResult = r(
   [{ focusMode: 'terminal-input', type: 'set-focus-mode' }],

package/src/defaults.ts

@@ -12,262 +12,290 @@ export function getDefaultKeymapConfig(): ResolvedKeymapConfig {
     .timeout(300)
 
     // -----------------------------------------------------------------------
-    // Navigation mode (src/input/modes/handlers/navigation.ts)
+    // Navigation mode
     // -----------------------------------------------------------------------
     .mode('navigation', (m) =>
       m
-        .map('<C-c>', actions.quit)
-        .map('<C-n>', actions.newTab)
-        .map('<C-g>', actions.sessionPicker)
-        .map('<C-z>', actions.ctrlZSidebar)
-        .map('dd', actions.closeTab)
-        .map('<C-b>', actions.toggleSidebar)
-        .map('<C-r>', actions.restartTab)
-        .map('<C-s>', actions.snippetPicker)
-        .map('<C-t>', actions.themePicker)
-        .map('<C-h>', actions.resizeSidebar(-2))
-        .map('<C-l>', actions.resizeSidebar(2))
-        .map('G', actions.toggleGitPanel)
-        .map('<C-d>', actions.enterGitMode)
-        .map('<C-j>', actions.resizeGitPanel(-0.05))
-        .map('<C-k>', actions.resizeGitPanel(0.05))
-        .map('J', actions.reorderTab(1))
-        .map('j', actions.nextTab)
-        .map('K', actions.reorderTab(-1))
-        .map('k', actions.prevTab)
-        .map('r', actions.renameTab)
-        .map('i', actions.enterInsert)
-        .map('?', actions.helpModal)
+        .map('<C-c>', actions.quit, 'Quit')
+        .map('<C-n>', actions.newTab, 'New tab')
+        .map('<C-g>', actions.sessionPicker, 'Session picker')
+        .map('<C-z>', actions.ctrlZSidebar, 'Focus sidebar')
+        .map('dd', actions.closeTab, 'Close tab')
+        .map('<C-b>', actions.toggleSidebar, 'Toggle sidebar')
+        .map('<C-r>', actions.restartTab, 'Restart tab')
+        .map('<C-s>', actions.snippetPicker, 'Snippet picker')
+        .map('<C-t>', actions.themePicker, 'Theme picker')
+        .map('<C-h>', actions.resizeSidebar(-2), 'Sidebar narrower')
+        .map('<C-l>', actions.resizeSidebar(2), 'Sidebar wider')
+        .map('G', actions.toggleGitPanel, 'Toggle git panel')
+        .map('<C-d>', actions.enterGitMode, 'Enter git mode')
+        .map('<C-j>', actions.resizeGitPanel(-0.05), 'Git panel smaller')
+        .map('<C-k>', actions.resizeGitPanel(0.05), 'Git panel larger')
+        .map('J', actions.reorderTab(1), 'Move tab right')
+        .map('j', actions.nextTab, 'Next tab')
+        .map('K', actions.reorderTab(-1), 'Move tab left')
+        .map('k', actions.prevTab, 'Prev tab')
+        .map('r', actions.renameTab, 'Rename tab')
+        .map('i', actions.enterInsert, 'Focus terminal')
+        .map('?', actions.helpModal, 'Help')
     )
 
     // -----------------------------------------------------------------------
     // Terminal-input mode
-    // Bindings here are processed by raw-input-handler.ts before bytes reach
-    // the PTY. Only single-chord <C-*> sequences are supported (no multi-key).
     // -----------------------------------------------------------------------
     .mode('terminal-input', (m) =>
       m
-        .map('<C-z>', actions.leaveTerminalInput)
-        .map('<Leader>', actions.enterLayoutMode)
-        .map('<C-b>', actions.toggleSidebarFromInput)
+        .map('<C-z>', actions.leaveTerminalInput, 'Leave insert')
+        .map('<Leader>', actions.enterLayoutMode, 'Layout mode')
+        .map('<C-b>', actions.toggleSidebarFromInput, 'Toggle sidebar')
     )
 
     // -----------------------------------------------------------------------
-    // Layout mode (src/input/modes/handlers/layout.ts)
+    // Session bar: same chords from nav and while typing in the terminal
+    // -----------------------------------------------------------------------
+    .mode(['navigation', 'terminal-input'], (m) =>
+      m
+        .map('<Leader>b', actions.toggleSessionBar, 'Toggle session bar')
+        .map('<Leader>1', actions.switchSessionByIndex(1), 'Session 1')
+        .map('<Leader>2', actions.switchSessionByIndex(2), 'Session 2')
+        .map('<Leader>3', actions.switchSessionByIndex(3), 'Session 3')
+        .map('<Leader>4', actions.switchSessionByIndex(4), 'Session 4')
+        .map('<Leader>5', actions.switchSessionByIndex(5), 'Session 5')
+        .map('<Leader>6', actions.switchSessionByIndex(6), 'Session 6')
+        .map('<Leader>7', actions.switchSessionByIndex(7), 'Session 7')
+        .map('<Leader>8', actions.switchSessionByIndex(8), 'Session 8')
+        .map('<Leader>9', actions.switchSessionByIndex(9), 'Session 9')
+    )
+
+    // -----------------------------------------------------------------------
+    // Layout mode
     // -----------------------------------------------------------------------
     .mode('layout', (m) =>
       m
-        .map('<Esc>', actions.exitLayoutToInput)
-        .map('<Leader>', actions.exitLayoutToInput)
-        .map('<C-z>', actions.exitLayoutToNavigation)
-        .map('H', actions.resizePane(-1, 'vertical'))
-        .map('L', actions.resizePane(1, 'vertical'))
-        .map('K', actions.resizePane(-1, 'horizontal'))
-        .map('J', actions.resizePane(1, 'horizontal'))
-        .map('h', actions.focusPane('left'))
-        .map('j', actions.focusPane('down'))
-        .map('k', actions.focusPane('up'))
-        .map('l', actions.focusPane('right'))
-        .map('|', actions.splitVertical)
-        .map('-', actions.splitHorizontal)
-        .map('q', actions.closePane)
+        .map('<Esc>', actions.exitLayoutToInput, 'Back to insert')
+        .map('<Leader>', actions.exitLayoutToInput, 'Back to insert')
+        .map('<C-z>', actions.exitLayoutToNavigation, 'Back to nav')
+        .map('H', actions.resizePane(-1, 'vertical'), 'Shrink ←')
+        .map('L', actions.resizePane(1, 'vertical'), 'Grow →')
+        .map('K', actions.resizePane(-1, 'horizontal'), 'Shrink ↑')
+        .map('J', actions.resizePane(1, 'horizontal'), 'Grow ↓')
+        .map('h', actions.focusPane('left'), 'Focus left')
+        .map('j', actions.focusPane('down'), 'Focus down')
+        .map('k', actions.focusPane('up'), 'Focus up')
+        .map('l', actions.focusPane('right'), 'Focus right')
+        .map('|', actions.splitVertical, 'Split vertical')
+        .map('-', actions.splitHorizontal, 'Split horizontal')
+        .map('q', actions.closePane, 'Close pane')
     )
 
     // -----------------------------------------------------------------------
-    // Git mode (src/input/modes/handlers/git-mode.ts)
+    // Git mode
     // -----------------------------------------------------------------------
     .mode('git-mode', (m) =>
       m
-        .map('<Esc>', actions.exitGitMode)
-        .map('j', actions.selectGitFile(1))
-        .map('k', actions.selectGitFile(-1))
-        .map('<C-d>', actions.scrollGitDiff(20))
-        .map('<C-u>', actions.scrollGitDiff(-20))
-        .map('<Down>', actions.scrollGitDiff(1))
-        .map('<Up>', actions.scrollGitDiff(-1))
-        .map('a', actions.gitStageSelected)
-        .map('d', actions.gitDestructiveSelected)
-        .map('c', actions.gitCommitOpen)
-        .map('p', actions.gitPush)
+        .map('<Esc>', actions.exitGitMode, 'Exit git')
+        .map('j', actions.selectGitFile(1), 'Next file')
+        .map('k', actions.selectGitFile(-1), 'Prev file')
+        .map('<C-d>', actions.scrollGitDiff(20), 'Page down')
+        .map('<C-u>', actions.scrollGitDiff(-20), 'Page up')
+        .map('<Down>', actions.scrollGitDiff(1), 'Scroll down')
+        .map('<Up>', actions.scrollGitDiff(-1), 'Scroll up')
+        .map('a', actions.gitStageSelected, 'Stage')
+        .map('d', actions.gitDestructiveSelected, 'Unstage/delete')
+        .map('c', actions.gitCommitOpen, 'Commit')
+        .map('p', actions.gitPush, 'Push')
     )
 
     // -----------------------------------------------------------------------
-    // Modal: help (src/input/modes/handlers/modal-help.ts)
+    // Modal: help
     // -----------------------------------------------------------------------
-    .mode('modal.help', (m) => m.map('<Esc>', actions.closeModal))
+    .mode('modal.help', (m) => m.map('<Esc>', actions.closeModal, 'Close'))
 
     // -----------------------------------------------------------------------
-    // Modal: theme-picker (src/input/modes/handlers/modal-theme-picker.ts)
+    // Modal: theme-picker
     // -----------------------------------------------------------------------
     .mode('modal.theme-picker', (m) =>
       m
-        .map('<Esc>', actions.restoreTheme)
-        .map('j', actions.previewTheme(1))
-        .map('k', actions.previewTheme(-1))
+        .map('<Esc>', actions.restoreTheme, 'Cancel')
+        .map('j', actions.previewTheme(1), 'Next')
+        .map('k', actions.previewTheme(-1), 'Prev')
         .map('<Down>', actions.previewTheme(1))
         .map('<Up>', actions.previewTheme(-1))
-        .map('<CR>', actions.confirmTheme)
+        .map('<CR>', actions.confirmTheme, 'Confirm')
+    )
+
+    // -----------------------------------------------------------------------
+    // Modal: update-available
+    // -----------------------------------------------------------------------
+    .mode('modal.update-available', (m) =>
+      m
+        .map('<Esc>', actions.closeModal, 'Cancel')
+        .map('l', actions.moveModalSelection(1), 'Next')
+        .map('h', actions.moveModalSelection(-1), 'Prev')
+        .map('j', actions.moveModalSelection(1))
+        .map('k', actions.moveModalSelection(-1))
+        .map('<Right>', actions.moveModalSelection(1))
+        .map('<Left>', actions.moveModalSelection(-1))
+        .map('<Down>', actions.moveModalSelection(1))
+        .map('<Up>', actions.moveModalSelection(-1))
+        .map('<CR>', actions.confirmUpdateSelection, 'Confirm')
     )
 
     // -----------------------------------------------------------------------
-    // Modal: rename-tab (src/input/modes/handlers/modal-rename-tab.ts)
+    // Modal: rename-tab
     // -----------------------------------------------------------------------
     .mode('modal.rename-tab', (m) =>
-      m.map('<Esc>', actions.closeModal).map('<CR>', actions.confirmRenameTab).passthrough()
+      m
+        .map('<Esc>', actions.closeModal, 'Cancel')
+        .map('<CR>', actions.confirmRenameTab, 'Confirm')
+        .passthrough()
     )
 
     // -----------------------------------------------------------------------
-    // Modal: new-tab (src/input/modes/handlers/modal-new-tab.ts)
+    // Modal: new-tab
     // -----------------------------------------------------------------------
     .mode('modal.new-tab', (m) =>
       m
-        .map('<Esc>', actions.closeModal)
-        .map('j', actions.moveModalSelection(1))
-        .map('k', actions.moveModalSelection(-1))
+        .map('<Esc>', actions.closeModal, 'Cancel')
+        .map('j', actions.moveModalSelection(1), 'Next')
+        .map('k', actions.moveModalSelection(-1), 'Prev')
         .map('<Down>', actions.moveModalSelection(1))
         .map('<Up>', actions.moveModalSelection(-1))
-        .map('<CR>', actions.launchSelectedAssistant)
-        .map('e', actions.beginCommandEdit)
+        .map('<CR>', actions.launchSelectedAssistant, 'Launch')
+        .map('e', actions.beginCommandEdit, 'Edit command')
     )
 
     // -----------------------------------------------------------------------
     // Modal: new-tab command-edit
-    // (src/input/modes/handlers/modal-new-tab-command-edit.ts)
     // -----------------------------------------------------------------------
     .mode('modal.new-tab.command-edit', (m) =>
       m
-        .map('<Esc>', actions.cancelCommandEdit('modal.new-tab'))
-        .map('<CR>', actions.commitCommandEdit)
-        .map('<C-n>', actions.moveModalSelection(1))
-        .map('<C-p>', actions.moveModalSelection(-1))
+        .map('<Esc>', actions.cancelCommandEdit('modal.new-tab'), 'Cancel')
+        .map('<CR>', actions.commitCommandEdit, 'Save')
+        .map('<C-n>', actions.moveModalSelection(1), 'Next')
+        .map('<C-p>', actions.moveModalSelection(-1), 'Prev')
         .passthrough()
     )
 
     // -----------------------------------------------------------------------
-    // Modal: session-picker (src/input/modes/handlers/modal-session-picker.ts)
+    // Modal: session-picker
     // -----------------------------------------------------------------------
     .mode('modal.session-picker', (m) =>
       m
-        .map('<Esc>', actions.sessionPickerEscape)
-        .map('j', actions.moveModalSelection(1))
-        .map('k', actions.moveModalSelection(-1))
+        .map('<Esc>', actions.sessionPickerEscape, 'Cancel')
+        .map('j', actions.moveModalSelection(1), 'Next')
+        .map('k', actions.moveModalSelection(-1), 'Prev')
         .map('<Down>', actions.moveModalSelection(1))
         .map('<Up>', actions.moveModalSelection(-1))
-        .map('<CR>', actions.confirmSelectedSession)
-        .map('n', actions.openCreateSessionModal)
-        .map('r', actions.openRenameSelectedSession)
-        .map('d', actions.deleteSelectedSession)
-        .map('/', actions.beginSessionFilter)
+        .map('<CR>', actions.confirmSelectedSession, 'Open')
+        .map('n', actions.openCreateSessionModal, 'New')
+        .map('r', actions.openRenameSelectedSession, 'Rename')
+        .map('d', actions.deleteSelectedSession, 'Delete')
+        .map('/', actions.beginSessionFilter, 'Filter')
     )
 
     // -----------------------------------------------------------------------
     // Modal: session-picker filtering
-    // (src/input/modes/handlers/modal-session-picker-filter.ts)
     // -----------------------------------------------------------------------
     .mode('modal.session-picker.filtering', (m) =>
       m
-        .map('<Esc>', actions.cancelCommandEdit('modal.session-picker'))
-        .map('<CR>', actions.confirmSelectedSession)
-        .map('<C-n>', actions.moveModalSelection(1))
-        .map('<C-p>', actions.moveModalSelection(-1))
+        .map('<Esc>', actions.cancelCommandEdit('modal.session-picker'), 'Cancel')
+        .map('<CR>', actions.confirmSelectedSession, 'Open')
+        .map('<C-n>', actions.moveModalSelection(1), 'Next')
+        .map('<C-p>', actions.moveModalSelection(-1), 'Prev')
         .passthrough()
     )
 
     // -----------------------------------------------------------------------
-    // Modal: session-name (src/input/modes/handlers/modal-session-name.ts)
+    // Modal: session-name
     // -----------------------------------------------------------------------
     .mode('modal.session-name', (m) =>
       m
-        .map('<Esc>', actions.backToSessionPicker)
-        .map('<CR>', actions.confirmSessionRename)
+        .map('<Esc>', actions.backToSessionPicker, 'Cancel')
+        .map('<CR>', actions.confirmSessionRename, 'Confirm')
         .passthrough()
     )
 
     // -----------------------------------------------------------------------
     // Modal: create-session
-    // (src/input/modes/handlers/modal-create-session.ts)
     // -----------------------------------------------------------------------
     .mode('modal.create-session', (m) =>
       m
-        .map('<Esc>', actions.backToSessionPicker)
-        .map('<Tab>', actions.switchField)
-        .map('<CR>', actions.confirmCreateSession)
-        .map('<C-n>', actions.moveModalSelection(1))
-        .map('<C-p>', actions.moveModalSelection(-1))
+        .map('<Esc>', actions.backToSessionPicker, 'Cancel')
+        .map('<Tab>', actions.switchField, 'Next field')
+        .map('<CR>', actions.confirmCreateSession, 'Confirm')
+        .map('<C-n>', actions.moveModalSelection(1), 'Next')
+        .map('<C-p>', actions.moveModalSelection(-1), 'Prev')
         .passthrough()
     )
 
     // -----------------------------------------------------------------------
     // Modal: snippet-picker
-    // (src/input/modes/handlers/modal-snippet-picker.ts)
     // -----------------------------------------------------------------------
     .mode('modal.snippet-picker', (m) =>
       m
-        .map('<Esc>', actions.closeModal)
-        .map('j', actions.moveModalSelection(1))
-        .map('k', actions.moveModalSelection(-1))
+        .map('<Esc>', actions.closeModal, 'Cancel')
+        .map('j', actions.moveModalSelection(1), 'Next')
+        .map('k', actions.moveModalSelection(-1), 'Prev')
         .map('<Down>', actions.moveModalSelection(1))
         .map('<Up>', actions.moveModalSelection(-1))
-        .map('<CR>', actions.pasteSelectedSnippet)
-        .map('a', actions.pasteSnippetToGroup)
-        .map('n', actions.openSnippetEditor)
-        .map('r', actions.editSelectedSnippet)
+        .map('<CR>', actions.pasteSelectedSnippet, 'Send')
+        .map('a', actions.pasteSnippetToGroup, 'Send to group')
+        .map('n', actions.openSnippetEditor, 'New')
+        .map('r', actions.editSelectedSnippet, 'Edit')
         .map('e', actions.editSelectedSnippet)
-        .map('d', actions.deleteSelectedSnippet)
-        .map('/', actions.beginSnippetFilter)
+        .map('d', actions.deleteSelectedSnippet, 'Delete')
+        .map('/', actions.beginSnippetFilter, 'Filter')
     )
 
     // -----------------------------------------------------------------------
     // Modal: snippet-picker filtering
-    // (src/input/modes/handlers/modal-snippet-picker-filter.ts)
     // -----------------------------------------------------------------------
     .mode('modal.snippet-picker.filtering', (m) =>
       m
-        .map('<Esc>', actions.cancelCommandEdit('modal.snippet-picker'))
-        .map('<CR>', actions.snippetFilterPaste)
-        .map('<C-a>', actions.snippetFilterPasteToGroup)
-        .map('<C-n>', actions.moveModalSelection(1))
-        .map('<C-p>', actions.moveModalSelection(-1))
+        .map('<Esc>', actions.cancelCommandEdit('modal.snippet-picker'), 'Cancel')
+        .map('<CR>', actions.snippetFilterPaste, 'Send')
+        .map('<C-a>', actions.snippetFilterPasteToGroup, 'Send to group')
+        .map('<C-n>', actions.moveModalSelection(1), 'Next')
+        .map('<C-p>', actions.moveModalSelection(-1), 'Prev')
         .passthrough()
     )
 
     // -----------------------------------------------------------------------
     // Modal: snippet-editor
-    // (src/input/modes/handlers/modal-snippet-editor.ts)
     // -----------------------------------------------------------------------
     .mode('modal.snippet-editor', (m) =>
       m
-        .map('<Esc>', actions.backToSnippetPicker)
-        .map('<Tab>', actions.switchField)
-        .map('<CR>', actions.saveSnippetEditor)
-        .map('<C-n>', actions.moveModalSelection(1))
-        .map('<C-p>', actions.moveModalSelection(-1))
+        .map('<Esc>', actions.backToSnippetPicker, 'Cancel')
+        .map('<Tab>', actions.switchField, 'Next field')
+        .map('<CR>', actions.saveSnippetEditor, 'Save')
+        .map('<C-n>', actions.moveModalSelection(1), 'Next')
+        .map('<C-p>', actions.moveModalSelection(-1), 'Prev')
         .passthrough()
     )
 
     // -----------------------------------------------------------------------
     // Modal: split-picker
-    // (src/input/modes/handlers/modal-split-picker.ts)
     // -----------------------------------------------------------------------
     .mode('modal.split-picker', (m) =>
       m
-        .map('<Esc>', actions.closeModal)
-        .map('j', actions.moveModalSelection(1))
-        .map('k', actions.moveModalSelection(-1))
+        .map('<Esc>', actions.closeModal, 'Cancel')
+        .map('j', actions.moveModalSelection(1), 'Next')
+        .map('k', actions.moveModalSelection(-1), 'Prev')
         .map('<Down>', actions.moveModalSelection(1))
         .map('<Up>', actions.moveModalSelection(-1))
-        .map('<CR>', actions.confirmSplit)
+        .map('<CR>', actions.confirmSplit, 'Confirm')
     )
 
     // -----------------------------------------------------------------------
-    // Modal: git-commit (src/input/modes/handlers/modal-git-commit.ts)
+    // Modal: git-commit
     // -----------------------------------------------------------------------
     .mode('modal.git-commit', (m) =>
       m
-        .map('<Esc>', actions.gitCommitCancel)
-        .map('<C-CR>', actions.gitCommitSubmit)
-        .map('<Tab>', actions.switchField)
-        .map('<CR>', actions.gitCommitReturnKey)
+        .map('<Esc>', actions.gitCommitCancel, 'Cancel')
+        .map('<C-CR>', actions.gitCommitSubmit, 'Commit')
+        .map('<Tab>', actions.switchField, 'Next field')
+        .map('<CR>', actions.gitCommitReturnKey, 'Newline / confirm')
         .passthrough()
     )
 

package/src/keymap-builder.ts

@@ -21,8 +21,13 @@ export class GroupBuilder implements GroupBuilderApi {
     private readonly groupName: string
   ) {}
 
-  map(keys: string, action: Action): this {
-    this.bindings.push({ group: this.groupName, keys: `${this.prefix}${keys}`, result: action })
+  map(keys: string, action: Action, description?: string): this {
+    this.bindings.push({
+      description,
+      group: this.groupName,
+      keys: `${this.prefix}${keys}`,
+      result: action,
+    })
     return this
   }
 
@@ -43,8 +48,8 @@ export class ModeBindingBuilder implements ModeBindingBuilderApi {
   private readonly removals: string[] = []
   private _passthrough = false
 
-  map(keys: string, action: Action): this {
-    this.bindings.push({ keys, result: action })
+  map(keys: string, action: Action, description?: string): this {
+    this.bindings.push({ description, keys, result: action })
     return this
   }
 
@@ -94,10 +99,36 @@ export class KeymapBuilder implements KeymapBuilderApi {
     return this
   }
 
-  mode(id: ModeId, configure: (m: ModeBindingBuilderApi) => ModeBindingBuilderApi): this {
+  mode(
+    id: ModeId | readonly ModeId[],
+    configure: (m: ModeBindingBuilderApi) => ModeBindingBuilderApi
+  ): this {
     const builder = new ModeBindingBuilder()
     configure(builder)
-    this.modes.set(id, builder._build())
+    const incoming = builder._build()
+    const ids = Array.isArray(id) ? id : [id]
+    for (const modeId of ids) {
+      const existing = this.modes.get(modeId)
+      if (!existing) {
+        // Fresh mode: clone so later merges don't mutate a shared array.
+        this.modes.set(modeId, {
+          bindings: [...incoming.bindings],
+          isPassthrough: incoming.isPassthrough,
+          removals: [...incoming.removals],
+        })
+        continue
+      }
+      // Merge: later bindings win over earlier ones sharing the same keys.
+      const incomingKeys = new Set(incoming.bindings.map((b) => b.keys))
+      this.modes.set(modeId, {
+        bindings: [
+          ...existing.bindings.filter((b) => !incomingKeys.has(b.keys)),
+          ...incoming.bindings,
+        ],
+        isPassthrough: existing.isPassthrough || incoming.isPassthrough,
+        removals: [...existing.removals, ...incoming.removals],
+      })
+    }
     return this
   }
 

package/src/resolver.ts

@@ -20,6 +20,7 @@ export function resolveConfig(userConfig: AimuxUserConfig): ResolvedConfig {
     backends: userConfig.backends ?? {},
     hooks: userConfig.hooks ?? {},
     keymaps,
+    sessionBar: userConfig.sessionBar ?? {},
     sidebar: userConfig.sidebar ?? {},
     snippets: userConfig.snippets ?? [],
     theme: userConfig.theme,

package/src/types.ts

@@ -27,6 +27,7 @@ export type ModeId =
   | 'modal.help'
   | 'modal.split-picker'
   | 'modal.git-commit'
+  | 'modal.update-available'
 
 // ─── Primitive app types ──────────────────────────────────────────────────────
 
@@ -124,6 +125,7 @@ export interface SessionRecord {
   createdAt: string
   updatedAt: string
   lastOpenedAt: string
+  order?: number
   workspaceSnapshot?: WorkspaceSnapshotV1
 }
 
@@ -263,6 +265,12 @@ export interface ModalSnippetEditor extends ModalBase {
   contentBuffer: string
 }
 
+export interface ModalUpdateAvailable extends ModalBase {
+  type: 'update-available'
+  currentVersion: string
+  latestVersion: string
+}
+
 export type ModalState =
   | ModalClosed
   | ModalNewTab
@@ -276,12 +284,20 @@ export type ModalState =
   | ModalCreateSession
   | ModalSnippetEditor
   | ModalGitCommit
+  | ModalUpdateAvailable
 
 export interface LayoutState {
   terminalCols: number
   terminalRows: number
 }
 
+export type SessionBarPosition = 'top' | 'bottom'
+
+export interface SessionBarState {
+  visible: boolean
+  position: SessionBarPosition
+}
+
 export interface AppState {
   tabs: TabSession[]
   activeTabId: string | null
@@ -289,6 +305,8 @@ export interface AppState {
   tabGroupMap: Record<string, string>
   sessions: SessionRecord[]
   currentSessionId: string | null
+  sessionsBusy: Record<string, boolean>
+  sessionBar: SessionBarState
   snippets: SnippetRecord[]
   focusMode: FocusMode
   sidebar: SidebarState
@@ -324,6 +342,7 @@ export type ModalAction =
   | { type: 'open-snippet-editor'; snippetId?: string }
   | { type: 'begin-snippet-filter' }
   | { type: 'open-theme-picker' }
+  | { type: 'open-update-available-modal'; currentVersion: string; latestVersion: string }
 
 export type SessionAction =
   | { type: 'load-session'; sessionId: string; workspaceSnapshot?: WorkspaceSnapshotV1 }
@@ -331,6 +350,8 @@ export type SessionAction =
   | { type: 'create-session-record'; session: SessionRecord }
   | { type: 'rename-session-record'; sessionId: string; name: string }
   | { type: 'delete-session-record'; sessionId: string }
+  | { type: 'reorder-sessions'; orderedIds: string[] }
+  | { type: 'set-session-busy'; sessionId: string; busy: boolean }
 
 export type TabAction =
   | { type: 'add-tab'; tab: TabSession }
@@ -392,6 +413,8 @@ export type UIAction =
   | { type: 'toggle-git-panel' }
   | { type: 'resize-git-panel'; delta: number }
   | { type: 'set-pending-chords'; chords: string[] | null }
+  | { type: 'toggle-session-bar' }
+  | { type: 'set-session-bar-position'; position: SessionBarPosition }
 
 export interface GitRefreshPayload {
   branch: string | null
@@ -467,6 +490,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 }
 
 // ─── Key input / KeyResult / ModeContext ──────────────────────────────────────
 
@@ -563,7 +588,7 @@ export type Action = KeyResult | ActionFn
 // ─── Keymap builder API types ─────────────────────────────────────────────────
 
 export interface GroupBuilderApi {
-  map(keys: string, action: Action): GroupBuilderApi
+  map(keys: string, action: Action, description?: string): GroupBuilderApi
   group(
     prefix: string,
     name: string,
@@ -572,7 +597,7 @@ export interface GroupBuilderApi {
 }
 
 export interface ModeBindingBuilderApi {
-  map(keys: string, action: Action): ModeBindingBuilderApi
+  map(keys: string, action: Action, description?: string): ModeBindingBuilderApi
   unmap(keys: string): ModeBindingBuilderApi
   group(
     prefix: string,
@@ -585,16 +610,25 @@ export interface ModeBindingBuilderApi {
 export interface KeymapBuilderApi {
   leader(key: string): KeymapBuilderApi
   timeout(ms: number): KeymapBuilderApi
-  mode(id: ModeId, configure: (m: ModeBindingBuilderApi) => ModeBindingBuilderApi): KeymapBuilderApi
+  mode(
+    id: ModeId | readonly ModeId[],
+    configure: (m: ModeBindingBuilderApi) => ModeBindingBuilderApi
+  ): KeymapBuilderApi
 }
 
 // ─── Top-level user config ────────────────────────────────────────────────────
 
+export interface SessionBarConfig {
+  visible?: boolean
+  position?: SessionBarPosition
+}
+
 export interface AimuxUserConfig {
   theme?: ThemeId | ThemeDefinition
   keymaps?: (k: KeymapBuilderApi) => KeymapBuilderApi
   backends?: Record<string, BackendConfig>
   sidebar?: SidebarConfig
+  sessionBar?: SessionBarConfig
   hooks?: HooksConfig
   snippets?: SnippetDef[]
 }
@@ -605,6 +639,7 @@ export interface BindingDef {
   keys: string
   result: Action
   group?: string
+  description?: string
 }
 
 export interface ModeKeymapDef {
@@ -624,6 +659,7 @@ export interface ResolvedConfig {
   keymaps: ResolvedKeymapConfig
   backends: Record<string, BackendConfig>
   sidebar: SidebarConfig
+  sessionBar: SessionBarConfig
   hooks: HooksConfig
   snippets: SnippetDef[]
 }