docs: bookmark WebSocket subscription issue for later resolution

.planning/JAMTRACK_WEBSOCKET_TODO.md

@@ -0,0 +1,73 @@
+# JamTrack WebSocket Subscription Issue - TO BE RESOLVED
+
+## Status
+**Paused** - 2026-01-15
+
+## Problem
+WebSocket subscription for JamTrack packaging progress is implemented but not yet working. When clicking play on a JamTrack, the packaging flow times out after 60 seconds without receiving progress updates.
+
+## What Was Implemented
+✅ Native WebSocket subscribe/unsubscribe in React (useJamServer.js)
+✅ SUBSCRIPTION_MESSAGE handler in useSessionWebSocket.js
+✅ Redux state updates for packaging progress (mediaSlice.js)
+✅ Proper parameter passing (jamServer) through all components
+
+## Current Error
+```
+[JamTrack] Subscribing to packaging notifications for package 23b10fa0-...
+[JamTrack] Waiting for package to be signed by server...
+[JamTrack] Play error: Packaging timeout after 60 seconds
+```
+
+No WebSocket messages are being received during packaging.
+
+## Recent Commits
+- `ed6d006d1` - fix(05-jamtrack): pass jamServer to all loadJamTrack calls
+- `965dc2d70` - fix(05-jamtrack): implement native WebSocket subscriptions in React
+- `12527c4eb` - fix(05-jamtrack): subscribe to WebSocket packaging notifications
+- `efdd8fe95` - fix(05-jamtrack): pass mixdown ID and package attributes to enqueue endpoint
+
+## Next Steps (When Resuming)
+1. **Verify WebSocket connection is active** when player opens
+   - Check `ws.current.readyState === WebSocket.OPEN`
+   - Add connection status indicator
+
+2. **Test SUBSCRIPTION_MESSAGE routing**
+   - Add logging to WebSocket onmessage handler in useJamServer.js
+   - Verify SUBSCRIBE message is sent to server
+   - Verify server acknowledges subscription
+   - Verify SUBSCRIPTION_MESSAGE arrives from server
+
+3. **Backend verification**
+   - Check if `JamTrackMixdownPackage.after_save` hook fires
+   - Check if `SubscriptionMessage.mixdown_signing_job_change(self)` is called
+   - Check WebSocket gateway routing for SUBSCRIPTION_MESSAGE
+
+4. **Alternative approach if WebSocket fails**
+   - Implement polling fallback: GET `/api/mixdown_packages/:id` every 2 seconds
+   - Check `signing_state` field directly from API
+   - Stop polling when `signing_state === 'SIGNED'`
+
+## Files Involved
+- `jam-ui/src/hooks/useJamServer.js` - Subscribe/unsubscribe methods
+- `jam-ui/src/hooks/useSessionWebSocket.js` - SUBSCRIPTION_MESSAGE handler
+- `jam-ui/src/store/features/mediaSlice.js` - Packaging state machine
+- `jam-ui/src/components/client/JKSessionJamTrackPlayer.js` - Player component
+- `ruby/lib/jam_ruby/models/jam_track_mixdown_package.rb` - Backend packaging (lines 56-63)
+- `web/app/controllers/api_jam_track_mixdowns_controller.rb` - Enqueue endpoint
+
+## API Endpoints
+- `POST /api/mixdowns/:id/enqueue` - Trigger packaging (working ✅)
+- WebSocket: `SUBSCRIBE` message with type='mixdown', id=packageId
+- WebSocket: Expecting `SUBSCRIPTION_MESSAGE` with packaging progress
+
+## Testing Notes
+- Test JamTrack: "db" by Midnight Oil
+- Mixdown ID: `5f24403f-3cfa-44f5-b36e-52b2c3c66af8`
+- Package ID: `23b10fa0-195d-4ad5-a5a7-2cba6b8c1451`
+- Sample rate: 48kHz
+- File type: mp3, encrypt_type: null
+
+---
+
+**Resume work by:** Running `/gsd:progress` or reading this file