F004 — Game Stages

​

Business Rule

1. Pre-deal — The table is idle. Only the Deal button is visible. No cards are shown.
2. Hole (PRE-FLOP) — Two hole cards are dealt to each hand. All hole cards are face-up. Five community card positions are visible as face-down card backs. Betting is open on all live hands.
3. Flop (POST-FLOP) — Three community cards are turned face-up. Betting remains open.
4. Turn — A fourth community card is turned face-up. Betting remains open.
5. River — The fifth and final community card is turned face-up. Betting closes. All bets are resolved and winnings paid out. The Deal button reappears for the next game.

​

Stage naming (design document vs implementation)

​

Technical Design

​

State representation

​

State transitions (TypeScript — GameEngine)

advance(): boolean {
  if (this.dealStatus >= 3) return false; // already at river
  this.dealStatus++;
  return true;
}

get isGameOver(): boolean {
  return this.dealStatus >= 3;
}

​

Deal flow (GameScene._onDeal)

click Deal button
  → engine.loadLocalGame() or engine.loadApiGame()
  → engine.advance()       // dealStatus: -1 → 0 (hole)
  → _render()
  → advanceBtn.setVisible(true)
  → dealBtn.setVisible(false)

​

Advance flow (GameScene._onAdvance)

click Advance button
  → engine.advance()       // dealStatus: N → N+1
  → _render()
  → if engine.isGameOver:
      → engine.resolveBets()
      → advanceBtn.setVisible(false)
      → dealBtn.setVisible(true)
      → _render()           // re-render to show WIN / final state

​

Community card reveal schedule

const communityReveal = [0, 3, 1, 1]; // cards revealed per stage: pre→hole→flop→turn→river
let revealed = 0;
for (let s = 0; s <= dealStatus; s++) revealed += communityReveal[s];
// dealStatus 0 (hole):  revealed = 0  — all face-down
// dealStatus 1 (flop):  revealed = 3  — flop 1,2,3 face-up
// dealStatus 2 (turn):  revealed = 4  — + turn face-up
// dealStatus 3 (river): revealed = 5  — all face-up

​

Hole card reveal rule

// HEDGE-135: all hole cards face-up once dealt
const faceUp = true;

​

HandStageInfo indexing

private _infoAt(hand: number): HandStageInfo | undefined {
  if (this.dealStatus < 0) return undefined;
  const n = this.record.numberOfHands;
  return this.record.handStageInfoList[this.dealStatus * n + hand];
}

​

Acceptance Criteria

• On page load, only the Deal button is visible; no cards or hand panels are shown
• Clicking Deal transitions to hole stage: cards appear, Advance button visible, Deal button hidden
• At hole stage: all hole cards (all hands) are face-up (HEDGE-135)
• At hole stage: all 5 community card slots show face-down card backs
• Clicking Advance at hole → flop: 3 community cards revealed face-up; all hole cards now face-up
• Clicking Advance at flop → turn: 4th community card revealed; 5th still face-down
• Clicking Advance at turn → river: all 5 community cards face-up; Deal button reappears
• advance() returns false at river and does not increment dealStatus beyond 3
• isGameOver is true only at dealStatus === 3
• resolveBets() is called exactly once, after the river advance

​

Version Parity

​

Known Discrepancies

​

Test Coverage

• screenshot: full game cycle — deal → flop → turn → river — covers stage transitions visually
• betting: full cycle — asserts dealStatus === 3 and gameOver === true at river

• advances to hole (0) on first advance()
• advances through all four stages
• returns false from advance() when already at river
• isGameOver is true at river