chess/planning/analysis/performance-budget.md

Performance Budget - HTML Chess Game

Executive Summary

This document establishes comprehensive performance budgets for all components of the HTML chess game. These budgets serve as hard limits to ensure optimal user experience across all device types and network conditions.

Budget Philosophy: "Performance is a feature, not an afterthought"

---

1. Overall Performance Targets

Critical Web Vitals

Metric	Target	Good	Warning	Critical
First Contentful Paint (FCP)	<500ms	<1s	<2s	>2s
Largest Contentful Paint (LCP)	<1s	<2.5s	<4s	>4s
Time to Interactive (TTI)	<1s	<2s	<3.5s	>3.5s
Total Blocking Time (TBT)	<100ms	<300ms	<600ms	>600ms
Cumulative Layout Shift (CLS)	<0.05	<0.1	<0.25	>0.25
First Input Delay (FID)	<10ms	<100ms	<300ms	>300ms

Performance Score Targets

Metric	Desktop	Mobile	Tool
Lighthouse Performance	>95	>90	Chrome DevTools
WebPageTest Grade	A	A	WebPageTest.org
PageSpeed Insights	>95	>90	Google PSI

---

2. Bundle Size Budget

Total Budget: 150KB Gzipped (500KB Uncompressed)

Breakdown by Asset Type

Asset Type	Budget (Uncompressed)	Budget (Gzipped)	Priority
HTML	5KB	2KB	Critical
Critical CSS	8KB (inline)	3KB	Critical
Deferred CSS	20KB	7KB	High
Core JavaScript	100KB	35KB	Critical
AI Module (lazy)	80KB	28KB	High
UI Module	40KB	14KB	Critical
Utilities	30KB	10KB	Medium
SVG Pieces (sprite)	25KB	12KB	Critical
Sound Effects (lazy)	50KB	20KB	Low
Fonts (system fallback)	0KB	0KB	N/A
TOTAL CRITICAL	173KB	61KB	-
TOTAL WITH AI	253KB	89KB	-
TOTAL WITH SOUNDS	303KB	109KB	-

Component-Level Budget

Component	Uncompressed	Gzipped	Lines of Code	Complexity
ChessBoard.js	12KB	4KB	~300	Medium
ChessPiece.js	15KB	5KB	~350	Medium
GameEngine.js	20KB	7KB	~500	High
MoveValidator.js	18KB	6KB	~450	High
MoveGenerator.js	16KB	5.5KB	~400	High
GameController.js	14KB	5KB	~350	Medium
UIController.js	18KB	6KB	~450	Medium
GameHistory.js	10KB	3.5KB	~250	Low
ThemeManager.js	8KB	2.5KB	~200	Low
Utils.js	9KB	3KB	~225	Low
Core Subtotal	140KB	48.5KB	~3,475	-
AIPlayer.js	25KB	8.5KB	~600	High
MoveEvaluator.js	22KB	7.5KB	~550	High
SearchAlgorithm.js	28KB	10KB	~700	Very High
TranspositionTable.js	12KB	4KB	~300	Medium
AI Subtotal	87KB	30KB	~2,150	-
TOTAL	227KB	78.5KB	~5,625	-

Code Splitting Strategy

// Initial Load (Critical Path) - 61KB gzipped
- index.html (2KB)
- critical.css (3KB inline)
- core-ui.js (35KB) // Board, Pieces, Controller, Validator
- pieces.svg (12KB)

// Lazy Loaded (On Game Start) - 28KB gzipped
- ai-engine.js (28KB) // AI, Evaluator, Search

// Deferred (Progressive Enhancement) - 27KB gzipped
- styles.css (7KB) // Non-critical styles
- sounds.js + audio (20KB) // Sound effects

// Total Initial: 61KB gzipped
// Total With AI: 89KB gzipped
// Total Everything: 116KB gzipped

---

3. Runtime Performance Budget

3.1 Core Game Operations

Operation	Budget	Measurement	Monitoring
Move Validation	<5ms	p95	Performance.mark()
Legal Move Generation	<10ms	p95	Performance.mark()
Execute Move	<3ms	p99	Performance.mark()
Undo/Redo Move	<5ms	p99	Performance.mark()
Check Detection	<8ms	p95	Performance.mark()
Checkmate Detection	<15ms	p95	Performance.mark()
Board Render (Full)	<16ms (60fps)	p95	RequestAnimationFrame
Board Update (Diff)	<2ms	p99	RequestAnimationFrame
Piece Animation	<250ms	Always	CSS Transitions

