Portal Chess: add 100 portal puzzles (mate in 1) with new Mode tab

Author: Swon404

src/puzzles/__tests__/portal-puzzles.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from "vitest";
+import { PORTAL_PUZZLES } from "../portal-puzzles";
+import { legalMovesFrom, makeMove, gameResult } from "../../engine/rules";
+import { parseSquare } from "../../engine/board";
+import type { Move } from "../../engine/board";
+
+/**
+ * Parse an extended UCI move string used by portal puzzles.
+ *
+ * Formats:
+ *   "e2e4"       — normal move
+ *   "e2e4@d8"    — portal entry: move to e4 (the portal), teleport to d8
+ *
+ * Returns the base UCI parts plus an optional portalTo square.
+ */
+function parsePortalUci(uci: string): {
+  from: { file: number; rank: number };
+  to: { file: number; rank: number };
+  portalTo?: { file: number; rank: number };
+  promotion?: string;
+} {
+  const atIdx = uci.indexOf("@");
+  if (atIdx !== -1) {
+    const base = uci.slice(0, atIdx);
+    const landStr = uci.slice(atIdx + 1);
+    const from = parseSquare(base.slice(0, 2));
+    const to = parseSquare(base.slice(2, 4));
+    const portalTo = parseSquare(landStr.slice(0, 2));
+    return { from, to, portalTo };
+  }
+  const from = parseSquare(uci.slice(0, 2));
+  const to = parseSquare(uci.slice(2, 4));
+  const promotion = uci.length === 5 ? uci[4].toUpperCase() : undefined;
+  return { from, to, promotion };
+}
+
+describe("portal puzzle solutions", () => {
+  for (const p of PORTAL_PUZZLES) {
+    it(`${p.id} — portal mate in ${p.mateIn()}`, () => {
+      let state = p.setup();
+      for (let i = 0; i < p.moves.length; i++) {
+        const uci = p.moves[i];
+        const { from, to, portalTo, promotion } = parsePortalUci(uci);
+
+        const candidates = legalMovesFrom(state, from);
+
+        let legal: Move | undefined;
+        if (portalTo) {
+          // Teleport move: match on from, to (portal square), and portalTo (landing).
+          legal = candidates.find(
+            (m) =>
+              m.from.file === from.file &&
+              m.from.rank === from.rank &&
+              m.to.file === to.file &&
+              m.to.rank === to.rank &&
+              m.isPortalEntry === true &&
+              m.portalTo !== undefined &&
+              m.portalTo.file === portalTo.file &&
+              m.portalTo.rank === portalTo.rank
+          );
+        } else {
+          legal = candidates.find(
+            (m) =>
+              m.to.file === to.file &&
+              m.to.rank === to.rank &&
+              (!promotion || m.promotion === promotion)
+          );
+        }
+
+        expect(legal, `ply ${i + 1} (${uci}) not legal in ${p.id}`).toBeDefined();
+        state = makeMove(state, legal!);
+
+        const res = gameResult(state);
+        if (i === p.moves.length - 1) {
+          expect(res.kind, `final move in ${p.id} did not mate`).toBe("checkmate");
+        } else {
+          expect(res.kind, `intermediate move in ${p.id} unexpectedly ended game`).toBe("ongoing");
+        }
+      }
+    });
+  }
+});

src/puzzles/portal-puzzle-db.ts

