init: scaffold duplicate_chess project and design spec

Local browser sandbox for "duplicate chess" — a four-player coupled-board chess variant invented by Andrew Freiberg. Scaffold per CREATE_PROJECT.md plus the approved design spec from this session's brainstorming. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-19 00:08:50 -04:00
commit 9611c0ae0e
5 changed files with 504 additions and 0 deletions
@@ -0,0 +1,7 @@
 node_modules/
 dist/
 .superpowers/
 .DS_Store
 *.local
 *.tsbuildinfo
 GITEA_API.md
@@ -0,0 +1,44 @@
 # Duplicate Chess
 > Local browser sandbox for "duplicate chess" — a four-player coupled-board chess variant.
 ## Start Here
 **Read the latest handoff first:** `.claude/handoffs/` (most recent file).
 It has session state, in-progress work, and ordered next steps.
 Then check `IDEA.md` for the project brief, `DECISIONS.md` for settled choices, and
 `docs/superpowers/specs/2026-05-19-duplicate-chess-design.md` for the full design.
 ## Project Identity
 A digitization of "duplicate chess," a four-player chess variant invented by Andrew
 Freiberg (Seth's father — also the inventor of the blind-chess variant behind the
 sibling `blind_chess` project). Four players (North, South, East, West) and four
 boards (NW, NE, SW, SE); each player controls one colour on two boards and must play
 the identical algebraic move on both. A captured piece leaves a frozen, capturable
 "ghost" twin on the player's other board. Every individual board always remains a
 legal game of orthodox chess.
 This project is a **local, single-operator sandbox/visualizer**: one screen, all four
 boards, an engine that enforces the synchronized-move coupling, renders ghosts, and
 detects the endgame. Its purpose is to let the variant be *seen* and studied — the
 inventor's own point is that it cannot be understood from prose alone.
 ## Current State
 - **Phase:** spec complete; implementation not started.
 - **Repo:** `git.sethpc.xyz/Seth/duplicate_chess`.
 - **Deploy target:** n/a — runs locally (`pnpm dev`).
 - **Stack:** Vite + Svelte 5 + TypeScript, `chess.js`. Single package; engine in
  `src/engine/` (pure, DOM-free, vitest-tested), UI in `src/lib/`.
 - **Next:** implementation plan via the writing-plans skill, then build.
 ## Conventions
 - Inherits homelab conventions from `~/bin/CLAUDE.md` (gitea CLI, conventional
  commits, `.claude/handoffs/` for session state).
 - The engine (`src/engine/`) is DOM-free and the single source of truth for game
  state. The UI never computes legality itself.
 - Provisional endgame rules are marked PROVISIONAL in the spec — they are Claude's
  chosen defaults, not Andrew's rulings. Flag them if revisited.
