HSE Quiz Bowl Tracker

Getting Started

HSE QB Tracker is built for live quiz bowl scoring with instant Firebase sync across devices. Open the left sidebar and work through Setup → Settings → Session & Data:

1. Session – create a named match session
2. Players – add your roster, import CSV/TXT, fix typos with Rename/Merge
3. Teams – create teams and assign players (only assigned players appear when recording)
4. Categories – fixed parent + subcategories, plus admin controls for colors and expected frequencies
5. User ID / Visual – set display name, appearance, color theme, accent style

Once configured, use Record Answer to log toss-ups in real time. Everything auto-saves and syncs.

Accounts & Authentication

You can sign in, create an account, or Continue as guest. Guest accounts work offline but don’t sync across devices until upgraded.

• Email / Password – Firebase Auth secures your data
• Guest – local-only until you click Upgrade guest account in User ID
• Forgot password – resets via Firebase email
• Appearance on login – Light / Dark / Device toggle is available before sign-in and persists after

Sidebar Navigation

The sidebar is the control center.

• Jump menu – top pill shows current group (Setup / Settings / Session & Data). Click to jump to any section.
• Hide / Menu – desktop: collapses to a narrow bar; mobile/iPad portrait: becomes a drawer that blurs the main view. Tap outside or Hide to close.
• Collapsible sections – each h2 toggles its content. Your last active section is remembered.
• Active section – highlighted in the jump menu, auto-expanded when you jump.

Sessions

Each match is a Session with its own answer log, teams, toss-ups heard, and players.

• Create – enter name in Session → + New Session. Auto-loads the global player pool.
• Load modal – header Session: name + Load button opens the modal. Features:
  • Search by name or date
  • Sort: Newest, Oldest, A-Z, Most/Least Answers
  • Checkbox per session → bulk bar: Select all visible, count, + Add to Analytics / − Exclude, Delete
  • Per-session Analytics toggle (green ON / red OFF) – excluded sessions are dimmed, struck-through, ignored in all Stats calculations
  • Active badge on current session, Answers & Questions Heard summary
• Session info panel – Name, Created, Last Updated, Answers count.

Players

• Add Player – type name → Add Player or Enter. Stored globally in Firebase.
• Import from File – CSV/TXT, comma/semicolon/newline separated.
• Player pool display – pills with × to remove from current session (global pool stays unless removed via Firebase).
• Player Management – Rename and Merge tools:
  • Rename – fixes typos everywhere in this session (teams, answer log, player mirror) and updates global pool. Undo via toast.
  • Merge – click Merge on the player you want to remove; search/select target. All answers/points combined, teams updated, old name removed from global pool. Fuzzy matching helps: exact, case-insensitive, first-name, contains. Undo restores both players.

Teams

Create teams (e.g. Varsity A), then toggle players to assign. Only players assigned to a team appear as buttons when recording. Team cards show name input, member toggles, and Remove Team. Bonus answers are recorded for the team – see Recording.

Categories

• Fixed tree: parent categories (Literature, Science, History, etc.) with subcategories. You cannot add/remove categories – they are standardized for analytics.
• Display shows all parents and their subs as chips.
• Admin-only when you are admin:
  • Category Colors – pick colors per parent, used in charts. Save / Reset Defaults.
  • Expected Subcategory Frequencies – % of toss-ups each sub should appear at a typical tournament. Shown under subcategory doughnut charts and drives “Categories to Work On” in Overview.

Recording Answers

In Record Answer panel:

1. Select Player – grouped by team, display uses first name + last initial when duplicates exist. For Team Bonus you select a team pill instead (dashed, full-width). Miss and Dead can be unattributed.
2. Point Type – choose one (click or 1-6 keys):

   Type	Key	Color	Points	Notes
   Power ⚡︎	1	Gold	+15	Early correct buzz before power mark
   Toss-up	2	Green	+10	Correct after power
   Team Bonus	3	Blue	+10 per part	Team-scored, pick team pill. Never assigned to individual
   Miss	4	Grey	0	Incorrect after power or no answer – can be unattributed
   Neg	5	Red	−5	Incorrect early interrupt – category hidden/optional
   Dead	6	Dark Grey	0	No team buzzed – can be unattributed, category hidden

   Color coding: Power is gold, Toss-up is green, red for Negs, blue for Bonuses, grey for Misses, and dark grey for Dead. Charts, log entries, and buttons all use this palette, with light/dark variants for contrast.

