@vanduo-oss/framework 1.3.0 → 1.3.2

package/dist/vanduo.esm.js

@@ -1,4 +1,4 @@
-/*! Vanduo v1.3.0 | Built: 2026-03-17T16:46:03.216Z | git:ea44b23 | development */
+/*! Vanduo v1.3.2 | Built: 2026-04-06T19:04:41.601Z | git:8e08b38 | development */
 
 // js/utils/lifecycle.js
 (function() {
@@ -107,7 +107,7 @@
 // js/vanduo.js
 (function() {
   "use strict";
-  const VANDUO_VERSION = true ? "1.3.0" : "0.0.0-dev";
+  const VANDUO_VERSION = true ? "1.3.2" : "0.0.0-dev";
   const Vanduo2 = {
     version: VANDUO_VERSION,
     components: {},
@@ -418,16 +418,17 @@
       }
       const codeElement = activePane.querySelector("code") || activePane;
       const code = codeElement.textContent;
+      let copySuccess;
       try {
         await navigator.clipboard.writeText(code);
-        this.showCopyFeedback(copyBtn, true);
+        copySuccess = true;
       } catch (_err) {
-        const success = this.fallbackCopy(code);
-        this.showCopyFeedback(copyBtn, success);
+        copySuccess = this.fallbackCopy(code);
       }
+      this.showCopyFeedback(copyBtn, copySuccess);
       const event = new CustomEvent("codesnippet:copy", {
         bubbles: true,
-        detail: { snippet, code, success: true }
+        detail: { snippet, code, success: copySuccess }
       });
       snippet.dispatchEvent(event);
     },
@@ -864,9 +865,6 @@
   const Dropdown = {
     // Store initialized dropdowns and their cleanup functions
     instances: /* @__PURE__ */ new Map(),
-    // Typeahead state
-    _typeaheadBuffer: "",
-    _typeaheadTimer: null,
     /**
      * Initialize dropdown components
      */
@@ -930,7 +928,7 @@
         item.addEventListener("keydown", itemKeydownHandler);
         cleanupFunctions.push(() => item.removeEventListener("keydown", itemKeydownHandler));
       });
-      this.instances.set(dropdown, { toggle, menu, cleanup: cleanupFunctions });
+      this.instances.set(dropdown, { toggle, menu, cleanup: cleanupFunctions, typeaheadBuffer: "", typeaheadTimer: null });
     },
     /**
      * Toggle dropdown
@@ -1059,16 +1057,18 @@
           break;
         default:
           if (isOpen && e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
-            clearTimeout(this._typeaheadTimer);
-            this._typeaheadBuffer += e.key.toLowerCase();
+            const instance = this.instances.get(dropdown);
+            if (!instance) break;
+            clearTimeout(instance.typeaheadTimer);
+            instance.typeaheadBuffer += e.key.toLowerCase();
             const match = items.find(
-              (item) => item.textContent.trim().toLowerCase().startsWith(this._typeaheadBuffer)
+              (item) => item.textContent.trim().toLowerCase().startsWith(instance.typeaheadBuffer)
             );
             if (match) {
               match.focus();
             }
-            this._typeaheadTimer = setTimeout(() => {
-              this._typeaheadBuffer = "";
+            instance.typeaheadTimer = setTimeout(() => {
+              instance.typeaheadBuffer = "";
             }, 500);
           }
           break;
@@ -1776,9 +1776,10 @@
       }));
       if (!this.img.complete) {
         this.img.style.opacity = "0";
-        this.img.onload = () => {
+        this._imgLoadHandler = () => {
           this.img.style.opacity = "";
         };
+        this.img.addEventListener("load", this._imgLoadHandler, { once: true });
       }
     },
     /**
@@ -1797,6 +1798,10 @@
       }
       setTimeout(() => {
         if (!this.isOpen) {
+          if (this._imgLoadHandler) {
+            this.img.removeEventListener("load", this._imgLoadHandler);
+            this._imgLoadHandler = null;
+          }
           this.img.src = "";
           this.img.alt = "";
         }
@@ -1856,6 +1861,8 @@
     zIndexCounter: 1050,
     // Store trigger cleanup functions
     _triggerCleanups: [],
+    // Shared ESC key handler (installed once)
+    _sharedEscHandler: null,
     /**
      * Initialize modals
      */
@@ -1920,16 +1927,17 @@
       };
       backdrop.addEventListener("click", backdropClickHandler);
       cleanupFunctions.push(() => backdrop.removeEventListener("click", backdropClickHandler));
