@dawcore/components 0.0.17 → 0.0.19

package/dist/index.d.mts

@@ -3,11 +3,18 @@ import { LitElement, PropertyValues, ReactiveController, ReactiveControllerHost
 import { MidiNoteData, SpectrogramConfig, FadeType, Peaks, Bits, 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;
@@ -824,7 +831,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;
@@ -979,6 +1008,15 @@ declare class DawEditorElement extends LitElement {
     connectedCallback(): void;
     disconnectedCallback(): void;
     willUpdate(changedProperties: Map<string, unknown>): void;
+    /**
+     * Cache of the last ViewportState forwarded to the spectrogram controller.
+     * Lit's `updated()` fires on every reactive state change (`_isPlaying`,
+     * `_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.
+     */
+    private _lastSpectrogramViewport;
     protected updated(_changed: Map<string, unknown>): void;
     private _onTrackConnected;
     private _onTrackRemoved;
@@ -1057,6 +1095,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

package/dist/index.d.ts

@@ -3,11 +3,18 @@ import { LitElement, PropertyValues, ReactiveController, ReactiveControllerHost
 import { MidiNoteData, SpectrogramConfig, FadeType, Peaks, Bits, 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;
@@ -824,7 +831,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;
@@ -979,6 +1008,15 @@ declare class DawEditorElement extends LitElement {
     connectedCallback(): void;
     disconnectedCallback(): void;
     willUpdate(changedProperties: Map<string, unknown>): void;
+    /**
+     * Cache of the last ViewportState forwarded to the spectrogram controller.
+     * Lit's `updated()` fires on every reactive state change (`_isPlaying`,
+     * `_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.
+     */
+    private _lastSpectrogramViewport;
     protected updated(_changed: Map<string, unknown>): void;
     private _onTrackConnected;
     private _onTrackRemoved;
@@ -1057,6 +1095,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

package/dist/index.js

@@ -3495,6 +3495,108 @@ async function loadFiles(host, files) {
   return { loaded, failed };
 }
 
+// src/interactions/midi-loader.ts
+var INSTALL_HINT = "@dawcore/midi is required for loadMidi(). Install with: npm install @dawcore/midi";
+async function loadMidiImpl(host, source, options = {}) {
+  const startTime = options.startTime ?? 0;
+  if (!Number.isFinite(startTime) || startTime < 0) {
+    throw new RangeError(
+      "loadMidi: startTime must be a non-negative finite number (got " + String(options.startTime) + ")"
+    );
+  }
+  let midiModule;
+  try {
+    midiModule = await import("@dawcore/midi");
+  } catch (originalErr) {
+    console.warn("[dawcore] @dawcore/midi dynamic import failed: " + String(originalErr));
+    throw new Error(INSTALL_HINT);
+  }
+  const { parseMidiUrl, parseMidiFile } = midiModule;
+  let parsed;
+  if (typeof source === "string") {
+    parsed = await parseMidiUrl(source, void 0, options.signal);
+  } else {
+    let buffer;
+    try {
+      buffer = await source.arrayBuffer();
+    } catch (err) {
+      throw new Error(
+        'loadMidi: failed to read File "' + source.name + '" (' + source.size + " bytes): " + String(err)
+      );
+    }
+    parsed = parseMidiFile(buffer);
+  }
+  const childrenBefore = new Set(host.querySelectorAll("daw-track"));
+  const settlements = await Promise.allSettled(
+    parsed.tracks.map(
+      (t) => host.addTrack({
+        name: t.name,
+        renderMode: "piano-roll",
+        clips: [
+          {
+            midiNotes: t.notes,
+            midiChannel: t.channel,
+            midiProgram: t.programNumber,
+            start: startTime
+          }
+        ]
+      })
+    )
+  );
+  const succeeded = [];
+  const rejections = [];
+  for (const s of settlements) {
+    if (s.status === "fulfilled") {
+      succeeded.push(s.value);
+    } else {
+      rejections.push(s.reason);
+    }
+  }
+  if (rejections.length > 0) {
+    const appendedTracks = Array.from(host.querySelectorAll("daw-track")).filter(
+      (el) => !childrenBefore.has(el)
+    );
+    for (const el of appendedTracks) {
+      try {
+        el.remove();
+      } catch (cleanupErr) {
+        console.warn("[dawcore] loadMidi cleanup failed for a track: " + String(cleanupErr));
+      }
+    }
+    await Promise.resolve();
+    for (let i = 1; i < rejections.length; i++) {
+      console.warn(
+        "[dawcore] loadMidi: additional track failure (" + i + "): " + stringifyReason(rejections[i])
+      );
+    }
+    const first = rejections[0];
+    if (rejections.length > 1) {
+      const message = "loadMidi: " + rejections.length + " of " + settlements.length + " tracks failed; first: " + (first instanceof Error ? first.message : stringifyReason(first));
+      throw new Error(message);
+    }
+    throw first instanceof Error ? first : new Error(stringifyReason(first));
+  }
+  return {
+    trackIds: succeeded.map((el) => el.trackId),
+    bpm: parsed.bpm,
+    timeSignature: parsed.timeSignature,
+    duration: parsed.duration,
+    name: parsed.name
+  };
+}
+function stringifyReason(reason) {
+  if (reason === null) return "null";
+  if (reason === void 0) return "undefined";
+  if (typeof reason === "object") {
+    try {
+      return JSON.stringify(reason);
+    } catch {
+      return Object.prototype.toString.call(reason);
+    }
+  }
+  return String(reason);
+}
+
 // src/interactions/recording-clip.ts
 var import_core7 = require("@waveform-playlist/core");
 function addRecordedClip(host, trackId, buf, startSample, durSamples, offsetSamples = 0) {
@@ -3828,6 +3930,15 @@ var DawEditorElement = class extends import_lit14.LitElement {
       v.scrollSelector = ".scroll-area";
       return v;
     })();
+    /**
+     * Cache of the last ViewportState forwarded to the spectrogram controller.
+     * Lit's `updated()` fires on every reactive state change (`_isPlaying`,
+     * `_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.
+     */
+    this._lastSpectrogramViewport = null;
     // --- Track Events ---
     this._onTrackConnected = (e) => {
       const trackId = e.detail?.trackId;
@@ -4364,7 +4475,11 @@ var DawEditorElement = class extends import_lit14.LitElement {
     if (this._spectrogramController) {
       const vs = this._viewport.visibleStart;
       const ve = this._viewport.visibleEnd;
+      const spp = this._renderSpp;
       if (Number.isFinite(vs) && Number.isFinite(ve)) {
+        const prev = this._lastSpectrogramViewport;
+        if (prev && prev.vs === vs && prev.ve === ve && prev.spp === spp) return;
+        this._lastSpectrogramViewport = { vs, ve, spp };
         const span = ve - vs;
         const bufferPad = span * 0.25;
         this._spectrogramController.setViewport({
@@ -4372,7 +4487,7 @@ var DawEditorElement = class extends import_lit14.LitElement {
           visibleEndPx: ve,
           bufferStartPx: Math.max(0, vs - bufferPad),
           bufferEndPx: ve + bufferPad,
-          samplesPerPixel: this._renderSpp
+          samplesPerPixel: spp
         });
       }
     }
@@ -5054,6 +5169,22 @@ var DawEditorElement = class extends import_lit14.LitElement {
   async loadFiles(files) {
     return loadFiles(this, files);
   }
+  /**
+   * 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.
+   */
+  async loadMidi(source, options) {
+    return loadMidiImpl(this, source, options);
+  }
   // --- Programmatic Track API ---
   /**
    * Build the engine if it hasn't been built yet. Lets consumers obtain a