@omercnet/paseo-queens 0.1.0-next.126.2

package/client/game/puzzles.ts

@@ -0,0 +1,100 @@
+import type { Puzzle } from "./types";
+
+export const PUZZLES = [
+  {
+    id: "paseo-queens-01",
+    size: 6,
+    regions: [
+      0, 0, 0, 1, 1, 1, 0, 0, 1, 1, 1, 1, 0, 2, 1, 1, 1, 3, 0, 0, 4, 4, 4, 3, 0, 4, 4, 4, 4, 5, 0,
+      0, 4, 5, 5, 5,
+    ],
+  },
+  {
+    id: "paseo-queens-02",
+    size: 6,
+    regions: [
+      1, 1, 0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 1, 1, 1, 1, 0, 2, 3, 5, 5, 1, 1, 2, 3, 5, 4, 4, 1, 2, 5,
+      5, 5, 5, 1, 2,
+    ],
+  },
+  {
+    id: "paseo-queens-03",
+    size: 6,
+    regions: [
+      0, 0, 0, 0, 1, 1, 0, 0, 0, 1, 1, 1, 2, 0, 4, 4, 1, 1, 2, 2, 3, 4, 4, 4, 2, 2, 3, 3, 4, 4, 3,
+      3, 3, 5, 4, 4,
+    ],
+  },
+  {
+    id: "paseo-queens-04",
+    size: 6,
+    regions: [
+      1, 1, 3, 3, 0, 2, 1, 1, 3, 3, 0, 2, 4, 1, 4, 3, 2, 2, 4, 4, 4, 3, 3, 3, 4, 4, 4, 4, 5, 3, 5,
+      5, 5, 5, 5, 5,
+    ],
+  },
+  {
+    id: "paseo-queens-05",
+    size: 6,
+    regions: [
+      0, 0, 1, 1, 1, 1, 1, 1, 1, 2, 4, 4, 1, 3, 3, 2, 2, 4, 1, 3, 3, 4, 2, 4, 5, 3, 5, 4, 4, 4, 5,
+      5, 5, 5, 4, 4,
+    ],
+  },
+  {
+    id: "paseo-queens-06",
+    size: 6,
+    regions: [
+      0, 2, 2, 2, 1, 1, 2, 2, 2, 1, 1, 1, 2, 2, 3, 3, 3, 1, 5, 5, 3, 3, 3, 4, 5, 5, 5, 3, 4, 4, 5,
+      5, 5, 5, 5, 5,
+    ],
+  },
+  {
+    id: "paseo-queens-07",
+    size: 6,
+    regions: [
+      2, 0, 0, 0, 0, 0, 2, 2, 1, 1, 0, 0, 2, 2, 2, 1, 4, 4, 2, 2, 2, 3, 4, 4, 2, 2, 5, 4, 4, 4, 5,
+      5, 5, 5, 4, 4,
+    ],
+  },
+  {
+    id: "paseo-queens-08",
+    size: 6,
+    regions: [
+      0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 1, 1, 3, 3, 2, 0, 4, 3, 3, 5, 2, 2, 4, 3, 3, 5, 2, 2, 4,
+      3, 3, 5, 5, 2,
+    ],
+  },
+  {
+    id: "paseo-queens-09",
+    size: 6,
+    regions: [
+      1, 1, 1, 2, 2, 0, 4, 1, 1, 2, 2, 2, 4, 1, 3, 2, 2, 2, 4, 3, 3, 3, 3, 3, 4, 3, 4, 3, 3, 3, 4,
+      4, 4, 5, 5, 5,
+    ],
+  },
+  {
+    id: "paseo-queens-10",
+    size: 6,
+    regions: [
+      0, 0, 0, 1, 1, 1, 0, 2, 2, 1, 1, 1, 0, 2, 2, 1, 1, 1, 3, 2, 2, 5, 5, 1, 3, 3, 2, 4, 5, 5, 3,
+      3, 3, 5, 5, 5,
+    ],
+  },
+  {
+    id: "paseo-queens-11",
+    size: 6,
+    regions: [
+      2, 2, 1, 1, 0, 0, 2, 2, 1, 1, 1, 0, 2, 2, 1, 1, 1, 0, 4, 4, 1, 3, 3, 0, 4, 4, 4, 3, 3, 3, 4,
+      3, 3, 3, 3, 5,
+    ],
+  },
+  {
+    id: "paseo-queens-12",
+    size: 6,
+    regions: [
+      1, 1, 1, 2, 2, 0, 3, 3, 1, 1, 2, 2, 5, 3, 4, 4, 2, 2, 5, 3, 4, 4, 4, 4, 5, 5, 4, 4, 4, 4, 5,
+      5, 4, 4, 4, 4,
+    ],
+  },
+] as const satisfies readonly Puzzle[];

