@arraypress/waveform-sounds 0.3.0 → 2.0.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 (81) hide show
  1. package/LICENSE +1 -1
  2. package/README.md +19 -1
  3. package/dist/waveform-sounds-no-autoinit.esm.js +145 -98
  4. package/dist/waveform-sounds-render.esm.js +25 -11
  5. package/dist/waveform-sounds.css +66 -78
  6. package/dist/waveform-sounds.esm.js +146 -99
  7. package/dist/waveform-sounds.js +147 -99
  8. package/dist/waveform-sounds.min.css +1 -1
  9. package/dist/waveform-sounds.min.js +1 -1
  10. package/package.json +36 -33
  11. package/src/css/waveform-sounds.css +66 -78
  12. package/src/js/core/{WaveformSounds.js → WaveformSounds.ts} +328 -189
  13. package/src/js/core/engine.ts +101 -0
  14. package/src/js/core/{options.js → options.ts} +33 -28
  15. package/src/js/data/{bpm.js → bpm.ts} +17 -17
  16. package/src/js/data/{navigation.js → navigation.ts} +17 -17
  17. package/src/js/data/{sounds.js → sounds.ts} +67 -63
  18. package/src/js/data/{url-state.js → url-state.ts} +27 -26
  19. package/src/js/dom/{colors.js → colors.ts} +12 -12
  20. package/src/js/dom/{draw.js → draw.ts} +17 -17
  21. package/src/js/dom/{menus.js → menus.ts} +72 -55
  22. package/src/js/dom/{rows.js → rows.ts} +18 -17
  23. package/src/js/{entry.js → entry.ts} +25 -0
  24. package/src/js/render/{html.js → html.ts} +18 -12
  25. package/src/js/render/{icons.js → icons.ts} +4 -4
  26. package/src/js/render/{markup.js → markup.ts} +82 -60
  27. package/src/js/render/{options.js → options.ts} +26 -20
  28. package/src/js/render/{strings.js → strings.ts} +17 -16
  29. package/src/js/{render-entry.js → render-entry.ts} +1 -0
  30. package/src/js/shared/{utils.js → utils.ts} +22 -22
  31. package/{index.d.ts → src/js/types.ts} +12 -87
  32. package/types/core/WaveformSounds.d.ts +145 -0
  33. package/types/core/WaveformSounds.d.ts.map +1 -0
  34. package/types/core/engine.d.ts +67 -0
  35. package/types/core/engine.d.ts.map +1 -0
  36. package/types/core/options.d.ts +76 -0
  37. package/types/core/options.d.ts.map +1 -0
  38. package/types/data/bpm.d.ts +67 -0
  39. package/types/data/bpm.d.ts.map +1 -0
  40. package/types/data/navigation.d.ts +53 -0
  41. package/types/data/navigation.d.ts.map +1 -0
  42. package/types/data/sounds.d.ts +167 -0
  43. package/types/data/sounds.d.ts.map +1 -0
  44. package/types/data/url-state.d.ts +83 -0
  45. package/types/data/url-state.d.ts.map +1 -0
  46. package/types/dom/colors.d.ts +35 -0
  47. package/types/dom/colors.d.ts.map +1 -0
  48. package/types/dom/draw.d.ts +73 -0
  49. package/types/dom/draw.d.ts.map +1 -0
  50. package/types/dom/menus.d.ts +77 -0
  51. package/types/dom/menus.d.ts.map +1 -0
  52. package/types/dom/rows.d.ts +42 -0
  53. package/types/dom/rows.d.ts.map +1 -0
  54. package/types/entry.d.ts +22 -0
  55. package/types/entry.d.ts.map +1 -0
  56. package/types/index.d.ts +16 -0
  57. package/types/index.d.ts.map +1 -0
  58. package/types/render/html.d.ts +39 -0
  59. package/types/render/html.d.ts.map +1 -0
  60. package/types/render/icons.d.ts +17 -0
  61. package/types/render/icons.d.ts.map +1 -0
  62. package/types/render/markup.d.ts +132 -0
  63. package/types/render/markup.d.ts.map +1 -0
  64. package/types/render/options.d.ts +56 -0
  65. package/types/render/options.d.ts.map +1 -0
  66. package/types/render/strings.d.ts +46 -0
  67. package/types/render/strings.d.ts.map +1 -0
  68. package/types/render-entry.d.ts +8 -0
  69. package/types/render-entry.d.ts.map +1 -0
  70. package/types/shared/utils.d.ts +57 -0
  71. package/types/shared/utils.d.ts.map +1 -0
  72. package/types/types.d.ts +254 -0
  73. package/types/types.d.ts.map +1 -0
  74. package/types/vendor/arraypress-text.d.ts +250 -0
  75. package/dist/waveform-sounds-no-autoinit.cjs +0 -2136
  76. package/dist/waveform-sounds-render.cjs +0 -614
  77. package/dist/waveform-sounds.cjs +0 -2158
  78. package/no-autoinit.d.ts +0 -2
  79. package/render.d.ts +0 -5
  80. package/src/js/core/engine.js +0 -57
  81. /package/src/js/{index.js → index.ts} +0 -0
@@ -28,7 +28,7 @@
28
28
 
29
29
  import {availableSorts, facets, matches, normalizeSounds, parseManifest, sortSounds, SORTS} from '../data/sounds.js';
30
30
  import {drawRowWaveform, resample} from '../dom/draw.js';
31
- import {engineOptions, enginePeaks} from './engine.js';
31
+ import {engineOptions, engineTrack} from './engine.js';
32
32
  import {Menus} from '../dom/menus.js';
33
33
  import {limitToReveal, pageWindow, rowTarget, seekTarget} from '../data/navigation.js';
34
34
  import {DEFAULT_OPTIONS, mergeOptions, readDataOptions} from './options.js';
