feat: add Jackbox API Logger CLI tool

Standalone tool that connects to a Jackbox room by code, captures all
websocket events, and logs summarized output to console + full JSON to
a JSONL file. Consolidates scattered scripts/ws-probe.js,
ws-lifecycle-test.js, and get-jackbox-player-count.js into one
cohesive debugging tool.

Co-authored-by: Cursor <cursoragent@cursor.com>

.gitea/issue_template/bug-report.yaml

@@ -0,0 +1,102 @@
+name: Bug Report
+about: Something is broken or behaving unexpectedly
+title: "[Bug] "
+labels:
+  - bug
+body:
+  - type: dropdown
+    id: area
+    attributes:
+      label: Affected Area
+      description: Which part of the application is affected?
+      options:
+        - Game Picker (selection, filters, weighting)
+        - Game Manager (CRUD, import/export, packs)
+        - Session Management (create, close, archive, notes)
+        - History / Session Detail (display, pagination, filters)
+        - Room Code / Player Count (ecast, monitoring)
+        - Chat Log Import / Voting
+        - Webhooks
+        - Authentication / Admin
+        - WebSocket / Real-time / Presence
+        - PWA (install, offline, service worker)
+        - UI / Styling / Responsiveness
+        - API (backend endpoint)
+        - Database / Migrations
+        - Docker / Deployment
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: deploy-method
+    attributes:
+      label: Deployment Method
+      options:
+        - Docker (docker-compose)
+        - Local development (npm run dev)
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Concise summary of what's wrong.
+      placeholder: "When I do X, Y happens instead of Z."
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: Minimal sequence to trigger the bug.
+      placeholder: |
+        1. Login as admin
+        2. Navigate to Picker page
+        3. Set player count filter to 3
+        4. Click "Roll the Dice"
+        5. Observe error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      placeholder: A game matching the filters should be selected.
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      placeholder: The page shows a spinner indefinitely and the console logs a 500 error.
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant Logs / Errors
+      description: Paste browser console errors, backend logs (`docker-compose logs backend`), or network responses. Wrap sensitive data.
+      render: shell
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Browser, OS, Node version, Docker version — whatever is relevant.
+      placeholder: |
+        Browser: Firefox 128
+        OS: macOS 15.3
+        Docker: 27.x / Compose v2.x
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Screenshots, related issues, workarounds tried, etc.

.gitea/issue_template/config.yaml

@@ -0,0 +1 @@
+blank_issues_enabled: true

.gitea/issue_template/feature-request.yaml

@@ -0,0 +1,87 @@
+name: Feature Request
+about: Suggest a new feature or improvement to an existing one
+title: "[Feature] "
+labels:
+  - enhancement
+body:
+  - type: dropdown
+    id: type
+    attributes:
+      label: Request Type
+      options:
+        - New feature
+        - Enhancement to existing feature
+        - UX / UI improvement
+        - API addition or change
+        - Developer experience / tooling
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Affected Area
+      description: Which part of the application does this relate to?
+      multiple: true
+      options:
+        - Game Picker
+        - Game Manager
+        - Session Management
+        - History / Session Detail
+        - Room Code / Player Count
+        - Chat Log Import / Voting
+        - Webhooks
+        - Authentication / Admin
+        - WebSocket / Real-time / Presence
+        - PWA
+        - UI / Styling
+        - API (backend)
+        - Database
+        - Docker / Deployment
+        - Documentation
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / Motivation
+      description: What problem does this solve, or what use case does it enable?
+      placeholder: "During a stream, I need to X but currently have to Y which is slow because Z."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: Describe what you'd like to happen. Be specific about behavior, UI, or API shape if you have ideas.
+      placeholder: |
+        Add a "favorites" toggle on each game card in the Manager.
+        Favorited games appear at the top of the picker pool.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Other approaches you thought about and why they're less ideal.
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: How important is this to you?
+      options:
+        - Nice to have
+        - Would improve my workflow noticeably
+        - Blocking a use case I need
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Mockups, screenshots, links to related issues, etc.

.gitignore

@@ -21,6 +21,7 @@ frontend/public/manifest.json
 # Logs
 *.log
 npm-debug.log*
+logs/
 
 # OS files
 .DS_Store
@@ -44,6 +45,7 @@ backend/config/admins.json
 
 # Cursor
 .cursor/
+.superpowers/
 chat-summaries/
 plan.md
 

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cottongin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,6 +1,9 @@
+> [!IMPORTANT]  
+> This project was developed entirely with AI coding assistance (Claude Opus 4.6 via Cursor IDE) and has not undergone rigorous review. It is provided as-is and may require adjustments for other environments.
+
 # Jackbox Party Pack Game Picker
 
-A full-stack web application that helps groups pick games to play from various Jackbox Party Packs. Features include random game selection with filters, session tracking, game management, and popularity scoring through chat log imports.
+A full-stack web application that helps groups pick games to play from various Jackbox Party Packs. Features include random game selection with weighted filters, session tracking, game management, popularity scoring through chat log imports and live voting, and Jackbox lobby integration.
 
 ## Features
 
@@ -13,26 +16,37 @@ A full-stack web application that helps groups pick games to play from various J
 ### Admin Features
 - **Game Picker**: Randomly select games with intelligent filters
   - Filter by player count, drawing games, game length, and family-friendly status
+  - Weighted random selection using game and pack favor bias
   - Automatic repeat avoidance (prevents same game or alternating pattern)
   - Manual game selection option
   - Real-time session tracking
 
 - **Game Manager**: Complete CRUD operations for games and packs
   - Enable/disable individual games or entire packs
+  - Set favor bias on games and packs to influence pick weighting
   - Import/export games via CSV
-  - View statistics (play counts, popularity scores)
+  - View statistics (play counts, upvotes, downvotes, popularity scores)
   - Add, edit, and delete games
 
 - **Session Management**: Track gaming sessions over time
   - Create and close sessions
-  - View session history
-  - Import chat logs to calculate game popularity
-  - Track which games were played when
+  - View session history with pagination and filters
+  - Archive/unarchive sessions
+  - Add, edit, and delete session notes (hidden from unauthenticated users)
+  - Export session data
+  - Bulk session creation
+  - Per-session game management (add, remove, reorder, set status)
+
+- **Room Code & Player Count**: Live Jackbox lobby integration
+  - Set room codes on session games
+  - Automatic player count fetching via Jackbox ecast shard API
+  - Start/stop player count monitoring
+  - Live status updates via WebSocket
 
 - **Chat Log Import**: Process chat messages to assess game popularity
   - Supports "thisgame++" and "thisgame--" voting
   - Automatically matches votes to games based on timestamps
-  - Updates popularity scores across sessions
+  - Updates upvote/downvote counts across sessions
 
 - **Live Voting API**: Real-time vote processing from external bots
   - Accept live votes via REST API
@@ -50,16 +64,18 @@ A full-stack web application that helps groups pick games to play from various J
 
 ### Public Features
 - View active session and games currently being played
-- Browse session history
+- Browse session history (with archived sessions hidden by default)
+- Detailed session view with game list and vote breakdowns
 - See game statistics and popularity
 
 ## Tech Stack
 
-- **Frontend**: React 18 with Vite, Tailwind CSS, React Router
-- **Backend**: Node.js with Express
+- **Frontend**: React 18 with Vite, Tailwind CSS, React Router 6
+- **Backend**: Node.js with Express 4
 - **Database**: SQLite with better-sqlite3
+- **Real-time**: WebSocket server (`ws`) for presence, subscriptions, and live events
 - **Authentication**: JWT-based admin authentication
-- **Deployment**: Docker with docker-compose
+- **Deployment**: Docker with docker-compose (Node 22 Alpine + nginx Alpine)
 
 ## Prerequisites
 
@@ -78,13 +94,12 @@ A full-stack web application that helps groups pick games to play from various J
    
    Create a `.env` file in the root directory:
    ```env
-   PORT=5000
-   NODE_ENV=production
-   DB_PATH=/app/data/jackbox.db
    JWT_SECRET=your-secret-jwt-key-change-this
    ADMIN_KEY=your-admin-key-here
    ```
    
