@arraypress/waveform-bar 1.3.1 → 1.4.0

package/dist/waveform-bar.esm.js

@@ -5,7 +5,10 @@ var ICONS = {
   prev: '<svg viewBox="0 0 24 24" width="18" height="18" fill="currentColor"><path d="M6 6h2v12H6zm3.5 6l8.5 6V6z"/></svg>',
   next: '<svg viewBox="0 0 24 24" width="18" height="18" fill="currentColor"><path d="M6 18l8.5-6L6 6v12zM16 6v12h2V6h-2z"/></svg>',
   queue: '<svg viewBox="0 0 24 24" width="18" height="18" fill="currentColor"><path d="M3 13h2v-2H3v2zm0 4h2v-2H3v2zm0-8h2V7H3v2zm4 4h14v-2H7v2zm0 4h14v-2H7v2zM7 7v2h14V7H7z"/></svg>',
+  share: '<svg viewBox="0 0 24 24" width="17" height="17" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 12v8a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-8"/><polyline points="16 6 12 2 8 6"/><line x1="12" y1="2" x2="12" y2="15"/></svg>',
   music: '<svg viewBox="0 0 24 24" width="18" height="18" fill="currentColor" opacity="0.5"><path d="M12 3v10.55c-.59-.34-1.27-.55-2-.55C7.79 13 6 14.79 6 17s1.79 4 4 4 4-1.79 4-4V7h4V3h-6z"/></svg>',
+  collapse: '<svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="6 9 12 15 18 9"/></svg>',
+  expand: '<svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="18 15 12 9 6 15"/></svg>',
   volHigh: '<svg viewBox="0 0 24 24" width="18" height="18" fill="currentColor"><path d="M3 9v6h4l5 5V4L7 9H3zm13.5 3c0-1.77-1.02-3.29-2.5-4.03v8.05c1.48-.73 2.5-2.25 2.5-4.02zM14 3.23v2.06c2.89.86 5 3.54 5 6.71s-2.11 5.85-5 6.71v2.06c4.01-.91 7-4.49 7-8.77s-2.99-7.86-7-8.77z"/></svg>',
   volLow: '<svg viewBox="0 0 24 24" width="18" height="18" fill="currentColor"><path d="M18.5 12c0-1.77-1.02-3.29-2.5-4.03v8.05c1.48-.73 2.5-2.25 2.5-4.02zM5 9v6h4l5 5V4L9 9H5z"/></svg>',
   volMute: '<svg viewBox="0 0 24 24" width="18" height="18" fill="currentColor"><path d="M16.5 12c0-1.77-1.02-3.29-2.5-4.03v2.21l2.45 2.45c.03-.2.05-.41.05-.63zm2.5 0c0 .94-.2 1.82-.54 2.64l1.51 1.51C20.63 14.91 21 13.5 21 12c0-4.28-2.99-7.86-7-8.77v2.06c2.89.86 5 3.54 5 6.71zM4.27 3L3 4.27 7.73 9H3v6h4l5 5v-6.73l4.25 4.25c-.67.52-1.42.93-2.25 1.18v2.06c1.38-.31 2.63-.95 3.69-1.81L19.73 21 21 19.73l-9-9L4.27 3zM12 4L9.91 6.09 12 8.18V4z"/></svg>',
@@ -30,6 +33,15 @@ function escapeHtml(str) {
   d.textContent = str;
   return d.innerHTML;
 }
+function isSafeHref(url) {
+  if (typeof url !== "string" || url === "") return false;
+  try {
+    const u = new URL(url, location.href);
+    return u.protocol === "http:" || u.protocol === "https:";
+  } catch (e) {
+    return false;
+  }
+}
 function formatTime(seconds) {
   if (!seconds || isNaN(seconds)) return "0:00";
   const m = Math.floor(seconds / 60);
@@ -41,12 +53,21 @@ function parseTrackFromElement(el) {
   if (!url) return null;
   let meta = {};
   try {
-    meta = JSON.parse(el.dataset.wbMeta || el.dataset.meta || "{}");
+    const parsed = JSON.parse(el.dataset.wbMeta || el.dataset.meta || "{}");
+    meta = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch (e) {
+  }
+  let markers = [];
+  try {
+    const parsed = JSON.parse(el.dataset.wbMarkers || el.dataset.markers || "null");
+    markers = Array.isArray(parsed) ? parsed : [];
   } catch (e) {
   }
-  let markers = null;
+  markers = markers.map((m) => m && typeof m === "object" ? { ...m, time: Number(m.time) } : null).filter((m) => m && Number.isFinite(m.time));
+  let waveform = null;
   try {
-    markers = JSON.parse(el.dataset.wbMarkers || el.dataset.markers || "null");
+    const parsed = JSON.parse(el.dataset.wbWaveform || el.dataset.waveform || "null");
+    waveform = Array.isArray(parsed) ? parsed : null;
   } catch (e) {
   }
   return {
@@ -60,7 +81,7 @@ function parseTrackFromElement(el) {
     duration: el.dataset.wbDuration || el.dataset.duration || "",
     bpm: el.dataset.wbBpm || el.dataset.bpm || "",
     key: el.dataset.wbKey || el.dataset.key || "",
-    waveform: el.dataset.wbWaveform || el.dataset.waveform || "",
+    waveform,
     markers,
     favorited: el.dataset.wbFavorited === "true",
     inCart: el.dataset.wbInCart === "true",
@@ -132,7 +153,7 @@ function fireAction(actionConfig, payload) {
     try {
       actionConfig.endpoint(payload);
     } catch (err) {
-      console.warn("WaveformBar action callback error:", err);
+      console.warn("[WaveformBar] Action callback error:", err);
     }
     return;
   }
@@ -144,7 +165,7 @@ function fireAction(actionConfig, payload) {
         ...actionConfig.headers || {}
       },
       body: JSON.stringify(payload)
-    }).catch((err) => console.warn("WaveformBar action request failed:", err));
+    }).catch((err) => console.warn("[WaveformBar] Action request failed:", err));
   }
 }
 
