pwa-audio-player 0.0.0-stage → 1.0.0

package/dist/index.cjs

@@ -0,0 +1,1035 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  GestureGuardian: () => GestureGuardian,
+  MediaSessionController: () => MediaSessionController,
+  PlaylistManager: () => PlaylistManager,
+  PwaPlayer: () => PwaPlayer,
+  SilentHoldKeeper: () => SilentHoldKeeper,
+  createPwaPlayer: () => createPwaPlayer,
+  detectPlatform: () => detectPlatform,
+  getActiveLyric: () => getActiveLyric,
+  getSilentWavUrl: () => getSilentWavUrl,
+  parseLrc: () => parseLrc,
+  platform: () => platform
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/platform.ts
+function detectPlatform() {
+  if (typeof window === "undefined" || typeof navigator === "undefined") {
+    return {
+      isIOS: false,
+      isSafari: false,
+      isStandalone: false,
+      supportsMediaSession: false,
+      supportsAudioSession: false
+    };
+  }
+  const ua = navigator.userAgent;
+  const isIOS = /iPad|iPhone|iPod/.test(ua) || navigator.platform === "MacIntel" && navigator.maxTouchPoints > 1;
+  const isSafari = /^((?!chrome|android).)*safari/i.test(ua) || /AppleWebKit/i.test(ua) && !/Chrome|CriOS|FxiOS/i.test(ua);
+  const isStandalone = "standalone" in window.navigator && Boolean(window.navigator.standalone) || window.matchMedia("(display-mode: standalone)").matches;
+  const supportsMediaSession = "mediaSession" in navigator;
+  const supportsAudioSession = "audioSession" in navigator;
+  return {
+    isIOS,
+    isSafari,
+    isStandalone,
+    supportsMediaSession,
+    supportsAudioSession
+  };
+}
+var platform = detectPlatform();
+
+// src/silentWav.ts
+var cachedSilentWavUrl = null;
+function getSilentWavUrl() {
+  if (cachedSilentWavUrl) {
+    return cachedSilentWavUrl;
+  }
+  if (typeof window === "undefined" || typeof Blob === "undefined") {
+    return "";
+  }
+  try {
+    const sampleRate = 8e3;
+    const durationSec = 2;
+    const numSamples = sampleRate * durationSec;
+    const buffer = new ArrayBuffer(44 + numSamples * 2);
+    const view = new DataView(buffer);
+    const writeString = (offset, str) => {
+      for (let i = 0; i < str.length; i++) {
+        view.setUint8(offset + i, str.charCodeAt(i));
+      }
+    };
+    writeString(0, "RIFF");
+    view.setUint32(4, 36 + numSamples * 2, true);
+    writeString(8, "WAVE");
+    writeString(12, "fmt ");
+    view.setUint32(16, 16, true);
+    view.setUint16(20, 1, true);
+    view.setUint16(22, 1, true);
+    view.setUint32(24, sampleRate, true);
+    view.setUint32(28, sampleRate * 2, true);
+    view.setUint16(32, 2, true);
+    view.setUint16(34, 16, true);
+    writeString(36, "data");
+    view.setUint32(40, numSamples * 2, true);
+    const blob = new Blob([buffer], { type: "audio/wav" });
+    cachedSilentWavUrl = URL.createObjectURL(blob);
+    return cachedSilentWavUrl;
+  } catch (err) {
+    console.error("[PwaPlayer:SilentWav] Failed to construct silent WAV blob:", err);
+    return "";
+  }
+}
+
+// src/keepAlive.ts
+var SilentHoldKeeper = class {
+  audioEl;
+  options;
+  events;
+  holding = false;
+  savedPauseTime = 0;
+  savedDuration = 0;
+  savedSongSrc = "";
+  savedTrack = null;
+  timeoutTimer = null;
+  constructor(audioEl, options = {}, events = {}) {
+    this.audioEl = audioEl;
+    this.options = {
+      strategy: options.strategy ?? "auto",
+      hardPauseTimeoutMs: options.hardPauseTimeoutMs ?? 5 * 60 * 1e3
+    };
+    this.events = events;
+  }
+  shouldActivateSilentHold() {
+    const strat = this.options.strategy;
+    if (strat === "silent-hold") return true;
+    if (strat === "native") return false;
+    return platform.isIOS;
+  }
+  isHolding() {
+    return this.holding;
+  }
+  getSavedPauseTime() {
+    return this.savedPauseTime;
+  }
+  updateSavedPauseTime(time) {
+    if (!this.holding) return;
+    this.savedPauseTime = Math.max(0, this.savedDuration > 0 ? Math.min(time, this.savedDuration) : time);
+  }
+  /**
+   * Intercept pause action.
+   * @returns true if handled by silent-hold keeper (caller MUST NOT call audio.pause())
+   */
+  handlePause(track, currentTime, duration, currentSrc) {
+    if (!this.shouldActivateSilentHold()) {
+      return false;
+    }
+    if (this.holding) {
+      console.info("[PwaPlayer:KeepAlive] AirPods Flip-Flop: Inverting pause action to resume.");
+      this.handleResume();
+      return true;
+    }
+    const songUrl = currentSrc || this.audioEl.src;
+    if (!songUrl || songUrl === window.location.href || songUrl.startsWith("blob:")) {
+      return false;
+    }
+    this.savedPauseTime = currentTime || this.audioEl.currentTime || 0;
+    this.savedDuration = duration > 0 && isFinite(duration) ? duration : this.audioEl.duration || 0;
+    this.savedSongSrc = songUrl;
+    this.savedTrack = track;
+    this.holding = true;
+    this.clearTimeoutTimer();
+    const silentUrl = getSilentWavUrl();
+    this.audioEl.loop = true;
+    this.audioEl.src = silentUrl;
+    this.audioEl.play().then(() => {
+      this.events.onKeepAliveEnter?.();
+    }).catch((err) => {
+      console.warn("[PwaPlayer:KeepAlive] Silent WAV play failed, falling back to native pause:", err);
+      this.reset();
+      try {
+        this.audioEl.pause();
+      } catch {
+      }
+    });
+    if (this.options.hardPauseTimeoutMs > 0) {
+      this.timeoutTimer = setTimeout(() => {
+        if (this.holding) {
+          console.info("[PwaPlayer:KeepAlive] Inactivity timeout reached. Executing hard pause to conserve power.");
+          this.reset();
+          try {
+            this.audioEl.pause();
+          } catch {
+          }
+          this.events.onHardPauseTimeout?.();
+        }
+      }, this.options.hardPauseTimeoutMs);
+      if (typeof this.timeoutTimer?.unref === "function") {
+        this.timeoutTimer.unref();
+      }
+    }
+    return true;
+  }
+  /**
+   * Intercept resume action.
+   * @returns true if handled by silent-hold recovery
+   */
+  handleResume(onPlaySuccess) {
+    if (!this.holding) {
+      return false;
+    }
+    this.clearTimeoutTimer();
+    const targetTime = this.savedPauseTime;
+    const songSrc = this.savedSongSrc;
+    this.holding = false;
+    this.audioEl.loop = false;
+    if (!songSrc || songSrc === window.location.href) {
+      return false;
+    }
+    this.audioEl.src = songSrc;
+    this.audioEl.play().then(() => {
+      const doSeek = () => {
+        try {
+          if (targetTime > 0) {
+            this.audioEl.currentTime = targetTime;
+          }
+        } catch (e) {
+          console.warn("[PwaPlayer:KeepAlive] Breakpoint seek failed:", e);
+        }
+        this.events.onKeepAliveExit?.();
+        onPlaySuccess?.();
+      };
+      if (this.audioEl.readyState >= 1 && this.audioEl.duration > 0) {
+        setTimeout(doSeek, 50);
+      } else {
+        const onMetadata = () => {
+          this.audioEl.removeEventListener("loadedmetadata", onMetadata);
+          setTimeout(doSeek, 50);
+        };
+        this.audioEl.addEventListener("loadedmetadata", onMetadata);
+      }
+    }).catch((err) => {
+      console.error("[PwaPlayer:KeepAlive] Track resume failed:", err);
+      this.holding = false;
+      this.audioEl.loop = false;
+    });
+    return true;
+  }
+  reset() {
+    this.clearTimeoutTimer();
+    this.holding = false;
+    this.savedPauseTime = 0;
+    this.savedDuration = 0;
+    this.savedSongSrc = "";
+    this.savedTrack = null;
+    try {
+      this.audioEl.loop = false;
+    } catch {
+    }
+  }
+  clearTimeoutTimer() {
+    if (this.timeoutTimer) {
+      clearTimeout(this.timeoutTimer);
+      this.timeoutTimer = null;
+    }
+  }
+};
+
+// src/mediaSession.ts
+var MediaSessionController = class {
+  callbacks;
+  enforceNavigation;
+  lastSyncedTrackId = null;
+  lastSyncedLyricText = null;
+  constructor(callbacks, enforceNavigation = true) {
+    this.callbacks = callbacks;
+    this.enforceNavigation = enforceNavigation;
+  }
+  isSupported() {
+    return typeof window !== "undefined" && "mediaSession" in navigator;
+  }
+  registerHandlers() {
+    if (!this.isSupported()) return;
+    try {
+      navigator.mediaSession.setActionHandler("play", () => this.callbacks.onPlay());
+      navigator.mediaSession.setActionHandler("pause", () => this.callbacks.onPause());
+      navigator.mediaSession.setActionHandler("previoustrack", () => this.callbacks.onPrev());
+      navigator.mediaSession.setActionHandler("nexttrack", () => this.callbacks.onNext());
+      if (this.enforceNavigation) {
+        try {
+          navigator.mediaSession.setActionHandler("seekbackward", null);
+        } catch {
+        }
+        try {
+          navigator.mediaSession.setActionHandler("seekforward", null);
+        } catch {
+        }
+        try {
+          navigator.mediaSession.setActionHandler("seekto", null);
+        } catch {
+        }
+      }
+    } catch (e) {
+      console.warn("[PwaPlayer:MediaSession] Failed to register action handlers:", e);
+    }
+  }
+  updatePlaybackState(state) {
+    if (!this.isSupported()) return;
+    try {
+      navigator.mediaSession.playbackState = state;
+    } catch {
+    }
+  }
+  updateMetadata(track, lyricInfo) {
+    if (!this.isSupported()) return;
+    if (!track) {
+      navigator.mediaSession.metadata = null;
+      this.lastSyncedTrackId = null;
+      this.lastSyncedLyricText = null;
+      return;
+    }
+    const currentLine = lyricInfo?.currentLine?.trim();
+    const nextLine = lyricInfo?.nextLine?.trim();
+    const title = currentLine || track.title;
+    const artist = currentLine ? `${track.title}${track.artist ? ` \xB7 ${track.artist}` : ""}` : track.artist || "Unknown Artist";
+    const album = nextLine ? `\u23ED ${nextLine}` : track.album || track.title;
+    if (navigator.mediaSession.metadata && this.lastSyncedTrackId === track.id && this.lastSyncedLyricText === currentLine) {
+      return;
+    }
+    this.lastSyncedTrackId = track.id;
+    this.lastSyncedLyricText = currentLine ?? null;
+    try {
+      navigator.mediaSession.metadata = new MediaMetadata({
+        title,
+        artist,
+        album,
+        artwork: this.normalizeArtwork(track.artwork)
+      });
+    } catch (err) {
+      console.warn("[PwaPlayer:MediaSession] Failed to update MediaMetadata:", err);
+    }
+  }
+  updatePosition(position, duration, playbackRate = 1) {
+    if (!this.isSupported() || !("setPositionState" in navigator.mediaSession)) return;
+    if (duration > 0 && isFinite(duration)) {
+      try {
+        navigator.mediaSession.setPositionState({
+          duration,
+          playbackRate,
+          position: Math.min(Math.max(0, position), duration)
+        });
+      } catch (err) {
+        console.warn("[PwaPlayer:MediaSession] setPositionState failed:", err);
+      }
+    }
+  }
+  clearPosition() {
+    if (!this.isSupported() || !("setPositionState" in navigator.mediaSession)) return;
+    try {
+      navigator.mediaSession.setPositionState();
+    } catch {
+      try {
+        navigator.mediaSession.setPositionState(null);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Apply Triple-Lock UI Masking during silent-hold keep-alive:
+   * 1. Mask playbackState as 'paused' so the OS displays ▶️ and stops fake progress calculation
+   * 2. Retain current track metadata (title, artist, artwork) so lockscreen card remains intact
+   * 3. Freeze setPositionState at exact breakpoint position
+   */
+  applyTripleInvisibleLock(track, duration, position) {
+    if (!this.isSupported()) return;
+    this.updatePlaybackState("paused");
+    if (track) {
+      this.updateMetadata(track);
+    }
+    this.updatePosition(position, duration, 1);
+  }
+  normalizeArtwork(artwork) {
+    if (Array.isArray(artwork)) {
+      return artwork;
+    }
+    const defaultUrl = artwork || "";
+    if (!defaultUrl) return [];
+    let resolvedUrl = defaultUrl;
+    try {
+      resolvedUrl = new URL(defaultUrl, window.location.href).href;
+    } catch {
+    }
+    return [
+      { src: resolvedUrl, sizes: "96x96" },
+      { src: resolvedUrl, sizes: "128x128" },
+      { src: resolvedUrl, sizes: "192x192" },
+      { src: resolvedUrl, sizes: "256x256" },
+      { src: resolvedUrl, sizes: "384x384" },
+      { src: resolvedUrl, sizes: "512x512" }
+    ];
+  }
+};
+
+// src/playlist.ts
+var PlaylistManager = class {
+  queue = [];
+  currentIndex = 0;
+  playMode = "sequence";
+  shuffleIndices = [];
+  shufflePointer = 0;
+  constructor(initialQueue = [], initialIndex = 0, initialMode = "sequence") {
+    this.queue = [...initialQueue];
+    this.currentIndex = Math.max(0, Math.min(initialIndex, this.queue.length - 1));
+    this.playMode = initialMode;
+    if (this.playMode === "shuffle") {
+      this.rebuildShuffleOrder();
+    }
+  }
+  getQueue() {
+    return [...this.queue];
+  }
+  getCurrentIndex() {
+    return this.currentIndex;
+  }
+  getCurrentTrack() {
+    if (this.currentIndex >= 0 && this.currentIndex < this.queue.length) {
+      return this.queue[this.currentIndex];
+    }
+    return null;
+  }
+  getPlayMode() {
+    return this.playMode;
+  }
+  setPlayMode(mode) {
+    this.playMode = mode;
+    if (mode === "shuffle") {
+      this.rebuildShuffleOrder();
+    }
+  }
+  setQueue(tracks, startIndex = 0) {
+    this.queue = [...tracks];
+    this.currentIndex = Math.max(0, Math.min(startIndex, this.queue.length - 1));
+    if (this.playMode === "shuffle") {
+      this.rebuildShuffleOrder();
+    }
+  }
+  setIndex(index) {
+    if (index >= 0 && index < this.queue.length) {
+      this.currentIndex = index;
+      return true;
+    }
+    return false;
+  }
+  getNextIndex() {
+    if (this.queue.length === 0) return -1;
+    if (this.playMode === "single") {
+      return this.currentIndex;
+    }
+    if (this.playMode === "shuffle") {
+      if (this.shuffleIndices.length === 0) this.rebuildShuffleOrder();
+      const nextPointer = (this.shufflePointer + 1) % this.shuffleIndices.length;
+      return this.shuffleIndices[nextPointer];
+    }
+    if (this.playMode === "loop") {
+      return (this.currentIndex + 1) % this.queue.length;
+    }
+    const next = this.currentIndex + 1;
+    return next < this.queue.length ? next : -1;
+  }
+  getPrevIndex() {
+    if (this.queue.length === 0) return -1;
+    if (this.playMode === "single") {
+      return this.currentIndex;
+    }
+    if (this.playMode === "shuffle") {
+      if (this.shuffleIndices.length === 0) this.rebuildShuffleOrder();
+      const prevPointer = (this.shufflePointer - 1 + this.shuffleIndices.length) % this.shuffleIndices.length;
+      return this.shuffleIndices[prevPointer];
+    }
+    if (this.playMode === "loop") {
+      return (this.currentIndex - 1 + this.queue.length) % this.queue.length;
+    }
+    const prev = this.currentIndex - 1;
+    return prev >= 0 ? prev : -1;
+  }
+  stepNext() {
+    const nextIdx = this.getNextIndex();
+    if (nextIdx >= 0) {
+      this.currentIndex = nextIdx;
+      if (this.playMode === "shuffle") {
+        this.shufflePointer = (this.shufflePointer + 1) % this.shuffleIndices.length;
+      }
+      return this.getCurrentTrack();
+    }
+    return null;
+  }
+  stepPrev() {
+    const prevIdx = this.getPrevIndex();
+    if (prevIdx >= 0) {
+      this.currentIndex = prevIdx;
+      if (this.playMode === "shuffle") {
+        this.shufflePointer = (this.shufflePointer - 1 + this.shuffleIndices.length) % this.shuffleIndices.length;
+      }
+      return this.getCurrentTrack();
+    }
+    return null;
+  }
+  shuffle() {
+    this.rebuildShuffleOrder();
+  }
+  rebuildShuffleOrder() {
+    const len = this.queue.length;
+    this.shuffleIndices = Array.from({ length: len }, (_, i) => i);
+    for (let i = len - 1; i > 0; i--) {
+      const j = Math.floor(Math.random() * (i + 1));
+      [this.shuffleIndices[i], this.shuffleIndices[j]] = [this.shuffleIndices[j], this.shuffleIndices[i]];
+    }
+    const currentPos = this.shuffleIndices.indexOf(this.currentIndex);
+    if (currentPos > 0) {
+      [this.shuffleIndices[0], this.shuffleIndices[currentPos]] = [this.shuffleIndices[currentPos], this.shuffleIndices[0]];
+    }
+    this.shufflePointer = 0;
+  }
+};
+
+// src/gesture.ts
+var GestureGuardian = class {
+  preloadedUrls = /* @__PURE__ */ new Set();
+  /**
+   * Preload adjacent tracks (both next and previous) concurrently
+   * while the current track is actively playing.
+   */
+  preloadSurroundingTracks(queue, currentIndex) {
+    if (typeof document === "undefined" || !queue.length) return;
+    const targets = [];
+    const nextIdx = (currentIndex + 1) % queue.length;
+    if (nextIdx !== currentIndex && queue[nextIdx]) {
+      targets.push(queue[nextIdx]);
+    }
+    const prevIdx = (currentIndex - 1 + queue.length) % queue.length;
+    if (prevIdx !== currentIndex && prevIdx !== nextIdx && queue[prevIdx]) {
+      targets.push(queue[prevIdx]);
+    }
+    for (const track of targets) {
+      if (!track.src || this.preloadedUrls.has(track.src)) continue;
+      this.warmupAudioUrl(track.src);
+    }
+  }
+  warmupAudioUrl(url) {
+    if (!url || url.startsWith("blob:")) return;
+    this.preloadedUrls.add(url);
+    try {
+      const link = document.createElement("link");
+      link.rel = "preload";
+      link.as = "fetch";
+      link.href = url;
+      link.crossOrigin = "anonymous";
+      document.head.appendChild(link);
+      const timer = setTimeout(() => {
+        try {
+          if (link.parentNode) link.parentNode.removeChild(link);
+        } catch {
+        }
+      }, 3e4);
+      if (typeof timer?.unref === "function") {
+        timer.unref();
+      }
+    } catch {
+      try {
+        fetch(url, { headers: { Range: "bytes=0-32767" } }).catch(() => {
+        });
+      } catch {
+      }
+    }
+  }
+  clear() {
+    this.preloadedUrls.clear();
+  }
+};
+
+// src/lyric.ts
+function parseLrc(lrcText) {
+  if (!lrcText || typeof lrcText !== "string") return [];
+  const lines = lrcText.split("\n");
+  const result = [];
+  const timeRegex = /\[(\d{1,2}):(\d{1,2})(?:\.(\d{1,3}))?\]/g;
+  for (const line of lines) {
+    timeRegex.lastIndex = 0;
+    const matches = [];
+    let match;
+    while ((match = timeRegex.exec(line)) !== null) {
+      const min = parseInt(match[1], 10);
+      const sec = parseInt(match[2], 10);
+      const ms = match[3] ? parseInt(match[3].padEnd(3, "0").slice(0, 3), 10) : 0;
+      matches.push(min * 60 + sec + ms / 1e3);
+    }
+    const text = line.replace(/\[\d{1,2}:\d{1,2}(?:\.\d{1,3})?\]/g, "").trim();
+    if (text) {
+      for (const t of matches) {
+        result.push({ time: t, text });
+      }
+    }
+  }
+  return result.sort((a, b) => a.time - b.time);
+}
+function getActiveLyric(lyrics, currentTime) {
+  if (!lyrics.length) {
+    return { index: -1 };
+  }
+  let low = 0;
+  let high = lyrics.length - 1;
+  let matchedIndex = -1;
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2);
+    if (lyrics[mid].time <= currentTime) {
+      matchedIndex = mid;
+      low = mid + 1;
+    } else {
+      high = mid - 1;
+    }
+  }
+  if (matchedIndex === -1) {
+    return {
+      index: -1,
+      nextLine: lyrics[0]?.text
+    };
+  }
+  return {
+    index: matchedIndex,
+    currentLine: lyrics[matchedIndex]?.text,
+    nextLine: lyrics[matchedIndex + 1]?.text
+  };
+}
+
+// src/player.ts
+var activePlayers = /* @__PURE__ */ new Set();
+var PwaPlayer = class {
+  audioEl;
+  playlist;
+  keepAlive;
+  mediaSession;
+  gesture;
+  isPlaying = false;
+  currentTime = 0;
+  duration = 0;
+  volume = 1;
+  listeners = /* @__PURE__ */ new Set();
+  parsedLyrics = [];
+  activeLyricIndex = -2;
+  activeLyricText = "";
+  enableLockscreenLyrics;
+  preloadAdjacent;
+  cachedState = null;
+  constructor(options = {}) {
+    if (options.audioElement) {
+      this.audioEl = options.audioElement;
+    } else if (typeof document !== "undefined") {
+      this.audioEl = document.createElement("audio");
+      this.audioEl.setAttribute("playsinline", "true");
+      this.audioEl.preload = "auto";
+    } else {
+      this.audioEl = {};
+    }
+    this.enableLockscreenLyrics = options.enableLockscreenLyrics ?? true;
+    this.preloadAdjacent = options.preloadAdjacent ?? true;
+    this.playlist = new PlaylistManager(
+      options.initialQueue ?? [],
+      options.initialIndex ?? 0,
+      options.initialMode ?? "sequence"
+    );
+    this.gesture = new GestureGuardian();
+    this.keepAlive = new SilentHoldKeeper(
+      this.audioEl,
+      options.keepAlive,
+      {
+        onKeepAliveEnter: () => {
+          const track = this.playlist.getCurrentTrack();
+          this.mediaSession.applyTripleInvisibleLock(
+            track,
+            this.duration,
+            this.keepAlive.getSavedPauseTime()
+          );
+          this.notify();
+        },
+        onKeepAliveExit: () => {
+          this.mediaSession.updatePlaybackState("playing");
+          const track = this.playlist.getCurrentTrack();
+          this.mediaSession.updateMetadata(track);
+          this.notify();
+        },
+        onHardPauseTimeout: () => {
+          this.isPlaying = false;
+          this.mediaSession.updatePlaybackState("paused");
+          this.notify();
+        }
+      }
+    );
+    this.mediaSession = new MediaSessionController(
+      {
+        onPlay: () => this.handleMediaSessionPlay(),
+        onPause: () => this.pause(),
+        onPrev: () => this.prev(),
+        onNext: () => this.next()
+      },
+      options.enforceTrackNavigation ?? true
+    );
+    this.bindAudioEvents();
+    this.mediaSession.registerHandlers();
+    const initialTrack = this.playlist.getCurrentTrack();
+    if (initialTrack) {
+      this.prepareTrack(initialTrack, false);
+    }
+    activePlayers.add(this);
+  }
+  // ================= Public Playback Controls =================
+  async play() {
+    for (const other of activePlayers) {
+      if (other !== this && other.isPlaying) {
+        other.pause();
+      }
+    }
+    if (this.keepAlive.isHolding()) {
+      this.keepAlive.handleResume(() => {
+        this.isPlaying = true;
+        this.warmupAdjacent();
+        this.notify();
+      });
+      return;
+    }
+    const currentTrack = this.playlist.getCurrentTrack();
+    if (!currentTrack) return;
+    if (!this.audioEl.src || this.audioEl.src === window.location.href || this.audioEl.src.startsWith("blob:")) {
+      this.prepareTrack(currentTrack, true);
+      return;
+    }
+    try {
+      await this.audioEl.play();
+      this.isPlaying = true;
+      this.warmupAdjacent();
+      this.notify();
+    } catch (err) {
+      console.warn("[PwaPlayer] play() rejected:", err);
+      this.isPlaying = false;
+      this.notify();
+    }
+  }
+  pause() {
+    if (!this.audioEl) return;
+    this.currentTime = this.audioEl.currentTime || this.currentTime;
+    const handledByKeepAlive = this.keepAlive.handlePause(
+      this.playlist.getCurrentTrack(),
+      this.currentTime,
+      this.duration,
+      this.audioEl.src
+    );
+    if (handledByKeepAlive) {
+      this.isPlaying = false;
+      this.notify();
+      return;
+    }
+    try {
+      this.audioEl.pause();
+    } catch {
+    }
+    this.isPlaying = false;
+    this.mediaSession.updatePlaybackState("paused");
+    this.notify();
+  }
+  toggle() {
+    if (this.keepAlive.isHolding()) {
+      this.play();
+      return;
+    }
+    if (this.isPlaying || !this.audioEl.paused && this.audioEl.currentTime > 0) {
+      this.pause();
+    } else {
+      this.play();
+    }
+  }
+  async next() {
+    this.keepAlive.reset();
+    this.mediaSession.clearPosition();
+    const track = this.playlist.stepNext();
+    if (!track) {
+      this.pause();
+      return;
+    }
+    this.prepareTrack(track, true);
+  }
+  async prev() {
+    this.keepAlive.reset();
+    this.mediaSession.clearPosition();
+    const track = this.playlist.stepPrev();
+    if (!track) {
+      this.pause();
+      return;
+    }
+    this.prepareTrack(track, true);
+  }
+  seek(seconds) {
+    const target = Math.max(0, this.duration > 0 ? Math.min(seconds, this.duration) : seconds);
+    this.currentTime = target;
+    if (this.keepAlive.isHolding()) {
+      this.keepAlive.updateSavedPauseTime(target);
+      this.mediaSession.applyTripleInvisibleLock(this.playlist.getCurrentTrack(), this.duration, target);
+      this.notify();
+      return;
+    }
+    try {
+      this.audioEl.currentTime = target;
+    } catch {
+    }
+    this.mediaSession.updatePosition(target, this.duration);
+    this.notify();
+  }
+  setQueue(tracks, startIndex = 0, autoPlay = true) {
+    this.keepAlive.reset();
+    this.mediaSession.clearPosition();
+    this.playlist.setQueue(tracks, startIndex);
+    const track = this.playlist.getCurrentTrack();
+    if (track) {
+      this.prepareTrack(track, autoPlay);
+    } else {
+      this.resetSource();
+    }
+  }
+  playTrackByIndex(index) {
+    if (this.playlist.setIndex(index)) {
+      this.keepAlive.reset();
+      this.mediaSession.clearPosition();
+      const track = this.playlist.getCurrentTrack();
+      if (track) {
+        this.prepareTrack(track, true);
+      }
+    }
+  }
+  setPlayMode(mode) {
+    this.playlist.setPlayMode(mode);
+    this.warmupAdjacent();
+    this.notify();
+  }
+  setVolume(val) {
+    this.volume = Math.max(0, Math.min(1, val));
+    if (this.audioEl) {
+      try {
+        this.audioEl.volume = this.volume;
+      } catch {
+      }
+    }
+    this.notify();
+  }
+  // ================= State & Subscription =================
+  getState() {
+    if (!this.cachedState) {
+      this.rebuildCachedState();
+    }
+    return this.cachedState;
+  }
+  rebuildCachedState() {
+    const isHold = this.keepAlive.isHolding();
+    this.cachedState = {
+      currentTrack: this.playlist.getCurrentTrack(),
+      playbackState: this.getPlaybackState(),
+      isPlaying: this.isPlaying,
+      isHolding: isHold,
+      currentTime: this.currentTime,
+      duration: this.duration,
+      queue: this.playlist.getQueue(),
+      queueIndex: this.playlist.getCurrentIndex(),
+      playMode: this.playlist.getPlayMode(),
+      volume: this.volume,
+      activeLyricIndex: this.activeLyricIndex,
+      activeLyricText: this.activeLyricText
+    };
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    listener(this.getState());
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  destroy() {
+    activePlayers.delete(this);
+    this.keepAlive.reset();
+    this.gesture.clear();
+    this.listeners.clear();
+    try {
+      this.audioEl.pause();
+      this.audioEl.src = "";
+    } catch {
+    }
+  }
+  // ================= Internal Mechanics =================
+  getPlaybackState() {
+    if (this.keepAlive.isHolding()) return "holding";
+    if (this.isPlaying) return "playing";
+    return this.currentTime > 0 ? "paused" : "idle";
+  }
+  notify() {
+    this.rebuildCachedState();
+    const state = this.cachedState;
+    for (const listener of this.listeners) {
+      try {
+        listener(state);
+      } catch (e) {
+        console.error("[PwaPlayer] Listener error:", e);
+      }
+    }
+  }
+  prepareTrack(track, autoPlay) {
+    this.currentTime = 0;
+    this.duration = track.duration || 0;
+    this.parsedLyrics = parseLrc(track.lrc);
+    this.activeLyricIndex = -2;
+    this.activeLyricText = "";
+    this.mediaSession.updateMetadata(track);
+    this.mediaSession.clearPosition();
+    if (this.audioEl) {
+      this.audioEl.src = track.src;
+      try {
+        this.audioEl.currentTime = 0;
+      } catch {
+      }
+    }
+    if (autoPlay) {
+      this.play();
+    } else {
+      this.notify();
+    }
+  }
+  resetSource() {
+    this.isPlaying = false;
+    this.currentTime = 0;
+    this.duration = 0;
+    try {
+      this.audioEl.pause();
+      this.audioEl.src = "";
+    } catch {
+    }
+    this.mediaSession.updateMetadata(null);
+    this.notify();
+  }
+  warmupAdjacent() {
+    if (this.preloadAdjacent) {
+      this.gesture.preloadSurroundingTracks(
+        this.playlist.getQueue(),
+        this.playlist.getCurrentIndex()
+      );
+    }
+  }
+  handleMediaSessionPlay() {
+    if (this.keepAlive.isHolding()) {
+      this.toggle();
+      return;
+    }
+    if (this.audioEl.paused) {
+      this.play();
+    }
+  }
+  bindAudioEvents() {
+    if (!this.audioEl || typeof this.audioEl.addEventListener !== "function") return;
+    this.audioEl.addEventListener("play", () => {
+      if (this.keepAlive.isHolding()) return;
+      this.isPlaying = true;
+      this.mediaSession.registerHandlers();
+      this.mediaSession.updatePlaybackState("playing");
+      const track = this.playlist.getCurrentTrack();
+      if (track) {
+        this.mediaSession.updateMetadata(track);
+      }
+      this.mediaSession.updatePosition(this.currentTime, this.duration);
+      this.warmupAdjacent();
+      this.notify();
+    });
+    this.audioEl.addEventListener("pause", () => {
+      if (this.keepAlive.isHolding()) return;
+      this.isPlaying = false;
+      this.mediaSession.updatePlaybackState("paused");
+      this.mediaSession.updatePosition(this.currentTime, this.duration);
+      this.notify();
+    });
+    this.audioEl.addEventListener("timeupdate", () => {
+      if (this.keepAlive.isHolding()) return;
+      this.currentTime = this.audioEl.currentTime;
+      if (this.audioEl.duration && !isNaN(this.audioEl.duration) && isFinite(this.audioEl.duration)) {
+        this.duration = this.audioEl.duration;
+      }
+      if (this.enableLockscreenLyrics && this.parsedLyrics.length > 0) {
+        const lyric = getActiveLyric(this.parsedLyrics, this.currentTime);
+        if (lyric.index !== this.activeLyricIndex) {
+          this.activeLyricIndex = lyric.index;
+          this.activeLyricText = lyric.currentLine || "";
+          this.mediaSession.updateMetadata(this.playlist.getCurrentTrack(), {
+            currentLine: lyric.currentLine,
+            nextLine: lyric.nextLine
+          });
+        }
+      }
+      this.notify();
+    });
+    this.audioEl.addEventListener("loadedmetadata", () => {
+      if (this.keepAlive.isHolding()) return;
+      if (this.audioEl.duration && !isNaN(this.audioEl.duration) && isFinite(this.audioEl.duration)) {
+        this.duration = this.audioEl.duration;
+      }
+      this.mediaSession.updatePosition(this.currentTime, this.duration);
+      this.notify();
+    });
+    this.audioEl.addEventListener("seeked", () => {
+      if (this.keepAlive.isHolding()) return;
+      this.currentTime = this.audioEl.currentTime;
+      this.mediaSession.updatePosition(this.currentTime, this.duration);
+      this.notify();
+    });
+    this.audioEl.addEventListener("ended", () => {
+      if (this.keepAlive.isHolding()) return;
+      this.next();
+    });
+    this.audioEl.addEventListener("error", () => {
+      if (this.keepAlive.isHolding()) return;
+      console.warn("[PwaPlayer] Audio element error encountered:", this.audioEl.error);
+      this.isPlaying = false;
+      this.notify();
+    });
+  }
+};
+function createPwaPlayer(options) {
+  return new PwaPlayer(options);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GestureGuardian,
+  MediaSessionController,
+  PlaylistManager,
+  PwaPlayer,
+  SilentHoldKeeper,
+  createPwaPlayer,
+  detectPlatform,
+  getActiveLyric,
+  getSilentWavUrl,
+  parseLrc,
+  platform
+});