weirsoe-party-protocol/docs/plans/2026-03-18-host-player-visual-overhaul-plan.md

Host + Player Visual Overhaul Plan

Date: 2026-03-18
Updated: 2026-03-23
Status: Active

Goal

• make the SPA host shell usable as the projected primary game screen
• make the SPA player shell a minimal mobile action surface instead of a secondary dashboard
• make phase changes feel shared across devices, without manual refresh in the normal path
• keep explicit developer-state available for host and player without contaminating the default presentation

Product Decisions From Playtesting

• the authenticated host may still create the session and choose the game, but the first player to join becomes the lobby captain on a phone
• the lobby captain is the default pre-game operator on the player side:
  • can start the game
  • can confirm readiness
  • can choose or rotate a player icon from a curated set when that is supported by the cartridge
• non-captain player devices should stay intentionally simple before game start:
  • icon selection if the game supports it
  • otherwise a passive "wait for the game to start" state
• once the game has started, player devices should only show the current player action:
  • text input
  • buttons
  • draw area
  • hidden private information when a cartridge needs it
• player devices should not show roster, session metadata, or broad game-state detail in the default UX
• pushed updates need to land across clients in the same phase-change window; perfect instant sync is not required, but manual update should not be part of the happy path

Current State

• role-aware session-detail payloads already exist for host/player/public viewers
• websocket transport and reconnect fallback already exist
• host/player developer-state toggles already exist
• presenter/player visual styling, question ornaments, and host voice playback already exist
• the remaining gaps are mostly product-shape gaps:
  • lobby captain flow is not yet the default
  • the default player shell still exposes too much context
  • synchronized multi-device updates are not yet strong enough for confidence
  • authored player identity assets and presenter-copy content are still incomplete

Non-Goals

• solving every future cartridge in this lane
• custom user-uploaded avatars
• full spectator mode
• native mobile apps
• replacing the existing REST contract wholesale

Known Issues To Solve

• a player phone cannot yet reliably act as the pre-game "start game" controller
• some clients still feel stale until a manual update path is used
• the default player UI still behaves too much like a diagnostic shell
• the plan file itself previously drifted into websocket-only scope; this document is now the authoritative visual-overhaul plan again

Verification

• .venv/bin/python manage.py check
• .venv/bin/python manage.py test realtime.tests lobby.tests.SessionDetailPhaseViewModelTests fupogfakta.tests.FupOgFaktaExtractionSliceTests
• npm --prefix frontend test -- angular-api-client.test.ts
• npm --prefix frontend/angular test -- src/app/features/host/host-shell.component.spec.ts src/app/features/player/player-shell.component.spec.ts src/app/realtime-visual-smoke.spec.ts
• npm --prefix frontend/angular run build
• local or staging multi-device smoke captured with docs/SPA_VISUAL_REALTIME_SMOKE_ARTIFACT.md

Batch 1 — Lobby Captain Flow

• add an explicit lobby-captain concept to the session contract
• the first player to join becomes the default captain
• expose captain capability to the player shell:
  • start game
  • ready/continue controls where appropriate
  • pre-game icon selection when supported
• keep a clear fallback/override story for dev and staging:
  • authenticated host can still inspect or recover the flow
  • developer-state shows who the current captain is and why
• update lobby and gameplay rules so "who can start" is deterministic and testable

Acceptance: in the normal couch + TV flow, the first joined player can start the game from a phone without needing the projected host screen as an operator console.

Batch 2 — Realtime Coherence

• treat websocket push as the primary phase-change transport
• make every significant phase transition emit enough information for all connected clients to converge without user action
• add or tighten revision/phase markers so stale refreshes do not leave some devices behind
• keep polling only as fallback and recovery
• if realtime recovery takes longer than a short threshold, show a clear reconnect notice instead of silently leaving stale UI on screen
• extend tests to cover one host plus three player clients moving through the same phase transition window

