@dawcore/components 0.0.13 → 0.0.15

package/README.md

@@ -13,6 +13,7 @@ Framework-agnostic Web Components for multi-track audio editing. Drop `<daw-edit
 - **File drop** — Drag audio files onto the editor to add tracks
 - **Recording** — Live mic recording with waveform preview, pause/resume, cancelable clip creation
 - **Pre-computed peaks** — Instant waveform rendering from `.dat` files before audio decodes
+- **MIDI tracks** — Programmatic MIDI clips render as piano-roll via `<daw-piano-roll>`. Playback via Tone.js adapter (native MIDI synth deferred). See [MIDI Tracks](#midi-tracks).
 - **Track controls** — Volume, pan, mute, solo per track via `<daw-track-controls>`
 - **Transport access** — Tempo, metronome, count-in, meter, effects via `@dawcore/transport`
 - **CSS theming** — Dark mode by default, fully customizable via CSS custom properties
@@ -92,7 +93,7 @@ adapter.transport.setCountIn(true);
 
 ### Tone.js (effects, MIDI synths)
 
-Uses Tone.js for audio processing. Single tempo/meter only.
+Uses Tone.js for audio processing. Single tempo/meter only. **Required for MIDI playback** — the native adapter has no MIDI synth yet, so MIDI clips render as piano-roll but are silent.
 
 ```bash
 npm install @waveform-playlist/playout tone
@@ -125,6 +126,50 @@ For multiple clips per track with independent positioning:
 </daw-editor>
 ```
 
+## MIDI Tracks
+
+Programmatic MIDI clips render as piano-roll. Playback requires the Tone.js adapter (the native adapter has no MIDI synth yet). Use the `editor.addTrack({ midi })` sugar for the simplest path:
+
+```javascript
+import { createToneAdapter } from '@waveform-playlist/playout';
+
+const editor = document.querySelector('daw-editor');
+editor.adapter = createToneAdapter({ ppqn: 960 });
+
+await editor.addTrack({
+  name: 'Lead',
+  midi: {
+    notes: [
+      { midi: 60, name: 'C4', time: 0.0, duration: 0.5, velocity: 0.8 },
+      { midi: 64, name: 'E4', time: 0.5, duration: 0.5, velocity: 0.7 },
+      { midi: 67, name: 'G4', time: 1.0, duration: 0.5, velocity: 0.8 },
+    ],
+    channel: 0,        // optional — 9 = GM percussion
+    program: 24,       // optional — GM instrument 0-127 (used by SoundFontToneTrack)
+  },
+});
+```
+
+This expands to a `<daw-track render-mode="piano-roll">` containing a `<daw-clip>` whose `midiNotes` JS property is set to the notes array. Equivalent declarative form:
+
+```html
+<daw-track render-mode="piano-roll" name="Lead">
+  <daw-clip midi-channel="0" midi-program="24"></daw-clip>
+</daw-track>
+<script>
+  document.querySelector('daw-clip').midiNotes = [
+    { midi: 60, name: 'C4', time: 0.0, duration: 0.5, velocity: 0.8 },
+    // ...
+  ];
+</script>
+```
+
+A clip is treated as MIDI iff `clip.midiNotes != null`. MIDI clips skip audio fetch + decode + peak generation. Trim handles and split-at-playhead are inert on MIDI clips for now (note slicing is a follow-up). Move drag works.
+
+**Theming:** the piano-roll honors `--daw-piano-roll-note-color` (default `#2a7070`), `--daw-piano-roll-selected-note-color` (default `#3d9e9e`), and `--daw-piano-roll-background` (default `#1a1a2e`).
+
+See `examples/dawcore-tone/midi.html` for a runnable demo (C major scale, PolySynth playback).
+
 ## Pre-Computed Peaks
 
 For instant waveform rendering before audio finishes decoding:
