upnext-adapter-browser 0.1.0

package/dist/src/remote.d.ts

@@ -0,0 +1,65 @@
+import type { Adapter, AdapterEvent, Binding, Capabilities, MediaRef } from 'upnext-core';
+import { type MediaElementLike } from './element.js';
+/**
+ * Driving a media element that lives somewhere else.
+ *
+ * In an Electron app the queue runs in the main process and the only thing that
+ * can hold an `<audio>` is a renderer. In a web app the element may sit inside
+ * an iframe or a worker-owned document. Either way the adapter and the element
+ * are separated by a boundary that only passes messages.
+ *
+ * The transport is deliberately not named. A host that has `ipcMain`/`ipcRenderer`
+ * uses that; one with `postMessage` uses that; a test uses two functions and no
+ * boundary at all. This library takes a `Channel` and asks no further questions,
+ * the same way `upnext-adapter-process` takes a command and does not care what
+ * language is on the other end.
+ */
+export interface Channel {
+    send(message: unknown): void;
+    /** Returns an unsubscribe function. */
+    subscribe(listener: (message: unknown) => void): () => void;
+}
+export interface RemoteMediaAdapterOptions {
+    id?: string;
+    channel: Channel;
+    /** How long to wait for the far side before giving up. */
+    requestTimeoutMs?: number;
+    extraExtensions?: string[];
+}
+/** The side that lives with the `Runtime`. */
+export declare class RemoteMediaAdapter implements Adapter {
+    #private;
+    readonly id: string;
+    readonly capabilities: Capabilities;
+    constructor(options: RemoteMediaAdapterOptions);
+    init(): Promise<void>;
+    /**
+     * Evaluated locally, never over the wire. `match` is synchronous by contract
+     * and asking across a boundary on every resolution would be absurd — and
+     * unnecessary, since what a media element accepts is knowable from the URL.
+     */
+    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>;
+}
+/**
+ * The side that lives with the element. Call it once, wherever the DOM is.
+ *
+ * It drives a real `MediaElementAdapter`, so the behaviour on the far side of
+ * the boundary is not a reimplementation that can drift — it is the same class
+ * the in-process case uses.
+ */
+export declare function serveMediaElement(element: MediaElementLike | (() => MediaElementLike), channel: Channel, options?: {
+    id?: string;
+    extraExtensions?: string[];
+}): () => void;
+//# sourceMappingURL=remote.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../../src/remote.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,OAAO,EACP,YAAY,EACZ,OAAO,EACP,YAAY,EACZ,QAAQ,EACT,MAAM,aAAa,CAAC;AACrB,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAG1E;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,OAAO;IACtB,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,uCAAuC;IACvC,SAAS,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC7D;AAiCD,MAAM,WAAW,yBAAyB;IACxC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,8CAA8C;AAC9C,qBAAa,kBAAmB,YAAW,OAAO;;IAChD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,YAAY,eAAuB;gBAQhC,OAAO,EAAE,yBAAyB;IAKxC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;;OAIG;IACH,KAAK,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM;IAItB,OAAO,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAK/C,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAGpE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAGrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAGtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAGrB,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAGvC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI;IAKxD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAwC/B;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,gBAAgB,GAAG,CAAC,MAAM,gBAAgB,CAAC,EACpD,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;CAAO,GACxD,MAAM,IAAI,CAsBZ"}

package/dist/src/remote.js

