Live Quiz Platform — Host app

Combined app document — Host app


Status	Draft
App	Host app
Generated	2026-06-05
Source of truth	`.claude/context/apps/host.md`

The TV-show app — runs the live quiz session on a TV or projector. Receives .quiz packages from the Designer over local Wi-Fi, advertises itself for Clients to discover, advances slides during the session, and is paired with a Remote for quizmaster control. Runs on iPad, Windows, macOS, and Android tablets.

Overview

The Host renders the Host canvas of each slide at the connected display's native resolution (typical target: 1920×1080 TV or projector). It is the authoritative source of session state — timer, scores, slide pointer, locked/unlocked input — and pushes per-Client slide content eagerly to each Client as it joins.

The Host also accepts a paired Remote (one per session) over a control-message WebSocket. The Remote drives navigation, sees the slide mirror + host-notes + live state, and (in Alpha) issues rich commands like jump-to-slide and trigger-element-reveal.

For the cross-cutting requirements, scope, and platform list, see the project PRD.

User flows

Per-flow diagrams (lifecycle, idle/load, join, session controls, fallback overlay, Remote pairing) live on the dedicated flow page, each linked to its relevant UI mockups.

Full flow diagrams — App lifecycle · Idle + load · Join + start · Session controls · Single-display fallback overlay · Remote pairing. Each flow links to the mockups it touches.
Surface inventory matrix — Every screen / panel / control / dialog with leads-to targets, phase tags, FR references.
Mockup launcher → — Browse every static mockup in one browser tab.

Architecture

A Unity project, sibling to Quiz.Client, Quiz.Remote, and Quiz.Preview. Two top-level scenes — MainMenu (pre-quiz lobby: load .quiz, accept Designer transfers, list connected teams, start session) and Play (slide-driven runner). References com.quiz.shared-assets, com.quiz.runtime, com.quiz.core via UPM. See Per-App Scaffolding — Host for the on-disk shape. Cross-cutting:

Architecture overview for the platform-level diagram.
Networking for the WebSocket transport, mDNS advertisement, eager-push model, and authoritative-timer mechanics.
Quiz Package Format for the .quiz archive shape the Host loads.
Backend Schema (stretch) for the cloud-backed library path the Host would consume in a future release.

Design notes

The brand identity, palette, typography, and motion language are project-wide and live in the Design Specification. The audience-window (Showtime) treatment is in that doc; the operator-window chrome rules are in the Studio Design Spec. Host-specific design notes are tagged *{host}*.

Build plan

The Host's items are part of the single project Build Plan. Filter visually for host — Host-tagged work is concentrated in Load-bearing prototype, Designer→Host transfer (Host side), Host live-session features, Crash recovery, First-pass animation.

User flows — detail

Surface-to-surface navigation flows for the Host. Each diagram shows the happy path forward only — same-screen actions (next slide, +10s, lock, mute jingles, etc.) live in prose under the diagram, not as self-loops on the canvas. Authoring conventions and theme tokens live in .claude/skills/mermaid-diagrams/SKILL.md.

Surfaces in Host surfaces. Functional requirements in Functional Requirements — Host.

2. Idle and load

Mockups: Idle · Incoming transfer · Package incompatible · Settings

%%{init: {"theme":"base","themeVariables":{"fontFamily":"Inter, system-ui, sans-serif","fontSize":"14px","primaryColor":"#FFFFFF","primaryBorderColor":"#FF009F","primaryTextColor":"#1F1933","secondaryColor":"#F0EBE3","secondaryBorderColor":"#16B2EB","secondaryTextColor":"#1F1933","tertiaryColor":"#F8F5F0","tertiaryBorderColor":"#5A536B","tertiaryTextColor":"#1F1933","lineColor":"#5A536B","edgeLabelBackground":"#F8F5F0","mainBkg":"#F8F5F0","clusterBkg":"#F0EBE3","clusterBorder":"#DDD5C8","titleColor":"#1F1933","nodeBorder":"#5A536B"},"flowchart":{"useMaxWidth":true,"htmlLabels":true,"curve":"basis","padding":20,"nodeSpacing":70,"rankSpacing":80}}}%% flowchart LR ID[Idle
loaded quizzes + toolbar] -->|tap quiz| LD[Loaded · awaiting start] ID -->|Load file… / incoming push| RCV[Receive + validate] RCV -->|valid| ID RCV -->|type mismatch| PI[Package-incompatible] LD --> JO[Join screen] classDef terminal fill:#E8F5EC,stroke:#36D17B,stroke-width:2px,color:#1F1933,rx:14,ry:14 class JO terminal

