@dawcore/components 0.0.18 → 0.0.20

package/dist/index.d.mts

@@ -1,13 +1,20 @@
 import * as lit from 'lit';
 import { LitElement, PropertyValues, ReactiveController, ReactiveControllerHost } from 'lit';
-import { MidiNoteData, SpectrogramConfig, FadeType, Peaks, Bits, PeakData, MeterEntry, SnapTo, ColorMapValue, ClipTrack, KeyboardShortcut } from '@waveform-playlist/core';
+import { MidiNoteData, RenderMode, SpectrogramConfig, Peaks, Bits, FadeType, PeakData, MeterEntry, SnapTo, ColorMapValue, ClipTrack, KeyboardShortcut } from '@waveform-playlist/core';
 import WaveformData from 'waveform-data';
 import { PlayoutAdapter, PlaylistEngine } from '@waveform-playlist/engine';
+import { MidiLoadOptions, MidiLoadResult } from '@dawcore/midi';
 import { ClipRegistration, CanvasRegistration, ViewportState } from '@dawcore/spectrogram';
 
 declare class DawClipElement extends LitElement {
     src: string;
     peaksSrc: string;
+    /**
+     * Timeline position in seconds. JS property only — NOT reflected to the
+     * `start` attribute (Lit's `reflect` defaults to false). Tests that need
+     * to assert clip position must read this property directly; reading
+     * `el.getAttribute('start')` returns `null` regardless of correctness.
+     */
     start: number;
     duration: number;
     offset: number;
@@ -39,113 +46,6 @@ declare global {
     }
 }
 
