upnext-adapter-browser 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,152 @@
+# upnext-adapter-browser
+
+[![npm](https://img.shields.io/npm/v/upnext-adapter-browser)](https://www.npmjs.com/package/upnext-adapter-browser)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/tothienbao6a0/upnext/blob/main/LICENSE)
+
+Plays audio through a media element you control, for
+[**upnext-core**](https://www.npmjs.com/package/upnext-core) — in a browser, an
+Electron renderer, or a webview.
+
+`upnext-core` has always claimed it runs anywhere JavaScript does. Until this
+package, the only adapter that could make a sound shelled out to `ffplay`, so a
+browser had a queue and no way to play it. This closes that.
+
+## Install
+
+```bash
+npm i upnext-core upnext-adapter-browser
+```
+
+```ts
+import { Runtime } from 'upnext-core';
+import { MediaElementAdapter } from 'upnext-adapter-browser';
+
+const runtime = new Runtime({
+  adapters: [new MediaElementAdapter({ element: document.querySelector('audio')! })],
+});
+
+runtime.enqueue('https://traffic.megaphone.fm/episode.mp3');
+runtime.enqueue('https://example.com/track.m4a');
+await runtime.play();
+```
+
+The element can be a function, so a host can build its queue before it has a
+document:
+
+```ts
+new MediaElementAdapter({ element: () => new Audio() });
+```
+
+## What it plays — and what it refuses
+
+An `<audio>` element plays a **media stream**. It does not play a **page**. That
+distinction is the whole design of this adapter, because "the browser can play
+anything" is the intuition and it is wrong.
+
+| | score | |
+|---|:---:|---|
+| `https://…/episode.mp3` | **1** | a direct stream |
+| `https://…/ABC.mp3?updated=1712` | **1** | query strings don't hide the format |
+| `blob:` / `data:audio/…` | **1** | already bytes |
+| `file:///music/song.mp3` | 0.8 | Electron and webviews yes, plain web no |
+| `https://…/download/12345` | 0.2 | no extension — podcast enclosures look like this, so it's tried last |
+| `https://…/article.html` | **0** | names a format we can't decode |
+| **`youtube.com/watch?v=…`** | **0** | **a page, not a stream** |
+| `open.spotify.com/track/…` | **0** | a page — use `upnext-adapter-spotify` |
+| `soundcloud.com`, `bandcamp.com`, `vimeo.com`, … | **0** | pages |
+
+Those refusals are deliberate and explicit. Handing an element a YouTube watch
+URL gets you a lump of HTML and a decode error — and a queue full of things that
+fail at the last moment is worse than one that admitted up front it couldn't
+take them. Scoring zero sends the entry to another adapter, or fails it
+honestly.
+
+Making those work needs a page-level integration — YouTube's IFrame player, a
+SoundCloud widget, a stream extractor — which is a different adapter with
+different terms of service, not a cleverer regex here.
+
+If your element has been taught extra formats (hls.js, a custom source
+extension), say so:
+
+```ts
+new MediaElementAdapter({ element, extraExtensions: ['.dsf'] });
+```
+
+## It does not touch tabs you already have open
+
+This adapter **owns a player**. It does not reach into pages the user has open.
+
+Commandeering somebody's YouTube tab needs a browser extension, and it's a
+different feature with a different risk profile — *pausing whatever is playing*
+is a control feature, where *queueing* needs a player you can hand things to.
+You cannot queue into a stranger's tab.
+
+## Capabilities
+
+```ts
+{
+  endOfTrack:      'event',          // the element's `ended` — no polling, no timers
+  position:        'authoritative',  // currentTime, not a guess
+  seek: true, pause: true, volume: true,
+  search:          false,            // it plays a URL it is handed
+  externalControl: false,            // nobody else has a handle on this element
+}
+```
+
+This is the fully-controlled end of the capability spectrum — the opposite of
+`upnext-adapter-spotify`, where a human can hit next on their phone.
+
+Blocked autoplay is reported as a failure rather than swallowed, so the runtime
+falls through to a source that can actually make sound.
+
+## Across a process boundary
+
+In Electron the queue usually lives in the main process, and only a renderer can
+hold an `<audio>`. The adapter splits in two, over any transport you like:
+
+```ts
+// main process — where the Runtime is
+import { RemoteMediaAdapter } from 'upnext-adapter-browser';
+
+const runtime = new Runtime({
+  adapters: [new RemoteMediaAdapter({
+    channel: {
+      send: (m) => win.webContents.send('upnext', m),
+      subscribe: (fn) => {
+        const h = (_e, m) => fn(m);
+        ipcMain.on('upnext', h);
+        return () => ipcMain.off('upnext', h);
+      },
+    },
+  })],
+});
+```
+
+```ts
+// renderer — where the element is
+import { serveMediaElement } from 'upnext-adapter-browser';
+
+serveMediaElement(document.querySelector('audio')!, {
+  send: (m) => ipcRenderer.send('upnext', m),
+  subscribe: (fn) => {
+    const h = (_e, m) => fn(m);
+    ipcRenderer.on('upnext', h);
+    return () => ipcRenderer.off('upnext', h);
+  },
+});
+```
+
+The transport is deliberately unnamed — `ipcMain`/`ipcRenderer`, `postMessage`,
+a WebSocket, or two functions in a test. This package takes a `Channel` and asks
+no further questions.
+
+`serveMediaElement` drives a real `MediaElementAdapter`, so behaviour on the far
+side is the same class as the in-process case and cannot drift from it. `match`
+is evaluated locally and never crosses the wire — it's synchronous by contract,
+and what an element accepts is knowable from the URL. Requests are bounded by
+`requestTimeoutMs` (5s default), and a malformed command becomes an error reply
+rather than an exception thrown inside a renderer where nothing is listening.
+
+---
+
+Full docs: **https://github.com/tothienbao6a0/upnext** · Apache-2.0

package/dist/src/element.d.ts

@@ -0,0 +1,64 @@
+import type { Adapter, AdapterEvent, Binding, Capabilities, MediaRef } from 'upnext-core';
+/**
+ * The part of `HTMLMediaElement` this adapter actually uses.
+ *
+ * Deliberately tiny. A real `<audio>` satisfies it, so does a `<video>`, so
+ * does a webview's element behind a proxy — and so does a fake in a test, which
+ * is the point: none of this needs a browser to be exercised.
+ */
+export interface MediaElementLike {
+    src: string;
+    currentTime: number;
+    readonly duration: number;
+    volume: number;
+    readonly paused: boolean;
+    play(): Promise<void> | void;
+    pause(): void;
+    load?(): void;
+    addEventListener(type: string, listener: () => void): void;
+    removeEventListener(type: string, listener: () => void): void;
+}
+export interface MediaElementAdapterOptions {
+    id?: string;
+    /**
+     * The element to drive. A function is allowed so the element can be created
+     * lazily — browsers refuse to construct audio contexts before a user
+     * gesture, and a host may not have a document yet when it builds its queue.
+     */
+    element: MediaElementLike | (() => MediaElementLike);
+    /** Extra media types this element is known to handle, e.g. `['audio/flac']`. */
+    extraExtensions?: string[];
+}
+/**
+ * Plays audio through a media element you own.
+ *
+ * This sits at the fully-controlled end of the capability spectrum, and it is
+ * the adapter that makes the core's claim true: `upnext-core` has always said
+ * it runs anywhere JavaScript does, but until now the only thing that could
+ * make a sound shelled out to `ffplay`, so a browser or an Electron renderer
+ * had a queue and no way to play it.
+ *
+ * What it deliberately does **not** do is reach into pages the user already has
+ * open. Commandeering somebody's YouTube tab needs a browser extension and is a
+ * different feature with a different risk profile — this owns a player, which
+ * is what a *queue* needs. See the README for where that line is.
+ */
+export declare class MediaElementAdapter implements Adapter {
+    #private;
+    readonly id: string;
+    readonly capabilities: Capabilities;
+    constructor(options: MediaElementAdapterOptions);
+    match(ref: MediaRef): number;
+    resolve(ref: MediaRef): Promise<Binding | null>;
+    load(binding: Binding, opts?: {
+        startAtMs?: number;
+    }): Promise<void>;
+    play(): Promise<void>;
+    pause(): Promise<void>;
+    stop(): Promise<void>;
+    seek(positionMs: number): Promise<void>;
+    setVolume(volume: number): Promise<void>;
+    subscribe(listener: (event: AdapterEvent) => void): () => void;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=element.d.ts.map

package/dist/src/element.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element.d.ts","sourceRoot":"","sources":["../../src/element.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,OAAO,EACP,YAAY,EACZ,OAAO,EACP,YAAY,EACZ,QAAQ,EACT,MAAM,aAAa,CAAC;AAGrB;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC7B,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,CAAC,IAAI,IAAI,CAAC;IACd,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC3D,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAC/D;AAED,MAAM,WAAW,0BAA0B;IACzC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,OAAO,EAAE,gBAAgB,GAAG,CAAC,MAAM,gBAAgB,CAAC,CAAC;IACrD,gFAAgF;IAChF,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,mBAAoB,YAAW,OAAO;;IACjD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,QAAQ,CAAC,YAAY,EAAE,YAAY,CAajC;gBAUU,OAAO,EAAE,0BAA0B;IAK/C,KAAK,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM;IAItB,OAAO,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAS/C,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IASpE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBrB,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI;IAWxD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAqE/B"}

package/dist/src/element.js

@@ -0,0 +1,176 @@
+import { defaultCapabilities } from 'upnext-core';
+import { canPlay, describeSource, score } from './sources.js';
+/**
+ * Plays audio through a media element you own.
+ *
+ * This sits at the fully-controlled end of the capability spectrum, and it is
+ * the adapter that makes the core's claim true: `upnext-core` has always said
+ * it runs anywhere JavaScript does, but until now the only thing that could
+ * make a sound shelled out to `ffplay`, so a browser or an Electron renderer
+ * had a queue and no way to play it.
+ *
+ * What it deliberately does **not** do is reach into pages the user already has
+ * open. Commandeering somebody's YouTube tab needs a browser extension and is a
+ * different feature with a different risk profile — this owns a player, which
+ * is what a *queue* needs. See the README for where that line is.
+ */
+export class MediaElementAdapter {
+    id;
+    capabilities = {
+        ...defaultCapabilities,
+        // The element tells us. No polling, no duration timer, no guessing.
+        endOfTrack: 'event',
+        position: 'authoritative',
+        seek: true,
+        pause: true,
+        volume: true,
+        // Nothing to search — this plays a URL it is handed.
+        search: false,
+        // Nobody else has a handle on this element. If something else could pause
+        // it, that would be the host's own UI, and the host already knows.
+        externalControl: false,
+    };
+    #options;
+    #element = null;
+    #listeners = new Set();
+    #detach = [];
+    #binding = null;
+    /** Set while we are tearing down, so our own `pause` is not reported. */
+    #closing = false;
+    constructor(options) {
+        this.id = options.id ?? 'browser';
+        this.#options = options;
+    }
+    match(ref) {
+        return score(ref, this.#options.extraExtensions);
+    }
+    async resolve(ref) {
+        if (!ref.uri || !canPlay(ref.uri, this.#options.extraExtensions))
+            return null;
+        return {
+            adapterId: this.id,
+            nativeUri: ref.uri,
+            ref: { ...ref, title: ref.title ?? describeSource(ref.uri) },
+        };
+    }
+    async load(binding, opts) {
+        const element = this.#ensure();
+        this.#binding = binding;
+        element.src = binding.nativeUri;
+        element.load?.();
+        if (opts?.startAtMs)
+            element.currentTime = opts.startAtMs / 1000;
+    }
+    async play() {
+        const element = this.#ensure();
+        // `play()` rejects when a browser blocks autoplay. That is a real failure
+        // the runtime should hear about, not a warning to swallow — it falls
+        // through to the next source, which may well be one that can make sound.
+        await element.play();
+    }
+    async pause() {
+        this.#ensure().pause();
+    }
+    async stop() {
+        const element = this.#element;
+        if (!element)
+            return;
+        this.#closing = true;
+        try {
+            element.pause();
+            // Releases the network connection and stops buffering. Without it a long
+            // podcast keeps downloading behind whatever plays next.
+            element.src = '';
+            element.load?.();
+        }
+        finally {
+            this.#closing = false;
+            this.#binding = null;
+        }
+    }
+    async seek(positionMs) {
+        this.#ensure().currentTime = Math.max(0, positionMs) / 1000;
+    }
+    async setVolume(volume) {
+        this.#ensure().volume = Math.min(1, Math.max(0, volume));
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        // Wiring is deferred until someone is listening, so constructing an adapter
+        // never touches the DOM — a host can build its queue before it has one.
+        if (this.#listeners.size === 1)
+            this.#wire();
+        return () => {
+            this.#listeners.delete(listener);
+            if (this.#listeners.size === 0)
+                this.#unwire();
+        };
+    }
+    async dispose() {
+        await this.stop();
+        this.#unwire();
+        this.#listeners.clear();
+        this.#element = null;
+    }
+    // -- internals ------------------------------------------------------------
+    #ensure() {
+        if (!this.#element) {
+            const source = this.#options.element;
+            this.#element = typeof source === 'function' ? source() : source;
+        }
+        return this.#element;
+    }
+    #wire() {
+        const element = this.#ensure();
+        const on = (type, handler) => {
+            element.addEventListener(type, handler);
+            this.#detach.push(() => element.removeEventListener(type, handler));
+        };
+        on('ended', () => this.#emit({ type: 'ended' }));
+        on('timeupdate', () => {
+            const durationMs = toMs(element.duration);
+            this.#emit({
+                type: 'position',
+                positionMs: Math.round(element.currentTime * 1000),
+                ...(durationMs ? { durationMs } : {}),
+            });
+        });
+        on('loadedmetadata', () => {
+            const durationMs = toMs(element.duration);
+            if (durationMs) {
+                this.#emit({ type: 'position', positionMs: 0, durationMs });
+            }
+        });
+        on('play', () => this.#emit({ type: 'status', status: 'playing' }));
+        on('pause', () => {
+            // Our own teardown pauses the element; reporting that would tell the
+            // runtime the listener paused when in fact the track was being replaced.
+            if (this.#closing)
+                return;
+            this.#emit({ type: 'status', status: 'paused' });
+        });
+        on('error', () => {
+            this.#emit({
+                type: 'error',
+                code: 'media_error',
+                message: `could not play ${this.#binding?.nativeUri ?? 'the loaded source'}`,
+            });
+        });
+    }
+    #unwire() {
+        for (const off of this.#detach)
+            off();
+        this.#detach = [];
+    }
+    #emit(event) {
+        for (const listener of [...this.#listeners])
+            listener(event);
+    }
+}
+/** A media element reports `NaN` before metadata and `Infinity` for streams. */
+function toMs(seconds) {
+    if (!Number.isFinite(seconds) || seconds <= 0)
+        return undefined;
+    return Math.round(seconds * 1000);
+}
+//# sourceMappingURL=element.js.map

package/dist/src/element.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element.js","sourceRoot":"","sources":["../../src/element.ts"],"names":[],"mappings":"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"}

package/dist/src/index.d.ts

@@ -0,0 +1,6 @@
+export { MediaElementAdapter } from './element.js';
+export type { MediaElementLike, MediaElementAdapterOptions } from './element.js';
+export { RemoteMediaAdapter, serveMediaElement } from './remote.js';
+export type { Channel, RemoteMediaAdapterOptions } from './remote.js';
+export { canPlay, score as scoreSource, describeSource } from './sources.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAEjF,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACpE,YAAY,EAAE,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAEtE,OAAO,EAAE,OAAO,EAAE,KAAK,IAAI,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,4 @@
+export { MediaElementAdapter } from './element.js';
+export { RemoteMediaAdapter, serveMediaElement } from './remote.js';
+export { canPlay, score as scoreSource, describeSource } from './sources.js';
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAGnD,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGpE,OAAO,EAAE,OAAO,EAAE,KAAK,IAAI,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}