feat: implement per-track and master effect chains (Option 3)

Architecture:
- Each track now has its own effect chain stored in track.effectChain
- Separate master effect chain for the final mix output
- SidePanel has 3 tabs: Tracks, Track FX, Master FX

Changes:
- types/track.ts: Add effectChain field to Track interface
- lib/audio/track-utils.ts: Initialize effect chain when creating tracks
- lib/hooks/useMultiTrack.ts: Exclude effectChain from localStorage, recreate on load
- components/editor/AudioEditor.tsx:
  - Add master effect chain state using useEffectChain hook
  - Add handlers for per-track effect chain manipulation
  - Pass both track and master effect chains to SidePanel
- components/layout/SidePanel.tsx:
  - Update to 3-tab interface (Tracks | Track FX | Master FX)
  - Track FX tab shows effects for currently selected track
  - Master FX tab shows master bus effects with preset management
  - Different icons for track vs master effects tabs

Note: Effect processing in Web Audio API not yet implemented.
This commit sets up the data structures and UI.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

components/editor/AudioEditor.tsx

@@ -44,17 +44,17 @@ export function AudioEditor() {
     togglePlayPause,
   } = useMultiTrackPlayer(tracks, masterVolume);
 
-  // Effect chain (for selected track)
+  // Master effect chain
   const {
-    chain: effectChain,
+    chain: masterEffectChain,
-    presets: effectPresets,
+    presets: masterEffectPresets,
-    toggleEffectEnabled,
+    toggleEffectEnabled: toggleMasterEffect,
-    removeEffect,
+    removeEffect: removeMasterEffect,
-    reorder: reorderEffects,
+    reorder: reorderMasterEffects,
-    clearChain,
+    clearChain: clearMasterChain,
-    savePreset,
+    savePreset: saveMasterPreset,
-    loadPresetToChain,
+    loadPresetToChain: loadMasterPreset,
-    deletePreset,
+    deletePreset: deleteMasterPreset,
   } = useEffectChain();
 
   // Multi-track handlers
@@ -84,6 +84,48 @@ export function AudioEditor() {
     }
   };
 
