@arraypress/waveform-bar 1.3.1 → 1.4.0

package/src/js/core.js

@@ -4,7 +4,7 @@
  */
 
 import {ICONS} from './icons.js';
-import {extractTitle, escapeHtml, formatTime, parseTrackFromElement} from './utils.js';
+import {extractTitle, escapeHtml, formatTime, parseTrackFromElement, isSafeHref} from './utils.js';
 import {
     saveQueueState,
     restoreQueueState,
@@ -36,10 +36,18 @@ const DEFAULTS = {
     maxMeta: 3,
     defaultArtwork: null,   // 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)',
@@ -75,6 +83,15 @@ export class WaveformBar {
         this._currentMarkerIndex = -1;
         this.repeat = 'off'; // 'off', 'all', 'one'
 
+        // Load-race guard: bumped before every track load so async
+        // continuations (loadTrack().then / restore-seek timeout) can detect
+        // that a newer load superseded them and bail out.
+        this._loadSeq = 0;
+        this._restoreSeekTimeout = null;
+
+        // Map<url, Set<WaveformPlayer>> of external-mode visual surfaces.
+        this._externalPlayers = new Map();
+
         // DOM refs
         this.barEl = null;
         this.queueEl = null;
@@ -109,10 +126,24 @@ export class WaveformBar {
         if (this.isInitialized) this.destroy();
 
         this.config = {...DEFAULTS, ...config};
-        this.volume = this.config.volume;
+
+        // Normalize volume from config — guard NaN / out-of-range so a bad
+        // value can't mute the player or throw downstream.
+        const v = Number(this.config.volume);
+        this.volume = Number.isFinite(v) ? Math.max(0, Math.min(1, v)) : 1;
+
+        // Shareable timestamp: parse the share link's `?<shareParam>=<seconds>`
+        // (time) plus the track identity (`?wid` = id, `?wu` = url fallback,
+        // `?wtitle`/`?wartist` for display). When the link names a track we
+        // cold-load it below; a bare `?<shareParam>=` with no track just seeks
+        // whatever loads first (applied once in the player onLoad hook).
+        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;
         }
 
@@ -135,6 +166,15 @@ export class WaveformBar {
             this._restoreState();
         }
 
+        // A share link that names a track (`?wid`/`?wu`) cold-loads it here —
+        // AFTER restore, so the shared track wins over the visitor's own last
+        // session. It loads paused at the shared timestamp (autoplay is blocked
+        // on a cold page open anyway, and landing cued is the right UX).
+        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;
 
         // Save exact position when navigating away
@@ -153,6 +193,45 @@ export class WaveformBar {
             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;
+        }
+        // Single delegated trigger listener (replaces per-element binding).
+        if (this._docClickTriggers) {
+            document.removeEventListener('click', this._docClickTriggers);
+            this._docClickTriggers = null;
+        }
+        // External-mode WaveformPlayer document listeners — previously
+        // anonymous and never removed. Stored on `this` so they can be torn
+        // down and the bind flag reset for a clean re-init.
+        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 = new Map();
+
+        // Cancel pending async work that could touch torn-down refs.
+        if (this._restoreSeekTimeout) {
+            clearTimeout(this._restoreSeekTimeout);
+            this._restoreSeekTimeout = null;
+        }
+        clearTimeout(this._shareFlashTimeout);
+        this._shareFlashTimeout = null;
+        // Invalidate any in-flight load continuation.
+        this._loadSeq++;
+
         if (this.barEl) {
             this.barEl.remove();
             this.barEl = null;
@@ -170,7 +249,24 @@ export class WaveformBar {
             this._beforeUnloadHandler = null;
         }
 
-        document.querySelectorAll('[data-wb-play],[data-wb-queue]').forEach(el => delete el._wbBound);
+        // Null cached DOM refs so a stale ref can't be poked after teardown.
+        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 = [];
@@ -195,6 +291,14 @@ export class WaveformBar {
         if (theme === 'light') this.barEl.classList.add('wb-light');
         this._resolvedTheme = theme;
 
+        // Layout width: `maxWidth` wins; else `wide` lifts the cap to full width.
+        // Default (neither set) leaves the stylesheet's 1400px cap in place.
+        const maxWidth = this.config.maxWidth || (this.config.wide ? '100%' : null);
+        if (maxWidth) this.barEl.style.setProperty('--wb-max-width', maxWidth);
+
+        // Dock to the top edge instead of the bottom (flips slide direction).
+        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);
@@ -206,20 +310,29 @@ export class WaveformBar {
         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');
 
         // Bind controls
         this.playBtnEl.addEventListener('click', () => this.togglePlay());
 
+        // Collapse-to-pill toggle.
+        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) {
@@ -259,13 +372,16 @@ export class WaveformBar {
             });
         }
 
-        // Close volume popup on outside click
-        document.addEventListener('click', (e) => {
+        // Close volume popup on outside click.
+        // Stored on `this` so destroy() can remove it — otherwise every
+        // re-init (init() calls destroy() first) leaks another listener.
+        this._docClickVolume = (e) => {
             if (this.volumePopupEl?.classList.contains('wb-volume-open') &&
-                !this.barEl.querySelector('.wb-volume')?.contains(e.target)) {
+                !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());
@@ -274,7 +390,9 @@ export class WaveformBar {
         if (this.config.showTrackLink) {
             this.barEl.querySelector('.wb-track').addEventListener('click', () => {
                 const t = this.getCurrentTrack();
-                if (t && t.link) window.location.href = t.link;
+                // Guard the scheme — a `data-wb-link="javascript:…"` value
+                // would otherwise execute on navigation (open-redirect / XSS).
+                if (t && t.link && isSafeHref(t.link)) window.location.href = t.link;
             });
         }
     }
@@ -291,21 +409,28 @@ export class WaveformBar {
 
         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)) {
+        // Stored on `this` so destroy() can remove it — otherwise every
+        // re-init leaks another document listener.
+        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;
@@ -356,6 +481,26 @@ export class WaveformBar {
                     this._loadCurrentTrack();
                 }
             },
+            onError: () => {
+                // A track failed to load/decode (bad URL, 404, codec). Without
+                // this the queue dead-stops on the broken entry. Reset play
+                // state, notify, and — when continuous — skip to the next
+                // entry so one dead track doesn't halt the whole queue.
+                this.isPlaying = false;
+                this._updatePlayButton();
+                this._syncPageState();
+                this._pumpExternalPlayState(false);
+
+                const track = this.getCurrentTrack();
+                this._emit('error', {track});
+
+                // Auto-advance like onEnd (but never wrap via repeat-all —
+                // that risks an infinite loop if the first track is also dead).
+                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);
@@ -377,7 +522,14 @@ export class WaveformBar {
                     this._checkMarkerBoundary(currentTime);
                 }
             },
-            onLoad: null
+            onLoad: () => {
+                // Apply a shareable-timestamp seek (?<shareParam>=) once, on the
+                // first track load after a fresh page open.
+                if (this._shareSeek != null && this.player) {
+                    this.player.seekTo(this._shareSeek);
+                    this._shareSeek = null;
+                }
+            }
         };
 
         if (this.config.waveformColor) opts.waveformColor = this.config.waveformColor;
@@ -392,26 +544,34 @@ export class WaveformBar {
     // =====================================================================
 
     _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);
-            });
-        });
+        // ONE delegated document listener instead of per-element binding.
+        // Per-element listeners leaked on every re-init (init() → destroy()
+        // only cleared a flag, never removed the handlers), leaving each row
+        // with stacked handlers that toggled each other so clicks did nothing.
+        // Delegation also covers late-mounted triggers for free, so the
+        // MutationObserver no longer needs to re-bind anything.
+        if (!this._docClickTriggers) {
+            this._docClickTriggers = (e) => {
+                // Queue first — a queue trigger nested in (or alongside) a
+                // play trigger must enqueue, not play. This mirrors the old
+                // per-element handler's stopPropagation() semantics.
+                const queueEl = e.target?.closest?.('[data-wb-queue]');
+                if (queueEl) {
+                    e.preventDefault();
+                    const track = parseTrackFromElement(queueEl);
+                    if (track) this.addToQueue(track);
+                    return;
+                }
 
-        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);
-            });
-        });
+                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);
+        }
 
         // External-mode WaveformPlayer instances on the page act as
         // visualization surfaces controlled by this bar — see the
