# Phase 28: VU Meter Optimization - Research

**Researched:** 2026-03-03
**Domain:** React performance optimization for high-frequency UI updates
**Confidence:** HIGH

## Summary

This phase addresses the root cause of page freezes during long sessions: VU meter updates at 50-70 updates/second flowing through React state management, triggering expensive reconciliation cycles. The current implementation uses `useState` in `useVuHelpers.js` to store VU levels, causing React to re-render every time the native C++ client sends a VU update.

The solution involves three complementary patterns:
1. **External VU Store** - Store VU data outside React using `useSyncExternalStore` (with shim for React 16 compatibility)
2. **requestAnimationFrame Batching** - Limit updates to 60fps to match display refresh rate
3. **Direct DOM Updates via Refs** - Bypass React reconciliation entirely for the visual meter updates

**Primary recommendation:** Create a standalone VU store module that buffers incoming VU data, batches updates with requestAnimationFrame, and exposes a subscription API. VU meter components use refs to directly manipulate DOM elements (CSS classes/styles) rather than relying on React state for visual updates.

## Standard Stack

The established libraries/tools for this domain:

### Core
| Library | Version | Purpose | Why Standard |
|---------|---------|---------|--------------|
| use-sync-external-store | ^1.6.0 | useSyncExternalStore shim | Official React shim, works with React 16.8+ |
| React refs (useRef) | built-in | Direct DOM access | Bypasses reconciliation for high-frequency updates |
| requestAnimationFrame | browser API | Frame synchronization | Limits updates to 60fps, matches display refresh |

### Supporting
| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| lodash/throttle | existing | Fallback throttling | If rAF batching insufficient |

### Alternatives Considered
| Instead of | Could Use | Tradeoff |
|------------|-----------|----------|
| External store | Canvas rendering | More complex, overkill for simple meter |
| Direct DOM | CSS animations | Less control over frame-by-frame updates |
| useSyncExternalStore | Zustand | Would add dependency, shim is simpler for this use case |

**Installation:**
```bash
cd jam-ui
npm install use-sync-external-store
```

## Architecture Patterns

### Recommended Project Structure
```
src/
├── stores/
│   └── vuStore.js           # External VU store (NEW)
├── hooks/
│   ├── useVuHelpers.js      # MODIFY: Remove useState, use external store
│   └── useVuStore.js        # NEW: Hook wrapping external store subscription
├── components/
│   └── client/
│       └── SessionTrackVU.js # MODIFY: Use refs for DOM updates
└── context/
    └── VuContext.js         # MODIFY: Simplified, provides store access
```

### Pattern 1: External Store with requestAnimationFrame Batching
**What:** A plain JavaScript module that holds VU state outside React, batches incoming updates, and notifies subscribers on each animation frame.
**When to use:** When data arrives faster than React can efficiently render (50+ updates/sec).
**Example:**
```javascript
// Source: React official docs + best practices for high-frequency data
// src/stores/vuStore.js

let vuLevels = {};  // { mixerId: { level: 0, clipping: false, timestamp: 0 } }
let listeners = new Set();
let pendingUpdates = {};
let rafId = null;

function emitChange() {
  for (const listener of listeners) {
    listener();
  }
}

function flushUpdates() {
  // Merge pending updates into vuLevels
  if (Object.keys(pendingUpdates).length > 0) {
    vuLevels = { ...vuLevels, ...pendingUpdates };
    pendingUpdates = {};
    emitChange();
  }
  rafId = requestAnimationFrame(flushUpdates);
}

export const vuStore = {
  // Called by native client bridge at 50-70/sec
  updateLevel(mixerId, level, clipping) {
    pendingUpdates[mixerId] = { level, clipping, timestamp: performance.now() };
    // Don't emit - rAF loop handles it
  },

  removeLevel(mixerId) {
    delete pendingUpdates[mixerId];
    if (vuLevels[mixerId]) {
      vuLevels = { ...vuLevels };
      delete vuLevels[mixerId];
      emitChange();
    }
  },

  getSnapshot() {
    return vuLevels;  // Must return same reference if unchanged
  },

  subscribe(listener) {
    listeners.add(listener);
    // Start rAF loop when first subscriber
    if (listeners.size === 1 && !rafId) {
      rafId = requestAnimationFrame(flushUpdates);
    }
    return () => {
      listeners.delete(listener);
      // Stop rAF loop when no subscribers
      if (listeners.size === 0 && rafId) {
        cancelAnimationFrame(rafId);
        rafId = null;
      }
    };
  },

  // For single meter subscription (more efficient)
  getLevelSnapshot(mixerId) {
    return vuLevels[mixerId] || null;
  }
};
```

