wavesurfer.js 7.12.6 → 7.12.8

package/README.md

@@ -6,7 +6,9 @@
 
 <img width="626" alt="waveform screenshot" src="https://github.com/katspaugh/wavesurfer.js/assets/381895/05f03bed-800e-4fa1-b09a-82a39a1c62ce">
 
-**Gold sponsor 💖** [Closed Caption Creator](https://www.closedcaptioncreator.com)
+---
+### Gold Sponsor 💖 [Closed Caption Creator](https://www.closedcaptioncreator.com) – Professional Subtitle Editor
+---
 
 # Table of contents
 
@@ -35,7 +37,7 @@ Alternatively, insert a UMD script tag which exports the library as a global `Wa
 <script src="https://unpkg.com/wavesurfer.js@7"></script>
 ```
 
-Create a wavesurfer instance and pass various [options](http://wavesurfer.xyz/docs/options):
+Create a wavesurfer instance and pass various [options](https://wavesurfer.xyz/docs/api/options):
 ```js
 const wavesurfer = WaveSurfer.create({
   container: '#waveform',
@@ -59,13 +61,17 @@ TypeScript types are included in the package, so there's no need to install `@ty
 
 See more [examples](https://wavesurfer.xyz/examples).
 
+## Documentation
+
+See the [wavesurfer.js guide](https://wavesurfer.xyz/docs/) on our website for beginner-friendly, practical documentation covering common use cases, plugins, framework integration, and troubleshooting.
+
 ## API reference
 
-See the wavesurfer.js documentation on our website:
+The full generated API reference lives at [wavesurfer.xyz/docs/api](https://wavesurfer.xyz/docs/api/):
 
- * [methods](https://wavesurfer.xyz/docs/methods)
- * [options](http://wavesurfer.xyz/docs/options)
- * [events](http://wavesurfer.xyz/docs/events)
+ * [methods](https://wavesurfer.xyz/docs/api/methods)
+ * [options](https://wavesurfer.xyz/docs/api/options)
+ * [events](https://wavesurfer.xyz/docs/api/events)
 
 ## Plugins
 

package/dist/__tests__/dom.test.js

@@ -1,4 +1,20 @@
-import createElement from '../dom.js';
+import createElement, { isHTMLElement } from '../dom.js';
+describe('isHTMLElement', () => {
+    test('accepts elements from the current realm', () => {
+        expect(isHTMLElement(document.createElement('div'))).toBe(true);
+    });
+    test('accepts element-like objects from another realm (e.g. an iframe)', () => {
+        const foreign = { nodeType: 1, style: {} };
+        expect(isHTMLElement(foreign)).toBe(true);
+    });
+    test('rejects non-elements', () => {
+        expect(isHTMLElement(null)).toBe(false);
+        expect(isHTMLElement(undefined)).toBe(false);
+        expect(isHTMLElement('#container')).toBe(false);
+        expect(isHTMLElement({})).toBe(false);
+        expect(isHTMLElement(document.createTextNode('text'))).toBe(false);
+    });
+});
 describe('createElement', () => {
     test('creates DOM structure', () => {
         var _a;

package/dist/__tests__/drag-stream.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/drag-stream.test.js

@@ -0,0 +1,108 @@
+import { createDragStream } from '../reactive/drag-stream.js';
+import { effect } from '../reactive/store.js';
+describe('createDragStream', () => {
+    beforeAll(() => {
+        Object.defineProperty(window, 'matchMedia', {
+            writable: true,
+            value: jest.fn().mockReturnValue({
+                matches: false,
+                addListener: jest.fn(),
+                removeListener: jest.fn(),
+            }),
+        });
+        if (typeof window.PointerEvent === 'undefined') {
+            class FakePointerEvent extends MouseEvent {
+                constructor(type, props) {
+                    super(type, props);
+                }
+            }
+            // @ts-expect-error
+            window.PointerEvent = FakePointerEvent;
+            // @ts-expect-error
+            global.PointerEvent = FakePointerEvent;
+        }
+    });
+    const pointerEvent = (type, props) => {
+        var _a;
+        const e = new PointerEvent(type, props);
+        Object.defineProperty(e, 'pointerId', { value: (_a = props.pointerId) !== null && _a !== void 0 ? _a : 0, configurable: true });
+        return e;
+    };
+    const setup = () => {
+        const el = document.createElement('div');
+        document.body.appendChild(el);
+        jest.spyOn(el, 'getBoundingClientRect').mockReturnValue({
+            left: 0,
+            top: 0,
+            width: 100,
+            height: 100,
+            right: 100,
+            bottom: 100,
+            x: 0,
+            y: 0,
+            toJSON: () => { },
+        });
+        const stream = createDragStream(el, { threshold: 0 });
+        const events = [];
+        const unsubscribe = effect(() => {
+            const drag = stream.signal.value;
+            if (drag)
+                events.push(drag);
+        }, [stream.signal]);
+        return {
+            el,
+            events,
+            cleanup: () => {
+                unsubscribe();
+                stream.cleanup();
+                el.remove();
+            },
+        };
+    };
+    test('emits start, move and end on a simple drag', () => {
+        const { el, events, cleanup } = setup();
+        el.dispatchEvent(pointerEvent('pointerdown', { clientX: 10, clientY: 10, pointerId: 1 }));
+        document.dispatchEvent(pointerEvent('pointermove', { clientX: 20, clientY: 20, pointerId: 1 }));
+        document.dispatchEvent(pointerEvent('pointerup', { clientX: 20, clientY: 20, pointerId: 1 }));
+        expect(events.map((e) => e.type)).toEqual(['start', 'move', 'end']);
+        cleanup();
+    });
+    test('drag still works after a two-finger touch', () => {
+        const { el, events, cleanup } = setup();
+        // Two-finger tap: the second finger lifts before the first
+        el.dispatchEvent(pointerEvent('pointerdown', { clientX: 10, clientY: 10, pointerId: 1 }));
+        el.dispatchEvent(pointerEvent('pointerdown', { clientX: 50, clientY: 10, pointerId: 2 }));
+        document.dispatchEvent(pointerEvent('pointerup', { clientX: 50, clientY: 10, pointerId: 2 }));
+        document.dispatchEvent(pointerEvent('pointerup', { clientX: 10, clientY: 10, pointerId: 1 }));
+        // A subsequent single-finger drag should work
+        el.dispatchEvent(pointerEvent('pointerdown', { clientX: 10, clientY: 10, pointerId: 3 }));
+        document.dispatchEvent(pointerEvent('pointermove', { clientX: 30, clientY: 10, pointerId: 3 }));
+        document.dispatchEvent(pointerEvent('pointerup', { clientX: 30, clientY: 10, pointerId: 3 }));
+        expect(events.map((e) => e.type)).toEqual(['start', 'move', 'end']);
+        cleanup();
+    });
+    test('a second finger lifting does not end the first pointer drag', () => {
+        const { el, events, cleanup } = setup();
+        el.dispatchEvent(pointerEvent('pointerdown', { clientX: 10, clientY: 10, pointerId: 1 }));
+        document.dispatchEvent(pointerEvent('pointermove', { clientX: 20, clientY: 10, pointerId: 1 }));
+        // A second finger touches and lifts mid-drag
+        el.dispatchEvent(pointerEvent('pointerdown', { clientX: 50, clientY: 10, pointerId: 2 }));
+        document.dispatchEvent(pointerEvent('pointerup', { clientX: 50, clientY: 10, pointerId: 2 }));
+        // The first finger continues dragging and lifts
+        document.dispatchEvent(pointerEvent('pointermove', { clientX: 30, clientY: 10, pointerId: 1 }));
+        document.dispatchEvent(pointerEvent('pointerup', { clientX: 30, clientY: 10, pointerId: 1 }));
+        expect(events.map((e) => e.type)).toEqual(['start', 'move', 'move', 'end']);
+        cleanup();
+    });
+    test('only the dragging pointer moves the drag', () => {
+        const { el, events, cleanup } = setup();
+        el.dispatchEvent(pointerEvent('pointerdown', { clientX: 10, clientY: 10, pointerId: 1 }));
+        document.dispatchEvent(pointerEvent('pointermove', { clientX: 20, clientY: 10, pointerId: 1 }));
+        // Moves from an untracked pointer are ignored
+        document.dispatchEvent(pointerEvent('pointermove', { clientX: 90, clientY: 90, pointerId: 7 }));
+        document.dispatchEvent(pointerEvent('pointerup', { clientX: 30, clientY: 10, pointerId: 1 }));
+        expect(events.map((e) => e.type)).toEqual(['start', 'move', 'end']);
+        expect(events[1].x).toBe(20);
+        cleanup();
+    });
+});

package/dist/__tests__/draggable.test.js

@@ -21,6 +21,40 @@ describe('makeDraggable', () => {
             global.PointerEvent = FakePointerEvent;
         }
     });
+    test('drag still works after a two-finger touch', () => {
+        const el = document.createElement('div');
+        document.body.appendChild(el);
+        jest.spyOn(el, 'getBoundingClientRect').mockReturnValue({
+            left: 0,
+            top: 0,
+            width: 100,
+            height: 100,
+            right: 100,
+            bottom: 100,
+            x: 0,
+            y: 0,
+            toJSON: () => { },
+        });
+        const pointerEvent = (type, props) => {
+            const e = new PointerEvent(type, props);
+            Object.defineProperty(e, 'pointerId', { value: props.pointerId, configurable: true });
+            return e;
+        };
+        const onDrag = jest.fn();
+        const unsubscribe = makeDraggable(el, onDrag, undefined, undefined, 0);
+        // Two-finger tap: the second finger lifts before the first
+        el.dispatchEvent(pointerEvent('pointerdown', { clientX: 10, clientY: 10, pointerId: 1 }));
+        el.dispatchEvent(pointerEvent('pointerdown', { clientX: 50, clientY: 10, pointerId: 2 }));
+        document.dispatchEvent(pointerEvent('pointerup', { clientX: 50, clientY: 10, pointerId: 2 }));
+        document.dispatchEvent(pointerEvent('pointerup', { clientX: 10, clientY: 10, pointerId: 1 }));
+        // A subsequent single-finger drag should work
+        el.dispatchEvent(pointerEvent('pointerdown', { clientX: 10, clientY: 10, pointerId: 3 }));
+        document.dispatchEvent(pointerEvent('pointermove', { clientX: 30, clientY: 10, pointerId: 3 }));
+        document.dispatchEvent(pointerEvent('pointerup', { clientX: 30, clientY: 10, pointerId: 3 }));
+        expect(onDrag).toHaveBeenCalled();
+        unsubscribe();
+        el.remove();
+    });
     test('invokes callbacks on drag', () => {
         const el = document.createElement('div');
         document.body.appendChild(el);

package/dist/__tests__/hover.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/hover.test.js

@@ -0,0 +1,64 @@
+import HoverPlugin from '../plugins/hover.js';
+import { signal } from '../reactive/store.js';
+const createEmitter = () => {
+    const listeners = new Map();
+    return {
+        on: jest.fn((event, listener) => {
+            if (!listeners.has(event)) {
+                listeners.set(event, new Set());
+            }
+            listeners.get(event).add(listener);
+            return () => { var _a; return (_a = listeners.get(event)) === null || _a === void 0 ? void 0 : _a.delete(listener); };
+        }),
+    };
+};
+const createWaveSurfer = (container, durationValue) => {
+    const duration = signal(durationValue);
+    Object.defineProperty(container, 'getBoundingClientRect', {
+        configurable: true,
+        value: () => ({ left: 0, width: 100 }),
+    });
+    document.body.appendChild(container);
+    return {
+        duration,
+        wavesurfer: Object.assign(Object.assign({}, createEmitter()), { options: { progressColor: '#555' }, getDuration: jest.fn(() => duration.value), getState: jest.fn(() => ({ duration })), getWrapper: jest.fn(() => container) }),
+    };
+};
+describe('HoverPlugin', () => {
+    afterEach(() => {
+        document.body.innerHTML = '';
+        jest.clearAllMocks();
+    });
+    test('passes the current wavesurfer duration to formatTimeCallback', () => {
+        var _a;
+        const container = document.createElement('div');
+        const formatTimeCallback = jest.fn((seconds) => `${seconds}`);
+        const { wavesurfer } = createWaveSurfer(container, 0);
+        const plugin = HoverPlugin.create({ formatTimeCallback });
+        plugin._init(wavesurfer);
+        wavesurfer.getDuration.mockReturnValue(12);
+        container.dispatchEvent(new MouseEvent('pointermove', { bubbles: true, clientX: 50 }));
+        expect(formatTimeCallback).toHaveBeenCalledWith(6);
+        expect((_a = container.querySelector('[part="hover-label"]')) === null || _a === void 0 ? void 0 : _a.textContent).toBe('6');
+    });
+    test('keeps the hover line hidden after pointerleave when duration updates', () => {
+        const container = document.createElement('div');
+        const formatTimeCallback = jest.fn((seconds) => `${seconds}`);
+        const { duration, wavesurfer } = createWaveSurfer(container, 10);
+        const plugin = HoverPlugin.create({ formatTimeCallback });
+        plugin._init(wavesurfer);
+        container.dispatchEvent(new MouseEvent('pointermove', { bubbles: true, clientX: 50 }));
+        const hover = container.querySelector('[part="hover"]');
+        expect(hover === null || hover === void 0 ? void 0 : hover.style.opacity).toBe('1');
+        expect(formatTimeCallback).toHaveBeenCalledTimes(1);
+        container.dispatchEvent(new MouseEvent('pointerleave', { bubbles: true }));
+        expect(hover === null || hover === void 0 ? void 0 : hover.style.opacity).toBe('0');
+        // transform is cleared after the opacity transition ends, not immediately
+        hover === null || hover === void 0 ? void 0 : hover.dispatchEvent(new Event('transitionend'));
+        expect(hover === null || hover === void 0 ? void 0 : hover.style.transform).toBe('');
+        duration.set(12);
+        expect(hover === null || hover === void 0 ? void 0 : hover.style.opacity).toBe('0');
+        expect(hover === null || hover === void 0 ? void 0 : hover.style.transform).toBe('');
+        expect(formatTimeCallback).toHaveBeenCalledTimes(1);
+    });
+});

package/dist/__tests__/regions.test.js

@@ -17,6 +17,12 @@ const createWaveSurfer = (duration = 10, width = 100, scroll = 0) => {
     document.body.appendChild(wrapper);
     return Object.assign(Object.assign({}, emitter), { getDecodedData: jest.fn(() => ({ numberOfChannels: 1 })), getDuration: jest.fn(() => duration), getScroll: jest.fn(() => scroll), getWidth: jest.fn(() => width), getWrapper: jest.fn(() => wrapper) });
 };
+const mockRect = (element, rect) => {
+    Object.defineProperty(element, 'getBoundingClientRect', {
+        configurable: true,
+        value: jest.fn(() => (Object.assign(Object.assign({}, rect), { right: rect.left + rect.width, bottom: rect.top + rect.height, x: rect.left, y: rect.top, toJSON: () => rect }))),
+    });
+};
 describe('RegionsPlugin', () => {
     beforeEach(() => {
         jest.useFakeTimers();
@@ -58,4 +64,37 @@ describe('RegionsPlugin', () => {
         region.setOptions({ start: 8, end: 9 });
         expect((_e = region.element) === null || _e === void 0 ? void 0 : _e.parentElement).toBeNull();
     });
+    test('places a region in the first free row instead of summing all prior overlaps', () => {
+        var _a, _b, _c;
+        const wavesurfer = createWaveSurfer();
+        const plugin = RegionsPlugin.create();
+        plugin._init(wavesurfer);
+        const firstRegion = plugin.addRegion({ start: 0, end: 1, content: 'First' });
+        const secondRegion = plugin.addRegion({ start: 1, end: 2, content: 'Second' });
+        const thirdRegion = plugin.addRegion({ start: 2, end: 3, content: 'Third' });
+        mockRect(firstRegion.content, { left: 0, top: 0, width: 40, height: 10 });
+        mockRect(secondRegion.content, { left: 50, top: 0, width: 40, height: 10 });
+        mockRect(thirdRegion.content, { left: 30, top: 0, width: 40, height: 10 });
+        jest.runOnlyPendingTimers();
+        expect((_a = firstRegion.content) === null || _a === void 0 ? void 0 : _a.style.marginTop).toBe('0px');
+        expect((_b = secondRegion.content) === null || _b === void 0 ? void 0 : _b.style.marginTop).toBe('0px');
+        expect((_c = thirdRegion.content) === null || _c === void 0 ? void 0 : _c.style.marginTop).toBe('12px');
+    });
+    test('reflows shifted labels when another region moves away', () => {
+        var _a, _b, _c;
+        const wavesurfer = createWaveSurfer();
+        const plugin = RegionsPlugin.create();
+        plugin._init(wavesurfer);
+        const firstRegion = plugin.addRegion({ start: 0, end: 1, content: 'First' });
+        const secondRegion = plugin.addRegion({ start: 1, end: 2, content: 'Second' });
+        mockRect(firstRegion.content, { left: 0, top: 0, width: 40, height: 10 });
+        mockRect(secondRegion.content, { left: 20, top: 0, width: 40, height: 10 });
+        jest.runOnlyPendingTimers();
+        expect((_a = secondRegion.content) === null || _a === void 0 ? void 0 : _a.style.marginTop).toBe('12px');
+        mockRect(firstRegion.content, { left: 80, top: 0, width: 40, height: 10 });
+        firstRegion.onContentBlur();
+        jest.runOnlyPendingTimers();
+        expect((_b = firstRegion.content) === null || _b === void 0 ? void 0 : _b.style.marginTop).toBe('0px');
+        expect((_c = secondRegion.content) === null || _c === void 0 ? void 0 : _c.style.marginTop).toBe('0px');
+    });
 });

package/dist/__tests__/renderer.test.js

@@ -60,6 +60,10 @@ describe('Renderer', () => {
         container.remove();
         jest.clearAllMocks();
     });
+    test('parentFromOptionsContainer accepts an element from another realm (e.g. an iframe)', () => {
+        const foreign = { nodeType: 1, style: {} };
+        expect(renderer.parentFromOptionsContainer(foreign)).toBe(foreign);
+    });
     test('parentFromOptionsContainer returns element and throws', () => {
         expect(renderer.parentFromOptionsContainer(container)).toBe(container);
         expect(renderer.parentFromOptionsContainer('#root')).toBe(container);

package/dist/__tests__/wavesurfer.test.js

@@ -178,6 +178,19 @@ describe('WaveSurfer public methods', () => {
         expect(spy).toHaveBeenCalledWith(2);
         expect(ws.stopAtPosition).toBe(4);
     }));
+    test('pauses and clamps time to the exact stop position when playback overshoots it', () => __awaiter(void 0, void 0, void 0, function* () {
+        const ws = createWs();
+        const media = ws.getMediaElement();
+        Object.defineProperty(media, 'paused', { configurable: true, value: false });
+        yield ws.play(1, 2);
+        // Simulate the clock overshooting the stop position between timer ticks
+        media.currentTime = 2.013;
+        const timer = getTimer();
+        const tick = timer.on.mock.calls.find(([event]) => event === 'tick')[1];
+        tick();
+        expect(media.pause).toHaveBeenCalled();
+        expect(ws.getCurrentTime()).toBe(2);
+    }));
     test('playPause toggles play and pause', () => __awaiter(void 0, void 0, void 0, function* () {
         const ws = createWs();
         const media = ws.getMediaElement();

package/dist/__tests__/webaudio.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/webaudio.test.js

@@ -0,0 +1,223 @@
+import WebAudioPlayer from '../webaudio.js';
+// Mock Web Audio API
+function createMockAudioContext() {
+    let _currentTime = 0;
+    const gainNode = {
+        gain: { value: 1 },
+        connect: jest.fn(),
+        disconnect: jest.fn(),
+    };
+    let bufferSourceOnended = null;
+    const bufferSource = {
+        buffer: null,
+        playbackRate: { value: 1 },
+        connect: jest.fn(),
+        disconnect: jest.fn(),
+        start: jest.fn(),
+        stop: jest.fn(),
+        addEventListener: jest.fn(),
+        get onended() {
+            return bufferSourceOnended;
+        },
+        set onended(fn) {
+            bufferSourceOnended = fn;
+        },
+    };
+    const audioContext = {
+        get currentTime() {
+            return _currentTime;
+        },
+        set currentTime(v) {
+            _currentTime = v;
+        },
+        sampleRate: 44100,
+        destination: {},
+        createGain: jest.fn(() => gainNode),
+        createBufferSource: jest.fn(() => bufferSource),
+        decodeAudioData: jest.fn(),
+    };
+    return {
+        audioContext,
+        gainNode,
+        bufferSource,
+        triggerOnended: () => {
+            if (bufferSourceOnended)
+                bufferSourceOnended();
+        },
+    };
+}
+function createMockBuffer(duration) {
+    return { duration, numberOfChannels: 1, getChannelData: jest.fn(() => new Float32Array(0)) };
+}
+describe('WebAudioPlayer', () => {
+    describe('audio session playback mode', () => {
+        const originalAudioSession = Object.getOwnPropertyDescriptor(navigator, 'audioSession');
+        afterEach(() => {
+            if (originalAudioSession) {
+                Object.defineProperty(navigator, 'audioSession', originalAudioSession);
+            }
+            else {
+                delete navigator.audioSession;
+            }
+            jest.restoreAllMocks();
+        });
+        test('sets navigator.audioSession.type to playback when available', () => {
+            const { audioContext } = createMockAudioContext();
+            const audioSession = { type: 'ambient' };
+            Object.defineProperty(navigator, 'audioSession', { configurable: true, value: audioSession });
+            new WebAudioPlayer(audioContext);
+            expect(audioSession.type).toBe('playback');
+        });
+        test('warns when setting navigator.audioSession.type fails', () => {
+            const { audioContext } = createMockAudioContext();
+            const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => undefined);
+            const audioSession = {
+                get type() {
+                    return 'ambient';
+                },
+                set type(_value) {
+                    throw new Error('nope');
+                },
+            };
+            Object.defineProperty(navigator, 'audioSession', { configurable: true, value: audioSession });
+            new WebAudioPlayer(audioContext);
+            expect(warnSpy).toHaveBeenCalledWith('Setting navigator.audioSession.type failed:', expect.objectContaining({ message: 'nope' }));
+        });
+    });
+    describe('onended and finish event', () => {
+        test('emits ended when buffer finishes naturally at duration', () => {
+            const { audioContext, triggerOnended } = createMockAudioContext();
+            const player = new WebAudioPlayer(audioContext);
+            const endedSpy = jest.fn();
+            player.on('ended', endedSpy);
+            player.buffer = createMockBuffer(10);
+            // Play
+            audioContext.currentTime = 100;
+            player.play();
+            // Simulate natural end: audioContext.currentTime has advanced by exactly the duration
+            audioContext.currentTime = 110; // 100 + 10 seconds of audio
+            triggerOnended();
+            expect(endedSpy).toHaveBeenCalledTimes(1);
+        });
+        test('emits ended when buffer finishes naturally and currentTime is slightly less than duration due to float precision', () => {
+            const { audioContext, triggerOnended } = createMockAudioContext();
+            const player = new WebAudioPlayer(audioContext);
+            const endedSpy = jest.fn();
+            player.on('ended', endedSpy);
+            player.buffer = createMockBuffer(10);
+            // Play
+            audioContext.currentTime = 100;
+            player.play();
+            // Simulate natural end with slight floating-point imprecision
+            // currentTime would be 0 + (109.999 - 100) * 1 = 9.999, which is < 10 (duration)
+            audioContext.currentTime = 109.999;
+            triggerOnended();
+            expect(endedSpy).toHaveBeenCalledTimes(1);
+        });
+        test('does not emit ended when paused programmatically (far from end)', () => {
+            const { audioContext, triggerOnended } = createMockAudioContext();
+            const player = new WebAudioPlayer(audioContext);
+            const endedSpy = jest.fn();
+            player.on('ended', endedSpy);
+            player.buffer = createMockBuffer(10);
+            // Play
+            audioContext.currentTime = 100;
+            player.play();
+            // Advance to mid-playback
+            audioContext.currentTime = 105;
+            // User pauses (sets this.paused = true synchronously)
+            player.pause();
+            // onended fires asynchronously after stop()
+            triggerOnended();
+            expect(endedSpy).not.toHaveBeenCalled();
+        });
+        test('does not emit ended when stopAt stops before end of audio', () => {
+            const { audioContext, triggerOnended } = createMockAudioContext();
+            const player = new WebAudioPlayer(audioContext);
+            const endedSpy = jest.fn();
+            player.on('ended', endedSpy);
+            player.buffer = createMockBuffer(10);
+            // Play
+            audioContext.currentTime = 100;
+            player.play();
+            // Stop at 5 seconds
+            audioContext.currentTime = 100;
+            player.stopAt(5);
+            // Simulate buffer stopping at 5 seconds
+            audioContext.currentTime = 105;
+            triggerOnended();
+            // Should NOT emit ended because currentTime (5) is far from duration (10)
+            expect(endedSpy).not.toHaveBeenCalled();
+        });
+        test('emits ended when currentTime slightly exceeds duration', () => {
+            const { audioContext, triggerOnended } = createMockAudioContext();
+            const player = new WebAudioPlayer(audioContext);
+            const endedSpy = jest.fn();
+            player.on('ended', endedSpy);
+            player.buffer = createMockBuffer(10);
+            // Play
+            audioContext.currentTime = 100;
+            player.play();
+            // Simulate natural end: audioContext has advanced slightly past the duration
+            audioContext.currentTime = 110.005;
+            triggerOnended();
+            expect(endedSpy).toHaveBeenCalledTimes(1);
+        });
+        test('emits ended with non-default playback rate', () => {
+            const { audioContext, triggerOnended } = createMockAudioContext();
+            const player = new WebAudioPlayer(audioContext);
+            const endedSpy = jest.fn();
+            player.on('ended', endedSpy);
+            player.buffer = createMockBuffer(10);
+            player._playbackRate = 2;
+            // Play
+            audioContext.currentTime = 100;
+            player.play();
+            // At 2x, 10s audio takes 5s real time
+            // currentTime = 0 + (104.999 - 100) * 2 = 9.998, which is < 10 but within tolerance
+            audioContext.currentTime = 104.999;
+            triggerOnended();
+            expect(endedSpy).toHaveBeenCalledTimes(1);
+        });
+        test('stopAt schedules the stop scaled by playback rate', () => {
+            const { audioContext, bufferSource } = createMockAudioContext();
+            const player = new WebAudioPlayer(audioContext);
+            player.buffer = createMockBuffer(10);
+            player._playbackRate = 2;
+            audioContext.currentTime = 100;
+            player.play();
+            // At 2x rate, stopping at media time 5 takes only 2.5s of real time
+            player.stopAt(5);
+            expect(bufferSource.stop).toHaveBeenCalledWith(102.5);
+        });
+        test('stopAt reports exactly the stop position after the buffer ends', () => {
+            var _a;
+            const { audioContext, bufferSource } = createMockAudioContext();
+            const player = new WebAudioPlayer(audioContext);
+            player.buffer = createMockBuffer(10);
+            audioContext.currentTime = 100;
+            player.play();
+            player.stopAt(5);
+            // The 'ended' event fires with some latency after the actual stop
+            audioContext.currentTime = 105.03;
+            const endedListener = (_a = bufferSource.addEventListener.mock.calls.find(([type]) => type === 'ended')) === null || _a === void 0 ? void 0 : _a[1];
+            endedListener === null || endedListener === void 0 ? void 0 : endedListener();
+            expect(player.currentTime).toBe(5);
+        });
+        test('does not emit ended when currentTime is beyond tolerance threshold from duration', () => {
+            const { audioContext, triggerOnended } = createMockAudioContext();
+            const player = new WebAudioPlayer(audioContext);
+            const endedSpy = jest.fn();
+            player.on('ended', endedSpy);
+            player.buffer = createMockBuffer(10);
+            // Play
+            audioContext.currentTime = 100;
+            player.play();
+            // Simulate stopAt scenario where currentTime is 0.02s before duration (beyond 0.01s tolerance)
+            // currentTime = 0 + (109.98 - 100) * 1 = 9.98, duration - currentTime = 0.02 >= 0.01
+            audioContext.currentTime = 109.98;
+            triggerOnended();
+            expect(endedSpy).not.toHaveBeenCalled();
+        });
+    });
+});

package/dist/dom.d.ts

@@ -10,4 +10,9 @@ export declare function createElement(tagName: string, content: TreeNode & {
     xmlns: string;
 }, container?: Node): SVGElement;
 export declare function createElement(tagName: string, content?: TreeNode, container?: Node): HTMLElement;
+/**
+ * Check if a value is an HTML element, including elements from other realms
+ * (e.g. an iframe), for which `instanceof HTMLElement` returns false
+ */
+export declare function isHTMLElement(value: unknown): value is HTMLElement;
 export default createElement;

package/dist/dom.js

@@ -33,4 +33,16 @@ export function createElement(tagName, content, container) {
     container === null || container === void 0 ? void 0 : container.appendChild(el);
     return el;
 }
+/**
+ * Check if a value is an HTML element, including elements from other realms
+ * (e.g. an iframe), for which `instanceof HTMLElement` returns false
+ */
+export function isHTMLElement(value) {
+    if (value instanceof HTMLElement)
+        return true;
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.nodeType === Node.ELEMENT_NODE &&
+        typeof value.style === 'object');
+}
 export default createElement;