On-screen actions (no navigation): toolbar — Settings dialog, Sign-in (Stretch), session-code visibility. Quiz row long-press opens context menu (Start session → Join · Preview slides → Loaded · Delete from device). Incoming-transfer prompt confirms → progress bar → done banner; reject returns to Idle.

3. Join and start

Mockups: Join screen · Remote pair prompt

%%{init: {"theme":"base","themeVariables":{"fontFamily":"Inter, system-ui, sans-serif","fontSize":"14px","primaryColor":"#FFFFFF","primaryBorderColor":"#FF009F","primaryTextColor":"#1F1933","secondaryColor":"#F0EBE3","secondaryBorderColor":"#16B2EB","secondaryTextColor":"#1F1933","tertiaryColor":"#F8F5F0","tertiaryBorderColor":"#5A536B","tertiaryTextColor":"#1F1933","lineColor":"#5A536B","edgeLabelBackground":"#F8F5F0","mainBkg":"#F8F5F0","clusterBkg":"#F0EBE3","clusterBorder":"#DDD5C8","titleColor":"#1F1933","nodeBorder":"#5A536B"},"flowchart":{"useMaxWidth":true,"htmlLabels":true,"curve":"basis","padding":20,"nodeSpacing":70,"rankSpacing":80}}}%% flowchart LR JO[Join screen
QR + URL + code + roster] -->|Start quiz ▸| SE[Session] JO --> RP[Remote pair prompt] RP -->|Remote accepted| JO classDef terminal fill:#E8F5EC,stroke:#36D17B,stroke-width:2px,color:#1F1933,rx:14,ry:14 class SE terminal

Roster actions (no navigation): team rows fill as Clients connect; long-press a row → context menu (Rename / Kick / Assign colour — Beta). Back to library: prompts confirm if any teams have joined; returns to Idle.

4. Session controls (operator window)

Mockups: Operator window · Audience window · Jump to slide · Score overrides · Pause · End-session confirm · Final standings

%%{init: {"theme":"base","themeVariables":{"fontFamily":"Inter, system-ui, sans-serif","fontSize":"14px","primaryColor":"#FFFFFF","primaryBorderColor":"#FF009F","primaryTextColor":"#1F1933","secondaryColor":"#F0EBE3","secondaryBorderColor":"#16B2EB","secondaryTextColor":"#1F1933","tertiaryColor":"#F8F5F0","tertiaryBorderColor":"#5A536B","tertiaryTextColor":"#1F1933","lineColor":"#5A536B","edgeLabelBackground":"#F8F5F0","mainBkg":"#F8F5F0","clusterBkg":"#F0EBE3","clusterBorder":"#DDD5C8","titleColor":"#1F1933","nodeBorder":"#5A536B"},"flowchart":{"useMaxWidth":true,"htmlLabels":true,"curve":"basis","padding":20,"nodeSpacing":70,"rankSpacing":80}}}%% flowchart TB SE[Session
operator + audience windows] SE --> PA[Paused overlay] SE --> JTS[Jump dialog — Alpha] SE --> SO[Score overrides — Alpha] SE --> ENC[End-session confirm] ENC -->|End| EN[Final standings] classDef terminal fill:#E8F5EC,stroke:#36D17B,stroke-width:2px,color:#1F1933,rx:14,ry:14 class EN terminal

Inline session controls (no navigation — buttons fire commands, audience window updates in place): Next slide / Previous · + 10 s / Skip timer / Lock now / Unlock · Show leaderboard · Trigger reveal (Alpha) · Mute jingles. Off-path overlays: Paused overlay → Resume; Jump / Overrides modals → Apply or Cancel returns to Session. Disconnects surface as banners (Client disconnect · Remote disconnect) and disappear on reconnect; no navigation.

5. Single-display fallback