@@ -0,0 +1,31 @@
 # DECISIONS.md — Duplicate Chess Decision Log
 Project-specific decisions. For global/cross-cutting decisions, see `~/bin/DECISIONS.md`.
 Format: `YYYY-MM-DD: <decision> — <why>`
 ## Architecture
 2026-05-19: First deliverable is a local single-operator sandbox/visualizer, not a networked game — the inventor's stated need is to *see* a mock game to comprehend the variant; networked four-player play is a separable later project.
 2026-05-19: Single Vite + Svelte 5 + TS app, no server — duplicate chess is perfect-information, so the whole engine and all four boards live client-side. No pnpm workspace (unlike blind_chess, which needs a server as its trusted view boundary).
 2026-05-19: Engine lives in a pure, DOM-free `src/engine/` tree (vitest-tested); Svelte UI in `src/lib/`. Keeps the coupled-legality logic isolated and portable if a networked version is ever built.
 2026-05-19: Engine = 4× `chess.js` + an intersection layer. A player's legal moves = the moves legal on *both* their boards, keyed by `(from,to,promotion)`. Ghost immobility, the synchronized-checkmate definition, and en-passant/castling divergence all fall out of the intersection — no special-case code.
 2026-05-19: Authoritative game state is an ordered list of synchronized moves; "replay to ply N" rebuilds all four `chess.js` boards. Powers undo and history scrubbing.
 ## Implementation
 2026-05-19: Compass UI — four boards rendered as 45° diamonds in an X/pinwheel (NW 225°, NE 135°, SW 315°, SE 45°), players seated in the four V-notches, pieces rotate *with* their board so each player's army faces their seat. Confirmed against Andrew's sketch (`USERFILES/4personchess.png` in blind_chess).
 2026-05-19: Four player colours (one per player) instead of White/Black fill — makes two-board ownership readable at a glance.
 2026-05-19: Intersection highlighting (teaching mode) — grabbing a piece shows playable squares (legal on both boards) AND board-local-only squares, so the coupling is visible.
 2026-05-19: Coordinate notation (`e2e4`) for the move log, not SAN — SAN's disambiguation differs between a player's two boards once they diverge, so it cannot be the single identical token.
 2026-05-19: Click-to-move, not drag — cleaner on rotated boards.
 2026-05-19: Provisional endgame rules picked by Claude, marked PROVISIONAL — Andrew can revise. First terminal event ends the game; any no-synchronized-move stalemate ends the game with all four drawing; threefold/50-move tracked on the whole four-board system; insufficient material not auto-detected.
 ## Deferred / Rejected
 2026-05-19: Networked four-player play — deferred; separable later project, would reuse the `src/engine/` tree.
 2026-05-19: AI opponents — deferred; the sandbox is operator-driven.
 2026-05-19: Free position editor — rejected for v1; play-from-start + history scrubbing keeps every shown position reachable by legal play, preserving the "every board is real chess" invariant.
 2026-05-19: Counter-rotating pieces upright on the diamonds — rejected; pieces rotate with their board so each player's army faces their seat (the point of the compass).
 2026-05-19: Deployment behind Caddy — deferred; v1 runs locally, the static build can be hosted later trivially.
 2026-05-19: A separate "dual view" of the on-move player's two boards — rejected; the compass is the whole UI, with the triple-highlight happening directly on it.
