docs: create comprehensive React/TypeScript migration plan

[justinpearson]

Summary

Creates a detailed migration plan for transitioning the Kid Pix codebase from vanilla JavaScript to React/TypeScript.

Related Issues

Parent Issue: #62 - Migrate from JS to React / TypeScript

Phase Issues:

• [SUB 62-a] Plan code migration #64 - [SUB 62-a] Plan code migration ✅ (this PR)
• [SUB 62-b] Phase 1: Foundation & Infrastructure #66 - [SUB 62-b] Phase 1: Foundation & Infrastructure
• [SUB 62-c] Phase 2: Core Systems #67 - [SUB 62-c] Phase 2: Core Systems
• [SUB 62-d] Phase 3: Simple Tools #68 - [SUB 62-d] Phase 3: Simple Tools
• [SUB 62-e] Phase 4: Complex Tools #69 - [SUB 62-e] Phase 4: Complex Tools
• [SUB 62-f] Phase 5: UI & Polish #70 - [SUB 62-f] Phase 5: UI & Polish

Plan Overview

5-Phase Incremental Migration (9-14 weeks):

1. Phase 1: Foundation & Infrastructure (1-2 weeks) - [SUB 62-b] Phase 1: Foundation & Infrastructure #66

   • TypeScript type definitions
   • Utility function migrations (colors, math, canvas, filters)
   • Canvas infrastructure completion (undo/redo, persistence)

2. Phase 2: Core Systems (2-3 weeks) - [SUB 62-c] Phase 2: Core Systems #67

   • Sound system with lazy loading
   • Event handling framework
   • Modifier key tracking

3. Phase 3: Simple Tools (2-3 weeks) - [SUB 62-d] Phase 3: Simple Tools #68

   • Migrate 5-10 simple tools (pencil, line, rectangle, oval, eraser)
   • Establish tool migration pattern
   • Prove approach with E2E tests

4. Phase 4: Complex Tools (3-4 weeks) - [SUB 62-e] Phase 4: Complex Tools #69

   • Brush system (20 variants)
   • Effect tools (mixer, firecracker, etc.)
   • Stamp system (200+ stamps)
   • Builder tools

5. Phase 5: UI & Polish (1-2 weeks) - [SUB 62-f] Phase 5: UI & Polish #70

   • Color palette, toolbar, submenus
   • Keyboard shortcuts
   • Performance optimization
   • Production cutover

Key Features

• Incremental approach: Bottom-up migration from utilities to UI
• Side-by-side operation: Both versions run concurrently via URL parameter (?react)
• Continuous validation: E2E tests at each phase boundary
• Pixel-perfect parity: Visual regression testing ensures identical rendering
• Detailed task breakdowns: Code examples and testing strategies for each task
• Risk mitigation: Risk assessment with contingency plans

Migration Strategy

The existing URL parameter system (?react) enables safe, gradual migration:

• Default: Vanilla JS version (production)
• ?react: React version (development)
• Benefits: A/B comparison, safe rollback, tool-by-tool validation

Testing Strategy

• Unit tests: 100% coverage target for utilities
• E2E tests: All 16 existing Playwright tests must pass
• Visual regression: Pixel-perfect comparison
• Performance benchmarks: React ≤ 105% of vanilla JS

What's Next

After this PR is merged:

1. Start Phase 1 ([SUB 62-b] Phase 1: Foundation & Infrastructure #66) implementation
2. Track progress with phase-level issues
3. Create PRs for each phase with comprehensive testing

Closes #64

🤖 Generated with Claude Code