Improve portal rules and puzzle UX

Author: Swon404

src/engine/__tests__/portal.test.ts

@@ -64,6 +64,30 @@ describe("Portal Chess: portal creation", () => {
     const ns = makeMove(s, cap[0]);
     expect(ns.portals?.b).toEqual([parseSquare("d5")]);
   });
+
+  it("Pawn on own portal blocks access and moving off does not consume it", () => {
+    const s = asPortal(parseFEN("4k3/8/8/8/8/8/4P3/4K1N1 w - - 0 1"));
+    s.portals = { w: [parseSquare("e2")], b: [], max: 1 };
+
+    const pawnMoves = legalMovesFrom(s, parseSquare("e2"));
+    expect(pawnMoves.some((m) => m.isPortalEntry)).toBe(false);
+    const up = pawnMoves.find((m) => sqEq(m.to, parseSquare("e3")));
+    expect(up).toBeDefined();
+
+    let ns = makeMove(s, up!);
+    expect(ns.portals?.w).toEqual([parseSquare("e2")]);
+
+    // Skip black's turn in this unit test and continue from white's side.
+    ns.turn = "w";
+    const ontoPortal = legalMovesFrom(ns, parseSquare("g1"))
+      .find((m) => sqEq(m.to, parseSquare("e2")));
+    expect(ontoPortal).toBeDefined();
+
+    ns = makeMove(ns, ontoPortal!);
+    ns.turn = "w";
+    const tele = legalMovesFrom(ns, parseSquare("e2")).filter((m) => m.isPortalEntry);
+    expect(tele.length).toBeGreaterThan(0);
+  });
 });
 
 describe("Portal Chess: teleport entry", () => {

src/engine/rules.ts

@@ -303,13 +303,12 @@ export function makeMove(state: GameState, move: Move): GameState {
   // Capture happens at move.to. Clear the destination square (handles capture).
   ns.board[move.to.rank][move.to.file] = null;
 
-  // Portal Chess (deferred warp): the portal under a non-creator piece is
-  // consumed when the piece leaves it (whether by normal move or teleport).
-  // The creator piece doesn't use portals, so its own movement never consumes
-  // a portal under it (the creator simply leaves it behind).
+  // Portal Chess (deferred warp): only non-pawn, non-creator pieces consume
+  // their own portal when leaving it (normal move or teleport). Pawns simply
+  // stand on portals and block access until they move away.
   if (ns.portals && ns.portalCreators) {
     const creator = ns.portalCreators[piece.color];
-    if (piece.type !== creator) {
+    if (piece.type !== "P" && piece.type !== creator) {
       const ownPortalAtFrom = ns.portals[piece.color].some((p) => sqEq(p, move.from));
       if (ownPortalAtFrom) {
         ns.portals[piece.color] = ns.portals[piece.color].filter((p) => !sqEq(p, move.from));

src/puzzles/portal-puzzle-db.ts

@@ -147,6 +147,86 @@ function isLight(s: string): boolean {
   return (sq.file + sq.rank) % 2 === 1;
 }
 
+const GENERIC_THEMES = new Set(["portal", "queen", "rook", "bishop", "knight", "mateIn1", "mateIn2"]);
+
+function candidateKey(c: RawCandidate): string {
+  return `${c.fen}|${c.wPortal ?? "-"}|${c.bPortal ?? "-"}|${c.moves.join(",")}`;
+}
+
+function motifOf(c: RawCandidate): string {
+  return c.themes.find((t) => !GENERIC_THEMES.has(t)) ?? "misc";
+}
+
+function spreadPick<T>(items: T[], count: number): T[] {
+  if (count <= 0 || items.length === 0) return [];
+  if (items.length <= count) return items.slice();
+  if (count === 1) return [items[Math.floor(items.length / 2)]];
+  const out: T[] = [];
+  for (let i = 0; i < count; i++) {
+    const idx = Math.round((i * (items.length - 1)) / (count - 1));
+    out.push(items[idx]);
+  }
+  return out;
+}
+
+function curateCandidates(valid: RawCandidate[], targetCount = 20): RawCandidate[] {
+  if (valid.length <= targetCount) return valid.slice();
+
+  const quotas: Record<string, number> = {
+    captureThenWarp: 5,
+    anastasia: 4,
+    "smothered-h6": 2,
+    "smothered-a6": 2,
+    rookLiftWhite: 4,
+    rookLiftBlack: 3,
+  };
+
+  const byMotif = new Map<string, RawCandidate[]>();
+  for (const c of valid) {
+    const motif = motifOf(c);
+    const arr = byMotif.get(motif) ?? [];
+    arr.push(c);
+    byMotif.set(motif, arr);
+  }
+  for (const arr of byMotif.values()) {
+    arr.sort((a, b) => candidateKey(a).localeCompare(candidateKey(b)));
+  }
+
+  const picked: RawCandidate[] = [];
+  const used = new Set<string>();
+  const take = (arr: RawCandidate[], n: number) => {
+    for (const c of spreadPick(arr, n)) {
+      const key = candidateKey(c);
+      if (used.has(key)) continue;
+      used.add(key);
+      picked.push(c);
+    }
+  };
+
+  for (const [motif, quota] of Object.entries(quotas)) {
+    const arr = byMotif.get(motif);
+    if (!arr || arr.length === 0 || quota <= 0) continue;
+    take(arr, Math.min(quota, arr.length));
+  }
+
+  if (picked.length < targetCount) {
+    const rest = valid.slice().sort((a, b) => {
+      const motifCmp = motifOf(a).localeCompare(motifOf(b));
+      if (motifCmp !== 0) return motifCmp;
+      return candidateKey(a).localeCompare(candidateKey(b));
+    });
+    for (const c of rest) {
+      if (picked.length >= targetCount) break;
+      const key = candidateKey(c);
+      if (used.has(key)) continue;
+      used.add(key);
+      picked.push(c);
+    }
+  }
+
+  return picked.slice(0, targetCount);
+}
+
 // ── pattern generators ──────────────────────────────────────────────────────
 
 /**
@@ -365,6 +445,72 @@ function genCaptureThenWarp(): RawCandidate[] {
   return out;
 }
 
+/**
+ * Pattern E — "Rook lift" (white to move).
+ *
+ * Black king is boxed on g8 by pawns f7/g7/h7. White rook stands on its own
+ * portal and teleports to e8 for immediate back-rank mate.
+ */
+function genRookLiftWhite(): RawCandidate[] {
+  const out: RawCandidate[] = [];
+  const fixed: Record<string, string> = {
+    "g8": "k",
+    "f7": "p",
+    "g7": "p",
+    "h7": "p",
+    "a1": "K",
+  };
+  const rookPortals = [
+    "b1", "c1", "d1", "e1", "f1", "h1",
+    "a2", "b2", "c2", "d2", "e2", "f2", "g2", "h2",
+  ];
+  for (const portal of rookPortals) {
+    const pieces = { ...fixed, [portal]: "R" };
+    const fen = `${fenPlacement(pieces)} w - -`;
+    out.push({
+      fen,
+      wPortal: portal,
+      bPortal: null,
+      moves: [`${portal}e8`],
+      themes: ["portal", "rook", "rookLiftWhite", "mateIn1"],
+    });
+  }
+  return out;
+}
+
+/**
+ * Pattern F — "Rook lift" mirror (black to move).
+ *
+ * White king is boxed on g1 by pawns f2/g2/h2. Black rook stands on its own
+ * portal and teleports to e1 for immediate back-rank mate.
+ */
+function genRookLiftBlack(): RawCandidate[] {
+  const out: RawCandidate[] = [];
+  const fixed: Record<string, string> = {
+    "a8": "k",
+    "g1": "K",
+    "f2": "P",
+    "g2": "P",
+    "h2": "P",
+  };
+  const rookPortals = [
+    "b8", "c8", "d8", "e8", "f8", "h8",
+    "a7", "b7", "c7", "d7", "e7", "f7", "g7", "h7",
+  ];
+  for (const portal of rookPortals) {
+    const pieces = { ...fixed, [portal]: "r" };
+    const fen = `${fenPlacement(pieces)} b - -`;
+    out.push({
+      fen,
+      wPortal: null,
+      bPortal: portal,
+      moves: [`${portal}e1`],
+      themes: ["portal", "rook", "rookLiftBlack", "mateIn1"],
+    });
+  }
+  return out;
+}
+
 // ── build ───────────────────────────────────────────────────────────────────
 
 function build(): PortalPuzzleRow[] {
@@ -375,11 +521,22 @@ function build(): PortalPuzzleRow[] {
     ...genKnightSmotherG(),
     ...genKnightSmotherB(),
     ...genCaptureThenWarp(),
+    ...genRookLiftWhite(),
+    ...genRookLiftBlack(),
   ];
-  const valid: PortalPuzzleRow[] = [];
-  let n = 1;
+
+  const validCandidates: RawCandidate[] = [];
   for (const c of candidates) {
     if (!validate(c)) continue;
+    validCandidates.push(c);
+  }
+
+  // Keep the portal set intentionally compact and varied.
+  const curated = curateCandidates(validCandidates, 20);
+
+  const valid: PortalPuzzleRow[] = [];
+  let n = 1;
+  for (const c of curated) {
     valid.push({
       id: `PP${String(n).padStart(3, "0")}`,
       fen: c.fen,

src/screens/NewGameScreen.tsx

@@ -145,8 +145,8 @@ export function NewGameScreen() {
             </label>
             <p className="hint">
               When ticked, teleport targets cannot be adjacent to any other piece.
-              When unticked (default), you can teleport anywhere empty &mdash; or stay
-              on the portal square (the portal remains active).
+              When unticked (default), you can teleport to any empty square
+              except the portal square itself.
             </p>
           </section>
         </>
@@ -197,6 +197,21 @@ export function NewGameScreen() {
         </section>
       )}
 
+      {showBlackName && (
+        <section>
+          <h3>Board orientation (2-player)</h3>
+          <label>
+            <input
+              type="checkbox"
+              checked={store.settings.autoFlip}
+              onChange={(e) => updateSetting("autoFlip", e.target.checked)}
+            />
+            {" "}Auto-turn board after each move
+          </label>
+          <p className="hint">Turn this off to keep the board fixed from White's side.</p>
+        </section>
+      )}
+
       {showLevel && (
         <section>
           <h3>Bot difficulty</h3>

src/screens/PuzzlesScreen.tsx

@@ -11,6 +11,7 @@ import {
   type PortalPuzzle
 } from "../puzzles/portal-puzzles";
 import { parseUci, parseSquare, type Square } from "../engine/board";
+import { gameResult } from "../engine/rules";
 
 type Status = "solving" | "wrong" | "solved";
 type MateFilter = "all" | 1 | 2 | 3;
@@ -84,6 +85,7 @@ export function PuzzlesScreen() {
 
   const pool: (Puzzle | PortalPuzzle)[] = mode === "portal" ? portalPool : stdPool;
   const puzzle = pool[index];
+  const sideToMate = useMemo(() => (puzzle ? puzzle.setup().turn : "w"), [puzzle?.id]);
   const totalSolved = activeProfile?.stats.puzzlesSolved ?? 0;
 
   const diffCounts = useMemo(() => {
@@ -152,7 +154,12 @@ export function PuzzlesScreen() {
       ok = false;
     }
 
-    if (!ok) {
+    // Accept alternative winning moves: if the user has just checkmated,
+    // count the puzzle as solved even when it differs from the scripted line.
+    const current = gameResult(state);
+    const solvedByMate = current.kind === "checkmate" && current.winner === sideToMate;
+
+    if (!ok && !solvedByMate) {
       setStatus("wrong");
       if (attemptedRef.current !== puzzle.id) {
         recordPuzzleAttempt(puzzle.id);
@@ -161,6 +168,13 @@ export function PuzzlesScreen() {
       return;
     }
 
+    if (solvedByMate) {
+      setStatus("solved");
+      recordPuzzleSolved(puzzle.id);
+      setPlayedPlies(moved);
+      return;
+    }
+
     const nextIdx = plyIndex + 1;
     if (nextIdx >= puzzle.moves.length) {
       setStatus("solved");
@@ -196,10 +210,10 @@ export function PuzzlesScreen() {
     if (!puzzle) return null;
     if (status === "solved") return <div className="puzzle-banner good">✅ Solved! Great job.</div>;
     if (status === "wrong") return <div className="puzzle-banner bad">❌ Not quite — tap Retry.</div>;
-    const side = puzzle.setup().turn === "w" ? "White" : "Black";
+    const side = sideToMate === "w" ? "White" : "Black";
     const done = alreadySolved ? " (already solved ✓)" : "";
     return <div className="puzzle-banner">You play {side}. Mate in {puzzle.mateIn()} — find the forced win.{done}</div>;
-  }, [status, puzzle, alreadySolved]);
+  }, [status, puzzle, alreadySolved, sideToMate]);
 
   const allSolvedHere = mode === "portal"
     ? basePortalPool.length > 0 && basePortalPool.every((p) => solvedIds.has(p.id))