@brimveyn/aimux-config 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BrimVeyn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# @brimveyn/aimux-config
+
+TypeScript configuration API for [aimux](https://github.com/BrimVeyn/aimux) — the terminal multiplexer for AI CLIs.
+
+Write your keymaps, theme, and backends in a typed TypeScript file. Method-chaining builder inspired by nvim, with a prefix-trie resolver that supports leader keys and multi-key sequences.
+
+## Install
+
+```bash
+mkdir -p ~/.config/aimux && cd ~/.config/aimux
+bun init -y
+bun add -d @brimveyn/aimux-config
+```
+
+Then create `~/.config/aimux/aimux.config.ts`:
+
+```ts
+import { defineConfig, actions, themes } from '@brimveyn/aimux-config'
+
+export default defineConfig({
+  theme: themes.extend('tokyo-night', { accent: '#ff9e64' }),
+
+  keymaps: (k) =>
+    k
+      .leader('<Space>')
+      .timeout(300)
+      .mode('navigation', (m) =>
+        m
+          .map('j', actions.nextTab)
+          .map('k', actions.prevTab)
+          .map('<leader>g', actions.sessionPicker)
+          .group('<leader>t', 'tabs', (g) =>
+            g.map('n', actions.newTab).map('r', actions.renameTab).map('x', actions.closeTab)
+          )
+      ),
+})
+```
+
+## Key notation
+
+| Notation          | Matches                        |
+| ----------------- | ------------------------------ |
+| `j`               | Bare character `j`             |
+| `J`               | Shift+J (uppercase letter)     |
+| `<C-n>`           | Ctrl+N                         |
+| `<M-x>` / `<A-x>` | Meta/Alt+X                     |
+| `<C-M-a>`         | Ctrl+Alt+A                     |
+| `<CR>`            | Return/Enter                   |
+| `<Esc>`           | Escape                         |
+| `<Space>`         | Spacebar                       |
+| `<Tab>`           | Tab                            |
+| `<BS>`            | Backspace                      |
+| `<Up>` `<Down>`   | Arrow keys                     |
+| `<leader>`        | Configured leader chord        |
+| `dd`              | Multi-key sequence (d, then d) |
+| `<leader>tn`      | Leader, then t, then n         |
+
+Ambiguous prefixes (e.g., `d` is bound AND `dd` is bound) are resolved after a configurable timeout (default 300ms).
+
+## Builder API
+
+### Top-level config
+
+```ts
+defineConfig({
+  theme?: ThemeId | ThemeDefinition
+  keymaps?: (k: KeymapBuilder) => KeymapBuilder
+  backends?: Record<string, BackendConfig>   // stub for future use
+  sidebar?: SidebarConfig                    // stub
+  hooks?: HooksConfig                        // stub
+  snippets?: SnippetDef[]                    // stub
+})
+```
+
+### Keymap builder
+
+```ts
+k.leader(keys) // default: '<Space>'
+  .timeout(ms) // default: 300
+  .mode(id, configure) // define bindings for a mode
+```
+
+### Mode builder
+
+```ts
+m.map(keys, action) // bind a key/sequence to an action
+  .unmap(keys) // remove a default binding
+  .group(prefix, name, g) // sugar for leader-prefixed sub-trees
+  .passthrough() // for text-input modes: unmatched keys route to text input
+```
+
+### Groups
+
+Groups organize leader-key sub-trees. `.group('<leader>t', 'tabs', g => g.map('n', ...))` is sugar for `.map('<leader>tn', ...)` with a `name` label used by the help modal.
+
+```ts
+.group('<leader>t', 'tabs', (g) => g
+  .map('n', actions.newTab)
+  .map('r', actions.renameTab)
+  .map('x', actions.closeTab))
+```
+
+## Actions
+
+Pre-built actions cover every built-in aimux operation:
+
+**Tab control** — `nextTab`, `prevTab`, `newTab`, `renameTab`, `closeTab`, `restartTab`, `moveTab(n)`, `reorderTab(n)`
+
+**Modals** — `sessionPicker`, `snippetPicker`, `themePicker`, `helpModal`, `closeModal`
+
+**Sidebar / panels** — `toggleSidebar`, `resizeSidebar(n)`, `toggleGitPanel`, `resizeGitPanel(n)`
+
+**Layout / splits** — `splitVertical`, `splitHorizontal`, `focusPane('left'|'right'|'up'|'down')`, `resizePane(n, 'horizontal'|'vertical')`, `closePane`
+
+**Mode transitions** — `enterInsert`, `enterLayoutMode`, `leaveTerminalInput`, `quit`
+
+**Custom actions** — write an `ActionFn` for dynamic logic:
+
+```ts
+.mode('navigation', (m) => m
+  .map('gT', (ctx) => {
+    const tabId = ctx.state.activeTabId
+    if (!tabId) return null
+    return {
+      actions: [{ type: 'close-active-tab' }],
+      effects: [{ type: 'close-tab', tabId }],
+    }
+  }))
+```
+
+## Themes
+
+```ts
+import { themes } from '@brimveyn/aimux-config'
+
+// Extend a built-in theme
+themes.extend('tokyo-night', {
+  accent: '#ff9e64',
+  background: '#1a1b26',
+})
+
+// Create a custom theme
+themes.create({
+  accent: '#...',
+  accentAlt: '#...',
+  background: '#...',
+  // ... all ThemeColors keys required
+})
+```
+
+Built-in themes: `aimux`, `tokyo-night`, `dracula`, `dracula-at-night`, `everforest`, `gruvbox-dark`, `catppuccin-mocha`, `nord`, `solarized-dark`, `one-dark`, `kanagawa`.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@brimveyn/aimux-config",
+  "version": "0.1.0",
+  "description": "TypeScript configuration API for aimux — keymaps, themes, and backends with a fluent builder.",
+  "keywords": [
+    "aimux",
+    "config",
+    "keybindings",
+    "keymap",
+    "leader-key",
+    "multiplexer",
+    "terminal",
+    "trie",
+    "tui"
+  ],
+  "homepage": "https://github.com/BrimVeyn/aimux#readme",
+  "bugs": {
+    "url": "https://github.com/BrimVeyn/aimux/issues"
+  },
+  "license": "MIT",
+  "author": "BrimVeyn",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BrimVeyn/aimux.git",
+    "directory": "packages/aimux-config"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./backends": "./src/backends.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/actions.ts

@@ -0,0 +1,368 @@
+import type { ActionFn, KeyResult, ModeContext } from './types'
+
+function r(
+  actions: KeyResult['actions'] = [],
+  effects: KeyResult['effects'] = [],
+  transition?: KeyResult['transition']
+): KeyResult {
+  return transition ? { actions, effects, transition } : { actions, effects }
+}
+
+// ---------------------------------------------------------------------------
+// Static actions (KeyResult values — no ctx needed)
+// ---------------------------------------------------------------------------
+
+export const nextTab: KeyResult = r([{ delta: 1, type: 'move-active-tab' }])
+export const prevTab: KeyResult = r([{ delta: -1, type: 'move-active-tab' }])
+
+export const newTab: KeyResult = r([{ type: 'open-new-tab-modal' }], [], 'modal.new-tab')
+export const renameTab: KeyResult = r([{ type: 'open-rename-tab-modal' }], [], 'modal.rename-tab')
+export const sessionPicker: KeyResult = r(
+  [{ type: 'open-session-picker' }],
+  [],
+  'modal.session-picker'
+)
+export const snippetPicker: KeyResult = r(
+  [{ type: 'open-snippet-picker' }],
+  [],
+  'modal.snippet-picker'
+)
+export const themePicker: KeyResult = r(
+  [{ type: 'open-theme-picker' }],
+  [{ action: 'open', type: 'apply-theme' }],
+  'modal.theme-picker'
+)
+export const helpModal: KeyResult = r([{ type: 'open-help-modal' }], [], 'modal.help')
+
+export const toggleSidebar: KeyResult = r([{ type: 'toggle-sidebar' }])
+export const toggleGitPanel: KeyResult = r([{ type: 'toggle-git-panel' }])
+
+export const splitVertical: KeyResult = r(
+  [{ direction: 'vertical', type: 'open-split-picker' }],
+  [],
+  'modal.split-picker'
+)
+export const splitHorizontal: KeyResult = r(
+  [{ direction: 'horizontal', type: 'open-split-picker' }],
+  [],
+  'modal.split-picker'
+)
+
+export const enterInsert: ActionFn = (ctx: ModeContext) => {
+  if (!ctx.state.activeTabId) return null
+  return r([{ focusMode: 'terminal-input', type: 'set-focus-mode' }], [], 'terminal-input')
+}
+
+export const closeModal: KeyResult = r([{ type: 'close-modal' }], [], 'navigation')
+
+// ---------------------------------------------------------------------------
+// Dynamic actions (need ctx at runtime — ActionFn)
+// ---------------------------------------------------------------------------
+
+export const closeTab: ActionFn = (ctx: ModeContext) => {
+  const tabId = ctx.state.activeTabId
+  if (!tabId) return null
+  return r([{ type: 'close-active-tab' }], [{ tabId, type: 'close-tab' }])
+}
+
+export const restartTab: ActionFn = (ctx: ModeContext) => {
+  const tab = ctx.state.tabs.find((t) => t.id === ctx.state.activeTabId)
+  if (!tab) return null
+  return r([], [{ tab, type: 'restart-tab' }])
+}
+
+export const quit: ActionFn = (ctx: ModeContext) => {
+  return r([], [{ state: ctx.state, type: 'quit' }])
+}
+
+// ---------------------------------------------------------------------------
+// Parameterized factories
+// ---------------------------------------------------------------------------
+
+export function moveTab(delta: number): KeyResult {
+  return r([{ delta, type: 'move-active-tab' }])
+}
+
+export function reorderTab(delta: number): KeyResult {
+  return r([{ delta, type: 'reorder-active-tab' }])
+}
+
+export function resizeSidebar(delta: number): KeyResult {
+  return r([{ delta, type: 'resize-sidebar' }])
+}
+
+export function resizeGitPanel(delta: number): KeyResult {
+  return r([{ delta, type: 'resize-git-panel' }])
+}
+
+export function focusPane(direction: 'left' | 'right' | 'up' | 'down'): KeyResult {
+  return r(
+    [
+      { direction, type: 'focus-pane-direction' },
+      { focusMode: 'terminal-input', type: 'set-focus-mode' },
+    ],
+    [],
+    'terminal-input'
+  )
+}
+
+export function resizePane(delta: number, axis: 'horizontal' | 'vertical'): ActionFn {
+  return (ctx: ModeContext) => {
+    const tabId = ctx.state.activeTabId
+    if (!tabId) return null
+    return r([{ axis, delta, tabId, type: 'resize-pane' }])
+  }
+}
+
+export function moveModalSelection(delta: number): KeyResult {
+  return r([{ delta, type: 'move-modal-selection' }])
+}
+
+export function moveModalSelectionWithPreview(
+  delta: number,
+  effects: KeyResult['effects']
+): KeyResult {
+  return r([{ delta, type: 'move-modal-selection' }], effects)
+}
+
+// ---------------------------------------------------------------------------
+// Modal-specific actions
+// ---------------------------------------------------------------------------
+
+export const launchSelectedAssistant: KeyResult = r([], [{ type: 'launch-selected-assistant' }])
+
+export const beginCommandEdit: KeyResult = r(
+  [{ type: 'begin-command-edit' }],
+  [],
+  'modal.new-tab.command-edit'
+)
+
+export const cancelCommandEdit = (returnTo: KeyResult['transition']): KeyResult =>
+  r([{ type: 'cancel-command-edit' }], [], returnTo)
+
+export const commitCommandEdit: KeyResult = r(
+  [{ type: 'commit-command-edit' }],
+  [{ type: 'save-custom-command' }],
+  'modal.new-tab'
+)
+
+export const confirmSelectedSession: KeyResult = r([], [{ type: 'confirm-selected-session' }])
+
+export const openCreateSessionModal: KeyResult = r(
+  [{ type: 'open-create-session-modal' }],
+  [],
+  'modal.create-session'
+)
+
+export const openRenameSelectedSession: KeyResult = r(
+  [],
+  [{ type: 'open-rename-selected-session' }]
+)
+
+export const deleteSelectedSession: KeyResult = r([], [{ type: 'delete-selected-session' }])
+
+export const beginSessionFilter: KeyResult = r(
+  [{ type: 'begin-session-filter' }],
+  [],
+  'modal.session-picker.filtering'
+)
+
+export const openSnippetEditor: KeyResult = r(
+  [{ type: 'open-snippet-editor' }],
+  [],
+  'modal.snippet-editor'
+)
+
+export const editSelectedSnippet: KeyResult = r([], [{ type: 'edit-selected-snippet' }])
+export const deleteSelectedSnippet: KeyResult = r([], [{ type: 'delete-selected-snippet' }])
+
+export const pasteSelectedSnippet: KeyResult = r(
+  [{ type: 'close-modal' }],
+  [{ type: 'paste-selected-snippet' }],
+  'navigation'
+)
+
+export const pasteSnippetToGroup: KeyResult = r(
+  [{ type: 'close-modal' }],
+  [{ type: 'paste-snippet-to-group' }],
+  'navigation'
+)
+
+export const beginSnippetFilter: KeyResult = r(
+  [{ type: 'begin-snippet-filter' }],
+  [],
+  'modal.snippet-picker.filtering'
+)
+
+export const confirmSplit: KeyResult = r([], [{ type: 'confirm-split' }])
+
+export const restoreTheme: KeyResult = r(
+  [{ type: 'close-modal' }],
+  [{ action: 'restore', type: 'apply-theme' }],
+  'navigation'
+)
+
+export const confirmTheme: KeyResult = r(
+  [{ type: 'close-modal' }],
+  [{ action: 'confirm', type: 'apply-theme' }],
+  'navigation'
+)
+
+export function previewTheme(delta: 1 | -1): KeyResult {
+  return r(
+    [{ delta, type: 'move-modal-selection' }],
+    [{ action: 'preview', delta, type: 'apply-theme' }]
+  )
+}
+
+export const switchField: KeyResult = r([{ type: 'switch-create-session-field' }])
+export const selectDirectory: KeyResult = r([{ type: 'select-directory' }])
+
+export const backToSessionPicker: KeyResult = r(
+  [{ type: 'open-session-picker' }],
+  [],
+  'modal.session-picker'
+)
+
+export const backToSnippetPicker: KeyResult = r(
+  [{ type: 'open-snippet-picker' }],
+  [],
+  'modal.snippet-picker'
+)
+
+export const saveSnippetEditor: KeyResult = r(
+  [{ type: 'close-modal' }],
+  [{ type: 'save-snippet-editor' }],
+  'navigation'
+)
+
+// Layout-specific
+export const exitLayoutToInput: KeyResult = r(
+  [{ focusMode: 'terminal-input', type: 'set-focus-mode' }],
+  [],
+  'terminal-input'
+)
+
+export const exitLayoutToNavigation: ActionFn = (ctx: ModeContext) => {
+  const actions: KeyResult['actions'] = [{ focusMode: 'navigation', type: 'set-focus-mode' }]
+  if (!ctx.state.sidebar.visible) {
+    actions.push({ type: 'toggle-sidebar' })
+  }
+  return r(actions, [], 'navigation')
+}
+
+export const closePane: ActionFn = (ctx: ModeContext) => {
+  const tabId = ctx.state.activeTabId
+  if (!tabId) return null
+  return r(
+    [
+      { tabId, type: 'close-pane' },
+      { focusMode: 'terminal-input', type: 'set-focus-mode' },
+    ],
+    [{ tabId, type: 'close-tab' }],
+    'terminal-input'
+  )
+}
+
+// Navigation-specific dynamic actions
+export const ctrlZSidebar: ActionFn = (ctx: ModeContext) => {
+  if (!ctx.state.sidebar.visible) {
+    return r([{ type: 'toggle-sidebar' }])
+  }
+  return r([])
+}
+
+// ---------------------------------------------------------------------------
+// Terminal-input escape shortcuts (used by raw-input-handler)
+// These fire while the user is actively in terminal-input mode.
+// ---------------------------------------------------------------------------
+
+export const leaveTerminalInput: KeyResult = r(
+  [{ focusMode: 'navigation', type: 'set-focus-mode' }],
+  [],
+  'navigation'
+)
+
+export const enterLayoutMode: KeyResult = r(
+  [{ focusMode: 'layout', type: 'set-focus-mode' }],
+  [],
+  'layout'
+)
+
+export const toggleSidebarFromInput: KeyResult = r([{ type: 'toggle-sidebar' }])
+
+// Session name modal
+export const confirmSessionRename: ActionFn = (ctx: ModeContext) => {
+  const trimmed = (ctx.state.modal.editBuffer ?? '').trim()
+  const sessionId = ctx.state.modal.sessionTargetId
+  if (trimmed && sessionId) {
+    return r(
+      [{ type: 'open-session-picker' }],
+      [{ name: trimmed, sessionId, type: 'rename-session' }],
+      'modal.session-picker'
+    )
+  }
+  return r([{ type: 'open-session-picker' }], [], 'modal.session-picker')
+}
+
+// Rename tab modal
+export const confirmRenameTab: ActionFn = (ctx: ModeContext) => {
+  const trimmed = (ctx.state.modal.editBuffer ?? '').trim()
+  const tabId = ctx.state.modal.sessionTargetId
+  const actions: KeyResult['actions'] = []
+  if (trimmed && tabId) {
+    actions.push({ tabId, title: trimmed, type: 'rename-tab' })
+  }
+  actions.push({ type: 'close-modal' })
+  return r(actions, [], 'navigation')
+}
+
+// Create session modal
+export const confirmCreateSession: ActionFn = (ctx: ModeContext) => {
+  const modal = ctx.state.modal as {
+    activeField?: string
+    editBuffer?: string
+    pendingProjectPath?: string
+  }
+
+  if (modal.activeField === 'directory') {
+    return r([{ type: 'select-directory' }])
+  }
+
+  const trimmed = (modal.editBuffer ?? '').trim()
+  const projectPath = modal.pendingProjectPath ?? undefined
+  const sessionName = trimmed || getDefaultSessionName(projectPath)
+  if (sessionName) {
+    return r(
+      [{ type: 'close-modal' }],
+      [{ name: sessionName, projectPath, type: 'create-session' }],
+      'navigation'
+    )
+  }
+  return r([{ type: 'close-modal' }], [], 'navigation')
+}
+
+function getDefaultSessionName(projectPath?: string): string {
+  if (!projectPath) return ''
+  const segments = projectPath.split('/').filter(Boolean)
+  return segments.at(-1) ?? ''
+}
+
+// Session picker escape (conditional)
+export const sessionPickerEscape: ActionFn = (ctx: ModeContext) => {
+  if (!ctx.state.currentSessionId) return null
+  return r([{ type: 'close-modal' }], [], 'navigation')
+}
+
+// Snippet filter: paste from filter + close
+export const snippetFilterPaste: KeyResult = r(
+  [{ type: 'close-modal' }],
+  [{ type: 'paste-selected-snippet' }],
+  'navigation'
+)
+
+export const snippetFilterPasteToGroup: KeyResult = r(
+  [{ type: 'close-modal' }],
+  [{ type: 'paste-snippet-to-group' }],
+  'navigation'
+)

package/src/backends.ts

@@ -0,0 +1,23 @@
+import type { BackendConfig } from './types'
+
+/**
+ * Create a Claude backend configuration.
+ * Stub — runtime wiring deferred to follow-up work.
+ */
+export function claudeBackend(opts?: { model?: string }): BackendConfig {
+  return {
+    args: opts?.model ? ['--model', opts.model] : [],
+    command: 'claude',
+  }
+}
+
+/**
+ * Create a Codex backend configuration.
+ * Stub — runtime wiring deferred to follow-up work.
+ */
+export function codexBackend(opts?: { args?: string[] }): BackendConfig {
+  return {
+    args: opts?.args ?? [],
+    command: 'codex',
+  }
+}