+  // Per-track effect chain handlers
+  const handleToggleTrackEffect = (effectId: string) => {
+    if (!selectedTrack) return;
+    const updatedChain = {
+      ...selectedTrack.effectChain,
+      effects: selectedTrack.effectChain.effects.map((e) =>
+        e.id === effectId ? { ...e, enabled: !e.enabled } : e
+      ),
+    };
+    updateTrack(selectedTrack.id, { effectChain: updatedChain });
+  };
+
+  const handleRemoveTrackEffect = (effectId: string) => {
+    if (!selectedTrack) return;
+    const updatedChain = {
+      ...selectedTrack.effectChain,
+      effects: selectedTrack.effectChain.effects.filter((e) => e.id !== effectId),
+    };
+    updateTrack(selectedTrack.id, { effectChain: updatedChain });
+  };
+
+  const handleReorderTrackEffects = (fromIndex: number, toIndex: number) => {
+    if (!selectedTrack) return;
+    const effects = [...selectedTrack.effectChain.effects];
+    const [removed] = effects.splice(fromIndex, 1);
+    effects.splice(toIndex, 0, removed);
+    const updatedChain = {
+      ...selectedTrack.effectChain,
+      effects,
+    };
+    updateTrack(selectedTrack.id, { effectChain: updatedChain });
+  };
+
+  const handleClearTrackChain = () => {
+    if (!selectedTrack) return;
+    const updatedChain = {
+      ...selectedTrack.effectChain,
+      effects: [],
+    };
+    updateTrack(selectedTrack.id, { effectChain: updatedChain });
+  };
+
   // Zoom controls
   const handleZoomIn = () => {
     setZoom((prev) => Math.min(20, prev + 1));
@@ -254,15 +296,20 @@ export function AudioEditor() {
           onUpdateTrack={updateTrack}
           onRemoveTrack={handleRemoveTrack}
           onClearTracks={handleClearTracks}
-          effectChain={effectChain}
+          trackEffectChain={selectedTrack?.effectChain ?? null}
-          effectPresets={effectPresets}
+          onToggleTrackEffect={handleToggleTrackEffect}
-          onToggleEffect={toggleEffectEnabled}
+          onRemoveTrackEffect={handleRemoveTrackEffect}
-          onRemoveEffect={removeEffect}
+          onReorderTrackEffects={handleReorderTrackEffects}
-          onReorderEffects={reorderEffects}
+          onClearTrackChain={handleClearTrackChain}
-          onSavePreset={savePreset}
+          masterEffectChain={masterEffectChain}
-          onLoadPreset={loadPresetToChain}
+          masterEffectPresets={masterEffectPresets}
-          onDeletePreset={deletePreset}
+          onToggleMasterEffect={toggleMasterEffect}
-          onClearChain={clearChain}
+          onRemoveMasterEffect={removeMasterEffect}
+          onReorderMasterEffects={reorderMasterEffects}
+          onSaveMasterPreset={saveMasterPreset}
+          onLoadMasterPreset={loadMasterPreset}
+          onDeleteMasterPreset={deleteMasterPreset}
+          onClearMasterChain={clearMasterChain}
         />
 
         {/* Main canvas area */}

components/layout/SidePanel.tsx

@@ -28,16 +28,23 @@ export interface SidePanelProps {
   onRemoveTrack: (trackId: string) => void;
   onClearTracks: () => void;
 
-  // Effect chain
+  // Track effect chain (for selected track)
-  effectChain: EffectChain;
+  trackEffectChain: EffectChain | null;
-  effectPresets: EffectPreset[];
+  onToggleTrackEffect: (effectId: string) => void;
-  onToggleEffect: (effectId: string) => void;
+  onRemoveTrackEffect: (effectId: string) => void;
-  onRemoveEffect: (effectId: string) => void;
+  onReorderTrackEffects: (fromIndex: number, toIndex: number) => void;
-  onReorderEffects: (fromIndex: number, toIndex: number) => void;
+  onClearTrackChain: () => void;
-  onSavePreset: (preset: EffectPreset) => void;
+
-  onLoadPreset: (preset: EffectPreset) => void;
+  // Master effect chain
-  onDeletePreset: (presetId: string) => void;
+  masterEffectChain: EffectChain;
-  onClearChain: () => void;
+  masterEffectPresets: EffectPreset[];
+  onToggleMasterEffect: (effectId: string) => void;
+  onRemoveMasterEffect: (effectId: string) => void;
+  onReorderMasterEffects: (fromIndex: number, toIndex: number) => void;
+  onSaveMasterPreset: (preset: EffectPreset) => void;
+  onLoadMasterPreset: (preset: EffectPreset) => void;
+  onDeleteMasterPreset: (presetId: string) => void;
+  onClearMasterChain: () => void;
 
   className?: string;
 }
@@ -51,19 +58,24 @@ export function SidePanel({
   onUpdateTrack,
   onRemoveTrack,
   onClearTracks,
-  effectChain,
+  trackEffectChain,
-  effectPresets,
+  onToggleTrackEffect,
-  onToggleEffect,
+  onRemoveTrackEffect,
-  onRemoveEffect,
+  onReorderTrackEffects,
-  onReorderEffects,
+  onClearTrackChain,
-  onSavePreset,
+  masterEffectChain,
-  onLoadPreset,
+  masterEffectPresets,
-  onDeletePreset,
+  onToggleMasterEffect,
-  onClearChain,
+  onRemoveMasterEffect,
+  onReorderMasterEffects,
+  onSaveMasterPreset,
+  onLoadMasterPreset,
+  onDeleteMasterPreset,
+  onClearMasterChain,
   className,
 }: SidePanelProps) {
   const [isCollapsed, setIsCollapsed] = React.useState(false);
-  const [activeTab, setActiveTab] = React.useState<'tracks' | 'chain'>('tracks');
+  const [activeTab, setActiveTab] = React.useState<'tracks' | 'trackFx' | 'masterFx'>('tracks');
   const [presetDialogOpen, setPresetDialogOpen] = React.useState(false);
 
   const selectedTrack = tracks.find((t) => t.id === selectedTrackId);
@@ -102,13 +114,21 @@ export function SidePanel({
             <Music2 className="h-4 w-4" />
           </Button>
           <Button
-            variant={activeTab === 'chain' ? 'secondary' : 'ghost'}
+            variant={activeTab === 'trackFx' ? 'secondary' : 'ghost'}
             size="icon-sm"
-            onClick={() => setActiveTab('chain')}
+            onClick={() => setActiveTab('trackFx')}
-            title="Effect Chain"
+            title="Track Effects"
           >
             <Link2 className="h-4 w-4" />
           </Button>
+          <Button
+            variant={activeTab === 'masterFx' ? 'secondary' : 'ghost'}
+            size="icon-sm"
+            onClick={() => setActiveTab('masterFx')}
+            title="Master Effects"
+          >
+            <Link2 className="h-4 w-4 text-primary" />
+          </Button>
         </div>
         <Button
           variant="ghost"
@@ -186,29 +206,21 @@ export function SidePanel({
           </>
         )}
 
-        {activeTab === 'chain' && (
+        {activeTab === 'trackFx' && (
           <div className="space-y-2">
             <div className="flex items-center justify-between">
               <h3 className="text-xs font-semibold text-muted-foreground uppercase">
-                Effect Chain
+                Track Effects
                 {selectedTrack && (
                   <span className="text-primary ml-2">({String(selectedTrack.name || 'Untitled Track')})</span>
                 )}
               </h3>
               <div className="flex gap-1">
-                <Button
+                {trackEffectChain && trackEffectChain.effects.length > 0 && (
-                  variant="ghost"
-                  size="icon-sm"
-                  onClick={() => setPresetDialogOpen(true)}
-                  title="Manage presets"
-                >
-                  <FolderOpen className="h-4 w-4" />
-                </Button>
-                {effectChain.effects.length > 0 && (
                   <Button
                     variant="ghost"
                     size="icon-sm"
-                    onClick={onClearChain}
+                    onClick={onClearTrackChain}
                     title="Clear all effects"
                   >
                     <Trash2 className="h-4 w-4 text-destructive" />
@@ -225,28 +237,63 @@ export function SidePanel({
                 </p>
               </div>
             ) : (
-              <>
+              <EffectRack
-                <EffectRack
+                chain={trackEffectChain!}
-                  chain={effectChain}
+                onToggleEffect={onToggleTrackEffect}
-                  onToggleEffect={onToggleEffect}
+                onRemoveEffect={onRemoveTrackEffect}
-                  onRemoveEffect={onRemoveEffect}
+                onReorderEffects={onReorderTrackEffects}
-                  onReorderEffects={onReorderEffects}
+              />
-                />
-                <PresetManager
-                  open={presetDialogOpen}
-                  onClose={() => setPresetDialogOpen(false)}
-                  currentChain={effectChain}
-                  presets={effectPresets}
-                  onSavePreset={onSavePreset}
-                  onLoadPreset={onLoadPreset}
-                  onDeletePreset={onDeletePreset}
-                  onExportPreset={() => {}}
-                  onImportPreset={(preset) => onSavePreset(preset)}
-                />
-              </>
             )}
           </div>
         )}
+
+        {activeTab === 'masterFx' && (
+          <div className="space-y-2">
+            <div className="flex items-center justify-between">
+              <h3 className="text-xs font-semibold text-muted-foreground uppercase">
+                Master Effects
+              </h3>
+              <div className="flex gap-1">
+                <Button
+                  variant="ghost"
+                  size="icon-sm"
+                  onClick={() => setPresetDialogOpen(true)}
+                  title="Manage presets"
+                >
+                  <FolderOpen className="h-4 w-4" />
+                </Button>
+                {masterEffectChain.effects.length > 0 && (
+                  <Button
+                    variant="ghost"
+                    size="icon-sm"
+                    onClick={onClearMasterChain}
+                    title="Clear all effects"
+                  >
+                    <Trash2 className="h-4 w-4 text-destructive" />
+                  </Button>
+                )}
+              </div>
+            </div>
+
+            <EffectRack
+              chain={masterEffectChain}
+              onToggleEffect={onToggleMasterEffect}
+              onRemoveEffect={onRemoveMasterEffect}
+              onReorderEffects={onReorderMasterEffects}
+            />
+            <PresetManager
+              open={presetDialogOpen}
+              onClose={() => setPresetDialogOpen(false)}
+              currentChain={masterEffectChain}
+              presets={masterEffectPresets}
+              onSavePreset={onSaveMasterPreset}
+              onLoadPreset={onLoadMasterPreset}
+              onDeletePreset={onDeleteMasterPreset}
+              onExportPreset={() => {}}
+              onImportPreset={(preset) => onSaveMasterPreset(preset)}
+            />
+          </div>
+        )}
       </div>
     </div>
   );

lib/audio/track-utils.ts

@@ -4,6 +4,7 @@
 
 import type { Track, TrackColor } from '@/types/track';
 import { DEFAULT_TRACK_HEIGHT, TRACK_COLORS } from '@/types/track';
+import { createEffectChain } from '@/lib/audio/effects/chain';
 
 /**
  * Generate a unique track ID
@@ -33,6 +34,7 @@ export function createTrack(name?: string, color?: TrackColor): Track {
     mute: false,
     solo: false,
     recordEnabled: false,
+    effectChain: createEffectChain(`${trackName} Effects`),
     collapsed: false,
     selected: false,
   };

lib/hooks/useMultiTrack.ts

@@ -1,6 +1,7 @@
 import { useState, useCallback, useEffect } from 'react';
 import type { Track } from '@/types/track';
 import { createTrack, createTrackFromBuffer } from '@/lib/audio/track-utils';
+import { createEffectChain } from '@/lib/audio/effects/chain';
 
 const STORAGE_KEY = 'audio-ui-multi-track';
 
@@ -24,11 +25,12 @@ export function useMultiTrack() {
           return [];
         }
 
-        // Note: AudioBuffers can't be serialized, so we only restore track metadata
+        // Note: AudioBuffers and EffectChains can't be serialized, so we only restore track metadata
         return parsed.map((t: any) => ({
           ...t,
           name: String(t.name || 'Untitled Track'), // Ensure name is always a string
           audioBuffer: null, // Will need to be reloaded
+          effectChain: createEffectChain(`${t.name} Effects`), // Recreate effect chain
         }));
       }
     } catch (error) {
@@ -45,7 +47,7 @@ export function useMultiTrack() {
     if (typeof window === 'undefined') return;
 
     try {
-      // Only save serializable fields, excluding audioBuffer and any DOM references
+      // Only save serializable fields, excluding audioBuffer, effectChain, and any DOM references
       const trackData = tracks.map((track) => ({
         id: track.id,
         name: String(track.name || 'Untitled Track'),
@@ -58,6 +60,7 @@ export function useMultiTrack() {
         recordEnabled: track.recordEnabled,
         collapsed: track.collapsed,
         selected: track.selected,
+        // Note: effectChain is excluded - will be recreated on load
       }));
       localStorage.setItem(STORAGE_KEY, JSON.stringify(trackData));
     } catch (error) {

types/track.ts

@@ -2,6 +2,8 @@
  * Multi-track types and interfaces
  */
 
+import type { EffectChain } from '@/lib/audio/effects/chain';
+
 export interface Track {
   id: string;
   name: string;
@@ -16,6 +18,9 @@ export interface Track {
   solo: boolean;
   recordEnabled: boolean;
 
+  // Effects
+  effectChain: EffectChain;
+
   // UI state
   collapsed: boolean;
   selected: boolean;