Targeted fixes on top of the editorial-lecture-hall pass:
- Leaderboard rank columns now align across all rows; medal stripes
reserve their 3px width on every row (no more 6px shift between
podium and chasers). Silver bumps to higher-contrast values in both
light and dark modes.
- Student leaderboard gains a visible "you" highlight (blue stripe,
blue name + score, small "you" eyebrow under the name). Matches by
display name since the server's student-facing top5 doesn't include
student_id.
- Lobby and Finished states share an editorial state-cta treatment:
display-serif "Ready to start." / "That's a wrap." with a numeric
cta-stats strip that anchors the right column on a projector.
- "02 PRE-FLIGHT" eyebrow continues the "01 JOIN" sequence on the
side panel, giving the page a magazine-spread rhythm.
- Live distribution suppresses empty bars when zero submissions and
shows a calm italic "Bars appear once the first answer comes in."
line instead.
- Roster orders newest-first; the top three rows light their dot
green and the freshest row gets a soft pulsing halo, so the
operator sees the room filling up at a glance.
- Student reveal "Your pick" tag moves to a top-edge ribbon above the
option text so it stops colliding with the count column on phones.
Editorial-lecture-hall direction: Source Serif 4 for question prose
and headlines, IBM Plex Sans chrome, IBM Plex Mono for tabular numerics
(countdown, scores, rank, session id, join URL). Single ink-blue accent
in light mode, brass-amber in dark mode; warm paper background instead
of the soft grey wash. Dropped border-radius from soft 14px to a sharp
2-4px to read as printed material rather than consumer app.
Density rebalanced for the two viewing surfaces. Student question text
goes to clamp(1.5rem, 2.4vw, 1.95rem) so it dominates a 390px phone;
admin chrome (Q-num, countdown, hist labels) tightened so the projector
read is "QUESTION LIVE" + question + options + distribution at a glance
across a 1920x1080 lecture hall. State badge is uppercase + tracked
with a status dot; live state pulses, urgent countdown (<=10s) blinks.
Leaderboard becomes a tabular scoreboard: hairline borders, alternating
row tint, gold/silver/bronze left-border medals on top 3 only (no other
rank treatments), mono numerics throughout. QR panel now has its own
SCAN TO JOIN eyebrow, the URL row sits below in mono with a copy CTA,
session id rendered as a code chip, anchored as one shareable artifact.
Picked-answer button gets a 2-step settle (scale 0.97 -> 1, color
swap), correct-row reveal animates an inset border-draw, countdown bar
gets a slow breathing highlight overlay; all motion respects
prefers-reduced-motion. JS change is one line per SPA: toggle .urgent
on the countdown when remaining <= 10s.
Backend simplification:
- The server now loads ONE pool JSON from $QUIZ_POOL_PATH at startup and
upserts a single canonical session. The session id comes from the pool
JSON's optional "session_id" field, falling back to $QUIZ_SESSION_ID.
- The multi-quiz / multi-session CRUD API is gone:
DELETED GET/POST /admin/api/quizzes
DELETED POST /admin/api/quizzes/upload
DELETED GET/POST /admin/api/sessions
DELETED GET /admin/login (HTML stub)
DELETED GET /admin/api/sessions/{sid}/csv (replaced by /admin/api/csv)
Replaced with a single-session control surface:
GET /admin/ — serves admin.html unconditionally
GET /admin/api/state — admin-gated; pool meta + state + QR + join URL
POST /admin/api/reset — admin-gated; wipe submissions + back to lobby
POST /admin/logout — clear admin cookie
GET /admin/api/csv — single-session results
WS /ws/instructor/{sid} — kept; new commands "next" + "reset"
- Instructor "Next" button is now a single state-driving command
(RoomManager.advance_to_next): from lobby it opens Q0; from question_open
it closes the current Q and opens the next; from question_closed it
opens the next; if past the last question it ends the session.
- New RoomManager.reset wipes submissions, participants, and per-question
state, then broadcasts a clean lobby.
- Student GET / now redirects to /?sid=<canonical> when no sid is given,
so the QR / share URL is fully deterministic.
Frontend rewrite (functional baseline; visual polish to follow):
- /admin/ is now a single SPA: GET /admin/api/state decides login form
vs dashboard. No separate /admin/login URL bar.
- Admin dashboard is state-driven with one primary action per state.
QR code, join URL, and live participant list are always visible on the
left so the operator can leave the page on a projector.
- Student answer buttons are big and tappable; reveal screen highlights
correct/wrong choice + shows score, total, and rank.
- Static admin/student SPAs share a CSS palette with light/dark support.
Tests rewritten around the single canonical session id.
The auto-bootstrapped session lets each test fixture skip the old
quiz/session creation dance. 39/39 tests pass.
Cleanup:
- Deleted CODEX_PROMPT.md, IMPLEMENTATION_REPORT.md, NOTES.md, SPEC.md,
static/observer.html (obsolete codex-build artifacts and the unused
observer view).
- .gitignore now blocks /pool.json (the runtime file the operator drops
on the server) and the leftover .codex_done / codex_run.log / etc.
- bootstrap.sh seeds /opt/quiz/pool.json from examples/pool_example.json
on first deploy so a fresh box reaches a usable state without manual
intervention; .env now includes QUIZ_POOL_PATH.
Unconditional 'exec < /dev/tty' broke non-interactive SSH invocations
where /dev/tty isn't openable. Move the reattach into the env-prompt
branch and skip it cleanly if /root/.quiz.env was pre-populated, with
a clear error if both stdin and /root/.quiz.env are missing.
One-shot deploy for fresh Ubuntu 24.04 root SSH:
curl -fsSL https://gitea.ahkhan.me/apps/quiz/raw/branch/master/deploy/bootstrap.sh | bash
bootstrap.sh: idempotent stage-by-stage installer for Caddy, Python venv,
quiz system user, repo clone to /opt/quiz, env-var prompts, systemd unit,
Caddyfile, and a healthz check. Reattaches /dev/tty so curl|bash can read
the admin password interactively.
quiz.service: uvicorn under the quiz system user (no shell, no SSH),
ProtectSystem=full, ProtectHome=true, PrivateTmp=true, NoNewPrivileges=true.
Caddyfile.tpl: reverse_proxy 127.0.0.1:8001 with auto Let's Encrypt;
DOMAIN substituted at install time.
examples/pool_example.json: generic demo pool, schema reference only.
README rewritten around the deploy flow + class-day lifecycle.
Real pools contain answer keys; only the generic demo pool example is
allowed to be tracked. Also excludes the .codex_done / codex_run.log /
codex_last_message.md leftovers from the original codex build run.
The first-pass JSON-decode hardening exposed two latent bugs that the
fuzz scenario hits as soon as the WS handler stays alive past a bad
message:
1) `data.get("type")` is called on whatever `receive_json()` decodes,
but valid JSON can be a list/string/number, not just a dict. Reject
non-object payloads with a structured bad_message error before
dispatch.
2) `submit_answer` did `if answer not in {"A","B","C","D"}` which
raises TypeError when the client sends an unhashable answer
(e.g. a dict). Add an isinstance(str) guard so any non-string
answer falls into the bad_answer branch instead of crashing the
handler.
31/31 pytest still passes. Together with the prior commit, the WS
handlers now survive the full set of fuzz payloads without dropping
the connection.
A single malformed JSON message (or a "WebSocket is not connected" race
on disconnect) was killing the per-client handler with an uncaught
exception in the ASGI app. The surrounding try/except only caught
WebSocketDisconnect, so the server would log a stack trace and the
client would silently drop.
Wrap receive_json() to catch JSONDecodeError, send a structured
{"type":"error","code":"bad_message"} ack, and continue. Widen the
outer except to (WebSocketDisconnect, RuntimeError) so disconnect
races on send/receive after close exit the handler cleanly instead
of bubbling up the ASGI stack.
Both student_ws and instructor_ws hardened in parallel. 31/31 pytest
suite still passes; this fixes the recurring fuzz-scenario warn and
the cycle-187-style cascade observed in the stress loop.
Two suites under tests/stress/, plus a tmux-friendly run_loop.sh
runner. Both boot a fresh uvicorn on an isolated DB per cycle and
log JSON line summaries to runs/.
api_stress.mjs covers WS-level scenarios that the existing pytest
suite does not exercise: 20-student happy path, late joiners with
correct remaining_ms, mid-question disconnect, browser-sleep + wake
to a different question_idx, cookie tampering and cross-session
cookie reuse, duplicate student_id, bad submit (out-of-order, wrong
idx, resubmit no-op), close-boundary race with auto-close, malformed
JSON fuzz, and flaky reconnect.
ui_stress.mjs drives the same flows in a real Chromium context via
playwright: happy UI, sleep/wake by closing+reopening a context with
the persisted cookie, document.cookie tampering attempt, and two
browser contexts joining with the same student_id.
Findings will be summarised in runs/summary.jsonl over time. One known
issue surfaces from the fuzz scenario: app/room.py student_ws's
receive_json call propagates JSONDecodeError out of the only
try/except (which catches WebSocketDisconnect), killing that client's
WS handler. Other clients are unaffected.
