Add IndexedDB preset caching with background prefetch

- Backend: stateless GET /api/preset-stem/{name}/{stem} endpoint serves
int16 PCM without creating a session (used by prefetcher)
- New presetCache.js: IndexedDB wrapper with versioned keys for cache
invalidation when preset audio changes
- New usePresetCache.js: on app mount, checks IndexedDB for each preset
and background-fetches any that are missing
- useAudioEngine: added loadStemsFromBytes() to build AudioBuffers
directly from cached bytes with no network round-trip
- App.jsx: cache-aware handleStemsReady — uses loadStemsFromBytes on
cache hit, falls back to loadStems on miss
- FileUpload: shows ✓ / … status badge per preset in dropdown

First visit: background prefetch populates IndexedDB while user explores
the UI. Subsequent visits: preset loads are instant from local cache.
Uncommented AI continuation section in ControlPanel.

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

backend/routers/presets.py

@@ -6,7 +6,7 @@ import io
 import numpy as np
 import soundfile as sf
 import mido
-from fastapi import APIRouter, HTTPException
+from fastapi import APIRouter, HTTPException, Response
 
 from ..models.session import create_session, StemData
 from ..models.schemas import UploadResponse
@@ -27,6 +27,34 @@ async def list_presets():
     return {"presets": presets}
 
 
+@router.get("/preset-stem/{preset_name}/{stem_name}")
+async def get_preset_stem_pcm(preset_name: str, stem_name: str):
+    """Serve a single preset stem as raw int16 PCM — stateless, no session created."""
+    wav_path = PRESETS_DIR / preset_name / f"{stem_name}.wav"
+    if not wav_path.exists():
+        raise HTTPException(status_code=404, detail=f"Stem '{stem_name}' not found in preset '{preset_name}'")
+
+    audio, sr = sf.read(str(wav_path))
+    audio = audio.astype(np.float32)
+    if audio.ndim == 2:
+        audio = np.mean(audio, axis=1).astype(np.float32)
+
+    num_frames = len(audio)
+    pcm_bytes = (audio * 32767).astype(np.int16).tobytes()
+
+    return Response(
+        content=pcm_bytes,
+        media_type="application/octet-stream",
+        headers={
+            "X-Sample-Rate": str(sr),
+            "X-Channels": "1",
+            "X-Frames": str(num_frames),
+            "X-Bit-Depth": "16",
+            "Access-Control-Expose-Headers": "X-Sample-Rate, X-Channels, X-Frames, X-Bit-Depth",
+        }
+    )
+
+
 @router.post("/preset/{preset_name}", response_model=UploadResponse)
 async def load_preset(preset_name: str):
     """Load a pre-committed preset into a session (no upload needed)."""

frontend/src/App.jsx

@@ -1,4 +1,4 @@
-import React, { useState, useCallback, useEffect } from 'react'
+import React, { useState, useRef, useCallback, useEffect } from 'react'
 import FileUpload from './components/FileUpload'
 import AnalysisDisplay from './components/AnalysisDisplay'
 import ControlPanel from './components/ControlPanel'
@@ -9,6 +9,8 @@ import ProcessingOverlay from './components/ProcessingOverlay'
 import { useSession } from './hooks/useSession'
 import { useAudioEngine } from './hooks/useAudioEngine'
 import { useProcessingProgress } from './hooks/useProcessingProgress'
