Living Word Classroom Live-Play / Projector Host Mode (Phase D-4)
STATUS: DRAFT. This is the "Kahoot/Blooket expectation" — how the game gets used in the room on Sunday. It needs founder decisions (L1–L5) and is the largest remaining Wave-3 item (real-time coordination). Built on the shipped classrooms feature (#733–#737) + aggregate reporting (#740).
§1 — Purpose
A teacher launches a shared class session, the class plays the same scene together, and the teacher sees live progress on a projector. The deep-dive plan's strong steer: start async (poll a shared counter) — ~80% of the classroom value at ~10% of the realtime-infra cost — and only add true realtime if demand proves it out.
§2 — What exists / what's needed
- Have: classrooms + anonymous device-based students (
lw_classroom_students), aggregate activity (lw_classroom_student_activity), owner-scoped APIs. - Need: a "live session" concept (a row teachers open/close), a host view, a way for joined devices to know "we're in a live session on scene X," and progress aggregation during the session.
- Realtime tech (decision L1): Supabase Realtime is available on the shared instance; alternative is short-poll (e.g. 3–5s) of a session-progress endpoint. Async-poll is simpler, offline-tolerant, and avoids socket scaling — the recommended v1.
§3 — Decisions (founder)
| # | Decision | Options |
|---|---|---|
| L1 | Realtime mechanism | (a) Async poll a shared session-progress endpoint (recommended v1). (b) Supabase Realtime channels (true live, more infra). |
| L2 | What the host (projector) view shows | Live count of students "in" + per-scene/beat completion progress bar; aggregate only (no per-child leaderboard — consistent with reporting R3 + AI-Bridge "don't rank kids"). Decide whether nicknames appear at all on the projector. |
| L3 | Cooperative vs competitive | Plan steer = cooperative ("recover all 7 Creation scrolls together," body-of-Christ framing), NO individual ranking. Confirm. |
| L4 | Projector styling | Large-text/high-contrast host view, CTAs hidden (it's shown to a room of kids). Confirm a dedicated ?projector=1 host layout. |
| L5 | Session lifecycle | Who can start (owner only), max duration / auto-close, what happens to a student mid-session who loses connection (per-device resume). |
§4 — Proposed v1 (pending L1–L5)
lw_classroom_sessions (id, classroom_id, scene_id, status open|closed, started_at, closed_at). Teacher POST /classrooms/[id]/sessions opens one; host view polls GET /classrooms/[id]/sessions/active for aggregate progress (reuses lw_classroom_student_activity filtered to the session window). Joined devices see "Mrs. Smith started a live session — play [scene]" and their completions count toward the shared goal. Projector layout at ?projector=1. All aggregate; no per-child ranking.
§5 — Recommendation
Async-poll, cooperative, aggregate-only, projector layout. Defer true Supabase Realtime until a teacher asks for second-by-second liveness. This is a multi-PR build (session table + host APIs + host/projector UI + in-game session awareness) — size it after L1–L5.