# 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

- [x] **Phase 28: VU Meter Optimization** - External store + RAF batching for high-frequency VU updates ✓
- [x] **Phase 29: Context Optimization** - Memoize and split MixersContext to isolate update frequency ✓
- [x] **Phase 30: Component Memoization** - Apply React.memo to prevent cascade re-renders ✓
- [x] **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**: 2 plans

Plans:
- [x] 28-01-PLAN.md — Create external VU store infrastructure (vuStore + useVuStore hook) ✓
- [x] 28-02-PLAN.md — Wire components to use external store with direct DOM updates ✓

### 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**: 1 plan

Plans:
- [x] 29-01-PLAN.md — Memoize context providers (MixersContext, VuContext, GlobalContext) and wrap consumers with React.memo ✓

### 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**: 1 plan

Plans:
- [x] 30-01-PLAN.md — Wrap JKSessionAudioInputs and JKSessionRemoteTracks with React.memo ✓

### 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**: 1 plan

Plans:
- [x] 31-01-PLAN.md — Create composed selectors with createSelector and refactor useMixerHelper to use shallowEqual ✓

### 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 | 2/2 | ✓ Complete | 2026-03-05 |
| 29. Context Optimization | v1.7 | 1/1 | ✓ Complete | 2026-03-05 |
| 30. Component Memoization | v1.7 | 1/1 | ✓ Complete | 2026-03-05 |
| 31. Selector Optimization | v1.7 | 1/1 | ✓ Complete | 2026-03-05 |
| 32. State Update Optimization | v1.7 | 0/TBD | Not started | - |

---
*v1.7 roadmap created 2026-03-03*