docs: hand recorder design note (v1 core loop + card-entry UX)

Tap-to-build recorder: correctness by construction, reusable mount-agnostic module
(pure buildStructured core), pre-fill from live session state, emits the locked
structured-hand contract. V1 = core capture loop; card entry = contextual picker
with sticky-suit-or-rank-first flow + x/unknown. V2 = smart legal-action keypad.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/RECORDER.md

@@ -0,0 +1,148 @@
+# Hand recorder — design note
+
+A tap-to-build hand recorder. The point isn't "nicer input" — it's **correctness by
+construction**: every tap writes a known action into a known slot, so there's no parse
+step that can be wrong. It sidesteps the whole class of LLM-parse replay bugs. The text
+parser stays for importing the backlog (old notes, Trilium, ChatGPT history); the recorder
+is clean capture going forward.
+
+Output is the canonical structured shape in [HAND_HISTORY.md](HAND_HISTORY.md) — so it
+drops straight into the DB and the existing replay viewer, and flows to RTO unchanged.
+
+## Principles
+
+1. **Correctness by construction** — the UI only lets you build valid hands; the emitter
+   produces the contract shape; the server `normalize_structured()` is the final guarantee.
+2. **Reusable module, mount-agnostic.** Decision: overlay first, swap to standalone if the
+   overlay fights the chat page — *reusing the code either way*. So the recorder is a
+   self-contained module mounted into a container element, with the **emit logic kept pure
+   (no DOM)**. Moving overlay → standalone is a re-mount, not a rewrite.
+3. **Don't reinvent what Lyra knows.** Pre-fill from live session state.
+
+## Architecture
+
+```
+lyra/web/static/recorder.js     # the module: state machine + DOM shell + buildStructured()
+lyra/web/static/recorder.css    # scoped styles (full-screen table + keypad)
+```
+
+- `Recorder.mount(containerEl, { sessionId, onSave, onClose })` — instantiates into any
+  container. In V1 the container is a full-screen overlay `<div>` inside `index.html`
+  (chat/session page stays mounted underneath — a flip-over, not a route change). If that
+  proves janky, the *same module* mounts into `recorder.html` with zero logic changes.
+- **Pure core, separable from DOM:** `buildStructured(state) -> structuredDict`. No element
+  access — takes the in-memory state, returns the contract object. This is the testable,
+  reusable heart; the DOM shell only reads/writes `state` and calls `buildStructured` on save.
+
+## Pre-fill from live state (the "it already knows" feel)
+
+Source: `GET /session/data` (→ `poker.hud`). Today it gives us:
+- `session`: `venue`, `stakes`, `game`, `format`, `is_live`
+- `stack.current` → hero's starting stack for the hand
+- `villains[]`: `name`, `category`, `tendencies`, `last_note` (the players read this session)
+
+Derived in the recorder:
+- **Blinds** parsed from `stakes` ("1/3" → SB 1, BB 3) → auto-seed the `post` actions.
+- **Hero stack** from `stack.current`.
+
+**Two gaps to close as part of the build** (flagged, not yet done):
+1. **Seats aren't in the HUD bundle.** `player_reads` *has* a `seat` column, but
+   `_session_villains()` doesn't select it — so we can name the villains but not place them.
+   Fix: add `seat` (latest read per player) to the villains payload, then auto-seat them.
+   Until then, V1 seats known villains in read-order and you assign positions by tapping.
+2. **Hero position isn't tracked live** (button/seat moves every hand) — so `hero_pos` is a
+   per-hand tap, seeded to last-used. That's correct, not a gap to "fix", just noting it.
+
+## In-memory state model
+
+```js
+state = {
+  meta:   { game, stakes, venue, sessionId },      // from /session/data
+  blinds: { sb, bb },                              // parsed from stakes
+  heroPos: "BTN",                                  // tapped per hand
+  seats:  [ { pos, name, stack, cards: null, in: true } ],  // incl. hero seat
+  street: "preflop",                              // street currently being entered
+  board:  { flop: [], turn: [], river: [] },
+  actions:[ { street, pos, action, amount } ],     // appended as you tap
+  result: { pot: null, heroNet: null, summary: "" }
+}
+```
+
+`buildStructured(state)` →
+
+| contract field | from |
+|---|---|
+| `hero_pos` | `state.heroPos` |
+| `hero_cards` | the hero seat's `cards` |
+| `players[]` | `state.seats` (`{pos,stack,name,cards}`; emitter doesn't set `hero`/version — server normalize does) |
+| `actions[]` | `state.actions`, with a `{street, board}` reveal entry spliced in at each street boundary from `state.board` |
+| `board` | `flop + turn + river` concatenated |
+| `result` | `state.result` |
+
+Client builds best-effort; **`store_hand_history()` → `normalize_structured()` is the
+authority** (canonical cards, hero sync, `schema_version`, `completeness`). Keeps the
+client dumb and the contract enforced in one place.
+
+## Persistence
+
+New endpoint (small, part of the build):
+```
+POST /hands   body: { structured, session_id?, tag?, lesson? }
+            -> store_hand_history(structured, ...) -> { id }
+```
+On save: POST, then hand off to the existing viewer `/hand/{id}` to replay — which doubles
+as the correctness check (what you tapped is exactly what replays).
+
+## Scope
+
+**V1 — core loop (chosen).** Seats + cards + per-street actions emitting valid structured
+JSON. Manual street advance (a "next street" button + board entry), free bet-size entry
+(type the number). Proves capture → store → replay end to end on the locked schema.
+
+### Card entry (V1)
+
+Contextual: tap a card slot (hero card, board square, "they showed") → a compact picker
+pops at that slot. One picker holds **4 color-coded suits + 13 ranks + `x` + unknown-card**.
+Whichever you tap first sets the flow for that card — no mode switch:
+
+- **Suit first → it locks** (stays lit). Each subsequent rank tap places `rank+lockedSuit`
+  and auto-advances. Flush flop = `♥ T 8 5` (4 taps); suited hole = `♥ A K` (3 taps).
+- **Rank first → card is pending a suit**; the next tap must be a suit (or `x`). Best for
+  rainbow/mixed. Locked suit stays in effect until a different suit is tapped.
+- **`x`** = unknown suit → stores e.g. `Ax`; flips `completeness.cards` false so RTO skips
+  suit-dependent math. **Unknown-card** button = a villain card never shown (`x`).
+
+No typing — lowercase tokens are the internal/contract format only; the player only ever
+taps symbols. State: `lockedSuit` (nullable) + the active slot; auto-advance on complete.
+
+**V2 — the smart keypad.** The contextual state machine layered on top: tracks whose turn
+it is and the current bet, offers only legal actions (check vs call; bet/raise reveal size
+presets ½/¾/pot/+1bb), auto-advances the street when action closes, tap-a-seat to set the
+actor, one-tap "they showed [cards]" at showdown. ~6–10 taps, no typing. Built on the same
+`state` + `buildStructured`, so V1's emitter doesn't change — V2 just drives `state` smarter.
+
+## Layout sketch (full-screen overlay)
+
+```
+┌───────────────────────────── Record hand ───────────────  ✕ ┐
+│            (CO)        (BTN)                                  │
+│      (HJ)        ◯ oval table ◯        (SB)                   │
+│            (MP)        (UTG)      (BB·hero)                   │
+│   board:  [ 7d ][ 2c ][ 5h ]   pot: 40                       │
+├──────────────────────────────────────────────────────────────┤
+│  acting: BB        [ fold ][ check ][ call ][ bet ][ raise ]  │
+│  amount: [  15  ]            [ ½ ][ ¾ ][ pot ][ +1bb ]  (V2)  │
+│  [ ◀ prev street ]  [ next street ▶ ]      [ they showed… ]   │
+├──────────────────────────────────────────────────────────────┤
+│  preflop: BTN raise 15 · BB call          [ save & replay ]   │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## Build order
+
+1. `POST /hands` endpoint + add `seat` to the villains payload (server, small).
+2. `recorder.js` skeleton: `mount()`, `state`, `buildStructured()` (pure).
+3. Overlay shell in `index.html` (open button in session/cash mode) + `recorder.css`.
+4. V1 capture flow → save → replay. Validate a real hand round-trips identically.
+5. V2 smart keypad on top.
+```