@@ -233,6 +278,9 @@ daw-editor {
   --daw-clip-header-text: #e0d4c8;
   --daw-controls-width: 180px;
   --daw-min-height: 200px;
+  --daw-piano-roll-note-color: #2a7070;
+  --daw-piano-roll-selected-note-color: #3d9e9e;
+  --daw-piano-roll-background: #1a1a2e;
 }
 ```
 
@@ -259,11 +307,15 @@ Methods: `loadFiles(fileList)`, `splitAtPlayhead()`.
 
 ### `<daw-track>`
 
-Declarative track data. Attributes: `src`, `name`, `volume`, `pan`, `muted`, `soloed`, `mono`.
+Declarative track data. Attributes: `src`, `name`, `volume`, `pan`, `muted`, `soloed`, `mono`, `render-mode` (`'waveform' | 'piano-roll'`, default `'waveform'`).
 
 ### `<daw-clip>`
 
-Declarative clip data. Attributes: `src`, `peaks-src`, `start`, `duration`, `offset`, `gain`.
+Declarative clip data. Attributes: `src`, `peaks-src`, `start`, `duration`, `offset`, `gain`, `midi-channel`, `midi-program`. JS-only property: `midiNotes: MidiNoteData[] | null` (note arrays are too large for attributes).
+
+### `<daw-piano-roll>`
+
+Visual element for MIDI note rendering. Mounted automatically when the parent track has `render-mode="piano-roll"` — you don't usually instantiate it directly. See [MIDI Tracks](#midi-tracks).
 
 ### `<daw-transport for="editor-id">`
 

package/dist/index.d.mts

@@ -18,6 +18,9 @@ declare class DawClipElement extends LitElement {
     fadeType: string;
     readonly clipId: `${string}-${string}-${string}-${string}-${string}`;
     createRenderRoot(): this;
+    connectedCallback(): void;
+    private _hasRendered;
+    updated(changed: PropertyValues): void;
 }
 declare global {
     interface HTMLElementTagNameMap {
@@ -201,7 +204,10 @@ interface TrackDescriptor {
     soloed: boolean;
     clips: ClipDescriptor[];
 }
-interface ClipDescriptor {
+/**
+ * Common fields shared by all clip descriptors regardless of source.
+ */
+interface BaseClipDescriptor {
     src: string;
     peaksSrc: string;
     start: number;
@@ -213,6 +219,62 @@ interface ClipDescriptor {
     fadeOut: number;
     fadeType: FadeType;
 }
+/**
+ * A clip descriptor sourced from a `<daw-clip>` DOM element. `clipId` is
+ * always set — `<daw-clip>.clipId` is a `crypto.randomUUID()` generated at
+ * construction. Engine `clip.id` is aligned with this id in `_loadTrack`
+ * and `_loadAndAppendClip` so DOM and engine reference the same clip.
+ */
+interface DomClipDescriptor extends BaseClipDescriptor {
+    kind: 'dom';
+    clipId: string;
+}
+/**
+ * A clip descriptor synthesized from a non-DOM source — file drops, the
+ * `<daw-track src>` shorthand fallback, or recording-clip insertion. No
+ * `clipId` because there's no DOM element to align with; the engine
+ * generates its own id at clip-creation time.
+ */
+interface DropClipDescriptor extends BaseClipDescriptor {
+    kind: 'drop';
+}
+type ClipDescriptor = DomClipDescriptor | DropClipDescriptor;
+/**
+ * Type predicate for the `'dom'` discriminator. Use to narrow a
+ * `ClipDescriptor` to `DomClipDescriptor` (which has `clipId`) without
+ * inline `c.kind === 'dom'` repetition.
+ */
+declare function isDomClip(desc: ClipDescriptor): desc is DomClipDescriptor;
+/**
+ * Public input shape for `editor.addTrack(config)`. All fields optional —
+ * defaults match the declarative `<daw-track>` defaults.
+ */
+interface TrackConfig {
+    name?: string;
+    volume?: number;
+    pan?: number;
+    muted?: boolean;
+    soloed?: boolean;
+    clips?: ClipConfig[];
+}
+/**
+ * Public input shape for clips passed via `TrackConfig.clips` or
+ * `editor.addClip(trackId, config)`. `src` is required — every clip needs
+ * an audio source to load. Other fields default to the matching
+ * `<daw-clip>` attribute defaults.
+ */
+interface ClipConfig {
+    src: string;
+    peaksSrc?: string;
+    start?: number;
+    duration?: number;
+    offset?: number;
+    gain?: number;
+    name?: string;
+    fadeIn?: number;
+    fadeOut?: number;
+    fadeType?: FadeType;
+}
 
 /**
  * Peak generation pipeline: AudioBuffer → web worker → WaveformData → PeakData.
@@ -584,6 +646,23 @@ interface DawRecordingErrorDetail {
     trackId: string;
     error: unknown;
 }
+interface DawClipConnectedDetail {
+    clipId: string;
+    element: DawClipElement;
+}
+interface DawClipIdDetail {
+    trackId: string;
+    clipId: string;
+}
+interface DawClipUpdateDetail {
+    trackId: string;
+    clipId: string;
+}
+interface DawClipErrorDetail {
+    trackId: string;
+    clipId: string;
+    error: unknown;
+}
 interface DawClipMoveDetail {
     readonly trackId: string;
     readonly clipId: string;
@@ -623,6 +702,10 @@ interface DawEventMap {
     'daw-recording-start': CustomEvent<DawRecordingStartDetail>;
     'daw-recording-complete': CustomEvent<DawRecordingCompleteDetail>;
     'daw-recording-error': CustomEvent<DawRecordingErrorDetail>;
+    'daw-clip-connected': CustomEvent<DawClipConnectedDetail>;
+    'daw-clip-update': CustomEvent<DawClipUpdateDetail>;
+    'daw-clip-ready': CustomEvent<DawClipIdDetail>;
+    'daw-clip-error': CustomEvent<DawClipErrorDetail>;
     'daw-clip-move': CustomEvent<DawClipMoveDetail>;
     'daw-clip-trim': CustomEvent<DawClipTrimDetail>;
     'daw-clip-split': CustomEvent<DawClipSplitDetail>;
@@ -649,6 +732,13 @@ declare class DawEditorElement extends LitElement {
     clipHeaders: boolean;
     clipHeaderHeight: number;
     interactiveClips: boolean;
+    /**
+     * When true, the timeline fills the visible viewport even if total clip
+     * duration is less. Lets the ruler render before any audio is loaded —
+     * useful for empty editors and recording UIs. In beats mode the 32-bar
+     * floor already provides this; this attribute controls the temporal mode.
+     */
+    indefinitePlayback: boolean;
     scaleMode: 'temporal' | 'beats';
     get ticksPerPixel(): number;
     set ticksPerPixel(value: number);
@@ -710,10 +800,7 @@ declare class DawEditorElement extends LitElement {
     get engine(): PlaylistEngine | null;
     get renderSamplesPerPixel(): number;
     /** Re-extract peaks for a clip at new offset/duration from cached WaveformData. */
-    reextractClipPeaks(clipId: string, offsetSamples: number, durationSamples: number): {
-        data: Peaks[];
-        length: number;
-    } | null;
+    reextractClipPeaks(clipId: string, offsetSamples: number, durationSamples: number): PeakData | null;
     private _pointer;
     private _viewport;
     static styles: lit.CSSResult[];
@@ -748,6 +835,42 @@ declare class DawEditorElement extends LitElement {
     private static _CONTROL_PROPS;
     private _onTrackControl;
     private _onTrackRemoveRequest;
+    private _onClipConnected;
+    private _onClipUpdate;
+    private _onClipRemovedFromDom;
+    private _loadAndAppendClip;
+    /**
+     * Resolve pre-computed peaks for a clip: fetch the .dat/.json, validate the
+     * sample rate matches the AudioContext, return the WaveformData or null.
+     * Warns on fetch failure and on sample-rate mismatch — never silent.
+     *
+     * Shared between `_loadTrack` (peaks-first preview path) and
+     * `_loadAndAppendClip` (incremental late-append).
+     */
+    private _resolvePeaks;
+    /**
+     * Construct an AudioClip from a decoded buffer (and optional WaveformData),
+     * align its id with the source `<daw-clip>.clipId` when present, populate
+     * `_clipBuffers` / `_clipOffsets`, generate peaks via the worker pipeline,
+     * and populate `_peaksData`. Returns the finished AudioClip.
+     *
+     * Shared between `_loadTrack`'s standard path and `_loadAndAppendClip`.
+     * Not used by `_loadTrack`'s peaks-first preview path because that path
+     * uses sync `extractPeaks` and inserts a preview track BEFORE audio decode.
+     */
+    private _finalizeAudioClip;
+    /** Remove a single clip from all per-clip caches. Used by error rollbacks. */
+    private _purgeClipCaches;
+    /**
+     * Recompute duration and forward an updated track to the engine. Single
+     * source of truth for the incremental-vs-full-rebuild policy used by every
+     * clip-level mutation (addClip, updateClip, removeClip, _applyClipUpdate).
+     * Use the engine's incremental updateTrack when available; otherwise fall
+     * back to full setTracks (legacy adapters).
+     */
+    private _commitTrackChange;
+    private _applyClipUpdate;
+    private _removeClipFromTrack;
     private _readTrackDescriptor;
     private _loadTrack;
     _fetchAndDecode(src: string): Promise<AudioBuffer>;
@@ -760,6 +883,67 @@ declare class DawEditorElement extends LitElement {
     private _onDragLeave;
     private _onDrop;
     loadFiles(files: FileList | File[]): Promise<LoadFilesResult>;
+    /**
+     * Build the engine if it hasn't been built yet. Lets consumers obtain a
+     * non-null `editor.engine` before any track has been loaded — useful for
+     * wiring analyzers, effects, or master taps before content arrives.
+     */
+    ready(): Promise<PlaylistEngine>;
+    /**
+     * Wait for either `readyEvent` or `errorEvent` to fire on this editor for
+     * the entity matching `matchesId`. Listeners are wired synchronously, then
+     * `setup` is called (typical: appendChild). Resolves with `resolveValue`
+     * on ready; rejects with a normalized Error on error. Used by addTrack and
+     * addClip to share their Promise-with-listener-cleanup machinery.
+     */
+    private _awaitId;
+    /**
+     * Append a `<daw-track>` element built from `config` and resolve once the
+     * track finishes loading (or reject on `daw-track-error`). Goes through
+     * the same `_loadTrack` pipeline as declarative tracks, so descriptors,
+     * peaks, and clip buffers are populated correctly.
+     */
+    addTrack(config?: TrackConfig): Promise<DawTrackElement>;
+    /**
+     * Remove a track by id. Equivalent to `trackElement.remove()` —
+     * the editor's MutationObserver handles engine and cache cleanup.
+     * No-op if no matching track exists.
+     */
+    removeTrack(trackId: string): void;
+    /**
+     * Update reflected attributes on a track. For DOM-element tracks the changes
+     * are written to the `<daw-track>` element (which fires `daw-track-update`);
+     * for tracks without a DOM element (file drops) the descriptor and engine
+     * state are updated in place.
+     */
+    updateTrack(trackId: string, partial: Partial<TrackConfig>): void;
+    /**
+     * Append a clip to an existing track. Builds a `<daw-clip>` from `config`
+     * and appends it to the track's DOM element when one exists; resolves with
+     * the new clip's id once the audio decode + peak generation finish.
+     */
+    addClip(trackId: string, config: ClipConfig): Promise<string>;
+    /**
+     * Remove a clip by id. Removes the matching `<daw-clip>` DOM element when
+     * present (MutationObserver handles cleanup); otherwise updates engine
+     * state directly. No-op if no matching clip exists.
+     */
+    removeClip(trackId: string, clipId: string): void;
+    /**
+     * Update a clip's position (start/duration/offset) or properties (gain/name).
+     * For DOM-element clips, writes properties on the `<daw-clip>` element which
+     * fires `daw-clip-update`; otherwise applies directly via `_applyClipUpdate`.
+     *
+     * Re-decoding (changing `src`) is not supported via this method — remove and
+     * re-add the clip instead.
+     *
+     * Note: `fadeIn` / `fadeOut` / `fadeType` on the partial are written to the
+     * `<daw-clip>` element (so they round-trip in the descriptor), but engine-side
+     * fade application from `<daw-clip>` properties is not yet implemented — see
+     * the broader fade-engine integration tracked separately.
+     */
+    updateClip(trackId: string, clipId: string, partial: Partial<ClipConfig>): void;
+    private _buildClipElement;
     play(startTime?: number): Promise<void>;
     pause(): void;
     stop(): void;
@@ -965,4 +1149,4 @@ interface SplitHost {
  */
 declare function splitAtPlayhead(host: SplitHost): boolean;
 
-export { AudioResumeController, type ClipDescriptor, type ClipEngineContract, ClipPointerHandler, type ClipPointerHost, DawClipElement, type DawClipMoveDetail, type DawClipSplitDetail, type DawClipTrimDetail, DawEditorElement, type DawErrorDetail, type DawEvent, type DawEventMap, type DawFilesLoadErrorDetail, DawGridElement, DawKeyboardShortcutsElement, DawPauseButtonElement, DawPlayButtonElement, DawPlayheadElement, DawRecordButtonElement, type DawRecordingCompleteDetail, type DawRecordingErrorDetail, type DawRecordingStartDetail, DawRulerElement, type DawSeekDetail, type DawSelectionDetail, DawSelectionElement, DawStopButtonElement, type DawTrackConnectedDetail, type DawTrackControlDetail, DawTrackControlsElement, DawTrackElement, type DawTrackErrorDetail, type DawTrackIdDetail, type DawTrackRemoveDetail, type DawTrackSelectDetail, DawTransportButton, DawTransportElement, DawWaveformElement, type KeyBinding, type LoadFilesResult, type PlaybackShortcutMap, type PointerEngineContract, RecordingController, type RecordingOptions, type RecordingSession, type SplitEngineContract, type SplitHost, type SplittingShortcutMap, type TrackDescriptor, type UndoShortcutMap, type WaveformSegment, splitAtPlayhead };
+export { AudioResumeController, type ClipConfig, type ClipDescriptor, type ClipEngineContract, ClipPointerHandler, type ClipPointerHost, type DawClipConnectedDetail, DawClipElement, type DawClipErrorDetail, type DawClipIdDetail, type DawClipMoveDetail, type DawClipSplitDetail, type DawClipTrimDetail, type DawClipUpdateDetail, DawEditorElement, type DawErrorDetail, type DawEvent, type DawEventMap, type DawFilesLoadErrorDetail, DawGridElement, DawKeyboardShortcutsElement, DawPauseButtonElement, DawPlayButtonElement, DawPlayheadElement, DawRecordButtonElement, type DawRecordingCompleteDetail, type DawRecordingErrorDetail, type DawRecordingStartDetail, DawRulerElement, type DawSeekDetail, type DawSelectionDetail, DawSelectionElement, DawStopButtonElement, type DawTrackConnectedDetail, type DawTrackControlDetail, DawTrackControlsElement, DawTrackElement, type DawTrackErrorDetail, type DawTrackIdDetail, type DawTrackRemoveDetail, type DawTrackSelectDetail, DawTransportButton, DawTransportElement, DawWaveformElement, type DomClipDescriptor, type DropClipDescriptor, type KeyBinding, type LoadFilesResult, type PlaybackShortcutMap, type PointerEngineContract, RecordingController, type RecordingOptions, type RecordingSession, type SplitEngineContract, type SplitHost, type SplittingShortcutMap, type TrackConfig, type TrackDescriptor, type UndoShortcutMap, type WaveformSegment, isDomClip, splitAtPlayhead };

package/dist/index.d.ts

@@ -18,6 +18,9 @@ declare class DawClipElement extends LitElement {
     fadeType: string;
     readonly clipId: `${string}-${string}-${string}-${string}-${string}`;
     createRenderRoot(): this;
+    connectedCallback(): void;
+    private _hasRendered;
+    updated(changed: PropertyValues): void;
 }
 declare global {
     interface HTMLElementTagNameMap {
@@ -201,7 +204,10 @@ interface TrackDescriptor {
     soloed: boolean;
     clips: ClipDescriptor[];
 }
-interface ClipDescriptor {
+/**
+ * Common fields shared by all clip descriptors regardless of source.
+ */
+interface BaseClipDescriptor {
     src: string;
     peaksSrc: string;
     start: number;
@@ -213,6 +219,62 @@ interface ClipDescriptor {
     fadeOut: number;
     fadeType: FadeType;
 }
+/**
+ * A clip descriptor sourced from a `<daw-clip>` DOM element. `clipId` is
+ * always set — `<daw-clip>.clipId` is a `crypto.randomUUID()` generated at
+ * construction. Engine `clip.id` is aligned with this id in `_loadTrack`
+ * and `_loadAndAppendClip` so DOM and engine reference the same clip.
+ */
+interface DomClipDescriptor extends BaseClipDescriptor {
+    kind: 'dom';
+    clipId: string;
+}
+/**
+ * A clip descriptor synthesized from a non-DOM source — file drops, the
+ * `<daw-track src>` shorthand fallback, or recording-clip insertion. No
+ * `clipId` because there's no DOM element to align with; the engine
+ * generates its own id at clip-creation time.
+ */
+interface DropClipDescriptor extends BaseClipDescriptor {
+    kind: 'drop';
+}
+type ClipDescriptor = DomClipDescriptor | DropClipDescriptor;
+/**
+ * Type predicate for the `'dom'` discriminator. Use to narrow a
+ * `ClipDescriptor` to `DomClipDescriptor` (which has `clipId`) without
+ * inline `c.kind === 'dom'` repetition.
+ */
+declare function isDomClip(desc: ClipDescriptor): desc is DomClipDescriptor;
+/**
+ * Public input shape for `editor.addTrack(config)`. All fields optional —
+ * defaults match the declarative `<daw-track>` defaults.
+ */
+interface TrackConfig {
+    name?: string;
+    volume?: number;
+    pan?: number;
+    muted?: boolean;
+    soloed?: boolean;
+    clips?: ClipConfig[];
+}
+/**
+ * Public input shape for clips passed via `TrackConfig.clips` or
+ * `editor.addClip(trackId, config)`. `src` is required — every clip needs
+ * an audio source to load. Other fields default to the matching
+ * `<daw-clip>` attribute defaults.
+ */
+interface ClipConfig {
+    src: string;
+    peaksSrc?: string;
+    start?: number;
+    duration?: number;
+    offset?: number;
+    gain?: number;
+    name?: string;
+    fadeIn?: number;
+    fadeOut?: number;
+    fadeType?: FadeType;
+}
 
 /**
  * Peak generation pipeline: AudioBuffer → web worker → WaveformData → PeakData.
@@ -584,6 +646,23 @@ interface DawRecordingErrorDetail {
     trackId: string;
     error: unknown;
 }
+interface DawClipConnectedDetail {
+    clipId: string;
+    element: DawClipElement;
+}
+interface DawClipIdDetail {
+    trackId: string;
+    clipId: string;
+}
+interface DawClipUpdateDetail {
+    trackId: string;
+    clipId: string;
+}
+interface DawClipErrorDetail {
+    trackId: string;
+    clipId: string;
+    error: unknown;
+}
 interface DawClipMoveDetail {
     readonly trackId: string;
     readonly clipId: string;
@@ -623,6 +702,10 @@ interface DawEventMap {
     'daw-recording-start': CustomEvent<DawRecordingStartDetail>;
     'daw-recording-complete': CustomEvent<DawRecordingCompleteDetail>;
     'daw-recording-error': CustomEvent<DawRecordingErrorDetail>;
+    'daw-clip-connected': CustomEvent<DawClipConnectedDetail>;
+    'daw-clip-update': CustomEvent<DawClipUpdateDetail>;
+    'daw-clip-ready': CustomEvent<DawClipIdDetail>;
+    'daw-clip-error': CustomEvent<DawClipErrorDetail>;
     'daw-clip-move': CustomEvent<DawClipMoveDetail>;
     'daw-clip-trim': CustomEvent<DawClipTrimDetail>;
     'daw-clip-split': CustomEvent<DawClipSplitDetail>;
@@ -649,6 +732,13 @@ declare class DawEditorElement extends LitElement {
     clipHeaders: boolean;
     clipHeaderHeight: number;
     interactiveClips: boolean;
+    /**
+     * When true, the timeline fills the visible viewport even if total clip
+     * duration is less. Lets the ruler render before any audio is loaded —
+     * useful for empty editors and recording UIs. In beats mode the 32-bar
+     * floor already provides this; this attribute controls the temporal mode.
+     */
+    indefinitePlayback: boolean;
     scaleMode: 'temporal' | 'beats';
     get ticksPerPixel(): number;
     set ticksPerPixel(value: number);
@@ -710,10 +800,7 @@ declare class DawEditorElement extends LitElement {
     get engine(): PlaylistEngine | null;
     get renderSamplesPerPixel(): number;
     /** Re-extract peaks for a clip at new offset/duration from cached WaveformData. */
-    reextractClipPeaks(clipId: string, offsetSamples: number, durationSamples: number): {
-        data: Peaks[];
-        length: number;
-    } | null;
+    reextractClipPeaks(clipId: string, offsetSamples: number, durationSamples: number): PeakData | null;
     private _pointer;
     private _viewport;
     static styles: lit.CSSResult[];
@@ -748,6 +835,42 @@ declare class DawEditorElement extends LitElement {
     private static _CONTROL_PROPS;
     private _onTrackControl;
     private _onTrackRemoveRequest;
+    private _onClipConnected;
+    private _onClipUpdate;
+    private _onClipRemovedFromDom;
+    private _loadAndAppendClip;
+    /**
+     * Resolve pre-computed peaks for a clip: fetch the .dat/.json, validate the
+     * sample rate matches the AudioContext, return the WaveformData or null.
+     * Warns on fetch failure and on sample-rate mismatch — never silent.
+     *
+     * Shared between `_loadTrack` (peaks-first preview path) and
+     * `_loadAndAppendClip` (incremental late-append).
+     */
+    private _resolvePeaks;
+    /**
+     * Construct an AudioClip from a decoded buffer (and optional WaveformData),
+     * align its id with the source `<daw-clip>.clipId` when present, populate
+     * `_clipBuffers` / `_clipOffsets`, generate peaks via the worker pipeline,
+     * and populate `_peaksData`. Returns the finished AudioClip.
+     *
+     * Shared between `_loadTrack`'s standard path and `_loadAndAppendClip`.
+     * Not used by `_loadTrack`'s peaks-first preview path because that path
+     * uses sync `extractPeaks` and inserts a preview track BEFORE audio decode.
+     */
+    private _finalizeAudioClip;
+    /** Remove a single clip from all per-clip caches. Used by error rollbacks. */
+    private _purgeClipCaches;
+    /**
+     * Recompute duration and forward an updated track to the engine. Single
+     * source of truth for the incremental-vs-full-rebuild policy used by every
+     * clip-level mutation (addClip, updateClip, removeClip, _applyClipUpdate).
+     * Use the engine's incremental updateTrack when available; otherwise fall
+     * back to full setTracks (legacy adapters).
+     */
+    private _commitTrackChange;
+    private _applyClipUpdate;
+    private _removeClipFromTrack;
     private _readTrackDescriptor;
     private _loadTrack;
     _fetchAndDecode(src: string): Promise<AudioBuffer>;
@@ -760,6 +883,67 @@ declare class DawEditorElement extends LitElement {
     private _onDragLeave;
     private _onDrop;
     loadFiles(files: FileList | File[]): Promise<LoadFilesResult>;
+    /**
+     * Build the engine if it hasn't been built yet. Lets consumers obtain a
+     * non-null `editor.engine` before any track has been loaded — useful for
+     * wiring analyzers, effects, or master taps before content arrives.
+     */
+    ready(): Promise<PlaylistEngine>;
+    /**
+     * Wait for either `readyEvent` or `errorEvent` to fire on this editor for
+     * the entity matching `matchesId`. Listeners are wired synchronously, then
+     * `setup` is called (typical: appendChild). Resolves with `resolveValue`
+     * on ready; rejects with a normalized Error on error. Used by addTrack and
+     * addClip to share their Promise-with-listener-cleanup machinery.
+     */
+    private _awaitId;
+    /**
+     * Append a `<daw-track>` element built from `config` and resolve once the
+     * track finishes loading (or reject on `daw-track-error`). Goes through
+     * the same `_loadTrack` pipeline as declarative tracks, so descriptors,
+     * peaks, and clip buffers are populated correctly.
+     */
+    addTrack(config?: TrackConfig): Promise<DawTrackElement>;
+    /**
+     * Remove a track by id. Equivalent to `trackElement.remove()` —
+     * the editor's MutationObserver handles engine and cache cleanup.
+     * No-op if no matching track exists.
+     */
+    removeTrack(trackId: string): void;
+    /**
+     * Update reflected attributes on a track. For DOM-element tracks the changes
+     * are written to the `<daw-track>` element (which fires `daw-track-update`);
+     * for tracks without a DOM element (file drops) the descriptor and engine
+     * state are updated in place.
+     */
+    updateTrack(trackId: string, partial: Partial<TrackConfig>): void;
+    /**
+     * Append a clip to an existing track. Builds a `<daw-clip>` from `config`
+     * and appends it to the track's DOM element when one exists; resolves with
+     * the new clip's id once the audio decode + peak generation finish.
+     */
+    addClip(trackId: string, config: ClipConfig): Promise<string>;
+    /**
+     * Remove a clip by id. Removes the matching `<daw-clip>` DOM element when
+     * present (MutationObserver handles cleanup); otherwise updates engine
+     * state directly. No-op if no matching clip exists.
+     */
+    removeClip(trackId: string, clipId: string): void;
+    /**
+     * Update a clip's position (start/duration/offset) or properties (gain/name).
+     * For DOM-element clips, writes properties on the `<daw-clip>` element which
+     * fires `daw-clip-update`; otherwise applies directly via `_applyClipUpdate`.
+     *
+     * Re-decoding (changing `src`) is not supported via this method — remove and
+     * re-add the clip instead.
+     *
+     * Note: `fadeIn` / `fadeOut` / `fadeType` on the partial are written to the
+     * `<daw-clip>` element (so they round-trip in the descriptor), but engine-side
+     * fade application from `<daw-clip>` properties is not yet implemented — see
+     * the broader fade-engine integration tracked separately.
+     */
+    updateClip(trackId: string, clipId: string, partial: Partial<ClipConfig>): void;
+    private _buildClipElement;
     play(startTime?: number): Promise<void>;
     pause(): void;
     stop(): void;
@@ -965,4 +1149,4 @@ interface SplitHost {
  */
 declare function splitAtPlayhead(host: SplitHost): boolean;
 
-export { AudioResumeController, type ClipDescriptor, type ClipEngineContract, ClipPointerHandler, type ClipPointerHost, DawClipElement, type DawClipMoveDetail, type DawClipSplitDetail, type DawClipTrimDetail, DawEditorElement, type DawErrorDetail, type DawEvent, type DawEventMap, type DawFilesLoadErrorDetail, DawGridElement, DawKeyboardShortcutsElement, DawPauseButtonElement, DawPlayButtonElement, DawPlayheadElement, DawRecordButtonElement, type DawRecordingCompleteDetail, type DawRecordingErrorDetail, type DawRecordingStartDetail, DawRulerElement, type DawSeekDetail, type DawSelectionDetail, DawSelectionElement, DawStopButtonElement, type DawTrackConnectedDetail, type DawTrackControlDetail, DawTrackControlsElement, DawTrackElement, type DawTrackErrorDetail, type DawTrackIdDetail, type DawTrackRemoveDetail, type DawTrackSelectDetail, DawTransportButton, DawTransportElement, DawWaveformElement, type KeyBinding, type LoadFilesResult, type PlaybackShortcutMap, type PointerEngineContract, RecordingController, type RecordingOptions, type RecordingSession, type SplitEngineContract, type SplitHost, type SplittingShortcutMap, type TrackDescriptor, type UndoShortcutMap, type WaveformSegment, splitAtPlayhead };
+export { AudioResumeController, type ClipConfig, type ClipDescriptor, type ClipEngineContract, ClipPointerHandler, type ClipPointerHost, type DawClipConnectedDetail, DawClipElement, type DawClipErrorDetail, type DawClipIdDetail, type DawClipMoveDetail, type DawClipSplitDetail, type DawClipTrimDetail, type DawClipUpdateDetail, DawEditorElement, type DawErrorDetail, type DawEvent, type DawEventMap, type DawFilesLoadErrorDetail, DawGridElement, DawKeyboardShortcutsElement, DawPauseButtonElement, DawPlayButtonElement, DawPlayheadElement, DawRecordButtonElement, type DawRecordingCompleteDetail, type DawRecordingErrorDetail, type DawRecordingStartDetail, DawRulerElement, type DawSeekDetail, type DawSelectionDetail, DawSelectionElement, DawStopButtonElement, type DawTrackConnectedDetail, type DawTrackControlDetail, DawTrackControlsElement, DawTrackElement, type DawTrackErrorDetail, type DawTrackIdDetail, type DawTrackRemoveDetail, type DawTrackSelectDetail, DawTransportButton, DawTransportElement, DawWaveformElement, type DomClipDescriptor, type DropClipDescriptor, type KeyBinding, type LoadFilesResult, type PlaybackShortcutMap, type PointerEngineContract, RecordingController, type RecordingOptions, type RecordingSession, type SplitEngineContract, type SplitHost, type SplittingShortcutMap, type TrackConfig, type TrackDescriptor, type UndoShortcutMap, type WaveformSegment, isDomClip, splitAtPlayhead };