@vanduo-oss/framework 1.3.1 → 1.3.2

package/dist/vanduo.esm.js

@@ -1,4 +1,4 @@
-/*! Vanduo v1.3.1 | Built: 2026-03-20T21:48:40.922Z | git:7e73bb8 | 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.1" : "0.0.0-dev";
+  const VANDUO_VERSION = true ? "1.3.2" : "0.0.0-dev";
   const Vanduo2 = {
     version: VANDUO_VERSION,
     components: {},
@@ -8540,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;