@@ -202,11 +223,15 @@ function buildBarHTML(config) {
     }
     right += "</div>";
   }
+  if (config.share) {
+    right += `<button class="wb-btn wb-btn-sm wb-share" aria-label="Share" title="Copy share link">${ICONS.share}</button>`;
+  }
   if (config.showQueue) {
     right += `<button class="wb-btn wb-btn-sm wb-queue-btn" aria-label="Queue" title="Queue">${ICONS.queue}</button>`;
   }
   right += "</div>";
-  return `<div class="wb-inner">${left}${centre}${right}</div>`;
+  const collapse = config.collapsible ? `<button class="wb-btn wb-btn-sm wb-collapse" aria-label="Collapse" title="Collapse">${ICONS.collapse}</button>` : "";
+  return `<div class="wb-inner">${left}${centre}${right}${collapse}</div>`;
 }
 
 // src/js/queue.js
@@ -310,10 +335,27 @@ var DEFAULTS = {
   // URL to fallback artwork image
   theme: null,
   // 'dark', 'light', or null (dark by default)
+  wide: false,
+  // true = content spans full width (lifts the 1400px cap)
+  maxWidth: null,
+  // custom content max-width (CSS value), e.g. '1200px'; overrides `wide`
+  position: "bottom",
+  // 'bottom' (default) or 'top' — which edge the bar docks to
+  collapsible: false,
+  // show a collapse button that shrinks the bar to a floating transport pill
+  waveform: true,
+  // false = classic Spotify-style seek bar instead of the waveform
+  errorText: null,
+  // custom "audio failed to load" message (null = player default)
+  share: false,
+  // show a "copy share link" button (emits ?<shareParam>=<seconds>)
+  shareParam: "wt",
+  // URL query param for the shared timestamp (seconds)
   waveformStyle: "mirror",
   waveformHeight: 32,
   barWidth: 2,
-  barSpacing: 0,
+  barSpacing: 2,
+  // 2px gap between 2px bars — crisp, separated bars (0 = solid "blob")
   waveformColor: null,
   progressColor: null,
   markerColor: "rgba(255, 255, 255, 0.25)",
@@ -347,6 +389,9 @@ var WaveformBar = class {
     this._activeMarkers = null;
     this._currentMarkerIndex = -1;
     this.repeat = "off";
+    this._loadSeq = 0;
+    this._restoreSeekTimeout = null;
+    this._externalPlayers = /* @__PURE__ */ new Map();
     this.barEl = null;
     this.queueEl = null;
     this.waveformContainer = null;
@@ -377,9 +422,12 @@ var WaveformBar = class {
   init(config = {}) {
     if (this.isInitialized) this.destroy();
     this.config = { ...DEFAULTS, ...config };
-    this.volume = this.config.volume;
+    const v = Number(this.config.volume);
+    this.volume = Number.isFinite(v) ? Math.max(0, Math.min(1, v)) : 1;
+    this._shareTarget = this._readShareTarget();
+    this._shareSeek = this._shareTarget && !this._shareTarget.id && !this._shareTarget.url ? this._shareTarget.time : null;
     if (typeof window.WaveformPlayer === "undefined") {
-      console.error("WaveformBar: WaveformPlayer is required.");
+      console.error("[WaveformBar] WaveformPlayer is required.");
       return this;
     }
     this._createBar();
@@ -395,6 +443,10 @@ var WaveformBar = class {
     if (this.config.persist) {
       this._restoreState();
     }
+    if (this._shareTarget && (this._shareTarget.id || this._shareTarget.url)) {
+      const shared = this._resolveSharedTrack(this._shareTarget);
+      if (shared) this._loadSharedTrack(shared, this._shareTarget.time);
+    }
     this.isInitialized = true;
     this._beforeUnloadHandler = () => this._saveState();
     window.addEventListener("beforeunload", this._beforeUnloadHandler);
@@ -409,6 +461,37 @@ var WaveformBar = class {
       this.player.destroy();
       this.player = null;
     }
+    if (this._docClickVolume) {
+      document.removeEventListener("click", this._docClickVolume);
+      this._docClickVolume = null;
+    }
+    if (this._docClickQueue) {
+      document.removeEventListener("click", this._docClickQueue);
+      this._docClickQueue = null;
+    }
+    if (this._docClickTriggers) {
+      document.removeEventListener("click", this._docClickTriggers);
+      this._docClickTriggers = null;
+    }
+    if (this._externalListenersBound) {
+      document.removeEventListener("waveformplayer:request-play", this._onExtRequestPlay);
+      document.removeEventListener("waveformplayer:request-pause", this._onExtRequestPause);
+      document.removeEventListener("waveformplayer:request-seek", this._onExtRequestSeek);
+      document.removeEventListener("waveformplayer:destroy", this._onExtDestroy);
+      this._onExtRequestPlay = null;
+      this._onExtRequestPause = null;
+      this._onExtRequestSeek = null;
+      this._onExtDestroy = null;
+      this._externalListenersBound = false;
+    }
+    this._externalPlayers = /* @__PURE__ */ new Map();
+    if (this._restoreSeekTimeout) {
+      clearTimeout(this._restoreSeekTimeout);
+      this._restoreSeekTimeout = null;
+    }
+    clearTimeout(this._shareFlashTimeout);
+    this._shareFlashTimeout = null;
+    this._loadSeq++;
     if (this.barEl) {
       this.barEl.remove();
       this.barEl = null;
@@ -425,7 +508,22 @@ var WaveformBar = class {
       window.removeEventListener("beforeunload", this._beforeUnloadHandler);
       this._beforeUnloadHandler = null;
     }
-    document.querySelectorAll("[data-wb-play],[data-wb-queue]").forEach((el) => delete el._wbBound);
+    this.volumePopupEl = null;
+    this.queueBtnEl = null;
+    this.titleEl = null;
+    this.artistEl = null;
+    this.metaEl = null;
+    this.playBtnEl = null;
+    this.repeatBtnEl = null;
+    this.waveformContainer = null;
+    this.queueBodyEl = null;
+    this.queueCountEl = null;
+    this.muteBtnEl = null;
+    this.volumeSliderEl = null;
+    this.favBtnEl = null;
+    this.cartBtnEl = null;
+    this.timeCurrentEl = null;
+    this.timeTotalEl = null;
     document.querySelectorAll(".wb-current,.wb-playing").forEach((el) => el.classList.remove("wb-current", "wb-playing"));
     this.queue = [];
     this.currentIndex = -1;
@@ -444,6 +542,9 @@ var WaveformBar = class {
     const theme = this.config.theme || this._detectTheme();
     if (theme === "light") this.barEl.classList.add("wb-light");
     this._resolvedTheme = theme;
+    const maxWidth = this.config.maxWidth || (this.config.wide ? "100%" : null);
+    if (maxWidth) this.barEl.style.setProperty("--wb-max-width", maxWidth);
+    if (this.config.position === "top") this.barEl.classList.add("wb-top");
     this.barEl.id = "waveform-bar";
     this.barEl.innerHTML = buildBarHTML(this.config);
     document.body.appendChild(this.barEl);
@@ -453,17 +554,24 @@ var WaveformBar = class {
     this.playBtnEl = this.barEl.querySelector(".wb-play");
     this.waveformContainer = this.barEl.querySelector(".wb-waveform-container");
     this.queueBtnEl = this.barEl.querySelector(".wb-queue-btn");
+    this.shareBtnEl = this.barEl.querySelector(".wb-share");
     this.muteBtnEl = this.barEl.querySelector(".wb-mute");
     this.volumeSliderEl = this.barEl.querySelector(".wb-volume-slider");
     this.favBtnEl = this.barEl.querySelector(".wb-fav");
     this.cartBtnEl = this.barEl.querySelector(".wb-cart");
     this.timeCurrentEl = this.barEl.querySelector(".wb-time-current");
     this.timeTotalEl = this.barEl.querySelector(".wb-time-total");
+    this.collapseBtnEl = this.barEl.querySelector(".wb-collapse");
     this.playBtnEl.addEventListener("click", () => this.togglePlay());
+    if (this.collapseBtnEl) {
+      this.collapseBtnEl.addEventListener("click", () => this.toggleCollapse());
+      if (this._readCollapsed()) this.collapse();
+    }
     const prevBtn = this.barEl.querySelector(".wb-prev");
     const nextBtn = this.barEl.querySelector(".wb-next");
     if (prevBtn) prevBtn.addEventListener("click", () => this.previous());
     if (nextBtn) nextBtn.addEventListener("click", () => this.next());
+    if (this.shareBtnEl) this.shareBtnEl.addEventListener("click", () => this._share());
     this.repeatBtnEl = this.barEl.querySelector(".wb-repeat");
     if (this.repeatBtnEl) {
       this.repeat = this.config.repeat || "off";
@@ -495,17 +603,18 @@ var WaveformBar = class {
         this.setVolume(parseInt(e.target.value) / 100);
       });
     }
-    document.addEventListener("click", (e) => {
-      if (this.volumePopupEl?.classList.contains("wb-volume-open") && !this.barEl.querySelector(".wb-volume")?.contains(e.target)) {
+    this._docClickVolume = (e) => {
+      if (this.volumePopupEl?.classList.contains("wb-volume-open") && !this.barEl?.querySelector(".wb-volume")?.contains(e.target)) {
         this.closeVolumePopup();
       }
-    });
+    };
+    document.addEventListener("click", this._docClickVolume);
     if (this.favBtnEl) this.favBtnEl.addEventListener("click", () => this.toggleFavorite());
     if (this.cartBtnEl) this.cartBtnEl.addEventListener("click", () => this.addToCart());
     if (this.config.showTrackLink) {
       this.barEl.querySelector(".wb-track").addEventListener("click", () => {
         const t = this.getCurrentTrack();
-        if (t && t.link) window.location.href = t.link;
+        if (t && t.link && isSafeHref(t.link)) window.location.href = t.link;
       });
     }
   }
@@ -517,20 +626,26 @@ var WaveformBar = class {
     this.queueBodyEl = this.queueEl.querySelector(".wb-queue-body");
     this.queueCountEl = this.queueEl.querySelector(".wb-queue-count");
     this.queueEl.querySelector(".wb-queue-clear").addEventListener("click", () => this.clearQueue());
-    document.addEventListener("click", (e) => {
-      if (this.queueOpen && !this.queueEl.contains(e.target) && !this.queueBtnEl.contains(e.target)) {
+    this._docClickQueue = (e) => {
+      if (this.queueOpen && !this.queueEl?.contains(e.target) && !this.queueBtnEl?.contains(e.target)) {
         this.closeQueuePanel();
       }
-    });
+    };
+    document.addEventListener("click", this._docClickQueue);
   }
   _initPlayer() {
     const opts = {
       showControls: false,
       showInfo: false,
-      waveformStyle: this.config.waveformStyle,
+      // Classic mode reuses the player's own built-in 'seekbar' style —
+      // a simple rounded progress bar (no waveform), with the player's
+      // native click-to-seek. No custom seek-bar DOM needed.
+      waveformStyle: this.config.waveform === false ? "seekbar" : this.config.waveformStyle,
       height: this.config.waveformHeight,
       barWidth: this.config.barWidth,
       barSpacing: this.config.barSpacing,
+      errorText: this.config.errorText,
+      // null -> player uses its own default
       singlePlay: false,
       onPlay: () => {
         this.isPlaying = true;
@@ -573,6 +688,18 @@ var WaveformBar = class {
           this._loadCurrentTrack();
         }
       },
+      onError: () => {
+        this.isPlaying = false;
+        this._updatePlayButton();
+        this._syncPageState();
+        this._pumpExternalPlayState(false);
+        const track = this.getCurrentTrack();
+        this._emit("error", { track });
+        if (this.config.continuous && this.currentIndex < this.queue.length - 1) {
+          this.currentIndex++;
+          this._loadCurrentTrack();
+        }
+      },
       onTimeUpdate: (currentTime, duration) => {
         this._lastPosition = currentTime;
         if (this.timeCurrentEl) this.timeCurrentEl.textContent = formatTime(currentTime);
@@ -586,7 +713,12 @@ var WaveformBar = class {
           this._checkMarkerBoundary(currentTime);
         }
       },
-      onLoad: null
+      onLoad: () => {
+        if (this._shareSeek != null && this.player) {
+          this.player.seekTo(this._shareSeek);
+          this._shareSeek = null;
+        }
+      }
     };
     if (this.config.waveformColor) opts.waveformColor = this.config.waveformColor;
     if (this.config.progressColor) opts.progressColor = this.config.progressColor;
@@ -597,25 +729,24 @@ var WaveformBar = class {
   // Triggers (private)
   // =====================================================================
   _bindTriggers() {
-    document.querySelectorAll("[data-wb-play]").forEach((el) => {
-      if (el._wbBound) return;
-      el._wbBound = true;
-      el.addEventListener("click", (e) => {
-        e.preventDefault();
-        const track = parseTrackFromElement(el);
-        if (track) this.play(track);
-      });
-    });
-    document.querySelectorAll("[data-wb-queue]").forEach((el) => {
-      if (el._wbBound) return;
-      el._wbBound = true;
-      el.addEventListener("click", (e) => {
-        e.preventDefault();
-        e.stopPropagation();
-        const track = parseTrackFromElement(el);
-        if (track) this.addToQueue(track);
-      });
-    });
+    if (!this._docClickTriggers) {
+      this._docClickTriggers = (e) => {
+        const queueEl = e.target?.closest?.("[data-wb-queue]");
+        if (queueEl) {
+          e.preventDefault();
+          const track = parseTrackFromElement(queueEl);
+          if (track) this.addToQueue(track);
+          return;
+        }
+        const playEl = e.target?.closest?.("[data-wb-play]");
+        if (playEl) {
+          e.preventDefault();
+          const track = parseTrackFromElement(playEl);
+          if (track) this.play(track);
+        }
+      };
+      document.addEventListener("click", this._docClickTriggers);
+    }
     this._attachExternalPlayers();
   }
   /**
@@ -633,13 +764,13 @@ var WaveformBar = class {
   _attachExternalPlayers() {
     if (!this._externalListenersBound) {
       this._externalListenersBound = true;
-      document.addEventListener("waveformplayer:request-play", (e) => {
+      this._onExtRequestPlay = (e) => {
         const t = e.detail;
         if (!t || !t.url) return;
         e.preventDefault();
         this.play(t);
-      });
-      document.addEventListener("waveformplayer:request-pause", (e) => {
+      };
+      this._onExtRequestPause = (e) => {
         const t = e.detail;
         if (!t || !t.url) return;
         const current = this.getCurrentTrack();
@@ -647,8 +778,8 @@ var WaveformBar = class {
           e.preventDefault();
           if (this.isPlaying) this.togglePlay();
         }
-      });
-      document.addEventListener("waveformplayer:request-seek", (e) => {
+      };
+      this._onExtRequestSeek = (e) => {
         const t = e.detail;
         if (!t || !t.url || typeof t.percent !== "number") return;
         const current = this.getCurrentTrack();
@@ -656,7 +787,16 @@ var WaveformBar = class {
           e.preventDefault();
           this.player.seekToPercent(t.percent);
         }
-      });
+      };
+      this._onExtDestroy = (e) => {
+        const inst = e.detail && e.detail.player;
+        if (!inst || !this._externalPlayers) return;
+        this._externalPlayers.forEach((set) => set.delete(inst));
+      };
+      document.addEventListener("waveformplayer:request-play", this._onExtRequestPlay);
+      document.addEventListener("waveformplayer:request-pause", this._onExtRequestPause);
+      document.addEventListener("waveformplayer:request-seek", this._onExtRequestSeek);
+      document.addEventListener("waveformplayer:destroy", this._onExtDestroy);
     }
     const previous = this._externalPlayers || /* @__PURE__ */ new Map();
     this._externalPlayers = /* @__PURE__ */ new Map();
@@ -733,7 +873,7 @@ var WaveformBar = class {
   _observeDOM() {
     if (typeof MutationObserver === "undefined") return;
     this._observer = new MutationObserver(() => {
-      this._bindTriggers();
+      this._attachExternalPlayers();
       this._syncPageState();
     });
     this._observer.observe(document.body, { childList: true, subtree: true });
@@ -880,6 +1020,7 @@ var WaveformBar = class {
       this.isMuted = true;
       if (this.player) this.player.setVolume(0);
       this._updateVolumeUI();
+      saveVolume(this.config.storageKey, this.volume, this.isMuted, this._volumeBeforeMute);
     }
     return this;
   }
@@ -919,7 +1060,9 @@ var WaveformBar = class {
     this._cartItems.add(id);
     if (this.cartBtnEl) {
       this.cartBtnEl.classList.add("wb-action-done");
-      setTimeout(() => this.cartBtnEl.classList.remove("wb-action-done"), 1500);
+      setTimeout(() => {
+        if (this.cartBtnEl) this.cartBtnEl.classList.remove("wb-action-done");
+      }, 1500);
     }
     this._syncCartAttributes(track.url, true);
     this._emit("cart", { track });
@@ -1081,9 +1224,252 @@ var WaveformBar = class {
   // =====================================================================
   // Internal: Loading & Display
   // =====================================================================
+  /**
+   * Parse a share link from the URL: the timestamp (`?<shareParam>=`, seconds)
+   * plus the track identity needed to load it cold — `?wid` (id, preferred),
+   * `?wu` (url, the works-anywhere fallback), and `?wtitle`/`?wartist` for
+   * display before metadata arrives. Returns null when no share params are
+   * present. An unsafe `?wu` (javascript:/data: etc.) is dropped, not loaded.
+   * @returns {{time:number, id:string|null, url:string|null, title:string|null, artist:string|null}|null}
+   * @private
+   */
+  _readShareTarget() {
+    let q;
+    try {
+      q = new URLSearchParams(window.location.search);
+    } catch (e) {
+      return null;
+    }
+    const rawTime = q.get(this.config.shareParam);
+    const id = q.get("wid");
+    const rawUrl = q.get("wu");
+    if (rawTime == null && id == null && rawUrl == null) return null;
+    let time = 0;
+    if (rawTime != null) {
+      const t = Number(rawTime);
+      if (Number.isFinite(t) && t >= 0) time = t;
+    }
+    const url = rawUrl && isSafeHref(rawUrl) ? rawUrl : null;
+    return { time, id: id || null, url, title: q.get("wtitle"), artist: q.get("wartist") };
+  }
+  /**
+   * Resolve a share target to a loadable track. Prefers an on-page trigger
+   * (matched by `data-wb-id`, then by url) so the cold load inherits the
+   * page's pre-generated peaks, markers, and favorite/cart state; falls back
+   * to a minimal track built from the embedded url + title/artist so the link
+   * still works on a page that doesn't contain the track.
+   * @param {{id:string|null, url:string|null, title:string|null, artist:string|null}} target
+   * @returns {Object|null}
+   * @private
+   */
+  _resolveSharedTrack(target) {
+    const triggers = document.querySelectorAll("[data-wb-play], [data-wb-queue]");
+    if (target.id) {
+      for (const el of triggers) {
+        if (el.dataset.wbId === target.id || el.dataset.id === target.id) {
+          const t = parseTrackFromElement(el);
+          if (t) return t;
+        }
+      }
+    }
+    if (target.url) {
+      for (const el of triggers) {
+        if (el.dataset.wbUrl === target.url || el.dataset.url === target.url) {
+          const t = parseTrackFromElement(el);
+          if (t) return t;
+        }
+      }
+      return {
+        url: target.url,
+        id: target.id || target.url,
+        title: target.title || extractTitle(target.url),
+        artist: target.artist || ""
+      };
+    }
+    return null;
+  }
+  /**
+   * Cold-load a share-target track at a timestamp, paused. Mirrors the
+   * restore path (loadTrack with autoplay:false + a `_loadSeq`-guarded,
+   * delayed seek) so a later user action cleanly supersedes it.
+   * @param {Object} track
+   * @param {number} time - seconds to seek to once loaded
+   * @private
+   */
+  _loadSharedTrack(track, time) {
+    if (!track || !track.url || !this.player) return;
+    const existing = this.queue.findIndex((t) => t.url === track.url);
+    if (existing >= 0) {
+      this.queue[existing] = { ...this.queue[existing], ...track };
+      this.currentIndex = existing;
+    } else {
+      this.queue.push(track);
+      this.currentIndex = this.queue.length - 1;
+    }
+    this.show();
+    this._updateTrackDisplay(track);
+    this._updateFavoriteUI();
+    this._updateNavButtons();
+    const loadOpts = { autoplay: false };
+    if (track.waveform) loadOpts.waveform = track.waveform;
+    if (track.markers && track.markers.length) {
+      const defaultColor = this.config.markerColor;
+      loadOpts.markers = track.markers.map((m) => ({ ...m, color: m.color || defaultColor }));
+      this._activeMarkers = track.markers;
+    } else {
+      loadOpts.markers = [];
+      this._activeMarkers = null;
+    }
+    this._currentMarkerIndex = -1;
+    const seq = ++this._loadSeq;
+    if (this._restoreSeekTimeout) {
+      clearTimeout(this._restoreSeekTimeout);
+      this._restoreSeekTimeout = null;
+    }
+    this.player.loadTrack(track.url, track.title, track.artist, loadOpts).then(() => {
+      if (this._loadSeq !== seq) return;
+      if (this.player) this.player.setVolume(this.isMuted ? 0 : this.volume);
+      if (time > 0) {
+        this._restoreSeekTimeout = setTimeout(() => {
+          this._restoreSeekTimeout = null;
+          if (this._loadSeq !== seq) return;
+          if (this.player) {
+            this.player.seekTo(time);
+            this._lastPosition = time;
+          }
+        }, 100);
+      }
+    }).catch(() => {
+    });
+    this._renderQueue();
+    this._syncPageState();
+    this._saveState();
+    this._updateNavButtons();
+    this._emit("trackchange", { track, index: this.currentIndex });
+    if (this.config.onTrackChange) this.config.onTrackChange(track, this.currentIndex);
+  }
+  /**
+   * Copy a shareable link to the current track at the current position, use
+   * the native share sheet when available, and emit `waveformbar:share`. The
+   * link carries both the timestamp AND the track identity so a cold open
+   * loads the right audio: `?<shareParam>=<seconds>` plus `wid` (id, when the
+   * track has a real one), `wu` (url — the works-anywhere fallback), and
+   * `wtitle`/`wartist` for display before metadata loads.
+   * @private
+   */
+  _share() {
+    const track = this.getCurrentTrack();
+    const cur = this.player && this.player.audio ? this.player.audio.currentTime : 0;
+    const seconds = Math.max(0, Math.floor(cur || 0));
+    let link;
+    try {
+      const url = new URL(window.location.href);
+      const p = url.searchParams;
+      p.set(this.config.shareParam, String(seconds));
+      if (track) {
+        if (track.id && track.id !== track.url) p.set("wid", track.id);
+        if (track.url) p.set("wu", track.url);
+        if (track.title) p.set("wtitle", track.title);
+        if (track.artist) p.set("wartist", track.artist);
+      }
+      link = url.toString();
+    } catch (e) {
+      return;
+    }
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      navigator.clipboard.writeText(link).catch(() => {
+      });
+    }
+    if (navigator.share) {
+      navigator.share({ title: track && track.title || void 0, url: link }).catch(() => {
+      });
+    }
+    this._flashShareCopied();
+    this._emit("share", { url: link, time: seconds, track });
+  }
+  /**
+   * Briefly flag the share button as "copied" for visual feedback.
+   * @private
+   */
+  _flashShareCopied() {
+    if (!this.shareBtnEl) return;
+    this.shareBtnEl.classList.add("wb-copied");
+    this.shareBtnEl.setAttribute("title", "Link copied!");
+    clearTimeout(this._shareFlashTimeout);
+    this._shareFlashTimeout = setTimeout(() => {
+      if (this.shareBtnEl) {
+        this.shareBtnEl.classList.remove("wb-copied");
+        this.shareBtnEl.setAttribute("title", "Copy share link");
+      }
+    }, 1500);
+  }
+  /**
+   * Collapse the bar to a small floating pill (artwork + play + expand).
+   * @returns {WaveformBar}
+   */
+  collapse() {
+    this.isCollapsed = true;
+    if (this.barEl) this.barEl.classList.add("wb-collapsed");
+    this._updateCollapseButton();
+    this._saveCollapsed();
+    this._emit("collapse", { collapsed: true });
+    return this;
+  }
+  /**
+   * Restore the bar from its collapsed pill back to the full bar.
+   * @returns {WaveformBar}
+   */
+  expand() {
+    this.isCollapsed = false;
+    if (this.barEl) this.barEl.classList.remove("wb-collapsed");
+    this._updateCollapseButton();
+    this._saveCollapsed();
+    this._emit("collapse", { collapsed: false });
+    return this;
+  }
+  /**
+   * Toggle the collapsed pill state.
+   * @returns {WaveformBar}
+   */
+  toggleCollapse() {
+    return this.isCollapsed ? this.expand() : this.collapse();
+  }
+  /**
+   * Swap the collapse button's icon + labels for the current state.
+   * @private
+   */
+  _updateCollapseButton() {
+    if (!this.collapseBtnEl) return;
+    this.collapseBtnEl.innerHTML = this.isCollapsed ? ICONS.expand : ICONS.collapse;
+    const label = this.isCollapsed ? "Expand" : "Collapse";
+    this.collapseBtnEl.setAttribute("aria-label", label);
+    this.collapseBtnEl.setAttribute("title", label);
+  }
+  /** Persist the collapsed state (session-scoped) when persistence is on. @private */
+  _saveCollapsed() {
+    if (!this.config.persist) return;
+    try {
+      sessionStorage.setItem(this.config.storageKey + "-collapsed", this.isCollapsed ? "1" : "0");
+    } catch (e) {
+    }
+  }
+  /** Read the persisted collapsed state. @returns {boolean} @private */
+  _readCollapsed() {
+    if (!this.config.persist) return false;
+    try {
+      return sessionStorage.getItem(this.config.storageKey + "-collapsed") === "1";
+    } catch (e) {
+      return false;
+    }
+  }
   _loadCurrentTrack() {
     const track = this.getCurrentTrack();
     if (!track || !this.player) return;
+    this._loadSeq++;
+    if (this._restoreSeekTimeout) {
+      clearTimeout(this._restoreSeekTimeout);
+      this._restoreSeekTimeout = null;
+    }
     this._pumpExternalPlayState(false);
     this.show();
     this._updateTrackDisplay(track);
@@ -1248,7 +1634,7 @@ var WaveformBar = class {
     }
     if (marker.artwork) {
       const artworkEl = this.barEl.querySelector(".wb-artwork");
-      if (artworkEl) artworkEl.innerHTML = `<img src="${marker.artwork}" alt="${marker.title || ""}" />`;
+      if (artworkEl) artworkEl.innerHTML = `<img src="${escapeHtml(marker.artwork)}" alt="${escapeHtml(marker.title || "")}" />`;
     }
     if (this.metaEl && (marker.bpm || marker.key)) {
       const metaTrack = {
@@ -1429,24 +1815,27 @@ var WaveformBar = class {
     this._updateTrackDisplay(track);
     this._updateFavoriteUI();
     this._updateNavButtons();
-    if (track.waveform) {
-      this.player.options.waveform = track.waveform;
-    }
-    this.player.options.title = track.title || "";
-    this.player.options.subtitle = track.artist || "";
+    const loadOpts = { autoplay: false };
+    if (track.waveform) loadOpts.waveform = track.waveform;
     if (track.markers && track.markers.length) {
       const defaultColor = this.config.markerColor;
-      this.player.options.markers = track.markers.map((m) => ({
+      loadOpts.markers = track.markers.map((m) => ({
         ...m,
         color: m.color || defaultColor
       }));
       this._activeMarkers = track.markers;
     } else {
-      this.player.options.markers = [];
+      loadOpts.markers = [];
       this._activeMarkers = null;
     }
     this._currentMarkerIndex = -1;
-    this.player.load(track.url).then(() => {
+    const seq = ++this._loadSeq;
+    if (this._restoreSeekTimeout) {
+      clearTimeout(this._restoreSeekTimeout);
+      this._restoreSeekTimeout = null;
+    }
+    this.player.loadTrack(track.url, track.title, track.artist, loadOpts).then(() => {
+      if (this._loadSeq !== seq) return;
       if (this.player) this.player.setVolume(this.isMuted ? 0 : this.volume);
       if (state.isPlaying && this.config.autoResume) {
         try {
@@ -1465,7 +1854,9 @@ var WaveformBar = class {
         }
       }
       if (state.position > 0) {
-        setTimeout(() => {
+        this._restoreSeekTimeout = setTimeout(() => {
+          this._restoreSeekTimeout = null;
+          if (this._loadSeq !== seq) return;
           if (this.player) {
             this.player.seekTo(state.position);
             this._lastPosition = state.position;
@@ -1480,7 +1871,8 @@ var WaveformBar = class {
   _restoreVolume() {
     const data = restoreVolume(this.config.storageKey);
     if (!data) return;
-    this.volume = data.volume;
+    const v = Number(data.volume);
+    this.volume = Number.isFinite(v) ? Math.max(0, Math.min(1, v)) : 1;
     this.isMuted = data.muted;
     this._volumeBeforeMute = data.volumeBeforeMute;
     if (this.player) this.player.setVolume(this.isMuted ? 0 : this.volume);