Merge pull request #277 from naomiaro/chore-react-ts-audit-refactors

React/TypeScript audit: lint baseline, provider refactor, spectrogram fix

Author: naomiaro

AGENTS.md

@@ -0,0 +1,6 @@
+# Agent Instructions
+
+Primary project guidance is maintained in `CLAUDE.MD`.
+
+- Read `CLAUDE.MD` before making changes.
+- Treat `CLAUDE.MD` as the source of truth for architecture and conventions.

CLAUDE.MD

@@ -401,6 +401,50 @@ const LazyExample = createLazyExample(
 
 **Documentation:** `website/docs/effects.md`
 
+### Shared Animation Frame Loop Hook (Provider Refactor, 2026-02-13)
+
+**Decision:** Centralize requestAnimationFrame lifecycle logic in a shared hook used by both playlist providers.
+
+**Implementation:**
+- New hook: `packages/browser/src/hooks/useAnimationFrameLoop.ts`
+- Exported from: `packages/browser/src/hooks/index.ts`
+- Integrated into:
+  - `packages/browser/src/WaveformPlaylistContext.tsx`
+  - `packages/browser/src/MediaElementPlaylistContext.tsx`
+
+**Why:**
+- Removes duplicated `requestAnimationFrame` / `cancelAnimationFrame` logic across providers
+- Ensures a single in-flight animation frame per provider
+- Standardizes cleanup on unmount and playback transitions
+
+### SpectrogramChannel Hook Stability (2026-02-13)
+
+**Decision:** Use stable default references for LUT/scale and remove hook dependency suppression.
+
+**Implementation:** `packages/ui-components/src/components/SpectrogramChannel.tsx`
+- Hoisted stable defaults:
+  - `DEFAULT_COLOR_LUT`
+  - `LINEAR_FREQUENCY_SCALE`
+- Updated effect dependencies to include worker/callback references explicitly
+- Removed `react-hooks/exhaustive-deps` suppression
+
+**Why:**
+- Prevents unnecessary redraw/recompute caused by new inline default references each render
+- Reduces stale-closure risk in worker canvas registration effect
+
+### ESLint Baseline (2026-02-13)
+
+**Decision:** Add a root flat ESLint config with TypeScript + React Hooks checks.
+
+**Implementation:**
+- Config file: `eslint.config.mjs`
+- Root `package.json` devDependencies include:
+  - `eslint`, `@eslint/js`
+  - `@typescript-eslint/parser`, `@typescript-eslint/eslint-plugin`
+  - `eslint-plugin-react-hooks`, `globals`
+
+**Status:** TypeScript checks pass (`pnpm typecheck`). Lint execution is currently blocked in offline environments until dependencies are installable (`pnpm install` needed when network is available).
+
 ---
 
 ## Recording Architecture

eslint.config.mjs

@@ -0,0 +1,68 @@
+import js from '@eslint/js';
+import tsParser from '@typescript-eslint/parser';
+import tsPlugin from '@typescript-eslint/eslint-plugin';
+import reactHooksPlugin from 'eslint-plugin-react-hooks';
+import globals from 'globals';
+
+export default [
+  {
+    ignores: [
+      '**/node_modules/**',
+      '**/dist/**',
+      '**/build/**',
+      '**/.docusaurus/**',
+      '**/playwright-report/**',
+      '**/test-results/**',
+      '**/*.d.ts',
+    ],
+  },
+  {
+    files: ['packages/**/src/**/*.{ts,tsx}', 'e2e/**/*.ts', 'website/src/**/*.{ts,tsx}'],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+        ecmaFeatures: {
+          jsx: true,
+        },
+      },
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tsPlugin,
+      'react-hooks': reactHooksPlugin,
+    },
+    rules: {
+      ...js.configs.recommended.rules,
+      ...tsPlugin.configs.recommended.rules,
+      'no-undef': 'off',
+      'no-unused-vars': 'off',
+      'react-hooks/rules-of-hooks': 'error',
+      'react-hooks/exhaustive-deps': 'error',
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+      '@typescript-eslint/no-explicit-any': 'warn',
+    },
+  },
+  {
+    files: ['**/*.{js,mjs,cjs}'],
+    languageOptions: {
+      globals: {
+        ...globals.node,
+      },
+    },
+    rules: {
+      ...js.configs.recommended.rules,
+    },
+  },
+  {
+    files: ['**/*.stories.{ts,tsx}'],
+    rules: {
+      'react-hooks/rules-of-hooks': 'off',
+      'react-hooks/exhaustive-deps': 'off',
+    },
+  },
+];

