@arraypress/waveform-sounds 2.0.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/README.md +24 -2
  2. package/dist/waveform-sounds-no-autoinit.esm.js +495 -90
  3. package/dist/waveform-sounds-render.esm.js +55 -5
  4. package/dist/waveform-sounds.css +88 -17
  5. package/dist/waveform-sounds.esm.js +498 -92
  6. package/dist/waveform-sounds.js +494 -92
  7. package/dist/waveform-sounds.min.css +1 -1
  8. package/dist/waveform-sounds.min.js +3 -3
  9. package/package.json +1 -1
  10. package/src/css/waveform-sounds.css +88 -17
  11. package/src/js/core/WaveformSounds.ts +350 -87
  12. package/src/js/core/element.ts +208 -0
  13. package/src/js/core/engine.ts +9 -3
  14. package/src/js/core/options.ts +0 -5
  15. package/src/js/data/bpm.ts +14 -4
  16. package/src/js/data/navigation.ts +16 -3
  17. package/src/js/data/sounds.ts +44 -14
  18. package/src/js/data/url-state.ts +33 -10
  19. package/src/js/dom/colors.ts +28 -1
  20. package/src/js/dom/draw.ts +0 -1
  21. package/src/js/dom/menus.ts +0 -2
  22. package/src/js/dom/rows.ts +0 -3
  23. package/src/js/entry.ts +13 -3
  24. package/src/js/index.ts +7 -3
  25. package/src/js/render/html.ts +0 -2
  26. package/src/js/render/icons.ts +0 -1
  27. package/src/js/render/markup.ts +41 -13
  28. package/src/js/render/options.ts +26 -4
  29. package/src/js/render/strings.ts +4 -3
  30. package/src/js/render-entry.ts +1 -1
  31. package/src/js/shared/utils.ts +4 -4
  32. package/src/js/types.ts +30 -3
  33. package/types/core/WaveformSounds.d.ts +40 -10
  34. package/types/core/WaveformSounds.d.ts.map +1 -1
  35. package/types/core/element.d.ts +84 -0
  36. package/types/core/element.d.ts.map +1 -0
  37. package/types/core/engine.d.ts +8 -3
  38. package/types/core/engine.d.ts.map +1 -1
  39. package/types/core/options.d.ts +0 -5
  40. package/types/core/options.d.ts.map +1 -1
  41. package/types/data/bpm.d.ts +17 -4
  42. package/types/data/bpm.d.ts.map +1 -1
  43. package/types/data/navigation.d.ts +11 -2
  44. package/types/data/navigation.d.ts.map +1 -1
  45. package/types/data/sounds.d.ts +13 -12
  46. package/types/data/sounds.d.ts.map +1 -1
  47. package/types/data/url-state.d.ts +32 -6
  48. package/types/data/url-state.d.ts.map +1 -1
  49. package/types/dom/colors.d.ts +13 -0
  50. package/types/dom/colors.d.ts.map +1 -1
  51. package/types/dom/draw.d.ts +0 -1
  52. package/types/dom/draw.d.ts.map +1 -1
  53. package/types/dom/menus.d.ts +0 -2
  54. package/types/dom/menus.d.ts.map +1 -1
  55. package/types/dom/rows.d.ts +0 -3
  56. package/types/dom/rows.d.ts.map +1 -1
  57. package/types/entry.d.ts +10 -4
  58. package/types/entry.d.ts.map +1 -1
  59. package/types/index.d.ts +2 -2
  60. package/types/index.d.ts.map +1 -1
  61. package/types/render/html.d.ts +0 -2
  62. package/types/render/html.d.ts.map +1 -1
  63. package/types/render/icons.d.ts.map +1 -1
  64. package/types/render/markup.d.ts +17 -8
  65. package/types/render/markup.d.ts.map +1 -1
  66. package/types/render/options.d.ts +17 -4
  67. package/types/render/options.d.ts.map +1 -1
  68. package/types/render/strings.d.ts +0 -3
  69. package/types/render/strings.d.ts.map +1 -1
  70. package/types/render-entry.d.ts +1 -1
  71. package/types/render-entry.d.ts.map +1 -1
  72. package/types/shared/utils.d.ts +3 -3
  73. package/types/shared/utils.d.ts.map +1 -1
  74. package/types/types.d.ts +29 -3
  75. package/types/types.d.ts.map +1 -1
@@ -26,24 +26,26 @@
26
26
  * @module core
27
27
  */
28
28
 
29
- import {availableSorts, facets, matches, normalizeSounds, parseManifest, sortSounds, SORTS} from '../data/sounds.js';
29
+ import {availableSorts, facets, formatClock, formatDuration, matches, normalizeSounds, parseManifest, sortSounds, SORTS} from '../data/sounds.js';
30
30
  import {drawRowWaveform, resample} from '../dom/draw.js';
31
31
  import {engineOptions, engineTrack} from './engine.js';
32
32
  import {Menus} from '../dom/menus.js';
33
- import {limitToReveal, pageWindow, rowTarget, seekTarget} from '../data/navigation.js';
33
+ import {limitToReveal, pageWindow, rowTarget, seekTarget, sliderEdgeTarget} from '../data/navigation.js';
34
34
  import {DEFAULT_OPTIONS, mergeOptions, readDataOptions} from './options.js';
35
35
  import {resolveRenderOptions} from '../render/options.js';
36
36
  import {loopsByDefault, renderSounds} from '../render/markup.js';
37
37
  import {indexRows, orderRows, readRows, visibleRows} from '../dom/rows.js';
38
38
  import {bpmLabel, countText, DEFAULT_STRINGS, fill} from '../render/strings.js';
39
- import {bpmFilterFromRange, bpmFraction, bpmRangeFromFilter} from '../data/bpm.js';
40
- import {pageSurface, resolveCssColor} from '../dom/colors.js';
39
+ import {bpmExtent, bpmFilterFromRange, bpmFraction, bpmRangeFromFilter} from '../data/bpm.js';
40
+ import {ancestorsOf, forcedColors, pageSurface, resolveCssColor} from '../dom/colors.js';
41
41
  import {readUrlState, urlKeys, writeUrlState} from '../data/url-state.js';
42
42
  import {emit, isTyping, LOG, pointerFraction} from '../shared/utils.js';
43
- import type {decodePeaks, encodePeaks, formatDuration, normalizeKey} from '../data/sounds.js';
43
+ import {h, text} from '../render/html.js';
44
+ import type {decodePeaks, encodePeaks, normalizeKey} from '../data/sounds.js';
44
45
  import type {EngineTrack} from './engine.js';
46
+ import type {WaveformPlayer} from '@arraypress/waveform-player';
45
47
  import type {RenderOptions} from '../render/options.js';