-type TrackRenderMode = 'waveform' | 'piano-roll' | 'spectrogram';
-interface TrackDescriptor {
-    name: string;
-    src: string;
-    volume: number;
-    pan: number;
-    muted: boolean;
-    soloed: boolean;
-    renderMode: TrackRenderMode;
-    spectrogramConfig?: SpectrogramConfig | null;
-    clips: ClipDescriptor[];
-}
-/**
- * Common fields shared by all clip descriptors regardless of source.
- */
-interface BaseClipDescriptor {
-    src: string;
-    peaksSrc: string;
-    start: number;
-    duration: number;
-    offset: number;
-    gain: number;
-    name: string;
-    fadeIn: number;
-    fadeOut: number;
-    fadeType: FadeType;
-    midiNotes: MidiNoteData[] | null;
-    midiChannel: number | null;
-    midiProgram: number | null;
-}
-/**
- * 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;
-    renderMode?: TrackRenderMode;
-    spectrogramConfig?: SpectrogramConfig | null;
-    clips?: ClipConfig[];
-    /**
-     * Convenience: creates a single piano-roll `<daw-clip>` child with these
-     * notes and sets `render-mode="piano-roll"` on the track. Equivalent to
-     * passing `{ renderMode: 'piano-roll', clips: [{ midiNotes, midiChannel, midiProgram }] }`.
-     * An explicit `renderMode` takes precedence over the inferred `'piano-roll'`.
-     *
-     * Creation-only — ignored by `updateTrack`. To modify notes after the
-     * track is built, use `editor.updateClip(trackId, clipId, { midiNotes })` or
-     * mutate the `<daw-clip>` element's `midiNotes` property directly.
-     */
-    midi?: {
-        notes: MidiNoteData[];
-        channel?: number;
-        program?: number;
-    };
-}
-/**
- * Public input shape for clips passed via `TrackConfig.clips` or
- * `editor.addClip(trackId, config)`. `src` is optional to support MIDI clips
- * with no audio source. 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;
-    midiNotes?: MidiNoteData[];
-    midiChannel?: number;
-    midiProgram?: number;
-}
-
 declare class DawTrackElement extends LitElement {
     src: string;
     name: string;
@@ -153,7 +53,9 @@ declare class DawTrackElement extends LitElement {
     pan: number;
     muted: boolean;
     soloed: boolean;
-    renderMode: TrackRenderMode;
+    get renderMode(): RenderMode;
+    set renderMode(value: RenderMode);
+    private _renderMode;
     spectrogramConfig: SpectrogramConfig | null;
     readonly trackId: `${string}-${string}-${string}-${string}-${string}`;
     createRenderRoot(): this;
@@ -353,6 +255,113 @@ declare global {
     }
 }
 
+type TrackRenderMode = RenderMode;
+interface TrackDescriptor {
+    name: string;
+    src: string;
+    volume: number;
+    pan: number;
+    muted: boolean;
+    soloed: boolean;
+    renderMode: TrackRenderMode;
+    spectrogramConfig?: SpectrogramConfig | null;
+    clips: ClipDescriptor[];
+}
+/**
+ * Common fields shared by all clip descriptors regardless of source.
+ */
+interface BaseClipDescriptor {
+    src: string;
+    peaksSrc: string;
+    start: number;
+    duration: number;
+    offset: number;
+    gain: number;
+    name: string;
+    fadeIn: number;
+    fadeOut: number;
+    fadeType: FadeType;
+    midiNotes: MidiNoteData[] | null;
+    midiChannel: number | null;
+    midiProgram: number | null;
+}
+/**
+ * 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;
+    renderMode?: TrackRenderMode;
+    spectrogramConfig?: SpectrogramConfig | null;
+    clips?: ClipConfig[];
+    /**
+     * Convenience: creates a single piano-roll `<daw-clip>` child with these
+     * notes and sets `render-mode="piano-roll"` on the track. Equivalent to
+     * passing `{ renderMode: 'piano-roll', clips: [{ midiNotes, midiChannel, midiProgram }] }`.
+     * An explicit `renderMode` takes precedence over the inferred `'piano-roll'`.
+     *
+     * Creation-only — ignored by `updateTrack`. To modify notes after the
+     * track is built, use `editor.updateClip(trackId, clipId, { midiNotes })` or
+     * mutate the `<daw-clip>` element's `midiNotes` property directly.
+     */
+    midi?: {
+        notes: MidiNoteData[];
+        channel?: number;
+        program?: number;
+    };
+}
+/**
+ * Public input shape for clips passed via `TrackConfig.clips` or
+ * `editor.addClip(trackId, config)`. `src` is optional to support MIDI clips
+ * with no audio source. 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;
+    midiNotes?: MidiNoteData[];
+    midiChannel?: number;
+    midiProgram?: number;
+}
+
 /**
  * Peak generation pipeline: AudioBuffer → web worker → WaveformData → PeakData.
  *
@@ -785,6 +794,12 @@ interface DawClipSplitDetail {
 }
 interface DawSpectrogramReadyDetail {
     trackId: string;
+    generation: number;
+}
+interface DawSpectrogramErrorDetail {
+    trackId: string;
+    generation: number;
+    error: Error;
 }
 interface DawEventMap {
     'daw-selection': CustomEvent<DawSelectionDetail>;
@@ -814,6 +829,7 @@ interface DawEventMap {
     'daw-clip-trim': CustomEvent<DawClipTrimDetail>;
     'daw-clip-split': CustomEvent<DawClipSplitDetail>;
     'daw-spectrogram-ready': CustomEvent<DawSpectrogramReadyDetail>;
+    'daw-spectrogram-error': CustomEvent<DawSpectrogramErrorDetail>;
 }
 type DawEvent<K extends keyof DawEventMap> = DawEventMap[K];
 interface LoadFilesResult {
@@ -824,7 +840,29 @@ interface LoadFilesResult {
     }>;
 }
 
-declare class DawEditorElement extends LitElement {
+/**
+ * MIDI loading logic extracted from daw-editor. Operates on the editor via a
+ * narrow host interface (`addTrack` + `querySelectorAll`) — `<daw-editor>`
+ * satisfies it without any new public surface.
+ *
+ * Numbered steps below match the Data Flow diagram in
+ * `docs/specs/2026-05-23-dawcore-load-midi-design.md`.
+ */
+
+/**
+ * Minimal host surface needed by `loadMidiImpl`. `<daw-editor>` satisfies this
+ * structurally. `querySelectorAll` is needed for cleanup-on-failure so the
+ * loader can identify `<daw-track>` elements appended during this call (both
+ * those whose `addTrack` resolved and those that rejected after `_loadTrack`
+ * fired `daw-track-error` — the latter aren't in the `addTrack` resolution
+ * value, so we need DOM observation to find them).
+ */
+interface MidiLoaderHost {
+    addTrack(config: TrackConfig): Promise<DawTrackElement>;
+    querySelectorAll(selector: string): NodeListOf<Element>;
+}
+
+declare class DawEditorElement extends LitElement implements MidiLoaderHost {
     get samplesPerPixel(): number;
     set samplesPerPixel(value: number);
     private _samplesPerPixel;
@@ -877,9 +915,10 @@ declare class DawEditorElement extends LitElement {
     /** Called by <daw-spectrogram> on chunk unmount / element disconnect. */
     _spectrogramUnregisterCanvas(canvasId: string): void;
     /**
-     * Push a clip's decoded audio into the spectrogram controller. No-op
-     * unless the track is in spectrogram render-mode and the controller
-     * already exists (it bootstraps from canvas registration).
+     * Forward a clip's AudioBuffer to the spectrogram controller if the parent
+     * track is in spectrogram render-mode. Eagerly creates the controller via
+     * `_ensureSpectrogramController` so the audio data is queued for the first
+     * render — even if no canvases have been registered yet.
      */
     private _maybeRegisterSpectrogramClipAudio;
     scaleMode: 'temporal' | 'beats';
@@ -985,7 +1024,10 @@ declare class DawEditorElement extends LitElement {
      * `_selectedTrackId`, etc.) — most of which don't affect the spectrogram
      * viewport. Skip the cross-controller call when nothing changed.
      *
-     * The orchestrator dedupes too, but this avoids the call entirely.
+     * The orchestrator dedupes identical viewports too, so removing this cache
+     * wouldn't change observable behavior — but it would push a fresh
+     * `setViewport` call (with object allocation) into every Lit reactive
+     * update for properties unrelated to the viewport.
      */
     private _lastSpectrogramViewport;
     protected updated(_changed: Map<string, unknown>): void;
@@ -1066,6 +1108,20 @@ declare class DawEditorElement extends LitElement {
     private _onDragLeave;
     private _onDrop;
     loadFiles(files: FileList | File[]): Promise<LoadFilesResult>;
+    /**
+     * Imperatively load a `.mid` file (URL or File) and create N `<daw-track>`
+     * elements — one per note-bearing MIDI track. On any per-track failure,
+     * every `<daw-track>` appended during the call is removed (both successful
+     * and failed) so the editor returns to its pre-call state.
+     *
+     * `options.signal` is forwarded to `fetch()` only for URL sources; aborting
+     * after parsing does not cancel in-flight `addTrack` calls.
+     *
+     * Requires the optional `@dawcore/midi` peer dep — throws with an install
+     * hint (and `console.warn`s the original error) when the dynamic import
+     * fails for any reason.
+     */
+    loadMidi(source: string | File, options?: MidiLoadOptions): Promise<MidiLoadResult>;
     /**
      * 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
@@ -1306,6 +1362,7 @@ declare class DawSpectrogramElement extends LitElement {
     static styles: lit.CSSResult;
     private _canvases;
     private _registeredCanvasIds;
+    private _warnedNoHost;
     /**
      * Walk up to the editor host. `closest('daw-editor')` does NOT cross
      * shadow boundaries — and this element lives inside the editor's shadow