F008 — Hand Status

Field	Value
ID	F008
Phase	1 — Core Game Engine
Jira	HEDGE-133
Status	TS ✅ · JS ⬜ · UMA ✅

Business Rule

At every betting stage the server assigns each hand a handStatus label. These labels drive:

Which hands are highlighted as the favourite (most likely to win)
Which hands are marked as dead at RIVER (losers)
Which hand is the winner at RIVER
UI display in the TS client (favourite badge, win/dead overlays)

HandStatus Values

Value	When set	Meaning
`IN_PLAY_BETTING_STAGE_ACTIVE`	HOLE / FLOP / TURN	Normal active hand — player may bet
`IN_PLAY_FAVOURITE`	HOLE / FLOP / TURN	The hand with the highest `winPercentage`; exactly one per stage
`IN_PLAY_WINNER`	RIVER	The hand that won the showdown
`IN_PLAY_DEAD`	RIVER	All non-winning hands at RIVER

Four further values exist in the HandStatus enum (UNDEFINED, IN_NON_BETTING_STAGE, IN_PLAY_PREVIOUS_BETTING_STAGE_NOT_ACTIVE, IN_PLAY_DISABLED, IN_PLAY_WILL_WIN) but are not emitted by the live advance endpoint.

Favourite Logic

At pre-RIVER stages the hand with the highest winPercentage receives IN_PLAY_FAVOURITE. In the event of a tie the first hand (lowest handIndex) wins the tiebreak.

// api/tables/[tableId]/advance.ts — buildHandOdds()
const status = i === favouriteIdx
  ? HandStatus.IN_PLAY_FAVOURITE
  : HandStatus.IN_PLAY_BETTING_STAGE_ACTIVE;

RIVER Logic

At RIVER the hand evaluator sets winPercentage = 100 (or drawPercentage = 100 for a split) for the winner. The API maps this to IN_PLAY_WINNER; all other hands receive IN_PLAY_DEAD.

TypeScript Implementation

ApiClient.ts maps handStatus to a boolean flag used by the scene:

statusIsFavourite: o.handStatus === 'IN_PLAY_FAVOURITE',

UMA State Bridge

platform.js exposes handStatus via window._lastStages:

window._lastStages[handIndex][lastEntry].handStatus
  → 'IN_PLAY_FAVOURITE' | 'IN_PLAY_BETTING_STAGE_ACTIVE' | 'IN_PLAY_WINNER' | 'IN_PLAY_DEAD' | null

_lastStages is populated:

At HOLE init (alongside _holeOdds)
After each advance (FLOP, TURN, RIVER) via buildGameStatus

At RIVER, window._winnerInfo[i].isWinner is an additional proxy: true ↔ IN_PLAY_WINNER.

Acceptance Criteria

#	Criterion	JS	TS	UMA
AC1	At HOLE, exactly one hand has `IN_PLAY_FAVOURITE`; all others have `IN_PLAY_BETTING_STAGE_ACTIVE`	⬜	✅	✅
AC2	At FLOP, exactly one hand has `IN_PLAY_FAVOURITE`; all others have `IN_PLAY_BETTING_STAGE_ACTIVE`	⬜	✅	✅
AC3	At TURN, exactly one hand has `IN_PLAY_FAVOURITE`; all others have `IN_PLAY_BETTING_STAGE_ACTIVE`	⬜	✅	✅
AC4	At RIVER, exactly one hand has `IN_PLAY_WINNER`; all others have `IN_PLAY_DEAD`	⬜	✅	✅
AC5	`IN_PLAY_FAVOURITE` hand always has the lowest odds value (= highest `winPercentage`)	⬜	✅	✅

UMA-testable ACs (via state bridge)

#	UMA Criterion	Notes
AC1-UMA	After HOLE, `_lastStages[i][0].handStatus`: exactly one `IN_PLAY_FAVOURITE`, rest `IN_PLAY_BETTING_STAGE_ACTIVE`	Set at HOLE init alongside `_holeOdds`
AC2-UMA	After FLOP advance, same check on `_lastStages[i][last].handStatus`
AC3-UMA	After TURN advance, same check
AC4-UMA	After RIVER advance, `_winnerInfo` has exactly one `isWinner === true`; `_lastStages[i][last].handStatus` ∈
AC5-UMA	The hand with `IN_PLAY_FAVOURITE` has the minimum odds value in `_lastStages` at that stage	Lowest odds = highest win%

Version Parity

Version	Status	Notes
JS (reference)	⬜ Not audited
TS	✅ Verified	`statusIsFavourite` mapped in `ApiClient.ts`; favourite badge rendered in `GameScene.ts`
UMA	✅ Verified	`tests/features/F008-hand-status.spec.ts` — AC1–AC5 (UMA) pass (2026-04-15)

Test Coverage

Playwright spec: tests/features/F008-hand-status.spec.ts — AC1–AC5 (UMA). Run with:

VERSION=uma npx playwright test tests/features/F008-hand-status.spec.ts --project=features --workers=1

F006 — Odds Calculation (winPercentage drives the favourite selection)
F005 — Hand Evaluation (RIVER winner determined by pokersolver → IN_PLAY_WINNER)
F025 — Dead Hand Display (uses IN_PLAY_DEAD status)
F026 — Cant-Lose Display (uses IN_PLAY_WILL_WIN — not yet implemented in live endpoint)

Overview

Game Engine

Betting

UI

Config

Bonus

V7 Horse Race

Platform

Lobby

F008 — Hand Status

F008 — Hand Status

Business Rule

HandStatus Values

Favourite Logic

RIVER Logic

TypeScript Implementation

UMA State Bridge

Acceptance Criteria

UMA-testable ACs (via state bridge)

Version Parity

Test Coverage

​F008 — Hand Status

​Business Rule

​HandStatus Values

​Favourite Logic

​RIVER Logic

​TypeScript Implementation

​UMA State Bridge

​Acceptance Criteria

​UMA-testable ACs (via state bridge)

​Version Parity

​Test Coverage

​Related Features

F008 — Hand Status

Business Rule

HandStatus Values

Favourite Logic

RIVER Logic

TypeScript Implementation

UMA State Bridge

Acceptance Criteria

UMA-testable ACs (via state bridge)

Version Parity

Test Coverage

Related Features