package/client/game/state.ts

@@ -0,0 +1,348 @@
+import { createEmptyCells, findConflicts, isSolved, setCellStates } from "./engine";
+import type { CellState, Puzzle } from "./types";
+
+export interface TimerState {
+  readonly startedAt: number | null;
+  readonly completedAt: number | null;
+  readonly elapsedMs: number;
+  readonly lastTickAt: number | null;
+}
+
+export interface GameHistoryEntry {
+  readonly cells: readonly CellState[];
+  readonly timer: TimerState;
+  readonly restoresTimer: boolean;
+}
+
+export interface PuzzleProgress {
+  readonly cells: readonly CellState[];
+  readonly history: readonly GameHistoryEntry[];
+  readonly solved: boolean;
+  readonly timer: TimerState;
+}
+
+export interface GameState {
+  readonly puzzles: readonly Puzzle[];
+  readonly solutions: readonly (readonly number[])[];
+  readonly progress: readonly PuzzleProgress[];
+  readonly activePuzzleIndex: number;
+}
+
+export type PuzzleSolution = readonly number[];
+
+export type GameAction =
+  | {
+      readonly type: "set-cells";
+      readonly indexes: readonly number[];
+      readonly state: CellState;
+      readonly now: number;
+    }
+  | { readonly type: "undo"; readonly now: number }
+  | { readonly type: "reset"; readonly now: number }
+  | { readonly type: "hint"; readonly now: number }
+  | { readonly type: "select-puzzle"; readonly index: number; readonly now: number }
+  | { readonly type: "tick"; readonly now: number };
+
+const EMPTY_TIMER: TimerState = {
+  startedAt: null,
+  completedAt: null,
+  elapsedMs: 0,
+  lastTickAt: null,
+};
+
+function assertTimestamp(now: number): void {
+  if (!Number.isFinite(now)) throw new RangeError("Timestamp must be finite.");
+}
+
+function advanceTimer(timer: TimerState, now: number): TimerState {
+  assertTimestamp(now);
+  if (timer.lastTickAt === null) return timer;
+
+  const nextTickAt = Math.max(timer.lastTickAt, now);
+  if (nextTickAt === timer.lastTickAt) return timer;
+
+  return {
+    ...timer,
+    elapsedMs: timer.elapsedMs + nextTickAt - timer.lastTickAt,
+    lastTickAt: nextTickAt,
+  };
+}
+
+function startTimer(timer: TimerState, now: number): TimerState {
+  assertTimestamp(now);
+  if (timer.startedAt !== null) return advanceTimer(timer, now);
+
+  return {
+    startedAt: now,
+    completedAt: null,
+    elapsedMs: 0,
+    lastTickAt: now,
+  };
+}
+
+function stopTimer(timer: TimerState, now: number): TimerState {
+  const advanced = advanceTimer(timer, now);
+  if (advanced.startedAt === null) return advanced;
+
+  return {
+    ...advanced,
+    completedAt: advanced.lastTickAt ?? Math.max(advanced.startedAt, now),
+    lastTickAt: null,
+  };
+}
+
+function resumeTimer(timer: TimerState, now: number): TimerState {
+  assertTimestamp(now);
+  if (timer.startedAt === null) return timer;
+
+  const latestTimestamp = timer.completedAt ?? timer.lastTickAt ?? timer.startedAt;
+  return {
+    ...timer,
+    completedAt: null,
+    lastTickAt: Math.max(latestTimestamp, now),
+  };
+}
+
+function firstSolution(puzzle: Puzzle): readonly number[] {
+  // This also validates the puzzle before the one-time solution search.
+  isSolved(puzzle, createEmptyCells(puzzle.size));
+
+  const usedColumns = new Uint8Array(puzzle.size);
+  const usedRegions = new Uint8Array(puzzle.size);
+  const solution = Array<number>(puzzle.size).fill(-1);
+
+  function search(row: number, previousColumn: number): boolean {
+    if (row === puzzle.size) return true;
+
+    for (let column = 0; column < puzzle.size; column += 1) {
+      const index = row * puzzle.size + column;
+      const region = puzzle.regions[index];
+      if (
+        usedColumns[column] === 1 ||
+        usedRegions[region] === 1 ||
+        (row > 0 && Math.abs(column - previousColumn) <= 1)
+      ) {
+        continue;
+      }
+
+      usedColumns[column] = 1;
+      usedRegions[region] = 1;
+      solution[row] = index;
+      if (search(row + 1, column)) return true;
+      usedColumns[column] = 0;
+      usedRegions[region] = 0;
+    }
+
+    return false;
+  }
+
+  if (!search(0, -2)) throw new RangeError(`Puzzle ${puzzle.id} has no solution.`);
+  return solution;
+}
+
+function normalizeSolution(puzzle: Puzzle, solution: PuzzleSolution): readonly number[] {
+  const cells = createEmptyCells(puzzle.size);
+  for (const index of solution) {
+    if (
+      !Number.isInteger(index) ||
+      index < 0 ||
+      index >= cells.length ||
+      cells[index] === "marked"
+    ) {
+      throw new RangeError(`Puzzle ${puzzle.id} has an invalid known solution.`);
+    }
+    cells[index] = "marked";
+  }
+
+  if (!isSolved(puzzle, cells))
+    throw new RangeError(`Puzzle ${puzzle.id} has an invalid known solution.`);
+  return [...solution].sort((left, right) => left - right);
+}
+
+export function createGameState(
+  puzzles: readonly Puzzle[],
+  knownSolutions: Readonly<Record<string, PuzzleSolution>> = {},
+): GameState {
+  if (puzzles.length === 0) throw new RangeError("The puzzle bank must not be empty.");
+  if (new Set(puzzles.map((puzzle) => puzzle.id)).size !== puzzles.length) {
+    throw new RangeError("Puzzle ids must be unique.");
+  }
+
+  const bank = puzzles.slice();
+  const solutions = bank.map((puzzle) => {
+    const known = knownSolutions[puzzle.id];
+    return known === undefined ? firstSolution(puzzle) : normalizeSolution(puzzle, known);
+  });
+  const emptyCellsBySize = new Map<number, readonly CellState[]>();
+  const progress = bank.map((puzzle): PuzzleProgress => {
+    let cells = emptyCellsBySize.get(puzzle.size);
+    if (!cells) {
+      cells = createEmptyCells(puzzle.size);
+      emptyCellsBySize.set(puzzle.size, cells);
+    }
+    return {
+      cells,
+      history: [],
+      solved: false,
+      timer: EMPTY_TIMER,
+    };
+  });
+
+  return {
+    puzzles: bank,
+    solutions,
+    progress,
+    activePuzzleIndex: 0,
+  };
+}
+
+function replaceActiveProgress(state: GameState, next: PuzzleProgress): GameState {
+  const progress = state.progress.slice();
+  progress[state.activePuzzleIndex] = next;
+  return { ...state, progress };
+}
+
+function changeCells(
+  state: GameState,
+  cells: readonly CellState[],
+  now: number,
+  restoresTimer: boolean,
+): GameState {
+  const current = state.progress[state.activePuzzleIndex];
+  const puzzle = state.puzzles[state.activePuzzleIndex];
+  const advancedTimer = advanceTimer(current.timer, now);
+  const runningTimer = startTimer(advancedTimer, now);
+  const solved = isSolved(puzzle, cells);
+  const timer = solved ? stopTimer(runningTimer, now) : runningTimer;
+  const historyEntry: GameHistoryEntry = {
+    cells: current.cells,
+    timer: advancedTimer,
+    restoresTimer,
+  };
+
+  return replaceActiveProgress(state, {
+    cells,
+    history: [...current.history, historyEntry],
+    solved,
+    timer,
+  });
+}
+
+function reset(state: GameState, now: number): GameState {
+  assertTimestamp(now);
+  const current = state.progress[state.activePuzzleIndex];
+  const pristine =
+    current.timer.startedAt === null && current.cells.every((cell) => cell === "empty");
+  if (pristine) return state;
+
+  const timer = advanceTimer(current.timer, now);
+  const historyEntry: GameHistoryEntry = {
+    cells: current.cells,
+    timer,
+    restoresTimer: true,
+  };
+
+  return replaceActiveProgress(state, {
+    cells: createEmptyCells(state.puzzles[state.activePuzzleIndex].size),
+    history: [...current.history, historyEntry],
+    solved: false,
+    timer: EMPTY_TIMER,
+  });
+}
+
+function undo(state: GameState, now: number): GameState {
+  assertTimestamp(now);
+  const current = state.progress[state.activePuzzleIndex];
+  const historyEntry = current.history[current.history.length - 1];
+  if (historyEntry === undefined) return state;
+
+  const puzzle = state.puzzles[state.activePuzzleIndex];
+  const solved = isSolved(puzzle, historyEntry.cells);
+  const currentTimer = advanceTimer(current.timer, now);
+  const restoredTimer = historyEntry.restoresTimer ? historyEntry.timer : currentTimer;
+  const timer = solved ? restoredTimer : resumeTimer(restoredTimer, now);
+
+  return replaceActiveProgress(state, {
+    cells: historyEntry.cells,
+    history: current.history.slice(0, -1),
+    solved,
+    timer,
+  });
+}
+
+function hint(state: GameState, now: number): GameState {
+  assertTimestamp(now);
+  const current = state.progress[state.activePuzzleIndex];
+  if (current.solved) return state;
+
+  const puzzle = state.puzzles[state.activePuzzleIndex];
+  const solution = state.solutions[state.activePuzzleIndex];
+  const conflicts = findConflicts(puzzle, current.cells);
+  let target = -1;
+  let replacement: CellState = "empty";
+
+  for (let index = 0; index < current.cells.length; index += 1) {
+    if (conflicts.has(index)) {
+      target = index;
+      break;
+    }
+  }
+
+  if (target === -1) {
+    const solutionCells = new Set(solution);
+    target = current.cells.findIndex(
+      (cell, index) => cell === "marked" && !solutionCells.has(index),
+    );
+  }
+
+  if (target === -1) {
+    target = solution.find((index) => current.cells[index] !== "marked") ?? -1;
+    replacement = "marked";
+  }
+
+  if (target === -1) return state;
+  const cells = current.cells.slice();
+  cells[target] = replacement;
+  return changeCells(state, cells, now, false);
+}
+
+export function gameReducer(state: GameState, action: GameAction): GameState {
+  const current = state.progress[state.activePuzzleIndex];
+
+  switch (action.type) {
+    case "set-cells": {
+      if (current.solved) return state;
+      const cells = setCellStates(current.cells, action.indexes, action.state);
+      return cells === current.cells ? state : changeCells(state, cells, action.now, false);
+    }
+    case "undo":
+      return undo(state, action.now);
+    case "reset":
+      return reset(state, action.now);
+    case "hint":
+      return hint(state, action.now);
+    case "select-puzzle": {
+      if (!Number.isInteger(action.index)) throw new RangeError("Puzzle index must be an integer.");
+      const activePuzzleIndex = Math.min(Math.max(action.index, 0), state.puzzles.length - 1);
+      const currentTimer = advanceTimer(current.timer, action.now);
+      if (activePuzzleIndex === state.activePuzzleIndex) {
+        return currentTimer === current.timer
+          ? state
+          : replaceActiveProgress(state, { ...current, timer: currentTimer });
+      }
+
+      const progress = state.progress.slice();
+      if (currentTimer !== current.timer)
+        progress[state.activePuzzleIndex] = { ...current, timer: currentTimer };
+      const selected = progress[activePuzzleIndex];
+      const selectedTimer = advanceTimer(selected.timer, action.now);
+      if (selectedTimer !== selected.timer)
+        progress[activePuzzleIndex] = { ...selected, timer: selectedTimer };
+      return { ...state, progress, activePuzzleIndex };
+    }
+    case "tick": {
+      const timer = advanceTimer(current.timer, action.now);
+      return timer === current.timer ? state : replaceActiveProgress(state, { ...current, timer });
+    }
+  }
+}

