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

# F104 — Hidden Odds Debug Panel

> Settings toggle to reveal the full odds chain (win%, draw%, odds_act, odds_marg, odds_rnd, rtp, rake) per hand. Default off — shown only when enabled.

# F104 — Hidden Odds Debug Panel

|                 |                                                                       |
| --------------- | --------------------------------------------------------------------- |
| **Phase**       | 3 — UI & Presentation                                                 |
| **Jira**        | HEDGE-225 (story) · HEDGE-226 (bug: historical odds missing from API) |
| **Parent epic** | HEDGE-82 — Config options page                                        |
| **Status**      | v4 ✅ · v5 N/A · v6 ✅ · v7 ✅ · v8 ✅                                    |

***

## Business Rule

The game normally shows players only the rounded odds (`odds_rnd`) for their current betting stage. All other probability and margin data is hidden.

When the **Show hidden odds** setting is enabled, a debug panel is displayed alongside the game showing the full odds chain for each hand at the current stage:

| Field              | Label      | Description                                                             |
| ------------------ | ---------- | ----------------------------------------------------------------------- |
| `winPercentage`    | win%       | Monte Carlo probability of winning outright                             |
| `drawPercentage`   | draw%      | Probability of a draw/split pot                                         |
| `percentWinOrDraw` | win/draw%  | Combined win or draw probability                                        |
| `oddsActual`       | odds\_act  | Fair decimal odds (100 / percentWinOrDraw)                              |
| `oddsMargin`       | odds\_marg | Odds after RTP margin applied (oddsActual × targetRtp)                  |
| `oddsRounded`      | odds\_rnd  | Final displayed odds (rounded to 1 d.p.) — this is what the player sees |
| `actualRtp`        | rtp        | Effective RTP for this bet (oddsRounded / oddsActual)                   |
| `roundingRake`     | rake       | Margin lost to rounding ((oddsMargin − oddsRounded) / oddsActual)       |

Plus: **undealt cards** count (deck size minus dealt cards).

The toggle defaults to **off**. It is intended for QA, development, and demonstration purposes.

***

## Technical Design

### Odds chain (server)

All fields are computed server-side in `computeOddsChain()` (`api/_lib/utils.ts`):

```
percentWinOrDraw  →  oddsActual  →  oddsMargin  →  oddsRounded
                                                  ↓
                                              actualRtp, roundingRake
```

The `HedgeEmHandOdds` API type was extended to include all chain fields:

```typescript theme={null}
export interface HedgeEmHandOdds {
  handIndex:      number;
  bettingStage:   BettingStage;
  handStatus:     HandStatus;
  winPercentage:  number;       // 0–100
  drawPercentage: number;       // 0–100
  odds:           number;       // oddsRounded — displayed to player
  // Extended fields (F104):
  oddsActual:     number;       // fair decimal odds
  oddsMargin:     number;       // after RTP margin
  actualRtp:      number;       // effective RTP for this bet
  roundingRake:   number;       // margin lost to rounding
  handName?:      string;       // pokersolver name at RIVER
}
```

### Bug: historical stage odds (HEDGE-226)

The GET `/api/tables/:id/state` endpoint currently only returns odds for the *current* stage. Historical stage odds (e.g. HOLE odds when at FLOP) are overwritten in `game_table_state.hand_odds` on each `/advance` call. Fixing this requires storing odds per-stage (separate columns or a JSON map keyed by stage). F104 displays current-stage odds only until HEDGE-226 is resolved.

### v4 — JS reference

Fully implemented. Settings panel toggle → `ENABLE_SHOW_HIDDEN_ODDS` flag → `drawSummaryInfo` global → debug popup rendered as a DOM overlay.

### v6 — Phaser 3 / TypeScript

* Toggle added to config overlay (row: "Show hidden odds", flag: `cfgShowHiddenOdds`)
* When enabled: Phaser `Graphics` + `Text` objects render a table in the top-right corner of the canvas
* Data sourced from `GameSnapshot.handOdds` (extended fields from API)
* Re-rendered on each `_renderHandPanels()` call

### v7 — Horse Race / HTML+CSS

* Toggle button added to race UI toolbar
* When enabled: HTML `<table>` panel injected into the DOM, positioned over the info panel area
* Data sourced from `window.__hedgeem.getSnapshot().handOdds`
* Updated on each `hedgeem:stateUpdate` event

### v8 — Casino / HTML+CSS

* Toggle button added to status bar
* When enabled: HTML `<table>` panel overlaid on the table
* Same data source as v7

***

## Acceptance Criteria

| #   | Criterion                                                                     |
| --- | ----------------------------------------------------------------------------- |
| AC1 | Toggle in settings panel labelled "Show hidden odds" (default: off)           |
| AC2 | When enabled, debug table visible with one column per hand                    |
| AC3 | Rows: win%, draw%, win/draw%, odds\_act, odds\_marg, odds\_rnd, rtp, rake     |
| AC4 | Undealt cards count shown below the table                                     |
| AC5 | Values match the server-computed odds chain                                   |
| AC6 | Table dismisses cleanly when toggle is turned off                             |
| AC7 | API `handOdds` array includes oddsActual, oddsMargin, actualRtp, roundingRake |

***

## Version Parity

| Version         | Status | Notes                                                   |
| --------------- | ------ | ------------------------------------------------------- |
| v4 (JS)         | ✅      | Reference implementation — DOM overlay, settings toggle |
| v5 (UMA)        | N/A    | Compiled client — cannot add UI                         |
| v6 (TS)         | ✅      | Phaser graphics table, config overlay toggle            |
| v7 (Horse Race) | ✅      | HTML table, toolbar toggle                              |
| v8 (Casino)     | ✅      | HTML table, status bar toggle                           |