3.2 AI Performance Budget

Difficulty	Depth	Max Time	Nodes Budget	Target Device
Random	0	<50ms	100	All
Beginner	2-3	<200ms	10,000	All
Intermediate	3-4	<500ms	100,000	Desktop/High-end Mobile
Advanced	4-5	<1s	500,000	Desktop/High-end Mobile
Expert	5-6	<2s	2,000,000	Desktop Only
Master	6-7	<5s	5,000,000	Desktop Only (Optional)

AI Optimization Targets

Optimization	Improvement Target	Implementation Complexity
Alpha-Beta Pruning	90% node reduction	High (8-10 hrs)
Move Ordering	50% additional reduction	Medium (5-6 hrs)
Transposition Table	30% speedup	High (8-10 hrs)
Iterative Deepening	Better UX (anytime)	Medium (4-5 hrs)
Quiescence Search	Quality (not speed)	High (6-8 hrs)
Web Workers	Non-blocking UI	High (6-8 hrs)

3.3 Rendering Performance Budget

Component	Frame Budget	Target FPS	Max Layout Shift
Board Rendering	<16ms	60fps	0
Piece Animation	<16ms	60fps	0
Highlight Updates	<8ms	120fps	0
UI Updates	<10ms	100fps	<0.01
Theme Changes	<100ms	N/A	<0.05
Scroll Performance	<16ms	60fps	0

Rendering Optimization Targets

Technique	Target Improvement	Browser Support
Virtual DOM / Diffing	5-10x faster updates	All modern
CSS Transform Animations	GPU acceleration	All modern
CSS Classes over Inline	2x faster updates	All
DocumentFragment	3x faster batch	All
RequestAnimationFrame	Consistent 60fps	All modern
will-change Property	Prevent layout thrash	All modern

---

4. Memory Budget

4.1 Heap Memory Budget

Device Class	Total Budget	Baseline	Game State	AI Cache	UI State
Desktop (Modern)	80MB	10MB	5MB	50MB	15MB
Desktop (Old)	50MB	10MB	5MB	25MB	10MB
Mobile (High-end)	40MB	8MB	5MB	20MB	7MB
Mobile (Mid-range)	25MB	8MB	5MB	8MB	4MB
Mobile (Low-end)	15MB	5MB	3MB	3MB	4MB

4.2 Component Memory Budget

Component	Budget	Notes
BoardState	2KB	64 squares + metadata
Move History	1KB/move	50 moves = 50KB
Transposition Table	5-50MB	Configurable by device
Move Cache	2MB	Recent positions
UI Event Listeners	1KB	Delegated events
Animation Buffers	5KB	Temporary
DOM Elements	3MB	64 squares + pieces

4.3 Garbage Collection Budget

Metric	Budget	Monitoring
GC Frequency	<1 per 30s	Performance API
Major GC Pause	<50ms	Performance API
Minor GC Pause	<10ms	Performance API
Heap Growth Rate	<1MB/min	Memory API
Memory Leaks	0	Chrome DevTools

Memory Optimization Techniques

Technique	Target	Complexity
Object Pooling	20-30% less GC	High (8-10 hrs)
Move History Truncation	Prevent growth	Medium (3-4 hrs)
Transposition Table Size Limits	Mobile stability	Low (2-3 hrs)
Weak References	Auto cleanup	Medium (4-5 hrs)
Lazy Evaluation	Reduce allocations	Medium (5-6 hrs)

---

5. Network Performance Budget (Future)

5.1 Initial Page Load

Resource Type	Budget	Caching	Priority
HTML Document	5KB	No cache	Highest
Critical CSS	3KB (inline)	N/A	Highest
Critical JS	35KB	1 year	Highest
SVG Sprite	12KB	1 year	High
Deferred CSS	7KB	1 year	Medium
AI Module	28KB	1 year	Medium
Sound Files	20KB	1 year	Low

5.2 Network Conditions

Connection	Target LCP	Target TTI	Max Bundle
5G	<300ms	<500ms	150KB
4G	<800ms	<1.2s	150KB
3G	<2s	<3s	100KB
Slow 3G	<5s	<8s	50KB
Offline	N/A	Cached	0KB