3. Category – optional, hidden for Neg/Dead. Click parent label for general parent, or specific sub chip. Selected parent stored if no sub picked.
4. Toss-Ups Heard – auto-tracks: increments once on first outcome per toss-up. Logic: if previous log entry was Neg/Miss and current is Power/Toss-up, it’s treated as follow-up to same question (no increment). Manual +/− buttons to correct. Required for normalized metrics like TU/20 and Leaderboard Score.
5. Record Answer (Enter) – logs, shows colored toast (green success, red Neg, gray Miss/Dead), clears selection.

Answer Log below shows reverse chronological entries with player/team, type, points, category, Delete per entry, and Clear Log button. Deleting also adjusts Toss-Ups Heard if that entry was the first outcome of its question and removes team bonus points / player mirror.

Substitutions

Sub panel lists Active players (assigned to teams) and Bench (in session pool but not active). Pick one Sub Out chip and one Sub In chip – button shows “⇄ Out → In” when ready, otherwise disabled. Executes substitution across all teams (removes out, adds in). Toasts guide you if you miss a pick.

Tracker Statistics (current session)

Below Record Answer:

• Team cards – total points (including team bonuses), recorded events, avg per member, member list. Click header to collapse.
• Player cards – total toss-up points, decisions, toss-ups (with powered count), negs, misses. Click to collapse.
• Player Rankings – ordered list with rank suffix (1st, 2nd...), ties share rank. Shows points, powers, negs, misses.

Stats (Analytics View)

Toggle to Stats via header switch. Data aggregates across all non-excluded sessions. Four tabs – your active tab and scroll position are remembered:

• Overview – HSE Team Overview:
  • Team Totals pills: Active Players, Toss-ups Heard, Total Points, Recorded Events
  • Answer Breakdown: Toss-ups, ⚡︎ Powered, Bonuses (team), Points, Negs, Misses, Dead TUs – Total and Avg/Player
  • Performance Rates: Reliability, Power Rate, TU/20, Points/20 – Team vs Avg/Player, color-coded
  • Category Strengths – top 5 categories by points
  • Categories to Work On – subcategories where heard % < expected % (gap >0.5%), grouped by parent, sorted by gap, colored by severity
• Players – ranked leaderboard across sessions:
  • Summary bar: team average, auto k, ranked vs provisional counts, Configure → Data Management
  • Sort pills: Total Points, Leaderboard Score, Reliability, Power Rate, TU/20, A-Z
  • Player card: rank, name, sessions, correct, TU heard (+ delta if overridden), Leaderboard Score + TU/20, expand arrow. Expanded: chips for Correct/Powers/Negs/Misses, TU heard adjust −/+, metric tiles (Total Points, Leaderboard Score with raw & avg note, Reliability, Power Rate, TU/20, Confidence with small-sample warning), Top Categories by Decisions, bonus note.
  • Ranked vs Provisional: needs 20 TU heard (one full session) to earn Leaderboard Score and appear in distribution. Provisional still shows diagnostics.
  • Click name → Player Details modal (hero with name/points, stat chips, category table with rank badges gold/silver/bronze, mini bars, recent log)
  • Formula panel – collapsible, explains every metric
• Charts – visual analytics (Chart.js):
  • Answer Breakdown – Answer Type Breakdown doughnut (Power, Toss-up, Bonus, Neg, Miss, Dead)
  • Category Volume – doughnut of parent category volume
  • Categories – Category Answer Breakdown by Type stacked bar
  • Subcategory Breakdown – per-parent doughnut, same-height row, info panel below each: subcategory, Actual % vs Expected %, gap colored (red >3%, orange >1%, green <−1%).
  • Players – Total Points by Player bar, Player Answer Breakdown by Type stacked bar, Player Points by Category stacked bar (click segment to expand to subcategories with hatch patterns alternating direction, click again to collapse)
  • Overall Performance – Score Distribution histogram: bands of Leaderboard Score, bar height = % of ranked players in band. Solid line = current distribution, dashed = ideal bell (normal fit to ranked scores), gold vertical = team average. Click bar → Score Band modal listing players in that band in order. Note explains provisional exclusion.
