@nayan-ui/games 1.19.0 → 1.20.0

package/src/games/sudoku/SudokuGame.ts

@@ -0,0 +1,250 @@
+// Sudoku's play, with no React: build a game with `createGame`, give it a layout, `start` it and `tick`
+// it every frame. Tap a cell to select it, then a number key to place that number there: right scores
+// 200 (and 500 more for each row, column or box it completes), wrong shows red until replaced. Fill
+// every cell inside fifteen minutes to win (a 5,000 bonus, then scored by the time it took).
+//
+// The puzzle and scoring are the original service's and store's (SudokuRules.ts).
+import { type Camera, type DragEvent, World } from '@nayan-ui/engine';
+import { calculateTimeBasedScore } from '../../services/ScoringService';
+import type { GameTheme } from '../../services/ThemeService';
+import { aimTilted, unproject } from '../shared/EngineTilt';
+import { cellAt, keyAt, type Layout, TAP_SLOP, TIME_LIMIT } from './SudokuConstants';
+import { completedUnits, newPuzzle, POINTS_PER_CORRECT, type Puzzle, remaining, WIN_BONUS } from './SudokuRules';
+import {
+  buildScene,
+  celebrate,
+  cellTop,
+  drawGrid,
+  drawKeys,
+  flash,
+  type Highlight,
+  keyTop,
+  pressKey,
+  removeScene,
+  type Scene,
+  setSceneTheme,
+  shakeCell
+} from './SudokuScene';
+
+export type Phase = 'ready' | 'playing' | 'over';
+/** place: a right number; wrong: a wrong one; win / lose: how it ended. */
+export type GameEvent = 'place' | 'wrong' | 'win' | 'lose';
+
+const WORLD_CAPACITY = 400; // 81 cells and their digits, nine keys with theirs, the board, and the confetti
+
+export function createGame(theme: GameTheme) {
+  const world = new World(WORLD_CAPACITY);
+  const camera: Camera = { eye: [0, 0, 240], target: [0, 0, 0], fov: 1, ortho: 1 };
+  const g = {
+    world,
+    camera,
+    theme,
+    layout: null as Layout | null,
+    scene: null as Scene | null,
+    phase: 'ready' as Phase,
+    puzzle: newPuzzle() as Puzzle,
+    filled: 0,
+    selRow: -1,
+    selCol: -1,
+    /** Score and the countdown live in the engine (Rust), advanced by world.update. */
+    get score() {
+      return world.scoreboard.score;
+    },
+    get timeLeft() {
+      return world.scoreboard.shownSeconds;
+    },
+    won: false,
+    /** A finger down: where, and on which key (0 on the board). */
+    press: null as { x: number; y: number; key: number } | null,
+    // UI hooks, set by the screen.
+    onPhase: (_p: Phase) => {},
+    onScore: (_s: number) => {},
+    onTime: (_t: number) => {},
+    onEvent: (_e: GameEvent) => {}
+  };
+  world.scoreboard.reset(0, TIME_LIMIT);
+  world.scoreboard.handlers = {
+    onSecond: (t) => g.onTime(t),
+    onTimeUp: () => g.phase === 'playing' && end(g, false)
+  };
+  return g;
+}
+export type Game = ReturnType<typeof createGame>;
+
+/** How a cell is highlighted, by the original board's priorities (selected, then same number, then row / column / box). */
+function highlighter(g: Game) {
+  const { selRow: sr, selCol: sc } = g;
+  const sel = sr >= 0 && sc >= 0 ? g.puzzle.grid[sr]![sc]!.value : 0;
+  return (r: number, c: number): Highlight => {
+    if (r === sr && c === sc) return 'selected';
+    if (sel > 0 && g.puzzle.grid[r]![c]!.value === sel) return 'same';
+    if (sr >= 0 && (r === sr || c === sc || (Math.floor(r / 3) === Math.floor(sr / 3) && Math.floor(c / 3) === Math.floor(sc / 3)))) return 'peer';
+    return 'none';
+  };
+}
+
+function draw(g: Game, pop = -1) {
+  const { layout: l, scene: s } = g;
+  if (!l || !s) return;
+  drawGrid(g.world, l, s, g.puzzle.grid, highlighter(g), pop);
+  drawKeys(g.world, l, s, remaining(g.puzzle));
+}
+
+// ── Scene ─────────────────────────────────────────────────────────────
+
+/** Lays the board out for the view (first layout, header height, rotation): rebuilt where things stand. */
+export function setLayout(g: Game, l: Layout) {
+  if (g.scene) removeScene(g.world, g.scene);
+  g.layout = l;
+  aimTilted(g.camera, l);
+  g.scene = buildScene(g.world, l, g.theme);
+  draw(g);
+}
+
+export function setTheme(g: Game, theme: GameTheme) {
+  g.theme = theme;
+  if (g.layout && g.scene) setSceneTheme(g.world, g.layout, g.scene, theme);
+}
+
+// ── Run ───────────────────────────────────────────────────────────────
+
+/** Starts on the puzzle already shown, nothing selected. */
+export function start(g: Game) {
+  if (g.phase !== 'ready') return;
+  g.world.scoreboard.reset();
+  g.world.scoreboard.startCountdown(TIME_LIMIT);
+  g.filled = 0;
+  g.won = false;
+  g.selRow = g.selCol = -1;
+  g.phase = 'playing';
+  draw(g);
+  g.onScore(0);
+  g.onTime(TIME_LIMIT);
+  g.onPhase('playing');
+}
+
+/** A fresh puzzle, not started (Stop, Play Again, as the original game). */
+export function reset(g: Game) {
+  g.puzzle = newPuzzle();
+  g.filled = 0;
+  g.selRow = g.selCol = -1;
+  g.world.scoreboard.reset(0, TIME_LIMIT);
+  g.won = false;
+  g.press = null;
+  g.phase = 'ready';
+  if (g.layout) setLayout(g, g.layout);
+  g.onScore(0);
+  g.onTime(TIME_LIMIT);
+  g.onPhase('ready');
+}
+
+export function dispose(g: Game) {
+  g.world.dispose();
+}
+
+export function tick(g: Game, dt: number) {
+  if (g.world.isDisposed) return;
+  g.world.update(dt);
+}
+
+function end(g: Game, won: boolean) {
+  g.world.scoreboard.stop();
+  g.won = won;
+  g.phase = 'over';
+  if (g.press?.key && g.layout && g.scene) pressKey(g.world, g.layout, g.scene, g.press.key, false);
+  g.press = null;
+  g.onPhase('over');
+  g.onEvent(won ? 'win' : 'lose');
+}
+
+// ── Moves ─────────────────────────────────────────────────────────────
+
+/** Selects a cell (any cell, given or not). */
+export function select(g: Game, row: number, col: number) {
+  if (g.phase !== 'playing') return;
+  g.selRow = row;
+  g.selCol = col;
+  draw(g);
+}
+
+/** Places a number in the selected cell (not a given one): checked against the solution and scored. */
+export function enter(g: Game, n: number) {
+  if (g.phase !== 'playing' || g.selRow < 0 || g.selCol < 0) return;
+  const { selRow: r, selCol: c } = g;
+  const cell = g.puzzle.grid[r]![c]!;
+  const answer = g.puzzle.solution[r]![c]!;
+  // Given, or already right (re-entering it would score and count it twice)
+  if (cell.given || (cell.value === answer && !cell.error)) return;
+  const right = n === answer;
+  cell.value = n;
+  cell.error = !right;
+  const { layout: l, scene: s } = g;
+  const i = r * 9 + c;
+  if (!right) {
+    draw(g, i);
+    if (l && s) shakeCell(g.world, l, s, i);
+    g.onEvent('wrong');
+    return;
+  }
+  g.filled += 1;
+  g.world.scoreboard.add(POINTS_PER_CORRECT);
+  const units = completedUnits(g.puzzle, r, c);
+  g.world.scoreboard.add(units.points);
+  draw(g, i);
+  if (units.cells.length && l && s) flash(g.world, l, s, units.cells, i);
+  g.onEvent('place');
+  if (g.filled >= g.puzzle.toFill) {
+    if (l && s) {
+      flash(
+        g.world,
+        l,
+        s,
+        Array.from({ length: 81 }, (_, k) => k),
+        i
+      );
+      celebrate(g.world, l);
+    }
+    g.world.scoreboard.add(WIN_BONUS);
+    g.world.scoreboard.set(calculateTimeBasedScore(TIME_LIMIT - g.timeLeft, TIME_LIMIT, g.score));
+    g.onScore(g.score);
+    end(g, true);
+    return;
+  }
+  g.onScore(g.score);
+}
+
+// ── The finger ────────────────────────────────────────────────────────
+
+/** What's under a view point: a number key (1..9), a cell, or nothing. */
+export function hitAt(g: Game, x: number, y: number): { key: number } | { cell: [number, number] } | null {
+  const l = g.layout;
+  if (!l) return null;
+  const [kx, ky] = unproject(l, x, y, keyTop(l));
+  const key = keyAt(l, kx, ky);
+  if (key) return { key };
+  const [cx, cy] = unproject(l, x, y, cellTop(l));
+  const cell = cellAt(l, cx, cy);
+  return cell ? { cell } : null;
+}
+
+/** A finger down presses a key in; a tap (lifting without wandering) selects a cell or enters a number. */
+export function drag(g: Game, { phase, x, y }: DragEvent) {
+  const { layout: l, scene: s } = g;
+  if (phase === 'start') {
+    const hit = g.phase === 'playing' ? hitAt(g, x, y) : null;
+    const key = hit && 'key' in hit ? hit.key : 0;
+    g.press = hit ? { x, y, key } : null;
+    if (key && l && s) pressKey(g.world, l, s, key, true);
+    return;
+  }
+  const p = g.press;
+  if (!p) return;
+  const far = Math.hypot(x - p.x, y - p.y) > TAP_SLOP;
+  if (phase !== 'end' && !far) return;
+  g.press = null;
+  if (p.key && l && s) pressKey(g.world, l, s, p.key, false);
+  if (phase !== 'end' || far) return;
+  if (p.key) return enter(g, p.key);
+  const hit = hitAt(g, x, y);
+  if (hit && 'cell' in hit) select(g, hit.cell[0], hit.cell[1]);
+}

