@dawcore/components 0.0.23 → 0.0.24

package/README.md

@@ -10,11 +10,16 @@ Framework-agnostic Web Components for multi-track audio editing. Drop `<daw-edit
 - **Drag interactions** — Move clips, trim boundaries, split at playhead
 - **Keyboard shortcuts** — Play/pause, split, undo/redo via `<daw-keyboard-shortcuts>`
 - **Undo/redo** — Full transaction-based undo with Cmd/Ctrl+Z and Cmd/Ctrl+Shift+Z
-- **File drop** — Drag audio files onto the editor to add tracks
+- **File drop** — Drag audio files onto the editor to add tracks (enable with the `file-drop` attribute)
 - **Recording** — Live mic recording with waveform preview, pause/resume, cancelable clip creation
 - **Pre-computed peaks** — Instant waveform rendering from `.dat` files before audio decodes
-- **MIDI tracks** — Programmatic MIDI clips render as piano-roll via `<daw-piano-roll>`. Playback via Tone.js adapter (native MIDI synth deferred). See [MIDI Tracks](#midi-tracks).
+- **MIDI tracks** — Declarative or programmatic MIDI clips render as piano-roll. Playback via the Tone.js adapter. See [MIDI Tracks](#midi-tracks).
+- **MIDI file loading** — `editor.loadMidi(urlOrFile)` parses a `.mid` file into piano-roll tracks via the optional `@dawcore/midi` peer
+- **Spectrogram rendering** — `<daw-track render-mode="spectrogram">` renders FFT spectrograms via `@dawcore/spectrogram`
 - **Track controls** — Volume, pan, mute, solo per track via `<daw-track-controls>`
+- **Effects chains** — Per-track and master effect chains with built-in `native-*` effects, WAM 2.0 plugins via `@dawcore/wam`, and in-browser-compiled Faust DSP via `@dawcore/faust`. See [Effects](#effects).
+- **Effect GUIs and persistence** — Mount plugin GUIs into your own panels; snapshot and restore whole chains. See [Effect GUIs](#effect-guis) and [Effects Persistence](#effects-persistence).
+- **Offline export** — `editor.exportAudio()` renders the session (clips, mix, all effect chains) to an `AudioBuffer`. See [Offline Export](#offline-export).
 - **Transport access** — Tempo, metronome, count-in, meter, effects via `@dawcore/transport`
 - **CSS theming** — Dark mode by default, fully customizable via CSS custom properties
 - **Native Web Audio** — Uses `@dawcore/transport` for playback scheduling. No Tone.js dependency.
@@ -25,21 +30,27 @@ Framework-agnostic Web Components for multi-track audio editing. Drop `<daw-edit
 npm install @dawcore/components
 ```
 
-Peer dependencies:
+Required peer dependencies:
+
 ```bash
 npm install @waveform-playlist/core @waveform-playlist/engine
 ```
 
 Audio backend (choose one — see [Choosing an Audio Backend](#choosing-an-audio-backend)):
+
 ```bash
 npm install @dawcore/transport          # Native Web Audio (recommended)
 # or
 npm install @waveform-playlist/playout tone  # Tone.js
 ```
 
-Optional (for recording):
+Optional peer dependencies — each is dynamic-imported on first use, so you only install (and ship) what you use:
+
 ```bash
-npm install @waveform-playlist/worklets
+npm install @waveform-playlist/worklets  # recording
+npm install @dawcore/midi                # editor.loadMidi()
+npm install @dawcore/wam                 # WAM 2.0 plugins (addWamPlugin) + generic effect GUIs
+npm install @dawcore/faust @dawcore/wam  # in-browser Faust compilation (addFaustEffect)
 ```
 
 ## Quick Start
@@ -93,7 +104,7 @@ adapter.transport.setCountIn(true);
 
 ### Tone.js (effects, MIDI synths)
 
-Uses Tone.js for audio processing. Single tempo/meter only. **Required for MIDI playback** — the native adapter has no MIDI synth yet, so MIDI clips render as piano-roll but are silent.
+Uses Tone.js for audio processing. Single tempo/meter only. **Required for MIDI playback** — the native adapter has no MIDI synth, so MIDI clips render as piano-roll but play silently on it.
 
 ```bash
 npm install @waveform-playlist/playout tone
@@ -128,7 +139,7 @@ For multiple clips per track with independent positioning:
 
 ## MIDI Tracks
 