+   `JWT_SECRET` is required. Provide either `ADMIN_KEY` (single admin) or configure named admins (see [Named Admins](#named-admins) below).
+
 3. **Build and start the containers**
    ```bash
    docker-compose up -d
@@ -96,7 +111,7 @@ A full-stack web application that helps groups pick games to play from various J
 
 5. **Login as admin**
    - Navigate to the login page
-   - Enter your `ADMIN_KEY` from the `.env` file
+   - Enter your `ADMIN_KEY` (or a named admin key) from your configuration
 
 The database will be automatically initialized and populated with games from `games-list.csv` on first run.
 
@@ -148,10 +163,32 @@ The backend will run on http://localhost:5000
    npm run dev
    ```
 
-The frontend will run on http://localhost:3000 and proxy API requests to the backend.
+The frontend will run on http://localhost:3000. Note: the Vite dev proxy is configured to forward `/api` requests to `http://backend:5000` (the Docker Compose service name). For bare-metal local development without Docker, you may need to update the proxy target in `vite.config.js` to `http://localhost:5000`.
 
 ## Configuration
 
+### Named Admins
+
+The app supports multiple named admin accounts. Create `backend/config/admins.json` (see `admins.example.json` for the format):
+
+```json
+[
+  { "name": "Alice", "key": "change-me-alice-key" },
+  { "name": "Bob", "key": "change-me-bob-key" }
+]
+```
+
+Each admin logs in with their unique key. Their name is embedded in the JWT and displayed in the presence bar.
+
+If `admins.json` is not found, the app falls back to the `ADMIN_KEY` environment variable as a single admin named "Admin".
+
+To use a custom path for the admins file, set `ADMIN_CONFIG_PATH` in your environment.
+
+For Docker, uncomment the volume mount in `docker-compose.yml`:
+```yaml
+- ./backend/config/admins.json:/app/config/admins.json:ro
+```
+
 ### Branding and Metadata
 
 All app branding, metadata, and PWA configuration is centralized in `frontend/src/config/branding.js`. Edit this file to customize:
@@ -176,7 +213,32 @@ cd frontend
 npm run generate-manifest
 ```
 
-The manifest is automatically generated during the build process, so you don't need to edit it directly.
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `JWT_SECRET` | Yes | — | Secret key for signing JWT tokens |
+| `ADMIN_KEY` | No | — | Single admin authentication key (fallback when `admins.json` is absent) |
+| `ADMIN_CONFIG_PATH` | No | `backend/config/admins.json` | Path to named admins JSON file |
+| `PORT` | No | `5000` | Backend server port |
+| `NODE_ENV` | No | `development` | Environment (production/development) |
+| `DB_PATH` | No | `./data/jackbox.db` | Path to SQLite database file |
+| `DEBUG` | No | `false` | Enable debug logging |
+
+## Testing
+
+The project uses Jest for API and integration tests. Tests live in the `tests/` directory at the repository root.
+
+```bash
+# Install backend dependencies first
+cd backend && npm install && cd ..
+
+# Run tests
+npx jest
+
+# Run tests in watch mode
+npx jest --watch
+```
 
 ## Project Structure
 
@@ -185,19 +247,28 @@ The manifest is automatically generated during the build process, so you don't n
 ├── backend/
 │   ├── routes/              # API route handlers
 │   │   ├── auth.js          # Authentication endpoints
-│   │   ├── games.js      # Game CRUD and management
-│   │   ├── sessions.js   # Session management
+│   │   ├── games.js         # Game CRUD, packs, favor bias
+│   │   ├── sessions.js      # Sessions, archives, notes, room codes, export
 │   │   ├── picker.js        # Game picker algorithm
 │   │   ├── stats.js         # Statistics endpoints
 │   │   ├── votes.js         # Live voting endpoint
 │   │   └── webhooks.js      # Webhook management
 │   ├── middleware/           # Express middleware
-│   │   └── auth.js       # JWT authentication
-│   ├── utils/            # Utility functions
-│   │   └── webhooks.js   # Webhook trigger and signature
-│   ├── database.js       # SQLite database setup
-│   ├── bootstrap.js      # Database initialization
-│   ├── server.js         # Express app entry point
+│   │   ├── auth.js          # JWT authentication (required)
+│   │   └── optional-auth.js # JWT authentication (optional, for public routes)
+│   ├── config/              # Configuration files
+│   │   ├── admins.example.json  # Example named admins config
+│   │   ├── admins.json          # Named admins (gitignored)
+│   │   └── load-admins.js       # Admin config loader
+│   ├── utils/               # Utility modules
+│   │   ├── websocket-manager.js  # WebSocket server (presence, events)
+│   │   ├── ecast-shard-client.js # Jackbox ecast shard integration
+│   │   ├── jackbox-api.js        # Jackbox API helpers
+│   │   ├── notes-preview.js      # Session notes preview generation
+│   │   └── webhooks.js           # Webhook trigger and HMAC signatures
+│   ├── database.js          # SQLite database setup and migrations
+│   ├── bootstrap.js         # Database initialization from CSV
+│   ├── server.js            # Express + WebSocket entry point
 │   ├── package.json
 │   └── Dockerfile
 ├── frontend/
@@ -207,9 +278,25 @@ The manifest is automatically generated during the build process, so you don't n
 │   │   │   ├── Login.jsx
 │   │   │   ├── Picker.jsx
 │   │   │   ├── Manager.jsx
-│   │   │   └── History.jsx
+│   │   │   ├── History.jsx
+│   │   │   └── SessionDetail.jsx
+│   │   ├── components/      # Reusable UI components
+│   │   │   ├── PresenceBar.jsx
+│   │   │   ├── Toast.jsx
+│   │   │   ├── ThemeToggle.jsx
+│   │   │   ├── Logo.jsx
+│   │   │   ├── RoomCodeModal.jsx
+│   │   │   ├── GamePoolModal.jsx
+│   │   │   ├── PopularityBadge.jsx
+│   │   │   ├── InstallPrompt.jsx
+│   │   │   └── SafariInstallPrompt.jsx
 │   │   ├── context/         # React context providers
-│   │   │   └── AuthContext.jsx
+│   │   │   ├── AuthContext.jsx
+│   │   │   └── ThemeContext.jsx
+│   │   ├── hooks/           # Custom React hooks
+│   │   │   └── usePresence.js
+│   │   ├── config/          # Frontend configuration
+│   │   │   └── branding.js
 │   │   ├── api/             # API client
 │   │   │   └── axios.js
 │   │   ├── App.jsx
@@ -219,44 +306,74 @@ The manifest is automatically generated during the build process, so you don't n
 │   ├── vite.config.js
 │   ├── tailwind.config.js
 │   ├── package.json
-│   ├── nginx.conf        # Nginx config for Docker
+│   ├── nginx.conf           # Nginx config for Docker (proxy + SPA)
 │   └── Dockerfile
+├── tests/                   # Jest API and integration tests
+│   ├── api/                 # Route-level tests
+│   ├── helpers/             # Test utilities
+│   └── jest.setup.js
+├── scripts/                 # Jackbox lobby inspection utilities
+├── docs/                    # API documentation, design specs, plans
+│   ├── api/                 # OpenAPI spec, endpoint docs, guides
+│   ├── plans/               # Implementation plans
+│   └── archive/             # Archived docs
 ├── docker-compose.yml
-├── games-list.csv        # Initial game data
+├── jest.config.js
+├── games-list.csv           # Initial game seed data
 └── README.md
 ```
 
 ## API Endpoints
 
+### Health
+- `GET /health` - Health check (returns `{ status: "ok" }`)
+
 ### Authentication
-- `POST /api/auth/login` - Login with admin key
+- `POST /api/auth/login` - Login with admin key (returns JWT with admin name)
 - `POST /api/auth/verify` - Verify JWT token
 
 ### Games
 - `GET /api/games` - List all games (with filters)
+- `GET /api/games/packs` - List unique pack names
+- `GET /api/games/meta/packs` - Get pack list with stats and favor bias
 - `GET /api/games/:id` - Get single game
 - `POST /api/games` - Create game (admin)
 - `PUT /api/games/:id` - Update game (admin)
 - `DELETE /api/games/:id` - Delete game (admin)
 - `PATCH /api/games/:id/toggle` - Toggle game enabled status (admin)
-- `GET /api/games/meta/packs` - Get pack list with stats
+- `PATCH /api/games/:id/favor` - Set game favor bias (admin)
 - `PATCH /api/games/packs/:name/toggle` - Toggle entire pack (admin)
+- `PATCH /api/games/packs/:name/favor` - Set pack favor bias (admin)
 - `GET /api/games/export/csv` - Export games to CSV (admin)
 - `POST /api/games/import/csv` - Import games from CSV (admin)
 
 ### Sessions
-- `GET /api/sessions` - List all sessions
+- `GET /api/sessions` - List sessions (paginated, filterable, `X-Total-Count` header)
 - `GET /api/sessions/active` - Get active session
-- `GET /api/sessions/:id` - Get single session
+- `GET /api/sessions/:id` - Get single session (notes hidden from unauthenticated users)
 - `POST /api/sessions` - Create new session (admin)
+- `POST /api/sessions/bulk` - Bulk create sessions (admin)
 - `POST /api/sessions/:id/close` - Close session (admin)
+- `DELETE /api/sessions/:id` - Delete session (admin)
+- `PUT /api/sessions/:id/notes` - Update session notes (admin)
+- `DELETE /api/sessions/:id/notes` - Delete session notes (admin)
+- `POST /api/sessions/:id/archive` - Archive session (admin)
+- `POST /api/sessions/:id/unarchive` - Unarchive session (admin)
 - `GET /api/sessions/:id/games` - Get games in session
-- `GET /api/sessions/:id/votes` - Get per-game vote breakdown for a session
 - `POST /api/sessions/:id/games` - Add game to session (admin)
+- `PATCH /api/sessions/:sessionId/games/:gameId/status` - Update game status (admin)
+- `DELETE /api/sessions/:sessionId/games/:gameId` - Remove game from session (admin)
+- `PATCH /api/sessions/:sessionId/games/:gameId/room-code` - Set room code (admin)
+- `PATCH /api/sessions/:sessionId/games/:gameId/player-count` - Update player count (admin)
+- `GET /api/sessions/:sessionId/games/:gameId/status-live` - Get live ecast status
+- `POST /api/sessions/:sessionId/games/:gameId/start-player-check` - Start player count monitoring (admin)
+- `POST /api/sessions/:sessionId/games/:gameId/stop-player-check` - Stop player count monitoring (admin)
+- `GET /api/sessions/:id/votes` - Get per-game vote breakdown for a session
 - `POST /api/sessions/:id/chat-import` - Import chat log (admin)
+- `GET /api/sessions/:id/export` - Export session data (admin)
 
 ### Game Picker
-- `POST /api/pick` - Pick random game with filters
+- `POST /api/pick` - Pick random game with filters and favor bias weighting
 
 ### Statistics
 - `GET /api/stats` - Get overall statistics
@@ -274,6 +391,9 @@ The manifest is automatically generated during the build process, so you don't n
 - `POST /api/webhooks/test/:id` - Test webhook (admin)
 - `GET /api/webhooks/:id/logs` - Get webhook logs (admin)
 
+### WebSocket
+- `ws://host/api/sessions/live` - Real-time connection for presence, session subscriptions, and live events
+
 ## Usage Guide
 
 ### Starting a Game Session
@@ -294,9 +414,10 @@ The manifest is automatically generated during the build process, so you don't n
 2. Navigate to the Manager page
 3. View statistics and pack information
 4. Toggle individual games or entire packs on/off
-5. Add new games with the "+ Add Game" button
-6. Edit or delete existing games
-7. Import/Export games via CSV
+5. Adjust favor bias to weight certain games or packs in the picker
+6. Add new games with the "+ Add Game" button
+7. Edit or delete existing games
+8. Import/Export games via CSV
 
 ### Closing a Session and Importing Chat Logs
 
@@ -322,6 +443,10 @@ The manifest is automatically generated during the build process, so you don't n
 6. Click "Close Session" to finalize
 7. Add optional notes about the session
 
+### Archiving Sessions
+
+Closed sessions can be archived to keep the history page clean. Archived sessions are hidden by default but can be viewed by toggling the archive filter. Archiving and unarchiving are available from the session detail page or via bulk actions in the history list.
+
 ## Chat Log Format
 
 The chat import feature expects a JSON array where each message has:
@@ -332,12 +457,12 @@ The chat import feature expects a JSON array where each message has:
 The system will:
 1. Parse each message for vote patterns
 2. Match the timestamp to the game being played at that time
-3. Update the game's popularity score (+1 for ++, -1 for --)
+3. Update the game's upvote/downvote counts (+1 for ++, -1 for --)
 4. Store the chat log in the database
 
 ## Bot Integration
 
-For integrating external bots (e.g., for live voting and game notifications), see **[BOT_INTEGRATION.md](docs/BOT_INTEGRATION.md)** for detailed documentation including:
+For integrating external bots (e.g., for live voting and game notifications), see **[BOT_INTEGRATION.md](docs/archive/BOT_INTEGRATION.md)** for detailed documentation including:
 
 - Live voting API usage
 - **WebSocket integration (recommended)** for real-time game notifications
@@ -374,10 +499,10 @@ go run get-player-count.go JYET
 - Extracts actual player count from lobby state
 
 These tools retrieve:
-- ✅ Actual player count (not just max capacity)
-- ✅ List of current players and their roles (host/player)
-- ✅ Game state and lobby status  
-- ✅ Audience count
+- Actual player count (not just max capacity)
+- List of current players and their roles (host/player)
+- Game state and lobby status  
+- Audience count
 
 **Note:** Direct WebSocket connection is not possible without authentication, so the tools join through jackbox.tv to capture the data.
 
@@ -386,13 +511,17 @@ These tools retrieve:
 ### games
 - id, pack_name, title, min_players, max_players, length_minutes
 - has_audience, family_friendly, game_type, secondary_type
-- play_count, popularity_score, upvotes, downvotes, enabled, created_at
+- play_count, popularity_score, upvotes, downvotes, favor_bias, enabled, created_at
+
+### packs
+- id, name (unique), favor_bias, created_at
 
 ### sessions
-- id, created_at, closed_at, is_active, notes
+- id, created_at, closed_at, is_active, notes, archived
 
 ### session_games
 - id, session_id, game_id, played_at, manually_added, status
+- room_code, player_count, player_count_check_status
 
 ### chat_logs
 - id, session_id, chatter_name, message, timestamp, parsed_vote, message_hash
@@ -422,8 +551,10 @@ The picker uses the following logic:
    - Exclude those games from selection pool
    - This prevents immediate repeats and alternating patterns
 
-3. **Random selection**:
-   - Pick a random game from remaining eligible games
+3. **Weighted random selection**:
+   - Games and packs can have a `favor_bias` (+/- integer)
+   - Positive bias increases pick probability; negative bias decreases it
+   - Pick a random game from remaining eligible games, weighted by bias
    - Return game details and pool size
 
 ## Docker Deployment
@@ -446,36 +577,28 @@ docker-compose down
 docker-compose up -d --build
 ```
 
-### Environment Variables
-
-Set these in your `.env` file or docker-compose environment:
-
-- `PORT` - Backend server port (default: 5000)
-- `NODE_ENV` - Environment (production/development)
-- `DB_PATH` - Path to SQLite database file
-- `JWT_SECRET` - Secret key for JWT tokens
-- `ADMIN_KEY` - Admin authentication key
-
 ### Data Persistence
 
-The SQLite database is stored in `backend/data/` and is persisted via Docker volumes. To backup your data, copy the `backend/data/` directory.
+The SQLite database is stored in a named Docker volume (`jackbox-data`) mapped to `/app/data` in the backend container. To backup your data, use `docker cp` or bind-mount a host directory.
 
 ## Troubleshooting
 
 ### Database not initializing
 - Ensure `games-list.csv` is in the root directory
 - Check backend logs: `docker-compose logs backend`
-- Manually delete `backend/data/jackbox.db` to force re-initialization
+- Manually delete the database to force re-initialization
 
 ### Can't login as admin
-- Verify your `ADMIN_KEY` environment variable is set
+- Verify your `ADMIN_KEY` or `admins.json` is configured correctly
 - Check that the `.env` file is loaded correctly
+- If using named admins, ensure `admins.json` has valid JSON with unique names and keys
 - Try restarting the backend service
 
 ### Frontend can't reach backend
 - Verify both containers are running: `docker-compose ps`
 - Check network connectivity: `docker-compose logs frontend`
 - Ensure nginx.conf proxy settings are correct
+- For local dev, confirm the Vite proxy target matches your backend URL
 
 ### Games not showing up
 - Check if games are enabled in the Manager
@@ -489,4 +612,3 @@ MIT
 ## Contributing
 
 Feel free to submit issues and pull requests!
-

backend/.dockerignore

@@ -0,0 +1,13 @@
+node_modules
+npm-debug.log
+.env
+.env.local
+*.db
+*.sqlite
+*.sqlite3
+data/
+.git
+.gitignore
+README.md
+config/admins.json
+

backend/bootstrap.js

@@ -54,6 +54,33 @@ function bootstrapGames() {
   console.log(`Successfully imported ${records.length} games from CSV`);
 }
 
+function bootstrapTickers() {
+  const tickersPath = path.join(__dirname, 'config', 'tickers.json');
+
+  if (!fs.existsSync(tickersPath)) {
+    console.log('tickers.json not found. Skipping ticker bootstrap.');
+    return;
+  }
+
+  const tickers = JSON.parse(fs.readFileSync(tickersPath, 'utf-8'));
+
+  const update = db.prepare('UPDATE games SET ticker = ? WHERE title = ? AND (ticker IS NULL OR ticker != ?)');
+
+  const updateMany = db.transaction((entries) => {
+    let updated = 0;
+    for (const [symbol, title] of entries) {
+      const result = update.run(symbol, title, symbol);
+      updated += result.changes;
+    }
+    return updated;
+  });
+
+  const updated = updateMany(Object.entries(tickers));
+  if (updated > 0) {
+    console.log(`Updated ticker symbols for ${updated} games`);
+  }
+}
+
 function parseLengthMinutes(lengthStr) {
   if (!lengthStr || lengthStr === '????' || lengthStr === '?') {
     return null;
@@ -69,5 +96,5 @@ function parseBoolean(value) {
   return value.toLowerCase() === 'yes' ? 1 : 0;
 }
 
-module.exports = { bootstrapGames };
+module.exports = { bootstrapGames, bootstrapTickers };
 

backend/config/admins.example.json

@@ -1,4 +1,5 @@
 [
-  { "name": "Alice", "key": "change-me-alice-key" },
-  { "name": "Bob", "key": "change-me-bob-key" }
+  { "name": "Alice", "role": "admin", "key": "change-me-alice-key" },
+  { "name": "Bob", "role": "bot", "key": "change-me-bob-key" },
+  { "name": "Charlie", "role": "utility", "key": "change-me-charlie-key" }
 ]

backend/config/load-admins.js

@@ -3,10 +3,19 @@ const path = require('path');
 
 const DEFAULT_CONFIG_PATH = path.join(__dirname, 'admins.json');
 
+function canRead(filePath) {
+  try {
+    fs.accessSync(filePath, fs.constants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function loadAdmins() {
   const configPath = process.env.ADMIN_CONFIG_PATH || DEFAULT_CONFIG_PATH;
 
-  if (fs.existsSync(configPath)) {
+  if (canRead(configPath)) {
     const raw = fs.readFileSync(configPath, 'utf-8');
     const admins = JSON.parse(raw);
 
@@ -35,6 +44,10 @@ function loadAdmins() {
     return admins;
   }
 
+  if (fs.existsSync(configPath) && !canRead(configPath)) {
+    console.warn(`[Auth] Config file exists at ${configPath} but is not readable, skipping`);
+  }
+
   if (process.env.ADMIN_KEY) {
     console.log('[Auth] No admins config file found, falling back to ADMIN_KEY env var');
     return [{ name: 'Admin', key: process.env.ADMIN_KEY }];
@@ -49,7 +62,7 @@ const admins = loadAdmins();
 
 function findAdminByKey(key) {
   const match = admins.find(a => a.key === key);
-  return match ? { name: match.name } : null;
+  return match ? { name: match.name, role: match.role || 'admin' } : null;
 }
 
 module.exports = { findAdminByKey, admins };

backend/config/tickers.json

@@ -0,0 +1,60 @@
+{
+  "QPL3": "Quiplash 3",
+  "QPL2": "Quiplash 2",
+  "QLXL": "Quiplash XL",
+  "FBXL": "Fibbage XL",
+  "FBG2": "Fibbage 2",
+  "FBG3": "Fibbage 3",
+  "FBG4": "Fibbage 4",
+  "TMP1": "Trivia Murder Party",
+  "TMP2": "Trivia Murder Party 2",
+  "DRWF": "Drawful",
+  "DRWA": "Drawful Animate",
+  "DD": "Dirty Drawful",
+  "DOOM": "Doominate",
+  "JJ": "Job Job",
+  "TKO2": "Tee K.O. 2",
+  "TKOX": "Tee K.O. T-Shirt Knock Out",
+  "CU": "Champ'd Up",
+  "BR": "Blather 'Round",
+  "STR": "Split the Room",
+  "ROOM": "Roomerang",
+  "BRKT": "Bracketeering",
+  "NNSR": "Nonsensory",
+  "QXRT": "Quixort",
+  "JNKT": "Junktopia",
+  "TP": "Talking Points",
+  "PS": "Patently Stupid",
+  "PTB": "Push the Button",
+  "WD": "Weapons Drawn",
+  "HPNT": "Hypnotorious",
+  "DCTN": "Dictionarium",
+  "RM": "Role Models",
+  "JB": "Joke Boat",
+  "GSPN": "Guesspionage",
+  "MVC": "Mad Verse City",
+  "HRSY": "Hear Say",
+  "CH": "Cookie Haus",
+  "SPCT": "Suspectives",
+  "LOT": "Legends of Trivia",
+  "STI": "Survive the Internet",
+  "CVDL": "Civic Doodle",
+  "MSM": "Monster Seeking Monster",
+  "TPM": "The Poll Mine",
+  "TWEP": "The Wheel of Enormous Proportions",
+  "TJ": "Time Jinx",
+  "DRM": "Dodo Re Mi",
+  "FT": "Fixy Text",
+  "SS": "Survey Scramble",
+  "WS": "Word Spud",
+  "LS": "Lie Swatter",
+  "FI": "Fakin' It!",
+  "FANL": "Fakin' It All Night Long",
+  "LMF": "Let Me Finish",
+  "BDTS": "Bidiots",
+  "BC": "Bomb Corp.",
+  "YDK1": "You Don't Know Jack\u00ae 2015",
+  "YDKJ": "You Don't Know Jack\u00ae Full Stream",
+  "ZPDM": "Zeeple Dome",
+  "EW": "Earwax\u2122"
+}

backend/database.js

@@ -125,6 +125,19 @@ function initializeDatabase() {
     // Column already exists, ignore error
   }
 
+  // Add ticker column for ticker-symbol voting
+  try {
+    db.exec(`ALTER TABLE games ADD COLUMN ticker TEXT`);
+  } catch (err) {
+    // Column already exists, ignore error
+  }
+
+  try {
+    db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_games_ticker ON games(ticker)`);
+  } catch (err) {
+    // Index already exists, ignore error
+  }
+
   // Migrate existing popularity_score to upvotes/downvotes if needed
   try {
     const gamesWithScore = db.prepare(`

backend/routes/auth.js

@@ -18,7 +18,7 @@ router.post('/login', (req, res) => {
   }
 
   const token = jwt.sign(
-    { role: 'admin', name: admin.name, timestamp: Date.now() },
+    { role: admin.role, name: admin.name, timestamp: Date.now() },
     JWT_SECRET,
     { expiresIn: '24h' }
   );
@@ -26,6 +26,7 @@ router.post('/login', (req, res) => {
   res.json({
     token,
     name: admin.name,
+    role: admin.role,
     message: 'Authentication successful',
     expiresIn: '24h'
   });

backend/routes/sessions.js

@@ -23,6 +23,9 @@ router.get('/', (req, res) => {
   try {
     const filter = req.query.filter || 'default';
     const limitParam = req.query.limit || 'all';
+    const offsetParam = req.query.offset || '0';
+    let offset = parseInt(offsetParam, 10);
+    if (isNaN(offset) || offset < 0) offset = 0;
 
     let whereClause = '';
     if (filter === 'default') {
@@ -45,6 +48,11 @@ router.get('/', (req, res) => {
       }
     }
 
+    let offsetClause = '';
+    if (offset > 0) {
+      offsetClause = `OFFSET ${offset}`;
+    }
+
     const sessions = db.prepare(`
       SELECT 
         s.id,
@@ -60,6 +68,7 @@ router.get('/', (req, res) => {
       GROUP BY s.id
       ORDER BY s.created_at DESC
       ${limitClause}
+      ${offsetClause}
     `).all();
 
     const result = sessions.map(({ notes, ...session }) => {
@@ -67,7 +76,23 @@ router.get('/', (req, res) => {
       return { ...session, has_notes, notes_preview };
     });
 
+    const absoluteTotal = db.prepare('SELECT COUNT(*) as total FROM sessions').get();
+
+    if (offset > 0) {
+      const prevRow = db.prepare(`
+        SELECT s.created_at
+        FROM sessions s
+        ${whereClause}
+        ORDER BY s.created_at DESC
+        LIMIT 1 OFFSET ${offset - 1}
+      `).get();
+      if (prevRow) {
+        res.set('X-Prev-Last-Date', prevRow.created_at);
+      }
+    }
+
     res.set('X-Total-Count', String(countRow.total));
+    res.set('X-Absolute-Total', String(absoluteTotal.total));
     res.json(result);
   } catch (error) {
     res.status(500).json({ error: error.message });

backend/routes/votes.js

@@ -89,7 +89,7 @@ router.get('/', (req, res) => {
 // Live vote endpoint - receives real-time votes from bot
 router.post('/live', authenticateToken, (req, res) => {
   try {
-    const { username, vote, timestamp } = req.body;
+    const { username, vote, timestamp, ticker } = req.body;
 
     // Validate payload
     if (!username || !vote || !timestamp) {
@@ -123,7 +123,24 @@ router.post('/live', authenticateToken, (req, res) => {
       });
     }
 
-    // Get all games played in this session with timestamps
+    let matchedGame = null;
+
+    if (ticker) {
+      // Ticker voting: resolve game globally by ticker symbol
+      const game = db.prepare(`
+        SELECT id AS game_id, title, pack_name, upvotes, downvotes, popularity_score
+        FROM games WHERE ticker = ?
+      `).get(ticker);
+
+      if (!game) {
+        return res.status(404).json({
+          error: `Unknown ticker '${ticker}'`,
+        });
+      }
+
+      matchedGame = game;
+    } else {
+      // thisgame++/thisgame-- voting: resolve game by timestamp interval
       const sessionGames = db.prepare(`
         SELECT sg.game_id, sg.played_at, g.title, g.pack_name, g.upvotes, g.downvotes, g.popularity_score
         FROM session_games sg
@@ -138,9 +155,7 @@ router.post('/live', authenticateToken, (req, res) => {
         });
       }
 
-    // Match vote timestamp to the correct game using interval logic
       const voteTime = voteTimestamp.getTime();
-    let matchedGame = null;
 
       for (let i = 0; i < sessionGames.length; i++) {
         const currentGame = sessionGames[i];
@@ -155,7 +170,6 @@ router.post('/live', authenticateToken, (req, res) => {
             break;
           }
         } else {
-        // Last game in session - vote belongs here if timestamp is after this game started
           if (voteTime >= currentGameTime) {
             matchedGame = currentGame;
             break;
@@ -175,6 +189,7 @@ router.post('/live', authenticateToken, (req, res) => {
           }
         });
       }
+    }
 
     // Check for duplicate vote (within 1 second window)
     // Get the most recent vote from this user
@@ -258,6 +273,7 @@ router.post('/live', authenticateToken, (req, res) => {
             id: updatedGame.id,
             title: updatedGame.title,
             pack_name: matchedGame.pack_name,
+            ticker: ticker || undefined,
           },
           vote: {
             username: username,
@@ -303,7 +319,8 @@ router.post('/live', authenticateToken, (req, res) => {
       vote: {
         username: username,
         type: vote,
-        timestamp: timestamp
+        timestamp: timestamp,
+        ticker: ticker || undefined,
       }
     });
 

backend/server.js

@@ -2,7 +2,7 @@ require('dotenv').config();
 const express = require('express');
 const http = require('http');
 const cors = require('cors');
-const { bootstrapGames } = require('./bootstrap');
+const { bootstrapGames, bootstrapTickers } = require('./bootstrap');
 const { WebSocketManager, setWebSocketManager } = require('./utils/websocket-manager');
 const { cleanupAllShards } = require('./utils/ecast-shard-client');
 
@@ -50,6 +50,7 @@ setWebSocketManager(wsManager);
 
 if (require.main === module) {
   bootstrapGames();
+  bootstrapTickers();
   server.listen(PORT, '0.0.0.0', () => {
     console.log(`Server is running on port ${PORT}`);
     console.log(`WebSocket server available at ws://localhost:${PORT}/api/sessions/live`);

backend/utils/ecast-shard-client.js

@@ -36,7 +36,7 @@ class EcastShardClient {
       lobbyState: roomVal.lobbyState ?? null,
       gameCanStart: !!roomVal.gameCanStart,
       gameIsStarting: !!roomVal.gameIsStarting,
-      gameStarted: roomVal.state === 'Gameplay',
+      gameStarted: roomVal.state != null && roomVal.state !== 'Lobby',
       gameFinished: !!roomVal.gameFinished,
     };
   }
@@ -213,6 +213,12 @@ class EcastShardClient {
         break;
       case 'client/disconnected':
         break;
+      case 'room/lock':
+        this.handleRoomLock();
+        break;
+      case 'room/exit':
+        this.handleRoomExit(message.result);
+        break;
       case 'error':
         this.handleError(message.result);
         break;
@@ -363,6 +369,44 @@ class EcastShardClient {
     }
   }
 
+  handleRoomLock() {
+    if (!this.gameStarted) {
+      console.log(`[Shard Monitor] Room ${this.roomCode} locked (game starting)`);
+      this.gameStarted = true;
+      this.gameState = this.gameState || 'Gameplay';
+      this.onEvent('game.started', {
+        sessionId: this.sessionId,
+        gameId: this.gameId,
+        roomCode: this.roomCode,
+        playerCount: this.playerCount,
+        players: [...this.playerNames],
+        maxPlayers: this.maxPlayers,
+      });
+    }
+  }
+
+  handleRoomExit() {
+    if (this.gameFinished) return;
+    console.log(`[Shard Monitor] Room ${this.roomCode} exited`);
+    this.gameFinished = true;
+    this.onEvent('game.ended', {
+      sessionId: this.sessionId,
+      gameId: this.gameId,
+      roomCode: this.roomCode,
+      playerCount: this.playerCount,
+      players: [...this.playerNames],
+    });
+    this.onEvent('room.disconnected', {
+      sessionId: this.sessionId,
+      gameId: this.gameId,
+      roomCode: this.roomCode,
+      reason: 'room_closed',
+      finalPlayerCount: this.playerCount,
+    });
+    activeShards.delete(`${this.sessionId}-${this.gameId}`);
+    this.disconnect();
+  }
+
   handleError(result) {
     console.error(`[Shard Monitor] Ecast error ${result?.code}: ${result?.msg}`);
     if (result?.code === 2027) {

backend/utils/websocket-manager.js

@@ -26,13 +26,17 @@ class WebSocketManager {
    * Handle new WebSocket connection
    */
   handleConnection(ws, req) {
-    console.log('[WebSocket] New connection from', req.socket.remoteAddress);
+    const clientIp = req.headers['x-forwarded-for']?.split(',')[0]?.trim()
+      || req.headers['x-real-ip']
+      || req.socket.remoteAddress;
+    console.log('[WebSocket] New connection from', clientIp);
     
     // Initialize client info
     const clientInfo = {
       authenticated: false,
       userId: null,
       adminName: null,
+      role: null,
       currentPage: null,
       subscribedSessions: new Set(),
       lastPing: Date.now()
@@ -130,6 +134,7 @@ class WebSocketManager {
         clientInfo.authenticated = true;
         clientInfo.userId = decoded.role;
         clientInfo.adminName = decoded.name || null;
+        clientInfo.role = decoded.role || 'admin';
 
         if (!decoded.name) {
           this.sendError(ws, 'Token missing admin identity, please re-login', 'auth_error');
@@ -141,7 +146,8 @@ class WebSocketManager {
           message: 'Authenticated successfully'
         });
         
-        console.log('[WebSocket] Client authenticated:', clientInfo.userId);
+        console.log('[WebSocket] Client authenticated:', clientInfo.adminName);
+        this.broadcastPresence();
       }
     } catch (err) {
       console.error('[WebSocket] Authentication failed:', err.message);
@@ -299,7 +305,7 @@ class WebSocketManager {
       });
       
       this.clients.delete(ws);
-      console.log('[WebSocket] Client disconnected and cleaned up');
+      console.log('[WebSocket] Client disconnected:', clientInfo.adminName || 'unauthenticated');
       this.broadcastPresence();
     }
   }
@@ -307,8 +313,12 @@ class WebSocketManager {
   broadcastPresence() {
     const admins = [];
     this.clients.forEach((info) => {
-      if (info.authenticated && info.adminName && info.currentPage) {
-        admins.push({ name: info.adminName, page: info.currentPage });
+      if (!info.authenticated || !info.adminName) return;
+      const role = info.role || 'admin';
+      if (role === 'bot' || role === 'utility') {
+        admins.push({ name: info.adminName, role, page: null });
+      } else if (info.currentPage) {
+        admins.push({ name: info.adminName, role, page: info.currentPage });
       }
     });
 

docker-compose.yml

@@ -15,8 +15,8 @@ services:
       - DEBUG=false
     volumes:
       - jackbox-data:/app/data
-      - ./games-list.csv:/app/games-list.csv:ro
-      # - ./backend/config/admins.json:/app/config/admins.json:ro
+      - ./games-list.csv:/app/games-list.csv:ro,z
+      - ./backend/config/admins.json:/app/config/admins.json:ro,z
     ports:
       - "5000:5000"
     networks:

docs/api/endpoints/votes.md

@@ -1,6 +1,9 @@
 # Votes Endpoints
 
-Real-time popularity voting. Bots or integrations send votes during live gaming sessions. Votes are matched to the currently-playing game using timestamp intervals.
+Real-time popularity voting. Bots or integrations send votes during live gaming sessions. Two voting mechanisms are supported:
+
+- **`thisgame++`/`thisgame--`** — votes for the game currently being played, matched via timestamp intervals.
+- **Ticker voting** — votes for a specific game by its ticker symbol (e.g. `QPL3` for Quiplash 3), regardless of what is currently being played.
 
 ## Endpoint Summary
 
@@ -71,7 +74,10 @@ Results are ordered by `timestamp DESC`. The `vote_type` field is returned as `"
 
 ## POST /api/votes/live
 
-Submit a real-time up/down vote for the game currently being played. Automatically finds the active session and matches the vote to the correct game using the provided timestamp and session game intervals.
+Submit a real-time up/down vote. Supports two independent voting mechanisms:
+
+- **Ticker voting** — include a `ticker` field to vote for a specific game by symbol. The game is resolved globally and does not need to be in the active session.
+- **`thisgame++`/`thisgame--` voting** — omit `ticker` to vote for the game currently being played, matched via timestamp intervals against `session_games`.
 
 ### Authentication
 
@@ -84,6 +90,20 @@ Bearer token required. Include in header: `Authorization: Bearer <token>`.
 | username | string | Yes | Identifier for the voter (used for deduplication) |
 | vote | string | Yes | `"up"` or `"down"` |
 | timestamp | string | Yes | ISO 8601 timestamp when the vote occurred |
+| ticker | string | No | Ticker symbol identifying the game (e.g. `QPL3`, `TMP2`). When provided, the game is resolved by ticker and timestamp matching is skipped. |
+
+**Ticker vote:**
+
+```json
+{
+  "username": "viewer123",
+  "vote": "up",
+  "timestamp": "2026-03-15T20:30:00Z",
+  "ticker": "QPL3"
+}
+```
+
+**`thisgame++`/`thisgame--` vote (no ticker):**
 
 ```json
 {
@@ -96,7 +116,8 @@ Bearer token required. Include in header: `Authorization: Bearer <token>`.
 ### Behavior
 
 - Finds the active session (single session with `is_active = 1`).
-- Matches the vote timestamp to the game being played at that time (uses interval between consecutive `played_at` timestamps).
+- **With `ticker`:** Looks up the game globally by ticker symbol. The game does not need to be part of the active session.
+- **Without `ticker`:** Matches the vote timestamp to the game being played at that time (uses interval between consecutive `played_at` timestamps).
 - Updates game `upvotes`, `downvotes`, and `popularity_score` atomically in a transaction.
 - **Deduplication:** Rejects votes from the same username within a 1-second window (409 Conflict).
 - Broadcasts a `vote.received` WebSocket event to all clients subscribed to the active session. See [WebSocket Protocol](../websocket.md#votereceived) for event payload.
@@ -105,6 +126,8 @@ Bearer token required. Include in header: `Authorization: Bearer <token>`.
 
 **200 OK**
 
+The `ticker` field is included in the response when the vote was submitted with a ticker.
+
 ```json
 {
   "success": true,
@@ -120,7 +143,8 @@ Bearer token required. Include in header: `Authorization: Bearer <token>`.
   "vote": {
     "username": "viewer123",
     "type": "up",
-    "timestamp": "2026-03-15T20:30:00Z"
+    "timestamp": "2026-03-15T20:30:00Z",
+    "ticker": "QPL3"
   }
 }
 ```
@@ -133,12 +157,29 @@ Bearer token required. Include in header: `Authorization: Bearer <token>`.
 | 400 | `{ "error": "vote must be either \"up\" or \"down\"" }` | Invalid vote value |
 | 400 | `{ "error": "Invalid timestamp format. Use ISO 8601 format (e.g., 2025-11-01T20:30:00Z)" }` | Invalid timestamp |
 | 404 | `{ "error": "No active session found" }` | No session with `is_active = 1` |
-| 404 | `{ "error": "No games have been played in the active session yet" }` | Active session has no games |
-| 404 | `{ "error": "Vote timestamp does not match any game in the active session", "debug": { "voteTimestamp": "2026-03-15T20:30:00Z", "sessionGames": [{ "title": "Quiplash 3", "played_at": "..." }] } }` | Timestamp outside any game interval |
+| 404 | `{ "error": "Unknown ticker 'XYZ'" }` | Ticker does not match any game |
+| 404 | `{ "error": "No games have been played in the active session yet" }` | Active session has no games (timestamp voting only) |
+| 404 | `{ "error": "Vote timestamp does not match any game in the active session", "debug": { ... } }` | Timestamp outside any game interval (timestamp voting only) |
 | 409 | `{ "error": "Duplicate vote detected (within 1 second of previous vote)", "message": "Please wait at least 1 second between votes", "timeSinceLastVote": 0.5 }` | Same username voted within 1 second |
 | 500 | `{ "error": "..." }` | Server error |
 
-### Example
+### Examples
+
+**Ticker vote:**
+
+```bash
+curl -X POST "http://localhost:5000/api/votes/live" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "username": "viewer123",
+    "vote": "up",
+    "timestamp": "2026-03-15T20:30:00Z",
+    "ticker": "QPL3"
+  }'
+```
+
+**`thisgame++` vote (no ticker):**
 
 ```bash
 curl -X POST "http://localhost:5000/api/votes/live" \

docs/superpowers/plans/2026-03-23-pagination-day-grouping.md

@@ -0,0 +1,611 @@
+# Pagination & Day Grouping Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add offset-based pagination and day-grouped session rendering to the History page.
+
+**Architecture:** Backend adds `offset` param and `X-Prev-Last-Date` header to `GET /sessions`. Frontend adds page state, groups sessions by local date at render time with styled day headers, and renders a Prev/Next pagination bar.
+
+**Tech Stack:** Node.js/Express/better-sqlite3 (backend), React/Tailwind CSS (frontend), Jest/supertest (tests)
+
+---
+
+### Task 1: Backend — Add `offset` param and `X-Prev-Last-Date` header
+
+**Files:**
+- Modify: `backend/routes/sessions.js:22-76` (the `GET /` handler)
+- Test: `tests/api/session-archive.test.js` (add new tests to the existing `GET /api/sessions` describe block)
+
+- [ ] **Step 1: Write failing tests for `offset` and `X-Prev-Last-Date`**
+
+Add these tests at the end of the `GET /api/sessions — filter and limit` describe block in `tests/api/session-archive.test.js`:
+
+```javascript
+test('offset skips the first N sessions', async () => {
+  for (let i = 0; i < 5; i++) {
+    seedSession({ is_active: 0, notes: null });
+  }
+
+  const allRes = await request(app).get('/api/sessions?filter=all&limit=all');
+  const offsetRes = await request(app).get('/api/sessions?filter=all&limit=2&offset=2');
+  expect(offsetRes.status).toBe(200);
+  expect(offsetRes.body).toHaveLength(2);
+  expect(offsetRes.body[0].id).toBe(allRes.body[2].id);
+  expect(offsetRes.body[1].id).toBe(allRes.body[3].id);
+});
+
+test('offset defaults to 0 when not provided', async () => {
+  for (let i = 0; i < 3; i++) {
+    seedSession({ is_active: 0, notes: null });
+  }
+
+  const res = await request(app).get('/api/sessions?filter=all&limit=2');
+  expect(res.status).toBe(200);
+  expect(res.body).toHaveLength(2);
+});
+
+test('negative offset is clamped to 0', async () => {
+  seedSession({ is_active: 0, notes: null });
+
+  const res = await request(app).get('/api/sessions?filter=all&offset=-5');
+  expect(res.status).toBe(200);
+  expect(res.body).toHaveLength(1);
+});
+
+test('non-numeric offset is clamped to 0', async () => {
+  seedSession({ is_active: 0, notes: null });
+
+  const res = await request(app).get('/api/sessions?filter=all&offset=abc');
+  expect(res.status).toBe(200);
+  expect(res.body).toHaveLength(1);
+});
+
+test('offset past end returns empty array', async () => {
+  seedSession({ is_active: 0, notes: null });
+
+  const res = await request(app).get('/api/sessions?filter=all&limit=5&offset=100');
+  expect(res.status).toBe(200);
+  expect(res.body).toHaveLength(0);
+  expect(res.headers['x-total-count']).toBe('1');
+});
+
+test('X-Prev-Last-Date header is set with correct value when offset > 0', async () => {
+  for (let i = 0; i < 5; i++) {
+    seedSession({ is_active: 0, notes: null });
+  }
+
+  const allRes = await request(app).get('/api/sessions?filter=all&limit=all');
+  const res = await request(app).get('/api/sessions?filter=all&limit=2&offset=2');
+  expect(res.headers['x-prev-last-date']).toBe(allRes.body[1].created_at);
+});
+
+test('X-Prev-Last-Date header is absent when offset is 0', async () => {
+  seedSession({ is_active: 0, notes: null });
+
+  const res = await request(app).get('/api/sessions?filter=all&limit=2');
+  expect(res.headers['x-prev-last-date']).toBeUndefined();
+});
+
+test('X-Total-Count is unaffected by offset', async () => {
+  for (let i = 0; i < 10; i++) {
+    seedSession({ is_active: 0, notes: null });
+  }
+
+  const res = await request(app).get('/api/sessions?filter=all&limit=3&offset=6');
+  expect(res.headers['x-total-count']).toBe('10');
+  expect(res.body).toHaveLength(3);
+});
+
+test('offset works with filter=default', async () => {
+  for (let i = 0; i < 5; i++) {
+    seedSession({ is_active: 0, notes: null });
+  }
+  const archived = seedSession({ is_active: 0, notes: null });
+  require('../helpers/test-utils').db.prepare(
+    'UPDATE sessions SET archived = 1 WHERE id = ?'
+  ).run(archived.id);
+
+  const res = await request(app).get('/api/sessions?filter=default&limit=2&offset=2');
+  expect(res.status).toBe(200);
+  expect(res.body).toHaveLength(2);
+  expect(res.headers['x-total-count']).toBe('5');
+  res.body.forEach(s => expect(s.archived).toBe(0));
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npx jest tests/api/session-archive.test.js --no-coverage --forceExit`
+Expected: 9 new tests FAIL (offset is not yet implemented)
+
+- [ ] **Step 3: Implement offset and X-Prev-Last-Date in the GET handler**
+
+In `backend/routes/sessions.js`, modify the `router.get('/')` handler (lines 22-76). After parsing `limitParam` (line 25), add offset parsing:
+
+```javascript
+const offsetParam = req.query.offset || '0';
+let offset = parseInt(offsetParam, 10);
+if (isNaN(offset) || offset < 0) offset = 0;
+```
+
+After the `limitClause` block (line 46), build the offset clause:
+
+```javascript
+let offsetClause = '';
+if (offset > 0) {
+  offsetClause = `OFFSET ${offset}`;
+}
+```
+
+Update the sessions query (line 62) to include `${offsetClause}` after `${limitClause}`:
+
+```sql
+ORDER BY s.created_at DESC
+${limitClause}
+${offsetClause}
+```
+
+Before `res.set('X-Total-Count', ...)`, add the `X-Prev-Last-Date` logic:
+
+```javascript
+if (offset > 0) {
+  const prevRow = db.prepare(`
+    SELECT s.created_at
+    FROM sessions s
+    ${whereClause}
+    ORDER BY s.created_at DESC
+    LIMIT 1 OFFSET ${offset - 1}
+  `).get();
+  if (prevRow) {
+    res.set('X-Prev-Last-Date', prevRow.created_at);
+  }
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `npx jest tests/api/session-archive.test.js --no-coverage --forceExit`
+Expected: ALL tests pass (24 existing + 9 new = 33)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add backend/routes/sessions.js tests/api/session-archive.test.js
+git commit -m "feat: add offset pagination and X-Prev-Last-Date header to GET /sessions"
+```
+
+---
+
+### Task 2: Frontend — Date utility helpers
+
+**Files:**
+- Modify: `frontend/src/utils/dateUtils.js`
+
+- [ ] **Step 1: Add `getLocalDateKey` and `formatDayHeader` helpers**
+
+Append to `frontend/src/utils/dateUtils.js`:
+
+```javascript
+/**
+ * Get a locale-independent date key for grouping sessions by local calendar day
+ * @param {string} sqliteTimestamp
+ * @returns {string} - e.g., "2026-03-23"
+ */
+export function getLocalDateKey(sqliteTimestamp) {
+  const d = parseUTCTimestamp(sqliteTimestamp);
+  const year = d.getFullYear();
+  const month = String(d.getMonth() + 1).padStart(2, '0');
+  const day = String(d.getDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+/**
+ * Format a SQLite timestamp as a day header string (e.g., "Sunday, Mar 23, 2026")
+ * @param {string} sqliteTimestamp
+ * @returns {string}
+ */
+export function formatDayHeader(sqliteTimestamp) {
+  const d = parseUTCTimestamp(sqliteTimestamp);
+  return d.toLocaleDateString(undefined, {
+    weekday: 'long',
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+  });
+}
+
+/**
+ * Format a SQLite timestamp as a time-only string (e.g., "7:30 PM")
+ * @param {string} sqliteTimestamp
+ * @returns {string}
+ */
+export function formatTimeOnly(sqliteTimestamp) {
+  const d = parseUTCTimestamp(sqliteTimestamp);
+  return d.toLocaleTimeString(undefined, {
+    hour: 'numeric',
+    minute: '2-digit',
+  });
+}
+```
+
+- [ ] **Step 2: Verify frontend builds**
+
+Run: `cd frontend && npm run build`
+Expected: Build succeeds with no errors
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add frontend/src/utils/dateUtils.js
+git commit -m "feat: add getLocalDateKey, formatDayHeader, formatTimeOnly date helpers"
+```
+
+---
+
+### Task 3: Frontend — Pagination state and API integration
+
+**Files:**
+- Modify: `frontend/src/pages/History.jsx:14-75` (state declarations and `loadSessions`)
+
+- [ ] **Step 1: Add page state and update loadSessions**
+
+In `History.jsx`, add state after line 17 (`absoluteTotal`):
+
+```javascript
+const [page, setPage] = useState(1);
+const [prevLastDate, setPrevLastDate] = useState(null);
+```
+
+Update `loadSessions` (the `api.get` call around line 32) to pass `offset`:
+
+```javascript
+const limitNum = limit === 'all' ? null : parseInt(limit, 10);
+const offset = limitNum ? (page - 1) * limitNum : 0;
+
+const response = await api.get('/sessions', {
+  params: { filter, limit, offset: offset || undefined }
+});
+```
+
+After setting `absoluteTotal`, add:
+
+```javascript
+setPrevLastDate(response.headers['x-prev-last-date'] || null);
+```
+
+Add `page` to the `useCallback` dependency array for `loadSessions`.
+
+- [ ] **Step 2: Add page reset logic**
+
+Update `handleFilterChange` and `handleLimitChange` to reset page:
+
+```javascript
+const handleFilterChange = (newFilter) => {
+  setFilter(newFilter);
+  localStorage.setItem(prefixKey(adminName, 'history-filter'), newFilter);
+  setSelectedIds(new Set());
+  setPage(1);
+};
+
+const handleLimitChange = (newLimit) => {
+  setLimit(newLimit);
+  localStorage.setItem(prefixKey(adminName, 'history-show-limit'), newLimit);
+  setSelectedIds(new Set());
+  setPage(1);
+};
+```
+
+Add auto-reset when page becomes empty. Place this check **after** all state updates (`setSessions`, `setTotalCount`, `setAbsoluteTotal`, `setPrevLastDate`) to avoid stale state:
+
+```javascript
+setSessions(response.data);
+setTotalCount(parseInt(response.headers['x-total-count'] || '0', 10));
+setAbsoluteTotal(parseInt(response.headers['x-absolute-total'] || '0', 10));
+setPrevLastDate(response.headers['x-prev-last-date'] || null);
+
+if (response.data.length === 0 && offset > 0) {
+  setPage(1);
+}
+```
+
+Also add `setPage(1)` to `exitSelectMode`:
+
+```javascript
+const exitSelectMode = () => {
+  setSelectMode(false);
+  setSelectedIds(new Set());
+  setShowBulkDeleteConfirm(false);
+  setPage(1);
+};
+```
+
+And in the select mode toggle button's `onClick` (where `setSelectMode(true)` is called), add `setPage(1)` after it. Similarly in `handlePointerDown` where `setSelectMode(true)` is called, add `setPage(1)` after it.
+
+- [ ] **Step 3: Verify frontend builds**
+
+Run: `cd frontend && npm run build`
+Expected: Build succeeds
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add frontend/src/pages/History.jsx
+git commit -m "feat: add pagination state and offset to session API calls"
+```
+
+---
+
+### Task 4: Frontend — Day grouping rendering
+
+**Files:**
+- Modify: `frontend/src/pages/History.jsx:1-8` (imports) and `208-316` (session list rendering)
+
+- [ ] **Step 1: Update imports**
+
+Replace the `dateUtils` import at line 6:
+
+```javascript
+import { formatDayHeader, formatTimeOnly, getLocalDateKey, isSunday } from '../utils/dateUtils';
+```
+
+(Remove `formatLocalDate` since session cards will now show time-only under day headers.)
+
+- [ ] **Step 2: Add grouping logic and render day headers**
+
+Replace the session list rendering section (`{sessions.map(session => { ... })}`) with day-grouped rendering. The grouping is computed at render time using `useMemo`:
+
+Add before the `return` statement (above `if (loading)`):
+
+```javascript
+const groupedSessions = useMemo(() => {
+  const groups = [];
+  let currentKey = null;
+
+  sessions.forEach(session => {
+    const dateKey = getLocalDateKey(session.created_at);
+    if (dateKey !== currentKey) {
+      currentKey = dateKey;
+      groups.push({ dateKey, sessions: [session] });
+    } else {
+      groups[groups.length - 1].sessions.push(session);
+    }
+  });
+
+  return groups;
+}, [sessions]);
+```
+
+Add `useMemo` to the React import at line 1.
+
+Replace the `{sessions.map(session => { ... })}` block inside `<div className="space-y-2">` with:
+
+```jsx
+{groupedSessions.map((group, groupIdx) => {
+  const isSundayGroup = isSunday(group.sessions[0].created_at);
+  const isContinued = groupIdx === 0 && page > 1 && prevLastDate &&
+    getLocalDateKey(prevLastDate) === group.dateKey;
+
+  return (
+    <div key={group.dateKey}>
+      {/* Day header bar */}
+      <div className="bg-gray-100 dark:bg-[#1e2a3a] rounded-md px-3.5 py-2 mb-2 flex justify-between items-center border-l-[3px] border-indigo-500">
+        <div className="flex items-center gap-2">
+          <span className="text-sm font-semibold text-indigo-700 dark:text-indigo-300">
+            {formatDayHeader(group.sessions[0].created_at)}
+          </span>
+          {isContinued && (
+            <span className="text-xs text-gray-400 dark:text-gray-500 italic">(continued)</span>
+          )}
+        </div>
+        {!isContinued && (
+          <div className="flex items-center gap-2">
+            <span className="text-xs text-gray-500 dark:text-gray-400">
+              {group.sessions.length} session{group.sessions.length !== 1 ? 's' : ''}
+            </span>
+            {isSundayGroup && (
+              <span className="text-xs font-semibold text-amber-700 dark:text-amber-300">🎲 Game Night</span>
+            )}
+          </div>
+        )}
+      </div>
+
+      {/* Session cards under this day */}
+      <div className="ml-3 space-y-1.5 mb-4">
+        {group.sessions.map(session => {
+          const isActive = session.is_active === 1;
+          const isSelected = selectedIds.has(session.id);
+          const isArchived = session.archived === 1;
+          const canSelect = selectMode && !isActive;
+
+          return (
+            <div
+              key={session.id}
+              className={`border rounded-lg transition ${
+                selectMode && isActive
+                  ? 'opacity-50 cursor-not-allowed border-gray-300 dark:border-gray-600'
+                  : isSelected
+                    ? 'border-indigo-500 bg-indigo-50 dark:bg-indigo-900/20 cursor-pointer'
+                    : 'border-gray-300 dark:border-gray-600 hover:border-indigo-400 dark:hover:border-indigo-500 cursor-pointer'
+              }`}
+              onClick={() => {
+                if (longPressFired.current) {
+                  longPressFired.current = false;
+                  return;
+                }
+                if (selectMode) {
+                  if (!isActive) toggleSelection(session.id);
+                } else {
+                  navigate(`/history/${session.id}`);
+                }
+              }}
+              onPointerDown={() => {
+                if (!isActive) handlePointerDown(session.id);
+              }}
+              onPointerUp={handlePointerUp}
+              onPointerLeave={handlePointerUp}
+            >
+              <div className="p-4">
+                <div className="flex items-start gap-3">
+                  {selectMode && (
+                    <div className={`mt-0.5 w-5 h-5 flex-shrink-0 rounded border-2 flex items-center justify-center ${
+                      isActive
+                        ? 'border-gray-300 dark:border-gray-600 bg-gray-100 dark:bg-gray-700'
+                        : isSelected
+                          ? 'border-indigo-600 bg-indigo-600'
+                          : 'border-gray-300 dark:border-gray-600'
+                    }`}>
+                      {isSelected && (
+                        <span className="text-white text-xs font-bold">✓</span>
+                      )}
+                    </div>
+                  )}
+                  <div className="flex-1 min-w-0">
+                    <div className="flex justify-between items-center mb-1">
+                      <div className="flex items-center gap-2 flex-wrap">
+                        <span className="font-semibold text-gray-800 dark:text-gray-100">
+                          Session #{session.id}
+                        </span>
+                        {isActive && (
+                          <span className="bg-green-100 dark:bg-green-900 text-green-800 dark:text-green-200 text-xs px-2 py-0.5 rounded">
+                            Active
+                          </span>
+                        )}
+                        {isArchived && (filter === 'all' || filter === 'archived') && (
+                          <span className="bg-gray-100 dark:bg-gray-700 text-gray-500 dark:text-gray-400 text-xs px-2 py-0.5 rounded">
+                            Archived
+                          </span>
+                        )}
+                      </div>
+                      <span className="text-sm text-gray-500 dark:text-gray-400">
+                        {session.games_played} game{session.games_played !== 1 ? 's' : ''}
+                      </span>
+                    </div>
+                    <div className="text-sm text-gray-500 dark:text-gray-400">
+                      {formatTimeOnly(session.created_at)}
+                    </div>
+                    {session.has_notes && session.notes_preview && (
+                      <div className="mt-2 text-sm text-indigo-400 dark:text-indigo-300 bg-indigo-50 dark:bg-indigo-900/20 px-3 py-2 rounded border-l-2 border-indigo-500">
+                        {session.notes_preview}
+                      </div>
+                    )}
+                  </div>
+                </div>
+              </div>
+
+              {!selectMode && isAuthenticated && isActive && (
+                <div className="px-4 pb-4 pt-0">
+                  <button
+                    onClick={(e) => {
+                      e.stopPropagation();
+                      setClosingSession(session.id);
+                    }}
+                    className="w-full bg-orange-600 dark:bg-orange-700 text-white px-4 py-2 rounded text-sm hover:bg-orange-700 dark:hover:bg-orange-800 transition"
+                  >
+                    End Session
+                  </button>
+                </div>
+              )}
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+})}
+```
+
+Each session card inside the group keeps its existing structure (selection, badges, notes preview, etc.) but:
+- The date line changes from `formatLocalDate(session.created_at)` to `formatTimeOnly(session.created_at)`
+- Remove the per-card `isSundaySession` badge (`🎲 Game Night` span) and the `· Sunday` text — these are now on the day header
+- Remove the `isSundaySession` const from inside the card map — it's computed per-group instead
+
+- [ ] **Step 3: Verify frontend builds**
+
+Run: `cd frontend && npm run build`
+Expected: Build succeeds
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add frontend/src/pages/History.jsx
+git commit -m "feat: render sessions grouped by day with styled header bars"
+```
+
+---
+
+### Task 5: Frontend — Pagination bar
+
+**Files:**
+- Modify: `frontend/src/pages/History.jsx` (add pagination bar below session list, above multi-select action bar)
+
+- [ ] **Step 1: Add pagination bar JSX**
+
+After the closing `</div>` of `<div className="space-y-2">` (the session list) and before the multi-select action bar `{selectMode && selectedIds.size > 0 && (`, add:
+
+```jsx
+{/* Pagination bar */}
+{limit !== 'all' && (() => {
+  const limitNum = parseInt(limit, 10);
+  const totalPages = Math.ceil(totalCount / limitNum);
+  if (totalPages <= 1) return null;
+  return (
+    <div className="flex justify-center items-center gap-4 py-3 mt-3 border-t border-gray-200 dark:border-gray-700">
+      <button
+        onClick={() => { setPage(p => p - 1); setSelectedIds(new Set()); }}
+        disabled={page <= 1}
+        className={`px-4 py-1.5 rounded-md text-sm font-medium transition ${
+          page <= 1
+            ? 'bg-gray-600 dark:bg-gray-700 text-gray-400 dark:text-gray-500 cursor-not-allowed'
+            : 'bg-indigo-600 text-white hover:bg-indigo-700'
+        }`}
+      >
+        ← Prev
+      </button>
+      <span className="text-sm text-gray-500 dark:text-gray-400">
+        Page {page} of {totalPages}
+      </span>
+      <button
+        onClick={() => { setPage(p => p + 1); setSelectedIds(new Set()); }}
+        disabled={page >= totalPages}
+        className={`px-4 py-1.5 rounded-md text-sm font-medium transition ${
+          page >= totalPages
+            ? 'bg-gray-600 dark:bg-gray-700 text-gray-400 dark:text-gray-500 cursor-not-allowed'
+            : 'bg-indigo-600 text-white hover:bg-indigo-700'
+        }`}
+      >
+        Next →
+      </button>
+    </div>
+  );
+})()}
+```
+
+- [ ] **Step 2: Verify frontend builds**
+
+Run: `cd frontend && npm run build`
+Expected: Build succeeds
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add frontend/src/pages/History.jsx
+git commit -m "feat: add Prev/Next pagination bar to session history"
+```
+
+---
+
+### Task 6: Final verification
+
+**Files:** None (verification only)
+
+- [ ] **Step 1: Run full backend test suite**
+
+Run: `npx jest --no-coverage --forceExit`
+Expected: All tests pass (147 existing + 9 new = 156)
+
+- [ ] **Step 2: Verify frontend build**
+
+Run: `cd frontend && npm run build`
+Expected: Clean build, no warnings
+
+- [ ] **Step 3: Final commit if any cleanup needed**

docs/superpowers/specs/2026-03-23-pagination-day-grouping-design.md

@@ -0,0 +1,99 @@
+# Pagination & Day Grouping — Design Spec
+
+**Date:** 2026-03-23
+**Status:** Approved
+
+## Overview
+
+Two enhancements to the session History page:
+1. **Pagination** — When "Show X" is set to a value other than "All", add Prev/Next navigation to access older sessions.
+2. **Day Grouping** — Group sessions that occurred on the same calendar day under a shared header bar.
+
+## Backend Changes
+
+### `GET /api/sessions` — New `offset` parameter
+
+Add an `offset` query parameter (default `0`) to the existing endpoint. Works with the existing `limit`, `filter`, `X-Total-Count`, and `X-Absolute-Total` headers.
+
+```
+GET /api/sessions?filter=default&limit=5&offset=10
+```
+
+**Offset validation:** Non-numeric or negative values are clamped to 0. An offset past the end returns an empty array (the pagination bar will show "Page X of Y" and the user can navigate back).
+
+**New response header:**
+- `X-Prev-Last-Date` — When `offset > 0`, the raw SQLite `created_at` timestamp (same format as `created_at` in response body, e.g. `"2026-03-23 19:30:00"`) of the session immediately before the current page (the session at position `offset - 1`). Used by the frontend to detect whether the first day group on the current page is a continuation from the previous page. Omitted when `offset` is 0. The frontend parses this with the existing `parseUTCTimestamp` utility.
+
+**SQL changes:** Add `OFFSET` clause to the existing query. For `X-Prev-Last-Date`, run a small secondary query to fetch the `created_at` of the session at position `offset - 1` (same filter/ordering).
+
+No other backend changes required.
+
+## Frontend Changes
+
+### State
+
+- `page` (number, default `1`) — current page number. Derived from offset: `offset = (page - 1) * limit`. **Not persisted** in localStorage; resets to 1 on navigation.
+- `prevLastDate` (string|null) — from `X-Prev-Last-Date` header. Used for "(continued)" detection.
+
+### Page math
+
+```
+totalPages = Math.ceil(totalCount / limitNum)
+offset = (page - 1) * limitNum
+```
+
+When `limit` is `"all"`, pagination is disabled (no offset, no pagination bar).
+
+### `loadSessions` changes
+
+Pass `offset` as a query parameter alongside `filter` and `limit`. Read `X-Prev-Last-Date` from response headers.
+
+### Page reset triggers
+
+Changing `filter`, `limit`, or entering/exiting `selectMode` resets `page` to 1.
+
+### Day Grouping (render-time only)
+
+Group the flat session array by local calendar date at render time. For each group:
+
+1. **Day header bar** — Styled with `bg-[#1e2a3a]` (dark) / `bg-gray-100` (light), left border accent (`border-l-[3px] border-indigo-500`), contains:
+   - Full date: "Sunday, Mar 23, 2026"
+   - Right side: session count ("2 sessions") and, if Sunday, "🎲 Game Night"
+2. **Session cards** — Indented slightly (`ml-3`) beneath their day header. Display **time only** (e.g., "7:30 PM") since the full date is in the header. Remove the per-card "· Sunday" text and per-card "🎲 Game Night" badge since that information is now on the day header.
+
+### "(continued)" detection
+
+When `page > 1` and `prevLastDate` is set:
+- Parse the previous page's last session date to a local calendar date string
+- If it matches the first day group's date, append an italic "(continued)" tag to that day header (no session count shown for continued groups since the count would be incomplete)
+
+### Pagination bar
+
+Rendered below the session list, above the multi-select action bar (if active). Only shown when `limit !== "all"` and `totalPages > 1`.
+
+Layout: `← Prev` button | "Page X of Y" text | `Next →` button
+
+- Prev button disabled (grayed out) on page 1
+- Next button disabled on last page
+- Active buttons use indigo (`bg-indigo-600`)
+- Disabled buttons use gray (`bg-gray-600/700` with `cursor-not-allowed`)
+
+### Multi-select interaction
+
+Day header bars are not selectable. Only session cards participate in multi-select. Checkboxes render inside the indented card area as they do today. Changing pages clears selected IDs but keeps select mode active.
+
+### Polling behavior
+
+The existing 3-second polling interval refetches the current page (same offset/limit/filter). If sessions are deleted while the user is on a later page and the page becomes empty, the next poll cycle detects `sessions.length === 0 && page > 1` and resets to page 1.
+
+### "Visible" count update
+
+The existing "X visible (Y total)" label continues to work as-is. `sessions.length` reflects the current page's sessions.
+
+## Scope
+
+- No changes to `SessionDetail.jsx`
+- No changes to bulk endpoints
+- No new dependencies
+- The `dateUtils.js` gains a `formatDayHeader` helper (e.g., "Sunday, Mar 23, 2026") and a `getLocalDateKey` helper for grouping
+- Existing tests for `GET /sessions` updated to cover `offset` parameter; new tests for `X-Prev-Last-Date` header

frontend/src/App.jsx

@@ -157,9 +157,6 @@ function App() {
         </div>
       </nav>
 
-      {/* Admin Presence */}
-      <PresenceBar />
-
       {/* Main Content */}
       <main className="container mx-auto px-4 py-8 flex-grow">
         <Routes>
@@ -172,8 +169,11 @@ function App() {
         </Routes>
       </main>
 
+      {/* Admin Presence */}
+      <PresenceBar />
+
       {/* Footer */}
-      <footer className="bg-white dark:bg-gray-800 border-t border-gray-200 dark:border-gray-700 mt-12 flex-shrink-0">
+      <footer className="bg-white dark:bg-gray-800 border-t border-gray-200 dark:border-gray-700 flex-shrink-0">
         <div className="container mx-auto px-4 py-6">
           <div className="flex flex-col md:flex-row justify-between items-center gap-2 text-sm text-gray-600 dark:text-gray-400">
             <div className="text-center md:text-left">

frontend/src/components/PresenceBar.jsx

@@ -2,37 +2,87 @@ import React from 'react';
 import { usePresence } from '../hooks/usePresence';
 import { useAuth } from '../context/AuthContext';
 
+function GearIcon() {
+  return (
+    <svg className="w-3 h-3 mr-1" fill="none" viewBox="0 0 24 24" strokeWidth={2} stroke="currentColor">
+      <path strokeLinecap="round" strokeLinejoin="round" d="M9.594 3.94c.09-.542.56-.94 1.11-.94h2.593c.55 0 1.02.398 1.11.94l.213 1.281c.063.374.313.686.645.87.074.04.147.083.22.127.325.196.72.257 1.075.124l1.217-.456a1.125 1.125 0 0 1 1.37.49l1.296 2.247a1.125 1.125 0 0 1-.26 1.431l-1.003.827c-.293.241-.438.613-.43.992a7.723 7.723 0 0 1 0 .255c-.008.378.137.75.43.991l1.004.827c.424.35.534.955.26 1.43l-1.298 2.248a1.125 1.125 0 0 1-1.369.491l-1.217-.456c-.355-.133-.75-.072-1.076.124a6.47 6.47 0 0 1-.22.128c-.331.183-.581.495-.644.869l-.213 1.281c-.09.543-.56.94-1.11.94h-2.594c-.55 0-1.019-.398-1.11-.94l-.213-1.281c-.062-.374-.312-.686-.644-.87a6.52 6.52 0 0 1-.22-.127c-.325-.196-.72-.257-1.076-.124l-1.217.456a1.125 1.125 0 0 1-1.369-.49l-1.297-2.247a1.125 1.125 0 0 1 .26-1.431l1.004-.827c.292-.24.437-.613.43-.991a6.932 6.932 0 0 1 0-.255c.007-.38-.138-.751-.43-.992l-1.004-.827a1.125 1.125 0 0 1-.26-1.43l1.297-2.247a1.125 1.125 0 0 1 1.37-.491l1.216.456c.356.133.751.072 1.076-.124.072-.044.146-.086.22-.128.332-.183.582-.495.644-.869l.214-1.28Z" />
+      <path strokeLinecap="round" strokeLinejoin="round" d="M15 12a3 3 0 1 1-6 0 3 3 0 0 1 6 0Z" />
+    </svg>
+  );
+}
+
+function ChatBubbleIcon() {
+  return (
+    <svg className="w-3 h-3 mr-1" fill="none" viewBox="0 0 24 24" strokeWidth={2} stroke="currentColor">
+      <path strokeLinecap="round" strokeLinejoin="round" d="M8.625 12a.375.375 0 1 1-.75 0 .375.375 0 0 1 .75 0Zm0 0H8.25m4.125 0a.375.375 0 1 1-.75 0 .375.375 0 0 1 .75 0Zm0 0H12m4.125 0a.375.375 0 1 1-.75 0 .375.375 0 0 1 .75 0Zm0 0h-.375M21 12c0 4.556-4.03 8.25-9 8.25a9.764 9.764 0 0 1-2.555-.337A5.972 5.972 0 0 1 5.41 20.97a5.969 5.969 0 0 1-.474-.065 4.48 4.48 0 0 0 .978-2.025c.09-.457-.133-.901-.467-1.226C3.93 16.178 3 14.189 3 12c0-4.556 4.03-8.25 9-8.25s9 3.694 9 8.25Z" />
+    </svg>
+  );
+}
+
+function ServiceBadge({ name, role }) {
+  const isBot = role === 'bot';
+  const colorClass = isBot
+    ? 'bg-purple-100 dark:bg-purple-900/40 text-purple-700 dark:text-purple-300'
+    : 'bg-teal-100 dark:bg-teal-900/40 text-teal-700 dark:text-teal-300';
+
+  return (
+    <span className={`inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium ${colorClass}`}>
+      {isBot ? <ChatBubbleIcon /> : <GearIcon />}
+      {name}
+    </span>
+  );
+}
+
 function PresenceBar() {
   const { isAuthenticated } = useAuth();
-  const { viewers } = usePresence();
+  const { viewers, services } = usePresence();
 
   if (!isAuthenticated) return null;
 
-  const otherViewers = viewers.filter(v => v !== 'me');
-  if (otherViewers.length === 0) return null;
+  const otherViewers = viewers.filter(v => v.name !== 'me');
+  const hasViewers = otherViewers.length > 0;
+  const hasServices = services.length > 0;
+
+  if (!hasViewers && !hasServices) return null;
 
   return (
-    <div className="container mx-auto px-2 sm:px-4 pt-3">
-      <div className="bg-white dark:bg-gray-800 rounded-lg shadow-sm border border-gray-200 dark:border-gray-700 px-4 py-2">
-        <div className="flex items-center gap-3">
+    <div className="sticky bottom-0 z-40 flex justify-end px-4 pb-4 pointer-events-none">
+      <div className="pointer-events-auto bg-white dark:bg-gray-800 rounded-lg shadow-sm border border-gray-200 dark:border-gray-700 px-4 py-2 w-fit">
+        <div className="flex flex-col gap-1.5">
+          {hasViewers && (
+            <div className="flex items-center gap-2">
               <span className="text-xs text-gray-500 dark:text-gray-400 uppercase tracking-wider font-medium flex-shrink-0">
-            who is watching
+                who's here?
               </span>
               <div className="flex flex-wrap gap-1.5">
-            {viewers.map((name, i) => (
+                {viewers.map((v, i) => (
                   <span
-                key={`${name}-${i}`}
+                    key={`${v.name}-${i}`}
                     className={`inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium ${
-                  name === 'me'
+                      v.name === 'me'
                         ? 'bg-indigo-100 dark:bg-indigo-900/40 text-indigo-700 dark:text-indigo-300'
                         : 'bg-gray-100 dark:bg-gray-700 text-gray-700 dark:text-gray-300'
                     }`}
                   >
-                {name}
+                    {v.name}
                   </span>
                 ))}
               </div>
             </div>
+          )}
+          {hasServices && (
+            <div className="flex items-center gap-2">
+              <span className="text-xs text-gray-500 dark:text-gray-400 uppercase tracking-wider font-medium flex-shrink-0">
+                connected
+              </span>
+              <div className="flex flex-wrap gap-1.5">
+                {services.map((s, i) => (
+                  <ServiceBadge key={`${s.name}-${i}`} name={s.name} role={s.role} />
+                ))}
+              </div>
+            </div>
+          )}
+        </div>
       </div>
     </div>
   );

frontend/src/config/branding.js

@@ -2,7 +2,7 @@ export const branding = {
   app: {
     name: 'HSO Jackbox Game Picker',
     shortName: 'Jackbox Game Picker',
-    version: '0.6.3 - Fish Tank Edition',
+    version: '0.7.0 - Fixed For Real Edition',
     description: 'Spicing up Hyper Spaceout game nights!',
   },
   meta: {

frontend/src/context/AuthContext.jsx

@@ -15,6 +15,7 @@ export const useAuth = () => {
 export const AuthProvider = ({ children }) => {
   const [token, setToken] = useState(localStorage.getItem('adminToken'));
   const [adminName, setAdminName] = useState(localStorage.getItem('adminName'));
+  const [adminRole, setAdminRole] = useState(localStorage.getItem('adminRole'));
   const [isAuthenticated, setIsAuthenticated] = useState(false);
   const [loading, setLoading] = useState(true);
 
@@ -27,9 +28,12 @@ export const AuthProvider = ({ children }) => {
           });
           setIsAuthenticated(true);
           const name = response.data.user?.name;
+          const role = response.data.user?.role || 'admin';
           if (name) {
             setAdminName(name);
+            setAdminRole(role);
             localStorage.setItem('adminName', name);
+            localStorage.setItem('adminRole', role);
           } else {
             logout();
           }
@@ -47,11 +51,13 @@ export const AuthProvider = ({ children }) => {
   const login = async (key) => {
     try {
       const response = await axios.post('/api/auth/login', { key });
-      const { token: newToken, name } = response.data;
+      const { token: newToken, name, role } = response.data;
       localStorage.setItem('adminToken', newToken);
       localStorage.setItem('adminName', name);
+      localStorage.setItem('adminRole', role || 'admin');
       setToken(newToken);
       setAdminName(name);
+      setAdminRole(role || 'admin');
       setIsAuthenticated(true);
       migratePreferences(name);
       return { success: true };
@@ -66,14 +72,17 @@ export const AuthProvider = ({ children }) => {
   const logout = () => {
     localStorage.removeItem('adminToken');
     localStorage.removeItem('adminName');
+    localStorage.removeItem('adminRole');
     setToken(null);
     setAdminName(null);
+    setAdminRole(null);
     setIsAuthenticated(false);
   };
 
   const value = {
     token,
     adminName,
+    adminRole,
     isAuthenticated,
     loading,
     login,

frontend/src/hooks/usePresence.js

@@ -9,9 +9,15 @@ export function usePresence() {
   const { token, adminName, isAuthenticated } = useAuth();
   const location = useLocation();
   const [viewers, setViewers] = useState([]);
+  const [services, setServices] = useState([]);
   const wsRef = useRef(null);
   const pingRef = useRef(null);
   const reconnectRef = useRef(null);
+  const locationRef = useRef(location.pathname);
+  const adminNameRef = useRef(adminName);
+
+  locationRef.current = location.pathname;
+  adminNameRef.current = adminName;
 
   const getWsUrl = useCallback(() => {
     const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
@@ -32,7 +38,7 @@ export function usePresence() {
       const msg = JSON.parse(event.data);
 
       if (msg.type === 'auth_success') {
-        ws.send(JSON.stringify({ type: 'page_focus', page: location.pathname }));
+        ws.send(JSON.stringify({ type: 'page_focus', page: locationRef.current }));
 
         pingRef.current = setInterval(() => {
           if (ws.readyState === WebSocket.OPEN) {
@@ -42,11 +48,16 @@ export function usePresence() {
       }
 
       if (msg.type === 'presence_update') {
-        const currentPage = location.pathname;
-        const onSamePage = msg.admins
-          .filter(a => a.page === currentPage)
-          .map(a => a.name === adminName ? 'me' : a.name);
-        setViewers(onSamePage);
+        const currentPage = locationRef.current;
+        const currentName = adminNameRef.current;
+        const pageViewers = msg.admins
+          .filter(a => a.role !== 'bot' && a.role !== 'utility' && a.page === currentPage)
+          .map(a => ({ name: a.name === currentName ? 'me' : a.name, role: a.role || 'admin' }));
+        const connectedServices = msg.admins
+          .filter(a => a.role === 'bot' || a.role === 'utility')
+          .map(a => ({ name: a.name, role: a.role }));
+        setViewers(pageViewers);
+        setServices(connectedServices);
       }
     };
 
@@ -58,7 +69,7 @@ export function usePresence() {
     ws.onerror = () => {
       ws.close();
     };
-  }, [isAuthenticated, token, adminName, location.pathname, getWsUrl]);
+  }, [isAuthenticated, token, getWsUrl]);
 
   useEffect(() => {
     connect();
@@ -79,5 +90,5 @@ export function usePresence() {
     }
   }, [location.pathname]);
 
-  return { viewers };
+  return { viewers, services };
 }

frontend/src/pages/History.jsx

@@ -1,9 +1,9 @@
-import React, { useState, useEffect, useCallback, useRef } from 'react';
+import React, { useState, useEffect, useCallback, useRef, useMemo } from 'react';
 import { useNavigate } from 'react-router-dom';
 import { useAuth } from '../context/AuthContext';
 import { useToast } from '../components/Toast';
 import api from '../api/axios';
-import { formatLocalDate, isSunday } from '../utils/dateUtils';
+import { formatDayHeader, formatTimeOnly, getLocalDateKey, isSunday } from '../utils/dateUtils';
 import { prefixKey } from '../utils/adminPrefs';
 
 function History() {
@@ -14,6 +14,9 @@ function History() {
   const [sessions, setSessions] = useState([]);
   const [loading, setLoading] = useState(true);
   const [totalCount, setTotalCount] = useState(0);
+  const [absoluteTotal, setAbsoluteTotal] = useState(0);
+  const [page, setPage] = useState(1);
+  const [prevLastDate, setPrevLastDate] = useState(null);
   const [closingSession, setClosingSession] = useState(null);
 
   const [filter, setFilter] = useState(() => localStorage.getItem(prefixKey(adminName, 'history-filter')) || 'default');
@@ -28,17 +31,26 @@ function History() {
 
   const loadSessions = useCallback(async () => {
     try {
+      const limitNum = limit === 'all' ? null : parseInt(limit, 10);
+      const offset = limitNum ? (page - 1) * limitNum : 0;
+
       const response = await api.get('/sessions', {
-        params: { filter, limit }
+        params: { filter, limit, offset: offset || undefined }
       });
       setSessions(response.data);
       setTotalCount(parseInt(response.headers['x-total-count'] || '0', 10));
+      setAbsoluteTotal(parseInt(response.headers['x-absolute-total'] || '0', 10));
+      setPrevLastDate(response.headers['x-prev-last-date'] || null);
+
+      if (response.data.length === 0 && offset > 0) {
+        setPage(1);
+      }
     } catch (err) {
       console.error('Failed to load sessions', err);
     } finally {
       setLoading(false);
     }
-  }, [filter, limit]);
+  }, [filter, limit, page]);
 
   useEffect(() => {
     loadSessions();
@@ -64,12 +76,14 @@ function History() {
     setFilter(newFilter);
     localStorage.setItem(prefixKey(adminName, 'history-filter'), newFilter);
     setSelectedIds(new Set());
+    setPage(1);
   };
 
   const handleLimitChange = (newLimit) => {
     setLimit(newLimit);
     localStorage.setItem(prefixKey(adminName, 'history-show-limit'), newLimit);
     setSelectedIds(new Set());
+    setPage(1);
   };
 
   const handleCloseSession = async (sessionId, notes) => {
@@ -100,6 +114,7 @@ function History() {
     setSelectMode(false);
     setSelectedIds(new Set());
     setShowBulkDeleteConfirm(false);
+    setPage(1);
   };
 
   const handlePointerDown = (sessionId) => {
@@ -109,6 +124,7 @@ function History() {
       longPressFired.current = true;
       setSelectMode(true);
       setSelectedIds(new Set([sessionId]));
+      setPage(1);
     }, 500);
   };
 
@@ -134,6 +150,23 @@ function History() {
     }
   };
 
+  const groupedSessions = useMemo(() => {
+    const groups = [];
+    let currentKey = null;
+
+    sessions.forEach(session => {
+      const dateKey = getLocalDateKey(session.created_at);
+      if (dateKey !== currentKey) {
+        currentKey = dateKey;
+        groups.push({ dateKey, sessions: [session] });
+      } else {
+        groups[groups.length - 1].sessions.push(session);
+      }
+    });
+
+    return groups;
+  }, [sessions]);
+
   if (loading) {
     return (
       <div className="flex justify-center items-center h-64">
@@ -179,11 +212,14 @@ function History() {
           </div>
           <div className="flex items-center gap-3">
             <span className="text-xs text-gray-400 dark:text-gray-500">
-              {totalCount} session{totalCount !== 1 ? 's' : ''} total
+              {sessions.length === absoluteTotal
+                ? `${absoluteTotal} session${absoluteTotal !== 1 ? 's' : ''} total`
+                : `${sessions.length} visible (${absoluteTotal} total)`
+              }
             </span>
             {isAuthenticated && (
               <button
-                onClick={selectMode ? exitSelectMode : () => setSelectMode(true)}
+                onClick={selectMode ? exitSelectMode : () => { setSelectMode(true); setPage(1); }}
                 className={`px-3 py-1.5 rounded text-sm font-medium transition ${
                   selectMode
                     ? 'bg-indigo-600 dark:bg-indigo-700 text-white hover:bg-indigo-700 dark:hover:bg-indigo-800'
@@ -201,12 +237,41 @@ function History() {
           <p className="text-gray-500 dark:text-gray-400">No sessions found</p>
         ) : (
           <div className="space-y-2">
-            {sessions.map(session => {
+            {groupedSessions.map((group, groupIdx) => {
+              const isSundayGroup = isSunday(group.sessions[0].created_at);
+              const isContinued = groupIdx === 0 && page > 1 && prevLastDate &&
+                getLocalDateKey(prevLastDate) === group.dateKey;
+
+              return (
+                <div key={group.dateKey}>
+                  {/* Day header bar */}
+                  <div className="bg-gray-100 dark:bg-[#1e2a3a] rounded-md px-3.5 py-2 mb-2 flex justify-between items-center border-l-[3px] border-indigo-500">
+                    <div className="flex items-center gap-2">
+                      <span className="text-sm font-semibold text-indigo-700 dark:text-indigo-300">
+                        {formatDayHeader(group.sessions[0].created_at)}
+                      </span>
+                      {isContinued && (
+                        <span className="text-xs text-gray-400 dark:text-gray-500 italic">(continued)</span>
+                      )}
+                    </div>
+                    {!isContinued && (
+                      <div className="flex items-center gap-2">
+                        <span className="text-xs text-gray-500 dark:text-gray-400">
+                          {group.sessions.length} session{group.sessions.length !== 1 ? 's' : ''}
+                        </span>
+                        {isSundayGroup && (
+                          <span className="text-xs font-semibold text-amber-700 dark:text-amber-300">🎲 Game Night</span>
+                        )}
+                      </div>
+                    )}
+                  </div>
+
+                  {/* Session cards under this day */}
+                  <div className="ml-3 space-y-1.5 mb-4">
+                    {group.sessions.map(session => {
                       const isActive = session.is_active === 1;
                       const isSelected = selectedIds.has(session.id);
-              const isSundaySession = isSunday(session.created_at);
                       const isArchived = session.archived === 1;
-              const canSelect = selectMode && !isActive;
 
                       return (
                         <div
@@ -261,11 +326,6 @@ function History() {
                                         Active
                                       </span>
                                     )}
-                            {isSundaySession && (
-                              <span className="bg-amber-100 dark:bg-amber-900 text-amber-800 dark:text-amber-200 text-xs px-2 py-0.5 rounded font-semibold">
-                                🎲 Game Night
-                              </span>
-                            )}
                                     {isArchived && (filter === 'all' || filter === 'archived') && (
                                       <span className="bg-gray-100 dark:bg-gray-700 text-gray-500 dark:text-gray-400 text-xs px-2 py-0.5 rounded">
                                         Archived
@@ -277,10 +337,7 @@ function History() {
                                   </span>
                                 </div>
                                 <div className="text-sm text-gray-500 dark:text-gray-400">
-                          {formatLocalDate(session.created_at)}
-                          {isSundaySession && (
-                            <span className="text-gray-400 dark:text-gray-500"> · Sunday</span>
-                          )}
+                                  {formatTimeOnly(session.created_at)}
                                 </div>
                                 {session.has_notes && session.notes_preview && (
                                   <div className="mt-2 text-sm text-indigo-400 dark:text-indigo-300 bg-indigo-50 dark:bg-indigo-900/20 px-3 py-2 rounded border-l-2 border-indigo-500">
@@ -308,8 +365,48 @@ function History() {
                       );
                     })}
                   </div>
+                </div>
+              );
+            })}
+          </div>
         )}
 
+        {/* Pagination bar */}
+        {limit !== 'all' && (() => {
+          const limitNum = parseInt(limit, 10);
+          const totalPages = Math.ceil(totalCount / limitNum);
+          if (totalPages <= 1) return null;
+          return (
+            <div className="flex justify-center items-center gap-4 py-3 mt-3 border-t border-gray-200 dark:border-gray-700">
+              <button
+                onClick={() => { setPage(p => p - 1); setSelectedIds(new Set()); }}
+                disabled={page <= 1}
+                className={`px-4 py-1.5 rounded-md text-sm font-medium transition ${
+                  page <= 1
+                    ? 'bg-gray-600 dark:bg-gray-700 text-gray-400 dark:text-gray-500 cursor-not-allowed'
+                    : 'bg-indigo-600 text-white hover:bg-indigo-700'
+                }`}
+              >
+                ← Prev
+              </button>
+              <span className="text-sm text-gray-500 dark:text-gray-400">
+                Page {page} of {totalPages}
+              </span>
+              <button
+                onClick={() => { setPage(p => p + 1); setSelectedIds(new Set()); }}
+                disabled={page >= totalPages}
+                className={`px-4 py-1.5 rounded-md text-sm font-medium transition ${
+                  page >= totalPages
+                    ? 'bg-gray-600 dark:bg-gray-700 text-gray-400 dark:text-gray-500 cursor-not-allowed'
+                    : 'bg-indigo-600 text-white hover:bg-indigo-700'
+                }`}
+              >
+                Next →
+              </button>
+            </div>
+          );
+        })()}
+
         {/* Multi-select Action Bar */}
         {selectMode && selectedIds.size > 0 && (
           <div className="sticky bottom-4 mt-4 bg-white dark:bg-gray-800 rounded-lg shadow-lg border border-gray-200 dark:border-gray-700 p-4 flex justify-between items-center">

frontend/src/utils/dateUtils.js

@@ -56,3 +56,44 @@ export function isSunday(sqliteTimestamp) {
   return parseUTCTimestamp(sqliteTimestamp).getDay() === 0;
 }
 
+/**
+ * Get a locale-independent date key for grouping sessions by local calendar day
+ * @param {string} sqliteTimestamp
+ * @returns {string} - e.g., "2026-03-23"
+ */
+export function getLocalDateKey(sqliteTimestamp) {
+  const d = parseUTCTimestamp(sqliteTimestamp);
+  const year = d.getFullYear();
+  const month = String(d.getMonth() + 1).padStart(2, '0');
+  const day = String(d.getDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+/**
+ * Format a SQLite timestamp as a day header string (e.g., "Sunday, Mar 23, 2026")
+ * @param {string} sqliteTimestamp
+ * @returns {string}
+ */
+export function formatDayHeader(sqliteTimestamp) {
+  const d = parseUTCTimestamp(sqliteTimestamp);
+  return d.toLocaleDateString(undefined, {
+    weekday: 'long',
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+  });
+}
+
+/**
+ * Format a SQLite timestamp as a time-only string (e.g., "7:30 PM")
+ * @param {string} sqliteTimestamp
+ * @returns {string}
+ */
+export function formatTimeOnly(sqliteTimestamp) {
+  const d = parseUTCTimestamp(sqliteTimestamp);
+  return d.toLocaleTimeString(undefined, {
+    hour: 'numeric',
+    minute: '2-digit',
+  });
+}
+

tests/api/ecast-shard-client.test.js

@@ -50,6 +50,15 @@ describe('EcastShardClient', () => {
       expect(result.gameStarted).toBe(true);
     });
 
+    test('detects game started from non-Lobby state (Pack 7 Logo)', () => {
+      const roomVal = { state: 'Logo', locale: 'en', platformId: 'PS4' };
+      const result = EcastShardClient.parseRoomEntity(roomVal);
+      expect(result.gameStarted).toBe(true);
+      expect(result.gameState).toBe('Logo');
+      expect(result.lobbyState).toBeNull();
+      expect(result.gameFinished).toBe(false);
+    });
+
     test('detects game finished', () => {
       const roomVal = { state: 'Gameplay', lobbyState: '', gameCanStart: true, gameIsStarting: false, gameFinished: true };
       const result = EcastShardClient.parseRoomEntity(roomVal);
@@ -272,6 +281,26 @@ describe('EcastShardClient', () => {
         expect(startEvents[0].data.players).toEqual(['A', 'B', 'C', 'D']);
       });
 
+      test('broadcasts game.started on state transition to Logo (Pack 7)', () => {
+        client.lobbyState = 'Countdown';
+        client.gameState = 'Lobby';
+        client.gameStarted = false;
+        client.playerCount = 4;
+        client.playerNames = ['A', 'B', 'C', 'D'];
+
+        client.handleEntityUpdate({
+          key: 'room',
+          val: { state: 'Logo', locale: 'en', platformId: 'PS4' },
+          version: 14, from: 1,
+        });
+
+        const startEvents = events.filter(e => e.type === 'game.started');
+        expect(startEvents).toHaveLength(1);
+        expect(startEvents[0].data.playerCount).toBe(4);
+        expect(client.gameState).toBe('Logo');
+        expect(client.gameStarted).toBe(true);
+      });
+
       test('does not broadcast game.started if already started', () => {
         client.gameStarted = true;
         client.gameState = 'Gameplay';
@@ -573,4 +602,80 @@ describe('EcastShardClient', () => {
       expect(events.some(e => e.type === 'room.disconnected' && e.data.reason === 'room_closed')).toBe(true);
     });
   });
+
+  describe('handleRoomLock', () => {
+    test('emits game.started when game has not yet started', () => {
+      const events = [];
+      const client = new EcastShardClient({
+        sessionId: 1,
+        gameId: 5,
+        roomCode: 'TEST',
+        maxPlayers: 8,
+        onEvent: (type, data) => events.push({ type, data }),
+      });
+      client.gameStarted = false;
+      client.playerCount = 4;
+      client.playerNames = ['A', 'B', 'C', 'D'];
+
+      client.handleRoomLock();
+
+      expect(client.gameStarted).toBe(true);
+      const startEvents = events.filter(e => e.type === 'game.started');
+      expect(startEvents).toHaveLength(1);
+      expect(startEvents[0].data.playerCount).toBe(4);
+    });
+
+    test('does not emit game.started if game already started', () => {
+      const events = [];
+      const client = new EcastShardClient({
+        sessionId: 1,
+        gameId: 5,
+        roomCode: 'TEST',
+        maxPlayers: 8,
+        onEvent: (type, data) => events.push({ type, data }),
+      });
+      client.gameStarted = true;
+
+      client.handleRoomLock();
+
+      expect(events.filter(e => e.type === 'game.started')).toHaveLength(0);
+    });
+  });
+
+  describe('handleRoomExit', () => {
+    test('emits game.ended and room.disconnected on room exit', () => {
+      const events = [];
+      const client = new EcastShardClient({
+        sessionId: 1,
+        gameId: 5,
+        roomCode: 'TEST',
+        maxPlayers: 8,
+        onEvent: (type, data) => events.push({ type, data }),
+      });
+      client.playerCount = 3;
+      client.playerNames = ['X', 'Y', 'Z'];
+
+      client.handleRoomExit();
+
+      expect(client.gameFinished).toBe(true);
+      expect(events.some(e => e.type === 'game.ended')).toBe(true);
+      expect(events.some(e => e.type === 'room.disconnected' && e.data.reason === 'room_closed')).toBe(true);
+    });
+
+    test('does not emit events if game already finished', () => {
+      const events = [];
+      const client = new EcastShardClient({
+        sessionId: 1,
+        gameId: 5,
+        roomCode: 'TEST',
+        maxPlayers: 8,
+        onEvent: (type, data) => events.push({ type, data }),
+      });
+      client.gameFinished = true;
+
+      client.handleRoomExit();
+
+      expect(events).toHaveLength(0);
+    });
+  });
 });

tests/api/named-admins.test.js

@@ -26,23 +26,33 @@ describe('load-admins', () => {
 
   test('loads admins from ADMIN_CONFIG_PATH', () => {
     const configPath = writeConfig([
-      { name: 'Alice', key: 'key-a' },
-      { name: 'Bob', key: 'key-b' }
+      { name: 'Alice', role: 'admin', key: 'key-a' },
+      { name: 'Bob', role: 'bot', key: 'key-b' }
     ]);
     process.env.ADMIN_CONFIG_PATH = configPath;
 
     const { findAdminByKey } = require('../../backend/config/load-admins');
-    expect(findAdminByKey('key-a')).toEqual({ name: 'Alice' });
-    expect(findAdminByKey('key-b')).toEqual({ name: 'Bob' });
+    expect(findAdminByKey('key-a')).toEqual({ name: 'Alice', role: 'admin' });
+    expect(findAdminByKey('key-b')).toEqual({ name: 'Bob', role: 'bot' });
     expect(findAdminByKey('wrong')).toBeNull();
   });
 
+  test('defaults role to admin when not specified', () => {
+    const configPath = writeConfig([
+      { name: 'Alice', key: 'key-a' }
+    ]);
+    process.env.ADMIN_CONFIG_PATH = configPath;
+
+    const { findAdminByKey } = require('../../backend/config/load-admins');
+    expect(findAdminByKey('key-a')).toEqual({ name: 'Alice', role: 'admin' });
+  });
+
   test('falls back to ADMIN_KEY when no config file', () => {
     process.env.ADMIN_CONFIG_PATH = path.join(tmpDir, 'nonexistent.json');
     process.env.ADMIN_KEY = 'legacy-key';
 
     const { findAdminByKey } = require('../../backend/config/load-admins');
-    expect(findAdminByKey('legacy-key')).toEqual({ name: 'Admin' });
+    expect(findAdminByKey('legacy-key')).toEqual({ name: 'Admin', role: 'admin' });
     expect(findAdminByKey('wrong')).toBeNull();
   });
 
@@ -91,7 +101,7 @@ describe('POST /api/auth/login — named admins', () => {
     ({ app } = require('../../backend/server'));
   });
 
-  test('login returns admin name in response', async () => {
+  test('login returns admin name and role in response', async () => {
     const res = await request(app)
       .post('/api/auth/login')
       .set('Content-Type', 'application/json')
@@ -99,10 +109,11 @@ describe('POST /api/auth/login — named admins', () => {
 
     expect(res.status).toBe(200);
     expect(res.body.name).toBeDefined();
+    expect(res.body.role).toBe('admin');
     expect(res.body.token).toBeDefined();
   });
 
-  test('verify returns admin name in user object', async () => {
+  test('verify returns admin name and role in user object', async () => {
     const loginRes = await request(app)
       .post('/api/auth/login')
       .set('Content-Type', 'application/json')
@@ -114,6 +125,7 @@ describe('POST /api/auth/login — named admins', () => {
 
     expect(res.status).toBe(200);
     expect(res.body.user.name).toBeDefined();
+    expect(res.body.user.role).toBe('admin');
   });
 
   test('invalid key still returns 401', async () => {
@@ -155,15 +167,15 @@ describe('WebSocket presence', () => {
     server.close(done);
   });
 
-  function makeToken(name) {
-    return jwt.sign({ role: 'admin', name }, process.env.JWT_SECRET, { expiresIn: '1h' });
+  function makeToken(name, role = 'admin') {
+    return jwt.sign({ role, name }, process.env.JWT_SECRET, { expiresIn: '1h' });
   }
 
-  function connectAndAuth(name) {
+  function connectAndAuth(name, role = 'admin') {
     return new Promise((resolve) => {
       const ws = new WebSocket(wsUrl);
       ws.on('open', () => {
-        ws.send(JSON.stringify({ type: 'auth', token: makeToken(name) }));
+        ws.send(JSON.stringify({ type: 'auth', token: makeToken(name, role) }));
       });
       ws.on('message', (data) => {
         const msg = JSON.parse(data.toString());
@@ -187,7 +199,7 @@ describe('WebSocket presence', () => {
     });
   }
 
-  test('page_focus triggers presence_update with admin name and page', async () => {
+  test('page_focus triggers presence_update with admin name, role, and page', async () => {
     const ws1 = await connectAndAuth('Alice');
     const ws2 = await connectAndAuth('Bob');
 
@@ -198,7 +210,7 @@ describe('WebSocket presence', () => {
     const msg = await presencePromise;
     expect(msg.admins).toEqual(
       expect.arrayContaining([
-        expect.objectContaining({ name: 'Alice', page: '/history' })
+        expect.objectContaining({ name: 'Alice', role: 'admin', page: '/history' })
       ])
     );
 
@@ -224,4 +236,61 @@ describe('WebSocket presence', () => {
 
     ws2.close();
   });
+
+  test('bot role appears in presence without page_focus', async () => {
+    const wsAdmin = await connectAndAuth('Alice');
+    const wsBot = await connectAndAuth('ChatBot', 'bot');
+
+    wsAdmin.send(JSON.stringify({ type: 'page_focus', page: '/history' }));
+
+    await new Promise(r => setTimeout(r, 100));
+
+    const presencePromise = waitForMessage(wsAdmin, 'presence_update');
+    wsAdmin.send(JSON.stringify({ type: 'page_focus', page: '/picker' }));
+
+    const msg = await presencePromise;
+    const botEntry = msg.admins.find(a => a.name === 'ChatBot');
+    expect(botEntry).toBeDefined();
+    expect(botEntry.role).toBe('bot');
+    expect(botEntry.page).toBeNull();
+
+    wsAdmin.close();
+    wsBot.close();
+  });
+
+  test('utility role appears in presence without page_focus', async () => {
+    const wsAdmin = await connectAndAuth('Alice');
+    const wsUtil = await connectAndAuth('OBS', 'utility');
+
+    wsAdmin.send(JSON.stringify({ type: 'page_focus', page: '/history' }));
+
+    await new Promise(r => setTimeout(r, 100));
+
+    const presencePromise = waitForMessage(wsAdmin, 'presence_update');
+    wsAdmin.send(JSON.stringify({ type: 'page_focus', page: '/picker' }));
+
+    const msg = await presencePromise;
+    const utilEntry = msg.admins.find(a => a.name === 'OBS');
+    expect(utilEntry).toBeDefined();
+    expect(utilEntry.role).toBe('utility');
+    expect(utilEntry.page).toBeNull();
+
+    wsAdmin.close();
+    wsUtil.close();
+  });
+
+  test('admin without page_focus is NOT in presence', async () => {
+    const ws1 = await connectAndAuth('Alice');
+    const ws2 = await connectAndAuth('Bob');
+
+    const presencePromise = waitForMessage(ws1, 'presence_update');
+    ws1.send(JSON.stringify({ type: 'page_focus', page: '/history' }));
+
+    const msg = await presencePromise;
+    const bobEntry = msg.admins.find(a => a.name === 'Bob');
+    expect(bobEntry).toBeUndefined();
+
+    ws1.close();
+    ws2.close();
+  });
 });

tests/api/session-archive.test.js

@@ -92,6 +92,97 @@ describe('GET /api/sessions — filter and limit', () => {
     expect(res.status).toBe(200);
     expect(res.body).toHaveLength(8);
   });
+
+  test('offset skips the first N sessions', async () => {
+    for (let i = 0; i < 5; i++) {
+      seedSession({ is_active: 0, notes: null });
+    }
+
+    const allRes = await request(app).get('/api/sessions?filter=all&limit=all');
+    const offsetRes = await request(app).get('/api/sessions?filter=all&limit=2&offset=2');
+    expect(offsetRes.status).toBe(200);
+    expect(offsetRes.body).toHaveLength(2);
+    expect(offsetRes.body[0].id).toBe(allRes.body[2].id);
+    expect(offsetRes.body[1].id).toBe(allRes.body[3].id);
+  });
+
+  test('offset defaults to 0 when not provided', async () => {
+    for (let i = 0; i < 3; i++) {
+      seedSession({ is_active: 0, notes: null });
+    }
+
+    const res = await request(app).get('/api/sessions?filter=all&limit=2');
+    expect(res.status).toBe(200);
+    expect(res.body).toHaveLength(2);
+  });
+
+  test('negative offset is clamped to 0', async () => {
+    seedSession({ is_active: 0, notes: null });
+
+    const res = await request(app).get('/api/sessions?filter=all&offset=-5');
+    expect(res.status).toBe(200);
+    expect(res.body).toHaveLength(1);
+  });
+
+  test('non-numeric offset is clamped to 0', async () => {
+    seedSession({ is_active: 0, notes: null });
+
+    const res = await request(app).get('/api/sessions?filter=all&offset=abc');
+    expect(res.status).toBe(200);
+    expect(res.body).toHaveLength(1);
+  });
+
+  test('offset past end returns empty array', async () => {
+    seedSession({ is_active: 0, notes: null });
+
+    const res = await request(app).get('/api/sessions?filter=all&limit=5&offset=100');
+    expect(res.status).toBe(200);
+    expect(res.body).toHaveLength(0);
+    expect(res.headers['x-total-count']).toBe('1');
+  });
+
+  test('X-Prev-Last-Date header is set with correct value when offset > 0', async () => {
+    for (let i = 0; i < 5; i++) {
+      seedSession({ is_active: 0, notes: null });
+    }
+
+    const allRes = await request(app).get('/api/sessions?filter=all&limit=all');
+    const res = await request(app).get('/api/sessions?filter=all&limit=2&offset=2');
+    expect(res.headers['x-prev-last-date']).toBe(allRes.body[1].created_at);
+  });
+
+  test('X-Prev-Last-Date header is absent when offset is 0', async () => {
+    seedSession({ is_active: 0, notes: null });
+
+    const res = await request(app).get('/api/sessions?filter=all&limit=2');
+    expect(res.headers['x-prev-last-date']).toBeUndefined();
+  });
+
+  test('X-Total-Count is unaffected by offset', async () => {
+    for (let i = 0; i < 10; i++) {
+      seedSession({ is_active: 0, notes: null });
+    }
+
+    const res = await request(app).get('/api/sessions?filter=all&limit=3&offset=6');
+    expect(res.headers['x-total-count']).toBe('10');
+    expect(res.body).toHaveLength(3);
+  });
+
+  test('offset works with filter=default', async () => {
+    for (let i = 0; i < 5; i++) {
+      seedSession({ is_active: 0, notes: null });
+    }
+    const archived = seedSession({ is_active: 0, notes: null });
+    require('../helpers/test-utils').db.prepare(
+      'UPDATE sessions SET archived = 1 WHERE id = ?'
+    ).run(archived.id);
+
+    const res = await request(app).get('/api/sessions?filter=default&limit=2&offset=2');
+    expect(res.status).toBe(200);
+    expect(res.body).toHaveLength(2);
+    expect(res.headers['x-total-count']).toBe('5');
+    res.body.forEach(s => expect(s.archived).toBe(0));
+  });
 });
 
 describe('POST /api/sessions/:id/archive', () => {

tests/api/votes-live-e2e.test.js

@@ -163,3 +163,104 @@ describe('POST /api/votes/live -> read-back (end-to-end)', () => {
     expect(sessionVotes.body.votes[0].total_votes).toBe(3);
   });
 });
+
+describe('POST /api/votes/live — ticker voting', () => {
+  let session, tickerGame, sessionGame;
+  const baseTime = '2026-03-15T20:00:00.000Z';
+
+  beforeEach(() => {
+    cleanDb();
+    tickerGame = seedGame({ title: 'Quiplash 3', pack_name: 'Party Pack 7', ticker: 'QPL3' });
+    sessionGame = seedGame({ title: 'Drawful 2', pack_name: 'Party Pack 3' });
+    session = seedSession({ is_active: 1 });
+    seedSessionGame(session.id, sessionGame.id, { status: 'playing', played_at: baseTime });
+  });
+
+  test('vote with valid ticker resolves to the correct game', async () => {
+    const res = await request(app)
+      .post('/api/votes/live')
+      .set('Authorization', getAuthHeader())
+      .set('Content-Type', 'application/json')
+      .send({
+        username: 'viewer1',
+        vote: 'up',
+        timestamp: '2026-03-15T20:05:00.000Z',
+        ticker: 'QPL3',
+      });
+
+    expect(res.status).toBe(200);
+    expect(res.body.game.id).toBe(tickerGame.id);
+    expect(res.body.game.title).toBe('Quiplash 3');
+    expect(res.body.vote.ticker).toBe('QPL3');
+
+    const row = db.prepare(
+      'SELECT * FROM live_votes WHERE game_id = ? AND username = ?'
+    ).get(tickerGame.id, 'viewer1');
+    expect(row).toBeDefined();
+    expect(row.vote_type).toBe(1);
+  });
+
+  test('ticker vote works for a game not in the active session', async () => {
+    const outsideGame = seedGame({ title: 'Fibbage XL', pack_name: 'Party Pack 1', ticker: 'FBXL' });
+
+    const res = await request(app)
+      .post('/api/votes/live')
+      .set('Authorization', getAuthHeader())
+      .set('Content-Type', 'application/json')
+      .send({
+        username: 'viewer1',
+        vote: 'down',
+        timestamp: '2026-03-15T20:05:00.000Z',
+        ticker: 'FBXL',
+      });
+
+    expect(res.status).toBe(200);
+    expect(res.body.game.id).toBe(outsideGame.id);
+    expect(res.body.game.title).toBe('Fibbage XL');
+  });
+
+  test('unknown ticker returns 404', async () => {
+    const res = await request(app)
+      .post('/api/votes/live')
+      .set('Authorization', getAuthHeader())
+      .set('Content-Type', 'application/json')
+      .send({
+        username: 'viewer1',
+        vote: 'up',
+        timestamp: '2026-03-15T20:05:00.000Z',
+        ticker: 'NOPE',
+      });
+
+    expect(res.status).toBe(404);
+    expect(res.body.error).toMatch(/Unknown ticker 'NOPE'/);
+  });
+
+  test('ticker vote updates game scores', async () => {
+    await request(app)
+      .post('/api/votes/live')
+      .set('Authorization', getAuthHeader())
+      .set('Content-Type', 'application/json')
+      .send({
+        username: 'viewer1',
+        vote: 'up',
+        timestamp: '2026-03-15T20:05:00.000Z',
+        ticker: 'QPL3',
+      });
+
+    await request(app)
+      .post('/api/votes/live')
+      .set('Authorization', getAuthHeader())
+      .set('Content-Type', 'application/json')
+      .send({
+        username: 'viewer2',
+        vote: 'down',
+        timestamp: '2026-03-15T20:06:05.000Z',
+        ticker: 'QPL3',
+      });
+
+    const game = db.prepare('SELECT upvotes, downvotes, popularity_score FROM games WHERE id = ?').get(tickerGame.id);
+    expect(game.upvotes).toBe(1);
+    expect(game.downvotes).toBe(1);
+    expect(game.popularity_score).toBe(0);
+  });
+});

tests/helpers/test-utils.js

@@ -34,12 +34,13 @@ function seedGame(overrides = {}) {
     upvotes: 0,
     downvotes: 0,
     popularity_score: 0,
+    ticker: null,
   };
   const g = { ...defaults, ...overrides };
   const result = db.prepare(`
-    INSERT INTO games (pack_name, title, min_players, max_players, length_minutes, has_audience, family_friendly, game_type, enabled, upvotes, downvotes, popularity_score)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(g.pack_name, g.title, g.min_players, g.max_players, g.length_minutes, g.has_audience, g.family_friendly, g.game_type, g.enabled, g.upvotes, g.downvotes, g.popularity_score);
+    INSERT INTO games (pack_name, title, min_players, max_players, length_minutes, has_audience, family_friendly, game_type, enabled, upvotes, downvotes, popularity_score, ticker)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(g.pack_name, g.title, g.min_players, g.max_players, g.length_minutes, g.has_audience, g.family_friendly, g.game_type, g.enabled, g.upvotes, g.downvotes, g.popularity_score, g.ticker);
   return db.prepare('SELECT * FROM games WHERE id = ?').get(result.lastInsertRowid);
 }
 

tools/jackbox-logger.js

@@ -0,0 +1,492 @@
+#!/usr/bin/env node
+
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+
+let WebSocket;
+try {
+  WebSocket = require('ws');
+} catch (_) {
+  try {
+    WebSocket = require('../backend/node_modules/ws');
+  } catch (_2) {
+    console.error('Error: WebSocket library (ws) not found.');
+    console.error('Run: cd backend && npm install');
+    process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ANSI helpers
+// ---------------------------------------------------------------------------
+const C = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+};
+
+// ---------------------------------------------------------------------------
+// CLI argument parsing
+// ---------------------------------------------------------------------------
+function parseArgs() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+    console.log(`
+${C.bold}Jackbox API Logger${C.reset}
+Connects to a Jackbox game room and logs all WebSocket events.
+
+${C.bold}Usage:${C.reset}
+  node tools/jackbox-logger.js <ROOM_CODE> [options]
+
+${C.bold}Options:${C.reset}
+  --role <shard|audience|player>   Connection role (default: shard)
+  --name <name>                    Display name (default: JBLogger)
+  --no-file                        Skip writing to log file
+  --verbose                        Print full JSON to console
+  --help, -h                       Show this help
+
+${C.bold}Examples:${C.reset}
+  node tools/jackbox-logger.js ABCD
+  node tools/jackbox-logger.js ABCD --role audience
+  node tools/jackbox-logger.js ABCD --verbose --no-file
+`);
+    process.exit(0);
+  }
+
+  const opts = {
+    roomCode: null,
+    role: 'shard',
+    name: 'JBLogger',
+    noFile: false,
+    verbose: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--role') {
+      opts.role = args[++i];
+    } else if (arg === '--name') {
+      opts.name = args[++i];
+    } else if (arg === '--no-file') {
+      opts.noFile = true;
+    } else if (arg === '--verbose') {
+      opts.verbose = true;
+    } else if (!arg.startsWith('-') && !opts.roomCode) {
+      opts.roomCode = arg.toUpperCase();
+    }
+  }
+
+  if (!opts.roomCode) {
+    console.error(`${C.red}Error: room code is required${C.reset}`);
+    process.exit(1);
+  }
+
+  if (!['shard', 'audience', 'player'].includes(opts.role)) {
+    console.error(`${C.red}Error: --role must be shard, audience, or player${C.reset}`);
+    process.exit(1);
+  }
+
+  return opts;
+}
+
+// ---------------------------------------------------------------------------
+// REST: fetch room info
+// ---------------------------------------------------------------------------
+function getRoomInfo(roomCode) {
+  return new Promise((resolve, reject) => {
+    https.get(`https://ecast.jackboxgames.com/api/v2/rooms/${roomCode}`, (res) => {
+      let data = '';
+      res.on('data', (chunk) => (data += chunk));
+      res.on('end', () => {
+        try {
+          const json = JSON.parse(data);
+          if (json.ok) resolve(json.body);
+          else reject(new Error(json.error || 'Room not found'));
+        } catch (e) {
+          reject(e);
+        }
+      });
+    }).on('error', reject);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Timestamp
+// ---------------------------------------------------------------------------
+function ts() {
+  return new Date().toISOString().slice(11, 23);
+}
+
+// ---------------------------------------------------------------------------
+// Console summarizer — merges patterns from ws-probe.js and ws-lifecycle-test.js
+// ---------------------------------------------------------------------------
+function summarize(msg) {
+  const r = msg.result || {};
+
+  switch (msg.opcode) {
+    case 'client/welcome': {
+      const hereEntries = r.here ? Object.entries(r.here) : [];
+      const players = hereEntries
+        .filter(([, v]) => v.roles?.player)
+        .map(([id, v]) => `${v.roles.player.name}(${id})`);
+      const entityKeys = r.entities ? Object.keys(r.entities) : [];
+      return (
+        `id=${r.id} reconnect=${r.reconnect} secret=${r.secret}\n` +
+        `           here: ${hereEntries.length} connections [${players.join(', ') || 'no players'}]\n` +
+        `           entities: [${entityKeys.join(', ')}]`
+      );
+    }
+
+    case 'object': {
+      if (r.key === 'room' || r.key === 'bc:room') {
+        const v = r.val || {};
+        return `ROOM state=${v.state} lobby=${v.lobbyState} canStart=${v.gameCanStart} starting=${v.gameIsStarting} finished=${v.gameFinished} v${r.version}`;
+      }
+      if (r.key === 'textDescriptions') {
+        const latest = r.val?.latestDescriptions;
+        if (Array.isArray(latest) && latest.length > 0) {
+          const last = latest[latest.length - 1];
+          return `TEXT "${last.text}" (${last.category}) v${r.version}`;
+        }
+        return `textDescriptions v${r.version}`;
+      }
+      if (r.key?.startsWith('player:')) {
+        const v = r.val || {};
+        return `PLAYER ${r.key} state=${v.state || 'init'} name=${v.playerName || '?'} vip=${v.playerIsVIP} v${r.version}`;
+      }
+      const valKeys = r.val ? Object.keys(r.val).slice(0, 5).join(',') : 'null';
+      return `ENTITY ${r.key} v${r.version} from=${r.from} val=[${valKeys}...]`;
+    }
+
+    case 'client/connected': {
+      const roleName = r.roles ? Object.keys(r.roles)[0] : r.role;
+      const playerName = r.roles?.player?.name || r.name || '';
+      return `id=${r.id} userId=${r.userId} role=${roleName} name=${playerName}`;
+    }
+
+    case 'client/disconnected': {
+      const roleName = r.roles ? Object.keys(r.roles)[0] : r.role;
+      return `id=${r.id} role=${roleName}`;
+    }
+
+    case 'client/kicked':
+      return JSON.stringify(r).slice(0, 200);
+
+    case 'room/lock':
+      return 'room locked (game starting)';
+
+    case 'room/exit':
+      return 'room closed';
+
+    case 'room/get-audience':
+      return `audience connections=${r.connections}`;
+
+    case 'error':
+      return `code=${r.code}: ${r.msg}`;
+
+    case 'ok':
+      return `seq response`;
+
+    default:
+      return JSON.stringify(r).slice(0, 200);
+  }
+}
+
+function opcodeColor(opcode) {
+  if (opcode === 'client/welcome') return C.green;
+  if (opcode === 'error') return C.red;
+  if (opcode === 'client/connected') return C.cyan;
+  if (opcode === 'client/disconnected') return C.yellow;
+  if (opcode === 'room/lock' || opcode === 'room/exit') return C.magenta;
+  if (opcode === 'object') return C.white;
+  return C.dim;
+}
+
+// ---------------------------------------------------------------------------
+// File logger
+// ---------------------------------------------------------------------------
+class FileLogger {
+  constructor(roomCode) {
+    const logsDir = path.join(__dirname, '..', 'logs');
+    fs.mkdirSync(logsDir, { recursive: true });
+
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    this.filePath = path.join(logsDir, `jackbox-${roomCode}-${timestamp}.jsonl`);
+    this.stream = fs.createWriteStream(this.filePath, { flags: 'a' });
+  }
+
+  write(entry) {
+    this.stream.write(JSON.stringify(entry) + '\n');
+  }
+
+  close() {
+    this.stream.end();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main logger
+// ---------------------------------------------------------------------------
+async function main() {
+  const opts = parseArgs();
+  const { roomCode, role, name, noFile, verbose } = opts;
+
+  console.log(`${C.bold}Jackbox API Logger${C.reset}`);
+  console.log(`${C.cyan}Room:${C.reset} ${roomCode}  ${C.cyan}Role:${C.reset} ${role}  ${C.cyan}Name:${C.reset} ${name}`);
+  console.log();
+
+  // Fetch room info
+  console.log(`${C.dim}[${ts()}]${C.reset} Fetching room info...`);
+  let roomInfo;
+  try {
+    roomInfo = await getRoomInfo(roomCode);
+  } catch (e) {
+    console.error(`${C.red}Failed to fetch room info: ${e.message}${C.reset}`);
+    process.exit(1);
+  }
+
+  console.log(`${C.dim}[${ts()}]${C.reset} ${C.green}Room found${C.reset}`);
+  console.log(`  ${C.cyan}Game:${C.reset}       ${roomInfo.appTag}`);
+  console.log(`  ${C.cyan}Host:${C.reset}       ${roomInfo.host}`);
+  console.log(`  ${C.cyan}Players:${C.reset}    max ${roomInfo.maxPlayers}`);
+  console.log(`  ${C.cyan}Locked:${C.reset}     ${roomInfo.locked}`);
+  console.log(`  ${C.cyan}Full:${C.reset}       ${roomInfo.full}`);
+  console.log(`  ${C.cyan}Audience:${C.reset}   ${roomInfo.audienceEnabled ? 'enabled' : 'disabled'}`);
+  console.log();
+
+  // File logger
+  let fileLogger = null;
+  if (!noFile) {
+    fileLogger = new FileLogger(roomCode);
+    console.log(`${C.dim}[${ts()}]${C.reset} Logging to ${C.bold}${fileLogger.filePath}${C.reset}`);
+    fileLogger.write({
+      ts: new Date().toISOString(),
+      direction: 'meta',
+      type: 'session_start',
+      roomCode,
+      role,
+      name,
+      host: roomInfo.host,
+      appTag: roomInfo.appTag,
+      maxPlayers: roomInfo.maxPlayers,
+      locked: roomInfo.locked,
+      full: roomInfo.full,
+      audienceEnabled: roomInfo.audienceEnabled,
+    });
+  }
+
+  // State for reconnection
+  let shardId = null;
+  let secret = null;
+  let msgCount = 0;
+  let reconnecting = false;
+  let manuallyStopped = false;
+  const startTime = Date.now();
+
+  function buildWsUrl(reconnect) {
+    if (role === 'audience') {
+      return `wss://${roomInfo.audienceHost || roomInfo.host}/api/v2/audience/${roomCode}/play`;
+    }
+    const base = `wss://${roomInfo.host}/api/v2/rooms/${roomCode}/play`;
+    if (reconnect && secret && shardId) {
+      return `${base}?role=${role}&name=${encodeURIComponent(name)}&format=json&secret=${secret}&id=${shardId}`;
+    }
+    return `${base}?role=${role}&name=${encodeURIComponent(name)}&userId=${name}-${Date.now()}&format=json`;
+  }
+
+  function connect(isReconnect) {
+    const url = buildWsUrl(isReconnect);
+    console.log(`${C.dim}[${ts()}]${C.reset} ${isReconnect ? 'Reconnecting' : 'Connecting'}: ${C.dim}${url}${C.reset}`);
+
+    const ws = new WebSocket(url, ['ecast-v0'], {
+      headers: {
+        Origin: 'https://jackbox.tv',
+        'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
+      },
+      handshakeTimeout: 10000,
+    });
+
+    ws.on('open', () => {
+      console.log(`${C.dim}[${ts()}]${C.reset} ${C.green}${C.bold}CONNECTED${C.reset}`);
+      console.log();
+    });
+
+    ws.on('message', (raw) => {
+      msgCount++;
+      try {
+        const msg = JSON.parse(raw.toString());
+
+        // Capture credentials from welcome for reconnection
+        if (msg.opcode === 'client/welcome' && msg.result) {
+          shardId = msg.result.id;
+          secret = msg.result.secret;
+        }
+
+        // Console output
+        const color = opcodeColor(msg.opcode);
+        const summary = summarize(msg);
+        console.log(
+          `${C.dim}[${ts()}]${C.reset} ${C.dim}#${msgCount} pc:${msg.pc ?? '-'}${C.reset} ${color}${C.bold}${msg.opcode}${C.reset} ${summary}`
+        );
+        if (verbose) {
+          console.log(JSON.stringify(msg, null, 2));
+        }
+
+        // File output
+        if (fileLogger) {
+          fileLogger.write({
+            ts: new Date().toISOString(),
+            direction: 'recv',
+            msgNum: msgCount,
+            pc: msg.pc,
+            opcode: msg.opcode,
+            raw: msg,
+          });
+        }
+      } catch (e) {
+        console.log(`${C.dim}[${ts()}]${C.reset} ${C.yellow}UNPARSEABLE${C.reset} ${raw.toString().slice(0, 200)}`);
+        if (fileLogger) {
+          fileLogger.write({
+            ts: new Date().toISOString(),
+            direction: 'recv',
+            msgNum: msgCount,
+            parseError: true,
+            raw: raw.toString().slice(0, 2000),
+          });
+        }
+      }
+    });
+
+    ws.on('close', (code, reason) => {
+      console.log(`${C.dim}[${ts()}]${C.reset} ${C.yellow}DISCONNECTED${C.reset} code=${code} reason=${reason}`);
+      if (fileLogger) {
+        fileLogger.write({
+          ts: new Date().toISOString(),
+          direction: 'meta',
+          type: 'disconnected',
+          code,
+          reason: reason?.toString(),
+        });
+      }
+      if (!manuallyStopped && secret != null) {
+        reconnectWithBackoff(ws);
+      }
+    });
+
+    ws.on('error', (err) => {
+      console.error(`${C.dim}[${ts()}]${C.reset} ${C.red}WS ERROR: ${err.message}${C.reset}`);
+      if (fileLogger) {
+        fileLogger.write({
+          ts: new Date().toISOString(),
+          direction: 'meta',
+          type: 'error',
+          message: err.message,
+        });
+      }
+    });
+
+    // SIGINT handler
+    const onSigint = () => {
+      manuallyStopped = true;
+      const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+      console.log();
+      console.log(`${C.bold}--- Session Summary ---${C.reset}`);
+      console.log(`  ${C.cyan}Messages:${C.reset}  ${msgCount}`);
+      console.log(`  ${C.cyan}Duration:${C.reset}  ${elapsed}s`);
+      if (fileLogger) {
+        console.log(`  ${C.cyan}Log file:${C.reset}  ${fileLogger.filePath}`);
+        fileLogger.write({
+          ts: new Date().toISOString(),
+          direction: 'meta',
+          type: 'session_end',
+          msgCount,
+          durationMs: Date.now() - startTime,
+        });
+        fileLogger.close();
+      }
+      console.log();
+      try {
+        ws.close(1000, 'Logger stopped');
+      } catch (_) {}
+      setTimeout(() => process.exit(0), 500);
+    };
+
+    process.removeAllListeners('SIGINT');
+    process.on('SIGINT', onSigint);
+
+    return ws;
+  }
+
+  async function reconnectWithBackoff() {
+    if (reconnecting || manuallyStopped) return;
+    reconnecting = true;
+    const delays = [2000, 4000, 8000];
+
+    for (let i = 0; i < delays.length; i++) {
+      console.log(`${C.dim}[${ts()}]${C.reset} ${C.yellow}Reconnect attempt ${i + 1}/${delays.length} in ${delays[i] / 1000}s...${C.reset}`);
+      await new Promise((r) => setTimeout(r, delays[i]));
+
+      if (manuallyStopped) {
+        reconnecting = false;
+        return;
+      }
+
+      try {
+        const freshRoom = await getRoomInfo(roomCode);
+        if (!freshRoom) {
+          console.log(`${C.dim}[${ts()}]${C.reset} ${C.red}Room no longer exists${C.reset}`);
+          reconnecting = false;
+          shutdown();
+          return;
+        }
+        roomInfo.host = freshRoom.host;
+        connect(true);
+        reconnecting = false;
+        return;
+      } catch (e) {
+        console.error(`${C.dim}[${ts()}]${C.reset} ${C.red}Reconnect attempt ${i + 1} failed: ${e.message}${C.reset}`);
+      }
+    }
+
+    console.error(`${C.dim}[${ts()}]${C.reset} ${C.red}${C.bold}All reconnect attempts failed. Exiting.${C.reset}`);
+    reconnecting = false;
+    shutdown();
+  }
+
+  function shutdown() {
+    const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+    console.log();
+    console.log(`${C.bold}--- Session Summary ---${C.reset}`);
+    console.log(`  ${C.cyan}Messages:${C.reset}  ${msgCount}`);
+    console.log(`  ${C.cyan}Duration:${C.reset}  ${elapsed}s`);
+    if (fileLogger) {
+      console.log(`  ${C.cyan}Log file:${C.reset}  ${fileLogger.filePath}`);
+      fileLogger.write({
+        ts: new Date().toISOString(),
+        direction: 'meta',
+        type: 'session_end',
+        msgCount,
+        durationMs: Date.now() - startTime,
+      });
+      fileLogger.close();
+    }
+    console.log();
+    process.exit(1);
+  }
+
+  connect(false);
+}
+
+main().catch((e) => {
+  console.error(`${C.red}Fatal: ${e.message}${C.reset}`);
+  process.exit(1);
+});