# Web Components Migration Spec

Migrate to native Web Components under the **dawcore** brand, making the library truly framework-agnostic — works with vanilla JS, React 19+, Vue, Svelte, Angular, or any framework that supports Custom Elements.

**Status:** Living spec — core shipped in `@dawcore/components`; remaining work tracked in epics [#452](https://github.com/naomiaro/waveform-playlist/issues/452)–[#458](https://github.com/naomiaro/waveform-playlist/issues/458). Last audited against code 2026-06-11.
**Target:** dawcore 1.0.0
**npm:** `@dawcore/*`
**GitHub:** [github.com/dawcore](https://github.com/dawcore) (repo transfer deferred — see Open Questions)

---

## Motivation

- **Framework-agnostic** — usable in vanilla JS, Lit, Svelte, Vue, Angular, or React without adapters
- **Smaller bundle** — no React/ReactDOM/styled-components runtime dependency
- **Web standard** — Custom Elements, Shadow DOM, and CSS Parts are supported in all modern browsers
- **Ecosystem alignment** — WAM plugins, Storybook, and @dnd-kit/dom all support Web Components natively
- **Simpler API** — HTML elements with attributes, properties, methods, and events

---

## Package Landscape

The original plan renamed every `@waveform-playlist/*` package into the `@dawcore/*` scope and replaced the React packages outright. **Decision (shipped): the two ecosystems coexist instead.**

- **`@waveform-playlist/*`** remains the React surface (`browser`, `ui-components`, `recording`, `annotations`, `spectrogram`, `midi`) plus the shared framework-agnostic foundations (`core`, `engine`, `playout`, `worklets`, `webaudio-peaks`, `loaders`, `media-element-playout`). No renames.
- **`@dawcore/*`** is the Web Components ecosystem, versioned independently at 0.x:

| Package                | Directory                      | Description                                                                        |
| ---------------------- | ------------------------------ | ---------------------------------------------------------------------------------- |
| `@dawcore/components`  | `packages/dawcore`             | Web Components UI layer — Lit Custom Elements with Shadow DOM                      |
| `@dawcore/transport`   | `packages/transport`           | Native Web Audio transport/scheduler (no Tone.js); provides `NativePlayoutAdapter` |
| `@dawcore/spectrogram` | `packages/dawcore-spectrogram` | Framework-agnostic spectrogram compute (worker pool)                               |
| `@dawcore/midi`        | `packages/dawcore-midi`        | Framework-agnostic MIDI parsing (optional peer of components)                      |
| `@dawcore/wam`         | `packages/dawcore-wam`         | WAM 2.0 plugin hosting (optional peer)                                             |
| `@dawcore/faust`       | `packages/dawcore-faust`       | In-browser Faust DSP → WAM compilation (optional peer)                             |

`@dawcore/components` consumes the shared foundations as peers (`@waveform-playlist/core`, `@waveform-playlist/engine`, `@waveform-playlist/worklets`) — the engine and type layer serve both surfaces. When a React package has framework-agnostic logic worth sharing, it follows the two-flavor split convention: `@dawcore/X` core + `@waveform-playlist/X` React wrapper (precedents: spectrogram, midi).

React packages without a Web Components equivalent yet: the recording arming surface (epic #453).

---

## Custom Elements

> **Implementation status:** the core editor elements are shipped. `<daw-player>` core (#473) is implemented. Annotation elements (epic #455) are implemented. Elements listed in this spec that don't exist yet are tracked in epics: transport/control elements (#452), record arming + VU meter (#453), `<daw-player>` follow-ups — effects (#475), `<daw-playback-rate>` (#476), transport-compat tests (#474), annotation hosting in `<daw-player>` (#477) — individual track-control elements (#457).

### Core Elements

```html
<!-- Minimal setup -->
<daw-editor id="my-editor" samples-per-pixel="1024" wave-height="128" timescale>
  <daw-keyboard-shortcuts playback splitting></daw-keyboard-shortcuts>
  <daw-track src="/audio/vocals.mp3" name="Vocals"></daw-track>
  <daw-track src="/audio/guitar.mp3" name="Guitar"></daw-track>
</daw-editor>

<!-- With transport (recording-aware by default) -->
<daw-transport for="my-editor">
  <daw-play-button></daw-play-button>
  <daw-pause-button></daw-pause-button>
  <daw-stop-button></daw-stop-button>
  <daw-record-button></daw-record-button>
  <daw-rewind-button></daw-rewind-button>
  <daw-fast-forward-button></daw-fast-forward-button>
  <daw-loop-button></daw-loop-button>
  <daw-time-display></daw-time-display>
  <daw-selection-start></daw-selection-start>
  <daw-selection-end></daw-selection-end>
  <daw-time-format></daw-time-format>
  <daw-tempo></daw-tempo>
  <daw-time-signature></daw-time-signature>
  <daw-snap-to></daw-snap-to>
  <daw-scale-mode></daw-scale-mode>
  <daw-zoom-in></daw-zoom-in>
  <daw-zoom-out></daw-zoom-out>
</daw-transport>
```

### Element Registry

| Element                     | Wraps                                      | Responsibilities                                                                                                                                                                                                                                                            |
| --------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<daw-editor>`              | PlaylistEngine + external `PlayoutAdapter` | Root element. Manages engine, tracks, state. Requires a consumer-provided adapter (`editor.adapter`) — it creates no AudioContext or adapter of its own (#378).                                                                                                             |
| `<daw-track>`               | Track state                                | Declares a track. Contains `<daw-clip>` children. Attributes: `name`, `volume`, `pan`, `muted`, `soloed`, `record-armed`, `input-device`, `render-mode`. `src` is shorthand for a track with a single implicit clip.                                                        |
| `<daw-clip>`                | AudioClip                                  | Audio or MIDI clip within a track. Attributes: `src`, `peaks-src`, `start`, `duration`, `offset`, `gain`, `name`, `color`, `fade-in`, `fade-out`, `fade-type`. Multiple clips sharing the same `src` share one decoded AudioBuffer.                                         |
| `<daw-waveform>`            | Canvas rendering                           | Waveform visualization. Renders peaks to canvas.                                                                                                                                                                                                                            |
| `<daw-transport>`           | Transport controls container               | Groups transport buttons, links to an editor via `for` attribute.                                                                                                                                                                                                           |
| `<daw-track-controls>`      | Track mixer strip                          | Shipped composite: name, volume, pan, mute, solo for one track, rendered by the editor in the frozen controls column. Dispatches a unified `daw-track-control` event (`{trackId, prop, value}`). Individual control elements below complement it (#457).                    |
| `<daw-play-button>`         | play()                                     | Triggers playback. If recording is armed, starts overdub recording simultaneously.                                                                                                                                                                                          |
| `<daw-pause-button>`        | pause() / togglePauseRecording()           | Pauses playback. During recording, toggles pause/resume of the worklet capture (Audacity-style). Reflects state via `data-paused` attribute; sync handled by `daw-recording-pause` / `daw-recording-resume` events so the spacebar shortcut and the button stay consistent. |
| `<daw-stop-button>`         | stop()                                     | Stops playback and recording. Finalizes any in-progress recording into a new clip.                                                                                                                                                                                          |
| `<daw-record-button>`       | record()                                   | Arms/starts recording on all armed tracks. When clicked during stop, arms the selected track (or first track). When clicked during play, starts overdub on armed tracks.                                                                                                    |
| `<daw-rewind-button>`       | seekTo(0)                                  | Rewinds playhead to the start of the timeline.                                                                                                                                                                                                                              |
| `<daw-fast-forward-button>` | seekTo(duration)                           | Jumps playhead to the end of the timeline.                                                                                                                                                                                                                                  |
| `<daw-loop-button>`         | toggleLoop()                               | Toggles loop playback for the current selection. Reflects `aria-pressed` state.                                                                                                                                                                                             |
| `<daw-time-display>`        | currentTime                                | Shows formatted playback time.                                                                                                                                                                                                                                              |
| `<daw-selection-start>`     | setSelection()                             | Editable input showing selection start time. Updates selection on change.                                                                                                                                                                                                   |
| `<daw-selection-end>`       | setSelection()                             | Editable input showing selection end time. Updates selection on change.                                                                                                                                                                                                     |
| `<daw-time-format>`         | setTimeFormat()                            | Select for time display format (`hh:mm:ss.sss`, `hh:mm:ss`, `seconds`). Affects time display and selection inputs.                                                                                                                                                          |
| `<daw-tempo>`               | editor.bpm property                        | Editable BPM input. Reflects current tempo. Drives grid/ruler musical time and snap. Display-only when consumer tick callbacks make the external tempo map authoritative (#407).                                                                                            |
| `<daw-time-signature>`      | editor.timeSignature property              | Editable time signature (e.g., `4/4`, `3/4`, `6/8`). Drives ruler subdivisions and snap grid.                                                                                                                                                                               |
| `<daw-snap-to>`             | setSnapTo()                                | Select for snap granularity. Controls clip drag/trim snapping and `<daw-grid>` line density. See [Snap Subdivisions](#snap-subdivisions).                                                                                                                                   |
| `<daw-scale-mode>`          | setScaleMode()                             | Select for ruler display mode (`beats`, `temporal`). Switches between bar:beat and minutes:seconds ruler.                                                                                                                                                                   |
| `<daw-zoom-in>`             | zoomIn()                                   | Zoom in button. Disabled when at maximum zoom.                                                                                                                                                                                                                              |
| `<daw-zoom-out>`            | zoomOut()                                  | Zoom out button. Disabled when at minimum zoom.                                                                                                                                                                                                                             |
| `<daw-undo-button>`         | undo()                                     | Undo last structural edit. Auto-disables when `canUndo` is false.                                                                                                                                                                                                           |
| `<daw-redo-button>`         | redo()                                     | Redo last undone edit. Auto-disables when `canRedo` is false.                                                                                                                                                                                                               |
| `<daw-playback-rate>`       | setPlaybackRate()                          | Playback speed control. Works with both `<daw-editor>` and `<daw-player>`.                                                                                                                                                                                                  |
| `<daw-player>`              | HTMLMediaElement                           | Lightweight single-track player. Uses `<audio>` element internally — no Tone.js, no engine. Supports waveform, transport, annotations, and optional effects.                                                                                                                |
| `<daw-mute-button>`         | mute toggle                                | Dispatches `daw-mute` event. Auto-wires to parent `<daw-track>` via `closest()`. Reflects `aria-pressed` state.                                                                                                                                                             |
| `<daw-solo-button>`         | solo toggle                                | Dispatches `daw-solo` event. Auto-wires to parent `<daw-track>`. Reflects `aria-pressed` state.                                                                                                                                                                             |
| `<daw-volume-slider>`       | setTrackVolume() / setMasterVolume()       | Volume control. When inside a `<daw-track>`, controls that track. When inside `<daw-transport>`, controls master volume.                                                                                                                                                    |
| `<daw-pan-slider>`          | setTrackPan()                              | Per-track pan control.                                                                                                                                                                                                                                                      |
| `<daw-vu-meter>`            | Meter worklet                              | Level metering (replaces SegmentedVUMeter).                                                                                                                                                                                                                                 |
| `<daw-ruler>`               | Time ruler                                 | Renders time ruler above tracks. In beats & bars mode, uses adaptive label density — skips labels at coarse zoom, shows every bar/beat at fine zoom. Shares tick computation with `<daw-grid>`.                                                                             |
| `<daw-grid>`                | Beat/bar grid                              | Canvas-based background grid behind waveforms. Visible only in beats & bars scale mode. Chunked rendering with virtual scrolling (same pattern as `<daw-waveform>`). See [Beat & Bar Grid](#beat--bar-grid).                                                                |
| `<daw-playhead>`            | Playhead                                   | Animated playhead line.                                                                                                                                                                                                                                                     |
| `<daw-keyboard-shortcuts>`  | Keyboard handler                           | Render-less element inside `<daw-editor>`. Boolean attributes: `playback`, `splitting`, `undo`. Properties: `customShortcuts`, `playbackShortcuts`, `splittingShortcuts`, `undoShortcuts` (key remapping), `shortcuts` (read-only, all active).                             |

### Beat & Bar Grid

`<daw-grid>` renders a striped background behind the track area, visible only in beats & bars scale mode. It helps users visually align clips to the beat/bar structure and makes snap-to-grid intuitive.

**Layer order:** `--daw-background` (editor base) → grid stripes → clips (opaque background) → waveforms → playhead. Track rows are transparent layout containers — no `--daw-track-background` fill — so grid stripes show through. Clips render with their own opaque background.

**Zoom-dependent display:**

| Zoom Level                         | Lines                                       | Striping            |
| ---------------------------------- | ------------------------------------------- | ------------------- |
| Coarse (bars too dense for labels) | Every Nth bar (matches ruler label density) | None — lines only   |
| Medium (bars visible, beats dense) | Every bar                                   | Bar-level odd/even  |
| Fine (beats visible)               | Every beat                                  | Beat-level odd/even |

Grid line spacing matches the ruler's label spacing — they share the same tick computation logic. The ruler's beats & bars mode uses adaptive label density (skip labels when they'd overlap, show every Nth bar at coarse zoom). The grid follows the same thresholds.

**CSS custom properties (shipped names — see `daw-grid.ts`):**

```css
--daw-grid-bar-highlight: rgba(255, 255, 255, 0.02); /* alternating bar fill */
--daw-grid-major-line: rgba(255, 255, 255, 0.1); /* bar lines */
--daw-grid-minor-line: rgba(255, 255, 255, 0.06); /* beat/subdivision lines */
```

Highlight stripes alternate at whatever the current granularity is (bars at medium zoom, beats at fine zoom). At coarse zoom, no stripes — just lines.

**Data source:** Reads tempo (BPM) and meter (numerator/denominator) from the editor's transport. Redraws on `tempochange`, `meterchange`, zoom, and scroll.

**Usage:**

```html
<daw-editor id="editor" samples-per-pixel="512" timescale>
  <daw-grid></daw-grid>
  <daw-keyboard-shortcuts playback splitting></daw-keyboard-shortcuts>
  <daw-track src="/audio/drums.opus" name="Drums"></daw-track>
  <daw-track src="/audio/bass.opus" name="Bass"></daw-track>
</daw-editor>
```

### Snap Subdivisions

Expand `SnapTo` from `'bar' | 'beat' | 'off'` to support note subdivisions and triplets:

```typescript
type SnapTo =
  | 'bar' // ticksPerBar
  | 'beat' // ticksPerBeat (quarter in 4/4, eighth in 6/8)
  | '1/2'
  | '1/4'
  | '1/8'
  | '1/16'
  | '1/32' // straight subdivisions
  | '1/2T'
  | '1/4T'
  | '1/8T'
  | '1/16T' // triplets (2/3 of straight value)
  | 'off';
```

**Grid tick calculation** (shared by `SnapToGridModifier`, `<daw-grid>`, and `<daw-ruler>`):

| SnapTo  | Grid ticks (at 960 PPQN, 4/4) | Musical value                      |
| ------- | ----------------------------- | ---------------------------------- |
| `bar`   | 3840                          | 1 bar                              |
| `beat`  | 960                           | quarter note                       |
| `1/2`   | 1920                          | half note                          |
| `1/4`   | 960                           | quarter note (same as beat in 4/4) |
| `1/8`   | 480                           | eighth note                        |
| `1/16`  | 240                           | sixteenth note                     |
| `1/32`  | 120                           | thirty-second note                 |
| `1/4T`  | 640                           | quarter triplet (960 \* 2/3)       |
| `1/8T`  | 320                           | eighth triplet (480 \* 2/3)        |
| `1/16T` | 160                           | sixteenth triplet (240 \* 2/3)     |

The `T` suffix denotes triplet — the note value is multiplied by 2/3. For compound meters (6/8), `beat` is an eighth note (480 ticks), so `1/8T` would be 320 ticks (eighth triplet).

**`<daw-snap-to>` element** renders a select/dropdown with these options. The current value drives both clip snapping (via `SnapToGridModifier`) and grid line density (via `<daw-grid>`).

**Utility function** (shipped in `@waveform-playlist/core` — `src/utils/musicalTicks.ts`):

```typescript
function snapToTicks(snapTo: SnapTo, timeSignature: [number, number], ppqn = 960): number;
```

Single source of truth for converting `SnapTo` → tick count. Used by `SnapToGridModifier`, `<daw-grid>`, and `<daw-ruler>`.

### Multi-Track Record Arming

> Tracked in epic #453. The recording backend (worklet pipeline, per-track sessions, pause/resume, latency compensation) is shipped; the arming API below is not yet.

```html
<!-- Arm individual tracks for recording -->
<daw-editor id="my-editor">
  <daw-track src="/audio/drums.mp3" name="Drums"></daw-track>
  <daw-track name="Vocal Take" record-armed></daw-track>
  <daw-track name="Guitar Take" record-armed input-device="abc123"></daw-track>
</daw-editor>

<daw-transport for="my-editor">
  <daw-record-button></daw-record-button>
  <daw-play-button></daw-play-button>
  <daw-stop-button></daw-stop-button>
</daw-transport>
```

**Behavior:**

- Tracks with `record-armed` attribute will record simultaneously when recording starts
- Each armed track can have its own `input-device` for different mic inputs
- Clicking `<daw-record-button>` during stop arms the selected track if none are armed, then starts record + play
- Clicking `<daw-record-button>` during play starts overdub recording on all armed tracks
- `<daw-stop-button>` stops playback and finalizes all in-progress recordings into new clips
- Tracks without `record-armed` play back normally during overdub
- `<daw-vu-meter>` on an armed track shows input level from the mic stream before and during recording

```javascript
// Programmatic multi-track arming
const editor = document.getElementById('my-editor');
const tracks = editor.querySelectorAll('daw-track');

// Arm specific tracks
tracks[1].arm(); // Default mic
tracks[2].arm('specific-device-id'); // Specific mic

// Check armed state
console.log(editor.armedTrackIds); // ['track-2', 'track-3']
console.log(editor.isRecordArmed); // true

// Listen for recording events
editor.addEventListener('daw-recording-start', (e) => {
  console.log('Recording started on track:', e.detail.trackId);
});

editor.addEventListener('daw-recording-complete', (e) => {
  console.log('Recorded buffer:', e.detail.audioBuffer);
  // Cancelable — preventDefault() to skip automatic clip creation
});

// Pause/resume during recording (Audacity-style: also pauses Transport when overdubbing)
editor.addEventListener('daw-recording-pause', (e) => {
  console.log('Paused track:', e.detail.trackId);
});

// Disarm all
editor.armedTrackIds.forEach((id) => {
  editor.querySelector(`daw-track[id="${id}"]`).disarm();
});
```

### Optional Elements

> Annotation elements shipped under epic #455. `parseAeneas`/`serializeAeneas` remain React-only in `@waveform-playlist/annotations` — the dawcore elements consume `<daw-annotation>` light-DOM children directly, not those parsers. Hosting `<daw-annotation-track>`/`<daw-annotation>` children inside `<daw-player>` is still open (#477); today they're documented under `<daw-editor>`.

| Element                  | Package    | Responsibilities                                                                                                                                                                                                     |
| ------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<daw-annotation-track>` | components | Timeline row containing draggable annotation boxes. Children are `<daw-annotation>` elements. Attributes: `editable`, `link-endpoints`, `continuous-play`, `keyboard-controls`, `box-label`, `name`.                 |
| `<daw-annotation>`       | components | Single annotation with `start`, `end` (seconds) attributes, optional `start-tick`, `end-tick` (musical position) attributes, and text content. Renders as a box in the track.                                        |
| `<daw-annotation-list>`  | components | Scrollable text panel. Links to a `<daw-annotation-track>` via `for` attribute — no duplicate data. `time-display` (`'time'` default \| `'bars'`) switches the times column between clock times and bar.beat ranges. |

```html
<!-- Annotations: single source of truth, dual view -->
<daw-editor id="my-editor">
  <daw-annotation-track id="lyrics" editable link-endpoints>
    <daw-annotation start="0.0" end="2.5">First line of lyrics</daw-annotation>
    <daw-annotation start="2.5" end="5.1">Second line of lyrics</daw-annotation>
    <daw-annotation start="5.1" end="8.0">Third line of lyrics</daw-annotation>
  </daw-annotation-track>
  <daw-track src="/audio/vocals.mp3" name="Vocals"></daw-track>
</daw-editor>

<!-- Text list view linked to the same data via for/id -->
<daw-annotation-list for="lyrics"></daw-annotation-list>
```

Annotations are defined once as `<daw-annotation>` children. The `<daw-annotation-list>` reads from the same elements — edits in either view (dragging a box or editing text) update the shared `<daw-annotation>` attributes.

**Tick authority rule:** an annotation is tick-based iff BOTH `start-tick` and `end-tick` are set — `start`/`end` seconds then become a derived cache the host editor keeps fresh (same pattern as clip `startTick`). Setting only one of the two tick attributes is a half-configured state: it's treated as seconds-based and logs a one-time warning per annotation. Tick edits (boundary drag, `moveStartBoundary`/`moveEndBoundary`) require a host `<daw-editor>` for tempo conversion — calling them on a tick-based annotation with no parent editor warns and is ignored.

**`<daw-annotation-list time-display="bars">`:** shows each row's times span as `B.b – B.b` bar.beat ranges instead of clock times. Resolves the host editor via `this.track.closest('daw-editor')`; tick-based annotations use `startTick`/`endTick` directly, seconds-based annotations convert via `editor._secondsToTicks()`. Both edges are converted with `ticksToBarBeat(tick, editor._meterEntries, editor.ppqn)` from `@waveform-playlist/core` (1-based bar/beat, multi-meter aware). No host editor → falls back to time display and warns once.

Spectrogram and piano-roll are render modes on `<daw-track>` (via the `render-mode` attribute), not standalone elements. See the [Spectrogram & Piano-Roll](#spectrogram--piano-roll) section.

---

## Properties, Attributes & Events

### `<daw-editor>` API

**Adapter (required):** `<daw-editor>` does not create an AudioContext or a default adapter. Set `editor.adapter` to a `PlayoutAdapter` before use — `NativePlayoutAdapter` (from `@dawcore/transport`) or `TonePlayoutAdapter` (Tone.js backend). The adapter owns the `AudioContext` and exposes a required `ppqn`; the engine aligns its tick resolution to `adapter.ppqn` on construction (#378).

**Attributes (reflected):**

```
samples-per-pixel    Number    1024     Zoom level
wave-height          Number    128      Track height in px
timescale            Boolean   false    Show time ruler
mono                 Boolean   false    Mono waveform rendering
automatic-scroll     Boolean   false    Follow playhead
indefinite-playback  Boolean   false    Disable end-of-timeline auto-stop (DAW-style roll until explicit stop). Implies fill-viewport
fill-viewport        Boolean   false    Fill viewport when shorter than visible width (layout only) — lets the ruler render before any audio is loaded
bar-width            Number    1        Waveform bar width
bar-gap              Number    0        Waveform bar gap
rounded-bars         Boolean   false    Pill-shaped bar caps (radius bar-width/2)
clip-headers         Boolean   false    Show clip name headers
file-drop            Boolean   false    Accept dropped audio/MIDI files
```

**Properties (JS only):**

```typescript
editor.adapter: PlayoutAdapter       // Required — consumer-provided audio backend (#378)
editor.tracks: TrackWithId[]         // {trackId, name, …} for every track incl. element-less (dropped/programmatic); the trackId keys the per-track APIs (addTrackEffect, removeTrack, updateTrack, …)
editor.isPlaying: boolean            // Playback state
editor.isRecording: boolean          // Recording state (any track recording)
editor.armedTrackIds: string[]       // Track IDs with record-armed attribute
editor.isRecordArmed: boolean        // Derived: armedTrackIds.length > 0
editor.currentTime: number           // Current playback time
editor.duration: number              // Total duration
editor.selection: {start, end}       // Selection range
editor.selectedTrackId: string|null  // Selected track
editor.effects: EffectState[]        // Read-only. Master effects chain (see Effects section for shape)
editor.spectrogramConfig: SpectrogramConfig | null  // Global spectrogram defaults (null = built-in defaults)
editor.canUndo: boolean              // Has undo history
editor.canRedo: boolean              // Has redo history
editor.undoLimit: number             // Max undo steps (default 100)
editor.engine: PlaylistEngine        // Direct engine access
```

**Methods:**

```typescript
editor.play(startTime?, endTime?): Promise<void>    // Starts overdub if record is armed. endTime disables
                                                     // looping and stops playback at that time (selection/
                                                     // annotation playback — used by annotationTrack.playActive())
editor.pause(): void                               // Pauses playback Transport (does NOT pause active recording — use togglePauseRecording for that)
editor.stop(): void                                // Stops playback
editor.record(): Promise<void>                     // Starts recording on all armed tracks
editor.startRecording(stream): Promise<void>       // Start recording on selected track with provided MediaStream
editor.stopRecording(): Promise<void>              // Stop and finalize recording (awaits worklet's done ack)
editor.pauseRecording(): void                      // Pause worklet capture only (no Transport effect)
editor.resumeRecording(): void                     // Resume worklet capture
editor.togglePauseRecording(): void                // Audacity-style: pauses worklet AND Transport (if running); on resume restarts Transport only when it was running before
editor.isRecording: boolean                        // (getter) any track currently recording
editor.isRecordingPaused: boolean                  // (getter) capture is paused
editor.armTrack(trackId: string, deviceId?: string): Promise<void>  // Arm a track
editor.disarmTrack(trackId: string): void           // Disarm a track
editor.seekTo(time: number): void
editor.setSelection(start: number, end: number): void
// Track mixing changes go through updateTrack() — there are no per-property
// setTrackVolume/Pan/Mute/Solo methods:
//   editor.updateTrack(trackId, { volume: 0.8, muted: true })
editor.zoomIn(): void
editor.zoomOut(): void
editor.setMasterVolume(volume: number): void
// Programmatic track/clip mutation (see "Programmatic Track Mutation" section)
editor.ready(): Promise<PlaylistEngine>                                  // Ensure engine is built; resolves with it
editor.addTrack(config: TrackConfig): Promise<DawTrackElement>           // Append a <daw-track>
editor.removeTrack(trackId: string): void                                // Remove track by ID
editor.updateTrack(trackId: string, partial: Partial<TrackConfig>): void
editor.addClip(trackId: string, config: ClipConfig): Promise<string>     // Returns clipId
editor.removeClip(trackId: string, clipId: string): void
editor.updateClip(trackId: string, clipId: string, partial: Partial<ClipConfig>): void
editor.setTimeFormat(format: string): void             // 'hh:mm:ss.sss' | 'hh:mm:ss' | 'seconds'
editor.setAutomaticScroll(enabled: boolean): void      // Toggle auto-scroll
editor.bpm = 140                                       // Display/grid tempo. Forwards to the adapter's
                                                       // transport ONLY when no tick callbacks are set;
                                                       // with consumer tick callbacks the external tempo
                                                       // map is authoritative and bpm is display-only (#407)
editor.timeSignature = [3, 4]                          // Property setter ([numerator, denominator])
editor.snapTo = 'beat'                                 // Property setter (full SnapTo union — see Snap Subdivisions)
editor.scaleMode = 'beats'                             // Property setter ('beats' | 'temporal')
editor.setLoopEnabled(enabled: boolean): void          // Toggle loop playback (planned)
editor.setLoopRegion(start: number, end: number): void // Set loop boundaries (planned)
// Effects (master chain)
editor.addEffect(type: string, params?: Record<string, number>): string  // Returns effectId
editor.removeEffect(effectId: string): void
editor.setEffectParams(effectId: string, params: Record<string, number>): void
editor.setEffectBypassed(effectId: string, bypassed: boolean): void
editor.moveEffect(effectId: string, newIndex: number): void
editor.openEffectGui(effectId: string, container: HTMLElement): Promise<HTMLElement> // Mount a master-chain effect's GUI into a consumer-provided container
editor.closeEffectGui(effectId: string): void                                        // Detach the GUI (cached for reopen)
// Offline rendering
editor.exportAudio(options?: ExportOptions): Promise<AudioBuffer>
// MIDI loading
editor.loadMidi(source: string | File, options?: MidiLoadOptions): Promise<MidiLoadResult>
// Undo/redo
editor.undo(): void
editor.redo(): void
editor.clearHistory(): void
// File loading (audio + MIDI auto-detection)
editor.loadFiles(files: File[] | FileList, options?: LoadFilesOptions): Promise<LoadFilesResult>
```

**Events:**

```typescript
'daw-ready'; // All tracks loaded
'daw-play'; // Playback started
'daw-pause'; // Playback paused
'daw-stop'; // Playback stopped
'daw-recording-start'; // Recording started on a track: detail: {trackId, stream}
'daw-recording-complete'; // Recording finalized: detail: {trackId, audioBuffer, startSample, durationSamples, offsetSamples} — cancelable; preventDefault() skips automatic clip creation
'daw-recording-error'; // Recording failed: detail: {trackId, error}
'daw-recording-pause'; // Worklet capture paused: detail: {trackId}
'daw-recording-resume'; // Worklet capture resumed: detail: {trackId}
'daw-record-arm'; // Track armed/disarmed: detail: {trackId, armed, armedTrackIds}
'daw-timeupdate'; // Playback time changed (RAF)
'daw-selection'; // Selection changed: detail: {start, end}
'daw-track-select'; // Track selected: detail: {trackId}
'daw-tracks-change'; // Tracks mutated (move/trim/split): detail: {tracks}
'daw-zoom'; // Zoom changed: detail: {samplesPerPixel}
// Effect events (bubble from <daw-track> for per-track, dispatched on <daw-editor> for master)
'daw-effect-add'; // Effect added: detail: {effectId, kind, type, params, index, url?, source?}
'daw-effect-remove'; // Effect removed: detail: {effectId}
'daw-effect-change'; // Params updated: detail: {effectId, params}
'daw-effect-bypass'; // Bypass toggled: detail: {effectId, bypassed}
'daw-effect-reorder'; // Effect moved: detail: {effectId, fromIndex, toIndex}
// Spectrogram
'daw-spectrogram-ready'; // Visible viewport FFT complete: detail: {trackId}
// Undo/redo
'daw-undo-state'; // canUndo/canRedo changed: detail: {canUndo, canRedo}
// File loading
'daw-files-load-error'; // Decode/parse failed: detail: {file: File, error: string}
// Programmatic mutation
'daw-track-ready'; // Track finished loading: detail: {trackId}
'daw-track-removed'; // Track removed (DOM removal / removeTrack / controls): detail: {trackId} — fired after editor.tracks reflects the removal
'daw-track-error'; // Track failed to load: detail: {trackId, error}
'daw-clip-ready'; // Clip finished loading: detail: {trackId, clipId}
'daw-clip-error'; // Clip failed to load: detail: {trackId, clipId, error}
```

### `<daw-track>` API

**Attributes (reflected):**

```
src              String    —        Audio source URL
name             String    —        Track display name
volume           Number    1        Track volume (0–1)
pan              Number    0        Stereo pan (-1 to 1)
muted            Boolean   false    Track is muted
soloed           Boolean   false    Track is soloed
record-armed     Boolean   false    Track is armed for recording
input-device     String    —        MediaDeviceInfo.deviceId for mic input
render-mode      String    waveform 'waveform' | 'spectrogram' | 'split' | 'piano-roll'
```

**Properties (JS only):**

```typescript
track.recordArmed: boolean       // Reflects record-armed attribute
track.inputDevice: string|null   // Reflects input-device attribute
track.renderMode: string         // Reflects render-mode attribute
track.isRecording: boolean       // Read-only: currently recording (armed + editor.isRecording)
track.inputStream: MediaStream   // Read-only: active mic stream when recording
track.effects: EffectState[]     // Read-only. Per-track effects chain: [{id, type, params, bypassed}, ...]
track.spectrogramConfig: SpectrogramConfig | null  // Per-track override (null = inherit from editor)
```

**Methods:**

```typescript
track.arm(deviceId?: string): Promise<void>   // Arm for recording, request mic access
track.disarm(): void                          // Disarm, release mic stream
// Effects (per-track chain) — same API as editor master chain
track.addEffect(type: string, params?: Record<string, number>): string  // Returns effectId
track.removeEffect(effectId: string): void
track.setEffectParams(effectId: string, params: Record<string, number>): void
track.setEffectBypassed(effectId: string, bypassed: boolean): void
track.moveEffect(effectId: string, newIndex: number): void
track.openEffectGui(effectId: string, container: HTMLElement): Promise<HTMLElement>  // Mount a per-track effect's GUI into a consumer-provided container
track.closeEffectGui(effectId: string): void                                         // Detach the GUI (cached for reopen)
```

When `arm()` is called without a `deviceId`, it uses the default input device. The method requests mic permission via `getUserMedia()` and stores the stream for use when recording starts. Calling `arm()` on an already-armed track with a different `deviceId` switches the input device.

### `<daw-clip>` API

**Attributes (reflected):**

```
src              String    —        Audio file URL
peaks-src        String    —        Pre-computed BBC audiowaveform peaks URL (.dat/.json)
start            Number    0        Position on timeline (seconds)
duration         Number    —        Clip duration (seconds). Defaults to source length.
offset           Number    0        Start offset within source audio (seconds) — trim start
gain             Number    1        Clip volume (0.0 to 1.0+)
name             String    —        Clip label
color            String    —        Clip color for visual distinction
fade-in          Number    0        Fade in duration (seconds)
fade-out         Number    0        Fade out duration (seconds)
fade-type        String    linear   Fade curve: 'linear' | 'logarithmic' | 'sCurve' | 'exponential'
midi-channel     Number    —        MIDI channel (0-indexed, 9 = percussion)
midi-program     Number    —        MIDI program number (0-127)
```

**Properties (JS only):**

```typescript
clip.midiNotes: MidiNoteData[] | null        // Parsed MIDI notes
```

Decoded `AudioBuffer`s and parsed peaks are managed by the editor's URL-keyed caches, not exposed as properties on the element. To supply a pre-decoded buffer or pre-computed peaks programmatically, use the imperative path instead: `editor.addClip(trackId, { audioBuffer, waveformData, ... })`.

Attributes use seconds for human readability. The element converts to the internal sample-based model (`startSample`, `offsetSamples`, `durationSamples`) automatically.

```html
<!-- Single clip shorthand: <daw-track src="..."> expands to one implicit clip -->
<daw-track name="Vocals" src="/audio/vocals.mp3"></daw-track>

<!-- Equivalent explicit form -->
<daw-track name="Vocals">
  <daw-clip src="/audio/vocals.mp3"></daw-clip>
</daw-track>

<!-- Multi-clip with positioning, fades, and shared audio source -->
<daw-track name="Chorus Repeats">
  <daw-clip
    src="/audio/chorus.mp3"
    start="0"
    duration="8"
    fade-in="0.5"
    fade-out="1.0"
    fade-type="sCurve"
  >
  </daw-clip>
  <daw-clip src="/audio/chorus.mp3" start="20" duration="8"> </daw-clip>
  <daw-clip src="/audio/chorus.mp3" start="40" duration="4" offset="2.0" fade-in="0.3"> </daw-clip>
</daw-track>

<!-- Pre-computed peaks for large files (render before decode) -->
<daw-track name="Full Mix">
  <daw-clip src="/audio/full-mix.mp3" peaks-src="/peaks/full-mix.dat"> </daw-clip>
</daw-track>
```

### Resource Caching

`<daw-editor>` maintains a URL-keyed cache for each resource type, deduplicating fetch + decode across clips:

```
Map<string, Promise<AudioBuffer>>     // src → decoded audio
Map<string, Promise<WaveformData>>    // peaks-src → parsed peaks
```

Multiple `<daw-clip>` elements with the same `src` share one `AudioBuffer` — each clip is an independent window (start/offset/duration/fades) into the same underlying data. The same applies to `peaks-src`. Cache is scoped to the editor instance and cleared when the editor is disconnected.

### `<daw-annotation-track>` API

**Attributes (reflected):**

```
editable           Boolean   false    Allow drag/resize of annotation boxes
link-endpoints     Boolean   false    Snap adjacent annotation boundaries together
continuous-play    Boolean   false    Auto-advance playback through annotations
keyboard-controls  Boolean   false    Enable keyboard navigation and boundary editing
box-label          String    'text'   Lane box label mode: 'text' | 'id' | 'none'
name               String    ''       Display label for the editor's controls-column lane row
```

`editable`, `link-endpoints`, and `continuous-play` map directly to `AnnotationListOptions` from `@waveform-playlist/core`. `keyboard-controls` enables keyboard shortcuts for annotation navigation and boundary editing (see [Keyboard Shortcuts](#keyboard-shortcuts)). `box-label` only affects the timeline lane's box text — `'text'` shows the annotation's text lines joined with spaces (default), `'id'` shows the `id` attribute or a 1-based position fallback, `'none'` renders bare region bars; `<daw-annotation-list>` always shows full text regardless of this setting. `name` mirrors `<daw-track name>` — an empty string (default) renders a blank spacer so setting it is opt-in and doesn't shift layout.

**Properties (JS only):**

```typescript
annotationTrack.activeAnnotationId: string | null                  // Currently selected annotation
annotationTrack.annotationShortcuts: AnnotationShortcutMap | null  // Key remapping (null = defaults)
```

**Methods:**

```typescript
annotationTrack.selectNext(): void
annotationTrack.selectPrevious(): void
annotationTrack.selectFirst(): void
annotationTrack.selectLast(): void
annotationTrack.clearSelection(): void
annotationTrack.playActive(): void
annotationTrack.moveStartBoundary(deltaMs: number): void
annotationTrack.moveEndBoundary(deltaMs: number): void
```

**Navigation with no active selection:** `selectNext()` with no `activeAnnotationId` selects the FIRST annotation (not the second); `selectPrevious()` with no selection selects the LAST annotation. Both wrap normally (last→first, first→last) once a selection exists. This lets `ArrowDown`/`ArrowRight` and `ArrowUp`/`ArrowLeft` behave symmetrically as "enter the list from either end" on first press.

**Capture-phase keyboard priority:** each `<daw-annotation-track keyboard-controls>` registers its keydown listener on `document` in the **capture** phase (`addEventListener('keydown', handler, true)`), which runs before `<daw-keyboard-shortcuts>`' bubble-phase listener regardless of DOM position. A consumed key calls `e.stopImmediatePropagation()` (not `stopPropagation()`) — this is required because multiple annotation tracks each register their own capture listener on the same `document` node, and `stopPropagation()` does not stop sibling listeners on that node, only `stopImmediatePropagation()` does. The practical effect: when two or more `<daw-annotation-track keyboard-controls>` elements are present, a consumed key acts on exactly the **first-registered track (DOM connection order)** — not every track, and not the "closest" or "focused" one. Keys the track doesn't consume (`Escape` with no selection, boundary-edit keys when not `editable` or nothing selected) fall through both to sibling annotation tracks and to `<daw-keyboard-shortcuts>`.

**Beats-mode variable-tempo limitation (seconds-based annotations only):** a **seconds-based** annotation (no `start-tick`/`end-tick`) positions its lane box with `left = floor(start_seconds * sampleRate / spp)` — using the same `spp` (`_renderSpp`) the beats grid uses. Clip positions in beats mode instead derive pixels from `startTick / ticksPerPixel` directly. Under a **fixed** tempo the two mappings agree, but under **variable tempo** (consumer-supplied `secondsToTicks`/`ticksToSeconds` callbacks with tempo changes), a seconds-based annotation's box drifts out of alignment with the tick-positioned clips and grid. A **tick-based** annotation (both `start-tick` and `end-tick` set) does not have this limitation: its lane box uses the same clip-identical tick math as clips (`round(tick / ticksPerPixel)`), so it stays pixel-exact under variable tempo. Give drifting annotations first-class tick positions (`start-tick`/`end-tick`) to eliminate the limitation.

The editor keeps a tick-based annotation's seconds cache fresh via a sweep (`AnnotationController.deriveSecondsCaches`) that runs on annotation connect/update/select and whenever the engine's reported `bpm` changes on `statechange`. A variable-tempo tempo-map edit that doesn't change the engine's scalar `bpm` (e.g. editing a later tempo-map segment) does not trigger this sweep — the seconds cache re-derives lazily on the next annotation connect/update/select event instead. Temporal-mode rendering always reads this seconds cache, so it's never stale by more than one such event.

**Events (`<daw-annotation>` / `<daw-annotation-track>`):**

```typescript
'daw-annotation-connected'; // <daw-annotation> mounted: detail: {annotationId, element}
'daw-annotation-update'; // start/end or start-tick/end-tick changed (after first render, not on initial mount): detail: {annotationId}
'daw-annotation-select'; // activeAnnotationId changed on a track (incl. clear → null): detail: {annotation: AnnotationData | null}
'daw-annotation-track-connected'; // <daw-annotation-track> mounted: detail: {element}
'daw-error'; // annotation shortcut action threw: detail: {operation: 'annotation-shortcut', key, error}
```

All bubble and compose (cross Shadow DOM boundaries). `daw-annotation-select` is dispatched on the `<daw-annotation-track>` element (`e.target` identifies which track), consumed by `<daw-annotation-list for="...">` to sync its active row.

### `<daw-player>` API

> Core implemented in #473 (epic #454). Wraps `@waveform-playlist/media-element-playout`. Outstanding follow-ups: effects (#475), `<daw-playback-rate>` element (#476), transport-compat tests (#474), annotations (#477).

A lightweight single-track audio player that uses `HTMLMediaElement` (`<audio>`) internally — no Tone.js, no PlaylistEngine. Ideal for podcast players, music previews, audiobook readers, or any scenario that needs waveform visualization without multi-track editing.

**Attributes (reflected):**

```
src              String    —        Audio source URL
peaks-src        String    —        Pre-computed BBC audiowaveform peaks URL (.dat/.json)
wave-height      Number    128      Waveform height in px
timescale        Boolean   false    Show time ruler
mono             Boolean   false    Mono waveform rendering
bar-width        Number    1        Waveform bar width
bar-gap          Number    0        Waveform bar gap
rounded-bars     Boolean   false    Pill-shaped bar caps (radius bar-width/2)
automatic-scroll Boolean   false    Follow playhead
playback-rate    Number    1        Playback speed (0.25–4.0)
```

**Properties (JS only):**

```typescript
player.isPlaying: boolean            // Read-only: playback state
player.currentTime: number           // Current playback position (seconds)
player.duration: number              // Read-only: total duration (seconds)
player.volume: number                // Volume (0–1)
player.effects: EffectState[]        // Read-only: effects chain
player.audioElement: HTMLAudioElement // Read-only: underlying <audio> element
player.theme: DawcoreTheme           // Theme object
```

**Methods:**

```typescript
player.play(): void
player.pause(): void
player.stop(): void
player.seekTo(time: number): void
player.setPlaybackRate(rate: number): void
player.setVolume(volume: number): void
// Effects — same API as editor/track
player.addEffect(type: string, params?: Record<string, number>): string
player.removeEffect(effectId: string): void
player.setEffectParams(effectId: string, params: Record<string, number>): void
player.setEffectBypassed(effectId: string, bypassed: boolean): void
player.moveEffect(effectId: string, newIndex: number): void
```

**Events:**

```typescript
'daw-ready'; // Audio metadata loaded, waveform rendered
'daw-play'; // Playback started
'daw-pause'; // Playback paused
'daw-stop'; // Playback stopped (reset to 0)
'daw-timeupdate'; // Playback time changed (RAF)
'daw-ended'; // Playback reached end of audio
```

**AudioContext lifecycle:** The player uses `HTMLMediaElement` directly — no AudioContext needed for basic playback. When the first effect is added via `addEffect()`, the player lazily creates an AudioContext, connects the `<audio>` element through a `MediaElementAudioSourceNode`, routes through the effects chain, and connects to the destination. This means zero Web Audio overhead for simple playback use cases.

**Children (planned, #477):** `<daw-player>` does not yet render `<daw-annotation-track>` / `<daw-annotation>` children for lyric display, chapter markers, or transcription overlays — only `<daw-editor>` hosts the annotation lane today (see [`<daw-annotation-track>` API](#daw-annotation-track-api)). The markup below is the target shape once #477 lands.

```html
<!-- Simple player -->
<daw-player src="/audio/episode-42.mp3" wave-height="80" timescale></daw-player>

<!-- Player with transport controls (annotation children not yet supported, #477) -->
<daw-player id="my-player" src="/audio/song.mp3" wave-height="64">
  <daw-annotation-track editable>
    <daw-annotation start="0" end="30">Intro</daw-annotation>
    <daw-annotation start="30" end="120">Verse 1</daw-annotation>
    <daw-annotation start="120" end="180">Chorus</daw-annotation>
  </daw-annotation-track>
</daw-player>

<daw-transport for="my-player">
  <daw-play-button></daw-play-button>
  <daw-pause-button></daw-pause-button>
  <daw-stop-button></daw-stop-button>
  <daw-time-display></daw-time-display>
  <daw-playback-rate></daw-playback-rate>
  <daw-volume-slider></daw-volume-slider>
</daw-transport>

<!-- Player with effects (AudioContext created lazily) -->
<script>
  const player = document.querySelector('daw-player');
  player.addEffect('tonejs-reverb', { decay: 3, wet: 0.4 });
  // AudioContext now exists, audio routed through reverb
</script>
```

### Transport Compatibility

`<daw-transport>` works with both `<daw-editor>` and `<daw-player>` via the `for` attribute. Most transport elements work with either target, but some are editor-only:

| Element                     | `<daw-editor>` | `<daw-player>` | Notes                              |
| --------------------------- | :------------: | :------------: | ---------------------------------- |
| `<daw-play-button>`         |      Yes       |      Yes       |                                    |
| `<daw-pause-button>`        |      Yes       |      Yes       |                                    |
| `<daw-stop-button>`         |      Yes       |      Yes       |                                    |
| `<daw-rewind-button>`       |      Yes       |      Yes       |                                    |
| `<daw-fast-forward-button>` |      Yes       |      Yes       |                                    |
| `<daw-time-display>`        |      Yes       |      Yes       |                                    |
| `<daw-volume-slider>`       |      Yes       |      Yes       | Master volume in transport context |
| `<daw-playback-rate>`       |      Yes       |      Yes       |                                    |
| `<daw-undo-button>`         |      Yes       |       No       | Player has no undo stack           |
| `<daw-redo-button>`         |      Yes       |       No       | Player has no undo stack           |
| `<daw-loop-button>`         |      Yes       |       No       | Player has no selection-based loop |
| `<daw-record-button>`       |      Yes       |       No       | Player doesn't support recording   |
| `<daw-selection-start>`     |      Yes       |       No       |                                    |
| `<daw-selection-end>`       |      Yes       |       No       |                                    |
| `<daw-time-format>`         |      Yes       |      Yes       |                                    |
| `<daw-tempo>`               |      Yes       |       No       |                                    |
| `<daw-time-signature>`      |      Yes       |       No       |                                    |
| `<daw-snap-to>`             |      Yes       |       No       |                                    |
| `<daw-scale-mode>`          |      Yes       |       No       |                                    |
| `<daw-zoom-in>`             |      Yes       |       No       | Player has fixed zoom              |
| `<daw-zoom-out>`            |      Yes       |       No       |                                    |

Transport elements that don't apply to `<daw-player>` render as disabled and log a warning to the console on first interaction.

---

## Styling

### CSS Custom Properties (Theme)

Replace styled-components theme with CSS custom properties:

```css
daw-editor {
  --daw-wave-color: #c49a6c;
  --daw-progress-color: #63c75f;
  --daw-playhead-color: #d08070;
  --daw-selection-color: rgba(99, 199, 95, 0.3);
  --daw-background: #1a1a2e;
  --daw-track-background: #16213e;
  --daw-ruler-color: #c49a6c;
  --daw-ruler-background: #0f0f1a;
  --daw-controls-background: #1a1a2e;
  --daw-controls-text: #e0d4c8;
  --daw-controls-width: 180px; /* Track-controls column width */
  --daw-clip-header-background: rgba(0, 0, 0, 0.4);
  --daw-clip-header-text: #e0d4c8;
  --daw-min-height: 200px; /* Min scroll-area height for empty editor / drop zone */
}
```

### CSS Parts (External Styling)

```css
/* Style internal parts from outside */
daw-editor::part(timescale) {
  font-family: 'Courier New';
}
daw-editor::part(track) {
  border-bottom: 1px solid #333;
}
daw-editor::part(cursor) {
  width: 2px;
}
daw-track::part(controls) {
  width: 200px;
}
daw-track::part(waveform) {
  background: #111;
}
daw-vu-meter::part(segment) {
  border-radius: 2px;
}
```

### Slots

> **Hybrid model (decision 2026-06-11):** the shipped default is the composite `<daw-track-controls>` strip, rendered by the editor in the frozen controls column and dispatching a unified `daw-track-control` event (`{trackId, prop, value}`). The `slot="controls"` mechanism and the individual auto-wiring elements below are the power-user path, tracked in epic #457.

```html
<daw-editor>
  <!-- Default slot: tracks -->
  <daw-track src="vocals.mp3" name="Vocals">
    <!-- Named slot: custom track controls -->
    <div slot="controls">
      <daw-volume-slider></daw-volume-slider>
      <daw-pan-slider></daw-pan-slider>
      <button>FX</button>
    </div>
  </daw-track>
</daw-editor>
```

### Custom Controls & Event Bubbling

Slotted content lives in the light DOM and can't access shadow DOM internals directly. Instead of React-style context hooks, custom controls use **DOM event bubbling** — the natural Web Components pattern.

**Built-in control elements** auto-wire to their parent track via `closest()`:

```html
<daw-track src="vocals.mp3" name="Vocals">
  <div slot="controls">
    <daw-mute-button></daw-mute-button>
    <daw-volume-slider></daw-volume-slider>
    <daw-pan-slider></daw-pan-slider>
    <daw-vu-meter></daw-vu-meter>
  </div>
</daw-track>
```

**Custom controls** dispatch bubbling events that any ancestor can handle:

```html
<daw-editor id="my-editor">
  <daw-track src="vocals.mp3" name="Vocals">
    <div slot="controls">
      <daw-volume-slider></daw-volume-slider>
      <button class="fx-btn">FX</button>
      <button class="delete-btn">Delete</button>
    </div>
  </daw-track>
</daw-editor>

<script>
  const editor = document.getElementById('my-editor');

  // Custom events bubble up through the DOM tree.
  // Use composed: true to cross shadow DOM boundaries.
  document.querySelector('.fx-btn').addEventListener('click', (e) => {
    e.target.dispatchEvent(
      new CustomEvent('open-fx', {
        bubbles: true,
        composed: true,
      })
    );
  });

  // Ancestor catches the event — closest() identifies which track
  editor.addEventListener('open-fx', (e) => {
    const track = e.target.closest('daw-track');
    console.log('open FX for', track.getAttribute('name'));
  });

  // Delete track via editor method
  document.querySelector('.delete-btn').addEventListener('click', (e) => {
    const track = e.target.closest('daw-track');
    editor.removeTrack(track.id);
  });
</script>
```

**Built-in elements use the same event contract.** `<daw-mute-button>` dispatches `daw-mute`, `<daw-solo-button>` dispatches `daw-solo` — the parent `<daw-track>` listens and toggles state. Since events keep bubbling, `<daw-editor>` also sees them (needed for solo logic which spans all tracks).

```html
<daw-track src="vocals.mp3" name="Vocals">
  <div slot="controls">
    <!-- Built-in: fires daw-mute event -->
    <daw-mute-button></daw-mute-button>
    <!-- Custom: fires the same event, same behavior -->
    <button
      onclick="this.dispatchEvent(new CustomEvent('daw-mute', { bubbles: true, composed: true }))"
    >
      My Custom Mute
    </button>
  </div>
</daw-track>
```

The track doesn't care what fired the event — any element that dispatches `daw-mute` triggers the same toggle. This makes every built-in control replaceable with a custom implementation.

**Key pattern:** Instead of pulling state down via hooks (React), navigate up via `closest()` and read properties from elements. Elements are the state containers — the DOM tree is the context.

---

## Drag & Drop

**Decision (shipped):** the original plan was `@dnd-kit/dom`. The implementation instead uses **native pointer events** — no drag library at all (`packages/dawcore/src/interactions/`):

- `PointerHandler` — timeline interactions: click-to-seek, drag-to-select, track selection.
- `ClipPointerHandler` — clip move and boundary trim via `setPointerCapture`, with a small `DRAG_THRESHOLD` to distinguish clicks from drags.

Both handlers talk to the engine through narrow contracts (`moveClip`, `trimClip`, `constrainTrimDelta`, `getClipBounds`) so collision and bounds logic stays engine-side, and they wrap each gesture in `beginTransaction()` / `commitTransaction()` so a full drag is one undo step (`abortTransaction()` on cancel). Snapping uses `snapTickToGrid` / `snapToTicks` from `@waveform-playlist/core` driven by the editor's `snapTo` value.

Note for E2E tests: synthetic `dispatchEvent(new PointerEvent(...))` cannot drive these handlers — `setPointerCapture` throws for fabricated pointerIds. Use real input (`page.mouse.*`).

---

## Effects

Effects are **imperative only** — no `<daw-effect>` element. Effects are configuration (how audio sounds), not content (what's in the track). The same API surface is available on both `<daw-editor>` (master chain) and `<daw-track>` (per-track chain).

**Decision (shipped — epics #412/#413/#414):** the original plan was 20 built-in Tone.js effects. The implementation instead ships a small **native Web Audio registry** plus **open plugin standards** (WAM 2.0 and in-browser Faust compilation) for everything richer. No Tone.js dependency in the effects path.

### Effect State

```typescript
interface EffectState {
  id: string; // Generated unique ID
  kind: string; // 'native' | 'wam'
  type: string; // Registry key (e.g., 'native-delay') or 'wam'
  params: Record<string, number>; // Current parameter values
  bypassed: boolean;
  url?: string; // WAM plugin source URL (url-loaded plugins)
  source?: { faust: string }; // Faust entries: the DSP source they were compiled from
  label?: string; // Human-readable name (e.g. a WAM descriptor's name)
  error?: string; // Set when the entry is a non-functional placeholder
}
```

Chain state round-trips via `getEffectsState()` / `setEffectsState()` — native params, WAM plugin state, and Faust sources (recompiled on restore) are all serializable (#424).

### Built-in Effects (native Web Audio)

Built-ins use a `native-` prefix and plain Web Audio nodes:

| Type                   | Label          | Category |
| ---------------------- | -------------- | -------- |
| `native-gain`          | Gain           | dynamics |
| `native-filter`        | Lowpass Filter | filter   |
| `native-compressor`    | Compressor     | dynamics |
| `native-stereo-panner` | Stereo Panner  | spatial  |
| `native-delay`         | Delay          | delay    |

### WAM & Faust Plugins

Richer effects come from plugin standards rather than a large built-in set:

- `addWamPlugin(url, initialState?)` loads a [WAM 2.0](https://www.webaudiomodules.com/) plugin into the chain (optional `@dawcore/wam` peer). Plugin GUIs (`createGui`/`destroyGui`), generic parameter fallback panels, state persistence, and offline export through WAM chains are supported.
- `addFaustEffect(dspCode, { name? })` compiles Faust DSP source in the browser to a WAM (optional `@dawcore/faust` peer).

Chain operations never branch on entry kind — native and plugin entries support the same bypass/reorder/remove/params surface.

### Effect GUIs

Effect editor GUIs are **host-agnostic** — the consumer supplies the container element the panel mounts into. The same two methods are available on both `<daw-editor>` (master chain) and `<daw-track>` (per-track chain):

- `openEffectGui(effectId, container)` mounts the effect's GUI into `container` and resolves with the mounted element. WAM plugins render their own GUI (`createGui`); native effects — and WAM plugins that ship no custom GUI — get a generic parameter panel built from the registry param definitions. A panel edit routes through the same path as `setEffectParams`, so it applies the change AND dispatches `daw-effect-change`.
- `closeEffectGui(effectId)` detaches the panel but **caches** it — reopening remounts the same element, preserving GUI state. The GUI is destroyed only when the effect is removed from the chain. Calling `closeEffectGui` on a never-opened id warns but never throws; an error-placeholder entry refuses to open.

```javascript
// Open a WAM plugin's GUI into your own container element
const panel = document.getElementById('plugin-panel');
await track.openEffectGui(wamId, panel);

// Detach (cached — reopen is cheap and preserves state)
track.closeEffectGui(wamId);
```

### Per-Track Effects by ID (element-less tracks)

The `<daw-track>` element methods above require a `<daw-track>` DOM element. Tracks created **without** one — drag-dropped via `<daw-editor file-drop>`, or `editor.addTrack(...)` when the consumer doesn't hold the returned element — have a `trackId` but no element to call methods on. `<daw-editor>` exposes the same per-track surface addressed by `trackId` so those tracks can carry their own insert chain:

```typescript
editor.addTrackEffect(trackId: string, type: string, params?: Record<string, number>): string
editor.addTrackWamPlugin(trackId: string, url: string, initialState?: unknown): Promise<string>
editor.addTrackFaustEffect(trackId: string, dspCode: string, options?: { name?: string }): Promise<string>
editor.removeTrackEffect(trackId: string, effectId: string): void
editor.setTrackEffectParams(trackId: string, effectId: string, params: Record<string, number>): void
editor.setTrackEffectBypassed(trackId: string, effectId: string, bypassed: boolean): void
editor.moveTrackEffect(trackId: string, effectId: string, newIndex: number): void
editor.trackEffects(trackId: string): EffectState[]
editor.openTrackEffectGui(trackId: string, effectId: string, container: HTMLElement): Promise<HTMLElement>
editor.closeTrackEffectGui(trackId: string, effectId: string): void
editor.getTrackEffectsState(trackId: string): Promise<SerializedEffectEntry[]>
editor.setTrackEffectsState(trackId: string, entries: SerializedEffectEntry[]): Promise<void>
```

`daw-effect-*` events dispatch from the track's `<daw-track>` element when one exists (so they bubble identically to the element-method path), else from the editor for element-less tracks. The `<daw-track>` element methods are thin sugar over these — `track.addEffect(type)` is `editor.addTrackEffect(track.trackId, type)` — so both entry points hit the same chain and fire the same events.

```javascript
// A stem dropped onto <daw-editor file-drop> — no <daw-track> element exists.
editor.addEventListener('daw-track-ready', async (e) => {
  const { trackId } = e.detail;
  await editor.addTrackWamPlugin(trackId, 'https://example.com/plugin/index.js');
});
```

### Effect Registry

Custom native effects register alongside the built-ins:

```typescript
import { registerEffect, getEffectDefinitions } from '@dawcore/components';

registerEffect('my-highpass', {
  label: 'Highpass Filter',
  category: 'filter',
  create: (audioContext, params) => {
    const node = new BiquadFilterNode(audioContext, {
      type: 'highpass',
      frequency: params.frequency,
    });
    return {
      input: node,
      output: node,
      applyParams: (p) => {
        if (p.frequency !== undefined) node.frequency.value = p.frequency;
      },
    };
  },
  defaults: { frequency: 200 },
  params: {
    frequency: { min: 20, max: 2000, step: 1, unit: 'Hz' },
  },
});

// Query available effects (built-in + registered)
const allEffects = getEffectDefinitions();
```

**Registration shapes** (see `packages/dawcore/src/effects/types.ts`):

```typescript
interface EffectDefinition {
  label: string;
  category: string;
  defaults: Record<string, number>;
  params: Record<string, EffectParamDef>;
  wetParam?: string; // Name of the wet/dry param, when the effect has one
  // Must work on any BaseAudioContext so the same definitions serve offline rendering:
  create: (audioContext: BaseAudioContext, params: Record<string, number>) => EffectInstance;
}

interface EffectInstance {
  input: AudioNode; // Chain attachment points (same node for single-node effects)
  output: AudioNode;
  applyParams: (params: Record<string, number>) => void; // In-place — chain never rebuilds for param changes
  dispose?: () => void;
}

interface EffectParamDef {
  min: number;
  max: number;
  step?: number;
  unit?: string; // 's', 'ms', 'Hz', 'dB', '%'
}
```

The built-ins use this same shape internally — `registerEffect` adds to the same map. Calling `addEffect('unknown-type')` throws with a clear error listing available types.

### Usage

```javascript
// Per-track effects
const track = document.querySelector('daw-track[name="Vocals"]');
const delayId = track.addEffect('native-delay', { delayTime: 0.25, feedback: 0.4 });
const filterId = track.addEffect('native-filter', { frequency: 800 });

// Master effects
const compId = editor.addEffect('native-compressor', { threshold: -24, ratio: 4 });

// WAM plugin (optional @dawcore/wam peer)
const wamId = await editor.addWamPlugin('https://example.com/plugin/index.js');

// Faust DSP compiled in the browser (optional @dawcore/faust peer)
const faustId = await editor.addFaustEffect(dspSource, { name: 'My Verb' });

// Real-time parameter updates (no chain rebuild)
track.setEffectParams(delayId, { delayTime: 0.5 });

// Bypass: effects with a wetParam store the original wet and set it to 0;
// effects without one are bypassed by disconnection.
track.setEffectBypassed(delayId, true);
track.setEffectBypassed(delayId, false);

// Reorder and remove
track.moveEffect(filterId, 0); // Move filter before delay
track.removeEffect(filterId);

// Read current state
console.log(track.effects); // EffectState[] (see Effect State above)
console.log(editor.effects); // Master chain, same shape
```

### Effect Events

Events are dispatched from the element that owns the chain. Per-track effect events bubble up to `<daw-editor>`, so you can listen on the editor for all effect changes.

```javascript
// Listen on a specific track
track.addEventListener('daw-effect-add', (e) => {
  console.log('Added', e.detail.type, 'at index', e.detail.index);
});

// Listen on editor to catch ALL effect changes (master + any track)
editor.addEventListener('daw-effect-bypass', (e) => {
  const track = e.target.closest('daw-track');
  if (track) {
    console.log('Track effect bypassed:', track.name, e.detail.effectId);
  } else {
    console.log('Master effect bypassed:', e.detail.effectId);
  }
});
```

### Offline Rendering / WAV Export

`editor.exportAudio()` renders offline through all effect chains (per-track + master), producing identical output to real-time playback:

```typescript
interface ExportOptions {
  format?: 'wav'; // Extensible for future formats
  sampleRate?: number; // Default: audioContext.sampleRate
  startTime?: number; // Default: 0
  duration?: number; // Default: editor.duration
  channels?: 1 | 2; // Default: 2 (stereo)
}
```

```javascript
// Basic export
const buffer = await editor.exportAudio();

// Export selection only
const { start, end } = editor.selection;
const buffer = await editor.exportAudio({
  startTime: start,
  duration: end - start,
});

// Convert to WAV blob for download
const wav = audioBufferToWav(buffer); // utility from @dawcore/core
const url = URL.createObjectURL(new Blob([wav], { type: 'audio/wav' }));
```

---

## Spectrogram & Piano-Roll

Spectrogram and piano-roll are **render modes on `<daw-track>`**, not standalone elements. A track can display as waveform, spectrogram, split (spectrogram + waveform), or piano-roll.

### Render Modes

```html
<!-- Waveform (default) -->
<daw-track src="/audio/vocals.mp3" name="Vocals"></daw-track>

<!-- Spectrogram -->
<daw-track src="/audio/vocals.mp3" name="Vocals" render-mode="spectrogram"></daw-track>

<!-- Split: spectrogram on top, waveform on bottom -->
<daw-track src="/audio/vocals.mp3" name="Vocals" render-mode="split"></daw-track>

<!-- Piano-roll (auto-set for tracks created by loadMidi) -->
<daw-track name="Piano" render-mode="piano-roll"></daw-track>
```

`waveform`, `spectrogram`, and `piano-roll` are shipped. `split` is tracked in #491 — today it warns and falls back to `spectrogram`.

Switchable at runtime:

```js
track.renderMode = 'spectrogram';
// or
track.setAttribute('render-mode', 'spectrogram');
```

### Spectrogram Configuration

Complex object — JS property, not attributes. Global defaults on the editor, per-track overrides on individual tracks.

```typescript
interface SpectrogramConfig {
  fftSize?: 256 | 512 | 1024 | 2048 | 4096 | 8192; // Default: 2048
  hopSize?: number; // Default: fftSize / 4
  windowFunction?: 'hann' | 'hamming' | 'blackman' | 'rectangular' | 'bartlett' | 'blackman-harris';
  frequencyScale?: 'linear' | 'logarithmic' | 'mel' | 'bark' | 'erb'; // Default: 'mel'
  colorMap?: 'viridis' | 'magma' | 'inferno' | 'grayscale' | 'igray' | 'roseus';
  minFrequency?: number; // Default: 0
  maxFrequency?: number; // Default: sampleRate / 2
  gainDb?: number; // Default: 20
  rangeDb?: number; // Default: 80
}
```

```javascript
// Global defaults (all spectrogram/split tracks inherit)
editor.spectrogramConfig = {
  fftSize: 2048,
  frequencyScale: 'mel',
  colorMap: 'viridis',
};

// Per-track override (merged with global)
track.spectrogramConfig = { colorMap: 'magma' };

// Reset to global defaults
track.spectrogramConfig = null;
```

**Worker pool:** Created lazily when the first track uses `'spectrogram'` or `'split'` mode. Disposed when no tracks use those modes. Internal — no consumer-facing pool API.

**Event:**

```typescript
'daw-spectrogram-ready'; // Visible viewport FFT complete: detail: {trackId}
```

Useful for E2E tests and screenshot tooling.

### MIDI Loading

MIDI files are loaded imperatively via `editor.loadMidi()` because a `.mid` file can contain multiple tracks — the track count is unknowable at HTML authoring time.

```typescript
editor.loadMidi(source: string | File, options?: MidiLoadOptions): Promise<MidiLoadResult>

interface MidiLoadOptions {
  /** Timeline position in seconds applied to every created clip (default: 0) */
  startTime?: number;
  /** AbortSignal forwarded to fetch() when source is a URL */
  signal?: AbortSignal;
}

interface MidiLoadResult {
  trackIds: string[];                   // IDs of created <daw-track> elements
  bpm: number;                          // Tempo from MIDI header (or 120)
  timeSignature: [number, number];      // e.g., [4, 4]
  duration: number;                     // Total duration in seconds
  name: string;                         // Song name from header (empty if absent)
}
```

```javascript
// Load multi-track MIDI — creates N <daw-track> elements automatically
const { trackIds, bpm, timeSignature } = await editor.loadMidi('/midi/song.mid');
console.log('Created tracks:', trackIds);

// Apply tempo from MIDI file (caller decides — loadMidi never mutates editor state implicitly)
editor.bpm = bpm;
editor.timeSignature = timeSignature;

// Position on timeline
await editor.loadMidi('/midi/bridge.mid', { startTime: 30.0 });
```

Created tracks get `render-mode="piano-roll"` automatically. Each track's clip carries `midiNotes` data for the piano-roll renderer. Track names are derived from the MIDI file (instrument name, channel, or GM program name).

**Cleanup-on-failure:** if any of the N track creations fails, `loadMidi` removes all successfully-created tracks before rejecting — the editor returns to its pre-call state. Documented limitation: an `AbortSignal` only cancels the fetch phase; aborts during the track-creation phase are a no-op (the in-flight `addTrack` calls run to completion).

**Deferred to future versions:**

- `flatten` option (needs a "hidden audio-only track" primitive in dawcore)
- `name` override (ambiguous semantics with multi-track files)
- Auto-applied tempo / time signature (currently caller does `editor.bpm = result.bpm`)

For programmatic MIDI (no file), set `clip.midiNotes` directly:

```javascript
const track = await editor.addTrack({ name: 'Synth Lead' });
const clip = track.querySelector('daw-clip');
clip.midiNotes = [
  { midi: 60, name: 'C4', time: 0, duration: 0.5, velocity: 0.8 },
  { midi: 64, name: 'E4', time: 0.5, duration: 0.5, velocity: 0.7 },
];
track.renderMode = 'piano-roll';
```

### Piano-Roll Theming

CSS custom properties, consistent with the overall theme system:

```css
daw-editor {
  --daw-piano-roll-note-color: #2a7070;
  --daw-piano-roll-selected-note-color: #3d9e9e;
  --daw-piano-roll-background: #1a1a2e;
}
```

Velocity maps to opacity (0.3 → 1.0). Pitch range auto-fits to actual note data. No JS configuration needed.

---

## Keyboard Shortcuts

Keyboard shortcuts are opt-in via two mechanisms: `<daw-keyboard-shortcuts>` for editor-level shortcuts, and `keyboard-controls` attribute on `<daw-annotation-track>` for annotation shortcuts.

### `<daw-keyboard-shortcuts>` Element

Render-less element placed inside `<daw-editor>`. Enables built-in shortcut presets via boolean attributes and supports custom shortcuts via JS property.

```html
<daw-editor id="my-editor">
  <daw-keyboard-shortcuts playback splitting></daw-keyboard-shortcuts>
  <daw-track src="/audio/vocals.mp3" name="Vocals"></daw-track>
</daw-editor>
```

**Attributes (reflected):**

```
playback         Boolean   false    Space=play/pause, Escape=stop, 0=rewind
splitting        Boolean   false    S=split clip at playhead on selected track
undo             Boolean   false    Cmd/Ctrl+Z=undo, Cmd/Ctrl+Shift+Z=redo
```

**Properties (JS only):**

```typescript
shortcuts.customShortcuts: KeyboardShortcut[]          // Additional custom shortcuts
shortcuts.shortcuts: KeyboardShortcut[]                // Read-only. All active shortcuts (built-in + custom)
shortcuts.playbackShortcuts: PlaybackShortcutMap | null   // Remap playback keys (null = defaults)
shortcuts.splittingShortcuts: SplittingShortcutMap | null  // Remap splitting keys (null = defaults)
```

**Shortcut definition shape:**

```typescript
interface KeyboardShortcut {
  key: string; // 'Space', 's', 'Escape', 'ArrowUp', etc.
  action: () => void; // Callback
  description?: string; // Human-readable label
  ctrlKey?: boolean; // Modifier (optional — if omitted, any state matches)
  shiftKey?: boolean;
  metaKey?: boolean;
  altKey?: boolean;
  preventDefault?: boolean; // Default: true
}

interface KeyBinding {
  key: string;
  ctrlKey?: boolean;
  shiftKey?: boolean;
  metaKey?: boolean;
  altKey?: boolean;
}
```

**Built-in playback shortcuts:**

| Action          | Default Key | Description     |
| --------------- | ----------- | --------------- |
| `playPause`     | `Space`     | Play/Pause      |
| `stop`          | `Escape`    | Stop            |
| `rewindToStart` | `0`         | Rewind to start |

**Built-in splitting shortcuts:**

| Action            | Default Key | Description            |
| ----------------- | ----------- | ---------------------- |
| `splitAtPlayhead` | `S`         | Split clip at playhead |

**Remapping built-in shortcuts:**

```typescript
interface PlaybackShortcutMap {
  playPause?: KeyBinding;
  stop?: KeyBinding;
  rewindToStart?: KeyBinding;
}

interface SplittingShortcutMap {
  splitAtPlayhead?: KeyBinding;
}
```

```javascript
const shortcuts = document.querySelector('daw-keyboard-shortcuts');

// Remap playback keys
shortcuts.playbackShortcuts = {
  playPause: { key: 'p' },
  stop: { key: 'q' },
};

// Add custom shortcuts
shortcuts.customShortcuts = [
  { key: 'c', action: () => editor.stop(), description: 'Clear all' },
  { key: 'Delete', action: () => editor.removeTrack(id), description: 'Delete track' },
];

// Reset to defaults
shortcuts.playbackShortcuts = null;
```

**Behaviors:**

- Ignores key repeat (no rapid toggling from held keys)
- Ignores events from `<input>`, `<textarea>`, and `contentEditable` elements
- Case-insensitive key matching
- First match wins

**Priority rule:** When both `<daw-keyboard-shortcuts>` and `<daw-annotation-track keyboard-controls>` are active, annotation shortcuts run first — the annotation track's `keydown` listener registers on `document` in the **capture** phase, ahead of `<daw-keyboard-shortcuts>`' bubble-phase listener. If an annotation is selected and the key matches an annotation action, the event is consumed via `stopImmediatePropagation()` (also blocks sibling annotation-track capture listeners — see [multi-track arbitration](#daw-annotation-track-api)). Otherwise it falls through to editor-level shortcuts. This means `Escape` clears the annotation selection first; pressing `Escape` again (with no selection) stops playback.

### Annotation Keyboard Controls

Enabled via `keyboard-controls` attribute on `<daw-annotation-track>`. Shortcuts are scoped to the annotation track that owns them — multiple annotation tracks can each have independent keyboard controls.

```html
<daw-annotation-track id="lyrics" editable link-endpoints keyboard-controls>
  <daw-annotation start="0.0" end="2.5">First line</daw-annotation>
  <daw-annotation start="2.5" end="5.1">Second line</daw-annotation>
</daw-annotation-track>
```

**Properties (JS only):**

```typescript
annotationTrack.activeAnnotationId: string | null              // Currently selected annotation
annotationTrack.annotationShortcuts: AnnotationShortcutMap | null  // Key remapping (null = defaults)
```

**Default key bindings:**

| Action             | Default Key                | Description              |
| ------------------ | -------------------------- | ------------------------ |
| `selectPrevious`   | `ArrowUp` / `ArrowLeft`    | Select previous (wraps)  |
| `selectNext`       | `ArrowDown` / `ArrowRight` | Select next (wraps)      |
| `selectFirst`      | `Home`                     | Select first             |
| `selectLast`       | `End`                      | Select last              |
| `clearSelection`   | `Escape`                   | Deselect                 |
| `moveStartEarlier` | `[`                        | Start −10ms              |
| `moveStartLater`   | `]`                        | Start +10ms              |
| `moveEndEarlier`   | `{` (Shift+[)              | End −10ms                |
| `moveEndLater`     | `}` (Shift+])              | End +10ms                |
| `playActive`       | `Enter`                    | Play selected annotation |

**Remapping:**

```typescript
interface AnnotationShortcutMap {
  selectPrevious?: KeyBinding;
  selectNext?: KeyBinding;
  selectFirst?: KeyBinding;
  selectLast?: KeyBinding;
  clearSelection?: KeyBinding;
  moveStartEarlier?: KeyBinding;
  moveStartLater?: KeyBinding;
  moveEndEarlier?: KeyBinding;
  moveEndLater?: KeyBinding;
  playActive?: KeyBinding;
}
```

```javascript
// Remap to vim-style keys (partial — only override what you want)
annotationTrack.annotationShortcuts = {
  selectPrevious: { key: 'k' },
  selectNext: { key: 'j' },
};
```

**Exposed methods** (for programmatic use outside keyboard shortcuts):

```typescript
annotationTrack.selectNext(): void
annotationTrack.selectPrevious(): void
annotationTrack.selectFirst(): void
annotationTrack.selectLast(): void
annotationTrack.clearSelection(): void
annotationTrack.playActive(): void
annotationTrack.moveStartBoundary(deltaMs: number): void
annotationTrack.moveEndBoundary(deltaMs: number): void
```

**Behaviors:**

- Auto-scrolls to center the active annotation on keyboard selection change
- Respects `link-endpoints` — boundary moves cascade to adjacent annotations
- Boundary constraints: minimum 0.1s duration for seconds-based annotations, end cannot exceed timeline duration — unless `<daw-editor indefinite-playback>` is set, which lifts the end bound entirely (DAW-style unbounded timeline) so annotations may extend past the audio. In temporal mode (not beats mode) the timeline width also extends to cover the furthest annotation end, keeping such annotations reachable/scrollable regardless of `indefinite-playback`. Tick-based annotations use a tick-space minimum duration instead: `max(1, round(ppqn / 32))` ticks (a 128th note, floored at 1 tick so it's never zero even at very low PPQN) — boundary math runs entirely in tick space (`ANNOTATION_LINK_THRESHOLD_TICKS` link threshold) so edits stay tempo-independent.
- In `scale-mode="beats"` with `snapTo` set to anything other than `'off'`, dragging a tick-based annotation's boundary snaps the target tick to the grid (`snapTickToGrid`) before applying boundary/link math — same snap behavior as clip drag. Seconds-based annotations and non-drag boundary edits (`moveStartBoundary`/`moveEndBoundary`) never snap.
- Navigation shortcuts always active; boundary editing requires `editable` attribute
- `selectNext`/`selectPrevious` with no active selection jump to the first/last annotation respectively rather than a no-op (see [Navigation with no active selection](#daw-annotation-track-api))
- Multiple `keyboard-controls` tracks: a consumed key acts on the first-registered track only (capture-phase `stopImmediatePropagation` — see [Capture-phase keyboard priority](#daw-annotation-track-api))
- In `scale-mode="beats"` with variable tempo, annotation-box positions can drift from tick-positioned clips/grid (see [Beats-mode variable-tempo limitation](#daw-annotation-track-api))

---

## Programmatic Track Mutation

Two consumer-facing ways to mutate tracks at runtime exist by design: **declarative DOM mutation** (append/remove/update `<daw-track>` and `<daw-clip>` elements) and **imperative editor methods** (`editor.addTrack`, `editor.removeTrack`, `editor.loadFiles`). The engine API (`editor.engine.setTracks`, `editor.engine.addTrack`, …) is **internal plumbing**, not a consumer surface — calling it directly bypasses the descriptor map that backs `<daw-track-controls>` and the peak/buffer caches that back the waveform.

### Engine Lifecycle

`<daw-editor>` builds its `PlaylistEngine` lazily on the first track load. With no children declared and no programmatic load issued, `editor.engine` is `null`. Consumers that need engine access before the first track must:

- Call `editor.loadFiles([...])` (recommended — populates descriptors, peaks, and engine in one shot), **or**
- Append a `<daw-track>` element (any path that triggers `_loadTrack` ensures the engine), **or**
- Use `await editor.ready()` (returns a promise that resolves once the engine is built — used to await engine availability without forcing a track load). When called before any track exists, `ready()` builds an empty engine eagerly.

```javascript
// Engine is null until something loads
console.log(editor.engine); // null

await editor.ready(); // builds engine if needed
console.log(editor.engine); // PlaylistEngine
```

### Declarative DOM Mutation

Appending a `<daw-track>` element to a connected `<daw-editor>` is fully supported. The track element fires a `daw-track-connected` event on `connectedCallback` (deferred via `setTimeout(0)`); the editor reads the descriptor and runs the standard load pipeline.

```javascript
const t = document.createElement('daw-track');
t.setAttribute('src', '/audio/kick.opus');
t.setAttribute('name', 'Kick');
editor.appendChild(t); // → daw-track-ready event fires when loaded
```

Removal works via `element.remove()` — the editor's MutationObserver detects detached `<daw-track>` nodes and cleans up engine state, peaks, and clip buffers. The engine call is incremental (`adapter.removeTrack`) when the adapter supports it; otherwise it falls back to `setTracks()` and stops playback.

**Updating reflected attributes** (`name`, `volume`, `pan`, `muted`, `soloed`, `src`) on a `<daw-track>` after connection fires `daw-track-update`. The editor diffs the new descriptor against the cached one and forwards changes to the engine. Changing `src` re-runs the full load pipeline.

#### Late `<daw-clip>` mutation

`<daw-clip>` dispatches `daw-clip-connected` (deferred via `setTimeout(0)` after construction) and `daw-clip-update` (when reflected attributes change after the initial render). The editor's MutationObserver detects clip removals on the `<daw-track>` subtree.

- Appending a `<daw-clip>` to an already-connected `<daw-track>` triggers an incremental load and appends the clip to the existing track.
- Mutating a `<daw-clip>` attribute (`start`, `offset`, `duration`, `gain`, `name`, `fade-in`, `fade-out`, `fade-type`) after track-connect propagates to the engine via `daw-clip-update`. Re-extracts peaks when `offset`/`duration` change.
- Removing a `<daw-clip>` from the DOM removes it from the engine and cleans up per-clip caches.

Changing `src` on an already-loaded `<daw-clip>` is **not** supported via `daw-clip-update` — remove and re-add the clip instead.

The editor's `daw-track-connected` handler reads all `<daw-clip>` children synchronously via `_readTrackDescriptor` during initial track load; `daw-clip-connected` events fired during that initial pass are skipped (the track loader handles them). Late-append clips (after `_engineTracks` already has the parent track) trigger the incremental path.

### Imperative Editor API

For consumers who can't or won't go through declarative DOM (Vue/Svelte/Angular templates, MIDI sources without a `src` URL, dynamic clip generation):

```typescript
editor.addTrack(config: TrackConfig): Promise<DawTrackElement>
editor.removeTrack(trackId: string): void
editor.updateTrack(trackId: string, partial: Partial<TrackConfig>): void
editor.addClip(trackId: string, config: ClipConfig): Promise<string>      // returns clipId
editor.removeClip(trackId: string, clipId: string): void
editor.updateClip(trackId: string, clipId: string, partial: Partial<ClipConfig>): void

interface TrackConfig {
  name?: string;
  volume?: number;     // 0..1, default 1
  pan?: number;        // -1..1, default 0
  muted?: boolean;
  soloed?: boolean;
  clips?: ClipConfig[];  // omit for empty track
}

interface ClipConfig {
  src?: string;            // URL — fetched + decoded
  audioBuffer?: AudioBuffer; // decoded buffer (skips fetch)
  waveformData?: WaveformDataObject;  // pre-computed peaks (peaks-first render)
  peaksSrc?: string;       // URL for .dat/.json peaks
  midiNotes?: MidiNoteData[]; // for MIDI/piano-roll tracks
  start?: number;          // seconds, default 0
  duration?: number;       // seconds, defaults to source length
  offset?: number;         // seconds, default 0
  gain?: number;           // 0..1+, default 1
  name?: string;
  fadeIn?: number;
  fadeOut?: number;
  fadeType?: FadeType;
}
```

Behavior contract — all methods MUST go through the same path as `_loadTrack` so that:

1. `<daw-track-controls>` shows the correct name/volume/pan/mute/solo (the descriptor map `_tracks` is populated).
2. The waveform renders (peaks generated and cached in `_peaksData`).
3. Drag/trim/split work (audio buffer cached in `_clipBuffers`).
4. The engine lifecycle is honoured (engine built lazily on first call; `daw-track-ready` event fires).

`addTrack` returns a real `<daw-track>` element appended to the editor's light DOM so subsequent declarative mutations work uniformly. The element's `src`/`name`/etc. attributes are reflected from the config.

```javascript
// Plain audio
const t = await editor.addTrack({
  name: 'Drums',
  clips: [{ src: '/audio/drums.opus', start: 0 }],
});
// t is a <daw-track> element — t.trackId is its id

// MIDI (no src, parsed notes provided directly)
await editor.addTrack({
  name: 'Synth',
  clips: [{ midiNotes: parsedNotes, start: 0, duration: 16 }],
});
```

### Why `editor.engine.setTracks(...)` is not a consumer API

The engine owns the playback graph; the editor owns the descriptor map, the DOM elements, the peak cache, and the clip-buffer cache. Calling `engine.setTracks` directly partially works — the `statechange` listener mirrors engine tracks into `_engineTracks` and `syncPeaksForChangedClips` regenerates peaks from any `clip.audioBuffer` attached to the engine clip — so a waveform will render. What stays broken:

- `_tracks` **descriptor map** is not populated. `<daw-track-controls>` falls back to `name='Untitled'`, `volume=1`, `pan=0`, `muted=false`, `soloed=false` — regardless of what the engine track was constructed with. The track's real name and volume are invisible in the controls column.
- `_onTrackControl` (volume slider, mute, solo buttons) early-returns when no descriptor exists, so user interactions on the controls column become silent no-ops.
- `_trackElements` is not populated. `editor.removeTrack(trackId)` falls back to `_onTrackRemoved` directly, but consumers that walk the DOM (`editor.querySelectorAll('daw-track')`) see nothing.

Treat `editor.engine` as **read-only** from consumer code (analyzers, master taps, effect insertions on `engine.masterOutputNode` are fine); mutate tracks via the editor API.

### Backwards-compat surface

`editor.engine` remains exposed for power users who need to wire effects, taps, or analyzers (e.g., `editor.engine.masterOutputNode`). Mutation methods on the engine are out of scope for the documented Web Component API.

---

## File Drop

### Built-in Drop Zone

Enable with the `file-drop` attribute on `<daw-editor>`:

```html
<daw-editor file-drop>
  <daw-track src="/audio/drums.mp3" name="Drums"></daw-track>
</daw-editor>
```

Dropping audio files (`.mp3`, `.wav`, `.ogg`, `.flac`, etc.) creates one new track per file.

**MIDI files in `loadFiles()` is planned, not yet implemented.** Today, drop a `.mid` via the file zone and it will fail at `AudioContext.decodeAudioData()`. Use `editor.loadMidi(file)` directly for MIDI input. See [MIDI Loading](#midi-loading).

### Programmatic File Loading

For custom drop zones, file pickers, or other UIs:

```typescript
editor.loadFiles(files: File[] | FileList): Promise<LoadFilesResult>

interface LoadFilesResult {
  loaded: string[];                                 // Successfully-loaded track IDs (audio only today)
  failed: Array<{ file: File; error: unknown }>;    // Per-file failures
}
```

```javascript
// Custom file picker
const input = document.createElement('input');
input.type = 'file';
input.multiple = true;
input.accept = 'audio/*';
input.onchange = async () => {
  const { loaded, failed } = await editor.loadFiles(input.files);
  console.log('Loaded:', loaded, 'Failed:', failed);
};
input.click();

// MIDI files require a separate call today
const midiInput = document.createElement('input');
midiInput.type = 'file';
midiInput.accept = '.mid,.midi';
midiInput.onchange = async () => {
  const result = await editor.loadMidi(midiInput.files[0]);
  console.log('Loaded MIDI tracks:', result.trackIds);
};
```

**Planned:** unify the two paths so a single `loadFiles()` call accepts mixed audio + MIDI input and routes by extension. Until that lands, callers branch on extension themselves.

### File Type Detection

`loadFiles()` does no upfront MIME type filtering — every file is passed to `AudioContext.decodeAudioData()`. Non-audio files (`.pdf`, `.txt`, `.mid`, etc.) will fail at decode and emit a `daw-files-load-error` event. This is intentional for audio: the browser's decoder is the most reliable detector of valid audio. For MIDI files, route through `editor.loadMidi()` instead.

```typescript
'daw-files-load-error'; // detail: {file: File, error: string}
```

```javascript
editor.addEventListener('daw-files-load-error', (e) => {
  console.warn('Failed to load', e.detail.file.name, ':', e.detail.error);
});
```

---

## Accessibility

> Tracked in epic #456 — not yet implemented. The 2026-06-11 audit found no ARIA roles, live region, or keyboard track navigation in the shipped elements; this section is the target behavior.

All elements render correct ARIA roles, labels, and states in their Shadow DOM automatically. Consumers can override `aria-label` on host elements.

### ARIA Roles & Semantics

**`<daw-editor>`:**

- `role="region"` — preserves standard screen reader browse-mode navigation
- `aria-label="Audio editor"` (default, overridable)
- `aria-roledescription="audio editor"`

**`<daw-track>`:**

- `role="group"`
- `aria-label` derived from `name` attribute (e.g., "Vocals")
- `aria-roledescription="audio track"`
- `aria-selected` reflects track selection state

**`<daw-clip>`:**

- `aria-hidden="true"` — clips are visual representations within the canvas, not keyboard-navigable in this phase

**Transport buttons** (`<daw-play-button>`, `<daw-stop-button>`, etc.):

- Render a native `<button>` in Shadow DOM
- `aria-label` set automatically ("Play", "Pause", "Stop", etc.)
- Toggle buttons (`<daw-loop-button>`, `<daw-mute-button>`, `<daw-solo-button>`, `<daw-record-button>`) — `aria-pressed` reflects toggle state

**`<daw-volume-slider>`, `<daw-pan-slider>`:**

- Render a native `<input type="range">` in Shadow DOM
- `aria-label` set automatically ("Volume", "Pan", or "Track Vocals volume")
- `aria-valuemin`, `aria-valuemax`, `aria-valuenow` reflect current range

**`<daw-time-display>`:**

- `role="status"`
- `aria-label="Playback time"`
- `aria-live="off"` — not announced every frame; screen reader users query on demand

**`<daw-vu-meter>`:**

- `role="meter"` (ARIA 1.2)
- `aria-valuenow`, `aria-valuemin`, `aria-valuemax` reflect current level
- `aria-label` set automatically (e.g., "Vocals level", "Master level")

**`<daw-selection-start>`, `<daw-selection-end>`:**

- Render native `<input>` in Shadow DOM
- `aria-label="Selection start time"` / `aria-label="Selection end time"`

**`<daw-tempo>`, `<daw-time-signature>`, `<daw-time-format>`, `<daw-snap-to>`, `<daw-scale-mode>`:**

- Render native `<input>` or `<select>` in Shadow DOM
- `aria-label` set automatically ("Tempo", "Time signature", "Time format", "Snap to", "Scale mode")

**`<daw-ruler>`, `<daw-playhead>`:**

- `aria-hidden="true"` — visual-only elements, screen readers skip them

**`<daw-annotation-track>` / `<daw-annotation>`:**

- Track: `role="list"`, annotations: `role="listitem"`
- `aria-label` from text content and time range (e.g., "First line, 0.0 to 2.5 seconds")
- `aria-selected` reflects active annotation state

### Keyboard Navigation

Arrow keys navigate between tracks when the editor has focus. Standard Tab order applies within track controls and transport.

| Key         | Action                                                           |
| ----------- | ---------------------------------------------------------------- |
| `ArrowUp`   | Focus previous track                                             |
| `ArrowDown` | Focus next track                                                 |
| `Tab`       | Move focus to next focusable element (controls, then next track) |
| `Shift+Tab` | Move focus backwards                                             |
| `Enter`     | Select focused track                                             |

**Note:** `Space` is reserved for play/pause (via `<daw-keyboard-shortcuts playback>`), not track selection. ArrowUp/Down for track navigation only applies when no `<daw-annotation-track keyboard-controls>` has an active selection — annotation shortcuts take priority per the [Keyboard Shortcuts](#keyboard-shortcuts) priority rule.

**Focus order within a track:**

1. Track itself (group)
2. Track controls slot (volume, pan, mute, solo — standard Tab order)
3. Next track

**Transport focus:** `<daw-transport>` children are standard buttons and inputs — native Tab order applies.

**Focus visibility:** All focusable elements render a visible focus indicator via `:focus-visible` in Shadow DOM, customizable via `::part(focus-ring)`:

```css
daw-track::part(focus-ring) {
  outline: 2px solid #63c75f;
  outline-offset: 2px;
}
```

### Live Region Announcements

`<daw-editor>` renders a visually hidden `aria-live="polite"` region in its Shadow DOM. Rapid state changes coalesce into a single announcement.

**Transport state:**

| Event        | Announcement                  |
| ------------ | ----------------------------- |
| Play         | "Playing"                     |
| Pause        | "Paused"                      |
| Stop         | "Stopped"                     |
| Record start | "Recording on Vocals, Guitar" |
| Record stop  | "Recording stopped"           |

**Track/clip operations:**

| Event                   | Announcement                        |
| ----------------------- | ----------------------------------- |
| Track selected          | "Track Vocals selected"             |
| Track added             | "Track Piano added"                 |
| Track removed           | "Track Piano removed"               |
| Track muted / unmuted   | "Vocals muted" / "Vocals unmuted"   |
| Track soloed / unsoloed | "Vocals soloed" / "Vocals unsoloed" |
| Clip split              | "Clip split at 5.2 seconds"         |
| Record armed            | "Vocals armed for recording"        |
| Loop enabled / disabled | "Loop enabled" / "Loop disabled"    |
| Zoom in / out           | "Zoom: 512 samples per pixel"       |

**Not announced** (query on demand):

- Time updates during playback (continuous, would be noisy)
- Selection changes (visual operation)

### Scope & Deferred Work

Clip drag, boundary trim, and waveform scrubbing remain mouse-only. Keyboard alternatives for pixel-level interactions are deferred to a future accessibility phase.

---

## Undo/Redo

### Scope

Only structural edits are undoable — operations that change the track/clip document model:

| Undoable         | Not Undoable                              |
| ---------------- | ----------------------------------------- |
| Clip move (drop) | Volume, pan, mute, solo                   |
| Clip trim        | Selection changes                         |
| Clip split       | Zoom                                      |
| Add/remove track | Loop region                               |
| Add/remove clip  | Playback transport (play/pause/stop/seek) |

Volume, pan, mute, and solo are live mixing adjustments — non-destructive and instantly reversible by the user. Selection and zoom are navigation, not edits.

### Snapshot-Based Stack

Each undo step stores a frozen copy of `tracks[]` before the operation. Undo restores the previous snapshot; redo re-applies the undone snapshot. No per-operation inverse logic — eliminates a class of bugs from incorrect reverse operations.

The stack has a fixed default limit of **100 steps**, configurable via `engine.undoLimit` or `editor.undoLimit`. When the limit is reached, the oldest entry is dropped.

Any new structural edit clears the redo stack (standard behavior — you can't redo after making a new change). `clearHistory()` is called automatically when tracks are fully replaced via `setTracks()`, since old snapshots reference a different track set.

### Transactions

`beginTransaction()` / `commitTransaction()` groups multiple mutations into a single undo step. One snapshot is captured at `beginTransaction()` and pushed to the stack at `commitTransaction()`.

**Primary use case: drag and drop.** The drag preview calls `moveClip()` on every tick, but only the final drop position should be an undo step:

```javascript
// In the drag handler (e.g., @dnd-kit/dom)
editor.addEventListener('daw-drag-start', () => {
  editor.engine.beginTransaction();
});

editor.addEventListener('daw-drag-end', () => {
  editor.engine.commitTransaction();
  // One undo step captures the net result
});
```

**Multi-step operations:** Transactions also group deliberate multi-step edits:

```javascript
// Split a clip and remove the left half — one undo step
editor.engine.beginTransaction();
editor.engine.splitClip(trackId, clipId, atSample);
editor.engine.removeClip(trackId, leftClipId);
editor.engine.commitTransaction();
```

**Cancellation:** `abortTransaction()` restores the pre-transaction snapshot without pushing to the undo stack. Used for cancelled drags (e.g., Escape key during drag):

```javascript
editor.addEventListener('daw-drag-cancel', () => {
  editor.engine.abortTransaction();
  // State restored, nothing added to undo stack
});
```

### Engine API

```typescript
engine.undo(): void               // Restore previous snapshot
engine.redo(): void               // Re-apply undone snapshot
engine.canUndo: boolean            // Has undo history
engine.canRedo: boolean            // Has redo history
engine.undoLimit: number           // Max stack size (default 100)
engine.clearHistory(): void        // Reset both stacks
engine.beginTransaction(): void    // Start grouping — snapshot captured
engine.commitTransaction(): void   // End grouping — push one step
engine.abortTransaction(): void    // Cancel — restore pre-transaction state
```

### Web Components API

`<daw-editor>` delegates to the engine:

```typescript
// Properties (read-only)
editor.canUndo: boolean
editor.canRedo: boolean

// Properties (read-write)
editor.undoLimit: number

// Methods
editor.undo(): void
editor.redo(): void
editor.clearHistory(): void
```

**Transport elements** (tracked in #466, with `daw-undo-state` and `editor.undoLimit`/`clearHistory()`):

`<daw-undo-button>` and `<daw-redo-button>` auto-wire to the editor via `<daw-transport for="...">`. They reflect disabled state based on `canUndo`/`canRedo`.

```html
<daw-transport for="my-editor">
  <daw-undo-button></daw-undo-button>
  <daw-redo-button></daw-redo-button>
  <daw-play-button></daw-play-button>
  <daw-stop-button></daw-stop-button>
</daw-transport>
```

**Keyboard shortcut preset:**

```html
<daw-editor>
  <daw-keyboard-shortcuts playback splitting undo></daw-keyboard-shortcuts>
</daw-editor>
```

Default bindings:

- **Cmd/Ctrl+Z** — Undo
- **Cmd/Ctrl+Shift+Z** — Redo

Remappable via the `undoShortcuts` property:

```typescript
interface UndoShortcutMap {
  undo?: KeyBinding;
  redo?: KeyBinding;
}
```

### Events

- **`daw-tracks-change`** fires as usual when undo/redo changes tracks (existing event, no special handling needed)
- **`daw-undo-state`** fires when `canUndo` or `canRedo` changes:

```typescript
'daw-undo-state'; // detail: {canUndo: boolean, canRedo: boolean}
```

```javascript
editor.addEventListener('daw-undo-state', (e) => {
  undoBtn.disabled = !e.detail.canUndo;
  redoBtn.disabled = !e.detail.canRedo;
});
```

Note: `<daw-undo-button>` and `<daw-redo-button>` handle this automatically — the event is for custom UI.

### Live Region Announcements

| Action | Announcement |
| ------ | ------------ |
| Undo   | "Undo"       |
| Redo   | "Redo"       |

---

## Framework Usage

All frameworks just need `import '@dawcore/components'` to register the custom elements. No wrapper packages needed.

### Vanilla JS

```html
<script type="module">
  import '@dawcore/components';

  const editor = document.querySelector('daw-editor');
  editor.addEventListener('daw-ready', () => console.log('loaded'));
  editor.addEventListener('daw-record', (e) => {
    console.log('recording', e.detail.trackIds);
  });

  document.querySelector('#play').addEventListener('click', () => {
    editor.play();
  });
</script>

<button id="play">Play</button>
<daw-editor id="my-editor" samples-per-pixel="1024" wave-height="128" timescale>
  <daw-track src="/audio/vocals.mp3" name="Vocals"></daw-track>
  <daw-track src="/audio/guitar.mp3" name="Guitar" record-armed></daw-track>
</daw-editor>
```

### React 19+

React 19+ has native Custom Elements interop — properties are set directly (not stringified to attributes) and custom events work via `onEventName` props. No wrapper package needed. React 18 is not supported.

```tsx
import '@dawcore/components';

function App() {
  const editorRef = useRef<DawEditorElement>(null);

  return (
    <>
      <button onClick={() => editorRef.current?.play()}>Play</button>
      <daw-editor
        ref={editorRef}
        samplesPerPixel={1024}
        waveHeight={128}
        timescale
        onDawReady={() => console.log('loaded')}
        onDawTracksChange={(e) => console.log(e.detail.tracks)}
        onDawRecord={(e) => console.log('recording', e.detail.trackIds)}
      >
        <daw-track src="/audio/vocals.mp3" name="Vocals" />
        <daw-track src="/audio/guitar.mp3" name="Guitar" recordArmed />
      </daw-editor>
    </>
  );
}
```

**JSX type declarations** ship inside `@dawcore/components` so TypeScript knows the valid attributes:

```typescript
// @dawcore/components/jsx.d.ts
declare namespace JSX {
  interface IntrinsicElements {
    'daw-editor': DawEditorAttributes & React.HTMLAttributes<DawEditorElement>;
    'daw-track': DawTrackAttributes & React.HTMLAttributes<DawTrackElement>;
    'daw-transport': DawTransportAttributes & React.HTMLAttributes<HTMLElement>;
    // ... all elements
  }
}
```

### Vue 3

```vue
<template>
  <button @click="play">Play</button>
  <daw-editor
    ref="editorRef"
    :samples-per-pixel="1024"
    :wave-height="128"
    timescale
    @daw-ready="onReady"
    @daw-tracks-change="onTracksChange"
    @daw-record="onRecord"
  >
    <daw-track src="/audio/vocals.mp3" name="Vocals" />
    <daw-track src="/audio/guitar.mp3" name="Guitar" record-armed />
  </daw-editor>
</template>

<script setup>
import '@dawcore/components';
import { ref } from 'vue';

const editorRef = ref(null);
function play() {
  editorRef.value?.play();
}
function onReady() {
  console.log('loaded');
}
function onTracksChange(e) {
  console.log(e.detail.tracks);
}
function onRecord(e) {
  console.log('recording', e.detail.trackIds);
}
</script>
```

One config line tells the Vue compiler which tags are custom elements:

```typescript
// vite.config.ts
vue({ template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith('daw-') } } });
```

### Svelte

```svelte
<script>
  import '@dawcore/components';

  let editorEl;
</script>

<button on:click={() => editorEl?.play()}>Play</button>
<daw-editor
  bind:this={editorEl}
  samplesPerPixel={1024}
  waveHeight={128}
  timescale
  on:daw-ready={() => console.log('loaded')}
  on:daw-tracks-change={(e) => console.log(e.detail.tracks)}
  on:daw-record={(e) => console.log('recording', e.detail.trackIds)}
>
  <daw-track src="/audio/vocals.mp3" name="Vocals" />
  <daw-track src="/audio/guitar.mp3" name="Guitar" record-armed />
</daw-editor>
```

No configuration needed — Svelte treats unknown tags as custom elements automatically.

### Angular

```typescript
// app.module.ts
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}
```

```html
<!-- app.component.html -->
<button (click)="play()">Play</button>
<daw-editor
  #editor
  [attr.samples-per-pixel]="1024"
  [attr.wave-height]="128"
  timescale
  (daw-ready)="onReady()"
  (daw-tracks-change)="onTracksChange($event)"
  (daw-record)="onRecord($event)"
>
  <daw-track src="/audio/vocals.mp3" name="Vocals"></daw-track>
  <daw-track src="/audio/guitar.mp3" name="Guitar" record-armed></daw-track>
</daw-editor>
```

### Framework Compatibility

| Framework  | Properties       | Custom Events        | Config Needed            | Extra Types                       |
| ---------- | ---------------- | -------------------- | ------------------------ | --------------------------------- |
| Vanilla JS | `.property =`    | `addEventListener()` | None                     | None                              |
| React 19+  | Native           | `onDawReady`         | None                     | JSX `IntrinsicElements` (shipped) |
| Vue 3      | `:prop` binding  | `@event`             | `isCustomElement`        | Optional Volar types              |
| Svelte     | `prop={value}`   | `on:event`           | None                     | None                              |
| Angular    | `[prop]` binding | `(event)`            | `CUSTOM_ELEMENTS_SCHEMA` | None                              |

---

## Migration Phases

Checklists updated against the 2026-06-11 code audit. Open items link to their tracking issues.

### Phase 1: Foundation

Create `@dawcore/components` package with core elements:

- [x] `<daw-editor>` — engine lifecycle, track management (adapter-pluggable, #378)
- [x] `<daw-track>` — track declaration via attributes
- [x] `<daw-clip>` — clip element with src/peaks-src, positioning (fades captured but not yet applied — #489)
- [x] Resource cache — URL-keyed dedup for AudioBuffer and peaks across clips
- [x] `<daw-waveform>` — chunked canvas waveform rendering with virtual scrolling
- [x] `<daw-playhead>` — animated playhead
- [x] `<daw-ruler>` — time ruler (virtual scrolling pending — #490)
- [x] CSS custom properties theme system
- [x] Playback: play/pause/stop/seek via element methods
- [x] Recording core: start/stop/pause/resume via editor methods, worklet capture, live waveform preview (arming surface — epic #453)
- [x] Custom events for state changes (recording/track/clip/effect events; `daw-ready` / `daw-timeupdate` / `daw-tracks-change` — #459, #468; `daw-record-arm` — #469)
- [ ] Accessibility — ARIA roles/labels, keyboard track navigation, live region, focus indicators → **epic #456**
- [x] `<daw-player>` — lightweight single-track HTMLMediaElement player → core done (#473); follow-ups: effects (#475), `<daw-playback-rate>` (#476), transport-compat tests (#474), annotations (#477)
- [ ] `<daw-playback-rate>` — playback speed transport element → #476

### Phase 2: Interactions

- [x] Clip drag — native pointer handlers (decision: no @dnd-kit/dom; see Drag & Drop)
- [x] Clip trimming (boundary drag)
- [x] Clip splitting (keyboard shortcut)
- [x] Selection (click + drag on timeline)
- [x] Track selection
- [x] `<daw-transport>` with play/pause/stop/record buttons (remaining button elements — **epic #452**)
- [x] `<daw-keyboard-shortcuts>` — playback/splitting/undo presets, custom shortcuts, key remapping
- [x] File drop — `file-drop` attribute, `loadFiles()` method (MIDI routing — #492)
- [x] Undo/redo — snapshot stack, transactions, keyboard preset (`<daw-undo-button>` / `<daw-redo-button>` + `daw-undo-state` — #466)

### Phase 3: Track Controls

- [x] Track mixing — shipped as the composite `<daw-track-controls>` strip (individual `<daw-volume-slider>` / `<daw-pan-slider>` / `<daw-mute-button>` / `<daw-solo-button>` + `slot="controls"` — **epic #457**; theming vars — #493)
- [ ] `<daw-vu-meter>` → #472
- [ ] `<daw-rewind-button>` / `<daw-fast-forward-button>` → #460
- [ ] `<daw-loop-button>` + editor loop API → #461
- [ ] `<daw-zoom-in>` / `<daw-zoom-out>` → #462
- [x] `<daw-time-display>` / `<daw-time-format>` → #459
- [ ] `<daw-selection-start>` / `<daw-selection-end>` → #463
- [ ] `<daw-tempo>` / `<daw-time-signature>` → #464
- [ ] `<daw-snap-to>` / `<daw-scale-mode>` → #465
- [ ] Master `<daw-volume-slider>` + `setMasterVolume()` → #467
- [x] Effects — imperative API on `<daw-editor>` (master) and `<daw-track>` (per-track)
- [x] Effect registry — native built-ins + `registerEffect()` + WAM/Faust plugins (decision: replaces the `tonejs-*` plan; epics #412–#414)
- [x] Effect bypass, reorder, real-time parameter updates, state persistence
- [x] `exportAudio()` — offline rendering through all effect chains (incl. WAM)

### Phase 4: Optional Features

- [x] `<daw-annotation-track>`, `<daw-annotation>`, `<daw-annotation-list>` → **epic #455**
- [x] Annotation keyboard controls → #480
- [x] Spectrogram render mode (`split` → #491)
- [x] Spectrogram config — editor global + track override, lazy worker pool
- [x] `editor.loadMidi()` — multi-track MIDI loading with cleanup-on-failure
- [x] Piano-roll render mode — `render-mode="piano-roll"`, `clip.midiNotes`
- [x] Piano-roll theming via CSS custom properties
- [ ] Loop region UI → #461

### Phase 5: React 19+ & JSX Types → **epic #458**

- [ ] JSX `IntrinsicElements` type declarations + `HTMLElementTagNameMap` → #486
- [ ] Custom Elements Manifest generation → #487
- [ ] React 19+ example app verifying native Custom Elements interop → #488
- ~~Storybook stories~~ — dropped (decision 2026-06-11): the examples apps and website demos serve the catalog role

### Phase 6: Documentation & Migration Guide

- [x] Getting-started page (`website/docs/web-components/getting-started.md`) + `examples/dawcore-native`, `examples/dawcore-tone`, `examples/dawcore-wam` apps
- [ ] Full Web Components docs (API reference per element, React ↔ WC guide) — carried by the docs IA-restructure plan (Phase 4, "WC integration")
- [ ] Website at dawcore.com — deferred with the repo transfer (see Open Questions)
- ~~Storybook for component catalog~~ — dropped (see Phase 5)

---

## Build & Tooling

| Concern         | Approach                                                                                |
| --------------- | --------------------------------------------------------------------------------------- |
| **Build**       | tsup (same as current packages)                                                         |
| **Types**       | TypeScript; Custom Elements Manifest planned (#487)                                     |
| **CSS**         | CSS custom properties + `::part()` (part exposure tracked in #494)                      |
| **Testing**     | Vitest + happy-dom                                                                      |
| **Drag & Drop** | Native pointer events (`PointerHandler` / `ClipPointerHandler`) — @dnd-kit/dom not used |
| **Docs**        | Docusaurus (existing website)                                                           |

Storybook was dropped from the plan (decision 2026-06-11).

---

## React ↔ Web Components API Map

The React packages are **not** being replaced — both surfaces coexist (see Package Landscape). This table maps React APIs to their Web Components equivalents for consumers moving between them:

| React (`@waveform-playlist/*`)                     | Web Components (`@dawcore/*`)                                                 |
| -------------------------------------------------- | ----------------------------------------------------------------------------- |
| `@waveform-playlist/browser` (React)               | `@dawcore/components` (Web Components)                                        |
| `@waveform-playlist/ui-components` (React)         | Merged into `@dawcore/components`                                             |
| `WaveformPlaylistProvider` (React context)         | `<daw-editor>` element                                                        |
| `usePlaylistControls()`                            | `element.play()`, `element.stop()`, etc.                                      |
| `usePlaylistState()`                               | `element.isPlaying`, `element.selection`, etc.                                |
| `usePlaylistData()`                                | `element.tracks`, `element.duration`, etc.                                    |
| `usePlaybackAnimation()`                           | `daw-timeupdate` event                                                        |
| `onTracksChange` prop                              | `daw-tracks-change` event                                                     |
| styled-components theme                            | CSS custom properties                                                         |
| `@dnd-kit/react`                                   | `@dnd-kit/dom`                                                                |
| `useDynamicEffects()` / `useTrackDynamicEffects()` | `editor.addEffect()` / `track.addEffect()` (imperative)                       |
| `SpectrogramProvider` (React context)              | `render-mode="spectrogram"` attribute + `spectrogramConfig` property          |
| `useMidiTracks()` hook                             | `editor.loadMidi()` method                                                    |
| `<KeyboardShortcuts>` (React component)            | `<daw-keyboard-shortcuts>` element                                            |
| `useAnnotationKeyboardControls()` hook             | `<daw-annotation-track keyboard-controls>` attribute                          |
| `useDynamicTracks()` hook (file/blob loading)      | `editor.loadFiles()` method + `file-drop` attribute                           |
| `useUndoRedo()` hook (planned)                     | `engine.undo()` / `engine.redo()` + `<daw-undo-button>` / `<daw-redo-button>` |
| `MediaElementPlaylistProvider` (React context)     | `<daw-player>` element                                                        |
| `useMediaElementControls()`                        | `player.play()`, `player.pause()`, etc.                                       |

React 19+ users consume `@dawcore/components` directly in JSX — no wrapper package needed. React 18 is not supported.

---

## Open Questions

1. **Lit or vanilla?** — Decided: **Lit**. Adds ~6KB but provides reactive properties, efficient re-rendering, and `@property` decorators. Reduces boilerplate significantly compared to vanilla `HTMLElement` subclasses. Well-maintained by Google, widely adopted, and has first-class Storybook support.
2. **Custom Elements Manifest** — Decided: **yes**. Generate with `@custom-elements-manifest/analyzer` from Lit source. Provides IDE autocomplete (VS Code suggests attributes in HTML) and machine-readable API docs. No manual maintenance — reads `@property()` decorators and JSDoc automatically. Implementation tracked in #487.
3. **Development strategy** — Superseded: the long-lived `feat/dawcore` branch was never used. Development happens via short-lived feature branches merged to `main` as each lands; `@dawcore/*` packages publish 0.x versions from `main` while the React surface continues uninterrupted.
4. **Repo migration** — Deferred. Develop and publish `@dawcore/*` packages from the existing `naomiaro/waveform-playlist` repo for now. Transfer to `dawcore` org later if desired — GitHub's transfer ownership preserves stars, watchers, forks, issues, PRs, and redirects old URLs.