vim-sudoku/NEXT_PROMPT.md

Next Session Prompt - Phase 40.3.3: Digit Entry

Context Setup

Hi! We're continuing the vim-sudoku unified API implementation. I need you to:

1. Read these files first (in order):

   • IMPLEMENTATION_PLAN.md - Overall roadmap
   • IMPLEMENTATION.md - Full implementation log (read ALL iterations)
   • AGENTS.md in the root (../../AGENTS.md) - Code conventions
   • UNIFIED_API.md in the root - Architecture reference

2. Review current state:

   • We're in Phase 40.3.3 (digit entry for edit mode)
   • Check latest git commits to see what's been done
   • Current working directory: /home/pastilhas/projects/vimazing/games/vim-sudoku

What We've Completed

Phase 40.1: Basic Cursor (✅ DONE)

• hjkl movement with bounds checking
• Blue cursor highlight
• Red flash on invalid moves
• All working perfectly

Phase 40.2: Complete Vim Motions (✅ DONE)

• Anchor moves: 0, ^, $, gg, G
• Count prefixes: 5j, 10l, etc.
• Repeat motion: .
• The 0 caveat solved: if (key === '0' && countRef.current === '') → anchor, else count
• gg requires two presses (pendingGRef state)
• All tested and flawless

Phase 40.3: Edit Mode State Machine (✅ DONE)

Phase 40.3.1: Mode state (normal/edit)

• i to enter edit mode
• Escape to exit edit mode
• Visual feedback using existing CSS classes

Phase 40.3.2: Edit mode rules

• Given cells (.given class) → Red flash, edit blocked
• Empty cells → Edit allowed
• User-entered cells (.user-entered class) → Edit allowed
• Vim motions blocked in edit mode

Visual Indicators:

• Normal mode: .active class (blue glow)
• Edit mode: .editing class (yellow/amber pulsing glow)
• Invalid: .invalid-move class (red flash 500ms)

Current Architecture

Key Files

src/
├── types.ts                      # Main type exports
├── useGame.ts                    # Orchestrator
├── useBoard/
│   ├── types.ts                  # BoardManager
│   ├── useBoard.ts               # Board management
│   ├── SudokuGenerator.ts        # Puzzle generation (class)
│   └── SudokuRenderer.ts         # DOM rendering (class)
├── useCursor/
│   ├── types.ts                  # CursorManager, CursorMode, Motion
│   ├── useCursor.ts              # Cursor + mode state
│   ├── useCursorRender.ts        # Visual feedback
│   └── useVimMotions.ts          # Vim motion processor
├── useGameStatus/
│   ├── types.ts                  # GameStatus, GameStatusManager
│   └── useGameStatus.ts          # Game lifecycle
└── useScore/
    ├── types.ts                  # ScoreManager (mocked for now)
    └── useScore.ts               # Scoring (mocked for now)

Current State

• Board: 9x9 grid, puzzle generation working
• Cursor: Full vim motions + edit mode state machine
• Mode: 'normal' | 'edit' with proper validation
• Visual: All feedback working (blue/yellow/red)

Phase 40.3.3: Digit Entry (NEXT TASK)

Goal

Allow user to type digits 1-9 when in edit mode to fill cells.

Requirements

When in Edit Mode:

1. User can type digits 1-9
2. Digit gets written to the current cell
3. Board state updates (needs board integration)
4. Cell shows digit with .user-entered class
5. Stay in edit mode after entering digit (don't auto-exit)
6. Pressing Escape exits edit mode

When in Normal Mode: 7. Digits 0-9 are count prefixes (already working) 8. No digit entry allowed

Implementation Strategy

Step 1: Board State Management

• useBoard needs to track current board state (not just initial)
• Add boardRef with current puzzle state
• Add method: setCell(row, col, value) to update board
• Re-render board after cell update

Step 2: Update useCursor

• In edit mode, detect digit keys (1-9)
• Call board's setCell() to update state
• Trigger board re-render
• Stay in edit mode (don't exit)

Step 3: Integration

• Pass board methods to useCursor
• Ensure re-render updates cell classes correctly
• User-entered cells get .user-entered class

Key Considerations

Board Representation:

• Board stored as 81-char string in boardRef.current
• '.' for empty, '1'-'9' for filled
• initialBoardRef keeps original puzzle (immutable)
• solutionRef keeps solution (for validation later)

Cell Updates:

// In useBoard
function setCell(row: number, col: number, value: string): void {
  const board = boardRef.current.split('');
  const index = row * 9 + col;
  board[index] = value;
  boardRef.current = board.join('');
  renderBoard(); // Re-render to show change
}

Passing to useCursor:

// In useGame
const cursor = useCursor(gameStatusManager, containerRef, board.setCell);

Testing Checklist

• Press i on empty cell → edit mode
• Type '5' → Cell shows 5
• Cell has .user-entered class
• Escape → normal mode
• Navigate to another cell → first cell still shows 5
• Press i on given cell → red flash (no edit)
• In normal mode, type '5j' → moves down 5 (count works)

Important Notes

Agent Rules (from AGENTS.md)

• No useCallback or useMemo (React 19 compiler handles it)
• No comments unless explicitly requested
• Type-first approach: Define types before implementation
• Follow existing patterns: Look at vim-maze and current code
• Update IMPLEMENTATION.md: After completing the phase

Code Conventions

• Plain functions, not wrapped in hooks
• Explicit import type for types
• Refs for non-reactive state, useState for reactive
• Clean, minimal whitespace
• Descriptive names (no data, item, etc.)

Git Workflow

• Small, focused commits
• Clear commit messages (what, why)
• Update IMPLEMENTATION.md with each phase
• Test builds before committing

How to Start

1. Read the files I mentioned at the top
2. Review latest git commits: git log --oneline -10
3. Confirm understanding of current state
4. Ask me if anything is unclear
5. Start implementing Phase 40.3.3 step by step

Let's implement digit entry slowly and carefully, testing at each step!

---

Quick Reference

Current Mode State: In useCursor.ts

const [mode, setMode] = useState<CursorMode>('normal');

Edit Mode Check: In keyboard handler

if (mode === 'edit') {
  if (key === 'Escape') setMode('normal');
  // Add digit handling here (1-9)
  return;
}

Board String Format:

"52...8.4....7...4......6.....8.....3.9....8..1...2.......2....6...3....7..8...9."
// 81 characters: digits for givens, '.' for empty

Ready to continue! 🚀