@@ -435,18 +595,20 @@ export class WaveformBar {
      * @private
      */
     _attachExternalPlayers() {
-        // Document-level listeners only bind once.
+        // Document-level listeners only bind once. Stored on `this` so
+        // destroy() can remove them (they were previously anonymous and
+        // leaked across re-inits).
         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;
                 // Only honour pause when this is the currently-playing
@@ -456,9 +618,9 @@ export class WaveformBar {
                     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();
@@ -466,7 +628,20 @@ export class WaveformBar {
                     e.preventDefault();
                     this.player.seekToPercent(t.percent);
                 }
-            });
+            };
+
+            // Prune a destroyed external player from the URL → players map
+            // so we don't keep pumping state into a torn-down instance.
+            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);
         }
 
         // Rebuild the URL → players map from scratch each pass — cheap
@@ -559,8 +734,12 @@ export class WaveformBar {
 
     _observeDOM() {
         if (typeof MutationObserver === 'undefined') return;
+        // Triggers are handled by the single delegated listener, so the
+        // observer only needs to (re)discover late-mounted external-mode
+        // players and re-sync page state.
+        // TODO(harden): debounce this callback.
         this._observer = new MutationObserver(() => {
-            this._bindTriggers();
+            this._attachExternalPlayers();
             this._syncPageState();
         });
         this._observer.observe(document.body, {childList: true, subtree: true});
@@ -735,6 +914,9 @@ export class WaveformBar {
             this.isMuted = true;
             if (this.player) this.player.setVolume(0);
             this._updateVolumeUI();
+            // Persist the muted flag — the unmute branch routes through
+            // setVolume() (which saves), so mute must save too.
+            saveVolume(this.config.storageKey, this.volume, this.isMuted, this._volumeBeforeMute);
         }
         return this;
     }
@@ -782,7 +964,9 @@ export class WaveformBar {
         // Visual feedback on bar button
         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);
         }
 
         // Sync data attribute back to page triggers