@@ -0,0 +1,141 @@
+import type { PieceType } from "../engine/board";
+
+/**
+ * Portal puzzle data row.
+ *
+ * Moves use extended UCI notation:
+ *   - "e2e4"        — normal move
+ *   - "e2e4@d8"     — move from e2 to e4 (a portal square), then teleport to d8
+ *
+ * wPortal / bPortal are algebraic squares ("e4", "h1", etc.) or null.
+ * creator is "K" so that queens, rooks, bishops, and knights can all use portals.
+ */
+export interface PortalPuzzleRow {
+  id: string;
+  /** FEN string — must have at least 4 space-separated fields. */
+  fen: string;
+  wPortal: string | null;
+  bPortal: string | null;
+  /** Piece type that creates portals. Use "K" so all other pieces can teleport. */
+  creator: PieceType;
+  /** Solution moves in extended UCI. */
+  moves: string[];
+  themes: string[];
+}
+
+// ─── DESIGN ──────────────────────────────────────────────────────────────────
+//
+// All 100 puzzles use one of four verified mate patterns. The mover (rook)
+// starts on rank 1, slides along its file to a portal, teleports to the
+// killing square, and delivers checkmate. The black king is trapped in a
+// corner by its own piece + a defending white queen.
+//
+//   PATTERN A (a-file mate):  k a8, black rook b8, white queen b6 → land a7
+//   PATTERN B (h-file mate):  k h8, black rook g8, white queen g6 → land h7
+//   PATTERN C (b7 mate):      k b8, black rook a8, white queen c7 → land b7
+//   PATTERN D (g7 mate):      k g8, black rook h8, white queen f7 → land g7
+//
+// For each pattern we vary the mover's starting file and the portal rank.
+// The white queen guards both the killing square AND the king's flight
+// squares, so every variation is a clean mate.
+//
+// ─────────────────────────────────────────────────────────────────────────────
+
+type Pattern = "A" | "B" | "C" | "D";
+
+interface PatternSpec {
+  /** FEN ranks 8..2 (rank 1 will be filled in per-mover). */
+  prefix: string;
+  /** Killing square (where the mover teleports). */
+  land: string;
+  /** Files where rank 1 is fully clear for the mover. */
+  moverFiles: string[];
+  theme: string;
+}
+
+const PATTERNS: Record<Pattern, PatternSpec> = {
+  A: {
+    prefix: "kr6/8/1Q6/8/8/8/8/",
+    land: "a7",
+    moverFiles: ["a", "c", "d", "e", "f", "g", "h"],
+    theme: "aFileMate",
+  },
+  B: {
+    prefix: "6rk/8/6Q1/8/8/8/8/",
+    land: "h7",
+    moverFiles: ["a", "b", "c", "d", "e", "f", "h"],
+    theme: "hFileMate",
+  },
+  C: {
+    prefix: "rk6/2Q5/8/8/8/8/8/",
+    land: "b7",
+    moverFiles: ["a", "b", "d", "e", "f", "g", "h"],
+    theme: "b7Mate",
+  },
+  D: {
+    prefix: "6kr/5Q2/8/8/8/8/8/",
+    land: "g7",
+    moverFiles: ["a", "b", "c", "d", "e", "g", "h"],
+    theme: "g7Mate",
+  },
+};
+
+function fileIdx(f: string): number {
+  return f.charCodeAt(0) - 97;
+}
+
+/** Build a rank-1 FEN string with one piece on the given file. */
+function rank1With(piece: "R", file: string): string {
+  const idx = fileIdx(file);
+  const left = idx === 0 ? "" : String(idx);
+  const right = idx === 7 ? "" : String(7 - idx);
+  return `${left}${piece}${right}`;
+}
+
+interface Variation {
+  pattern: Pattern;
+  file: string;
+  portalRank: number;
+}
+
+function makeRow(id: string, v: Variation): PortalPuzzleRow {
+  const spec = PATTERNS[v.pattern];
+  const rank1 = rank1With("R", v.file);
+  const fen = `${spec.prefix}${rank1} w - -`;
+  const portal = `${v.file}${v.portalRank}`;
+  return {
+    id,
+    fen,
+    wPortal: portal,
+    bPortal: null,
+    creator: "K",
+    moves: [`${v.file}1${portal}@${spec.land}`],
+    themes: ["portal", "rook", spec.theme, "mateIn1"],
+  };
+}
+
+function variationsFor(pattern: Pattern): Variation[] {
+  const spec = PATTERNS[pattern];
+  const out: Variation[] = [];
+  for (const file of spec.moverFiles) {
+    for (let r = 2; r <= 7; r++) {
+      out.push({ pattern, file, portalRank: r });
+    }
+  }
+  return out;
+}
+
+function buildAll(): PortalPuzzleRow[] {
+  const picked: PortalPuzzleRow[] = [];
+  let n = 1;
+  for (const pat of ["A", "B", "C", "D"] as Pattern[]) {
+    const vs = variationsFor(pat).slice(0, 25);
+    for (const v of vs) {
+      picked.push(makeRow(`PP${String(n).padStart(3, "0")}`, v));
+      n++;
+    }
+  }
+  return picked;
+}
+
+export const PORTAL_PUZZLE_DB: PortalPuzzleRow[] = buildAll();

src/puzzles/portal-puzzles.ts

@@ -0,0 +1,56 @@
+import { type GameState, parseFEN, type PieceType } from "../engine/board";
+import { PORTAL_PUZZLE_DB, type PortalPuzzleRow } from "./portal-puzzle-db";
+
+export interface PortalPuzzle {
+  id: string;
+  fen: string;
+  wPortal: string | null;
+  bPortal: string | null;
+  creator: PieceType;
+  moves: string[];
+  themes: string[];
+  plies(): number;
+  mateIn(): 1 | 2;
+  setup(): GameState;
+}
+
+/** Convert an algebraic square string ("e4") to { file, rank }. */
+function alg(sq: string): { file: number; rank: number } {
+  const file = sq.charCodeAt(0) - 97; // 'a' = 0
+  const rank = parseInt(sq[1], 10) - 1; // '1' = 0
+  return { file, rank };
+}
+
+function makePortalPuzzle(p: PortalPuzzleRow): PortalPuzzle {
+  return {
+    id: p.id,
+    fen: p.fen,
+    wPortal: p.wPortal,
+    bPortal: p.bPortal,
+    creator: p.creator,
+    moves: p.moves,
+    themes: p.themes,
+    plies: () => p.moves.length,
+    mateIn: () => (Math.ceil(p.moves.length / 2) <= 1 ? 1 : 2) as 1 | 2,
+    setup(): GameState {
+      const state = parseFEN(p.fen);
+      state.portals = {
+        w: p.wPortal ? alg(p.wPortal) : null,
+        b: p.bPortal ? alg(p.bPortal) : null,
+      };
+      state.portalCreators = { w: p.creator, b: p.creator };
+      return state;
+    },
+  };
+}
+
+export const PORTAL_PUZZLES: PortalPuzzle[] = PORTAL_PUZZLE_DB.map(makePortalPuzzle);
+
+export function filterPortalPuzzles(opts: {
+  mateIn?: 1 | 2 | "all";
+}): PortalPuzzle[] {
+  return PORTAL_PUZZLES.filter((p) => {
+    if (opts.mateIn && opts.mateIn !== "all" && p.mateIn() !== opts.mateIn) return false;
+    return true;
+  });
+}