package/client/game/types.ts

@@ -0,0 +1,7 @@
+export type CellState = "empty" | "excluded" | "marked";
+
+export interface Puzzle {
+  readonly id: string;
+  readonly size: number;
+  readonly regions: readonly number[];
+}

package/client/game-controls.tsx

@@ -0,0 +1,199 @@
+import type { PluginSurfaceProps } from "@getpaseo/plugin/client";
+import { useMemo } from "react";
+import { ActivityIndicator, Pressable, StyleSheet, Text, View } from "react-native";
+
+export type GameControlsProps = {
+  canUndo: boolean;
+  canHint: boolean;
+  canReset: boolean;
+  canGoPrevious: boolean;
+  canGoNext: boolean;
+  saving: boolean;
+  disabled: boolean;
+  theme: PluginSurfaceProps["theme"];
+  dense?: boolean;
+  showNavigation?: boolean;
+  showSavingStatus?: boolean;
+  onUndo(): void;
+  onHint(): void;
+  onReset(): void;
+  onPrevious(): void;
+  onNext(): void;
+};
+
+export function GameControls({
+  canUndo,
+  canHint,
+  canReset,
+  canGoPrevious,
+  canGoNext,
+  saving,
+  disabled,
+  dense = false,
+  theme,
+  showNavigation = true,
+  showSavingStatus = true,
+  onUndo,
+  onHint,
+  onReset,
+  onPrevious,
+  onNext,
+}: GameControlsProps) {
+  const styles = useMemo(() => createStyles(theme, dense), [dense, theme]);
+  const controls = [
+    {
+      key: "previous",
+      label: "Previous",
+      accessibilityLabel: "Go to previous puzzle",
+      available: canGoPrevious,
+      onPress: onPrevious,
+    },
+    {
+      key: "undo",
+      label: "Undo",
+      accessibilityLabel: "Undo last move",
+      available: canUndo,
+      onPress: onUndo,
+    },
+    {
+      key: "hint",
+      label: "Hint",
+      accessibilityLabel: "Show a hint",
+      available: canHint,
+      onPress: onHint,
+    },
+    {
+      key: "reset",
+      label: "Reset",
+      accessibilityLabel: "Reset puzzle",
+      available: canReset,
+      onPress: onReset,
+    },
+    {
+      key: "next",
+      label: "Next",
+      accessibilityLabel: "Go to next puzzle",
+      available: canGoNext,
+      onPress: onNext,
+    },
+  ] as const;
+
+  return (
+    <View style={styles.container}>
+      <View style={styles.controls}>
+        {controls
+          .filter(
+            (control) => showNavigation || (control.key !== "previous" && control.key !== "next"),
+          )
+          .map((control) => {
+            const controlDisabled = disabled || !control.available;
+
+            return (
+              <Pressable
+                key={control.key}
+                accessibilityRole="button"
+                accessibilityLabel={control.accessibilityLabel}
+                accessibilityState={{ disabled: controlDisabled }}
+                disabled={controlDisabled}
+                hitSlop={2}
+                onPress={control.onPress}
+                style={({ pressed }) => [
+                  styles.control,
+                  pressed && !controlDisabled && styles.controlPressed,
+                ]}
+              >
+                <Text style={[styles.controlText, controlDisabled && styles.controlTextDisabled]}>
+                  {control.label}
+                </Text>
+              </Pressable>
+            );
+          })}
+      </View>
+      {showSavingStatus ? (
+        <View style={styles.savingSlot}>
+          {saving ? (
+            <View
+              accessibilityLiveRegion="polite"
+              accessibilityRole="progressbar"
+              accessibilityLabel="Saving game progress"
+              accessibilityState={{ busy: true }}
+              accessibilityValue={{ text: "Saving" }}
+              style={styles.savingStatus}
+            >
+              <ActivityIndicator size="small" color={theme.colors.accent} />
+              <Text style={styles.savingText}>Saving…</Text>
+            </View>
+          ) : null}
+        </View>
+      ) : null}
+    </View>
+  );
+}
+
+function createStyles(theme: PluginSurfaceProps["theme"], dense: boolean) {
+  return StyleSheet.create({
+    container: {
+      width: "100%",
+      alignItems: "center",
+      gap: 8,
+    },
+    controls: {
+      width: "100%",
+      flexDirection: "row",
+      flexWrap: "wrap",
+      alignItems: "stretch",
+      justifyContent: "center",
+      gap: 8,
+    },
+    control: {
+      minWidth: dense ? 68 : 94,
+      maxWidth: dense ? 96 : 132,
+      minHeight: 44,
+      flexGrow: 1,
+      flexBasis: dense ? 68 : 94,
+      flexShrink: 1,
+      flexDirection: "row",
+      alignItems: "center",
+      justifyContent: "center",
+      gap: 7,
+      paddingHorizontal: 12,
+      paddingVertical: 9,
+      borderWidth: StyleSheet.hairlineWidth,
+      borderColor: theme.colors.border,
+      borderRadius: 9,
+      backgroundColor: theme.colors.surface2,
+    },
+    controlPressed: {
+      opacity: 0.7,
+      transform: [{ scale: 0.98 }],
+    },
+    controlText: {
+      color: theme.colors.foreground,
+      fontSize: 12,
+      fontWeight: "600",
+    },
+    controlTextDisabled: {
+      color: theme.colors.foregroundMuted,
+    },
+    savingSlot: {
+      minHeight: 24,
+      alignItems: "center",
+      justifyContent: "center",
+    },
+    savingStatus: {
+      minHeight: 24,
+      flexDirection: "row",
+      alignItems: "center",
+      justifyContent: "center",
+      gap: 6,
+      paddingHorizontal: 10,
+      borderRadius: 999,
+      backgroundColor: theme.colors.surface1,
+    },
+    savingText: {
+      color: theme.colors.foregroundMuted,
+      fontSize: 11,
+      fontWeight: "600",
+    },
+  });
+}

