feat: implement Phase 10 - minimal skeleton with empty grid

Create clean src/ structure with minimal viable implementation:

Core Files:
- src/types.ts: Basic type definitions (Difficulty, GameStatus, GameManager)
- src/index.ts: Main package exports
- src/game.css: Copied from src_old for styling
- src/useGame.ts: Orchestrator with mocked GameManager API
- src/useBoard/useBoard.ts: Renders empty 9x9 sudoku grid

Implementation Details:
- useBoard renders 81 cells with sudoku-grid/sudoku-cell classes
- Each cell has data-r and data-c attributes for identification
- useGame provides full GameManager interface to satisfy example app
- Real implementations: gameStatus, keyLog tracking, game controls
- Mocked implementations: cursor ({}), scoreManager (zeros/null)
- Supports optional platformHook parameter

Build Status:
- TypeScript compiles cleanly with no errors
- Example app builds successfully
- Ready for browser testing with empty grid display

Phase 10 complete. Next: Phase 20 (full useBoard with puzzle generation).

IMPLEMENTATION.md

@@ -63,6 +63,82 @@ vim-sudoku/
 
 ---
 
-## Iteration 2: [Pending]
+## Iteration 2: Phase 10 - Minimal Skeleton
+
+**Date**: 2025-01-22
+
+### Goals
+- Create clean src/ directory structure
+- Implement minimal types
+- Build empty 9x9 grid rendering
+- Mock GameManager API for example app
+- Get visual feedback without errors
+
+### Tasks Completed
+
+#### 1. Created Core Structure
+```
+src/
+├── game.css              [COPIED] - From src_old
+├── index.ts              [CREATED] - Main exports
+├── types.ts              [CREATED] - Basic type definitions
+├── useGame.ts            [CREATED] - Orchestrator with mocks
+└── useBoard/
+    └── useBoard.ts       [CREATED] - Empty grid rendering
+```
+
+#### 2. Implemented Types (src/types.ts)
+- `Difficulty` - Puzzle difficulty levels
+- `GameStatus` - Game state machine states
+- `GameOptions` - useGame configuration
+- `GameManager` - Full API interface (mocked for now)
+- `KeyLogEntry` - Keystroke tracking
+
+#### 3. Implemented useBoard (src/useBoard/useBoard.ts)
+- `containerRef` - DOM reference
+- `renderBoard()` - Renders empty 9x9 sudoku grid
+- Creates proper HTML structure with `sudoku-grid` and `sudoku-cell` classes
+- Sets data attributes (data-r, data-c) for cell identification
+
+#### 4. Implemented useGame (src/useGame.ts)
+- Calls `useBoard()` for grid rendering
+- Returns full `GameManager` interface
+- Real implementations:
+  - `gameStatus` state management
+  - `startGame`, `togglePause`, `quitGame`
+  - `keyLog` tracking with `clearKeyLog`, `getKeyLog`
+- Mocked implementations:
+  - `cursor` (empty object)
+  - `scoreManager` (zeros and null)
+- Supports optional `platformHook` parameter
+
+#### 5. Verified Build
+- ✅ TypeScript compilation successful
+- ✅ Example app builds without errors
+- ✅ No runtime errors expected
+
+### Technical Details
+
+**Empty Grid Rendering**:
+- 81 cells (9x9) created with `sudoku-cell` class
+- Each cell has `data-r` and `data-c` attributes
+- Wrapped in `sudoku-grid` div inside `#sudoku` container
+- Uses CSS from src_old for styling
+
+**Mocking Strategy**:
+- Return full GameManager interface to satisfy example app
+- Mock methods do nothing (empty functions)
+- Mock values return defaults (0, null, empty arrays)
+- Real state management only for critical path (gameStatus)
+
+### Next Steps
+- Phase 20: Implement full useBoard with SudokuGenerator
+  - Port puzzle generation logic
+  - Add board state management
+  - Implement cell validation
+
+---
+
+## Iteration 3: [Pending]
 
 *To be filled as implementation progresses...*

src/game.css

