@brimveyn/aimux-config 0.2.4 → 0.2.6

package/package.json

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

package/src/actions.ts

@@ -237,6 +237,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,273 @@ 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)
+    // 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: rename-tab (src/input/modes/handlers/modal-rename-tab.ts)
+    // 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
     // -----------------------------------------------------------------------
     .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
   }
 

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 ──────────────────────────────────────────────────────
 
@@ -263,6 +264,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,6 +283,7 @@ export type ModalState =
   | ModalCreateSession
   | ModalSnippetEditor
   | ModalGitCommit
+  | ModalUpdateAvailable
 
 export interface LayoutState {
   terminalCols: number
@@ -324,6 +332,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 }
@@ -467,6 +476,7 @@ export type SideEffect =
   | { type: 'git-rm'; path: string }
   | { type: 'git-commit'; title: string; body: string }
   | { type: 'git-push' }
+  | { type: 'confirm-update-selection' }
 
 // ─── Key input / KeyResult / ModeContext ──────────────────────────────────────
 
@@ -563,7 +573,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 +582,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,
@@ -605,6 +615,7 @@ export interface BindingDef {
   keys: string
   result: Action
   group?: string
+  description?: string
 }
 
 export interface ModeKeymapDef {