### Pattern 2: Direct DOM Updates with Refs
**What:** VU meter components use refs to directly manipulate DOM elements, bypassing React reconciliation.
**When to use:** For visual updates that happen more than 30 times per second.
**Example:**
```javascript
// Source: React performance best practices
// Direct DOM manipulation for VU lights

function VuMeterDirect({ mixerId, lightCount = 16 }) {
  const containerRef = useRef(null);
  const lightsRef = useRef([]);

  // Subscribe to just this mixer's data
  useEffect(() => {
    let rafId = null;

    const updateVisuals = () => {
      const data = vuStore.getLevelSnapshot(mixerId);
      if (!data || !containerRef.current) return;

      const { level, clipping } = data;
      const activeLights = Math.round(level * lightCount);

      // Direct DOM manipulation - no React involvement
      lightsRef.current.forEach((light, i) => {
        if (!light) return;
        const isActive = (lightCount - 1 - i) < activeLights;
        const positionFromBottom = lightCount - 1 - i;

        // Remove all state classes
        light.classList.remove('vu-bg-success', 'vu-bg-warning', 'vu-bg-danger', 'vu-bg-secondary');

        if (isActive) {
          if (clipping) {
            light.classList.add('vu-bg-danger');
          } else if (positionFromBottom >= Math.floor(lightCount * 0.75)) {
            light.classList.add('vu-bg-danger');
          } else if (positionFromBottom >= Math.floor(lightCount * 0.5)) {
            light.classList.add('vu-bg-warning');
          } else {
            light.classList.add('vu-bg-success');
          }
        } else {
          light.classList.add('vu-bg-secondary');
        }
      });

      rafId = requestAnimationFrame(updateVisuals);
    };

    rafId = requestAnimationFrame(updateVisuals);
    return () => cancelAnimationFrame(rafId);
  }, [mixerId, lightCount]);

  // Render once, never re-render for VU updates
  return (
    <div ref={containerRef} className="vu">
      <div className="d-flex flex-column">
        {Array.from({ length: lightCount }).map((_, i) => (
          <div
            key={i}
            ref={el => lightsRef.current[i] = el}
            className="vu-bg-secondary"
            style={{ height: '10px', width: '25px', marginTop: '1px', borderRadius: '2px', border: '1px solid #eee' }}
          />
        ))}
      </div>
    </div>
  );
}
```

### Pattern 3: useSyncExternalStore Hook Wrapper
**What:** A custom hook that safely subscribes React components to the external store.
**When to use:** When components need to respond to VU changes (e.g., clipping indicators that need to trigger other UI).
**Example:**
```javascript
// Source: React official documentation for useSyncExternalStore
// src/hooks/useVuStore.js

import { useSyncExternalStore } from 'use-sync-external-store/shim';
import { vuStore } from '../stores/vuStore';

// Subscribe to all VU levels (use sparingly - causes re-renders)
export function useAllVuLevels() {
  return useSyncExternalStore(
    vuStore.subscribe,
    vuStore.getSnapshot
  );
}

// Subscribe to single mixer - more efficient
export function useVuLevel(mixerId) {
  const getSnapshot = useCallback(() => vuStore.getLevelSnapshot(mixerId), [mixerId]);
  return useSyncExternalStore(
    vuStore.subscribe,
    getSnapshot
  );
}
```

### Anti-Patterns to Avoid
- **useState for VU levels:** Creates new state on every update, triggers reconciliation
- **Redux for VU data:** 50-70 actions/sec overwhelms Redux DevTools and middleware
- **Context for high-frequency updates:** Each update re-renders all consumers
- **Creating new objects in getSnapshot:** Must return same reference if data unchanged
- **Multiple rAF loops:** Centralize animation handling, don't create per-component loops

## Don't Hand-Roll

Problems that look simple but have existing solutions:

| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| External store subscription | Custom subscription system | useSyncExternalStore shim | Handles concurrent rendering edge cases |
| Frame rate limiting | setInterval/setTimeout | requestAnimationFrame | Syncs with display refresh, pauses when tab hidden |
| React 16 compatibility | Custom useSyncExternalStore | use-sync-external-store npm | Official React team maintained |

**Key insight:** The combination of external store + rAF batching + direct DOM refs is a well-established pattern for this exact problem (high-frequency visual updates). The useSyncExternalStore shim handles React's concurrent rendering complexities that are easy to get wrong with a custom implementation.

## Common Pitfalls

### Pitfall 1: getSnapshot Returns New Object Every Call
**What goes wrong:** Infinite re-render loop or excessive renders
**Why it happens:** useSyncExternalStore uses Object.is() comparison; new objects always differ
**How to avoid:** Store immutable snapshots, return the stored reference directly
**Warning signs:** React DevTools shows constant re-renders, console shows "maximum update depth exceeded"