package.json

@@ -21,8 +21,14 @@
     "version:bump": "node scripts/bump-version.js"
   },
   "devDependencies": {
+    "@eslint/js": "^9.20.0",
     "@playwright/test": "^1.57.0",
+    "@typescript-eslint/eslint-plugin": "^8.24.1",
+    "@typescript-eslint/parser": "^8.24.1",
     "@types/node": "^20.10.6",
+    "eslint": "^9.20.1",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "globals": "^15.15.0",
     "prettier": "^3.1.1",
     "rollup-plugin-visualizer": "^6.0.5",
     "typescript": "^5.3.3"

packages/annotations/src/hooks/useAnnotationControls.ts

@@ -1,5 +1,5 @@
 import { useState, useCallback } from 'react';
-import type { AnnotationData, AnnotationListOptions } from '../types';
+import type { AnnotationData } from '../types';
 
 const LINK_THRESHOLD = 0.01; // Consider edges "linked" if within 10ms
 

packages/browser/src/MediaElementPlaylistContext.tsx

@@ -11,7 +11,6 @@ import React, {
 import { ThemeProvider } from 'styled-components';
 import {
   MediaElementPlayout,
-  type MediaElementTrackOptions,
 } from '@waveform-playlist/media-element-playout';
 import { type WaveformDataObject } from '@waveform-playlist/core';
 import {
@@ -23,6 +22,7 @@ import { extractPeaksFromWaveformData } from './waveformDataLoader';
 import type WaveformData from 'waveform-data';
 import type { PeakData } from '@waveform-playlist/webaudio-peaks';
 import type { ClipPeaks, TrackClipPeaks } from './WaveformPlaylistContext';
+import { useAnimationFrameLoop } from './hooks/useAnimationFrameLoop';
 
 // Configuration for a single media element track
 export interface MediaElementTrackConfig {
@@ -202,12 +202,12 @@ export const MediaElementPlaylistProvider: React.FC<
   // Refs
   const playoutRef = useRef<MediaElementPlayout | null>(null);
   const currentTimeRef = useRef<number>(0);
-  const animationFrameRef = useRef<number | null>(null);
   const continuousPlayRef = useRef<boolean>(continuousPlay);
   const activeAnnotationIdRef = useRef<string | null>(null);
   const scrollContainerRef = useRef<HTMLDivElement | null>(null);
   const isAutomaticScrollRef = useRef<boolean>(automaticScroll);
   const samplesPerPixelRef = useRef<number>(initialSamplesPerPixel);
+  const { startAnimationFrameLoop, stopAnimationFrameLoop } = useAnimationFrameLoop();
 
   // Sync refs
   useEffect(() => {
@@ -259,10 +259,7 @@ export const MediaElementPlaylistProvider: React.FC<
 
     // Set up playback complete callback
     playout.setOnPlaybackComplete(() => {
-      if (animationFrameRef.current) {
-        cancelAnimationFrame(animationFrameRef.current);
-        animationFrameRef.current = null;
-      }
+      stopAnimationFrameLoop();
       setIsPlaying(false);
       setActiveAnnotationId(null);
       currentTimeRef.current = 0;
@@ -274,12 +271,10 @@ export const MediaElementPlaylistProvider: React.FC<
     onReady?.();
 
     return () => {
-      if (animationFrameRef.current) {
-        cancelAnimationFrame(animationFrameRef.current);
-      }
+      stopAnimationFrameLoop();
       playout.dispose();
     };
-  }, [track.source, track.waveformData, track.name, initialPlaybackRate, onReady]);
+  }, [track.source, track.waveformData, track.name, initialPlaybackRate, onReady, stopAnimationFrameLoop, setActiveAnnotationId]);
 
   // Generate peaks from waveform data
   useEffect(() => {
@@ -308,10 +303,6 @@ export const MediaElementPlaylistProvider: React.FC<
 
   // Animation loop
   const startAnimationLoop = useCallback(() => {
-    if (animationFrameRef.current) {
-      cancelAnimationFrame(animationFrameRef.current);
-    }
-
     const updateTime = () => {
       const time = playoutRef.current?.getCurrentTime() ?? 0;
       currentTimeRef.current = time;
@@ -368,18 +359,13 @@ export const MediaElementPlaylistProvider: React.FC<
         container.scrollLeft = targetScrollLeft;
       }
 
-      animationFrameRef.current = requestAnimationFrame(updateTime);
+      startAnimationFrameLoop(updateTime);
     };
 
-    animationFrameRef.current = requestAnimationFrame(updateTime);
-  }, [setActiveAnnotationId, sampleRate, controls]);
+    startAnimationFrameLoop(updateTime);
+  }, [setActiveAnnotationId, sampleRate, controls, startAnimationFrameLoop]);
 
-  const stopAnimationLoop = useCallback(() => {
-    if (animationFrameRef.current) {
-      cancelAnimationFrame(animationFrameRef.current);
-      animationFrameRef.current = null;
-    }
-  }, []);
+  const stopAnimationLoop = stopAnimationFrameLoop;
 
   // Playback controls
   const play = useCallback(

packages/browser/src/WaveformPlaylistContext.tsx

@@ -10,7 +10,7 @@ import { extractPeaksFromWaveformData } from './waveformDataLoader';
 import type WaveformData from 'waveform-data';
 import type { PeakData } from '@waveform-playlist/webaudio-peaks';
 import type { AnnotationData } from '@waveform-playlist/core';
-import { useTimeFormat, useZoomControls, useMasterVolume } from './hooks';
+import { useTimeFormat, useZoomControls, useMasterVolume, useAnimationFrameLoop } from './hooks';
 
 // Types
 export interface ClipPeaks {
@@ -254,7 +254,6 @@ export const WaveformPlaylistProvider: React.FC<WaveformPlaylistProviderProps> =
   const playoutRef = useRef<TonePlayout | null>(null);
   const playStartPositionRef = useRef<number>(0);
   const currentTimeRef = useRef<number>(0);
-  const animationFrameRef = useRef<number | null>(null);
   const trackStatesRef = useRef<TrackState[]>(trackStates);
   const playbackStartTimeRef = useRef<number>(0); // context.currentTime when playback started
   const audioStartPositionRef = useRef<number>(0); // Audio position when playback started
@@ -275,6 +274,7 @@ export const WaveformPlaylistProvider: React.FC<WaveformPlaylistProviderProps> =
   const zoom = useZoomControls({ initialSamplesPerPixel, zoomLevels });
   const samplesPerPixel = zoom.samplesPerPixel;
   const { masterVolume, setMasterVolume } = useMasterVolume({ playoutRef, initialVolume: 1.0 });
+  const { animationFrameRef, startAnimationFrameLoop, stopAnimationFrameLoop } = useAnimationFrameLoop();
 
   // Custom setter for continuousPlay that updates BOTH state and ref synchronously
   // This ensures the ref is updated immediately, before the animation loop can read it
@@ -384,10 +384,7 @@ export const WaveformPlaylistProvider: React.FC<WaveformPlaylistProviderProps> =
     // Stop current playback and animation before disposing
     if (playoutRef.current && wasPlaying) {
       playoutRef.current.stop();
-      if (animationFrameRef.current) {
-        cancelAnimationFrame(animationFrameRef.current);
-        animationFrameRef.current = null;
-      }
+      stopAnimationFrameLoop();
       // Mark that we need to resume playback after playout is rebuilt
       pendingResumeRef.current = { position: resumePosition };
     }
@@ -524,14 +521,12 @@ export const WaveformPlaylistProvider: React.FC<WaveformPlaylistProviderProps> =
     loadAudio();
 
     return () => {
-      if (animationFrameRef.current) {
-        cancelAnimationFrame(animationFrameRef.current);
-      }
+      stopAnimationFrameLoop();
       if (playoutRef.current) {
         playoutRef.current.dispose();
       }
     };
-  }, [tracks, onReady, isPlaying]);
+  }, [tracks, onReady, isPlaying, effects, stopAnimationFrameLoop]);
 
   // Regenerate peaks when zoom or mono changes (without reloading audio)
   useEffect(() => {
@@ -617,12 +612,6 @@ export const WaveformPlaylistProvider: React.FC<WaveformPlaylistProviderProps> =
 
   // Animation loop
   const startAnimationLoop = useCallback(() => {
-    // Cancel any existing animation frame before starting a new one
-    if (animationFrameRef.current) {
-      cancelAnimationFrame(animationFrameRef.current);
-      animationFrameRef.current = null;
-    }
-
     const updateTime = () => {
       // Calculate current position based on context.currentTime timing
       const elapsed = getContext().currentTime - playbackStartTimeRef.current;
@@ -720,7 +709,7 @@ export const WaveformPlaylistProvider: React.FC<WaveformPlaylistProviderProps> =
           playoutRef.current?.play(timeNow, loopStartRef.current);
 
           // Continue animation loop
-          animationFrameRef.current = requestAnimationFrame(updateTime);
+          startAnimationFrameLoop(updateTime);
           return;
         }
       }
@@ -736,17 +725,12 @@ export const WaveformPlaylistProvider: React.FC<WaveformPlaylistProviderProps> =
         setActiveAnnotationId(null);
         return;
       }
-      animationFrameRef.current = requestAnimationFrame(updateTime);
+      startAnimationFrameLoop(updateTime);
     };
-    animationFrameRef.current = requestAnimationFrame(updateTime);
-  }, [duration, audioBuffers, samplesPerPixel, continuousPlay]);
+    startAnimationFrameLoop(updateTime);
+  }, [duration, audioBuffers, controls.show, controls.width, setActiveAnnotationId, startAnimationFrameLoop]);
 