@@ -40,11 +40,53 @@ import {bpmFilterFromRange, bpmFraction, bpmRangeFromFilter} from '../data/bpm.j
40
40
  import {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';
44
+ import type {EngineTrack} from './engine.js';
45
+ import type {RenderOptions} from '../render/options.js';
46
+ import type {Sound, SoundInput, SoundsFilter, SoundsLoopFilter, SoundsSort, WaveformSoundsOptions, WaveformSoundsStrings} from '../types.js';
47
+
48
+ /** The engine `WaveformPlayer`, as far as the list uses it. */
49
+ interface Engine {
50
+ audio: HTMLAudioElement | null;
51
+ waveformData: number[];
52
+ play(): unknown;
53
+ pause(): unknown;
54
+ seekTo(seconds: number): unknown;
55
+ loadTrack(url: string, title: string, artist: string | null, options: EngineTrack): unknown;
56
+ destroy(): unknown;
57
+ }
58
+
59
+ /** The `WaveformPlayer` class (`playerClass`, or the page's global). */
60
+ type EngineClass = new (container: HTMLElement, options: Record<string, any>) => Engine;
61
+
62
+ /** The elements the runtime drives (`_cacheRefs`). */
63
+ interface Refs {
64
+ list: HTMLElement;
65
+ search: HTMLInputElement | null;
66
+ bpmMin: HTMLInputElement | null;
67
+ bpmMax: HTMLInputElement | null;
68
+ bpmRange: HTMLElement | null;
69
+ bpmReadout: HTMLElement | null;
70
+ bpmClear: HTMLElement | null;
71
+ bpmLabel: HTMLElement | null;
72
+ loop: HTMLElement | null;
73
+ count: HTMLElement | null;
74
+ empty: HTMLElement | null;
75
+ more: HTMLElement | null;
76
+ engine: HTMLElement | null;
77
+ status: HTMLElement | null;
78
+ chips: HTMLElement[];
79
+ loopFilter: HTMLElement[];
80
+ }
81
+
82
+ /** The public fields are readonly to callers; the class itself writes them
83
+ * through this (a cast: it emits nothing). */
84
+ type Writable<T> = {-readonly [K in keyof T]: T[K]};
43
85
 
44
86
  export {DEFAULT_OPTIONS};
45
87
 
46
88
  /** An empty filter: everything matches. */
47
- const NO_FILTER = Object.freeze({query: '', type: '', key: '', bpmMin: '', bpmMax: '', loop: ''});
89
+ const NO_FILTER: Readonly<SoundsFilter> = Object.freeze({query: '', type: '', key: '', bpmMin: '', bpmMax: '', loop: ''});
48
90
 
49
91
  /** Debounce for typing in the search box and the BPM fields (ms). */
50
92
  const SEARCH_DELAY = 120;
@@ -54,19 +96,84 @@ const BPM_DELAY = 200;
54
96
  const URL_DELAY = 250;
55
97
 
56
98
  export class WaveformSounds {
57
- /** @type {Map<Element, WaveformSounds>} */
58
- static instances = new Map();
99
+ /** Every live instance, by its element. */
100
+ static instances: Map<Element, WaveformSounds> = new Map();
101
+ /** The pure helpers, for `<script>` users (attached in `entry.ts`). */
102
+ declare static utils: {
103
+ encodePeaks: typeof encodePeaks;
104
+ decodePeaks: typeof decodePeaks;
105
+ normalizeKey: typeof normalizeKey;
106
+ normalizeSounds: typeof normalizeSounds;
107
+ parseManifest: typeof parseManifest;
108
+ facets: typeof facets;
109
+ matches: typeof matches;
110
+ sortSounds: typeof sortSounds;
111
+ formatDuration: typeof formatDuration;
112
+ renderSounds: typeof renderSounds;
113
+ };
114
+ /** Every option with its default (attached in `entry.ts`). */
115
+ declare static DEFAULT_OPTIONS: WaveformSoundsOptions;
116
+ /** The English UI strings (attached in `entry.ts`). */
117
+ declare static DEFAULT_STRINGS: WaveformSoundsStrings;
118
+
119
+ declare readonly container: HTMLElement;
120
+ declare readonly options: Required<WaveformSoundsOptions>;
121
+ /** Resolves once the list is built (after a manifest fetch, if any).
122
+ * The build always happens after the constructor returns, so listeners
123
+ * attached straight after `new WaveformSounds()` see `ready`. It never
124
+ * rejects: a failed build (e.g. the manifest 404s) resolves it too and
125
+ * is reported through `onError` / `waveformsounds:error`. Calls made
126
+ * before it resolves are honoured: `setFilter`/`setSort` show in the
127
+ * controls once built, and `play()` waits for the list. */
128
+ declare readonly ready: Promise<void>;
129
+ declare readonly sounds: Sound[];
130
+ declare readonly filter: SoundsFilter;
131
+ declare readonly sortBy: SoundsSort;
132
+ declare readonly playing: boolean;
133
+ /** The engine `WaveformPlayer`, created on first play. */
134
+ declare readonly engine: unknown;
135
+
136
+ /** @internal */ declare strings: WaveformSoundsStrings;
137
+ /** @internal */ declare render: RenderOptions;
138
+ /** @internal */ declare rows: HTMLElement[];
139
+ /** @internal */ declare limit: number;
140
+ /** @internal */ declare currentIndex: number | null;
141
+ /** @internal */ declare progress: number;
142
+ /** @internal */ declare loop: boolean;
143
+ /** @internal */ declare menus: Menus | null;
144
+ /** @internal */ declare destroyed: boolean;
145
+ /** @internal Unset until the list is built; code that can run before checks it. */
146
+ declare $: Refs;
147
+ /** @internal */ declare colors: {wave: string, progress: string} | undefined;
148
+ /** @internal */ declare _ctl: AbortController;
149
+ /** @internal */ declare _originalHTML: string | null;
150
+ /** @internal */ declare _pendingSeek: number | null;
151
+ /** @internal */ declare _raf: number;
152
+ /** @internal */ declare _addedClasses: string[] | undefined;
153
+ /** @internal */ declare _loopSet: boolean | undefined;
154
+ /** @internal */ declare _sortSet: boolean | undefined;
155
+ /** @internal */ declare _bpmExtent: {min: number, max: number} | null;
156
+ /** @internal */ declare _sorts: string[];
157
+ /** @internal */ declare _lastSort: string | undefined;
158
+ /** @internal */ declare _lastPointer: string | undefined;
159
+ /** @internal */ declare _drawn: Set<number> | undefined;
160
+ /** @internal */ declare _io: IntersectionObserver | undefined;
161
+ /** @internal */ declare _ro: ResizeObserver | undefined;
162
+ /** @internal */ declare _mo: MutationObserver | undefined;
163
+ /** @internal */ declare _autoSurface: boolean | undefined;
164
+ /** @internal */ declare _urlTimer: number | undefined;
165
+ /** @internal */ declare _cued: boolean | undefined;
59
166
 
60
167
  /**
61
168
  * @param {HTMLElement|string} container - The element (or a selector).
62
- * @param {import('../../../index').WaveformSoundsOptions} [options]
169
+ * @param {WaveformSoundsOptions} [options]
63
170
  */
64
- constructor(container, options = {}) {
65
- const el = typeof container === 'string' ? document.querySelector(container) : container;
171
+ constructor(container: HTMLElement | string, options: WaveformSoundsOptions = {}) {
172
+ const el = typeof container === 'string' ? document.querySelector<HTMLElement>(container) : container;
66
173
  if (!el) throw new Error(`${LOG} Container not found: ${container}`);
67
174
  this.container = el;
68
175
  // Precedence, as across the family: data-* > constructor > default.
69
- this.options = mergeOptions(DEFAULT_OPTIONS, options, readDataOptions(el));
176
+ this.options = mergeOptions(DEFAULT_OPTIONS, options, readDataOptions(el)) as Required<WaveformSoundsOptions>;
70
177
  this.options.waveformStyle = this.options.waveformStyle === 'bars' ? 'bars' : 'mirror';
71
178
  this.strings = {...DEFAULT_STRINGS, ...(this.options.strings || {})};
72
179
  this.render = {...resolveRenderOptions(this.options), strings: this.strings};
@@ -108,18 +215,18 @@ export class WaveformSounds {
108
215
  /**
109
216
  * Adopt server-rendered markup or render it (from `sounds` or a fetched
110
217
  * manifest), then wire everything up.
111
- * @private
218
+ * @internal
112
219
  */
113
- async _init() {
220
+ async _init(): Promise<void> {
114
221
  const el = this.container;
115
- const adopted = el.querySelector('[data-ws-list]');
222
+ const adopted = el.querySelector<HTMLElement>('[data-ws-list]');
116
223
  if (adopted) {
117
- this.sounds = readRows(adopted);
224
+ (this as Writable<WaveformSounds>).sounds = readRows(adopted);
118
225
  } else {
119
226
  this._originalHTML = el.innerHTML;
120
- this.sounds = await this._loadSounds();
227
+ (this as Writable<WaveformSounds>).sounds = await this._loadSounds();
121
228
  if (this.destroyed) return;
122
- el.innerHTML = renderSounds(this.sounds, {...this.render, idPrefix: this.options.idPrefix || el.id || undefined});
229
+ el.innerHTML = renderSounds(this.sounds as SoundInput[], {...this.render, idPrefix: this.options.idPrefix || el.id || undefined});
123
230
  }
124
231
  if (this.destroyed) return;
125
232
 
@@ -141,7 +248,7 @@ export class WaveformSounds {
141
248
  // The starting order is the first one offered, unless setSort()
142
249
  // already chose one; then the address may override both.
143
250
  this._sorts = availableSorts(this.render.sorts, facets(this.sounds));
144
- if (!this._sortSet) this.sortBy = this._sorts[0] || 'default';
251
+ if (!this._sortSet) (this as Writable<WaveformSounds>).sortBy = (this._sorts[0] || 'default') as SoundsSort;
145
252
  this._readUrl();
146
253
  // Show any filter/sort set before now (from code or the address).
147
254
  this._syncControls();
@@ -153,6 +260,9 @@ export class WaveformSounds {
153
260
  // BEFORE the first play — built on first play, that sound went
154
261
  // untracked.
155
262
  if (this._playerClass()) this._ensureEngine();
263
+ // Strip: the docked player starts with the first sound cued — its
264
+ // title and waveform, ready to play — rather than an empty frame.
265
+ if (this.render.player === 'strip' && this.engine && this.currentIndex == null) this._cueFirst();
156
266
 
157
267
  this._emit('ready', {sounds: this.sounds.length});
158
268
  this.options.onReady?.(this);
@@ -160,10 +270,10 @@ export class WaveformSounds {
160
270
 
161
271
  /**
162
272
  * The sounds from the `sounds` option, else the `manifest` URL.
163
- * @returns {Promise<import('../../../index').Sound[]>}
164
- * @private
273
+ * @returns
274
+ * @internal
165
275
  */
166
- async _loadSounds() {
276
+ async _loadSounds(): Promise<Sound[]> {
167
277
  if (this.options.sounds || !this.options.manifest) return normalizeSounds(this.options.sounds || []);
168
278
  const res = await fetch(this.options.manifest);
169
279
  if (!res.ok) throw new Error(`${LOG} Manifest ${this.options.manifest}: HTTP ${res.status}`);
@@ -172,15 +282,15 @@ export class WaveformSounds {
172
282
 
173
283
  /**
174
284
  * Look up the elements the runtime drives.
175
- * @private
285
+ * @internal
176
286
  */
177
287
  _cacheRefs() {
178
- const q = (sel) => this.container.querySelector(sel);
288
+ const q = <T extends HTMLElement = HTMLElement>(sel: string) => this.container.querySelector<T>(sel);
179
289
  this.$ = {
180
- list: q('[data-ws-list]'),
181
- search: q('[data-ws-search]'),
182
- bpmMin: q('[data-ws-bpm-min]'),
183
- bpmMax: q('[data-ws-bpm-max]'),
290
+ list: q('[data-ws-list]')!,
291
+ search: q<HTMLInputElement>('[data-ws-search]'),
292
+ bpmMin: q<HTMLInputElement>('[data-ws-bpm-min]'),
293
+ bpmMax: q<HTMLInputElement>('[data-ws-bpm-max]'),
184
294
  bpmRange: q('[data-ws-bpm-range]'),
185
295
  bpmReadout: q('[data-ws-bpm-readout]'),
186
296
  bpmClear: q('[data-ws-bpm-clear]'),
@@ -191,8 +301,8 @@ export class WaveformSounds {
191
301
  more: q('[data-ws-more]'),
192
302
  engine: q('[data-ws-engine]'),
193
303
  status: q('[data-ws-status]'),
194
- chips: [...this.container.querySelectorAll('[data-ws-type]')],
195
- loopFilter: [...this.container.querySelectorAll('[data-ws-loop-filter]')],
304
+ chips: [...this.container.querySelectorAll<HTMLElement>('[data-ws-type]')],
305
+ loopFilter: [...this.container.querySelectorAll<HTMLElement>('[data-ws-loop-filter]')],
196
306
  };
197
307
  this.rows = indexRows(this.$.list);
198
308
  }
@@ -200,7 +310,7 @@ export class WaveformSounds {
200
310
  /**
201
311
  * Every listener. All are removed by `destroy()` through one
202
312
  * AbortController.
203
- * @private
313
+ * @internal
204
314
  */
205
315
  _bind() {
206
316
  const sig = {signal: this._ctl.signal};
@@ -214,24 +324,24 @@ export class WaveformSounds {
214
324
  let searchTimer = 0, bpmTimer = 0;
215
325
  $.search?.addEventListener('input', () => {
216
326
  clearTimeout(searchTimer);
217
- searchTimer = setTimeout(() => this.setFilter({query: $.search.value}), SEARCH_DELAY);
327
+ searchTimer = setTimeout(() => this.setFilter({query: $.search!.value}), SEARCH_DELAY);
218
328
  }, sig);
219
329
  $.search?.addEventListener('keydown', (e) => {
220
330
  if (e.key === 'ArrowDown') { e.preventDefault(); this._focusRow(visibleRows($.list)[0]); }
221
- if (e.key === 'Escape' && $.search.value) { e.preventDefault(); $.search.value = ''; this.setFilter({query: ''}); }
331
+ if (e.key === 'Escape' && $.search!.value) { e.preventDefault(); $.search!.value = ''; this.setFilter({query: ''}); }
222
332
  }, sig);
223
333
  // The BPM handles: the label and the track follow the drag at once;
224
334
  // the list re-filters once it settles. A handle can't pass the other.
225
- const onBpm = (moved) => {
226
- const lo = Number($.bpmMin.value), hi = Number($.bpmMax.value);
335
+ const onBpm = (moved: HTMLInputElement) => {
336
+ const lo = Number($.bpmMin!.value), hi = Number($.bpmMax!.value);
227
337
  if (lo > hi) moved.value = String(moved === $.bpmMin ? hi : lo);
228
- const f = bpmFilterFromRange(Number($.bpmMin.value), Number($.bpmMax.value), this._bpmExtent);
338
+ const f = bpmFilterFromRange(Number($.bpmMin!.value), Number($.bpmMax!.value), this._bpmExtent!);
229
339
  this._showBpm(f);
230
340
  clearTimeout(bpmTimer);
231
341
  bpmTimer = setTimeout(() => this.setFilter(f), BPM_DELAY);
232
342
  };
233
- $.bpmMin?.addEventListener('input', () => onBpm($.bpmMin), sig);
234
- $.bpmMax?.addEventListener('input', () => onBpm($.bpmMax), sig);
343
+ $.bpmMin?.addEventListener('input', () => onBpm($.bpmMin!), sig);
344
+ $.bpmMax?.addEventListener('input', () => onBpm($.bpmMax!), sig);
235
345
  $.bpmClear?.addEventListener('click', () => {
236
346
  clearTimeout(bpmTimer);
237
347
  this.setFilter({bpmMin: '', bpmMax: ''});
@@ -239,15 +349,15 @@ export class WaveformSounds {
239
349
 
240
350
  this.menus = new Menus(root, {
241
351
  signal: this._ctl.signal,
242
- onPick: (name, value) => (name === 'sort' ? this.setSort(value) : this.setFilter({[name]: value})),
352
+ onPick: (name, value) => (name === 'sort' ? this.setSort(value as SoundsSort) : this.setFilter({[name]: value})),
243
353
  });
244
354
 
245
355
  // Any OTHER player starting pauses the list (every WaveformPlayer's
246
356
  // play event bubbles to the document). The engine's singlePlay only
247
357
  // reaches players that also use singlePlay — a WaveformBar's player
248
358
  // doesn't, so without this the bar and the list could play at once.
249
- document.addEventListener('waveformplayer:play', (e) => {
250
- const player = e.detail?.player;
359
+ document.addEventListener('waveformplayer:play', (e: Event) => {
360
+ const player = (e as CustomEvent).detail?.player;
251
361
  if (player && player !== this.engine && this.playing) this.pause();
252
362
  }, sig);
253
363
  }
@@ -257,25 +367,25 @@ export class WaveformSounds {
257
367
  /**
258
368
  * Clicks: type chips, loops or one-shots, Show more, Clear, Loop, a touch tap on a waveform
259
369
  * (seek), and anywhere else on a row (play/pause).
260
- * @private
370
+ * @internal
261
371
  */
262
- _onClick(e) {
263
- const t = e.target;
264
- const chip = t.closest('[data-ws-type]');
372
+ _onClick(e: MouseEvent): void {
373
+ const t = e.target as Element;
374
+ const chip = t.closest<HTMLElement>('[data-ws-type]');
265
375
  if (chip) { this.setFilter({type: chip.dataset.wsType}); return; }
266
- const seg = t.closest('[data-ws-loop-filter]');
267
- if (seg) { this.setFilter({loop: seg.dataset.wsLoopFilter}); return; }
376
+ const seg = t.closest<HTMLElement>('[data-ws-loop-filter]');
377
+ if (seg) { this.setFilter({loop: seg.dataset.wsLoopFilter as SoundsLoopFilter}); return; }
268
378
  if (t.closest('[data-ws-more]')) { this.showMore(); return; }
269
379
  if (t.closest('[data-ws-clear]')) { this.clearFilters(); return; }
270
380
  if (t.closest('[data-ws-loop]')) { this.setLoop(!this.loop); return; }
271
- const wave = t.closest('.ws-wave');
381
+ const wave = t.closest<HTMLElement>('.ws-wave');
272
382
  if (wave) {
273
383
  // Touch seeks on the TAP (this click): its press may have been
274
384
  // the start of a scroll.
275
385
  if (this._lastPointer === 'touch') this._seekAt(wave, e.clientX);
276
386
  return;
277
387
  }
278
- const row = t.closest('[data-ws-index]');
388
+ const row = t.closest<HTMLElement>('[data-ws-index]');
279
389
  if (!row || t.closest('.ws-download')) return;
280
390
  this.toggle(Number(row.dataset.wsIndex));
281
391
  this._focusRowQuietly(row);
@@ -284,11 +394,11 @@ export class WaveformSounds {
284
394
  /**
285
395
  * Mouse and pen seek on PRESS, like every scrubber. Remembers the
286
396
  * pointer type for the click that follows.
287
- * @private
397
+ * @internal
288
398
  */
289
- _onPointerDown(e) {
399
+ _onPointerDown(e: PointerEvent): void {
290
400
  this._lastPointer = e.pointerType;
291
- const wave = e.target.closest('.ws-wave');
401
+ const wave = (e.target as Element).closest<HTMLElement>('.ws-wave');
292
402
  if (!wave || e.button !== 0 || e.pointerType === 'touch') return;
293
403
  e.preventDefault();
294
404
  this._seekAt(wave, e.clientX);
@@ -296,10 +406,10 @@ export class WaveformSounds {
296
406
 
297
407
  /**
298
408
  * Seek (or start) a row's sound where its waveform was pressed.
299
- * @private
409
+ * @internal
300
410
  */
301
- _seekAt(wave, clientX) {
302
- const row = wave.closest('[data-ws-index]');
411
+ _seekAt(wave: HTMLElement, clientX: number): void {
412
+ const row = wave.closest<HTMLElement>('[data-ws-index]')!;
303
413
  this._seekRow(Number(row.dataset.wsIndex), pointerFraction(clientX, wave.getBoundingClientRect()));
304
414
  this._focusRowQuietly(row);
305
415
  }
@@ -307,16 +417,16 @@ export class WaveformSounds {
307
417
  /**
308
418
  * Keys on the list: `/` focuses search; ↑/↓/Home/End move between rows
309
419
  * (auditioning while something plays); ←/→ seek the playing row.
310
- * @private
420
+ * @internal
311
421
  */
312
- _onKey(e) {
422
+ _onKey(e: KeyboardEvent): void {
313
423
  if (e.defaultPrevented || e.altKey || e.ctrlKey || e.metaKey) return;
314
- if (e.key === '/' && !isTyping(e.target) && this.$.search) {
424
+ if (e.key === '/' && !isTyping(e.target as Element | null) && this.$.search) {
315
425
  e.preventDefault();
316
426
  this.$.search.focus();
317
427
  return;
318
428
  }
319
- const row = e.target.closest?.('[data-ws-index]');
429
+ const row = (e.target as Element).closest?.<HTMLElement>('[data-ws-index]');
320
430
  if (!row) return;
321
431
 
322
432
  const index = Number(row.dataset.wsIndex);
@@ -339,10 +449,10 @@ export class WaveformSounds {
339
449
 
340
450
  /**
341
451
  * Focus a row's play button.
342
- * @private
452
+ * @internal
343
453
  */
344
- _focusRow(row) {
345
- row?.querySelector('.ws-play')?.focus();
454
+ _focusRow(row: HTMLElement | null | undefined): void {
455
+ row?.querySelector<HTMLElement>('.ws-play')?.focus();
346
456
  }
347
457
 
348
458
  /**
@@ -351,10 +461,10 @@ export class WaveformSounds {
351
461
  * on the title or waveform left focus on <body>, and Safari never
352
462
  * focuses a clicked button). No scroll jump, and no focus ring: the
353
463
  * browser shows none for a focus that follows a pointer.
354
- * @private
464
+ * @internal
355
465
  */
356
- _focusRowQuietly(row) {
357
- const btn = row?.querySelector('.ws-play');
466
+ _focusRowQuietly(row: HTMLElement | null | undefined): void {
467
+ const btn = row?.querySelector<HTMLElement>('.ws-play');
358
468
  if (btn && document.activeElement !== btn) btn.focus({preventScroll: true});
359
469
  }
360
470
 
@@ -363,23 +473,23 @@ export class WaveformSounds {
363
473
  /**
364
474
  * Draw row canvases as they scroll into view; redraw on resize and on
365
475
  * theme flips (the canvas can't follow CSS by itself).
366
- * @private
476
+ * @internal
367
477
  */
368
- _observe() {
478
+ _observe(): void {
369
479
  if (this.render.player !== 'inline' || typeof window === 'undefined') return;
370
480
  this._drawn = new Set();
371
481
  if ('IntersectionObserver' in window) {
372
482
  this._io = new IntersectionObserver((entries) => {
373
483
  for (const entry of entries) {
374
484
  if (!entry.isIntersecting) continue;
375
- const i = Number(entry.target.dataset.wsIndex);
376
- this._drawn.add(i);
485
+ const i = Number((entry.target as HTMLElement).dataset.wsIndex);
486
+ this._drawn!.add(i);
377
487
  this._drawRow(i);
378
488
  }
379
489
  }, {rootMargin: '200px 0px'});
380
- this.rows.forEach((r) => r && this._io.observe(r));
490
+ this.rows.forEach((r) => r && this._io!.observe(r));
381
491
  } else {
382
- this.rows.forEach((r, i) => r && this._drawn.add(i));
492
+ this.rows.forEach((r, i) => r && this._drawn!.add(i));
383
493
  }
384
494
  if ('ResizeObserver' in window) {
385
495
  let width = 0;
@@ -404,9 +514,9 @@ export class WaveformSounds {
404
514
  /**
405
515
  * Resolve the canvas colours (options, else the CSS custom properties)
406
516
  * and keep `--ws-surface` current unless the site set it.
407
- * @private
517
+ * @internal
408
518
  */
409
- _resolveColors() {
519
+ _resolveColors(): void {
410
520
  if (this._autoSurface || !getComputedStyle(this.container).getPropertyValue('--ws-surface').trim()) {
411
521
  this._autoSurface = true;
412
522
  this.container.style.removeProperty('--ws-surface');
@@ -420,9 +530,9 @@ export class WaveformSounds {
420
530
 
421
531
  /**
422
532
  * Draw one row's waveform (only once it has been on screen).
423
- * @private
533
+ * @internal
424
534
  */
425
- _drawRow(index) {
535
+ _drawRow(index: number | null | undefined): void {
426
536
  if (this.render.player !== 'inline' || index == null || !this._drawn?.has(index)) return;
427
537
  const row = this.rows[index];
428
538
  const canvas = row?.querySelector('canvas');
@@ -439,9 +549,9 @@ export class WaveformSounds {
439
549
 
440
550
  /**
441
551
  * Redraw every row drawn so far.
442
- * @private
552
+ * @internal
443
553
  */
444
- _redrawAll() {
554
+ _redrawAll(): void {
445
555
  this._drawn?.forEach((i) => this._drawRow(i));
446
556
  }
447
557
 
@@ -449,22 +559,22 @@ export class WaveformSounds {
449
559
 
450
560
  /**
451
561
  * Apply the filter and sort from the address (`urlState`).
452
- * @private
562
+ * @internal
453
563
  */
454
- _readUrl() {
564
+ _readUrl(): void {
455
565
  const keys = urlKeys(this.options.urlState);
456
566
  if (!keys || typeof location === 'undefined') return;
457
567
  const {filter, sort} = readUrlState(location.search, keys, facets(this.sounds), this._sorts);
458
- this.filter = {...this.filter, ...filter};
459
- if (sort) { this.sortBy = sort; this._sortSet = true; }
568
+ (this as Writable<WaveformSounds>).filter = {...this.filter, ...filter};
569
+ if (sort) { (this as Writable<WaveformSounds>).sortBy = sort as SoundsSort; this._sortSet = true; }
460
570
  }
461
571
 
462
572
  /**
463
573
  * Rewrite the address shortly after a change (replaceState: no history
464
574
  * entries).
465
- * @private
575
+ * @internal
466
576
  */
467
- _queueUrl() {
577
+ _queueUrl(): void {
468
578
  const keys = urlKeys(this.options.urlState);
469
579
  if (!keys || typeof location === 'undefined') return;
470
580
  clearTimeout(this._urlTimer);
@@ -478,7 +588,7 @@ export class WaveformSounds {
478
588
  /* ── Filtering, sorting, paging ───────────────────────────────────── */
479
589
 
480
590
  /** The sounds that pass the filter, in the current sort order. */
481
- get visible() {
591
+ get visible(): Sound[] {
482
592
  return sortSounds(this.sounds.filter((s) => matches(s, this.filter)), this.sortBy);
483
593
  }
484
594
 
@@ -486,30 +596,33 @@ export class WaveformSounds {
486
596
  * Change the filter (merged into the current one) and re-apply. Back to
487
597
  * the first page.
488
598
  *
489
- * @param {Partial<import('../../../index').SoundsFilter>} patch
599
+ * @param patch
490
600
  */
491
- setFilter(patch = {}) {
492
- this.filter = {...this.filter, ...patch};
601
+ // The public signature (as in 0.3.1's index.d.ts: `patch` required); the
602
+ // implementation's default stays, and an overload signature emits nothing.
603
+ setFilter(patch: Partial<SoundsFilter>): void;
604
+ setFilter(patch: Partial<SoundsFilter> = {}): void {
605
+ (this as Writable<WaveformSounds>).filter = {...this.filter, ...patch};
493
606
  this.limit = this._pageSize();
494
607
  this._syncControls();
495
608
  this._apply({resort: false});
496
609
  }
497
610
 
498
611
  /** Reset every filter (the sort stays). */
499
- clearFilters() {
612
+ clearFilters(): void {
500
613
  this.setFilter(NO_FILTER);
501
614
  }
502
615
 
503
- /** @param {import('../../../index').SoundsSort} by */
504
- setSort(by) {
616
+ /** @param by */
617
+ setSort(by: SoundsSort): void {
505
618
  this._sortSet = true;
506
- this.sortBy = SORTS.includes(by) ? by : 'default';
619
+ (this as Writable<WaveformSounds>).sortBy = SORTS.includes(by) ? by : 'default';
507
620
  this.menus?.setValue('sort', this.sortBy);
508
621
  this._apply({resort: true});
509
622
  }
510
623
 
511
624
  /** Reveal the next page of results. */
512
- showMore() {
625
+ showMore(): void {
513
626
  if (this.limit === Infinity) return;
514
627
  this.limit += this.render.pageSize;
515
628
  this._apply({resort: false});
@@ -517,18 +630,18 @@ export class WaveformSounds {
517
630
 
518
631
  /**
519
632
  * Rows per page (Infinity when paging is off).
520
- * @private
633
+ * @internal
521
634
  */
522
- _pageSize() {
635
+ _pageSize(): number {
523
636
  return this.render.pageSize > 0 ? this.render.pageSize : Infinity;
524
637
  }
525
638
 
526
639
  /**
527
640
  * Show the current filter and sort in the controls (they can be set from
528
641
  * code or the address, not only by the controls themselves).
529
- * @private
642
+ * @internal
530
643
  */
531
- _syncControls() {
644
+ _syncControls(): void {
532
645
  const $ = this.$, f = this.filter;
533
646
  if (!$) return;
534
647
  if ($.search && $.search.value !== f.query) $.search.value = f.query;
@@ -549,9 +662,9 @@ export class WaveformSounds {
549
662
  * Show a BPM filter in its menu: the button label, the panel's readout,
550
663
  * the filled part of the track, and which handle sits on top (the one
551
664
  * that can still move, when they meet).
552
- * @private
665
+ * @internal
553
666
  */
554
- _showBpm(f) {
667
+ _showBpm(f: {bpmMin?: string | number, bpmMax?: string | number}): void {
555
668
  const $ = this.$, extent = this._bpmExtent;
556
669
  if (!$?.bpmRange || !extent) return;
557
670
  const {lo, hi} = bpmRangeFromFilter(f, extent);
@@ -568,11 +681,11 @@ export class WaveformSounds {
568
681
  * Lay the rows out for the current filter, sort and page: order, hide,
569
682
  * "Show more", the empty state and the count. Then report it.
570
683
  *
571
- * @param {{resort: boolean}} opts - Reorder the rows even if the sort
684
+ * @param opts - Reorder the rows even if the sort
572
685
  * hasn't changed.
573
- * @private
686
+ * @internal
574
687
  */
575
- _apply({resort}) {
688
+ _apply({resort}: {resort: boolean}): void {
576
689
  const $ = this.$;
577
690
  if (!$) return;
578
691
  if (resort || this.sortBy !== this._lastSort) {
@@ -588,6 +701,8 @@ export class WaveformSounds {
588
701
  }
589
702
  if ($.empty) $.empty.hidden = shown.length > 0;
590
703
  if ($.count) $.count.textContent = countText(shown.length, this.sounds.length, this.strings);
704
+ // Nothing played yet: keep the cued sound one the list still shows.
705
+ if (this._cued && !this.playing) this._cueFirst();
591
706
  this._queueUrl();
592
707
  this._emit('filter', {visible: shown.length, total: this.sounds.length, filter: {...this.filter}, sort: this.sortBy});
593
708
  this.options.onFilter?.(shown, this);
@@ -599,11 +714,11 @@ export class WaveformSounds {
599
714
  * Resolve an index, id or sound to an index in `this.sounds`. No
600
715
  * target means the current sound, else the first visible one.
601
716
  *
602
- * @param {number|string|Object} [target]
603
- * @returns {number|null}
604
- * @private
717
+ * @param target
718
+ * @returns
719
+ * @internal
605
720
  */
606
- _indexOf(target) {
721
+ _indexOf(target?: number | string | Sound | null): number | null {
607
722
  if (target == null) return this.currentIndex ?? (this.visible[0] ? this.sounds.indexOf(this.visible[0]) : null);
608
723
  if (typeof target === 'number') return this.sounds[target] ? target : null;
609
724
  const i = typeof target === 'object' ? this.sounds.indexOf(target) : this.sounds.findIndex((s) => s.id === String(target));
@@ -612,11 +727,11 @@ export class WaveformSounds {
612
727
 
613
728
  /**
614
729
  * The WaveformPlayer class: `playerClass`, else the page's global.
615
- * @returns {Function|null}
616
- * @private
730
+ * @returns
731
+ * @internal
617
732
  */
618
- _playerClass() {
619
- return this.options.playerClass || (typeof window !== 'undefined' ? window.WaveformPlayer : null) || null;
733
+ _playerClass(): EngineClass | null {
734
+ return (this.options.playerClass || (typeof window !== 'undefined' ? (window as any).WaveformPlayer : null) || null) as EngineClass | null;
620
735
  }
621
736
 
622
737
  /**
@@ -625,12 +740,12 @@ export class WaveformSounds {
625
740
  * which would strip `ws-engine--strip` (and with it the docked styling).
626
741
  * Made here rather than in the markup so server-rendered HTML from any
627
742
  * version works.
628
- * @returns {HTMLElement}
629
- * @private
743
+ * @returns
744
+ * @internal
630
745
  */
631
- _engineMount() {
632
- const slot = this.$.engine;
633
- let mount = slot.querySelector(':scope > [data-ws-engine-mount]');
746
+ _engineMount(): HTMLElement {
747
+ const slot = this.$.engine!;
748
+ let mount = slot.querySelector<HTMLElement>(':scope > [data-ws-engine-mount]');
634
749
  if (!mount) {
635
750
  mount = document.createElement('div');
636
751
  mount.setAttribute('data-ws-engine-mount', '');
@@ -641,38 +756,39 @@ export class WaveformSounds {
641
756
 
642
757
  /**
643
758
  * Build the engine once (it holds no audio until a play).
644
- * @returns {Object|null} The engine, or null without a player class.
645
- * @private
759
+ * @returns The engine, or null without a player class.
760
+ * @internal
646
761
  */
647
- _ensureEngine() {
648
- if (this.engine) return this.engine;
762
+ _ensureEngine(): Engine | null {
763
+ if (this.engine) return this.engine as Engine;
649
764
  const Player = this._playerClass();
650
765
  if (!Player) {
651
766
  console.error(`${LOG} @arraypress/waveform-player is required: load it before playing (or pass playerClass).`);
652
767
  return null;
653
768
  }
654
- this.engine = new Player(this._engineMount(), engineOptions(this.options.playerOptions, this.render.player, {
769
+ (this as Writable<WaveformSounds>).engine = new Player(this._engineMount(), engineOptions(this.options.playerOptions, this.render.player, {
655
770
  onLoad: () => this._onEngineLoad(),
656
771
  onPlay: () => this._setPlaying(true),
657
772
  onPause: () => this._setPlaying(false),
658
773
  onEnd: () => this._onEnd(),
659
- onTimeUpdate: (time, duration) => this._onTime(time, duration),
660
- onError: (err) => this._onEngineError(err),
774
+ onTimeUpdate: (time: number, duration: number) => this._onTime(time, duration),
775
+ onError: (err: unknown) => this._onEngineError(err),
661
776
  }));
662
- return this.engine;
777
+ return this.engine as Engine;
663
778
  }
664
779
 
665
780
  /**
666
781
  * Play a sound (by index, id or sound object), or resume the current
667
782
  * one. Before the list is built the call waits for it.
668
783
  *
669
- * @param {number|string|Object} [target]
670
- * @param {{at?: number}} [opts] - `at`: start position 0..1.
784
+ * @param target
785
+ * @param opts - `at`: start position 0..1.
671
786
  */
672
- play(target, opts = {}) {
787
+ play(target?: number | string | Sound, opts: {at?: number} = {}): void {
673
788
  if (!this.$) { this.ready.then(() => { if (!this.destroyed) this.play(target, opts); }); return; }
674
789
  const index = this._indexOf(target);
675
790
  if (index == null) return;
791
+ this._cued = false;
676
792
  const engine = this._ensureEngine();
677
793
  if (!engine) return;
678
794
  if (index === this.currentIndex && engine.audio?.src) {
@@ -687,19 +803,39 @@ export class WaveformSounds {
687
803
  if (previous != null) this._paintRow(previous);
688
804
  this._paintRow(index);
689
805
  const sound = this.sounds[index];
690
- engine.loadTrack(sound.url, sound.title, sound.type || null, {waveform: enginePeaks(sound, this.render.player), autoplay: true});
806
+ engine.loadTrack(sound.url, sound.title, sound.type || null, engineTrack(sound, this.render.player, true));
807
+ }
808
+
809
+ /**
810
+ * Strip layout: load the first sound the list shows into the docked
811
+ * player WITHOUT playing it, so the player shows a title and waveform
812
+ * (and its play button plays that sound) instead of an empty frame.
813
+ * Only metadata is fetched — the browser default for any `<audio>`.
814
+ * The row isn't marked current until it plays.
815
+ * @internal
816
+ */
817
+ _cueFirst(): void {
818
+ const engine = this.engine as Engine | null;
819
+ const first = this.visible[0];
820
+ if (!engine || !first) return;
821
+ const index = this.sounds.indexOf(first);
822
+ if (index === this.currentIndex) return;
823
+ this.currentIndex = index;
824
+ this.progress = 0;
825
+ this._cued = true;
826
+ engine.loadTrack(first.url, first.title, first.type || null, engineTrack(first, 'strip', false));
691
827
  }
692
828
 
693
829
  /** Pause the current sound. */
694
- pause() {
695
- if (this.engine && this.playing) this.engine.pause();
830
+ pause(): void {
831
+ if (this.engine && this.playing) (this.engine as Engine).pause();
696
832
  }
697
833
 
698
834
  /**
699
835
  * The current sound plays/pauses; another sound starts.
700
- * @param {number|string|Object} [target]
836
+ * @param target
701
837
  */
702
- toggle(target) {
838
+ toggle(target?: number | string | Sound): void {
703
839
  const index = this._indexOf(target);
704
840
  if (index == null) return;
705
841
  if (index === this.currentIndex && this.playing) this.pause();
@@ -707,22 +843,23 @@ export class WaveformSounds {
707
843
  }
708
844
 
709
845
  /** Play the next visible sound (no wrap at the end). */
710
- next() { this._step(1); }
846
+ next(): void { this._step(1); }
711
847
 
712
848
  /** Play the previous visible sound. */
713
- previous() { this._step(-1); }
849
+ previous(): void { this._step(-1); }
714
850
 
715
851
  /**
716
852
  * Play the visible sound `dir` places away, revealing it if it's past
717
853
  * the current page.
718
854
  *
719
- * @param {1|-1} dir
720
- * @returns {boolean} Whether there was one.
721
- * @private
855
+ * @param dir
856
+ * @returns Whether there was one.
857
+ * @internal
722
858
  */
723
- _step(dir) {
859
+ _step(dir: 1 | -1): boolean {
724
860
  const shown = this.visible;
725
- const at = this.currentIndex == null ? -1 : shown.indexOf(this.sounds[this.currentIndex]);
861
+ // A cued sound counts as nothing played: next() starts with it.
862
+ const at = this.currentIndex == null || this._cued ? -1 : shown.indexOf(this.sounds[this.currentIndex]);
726
863
  const target = shown[at + dir];
727
864
  if (!target) return false;
728
865
  const limit = limitToReveal(this.limit, at + dir);
@@ -735,9 +872,9 @@ export class WaveformSounds {
735
872
  * Loop the current sound (auditioning a loop is the common case). When
736
873
  * the list marks its loops (`loop: true` on any sound), only those
737
874
  * repeat: a one-shot always plays once.
738
- * @param {boolean} on
875
+ * @param on
739
876
  */
740
- setLoop(on) {
877
+ setLoop(on: boolean): void {
741
878
  this._loopSet = true;
742
879
  this.loop = !!on;
743
880
  this._setLoop(this.loop);
@@ -745,54 +882,54 @@ export class WaveformSounds {
745
882
 
746
883
  /**
747
884
  * Apply the loop state to the toggle and the engine.
748
- * @private
885
+ * @internal
749
886
  */
750
- _setLoop(on) {
887
+ _setLoop(on: boolean): void {
751
888
  this.$?.loop?.setAttribute('aria-pressed', String(on));
752
- if (this.engine?.audio) this.engine.audio.loop = this._repeats();
889
+ if ((this.engine as Engine | null)?.audio) (this.engine as Engine).audio!.loop = this._repeats();
753
890
  }
754
891
 
755
892
  /**
756
893
  * Should the current sound repeat? The Loop toggle is on, and either
757
894
  * the list doesn't say which sounds are loops or this one is.
758
- * @private
895
+ * @internal
759
896
  */
760
- _repeats() {
897
+ _repeats(): boolean {
761
898
  if (!this.loop) return false;
762
899
  const marksLoops = this.sounds.some((s) => s.loop);
763
- return !marksLoops || !!this.sounds[this.currentIndex]?.loop;
900
+ return !marksLoops || !!this.sounds[this.currentIndex!]?.loop;
764
901
  }
765
902
 
766
903
  /**
767
904
  * Seek a row's sound to `fraction`; a row that isn't current starts
768
905
  * there. Before the duration is known the seek waits for it.
769
- * @private
906
+ * @internal
770
907
  */
771
- _seekRow(index, fraction) {
908
+ _seekRow(index: number, fraction: number): void {
772
909
  if (index !== this.currentIndex || !this.engine) { this.play(index, {at: fraction}); return; }
773
- const duration = this.engine.audio?.duration;
774
- if (!Number.isFinite(duration) || duration <= 0) { this._pendingSeek = fraction; return; }
775
- this.engine.seekTo(fraction * duration);
910
+ const duration = (this.engine as Engine).audio?.duration;
911
+ if (!Number.isFinite(duration) || duration! <= 0) { this._pendingSeek = fraction; return; }
912
+ (this.engine as Engine).seekTo(fraction * duration!);
776
913
  this.progress = fraction;
777
914
  this._paintRow(index);
778
- if (!this.playing) this.engine.play();
915
+ if (!this.playing) (this.engine as Engine).play();
779
916
  }
780
917
 
781
918
  /**
782
919
  * The engine loaded a sound: apply the loop, borrow decoded peaks for a
783
920
  * row that had none, and land a pending seek.
784
- * @private
921
+ * @internal
785
922
  */
786
- _onEngineLoad() {
787
- if (this.engine?.audio) this.engine.audio.loop = this._repeats();
788
- const sound = this.sounds[this.currentIndex];
789
- if (sound && !sound.peaks && this.engine?.waveformData?.length) {
790
- sound.peaks = resample(this.engine.waveformData, 96);
923
+ _onEngineLoad(): void {
924
+ if ((this.engine as Engine | null)?.audio) (this.engine as Engine).audio!.loop = this._repeats();
925
+ 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);
791
928
  this._drawRow(this.currentIndex);
792
929
  }
793
- const duration = this.engine?.audio?.duration;
794
- if (this._pendingSeek != null && Number.isFinite(duration) && duration > 0) {
795
- this.engine.seekTo(this._pendingSeek * duration);
930
+ const duration = (this.engine as Engine | null)?.audio?.duration;
931
+ if (this._pendingSeek != null && Number.isFinite(duration) && duration! > 0) {
932
+ (this.engine as Engine).seekTo(this._pendingSeek * duration!);
796
933
  this.progress = this._pendingSeek;
797
934
  this._pendingSeek = null;
798
935
  }
@@ -800,14 +937,14 @@ export class WaveformSounds {
800
937
 
801
938
  /**
802
939
  * Playback progress: repaint the current row, once per frame.
803
- * @private
940
+ * @internal
804
941
  */
805
- _onTime(time, duration) {
942
+ _onTime(time: number, duration: number): void {
806
943
  if (this.currentIndex == null || !duration) return;
807
944
  if (this._pendingSeek != null) {
808
945
  const fraction = this._pendingSeek;
809
946
  this._pendingSeek = null;
810
- this.engine.seekTo(fraction * duration);
947
+ (this.engine as Engine).seekTo(fraction * duration);
811
948
  return;
812
949
  }
813
950
  this.progress = Math.min(Math.max(time / duration, 0), 1);
@@ -815,16 +952,16 @@ export class WaveformSounds {
815
952
  this._raf = requestAnimationFrame(() => {
816
953
  this._raf = 0;
817
954
  this._drawRow(this.currentIndex);
818
- this.rows[this.currentIndex]?.querySelector('.ws-wave')?.setAttribute('aria-valuenow', String(Math.round(this.progress * 100)));
955
+ this.rows[this.currentIndex!]?.querySelector('.ws-wave')?.setAttribute('aria-valuenow', String(Math.round(this.progress * 100)));
819
956
  });
820
957
  }
821
958
 
822
959
  /**
823
960
  * A sound finished: report it, then auto-advance or settle.
824
- * @private
961
+ * @internal
825
962
  */
826
- _onEnd() {
827
- const sound = this.sounds[this.currentIndex];
963
+ _onEnd(): void {
964
+ const sound = this.sounds[this.currentIndex!];
828
965
  this._emit('end', {sound, index: this.currentIndex});
829
966
  this.options.onEnd?.(sound, this);
830
967
  if (this.options.autoAdvance && this._step(1)) return;
@@ -834,11 +971,11 @@ export class WaveformSounds {
834
971
 
835
972
  /**
836
973
  * A sound failed to load or play: mark its row and report it.
837
- * @private
974
+ * @internal
838
975
  */
839
- _onEngineError(err) {
840
- this.rows[this.currentIndex]?.classList.add('is-error');
841
- this._emit('error', {error: err, sound: this.sounds[this.currentIndex], index: this.currentIndex});
976
+ _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});
842
979
  this.options.onError?.(err, this);
843
980
  }
844
981
 
@@ -846,11 +983,12 @@ export class WaveformSounds {
846
983
  * Record play/pause and repaint. Events fire only on a real change: at a
847
984
  * natural end the browser fires `pause` then `ended`, and `_onEnd()`
848
985
  * also settles the state — one pause event, not two.
849
- * @private
986
+ * @internal
850
987
  */
851
- _setPlaying(on) {
988
+ _setPlaying(on: boolean): void {
852
989
  const changed = this.playing !== on;
853
- this.playing = on;
990
+ (this as Writable<WaveformSounds>).playing = on;
991
+ if (on) this._cued = false; // the strip's own button played the cued sound
854
992
  const index = this.currentIndex;
855
993
  if (index == null) return;
856
994
  this._paintRow(index);
@@ -865,9 +1003,9 @@ export class WaveformSounds {
865
1003
 
866
1004
  /**
867
1005
  * A row's state classes, play-button label and waveform.
868
- * @private
1006
+ * @internal
869
1007
  */
870
- _paintRow(index) {
1008
+ _paintRow(index: number): void {
871
1009
  const row = this.rows[index];
872
1010
  if (!row) return;
873
1011
  const current = index === this.currentIndex;
@@ -879,7 +1017,7 @@ export class WaveformSounds {
879
1017
  btn.setAttribute('aria-pressed', String(on));
880
1018
  btn.setAttribute('aria-label', fill(on ? this.strings.pause : this.strings.play, {title: this.sounds[index].title}));
881
1019
  }
882
- const wave = row.querySelector('.ws-wave');
1020
+ const wave = row.querySelector<HTMLElement>('.ws-wave');
883
1021
  if (wave) {
884
1022
  wave.tabIndex = current ? 0 : -1;
885
1023
  if (!current) wave.setAttribute('aria-valuenow', '0');
@@ -891,15 +1029,16 @@ export class WaveformSounds {
891
1029
 
892
1030
  /**
893
1031
  * Emit a `waveformsounds:<name>` event carrying this instance.
894
- * @private
1032
+ * @internal
895
1033
  */
896
- _emit(name, detail = {}) {
1034
+ _emit(name: string, detail: Record<string, any> = {}): void {
897
1035
  emit(this.container, name, {...detail, instance: this});
898
1036
  }
899
1037
 
900
1038
  /** The sound playing (or paused) now, or null. */
901
- get current() {
902
- return this.currentIndex == null ? null : this.sounds[this.currentIndex];
1039
+ get current(): Sound | null {
1040
+ // A cued sound (strip, nothing played yet) isn't "current".
1041
+ return this.currentIndex == null || this._cued ? null : this.sounds[this.currentIndex];
903
1042
  }
904
1043
 
905
1044
  /**
@@ -909,7 +1048,7 @@ export class WaveformSounds {
909
1048
  * re-sorted, hidden or marked current — so to start again, re-render it
910
1049
  * rather than constructing a new instance over it.
911
1050
  */
912
- destroy() {
1051
+ destroy(): void {
913
1052
  if (this.destroyed) return;
914
1053
  this.destroyed = true;
915
1054
  this._ctl.abort();
@@ -918,8 +1057,8 @@ export class WaveformSounds {
918
1057
  this._mo?.disconnect();
919
1058
  if (this._raf) cancelAnimationFrame(this._raf);
920
1059
  clearTimeout(this._urlTimer);
921
- try { this.engine?.destroy(); } catch { /* engine already gone */ }
922
- this.engine = null;
1060
+ try { (this.engine as Engine | null)?.destroy(); } catch { /* engine already gone */ }
1061
+ (this as Writable<WaveformSounds>).engine = null;
923
1062
  this.$?.engine?.querySelector(':scope > [data-ws-engine-mount]')?.remove();
924
1063
  if (this._originalHTML != null) this.container.innerHTML = this._originalHTML;
925
1064
  if (this._addedClasses?.length) this.container.classList.remove(...this._addedClasses);
@@ -931,14 +1070,14 @@ export class WaveformSounds {
931
1070
  /**
932
1071
  * Initialise every `[data-waveform-sounds]` under `root` that isn't yet.
933
1072
  *
934
- * @param {ParentNode} [root=document]
935
- * @returns {WaveformSounds[]} The new instances.
1073
+ * @param root
1074
+ * @returns The new instances.
936
1075
  */
937
- static init(root = document) {
1076
+ static init(root: ParentNode = document): WaveformSounds[] {
938
1077
  if (typeof document === 'undefined') return [];
939
1078
  const scope = root || document;
940
- const els = [...(scope.matches?.('[data-waveform-sounds]') ? [scope] : []), ...scope.querySelectorAll('[data-waveform-sounds]')];
941
- const created = [];
1079
+ const els = [...((scope as Element).matches?.('[data-waveform-sounds]') ? [scope as HTMLElement] : []), ...scope.querySelectorAll<HTMLElement>('[data-waveform-sounds]')];
1080
+ const created: WaveformSounds[] = [];
942
1081
  for (const el of els) {
943
1082
  if (el.dataset.wsInitialized === 'true' || WaveformSounds.instances.has(el)) continue;
944
1083
  try { created.push(new WaveformSounds(el)); } catch (err) { console.error(`${LOG} Failed to initialise:`, err, el); }
@@ -948,17 +1087,17 @@ export class WaveformSounds {
948
1087
 
949
1088
  /**
950
1089
  * The instance on an element (or selector), if any.
951
- * @param {Element|string} el
952
- * @returns {WaveformSounds|null}
1090
+ * @param el
1091
+ * @returns
953
1092
  */
954
- static getInstance(el) {
1093
+ static getInstance(el: Element | string): WaveformSounds | null {
955
1094
  const node = typeof el === 'string' ? document.querySelector(el) : el;
956
1095
  return node ? WaveformSounds.instances.get(node) || null : null;
957
1096
  }
958
1097
 
959
1098
  /** Destroy instances whose element has left the document (after a
960
1099
  * client-side navigation). */
961
- static prune() {
1100
+ static prune(): void {
962
1101
  for (const [el, inst] of WaveformSounds.instances) if (!el.isConnected) inst.destroy();
963
1102
  }
964
1103
  }