seth
/
jam-cloud
mirror of https://bitbucket.org/jamkazam/jam-cloud.git
1
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity
jam-cloud/.planning/PROJECT.md

7.5 KiB
Raw Blame History

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.1, v1.2, v1.3):

  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

Current Milestone (v1.4): 6. 🚧 Memory Leak Prevention - Fix memory leaks causing session screen freezes after ~10 minutes

Future Work:

  • Metronome - Tempo/sound configuration and playback (deferred)
  • Recording Modal Performance - Audit recording modal for memory leaks (deferred)

Context

Current State

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

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.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.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.4 Memory Leak Prevention (IN PROGRESS):

  • ⏳ 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
  • ⏳ Add safeguards to prevent memory leak regression

Deferred:

  • Metronome - Tempo/sound configuration and playback
  • Recording Modal Performance - Memory leak audit (separate from session screen)

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

Recent Work

Phase 5 Redux Migration (Completed):

  • Migrated MediaContext to Redux (mediaSlice.js, mixersSlice.js)
  • Eliminated duplicate state across contexts and hooks
  • Fixed VU meter bug with personal mixer mode flag handling
  • Established clean separation: Redux for data, local state for UI

Requirements

Validated (from v1.0, v1.1, v1.2)

  • ✓ Native file dialog for track selection - works well for media files
  • ✓ jamClient API integration - proven in Backing Track/JamTrack
  • ✓ Redux state management architecture - validated in media and chat features
  • ✓ WebSocket real-time communication - proven in chat feature
  • ✓ Modeless dialog pattern - established in chat window
  • ✓ Backend API integration - REST endpoints for chat/media working well
  • ✓ File attachment upload to S3 - validated in Session Attachments
  • ✓ Attachment display in chat - validated in Session Attachments

Active (v1.4 Memory Leak Prevention)

VU Meters:

  • Audit animation/interval cleanup on unmount
  • Fix any leaking intervals or requestAnimationFrame
  • Ensure VU meter components clean up properly when hidden

Chat Window:

  • Audit WebSocket listener cleanup
  • Check for unbounded message state growth
  • Ensure proper cleanup when chat window closes

Session Screen Base:

  • Audit useEffect cleanup functions
  • Check polling intervals for proper cleanup
  • Audit event listener registration/removal

Verification:

  • Manual test: session stable after 15+ minutes
  • No memory growth in browser dev tools

Out of Scope

  • Recording modal - Separate milestone for recording-specific performance
  • New features - Focus purely on fixing existing memory leaks
  • Backend changes - Frontend-only fixes
  • Refactoring beyond leak fixes - Minimal changes to fix leaks

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)
File types from legacy .pdf, .xml, .mxl, .txt (notation), .png/.jpg/.jpeg/.gif (images), .mp3/.wav (audio) 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 - comprehensive coverage Confirmed (v1.3)

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

v1.4 Memory Leak Prevention (Current Focus):

  • jam-ui/src/components/client/JKSessionScreen.js - Main session screen, parent of all session components
  • jam-ui/src/components/client/JKVUMeterBank.js - VU meter visualization (likely suspect)
  • jam-ui/src/components/client/JKChatWindow.js - Chat window with WebSocket integration
  • jam-ui/src/components/client/JKChatMessageList.js - Message list component
  • jam-ui/src/store/features/sessionChatSlice.js - Chat Redux state
  • jam-ui/src/store/features/mixersSlice.js - Mixer/VU meter Redux state

Investigation Areas:

  • useEffect hooks without cleanup functions
  • setInterval/setTimeout without clearInterval/clearTimeout
  • requestAnimationFrame without cancelAnimationFrame
  • WebSocket event listener registration without removal
  • Redux state growing unbounded

Last updated: 2026-02-08 for v1.4 Memory Leak Prevention milestone