two-keys/CLAUDE.md

# Two Keys: Co-op Mysteries for Couples

> Build spec for Claude Code. Read this whole file before writing any code.
> Game content lives in `content/games/*.yaml`. **Never hard-code puzzle answers in client code.**

## 1. What we're building

A website where **two players (a couple)** play co-op mystery games together. Each player sees **different information**, so neither can solve anything alone. They talk it out, pool clues, and enter answers into shared locks. Every lock solved earns a **key**. Enough keys unravel the mystery.

**Core rule of every game: Player A and Player B never see the same clue set.** Every lock needs info from both.

### Game library (18 games, 4 engines)

| # | Game | Category | Engine | File |
|---|------|----------|--------|------|
| 1 | Death at Vineyard Hollow | Murder Mystery | `story` | `vineyard-hollow.yaml` |
| 2 | The Last Set at the Blue Lantern | Murder Mystery | `story` | `blue-lantern.yaml` |
| 3 | Murder on the Southern Star | Murder Mystery | `story` | `southern-star.yaml` |
| 4 | The Clockmaker's Attic | Escape Room | `story` | `clockmakers-attic.yaml` |
| 5 | Signal Lost: Station Echo | Escape Room | `story` | `station-echo.yaml` |
| 6 | Tick Tock Together | Co-op Defuse | `defuse` | `tick-tock-together.yaml` |
| 7 | In Sync | Couples Connection | `sync` | `in-sync.yaml` |
| 8 | Labyrinth of Lanterns | Co-op Navigation | `labyrinth` | `labyrinth-of-lanterns.yaml` |
| 9 | Dead Air | Murder Mystery | `story` | `dead-air.yaml` |
| 10 | The Masquerade at Montague House | Murder Mystery | `story` | `masquerade-montague.yaml` |
| 11 | The Kalahari Expedition | Murder Mystery | `story` | `kalahari-expedition.yaml` |
| 12 | The Alchemist's Vault | Escape Room | `story` | `alchemists-vault.yaml` |
| 13 | Submerged: Deep Lab Nereid | Escape Room | `story` | `deep-lab-nereid.yaml` |
| 14 | The Kestrel Bank Job | Escape Room | `story` | `kestrel-heist.yaml` |
| 15 | Tick Tock: Overtime | Co-op Defuse | `defuse` | `tick-tock-overtime.yaml` |
| 16 | In Sync: Deep Cuts | Couples Connection | `sync` | `in-sync-deep-cuts.yaml` |
| 17 | The Drowned Catacombs | Co-op Navigation | `labyrinth` | `drowned-catacombs.yaml` |
| 18 | The Mirror Maze | Co-op Navigation | `labyrinth` | `mirror-maze.yaml` |

## 2. Tech stack

- **Monorepo** with npm workspaces: `client/`, `server/`, `shared/`, `content/`
- **Client:** Vite + React 18 + TypeScript + Tailwind CSS + React Router + `socket.io-client` + Framer Motion (subtle transitions only)
- **Server:** Node 20 + TypeScript + Express + Socket.io + `js-yaml` + `zod`
- **Shared:** TypeScript types + the answer normalizer (used by tests; the server is the only thing that checks answers)
- **Tests:** Vitest (server + shared), Playwright smoke test (optional, phase 6)
- **Storage:** In-memory room store, snapshotted to `server/data/rooms.json` every 10s and on shutdown so a restart doesn't kill a game in progress. Rooms expire after 24h idle.
- **Deploy target:** single Node process serves the built client + websocket (Render / Railway / Fly.io). No serverless, as we need persistent websockets.

### Folder structure