Mockups: Audience window (overlay state)

On a machine with one display the operator window becomes a summoned overlay, not a separate window. Inputs (tap / move mouse) reveal the control row; auto-hides after 4 s of inactivity. Both states are the same Session screen — no separate node.

6. Remote pairing

Mockups: Remote pair prompt

%%{init: {"theme":"base","themeVariables":{"fontFamily":"Inter, system-ui, sans-serif","fontSize":"14px","primaryColor":"#FFFFFF","primaryBorderColor":"#FF009F","primaryTextColor":"#1F1933","secondaryColor":"#F0EBE3","secondaryBorderColor":"#16B2EB","secondaryTextColor":"#1F1933","tertiaryColor":"#F8F5F0","tertiaryBorderColor":"#5A536B","tertiaryTextColor":"#1F1933","lineColor":"#5A536B","edgeLabelBackground":"#F8F5F0","mainBkg":"#F8F5F0","clusterBkg":"#F0EBE3","clusterBorder":"#DDD5C8","titleColor":"#1F1933","nodeBorder":"#5A536B"},"flowchart":{"useMaxWidth":true,"htmlLabels":true,"curve":"basis","padding":20,"nodeSpacing":70,"rankSpacing":80}}}%% flowchart LR RPP[Pair prompt
code + QR] --> WAIT[Wait for Remote] WAIT --> RA[Accept-Remote prompt] RA -->|Accept| PAIRED[Paired] classDef terminal fill:#E8F5EC,stroke:#36D17B,stroke-width:2px,color:#1F1933,rx:14,ry:14 class PAIRED terminal

On-screen actions: Regenerate code (cycles the visible code, stays on prompt); Reject (back to waiting). Remote disconnect while paired returns the operator HUD to "no Remote paired" state inline; no navigation.

Design specification — cross-cutting brand

Shared brand language across all four apps (see Applications). Source of truth for cross-cutting requirement F-X-3. Brand-true treatment lands at Beta; MVP and Alpha are visually utilitarian. Operator-chrome rules for Designer / Host operator / Remote live in Design Specification — Studio.

Final product / brand name deferred to Beta — see open questions. This spec refers to apps by engineering project names (Quiz.Designer, Quiz.Host, Quiz.Client, Quiz.Remote).

Brand identity

Asset	Treatment
Wordmark	Bold, slightly condensed uppercase display face, white fill with heavy black drop shadow. Final wording locked at Beta.
Tagline	Clean uppercase sans, lighter weight, white on dark, neon underline accent. Final wording locked at Beta.
Logomark	Stylised Q with a checkmark tucked inside it in hot magenta with a black drop shadow. Iconographic, not an initialism.
Mascot	Friendly cartoon smartphone — pink/magenta body, big cartoon eyes, white-gloved waving hand, white shoes. Rigged once, reused across all four apps with context-appropriate poses. Rig lands at Beta.

Tone: live quiz on a Saturday night, televised. High contrast, vibrant gradients, neon edges. Mascot keeps warmth and humour under the energy.

Colour palette

Core hues

Token	Hex	Usage
`color.magenta`	`#FF009F`	Primary brand accent; logomark; key CTAs; big-reveal highlights.
`color.electric-blue`	`#16B2EB`	Secondary brand accent; live-state indicators; secondary CTAs.
`color.deep-purple`	`#961EEF`	Transitional gradient stop; high-energy backgrounds; big-reveal stages.
`color.white`	`#FFFFFF`	Wordmark fill; primary text on dark.
`color.near-black`	`#0F0B1A`	Primary text on light; neutral surfaces. Slight purple tint reads brand-consistent.

Gradients + glow

Brand gradient — linear, left→right: magenta → deep-purple → electric-blue. Reserved for hero surfaces.
Subtle backdrop — brand gradient with low-opacity low-poly facet overlay. For content-heavy surfaces.
Neon glow — outer glow (high blur, brand-coloured, additive blend) on framed surfaces, big-reveal headings, active leaderboard rows. Use sparingly.

QUIZ NIGHT

Theming

Two independent theme layers, both Beta:

