diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md
index 4e2c052a8..c6367b3b5 100644
--- 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 | - |
diff --git a/.planning/STATE.md b/.planning/STATE.md
index b7a51443c..60bd106d4 100644
--- 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
diff --git a/.planning/phases/04-jamtrack-research-design/04-01-PLAN.md b/.planning/phases/04-jamtrack-research-design/04-01-PLAN.md
new file mode 100644
index 000000000..e25d6bc05
--- /dev/null
+++ b/.planning/phases/04-jamtrack-research-design/04-01-PLAN.md
@@ -0,0 +1,283 @@
+# Phase 4 Plan 1: Document Legacy JamTrack Implementation
+
+
+Document legacy JamTrack patterns, jamClient API, and React integration patterns to serve as reference for Phase 5 implementation.
+
+
+
+@.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
+
+
+
+## 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.
+
+
+
+### 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)
+
+
+
+
+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
+
+
+
+- [ ] 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
+
+
+
diff --git a/.planning/phases/04-jamtrack-research-design/04-02-PLAN.md b/.planning/phases/04-jamtrack-research-design/04-02-PLAN.md
new file mode 100644
index 000000000..6e0f4244b
--- /dev/null
+++ b/.planning/phases/04-jamtrack-research-design/04-02-PLAN.md
@@ -0,0 +1,430 @@
+# Phase 4 Plan 2: Design React JamTrack Architecture
+
+
+Design comprehensive React component architecture, Redux state structure, and implementation roadmap for Phase 5 JamTrack migration.
+
+
+
+@.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
+
+
+
+## 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
+
+
+
+### 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
+
+
+
+
+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
+
+
+
+- [ ] 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
+
+
+