Merge pull request #276 from naomiaro/fix/react-production-readiness

Improve React production readiness

Author: naomiaro

CLAUDE.MD

@@ -90,11 +90,12 @@ pnpm publish --filter @waveform-playlist/NEW-PACKAGE --no-git-checks --access pu
 
 **API Source of Truth:**
 - Context types (hooks, state, controls): `packages/browser/src/WaveformPlaylistContext.tsx`
+- Context hooks: `usePlaybackAnimation`, `usePlaylistState`, `usePlaylistControls`, `usePlaylistData` (no combined hook — `useWaveformPlaylist` was removed in v6.0.2)
 - MediaElement context types: `packages/browser/src/MediaElementPlaylistContext.tsx`
 - AudioTrackConfig interface: `packages/browser/src/hooks/useAudioTracks.ts`
 - Effects hooks return types: `packages/browser/src/hooks/useDynamicEffects.ts`, `useTrackDynamicEffects.ts`
 
-**Common Doc Drift:** Non-existent hooks, wrong property names (e.g., `gain` vs `volume`, `seek` vs `seekTo`), properties attributed to wrong context hooks. Always cross-check docs against source interfaces.
+**Common Doc Drift:** Non-existent hooks (e.g., `useWaveformPlaylist` was removed), wrong property names (e.g., `gain` vs `volume`, `seek` vs `seekTo`), properties attributed to wrong context hooks. Always cross-check docs against source interfaces.
 
 **Verify docs render:** `pnpm --filter website build` (CSS calc warnings are pre-existing, harmless)
 
@@ -546,6 +547,10 @@ const analyser = context.createAnalyser();
 11. **Playlist Loading Detection** - Use `data-playlist-state` attribute and `waveform-playlist:ready` custom event for reliable loading detection in CSS, E2E tests, and external integrations
 12. **Stable React Keys for Tracks/Clips** - Always use `track.id` / `clip.clipId` as React keys, never array indices. Index-based keys cause DOM reuse on removal, breaking `transferControlToOffscreen()` (can only be called once per canvas) and causing stale OffscreenCanvas references.
 13. **Per-Track Maps Must Use Track ID** - Any `Map` storing per-track overrides (render modes, configs) must be keyed by `track.id` (string), not array index. Index keys break when tracks are added/removed.
+14. **Context Value Memoization** - All context value objects in providers must be wrapped with `useMemo`. Extract inline callbacks into `useCallback` first to avoid dependency churn.
+15. **Error Boundary Available** - `PlaylistErrorBoundary` from `@waveform-playlist/ui-components` catches render errors. Uses plain CSS (no styled-components) so it works without ThemeProvider.
+16. **Audio Disconnect Diagnostics** - Use `console.warn('[waveform-playlist] ...')` in catch blocks for audio node disconnect errors, never silently swallow.
+17. **Fetch Cleanup with AbortController** - `useAudioTracks` uses AbortController to cancel in-flight fetches on cleanup. Follow this pattern for any fetch in useEffect.
 
 ### Playlist Loading Detection
 

PROJECT_STRUCTURE.md

@@ -878,7 +878,7 @@ The playlist now provides a **flexible/headless API** using React Context and pr
 - `WaveformPlaylistProvider` wraps your app and provides state via context
 - Primitive components (PlayButton, ZoomInButton, etc.) work anywhere inside the provider
 - `Waveform` component accepts a render prop for custom track controls
-- `useWaveformPlaylist` hook provides direct access to state/methods
+- Split context hooks (`usePlaylistData`, `usePlaylistControls`, etc.) provide direct access to state/methods
 
 ### Benefits
 