Studio operator-chrome theme designer host remote — calm low-chroma chrome for Designer, the Host operator window, and Remote. Each ships light + dark. See Design Specification — Studio. Only the Client phone and the Host audience window render full Showtime.
Per-quiz theme on Host / Client / Remote hostclientremote — quiz manifest declares a theme (enum: dark, light, brand presets). Default is dark brand theme. Richer custom palettes are Stretch.

Studio chrome theme and per-quiz theme are independent — an author might author in light Studio chrome but ship a dark-themed quiz.

Typography

Role	Family
Display / headings / numerals (scores, timers, countdowns)	Bebas Neue — tall condensed uppercase, tight tracking, drop shadow on dark.
Body / UI	Inter — geometric sans, sentence case, generous line-height.
Mono (codes, timestamps, debug, metadata labels)	JetBrains Mono.

Rules

Headings uppercase, bold, tight letter-spacing, drop shadow on dark.
No more than two type families visible at once.
Numbers (scores, timers) use the display face for impact.

Samples

Family	Sample
Bebas Neue · headline	QUIZ NIGHT TONIGHT
Bebas Neue · score	42
Inter · body	A quick brown fox jumps over the lazy dog.
JetBrains Mono · metadata	core.multiple-choice-input v1.0.0

Visual motifs

Neon glow borders on hero panels, leaderboards, big-reveal stages.
Low-poly facet textures as subtle overlays on gradients.
Gradient backdrops — full saturation for hero only; tone down for content-heavy.
Cartoon mascot on launch, empty states, loading, end-of-quiz. Pose matches context.

Iconography

Bold and chunky, geometric, weight matches the display typography. No hairlines.
External imagery (photos, screenshots) sits inside framed cards with neon-glow borders.

Motion

Confident and snappy. Spring-driven transitions with slight overshoot. Avoid lazy ease-in/out.
Big reveals — combined scale + glow pulse + branded audio sting. Reserve for genuine reveals.
Idle states — mascot in subtle motion (idle bob, blink) over abstract spinners.

Implementation details, performance budgets, and engine-side mechanics live in Architecture — Tech Stack and Non-Functional Requirements.

Sound design

Full audio language lands at Beta:

Stings — correct, incorrect, time-up, lock, big reveal, end of round, end of quiz.
Transitions — slide-advance whoosh, leaderboard reveal swell, round-change motif.
Big-reveal audio — branded sting paired with the visual reveal motif.
Ambient music bed (light) — optional between rounds; muted during questions.
Buzzer jingles (Alpha — earlier than the rest). Teams pick at join (F-CL-15); Host plays on first-press win (F-HO-27). Author-supplied; small built-in default library (F-DE-29). Mixed at the same loudness band as branded stings.

Mix for venue noise: stings cut through pub ambient without being intrusive.

Team identity client host

Each team bundles name, colour (Beta), avatar (premade or photo, Alpha), buzzer jingle (Alpha) at join. Identity carries through every Host moment featuring the team: leaderboard rows, big-reveal callouts, correct-answer pings, buzzer-win playback. Team photos render at a fixed circular crop at leaderboard scale and a larger square crop on the join-screen roster. Premade avatars use the same crop so the leaderboard reads consistently regardless of source.

Layout and spacing

Spacing scale — 8 px base: 4, 8, 16, 24, 32, 48, 64, 96. No other values.

Host canvas host

Fixed virtual 1920×1080 (16:9), scales to the connected display. Absolute coordinates. Large type, generous spacing, readable across a room. Low density, high impact.

Voice and tone

Friendly and confident — host who knows the room and is having fun.
Concise — pub-quiz rhythm; copy that drags kills the energy.
Playful, not silly — wit and mild theatre.
Inclusive — no in-jokes, no jargon.

Design specification — Studio operator chrome

Operator-facing chrome for Designer, the Host operator window, and Remote. Where this page and the cross-cutting Design Specification disagree, this page wins for chrome surfaces; where this page is silent, fall back to the cross-cutting spec.

Principle — chrome calm, canvas loud. Operator surfaces sit at low chroma; the embedded canvas / audience-mirror region inside each operator app renders full Showtime.

Which surface gets which theme