-Programmatic MIDI clips render as piano-roll. Playback requires the Tone.js adapter (the native adapter has no MIDI synth yet). Use the `editor.addTrack({ midi })` sugar for the simplest path:
+Programmatic MIDI clips render as piano-roll. Playback requires the Tone.js adapter (the native adapter has no MIDI synth). Use the `editor.addTrack({ midi })` sugar for the simplest path:
 
 ```javascript
 import { createToneAdapter } from '@waveform-playlist/playout';
@@ -164,7 +175,7 @@ This expands to a `<daw-track render-mode="piano-roll">` containing a `<daw-clip
 </script>
 ```
 
-A clip is treated as MIDI iff `clip.midiNotes != null`. MIDI clips skip audio fetch + decode + peak generation. Trim handles and split-at-playhead are inert on MIDI clips for now (note slicing is a follow-up). Move drag works.
+A clip is treated as MIDI iff `clip.midiNotes != null`. MIDI clips skip audio fetch + decode + peak generation. Move drag works on MIDI clips; trim handles and split-at-playhead are inert on them.
 
 **Theming:** the piano-roll honors `--daw-piano-roll-note-color` (default `#2a7070`), `--daw-piano-roll-selected-note-color` (default `#3d9e9e`), and `--daw-piano-roll-background` (default `#1a1a2e`).
 
@@ -184,6 +195,24 @@ For instant waveform rendering before audio finishes decoding:
 
 The `.dat` file renders the waveform immediately. Audio decodes in the background for playback.
 
+## Effects Persistence
+
+`getEffectsState()` / `setEffectsState(entries)` on `<daw-editor>` (master chain) and `<daw-track>` snapshot and restore effect chains. Persist the returned array however you like (localStorage, server, project file):
+
+```js
+const saved = await editor.getEffectsState();
+// [
+//   { kind: 'native', type: 'native-delay', params: {...}, bypassed: false },
+//   { kind: 'wam', url: 'https://…/index.js', bypassed: false, state: {…} },
+// ]
+localStorage.setItem('master-fx', JSON.stringify(saved));
+
+// later / next session
+await editor.setEffectsState(JSON.parse(localStorage.getItem('master-fx')));
+```
+
+WAM entries carry the plugin's own `getState()` snapshot, reapplied on restore. Faust entries (added with `addFaustEffect`) persist their DSP source instead of a URL — `{ kind: 'wam', faustDsp, faustName, bypassed, state }` — and are recompiled in the browser on restore. If a saved plugin URL is unreachable (or a saved Faust source no longer compiles), the restore **continues**: the entry becomes a bypassed passthrough placeholder at its saved position (a `daw-effect-error` event fires with `{effectId, url?, source?, message}`), and its saved state is retained so re-serializing round-trips it for a later retry.
+
 ## Transport Access
 
 Transport-specific APIs are on the `NativePlayoutAdapter` reference:
