refactor: deepen IPC, export, chop-editor, and analysis modules

Five behavior-preserving deepening refactors:

- IPC contract: single source of truth in electron/ipc-contract.ts. The
  preload bridge and the Window.api type derive from it, and main handlers
  register through a typed handle(), so renderer/main drift becomes a compile
  error instead of a runtime "no handler" / dropped-field bug.
- Export pipeline: extract exportClips() so audio:exportRegions and
  packs:export share one renderer of "chop -> hardware-ready file" instead of
  duplicating the ffmpeg loop.
- Chop editor: lift undo/redo history and autosave out of AudioWaveform into
  useChopHistory and useChopAutosave (809 -> 720 lines).
- Library store: dedupe the fire-and-forget background analysis in importFolder
  and saveChops into one backfillAnalysis helper.
- Audio analysis: move the worker pool behind its runOnWorker interface into
  audioAnalysis.pool.ts, leaving the facade readable.

Claude-Session: https://claude.ai/code/session_01JNA5nzPkMqVmAcSEqkdAMh

Author: RubenGlez

electron/ipc-contract.ts

@@ -0,0 +1,88 @@
+// Single source of truth for the renderer<->main bridge. The grouped `Api` shape is what the
+// renderer sees as `window.api`; the preload bridge is typed against it (so it can't forward the
+// wrong args), `Window.api` is declared from it, and main handlers are registered through the
+// typed `handle` helper keyed by the flattened channel map below. Change a signature here and all
+// three faces fail to compile until they agree.
+import type {
+  Sample,
+  Pack,
+  PackSlot,
+  Project,
+  ProjectRegion,
+  ProjectChop,
+  PackSourceItem,
+  ExportRegionsParams,
+  FreesoundPage,
+} from './types'
+
+export type Api = {
+  library: {
+    getSamples: (filters?: { bpm?: number; key?: string; tags?: string[]; projectId?: string }) => Promise<Sample[]>
+    addSample: (data: { name: string; filePath: string; duration?: number }) => Promise<Sample>
+    updateSample: (id: string, data: Partial<Pick<Sample, 'name' | 'bpm' | 'musicalKey' | 'tags' | 'waveformData'>>) => Promise<void>
+    deleteSample: (id: string) => Promise<void>
+    saveChops: (params: {
+      sourceFilePath: string
+      regions: Array<{ start: number; end: number; name: string }>
+      projectId?: string
+    }) => Promise<Sample[]>
+    importFolder: (folderPath: string) => Promise<{ imported: number; skipped: number }>
+    getPackSlotRefCount: (id: string) => Promise<number>
+    getOrphans: () => Promise<Sample[]>
+    deleteOrphans: (ids: string[]) => Promise<{ deleted: number }>
+  }
+  projects: {
+    getAll: () => Promise<Project[]>
+    get: (id: string) => Promise<Project | null>
+    save: (data: { name: string; sourcePath: string | null; sourceName?: string | null; source?: 'local' | 'freesound'; regions: ProjectRegion[] }) => Promise<Project>
+    update: (id: string, data: Partial<Pick<Project, 'name' | 'sourcePath' | 'regions'>>) => Promise<void>
+    getChops: (projectId: string) => Promise<ProjectChop[]>
+    getAllChops: () => Promise<Array<ProjectChop & { projectName: string; sourcePath: string | null; source: 'local' | 'freesound' }>>
+    upsertChops: (projectId: string, regions: ProjectRegion[]) => Promise<ProjectChop[]>
+    delete: (id: string) => Promise<void>
+    duplicate: (id: string) => Promise<Project | null>
+  }
+  audio: {
+    exportRegions: (params: ExportRegionsParams) => Promise<{ filesWritten: number }>
+    trimSource: (params: { sourceFilePath: string; start: number; end: number }) => Promise<{ filePath: string; duration: number }>
+  }
+  fs: {
+    getPathForFile: (file: File) => string
+    pickFile: () => Promise<string | null>
+    pickFolder: () => Promise<string | null>
+  }
+  settings: {
+    get: (key: string) => Promise<unknown>
+    set: (key: string, value: unknown) => Promise<void>
+  }
+  freesound: {
+    search: (query: string, page?: number, sort?: string, filter?: string) => Promise<FreesoundPage>
+    download: (soundId: number, name: string, previewUrl: string) => Promise<{ name: string; filePath: string }>
+  }
+  shell: {
+    openExternal: (url: string) => Promise<void>
+  }
+  packs: {
+    getAll: () => Promise<Pack[]>
+    getSlots: (packId: string) => Promise<PackSlot[]>
+    getProfiles: () => Promise<Array<{ id: string; name: string; padCount: number }>>
+    create: (data: Pick<Pack, 'name' | 'hardwareProfile'>) => Promise<Pack>
+    upsertSlot: (packId: string, slotNumber: number, source: PackSourceItem) => Promise<void>
+    removeSlot: (packId: string, slotNumber: number) => Promise<void>
+    rename: (id: string, name: string) => Promise<void>
+    delete: (id: string) => Promise<void>
+    export: (packId: string, outputDir: string) => Promise<{ filesWritten: number }>
+  }
+}
+
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never
+
+// Flatten the grouped Api into the flat `group:method` channel names used over IPC, preserving
+// each method's exact signature. This is what main-side `handle` is keyed by.
+export type ApiChannels = UnionToIntersection<
+  {
+    [G in keyof Api]: {
+      [M in keyof Api[G] as `${G & string}:${M & string}`]: Api[G][M]
+    }
+  }[keyof Api]
+>

