From 9174d161c630fe8d72929ff69117e697cfd30c3d Mon Sep 17 00:00:00 2001 From: Nuwan Date: Tue, 3 Mar 2026 19:57:32 +0530 Subject: [PATCH] docs: start milestone v1.7 Performance Optimization MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .planning/PROJECT.md | 5 +- .planning/REQUIREMENTS.md | 94 ++++++++++++++++++++++++++++++++ .planning/ROADMAP.md | 112 ++++++++++++++++++++++++++++++++++++++ .planning/STATE.md | 54 ++++++++++++------ 4 files changed, 246 insertions(+), 19 deletions(-) create mode 100644 .planning/REQUIREMENTS.md create mode 100644 .planning/ROADMAP.md diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md index b4509a572..f2ac2c2a1 100644 --- 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* diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md new file mode 100644 index 000000000..ccad707a2 --- /dev/null +++ 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* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 000000000..53ec698fb --- /dev/null +++ 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* diff --git a/.planning/STATE.md b/.planning/STATE.md index ef3e87552..8dca629b8 100644 --- 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