docs: start milestone v1.7 Performance Optimization

Goals: - Eliminate page freezes from excessive React re-renders - Optimize VU meter updates (50-70/sec → batched RAF) - Prevent cascading re-renders with memoization - Apply React best practices for granular updates Phases: 28. VU Meter Optimization 29. Context Optimization 30. Component Memoization 31. Selector Optimization 32. State Update Optimization 19 requirements across 5 phases. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-03-03 19:57:32 +05:30 · 2026-03-03 19:57:32 +05:30 · 9174d161c6
parent 4c4ee9253b
commit 9174d161c6
4 changed files with 246 additions and 19 deletions
--- a/.planning/PROJECT.md
+++ b/.planning/PROJECT.md
@ -16,6 +16,9 @@ Transform session features from the legacy web project into modern React pattern
 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)

@ -167,4 +170,4 @@ Transform session features from the legacy web project into modern React pattern
 - `jam-ui/src/store/features/mixersSlice.js` - Mixer state with removeVuState

 ---
-*Last updated: 2026-03-03 after v1.6 Media Features Polish milestone shipped*
+*Last updated: 2026-03-03 after v1.7 Performance Optimization milestone started*
--- a/.planning/REQUIREMENTS.md
+++ b/.planning/REQUIREMENTS.md
@ -0,0 +1,94 @@
+# Requirements: v1.7 Performance Optimization
+
+**Defined:** 2026-03-03
+**Core Value:** Eliminate page freezes by reducing unnecessary React re-renders
+
+## v1.7 Requirements
+
+Requirements for optimizing render performance in session screen components.
+
+### VU Meter Optimization
+
+- [ ] **VU-01**: VU meter updates use requestAnimationFrame batching instead of immediate state updates
+- [ ] **VU-02**: VU meter components use refs for direct DOM updates (bypass React reconciliation)
+- [ ] **VU-03**: VU data stored in external store (useSyncExternalStore pattern)
+
+### Context Optimization
+
+- [ ] **CTX-01**: MixersContext value is memoized to prevent unnecessary re-renders
+- [ ] **CTX-02**: Split MixersContext into separate VuContext and MixerConfigContext
+- [ ] **CTX-03**: Context consumers only subscribe to data they actually use
+
+### Component Memoization
+
+- [ ] **MEMO-01**: JKSessionAudioInputs wrapped with React.memo
+- [ ] **MEMO-02**: JKSessionRemoteTracks wrapped with React.memo
+- [ ] **MEMO-03**: SessionTrackVU wrapped with React.memo (if not using refs)
+- [ ] **MEMO-04**: SessionTrackGain wrapped with React.memo
+
+### Selector Optimization
+
+- [ ] **SEL-01**: Consolidate 18+ individual selectors in useMixerHelper into composed selectors
+- [ ] **SEL-02**: Use createSelector for memoized derived data
+- [ ] **SEL-03**: Apply shallowEqual comparison for object selectors
+
+### State Update Optimization
+
+- [ ] **STATE-01**: Consolidate triple track sync calls into single debounced call
+- [ ] **STATE-02**: Fix debounce instance recreation in useSessionModel.trackChanges
+- [ ] **STATE-03**: Prevent array recreation in mixer categorization when content is identical
+
+### State Colocation
+
+- [ ] **COLOC-01**: Move resyncLoading state from JKSessionScreen to ResyncButton component
+- [ ] **COLOC-02**: Move videoLoading state from JKSessionScreen to VideoButton component
+- [ ] **COLOC-03**: Audit other local states that can be moved to child components
+
+## Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| External VU store over Redux | VU updates at 50-70/sec would overwhelm Redux; external store bypasses React reconciliation |
+| Context splitting | Separates high-frequency (VU) from low-frequency (config) updates |
+| React.memo over PureComponent | Functional components are standard in codebase; memo provides same benefits |
+| requestAnimationFrame batching | Limits updates to 60fps max, matches display refresh rate |
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| Virtualization for track lists | Only beneficial with 10+ participants; complexity not justified for typical sessions |
+| Web Workers for VU processing | Overkill; RAF batching should be sufficient |
+| Complete state management rewrite | Too risky; incremental optimization preferred |
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| VU-01 | Phase 28 | Pending |
+| VU-02 | Phase 28 | Pending |
+| VU-03 | Phase 28 | Pending |
+| CTX-01 | Phase 29 | Pending |
+| CTX-02 | Phase 29 | Pending |
+| CTX-03 | Phase 29 | Pending |
+| MEMO-01 | Phase 30 | Pending |
+| MEMO-02 | Phase 30 | Pending |
+| MEMO-03 | Phase 30 | Pending |
+| MEMO-04 | Phase 30 | Pending |
+| SEL-01 | Phase 31 | Pending |
+| SEL-02 | Phase 31 | Pending |
+| SEL-03 | Phase 31 | Pending |
+| STATE-01 | Phase 32 | Pending |
+| STATE-02 | Phase 32 | Pending |
+| STATE-03 | Phase 32 | Pending |
+| COLOC-01 | Phase 32 | Pending |
+| COLOC-02 | Phase 32 | Pending |
+| COLOC-03 | Phase 32 | Pending |
+
+**Coverage:**
+- v1.7 requirements: 19 total
+- Mapped to phases: 19
+- Unmapped: 0 ✓
+
+---
+*Requirements defined: 2026-03-03*
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@ -0,0 +1,112 @@
+# Roadmap: JamKazam Media Features Modernization
+
+## Milestones
+
+- v1.0 Media Players (Phases 1-4) - SHIPPED 2026-01-14
+- v1.1 Music Session Chat (Phases 5-10) - SHIPPED 2026-01-27
+- v1.2 Session Attachments (Phases 11-14) - SHIPPED 2026-02-07
+- v1.3 Session Settings Tests (Phases 15-17) - SHIPPED 2026-02-08
+- v1.4 Memory Leak Prevention (Phases 18-22) - SHIPPED 2026-02-10
+- v1.5 Fix Session Recording (Phases 23-25) - SHIPPED 2026-02-25
+- v1.6 Media Features Polish (Phases 26-27) - SHIPPED 2026-03-03
+- **v1.7 Performance Optimization** (Phases 28-32) - IN PROGRESS
+
+## Overview
+
+v1.7 eliminates page freezes caused by excessive React re-renders. The primary culprits are VU meter updates (50-70/sec), unoptimized context providers, missing component memoization, and redundant state updates. Each phase targets a specific optimization category with measurable impact.
+
+## Phases
+
+- [ ] **Phase 28: VU Meter Optimization** - External store + RAF batching for high-frequency VU updates
+- [ ] **Phase 29: Context Optimization** - Memoize and split MixersContext to isolate update frequency
+- [ ] **Phase 30: Component Memoization** - Apply React.memo to prevent cascade re-renders
+- [ ] **Phase 31: Selector Optimization** - Consolidate and memoize Redux selectors
+- [ ] **Phase 32: State Update Optimization** - Debounce, colocate, and deduplicate state updates
+
+## Phase Details
+
+### Phase 28: VU Meter Optimization
+**Goal**: VU meter updates no longer trigger React reconciliation
+**Depends on**: v1.6 complete
+**Requirements**: VU-01, VU-02, VU-03
+**Success Criteria** (what must be TRUE):
+  1. VU data flows through external store, not Redux
+  2. VU components use refs for direct DOM updates
+  3. React DevTools Profiler shows 0 re-renders from VU updates
+  4. Session screen remains responsive during 10+ minute session
+**Plans**: TBD
+
+Plans:
+- [ ] 28-01: TBD
+
+### Phase 29: Context Optimization
+**Goal**: Context changes only re-render components that use the changed data
+**Depends on**: Phase 28 (VU separated from context)
+**Requirements**: CTX-01, CTX-02, CTX-03
+**Success Criteria** (what must be TRUE):
+  1. MixersContext.Provider value is memoized
+  2. VuContext separated from MixerConfigContext
+  3. Volume slider change doesn't re-render VU meters
+  4. VU update doesn't re-render volume sliders
+**Plans**: TBD
+
+Plans:
+- [ ] 29-01: TBD
+
+### Phase 30: Component Memoization
+**Goal**: Child components don't re-render when parent re-renders with same props
+**Depends on**: Phase 29 (context optimized)
+**Requirements**: MEMO-01, MEMO-02, MEMO-03, MEMO-04
+**Success Criteria** (what must be TRUE):
+  1. JKSessionAudioInputs wrapped with React.memo
+  2. JKSessionRemoteTracks wrapped with React.memo
+  3. Track components only re-render when their specific track data changes
+  4. React DevTools shows stable render counts for memoized components
+**Plans**: TBD
+
+Plans:
+- [ ] 30-01: TBD
+
+### Phase 31: Selector Optimization
+**Goal**: Redux selectors compute efficiently with memoization
+**Depends on**: Nothing (independent of Phase 28-30)
+**Requirements**: SEL-01, SEL-02, SEL-03
+**Success Criteria** (what must be TRUE):
+  1. useMixerHelper uses composed selectors instead of 18+ individual selectors
+  2. Derived data uses createSelector for memoization
+  3. Object selectors use shallowEqual comparison
+  4. Single mixer field change triggers 1-3 selector runs (not 18+)
+**Plans**: TBD
+
+Plans:
+- [ ] 31-01: TBD
+
+### Phase 32: State Update Optimization
+**Goal**: Redundant and cascading state updates eliminated
+**Depends on**: Nothing (independent of Phase 28-31)
+**Requirements**: STATE-01, STATE-02, STATE-03, COLOC-01, COLOC-02, COLOC-03
+**Success Criteria** (what must be TRUE):
+  1. Track sync fires once per session join (not 3 times)
+  2. Debounce in trackChanges uses stable reference
+  3. Mixer categorization doesn't dispatch when content unchanged
+  4. Loading states moved to components that use them
+  5. JKSessionScreen re-render count reduced by 50%+
+**Plans**: TBD
+
+Plans:
+- [ ] 32-01: TBD
+
+## Progress
+
+**Execution Order:** Phase 28 first (highest impact), then 29-30 (depend on 28), then 31-32 (independent)
+
+| Phase | Milestone | Plans Complete | Status | Completed |
+|-------|-----------|----------------|--------|-----------|
+| 28. VU Meter Optimization | v1.7 | 0/TBD | Not started | - |
+| 29. Context Optimization | v1.7 | 0/TBD | Not started | - |
+| 30. Component Memoization | v1.7 | 0/TBD | Not started | - |
+| 31. Selector Optimization | v1.7 | 0/TBD | Not started | - |
+| 32. State Update Optimization | v1.7 | 0/TBD | Not started | - |
+
+---
+*v1.7 roadmap created 2026-03-03*
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@ -5,16 +5,16 @@
 See: .planning/PROJECT.md (updated 2026-03-03)

 **Core value:** Modernize session features from legacy jQuery/Rails to React patterns