```
two-keys/
  CLAUDE.md
  GAMES.md                  # spoiler guide (designer reference, never served)
  package.json              # workspaces
  content/games/*.yaml      # all game content (source of truth)
  shared/src/
    types.ts                # Game, Chapter, Clue, Lock, Room, etc.
    normalize.ts            # answer normalizer
  server/src/
    index.ts                # express + socket.io bootstrap
    content/loader.ts       # loads + zod-validates YAML at boot
    content/sanitize.ts     # strips answers, filters clues by role
    rooms/store.ts          # in-memory store + snapshot
    rooms/codes.ts          # 5-char room codes (no 0/O/1/I)
    engines/story.ts
    engines/defuse.ts       # generator + solver
    engines/sync.ts
    engines/labyrinth.ts
    socket/handlers.ts
    scripts/validate-content.ts
  client/src/
    pages/Home.tsx Library.tsx Lobby.tsx Play.tsx Results.tsx HowToPlay.tsx
    engines/StoryGame/ DefuseGame/ SyncGame/ LabyrinthGame/
    components/ClueCard.tsx LockPanel.tsx KeyRing.tsx HintButton.tsx
               Notepad.tsx PartnerStatus.tsx Timer.tsx PassDeviceScreen.tsx
    lib/socket.ts session.ts theme.ts
```

## 3. Rooms, roles, and play modes

### Two-device mode (default)
1. Player creates a game from the library → server creates a room with a 5-char code (e.g. `K7MRX`) and a share link `/join/K7MRX`.
2. Creator picks role **A** or **B** (each game names its roles, e.g. "Inspector" / "Estate Insider"). Partner joins and gets the other role.
3. Game starts when both are in and both tap **Ready**.
4. Each browser stores `{roomCode, playerToken}` in `localStorage` (wrapped in try/catch) for **reconnect**. Refreshing the page rejoins the same seat.

### Couch mode (one device)
- One phone/laptop, both players. Role views alternate behind a **"Pass to [Role B name] 👀 (no peeking)"** cover screen with a tap-to-reveal.
- Locks and the key ring are visible in both views.

### Partner presence
- Show partner online/offline dot, which chapter they're viewing, and a **"Ping"** button (sends a little 👋 / 🔍 / 💡 / ❤️ reaction that floats on the partner's screen).
- **Shared notepad** synced live (debounced 300ms, last-write-wins is fine).
- No in-app chat. Couples are on the couch or on a call. Add a line on the lobby: "Best played on a call or side by side."

## 4. Content model (YAML → zod)

All game files share a header:

```yaml
id: string                # matches filename
engine: story | defuse | sync | labyrinth
category: murder-mystery | escape-room | co-op
title, tagline: string
estimatedMinutes: number
difficulty: 1-5
players: { min: 2, max: 2 }
theme: { primary, accent, background, headingFont }
roles: { A: {name, blurb}, B: {name, blurb} }
intro: markdown
```

### `story` engine (games 1–5, 9–14)

```yaml
rules:               # optional
  hintPenaltySeconds: number   # default 120
  timeLimitMinutes: number     # hard limit on elapsed + penalties; running out ends the game
  timeLimitLabel: string       # what the countdown is called, e.g. "Water level"
suspects:            # optional (murder mysteries)
  - { id, name, role, description }
chapters:
  - id, title, narrative (markdown, both players see it)
    clues:
      A: [Clue]      # only Player A ever receives these
      B: [Clue]      # only Player B
      shared: [Clue] # both
    lock:
      id, prompt
      inputType: code | text | choice
      format: string        # shown under the input, e.g. "4 digits", "HH:MM"
      options: [...]        # only for choice
      answers: [string]     # SERVER ONLY, any match = correct
      hints: [string, string, string]   # tier 1 nudge → tier 3 near-solution
      successText: markdown # revealed to both on unlock
      keyName: string       # name of the key earned, e.g. "Cellar Key"
finale:
  type: accusation | escape
  prompt
  # accusation only:
  questions: [{ id, label, options: [{id, label}], answer }]  # answer SERVER ONLY
  maxAttempts: number
  failEnding, reveal: markdown
  # escape only:
  clues: { A: [Clue], B: [Clue] }   # finale gets its own split clues
  lock: Lock                        # same shape as a chapter lock (no keyName needed)
  # both:
  successEnding: markdown
  failEnding: markdown              # optional on escape: shown when the time limit runs out
```

Use a zod discriminated union on `finale.type`.

