docs: document Phase 40.3 - Edit Mode Implementation

Documented complete edit mode state machine:
- Phase 40.3.1: Mode state (normal/edit) with i and Escape
- Phase 40.3.2: Edit rules (given cells block, red flash feedback)
- Visual indicators using existing CSS classes
- Mode behavior and transitions

All edit mode functionality tested and working:
✅ State machine transitions
✅ Given cell validation with red flash
✅ Visual feedback (blue/yellow/red)
✅ Vim motions blocked in edit mode

Phase 40.3 complete. Ready for digit entry (40.3.3).

IMPLEMENTATION.md

@@ -648,6 +648,120 @@ type Motion = { dr: number; dc: number; steps: number };
 
 ---
 
-## Iteration 8: [Pending]
+## Iteration 8: Phase 40.3 - Edit Mode Implementation
+
+**Date**: 2025-01-22
+
+### Goals
+- Implement edit mode state machine
+- Add rules for editable vs given cells
+- Use existing CSS classes for visual feedback
+- No digit entry yet - just mode switching
+
+### Tasks Completed
+
+#### 1. Mode State Machine (Phase 40.3.1)
+**Added CursorMode type:**
+- `'normal'` - Navigation mode (vim motions active)
+- `'edit'` - Edit mode (ready for digit entry)
+
+**Key Bindings:**
+- `i` - Enter edit mode (insert)
+- `Escape` - Exit edit mode to normal
+
+**State Management:**
+- Mode tracked with useState in useCursor
+- Starts in 'normal' mode on game start
+- Mode passed to useCursorRender for visual feedback
+
+#### 2. Edit Mode Rules (Phase 40.3.2)
+**Cell Editability:**
+- Given cells (`.given` class): Cannot be edited
+- Empty cells: Can be edited
+- User-entered cells (`.user-entered` class): Can be edited
+
+**Validation Logic:**
+```typescript
+if (key === 'i') {
+  const targetCell = cells[index];
+  if (targetCell && targetCell.classList.contains('given')) {
+    flashInvalidMove();  // Red flash
+    return;              // Block edit mode
+  }
+  setMode('edit');       // Allow edit mode
+}
+```
+
+**Visual Feedback:**
+- Attempt to edit given cell → Red flash (500ms)
+- Successfully enter edit mode → Yellow/amber glow
+
+#### 3. Visual Indicators
+**Using Existing CSS Classes:**
+- Normal mode: `.active` class (blue glow)
+- Edit mode: `.editing` class (yellow/amber pulsing glow)
+- Invalid attempt: `.invalid-move` class (red flash)
+
+**Removed Custom CSS:**
+- Removed `.cursor` and `.cursor-edit` classes
+- Using original CSS design from src_old
+- Consistent with existing game aesthetics
+
+#### 4. Mode Behavior
+**Normal Mode:**
+- All vim motions work (hjkl, anchors, counts, repeat)
+- Blue glow on current cell
+- Can navigate freely
+
+**Edit Mode:**
+- All vim motions blocked
+- Yellow/amber pulsing glow
+- Only Escape key active (exit to normal)
+- Ready for digit entry (not implemented yet)
+
+### Technical Details
+
+**Cell Classification:**
+- Given cells: Have digits from puzzle generation
+- Renderer adds `.given` class to these cells
+- These cells are immutable (cannot be edited)
+
+**Flash Mechanism:**
+- `flashInvalidMove()` adds `.invalid-move` class
+- CSS animation shows red glow for 500ms
+- Class auto-removed after timeout
+- Same mechanism used for boundary violations
+
+**Mode Transition Flow:**
+```
+Normal (blue) 
+   ↓ [press i on empty/user cell]
+Edit (yellow)
+   ↓ [press Escape]
+Normal (blue)
+
+Normal (blue)
+   ↓ [press i on given cell]
+Red flash → Stay in Normal
+```
+
+### Testing Results
+✅ Edit mode state machine working
+✅ i and Escape toggle modes correctly
+✅ Given cells block edit mode with red flash
+✅ Empty cells allow edit mode
+✅ User-entered cells allow edit mode
+✅ Vim motions blocked in edit mode
+✅ Visual indicators clear and distinct
+
+### Next Steps
+- Phase 40.3.3: Add digit entry (1-9)
+- Phase 40.3.4: Add erase functionality (x, Backspace)
+- Phase 40.3.5: Add replace mode (r)
+- Integration with board state management
+
+---
+
+## Iteration 9: [Pending]
 
 *To be filled as implementation progresses...*