@mdxui/terminal 2.0.0

package/src/__tests__/core/types.test.ts

@@ -0,0 +1,1398 @@
+/**
+ * @mdxui/terminal UINode Type System Tests (RED phase)
+ *
+ * TDD RED Phase: These tests define the contract for the UINode type system
+ * that powers the Universal Terminal UI's multi-tier rendering architecture.
+ *
+ * The UINode system supports rendering to multiple tiers:
+ * - TEXT: Plain text without formatting
+ * - MARKDOWN: Markdown syntax for simple formatting
+ * - ASCII: ASCII art and basic drawing characters
+ * - UNICODE: Unicode box drawing and symbols
+ * - ANSI: Full ANSI escape sequences for colors/styles
+ * - INTERACTIVE: Full interactive terminal UI with input handling
+ *
+ * NOTE: These tests are expected to FAIL until implementation is complete.
+ * Run: pnpm --filter @mdxui/terminal test
+ */
+import { describe, it, expect, expectTypeOf } from 'vitest'
+import { z } from 'zod'
+
+// ============================================================================
+// These imports WILL FAIL until src/core/types.ts is implemented
+// ============================================================================
+import type {
+  UINode,
+  RenderTier,
+  RenderContext,
+  ThemeTokens,
+} from '../../core/types'
+
+import {
+  UINodeSchema,
+  RenderTierSchema,
+  RenderContextSchema,
+  ThemeTokensSchema,
+} from '../../core/types'
+
+// ============================================================================
+// UINode Interface Tests
+// ============================================================================
+
+describe('UINode Interface', () => {
+  describe('structure validation', () => {
+    it('requires type field as string', () => {
+      // UINode must have a type string identifying the component
+      const node: UINode = {
+        type: 'box',
+        props: {},
+      }
+
+      expect(node.type).toBe('box')
+      expectTypeOf(node.type).toBeString()
+    })
+
+    it('requires props field as Record<string, unknown>', () => {
+      const node: UINode = {
+        type: 'text',
+        props: {
+          bold: true,
+          content: 'Hello',
+          size: 14,
+        },
+      }
+
+      expect(node.props).toBeDefined()
+      expect(typeof node.props).toBe('object')
+      expectTypeOf(node.props).toEqualTypeOf<Record<string, unknown>>()
+    })
+
+    it('allows optional children array of UINodes', () => {
+      const node: UINode = {
+        type: 'box',
+        props: { padding: 1 },
+        children: [
+          { type: 'text', props: { content: 'Child 1' } },
+          { type: 'text', props: { content: 'Child 2' } },
+        ],
+      }
+
+      expect(node.children).toHaveLength(2)
+      expect(node.children![0].type).toBe('text')
+    })
+
+    it('allows undefined children', () => {
+      const node: UINode = {
+        type: 'text',
+        props: {},
+      }
+
+      expect(node.children).toBeUndefined()
+    })
+
+    it('allows optional data field for bound query data', () => {
+      const queryResult = { users: [{ id: 1, name: 'Alice' }] }
+      const node: UINode = {
+        type: 'table',
+        props: {},
+        data: queryResult,
+      }
+
+      expect(node.data).toBe(queryResult)
+    })
+
+    it('allows optional key field for React-style reconciliation', () => {
+      const node: UINode = {
+        type: 'list-item',
+        props: {},
+        key: 'item-123',
+      }
+
+      expect(node.key).toBe('item-123')
+      expectTypeOf(node.key).toEqualTypeOf<string | undefined>()
+    })
+
+    it('supports deeply nested children', () => {
+      const node: UINode = {
+        type: 'box',
+        props: {},
+        children: [
+          {
+            type: 'panel',
+            props: { title: 'Section' },
+            children: [
+              {
+                type: 'text',
+                props: { content: 'Nested content' },
+              },
+            ],
+          },
+        ],
+      }
+
+      expect(node.children![0].children![0].type).toBe('text')
+    })
+  })
+
+  describe('type inference', () => {
+    it('infers correct structure from UINode type', () => {
+      // Type-level test: ensure UINode has correct shape
+      expectTypeOf<UINode>().toHaveProperty('type')
+      expectTypeOf<UINode>().toHaveProperty('props')
+    })
+
+    it('children array contains only UINode types', () => {
+      type ChildrenType = UINode['children']
+      expectTypeOf<ChildrenType>().toEqualTypeOf<UINode[] | undefined>()
+    })
+  })
+})
+
+// ============================================================================
+// RenderTier Type Tests
+// ============================================================================
+
+describe('RenderTier Type', () => {
+  describe('tier completeness', () => {
+    it('includes text tier for plain text output', () => {
+      const tier: RenderTier = 'text'
+      expect(tier).toBe('text')
+    })
+
+    it('includes markdown tier for formatted text', () => {
+      const tier: RenderTier = 'markdown'
+      expect(tier).toBe('markdown')
+    })
+
+    it('includes ascii tier for ASCII art rendering', () => {
+      const tier: RenderTier = 'ascii'
+      expect(tier).toBe('ascii')
+    })
+
+    it('includes unicode tier for box drawing characters', () => {
+      const tier: RenderTier = 'unicode'
+      expect(tier).toBe('unicode')
+    })
+
+    it('includes ansi tier for colored terminal output', () => {
+      const tier: RenderTier = 'ansi'
+      expect(tier).toBe('ansi')
+    })
+
+    it('includes interactive tier for full terminal UI', () => {
+      const tier: RenderTier = 'interactive'
+      expect(tier).toBe('interactive')
+    })
+  })
+
+  describe('type exhaustiveness', () => {
+    it('only allows the 6 defined tiers', () => {
+      // This test verifies that RenderTier is a union of exactly 6 strings
+      const allTiers: RenderTier[] = [
+        'text',
+        'markdown',
+        'ascii',
+        'unicode',
+        'ansi',
+        'interactive',
+      ]
+
+      expect(allTiers).toHaveLength(6)
+
+      // Type-level check: each tier is assignable to RenderTier
+      allTiers.forEach((tier) => {
+        expectTypeOf(tier).toMatchTypeOf<RenderTier>()
+      })
+    })
+
+    it('rejects invalid tier strings at compile time', () => {
+      // This is a type-level test - invalid tiers should cause compile errors
+      // The test passes if the type system correctly rejects invalid values
+      // @ts-expect-error - 'invalid' is not a valid RenderTier
+      const _invalidTier: RenderTier = 'invalid'
+
+      // @ts-expect-error - 'html' is not a valid RenderTier
+      const _htmlTier: RenderTier = 'html'
+
+      // @ts-expect-error - numbers are not valid
+      const _numericTier: RenderTier = 42
+    })
+  })
+
+  describe('tier ordering', () => {
+    it('defines tiers in capability order (text < markdown < ascii < unicode < ansi < interactive)', () => {
+      // This documents the expected capability hierarchy
+      // Lower tiers have less capability, higher tiers have more
+      const tierOrder: Record<RenderTier, number> = {
+        text: 0,
+        markdown: 1,
+        ascii: 2,
+        unicode: 3,
+        ansi: 4,
+        interactive: 5,
+      }
+
+      expect(tierOrder.text).toBeLessThan(tierOrder.markdown)
+      expect(tierOrder.markdown).toBeLessThan(tierOrder.ascii)
+      expect(tierOrder.ascii).toBeLessThan(tierOrder.unicode)
+      expect(tierOrder.unicode).toBeLessThan(tierOrder.ansi)
+      expect(tierOrder.ansi).toBeLessThan(tierOrder.interactive)
+    })
+  })
+})
+
+// ============================================================================
+// RenderContext Interface Tests
+// ============================================================================
+
+describe('RenderContext Interface', () => {
+  describe('required fields', () => {
+    it('requires tier field of type RenderTier', () => {
+      const context: RenderContext = {
+        tier: 'ansi',
+        width: 80,
+        height: 24,
+        depth: 0,
+        theme: {} as ThemeTokens,
+        interactive: false,
+      }
+
+      expect(context.tier).toBe('ansi')
+      expectTypeOf(context.tier).toEqualTypeOf<RenderTier>()
+    })
+
+    it('requires width field as number', () => {
+      const context: RenderContext = {
+        tier: 'text',
+        width: 120,
+        height: 40,
+        depth: 0,
+        theme: {} as ThemeTokens,
+        interactive: false,
+      }
+
+      expect(context.width).toBe(120)
+      expectTypeOf(context.width).toBeNumber()
+    })
+
+    it('requires height field as number', () => {
+      const context: RenderContext = {
+        tier: 'text',
+        width: 80,
+        height: 24,
+        depth: 0,
+        theme: {} as ThemeTokens,
+        interactive: false,
+      }
+
+      expect(context.height).toBe(24)
+      expectTypeOf(context.height).toBeNumber()
+    })
+
+    it('requires depth field as number for nesting level', () => {
+      const context: RenderContext = {
+        tier: 'unicode',
+        width: 80,
+        height: 24,
+        depth: 3,
+        theme: {} as ThemeTokens,
+        interactive: false,
+      }
+
+      expect(context.depth).toBe(3)
+      expectTypeOf(context.depth).toBeNumber()
+    })
+
+    it('requires theme field of type ThemeTokens', () => {
+      const theme: ThemeTokens = {
+        primary: '\x1b[34m',
+        secondary: '\x1b[36m',
+        muted: '\x1b[90m',
+        foreground: '\x1b[37m',
+        background: '\x1b[40m',
+        border: '\x1b[90m',
+        success: '\x1b[32m',
+        warning: '\x1b[33m',
+        error: '\x1b[31m',
+        info: '\x1b[34m',
+      }
+
+      const context: RenderContext = {
+        tier: 'ansi',
+        width: 80,
+        height: 24,
+        depth: 0,
+        theme,
+        interactive: false,
+      }
+
+      expect(context.theme).toBe(theme)
+      expectTypeOf(context.theme).toEqualTypeOf<ThemeTokens>()
+    })
+
+    it('requires interactive field as boolean', () => {
+      const context: RenderContext = {
+        tier: 'interactive',
+        width: 80,
+        height: 24,
+        depth: 0,
+        theme: {} as ThemeTokens,
+        interactive: true,
+      }
+
+      expect(context.interactive).toBe(true)
+      expectTypeOf(context.interactive).toBeBoolean()
+    })
+  })
+
+  describe('field semantics', () => {
+    it('width represents terminal column count', () => {
+      const context: RenderContext = {
+        tier: 'text',
+        width: 80,
+        height: 24,
+        depth: 0,
+        theme: {} as ThemeTokens,
+        interactive: false,
+      }
+
+      // Standard terminal width
+      expect(context.width).toBeGreaterThan(0)
+    })
+
+    it('height represents terminal row count', () => {
+      const context: RenderContext = {
+        tier: 'text',
+        width: 80,
+        height: 24,
+        depth: 0,
+        theme: {} as ThemeTokens,
+        interactive: false,
+      }
+
+      // Standard terminal height
+      expect(context.height).toBeGreaterThan(0)
+    })
+
+    it('depth starts at 0 for root components', () => {
+      const rootContext: RenderContext = {
+        tier: 'text',
+        width: 80,
+        height: 24,
+        depth: 0,
+        theme: {} as ThemeTokens,
+        interactive: false,
+      }
+
+      expect(rootContext.depth).toBe(0)
+    })
+
+    it('depth increments for nested components', () => {
+      const nestedContext: RenderContext = {
+        tier: 'text',
+        width: 80,
+        height: 24,
+        depth: 2,
+        theme: {} as ThemeTokens,
+        interactive: false,
+      }
+
+      expect(nestedContext.depth).toBe(2)
+    })
+
+    it('interactive is true only for interactive tier', () => {
+      const textContext: RenderContext = {
+        tier: 'text',
+        width: 80,
+        height: 24,
+        depth: 0,
+        theme: {} as ThemeTokens,
+        interactive: false,
+      }
+
+      const interactiveContext: RenderContext = {
+        tier: 'interactive',
+        width: 80,
+        height: 24,
+        depth: 0,
+        theme: {} as ThemeTokens,
+        interactive: true,
+      }
+
+      expect(textContext.interactive).toBe(false)
+      expect(interactiveContext.interactive).toBe(true)
+    })
+  })
+})
+
+// ============================================================================
+// ThemeTokens Interface Tests
+// ============================================================================
+
+describe('ThemeTokens Interface', () => {
+  describe('required color tokens', () => {
+    it('includes primary color token', () => {
+      const theme: ThemeTokens = {
+        primary: '\x1b[34m',
+        secondary: '',
+        muted: '',
+        foreground: '',
+        background: '',
+        border: '',
+        success: '',
+        warning: '',
+        error: '',
+        info: '',
+      }
+
+      expect(theme.primary).toBe('\x1b[34m')
+    })
+
+    it('includes secondary color token', () => {
+      const theme: ThemeTokens = {
+        primary: '',
+        secondary: '\x1b[36m',
+        muted: '',
+        foreground: '',
+        background: '',
+        border: '',
+        success: '',
+        warning: '',
+        error: '',
+        info: '',
+      }
+
+      expect(theme.secondary).toBe('\x1b[36m')
+    })
+
+    it('includes muted color token', () => {
+      const theme: ThemeTokens = {
+        primary: '',
+        secondary: '',
+        muted: '\x1b[90m',
+        foreground: '',
+        background: '',
+        border: '',
+        success: '',
+        warning: '',
+        error: '',
+        info: '',
+      }
+
+      expect(theme.muted).toBe('\x1b[90m')
+    })
+
+    it('includes foreground color token', () => {
+      const theme: ThemeTokens = {
+        primary: '',
+        secondary: '',
+        muted: '',
+        foreground: '\x1b[37m',
+        background: '',
+        border: '',
+        success: '',
+        warning: '',
+        error: '',
+        info: '',
+      }
+
+      expect(theme.foreground).toBe('\x1b[37m')
+    })
+
+    it('includes background color token', () => {
+      const theme: ThemeTokens = {
+        primary: '',
+        secondary: '',
+        muted: '',
+        foreground: '',
+        background: '\x1b[40m',
+        border: '',
+        success: '',
+        warning: '',
+        error: '',
+        info: '',
+      }
+
+      expect(theme.background).toBe('\x1b[40m')
+    })
+
+    it('includes border color token', () => {
+      const theme: ThemeTokens = {
+        primary: '',
+        secondary: '',
+        muted: '',
+        foreground: '',
+        background: '',
+        border: '\x1b[90m',
+        success: '',
+        warning: '',
+        error: '',
+        info: '',
+      }
+
+      expect(theme.border).toBe('\x1b[90m')
+    })
+
+    it('includes semantic status tokens (success, warning, error, info)', () => {
+      const theme: ThemeTokens = {
+        primary: '',
+        secondary: '',
+        muted: '',
+        foreground: '',
+        background: '',
+        border: '',
+        success: '\x1b[32m',
+        warning: '\x1b[33m',
+        error: '\x1b[31m',
+        info: '\x1b[34m',
+      }
+
+      expect(theme.success).toBe('\x1b[32m')
+      expect(theme.warning).toBe('\x1b[33m')
+      expect(theme.error).toBe('\x1b[31m')
+      expect(theme.info).toBe('\x1b[34m')
+    })
+  })
+
+  describe('token type requirements', () => {
+    it('all tokens are strings (ANSI escape sequences)', () => {
+      const theme: ThemeTokens = {
+        primary: '\x1b[34m',
+        secondary: '\x1b[36m',
+        muted: '\x1b[90m',
+        foreground: '\x1b[37m',
+        background: '\x1b[40m',
+        border: '\x1b[90m',
+        success: '\x1b[32m',
+        warning: '\x1b[33m',
+        error: '\x1b[31m',
+        info: '\x1b[34m',
+      }
+
+      Object.values(theme).forEach((value) => {
+        expect(typeof value).toBe('string')
+      })
+    })
+  })
+})
+
+// ============================================================================
+// Zod Schema Tests - UINodeSchema
+// ============================================================================
+
+describe('UINodeSchema (Zod)', () => {
+  describe('valid UINode objects', () => {
+    it('parses minimal valid UINode', () => {
+      const input = {
+        type: 'text',
+        props: {},
+      }
+
+      const result = UINodeSchema.safeParse(input)
+      expect(result.success).toBe(true)
+      if (result.success) {
+        expect(result.data.type).toBe('text')
+        expect(result.data.props).toEqual({})
+      }
+    })
+
+    it('parses UINode with props', () => {
+      const input = {
+        type: 'box',
+        props: {
+          padding: 2,
+          border: 'single',
+          bg: '#1a1a1a',
+        },
+      }
+
+      const result = UINodeSchema.safeParse(input)
+      expect(result.success).toBe(true)
+      if (result.success) {
+        expect(result.data.props.padding).toBe(2)
+      }
+    })
+
+    it('parses UINode with children', () => {
+      const input = {
+        type: 'box',
+        props: {},
+        children: [
+          { type: 'text', props: { content: 'Hello' } },
+          { type: 'text', props: { content: 'World' } },
+        ],
+      }
+
+      const result = UINodeSchema.safeParse(input)
+      expect(result.success).toBe(true)
+      if (result.success) {
+        expect(result.data.children).toHaveLength(2)
+      }
+    })
+
+    it('parses UINode with deeply nested children', () => {
+      const input = {
+        type: 'panel',
+        props: { title: 'Container' },
+        children: [
+          {
+            type: 'box',
+            props: {},
+            children: [
+              {
+                type: 'text',
+                props: { content: 'Deep' },
+                children: [],
+              },
+            ],
+          },
+        ],
+      }
+
+      const result = UINodeSchema.safeParse(input)
+      expect(result.success).toBe(true)
+    })
+
+    it('parses UINode with data binding', () => {
+      const input = {
+        type: 'table',
+        props: {},
+        data: {
+          rows: [
+            { id: 1, name: 'Alice' },
+            { id: 2, name: 'Bob' },
+          ],
+        },
+      }
+
+      const result = UINodeSchema.safeParse(input)
+      expect(result.success).toBe(true)
+      if (result.success) {
+        expect(result.data.data).toEqual({
+          rows: [
+            { id: 1, name: 'Alice' },
+            { id: 2, name: 'Bob' },
+          ],
+        })
+      }
+    })
+
+    it('parses UINode with key', () => {
+      const input = {
+        type: 'list-item',
+        props: {},
+        key: 'item-42',
+      }
+
+      const result = UINodeSchema.safeParse(input)
+      expect(result.success).toBe(true)
+      if (result.success) {
+        expect(result.data.key).toBe('item-42')
+      }
+    })
+
+    it('parses UINode with all optional fields', () => {
+      const input = {
+        type: 'complex',
+        props: { flag: true, count: 5 },
+        children: [{ type: 'child', props: {} }],
+        data: { fetched: true },
+        key: 'unique-key',
+      }
+
+      const result = UINodeSchema.safeParse(input)
+      expect(result.success).toBe(true)
+    })
+  })
+
+  describe('invalid UINode objects', () => {
+    it('rejects missing type field', () => {
+      const input = {
+        props: {},
+      }
+
+      const result = UINodeSchema.safeParse(input)
+      expect(result.success).toBe(false)
+      if (!result.success) {
+        expect(result.error.issues[0].path).toContain('type')
+      }
+    })
+
+    it('accepts missing props field (props is optional)', () => {
+      const input = {
+        type: 'text',
+      }
+
+      const result = UINodeSchema.safeParse(input)
+      expect(result.success).toBe(true)
+    })
+
+    it('rejects non-string type field', () => {
+      const input = {
+        type: 123,
+        props: {},
+      }
+
+      const result = UINodeSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects non-object props field', () => {
+      const input = {
+        type: 'text',
+        props: 'not an object',
+      }
+
+      const result = UINodeSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+
+    it('accepts string children field (children can be string or array)', () => {
+      const input = {
+        type: 'box',
+        props: {},
+        children: 'string content',
+      }
+
+      const result = UINodeSchema.safeParse(input)
+      expect(result.success).toBe(true)
+    })
+
+    it('rejects invalid children elements', () => {
+      const input = {
+        type: 'box',
+        props: {},
+        children: [
+          { type: 'valid', props: {} },
+          'invalid child',
+          { missingType: true, props: {} },
+        ],
+      }
+
+      const result = UINodeSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects non-string key field', () => {
+      const input = {
+        type: 'item',
+        props: {},
+        key: 42,
+      }
+
+      const result = UINodeSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects null input', () => {
+      const result = UINodeSchema.safeParse(null)
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects undefined input', () => {
+      const result = UINodeSchema.safeParse(undefined)
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects array input', () => {
+      const result = UINodeSchema.safeParse([{ type: 'text', props: {} }])
+      expect(result.success).toBe(false)
+    })
+  })
+
+  describe('error messages', () => {
+    it('provides clear error for missing type', () => {
+      const result = UINodeSchema.safeParse({ props: {} })
+      expect(result.success).toBe(false)
+      if (!result.success) {
+        const typeError = result.error.issues.find((i) => i.path.includes('type'))
+        expect(typeError).toBeDefined()
+      }
+    })
+
+    it('provides clear error for invalid nested children', () => {
+      const input = {
+        type: 'box',
+        props: {},
+        children: [
+          {
+            type: 'panel',
+            props: {},
+            children: [
+              { props: {} }, // Missing type
+            ],
+          },
+        ],
+      }
+
+      const result = UINodeSchema.safeParse(input)
+      expect(result.success).toBe(false)
+      if (!result.success) {
+        // Error path should indicate the nested location
+        const hasNestedPath = result.error.issues.some(
+          (i) => i.path.includes('children')
+        )
+        expect(hasNestedPath).toBe(true)
+      }
+    })
+  })
+})
+
+// ============================================================================
+// Zod Schema Tests - RenderTierSchema
+// ============================================================================
+
+describe('RenderTierSchema (Zod)', () => {
+  describe('valid tiers', () => {
+    it('parses "text" tier', () => {
+      const result = RenderTierSchema.safeParse('text')
+      expect(result.success).toBe(true)
+      expect(result.data).toBe('text')
+    })
+
+    it('parses "markdown" tier', () => {
+      const result = RenderTierSchema.safeParse('markdown')
+      expect(result.success).toBe(true)
+      expect(result.data).toBe('markdown')
+    })
+
+    it('parses "ascii" tier', () => {
+      const result = RenderTierSchema.safeParse('ascii')
+      expect(result.success).toBe(true)
+      expect(result.data).toBe('ascii')
+    })
+
+    it('parses "unicode" tier', () => {
+      const result = RenderTierSchema.safeParse('unicode')
+      expect(result.success).toBe(true)
+      expect(result.data).toBe('unicode')
+    })
+
+    it('parses "ansi" tier', () => {
+      const result = RenderTierSchema.safeParse('ansi')
+      expect(result.success).toBe(true)
+      expect(result.data).toBe('ansi')
+    })
+
+    it('parses "interactive" tier', () => {
+      const result = RenderTierSchema.safeParse('interactive')
+      expect(result.success).toBe(true)
+      expect(result.data).toBe('interactive')
+    })
+  })
+
+  describe('invalid tiers', () => {
+    it('rejects empty string', () => {
+      const result = RenderTierSchema.safeParse('')
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects unknown tier names', () => {
+      const invalidTiers = ['html', 'pdf', 'json', 'xml', 'rich', 'plain']
+
+      invalidTiers.forEach((tier) => {
+        const result = RenderTierSchema.safeParse(tier)
+        expect(result.success).toBe(false)
+      })
+    })
+
+    it('rejects uppercase variants', () => {
+      const result = RenderTierSchema.safeParse('TEXT')
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects numeric values', () => {
+      const result = RenderTierSchema.safeParse(1)
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects null', () => {
+      const result = RenderTierSchema.safeParse(null)
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects undefined', () => {
+      const result = RenderTierSchema.safeParse(undefined)
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects objects', () => {
+      const result = RenderTierSchema.safeParse({ tier: 'text' })
+      expect(result.success).toBe(false)
+    })
+  })
+})
+
+// ============================================================================
+// Zod Schema Tests - RenderContextSchema
+// ============================================================================
+
+describe('RenderContextSchema (Zod)', () => {
+  describe('valid RenderContext objects', () => {
+    it('parses valid RenderContext with all required fields', () => {
+      const input = {
+        tier: 'ansi',
+        width: 80,
+        height: 24,
+        depth: 0,
+        theme: {
+          primary: '\x1b[34m',
+          secondary: '\x1b[36m',
+          muted: '\x1b[90m',
+          foreground: '\x1b[37m',
+          background: '\x1b[40m',
+          border: '\x1b[90m',
+          success: '\x1b[32m',
+          warning: '\x1b[33m',
+          error: '\x1b[31m',
+          info: '\x1b[34m',
+        },
+        interactive: false,
+      }
+
+      const result = RenderContextSchema.safeParse(input)
+      expect(result.success).toBe(true)
+    })
+
+    it('parses RenderContext with interactive tier', () => {
+      const input = {
+        tier: 'interactive',
+        width: 120,
+        height: 40,
+        depth: 0,
+        theme: {
+          primary: '',
+          secondary: '',
+          muted: '',
+          foreground: '',
+          background: '',
+          border: '',
+          success: '',
+          warning: '',
+          error: '',
+          info: '',
+        },
+        interactive: true,
+      }
+
+      const result = RenderContextSchema.safeParse(input)
+      expect(result.success).toBe(true)
+    })
+
+    it('parses RenderContext with non-zero depth', () => {
+      const input = {
+        tier: 'text',
+        width: 80,
+        height: 24,
+        depth: 5,
+        theme: {
+          primary: '',
+          secondary: '',
+          muted: '',
+          foreground: '',
+          background: '',
+          border: '',
+          success: '',
+          warning: '',
+          error: '',
+          info: '',
+        },
+        interactive: false,
+      }
+
+      const result = RenderContextSchema.safeParse(input)
+      expect(result.success).toBe(true)
+      if (result.success) {
+        expect(result.data.depth).toBe(5)
+      }
+    })
+  })
+
+  describe('invalid RenderContext objects', () => {
+    const validTheme = {
+      primary: '',
+      secondary: '',
+      muted: '',
+      foreground: '',
+      background: '',
+      border: '',
+      success: '',
+      warning: '',
+      error: '',
+      info: '',
+    }
+
+    it('rejects missing tier field', () => {
+      const input = {
+        width: 80,
+        height: 24,
+        depth: 0,
+        theme: validTheme,
+        interactive: false,
+      }
+
+      const result = RenderContextSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects invalid tier value', () => {
+      const input = {
+        tier: 'invalid-tier',
+        width: 80,
+        height: 24,
+        depth: 0,
+        theme: validTheme,
+        interactive: false,
+      }
+
+      const result = RenderContextSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects missing width field', () => {
+      const input = {
+        tier: 'text',
+        height: 24,
+        depth: 0,
+        theme: validTheme,
+        interactive: false,
+      }
+
+      const result = RenderContextSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects non-numeric width', () => {
+      const input = {
+        tier: 'text',
+        width: '80',
+        height: 24,
+        depth: 0,
+        theme: validTheme,
+        interactive: false,
+      }
+
+      const result = RenderContextSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects negative width', () => {
+      const input = {
+        tier: 'text',
+        width: -1,
+        height: 24,
+        depth: 0,
+        theme: validTheme,
+        interactive: false,
+      }
+
+      const result = RenderContextSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects missing height field', () => {
+      const input = {
+        tier: 'text',
+        width: 80,
+        depth: 0,
+        theme: validTheme,
+        interactive: false,
+      }
+
+      const result = RenderContextSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects negative height', () => {
+      const input = {
+        tier: 'text',
+        width: 80,
+        height: -10,
+        depth: 0,
+        theme: validTheme,
+        interactive: false,
+      }
+
+      const result = RenderContextSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects missing depth field', () => {
+      const input = {
+        tier: 'text',
+        width: 80,
+        height: 24,
+        theme: validTheme,
+        interactive: false,
+      }
+
+      const result = RenderContextSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects negative depth', () => {
+      const input = {
+        tier: 'text',
+        width: 80,
+        height: 24,
+        depth: -1,
+        theme: validTheme,
+        interactive: false,
+      }
+
+      const result = RenderContextSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects missing theme field', () => {
+      const input = {
+        tier: 'text',
+        width: 80,
+        height: 24,
+        depth: 0,
+        interactive: false,
+      }
+
+      const result = RenderContextSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects theme with missing tokens', () => {
+      const input = {
+        tier: 'text',
+        width: 80,
+        height: 24,
+        depth: 0,
+        theme: {
+          primary: '',
+          // Missing other required tokens
+        },
+        interactive: false,
+      }
+
+      const result = RenderContextSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects missing interactive field', () => {
+      const input = {
+        tier: 'text',
+        width: 80,
+        height: 24,
+        depth: 0,
+        theme: validTheme,
+      }
+
+      const result = RenderContextSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects non-boolean interactive field', () => {
+      const input = {
+        tier: 'text',
+        width: 80,
+        height: 24,
+        depth: 0,
+        theme: validTheme,
+        interactive: 'yes',
+      }
+
+      const result = RenderContextSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+  })
+})
+
+// ============================================================================
+// Zod Schema Tests - ThemeTokensSchema
+// ============================================================================
+
+describe('ThemeTokensSchema (Zod)', () => {
+  describe('valid ThemeTokens objects', () => {
+    it('parses valid ThemeTokens with all tokens', () => {
+      const input = {
+        primary: '\x1b[34m',
+        secondary: '\x1b[36m',
+        muted: '\x1b[90m',
+        foreground: '\x1b[37m',
+        background: '\x1b[40m',
+        border: '\x1b[90m',
+        success: '\x1b[32m',
+        warning: '\x1b[33m',
+        error: '\x1b[31m',
+        info: '\x1b[34m',
+      }
+
+      const result = ThemeTokensSchema.safeParse(input)
+      expect(result.success).toBe(true)
+    })
+
+    it('parses ThemeTokens with empty string tokens (for text tier)', () => {
+      const input = {
+        primary: '',
+        secondary: '',
+        muted: '',
+        foreground: '',
+        background: '',
+        border: '',
+        success: '',
+        warning: '',
+        error: '',
+        info: '',
+      }
+
+      const result = ThemeTokensSchema.safeParse(input)
+      expect(result.success).toBe(true)
+    })
+  })
+
+  describe('invalid ThemeTokens objects', () => {
+    it('rejects missing primary token', () => {
+      const input = {
+        secondary: '',
+        muted: '',
+        foreground: '',
+        background: '',
+        border: '',
+        success: '',
+        warning: '',
+        error: '',
+        info: '',
+      }
+
+      const result = ThemeTokensSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects missing semantic tokens', () => {
+      const input = {
+        primary: '',
+        secondary: '',
+        muted: '',
+        foreground: '',
+        background: '',
+        border: '',
+        // Missing success, warning, error, info
+      }
+
+      const result = ThemeTokensSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects non-string token values', () => {
+      const input = {
+        primary: 123,
+        secondary: '',
+        muted: '',
+        foreground: '',
+        background: '',
+        border: '',
+        success: '',
+        warning: '',
+        error: '',
+        info: '',
+      }
+
+      const result = ThemeTokensSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects null token values', () => {
+      const input = {
+        primary: null,
+        secondary: '',
+        muted: '',
+        foreground: '',
+        background: '',
+        border: '',
+        success: '',
+        warning: '',
+        error: '',
+        info: '',
+      }
+
+      const result = ThemeTokensSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+  })
+})
+
+// ============================================================================
+// Type Coercion Behavior Tests
+// ============================================================================
+
+describe('Schema type coercion', () => {
+  describe('UINodeSchema coercion', () => {
+    it('does not coerce props array to object', () => {
+      const input = {
+        type: 'text',
+        props: ['invalid', 'array'],
+      }
+
+      const result = UINodeSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+
+    it('does not coerce numeric type to string', () => {
+      const input = {
+        type: 42,
+        props: {},
+      }
+
+      const result = UINodeSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+  })
+
+  describe('RenderContextSchema coercion', () => {
+    it('does not coerce string numbers to numbers', () => {
+      const input = {
+        tier: 'text',
+        width: '80',
+        height: '24',
+        depth: '0',
+        theme: {
+          primary: '',
+          secondary: '',
+          muted: '',
+          foreground: '',
+          background: '',
+          border: '',
+          success: '',
+          warning: '',
+          error: '',
+          info: '',
+        },
+        interactive: false,
+      }
+
+      const result = RenderContextSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+
+    it('does not coerce string boolean to boolean', () => {
+      const input = {
+        tier: 'text',
+        width: 80,
+        height: 24,
+        depth: 0,
+        theme: {
+          primary: '',
+          secondary: '',
+          muted: '',
+          foreground: '',
+          background: '',
+          border: '',
+          success: '',
+          warning: '',
+          error: '',
+          info: '',
+        },
+        interactive: 'true',
+      }
+
+      const result = RenderContextSchema.safeParse(input)
+      expect(result.success).toBe(false)
+    })
+  })
+})