blind_chess/CLAUDE.md

blind_chess

Web-based two-player chess where each player sees only their own pieces; the server acts as moderator.

Start Here

Read the latest handoff first: .claude/handoffs/ (most recent file).

Then check DECISIONS.md for settled choices, and docs/superpowers/specs/2026-04-28-blind-chess-design.md for the full design spec.

Project Identity

A digitization of a battleship-style chess variant. Two players, separated; a moderator who sees both boards and announces a fixed vocabulary of events ("Black has moved and captured", "Moving that piece will not help you", "White is in check"). The physical version requires three people; this version replaces the moderator with a server. Ships with both vanilla mode (full reveal — normal chess) and blind mode (the variation) on day one. Mode is a per-player view filter on a shared engine, not a different game.

The system's most distinctive property: highlighting in blind mode reveals zero opponent information. It's computed purely from (piece type, position, own-piece set) — a function whose signature literally cannot read opponent state. The moderator vocabulary is the only legitimate channel for opponent events.

Current State

• Phase: MVP deployed and live at https://chess.sethpc.xyz (2026-04-28).
• Repo: git.sethpc.xyz/Seth/blind_chess.
• Stack: Node 22 + TypeScript, Fastify + ws, Svelte 5 + Vite, chess.js. pnpm workspace with packages/{server,client,shared}.
• Deploy: LXC CT 690 on node-241 at 192.168.0.245, behind Caddy CT 600. Systemd unit blind-chess.service, port 3000. In-memory state only.
• Tests: 43 passing — 21 in shared (geometric helper), 22 in server (FSM + view + 4 real-WS integration).
• Known gaps (deferred): drag-and-drop input (click-to-move only), full integration coverage of every endgame path, mobile-specific polish, observability beyond /api/health.

Key files

• IDEA.md — original project brief (Seth's words)
• DECISIONS.md — locked architectural and gameplay decisions
• docs/superpowers/specs/2026-04-28-blind-chess-design.md — full design spec (data model, protocol, FSM, testing)
• packages/shared/src/geometric.ts — the zero-leak helper. The signature is the proof.
• packages/server/src/view.ts — buildView, the security boundary.
• packages/server/src/commit.ts — touch-move FSM (the spec's hierarchy decision table).
• packages/server/src/translator.ts — chess.js Move → moderator-vocabulary enum.
• deploy/blind-chess.service — systemd unit (canonical at /etc/systemd/system/blind-chess.service on the CT).
• deploy/Caddyfile.snippet — block already added to /etc/caddy/Caddyfile on CT 600.

Operations

• Logs: ssh root@192.168.0.245 'journalctl -u blind-chess -f'
• Restart: ssh root@192.168.0.245 'systemctl restart blind-chess'
• Health: curl https://chess.sethpc.xyz/api/health
• Deploy update: pnpm -r build → pnpm --filter @blind-chess/server deploy --prod --legacy .deploy-server → rsync server bundle to /opt/blind-chess/server/ and client dist/ to /opt/blind-chess/client/dist/ → chown -R blindchess:blindchess /opt/blind-chess → systemctl restart blind-chess. Server restart drops in-memory games (acceptable for MVP).

Conventions

• Inherits global homelab conventions from ~/bin/CLAUDE.md (gitea CLI, conventional commits, .claude/handoffs/ for session state).
• pnpm workspace; do not use npm/yarn lockfiles.
• All inter-package types live in packages/shared/. Never duplicate protocol types in client or server.
• Server is the single authority on game state. Client commit messages are requests, not facts.
• The view filter (buildView) is the only egress for board state. Don't bypass it.