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

# F055 — Demo Hand Panel (QA / Forced Deals)

> A debug overlay activated by ?demo URL parameter that lets operators and QA engineers force specific pre-computed hands from a list of 17 named scenarios

# F055 — Demo Hand Panel

| Field  | Value                               |
| ------ | ----------------------------------- |
| ID     | F055                                |
| Phase  | 4 — Config / Debug                  |
| Jira   | HEDGE-228                           |
| Status | TS ✅ · JS ⬜ · UMA ✅ (as `DEMOMENU`) |

## Business Rule

A hidden debug panel, activated only via a URL parameter, allows operators and QA engineers to force any of 17 pre-computed game scenarios at will. It is **invisible in normal play** and has no effect on production deployments unless the URL parameter is explicitly added.

## Activation

Append `?demo` to the game URL:

```
https://hedgeem-v6.qeetoto.com/?demo
```

A red **DEMO** button appears in the top-right corner of the game. Clicking it toggles a list of 17 preset hand scenarios. Clicking any scenario forces that hand immediately (interrupting any in-progress game).

## The 17 Preset Scenarios

These are the 17 pre-computed `demoData[]` records from `coredata.ts`, sourced from `hedgeem-v4/odobo/src/js/dev/demodata.js`. They mirror v5's `DEMOMENUCONFIG.OPTIONS` (IDs 1–17 in `debug.js`).

| #  | Description                                                                  |
| -- | ---------------------------------------------------------------------------- |
| 1  | All hands start with same chance of winning. Then one has a lucky flop       |
| 2  | All hands start with same chance of winning. Then one has a lucky flop (v2)  |
| 3  | All hands have exactly same chance of winning                                |
| 4  | Only one hand can win after TURN dealt                                       |
| 5  | Only one hand can win after flop dealt                                       |
| 6  | All hands win AND five best cards could be made from community or hole cards |
| 7  | All hands win AND five best cards are just the board cards                   |
| 8  | One hand can't lose but others could win                                     |
| 9  | A typical game with lots of 'outs' for each hand and good balance of odds    |
| 10 | A typical game where all hands have their turn of luck                       |
| 11 | Good odds for 'Pocket Kings' — an emotional hand that stimulates betting     |
| 12 | Bet on hand 3, then £1 on hands 1 and 2 post-Flop                            |
| 13 | Bet heavy on hand 1, then Hedge Your Bets post-Flop                          |
| 14 | A rank-outsider x700 where Turn and River need to be exact cards, wins       |
| 15 | Shows the maximum and minimum possible odds in a four-handed game            |
| 16 | After some excitement — all hands win                                        |
| 17 | All hands dead after the Flop                                                |

## V5 Source References

| File                                                              | Lines     | Purpose                                                                                   |
| ----------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------- |
| `source/client_source/src/js/Engine/modules/ui/demoMenuDom.js`    | 1–120     | `DemoMenuDom` — DOM overlay class (production v5 implementation)                          |
| `source/client_source/src/js/Engine/modules/ui/demoMenu.js`       | 1–140     | `DemoMenu` — Phaser 2 canvas variant (older)                                              |
| `source/client_source/src/js/GameConfig/fugaGaming/game/debug.js` | 7, 12–110 | `DEMOMENU = false` flag; `DEMOMENUCONFIG.OPTIONS` array with 17 presets and labels        |
| `source/client_source/src/js/Engine/gameEngine.js`                | 38        | `if(DEMOMENU === true) demoMenu = new DemoMenuDom()`                                      |
| `source/client_source/src/js/Game/gameTypes/baseGameScene.js`     | 40–89     | Subscribes `EVENT.UI.CUSTOM_ORDER`; `_onCustomDemoAction()` parses custom JSON hand input |
| `source/client_source/src/js/API/fugaGaming/apiFuga.js`           | 670–681   | `makeDemoRequest()` — sends `{action:"demo", demoId}` to server via GDK packet            |

## V6 Implementation

### Files