---

6. Device-Specific Budgets

6.1 Desktop Performance Budget

Metric	Modern (2020+)	Old (2015-2019)	Ancient (<2015)
FCP	<300ms	<500ms	<1s
LCP	<600ms	<1s	<2s
TTI	<800ms	<1.5s	<3s
AI Time (Depth 6)	<500ms	<1s	<2s
Frame Rate	60fps	60fps	45fps
Bundle Size	150KB	120KB	80KB
Memory Usage	80MB	50MB	30MB

6.2 Mobile Performance Budget

Metric	High-end	Mid-range	Low-end
FCP	<600ms	<1s	<2s
LCP	<1.2s	<2s	<3s
TTI	<1.5s	<2.5s	<4s
AI Time (Depth 4)	<1s	<2s	<5s
Frame Rate	60fps	45fps	30fps
Bundle Size	120KB	80KB	50KB
Memory Usage	40MB	25MB	15MB
Battery Impact	<3%/hour	<5%/hour	<8%/hour

---

7. Feature-Specific Budgets

7.1 Drag and Drop

Metric	Budget	Notes
Drag Start Latency	<10ms	Immediate feedback
Drag Update	<16ms (60fps)	Smooth tracking
Drop Detection	<5ms	Instant response
Animation	<250ms	Visual polish
Memory	<100KB	Temporary state

7.2 Pawn Promotion Dialog

Metric	Budget	Notes
Dialog Open	<50ms	Instant display
Selection Response	<10ms	Immediate
Animation	<200ms	Quick transition
Memory	<50KB	Temporary UI

7.3 Game History

Metric	Budget	Notes
Add Move	<2ms	Append operation
Undo/Redo	<5ms	State restoration
PGN Export	<50ms	String generation
History Display	<16ms	List rendering
Memory	1KB/move	Linear growth

7.4 Theme Switching

Metric	Budget	Notes
Theme Load	<100ms	CSS update
Color Update	<50ms	CSS variables
Piece Sprite Swap	<200ms	Image loading
Layout Shift	0	No reflow
Memory	<500KB	Theme data

---

8. Optimization Implementation Budget

8.1 Time Investment by Priority

Priority	Total Hours	ROI	Status
CRITICAL	28-36 hrs	10-100x improvement	Required
HIGH	41-50 hrs	3-5x improvement	Recommended
MEDIUM	14-18 hrs	1.5-2x improvement	Optional
TOTAL	83-104 hrs	15-200x improvement	-

8.2 Critical Optimizations (Must-Have)

Optimization	Time	Impact	Dependency
Alpha-Beta Pruning	8-10 hrs	10-100x AI speed	None
Web Workers	6-8 hrs	Non-blocking UI	None
DOM Diffing	6-8 hrs	5-10x render speed	None
CSS Transforms	4-5 hrs	GPU acceleration	None
Code Splitting	4-5 hrs	2x faster load	Build tools
TOTAL	28-36 hrs	Essential	Minimal

8.3 High Priority Optimizations (Should-Have)

Optimization	Time	Impact	Dependency
Move Ordering	5-6 hrs	2-3x AI speed	Alpha-Beta
Transposition Table	8-10 hrs	1.5-2x AI speed	Hash functions
Bundle Optimization	8-10 hrs	50% smaller	Build pipeline
Incremental Eval	10-12 hrs	1.5x AI speed	Evaluator
Mobile Optimization	10-12 hrs	Mobile support	Device detection
TOTAL	41-50 hrs	Significant	Moderate

8.4 Medium Priority Optimizations (Nice-to-Have)

Optimization	Time	Impact	Dependency
Iterative Deepening	4-5 hrs	Better UX	Alpha-Beta
Object Pooling	8-10 hrs	Reduced GC	None
SVG Optimization	2-3 hrs	50% smaller	SVGO tool
TOTAL	14-18 hrs	Polish	Low

---

9. Performance Monitoring Strategy

9.1 Development Metrics

Metric	Tool	Frequency	Alert Threshold
Bundle Size	Webpack	Every build	>150KB gzipped
Test Performance	Jest	Every run	>5s total
Lighthouse Score	CLI	Pre-commit	<90
Memory Leaks	Chrome DevTools	Weekly	Any detected
Code Coverage	Jest	Every push	<80%

9.2 Production Metrics (Future)

