@dawcore/components 0.0.12 → 0.0.14

package/dist/index.mjs

@@ -27,11 +27,54 @@ var DawClipElement = class extends LitElement {
     this.fadeOut = 0;
     this.fadeType = "linear";
     this.clipId = crypto.randomUUID();
+    // Removal is detected by the editor's MutationObserver — detached elements
+    // cannot bubble events to ancestors.
+    this._hasRendered = false;
   }
   // Light DOM — no visual rendering, just a data container
   createRenderRoot() {
     return this;
   }
+  connectedCallback() {
+    super.connectedCallback();
+    setTimeout(() => {
+      this.dispatchEvent(
+        new CustomEvent("daw-clip-connected", {
+          bubbles: true,
+          composed: true,
+          detail: { clipId: this.clipId, element: this }
+        })
+      );
+    }, 0);
+  }
+  updated(changed) {
+    if (!this._hasRendered) {
+      this._hasRendered = true;
+      return;
+    }
+    const clipProps = [
+      "src",
+      "peaksSrc",
+      "start",
+      "duration",
+      "offset",
+      "gain",
+      "name",
+      "fadeIn",
+      "fadeOut",
+      "fadeType"
+    ];
+    if (clipProps.some((p) => changed.has(p))) {
+      const trackEl = this.closest("daw-track");
+      this.dispatchEvent(
+        new CustomEvent("daw-clip-update", {
+          bubbles: true,
+          composed: true,
+          detail: { trackId: trackEl?.trackId ?? "", clipId: this.clipId }
+        })
+      );
+    }
+  }
 };
 __decorateClass([
   property()
@@ -839,6 +882,13 @@ DawStopButtonElement = __decorateClass([
 // src/elements/daw-editor.ts
 import { LitElement as LitElement9, html as html8, css as css8 } from "lit";
 import { customElement as customElement11, property as property7, state as state3 } from "lit/decorators.js";
+
+// src/types.ts
+function isDomClip(desc) {
+  return desc.kind === "dom";
+}
+
+// src/elements/daw-editor.ts
 import {
   createClip as createClip3,
   createClipFromSeconds,
@@ -1846,6 +1896,7 @@ var ViewportController = class {
   constructor(host) {
     this._scrollContainer = null;
     this._lastScrollLeft = 0;
+    this._resizeObserver = null;
     // Permissive defaults: render everything until scroll container is attached
     this.visibleStart = -Infinity;
     this.visibleEnd = Infinity;
@@ -1878,13 +1929,26 @@ var ViewportController = class {
   }
   hostDisconnected() {
     this._scrollContainer?.removeEventListener("scroll", this._onScroll);
+    this._resizeObserver?.disconnect();
+    this._resizeObserver = null;
     this._scrollContainer = null;
   }
   _attachScrollContainer(container) {
     this._scrollContainer?.removeEventListener("scroll", this._onScroll);
+    this._resizeObserver?.disconnect();
     this._scrollContainer = container;
     container.addEventListener("scroll", this._onScroll, { passive: true });
     this._update(container.scrollLeft, container.clientWidth);
+    if (typeof ResizeObserver !== "undefined") {
+      this._resizeObserver = new ResizeObserver(() => {
+        if (!this._scrollContainer) return;
+        const next = this._scrollContainer.clientWidth;
+        if (next === this.containerWidth) return;
+        this._update(this._scrollContainer.scrollLeft, next);
+        this._host.requestUpdate();
+      });
+      this._resizeObserver.observe(container);
+    }
     this._host.requestUpdate();
   }
   _update(scrollLeft, containerWidth) {
@@ -2850,6 +2914,7 @@ async function loadFiles(host, files) {
         soloed: false,
         clips: [
           {
+            kind: "drop",
             src: "",
             peaksSrc: "",
             start: 0,
@@ -2936,6 +3001,7 @@ function addRecordedClip(host, trackId, buf, startSample, durSamples, offsetSamp
     if (desc) {
       const sr = host.effectiveSampleRate;
       const clipDesc = {
+        kind: "drop",
         src: "",
         peaksSrc: "",
         start: startSample / sr,
@@ -3172,6 +3238,7 @@ var DawEditorElement = class extends LitElement9 {
     this.clipHeaders = false;
     this.clipHeaderHeight = 20;
     this.interactiveClips = false;
+    this.indefinitePlayback = false;
     this.scaleMode = "temporal";
     this._ticksPerPixel = 24;
     this._bpm = 120;
@@ -3288,6 +3355,51 @@ var DawEditorElement = class extends LitElement9 {
         this._onTrackRemoved(trackId);
       }
     };
+    // --- Clip lifecycle ---
+    this._onClipConnected = (e) => {
+      const detail = e.detail;
+      const clipEl = detail.element;
+      if (!(clipEl instanceof HTMLElement)) return;
+      const trackEl = clipEl.closest("daw-track");
+      if (!trackEl) return;
+      const trackId = trackEl.trackId;
+      if (!this._engineTracks.has(trackId)) {
+        const desc = this._tracks.get(trackId);
+        if (desc && !desc.clips.some((c) => isDomClip(c) && c.clipId === clipEl.clipId)) {
+          console.warn(
+            '[dawcore] daw-clip-connected fired while parent track "' + trackId + '" is still loading \u2014 late-appended clip may be missed. Wait for daw-track-ready before appending more <daw-clip> children, or use editor.addClip(trackId, config) after the track finishes loading.'
+          );
+        }
+        return;
+      }
+      const clipDesc = {
+        kind: "dom",
+        clipId: clipEl.clipId,
+        src: clipEl.src,
+        peaksSrc: clipEl.peaksSrc,
+        start: clipEl.start,
+        duration: clipEl.duration,
+        offset: clipEl.offset,
+        gain: clipEl.gain,
+        name: clipEl.name,
+        fadeIn: clipEl.fadeIn,
+        fadeOut: clipEl.fadeOut,
+        fadeType: clipEl.fadeType
+      };
+      this._loadAndAppendClip(trackId, clipDesc);
+    };
+    this._onClipUpdate = (e) => {
+      const clipEl = e.target;
+      if (!(clipEl instanceof HTMLElement) || clipEl.tagName !== "DAW-CLIP") return;
+      const detail = e.detail;
+      if (!detail.trackId) {
+        console.warn(
+          "[dawcore] daw-clip-update fired from a <daw-clip> not nested in a <daw-track> \u2014 ignored"
+        );
+        return;
+      }
+      this._applyClipUpdate(detail.trackId, detail.clipId, clipEl);
+    };
     // --- File Drop ---
     this._onDragOver = (e) => {
       if (!this.fileDrop) return;
@@ -3420,9 +3532,7 @@ var DawEditorElement = class extends LitElement9 {
       this.mono,
       singleClipOffsets
     );
-    const peakData = result.get(clipId);
-    if (!peakData) return null;
-    return { data: peakData.data, length: peakData.length };
+    return result.get(clipId) ?? null;
   }
   get effectiveSampleRate() {
     return this._resolvedSampleRate ?? this.sampleRate;
@@ -3476,7 +3586,13 @@ var DawEditorElement = class extends LitElement9 {
       const minTicks = 32 * num * this.ppqn;
       return Math.ceil(Math.max(contentTicks, minTicks) / this.ticksPerPixel);
     }
-    return Math.ceil(this._duration * this.effectiveSampleRate / this.samplesPerPixel);
+    const naturalWidth = Math.ceil(
+      this._duration * this.effectiveSampleRate / this.samplesPerPixel
+    );
+    if (this.indefinitePlayback) {
+      return Math.max(naturalWidth, this._viewport.containerWidth);
+    }
+    return naturalWidth;
   }
   /** Grid height when no tracks exist — matches scroll area's rendered height. */
   get _emptyGridHeight() {
@@ -3518,19 +3634,29 @@ var DawEditorElement = class extends LitElement9 {
     this.addEventListener("daw-track-update", this._onTrackUpdate);
     this.addEventListener("daw-track-control", this._onTrackControl);
     this.addEventListener("daw-track-remove", this._onTrackRemoveRequest);
+    this.addEventListener("daw-clip-connected", this._onClipConnected);
+    this.addEventListener("daw-clip-update", this._onClipUpdate);
     this._childObserver = new MutationObserver((mutations) => {
       for (const mutation of mutations) {
         for (const node of mutation.removedNodes) {
           if (node instanceof HTMLElement) {
             if (node.tagName === "DAW-TRACK") {
               this._onTrackRemoved(node.trackId);
+            } else if (node.tagName === "DAW-CLIP") {
+              this._onClipRemovedFromDom(node);
             }
-            const nested = node.querySelectorAll?.("daw-track");
-            if (nested) {
-              for (const track of nested) {
+            const nestedTracks = node.querySelectorAll?.("daw-track");
+            if (nestedTracks) {
+              for (const track of nestedTracks) {
                 this._onTrackRemoved(track.trackId);
               }
             }
+            const nestedClips = node.querySelectorAll?.("daw-clip");
+            if (nestedClips) {
+              for (const clip of nestedClips) {
+                this._onClipRemovedFromDom(clip);
+              }
+            }
           }
         }
       }
@@ -3543,6 +3669,8 @@ var DawEditorElement = class extends LitElement9 {
     this.removeEventListener("daw-track-update", this._onTrackUpdate);
     this.removeEventListener("daw-track-control", this._onTrackControl);
     this.removeEventListener("daw-track-remove", this._onTrackRemoveRequest);
+    this.removeEventListener("daw-clip-connected", this._onClipConnected);
+    this.removeEventListener("daw-clip-update", this._onClipUpdate);
     this._childObserver?.disconnect();
     this._childObserver = null;
     this._trackElements.clear();
@@ -3608,11 +3736,257 @@ var DawEditorElement = class extends LitElement9 {
       this._stopPlayhead();
     }
   }
+  _onClipRemovedFromDom(clipEl) {
+    const clipId = clipEl.clipId;
+    for (const [trackId, t] of this._engineTracks.entries()) {
+      if (t.clips.some((c) => c.id === clipId)) {
+        this._removeClipFromTrack(trackId, clipId);
+        return;
+      }
+    }
+    if (this._clipBuffers.has(clipId) || this._clipOffsets.has(clipId) || this._peaksData.has(clipId)) {
+      console.warn(
+        '[dawcore] _onClipRemovedFromDom: orphaned cache entries for clip "' + clipId + '" \u2014 purging (DOM/engine id mismatch?)'
+      );
+      this._purgeClipCaches(clipId);
+    }
+  }
+  async _loadAndAppendClip(trackId, clipDesc) {
+    if (!clipDesc.src) return;
+    const clipId = clipDesc.clipId;
+    let insertedClipId = null;
+    try {
+      const waveformDataPromise = clipDesc.peaksSrc ? this._resolvePeaks(clipDesc.peaksSrc) : Promise.resolve(null);
+      const audioPromise = this._fetchAndDecode(clipDesc.src);
+      const [waveformData, audioBuffer] = await Promise.all([waveformDataPromise, audioPromise]);
+      this._resolvedSampleRate = audioBuffer.sampleRate;
+      const clip = await this._finalizeAudioClip(clipDesc, audioBuffer, waveformData);
+      insertedClipId = clip.id;
+      const t = this._engineTracks.get(trackId);
+      if (!t) {
+        this._purgeClipCaches(clip.id);
+        return;
+      }
+      const updatedTrack = { ...t, clips: [...t.clips, clip] };
+      this._engineTracks = new Map(this._engineTracks).set(trackId, updatedTrack);
+      const desc = this._tracks.get(trackId);
+      if (desc) {
+        this._tracks = new Map(this._tracks).set(trackId, {
+          ...desc,
+          clips: [...desc.clips, clipDesc]
+        });
+      }
+      this._commitTrackChange(trackId, updatedTrack);
+      this.dispatchEvent(
+        new CustomEvent("daw-clip-ready", {
+          bubbles: true,
+          composed: true,
+          detail: { trackId, clipId: clip.id }
+        })
+      );
+    } catch (err) {
+      console.warn("[dawcore] _loadAndAppendClip failed: " + String(err));
+      if (insertedClipId) this._purgeClipCaches(insertedClipId);
+      this.dispatchEvent(
+        new CustomEvent("daw-clip-error", {
+          bubbles: true,
+          composed: true,
+          detail: { trackId, clipId: insertedClipId ?? clipId, error: err }
+        })
+      );
+    }
+  }
+  /**
+   * 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).
+   */
+  async _resolvePeaks(peaksSrc) {
+    try {
+      const wd = await this._fetchPeaks(peaksSrc);
+      const contextRate = this.audioContext.sampleRate;
+      if (wd.sample_rate === contextRate) return wd;
+      console.warn(
+        "[dawcore] Pre-computed peaks at " + wd.sample_rate + " Hz do not match AudioContext at " + contextRate + " Hz \u2014 ignoring " + peaksSrc + ", generating from audio"
+      );
+      return null;
+    } catch (err) {
+      console.warn(
+        "[dawcore] Failed to load peaks from " + peaksSrc + ": " + String(err) + " \u2014 falling back to AudioBuffer generation"
+      );
+      return null;
+    }
+  }
+  /**
+   * 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.
+   */
+  async _finalizeAudioClip(clipDesc, audioBuffer, waveformData) {
+    let clip;
+    if (waveformData) {
+      const wdRate = waveformData.sample_rate;
+      clip = createClip3({
+        audioBuffer,
+        waveformData,
+        startSample: Math.round(clipDesc.start * wdRate),
+        durationSamples: Math.round((clipDesc.duration || waveformData.duration) * wdRate),
+        offsetSamples: Math.round(clipDesc.offset * wdRate),
+        gain: clipDesc.gain,
+        name: clipDesc.name,
+        sampleRate: wdRate,
+        sourceDurationSamples: Math.ceil(waveformData.duration * wdRate)
+      });
+      this._peakPipeline.cacheWaveformData(audioBuffer, waveformData);
+    } else {
+      clip = createClipFromSeconds({
+        audioBuffer,
+        startTime: clipDesc.start,
+        duration: clipDesc.duration || audioBuffer.duration,
+        offset: clipDesc.offset,
+        gain: clipDesc.gain,
+        name: clipDesc.name,
+        sampleRate: audioBuffer.sampleRate,
+        sourceDuration: audioBuffer.duration
+      });
+    }
+    if (isDomClip(clipDesc)) clip.id = clipDesc.clipId;
+    this._clipBuffers = new Map(this._clipBuffers).set(clip.id, audioBuffer);
+    this._clipOffsets.set(clip.id, {
+      offsetSamples: clip.offsetSamples,
+      durationSamples: clip.durationSamples
+    });
+    let peakData;
+    try {
+      peakData = await this._peakPipeline.generatePeaks(
+        audioBuffer,
+        this._renderSpp,
+        this.mono,
+        clip.offsetSamples,
+        clip.durationSamples
+      );
+    } catch (err) {
+      this._purgeClipCaches(clip.id);
+      throw err;
+    }
+    this._peaksData = new Map(this._peaksData).set(clip.id, peakData);
+    if (waveformData) {
+      this._minSamplesPerPixel = Math.max(this._minSamplesPerPixel, waveformData.scale);
+    }
+    return clip;
+  }
+  /** Remove a single clip from all per-clip caches. Used by error rollbacks. */
+  _purgeClipCaches(clipId) {
+    const nextBuffers = new Map(this._clipBuffers);
+    nextBuffers.delete(clipId);
+    this._clipBuffers = nextBuffers;
+    const nextPeaks = new Map(this._peaksData);
+    nextPeaks.delete(clipId);
+    this._peaksData = nextPeaks;
+    this._clipOffsets.delete(clipId);
+  }
+  /**
+   * 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).
+   */
+  _commitTrackChange(trackId, updatedTrack) {
+    this._recomputeDuration();
+    if (this._engine?.updateTrack) this._engine.updateTrack(trackId, updatedTrack);
+    else if (this._engine) this._engine.setTracks([...this._engineTracks.values()]);
+  }
+  _applyClipUpdate(trackId, clipId, clipEl) {
+    const t = this._engineTracks.get(trackId);
+    if (!t) {
+      console.warn('[dawcore] _applyClipUpdate: no engine track for id "' + trackId + '"');
+      return;
+    }
+    const idx = t.clips.findIndex((c) => c.id === clipId);
+    if (idx === -1) {
+      console.warn(
+        '[dawcore] _applyClipUpdate: clip "' + clipId + '" not found in track "' + trackId + '" (DOM/engine clip-id misalignment?)'
+      );
+      return;
+    }
+    const oldClip = t.clips[idx];
+    const sr = oldClip.sampleRate ?? this.effectiveSampleRate;
+    const newStartSample = Math.round(clipEl.start * sr);
+    const newDurationSamples = clipEl.duration > 0 ? Math.round(clipEl.duration * sr) : oldClip.durationSamples;
+    const newOffsetSamples = Math.round(clipEl.offset * sr);
+    const updatedClip = {
+      ...oldClip,
+      startSample: newStartSample,
+      durationSamples: newDurationSamples,
+      offsetSamples: newOffsetSamples,
+      gain: clipEl.gain,
+      name: clipEl.name || oldClip.name
+    };
+    const updatedClips = [...t.clips];
+    updatedClips[idx] = updatedClip;
+    const updatedTrack = { ...t, clips: updatedClips };
+    this._engineTracks = new Map(this._engineTracks).set(trackId, updatedTrack);
+    const boundsChanged = oldClip.offsetSamples !== newOffsetSamples || oldClip.durationSamples !== newDurationSamples;
+    if (boundsChanged) {
+      this._clipOffsets.set(clipId, {
+        offsetSamples: newOffsetSamples,
+        durationSamples: newDurationSamples
+      });
+      const peaks = this.reextractClipPeaks(clipId, newOffsetSamples, newDurationSamples);
+      if (peaks) {
+        this._peaksData = new Map(this._peaksData).set(clipId, peaks);
+      }
+    }
+    this._commitTrackChange(trackId, updatedTrack);
+  }
+  _removeClipFromTrack(trackId, clipId) {
+    const t = this._engineTracks.get(trackId);
+    if (!t) {
+      console.warn('[dawcore] _removeClipFromTrack: no engine track for id "' + trackId + '"');
+      return;
+    }
+    const updatedClips = t.clips.filter((c) => c.id !== clipId);
+    if (updatedClips.length === t.clips.length) {
+      console.warn(
+        '[dawcore] _removeClipFromTrack: clip "' + clipId + '" not found in track "' + trackId + '"'
+      );
+      return;
+    }
+    const updatedTrack = { ...t, clips: updatedClips };
+    this._engineTracks = new Map(this._engineTracks).set(trackId, updatedTrack);
+    const nextBuffers = new Map(this._clipBuffers);
+    nextBuffers.delete(clipId);
+    this._clipBuffers = nextBuffers;
+    this._clipOffsets.delete(clipId);
+    const nextPeaks = new Map(this._peaksData);
+    nextPeaks.delete(clipId);
+    this._peaksData = nextPeaks;
+    const desc = this._tracks.get(trackId);
+    if (desc) {
+      this._tracks = new Map(this._tracks).set(trackId, {
+        ...desc,
+        // Only DOM-sourced clips have an id to match; drop-sourced clips are
+        // filtered through unchanged (their identity is the descriptor itself).
+        clips: desc.clips.filter((c) => !(isDomClip(c) && c.clipId === clipId))
+      });
+    }
+    this._commitTrackChange(trackId, updatedTrack);
+  }
   _readTrackDescriptor(trackEl) {
     const clipEls = trackEl.querySelectorAll("daw-clip");
     const clips = [];
     if (clipEls.length === 0 && trackEl.src) {
       clips.push({
+        kind: "drop",
         src: trackEl.src,
         peaksSrc: "",
         start: 0,
@@ -3627,6 +4001,8 @@ var DawEditorElement = class extends LitElement9 {
     } else {
       for (const clipEl of clipEls) {
         clips.push({
+          kind: "dom",
+          clipId: clipEl.clipId,
           src: clipEl.src,
           peaksSrc: clipEl.peaksSrc,
           start: clipEl.start,
@@ -3656,111 +4032,92 @@ var DawEditorElement = class extends LitElement9 {
       const clips = [];
       for (const clipDesc of descriptor.clips) {
         if (!clipDesc.src) continue;
-        const waveformDataPromise = clipDesc.peaksSrc ? this._fetchPeaks(clipDesc.peaksSrc) : null;
-        const audioPromise = this._fetchAndDecode(clipDesc.src);
-        let waveformData = null;
-        if (waveformDataPromise) {
-          try {
-            const wd = await waveformDataPromise;
-            const contextRate = this.audioContext.sampleRate;
-            if (wd.sample_rate === contextRate) {
-              waveformData = wd;
-            } else {
-              console.warn(
-                "[dawcore] Pre-computed peaks at " + wd.sample_rate + " Hz do not match AudioContext at " + contextRate + " Hz \u2014 ignoring " + clipDesc.peaksSrc + ", generating from audio"
-              );
-            }
-          } catch (err) {
-            console.warn(
-              "[dawcore] Failed to load peaks from " + clipDesc.peaksSrc + ": " + String(err) + " \u2014 falling back to AudioBuffer generation"
+        try {
+          const waveformDataPromise = clipDesc.peaksSrc ? this._resolvePeaks(clipDesc.peaksSrc) : Promise.resolve(null);
+          const audioPromise = this._fetchAndDecode(clipDesc.src);
+          const waveformData = await waveformDataPromise;
+          if (waveformData) {
+            const wdRate = waveformData.sample_rate;
+            const clip2 = createClip3({
+              waveformData,
+              startSample: Math.round(clipDesc.start * wdRate),
+              durationSamples: Math.round((clipDesc.duration || waveformData.duration) * wdRate),
+              offsetSamples: Math.round(clipDesc.offset * wdRate),
+              gain: clipDesc.gain,
+              name: clipDesc.name,
+              sampleRate: wdRate,
+              sourceDurationSamples: Math.ceil(waveformData.duration * wdRate)
+            });
+            if (isDomClip(clipDesc)) clip2.id = clipDesc.clipId;
+            const effectiveScale = Math.max(this._renderSpp, waveformData.scale);
+            const peakData = extractPeaks(
+              waveformData,
+              effectiveScale,
+              this.mono,
+              clip2.offsetSamples,
+              clip2.durationSamples
             );
+            this._clipOffsets.set(clip2.id, {
+              offsetSamples: clip2.offsetSamples,
+              durationSamples: clip2.durationSamples
+            });
+            this._peaksData = new Map(this._peaksData).set(clip2.id, peakData);
+            this._minSamplesPerPixel = Math.max(this._minSamplesPerPixel, waveformData.scale);
+            const previewTrack = createTrack2({
+              name: descriptor.name,
+              clips: [clip2],
+              volume: descriptor.volume,
+              pan: descriptor.pan,
+              muted: descriptor.muted,
+              soloed: descriptor.soloed
+            });
+            previewTrack.id = trackId;
+            this._engineTracks = new Map(this._engineTracks).set(trackId, previewTrack);
+            this._recomputeDuration();
+            let audioBuffer2;
+            try {
+              audioBuffer2 = await audioPromise;
+            } catch (audioErr) {
+              const nextPeaks = new Map(this._peaksData);
+              nextPeaks.delete(clip2.id);
+              this._peaksData = nextPeaks;
+              this._clipOffsets.delete(clip2.id);
+              const nextEngine = new Map(this._engineTracks);
+              nextEngine.delete(trackId);
+              this._engineTracks = nextEngine;
+              this._minSamplesPerPixel = this._peakPipeline.getMaxCachedScale(this._clipBuffers);
+              this._recomputeDuration();
+              throw audioErr;
+            }
+            this._resolvedSampleRate = audioBuffer2.sampleRate;
+            const updatedClip = { ...clip2, audioBuffer: audioBuffer2 };
+            this._clipBuffers = new Map(this._clipBuffers).set(clip2.id, audioBuffer2);
+            this._peakPipeline.cacheWaveformData(audioBuffer2, waveformData);
+            clips.push(updatedClip);
+            continue;
           }
-        }
-        if (waveformData) {
-          const wdRate = waveformData.sample_rate;
-          const clip2 = createClip3({
-            waveformData,
-            startSample: Math.round(clipDesc.start * wdRate),
-            durationSamples: Math.round((clipDesc.duration || waveformData.duration) * wdRate),
-            offsetSamples: Math.round(clipDesc.offset * wdRate),
-            gain: clipDesc.gain,
-            name: clipDesc.name,
-            sampleRate: wdRate,
-            sourceDurationSamples: Math.ceil(waveformData.duration * wdRate)
-          });
-          const effectiveScale = Math.max(this._renderSpp, waveformData.scale);
-          const peakData2 = extractPeaks(
-            waveformData,
-            effectiveScale,
-            this.mono,
-            clip2.offsetSamples,
-            clip2.durationSamples
+          const audioBuffer = await audioPromise;
+          this._resolvedSampleRate = audioBuffer.sampleRate;
+          const clip = await this._finalizeAudioClip(clipDesc, audioBuffer, null);
+          clips.push(clip);
+        } catch (clipErr) {
+          console.warn(
+            '[dawcore] _loadTrack: clip "' + clipDesc.src + '" failed: ' + String(clipErr)
           );
-          this._clipOffsets.set(clip2.id, {
-            offsetSamples: clip2.offsetSamples,
-            durationSamples: clip2.durationSamples
-          });
-          this._peaksData = new Map(this._peaksData).set(clip2.id, peakData2);
-          this._minSamplesPerPixel = Math.max(this._minSamplesPerPixel, waveformData.scale);
-          const previewTrack = createTrack2({
-            name: descriptor.name,
-            clips: [clip2],
-            volume: descriptor.volume,
-            pan: descriptor.pan,
-            muted: descriptor.muted,
-            soloed: descriptor.soloed
-          });
-          previewTrack.id = trackId;
-          this._engineTracks = new Map(this._engineTracks).set(trackId, previewTrack);
-          this._recomputeDuration();
-          let audioBuffer2;
-          try {
-            audioBuffer2 = await audioPromise;
-          } catch (audioErr) {
-            const nextPeaks = new Map(this._peaksData);
-            nextPeaks.delete(clip2.id);
-            this._peaksData = nextPeaks;
-            this._clipOffsets.delete(clip2.id);
-            const nextEngine = new Map(this._engineTracks);
-            nextEngine.delete(trackId);
-            this._engineTracks = nextEngine;
-            this._minSamplesPerPixel = this._peakPipeline.getMaxCachedScale(this._clipBuffers);
-            this._recomputeDuration();
-            throw audioErr;
+          if (this.isConnected) {
+            this.dispatchEvent(
+              new CustomEvent("daw-clip-error", {
+                bubbles: true,
+                composed: true,
+                detail: {
+                  trackId,
+                  clipId: isDomClip(clipDesc) ? clipDesc.clipId : "",
+                  error: clipErr
+                }
+              })
+            );
           }
-          this._resolvedSampleRate = audioBuffer2.sampleRate;
-          const updatedClip = { ...clip2, audioBuffer: audioBuffer2 };
-          this._clipBuffers = new Map(this._clipBuffers).set(clip2.id, audioBuffer2);
-          this._peakPipeline.cacheWaveformData(audioBuffer2, waveformData);
-          clips.push(updatedClip);
-          continue;
         }
-        const audioBuffer = await audioPromise;
-        this._resolvedSampleRate = audioBuffer.sampleRate;
-        const clip = createClipFromSeconds({
-          audioBuffer,
-          startTime: clipDesc.start,
-          duration: clipDesc.duration || audioBuffer.duration,
-          offset: clipDesc.offset,
-          gain: clipDesc.gain,
-          name: clipDesc.name,
-          sampleRate: audioBuffer.sampleRate,
-          sourceDuration: audioBuffer.duration
-        });
-        this._clipBuffers = new Map(this._clipBuffers).set(clip.id, audioBuffer);
-        this._clipOffsets.set(clip.id, {
-          offsetSamples: clip.offsetSamples,
-          durationSamples: clip.durationSamples
-        });
-        const peakData = await this._peakPipeline.generatePeaks(
-          audioBuffer,
-          this._renderSpp,
-          this.mono,
-          clip.offsetSamples,
-          clip.durationSamples
-        );
-        this._peaksData = new Map(this._peaksData).set(clip.id, peakData);
-        clips.push(clip);
       }
       const track = createTrack2({
         name: descriptor.name,
@@ -3770,6 +4127,12 @@ var DawEditorElement = class extends LitElement9 {
         muted: descriptor.muted,
         soloed: descriptor.soloed
       });
+      const requestedClips = descriptor.clips.filter((c) => c.src).length;
+      if (requestedClips > 0 && clips.length === 0) {
+        throw new Error(
+          "all " + requestedClips + " clip(s) failed to load \u2014 see prior daw-clip-error events"
+        );
+      }
       track.id = trackId;
       this._engineTracks = new Map(this._engineTracks).set(trackId, track);
       this._recomputeDuration();
@@ -3903,6 +4266,251 @@ var DawEditorElement = class extends LitElement9 {
   async loadFiles(files) {
     return loadFiles(this, files);
   }
+  // --- Programmatic Track API ---
+  /**
+   * 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.
+   */
+  async ready() {
+    return this._ensureEngine();
+  }
+  /**
+   * 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.
+   */
+  _awaitId(readyEvent, errorEvent, matchesId, resolveValue, setup) {
+    return new Promise((resolve, reject) => {
+      const onReady = (e) => {
+        if (!matchesId(e.detail)) return;
+        cleanup();
+        resolve(resolveValue);
+      };
+      const onError = (e) => {
+        const detail = e.detail;
+        if (!matchesId(e.detail)) return;
+        cleanup();
+        const err = detail.error;
+        reject(err instanceof Error ? err : new Error(String(err)));
+      };
+      const cleanup = () => {
+        this.removeEventListener(readyEvent, onReady);
+        this.removeEventListener(errorEvent, onError);
+      };
+      this.addEventListener(readyEvent, onReady);
+      this.addEventListener(errorEvent, onError);
+      setup();
+    });
+  }
+  /**
+   * 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 = {}) {
+    const trackEl = document.createElement("daw-track");
+    if (config.name !== void 0) trackEl.setAttribute("name", config.name);
+    if (config.volume !== void 0) trackEl.volume = config.volume;
+    if (config.pan !== void 0) trackEl.pan = config.pan;
+    if (config.muted) trackEl.setAttribute("muted", "");
+    if (config.soloed) trackEl.setAttribute("soloed", "");
+    for (const clipConfig of config.clips ?? []) {
+      trackEl.appendChild(this._buildClipElement(clipConfig));
+    }
+    return this._awaitId(
+      "daw-track-ready",
+      "daw-track-error",
+      (d) => d.trackId === trackEl.trackId,
+      trackEl,
+      () => this.appendChild(trackEl)
+    );
+  }
+  /**
+   * 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) {
+    const trackEl = this._trackElements.get(trackId);
+    if (trackEl) {
+      trackEl.remove();
+    } else if (this._engineTracks.has(trackId)) {
+      this._onTrackRemoved(trackId);
+    } else {
+      console.warn('[dawcore] removeTrack: no track found for id "' + trackId + '"');
+    }
+  }
+  /**
+   * 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, partial) {
+    const trackEl = this._trackElements.get(trackId);
+    if (trackEl) {
+      if (partial.name !== void 0) trackEl.setAttribute("name", partial.name);
+      if (partial.volume !== void 0) trackEl.volume = partial.volume;
+      if (partial.pan !== void 0) trackEl.pan = partial.pan;
+      if (partial.muted !== void 0) {
+        if (partial.muted) trackEl.setAttribute("muted", "");
+        else trackEl.removeAttribute("muted");
+      }
+      if (partial.soloed !== void 0) {
+        if (partial.soloed) trackEl.setAttribute("soloed", "");
+        else trackEl.removeAttribute("soloed");
+      }
+      return;
+    }
+    const oldDesc = this._tracks.get(trackId);
+    if (!oldDesc) return;
+    const newDesc = {
+      ...oldDesc,
+      ...partial.name !== void 0 && { name: partial.name },
+      ...partial.volume !== void 0 && { volume: partial.volume },
+      ...partial.pan !== void 0 && { pan: partial.pan },
+      ...partial.muted !== void 0 && { muted: partial.muted },
+      ...partial.soloed !== void 0 && { soloed: partial.soloed }
+    };
+    this._tracks = new Map(this._tracks).set(trackId, newDesc);
+    if (this._engine) {
+      if (partial.volume !== void 0) this._engine.setTrackVolume(trackId, partial.volume);
+      if (partial.pan !== void 0) this._engine.setTrackPan(trackId, partial.pan);
+      if (partial.muted !== void 0) this._engine.setTrackMute(trackId, partial.muted);
+      if (partial.soloed !== void 0) this._engine.setTrackSolo(trackId, partial.soloed);
+    }
+  }
+  /**
+   * 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, config) {
+    if (!config.src) {
+      return Promise.reject(
+        new Error(
+          "addClip: config.src is required \u2014 pass a URL to load. Empty/recording clips are not yet supported via addClip."
+        )
+      );
+    }
+    const trackEl = this._trackElements.get(trackId);
+    if (!trackEl) {
+      return Promise.reject(
+        new Error(
+          'addClip: no <daw-track> element for trackId "' + trackId + '" \u2014 addClip currently requires a DOM-backed track. Use editor.addTrack(config) first.'
+        )
+      );
+    }
+    const clipEl = this._buildClipElement(config);
+    return this._awaitId(
+      "daw-clip-ready",
+      "daw-clip-error",
+      (d) => d.clipId === clipEl.clipId,
+      clipEl.clipId,
+      () => trackEl.appendChild(clipEl)
+    );
+  }
+  /**
+   * 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, clipId) {
+    const trackEl = this._trackElements.get(trackId);
+    if (trackEl) {
+      const clipEl = [...trackEl.querySelectorAll("daw-clip")].find(
+        (c) => c.clipId === clipId
+      );
+      if (clipEl) {
+        clipEl.remove();
+        return;
+      }
+    }
+    if (this._engineTracks.has(trackId)) {
+      this._removeClipFromTrack(trackId, clipId);
+      return;
+    }
+    console.warn(
+      '[dawcore] removeClip: no track found for id "' + trackId + '" (clipId "' + clipId + '")'
+    );
+  }
+  /**
+   * 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, clipId, partial) {
+    const trackEl = this._trackElements.get(trackId);
+    if (trackEl) {
+      const clipEl = [...trackEl.querySelectorAll("daw-clip")].find(
+        (c) => c.clipId === clipId
+      );
+      if (clipEl) {
+        if (partial.start !== void 0) clipEl.start = partial.start;
+        if (partial.duration !== void 0) clipEl.duration = partial.duration;
+        if (partial.offset !== void 0) clipEl.offset = partial.offset;
+        if (partial.gain !== void 0) clipEl.gain = partial.gain;
+        if (partial.name !== void 0) clipEl.setAttribute("name", partial.name);
+        if (partial.fadeIn !== void 0) clipEl.fadeIn = partial.fadeIn;
+        if (partial.fadeOut !== void 0) clipEl.fadeOut = partial.fadeOut;
+        if (partial.fadeType !== void 0) clipEl.setAttribute("fade-type", partial.fadeType);
+        return;
+      }
+    }
+    const t = this._engineTracks.get(trackId);
+    if (!t) {
+      console.warn('[dawcore] updateClip: no track found for id "' + trackId + '"');
+      return;
+    }
+    const idx = t.clips.findIndex((c) => c.id === clipId);
+    if (idx === -1) {
+      console.warn(
+        '[dawcore] updateClip: clip "' + clipId + '" not found in track "' + trackId + '"'
+      );
+      return;
+    }
+    const oldClip = t.clips[idx];
+    const sr = oldClip.sampleRate ?? this.effectiveSampleRate;
+    const updatedClip = {
+      ...oldClip,
+      ...partial.start !== void 0 && { startSample: Math.round(partial.start * sr) },
+      ...partial.duration !== void 0 && partial.duration > 0 && { durationSamples: Math.round(partial.duration * sr) },
+      ...partial.offset !== void 0 && { offsetSamples: Math.round(partial.offset * sr) },
+      ...partial.gain !== void 0 && { gain: partial.gain },
+      ...partial.name !== void 0 && { name: partial.name }
+    };
+    const updatedClips = [...t.clips];
+    updatedClips[idx] = updatedClip;
+    const updatedTrack = { ...t, clips: updatedClips };
+    this._engineTracks = new Map(this._engineTracks).set(trackId, updatedTrack);
+    this._commitTrackChange(trackId, updatedTrack);
+  }
+  _buildClipElement(config) {
+    const clipEl = document.createElement("daw-clip");
+    if (config.src !== void 0) clipEl.setAttribute("src", config.src);
+    if (config.peaksSrc !== void 0) clipEl.setAttribute("peaks-src", config.peaksSrc);
+    if (config.start !== void 0) clipEl.start = config.start;
+    if (config.duration !== void 0) clipEl.duration = config.duration;
+    if (config.offset !== void 0) clipEl.offset = config.offset;
+    if (config.gain !== void 0) clipEl.gain = config.gain;
+    if (config.name !== void 0) clipEl.setAttribute("name", config.name);
+    if (config.fadeIn !== void 0) clipEl.fadeIn = config.fadeIn;
+    if (config.fadeOut !== void 0) clipEl.fadeOut = config.fadeOut;
+    if (config.fadeType !== void 0) clipEl.setAttribute("fade-type", config.fadeType);
+    return clipEl;
+  }
   // --- Playback ---
   async play(startTime) {
     try {
@@ -4076,38 +4684,34 @@ var DawEditorElement = class extends LitElement9 {
     if (!playhead || !this._engine) return;
     const engine = this._engine;
     const ctx = this.audioContext;
+    const audibleTime = () => {
+      const outputLatency = "outputLatency" in ctx ? ctx.outputLatency : 0;
+      const t = engine.getCurrentTime() - outputLatency - engine.lookAhead;
+      return Number.isFinite(t) ? Math.max(0, t) : 0;
+    };
     if (this.scaleMode === "beats") {
       const secondsToTicksFn = (s) => this._secondsToTicks(s);
-      playhead.startBeatsAnimationWithMap(
-        () => {
-          const latency = "outputLatency" in ctx ? ctx.outputLatency : 0;
-          return Math.max(0, engine.getCurrentTime() - latency);
-        },
-        secondsToTicksFn,
-        this.ticksPerPixel
-      );
+      playhead.startBeatsAnimationWithMap(audibleTime, secondsToTicksFn, this.ticksPerPixel);
     } else {
-      playhead.startAnimation(
-        () => {
-          const latency = "outputLatency" in ctx ? ctx.outputLatency : 0;
-          return Math.max(0, engine.getCurrentTime() - latency);
-        },
-        this.effectiveSampleRate,
-        this.samplesPerPixel
-      );
+      playhead.startAnimation(audibleTime, this.effectiveSampleRate, this.samplesPerPixel);
     }
   }
   _stopPlayhead() {
     const playhead = this._getPlayhead();
     if (!playhead) return;
+    const ctx = this.audioContext;
+    const outputLatency = "outputLatency" in ctx ? ctx.outputLatency : 0;
+    const lookAhead = this._engine?.lookAhead ?? 0;
+    const t = this._currentTime - outputLatency - lookAhead;
+    const visualTime = Number.isFinite(t) ? Math.max(0, t) : 0;
     if (this.scaleMode === "beats") {
       playhead.stopBeatsAnimationWithMap(
-        this._currentTime,
+        visualTime,
         (s) => this._secondsToTicks(s),
         this.ticksPerPixel
       );
     } else {
-      playhead.stopAnimation(this._currentTime, this.effectiveSampleRate, this.samplesPerPixel);
+      playhead.stopAnimation(visualTime, this.effectiveSampleRate, this.samplesPerPixel);
     }
   }
   _getPlayhead() {
@@ -4155,7 +4759,7 @@ var DawEditorElement = class extends LitElement9 {
       };
     });
     return html8`
-      ${orderedTracks.length > 0 ? html8`<div class="controls-column">
+      ${orderedTracks.length > 0 || this.indefinitePlayback ? html8`<div class="controls-column">
             ${this.timescale ? html8`<div style="height: 30px;"></div>` : ""}
             ${orderedTracks.map(
       (t) => html8`
@@ -4181,7 +4785,7 @@ var DawEditorElement = class extends LitElement9 {
           @dragleave=${this._onDragLeave}
           @drop=${this._onDrop}
         >
-          ${(orderedTracks.length > 0 || this.scaleMode === "beats") && this.timescale ? html8`<daw-ruler
+          ${(orderedTracks.length > 0 || this.scaleMode === "beats" || this.indefinitePlayback) && this.timescale ? html8`<daw-ruler
                 .samplesPerPixel=${spp}
                 .sampleRate=${this.effectiveSampleRate}
                 .duration=${this._duration}
@@ -4201,7 +4805,7 @@ var DawEditorElement = class extends LitElement9 {
                 .length=${this._totalWidth}
                 .height=${orderedTracks.length > 0 ? orderedTracks.reduce((sum, t) => sum + t.trackHeight + 1, 0) : this._emptyGridHeight}
               ></daw-grid>` : ""}
-          ${orderedTracks.length > 0 || this.scaleMode === "beats" ? html8`<daw-selection .startPx=${selStartPx} .endPx=${selEndPx}></daw-selection>
+          ${orderedTracks.length > 0 || this.scaleMode === "beats" || this.indefinitePlayback ? html8`<daw-selection .startPx=${selStartPx} .endPx=${selEndPx}></daw-selection>
                 <daw-playhead></daw-playhead>` : ""}
           ${orderedTracks.map((t) => {
       const channelHeight = this.waveHeight;
@@ -4398,6 +5002,9 @@ __decorateClass([
 __decorateClass([
   property7({ type: Boolean, attribute: "interactive-clips" })
 ], DawEditorElement.prototype, "interactiveClips", 2);
+__decorateClass([
+  property7({ type: Boolean, attribute: "indefinite-playback" })
+], DawEditorElement.prototype, "indefinitePlayback", 2);
 __decorateClass([
   property7({ type: String, attribute: "scale-mode" })
 ], DawEditorElement.prototype, "scaleMode", 2);
@@ -4537,12 +5144,14 @@ var DawRulerElement = class extends LitElement10 {
         ppqn: this.ppqn
       });
       this._tickData = null;
-    } else if (this.duration > 0) {
+    } else if (this.duration > 0 || this.totalWidth > 0) {
+      const widthDerivedDuration = this.totalWidth * this.samplesPerPixel / this.sampleRate;
+      const effectiveDuration = Math.max(this.duration, widthDerivedDuration);
       this._musicalTickData = null;
       this._tickData = computeTemporalTicks(
         this.samplesPerPixel,
         this.sampleRate,
-        this.duration,
+        effectiveDuration,
         this.rulerHeight
       );
     } else {
@@ -4994,6 +5603,7 @@ export {
   DawTransportElement,
   DawWaveformElement,
   RecordingController,
+  isDomClip,
   splitAtPlayhead
 };
 //# sourceMappingURL=index.mjs.map