feat(realtime): live updates across the site — the activity room

[tbcsec]

Fixes #18

What

One new mechanism instead of five bespoke fixes: a per-competition activity/<competition_id> WebSocket room that fans out tiny event-name pings, and a frontend map from event names → TanStack Query invalidations. Every surface the issue names now updates live:

• Dashboard widgets — stats tiles, recent activity, challenge health, your standing/solves
• Challenge cards — solve counts, dynamic point values, the dialog's solver list
• Participants / teams roster — joins, standings, overtakes
• Support — thread replies now bump the staff queue; a competitor's ticket list refreshes when staff reply/resolve (rides their existing notification frames — no new socket)
• Analytics — attempts, solves, completion rates

Bonus liveness for free (one map line each): the pause banner appears live (competition.updated), module toggles re-gate the nav live, and category/hint/vocab edits propagate.

Design

• Ping → refetch, not snapshot-push. These surfaces are all per-user filtered (solved state, locks, MC attempts, role-scoped stats), so a shared snapshot can't exist. Frames carry the event name + ids only, never bodies — nothing can leak, because the refetch is permission-filtered server-side. §4.1 now documents the two room idioms (snapshot vs ping).
• One shell-level socket (mounted beside the notification bell), authorized like the scoreboard room (challenge_view), broadcast skipped when nobody's watching. invalidateQueries only refetches mounted queries, so background pages are marked stale and fetch fresh on navigation.
• Curated allowlists on both ends: the backend fans out an explicit event list (ticket.*/announcement.* excluded — they have tighter-scoped rooms; user.*/role.* are global-admin domains); the frontend map treats unmapped events as a no-op.
• Per-key leading+trailing throttle (2.5s) in lib/live.ts: a lone event lands instantly, a burst collapses to at most one refetch per key per window, the last event is never lost.

New §3.2 event: challenge.attempted (owner-approved)

Every graded submission, right or wrong — the event half of §13.2's "every attempt is logged". Wrong guesses previously emitted nothing, so attempt counters could not go live. Automation trigger gated view_competition_analytics (others' attempts are staff analytics data); volume bounded by the submission rate limit. Deliberately not wired to the challenge-list refetch (heaviest query, most frequent event).

Tests

• Backend 391 passed (+6): room auth (member/outsider/bogus id), wrong submit → attempted ping, correct submit → attempted then solved, ticket events don't reach the room, team-created ping, thread-reply → support bump, notification frame carries competition_id.
• Frontend 109 passed (+11): map coverage incl. the layout-key exclusion, throttle timing (leading/trailing/steady-state/dispose) under fake timers. tsc + eslint clean.

Live verification (demo backend + simulator)

Logged in as admin with the simulator generating traffic — no reloads anywhere:

• Dashboard tiles climbed 16→20 solves / 23→29 submissions in 30s; recent-activity feed streamed.
• Challenge cards: page-wide solve total read exactly 31 when the DB held 31.
• Analytics: attempts 52→63, solves 36→47 in place.
• Roster: a bot overtook rank 2 in place.
• API-pausing the competition surfaced the paused banner on the challenges page within the throttle window.
• One activity socket total, no reconnect churn, zero console errors.

🤖 Generated with Claude Code