### Pitfall 2: subscribe Function Recreated Every Render
**What goes wrong:** Unnecessary unsubscribe/resubscribe on every render
**Why it happens:** Defining subscribe inside component creates new function reference each render
**How to avoid:** Define subscribe outside component or use useCallback with stable dependencies
**Warning signs:** VU meters flicker or drop updates during other component updates

### Pitfall 3: Memory Leaks from Uncancelled Animation Frames
**What goes wrong:** rAF callbacks continue after component unmount, accessing null refs
**Why it happens:** Missing cleanup in useEffect, or cleanup doesn't cancel all pending frames
**How to avoid:** Store rafId in ref, cancel in cleanup, check refs before accessing
**Warning signs:** Console errors about "cannot read property of null" after leaving session

### Pitfall 4: Blocking Main Thread with DOM Reads/Writes
**What goes wrong:** Layout thrashing causes jank even at 60fps
**Why it happens:** Interleaving offsetWidth reads with style writes forces browser reflow
**How to avoid:** Batch all reads, then all writes; use classList instead of style for class changes
**Warning signs:** React DevTools Profiler shows long "Commit" times, browser DevTools shows forced reflow

### Pitfall 5: Not Handling Missing Mixers
**What goes wrong:** VU meter crashes when mixer removed mid-session
**Why it happens:** Native client may remove mixer before React component unmounts
**How to avoid:** Always check if mixer/level exists before updating, handle null gracefully
**Warning signs:** Console errors during session participant leave

## Code Examples

Verified patterns from official sources:

### Bridge Callback Integration
```javascript
// Source: Current codebase pattern + optimization
// Modify handleBridgeCallback in useMixerStore.js

import { vuStore } from '../stores/vuStore';

const handleBridgeCallback = useCallback((vuData) => {
  for (const vuInfo of vuData) {
    const eventName = vuInfo[0];
    if (eventName === "vu") {
      const mixerId = vuInfo[1];
      const mode = vuInfo[2];
      const leftValue = vuInfo[3];
      const leftClipping = vuInfo[4];

      // Convert dB to 0.0-1.0 range
      const normalizedLevel = (leftValue + 80) / 80;

      // Create qualified ID matching current pattern
      const fqId = (mode ? 'M' : 'P') + mixerId;

      // Update external store instead of React state
      vuStore.updateLevel(fqId, normalizedLevel, leftClipping);
    }
  }
}, []);
```

### VU Context Simplified
```javascript
// Source: Pattern from codebase + useSyncExternalStore best practices
// Modify VuContext.js

import React, { createContext, useContext } from 'react';
import { vuStore } from '../stores/vuStore';

const VuContext = createContext();

export const VuProvider = ({ children }) => {
  return (
    <VuContext.Provider value={vuStore}>
      {children}
    </VuContext.Provider>
  );
};

export const useVuContext = () => {
  const context = useContext(VuContext);
  if (!context) {
    throw new Error('useVuContext must be used within a VuProvider');
  }
  return context;
};
```

### SessionTrackVU Optimized
```javascript
// Source: Current component + direct DOM pattern
// Modify SessionTrackVU.js

import React, { useEffect, useRef, useCallback, memo } from 'react';
import { vuStore } from '../../stores/vuStore';

const SessionTrackVU = memo(function SessionTrackVU({
  lightCount = 16,
  orientation = 'vertical',
  lightWidth = 15,
  lightHeight = 10,
  mixers
}) {
  const containerRef = useRef(null);
  const lightsRef = useRef([]);
  const mixerIdRef = useRef(null);
  const rafIdRef = useRef(null);

  // Update mixerId when mixers change
  useEffect(() => {
    const mixer = mixers?.vuMixer;
    mixerIdRef.current = mixer ? `${mixer.mode ? 'M' : 'P'}${mixer.id}` : null;

    return () => {
      // Cleanup VU state on unmount
      if (mixerIdRef.current) {
        vuStore.removeLevel(mixerIdRef.current);
      }
    };
  }, [mixers]);

  // Animation loop for direct DOM updates
  useEffect(() => {
    const updateVisuals = () => {
      const mixerId = mixerIdRef.current;
      if (!mixerId) {
        rafIdRef.current = requestAnimationFrame(updateVisuals);
        return;
      }

      const data = vuStore.getLevelSnapshot(mixerId);
      const level = data?.level ?? 0;
      const clipping = data?.clipping ?? false;
      const activeLights = Math.round(level * lightCount);

      // Direct DOM manipulation
      for (let i = 0; i < lightCount; i++) {
        const light = lightsRef.current[i];
        if (!light) continue;

        const positionFromBottom = lightCount - 1 - i;
        const isActive = positionFromBottom < activeLights;

        // Use classList for efficient class manipulation
        light.className = isActive
          ? (clipping || positionFromBottom >= lightCount * 0.75)
            ? 'vu-light vu-bg-danger'
            : (positionFromBottom >= lightCount * 0.5)
              ? 'vu-light vu-bg-warning'
              : 'vu-light vu-bg-success'
          : 'vu-light vu-bg-secondary';
      }

      rafIdRef.current = requestAnimationFrame(updateVisuals);
    };

    rafIdRef.current = requestAnimationFrame(updateVisuals);

    return () => {
      if (rafIdRef.current) {
        cancelAnimationFrame(rafIdRef.current);
      }
    };
  }, [lightCount]);

  // Render only once - never re-renders for VU updates
  return (
    <div ref={containerRef} className="vu">
      <div className="d-flex flex-column" style={{ height: `${lightCount * (lightHeight + 1)}px` }}>
        {Array.from({ length: lightCount }).map((_, i) => (
          <div
            key={i}
            ref={el => lightsRef.current[i] = el}
            className="vu-light vu-bg-secondary"
            style={{
              height: `${lightHeight}px`,
              width: '25px',
              marginTop: '1px',
              borderRadius: '2px',
              border: '1px solid #eee'
            }}
          />
        ))}
      </div>
    </div>
  );
});

export default SessionTrackVU;
```

