wow, chrome-extension MUCH improved - websockets

chrome-extension/DEBUG.md

@@ -0,0 +1,179 @@
+# Chrome Extension Debugging Guide
+
+## Version 3.0.2 - Apollo Client Detection Issues
+
+If the extension can't find Apollo Client, follow these steps to diagnose the issue:
+
+### Step 1: Reload Extension and Page
+
+1. Go to `chrome://extensions/`
+2. Find "Jackbox Chat Tracker for Kosmi"
+3. Click the reload icon (circular arrow)
+4. Navigate to Kosmi room: `https://app.kosmi.io/room/@yourroomname`
+5. Refresh the page (Ctrl+R or Cmd+R)
+
+### Step 2: Run Debug Function
+
+1. Open Chrome DevTools (F12)
+2. Go to Console tab
+3. Wait 5-10 seconds after page load (let Kosmi fully initialize)
+4. Type: `window.debugJackboxTracker()`
+5. Press Enter
+
+### Step 3: Analyze Output
+
+The debug function will show:
+
+#### If Apollo Client is Found ✓
+```
+=== Jackbox Chat Tracker Debug ===
+✓ Apollo Client found!
+Apollo Client: ApolloClient {...}
+Apollo Client keys: ['cache', 'link', 'queryManager', ...]
+Apollo Link: {...}
+Apollo Link keys: ['client', ...]
+GraphQL client: {...}
+GraphQL client keys: ['on', 'subscribe', 'iterate', 'dispose', 'terminate']
+=== End Debug ===
+```
+
+**Action:** Try clicking "Start Tracking" in the extension popup. It should work now!
+
+#### If Apollo Client is NOT Found ✗
+```
+=== Jackbox Chat Tracker Debug ===
+✗ Apollo Client not found
+Checking for window.__APOLLO_CLIENT__: undefined
+Window keys that might be relevant: ['__someOtherKey__', ...]
+=== End Debug ===
+```
+
+**Action:** Copy the "Window keys that might be relevant" list and report it to the developer.
+
+### Step 4: Check Timing
+
+If Apollo Client is not found immediately, wait longer and try again:
+
+```javascript
+// Run debug after 10 seconds
+setTimeout(() => window.debugJackboxTracker(), 10000);
+```
+
+### Step 5: Manual Apollo Client Search
+
+If still not working, manually check for Apollo Client:
+
+```javascript
+// Check if it exists
+console.log('window.__APOLLO_CLIENT__:', window.__APOLLO_CLIENT__);
+
+// Search all window properties
+Object.keys(window).forEach(key => {
+  if (key.includes('apollo') || key.includes('Apollo')) {
+    console.log('Found Apollo-related key:', key, window[key]);
+  }
+});
+
+// Check if it's in a different location
+console.log('document.__APOLLO_CLIENT__:', document.__APOLLO_CLIENT__);
+```
+
+### Common Issues
+
+#### Issue: "Apollo Client not found after 15 attempts"
+
+**Causes:**
+1. Kosmi changed their client variable name
+2. Apollo Client loads after 15 seconds
+3. You're not on a Kosmi room page
+
+**Solutions:**
+1. Wait longer (30+ seconds) and run `window.debugJackboxTracker()`
+2. Make sure you're on `app.kosmi.io/room/...` not just `app.kosmi.io`
+3. Try a different room
+4. Check if Kosmi updated their code
+
+#### Issue: "GraphQL client not found in Apollo Client"
+
+**Cause:** Apollo Client structure changed
+
+**Solution:**
+1. Run debug function to see Apollo Client structure
+2. Look for the WebSocket client in a different location
+3. Report the structure to the developer
+
+### Reporting Issues
+
+When reporting Apollo Client not found, include:
+
+1. **Console Output:**
+   ```
+   // Copy ALL of this:
+   window.debugJackboxTracker()
+   ```
+
+2. **Window Keys:**
+   ```javascript
+   // Copy this:
+   Object.keys(window).filter(k => k.startsWith('__') || k.includes('apollo'))
+   ```
+
+3. **Kosmi URL:**
+   - Full URL of the room (redact room name if private)
+
+4. **Browser Version:**
+   - Chrome version (chrome://version/)
+
+5. **Extension Version:**
+   - Check `chrome://extensions/` → "Jackbox Chat Tracker" → version number
+
+---
+
+## Advanced Debugging
+
+### Hook Detection
+
+Check if the WebSocket hook is working:
+
+```javascript
+// This should exist after successfully starting tracking
+console.log('GraphQL Client:', window.__APOLLO_CLIENT__?.link?.client);
+
+// Try manually hooking
+const client = window.__APOLLO_CLIENT__.link.client;
+client.on('message', (data) => {
+  console.log('MANUAL HOOK - Message:', data);
+});
+```
+
+### Message Interception
+
+Test if messages are flowing:
+
+```javascript
+// Send a test message in Kosmi chat: "test thisgame++"
+// Check console for:
+// [Jackbox Chat Tracker] New message: {...}
+// [Jackbox Chat Tracker] ✓ Vote detected!
+```
+
+---
+
+## Version History
+
+### v3.0.2
+- Added multiple Apollo Client detection strategies
+- Added `window.debugJackboxTracker()` debug function
+- Extended search to all window/document properties
+- Increased retry limit to 15 attempts (15-30 seconds)
+- Added detailed error logging
+
+### v3.0.1
+- Fixed infinite loop on page load
+- Disabled auto-start tracking
+- Added retry limit
+
+### v3.0.0
+- Initial WebSocket API implementation
+- Replaced DOM parsing with GraphQL subscriptions
+