package/src/games/sudoku/SudokuRules.ts

@@ -0,0 +1,125 @@
+// Sudoku's rules, with no React or engine: the solved board (random diagonal boxes, then row-major
+// backtracking with shuffled candidates and dead-end pruning), the puzzle (36 clues left at random),
+// placing a number (scored, and checked against the solution), and the row / column / box bonuses.
+// Ported from the original service and store (games/sudoku), with the same random draws, so a seed gives
+// the same puzzle.
+
+export const POINTS_PER_CORRECT = 200;
+export const POINTS_PER_UNIT = 500; // a completed row, column or box
+export const WIN_BONUS = 5000;
+export const CLUES = 36;
+
+export type Cell = { value: number; given: boolean; error: boolean };
+export type Puzzle = { grid: Cell[][]; solution: number[][]; toFill: number };
+
+const DIGITS = [1, 2, 3, 4, 5, 6, 7, 8, 9];
+const ALL_DIGITS = 0x3fe; // bits 1..9
+const BOX_OF = Array.from({ length: 81 }, (_, i) => Math.floor(i / 27) * 3 + Math.floor((i % 9) / 3));
+
+function shuffle<T>(arr: T[]): T[] {
+  const a = [...arr];
+  for (let i = a.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [a[i], a[j]] = [a[j]!, a[i]!];
+  }
+  return a;
+}
+
+function deadCell(cells: Uint8Array, rows: Uint16Array, cols: Uint16Array, boxes: Uint16Array, from: number) {
+  for (let i = from; i < 81; i++) if (cells[i] === 0 && (rows[(i / 9) | 0]! | cols[i % 9]! | boxes[BOX_OF[i]!]!) === ALL_DIGITS) return true;
+  return false;
+}
+
+function solve(cells: Uint8Array, rows: Uint16Array, cols: Uint16Array, boxes: Uint16Array, from: number): boolean {
+  let i = from;
+  while (i < 81 && cells[i] !== 0) i++;
+  if (i === 81) return true;
+  const r = (i / 9) | 0;
+  const c = i % 9;
+  const b = BOX_OF[i]!;
+  for (const n of shuffle(DIGITS)) {
+    const bit = 1 << n;
+    if ((rows[r]! | cols[c]! | boxes[b]!) & bit) continue;
+    cells[i] = n;
+    rows[r]! |= bit;
+    cols[c]! |= bit;
+    boxes[b]! |= bit;
+    if (!deadCell(cells, rows, cols, boxes, i + 1) && solve(cells, rows, cols, boxes, i + 1)) return true;
+    cells[i] = 0;
+    rows[r]! &= ~bit;
+    cols[c]! &= ~bit;
+    boxes[b]! &= ~bit;
+  }
+  return false;
+}
+
+function solvedBoard(): number[][] {
+  const cells = new Uint8Array(81);
+  const rows = new Uint16Array(9);
+  const cols = new Uint16Array(9);
+  const boxes = new Uint16Array(9);
+  for (let box = 0; box < 9; box += 3) {
+    const nums = shuffle(DIGITS);
+    let k = 0;
+    for (let r = box; r < box + 3; r++)
+      for (let c = box; c < box + 3; c++) {
+        const n = nums[k++]!;
+        const bit = 1 << n;
+        cells[r * 9 + c] = n;
+        rows[r]! |= bit;
+        cols[c]! |= bit;
+        boxes[BOX_OF[r * 9 + c]!]! |= bit;
+      }
+  }
+  solve(cells, rows, cols, boxes, 0);
+  return Array.from({ length: 9 }, (_, r) => Array.from(cells.subarray(r * 9, r * 9 + 9)));
+}
+
+/** A fresh puzzle: a solved board with all but 36 cells emptied, at random. */
+export function newPuzzle(): Puzzle {
+  const solution = solvedBoard();
+  const grid: Cell[][] = solution.map((row) => row.map((value) => ({ value, given: true, error: false })));
+  const positions = shuffle(Array.from({ length: 81 }, (_, i) => ({ row: Math.floor(i / 9), col: i % 9 })));
+  for (const p of positions.slice(0, 81 - CLUES)) {
+    grid[p.row]![p.col]!.value = 0;
+    grid[p.row]![p.col]!.given = false;
+  }
+  return { grid, solution, toFill: 81 - CLUES };
+}
+
+/** The cells of the row, column and box through (row, col) that are now all solved, each unit once, and the points for them. */
+export function completedUnits(p: Puzzle, row: number, col: number): { cells: number[]; points: number } {
+  const ok = (r: number, c: number) => p.grid[r]![c]!.value === p.solution[r]![c];
+  const cells = new Set<number>();
+  let points = 0;
+  let rowComplete = true,
+    colComplete = true;
+  for (let i = 0; i < 9; i++) {
+    if (!ok(row, i)) rowComplete = false;
+    if (!ok(i, col)) colComplete = false;
+  }
+  if (rowComplete) {
+    points += POINTS_PER_UNIT;
+    for (let c = 0; c < 9; c++) cells.add(row * 9 + c);
+  }
+  if (colComplete) {
+    points += POINTS_PER_UNIT;
+    for (let r = 0; r < 9; r++) cells.add(r * 9 + col);
+  }
+  const br = Math.floor(row / 3) * 3;
+  const bc = Math.floor(col / 3) * 3;
+  let box = true;
+  for (let r = br; r < br + 3; r++) for (let c = bc; c < bc + 3; c++) if (!ok(r, c)) box = false;
+  if (box) {
+    points += POINTS_PER_UNIT;
+    for (let r = br; r < br + 3; r++) for (let c = bc; c < bc + 3; c++) cells.add(r * 9 + c);
+  }
+  return { cells: [...cells], points };
+}
+
+/** How many of each digit are still to place (9 minus the right-looking ones on the board), as the original pad counted. */
+export function remaining(p: Puzzle): number[] {
+  const counts = [0, 9, 9, 9, 9, 9, 9, 9, 9, 9];
+  for (const row of p.grid) for (const cell of row) if (cell.value > 0 && !cell.error) counts[cell.value] = Math.max(0, counts[cell.value]! - 1);
+  return counts;
+}