46
- import type {Sound, SoundInput, SoundsFilter, SoundsLoopFilter, SoundsSort, WaveformSoundsOptions, WaveformSoundsStrings} from '../types.js';
48
+ import type {Sound, SoundInput, SoundsFilter, SoundsLoopFilter, SoundsSort, WaveformSoundsInstanceEventMap, WaveformSoundsOptions, WaveformSoundsStrings} from '../types.js';
47
49
 
48
50
  /** The engine `WaveformPlayer`, as far as the list uses it. */
49
51
  interface Engine {
@@ -95,7 +97,26 @@ const BPM_DELAY = 200;
95
97
  /** Debounce before the address is rewritten after a change (ms). */
96
98
  const URL_DELAY = 250;
97
99
 
98
- export class WaveformSounds {
100
+ /**
101
+ * Typed listeners for the events a list dispatches on itself (see
102
+ * {@link WaveformSoundsInstanceEventMap}). Types only: merged into the class
103
+ * below, it emits nothing.
104
+ */
105
+ export interface WaveformSounds {
106
+ addEventListener<K extends keyof WaveformSoundsInstanceEventMap>(type: K, listener: (this: WaveformSounds, ev: WaveformSoundsInstanceEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
107
+ addEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | AddEventListenerOptions): void;
108
+ removeEventListener<K extends keyof WaveformSoundsInstanceEventMap>(type: K, listener: (this: WaveformSounds, ev: WaveformSoundsInstanceEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
109
+ removeEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | EventListenerOptions): void;
110
+ }
111
+
112
+ /**
113
+ * An `EventTarget`, like the core's player: each moment is dispatched on the
114
+ * instance as a plain event (`ready`, `play`, `pause`, `end`, `filter`,
115
+ * `error`), and on the container as a bubbling, composed
116
+ * `waveformsounds:<name>` CustomEvent carrying the details.
117
+ */
118
+ // biome-ignore lint/suspicious/noUnsafeDeclarationMerging: see the interface above
119
+ export class WaveformSounds extends EventTarget {
99
120
  /** Every live instance, by its element. */
100
121
  static instances: Map<Element, WaveformSounds> = new Map();
101
122
  /** The pure helpers, for `<script>` users (attached in `entry.ts`). */
@@ -111,6 +132,11 @@ export class WaveformSounds {
111
132
  formatDuration: typeof formatDuration;
112
133
  renderSounds: typeof renderSounds;
113
134
  };
135
+ /** Register the `<waveform-sounds>` element (default tag name
136
+ * `waveform-sounds`). The default entry does this on import; this
137
+ * reaches it from a `<script>` page that opted out of auto-init.
138
+ * Attached in `entry.ts`. Since 2.1.0. */
139
+ declare static defineElement: (name?: string) => CustomElementConstructor | undefined;
114
140
  /** Every option with its default (attached in `entry.ts`). */
115
141
  declare static DEFAULT_OPTIONS: WaveformSoundsOptions;
116
142
  /** The English UI strings (attached in `entry.ts`). */
@@ -130,8 +156,9 @@ export class WaveformSounds {
130
156
  declare readonly filter: SoundsFilter;
131
157
  declare readonly sortBy: SoundsSort;
132
158
  declare readonly playing: boolean;
133
- /** The engine `WaveformPlayer`, created on first play. */
134
- declare readonly engine: unknown;
159
+ /** The engine `WaveformPlayer`: built when the list is ready if the
160
+ * player is on the page (else on first play), null before and after. */
161
+ declare readonly engine: WaveformPlayer | null;
135
162
 
136
163
  /** @internal */ declare strings: WaveformSoundsStrings;
137
164
  /** @internal */ declare render: RenderOptions;
@@ -147,6 +174,7 @@ export class WaveformSounds {
147
174
  /** @internal */ declare colors: {wave: string, progress: string} | undefined;
148
175
  /** @internal */ declare _ctl: AbortController;
149
176
  /** @internal */ declare _originalHTML: string | null;
177
+ /** @internal Adopted server markup as it arrived (destroy({restore})). */ declare _adoptedHTML: string | undefined;
150
178
  /** @internal */ declare _pendingSeek: number | null;
151
179
  /** @internal */ declare _raf: number;
152
180
  /** @internal */ declare _addedClasses: string[] | undefined;
@@ -156,24 +184,33 @@ export class WaveformSounds {
156
184
  /** @internal */ declare _sorts: string[];
157
185
  /** @internal */ declare _lastSort: string | undefined;
158
186
  /** @internal */ declare _lastPointer: string | undefined;
159
- /** @internal */ declare _drawn: Set<number> | undefined;
187
+ /** @internal Rows drawn at least once. */ declare _drawn: Set<number> | undefined;
188
+ /** @internal Drawn rows whose picture is stale (redrawn when they show). */ declare _dirty: Set<number> | undefined;
189
+ /** @internal Rows near the viewport (undefined without IntersectionObserver). */ declare _onScreen: Set<number> | undefined;
160
190
  /** @internal */ declare _io: IntersectionObserver | undefined;
161
191
  /** @internal */ declare _ro: ResizeObserver | undefined;
162
192
  /** @internal */ declare _mo: MutationObserver | undefined;
163
193
  /** @internal */ declare _autoSurface: boolean | undefined;
164
194
  /** @internal */ declare _urlTimer: number | undefined;
165
195
  /** @internal */ declare _cued: boolean | undefined;
196
+ /** @internal The sounds the last layout shows, in order (see `visible`). */ declare _shown: Sound[] | undefined;
197
+ /** @internal The engine's own `preload` (a cue uses 'none'). */ declare _preload: string | undefined;
198
+ /** @internal The row holding the list's one Tab stop. */ declare _active: HTMLElement | null;
199
+ /** @internal The sound last reported as playing (its pause not yet reported). */ declare _announced: number | null | undefined;
166
200
 
167
201
  /**
168
202
  * @param {HTMLElement|string} container - The element (or a selector).
169
203
  * @param {WaveformSoundsOptions} [options]
170
204
  */
171
205
  constructor(container: HTMLElement | string, options: WaveformSoundsOptions = {}) {
206
+ super();
172
207
  const el = typeof container === 'string' ? document.querySelector<HTMLElement>(container) : container;
173
208
  if (!el) throw new Error(`${LOG} Container not found: ${container}`);
174
209
  this.container = el;
175
210
  // Precedence, as across the family: data-* > constructor > default.
176
- this.options = mergeOptions(DEFAULT_OPTIONS, options, readDataOptions(el)) as Required<WaveformSoundsOptions>;
211
+ // A <waveform-sounds> element reads its plain attributes too.
212
+ const data = (el as {_wsOptions?: () => Record<string, any>})._wsOptions?.() ?? readDataOptions(el);
213
+ this.options = mergeOptions(DEFAULT_OPTIONS, options, data) as Required<WaveformSoundsOptions>;
177
214
  this.options.waveformStyle = this.options.waveformStyle === 'bars' ? 'bars' : 'mirror';
178
215
  this.strings = {...DEFAULT_STRINGS, ...(this.options.strings || {})};
179
216
  this.render = {...resolveRenderOptions(this.options), strings: this.strings};
@@ -204,7 +241,9 @@ export class WaveformSounds {
204
241
  // through onError / `waveformsounds:error`.
205
242
  /** Resolves once the list is built (after a manifest fetch, if any). */
206
243
  this.ready = Promise.resolve().then(() => this._init()).catch((err) => {
244
+ if (this.destroyed) return; // e.g. the manifest fetch, aborted by destroy()
207
245
  console.error(`${LOG} Failed to initialise:`, err);
246
+ this._showLoadError();
208
247
  this._emit('error', {error: err});
209
248
  this.options.onError?.(err, this);
210
249
  });
@@ -221,6 +260,8 @@ export class WaveformSounds {
221
260
  const el = this.container;
222
261
  const adopted = el.querySelector<HTMLElement>('[data-ws-list]');
223
262
  if (adopted) {
263
+ // As the server sent it, for destroy({restore: true}).
264
+ this._adoptedHTML = el.innerHTML;
224
265
  (this as Writable<WaveformSounds>).sounds = readRows(adopted);
225
266
  } else {
226
267
  this._originalHTML = el.innerHTML;
@@ -243,7 +284,7 @@ export class WaveformSounds {
243
284
  // when the list marks loops — only those repeat.
244
285
  if (!this._loopSet) this.loop = loopsByDefault(this.options.loop, facets(this.sounds));
245
286
  this._setLoop(this.loop);
246
- this._bpmExtent = facets(this.sounds).bpm;
287
+ this._bpmExtent = bpmExtent(facets(this.sounds).bpm);
247
288
 
248
289
  // The starting order is the first one offered, unless setSort()
249
290
  // already chose one; then the address may override both.
@@ -270,14 +311,31 @@ export class WaveformSounds {
270
311
 
271
312
  /**
272
313
  * The sounds from the `sounds` option, else the `manifest` URL.
273
- * @returns
274
314
  * @internal
275
315
  */
276
316
  async _loadSounds(): Promise<Sound[]> {
277
317
  if (this.options.sounds || !this.options.manifest) return normalizeSounds(this.options.sounds || []);
278
- const res = await fetch(this.options.manifest);
279
- if (!res.ok) throw new Error(`${LOG} Manifest ${this.options.manifest}: HTTP ${res.status}`);
280
- return parseManifest(await res.json());
318
+ const url = this.options.manifest;
319
+ // destroy() aborts it: a list torn down mid-fetch never builds.
320
+ const res = await fetch(url, {signal: this._ctl.signal});
321
+ if (!res.ok) throw new Error(`${LOG} Manifest ${url}: HTTP ${res.status}`);
322
+ const manifest = await res.json();
323
+ // Not a list of sounds at all is a broken manifest, not an empty pack.
324
+ if (!Array.isArray(manifest) && !Array.isArray(manifest?.sounds)) throw new Error(`${LOG} Manifest ${url}: no "sounds" list`);
325
+ return parseManifest(manifest);
326
+ }
327
+
328
+ /**
329
+ * A build that failed (the manifest 404s, isn't JSON, isn't a manifest)
330
+ * says so where the list would be — unless the container holds the
331
+ * site's own fallback, which stays. destroy() restores what was there.
332
+ * @internal
333
+ */
334
+ _showLoadError(): void {
335
+ const el = this.container;
336
+ if (this.$ || el.querySelector('*')) return;
337
+ this._originalHTML ??= el.innerHTML;
338
+ el.innerHTML = h('p', {class: 'ws-empty ws-load-error', role: 'alert', 'data-ws-load-error': true}, text(this.strings.loadError));
281
339
  }
282
340
 
283
341
  /**
@@ -305,6 +363,36 @@ export class WaveformSounds {
305
363
  loopFilter: [...this.container.querySelectorAll<HTMLElement>('[data-ws-loop-filter]')],
306
364
  };
307
365
  this.rows = indexRows(this.$.list);
366
+ // Roving tabindex: the list is ONE Tab stop (the active row's
367
+ // controls); ↑/↓ move between rows. Set here, not in the markup, so
368
+ // server-rendered HTML from any version gets it.
369
+ this._active = null;
370
+ for (const row of this.rows) if (row) this._rowStops(row, false);
371
+ }
372
+
373
+ /**
374
+ * Make a row's own controls (play, download, and the seek slider when it
375
+ * is the current sound) Tab stops, or not.
376
+ * @internal
377
+ */
378
+ _rowStops(row: HTMLElement, on: boolean): void {
379
+ const play = row.querySelector<HTMLElement>('.ws-play');
380
+ if (play) play.tabIndex = on ? 0 : -1;
381
+ const dl = row.querySelector<HTMLElement>('.ws-download');
382
+ if (dl) dl.tabIndex = on ? 0 : -1;
383
+ const wave = row.querySelector<HTMLElement>('.ws-wave');
384
+ if (wave) wave.tabIndex = on && Number(row.dataset.wsIndex) === this.currentIndex ? 0 : -1;
385
+ }
386
+
387
+ /**
388
+ * Move the list's Tab stop to `row` (roving tabindex).
389
+ * @internal
390
+ */
391
+ _rove(row: HTMLElement | null | undefined): void {
392
+ if (!row || row === this._active) return;
393
+ if (this._active) this._rowStops(this._active, false);
394
+ this._active = row;
395
+ this._rowStops(row, true);
308
396
  }
309
397
 
310
398
  /**
@@ -320,6 +408,8 @@ export class WaveformSounds {
320
408
  root.addEventListener('click', (e) => this._onClick(e), sig);
321
409
  root.addEventListener('pointerdown', (e) => this._onPointerDown(e), sig);
322
410
  root.addEventListener('keydown', (e) => this._onKey(e), sig);
411
+ // Whatever row gets focus (arrows, a click, a script) holds the Tab stop.
412
+ $.list.addEventListener('focusin', (e) => this._rove((e.target as Element).closest<HTMLElement>('[data-ws-index]')), sig);
323
413
 
324
414
  let searchTimer = 0, bpmTimer = 0;
325
415
  $.search?.addEventListener('input', () => {
@@ -375,8 +465,15 @@ export class WaveformSounds {
375
465
  if (chip) { this.setFilter({type: chip.dataset.wsType}); return; }
376
466
  const seg = t.closest<HTMLElement>('[data-ws-loop-filter]');
377
467
  if (seg) { this.setFilter({loop: seg.dataset.wsLoopFilter as SoundsLoopFilter}); return; }
378
- if (t.closest('[data-ws-more]')) { this.showMore(); return; }
379
- if (t.closest('[data-ws-clear]')) { this.clearFilters(); return; }
468
+ if (t.closest('[data-ws-more]')) { this._showMoreFromButton(); return; }
469
+ if (t.closest('[data-ws-clear]')) {
470
+ // The button disappears with the empty state: focus goes back
471
+ // to the search (else the first row), never to <body>.
472
+ this.clearFilters();
473
+ if (this.$.search) this.$.search.focus();
474
+ else this._focusRow(visibleRows(this.$.list)[0]);
475
+ return;
476
+ }
380
477
  if (t.closest('[data-ws-loop]')) { this.setLoop(!this.loop); return; }
381
478
  const wave = t.closest<HTMLElement>('.ws-wave');
382
479
  if (wave) {
@@ -391,6 +488,18 @@ export class WaveformSounds {
391
488
  this._focusRowQuietly(row);
392
489
  }
393
490
 
491
+ /**
492
+ * "Show more", pressed: reveal the next page. When that was the last page
493
+ * the button hides, so focus moves to the first row it revealed rather
494
+ * than falling to <body>.
495
+ * @internal
496
+ */
497
+ _showMoreFromButton(): void {
498
+ const before = new Set(visibleRows(this.$.list));
499
+ this.showMore();
500
+ if (this.$.more?.hidden) this._focusRow(visibleRows(this.$.list).find((r) => !before.has(r)));
501
+ }
502
+
394
503
  /**
395
504
  * Mouse and pen seek on PRESS, like every scrubber. Remembers the
396
505
  * pointer type for the click that follows.
@@ -416,7 +525,8 @@ export class WaveformSounds {
416
525
 
417
526
  /**
418
527
  * Keys on the list: `/` focuses search; ↑/↓/Home/End move between rows
419
- * (auditioning while something plays); ←/→ seek the playing row.
528
+ * (auditioning while something plays); ←/→ seek the playing row, and on
529
+ * its seek slider Home/End seek to the start/end.
420
530
  * @internal
421
531
  */
422
532
  _onKey(e: KeyboardEvent): void {
@@ -430,7 +540,10 @@ export class WaveformSounds {
430
540
  if (!row) return;
431
541
 
432
542
  const index = Number(row.dataset.wsIndex);
433
- const seek = seekTarget(this.progress, e.key);
543
+ // On the seek slider, Home / End seek (the slider pattern) rather
544
+ // than jump to the first / last row.
545
+ const edge = (e.target as Element).closest('.ws-wave') ? sliderEdgeTarget(e.key) : null;
546
+ const seek = edge ?? seekTarget(this.progress, e.key);
434
547
  if (seek !== null) {
435
548
  if (index !== this.currentIndex || !this.engine) return;
436
549
  e.preventDefault();
@@ -478,11 +591,19 @@ export class WaveformSounds {
478
591
  _observe(): void {
479
592
  if (this.render.player !== 'inline' || typeof window === 'undefined') return;
480
593
  this._drawn = new Set();
594
+ this._dirty = new Set();
481
595
  if ('IntersectionObserver' in window) {
596
+ // Rows near the viewport. A row is drawn the first time it comes
597
+ // near, and again only if it went stale (a resize or a theme flip
598
+ // while it was away): a long list scrolled back and forth
599
+ // repaints nothing it doesn't have to.
600
+ this._onScreen = new Set();
482
601
  this._io = new IntersectionObserver((entries) => {
483
602
  for (const entry of entries) {
484
- if (!entry.isIntersecting) continue;
485
603
  const i = Number((entry.target as HTMLElement).dataset.wsIndex);
604
+ if (!entry.isIntersecting) { this._onScreen!.delete(i); continue; }
605
+ this._onScreen!.add(i);
606
+ if (this._drawn!.has(i) && !this._dirty!.has(i)) continue;
486
607
  this._drawn!.add(i);
487
608
  this._drawRow(i);
488
609
  }
@@ -501,31 +622,51 @@ export class WaveformSounds {
501
622
  });
502
623
  this._ro.observe(this.$.list);
503
624
  }
504
- const refresh = () => requestAnimationFrame(() => { this._resolveColors(); this._redrawAll(); });
625
+ let queued = 0;
626
+ const refresh = () => {
627
+ if (queued) return;
628
+ // A style change on an ancestor can be anything (an animation,
629
+ // a layout tweak): redraw only if the canvas colours moved.
630
+ queued = requestAnimationFrame(() => { queued = 0; if (this._resolveColors()) this._redrawAll(); });
631
+ };
632
+ // A theme can flip on ANY ancestor (a dark section, a themed card,
633
+ // a framework's root div), not just <html> / <body>. The container
634
+ // itself counts for class and theme, not style: the runtime writes
635
+ // --ws-surface there.
505
636
  this._mo = new MutationObserver(refresh);
506
- const watch = {attributes: true, attributeFilter: ['class', 'data-theme', 'data-color-scheme', 'style']};
507
- this._mo.observe(document.documentElement, watch);
508
- if (document.body) this._mo.observe(document.body, watch);
509
- try {
510
- window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', refresh, {signal: this._ctl.signal});
511
- } catch { /* no matchMedia */ }
637
+ this._mo.observe(this.container, {attributes: true, attributeFilter: ['class', 'data-theme', 'data-color-scheme']});
638
+ for (const node of ancestorsOf(this.container)) {
639
+ this._mo.observe(node, {attributes: true, attributeFilter: ['class', 'data-theme', 'data-color-scheme', 'style']});
640
+ }
641
+ for (const query of ['(prefers-color-scheme: dark)', '(forced-colors: active)']) {
642
+ try {
643
+ window.matchMedia(query).addEventListener('change', refresh, {signal: this._ctl.signal});
644
+ } catch { /* no matchMedia */ }
645
+ }
512
646
  }
513
647
 
514
648
  /**
515
- * Resolve the canvas colours (options, else the CSS custom properties)
516
- * and keep `--ws-surface` current unless the site set it.
649
+ * Resolve the canvas colours (options, else the CSS custom properties;
650
+ * system colours under forced colours) and keep `--ws-surface` current
651
+ * unless the site set it.
652
+ * @returns Whether the canvas colours changed.
517
653
  * @internal
518
654
  */
519
- _resolveColors(): void {
655
+ _resolveColors(): boolean {
656
+ const before = this.colors;
520
657
  if (this._autoSurface || !getComputedStyle(this.container).getPropertyValue('--ws-surface').trim()) {
521
658
  this._autoSurface = true;
522
659
  this.container.style.removeProperty('--ws-surface');
523
660
  this.container.style.setProperty('--ws-surface', pageSurface(this.container));
524
661
  }
662
+ // Forced colours: the system's own text and highlight, whatever the
663
+ // options or the CSS say (as every other part of the list does).
664
+ const forced = forcedColors();
525
665
  this.colors = {
526
- wave: this.options.waveformColor || resolveCssColor(this.container, 'var(--ws-wave-color)') || 'rgba(128,128,128,.5)',
527
- progress: this.options.progressColor || resolveCssColor(this.container, 'var(--ws-progress-color)') || 'currentColor',
666
+ wave: (forced ? resolveCssColor(this.container, 'CanvasText') : this.options.waveformColor || resolveCssColor(this.container, 'var(--ws-wave-color)')) || 'rgba(128,128,128,.5)',
667
+ progress: (forced ? resolveCssColor(this.container, 'Highlight') : this.options.progressColor || resolveCssColor(this.container, 'var(--ws-progress-color)')) || 'currentColor',
528
668
  };
669
+ return !before || before.wave !== this.colors.wave || before.progress !== this.colors.progress;
529
670
  }
530
671
 
531
672
  /**
@@ -536,7 +677,10 @@ export class WaveformSounds {
536
677
  if (this.render.player !== 'inline' || index == null || !this._drawn?.has(index)) return;
537
678
  const row = this.rows[index];
538
679
  const canvas = row?.querySelector('canvas');
539
- if (!canvas || row.hidden) return;
680
+ if (!canvas) return;
681
+ // Hidden (filtered, or past the page): draw it when it shows again.
682
+ if (row.hidden) { this._dirty?.add(index); return; }
683
+ this._dirty?.delete(index);
540
684
  const gap = Number(this.options.barGap);
541
685
  drawRowWaveform(canvas, this.sounds[index].peaks, index === this.currentIndex ? this.progress : 0, {
542
686
  style: this.options.waveformStyle,
@@ -548,11 +692,17 @@ export class WaveformSounds {
548
692
  }
549
693
 
550
694
  /**
551
- * Redraw every row drawn so far.
695
+ * After a resize or a theme flip: redraw the rows on screen now, and
696
+ * mark the rest stale — each is redrawn when it scrolls back in. (With
697
+ * 1000 rows drawn, redrawing them all took ~0.4s in Chrome and ~1.9s in
698
+ * WebKit per resize step.)
552
699
  * @internal
553
700
  */
554
701
  _redrawAll(): void {
555
- this._drawn?.forEach((i) => this._drawRow(i));
702
+ this._drawn?.forEach((i) => {
703
+ if (this._onScreen && !this._onScreen.has(i)) this._dirty!.add(i);
704
+ else this._drawRow(i);
705
+ });
556
706
  }
557
707
 
558
708
  /* ── Filters in the address ───────────────────────────────────────── */
@@ -564,7 +714,8 @@ export class WaveformSounds {
564
714
  _readUrl(): void {
565
715
  const keys = urlKeys(this.options.urlState);
566
716
  if (!keys || typeof location === 'undefined') return;
567
- const {filter, sort} = readUrlState(location.search, keys, facets(this.sounds), this._sorts);
717
+ const f = facets(this.sounds);
718
+ const {filter, sort} = readUrlState(location.search, keys, {...f, bpm: bpmExtent(f.bpm)}, this._sorts);
568
719
  (this as Writable<WaveformSounds>).filter = {...this.filter, ...filter};
569
720
  if (sort) { (this as Writable<WaveformSounds>).sortBy = sort as SoundsSort; this._sortSet = true; }
570
721
  }
@@ -589,6 +740,16 @@ export class WaveformSounds {
589
740
 
590
741
  /** The sounds that pass the filter, in the current sort order. */
591
742
  get visible(): Sound[] {
743
+ // Laid out by the last _apply(), which runs on every filter or sort
744
+ // change; computed afresh only before the list is built.
745
+ return [...(this._shown ?? this._match())];
746
+ }
747
+
748
+ /**
749
+ * Filter and sort the sounds now.
750
+ * @internal
751
+ */
752
+ _match(): Sound[] {
592
753
  return sortSounds(this.sounds.filter((s) => matches(s, this.filter)), this.sortBy);
593
754
  }
594
755
 
@@ -689,18 +850,38 @@ export class WaveformSounds {
689
850
  const $ = this.$;
690
851
  if (!$) return;
691
852
  if (resort || this.sortBy !== this._lastSort) {
692
- orderRows($.list, sortSounds(this.sounds, this.sortBy).map((s) => this.rows[this.sounds.indexOf(s)]));
853
+ // Each sound's row by identity: a Map, not indexOf per sound
854
+ // (quadratic — 1000 sounds was a million comparisons a sort).
855
+ const index = new Map(this.sounds.map((s, i) => [s, i]));
856
+ orderRows($.list, sortSounds(this.sounds, this.sortBy).map((s) => this.rows[index.get(s)!]));
693
857
  this._lastSort = this.sortBy;
694
858
  }
695
- const shown = this.visible;
859
+ const shown = this._match();
860
+ this._shown = shown;
696
861
  const {visible, remaining} = pageWindow(shown, this.limit);
697
862
  this.sounds.forEach((s, i) => { if (this.rows[i]) this.rows[i].hidden = !visible.has(s); });
698
863
  if ($.more) {
699
864
  $.more.hidden = remaining <= 0;
700
865
  $.more.textContent = fill(this.strings.showMore, {count: Math.min(remaining, this.render.pageSize || remaining)});
701
866
  }
702
- if ($.empty) $.empty.hidden = shown.length > 0;
867
+ if ($.empty) {
868
+ $.empty.hidden = shown.length > 0;
869
+ // No sounds at all: nothing matches because there is nothing, and
870
+ // there is no filter to clear.
871
+ if (!this.sounds.length && $.empty.textContent !== this.strings.noSounds) $.empty.textContent = this.strings.noSounds;
872
+ }
703
873
  if ($.count) $.count.textContent = countText(shown.length, this.sounds.length, this.strings);
874
+ // The Tab stop never sits on a hidden row; and if focus was in the
875
+ // row just filtered away, it follows the stop instead of falling
876
+ // to <body>.
877
+ if (!this._active || this._active.hidden) {
878
+ const lost = !!this._active?.contains(document.activeElement);
879
+ const first = visibleRows($.list)[0];
880
+ if (first) {
881
+ this._rove(first);
882
+ if (lost) this._focusRowQuietly(first);
883
+ } else if (this._active) { this._rowStops(this._active, false); this._active = null; }
884
+ }
704
885
  // Nothing played yet: keep the cued sound one the list still shows.
705
886
  if (this._cued && !this.playing) this._cueFirst();
706
887
  this._queueUrl();
@@ -715,11 +896,14 @@ export class WaveformSounds {
715
896
  * target means the current sound, else the first visible one.
716
897
  *
717
898
  * @param target
718
- * @returns
719
899
  * @internal
720
900
  */
721
901
  _indexOf(target?: number | string | Sound | null): number | null {
722
- if (target == null) return this.currentIndex ?? (this.visible[0] ? this.sounds.indexOf(this.visible[0]) : null);
902
+ if (target == null) {
903
+ if (this.currentIndex != null) return this.currentIndex;
904
+ const first = (this._shown ?? this._match())[0];
905
+ return first ? this.sounds.indexOf(first) : null;
906
+ }
723
907
  if (typeof target === 'number') return this.sounds[target] ? target : null;
724
908
  const i = typeof target === 'object' ? this.sounds.indexOf(target) : this.sounds.findIndex((s) => s.id === String(target));
725
909
  return i >= 0 ? i : null;
@@ -727,20 +911,26 @@ export class WaveformSounds {
727
911
 
728
912
  /**
729
913
  * The WaveformPlayer class: `playerClass`, else the page's global.
730
- * @returns
731
914
  * @internal
732
915
  */
733
916
  _playerClass(): EngineClass | null {
734
917
  return (this.options.playerClass || (typeof window !== 'undefined' ? (window as any).WaveformPlayer : null) || null) as EngineClass | null;
735
918
  }
736
919
 
920
+ /**
921
+ * The engine as the list drives it (fields the core keeps internal).
922
+ * @internal
923
+ */
924
+ _eng(): Engine | null {
925
+ return this.engine as unknown as Engine | null;
926
+ }
927
+
737
928
  /**
738
929
  * The element the engine mounts into: a child of the engine slot, never
739
930
  * the slot itself. WaveformPlayer resets its container's `className`,
740
931
  * which would strip `ws-engine--strip` (and with it the docked styling).
741
932
  * Made here rather than in the markup so server-rendered HTML from any
742
933
  * version works.
743
- * @returns
744
934
  * @internal
745
935
  */
746
936
  _engineMount(): HTMLElement {
@@ -760,21 +950,23 @@ export class WaveformSounds {
760
950
  * @internal
761
951
  */
762
952
  _ensureEngine(): Engine | null {
763
- if (this.engine) return this.engine as Engine;
953
+ if (this.engine) return this._eng();
764
954
  const Player = this._playerClass();
765
955
  if (!Player) {
766
956
  console.error(`${LOG} @arraypress/waveform-player is required: load it before playing (or pass playerClass).`);
767
957
  return null;
768
958
  }
769
- (this as Writable<WaveformSounds>).engine = new Player(this._engineMount(), engineOptions(this.options.playerOptions, this.render.player, {
959
+ const options = engineOptions(this.options.playerOptions, this.render.player, {
770
960
  onLoad: () => this._onEngineLoad(),
771
961
  onPlay: () => this._setPlaying(true),
772
962
  onPause: () => this._setPlaying(false),
773
963
  onEnd: () => this._onEnd(),
774
964
  onTimeUpdate: (time: number, duration: number) => this._onTime(time, duration),
775
965
  onError: (err: unknown) => this._onEngineError(err),
776
- }));
777
- return this.engine as Engine;
966
+ });
967
+ this._preload = options.preload;
968
+ (this as Writable<WaveformSounds>).engine = new Player(this._engineMount(), options) as unknown as WaveformPlayer;
969
+ return this._eng();
778
970
  }
779
971
 
780
972
  /**
@@ -803,32 +995,46 @@ export class WaveformSounds {
803
995
  if (previous != null) this._paintRow(previous);
804
996
  this._paintRow(index);
805
997
  const sound = this.sounds[index];
806
- engine.loadTrack(sound.url, sound.title, sound.type || null, engineTrack(sound, this.render.player, true));
998
+ engine.loadTrack(sound.url, sound.title, sound.type || null, engineTrack(sound, this.render.player, true, this._preload));
807
999
  }
808
1000
 
809
1001
  /**
810
1002
  * Strip layout: load the first sound the list shows into the docked
811
1003
  * player WITHOUT playing it, so the player shows a title and waveform
812
1004
  * (and its play button plays that sound) instead of an empty frame.
813
- * Only metadata is fetched — the browser default for any `<audio>`.
1005
+ * Nothing is fetched (`preload: 'none'`): the player shows the title,
1006
+ * length and peaks from the data, and the audio loads on play — a filter
1007
+ * change re-cues, and each cue used to fetch a file's metadata.
814
1008
  * The row isn't marked current until it plays.
815
1009
  * @internal
816
1010
  */
817
1011
  _cueFirst(): void {
818
- const engine = this.engine as Engine | null;
819
- const first = this.visible[0];
1012
+ const engine = this._eng();
1013
+ const first = (this._shown ?? this._match())[0];
820
1014
  if (!engine || !first) return;
821
1015
  const index = this.sounds.indexOf(first);
822
1016
  if (index === this.currentIndex) return;
823
1017
  this.currentIndex = index;
824
1018
  this.progress = 0;
825
1019
  this._cued = true;
826
- engine.loadTrack(first.url, first.title, first.type || null, engineTrack(first, 'strip', false));
1020
+ // Firefox fetches a source set in the same task as a script's
1021
+ // load(), whatever `preload` says — and the core's loadTrack() resets
1022
+ // the element with load() before setting the new source. Nothing
1023
+ // plays yet, so that reset can go: setting `src` (which the core
1024
+ // does too) restarts the element's load on its own.
1025
+ const audio = engine.audio;
1026
+ const shim = audio && typeof audio.load === 'function';
1027
+ if (shim) audio!.load = () => {};
1028
+ try {
1029
+ engine.loadTrack(first.url, first.title, first.type || null, engineTrack(first, 'strip', false, 'none'));
1030
+ } finally {
1031
+ if (shim) delete (audio as Partial<HTMLAudioElement>).load;
1032
+ }
827
1033
  }
828
1034
 
829
1035
  /** Pause the current sound. */
830
1036
  pause(): void {
831
- if (this.engine && this.playing) (this.engine as Engine).pause();
1037
+ if (this.engine && this.playing) this._eng()!.pause();
832
1038
  }
833
1039
 
834
1040
  /**
@@ -857,7 +1063,7 @@ export class WaveformSounds {
857
1063
  * @internal
858
1064
  */
859
1065
  _step(dir: 1 | -1): boolean {
860
- const shown = this.visible;
1066
+ const shown = this._shown ?? this._match();
861
1067
  // A cued sound counts as nothing played: next() starts with it.
862
1068
  const at = this.currentIndex == null || this._cued ? -1 : shown.indexOf(this.sounds[this.currentIndex]);
863
1069
  const target = shown[at + dir];
@@ -886,7 +1092,7 @@ export class WaveformSounds {
886
1092
  */
887
1093
  _setLoop(on: boolean): void {
888
1094
  this.$?.loop?.setAttribute('aria-pressed', String(on));
889
- if ((this.engine as Engine | null)?.audio) (this.engine as Engine).audio!.loop = this._repeats();
1095
+ if (this._eng()?.audio) this._eng()!.audio!.loop = this._repeats();
890
1096
  }
891
1097
 
892
1098
  /**
@@ -907,29 +1113,31 @@ export class WaveformSounds {
907
1113
  */
908
1114
  _seekRow(index: number, fraction: number): void {
909
1115
  if (index !== this.currentIndex || !this.engine) { this.play(index, {at: fraction}); return; }
910
- const duration = (this.engine as Engine).audio?.duration;
1116
+ const duration = this._eng()!.audio?.duration;
911
1117
  if (!Number.isFinite(duration) || duration! <= 0) { this._pendingSeek = fraction; return; }
912
- (this.engine as Engine).seekTo(fraction * duration!);
1118
+ this._eng()!.seekTo(fraction * duration!);
913
1119
  this.progress = fraction;
914
1120
  this._paintRow(index);
915
- if (!this.playing) (this.engine as Engine).play();
1121
+ this._paintSlider();
1122
+ if (!this.playing) this._eng()!.play();
916
1123
  }
917
1124
 
918
1125
  /**
919
- * The engine loaded a sound: apply the loop, borrow decoded peaks for a
1126
+ * The engine loaded a sound: clear an earlier failure, apply the loop, borrow decoded peaks for a
920
1127
  * row that had none, and land a pending seek.
921
1128
  * @internal
922
1129
  */
923
1130
  _onEngineLoad(): void {
924
- if ((this.engine as Engine | null)?.audio) (this.engine as Engine).audio!.loop = this._repeats();
1131
+ if (this.currentIndex != null) this.rows[this.currentIndex]?.classList.remove('is-error');
1132
+ if (this._eng()?.audio) this._eng()!.audio!.loop = this._repeats();
925
1133
  const sound = this.sounds[this.currentIndex!];
926
- if (sound && !sound.peaks && (this.engine as Engine | null)?.waveformData?.length) {
927
- sound.peaks = resample((this.engine as Engine).waveformData, 96);
1134
+ if (sound && !sound.peaks && this._eng()?.waveformData?.length) {
1135
+ sound.peaks = resample(this._eng()!.waveformData, 96);
928
1136
  this._drawRow(this.currentIndex);
929
1137
  }
930
- const duration = (this.engine as Engine | null)?.audio?.duration;
1138
+ const duration = this._eng()?.audio?.duration;
931
1139
  if (this._pendingSeek != null && Number.isFinite(duration) && duration! > 0) {
932
- (this.engine as Engine).seekTo(this._pendingSeek * duration!);
1140
+ this._eng()!.seekTo(this._pendingSeek * duration!);
933
1141
  this.progress = this._pendingSeek;
934
1142
  this._pendingSeek = null;
935
1143
  }
@@ -944,7 +1152,7 @@ export class WaveformSounds {
944
1152
  if (this._pendingSeek != null) {
945
1153
  const fraction = this._pendingSeek;
946
1154
  this._pendingSeek = null;
947
- (this.engine as Engine).seekTo(fraction * duration);
1155
+ this._eng()!.seekTo(fraction * duration);
948
1156
  return;
949
1157
  }
950
1158
  this.progress = Math.min(Math.max(time / duration, 0), 1);
@@ -952,7 +1160,7 @@ export class WaveformSounds {
952
1160
  this._raf = requestAnimationFrame(() => {
953
1161
  this._raf = 0;
954
1162
  this._drawRow(this.currentIndex);
955
- this.rows[this.currentIndex!]?.querySelector('.ws-wave')?.setAttribute('aria-valuenow', String(Math.round(this.progress * 100)));
1163
+ this._paintSlider();
956
1164
  });
957
1165
  }
958
1166
 
@@ -970,33 +1178,62 @@ export class WaveformSounds {
970
1178
  }
971
1179
 
972
1180
  /**
973
- * A sound failed to load or play: mark its row and report it.
1181
+ * A sound failed to load or play: it isn't playing (no stale "Pause"),
1182
+ * its row is marked until it plays, and the live region says so.
974
1183
  * @internal
975
1184
  */
976
1185
  _onEngineError(err: unknown): void {
977
- this.rows[this.currentIndex!]?.classList.add('is-error');
978
- this._emit('error', {error: err, sound: this.sounds[this.currentIndex!], index: this.currentIndex});
1186
+ const index = this.currentIndex;
1187
+ const sound = index == null ? undefined : this.sounds[index];
1188
+ if (index != null) this.rows[index]?.classList.add('is-error');
1189
+ this._setPlaying(false);
1190
+ // A cued sound (strip, nothing played) wasn't asked for: no announcement.
1191
+ if (sound && !this._cued && this.$?.status) this.$.status.textContent = fill(this.strings.playError, {title: sound.title});
1192
+ this._emit('error', {error: err, sound, index});
979
1193
  this.options.onError?.(err, this);
980
1194
  }
981
1195
 
982
1196
  /**
983
- * Record play/pause and repaint. Events fire only on a real change: at a
984
- * natural end the browser fires `pause` then `ended`, and `_onEnd()`
985
- * also settles the state — one pause event, not two.
1197
+ * Record play/pause and repaint, and report what the listener hears.
1198
+ * Events follow the SOUND, not the flag: switching sounds while one plays
1199
+ * (↓ audition, `play(i)`, `next()`, auto-advance) never flips `playing`
1200
+ * in some engines (the media element swaps source without a `pause`),
1201
+ * so the last sound announced is tracked — a different one starting
1202
+ * reports `pause` for the outgoing sound, then `play` for the new one.
1203
+ * At a natural end the browser fires `pause` then `ended`, and `_onEnd()`
1204
+ * settles the state again: one pause event, not two.
986
1205
  * @internal
987
1206
  */
988
1207
  _setPlaying(on: boolean): void {
989
- const changed = this.playing !== on;
990
1208
  (this as Writable<WaveformSounds>).playing = on;
991
1209
  if (on) this._cued = false; // the strip's own button played the cued sound
992
1210
  const index = this.currentIndex;
993
1211
  if (index == null) return;
1212
+ if (on) this.rows[index]?.classList.remove('is-error'); // it plays after all
994
1213
  this._paintRow(index);
995
- if (!changed) return;
1214
+ const was = this._announced ?? null;
1215
+ if (on) {
1216
+ if (was === index) return;
1217
+ if (was != null) this._announce('pause', was);
1218
+ this._announced = index;
1219
+ this._announce('play', index);
1220
+ } else if (was != null) {
1221
+ this._announced = null;
1222
+ this._announce('pause', was);
1223
+ }
1224
+ }
1225
+
1226
+ /**
1227
+ * Report a sound starting or stopping: the live region (on play), the
1228
+ * `waveformsounds:play|pause` event and the `onPlay` / `onPause` callback.
1229
+ * @internal
1230
+ */
1231
+ _announce(type: 'play' | 'pause', index: number): void {
996
1232
  const sound = this.sounds[index];
997
- if (on && this.$.status) this.$.status.textContent = fill(this.strings.nowPlaying, {title: sound.title});
998
- this._emit(on ? 'play' : 'pause', {sound, index});
999
- (on ? this.options.onPlay : this.options.onPause)?.(sound, this);
1233
+ if (!sound) return;
1234
+ if (type === 'play' && this.$?.status) this.$.status.textContent = fill(this.strings.nowPlaying, {title: sound.title});
1235
+ this._emit(type, {sound, index});
1236
+ (type === 'play' ? this.options.onPlay : this.options.onPause)?.(sound, this);
1000
1237
  }
1001
1238
 
1002
1239
  /* ── Row painting ─────────────────────────────────────────────────── */
@@ -1019,20 +1256,41 @@ export class WaveformSounds {
1019
1256
  }
1020
1257
  const wave = row.querySelector<HTMLElement>('.ws-wave');
1021
1258
  if (wave) {
1022
- wave.tabIndex = current ? 0 : -1;
1023
- if (!current) wave.setAttribute('aria-valuenow', '0');
1259
+ wave.tabIndex = current && row === this._active ? 0 : -1;
1260
+ if (!current) {
1261
+ wave.setAttribute('aria-valuenow', '0');
1262
+ wave.removeAttribute('aria-valuetext');
1263
+ }
1024
1264
  }
1025
1265
  this._drawRow(index);
1026
1266
  }
1027
1267
 
1268
+ /**
1269
+ * The current row's seek slider: its position (0–100) and, for a screen
1270
+ * reader, the time ("0:12 of 0:30").
1271
+ * @internal
1272
+ */
1273
+ _paintSlider(): void {
1274
+ const index = this.currentIndex;
1275
+ const wave = index == null ? null : this.rows[index]?.querySelector('.ws-wave');
1276
+ if (!wave) return;
1277
+ wave.setAttribute('aria-valuenow', String(Math.round(this.progress * 100)));
1278
+ const audio = this._eng()?.audio;
1279
+ const duration = Number.isFinite(audio?.duration) && audio!.duration > 0 ? audio!.duration : this.sounds[index!].duration;
1280
+ if (duration) wave.setAttribute('aria-valuetext', fill(this.strings.seekValue, {time: formatClock(this.progress * duration), duration: formatDuration(duration)}));
1281
+ }
1282
+
1028
1283
  /* ── Events & lifecycle ──────────────────────────────────────────── */
1029
1284
 
1030
1285
  /**
1031
- * Emit a `waveformsounds:<name>` event carrying this instance.
1286
+ * Announce a moment both ways: a `waveformsounds:<name>` event on the
1287
+ * container carrying the details and this instance, then a plain `<name>`
1288
+ * event on the instance.
1032
1289
  * @internal
1033
1290
  */
1034
- _emit(name: string, detail: Record<string, any> = {}): void {
1291
+ _emit(name: keyof WaveformSoundsInstanceEventMap, detail: Record<string, any> = {}): void {
1035
1292
  emit(this.container, name, {...detail, instance: this});
1293
+ this.dispatchEvent(new Event(name));
1036
1294
  }
1037
1295
 
1038
1296
  /** The sound playing (or paused) now, or null. */
@@ -1045,10 +1303,15 @@ export class WaveformSounds {
1045
1303
  * Tear down: listeners, observers, timers and the engine. Markup this
1046
1304
  * instance rendered is restored to what the container held before.
1047
1305
  * ADOPTED (server-rendered) markup is left as it is now — rows may be
1048
- * re-sorted, hidden or marked current — so to start again, re-render it
1049
- * rather than constructing a new instance over it.
1306
+ * re-sorted, hidden or marked current — unless `restore` is set: then it
1307
+ * is put back exactly as the server sent it, ready for a new instance
1308
+ * (what a framework re-mounting the same markup wants).
1309
+ *
1310
+ * @param options
1311
+ * @param options.restore - Put adopted server markup back as it was.
1312
+ * Default false. Since 2.1.0.
1050
1313
  */
1051
- destroy(): void {
1314
+ destroy(options: {restore?: boolean} = {}): void {
1052
1315
  if (this.destroyed) return;
1053
1316
  this.destroyed = true;
1054
1317
  this._ctl.abort();
@@ -1057,10 +1320,11 @@ export class WaveformSounds {
1057
1320
  this._mo?.disconnect();
1058
1321
  if (this._raf) cancelAnimationFrame(this._raf);
1059
1322
  clearTimeout(this._urlTimer);
1060
- try { (this.engine as Engine | null)?.destroy(); } catch { /* engine already gone */ }
1323
+ try { this._eng()?.destroy(); } catch { /* engine already gone */ }
1061
1324
  (this as Writable<WaveformSounds>).engine = null;
1062
1325
  this.$?.engine?.querySelector(':scope > [data-ws-engine-mount]')?.remove();
1063
1326
  if (this._originalHTML != null) this.container.innerHTML = this._originalHTML;
1327
+ else if (options.restore && this._adoptedHTML != null) this.container.innerHTML = this._adoptedHTML;
1064
1328
  if (this._addedClasses?.length) this.container.classList.remove(...this._addedClasses);
1065
1329
  if (this._autoSurface) this.container.style.removeProperty('--ws-surface');
1066
1330
  delete this.container.dataset.wsInitialized;
@@ -1088,7 +1352,6 @@ export class WaveformSounds {
1088
1352
  /**
1089
1353
  * The instance on an element (or selector), if any.
1090
1354
  * @param el
1091
- * @returns
1092
1355
  */
1093
1356
  static getInstance(el: Element | string): WaveformSounds | null {
1094
1357
  const node = typeof el === 'string' ? document.querySelector(el) : el;