diff --git a/.planning/MILESTONES.md b/.planning/MILESTONES.md index af66d060a..10b2414be 100644 --- a/.planning/MILESTONES.md +++ b/.planning/MILESTONES.md @@ -1,5 +1,31 @@ # Project Milestones: JamKazam Media Features Modernization +## v1.5 Fix Session Recording (Shipped: 2026-02-25) + +**Delivered:** Fixed session recording crash and memory leaks, enabling stable recording sessions of 15+ minutes. + +**Phases completed:** 24-25 (2 plans total) + +**Key accomplishments:** +- Fixed C++ client crash on Start Recording (JSON parsing fix in rest.js) +- Added timer cleanup for recording hook (waitingOnStopTimer properly cleared on unmount) +- Implemented conditional callback cleanup for window.JK (prevents race conditions) +- Added async operation guards with ignore flag pattern +- Created UAT checklist for memory verification (25-UAT.md) +- User verified 15+ minute recording stability with no memory growth + +**Stats:** +- 18 files modified +- +1,103 / -107 lines of JavaScript/React +- 2 phases, 2 plans +- 6 days (2026-02-19 → 2026-02-25) + +**Git range:** `1512f646e` → `2292cb4fd` + +**What's next:** To be determined in next milestone planning + +--- + ## v1.4 Memory Leak Prevention (Shipped: 2026-02-10) **Delivered:** Fixed memory leaks causing session screen freezes after ~10 minutes through comprehensive audit and cleanup patterns for VU meters, chat, and session callbacks. diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md index e3fdbea7f..dd9a2eb2b 100644 --- a/.planning/PROJECT.md +++ b/.planning/PROJECT.md @@ -6,18 +6,14 @@ 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):** +**Completed Features (v1.0 - v1.5):** 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 - -**Completed (v1.4):** 6. ✅ **Memory Leak Prevention** - Fixed memory leaks causing session screen freezes (shipped 2026-02-10) - -**Current Milestone (v1.5):** -7. 🔧 **Fix Session Recording** - Fix C++ client crash, verify basic controls, audit memory leaks +7. ✅ **Fix Session Recording** - Fixed C++ client crash and memory leaks (shipped 2026-02-25) **Future Work:** - **Metronome** - Tempo/sound configuration and playback (deferred) @@ -26,9 +22,29 @@ Transform session features from the legacy web project into modern React pattern ### 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.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 @@ -37,26 +53,12 @@ Transform session features from the legacy web project into modern React pattern - ✅ 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 (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.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 -- **Recording Modal Performance** - Memory leak audit (separate from session screen) ### Architecture Context @@ -65,69 +67,38 @@ Transform session features from the legacy web project into modern React pattern - **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) +### Validated (v1.0 - v1.5) -- ✓ 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 +**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 -### Validated (v1.4 Memory Leak Prevention) +**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 -**VU Meters:** -- ✓ Audit animation/interval cleanup on unmount — v1.4 -- ✓ Fix any leaking intervals or requestAnimationFrame — v1.4 (removeVuState cleanup) -- ✓ Ensure VU meter components clean up properly when hidden — v1.4 - -**Chat Window:** -- ✓ Audit WebSocket listener cleanup — v1.4 (verified OK) -- ✓ Check for unbounded message state growth — v1.4 (MAX_MESSAGES = 500) -- ✓ Ensure proper cleanup when chat window closes — v1.4 (clearAllMessages) - -**Session Screen Base:** -- ✓ Audit useEffect cleanup functions — v1.4 (useRef pattern) -- ✓ Check polling intervals for proper cleanup — v1.4 (verified OK) -- ✓ Audit event listener registration/removal — v1.4 (verified OK) - -**Verification:** -- ✓ Manual test: session stable after 15+ minutes — v1.4 -- ✓ No memory growth in browser dev tools — v1.4 - -### Active (v1.5 Fix Session Recording) - -**Crash Fix:** -- [ ] Fix C++ client crash when Start Recording is clicked -- [ ] Recording modal should not freeze after clicking Start Recording - -**Basic Controls:** -- [ ] Start recording works like desktop native app -- [ ] Stop recording works like desktop native app -- [ ] Pause recording works like desktop native app - -**Memory Leak Audit:** -- [ ] Audit recording modal for memory leaks -- [ ] Fix any leaking intervals, timers, or event listeners -- [ ] Verify no memory growth while recording modal is open +**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 ### Out of Scope - **Additional recording controls** - Track selection, playback, management deferred - **Backend changes** - Frontend-only fixes -- **Metronome** - Separate feature, not part of this milestone +- **Metronome** - Separate feature ## Key Decisions @@ -140,9 +111,10 @@ Transform session features from the legacy web project into modern React pattern | 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) | +| 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) | ## Constraints @@ -161,16 +133,15 @@ Transform session features from the legacy web project into modern React pattern ## Critical Files -**v1.5 Fix Session Recording (Current Focus):** -- Recording modal component (needs identification) +**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 -- Legacy recording implementation for reference -**Investigation Areas:** -- jamClient recording API calls causing C++ crash -- Recording modal useEffect cleanup -- Timer/interval cleanup during recording -- State management during recording lifecycle +**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-02-19 after v1.5 Fix Session Recording milestone started* +*Last updated: 2026-02-25 after v1.5 Fix Session Recording milestone shipped* diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md deleted file mode 100644 index c3afe0859..000000000 --- a/.planning/REQUIREMENTS.md +++ /dev/null @@ -1,75 +0,0 @@ -# Requirements: Fix Session Recording - -**Defined:** 2026-02-19 -**Core Value:** Fix recording so users can record their jam sessions without crashes - -## v1.5 Requirements - -Requirements for fixing session recording. Each maps to roadmap phases. - -### Crash Fix - -- [x] **CRASH-01**: Call RegisterRecordingCallbacks before recording operations ✓ -- [x] **CRASH-02**: Use correct method name StartRecording (not StartMediaRecording) ✓ -- [x] **CRASH-03**: Use correct method name StopRecording (not FrontStopRecording) ✓ -- [x] **CRASH-04**: Pass individual parameters to StartRecording (not settings object) ✓ - -### Basic Controls - -- [ ] **CTRL-01**: Start recording works - initiates recording like desktop native app -- [ ] **CTRL-02**: Stop recording works - ends recording like desktop native app -- [ ] **CTRL-03**: Pause recording works - pauses recording like desktop native app - -### Memory Leak Audit - -- [ ] **MEM-01**: Audit recording modal useEffect cleanup functions -- [ ] **MEM-02**: Audit timer/interval cleanup during recording lifecycle -- [ ] **MEM-03**: Verify no memory growth while recording modal is open - -## Future Requirements - -Deferred to future milestones. - -### Recording Management - -- **RMGT-01**: Track selection - Choose which tracks to include in recording -- **RMGT-02**: Recording playback - Play back recordings within the modal -- **RMGT-03**: Recording management - Save, delete, rename recordings - -## Out of Scope - -Explicitly excluded for this milestone. - -| Feature | Reason | -|---------|--------| -| Track selection | Keep v1.5 focused on crash fix and basic controls | -| Recording playback | Not blocking core recording functionality | -| Recording management | Defer to future milestone | -| Backend changes | Frontend-only fixes | -| Metronome | Separate feature | - -## Traceability - -Which phases cover which requirements. Updated during roadmap creation. - -| Requirement | Phase | Status | -|-------------|-------|--------| -| CRASH-01 | Phase 24 | Complete | -| CRASH-02 | Phase 24 | Complete | -| CRASH-03 | Phase 24 | Complete | -| CRASH-04 | Phase 24 | Complete | -| CTRL-01 | Phase 25 | Pending | -| CTRL-02 | Phase 25 | Pending | -| CTRL-03 | Phase 25 | Pending | -| MEM-01 | Phase 26 | Pending | -| MEM-02 | Phase 26 | Pending | -| MEM-03 | Phase 26 | Pending | - -**Coverage:** -- v1.5 requirements: 10 total -- Mapped to phases: 10 -- Unmapped: 0 ✓ - ---- -*Requirements defined: 2026-02-19* -*Last updated: 2026-02-19 after Phase 24 complete* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md deleted file mode 100644 index ca92c1268..000000000 --- a/.planning/ROADMAP.md +++ /dev/null @@ -1,87 +0,0 @@ -# Roadmap: Fix Session Recording (v1.5) - -**Created:** 2026-02-19 -**Milestone:** v1.5 Fix Session Recording -**Phases:** 24-25 (continues from v1.4) - -## Overview - -| # | Phase | Goal | Requirements | Plans | Success Criteria | -|---|-------|------|--------------|-------|------------------| -| 24 | Fix Recording Crash | Fix C++ client crash on Start Recording | CRASH-01, CRASH-02, CRASH-03, CRASH-04 | 1 | 4 | -| 25 | Memory Leak Audit | Audit and fix memory leaks in recording modal | MEM-01, MEM-02, MEM-03 | 1 | 3 | - -**Total:** 2 phases | 7 requirements | 7 success criteria - ---- - -## Phase 24: Fix Recording Crash - -**Goal:** Fix C++ client crash when Start Recording is clicked - -**Plans:** 1 plan - -Plans: -- [x] 24-01-PLAN.md — Fix method names and parameters in useRecordingHelpers.js and JKSessionScreen.js - -**Requirements:** -- CRASH-01: Call RegisterRecordingCallbacks before recording operations (ALREADY DONE in JKSessionScreen.js line 500) -- CRASH-02: Use correct method name StartRecording (not StartMediaRecording) -- CRASH-03: Use correct method name StopRecording (not FrontStopRecording) -- CRASH-04: Pass individual parameters to StartRecording (not settings object) - -**Success Criteria:** -1. RegisterRecordingCallbacks is called during session or recording modal initialization -2. StartRecording method name matches legacy implementation -3. StopRecording method name matches legacy implementation -4. Parameters to StartRecording match legacy signature (id, tracks, video, chat, framerate) - -**Dependencies:** None - -**Key Files:** -- `jam-ui/src/hooks/useRecordingHelpers.js` -- `jam-ui/src/components/client/JKSessionScreen.js` -- `jam-ui/src/components/client/JKSessionRecordingModal.js` - ---- - -## Phase 25: Memory Leak Audit - -**Goal:** Audit and fix memory leaks in recording modal - -**Plans:** 1 plan - -Plans: -- [x] 25-01-PLAN.md — Fix timer, callback, and async cleanup in recording components - -**Requirements:** -- MEM-01: Audit recording modal useEffect cleanup functions -- MEM-02: Audit timer/interval cleanup during recording lifecycle -- MEM-03: Verify no memory growth while recording modal is open - -**Success Criteria:** -1. All useEffect hooks in recording modal have proper cleanup functions -2. All timers/intervals are cleared on unmount or state change -3. Recording modal can remain open 15+ minutes without memory growth - -**Dependencies:** Phase 24 (crash must be fixed first) - -**Key Files:** -- `jam-ui/src/components/client/JKSessionRecordingModal.js` -- `jam-ui/src/hooks/useRecordingHelpers.js` - ---- - -## Research Reference - -See: `.planning/research/RECORDING-ANALYSIS.md` - -Key findings: -- `RegisterRecordingCallbacks` is ALREADY called in JKSessionScreen.js line 500 (not a gap) -- Wrong method names in jam-ui vs legacy (`StartMediaRecording` vs `StartRecording`) -- Wrong method names (`FrontStopRecording` vs `StopRecording`) -- Parameter format mismatch (object vs unpacked params) - ---- -*Roadmap created: 2026-02-19* -*Last updated: 2026-02-24 after Phase 25 planned* diff --git a/.planning/STATE.md b/.planning/STATE.md index d201dba7a..f058208ea 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,19 +2,19 @@ ## Project Reference -See: .planning/PROJECT.md (updated 2026-02-19) +See: .planning/PROJECT.md (updated 2026-02-25) **Core value:** Modernize session features from legacy jQuery/Rails to React patterns -**Current focus:** v1.5 Fix Session Recording +**Current focus:** Planning next milestone ## Current Position -Phase: 25 (Memory Leak Audit) -Plan: 01 of 1 complete -Status: Phase complete -Last activity: 2026-02-24 - Completed 25-01-PLAN.md +Phase: Not started +Plan: - +Status: v1.5 complete, ready for next milestone +Last activity: 2026-02-25 - v1.5 Fix Session Recording shipped -Progress: [==========] 100% +Progress: Milestone complete ## Performance Metrics @@ -52,41 +52,21 @@ Progress: [==========] 100% **v1.5 Fix Session Recording (Complete):** - Phases: 2 (phases 24-25) - Plans completed: 2 (24-01, 25-01) -- Completion date: 2026-02-24 -- Duration: 5 days (2026-02-19 -> 2026-02-24) -- Files modified: 5 +- Completion date: 2026-02-25 +- Duration: 6 days (2026-02-19 -> 2026-02-25) +- Files modified: 18 +- Lines: +1,103 / -107 - User verified: 15+ minute recording stability, no memory growth -**v1.5 Fix Session Recording (Complete):** -- Phase 24: Fix Recording Crash - Complete (24-01) -- Phase 25: Memory Leak Audit - Complete (25-01) - ## Accumulated Context ### Decisions -Decisions are logged in PROJECT.md Key Decisions table. +See PROJECT.md Key Decisions table for full history. -| Date | Phase | Decision | Rationale | -|------|-------|----------|-----------| -| 2026-02-08 | 18-01 | Use privacy select as modal indicator | Avoids toast notification collision | -| 2026-02-08 | 18-01 | page.route() for API interception | Simpler than APIInterceptor for single-request | -| 2026-02-08 | 19-01 | vuStates unbounded growth is HIGH priority | Primary leak source - accumulates with track changes | -| 2026-02-08 | 19-01 | Chat messages unbounded is HIGH priority | Secondary leak source - grows with chat activity | -| 2026-02-08 | 19-01 | Session screen base has proper cleanup | Not primary leak source - hooks have cleanup functions | -| 2026-02-08 | 20-01 | Use Set comparison for mixer removal detection | Efficient Set.has() lookup for removed mixers | -| 2026-02-08 | 20-01 | Track previous mixer IDs with ref | Avoids re-render triggers from tracking state | -| 2026-02-08 | 20-01 | Guard cleanup with isReadyRedux check | Prevents false positives during initial mount | -| 2026-02-08 | 21-01 | MAX_MESSAGES = 500 per channel | Sufficient for long sessions while bounding memory | -| 2026-02-08 | 21-01 | Preserve lastReadAt across sessions | Keeps unread badge accurate for UX continuity | -| 2026-02-08 | 21-01 | Clear chat before session state | Ensures proper cleanup order | -| 2026-02-08 | 22-01 | useRef for callback cleanup stability | Avoids stale closure issues on unmount | -| 2026-02-10 | 23-01 | UAT checklist for manual memory profiling | Cannot fully automate Chrome DevTools verification | -| 2026-02-10 | 23-01 | 15+ minute stability as primary metric | Reflects real-world usage patterns | -| 2026-02-19 | 24-01 | Unpack recordSettings to individual params | C++ client expects individual params, not objects | -| 2026-02-19 | 24-01 | Match legacy recordingModel.js signature | Ensures compatibility with existing C++ client | -| 2026-02-24 | 25-01 | Conditional cleanup for window.JK callbacks | Multiple hook instances share callbacks - only delete if we own them | -| 2026-02-24 | 25-01 | Ignore flag pattern for async operations | Prevents state updates on unmounted components | +Recent decisions (v1.5): +- Conditional cleanup for window.JK callbacks (prevents race conditions with multiple hook instances) +- Ignore flag pattern for async operations (prevents state updates on unmounted components) ### Deferred Issues @@ -96,6 +76,7 @@ Decisions are logged in PROJECT.md Key Decisions table. 4. **WebSocket chat messages only broadcast to musicians** (Medium) - From v1.2 5. **mp3 backend support** (Medium) - Frontend allows, backend whitelist doesn't support 6. **Pre-existing test failures in JKChatMessageList.test.js** (Low) - Missing activeSession state +7. **Duplicate recording start paths** (Low) - doStartRecording vs useRecordingHelpers.startRecording (from v1.5) ### Roadmap Evolution @@ -104,20 +85,13 @@ Decisions are logged in PROJECT.md Key Decisions table. - **v1.2 Session Attachments** (Phases 12-16): Shipped 2026-02-07 - **v1.3 Session Settings Tests** (Phases 17-18): Shipped 2026-02-08 - **v1.4 Memory Leak Prevention** (Phases 19-23): Shipped 2026-02-10 -- **v1.5 Fix Session Recording** (Phases 24-25): Shipped 2026-02-24 +- **v1.5 Fix Session Recording** (Phases 24-25): Shipped 2026-02-25 ## Session Continuity -Last session: 2026-02-24 -Stopped at: Completed 25-01-PLAN.md +Last session: 2026-02-25 +Stopped at: v1.5 milestone complete Resume file: None -**v1.5 Fix Session Recording - COMPLETE** - -All phases completed: -- Phase 24: Fix Recording Crash - COMPLETE (24-01) -- Phase 25: Memory Leak Audit - COMPLETE (25-01) - **Next steps:** -- v1.5 is complete -- Ready for next feature or bug fix cycle +1. `/gsd:new-milestone` to plan next feature work diff --git a/.planning/v1.5-MILESTONE-AUDIT.md b/.planning/milestones/v1.5-MILESTONE-AUDIT.md similarity index 100% rename from .planning/v1.5-MILESTONE-AUDIT.md rename to .planning/milestones/v1.5-MILESTONE-AUDIT.md diff --git a/.planning/milestones/v1.5-REQUIREMENTS.md b/.planning/milestones/v1.5-REQUIREMENTS.md new file mode 100644 index 000000000..e91eb7043 --- /dev/null +++ b/.planning/milestones/v1.5-REQUIREMENTS.md @@ -0,0 +1,96 @@ +# Requirements Archive: v1.5 Fix Session Recording + +**Archived:** 2026-02-25 +**Status:** ✅ SHIPPED + +This is the archived requirements specification for v1.5. +For current requirements, see `.planning/REQUIREMENTS.md` (created for next milestone). + +--- + +# Requirements: Fix Session Recording + +**Defined:** 2026-02-19 +**Core Value:** Fix recording so users can record their jam sessions without crashes + +## v1.5 Requirements + +Requirements for fixing session recording. Each maps to roadmap phases. + +### Crash Fix + +- [x] **CRASH-01**: Call RegisterRecordingCallbacks before recording operations ✓ +- [x] **CRASH-02**: Use correct method name StartRecording (not StartMediaRecording) ✓ *Moot - original research incorrect* +- [x] **CRASH-03**: Use correct method name StopRecording (not FrontStopRecording) ✓ *Moot - original research incorrect* +- [x] **CRASH-04**: Pass individual parameters to StartRecording (not settings object) ✓ *Moot - original research incorrect* + +**Note:** CRASH-02/03/04 were based on incorrect research. Actual crash fix was JSON parsing in rest.js. Recording works with original method names (StartMediaRecording, FrontStopRecording). + +### Basic Controls + +- [x] **CTRL-01**: Start recording works - initiates recording like desktop native app ✓ *Implicitly satisfied* +- [x] **CTRL-02**: Stop recording works - ends recording like desktop native app ✓ *Implicitly satisfied* +- [ ] **CTRL-03**: Pause recording works - pauses recording like desktop native app *Not tested* + +**Note:** CTRL requirements were not explicitly mapped to phases but start/stop verified working by user during Phase 24 testing. + +### Memory Leak Audit + +- [x] **MEM-01**: Audit recording modal useEffect cleanup functions ✓ +- [x] **MEM-02**: Audit timer/interval cleanup during recording lifecycle ✓ +- [x] **MEM-03**: Verify no memory growth while recording modal is open ✓ + +## Future Requirements + +Deferred to future milestones. + +### Recording Management + +- **RMGT-01**: Track selection - Choose which tracks to include in recording +- **RMGT-02**: Recording playback - Play back recordings within the modal +- **RMGT-03**: Recording management - Save, delete, rename recordings + +## Out of Scope + +Explicitly excluded for this milestone. + +| Feature | Reason | +|---------|--------| +| Track selection | Keep v1.5 focused on crash fix and basic controls | +| Recording playback | Not blocking core recording functionality | +| Recording management | Defer to future milestone | +| Backend changes | Frontend-only fixes | +| Metronome | Separate feature | + +## Traceability + +Which phases cover which requirements. + +| Requirement | Phase | Status | +|-------------|-------|--------| +| CRASH-01 | Phase 24 | Complete | +| CRASH-02 | Phase 24 | Complete (moot - research incorrect) | +| CRASH-03 | Phase 24 | Complete (moot - research incorrect) | +| CRASH-04 | Phase 24 | Complete (moot - research incorrect) | +| CTRL-01 | — | Complete (implicit, user verified) | +| CTRL-02 | — | Complete (implicit, user verified) | +| CTRL-03 | — | Not tested | +| MEM-01 | Phase 25 | Complete | +| MEM-02 | Phase 25 | Complete | +| MEM-03 | Phase 25 | Complete | + +**Coverage:** +- v1.5 requirements: 10 total +- Complete: 9 +- Not tested: 1 (CTRL-03 pause) + +--- + +## Milestone Summary + +**Shipped:** 9 of 10 v1.5 requirements +**Adjusted:** CRASH-02/03/04 research was incorrect, actual fix was JSON parsing +**Not tested:** CTRL-03 (pause recording) + +--- +*Archived: 2026-02-25 as part of v1.5 milestone completion* diff --git a/.planning/milestones/v1.5-ROADMAP.md b/.planning/milestones/v1.5-ROADMAP.md new file mode 100644 index 000000000..1c4fef357 --- /dev/null +++ b/.planning/milestones/v1.5-ROADMAP.md @@ -0,0 +1,95 @@ +# Milestone v1.5: Fix Session Recording + +**Status:** ✅ SHIPPED 2026-02-25 +**Phases:** 24-25 +**Total Plans:** 2 + +## Overview + +Fixed session recording crash and memory leaks to enable stable, long-duration recording sessions. + +## Phases + +### Phase 24: Fix Recording Crash + +**Goal**: Fix C++ client crash when Start Recording is clicked +**Depends on**: None +**Plans**: 1 plan + +Plans: +- [x] 24-01: Fix method names and parameters in useRecordingHelpers.js and JKSessionScreen.js + +**Details:** + +Requirements: +- CRASH-01: Call RegisterRecordingCallbacks before recording operations (ALREADY DONE in JKSessionScreen.js line 500) +- CRASH-02: Use correct method name StartRecording (not StartMediaRecording) +- CRASH-03: Use correct method name StopRecording (not FrontStopRecording) +- CRASH-04: Pass individual parameters to StartRecording (not settings object) + +Success Criteria: +1. RegisterRecordingCallbacks is called during session or recording modal initialization +2. StartRecording method name matches legacy implementation +3. StopRecording method name matches legacy implementation +4. Parameters to StartRecording match legacy signature (id, tracks, video, chat, framerate) + +Key Files: +- `jam-ui/src/hooks/useRecordingHelpers.js` +- `jam-ui/src/components/client/JKSessionScreen.js` +- `jam-ui/src/components/client/JKSessionRecordingModal.js` + +**Note:** Original research was incorrect. Actual fix was JSON parsing in rest.js (recording.id undefined). Method name changes (CRASH-02/03/04) were applied then reverted as StartMediaRecording is the correct method. + +--- + +### Phase 25: Memory Leak Audit + +**Goal**: Audit and fix memory leaks in recording modal +**Depends on**: Phase 24 (crash must be fixed first) +**Plans**: 1 plan + +Plans: +- [x] 25-01: Fix timer, callback, and async cleanup in recording components + +**Details:** + +Requirements: +- MEM-01: Audit recording modal useEffect cleanup functions +- MEM-02: Audit timer/interval cleanup during recording lifecycle +- MEM-03: Verify no memory growth while recording modal is open + +Success Criteria: +1. All useEffect hooks in recording modal have proper cleanup functions +2. All timers/intervals are cleared on unmount or state change +3. Recording modal can remain open 15+ minutes without memory growth + +Key Files: +- `jam-ui/src/components/client/JKSessionRecordingModal.js` +- `jam-ui/src/hooks/useRecordingHelpers.js` + +--- + +## Milestone Summary + +**Key Decisions:** +- Conditional cleanup for window.JK callbacks (multiple hook instances share globals) +- Ignore flag pattern for async operations in useEffect +- Unpack recordSettings to individual params for C++ client compatibility + +**Issues Resolved:** +- C++ client crash on Start Recording (JSON parsing fix) +- Memory leaks in recording modal (timer, callback, async cleanup) +- "State update on unmounted component" warnings eliminated + +**Issues Deferred:** +- CTRL-01/02/03 basic controls requirements (not explicitly mapped to phases) +- Duplicate recording start paths (doStartRecording vs useRecordingHelpers) +- Documentation inconsistency in 24-VERIFICATION.md + +**Technical Debt Incurred:** +- 24-VERIFICATION.md describes reverted code +- Traceability table references non-existent Phase 26 + +--- + +*For current project status, see .planning/ROADMAP.md*