| File                                         | Purpose                                                     |
| -------------------------------------------- | ----------------------------------------------------------- |
| `hedgeem-v6-client/src/engine/GameEngine.ts` | `loadForcedGame(record)` — loads a specific record directly |
| `hedgeem-v6-client/src/scenes/GameScene.ts`  | `demoMode` flag, `_createDemoPanel()`, `_startDemoHand()`   |
| `hedgeem-v6-client/src/data/coredata.ts`     | `demoData[]` — 17 pre-computed `GameRecord` objects         |

### Key Locations

| Symbol                              | File            | \~Line | Description                                                                                          |
| ----------------------------------- | --------------- | ------ | ---------------------------------------------------------------------------------------------------- |
| `GameEngine.loadForcedGame(record)` | `GameEngine.ts` | \~130  | Loads a `GameRecord` directly, `isLiveData = false`. Equivalent to `loadApiGame()` but bypasses API. |
| `demoMode` flag                     | `GameScene.ts`  | \~255  | `new URLSearchParams(window.location.search).has('demo')`                                            |
| `_demoPanel` property               | `GameScene.ts`  | \~256  | Holds the DOM `HTMLElement` ref for cleanup                                                          |
| Shutdown cleanup                    | `GameScene.ts`  | \~302  | `this._demoPanel?.remove()` in `'shutdown'` event listener                                           |
| `_createDemoPanel()` call           | `GameScene.ts`  | \~349  | End of `create()` — only runs when `demoMode = true`                                                 |
| `_createDemoPanel()`                | `GameScene.ts`  | \~1487 | Creates fixed-position DOM overlay; 17 buttons from `demoData[]`                                     |
| `_startDemoHand(record)`            | `GameScene.ts`  | \~1545 | Calls `engine.loadForcedGame(record)`, advances to hole stage, renders                               |
| `demoData[]`                        | `coredata.ts`   | \~6589 | 17 pre-computed `GameRecord` objects (sourced from `demodata.js`)                                    |

### Architecture Difference from V5

In v5, the numbered preset IDs (1–17) were sent to the **server** which looked up a stored deal and returned computed odds. In v6, the 17 `demoData[]` records are embedded **client-side** with full pre-computed odds for all stages — no server round-trip is needed.

### Not Yet Implemented

**Custom hand input** — v5 allowed pasting a JSON hand string (`{"hands":["4dKs",...],"bc1":"3c",...}`) which was sent to the server with `action:"demo"` and returned with computed odds. Implementing this in v6 requires `/api/deal` to accept a `forceHand` parameter. The `_onCustomDemoAction()` parsing logic in `baseGameScene.js:45–89` can serve as the reference.

## Acceptance Criteria

| ID         | Criterion                                                                          |
| ---------- | ---------------------------------------------------------------------------------- |
| AC-F055-01 | `?demo` absent → no DEMO button shown, zero production impact                      |
| AC-F055-02 | `?demo` present → red DEMO toggle button appears top-right                         |
| AC-F055-03 | Clicking DEMO expands a list of 17 labelled presets                                |
| AC-F055-04 | Clicking any preset immediately deals that specific hand                           |
| AC-F055-05 | The forced hand matches the `demoData[i]` record exactly (cards, odds, stage info) |
| AC-F055-06 | Panel collapses after a preset is selected                                         |
| AC-F055-07 | Panel DOM element is removed cleanly on scene shutdown / orientation flip          |
| AC-F055-08 | A forced deal can interrupt an in-progress game safely                             |

## Version Parity

| Version         | Status            | Notes                                                                     |
| --------------- | ----------------- | ------------------------------------------------------------------------- |
| JS (v4)         | ⬜ Not yet audited | Likely has a debug mode; no `DemoMenu` found in v4 source                 |
| TypeScript (v6) | ✅ Implemented     | `?demo` URL param, 17 presets, `loadForcedGame()`, HEDGE-228              |
| UMA (v5)        | ✅ Implemented     | `DEMOMENU=true` in `debug.js`, `DemoMenuDom`, `makeDemoRequest()` via GDK |