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:

   [
     {
       "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):

[
  {
    "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.