@nayan-ui/games 1.20.0 → 1.21.0

package/src/games/pipe-connect/PipeConnectConstants.ts

@@ -1,101 +0,0 @@
-// Pipe Connect's rules, pieces, timings and layout. Rules, puzzles and scoring match the original version
-// (games/pipe-connect), so scores carry over.
-import { getScoreBoardTop } from '../shared/EngineHud';
-import type { TiltView } from '../shared/EngineTilt';
-import { frontLight, gameWidthFor } from '../shared/EngineUtils';
-
-// ── Rules ─────────────────────────────────────────────────────────────
-
-export const TIME_LIMIT = 120; // seconds
-export const POINTS_PER_PUZZLE = 5000; // the base calculateTimeBasedScore adds the time bonus to
-
-/** The grid is 7 x 7 on a phone, 8 x 8 on a tablet (as the original game decided it). */
-export const gridSizeFor = (tablet: boolean) => (tablet ? 8 : 7);
-
-export enum PipeType {
-  EMPTY = 'empty',
-  STRAIGHT = 'straight',
-  CORNER = 'corner',
-  CROSS = 'cross',
-  T_SHAPE = 't-shape',
-  SOURCE = 'source',
-  SINK = 'sink'
-}
-
-/** Open sides, as a bitmask. */
-export const DIRECTION = { TOP: 1, RIGHT: 2, BOTTOM: 4, LEFT: 8 } as const;
-const ALL = DIRECTION.TOP | DIRECTION.RIGHT | DIRECTION.BOTTOM | DIRECTION.LEFT;
-
-/** Each piece's open sides at rotations 0..3 (a quarter turn clockwise each). */
-export const PIPE_OPENINGS: Record<PipeType, number[]> = {
-  [PipeType.EMPTY]: [0, 0, 0, 0],
-  [PipeType.STRAIGHT]: [
-    DIRECTION.TOP | DIRECTION.BOTTOM,
-    DIRECTION.LEFT | DIRECTION.RIGHT,
-    DIRECTION.TOP | DIRECTION.BOTTOM,
-    DIRECTION.LEFT | DIRECTION.RIGHT
-  ],
-  [PipeType.CORNER]: [
-    DIRECTION.TOP | DIRECTION.RIGHT,
-    DIRECTION.RIGHT | DIRECTION.BOTTOM,
-    DIRECTION.BOTTOM | DIRECTION.LEFT,
-    DIRECTION.LEFT | DIRECTION.TOP
-  ],
-  [PipeType.CROSS]: [ALL, ALL, ALL, ALL],
-  [PipeType.T_SHAPE]: [
-    DIRECTION.TOP | DIRECTION.RIGHT | DIRECTION.BOTTOM,
-    DIRECTION.RIGHT | DIRECTION.BOTTOM | DIRECTION.LEFT,
-    DIRECTION.BOTTOM | DIRECTION.LEFT | DIRECTION.TOP,
-    DIRECTION.LEFT | DIRECTION.TOP | DIRECTION.RIGHT
-  ],
-  [PipeType.SOURCE]: [ALL, ALL, ALL, ALL],
-  [PipeType.SINK]: [ALL, ALL, ALL, ALL]
-};
-
-// ── Feel (seconds) ────────────────────────────────────────────────────
-
-export const TURN_TIME = 0.2; // a pipe swings round a quarter turn, overshooting a touch
-export const FLOW_STEP = 0.045; // water reaches each newly joined pipe this long after the last
-export const WIN_STEP = 0.03; // the win pulse runs out from the source
-
-// ── The scene ─────────────────────────────────────────────────────────
-
-/** The camera leans back from straight down, so the pipes stand up off their tiles. */
-export const TILT = 0.32;
-/** Lit from the upper left; surfaces facing up off the board (+z) keep their exact color. */
-export const LIGHT = frontLight([-0.4, 0.5, 1], 0.45);
-export const COLORS = {
-  PIPE: '#8B9DC3',
-  WATER: '#4FC3F7',
-  SOURCE: '#4CAF50',
-  SINK: '#FF7043',
-  CLASSIC_BOARD: 'rgba(255, 255, 255, 0.30)',
-  CLASSIC_CELL: 'rgba(255, 255, 255, 0.10)'
-} as const;
-
-// ── Layout (view points) ──────────────────────────────────────────────
-
-const SCOREBOARD_HEIGHT = 82;
-const CONTROLS_HEIGHT = 110;
-const TABLET_WIDTH = 640;
-
-export type Layout = TiltView & { size: number; cell: number; padding: number; board: number };
-
-/** Whole-point cells as wide as the game area allows (as the original board), smaller if the screen is short. */
-export function getLayout(width: number, height: number, offset: number, size: number): Layout {
-  const tablet = width > TABLET_WIDTH;
-  const padding = tablet ? 6 : 4;
-  const gameWidth = gameWidthFor(width);
-  const top = getScoreBoardTop(offset) + SCOREBOARD_HEIGHT;
-  const room = Math.max(200, height - top - CONTROLS_HEIGHT);
-  const cell = Math.max(10, Math.floor(Math.min((gameWidth - padding * 2) / size, (room / Math.cos(TILT) - padding * 2) / size)));
-  return { width, height, tilt: TILT, centerY: top + room / 2, size, cell, padding, board: cell * size + padding * 2 };
-}
-
-export const isTabletWidth = (width: number) => width > TABLET_WIDTH;
-
-/** A cell's centre on the board (row 0 along the top), in world units. */
-export function cellCentre(l: Layout, row: number, col: number): [number, number] {
-  const half = l.board / 2;
-  return [-half + l.padding + (col + 0.5) * l.cell, half - l.padding - (row + 0.5) * l.cell];
-}