@@ -0,0 +1,183 @@
+import { defaultCapabilities } from 'upnext-core';
+import { MediaElementAdapter } from './element.js';
+import { score } from './sources.js';
+/**
+ * Both ends run the same capabilities, because both ends are the same adapter —
+ * `serveMediaElement` drives a real `MediaElementAdapter`. There is no handshake
+ * to negotiate: a media element is a media element wherever it is sitting.
+ */
+const REMOTE_CAPABILITIES = {
+    ...defaultCapabilities,
+    endOfTrack: 'event',
+    position: 'authoritative',
+    seek: true,
+    pause: true,
+    volume: true,
+    search: false,
+    externalControl: false,
+};
+/** The side that lives with the `Runtime`. */
+export class RemoteMediaAdapter {
+    id;
+    capabilities = REMOTE_CAPABILITIES;
+    #options;
+    #listeners = new Set();
+    #pending = new Map();
+    #unsubscribe = null;
+    #nextId = 1;
+    constructor(options) {
+        this.id = options.id ?? 'browser';
+        this.#options = options;
+    }
+    async init() {
+        this.#unsubscribe ??= this.#options.channel.subscribe((message) => this.#receive(message));
+    }
+    /**
+     * Evaluated locally, never over the wire. `match` is synchronous by contract
+     * and asking across a boundary on every resolution would be absurd — and
+     * unnecessary, since what a media element accepts is knowable from the URL.
+     */
+    match(ref) {
+        return score(ref, this.#options.extraExtensions);
+    }
+    async resolve(ref) {
+        if (!ref.uri || this.match(ref) === 0)
+            return null;
+        return { adapterId: this.id, nativeUri: ref.uri, ref: { ...ref } };
+    }
+    async load(binding, opts) {
+        await this.#request('load', { binding, ...opts });
+    }
+    async play() {
+        await this.#request('play');
+    }
+    async pause() {
+        await this.#request('pause');
+    }
+    async stop() {
+        await this.#request('stop');
+    }
+    async seek(positionMs) {
+        await this.#request('seek', { positionMs });
+    }
+    async setVolume(volume) {
+        await this.#request('setVolume', { volume });
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    async dispose() {
+        for (const [, pending] of this.#pending)
+            clearTimeout(pending.timer);
+        this.#pending.clear();
+        this.#unsubscribe?.();
+        this.#unsubscribe = null;
+        this.#listeners.clear();
+    }
+    #request(method, params) {
+        void this.init();
+        const id = this.#nextId++;
+        const timeoutMs = this.#options.requestTimeoutMs ?? 5000;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#pending.delete(id);
+                reject(new Error(`${this.id}: ${method} timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.#pending.set(id, { resolve, reject, timer });
+            this.#options.channel.send({ id, method, params });
+        });
+    }
+    #receive(message) {
+        if (!message || typeof message !== 'object')
+            return;
+        if ('event' in message) {
+            const { event } = message;
+            for (const listener of [...this.#listeners])
+                listener(event);
+            return;
+        }
+        const reply = message;
+        const pending = this.#pending.get(reply.id);
+        if (!pending)
+            return;
+        this.#pending.delete(reply.id);
+        clearTimeout(pending.timer);
+        if (reply.error)
+            pending.reject(new Error(`${this.id}: ${reply.error}`));
+        else
+            pending.resolve();
+    }
+}
+/**
+ * The side that lives with the element. Call it once, wherever the DOM is.
+ *
+ * It drives a real `MediaElementAdapter`, so the behaviour on the far side of
+ * the boundary is not a reimplementation that can drift — it is the same class
+ * the in-process case uses.
+ */
+export function serveMediaElement(element, channel, options = {}) {
+    const adapter = new MediaElementAdapter({ element, ...options });
+    const offEvents = adapter.subscribe((event) => channel.send({ event }));
+    const offCommands = channel.subscribe((message) => {
+        if (!message || typeof message !== 'object' || !('method' in message))
+            return;
+        const command = message;
+        void run(adapter, command)
+            .then(() => channel.send({ id: command.id }))
+            .catch((err) => channel.send({
+            id: command.id,
+            error: err instanceof Error ? err.message : String(err),
+        }));
+    });
+    return () => {
+        offCommands();
+        offEvents();
+        void adapter.dispose();
+    };
+}
+/**
+ * Apply one command, checking what came across the boundary.
+ *
+ * These arrive as `unknown` from another process — a renderer that reloaded
+ * mid-flight, a host wiring the channel to the wrong window, a future version
+ * sending a field this one has never heard of. Validating here means a bad
+ * message becomes an error reply the runtime can fail over from, rather than a
+ * `TypeError` thrown inside somebody's renderer where nothing is listening.
+ */
+async function run(adapter, command) {
+    const params = (command.params ?? {});
+    switch (command.method) {
+        case 'load': {
+            const binding = params.binding;
+            if (!binding || typeof binding.nativeUri !== 'string') {
+                throw new Error('load requires a binding with a nativeUri');
+            }
+            const startAtMs = typeof params.startAtMs === 'number' ? params.startAtMs : undefined;
+            return adapter.load(binding, startAtMs === undefined ? undefined : { startAtMs });
+        }
+        case 'play':
+            return adapter.play();
+        case 'pause':
+            return adapter.pause();
+        case 'stop':
+            return adapter.stop();
+        case 'seek': {
+            const positionMs = params.positionMs;
+            if (typeof positionMs !== 'number' || !Number.isFinite(positionMs)) {
+                throw new Error('seek requires a finite positionMs');
+            }
+            return adapter.seek(positionMs);
+        }
+        case 'setVolume': {
+            const volume = params.volume;
+            if (typeof volume !== 'number' || !Number.isFinite(volume)) {
+                throw new Error('setVolume requires a finite volume');
+            }
+            return adapter.setVolume(volume);
+        }
+        default:
+            throw new Error(`unknown method ${String(command.method)}`);
+    }
+}
+//# sourceMappingURL=remote.js.map

package/dist/src/remote.js.map

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

package/dist/src/sources.d.ts

@@ -0,0 +1,14 @@
+import type { MediaRef } from 'upnext-core';
+export declare function canPlay(uri: string, extraExtensions?: string[]): boolean;
+/**
+ * How confident this element is that it can play the ref.
+ *
+ * A direct media URL scores 1. An `http(s)` URL with no recognisable extension
+ * scores low but non-zero — podcast enclosures are routinely extensionless
+ * redirects, and "try me last" is the honest answer for those: if it fails,
+ * the binder moves to the next source, which is exactly the machinery for it.
+ */
+export declare function score(ref: MediaRef, extraExtensions?: string[]): number;
+/** A short label for a URL, so a queue does not show a column of raw links. */
+export declare function describeSource(uri: string): string;
+//# sourceMappingURL=sources.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../../src/sources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AA0C5C,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAExE;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,QAAQ,EAAE,eAAe,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CA8BvE;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CASlD"}

package/dist/src/sources.js

@@ -0,0 +1,118 @@
+/**
+ * What a media element can and cannot be handed.
+ *
+ * The temptation with a browser adapter is to claim the web, because "the
+ * browser can play anything" feels true. It is not. An `<audio>` element plays
+ * a *media stream*; it does not play a *page*. Handing it a YouTube watch URL
+ * gets you a lump of HTML and a decode error, and the difference matters
+ * because a queue full of things that fail at the last moment is worse than one
+ * that admitted it could not take them.
+ */
+/** Container and codec extensions a media element will normally accept. */
+const PLAYABLE_EXTENSIONS = new Set([
+    '.mp3', '.m4a', '.m4b', '.aac', '.wav', '.flac', '.ogg', '.oga', '.opus',
+    '.weba', '.webm', '.mp4', '.m4v', '.mov', '.aiff', '.aif', '.caf',
+    // Adaptive manifests. Native only in Safari without a library, but a host
+    // that has attached hls.js to its element makes these work, and the element
+    // is the host's to configure.
+    '.m3u8', '.mpd',
+]);
+/**
+ * Pages that play media *inside* them, which is not the same as being media.
+ *
+ * Listed explicitly and scored zero rather than left to fall through the
+ * extension check, because these are exactly what somebody will try first. A
+ * silent zero sends the entry to another adapter or fails it honestly; a
+ * hopeful guess plays nothing and blames the file.
+ *
+ * Making these 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 smarter regex here.
+ */
+const PAGE_HOSTS = [
+    'youtube.com', 'youtu.be', 'music.youtube.com',
+    'open.spotify.com', 'music.apple.com',
+    'soundcloud.com', 'bandcamp.com', 'mixcloud.com',
+    'vimeo.com', 'twitch.tv',
+];
+export function canPlay(uri, extraExtensions) {
+    return score({ uri }, extraExtensions) > 0;
+}
+/**
+ * How confident this element is that it can play the ref.
+ *
+ * A direct media URL scores 1. An `http(s)` URL with no recognisable extension
+ * scores low but non-zero — podcast enclosures are routinely extensionless
+ * redirects, and "try me last" is the honest answer for those: if it fails,
+ * the binder moves to the next source, which is exactly the machinery for it.
+ */
+export function score(ref, extraExtensions) {
+    const uri = ref.uri;
+    if (!uri)
+        return 0;
+    // Anything the host has already turned into bytes is certain.
+    if (uri.startsWith('blob:'))
+        return 1;
+    if (uri.startsWith('data:audio/') || uri.startsWith('data:video/'))
+        return 1;
+    const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(uri)?.[1]?.toLowerCase();
+    const extension = extensionOf(uri);
+    const known = extension !== null && isKnown(extension, extraExtensions);
+    if (scheme === 'file') {
+        // Works in an Electron renderer and in a webview; a plain web page will be
+        // refused by the browser itself. Below a direct http URL, above a guess.
+        return known ? 0.8 : 0;
+    }
+    if (scheme !== 'http' && scheme !== 'https')
+        return 0;
+    if (isPage(uri))
+        return 0;
+    if (known)
+        return 1;
+    // A URL that *names* a format we do not handle is a no, not a maybe —
+    // `.html` and `.json` are not things to try hopefully and fail on.
+    if (extension !== null)
+        return 0;
+    // No extension at all. Podcast enclosures are routinely extensionless
+    // redirects, so this is worth trying once nothing better has offered.
+    return 0.2;
+}
+/** A short label for a URL, so a queue does not show a column of raw links. */
+export function describeSource(uri) {
+    try {
+        const url = new URL(uri);
+        const last = url.pathname.split('/').filter(Boolean).pop();
+        if (last)
+            return decodeURIComponent(last.replace(/\.[^.]+$/, ''));
+        return url.hostname;
+    }
+    catch {
+        return uri;
+    }
+}
+function isPage(uri) {
+    let host;
+    try {
+        host = new URL(uri).hostname.toLowerCase().replace(/^www\./, '');
+    }
+    catch {
+        return false;
+    }
+    return PAGE_HOSTS.some((page) => host === page || host.endsWith(`.${page}`));
+}
+/** The extension of the last path segment, or null when there isn't one. */
+function extensionOf(uri) {
+    // Query strings and fragments are stripped first: signed podcast URLs carry
+    // `?updated=...` after the extension and would otherwise never match.
+    const path = uri.split(/[?#]/)[0] ?? '';
+    const segment = path.slice(path.lastIndexOf('/') + 1);
+    const dot = segment.lastIndexOf('.');
+    // A leading dot is a hidden file, not an extension.
+    if (dot <= 0)
+        return null;
+    return segment.slice(dot).toLowerCase();
+}
+function isKnown(extension, extra) {
+    return PLAYABLE_EXTENSIONS.has(extension) || (extra?.includes(extension) ?? false);
+}
+//# sourceMappingURL=sources.js.map

package/dist/src/sources.js.map

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

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "upnext-adapter-browser",
+  "version": "0.1.0",
+  "description": "Play audio through a media element you control — in a browser, an Electron renderer, or a webview. Works across a process boundary too.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": { ".": "./dist/src/index.js" },
+  "files": ["dist/src", "src"],
+  "dependencies": { "upnext-core": "0.1.0" },
+  "engines": { "node": ">=20" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tothienbao6a0/upnext.git",
+    "directory": "packages/adapter-browser"
+  },
+  "homepage": "https://github.com/tothienbao6a0/upnext#readme",
+  "bugs": { "url": "https://github.com/tothienbao6a0/upnext/issues" },
+  "keywords": ["audio", "playback", "browser", "electron", "html5-audio", "upnext-adapter"]
+}

package/src/element.ts

@@ -0,0 +1,232 @@
+import { defaultCapabilities } from 'upnext-core';
+import type {
+  Adapter,
+  AdapterEvent,
+  Binding,
+  Capabilities,
+  MediaRef,
+} from 'upnext-core';
+import { canPlay, describeSource, score } from './sources.js';
+
+/**
+ * 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 class MediaElementAdapter implements Adapter {
+  readonly id: string;
+
+  readonly capabilities: 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: MediaElementAdapterOptions;
+  #element: MediaElementLike | null = null;
+  #listeners = new Set<(event: AdapterEvent) => void>();
+  #detach: Array<() => void> = [];
+  #binding: Binding | null = null;
+  /** Set while we are tearing down, so our own `pause` is not reported. */
+  #closing = false;
+
+  constructor(options: MediaElementAdapterOptions) {
+    this.id = options.id ?? 'browser';
+    this.#options = options;
+  }
+
+  match(ref: MediaRef): number {
+    return score(ref, this.#options.extraExtensions);
+  }
+
+  async resolve(ref: MediaRef): Promise<Binding | null> {
+    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: Binding, opts?: { startAtMs?: number }): Promise<void> {
+    const element = this.#ensure();
+    this.#binding = binding;
+
+    element.src = binding.nativeUri;
+    element.load?.();
+    if (opts?.startAtMs) element.currentTime = opts.startAtMs / 1000;
+  }
+
+  async play(): Promise<void> {
+    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(): Promise<void> {
+    this.#ensure().pause();
+  }
+
+  async stop(): Promise<void> {
+    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: number): Promise<void> {
+    this.#ensure().currentTime = Math.max(0, positionMs) / 1000;
+  }
+
+  async setVolume(volume: number): Promise<void> {
+    this.#ensure().volume = Math.min(1, Math.max(0, volume));
+  }
+
+  subscribe(listener: (event: AdapterEvent) => void): () => void {
+    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(): Promise<void> {
+    await this.stop();
+    this.#unwire();
+    this.#listeners.clear();
+    this.#element = null;
+  }
+
+  // -- internals ------------------------------------------------------------
+
+  #ensure(): MediaElementLike {
+    if (!this.#element) {
+      const source = this.#options.element;
+      this.#element = typeof source === 'function' ? source() : source;
+    }
+    return this.#element;
+  }
+
+  #wire(): void {
+    const element = this.#ensure();
+
+    const on = (type: string, handler: () => void) => {
+      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(): void {
+    for (const off of this.#detach) off();
+    this.#detach = [];
+  }
+
+  #emit(event: AdapterEvent): void {
+    for (const listener of [...this.#listeners]) listener(event);
+  }
+}
+
+/** A media element reports `NaN` before metadata and `Infinity` for streams. */
+function toMs(seconds: number): number | undefined {
+  if (!Number.isFinite(seconds) || seconds <= 0) return undefined;
+  return Math.round(seconds * 1000);
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+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';