@vanduo-oss/framework 1.3.1 → 1.3.3

package/dist/vanduo.js

@@ -1,4 +1,4 @@
-/*! Vanduo v1.3.1 | Built: 2026-03-20T21:48:40.922Z | git:7e73bb8 | development */
+/*! Vanduo v1.3.3 | Built: 2026-04-10T21:45:12.664Z | git:281f4f6 | development */
 (() => {
   // js/utils/lifecycle.js
   (function() {
@@ -107,7 +107,7 @@
   // js/vanduo.js
   (function() {
     "use strict";
-    const VANDUO_VERSION = true ? "1.3.1" : "0.0.0-dev";
+    const VANDUO_VERSION = true ? "1.3.3" : "0.0.0-dev";
     const Vanduo2 = {
       version: VANDUO_VERSION,
       components: {},
@@ -3806,6 +3806,7 @@
       loadPreferences: function() {
         this.state.theme = this.getStorageValue(this.STORAGE_KEYS.THEME, this.DEFAULTS.THEME);
         this.state.primary = this.getStorageValue(this.STORAGE_KEYS.PRIMARY, this.getDefaultPrimary(this.state.theme));
+        this._normalizeDefaultPrimaryIfStaleWithStoredTheme();
         this.state.neutral = this.getStorageValue(this.STORAGE_KEYS.NEUTRAL, this.DEFAULTS.NEUTRAL);
         this.state.radius = this.getStorageValue(this.STORAGE_KEYS.RADIUS, this.DEFAULTS.RADIUS);
         this.state.font = this.getStorageValue(this.STORAGE_KEYS.FONT, this.DEFAULTS.FONT);
@@ -3891,12 +3892,10 @@
           mode = this.DEFAULTS.THEME;
         }
         this._isApplying = true;
-        const currentMode = this.state.theme;
-        const oldDefault = this.getDefaultPrimary(currentMode);
-        if (this.state.primary === oldDefault) {
-          const newDefault = this.getDefaultPrimary(mode);
-          if (newDefault !== this.state.primary) {
-            this.applyPrimary(newDefault);
+        if (this.isUsingDefaultPrimary()) {
+          const expected = this.getDefaultPrimary(mode);
+          if (this.state.primary !== expected) {
+            this.applyPrimary(expected);
           }
         }
         this.state.theme = mode;
@@ -4138,6 +4137,20 @@
       isUsingDefaultPrimary: function() {
         return this.state.primary === this.DEFAULTS.PRIMARY_LIGHT || this.state.primary === this.DEFAULTS.PRIMARY_DARK;
       },
+      /**
+       * When primary is still one of the auto-default palette keys (black/amber) but
+       * localStorage was written under a different theme (or OS changed in system mode),
+       * align in-memory state before applyAllPreferences runs — avoids amber+light / black+dark drift.
+       */
+      _normalizeDefaultPrimaryIfStaleWithStoredTheme: function() {
+        if (!this.isUsingDefaultPrimary()) {
+          return;
+        }
+        const expected = this.getDefaultPrimary(this.state.theme);
+        if (this.state.primary !== expected) {
+          this.state.primary = expected;
+        }
+      },
       bindEvents: function() {
         if (this.elements.trigger) {
           this.addListener(this.elements.trigger, "click", (e) => {
@@ -4376,6 +4389,9 @@
         this._onMediaChange = (_e) => {
           if (this.state.preference === "system") {
             this.applyTheme();
+            if (window.ThemeCustomizer && typeof window.ThemeCustomizer.applyTheme === "function" && !window.ThemeCustomizer._isApplying) {
+              window.ThemeCustomizer.applyTheme("system");
+            }
           }
         };
         this._mediaQuery.addEventListener("change", this._onMediaChange);
@@ -5607,6 +5623,8 @@
       touchState: null,
       // Feedback element
       feedbackElement: null,
+      // Shared selector used by init and touch reorder
+      containerSelector: ".vd-draggable-container, .vd-draggable-container-vertical",
       /**
        * Initialize draggable components
        */
@@ -5618,7 +5636,7 @@
           }
           this.initDraggable(element);
         });
-        const containers = document.querySelectorAll(".vd-draggable-container, .vd-draggable-container-vertical");
+        const containers = document.querySelectorAll(this.containerSelector);
         containers.forEach((container) => {
           if (!this.instances.has(container)) {
             this.initContainer(container);
@@ -5862,10 +5880,16 @@
        */
       handleTouchStart: function(e, element) {
         const touch = e.touches[0];
+        const rect = element.getBoundingClientRect();
         this.touchState = {
           element,
           startX: touch.clientX,
           startY: touch.clientY,
+          lastX: touch.clientX,
+          lastY: touch.clientY,
+          // Keep preview anchored to the original grab point.
+          offsetX: touch.clientX - rect.left,
+          offsetY: touch.clientY - rect.top,
           startTime: Date.now(),
           isDragging: false
         };
@@ -5878,6 +5902,8 @@
       handleTouchMove: function(e, element) {
         if (!this.touchState) return;
         const touch = e.touches[0];
+        this.touchState.lastX = touch.clientX;
+        this.touchState.lastY = touch.clientY;
         const deltaX = touch.clientX - this.touchState.startX;
         const deltaY = touch.clientY - this.touchState.startY;
         if (Math.abs(deltaX) > 10 || Math.abs(deltaY) > 10) {
@@ -5890,7 +5916,10 @@
               element,
               initialPosition: { x: this.touchState.startX, y: this.touchState.startY },
               initialBounds: element.getBoundingClientRect(),
-              data: this.getData(element)
+              data: this.getData(element),
+              // Preserve where inside the element the drag started for accurate ghost positioning.
+              offsetX: this.touchState.offsetX,
+              offsetY: this.touchState.offsetY
             };
             element.dispatchEvent(new CustomEvent("draggable:start", {
               bubbles: true,
@@ -5912,7 +5941,8 @@
                 delta: { x: deltaX, y: deltaY }
               }
             }));
-            const container = element.closest(".vd-draggable-container");
+            this.updateTouchDropZone(touch.clientX, touch.clientY);
+            const container = element.closest(this.containerSelector);
             if (container && container.contains(element)) {
               this.handleReorder(container, element, touch.clientX, touch.clientY);
             }
@@ -5927,6 +5957,17 @@
       handleTouchEnd: function(e, element) {
         if (this.touchState && this.touchState.isDragging) {
           if (e.cancelable) e.preventDefault();
+          const endTouch = e.changedTouches?.[0];
+          const endPosition = {
+            x: endTouch?.clientX ?? this.touchState.lastX ?? this.touchState.startX,
+            y: endTouch?.clientY ?? this.touchState.lastY ?? this.touchState.startY
+          };
+          const dropZone = this.resolveDropZoneAtPoint(endPosition.x, endPosition.y) || this.touchState.overZone;
+          if (dropZone) {
+            this.dispatchDrop(dropZone, endPosition);
+          } else if (this.touchState.overZone) {
+            this.touchState.overZone.classList.remove("is-drag-over");
+          }
           element.classList.remove("is-dragging");
           element.classList.add("is-dropped");
           element.setAttribute("aria-grabbed", "false");
@@ -5934,7 +5975,6 @@
           if (this.feedbackElement) {
             this.feedbackElement.classList.add("hidden");
           }
-          const endTouch = e.changedTouches[0];
           const data = this.currentDrag?.data || this.getData(element);
           const startX = this.touchState?.startX || 0;
           const startY = this.touchState?.startY || 0;
@@ -5943,10 +5983,10 @@
             detail: {
               element,
               data,
-              position: { x: endTouch.clientX, y: endTouch.clientY },
+              position: endPosition,
               delta: {
-                x: endTouch.clientX - startX,
-                y: endTouch.clientY - startY
+                x: endPosition.x - startX,
+                y: endPosition.y - startY
               }
             }
           }));
@@ -5987,6 +6027,58 @@
        */
       handleDrop: function(e, zone) {
         e.preventDefault();
+        this.dispatchDrop(zone, { x: e.clientX, y: e.clientY });
+      },
+      /**
+       * Resolve a drop zone from viewport coordinates
+       * @param {number} x
+       * @param {number} y
+       * @returns {HTMLElement|null}
+       */
+      resolveDropZoneAtPoint: function(x, y) {
+        if (!Number.isFinite(x) || !Number.isFinite(y)) return null;
+        if (typeof document.elementsFromPoint === "function") {
+          const stacked = document.elementsFromPoint(x, y);
+          for (const element of stacked) {
+            const zone = element.closest(".vd-drop-zone");
+            if (zone) return zone;
+          }
+        }
+        const target = document.elementFromPoint(x, y);
+        const targetZone = target ? target.closest(".vd-drop-zone") : null;
+        if (targetZone) return targetZone;
+        const zones = document.querySelectorAll(".vd-drop-zone");
+        for (const zone of zones) {
+          const rect = zone.getBoundingClientRect();
+          if (x >= rect.left && x <= rect.right && y >= rect.top && y <= rect.bottom) {
+            return zone;
+          }
+        }
+        return null;
+      },
+      /**
+       * Track and update active drop-zone hover state on touch devices
+       * @param {number} x
+       * @param {number} y
+       */
+      updateTouchDropZone: function(x, y) {
+        if (!this.touchState) return;
+        const nextZone = this.resolveDropZoneAtPoint(x, y);
+        const prevZone = this.touchState.overZone || null;
+        if (prevZone && prevZone !== nextZone) {
+          prevZone.classList.remove("is-drag-over");
+        }
+        if (nextZone && nextZone !== prevZone) {
+          nextZone.classList.add("is-drag-over");
+        }
+        this.touchState.overZone = nextZone || null;
+      },
+      /**
+       * Dispatch a normalized drop event for mouse and touch flows
+       * @param {HTMLElement} zone
+       * @param {{x:number, y:number}} position
+       */
+      dispatchDrop: function(zone, position) {
         zone.classList.remove("is-drag-over");
         zone.dispatchEvent(new CustomEvent("draggable:drop", {
           bubbles: true,
@@ -5994,7 +6086,7 @@
             zone,
             element: this.currentDrag?.element,
             data: this.currentDrag?.data,
-            position: { x: e.clientX, y: e.clientY }
+            position
           }
         }));
       },
@@ -6095,9 +6187,11 @@
         this.feedbackElement.innerHTML = "";
         const clone = this.currentDrag.element.cloneNode(true);
         this.feedbackElement.appendChild(clone);
+        const offsetX = this.currentDrag.offsetX ?? 20;
+        const offsetY = this.currentDrag.offsetY ?? 20;
         Object.assign(this.feedbackElement.style, {
-          left: x - 20 + "px",
-          top: y - 20 + "px",
+          left: x - offsetX + "px",
+          top: y - offsetY + "px",
           width: rect.width + "px",
           height: rect.height + "px"
         });
@@ -8540,6 +8634,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;