package/src/games/pipe-connect/PipeConnectGame.ts

@@ -1,179 +0,0 @@
-// Pipe Connect's play, with no React: build a game with `createGame` (it deals a puzzle), give it a
-// layout, `start` it and `tick` it every frame. Tap a pipe to turn it a quarter turn clockwise; the
-// water runs from the source through every pipe joined up to it. Reach the sink inside five minutes to
-// win (scored by the time it took, as the original version did). The store's rules, ported as they were.
-import { type Camera, World } from '@nayan-ui/engine';
-import { calculateTimeBasedScore } from '../../services/ScoringService';
-import type { GameTheme } from '../../services/ThemeService';
-import { aimTilted, unproject } from '../shared/EngineTilt';
-import { type Layout, PipeType, POINTS_PER_PUZZLE, TIME_LIMIT } from './PipeConnectConstants';
-import { findConnectedPath, generatePuzzle, isPuzzleCompleteFromSet, type PipeCell, rotatePipe } from './PipeConnectRules';
-import { buildScene, flow, removeScene, type Scene, setSceneTheme, splash, turnPiece, winPulse } from './PipeConnectScene';
-
-export type Phase = 'ready' | 'playing' | 'over';
-
-const WORLD_CAPACITY = 300; // 64 tiles and pipes at most, the board, and the splash
-
-/** The cells the water reaches, each with its place along the way out from the source (1 = the source). */
-const reach = (grid: PipeCell[][], connected = findConnectedPath(grid)) => {
-  const order = new Map<string, number>();
-  for (const id of connected) order.set(id, order.size + 1);
-  return order;
-};
-
-export function createGame(theme: GameTheme, size: number) {
-  const world = new World(WORLD_CAPACITY);
-  const camera: Camera = { eye: [0, 0, 240], target: [0, 0, 0], fov: 1, ortho: 1 };
-  const grid = generatePuzzle(size);
-  const g = {
-    world,
-    camera,
-    theme,
-    size,
-    layout: null as Layout | null,
-    scene: null as Scene | null,
-    phase: 'ready' as Phase,
-    grid,
-    wet: reach(grid),
-    /** Score and the countdown live in the engine (Rust), advanced by world.update. */
-    get score() {
-      return world.scoreboard.score;
-    },
-    get time() {
-      return world.scoreboard.shownSeconds;
-    },
-    won: false,
-    // UI hooks, set by the screen.
-    onPhase: (_p: Phase) => {},
-    onTime: (_t: number) => {},
-    /** A pipe turned; `solved` when that turn reached the sink. */
-    onTurn: (_solved: boolean) => {}
-  };
-  world.scoreboard.reset(0, TIME_LIMIT);
-  world.scoreboard.handlers = {
-    onSecond: (t) => g.onTime(t),
-    onTimeUp: () => {
-      if (g.phase !== 'playing') return;
-      g.won = false;
-      g.phase = 'over';
-      g.onPhase('over');
-    }
-  };
-  return g;
-}
-export type Game = ReturnType<typeof createGame>;
-
-const index = (g: Game, row: number, col: number) => row * g.size + col;
-
-// ── Scene ─────────────────────────────────────────────────────────────
-
-/** Lays the board out for the view (first layout, header height, rotation): rebuilt from the puzzle's state. */
-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, g.grid, new Set(g.wet.keys()));
-}
-
-export function setTheme(g: Game, theme: GameTheme) {
-  g.theme = theme;
-  if (g.layout && g.scene) setSceneTheme(g.world, g.layout, g.scene, theme);
-}
-
-// ── Run ───────────────────────────────────────────────────────────────
-
-/** Plays the puzzle that's showing. */
-export function start(g: Game) {
-  if (g.phase !== 'ready') return;
-  g.phase = 'playing';
-  g.world.scoreboard.startCountdown(TIME_LIMIT);
-  g.onPhase('playing');
-}
-
-/** A fresh puzzle, not started (Stop, Play Again). The world, and the GPU view drawing it, are kept. */
-export function reset(g: Game) {
-  g.grid = generatePuzzle(g.size);
-  g.wet = reach(g.grid);
-  g.world.scoreboard.reset(0, TIME_LIMIT);
-  g.won = false;
-  g.phase = 'ready';
-  if (g.layout) setLayout(g, g.layout);
-  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);
-}
-
-// ── Taps ──────────────────────────────────────────────────────────────
-
-/** The cell under a view point (as seen on the pipes, a little above the tiles). */
-export function cellAt(g: Game, x: number, y: number): [number, number] | null {
-  const l = g.layout;
-  if (!l) return null;
-  const [wx, wy] = unproject(l, x, y, l.cell * 0.15);
-  const half = l.board / 2;
-  const col = Math.floor((wx + half - l.padding) / l.cell);
-  const row = Math.floor((half - l.padding - wy) / l.cell);
-  return row >= 0 && row < g.size && col >= 0 && col < g.size ? [row, col] : null;
-}
-
-export function tap(g: Game, x: number, y: number) {
-  const at = cellAt(g, x, y);
-  if (at) rotateAt(g, at[0], at[1]);
-}
-
-/** Turns the pipe in a cell (not the source, sink or an empty one), then lets the water find its way. */
-export function rotateAt(g: Game, row: number, col: number) {
-  if (g.phase !== 'playing') return;
-  const cell = g.grid[row]?.[col];
-  if (!cell || cell.fixed || cell.type === PipeType.EMPTY) return;
-  const rotated = rotatePipe(cell);
-  g.grid[row]![col] = rotated;
-  const before = g.wet;
-  const connected = findConnectedPath(g.grid);
-  const complete = isPuzzleCompleteFromSet(g.grid, connected);
-  g.wet = reach(g.grid, connected);
-
-  const { layout: l, scene: s } = g;
-  if (l && s) {
-    const e = s.pieces[index(g, row, col)];
-    if (e != null) turnPiece(g.world, e, rotated.rotation);
-    // The first newly reached pipe's place along the path: the rest follow on from it
-    let base = 0;
-    for (const [id, order] of g.wet) if (!before.has(id) && (!base || order < base)) base = order;
-    for (const r of g.grid)
-      for (const c of r) {
-        const piece = s.pieces[index(g, c.row, c.col)];
-        if (piece == null) continue;
-        const now = g.wet.get(c.id);
-        if (!!now !== before.has(c.id)) flow(g.world, l, piece, c, !!now, now ?? 0, base);
-      }
-    if (complete) {
-      for (const [id, order] of g.wet) {
-        const [r, c] = id.split('-').map(Number) as [number, number];
-        const piece = s.pieces[index(g, r, c)];
-        if (piece != null) winPulse(g.world, l, piece, order);
-      }
-      const sink = g.grid.flat().find((c) => c.type === PipeType.SINK);
-      if (sink) splash(g.world, l, sink.row, sink.col);
-    }
-  }
-
-  if (complete) {
-    g.world.scoreboard.set(calculateTimeBasedScore(TIME_LIMIT - g.time, TIME_LIMIT, g.score + POINTS_PER_PUZZLE));
-    g.world.scoreboard.stop();
-    g.won = true;
-    g.phase = 'over';
-    g.onTurn(true);
-    g.onPhase('over');
-    return;
-  }
-  g.onTurn(false);
-}

