openaudio-suite 2.5.5 → 2.6.1

package/docs/OPENAUDIO_S.md

@@ -1,7 +1,7 @@
 # OpenAudio_s.js API Reference
 
-**Version:** 1.0.0  
-**Class:** `SequentialAudio`  
+**Version:** 1.3.0
+**Class:** `SequentialAudio`
 **Use Case:** Sequential/playlist playback with manual or auto-advance
 
 ---
@@ -9,26 +9,21 @@
 ## Quick Start
 
 ```javascript
-// Create a player
 const player = new SequentialAudio([
-  { src: 'intro.mp3', label: 'Introduction' },
+  { src: 'intro.mp3',    label: 'Introduction' },
   { src: 'chapter1.mp3', label: 'Chapter 1' },
   { src: 'chapter2.mp3', label: 'Chapter 2' }
 ], {
-  autoAdvance: false,  // Require manual click to advance
-  onPlay: (clip) => console.log(`Playing: ${clip.label}`),
-  onComplete: () => console.log('All clips finished!')
+  autoAdvance: false,
+  onPlay:      (clip) => console.log(`Playing: ${clip.label}`),
+  onComplete:  ()     => console.log('All clips finished!')
 });
 
-// Start the sequence
-document.getElementById('play-btn').addEventListener('click', () => {
-  player.play();
-});
+// Start — must be inside a user gesture
+document.getElementById('play-btn').addEventListener('click', () => player.play());
 
 // Advance to next clip
-document.getElementById('next-btn').addEventListener('click', () => {
-  player.next();
-});
+document.getElementById('next-btn').addEventListener('click', () => player.next());
 ```
 
 ---
@@ -54,63 +49,35 @@ Array of clip objects in playback order.
 
 Each clip object:
 - **`src`** (string, required) — Path or data URI to audio file
-- **`label`** (string) — Display name for console/callbacks
+- **`label`** (string, optional) — Display name for console/callbacks
 
 #### `options` (object, optional)
 
 ```javascript
 {
-  autoAdvance: false,        // Boolean: auto-play next clip after current ends
-  loop:        false,        // Boolean: loop sequence when complete
-  onPlay:      (clip) => {}, // Function: called when clip starts
-  onEnd:       (clip) => {}, // Function: called when clip ends
-  onComplete:  () => {}      // Function: called when sequence finishes
+  autoAdvance:  false,       // Boolean: auto-play next clip after current ends
+  advanceDelay: 0.5,         // Number: seconds to wait before auto-advance
+  loop:         false,       // Boolean: loop sequence when complete
+  volume:       1.0,         // Number: volume 0.0–1.0
+  onPlay:       (clip) => {},// Function: called when clip starts
+  onEnd:        (clip) => {},// Function: called when clip ends
+  onComplete:   () => {}     // Function: called when sequence finishes
 }
 ```
 
 **All options are optional.**
 
-### Constructor Examples
-
-```javascript
-// Minimal
-const player = new SequentialAudio([
-  { src: 'clip1.mp3' },
-  { src: 'clip2.mp3' }
-]);
-
-// With manual advance (require click between clips)
-const player = new SequentialAudio(clips, {
-  autoAdvance: false,
-  onPlay: (clip) => updateUI(clip.label)
-});
-
-// With auto-advance (play next automatically)
-const player = new SequentialAudio(clips, {
-  autoAdvance: true,
-  onComplete: () => showFinishScreen()
-});
-
-// With looping
-const player = new SequentialAudio(clips, {
-  loop: true,  // Restart sequence when complete
-  onComplete: () => console.log('Looping...')
-});
-```
-
 ### Constructor Errors
 
 ```javascript
-// Throws TypeError if clips is missing, empty, or invalid
-new SequentialAudio();                    // ❌ TypeError
-new SequentialAudio([]);                  // ❌ TypeError
-new SequentialAudio([{ src: '' }]);       // ❌ Empty src
+// Throws TypeError
+new SequentialAudio();                      // ❌ Missing clips
+new SequentialAudio([]);                    // ❌ Empty array
+new SequentialAudio([{ src: '' }]);         // ❌ Empty src
 new SequentialAudio([{ label: 'No src' }]); // ❌ Missing src
 
 // Valid
-new SequentialAudio([
-  { src: 'clip.mp3', label: 'Clip' }
-]); // ✅
+new SequentialAudio([{ src: 'clip.mp3', label: 'Clip' }]); // ✅
 ```
 
 ---