Acceptance: phase changes propagate across host and player clients together closely enough that manual update is not required in the happy path.

Batch 3 — Simplified Player Phone UX

• reduce the default player shell to one main action surface per phase
• pre-game states:
  • captain device: start game + identity/icon choice if supported
  • non-captain devices: icon choice or passive wait state
• in-game states:
  • input-only or choice-only when action is required
  • simple waiting state when no action is required
  • private hidden information panel when a cartridge needs it
• remove roster/session/debug context from the default player presentation
• keep developer-state behind the existing explicit toggle/query override
• preserve draft text, selections, and focus during background sync and reconnect

Acceptance: a player can glance at the phone and immediately know what to do, without seeing unnecessary room/session detail.

Batch 4 — Presenter Host Experience

• keep the host screen presenter-first:
  • lobby scene
  • question/lie scene
  • guess scene
  • reveal scene
  • scoreboard scene
  • final result scene
• show the question prominently on the projected host even when players only get input controls
• display player icons/colors consistently across all presenter beats
• keep operational controls in a secondary backstage layer instead of the default projected surface
• integrate voice cues and uploaded audio into the presenter rhythm
• make the default lobby scene support the new player-captain model:
  • projected host shows readiness and roster
  • captain phone owns the start action

Acceptance: the host screen can stay on the TV as the main visual surface without asking the projected operator to click through the game.

Batch 5 — Content, Assets, and Cartridge Hooks

• add content/admin support for curated player icon sets or avatar-like identity options
• keep authored question ornaments and extend them where useful
• add optional phase-specific presenter copy that can be authored instead of only inferred from shared i18n keys
• define one generic private-info contract for cartridges that need hidden player instructions or roles
• keep the fallback story explicit:
  • deterministic icons and copy still work when authored assets are absent

Acceptance: the visual lane is not blocked on hardcoded placeholder assets, and future cartridges have a place to attach hidden player info without bloating the default phone UX.

Batch 6 — Smoke Coverage and Sign-Off

• extend automated smoke for:
  • first-player captain start
  • websocket phase propagation across host + 3 player clients
  • no-input-loss during reconnect
  • presenter-only question visibility
  • hidden player info routing where applicable
  • developer-state visibility and safety gates
• extend the manual artifact checklist so it proves:
  • projected host during lobby, reveal, and scoreboard
  • captain phone start flow
  • at least 3 player devices
  • reconnect recovery without manual refresh
  • separate host/player developer-state captures

Acceptance: the overhaul is demonstrable in a realistic living-room flow, not just in isolated component tests.

Definition of Done

This lane is complete when:

• the first joined player can start the game from a phone in the normal flow
• non-captain phones stay intentionally minimal before game start
• player phones show only the current action or private hidden info by default
• websocket state sync is the primary update path and manual update is not required in the happy path
• the projected host screen is usable as a real presenter surface
• backend contracts remain role-correct
• host/player visuals share one coherent visual system
• regression tests cover realtime, visibility, and input preservation
• host and player both provide an explicit developer-state that is useful in dev/staging and hidden by default
• the multi-device artifact in docs/SPA_VISUAL_REALTIME_SMOKE_ARTIFACT.md has been captured for the current flow

Recommended Order

1. Batch 1: lobby captain flow.
2. Batch 2: realtime coherence.
3. Batch 3: simplified player phone UX.
4. Batch 4: presenter host flow adjustments for the captain model.
5. Batch 5: authored assets and cartridge hooks.
6. Batch 6: smoke coverage and sign-off.

Ralph Loop Exit Rule

• this plan should only be marked Completed when the Definition of Done is satisfied
• narrower websocket or sub-feature slices should be tracked as check-ins under this plan or in separate plan files, not by rewriting this file into a different plan

Explicitly Deferred

• custom uploaded user avatars
• advanced moderation/admin tooling
• spectator mode
• native mobile clients
• multi-cartridge theming beyond the shared shell and contract hooks above