electron/main/index.ts

@@ -1,11 +1,12 @@
-import { app, BrowserWindow, dialog, shell, session, protocol, net, ipcMain } from 'electron'
+import { app, BrowserWindow, dialog, shell, session, protocol, net } from 'electron'
 import { release } from 'node:os'
 import { dirname, join } from 'node:path'
 import { appendFileSync, existsSync, mkdirSync } from 'node:fs'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { update } from './update'
 import { initDatabase } from './db/index'
 import { materializeProjectChops } from './services/materializeChops'
+import { handle } from './ipc/handle'
 import { registerLibraryHandlers } from './ipc/library'
 import { registerAudioHandlers } from './ipc/audio'
 import { registerFilesystemHandlers } from './ipc/filesystem'
@@ -229,7 +230,7 @@ app.whenReady().then(async () => {
     })
   }
 
-  ipcMain.handle('shell:openExternal', (_, url: string) => {
+  handle('shell:openExternal', (_, url: string) => {
     if (url.startsWith('https:')) shell.openExternal(url)
   })
 

electron/main/ipc/audio.ts

@@ -1,40 +1,29 @@
-import { ipcMain } from 'electron'
-import path from 'node:path'
-import fs from 'node:fs'
-import { getProfile, applyProfileFormat } from '../hardware/profiles'
+import { handle } from './handle'
+import { getProfile } from '../hardware/profiles'
+import { exportClips, type ExportClip } from '../services/export'
 import { trimSourceToCache } from '../services/trim'
-import { configureFfmpeg, ffmpeg } from '../services/ffmpeg'
+import { configureFfmpeg } from '../services/ffmpeg'
 import type { ExportRegionsParams, TrimSourceParams } from '../../types'
 
 configureFfmpeg()
 
 export function registerAudioHandlers(): void {
-  ipcMain.handle('audio:exportRegions', async (_, params: ExportRegionsParams) => {
+  handle('audio:exportRegions', async (_, params: ExportRegionsParams) => {
     const { regions, sourceFilePath, outputDir, profileId } = params
     const profile = getProfile(profileId)
 
-    if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true })
+    const clips: ExportClip[] = regions.map((region, index) => ({
+      sourcePath: sourceFilePath,
+      slotNumber: index,
+      name: region.name || `sample_${index + 1}`,
+      start: region.start,
+      end: region.end,
+    }))
 
-    await Promise.all(
-      regions.map((region, index) =>
-        new Promise<void>((resolve, reject) => {
-          const outputFile = path.join(outputDir, profile.fileName(index, region.name || `sample_${index + 1}`))
-
-          applyProfileFormat(profile, ffmpeg(sourceFilePath)
-            .setStartTime(region.start)
-            .setDuration(region.end - region.start))
-            .output(outputFile)
-            .on('end', () => resolve())
-            .on('error', reject)
-            .run()
-        })
-      )
-    )
-
-    return { filesWritten: regions.length }
+    return exportClips(profile, clips, outputDir)
   })
 
-  ipcMain.handle('audio:trimSource', async (_, params: TrimSourceParams) => {
+  handle('audio:trimSource', async (_, params: TrimSourceParams) => {
     const { sourceFilePath, start, end } = params
     return trimSourceToCache(sourceFilePath, start, end)
   })

electron/main/ipc/filesystem.ts

@@ -1,15 +1,16 @@
-import { ipcMain, dialog } from 'electron'
+import { dialog } from 'electron'
+import { handle } from './handle'
 
 export function registerFilesystemHandlers(): void {
-  ipcMain.handle('fs:pickFile', async () => {
+  handle('fs:pickFile', async () => {
     const result = await dialog.showOpenDialog({
       properties: ['openFile'],
       filters: [{ name: 'Audio', extensions: ['wav', 'mp3', 'flac', 'aiff', 'ogg', 'm4a'] }],
     })
     return result.canceled ? null : result.filePaths[0]
   })
 
-  ipcMain.handle('fs:pickFolder', async () => {
+  handle('fs:pickFolder', async () => {
     const result = await dialog.showOpenDialog({
       properties: ['openDirectory', 'createDirectory'],
     })

electron/main/ipc/freesound.ts

@@ -1,6 +1,7 @@
-import { ipcMain, app, net } from 'electron'
+import { app, net } from 'electron'
 import path from 'node:path'
 import fs from 'node:fs'
+import { handle } from './handle'
 
 const BASE = 'https://freesound.org/apiv2'
 
@@ -14,7 +15,7 @@ function getApiKey(): string {
 }
 
 export function registerFreesoundHandlers(): void {
-  ipcMain.handle('freesound:search', async (_, query: string, page = 1, sort = 'score', filter = '') => {
+  handle('freesound:search', async (_, query: string, page = 1, sort = 'score', filter = '') => {
     const token = getApiKey()
     if (!token) throw new Error('No Freesound API key configured')
     const params: Record<string, string> = {
@@ -32,7 +33,7 @@ export function registerFreesoundHandlers(): void {
     return res.json()
   })
 
-  ipcMain.handle('freesound:download', async (_, _soundId: number, name: string, previewUrl: string) => {
+  handle('freesound:download', async (_, _soundId: number, name: string, previewUrl: string) => {
     const dir = path.join(app.getPath('userData'), 'staging')
     if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
     const outPath = path.join(dir, `${crypto.randomUUID()}.mp3`)

electron/main/ipc/handle.ts

@@ -0,0 +1,13 @@
+import { ipcMain, type IpcMainInvokeEvent } from 'electron'
+import type { ApiChannels } from '../../ipc-contract'
+
+// Register a main-process handler typed against the IPC contract. The channel name must be a real
+// `group:method` from `Api`, and the handler's args and return type are derived from that method's
+// signature, so renaming a channel or changing a payload in the contract fails to compile here.
+type ChannelHandler<K extends keyof ApiChannels> = ApiChannels[K] extends (...args: infer A) => infer R
+  ? (event: IpcMainInvokeEvent, ...args: A) => R | Awaited<R>
+  : never
+
+export function handle<K extends keyof ApiChannels>(channel: K, handler: ChannelHandler<K>): void {
+  ipcMain.handle(channel as string, handler as (event: IpcMainInvokeEvent, ...args: unknown[]) => unknown)
+}

electron/main/ipc/library.ts

@@ -1,6 +1,7 @@
-import { ipcMain, app } from 'electron'
+import { app } from 'electron'
 import path from 'node:path'
 import fs from 'node:fs'
+import { handle } from './handle'
 import * as samples from '../db/queries/samples'
 
 const AUDIO_EXTS = new Set(['wav', 'mp3', 'flac', 'aiff', 'aif', 'ogg', 'm4a'])
@@ -27,19 +28,19 @@ import { syncProjectChopsToLibrary } from '../services/materializeChops'
 import type { Sample, Project, ProjectRegion } from '../../types'
 
 export function registerLibraryHandlers(): void {
-  ipcMain.handle('library:getSamples', (_, filters?: { bpm?: number; key?: string; tags?: string[]; projectId?: string }) => {
+  handle('library:getSamples', (_, filters?: { bpm?: number; key?: string; tags?: string[]; projectId?: string }) => {
     return samples.getAllSamples(filters)
   })
 
-  ipcMain.handle('library:addSample', (_, data: { name: string; filePath: string; duration?: number }) => {
+  handle('library:addSample', (_, data: { name: string; filePath: string; duration?: number }) => {
     return samples.addSample(data)
   })
 
-  ipcMain.handle('library:updateSample', (_, id: string, data: Partial<Pick<Sample, 'name' | 'bpm' | 'musicalKey' | 'tags' | 'waveformData'>>) => {
+  handle('library:updateSample', (_, id: string, data: Partial<Pick<Sample, 'name' | 'bpm' | 'musicalKey' | 'tags' | 'waveformData'>>) => {
     samples.updateSample(id, data)
   })
 
-  ipcMain.handle('library:importFolder', (_, folderPath: string) => {
+  handle('library:importFolder', (_, folderPath: string) => {
     const existing = new Set(samples.getAllSamples().map((s) => s.filePath))
     const allFiles = scanAudioFiles(folderPath)
     const newFiles = allFiles.filter((f) => !existing.has(f))
@@ -50,14 +51,14 @@ export function registerLibraryHandlers(): void {
     return { imported: newFiles.length, skipped: allFiles.length - newFiles.length }
   })
 
-  ipcMain.handle('library:deleteSample', (_, id: string) => {
+  handle('library:deleteSample', (_, id: string) => {
     const filePath = samples.deleteSample(id)
     if (filePath) {
       try { fs.unlinkSync(filePath) } catch { /* file already gone, ignore */ }
     }
   })
 
-  ipcMain.handle('library:saveChops', async (_, params: {
+  handle('library:saveChops', async (_, params: {
     sourceFilePath: string
     regions: Array<{ start: number; end: number; name: string }>
     projectId?: string
@@ -90,40 +91,40 @@ export function registerLibraryHandlers(): void {
     return saved
   })
 
-  ipcMain.handle('projects:getAll', () => {
+  handle('projects:getAll', () => {
     return projects.getAllProjects()
   })
 
-  ipcMain.handle('projects:get', (_, id: string) => {
+  handle('projects:get', (_, id: string) => {
     return projects.getProject(id)
   })
 
-  ipcMain.handle('projects:save', async (_, data: { name: string; sourcePath: string | null; sourceName?: string | null; source?: 'local' | 'freesound'; regions: ProjectRegion[] }) => {
+  handle('projects:save', async (_, data: { name: string; sourcePath: string | null; sourceName?: string | null; source?: 'local' | 'freesound'; regions: ProjectRegion[] }) => {
     const project = projects.saveProject(data)
     await syncProjectChopsToLibrary(project.id)
     return project
   })
 
-  ipcMain.handle('projects:update', async (_, id: string, data: Partial<Pick<Project, 'name' | 'sourcePath' | 'regions'>>) => {
+  handle('projects:update', async (_, id: string, data: Partial<Pick<Project, 'name' | 'sourcePath' | 'regions'>>) => {
     projects.updateProject(id, data)
     if (data.regions !== undefined) await syncProjectChopsToLibrary(id)
   })
 
-  ipcMain.handle('projects:getChops', (_, projectId: string) => {
+  handle('projects:getChops', (_, projectId: string) => {
     return projects.getProjectChops(projectId)
   })
 
-  ipcMain.handle('projects:getAllChops', () => {
+  handle('projects:getAllChops', () => {
     return projects.getAllProjectChops()
   })
 
-  ipcMain.handle('projects:upsertChops', async (_, projectId: string, regions: ProjectRegion[]) => {
+  handle('projects:upsertChops', async (_, projectId: string, regions: ProjectRegion[]) => {
     const chops = projects.upsertProjectChops(projectId, regions)
     await syncProjectChopsToLibrary(projectId)
     return chops
   })
 
-  ipcMain.handle('projects:delete', (_, id: string) => {
+  handle('projects:delete', (_, id: string) => {
     // The library is a projection of projects, so a deleted project's materialized chops leave the
     // library too (rows + files). Pack slots that referenced them are left intact — packs are
     // independent snapshots.
@@ -137,21 +138,21 @@ export function registerLibraryHandlers(): void {
     projects.deleteProject(id)
   })
 
-  ipcMain.handle('projects:duplicate', async (_, id: string) => {
+  handle('projects:duplicate', async (_, id: string) => {
     const project = projects.duplicateProject(id)
     if (project) await syncProjectChopsToLibrary(project.id)
     return project
   })
 
-  ipcMain.handle('library:getPackSlotRefCount', (_, id: string) => {
+  handle('library:getPackSlotRefCount', (_, id: string) => {
     return samples.getSamplePackSlotRefCount(id)
   })
 
-  ipcMain.handle('library:getOrphans', () => {
+  handle('library:getOrphans', () => {
     return samples.getAllSamples().filter((s) => !fs.existsSync(s.filePath))
   })
 
-  ipcMain.handle('library:deleteOrphans', (_, ids: string[]) => {
+  handle('library:deleteOrphans', (_, ids: string[]) => {
     for (const id of ids) samples.deleteSample(id)
     return { deleted: ids.length }
   })