-      const escKeyHandler = (e) => {
-        if (e.key === "Escape" && this.openModals.length > 0) {
-          const topModal = this.openModals[this.openModals.length - 1];
-          if (topModal === modal && topModal.dataset.keyboard !== "false") {
-            this.close(topModal);
+      if (!this._sharedEscHandler) {
+        this._sharedEscHandler = (e) => {
+          if (e.key === "Escape" && this.openModals.length > 0) {
+            const topModal = this.openModals[this.openModals.length - 1];
+            if (topModal.dataset.keyboard !== "false") {
+              this.close(topModal);
+            }
           }
-        }
-      };
-      document.addEventListener("keydown", escKeyHandler);
-      cleanupFunctions.push(() => document.removeEventListener("keydown", escKeyHandler));
+        };
+        document.addEventListener("keydown", this._sharedEscHandler);
+      }
       this.modals.set(modal, { backdrop, dialog, trapHandler: null, cleanup: cleanupFunctions });
     },
     /**
@@ -2109,6 +2117,10 @@
       });
       this._triggerCleanups.forEach((fn) => fn());
       this._triggerCleanups = [];
+      if (this._sharedEscHandler) {
+        document.removeEventListener("keydown", this._sharedEscHandler);
+        this._sharedEscHandler = null;
+      }
     }
   };
   if (typeof window.Vanduo !== "undefined") {
@@ -2274,7 +2286,7 @@
       if (overlay) {
         overlay.classList.add("is-active");
       }
-      document.body.style.overflow = "hidden";
+      document.body.classList.add("body-navbar-open");
       toggle.setAttribute("aria-expanded", "true");
       menu.setAttribute("aria-hidden", "false");
     },
@@ -2291,7 +2303,7 @@
       if (overlay) {
         overlay.classList.remove("is-active");
       }
-      document.body.style.overflow = "";
+      document.body.classList.remove("body-navbar-open");
       const dropdownMenus = menu.querySelectorAll(".vd-navbar-dropdown-menu.is-open");
       dropdownMenus.forEach((dropdownMenu) => {
         dropdownMenu.classList.remove("is-open");
@@ -2850,9 +2862,6 @@
   const Select = {
     // Store initialized selects and their cleanup functions
     instances: /* @__PURE__ */ new Map(),
-    // Typeahead state
-    _typeaheadBuffer: "",
-    _typeaheadTimer: null,
     /**
      * Initialize select components
      */
@@ -2933,7 +2942,7 @@
       };
       select.addEventListener("change", changeHandler);
       cleanupFunctions.push(() => select.removeEventListener("change", changeHandler));
