# Project State

## Project Reference

See: .planning/PROJECT.md (updated 2026-03-03)

**Core value:** Modernize session features from legacy jQuery/Rails to React patterns
**Current focus:** v1.7 Performance Optimization - Eliminate page freezes from excessive re-renders

## Current Position

Phase: v1.7 Complete
Plan: All stable phases complete (28, 29, 30)
Status: Milestone shipped
Last activity: 2026-03-06 — v1.7 shipped (Phases 31-32 reverted)

Progress: [██████████] 100%

## Performance Metrics

**v1.0 - v1.6 Summary:**
- Total milestones shipped: 7
- Total phases completed: 27
- Total plans completed: 49

**v1.7 Performance Optimization (In Progress):**
- Phases: 5 (phases 28-32)
- Phases completed: 3 (Phases 28, 29, 30)
- Phases reverted: 2 (Phases 31, 32 caused VU/slider perf regression)
- Requirements: 19 (15 complete)
- Plans completed: 7

## Accumulated Context

### Decisions

See PROJECT.md Key Decisions table for full history.

Recent decisions (v1.7):
- External VU store over Redux (50-70 updates/sec would overwhelm Redux) - 28-01
- useSyncExternalStore shim for React 16 compatibility - 28-01
- Dual hook API (useAllVuLevels and useVuLevel) for flexibility - 28-01
- RAF batching centralized in store vs per-component - 28-01
- 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)
- Route VU data directly to vuStore in bridge callback, bypassing React state - 28-02
- Per-component RAF loops over centralized subscription system (simpler for multiple mixer IDs) - 28-02
- React.memo on SessionTrackVU to prevent parent re-render propagation - 28-02
- className assignment over classList.add/remove for DOM efficiency - 28-02
- getMixer stabilization via useCallback prevents cascade of function recreations - 29-01
- Context value memoization only effective when hook functions are stable - 29-01
- React.memo on consumers completes the optimization chain - 29-01
- Container component memoization completes memoization chain from Phase 29 - 30-01
- Default shallow comparison sufficient when props are stable from upstream - 30-01
- Group selectors by usage pattern (core, track, lookup, metadata) - 31-01 - REVERTED
- shallowEqual with composed selectors for object return comparisons - 31-01 - REVERTED
- 1.5s debounce delay for track sync covers mixer initialization window - 32-01 - REVERTED
- useDebounceCallback with ref pattern prevents stale closures - 32-01 - REVERTED
- useMemo with empty deps creates stable debounced function - 32-01 - REVERTED
- State colocation: Loading state lives in component that uses it - 32-03 - REVERTED
- React.memo on self-contained button components prevents parent re-renders - 32-03 - REVERTED

**Phase 31-32 Revert (2026-03-06):**
- Composed selectors with shallowEqual caused VU meters to animate slowly
- Phase 32 changes caused volume sliders to be unresponsive
- Root cause: likely blocking main thread during selector evaluation
- Phases 28-30 optimizations remain effective and stable

### Investigation Findings (v1.7)

**Root causes of page freezes:**
1. VU meter updates at 50-70/sec through Redux - FIXED (Phase 28)
2. MixersContext creates new reference every render - FIXED (Phase 29)
3. 18+ individual selectors in useMixerHelper - REVERTED (Phase 31 caused perf regression)
4. Triple track sync calls on session join - REVERTED (Phase 32 caused perf regression)
5. Debounce instance recreation on dependency change - REVERTED (Phase 32 caused perf regression)
6. Missing React.memo on child components - FIXED (Phase 30)
7. Redundant mixer categorization dispatches - REVERTED (Phase 32 caused perf regression)
8. Loading state in parent causing unnecessary re-renders - REVERTED (Phase 32 caused perf regression)

**Hotspot files:**
- `useMixerStore.js:178-185` - VU update dispatch - FIXED
- `useVuHelpers.js:99-104` - setVuStates object creation - FIXED
- `mixersSlice.js:145-165` - updateMixer creates new objects
- `JKSessionScreen.js:463-475` - Triple track sync calls - REVERTED
- `useSessionModel.js:605-614` - Debounced trackChanges - REVERTED
- `MixersContext.js:10` - Unmemoized context value - FIXED
- `useMixerHelper.js:291-295` - Unconditional category dispatches - REVERTED

### Deferred Issues

1. **End-of-track restart requires double-click** (Minor) - From v1.0
2. **Loop functionality not working** (Medium) - From v1.0
3. **Volume control not working in popup mode** (Medium) - From v1.0
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) - From v1.5

### Roadmap Evolution

- **v1.0 Media Players** (Phases 1-5): Shipped 2026-01-14
- **v1.1 Music Session Chat** (Phases 6-11): Shipped 2026-01-31
- **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-25
- **v1.6 Media Features Polish** (Phases 26-27): Shipped 2026-03-03
- **v1.7 Performance Optimization** (Phases 28-30): Shipped 2026-03-06

## Session Continuity

Last session: 2026-03-06
Stopped at: v1.7 milestone shipped
Resume file: None

**Next steps:**
1. Merge fix_for_page_freeze branch to develop
2. Plan v1.8 milestone if needed