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

# F020 — Deal Button / Auto-deal on Load

> Game initialises at hole stage automatically on load; DEAL button starts subsequent games

# F020 — Deal Button / Auto-deal on Load

| Field  | Value                              |
| ------ | ---------------------------------- |
| ID     | F020                               |
| Phase  | 3 — UI                             |
| Jira   | HEDGE-134                          |
| Status | TS ✅ fixed · JS ✅ verified · UMA ⬜ |

## Business Rule

The game must start at the **hole stage** immediately on load — hole cards face-up, community
cards face-down, hand odds visible, betting UI active. No player action is required to initiate
the first deal.

After river is resolved, a **DEAL** button appears so the player can start the next game.
The DEAL button is hidden at all other times.

## JavaScript Reference

**JS Source:** `hedgeem-v4/odobo/src/js/control.js`

```javascript theme={null}
// control.js:15 — called once at game launch
function InitialiseGame() {
    SetCreditAmount(CREDIT_INIT_VALUE);
    SetWinAmountTitle(false);
    SetWinAmount(0);
    InitialiseDealData();
    AdvanceGameState();   // ← auto-runs all CC_AUTO_ADVANCE states to CC_ALLOW_BETS_1
    gameInitialised = true;
}
```

`AdvanceGameState()` loops through:

```
CC_GAME_INIT → CC_GAME_START → CC_DEAL_CARD1 … CC_DEAL_CARD13 → CC_ALLOW_BETS_1
```

All states up to `CC_ALLOW_BETS_1` are `CC_AUTO_ADVANCE` — they run without player input.
The loop stops at `CC_ALLOW_BETS_1` which is `CC_AWAIT_INPUT` (hole betting window).

**JS Live:** [hedgeem.qeetoto.com](https://hedgeem.qeetoto.com) — loads directly at hole stage.

### Between games (JS)

After river resolution the JS state machine auto-advances:

```
CC_ADD_WIN → CC_CYCLE_HANDS → CC_SHOW_HAND1…4 → CC_GAME_END → CC_GAME_START → [re-deal]
```

The next game starts automatically with no player action. There is no explicit DEAL button
in JS — the green advance button triggers each stage transition.

## TypeScript Implementation

**File:** `standalone_reference_client/src/scenes/GameScene.ts`

### Fix applied (HEDGE-134)

Added `this._onDeal()` call at the end of `GameScene.create()`:

```typescript theme={null}
// Auto-deal on load — JS reference starts at hole stage immediately (control.js:InitialiseGame).
// HEDGE-134
this._onDeal();
```

`_onDeal()` handles:

1. Hides DEAL button
2. Loads local game (`engine.loadLocalGame()`)
3. Advances to hole (`engine.advance()` → dealStatus=0)
4. Renders the hole stage
5. Shows advance button

### Between games (TS — design difference)

Unlike JS (fully automatic), TS shows the DEAL button after river so the player explicitly
starts the next game. This is a deliberate UX difference — considered acceptable for v5.

## Acceptance Criteria

| #   | Criterion                                                         | JS  | TS | UMA |
| --- | ----------------------------------------------------------------- | --- | -- | --- |
| AC1 | Page load shows hole stage — cards dealt, odds visible            | ✅   | ✅  | ⬜   |
| AC2 | DEAL button hidden on initial load                                | N/A | ✅  | ⬜   |
| AC3 | DEAL button appears after river resolved                          | N/A | ✅  | ⬜   |
| AC4 | Playwright confirms `dealStatus === 0` without player interaction | ✅   | ✅  | ⬜   |

## Version Parity

| Version        | Status        | Notes                                                    |
| -------------- | ------------- | -------------------------------------------------------- |
| JS (reference) | ✅ Verified    | Auto-deals via `InitialiseGame()` → `AdvanceGameState()` |
| TS             | ✅ Fixed       | `_onDeal()` called from `create()` — HEDGE-134           |
| UMA            | ⬜ Not audited | Phase 5                                                  |

## Test Coverage

| Test                             | Location                                              |
| -------------------------------- | ----------------------------------------------------- |
| Auto-deal on load                | `tests/features/F020-deal-button.spec.ts` (to add)    |
| Smoke — page loads at hole stage | `standalone_reference_client/tests/e2e/smoke.spec.ts` |