@mdxui/terminal 2.0.0

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

@@ -0,0 +1,948 @@
+/**
+ * ANSI to CSS Mapping Tests
+ *
+ * TDD RED Phase: Tests for converting ANSI escape codes to CSS styles.
+ * All tests should FAIL initially because ansiToCSS/parseAnsiToSpans doesn't exist yet.
+ *
+ * This enables web rendering of ANSI terminal output in browser terminals.
+ * The converter parses ANSI escape sequences and produces:
+ * - CSS color values (names, hex, rgb())
+ * - CSS text decoration (bold, italic, underline)
+ * - Structured spans with inline styles
+ *
+ * @module
+ */
+import { describe, it, expect } from 'vitest'
+
+// ============================================================================
+// Types for ANSI to CSS Converter (contract definition)
+// ============================================================================
+
+/**
+ * CSS style properties for a styled text span
+ */
+interface CSSStyleProperties {
+  color?: string
+  backgroundColor?: string
+  fontWeight?: 'bold' | 'normal'
+  fontStyle?: 'italic' | 'normal'
+  textDecoration?: 'underline' | 'line-through' | 'none'
+  opacity?: number
+}
+
+/**
+ * A span of text with associated CSS styles
+ */
+interface StyledSpan {
+  text: string
+  style: CSSStyleProperties
+}
+
+/**
+ * Result of parsing ANSI string to CSS
+ */
+interface ANSIToCSSResult {
+  spans: StyledSpan[]
+  plainText: string
+}
+
+// ============================================================================
+// Test Suite: ANSI 16 Colors to CSS
+// ============================================================================
+
+describe('ansiToCSS', () => {
+  describe('ANSI 16 foreground colors to CSS color names', () => {
+    it('converts ANSI black (30) to CSS color black', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[30mBlack text\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.color).toBe('black')
+      expect(result.spans[0].text).toBe('Black text')
+    })
+
+    it('converts ANSI red (31) to CSS color red', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[31mRed text\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.color).toBe('red')
+    })
+
+    it('converts ANSI green (32) to CSS color green', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[32mGreen text\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.color).toBe('green')
+    })
+
+    it('converts ANSI yellow (33) to CSS color yellow', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[33mYellow text\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.color).toBe('yellow')
+    })
+
+    it('converts ANSI blue (34) to CSS color blue', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[34mBlue text\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.color).toBe('blue')
+    })
+
+    it('converts ANSI magenta (35) to CSS color magenta', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[35mMagenta text\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.color).toBe('magenta')
+    })
+
+    it('converts ANSI cyan (36) to CSS color cyan', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[36mCyan text\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.color).toBe('cyan')
+    })
+
+    it('converts ANSI white (37) to CSS color white', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[37mWhite text\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.color).toBe('white')
+    })
+  })
+
+  // ============================================================================
+  // Bright/High-Intensity Foreground Colors (90-97)
+  // ============================================================================
+
+  describe('ANSI bright foreground colors to CSS', () => {
+    it('converts ANSI bright black/gray (90) to CSS color', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[90mGray text\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      // Bright black is typically gray - could be 'gray' or '#808080'
+      expect(result.spans[0].style.color).toBe('gray')
+    })
+
+    it('converts ANSI bright red (91) to CSS color', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[91mBright red\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      // Bright colors use hex values for precision
+      expect(result.spans[0].style.color).toBe('#ff5555')
+    })
+
+    it('converts ANSI bright green (92) to CSS color', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[92mBright green\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.color).toBe('#55ff55')
+    })
+
+    it('converts ANSI bright yellow (93) to CSS color', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[93mBright yellow\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.color).toBe('#ffff55')
+    })
+
+    it('converts ANSI bright blue (94) to CSS color', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[94mBright blue\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.color).toBe('#5555ff')
+    })
+
+    it('converts ANSI bright magenta (95) to CSS color', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[95mBright magenta\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.color).toBe('#ff55ff')
+    })
+
+    it('converts ANSI bright cyan (96) to CSS color', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[96mBright cyan\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.color).toBe('#55ffff')
+    })
+
+    it('converts ANSI bright white (97) to CSS color', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[97mBright white\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.color).toBe('#ffffff')
+    })
+  })
+
+  // ============================================================================
+  // Background Colors (40-47)
+  // ============================================================================
+
+  describe('ANSI 16 background colors to CSS', () => {
+    it('converts ANSI black background (40) to CSS', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[40mBlack bg\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.backgroundColor).toBe('black')
+    })
+
+    it('converts ANSI red background (41) to CSS', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[41mRed bg\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.backgroundColor).toBe('red')
+    })
+
+    it('converts ANSI green background (42) to CSS', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[42mGreen bg\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.backgroundColor).toBe('green')
+    })
+
+    it('converts ANSI yellow background (43) to CSS', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[43mYellow bg\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.backgroundColor).toBe('yellow')
+    })
+
+    it('converts ANSI blue background (44) to CSS', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[44mBlue bg\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.backgroundColor).toBe('blue')
+    })
+
+    it('converts ANSI magenta background (45) to CSS', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[45mMagenta bg\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.backgroundColor).toBe('magenta')
+    })
+
+    it('converts ANSI cyan background (46) to CSS', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[46mCyan bg\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.backgroundColor).toBe('cyan')
+    })
+
+    it('converts ANSI white background (47) to CSS', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[47mWhite bg\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.backgroundColor).toBe('white')
+    })
+  })
+
+  // ============================================================================
+  // ANSI 256 Colors to CSS Hex Values
+  // ============================================================================
+
+  describe('ANSI 256 colors to CSS hex values', () => {
+    it('converts ANSI 256 foreground color 196 (red) to hex', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      // \x1b[38;5;196m = foreground 256-color mode, color 196
+      const ansiString = '\x1b[38;5;196mRed 196\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      // Color 196 in 256 palette is #ff0000 (bright red)
+      expect(result.spans[0].style.color).toBe('#ff0000')
+    })
+
+    it('converts ANSI 256 foreground color 46 (green) to hex', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[38;5;46mGreen 46\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      // Color 46 in 256 palette is #00ff00
+      expect(result.spans[0].style.color).toBe('#00ff00')
+    })
+
+    it('converts ANSI 256 foreground color 21 (blue) to hex', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[38;5;21mBlue 21\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      // Color 21 in 256 palette is #0000ff
+      expect(result.spans[0].style.color).toBe('#0000ff')
+    })
+
+    it('converts ANSI 256 background color 196 (red) to hex', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      // \x1b[48;5;196m = background 256-color mode, color 196
+      const ansiString = '\x1b[48;5;196mRed bg 196\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.backgroundColor).toBe('#ff0000')
+    })
+
+    it('converts ANSI 256 grayscale color 240 to hex', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[38;5;240mGray 240\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      // Color 240 is in grayscale ramp (232-255), approximately #585858
+      expect(result.spans[0].style.color).toBe('#585858')
+    })
+
+    it('converts ANSI 256 grayscale color 232 (darkest) to hex', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[38;5;232mGray 232\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      // Color 232 is the darkest in grayscale ramp, #080808
+      expect(result.spans[0].style.color).toBe('#080808')
+    })
+
+    it('converts ANSI 256 grayscale color 255 (lightest) to hex', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[38;5;255mGray 255\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      // Color 255 is the lightest in grayscale ramp, #eeeeee
+      expect(result.spans[0].style.color).toBe('#eeeeee')
+    })
+
+    it('converts ANSI 256 color cube value 75 to hex', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[38;5;75mCube 75\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      // Color 75 in 6x6x6 cube: r=1, g=2, b=3 -> #5fafff (light blue)
+      expect(result.spans[0].style.color).toBe('#5fafff')
+    })
+
+    it('converts ANSI 256 standard colors 0-15 to CSS', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      // Color 0 = black
+      const result0 = ansiToCSS('\x1b[38;5;0mBlack\x1b[0m')
+      expect(result0.spans[0].style.color).toBe('#000000')
+
+      // Color 15 = bright white
+      const result15 = ansiToCSS('\x1b[38;5;15mBright White\x1b[0m')
+      expect(result15.spans[0].style.color).toBe('#ffffff')
+    })
+  })
+
+  // ============================================================================
+  // ANSI True Color (24-bit RGB) to CSS rgb()
+  // ============================================================================
+
+  describe('ANSI true color to CSS rgb()', () => {
+    it('converts ANSI true color foreground to CSS rgb()', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      // \x1b[38;2;59;130;246m = foreground true color, RGB(59, 130, 246)
+      const ansiString = '\x1b[38;2;59;130;246mBlue 500\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.color).toBe('rgb(59, 130, 246)')
+    })
+
+    it('converts ANSI true color background to CSS rgb()', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      // \x1b[48;2;239;68;68m = background true color, RGB(239, 68, 68)
+      const ansiString = '\x1b[48;2;239;68;68mRed 500 bg\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.backgroundColor).toBe('rgb(239, 68, 68)')
+    })
+
+    it('converts ANSI true color with full RGB range', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      // Pure white
+      const white = ansiToCSS('\x1b[38;2;255;255;255mWhite\x1b[0m')
+      expect(white.spans[0].style.color).toBe('rgb(255, 255, 255)')
+
+      // Pure black
+      const black = ansiToCSS('\x1b[38;2;0;0;0mBlack\x1b[0m')
+      expect(black.spans[0].style.color).toBe('rgb(0, 0, 0)')
+
+      // Arbitrary color
+      const custom = ansiToCSS('\x1b[38;2;128;64;192mCustom\x1b[0m')
+      expect(custom.spans[0].style.color).toBe('rgb(128, 64, 192)')
+    })
+
+    it('handles both foreground and background true colors', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[38;2;255;255;255m\x1b[48;2;0;0;128mWhite on Navy\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.color).toBe('rgb(255, 255, 255)')
+      expect(result.spans[0].style.backgroundColor).toBe('rgb(0, 0, 128)')
+    })
+  })
+
+  // ============================================================================
+  // Text Styling to CSS Properties
+  // ============================================================================
+
+  describe('ANSI text styles to CSS properties', () => {
+    it('converts ANSI bold (1) to CSS fontWeight bold', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[1mBold text\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.fontWeight).toBe('bold')
+      expect(result.spans[0].text).toBe('Bold text')
+    })
+
+    it('converts ANSI dim (2) to CSS opacity', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[2mDim text\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.opacity).toBe(0.5)
+    })
+
+    it('converts ANSI italic (3) to CSS fontStyle italic', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[3mItalic text\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.fontStyle).toBe('italic')
+    })
+
+    it('converts ANSI underline (4) to CSS textDecoration underline', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[4mUnderlined text\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.textDecoration).toBe('underline')
+    })
+
+    it('converts ANSI strikethrough (9) to CSS textDecoration line-through', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[9mStrikethrough text\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.textDecoration).toBe('line-through')
+    })
+
+    it('converts ANSI inverse (7) to swapped fg/bg colors', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      // Red text with inverse should become red background with default foreground
+      const ansiString = '\x1b[31m\x1b[7mInverse red\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      // After inverse, red moves to background
+      expect(result.spans[0].style.backgroundColor).toBe('red')
+      // Foreground should be default or explicitly set
+      expect(result.spans[0].style.color).toBeDefined()
+    })
+  })
+
+  // ============================================================================
+  // Combination Styles
+  // ============================================================================
+
+  describe('combination styles', () => {
+    it('combines bold and color', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[1m\x1b[31mBold Red\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.fontWeight).toBe('bold')
+      expect(result.spans[0].style.color).toBe('red')
+    })
+
+    it('combines italic and underline', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[3m\x1b[4mItalic Underline\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.fontStyle).toBe('italic')
+      expect(result.spans[0].style.textDecoration).toBe('underline')
+    })
+
+    it('combines foreground and background colors', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[37m\x1b[44mWhite on Blue\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.color).toBe('white')
+      expect(result.spans[0].style.backgroundColor).toBe('blue')
+    })
+
+    it('combines all style properties', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[1m\x1b[3m\x1b[4m\x1b[36m\x1b[40mFull Style\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.fontWeight).toBe('bold')
+      expect(result.spans[0].style.fontStyle).toBe('italic')
+      expect(result.spans[0].style.textDecoration).toBe('underline')
+      expect(result.spans[0].style.color).toBe('cyan')
+      expect(result.spans[0].style.backgroundColor).toBe('black')
+    })
+
+    it('handles SGR sequences with multiple parameters', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      // \x1b[1;31;44m = bold;red;blue-bg in single sequence
+      const ansiString = '\x1b[1;31;44mCombined SGR\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.fontWeight).toBe('bold')
+      expect(result.spans[0].style.color).toBe('red')
+      expect(result.spans[0].style.backgroundColor).toBe('blue')
+    })
+  })
+
+  // ============================================================================
+  // Reset Handling
+  // ============================================================================
+
+  describe('reset handling', () => {
+    it('resets all styles with code 0', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[1m\x1b[31mStyled\x1b[0mPlain'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans).toHaveLength(2)
+      expect(result.spans[0].style.fontWeight).toBe('bold')
+      expect(result.spans[0].style.color).toBe('red')
+      expect(result.spans[1].style.fontWeight).toBeUndefined()
+      expect(result.spans[1].style.color).toBeUndefined()
+    })
+
+    it('resets bold with code 22', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[1mBold\x1b[22mNormal'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.fontWeight).toBe('bold')
+      expect(result.spans[1].style.fontWeight).toBe('normal')
+    })
+
+    it('resets italic with code 23', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[3mItalic\x1b[23mNormal'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.fontStyle).toBe('italic')
+      expect(result.spans[1].style.fontStyle).toBe('normal')
+    })
+
+    it('resets underline with code 24', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[4mUnderline\x1b[24mNormal'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.textDecoration).toBe('underline')
+      expect(result.spans[1].style.textDecoration).toBe('none')
+    })
+
+    it('resets foreground color with code 39', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[31mRed\x1b[39mDefault'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.color).toBe('red')
+      expect(result.spans[1].style.color).toBeUndefined()
+    })
+
+    it('resets background color with code 49', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[41mRed BG\x1b[49mDefault'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans[0].style.backgroundColor).toBe('red')
+      expect(result.spans[1].style.backgroundColor).toBeUndefined()
+    })
+  })
+
+  // ============================================================================
+  // Plain Text Extraction
+  // ============================================================================
+
+  describe('plain text extraction', () => {
+    it('extracts plain text from styled string', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[1m\x1b[31mHello\x1b[0m \x1b[32mWorld\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.plainText).toBe('Hello World')
+    })
+
+    it('handles plain text without ANSI codes', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = 'Just plain text'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.plainText).toBe('Just plain text')
+      expect(result.spans).toHaveLength(1)
+      expect(result.spans[0].text).toBe('Just plain text')
+    })
+
+    it('handles empty string', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const result = ansiToCSS('')
+
+      expect(result.plainText).toBe('')
+      expect(result.spans).toHaveLength(0)
+    })
+
+    it('handles string with only ANSI codes (no text)', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[31m\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.plainText).toBe('')
+    })
+  })
+
+  // ============================================================================
+  // Multiple Spans
+  // ============================================================================
+
+  describe('multiple styled spans', () => {
+    it('creates separate spans for different styles', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[31mRed\x1b[0m \x1b[32mGreen\x1b[0m \x1b[34mBlue\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans.length).toBeGreaterThanOrEqual(3)
+
+      const redSpan = result.spans.find(s => s.text.includes('Red'))
+      const greenSpan = result.spans.find(s => s.text.includes('Green'))
+      const blueSpan = result.spans.find(s => s.text.includes('Blue'))
+
+      expect(redSpan?.style.color).toBe('red')
+      expect(greenSpan?.style.color).toBe('green')
+      expect(blueSpan?.style.color).toBe('blue')
+    })
+
+    it('handles style changes mid-text', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = 'Normal \x1b[1mBold\x1b[0m Normal'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.spans).toHaveLength(3)
+      expect(result.spans[0].text).toBe('Normal ')
+      expect(result.spans[0].style.fontWeight).toBeUndefined()
+      expect(result.spans[1].text).toBe('Bold')
+      expect(result.spans[1].style.fontWeight).toBe('bold')
+      expect(result.spans[2].text).toBe(' Normal')
+      expect(result.spans[2].style.fontWeight).toBeUndefined()
+    })
+
+    it('handles nested style changes', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      // Bold, then add red, then remove bold but keep red
+      const ansiString = '\x1b[1mBold \x1b[31mBold+Red\x1b[22mJust Red\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      const boldSpan = result.spans.find(s => s.text === 'Bold ')
+      const boldRedSpan = result.spans.find(s => s.text === 'Bold+Red')
+      const justRedSpan = result.spans.find(s => s.text === 'Just Red')
+
+      expect(boldSpan?.style.fontWeight).toBe('bold')
+      expect(boldSpan?.style.color).toBeUndefined()
+
+      expect(boldRedSpan?.style.fontWeight).toBe('bold')
+      expect(boldRedSpan?.style.color).toBe('red')
+
+      expect(justRedSpan?.style.fontWeight).toBe('normal')
+      expect(justRedSpan?.style.color).toBe('red')
+    })
+  })
+
+  // ============================================================================
+  // Edge Cases
+  // ============================================================================
+
+  describe('edge cases', () => {
+    it('handles incomplete escape sequences gracefully', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      // Incomplete sequence (missing m terminator)
+      const ansiString = '\x1b[31Incomplete'
+
+      // Should not throw, handle gracefully
+      expect(() => ansiToCSS(ansiString)).not.toThrow()
+    })
+
+    it('handles unknown SGR codes gracefully', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      // Code 999 is not a valid SGR code
+      const ansiString = '\x1b[999mUnknown\x1b[0m'
+
+      expect(() => ansiToCSS(ansiString)).not.toThrow()
+      const result = ansiToCSS(ansiString)
+      expect(result.plainText).toBe('Unknown')
+    })
+
+    it('handles cursor movement codes (ignores them)', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      // Cursor up (\x1b[A), down (\x1b[B) - not SGR codes
+      const ansiString = '\x1b[AUp\x1b[BDown'
+      const result = ansiToCSS(ansiString)
+
+      // Should strip non-SGR sequences and return text
+      expect(result.plainText).toContain('Up')
+      expect(result.plainText).toContain('Down')
+    })
+
+    it('handles hyperlink sequences (OSC 8)', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      // OSC 8 hyperlink: \x1b]8;;URL\x1b\\text\x1b]8;;\x1b\\
+      const ansiString = '\x1b]8;;https://example.com\x1b\\Link Text\x1b]8;;\x1b\\'
+      const result = ansiToCSS(ansiString)
+
+      // Should extract text, may or may not preserve link info
+      expect(result.plainText).toContain('Link Text')
+    })
+
+    it('handles newlines within styled text', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[31mLine 1\nLine 2\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.plainText).toContain('Line 1')
+      expect(result.plainText).toContain('Line 2')
+      // Style should apply to both lines
+      expect(result.spans[0].style.color).toBe('red')
+    })
+
+    it('handles Unicode characters', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[32m\u2713 Success\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.plainText).toContain('\u2713')
+      expect(result.spans[0].style.color).toBe('green')
+    })
+
+    it('handles emoji in styled text', async () => {
+      const { ansiToCSS } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[33mWarning! \x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      expect(result.plainText).toBe('Warning! ')
+      expect(result.spans[0].style.color).toBe('yellow')
+    })
+  })
+
+  // ============================================================================
+  // CSS String Generation
+  // ============================================================================
+
+  describe('CSS string generation', () => {
+    it('generates valid CSS style string from span', async () => {
+      const { ansiToCSS, spanToInlineStyle } = await import('../../renderers/ansi-css')
+
+      const ansiString = '\x1b[1m\x1b[31mBold Red\x1b[0m'
+      const result = ansiToCSS(ansiString)
+
+      const cssString = spanToInlineStyle(result.spans[0])
+
+      expect(cssString).toContain('font-weight: bold')
+      expect(cssString).toContain('color: red')
+    })
+
+    it('generates empty string for unstyled span', async () => {
+      const { ansiToCSS, spanToInlineStyle } = await import('../../renderers/ansi-css')
+
+      const result = ansiToCSS('Plain text')
+      const cssString = spanToInlineStyle(result.spans[0])
+
+      expect(cssString).toBe('')
+    })
+
+    it('generates correct CSS for 256-color', async () => {
+      const { ansiToCSS, spanToInlineStyle } = await import('../../renderers/ansi-css')
+
+      const result = ansiToCSS('\x1b[38;5;196mRed 196\x1b[0m')
+      const cssString = spanToInlineStyle(result.spans[0])
+
+      expect(cssString).toContain('color: #ff0000')
+    })
+
+    it('generates correct CSS for true color', async () => {
+      const { ansiToCSS, spanToInlineStyle } = await import('../../renderers/ansi-css')
+
+      const result = ansiToCSS('\x1b[38;2;59;130;246mBlue\x1b[0m')
+      const cssString = spanToInlineStyle(result.spans[0])
+
+      expect(cssString).toContain('color: rgb(59, 130, 246)')
+    })
+  })
+})
+
+// ============================================================================
+// HTML Generation Tests
+// ============================================================================
+
+describe('ansiToHTML', () => {
+  it('converts ANSI string to HTML with span elements', async () => {
+    const { ansiToHTML } = await import('../../renderers/ansi-css')
+
+    const ansiString = '\x1b[31mRed\x1b[0m Normal \x1b[32mGreen\x1b[0m'
+    const html = ansiToHTML(ansiString)
+
+    expect(html).toContain('<span')
+    expect(html).toContain('color: red')
+    expect(html).toContain('Red')
+    expect(html).toContain('color: green')
+    expect(html).toContain('Green')
+  })
+
+  it('escapes HTML entities in text content', async () => {
+    const { ansiToHTML } = await import('../../renderers/ansi-css')
+
+    const ansiString = '\x1b[31m<script>alert("xss")</script>\x1b[0m'
+    const html = ansiToHTML(ansiString)
+
+    expect(html).not.toContain('<script>')
+    expect(html).toContain('&lt;script&gt;')
+  })
+
+  it('preserves newlines as <br> elements', async () => {
+    const { ansiToHTML } = await import('../../renderers/ansi-css')
+
+    const ansiString = 'Line 1\nLine 2\nLine 3'
+    const html = ansiToHTML(ansiString)
+
+    expect(html).toContain('<br>')
+  })
+
+  it('handles empty string', async () => {
+    const { ansiToHTML } = await import('../../renderers/ansi-css')
+
+    const html = ansiToHTML('')
+
+    expect(html).toBe('')
+  })
+
+  it('handles plain text without ANSI codes', async () => {
+    const { ansiToHTML } = await import('../../renderers/ansi-css')
+
+    const html = ansiToHTML('Plain text')
+
+    expect(html).toBe('Plain text')
+  })
+})
+
+// ============================================================================
+// React Component Generation Tests (optional, for React integration)
+// ============================================================================
+
+describe('parseAnsiToSpans (for React)', () => {
+  it('returns array of span objects ready for React rendering', async () => {
+    const { parseAnsiToSpans } = await import('../../renderers/ansi-css')
+
+    const ansiString = '\x1b[1m\x1b[36mCyan Bold\x1b[0m'
+    const spans = parseAnsiToSpans(ansiString)
+
+    expect(Array.isArray(spans)).toBe(true)
+    expect(spans[0]).toHaveProperty('text')
+    expect(spans[0]).toHaveProperty('style')
+    expect(spans[0].style).toHaveProperty('fontWeight', 'bold')
+    expect(spans[0].style).toHaveProperty('color', 'cyan')
+  })
+
+  it('returns style object compatible with React CSSProperties', async () => {
+    const { parseAnsiToSpans } = await import('../../renderers/ansi-css')
+
+    const spans = parseAnsiToSpans('\x1b[38;2;100;150;200mTrue Color\x1b[0m')
+
+    // Style should use camelCase for React compatibility
+    const style = spans[0].style
+    expect(style.color).toBe('rgb(100, 150, 200)')
+    // Should not have hyphenated properties
+    expect(style).not.toHaveProperty('font-weight')
+    expect(style).not.toHaveProperty('background-color')
+  })
+})