@@ -973,10 +1157,285 @@ export class WaveformBar {
     // 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;
+        }
+        // Only honour an embedded url that's a safe http(s)/relative target —
+        // the value is attacker-controllable, so never let it be javascript:.
+        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]');
+
+        // 1. By id (clean, short links). Skips when no id was shared.
+        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;
+                }
+            }
+        }
+
+        // 2. By url — match an on-page trigger to inherit its peaks/state...
+        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;
+                }
+            }
+            // 3. ...else build a minimal track straight from the link (cross-page).
+            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;
+
+        // Make it the current queue entry (dedup by url, like play()).
+        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);
+            // Seek slightly after load — the audio element needs to be ready
+            // for the seek to stick (same 100ms guard the restore path uses).
+            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) {
+                // id falls back to url internally, so only emit wid when it's a
+                // real, distinct identifier (clean per-track-page links).
+                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) || undefined, 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;
 
+        // Bump the load token and cancel any pending restore-seek so a
+        // stale async continuation (from a prior load) can't apply to this
+        // newer track under rapid switching.
+        this._loadSeq++;
+        if (this._restoreSeekTimeout) {
+            clearTimeout(this._restoreSeekTimeout);
+            this._restoreSeekTimeout = null;
+        }
+
         // Reset any previously-current external player so its UI flips
         // back to "paused" while the new track loads. The new track's
         // onPlay callback will set the matching external to playing
@@ -1188,7 +1647,7 @@ export class WaveformBar {
         // Update artwork if provided
         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 || '')}" />`;
         }
 
         // Update meta tags if bpm/key provided
@@ -1411,30 +1870,38 @@ export class WaveformBar {
         this._updateFavoriteUI();
         this._updateNavButtons();
 
-        // Use load() instead of loadTrack() to avoid auto-play.
-        // We handle seek and play manually after the audio is ready.
-        if (track.waveform) {
-            this.player.options.waveform = track.waveform;
-        }
-
-        this.player.options.title = track.title || '';
-        this.player.options.subtitle = track.artist || '';
+        // Use the public loadTrack() API with { autoplay: false } (core
+        // v1.8.0+) instead of poking player.options.* + load(). This avoids
+        // loadTrack's forced auto-play while still routing through the
+        // supported API — we handle seek and resume manually below.
+        const loadOpts = {autoplay: false};
+        if (track.waveform) loadOpts.waveform = track.waveform;
 
         // Pass markers to the player and set up DJ mode
         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(() => {
+        // Capture the load token so the async continuation below bails out if
+        // a newer load (user clicked another track, or destroy()) supersedes
+        // this restore before its promise / seek-timeout fires.
+        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) {
@@ -1457,7 +1924,9 @@ export class WaveformBar {
             // Seek after play — the audio element needs to be in a playing
             // or ready state for seek to stick reliably
             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;
@@ -1474,7 +1943,10 @@ export class WaveformBar {
     _restoreVolume() {
         const data = restoreVolume(this.config.storageKey);
         if (!data) return;
-        this.volume = data.volume;
+        // Normalize persisted volume — a corrupted store could otherwise
+        // carry NaN / out-of-range and mute or break the player.
+        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);