openaudio-suite 2.5.5 → 2.6.1

package/OpenAudio_r.js

@@ -1,34 +1,32 @@
 /**
  * @file        OpenAudio_r.js
  * @author      Rexore
- * @version     2.4.0
- * @license     GPL-3.0-or-later
+ * @version     2.6.0
+ * @license     Apache-2.0
  *
- * audio_engine.js — A self-contained, randomised audio scheduling engine.
- * Copyright (C) 2025  Rexore
+ * OpenAudio_r.js — A self-contained, randomised audio scheduling engine.
+ * Copyright 2025 Rexore
  *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
  *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
+ *     https://www.apache.org/licenses/LICENSE-2.0
  *
- * You should have received a copy of the GNU General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
  *
  * Attach to any element or user action. No dependencies.
- *
  * ============================================================================
  * QUICK START
  * ============================================================================
  *
  * 1. Include the script:
  *
- *      <script src="audio_engine.js"></script>
+ *      <script src="OpenAudio_r.js"></script>
  *
  * 2. Create an engine instance with your clips:
  *
@@ -150,101 +148,82 @@
  * CHANGELOG
  * ============================================================================
  *
+ * 2.6.0
+ *   - All constructor and addClip() validation throws changed from Error to
+ *     TypeError. This matches the ECMAScript convention (and the behaviour of
+ *     OpenAudio.js and OpenAudio_s.js) that type-mismatch errors should be
+ *     TypeError so callers can distinguish them via instanceof.
+ *   - #isStarted is now set true inside the unlock .then() (after the Audio
+ *     element is confirmed usable), not at the top of start() before the
+ *     unlock. The duplicate-start guard during the unlock window is handled
+ *     by #isUnlocking, which is set immediately. This aligns the state machine
+ *     semantics with OpenAudio_s.js (D3).
+ *   - Expanded three compact single-line try/catch blocks in the onended
+ *     handler, #resetCycle(), and #playNext() .then() to multi-line style,
+ *     matching the formatting convention used in OpenAudio.js and
+ *     OpenAudio_s.js (S2).
+ *
+ * 2.5.0
+ *   - isStarted and isPlaying are now private fields (#isStarted, #isPlaying)
+ *     exposed via read-only getters. Previously they were plain public
+ *     properties, allowing callers to silently corrupt the state machine.
+ *     All internal guards updated to use #isStarted / #isPlaying.
+ *   - #isDestroyed flag: all public methods (start, stop, reset, setVolume,
+ *     addClip, destroy) now return immediately after destroy() has been
+ *     called, making post-destroy calls safe no-ops. Previously destroy()
+ *     documented post-destroy behaviour as "undefined"; in practice, calling
+ *     start() after destroy() would silently re-run the engine without a
+ *     visibility listener, causing partially torn-down state.
+ *   - destroy() now releases the Audio element via removeAttribute('src') +
+ *     load() per the WHATWG HTMLMediaElement resource-release spec, then nulls
+ *     #audio. Previously the element was kept live with its src intact.
+ *   - #isPlaying is now set true synchronously before #audio.play() in
+ *     #playNext(), closing the race window where isPlaying reported false
+ *     while audio was starting. Reverted to false in .catch() on failure.
+ *
+ * 2.4.1
+ *   - Licence changed from GPL-3.0-or-later to Apache-2.0 across the suite.
+ *
  * 2.4.0
  *   - #isUnlocking flag: start() now sets a private boolean during the silent
  *     MP3 unlock phase. Rapid repeated calls to start() before the unlock
  *     promise resolves are ignored, preventing multiple overlapping unlock
- *     attempts from racing each other. Previously only isStarted was checked,
- *     which was set synchronously — but the unlock play() is async, leaving a
- *     window where a spam-click could trigger duplicate #scheduleNext() calls.
+ *     attempts from racing each other.
  *   - destroy() method: removes the visibilitychange listener added in the
  *     constructor using a stored bound handler reference (#boundVisibility).
- *     Calling destroy() on teardown is essential in SPAs (React, Vue, etc.)
- *     where multiple engine instances may be created and destroyed over the
- *     component lifecycle. Without it, stale listeners accumulate on document
- *     and defunct engine instances wake up on every tab-focus event.
  *   - AudioEngine.canPlay(type) static method: wraps HTMLAudioElement
- *     .canPlayType() with a clean boolean return. Use this to check browser
- *     support for .ogg, .wav, or .flac sources before constructing an engine,
- *     rather than discovering a silent failure at play() time.
- *   - onCycleReset callback wrapped in try/catch, matching the existing
- *     resilience applied to onPlay and onEnd. A throwing onCycleReset can no
- *     longer stall the engine loop.
+ *     .canPlayType() with a clean boolean return.
+ *   - onCycleReset callback wrapped in try/catch.
  *   - Documentation: added HTML5 AUDIO vs. WEB AUDIO API comparison table and
  *     CALLBACK RESILIENCE section.
  *
  * 2.3.0
- *   - Clip src validation: constructor and addClip() now verify that every clip
- *     has a non-empty string src. Previously a clip with a missing or non-string
- *     src property would silently map undefined into the engine, producing a
- *     confusing audio error rather than a clear failure at the point of entry.
- *   - Next-clip prefetch: #scheduleNext() now sets #audio.src to the next
- *     selected clip immediately after the current clip ends, before the inter-
- *     clip delay fires. The browser begins buffering the file during the gap,
- *     eliminating the network fetch delay that previously occurred at #playNext()
- *     time. The clip is still marked played and selected at schedule time, not
- *     at play time, preserving shuffle-bag correctness.
- *   - Background tab throttling mitigation: #scheduleNext() records the wall-
- *     clock time at which the delay was set (#timerSetAt) and the intended
- *     duration (#timerDelay). A visibilitychange listener fires when the tab
- *     returns to the foreground: if the elapsed time has already met or exceeded
- *     the intended delay, the pending timer is cancelled and #playNext() is
- *     called immediately. If not, the remaining time is rescheduled precisely.
- *     This recovers pacing after background throttling without over-firing.
- *   - Documentation: added BACKGROUND TAB THROTTLING and WEB AUDIO API sections
- *     explaining the architectural limits of the HTML5 <audio> approach and
- *     guidance on when to consider migrating to the Web Audio API.
+ *   - Clip src validation in constructor and addClip().
+ *   - Next-clip prefetch: #scheduleNext() sets #audio.src to the next selected
+ *     clip during the inter-clip gap, eliminating network fetch delay.
+ *   - Background tab throttling mitigation via wall-clock correction.
  *
  * 2.2.0
- *   - True private fields (#) replace pseudo-private (_) properties throughout.
- *     External scripts can no longer accidentally read or mutate internal state,
- *     and attempting to do so throws a SyntaxError at parse time.
- *   - NotAllowedError handling: if the browser rejects play() due to an autoplay
- *     policy violation, the engine now calls stop() and halts rather than
- *     rescheduling. Previously, rescheduling on an autoplay block produced a
- *     silent infinite loop of blocked timeouts and console warnings.
- *   - Silent base64 unlock in start(): a 1-second silent MP3 is played
- *     synchronously within the gesture context to unlock the Audio element.
- *     _scheduleNext() is then called immediately so the first real clip
- *     respects the configured lowTime/maxTime delay. Previously the first clip
- *     always played with zero delay.
- *   - setVolume(value) public method: updates #volume and applies the new value
- *     to the live Audio element immediately, enabling real-time fading and
- *     volume sliders without waiting for the next clip.
+ *   - True private fields (#) replace pseudo-private (_) properties.
+ *   - NotAllowedError handling: engine halts rather than silent-loops.
+ *   - Silent base64 unlock in start().
+ *   - setVolume(value) public method.
  *
  * 2.1.1
- *   - Constructor now validates lowTime and maxTime: both must be non-negative
- *     numbers and lowTime must not exceed maxTime. Inverted or negative values
- *     previously caused silent setTimeout(0) looping with no warning.
- *   - _scheduleNext() clears any existing _timer before setting a new one,
- *     preventing a double-schedule race if onerror fires unexpectedly.
- *   - Cycle-boundary repeat fix: after a lazy reset with 2+ clips, _currentClip
- *     is excluded from the freshly-reset pool so the last clip of one cycle
- *     cannot immediately be the first clip of the next.
- *   - stop() no longer resets currentTime to 0. The interrupted clip's position
- *     is discarded (audio is paused); the next start() picks the next clip in
- *     the cycle. Resume-mid-clip is not a supported feature.
+ *   - Constructor validates lowTime and maxTime.
+ *   - #scheduleNext() clears existing timer before setting new one.
+ *   - Cycle-boundary repeat fix.
+ *   - stop() no longer resets currentTime.
  *
  * 2.1.0
- *   - Single reusable Audio element created once in the constructor.
- *     Satisfies strict mobile autoplay rules (iOS Safari) which require the
- *     Audio object itself to be created inside the gesture activation context.
- *     Previously a new Audio() was instantiated per clip inside _playNext(),
- *     which broke mobile autoplay after the first clip.
- *   - _scheduleNext() extracted as a named method (previously an inline closure).
- *   - stop() no longer needs to null-check a _currentAudio ref — it just
- *     pauses the single shared element directly.
- *   - _playNext() guards against stop() racing with a resolving play() promise
- *     (AbortError catch path and isStarted check after .then() resolves).
- *   - onEnd fires AFTER _scheduleNext() — a throwing callback can never
- *     prevent the next clip from scheduling.
- *   - onerror listener attached once in constructor rather than per-play.
+ *   - Single reusable Audio element created once in constructor.
+ *   - #scheduleNext() extracted as a named method.
+ *   - AbortError handling in #playNext().
+ *   - onerror listener attached once in constructor.
  *
  * 2.0.0
- *   - Initial public release.
- *   - Shuffle bag algorithm replacing naive Math.random() selection.
- *   - onPlay / onEnd / onCycleReset callbacks.
- *   - addClip() runtime insertion.
+ *   - Initial public release. Shuffle bag algorithm. onPlay / onEnd /
+ *     onCycleReset callbacks. addClip() runtime insertion.
  *
  * ============================================================================
  * HTML5 AUDIO vs. WEB AUDIO API — QUICK REFERENCE
@@ -290,25 +269,30 @@
  *                              Safe to call multiple times — ignored if running.
  *                              Ignores rapid repeat calls during the unlock phase
  *                              via an internal #isUnlocking flag.
+ *                              No-op after destroy().
  *
  *   engine.stop()              Stop engine. Cancels timer, pauses audio.
  *                              Preserves cycle state — start() resumes it.
+ *                              No-op after destroy().
  *
  *   engine.reset()             Stop and clear all played flags.
  *                              Next start() begins a fresh random cycle.
+ *                              No-op after destroy().
  *
- *   engine.destroy()           Stop the engine and remove all document-level event
- *                              listeners. Call this when tearing down the instance
- *                              in SPAs (React, Vue, etc.) to prevent listener
- *                              accumulation and memory leaks.
+ *   engine.destroy()           Stop the engine, release the Audio element, and
+ *                              remove all document-level event listeners. Call
+ *                              when tearing down in SPAs. All subsequent method
+ *                              calls are safe no-ops.
  *
  *   engine.addClip(clip)       Add a clip at runtime. Enters the pool immediately.
  *                              Throws if clip.src is missing or not a string.
+ *                              No-op after destroy().
  *
- *   engine.setVolume(value)    Set volume (0.0–1.0) immediately, affects live playback.
+ *   engine.setVolume(value)    Set volume (0.0–1.0) immediately, affects live
+ *                              playback. No-op after destroy().
  *
- *   engine.isStarted           {boolean}  True after first start() call.
- *   engine.isPlaying           {boolean}  True while a clip is actively playing.
+ *   engine.isStarted           {boolean}  Read-only. True after first start() call.
+ *   engine.isPlaying           {boolean}  Read-only. True while a clip is playing.
  *
  * ── STATIC UTILITY ──────────────────────────────────────────────────────────
  *
@@ -351,7 +335,11 @@ class AudioEngine {
   #currentClip;
   #nextClip;        // pre-selected clip loaded into #audio during the inter-clip gap
   #isUnlocking;     // true while the silent-MP3 unlock play() promise is pending
+  #isDestroyed;     // true after destroy(); all public methods become safe no-ops
   #boundVisibility; // bound handler reference stored for removeEventListener in destroy()
+  // Backing fields for the read-only isStarted / isPlaying getters.
+  #isStarted;
+  #isPlaying;
 
   /**
    * @param {Array<{ src: string, label?: string }>} clips
@@ -368,12 +356,13 @@ class AudioEngine {
    */
   constructor(clips = [], options = {}) {
     if (!Array.isArray(clips) || clips.length === 0) {
-      throw new Error('AudioEngine: clips must be a non-empty array.');
+      throw new TypeError('AudioEngine: clips must be a non-empty array.');
     }
+
     // Validate every clip has a non-empty string src before doing anything else
     const badClip = clips.findIndex(c => !c || typeof c.src !== 'string' || c.src.trim() === '');
     if (badClip !== -1) {
-      throw new Error(`AudioEngine: clips[${badClip}] is missing a valid src string.`);
+      throw new TypeError(`AudioEngine: clips[${badClip}] is missing a valid src string.`);
     }
 
     // Defensive copy — never mutate the caller's original array
@@ -388,13 +377,13 @@ class AudioEngine {
     this.#volume  = options.volume  ?? 0.85;
 
     if (typeof this.#lowTime !== 'number' || this.#lowTime < 0) {
-      throw new Error('AudioEngine: lowTime must be a non-negative number.');
+      throw new TypeError('AudioEngine: lowTime must be a non-negative number.');
     }
     if (typeof this.#maxTime !== 'number' || this.#maxTime < 0) {
-      throw new Error('AudioEngine: maxTime must be a non-negative number.');
+      throw new TypeError('AudioEngine: maxTime must be a non-negative number.');
     }
     if (this.#lowTime > this.#maxTime) {
-      throw new Error(`AudioEngine: lowTime (${this.#lowTime}) must not exceed maxTime (${this.#maxTime}).`);
+      throw new TypeError(`AudioEngine: lowTime (${this.#lowTime}) must not exceed maxTime (${this.#maxTime}).`);
     }
 
     this.#onPlay       = options.onPlay       || null;
@@ -404,9 +393,10 @@ class AudioEngine {
     this.#timer       = null;
     this.#timerSetAt  = null;
     this.#timerDelay  = null;
-    this.isStarted    = false;
-    this.isPlaying    = false;
+    this.#isStarted   = false;
+    this.#isPlaying   = false;
     this.#isUnlocking = false;
+    this.#isDestroyed = false;
 
     // Single reusable Audio element — created once here so that mobile browsers
     // (iOS Safari) keep it within the gesture activation context for all
@@ -415,17 +405,21 @@ class AudioEngine {
     this.#currentClip = null;
     this.#nextClip    = null;
 
-    // Listeners attached once to avoid duplicates and memory leaks
+    // Listeners attached once to avoid duplicates and memory leaks.
     this.#audio.onended = () => {
-      if (!this.isStarted) return;
-      // Schedule next BEFORE firing callback — a throwing onEnd can never stall the engine
+      if (!this.#isStarted) return;
+      // Schedule next BEFORE firing callback — a throwing onEnd can never stall the engine.
       this.#scheduleNext();
-      try { if (this.#onEnd) this.#onEnd(this.#currentClip); } catch(e) { console.warn('AudioEngine: onEnd callback error:', e); }
+      try {
+        if (this.#onEnd) this.#onEnd(this.#currentClip);
+      } catch (e) {
+        console.warn('AudioEngine: onEnd callback error:', e);
+      }
     };
 
     this.#audio.onerror = (e) => {
       console.warn(`AudioEngine: audio error on "${this.#currentClip?.label}":`, e);
-      if (!this.isStarted) return;
+      if (!this.#isStarted) return;
       this.#scheduleNext();
     };
 
@@ -439,6 +433,12 @@ class AudioEngine {
 
   // ── PUBLIC API ─────────────────────────────────────────────────────────────
 
+  /** @returns {boolean} True after first start() call. Read-only. */
+  get isStarted() { return this.#isStarted; }
+
+  /** @returns {boolean} True while a clip is actively playing. Read-only. */
+  get isPlaying() { return this.#isPlaying; }
+
   /**
    * Start the engine.
    *
@@ -453,12 +453,17 @@ class AudioEngine {
    * Safe to call multiple times — silently ignored if already started or if
    * the unlock phase is still in progress (#isUnlocking), preventing a rapid
    * sequence of start() calls from triggering duplicate #scheduleNext() calls
-   * before the first unlock promise resolves.
+   * before the first unlock promise resolves. No-op after destroy().
+   *
+   * Design note (D3): #isStarted is set true inside the unlock .then(), after
+   * the Audio element is confirmed usable. This aligns with OpenAudio_s.js,
+   * which also sets #isStarted after the unlock resolves (inside #playClip()).
+   * The guard against duplicate start() calls during the unlock window is
+   * handled by #isUnlocking, not #isStarted.
    */
   start() {
-    if (this.isStarted || this.#isUnlocking) return;
+    if (this.#isDestroyed || this.#isStarted || this.#isUnlocking) return;
     this.#isUnlocking = true;
-    this.isStarted    = true;
 
     // Play the silent clip synchronously within the gesture context.
     // This "blesses" the Audio element on strict autoplay browsers (iOS Safari)
@@ -469,8 +474,10 @@ class AudioEngine {
     this.#audio.play()
       .then(() => {
         this.#isUnlocking = false;
-        if (!this.isStarted) return;
-        // Restore volume and schedule the first real clip with a random delay
+        if (this.#isDestroyed) return;
+        // Mark started only after the element is confirmed usable.
+        this.#isStarted    = true;
+        // Restore volume and schedule the first real clip with a random delay.
         this.#audio.volume = Math.min(1, Math.max(0, this.#volume));
         this.#scheduleNext();
       })
@@ -486,7 +493,7 @@ class AudioEngine {
           );
           this.stop();
         }
-        // AbortError or other — safe to ignore; stop() cleans up if needed
+        // AbortError or other — safe to ignore; stop() cleans up if needed.
       });
   }
 
@@ -495,22 +502,26 @@ class AudioEngine {
    * Cancels any pending timer and stops the current audio.
    * Played flags are preserved — call start() again to begin the next
    * clip in the cycle (the interrupted clip is not replayed).
+   * No-op after destroy().
    */
   stop() {
+    if (this.#isDestroyed) return;
     if (this.#timer) {
       clearTimeout(this.#timer);
       this.#timer = null;
     }
-    this.isStarted = false;
-    this.isPlaying = false;
+    this.#isStarted = false;
+    this.#isPlaying = false;
     this.#audio.pause();
   }
 
   /**
    * Stop the engine and reset all cycle state.
    * All played flags cleared — next start() begins a completely fresh cycle.
+   * No-op after destroy().
    */
   reset() {
+    if (this.#isDestroyed) return;
     this.stop();
     this.#clips.forEach(c => c.played = false);
   }
@@ -519,12 +530,14 @@ class AudioEngine {
    * Add a clip to the engine at runtime.
    * The clip is inserted into the pool immediately with played = false,
    * making it available for selection in the current or next cycle.
+   * No-op after destroy().
    *
    * @param {{ src: string, label?: string }} clip
    */
   addClip(clip) {
+    if (this.#isDestroyed) return;
     if (!clip || typeof clip.src !== 'string' || clip.src.trim() === '') {
-      throw new Error('AudioEngine.addClip: clip must have a non-empty string src property.');
+      throw new TypeError('AudioEngine.addClip: clip must have a non-empty string src property.');
     }
     this.#clips.push({
       src:    clip.src,
@@ -536,11 +549,13 @@ class AudioEngine {
   /**
    * Set the playback volume immediately.
    * Applies to the currently playing clip as well as all future clips.
+   * No-op after destroy().
    *
    * @param {number} value  Volume level from 0.0 (silent) to 1.0 (full).
    *                        Values outside this range are clamped.
    */
   setVolume(value) {
+    if (this.#isDestroyed) return;
     this.#volume = Math.min(1, Math.max(0, value));
     this.#audio.volume = this.#volume;
   }
@@ -548,18 +563,34 @@ class AudioEngine {
   /**
    * Destroy the engine instance.
    *
-   * Calls stop() and removes the visibilitychange event listener from
-   * document using the stored bound handler reference. Always call this
-   * when tearing down an AudioEngine in a Single Page Application
-   * (React, Vue, Angular, etc.) to prevent stale listeners accumulating
-   * on the document object across component mounts and unmounts.
+   * Stops the engine, releases the Audio element per the WHATWG
+   * HTMLMediaElement resource-release spec (removeAttribute('src') + load()),
+   * and removes the visibilitychange event listener from document using the
+   * stored bound handler reference. Always call this when tearing down an
+   * AudioEngine in a Single Page Application (React, Vue, Angular, etc.) to
+   * prevent stale listeners accumulating on the document object across
+   * component mounts and unmounts.
    *
-   * After destroy(), the instance should be discarded — behaviour of any
-   * further method calls is undefined.
+   * All subsequent method calls after destroy() are safe no-ops.
    */
   destroy() {
-    this.stop();
+    if (this.#isDestroyed) return;
+    this.#isDestroyed = true;
+    if (this.#timer) {
+      clearTimeout(this.#timer);
+      this.#timer = null;
+    }
+    this.#isStarted = false;
+    this.#isPlaying = false;
+    this.#audio.pause();
     document.removeEventListener('visibilitychange', this.#boundVisibility);
+    // WHATWG-specified resource-release sequence: removeAttribute('src') +
+    // load() aborts any in-progress network fetch and resets the media element
+    // state machine cleanly, avoiding the spurious 'error' events that
+    // src = '' can fire on some browsers.
+    this.#audio.removeAttribute('src');
+    this.#audio.load();
+    this.#audio = null;
   }
 
   /**
@@ -602,7 +633,11 @@ class AudioEngine {
    */
   #resetCycle() {
     this.#clips.forEach(c => c.played = false);
-    try { if (this.#onCycleReset) this.#onCycleReset(); } catch(e) { console.warn('AudioEngine: onCycleReset callback error:', e); }
+    try {
+      if (this.#onCycleReset) this.#onCycleReset();
+    } catch (e) {
+      console.warn('AudioEngine: onCycleReset callback error:', e);
+    }
   }
 
   /**
@@ -619,18 +654,18 @@ class AudioEngine {
    */
   #onVisibilityChange() {
     if (document.visibilityState !== 'visible') return;
-    if (!this.isStarted || !this.#timer || this.#timerSetAt === null) return;
+    if (!this.#isStarted || !this.#timer || this.#timerSetAt === null) return;
 
     const elapsed = Date.now() - this.#timerSetAt;
     if (elapsed >= this.#timerDelay) {
-      // Timer should already have fired — play immediately
+      // Timer should already have fired — play immediately.
       clearTimeout(this.#timer);
       this.#timer      = null;
       this.#timerSetAt = null;
       this.#timerDelay = null;
       this.#playNext();
     } else {
-      // Reschedule precisely for the remaining duration
+      // Reschedule precisely for the remaining duration.
       const remaining = this.#timerDelay - elapsed;
       clearTimeout(this.#timer);
       this.#timerSetAt = Date.now();
@@ -640,13 +675,12 @@ class AudioEngine {
   }
 
   /**
+   * Schedules the next clip after a random inter-clip delay in [lowTime, maxTime].
    *
-   * Pre-selecting and pre-fetching during the gap means the browser starts
-   * buffering the next file immediately after the current one ends, rather
-   * than waiting until the timer fires. This eliminates the network latency
-   * that would otherwise appear between the timer firing and audio actually
-   * beginning to play, particularly noticeable on slow connections or with
-   * large files.
+   * Pre-selects and pre-fetches the clip during the gap so the browser starts
+   * buffering the file immediately after the current clip ends, rather than
+   * waiting for the timer to fire. This eliminates network fetch latency that
+   * would otherwise be noticeable on slow connections or large files.
    *
    * #timerSetAt and #timerDelay are recorded so the visibilitychange listener
    * can recalculate remaining time accurately after background tab throttling.
@@ -656,7 +690,7 @@ class AudioEngine {
       clearTimeout(this.#timer);
       this.#timer = null;
     }
-    this.isPlaying = false;
+    this.#isPlaying = false;
 
     // Pre-select the next clip now, during the gap, so shuffle-bag state
     // stays consistent regardless of how long the delay runs.
@@ -712,9 +746,13 @@ class AudioEngine {
    * time this method fires, the browser has had the full delay period to
    * buffer the file, eliminating the fetch latency that would occur if src
    * were assigned here instead.
+   *
+   * #isPlaying is set true synchronously before #audio.play() to close the
+   * race window where isPlaying reported false while audio was starting.
+   * Reverted in .catch() on real failure.
    */
   #playNext() {
-    if (!this.isStarted) return;
+    if (!this.#isStarted) return;
 
     // Consume the pre-selected clip. If somehow null (e.g. called directly
     // before #scheduleNext has run), fall back to selecting now.
@@ -722,7 +760,7 @@ class AudioEngine {
     this.#nextClip    = null;
     this.#currentClip = clip;
 
-    // Restore volume — was zeroed during prefetch to suppress decode artefacts
+    // Restore volume — was zeroed during prefetch to suppress decode artefacts.
     this.#audio.volume = Math.min(1, Math.max(0, this.#volume));
     this.#audio.loop   = false;
 
@@ -732,28 +770,37 @@ class AudioEngine {
       this.#audio.src = clip.src;
     }
 
-    this.#audio.play().then(() => {
-      if (!this.isStarted) {
-        this.#audio.pause();
-        return;
-      }
-      this.isPlaying = true;
-      try { if (this.#onPlay) this.#onPlay(clip); } catch(e) { console.warn('AudioEngine: onPlay callback error:', e); }
-
-    }).catch(err => {
-      if (err.name === 'AbortError' || !this.isStarted) return;
-
-      if (err.name === 'NotAllowedError') {
-        console.warn(
-          `AudioEngine: play() blocked by autoplay policy for "${clip.label}". ` +
-          `Halting engine. Call start() again inside a user gesture to resume.`
-        );
-        this.stop();
-      } else {
-        console.warn(`AudioEngine: play() failed for "${clip.label}".\nError: ${err}`);
-        this.#scheduleNext();
-      }
-    });
+    // Set before the async boundary to close the isPlaying race window.
+    this.#isPlaying = true;
+
+    this.#audio.play()
+      .then(() => {
+        if (!this.#isStarted || this.#isDestroyed) {
+          this.#audio?.pause();
+          this.#isPlaying = false;
+          return;
+        }
+        try {
+          if (this.#onPlay) this.#onPlay(clip);
+        } catch (e) {
+          console.warn('AudioEngine: onPlay callback error:', e);
+        }
+      })
+      .catch(err => {
+        this.#isPlaying = false;   // revert the optimistic flag on failure
+        if (err.name === 'AbortError' || !this.#isStarted) return;
+
+        if (err.name === 'NotAllowedError') {
+          console.warn(
+            `AudioEngine: play() blocked by autoplay policy for "${clip.label}". ` +
+            `Halting engine. Call start() again inside a user gesture to resume.`
+          );
+          this.stop();
+        } else {
+          console.warn(`AudioEngine: play() failed for "${clip.label}".\nError: ${err}`);
+          this.#scheduleNext();
+        }
+      });
   }
 }
 
@@ -848,7 +895,7 @@ if (!AudioEngine.canPlay('audio/ogg')) {
 // React example:
 // useEffect(() => {
 //   const engine = new AudioEngine(clips);
-//   return () => engine.destroy(); // removes visibilitychange listener on unmount
+//   return () => engine.destroy(); // removes listener, releases audio on unmount
 // }, []);
 
 // Vue example: