Presenter-Mode Live Answers (QR) — Design Spec

Date: 2026-07-21 · Approved by: Mario (chat, "do it!")

What it is

In the Academy player's presenter mode, an instructor can turn on Live Answers. Question slides then show a QR code + join code; students scan ONCE, stay connected on their phones for the whole lesson, and answer every question the instructor shows. The big screen shows a live A/B/C/D bar tally + answered count; on reveal the correct bar lights green on screen and phones. At the end the instructor gets a per-student score report.

Decisions (locked in the interview)

• Scope: ALL question slides — Progress Review quick-checks AND the 10-question final quiz.
• Join flow: scan once, stay connected (Kahoot-style). QR + short join code on question slides.
• Screen during answering: live bar tally + "N of M answered"; reveal lights the correct answer green.
• Identity: named — signed-in account name, or typed name if not signed in.
• Phone view: buttons only (option text on big A/B/C/D buttons; students read the question off the big screen).
• Report: yes — per-student scores + most-missed questions, saved with the session.
• Approach: Option A — reuse the existing Classroom Live Quiz engine (classroom_sessions Firestore collection + the /classroom phone-join page). No new backend, $0.

Architecture

• Host side (academy-player.html):
  • New "Live Answers" toggle in the settings gear, visible ONLY to admins/instructors (same gating as ?instructor=1 / window.__ACAD_INSTRUCTOR + admin check). Students never see it.
  • Turning it on creates a classroom_sessions doc (same schema the Classroom host uses: joinCode, status, current question {text, options, correct}, participants + answers subcollections), tagged source: 'academy', plus deck id + lesson title.
  • On every question slide (review, quiz question) the player pushes THAT question to the session — with the on-screen (already-shuffled) option order so letters always match — and renders a side panel: QR (api.qrserver.com, same as Classroom) + join code + live bars + answered count via an answers snapshot listener.
  • Reveal: when the instructor reveals/answers on screen (or advances), the session doc is marked revealed with the correct index; phones show right/wrong.
  • Non-question slides → session status waiting; phones show a "waiting for the next question" screen.
  • Ending the session (toggle off, end button, or leaving the lesson) → status ended + report overlay (per-student scores, most-missed questions). Data stays in the session doc (askedHistory-style) like Classroom reports.
• Student side (classroom.html): reuse the join page. Additions: honor a buttons-only flag (hide question text when the session says so) and the waiting state between questions. Everything else (join by code/QR, answer write, reveal feedback, score) already exists.

Error handling

• No signed-in user on the phone → name prompt (existing Classroom behavior).
• Firestore write fails / offline → panel shows "reconnecting"; answers are one-tap idempotent (doc per student per question index, last write wins — existing pattern).
• Instructor closes the tab without ending → session docs are harmless; a new session gets a new code. (Same as Classroom today.)
• Question bank safety: only the currently-shown question is pushed; the deck is never exposed to the phones.

Testing

• Syntax-check both HTML files' scripts.
• Browser-verify: desktop presenter view with QR panel; phone join at 375px; answer→tally→reveal round trip; waiting state; report overlay.
• Verify students (non-admin) never see the toggle.

Mobile

Both sides tested at 375px per CLAUDE.md rule 18. The QR panel must not break the no-scroll slide layout on desktop; on phones the panel stacks.