@mdxui/terminal 2.0.0

package/src/__tests__/core/tier-switcher.test.ts

@@ -0,0 +1,1103 @@
+/**
+ * @mdxui/terminal Tier Switcher Control Tests (RED phase)
+ *
+ * TDD RED Phase: These tests define the contract for runtime tier switching
+ * in the Universal Terminal UI. The Tier Switcher allows users to dynamically
+ * switch between render tiers at runtime.
+ *
+ * Key behaviors:
+ * - Tier detection based on terminal capabilities
+ * - Runtime tier switching (TEXT → ANSI → INTERACTIVE)
+ * - Graceful fallback when a tier is unavailable
+ * - User preference override
+ * - Re-render on tier change
+ *
+ * NOTE: These tests are expected to FAIL until implementation is complete.
+ * Run: pnpm --filter @mdxui/terminal test
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import type { RenderTier } from '../../core/types'
+
+// ============================================================================
+// These imports WILL FAIL until src/core/tier-switcher.ts is implemented
+// ============================================================================
+
+import {
+  TierSwitcher,
+  createTierSwitcher,
+  detectTierCapabilities,
+  getTierOrder,
+  canSwitchToTier,
+  type TierCapabilities,
+  type TierSwitcherOptions,
+  type TierChangeEvent,
+} from '../../core/tier-switcher'
+
+// ============================================================================
+// Test Fixtures
+// ============================================================================
+
+const ALL_TIERS: RenderTier[] = ['text', 'markdown', 'ascii', 'unicode', 'ansi', 'interactive']
+
+const mockFullCapabilities: TierCapabilities = {
+  text: true,
+  markdown: true,
+  ascii: true,
+  unicode: true,
+  ansi: true,
+  interactive: true,
+}
+
+const mockBasicCapabilities: TierCapabilities = {
+  text: true,
+  markdown: true,
+  ascii: true,
+  unicode: false,
+  ansi: false,
+  interactive: false,
+}
+
+const mockAnsiCapabilities: TierCapabilities = {
+  text: true,
+  markdown: true,
+  ascii: true,
+  unicode: true,
+  ansi: true,
+  interactive: false, // No interactive support (e.g., piped output)
+}
+
+// ============================================================================
+// Tier Detection Tests
+// ============================================================================
+
+describe('Tier Detection', () => {
+  describe('detectTierCapabilities', () => {
+    it('returns TierCapabilities object with all tier flags', () => {
+      const capabilities = detectTierCapabilities()
+
+      expect(capabilities).toBeDefined()
+      expect(typeof capabilities.text).toBe('boolean')
+      expect(typeof capabilities.markdown).toBe('boolean')
+      expect(typeof capabilities.ascii).toBe('boolean')
+      expect(typeof capabilities.unicode).toBe('boolean')
+      expect(typeof capabilities.ansi).toBe('boolean')
+      expect(typeof capabilities.interactive).toBe('boolean')
+    })
+
+    it('always supports text tier', () => {
+      const capabilities = detectTierCapabilities()
+
+      // Text tier should always be available as the fallback
+      expect(capabilities.text).toBe(true)
+    })
+
+    it('always supports markdown tier', () => {
+      const capabilities = detectTierCapabilities()
+
+      // Markdown is just text with formatting markers, always available
+      expect(capabilities.markdown).toBe(true)
+    })
+
+    it('always supports ascii tier', () => {
+      const capabilities = detectTierCapabilities()
+
+      // ASCII characters are universally supported
+      expect(capabilities.ascii).toBe(true)
+    })
+
+    it('detects unicode support based on terminal encoding', () => {
+      const capabilities = detectTierCapabilities()
+
+      // Unicode support depends on terminal UTF-8 support
+      expect(typeof capabilities.unicode).toBe('boolean')
+    })
+
+    it('detects ANSI color support based on terminal capabilities', () => {
+      const capabilities = detectTierCapabilities()
+
+      // ANSI support depends on terminal color support
+      expect(typeof capabilities.ansi).toBe('boolean')
+    })
+
+    it('detects interactive support based on TTY and input availability', () => {
+      const capabilities = detectTierCapabilities()
+
+      // Interactive requires TTY with stdin/stdout
+      expect(typeof capabilities.interactive).toBe('boolean')
+    })
+
+    it('accepts optional environment override', () => {
+      const customEnv = {
+        TERM: 'xterm-256color',
+        COLORTERM: 'truecolor',
+        FORCE_COLOR: '1',
+      }
+
+      const capabilities = detectTierCapabilities({ env: customEnv })
+
+      expect(capabilities).toBeDefined()
+    })
+
+    it('accepts optional TTY override', () => {
+      const capabilities = detectTierCapabilities({
+        isTTY: true,
+        isStdinTTY: true,
+        isStdoutTTY: true,
+      })
+
+      expect(capabilities).toBeDefined()
+    })
+
+    it('disables interactive when stdin is not a TTY', () => {
+      const capabilities = detectTierCapabilities({
+        isTTY: true,
+        isStdinTTY: false, // Piped input
+        isStdoutTTY: true,
+      })
+
+      expect(capabilities.interactive).toBe(false)
+    })
+
+    it('disables interactive when stdout is not a TTY', () => {
+      const capabilities = detectTierCapabilities({
+        isTTY: true,
+        isStdinTTY: true,
+        isStdoutTTY: false, // Piped output
+      })
+
+      expect(capabilities.interactive).toBe(false)
+    })
+
+    it('respects NO_COLOR environment variable', () => {
+      const capabilities = detectTierCapabilities({
+        env: { NO_COLOR: '1' },
+      })
+
+      expect(capabilities.ansi).toBe(false)
+    })
+
+    it('respects FORCE_COLOR environment variable', () => {
+      const capabilities = detectTierCapabilities({
+        env: { FORCE_COLOR: '1' },
+        isTTY: false, // Even without TTY
+      })
+
+      expect(capabilities.ansi).toBe(true)
+    })
+  })
+
+  describe('getTierOrder', () => {
+    it('returns tiers in capability order', () => {
+      const order = getTierOrder()
+
+      expect(order).toEqual(['text', 'markdown', 'ascii', 'unicode', 'ansi', 'interactive'])
+    })
+
+    it('returns tier ordering as a map', () => {
+      const orderMap = getTierOrder('map')
+
+      expect(orderMap).toEqual({
+        text: 0,
+        markdown: 1,
+        ascii: 2,
+        unicode: 3,
+        ansi: 4,
+        interactive: 5,
+      })
+    })
+
+    it('text has lowest order (0)', () => {
+      const orderMap = getTierOrder('map')
+      expect(orderMap.text).toBe(0)
+    })
+
+    it('interactive has highest order (5)', () => {
+      const orderMap = getTierOrder('map')
+      expect(orderMap.interactive).toBe(5)
+    })
+  })
+
+  describe('canSwitchToTier', () => {
+    it('returns true when tier is supported', () => {
+      const result = canSwitchToTier('ansi', mockFullCapabilities)
+      expect(result).toBe(true)
+    })
+
+    it('returns false when tier is not supported', () => {
+      const result = canSwitchToTier('interactive', mockAnsiCapabilities)
+      expect(result).toBe(false)
+    })
+
+    it('always returns true for text tier', () => {
+      const result = canSwitchToTier('text', mockBasicCapabilities)
+      expect(result).toBe(true)
+    })
+
+    it('returns false for unicode when not supported', () => {
+      const result = canSwitchToTier('unicode', mockBasicCapabilities)
+      expect(result).toBe(false)
+    })
+
+    it('returns false for ansi when not supported', () => {
+      const result = canSwitchToTier('ansi', mockBasicCapabilities)
+      expect(result).toBe(false)
+    })
+  })
+})
+
+// ============================================================================
+// TierSwitcher Factory Tests
+// ============================================================================
+
+describe('createTierSwitcher', () => {
+  it('creates a TierSwitcher instance', () => {
+    const switcher = createTierSwitcher()
+
+    expect(switcher).toBeDefined()
+    expect(typeof switcher.getCurrentTier).toBe('function')
+    expect(typeof switcher.setTier).toBe('function')
+  })
+
+  it('accepts initial tier option', () => {
+    const switcher = createTierSwitcher({ initialTier: 'unicode' })
+
+    expect(switcher.getCurrentTier()).toBe('unicode')
+  })
+
+  it('accepts capabilities override', () => {
+    const switcher = createTierSwitcher({
+      capabilities: mockBasicCapabilities,
+    })
+
+    expect(switcher.getCapabilities()).toEqual(mockBasicCapabilities)
+  })
+
+  it('accepts auto-detect option', () => {
+    const switcher = createTierSwitcher({ autoDetect: true })
+
+    expect(switcher).toBeDefined()
+  })
+
+  it('defaults to highest available tier when autoDetect is true', () => {
+    const switcher = createTierSwitcher({
+      autoDetect: true,
+      capabilities: mockAnsiCapabilities,
+    })
+
+    // Should auto-select 'ansi' as highest available
+    expect(switcher.getCurrentTier()).toBe('ansi')
+  })
+
+  it('defaults to text tier when autoDetect is false', () => {
+    const switcher = createTierSwitcher({ autoDetect: false })
+
+    expect(switcher.getCurrentTier()).toBe('text')
+  })
+
+  it('accepts onChange callback', () => {
+    const onChange = vi.fn()
+    const switcher = createTierSwitcher({ onChange })
+
+    switcher.setTier('ansi')
+
+    expect(onChange).toHaveBeenCalled()
+  })
+})
+
+// ============================================================================
+// TierSwitcher Instance Tests
+// ============================================================================
+
+describe('TierSwitcher', () => {
+  let switcher: TierSwitcher
+
+  beforeEach(() => {
+    switcher = createTierSwitcher({
+      capabilities: mockFullCapabilities,
+      initialTier: 'text',
+    })
+  })
+
+  afterEach(() => {
+    switcher.destroy()
+  })
+
+  describe('getCurrentTier', () => {
+    it('returns the current render tier', () => {
+      expect(switcher.getCurrentTier()).toBe('text')
+    })
+
+    it('reflects tier changes', () => {
+      switcher.setTier('ansi')
+      expect(switcher.getCurrentTier()).toBe('ansi')
+    })
+  })
+
+  describe('setTier', () => {
+    it('changes the current tier', () => {
+      switcher.setTier('unicode')
+      expect(switcher.getCurrentTier()).toBe('unicode')
+    })
+
+    it('returns true on successful change', () => {
+      const result = switcher.setTier('ansi')
+      expect(result).toBe(true)
+    })
+
+    it('returns false when tier is not available', () => {
+      const limitedSwitcher = createTierSwitcher({
+        capabilities: mockBasicCapabilities,
+        initialTier: 'text',
+      })
+
+      const result = limitedSwitcher.setTier('ansi')
+      expect(result).toBe(false)
+      expect(limitedSwitcher.getCurrentTier()).toBe('text')
+
+      limitedSwitcher.destroy()
+    })
+
+    it('emits change event on successful switch', () => {
+      const listener = vi.fn()
+      switcher.on('change', listener)
+
+      switcher.setTier('ansi')
+
+      expect(listener).toHaveBeenCalledWith(
+        expect.objectContaining({
+          previousTier: 'text',
+          newTier: 'ansi',
+        })
+      )
+    })
+
+    it('does not emit change event when setting same tier', () => {
+      const listener = vi.fn()
+      switcher.on('change', listener)
+
+      switcher.setTier('text') // Already text
+
+      expect(listener).not.toHaveBeenCalled()
+    })
+
+    it('validates tier value', () => {
+      // @ts-expect-error - Testing runtime validation
+      const result = switcher.setTier('invalid')
+      expect(result).toBe(false)
+    })
+  })
+
+  describe('getCapabilities', () => {
+    it('returns current capabilities', () => {
+      const caps = switcher.getCapabilities()
+      expect(caps).toEqual(mockFullCapabilities)
+    })
+
+    it('returns frozen object', () => {
+      const caps = switcher.getCapabilities()
+      expect(Object.isFrozen(caps)).toBe(true)
+    })
+  })
+
+  describe('getAvailableTiers', () => {
+    it('returns array of available tiers', () => {
+      const tiers = switcher.getAvailableTiers()
+      expect(tiers).toEqual(ALL_TIERS)
+    })
+
+    it('only returns supported tiers', () => {
+      const limitedSwitcher = createTierSwitcher({
+        capabilities: mockBasicCapabilities,
+      })
+
+      const tiers = limitedSwitcher.getAvailableTiers()
+      expect(tiers).toEqual(['text', 'markdown', 'ascii'])
+
+      limitedSwitcher.destroy()
+    })
+
+    it('returns tiers in capability order', () => {
+      const tiers = switcher.getAvailableTiers()
+      const orderMap = getTierOrder('map')
+
+      for (let i = 1; i < tiers.length; i++) {
+        expect(orderMap[tiers[i - 1]]).toBeLessThan(orderMap[tiers[i]])
+      }
+    })
+  })
+
+  describe('canSwitchTo', () => {
+    it('returns true for available tiers', () => {
+      expect(switcher.canSwitchTo('interactive')).toBe(true)
+    })
+
+    it('returns false for unavailable tiers', () => {
+      const limitedSwitcher = createTierSwitcher({
+        capabilities: mockBasicCapabilities,
+      })
+
+      expect(limitedSwitcher.canSwitchTo('ansi')).toBe(false)
+
+      limitedSwitcher.destroy()
+    })
+
+    it('always returns true for text tier', () => {
+      expect(switcher.canSwitchTo('text')).toBe(true)
+    })
+  })
+
+  describe('upgradeToHighest', () => {
+    it('switches to highest available tier', () => {
+      switcher.upgradeToHighest()
+      expect(switcher.getCurrentTier()).toBe('interactive')
+    })
+
+    it('respects capabilities', () => {
+      const limitedSwitcher = createTierSwitcher({
+        capabilities: mockAnsiCapabilities,
+        initialTier: 'text',
+      })
+
+      limitedSwitcher.upgradeToHighest()
+      expect(limitedSwitcher.getCurrentTier()).toBe('ansi')
+
+      limitedSwitcher.destroy()
+    })
+
+    it('returns new tier', () => {
+      const result = switcher.upgradeToHighest()
+      expect(result).toBe('interactive')
+    })
+  })
+
+  describe('downgradeToLowest', () => {
+    it('switches to text tier', () => {
+      switcher.setTier('ansi')
+      switcher.downgradeToLowest()
+      expect(switcher.getCurrentTier()).toBe('text')
+    })
+
+    it('returns text tier', () => {
+      const result = switcher.downgradeToLowest()
+      expect(result).toBe('text')
+    })
+  })
+
+  describe('upgradeOneLevel', () => {
+    it('switches to next higher tier', () => {
+      switcher.setTier('ascii')
+      const result = switcher.upgradeOneLevel()
+
+      expect(result).toBe('unicode')
+      expect(switcher.getCurrentTier()).toBe('unicode')
+    })
+
+    it('skips unavailable tiers', () => {
+      const limitedSwitcher = createTierSwitcher({
+        capabilities: {
+          ...mockBasicCapabilities,
+          ansi: true, // Skip unicode, go to ansi
+        },
+        initialTier: 'ascii',
+      })
+
+      limitedSwitcher.upgradeOneLevel()
+      expect(limitedSwitcher.getCurrentTier()).toBe('ansi')
+
+      limitedSwitcher.destroy()
+    })
+
+    it('returns same tier when already at highest', () => {
+      switcher.setTier('interactive')
+      const result = switcher.upgradeOneLevel()
+
+      expect(result).toBe('interactive')
+    })
+  })
+
+  describe('downgradeOneLevel', () => {
+    it('switches to next lower tier', () => {
+      switcher.setTier('ansi')
+      const result = switcher.downgradeOneLevel()
+
+      expect(result).toBe('unicode')
+      expect(switcher.getCurrentTier()).toBe('unicode')
+    })
+
+    it('returns text when already at lowest', () => {
+      switcher.setTier('text')
+      const result = switcher.downgradeOneLevel()
+
+      expect(result).toBe('text')
+    })
+  })
+})
+
+// ============================================================================
+// Graceful Fallback Tests
+// ============================================================================
+
+describe('Graceful Fallback', () => {
+  it('falls back to lower tier when requested tier unavailable', () => {
+    const switcher = createTierSwitcher({
+      capabilities: mockBasicCapabilities,
+      initialTier: 'text',
+      fallbackBehavior: 'downgrade',
+    })
+
+    const result = switcher.setTier('ansi', { fallback: true })
+
+    // Should fall back to ascii (highest available)
+    expect(result).toBe(true)
+    expect(switcher.getCurrentTier()).toBe('ascii')
+
+    switcher.destroy()
+  })
+
+  it('does not fallback when fallback is disabled', () => {
+    const switcher = createTierSwitcher({
+      capabilities: mockBasicCapabilities,
+      initialTier: 'text',
+    })
+
+    const result = switcher.setTier('ansi', { fallback: false })
+
+    expect(result).toBe(false)
+    expect(switcher.getCurrentTier()).toBe('text')
+
+    switcher.destroy()
+  })
+
+  it('emits fallback event when fallback occurs', () => {
+    const listener = vi.fn()
+    const switcher = createTierSwitcher({
+      capabilities: mockBasicCapabilities,
+      initialTier: 'text',
+      fallbackBehavior: 'downgrade',
+    })
+
+    switcher.on('fallback', listener)
+    switcher.setTier('interactive', { fallback: true })
+
+    expect(listener).toHaveBeenCalledWith(
+      expect.objectContaining({
+        requestedTier: 'interactive',
+        actualTier: 'ascii',
+        reason: 'unavailable',
+      })
+    )
+
+    switcher.destroy()
+  })
+
+  it('finds nearest available tier when falling back', () => {
+    const customCapabilities: TierCapabilities = {
+      text: true,
+      markdown: true,
+      ascii: true,
+      unicode: false,
+      ansi: true, // Skip unicode, support ansi
+      interactive: false,
+    }
+
+    const switcher = createTierSwitcher({
+      capabilities: customCapabilities,
+      initialTier: 'text',
+      fallbackBehavior: 'downgrade',
+    })
+
+    // Request interactive, should fall back to ansi
+    switcher.setTier('interactive', { fallback: true })
+    expect(switcher.getCurrentTier()).toBe('ansi')
+
+    switcher.destroy()
+  })
+})
+
+// ============================================================================
+// User Preference Override Tests
+// ============================================================================
+
+describe('User Preference Override', () => {
+  it('respects user preference even when higher tier available', () => {
+    const switcher = createTierSwitcher({
+      capabilities: mockFullCapabilities,
+      userPreference: 'ansi', // User prefers ansi over interactive
+      autoDetect: true,
+    })
+
+    expect(switcher.getCurrentTier()).toBe('ansi')
+
+    switcher.destroy()
+  })
+
+  it('allows setting user preference', () => {
+    const switcher = createTierSwitcher({
+      capabilities: mockFullCapabilities,
+    })
+
+    switcher.setUserPreference('unicode')
+    expect(switcher.getUserPreference()).toBe('unicode')
+
+    switcher.destroy()
+  })
+
+  it('falls back when user preference is unavailable', () => {
+    const switcher = createTierSwitcher({
+      capabilities: mockBasicCapabilities,
+      userPreference: 'ansi', // Not available
+      autoDetect: true,
+    })
+
+    // Should fall back to highest available (ascii)
+    expect(switcher.getCurrentTier()).toBe('ascii')
+
+    switcher.destroy()
+  })
+
+  it('clearing user preference returns to auto-detect behavior', () => {
+    const switcher = createTierSwitcher({
+      capabilities: mockFullCapabilities,
+      userPreference: 'text',
+      autoDetect: true,
+    })
+
+    expect(switcher.getCurrentTier()).toBe('text')
+
+    switcher.clearUserPreference()
+    expect(switcher.getUserPreference()).toBeNull()
+    // After clearing, should use highest available
+    expect(switcher.getCurrentTier()).toBe('interactive')
+
+    switcher.destroy()
+  })
+
+  it('persists user preference', () => {
+    const storage = new Map<string, string>()
+    const switcher = createTierSwitcher({
+      capabilities: mockFullCapabilities,
+      storage: {
+        get: (key) => storage.get(key) ?? null,
+        set: (key, value) => storage.set(key, value),
+        remove: (key) => storage.delete(key),
+      },
+    })
+
+    switcher.setUserPreference('unicode')
+
+    expect(storage.get('tier-preference')).toBe('unicode')
+
+    switcher.destroy()
+  })
+
+  it('loads user preference from storage', () => {
+    const storage = new Map<string, string>([['tier-preference', 'ansi']])
+    const switcher = createTierSwitcher({
+      capabilities: mockFullCapabilities,
+      storage: {
+        get: (key) => storage.get(key) ?? null,
+        set: (key, value) => storage.set(key, value),
+        remove: (key) => storage.delete(key),
+      },
+      autoDetect: true,
+    })
+
+    expect(switcher.getUserPreference()).toBe('ansi')
+    expect(switcher.getCurrentTier()).toBe('ansi')
+
+    switcher.destroy()
+  })
+})
+
+// ============================================================================
+// Re-render on Tier Change Tests
+// ============================================================================
+
+describe('Re-render on Tier Change', () => {
+  it('emits change event with re-render flag', () => {
+    const listener = vi.fn()
+    const switcher = createTierSwitcher({
+      capabilities: mockFullCapabilities,
+      initialTier: 'text',
+    })
+
+    switcher.on('change', listener)
+    switcher.setTier('ansi')
+
+    expect(listener).toHaveBeenCalledWith(
+      expect.objectContaining({
+        shouldRerender: true,
+      })
+    )
+
+    switcher.destroy()
+  })
+
+  it('provides requestRerender callback', () => {
+    const rerender = vi.fn()
+    const switcher = createTierSwitcher({
+      capabilities: mockFullCapabilities,
+      initialTier: 'text',
+      onRerender: rerender,
+    })
+
+    switcher.setTier('ansi')
+
+    expect(rerender).toHaveBeenCalled()
+
+    switcher.destroy()
+  })
+
+  it('allows suppressing re-render', () => {
+    const rerender = vi.fn()
+    const switcher = createTierSwitcher({
+      capabilities: mockFullCapabilities,
+      initialTier: 'text',
+      onRerender: rerender,
+    })
+
+    switcher.setTier('ansi', { rerender: false })
+
+    expect(rerender).not.toHaveBeenCalled()
+
+    switcher.destroy()
+  })
+
+  it('batches multiple tier changes', () => {
+    const rerender = vi.fn()
+    const switcher = createTierSwitcher({
+      capabilities: mockFullCapabilities,
+      initialTier: 'text',
+      onRerender: rerender,
+      batchRerenders: true,
+    })
+
+    switcher.batch(() => {
+      switcher.setTier('ascii')
+      switcher.setTier('unicode')
+      switcher.setTier('ansi')
+    })
+
+    // Should only call rerender once at end of batch
+    expect(rerender).toHaveBeenCalledTimes(1)
+
+    switcher.destroy()
+  })
+})
+
+// ============================================================================
+// Event System Tests
+// ============================================================================
+
+describe('Event System', () => {
+  let switcher: TierSwitcher
+
+  beforeEach(() => {
+    switcher = createTierSwitcher({
+      capabilities: mockFullCapabilities,
+      initialTier: 'text',
+    })
+  })
+
+  afterEach(() => {
+    switcher.destroy()
+  })
+
+  describe('on', () => {
+    it('registers change event listener', () => {
+      const listener = vi.fn()
+      switcher.on('change', listener)
+
+      switcher.setTier('ansi')
+
+      expect(listener).toHaveBeenCalled()
+    })
+
+    it('registers fallback event listener', () => {
+      const limitedSwitcher = createTierSwitcher({
+        capabilities: mockBasicCapabilities,
+        fallbackBehavior: 'downgrade',
+      })
+
+      const listener = vi.fn()
+      limitedSwitcher.on('fallback', listener)
+
+      limitedSwitcher.setTier('ansi', { fallback: true })
+
+      expect(listener).toHaveBeenCalled()
+
+      limitedSwitcher.destroy()
+    })
+
+    it('returns unsubscribe function', () => {
+      const listener = vi.fn()
+      const unsubscribe = switcher.on('change', listener)
+
+      unsubscribe()
+      switcher.setTier('ansi')
+
+      expect(listener).not.toHaveBeenCalled()
+    })
+
+    it('supports multiple listeners', () => {
+      const listener1 = vi.fn()
+      const listener2 = vi.fn()
+
+      switcher.on('change', listener1)
+      switcher.on('change', listener2)
+
+      switcher.setTier('ansi')
+
+      expect(listener1).toHaveBeenCalled()
+      expect(listener2).toHaveBeenCalled()
+    })
+  })
+
+  describe('off', () => {
+    it('removes event listener', () => {
+      const listener = vi.fn()
+      switcher.on('change', listener)
+      switcher.off('change', listener)
+
+      switcher.setTier('ansi')
+
+      expect(listener).not.toHaveBeenCalled()
+    })
+
+    it('handles removing non-existent listener', () => {
+      const listener = vi.fn()
+
+      // Should not throw
+      expect(() => switcher.off('change', listener)).not.toThrow()
+    })
+  })
+
+  describe('once', () => {
+    it('listener only fires once', () => {
+      const listener = vi.fn()
+      switcher.once('change', listener)
+
+      switcher.setTier('ascii')
+      switcher.setTier('unicode')
+
+      expect(listener).toHaveBeenCalledTimes(1)
+    })
+  })
+})
+
+// ============================================================================
+// TierChangeEvent Tests
+// ============================================================================
+
+describe('TierChangeEvent', () => {
+  it('contains previousTier and newTier', () => {
+    const listener = vi.fn()
+    const switcher = createTierSwitcher({
+      capabilities: mockFullCapabilities,
+      initialTier: 'text',
+    })
+
+    switcher.on('change', listener)
+    switcher.setTier('ansi')
+
+    const event: TierChangeEvent = listener.mock.calls[0][0]
+
+    expect(event.previousTier).toBe('text')
+    expect(event.newTier).toBe('ansi')
+
+    switcher.destroy()
+  })
+
+  it('contains timestamp', () => {
+    const listener = vi.fn()
+    const switcher = createTierSwitcher({
+      capabilities: mockFullCapabilities,
+      initialTier: 'text',
+    })
+
+    const beforeTime = Date.now()
+    switcher.on('change', listener)
+    switcher.setTier('ansi')
+    const afterTime = Date.now()
+
+    const event: TierChangeEvent = listener.mock.calls[0][0]
+
+    expect(event.timestamp).toBeGreaterThanOrEqual(beforeTime)
+    expect(event.timestamp).toBeLessThanOrEqual(afterTime)
+
+    switcher.destroy()
+  })
+
+  it('contains capabilities snapshot', () => {
+    const listener = vi.fn()
+    const switcher = createTierSwitcher({
+      capabilities: mockFullCapabilities,
+      initialTier: 'text',
+    })
+
+    switcher.on('change', listener)
+    switcher.setTier('ansi')
+
+    const event: TierChangeEvent = listener.mock.calls[0][0]
+
+    expect(event.capabilities).toEqual(mockFullCapabilities)
+
+    switcher.destroy()
+  })
+
+  it('contains shouldRerender flag', () => {
+    const listener = vi.fn()
+    const switcher = createTierSwitcher({
+      capabilities: mockFullCapabilities,
+      initialTier: 'text',
+    })
+
+    switcher.on('change', listener)
+    switcher.setTier('ansi')
+
+    const event: TierChangeEvent = listener.mock.calls[0][0]
+
+    expect(typeof event.shouldRerender).toBe('boolean')
+
+    switcher.destroy()
+  })
+})
+
+// ============================================================================
+// Lifecycle Tests
+// ============================================================================
+
+describe('Lifecycle', () => {
+  describe('destroy', () => {
+    it('removes all event listeners', () => {
+      const listener = vi.fn()
+      const switcher = createTierSwitcher({
+        capabilities: mockFullCapabilities,
+      })
+
+      switcher.on('change', listener)
+      switcher.destroy()
+
+      // Attempting to use after destroy should be safe
+      expect(() => switcher.setTier('ansi')).not.toThrow()
+      expect(listener).not.toHaveBeenCalled()
+    })
+
+    it('prevents further tier changes', () => {
+      const switcher = createTierSwitcher({
+        capabilities: mockFullCapabilities,
+        initialTier: 'text',
+      })
+
+      switcher.destroy()
+      const result = switcher.setTier('ansi')
+
+      expect(result).toBe(false)
+      expect(switcher.getCurrentTier()).toBe('text')
+    })
+
+    it('is idempotent', () => {
+      const switcher = createTierSwitcher()
+
+      // Multiple destroy calls should not throw
+      expect(() => {
+        switcher.destroy()
+        switcher.destroy()
+        switcher.destroy()
+      }).not.toThrow()
+    })
+  })
+
+  describe('isDestroyed', () => {
+    it('returns false initially', () => {
+      const switcher = createTierSwitcher()
+
+      expect(switcher.isDestroyed()).toBe(false)
+
+      switcher.destroy()
+    })
+
+    it('returns true after destroy', () => {
+      const switcher = createTierSwitcher()
+      switcher.destroy()
+
+      expect(switcher.isDestroyed()).toBe(true)
+    })
+  })
+})
+
+// ============================================================================
+// Integration Tests
+// ============================================================================
+
+describe('Integration', () => {
+  it('full tier switching workflow', () => {
+    const changes: TierChangeEvent[] = []
+    const switcher = createTierSwitcher({
+      capabilities: mockFullCapabilities,
+      autoDetect: true,
+      onChange: (event) => changes.push(event),
+    })
+
+    // Start at highest (interactive)
+    expect(switcher.getCurrentTier()).toBe('interactive')
+
+    // Downgrade to ANSI for piped output
+    switcher.setTier('ansi')
+    expect(switcher.getCurrentTier()).toBe('ansi')
+
+    // Set user preference
+    switcher.setUserPreference('unicode')
+    expect(switcher.getCurrentTier()).toBe('unicode')
+
+    // Clear preference, return to last set tier
+    switcher.clearUserPreference()
+    // Note: clearing preference doesn't auto-upgrade
+
+    expect(changes.length).toBeGreaterThan(0)
+
+    switcher.destroy()
+  })
+
+  it('graceful degradation when capabilities change', () => {
+    const switcher = createTierSwitcher({
+      capabilities: mockFullCapabilities,
+      initialTier: 'interactive',
+    })
+
+    // Simulate capabilities being reduced (e.g., output piped)
+    switcher.updateCapabilities(mockAnsiCapabilities)
+
+    // Should automatically fall back to highest available
+    expect(switcher.getCurrentTier()).toBe('ansi')
+
+    switcher.destroy()
+  })
+
+  it('handles rapid tier changes', () => {
+    const rerender = vi.fn()
+    const switcher = createTierSwitcher({
+      capabilities: mockFullCapabilities,
+      initialTier: 'text',
+      onRerender: rerender,
+      batchRerenders: true,
+      batchDelay: 10,
+    })
+
+    // Rapid changes
+    for (const tier of ALL_TIERS) {
+      switcher.setTier(tier)
+    }
+
+    // Wait for batch to complete
+    return new Promise<void>((resolve) => {
+      setTimeout(() => {
+        // Should have batched all re-renders
+        expect(rerender.mock.calls.length).toBeLessThan(ALL_TIERS.length)
+        expect(switcher.getCurrentTier()).toBe('interactive')
+        switcher.destroy()
+        resolve()
+      }, 50)
+    })
+  })
+})