# JamKazam Media Features Modernization

**One-liner:** Modernize session features from legacy jQuery/Rails to React patterns in jam-ui, with comprehensive test coverage

## Vision

Transform session features from the legacy web project into modern React patterns in jam-ui. The features exist in the legacy codebase with jQuery dialogs and polling-based playback monitoring - we're bringing them into the React architecture with proper component structure, hooks, and Redux integration where appropriate.

**Completed Features (v1.0 - v1.6):**
1. ✅ **Backing Track** - File-based audio playback with player controls
2. ✅ **JamTrack** - Collaborative track loading with mixdown selection
3. ✅ **Session Chat** - Real-time chat with message history and read/unread tracking
4. ✅ **Session Attachments** - File upload/download integration with chat window
5. ✅ **Session Settings Tests** - Jest unit tests and Playwright integration tests
6. ✅ **Memory Leak Prevention** - Fixed memory leaks causing session screen freezes (shipped 2026-02-10)
7. ✅ **Fix Session Recording** - Fixed C++ client crash and memory leaks (shipped 2026-02-25)
8. ✅ **Media Features Polish** - Fixed JamTrack loading, Backing Track sync, multiple media prevention (shipped 2026-03-03)

**Current Milestone (v1.7):**
9. 🔧 **Performance Optimization** - Eliminate page freezes from excessive re-renders, optimize VU/mixer state updates

**Future Work:**
- Additional recording controls (track selection, playback, management)

## Context

### Current State

**v1.6 Media Features Polish (SHIPPED 2026-03-03):**
- ✅ JamTrack loading sequence fixed (defer UI until backend ready)
- ✅ JamTrack player window sizing (460x350) without scrollbars
- ✅ "Create custom mix" navigation to JamTrack editor
- ✅ JamTrack callback cleanup (memory leak prevention)
- ✅ Backing track sync to session screen via Redux
- ✅ Async cleanup pattern for unmount state warnings
- ✅ Prevent opening multiple media players simultaneously

**v1.5 Fix Session Recording (SHIPPED 2026-02-25):**
- ✅ Fixed C++ client crash on Start Recording (JSON parsing fix)
- ✅ Timer cleanup for recording hook (waitingOnStopTimer)
- ✅ Conditional callback cleanup for window.JK (prevents race conditions)
- ✅ Async operation guards with ignore flag pattern
- ✅ User verified 15+ minute recording stability

**v1.4 Memory Leak Prevention (SHIPPED 2026-02-10):**
- ✅ Audit and fix VU meter animation/interval cleanup
- ✅ Audit and fix chat window WebSocket listeners and state management
- ✅ Audit and fix session screen polling and useEffect cleanup
- ✅ User verified 15+ minute session stability

**v1.3 Session Settings Tests (SHIPPED 2026-02-08):**
- ✅ Jest unit tests for JKSessionSettingsModal component
- ✅ Playwright integration tests for Settings modal user flows
- ✅ Coverage for critical paths: save, cancel, validation, errors

**v1.2 Session Attachments (SHIPPED 2026-02-07):**
- ✅ File attachment capability from session toolbar
- ✅ Integration with existing chat window
- ✅ Real-time attachment notifications via WebSocket
- ✅ File viewing in new browser tab

**v1.1 Music Session Chat (SHIPPED 2026-01-27):**
- ✅ Redux state management with WebSocket integration
- ✅ Modeless chat window with message list and auto-scroll
- ✅ Message composition and real-time delivery
- ✅ Read/unread status tracking with badge indicators
- ✅ Error handling, accessibility, and edge cases

**v1.0 Media Players (SHIPPED 2026-01-14):**
- ✅ Backing Track - Complete with playback monitoring, seek controls, error handling
- ✅ JamTrack - Complete with mixdown selection, player controls, download UI

**Deferred:**
- **Metronome** - Tempo/sound configuration and playback

### Architecture Context

- **Frontend:** React 16.13.1 SPA with Redux Toolkit 1.6.1
- **Native Bridge:** C++ desktop client exposed via `jamClientProxy.js` QWebChannel tunnel
- **State Management:** Redux for global state, local component state for transient playback data
- **Legacy Reference:** jQuery-based implementation in `web/app/assets/javascripts/` using 500ms polling

## Requirements

### Validated (v1.0 - v1.5)

