@mdxui/terminal 2.0.0

package/src/__tests__/theme.test.ts

@@ -0,0 +1,639 @@
+/**
+ * @mdxui/terminal Theme System Tests
+ *
+ * TDD RED Phase: These tests define the contract for terminal theme/color system.
+ * All tests should FAIL initially because the implementation doesn't exist yet.
+ *
+ * The theme system maps:
+ * - Tailwind CSS classes → ANSI escape codes
+ * - CSS design tokens → Terminal-safe colors
+ * - Semantic colors → Context-aware ANSI codes
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+
+describe('@mdxui/terminal theme system', () => {
+  // ============================================================================
+  // Tailwind → ANSI Color Mapping
+  // ============================================================================
+
+  describe('tailwindToAnsi', () => {
+    it('converts text-blue-500 to ANSI 256 blue', async () => {
+      const { tailwindToAnsi } = await import('@mdxui/terminal')
+      // ANSI 256 color 33 is a blue that approximates Tailwind blue-500
+      expect(tailwindToAnsi('text-blue-500')).toBe('\x1b[38;5;33m')
+    })
+
+    it('converts bg-red-600 to ANSI 256 background red', async () => {
+      const { tailwindToAnsi } = await import('@mdxui/terminal')
+      // ANSI 256 color 160 is a red that approximates Tailwind red-600
+      // 38;5;N = foreground, 48;5;N = background
+      expect(tailwindToAnsi('bg-red-600')).toBe('\x1b[48;5;160m')
+    })
+
+    it('converts text-green-400 to ANSI 256 green', async () => {
+      const { tailwindToAnsi } = await import('@mdxui/terminal')
+      expect(tailwindToAnsi('text-green-400')).toBe('\x1b[38;5;71m')
+    })
+
+    it('converts text-yellow-500 to ANSI 256 yellow', async () => {
+      const { tailwindToAnsi } = await import('@mdxui/terminal')
+      expect(tailwindToAnsi('text-yellow-500')).toBe('\x1b[38;5;220m')
+    })
+
+    it('converts text-purple-600 to ANSI 256 purple', async () => {
+      const { tailwindToAnsi } = await import('@mdxui/terminal')
+      expect(tailwindToAnsi('text-purple-600')).toBe('\x1b[38;5;128m')
+    })
+
+    it('converts bg-gray-800 to ANSI 256 dark gray background', async () => {
+      const { tailwindToAnsi } = await import('@mdxui/terminal')
+      expect(tailwindToAnsi('bg-gray-800')).toBe('\x1b[48;5;238m')
+    })
+
+    it('converts text-white to ANSI bright white', async () => {
+      const { tailwindToAnsi } = await import('@mdxui/terminal')
+      expect(tailwindToAnsi('text-white')).toBe('\x1b[38;5;15m')
+    })
+
+    it('converts text-black to ANSI black', async () => {
+      const { tailwindToAnsi } = await import('@mdxui/terminal')
+      expect(tailwindToAnsi('text-black')).toBe('\x1b[38;5;0m')
+    })
+
+    it('handles unknown classes by returning empty string', async () => {
+      const { tailwindToAnsi } = await import('@mdxui/terminal')
+      expect(tailwindToAnsi('unknown-class')).toBe('')
+    })
+
+    it('supports Tailwind gray scale variants', async () => {
+      const { tailwindToAnsi } = await import('@mdxui/terminal')
+      expect(tailwindToAnsi('text-gray-100')).toMatch(/\x1b\[38;5;\d+m/)
+      expect(tailwindToAnsi('text-gray-300')).toMatch(/\x1b\[38;5;\d+m/)
+      expect(tailwindToAnsi('text-gray-500')).toMatch(/\x1b\[38;5;\d+m/)
+      expect(tailwindToAnsi('text-gray-700')).toMatch(/\x1b\[38;5;\d+m/)
+      expect(tailwindToAnsi('text-gray-900')).toMatch(/\x1b\[38;5;\d+m/)
+    })
+
+    it('supports slate, zinc, neutral, and stone scales', async () => {
+      const { tailwindToAnsi } = await import('@mdxui/terminal')
+      expect(tailwindToAnsi('text-slate-500')).toMatch(/\x1b\[38;5;\d+m/)
+      expect(tailwindToAnsi('text-zinc-500')).toMatch(/\x1b\[38;5;\d+m/)
+      expect(tailwindToAnsi('text-neutral-500')).toMatch(/\x1b\[38;5;\d+m/)
+      expect(tailwindToAnsi('text-stone-500')).toMatch(/\x1b\[38;5;\d+m/)
+    })
+
+    it('handles all Tailwind color intensities (50-950)', async () => {
+      const { tailwindToAnsi } = await import('@mdxui/terminal')
+      const intensities = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950]
+      for (const intensity of intensities) {
+        expect(tailwindToAnsi(`text-blue-${intensity}`)).toMatch(/\x1b\[38;5;\d+m/)
+      }
+    })
+
+    it('converts font-bold to ANSI bold', async () => {
+      const { tailwindToAnsi } = await import('@mdxui/terminal')
+      expect(tailwindToAnsi('font-bold')).toBe('\x1b[1m')
+    })
+
+    it('converts italic to ANSI italic', async () => {
+      const { tailwindToAnsi } = await import('@mdxui/terminal')
+      expect(tailwindToAnsi('italic')).toBe('\x1b[3m')
+    })
+
+    it('converts underline to ANSI underline', async () => {
+      const { tailwindToAnsi } = await import('@mdxui/terminal')
+      expect(tailwindToAnsi('underline')).toBe('\x1b[4m')
+    })
+
+    it('converts line-through to ANSI strikethrough', async () => {
+      const { tailwindToAnsi } = await import('@mdxui/terminal')
+      expect(tailwindToAnsi('line-through')).toBe('\x1b[9m')
+    })
+  })
+
+  // ============================================================================
+  // Theme Token System
+  // ============================================================================
+
+  describe('createTerminalTheme', () => {
+    it('creates a dark mode theme with all semantic colors', async () => {
+      const { createTerminalTheme } = await import('@mdxui/terminal')
+      const theme = createTerminalTheme({ mode: 'dark' })
+
+      expect(theme.mode).toBe('dark')
+      expect(theme.colors).toBeDefined()
+      expect(theme.colors.primary).toBeDefined()
+      expect(theme.colors.secondary).toBeDefined()
+      expect(theme.colors.accent).toBeDefined()
+      expect(theme.colors.muted).toBeDefined()
+    })
+
+    it('creates a light mode theme with appropriate contrast', async () => {
+      const { createTerminalTheme } = await import('@mdxui/terminal')
+      const theme = createTerminalTheme({ mode: 'light' })
+
+      expect(theme.mode).toBe('light')
+      expect(theme.colors.foreground).toBeDefined()
+      expect(theme.colors.background).toBeDefined()
+      // Light mode should have dark foreground for contrast
+      expect(theme.colors.foreground).not.toBe(theme.colors.background)
+    })
+
+    it('includes all status colors', async () => {
+      const { createTerminalTheme } = await import('@mdxui/terminal')
+      const theme = createTerminalTheme({ mode: 'dark' })
+
+      expect(theme.colors.success).toBeDefined()
+      expect(theme.colors.warning).toBeDefined()
+      expect(theme.colors.error).toBeDefined()
+      expect(theme.colors.info).toBeDefined()
+    })
+
+    it('includes UI colors', async () => {
+      const { createTerminalTheme } = await import('@mdxui/terminal')
+      const theme = createTerminalTheme({ mode: 'dark' })
+
+      expect(theme.colors.border).toBeDefined()
+      expect(theme.colors.background).toBeDefined()
+      expect(theme.colors.foreground).toBeDefined()
+      expect(theme.colors.selection).toBeDefined()
+      expect(theme.colors.focus).toBeDefined()
+    })
+
+    it('allows custom color overrides', async () => {
+      const { createTerminalTheme } = await import('@mdxui/terminal')
+      const customPrimary = '\x1b[38;5;45m' // Custom cyan
+      const theme = createTerminalTheme({
+        mode: 'dark',
+        colors: {
+          primary: customPrimary,
+        },
+      })
+
+      expect(theme.colors.primary).toBe(customPrimary)
+    })
+
+    it('defaults to dark mode when mode not specified', async () => {
+      const { createTerminalTheme } = await import('@mdxui/terminal')
+      const theme = createTerminalTheme({})
+
+      expect(theme.mode).toBe('dark')
+    })
+
+    it('provides ANSI escape codes for all colors', async () => {
+      const { createTerminalTheme } = await import('@mdxui/terminal')
+      const theme = createTerminalTheme({ mode: 'dark' })
+
+      // All colors should be valid ANSI escape sequences
+      const ansiPattern = /^\x1b\[\d+(;\d+)*m$/
+      for (const [key, value] of Object.entries(theme.colors)) {
+        if (value) {
+          expect(value).toMatch(ansiPattern)
+        }
+      }
+    })
+  })
+
+  // ============================================================================
+  // Semantic Color Retrieval
+  // ============================================================================
+
+  describe('getThemeColor', () => {
+    it('retrieves primary color from theme', async () => {
+      const { getThemeColor, createTerminalTheme } = await import('@mdxui/terminal')
+      const theme = createTerminalTheme({ mode: 'dark' })
+      const color = getThemeColor(theme, 'primary')
+
+      expect(color).toBeDefined()
+      expect(typeof color).toBe('string')
+      expect(color).toMatch(/\x1b\[/)
+    })
+
+    it('retrieves error color from theme', async () => {
+      const { getThemeColor, createTerminalTheme } = await import('@mdxui/terminal')
+      const theme = createTerminalTheme({ mode: 'dark' })
+      const color = getThemeColor(theme, 'error')
+
+      expect(color).toBeDefined()
+      expect(color).toContain('\x1b[')
+    })
+
+    it('returns fallback for unknown color keys', async () => {
+      const { getThemeColor, createTerminalTheme } = await import('@mdxui/terminal')
+      const theme = createTerminalTheme({ mode: 'dark' })
+      const color = getThemeColor(theme, 'unknownColor' as any, '\x1b[37m')
+
+      expect(color).toBe('\x1b[37m')
+    })
+
+    it('throws when no fallback provided for unknown key', async () => {
+      const { getThemeColor, createTerminalTheme } = await import('@mdxui/terminal')
+      const theme = createTerminalTheme({ mode: 'dark' })
+
+      expect(() => getThemeColor(theme, 'unknownColor' as any)).toThrow()
+    })
+  })
+
+  // ============================================================================
+  // Color Support Detection
+  // ============================================================================
+
+  describe('detectColorSupport', () => {
+    let originalEnv: NodeJS.ProcessEnv
+
+    beforeEach(() => {
+      originalEnv = { ...process.env }
+    })
+
+    afterEach(() => {
+      process.env = originalEnv
+    })
+
+    it('returns color support level as string', async () => {
+      const { detectColorSupport } = await import('@mdxui/terminal')
+      const support = detectColorSupport()
+
+      expect(['none', '16', '256', 'truecolor']).toContain(support)
+    })
+
+    it('detects truecolor from COLORTERM env', async () => {
+      process.env.COLORTERM = 'truecolor'
+      // Clear the module cache to pick up new env
+      vi.resetModules()
+      const { detectColorSupport } = await import('@mdxui/terminal')
+      const support = detectColorSupport()
+
+      expect(support).toBe('truecolor')
+    })
+
+    it('detects 24bit from COLORTERM env', async () => {
+      process.env.COLORTERM = '24bit'
+      vi.resetModules()
+      const { detectColorSupport } = await import('@mdxui/terminal')
+      const support = detectColorSupport()
+
+      expect(support).toBe('truecolor')
+    })
+
+    it('detects 256 colors from TERM containing 256color', async () => {
+      delete process.env.COLORTERM
+      process.env.TERM = 'xterm-256color'
+      vi.resetModules()
+      const { detectColorSupport } = await import('@mdxui/terminal')
+      const support = detectColorSupport()
+
+      expect(support).toBe('256')
+    })
+
+    it('detects 16 colors from basic TERM', async () => {
+      delete process.env.COLORTERM
+      process.env.TERM = 'xterm'
+      vi.resetModules()
+      const { detectColorSupport } = await import('@mdxui/terminal')
+      const support = detectColorSupport()
+
+      expect(support).toBe('16')
+    })
+
+    it('returns none for dumb terminal', async () => {
+      delete process.env.COLORTERM
+      process.env.TERM = 'dumb'
+      vi.resetModules()
+      const { detectColorSupport } = await import('@mdxui/terminal')
+      const support = detectColorSupport()
+
+      expect(support).toBe('none')
+    })
+
+    it('respects NO_COLOR environment variable', async () => {
+      process.env.NO_COLOR = '1'
+      process.env.COLORTERM = 'truecolor'
+      vi.resetModules()
+      const { detectColorSupport } = await import('@mdxui/terminal')
+      const support = detectColorSupport()
+
+      expect(support).toBe('none')
+    })
+
+    it('respects FORCE_COLOR environment variable', async () => {
+      process.env.FORCE_COLOR = '3'
+      delete process.env.NO_COLOR
+      vi.resetModules()
+      const { detectColorSupport } = await import('@mdxui/terminal')
+      const support = detectColorSupport()
+
+      expect(support).toBe('truecolor')
+    })
+  })
+
+  // ============================================================================
+  // CSS Variable Mapping
+  // ============================================================================
+
+  describe('cssVarToAnsi', () => {
+    it('maps --primary to theme primary color', async () => {
+      const { cssVarToAnsi, createTerminalTheme } = await import('@mdxui/terminal')
+      const theme = createTerminalTheme({ mode: 'dark' })
+      const color = cssVarToAnsi('--primary', theme)
+
+      expect(color).toBe(theme.colors.primary)
+    })
+
+    it('maps --foreground to theme foreground color', async () => {
+      const { cssVarToAnsi, createTerminalTheme } = await import('@mdxui/terminal')
+      const theme = createTerminalTheme({ mode: 'dark' })
+      const color = cssVarToAnsi('--foreground', theme)
+
+      expect(color).toBe(theme.colors.foreground)
+    })
+
+    it('maps --background to theme background color', async () => {
+      const { cssVarToAnsi, createTerminalTheme } = await import('@mdxui/terminal')
+      const theme = createTerminalTheme({ mode: 'dark' })
+      const color = cssVarToAnsi('--background', theme)
+
+      expect(color).toBe(theme.colors.background)
+    })
+
+    it('maps --destructive to theme error color', async () => {
+      const { cssVarToAnsi, createTerminalTheme } = await import('@mdxui/terminal')
+      const theme = createTerminalTheme({ mode: 'dark' })
+      const color = cssVarToAnsi('--destructive', theme)
+
+      expect(color).toBe(theme.colors.error)
+    })
+
+    it('maps --muted-foreground to theme muted color', async () => {
+      const { cssVarToAnsi, createTerminalTheme } = await import('@mdxui/terminal')
+      const theme = createTerminalTheme({ mode: 'dark' })
+      const color = cssVarToAnsi('--muted-foreground', theme)
+
+      expect(color).toBe(theme.colors.muted)
+    })
+
+    it('returns empty string for unknown CSS variables', async () => {
+      const { cssVarToAnsi, createTerminalTheme } = await import('@mdxui/terminal')
+      const theme = createTerminalTheme({ mode: 'dark' })
+      const color = cssVarToAnsi('--unknown-var', theme)
+
+      expect(color).toBe('')
+    })
+  })
+
+  // ============================================================================
+  // Color Degradation (graceful fallback for limited color support)
+  // ============================================================================
+
+  describe('degradeColor', () => {
+    it('passes through ANSI 256 color when support is 256', async () => {
+      const { degradeColor } = await import('@mdxui/terminal')
+      const color = '\x1b[38;5;33m'
+      const degraded = degradeColor(color, '256')
+
+      expect(degraded).toBe(color)
+    })
+
+    it('converts ANSI 256 to basic 16 color when support is 16', async () => {
+      const { degradeColor } = await import('@mdxui/terminal')
+      const color = '\x1b[38;5;33m' // 256-color blue
+      const degraded = degradeColor(color, '16')
+
+      // Should convert to basic blue (34) or bright blue (94)
+      expect(degraded).toMatch(/\x1b\[3[0-7]m|\x1b\[9[0-7]m/)
+    })
+
+    it('returns empty string when support is none', async () => {
+      const { degradeColor } = await import('@mdxui/terminal')
+      const color = '\x1b[38;5;33m'
+      const degraded = degradeColor(color, 'none')
+
+      expect(degraded).toBe('')
+    })
+
+    it('handles truecolor to 256 conversion', async () => {
+      const { degradeColor } = await import('@mdxui/terminal')
+      // Truecolor blue: RGB(59, 130, 246) - Tailwind blue-500
+      const color = '\x1b[38;2;59;130;246m'
+      const degraded = degradeColor(color, '256')
+
+      // Should be a valid 256-color code
+      expect(degraded).toMatch(/\x1b\[38;5;\d+m/)
+    })
+  })
+
+  // ============================================================================
+  // Theme-Aware Styling
+  // ============================================================================
+
+  describe('applyThemeStyles', () => {
+    it('wraps text with theme-appropriate colors', async () => {
+      const { applyThemeStyles, createTerminalTheme } = await import('@mdxui/terminal')
+      const theme = createTerminalTheme({ mode: 'dark' })
+      const styled = applyThemeStyles('Hello', theme, 'primary')
+
+      expect(styled).toContain(theme.colors.primary)
+      expect(styled).toContain('Hello')
+      expect(styled).toContain('\x1b[0m') // Reset at end
+    })
+
+    it('supports multiple style types', async () => {
+      const { applyThemeStyles, createTerminalTheme } = await import('@mdxui/terminal')
+      const theme = createTerminalTheme({ mode: 'dark' })
+      const styled = applyThemeStyles('Error!', theme, 'error')
+
+      expect(styled).toContain(theme.colors.error)
+    })
+
+    it('handles background styling', async () => {
+      const { applyThemeStyles, createTerminalTheme } = await import('@mdxui/terminal')
+      const theme = createTerminalTheme({ mode: 'dark' })
+      const styled = applyThemeStyles('Selected', theme, 'selection')
+
+      expect(styled).toContain(theme.colors.selection)
+    })
+  })
+
+  // ============================================================================
+  // Dark/Light Mode Contrast
+  // ============================================================================
+
+  describe('theme mode contrast', () => {
+    it('dark mode has light foreground on dark background', async () => {
+      const { createTerminalTheme } = await import('@mdxui/terminal')
+      const theme = createTerminalTheme({ mode: 'dark' })
+
+      // Dark mode: foreground should be light-colored
+      // Using ANSI 256 grayscale: 232-255 (232=black, 255=white)
+      // Light text would be 250+ range
+      expect(theme.colors.foreground).toBeDefined()
+      expect(theme.colors.background).toBeDefined()
+    })
+
+    it('light mode has dark foreground on light background', async () => {
+      const { createTerminalTheme } = await import('@mdxui/terminal')
+      const theme = createTerminalTheme({ mode: 'light' })
+
+      // Light mode: foreground should be dark-colored
+      expect(theme.colors.foreground).toBeDefined()
+      expect(theme.colors.background).toBeDefined()
+    })
+
+    it('primary color has good contrast in both modes', async () => {
+      const { createTerminalTheme } = await import('@mdxui/terminal')
+      const darkTheme = createTerminalTheme({ mode: 'dark' })
+      const lightTheme = createTerminalTheme({ mode: 'light' })
+
+      // Primary should be different for each mode to maintain contrast
+      expect(darkTheme.colors.primary).toBeDefined()
+      expect(lightTheme.colors.primary).toBeDefined()
+    })
+  })
+
+  // ============================================================================
+  // RGB/Hex to ANSI Conversion
+  // ============================================================================
+
+  describe('rgbToAnsi', () => {
+    it('converts RGB values to ANSI 256 color', async () => {
+      const { rgbToAnsi } = await import('@mdxui/terminal')
+      // Blue-500: RGB(59, 130, 246)
+      const ansi = rgbToAnsi(59, 130, 246)
+
+      expect(ansi).toMatch(/\x1b\[38;5;\d+m/)
+    })
+
+    it('converts black to ANSI 256 color 0', async () => {
+      const { rgbToAnsi } = await import('@mdxui/terminal')
+      const ansi = rgbToAnsi(0, 0, 0)
+
+      expect(ansi).toBe('\x1b[38;5;0m')
+    })
+
+    it('converts white to ANSI 256 color 15', async () => {
+      const { rgbToAnsi } = await import('@mdxui/terminal')
+      const ansi = rgbToAnsi(255, 255, 255)
+
+      expect(ansi).toBe('\x1b[38;5;15m')
+    })
+
+    it('supports background mode', async () => {
+      const { rgbToAnsi } = await import('@mdxui/terminal')
+      const ansi = rgbToAnsi(255, 0, 0, { background: true })
+
+      expect(ansi).toMatch(/\x1b\[48;5;\d+m/)
+    })
+  })
+
+  describe('hexToAnsi', () => {
+    it('converts hex color to ANSI 256 color', async () => {
+      const { hexToAnsi } = await import('@mdxui/terminal')
+      // Blue-500: #3b82f6
+      const ansi = hexToAnsi('#3b82f6')
+
+      expect(ansi).toMatch(/\x1b\[38;5;\d+m/)
+    })
+
+    it('handles hex without hash prefix', async () => {
+      const { hexToAnsi } = await import('@mdxui/terminal')
+      const ansi = hexToAnsi('3b82f6')
+
+      expect(ansi).toMatch(/\x1b\[38;5;\d+m/)
+    })
+
+    it('handles 3-character hex shorthand', async () => {
+      const { hexToAnsi } = await import('@mdxui/terminal')
+      const ansi = hexToAnsi('#fff')
+
+      expect(ansi).toBe('\x1b[38;5;15m')
+    })
+
+    it('supports background mode', async () => {
+      const { hexToAnsi } = await import('@mdxui/terminal')
+      const ansi = hexToAnsi('#ff0000', { background: true })
+
+      expect(ansi).toMatch(/\x1b\[48;5;\d+m/)
+    })
+  })
+
+  // ============================================================================
+  // ANSI Code Constants
+  // ============================================================================
+
+  describe('ANSI constants', () => {
+    it('exports ANSI reset code', async () => {
+      const { ANSI } = await import('@mdxui/terminal')
+      expect(ANSI.reset).toBe('\x1b[0m')
+    })
+
+    it('exports ANSI style codes', async () => {
+      const { ANSI } = await import('@mdxui/terminal')
+      expect(ANSI.bold).toBe('\x1b[1m')
+      expect(ANSI.dim).toBe('\x1b[2m')
+      expect(ANSI.italic).toBe('\x1b[3m')
+      expect(ANSI.underline).toBe('\x1b[4m')
+    })
+
+    it('exports basic foreground colors', async () => {
+      const { ANSI } = await import('@mdxui/terminal')
+      expect(ANSI.black).toBe('\x1b[30m')
+      expect(ANSI.red).toBe('\x1b[31m')
+      expect(ANSI.green).toBe('\x1b[32m')
+      expect(ANSI.yellow).toBe('\x1b[33m')
+      expect(ANSI.blue).toBe('\x1b[34m')
+      expect(ANSI.magenta).toBe('\x1b[35m')
+      expect(ANSI.cyan).toBe('\x1b[36m')
+      expect(ANSI.white).toBe('\x1b[37m')
+    })
+
+    it('exports bright foreground colors', async () => {
+      const { ANSI } = await import('@mdxui/terminal')
+      expect(ANSI.brightBlack).toBe('\x1b[90m')
+      expect(ANSI.brightRed).toBe('\x1b[91m')
+      expect(ANSI.brightGreen).toBe('\x1b[92m')
+      expect(ANSI.brightYellow).toBe('\x1b[93m')
+      expect(ANSI.brightBlue).toBe('\x1b[94m')
+      expect(ANSI.brightMagenta).toBe('\x1b[95m')
+      expect(ANSI.brightCyan).toBe('\x1b[96m')
+      expect(ANSI.brightWhite).toBe('\x1b[97m')
+    })
+
+    it('exports background colors', async () => {
+      const { ANSI } = await import('@mdxui/terminal')
+      expect(ANSI.bgBlack).toBe('\x1b[40m')
+      expect(ANSI.bgRed).toBe('\x1b[41m')
+      expect(ANSI.bgGreen).toBe('\x1b[42m')
+      expect(ANSI.bgYellow).toBe('\x1b[43m')
+      expect(ANSI.bgBlue).toBe('\x1b[44m')
+      expect(ANSI.bgMagenta).toBe('\x1b[45m')
+      expect(ANSI.bgCyan).toBe('\x1b[46m')
+      expect(ANSI.bgWhite).toBe('\x1b[47m')
+    })
+  })
+
+  // ============================================================================
+  // Styled Text Helper
+  // ============================================================================
+
+  describe('styled helper', () => {
+    it('wraps text with ANSI codes and reset', async () => {
+      const { styled, ANSI } = await import('@mdxui/terminal')
+      const result = styled('Hello', ANSI.blue)
+
+      expect(result).toBe('\x1b[34mHello\x1b[0m')
+    })
+
+    it('combines multiple ANSI codes', async () => {
+      const { styled, ANSI } = await import('@mdxui/terminal')
+      const result = styled('Bold Blue', ANSI.bold, ANSI.blue)
+
+      expect(result).toBe('\x1b[1m\x1b[34mBold Blue\x1b[0m')
+    })
+
+    it('returns plain text when no codes provided', async () => {
+      const { styled } = await import('@mdxui/terminal')
+      const result = styled('Plain')
+
+      expect(result).toBe('Plain')
+    })
+  })
+})