App	Surface	Theme
Quiz.Designer	Entire app (chrome + dialogs). Preview canvas renders Showtime inside.	Studio.
Quiz.Host	Audience window (projector / TV).	Showtime — see `design-spec.md`.
Quiz.Host	Operator window (laptop / iPad). The embedded audience preview renders Showtime.	Studio.
Quiz.Client	Entire app. Team phone, audience-facing.	Showtime — see `design-spec.md`.
Quiz.Remote	Entire app. The embedded audience-mirror renders Showtime.	Studio.

Chrome surface tokens

Scheme: Indigo Nebula. Dark = deep cool indigo with subtle warm-peach tint glow. Light = warm cream paper with the same peach tint, visible. The chrome stays flat — only the page-level bg-glow carries any gradient.

Dark theme — deep indigo, warm-peach undertone

Token	Hex	Usage
`chrome.base`	`#11101A`	Application window background; canvas / mirror backdrop. Deep cool indigo.
`chrome.panel`	`#181722`	Top toolbar; dialog body; popovers; primary inset surface.
`chrome.paper`	`#1F1E2A`	Side panels; titlebar; statusbar.
`chrome.raised`	`#1E1D29`	Selected row; input fill; segment-control background.
`chrome.hover`	`#272636`	Hover state for rows and buttons.
`chrome.border`	`rgba(200,195,200,0.09)`	Hairline divider. 1 px, never thicker.
`chrome.border-strong`	`rgba(200,195,200,0.18)`	Active border on focused / selected raised elements.
`chrome.text`	`#E0DDDA`	Primary copy, slide names, headings. Warm off-white.
`chrome.text-muted`	`#928E97`	Secondary copy, helper text, panel headings.
`chrome.text-subtle`	`#5C5862`	Labels, metadata, mono runs, statusbar text.
`chrome.tint`	`radial peach @ 6%`	Page-level bg-glow over `chrome.base`. Anchors warm undertone behind cool surfaces.

Light theme — warm cream, visible peach wash

Token	Hex	Usage
`chrome.base`	`#F5F2EE`	Application window; canvas / mirror backdrop. Warm cream, never bone-white.
`chrome.panel`	`#FFFFFF`	Top toolbar; card; input fill; dialog body.
`chrome.paper`	`#ECE7E0`	Side panels; statusbar; secondary surface.
`chrome.raised`	`#ECE7E0`	Selected row; segment-control background; hover-into-selected.
`chrome.hover`	`#D4CFC8`	Strong hover; pressed state.
`chrome.border`	`rgba(31,28,36,0.10)`	Hairline divider. Warm ink.
`chrome.border-strong`	`rgba(31,28,36,0.18)`	Active border on focused / selected raised elements.
`chrome.text`	`#1F1C24`	Primary copy. Warm-near-black.
`chrome.text-muted`	`#5F5C68`	Secondary copy, helper text.
`chrome.text-subtle`	`#959099`	Labels, metadata, mono runs.
`chrome.tint`	`radial peach @ 14%`	Page-level bg-glow over `chrome.base`. Carries the scheme's warm signature on light.

Brand-hue ration in chrome

The chrome accents diverge from the Showtime brand-locked colors. Studio's three accent slots are studio-specific values, not the cross-cutting branding.jpg magenta / electric-blue / deep-purple.

Hue (slot)	Dark	Light	Where it appears	Where it does not
`accent` (warm pink)	`#FF3D9A`	`#E5217F`	Logomark tile in toolbar (rounded square, accent fill, white "Q"); primary CTA (Designer Push to Host / New Quiz / Save when unsaved; Host Start Session / Resume; Remote Advance); active-row left-edge indicator (2 px inset shadow); focus ring on text inputs only for the primary action.	Panel fills, surface gradients, large area accents, hover backgrounds, decorative use.
`info` (muted teal)	`#5FA0A8`	`#3F767E`	Generic focus ring (input, button); inline links; secondary CTA (Designer Reconnect, Host Discover Hosts, Remote Re-pair); info badges; selection outline on canvas elements.	Panel fills, hero gradients.
`tint` (warm peach)	`#C89070`	`#A5673F`	Page-level bg-glow only — radial wash behind `chrome.base`. Drives the row-hover wash at low alpha.	Anywhere directly on chrome surfaces; on canvas-rendered content.

