From 695c356e917bbdf5de027dd7dd81b57014085317 Mon Sep 17 00:00:00 2001
From: Andre Padez <andre.padez@gmail.com>
Date: Wed, 22 Oct 2025 18:59:47 +0100
Subject: [PATCH] docs: document Phase 40.1 implementation and Issue 1 fix

---
 IMPLEMENTATION.md | 64 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 63 insertions(+), 1 deletion(-)

diff --git a/IMPLEMENTATION.md b/IMPLEMENTATION.md
index 5614d5d..72910aa 100644
--- a/IMPLEMENTATION.md
+++ b/IMPLEMENTATION.md
@@ -420,6 +420,68 @@ const gameManager = {
 
 ---
 
-## Iteration 6: [Pending]
+## Iteration 6: Phase 40.1 - Basic Cursor with hjkl Movement
+
+**Date**: 2025-01-22
+
+### Goals
+- Implement basic cursor navigation
+- Add hjkl vim keys
+- Visual cursor highlight
+- Only active during gameplay
+
+### Tasks Completed
+
+#### 1. Created useCursor Module
+- `useCursor.ts` - Position tracking and movement logic
+- `useCursorRender.ts` - Visual cursor highlight on DOM
+- `types.ts` - Coord and CursorManager types
+
+#### 2. Cursor Implementation
+- Position tracking with useState (row/col 0-8)
+- Movement functions: moveLeft, moveRight, moveUp, moveDown
+- Bounds checking prevents moving outside 9x9 grid
+- Keyboard listener for h/j/k/l keys
+- Only active when gameStatus === 'started'
+
+#### 3. Visual Feedback
+- Blue highlight with border on current cell
+- CSS class 'cursor' applied to active cell
+- Removed from previous cell on movement
+
+#### 4. Fixed Initial Cursor Display (Issue 1)
+**Problem**: Cursor not showing on game start before first move
+**Root Cause**: renderBoard() rebuilds DOM, wiping cursor class
+**Solution**: Added boardRendered counter
+- Increments after each renderBoard()
+- useCursorRender depends on boardRendered
+- Forces cursor re-application after DOM rebuild
+
+**Flow**:
+1. Press Space → startGame()
+2. renderBoard() rebuilds DOM
+3. boardRendered increments
+4. useCursorRender triggers
+5. Cursor class applied to (0,0)
+
+### Technical Details
+
+**useState vs useRef**:
+- Initially used useRef (no re-renders)
+- Changed to useState to trigger useCursorRender
+- Position changes now properly update DOM
+
+**Timing Issue Resolution**:
+- renderBoard() is synchronous
+- useEffect runs after render
+- boardRendered ensures proper ordering
+
+### Next Steps
+- Issue 2: Fix cursor border conflicts with grid edges
+- Issue 3: Add red flash on invalid movement attempts
+
+---
+
+## Iteration 7: [Pending]
 
 *To be filled as implementation progresses...*