**Clue object:** `{ id, title, type, body, signal? }`
- `type` ∈ `note | letter | document | report | log | table | photo | map | transcript | signal | diagram`
- `body` is markdown (tables allowed). Render each type with its own card style:
  - `note`: handwritten-ish (Caveat font), slight rotation
  - `letter`: paper texture, serif
  - `report` / `document` / `log`: typewriter / monospace header strip
  - `photo`: polaroid frame; body text is the photo description in italics (no image assets needed)
  - `map` / `diagram`: monospace block, preserve whitespace, grid tables
  - `signal`: animated blinking light driven by `signal` field (see §6.3)
- Clues from **previous** chapters stay accessible in an "Evidence Locker" drawer. The locker searches clue titles and bodies (client-side, own clues only), filters by chapter, and lets each player star clues (`clue:pin`). The partner only ever gets the **count** of stars, never which clues.
- Clue text uses `Noto Sans Symbols 2` as a fallback (Braille, alchemy symbols). Code fences (stencil grids, box-drawing keypads, SQL) are monospace at `line-height: 1.15`; wide tables and blocks scroll inside their card, never the page.

### Other engines
See each YAML for its schema. Summaries in §6.

## 5. Security & answer checking (important)

- The server loads YAML and keeps the full version in memory.
- `sanitize.ts` builds the **per-role payload**: removes every `answers`, `answer`, `solution`, finale `answer` field, and removes the *other* role's clues. Write a unit test asserting no sanitized payload contains any answer string.
- Also strip per engine: **defuse** → Technician never gets `manual`, Expert never gets the device state; nobody gets `fixtures` or computed solutions. **labyrinth** → Explorer never gets `grid`, `glyphs`, `lanterns` positions; Navigator never gets the Explorer's coordinates. **sync** → never send the partner's answer until both have answered. **signal clues** → send the `signal` pattern only for clues of type `signal`, and the client must never print it as text.
- Hints are only sent once revealed (never ship unrevealed hint tiers to the client).
- **Only the server checks answers.** Client sends `lock:submit {lockId, value}`.
- **Normalizer** (`shared/normalize.ts`): uppercase → strip accents → remove everything except `A-Z0-9`. So `"20:40"`, `"20 40"` → `2040`; `"Fire Swart, Friday!"` → `FIRESWARTFRIDAY`. Compare normalized input to each normalized entry in `answers`.
- Rate-limit submissions: max 1 per 2s per room per lock; after 5 wrong answers on one lock, show "Need a hint?" nudge.

## 6. Engines

