jackboxpartypack-gamepicker/chrome-extension/README.md

# Jackbox Chat Tracker Chrome Extension

A Chrome extension for tracking Jackbox game votes (`thisgame++` and `thisgame--`) from Kosmi chat.

## Features

- ✅ Tracks `thisgame++` and `thisgame--` votes in Kosmi chat
- ✅ Records username, full message, and UTC timestamp
- ✅ Case-insensitive matching (works with `THISGAME++`, `ThisGame--`, etc.)
- ✅ Matches votes anywhere in the message
- ✅ Exports data as JSON in the format expected by the Jackbox Game Picker app
- ✅ Real-time vote tracking with live updates
- ✅ Simple, intuitive interface

## Installation

1. Open Chrome and navigate to `chrome://extensions/`
2. Enable "Developer mode" in the top right
3. Click "Load unpacked"
4. Select the `chrome-extension` folder
5. The extension is now installed!

## Usage

### Starting a Tracking Session

1. Navigate to a Kosmi room: `https://app.kosmi.io/room/...`
2. Click the extension icon in your browser toolbar
3. Click "Start Tracking"
4. The extension will now monitor chat for votes

### Viewing Votes

- The popup shows all recorded votes in real-time
- Each vote displays:
  - Username
  - Full message text
  - Timestamp (in your local timezone)
  - Vote type (positive/negative indicated by color)

### Exporting Data

1. Click "Export JSON" to download votes
2. The file format matches the Jackbox Game Picker import format:
   ```json
   [
     {
       "username": "Alice",
       "message": "thisgame++",
       "timestamp": "2025-10-30T20:15:00Z"
     }
   ]
   ```
3. Import this JSON file into the Jackbox Game Picker app

### Resetting Votes

- Click "Reset Votes" to clear all recorded votes
- Confirmation dialog prevents accidental resets

## How It Works

The extension hooks into Kosmi's GraphQL WebSocket API (`wss://engine.kosmi.io/gql-ws`) to monitor real-time chat messages. This is much more reliable than DOM parsing!

When a message is received, the extension:
1. Checks if it contains `thisgame++` or `thisgame--` (case-insensitive)
2. Extracts the **username** from the GraphQL response
3. Extracts the **full message text**
4. Records the **UTC timestamp**

### Why WebSocket?

Previous versions used DOM parsing (MutationObserver), which was fragile and prone to breaking when Kosmi updated their UI. Version 3.0.0 uses Kosmi's own GraphQL API, which is:
- ✅ More reliable (API is stable)
- ✅ Faster (no DOM traversal needed)
- ✅ More accurate (username is always correct)
- ✅ Less CPU intensive (no constant DOM monitoring)

## Vote Format

**Input** (Kosmi chat):
```
Alice: This is great! thisgame++
Bob: thisgame-- not my favorite
Charlie: THISGAME++ love it!
```

**Output** (JSON export):
```json
[
  {
    "username": "Alice",
    "message": "This is great! thisgame++",
    "timestamp": "2025-10-30T20:15:00.123Z"
  },
  {
    "username": "Bob",
    "message": "thisgame-- not my favorite",
    "timestamp": "2025-10-30T20:15:15.456Z"
  },
  {
    "username": "Charlie",
    "message": "THISGAME++ love it!",
    "timestamp": "2025-10-30T20:15:30.789Z"
  }
]
```

## Technical Details

### Files

- `manifest.json`: Extension configuration
- `content.js`: Monitors Kosmi chat and records votes
- `popup.html`: Extension popup interface
- `popup.js`: Popup logic and controls
- `popup.css`: Popup styling
- `icons/`: Extension icons

### Permissions

- `storage`: Save votes locally
- `activeTab`: Access current Kosmi tab
- `downloads`: Export JSON files
- `https://app.kosmi.io/*`: Access Kosmi chat

### Data Storage

- Votes are stored locally using Chrome's `storage.local` API
- Data persists across browser sessions
- No data is sent to external servers

## Changelog

### Version 3.0.1 (Current)

- 🐛 Fixed infinite retry loop when Apollo Client not found
- 🐛 Disabled auto-start on page load (user must manually start tracking)
- ✅ Added retry limit (10 attempts max, then gives up gracefully)
- ✅ Only sets `isTracking = true` after successfully hooking into Apollo Client
- ✅ Better error messages with attempt counter

### Version 3.0.0

- 🎉 **Complete rewrite using GraphQL WebSocket API**
- ✅ Hooks directly into Kosmi's Apollo Client
- ✅ 100% reliable message and username extraction
- ✅ No more DOM parsing or MutationObserver
- ✅ Lightweight and performant
- ✅ Future-proof (API-based, not DOM-based)
- ❌ Removed fragile DOM traversal code
- ❌ No more "Unknown" usernames

### Version 2.0.2

- 🐛 Fixed sidebar responsiveness with polling updates
- 🐛 Fixed MutationObserver not detecting new messages
- 🐛 Suppressed "Could not establish connection" errors
- ✅ Added extensive debug logging for troubleshooting
- ✅ Observer now properly disconnects and reconnects on start

### Version 2.0.1

- 🐛 Fixed duplicate vote counting issue
- 🐛 Improved username extraction with multiple fallback strategies
- ✅ Re-added sidebar panel support

### Version 2.0.0

- ✅ Simplified to only track `thisgame++` and `thisgame--`
- ✅ Removed complex game alias system
- ✅ Captures full message context
- ✅ UTC timestamp recording
- ✅ New JSON export format
- ✅ Improved UI with vote preview
- ✅ Case-insensitive matching

## Troubleshooting

**Extension not detecting votes:**
1. Make sure you're on a Kosmi room page (`app.kosmi.io/room/...`)
2. Click "Stop Tracking" then "Start Tracking" to reset
3. Check browser console for errors (F12 → Console tab)

**Votes not saving:**
1. Check Chrome's storage permissions
2. Try resetting votes and starting fresh
3. Ensure extension has permission to access Kosmi

**Export not working:**
1. Check Chrome's download permissions
2. Ensure popup blockers aren't blocking downloads
3. Try clicking "Export JSON" again

**Extension not loading:**
1. Make sure you've reloaded the extension after updating files
2. Go to `chrome://extensions/`, find "Jackbox Chat Tracker", and click the reload icon
3. Refresh the Kosmi room page after reloading the extension

**Apollo Client not found:**
1. The extension needs a moment after page load to find Apollo Client
2. Wait 2-3 seconds after the page loads, then click "Start Tracking"
3. Check console for "Apollo Client not found!" error
4. If error persists, Kosmi may have changed their client framework

## Support

For issues or questions, please file an issue in the main repository.

## License

Same as main Jackbox Game Picker project.