-  const stopAnimationLoop = useCallback(() => {
-    if (animationFrameRef.current) {
-      cancelAnimationFrame(animationFrameRef.current);
-      animationFrameRef.current = null;
-    }
-  }, []);
+  const stopAnimationLoop = stopAnimationFrameLoop;
 
   // Restart animation loop and reschedule playout when continuousPlay changes during playback
   // This ensures the loop always has the current continuousPlay value
@@ -786,7 +770,7 @@ export const WaveformPlaylistProvider: React.FC<WaveformPlaylistProviderProps> =
     };
 
     reschedulePlayback();
-  }, [continuousPlay, isPlaying, startAnimationLoop, stopAnimationLoop]);
+  }, [continuousPlay, isPlaying, startAnimationLoop, stopAnimationLoop, animationFrameRef]);
 
   // Resume playback after tracks change (e.g., after splitting a clip during playback)
   useEffect(() => {
@@ -878,7 +862,7 @@ export const WaveformPlaylistProvider: React.FC<WaveformPlaylistProviderProps> =
     currentTimeRef.current = playStartPositionRef.current;
     setCurrentTime(playStartPositionRef.current);
     setActiveAnnotationId(null);
-  }, [stopAnimationLoop]);
+  }, [stopAnimationLoop, setActiveAnnotationId]);
 
   // Seek to a specific time - works whether playing or stopped
   const seekTo = useCallback((time: number) => {
@@ -1154,4 +1138,3 @@ export const usePlaylistData = () => {
   }
   return context;
 };
-

packages/browser/src/components/MediaElementPlaylist.tsx

@@ -63,7 +63,7 @@ export const MediaElementPlaylist: React.FC<MediaElementPlaylistProps> = ({
   const theme = useTheme() as import('@waveform-playlist/ui-components').WaveformPlaylistTheme;
 
   // MediaElement context hooks
-  const { isPlaying, currentTimeRef } = useMediaElementAnimation();
+  const { isPlaying } = useMediaElementAnimation();
   const { annotations, activeAnnotationId } = useMediaElementState();
   const annotationIntegration = useContext(AnnotationIntegrationContext);
   const { play, seekTo, setActiveAnnotationId, setAnnotations, setScrollContainer } = useMediaElementControls();

packages/browser/src/components/PlaylistVisualization.tsx

@@ -87,7 +87,7 @@ export const PlaylistVisualization: React.FC<PlaylistVisualizationProps> = ({
   renderTrackControls,
   renderTimestamp,
   renderPlayhead,
-  annotationControls,
+  annotationControls: _annotationControls,
   getAnnotationBoxLabel,
   className,
   showClipHeaders = false,
@@ -106,7 +106,7 @@ export const PlaylistVisualization: React.FC<PlaylistVisualizationProps> = ({
     annotations,
     activeAnnotationId,
     annotationsEditable,
-    linkEndpoints,
+    linkEndpoints: _linkEndpoints,
     continuousPlay,
     selectedTrackId,
     loopStart,
@@ -115,7 +115,7 @@ export const PlaylistVisualization: React.FC<PlaylistVisualizationProps> = ({
   } = usePlaylistState();
   const annotationIntegration = useContext(AnnotationIntegrationContext);
   const {
-    setAnnotations,
+    setAnnotations: _setAnnotations,
     setActiveAnnotationId,
     setTrackMute,
     setTrackSolo,