package/src/games/sudoku/SudokuScene.ts

@@ -0,0 +1,304 @@
+// Everything Sudoku draws: the board (a wooden board in the classic theme, the theme's board
+// otherwise) with the grid's navy lines showing between 81 raised cells, each tinted as the original
+// cells were (given, selected, same number, same row / column / box, wrong), the digits standing on
+// them in 3D strokes, and a row of nine wooden number keys under the board, each with how many of its
+// digit are left. Seen from a little in front of straight down (shared/EngineTilt: an orthographic
+// camera leaning back, one world unit per point). Cells, keys and each digit share a mesh apiece.
+import { type Color, effects, type Entity, extrude, type Model, Path, type World } from '@nayan-ui/engine';
+import type { GameTheme } from '../../services/ThemeService';
+import { setBackdropTheme, spawnBackdrop } from '../shared/EngineBackdrop';
+import { spawnRaisedBlock } from '../shared/EngineBlocks';
+import { flatGlyphMesh } from '../shared/EngineGlyphs';
+import { cacheGameAsset, createGameMesh as createShape } from '../shared/EngineMeshes';
+import { placeTiltedBackdrop } from '../shared/EngineTilt';
+import { toColor } from '../shared/EngineUtils';
+import { CELL_HEIGHT, cellCentre, COLORS, FLASH_STEP, KEY_HEIGHT, keyCentre, type Layout } from './SudokuConstants';
+import type { Cell } from './SudokuRules';
+
+const meshes = new Map<string, Model>();
+const cached = (key: string, build: () => Model) => {
+  let m = meshes.get(key);
+  if (!m) {
+    m = cacheGameAsset('sudoku/SudokuScene:' + key, build);
+    meshes.set(key, m);
+  }
+  return m;
+};
+const BOARD_DEPTH = 10;
+const BACKDROP_DEPTH = 30;
+const SURFACE = 1; // where the cells and keys stand
+
+const panelMesh = (w: number, h: number, radius: number, depth: number) =>
+  cached(`sd-panel:${w}:${h}:${radius}:${depth}`, () =>
+    createShape(extrude(new Path().addRoundedRect(-w / 2, -h / 2, w, h, radius), { depth }), { shine: 0 })
+  );
+
+/** How a cell reads: selected, wrong, sharing the selected number, in the selected cell's row / column / box, or none. */
+export type Highlight = 'selected' | 'same' | 'peer' | 'none';
+
+const cellColor = (cell: Cell, hl: Highlight): Color =>
+  toColor(
+    hl === 'selected'
+      ? COLORS.SELECTED
+      : cell.error
+        ? COLORS.ERROR
+        : hl === 'same'
+          ? COLORS.SAME_NUMBER
+          : hl === 'peer'
+            ? COLORS.PEER
+            : cell.given
+              ? COLORS.GIVEN
+              : COLORS.CELL
+  );
+const digitColor = (cell: Cell): Color => toColor(cell.error ? COLORS.TEXT_ERROR : cell.given ? COLORS.TEXT_GIVEN : COLORS.TEXT_PLACED);
+
+// ── Spawning ──────────────────────────────────────────────────────────
+
+type Key = { root: Entity; block: Entity; digit: Entity; count: Entity };
+export type Scene = {
+  backdrop: Entity;
+  board: Entity[];
+  cells: Entity[];
+  /** The digit on each cell (null while empty), and what it shows. */
+  digits: (Entity | null)[];
+  shown: string[];
+  selected: number;
+  keys: Key[];
+  keyCounts: number[];
+};
+
+/** A key's digit size, and its count's. */
+const keyDigit = (l: Layout) => Math.min(l.key * 0.5, l.keyH * 0.4);
+/** A cell's digit, of the cell: printed flat on its face. */
+const DIGIT = 0.5;
+const cellHeight = (l: Layout, selected: boolean) => l.cell * CELL_HEIGHT * (selected ? 1.8 : 1);
+
+const cellTop = (l: Layout) => SURFACE + l.cell * CELL_HEIGHT;
+const keyTop = (l: Layout) => SURFACE + l.key * KEY_HEIGHT;
+
+function spawnBoard(world: World, l: Layout, theme: GameTheme): Entity[] {
+  const classic = theme.mode === 'classic';
+  const out = [
+    world.spawn({
+      mesh: panelMesh(l.board, l.board, classic ? 14 : 8, BOARD_DEPTH),
+      position: [0, l.boardY, -BOARD_DEPTH / 2],
+      color: toColor(classic ? COLORS.FRAME : theme.BOARD.SURFACE),
+      pickable: false
+    }),
+    // Under the cells, showing between them as the thin lines and thick box borders: the theme's grid color (navy on classic)
+    world.spawn({
+      mesh: panelMesh(l.grid, l.grid, 4, 1),
+      position: [0, l.boardY, 0.5],
+      color: toColor(classic ? COLORS.LINES : theme.BOARD.GRID_LINE),
+      pickable: false
+    })
+  ];
+  if (classic)
+    out.push(
+      world.spawn({ mesh: panelMesh(l.grid + 6, l.grid + 6, 8, 1), position: [0, l.boardY, 0.2], color: toColor(COLORS.WELL), pickable: false })
+    );
+  return out;
+}
+
+export function buildScene(world: World, l: Layout, theme: GameTheme): Scene {
+  const backdrop = spawnBackdrop(world, l.width, l.height, -BACKDROP_DEPTH, theme);
+  placeTiltedBackdrop(world, backdrop, l, BACKDROP_DEPTH);
+  const h = l.cell * CELL_HEIGHT;
+  const cells: Entity[] = [];
+  for (let r = 0; r < 9; r++)
+    for (let c = 0; c < 9; c++) {
+      const [x, y] = cellCentre(l, r, c);
+      cells.push(
+        // A matte bevelled block, as 2048's (square, so its scale is its size)
+        spawnRaisedBlock(world, {
+          position: [x, y, SURFACE + h / 2],
+          size: [l.cell, l.cell, h],
+          color: toColor(COLORS.CELL),
+          gloss: false,
+          shadow: false
+        })
+      );
+    }
+  const keys: Key[] = [];
+  const kh = l.key * KEY_HEIGHT;
+  for (let n = 1; n <= 9; n++) {
+    const [x, y] = keyCentre(l, n);
+    const root = world.spawn({ mesh: 'none', position: [x, y, SURFACE], pickable: false });
+    const block = spawnRaisedBlock(world, {
+      parent: root,
+      position: [0, 0, kh / 2],
+      size: [l.key, l.keyH, kh],
+      color: toColor(COLORS.KEY),
+      gloss: false,
+      shadow: false
+    });
+    const big = keyDigit(l);
+    const digit = world.spawn({
+      mesh: flatGlyphMesh(String(n)),
+      parent: root,
+      position: [0, l.keyH * 0.1, kh + 0.6],
+      scale: big,
+      color: toColor(COLORS.KEY_TEXT),
+      pickable: false
+    });
+    const small = big * 0.42;
+    const count = world.spawn({
+      mesh: flatGlyphMesh('9'),
+      parent: root,
+      position: [0, -l.keyH * 0.32, kh + 0.6],
+      scale: small,
+      color: toColor(COLORS.KEY_REMAINING),
+      pickable: false
+    });
+    keys.push({ root, block, digit, count });
+  }
+  const s: Scene = {
+    backdrop,
+    board: spawnBoard(world, l, theme),
+    cells,
+    digits: Array(81).fill(null),
+    shown: Array(81).fill(''),
+    selected: -1,
+    keys,
+    keyCounts: Array(9).fill(-1)
+  };
+  return s;
+}
+
+export function removeScene(world: World, s: Scene) {
+  for (const e of [s.backdrop, ...s.board, ...s.cells, ...s.digits, ...s.keys.map((k) => k.root)]) if (e != null) world.despawn(e);
+}
+
+export function setSceneTheme(world: World, l: Layout, s: Scene, theme: GameTheme) {
+  setBackdropTheme(world, s.backdrop, theme);
+  for (const e of s.board) world.despawn(e);
+  s.board = spawnBoard(world, l, theme);
+}
+
+// ── Drawing the board's state ─────────────────────────────────────────
+
+/**
+ * Brings every cell up to date: its tint for the highlight, and its digit (spawned, recolored or
+ * removed only where it changed). `pop` is the cell just placed: its digit drops in.
+ */
+export function drawGrid(world: World, l: Layout, s: Scene, grid: Cell[][], highlight: (r: number, c: number) => Highlight, pop = -1) {
+  const size = l.cell * DIGIT;
+  s.selected = -1;
+  for (let r = 0; r < 9; r++)
+    for (let c = 0; c < 9; c++) {
+      const i = r * 9 + c;
+      const cell = grid[r]![c]!;
+      const hl = highlight(r, c);
+      const [x, y] = cellCentre(l, r, c);
+      const h = cellHeight(l, hl === 'selected');
+      const z = SURFACE + h + 0.6;
+      if (hl === 'selected') s.selected = i;
+      // A new selection or entry supersedes any completion hop still moving this cell.
+      world.stopAnimation(s.cells[i]!);
+      world.set(s.cells[i]!, { color: cellColor(cell, hl), position: [x, y, SURFACE + h / 2], scale: [l.cell, l.cell, h] });
+      const key = cell.value ? `${cell.value}:${cell.given}:${cell.error}` : '';
+      if (key !== s.shown[i]) {
+        const old = s.digits[i];
+        if (old != null) world.despawn(old);
+        s.digits[i] = null;
+        if (cell.value) {
+          const e = world.spawn({
+            mesh: flatGlyphMesh(String(cell.value)),
+            position: [x, y, z],
+            scale: size,
+            color: digitColor(cell),
+            pickable: false
+          });
+          if (i === pop) {
+            world.set(e, { scale: size * 0.2, position: [x, y, z + l.cell * 0.5] });
+            world.animate(e, { scale: size, position: [x, y, z] }, { duration: 0.22, easing: 'back' });
+          }
+          s.digits[i] = e;
+        }
+        s.shown[i] = key;
+      } else if (s.digits[i] != null) {
+        world.stopAnimation(s.digits[i]!);
+        world.set(s.digits[i]!, { position: [x, y, z], scale: size });
+      }
+    }
+}
+
+/** The keys' counts of digits left, greyed out at none. */
+export function drawKeys(world: World, l: Layout, s: Scene, counts: number[]) {
+  const small = keyDigit(l) * 0.42;
+  s.keys.forEach((k, i) => {
+    const left = counts[i + 1]!;
+    if (s.keyCounts[i] === left) return;
+    s.keyCounts[i] = left;
+    world.set(k.block, { color: toColor(left > 0 ? COLORS.KEY : COLORS.KEY_DISABLED) });
+    world.set(k.digit, { color: toColor(left > 0 ? COLORS.KEY_TEXT : COLORS.KEY_DISABLED_TEXT) });
+    world.set(k.count, { mesh: flatGlyphMesh(String(left)), scale: left > 0 ? small : 0.001 });
+  });
+}
+
+/** A key pressed down into the board while touched. */
+export function pressKey(world: World, l: Layout, s: Scene, n: number, down: boolean) {
+  const k = s.keys[n - 1];
+  if (!k) return;
+  const [x, y] = keyCentre(l, n);
+  world.animate(
+    k.root,
+    { position: [x, y, SURFACE - (down ? l.key * KEY_HEIGHT * 0.55 : 0)] },
+    { duration: down ? 0.06 : 0.12, easing: down ? 'easeOut' : 'back' }
+  );
+}
+
+// ── Feedback ──────────────────────────────────────────────────────────
+
+/** A wrong number: the cell shakes. */
+export function shakeCell(world: World, l: Layout, s: Scene, i: number) {
+  world.animate(s.cells[i]!, { shake: l.cell * 0.12 }, { duration: 0.28 });
+  const d = s.digits[i];
+  if (d != null) world.animate(d, { shake: l.cell * 0.12 }, { duration: 0.28 });
+}
+
+/** A completed row / column / box (or the whole board): its cells hop and flash in a sweep from `origin`. */
+export function flash(world: World, l: Layout, s: Scene, cells: number[], origin: number) {
+  const or = Math.floor(origin / 9);
+  const oc = origin % 9;
+  for (const i of cells) {
+    const h = cellHeight(l, i === s.selected);
+    const r = Math.floor(i / 9);
+    const c = i % 9;
+    const [x, y] = cellCentre(l, r, c);
+    const delay = Math.max(Math.abs(r - or), Math.abs(c - oc)) * FLASH_STEP;
+    world.animate(s.cells[i]!, [{ position: [x, y, SURFACE + h / 2 + l.cell * 0.3], at: 0.35 }, { position: [x, y, SURFACE + h / 2] }], {
+      duration: 0.4,
+      delay,
+      easing: 'easeOut'
+    });
+    const d = s.digits[i];
+    if (d != null) {
+      const size = l.cell * DIGIT;
+      const z = SURFACE + h + 0.6;
+      world.animate(
+        d,
+        [
+          { position: [x, y, z + l.cell * 0.3], scale: size * 1.2, at: 0.35 },
+          { position: [x, y, z], scale: size }
+        ],
+        { duration: 0.4, delay, easing: 'easeOut' }
+      );
+    }
+  }
+}
+
+/** Solved: confetti over the board. */
+export function celebrate(world: World, l: Layout) {
+  effects.confetti(world, {
+    position: [0, l.boardY, l.cell * 2],
+    count: 70,
+    size: l.cell * 0.2,
+    speed: l.board * 1.3,
+    lifetime: 1.4,
+    gravity: -l.board * 2.2,
+    colors: ['#FFD700', '#4CAF50', '#2196F3', '#E74C3C'].map((c) => toColor(c))
+  });
+}
+
+export { keyTop, cellTop };