@@ -0,0 +1,42 @@
 # IDEA.md — Duplicate Chess
 ## What is this?
 A local, browser-based sandbox/visualizer for **"duplicate chess"** — a four-player
 chess variant invented by Andrew Freiberg (Seth's father). This project is to
 duplicate chess what the sibling `blind_chess` project is to blind chess: a
 digitization that lets an otherwise hard-to-play variant actually be played and
 studied.
 Duplicate chess: four players — North, South, East, West — and four chessboards set
 up between adjacent compass points (NW, NE, SW, SE). North and South play White;
 East and West play Black. Each player controls one colour on **two** boards (North =
 White on NW and NE; West = Black on NW and SW; and so on). Turn order is N → S → E → W.
 The defining rule: on your turn you make the **identical algebraic move on both of
 your boards**. A move is legal only if it is legal on both. When one of your pieces
 is captured on one board, its twin on your other board freezes into a **"ghost"** —
 it can never move again (no synchronized move exists for it), but it still occupies
 its square, blocks lines, can give discovered check, and can itself be captured.
 Every individual board always remains a legal game of orthodox chess.
 ## Problem it solves
 In the inventor's own words, the variant can't be grasped from prose: "this is not
 really a variant that can be understood verbally after a certain point ... diagrams
 are probably essential." The physical game is fiddly to set up and play. This tool
 puts all four boards on one screen, enforces the synchronized-move coupling, renders
 ghosts, and shows *why* a move is or isn't legal — so the variant can be seen.
 ## Constraints / preferences
 - Local, single-operator tool. No server, no networking, no accounts — duplicate
  chess is perfect-information, so one screen shows the whole game truthfully.
 - Stack: Vite + Svelte 5 + TypeScript, `chess.js` per board. Single package.
 - Sibling project to `blind_chess`; same homelab conventions.
 - v1 is a visualizer/sandbox. Networked four-player play and AI opponents are
  explicitly out of scope for now.
 See `docs/superpowers/specs/2026-05-19-duplicate-chess-design.md` for the full design,
 and `USERFILES/4-person-chess.txt` in the `blind_chess` repo for the original
 inventor conversation this is based on.
@@ -0,0 +1,380 @@
 # Duplicate Chess — Design Spec
 **Date:** 2026-05-19
 **Status:** Approved (brainstorming complete); ready for implementation planning.
 **Author:** Claude + Seth, from a brainstorming session based on the inventor
 conversation in `blind_chess/USERFILES/4-person-chess.txt`.
 ---
 ## 1. Overview
 Duplicate chess is a four-player chess variant invented by Andrew Freiberg. This
 project is a **local, single-operator, browser-based sandbox/visualizer** for it —
 the digital equivalent of what `blind_chess` did for blind chess. One operator
 drives all four players; the tool enforces the rules, renders the state, and shows
 *why* moves are or are not legal. Its purpose is comprehension: the inventor's stated
 position is that the variant cannot be understood from prose, only from seeing it
 played.
 **Key property — perfect information.** Unlike blind chess, duplicate chess hides
 nothing. Every player sees all four boards. There is therefore no view filter and no
 trusted server boundary: the whole engine and UI run client-side in one app.
 ---
 ## 2. The variant — rules
 ### 2.1 Setup
 - Four players: **North, South, East, West**.
 - Four boards, one between each adjacent pair of compass points: **NW, NE, SW, SE**.
 - North and South play **White**; East and West play **Black**.
 - Each player controls one colour on **two** boards:
  | Board | White player | Black player |
  |-------|--------------|--------------|
  | NW    | North        | West         |
  | NE    | North        | East         |
  | SW    | South        | West         |
  | SE    | South        | East         |
 - Every board starts from the standard chess position.
 ### 2.2 Turn order and the synchronized move
 - Turn order is **N → S → E → W**, repeating.
 - On your turn you make **one move**, applied **identically to both of your boards**
  (same from-square, same to-square, same promotion piece).
 - A move is **legal only if it is legal on both** of your boards. If it is not legal
  on both, you may not play it.
 - "Identical" means identical algebraic coordinates. The two boards may differ in
  what the move *does* (a capture on one board, a quiet move on the other) — that is
  the normal source of divergence.
 ### 2.3 Ghosts
 - When one of your pieces is captured on one board, its **twin** on your other board
  becomes a **ghost**: it can never move again, because no synchronized move exists
  for it (its counterpart is gone).
 - A ghost is **not removed**. It still occupies its square, blocks lines, defends
  squares, can produce a discovered check, can restrict enemy king movement, and can
  itself be captured (if that capture is a legal synchronized move for the capturing
  player).
 - Ghost status is a **one-way, three-state lifecycle** for every original piece-pair:
  (1) both twins alive and moving in lockstep → (2) one captured, one ghost → (3)
  both gone. There is no recursion: once a twin is captured there is no surviving
  counterpart to generate further ghosts.
 ### 2.4 Check, checkmate, stalemate
 - Each individual board, viewed in isolation, is always a legal game of orthodox
  chess. The single exception is the definition of checkmate (below).
 - **Checkmate** = a player to move is in check on at least one of their boards and
  has **no synchronized legal move**. A board viewed alone might show an escape, but
  if that escape cannot be duplicated on the other board, the player is mated.
 - **Stalemate** = a player to move is **not** in check and has no synchronized legal
  move.
 ### 2.5 Special moves
 - **Castling**: allowed only if legal on both of the player's boards.
 - **Promotion**: a synchronized pawn advance to the last rank promotes on both
  boards, necessarily to the **same piece**.
 - **En passant**: handled by the general rule — the move is legal iff the identical
  `(from,to)` is legal on both boards; it may be an en-passant capture on one board
  and a different (or illegal) move on the other.
 ### 2.6 Result
 - The winner is the player who delivers checkmate; the loser is the player mated;
  the other two draw. It is possible for everyone to draw.
 - See §6 for the **provisional** rulings on cases the inventor conversation left
  underspecified.
 ---
 ## 3. Architecture
 A **single Vite + Svelte 5 + TypeScript** application. No server, no pnpm workspace.
 ```
 duplicate_chess/
  src/
    engine/        pure TypeScript, DOM-free, vitest-tested
      boards.ts        board/player/turn-order constants and maps
      game.ts          DuplicateGame: state, move application, history
      legality.ts      synchronized-move intersection
      ghosts.ts        ghost derivation
      endgame.ts       checkmate / stalemate / draw detection
      notation.ts      coordinate notation, save/load JSON
      types.ts         shared engine types
    lib/           Svelte 5 components
      Compass.svelte       the four-board pinwheel
      Board.svelte         one board (rotatable, click-to-move, highlights)
      Panel.svelte         turn indicator, move log, legend, controls
      PromotionDialog.svelte
      stores/game.svelte.ts   reactive wrapper over the engine
    App.svelte
    main.ts
 ```
 - `chess.js` provides per-board orthodox chess: move generation, application,
  check detection, FEN.
 - The **engine is the single source of truth**. The UI never computes legality; it
  calls the engine and renders the result.
 - The engine is DOM-free so it is unit-testable and liftable into a package if a
  networked four-player version is ever built.
 ---
 ## 4. The engine
 ### 4.1 The core insight — intersection
 The coupled game reduces to an intersection. Hold four `chess.js` instances. On
 player `P`'s turn:
 ```
 movesA  = chess[boardA].moves({ verbose: true })   // P's moves on board A
 movesB  = chess[boardB].moves({ verbose: true })   // P's moves on board B
 synced  = movesA ∩ movesB   keyed by (from, to, promotion)
 ```
 `synced` **is** `P`'s legal move set. Three otherwise-hard rules need no special
 code:
 - **Ghosts cannot move** — a ghost on board A has no twin on board B, so no move
  from its square can appear in `synced`.
 - **Checkmate** — `synced` empty *and* `P` in check on ≥1 board. A board showing an
  un-synchronizable escape is handled automatically, because that escape is not in
  `synced`.
 - **En passant / castling divergence** — same `(from,to[,promotion])` or it is
  simply absent from `synced`.
 The turn order N→S→E→W also gives every individual board a clean White-then-Black
 alternation, so each `chess.js` instance stays internally consistent and
 `chess.moves()` always returns the moves of the player whose global turn it is.
 ### 4.2 Constants (`boards.ts`)
 ```
 BOARDS      = ['NW','NE','SW','SE']
 PLAYERS     = ['N','S','E','W']            // also the turn order
 PLAYER_BOARDS = { N:['NW','NE'], S:['SW','SE'], E:['NE','SE'], W:['NW','SW'] }
 PLAYER_COLOR  = { N:'w', S:'w', E:'b', W:'b' }
 BOARD_PLAYERS = { NW:{w:'N',b:'W'}, NE:{w:'N',b:'E'},
                  SW:{w:'S',b:'W'}, SE:{w:'S',b:'E'} }
 ```
 ### 4.3 State and the move list
 The authoritative state is an **ordered list of synchronized moves**:
 ```
 history: { player: Player, from: Square, to: Square, promotion?: PieceSymbol }[]
 ```
 `replayTo(n)` builds four fresh `chess.js` boards and applies the first `n` history
 entries (each entry applied to its player's two boards). This single function powers
 construction, **undo** (`replayTo(history.length - 1)`), and **history scrubbing**
 (`replayTo(k)` for view-only display). Making a new move while scrubbed truncates
 history after the scrub point — standard behaviour.
 `currentPlayer = PLAYERS[history.length % 4]`.
 ### 4.4 Legality (`legality.ts`)
 - `legalSyncedMoves(player) → Move[]` — the intersection from §4.1.
 - For the UI's triple-highlight, the engine also exposes, for a grabbed square `s`
  belonging to the current player: `movesA.from(s)`, `movesB.from(s)`, and the
  `synced` subset from `s`. The UI renders the `synced` subset as **playable**
  (green) on both boards and the board-local remainder as **legal-here-only**
  (grey). Grabbing a ghost therefore visibly yields zero playable moves.
 ### 4.5 Ghosts (`ghosts.ts`)
 Invariant: a player's **non-ghost** pieces always occupy identical squares on both
 their boards (they move in lockstep; a ghost is exactly a piece whose lockstep
 broke). Therefore:
 > A piece of player `P`'s colour on board A at square `s` is a **ghost** iff board B
 > (P's other board) has no `P`-colour piece at `s`.
 `ghosts() → { board, square }[]` over all four players. Used for rendering only;
 legality already excludes ghost moves via the intersection.
 ### 4.6 Endgame (`endgame.ts`)
 After each move, evaluate the next player `P`:
 - `synced` non-empty → game continues.
 - `synced` empty and `P` in check on ≥1 board → **checkmate**: `P` loses; each
  opponent on a board where `P` is in check is a **winner**; the remaining player(s)
  draw.
 - `synced` empty and `P` not in check → **stalemate**: game ends, all four draw
  (provisional — see §6).
 - **Global threefold repetition**: the combined key (four boards' piece placement +
  castling rights + en-passant squares, plus `currentPlayer`) has occurred three
  times → game ends, all draw.
 - **Global 50-move rule**: 50 full rounds with no capture and no pawn move on any
  board → game ends, all draw.
 The result is a per-player map of `'win' | 'draw' | 'loss'`. The game ends at the
 first terminal event.
 ### 4.7 Save / load (`notation.ts`)
 ```json
 { "variant": "duplicate-chess", "version": 1,
  "moves": [ { "player": "N", "from": "e2", "to": "e4" }, ... ] }
 ```
 Save = serialize `history` and trigger a file download. Load = parse and `replayTo`
 the full list. The move list is sufficient to reconstruct everything.
 ---
 ## 5. The UI
 ### 5.1 The compass
 Confirmed against the inventor's sketch (`blind_chess/USERFILES/4personchess.png`).
 - Four boards rendered as **45° diamonds** in an X / pinwheel.
 - Per-board rotation: **NW 225°, NE 135°, SW 315°, SE 45°**. Each rotation puts that
  board's White player's home rank on the edge facing their seat, oriented to read
  right-way-up from that seat (standard chess: your pieces near you, glyphs pointing
  away into the board).
 - Pieces rotate **with** their board — so each player's army faces their seat.
 - Players sit in the four V-notches between the diamonds: North top, East right,
  South bottom, West left.
 - The on-move player's two boards carry a coloured **turn-glow**.
 ### 5.2 Player colours
 Four distinct piece colours, one per player (one suggested palette: North blue,
 South red, East violet, West orange — final palette is an implementation detail).
 Recolouring rather than White/Black fill makes two-board ownership instantly
 readable: North's army is the same colour on both NW and NE. Pieces carry a dark
 outline so they stay legible on both square shades. Pieces may be Unicode glyphs for
 v1; a tintable SVG set is a possible upgrade.
 ### 5.3 Intersection highlighting (teaching mode)
 When the operator clicks (grabs) a piece belonging to the current player, both that
 player's boards highlight:
 - **Green dot** — a *playable* destination (legal on both boards; in `synced`).
 - **Grey dashed dot** — legal on *that board only*; the coupling forbids it.
 - **Cyan outline** — the grabbed square.
 This makes the divergence between a player's two boards directly visible, and is the
 reason the project exists. Clicking a destination plays the move; clicking elsewhere
 or the grabbed piece again cancels.
 ### 5.4 Ghosts
 Rendered in place at reduced opacity with a dashed ring in the owning player's
 colour.
 ### 5.5 Side panel
 - **Turn indicator** — whose move, ghost counts, check status.
 - **Move log** — coordinate notation, one row per round, four columns (N/S/E/W),
  one identical token per player (`e2e4`). SAN is not used: its disambiguation
  differs between a player's two boards once they diverge, so it cannot be the
  single identical token.
 - **Legend** — highlight meanings, ghost marker, the four player colours.
 - **Controls** — New game, Undo, Prev/Next (history scrubbing), Save, Load.
 ### 5.6 Move input and promotion
 - **Click-to-move**: click a piece → triple-highlight appears → click a destination.
  Click-to-move (not drag) is cleaner on rotated boards.
 - **Promotion**: when the chosen move is a pawn reaching the last rank, a dialog
  picks the piece; both pawns promote identically.
 ---
 ## 6. Provisional endgame rules
 The inventor conversation fully specifies the common ending (first checkmate → one
 winner, one loser, two draws) but leaves edge cases open. The operator chose to ship
 **provisional defaults now**, clearly marked, for Andrew to revise later. These are
 **PROVISIONAL — Claude's defaults, not Andrew's rulings**:
 | Case | Provisional ruling |
 |------|--------------------|
 | **Single-player stalemate** (no synchronized move, not in check) | The whole game ends; all four players draw. No frozen-board continuation — this keeps the engine free of multi-player-elimination logic and matches "it is possible for everyone to draw." |
 | **Double-board checkmate** (mated while in check on both boards, by both opponents) | Both checking opponents are recorded as winners; the mated player loses; the fourth player draws. Generalizes "the winner is the one who checkmates" without a tiebreak. |
 | **Threefold repetition / 50-move** | Evaluated on the whole four-board system (all four positions + side-to-move), not per board. Triggers an all-draw game end. |
 | **Insufficient material** | Not auto-detected (rare and hard to define across four coupled boards). The operator may declare a draw manually. |
 Each provisional rule must be marked in code (a `PROVISIONAL` comment or constant)
 so a future ruling from Andrew can be located and applied cleanly.
 ---
 ## 7. Scope
 **In scope (v1):**
 - Play a full game from the standard start, operator-driving all four players.
 - The compass UI with pinwheel boards and four player colours.
 - Intersection (teaching-mode) highlighting.
 - Ghost detection and rendering.
 - Checkmate / stalemate / draw detection with the provisional rules.
 - Coordinate-notation move log.
 - Undo and history scrubbing.
 - Save / load a game to a JSON file.
 **Out of scope (v1):**
 - Networked four-player play (separable later project; would reuse `src/engine/`).
 - AI opponents (the sandbox is operator-driven).
 - A free position editor (play-from-start keeps every shown position reachable by
  legal play, preserving the "every board is real chess" invariant).
 - Insufficient-material auto-detection.
 - Deployment behind Caddy (the static build can be hosted later trivially).
 - Mobile-specific polish (four boards want a wide screen; desktop-first).
 ---
 ## 8. Testing
 - `src/engine/` is pure TypeScript with no DOM — covered by **vitest**:
  - synchronized-move intersection (including divergence, castling, en passant);
  - ghost derivation (lifecycle: lockstep → ghost → gone);
  - endgame detection (single- and double-board checkmate, stalemate, threefold,
    50-move);
  - history replay / undo / scrub correctness;
  - a scripted full game played to a terminal state.
 - Svelte components: `svelte-check` plus manual browser testing — same division of
  labour as `blind_chess` (no component test harness by design).
 ---
 ## 9. Open questions / future
 - **The provisional rules in §6** need Andrew's confirmation; the
  double-board-mate winner rule and the stalemate-ends-the-game rule are the two
  most consequential.
 - **50-move counting units** (rounds vs plies) — to be pinned during implementation;
  provisionally "50 rounds."
 - **Rotated-board ergonomics** — playing on a board rotated 135–225° is harder to
  read than an upright board. v1 ships the static pinwheel as drawn. If play proves
  awkward, a candidate enhancement is a click-to-focus that temporarily uprights the
  active player's two boards. Not in v1 scope.
 - **Networked four-player play** is the natural follow-on project and the reason the
  engine is kept DOM-free and self-contained.
 ---
 ## 10. Source material
 - `blind_chess/USERFILES/4-person-chess.txt` — the original inventor conversation
  defining the variant.
 - `blind_chess/USERFILES/4personchess.png` — Andrew's sketch of the compass layout.
 - Brainstorming mockups: `blind_chess/.superpowers/brainstorm/.../content/`
  (`layout-v6.html` is the approved compass layout).