• Team Compositions – unique lineups:
  • Search by team name, player, date. Filter by player count pills (Show All, 1 Player, 2 Players...).
  • Summary pill: X unique compositions across Y sessions
  • Card: left border color, team name + appearances badge, member list “A / B / C”, date • events, points + expand arrow. Expanded: stat chips (Points, Toss-ups, Bonuses, Powers, Negs, Misses, Accuracy), Capitalization (eBonus) = 100×10×bonuses / 30×(toss-ups+powers) and Point Control (eTotal) = 100×(15P+10T+10B−5N)/45×heard with bars colored by threshold (green ≥66%, orange ≥33%, red <33%)

Formula Symbols & Player Metrics

All formulas count official toss-up decisions only – bonuses excluded.

• P – Powers (+15)
• T – Toss-ups (+10)
• N – Negs (−5)
• M – Misses (0)
• H – Toss-Ups Heard – opportunities player was in room for (session counter accumulated across valid sessions, adjustable via override)
• k – confidence constant – auto-set to median H among ranked players; at H=k player is 50% trusted
• Team Average – mean Raw TU/20 of ranked players

Ranked vs provisional: ranked only when H ≥ 20. Provisional gets diagnostics but no Leaderboard Score, excluded from team average, k, and distribution chart.

Official Score System

Leaderboard Score is the only overall ranking score. Earned after 20 TU heard. Formula:

Leaderboard Score = Confidence × Raw TU/20 + (1 − Confidence) × Team Average

Bonuses are team-scored, shown in team totals and answer log, never in individual rankings.

Export & Import

• Export Data section (sidebar → Session & Data → Export / Import):
  • Toggles: Players & Scores, Answer Log, Team Statistics – select what to include
  • Export to Excel (CSV format currently) and Export as JSON (full session backup)
  • Import Session – select JSON file, status message, overwrite confirmation if name exists
• Data Management → Export All Data – exports all sessions at once as:
  • xlsx – workbook with Answer Log, Player Stats (per session), Session Summary sheets
  • csv – combined answer log across sessions
  • json – { exportedAt, sessions: [...] } full backup

User ID

Your Firebase identity.

• Avatar circle with initials, display name, subtitle
• Account meta: Signed in as (email), Account type (email / guest / anonymous), Firebase UID (code)
• Display name input – save to Firebase so teammates recognize you
• Buttons: Save display name, Clear name, Upgrade guest account (if guest), Sign out
• Sync status text for profile save/load

Visual Settings

Account settings – sync to Firebase and cache locally. Light/Dark independent of Color Theme. Text contrast has been improved (darker secondary text in light mode, lighter in dark mode) and titles are lightly tinted to your active theme color for better readability.

• Appearance – Light ☀, Dark ☾, Device ◑ (follows system). Stored as themeMode. Hint shows effective mode.
• Color Theme – 9 palettes: Tricolor (HSE blue/white/red default), Royal, Indigo, Teal, Crimson, Purple, Sunset, Slate, Forest. Each shows chip with 3-color preview. Plus Custom where you pick Primary, Gradient, Accent via color + hex inputs. Primary drives main UI, Gradient blends into headers/toggles, Accent controls outlines + highlighted text (auto-lifted for contrast in dark mode). Reset button.
• Accent Style – Pinstripe (clean banner gradient, pinstripes on surfaces, accent reserved for outlines/highlights) vs Gradient (classic primary→gradient blend). Both keep palette-tinted outlines.
• Interface – Hide scrollbars toggle (cleaner look, scrolling still works)
• Category Colors – admin-only, per-parent color pickers, Save/Reset
• Sync status

Admin Panel

Visible only to admins (UID-based, enforced by Firebase rules).

