feat: add useDynamicTracks hook and fix layout shift on track load

Add reusable useDynamicTracks hook for runtime track additions (drag-and-drop,
file picker) with instant placeholder feedback while audio decodes in parallel.
Replaces inline loading logic in NewTracksExample with the new hook.

Fix layout shift when placeholder tracks transition to loaded tracks by:
- Removing stale audioBuffers check from PlaylistVisualization loading guard
- Computing displayDuration synchronously from tracks instead of effect-set state
- Ensuring rawChannels floors at 1 to prevent zero-height track collapse
- Generating empty peaks with correct channel count in WaveformPlaylistContext

Hook features:
- Per-track AbortController (Map<trackId, AbortController>) cancels fetches on
  removal and unmount
- loadingIds ref tracks active decodes for accurate loadingCount on removal
- errors state exposes TrackLoadError[] for user-facing failure feedback
- Blob support in TrackSource union (File, Blob, string, or {src, name})
- Uses getGlobalAudioContext() from playout package

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

Author: naomiaro

PROJECT_STRUCTURE.md

@@ -125,7 +125,7 @@ const clip = createClipFromSeconds({
   │   ├── Selection.tsx
   │   ├── AnnotationBox.tsx
   │   └── TrackControls/
-  ├── contexts/          # React contexts (theme, playlist info, playout)
+  ├── contexts/          # React contexts (theme, playlist info, playout, scroll viewport)
   ├── utils/             # Utilities (time formatting, conversions)
   ├── styled/            # Shared styled components
   │   ├── CheckboxStyles.tsx  # Checkbox, label, wrapper
@@ -196,8 +196,10 @@ const clip = createClipFromSeconds({
   ├── index.tsx                         # Main entry point + API exports
   ├── WaveformPlaylistContext.tsx        # Context provider (flexible API)
   ├── MediaElementPlaylistContext.tsx    # Context provider (HTMLAudioElement)
+  ├── AnnotationIntegrationContext.tsx   # Optional annotation integration
   ├── SpectrogramIntegrationContext.tsx  # Optional spectrogram integration
   ├── hooks/                            # Custom hooks
+  │   ├── useAnimationFrameLoop.ts      # Shared rAF loop for providers
   │   ├── useAnnotationDragHandlers.ts  # Annotation drag logic
   │   ├── useAnnotationKeyboardControls.ts # Annotation navigation & editing
   │   ├── useAudioEffects.ts            # Audio effects management
@@ -206,13 +208,14 @@ const clip = createClipFromSeconds({
   │   ├── useClipSplitting.ts           # Split clips at playhead
   │   ├── useDragSensors.ts             # @dnd-kit sensor config
   │   ├── useDynamicEffects.ts          # Master effects chain
+  │   ├── useDynamicTracks.ts           # Runtime track additions (placeholder-then-replace)
   │   ├── useExportWav.ts               # WAV export via Tone.Offline
-  │   ├── useIntegratedRecording.ts     # Recording integration
   │   ├── useKeyboardShortcuts.ts       # Flexible keyboard shortcut system
   │   ├── useMasterVolume.ts            # Master volume control
   │   ├── usePlaybackShortcuts.ts       # Default playback shortcuts
   │   ├── useTimeFormat.ts              # Time formatting
   │   ├── useTrackDynamicEffects.ts     # Per-track effects
+  │   ├── useWaveformDataCache.ts       # Web worker peak generation cache
   │   └── useZoomControls.ts            # Zoom level management
   ├── components/                       # React components
   │   ├── PlaylistVisualization.tsx      # Main waveform + track rendering
@@ -225,6 +228,8 @@ const clip = createClipFromSeconds({
   │   ├── effectDefinitions.ts          # 20 Tone.js effect definitions
   │   ├── effectFactory.ts              # Effect instance creation
   │   └── index.ts
+  ├── workers/                          # Web workers
+  │   └── peaksWorker.ts                # Inline Blob worker for peak generation
   └── waveformDataLoader.ts            # BBC waveform-data.js support
   ```
 - **Build:** Vite + tsup
@@ -631,20 +636,22 @@ Business logic is extracted into reusable custom hooks that can be used by any c
 
 **Hooks (in `packages/browser/src/hooks/`):**
 
-- `useAudioTracks` - Track loading and management
+- `useAnimationFrameLoop` - Shared rAF lifecycle for both playlist providers
+- `useAudioTracks` - Declarative track loading (configs-driven)
 - `useClipDragHandlers` - Clip drag-to-move and boundary trimming
 - `useClipSplitting` - Split clips at playhead
 - `useAnnotationDragHandlers` - Annotation drag logic
 - `useAnnotationKeyboardControls` - Annotation navigation & editing
+- `useDynamicTracks` - Runtime track additions with placeholder-then-replace pattern
 - `useKeyboardShortcuts` - Flexible keyboard shortcut system
 - `usePlaybackShortcuts` - Default playback shortcuts (0 = rewind)
 - `useDynamicEffects` - Master effects chain with runtime parameter updates
 - `useTrackDynamicEffects` - Per-track effects management
 - `useAudioEffects` - Audio effects management
 - `useExportWav` - WAV export via Tone.Offline
-- `useIntegratedRecording` - Recording integration
 - `useMasterVolume` - Master volume control
 - `useTimeFormat` - Time formatting and format selection
+- `useWaveformDataCache` - Web worker peak generation and cache
 - `useZoomControls` - Zoom level management
 - `useDragSensors` - @dnd-kit sensor configuration
 

packages/browser/src/WaveformPlaylistContext.tsx

@@ -578,12 +578,19 @@ export const WaveformPlaylistProvider: React.FC<WaveformPlaylistProviderProps> =
           }
         }
 
-        // Path C: No peaks data available yet — render empty while worker processes
+        // Path C: No peaks data available yet — render empty while worker processes.
+        // Use correct channel count from audioBuffer to prevent track height shift
+        // when peaks arrive (mono mode collapses to 1 channel).
         if (!peaks) {
           if (!clip.audioBuffer && !clip.waveformData) {
             console.warn(`[waveform-playlist] Clip "${clip.id}" has no audio data or waveform data`);
           }
-          peaks = { length: 0, data: [], bits: 16 };
+          const numChannels = mono ? 1 : (clip.audioBuffer?.numberOfChannels ?? 1);
+          peaks = {
+            length: 0,
+            data: Array.from({ length: numChannels }, () => new Int16Array(0)),
+            bits: 16,
+          };
         }
 
         return {

packages/browser/src/components/PlaylistVisualization.tsx

@@ -129,7 +129,6 @@ export const PlaylistVisualization: React.FC<PlaylistVisualizationProps> = ({
     setLoopRegion,
   } = usePlaylistControls();
   const {
-    audioBuffers,
     peaksDataArray,
     trackStates,
     tracks,
@@ -192,8 +191,17 @@ export const PlaylistVisualization: React.FC<PlaylistVisualizationProps> = ({
     setScrollContainer(element);
   }, [setScrollContainer]);
 
-  // Calculate dimensions
-  let displayDuration = audioBuffers.length > 0 ? duration : DEFAULT_EMPTY_TRACK_DURATION;
+  // Calculate dimensions — derive duration directly from tracks prop to prevent width
+  // shift. The `duration` state is set in an effect and lags tracks by at least one render.
+  const tracksMaxDuration = tracks.reduce((max, track) => {
+    return track.clips.reduce((clipMax, clip) => {
+      const end = (clip.startSample + clip.durationSamples) / clip.sampleRate;
+      return Math.max(clipMax, end);
+    }, max);
+  }, 0);
+  let displayDuration = tracksMaxDuration > 0
+    ? tracksMaxDuration
+    : (duration > 0 ? duration : DEFAULT_EMPTY_TRACK_DURATION);
 
   if (recordingState?.isRecording) {
     const recordingEndSample = recordingState.startSample + recordingState.durationSamples;
@@ -235,7 +243,7 @@ export const PlaylistVisualization: React.FC<PlaylistVisualizationProps> = ({
     for (let i = 0; i < peaksDataArray.length; i++) {
       const trackClipPeaks = peaksDataArray[i];
       const rawCh = trackClipPeaks.length > 0
-        ? Math.max(...trackClipPeaks.map(clip => clip.peaks.data.length))
+        ? Math.max(1, ...trackClipPeaks.map(clip => clip.peaks.data.length))
         : 1;
       const trackMode = spectrogram?.trackSpectrogramOverrides.get(tracks[i]?.id)?.renderMode ?? tracks[i]?.renderMode ?? 'waveform';
       const effectiveCh = trackMode === 'both' ? rawCh * 2 : rawCh;
@@ -297,9 +305,12 @@ export const PlaylistVisualization: React.FC<PlaylistVisualizationProps> = ({
     }
   };
 
-  // Only show loading if we have tracks WITH clips but haven't loaded their data yet
+  // Only show loading if we have tracks WITH clips but peaks haven't been computed yet.
+  // Don't check audioBuffers — it's set in an effect and can be stale for one or more
+  // renders after tracks change, causing the playlist to unmount and remount (layout shift).
+  // Placeholder tracks (clips: []) bypass this check intentionally.
   const hasClips = tracks.some(track => track.clips.length > 0);
-  if (hasClips && (audioBuffers.length === 0 || peaksDataArray.length === 0)) {
+  if (hasClips && peaksDataArray.length === 0) {
     return <div className={className}>Loading waveform...</div>;
   }
 
@@ -449,7 +460,7 @@ export const PlaylistVisualization: React.FC<PlaylistVisualizationProps> = ({
                 );
 
                 const rawChannels = trackClipPeaks.length > 0
-                  ? Math.max(...trackClipPeaks.map(clip => clip.peaks.data.length))
+                  ? Math.max(1, ...trackClipPeaks.map(clip => clip.peaks.data.length))
                   : 1;
                 const maxChannels = rawChannels;
 

packages/browser/src/hooks/index.ts

@@ -44,3 +44,6 @@ export type { AnimationFrameLoopControls } from './useAnimationFrameLoop';
 
 export { useWaveformDataCache } from './useWaveformDataCache';
 export type { UseWaveformDataCacheReturn } from './useWaveformDataCache';
+
+export { useDynamicTracks } from './useDynamicTracks';
+export type { TrackSource, TrackLoadError, UseDynamicTracksReturn } from './useDynamicTracks';

packages/browser/src/hooks/useDynamicTracks.ts

@@ -0,0 +1,188 @@
+/**
+ * useDynamicTracks — imperative hook for runtime track additions.
+ *
+ * Complements `useAudioTracks` (declarative, configs-driven) with an
+ * imperative `addTracks()` API for dynamic loading (drag-and-drop, file pickers).
+ *
+ * Placeholder tracks appear instantly while audio decodes in parallel.
+ */
+
+import { useState, useCallback, useRef, useEffect } from 'react';
+import { ClipTrack, createTrack, createClipFromSeconds } from '@waveform-playlist/core';
+import { getGlobalAudioContext } from '@waveform-playlist/playout';
+
+/** A source that can be decoded into a track. */
+export type TrackSource =
+  | File
+  | Blob
+  | string
+  | { src: string; name?: string };
+
+/** Info about a track that failed to load. */
+export interface TrackLoadError {
+  /** Display name of the source that failed. */
+  name: string;
+  /** The underlying error. */
+  error: Error;
+}
+
+export interface UseDynamicTracksReturn {
+  /**
+   * Current tracks array (placeholders + loaded). Pass to WaveformPlaylistProvider.
+   * Placeholder tracks have `clips: []` and names ending with " (loading...)".
+   */
+  tracks: ClipTrack[];
+  /** Add one or more sources — creates placeholder tracks immediately. */
+  addTracks: (sources: TrackSource[]) => void;
+  /** Remove a track by its id. Aborts in-flight fetch/decode if still loading. */
+  removeTrack: (trackId: string) => void;
+  /** Number of sources currently decoding. */
+  loadingCount: number;
+  /** True when any source is still decoding. */
+  isLoading: boolean;
+  /** Tracks that failed to load (removed from `tracks` automatically). */
+  errors: TrackLoadError[];
+}
+
+/** Extract a display name from a TrackSource. */
+function getSourceName(source: TrackSource): string {
+  if (source instanceof File) {
+    return source.name.replace(/\.[^/.]+$/, '');
+  }
+  if (source instanceof Blob) {
+    return 'Untitled';
+  }
+  if (typeof source === 'string') {
+    return source.split('/').pop()?.replace(/\.[^/.]+$/, '') ?? 'Untitled';
+  }
+  return source.name ?? source.src.split('/').pop()?.replace(/\.[^/.]+$/, '') ?? 'Untitled';
+}
+
+/** Decode a TrackSource into an AudioBuffer + clean name. */
+async function decodeSource(
+  source: TrackSource,
+  audioContext: AudioContext,
+  signal?: AbortSignal
+): Promise<{ audioBuffer: AudioBuffer; name: string }> {
+  const name = getSourceName(source);
+
+  // File and Blob: read arrayBuffer directly (not abortable, but we check signal after)
+  if (source instanceof Blob) {
+    const arrayBuffer = await source.arrayBuffer();
+    signal?.throwIfAborted();
+    const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
+    return { audioBuffer, name };
+  }
+
+  const url = typeof source === 'string' ? source : source.src;
+  const response = await fetch(url, { signal });
+  if (!response.ok) throw new Error(`Failed to fetch ${url}: ${response.statusText}`);
+  const arrayBuffer = await response.arrayBuffer();
+  signal?.throwIfAborted();
+  const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
+  return { audioBuffer, name };
+}
+
+export function useDynamicTracks(): UseDynamicTracksReturn {
+  const [tracks, setTracks] = useState<ClipTrack[]>([]);
+  const [loadingCount, setLoadingCount] = useState(0);
+  const [errors, setErrors] = useState<TrackLoadError[]>([]);
+  const cancelledRef = useRef(false);
+  /** Track IDs currently decoding — for accurate loadingCount on removal. */
+  const loadingIdsRef = useRef(new Set<string>());
+  /** Per-track AbortControllers for in-flight fetches — keyed by track ID. */
+  const abortControllersRef = useRef(new Map<string, AbortController>());
+
+  useEffect(() => {
+    const controllers = abortControllersRef.current;
+    return () => {
+      cancelledRef.current = true;
+      for (const controller of controllers.values()) {
+        controller.abort();
+      }
+      controllers.clear();
+    };
+  }, []);
+
+  const addTracks = useCallback((sources: TrackSource[]) => {
+    if (sources.length === 0) return;
+
+    const audioContext = getGlobalAudioContext();
+
+    // 1. Create placeholder tracks immediately
+    const placeholders = sources.map(source => ({
+      track: createTrack({ name: `${getSourceName(source)} (loading...)`, clips: [] }),
+      source,
+    }));
+
+    setTracks(prev => [...prev, ...placeholders.map(p => p.track)]);
+    setLoadingCount(prev => prev + sources.length);
+
+    // 2. Decode each source in parallel (fire-and-forget per source)
+    for (const { track, source } of placeholders) {
+      loadingIdsRef.current.add(track.id);
+      const controller = new AbortController();
+      abortControllersRef.current.set(track.id, controller);
+
+      (async () => {
+        try {
+          const { audioBuffer, name } = await decodeSource(
+            source, audioContext, controller.signal
+          );
+          const clip = createClipFromSeconds({
+            audioBuffer,
+            startTime: 0,
+            duration: audioBuffer.duration,
+            offset: 0,
+            name,
+          });
+
+          // Guard: skip state update if hook unmounted or track was removed while decoding
+          if (!cancelledRef.current && loadingIdsRef.current.has(track.id)) {
+            setTracks(prev => prev.map(t =>
+              t.id === track.id ? { ...t, name, clips: [clip] } : t
+            ));
+          }
+        } catch (error) {
+          if (error instanceof DOMException && error.name === 'AbortError') return;
+          console.warn('[waveform-playlist] Error loading audio:', error);
+          // Guard: skip state update if hook unmounted or track was removed while decoding
+          if (!cancelledRef.current && loadingIdsRef.current.has(track.id)) {
+            setTracks(prev => prev.filter(t => t.id !== track.id));
+            setErrors(prev => [...prev, {
+              name: getSourceName(source),
+              error: error instanceof Error ? error : new Error(String(error)),
+            }]);
+          }
+        } finally {
+          abortControllersRef.current.delete(track.id);
+          if (!cancelledRef.current && loadingIdsRef.current.delete(track.id)) {
+            setLoadingCount(prev => prev - 1);
+          }
+        }
+      })();
+    }
+  }, []);
+
+  const removeTrack = useCallback((trackId: string) => {
+    setTracks(prev => prev.filter(t => t.id !== trackId));
+    // Abort in-flight fetch/decode and update loading state
+    const controller = abortControllersRef.current.get(trackId);
+    if (controller) {
+      controller.abort();
+      abortControllersRef.current.delete(trackId);
+    }
+    if (loadingIdsRef.current.delete(trackId)) {
+      setLoadingCount(prev => prev - 1);
+    }
+  }, []);
+
+  return {
+    tracks,
+    addTracks,
+    removeTrack,
+    loadingCount,
+    isLoading: loadingCount > 0,
+    errors,
+  };
+}

packages/browser/src/index.tsx

@@ -47,6 +47,7 @@ export {
   useDynamicEffects,
   useTrackDynamicEffects,
   useExportWav,
+  useDynamicTracks,
 } from './hooks';
 export type {
   AudioTrackConfig,
@@ -63,6 +64,9 @@ export type {
   ExportOptions,
   ExportResult,
   UseExportWavReturn,
+  TrackSource,
+  TrackLoadError,
+  UseDynamicTracksReturn,
 } from './hooks';
 
 // Export effect definitions and factory