docs(gsd): plan Phase 4 - JamTrack Research & Design

Creates 2 execution plans for Phase 4: - Plan 04-01: Document legacy implementation, jamClient API, React patterns - Plan 04-02: Design React architecture, Redux state, Phase 5 roadmap Phase 4 planning included comprehensive codebase discovery: - Legacy jQuery/CoffeeScript implementation patterns - jamClient API methods (15+ JamTrack-specific) - Modern React patterns in jam-ui - Redux state structure and data flow Updates ROADMAP (2 plans) and STATE (ready for execution).
2026-01-14 20:00:30 +05:30 · 2026-01-14 20:00:30 +05:30 · 794600678e
parent 197d91e9af
commit 794600678e
4 changed files with 723 additions and 9 deletions
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@ -60,10 +60,11 @@ Plans:
 **Depends on**: Phase 3
 **Research**: Likely (exploring legacy jQuery/CoffeeScript implementation)
 **Research topics**: Legacy JamTrack dialog patterns, mixdown selection UI, CoffeeScript React integration patterns, jamClient JamTrack API methods
-**Plans**: TBD
+**Plans**: 2 plans

 Plans:
- [ ] TBD during phase planning
+- [ ] 04-01: Document legacy implementation, jamClient API, and React patterns
+- [ ] 04-02: Design React architecture, Redux state, and Phase 5 roadmap

 ### Phase 5: JamTrack Implementation
 **Goal**: Build JamTrack player with file opening, mixdown selection, and playback controls
@ -103,7 +104,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7
 | 1. Backing Track Playback Monitoring | 1/1 | Complete | 2026-01-13 |
 | 2. Backing Track Seek Controls | 1/1 | Complete | 2026-01-14 |
 | 3. Backing Track Finalization | 3/3 | Complete | 2026-01-14 |
-| 4. JamTrack Research & Design | 0/TBD | Not started | - |
+| 4. JamTrack Research & Design | 0/2 | Planned | - |
 | 5. JamTrack Implementation | 0/TBD | Not started | - |
 | 6. Metronome Research & Design | 0/TBD | Not started | - |
 | 7. Metronome Implementation | 0/TBD | Not started | - |
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@ -9,10 +9,10 @@ See: .planning/PROJECT.md (updated 2026-01-13)

 ## Current Position

-Phase: 3 of 7 (Backing Track Finalization) - COMPLETE
-Plan: 3 of 3 in current phase
-Status: Phase 3 complete with known issues documented
-Last activity: 2026-01-14 — Completed Phase 3: Backing Track Finalization
+Phase: 4 of 7 (JamTrack Research & Design) - PLANNED
+Plan: 0 of 2 in current phase
+Status: Phase 4 planning complete, ready for execution
+Last activity: 2026-01-14 — Planned Phase 4: 2 plans created

 Progress: ████████░░ 43%

@ -94,7 +94,7 @@ None yet.
 ## Session Continuity

 Last session: 2026-01-14
-Stopped at: Completed Phase 3 (Backing Track Finalization) with 3 known issues documented
+Stopped at: Completed Phase 4 planning with 2 plans created
 Resume file: None

