refactor: extract useChunkedCanvasRefs hook to standardize canvas ref pattern

The second Rule of Three violation: Channel, TimeScale, and SpectrogramChannel
all had identical callback-ref + stale-cleanup logic for managing chunked canvas
elements. Standardize on Map<number, HTMLCanvasElement> (TimeScale already used
Map; Channel and SpectrogramChannel used sparse arrays). Net -57 lines.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: naomiaro

CLAUDE.MD

@@ -467,6 +467,10 @@ const LazyExample = createLazyExample(
 - `SpectrogramChannel` — only mounts visible chunks (biggest memory win)
 - All use absolute positioning (`left: chunkIndex * 1000px`) instead of `float: left`
 
+**Shared hooks:**
+- `useVisibleChunkIndices(totalWidth, chunkWidth)` — returns memoized array of visible chunk indices. Uses string-key comparison internally for re-render gating. Exported from `ui-components`.
+- `useChunkedCanvasRefs()` — callback ref + Map storage + stale cleanup for chunked canvases. Internal only (not exported from package public API). Uses `Map<number, HTMLCanvasElement>` instead of sparse arrays.
+
 **Backwards compatibility:** `useScrollViewport()` returns `null` without provider. All components default to rendering everything when viewport is `null`.
 
 ### Web Worker Peak Generation (2026-02-13)
@@ -634,6 +638,8 @@ const analyser = context.createAnalyser();
 17. **Fetch Cleanup with AbortController** - `useAudioTracks` uses AbortController to cancel in-flight fetches on cleanup. Follow this pattern for any fetch in useEffect. For per-item abort (e.g., removing one loading track), use `Map<id, AbortController>` instead of `Set<AbortController>`.
 18. **Derive Render Guards from Props, Not Effect State** - Don't use effect-set state (e.g., `audioBuffers`) in render guards. Effect state lags props by one+ renders, causing content to flash/disappear. Compute values synchronously from props instead.
 19. **Copy Refs in useEffect Body** - When accessing a ref in `useEffect` cleanup, copy `.current` to a local variable inside the effect body. ESLint's `react-hooks/exhaustive-deps` rule flags refs that may change between render and cleanup.
+20. **Refs from Custom Hooks in Dep Arrays** - When a `useRef` is returned from a custom hook, ESLint's `exhaustive-deps` can't trace its stability. Include it in the dep array (harmless, never triggers) rather than using `eslint-disable-next-line` which would mask real missing dependencies.
+21. **Every-Render Cleanup Effects** - `useChunkedCanvasRefs` and SpectrogramChannel's worker cleanup use `useEffect` with no dependency array intentionally. The virtualizer can unmount canvases between any render. Do NOT add `[]` or other deps — this would break stale ref pruning.
 
 ### Playlist Loading Detection
 

packages/ui-components/src/components/Channel.tsx

@@ -1,8 +1,9 @@
-import React, { FunctionComponent, useLayoutEffect, useEffect, useCallback, useRef } from 'react';
+import React, { FunctionComponent, useLayoutEffect } from 'react';
 import styled from 'styled-components';
 import type { Peaks, Bits } from '@waveform-playlist/core';
 import { WaveformColor, WaveformDrawMode, isWaveformGradient, waveformColorToCss } from '../wfpl-theme';
 import { useVisibleChunkIndices } from '../contexts/ScrollViewport';
+import { useChunkedCanvasRefs } from '../hooks/useChunkedCanvasRefs';
 import { MAX_CANVAS_WIDTH } from '../constants';
 
 // Re-export WaveformColor for consumers
@@ -121,41 +122,16 @@ export const Channel: FunctionComponent<ChannelProps> = (props) => {
     transparentBackground = false,
     drawMode = 'inverted',
   } = props;
-  const canvasesRef = useRef<HTMLCanvasElement[]>([]);
+  const { canvasRef, canvasMapRef } = useChunkedCanvasRefs();
 
   const visibleChunkIndices = useVisibleChunkIndices(length, MAX_CANVAS_WIDTH);
 
-  const canvasRef = useCallback(
-    (canvas: HTMLCanvasElement | null) => {
-      if (canvas !== null) {
-        const index: number = parseInt(canvas.dataset.index!, 10);
-        canvasesRef.current[index] = canvas;
-      }
-    },
-    []
-  );
-
-  // Clean up stale refs for unmounted chunks
-  useEffect(() => {
-    const canvases = canvasesRef.current;
-    for (let i = canvases.length - 1; i >= 0; i--) {
-      if (canvases[i] && !canvases[i].isConnected) {
-        delete canvases[i];
-      }
-    }
-  });
-
   // Draw waveform bars on visible canvas chunks.
-  // visibleChunkKey changes only when chunks mount/unmount, not on every scroll pixel.
+  // visibleChunkIndices changes only when chunks mount/unmount, not on every scroll pixel.
   useLayoutEffect(() => {
-    const canvases = canvasesRef.current;
     const step = barWidth + barGap;
 
-    for (let i = 0; i < canvases.length; i++) {
-      const canvas = canvases[i];
-      if (!canvas) continue; // Skip unmounted chunks (sparse array from virtualization)
-
-      const canvasIdx = parseInt(canvas.dataset.index!, 10);
+    for (const [canvasIdx, canvas] of canvasMapRef.current.entries()) {
       const globalPixelOffset = canvasIdx * MAX_CANVAS_WIDTH;
 
       const ctx = canvas.getContext('2d');
@@ -232,6 +208,7 @@ export const Channel: FunctionComponent<ChannelProps> = (props) => {
       }
     }
   }, [
+    canvasMapRef,
     data,
     bits,
     waveHeight,

packages/ui-components/src/components/SpectrogramChannel.tsx

@@ -1,7 +1,8 @@
-import React, { FunctionComponent, useLayoutEffect, useCallback, useRef, useEffect } from 'react';
+import React, { FunctionComponent, useLayoutEffect, useRef, useEffect } from 'react';
 import styled from 'styled-components';
 import type { SpectrogramData } from '@waveform-playlist/core';
 import { useVisibleChunkIndices } from '../contexts/ScrollViewport';
+import { useChunkedCanvasRefs } from '../hooks/useChunkedCanvasRefs';
 import { MAX_CANVAS_WIDTH } from '../constants';
 const LINEAR_FREQUENCY_SCALE = (f: number, minF: number, maxF: number) => (f - minF) / (maxF - minF);
 
@@ -110,7 +111,7 @@ export const SpectrogramChannel: FunctionComponent<SpectrogramChannelProps> = ({
   onCanvasesReady,
 }) => {
   const channelIndex = channelIndexProp ?? index;
-  const canvasesRef = useRef<HTMLCanvasElement[]>([]);
+  const { canvasRef, canvasMapRef } = useChunkedCanvasRefs();
   const registeredIdsRef = useRef<string[]>([]);
   const transferredCanvasesRef = useRef<WeakSet<HTMLCanvasElement>>(new WeakSet());
   const workerApiRef = useRef(workerApi);
@@ -121,16 +122,6 @@ export const SpectrogramChannel: FunctionComponent<SpectrogramChannelProps> = ({
 
   const visibleChunkIndices = useVisibleChunkIndices(length, MAX_CANVAS_WIDTH);
 
-  const canvasRef = useCallback(
-    (canvas: HTMLCanvasElement | null) => {
-      if (canvas !== null) {
-        const idx = parseInt(canvas.dataset.index!, 10);
-        canvasesRef.current[idx] = canvas;
-      }
-    },
-    []
-  );
-
   const lut = colorLUT ?? DEFAULT_COLOR_LUT;
   const maxF = maxFrequency ?? (data ? data.sampleRate / 2 : 22050);
   const scaleFn = frequencyScaleFn ?? LINEAR_FREQUENCY_SCALE;
@@ -154,18 +145,13 @@ export const SpectrogramChannel: FunctionComponent<SpectrogramChannelProps> = ({
     const currentWorkerApi = workerApiRef.current;
     if (!currentWorkerApi || !clipId) return;
 
-    const canvases = canvasesRef.current;
     const newIds: string[] = [];
     const newWidths: number[] = [];
 
-    for (let i = 0; i < canvases.length; i++) {
-      const canvas = canvases[i];
-      if (!canvas) continue;
-
+    for (const [canvasIdx, canvas] of canvasMapRef.current.entries()) {
       // Skip canvases that have already been transferred to the worker
       if (transferredCanvasesRef.current.has(canvas)) continue;
 
-      const canvasIdx = parseInt(canvas.dataset.index!, 10);
       const canvasId = `${clipId}-ch${channelIndex}-chunk${canvasIdx}`;
 
       let offscreen: OffscreenCanvas;
@@ -194,7 +180,7 @@ export const SpectrogramChannel: FunctionComponent<SpectrogramChannelProps> = ({
       registeredIdsRef.current = [...registeredIdsRef.current, ...newIds];
       onCanvasesReadyRef.current?.(newIds, newWidths);
     }
-  }, [isWorkerMode, clipId, channelIndex, length, visibleChunkIndices]);
+  }, [canvasMapRef, isWorkerMode, clipId, channelIndex, length, visibleChunkIndices]);
 
   // Clean up stale worker registrations for canvases that unmounted
   useEffect(() => {
@@ -209,7 +195,7 @@ export const SpectrogramChannel: FunctionComponent<SpectrogramChannelProps> = ({
       const match = id.match(/chunk(\d+)$/);
       if (!match) { remaining.push(id); continue; }
       const chunkIdx = parseInt(match[1], 10);
-      const canvas = canvasesRef.current[chunkIdx];
+      const canvas = canvasMapRef.current.get(chunkIdx);
       if (canvas && canvas.isConnected) {
         remaining.push(id);
       } else {
@@ -244,19 +230,14 @@ export const SpectrogramChannel: FunctionComponent<SpectrogramChannelProps> = ({
   useLayoutEffect(() => {
     if (isWorkerMode || !data) return;
 
-    const canvases = canvasesRef.current;
     const { frequencyBinCount, frameCount, hopSize, sampleRate, gainDb, rangeDb: rawRangeDb } = data;
     const rangeDb = rawRangeDb === 0 ? 1 : rawRangeDb;
 
     // Pre-compute Y mapping: for each pixel row, which frequency bin(s) to sample
     const binToFreq = (bin: number) => (bin / frequencyBinCount) * (sampleRate / 2);
 
-    for (let i = 0; i < canvases.length; i++) {
-      const canvas = canvases[i];
-      if (!canvas) continue;  // Skip unmounted chunks
-
-      const canvasIdx = parseInt(canvas.dataset.index!, 10);
-      const globalPixelOffset = canvasIdx * MAX_CANVAS_WIDTH;  // Compute from index
+    for (const [canvasIdx, canvas] of canvasMapRef.current.entries()) {
+      const globalPixelOffset = canvasIdx * MAX_CANVAS_WIDTH;
 
       const ctx = canvas.getContext('2d');
       if (!ctx) continue;
@@ -348,7 +329,7 @@ export const SpectrogramChannel: FunctionComponent<SpectrogramChannelProps> = ({
 
     }
 
-  }, [isWorkerMode, data, length, waveHeight, devicePixelRatio, samplesPerPixel, lut, minFrequency, maxF, scaleFn, hasCustomFrequencyScale, visibleChunkIndices]);
+  }, [canvasMapRef, isWorkerMode, data, length, waveHeight, devicePixelRatio, samplesPerPixel, lut, minFrequency, maxF, scaleFn, hasCustomFrequencyScale, visibleChunkIndices]);
 
   // Build visible canvas chunk elements
   const canvases = visibleChunkIndices.map((i) => {

packages/ui-components/src/components/TimeScale.tsx

@@ -1,8 +1,9 @@
-import React, { FunctionComponent, useRef, useEffect, useLayoutEffect, useContext, useMemo, useCallback } from 'react';
+import React, { FunctionComponent, useLayoutEffect, useContext, useMemo } from 'react';
 import styled, { withTheme, DefaultTheme } from 'styled-components';
 import { PlaylistInfoContext } from '../contexts/PlaylistInfo';
 import { useDevicePixelRatio } from '../contexts/DevicePixelRatio';
 import { useVisibleChunkIndices } from '../contexts/ScrollViewport';
+import { useChunkedCanvasRefs } from '../hooks/useChunkedCanvasRefs';
 import { secondsToPixels } from '../utils/conversions';
 import { MAX_CANVAS_WIDTH } from '../constants';
 
@@ -86,7 +87,7 @@ export const TimeScale: FunctionComponent<TimeScalePropsWithTheme> = (props) =>
     secondStep,
     renderTimestamp,
   } = props;
-  const canvasRefsMap = useRef<Map<number, HTMLCanvasElement>>(new Map());
+  const { canvasRef, canvasMapRef } = useChunkedCanvasRefs();
   const {
     sampleRate,
     samplesPerPixel,
@@ -95,13 +96,6 @@ export const TimeScale: FunctionComponent<TimeScalePropsWithTheme> = (props) =>
   } = useContext(PlaylistInfoContext);
   const devicePixelRatio = useDevicePixelRatio();
 
-  const canvasRefCallback = useCallback((canvas: HTMLCanvasElement | null) => {
-    if (canvas !== null) {
-      const idx = parseInt(canvas.dataset.index!, 10);
-      canvasRefsMap.current.set(idx, canvas);
-    }
-  }, []);
-
   const { widthX, canvasInfo, timeMarkersWithPositions } = useMemo(() => {
     const nextCanvasInfo = new Map<number, number>();
     const nextMarkers: Array<{ pix: number; element: React.ReactNode }> = [];
@@ -160,7 +154,7 @@ export const TimeScale: FunctionComponent<TimeScalePropsWithTheme> = (props) =>
         width={chunkWidth * devicePixelRatio}
         height={timeScaleHeight * devicePixelRatio}
         data-index={i}
-        ref={canvasRefCallback}
+        ref={canvasRef}
       />
     );
   });
@@ -180,20 +174,10 @@ export const TimeScale: FunctionComponent<TimeScalePropsWithTheme> = (props) =>
         .map(({ element }) => element)
     : timeMarkersWithPositions.map(({ element }) => element);
 
-  // Clean up stale refs for unmounted chunks
-  useEffect(() => {
-    const currentMap = canvasRefsMap.current;
-    for (const [idx, canvas] of currentMap.entries()) {
-      if (!canvas.isConnected) {
-        currentMap.delete(idx);
-      }
-    }
-  });
-
   // Draw tick marks on visible canvas chunks.
-  // visibleChunkKey changes only when chunks mount/unmount, not on every scroll pixel.
+  // visibleChunkIndices changes only when chunks mount/unmount, not on every scroll pixel.
   useLayoutEffect(() => {
-    for (const [chunkIdx, canvas] of canvasRefsMap.current.entries()) {
+    for (const [chunkIdx, canvas] of canvasMapRef.current.entries()) {
       const ctx = canvas.getContext('2d');
       if (!ctx) continue;
 
@@ -215,7 +199,7 @@ export const TimeScale: FunctionComponent<TimeScalePropsWithTheme> = (props) =>
         ctx.fillRect(localX, scaleY, 1, scaleHeight);
       }
     }
-  }, [duration, devicePixelRatio, timeColor, timeScaleHeight, canvasInfo, visibleChunkIndices]);
+  }, [canvasMapRef, duration, devicePixelRatio, timeColor, timeScaleHeight, canvasInfo, visibleChunkIndices]);
 
   return (
     <PlaylistTimeScaleScroll

packages/ui-components/src/contexts/ScrollViewport.tsx

@@ -166,7 +166,7 @@ export function useScrollViewportSelector<T>(
  * Only triggers a re-render when the set of visible chunks changes, not on every scroll pixel.
  *
  * @param totalWidth Total width in CSS pixels of the content being chunked.
- * @param chunkWidth Width of each chunk in CSS pixels. Defaults to MAX_CANVAS_WIDTH (1000).
+ * @param chunkWidth Width of each chunk in CSS pixels (typically MAX_CANVAS_WIDTH, 1000).
  */
 export function useVisibleChunkIndices(totalWidth: number, chunkWidth: number): number[] {
   const visibleChunkKey = useScrollViewportSelector((viewport) => {

packages/ui-components/src/hooks/useChunkedCanvasRefs.ts

@@ -0,0 +1,41 @@
+import { useCallback, useEffect, useRef } from 'react';
+
+/**
+ * Manages canvas element refs for chunked virtual-scroll rendering.
+ *
+ * Provides a callback ref (for `ref={canvasRef}`) that stores canvases
+ * by their `data-index` chunk index, and automatically cleans up refs
+ * for canvases that have been unmounted by the virtualizer.
+ *
+ * Used by Channel, TimeScale, and SpectrogramChannel.
+ *
+ * @returns
+ * - `canvasRef` — Callback ref to attach to each `<canvas data-index={i}>` element.
+ * - `canvasMapRef` — Stable ref to a `Map<number, HTMLCanvasElement>` for iterating
+ *   over mounted canvases during draw effects.
+ */
+export function useChunkedCanvasRefs() {
+  const canvasMapRef = useRef<Map<number, HTMLCanvasElement>>(new Map());
+
+  const canvasRef = useCallback((canvas: HTMLCanvasElement | null) => {
+    if (canvas !== null) {
+      const idx = parseInt(canvas.dataset.index!, 10);
+      canvasMapRef.current.set(idx, canvas);
+    }
+  }, []);
+
+  // Clean up stale refs for unmounted chunks.
+  // Intentionally has no dependency array — runs after every render because
+  // the virtualizer can unmount canvases at any time, and drawing effects
+  // need the map pruned before they iterate it.
+  useEffect(() => {
+    const map = canvasMapRef.current;
+    for (const [idx, canvas] of map.entries()) {
+      if (!canvas.isConnected) {
+        map.delete(idx);
+      }
+    }
+  });
+
+  return { canvasRef, canvasMapRef };
+}