feat(ui): Sit-in method selection UI (Next Big Blind vs Post Required Blinds)

[bitcoinbrisbane]

Parent Issue

block52/poker-vm#1830 — Section 3: Sit In Options
Also related to #50 (initial join sit-in options) — this covers the UI specifically.

Problem

The current "SIT IN" button is a single-click action with no options. The document requires two sit-in methods with dynamic blind labels.

Current UI

┌─────────────────────────────┐
│  [ SIT IN ]                 │  ← Single button, no options
│                             │  ← Immediately sets ACTIVE
│                             │  ← No blind posting
└─────────────────────────────┘

Current code: ui/src/components/playPage/Table/components/PlayerActionButtons.tsx

Required UI

AC-1: Solo Player — No Sit-In Options, Show "Waiting for Players"

Industry standard: No major poker site (PokerStars, GGPoker, 888poker, PartyPoker, ACR) shows sit-in options to the first/only player at an empty table. There's no game to join, no blinds rotating, nothing to "wait for" or "post into."

Behavior:

• When a player is the only player at the table (no other seated/active players), do NOT show the sit-in method options
• Instead, show the existing "Waiting for players to join..." bubble (already in TableStatusMessages.tsx)
• The sit-in options only appear when there are 2+ players at the table (i.e., a game is running or can start)

┌─────────────────────────────────┐
│  ⏳ Waiting for players to join │  ← Solo player, no options
└─────────────────────────────────┘

When 2nd player joins:

• PVM bootstrap activates both players automatically (no sit-in selection needed for founding players)
• Game starts with button draw

When 3rd+ player joins a running game:

• Player is SEATED → sees sit-in options (AC-2)

Scenario	Show sit-in options?	What happens?
1st player at empty table	No	"Waiting for players" bubble
2nd player at empty table	No	Bootstrap activates both, game starts
3rd+ player joins running game	Yes	Choose "Sit In On Next Big Blind" or "Post Required Blinds Now"
Player returns from SITTING_OUT	Yes	Choose "Sit In On Next Big Blind" or "Post Required Blinds Now"

AC-2: Sit-In Options Panel (3+ players, joining running game)

When player is SEATED or SITTING_OUT and there are active players at the table, show two stacked buttons:

┌──────────────────────────────────────────────────────┐
│  [ Sit In On Next Big Blind ]       ← green primary  │
│  [ Post Required Blinds Now ]       ← subtle         │
└──────────────────────────────────────────────────────┘

• "Sit In On Next Big Blind" calls handleSitIn(tableId, network, "next-bb")
• "Post Required Blinds Now" calls handleSitIn(tableId, network, "post-now")
• Mobile: compact version with smaller text

AC-3: Pending State (SITTING_IN)

After selecting a method, show waiting indicator with method-specific message:

┌──────────────────────────────────────────┐
│  ● Waiting For Next Big Blind...         │  ← method=next-bb
│     [ Cancel ]                           │
└──────────────────────────────────────────┘

or

┌──────────────────────────────────────────┐
│  ● Waiting to Post Required Blinds...    │  ← method=post-now
│     [ Cancel ]                           │
└──────────────────────────────────────────┘

• Cancel button calls handleSitOut() which clears sitInMethod (per feat(pvm): Implement sit-in options on join (Next BB vs Post Now) #50)

AC-4: Dynamic Blind Labels (Future Enhancement)

The "Post Required Blinds Now" label could show exact blind amounts:

• "Post Big Blind ($0.20) Now"
• "Post Small Blind + Big Blind ($0.30) Now"

Deferred — requires PVM to expose missed blind data.

Implementation

Files to Modify

File	Change
ui/src/components/playPage/Table/components/PlayerActionButtons.tsx	Hide sit-in options when solo player; show stacked buttons for 3+ players
ui/src/hooks/playerActions/sitIn.ts	Accept method parameter (done)
ui/src/components/common/actionHandlers.ts	Pass method to handleSitIn (done)
ui/src/components/playPage/Table.tsx	Pass active player count or solo flag to PlayerActionButtons

Key Logic Change (PlayerActionButtons)

// Don't show sit-in options if player is the only one at the table
if (hasSitInAction && activePlayerCount === 0) {
    return null; // "Waiting for players" bubble shown by TableStatusMessages
}

Related Issues

• block52/poker-vm#1830 — Parent: complete state logic (Section 3)
• feat(pvm): Implement sit-in options on join (Next BB vs Post Now) #50 — Initial join sit-in options (PVM-focused)
• block52/poker-vm#1844 — Tech debt: export SitInMethod constants from SDK
• bug(ui): turn animation ring shows when no hand is active #57 — Bug: turn animation ring shows when no hand is active
• block52/poker-vm#1086 — Sit-in after missing blinds
• block52/poker-vm#774 — BUY CHIPS (for insufficient chips redirect)

🤖 Generated with Claude Code

[bitcoinbrisbane]

@Dzeezbtc — Question on Section 3 sit-in options:

What is "Required Blinds (Dynamic Naming)"?

The document says the UI text must explicitly state what will be posted, with three variants:

• Post Big Blind
• Post Small Blind
• Post Small Blind and Big Blind

(Determined by blinds missed since last active play)

Questions:

1. How do we determine which blinds were "missed"? Is it based on how many times the BB/SB position passed the player's seat while they were sitting out? Or is it simply based on their seat position relative to the blinds when they sit back in?

2. Is this a fixed cost or variable? For example at a $0.10/$0.20 table — if a player missed 3 orbits, do they post $0.20 (one BB) or $0.60 (3x BB)? In most live poker rooms it's always just one BB regardless of how many orbits missed. Confirm this is the same here.

3. "Post Small Blind" as a standalone option — in what scenario would a player only owe the SB? This typically only happens if they missed exactly the SB but not the BB, which is a very narrow timing window. Is this a real case we need to handle?

[Dzeezbtc]

How do we determine which blinds were missed?

Missed blinds are determined by the player’s seat position relative to the button as it moves around the table.

Point 1

A player must either:

Wait for the next Big Blind to enter a hand for free, or

Post blinds to return to the game earlier.

Point 2

If a player chooses to sit in on the next available hand, they must post the blinds they missed in order to join the game.

Example:
If a player has missed both the Small Blind (SB) and the Big Blind (BB) and wishes to join the next available hand, they must post both the SB and the BB.

Point 3

A player is not required to pay for multiple missed blinds when returning to the game. The maximum requirement to sit in on the next available hand is one SB and one BB.

Point 4

It is important to note that if a player chooses to sit in on the next available hand and that hand places them directly in the Big Blind, they are only required to post the BB and do not need to post the SB.

Is this a fixed cost or variable?

This is a fixed rule and is consistent across live and online poker.
A player is required to post a maximum of one Small Blind and one Big Blind.

“Post Small Blind” as a standalone option

In what scenario would a player only owe the Small Blind?

This occurs when a player misses only the Small Blind but does not miss the Big Blind. Although this is a narrow timing window, it is a legitimate and important game scenario that must be handled correctly.

This situation happens when a player misses the SB and chooses to return to the game immediately. Posting the Small Blind in this case is a standard part of the game and must be supported.

[bitcoinbrisbane]

AC1