package/client/game-mark.tsx

@@ -0,0 +1,54 @@
+import { Text, View } from "react-native";
+
+export type GameMarkProps = {
+  size: number;
+  color: string;
+  conflicted?: boolean;
+};
+
+export function GameMark({ size, color, conflicted = false }: GameMarkProps) {
+  const visualOffset = -Math.max(1, Math.round(size * 0.1));
+  return (
+    <View
+      accessible={false}
+      importantForAccessibility="no-hide-descendants"
+      style={{
+        width: size,
+        height: size,
+        alignItems: "center",
+        justifyContent: "center",
+      }}
+    >
+      <Text
+        accessible={false}
+        importantForAccessibility="no"
+        style={{
+          width: size,
+          height: size,
+          color,
+          fontSize: size,
+          lineHeight: size,
+          fontWeight: "700",
+          includeFontPadding: false,
+          textAlign: "center",
+          textAlignVertical: "center",
+          transform: [{ translateY: visualOffset }],
+        }}
+      >
+        ♛
+      </Text>
+      {conflicted ? (
+        <View
+          style={{
+            position: "absolute",
+            width: size * 0.9,
+            height: Math.max(2, size * 0.08),
+            borderRadius: size,
+            backgroundColor: color,
+            transform: [{ translateY: visualOffset }, { rotate: "-45deg" }],
+          }}
+        />
+      ) : null}
+    </View>
+  );
+}