• Admin UIDs list – shows each admin with display name if known, UID mono, You / Legacy pills, Remove button. Empty state explains seeding.
• Add admin UID – paste Firebase UID, Add button. Find your UID in User ID section.
• Publish release notes – card linking to Updates modal (share new builds, write changelog, upload file)
• Build status – This file (display) + (internal), Published in Firebase (build + label), Published on GitHub

Data Management

Admin-only section with critical controls.

• Performance Score Settings – Global, synced:
  • Ranking requires full session: 20 TU heard to earn Leaderboard Score and appear in distribution
  • Automatic k = median TU heard among ranked players – typical ranked player 50% trusted, adapts as dataset grows
  • Official model: Leaderboard Score only overall ranking, Reliability/Power Rate/TU/20 diagnostics, bonuses team-scored excluded
• Expected Subcategory Frequencies – admin sets % per sub, used for expected vs actual in charts and Categories to Work On. Save/Reset.
• Danger Zone – collapsible red-bordered area:
  • Export All before deleting: buttons for Excel, CSV, JSON
  • Delete All Data – permanently deletes all sessions & data across every device, no undo. Requires admin password Neg 5 (second confirmation). Toast warns to export first.

Debug Menu

Admin-only, for testing without live data. Scenario select: Mid-game (~20q), Full game (~30q), Blowout (one team dominant). Inject Debug Data button populates current session with realistic placeholder players (Alex Carter, Jordan Lee...), teams (Alpha/Beta), answer log, Toss-Ups Heard, categories. Clear Session Data wipes session (confirm). Status text shows result.

Header, Updates, Shortcuts & Sync

• Header left – Menu button (hidden when sidebar open on desktop, always visible on mobile)
• Header center – Title (responsive short/medium/full), Session name, Version badge with deploy indicator border: green=success, yellow pulsing=pending, red=failed
• Header right – Tracker/Stats toggle switch (knob slides), Updates button ↻ with yellow “New” badge when remote build newer, Help ? button, Autosave indicator: ring spinner + dot – yellow connecting, dim idle, green flash on save, red error with tooltip
• Update banner – appears at top when new deploy succeeds while you have page open, with Refresh button
• Keyboard shortcuts (when not typing in input):
  • 1 Power, 2 Toss-up, 3 Bonus, 4 Miss, 5 Neg, 6 Dead
  • Enter Record Answer
  On touch devices kbd hints hidden, tap targets enlarged to ≥44px, no blue tap flash, long-press callout disabled, edge-scroll contained, safe-area insets respected.
• Toasts – bottom center: record toast (color-coded), app toast (warn/success/info with optional Undo), confirm toast (Cancel/Confirm), welcome toast (Open Help / Maybe Later, first visit)
• Modals – Help, Updates, Sessions, Player Action (Rename/Merge), Score Band (players in band), Player Details. Esc closes Updates. Click outside to close some.

What Syncs Globally

Firebase Realtime Database, instant across devices:

• All session data (answer logs, scores, toss-ups heard, teams, players per session)
• Global player pool
• Session invalid flags (analytics on/off), player Toss-Ups Heard overrides, manual inclusions
• Category colors, expected subcategory frequencies (admin)
• Admin UIDs list, app version, release history, global settings (skill threshold, etc.)

Per-account (Firebase user profile + localStorage cache): theme mode, color theme or custom colors, accent style, hide scrollbars, sidebar collapsed, active sidebar section, analytics open/tab/scroll, low-data/formulas panel collapsed, welcome dismissed, loading source.

Updates & Changelog

Open Updates in the header to see the release summary and history. HSE source is split into modules for development, but index.html is the one self-contained runtime artifact; users do not need the src folder. For school devices, the Download button reads the verified matching index.html from Firebase first and saves a versioned file such as hse-quiz-bowl-tracker-v3.12.1.html. GitHub is only a legacy fallback. Admins should attach the exact built index.html when publishing; the app refuses a file whose embedded version does not match the release being published. If a file was already downloaded, the Updates card says “Download again” so users do not mistake duplicate downloads for new builds.

Source Code on GitHub

Open source – browse code, release history, report bugs.

Repository: github.com/ajani190819-ops/HSEQB

Loading source: —