almost stable

CLAUDE.md

@@ -0,0 +1,69 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Svelte + TypeScript audio synthesis application that generates and manipulates sounds using various synthesis recipes (modes). Each recipe is a different flavour of audio synthesis, generating random audio samples that musicians can use in their compositions. Users can generate random sounds, mutate existing ones, visualize waveforms, and export audio as WAV files.
+
+## Build System
+
+- **Package manager**: pnpm (not npm or yarn)
+- **Bundler**: Vite (using rolldown-vite fork)
+- **Development**: `pnpm dev`
+- **Build**: `pnpm build`
+- **Preview**: `pnpm preview`
+- **Type checking**: `pnpm check` (runs svelte-check and tsc)
+
+## Architecture
+
+### Audio Pipeline
+
+The audio system follows a layered architecture:
+
+1. **SynthEngine interface** (`src/lib/audio/engines/SynthEngine.ts`): Abstract interface for synthesis engines
+   - Defines `generate()`, `randomParams()`, and `mutateParams()` methods
+   - All engines must generate stereo output: `[Float32Array, Float32Array]`
+   - Time-based parameters (envelopes, LFOs) stored as ratios (0-1) and scaled by duration during generation
+
+2. **Engines**
+
+3. **AudioService** (`src/lib/audio/services/AudioService.ts`): Web Audio API wrapper
+   - Manages AudioContext, gain node, and playback
+   - Provides playback position tracking via animation frames
+   - Fixed sample rate: 44100 Hz
+
+4. **WAVEncoder** (`src/lib/audio/utils/WAVEncoder.ts`): Audio export functionality
+
+### State Management
+
+- No external state library - uses Svelte 5's reactivity
+- Settings persistence via localStorage (`src/lib/utils/settings.ts`)
+- Volume and duration preferences saved/loaded automatically
+
+### UI Components
+
+- **App.svelte**: Main application container and control logic
+- **WaveformDisplay.svelte**: Visual waveform rendering with playback position indicator
+- **VUMeter.svelte**: Real-time level meter
+- Color generation: Random colors for each sound (`src/lib/utils/colors.ts`)
+
+## Key Patterns
+
+### Adding New Synthesis Engines
+
+**CRITICAL: Each engine must be completely self-contained in a single file.** Do not create separate utility files, helper classes, or subdirectories for engine components. All DSP code, envelopes, oscillators, and algorithm logic should be private methods within the engine class.
+
+1. Implement the `SynthEngine` interface in a single file under `src/lib/audio/engines/`
+2. Implement `getName()` to return the engine's display name
+3. Implement `getDescription()` to return a brief description of the engine
+4. Ensure `generate()` returns stereo output: `[Float32Array, Float32Array]`
+5. Time-based parameters should be ratios (0-1) scaled by duration
+6. Provide `randomParams()` and `mutateParams()` implementations
+7. Keep all helper functions, enums, and types in the same file
+8. **Register the engine** by adding it to the `engines` array in `src/lib/audio/engines/registry.ts`
+9. The mode buttons in the UI will automatically update to include your new engine
+
+### Duration Handling
+
+Duration is user-adjustable. All time-based synthesis parameters (attack, decay, release, LFO rates) must scale with duration. Store envelope timings as ratios of total duration, not absolute seconds.