- Add removedCells to GameOptions for custom puzzle sizes
- removedCells overrides difficulty default when provided
- Maintain backward compatibility with all defaults
- Complete IMPLEMENTATION.md with Iteration 16 and summary
- Completely rewrite README.md with comprehensive documentation:
- Complete API reference (GameOptions, GameManager, CursorManager, ScoreManager)
- Game states and state machine flow
- Full VIM controls reference (movement, editing, hints, game control)
- Cell state rules and visual feedback
- Detailed scoring formula with examples
- Game-over conditions (time and hint limits)
- Hint system priority and penalties
- Configuration examples for different play styles
- Platform hook integration guide
- Mark implementation as COMPLETE and PRODUCTION READY
- Add getHint() method to BoardManager with two-tier priority:
1. Find incorrect user-entered cells → flash red
2. Find empty cells → show correct digit green temporarily
- Add Shift+H key handler in useCursor (normal mode only)
- Visual feedback:
- Red flash (hint-flash-error): incorrect cells, 1s duration, red bg + border
- Green flash (hint-flash-correct): correct digit shown, 1s duration, green bg + border
- Distinct from invalid-move (no background, 500ms)
- Score penalties based on difficulty:
- Easy: 25 points per hint
- Medium: 50 points per hint
- Hard: 100 points per hint
- Track hints used in scoreboard display
- Correct digit appears temporarily (1s) then disappears (player still does the work)
- Update example app to show hints counter and Shift+H instruction
- Add useTimer hook for elapsed time tracking
- Add useScore hook with comprehensive metrics:
- Total keystrokes (all keys)
- Edit keystrokes (only editing keys)
- Optimal keystrokes (empty cells × 3)
- Efficiency percentage (optimal/edit × 100)
- Final score (70% efficiency + 30% time-based)
- Win condition detects board completion only in normal mode
- Track all keystrokes with timestamps in useGame
- Update example app with full scoreboard display
- Expose boardRef in BoardManager for state checking
- Adjust easy mode to 5 removed cells for testing
- Add x, d, Delete in normal mode to erase user-entered cells
- Add Backspace in edit mode to erase and stay in edit mode
- Add Backspace in normal mode as invalid move (red flash)
- All erase commands respect given cell protection
- Empty cells flash red on erase attempt in normal mode
- Add singleEdit state to track single vs multi-edit mode
- r and c only work on user-entered cells (flash red otherwise)
- i only works on empty cells (flash red on given or user-entered)
- r/c auto-exit to normal mode after one digit entry
- i stays in edit mode until Escape (multi-edit)
- Add position to useEffect dependency array in useCursor
- Fixes issue where old position was captured in handleKeyDown closure
- Edit mode entry now correctly validates current cell position
- Add setCell method to useBoard to update board state
- Handle digit keys 1-9 in edit mode in useCursor
- Move boardRendered counter to useBoard for proper cursor re-rendering
- Fix golden glow disappearing after digit entry
- Digits display with .user-entered class via renderer
Comprehensive prompt for Phase 40.3.3 (digit entry):
- Context setup instructions
- Complete summary of Phases 40.1, 40.2, 40.3
- Current architecture overview
- Detailed implementation strategy for digit entry
- Testing checklist
- Agent rules and code conventions
- Quick reference for current state
This document allows seamless continuation in a new chat session
with full context and clear next steps.
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).
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