+import { usePresetCache } from './hooks/usePresetCache'
+import { getCachedPreset } from './utils/presetCache'
 
 function App() {
   const {
@@ -37,6 +39,7 @@ function App() {
     pans,
     analyserData,
     loadStems,
+    loadStemsFromBytes,
     play,
     pause,
     stop,
@@ -51,6 +54,11 @@ function App() {
     clearBufferCache
   } = useAudioEngine()
 
+  const { cacheStatus } = usePresetCache()
+
+  // Tracks which preset is currently being loaded so handleStemsReady can check the cache
+  const currentPresetNameRef = useRef(null)
+
   const [isProcessing, setIsProcessing] = useState(false)
   const [isGenerating, setIsGenerating] = useState(false)
   const [continuationReady, setContinuationReady] = useState(false)
@@ -67,9 +75,15 @@ function App() {
   const hasRegion = regionStart !== null && regionEnd !== null
 
   const handleUpload = useCallback(async (files) => {
+    currentPresetNameRef.current = null
     await upload(files)
   }, [upload])
 
+  const handleLoadPreset = useCallback(async (presetName) => {
+    currentPresetNameRef.current = presetName
+    await loadPreset(presetName)
+  }, [loadPreset])
+
   const handleProcess = useCallback(async (semitones, targetBpm) => {
     setIsProcessing(true)
     resetProgress()
@@ -133,18 +147,23 @@ function App() {
   const handleStemsReady = useCallback(async () => {
     if (sessionId && stems.length > 0) {
       console.log('=== handleStemsReady called ===')
-      console.log('Session:', sessionId)
-      console.log('Stems to load:', stems)
-      const start = performance.now()
+      const presetName = currentPresetNameRef.current
+      if (presetName) {
+        const cached = await getCachedPreset(presetName, stems)
+        if (cached) {
+          console.log(`[preset] Cache hit for '${presetName}' — loading from IndexedDB`)
+          await loadStemsFromBytes(cached)
+          return
+        }
+        console.log(`[preset] Cache miss for '${presetName}' — fetching from network`)
+      }
       try {
         await loadStems(sessionId, stems)
-        const end = performance.now()
-        console.log(`=== handleStemsReady completed in ${(end - start).toFixed(0)}ms ===`)
       } catch (err) {
         console.error('Failed to load stems:', err)
       }
     }
-  }, [sessionId, stems, loadStems])
+  }, [sessionId, stems, loadStems, loadStemsFromBytes])
 
   // Track full song duration whenever we're in full mode and duration updates
   useEffect(() => {
@@ -167,10 +186,11 @@ function App() {
 
           <FileUpload
             onUpload={handleUpload}
-            onLoadPreset={loadPreset}
+            onLoadPreset={handleLoadPreset}
             loading={loading}
             error={error}
             onClearError={clearError}
+            cacheStatus={cacheStatus}
           />
         </div>
       </div>

frontend/src/components/ControlPanel.jsx

@@ -351,7 +351,6 @@ function ControlPanel({ detection, onProcess, isProcessing, hasRegion, isGenerat
         {isProcessing ? 'Processing...' : hasChanges ? (hasRegion ? 'Apply to Selection' : 'Apply Changes') : 'No Changes'}
       </button>
 
-      {/* AI Continuation — always visible */}
       <div className="mt-6 pt-6 border-t border-gray-700/50">
         <h3 className="text-sm font-semibold text-white mb-3">AI Continuation</h3>
         <input

frontend/src/components/FileUpload.jsx

@@ -8,7 +8,7 @@ const STEM_TYPES = [
   { name: 'click_record', label: 'Click Record', icon: '⏱️' }
 ]
 
-function FileUpload({ onUpload, onLoadPreset, loading, error, onClearError }) {
+function FileUpload({ onUpload, onLoadPreset, loading, error, onClearError, cacheStatus = {} }) {
   const [presets, setPresets] = useState([])
   const [selectedPreset, setSelectedPreset] = useState('')
 
@@ -107,9 +107,15 @@ function FileUpload({ onUpload, onLoadPreset, loading, error, onClearError }) {
               className="flex-1 bg-gray-800 border border-gray-600 rounded-lg px-3 py-2 text-white text-sm focus:outline-none focus:border-primary-500"
             >
               <option value="">Select a demo...</option>
-              {presets.map(p => (
-                <option key={p} value={p}>{p}</option>
-              ))}
+              {presets.map(p => {
+                const status = cacheStatus[p]
+                const label = status === 'cached'
+                  ? `${p} ✓`
+                  : status === 'loading'
+                    ? `${p} …`
+                    : p
+                return <option key={p} value={p}>{label}</option>
+              })}
             </select>
             <button
               onClick={() => selectedPreset && onLoadPreset(selectedPreset)}
@@ -119,6 +125,12 @@ function FileUpload({ onUpload, onLoadPreset, loading, error, onClearError }) {
               {loading ? 'Loading...' : 'Load'}
             </button>
           </div>
+          {selectedPreset && cacheStatus[selectedPreset] === 'cached' && (
+            <p className="text-xs text-green-400/70 mt-2">Ready — will load instantly from local cache</p>
+          )}
+          {selectedPreset && cacheStatus[selectedPreset] === 'loading' && (
+            <p className="text-xs text-yellow-400/70 mt-2">Caching in background…</p>
+          )}
         </div>
       )}
 

frontend/src/hooks/useAudioEngine.js

@@ -262,6 +262,95 @@ export function useAudioEngine() {
     console.log(`Duration: ${maxDuration.toFixed(1)}s`)
   }, [initAudio])
 
+  // Load stems directly from cached IndexedDB bytes — no network fetch needed.
+  // stemsData shape: { stemName: { bytes: ArrayBuffer, sampleRate, numChannels, numFrames } }
+  const loadStemsFromBytes = useCallback(async (stemsData) => {
+    const totalStart = performance.now()
+    console.log('=== STEM LOADING FROM CACHE START ===')
+
+    const ctx = initAudio()
+
+    // Disconnect existing audio graph nodes
+    Object.values(gainsRef.current).forEach(g => g?.disconnect())
+    Object.values(compressorsRef.current).forEach(c => c?.disconnect())
+    Object.values(pannersRef.current).forEach(p => p?.disconnect())
+    Object.values(reverbGainsRef.current).forEach(r => r?.disconnect())
+    Object.values(reverbSendsRef.current).forEach(r => r?.disconnect())
+    buffersRef.current = {}
+    gainsRef.current = {}
+    compressorsRef.current = {}
+    pannersRef.current = {}
+    reverbGainsRef.current = {}
+    reverbSendsRef.current = {}
+    setIsLoaded(false)
+
+    const newVolumes = {}
+    let maxDuration = 0
+
+    for (const [stem, { bytes, sampleRate, numChannels, numFrames }] of Object.entries(stemsData)) {
+      const int16 = new Int16Array(bytes)
+      const float32 = new Float32Array(int16.length)
+      for (let i = 0; i < int16.length; i++) {
+        float32[i] = int16[i] / 32767
+      }
+      const audioBuffer = ctx.createBuffer(numChannels, numFrames, sampleRate)
+      audioBuffer.copyToChannel(float32, 0)
+
+      buffersRef.current[stem] = audioBuffer
+      if (audioBuffer.duration > maxDuration) maxDuration = audioBuffer.duration
+      newVolumes[stem] = 1
+
+      // Effect chain: source → gain → compressor → panner → (dry + wet reverb) → master
+      gainsRef.current[stem] = ctx.createGain()
+
+      compressorsRef.current[stem] = ctx.createDynamicsCompressor()
+      compressorsRef.current[stem].threshold.value = -24
+      compressorsRef.current[stem].knee.value = 30
+      compressorsRef.current[stem].ratio.value = 4
+      compressorsRef.current[stem].attack.value = 0.003
+      compressorsRef.current[stem].release.value = 0.25
+
+      pannersRef.current[stem] = ctx.createStereoPanner()
+      const stemLower = stem.toLowerCase()
+      let defaultPan = 0
+      if (stemLower.includes('bass')) defaultPan = 0
+      else if (stemLower.includes('drum')) defaultPan = 0
+      else if (stemLower.includes('guitar')) defaultPan = -0.3
+      else if (stemLower.includes('synth')) defaultPan = 0.3
+      else if (stemLower.includes('keys')) defaultPan = 0.2
+      else if (stemLower.includes('vocal')) defaultPan = 0
+      else defaultPan = (Math.random() - 0.5) * 0.4
+      pannersRef.current[stem].pan.value = defaultPan
+
+      reverbSendsRef.current[stem] = ctx.createGain()
+      reverbSendsRef.current[stem].gain.value = 0
+
+      gainsRef.current[stem].connect(compressorsRef.current[stem])
+      compressorsRef.current[stem].connect(pannersRef.current[stem])
+      pannersRef.current[stem].connect(masterGainRef.current)
+      pannersRef.current[stem].connect(reverbSendsRef.current[stem])
+      reverbSendsRef.current[stem].connect(convolverRef.current)
+    }
+
+    const newReverbs = {}
+    const newPans = {}
+    Object.keys(buffersRef.current).forEach(stem => {
+      newReverbs[stem] = 0.15
+      newPans[stem] = pannersRef.current[stem]?.pan.value || 0
+    })
+
+    setDuration(maxDuration)
+    setVolumes(newVolumes)
+    setReverbs(newReverbs)
+    setPans(newPans)
+    setSolos({})
+    setMutes({})
+    setIsLoaded(true)
+    pauseTimeRef.current = 0
+
+    console.log(`=== STEM LOADING FROM CACHE COMPLETE in ${(performance.now() - totalStart).toFixed(0)}ms ===`)
+  }, [initAudio])
+
   // Get frequency data for visualization
   const getAnalyserData = useCallback(() => {
     if (!analyserRef.current) return null
@@ -564,6 +653,7 @@ export function useAudioEngine() {
 
     // Methods
     loadStems,
+    loadStemsFromBytes,
     play,
     pause,
     stop,

frontend/src/hooks/usePresetCache.js

@@ -0,0 +1,76 @@
+import { useState, useEffect, useCallback } from 'react'
+import { isCached, cacheStem } from '../utils/presetCache'
+
+const STEM_NAMES = ['guitar', 'drums', 'bass', 'synth', 'click_record']
+
+/**
+ * Checks IndexedDB for cached presets on mount, then background-fetches
+ * any that are missing using the stateless /api/preset-stem endpoint.
+ *
+ * Returns cacheStatus: { [presetName]: 'cached' | 'loading' | 'uncached' }
+ */
+export function usePresetCache() {
+  const [cacheStatus, setCacheStatus] = useState({})
+
+  const prefetchPreset = useCallback(async (presetName) => {
+    setCacheStatus(prev => ({ ...prev, [presetName]: 'loading' }))
+    try {
+      const results = await Promise.all(
+        STEM_NAMES.map(async (stemName) => {
+          const response = await fetch(`/api/preset-stem/${presetName}/${stemName}`)
+          if (!response.ok) return false
+
+          const sampleRate = parseInt(response.headers.get('X-Sample-Rate'))
+          const numChannels = parseInt(response.headers.get('X-Channels'))
+          const numFrames = parseInt(response.headers.get('X-Frames'))
+          const bytes = await response.arrayBuffer()
+
+          await cacheStem(presetName, stemName, { bytes, sampleRate, numChannels, numFrames })
+          return true
+        })
+      )
+
+      const allOk = results.every(Boolean)
+      setCacheStatus(prev => ({ ...prev, [presetName]: allOk ? 'cached' : 'uncached' }))
+    } catch {
+      setCacheStatus(prev => ({ ...prev, [presetName]: 'uncached' }))
+    }
+  }, [])
+
+  useEffect(() => {
+    let cancelled = false
+
+    async function init() {
+      try {
+        const res = await fetch('/api/presets')
+        const { presets } = await res.json()
+        if (cancelled || !presets?.length) return
+
+        // Check which presets are already in IndexedDB
+        const statuses = {}
+        await Promise.all(
+          presets.map(async (name) => {
+            statuses[name] = (await isCached(name, STEM_NAMES)) ? 'cached' : 'uncached'
+          })
+        )
+        if (cancelled) return
+        setCacheStatus(statuses)
+
+        // Background-fetch uncached presets one at a time to avoid saturating bandwidth
+        for (const name of presets) {
+          if (cancelled) break
+          if (statuses[name] === 'uncached') {
+            await prefetchPreset(name)
+          }
+        }
+      } catch {
+        // Prefetch is best-effort — silently fail
+      }
+    }
+
+    init()
+    return () => { cancelled = true }
+  }, [prefetchPreset])
+
+  return { cacheStatus }
+}

frontend/src/utils/presetCache.js

@@ -0,0 +1,88 @@
+/**
+ * IndexedDB cache for preset stem PCM data.
+ * Stores raw int16 bytes + metadata so preset loads are instant after first visit.
+ *
+ * Bump CACHE_VERSION whenever preset audio files change on the server —
+ * old entries will be ignored and re-fetched.
+ */
+
+const DB_NAME = 'jam-tracks-presets'
+const DB_VERSION = 1
+const STORE_NAME = 'stems'
+export const CACHE_VERSION = 1
+
+function openDB() {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(DB_NAME, DB_VERSION)
+    req.onupgradeneeded = (e) => {
+      const db = e.target.result
+      if (!db.objectStoreNames.contains(STORE_NAME)) {
+        db.createObjectStore(STORE_NAME)
+      }
+    }
+    req.onsuccess = (e) => resolve(e.target.result)
+    req.onerror = (e) => reject(e.target.error)
+  })
+}
+
+function dbGet(db, key) {
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_NAME, 'readonly')
+    const req = tx.objectStore(STORE_NAME).get(key)
+    req.onsuccess = (e) => resolve(e.target.result)
+    req.onerror = (e) => reject(e.target.error)
+  })
+}
+
+function dbPut(db, key, value) {
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_NAME, 'readwrite')
+    const req = tx.objectStore(STORE_NAME).put(value, key)
+    req.onsuccess = () => resolve()
+    req.onerror = (e) => reject(e.target.error)
+  })
+}
+
+function stemKey(presetName, stemName) {
+  return `v${CACHE_VERSION}:${presetName}:${stemName}`
+}
+
+/** Returns true if all stemNames for this preset are cached. */
+export async function isCached(presetName, stemNames) {
+  try {
+    const db = await openDB()
+    const checks = await Promise.all(stemNames.map(s => dbGet(db, stemKey(presetName, s))))
+    return checks.every(v => v != null)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Returns cached data for all stems or null if any stem is missing.
+ * Shape: { stemName: { bytes: ArrayBuffer, sampleRate, numChannels, numFrames } }
+ */
+export async function getCachedPreset(presetName, stemNames) {
+  try {
+    const db = await openDB()
+    const result = {}
+    for (const stemName of stemNames) {
+      const entry = await dbGet(db, stemKey(presetName, stemName))
+      if (!entry) return null
+      result[stemName] = entry
+    }
+    return result
+  } catch {
+    return null
+  }
+}
+
+/** Store a single stem's PCM data in IndexedDB. */
+export async function cacheStem(presetName, stemName, data) {
+  try {
+    const db = await openDB()
+    await dbPut(db, stemKey(presetName, stemName), data)
+  } catch (err) {
+    console.warn('[presetCache] Failed to cache stem:', err)
+  }
+}