@drop-ai/core 0.2.0 → 0.3.1

package/README.md

@@ -1,316 +1,734 @@
-# @drop-ai/core
-
-drop.ai DAW의 헤드리스 코어 라이브러리. 오디오 편집 도메인 로직, 커맨드 시스템, 오토메이션, 플러그인, MIDI 등 UI 독립적인 모든 기능을 포함한다.
-
-## 왜 분리했는가
-
-기존에는 `src/core/`에 있던 코어 로직이 Next.js 앱과 같은 디렉토리에 섞여 있었다. 문제점:
-
-- **Tone.js 커플링**: `AudioEngine`이 `ToneAudioProvider`를 직접 import하여 브라우저 없이 사용 불가
-- **Zustand 커플링**: `EditorHandler`, `defaultActions`, `dawQueryTool`이 `useDAWStore`를 직접 import
-- **테스트 격리 불가**: Node.js CLI나 headless 환경에서 코어 로직만 테스트하기 어려움
-- **재사용 불가**: 다른 프레임워크(Electron, React Native 등)에서 코어 로직 사용 불가
-
-분리 후:
-
-- `@drop-ai/core`는 **브라우저/프레임워크 의존성 제로**
-- Node.js CLI, 테스트, 다른 프레임워크에서 독립적으로 사용 가능
-- 향후 npm publish 가능
-
-## 아키텍처
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  Next.js App (src/)                                     │
-│  ┌──────────┐ ┌──────────────┐ ┌──────────────────────┐ │
-│  │Components│ │  Stores      │ │  App-level modules   │ │
-│  │(React)   │ │  (Zustand)   │ │  - ToneAudioProvider  │ │
-│  │          │ │  useDAWStore  │ │  - EditorHandler     │ │
-│  │          │ │              │ │  - defaultActions    │ │
-│  │          │ │              │ │  - dawQueryTool      │ │
-│  └────┬─────┘ └──────┬───────┘ └──────────┬───────────┘ │
-│       │              │                     │             │
-│       └──────────────┼─────────────────────┘             │
-│                      │                                   │
-├──────────────────────┼───────────────────────────────────┤
-│                      ▼                                   │
-│  @drop-ai/core (packages/core/)                          │
-│  ┌────────┐ ┌────────┐ ┌──────────┐ ┌────────────────┐  │
-│  │Domain  │ │Commands│ │Audio     │ │Automation      │  │
-│  │Session │ │Executor│ │Engine    │ │List, Curve,    │  │
-│  │Track   │ │History │ │Backend(I)│ │Mode            │  │
-│  │Region  │ │55 Impls│ │Exporter  │ └────────────────┘  │
-│  │Playlist│ │15 Hdlrs│ │Meter     │ ┌────────────────┐  │
-│  │Source  │ └────────┘ └──────────┘ │Plugins         │  │
-│  │Range   │ ┌────────┐ ┌──────────┐ │EQ, Reverb,     │  │
-│  │Marker  │ │Lib     │ │Processing│ │Compressor, ... │  │
-│  │MIDI    │ │Signal  │ │Gain, Pan │ └────────────────┘  │
-│  └────────┘ └────────┘ └──────────┘                     │
-└─────────────────────────────────────────────────────────┘
-```
-
-## 모듈 구조 (193 파일)
-
-### `domain/` — 도메인 모델 (42 파일)
-
-DAW의 핵심 데이터 구조. Ardour의 도메인 모델을 참고하여 설계됨.
-
-| 클래스 | 설명 |
-|--------|------|
-| `Session` | 프로젝트 루트. 트랙, 소스, 마커, 레인지, 템포맵 관리 |
-| `Track` | 오디오/MIDI/Bus/AUX 트랙. Route(IO + 프로세서 체인) 포함 |
-| `Region` | 타임라인 위의 오디오 구간. start, length, sourceStart, fades |
-| `Playlist` | 트랙 내 Region 컬렉션. 레이어, 크로스페이드 지원 |
-| `Source` | 오디오 파일 참조. URL, duration, sampleRate |
-| `Range` | 루프/펀치/선택 범위 (start, end) |
-| `Marker` | 타임라인 마커 (위치 + 이름) |
-| `MidiNote` / `MidiRegion` | MIDI 데이터 |
-| `SendBus` | 센드 버스 (pre/post fader) |
-| `GridSettings` | 그리드 타입, 스냅 모드 |
-| `TempoMap` | BPM 변경 이벤트 관리 |
-| `CrossfadeEngine` | 리전 겹침 시 자동 크로스페이드 계산 |
-| `TransportFSM` | 재생/정지/녹음 상태 머신 |
-| `MixerScene` | 믹서 스냅샷 저장/불러오기 |
-
-모든 도메인 객체는 `Signal` 기반 이벤트를 발행한다:
-```typescript
-session.trackAdded.connect((track: Track) => { ... });
-session.tempoChanged.connect((bpm: number) => { ... });
-track.muteChanged.connect((muted: boolean) => { ... });
-```
-
-### `commands/` — 커맨드 시스템 (62 파일)
-
-Undo/Redo 지원 커맨드 패턴 구현.
-
-- **`CommandExecutor`**: Zod 스키마 검증 → 핸들러 라우팅 → 실행. 싱글톤.
-- **`CommandHistory`**: Undo/Redo 스택 관리. depth 설정 가능.
-- **15개 핸들러**: Transport, Track, Region, Range, Automation, Export, IO, SendBus, Session, Marker, Midi, MixerScene, TrackGroup, History + 앱에서 등록하는 EditorHandler
-- **55개 커맨드 구현체**: AddTrack, MoveRegion, SplitAtPlayhead, SetTrackVolume 등
-
-```typescript
-// 커맨드 실행
-await CommandExecutor.getInstance().execute({
-    type: CommandType.ADD_TRACK,
-    payload: { name: 'Vocals', trackType: 'audio' }
-});
-
-// 앱에서 커스텀 핸들러 등록
-CommandExecutor.getInstance().registerHandler(new EditorHandler());
-```
-
-### `audio/` — 오디오 엔진 (10 파일)
-
-- **`AudioEngine`**: 세션과 백엔드를 연결하는 중앙 컨트롤러. 싱글톤.
-  - 트랜스포트 (play/stop/pause/seek)
-  - 녹음 (audio + MIDI, 펀치, 루프 레코딩)
-  - 미터링 (peak/RMS/LUFS)
-  - 프로세서 체인 동기화
-- **`AudioProvider`**: 인터페이스. 실제 오디오 I/O 추상화.
-  - 앱: `ToneAudioProvider` (Tone.js + Web Audio API)
-  - CLI: `HeadlessAudioProvider`
-  - 테스트: `MockAudioProvider`
-- **`OfflineExporter`**: WAV/MP3/OGG/FLAC 오프라인 렌더링
-- **`PlaylistEngine`**: 샘플 정확도 리전 렌더링 (AudioWorklet용)
-
-```typescript
-// 백엔드 주입 (Dependency Injection)
-const engine = AudioEngine.getInstance(new ToneAudioProvider());
-
-// 또는 headless 환경
-const engine = AudioEngine.getInstance(new HeadlessAudioProvider());
-```
-
-### `automation/` — 오토메이션 (6 파일)
-
-| 클래스 | 설명 |
-|--------|------|
-| `AutomationList` | 파라미터별 오토메이션 포인트 컬렉션 |
-| `AutomationCurve` | 보간 (linear, exponential, s-curve) |
-| `AutomationMode` | Read, Write, Touch, Latch |
-| `PointThinning` | 실시간 녹음 시 포인트 간소화 |
-| `ParameterDescriptor` | 파라미터 메타데이터 (min, max, default) |
-
-### `plugins/` — 플러그인 시스템 (16 파일)
-
-내장 오디오 플러그인:
-
-| 플러그인 | 설명 |
-|----------|------|
-| `ParametricEQPlugin` | 6밴드 파라메트릭 EQ |
-| `MultibandCompressorPlugin` | 멀티밴드 컴프레서 |
-| `ConvolutionReverbPlugin` | 컨볼루션 리버브 |
-| `SyncDelayPlugin` | BPM 동기 딜레이 |
-| `TapeSaturationPlugin` | 테이프 새추레이션 |
-| `DeEsserPlugin` | 디에서 |
-| `ExpanderPlugin` | 익스팬더/게이트 |
-| `PhaserPlugin` | 페이저 |
-| `TremoloPlugin` | 트레몰로 |
-| `VibratoPlugin` | 비브라토 |
-| `AutoPanPlugin` | 오토 팬 |
-
-`PluginManager`로 등록/생성:
-```typescript
-const manager = PluginManager.getInstance();
-const eq = manager.createPlugin('internal-parametric-eq');
-```
-
-### `processing/` — 신호 처리 체인 (8 파일)
-
-Route(트랙 당 프로세서 체인)를 구성하는 프로세서들:
-
-- `GainProcessor` (Fader / Trim)
-- `PanProcessor` (스테레오 패닝 + 폭 조절)
-- `PolarityProcessor` (위상 반전)
-- `SendProcessor` (Pre/Post fader 센드)
-- `MeterProcessor` (피크/RMS 미터링)
-- `PluginInsert` (플러그인 삽입 슬롯)
-
-### `lib/` — 유틸리티
-
-- **`Signal<T>`**: 타입 안전 이벤트 시스템. Qt의 Signal/Slot 패턴.
-
-```typescript
-const signal = new Signal<number>();
-const sub = signal.connect((value) => console.log(value));
-signal.emit(42);
-sub.dispose(); // 구독 해제
-```
-
-### `actions/` — 액션 레지스트리 (2 파일)
-
-키보드 단축키 ↔ 커맨드 매핑 시스템.
-
-- `ActionRegistry`: 액션 등록/조회/실행
-- `ActionDefinition`: id, label, category, defaultKey, commandFactory
-
-```typescript
-const registry = ActionRegistry.getInstance();
-registry.registerDefaults(defaultActions); // 앱에서 등록
-await registry.execute('transport.togglePlay');
-```
-
-### `preferences/` — 설정 (3 파일)
-
-- `Preferences`: 싱글톤. audioBufferSize, sampleRate, theme, gridSubdivision 등
-- `KeyBindings`: 커스텀 키 바인딩 오버라이드
-
-### `storage/` — 세션 저장 (3 파일)
-
-- `SessionStorage`: IndexedDB/localStorage 기반 세션 저장/불러오기
-- `AutoSave`: 주기적 자동 저장
-- `SessionTemplate`: 새 세션 템플릿
-
-### `ai/` — AI 에이전트 (5 파일)
-
-- `DAWAgent`: LLM 기반 DAW 제어 에이전트
-- `dawCommandTool`: AI가 커맨드를 실행하는 도구
-- `dawSystemPrompt`: DAW 컨텍스트 시스템 프롬프트
-
-## 앱에서의 사용법
-
-### 부트스트랩 (useDAWStore.init)
-
-```typescript
-import { AudioEngine } from '@drop-ai/core/audio/AudioEngine';
-import { CommandExecutor } from '@drop-ai/core/commands/CommandExecutor';
-import { ActionRegistry } from '@drop-ai/core/actions/ActionRegistry';
-import { ToneAudioProvider } from '../audio/ToneAudioProvider';
-import { EditorHandler } from '../app-commands/EditorHandler';
-import { defaultActions } from '../app-actions/defaultActions';
-
-// 1. 오디오 백엔드 주입
-AudioEngine.getInstance(new ToneAudioProvider());
-
-// 2. 앱 전용 커맨드 핸들러 등록
-CommandExecutor.getInstance().registerHandler(new EditorHandler());
-
-// 3. 기본 액션(키보드 단축키) 등록
-ActionRegistry.getInstance().registerDefaults(defaultActions);
-```
-
-### Import 패턴
-
-```typescript
-// barrel import (주요 타입)
-import { Session, Track, Region, AudioEngine } from '@drop-ai/core';
-
-// deep import (특정 모듈)
-import { AudioEngine } from '@drop-ai/core/audio/AudioEngine';
-import { CommandType } from '@drop-ai/core/commands/types';
-import { Signal } from '@drop-ai/core/lib/Signal';
-import { TempoMap } from '@drop-ai/core/domain/temporal/TempoMap';
-```
-
-## 앱 쪽에 남긴 파일 (7개)
-
-브라우저/스토어 의존성 때문에 코어에 포함할 수 없는 파일들:
-
-| 파일 | 위치 | 이유 |
-|------|------|------|
-| `ToneAudioProvider.ts` | `src/audio/` | Tone.js + browser AudioContext |
-| `ToneTrack.ts` | `src/audio/` | Tone.js import |
-| `TrackProcessor.ts` | `src/audio/worklets/` | AudioWorklet browser API |
-| `TimeStretchProcessor.ts` | `src/audio/` | soundtouchjs + OfflineAudioContext |
-| `defaultActions.ts` | `src/app-actions/` | useDAWStore import |
-| `EditorHandler.ts` | `src/app-commands/` | useDAWStore import |
-| `dawQueryTool.ts` | `src/app-ai/` | useDAWStore import |
-
-## 디커플링 요약
-
-| 변경 | Before | After |
-|------|--------|-------|
-| `AudioEngine` | `ToneAudioProvider` 하드코딩 | 백엔드 주입 필수 (DI) |
-| `CommandExecutor` | `EditorHandler` 내장 | `registerHandler()` API |
-| `ActionRegistry` | `defaultActions` 자동 로드 | `registerDefaults()` API |
-| `KeyBindings` / `Preferences` | `localStorage` 직접 접근 | `typeof localStorage` 가드 |
-| `ExportHandler` | `document.createElement` 직접 호출 | `typeof document` 가드 |
-| `ai/tools` | `dawQueryTool` 내장 | 앱에서 별도 관리 |
-
-## 설정 파일
-
-### pnpm-workspace.yaml
-```yaml
-packages:
-  - "packages/*"
-```
-
-### 루트 package.json (의존성)
-```json
-{
-  "dependencies": {
-    "@drop-ai/core": "workspace:*"
-  }
-}
-```
-
-### 루트 tsconfig.json (paths)
-```json
-{
-  "paths": {
-    "@/*": ["./*"],
-    "@drop-ai/core": ["./packages/core/src"],
-    "@drop-ai/core/*": ["./packages/core/src/*"]
-  }
-}
-```
-
-## 테스트
-
-```bash
-# 전체 단위 테스트 (308개)
-pnpm test
-
-# 코어 패키지 타입 체크
-cd packages/core && npx tsc --noEmit
-
-# 루트 프로젝트 타입 체크
-npx tsc --noEmit
-```
-
-## 향후 계획
-
-- [ ] `packages/core/` 빌드 파이프라인 (`tsc` → `dist/`)
-- [ ] npm publish (`private: false`)
-- [ ] Electron 앱에서 `@drop-ai/core` 재사용
-- [ ] 코어 전용 단위 테스트 (`packages/core/test/`)
+# drop-daw
+
+Headless DAW (Digital Audio Workstation) engine for TypeScript/JavaScript. Provides domain models, command system, audio engine, automation, plugins, and MIDI — all with zero browser or framework dependencies.
+
+```bash
+npm install drop-daw
+```
+
+## Features
+
+- **Headless** — No browser, no React, no framework required. Runs in Node.js, Electron, or any JS runtime.
+- **Command Pattern** — All mutations go through `CommandExecutor` with built-in Undo/Redo.
+- **Dependency Injection** — Bring your own audio backend via the `AudioProvider` interface.
+- **60+ Commands** — Transport, tracks, regions, automation, plugins, MIDI, markers, ranges, export.
+- **20+ Built-in Plugins** — EQ, compressor, reverb, delay, saturation, de-esser, and more.
+- **Signal-based Events** — Type-safe reactive event system (Qt Signal/Slot pattern).
+- **Serialization** — Full session save/load with JSON snapshots.
+- **TypeScript-first** — Complete type definitions included.
+
+---
+
+## Quick Start
+
+```typescript
+import {
+  AudioEngine,
+  Session,
+  Track,
+  TrackType,
+  CommandExecutor,
+  CommandType,
+} from 'drop-daw';
+
+// 1. Implement AudioProvider interface for your platform
+class MyAudioBackend implements AudioProvider {
+  // ... implement the interface methods
+}
+
+// 2. Initialize the engine with your backend
+const engine = AudioEngine.getInstance(new MyAudioBackend());
+
+// 3. Work with the session directly
+const track = engine.session.addTrack('Vocals', TrackType.AUDIO);
+
+// 4. Or use the command system (with undo/redo support)
+await CommandExecutor.getInstance().execute({
+  type: CommandType.ADD_TRACK,
+  payload: { name: 'Guitar', trackType: 'audio' },
+});
+```
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────┐
+│  Your App                                        │
+│  (React, Electron, Node.js CLI, etc.)            │
+│                                                  │
+│  ┌─────────────┐  ┌────────────────────────────┐ │
+│  │ UI Layer    │  │ AudioProvider (impl)        │ │
+│  │ (optional)  │  │ e.g. Web Audio, PortAudio  │ │
+│  └──────┬──────┘  └─────────────┬──────────────┘ │
+├─────────┼───────────────────────┼────────────────┤
+│         ▼                       ▼                │
+│  ┌─────────────┐  ┌────────────────────────────┐ │
+│  │ Command     │  │ AudioEngine                │ │
+│  │ Executor    │  │ (session + backend)        │ │
+│  └──────┬──────┘  └────────────────────────────┘ │
+│         ▼                                        │
+│  ┌───────────────────────────────────────┐       │
+│  │ Domain Layer                          │       │
+│  │ Session → Track → Playlist → Region   │       │
+│  │ Automation, Plugins, MIDI, Markers    │       │
+│  └───────────────────────────────────────┘       │
+│                                                  │
+│  drop-daw                                        │
+└──────────────────────────────────────────────────┘
+```
+
+---
+
+## Core Concepts
+
+### Session
+
+The root container for a DAW project. Manages tracks, sources, markers, ranges, tempo, and transport state.
+
+```typescript
+import { Session, TrackType } from 'drop-daw';
+
+const session = new Session('My Song', undefined, 44100);
+
+// Tracks
+const vocal = session.addTrack('Vocals', TrackType.AUDIO);
+const bass = session.addTrack('Bass', TrackType.AUDIO);
+const synth = session.addTrack('Synth', TrackType.MIDI);
+const reverb = session.addAuxTrack('Reverb Bus');
+
+// Transport
+session.setTempo(120);
+session.setTimeSignature(4, 4);
+
+// Markers
+session.addMarker('Chorus', 44100 * 30); // at 30 seconds
+
+// Ranges
+const loopRange = session.addRange('Loop A', 44100 * 10, 44100 * 20);
+session.setLoopRange(loopRange.id);
+session.setLoopEnabled(true);
+
+// Serialization
+const snapshot = session.toJSON();
+const restored = Session.fromJSON(snapshot);
+```
+
+### Track
+
+Represents an audio, MIDI, aux, bus, folder, or VCA track. Each track has a `Route` (signal chain) and a `Playlist` (region container).
+
+```typescript
+const track = session.addTrack('Lead Guitar', TrackType.AUDIO);
+
+track.setMute(false);
+track.setSolo(true);
+track.setArmed(true);
+track.setColor('#ff6b6b');
+track.setMonitorMode(MonitorMode.AUTO);
+
+// React to changes
+track.muteChanged.connect((muted) => console.log('Mute:', muted));
+track.soloChanged.connect((soloed) => console.log('Solo:', soloed));
+```
+
+**Track Types:**
+
+| Type | Description |
+|------|-------------|
+| `AUDIO` | Standard audio track with region playback |
+| `MIDI` | MIDI track with note data and virtual instruments |
+| `AUX` | Auxiliary bus for send effects (reverb, delay) |
+| `BUS` | Mix bus for subgroup routing |
+| `FOLDER` | Folder track for organizing child tracks |
+| `VCA` | VCA fader for linked level control |
+
+### Region
+
+A segment of audio on the timeline, referencing a `Source`.
+
+```typescript
+import { Region } from 'drop-daw';
+
+const region = new Region(
+  'region-1',    // id
+  'source-1',    // sourceId
+  0,             // start (frames)
+  44100 * 10,    // length (10 seconds at 44.1kHz)
+  0,             // sourceStart
+  'Vocal Take 1' // name
+);
+
+region.setFadeIn(4410);           // 100ms fade in
+region.setFadeOut(4410);          // 100ms fade out
+region.move(44100 * 5);           // move to 5 seconds
+region.resize(44100 * 8);         // resize to 8 seconds
+```
+
+### AudioEngine
+
+Central controller connecting the session to an audio backend. Uses the singleton pattern with dependency injection.
+
+```typescript
+import { AudioEngine, AudioProvider } from 'drop-daw';
+
+// Initialize with your backend implementation
+const engine = AudioEngine.getInstance(myBackend);
+await engine.initialize();
+
+// Transport
+await engine.start();
+engine.pause();
+engine.seek(10.5); // seek to 10.5 seconds
+engine.stop();
+
+// Metering
+const meter = engine.getMeterData('track-1');
+console.log('Peak:', meter.peak, 'RMS:', meter.rms);
+
+// Export
+await engine.exportAudio(engine.getExportConfig(), engine.getExportStatus());
+
+// Swap backend at runtime
+engine.setBackend(new DifferentBackend());
+```
+
+### AudioProvider Interface
+
+Implement this interface to connect drop-daw to any audio system.
+
+```typescript
+import { AudioProvider } from 'drop-daw';
+
+class WebAudioBackend implements AudioProvider {
+  async initialize(): Promise<void> { /* ... */ }
+
+  // Transport
+  start(): void { /* ... */ }
+  stop(): void { /* ... */ }
+  pause(): void { /* ... */ }
+  seek(time: number): void { /* ... */ }
+
+  // Track management
+  createTrack(trackId, name, inputId, outputId): void { /* ... */ }
+  deleteTrack(trackId): void { /* ... */ }
+
+  // Region scheduling
+  scheduleRegion(trackId, region): void { /* ... */ }
+  updateRegions(trackId, regions): void { /* ... */ }
+  removeRegion(trackId, regionId): void { /* ... */ }
+
+  // Metering
+  getMeterData(trackId): MeterData { /* ... */ }
+  getMasterMeterData(): MeterData { /* ... */ }
+
+  // ... and more (see full interface in source)
+}
+```
+
+**Included backend examples (in the drop.ai app, not in this package):**
+
+| Backend | Environment | Description |
+|---------|-------------|-------------|
+| `ToneAudioProvider` | Browser | Tone.js + Web Audio API |
+| `HeadlessAudioProvider` | Node.js | No-op backend for CLI/testing |
+| `MockAudioProvider` | Test | Mock backend for unit tests |
+
+---
+
+## Command System
+
+All state mutations can go through the command system, providing validation (via Zod), handler routing, and undo/redo support.
+
+### Executing Commands
+
+```typescript
+import { CommandExecutor, CommandType } from 'drop-daw';
+
+const executor = CommandExecutor.getInstance();
+
+// Add a track
+await executor.execute({
+  type: CommandType.ADD_TRACK,
+  payload: { name: 'Vocals', trackType: 'audio' },
+});
+
+// Set volume
+await executor.execute({
+  type: CommandType.SET_VOLUME,
+  payload: { trackId: 'track-1', volume: 0.75 },
+});
+
+// Split region at playhead
+await executor.execute({
+  type: CommandType.SPLIT_AT_PLAYHEAD,
+  payload: { trackId: 'track-1', frame: 44100 * 15 },
+});
+
+// Add a plugin
+await executor.execute({
+  type: CommandType.ADD_PLUGIN,
+  payload: { trackId: 'track-1', pluginId: 'internal-eq6' },
+});
+```
+
+### Undo / Redo
+
+```typescript
+const history = executor.history;
+
+await history.undo();
+await history.redo();
+await history.undoMultiple(3); // undo 3 steps
+
+console.log(history.canUndo);       // true
+console.log(history.nextUndoLabel);  // "Add Track"
+
+// Transaction: group multiple commands into one undo step
+history.beginTransaction('Move and resize');
+// ... execute multiple commands ...
+await history.commitTransaction();
+```
+
+### Registering Custom Handlers
+
+```typescript
+import { CommandHandler, CommandResult } from 'drop-daw';
+
+class MyCustomHandler implements CommandHandler {
+  readonly handledTypes = ['MY_CUSTOM_COMMAND'];
+
+  async execute(type: string, payload: any): Promise<CommandResult> {
+    // your logic here
+    return { success: true };
+  }
+}
+
+CommandExecutor.getInstance().registerHandler(new MyCustomHandler());
+```
+
+### Command Types
+
+**Transport:** `PLAY`, `PAUSE`, `STOP`, `SEEK`, `SET_TEMPO`, `SET_TIME_SIGNATURE`, `TOGGLE_METRONOME`, `START_RECORDING`, `STOP_RECORDING`
+
+**Tracks:** `ADD_TRACK`, `REMOVE_TRACK`, `SET_VOLUME`, `SET_PAN`, `MUTE_TRACK`, `SOLO_TRACK`, `ARM_TRACK`, `SET_TRACK_MONITOR`
+
+**Regions:** `ADD_REGION`, `REMOVE_REGION`, `MOVE_REGION`, `RESIZE_REGION`, `SPLIT_AT_PLAYHEAD`, `DUPLICATE_REGION`, `COPY_REGION`, `PASTE_REGION`, `MERGE_REGIONS`, `TRIM_REGION`, `SET_REGION_FADES`, `REVERSE_REGION`, `NORMALIZE_REGION`, `STRIP_SILENCE`, `TIME_STRETCH_REGION`, `LOCK_REGION`, `GROUP_REGIONS`, `UNGROUP_REGIONS`
+
+**Automation:** `ADD_AUTOMATION`, `MOVE_AUTOMATION_POINT`, `REMOVE_AUTOMATION_POINT`
+
+**Plugins:** `ADD_PLUGIN`, `REMOVE_PLUGIN`, `SET_PLUGIN_PARAMETER`
+
+**Ranges:** `ADD_RANGE`, `REMOVE_RANGE`, `SET_RANGE`, `SET_LOOP_RANGE`, `SET_PUNCH_RANGE`, `TOGGLE_LOOP`
+
+**Markers:** `ADD_MARKER`, `REMOVE_MARKER`, `MOVE_MARKER`
+
+**IO/Routing:** `CONNECT_IO`, `DISCONNECT_IO`, `ADD_SEND_BUS`, `REMOVE_SEND_BUS`, `SET_SEND_LEVEL`
+
+**Session:** `EXPORT`, `NEW_SESSION`, `LOAD_SESSION`, `SAVE_SESSION`, `SAVE_SNAPSHOT`
+
+**History:** `UNDO`, `REDO`, `SELECTION_UNDO`, `SELECTION_REDO`
+
+---
+
+## Plugins
+
+20+ built-in audio effect plugins, managed by `PluginManager`.
+
+```typescript
+import { PluginManager } from 'drop-daw';
+
+const manager = PluginManager.getInstance();
+
+// List all available plugins
+const plugins = manager.getAvailablePlugins();
+plugins.forEach(p => console.log(p.id, p.name));
+
+// Create a plugin instance
+const eq = manager.createPlugin('internal-eq6');
+eq.setParameter('band1-freq', 100);
+eq.setParameter('band1-gain', 3.0);
+
+// Get/set full state (presets)
+const state = eq.getState();
+eq.setState(state);
+
+// React to parameter changes
+eq.parameterChanged.connect(({ id, value }) => {
+  console.log(`${id} changed to ${value}`);
+});
+```
+
+### Available Plugins
+
+| ID | Name | Description |
+|----|------|-------------|
+| `internal-eq6` | Parametric EQ | 6-band parametric equalizer |
+| `internal-compressor` | Compressor | Dynamics compressor |
+| `internal-multiband-comp` | Multiband Compressor | Multi-band dynamics |
+| `internal-expander` | Expander | Expander/gate |
+| `internal-gate` | Gate | Noise gate |
+| `internal-deesser` | De-Esser | Sibilance reduction |
+| `internal-reverb` | Reverb | Algorithmic reverb |
+| `internal-convolver` | Convolution Reverb | IR-based reverb |
+| `internal-delay` | Delay | Simple delay |
+| `internal-sync-delay` | Sync Delay | BPM-synced delay |
+| `internal-chorus` | Chorus | Chorus effect |
+| `internal-phaser` | Phaser | Phaser effect |
+| `internal-tremolo` | Tremolo | Tremolo effect |
+| `internal-vibrato` | Vibrato | Vibrato effect |
+| `internal-autopan` | Auto Pan | Automatic panning |
+| `internal-distortion` | Distortion | Distortion/overdrive |
+| `internal-tape-sat` | Tape Saturation | Analog tape emulation |
+| `internal-filter` | Filter | Multi-mode filter |
+| `internal-eq3` | 3-Band EQ | Simple 3-band EQ |
+| `internal-gain` | Gain | Utility gain |
+
+---
+
+## Automation
+
+Per-parameter automation with multiple recording modes.
+
+```typescript
+import { AutomationList, AutomationMode } from 'drop-daw';
+
+const automation = new AutomationList();
+
+// Add points
+automation.addPoint(0, 0.5);       // value 0.5 at time 0
+automation.addPoint(2.0, 1.0);     // value 1.0 at time 2s
+automation.addPoint(4.0, 0.0);     // value 0.0 at time 4s
+
+// Read interpolated value
+const value = automation.getValueAt(1.0); // ~0.75 (linear interpolation)
+
+// Modes
+automation.mode = AutomationMode.READ;   // playback only
+automation.mode = AutomationMode.WRITE;  // overwrite
+automation.mode = AutomationMode.TOUCH;  // write while touching, snap back on release
+automation.mode = AutomationMode.LATCH;  // write while touching, hold last value
+
+// Range operations
+const copied = automation.copy(1.0, 3.0);
+automation.paste(copied, 5.0);
+automation.eraseRange(1.0, 3.0);
+```
+
+---
+
+## Signal (Event System)
+
+Type-safe event emitter inspired by Qt's Signal/Slot pattern. Used throughout the domain layer.
+
+```typescript
+import { Signal } from 'drop-daw';
+
+const signal = new Signal<number>();
+
+// Subscribe
+const sub = signal.connect((value) => {
+  console.log('Received:', value);
+});
+
+// Emit
+signal.emit(42); // logs "Received: 42"
+
+// Unsubscribe
+sub.dispose();
+
+// Or disconnect by reference
+const handler = (v: number) => console.log(v);
+signal.connect(handler);
+signal.disconnect(handler);
+
+// Clear all listeners
+signal.clear();
+```
+
+### Common Signals
+
+```typescript
+// Session
+session.trackAdded.connect((track) => { /* ... */ });
+session.trackRemoved.connect((trackId) => { /* ... */ });
+session.tempoChanged.connect((bpm) => { /* ... */ });
+session.playingChanged.connect((isPlaying) => { /* ... */ });
+session.selectionChanged.connect((selectedIds) => { /* ... */ });
+session.markerAdded.connect((marker) => { /* ... */ });
+
+// Track
+track.muteChanged.connect((muted) => { /* ... */ });
+track.soloChanged.connect((soloed) => { /* ... */ });
+track.armChanged.connect((armed) => { /* ... */ });
+
+// CommandExecutor
+executor.commandExecuted.connect(({ type, payload }) => { /* ... */ });
+
+// CommandHistory
+history.historyChanged.connect(() => { /* ... */ });
+```
+
+---
+
+## Actions & Key Bindings
+
+Map keyboard shortcuts to commands.
+
+```typescript
+import { ActionRegistry, ActionCategory } from 'drop-daw';
+
+const registry = ActionRegistry.getInstance();
+
+// Register default actions (typically done at app bootstrap)
+registry.registerDefaults([
+  {
+    id: 'transport.play',
+    label: 'Play/Pause',
+    category: ActionCategory.TRANSPORT,
+    defaultKey: 'Space',
+    commandFactory: () => ({ type: CommandType.PLAY, payload: {} }),
+  },
+  {
+    id: 'edit.undo',
+    label: 'Undo',
+    category: ActionCategory.EDIT,
+    defaultKey: 'Ctrl+Z',
+    commandFactory: () => ({ type: CommandType.UNDO, payload: {} }),
+  },
+]);
+
+// Execute by action ID
+await registry.execute('transport.play');
+
+// Query
+const actions = registry.getActionsByCategory();
+const key = registry.getEffectiveKey('transport.play'); // 'Space'
+```
+
+### Custom Key Bindings
+
+```typescript
+import { KeyBindings } from 'drop-daw';
+
+const bindings = KeyBindings.getInstance();
+
+bindings.setBinding('transport.play', 'Enter');
+bindings.getBinding('transport.play'); // 'Enter'
+bindings.removeBinding('transport.play'); // back to default
+bindings.resetToDefaults();
+```
+
+---
+
+## Preferences
+
+Persistent settings with defaults.
+
+```typescript
+import { Preferences } from 'drop-daw';
+
+const prefs = Preferences.getInstance();
+
+prefs.set('sampleRate', 48000);
+prefs.set('audioBufferSize', 256);
+prefs.set('theme', 'dark');
+prefs.set('snapToGrid', true);
+prefs.set('historyDepth', 100);
+
+const sr = prefs.get('sampleRate'); // 48000
+
+// React to changes
+prefs.preferenceChanged.connect(() => {
+  console.log('Settings updated');
+});
+
+// Reset
+prefs.resetToDefaults();
+```
+
+**Available Keys:** `audioBufferSize`, `sampleRate`, `theme`, `autoSaveInterval`, `snapToGrid`, `gridSubdivision`, `meterType`, `showMinimap`, `followPlayhead`, `countInBars`, `historyDepth`, `saveHistory`, `saveHistoryDepth`
+
+---
+
+## Storage
+
+Session persistence via IndexedDB (browser) or localStorage fallback.
+
+```typescript
+import { SessionStorage } from 'drop-daw';
+
+const storage = SessionStorage.getInstance();
+
+// Save
+await storage.saveSession(session);
+
+// List
+const sessions = await storage.listSessions();
+// [{ id: '...', name: 'My Song', modified: Date }]
+
+// Load
+const snapshot = await storage.loadSession(sessions[0].id);
+const restored = Session.fromJSON(snapshot);
+
+// Snapshots (named save points)
+const snapId = await storage.saveSnapshot(session.id, 'Before mixing', session.toJSON());
+const snap = await storage.loadSnapshot(snapId);
+
+// Delete
+await storage.deleteSession(session.id);
+```
+
+---
+
+## Processing Chain
+
+Each track has a `Route` containing an ordered chain of processors.
+
+```typescript
+import {
+  GainProcessor,
+  PanProcessor,
+  PluginInsert,
+  SendProcessor,
+  MeterProcessor,
+} from 'drop-daw';
+
+// Processor types available in the chain:
+// GainProcessor  — Fader / Trim level control
+// PanProcessor   — Stereo panning and width
+// PluginInsert   — Plugin effect slot
+// SendProcessor  — Pre/Post fader send to aux bus
+// MeterProcessor — Peak/RMS metering
+```
+
+---
+
+## Usage Examples
+
+### Node.js CLI
+
+```typescript
+import { AudioEngine, Session, CommandExecutor, CommandType } from 'drop-daw';
+
+// Headless backend (no audio output)
+class HeadlessBackend implements AudioProvider {
+  async initialize() {}
+  start() {}
+  stop() {}
+  // ... no-op implementations
+}
+
+const engine = AudioEngine.getInstance(new HeadlessBackend());
+const session = engine.session;
+
+session.addTrack('Track 1', TrackType.AUDIO);
+console.log('Tracks:', session.tracks.map(t => t.name));
+
+const snapshot = session.toJSON();
+// Save to file, process offline, etc.
+```
+
+### Electron App
+
+```typescript
+import { AudioEngine, AudioProvider } from 'drop-daw';
+
+class ElectronAudioBackend implements AudioProvider {
+  // Use PortAudio or native audio APIs
+  // ...
+}
+
+const engine = AudioEngine.getInstance(new ElectronAudioBackend());
+await engine.initialize();
+```
+
+### React Integration
+
+```typescript
+import { useEffect, useState } from 'react';
+import { AudioEngine, Session } from 'drop-daw';
+
+function useDAWEngine(backend: AudioProvider) {
+  const [engine] = useState(() => AudioEngine.getInstance(backend));
+
+  useEffect(() => {
+    const sub = engine.session.tempoChanged.connect((bpm) => {
+      // update React state
+    });
+    return () => sub.dispose();
+  }, [engine]);
+
+  return engine;
+}
+```
+
+---
+
+## API Reference
+
+### Singletons
+
+| Class | Access | Description |
+|-------|--------|-------------|
+| `AudioEngine` | `getInstance(backend?)` | Audio engine with session and transport |
+| `CommandExecutor` | `getInstance()` | Command dispatch with validation |
+| `PluginManager` | `getInstance()` | Plugin factory |
+| `ActionRegistry` | `getInstance()` | Keyboard shortcut ↔ command mapping |
+| `Preferences` | `getInstance()` | User settings |
+| `KeyBindings` | `getInstance()` | Custom key binding overrides |
+| `SessionStorage` | `getInstance()` | Session persistence |
+
+### Domain Models
+
+| Class | Description |
+|-------|-------------|
+| `Session` | Project root — tracks, sources, markers, ranges, tempo |
+| `Track` | Audio/MIDI/AUX/BUS/FOLDER/VCA track |
+| `Region` | Audio segment on the timeline |
+| `Playlist` | Region collection within a track |
+| `Source` | Audio file reference (URL, duration, sampleRate) |
+| `Range` | Loop/punch/selection range |
+| `Marker` | Timeline marker (position + name) |
+| `MidiNote` | Single MIDI note event |
+| `MidiRegion` | MIDI note collection on the timeline |
+| `SendBus` | Pre/post fader send bus |
+| `Route` | Signal chain (input → processors → output) |
+| `TempoMap` | BPM change events over time |
+| `GridSettings` | Grid type and snap mode |
+| `CrossfadeEngine` | Automatic crossfade calculation |
+| `MixerScene` | Mixer snapshot save/restore |
+| `TrackGroup` | Track grouping for linked control |
+
+### Type Definitions
+
+```typescript
+type FrameCount = number    // sample frame position
+type SampleRate = number    // e.g. 44100, 48000, 96000
+type Gain = number          // 0.0 to 1.0+
+type DB = number            // decibels
+
+type TrackId = string
+type RegionId = string
+type SourceId = string
+type RangeId = string
+type ProcessorId = string
+type RouteId = string
+```
+
+---
+
+## Dependencies
+
+| Package | Type | Description |
+|---------|------|-------------|
+| `zod` | runtime | Command payload validation |
+| `lamejs` | peer (optional) | MP3 export support |
+| `soundtouchjs` | peer (optional) | Time-stretch / pitch-shift |
+
+---
+
+## License
+
+MIT