## State of the Art

| Old Approach | Current Approach | When Changed | Impact |
|--------------|------------------|--------------|--------|
| useState for frequent updates | useSyncExternalStore + refs | React 18 (2022) | Eliminates reconciliation overhead |
| setInterval for animation | requestAnimationFrame | Browser standard | Syncs with display, battery efficient |
| Inline styles in render | classList manipulation | Performance best practice | Avoids style recalculation |
| Context for high-freq data | External stores | React 18 concurrent | Prevents cascade re-renders |

**Deprecated/outdated:**
- ReactUpdates.injection.injectBatchingStrategy: This was a React internal that older batching solutions used. Not applicable to modern React.
- componentWillReceiveProps for VU: Lifecycle methods are deprecated; use effects and refs instead.

## Open Questions

Things that couldn't be fully resolved:

1. **Optimal rAF batching threshold**
   - What we know: 60fps is standard display refresh, native client sends 50-70/sec (150ms refresh rate)
   - What's unclear: Whether we should batch to exactly 60fps or adapt based on actual update frequency
   - Recommendation: Start with rAF (60fps cap), measure performance, adjust if needed

2. **React DevTools Profiler verification approach**
   - What we know: Requirement says "0 re-renders from VU updates"
   - What's unclear: Exact profiler setup to verify this claim
   - Recommendation: Document profiler steps in verification task, capture before/after screenshots

3. **Interaction with existing MixersContext re-renders**
   - What we know: MixersContext was identified as creating new references every render (investigation finding)
   - What's unclear: Whether VU optimization alone is sufficient or MixersContext needs parallel fixes
   - Recommendation: VU optimization addresses VU-specific re-renders; MixersContext is separate scope

## Sources

### Primary (HIGH confidence)
- [React useSyncExternalStore official docs](https://react.dev/reference/react/useSyncExternalStore) - API, patterns, caveats
- [use-sync-external-store npm (React team)](https://github.com/facebook/react/blob/main/packages/use-sync-external-store/package.json) - Shim compatibility: React 16.8+
- [MDN requestAnimationFrame](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestAnimationFrame) - Browser API specification

### Secondary (MEDIUM confidence)
- [Epic React - useSyncExternalStore Demystified](https://www.epicreact.dev/use-sync-external-store-demystified-for-practical-react-development-w5ac0) - Implementation patterns
- [OpenReplay - requestAnimationFrame in React](https://blog.openreplay.com/use-requestanimationframe-in-react-for-smoothest-animations/) - Hook patterns and cleanup
- [SitePoint - Streaming Backends & React](https://www.sitepoint.com/streaming-backends-react-controlling-re-render-chaos/) - High-frequency data patterns

### Tertiary (LOW confidence)
- WebSearch results for "React VU meter" - Confirmed general patterns but no authoritative 2026 sources

## Metadata

**Confidence breakdown:**
- Standard stack: HIGH - Official React shim documented with version compatibility
- Architecture: HIGH - Patterns verified against React official docs
- Pitfalls: MEDIUM - Based on documented useSyncExternalStore caveats + general React performance patterns

**Research date:** 2026-03-03
**Valid until:** 2026-04-03 (30 days - stable patterns, no breaking changes expected)