### 6.1 Story engine (games 1–5)
- State: `currentChapter`, `keys[]`, `hintsUsed{lockId: tier}`, `wrongAttempts{}`, `startedAt`, `penaltySeconds`, `finaleAttempts`.
- Chapter view: narrative on top → my clues → lock panel → key ring.
- Correct answer → both players see the lock spring open (animation), `successText` reveals, the key flies onto the key ring, **Continue** button (either player can press) advances both.
- **Hints:** either player can request; tiers unlock in order; both players see revealed hints. Each hint adds **+2:00** penalty (or the game's `rules.hintPenaltySeconds`). Confirm dialog before revealing tier 3 ("This basically solves it. Sure?").
- **Time limit:** games with `rules.timeLimitMinutes` show a countdown instead of a stopwatch. When elapsed + penalty time passes the limit, the server ends the game with `failEnding` (plus `reveal` for an accusation) and the results page shows **Out of time** instead of a rank. A `timeLimitLabel` containing "water" (Deep Lab Nereid) also draws the countdown as water rising behind the header (no wave with `prefers-reduced-motion`).
- **Finale:** when all chapter keys are collected, the finale opens. For `accusation`, both players must agree: Player A proposes answers, Player B sees them and taps **Agree** or **Change**. Submit only when both agree. Wrong submission shows "Not quite. N attempts left" without revealing which part was wrong. After `maxAttempts`, show `failEnding` + `reveal`. Any number of questions works. On the last attempt (always, with `maxAttempts: 1`) submitting asks "One shot. Are you both sure?" first.
- For `escape` finales, it's just the last lock; on success show `successEnding`.

### 6.2 Defuse engine (game 6). See `tick-tock-together.yaml`
- Player A (**Technician**) sees the device. Player B (**Expert**) sees only the manual.
- Server **generates** each device from a seeded RNG and computes the solution with a **solver implementing the manual rules exactly**. Never generate a device the solver can't solve.
- Implement the fixtures in the YAML as unit tests. They must pass.
- Strikes: 3 per level. Timer per level. Clock speeds up 25% after each strike.
- Each level cleared = 1 key. Fail a level → retry with a new seed (no key lost).
- **Rulesets:** each manual's rules are code in `engines/defuse.ts`, picked by the YAML's `ruleset` (`classic` = Tick Tock Together, `overtime` = Tick Tock: Overtime). A new manual needs a new ruleset.
- **Overtime** adds indicator lights, a per-level `strikesOverride`, and three modules: `passwords` (cycle five letter columns, submit the one listed word they spell), `morse` (read a blinking light, tune 3.500–3.600 MHz, transmit) and `simon` (press the mapped colour for every flash; the mapping moves with the strike count). The Technician gets the Morse pattern only as a light, and only the flashes of the current stage.

### 6.3 Signal clues (game 5)
`signal: "./-.-./..../---"`: `.` = 250ms on, `-` = 750ms on, 250ms gap between symbols, `/` = 1000ms gap between letters, 3000ms pause, then loop. Render as a glowing circle. Add a "Replay" button. Never render the dot/dash text to that player (they must read the light).

### 6.4 Sync engine (game 7). See `in-sync.yaml`
- Rounds of 5 questions. Both answer privately; answers reveal simultaneously with a flip animation.
- `match` rounds: both pick from the same options. Match = point.
- `predict` rounds: the `subject` role answers about themselves, the other guesses. Match = point.
- 3+ points in a round = key. Failing a round lets them replay it once with fresh questions.
- Draw questions randomly from the bank, never repeating within a session. (When a `predict` bank is too small for that, a question may come back once, asked about the other partner.)
- `telepathy` rounds (Deep Cuts): no options, both type one word (max 30 characters). Same word = point; case, spaces, punctuation and a trailing S are ignored.
- `rank` rounds (Deep Cuts): the subject (cycled through `subjectPattern`) orders four items (drag, or up/down buttons), the partner predicts. Point only if **both** the top and the bottom match; the reveal highlights both.
- A round can set its own `pointsForKey`.

### 6.5 Labyrinth engine (game 8). See `labyrinth-of-lanterns.yaml`
- Player B (**Explorer**) sees only their current cell: four direction buttons (disabled where wall), glyph on the floor if any, key if present.
- Player A (**Navigator**) sees the full map with glyphs, keys, traps, and exit, but **NOT** the Explorer's position. The Navigator has to work out where they are from what the Explorer describes.
- Traps are invisible to the Explorer. Stepping on one sends them back to Start (keys kept) and adds 1:00 penalty.
- Each lantern key collected = key. Exit only opens with all 3.
- Server validates every move.
- `lanternsRequired` sets how many lanterns the maze has (default 3).
- `oneWay` gates (Drowned Catacombs): passable from `{x, y}` in `dir` only. The Navigator sees an arrow; the Explorer sees the way back as a gate, not a wall.
- `explorer.compass: relative` (Mirror Maze): the Explorer moves forward/left/right/back from the way they face (their last step), and never sees N/E/S/W.
- `navigatorView.mapTransform: mirror-x` (Mirror Maze): the Navigator's map, and everything on it, is served flipped left to right.

## 7. Socket events

Client → server:
`room:create {gameId}`, `room:join {code, playerToken?}`, `room:pickRole {role}`, `room:ready`,
`lock:submit {lockId, value}`, `hint:request {lockId}`, `clue:pin {clueId}`, `chapter:continue`,
`finale:propose {answers}`, `finale:agree`, `finale:submit`,
`defuse:action {moduleId, action}`, `sync:answer {questionId, optionId | text | order}`,
`maze:move {dir}` (`n/e/s/w`, or `f/l/r/b` / `forward/left/right/back` with a relative compass), `notepad:update {text}`, `ping {emoji}`

Server → client:
`room:state` (full sanitized per-role state, sent on every change), `lock:result {lockId, correct}`,
`toast {message}`, `ping {from, emoji}`, `error {code, message}`

Keep it simple: after any mutation, broadcast a fresh per-role `room:state` to each socket.

## 8. Scoring & results

- `finalTime = elapsed + penaltySeconds`
- Rank badges: **Soulmate Sleuths** (no hints, under estimate) / **Dream Team** / **Getting There** / **Love Is Patient** 😅 / **Out of time** (a time limit ran out)
- **Nightmare Survivors ☠️**: a difficulty-5 game finished with zero hints. Shown on the results page and, once earned, on that game's library card.
- Results page: time, hints used, keys earned, wrong guesses, plus a "Play another" carousel. Store best results per game in localStorage.

## 9. Design direction

- Vibe: **date-night cozy meets noir**. Dark mode default, warm candlelit accents, per-game theme from YAML `theme`.
- Fonts: Playfair Display / Inter / Caveat (handwritten notes) / JetBrains Mono (logs, maps) from Google Fonts.
- Home page: hero "Two players. One mystery. Every key needs both of you." + game library grid (cards show category chip, time, difficulty 🔑 out of 5; difficulty 5 adds a **☠️ Nightmare** chip). Difficulty: 1 Easy · 2 Medium · 3 Hard · 4 Expert · 5 Nightmare. The library sorts easiest first and filters by category and difficulty.
- **Mobile-first.** Most couples will play on two phones. Clue cards stack vertically; lock panel is sticky at the bottom; evidence locker is a bottom sheet.
- Accessibility: all locks keyboard-operable, `prefers-reduced-motion` respected, colorblind-safe (defuse wires also show their color name as text label).
- Role color-coding: A = warm (amber), B = cool (teal), shown as a badge on every clue card ("Only you can see this").

## 10. Content validation script

`npm run validate-content` must check:
- Every YAML parses and passes its engine's zod schema
- Story: every chapter has ≥1 clue for A **and** ≥1 for B; every lock has ≥1 answer and exactly 3 hints; finale answers exist in options; clue ids are unique; every signal clue has a `signal`; escape finales have A and B clues
- Defuse: all fixtures solve to their expected solution (with the game's ruleset); every module a level uses is defined; for `overtime`, the keypad columns, password words and Morse frequencies match the solver's tables (`OVERTIME_TABLES`) and every password fixture column has exactly `lettersPerColumn` letters
- Labyrinth: grid rows equal length; exactly one S and E; exactly `lanternsRequired` K; every K and E reachable from S **without stepping on a trap** (BFS, respecting one-way gates); no cell where a gate leaves the Explorer stuck for good; glyphs and gates never on walls or traps; every `lanterns` entry sits on a K
- Sync: ≥15 questions per round type in use; every rank question has exactly 4 items; no option that looks split by an unquoted comma (quote any option or label containing a comma)
- Choice options (`{ id, label }`) are strict, so a stray key from an unquoted comma fails validation
Run it in CI and as a pre-start step.

## 11. Build phases (do in order, commit after each)

1. **Scaffold** monorepo, shared types, normalizer + tests, YAML loader + zod schemas + validate script.
2. **Rooms**: create/join/role/ready/reconnect, lobby UI, home + library pages.
3. **Story engine** end-to-end with `vineyard-hollow`. Then confirm games 2–5 load and play with no code changes.
4. **Hints, timer, penalties, finale agreement flow, results page.**
5. **Defuse, Sync, Labyrinth** engines.
6. Couch mode, notepad, pings, polish, theming, mobile QA, Playwright smoke test (two browser contexts complete Clockmaker's Attic).

## 12. Acceptance criteria

- [ ] Two phones can play any of the 18 games start to finish
- [ ] Player A cannot find B's clues or any answer via DevTools / network tab
- [ ] Refreshing mid-game rejoins the same role and progress
- [ ] All answers listed in the YAML are accepted; normalizer handles spaces/case/punctuation
- [ ] `npm run validate-content` passes; all unit tests pass
- [ ] Works at 375px wide with no horizontal scroll