Public Common Screen Flow

Replaces the facilitator-driven game start. The common screen IS the game host.

Overview

When a user points their browser at the root URL, a new game session is created automatically. The common screen displays a QR code and join URL. Players scan the code, enter their name, and join the lobby. The game starts automatically based on timer rules — no facilitator needed.

After a game finishes, results are shown for a period, then a new lobby auto-creates.

State Machine (Updated)

AUTO_LOBBY → COUNTDOWN → PLAYING → REVIEWING → RESULTS → COOLDOWN → AUTO_LOBBY
                 ↑                      │
                 └── (next question) ───┘

CREATED and LOBBY are merged into AUTO_LOBBY — the system creates and opens the lobby in one step.

FINISHED is replaced by COOLDOWN — results display for a set period, then the cycle restarts.

Auto-Lobby Creation

Trigger: GET / (root URL)

System behaviour:
1. Select a random question set from the available pool
2. Create a new game with default config (10 questions, 60s per question)
3. Generate human-readable game code (e.g., "Blue-Dancing-Horse")
4. Display common screen with:
- QR code encoding the player join URL
- Human-readable game code
- Join URL as text
- Lobby countdown timer (starts at 5:00 when first player joins)
- Player list (updates as players join via SSE)

Lobby Timer Rules

The lobby timer governs when the game auto-starts. Three conditions, whichever comes first:

Condition 1: Timeout with no new players

• Timer starts at 5:00 (5 minutes) when the first player joins
• Timer counts down visibly on the common screen
• If timer reaches 0:00 and at least 1 player has joined → game starts

Condition 2: Rolling extension for new players

• Each new player joining resets the timer to 0:30 if less than 30 seconds remain
• This allows latecomers to extend the lobby window
• The extension only applies when the timer is below 30 seconds
• Example sequence:
• Timer at 0:22 → new player joins → timer resets to 0:30
• Timer at 0:15 → new player joins → timer resets to 0:30
• Timer at 1:45 → new player joins → timer stays at 1:45 (above 30s, no extension)

Condition 3: Max players reached

• When 40 players have joined → game starts immediately
• No waiting for the timer

Minimum players

• 1 player minimum required to start
• If timer expires with 0 players, timer resets and waits for the first player

Player Join Flow (Unchanged core, simplified entry)

1. Player scans QR code on common screen
2. Lands on /play/{code} — join page
3. Enters player name (email remains optional)
4. POST /play/{code}/join registers player
5. Player sees "Get Ready" screen with lobby countdown
6. SSE keeps player updated on lobby state and game start

Auto-Progression Through Questions

With no facilitator, the game must auto-advance:

1. COUNTDOWN (5 seconds) → PLAYING
2. PLAYING → question timer runs (e.g., 60 seconds)
3. When timer expires OR all players have answered → REVIEWING
4. REVIEWING lasts a fixed duration (e.g., 10 seconds) → auto-advance
5. If more questions remain → back to COUNTDOWN
6. If no more questions → RESULTS

Results and Restart Cycle

1. RESULTS displayed for a fixed period (e.g., 60 seconds)

• Rankings, winner highlight, stats
• Rolling credits animation

1. COOLDOWN → brief pause (e.g., 10 seconds)
2. AUTO_LOBBY → new game session auto-created with a new random question set
3. Cycle repeats indefinitely

The common screen never goes blank or requires manual intervention.

API Changes Required

Removed endpoints (facilitator)

• ~~POST /api/games~~ — replaced by auto-creation on root URL visit
• ~~PUT /api/games/{code}/config~~ — defaults are used
• ~~POST /api/games/{code}/start~~ — auto-start replaces manual start
• ~~POST /api/games/{code}/next~~ — auto-advance replaces manual next
• ~~POST /api/games/{code}/halt~~ — no emergency stop needed without facilitator
• ~~POST /api/games/{code}/end~~ — auto-transition to cooldown

New/modified endpoints

• GET / — creates auto-lobby, returns common screen
• GET /api/games/{code}/lobby-timer — returns remaining lobby time and player count
• SSE events should include lobby-timer updates when players join (timer extension)

Kept endpoints (player + common screen)

• POST /api/games/{code}/players — join game (only during AUTO_LOBBY)
• GET /api/games/{code}/questions/current — get current question
• POST /api/games/{code}/questions/{index}/answers — submit answer
• GET /api/games/{code}/results — get final results
• GET /api/games/{code}/state — common screen state
• All SSE endpoints

Web Routes (Updated)

Route	Purpose
GET /	Auto-create lobby, render common screen
GET /screen/{code}	Common screen for a specific game
SSE /screen/{code}/events	Real-time common screen updates
GET /play/{code}	Player join page
POST /play/{code}/join	Register player
POST /play/{code}/answer	Submit answer
SSE /play/{code}/events	Real-time player updates

The /facilitator routes are removed.

Common Screen Display States

AUTO_LOBBY (waiting for players)

• Large QR code (center)
• Join URL and game code (below QR)
• Lobby countdown timer (prominent, top)
• Player list (scrolling, updates live via SSE)
• "Scan to join!" call to action

COUNTDOWN (between questions)

• Question number indicator ("Question 3 of 10")
• Countdown animation (5, 4, 3, 2, 1)

PLAYING (question active)

• Question text at top (readable from distance)
• Question illustration mid-right
• Timer countdown mid-left
• Players joined / answers received counter

REVIEWING (after question)

• Correct answer revealed
• Stats: first to answer, best delta, median delta
• Auto-advances after fixed duration

RESULTS (game over)

• Ranked leaderboard
• Winner highlight
• Response time stats
• "Next game starting in..." countdown

Configuration Defaults

Parameter	Default	Notes
Lobby timeout	300s (5 min)	From first player join
Lobby extension	30s	Added when player joins with <30s remaining
Max players	40	Immediate start when reached
Min players	1	Must have at least 1 to start
Questions per game	10	From question set
Question time limit	60s	Per question
Countdown between questions	5s	Before each question
Review duration	10s	Auto-advance after review
Results display	60s	Before auto-restart
Cooldown	10s	Between results and new lobby
Question set selection	Random	Rotate through available sets