-      this.instances.set(select, { wrapper, button, dropdown, cleanup: cleanupFunctions });
+      this.instances.set(select, { wrapper, button, dropdown, cleanup: cleanupFunctions, typeaheadBuffer: "", typeaheadTimer: null });
     },
     /**
      * Build options in dropdown
@@ -3027,7 +3036,7 @@
      * @param {HTMLElement} dropdown - Dropdown container
      */
     updateSelectedOptions: function(select, dropdown) {
-      const options = dropdown.querySelectorAll(".vd-custom-select-option");
+      const options = dropdown.querySelectorAll(".custom-select-option");
       const selectedValues = Array.from(select.selectedOptions).map((opt) => opt.value);
       options.forEach((optionEl) => {
         const value = optionEl.dataset.value;
@@ -3061,7 +3070,7 @@
     openDropdown: function(button, dropdown) {
       dropdown.classList.add("is-open");
       button.setAttribute("aria-expanded", "true");
-      const firstOption = dropdown.querySelector(".vd-custom-select-option:not(.is-disabled)");
+      const firstOption = dropdown.querySelector(".custom-select-option:not(.is-disabled)");
       if (firstOption) {
         firstOption.focus();
       }
@@ -3084,7 +3093,7 @@
      */
     handleKeydown: function(e, select, button, dropdown) {
       const isOpen = dropdown.classList.contains("is-open");
-      const options = Array.from(dropdown.querySelectorAll(".vd-custom-select-option:not(.is-disabled)"));
+      const options = Array.from(dropdown.querySelectorAll(".custom-select-option:not(.is-disabled)"));
       const currentIndex = options.findIndex((opt) => opt === document.activeElement);
       switch (e.key) {
         case "Enter":
@@ -3135,16 +3144,18 @@
           break;
         default:
           if (isOpen && e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
-            clearTimeout(this._typeaheadTimer);
-            this._typeaheadBuffer += e.key.toLowerCase();
+            const instance = this.instances.get(select);
+            if (!instance) break;
+            clearTimeout(instance.typeaheadTimer);
+            instance.typeaheadBuffer += e.key.toLowerCase();
             const match = options.find(
-              (opt) => opt.textContent.trim().toLowerCase().startsWith(this._typeaheadBuffer)
+              (opt) => opt.textContent.trim().toLowerCase().startsWith(instance.typeaheadBuffer)
             );
             if (match) {
               match.focus();
             }
-            this._typeaheadTimer = setTimeout(() => {
-              this._typeaheadBuffer = "";
+            instance.typeaheadTimer = setTimeout(() => {
+              instance.typeaheadBuffer = "";
             }, 500);
           }
           break;
@@ -3176,7 +3187,9 @@
       if (element.id) {
         return element.id;
       }
-      return "select-" + Math.random().toString(36).substr(2, 9);
+      const id = "select-" + Math.random().toString(36).substr(2, 9);
+      element.id = id;
+      return id;
     },
     /**
      * Destroy a select instance and clean up event listeners
@@ -4230,7 +4243,6 @@
       this.applyNeutral(this.DEFAULTS.NEUTRAL);
       this.applyRadius(this.DEFAULTS.RADIUS);
       this.applyFont(this.DEFAULTS.FONT);
-      this.applyTheme(this.DEFAULTS.THEME);
       this.updateUI();
       this.dispatchEvent("reset", { state: { ...this.state } });
     },
@@ -7015,6 +7027,11 @@
 // js/components/suggest.js
 (function() {
   "use strict";
+  function _escapeHtml(text) {
+    const div = document.createElement("div");
+    div.textContent = text;
+    return div.innerHTML;
+  }
   const Suggest = {
     instances: /* @__PURE__ */ new Map(),
     init: function() {
@@ -7074,8 +7091,9 @@
           li.id = listId + "-item-" + i;
           const text = typeof item === "object" ? item.label || item.text || String(item) : String(item);
           if (query) {
+            const escaped = _escapeHtml(text);
             const re = new RegExp("(" + query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + ")", "gi");
-            li.innerHTML = text.replace(re, '<span class="vd-suggest-match">$1</span>');
+            li.innerHTML = escaped.replace(re, '<span class="vd-suggest-match">$1</span>');
           } else {
             li.textContent = text;
           }
@@ -7228,14 +7246,20 @@
       maxVal: (value, param) => parseFloat(value) <= parseFloat(param),
       pattern: (value, param) => {
         try {
+          if (param.length > 100) return false;
           return new RegExp(param).test(value);
         } catch (_e) {
           return false;
         }
       },
       match: (value, param) => {
-        const other = document.querySelector('[name="' + param + '"]');
-        return other ? value === other.value : false;
+        try {
+          const escaped = typeof CSS !== "undefined" && CSS.escape ? CSS.escape(param) : param;
+          const other = document.querySelector('[name="' + escaped + '"]');
+          return other ? value === other.value : false;
+        } catch (_e) {
+          return false;
+        }
       }
     },
     messages: {
@@ -8516,6 +8540,667 @@
   window.VanduoSpotlight = Spotlight;
 })();
 
+// js/components/music-player.js
+(function() {
+  "use strict";
+  function shuffleArray(arr) {
+    const shuffled = arr.slice();
+    for (let i = shuffled.length - 1; i > 0; i--) {
+      const j = Math.floor(Math.random() * (i + 1));
+      const tmp = shuffled[i];
+      shuffled[i] = shuffled[j];
+      shuffled[j] = tmp;
+    }
+    return shuffled;
+  }
+  function formatTime(seconds) {
+    if (!isFinite(seconds) || seconds < 0) return "0:00";
+    const m = Math.floor(seconds / 60);
+    const s = Math.floor(seconds % 60);
+    return m + ":" + (s < 10 ? "0" : "") + s;
+  }
+  function updateRangeFill(input) {
+    const min = parseFloat(input.min) || 0;
+    const max = parseFloat(input.max) || 1;
+    const val = parseFloat(input.value) || 0;
+    const pct = (val - min) / (max - min) * 100;
+    input.style.setProperty("--fill", pct + "%");
+    input.style.backgroundImage = "linear-gradient(to right, var(--music-player-track-fill, currentColor) 0%, var(--music-player-track-fill, currentColor) " + pct + "%, var(--music-player-track-bg, #ccc) " + pct + "%, var(--music-player-track-bg, #ccc) 100%)";
+  }
+  function icon(name) {
+    const el = document.createElement("i");
+    el.className = "ph ph-" + name;
+    el.setAttribute("aria-hidden", "true");
+    return el;
+  }
+  const MusicPlayer = {
+    /** @type {Map<HTMLElement, Object>} */
+    instances: /* @__PURE__ */ new Map(),
+    /**
+     * Default options.
+     */
+    defaults: {
+      tracks: [],
+      volume: 0.5,
+      shuffle: false,
+      showProgress: false,
+      showPlaylist: false,
+      autoAdvance: true
+    },
+    /**
+     * Auto-initialize all .vd-music-player / [data-music-player] elements.
+     * Options can be provided via data-music-player-options (JSON string).
+     */
+    init: function() {
+      document.querySelectorAll(".vd-music-player, [data-music-player]").forEach((el) => {
+        if (this.instances.has(el)) return;
+        let opts = {};
+        const attr = el.getAttribute("data-music-player-options");
+        if (attr) {
+          try {
+            opts = JSON.parse(attr);
+          } catch (_) {
+          }
+        }
+        this.initPlayer(el, opts);
+      });
+    },
+    /**
+     * Initialize a single player element.
+     * @param {HTMLElement} container
+     * @param {Object} [options]
+     */
+    initPlayer: function(container, options) {
+      const opts = Object.assign({}, this.defaults, options || {});
+      const rawTracks = Array.isArray(opts.tracks) ? opts.tracks : [];
+      const tracks = rawTracks.filter((t) => t && typeof t.url === "string" && t.url.trim());
+      const trackList = opts.shuffle ? shuffleArray(tracks) : tracks.slice();
+      const state = {
+        tracks: trackList,
+        originalTracks: tracks.slice(),
+        currentIndex: 0,
+        isPlaying: false,
+        volume: Math.max(0, Math.min(1, opts.volume)),
+        shuffle: opts.shuffle,
+        showProgress: opts.showProgress,
+        showPlaylist: opts.showPlaylist,
+        autoAdvance: opts.autoAdvance,
+        audio: null
+      };
+      const audio = new Audio();
+      audio.volume = state.volume;
+      audio.preload = "metadata";
+      state.audio = audio;
+      this._buildDOM(container, state);
+      const refs = {
+        btnPlay: container.querySelector(".vd-music-player-btn-play"),
+        btnPrev: container.querySelector(".vd-music-player-btn-prev"),
+        btnNext: container.querySelector(".vd-music-player-btn-next"),
+        btnShuffle: container.querySelector(".vd-music-player-btn-shuffle"),
+        btnPlaylist: container.querySelector(".vd-music-player-btn-playlist"),
+        trackName: container.querySelector(".vd-music-player-track-name"),
+        volumeSlider: container.querySelector(".vd-music-player-volume-slider"),
+        volumeIcon: container.querySelector(".vd-music-player-volume-icon"),
+        progressBar: container.querySelector(".vd-music-player-progress-bar"),
+        timeElapsed: container.querySelector(".vd-music-player-time-elapsed"),
+        timeDuration: container.querySelector(".vd-music-player-time-duration"),
+        playlistPanel: container.querySelector(".vd-music-player-playlist")
+      };
+      const renderPlayIcon = () => {
+        const btn = refs.btnPlay;
+        if (!btn) return;
+        btn.innerHTML = "";
+        btn.appendChild(icon(state.isPlaying ? "pause" : "play"));
+        btn.setAttribute("aria-label", state.isPlaying ? "Pause" : "Play");
+        btn.classList.toggle("is-active", state.isPlaying);
+      };
+      const renderTrackName = () => {
+        const el = refs.trackName;
+        if (!el) return;
+        const track = state.tracks[state.currentIndex];
+        if (track) {
+          el.textContent = track.name || "Unknown Track";
+          el.classList.remove("is-idle");
+        } else {
+          el.textContent = "No tracks loaded";
+          el.classList.add("is-idle");
+        }
+      };
+      const renderVolumeIcon = () => {
+        const el = refs.volumeIcon;
+        if (!el) return;
+        el.innerHTML = "";
+        const v = state.volume;
+        const name = v === 0 ? "speaker-none" : v < 0.5 ? "speaker-low" : "speaker-high";
+        el.appendChild(icon(name));
+      };
+      const renderShuffleBtn = () => {
+        const btn = refs.btnShuffle;
+        if (!btn) return;
+        btn.classList.toggle("is-active", state.shuffle);
+        btn.setAttribute("aria-pressed", state.shuffle ? "true" : "false");
+      };
+      const renderPlaylistItems = () => {
+        const panel = refs.playlistPanel;
+        if (!panel) return;
+        panel.innerHTML = "";
+        state.tracks.forEach((track, i) => {
+          const item = document.createElement("button");
+          item.className = "vd-music-player-playlist-item" + (i === state.currentIndex ? " is-active" : "");
+          item.type = "button";
+          item.setAttribute("data-index", String(i));
+          item.setAttribute("aria-current", i === state.currentIndex ? "true" : "false");
+          const num = document.createElement("span");
+          num.className = "vd-music-player-playlist-num";
+          num.textContent = String(i + 1);
+          const name = document.createElement("span");
+          name.className = "vd-music-player-playlist-name";
+          name.textContent = track.name || "Track " + (i + 1);
+          item.appendChild(num);
+          item.appendChild(name);
+          panel.appendChild(item);
+        });
+      };
+      const renderProgress = () => {
+        const bar = refs.progressBar;
+        if (!bar || !audio.duration) return;
+        const pct = audio.currentTime / audio.duration * 100;
+        bar.value = String(pct);
+        updateRangeFill(bar);
+        if (refs.timeElapsed) refs.timeElapsed.textContent = formatTime(audio.currentTime);
+        if (refs.timeDuration) refs.timeDuration.textContent = formatTime(audio.duration);
+      };
+      const loadTrack = (index, autoPlay) => {
+        const track = state.tracks[index];
+        if (!track) return;
+        state.currentIndex = index;
+        audio.src = track.url;
+        renderTrackName();
+        renderPlaylistItems();
+        if (refs.progressBar) {
+          refs.progressBar.value = "0";
+          updateRangeFill(refs.progressBar);
+        }
+        if (refs.timeElapsed) refs.timeElapsed.textContent = "0:00";
+        if (refs.timeDuration) refs.timeDuration.textContent = "0:00";
+        container.dispatchEvent(
+          new CustomEvent("musicplayer:trackchange", {
+            bubbles: true,
+            detail: { index, name: track.name, url: track.url }
+          })
+        );
+        if (autoPlay) {
+          audio.play().catch(() => {
+          });
+        }
+      };
+      const cleanupFunctions = [];
+      const onPlay = () => {
+        state.isPlaying = true;
+        renderPlayIcon();
+        container.dispatchEvent(new CustomEvent("musicplayer:play", { bubbles: true }));
+      };
+      const onPause = () => {
+        state.isPlaying = false;
+        renderPlayIcon();
+        container.dispatchEvent(new CustomEvent("musicplayer:pause", { bubbles: true }));
+      };
+      const onEnded = () => {
+        if (state.autoAdvance && state.tracks.length > 1) {
+          const next = (state.currentIndex + 1) % state.tracks.length;
+          loadTrack(next, true);
+        } else {
+          state.isPlaying = false;
+          renderPlayIcon();
+          container.dispatchEvent(new CustomEvent("musicplayer:ended", { bubbles: true }));
+        }
+      };
+      const onTimeUpdate = () => {
+        if (state.showProgress) renderProgress();
+      };
+      const onLoadedMetadata = () => {
+        if (refs.timeDuration) refs.timeDuration.textContent = formatTime(audio.duration);
+        if (refs.progressBar) {
+          refs.progressBar.max = "100";
+          updateRangeFill(refs.progressBar);
+        }
+      };
+      audio.addEventListener("play", onPlay);
+      audio.addEventListener("pause", onPause);
+      audio.addEventListener("ended", onEnded);
+      audio.addEventListener("timeupdate", onTimeUpdate);
+      audio.addEventListener("loadedmetadata", onLoadedMetadata);
+      cleanupFunctions.push(() => {
+        audio.removeEventListener("play", onPlay);
+        audio.removeEventListener("pause", onPause);
+        audio.removeEventListener("ended", onEnded);
+        audio.removeEventListener("timeupdate", onTimeUpdate);
+        audio.removeEventListener("loadedmetadata", onLoadedMetadata);
+        audio.pause();
+        audio.src = "";
+      });
+      if (refs.btnPlay) {
+        const handler = () => {
+          if (!audio.src && state.tracks.length) loadTrack(state.currentIndex, false);
+          if (state.isPlaying) {
+            audio.pause();
+          } else {
+            audio.play().catch(() => {
+            });
+          }
+        };
+        refs.btnPlay.addEventListener("click", handler);
+        cleanupFunctions.push(() => refs.btnPlay.removeEventListener("click", handler));
+        const keyHandler = (e) => {
+          if (e.key === " " || e.key === "Enter") {
+            e.preventDefault();
+            handler();
+          }
+        };
+        refs.btnPlay.addEventListener("keydown", keyHandler);
+        cleanupFunctions.push(() => refs.btnPlay.removeEventListener("keydown", keyHandler));
+      }
+      if (refs.btnPrev) {
+        const handler = () => {
+          if (!state.tracks.length) return;
+          if (audio.currentTime > 3) {
+            audio.currentTime = 0;
+          } else {
+            const prev = state.currentIndex === 0 ? state.tracks.length - 1 : state.currentIndex - 1;
+            loadTrack(prev, state.isPlaying);
+          }
+        };
+        refs.btnPrev.addEventListener("click", handler);
+        cleanupFunctions.push(() => refs.btnPrev.removeEventListener("click", handler));
+      }
+      if (refs.btnNext) {
+        const handler = () => {
+          if (!state.tracks.length) return;
+          const next = (state.currentIndex + 1) % state.tracks.length;
+          loadTrack(next, state.isPlaying);
+        };
+        refs.btnNext.addEventListener("click", handler);
+        cleanupFunctions.push(() => refs.btnNext.removeEventListener("click", handler));
+      }
+      if (refs.btnShuffle) {
+        const handler = () => {
+          state.shuffle = !state.shuffle;
+          if (state.shuffle) {
+            const current = state.tracks[state.currentIndex];
+            state.tracks = shuffleArray(state.tracks);
+            const newIdx = state.tracks.findIndex((t) => t === current);
+            if (newIdx > 0) {
+              state.tracks.splice(newIdx, 1);
+              state.tracks.unshift(current);
+            }
+            state.currentIndex = 0;
+          } else {
+            const current = state.tracks[state.currentIndex];
+            state.tracks = state.originalTracks.slice();
+            state.currentIndex = state.tracks.findIndex((t) => t === current);
+            if (state.currentIndex < 0) state.currentIndex = 0;
+          }
+          renderShuffleBtn();
+          renderPlaylistItems();
+        };
+        refs.btnShuffle.addEventListener("click", handler);
+        cleanupFunctions.push(() => refs.btnShuffle.removeEventListener("click", handler));
+      }
+      if (refs.btnPlaylist) {
+        const handler = () => {
+          const panel = refs.playlistPanel;
+          if (!panel) return;
+          const isOpen = panel.classList.toggle("is-open");
+          refs.btnPlaylist.classList.toggle("is-active", isOpen);
+          refs.btnPlaylist.setAttribute("aria-expanded", isOpen ? "true" : "false");
+        };
+        refs.btnPlaylist.addEventListener("click", handler);
+        cleanupFunctions.push(() => refs.btnPlaylist.removeEventListener("click", handler));
+      }
+      if (refs.volumeSlider) {
+        const handler = (e) => {
+          const v = parseFloat(e.target.value);
+          state.volume = v;
+          audio.volume = v;
+          renderVolumeIcon();
+          updateRangeFill(refs.volumeSlider);
+          container.dispatchEvent(
+            new CustomEvent("musicplayer:volumechange", { bubbles: true, detail: { volume: v } })
+          );
+        };
+        refs.volumeSlider.addEventListener("input", handler);
+        cleanupFunctions.push(() => refs.volumeSlider.removeEventListener("input", handler));
+        updateRangeFill(refs.volumeSlider);
+      }
+      if (refs.progressBar) {
+        const handler = (e) => {
+          if (!audio.duration) return;
+          const pct = parseFloat(e.target.value);
+          audio.currentTime = pct / 100 * audio.duration;
+          updateRangeFill(refs.progressBar);
+        };
+        refs.progressBar.addEventListener("input", handler);
+        cleanupFunctions.push(() => refs.progressBar.removeEventListener("input", handler));
+      }
+      if (refs.playlistPanel) {
+        const panelHandler = (e) => {
+          const item = e.target.closest(".vd-music-player-playlist-item");
+          if (!item) return;
+          const idx = parseInt(item.getAttribute("data-index"), 10);
+          if (!isNaN(idx)) loadTrack(idx, true);
+        };
+        refs.playlistPanel.addEventListener("click", panelHandler);
+        cleanupFunctions.push(
+          () => refs.playlistPanel.removeEventListener("click", panelHandler)
+        );
+      }
+      renderPlayIcon();
+      renderTrackName();
+      renderVolumeIcon();
+      if (opts.showPlaylist) renderPlaylistItems();
+      this.instances.set(container, { state, audio, refs, cleanup: cleanupFunctions });
+      container.setAttribute("data-music-player-initialized", "true");
+    },
+    /* ─── DOM builder ─────────────────────────────────────── */
+    /**
+     * Build the inner DOM structure inside container.
+     * Pre-existing inner content is replaced only if it has no
+     * recognised child elements (allows server-rendered markup).
+     * @param {HTMLElement} container
+     * @param {Object} state
+     */
+    _buildDOM: function(container, state) {
+      if (container.querySelector(".vd-music-player-controls")) return;
+      container.setAttribute("role", "region");
+      container.setAttribute("aria-label", "Music Player");
+      if (state.showProgress) container.classList.add("has-progress");
+      if (state.showPlaylist) container.classList.add("has-playlist");
+      const info = document.createElement("div");
+      info.className = "vd-music-player-info";
+      const iconWrap = document.createElement("span");
+      iconWrap.className = "vd-music-player-icon";
+      iconWrap.setAttribute("aria-hidden", "true");
+      iconWrap.appendChild(icon("music-note"));
+      const trackName = document.createElement("span");
+      trackName.className = "vd-music-player-track-name";
+      trackName.setAttribute("aria-live", "polite");
+      trackName.setAttribute("aria-atomic", "true");
+      info.appendChild(iconWrap);
+      info.appendChild(trackName);
+      container.appendChild(info);
+      const controls = document.createElement("div");
+      controls.className = "vd-music-player-controls";
+      controls.setAttribute("role", "group");
+      controls.setAttribute("aria-label", "Playback controls");
+      const btnPrev = document.createElement("button");
+      btnPrev.type = "button";
+      btnPrev.className = "vd-music-player-btn vd-music-player-btn-prev";
+      btnPrev.setAttribute("aria-label", "Previous track");
+      btnPrev.appendChild(icon("skip-back"));
+      const btnPlay = document.createElement("button");
+      btnPlay.type = "button";
+      btnPlay.className = "vd-music-player-btn vd-music-player-btn-play";
+      btnPlay.setAttribute("aria-label", "Play");
+      btnPlay.appendChild(icon("play"));
+      const btnNext = document.createElement("button");
+      btnNext.type = "button";
+      btnNext.className = "vd-music-player-btn vd-music-player-btn-next";
+      btnNext.setAttribute("aria-label", "Next track");
+      btnNext.appendChild(icon("skip-forward"));
+      controls.appendChild(btnPrev);
+      controls.appendChild(btnPlay);
+      controls.appendChild(btnNext);
+      if (state.showPlaylist || state.shuffle !== void 0) {
+        const btnShuffle = document.createElement("button");
+        btnShuffle.type = "button";
+        btnShuffle.className = "vd-music-player-btn vd-music-player-btn-shuffle";
+        btnShuffle.setAttribute("aria-label", "Shuffle");
+        btnShuffle.setAttribute("aria-pressed", state.shuffle ? "true" : "false");
+        btnShuffle.appendChild(icon("shuffle"));
+        controls.appendChild(btnShuffle);
+      }
+      const spacer = document.createElement("span");
+      spacer.className = "vd-music-player-spacer";
+      spacer.setAttribute("aria-hidden", "true");
+      controls.appendChild(spacer);
+      const volumeWrap = document.createElement("div");
+      volumeWrap.className = "vd-music-player-volume";
+      const volumeIcon = document.createElement("span");
+      volumeIcon.className = "vd-music-player-volume-icon";
+      volumeIcon.setAttribute("aria-hidden", "true");
+      const volumeSlider = document.createElement("input");
+      volumeSlider.type = "range";
+      volumeSlider.className = "vd-music-player-volume-slider";
+      volumeSlider.min = "0";
+      volumeSlider.max = "1";
+      volumeSlider.step = "0.01";
+      volumeSlider.value = String(state.volume);
+      volumeSlider.setAttribute("aria-label", "Volume");
+      volumeWrap.appendChild(volumeIcon);
+      volumeWrap.appendChild(volumeSlider);
+      controls.appendChild(volumeWrap);
+      if (state.showPlaylist) {
+        const btnPlaylist = document.createElement("button");
+        btnPlaylist.type = "button";
+        btnPlaylist.className = "vd-music-player-btn vd-music-player-btn-playlist";
+        btnPlaylist.setAttribute("aria-label", "Show playlist");
+        btnPlaylist.setAttribute("aria-expanded", "false");
+        btnPlaylist.appendChild(icon("playlist"));
+        controls.appendChild(btnPlaylist);
+      }
+      container.appendChild(controls);
+      if (state.showProgress) {
+        const progressRow = document.createElement("div");
+        progressRow.className = "vd-music-player-progress";
+        const timeElapsed = document.createElement("span");
+        timeElapsed.className = "vd-music-player-time vd-music-player-time-elapsed";
+        timeElapsed.textContent = "0:00";
+        timeElapsed.setAttribute("aria-hidden", "true");
+        const progressBar = document.createElement("input");
+        progressBar.type = "range";
+        progressBar.className = "vd-music-player-progress-bar";
+        progressBar.min = "0";
+        progressBar.max = "100";
+        progressBar.step = "0.1";
+        progressBar.value = "0";
+        progressBar.setAttribute("aria-label", "Seek");
+        const timeDuration = document.createElement("span");
+        timeDuration.className = "vd-music-player-time vd-music-player-time-duration";
+        timeDuration.textContent = "0:00";
+        timeDuration.setAttribute("aria-hidden", "true");
+        progressRow.appendChild(timeElapsed);
+        progressRow.appendChild(progressBar);
+        progressRow.appendChild(timeDuration);
+        container.appendChild(progressRow);
+      }
+      if (state.showPlaylist) {
+        const playlist = document.createElement("div");
+        playlist.className = "vd-music-player-playlist";
+        playlist.setAttribute("aria-label", "Playlist");
+        container.appendChild(playlist);
+      }
+    },
+    /* ─── Public API ──────────────────────────────────────── */
+    /**
+     * @param {HTMLElement} container
+     */
+    play: function(container) {
+      const inst = this.instances.get(container);
+      if (!inst) return;
+      if (!inst.audio.src && inst.state.tracks.length) {
+        inst.audio.src = inst.state.tracks[inst.state.currentIndex].url;
+      }
+      inst.audio.play().catch(() => {
+      });
+    },
+    /**
+     * @param {HTMLElement} container
+     */
+    pause: function(container) {
+      const inst = this.instances.get(container);
+      if (inst) inst.audio.pause();
+    },
+    /**
+     * @param {HTMLElement} container
+     */
+    toggle: function(container) {
+      const inst = this.instances.get(container);
+      if (!inst) return;
+      if (inst.state.isPlaying) {
+        this.pause(container);
+      } else {
+        this.play(container);
+      }
+    },
+    /**
+     * @param {HTMLElement} container
+     */
+    next: function(container) {
+      const inst = this.instances.get(container);
+      if (!inst || !inst.state.tracks.length) return;
+      const next = (inst.state.currentIndex + 1) % inst.state.tracks.length;
+      this._loadTrack(inst, next, inst.state.isPlaying);
+    },
+    /**
+     * @param {HTMLElement} container
+     */
+    previous: function(container) {
+      const inst = this.instances.get(container);
+      if (!inst || !inst.state.tracks.length) return;
+      const len = inst.state.tracks.length;
+      const prev = (inst.state.currentIndex - 1 + len) % len;
+      this._loadTrack(inst, prev, inst.state.isPlaying);
+    },
+    /**
+     * @param {HTMLElement} container
+     * @param {number} value - 0 to 1
+     */
+    setVolume: function(container, value) {
+      const inst = this.instances.get(container);
+      if (!inst) return;
+      const v = Math.max(0, Math.min(1, value));
+      inst.state.volume = v;
+      inst.audio.volume = v;
+      if (inst.refs.volumeSlider) {
+        inst.refs.volumeSlider.value = String(v);
+        updateRangeFill(inst.refs.volumeSlider);
+      }
+      container.dispatchEvent(
+        new CustomEvent("musicplayer:volumechange", { bubbles: true, detail: { volume: v } })
+      );
+    },
+    /**
+     * @param {HTMLElement} container
+     * @param {number} index - Track index
+     */
+    setTrack: function(container, index) {
+      const inst = this.instances.get(container);
+      if (!inst) return;
+      this._loadTrack(inst, index, inst.state.isPlaying);
+    },
+    /**
+     * Shuffle or un-shuffle the track list.
+     * @param {HTMLElement} container
+     */
+    shuffle: function(container) {
+      const inst = this.instances.get(container);
+      if (!inst || !inst.refs.btnShuffle) return;
+      inst.refs.btnShuffle.click();
+    },
+    /**
+     * Return a shallow copy of the current player state.
+     * @param {HTMLElement} container
+     * @returns {Object|null}
+     */
+    getState: function(container) {
+      const inst = this.instances.get(container);
+      if (!inst) return null;
+      const s = inst.state;
+      return {
+        isPlaying: s.isPlaying,
+        currentIndex: s.currentIndex,
+        currentTrack: s.tracks[s.currentIndex] || null,
+        volume: s.volume,
+        shuffle: s.shuffle,
+        tracks: s.tracks.slice()
+      };
+    },
+    /**
+     * Stop playback, clean up listeners, remove instance.
+     * @param {HTMLElement} container
+     */
+    destroy: function(container) {
+      const inst = this.instances.get(container);
+      if (!inst) return;
+      inst.cleanup.forEach((fn) => fn());
+      this.instances.delete(container);
+      container.removeAttribute("data-music-player-initialized");
+    },
+    /**
+     * Destroy all instances.
+     */
+    destroyAll: function() {
+      this.instances.forEach((_, container) => this.destroy(container));
+    },
+    /* ─── Internal helpers ────────────────────────────────── */
+    /**
+     * Load track by index on an already-initialised instance object.
+     * @param {Object} inst
+     * @param {number} index
+     * @param {boolean} autoPlay
+     */
+    _loadTrack: function(inst, index, autoPlay) {
+      const track = inst.state.tracks[index];
+      if (!track) return;
+      const container = this._containerOf(inst);
+      inst.state.currentIndex = index;
+      inst.audio.src = track.url;
+      if (inst.refs.trackName) {
+        inst.refs.trackName.textContent = track.name || "Unknown Track";
+        inst.refs.trackName.classList.remove("is-idle");
+      }
+      if (inst.refs.playlistPanel) {
+        inst.refs.playlistPanel.querySelectorAll(".vd-music-player-playlist-item").forEach((item, i) => {
+          const active = i === index;
+          item.classList.toggle("is-active", active);
+          item.setAttribute("aria-current", active ? "true" : "false");
+        });
+      }
+      if (inst.refs.progressBar) {
+        inst.refs.progressBar.value = "0";
+        updateRangeFill(inst.refs.progressBar);
+      }
+      if (inst.refs.timeElapsed) inst.refs.timeElapsed.textContent = "0:00";
+      if (inst.refs.timeDuration) inst.refs.timeDuration.textContent = "0:00";
+      if (container) {
+        container.dispatchEvent(
+          new CustomEvent("musicplayer:trackchange", {
+            bubbles: true,
+            detail: { index, name: track.name, url: track.url }
+          })
+        );
+      }
+      if (autoPlay) inst.audio.play().catch(() => {
+      });
+    },
+    /**
+     * Reverse-lookup the container element for a given instance object.
+     * @param {Object} inst
+     * @returns {HTMLElement|null}
+     */
+    _containerOf: function(inst) {
+      for (const [container, i] of this.instances) {
+        if (i === inst) return container;
+      }
+      return null;
+    }
+  };
+  if (typeof window.Vanduo !== "undefined") {
+    window.Vanduo.register("musicPlayer", MusicPlayer);
+  }
+  window.VanduoMusicPlayer = MusicPlayer;
+})();
+
 // js/index.js
 var Vanduo = window.Vanduo;
 var index_default = Vanduo;