@mdxui/terminal 2.0.0

package/src/__tests__/renderers/ansi.test.ts

@@ -0,0 +1,1366 @@
+/**
+ * @mdxui/terminal ANSI Renderer Tests
+ *
+ * TDD RED Phase: Tests for the ANSI escape code renderer.
+ * All tests should FAIL initially because renderANSI doesn't exist yet.
+ *
+ * The ANSI renderer converts UINode trees to colored terminal output strings
+ * using ANSI escape codes for styling (colors, bold, underline, etc.).
+ *
+ * This is part of the Universal Terminal UI 6-tier rendering system.
+ */
+import { describe, it, expect, beforeEach } from 'vitest'
+
+// ============================================================================
+// Types for ANSI Renderer (these define the contract)
+// ============================================================================
+
+/**
+ * UINode represents a node in the terminal UI tree.
+ * This is the input format for all renderers.
+ */
+interface UINode {
+  type: string
+  props?: Record<string, unknown>
+  children?: UINode[] | string
+  text?: string
+}
+
+/**
+ * ANSI renderer options
+ */
+interface ANSIRenderOptions {
+  /** Color support level */
+  colorSupport?: 'none' | '16' | '256' | 'truecolor'
+  /** Theme mode */
+  theme?: 'dark' | 'light'
+  /** Terminal width for wrapping */
+  width?: number
+  /** Whether to include reset codes between elements */
+  resetBetweenElements?: boolean
+}
+
+// ============================================================================
+// Test Suite: Basic ANSI Output
+// ============================================================================
+
+describe('renderANSI', () => {
+  describe('basic text rendering', () => {
+    it('renders plain text without ANSI codes', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Hello World',
+      }
+
+      const result = renderANSI(node)
+      expect(result).toBe('Hello World')
+    })
+
+    it('renders nested text nodes', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'box',
+        children: [
+          { type: 'text', text: 'Line 1' },
+          { type: 'text', text: 'Line 2' },
+        ],
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('Line 1')
+      expect(result).toContain('Line 2')
+    })
+
+    it('returns empty string for empty node', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: '',
+      }
+
+      const result = renderANSI(node)
+      expect(result).toBe('')
+    })
+  })
+
+  // ============================================================================
+  // Foreground Colors (Basic 16 ANSI)
+  // ============================================================================
+
+  describe('foreground colors (16 color)', () => {
+    it('applies red foreground color', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Error',
+        props: { color: 'red' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[31m') // Red foreground
+      expect(result).toContain('Error')
+      expect(result).toContain('\x1b[0m') // Reset
+    })
+
+    it('applies green foreground color', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Success',
+        props: { color: 'green' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[32m') // Green foreground
+      expect(result).toContain('Success')
+    })
+
+    it('applies yellow foreground color', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Warning',
+        props: { color: 'yellow' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[33m') // Yellow foreground
+    })
+
+    it('applies blue foreground color', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Info',
+        props: { color: 'blue' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[34m') // Blue foreground
+    })
+
+    it('applies magenta foreground color', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Highlight',
+        props: { color: 'magenta' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[35m') // Magenta foreground
+    })
+
+    it('applies cyan foreground color', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Accent',
+        props: { color: 'cyan' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[36m') // Cyan foreground
+    })
+
+    it('applies white foreground color', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Light',
+        props: { color: 'white' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[37m') // White foreground
+    })
+
+    it('applies black foreground color', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Dark',
+        props: { color: 'black' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[30m') // Black foreground
+    })
+  })
+
+  // ============================================================================
+  // Bright Foreground Colors
+  // ============================================================================
+
+  describe('bright foreground colors', () => {
+    it('applies bright red foreground', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Alert',
+        props: { color: 'brightRed' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[91m') // Bright red
+    })
+
+    it('applies bright green foreground', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Done',
+        props: { color: 'brightGreen' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[92m') // Bright green
+    })
+
+    it('applies bright yellow foreground', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Caution',
+        props: { color: 'brightYellow' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[93m') // Bright yellow
+    })
+
+    it('applies bright blue foreground', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Link',
+        props: { color: 'brightBlue' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[94m') // Bright blue
+    })
+
+    it('applies bright magenta foreground', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Special',
+        props: { color: 'brightMagenta' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[95m') // Bright magenta
+    })
+
+    it('applies bright cyan foreground', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Primary',
+        props: { color: 'brightCyan' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[96m') // Bright cyan
+    })
+
+    it('applies bright white foreground', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Bright',
+        props: { color: 'brightWhite' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[97m') // Bright white
+    })
+
+    it('applies bright black (gray) foreground', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Muted',
+        props: { color: 'brightBlack' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[90m') // Bright black (gray)
+    })
+  })
+
+  // ============================================================================
+  // Background Colors
+  // ============================================================================
+
+  describe('background colors', () => {
+    it('applies red background color', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Error Badge',
+        props: { backgroundColor: 'red' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[41m') // Red background
+      expect(result).toContain('Error Badge')
+    })
+
+    it('applies green background color', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Success Badge',
+        props: { backgroundColor: 'green' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[42m') // Green background
+    })
+
+    it('applies yellow background color', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Warning Badge',
+        props: { backgroundColor: 'yellow' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[43m') // Yellow background
+    })
+
+    it('applies blue background color', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Info Badge',
+        props: { backgroundColor: 'blue' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[44m') // Blue background
+    })
+
+    it('applies magenta background color', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Highlight',
+        props: { backgroundColor: 'magenta' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[45m') // Magenta background
+    })
+
+    it('applies cyan background color', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Selected',
+        props: { backgroundColor: 'cyan' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[46m') // Cyan background
+    })
+
+    it('applies white background color', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Inverted',
+        props: { backgroundColor: 'white' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[47m') // White background
+    })
+
+    it('applies black background color', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Dark Mode',
+        props: { backgroundColor: 'black' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[40m') // Black background
+    })
+  })
+
+  // ============================================================================
+  // Text Formatting (Bold, Italic, Underline, etc.)
+  // ============================================================================
+
+  describe('text formatting', () => {
+    it('applies bold formatting', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Important',
+        props: { bold: true },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[1m') // Bold
+      expect(result).toContain('Important')
+      expect(result).toContain('\x1b[0m') // Reset
+    })
+
+    it('applies italic formatting', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Emphasis',
+        props: { italic: true },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[3m') // Italic
+    })
+
+    it('applies underline formatting', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Link',
+        props: { underline: true },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[4m') // Underline
+    })
+
+    it('applies dim/faint formatting', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Subtle',
+        props: { dim: true },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[2m') // Dim
+    })
+
+    it('applies strikethrough formatting', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Deleted',
+        props: { strikethrough: true },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[9m') // Strikethrough
+    })
+
+    it('applies inverse/reverse formatting', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Inverted',
+        props: { inverse: true },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[7m') // Inverse
+    })
+  })
+
+  // ============================================================================
+  // Combined Styles
+  // ============================================================================
+
+  describe('combined styles', () => {
+    it('combines bold and color', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Bold Red',
+        props: { bold: true, color: 'red' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[1m') // Bold
+      expect(result).toContain('\x1b[31m') // Red
+      expect(result).toContain('Bold Red')
+      expect(result).toContain('\x1b[0m') // Reset
+    })
+
+    it('combines foreground and background colors', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Badge',
+        props: { color: 'white', backgroundColor: 'blue' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[37m') // White foreground
+      expect(result).toContain('\x1b[44m') // Blue background
+    })
+
+    it('combines bold, italic, and underline', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Fancy',
+        props: { bold: true, italic: true, underline: true },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[1m') // Bold
+      expect(result).toContain('\x1b[3m') // Italic
+      expect(result).toContain('\x1b[4m') // Underline
+    })
+
+    it('combines all style properties', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Everything',
+        props: {
+          bold: true,
+          italic: true,
+          underline: true,
+          color: 'cyan',
+          backgroundColor: 'black',
+        },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[1m') // Bold
+      expect(result).toContain('\x1b[3m') // Italic
+      expect(result).toContain('\x1b[4m') // Underline
+      expect(result).toContain('\x1b[36m') // Cyan
+      expect(result).toContain('\x1b[40m') // Black bg
+      expect(result).toContain('\x1b[0m') // Reset
+    })
+  })
+
+  // ============================================================================
+  // 256 Color Support
+  // ============================================================================
+
+  describe('256 color support', () => {
+    it('applies 256-color foreground using numeric code', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Extended',
+        props: { color: 196 }, // Bright red in 256 palette
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[38;5;196m') // 256-color foreground
+    })
+
+    it('applies 256-color background using numeric code', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Extended BG',
+        props: { backgroundColor: 21 }, // Blue in 256 palette
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[48;5;21m') // 256-color background
+    })
+
+    it('applies grayscale 256-color', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Gray',
+        props: { color: 240 }, // Mid gray in grayscale ramp (232-255)
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[38;5;240m')
+    })
+
+    it('applies 256-color cube values', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      // Color cube starts at 16: 6x6x6 = 216 colors (16-231)
+      const node: UINode = {
+        type: 'text',
+        text: 'Cube Color',
+        props: { color: 75 }, // Light blue in color cube
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[38;5;75m')
+    })
+  })
+
+  // ============================================================================
+  // True Color (24-bit RGB) Support
+  // ============================================================================
+
+  describe('true color (24-bit) support', () => {
+    it('applies RGB foreground color', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'RGB Text',
+        props: { color: { r: 59, g: 130, b: 246 } }, // Tailwind blue-500
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[38;2;59;130;246m') // True color foreground
+    })
+
+    it('applies RGB background color', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'RGB Background',
+        props: { backgroundColor: { r: 239, g: 68, b: 68 } }, // Tailwind red-500
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[48;2;239;68;68m') // True color background
+    })
+
+    it('applies hex color foreground', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Hex Color',
+        props: { color: '#3b82f6' }, // Tailwind blue-500
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[38;2;59;130;246m')
+    })
+
+    it('applies hex color background', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Hex Background',
+        props: { backgroundColor: '#10b981' }, // Tailwind emerald-500
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[48;2;16;185;129m')
+    })
+
+    it('handles 3-char hex shorthand', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Short Hex',
+        props: { color: '#f00' }, // Red
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[38;2;255;0;0m')
+    })
+  })
+
+  // ============================================================================
+  // Reset Codes
+  // ============================================================================
+
+  describe('reset codes', () => {
+    it('appends reset code after styled text', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Styled',
+        props: { color: 'red' },
+      }
+
+      const result = renderANSI(node)
+      expect(result.endsWith('\x1b[0m')).toBe(true)
+    })
+
+    it('resets between sibling elements', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'box',
+        children: [
+          { type: 'text', text: 'Red', props: { color: 'red' } },
+          { type: 'text', text: 'Blue', props: { color: 'blue' } },
+        ],
+      }
+
+      const result = renderANSI(node)
+      // Red text should be followed by reset before blue
+      const redIndex = result.indexOf('\x1b[31m')
+      const resetIndex = result.indexOf('\x1b[0m', redIndex)
+      const blueIndex = result.indexOf('\x1b[34m')
+
+      expect(redIndex).toBeLessThan(resetIndex)
+      expect(resetIndex).toBeLessThan(blueIndex)
+    })
+
+    it('does not add unnecessary resets for plain text', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Plain',
+      }
+
+      const result = renderANSI(node)
+      expect(result).not.toContain('\x1b[')
+    })
+  })
+
+  // ============================================================================
+  // Color Support Degradation
+  // ============================================================================
+
+  describe('color support degradation', () => {
+    it('degrades true color to 256 colors when colorSupport is 256', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Degraded',
+        props: { color: '#3b82f6' },
+      }
+
+      const result = renderANSI(node, { colorSupport: '256' })
+      // Should use 256-color escape sequence instead of true color
+      expect(result).toMatch(/\x1b\[38;5;\d+m/)
+      expect(result).not.toContain('\x1b[38;2;')
+    })
+
+    it('degrades 256 color to 16 colors when colorSupport is 16', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Basic',
+        props: { color: 196 }, // 256-color red
+      }
+
+      const result = renderANSI(node, { colorSupport: '16' })
+      // Should use basic 16-color escape sequence
+      expect(result).toMatch(/\x1b\[3[0-7]m|\x1b\[9[0-7]m/)
+      expect(result).not.toContain('\x1b[38;5;')
+    })
+
+    it('strips all colors when colorSupport is none', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'No Color',
+        props: { color: 'red', backgroundColor: 'blue', bold: true },
+      }
+
+      const result = renderANSI(node, { colorSupport: 'none' })
+      // Should not contain any color codes, but may contain bold
+      expect(result).not.toContain('\x1b[31m')
+      expect(result).not.toContain('\x1b[44m')
+      expect(result).toContain('No Color')
+    })
+
+    it('preserves text formatting when colors are stripped', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Bold Only',
+        props: { color: 'red', bold: true },
+      }
+
+      const result = renderANSI(node, { colorSupport: 'none' })
+      // Bold formatting should be preserved even without colors
+      expect(result).toContain('\x1b[1m')
+      expect(result).toContain('Bold Only')
+    })
+  })
+
+  // ============================================================================
+  // Theme Support
+  // ============================================================================
+
+  describe('theme support', () => {
+    it('uses dark theme colors by default', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Default',
+        props: { color: 'primary' },
+      }
+
+      const result = renderANSI(node)
+      // Should use dark theme primary color (typically cyan/blue)
+      expect(result).toMatch(/\x1b\[/)
+    })
+
+    it('uses light theme colors when specified', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Light Mode',
+        props: { color: 'primary' },
+      }
+
+      const darkResult = renderANSI(node, { theme: 'dark' })
+      const lightResult = renderANSI(node, { theme: 'light' })
+
+      // Light and dark theme should produce different colors for primary
+      expect(darkResult).not.toBe(lightResult)
+    })
+
+    it('resolves semantic color names', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const semanticColors = ['primary', 'secondary', 'accent', 'muted', 'success', 'warning', 'error', 'info']
+
+      for (const color of semanticColors) {
+        const node: UINode = {
+          type: 'text',
+          text: color,
+          props: { color },
+        }
+
+        const result = renderANSI(node)
+        expect(result).toContain('\x1b[')
+        expect(result).toContain(color)
+      }
+    })
+
+    it('resolves foreground semantic color', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Foreground',
+        props: { color: 'foreground' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[')
+    })
+
+    it('resolves background semantic color', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Background',
+        props: { backgroundColor: 'background' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[')
+    })
+  })
+
+  // ============================================================================
+  // Component Type Rendering
+  // ============================================================================
+
+  describe('component types', () => {
+    it('renders box component with proper structure', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'box',
+        props: { border: 'single' },
+        children: [{ type: 'text', text: 'Content' }],
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('Content')
+    })
+
+    it('renders badge component with variant colors', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'badge',
+        props: { variant: 'success' },
+        text: 'Active',
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\x1b[') // Should have color styling
+      expect(result).toContain('Active')
+    })
+
+    it('renders button component with focus styling', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'button',
+        props: { focused: true, variant: 'primary' },
+        text: 'Submit',
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('Submit')
+      // Focused buttons should have distinct styling
+      expect(result).toContain('\x1b[')
+    })
+
+    it('renders spinner component with animation frame', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'spinner',
+        props: { label: 'Loading...' },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('Loading...')
+    })
+
+    it('renders panel component with title', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'panel',
+        props: { title: 'Settings', border: 'single' },
+        children: [{ type: 'text', text: 'Panel content' }],
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('Settings')
+      expect(result).toContain('Panel content')
+    })
+
+    it('renders card component with title styling', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'card',
+        props: { title: 'Card Title' },
+        children: [{ type: 'text', text: 'Card body' }],
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('Card Title')
+      expect(result).toContain('Card body')
+    })
+
+    it('renders input component with cursor', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'input',
+        props: { value: 'Hello', focused: true, cursorPosition: 5 },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('Hello')
+    })
+
+    it('renders select component with options', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'select',
+        props: {
+          options: [
+            { label: 'Option 1', value: 1 },
+            { label: 'Option 2', value: 2 },
+          ],
+          highlightedIndex: 0,
+        },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('Option 1')
+      expect(result).toContain('Option 2')
+    })
+
+    it('renders table component with headers and rows', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'table',
+        props: {
+          columns: [
+            { key: 'name', header: 'Name' },
+            { key: 'status', header: 'Status' },
+          ],
+          data: [
+            { name: 'Item 1', status: 'Active' },
+            { name: 'Item 2', status: 'Inactive' },
+          ],
+        },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('Name')
+      expect(result).toContain('Status')
+      expect(result).toContain('Item 1')
+      expect(result).toContain('Item 2')
+    })
+
+    it('renders list component with bullets', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'list',
+        props: {
+          items: ['First', 'Second', 'Third'],
+          bullet: '*',
+        },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('First')
+      expect(result).toContain('Second')
+      expect(result).toContain('Third')
+    })
+
+    it('renders breadcrumb component with separator', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'breadcrumb',
+        props: {
+          items: [
+            { label: 'Home', path: '/' },
+            { label: 'Settings', path: '/settings' },
+          ],
+          separator: '>',
+        },
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('Home')
+      expect(result).toContain('>')
+      expect(result).toContain('Settings')
+    })
+  })
+
+  // ============================================================================
+  // Edge Cases
+  // ============================================================================
+
+  describe('edge cases', () => {
+    it('handles null children', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'box',
+        children: undefined,
+      }
+
+      const result = renderANSI(node)
+      expect(result).toBe('')
+    })
+
+    it('handles empty array children', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'box',
+        children: [],
+      }
+
+      const result = renderANSI(node)
+      expect(result).toBe('')
+    })
+
+    it('handles string children', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        children: 'String child',
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('String child')
+    })
+
+    it('handles deeply nested nodes', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'box',
+        children: [
+          {
+            type: 'box',
+            children: [
+              {
+                type: 'box',
+                children: [
+                  {
+                    type: 'text',
+                    text: 'Deep',
+                    props: { color: 'cyan' },
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('Deep')
+      expect(result).toContain('\x1b[36m') // Cyan
+    })
+
+    it('handles special characters in text', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Special: <>&"\'',
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('<>&"\'')
+    })
+
+    it('handles unicode characters', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Unicode: \u2713 \u2717 \u25CF \u25CB',
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('\u2713')
+      expect(result).toContain('\u2717')
+    })
+
+    it('handles emoji', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Status: OK',
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('OK')
+    })
+
+    it('handles newlines in text', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Line 1\nLine 2\nLine 3',
+      }
+
+      const result = renderANSI(node)
+      expect(result).toContain('Line 1')
+      expect(result).toContain('Line 2')
+      expect(result).toContain('Line 3')
+    })
+
+    it('handles undefined props', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'No props',
+        props: undefined,
+      }
+
+      const result = renderANSI(node)
+      expect(result).toBe('No props')
+    })
+
+    it('handles unknown node types gracefully', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'unknown-component',
+        text: 'Unknown',
+      }
+
+      // Should not throw, may render text content or empty
+      expect(() => renderANSI(node)).not.toThrow()
+    })
+
+    it('handles invalid color values gracefully', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Invalid',
+        props: { color: 'not-a-color' },
+      }
+
+      // Should not throw, should render text without that color
+      expect(() => renderANSI(node)).not.toThrow()
+      const result = renderANSI(node)
+      expect(result).toContain('Invalid')
+    })
+  })
+
+  // ============================================================================
+  // Terminal Width Handling
+  // ============================================================================
+
+  describe('terminal width', () => {
+    it('respects width option for text wrapping context', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'This is a long text that might need wrapping',
+        props: { wrap: 'wrap' },
+      }
+
+      const result = renderANSI(node, { width: 20 })
+      // Result should be aware of width for layout purposes
+      expect(result).toContain('This is')
+    })
+  })
+
+  // ============================================================================
+  // Performance / Output Size
+  // ============================================================================
+
+  describe('output optimization', () => {
+    it('does not duplicate reset codes unnecessarily', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'box',
+        children: [
+          { type: 'text', text: 'A', props: { color: 'red' } },
+          { type: 'text', text: 'B', props: { color: 'red' } },
+        ],
+      }
+
+      const result = renderANSI(node)
+      // Should not have consecutive reset codes
+      expect(result).not.toContain('\x1b[0m\x1b[0m')
+    })
+
+    it('combines adjacent ANSI codes efficiently', async () => {
+      const { renderANSI } = await import('../../renderers/ansi')
+
+      const node: UINode = {
+        type: 'text',
+        text: 'Optimized',
+        props: { bold: true, color: 'red' },
+      }
+
+      const result = renderANSI(node)
+      // Both codes should be present
+      expect(result).toContain('\x1b[1m')
+      expect(result).toContain('\x1b[31m')
+      // Only one reset at the end
+      expect(result.match(/\x1b\[0m/g)?.length).toBe(1)
+    })
+  })
+})
+
+// ============================================================================
+// Integration with Theme System
+// ============================================================================
+
+describe('renderANSI theme integration', () => {
+  it('accepts theme colors from createTerminalTheme', async () => {
+    const { renderANSI } = await import('../../renderers/ansi')
+    const { createTerminalTheme } = await import('../../theme')
+
+    const theme = createTerminalTheme({ mode: 'dark' })
+
+    const node: UINode = {
+      type: 'text',
+      text: 'Themed',
+      props: { color: 'primary' },
+    }
+
+    // Should be able to pass theme colors somehow
+    const result = renderANSI(node, { theme: 'dark' })
+    expect(result).toContain('Themed')
+    expect(result).toContain('\x1b[')
+  })
+
+  it('uses theme error color for error variant badge', async () => {
+    const { renderANSI } = await import('../../renderers/ansi')
+
+    const node: UINode = {
+      type: 'badge',
+      props: { variant: 'error' },
+      text: 'Error',
+    }
+
+    const result = renderANSI(node)
+    // Should use red-ish error color from theme
+    expect(result).toMatch(/\x1b\[.*31m|\x1b\[.*91m|\x1b\[38;5;\d+m|\x1b\[38;2;\d+;\d+;\d+m/)
+  })
+
+  it('uses theme success color for success variant badge', async () => {
+    const { renderANSI } = await import('../../renderers/ansi')
+
+    const node: UINode = {
+      type: 'badge',
+      props: { variant: 'success' },
+      text: 'Success',
+    }
+
+    const result = renderANSI(node)
+    // Should use green-ish success color from theme
+    expect(result).toMatch(/\x1b\[.*32m|\x1b\[.*92m|\x1b\[38;5;\d+m|\x1b\[38;2;\d+;\d+;\d+m/)
+  })
+})