-**Current focus:** v1.6 complete — ready for next milestone planning
+**Current focus:** v1.7 Performance Optimization - Eliminate page freezes from excessive re-renders

 ## Current Position

-Phase: 27 of 27 (v1.6 complete)
-Plan: All plans complete
-Status: Milestone shipped
-Last activity: 2026-03-03 — v1.6 Media Features Polish shipped
+Phase: 28 of 32 (VU Meter Optimization)
+Plan: Not started
+Status: Ready to plan
+Last activity: 2026-03-03 — v1.7 Performance Optimization milestone started

-Progress: [██████████] 100%
+Progress: [░░░░░░░░░░] 0%

 ## Performance Metrics

@ -23,10 +23,10 @@ Progress: [██████████] 100%
 - Total phases completed: 27
 - Total plans completed: 49

-**v1.6 Media Features Polish (SHIPPED 2026-03-03):**
- Phases: 2 (phases 26-27)
- Requirements: 6 shipped, 2 descoped
- Plans completed: 5 (26-01, 26-02, 26-03, 26-04, 27-01)
+**v1.7 Performance Optimization (In Progress):**
+- Phases: 5 (phases 28-32)
+- Requirements: 19
+- Plans completed: 0

 ## Accumulated Context

@ -34,12 +34,29 @@ Progress: [██████████] 100%

 See PROJECT.md Key Decisions table for full history.

