> ## Documentation Index
> Fetch the complete documentation index at: https://hedgeem-api.qeetoto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# F002 — Deck Management

## Business Rule

HedgeEm uses a standard 52-card deck (4 suits × 13 ranks). The deck is shuffled server-side before each game. Cards are dealt without replacement — once a card is assigned to a hole hand or a community card position, it cannot appear again in the same game.

* **Hole cards**: 2 per hand × number of hands (e.g. 6 cards for 3 hands)
* **Community cards**: exactly 5 (flop 1, 2, 3; turn; river)
* **Total cards used per game**: `2 × numHands + 5` (e.g. 11 for 3 hands)
* **Cards remaining undealt**: `52 − (2 × numHands + 5)` (e.g. 41 for 3 hands — never revealed)

Card notation: 2-character token — rank (`2`–`9`, `T`, `J`, `Q`, `K`, `A`) followed by suit (`c`=clubs, `d`=diamonds, `h`=hearts, `s`=spades). e.g. `Ac` = Ace of clubs, `Th` = Ten of hearts.

***

## Technical Design

### Server-side shuffling

The REST API shuffles the deck server-side (Fisher-Yakes or equivalent). The shuffled deck is used to:

1. Deal 2 hole cards per hand — returned as `hands[]` (4-char strings) in the `STATUS_HOLE` API response
2. Deal 5 community cards — returned as `flopCard1`–`flopCard3`, `turnCard`, `riverCard` in each stage response

The shuffle algorithm is opaque to the client. The UMA client only sees card tokens in the API response.

### UMA client state bridge

```javascript theme={null}
window._holeCards  // string[] — 4-char per hand (e.g. ['AcKd','7h2s','QsJd'])
                   // set after STATUS_HOLE advance

window._stageCards // { flopCard1, flopCard2, flopCard3, turnCard, riverCard }
                   // each value is a 2-char string or null (null until that stage is reached)
                   // set after each advance call in platform.js
```

### Card token format

| Field              | Valid values                                                                |
| ------------------ | --------------------------------------------------------------------------- |
| Rank               | `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `T`, `J`, `Q`, `K`, `A` (13 values) |
| Suit               | `c` (clubs), `d` (diamonds), `h` (hearts), `s` (spades) (4 values)          |
| Total unique cards | 52                                                                          |

### GDK card translation

`platform.js` translates 2-char tokens to GDK card objects via `restToGdkCard(s)` before passing to the game engine. The translation maps rank characters to integers (2–14) and suit characters to integers (0–3).

***

## Acceptance Criteria

* **AC1** — After advancing to RIVER, `_stageCards` contains exactly 5 non-null community card tokens (flopCard1, flopCard2, flopCard3, turnCard, riverCard)
* **AC2** — All card tokens (hole cards + community cards) are valid 2-char strings: rank in `{2–9, T, J, Q, K, A}`, suit in `{c, d, h, s}`
* **AC3** — No card token appears more than once across all hole cards AND all community cards (global deck integrity)
* **AC4** — Total unique cards dealt equals `2 × handCount + 5` (e.g. 11 for 3 hands)
* **AC5** — Community cards are revealed progressively: flopCard1–3 non-null at FLOP; turnCard non-null at TURN; riverCard non-null at RIVER

***

## Version Parity

| Version    | Status            | Notes                                                                     |
| ---------- | ----------------- | ------------------------------------------------------------------------- |
| JavaScript | ⬜ Not yet audited | Reference implementation at hedgeem.qeetoto.com                           |
| TypeScript | ⬜ Not yet audited | `GameRecord` / `GameEngine`                                               |
| UMA        | ✅ Verified        | `tests/features/F002-deck-management.spec.ts` — AC1–AC5 pass (2026-04-15) |

***

## Known Discrepancies

None documented yet.

***

## Test Coverage

Playwright spec: `tests/features/F002-deck-management.spec.ts` — AC1–AC5.

Run with:

```bash theme={null}
VERSION=uma npx playwright test tests/features/F002-deck-management.spec.ts --project=features --workers=1
```