Metric	Tool	Sampling	P95 Target
Real User FCP	RUM	1%	<1s
Real User LCP	RUM	1%	<2s
Real User TTI	RUM	1%	<2.5s
AI Response Time	Custom	100%	<2s
Error Rate	Sentry	100%	<0.1%
Crash Rate	Sentry	100%	<0.01%

9.3 Performance Testing

// Performance Test Suite
describe('Performance Budget', () => {
  it('should render board in <16ms', () => {
    performance.mark('render-start');
    renderBoard();
    performance.mark('render-end');
    const duration = performance.measure('render', 'render-start', 'render-end');
    expect(duration.duration).toBeLessThan(16);
  });

  it('should calculate AI move in <1s (depth 5)', () => {
    const start = performance.now();
    const move = ai.calculateMove(position, { depth: 5 });
    const duration = performance.now() - start;
    expect(duration).toBeLessThan(1000);
  });

  it('should validate move in <5ms', () => {
    performance.mark('validate-start');
    const isValid = validator.isMoveLegal(from, to, gameState);
    performance.mark('validate-end');
    const duration = performance.measure('validate', 'validate-start', 'validate-end');
    expect(duration.duration).toBeLessThan(5);
  });

  it('should maintain 60fps during animation', async () => {
    const frameRates = await measureFrameRate(() => animateMove(from, to));
    expect(Math.min(...frameRates)).toBeGreaterThan(58);
  });

  it('should use <50MB memory on mobile', () => {
    if (isMobile()) {
      const memUsage = performance.memory.usedJSHeapSize / 1024 / 1024;
      expect(memUsage).toBeLessThan(50);
    }
  });
});

---

10. Budget Violation Response Plan

10.1 Budget Exceeded Protocol

Violation Severity	Response	Timeline
<10% Over	Document and plan fix	Next sprint
10-25% Over	Immediate investigation	24 hours
25-50% Over	Block merge, optimize	Before merge
>50% Over	Critical fix required	Immediate

10.2 Performance Regression Handling

// Pre-commit hook
if (bundleSize > BUDGET.bundleSize * 1.1) {
  console.error('❌ Bundle size exceeded budget by >10%');
  console.error(`Current: ${bundleSize}KB | Budget: ${BUDGET.bundleSize}KB`);
  process.exit(1);
}

if (lighthouseScore < 90) {
  console.warn('⚠️  Lighthouse score below threshold');
  console.warn(`Current: ${lighthouseScore} | Target: 90+`);
}

10.3 Optimization Priority Matrix

When budgets are exceeded, prioritize fixes by:

1. Impact: User-facing performance issues first
2. Effort: Quick wins before complex refactors
3. Risk: Low-risk optimizations before risky changes
4. Dependency: Independent fixes before dependent ones

---

11. Performance Budget Summary

Critical Metrics (Must Meet)

Metric	Budget	Priority
Lighthouse Score	>90	Critical
Initial Load (gzipped)	<61KB	Critical
FCP	<500ms	Critical
TTI	<1s	Critical
AI Response (Depth 5)	<1s	Critical
Frame Rate	60fps	Critical
Memory (Desktop)	<80MB	Critical
Memory (Mobile)	<40MB	Critical

Success Criteria

✅ Pass: All critical budgets met ⚠️ Warning: 1-2 budgets exceeded by <10% ❌ Fail: Any budget exceeded by >10% or 3+ budgets exceeded

---

12. Long-Term Performance Goals

Phase 1: MVP (Current)

• Meet all critical budgets
• 90+ Lighthouse score
• 60fps on desktop
• Basic mobile support

Phase 2: Optimization (2-3 weeks)

• 95+ Lighthouse score
• 60fps on high-end mobile
• <50KB initial bundle
• Advanced AI optimizations

Phase 3: Excellence (1-2 months)

• 98+ Lighthouse score
• 60fps on all devices
• <30KB initial bundle
• Best-in-class performance

---

Budget Maintenance

This performance budget is a living document and should be:

1. Reviewed: Every sprint
2. Updated: When requirements change
3. Enforced: On every commit
4. Celebrated: When exceeded in positive direction

Remember: "A performance budget is only useful if it's enforced."

---

Document Version: 1.0.0 Last Updated: 2025-11-22 Owner: Performance Optimizer Agent Review Cycle: Every Sprint