Rules Implemented:
1. Can only enter edit mode on empty cells or user-entered cells
2. Pressing 'i' on a given cell (from algo) triggers red flash
3. Edit mode blocked on cells with 'given' class
Visual Changes:
- Use existing 'active' class for normal mode cursor (blue glow)
- Use existing 'editing' class for edit mode (yellow/amber glow)
- Removed custom cursor/cursor-edit classes
- Matches original CSS design from src_old
Cell Detection:
- Check if cell has 'given' class before entering edit mode
- Given cells: From puzzle generation (immutable)
- Empty or user-entered cells: Can be edited
Flow:
1. Navigate to given cell → Press 'i' → Red flash (blocked)
2. Navigate to empty cell → Press 'i' → Yellow editing glow
3. Navigate to user-entered cell → Press 'i' → Yellow editing glow
4. Press Escape → Return to blue active glow
Phase 40.3.2 complete.
Added mode state machine with visual feedback:
Mode State:
- CursorMode type: 'normal' | 'edit'
- Tracked in useCursor with useState
- Starts in 'normal' mode
Key Bindings:
- Press 'i' in normal mode → Enter edit mode
- Press 'Escape' in edit mode → Return to normal mode
- All vim motions (hjkl, anchors, etc.) only work in normal mode
- Edit mode blocks all movement keys
Visual Feedback:
- Normal mode: Blue outline (rgb(59, 130, 246))
- Edit mode: Green pulsing outline (rgb(34, 197, 94))
- Smooth pulse animation (1.5s ease-in-out infinite)
- cursor-edit CSS class applied in edit mode
Flow:
1. Game starts in normal mode (blue cursor)
2. Press 'i' → Green pulsing cursor (edit mode)
3. Press 'Escape' → Blue cursor (normal mode)
No digit entry yet - just state machine and visual indicators.
Phase 40.3.1 complete.
Added pendingGRef to track when waiting for second 'g':
- First g: Set pendingGRef = true, return null (no action)
- Second g: Check pendingGRef, if true → 'top' anchor
- Any other key after first g: Clear pendingGRef, return null
Now:
- g alone → Nothing (waiting for second g)
- gg → Jump to top of column
- G → Jump to bottom of column
Matches vim behavior for gg command.
Added complete vim motion system with anchor moves:
New Files:
- src/useCursor/useVimMotions.ts: Vim motion processor
- Handles number prefixes (counts)
- Special 0 handling: anchor when alone, count when prefixed
- Tracks last motion for repeat (.)
Anchor Moves:
- 0 or ^ → Move to start of row (col 0)
- $ → Move to end of row (col 8)
- gg → Move to top of column (row 0)
- G → Move to bottom of column (row 8)
Count Support:
- 5j → Move down 5 cells
- 10l → Move right 10 cells (bounded to 8)
- Works with all directional moves (h/j/k/l)
Repeat Motion:
- . → Repeat last motion with same count
Key Logic (0 handling):
- If 0 pressed with empty count buffer → anchor to start
- If 0 pressed with existing count → add to count (10j, 20k)
- Prevents conflict between anchor and counted moves
Updated:
- useCursor.ts: Integrated useVimMotions processor
- types.ts: Added Motion and VimMotionSystem types
- CursorManager: Added anchor and repeat methods
All moves respect 9x9 bounds with red flash on invalid.
Documented:
- Issue 3: Red flash on invalid movement (500ms animation)
- Cleanup: Removed all debug console.logs
- Summary: All 3 issues resolved, production-ready
Phase 40.1 complete:
✅ Basic cursor with hjkl movement
✅ Visual cursor highlight (blue outline)
✅ Shows immediately on game start
✅ No border conflicts with grid edges
✅ Red flash feedback on invalid moves
✅ Clean, production-ready code
Ready for next phase or sidequest.
When user attempts to move out of bounds, show visual feedback:
CSS:
- Added .invalid-move class with red outline and background
- Animation: invalid-flash (500ms ease-out)
- Starts with bright red glow, fades out
- Red outline (3px solid) matches cursor style
Logic:
- flashInvalidMove() function in useCursor
- Triggers when move would go out of bounds (< 0 or > 8)
- Adds invalid-move class to current cell
- Removes class after 500ms
- Passes containerRef to useCursor for DOM access
Cleanup:
- Removed all console.log debugging statements
- Clean code ready for production
UX Flow:
- Press h at left edge → Red flash at current position
- Press j at bottom edge → Red flash at current position
- Press k at top edge → Red flash at current position
- Press l at right edge → Red flash at current position
Issue 3 complete!
Added boardRendered counter to track when board DOM is rebuilt:
- Increments after each renderBoard() call
- useCursorRender depends on boardRendered
- Forces cursor re-application after board rebuilds DOM
Flow:
1. Game starts
2. renderBoard() rebuilds DOM
3. boardRendered increments
4. useCursorRender triggers
5. Cursor class applied to (0,0)
This ensures cursor is visible immediately when pressing Space.
Issue: When game starts, renderBoard() rebuilds DOM which removes cursor class
Solution: Add gameStatus as dependency to useCursorRender
- Now re-applies cursor after board renders
- Only applies cursor when gameStatus === 'started'
This ensures cursor is visible immediately when game starts at position (0,0).
The cursor position wasn't updating visually because:
- useRef doesn't trigger re-renders
- useCursorRender wasn't being called on position changes
Solution:
- Changed position from useRef to useState
- Now position changes trigger re-renders
- useCursorRender receives updated position
- Cursor highlight updates properly
Added temporary console.logs for debugging:
- Cursor position changes
- Key press events
- Movement attempts and bounds checking
- Cell selection and class application
This will help verify cursor is working in browser.
Console logs to be removed once verified working.
Add cursor navigation with hjkl keys (vim-style):
New Module Structure:
- src/useCursor/types.ts: Coord and CursorManager types
- src/useCursor/useCursor.ts: Cursor movement logic
- src/useCursor/useCursorRender.ts: Visual cursor highlight
- src/useCursor/index.ts: Public exports
Cursor Implementation:
- Position tracking with useRef (row/col from 0-8)
- Basic movement: moveLeft, moveRight, moveUp, moveDown
- Bounds checking (prevents moving outside 9x9 grid)
- Keyboard listener for h/j/k/l keys
- Only active when gameStatus === 'started'
Cursor Rendering:
- useCursorRender hook tracks cursor position
- Adds 'cursor' CSS class to current cell
- Removes from previous cell on movement
- Blue highlight with border (rgba(59, 130, 246, 0.3))
Integration:
- src/useGame.ts: Integrate useCursor and useCursorRender
- src/types.ts: Export CursorManager and Coord types
- src/useBoard/types.ts: NEW - BoardManager type
- src/game.css: Add cursor highlight styles
Game Flow:
- Press Space → Game starts → Cursor appears at (0,0)
- Press h/j/k/l → Cursor moves (bounded to grid)
- Visual feedback with blue highlight
- Press Q → Return to waiting state
Phase 40.1 complete. Next: Add number prefixes (5j) and other vim motions.
Extract game status logic into dedicated hook following vim-maze pattern:
New Module Structure:
- src/useGameStatus/types.ts: GameStatus and GameStatusManager types
- src/useGameStatus/useGameStatus.ts: Hook implementation
- src/useGameStatus/index.ts: Public exports
Hook Implementation:
- State machine with 5 states (waiting/started/paused/game-over/game-won)
- Methods: startGame, togglePause, quitGame, setGameStatus
- Clean state transitions with useState
- Simpler than vim-maze (no intermediate 'has-key' state)
Updated Core Files:
- src/useGame.ts: Use useGameStatus() instead of inline useState
- Compose gameStatusManager into GameManager
- Cleaner separation of concerns
- src/types.ts: Import and re-export GameStatus types
- GameManager extends GameStatusManager (intersection type)
- Single source of truth for status types
- src/index.ts: Export useGameStatus hook publicly
Benefits:
- Reusable state machine
- Easier to test in isolation
- Follows unified API architecture
- Matches vim-maze patterns
State Transitions:
waiting → startGame() → started ↔ togglePause() ↔ paused
started → (win/lose) → game-won/game-over
* → quitGame() → waiting
Phase 30 complete. Next: Phase 40 (useCursor composition).
Add interactive difficulty selection when game is idle:
Example App Changes:
- example/src/App.tsx: Add difficulty state and radio group
- Import useState and Difficulty type
- Radio buttons for Easy/Medium/Hard
- Only visible when gameStatus === 'waiting'
- Updates difficulty state on selection
- Passes selected difficulty to useGame
Core Changes:
- src/useGame.ts: Respect difficulty changes
- Add difficulty to useEffect dependencies
- Regenerates board when difficulty changes
UX Flow:
1. User sees difficulty selector on idle screen
2. Selects difficulty (easy/medium/hard)
3. Presses Space to start
4. Puzzle generated with selected difficulty
5. On quit, returns to selector with last selection
Cell Counts:
- Easy: 40 empty cells (~41 givens)
- Medium: 50 empty cells (~31 givens)
- Hard: 60 empty cells (~21 givens)
Port sudoku generation algorithm and integrate with game flow:
Core Changes:
- src/useBoard/SudokuGenerator.ts: Ported from src_old/lib/Sudoku.ts
- Full puzzle generation algorithm (robatron/sudoku.js)
- Supports all difficulty levels (easy through inhuman)
- Returns 81-character string representation
- src/useBoard/useBoard.ts: Enhanced with puzzle state
- Added boardRef and initialBoardRef for state management
- Added generateBoard(difficulty) method
- Updated renderBoard() to display givens from board string
- Cells show digits for givens, empty for '.' characters
- src/useGame.ts: Integrated game flow
- Reads difficulty from GameOptions (defaults to 'easy')
- Generates puzzle on startGame (gameStatus → 'started')
- Re-renders board on status changes
- quitGame returns to empty grid
Game Flow:
- Waiting: Empty 9x9 grid
- Press Space → startGame() → puzzle generated (~62 givens on easy)
- Press Q → quitGame() → empty grid
Testing platformHook integration:
- startGame trigger working via useKeyBindings
- quitGame trigger working via useKeyBindings
- Board state properly cleared/populated on status changes
Phase 20 complete. Next: Phase 30 (useGameStatus hook).
- Archive previous implementation attempt (src -> src_failed)
- Create comprehensive IMPLEMENTATION_PLAN.md with phased approach
- Create IMPLEMENTATION.md to track implementation progress
- Update example app to match vim-maze patterns:
- Simplify UI to desktop-only (no mobile support)
- Add score metrics display (time, keystrokes, final score)
- Update instructions for sudoku-specific keys (hjkl, i for edit)
- Remove unnecessary mobile hooks
Phase 5 complete. Ready to begin Phase 10 (Setup & Core Types).
pastilhas