@@ -900,12 +900,14 @@ import {
   StopButton,
   Waveform,
   MasterVolumeControl,
-  useWaveformPlaylist,
+  usePlaylistData,
+  usePlaylistControls,
 } from '@waveform-playlist/browser';
 
 // Custom track controls
 const CustomTrackControls = ({ trackIndex }) => {
-  const { trackStates, setTrackMute } = useWaveformPlaylist();
+  const { trackStates } = usePlaylistData();
+  const { setTrackMute } = usePlaylistControls();
   return (
     <button onClick={() => setTrackMute(trackIndex, !trackStates[trackIndex].muted)}>
       {trackStates[trackIndex].muted ? 'Unmute' : 'Mute'}

packages/browser/src/WaveformPlaylistContext.tsx

@@ -41,77 +41,6 @@ export interface TrackState {
   pan: number;
 }
 
-export interface WaveformPlaylistContextValue {
-  // State
-  isPlaying: boolean;
-  currentTime: number;
-  duration: number;
-  audioBuffers: AudioBuffer[];
-  peaksDataArray: TrackClipPeaks[]; // Array of tracks, each containing array of clip peaks
-  trackStates: TrackState[];
-  annotations: AnnotationData[];
-  activeAnnotationId: string | null;
-  selectionStart: number;
-  selectionEnd: number;
-  isAutomaticScroll: boolean;
-  continuousPlay: boolean;
-  linkEndpoints: boolean;
-  annotationsEditable: boolean;
-
-  // Playback controls
-  play: (startTime?: number, playDuration?: number) => Promise<void>;
-  pause: () => void;
-  stop: () => void;
-  setCurrentTime: (time: number) => void;
-
-  // Track controls
-  setTrackMute: (trackIndex: number, muted: boolean) => void;
-  setTrackSolo: (trackIndex: number, soloed: boolean) => void;
-  setTrackVolume: (trackIndex: number, volume: number) => void;
-  setTrackPan: (trackIndex: number, pan: number) => void;
-
-  // Selection
-  setSelection: (start: number, end: number) => void;
-
-  // Time format
-  timeFormat: TimeFormat;
-  setTimeFormat: (format: TimeFormat) => void;
-  formatTime: (seconds: number) => string;
-
-  // Zoom
-  samplesPerPixel: number;
-  zoomIn: () => void;
-  zoomOut: () => void;
-  canZoomIn: boolean;
-  canZoomOut: boolean;
-
-  // Master volume
-  masterVolume: number;
-  setMasterVolume: (volume: number) => void;
-
-  // Automatic scroll
-  setAutomaticScroll: (enabled: boolean) => void;
-  setScrollContainer: (element: HTMLDivElement | null) => void;
-
-  // Annotation controls
-  setContinuousPlay: (enabled: boolean) => void;
-  setLinkEndpoints: (enabled: boolean) => void;
-  setAnnotationsEditable: (enabled: boolean) => void;
-  setAnnotations: React.Dispatch<React.SetStateAction<AnnotationData[]>>;
-  setActiveAnnotationId: (id: string | null) => void;
-
-  // Refs
-  playoutRef: React.RefObject<TonePlayout | null>;
-  currentTimeRef: React.RefObject<number>;
-
-  // Playlist info
-  sampleRate: number;
-  waveHeight: number;
-  timeScaleHeight: number;
-  minimumPlaylistHeight: number;
-  controls: { show: boolean; width: number };
-}
-
 // Split contexts for performance optimization
 // High-frequency updates (currentTime) are isolated from low-frequency state changes
 
@@ -222,9 +151,6 @@ const PlaylistStateContext = createContext<PlaylistStateContextValue | null>(nul
 const PlaylistControlsContext = createContext<PlaylistControlsContextValue | null>(null);
 const PlaylistDataContext = createContext<PlaylistDataContextValue | null>(null);
 
-// Keep the original context for backwards compatibility
-const WaveformPlaylistContext = createContext<WaveformPlaylistContextValue | null>(null);
-
 export interface WaveformPlaylistProviderProps {
   tracks: ClipTrack[]; // Updated to use clip-based model
   timescale?: boolean;
@@ -1071,15 +997,15 @@ export const WaveformPlaylistProvider: React.FC<WaveformPlaylistProviderProps> =
   // Split context values for performance optimization
   // High-frequency updates (currentTime) isolated from other state
 
-  const animationValue: PlaybackAnimationContextValue = {
+  const animationValue: PlaybackAnimationContextValue = useMemo(() => ({
     isPlaying,
     currentTime,
     currentTimeRef,
     playbackStartTimeRef,
     audioStartPositionRef,
-  };
+  }), [isPlaying, currentTime, currentTimeRef, playbackStartTimeRef, audioStartPositionRef]);
 
-  const stateValue: PlaylistStateContextValue = {
+  const stateValue: PlaylistStateContextValue = useMemo(() => ({
     continuousPlay,
     linkEndpoints,
     annotationsEditable,
@@ -1092,18 +1018,24 @@ export const WaveformPlaylistProvider: React.FC<WaveformPlaylistProviderProps> =
     selectedTrackId,
     loopStart,
     loopEnd,
-  };
+  }), [continuousPlay, linkEndpoints, annotationsEditable, isAutomaticScroll, isLoopEnabled, annotations, activeAnnotationId, selectionStart, selectionEnd, selectedTrackId, loopStart, loopEnd]);
 
-  const controlsValue: PlaylistControlsContextValue = {
+  const setCurrentTimeControl = useCallback((time: number) => {
+    currentTimeRef.current = time;
+    setCurrentTime(time);
+  }, [currentTimeRef]);
+
+  const setAutomaticScrollControl = useCallback((enabled: boolean) => {
+    setIsAutomaticScroll(enabled);
+  }, []);
+
+  const controlsValue: PlaylistControlsContextValue = useMemo(() => ({
     // Playback controls
     play,
     pause,
     stop,
     seekTo,
-    setCurrentTime: (time: number) => {
-      currentTimeRef.current = time;
-      setCurrentTime(time);
-    },
+    setCurrentTime: setCurrentTimeControl,
 
     // Track controls
     setTrackMute,
@@ -1127,9 +1059,7 @@ export const WaveformPlaylistProvider: React.FC<WaveformPlaylistProviderProps> =
     setMasterVolume,
 
     // Automatic scroll
-    setAutomaticScroll: (enabled: boolean) => {
-      setIsAutomaticScroll(enabled);
-    },
+    setAutomaticScroll: setAutomaticScrollControl,
     setScrollContainer,
     scrollContainerRef,
 
@@ -1146,9 +1076,9 @@ export const WaveformPlaylistProvider: React.FC<WaveformPlaylistProviderProps> =
     setLoopRegionFromSelection,
     clearLoopRegion,
 
-  };
+  }), [play, pause, stop, seekTo, setCurrentTimeControl, setTrackMute, setTrackSolo, setTrackVolume, setTrackPan, setSelection, setSelectedTrackId, setTimeFormat, formatTime, zoom.zoomIn, zoom.zoomOut, setMasterVolume, setAutomaticScrollControl, setScrollContainer, scrollContainerRef, setContinuousPlay, setLinkEndpoints, setAnnotationsEditable, setAnnotations, setActiveAnnotationId, setLoopEnabled, setLoopRegion, setLoopRegionFromSelection, clearLoopRegion]);
 
-  const dataValue: PlaylistDataContextValue = {
+  const dataValue: PlaylistDataContextValue = useMemo(() => ({
     duration,
     audioBuffers,
     peaksDataArray,
@@ -1170,15 +1100,7 @@ export const WaveformPlaylistProvider: React.FC<WaveformPlaylistProviderProps> =
     progressBarWidth,
     isReady,
     mono,
-  };
-
-  // Combined value for backwards compatibility
-  const value: WaveformPlaylistContextValue = {
-    ...animationValue,
-    ...stateValue,
-    ...controlsValue,
-    ...dataValue,
-  };
+  }), [duration, audioBuffers, peaksDataArray, trackStates, tracks, sampleRate, waveHeight, timeScaleHeight, minimumPlaylistHeight, controls, playoutRef, samplesPerPixel, timeFormat, masterVolume, zoom.canZoomIn, zoom.canZoomOut, barWidth, barGap, progressBarWidth, isReady, mono]);
 
   // Merge user theme with default theme
   const mergedTheme = { ...defaultTheme, ...userTheme };
@@ -1189,9 +1111,7 @@ export const WaveformPlaylistProvider: React.FC<WaveformPlaylistProviderProps> =
         <PlaylistStateContext.Provider value={stateValue}>
           <PlaylistControlsContext.Provider value={controlsValue}>
             <PlaylistDataContext.Provider value={dataValue}>
-              <WaveformPlaylistContext.Provider value={value}>
                 {children}
-              </WaveformPlaylistContext.Provider>
             </PlaylistDataContext.Provider>
           </PlaylistControlsContext.Provider>
         </PlaylistStateContext.Provider>
@@ -1235,12 +1155,3 @@ export const usePlaylistData = () => {
   return context;
 };
 
-// Main hook that combines all contexts - use this for backwards compatibility
-// or when you need access to multiple contexts
-export const useWaveformPlaylist = () => {
-  const context = useContext(WaveformPlaylistContext);
-  if (!context) {
-    throw new Error('useWaveformPlaylist must be used within WaveformPlaylistProvider');
-  }
-  return context;
-};

packages/browser/src/components/index.tsx

@@ -11,4 +11,4 @@ export * from './PlaylistVisualization';
 export * from './PlaylistAnnotationList';
 
 // Re-export WaveformPlaylistProvider and types from context
-export { WaveformPlaylistProvider, useWaveformPlaylist, type WaveformTrack } from '../WaveformPlaylistContext';
+export { WaveformPlaylistProvider, type WaveformTrack } from '../WaveformPlaylistContext';

packages/browser/src/hooks/useAudioTracks.ts

@@ -118,6 +118,7 @@ export function useAudioTracks(
     }
 
     let cancelled = false;
+    const abortController = new AbortController();
     // Track loaded tracks by their config index for progressive mode
     const loadedTracksMap = new Map<number, ClipTrack>();
 
@@ -225,7 +226,7 @@ export function useAudioTracks(
             throw new Error(`Track ${index + 1}: Must provide src, audioBuffer, or waveformData`);
           }
 
-          const response = await fetch(config.src);
+          const response = await fetch(config.src, { signal: abortController.signal });
           if (!response.ok) {
             throw new Error(`Failed to fetch ${config.src}: ${response.statusText}`);
           }
@@ -275,9 +276,10 @@ export function useAudioTracks(
 
     loadTracks();
 
-    // Cleanup function to prevent state updates if component unmounts
+    // Cleanup: prevent state updates and abort in-flight fetches on unmount
     return () => {
       cancelled = true;
+      abortController.abort();
     };
   }, [configs, progressive]);
 

packages/browser/src/hooks/useDynamicEffects.ts

@@ -81,7 +81,7 @@ export function useDynamicEffects(fftSize: number = 256): UseDynamicEffectsRetur
     try {
       masterGainNode.disconnect();
     } catch (e) {
-      // Ignore disconnect errors
+      console.warn('[waveform-playlist] Error disconnecting master effects chain:', e);
     }
 
     // Get effect instances in order
@@ -101,7 +101,7 @@ export function useDynamicEffects(fftSize: number = 256): UseDynamicEffectsRetur
         try {
           inst.disconnect();
         } catch (e) {
-          // Ignore
+          console.warn(`[waveform-playlist] Error disconnecting effect "${inst.id}":`, e);
         }
         currentNode.connect(inst.effect);
         currentNode = inst.effect;

packages/browser/src/hooks/useTrackDynamicEffects.ts

@@ -87,7 +87,7 @@ export function useTrackDynamicEffects(): UseTrackDynamicEffectsReturn {
     try {
       graphEnd.disconnect();
     } catch (e) {
-      // Ignore disconnect errors
+      console.warn(`[waveform-playlist] Error disconnecting track "${trackId}" effect chain:`, e);
     }
 
     // Get effect instances in order
@@ -106,7 +106,7 @@ export function useTrackDynamicEffects(): UseTrackDynamicEffectsReturn {
         try {
           inst.disconnect();
         } catch (e) {
-          // Ignore
+          console.warn(`[waveform-playlist] Error disconnecting effect "${inst.id}" on track "${trackId}":`, e);
         }
         currentNode.connect(inst.effect);
         currentNode = inst.effect;

packages/browser/src/index.tsx

@@ -8,13 +8,12 @@ export type { EffectsFunction, TrackEffectsFunction } from '@waveform-playlist/p
 // Export new flexible/headless API
 export {
   WaveformPlaylistProvider,
-  useWaveformPlaylist,
   usePlaybackAnimation,
   usePlaylistState,
   usePlaylistControls,
   usePlaylistData,
 } from './WaveformPlaylistContext';
-export type { WaveformPlaylistContextValue, WaveformTrack, TrackState } from './WaveformPlaylistContext';
+export type { WaveformTrack, TrackState } from './WaveformPlaylistContext';
 
 // Export MediaElement-based provider (single-track with playback rate control)
 export {