@@ -0,0 +1,256 @@
+/* =========================================================
+   🔧 Controls (tweak these)
+   ========================================================= */
+:root {
+  --cell-size: 96px;
+  --cell-font-size: 48px;
+  --grid-gap: 6px;
+  --box-separator: 9px;
+}
+
+/* =========================================================
+   Container & Grid Base
+   ========================================================= */
+#sudoku_container {
+  position: relative;
+  margin: 1em auto;
+  width: fit-content;
+}
+
+#sudoku {
+  position: relative;
+  background-color: var(--card, #1e2030);
+  border-radius: 0.5rem;
+  box-shadow: 0 0 10px rgba(27, 29, 43, 0.6), inset 0 0 6px rgba(130, 170, 255, 0.05);
+  padding: 0.5rem;
+  width: fit-content;
+}
+
+/* =========================================================
+   Grid Layout
+   ========================================================= */
+#sudoku .sudoku-grid {
+  display: grid;
+  grid-template-columns: 
+    var(--cell-size) var(--cell-size) var(--cell-size)
+    var(--cell-size) var(--cell-size) var(--cell-size)
+    var(--cell-size) var(--cell-size) var(--cell-size);
+  grid-template-rows: 
+    var(--cell-size) var(--cell-size) var(--cell-size)
+    var(--cell-size) var(--cell-size) var(--cell-size)
+    var(--cell-size) var(--cell-size) var(--cell-size);
+  column-gap: var(--grid-gap);
+  row-gap: var(--grid-gap);
+  user-select: none;
+}
+
+/* =========================================================
+   Cell Base Styles
+   ========================================================= */
+#sudoku .sudoku-cell {
+  width: var(--cell-size);
+  height: var(--cell-size);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 4px;
+  font-family: "Fira Code", monospace;
+  font-size: var(--cell-font-size);
+  background: var(--muted, #2f334d);
+  color: var(--foreground, #c8d3f5);
+  transition: all 0.15s ease;
+  box-shadow: inset 0 0 3px rgba(27, 29, 43, 0.4);
+}
+
+/* =========================================================
+   3x3 Box Separators
+   ========================================================= */
+/* Right borders (end of each 3x3 box horizontally) */
+#sudoku .sudoku-cell[data-c="2"],
+#sudoku .sudoku-cell[data-c="5"],
+#sudoku .sudoku-cell[data-c="8"] {
+  border-right: 2px solid color-mix(in srgb, var(--primary, #82aaff) 30%, transparent);
+}
+
+/* Left borders (start of each 3x3 box horizontally) */
+#sudoku .sudoku-cell[data-c="0"],
+#sudoku .sudoku-cell[data-c="3"],
+#sudoku .sudoku-cell[data-c="6"] {
+  border-left: 2px solid color-mix(in srgb, var(--primary, #82aaff) 30%, transparent);
+}
+
+/* Bottom borders (end of each 3x3 box vertically) */
+#sudoku .sudoku-cell[data-r="2"],
+#sudoku .sudoku-cell[data-r="5"],
+#sudoku .sudoku-cell[data-r="8"] {
+  border-bottom: 2px solid color-mix(in srgb, var(--primary, #82aaff) 30%, transparent);
+}
+
+/* Top borders (start of each 3x3 box vertically) */
+#sudoku .sudoku-cell[data-r="0"],
+#sudoku .sudoku-cell[data-r="3"],
+#sudoku .sudoku-cell[data-r="6"] {
+  border-top: 2px solid color-mix(in srgb, var(--primary, #82aaff) 30%, transparent);
+}
+
+/* =========================================================
+   User-Entered Cells
+   ========================================================= */
+#sudoku .sudoku-cell.user-entered {
+  color: var(--primary, #82aaff);
+  font-weight: 600;
+}
+
+/* =========================================================
+   Active Cell Highlight (Navigation Mode)
+   ========================================================= */
+#sudoku .sudoku-cell.active {
+  outline: 2px solid var(--primary, #82aaff);
+  outline-offset: -2px;
+  background: color-mix(in srgb, var(--primary, #82aaff) 20%, var(--muted, #2f334d));
+  box-shadow: 
+    0 0 8px color-mix(in srgb, var(--primary, #82aaff) 40%, transparent),
+    0 0 12px color-mix(in srgb, var(--primary, #82aaff) 20%, transparent),
+    inset 0 0 6px color-mix(in srgb, var(--primary, #82aaff) 15%, transparent);
+}
+
+/* =========================================================
+   Editing Cell Highlight (Edit Mode)
+   ========================================================= */
+#sudoku .sudoku-cell.editing {
+  outline: 2px solid var(--accent, #ffc777);
+  outline-offset: -2px;
+  background: color-mix(in srgb, var(--accent, #ffc777) 15%, var(--muted, #2f334d));
+  box-shadow: 
+    0 0 16px color-mix(in srgb, var(--accent, #ffc777) 70%, transparent),
+    0 0 24px color-mix(in srgb, var(--accent, #ffc777) 40%, transparent),
+    inset 0 0 12px color-mix(in srgb, var(--accent, #ffc777) 30%, transparent);
+  animation: editing-cell-glow 1.5s ease-in-out infinite;
+}
+
+@keyframes editing-cell-glow {
+  0%, 100% {
+    box-shadow: 
+      0 0 16px color-mix(in srgb, var(--accent, #ffc777) 70%, transparent),
+      0 0 24px color-mix(in srgb, var(--accent, #ffc777) 40%, transparent),
+      inset 0 0 12px color-mix(in srgb, var(--accent, #ffc777) 30%, transparent);
+  }
+  50% {
+    box-shadow: 
+      0 0 20px color-mix(in srgb, var(--accent, #ffc777) 90%, transparent),
+      0 0 32px color-mix(in srgb, var(--accent, #ffc777) 60%, transparent),
+      inset 0 0 16px color-mix(in srgb, var(--accent, #ffc777) 40%, transparent);
+  }
+}
+
+/* =========================================================
+   Visual Feedback Effects
+   ========================================================= */
+/* Invalid move effect */
+#sudoku .sudoku-cell.invalid-move {
+  animation: sudoku-invalid-pulse 180ms ease-out;
+  box-shadow:
+    0 0 12px color-mix(in srgb, var(--destructive, #c53b53) 85%, transparent),
+    0 0 24px color-mix(in srgb, var(--destructive, #c53b53) 45%, transparent);
+}
+
+@keyframes sudoku-invalid-pulse {
+  0% {
+    transform: scale(1.05);
+    box-shadow:
+      0 0 16px color-mix(in srgb, var(--destructive, #c53b53) 95%, transparent),
+      0 0 28px color-mix(in srgb, var(--destructive, #c53b53) 55%, transparent);
+  }
+  100% {
+    transform: none;
+    box-shadow: none;
+  }
+}
+
+/* Locked cell effect (pre-filled clues) */
+#sudoku .sudoku-cell.locked-cell {
+  animation: sudoku-locked-pulse 300ms ease-out;
+}
+
+@keyframes sudoku-locked-pulse {
+  0% {
+    transform: scale(1.08);
+    background: rgba(255, 85, 85, 0.3);
+    box-shadow:
+      0 0 20px rgba(255, 85, 85, 0.9),
+      0 0 32px rgba(255, 85, 85, 0.6),
+      inset 0 0 16px rgba(255, 85, 85, 0.4);
+  }
+  50% {
+    transform: scale(1.05);
+    background: rgba(255, 85, 85, 0.2);
+    box-shadow:
+      0 0 16px rgba(255, 85, 85, 0.8),
+      0 0 28px rgba(255, 85, 85, 0.5),
+      inset 0 0 12px rgba(255, 85, 85, 0.3);
+  }
+  100% {
+    transform: none;
+    background: transparent;
+    box-shadow: none;
+  }
+}
+
+/* Trail effect for moves */
+#sudoku .sudoku-cell.trail {
+  box-shadow: 
+    inset 0 0 6px color-mix(in srgb, var(--primary, #82aaff) 60%, transparent), 
+    0 0 6px color-mix(in srgb, var(--primary, #82aaff) 35%, transparent);
+  animation: sudoku-trail-fade 220ms ease-out;
+}
+
+@keyframes sudoku-trail-fade {
+  from { background-color: color-mix(in srgb, var(--primary, #82aaff) 25%, transparent); }
+  to   { background-color: transparent; }
+}
+
+/* Valid move flash */
+#sudoku .sudoku-cell.valid-move {
+  animation: sudoku-valid-flash 300ms ease-out;
+}
+
+@keyframes sudoku-valid-flash {
+  0% {
+    background: color-mix(in srgb, var(--success, #4fd6be) 40%, transparent);
+    box-shadow:
+      0 0 12px color-mix(in srgb, var(--success, #4fd6be) 80%, transparent),
+      0 0 20px color-mix(in srgb, var(--success, #4fd6be) 50%, transparent),
+      inset 0 0 8px color-mix(in srgb, var(--success, #4fd6be) 35%, transparent);
+  }
+  100% {
+    background: transparent;
+    box-shadow: none;
+  }
+}
+
+/* Conflict highlighting */
+#sudoku .sudoku-cell.conflict {
+  outline: 2px solid var(--destructive, #c53b53);
+  outline-offset: -2px;
+  background: color-mix(in srgb, var(--destructive, #c53b53) 25%, var(--muted, #2f334d));
+  box-shadow:
+    0 0 10px color-mix(in srgb, var(--destructive, #c53b53) 70%, transparent),
+    0 0 18px color-mix(in srgb, var(--destructive, #c53b53) 40%, transparent),
+    inset 0 0 8px color-mix(in srgb, var(--destructive, #c53b53) 30%, transparent);
+  animation: sudoku-conflict-pulse 1s ease-in-out infinite;
+}
+
+@keyframes sudoku-conflict-pulse {
+  0%, 100% {
+    box-shadow:
+      0 0 10px color-mix(in srgb, var(--destructive, #c53b53) 70%, transparent),
+      0 0 18px color-mix(in srgb, var(--destructive, #c53b53) 40%, transparent),
+      inset 0 0 8px color-mix(in srgb, var(--destructive, #c53b53) 30%, transparent);
+  }
+  50% {
+    box-shadow:
+      0 0 14px color-mix(in srgb, var(--destructive, #c53b53) 85%, transparent),
+      0 0 24px color-mix(in srgb, var(--destructive, #c53b53) 55%, transparent),
+      inset 0 0 12px color-mix(in srgb, var(--destructive, #c53b53) 40%, transparent);
+  }
+}

src/index.ts

@@ -0,0 +1,2 @@
+export { useGame } from './useGame';
+export type { GameManager, GameOptions, GameStatus, Difficulty } from './types';

src/types.ts

@@ -0,0 +1,30 @@
+import type { RefObject } from 'react';
+
+export type Difficulty = 'easy' | 'medium' | 'hard' | 'very-hard' | 'insane' | 'inhuman';
+
+export type GameStatus = 'waiting' | 'started' | 'paused' | 'game-over' | 'game-won';
+
+export type GameOptions = {
+  difficulty?: Difficulty;
+};
+
+export type KeyLogEntry = { key: string; timestamp: number };
+
+export type GameManager = {
+  containerRef: RefObject<HTMLDivElement | null>;
+  renderBoard: () => void;
+  gameStatus: GameStatus;
+  setGameStatus: (status: GameStatus) => void;
+  startGame: () => void;
+  togglePause: (pause?: boolean) => void;
+  quitGame: () => void;
+  cursor: any;
+  scoreManager: {
+    timeValue: number;
+    keystrokes: number;
+    finalScore: number | null;
+  };
+  keyLog: KeyLogEntry[];
+  clearKeyLog: () => void;
+  getKeyLog: () => KeyLogEntry[];
+};

src/useBoard/useBoard.ts

@@ -0,0 +1,37 @@
+import { useRef } from 'react';
+
+export function useBoard() {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+
+  function renderBoard() {
+    const container = containerRef.current;
+    if (!container) return;
+
+    container.innerHTML = '';
+    
+    const sudokuDiv = document.createElement('div');
+    sudokuDiv.id = 'sudoku';
+
+    const grid = document.createElement('div');
+    grid.className = 'sudoku-grid';
+
+    for (let i = 0; i < 81; i++) {
+      const r = Math.floor(i / 9);
+      const c = i % 9;
+      const cell = document.createElement('div');
+      cell.className = 'sudoku-cell';
+      cell.dataset.r = String(r);
+      cell.dataset.c = String(c);
+      cell.textContent = '';
+      grid.appendChild(cell);
+    }
+
+    sudokuDiv.appendChild(grid);
+    container.appendChild(sudokuDiv);
+  }
+
+  return {
+    containerRef,
+    renderBoard,
+  };
+}

src/useGame.ts

@@ -0,0 +1,50 @@
+import { useState, useEffect } from 'react';
+import type { GameManager, GameOptions, GameStatus } from './types';
+import { useBoard } from './useBoard/useBoard';
+
+export function useGame(_options: GameOptions = {}, platformHook?: unknown): GameManager {
+  const board = useBoard();
+  const { containerRef, renderBoard } = board;
+  
+  const [gameStatus, setGameStatus] = useState<GameStatus>('waiting');
+  const [keyLog, setKeyLog] = useState<{ key: string; timestamp: number }[]>([]);
+
+  useEffect(() => {
+    renderBoard();
+  }, []);
+
+  const gameManager: GameManager = {
+    containerRef,
+    renderBoard,
+    gameStatus,
+    setGameStatus,
+    startGame: () => {
+      setGameStatus('started');
+    },
+    togglePause: (pause?: boolean) => {
+      if (typeof pause === 'boolean') {
+        setGameStatus(pause ? 'paused' : 'started');
+      } else {
+        setGameStatus(prev => prev === 'paused' ? 'started' : 'paused');
+      }
+    },
+    quitGame: () => {
+      setGameStatus('waiting');
+    },
+    cursor: {},
+    scoreManager: {
+      timeValue: 0,
+      keystrokes: 0,
+      finalScore: null,
+    },
+    keyLog,
+    clearKeyLog: () => setKeyLog([]),
+    getKeyLog: () => [...keyLog],
+  };
+
+  if (typeof platformHook === 'function') {
+    platformHook(gameManager);
+  }
+
+  return gameManager;
+}