project-lyra/docs/RECORDER.md

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 — 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

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.