@mdxui/terminal 2.0.0

package/src/__tests__/integration.test.ts

@@ -0,0 +1,905 @@
+/**
+ * @mdxui/terminal Integration Tests
+ *
+ * TDD RED Phase: End-to-end integration tests for the terminal render pipeline.
+ * These tests verify that the full system works together correctly:
+ * - Components render to string output
+ * - Nested components compose properly
+ * - Theme applies across component trees
+ * - Focus state affects rendering
+ * - Keyboard input updates component state
+ * - Terminal capabilities are respected
+ *
+ * All tests should initially define contracts that the implementation must fulfill.
+ *
+ * NOTE: React hooks (useFocus, useNavigableList, etc.) cannot be tested outside
+ * of a React component context. Those tests use the keyboard manager and other
+ * non-hook APIs to verify integration behavior.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import React from 'react'
+
+// ============================================================================
+// Test Utilities
+// ============================================================================
+
+/**
+ * Simulates rendering a component to terminal strings.
+ */
+async function renderToTerminal(element: React.ReactElement): Promise<string[]> {
+  const { renderComponent } = await import('../components')
+
+  if (typeof renderComponent !== 'function') {
+    throw new Error('renderComponent function not exported from @mdxui/terminal/components')
+  }
+
+  return renderComponent(element)
+}
+
+/**
+ * Check if a string contains ANSI escape codes
+ */
+function hasAnsiCodes(str: string): boolean {
+  // eslint-disable-next-line no-control-regex
+  return /\x1b\[[\d;]*m/.test(str)
+}
+
+/**
+ * Strip ANSI codes from string for content testing
+ */
+function stripAnsi(str: string): string {
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/\x1b\[[\d;]*m/g, '')
+}
+
+/**
+ * Join and strip ANSI from rendered lines
+ */
+function getPlainContent(lines: string[]): string {
+  return stripAnsi(lines.join('\n'))
+}
+
+// ============================================================================
+// 1. Full Render Pipeline Tests
+// ============================================================================
+
+describe('Integration', () => {
+  describe('Full Render Pipeline', () => {
+    beforeEach(() => {
+      vi.resetModules()
+    })
+
+    it('TerminalApp renders to string output', async () => {
+      const { TerminalApp, Text } = await import('..')
+
+      const element = React.createElement(
+        TerminalApp,
+        { children: React.createElement(Text, {}, 'Hello Terminal') }
+      )
+
+      const lines = await renderToTerminal(element)
+
+      // Should produce at least one line of output
+      expect(lines.length).toBeGreaterThan(0)
+
+      // Should contain the text content
+      const content = getPlainContent(lines)
+      expect(content).toContain('Hello Terminal')
+    })
+
+    it('nested components render correctly', async () => {
+      const { Box, Text } = await import('../components')
+
+      // Create nested structure: Box > Box > Text
+      const innerText = React.createElement(Text, { color: 'cyan' }, 'Inner content')
+      const innerBox = React.createElement(Box, { border: 'single', padding: 1 }, innerText)
+      const outerBox = React.createElement(Box, { border: 'double', padding: 1 }, innerBox)
+
+      const lines = await renderToTerminal(outerBox)
+
+      const content = getPlainContent(lines)
+
+      // Should contain the nested text
+      expect(content).toContain('Inner content')
+
+      // Should have double border characters from outer box
+      expect(lines.join('')).toMatch(/[\u2550\u2554\u2557\u255A\u255D]/)
+
+      // Should have single border characters from inner box
+      expect(lines.join('')).toMatch(/[\u2500\u250C\u2510\u2514\u2518]/)
+    })
+
+    it('theme applies to all children', async () => {
+      const { Box, Text } = await import('../components')
+
+      // Test that styled text renders with ANSI codes
+      const textElement = React.createElement(Text, { color: 'red', bold: true }, 'Styled text')
+      const boxElement = React.createElement(
+        Box,
+        { border: 'single' },
+        textElement
+      )
+
+      const lines = await renderToTerminal(boxElement)
+
+      // Output should contain ANSI codes (theme colors applied)
+      const output = lines.join('')
+      expect(hasAnsiCodes(output)).toBe(true)
+
+      // Content should still be present
+      expect(getPlainContent(lines)).toContain('Styled text')
+    })
+
+    it('focus state affects rendering', async () => {
+      const { Box, Input } = await import('../components')
+
+      // Unfocused input
+      const unfocusedInput = React.createElement(Input, {
+        value: 'test',
+        focused: false,
+        onChange: () => {},
+      })
+      const unfocusedLines = await renderToTerminal(
+        React.createElement(Box, {}, unfocusedInput)
+      )
+
+      // Focused input
+      const focusedInput = React.createElement(Input, {
+        value: 'test',
+        focused: true,
+        onChange: () => {},
+      })
+      const focusedLines = await renderToTerminal(
+        React.createElement(Box, {}, focusedInput)
+      )
+
+      // Focused input should have different styling (more ANSI codes for cursor/highlight)
+      const unfocusedOutput = unfocusedLines.join('')
+      const focusedOutput = focusedLines.join('')
+
+      // Both should contain the value
+      expect(stripAnsi(unfocusedOutput)).toContain('test')
+      expect(stripAnsi(focusedOutput)).toContain('test')
+
+      // Focused should have cursor indicator (inverse video or underline)
+      expect(focusedOutput).toMatch(/\x1b\[7m|\x1b\[4m/)
+    })
+  })
+
+  // ============================================================================
+  // 2. Keyboard Integration Tests
+  // ============================================================================
+
+  describe('Keyboard Integration', () => {
+    beforeEach(() => {
+      vi.resetModules()
+    })
+
+    it('key press updates component state', async () => {
+      const { createKeyboardManager, VIM_BINDINGS } = await import('..')
+
+      // Track state changes
+      let currentIndex = 0
+      const onAction = vi.fn((action: string) => {
+        if (action === 'move-down') currentIndex++
+        if (action === 'move-up') currentIndex--
+      })
+
+      const manager = createKeyboardManager({
+        bindings: VIM_BINDINGS,
+        onAction,
+      })
+
+      // Simulate key presses
+      manager.handleKey('j') // move down
+      expect(currentIndex).toBe(1)
+      expect(onAction).toHaveBeenCalledWith('move-down', expect.any(Object))
+
+      manager.handleKey('j') // move down
+      expect(currentIndex).toBe(2)
+
+      manager.handleKey('k') // move up
+      expect(currentIndex).toBe(1)
+      expect(onAction).toHaveBeenCalledWith('move-up', expect.any(Object))
+    })
+
+    it('focus changes update rendering via props', async () => {
+      const { Input } = await import('../components')
+
+      // Test that focus prop changes rendering
+      const unfocusedInput = React.createElement(Input, {
+        value: 'test',
+        focused: false,
+        onChange: () => {},
+      })
+      const unfocusedLines = await renderToTerminal(unfocusedInput)
+
+      const focusedInput = React.createElement(Input, {
+        value: 'test',
+        focused: true,
+        onChange: () => {},
+      })
+      const focusedLines = await renderToTerminal(focusedInput)
+
+      // Both should contain the value
+      expect(getPlainContent(unfocusedLines)).toContain('test')
+      expect(getPlainContent(focusedLines)).toContain('test')
+
+      // Focused state should produce different output
+      const unfocusedOutput = unfocusedLines.join('')
+      const focusedOutput = focusedLines.join('')
+
+      // Focused input should have cursor indicator (inverse video or underline)
+      expect(focusedOutput).toMatch(/\x1b\[7m|\x1b\[4m/)
+    })
+
+    it('navigation state tracked via keyboard manager', async () => {
+      const { createKeyboardManager, VIM_BINDINGS } = await import('..')
+
+      // Simulate navigable list state management
+      const items = ['Apple', 'Banana', 'Cherry', 'Date']
+      let currentIndex = 0
+
+      const onAction = vi.fn((action: string) => {
+        if (action === 'move-down') {
+          currentIndex = Math.min(currentIndex + 1, items.length - 1)
+        }
+        if (action === 'move-up') {
+          currentIndex = Math.max(currentIndex - 1, 0)
+        }
+        if (action === 'move-first') {
+          currentIndex = 0
+        }
+        if (action === 'move-last') {
+          currentIndex = items.length - 1
+        }
+      })
+
+      const manager = createKeyboardManager({
+        bindings: VIM_BINDINGS,
+        onAction,
+      })
+
+      // Initially at first item
+      expect(currentIndex).toBe(0)
+      expect(items[currentIndex]).toBe('Apple')
+
+      // Move down
+      manager.handleKey('j')
+      expect(currentIndex).toBe(1)
+      expect(items[currentIndex]).toBe('Banana')
+
+      // Move to last (gg sequence for move-first, G for move-last)
+      manager.handleKey('G')
+      expect(currentIndex).toBe(3)
+      expect(items[currentIndex]).toBe('Date')
+
+      // Move to first
+      manager.handleKey('g')
+      manager.handleKey('g')
+      expect(currentIndex).toBe(0)
+      expect(items[currentIndex]).toBe('Apple')
+    })
+
+    it('actions trigger callbacks', async () => {
+      const { createKeyboardManager } = await import('..')
+
+      const onSelect = vi.fn()
+      const onBack = vi.fn()
+      const onQuit = vi.fn()
+
+      const manager = createKeyboardManager({
+        bindings: {
+          enter: 'select',
+          escape: 'back',
+          q: 'quit',
+        },
+        onAction: (action) => {
+          if (action === 'select') onSelect()
+          if (action === 'back') onBack()
+          if (action === 'quit') onQuit()
+        },
+      })
+
+      manager.handleKey('enter')
+      expect(onSelect).toHaveBeenCalled()
+
+      manager.handleKey('escape')
+      expect(onBack).toHaveBeenCalled()
+
+      manager.handleKey('q')
+      expect(onQuit).toHaveBeenCalled()
+    })
+  })
+
+  // ============================================================================
+  // 3. Real Components Tests
+  // ============================================================================
+
+  describe('Real Components', () => {
+    beforeEach(() => {
+      vi.resetModules()
+    })
+
+    it('dashboard with sidebar and content renders', async () => {
+      const { Box, SidebarItem, Text } = await import('../components')
+
+      // Build a dashboard layout - render sidebar items individually to verify they work
+      const sidebarItem1 = React.createElement(SidebarItem, { label: 'Dashboard', icon: '\u2302', active: true })
+      const sidebarItem2 = React.createElement(SidebarItem, { label: 'Settings', icon: '\u2699' })
+
+      const lines1 = await renderToTerminal(sidebarItem1)
+      const lines2 = await renderToTerminal(sidebarItem2)
+
+      // Each sidebar item should render its label
+      expect(getPlainContent(lines1)).toContain('Dashboard')
+      expect(getPlainContent(lines2)).toContain('Settings')
+
+      // Now test the main content area
+      const content = React.createElement(
+        Box,
+        { flexDirection: 'column' },
+        React.createElement(Text, { bold: true }, 'Welcome to Dashboard'),
+        React.createElement(Text, {}, 'Select an option from the sidebar')
+      )
+
+      const contentLines = await renderToTerminal(content)
+      const plainContent = getPlainContent(contentLines)
+
+      // Should contain main content
+      expect(plainContent).toContain('Welcome to Dashboard')
+      expect(plainContent).toContain('Select an option from the sidebar')
+    })
+
+    it('form with inputs and buttons renders', async () => {
+      const { Input, Button, Text } = await import('../components')
+
+      // Test individual form components to verify they render correctly
+      const title = React.createElement(Text, { bold: true }, 'Login Form')
+      const titleLines = await renderToTerminal(title)
+      expect(getPlainContent(titleLines)).toContain('Login Form')
+
+      // Test input with label
+      const usernameInput = React.createElement(Input, {
+        label: 'Username',
+        value: '',
+        placeholder: 'Enter username',
+        onChange: () => {},
+      })
+      const inputLines = await renderToTerminal(usernameInput)
+      const inputContent = getPlainContent(inputLines)
+      // Input should contain label and/or placeholder
+      expect(inputContent).toMatch(/Username|Enter username/)
+
+      // Test password input (masked)
+      const passwordInput = React.createElement(Input, {
+        value: 'secret123',
+        type: 'password',
+        onChange: () => {},
+      })
+      const passwordLines = await renderToTerminal(passwordInput)
+      const passwordContent = getPlainContent(passwordLines)
+      // Password should be masked (not showing actual value)
+      expect(passwordContent).not.toContain('secret123')
+
+      // Test buttons
+      const loginButton = React.createElement(Button, { variant: 'primary', onPress: () => {} }, 'Login')
+      const cancelButton = React.createElement(Button, { variant: 'default', onPress: () => {} }, 'Cancel')
+
+      const loginLines = await renderToTerminal(loginButton)
+      const cancelLines = await renderToTerminal(cancelButton)
+
+      expect(getPlainContent(loginLines)).toContain('Login')
+      expect(getPlainContent(cancelLines)).toContain('Cancel')
+    })
+
+    it('table with data renders', async () => {
+      const { Table } = await import('../components')
+
+      interface User {
+        name: string
+        email: string
+        role: string
+      }
+
+      const data: User[] = [
+        { name: 'Alice', email: 'alice@example.com', role: 'Admin' },
+        { name: 'Bob', email: 'bob@example.com', role: 'User' },
+        { name: 'Charlie', email: 'charlie@example.com', role: 'User' },
+      ]
+
+      const columns = [
+        { key: 'name' as const, header: 'Name', width: 15 },
+        { key: 'email' as const, header: 'Email', width: 25 },
+        { key: 'role' as const, header: 'Role', width: 10 },
+      ]
+
+      const table = React.createElement(Table, { data, columns })
+
+      const lines = await renderToTerminal(table)
+      const plainContent = getPlainContent(lines)
+
+      // Should contain headers
+      expect(plainContent).toContain('Name')
+      expect(plainContent).toContain('Email')
+      expect(plainContent).toContain('Role')
+
+      // Should contain data
+      expect(plainContent).toContain('Alice')
+      expect(plainContent).toContain('alice@example.com')
+      expect(plainContent).toContain('Admin')
+      expect(plainContent).toContain('Bob')
+      expect(plainContent).toContain('Charlie')
+    })
+
+    it('dialog modal renders', async () => {
+      const { Dialog, Box, Text, Button } = await import('../components')
+
+      const dialogContent = React.createElement(
+        Box,
+        { flexDirection: 'column', gap: 1 },
+        React.createElement(Text, {}, 'Are you sure you want to delete this item?'),
+        React.createElement(
+          Box,
+          { flexDirection: 'row', gap: 2 },
+          React.createElement(Button, { variant: 'destructive', onPress: () => {} }, 'Delete'),
+          React.createElement(Button, { variant: 'default', onPress: () => {} }, 'Cancel')
+        )
+      )
+
+      const dialog = React.createElement(Dialog, {
+        open: true,
+        title: 'Confirm Deletion',
+        onClose: () => {},
+        children: dialogContent,
+      })
+
+      const lines = await renderToTerminal(dialog)
+      const plainContent = getPlainContent(lines)
+
+      // Should contain dialog title
+      expect(plainContent).toContain('Confirm Deletion')
+
+      // Should contain dialog content
+      expect(plainContent).toContain('Are you sure you want to delete this item?')
+      expect(plainContent).toContain('Delete')
+      expect(plainContent).toContain('Cancel')
+
+      // Should have modal styling (border)
+      const output = lines.join('')
+      expect(output).toMatch(/[\u250C\u2554\u256D]/) // top-left border corners
+    })
+  })
+
+  // ============================================================================
+  // 4. Terminal Capabilities Tests
+  // ============================================================================
+
+  describe('Terminal Capabilities', () => {
+    beforeEach(() => {
+      vi.resetModules()
+    })
+
+    it('color degradation works (256 to 16)', async () => {
+      const { degradeColor } = await import('../theme')
+
+      // ANSI 256 blue (color 33)
+      const color256 = '\x1b[38;5;33m'
+
+      // Degrade to 16 colors
+      const color16 = degradeColor(color256, '16')
+
+      // Should be a basic 16-color code (30-37 or 90-97)
+      expect(color16).toMatch(/\x1b\[3[0-7]m|\x1b\[9[0-7]m/)
+
+      // Should not be empty
+      expect(color16.length).toBeGreaterThan(0)
+    })
+
+    it('color degradation returns empty for none support', async () => {
+      const { degradeColor } = await import('../theme')
+
+      const color256 = '\x1b[38;5;33m'
+      const colorNone = degradeColor(color256, 'none')
+
+      // Should return empty string for no color support
+      expect(colorNone).toBe('')
+    })
+
+    it('truecolor to 256 conversion works', async () => {
+      const { degradeColor } = await import('../theme')
+
+      // Truecolor blue
+      const truecolor = '\x1b[38;2;59;130;246m'
+
+      // Degrade to 256 colors
+      const color256 = degradeColor(truecolor, '256')
+
+      // Should be a valid 256-color code
+      expect(color256).toMatch(/\x1b\[38;5;\d+m/)
+    })
+
+    it('size constraints respected', async () => {
+      const { Box, Text } = await import('../components')
+
+      // Create a box with fixed dimensions
+      const constrainedBox = React.createElement(
+        Box,
+        { width: 30, height: 5, border: 'single' },
+        React.createElement(Text, {}, 'Short content')
+      )
+
+      const lines = await renderToTerminal(constrainedBox)
+
+      // Should have exactly 5 lines (the specified height)
+      expect(lines.length).toBe(5)
+
+      // Content should be within the box
+      const content = getPlainContent(lines)
+      expect(content).toContain('Short content')
+    })
+
+    it('ANSI codes properly formatted in output', async () => {
+      const { Text } = await import('../components')
+
+      // Create styled text
+      const styledText = React.createElement(
+        Text,
+        { bold: true, color: 'red', underline: true },
+        'Styled content'
+      )
+
+      const lines = await renderToTerminal(styledText)
+      const output = lines.join('')
+
+      // Should contain bold ANSI code
+      expect(output).toContain('\x1b[1m')
+
+      // Should contain red foreground ANSI code
+      expect(output).toContain('\x1b[31m')
+
+      // Should contain underline ANSI code
+      expect(output).toContain('\x1b[4m')
+
+      // Should contain reset ANSI code at end
+      expect(output).toContain('\x1b[0m')
+
+      // Content should still be present
+      expect(stripAnsi(output)).toContain('Styled content')
+    })
+
+    it('detectColorSupport returns valid level', async () => {
+      const { detectColorSupport } = await import('../theme')
+
+      const support = detectColorSupport()
+
+      // Should return one of the valid levels
+      expect(['none', '16', '256', 'truecolor']).toContain(support)
+    })
+  })
+
+  // ============================================================================
+  // 5. Component Composition Tests
+  // ============================================================================
+
+  describe('Component Composition', () => {
+    beforeEach(() => {
+      vi.resetModules()
+    })
+
+    it('Badge inside Text renders correctly', async () => {
+      const { Box, Text, Badge } = await import('../components')
+
+      const element = React.createElement(
+        Box,
+        {},
+        React.createElement(Text, {}, 'Status: '),
+        React.createElement(Badge, { variant: 'success' }, 'Active')
+      )
+
+      const lines = await renderToTerminal(element)
+      const content = getPlainContent(lines)
+
+      expect(content).toContain('Status:')
+      expect(content).toContain('Active')
+
+      // Badge should have some styling (ANSI codes)
+      // Success variant should have color styling
+      const output = lines.join('')
+      // Verify badge renders content - styling is implementation detail
+      expect(content).toMatch(/Active/)
+    })
+
+    it('Breadcrumb navigation renders', async () => {
+      const { Breadcrumb } = await import('../components')
+
+      const breadcrumb = React.createElement(Breadcrumb, {
+        items: [
+          { label: 'Home', path: '/' },
+          { label: 'Products', path: '/products' },
+          { label: 'Electronics', path: '/products/electronics' },
+          { label: 'Phones' }, // Current page (no path)
+        ],
+      })
+
+      const lines = await renderToTerminal(breadcrumb)
+      const content = getPlainContent(lines)
+
+      // All items should be rendered
+      expect(content).toContain('Home')
+      expect(content).toContain('Products')
+      expect(content).toContain('Electronics')
+      expect(content).toContain('Phones')
+
+      // Should have separators
+      expect(content).toMatch(/[\/>\u203A\u2192]/)
+    })
+
+    it('Spinner animation frame renders', async () => {
+      const { Spinner } = await import('../components')
+
+      const spinner = React.createElement(Spinner, { label: 'Loading...' })
+
+      const lines = await renderToTerminal(spinner)
+      const content = getPlainContent(lines)
+
+      // Should contain the label
+      expect(content).toContain('Loading...')
+
+      // Should contain a spinner frame character
+      // Common spinner chars: dots, braille patterns, bars
+      expect(lines.join('')).toMatch(/[\u280B\u2819\u2839\u28B9\u28F9\u28FC\u28E4\u2846|\\/-]/)
+    })
+
+    it('List with selection renders', async () => {
+      const { List } = await import('../components')
+
+      const list = React.createElement(List, {
+        items: ['First item', 'Second item', 'Third item'],
+        selectedIndex: 1,
+        onSelect: () => {},
+      })
+
+      const lines = await renderToTerminal(list)
+      const content = getPlainContent(lines)
+
+      // All items should be present
+      expect(content).toContain('First item')
+      expect(content).toContain('Second item')
+      expect(content).toContain('Third item')
+
+      // Selected item should have highlight styling
+      const output = lines.join('')
+      expect(hasAnsiCodes(output)).toBe(true)
+    })
+  })
+
+  // ============================================================================
+  // 6. Theme Provider Integration Tests
+  // ============================================================================
+
+  describe('Theme Provider Integration', () => {
+    beforeEach(() => {
+      vi.resetModules()
+    })
+
+    it('dark theme provides dark mode colors', async () => {
+      const { createTerminalTheme } = await import('../theme')
+
+      const darkTheme = createTerminalTheme({ mode: 'dark' })
+
+      expect(darkTheme.mode).toBe('dark')
+      expect(darkTheme.colors.foreground).toBeDefined()
+      expect(darkTheme.colors.background).toBeDefined()
+      expect(darkTheme.colors.primary).toBeDefined()
+    })
+
+    it('light theme provides light mode colors', async () => {
+      const { createTerminalTheme } = await import('../theme')
+
+      const lightTheme = createTerminalTheme({ mode: 'light' })
+
+      expect(lightTheme.mode).toBe('light')
+      expect(lightTheme.colors.foreground).toBeDefined()
+      expect(lightTheme.colors.background).toBeDefined()
+    })
+
+    it('createTerminalTheme creates usable theme', async () => {
+      const { createTerminalTheme } = await import('../theme')
+
+      const darkTheme = createTerminalTheme({ mode: 'dark' })
+
+      expect(darkTheme.mode).toBe('dark')
+      expect(darkTheme.colors.foreground).toBeDefined()
+      expect(typeof darkTheme.colors.primary).toBe('string')
+      expect(darkTheme.colors.primary).toContain('\x1b[') // ANSI code
+    })
+  })
+
+  // ============================================================================
+  // 7. Focus Provider Integration Tests
+  // ============================================================================
+
+  describe('Focus Provider Integration', () => {
+    beforeEach(() => {
+      vi.resetModules()
+    })
+
+    it('FocusContext is exported and available', async () => {
+      const { FocusContext } = await import('..')
+
+      // FocusContext should be a valid React context
+      expect(FocusContext).toBeDefined()
+      expect(FocusContext.Provider).toBeDefined()
+    })
+
+    it('createKeyboardManager can track focus state externally', async () => {
+      const { createKeyboardManager, COMMON_BINDINGS } = await import('..')
+
+      // Simulate focus management with keyboard manager
+      let focusedIndex = 0
+      const focusableElements = ['input-1', 'input-2', 'button-1']
+
+      const onAction = vi.fn((action: string) => {
+        if (action === 'focus-next') {
+          focusedIndex = (focusedIndex + 1) % focusableElements.length
+        }
+        if (action === 'focus-prev') {
+          focusedIndex = (focusedIndex - 1 + focusableElements.length) % focusableElements.length
+        }
+      })
+
+      const manager = createKeyboardManager({
+        bindings: COMMON_BINDINGS,
+        onAction,
+      })
+
+      // Tab should move focus forward
+      manager.handleKey('tab')
+      expect(focusedIndex).toBe(1)
+
+      manager.handleKey('tab')
+      expect(focusedIndex).toBe(2)
+
+      // Shift+Tab should move focus backward
+      manager.handleKey('shift+tab')
+      expect(focusedIndex).toBe(1)
+    })
+  })
+
+  // ============================================================================
+  // 8. Grid Navigation Tests
+  // ============================================================================
+
+  describe('Grid Navigation', () => {
+    beforeEach(() => {
+      vi.resetModules()
+    })
+
+    it('keyboard manager supports 2D grid navigation', async () => {
+      const { createKeyboardManager, VIM_BINDINGS, ARROW_BINDINGS } = await import('..')
+
+      // Simulate 2D grid state
+      const rows = 3
+      const cols = 4
+      let row = 0
+      let col = 0
+
+      const onAction = vi.fn((action: string) => {
+        switch (action) {
+          case 'move-up':
+            row = Math.max(0, row - 1)
+            break
+          case 'move-down':
+            row = Math.min(rows - 1, row + 1)
+            break
+          case 'move-left':
+            col = Math.max(0, col - 1)
+            break
+          case 'move-right':
+            col = Math.min(cols - 1, col + 1)
+            break
+        }
+      })
+
+      const manager = createKeyboardManager({
+        bindings: { ...VIM_BINDINGS, ...ARROW_BINDINGS },
+        onAction,
+      })
+
+      // Initial position
+      expect(row).toBe(0)
+      expect(col).toBe(0)
+
+      // Move right (l or right arrow)
+      manager.handleKey('l')
+      expect(col).toBe(1)
+
+      manager.handleKey('right')
+      expect(col).toBe(2)
+
+      // Move down (j or down arrow)
+      manager.handleKey('j')
+      expect(row).toBe(1)
+
+      manager.handleKey('down')
+      expect(row).toBe(2)
+
+      // Move left (h or left arrow)
+      manager.handleKey('h')
+      expect(col).toBe(1)
+
+      // Move up (k or up arrow)
+      manager.handleKey('k')
+      expect(row).toBe(1)
+
+      // Boundary checking - should not go past edges
+      manager.handleKey('up') // row = 0
+      manager.handleKey('up') // should stay at 0
+      expect(row).toBe(0)
+
+      manager.handleKey('left') // col = 0
+      manager.handleKey('left') // should stay at 0
+      expect(col).toBe(0)
+    })
+  })
+
+  // ============================================================================
+  // 9. Error Handling Tests
+  // ============================================================================
+
+  describe('Error Handling', () => {
+    beforeEach(() => {
+      vi.resetModules()
+    })
+
+    it('renders gracefully with empty children', async () => {
+      const { Box } = await import('../components')
+
+      const emptyBox = React.createElement(Box, { border: 'single', width: 10, height: 3 })
+
+      const lines = await renderToTerminal(emptyBox)
+
+      // Should still render the box structure
+      expect(lines.length).toBeGreaterThan(0)
+    })
+
+    it('handles null children without crashing', async () => {
+      const { Box, Text } = await import('../components')
+
+      const element = React.createElement(
+        Box,
+        {},
+        React.createElement(Text, {}, 'Before'),
+        null,
+        React.createElement(Text, {}, 'After')
+      )
+
+      const lines = await renderToTerminal(element)
+      const content = getPlainContent(lines)
+
+      expect(content).toContain('Before')
+      expect(content).toContain('After')
+    })
+
+    it('disabled keyboard manager ignores keys', async () => {
+      const { createKeyboardManager } = await import('..')
+
+      const onAction = vi.fn()
+      const manager = createKeyboardManager({
+        bindings: { j: 'move-down' },
+        onAction,
+        enabled: false,
+      })
+
+      // Should not trigger when disabled
+      manager.handleKey('j')
+      expect(onAction).not.toHaveBeenCalled()
+
+      // Should work after enabling
+      manager.enable()
+      manager.handleKey('j')
+      expect(onAction).toHaveBeenCalledWith('move-down', expect.any(Object))
+    })
+  })
+})