-**Next:** Phase 4 (JamTrack Research & Design) - Ready for planning
+**Next:** Phase 4 Plan 1 (Document Legacy Implementation) - Ready for execution
--- a/.planning/phases/04-jamtrack-research-design/04-01-PLAN.md
+++ b/.planning/phases/04-jamtrack-research-design/04-01-PLAN.md
@ -0,0 +1,283 @@
+# Phase 4 Plan 1: Document Legacy JamTrack Implementation
+
+<objective>
+Document legacy JamTrack patterns, jamClient API, and React integration patterns to serve as reference for Phase 5 implementation.
+</objective>
+
+<execution_context>
+@.planning/STATE.md
+@.planning/ROADMAP.md
+@.planning/phases/03-backing-track-finalization/03-03-SUMMARY.md
+@web/app/assets/javascripts/dialog/openJamTrackDialog.js
+@web/app/assets/javascripts/download_jamtrack.js.coffee
+@web/app/assets/javascripts/react-components/stores/JamTrackStore.js.coffee
+@web/app/assets/javascripts/bridge_api.es6
+@jam-ui/src/components/client/JKSessionBackingTrackPlayer.js
+@jam-ui/src/hooks/useMediaActions.js
+</execution_context>
+
+<context>
+## Background
+
+Phase 3 completed the Backing Track player implementation with established patterns:
+- Redux-based state management (mediaSlice, sessionUISlice)
+- jamClient async integration with error handling
+- WebSocket real-time updates (MIXER_CHANGES)
+- Modal/popup rendering duality
+- Visibility-aware polling for playback monitoring
+
+## Discovery Completed
+
+Comprehensive exploration has identified:
+
+**Legacy Implementation:**
+- jQuery dialog for JamTrack selection with search/pagination
+- CoffeeScript state machine for download/synchronization (8 states)
+- Reflux stores for JamTrack and mixdown management
+- jamClient API with 15+ JamTrack-specific methods
+
+**Modern React Patterns:**
+- Existing JamTrack components in jam-ui (modal, player, stems)
+- Redux migration underway (MediaContext → mediaSlice)
+- useMediaActions hook for async operations
+- WebSocket integration via useSessionWebSocket
+
+## Phase 4 Goal
+
+Create comprehensive documentation to bridge legacy patterns to modern React architecture, enabling efficient Phase 5 implementation.
+</context>
+
+<tasks>
+### Task 1: Create Legacy Implementation Documentation
+
+**type:** auto
+
+**files:**
+- CREATE `.planning/codebase/JAMTRACK_LEGACY.md`
+
+**action:**
+Document the legacy JamTrack implementation patterns discovered during exploration:
+
+1. **Legacy Dialog Patterns**
+   - openJamTrackDialog.js: Selection UI with search/pagination
+   - File location, initialization pattern, callback structure
+   - Data flow: dialog → REST API → selection callback → loadJamTrack()
+
+2. **Download/Sync State Machine**
+   - download_jamtrack.js.coffee: 8-state synchronization engine
+   - States: no_client, synchronized, packaging, downloading, keying, initial, quiet, errored
+   - Key operations: download initiation, progress tracking, encryption key handling
+   - Integration with jamClient methods
+
+3. **Store Patterns**
+   - JamTrackStore.js.coffee: Mixdown synchronization state management
+   - JamTrackMixdownStore.js.coffee: Mixdown CRUD operations
+   - pickMyPackage() logic for compatible mixdown selection (ogg vs jkz, sample rate matching)
+   - WebSocket subscription patterns (manageWatchedMixdowns)
+
+4. **REST API Endpoints**
+   - POST /api/sessions/{sessionId}/jam_tracks/{jamTrackId}/open
+   - POST /api/jamtracks/{id}/mixdowns/active
+   - POST /api/mixdowns/ (create/edit/delete)
+   - POST /api/mixdowns/{id}/enqueue
+
+5. **Integration Points**
+   - session.js loadJamTrack() function (lines 2691-2777)
+   - Recording conflict detection
+   - DIALOG_CLOSED event pattern
+
+**verify:**
+- JAMTRACK_LEGACY.md exists and contains all 5 sections
+- Code file references include line numbers
+- State machine diagram or table included
+- API endpoint table with method/path/purpose
+
+**done:**
+Legacy implementation patterns documented for reference during React migration.
+
+---
+
+### Task 2: Create jamClient API Reference
+
+**type:** auto
+
+**files:**
+- CREATE `.planning/codebase/JAMTRACK_API.md`
+
+**action:**
+Document all jamClient JamTrack-related methods with signatures, parameters, return values, and usage patterns:
+
+1. **Playback Methods**
+   - `JamTrackPlay(jamTrackId)` - Load and play JamTrack
+   - `JamTrackStopPlay()` - Stop playback
+   - `JamTrackIsPlaying()` - Query playback state
+   - Return types and error handling
+
+2. **Track Data Methods**
+   - `JamTrackGetTracks()` - Get stem track list
+   - `JamTrackGetTrackDetail(fqId)` - Get sync/key state (returns: key_state, version)
+   - `JamTrackGetImage()` - Get album art
+   - `GetJamTrackTimeline()` - Get timeline data
+
+3. **Download/Sync Methods**
+   - `JamTrackDownload(jamTrackId, mixdownId, userId, progressCallback, successCallback, failCallback)`
+   - `JamTrackKeysRequest()` - Request encryption keys
+   - `InvalidateJamTrack(fqId)` - Clear cached version
+   - Callback patterns and error handling
+
+4. **JMEP (Jam Enhancement Package) Methods**
+   - `JamTrackLoadJmep(fqId, jmepData)` - Load tempo/pitch modifications
+   - JMEP data structure and usage
+
+5. **Playback Control Methods**
+   - `SessionJamTrackSeekMs()` - Seek playback position
+   - `SessionCurrrentJamTrackPlayPosMs()` - Get current position
+   - `SessionGetJamTracksPlayDurationMs()` - Get total duration
+
+6. **Query Methods**
+   - `GetSampleRate()` - Get audio sample rate (44 or 48 kHz)
+   - Sample rate implications for fqId format
+
+7. **Backing Track Comparison**
+   - Native dialog: `ShowSelectBackingTrackDialog(callbackFunctionName)`
+   - File-based vs JamTrack ID-based patterns
+   - Shared methods: SessionStartPlay(), SessionStopPlay(), SessionPausePlay()
+
+**verify:**
+- JAMTRACK_API.md exists with all 7 sections
+- Each method documented with signature and return type
+- Async/Promise patterns noted
+- Code examples for common operations (download, play, seek)
+- Comparison table: JamTrack vs Backing Track methods
+
+**done:**
+Complete jamClient API reference created for implementation use.
+
+---
+
+### Task 3: Document Modern React Integration Patterns
+
+**type:** checkpoint:human-verify
+
+**files:**
+- CREATE `.planning/codebase/JAMTRACK_REACT_PATTERNS.md`
+
+**action:**
+Document existing React patterns in jam-ui that will be extended for JamTrack:
+
+1. **Component Architecture**
+   - JKSessionJamTrackModal: Selection UI (already exists)
+   - JKSessionJamTrackStems: Stem mixer view (already exists)
+   - JKJamTrackPlayer: Public player with master/stems dropdown (already exists)
+   - Missing components: Session JamTrack player with playback controls
+
+2. **Redux State Structure**
+   - Current mediaSlice structure (backingTracks, jamTracks, jamTrackState)
+   - Current activeSessionSlice structure (selectedJamTrack, jamTrackStems)
+   - Current sessionUISlice structure (modal visibility)
+   - Gaps identified for JamTrack player state
+
+3. **Hook Patterns**
+   - useMediaActions: async operation wrappers (openBackingTrack, loadJamTrack, closeMedia)
+   - useJamTrack: Redux selectors + mixdown operations
+   - useSessionWebSocket: WebSocket message dispatchers
+   - Pattern to follow for new JamTrack hooks
+
+4. **Data Flow**
+   - User action → Modal selection → Redux dispatch → jamClient call
+   - WebSocket MIXER_CHANGES → Redux update → UI sync
+   - WebSocket JAM_TRACK_CHANGES → jamTrackState update → Real-time UI
+   - Flowchart or sequence diagram
+
+5. **Error Handling Strategy**
+   - Backing Track Player error types: file, network, playback, general
+   - Error UI patterns: banner with dismiss/retry
+   - Async error handling via rejectWithValue in thunks
+   - Apply same patterns to JamTrack
+
+6. **Performance Patterns**
+   - Visibility-aware polling (500ms visible, 2000ms hidden)
+   - useCallback for all handlers
+   - Lazy state updates (only update if value changed)
+   - Consecutive error tracking with refs
+
+7. **Established Patterns from Phase 3**
+   - jamClient returns Promises (always async/await)
+   - jamClient returns strings (parseInt before math)
+   - Non-serializable objects (jamClient) passed as props, not stored in Redux
+   - Cleanup on unmount to prevent stale state
+
+**verify:**
+- JAMTRACK_REACT_PATTERNS.md exists with all 7 sections
+- File references to existing implementations
+- Flowchart or sequence diagram for data flow
+- Comparison to Backing Track patterns highlighted
+- Gaps identified for Phase 5 implementation
+
+**done:**
+Modern React integration patterns documented, ready for architecture design.
+
+---
+
+### CHECKPOINT: Verify Documentation Completeness
+
+**type:** human-verify
+
+**prompt:**
+Review the three documentation files created:
+
+1. `.planning/codebase/JAMTRACK_LEGACY.md` - Legacy implementation patterns
+2. `.planning/codebase/JAMTRACK_API.md` - jamClient API reference
+3. `.planning/codebase/JAMTRACK_REACT_PATTERNS.md` - Modern React patterns
+
+**Verification criteria:**
+- All discovery findings captured
+- Code file references accurate with line numbers
+- API methods have signatures and return types
+- React patterns reference existing implementations
+- Documentation is clear and actionable for Phase 5
+
+**Actions:**
+- If gaps found: Identify missing sections and add them
+- If complete: Approve to proceed to Plan 04-02 (Design React Architecture)
+
+</tasks>
+
+<verification>
+Documentation completeness verified through:
+
+1. **Coverage Check**
+   - Compare documentation sections to discovery findings
+   - Verify all legacy files explored are referenced
+   - Confirm all jamClient methods documented
+   - Check all React patterns captured
+
+2. **Reference Accuracy**
+   - File paths are absolute and correct
+   - Line numbers match actual code locations
+   - API signatures match bridge_api.es6 definitions
+
+3. **Actionability Test**
+   - Documentation provides enough detail for Phase 5 implementation
+   - Code examples clarify complex patterns
+   - Gaps clearly identified for new development
+</verification>
+
+<success_criteria>
+- [ ] JAMTRACK_LEGACY.md created with 5 sections
+- [ ] JAMTRACK_API.md created with 7 sections
+- [ ] JAMTRACK_REACT_PATTERNS.md created with 7 sections
+- [ ] All documentation files committed to git
+- [ ] User verification checkpoint passed
+- [ ] Documentation gaps identified or confirmed complete
+</success_criteria>
+
+<output>
+**Artifacts:**
+- `.planning/codebase/JAMTRACK_LEGACY.md` - Legacy implementation reference
+- `.planning/codebase/JAMTRACK_API.md` - jamClient API documentation
+- `.planning/codebase/JAMTRACK_REACT_PATTERNS.md` - React integration patterns
+
+**Purpose:**
+Comprehensive documentation bridging legacy JamTrack patterns to modern React architecture, enabling efficient Phase 5 implementation without repeated codebase exploration.
+</output>
--- a/.planning/phases/04-jamtrack-research-design/04-02-PLAN.md
+++ b/.planning/phases/04-jamtrack-research-design/04-02-PLAN.md
@ -0,0 +1,430 @@
+# Phase 4 Plan 2: Design React JamTrack Architecture
+
+<objective>
+Design comprehensive React component architecture, Redux state structure, and implementation roadmap for Phase 5 JamTrack migration.
+</objective>
+
+<execution_context>
+@.planning/codebase/JAMTRACK_LEGACY.md
+@.planning/codebase/JAMTRACK_API.md
+@.planning/codebase/JAMTRACK_REACT_PATTERNS.md
+@.planning/phases/03-backing-track-finalization/03-03-SUMMARY.md
+@jam-ui/src/components/client/JKSessionBackingTrackPlayer.js
+@jam-ui/src/store/features/mediaSlice.js
+@jam-ui/src/store/features/sessionUISlice.js
+@jam-ui/src/hooks/useMediaActions.js
+</execution_context>
+
+<context>
+## Background
+
+**Completed Work:**
+- Phase 3: Backing Track Player with Redux integration
+- Plan 04-01: Legacy documentation and API reference
+
+**Established Patterns:**
+- Component structure: Modal → Player → Session View
+- Redux slices: mediaSlice (data), sessionUISlice (UI state), activeSessionSlice (session data)
+- Async operations: Redux thunks wrapping jamClient calls
+- Real-time updates: WebSocket → Redux dispatch
+- Error handling: Type-specific errors with retry capabilities
+
+## Phase 4 Plan 2 Goal
+
+Create detailed architecture design for JamTrack React components that:
+1. Follows established Backing Track patterns
+2. Handles JamTrack-specific complexity (mixdown selection, download/sync, JMEP)
+3. Defines clear Redux state structure
+4. Provides actionable implementation roadmap for Phase 5
+
+## Key Challenges
+
+1. **Mixdown Complexity**: JamTracks support multiple playback modes (master, custom mixes, individual stems)
+2. **Download/Sync State**: 8-state synchronization engine must translate to React/Redux
+3. **JMEP Loading**: Tempo/pitch modifications require special handling
+4. **Sample Rate Handling**: fqId format depends on native client sample rate
+5. **WebSocket Integration**: JAM_TRACK_CHANGES real-time updates for playback state
+</context>
+
+<tasks>
+### Task 1: Design Component Structure
+
+**type:** auto
+
+**files:**
+- CREATE `.planning/phases/04-jamtrack-research-design/COMPONENT_DESIGN.md`
+
+**action:**
+Design complete React component architecture for JamTrack functionality:
+
+1. **JKSessionJamTrackPlayer Component** (NEW - primary deliverable)
+   - Purpose: Full-featured JamTrack player with playback controls
+   - Rendering modes: Modal and Popup (follow Backing Track pattern)
+   - Props interface:
+     - `isOpen`, `onClose`, `jamTrack`, `jamClient`, `session`, `currentUser`, `isPopup`
+   - State management:
+     - Local state: isPlaying, isPaused, currentPosition, duration, isLoading, error, selectedMixdown
+     - Redux state: jamTrackState, mixdowns, downloadState
+   - Sub-components:
+     - Mixdown selector dropdown (master/custom mixes/stems)
+     - Playback controls (play/pause/stop)
+     - Seek bar with position display
+     - Download/sync progress indicator
+     - Error banner with retry
+
+2. **JKSessionJamTrackModal Component** (EXISTS - may need updates)
+   - Current: Selection UI with search/pagination
+   - Potential updates: Add download state indicators, mixdown preview
+   - Integration: Callback pattern → dispatch loadJamTrack
+
+3. **JKSessionJamTrackStems Component** (EXISTS - verify completeness)
+   - Purpose: Display JamTrack stem tracks in session mixer view
+   - Props: jamTrackStems, mixerHelper
+   - Verify: Supports all mixer operations (volume, pan, mute, solo)
+
+4. **Component Hierarchy**
+   ```
+   JKSessionScreen
+   ├── JKSessionJamTrackModal (selection)
+   │   └── onSelect → dispatch loadJamTrack()
+   ├── JKSessionJamTrackPlayer (playback controls)
+   │   ├── MixdownSelector
+   │   ├── PlaybackControls
+   │   ├── SeekBar
+   │   └── DownloadProgress
+   └── JKSessionJamTrackStems (mixer view)
+       └── SessionTrackVU, SessionTrackGain (per stem)
+   ```
+
+5. **Props vs Redux Decision Matrix**
+   | Data | Storage | Rationale |
+   |------|---------|-----------|
+   | jamClient | Props | Non-serializable |
+   | session, currentUser | Props | Parent context |
+   | isOpen, isPopup | Props | Parent controls visibility |
+   | jamTrack data | Redux (media.jamTracks) | WebSocket updates |
+   | jamTrackState | Redux (media.jamTrackState) | Real-time playback state |
+   | selectedMixdown | Local state | Player-specific UI state |
+   | downloadState | Redux (media.downloadState) | Shared across components |
+   | error | Local state | Player-specific errors |
+
+6. **Comparison to Backing Track Player**
+   | Feature | Backing Track | JamTrack | Notes |
+   |---------|---------------|----------|-------|
+   | File selection | Native dialog | Modal selection | Different patterns |
+   | Playback controls | play/pause/stop/seek | Same + mixdown selector | JamTrack adds dropdown |
+   | Duration loading | Single async call | May need sync check | JamTrack download state |
+   | Volume control | SessionSetTrackVolumeData | Same (per stem) | Mixer integration |
+   | Loop control | SessionSetBackingTrackFileLoop | TBD if supported | Check jamClient API |
+   | Error types | file, network, playback, general | Same + download, sync | JamTrack adds download errors |
+
+**verify:**
+- COMPONENT_DESIGN.md created with all 6 sections
+- Component hierarchy diagram included
+- Props interfaces defined with types
+- Redux vs local state decisions documented
+- Comparison table to Backing Track complete
+
+**done:**
+Component architecture designed with clear interfaces and data flow patterns.
+
+---
+
+### Task 2: Design Redux State Structure
+
+**type:** auto
+
+**files:**
+- CREATE `.planning/phases/04-jamtrack-research-design/REDUX_DESIGN.md`
+
+**action:**
+Design comprehensive Redux state structure for JamTrack functionality:
+
+1. **mediaSlice Extensions**
+   ```javascript
+   {
+     backingTracks: [],        // Existing
+     jamTracks: [],            // Existing - extend structure
+     recordedTracks: [],       // Existing
+     metronome: null,          // Existing
+
+     // NEW: JamTrack-specific state
+     jamTrackState: {
+       isPlaying: false,
+       isPaused: false,
+       currentPositionMs: 0,
+       durationMs: 0,
+       selectedMixdownId: null,
+       playbackMode: 'master'  // 'master' | 'custom-mix' | 'stem'
+     },
+
+     // NEW: Download/sync state
+     downloadState: {
+       jamTrackId: null,
+       mixdownId: null,
+       state: 'idle',  // 'idle' | 'checking' | 'downloading' | 'keying' | 'synchronized' | 'error'
+       progress: 0,    // 0-100
+       error: null
+     },
+
+     // Existing loading states
+     loading: {
+       backingTrack: false,
+       jamTrack: false,        // Extend to include download state
+       metronome: false,
+       closing: false
+     }
+   }
+   ```
+
+2. **activeSessionSlice Extensions**
+   ```javascript
+   {
+     selectedJamTrack: null,   // Existing - full JamTrack object
+     jamTrackStems: [],        // Existing - stem track array
+
+     // NEW: Mixdown data
+     availableMixdowns: [],    // User's custom mixes
+     activeMixdown: null       // Currently playing mixdown
+   }
+   ```
+
+3. **sessionUISlice Extensions**
+   ```javascript
+   {
+     modals: {
+       jamTrack: false,        // Existing
+       backingTrack: false,    // Existing
+       metronome: false,       // Existing
+
+       // NEW: JamTrack-specific modals
+       jamTrackPlayer: false   // Player modal visibility
+     },
+
+     // NEW: JamTrack UI state
+     jamTrackUI: {
+       showMixdownSelector: true,
+       showDownloadProgress: true,
+       playerMode: 'modal'     // 'modal' | 'popup'
+     }
+   }
+   ```
+
+4. **Async Thunks**
+   - `loadJamTrack({ jamTrack, mixdownId?, jamClient })` - Load and play JamTrack
+   - `downloadJamTrack({ jamTrackId, mixdownId, jamClient })` - Download with progress
+   - `checkJamTrackSync({ jamTrackId, jamClient })` - Check download/key state
+   - `loadJMEP({ jamTrack, jmepData, jamClient })` - Load tempo/pitch modifications
+   - `seekJamTrack({ positionMs, jamClient })` - Seek playback
+   - `closeJamTrack({ jamClient })` - Stop and clean up
+
+5. **Reducers**
+   - `setJamTracks(state, action)` - From MIXER_CHANGES WebSocket
+   - `updateJamTrackState(state, action)` - From JAM_TRACK_CHANGES WebSocket
+   - `setDownloadState(state, action)` - Progress updates during download
+   - `setAvailableMixdowns(state, action)` - User's custom mixes
+   - `setActiveMixdown(state, action)` - Selected mixdown
+
+6. **Selectors**
+   ```javascript
+   // Media selectors
+   selectJamTracks(state) => state.media.jamTracks
+   selectJamTrackState(state) => state.media.jamTrackState
+   selectDownloadState(state) => state.media.downloadState
+   selectIsJamTrackPlaying(state) => state.media.jamTrackState.isPlaying
+
+   // Session selectors
+   selectSelectedJamTrack(state) => state.activeSession.selectedJamTrack
+   selectJamTrackStems(state) => state.activeSession.jamTrackStems
+   selectAvailableMixdowns(state) => state.activeSession.availableMixdowns
+
+   // UI selectors
+   selectJamTrackPlayerOpen(state) => state.sessionUI.modals.jamTrackPlayer
+   selectJamTrackUI(state) => state.sessionUI.jamTrackUI
+   ```
+
+7. **WebSocket Integration**
+   - MIXER_CHANGES handler: Dispatch `setJamTracks(sessionMixers.mixers.jamTracks)`
+   - JAM_TRACK_CHANGES handler: Dispatch `updateJamTrackState(changes)`
+   - Real-time playback position updates (similar to Backing Track polling)
+
+8. **State Machine for Download/Sync**
+   | State | Description | Next States | Actions |
+   |-------|-------------|-------------|---------|
+   | idle | No active download | checking, downloading | User initiates download |
+   | checking | Querying sync state | synchronized, downloading, error | JamTrackGetTrackDetail() |
+   | downloading | Download in progress | keying, error | JamTrackDownload() with progress callback |
+   | keying | Requesting encryption keys | synchronized, error | JamTrackKeysRequest() |
+   | synchronized | Ready to play | idle | JamTrackPlay() success |
+   | error | Download/sync failed | idle (after retry) | Show error, allow retry |
+
+**verify:**
+- REDUX_DESIGN.md created with all 8 sections
+- State structure with TypeScript-style type annotations
+- All thunks defined with parameters and return types
+- Selector list complete
+- State machine table or diagram included
+- Comparison to Backing Track Redux patterns
+
+**done:**
+Redux state structure designed with clear data flow and state management patterns.
+
+---
+
+### Task 3: Create Phase 5 Implementation Roadmap
+
+**type:** checkpoint:human-verify
+
+**files:**
+- CREATE `.planning/phases/04-jamtrack-research-design/IMPLEMENTATION_ROADMAP.md`
+
+**action:**
+Create detailed implementation roadmap for Phase 5 with risk analysis:
+
+1. **Phase 5 Task Breakdown** (preliminary - will be refined during Phase 5 planning)
+   - Plan 05-01: Redux State Setup (mediaSlice, activeSessionSlice, sessionUISlice extensions)
+   - Plan 05-02: jamClient Integration (async thunks, download/sync state machine)
+   - Plan 05-03: JKSessionJamTrackPlayer Component (player UI, playback controls, mixdown selector)
+   - Plan 05-04: WebSocket Integration (MIXER_CHANGES, JAM_TRACK_CHANGES handlers)
+   - Plan 05-05: Download/Sync Flow (progress UI, error handling, retry logic)
+   - Plan 05-06: Testing & Edge Cases (error scenarios, network resilience, UAT)
+
+2. **Dependency Graph**
+   ```
+   05-01 (Redux State) → 05-02 (jamClient Integration)
+                       ↘
+   05-03 (Player Component) ← 05-02
+                       ↓
+   05-04 (WebSocket) ← 05-02
+                       ↓
+   05-05 (Download/Sync) ← 05-04
+                       ↓
+   05-06 (Testing/UAT)
+   ```
+
+3. **Risk Analysis**
+   | Risk | Likelihood | Impact | Mitigation |
+   |------|------------|--------|------------|
+   | Download/sync state machine complexity | High | High | Parallel implementation with feature flag, gradual rollout |
+   | JMEP loading failures | Medium | Medium | Graceful degradation (play master if JMEP fails), error handling |
+   | Sample rate mismatch | Medium | High | Validate sample rate early, show error if incompatible |
+   | WebSocket JAM_TRACK_CHANGES integration | Low | Medium | Follow MIXER_CHANGES pattern, test with real sessions |
+   | Mixdown selector UX complexity | Medium | Low | MVP: master + custom mixes, defer stem-level control |
+   | Native client API changes | Low | High | Verify API methods in test environment before implementation |
+   | Performance regression | Low | Medium | Reuse Backing Track polling patterns, benchmark dispatch speed |
+
+4. **Critical Decisions Needed Before Phase 5**
+   - [ ] Does jamClient support JamTrack loop functionality? (Test: `SessionSetBackingTrackFileLoop` equivalent)
+   - [ ] Should download/sync happen automatically or require user confirmation?
+   - [ ] MVP mixdown selector: Master + custom mixes only, or include individual stems?
+   - [ ] Popup vs modal preference: Default to popup like Backing Track, or modal?
+   - [ ] Error recovery strategy: Auto-retry downloads or require manual retry?
+
+5. **Success Metrics for Phase 5**
+   - [ ] JamTrack loads and plays with master mix
+   - [ ] Mixdown selector switches between master/custom mixes without interruption
+   - [ ] Download progress shown during sync
+   - [ ] Seek bar functional (drag-to-position)
+   - [ ] Error handling with user feedback
+   - [ ] No playback interruptions or state sync issues
+   - [ ] Performance: <1ms Redux dispatch, 60fps UI updates
+
+6. **Testing Strategy**
+   - Unit tests: Redux reducers, thunks, selectors (>80% coverage)
+   - Integration tests: jamClient call sequences, WebSocket message handling
+   - Manual UAT: Load JamTrack, switch mixdowns, seek, pause/resume, error scenarios
+   - Performance tests: Dispatch speed, polling frequency, memory leaks
+
+7. **Comparison to Phase 3 Effort**
+   | Metric | Phase 3 (Backing Track) | Phase 5 (JamTrack) Estimate |
+   |--------|-------------------------|------------------------------|
+   | Plans | 3 plans | 6 plans |
+   | Tasks | ~10 tasks | ~18 tasks |
+   | Complexity | Medium | High (download/sync state machine) |
+   | New components | 1 (Player) | 1 (Player) + updates to Modal/Stems |
+   | Redux state additions | 2 slices | 3 slices (more complex structure) |
+   | jamClient methods | 8-10 methods | 15+ methods |
+   | Known blockers | 3 deferred issues | TBD (likely 2-4 similar issues) |
+
+**verify:**
+- IMPLEMENTATION_ROADMAP.md created with all 7 sections
+- Dependency graph visualized (text diagram or mermaid)
+- Risk analysis complete with mitigation strategies
+- Critical decisions identified
+- Success metrics defined
+- Testing strategy outlined
+
+**done:**
+Phase 5 implementation roadmap created with risk analysis and clear path forward.
+
+---
+
+### CHECKPOINT: Architecture Review and Approval
+
+**type:** human-verify
+
+**prompt:**
+Review the architecture design created across three documents:
+
+1. `.planning/phases/04-jamtrack-research-design/COMPONENT_DESIGN.md` - React component structure
+2. `.planning/phases/04-jamtrack-research-design/REDUX_DESIGN.md` - Redux state and data flow
+3. `.planning/phases/04-jamtrack-research-design/IMPLEMENTATION_ROADMAP.md` - Phase 5 implementation plan
+
+**Verification criteria:**
+- Component design follows established Backing Track patterns
+- Redux state structure accommodates JamTrack-specific complexity
+- Implementation roadmap is actionable and complete
+- Risk analysis covers critical concerns
+- Critical decisions identified for user input
+
+**Actions:**
+- If revisions needed: Specify changes to component/Redux design
+- If critical decisions need answers: Answer decision questions in roadmap
+- If approved: Proceed to commit Phase 4 completion
+
+</tasks>
+
+<verification>
+Architecture design verified through:
+
+1. **Pattern Consistency**
+   - Compare component design to JKSessionBackingTrackPlayer.js
+   - Verify Redux state structure follows mediaSlice patterns
+   - Check thunk signatures match useMediaActions patterns
+
+2. **Completeness Check**
+   - All JamTrack-specific features addressed (mixdowns, download/sync, JMEP)
+   - Error handling strategy defined
+   - WebSocket integration planned
+   - Performance considerations included
+
+3. **Actionability Test**
+   - Phase 5 roadmap provides clear starting point
+   - Component interfaces fully defined
+   - Redux state structure ready for implementation
+   - Risk mitigation strategies practical
+
+4. **Risk Coverage**
+   - All high-impact risks identified
+   - Mitigation strategies feasible
+   - Critical decisions captured
+</verification>
+
+<success_criteria>
+- [ ] COMPONENT_DESIGN.md created with complete component hierarchy
+- [ ] REDUX_DESIGN.md created with state structure and thunks
+- [ ] IMPLEMENTATION_ROADMAP.md created with Phase 5 breakdown
+- [ ] All design documents committed to git
+- [ ] User verification checkpoint passed
+- [ ] Critical decisions answered or deferred to Phase 5 planning
+</success_criteria>
+
+<output>
+**Artifacts:**
+- `.planning/phases/04-jamtrack-research-design/COMPONENT_DESIGN.md` - Component architecture
+- `.planning/phases/04-jamtrack-research-design/REDUX_DESIGN.md` - Redux state design
+- `.planning/phases/04-jamtrack-research-design/IMPLEMENTATION_ROADMAP.md` - Phase 5 roadmap
+
+**Purpose:**
+Comprehensive React architecture design for JamTrack functionality, enabling Phase 5 implementation with clear component structure, Redux state management, and risk-aware implementation strategy.
+</output>