@arraypress/waveform-bar 1.3.1 → 1.4.0

package/dist/waveform-bar.js

@@ -6,7 +6,10 @@
     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>',
@@ -31,6 +34,15 @@
     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);
@@ -42,12 +54,21 @@
     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 {
@@ -61,7 +82,7 @@
       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",
@@ -133,7 +154,7 @@
       try {
         actionConfig.endpoint(payload);
       } catch (err) {
-        console.warn("WaveformBar action callback error:", err);
+        console.warn("[WaveformBar] Action callback error:", err);
       }
       return;
     }
@@ -145,7 +166,7 @@
           ...actionConfig.headers || {}
         },
         body: JSON.stringify(payload)
-      }).catch((err) => console.warn("WaveformBar action request failed:", err));
+      }).catch((err) => console.warn("[WaveformBar] Action request failed:", err));
     }
   }
 
@@ -203,11 +224,15 @@
       }
       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
@@ -311,10 +336,27 @@
     // 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)",
@@ -348,6 +390,9 @@
       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;
@@ -378,9 +423,12 @@
     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();
@@ -396,6 +444,10 @@
       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);
@@ -410,6 +462,37 @@
         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;
@@ -426,7 +509,22 @@
         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;
@@ -445,6 +543,9 @@
       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);
@@ -454,17 +555,24 @@
       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";
@@ -496,17 +604,18 @@
           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;
         });
       }
     }
@@ -518,20 +627,26 @@
       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;
@@ -574,6 +689,18 @@
             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);
@@ -587,7 +714,12 @@
             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;
@@ -598,25 +730,24 @@
     // 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();
     }
     /**
@@ -634,13 +765,13 @@
     _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();
@@ -648,8 +779,8 @@
             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();
@@ -657,7 +788,16 @@
             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();
@@ -734,7 +874,7 @@
     _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 });
@@ -881,6 +1021,7 @@
         this.isMuted = true;
         if (this.player) this.player.setVolume(0);
         this._updateVolumeUI();
+        saveVolume(this.config.storageKey, this.volume, this.isMuted, this._volumeBeforeMute);
       }
       return this;
     }
@@ -920,7 +1061,9 @@
       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 });
@@ -1082,9 +1225,252 @@
     // =====================================================================
     // 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);
@@ -1249,7 +1635,7 @@
       }
       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 = {
@@ -1430,24 +1816,27 @@
       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 {
@@ -1466,7 +1855,9 @@
           }
         }
         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;
@@ -1481,7 +1872,8 @@
     _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);