@@ -202,6 +231,88 @@ adapter.transport.on('countIn', ({ beat, totalBeats }) => {
 adapter.transport.connectTrackOutput('track-id', reverbNode);
 ```
 
+## Effects
+
+Per-track and master effect chains (requires `@dawcore/transport` >= 0.0.13). `<daw-track>` owns its track chain; `<daw-editor>` owns the master chain — same API on both:
+
+```javascript
+const track = document.querySelector('daw-track');
+
+// Built-in native-* effects: native-gain, native-filter, native-compressor,
+// native-stereo-panner, native-delay
+const filterId = track.addEffect('native-filter', { frequency: 800 });
+const compressorId = editor.addEffect('native-compressor'); // master chain
+
+track.setEffectParams(filterId, { frequency: 2000 });  // live, during playback
+track.setEffectBypassed(filterId, true);
+track.moveEffect(filterId, 1);
+track.removeEffect(filterId);
+console.log(track.effects);  // [{ id, kind, type, params, bypassed }, ...]
+```
+
+Effect events dispatch from the owning element and bubble to the editor:
+
+```javascript
+editor.addEventListener('daw-effect-add', (e) => console.log(e.detail));
+// also: daw-effect-remove, daw-effect-change, daw-effect-bypass, daw-effect-reorder
+```
+
+Register custom effects with `registerEffect(type, definition)`; inspect built-ins with `getEffectDefinitions()` (exports from `@dawcore/components`).
+
+### WAM Plugins
+
+[Web Audio Modules 2.0](https://www.webaudiomodules.com/) plugins load into the same chains via the optional `@dawcore/wam` peer (`npm install @dawcore/wam`):
+
+```javascript
+const wamId = await track.addWamPlugin('https://www.webaudiomodules.com/community/plugins/burns-audio/delay/index.js');
+// WAM entries are ordinary chain entries — bypass/move/remove/events all work
+```
+
+See `examples/dawcore-native/effects.html` for a native-effects demo and `examples/dawcore-wam/` (`pnpm example:dawcore-wam`) for the end-to-end WAM demo: URL paste, community-library picker (`fetchWamLibrary`), GUIs, persistence with reload, and WAV export.
+
+### Faust Effects (compiled in the browser)
+
+Write custom DSP in [Faust](https://faust.grame.fr/) and hear it instantly — `addFaustEffect(dspCode, options?)` compiles the source **in the browser** via the optional `@dawcore/faust` peer (`npm install @dawcore/faust @dawcore/wam`) and adds the result to the chain as an ordinary WAM entry:
+
+```javascript
+// Track chains are stereo — duplicate mono filters across both channels.
+const effectId = await track.addFaustEffect(
+  `import("stdfaust.lib");
+   cutoff = hslider("cutoff", 1000, 20, 20000, 1);
+   process = fi.lowpass(2, cutoff), fi.lowpass(2, cutoff);`,
+  { name: 'My Lowpass' }
+);
+// Every hslider/vslider/checkbox becomes a WAM parameter + a GUI control.
+```
+
+The Faust compiler (~2.5 MB gzipped WASM) loads lazily on the first call — consumers who never compile Faust load zero compiler bytes. Compile errors keep Faust's line/column diagnostics and leave the chain untouched. Faust entries persist as their DSP source (`{ kind: 'wam', faustDsp, faustName, state }` — no URL) and are **recompiled** on `setEffectsState` restore and offline export. See the "Faust (compile in browser)" section of `examples/dawcore-wam/`.
+
+### Effect GUIs
+
+`openEffectGui(effectId, container)` / `closeEffectGui(effectId)` on both elements mount an effect's GUI into a container **you** provide (your own panel, drawer, floating window — dawcore ships no plugin-window UI):
+
+```javascript
+const panel = document.querySelector('#fx-panel');
+
+const guiEl = await track.openEffectGui(wamId, panel); // WAM plugins mount their own GUI
+track.closeEffectGui(wamId); // hides — audio keeps processing, element stays cached
+await track.openEffectGui(wamId, panel); // instant reopen, same element
+```
+
+The GUI is created lazily on first open and only destroyed (`destroyGui`) when the effect — or its track — is removed from the chain. Plugins without a GUI, and `native-*` effects, get a generic parameter panel (labeled sliders from the plugin's `getParameterInfo()` or the registry's params metadata) rendered by `@dawcore/wam`; slider edits apply live and dispatch `daw-effect-change` like any other parameter edit.
+
+### Offline Export
+
+`editor.exportAudio(options?)` renders the whole session — clips, volume/pan, mute/solo, per-track and master effect chains — on an `OfflineAudioContext` and resolves to an `AudioBuffer` (encode it to WAV/FLAC however you like):
+
+```javascript
+const buffer = await editor.exportAudio();
+// options: { sampleRate?, startTime?, duration?, channels? }
+const intro = await editor.exportAudio({ startTime: 0, duration: 8, channels: 2 });
+```
+
+Chains rebuild from their persisted form: `native-*` effects via the registry, WAM plugins re-instantiated on the offline context with their saved state (worklets are bound to one context), and Faust entries recompiled from their persisted DSP source. Bypass behavior matches live playback; all offline plugin instances are destroyed after rendering.
+
 ## Programmatic File Loading
 
 ```javascript
@@ -292,26 +403,39 @@ Core orchestrator. Attributes:
 
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `samples-per-pixel` | number | `1024` | Zoom level |
-| `sample-rate` | number | `48000` | AudioContext sample rate hint |
-| `wave-height` | number | `100` | Track waveform height in pixels |
+| `samples-per-pixel` | number | `1024` | Zoom level (clamped to the pre-computed peaks floor when one is active) |
+| `wave-height` | number | `128` | Track waveform height in pixels |
 | `timescale` | boolean | `false` | Show time ruler |
 | `clip-headers` | boolean | `false` | Show clip name headers |
+| `clip-header-height` | number | `20` | Clip header height in pixels |
 | `interactive-clips` | boolean | `false` | Enable drag/trim/split |
+| `file-drop` | boolean | `false` | Accept audio files dropped onto the editor |
 | `mono` | boolean | `false` | Merge stereo to mono display |
-| `eager-resume` | boolean | `false` | Resume AudioContext on first user gesture |
+| `bar-width` / `bar-gap` | number | `1` / `0` | Waveform bar rendering style |
+| `indefinite-playback` | boolean | `false` | Keep ruler/timeline filling the viewport with no clips |
+| `scale-mode` | string | `'temporal'` | `'temporal'` (seconds) or `'beats'` (tick-linear grid) |
+| `ticks-per-pixel` | number | `24` | Zoom level in beats mode |
+| `snap-to` | string | `'off'` | Grid snapping in beats mode (`'bar'`, `'beat'`, `'1/2'`…`'1/16'`, `'off'`) |
+| `eager-resume` | string | — | Resume AudioContext on first gesture; bare attribute targets the editor, or pass `"document"` / a CSS selector |
+
+JS properties: `adapter` (required `PlayoutAdapter`), `recordingStream`, `bpm`, `ppqn`, `timeSignature`, `meterEntries`, `secondsToTicks` / `ticksToSeconds` (variable-tempo callbacks), `spectrogramConfig`, `spectrogramColorMap`. Read-only: `engine`, `audioContext` (from the adapter), `tracks`, `selection`, `selectedTrackId`, `currentTime`, `canUndo` / `canRedo`, `isRecording`.
 
-JS properties: `audioContext`, `recordingStream`, `engine`.
+Methods:
 
-Methods: `loadFiles(fileList)`, `splitAtPlayhead()`.
+- Playback: `play(startTime?)`, `pause()`, `stop()`, `togglePlayPause()`, `seekTo(time)`
+- Loading: `loadFiles(files)`, `loadMidi(urlOrFile, options?)`, `ready()`
+- Tracks & clips: `addTrack(config)`, `removeTrack(id)`, `updateTrack(id, partial)`, `addClip(trackId, config)`, `removeClip(trackId, clipId)`, `updateClip(trackId, clipId, partial)`
+- Editing: `splitAtPlayhead()`, `undo()`, `redo()`, `setSelection(start, end)`
+- Recording: `startRecording(stream?, options?)`, `stopRecording()`, `pauseRecording()`, `resumeRecording()`, `togglePauseRecording()`
+- Effects & export: the master-chain effects API (see [Effects](#effects)), `getEffectsState()` / `setEffectsState(entries)`, `openEffectGui()` / `closeEffectGui()`, `exportAudio(options?)`
 
 ### `<daw-track>`
 
-Declarative track data. Attributes: `src`, `name`, `volume`, `pan`, `muted`, `soloed`, `mono`, `render-mode` (`'waveform' | 'piano-roll'`, default `'waveform'`).
+Declarative track data. Attributes: `src`, `name`, `volume`, `pan`, `muted`, `soloed`, `render-mode` (`'waveform' | 'piano-roll' | 'spectrogram'`, default `'waveform'`). JS property: `spectrogramConfig` (per-track spectrogram override). Also exposes the per-track effects API (see [Effects](#effects)).
 
 ### `<daw-clip>`
 
-Declarative clip data. Attributes: `src`, `peaks-src`, `start`, `duration`, `offset`, `gain`, `midi-channel`, `midi-program`. JS-only property: `midiNotes: MidiNoteData[] | null` (note arrays are too large for attributes).
+Declarative clip data. Attributes: `src`, `peaks-src`, `start`, `duration`, `offset`, `gain`, `name`, `color`, `midi-channel`, `midi-program`. JS-only property: `midiNotes: MidiNoteData[] | null` (note arrays are too large for attributes).
 
 ### `<daw-piano-roll>`
 
@@ -356,12 +480,20 @@ editor.addEventListener('daw-recording-complete', (e) => {
   console.log(e.detail.audioBuffer);
 });
 
+// Effects (track events bubble up to the editor)
+editor.addEventListener('daw-effect-add', (e) => console.log(e.detail));
+editor.addEventListener('daw-effect-change', (e) => console.log(e.detail));
+// also: daw-effect-remove, daw-effect-bypass, daw-effect-reorder
+
 // Errors
 editor.addEventListener('daw-track-error', (e) => console.error(e.detail));
 editor.addEventListener('daw-error', (e) => console.error(e.detail));
 editor.addEventListener('daw-files-load-error', (e) => console.error(e.detail));
+editor.addEventListener('daw-effect-error', (e) => console.error(e.detail));
 ```
 
+All events and their `detail` payloads are typed in the exported `DawEventMap`.
+
 ## Custom AudioContext
 
 Pass a custom `AudioContext` via the adapter:
@@ -374,6 +506,13 @@ editor.adapter = adapter;
 
 Set the adapter before tracks load. The provided context is used for decoding, playback, and recording.
 
+## Examples & Documentation
+
+- [`examples/dawcore-native/`](https://github.com/naomiaro/waveform-playlist/tree/main/examples/dawcore-native) — native transport: basics, multi-clip, metronome, beats grid, beat maps, effects, spectrogram, recording (`pnpm example:dawcore-native`)
+- [`examples/dawcore-tone/`](https://github.com/naomiaro/waveform-playlist/tree/main/examples/dawcore-tone) — Tone.js adapter: MIDI, SoundFont playback (`pnpm example:dawcore-tone`)
+- [`examples/dawcore-wam/`](https://github.com/naomiaro/waveform-playlist/tree/main/examples/dawcore-wam) — WAM plugins end-to-end + in-browser Faust compilation (`pnpm example:dawcore-wam`)
+- Guides: [naomiaro.github.io/waveform-playlist](https://naomiaro.github.io/waveform-playlist/docs/web-components/getting-started)
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -46,6 +46,87 @@ declare global {
     }
 }
 
+/** Range/display metadata for one effect parameter. */
+interface EffectParamDef {
+    min: number;
+    max: number;
+    step?: number;
+    /** 's', 'ms', 'Hz', 'dB', '%' … */
+    unit?: string;
+}
+/**
+ * A live, wired effect. `input`/`output` are the chain attachment points
+ * (the same node for single-node effects). `applyParams` updates AudioParams
+ * in place — the chain never rebuilds for parameter changes.
+ */
+interface EffectInstance {
+    input: AudioNode;
+    output: AudioNode;
+    applyParams: (params: Record<string, number>) => void;
+    dispose?: () => void;
+    /** Serializable snapshot of plugin-internal state (WAM getState). */
+    getState?: () => Promise<unknown>;
+    /** Builds the plugin's own GUI element (WAM createGui). GUI lifecycle is
+     *  independent of audio — hiding/destroying a GUI never stops processing. */
+    createGui?: () => Promise<HTMLElement>;
+    /** Releases a GUI element previously built by `createGui` (WAM destroyGui). */
+    destroyGui?: (gui: HTMLElement) => void;
+    /** Parameter metadata for the generic fallback panel (WAM getParameterInfo). */
+    getParameterInfo?: () => Promise<unknown>;
+}
+/** A registered effect type. `create` must work on any BaseAudioContext so
+ *  the same definitions serve offline rendering. */
+interface EffectDefinition {
+    label: string;
+    category: string;
+    defaults: Record<string, number>;
+    params: Record<string, EffectParamDef>;
+    /** Name of the wet/dry param, when the effect has one. Bypass zeroes it
+     *  (storing the original); effects without one are bypassed by
+     *  disconnection. */
+    wetParam?: string;
+    create: (audioContext: BaseAudioContext, params: Record<string, number>) => EffectInstance;
+}
+/** Public, serializable view of one chain entry. */
+interface EffectState {
+    id: string;
+    kind: string;
+    type: string;
+    params: Record<string, number>;
+    bypassed: boolean;
+    url?: string;
+    /** Present on Faust entries: the DSP source this effect was compiled from. */
+    source?: {
+        faust: string;
+    };
+    label?: string;
+    error?: string;
+}
+/** Persisted form of a chain — see README for the consumer contract. */
+type SerializedEffectEntry = {
+    kind: 'native';
+    type: string;
+    params: Record<string, number>;
+    bypassed: boolean;
+} | {
+    kind: 'wam';
+    /** Module URL for url-loaded plugins. Absent for Faust entries. */
+    url?: string;
+    bypassed: boolean;
+    state?: unknown;
+    /** Faust DSP source — restore recompiles in-browser via @dawcore/faust
+     *  instead of fetching a URL. */
+    faustDsp?: string;
+    /** Name the Faust entry was compiled under (restores the same label). */
+    faustName?: string;
+};
+/** Result of creating an effect via the registry. */
+interface CreatedEffect {
+    instance: EffectInstance;
+    params: Record<string, number>;
+    wetParam?: string;
+}
+
 declare class DawTrackElement extends LitElement {
     src: string;
     name: string;
@@ -59,6 +140,35 @@ declare class DawTrackElement extends LitElement {
     spectrogramConfig: SpectrogramConfig | null;
     readonly trackId: `${string}-${string}-${string}-${string}-${string}`;
     createRenderRoot(): this;
+    addEffect(type: string, params?: Record<string, number>): string;
+    /** Load a WAM plugin (via the optional @dawcore/wam peer) into this track's chain. */
+    addWamPlugin(url: string, initialState?: unknown): Promise<string>;
+    /**
+     * Compile Faust DSP source in the browser (via the optional @dawcore/faust
+     * peer) and add the resulting WAM to this track's chain. Compile errors
+     * keep their Faust line/column diagnostics and leave the chain untouched.
+     */
+    addFaustEffect(dspCode: string, options?: {
+        name?: string;
+    }): Promise<string>;
+    /** Snapshot this track's chain in its persisted form (see dawcore README). */
+    getEffectsState(): Promise<SerializedEffectEntry[]>;
+    /** Replace this track's chain with a persisted snapshot. */
+    setEffectsState(entries: SerializedEffectEntry[]): Promise<void>;
+    /**
+     * Open (lazily creating) the GUI for one of this track's effects into a
+     * consumer-provided container. Closing hides without interrupting audio;
+     * the element is cached for reopen. See <daw-editor>.openEffectGui.
+     */
+    openEffectGui(effectId: string, container: HTMLElement): Promise<HTMLElement>;
+    /** Hide an effect's GUI (cached for reopen — never destroys). */
+    closeEffectGui(effectId: string): void;
+    removeEffect(effectId: string): void;
+    setEffectParams(effectId: string, params: Record<string, number>): void;
+    setEffectBypassed(effectId: string, bypassed: boolean): void;
+    moveEffect(effectId: string, newIndex: number): void;
+    get effects(): EffectState[];
+    private _effectsEditor;
     connectedCallback(): void;
     private _hasRendered;
     updated(changed: PropertyValues): void;
@@ -826,6 +936,45 @@ interface DawSpectrogramErrorDetail {
     generation: number;
     error: Error;
 }
+interface DawEffectAddDetail {
+    effectId: string;
+    kind: string;
+    type: string;
+    params: Record<string, number>;
+    index: number;
+    /** Plugin source URL (kind 'wam', url-loaded). */
+    url?: string;
+    /** Faust DSP source (kind 'wam', compiled in-browser via @dawcore/faust). */
+    source?: {
+        faust: string;
+    };
+}
+interface DawEffectRemoveDetail {
+    effectId: string;
+}
+interface DawEffectChangeDetail {
+    effectId: string;
+    params: Record<string, number>;
+}
+interface DawEffectBypassDetail {
+    effectId: string;
+    bypassed: boolean;
+}
+interface DawEffectReorderDetail {
+    effectId: string;
+    fromIndex: number;
+    toIndex: number;
+}
+interface DawEffectErrorDetail {
+    effectId: string;
+    /** Plugin source URL (absent for Faust entries, which have no URL). */
+    url?: string;
+    /** Faust DSP source of the failed entry, when applicable. */
+    source?: {
+        faust: string;
+    };
+    message: string;
+}
 interface DawEventMap {
     'daw-selection': CustomEvent<DawSelectionDetail>;
     'daw-seek': CustomEvent<DawSeekDetail>;
@@ -855,6 +1004,12 @@ interface DawEventMap {
     'daw-clip-split': CustomEvent<DawClipSplitDetail>;
     'daw-spectrogram-ready': CustomEvent<DawSpectrogramReadyDetail>;
     'daw-spectrogram-error': CustomEvent<DawSpectrogramErrorDetail>;
+    'daw-effect-add': CustomEvent<DawEffectAddDetail>;
+    'daw-effect-remove': CustomEvent<DawEffectRemoveDetail>;
+    'daw-effect-change': CustomEvent<DawEffectChangeDetail>;
+    'daw-effect-bypass': CustomEvent<DawEffectBypassDetail>;
+    'daw-effect-reorder': CustomEvent<DawEffectReorderDetail>;
+    'daw-effect-error': CustomEvent<DawEffectErrorDetail>;
 }
 type DawEvent<K extends keyof DawEventMap> = DawEventMap[K];
 interface LoadFilesResult {
@@ -887,6 +1042,42 @@ interface MidiLoaderHost {
     querySelectorAll(selector: string): NodeListOf<Element>;
 }
 
+interface ExportOptions {
+    /** Default: the host's sample rate. */
+    sampleRate?: number;
+    /** Window start in seconds. Default: 0. */
+    startTime?: number;
+    /** Window length in seconds. Default: host duration minus startTime. */
+    duration?: number;
+    /** Default: 2 (stereo). */
+    channels?: 1 | 2;
+}
+interface ExportClip {
+    startSample: number;
+    durationSamples: number;
+    offsetSamples: number;
+    sampleRate: number;
+    gain?: number;
+    audioBuffer?: AudioBuffer;
+}
+interface ExportTrack {
+    id: string;
+    volume: number;
+    pan: number;
+    muted: boolean;
+    soloed: boolean;
+    clips: ExportClip[];
+}
+/** What the editor provides to the export pipeline. */
+interface ExportAudioHost {
+    effectiveSampleRate: number;
+    /** Natural session duration in seconds. */
+    duration: number;
+    tracks: ExportTrack[];
+    getMasterEffectsState(): Promise<SerializedEffectEntry[]>;
+    getTrackEffectsState(trackId: string): Promise<SerializedEffectEntry[]>;
+}
+
 declare class DawEditorElement extends LitElement implements MidiLoaderHost {
     get samplesPerPixel(): number;
     set samplesPerPixel(value: number);
@@ -989,6 +1180,57 @@ declare class DawEditorElement extends LitElement implements MidiLoaderHost {
     set adapter(value: PlayoutAdapter | null);
     get adapter(): PlayoutAdapter | null;
     private _externalAdapter;
+    private _effectsManager;
+    private get _effects();
+    /** Master effects chain — inserted between the master bus and the destination. */
+    addEffect(type: string, params?: Record<string, number>): string;
+    removeEffect(effectId: string): void;
+    setEffectParams(effectId: string, params: Record<string, number>): void;
+    setEffectBypassed(effectId: string, bypassed: boolean): void;
+    moveEffect(effectId: string, newIndex: number): void;
+    get effects(): EffectState[];
+    /** Load a WAM plugin (via the optional @dawcore/wam peer) into the master chain. */
+    addWamPlugin(url: string, initialState?: unknown): Promise<string>;
+    /**
+     * Compile Faust DSP source in the browser (via the optional @dawcore/faust
+     * peer) and add the resulting WAM to the master chain. Compile errors keep
+     * their Faust line/column diagnostics and leave the chain untouched.
+     */
+    addFaustEffect(dspCode: string, options?: {
+        name?: string;
+    }): Promise<string>;
+    /**
+     * Open (lazily creating) the GUI for a master-chain effect into a
+     * consumer-provided container. WAM plugins mount their own GUI; plugins
+     * without one — and native effects — get the generic parameter panel from
+     * @dawcore/wam. The element is cached: closeEffectGui hides it without
+     * interrupting audio, reopening remounts the same element.
+     */
+    openEffectGui(effectId: string, container: HTMLElement): Promise<HTMLElement>;
+    /** Hide a master-chain effect's GUI (cached for reopen — never destroys). */
+    closeEffectGui(effectId: string): void;
+    /** Snapshot the master chain in its persisted form (see dawcore README). */
+    getEffectsState(): Promise<SerializedEffectEntry[]>;
+    /** Replace the master chain with a persisted snapshot. */
+    setEffectsState(entries: SerializedEffectEntry[]): Promise<void>;
+    /**
+     * Render the session offline through all effect chains (per-track +
+     * master), including WAM plugins (re-instantiated on the offline context
+     * with their live state). Returns the rendered AudioBuffer.
+     */
+    exportAudio(options?: ExportOptions): Promise<AudioBuffer>;
+    /** Internal — <daw-track> effects API delegates here (dawcore-internal contract). */
+    _trackAddEffect(trackId: string, target: EventTarget, type: string, params?: Record<string, number>): string;
+    _trackEffectOp(trackId: string, target: EventTarget, op: 'remove' | 'setParams' | 'setBypassed' | 'move', effectId: string, arg?: any): void;
+    _trackEffects(trackId: string): EffectState[];
+    _trackAddWamPlugin(trackId: string, target: EventTarget, url: string, initialState?: unknown): Promise<string>;
+    _trackAddFaustEffect(trackId: string, target: EventTarget, dspCode: string, options?: {
+        name?: string;
+    }): Promise<string>;
+    _trackOpenEffectGui(trackId: string, target: EventTarget, effectId: string, container: HTMLElement): Promise<HTMLElement>;
+    _trackCloseEffectGui(_trackId: string, effectId: string): void;
+    _trackGetEffectsState(trackId: string): Promise<SerializedEffectEntry[]>;
+    _trackSetEffectsState(trackId: string, target: EventTarget, entries: SerializedEffectEntry[]): Promise<void>;
     get audioContext(): AudioContext;
     _engine: PlaylistEngine | null;
     private _warnedMissingTicksToSeconds;
@@ -1496,4 +1738,9 @@ interface SplitHost {
  */
 declare function splitAtPlayhead(host: SplitHost): boolean;
 
-export { AudioResumeController, type ClipConfig, type ClipDescriptor, type ClipEngineContract, ClipPointerHandler, type ClipPointerHost, type DawClipConnectedDetail, DawClipElement, type DawClipErrorDetail, type DawClipIdDetail, type DawClipMoveDetail, type DawClipSplitDetail, type DawClipTrimDetail, type DawClipUpdateDetail, DawEditorElement, type DawErrorDetail, type DawEvent, type DawEventMap, type DawFilesLoadErrorDetail, DawGridElement, DawKeyboardShortcutsElement, DawPauseButtonElement, DawPianoRollElement, DawPlayButtonElement, DawPlayheadElement, DawRecordButtonElement, type DawRecordingCompleteDetail, type DawRecordingErrorDetail, type DawRecordingStartDetail, DawRulerElement, type DawSeekDetail, type DawSelectionDetail, DawSelectionElement, DawSpectrogramElement, DawStopButtonElement, type DawTrackConnectedDetail, type DawTrackControlDetail, DawTrackControlsElement, DawTrackElement, type DawTrackErrorDetail, type DawTrackIdDetail, type DawTrackRemoveDetail, type DawTrackSelectDetail, DawTransportButton, DawTransportElement, DawWaveformElement, type DomClipDescriptor, type DropClipDescriptor, type KeyBinding, type LoadFilesResult, type PlaybackShortcutMap, type PointerEngineContract, RecordingController, type RecordingOptions, type RecordingSession, SpectrogramController, type SplitEngineContract, type SplitHost, type SplittingShortcutMap, type TrackConfig, type TrackDescriptor, type TrackRenderMode, type UndoShortcutMap, type WaveformSegment, isDomClip, splitAtPlayhead };
+declare function registerEffect(type: string, definition: EffectDefinition): void;
+/** A copy — mutating the returned map does not affect the registry. */
+declare function getEffectDefinitions(): Map<string, EffectDefinition>;
+declare function createEffectInstance(type: string, audioContext: BaseAudioContext, params?: Record<string, number>): CreatedEffect;
+
+export { AudioResumeController, type ClipConfig, type ClipDescriptor, type ClipEngineContract, ClipPointerHandler, type ClipPointerHost, type DawClipConnectedDetail, DawClipElement, type DawClipErrorDetail, type DawClipIdDetail, type DawClipMoveDetail, type DawClipSplitDetail, type DawClipTrimDetail, type DawClipUpdateDetail, DawEditorElement, type DawEffectAddDetail, type DawEffectBypassDetail, type DawEffectChangeDetail, type DawEffectErrorDetail, type DawEffectRemoveDetail, type DawEffectReorderDetail, type DawErrorDetail, type DawEvent, type DawEventMap, type DawFilesLoadErrorDetail, DawGridElement, DawKeyboardShortcutsElement, DawPauseButtonElement, DawPianoRollElement, DawPlayButtonElement, DawPlayheadElement, DawRecordButtonElement, type DawRecordingCompleteDetail, type DawRecordingErrorDetail, type DawRecordingStartDetail, DawRulerElement, type DawSeekDetail, type DawSelectionDetail, DawSelectionElement, DawSpectrogramElement, DawStopButtonElement, type DawTrackConnectedDetail, type DawTrackControlDetail, DawTrackControlsElement, DawTrackElement, type DawTrackErrorDetail, type DawTrackIdDetail, type DawTrackRemoveDetail, type DawTrackSelectDetail, DawTransportButton, DawTransportElement, DawWaveformElement, type DomClipDescriptor, type DropClipDescriptor, type EffectDefinition, type EffectInstance, type EffectParamDef, type EffectState, type ExportAudioHost, type ExportOptions, type KeyBinding, type LoadFilesResult, type PlaybackShortcutMap, type PointerEngineContract, RecordingController, type RecordingOptions, type RecordingSession, type SerializedEffectEntry, SpectrogramController, type SplitEngineContract, type SplitHost, type SplittingShortcutMap, type TrackConfig, type TrackDescriptor, type TrackRenderMode, type UndoShortcutMap, type WaveformSegment, createEffectInstance, getEffectDefinitions, isDomClip, registerEffect, splitAtPlayhead };