From 1512f646eaca01933bcbfb769995119c25ace3df Mon Sep 17 00:00:00 2001 From: Nuwan Date: Thu, 19 Feb 2026 15:04:30 +0530 Subject: [PATCH] docs: start milestone v1.5 Fix Session Recording Scope: - Phase 24: Fix C++ client crash on Start Recording - Phase 25: Verify Start/Stop/Pause work like desktop native app - Phase 26: Memory leak audit for recording modal Research findings: - Missing RegisterRecordingCallbacks call - Wrong method names (StartMediaRecording vs StartRecording) - Parameter format mismatch 10 requirements across 3 phases. Co-Authored-By: Claude Opus 4.5 --- .planning/PROJECT.md | 47 ++++++--- .planning/REQUIREMENTS.md | 75 +++++++++++++ .planning/ROADMAP.md | 100 ++++++++++++++++++ .planning/STATE.md | 29 ++--- .planning/research/RECORDING-ANALYSIS.md | 129 +++++++++++++++++++++++ 5 files changed, 349 insertions(+), 31 deletions(-) create mode 100644 .planning/REQUIREMENTS.md create mode 100644 .planning/ROADMAP.md create mode 100644 .planning/research/RECORDING-ANALYSIS.md diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md index 197ff5f24..e3fdbea7f 100644 --- a/.planning/PROJECT.md +++ b/.planning/PROJECT.md @@ -16,9 +16,11 @@ Transform session features from the legacy web project into modern React pattern **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 + **Future Work:** - **Metronome** - Tempo/sound configuration and playback (deferred) -- **Recording Modal Performance** - Audit recording modal for memory leaks (deferred) ## Context @@ -105,12 +107,27 @@ Transform session features from the legacy web project into modern React pattern - ✓ 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 + ### Out of Scope -- **Recording modal** - Separate milestone for recording-specific performance -- **New features** - Focus purely on fixing existing memory leaks +- **Additional recording controls** - Track selection, playback, management deferred - **Backend changes** - Frontend-only fixes -- **Refactoring beyond leak fixes** - Minimal changes to fix leaks +- **Metronome** - Separate feature, not part of this milestone ## Key Decisions @@ -144,20 +161,16 @@ Transform session features from the legacy web project into modern React pattern ## 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 +**v1.5 Fix Session Recording (Current Focus):** +- Recording modal component (needs identification) +- `jam-ui/src/services/jamClientProxy.js` - C++ client bridge for recording commands +- Legacy recording implementation for reference **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 +- jamClient recording API calls causing C++ crash +- Recording modal useEffect cleanup +- Timer/interval cleanup during recording +- State management during recording lifecycle --- -*Last updated: 2026-02-18 after v1.4 Memory Leak Prevention milestone complete* +*Last updated: 2026-02-19 after v1.5 Fix Session Recording milestone started* diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md new file mode 100644 index 000000000..18b955771 --- /dev/null +++ b/.planning/REQUIREMENTS.md @@ -0,0 +1,75 @@ +# 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 + +- [ ] **CRASH-01**: Call RegisterRecordingCallbacks before recording operations +- [ ] **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) + +### 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 | Pending | +| CRASH-02 | Phase 24 | Pending | +| CRASH-03 | Phase 24 | Pending | +| CRASH-04 | Phase 24 | Pending | +| 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 initial definition* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 000000000..1b59f7c3c --- /dev/null +++ b/.planning/ROADMAP.md @@ -0,0 +1,100 @@ +# Roadmap: Fix Session Recording (v1.5) + +**Created:** 2026-02-19 +**Milestone:** v1.5 Fix Session Recording +**Phases:** 24-26 (continues from v1.4) + +## Overview + +| # | Phase | Goal | Requirements | Success Criteria | +|---|-------|------|--------------|------------------| +| 24 | Fix Recording Crash | Fix C++ client crash on Start Recording | CRASH-01, CRASH-02, CRASH-03, CRASH-04 | 4 | +| 25 | Verify Basic Controls | Verify Start/Stop/Pause work like desktop native app | CTRL-01, CTRL-02, CTRL-03 | 3 | +| 26 | Memory Leak Audit | Audit and fix memory leaks in recording modal | MEM-01, MEM-02, MEM-03 | 3 | + +**Total:** 3 phases | 10 requirements | 10 success criteria + +--- + +## Phase 24: Fix Recording Crash + +**Goal:** Fix C++ client crash when Start Recording is clicked + +**Requirements:** +- CRASH-01: Call RegisterRecordingCallbacks before recording operations +- 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` +- Recording modal component +- Session initialization code + +--- + +## Phase 25: Verify Basic Controls + +**Goal:** Verify Start/Stop/Pause work like desktop native app + +**Requirements:** +- 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 + +**Success Criteria:** +1. User can click Start Recording and recording begins without crash +2. User can click Stop Recording and recording ends properly +3. Pause control works as expected (or is confirmed not applicable) + +**Dependencies:** Phase 24 (crash must be fixed first) + +**Key Files:** +- Recording modal component +- `jam-ui/src/hooks/useRecordingHelpers.js` + +--- + +## Phase 26: Memory Leak Audit + +**Goal:** Audit and fix memory leaks in recording modal + +**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 25 (controls must work to test memory) + +**Key Files:** +- Recording modal component +- `jam-ui/src/hooks/useRecordingHelpers.js` +- Any recording-related state management + +--- + +## Research Reference + +See: `.planning/research/RECORDING-ANALYSIS.md` + +Key findings: +- Missing `RegisterRecordingCallbacks` call is primary crash cause +- Wrong method names in jam-ui vs legacy +- Parameter format mismatch + +--- +*Roadmap created: 2026-02-19* +*Last updated: 2026-02-19 after initial creation* diff --git a/.planning/STATE.md b/.planning/STATE.md index b88bc054b..5cfae5384 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,19 +2,19 @@ ## Project Reference -See: .planning/PROJECT.md (updated 2026-02-18) +See: .planning/PROJECT.md (updated 2026-02-19) **Core value:** Modernize session features from legacy jQuery/Rails to React patterns -**Current focus:** Planning next milestone +**Current focus:** v1.5 Fix Session Recording ## Current Position -Phase: Ready for next milestone +Phase: 24 (Fix Recording Crash) Plan: Not started -Status: Between milestones (v1.4 complete, v1.5 not started) -Last activity: 2026-02-18 - v1.4 Memory Leak Prevention milestone archived +Status: Ready for planning +Last activity: 2026-02-19 — Roadmap created -Progress: Ready for `/gsd:new-milestone` +Progress: `/gsd:discuss-phase 24` or `/gsd:plan-phase 24` ## Performance Metrics @@ -91,16 +91,17 @@ Decisions are logged in PROJECT.md Key Decisions table. ## Session Continuity -Last session: 2026-02-18 -Stopped at: v1.4 milestone archived +Last session: 2026-02-19 +Stopped at: Roadmap created Resume file: None -**v1.4 Memory Leak Prevention Milestone Archived** +**v1.5 Fix Session Recording** -Archived to: -- `.planning/milestones/v1.4-ROADMAP.md` -- `.planning/milestones/v1.4-REQUIREMENTS.md` +Phases: +- Phase 24: Fix Recording Crash (CRASH-01 to CRASH-04) +- Phase 25: Verify Basic Controls (CTRL-01 to CTRL-03) +- Phase 26: Memory Leak Audit (MEM-01 to MEM-03) **Next steps:** -1. Merge `fix_memory_leaks_take2` branch to develop (optional) -2. Run `/gsd:new-milestone` to start next feature milestone +1. Run `/gsd:discuss-phase 24` to gather context +2. Or `/gsd:plan-phase 24` to plan directly diff --git a/.planning/research/RECORDING-ANALYSIS.md b/.planning/research/RECORDING-ANALYSIS.md new file mode 100644 index 000000000..8d9b1c609 --- /dev/null +++ b/.planning/research/RECORDING-ANALYSIS.md @@ -0,0 +1,129 @@ +# Recording Implementation Analysis + +**Date:** 2026-02-19 +**Purpose:** Compare legacy vs jam-ui recording to identify crash cause + +## Legacy Implementation (jQuery/Rails) - WORKING + +### Initialization Sequence + +In `session.js` (line 145), the legacy app registers recording callbacks during session initialization: + +```javascript +context.jamClient.RegisterRecordingCallbacks( + "JK.HandleRecordingStartResult", + "JK.HandleRecordingStopResult", + "JK.HandleRecordingStarted", + "JK.HandleRecordingStopped", + "JK.HandleRecordingAborted" +); +``` + +The `recordingModel.js` sets up these callback handlers as global functions on `window.JK` (lines 404-408). + +### Start Recording Flow + +```javascript +// recordingModel.js line 99 +jamClient.StartRecording(recording["id"], groupedTracks, recordVideo, recordChat, recordFramerate); +``` +- Parameters: recording ID, grouped client tracks, video flag, chat flag, framerate + +### Stop Recording Flow + +```javascript +// recordingModel.js line 141 +jamClient.StopRecording(recording.id, groupedTracks); +``` +- Parameters: recording ID, grouped client tracks + +### Key Pattern +Callback registration happens BEFORE any recording operations. + +## jam-ui Implementation - INCOMPLETE/BROKEN + +### Current State + +1. **Start Recording** (`useRecordingHelpers.js` line 101): + ```javascript + await jamClient.StartMediaRecording(recording.id, groupedTracks, recordSettings); + ``` + - Wrong method name: `StartMediaRecording` vs `StartRecording` + - Wrong parameters: passes `recordSettings` object instead of individual params + +2. **Stop Recording** (line 166): + ```javascript + await jamClient.FrontStopRecording(recording.id, groupedTracks); + ``` + - Wrong method name: `FrontStopRecording` vs `StopRecording` + +3. **Callback Registration:** + - Lines 408-427 define global handlers on `window.JK` + - `RegisterRecordingCallbacks` is NEVER called + - C++ client doesn't know which callbacks to invoke + +## Identified Gaps + +| Aspect | Legacy App | jam-ui | Status | +|--------|-----------|--------|--------| +| Callback Registration | Done in session init | Only defined, never registered | **CRITICAL GAP** | +| StartRecording Method | `StartRecording(id, tracks, video, chat, framerate)` | `StartMediaRecording(id, tracks, settings)` | **WRONG METHOD** | +| StopRecording Method | `StopRecording(id, tracks)` | `FrontStopRecording(id, tracks)` | **WRONG METHOD** | +| Callback Handlers | Global functions on window.JK | Global functions on window.JK | OK | +| Parameter Format | 5 individual params for Start | Settings object | **FORMAT MISMATCH** | + +## Likely Cause of C++ Client Crash + +1. **Missing RegisterRecordingCallbacks call**: The C++ client doesn't know which JavaScript callbacks to invoke when recording events occur. This causes unhandled callbacks in the C++ layer. + +2. **Wrong method names**: The C++ client expects `StartRecording` not `StartMediaRecording`. These methods may not exist or have different signatures. + +3. **Parameter mismatch**: The C++ client expects unpacked individual parameters, crashes trying to interpret a JavaScript object. + +## Recommended Fix Approach + +### Phase 1: Fix Crash (Critical) + +1. **Add RegisterRecordingCallbacks call** - Call during recording modal mount or session initialization: + ```javascript + await jamClient.RegisterRecordingCallbacks( + "JK.HandleRecordingStartResult", + "JK.HandleRecordingStopResult", + "JK.HandleRecordingStarted", + "JK.HandleRecordingStopped", + "JK.HandleRecordingAborted" + ); + ``` + +2. **Fix method names**: + - `StartMediaRecording` → `StartRecording` + - `FrontStopRecording` → `StopRecording` + +3. **Unpack settings into individual parameters**: + ```javascript + jamClient.StartRecording( + id, + tracks, + recordSettings.videoType || 0, // recordVideo + recordSettings.recordChat ? 1 : 0, // recordChat + 0 // recordFramerate + ); + ``` + +### Phase 2: Verify Controls + +After fixing the crash, verify Start/Stop/Pause work like the desktop native app. + +### Phase 3: Memory Leak Audit + +Audit recording modal for: +- useEffect cleanup functions +- Timer/interval cleanup +- Event listener cleanup +- State management during recording lifecycle + +## Files to Modify + +- Recording modal component (needs identification) +- `jam-ui/src/hooks/useRecordingHelpers.js` - Fix method names and parameters +- Session initialization - Add RegisterRecordingCallbacks call