**Core Architecture:**
- ✓ Native file dialog for track selection — v1.0
- ✓ jamClient API integration — v1.0
- ✓ Redux state management architecture — v1.1
- ✓ WebSocket real-time communication — v1.1
- ✓ Modeless dialog pattern — v1.1
- ✓ Backend API integration — v1.2
- ✓ File attachment upload to S3 — v1.2
- ✓ Attachment display in chat — v1.2

**Memory Management:**
- ✓ VU meter animation/interval cleanup — v1.4
- ✓ Chat window WebSocket listener cleanup — v1.4
- ✓ Session screen useEffect cleanup — v1.4
- ✓ 15+ minute session stability — v1.4

**Recording:**
- ✓ Recording crash fix (JSON parsing) — v1.5
- ✓ Recording modal memory leak fixes — v1.5
- ✓ Timer cleanup on unmount — v1.5
- ✓ Conditional callback cleanup — v1.5
- ✓ 15+ minute recording stability — v1.5

**Media Features Polish:**
- ✓ JamTrack defer UI until backend ready — v1.6
- ✓ JamTrack window sizing (460x350) — v1.6
- ✓ JamTrack "Create custom mix" navigation — v1.6
- ✓ JamTrack callback cleanup — v1.6
- ✓ Backing track sync to session screen — v1.6
- ✓ Async cleanup for unmount warnings — v1.6
- ✓ Prevent multiple media players — v1.6

### Out of Scope

- **Additional recording controls** - Track selection, playback, management deferred
- **Backend changes** - Frontend-only fixes
- **Metronome** - Separate feature

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| Keep native file dialogs | Already working, platform-native UX, no need to rebuild | Validated (v1.0) |
| Use Redux for chat state | Global visibility needed for badge, history, WebSocket sync | Validated (v1.1) |
| Reuse existing backend | MusicNotation model already has S3, API, attachment_type | Validated (v1.2) |
| Only toolbar upload | Simplifies UX, avoids dual upload paths, matches common patterns | Validated (v1.2) |
| 10 MB file size limit | Matches legacy app limit, reasonable for notation/audio files | Validated (v1.2) |
| Browser handles view/download | No custom preview UI, leverages native browser capabilities | Validated (v1.2) |
| Display in chat window | Natural integration, attachments are part of session communication | Validated (v1.2) |
| Critical paths only | Focus on save/cancel/validation/errors, not exhaustive coverage | Confirmed (v1.3) |
| Both test types | Jest for unit tests, Playwright for integration | Confirmed (v1.3) |
| Conditional callback cleanup | Multiple hook instances share window.JK callbacks | Validated (v1.5) |
| Ignore flag pattern | Prevents state updates on unmounted components | Validated (v1.5) |
| Defer JamTrack UI until synchronized | Prevents empty controls showing before backend ready | Validated (v1.6) |
| WindowPortal sizing 460x350 | Matches content dimensions plus padding for JamTrack | Validated (v1.6) |
| openBackingTrack action for sync | Centralized Redux + server sync for backing tracks | Validated (v1.6) |
| Prevent multiple media players | Only one media type (JamTrack/BackingTrack/Metronome) at a time | Validated (v1.6) |

## Constraints

### Technical

- **React 16 patterns only** - No async/await in useEffect without proper cleanup
- **Minimal changes** - Fix leaks with smallest possible code changes
- **No new dependencies** - Use existing patterns and tools
- **Preserve existing behavior** - Fixes should not change user-facing functionality

### Testing

- **Manual verification** - Session must remain stable for 15+ minutes
- **Memory monitoring** - Use browser dev tools to verify no memory growth
- **Existing tests must pass** - Don't break anything while fixing leaks

## Critical Files

**Recording (v1.5):**
- `jam-ui/src/hooks/useRecordingHelpers.js` - Recording hook with cleanup patterns
- `jam-ui/src/components/client/JKSessionRecordingModal.js` - Recording modal with async guards
- `jam-ui/src/services/jamClientProxy.js` - C++ client bridge for recording commands

**Memory Management (v1.4):**
- `jam-ui/src/components/client/JKSessionScreen.js` - Session screen with callback cleanup
- `jam-ui/src/store/features/chatSlice.js` - Chat state with MAX_MESSAGES bounds
- `jam-ui/src/store/features/mixersSlice.js` - Mixer state with removeVuState

---
*Last updated: 2026-03-03 after v1.7 Performance Optimization milestone started*
