From 28f86d781c416e55124acd26f439aebdbeb47e0e Mon Sep 17 00:00:00 2001
From: Dabit <dabit@localhost>
Date: Tue, 10 Mar 2026 14:18:11 +0100
Subject: [PATCH] docs: complete project research synthesis

Synthesized 4 parallel research efforts into comprehensive SUMMARY.md:
- STACK.md: Vanilla Canvas 2D, fixed timestep, Web Audio, no dependencies
- FEATURES.md: MVP features + v1.x enhancements + defer list
- ARCHITECTURE.md: Game loop + state machine + entity patterns, 10-phase build order
- PITFALLS.md: 8 critical pitfalls with prevention strategies

Key recommendations:
- Use fixed timestep accumulator (60 Hz physics, variable rendering)
- Implement 10 phases from game loop foundation to cross-browser testing
- Address critical pitfalls early (tunneling, timing, DPI, autoplay, AI, power-ups, lag, memory)
- MVP ships with core Pong + AI + menus + basic polish
- v1.x adds particles, trails, power-ups, arenas

All research backed by official sources (MDN, web.dev, Chrome docs) and established patterns.
Confidence: HIGH. Ready for requirements definition.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .planning/research/ARCHITECTURE.md | 790 +++++++++++++++++++++++++++++
 .planning/research/FEATURES.md     | 246 +++++++++
 .planning/research/PITFALLS.md     | 420 +++++++++++++++
 .planning/research/STACK.md        | 328 ++++++++++++
 .planning/research/SUMMARY.md      | 227 +++++++++
 5 files changed, 2011 insertions(+)
 create mode 100644 .planning/research/ARCHITECTURE.md
 create mode 100644 .planning/research/FEATURES.md
 create mode 100644 .planning/research/PITFALLS.md
 create mode 100644 .planning/research/STACK.md
 create mode 100644 .planning/research/SUMMARY.md