@@ -119,205 +86,135 @@ new SequentialAudio([
 
 ### `play()`
 
-Start playback from the first clip (or current position if paused).
-
-**Must be called inside a user gesture on first use.**
+Start the sequence. Must be called inside a user gesture on first use.
 
 ```javascript
-// First call (inside gesture)
-document.addEventListener('click', () => {
-  player.play();  // ✅ Starts from clip 0
-});
-
-// Subsequent calls
-player.play();  // Safe to call anytime
+document.addEventListener('click', () => player.play(), { once: true });
 ```
 
 **Behavior:**
-- If already playing: ignored (safe)
-- If paused: resumes from current position
-- If finished: starts from beginning
+- If already started or playing: ignored (safe)
+- If sequence has not started: unlocks Audio element and plays first clip
 
 ---
 
 ### `next()`
 
-Advance to the next clip and play it.
+Advance to the next clip and play it. No-op if `play()` has not been called yet.
 
 ```javascript
-player.next();  // Play next clip
+player.next();
 ```
 
 **Behavior:**
 - Increments clip index by 1
-- Plays the new clip
 - At end of sequence:
-  - If `loop: true` → Wraps to beginning and plays clip 0
-  - If `loop: false` → Stops and fires `onComplete`
-
-```javascript
-const player = new SequentialAudio([clip1, clip2, clip3], {
-  loop: false
-});
-
-player.goto(0);   // Clip 0
-player.next();    // Clip 1
-player.next();    // Clip 2
-player.next();    // Stops, fires onComplete
-```
+  - `loop: true` → wraps to clip 0
+  - `loop: false` → fires `onComplete`, stops
 
 ---
 
 ### `goto(index)`
 
-Jump to a specific clip by index and play it immediately.
+Jump to a clip by zero-based index and play it.
 
 ```javascript
-player.goto(0);   // Jump to first clip
-player.goto(2);   // Jump to third clip
+player.goto(0);   // First clip
+player.goto(2);   // Third clip
+player.goto(10);  // ❌ Warning if out of range — no-op
 ```
 
 **Parameters:**
-- **`index`** (number) — 0-based clip index
-
-**Behavior:**
-- Jumps to the specified clip and plays it
-- Validates index (warns if out of range, no-op)
-
-```javascript
-const player = new SequentialAudio([c1, c2, c3, c4]);
-
-player.goto(1);   // ✅ Play clip 2
-player.goto(10);  // ❌ Warning: out of range
-```
+- `index` (number) — 0-based clip index
 
 ---
 
 ### `gotoLabel(label)`
 
-Jump to a clip by its label and play it.
-
-```javascript
-player.gotoLabel('Chapter 5');
-```
-
-**Parameters:**
-- **`label`** (string) — Exact label match
-
-**Behavior:**
-- Searches clips for matching label
-- Jumps to first match
-- Warns if label not found
+Jump to a clip by label (exact string match) and play it.
 
 ```javascript
-const player = new SequentialAudio([
-  { src: 'intro.mp3', label: 'Introduction' },
-  { src: 'ch1.mp3', label: 'Chapter 1' },
-  { src: 'ch2.mp3', label: 'Chapter 2' }
-]);
-
-player.gotoLabel('Chapter 1');   // ✅ Jumps to index 1
-player.gotoLabel('Chapter 99');  // ❌ Warning: not found
+player.gotoLabel('Chapter 1');   // ✅ Jumps to matching clip
+player.gotoLabel('Chapter 99');  // ❌ Warning if not found — no-op
 ```
 
 ---
 
 ### `pause()`
 
-Pause playback without changing the clip or position.
-
-```javascript
-player.pause();
-```
-
-**Behavior:**
-- Pauses audio at current position
-- Sets `isPlaying = false`
-- Call `resume()` to continue from same position
+Pause at current playback position.
 
 ```javascript
-player.play();      // Playing clip 1, 2:30 elapsed
-player.pause();     // Paused at 2:30
-player.resume();    // Resume from 2:30
+player.play();    // Playing at 2:30
+player.pause();   // Paused at 2:30
+player.resume();  // Resumes from 2:30
 ```
 
 ---
 
 ### `resume()`
 
-Resume playback from where it was paused.
-
-```javascript
-player.resume();
-```
-
-**Behavior:**
-- If paused: resumes audio
-- If already playing: no-op (safe)
+Resume from paused position. No-op if not paused.
 
 ```javascript
-player.play();      // Playing
-player.pause();     // Paused
-player.resume();    // Resume from pause point
-player.resume();    // No-op (already playing)
+player.resume();  // Resumes from pause point
+player.resume();  // No-op if already playing
 ```
 
 ---
 
 ### `stop()`
 
-Stop playback and rewind to the beginning of the current clip.
+Pause, rewind current clip to 0:00, and cancel any pending auto-advance timer.
 
 ```javascript
 player.stop();
 ```
 
-**Behavior:**
-- Pauses audio
-- Rewinds to 0:00 of current clip
-- Sets `isPlaying = false`
-- Calling `play()` after will restart from beginning
+From v1.2.0: `stop()` cancels any pending auto-advance `setTimeout`, so calling `stop()` during the inter-clip delay window correctly prevents the next clip from starting.
 
-```javascript
-player.play();      // Playing clip 1, 2:30 elapsed
-player.stop();      // Stopped, rewound to 0:00
-player.play();      // Restart from 0:00
-```
+From v1.3.0: `stop()` also sets a `#playCancelled` flag. If `play()` is called and `stop()` (or `reset()`) is called before the silent-MP3 unlock resolves (~50–200 ms), the clip will not start when the unlock completes. Previously this race was unguarded — the clip would play despite the explicit stop.
 
 ---
 
 ### `reset()`
 
-Reset the sequence to the first clip without playing.
+Stop and reset sequence to clip 0. Clears `isStarted` — next `play()` re-runs the unlock.
 
 ```javascript
-player.reset();
+player.goto(3);   // At clip 4
+player.reset();   // Back to clip 0, stopped
+player.play();    // Starts fresh from clip 0
 ```
 
-**Behavior:**
-- Stops playback
-- Resets to clip index 0
-- Resets `isStarted` flag
-- Calling `play()` will start from beginning
+---
+
+### `destroy()`
+
+Release the Audio element, remove event listeners, and cancel any pending auto-advance timer. All subsequent method calls are safe no-ops.
 
 ```javascript
-player.goto(3);     // At clip 4
-player.reset();     // Back to clip 0, stopped
-player.play();      // Play clip 0
+player.destroy();
+
+// React example
+useEffect(() => {
+  const player = new SequentialAudio(clips);
+  return () => player.destroy();
+}, []);
 ```
 
 ---
 
 ### `getCurrentClip()`
 
-Get the current clip object.
+Get a **copy** of the current clip object. Returns a copy to prevent mutation of the internal playlist.
 
 ```javascript
 const clip = player.getCurrentClip();
 console.log(clip.label, clip.src);
 ```
 
-**Returns:** Current clip object `{ src, label, ... }`
+**Returns:** `{ src: string, label: string }` (copy)
 
 ---
 
@@ -327,60 +224,30 @@ Get the current clip index (0-based).
 
 ```javascript
 const index = player.getCurrentIndex();
-console.log(`Playing clip ${index + 1}`);
+console.log(`Clip ${index + 1} of ${player.getClipCount()}`);
 ```
 
-**Returns:** Number (0 to clipCount - 1)
-
 ---
 
 ### `getClipCount()`
 
-Get total number of clips in the sequence.
+Get total number of clips.
 
 ```javascript
 const total = player.getClipCount();
-console.log(`${total} clips in sequence`);
 ```
 
-**Returns:** Number
-
 ---
 
 ### `getClips()`
 
-Get a copy of all clips.
+Get a **deep copy** of all clip objects. Inner objects are copied to prevent callers from mutating the internal playlist.
 
 ```javascript
 const allClips = player.getClips();
-console.log(`Sequence has ${allClips.length} clips`);
 ```
 
-**Returns:** Array of clip objects (copy, not reference)
-
----
-
-### `destroy()`
-
-Clean up and remove all references. Call on SPA unmount.
-
-```javascript
-player.destroy();
-```
-
-**Behavior:**
-- Stops playback
-- Clears audio element
-- Nullifies internal references
-- After this, don't call any other methods
-
-```javascript
-// React example
-useEffect(() => {
-  const player = new SequentialAudio(clips);
-  return () => player.destroy();
-}, []);
-```
+**Returns:** `Array<{ src: string, label: string }>` (deep copy)
 
 ---
 
@@ -389,23 +256,17 @@ useEffect(() => {
 Check if browser supports an audio format.
 
 ```javascript
-SequentialAudio.canPlay('audio/mpeg') → boolean
+SequentialAudio.canPlay('audio/mpeg')  // → boolean
+SequentialAudio.canPlay('audio/ogg')   // → boolean
+SequentialAudio.canPlay('audio/wav')   // → boolean
+SequentialAudio.canPlay('audio/webm')  // → boolean
 ```
 
-**Parameters:**
-- **`type`** (string) — MIME type to check
-  - `'audio/mpeg'` — MP3
-  - `'audio/ogg'` — OGG Vorbis
-  - `'audio/wav'` — WAV
-  - `'audio/webm'` — WebM
-
-**Returns:** `true` if supported, `false` otherwise
+**Returns:** `true` if supported, `false` if unsupported or input is not a string.
 
 ```javascript
-if (SequentialAudio.canPlay('audio/ogg')) {
-  // Use OGG files
-} else {
-  // Fall back to MP3
+if (!SequentialAudio.canPlay('audio/ogg')) {
+  console.warn('OGG not supported — use MP3 sources instead');
 }
 ```
 
@@ -415,17 +276,13 @@ if (SequentialAudio.canPlay('audio/ogg')) {
 
 ### `isPlaying`
 
-**Type:** `boolean` (read-only)
+**Type:** `boolean` (read-only getter)
 
-`true` if a clip is actively playing, `false` if paused or stopped.
+`true` if a clip is actively playing, `false` if paused, stopped, or between clips.
 
 ```javascript
-player.play();
-
 if (player.isPlaying) {
-  console.log('Clip is playing');
-} else {
-  console.log('Clip is paused or stopped');
+  player.pause();
 }
 ```
 
@@ -433,18 +290,16 @@ if (player.isPlaying) {
 
 ### `isStarted`
 
-**Type:** `boolean` (read-only)
+**Type:** `boolean` (read-only getter)
 
-`true` after first `play()` call (sequence has been unlocked and started).
+`true` after `play()` has been called and the sequence has been unlocked. `false` before first `play()` or after `reset()`.
 
 ```javascript
-const player = new SequentialAudio(clips);
-
 console.log(player.isStarted); // false
-
 player.play();
-
 console.log(player.isStarted); // true
+player.reset();
+console.log(player.isStarted); // false
 ```
 
 ---
@@ -458,76 +313,52 @@ Called when a clip **starts playing**.
 ```javascript
 const player = new SequentialAudio(clips, {
   onPlay: (clip) => {
-    console.log(`Now playing: ${clip.label}`);
     updateProgressBar(clip.label);
   }
 });
 ```
 
-**Parameter:**
-- **`clip`** — The clip object being played `{ src, label }`
+**Parameter:** `clip` — a copy of the clip object `{ src, label }`.
 
-**Thrown errors are caught:** If your callback throws, the error is logged but playback continues.
-
-```javascript
-const player = new SequentialAudio(clips, {
-  onPlay: (clip) => {
-    throw new Error('Oops!');
-    // Error logged, playback unaffected
-  }
-});
-```
+**Error handling:** Errors are caught and logged. A throwing callback will not stall playback.
 
 ---
 
 ### `onEnd(clip)`
 
-Called when a clip **finishes playing** (reaches natural end).
-
-Does NOT fire if you call `stop()` or `pause()` before the clip ends.
+Called when a clip **finishes naturally**. Does not fire if `stop()` or `pause()` interrupts the clip.
 
 ```javascript
 const player = new SequentialAudio(clips, {
   onEnd: (clip) => {
     console.log(`Finished: ${clip.label}`);
-    // Auto-advance is handled separately
   }
 });
 ```
 
-**Parameter:**
-- **`clip`** — The clip object that ended
-
 **After `onEnd`:**
-- If `autoAdvance: true` → Next clip starts automatically (after 500ms delay)
-- If `autoAdvance: false` → Sequence pauses, waiting for `next()` call
+- `autoAdvance: true` → next clip starts after `advanceDelay` seconds
+- `autoAdvance: false` → sequence waits for `next()` call
 
 ---
 
 ### `onComplete()`
 
-Called when the entire sequence finishes (no more clips).
-
-Only fires if `autoAdvance: true` OR user explicitly calls `next()` on the last clip.
+Called when the entire sequence finishes (no more clips and `loop: false`).
 
 ```javascript
 const player = new SequentialAudio(clips, {
   onComplete: () => {
-    console.log('Sequence complete!');
     showCongratulationsScreen();
   }
 });
 ```
 
-**After `onComplete`:**
-- If `loop: true` → Sequence wraps to beginning, ready for replay
-- If `loop: false` → Sequence stops
-
 ---
 
 ## Usage Patterns
 
-### Pattern 1: Narrated Story (Manual Advance)
+### Narrated Story (Manual Advance)
 
 ```javascript
 const story = new SequentialAudio([
@@ -535,9 +366,9 @@ const story = new SequentialAudio([
   { src: 'chapter2.mp3', label: 'Chapter 2' },
   { src: 'chapter3.mp3', label: 'Chapter 3' }
 ], {
-  autoAdvance: false,  // User controls pacing
-  onPlay: (clip) => updateUI(`Reading: ${clip.label}`),
-  onComplete: () => showTheEnd()
+  autoAdvance: false,
+  onPlay:      (clip) => updateUI(`Reading: ${clip.label}`),
+  onComplete:  ()     => showTheEnd()
 });
 
 document.addEventListener('click', () => story.play(), { once: true });
@@ -549,106 +380,64 @@ document.getElementById('prev-btn').addEventListener('click', () => {
 
 ---
 
-### Pattern 2: Tutorial with Auto-Advance
+### Tutorial with Auto-Advance
 
 ```javascript
 const tutorial = new SequentialAudio([
-  { src: 'intro.mp3', label: 'Introduction' },
-  { src: 'step1.mp3', label: 'Step 1' },
-  { src: 'step2.mp3', label: 'Step 2' },
-  { src: 'conclusion.mp3', label: 'Conclusion' }
+  { src: 'intro.mp3',       label: 'Introduction' },
+  { src: 'step1.mp3',       label: 'Step 1' },
+  { src: 'step2.mp3',       label: 'Step 2' },
+  { src: 'conclusion.mp3',  label: 'Conclusion' }
 ], {
-  autoAdvance: true,  // Auto-play next step
-  onPlay: (clip) => highlightStep(clip.label),
-  onComplete: () => showCompletionCertificate()
+  autoAdvance:  true,
+  advanceDelay: 0.5,
+  onPlay:       (clip) => highlightStep(clip.label),
+  onComplete:   ()     => showCompletionCertificate()
 });
 
-document.getElementById('start-tutorial').addEventListener('click', () => {
-  tutorial.play();
-});
+document.getElementById('start-tutorial').addEventListener('click', () => tutorial.play());
 ```
 
 ---
 
-### Pattern 3: Interactive Quiz with Narration
+### Interactive Quiz
 
 ```javascript
 const quiz = new SequentialAudio([
   { src: 'question1.mp3', label: 'Question 1' },
   { src: 'question2.mp3', label: 'Question 2' },
-  { src: 'question3.mp3', label: 'Question 3' },
-  { src: 'results.mp3', label: 'Results' }
+  { src: 'results.mp3',   label: 'Results' }
 ], {
   autoAdvance: false,
-  onPlay: (clip) => {
-    // Show question UI
-    showQuestion(clip.label);
-  },
-  onComplete: () => {
-    // Show final score
-    showResults();
-  }
+  onPlay:      (clip) => showQuestion(clip.label),
+  onComplete:  ()     => showResults()
 });
 
-// User answers question, then advances
 function submitAnswer(answer) {
   recordAnswer(answer);
-  quiz.next();  // Move to next question
+  quiz.next();
 }
 ```
 
 ---
 
-### Pattern 4: Looping Background Narration
-
-```javascript
-const loopingNarration = new SequentialAudio([
-  { src: 'intro.mp3', label: 'Intro' },
-  { src: 'main.mp3', label: 'Main Message' },
-  { src: 'outro.mp3', label: 'Outro' }
-], {
-  autoAdvance: true,
-  loop: true,  // Restart after outro
-  onPlay: (clip) => console.log(`[${clip.label}]`)
-});
-
-document.addEventListener('click', () => loopingNarration.play(), { once: true });
-```
-
----
-
-### Pattern 5: Guided Tour with Skip/Rewind
+### Guided Tour with Skip/Rewind
 
 ```javascript
 const tour = new SequentialAudio([
-  { src: 'welcome.mp3', label: 'Welcome' },
+  { src: 'welcome.mp3',  label: 'Welcome' },
   { src: 'feature1.mp3', label: 'Feature 1: Dashboard' },
   { src: 'feature2.mp3', label: 'Feature 2: Settings' },
-  { src: 'feature3.mp3', label: 'Feature 3: Profile' },
-  { src: 'thanks.mp3', label: 'Thanks' }
+  { src: 'thanks.mp3',   label: 'Thanks' }
 ], {
-  onPlay: (clip) => highlightFeature(clip.label),
-  onComplete: () => completeTour()
-});
-
-// Play from start
-document.getElementById('start-tour').addEventListener('click', () => tour.play());
-
-// Jump to specific section
-document.getElementById('skip-to-settings').addEventListener('click', () => {
-  tour.gotoLabel('Feature 2: Settings');
-});
-
-// Rewind one step
-document.getElementById('previous').addEventListener('click', () => {
-  const idx = Math.max(0, tour.getCurrentIndex() - 1);
-  tour.goto(idx);
+  onPlay:     (clip) => highlightFeature(clip.label),
+  onComplete: ()     => completeTour()
 });
 
-// Forward one step
-document.getElementById('next').addEventListener('click', () => {
-  tour.next();
-});
+document.getElementById('start-tour').addEventListener('click',        () => tour.play());
+document.getElementById('skip-to-settings').addEventListener('click', () => tour.gotoLabel('Feature 2: Settings'));
+document.getElementById('previous').addEventListener('click',          () => tour.goto(Math.max(0, tour.getCurrentIndex() - 1)));
+document.getElementById('next').addEventListener('click',              () => tour.next());
 ```
 
 ---
@@ -657,9 +446,6 @@ document.getElementById('next').addEventListener('click', () => {
 
 ### Audio Won't Play on First Click
 
-**Problem:** Calling `play()` outside a user gesture.
-
-**Solution:**
 ```javascript
 // ✅ Correct
 document.addEventListener('click', () => player.play());
@@ -668,32 +454,17 @@ document.addEventListener('click', () => player.play());
 setTimeout(() => player.play(), 1000);
 ```
 
----
-
-### Can't Advance to Next Clip
-
-**Problem:** Calling `next()` but nothing happens.
+### Stop Doesn't Prevent Auto-Advance (v1.1.0 and earlier)
 
-**Cause:** Already at last clip and `loop: false`.
+This was fixed in v1.2.0. `stop()` now calls `clearTimeout` on the pending advance timer. Upgrade to v1.2.0 to resolve.
 
-**Solution:**
-```javascript
-if (player.getCurrentIndex() < player.getClipCount() - 1) {
-  player.next();
-} else if (loop) {
-  // Already handled by library
-  player.next();
-}
-```
+### Stop During Unlock Still Plays Clip (v1.2.0 and earlier)
 
----
+This was fixed in v1.3.0. `stop()` and `reset()` now set a `#playCancelled` flag that the unlock `.then()` checks before starting playback. Previously, calling `stop()` or `reset()` in the ~50–200 ms window between `play()` being called and the silent-MP3 unlock resolving was silently ignored — the clip would start anyway. Upgrade to v1.3.0 to resolve.
 
 ### Progress Bar Shows Wrong Index
 
-**Problem:** UI shows wrong clip number.
-
-**Solution:** `getCurrentIndex()` is 0-based, so display `index + 1`:
-
+`getCurrentIndex()` is 0-based:
 ```javascript
 const index = player.getCurrentIndex();
 console.log(`Clip ${index + 1} of ${player.getClipCount()}`);
@@ -701,34 +472,15 @@ console.log(`Clip ${index + 1} of ${player.getClipCount()}`);
 
 ---
 
-### onComplete Fires Too Early
-
-**Problem:** Callback fires before last clip actually ends.
-
-**Cause:** `autoAdvance: true` fires `next()` → triggers `onComplete` before last clip fully plays.
-
-**Solution:** Use manual advance or check if you really want `onComplete` at this time:
-
-```javascript
-const player = new SequentialAudio(clips, {
-  autoAdvance: false,  // User controls advancement
-  onComplete: () => {
-    // Now fires only when user explicitly ends sequence
-  }
-});
-```
-
----
-
 ## Browser Compatibility
 
 | Browser | Support | Notes |
 |---------|---------|-------|
-| Chrome 70+ | ✅ Full | Autoplay policy: gesture required first time |
+| Chrome 70+ | ✅ Full | Gesture required first time |
 | Firefox 65+ | ✅ Full | Same as Chrome |
-| Safari 12+ | ✅ Full | iOS: gesture required; Desktop: autoplay OK |
+| Safari 12+ | ✅ Full | iOS: gesture required |
 | Edge 79+ | ✅ Full | Same as Chrome |
-| iOS Safari 12+ | ✅ Full | Gesture required; extensively tested |
+| iOS Safari 12+ | ✅ Full | Extensively tested |
 | Chrome Android | ✅ Full | Gesture required |
 
 ---
@@ -738,13 +490,46 @@ const player = new SequentialAudio(clips, {
 - **File Size:** ~5 KB (minified)
 - **Gzipped:** ~2 KB
 - **Runtime Memory:** < 150 KB per player
-- **CPU:** Negligible — HTML5 Audio element management only
+- **CPU:** Negligible
+
+---
+
+## Changelog
+
+### v1.3.0 (March 2026)
+- **`#playCancelled` flag** — `stop()` and `reset()` now plant a cancellation token that the in-flight silent-MP3 unlock `.then()` checks before calling `#playClip()`. Previously, calling `stop()` or `reset()` during the ~50–200 ms unlock window was silently ignored — the clip would start regardless.
+- **`stop()` doc updated** — Behaviour note now covers both the auto-advance timer cancellation (v1.2.0) and the new unlock cancellation (v1.3.0).
+- **Usage example fix** — `goto(getCurrentIndex() - 1)` in the guided-tour example now uses `Math.max(0, …)`, preventing a spurious out-of-range `console.warn` when the user is already on the first clip.
+
+### v1.2.0 (March 2026)
+- `isPlaying` and `isStarted` are now read-only getters backed by private fields
+- `#isPlaying` and `#isStarted` set synchronously before `#audio.play()` in `#playClip()`, closing double-play race window
+- `#advanceTimer` stored and cleared by `stop()`, `reset()`, and `destroy()`
+- `resume()` race fixed — `#isPlaying` set synchronously, reverted in `.catch()`
+- `destroy()` uses `removeAttribute('src')` + `load()` per WHATWG spec
+- `getCurrentClip()` returns shallow copy; `getClips()` deep-copies inner objects
+
+### v1.1.0 (March 2026)
+- Unlock now plays on the shared `#audio` element (fixes `NotAllowedError` on iOS Safari)
+- `play()` guard extended to check `isStarted`
+- `next()` / `goto()` / `gotoLabel()` guard against uninitialised player
+- `pause()` / `resume()` guard on `isStarted`
+- `destroy()` removes `ended` listener via stored `#endedHandler` reference
+- `#isDestroyed` flag — all public methods safe no-ops after `destroy()`
+- `advanceDelay` option added (default `0.5s`)
+
+### v1.0.0 (March 2026)
+- Initial release: sequential playlist player
+- Click-to-advance playback control
+- Jump to clip by index (`goto()`) or label (`gotoLabel()`)
+- Pause/resume support
+- Progress tracking (`getCurrentClip()`, `getCurrentIndex()`, `getClipCount()`)
 
 ---
 
 ## License
 
-GNU General Public License v3.0 or later. See [LICENSE](../LICENSE).
+Apache License 2.0. See [LICENSE](../LICENSE).
 
 ---
 
@@ -757,4 +542,4 @@ GNU General Public License v3.0 or later. See [LICENSE](../LICENSE).
 
 ---
 
-*Last updated: March 2025*
+*Last updated: March 2026*