A fully playable digital version of Qwirkle with online multiplayer via room codes (2-4 players) and local hotseat mode. Built with React + TypeScript frontend, WebSocket real-time sync, and a shared TypeScript game engine. Includes comprehensive testing with random fuzzing, heuristic agents, multiplayer integration tests, and a rules judge.

• Online Multiplayer: Create/join rooms with shareable codes, real-time gameplay, no login required
• Local Hotseat Mode: Pass-and-play on one device
• Server-Authoritative: All game logic runs server-side to prevent cheating
• Reconnect Support: Players automatically rejoin if they refresh or disconnect
• Deterministic Replay: Every game is reproducible from seed + action log
• Dark Theme UI: Polished interface with pan/zoom board

• 108 tiles: 6 colors (red, orange, yellow, green, blue, purple) x 6 shapes (circle, diamond, square, star, clover, cross) x 3 copies each.
• Starting player: Determined by who has the largest set of tiles sharing one attribute (color or shape) with no duplicates. Tie-break: lower seat index.
• Trading: You may trade 1 to N tiles where N = min(hand size, bag size). You draw replacements first, then traded tiles are shuffled back into the bag.
• Forced trade: If a player has no legal placements and the bag is not empty, they must trade.
• Endgame: When the bag is empty, players do not refill. The first player to empty their hand gets +6 bonus points. If all remaining players are stuck (no legal placements and bag is empty), the game ends immediately.
• Scoring: Each tile placed scores 1 point per tile in each line it participates in (horizontal and vertical). A single isolated tile scores 1 point. A Qwirkle (line of 6) scores 6 + 6 bonus = 12.
• Lines: Maximum length 6. A color line has all same color with distinct shapes. A shape line has all same shape with distinct colors. No duplicates allowed.
• Placement: All tiles played on a turn must be in the same row or column, must be contiguous (gaps allowed if filled by existing board tiles), and must connect to the existing board (except the first move).

qwirkle/
├── shared/src/          # Core game engine (TypeScript)
│   ├── types.ts         # All types, constants, helpers
│   ├── rng.ts           # Seeded PRNG (xoshiro128**)
│   └── engine.ts        # Game engine, validation, scoring, replay
├── frontend/src/        # React + Vite frontend
│   ├── hooks/useGame.ts # Game state management hook
│   ├── components/      # UI components (Board, Hand, Controls, etc.)
│   └── App.tsx          # Main app
├── backend/src/         # Express API server (optional)
│   └── server.ts        # REST API for game management
├── simulation/src/      # Testing infrastructure
│   ├── runner.ts        # Fuzz test runner (random + heuristic)
│   ├── random-agent.ts  # Random legal move agent
│   ├── heuristic-agent.ts # Greedy score-maximizing agent
│   ├── judge.ts         # Rules oracle / LLM judge
│   ├── replay.ts        # Deterministic replay CLI
│   └── regression-runner.ts # Regression test runner
├── tests/regressions/   # Auto-populated regression tests
└── package.json

• Node.js 20+
• npm

npm install
cd frontend && npm install && cd ..

# 1. Build the frontend
npm run build

# 2. Start the server
npm run server

Opens at http://localhost:3001. Features:

• Online multiplayer via room codes
• WebSocket real-time sync
• Server-authoritative game logic
• Auto-reconnect on disconnect

Usage:

1. Click "Create Room" → share room code with friends
2. Others click "Join Room" → enter code
3. All players click "Ready" → host starts game
4. Play turns in real-time!

npm run dev

Opens at http://localhost:5173/local.

• No server needed
• Pass device between players
• Pure client-side gameplay

npm run build

Outputs to dist/ for static hosting.

npm test

npm run test:all

Runs: 200 random games + 100 heuristic games + 50 judge-checked games + all regressions.

npx tsx simulation/src/runner.ts <agent> <numGames> <numPlayers> <startSeed>
# Example: npx tsx simulation/src/runner.ts random 1000 4 1

Every game can be replayed from its seed and action log:

# In the web UI, click "Replay" to download a replay JSON
npx tsx simulation/src/replay.ts path/to/replay.json

• Room Codes: 5-character codes (e.g., "ABCDE") from safe alphabet (no confusing chars)
• No Logins: Players identified by UUID + secret token stored in localStorage
• Auto-Reconnect: Tokens allow rejoining after disconnect/refresh
• TTL: Rooms expire after 2 hours of inactivity

REST Endpoints:

• POST /api/rooms - Create room (returns code, player credentials)
• POST /api/rooms/:code/join - Join room (returns credentials)
• GET /api/rooms/:code/snapshot - Get current state (auth required)

WebSocket Events (Client → Server):

• SET_READY - Toggle ready status
• START_GAME - Host starts game
• PROPOSE_ACTION - Submit play/trade action
• KICK_PLAYER - Host kicks player
• LEAVE_ROOM - Disconnect

WebSocket Events (Server → Client):

• ROOM_SNAPSHOT - Initial state on connect
• ROOM_UPDATED - Room state changed (player joined/ready/etc)
• GAME_STARTED - Game began, includes initial game state
• ACTION_APPLIED - Move executed, new game state
• ACTION_REJECTED - Invalid move (with reason)
• KICKED - You were removed from room
• ERROR - General error message

• All validation on server: Clients propose actions, server validates + applies
• Prevents cheating: Server is source of truth for game state
• State broadcast: After each action, server sends updated state to all clients
• Hand privacy: Each player only receives their own hand in snapshots
• Turn enforcement: Server rejects actions from non-current player

The simulation/src/multiplayer-test.ts runs automated tests:

• ✅ Invalid token rejection
• ✅ Turn enforcement (wrong player can't act)
• ✅ Reconnect preserves player state
• ✅ Full 2/3/4-player games with bot clients
• ✅ Duplicate name rejection

The engine checks these after every action:

1. Tile count conservation: 108 tiles always distributed across bag + hands + board
2. No duplicate tile IDs: Every tile has a unique ID tracked globally
3. Board line validity: No line exceeds 6, no duplicates within lines, all tiles share one attribute
4. Board connectivity: All board tiles form a single connected component
5. Hand size: Never exceeds 6
6. Score non-negativity: All scores >= 0
7. Turn synchronization: Turn counter matches action log length

1. Turn sync at endgame (turn_sync_endgame): The turn counter was not incremented when the game ended via the empty-hand + empty-bag path, causing a mismatch between state.turn and state.actionLog.length. Fixed by incrementing turn before setting gameOver. Regression test auto-generated.