# 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