-Recent decisions (v1.6):
- Defer JamTrack UI until synchronized (prevents empty controls)
- WindowPortal sizing 460x350 (matches content plus padding)
- openBackingTrack action for centralized Redux + server sync
- Prevent multiple media players (one at a time)
- Descope Metronome debounce (responsiveness satisfactory)
+Recent decisions (v1.7):
+- External VU store over Redux (50-70 updates/sec would overwhelm Redux)
+- Context splitting (separates high-frequency from low-frequency updates)
+- React.memo over PureComponent (functional components standard in codebase)
+- requestAnimationFrame batching (limits to 60fps, matches display refresh)
+
+### Investigation Findings (v1.7)
+
+**Root causes of page freezes:**
+1. VU meter updates at 50-70/sec through Redux
+2. MixersContext creates new reference every render
+3. 18+ individual selectors in useMixerHelper
+4. Triple track sync calls on session join
+5. Debounce instance recreation on dependency change
+6. Missing React.memo on child components
+
+**Hotspot files:**
+- `useMixerStore.js:178-185` - VU update dispatch
+- `useVuHelpers.js:99-104` - setVuStates object creation
+- `mixersSlice.js:145-165` - updateMixer creates new objects
+- `JKSessionScreen.js:463-475` - Triple track sync calls
+- `useSessionModel.js:605-614` - Debounced trackChanges
+- `MixersContext.js:10` - Unmemoized context value

 ### Deferred Issues

@ -60,12 +77,13 @@ Recent decisions (v1.6):
 - **v1.4 Memory Leak Prevention** (Phases 19-23): Shipped 2026-02-10
 - **v1.5 Fix Session Recording** (Phases 24-25): Shipped 2026-02-25
 - **v1.6 Media Features Polish** (Phases 26-27): Shipped 2026-03-03
+- **v1.7 Performance Optimization** (Phases 28-32): In Progress

 ## Session Continuity

 Last session: 2026-03-03
-Stopped at: v1.6 milestone complete
+Stopped at: v1.7 milestone initialized
 Resume file: None

 **Next steps:**
-1. `/gsd:new-milestone` — start next milestone (questioning → research → requirements → roadmap)
+1. `/gsd:plan-phase 28` — plan VU Meter Optimization phase