diff --git a/.planning/research/ARCHITECTURE.md b/.planning/research/ARCHITECTURE.md
new file mode 100644
index 0000000..a04bc0f
--- /dev/null
+++ b/.planning/research/ARCHITECTURE.md
@@ -0,0 +1,790 @@
+# Architecture Research: HTML5 Canvas Arcade Games
+
+**Domain:** HTML5 Canvas 2D arcade games (Pong-like)
+**Researched:** 2026-03-10
+**Confidence:** HIGH
+
+## Standard Architecture
+
+### System Overview
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│                      Presentation Layer                         │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
+│  │ Canvas View  │  │  UI Layer    │  │  Audio Out   │          │
+│  │  (rendering) │  │  (DOM menus) │  │  (Web Audio) │          │
+│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘          │
+│         │                 │                 │                   │
+├─────────┴─────────────────┴─────────────────┴──────────────────┤
+│                    Game Loop Manager                             │
+│   ┌────────────────────────────────────────────────────┐        │
+│   │  requestAnimationFrame → Update → Render → Loop   │        │
+│   └────────────────────────────────────────────────────┘        │
+├─────────────────────────────────────────────────────────────────┤
+│                        State Machine                             │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
+│  │  Menu    │→ │  Game    │→ │  Pause   │→ │GameOver  │        │
+│  │ State    │  │ State    │  │ State    │  │ State    │        │
+│  └──────────┘  └──────────┘  └──────────┘  └──────────┘        │
+├─────────────────────────────────────────────────────────────────┤
+│                    Game Logic Layer                              │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
+│  │ Entity Mgr   │  │ Physics/     │  │ Collision    │          │
+│  │ (ball,       │  │ Movement     │  │ Detection    │          │
+│  │  paddles)    │  │ Update       │  │              │          │
+│  └──────────────┘  └──────────────┘  └──────────────┘          │
+│  ┌──────────────┐  ┌──────────────┐                             │
+│  │ Particle     │  │ Power-up     │                             │
+│  │ System       │  │ Logic        │                             │
+│  └──────────────┘  └──────────────┘                             │
+├─────────────────────────────────────────────────────────────────┤
+│                      Input Layer                                 │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
+│  │ Keyboard     │  │ Input State  │  │ Command      │          │
+│  │ Events       │  │ Manager      │  │ Queue        │          │
+│  └──────────────┘  └──────────────┘  └──────────────┘          │
+└────────────────────────────────────────────────────────────────┘
+```
+
+### Component Responsibilities
+
+| Component | Responsibility | Typical Implementation |
+|-----------|----------------|------------------------|
+| **Game Loop Manager** | Orchestrates frame timing, calls update/render in sequence, manages requestAnimationFrame | Single `gameLoop()` function that runs at ~60fps |
+| **State Machine** | Transitions between menu, playing, paused, game over states; isolates logic per scene | Object with `onEnter()`, `update()`, `render()`, `onExit()` methods per state |
+| **Input Manager** | Captures keyboard events, debounces, maintains current key state | Listens to keydown/keyup, maintains a `keysPressed` object |
+| **Entity Manager** | Owns and updates all game objects (paddles, ball, power-ups) | Array of entities with position, velocity, update/render methods |
+| **Physics/Movement** | Updates entity positions based on velocity, applies gravity if needed | `velocity.x`, `velocity.y` updated per frame, position += velocity |
+| **Collision Detection** | Detects overlaps between entities, triggers responses | AABB (Axis-Aligned Bounding Box) for rectangles; circle distance for round objects |
+| **Particle System** | Manages short-lived visual effects (impacts, explosions, trails) | Maintains particle array, updates lifetime/position, removes expired particles |
+| **Power-up System** | Spawns power-ups, detects collection, applies effects | Object with spawn logic, duration tracking, effect callbacks |
+| **Audio Manager** | Plays sound effects and music with pooling to avoid cutoff | Array of audio elements for each sound, round-robin playback |
+| **Renderer** | Draws all entities to canvas | Canvas 2D context calls in specific order (background, entities, UI) |
+
+## Recommended Project Structure
+
+For a vanilla JavaScript HTML5 Canvas game (no build tools), structure as a single HTML file or minimal multi-file approach:
+
+```
+index.html                  # Single entry point (if single-file)
+  ├── <canvas>
+  └── <script src="game.js">
+
+OR multi-file (if modular):
+
+game/
+├── index.html              # Canvas element + script loading
+├── game.js                 # Main game loop and orchestration
+├── states/
+│   ├── MenuState.js        # Title screen, mode selection
+│   ├── GameState.js        # Active gameplay
+│   ├── PauseState.js       # Pause overlay
+│   └── GameOverState.js    # End screen
+├── entities/
+│   ├── Ball.js             # Ball entity (position, velocity, radius)
+│   ├── Paddle.js           # Paddle entity (position, score, AI logic)
+│   ├── PowerUp.js          # Power-up entity
+│   └── EntityManager.js    # Holds and updates all entities
+├── systems/
+│   ├── InputManager.js     # Keyboard input handling
+│   ├── PhysicsSystem.js    # Movement and velocity updates
+│   ├── CollisionSystem.js  # Collision detection and response
+│   ├── ParticleSystem.js   # Particle management
+│   └── AudioManager.js     # Sound effects and music
+└── utils/
+    ├── constants.js        # Game settings (canvas size, speeds)
+    └── helpers.js          # Utility functions
+```
+
+### Structure Rationale
+
+- **Single file vs. modular:** For a small game like Pong, a single HTML file works well for shareability. Use modular structure if the game grows (multiple levels, complex mechanics).
+- **States folder:** Each game scene (menu, gameplay, pause) is isolated, making it easy to change scene logic without affecting others.
+- **Entities folder:** Separates "what things exist" from "how the game works," making entity behavior updates straightforward.
+- **Systems folder:** Core game mechanics (input, physics, collision, audio) are independent modules that don't need to know about each other.
+- **Utils folder:** Shared constants and helpers keep the code DRY without creating unnecessary abstractions.
+
+## Architectural Patterns
+
+### Pattern 1: Game Loop (requestAnimationFrame + Update/Render Separation)
+
+**What:** The core loop calls `update()` to change game state, then `render()` to draw the result. Uses `requestAnimationFrame` to stay in sync with the browser's refresh cycle.
+
+**When to use:** Every HTML5 Canvas game needs this. It's the heartbeat of the application.
+
+**Trade-offs:**
+- **Pro:** Prevents visual glitches (draw happens after all logic updates)
+- **Pro:** Matches browser refresh rate (~60fps) automatically
+- **Pro:** Better battery life on mobile than raw setInterval
+- **Con:** Slightly more complex than a naive loop
+- **Con:** Frame rate is tied to display refresh (usually not an issue)
+
+**Example:**
+```javascript
+function gameLoop(timestamp) {
+  // Calculate delta time for frame-rate independent movement
+  const deltaTime = (timestamp - lastTimestamp) / 1000;
+  lastTimestamp = timestamp;
+
+  // Update all game logic
+  currentState.update(deltaTime);
+
+  // Clear and redraw
+  ctx.clearRect(0, 0, canvas.width, canvas.height);
+  currentState.render(ctx);
+
+  // Continue loop
+  requestAnimationFrame(gameLoop);
+}
+
+requestAnimationFrame(gameLoop);
+```
+
+### Pattern 2: State Machine (Menu → Playing → Paused → GameOver)
+
+**What:** The game has distinct scenes (states). Only one is active at a time. Each state has `onEnter()`, `update()`, `render()`, and `onExit()` hooks.
+
+**When to use:** Any game with multiple screens (menu, gameplay, pause, game over).
+
+**Trade-offs:**
+- **Pro:** Clear separation of concerns — menu logic doesn't leak into gameplay
+- **Pro:** Easy to add new states without rewriting existing ones
+- **Pro:** Makes pause/resume trivial (just swap states)
+- **Con:** Requires discipline to avoid state-to-state coupling
+- **Con:** Small games might feel over-engineered with this pattern
+
+**Example:**
+```javascript
+class GameState {
+  onEnter() {
+    // Initialize game (reset ball, paddles, score)
+  }
+
+  update(deltaTime) {
+    // Update paddles, ball, check collisions, update score
+    inputManager.poll();
+    entityManager.updateAll(deltaTime);
+    collisionSystem.check(entityManager.entities);
+  }
+
+  render(ctx) {
+    // Draw paddles, ball, particles, score
+    ctx.fillStyle = '#000';
+    ctx.fillRect(0, 0, canvas.width, canvas.height);
+    entityManager.renderAll(ctx);
+    particleSystem.render(ctx);
+  }
+
+  onExit() {
+    // Cleanup if needed
+  }
+}
+
+class StateMachine {
+  currentState = new MenuState();
+
+  update(deltaTime) {
+    this.currentState.update(deltaTime);
+    // Check for state transitions
+    if (someCondition) {
+      this.currentState.onExit();
+      this.currentState = new GameState();
+      this.currentState.onEnter();
+    }
+  }
+
+  render(ctx) {
+    this.currentState.render(ctx);
+  }
+}
+```
+
+### Pattern 3: Entity System (Ball, Paddles, Power-ups as Objects)
+
+**What:** All dynamic game objects (ball, paddles, power-ups) inherit from a base `Entity` class or implement a common interface. Entities have position, velocity, and `update()`/`render()` methods.
+
+**When to use:** When you have multiple types of objects that behave similarly (moveable, renderable).
+
+**Trade-offs:**
+- **Pro:** Adding new entity types (new power-up, new obstacle) is just another class
+- **Pro:** All entities update/render the same way in the loop
+- **Pro:** Easy to track all game objects in one collection
+- **Con:** Overkill for very simple games with only 3 objects
+- **Con:** Inheritance hierarchies can get messy if not carefully designed
+
+**Example:**
+```javascript
+class Entity {
+  constructor(x, y, width, height) {
+    this.x = x;
+    this.y = y;
+    this.width = width;
+    this.height = height;
+    this.velocity = { x: 0, y: 0 };
+    this.active = true;
+  }
+
+  update(deltaTime) {
+    this.x += this.velocity.x * deltaTime;
+    this.y += this.velocity.y * deltaTime;
+  }
+
+  render(ctx) {
+    // Override in subclass
+  }
+}
+
+class Ball extends Entity {
+  constructor(x, y, radius) {
+    super(x, y, radius * 2, radius * 2);
+    this.radius = radius;
+    this.velocity = { x: 300, y: 300 }; // pixels per second
+  }
+
+  render(ctx) {
+    ctx.fillStyle = '#fff';
+    ctx.beginPath();
+    ctx.arc(this.x, this.y, this.radius, 0, Math.PI * 2);
+    ctx.fill();
+  }
+}
+
+class Paddle extends Entity {
+  constructor(x, y, width, height) {
+    super(x, y, width, height);
+    this.score = 0;
+  }
+
+  render(ctx) {
+    ctx.fillStyle = '#fff';
+    ctx.fillRect(this.x, this.y, this.width, this.height);
+  }
+}
+
+const entities = [];
+entities.push(new Ball(canvasWidth / 2, canvasHeight / 2, 5));
+entities.push(new Paddle(10, canvasHeight / 2 - 40, 10, 80));
+entities.push(new Paddle(canvasWidth - 20, canvasHeight / 2 - 40, 10, 80));
+
+// In game loop:
+entities.forEach(e => e.update(deltaTime));
+entities.forEach(e => e.render(ctx));
+```
+
+### Pattern 4: Collision Detection (AABB Bounding Box for Rectangles)
+
+**What:** Check if two axis-aligned rectangles overlap using four boundary conditions. For the ball (circle), check distance between centers against sum of radii.
+
+**When to use:** Every frame to detect ball-paddle hits, ball-boundaries, paddle-obstacles.
+
+**Trade-offs:**
+- **Pro:** Fast and simple for rectangular objects
+- **Pro:** Good enough for arcade games (player won't notice slight imprecision)
+- **Con:** Not pixel-perfect — ball can clip through corners
+- **Con:** Doesn't handle rotating objects well
+
+**Example:**
+```javascript
+// Rectangle-Rectangle collision (paddle-to-paddle boundaries)
+function checkAABB(rectA, rectB) {
+  return (
+    rectA.x < rectB.x + rectB.width &&
+    rectA.x + rectA.width > rectB.x &&
+    rectA.y < rectB.y + rectB.height &&
+    rectA.y + rectA.height > rectB.y
+  );
+}
+
+// Circle-Rectangle collision (ball-to-paddle)
+function checkCircleRect(circle, rect) {
+  const closestX = Math.max(rect.x, Math.min(circle.x, rect.x + rect.width));
+  const closestY = Math.max(rect.y, Math.min(circle.y, rect.y + rect.height));
+
+  const distanceX = circle.x - closestX;
+  const distanceY = circle.y - closestY;
+
+  return (distanceX * distanceX + distanceY * distanceY) < (circle.radius * circle.radius);
+}
+
+// In collision system:
+collisionSystem.check = function(entities) {
+  const ball = entities.find(e => e instanceof Ball);
+  const paddles = entities.filter(e => e instanceof Paddle);
+
+  paddles.forEach(paddle => {
+    if (checkCircleRect(ball, paddle)) {
+      ball.velocity.x = -ball.velocity.x; // Bounce
+      ball.x = ball.velocity.x > 0 ? paddle.x + paddle.width : paddle.x - ball.radius;
+    }
+  });
+};
+```
+
+### Pattern 5: Particle System (Short-Lived Visual Effects)
+
+**What:** Maintains an array of particles (small objects with position, velocity, lifetime). Each frame, particles move, fade out, and are removed when dead.
+
+**When to use:** Impact effects, trail effects, explosions — anything visual that lasts a few frames.
+
+**Trade-offs:**
+- **Pro:** Creates visual juice and feedback
+- **Pro:** Performant (particles are simple, deleted quickly)
+- **Con:** Particles can accumulate if not carefully pruned
+- **Con:** Requires tuning (count, lifetime, velocity) for good feel
+
+**Example:**
+```javascript
+class Particle {
+  constructor(x, y, vx, vy, lifetime) {
+    this.x = x;
+    this.y = y;
+    this.vx = vx;
+    this.vy = vy;
+    this.lifetime = lifetime;
+    this.maxLifetime = lifetime;
+  }
+
+  update(deltaTime) {
+    this.x += this.vx * deltaTime;
+    this.y += this.vy * deltaTime;
+    this.lifetime -= deltaTime;
+  }
+
+  render(ctx) {
+    const alpha = this.lifetime / this.maxLifetime;
+    ctx.globalAlpha = alpha;
+    ctx.fillStyle = '#fff';
+    ctx.fillRect(this.x, this.y, 2, 2);
+    ctx.globalAlpha = 1;
+  }
+
+  isAlive() {
+    return this.lifetime > 0;
+  }
+}
+
+class ParticleSystem {
+  particles = [];
+
+  burst(x, y, count = 10) {
+    for (let i = 0; i < count; i++) {
+      const angle = (Math.PI * 2 * i) / count;
+      const vx = Math.cos(angle) * 200;
+      const vy = Math.sin(angle) * 200;
+      this.particles.push(new Particle(x, y, vx, vy, 0.5));
+    }
+  }
+
+  update(deltaTime) {
+    this.particles.forEach(p => p.update(deltaTime));
+    this.particles = this.particles.filter(p => p.isAlive());
+  }
+
+  render(ctx) {
+    this.particles.forEach(p => p.render(ctx));
+  }
+}
+
+// In game loop, on ball-paddle collision:
+particleSystem.burst(ball.x, ball.y, 8);
+```
+
+### Pattern 6: Audio Manager with Sound Pooling
+
+**What:** Maintain a pool of Audio objects for each sound effect. Cycle through them to avoid cutting off sounds when playing rapid-fire effects.
+
+**When to use:** When you need to play the same sound multiple times in quick succession (paddle hits, power-up pickups).
+
+**Trade-offs:**
+- **Pro:** Sounds don't cut each other off
+- **Pro:** No lag from creating new Audio objects
+- **Con:** Requires pre-loading and managing multiple copies of each sound
+- **Con:** Web Audio API is more complex but more powerful
+
+**Example:**
+```javascript
+class AudioManager {
+  sounds = {};
+
+  registerSound(name, filename, poolSize = 3) {
+    this.sounds[name] = [];
+    for (let i = 0; i < poolSize; i++) {
+      const audio = new Audio(filename);
+      audio.poolName = name;
+      audio.ready = false;
+      audio.addEventListener('canplaythrough', () => {
+        audio.ready = true;
+      });
+      this.sounds[name].push(audio);
+    }
+  }
+
+  play(name, volume = 1.0) {
+    const pool = this.sounds[name];
+    if (!pool) {
+      console.warn(`Sound "${name}" not registered`);
+      return;
+    }
+
+    // Find next available sound in pool
+    for (let audio of pool) {
+      if (audio.paused) {
+        audio.currentTime = 0;
+        audio.volume = volume;
+        audio.play().catch(() => {
+          // Browser autoplay policy blocks it — ok to ignore
+        });
+        return;
+      }
+    }
+  }
+}
+
+// Usage:
+const audioManager = new AudioManager();
+audioManager.registerSound('paddle-hit', 'sounds/paddle.wav', 4);
+audioManager.registerSound('score', 'sounds/score.wav', 1);
+
+// In collision system:
+audioManager.play('paddle-hit', 0.7);
+```
+
+## Data Flow
+
+### Game Loop Flow
+
+```
+Frame Start
+    ↓
+Input Manager (poll keyboard)
+    ↓
+Current State.update(deltaTime)
+    │
+    ├→ Entity Manager.update() [move ball, paddles]
+    │
+    ├→ Collision System.check() [detect hits, trigger events]
+    │
+    ├→ Particle System.update() [age and remove particles]
+    │
+    └→ Audio Manager [enqueue sounds from events]
+    ↓
+Canvas.clearRect() [blank the canvas]
+    ↓
+Current State.render(ctx)
+    │
+    ├→ Background [draw arena]
+    │
+    ├→ Entity Manager.render() [draw paddles, ball]
+    │
+    ├→ Particle System.render() [draw particle effects]
+    │
+    └→ UI Layer [draw score, instructions]
+    ↓
+Request next frame
+```
+
+### State Transition Flow
+
+```
+Current State (e.g., MenuState)
+    ↓
+Check for exit conditions
+    ↓
+Call currentState.onExit()
+    ↓
+Create new state (e.g., GameState)
+    ↓
+Call newState.onEnter()
+    ↓
+Update state reference
+    ↓
+Next frame uses new state
+```
+
+### Collision Response Flow
+
+```
+Collision Detected (e.g., Ball ↔ Paddle)
+    ↓
+Update velocity [bounce ball]
+    ↓
+Trigger event [emit "paddle-hit"]
+    ↓
+Particle System.burst() [visual feedback]
+    ↓
+Audio Manager.play() [sound feedback]
+    ↓
+Power-up System [check if power-up triggered]
+```
+
+## Build Order (Recommended Implementation Sequence)
+
+The following order minimizes integration complexity and ensures each phase is testable:
+
+### Phase 1: Game Loop + Single State
+1. Create canvas, get context
+2. Implement `requestAnimationFrame` loop
+3. Implement first state (GameState with basic ball + one paddle)
+4. Test: Ball moves, paddle can be manually updated
+
+**Deliverable:** Ball bounces off canvas edges, stationary paddle on screen
+
+### Phase 2: Input + Movement
+1. Implement InputManager (keyboard event listeners)
+2. Wire input to paddle 1 movement
+3. Test: Paddle responds to keys
+
+**Deliverable:** Player can move left paddle up/down
+
+### Phase 3: Collision + Physics
+1. Implement Collision System
+2. Ball bounces off paddles and walls
+3. Ball-paddle collision response (velocity reversal)
+
+**Deliverable:** Ball bounces realistically off paddles and boundaries
+
+### Phase 4: Second Paddle + Score
+1. Add paddle 2 (AI or second player)
+2. Implement score tracking (ball off-screen = point)
+3. Reset ball position on score
+
+**Deliverable:** Game tracks score, one paddle controlled, one paddle AI or manual
+
+### Phase 5: State Machine + Menu
+1. Implement StateMachine and multiple states (Menu, Game, GameOver)
+2. Add MenuState (start game, select mode)
+3. Add GameOverState (show winner, restart)
+4. Wire transitions
+
+**Deliverable:** Full menu flow — start, play, game over, restart
+
+### Phase 6: Audio
+1. Implement AudioManager with sound pooling
+2. Add sound effects for paddle hits, scoring, menu clicks
+3. Add background music to GameState
+
+**Deliverable:** Game has audio feedback
+
+### Phase 7: Particle System + Polish
+1. Implement ParticleSystem
+2. Emit particles on collisions, scoring
+3. Glow effects, trails (via particles)
+
+**Deliverable:** Visually polished — particles on impact, trails on ball
+
+### Phase 8: Power-ups
+1. Implement PowerUpSystem
+2. Power-up types: speed boost, paddle enlargement, ball split
+3. Spawn logic, collision detection, effect application
+
+**Deliverable:** Power-ups spawn randomly, apply effects
+
+### Phase 9: Multiple Arenas
+1. Add arena config (layout, obstacles, hazards)
+2. Arena selection in menu
+3. Level progression on wins
+
+**Deliverable:** Multiple distinct arena layouts playable
+
+### Phase 10: Polish + Refinement
+1. Tune difficulty curves (AI, ball speeds)
+2. Screen shake on impacts
+3. Pause state and pause key
+4. Settings menu (volume, difficulty)
+
+**Deliverable:** Game feels complete and juicy
+
+## Scaling Considerations
+
+For an HTML5 Canvas Pong game, "scaling" is less about handling millions of users and more about complexity growth.
+
+| Scale | Architecture Adjustments |
+|-------|--------------------------|
+| **Current (2-4 entities)** | Single state, simple collision checks, particle count < 100. No optimization needed. |
+| **Medium (10+ entities, complex arenas)** | Spatial partitioning for collision detection (divide canvas into grid cells, only check nearby entities). Consider renderer caching (re-use canvas for static backgrounds). |
+| **Large (many power-ups, obstacles, hazards)** | Separate rendering layer for UI (use DOM instead of canvas for menus/HUD). Consider offscreen canvas rendering for frequently-drawn elements. Profile particle system (may need pooling limits). |
+
+**In practice:** For a Pong game, the "medium" complexity level is the realistic ceiling. Even with 50 particles and dozens of power-ups, a single-threaded JS game will run fine at 60fps.
+
+## Anti-Patterns
+
+### Anti-Pattern 1: All Game Logic in the Render Function
+
+**What people do:**
+```javascript
+function draw() {
+  ctx.clearRect(0, 0, canvas.width, canvas.height);
+  // Move entities
+  ball.x += ball.vx;
+  ball.y += ball.vy;
+  // Check collisions
+  if (ball.x < 0) ball.vx = -ball.vx;
+  // Update score
+  if (ball.x < 0) score++;
+  // Draw
+  ctx.fillRect(ball.x, ball.y, 10, 10);
+}
+```
+
+**Why it's wrong:**
+- Mixing logic and rendering makes the frame rate dependent on rendering performance
+- Hard to test (can't verify logic without drawing)
+- Debugging is confusing (is the bug in movement or rendering?)
+- Impossible to pause (pause the render, logic stops too)
+
+**Do this instead:** Separate `update()` and `render()` phases.
+
+```javascript
+function gameLoop() {
+  update(deltaTime); // All logic changes state
+  render();          // Render displays state
+  requestAnimationFrame(gameLoop);
+}
+```
+
+### Anti-Pattern 2: No Input Debouncing / Polling Every Event
+
+**What people do:**
+```javascript
+document.addEventListener('keydown', (e) => {
+  if (e.key === 'w') paddle.y -= 10; // Move immediately on keydown
+  if (e.key === 's') paddle.y += 10;
+});
+```
+
+**Why it's wrong:**
+- Movement tied to event firing (non-deterministic)
+- Key repeat lag can cause jerky movement
+- Can't handle two keys pressed simultaneously
+- Frame rate dependency (holding key moves differently on 60fps vs 120fps)
+
+**Do this instead:** Track key state in `update()`.
+
+```javascript
+const keysPressed = {};
+
+document.addEventListener('keydown', (e) => {
+  keysPressed[e.key] = true;
+});
+
+document.addEventListener('keyup', (e) => {
+  keysPressed[e.key] = false;
+});
+
+function update(deltaTime) {
+  if (keysPressed['w']) paddle.y -= paddle.speed * deltaTime;
+  if (keysPressed['s']) paddle.y += paddle.speed * deltaTime;
+}
+```
+
+### Anti-Pattern 3: Collision Response Couples Ball and Paddle
+
+**What people do:**
+```javascript
+class Ball {
+  checkCollision(paddle) {
+    if (this.overlaps(paddle)) {
+      paddle.score++; // Ball knows about paddle state
+      this.velocity.x = -this.velocity.x;
+      this.y = this.y < paddle.y ? paddle.y - this.radius : paddle.y + paddle.height;
+    }
+  }
+}
+```
+
+**Why it's wrong:**
+- Ball is tightly coupled to Paddle (hard to add obstacles, other bounceable objects)
+- Score logic is buried in physics code
+- Hard to test ball movement independently
+
+**Do this instead:** Separate collision detection from response.
+
+```javascript
+function handleCollision(ball, paddle) {
+  ball.velocity.x = -ball.velocity.x;
+  ball.x = ball.velocity.x > 0 ? paddle.x + paddle.width : paddle.x - ball.radius;
+
+  // Event-driven responses
+  emitEvent('collision', { object: 'ball-paddle', paddle });
+}
+
+// Listeners respond to event:
+on('collision', (event) => {
+  if (event.object === 'ball-paddle') {
+    audioManager.play('paddle-hit');
+    particleSystem.burst(ball.x, ball.y);
+  }
+});
+```
+
+### Anti-Pattern 4: Drawing Every Frame Without Clearing
+
+**What people do:**
+```javascript
+function draw() {
+  // ctx.clearRect(...) is commented out to create "trails"
+  ctx.fillStyle = '#fff';
+  ctx.fillRect(ball.x, ball.y, 10, 10);
+}
+```
+
+**Why it's wrong:**
+- Performance degrades over time (entire canvas accumulates garbage)
+- Can't pause or reset without flickering
+- Artifact buildup makes the scene look muddy
+
+**Do this instead:** Clear intentionally, use particles for trails.
+
+```javascript
+function draw() {
+  ctx.clearRect(0, 0, canvas.width, canvas.height);
+
+  // Draw arena
+  ctx.fillStyle = '#222';
+  ctx.fillRect(0, 0, canvas.width, canvas.height);
+
+  // Draw entities
+  entities.forEach(e => e.render(ctx));
+
+  // Particles create visual trails naturally
+  particleSystem.render(ctx);
+}
+```
+
+## Integration Points
+
+### Internal Boundaries
+
+| Boundary | Communication | Notes |
+|----------|---------------|-------|
+| **Collision System ↔ Event System** | Events (e.g., "ball-paddle-hit") | Decouples physics from reactions (audio, particles, score) |
+| **State ↔ State Machine** | State transitions, hooks | Each state is independent; only state machine knows how to switch |
+| **Input Manager ↔ Current State** | Polled each frame (keysPressed object) | State reads keys; input manager doesn't know about game logic |
+| **Entity Manager ↔ Collision System** | Entity list passed to collision check | Collision system reads entity data; doesn't modify entities directly |
+| **Audio Manager ↔ Collision/Scoring** | Direct play() calls from event handlers | Audio is triggered by events, not tightly coupled |
+| **Particle System ↔ Collision Events** | Direct burst() calls from event handlers | Particles are visual feedback, triggered by events |
+
+### External Services (if any)
+
+| Service | Integration Pattern | Notes |
+|---------|---------------------|-------|
+| **Sound Files** | Loaded via `new Audio(filename)` at init | Pre-load and cache; handle browser autoplay policy |
+| **Image Assets** | `new Image()` for sprites if used | Load before game state starts |
+
+## Sources
+
+- [The Complete Guide to Building HTML5 Games with Canvas and SVG - SitePoint](https://www.sitepoint.com/the-complete-guide-to-building-html5-games-with-canvas-and-svg/)
+- [Best JavaScript and HTML5 game engines (updated for 2025) - LogRocket Blog](https://blog.logrocket.com/best-javascript-html5-game-engines-2025/)
+- [Game Loop in HTML5 Canvas - Bryan Lew](https://blewjy.github.io/gamedev/html5/canvas/gameloop/javascript/2020/02/21/game-dev-html5-canvas-game-loop.html)
+- [Creating a State Stack Engine for your game with JavaScript - idiallo.com](https://idiallo.com/blog/javascript-game-state-stack-engine)
+- [Game State Management Patterns - Jake Gordon](https://jakesgordon.com/writing/javascript-game-foundations-state-management/)
+- [Create a Proper Game Loop - Spicy Yoghurt](https://spicyyoghurt.com/tutorials/html5-javascript-game-development/create-a-proper-game-loop-with-requestanimationframe)
+- [Collision Detection - MDN](https://developer.mozilla.org/en-US/docs/Games/Tutorials/2D_Breakout_game_pure_JavaScript/Collision_detection)
+- [Collision Detection and Physics - Spicy Yoghurt](https://spicyyoghurt.com/tutorials/html5-javascript-game-development/collision-detection-physics)
+- [GitHub: html5-pong Vanilla JavaScript Implementation](https://github.com/SMenigat/html5-pong)
+- [Dev.to: Create Ping Pong Game Using JavaScript](https://dev.to/cwrcode/create-ping-pong-game-using-javascript-source-code-2d43)
+
+---
+*Architecture research for: HTML5 Canvas arcade games (Pong-like)*
+*Researched: 2026-03-10*
diff --git a/.planning/research/FEATURES.md b/.planning/research/FEATURES.md
new file mode 100644
index 0000000..3644b16
--- /dev/null
+++ b/.planning/research/FEATURES.md
@@ -0,0 +1,246 @@
+# Feature Research
+
+**Domain:** HTML5 Arcade Pong Game
+**Researched:** 2026-03-10
+**Confidence:** HIGH
+
+## Feature Landscape
+
+### Table Stakes (Users Expect These)
+
+Features users assume exist. Missing these = product feels incomplete.
+
+| Feature | Why Expected | Complexity | Notes |
+|---------|--------------|------------|-------|
+| Basic Pong gameplay (ball + 2 paddles) | Core game loop—players can't engage without it | LOW | Ball physics, collision detection, paddle movement |
+| Single-player vs AI | Standard for arcade games; gives solo players something to do | MEDIUM | AI needs configurable difficulty to feel fair |
+| 2-player local multiplayer | Arcade tradition; keyboard-first implementation, same machine | LOW | Straightforward split-input handling |
+| Game screens (title, mode select, game over) | Professional game expectation; unpolished without them | MEDIUM | Navigation between screens, state management |
+| Settings menu | Expected in any "finished" game; customization signals quality | MEDIUM | Difficulty level, color scheme, sound toggle |
+| Score tracking & display | Players need feedback on performance; missing = feels broken | LOW | HUD element, persisted in-game via canvas |
+| Pause functionality | User expectation for any interactive app | LOW | Toggle game loop, overlay pause screen |
+| Win conditions (first to X points/match structure) | Without clear goals, game feels aimless | LOW | Score tracking, match rounds, restart logic |
+| Responsive controls (smooth paddle movement) | Core feel—sluggish controls = game feels bad | MEDIUM | Keyboard input, velocity-based movement |
+| Visual feedback on collision (ball impact visual) | Players expect immediate action-response connection | LOW | Flash, particle pop, or glow on hit |
+
+### Differentiators (Competitive Advantage)
+
+Features that set the product apart. Not required, but valuable.
+
+| Feature | Value Proposition | Complexity | Notes |
+|---------|-------------------|------------|-------|
+| Particle effects on ball impact | Creates "juice"—game feels modern and satisfying vs flat | MEDIUM | Burst of 5-10 particles, fade over ~0.2s |
+| Glow/aura effects on paddles/ball | Neon/arcade aesthetic; makes visuals pop off screen | MEDIUM | Canvas shadow glow, can be toggled via settings |
+| Screen shake on scoring/power-up | Physical feedback without controller; adds impact | LOW | Offset canvas camera 2-5px for 100-200ms |
+| Ball trail/motion blur effect | Tracks ball movement, improves visual clarity at speed | MEDIUM | Canvas line drawing from previous positions |
+| Power-ups during play (multi-ball, slow time, enlarged paddle) | Adds strategic depth, breaks up gameplay rhythm, keeps matches fresh | HIGH | Spawn logic, collision detection, timer management |
+| Multiple arenas/stages (different visual themes or layouts) | Extends play value; visual freshness; progression feel | MEDIUM | Stage obstacles, different visual tiling/colors |
+| Difficulty progression (ball speeds up as match progresses) | Makes game escalate tension; comebacks feel earned | LOW | Velocity scaling with score or time |
+| Sound effects (paddle hit, wall hit, score, power-up) | Polished audio feedback; arcade authenticity | MEDIUM | Web Audio API or HTML5 audio elements, 4-6 SFX |
+| Background music/ambience | Sets mood; modern games expected to have it | MEDIUM | Looping track, can be muted in settings |
+| Combo/streak counter | Gamification hook; makes chaining successes feel rewarded | LOW | Visual counter, audio/visual feedback on streak |
+| Visual variety (color schemes, neon vs retro vs modern) | Customization drives engagement; feels "yours" | LOW | Canvas color theming, easy CSS/JS swap |
+
+### Anti-Features (Commonly Requested, Often Problematic)
+
+Features that seem good but create problems.
+
+| Feature | Why Requested | Why Problematic | Alternative |
+|---------|---------------|-----------------|-------------|
+| Online multiplayer / leaderboards | "Let players compete globally" sounds appealing | Requires backend, authentication, persistence; exponentially increases complexity; out of scope for v1 | Stick with local multiplayer; defer online until core game ships |
+| Mobile touch controls | "More players via phones" seems like obvious feature expansion | Touch has different physics (no relative movement); screen size ruins UI; controls feel imprecise; derails keyboard focus | Mobile-first is a separate project; keyboard design is cleaner |
+| Persistent progression / accounts | "Save player progress" feels professional | Requires database or localStorage manipulation; cheating risk; adds state management burden | No accounts for v1; each session is independent |
+| Tutorial / onboarding flow | "Help new players understand mechanics" is thoughtful | Arcade games learn-by-doing; tutorial adds complexity; most Pong players understand immediately | Let players figure it out in 30 seconds; simple help text in menu |
+| Ultra-complex power-up economy | "10+ power-up types for replayability" sounds great | Creates balancing nightmare; testing burden explodes; confuses simple game; dilutes impact of each power-up | Start with 3-4 power-ups; quality over quantity |
+| Highly detailed obstacle-heavy arenas | "More level variety through complexity" feels deep | Clutters screen; makes collision detection harder; slows down pacing; feels chaotic vs satisfying | Simple arena variations (walls, center obstacle); minimize visual noise |
+| Procedural/random stage generation | "Infinite replayability" sounds cool | Makes balance impossible; can generate unwinnable/boring states; unfair feel | Handcrafted stages; 3-5 solid arenas beats infinite bad ones |
+| AI learning / adaptation | "AI that gets better as you play" | Feels unfair; players resent opponent learning from them; debugging nightmare | Simple difficulty levels; consistent, beatable AI at each level |
+| Deep customization (paddle size, ball size, court dimensions) | "Let players tinker" signals flexibility | Breaks game balance; creates invalid states; players get lost in options; paralysis | Fixed geometry; color/visual customization only |
+
+## Feature Dependencies
+
+```
+Title Screen
+    └──requires──> Game Mode Select
+                       ├──requires──> Solo Play (AI Opponent)
+                       │                  └──requires──> Game Loop (core Pong)
+                       │                                  ├──requires──> Ball Physics
+                       │                                  ├──requires──> Collision Detection
+                       │                                  └──requires──> AI Difficulty System
+                       │
+                       └──requires──> 2-Player Mode
+                                          └──requires──> Game Loop (same as above)
+
+Game Loop
+    ├──requires──> Score Display
+    ├──requires──> Pause Functionality
+    │
+    ├──enhances──> Visual Feedback (particles, glow, trails)
+    ├──enhances──> Sound Effects
+    │
+    └──enables────> Power-ups
+                       ├──requires──> Power-up Spawn System
+                       └──requires──> Power-up UI (timer display)
+
+Power-ups
+    └──requires──> Game Loop (core physics must handle multi-ball, etc.)
+
+Game Over Screen
+    ├──requires──> Score Tracking
+    └──requires──> Restart / Menu Navigation
+
+Settings Menu
+    ├──enhances──> AI Difficulty (toggle Easy/Medium/Hard)
+    ├──enhances──> Visual Effects (toggle particles, glow, trails)
+    ├──enhances──> Audio (toggle sound effects, music)
+    └──enhances──> Visual Theme (color scheme selection)
+
+Multiple Arenas
+    └──requires──> Arena Selection / Mode Select Screen
+                       └──enhances──> Replayability
+```
+
+### Dependency Notes
+
+- **Game Loop requires Ball Physics and Collision Detection:** Pong is unplayable without these core mechanics.
+- **AI Opponent requires Difficulty System:** Difficulty toggle is critical for fair single-player experience; easy AI vs hard AI makes massive difference in satisfaction.
+- **Visual Feedback enhances Game Loop:** Particles, glow, trails don't break core game but make it feel modern. These are the "juice" that separates polished from flat.
+- **Power-ups enable Strategic Play:** Power-ups require solid core loop first; launching with broken power-up balance is worse than launching without them.
+- **Settings Menu enhances Multiple Features:** Settings unlock customization across difficulty, visuals, and audio without complicating core gameplay.
+- **Multiple Arenas depend on Core Loop:** New arenas need stable physics first; can add in v1.x after core validates.
+
+## MVP Definition
+
+### Launch With (v1)
+
+Minimum viable product — what's needed to validate the concept.
+
+- [x] Basic Pong gameplay (ball, 2 paddles, collision detection) — Players need the core game
+- [x] AI opponent with difficulty levels (Easy/Medium/Hard) — Solo players need something to do
+- [x] 2-player local multiplayer — Keyboard multiplayer is arcade tradition
+- [x] Score display & match structure (first to N points) — Players need goals
+- [x] Title screen, mode select, game over screens — Polished feel matters
+- [x] Pause functionality — Users expect to pause
+- [x] Basic visual feedback (collision flash or glow) — "Juice" starts here
+- [x] Basic sound effects (paddle hit, wall hit, score sound) — Arcade authenticity
+- [x] Settings menu (difficulty, sound toggle, color scheme) — Control signals quality
+
+### Add After Validation (v1.x)
+
+Features to add once core is working and players engage.
+
+- [ ] Particle effects on impact — Players will notice lack of visual polish; easy win for engagement
+- [ ] Ball trails / motion blur — Improves clarity at high speeds; visual feedback upgrade
+- [ ] Power-ups (3-4 types: multi-ball, slow time, enlarged paddle, speed boost) — Adds strategic depth after core gameplay proves solid
+- [ ] 2nd & 3rd arena variations (theme/obstacle changes) — Extends play value once players want variety
+- [ ] Background music loop — Ambience upgrade; audio polish
+- [ ] Screen shake on scoring — Impact feedback; easy add-on
+
+### Future Consideration (v2+)
+
+Features to defer until product-market fit is established.
+
+- [ ] Advanced power-ups (ice ball, split shot, shield) — Risk of over-complicating game feel
+- [ ] Combo/streak counter system — Gamification; depends on user feedback about engagement
+- [ ] Online leaderboards — Requires backend; out of scope for static HTML5 delivery
+- [ ] AI learning / adaptation — Risk of feeling unfair; complexity not justified
+- [ ] Mobile touch controls — Separate design problem; keyboard focus is cleaner
+- [ ] Procedural stage generation — Risk of balance problems; handcrafted is better
+
+## Feature Prioritization Matrix
+
+| Feature | User Value | Implementation Cost | Priority |
+|---------|------------|---------------------|----------|
+| Core Pong gameplay | HIGH | MEDIUM | P1 |
+| AI opponent with difficulty | HIGH | MEDIUM | P1 |
+| 2-player local multiplayer | HIGH | LOW | P1 |
+| Game screens (title, menu, over) | HIGH | MEDIUM | P1 |
+| Score tracking & display | HIGH | LOW | P1 |
+| Pause functionality | MEDIUM | LOW | P1 |
+| Settings menu | MEDIUM | MEDIUM | P1 |
+| Basic visual feedback (glow/flash) | HIGH | LOW | P1 |
+| Basic sound effects | MEDIUM | LOW | P1 |
+| Particle effects on impact | HIGH | MEDIUM | P2 |
+| Ball trail / motion blur | MEDIUM | MEDIUM | P2 |
+| Power-ups (multi-ball, etc.) | HIGH | HIGH | P2 |
+| Multiple arenas | MEDIUM | MEDIUM | P2 |
+| Background music | MEDIUM | MEDIUM | P2 |
+| Screen shake on scoring | MEDIUM | LOW | P2 |
+| Combo counter | LOW | LOW | P3 |
+| Advanced power-up types | MEDIUM | HIGH | P3 |
+| Online multiplayer | LOW | CRITICAL | P3+ |
+| Mobile touch controls | LOW | HIGH | P3+ |
+
+**Priority key:**
+- P1: Must have for launch (v1) — Ship with these
+- P2: Should have, add when possible (v1.x) — Polish pass
+- P3: Nice to have, future consideration (v2+) — Defer or skip
+
+## Arcade Game Design Expectations
+
+Based on industry patterns for arcade-style games, here's what makes a Pong game feel "complete":
+
+### Screen & Menu Flow
+- **Title Screen:** Logo/game name, prominent start button, settings access
+- **Mode Select:** Clear choices (Solo vs 2-Player), easy navigation
+- **Game Screen:** Clean HUD (scores, timer if applicable), minimal UI noise
+- **Pause Screen:** Large "PAUSED" text, resume/settings/menu options, darkened overlay
+- **Game Over Screen:** Final scores, winner announcement, restart/menu navigation
+
+### Game Feel Expectations
+- Controls respond instantly (no input lag)
+- Collision feedback is *immediate* (flash, sound, particle burst)
+- Score changes are celebrated (sound + visual feedback)
+- Difficulty scaling feels fair (AI doesn't feel cheesy at any level)
+- Game is immediately playable (no tutorial; learn by doing)
+
+### Visual Polish Indicators
+- Modern Pong games use neon/glow aesthetic OR clean minimal design (rarely both)
+- Movement has trails or blur at high speeds
+- Impacts register visually, not just mechanically
+- Color scheme is consistent (coherent visual language)
+
+### Audio Expectations
+- Paddle hits have distinct sound from wall hits (Pong classic: octave difference)
+- Point scoring gets celebration audio (different from hit sounds)
+- No audio ever blocks game state changes (no long audio sequences)
+- Music/ambient is subtle; doesn't mask game sounds
+
+## Competitor Feature Analysis
+
+| Feature | Pong Quest (RPG take) | Pixel Pong Pro (arcade) | Pong Worlds (modern) | Super Pong Next Gen (our approach) |
+|---------|----------------------|------------------------|----------------------|----------------------------------|
+| Core Pong gameplay | Yes, wrapped in RPG progression | Yes, arcade-focused | Yes, with obstacles | Yes, with juice |
+| AI difficulty levels | Multiple via level progression | Adjustable difficulty | Yes | Easy/Medium/Hard toggle |
+| 2-player mode | Dungeon co-op | Local vs mode | Yes | Keyboard local only |
+| Power-ups | 50+ silly power-ups | Time-slow mechanic | 5 paddle variants | 3-4 focused power-up types |
+| Visual polish | Retro pixel style | Glitchy effects | Neon/modern | Glow, particles, trails |
+| Sound design | Audio feedback | Arcade beeps | Music + SFX | Classic Pong tones + modern polish |
+| Multiple stages | Themed dungeons | Endless arcade | 5+ worlds | 3-4 arena variations |
+| Persistence | RPG progression tree | Score records | Progression unlocks | Session-based, no persistence |
+| Scope | Medium (RPG wrapper) | Small (arcade focus) | Medium (cosmetics) | Small-Medium (pure arcade juice) |
+
+**Our approach:** Skip RPG bloat, skip endless mode chaos, skip complex cosmetic systems. Instead: solid core Pong + focused polish (particles, glow, trails) + 3-4 well-designed power-ups + 3-4 arena variations. Quality over quantity.
+
+## Sources
+
+- [Basic Pong HTML and JavaScript Game](https://gist.github.com/straker/81b59eecf70da93af396f963596dfdc5)
+- [Top HTML5 games tagged pong - itch.io](https://itch.io/games/html5/tag-pong)
+- [How to Create a Ping Pong Game with HTML, CSS and JavaScript](https://www.codewithfaraz.com/content/124/how-to-create-a-ping-pong-game-with-html-css-and-javascript)
+- [Arcade Game Design Fundamentals](https://gamedesignskills.com/game-design/arcade/)
+- [How Arcade Game Design Still Shapes Interactive Entertainment](https://game-ace.com/blog/arcade-game-design/)
+- [Squeezing more juice out of your game design](https://www.gameanalytics.com/blog/squeezing-more-juice-out-of-your-game-design)
+- [Juice in Game Design: Making Your Games Feel Amazing](https://www.bloodmooninteractive.com/articles/juice.html)
+- [Pong AI and Game Mechanics](https://gamemechanics.fandom.com/wiki/Pong)
+- [Pong Game Using AI](https://www.ijsrp.org/research-paper-0922/ijsrp-p12939.pdf)
+- [Game UI Database - Title Screen](https://www.gameuidatabase.com/index.php?scrn=1)
+- [Game UI Database - Pause Screen](https://www.gameuidatabase.com/index.php?scrn=44)
+- [Breaking Down Breakout: System And Level Design](https://www.gamedeveloper.com/design/breaking-down-breakout-system-and-level-design-for-breakout-style-games)
+- [The Impact Of Sound And Music In Arcade Gaming](https://www.homegamesroom.co.uk/blogs/types-of-arcade-machines-and-their-features/the-impact-of-sound-and-music-in-arcade-gaming)
+- [7 HTML5 Game Design Mistakes to Avoid](https://www.htmlgoodies.com/html5/7-html5-game-design-mistakes-to-avoid/)
+- [The Ultimate Guide to Game Design Anti-patterns](https://www.numberanalytics.com/blog/ultimate-guide-to-game-design-anti-patterns)
+- [Principles Of HTML5 Game Design](https://www.smashingmagazine.com/2015/09/principles-of-html5-game-design/)
+
+---
+*Feature research for: HTML5 Arcade Pong Game*
+*Researched: 2026-03-10*
diff --git a/.planning/research/PITFALLS.md b/.planning/research/PITFALLS.md
new file mode 100644
index 0000000..c9fb2a0
--- /dev/null
+++ b/.planning/research/PITFALLS.md
@@ -0,0 +1,420 @@
+# Domain Pitfalls: HTML5 Canvas Arcade Games
+
+**Domain:** HTML5 Canvas 2D arcade games (Pong-like)
+**Researched:** 2026-03-10
+**Confidence:** HIGH (verified with official docs, multiple sources, and established patterns)
+
+## Critical Pitfalls
+
+### Pitfall 1: Tunneling — Ball Passing Through Paddles at High Speed
+
+**What goes wrong:**
+The ball moves so fast between frames that it jumps from one side of a paddle to the other without ever registering a collision. Players see the ball suddenly teleport through their paddle, breaking game feel and causing frustration. This is especially common when ball velocity increases via power-ups or as AI difficulty scales.
+
+**Why it happens:**
+Discrete collision detection only checks positions at the start and end of each frame. If the ball travels 50+ pixels per frame and the paddle is only 20 pixels wide, the ball can be "before paddle" at frame N-1 and "after paddle" at frame N, with no intersection detected in between.
+
+**How to avoid:**
+1. **Continuous Collision Detection (CCD)**: Sweep a collision shape along the ball's motion path and detect if it intersects the paddle at any point during travel, not just endpoints.
+2. **Smaller time steps**: Subdivide each frame's physics into multiple micro-steps (e.g., 0.016 seconds into 4 × 0.004 second steps). Ball travels less distance per step, reducing tunnel size.
+3. **Swept collision volumes**: Create a rectangle representing all space the ball occupied during the frame and test against paddle AABB (axis-aligned bounding box).
+4. **Ray casting**: Cast a ray from the ball's previous position to current position and check intersection with paddle geometry.
+5. **Clamp ball velocity**: Set a maximum ball speed that you know will be reliably detected with your paddle width and frame time.
+
+**Warning signs:**
+- Ball occasionally disappears through paddles during fast rallies
+- High-difficulty AI generates faster ball speeds, increasing "cheap" losses
+- Power-up that increases ball speed makes paddling feel unreliable
+- Player reports: "I moved the paddle right into it and it went through"
+
+**Phase to address:**
+**Phase 2 (Core Physics)** — Implement collision detection architecture from day one. Tunneling is a show-stopper that's expensive to retrofit. Must be proven working before power-ups or AI velocity scaling is introduced.
+
+---
+
+### Pitfall 2: Game Loop Timing — Frame Rate Dependency and Spiral of Death
+
+**What goes wrong:**
+If you multiply physics by frame time (delta time) but don't cap it, one slow frame causes physics to jump a large distance. That large jump takes longer to simulate, making the next frame slower, requiring even larger physics jumps. The game enters a "spiral of death" — each frame gets slower, simulations get larger, until the browser freezes.
+
+Alternatively, if you ignore delta time and tie movement directly to frame count, the game plays at different speeds on 60fps monitors vs. 120fps monitors, or on slow vs. fast machines. Players on high-refresh displays move twice as fast, breaking competitive play and AI balance.
+
+**Why it happens:**
+Developers either:
+- Use variable delta time without capping it (causes spiral of death)
+- Ignore delta time entirely (assumes 60fps everywhere, unrealistic)
+- Use setInterval instead of requestAnimationFrame (poor browser synchronization, timing jitter)
+
+**How to avoid:**
+1. **Use fixed delta time game loop**: Accumulate elapsed time and step physics in fixed increments (e.g., always step by 0.016s = 1/60 frame). Decouple physics from frame rate.
+2. **Cap delta time**: If a frame takes unexpectedly long, clamp delta time to a maximum (e.g., 0.032s max) to prevent spiral of death. Better to "skip" physics than freeze.
+3. **Use requestAnimationFrame**: Schedule updates with `window.requestAnimationFrame()`, not `setInterval()`. RAF syncs with browser refresh, reducing jitter and input lag.
+4. **Multiply velocities by delta time**: `position += velocity * deltaTime` — ensures same distance traveled regardless of frame rate.
+5. **Test on variable frame rates**: Force slow frames and verify the game doesn't enter spiral of death. Test on 60hz, 120hz, and intentionally laggy machines.
+
+**Warning signs:**
+- Game runs smoothly at 60fps but fast/jerky at 120fps+
+- One stutter causes cascading slowdowns until browser becomes unresponsive
+- AI or ball speed is inconsistent between test runs
+- Player loses while ball moves visibly faster than usual
+- Performance profiler shows frame time growing each frame (spiral signature)
+
+**Phase to address:**
+**Phase 1 (Game Loop)** — This is the foundation. Every other system depends on correct timing. Implement and test fixed-step physics before any game logic.
+
+---
+
+### Pitfall 3: Canvas DPI Scaling — Blurry Graphics on Retina Displays
+
+**What goes wrong:**
+Your game looks sharp on a standard 96 DPI display but appears blurry, pixelated, or soft on Retina/HiDPI screens (2x pixel ratio on modern MacBooks, iPhones, newer Windows displays). Canvas is rendered at 96 DPI by default; HiDPI screens scale it up, causing visual degradation. Players notice immediately and the game feels cheap, even if gameplay is solid.
+
+**Why it happens:**
+HTML5 Canvas has a default DPI of 72-96. When viewed on a 2x density Retina screen, the browser upscales the canvas image (like stretching a PNG), causing blurriness. The CSS size and the internal resolution are decoupled. Most developers set canvas width/height in CSS but don't account for `devicePixelRatio`.
+
+**How to avoid:**
+1. **Query devicePixelRatio**: Read `window.devicePixelRatio` (typically 1 on standard, 2 on Retina, can be 1.5 or 3+ on unusual displays).
+2. **Scale canvas internally**: Set canvas width/height to `(targetWidth * dpr, targetHeight * dpr)`. Set CSS width/height to original size.
+3. **Scale 2D context**: Call `ctx.scale(dpr, dpr)` after creating the context. Now all drawing commands account for the pixel ratio.
+4. **Example**:
+   ```javascript
+   const dpr = window.devicePixelRatio || 1;
+   canvas.width = 800 * dpr;
+   canvas.height = 600 * dpr;
+   canvas.style.width = '800px';
+   canvas.style.height = '600px';
+   ctx.scale(dpr, dpr);
+   ```
+5. **Handle zoom changes**: `devicePixelRatio` can change if the user zooms the page (fractional values like 2.223). Re-apply scaling on window resize and orientation change.
+6. **Test on real Retina hardware** or browser DevTools device emulation (Chrome: toggle device mode, select "iPhone 12" or "MacBook Pro").
+
+**Warning signs:**
+- Game looks sharp on your desktop, but blurry on MacBook or mobile
+- Players report "pixelated graphics" or "soft rendering"
+- Text, particle trails, and thin lines appear fuzzy while gameplay works fine
+- Obvious visual gap compared to native mobile apps
+
+**Phase to address:**
+**Phase 1 (Rendering Setup)** — Implement DPI scaling before drawing anything. It's a one-time setup with massive visual payoff. Cheap to fix early, embarrassing to fix after launch.
+
+---
+
+### Pitfall 4: WebAudio Autoplay Policy — Audio Context Won't Initialize
+
+**What goes wrong:**
+You initialize the Web Audio API on page load to prepare sound effects and music. On Chrome, Firefox, and Safari, the audio context is suspended and audio never plays. The game launches silently, and sound only works after the player clicks somewhere. If you try to play audio before user interaction, nothing happens. In some browsers, audio context creation itself fails.
+
+Modern browsers enforce strict autoplay policies: audio must be preceded by explicit user interaction (click, tap, key press). This was added to prevent auto-playing ads and surprise sounds.
+
+**Why it happens:**
+Developers assume they can initialize audio immediately. They don't know about the autoplay policy. On first load, there's no user gesture, so `AudioContext` is created but immediately suspended. Attempts to play sounds fail silently.
+
+**How to avoid:**
+1. **Create AudioContext on first user interaction**: Wait for the player's first click/tap, then initialize Web Audio. This also saves resources on pages the player never actually plays.
+2. **Call context.resume() after user gesture**:
+   ```javascript
+   document.addEventListener('click', () => {
+     if (audioContext.state === 'suspended') {
+       audioContext.resume();
+     }
+   });
+   ```
+3. **Provide audio enable/disable toggle**: Let players disable sound in settings without breaking the game. Store preference in localStorage.
+4. **Test on Chrome, Firefox, Safari**: Autoplay policies differ subtly. Test cross-browser on real devices.
+5. **Graceful fallback**: If audio doesn't play, the game still works. Don't break core functionality over sound.
+
+**Warning signs:**
+- Game launches silently on first load, audio works after any click
+- Audio context state is "suspended" when logged to console
+- Web Audio graphs show no output or oscillators don't produce sound
+- "DOMException: NotAllowedError" when creating audio context
+- Mobile browsers (iOS Safari) never play audio unless explicitly enabled
+
+**Phase to address:**
+**Phase 4 (Audio & Juiciness)** — Audio is non-critical to core gameplay, but getting it right prevents the silent-game impression. Should be addressed before polish pass, not MVP.
+
+---
+
+### Pitfall 5: AI Difficulty Balance — Unbeatable or Brain-Dead
+
+**What goes wrong:**
+AI opponent is either trivially easy (always misses, moves slowly) making single-player boring, or perfectly inhuman (hits every ball perfectly) making the game unwinnable. There's no middle ground. Players either crush the AI immediately or face an impossible wall, killing replayability.
+
+**Why it happens:**
+Developers often take a shortcut: set AI paddle Y-axis equal to ball Y-axis (perfect tracking). Or they hardcode a fixed reaction speed. No difficulty levels, no margin of error. The AI is deterministic and extreme.
+
+**How to avoid:**
+1. **Add reaction delay**: AI should have a perceptual delay before reacting (e.g., 0.2 seconds). Humans have reaction time; so should the AI.
+2. **Introduce error margin**: AI aims for ball position ± random offset (e.g., ± 10 pixels). Perfect aim is impossible; gives human players a chance.
+3. **Implement multiple difficulty levels**:
+   - **Easy**: Large reaction delay (0.3s+), large error margin (±20 pixels), slower paddle speed
+   - **Medium**: Small delay (0.1s), small error margin (±5 pixels), normal paddle speed
+   - **Hard**: Minimal delay (0.05s), minimal error margin (±2 pixels), slightly faster paddle speed
+4. **Add adaptive learning (optional)**: Track player skill and adjust AI in real-time. But only after proving static difficulties work.
+5. **Give AI imperfect information**: AI shouldn't predict ball trajectory perfectly. Let it track the ball's visible path and occasionally misjudge angle or spin.
+6. **Test at each difficulty**: Play 10 rounds at each level. Easy should feel winnable. Hard should feel challenging but fair. Medium should feel competitive.
+
+**Warning signs:**
+- Single-player against AI feels pointless (too easy or too hard)
+- No difficulty setting, players have no progression path
+- AI hits every ball or misses every ball (no middle ground)
+- Player reports: "I can beat easy mode with my eyes closed" or "Hard is impossible"
+- Difficulty spike between Easy and Hard is too large (missing Medium equivalent)
+
+**Phase to address:**
+**Phase 3 (AI)** — AI difficulty must be tuned before launch. Broken difficulty is worse than no AI. Must include multiple levels and feel fair.
+
+---
+
+### Pitfall 6: Power-Up Balance — Breaks Gameplay or Feels Pointless
+
+**What goes wrong:**
+Power-ups either trivialize the game (ball slows down, paddle doubles in size, player wins instantly) or are too weak to matter (1% speed increase that nobody notices). Some power-ups are clearly better than others, so only one is ever useful. Or power-ups spawn so frequently that the game becomes random chaos instead of skill-based.
+
+**Why it happens:**
+Power-ups are added late as a "juiciness" feature without playtesting. Developers don't balance spawn rates, durations, or effects relative to the base game. Each power-up is tuned in isolation, not against the full suite.
+
+**How to avoid:**
+1. **Define power-up tiers**: Categorize by impact (weak, medium, strong). Each tier should spawn at different rates.
+   - **Weak**: +5% ball speed (noticeable but not game-changing)
+   - **Medium**: Paddle size +30% or ball speed -20% (moderately useful)
+   - **Strong**: Triple ball or freeze opponent paddle (rare, high-impact)
+2. **Tune spawn rates**: Weak power-ups spawn every 15-20 seconds. Medium every 30-40 seconds. Strong every 60+ seconds. Adjust based on playtesting.
+3. **Set sensible durations**: Most power-ups should last 5-10 seconds (enough to feel useful, not permanent). Longer durations make balancing harder.
+4. **Avoid overpowered combinations**: A large paddle + slow ball is almost unbeatable. Test all combinations.
+5. **Make power-ups visible**: Players should know a power-up is active and when it expires (visual indicator, timer bar, color change). Mystery mechanics feel unfair.
+6. **Playtest extensively**: 20+ rounds with varied power-up timing. Does it change strategy or just randomize outcomes? If the latter, recalibrate.
+
+**Warning signs:**
+- One power-up is clearly better; players camp it or ignore others
+- Power-ups spawn too often, removing skill from the game
+- A single power-up is almost unbeatable (ball slow + large paddle)
+- Players don't understand what a power-up does
+- Power-up effect is so subtle it's not noticeable (wasted UI real estate)
+
+**Phase to address:**
+**Phase 4 (Power-Ups & Arenas)** — Power-ups should be added only after base gameplay (physics, AI, collision) is solid. Balancing requires playtesting against a working AI. Can't tune power-ups if the foundation is broken.
+
+---
+
+### Pitfall 7: Input Lag — Paddle Feels Unresponsive
+
+**What goes wrong:**
+Player presses up arrow or W key to move the paddle, but there's a visible delay before the paddle responds. Feels sluggish, uncontrollable. Timing-sensitive games (like Pong) become unplayable because the delay breaks prediction. Players blame the game for feeling bad, even if physics is correct.
+
+**Why it happens:**
+- Using `setInterval()` instead of `requestAnimationFrame()` (not synced to refresh)
+- Keyboard state not polled during game update (only during event handlers)
+- Excessive DOM manipulation between input and rendering
+- Browser input lag (8-13 frames / 130+ ms on some browsers)
+
+**How to avoid:**
+1. **Use requestAnimationFrame**: Schedule updates with `window.requestAnimationFrame()`, not `setInterval()`. RAF syncs with monitor refresh.
+2. **Maintain a key state map**: Track which keys are pressed in a boolean object. Update on keydown/keyup, then read state during game update.
+   ```javascript
+   const keys = {};
+   document.addEventListener('keydown', (e) => keys[e.key] = true);
+   document.addEventListener('keyup', (e) => keys[e.key] = false);
+   // In game loop:
+   if (keys['ArrowUp']) paddleY -= paddleSpeed * deltaTime;
+   ```
+3. **Update paddle position during game update, not event handler**: Never move the paddle directly in the keydown event. That causes de-sync between input and rendering.
+4. **Minimize DOM changes**: Avoid `document.getElementById()` inside the game loop. Pre-cache DOM references.
+5. **Test input latency**: Use a camera at 240fps+ or the built-in browser input latency tester to measure delay. Target <50ms total (including display lag).
+
+**Warning signs:**
+- Paddle movement feels sluggish or delayed
+- Paddle doesn't move immediately after key press
+- Player can't hit fast balls reliably (timing window too tight)
+- Player reports: "The paddle won't respond fast enough"
+- Frame-by-frame video shows visible delay between input and paddle movement
+
+**Phase to address:**
+**Phase 2 (Game Loop)** — Input responsiveness is fundamental. If the player can't control the paddle smoothly, nothing else matters. Must be perfect before AI or power-ups.
+
+---
+
+### Pitfall 8: Memory Leaks from Event Listeners
+
+**What goes wrong:**
+After playing multiple rounds, the game consumes more and more memory. Opening/closing menus, starting/ending matches, or switching game modes accumulates stale event listeners. Eventually, the browser tab becomes slow or crashes. The leak is silent — no error messages, just creeping slowness.
+
+**Why it happens:**
+Event listeners for keyboard input, window resize, or state changes aren't removed when transitioning between game states. Each menu open or game over adds more listeners. The old listeners are never garbage collected because they still reference the old state objects.
+
+**How to avoid:**
+1. **Always remove event listeners on state cleanup**:
+   ```javascript
+   // When transitioning state
+   document.removeEventListener('keydown', handleKeyDown);
+   document.removeEventListener('keyup', handleKeyUp);
+   window.removeEventListener('resize', handleResize);
+   ```
+2. **Use named functions for removeEventListener**: Anonymous functions can't be removed. Use a reference:
+   ```javascript
+   const handleKeyDown = (e) => { /* ... */ };
+   document.addEventListener('keydown', handleKeyDown);
+   // Later:
+   document.removeEventListener('keydown', handleKeyDown);
+   ```
+3. **Use the `once` option for one-time listeners**: `addEventListener('click', handler, { once: true })` auto-removes after firing.
+4. **Centralize listener management**: Keep a registry of all active listeners. When changing game state, remove all listeners for the old state.
+5. **Test for leaks**: Use Chrome DevTools Memory tab to take heap snapshots. Play multiple rounds, switch states, check memory growth. Should be stable, not growing.
+
+**Warning signs:**
+- Memory usage grows 10-50MB per game round
+- After playing for 10+ rounds, noticeable slowdown
+- Chrome DevTools Memory shows detached DOM nodes or listeners piling up
+- Game works fine for 2 rounds, then stutters on round 3
+- Closing and reopening settings menu causes a lag spike
+
+**Phase to address:**
+**Phase 3 (State Management)** — Implement cleanup as part of state transitions. Can't be patched later without refactoring. Establish the pattern early.
+
+---
+
+## Technical Debt Patterns
+
+| Shortcut | Immediate Benefit | Long-term Cost | When Acceptable |
+|----------|-------------------|----------------|-----------------|
+| Skip collision detection architecture, hardcode paddle bounds checks | "Simple" code, faster initial development | Ball tunneling, impossible to add moving obstacles or complex arenas | Never. This breaks the game. |
+| Use variable delta time without capping | "Works" on most machines | Spiral of death on slow frames, unpredictable gameplay | Never. Use fixed timestep. |
+| Render full canvas every frame without optimization | Quick to code | 30fps instead of 60fps, power-ups cause visible stutters | Only if particle count is <50. Profile first. |
+| Don't implement power-up balance, ship with minimal tuning | Launch faster | Power-ups break or trivialize gameplay, kills replayability | Only in MVP. Must be tuned before v1.0. |
+| Ignore DPI scaling, assume standard 96 DPI | Saves setup code | Blurry on Retina displays, players think game is poorly made | Never. 5 minutes of code, massive visual impact. |
+| Don't remove event listeners on state transitions | Fewer lines of code | Memory creeps, lag accumulates, browser crashes on long sessions | Never. Cleanup is non-negotiable. |
+| Create AudioContext on page load (ignore autoplay policy) | Audio "ready" immediately | Silent game on first load, player thinks sound is broken | Never. Respect autoplay policy. |
+
+---
+
+## Integration Gotchas
+
+| Integration | Common Mistake | Correct Approach |
+|-------------|----------------|------------------|
+| **Canvas rendering + requestAnimationFrame** | Use `setInterval()` for game loop instead of RAF. Causes jitter, visual tearing, and poor input feel. | Always use `window.requestAnimationFrame()`. Syncs with monitor refresh, provides timestamp for delta time. |
+| **Keyboard input + Game state** | Listen for keydown/keyup globally without checking game state. Menu and game both respond to same keys, inputs conflict. | Maintain key state map. Only read state in appropriate game phase (not in menu). Clear state on transitions. |
+| **Power-ups + Physics** | Power-up changes ball speed instantly mid-flight. Can cause tunneling if new speed exceeds collision detection limits. | Clamp power-up effects to safe ranges. Test all combinations against max expected velocity. |
+| **Audio + Game state** | Play sounds in keydown event handler. Sounds overlap, button mashing causes audio feedback explosion. | Queue audio events and play during game update, once per frame max. |
+| **Canvas size + Window resize** | Set canvas CSS size but not internal resolution. On window resize, canvas stretches or shrinks, breaking DPI scaling. | Listen to `window.resize`, recalculate canvas width/height accounting for `devicePixelRatio`, re-apply scale. |
+
+---
+
+## Performance Traps
+
+| Trap | Symptoms | Prevention | When It Breaks |
+|------|----------|------------|----------------|
+| **Excessive canvas clears** | Frame rate drops from 60 to 40 fps as particle count grows. clearRect() becomes the bottleneck. | Use dirty rectangles: only clear regions where objects moved, not full canvas. Or use offscreen canvases for static backgrounds. | 500+ particles on screen, or lots of large objects moving fast. |
+| **Unoptimized collision detection** | 60 fps with 2 paddles and 1 ball. 30 fps when adding 3 obstacles. O(n²) collision checks are too slow. | Use broad-phase filtering (grid-based spatial partitioning). Only test nearby objects, not all objects. | 10+ collidable objects. Switch to spatial hashing before launch. |
+| **Physics simulation with large delta time** | One stutter triggers spiral of death: frame takes 50ms, next frame must simulate 50ms of physics, takes 100ms, etc. | Cap delta time to a maximum (e.g., 0.032s). Overflow into multiple micro-steps instead of one large step. | Any slow frame during fixed-timestep simulation. Must cap. |
+| **Global event listeners not cleaned up** | Memory grows 20-30MB per game session. After 10 sessions, browser becomes laggy. | Remove all listeners in state cleanup. Test with DevTools Memory profiler. | Long gaming sessions (>30 min). Problems appear silently. |
+| **Rendering tiny particles with full alpha blending** | Smooth 60 fps with particles at alpha=0.8. Huge lag when alpha=0.1 (transparent), GPU works harder on blending. | Batch particle renders, use WebGL for >1000 particles, or limit transparency to alpha >= 0.3. | Lots of semi-transparent particles. Plasma/explosion effects common culprit. |
+
+---
+
+## UX Pitfalls
+
+| Pitfall | User Impact | Better Approach |
+|---------|-------------|-----------------|
+| **No difficulty setting** | New players get crushed by hard AI or bored by easy AI. No progression path. | Offer Easy, Medium, Hard. Let players choose. Easy should be winnable for non-gamers. |
+| **Power-ups with no clear visual feedback** | Player collects power-up but has no idea what happened. Effect is subtle or non-obvious. "Did something change?" | Use visual indicators: paddle glow when large, trail color change, timer bar, on-screen text ("SLOW MODE"). |
+| **Input lag makes game feel broken** | Player presses key, paddle responds late. Feels uncontrollable. Player blames the game, not their skill. | Ensure <50ms total latency. Test on target hardware. If possible, implement input prediction (show paddle moving before update if expected). |
+| **Silent game on first load** | Player thinks speakers are broken or audio is missing. | Initialize Web Audio on first click, provide audio toggle in settings, test audio on launch. |
+| **Winning feels random due to power-ups** | Player feels skill doesn't matter, only luck. Devalues high-score runs. | Balance power-ups so they enhance skill expression, not replace it. Rare, high-impact power-ups are better than constant minor ones. |
+| **No visual feedback on collisions** | Ball bounces off paddle but feels unresponsive. Paddle hit doesn't feel good. | Add particle burst, paddle glow flash, slight screen shake, or audio tick on hit. "Juice" makes hits feel impactful. |
+
+---
+
+## "Looks Done But Isn't" Checklist
+
+- [ ] **Collision detection:** Often missing CCD or tunneling fixes — verify ball doesn't pass through paddles at max expected speed
+- [ ] **Game loop:** Often using `setInterval()` instead of RAF — verify `requestAnimationFrame()` is used, delta time is capped, physics is deterministic
+- [ ] **Canvas scaling:** Often ignores DPI — verify game looks sharp on Retina displays by testing on real hardware or DevTools emulation
+- [ ] **Audio:** Often doesn't handle autoplay policy — verify audio plays on first click, not silently on load, and context.resume() is called
+- [ ] **AI difficulty:** Often unbeatable or trivial — verify Easy, Medium, Hard all feel fair after 10 test rounds at each level
+- [ ] **Power-up balance:** Often untested with full suite — verify no single power-up is overpowered, spawn rates feel right, visual feedback is clear
+- [ ] **Input responsiveness:** Often laggy due to poor event handling — verify <50ms input latency, test on target hardware, use RAF
+- [ ] **Memory leaks:** Often accumulate silently — verify memory is stable after 10 game sessions, use DevTools Memory profiler
+- [ ] **Multiple game states:** Often reuse listeners across states — verify all listeners are removed on state transitions, no detached DOM nodes linger
+
+---
+
+## Recovery Strategies
+
+| Pitfall | Recovery Cost | Recovery Steps |
+|---------|---------------|----------------|
+| **Tunneling detected after launch** | HIGH | Implement CCD or smaller timesteps. Requires refactoring collision system. 2-3 days of work. |
+| **Spiral of death due to uncapped delta time** | HIGH | Cap delta time and implement fixed timestep. Physics must be re-verified. 1-2 days. |
+| **Game blurry on Retina (discovered late)** | LOW | Add devicePixelRatio scaling. 1 hour. But impacts visual first impression. |
+| **Audio silent on first load** | MEDIUM | Add user gesture detection and context.resume(). Requires event listener refactor. 4-6 hours. |
+| **AI is unbeatable, players quit** | MEDIUM | Implement difficulty levels and tune each. Requires playtesting loop. 2-3 days. |
+| **Power-ups break gameplay** | HIGH | Re-balance spawn rates, durations, effects. Requires extensive playtesting. 2-3 days. |
+| **Input lag makes game unplayable** | MEDIUM | Switch to RAF, implement key state map. May require game loop rewrite. 1-2 days. |
+| **Memory creeping after long sessions** | MEDIUM | Audit all event listeners, implement cleanup. Use DevTools Memory to verify. 4-6 hours. |
+
+---
+
+## Phase-Specific Warnings
+
+| Phase Topic | Likely Pitfall | Mitigation |
+|-------------|---------------|------------|
+| **Phase 1: Game Loop** | Frame rate dependency, delta time not capped, requestAnimationFrame not used | Use fixed timestep with capped delta time from day one. Verify on 60hz and 120hz monitors. |
+| **Phase 1: Rendering** | Canvas DPI not scaled, blurry on Retina | Implement devicePixelRatio scaling. Test on real Retina hardware or browser emulation. |
+| **Phase 2: Physics & Collision** | Tunneling at high speeds, ball passing through paddles | Implement CCD or smaller timesteps. Test with ball speeds up to expected max (with power-up scaling). |
+| **Phase 2: Input** | Input lag, unresponsive paddle controls | Maintain key state map, poll during game update, use RAF. Test input latency <50ms. |
+| **Phase 3: AI** | AI difficulty too easy or too hard, no middle ground | Implement Easy/Medium/Hard with reaction delays and error margins. Playtest each difficulty level. |
+| **Phase 3: State Management** | Memory leaks from event listeners, detached DOM nodes | Implement cleanup on state transitions. Test with DevTools Memory profiler. |
+| **Phase 4: Audio** | Audio context suspended, silent on first load | Implement context.resume() on first user gesture. Test autoplay policy on Chrome, Firefox, Safari. |
+| **Phase 4: Power-Ups** | Overpowered or useless effects, breaks gameplay | Implement difficulty tiers, tune spawn rates, playtest all combinations. Don't ship untested power-ups. |
+| **Phase 4: Polish & Juiciness** | Particle effects cause lag, screen shake is jerky | Profile particle rendering, use offscreen canvases or reduce count if needed. Use RAF for smooth animations. |
+
+---
+
+## Sources
+
+### Official Documentation & Standards
+- [Web APIs: Canvas API — MDN](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API)
+- [Optimizing canvas — MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Optimizing_canvas)
+- [Window: requestAnimationFrame() method — MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestAnimationFrame)
+- [Web Audio, Autoplay Policy and Games — Chrome for Developers](https://developer.chrome.com/blog/web-audio-autoplay)
+- [Autoplay policy in Chrome — Chrome for Developers](https://developer.chrome.com/blog/autoplay)
+- [Window: devicePixelRatio property — MDN Web APIs](https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio)
+- [Autoplay guide for media and Web Audio APIs — MDN Media](https://developer.mozilla.org/en-US/docs/Web/Media/Guides/Autoplay)
+
+### Game Development & Physics
+- [Video Game Physics Tutorial - Part II: Collision Detection for Solid Objects — Toptal](https://www.toptal.com/developers/game/video-game-physics-part-ii-collision-detection-for-solid-objects)
+- [Continuous Collision Detection (Background Information) — DigitalRune Documentation](https://digitalrune.github.io/DigitalRune-Documentation/html/138fc8fe-c536-40e0-af6b-0fb7e8eb9623.htm)
+- [Collision detection — Game development — MDN](https://developer.mozilla.org/en-US/docs/Games/Tutorials/2D_Breakout_game_pure_JavaScript/Collision_detection)
+- [Pong AI Test — Joshua Masters](https://mastersj5.github.io/projects/2_project/)
+- [Pong Extra: Making an Enemy Paddle — Retro Game Deconstruction Zone](https://www.retrogamedeconstructionzone.com/2025/01/pong-extra-making-enemy-paddle.html)
+- [Thinking about pong AI — Lucas Coelho](https://www.lucascoelho.dev/blog/thinking-about-pong-ai)
+
+### Performance & Optimization
+- [Creating a variable delta time javascript game loop — Stephen Dodd Tech](https://stephendoddtech.com/blog/game-design/variable-delta-time-javascript-game-loop)
+- [Creating a fixed delta time javascript game loop — Stephen Dodd Tech](https://stephendoddtech.com/blog/game-design/fixed-delta-time-javascript-game-loop)
+- [A Detailed Explanation of JavaScript Game Loops and Timing — Isaac Sukin](https://isaacsukin.com/news/2015/01/detailed-explanation-javascript-game-loops-and-timing)
+- [Performant Game Loops in JavaScript — Aleksandr Hovhannisyan](https://www.aleksandrhovhannisyan.com/blog/javascript-game-loop/)
+- [Optimising HTML5 Canvas games — Nicola Hibbert](https://nicolahibbert.com/optimising-html5-canvas-games/)
+- [Top Mistakes to Avoid When Developing Games with HTML5 — Superpowers HTML5](https://superpowers-html5.com/top-mistakes-to-avoid-when-developing-games-with-html5)
+- [HTML5 Canvas Performance and Optimization Tips — GitHub Gist](https://gist.github.com/jaredwilli/5469626)
+- [Improving HTML5 Canvas performance — web.dev](https://web.dev/canvas-performance/)
+- [High DPI Canvas — web.dev](https://web.dev/articles/canvas-hidipi)
+- [Ensuring our Canvas Visuals Look Good on Retina/High-DPI Screens — Kirupa](https://www.kirupa.com/canvas/canvas_high_dpi_retina.htm)
+
+### Input & Interactivity
+- [Handling user input in HTML5 Canvas-based games — IBM Developer](https://developer.ibm.com/tutorials/wa-games/)
+- [The effect of web browser "Input Lag" in HTML5 games — VSync Tester](https://www.vsynctester.com/game.html)
+- [Optimize input delay — web.dev](https://web.dev/articles/optimize-input-delay)
+
+### Memory & State Management
+- [How to Avoid Memory Leaks in JavaScript Event Listeners — DEV Community](https://dev.to/alex_aslam/how-to-avoid-memory-leaks-in-javascript-event-listeners-4hna)
+- [4 Types of Memory Leaks in JavaScript and How to Get Rid Of Them — Auth0](https://auth0.com/blog/four-types-of-leaks-in-your-javascript-code-and-how-to-get-rid-of-them)
+
+### AI & Game Balance
+- [Dynamic game difficulty balancing — Wikipedia](https://en.wikipedia.org/wiki/Dynamic_game_difficulty_balancing)
+- [Artificial Difficulty in Games — Indiecator](https://indiecator.org/2024/08/20/artificial-difficulty-in-games/)
+- [Dynamic Difficulty Adjustment (DDA) in Computer Games: A Review — Zohaib et al. 2018](https://onlinelibrary.wiley.com/doi/10.1155/2018/5681652)
+
+---
+
+*Pitfalls research for: HTML5 Canvas arcade game (Pong-like)*
+*Researched: 2026-03-10*
diff --git a/.planning/research/STACK.md b/.planning/research/STACK.md
new file mode 100644
index 0000000..0a8f435
--- /dev/null
+++ b/.planning/research/STACK.md
@@ -0,0 +1,328 @@
+# Stack Research: HTML5 Canvas Arcade Game (Super Pong Next Gen)
+
+**Domain:** Vanilla HTML5 Canvas arcade game
+**Researched:** 2026-03-10
+**Confidence:** HIGH
+
+## Recommended Stack
+
+### Core Technologies
+
+| Technology | Version | Purpose | Why Recommended |
+|------------|---------|---------|-----------------|
+| HTML5 Canvas 2D Context | Built-in | Game rendering and graphics | Native to all modern browsers, perfect for 2D arcade games. Canvas 2D is the standard choice for sprite/particle-based games like Pong with excellent CPU performance and full control over pixel rendering. WebGL adds complexity (requires GLSL shaders and 3D math) without benefit for 2D arcade games. |
+| Vanilla JavaScript (ES6+) | Latest | Game logic, input handling, game loop | No framework overhead. Direct Canvas API control. ES6+ provides async/await, arrow functions, and classes for clean game code. This is the standard for shipping static HTML5 games. |
+| requestAnimationFrame (RAF) API | Built-in | Main game loop timing | Standard for browser games since 2011. RAF automatically syncs with monitor refresh rate (60 Hz or 120 Hz depending on display), pauses in background tabs (saves battery), and eliminates timing issues with setTimeout/setInterval. All modern browsers support it natively. |
+| Fixed Timestep Accumulator Pattern | Custom implementation | Consistent game physics and gameplay | Decouples game simulation (fixed 60 Hz physics) from rendering (variable frame rate). Ensures Pong ball physics, paddle collision, and scoring behave identically across devices with different monitor refresh rates. Prevents "spiral of death" on low-end hardware. Accumulator pattern is the gold standard since Gaffer on Games established it in 2006. |
+| Web Audio API | Built-in | Sound effects and music | Native support across all modern browsers. Handles unlimited simultaneous sounds (no 32-sound limit like old <audio> tags). Precise timing control needed for paddle hits, scoring, and power-up sounds. Avoids HTML <audio> tag bloat and pre-loading issues. |
+
+### Supporting Libraries
+
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| GSAP (TweenLite) | v3 | Easing, tweening, animations | Optional for smooth UI animations (menu transitions, score popups, power-up indicators). Only needed if you want sophisticated easing curves beyond linear interpolation. ~20 KB minified. Can be omitted if easing is written manually. |
+| None (write particle effects from scratch) | — | Particle effects (screen shake, paddle hits, power-up bursts) | Vanilla JavaScript particle system is only ~200 lines of code. Creates a simple emitter system with velocity, gravity, alpha fade. Gives full control over visual style and performance. Pre-built particle libraries add 10-50 KB for minimal benefit in a 2D arcade game. |
+| None (write collision detection from scratch) | — | Collision detection (paddle-ball, ball-wall) | For Pong, only AABB (Axis-Aligned Bounding Box) and circle-rectangle collision needed. Simple math functions (~50 lines total). Physics libraries like Cannon.js are overkill and add 100+ KB. |
+
+### Development Tools
+
+| Tool | Purpose | Notes |
+|------|---------|-------|
+| Live Server / Python -m http.server | Local development | No build step required. Run `python3 -m http.server` or use VS Code Live Server extension. Canvas and Web Audio require HTTP (not file://) due to CORS and security. |
+| Browser DevTools (Chrome/Firefox) | Debugging and profiling | Built-in. Use Performance tab to measure frame rate (aim for 60 fps consistent). Use Network tab to verify static file loads instantly. Use Console for logging game state. |
+| No build tools (webpack, vite, esbuild) | Single static file delivery | Avoid build complexity. Ship as `index.html` with inline `<script>` or separate `.js` file. This is the greenfield constraint and strength of this approach. |
+
+## Architecture Patterns
+
+### Game Loop Structure (Recommended Implementation)
+
+```javascript
+// Fixed timestep with variable rendering
+let lastTime = 0;
+let accumulator = 0;
+const FIXED_TIMESTEP = 1 / 60; // 60 Hz physics
+
+function gameLoop(currentTime) {
+  const deltaTime = (currentTime - lastTime) / 1000; // Convert to seconds
+  lastTime = currentTime;
+
+  // Cap deltaTime to prevent spiral of death (max 3 frames worth)
+  const clampedDelta = Math.min(deltaTime, 3 * FIXED_TIMESTEP);
+
+  accumulator += clampedDelta;
+
+  // Fixed timestep updates
+  while (accumulator >= FIXED_TIMESTEP) {
+    update(FIXED_TIMESTEP); // Physics, collisions, AI
+    accumulator -= FIXED_TIMESTEP;
+  }
+
+  // Variable rate rendering
+  render(); // Draw to canvas
+
+  requestAnimationFrame(gameLoop);
+}
+
+requestAnimationFrame(gameLoop);
+```
+
+**Why this pattern:**
+- Physics runs at fixed 60 Hz → identical gameplay on 60 Hz and 144 Hz monitors
+- Rendering runs as fast as hardware allows → smooth visuals
+- Accumulator prevents frame skipping and ensures no physics updates are missed
+- Capped deltaTime prevents "spiral of death" when a frame takes too long
+
+### Particle System Pattern
+
+```javascript
+class Particle {
+  constructor(x, y, vx, vy) {
+    this.x = x; this.y = y;
+    this.vx = vx; this.vy = vy;
+    this.life = 1.0; // Alpha
+    this.decay = 0.02; // Life per frame
+  }
+
+  update(dt) {
+    this.x += this.vx * dt;
+    this.y += this.vy * dt;
+    this.life -= this.decay * dt;
+  }
+
+  draw(ctx) {
+    ctx.globalAlpha = this.life;
+    ctx.fillStyle = 'rgba(255, 200, 0, 1)';
+    ctx.fillRect(this.x - 2, this.y - 2, 4, 4);
+    ctx.globalAlpha = 1.0;
+  }
+}
+
+class ParticleEmitter {
+  constructor() {
+    this.particles = [];
+  }
+
+  emit(x, y, count = 10) {
+    for (let i = 0; i < count; i++) {
+      const angle = (Math.PI * 2 * i) / count;
+      const speed = 100 + Math.random() * 50;
+      this.particles.push(
+        new Particle(x, y, Math.cos(angle) * speed, Math.sin(angle) * speed)
+      );
+    }
+  }
+
+  update(dt) {
+    this.particles = this.particles.filter(p => {
+      p.update(dt);
+      return p.life > 0;
+    });
+  }
+
+  draw(ctx) {
+    this.particles.forEach(p => p.draw(ctx));
+  }
+}
+```
+
+**Why custom:** No external library needed, ~100 lines total, full control over visuals and performance, can emit thousands of particles without hiccup.
+
+### Collision Detection (AABB for Paddles/Ball)
+
+```javascript
+// Axis-Aligned Bounding Box collision
+function checkAABBCollision(rect1, rect2) {
+  return rect1.x < rect2.x + rect2.width &&
+         rect1.x + rect1.width > rect2.x &&
+         rect1.y < rect2.y + rect2.height &&
+         rect1.y + rect1.height > rect2.y;
+}
+
+// Circle-Rectangle collision (ball hitting paddle edge)
+function checkCircleRectCollision(circle, rect) {
+  const closestX = Math.max(rect.x, Math.min(circle.x, rect.x + rect.width));
+  const closestY = Math.max(rect.y, Math.min(circle.y, rect.y + rect.height));
+
+  const distX = circle.x - closestX;
+  const distY = circle.y - closestY;
+
+  return (distX * distX + distY * distY) < (circle.radius * circle.radius);
+}
+```
+
+**Why custom:** These are 10-15 lines of simple math. Physics libraries like Cannon.js add 100+ KB for zero benefit in Pong.
+
+## Alternatives Considered
+
+| Recommended | Alternative | When to Use Alternative |
+|-------------|-------------|-------------------------|
+| Vanilla JS | Three.js or Babylon.js (WebGL) | Only if game needs 3D rotation, lighting, or 10,000+ on-screen objects. Arcade Pong is 2D, simple geometry → Canvas 2D is faster and easier. |
+| Canvas 2D | WebGL 2.0 | Only if game needs advanced shaders, real-time shadow casting, or HDR rendering. For "juicy" 2D arcade effects (particles, glow, screen shake) Canvas 2D is sufficient. |
+| Fixed timestep accumulator | Variable timestep (frame-by-frame) | Only for turn-based games where gameplay doesn't depend on consistent physics timing. Pong requires consistent ball physics across all refresh rates → fixed timestep is mandatory. |
+| Web Audio API | HTML <audio> tag | Only for narration/long-form audio where streaming is needed. Web Audio is superior for game SFX: no pre-loading, unlimited simultaneous sounds, precise timing, no browser quirks. |
+| Custom particle system | Pixi.js (2D rendering library) | Only if game needs 100,000+ animated sprites with sophisticated batching. Pong has <50 particles at once → custom system is overkill. Pixi adds 150+ KB. |
+| GSAP (optional) | Manual easing functions | Only if UI animations are sophisticated. For power-up indicators or simple score popups, hand-written easing (ease-in, ease-out) is 5 lines of code. |
+
+## What NOT to Use
+
+| Avoid | Why | Use Instead |
+|-------|-----|-------------|
+| Phaser, Babylon.js, Cocos2d, Unity WebGL | Overkill for 2D arcade game. Adds 500 KB-2 MB bundle size, build complexity, learning curve, and abstraction layers that make low-level control harder. | Vanilla Canvas 2D + requestAnimationFrame. This is greenfield—ship single HTML file. |
+| Webpack, Vite, esbuild, rollup | Build tool complexity defeats purpose of "single static file." Game runs fine without transpilation (ES6+ is supported in all modern browsers since 2015). | Ship as plain HTML + vanilla JS. Keep file structure flat: index.html, styles.css (optional), game.js. |
+| Three.js / WebGL | Adds 3D complexity (GLSL shaders, matrix math, GPU programming) for no visual benefit. Pong is 2D rectangles + particles. Canvas 2D renders these faster on CPU. | Stay with Canvas 2D. If you ever need 3D, migrate then (unlikely). |
+| Cannon.js, Rapier (Physics engines) | Pong physics is trivial: ball bounces off walls and paddles with simple reflection math. Physics engine overhead (100+ KB, collision manifolds, impulse resolution) is wasted. | Implement ball reflection logic in 20 lines: `ballVx *= -1` for wall hits, angle-based bounce for paddle hits. |
+| npm dependencies for utilities | Every npm package adds build friction and bundle size. Helper functions (color conversion, easing, vector math) are simpler to write inline than to manage as dependencies. | Write custom utilities inline. A 2D vector helper is 30 lines. An easing function is 5 lines. |
+| Persistent leaderboards / Backend | Out of scope (no server in requirements). Adds deployment complexity and API security concerns. | Store scores in localStorage for local play session only. No remote persistence needed for v1. |
+
+## Stack Patterns by Variant
+
+**If you want polished particle effects and screen shake:**
+- Use Web Audio API for impact sounds timed with physics (paddle hit → sfx + particle burst)
+- Implement custom ParticleEmitter class (~100 lines)
+- Add screen shake via simple canvas translate: `ctx.translate(Math.random() - 0.5, Math.random() - 0.5)`
+- This is the path for "visually juicy" requirements in PROJECT.md
+
+**If you want to minimize code and polish:**
+- Strip to: Canvas 2D, RAF, Web Audio API (built-in), no particles, basic shapes only
+- Trade visual juice for ~500 lines of code
+- Not recommended given PROJECT.md emphasis on "makes someone say whoa"
+
+**If you want to add difficulty scaling (AI opponent):**
+- Implement AI as simple state machine: track ball, move paddle toward it, add reaction delay
+- Use fixed timestep to ensure AI behaves consistently across devices
+- AI decision logic lives in update loop, no separate AI library needed
+
+## Version Compatibility
+
+| Package | Version | Notes |
+|---------|---------|-------|
+| Canvas 2D API | All modern browsers (ES5+) | No version to pin. Available everywhere. |
+| requestAnimationFrame | All modern browsers (ES5+) | No version. Standard since 2011. IE 10+ supported. |
+| Web Audio API | All modern browsers (2012+) | No version. Safari, Chrome, Firefox, Edge all current versions support it fully. |
+| GSAP TweenLite (if used) | v3+ | v3 is lightweight (~40 KB minified). Can be loaded from CDN or skipped entirely. No peer dependencies. |
+| JavaScript language | ES6+ | Modern syntax. All deployment targets support ES6+ (Chrome 51+, Firefox 54+, Safari 10+, Edge 15+). No transpilation needed. |
+
+## Installation (No Build Required)
+
+```html
+<!-- Minimal setup: index.html -->
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Super Pong Next Gen</title>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <style>
+    body { margin: 0; overflow: hidden; background: #111; }
+    canvas { display: block; }
+  </style>
+</head>
+<body>
+  <canvas id="gameCanvas" width="800" height="600"></canvas>
+
+  <!-- Optional: GSAP TweenLite for UI animations -->
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.2/gsap.min.js"></script>
+
+  <!-- Game code -->
+  <script src="game.js"></script>
+</body>
+</html>
+```
+
+**To run locally (no build step):**
+
+```bash
+# Option 1: Python (built-in)
+python3 -m http.server 8000
+
+# Option 2: Node.js (if installed)
+npx http-server
+
+# Option 3: VS Code Live Server extension (GUI click)
+```
+
+Then open `http://localhost:8000` in browser.
+
+**No npm, no build tools, no transpilation needed.** The constraint is a feature—maximizes portability and minimizes deployment surface area.
+
+## Critical Decisions
+
+### Canvas 2D, Not WebGL
+
+**Decision:** Use Canvas 2D API exclusively.
+
+**Reasoning:**
+- Pong is pure 2D (rectangles, circles, particles)
+- Canvas 2D has zero startup cost, WebGL requires GLSL shader compilation
+- Canvas 2D draws millions of pixels per frame efficiently on CPU
+- WebGL overkill: no 3D transforms, no complex lighting, no real-time shadow maps
+- Canvas 2D is familiar to JavaScript devs (no GPU programming knowledge needed)
+- Performance: Canvas 2D renders 2D arcade games faster than WebGL on mid-range hardware
+
+**Outcome:** Single canvas element, 2D context. All graphics drawn with fillRect, fillCircle, drawImage (if sprites).
+
+### Fixed Timestep Over Variable Timestep
+
+**Decision:** Implement fixed 60 Hz physics timestep with variable rendering refresh rate.
+
+**Reasoning:**
+- Ensures ball physics are identical on 60 Hz monitors and 144 Hz monitors
+- Prevents "bounce randomness" that breaks game feel
+- Accumulator pattern handles frame skipping without losing physics updates
+- Is the standard for physics-based games since 2006 (Gaffer on Games)
+- Prevents "spiral of death" on low-end hardware (capped deltaTime)
+
+**Outcome:** Game loop uses accumulator. Physics updates in fixed increments, rendering as fast as hardware allows.
+
+### Web Audio API, Not HTML <audio>
+
+**Decision:** Use Web Audio API for all sound.
+
+**Reasoning:**
+- No pre-loading required (unlike <audio> tags which need preload attributes and suffer quirks)
+- Unlimited simultaneous sounds (no 32-sound limit)
+- Precise timing control needed for game feel (paddle hit → instant sfx feedback)
+- Single API handles both sound effects and dynamic music
+- Works offline and in Service Workers
+
+**Outcome:** Create AudioContext, use Web Audio nodes for synthesis or sample playback.
+
+### No External Game Engine or Physics Library
+
+**Decision:** Custom implementation of game loop, collision detection, and particle effects.
+
+**Reasoning:**
+- Phaser/Babylon.js add 500 KB-2 MB for features Pong doesn't use
+- Collision detection is trivial (AABB + circle-rect = 20 lines)
+- Particle system is 100 lines of simple code
+- Keeping code hand-written gives full control, understanding, and minimum bundle
+- Greenfield constraint: single static file = no build toolchain
+
+**Outcome:** ~1000-1500 lines of game code total. No dependencies. Portable everywhere.
+
+## Deployment Constraints
+
+- **Single file delivery:** HTML file can inline CSS and JavaScript or load them as separate files
+- **No server required:** Can be hosted on GitHub Pages, Netlify, or any static host
+- **No build step:** Can edit game.js, reload browser, see changes instantly
+- **Browser compatibility:** Target modern browsers (Chrome 90+, Firefox 88+, Safari 14+, Edge 90+)
+
+## Sources
+
+- [MDN Canvas API & 2D Context](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) — Core Canvas rendering specification
+- [MDN requestAnimationFrame](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame) — Game loop timing standard
+- [MDN Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API) — Game sound implementation
+- [Gaffer on Games: Fix Your Timestep](https://gafferongames.com/post/fix_your_timestep/) — Fixed timestep pattern (2004, still standard)
+- [MDN 2D Collision Detection](https://developer.mozilla.org/en-US/docs/Games/Techniques/2D_collision_detection) — AABB and circle collision algorithms
+- [Animation and Game Development with HTML5 Canvas](https://medium.com/@TechnologyDiaries/animation-and-game-development-with-html5-canvas-f0c599312a00) — 2025 Canvas best practices (Medium)
+- [Create a Proper Game Loop](https://spicyyoghurt.com/tutorials/html5-javascript-game-development/create-a-proper-game-loop-with-requestanimationframe) — Game loop implementation patterns
+- [Taming Time in Game Engines](https://andreleite.com/posts/2025/game-loop/fixed-timestep-game-loop/) — 2025 fixed timestep deep dive
+- [GSAP Documentation](https://gsap.com/docs/v3/GSAP/Tween/) — Tweening library (optional for UI)
+- [WebGL vs Canvas: Best Choice](https://altersquare.io/webgl-vs-canvas-best-choice-for-browser-based-cad-tools/) — Canvas 2D vs WebGL decision framework
+- [I Built 120 HTML5 Games Using Pure Canvas](https://dev.to/cannan_david/i-built-120-html5-games-using-pure-canvas-no-frameworks-gdm) — Real-world evidence of vanilla Canvas viability
+- [MDN 2D Breakout Game Tutorial](https://developer.mozilla.org/en-US/docs/Games/Tutorials/2D_Breakout_game_pure_JavaScript) — Step-by-step vanilla Canvas game example
+
+---
+*Stack research for: Super Pong Next Gen (HTML5 Canvas arcade game)*
+*Researched: 2026-03-10*
+*Confidence: HIGH*
diff --git a/.planning/research/SUMMARY.md b/.planning/research/SUMMARY.md
new file mode 100644
index 0000000..27ce9e5
--- /dev/null
+++ b/.planning/research/SUMMARY.md
@@ -0,0 +1,227 @@
+# Project Research Summary
+
+**Project:** Super Pong Next Gen
+**Domain:** HTML5 Canvas 2D arcade game
+**Researched:** 2026-03-10
+**Confidence:** HIGH
+
+## Executive Summary
+
+Super Pong Next Gen is a classic 2D arcade game built with vanilla HTML5 Canvas (no frameworks), deployed as a single static HTML file. Research strongly recommends a minimal-dependencies approach: Canvas 2D rendering, requestAnimationFrame game loop with fixed physics timestep, Web Audio API for sound, and vanilla JavaScript ES6+. This keeps the bundle small, deployment simple, and code maintainable.
+
+The core challenge is not technology selection but execution quality. Research identified 8 critical pitfalls that will break the game if missed: ball tunneling through paddles at high speeds, game loop timing causing frame-rate inconsistency or cascading slowdowns ("spiral of death"), canvas DPI scaling causing blur on Retina displays, audio autoplay policy silencing the game on first load, AI difficulty imbalance, power-up tuning, input lag, and memory leaks from event listeners. Each pitfall is well-understood and preventable with the right architectural choices made early.
+
+The recommended roadmap structures development as 10 phases, starting with the game loop + core physics, then adding second paddle and AI, state machine and menus, audio, visual polish (particles and effects), power-ups, arenas, and finally tuning and cross-browser testing. This order ensures each phase is testable and prevents costly late-stage refactoring.
+
+## Key Findings
+
+### Recommended Stack
+
+The stack is deliberately minimal to maximize portability and minimize deployment friction. Core technologies:
+
+- **HTML5 Canvas 2D Context** — Rendering for 2D sprites, particles, UI. Chosen over WebGL because Pong is pure 2D with no lighting/shaders. WebGL adds complexity for zero visual benefit.
+- **Vanilla JavaScript ES6+** — Game logic and game loop. No framework overhead, direct Canvas control. All modern browsers support ES6+ natively (no transpilation).
+- **requestAnimationFrame (RAF)** — Game loop timing. Syncs with monitor refresh (60/120 Hz), pauses in background tabs (battery-saving), eliminates setTimeout jitter.
+- **Fixed Timestep Accumulator Pattern** — Physics runs at fixed 60 Hz, rendering at variable frame rate. Ensures ball physics are identical across all monitor refresh rates. Decouples gameplay from hardware.
+- **Web Audio API** — Sound effects and music. No pre-loading required, unlimited simultaneous sounds, precise timing control for game feedback.
+
+**Optional enhancements:** GSAP TweenLite (v3, ~40 KB) for UI animations, but can be omitted. All other functionality (particles, collision, sound) uses vanilla code (<200 lines each).
+
+**No build tools:** Ship as plain HTML + JavaScript. No Webpack, Vite, esbuild, or transpilation. Deployment is a single file on any static host.
+
+**Why this stack:** Canvas 2D is the 2025 standard for 2D arcade games. Fixed timestep is canonical since Gaffer on Games (2004). No physics engines needed (Pong collision is 20 lines of math). No particle libraries needed (100 lines of vanilla code gives full control). Result: ~1500-2000 lines of game code total, portable everywhere.
+
+### Expected Features
+
+**MVP (v1.0) — Launch with these:**
+- Basic Pong gameplay (ball, 2 paddles, collision detection) — Core loop
+- AI opponent with Easy/Medium/Hard difficulty levels — Solo players need challenge progression
+- 2-player local multiplayer (keyboard-based) — Arcade tradition
+- Score tracking & match structure (first to N points) — Players need goals
+- Game screens (title, mode select, game over) — Professional feel
+- Pause functionality — User expectation
+- Settings menu (difficulty, sound toggle, color scheme) — Control signals quality
+- Basic visual feedback (glow/flash on collision) — Starts the "juice"
+- Basic sound effects (paddle hit, wall hit, score) — Arcade authenticity
+
+**v1.x Polish Pass — Add after validation:**
+- Particle effects on ball impact — Visual juice, differentiator
+- Ball trail / motion blur effect — Improves clarity at high speeds
+- Power-ups (3-4 types: multi-ball, slow time, enlarged paddle, speed boost) — Strategic depth
+- Multiple arenas (2-3 variations) — Extends play value
+- Background music loop — Ambience
+- Screen shake on scoring — Physical feedback
+- Difficulty progression (ball speeds up over match) — Escalates tension
+
+**v2+ or defer indefinitely:**
+- Online multiplayer / leaderboards — Out of scope (no backend)
+- Mobile touch controls — Separate design problem
+- Persistent progression — Requires database
+- Tutorial flow — Pong learns-by-doing
+- 10+ power-up types — Over-complicates game
+- Procedural arenas — Makes balance impossible
+- AI learning/adaptation — Feels unfair
+
+**Feature dependencies:** Game loop requires ball physics and collision. AI requires difficulty system. Power-ups require solid core loop. Settings enhance features across difficulty, visuals, audio without complicating core.
+
+### Architecture Approach
+
+Recommended architecture uses classic game development patterns proven across 2D arcade games:
+
+- **Game Loop** — requestAnimationFrame + fixed timestep accumulator (60 Hz physics, variable rendering)
+- **State Machine** — Menu → GameState → PauseState → GameOverState with onEnter/update/render/onExit hooks
+- **Entity System** — Paddle, Ball, PowerUp as objects with update() and render() methods
+- **Collision System** — AABB (Axis-Aligned Bounding Box) for rectangles, circle-distance for ball
+- **Particle System** — Simple emitter (~100 lines) for visual effects, particles with lifetime/alpha fade
+- **Audio Manager** — Sound pooling to prevent cutoff on rapid-fire effects
+- **Input Manager** — Keyboard state tracking (key state map, polled during update)
+
+**10-phase build order** ensures testability and avoids cascading refactoring:
+
+1. Game Loop + Canvas Setup
+2. Input + Physics + Collision
+3. Second Paddle + AI + State Management
+4. Menus + Audio
+5. Pause State
+6. Particle System + Visual Effects
+7. Power-Ups + Arenas
+8. Advanced Polish + Tuning
+9. Performance Profiling
+10. Release Testing
+
+Each phase produces independently testable deliverables.
+
+### Critical Pitfalls
+
+Research identified 8 pitfalls with clear prevention strategies:
+
+1. **Ball Tunneling** (Phase 2) — Ball passes through paddles at high speed. Fix: Continuous collision detection or velocity clamping. Test early with max expected speeds.
+
+2. **Game Loop Timing** (Phase 1) — Frame-rate dependency or "spiral of death." Fix: Fixed timestep with capped delta time, requestAnimationFrame (not setInterval).
+
+3. **Canvas DPI Scaling** (Phase 1) — Blurry on Retina displays. Fix: Query devicePixelRatio, scale canvas internal resolution, test on real hardware. 1 hour, massive visual impact.
+
+4. **WebAudio Autoplay Policy** (Phase 4) — Audio silent on first load. Fix: Initialize on first user gesture, call context.resume(), provide audio toggle.
+
+5. **AI Difficulty Balance** (Phase 3) — AI trivially easy or impossibly hard. Fix: Easy/Medium/Hard with reaction delays (0.3s/0.1s/0.05s) and error margins (±20/±5/±2 pixels). Playtest each level.
+
+6. **Power-Up Balance** (Phase 7) — Over/under-powered effects. Fix: Categorize by tier, tune spawn rates, test all combinations, ensure visual feedback.
+
+7. **Input Lag** (Phase 2) — Unresponsive paddle. Fix: RAF (not setInterval), key state map, poll during update (not in event handler).
+
+8. **Memory Leaks** (Phase 3) — Creeping memory after multiple rounds. Fix: Remove all event listeners on state transitions. Test with DevTools Memory profiler.
+
+## Implications for Roadmap
+
+### Phase 1: Game Loop + Rendering Setup
+**Rationale:** Foundation. Every other system depends on correct timing and rendering.
+**Delivers:** Canvas with DPI scaling, RAF game loop with fixed timestep accumulator, delta time capping, initial state rendering.
+**Avoids:** Game loop timing issues, DPI blur, frame-rate dependency.
+**Effort:** 1-2 days.
+
+### Phase 2: Input + Physics + Collision
+**Rationale:** Players can't engage without paddle control and ball physics. Input responsiveness is critical.
+**Delivers:** Keyboard input with key state map, ball velocity-based movement, AABB + circle-rect collision, ball bouncing.
+**Avoids:** Input lag, tunneling, unresponsive controls.
+**Effort:** 2-3 days.
+
+### Phase 3: Second Paddle + AI + State Management
+**Rationale:** Core game playable with two paddles. AI enables solo play. State management prevents listener leaks.
+**Delivers:** Second paddle (AI-controlled), AI with Easy/Medium/Hard, score tracking, state transitions, listener cleanup.
+**Avoids:** Difficulty imbalance, memory leaks, unbalanced solo play.
+**Effort:** 2-3 days.
+
+### Phase 4: Menus + Audio
+**Rationale:** Polished UX flow. Audio requires careful autoplay policy handling.
+**Delivers:** Title/mode select/game over screens, settings menu, Web Audio with pooling, sound effects, context.resume() on first click.
+**Avoids:** Silent game on first load, autoplay violations, input conflicts.
+**Effort:** 2-3 days.
+
+### Phase 5: Pause State
+**Rationale:** User expectation. Simple to add after menus.
+**Delivers:** Pause key, pause overlay, resume/settings/menu options.
+**Effort:** 0.5 days.
+
+### Phase 6: Particle System + Visual Polish
+**Rationale:** Creates "juice" — immediate visual feedback on collisions.
+**Delivers:** Particle bursts on collision, ball trails, glow effects, optional screen shake.
+**Avoids:** Flat gameplay, particle lag (keep <100 on screen).
+**Effort:** 2-3 days.
+
+### Phase 7: Power-Ups + Arenas
+**Rationale:** Strategic depth and play value extension. Requires solid core first.
+**Delivers:** 3-4 power-up types with spawn logic, arena selection, 2-3 layout variations.
+**Avoids:** Overpowered effects, balance-breaking combinations.
+**Effort:** 3-4 days.
+
+### Phase 8: Advanced Polish + Tuning
+**Rationale:** Refinement after core validates. Difficulty progression, music, sound design.
+**Delivers:** Difficulty scaling (ball speeds up), AI behavioral variety, background music, enhanced SFX.
+**Effort:** 2-3 days.
+
+### Phase 9: Performance Profiling
+**Rationale:** Ensure 60 fps on target hardware. Profile rendering and memory.
+**Delivers:** Verified 60 fps, no memory creep after 10+ sessions, optimized particle/collision systems.
+**Effort:** 1-2 days.
+
+### Phase 10: Release Testing
+**Rationale:** Final validation. Cross-browser and platform testing.
+**Delivers:** Confirmed working on Chrome 90+, Firefox 88+, Safari 14+, Edge 90+. DPI scaling on Retina verified. Input lag <50ms. All pitfalls mitigated.
+**Effort:** 1-2 days.
+
+**Total estimated effort:** 16-25 days for core game (Phases 1-6), additional 10-12 days for depth features (Phases 7-10).
+
+### Phase Ordering Rationale
+
+1. **Dependency chain:** Game loop (P1) → Physics (P2) → AI (P3) → Menus (P4) → Enhancements (P5+)
+2. **Risk mitigation:** Critical pitfalls addressed in Phases 1-2 when code is small. AI balance tuned in Phase 3. Audio in Phase 4. Power-ups deferred to Phase 7.
+3. **Testability:** Each phase produces playable deliverables. Continuous validation, not waterfall.
+
+### Research Flags
+
+**Phases needing deeper research:**
+- **Phase 3 (AI):** Exact reaction delay and error margin values need playtesting with human players. Estimates provided, but empirical tuning required.
+- **Phase 7 (Power-ups):** Spawn rate tuning (weak/medium/strong frequencies) depends on desired chaos level. Playtesting loop needed.
+
+**Phases with standard patterns (skip deep research):**
+- **Phase 1 (Game Loop):** Fixed timestep is canonical (Gaffer on Games). Canvas 2D rendering is well-documented (MDN).
+- **Phase 2 (Physics/Collision):** AABB and circle-rect are textbook algorithms. RAF usage is standard.
+- **Phase 4 (Audio):** Web Audio autoplay policy is documented in official sources. context.resume() is standard pattern.
+- **Phase 6 (Particles):** Particle systems are well-understood. Standard implementation patterns.
+
+## Confidence Assessment
+
+| Area | Confidence | Notes |
+|------|------------|-------|
+| Stack | HIGH | Canvas 2D, RAF, fixed timestep, Web Audio all verified in official MDN docs, established patterns (Gaffer on Games 2004), and community consensus. No alternatives justified. |
+| Features | HIGH | Table stakes align with arcade conventions. MVP/v1.x split based on complexity analysis. Feature dependencies mapped. Power-ups and arenas are proven enhancements. |
+| Architecture | HIGH | Game loop + state machine + entity system is industry-standard since 2006+. Verified across MDN tutorials, SitePoint guides, multiple 2025 sources. Component boundaries straightforward. |
+| Pitfalls | HIGH | All 8 pitfalls documented in official sources (MDN, Chrome for Developers, web.dev). Fixes are established patterns with proven solutions. No novel challenges identified. |
+
+**Overall confidence:** HIGH — All findings backed by official documentation, established patterns, and recent (2025) sources. No critical gaps. Ready for requirements.
+
+### Gaps to Address
+
+1. **AI parameter tuning:** Exact reaction delays and error margins need empirical validation. Initial estimates provided; refine during Phase 3 playtesting.
+2. **Power-up spawn rates:** Weak/medium/strong frequencies are estimates. Actual rates depend on match duration. Requires Phase 7 playtesting.
+3. **Particle performance limits:** <100 particles recommended. Actual limit depends on target hardware. Profile during Phase 9.
+4. **Audio SFX design:** Sounds identified (paddle hit, wall hit, score). Actual sound design can be simple sine-wave synthesis or professional samples. Polish during Phase 8.
+5. **localStorage performance:** Leaderboard storage safe for <1000 scores. Scaling beyond that not researched. Low priority for v1.
+
+## Sources
+
+Research synthesized from 4 specialist reports (STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md) covering:
+
+- **Official Documentation:** MDN Canvas API, requestAnimationFrame, Web Audio API, devicePixelRatio
+- **Established Patterns:** Gaffer on Games (fixed timestep, 2004), game loop patterns, state machines
+- **2025 Sources:** LogRocket, SitePoint, web.dev, Medium articles on Canvas performance
+- **Domain Resources:** Arcade game design fundamentals, Pong implementations, game UI conventions
+- **Official Guides:** Chrome for Developers (autoplay policy), web.dev (canvas optimization, input lag)
+
+All sources verified as HIGH confidence (official docs or multiple consensus sources).
+
+---
+
+*Research completed: 2026-03-10*
+*Four specialist research files synthesized*
+*Ready for requirements definition and roadmap creation*