> ## 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.

# F001 — Hand Count Rules

## Business Rule

HedgeEm deals a configurable number of simultaneous Texas Hold'em hands at one table. The player bets on one or more of these hands before community cards are revealed.

* **Default**: 3 hands
* **Minimum**: 2 hands
* **Reference client UI maximum**: 4 hands (configurable via settings — see F030)
* **Theoretical backend maximum**: 23 hands — `floor((52 − 5) ÷ 2)` — 52 cards in a standard deck, 5 reserved for community cards, 2 hole cards per hand

The hand count is set at the start of each round and does not change mid-game.

***

## Technical Design

### UMA client (`platform.js`)

```javascript theme={null}
var NUM_HANDS = 3; // default, hardcoded in platform.js
```

`NUM_HANDS` is sent to the GDK in the `game:InitStatus` payload:

```javascript theme={null}
maxHandCount: NUM_HANDS,     // tells the GDK how many hand panels to render
numberOfHands: NUM_HANDS,    // sent in each /api/tables/:id/deal request
```

After each deal, the state bridge exposes hole cards per hand:

```javascript theme={null}
window._holeCards = holeState.hands; // string[] — one 4-char entry per hand, e.g. ['AcKd','7h2s','QsJd']
```

Each string is 4 characters: rank+suit for card 1 followed by rank+suit for card 2 (e.g. `Ac` = Ace of clubs, `Kd` = King of diamonds → `AcKd`).

### Deck constraint derivation

```
52 cards in deck
−  5 community cards
= 47 available for hole cards
÷  2 cards per hand
= 23.5 → floor = 23 maximum hands
```

### Hand indexing

Hands are 0-indexed internally. `_holeCards[0]` is hand 0, `_holeCards[1]` is hand 1, etc. UI panels are rendered in the same order.

***

## Acceptance Criteria

* **AC1** — After page load and initialisation, `window._holeCards.length` equals the configured hand count (default: 3)
* **AC2** — Each entry in `_holeCards` is exactly 4 characters (two 2-char card tokens, e.g. `AcKd`)
* **AC3** — Hand count is within the valid range: ≥ 2 and ≤ 23
* **AC4** — No card appears more than once across all hands (deck integrity — no duplicates)

***

## Version Parity

| Version    | Status            | Notes                                                                |
| ---------- | ----------------- | -------------------------------------------------------------------- |
| JavaScript | ⬜ Not yet audited | Reference implementation at hedgeem.qeetoto.com                      |
| TypeScript | ✅ Implemented     | `GameEngine.numberOfHands`, `GameRecord.numberOfHands`               |
| UMA        | ✅ Verified        | `tests/features/F001-hand-count.spec.ts` — AC1–AC4 pass (2026-04-15) |

***

## Known Discrepancies

None documented yet.

***

## Test Coverage

Playwright spec: `tests/features/F001-hand-count.spec.ts` — AC1–AC4.

Run with:

```bash theme={null}
VERSION=uma npx playwright test tests/features/F001-hand-count.spec.ts --project=features --workers=1
```