package/src/games/pipe-connect/PipeConnectRules.ts

@@ -1,326 +0,0 @@
-// Pipe Connect's puzzles and moves, as plain functions: a winding path of pipes from a source on the
-// left edge to a sink on the right, every other cell filled with a decoy, all scrambled; turning a pipe;
-// and which pipes the water reaches. The original version's service (games/pipe-connect), unchanged but for
-// taking the grid size as an argument, so every puzzle plays the same.
-import { DIRECTION, PIPE_OPENINGS, PipeType } from './PipeConnectConstants';
-
-export interface PipeCell {
-  id: string;
-  row: number;
-  col: number;
-  type: PipeType;
-  rotation: number; // 0-3 (0°, 90°, 180°, 270°)
-  filled: boolean; // water flowing through
-  fixed: boolean; // source/sink — cannot rotate
-}
-
-// Get the open directions for a pipe cell
-export const getOpenDirections = (cell: PipeCell): number => {
-  const openings = PIPE_OPENINGS[cell.type];
-  if (!openings) return 0;
-  return openings[cell.rotation % 4] ?? 0;
-};
-
-// Check if two adjacent cells are connected
-const areConnected = (cellA: PipeCell, cellB: PipeCell): boolean => {
-  const openA = getOpenDirections(cellA);
-  const openB = getOpenDirections(cellB);
-
-  const dRow = cellB.row - cellA.row;
-  const dCol = cellB.col - cellA.col;
-
-  if (dRow === -1 && dCol === 0) {
-    return (openA & DIRECTION.TOP) !== 0 && (openB & DIRECTION.BOTTOM) !== 0;
-  }
-  if (dRow === 1 && dCol === 0) {
-    return (openA & DIRECTION.BOTTOM) !== 0 && (openB & DIRECTION.TOP) !== 0;
-  }
-  if (dRow === 0 && dCol === -1) {
-    return (openA & DIRECTION.LEFT) !== 0 && (openB & DIRECTION.RIGHT) !== 0;
-  }
-  if (dRow === 0 && dCol === 1) {
-    return (openA & DIRECTION.RIGHT) !== 0 && (openB & DIRECTION.LEFT) !== 0;
-  }
-  return false;
-};
-
-// BFS to find all cells connected to the source via properly connected pipes
-export const findConnectedPath = (grid: PipeCell[][]): Set<string> => {
-  const connected = new Set<string>();
-  const queue: PipeCell[] = [];
-
-  for (const row of grid) {
-    for (const cell of row) {
-      if (cell.type === PipeType.SOURCE) {
-        queue.push(cell);
-        connected.add(cell.id);
-      }
-    }
-  }
-
-  for (let head = 0; head < queue.length; head++) {
-    const current = queue[head]!;
-    const neighbors = getNeighbors(grid, current.row, current.col);
-
-    for (const neighbor of neighbors) {
-      if (connected.has(neighbor.id)) continue;
-      if (neighbor.type === PipeType.EMPTY) continue;
-
-      if (areConnected(current, neighbor)) {
-        connected.add(neighbor.id);
-        queue.push(neighbor);
-      }
-    }
-  }
-
-  return connected;
-};
-
-// Check completion using pre-computed connected set (avoids double BFS)
-export const isPuzzleCompleteFromSet = (grid: PipeCell[][], connected: Set<string>): boolean => {
-  for (const row of grid) {
-    for (const cell of row) {
-      if (cell.type === PipeType.SINK && connected.has(cell.id)) {
-        return true;
-      }
-    }
-  }
-  return false;
-};
-
-// Check if source is connected to sink
-export const isPuzzleComplete = (grid: PipeCell[][]): boolean => {
-  const connected = findConnectedPath(grid);
-  return isPuzzleCompleteFromSet(grid, connected);
-};
-
-// Get adjacent cells
-const getNeighbors = (grid: PipeCell[][], row: number, col: number): PipeCell[] => {
-  const neighbors: PipeCell[] = [];
-  if (row > 0) neighbors.push(grid[row - 1]![col]!);
-  if (row < grid.length - 1) neighbors.push(grid[row + 1]![col]!);
-  if (col > 0) neighbors.push(grid[row]![col - 1]!);
-  if (col < (grid[0]?.length ?? 0) - 1) neighbors.push(grid[row]![col + 1]!);
-  return neighbors;
-};
-
-interface PathNode {
-  row: number;
-  col: number;
-}
-
-// A short, near-straight run from source to sink could be completed in a handful of taps, so the
-// two ends are kept well apart in row and the walk between them is left free to wander.
-const minEndRowGap = (rows: number) => Math.max(2, Math.floor(rows / 2));
-
-// Generate a solvable puzzle — fills entire grid with pipes
-export const generatePuzzle = (size: number): PipeCell[][] => {
-  const rows = size;
-  const cols = size;
-
-  // Create empty grid
-  const grid: PipeCell[][] = [];
-  for (let r = 0; r < rows; r++) {
-    const row: PipeCell[] = [];
-    for (let c = 0; c < cols; c++) {
-      row.push({
-        id: `${r}-${c}`,
-        row: r,
-        col: c,
-        type: PipeType.EMPTY,
-        rotation: 0,
-        filled: false,
-        fixed: false
-      });
-    }
-    grid.push(row);
-  }
-
-  // Source and sink sit on opposite edges, and far enough apart in row that no straight shot exists
-  const sourceRow = Math.floor(Math.random() * rows);
-  let sinkRow = Math.floor(Math.random() * rows);
-  const gap = minEndRowGap(rows);
-  if (Math.abs(sinkRow - sourceRow) < gap) {
-    sinkRow = sourceRow < rows / 2 ? Math.min(rows - 1, sourceRow + gap) : Math.max(0, sourceRow - gap);
-  }
-
-  grid[sourceRow]![0] = {
-    ...grid[sourceRow]![0]!,
-    type: PipeType.SOURCE,
-    fixed: true
-  };
-
-  grid[sinkRow]![cols - 1] = {
-    ...grid[sinkRow]![cols - 1]!,
-    type: PipeType.SINK,
-    fixed: true
-  };
-
-  // Build a random winding path from source to sink
-  const path = buildRandomPath(sourceRow, 0, sinkRow, cols - 1, rows, cols);
-
-  // Place pipes along the main path
-  placePipesAlongPath(grid, path);
-
-  // Fill ALL remaining empty cells with pipes to make the grid dense
-  fillEmptyCells(grid, rows, cols);
-
-  // Scramble all non-fixed pipe rotations
-  scrambleRotations(grid);
-
-  return grid;
-};
-
-// Build a random winding path from source to sink
-const buildRandomPath = (startRow: number, startCol: number, endRow: number, endCol: number, rows: number, cols: number): PathNode[] => {
-  const visited = new Set<string>();
-  const path: PathNode[] = [];
-
-  const dfs = (r: number, c: number): boolean => {
-    if (r === endRow && c === endCol) {
-      path.push({ row: r, col: c });
-      return true;
-    }
-
-    visited.add(`${r}-${c}`);
-    path.push({ row: r, col: c });
-
-    // Unsorted on purpose: the walk used to be pulled straight at the sink, which produced a short,
-    // obvious run. Picking freely at random lets it wander far off the direct line, and the
-    // backtracking below still guarantees it reaches the sink.
-    const dirs = shuffleArray([
-      { dr: -1, dc: 0 },
-      { dr: 1, dc: 0 },
-      { dr: 0, dc: -1 },
-      { dr: 0, dc: 1 }
-    ]);
-
-    for (const dir of dirs) {
-      const nr = r + dir.dr;
-      const nc = c + dir.dc;
-
-      if (nr >= 0 && nr < rows && nc >= 0 && nc < cols && !visited.has(`${nr}-${nc}`)) {
-        if (dfs(nr, nc)) return true;
-      }
-    }
-
-    path.pop();
-    return false;
-  };
-
-  dfs(startRow, startCol);
-  return path;
-};
-
-// Determine pipe type and correct rotation for each cell in the path
-const placePipesAlongPath = (grid: PipeCell[][], path: PathNode[]) => {
-  for (let i = 0; i < path.length; i++) {
-    const node = path[i]!;
-    const cell = grid[node.row]![node.col]!;
-
-    if (cell.type === PipeType.SOURCE || cell.type === PipeType.SINK) continue;
-
-    let openDirs = 0;
-    if (i > 0) {
-      const prev = path[i - 1]!;
-      const dr = prev.row - node.row;
-      const dc = prev.col - node.col;
-      if (dr === -1) openDirs |= DIRECTION.TOP;
-      if (dr === 1) openDirs |= DIRECTION.BOTTOM;
-      if (dc === -1) openDirs |= DIRECTION.LEFT;
-      if (dc === 1) openDirs |= DIRECTION.RIGHT;
-    }
-    if (i < path.length - 1) {
-      const next = path[i + 1]!;
-      const dr = next.row - node.row;
-      const dc = next.col - node.col;
-      if (dr === -1) openDirs |= DIRECTION.TOP;
-      if (dr === 1) openDirs |= DIRECTION.BOTTOM;
-      if (dc === -1) openDirs |= DIRECTION.LEFT;
-      if (dc === 1) openDirs |= DIRECTION.RIGHT;
-    }
-
-    const match = findPipeForOpenings(openDirs);
-    cell.type = match.type;
-    cell.rotation = match.rotation;
-  }
-};
-
-// Find which pipe type + rotation produces the given openings bitmask
-const findPipeForOpenings = (openDirs: number): { type: PipeType; rotation: number } => {
-  const types = [PipeType.STRAIGHT, PipeType.CORNER, PipeType.T_SHAPE, PipeType.CROSS];
-  for (const type of types) {
-    const openings = PIPE_OPENINGS[type]!;
-    for (let rot = 0; rot < 4; rot++) {
-      if (openings[rot] === openDirs) {
-        return { type, rotation: rot };
-      }
-    }
-  }
-  return { type: PipeType.STRAIGHT, rotation: 0 };
-};
-
-// Fill all remaining empty cells with random pipe types
-const fillEmptyCells = (grid: PipeCell[][], rows: number, cols: number) => {
-  // No CROSS filler: it is open on all four sides at every rotation, so each one was a free joint
-  // that let water find the sink by accident. T pieces are kept rare for the same reason.
-  const pipeTypes = [PipeType.STRAIGHT, PipeType.CORNER, PipeType.T_SHAPE];
-  const weights = [0.45, 0.45, 0.1];
-
-  for (let r = 0; r < rows; r++) {
-    for (let c = 0; c < cols; c++) {
-      const cell = grid[r]![c]!;
-      if (cell.type !== PipeType.EMPTY) continue;
-
-      // Pick weighted random type
-      const rand = Math.random();
-      let cumulative = 0;
-      let chosenType = PipeType.STRAIGHT;
-      for (let i = 0; i < pipeTypes.length; i++) {
-        cumulative += weights[i]!;
-        if (rand < cumulative) {
-          chosenType = pipeTypes[i]!;
-          break;
-        }
-      }
-
-      cell.type = chosenType;
-      cell.rotation = Math.floor(Math.random() * 4);
-    }
-  }
-};
-
-// Scramble all non-fixed pipe rotations
-const scrambleRotations = (grid: PipeCell[][]) => {
-  for (const row of grid) {
-    for (const cell of row) {
-      if (cell.fixed || cell.type === PipeType.EMPTY) continue;
-      if (cell.type === PipeType.CROSS) continue;
-      const originalRotation = cell.rotation;
-      let newRotation = originalRotation;
-      while (newRotation === originalRotation) {
-        newRotation = Math.floor(Math.random() * 4);
-      }
-      cell.rotation = newRotation;
-    }
-  }
-};
-
-// Rotate a pipe 90° clockwise
-export const rotatePipe = (cell: PipeCell): PipeCell => {
-  if (cell.fixed || cell.type === PipeType.EMPTY) return cell;
-  return {
-    ...cell,
-    rotation: (cell.rotation + 1) % 4
-  };
-};
-
-// Utility: shuffle array (Fisher-Yates)
-const shuffleArray = <T>(arr: T[]): T[] => {
-  const result = [...arr];
-  for (let i = result.length - 1; i > 0; i--) {
-    const j = Math.floor(Math.random() * (i + 1));
-    [result[i], result[j]] = [result[j]!, result[i]!];
-  }
-  return result;
-};