Showtime brand hues (magenta #FF009F, electric-blue #16B2EB, deep-purple #961EEF) appear only inside the embedded canvas / audience-mirror region — never on Studio chrome. The mockups render Studio chrome accents for slide-thumbnail decoration purely as approximation; live Quiz.Preview renders Showtime at full saturation per the cross-cutting Design Specification.

Showtime warm-support hues (coral, sunshine, rose, peach) do not appear in Studio chrome — canvas / mirror only.

Status hues

Token	Hex	Role
`mint`	`#36D17B`	Save / connection / pair success; auto-save dot; live indicator when Hosts have clients connected.
`amber`	`#FFA94D`	Unsaved-changes dot (Designer titlebar); transfer-pending dot (Host); reconnecting dot (Remote); timer-low; caution states.
`crimson`	`#E63946`	Destructive action (Delete Quiz, End Session, Unpair); validation-error border; failure banner.

Typography in chrome

Body — Inter, 13 px primary, 12 px tool buttons / panel headers, 11 px panel titles.
Display — Bebas Neue, sparingly. Dialog headlines (≥ 24 px), welcome / discover surfaces, section dividers in long dialogs.
Mono — JetBrains Mono carries weight here. Slide indices, session codes, file paths, version numbers, save timestamps, type labels, panel-title labels (SLIDES · 20), keyboard shortcuts in menus, statusbar items. Mono is the structural signal: this is metadata.

Statusbar uppercase mono (AUTOSAVE 14:32, BUILD 2026.05.13). Side-panel titles uppercase mono with 3 px letter-spacing. Tool-button labels sentence-case Inter.

Per-app components

Designer

Region	Spec
Toolbar (top)	52 px, `chrome.panel`, logomark left, document name, tool-button groups, primary CTA right.
Left panel — slide list	240 px, `chrome.paper`, mono panel title, slide rows with index + thumbnail + meta. Active row: `chrome.raised` + 2 px `accent` inset shadow left.
Canvas (centre)	`chrome.base` backdrop with 24 px grid. Embedded 16:9 canvas renders full Showtime. Floating canvas toolbar bottom-centred.
Right panel — properties inspector	280 px, `chrome.paper`, mono panel title, property groups separated by 1 px borders. Inputs `chrome.raised`. Focus ring `info`.
Statusbar (bottom)	28 px, `chrome.paper`, mono items, mint / amber status dots.

Host operator window

Region	Spec
Title bar	Same vocabulary as Designer. Mono session code (`7K2-9P`) visible.
Audience-mirror	Sized to projector / TV aspect (typically 16:9), framed by `chrome.base`, renders the current slide at full Showtime saturation.
Host-notes pane	`chrome.paper`, generous line-height for session-running distance. Inter body; `chrome.text-muted` for code refs.
Control bar (bottom)	`chrome.panel`. Primary actions (Advance, Reveal, Lock, Timer, End Session). Mono session HUD on right (slide index, timer, score totals).
Connected-clients list	`chrome.paper` showing each team's name + colour dot + connection status. Mint = connected; amber = recently dropped; crimson = disconnected.

Remote

Region	Spec
Top bar	44 px, `chrome.panel`, paired-Host name centre, pairing status dot right. Logomark optional.
Audience-mirror	16:9 aspect, full Showtime inside, framed by `chrome.base`.
Host-notes pane	`chrome.paper`, generous Inter line-height for read-while-walking.
Control surface	`chrome.panel`. Primary action (Advance) — `accent` fill, 56×56 pt min. Secondary actions (back, reveal, lock, timer override, score override) `chrome.raised` 44×44 pt min. Heavy mono labels above each group (`NAV`, `REVEAL`, `LOCK`, `TIMER`).
Splash / discover	Welcome surface — brand gradient hero allowed here per cross-cutting spec.

Default theme per app

App	Default	Why
Quiz.Designer	Light	Long authoring sessions — easier on the eyes for hours.
Quiz.Host operator	Dark	Sessions in low-light venues; operator at the back of the room reads better off dark.
Quiz.Remote	Dark	Quizmaster walks low-light venues; dark reduces glare.

All three ship the other theme too, selectable in settings. Per-quiz theme on the Host audience window and Client is independent.