@mdxui/terminal 2.0.0

package/src/__tests__/keyboard.test.ts

@@ -0,0 +1,1791 @@
+/**
+ * @mdxui/terminal Keyboard Navigation Tests
+ *
+ * TDD RED Phase: These tests define the contract for keyboard navigation
+ * in terminal UIs. All tests should FAIL initially because the APIs
+ * aren't implemented yet.
+ *
+ * Requirements tested:
+ * - j/k movement (Vim-style vertical navigation)
+ * - h/l movement (Vim-style horizontal navigation)
+ * - Enter/Space selection and activation
+ * - Tab/Shift+Tab focus cycling
+ * - Escape cancel/back navigation
+ * - Custom key bindings
+ * - Focus management (tracking, trapping)
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import React from 'react'
+
+// Mock React for testing components without full React reconciler
+vi.mock('react', async () => {
+  const actual = await vi.importActual('react')
+  return {
+    ...actual,
+    createElement: vi.fn((type, props, ...children) => ({
+      type,
+      props: { ...props, children },
+    })),
+    useState: vi.fn((initial) => [initial, vi.fn()]),
+    useEffect: vi.fn(),
+    useCallback: vi.fn((fn) => fn),
+    useRef: vi.fn((initial) => ({ current: initial })),
+    useContext: vi.fn(),
+    createContext: vi.fn((defaultValue) => ({
+      Provider: vi.fn(),
+      Consumer: vi.fn(),
+      _currentValue: defaultValue,
+    })),
+  }
+})
+
+// ============================================================================
+// createKeyboardManager Tests
+// ============================================================================
+
+describe('createKeyboardManager', () => {
+  describe('basic creation', () => {
+    it('creates a keyboard manager with bindings', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+
+      const manager = createKeyboardManager({
+        bindings: {
+          j: 'move-down',
+          k: 'move-up',
+          enter: 'select',
+          escape: 'back',
+        },
+      })
+
+      expect(manager).toBeDefined()
+      expect(typeof manager.handleKey).toBe('function')
+    })
+
+    it('returns actions for bound keys', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+
+      const manager = createKeyboardManager({
+        bindings: {
+          j: 'move-down',
+          k: 'move-up',
+        },
+      })
+
+      expect(manager.getAction('j')).toBe('move-down')
+      expect(manager.getAction('k')).toBe('move-up')
+    })
+
+    it('returns undefined for unbound keys', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+
+      const manager = createKeyboardManager({
+        bindings: {
+          j: 'move-down',
+        },
+      })
+
+      expect(manager.getAction('x')).toBeUndefined()
+    })
+  })
+
+  describe('modifier key support', () => {
+    it('handles ctrl modifier', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+
+      const manager = createKeyboardManager({
+        bindings: {
+          'ctrl+c': 'cancel',
+          'ctrl+s': 'save',
+        },
+      })
+
+      expect(manager.getAction('ctrl+c')).toBe('cancel')
+      expect(manager.getAction('ctrl+s')).toBe('save')
+    })
+
+    it('handles alt modifier', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+
+      const manager = createKeyboardManager({
+        bindings: {
+          'alt+h': 'help',
+        },
+      })
+
+      expect(manager.getAction('alt+h')).toBe('help')
+    })
+
+    it('handles shift modifier', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+
+      const manager = createKeyboardManager({
+        bindings: {
+          'shift+tab': 'focus-prev',
+          K: 'move-up-fast', // Capital K = shift+k
+        },
+      })
+
+      expect(manager.getAction('shift+tab')).toBe('focus-prev')
+      expect(manager.getAction('K')).toBe('move-up-fast')
+    })
+
+    it('handles combined modifiers', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+
+      const manager = createKeyboardManager({
+        bindings: {
+          'ctrl+shift+s': 'save-as',
+          'ctrl+alt+delete': 'force-quit',
+        },
+      })
+
+      expect(manager.getAction('ctrl+shift+s')).toBe('save-as')
+    })
+  })
+
+  describe('vim-style bindings', () => {
+    it('supports standard vim movement (h/j/k/l)', async () => {
+      const { createKeyboardManager, VIM_BINDINGS } = await import('@mdxui/terminal')
+
+      const manager = createKeyboardManager({
+        bindings: VIM_BINDINGS,
+      })
+
+      expect(manager.getAction('h')).toBe('move-left')
+      expect(manager.getAction('j')).toBe('move-down')
+      expect(manager.getAction('k')).toBe('move-up')
+      expect(manager.getAction('l')).toBe('move-right')
+    })
+
+    it('supports vim navigation bindings', async () => {
+      const { createKeyboardManager, VIM_BINDINGS } = await import('@mdxui/terminal')
+
+      const manager = createKeyboardManager({
+        bindings: VIM_BINDINGS,
+      })
+
+      expect(manager.getAction('gg')).toBe('move-first')
+      expect(manager.getAction('G')).toBe('move-last')
+      expect(manager.getAction('/')).toBe('search')
+    })
+
+    it('supports vim action bindings', async () => {
+      const { createKeyboardManager, VIM_BINDINGS } = await import('@mdxui/terminal')
+
+      const manager = createKeyboardManager({
+        bindings: VIM_BINDINGS,
+      })
+
+      expect(manager.getAction('enter')).toBe('select')
+      expect(manager.getAction('escape')).toBe('back')
+      expect(manager.getAction('q')).toBe('quit')
+    })
+  })
+
+  describe('handleKey callback', () => {
+    it('calls action handler when key matches', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+      const onAction = vi.fn()
+
+      const manager = createKeyboardManager({
+        bindings: { j: 'move-down' },
+        onAction,
+      })
+
+      manager.handleKey('j')
+      expect(onAction).toHaveBeenCalledWith('move-down', { key: 'j' })
+    })
+
+    it('does not call handler for unbound keys', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+      const onAction = vi.fn()
+
+      const manager = createKeyboardManager({
+        bindings: { j: 'move-down' },
+        onAction,
+      })
+
+      manager.handleKey('x')
+      expect(onAction).not.toHaveBeenCalled()
+    })
+
+    it('returns true when key was handled', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+
+      const manager = createKeyboardManager({
+        bindings: { j: 'move-down' },
+      })
+
+      expect(manager.handleKey('j')).toBe(true)
+    })
+
+    it('returns false when key was not handled', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+
+      const manager = createKeyboardManager({
+        bindings: { j: 'move-down' },
+      })
+
+      expect(manager.handleKey('x')).toBe(false)
+    })
+  })
+
+  describe('binding management', () => {
+    it('allows adding bindings dynamically', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+
+      const manager = createKeyboardManager({
+        bindings: { j: 'move-down' },
+      })
+
+      manager.addBinding('x', 'delete')
+      expect(manager.getAction('x')).toBe('delete')
+    })
+
+    it('allows removing bindings', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+
+      const manager = createKeyboardManager({
+        bindings: { j: 'move-down', k: 'move-up' },
+      })
+
+      manager.removeBinding('j')
+      expect(manager.getAction('j')).toBeUndefined()
+      expect(manager.getAction('k')).toBe('move-up')
+    })
+
+    it('allows replacing all bindings', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+
+      const manager = createKeyboardManager({
+        bindings: { j: 'move-down' },
+      })
+
+      manager.setBindings({ x: 'delete' })
+      expect(manager.getAction('j')).toBeUndefined()
+      expect(manager.getAction('x')).toBe('delete')
+    })
+
+    it('returns all current bindings', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+
+      const bindings = { j: 'move-down', k: 'move-up' }
+      const manager = createKeyboardManager({ bindings })
+
+      expect(manager.getBindings()).toEqual(bindings)
+    })
+  })
+
+  describe('enabled state', () => {
+    it('can be disabled', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+      const onAction = vi.fn()
+
+      const manager = createKeyboardManager({
+        bindings: { j: 'move-down' },
+        onAction,
+        enabled: false,
+      })
+
+      manager.handleKey('j')
+      expect(onAction).not.toHaveBeenCalled()
+    })
+
+    it('can toggle enabled state', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+      const onAction = vi.fn()
+
+      const manager = createKeyboardManager({
+        bindings: { j: 'move-down' },
+        onAction,
+      })
+
+      manager.disable()
+      manager.handleKey('j')
+      expect(onAction).not.toHaveBeenCalled()
+
+      manager.enable()
+      manager.handleKey('j')
+      expect(onAction).toHaveBeenCalledWith('move-down', { key: 'j' })
+    })
+
+    it('reports enabled status', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+
+      const manager = createKeyboardManager({
+        bindings: {},
+        enabled: false,
+      })
+
+      expect(manager.isEnabled()).toBe(false)
+      manager.enable()
+      expect(manager.isEnabled()).toBe(true)
+    })
+  })
+
+  describe('key sequence support', () => {
+    it('handles multi-key sequences like gg', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+      const onAction = vi.fn()
+
+      const manager = createKeyboardManager({
+        bindings: {
+          gg: 'move-first',
+          G: 'move-last',
+        },
+        onAction,
+      })
+
+      manager.handleKey('g')
+      expect(onAction).not.toHaveBeenCalled() // Waiting for second key
+
+      manager.handleKey('g')
+      expect(onAction).toHaveBeenCalledWith('move-first', { key: 'gg' })
+    })
+
+    it('times out pending sequence', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+      const onAction = vi.fn()
+
+      const manager = createKeyboardManager({
+        bindings: {
+          gg: 'move-first',
+          g: 'go', // Fallback if only single g
+        },
+        onAction,
+        sequenceTimeout: 500,
+      })
+
+      manager.handleKey('g')
+      // Simulate timeout
+      await new Promise((r) => setTimeout(r, 600))
+
+      expect(onAction).toHaveBeenCalledWith('go', { key: 'g' })
+    })
+
+    it('cancels pending sequence on escape', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+
+      const manager = createKeyboardManager({
+        bindings: {
+          gg: 'move-first',
+        },
+      })
+
+      manager.handleKey('g')
+      expect(manager.getPendingSequence()).toBe('g')
+
+      manager.handleKey('escape')
+      expect(manager.getPendingSequence()).toBe('')
+    })
+  })
+
+  describe('destroy method', () => {
+    it('provides destroy function', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+
+      const manager = createKeyboardManager({
+        bindings: { j: 'move-down' },
+      })
+
+      expect(typeof manager.destroy).toBe('function')
+    })
+
+    it('clears pending sequence on destroy', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+
+      const manager = createKeyboardManager({
+        bindings: {
+          gg: 'move-first',
+        },
+      })
+
+      manager.handleKey('g')
+      expect(manager.getPendingSequence()).toBe('g')
+
+      manager.destroy()
+      expect(manager.getPendingSequence()).toBe('')
+    })
+
+    it('clears sequence timer on destroy to prevent memory leak', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+      const onAction = vi.fn()
+
+      const manager = createKeyboardManager({
+        bindings: {
+          gg: 'move-first',
+          g: 'go',
+        },
+        onAction,
+        sequenceTimeout: 100,
+      })
+
+      // Start a sequence which creates a timer
+      // When 'g' is pressed and 'gg' exists, it waits for potential sequence completion
+      manager.handleKey('g')
+
+      // Immediately destroy before timeout fires
+      manager.destroy()
+
+      // Now verify destruction worked by checking onAction was not called yet
+      // (if the timer fired, it would have called onAction with 'go')
+      const callCountBeforeWait = onAction.mock.calls.length
+
+      // Wait for what would have been the timeout
+      await new Promise((r) => setTimeout(r, 200))
+
+      // The timeout handler should NOT have been called because destroy cleared it
+      // Without destroy, the timeout would have triggered 'go' action for 'g'
+      expect(onAction.mock.calls.length).toBe(callCountBeforeWait)
+    })
+
+    it('can be called multiple times safely', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+
+      const manager = createKeyboardManager({
+        bindings: { gg: 'move-first' },
+      })
+
+      manager.handleKey('g')
+
+      // Should not throw when called multiple times
+      expect(() => {
+        manager.destroy()
+        manager.destroy()
+        manager.destroy()
+      }).not.toThrow()
+    })
+  })
+})
+
+// ============================================================================
+// useKeyboard Hook Tests
+// ============================================================================
+
+describe('useKeyboard hook', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('registers keyboard handler', async () => {
+    const { useKeyboard } = await import('@mdxui/terminal')
+    const handler = vi.fn()
+
+    const result = useKeyboard(handler)
+
+    expect(result).toBeDefined()
+    expect(result.enabled).toBe(true)
+  })
+
+  it('provides enable/disable controls', async () => {
+    const { useKeyboard } = await import('@mdxui/terminal')
+    const handler = vi.fn()
+
+    const result = useKeyboard(handler)
+
+    expect(typeof result.enable).toBe('function')
+    expect(typeof result.disable).toBe('function')
+  })
+
+  it('respects enabled option', async () => {
+    const { useKeyboard } = await import('@mdxui/terminal')
+    const handler = vi.fn()
+
+    const result = useKeyboard(handler, { enabled: false })
+
+    expect(result.enabled).toBe(false)
+  })
+
+  it('provides key information in handler', async () => {
+    const { useKeyboard } = await import('@mdxui/terminal')
+
+    // The handler should receive key and modifier info
+    type KeyHandler = (
+      key: string,
+      modifiers: { ctrl: boolean; alt: boolean; shift: boolean; meta: boolean }
+    ) => void
+
+    const handler: KeyHandler = vi.fn()
+    useKeyboard(handler)
+
+    // Handler signature is tested; actual calls depend on terminal events
+    expect(handler).toBeDefined()
+  })
+
+  it('supports priority for layered handlers', async () => {
+    const { useKeyboard } = await import('@mdxui/terminal')
+    const handler = vi.fn()
+
+    // Higher priority handlers should receive events first
+    const result = useKeyboard(handler, { priority: 10 })
+
+    expect(result.priority).toBe(10)
+  })
+
+  it('cleans up on unmount', async () => {
+    const { useKeyboard } = await import('@mdxui/terminal')
+    const handler = vi.fn()
+
+    const result = useKeyboard(handler)
+
+    // Should have cleanup function
+    expect(typeof result.cleanup).toBe('function')
+  })
+})
+
+// ============================================================================
+// useFocus Hook Tests
+// ============================================================================
+
+describe('useFocus hook', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('basic focus state', () => {
+    it('returns focused state', async () => {
+      const { useFocus } = await import('@mdxui/terminal')
+
+      const result = useFocus()
+
+      expect(typeof result.focused).toBe('boolean')
+    })
+
+    it('provides focus function', async () => {
+      const { useFocus } = await import('@mdxui/terminal')
+
+      const result = useFocus()
+
+      expect(typeof result.focus).toBe('function')
+    })
+
+    it('provides blur function', async () => {
+      const { useFocus } = await import('@mdxui/terminal')
+
+      const result = useFocus()
+
+      expect(typeof result.blur).toBe('function')
+    })
+  })
+
+  describe('focus navigation', () => {
+    it('provides focusNext function', async () => {
+      const { useFocus } = await import('@mdxui/terminal')
+
+      const result = useFocus()
+
+      expect(typeof result.focusNext).toBe('function')
+    })
+
+    it('provides focusPrev function', async () => {
+      const { useFocus } = await import('@mdxui/terminal')
+
+      const result = useFocus()
+
+      expect(typeof result.focusPrev).toBe('function')
+    })
+
+    it('provides focusFirst function', async () => {
+      const { useFocus } = await import('@mdxui/terminal')
+
+      const result = useFocus()
+
+      expect(typeof result.focusFirst).toBe('function')
+    })
+
+    it('provides focusLast function', async () => {
+      const { useFocus } = await import('@mdxui/terminal')
+
+      const result = useFocus()
+
+      expect(typeof result.focusLast).toBe('function')
+    })
+  })
+
+  describe('focus identification', () => {
+    it('accepts id parameter', async () => {
+      const { useFocus } = await import('@mdxui/terminal')
+
+      const result = useFocus({ id: 'my-element' })
+
+      expect(result.id).toBe('my-element')
+    })
+
+    it('generates id if not provided', async () => {
+      const { useFocus } = await import('@mdxui/terminal')
+
+      const result = useFocus()
+
+      expect(typeof result.id).toBe('string')
+      expect(result.id.length).toBeGreaterThan(0)
+    })
+  })
+
+  describe('auto focus', () => {
+    it('supports autoFocus option', async () => {
+      const { useFocus } = await import('@mdxui/terminal')
+
+      const result = useFocus({ autoFocus: true })
+
+      // With autoFocus, component should request focus on mount
+      expect(result.focused).toBe(true)
+    })
+  })
+
+  describe('tab index', () => {
+    it('returns tabIndex for ordering', async () => {
+      const { useFocus } = await import('@mdxui/terminal')
+
+      const result = useFocus({ tabIndex: 5 })
+
+      expect(result.tabIndex).toBe(5)
+    })
+
+    it('defaults tabIndex to 0', async () => {
+      const { useFocus } = await import('@mdxui/terminal')
+
+      const result = useFocus()
+
+      expect(result.tabIndex).toBe(0)
+    })
+
+    it('negative tabIndex removes from tab order', async () => {
+      const { useFocus } = await import('@mdxui/terminal')
+
+      const result = useFocus({ tabIndex: -1 })
+
+      expect(result.tabIndex).toBe(-1)
+    })
+  })
+
+  describe('focus callbacks', () => {
+    it('calls onFocus when focused', async () => {
+      const { useFocus } = await import('@mdxui/terminal')
+      const onFocus = vi.fn()
+
+      useFocus({ onFocus })
+
+      // onFocus should be registered
+      expect(onFocus).toBeDefined()
+    })
+
+    it('calls onBlur when blurred', async () => {
+      const { useFocus } = await import('@mdxui/terminal')
+      const onBlur = vi.fn()
+
+      useFocus({ onBlur })
+
+      // onBlur should be registered
+      expect(onBlur).toBeDefined()
+    })
+  })
+})
+
+// ============================================================================
+// FocusProvider Tests
+// ============================================================================
+
+describe('FocusProvider', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('basic rendering', () => {
+    it('renders children', async () => {
+      const { FocusProvider } = await import('@mdxui/terminal')
+
+      const element = FocusProvider({ children: 'Content' })
+
+      expect(element).toBeDefined()
+    })
+  })
+
+  describe('focus trapping', () => {
+    it('supports trap prop for modal focus', async () => {
+      const { FocusProvider } = await import('@mdxui/terminal')
+
+      const element = FocusProvider({ trap: true, children: 'Modal content' })
+
+      // FocusProvider wraps in Context.Provider, check inner div's data-focus-trap
+      const divElement = element.props?.children
+      expect(divElement?.props?.['data-focus-trap']).toBe(true)
+    })
+
+    it('wraps Tab focus to first element when at end', async () => {
+      const { FocusProvider } = await import('@mdxui/terminal')
+
+      const element = FocusProvider({
+        trap: true,
+        wrapFocus: true,
+        children: 'Content',
+      })
+
+      // wrapFocus is passed to div props and used internally for navigation
+      const divElement = element.props?.children
+      expect(divElement?.props?.wrapFocus).toBe(true)
+    })
+
+    it('wraps Shift+Tab focus to last element when at start', async () => {
+      const { FocusProvider } = await import('@mdxui/terminal')
+
+      // Same as above - wrapFocus handles both directions
+      const element = FocusProvider({
+        trap: true,
+        wrapFocus: true,
+        children: 'Content',
+      })
+
+      const divElement = element.props?.children
+      expect(divElement?.props?.wrapFocus).toBe(true)
+    })
+  })
+
+  describe('initial focus', () => {
+    it('supports initialFocus id', async () => {
+      const { FocusProvider } = await import('@mdxui/terminal')
+
+      const element = FocusProvider({
+        initialFocus: 'my-input',
+        children: 'Content',
+      })
+
+      // initialFocus is passed through to div props
+      const divElement = element.props?.children
+      expect(divElement?.props?.initialFocus).toBe('my-input')
+    })
+
+    it('focuses first focusable by default', async () => {
+      const { FocusProvider } = await import('@mdxui/terminal')
+
+      const element = FocusProvider({
+        focusFirstOnMount: true,
+        children: 'Content',
+      })
+
+      // focusFirstOnMount is passed through to div props
+      const divElement = element.props?.children
+      expect(divElement?.props?.focusFirstOnMount).toBe(true)
+    })
+  })
+
+  describe('focus restoration', () => {
+    it('restores focus on unmount', async () => {
+      const { FocusProvider } = await import('@mdxui/terminal')
+
+      const element = FocusProvider({
+        restoreFocus: true,
+        children: 'Content',
+      })
+
+      // restoreFocus is passed through to div props
+      const divElement = element.props?.children
+      expect(divElement?.props?.restoreFocus).toBe(true)
+    })
+  })
+
+  describe('focus group', () => {
+    it('supports group name for scoped focus', async () => {
+      const { FocusProvider } = await import('@mdxui/terminal')
+
+      const element = FocusProvider({
+        group: 'sidebar',
+        children: 'Content',
+      })
+
+      // group is exposed via data-focus-group attribute
+      const divElement = element.props?.children
+      expect(divElement?.props?.['data-focus-group']).toBe('sidebar')
+    })
+  })
+})
+
+// ============================================================================
+// useFocusManager Hook Tests
+// ============================================================================
+
+describe('useFocusManager hook', () => {
+  it('provides access to focus context', async () => {
+    const { useFocusManager } = await import('@mdxui/terminal')
+
+    const result = useFocusManager()
+
+    expect(result).toBeDefined()
+  })
+
+  it('tracks all focusable elements', async () => {
+    const { useFocusManager } = await import('@mdxui/terminal')
+
+    const result = useFocusManager()
+
+    expect(Array.isArray(result.focusableIds)).toBe(true)
+  })
+
+  it('tracks currently focused element', async () => {
+    const { useFocusManager } = await import('@mdxui/terminal')
+
+    const result = useFocusManager()
+
+    // Could be null if nothing focused, or string id
+    expect(result.focusedId === null || typeof result.focusedId === 'string').toBe(true)
+  })
+
+  it('provides focusById function', async () => {
+    const { useFocusManager } = await import('@mdxui/terminal')
+
+    const result = useFocusManager()
+
+    expect(typeof result.focusById).toBe('function')
+  })
+
+  it('provides focus navigation functions', async () => {
+    const { useFocusManager } = await import('@mdxui/terminal')
+
+    const result = useFocusManager()
+
+    expect(typeof result.focusNext).toBe('function')
+    expect(typeof result.focusPrev).toBe('function')
+    expect(typeof result.focusFirst).toBe('function')
+    expect(typeof result.focusLast).toBe('function')
+  })
+
+  it('provides trap state', async () => {
+    const { useFocusManager } = await import('@mdxui/terminal')
+
+    const result = useFocusManager()
+
+    expect(typeof result.isTrapped).toBe('boolean')
+  })
+})
+
+// ============================================================================
+// Vim-style Navigation Integration Tests
+// ============================================================================
+
+describe('vim-style navigation', () => {
+  describe('j/k vertical movement', () => {
+    it('j moves selection down', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+      const onAction = vi.fn()
+
+      const manager = createKeyboardManager({
+        bindings: { j: 'move-down', k: 'move-up' },
+        onAction,
+      })
+
+      manager.handleKey('j')
+      expect(onAction).toHaveBeenCalledWith('move-down', expect.any(Object))
+    })
+
+    it('k moves selection up', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+      const onAction = vi.fn()
+
+      const manager = createKeyboardManager({
+        bindings: { j: 'move-down', k: 'move-up' },
+        onAction,
+      })
+
+      manager.handleKey('k')
+      expect(onAction).toHaveBeenCalledWith('move-up', expect.any(Object))
+    })
+
+    it('J (shift+j) for faster movement', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+      const onAction = vi.fn()
+
+      const manager = createKeyboardManager({
+        bindings: { J: 'move-down-page', K: 'move-up-page' },
+        onAction,
+      })
+
+      manager.handleKey('J')
+      expect(onAction).toHaveBeenCalledWith('move-down-page', expect.any(Object))
+    })
+  })
+
+  describe('h/l horizontal movement', () => {
+    it('h moves left', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+      const onAction = vi.fn()
+
+      const manager = createKeyboardManager({
+        bindings: { h: 'move-left', l: 'move-right' },
+        onAction,
+      })
+
+      manager.handleKey('h')
+      expect(onAction).toHaveBeenCalledWith('move-left', expect.any(Object))
+    })
+
+    it('l moves right', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+      const onAction = vi.fn()
+
+      const manager = createKeyboardManager({
+        bindings: { h: 'move-left', l: 'move-right' },
+        onAction,
+      })
+
+      manager.handleKey('l')
+      expect(onAction).toHaveBeenCalledWith('move-right', expect.any(Object))
+    })
+  })
+
+  describe('arrow key alternatives', () => {
+    it('arrow keys work alongside vim keys', async () => {
+      const { createKeyboardManager, ARROW_BINDINGS } = await import('@mdxui/terminal')
+      const onAction = vi.fn()
+
+      const manager = createKeyboardManager({
+        bindings: ARROW_BINDINGS,
+        onAction,
+      })
+
+      manager.handleKey('up')
+      expect(onAction).toHaveBeenCalledWith('move-up', expect.any(Object))
+
+      manager.handleKey('down')
+      expect(onAction).toHaveBeenCalledWith('move-down', expect.any(Object))
+
+      manager.handleKey('left')
+      expect(onAction).toHaveBeenCalledWith('move-left', expect.any(Object))
+
+      manager.handleKey('right')
+      expect(onAction).toHaveBeenCalledWith('move-right', expect.any(Object))
+    })
+  })
+})
+
+// ============================================================================
+// Selection & Activation Tests
+// ============================================================================
+
+describe('selection and activation', () => {
+  describe('enter key', () => {
+    it('triggers select action', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+      const onAction = vi.fn()
+
+      const manager = createKeyboardManager({
+        bindings: { enter: 'select', return: 'select' },
+        onAction,
+      })
+
+      manager.handleKey('enter')
+      expect(onAction).toHaveBeenCalledWith('select', expect.any(Object))
+    })
+  })
+
+  describe('space key', () => {
+    it('triggers toggle action', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+      const onAction = vi.fn()
+
+      const manager = createKeyboardManager({
+        bindings: { space: 'toggle', ' ': 'toggle' },
+        onAction,
+      })
+
+      manager.handleKey('space')
+      expect(onAction).toHaveBeenCalledWith('toggle', expect.any(Object))
+    })
+  })
+
+  describe('escape key', () => {
+    it('triggers back/cancel action', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+      const onAction = vi.fn()
+
+      const manager = createKeyboardManager({
+        bindings: { escape: 'back' },
+        onAction,
+      })
+
+      manager.handleKey('escape')
+      expect(onAction).toHaveBeenCalledWith('back', expect.any(Object))
+    })
+  })
+})
+
+// ============================================================================
+// Tab Navigation Tests
+// ============================================================================
+
+describe('tab navigation', () => {
+  describe('Tab key', () => {
+    it('Tab triggers focus-next action', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+      const onAction = vi.fn()
+
+      const manager = createKeyboardManager({
+        bindings: { tab: 'focus-next', 'shift+tab': 'focus-prev' },
+        onAction,
+      })
+
+      manager.handleKey('tab')
+      expect(onAction).toHaveBeenCalledWith('focus-next', expect.any(Object))
+    })
+  })
+
+  describe('Shift+Tab', () => {
+    it('Shift+Tab triggers focus-prev action', async () => {
+      const { createKeyboardManager } = await import('@mdxui/terminal')
+      const onAction = vi.fn()
+
+      const manager = createKeyboardManager({
+        bindings: { tab: 'focus-next', 'shift+tab': 'focus-prev' },
+        onAction,
+      })
+
+      manager.handleKey('shift+tab')
+      expect(onAction).toHaveBeenCalledWith('focus-prev', expect.any(Object))
+    })
+  })
+})
+
+// ============================================================================
+// Custom Bindings Tests
+// ============================================================================
+
+describe('custom bindings', () => {
+  it('allows custom action names', async () => {
+    const { createKeyboardManager } = await import('@mdxui/terminal')
+    const onAction = vi.fn()
+
+    const manager = createKeyboardManager({
+      bindings: {
+        d: 'delete-item',
+        r: 'rename-item',
+        n: 'new-item',
+      },
+      onAction,
+    })
+
+    manager.handleKey('d')
+    expect(onAction).toHaveBeenCalledWith('delete-item', expect.any(Object))
+  })
+
+  it('supports function as action', async () => {
+    const { createKeyboardManager } = await import('@mdxui/terminal')
+    const customAction = vi.fn()
+
+    const manager = createKeyboardManager({
+      bindings: {
+        x: customAction,
+      },
+    })
+
+    manager.handleKey('x')
+    expect(customAction).toHaveBeenCalled()
+  })
+
+  it('supports context-aware bindings', async () => {
+    const { createKeyboardManager } = await import('@mdxui/terminal')
+    const onAction = vi.fn()
+
+    const manager = createKeyboardManager({
+      bindings: { enter: 'select' },
+      onAction,
+      context: { mode: 'list' },
+    })
+
+    manager.handleKey('enter')
+    expect(onAction).toHaveBeenCalledWith('select', expect.objectContaining({
+      context: { mode: 'list' },
+    }))
+  })
+
+  it('allows updating context', async () => {
+    const { createKeyboardManager } = await import('@mdxui/terminal')
+    const onAction = vi.fn()
+
+    const manager = createKeyboardManager({
+      bindings: { enter: 'select' },
+      onAction,
+      context: { mode: 'list' },
+    })
+
+    manager.setContext({ mode: 'edit' })
+    manager.handleKey('enter')
+
+    expect(onAction).toHaveBeenCalledWith('select', expect.objectContaining({
+      context: { mode: 'edit' },
+    }))
+  })
+})
+
+// ============================================================================
+// Preset Bindings Tests
+// ============================================================================
+
+describe('preset bindings', () => {
+  it('exports VIM_BINDINGS preset', async () => {
+    const { VIM_BINDINGS } = await import('@mdxui/terminal')
+
+    expect(VIM_BINDINGS).toBeDefined()
+    expect(VIM_BINDINGS.j).toBe('move-down')
+    expect(VIM_BINDINGS.k).toBe('move-up')
+    expect(VIM_BINDINGS.h).toBe('move-left')
+    expect(VIM_BINDINGS.l).toBe('move-right')
+  })
+
+  it('exports ARROW_BINDINGS preset', async () => {
+    const { ARROW_BINDINGS } = await import('@mdxui/terminal')
+
+    expect(ARROW_BINDINGS).toBeDefined()
+    expect(ARROW_BINDINGS.up).toBe('move-up')
+    expect(ARROW_BINDINGS.down).toBe('move-down')
+    expect(ARROW_BINDINGS.left).toBe('move-left')
+    expect(ARROW_BINDINGS.right).toBe('move-right')
+  })
+
+  it('exports COMMON_BINDINGS preset', async () => {
+    const { COMMON_BINDINGS } = await import('@mdxui/terminal')
+
+    expect(COMMON_BINDINGS).toBeDefined()
+    expect(COMMON_BINDINGS.enter).toBe('select')
+    expect(COMMON_BINDINGS.escape).toBe('back')
+    expect(COMMON_BINDINGS.tab).toBe('focus-next')
+    expect(COMMON_BINDINGS['shift+tab']).toBe('focus-prev')
+  })
+
+  it('allows merging presets', async () => {
+    const { createKeyboardManager, VIM_BINDINGS, COMMON_BINDINGS } = await import('@mdxui/terminal')
+
+    const manager = createKeyboardManager({
+      bindings: { ...VIM_BINDINGS, ...COMMON_BINDINGS },
+    })
+
+    // Should have both vim and common bindings
+    expect(manager.getAction('j')).toBe('move-down')
+    expect(manager.getAction('enter')).toBe('select')
+  })
+})
+
+// ============================================================================
+// Focus Manager Context Tests
+// ============================================================================
+
+describe('FocusManagerContext', () => {
+  it('exports FocusContext', async () => {
+    const { FocusContext } = await import('@mdxui/terminal')
+
+    expect(FocusContext).toBeDefined()
+  })
+
+  it('provides default value when not in provider', async () => {
+    const { useFocusManager } = await import('@mdxui/terminal')
+
+    const result = useFocusManager()
+
+    // Should have default no-op implementations
+    expect(result.focusableIds).toEqual([])
+    expect(result.focusedId).toBeNull()
+  })
+})
+
+// ============================================================================
+// useNavigableList Hook Tests
+// ============================================================================
+
+describe('useNavigableList hook', () => {
+  it('provides current index', async () => {
+    const { useNavigableList } = await import('@mdxui/terminal')
+
+    const result = useNavigableList({
+      items: ['a', 'b', 'c'],
+    })
+
+    expect(typeof result.currentIndex).toBe('number')
+    expect(result.currentIndex).toBe(0) // Default to first item
+  })
+
+  it('provides navigation functions', async () => {
+    const { useNavigableList } = await import('@mdxui/terminal')
+
+    const result = useNavigableList({
+      items: ['a', 'b', 'c'],
+    })
+
+    expect(typeof result.moveUp).toBe('function')
+    expect(typeof result.moveDown).toBe('function')
+    expect(typeof result.moveToFirst).toBe('function')
+    expect(typeof result.moveToLast).toBe('function')
+  })
+
+  it('provides current item', async () => {
+    const { useNavigableList } = await import('@mdxui/terminal')
+
+    const result = useNavigableList({
+      items: ['a', 'b', 'c'],
+      initialIndex: 1,
+    })
+
+    expect(result.currentItem).toBe('b')
+  })
+
+  it('supports wrap option', async () => {
+    const { useNavigableList } = await import('@mdxui/terminal')
+
+    const result = useNavigableList({
+      items: ['a', 'b', 'c'],
+      wrap: true,
+    })
+
+    expect(result.wrap).toBe(true)
+  })
+
+  it('supports keyboard bindings', async () => {
+    const { useNavigableList } = await import('@mdxui/terminal')
+
+    const result = useNavigableList({
+      items: ['a', 'b', 'c'],
+      useKeyboard: true,
+    })
+
+    expect(result.keyboardEnabled).toBe(true)
+  })
+
+  it('provides setIndex function', async () => {
+    const { useNavigableList } = await import('@mdxui/terminal')
+
+    const result = useNavigableList({
+      items: ['a', 'b', 'c'],
+    })
+
+    expect(typeof result.setIndex).toBe('function')
+  })
+})
+
+// ============================================================================
+// useNavigableGrid Hook Tests
+// ============================================================================
+
+describe('useNavigableGrid hook', () => {
+  it('provides current position', async () => {
+    const { useNavigableGrid } = await import('@mdxui/terminal')
+
+    const result = useNavigableGrid({
+      rows: 3,
+      cols: 4,
+    })
+
+    expect(typeof result.row).toBe('number')
+    expect(typeof result.col).toBe('number')
+    expect(result.row).toBe(0)
+    expect(result.col).toBe(0)
+  })
+
+  it('provides navigation functions for all directions', async () => {
+    const { useNavigableGrid } = await import('@mdxui/terminal')
+
+    const result = useNavigableGrid({
+      rows: 3,
+      cols: 4,
+    })
+
+    expect(typeof result.moveUp).toBe('function')
+    expect(typeof result.moveDown).toBe('function')
+    expect(typeof result.moveLeft).toBe('function')
+    expect(typeof result.moveRight).toBe('function')
+  })
+
+  it('provides moveToCell function', async () => {
+    const { useNavigableGrid } = await import('@mdxui/terminal')
+
+    const result = useNavigableGrid({
+      rows: 3,
+      cols: 4,
+    })
+
+    expect(typeof result.moveToCell).toBe('function')
+  })
+
+  it('supports wrap in both dimensions', async () => {
+    const { useNavigableGrid } = await import('@mdxui/terminal')
+
+    const result = useNavigableGrid({
+      rows: 3,
+      cols: 4,
+      wrapHorizontal: true,
+      wrapVertical: true,
+    })
+
+    expect(result.wrapHorizontal).toBe(true)
+    expect(result.wrapVertical).toBe(true)
+  })
+
+  it('supports keyboard bindings', async () => {
+    const { useNavigableGrid } = await import('@mdxui/terminal')
+
+    const result = useNavigableGrid({
+      rows: 3,
+      cols: 4,
+      useKeyboard: true,
+    })
+
+    expect(result.keyboardEnabled).toBe(true)
+  })
+})
+
+// ============================================================================
+// Type Exports Tests
+// ============================================================================
+
+describe('type exports', () => {
+  it('exports KeyBinding type', async () => {
+    // This test verifies types are exported - checking via usage
+    const { createKeyboardManager } = await import('@mdxui/terminal')
+
+    // TypeScript would fail compilation if KeyBinding isn't exported correctly
+    const manager = createKeyboardManager({
+      bindings: { j: 'move-down' },
+    })
+
+    expect(manager).toBeDefined()
+  })
+
+  it('exports KeyboardAction type', async () => {
+    const { createKeyboardManager } = await import('@mdxui/terminal')
+
+    // KeyboardAction should support string and function
+    const manager = createKeyboardManager({
+      bindings: {
+        a: 'action-name',
+        b: () => {},
+      },
+    })
+
+    expect(manager).toBeDefined()
+  })
+
+  it('exports KeyModifiers type', async () => {
+    const { useKeyboard } = await import('@mdxui/terminal')
+
+    // KeyModifiers is used in handler parameter
+    useKeyboard((_key, modifiers) => {
+      // TypeScript checks modifiers has ctrl, alt, shift, meta
+      const _: boolean = modifiers.ctrl
+      const __: boolean = modifiers.alt
+      const ___: boolean = modifiers.shift
+    })
+  })
+
+  it('exports FocusableElement type', async () => {
+    const { useFocus } = await import('@mdxui/terminal')
+
+    // FocusableElement is the return type of useFocus
+    const element = useFocus({ id: 'test' })
+
+    expect(element.id).toBeDefined()
+    expect(typeof element.focused).toBe('boolean')
+  })
+})
+
+// ============================================================================
+// normalizeReadlineKey Tests
+// ============================================================================
+
+describe('normalizeReadlineKey', () => {
+  it('normalizes single character input', async () => {
+    const { normalizeReadlineKey } = await import('@mdxui/terminal')
+
+    const result = normalizeReadlineKey('a', undefined)
+
+    expect(result.name).toBe('a')
+    expect(result.ctrl).toBe(false)
+    expect(result.alt).toBe(false)
+    expect(result.shift).toBe(false)
+    expect(result.meta).toBe(false)
+  })
+
+  it('detects shift for uppercase letters', async () => {
+    const { normalizeReadlineKey } = await import('@mdxui/terminal')
+
+    const result = normalizeReadlineKey('A', undefined)
+
+    expect(result.name).toBe('A')
+    expect(result.shift).toBe(true)
+  })
+
+  it('normalizes return to enter', async () => {
+    const { normalizeReadlineKey } = await import('@mdxui/terminal')
+
+    const result = normalizeReadlineKey('\r', { name: 'return' })
+
+    expect(result.name).toBe('enter')
+  })
+
+  it('preserves ctrl modifier from readline key', async () => {
+    const { normalizeReadlineKey } = await import('@mdxui/terminal')
+
+    const result = normalizeReadlineKey('\x03', { name: 'c', ctrl: true })
+
+    expect(result.name).toBe('c')
+    expect(result.ctrl).toBe(true)
+  })
+
+  it('preserves shift modifier from readline key', async () => {
+    const { normalizeReadlineKey } = await import('@mdxui/terminal')
+
+    const result = normalizeReadlineKey('\t', { name: 'tab', shift: true })
+
+    expect(result.name).toBe('tab')
+    expect(result.shift).toBe(true)
+  })
+
+  it('normalizes arrow keys', async () => {
+    const { normalizeReadlineKey } = await import('@mdxui/terminal')
+
+    expect(normalizeReadlineKey('\x1b[A', { name: 'up' }).name).toBe('up')
+    expect(normalizeReadlineKey('\x1b[B', { name: 'down' }).name).toBe('down')
+    expect(normalizeReadlineKey('\x1b[C', { name: 'right' }).name).toBe('right')
+    expect(normalizeReadlineKey('\x1b[D', { name: 'left' }).name).toBe('left')
+  })
+
+  it('normalizes escape key', async () => {
+    const { normalizeReadlineKey } = await import('@mdxui/terminal')
+
+    const result = normalizeReadlineKey('\x1b', { name: 'escape' })
+
+    expect(result.name).toBe('escape')
+  })
+
+  it('handles unknown keys by lowercasing', async () => {
+    const { normalizeReadlineKey } = await import('@mdxui/terminal')
+
+    const result = normalizeReadlineKey('x', { name: 'CUSTOMKEY' })
+
+    expect(result.name).toBe('customkey')
+  })
+})
+
+// ============================================================================
+// keyToBindingString Tests
+// ============================================================================
+
+describe('keyToBindingString', () => {
+  it('returns plain key name for no modifiers', async () => {
+    const { keyToBindingString } = await import('@mdxui/terminal')
+
+    const result = keyToBindingString({
+      name: 'a',
+      ctrl: false,
+      alt: false,
+      shift: false,
+      meta: false,
+    })
+
+    expect(result).toBe('a')
+  })
+
+  it('adds ctrl modifier', async () => {
+    const { keyToBindingString } = await import('@mdxui/terminal')
+
+    const result = keyToBindingString({
+      name: 'c',
+      ctrl: true,
+      alt: false,
+      shift: false,
+      meta: false,
+    })
+
+    expect(result).toBe('ctrl+c')
+  })
+
+  it('adds shift modifier', async () => {
+    const { keyToBindingString } = await import('@mdxui/terminal')
+
+    const result = keyToBindingString({
+      name: 'tab',
+      ctrl: false,
+      alt: false,
+      shift: true,
+      meta: false,
+    })
+
+    expect(result).toBe('shift+tab')
+  })
+
+  it('combines multiple modifiers in order', async () => {
+    const { keyToBindingString } = await import('@mdxui/terminal')
+
+    const result = keyToBindingString({
+      name: 's',
+      ctrl: true,
+      alt: false,
+      shift: true,
+      meta: false,
+    })
+
+    expect(result).toBe('ctrl+shift+s')
+  })
+
+  it('includes all four modifiers when present', async () => {
+    const { keyToBindingString } = await import('@mdxui/terminal')
+
+    const result = keyToBindingString({
+      name: 'a',
+      ctrl: true,
+      alt: true,
+      shift: true,
+      meta: true,
+    })
+
+    expect(result).toBe('ctrl+alt+shift+meta+a')
+  })
+})
+
+// ============================================================================
+// normalizeOpenTUIKey Tests
+// ============================================================================
+
+describe('normalizeOpenTUIKey', () => {
+  it('normalizes basic key', async () => {
+    const { normalizeOpenTUIKey } = await import('@mdxui/terminal')
+
+    const result = normalizeOpenTUIKey({
+      name: 'a',
+      ctrl: false,
+      meta: false,
+      shift: false,
+      option: false,
+      sequence: 'a',
+    })
+
+    expect(result.name).toBe('a')
+    expect(result.ctrl).toBe(false)
+    expect(result.alt).toBe(false)
+    expect(result.shift).toBe(false)
+    expect(result.meta).toBe(false)
+  })
+
+  it('maps option to alt', async () => {
+    const { normalizeOpenTUIKey } = await import('@mdxui/terminal')
+
+    const result = normalizeOpenTUIKey({
+      name: 'h',
+      ctrl: false,
+      meta: false,
+      shift: false,
+      option: true,
+      sequence: 'h',
+    })
+
+    expect(result.alt).toBe(true)
+  })
+
+  it('normalizes return to enter', async () => {
+    const { normalizeOpenTUIKey } = await import('@mdxui/terminal')
+
+    const result = normalizeOpenTUIKey({
+      name: 'return',
+      ctrl: false,
+      meta: false,
+      shift: false,
+      option: false,
+      sequence: '\r',
+    })
+
+    expect(result.name).toBe('enter')
+  })
+
+  it('preserves all modifier keys', async () => {
+    const { normalizeOpenTUIKey } = await import('@mdxui/terminal')
+
+    const result = normalizeOpenTUIKey({
+      name: 's',
+      ctrl: true,
+      meta: true,
+      shift: true,
+      option: true,
+      sequence: 's',
+    })
+
+    expect(result.ctrl).toBe(true)
+    expect(result.meta).toBe(true)
+    expect(result.shift).toBe(true)
+    expect(result.alt).toBe(true)
+  })
+})
+
+// ============================================================================
+// createOpenTUIKeyHandler Tests
+// ============================================================================
+
+describe('createOpenTUIKeyHandler', () => {
+  it('creates a handler function', async () => {
+    const { createKeyboardManager, createOpenTUIKeyHandler } = await import('@mdxui/terminal')
+
+    const manager = createKeyboardManager({ bindings: {} })
+    const handler = createOpenTUIKeyHandler(manager)
+
+    expect(typeof handler).toBe('function')
+  })
+
+  it('passes key events to manager', async () => {
+    const { createKeyboardManager, createOpenTUIKeyHandler } = await import('@mdxui/terminal')
+    const onAction = vi.fn()
+
+    const manager = createKeyboardManager({
+      bindings: { j: 'move-down' },
+      onAction,
+    })
+    const handler = createOpenTUIKeyHandler(manager)
+
+    handler({
+      name: 'j',
+      ctrl: false,
+      meta: false,
+      shift: false,
+      option: false,
+      sequence: 'j',
+    })
+
+    expect(onAction).toHaveBeenCalledWith('move-down', expect.any(Object))
+  })
+
+  it('skips release events', async () => {
+    const { createKeyboardManager, createOpenTUIKeyHandler } = await import('@mdxui/terminal')
+    const onAction = vi.fn()
+
+    const manager = createKeyboardManager({
+      bindings: { j: 'move-down' },
+      onAction,
+    })
+    const handler = createOpenTUIKeyHandler(manager)
+
+    handler({
+      name: 'j',
+      ctrl: false,
+      meta: false,
+      shift: false,
+      option: false,
+      sequence: 'j',
+      eventType: 'release',
+    })
+
+    expect(onAction).not.toHaveBeenCalled()
+  })
+
+  it('handles modifier keys', async () => {
+    const { createKeyboardManager, createOpenTUIKeyHandler } = await import('@mdxui/terminal')
+    const onAction = vi.fn()
+
+    const manager = createKeyboardManager({
+      bindings: { 'ctrl+c': 'cancel' },
+      onAction,
+    })
+    const handler = createOpenTUIKeyHandler(manager)
+
+    handler({
+      name: 'c',
+      ctrl: true,
+      meta: false,
+      shift: false,
+      option: false,
+      sequence: '\x03',
+    })
+
+    expect(onAction).toHaveBeenCalledWith('cancel', expect.any(Object))
+  })
+})
+
+// ============================================================================
+// attachKeyboardManager Tests
+// ============================================================================
+
+describe('attachKeyboardManager', () => {
+  it('exports attachKeyboardManager function', async () => {
+    const { attachKeyboardManager } = await import('@mdxui/terminal')
+
+    expect(typeof attachKeyboardManager).toBe('function')
+  })
+
+  it('throws error for non-TTY stdin', async () => {
+    const { createKeyboardManager, attachKeyboardManager } = await import('@mdxui/terminal')
+
+    const manager = createKeyboardManager({ bindings: {} })
+
+    // Create a mock non-TTY stream
+    const mockStream = {
+      isTTY: false,
+    } as NodeJS.ReadStream
+
+    expect(() => attachKeyboardManager(manager, { input: mockStream })).toThrow('requires a TTY stdin')
+  })
+})
+
+// ============================================================================
+// Type Exports for Terminal Input
+// ============================================================================
+
+describe('terminal input type exports', () => {
+  it('exports NormalizedKey type', async () => {
+    // Type check - if this compiles, the type is exported
+    const { normalizeReadlineKey } = await import('@mdxui/terminal')
+
+    const key = normalizeReadlineKey('a', undefined)
+
+    // Verify structure matches NormalizedKey
+    expect('name' in key).toBe(true)
+    expect('ctrl' in key).toBe(true)
+    expect('alt' in key).toBe(true)
+    expect('shift' in key).toBe(true)
+    expect('meta' in key).toBe(true)
+  })
+
+  it('exports ReadlineKey type', async () => {
+    const { normalizeReadlineKey } = await import('@mdxui/terminal')
+
+    // ReadlineKey is accepted as parameter type
+    const key: { name: string; ctrl: boolean } = { name: 'a', ctrl: false }
+    const result = normalizeReadlineKey('a', key)
+
+    expect(result).toBeDefined()
+  })
+
+  it('exports OpenTUIKeyEvent type', async () => {
+    const { createOpenTUIKeyHandler, createKeyboardManager } = await import('@mdxui/terminal')
+
+    const manager = createKeyboardManager({ bindings: {} })
+    const handler = createOpenTUIKeyHandler(manager)
+
+    // OpenTUIKeyEvent structure is accepted
+    handler({
+      name: 'a',
+      ctrl: false,
+      meta: false,
+      shift: false,
+      option: false,
+      sequence: 'a',
+    })
+  })
+
+  it('exports AttachKeyboardOptions type', async () => {
+    // Type check - if this compiles with the options, the type works
+    const { attachKeyboardManager, createKeyboardManager } = await import('@mdxui/terminal')
+
+    const manager = createKeyboardManager({ bindings: {} })
+
+    // This should type-check even though we can't run it without a TTY
+    const options = { exitOnCtrlC: false }
+
+    // Just verify the options shape is correct
+    expect(options.exitOnCtrlC).toBe(false)
+  })
+
+  it('exports DetachKeyboard type', async () => {
+    const { createOpenTUIKeyHandler, createKeyboardManager } = await import('@mdxui/terminal')
+
+    // DetachKeyboard is a function type
+    // We can't actually test attachKeyboardManager without a TTY,
+    // but we can verify the return type concept works
+    const manager = createKeyboardManager({ bindings: {} })
+
+    // A DetachKeyboard function is just () => void
+    const detach: () => void = () => {}
+
+    expect(typeof detach).toBe('function')
+  })
+})