@banou/media-player 0.8.19 → 0.8.21

package/dist/remote/index.d.ts

@@ -0,0 +1,155 @@
+import type { Transport } from 'osra';
+import type { PlayerMedia } from '../react/media';
+import type { Writable } from './protocol';
+export type { PlayerEvent, PlayerSnapshot, PlayerUpdate } from './protocol';
+export { DEFAULT_PLAYER_ID, PLAYER_CHANNEL, PLAYER_EVENTS } from './protocol';
+/**
+ * Where a player serves from, and to whom.
+ *
+ * With nothing given it serves the window that FRAMES this document, and only that window: a tab is
+ * full of frames, and a player that answered whichever of them asked first would be anyone's.
+ * `origin` narrows the embedder further when it is known; left unset, the player serves the framing
+ * window whatever its origin, so what it serves (its snapshot, `currentSrc` included) reaches any
+ * page that embeds it. `transport` replaces all of that for an unusual topology (a worker, a port
+ * the two sides already share). `channel` is what separates this from other osra traffic on the same
+ * window, and both sides must agree on it.
+ */
+export type ExposePlayerOptions = {
+    /**
+     * Which player this is, for a document that serves more than one: an embedder asks for it by the
+     * same id. Defaults to `DEFAULT_PLAYER_ID`, so a document with one player never says it.
+     *
+     * Serving the same id twice REPLACES it, which is how a player that switches media is followed;
+     * two different ids are two players and neither disturbs the other.
+     */
+    id?: string;
+    transport?: Transport;
+    /**
+     * The embedder's origin, when it is known: what is served reaches nobody else.
+     *
+     * Two calls naming different origins are two channels, and both answer on the same wire, so a
+     * document that serves one embedder openly and another narrowly should give them different
+     * `channel` names rather than relying on the origin to separate them.
+     */
+    origin?: string;
+    channel?: string;
+    /**
+     * Stops serving this media, exactly as the returned teardown does, AND closes the channel it was
+     * served on, which is the only thing that ever does.
+     *
+     * A teardown deliberately does not: a document that swaps a media removes one and adds the next,
+     * and a channel that closed in between would drop every embedder listening to the others.
+     */
+    signal?: AbortSignal;
+};
+/**
+ * Serve `media` to this document's embedder. Returns the teardown for THIS media.
+ *
+ * A plain function rather than a controller object, unlike the engine's, because the caller is
+ * almost always a React effect and this is exactly what one returns.
+ *
+ * The channel to the embedder lives for the document's life and is opened once; what `exposePlayer`
+ * does is put a media on it. Tearing down and calling it again with the next media (which is what
+ * `<MediaPlayer expose>` does whenever its media changes) swaps the media on the same channel, so an
+ * embedder's mirror follows the switch as an element would report it: `emptied`, then the new media's
+ * state. An embedder never has to reconnect.
+ *
+ * Two calls that name a different `origin` or `channel` are two channels. A caller that supplies its
+ * own `transport` gets a channel of its own, which its teardown closes.
+ *
+ * Safe to call in a document nobody frames: it serves nobody and returns at once.
+ */
+export declare const exposePlayer: (media: PlayerMedia, options?: ExposePlayerOptions) => (() => void);
+/** The properties an embedder may write. Everything else mirrors the far side and is read-only. */
+type Mirrored = Omit<PlayerMedia, Writable>;
+/**
+ * A player in another document, as a media of this one.
+ *
+ * Everything the mirror carries is present, unlike `PlayerMedia`, where most of it is optional
+ * because a media may not implement it: the mirror always answers, from a snapshot that always has
+ * every field. So a consumer reads `player.buffered.length` rather than `player.buffered?.length`.
+ */
+export type MediaPlayerHandle = {
+    readonly [K in keyof Mirrored]: Mirrored[K];
+} & Readonly<Required<Pick<PlayerMedia, 'src' | 'currentSrc' | 'ended' | 'buffered' | 'seekable' | 'error' | 'videoWidth' | 'videoHeight'>>> & Required<Pick<PlayerMedia, Writable>> & {
+    /**
+     * Settles once the far side has first answered with its state; reads before that answer the
+     * empty defaults. Stays pending for as long as nobody answers, and rejects with an AbortError on
+     * `destroy()` or when `signal` aborts.
+     *
+     * Nobody answering covers more than an embed with no player in it: a `MessagePort` whose peer has
+     * gone raises no event, so a mirror on a dead transport cannot tell that from a slow one. Bound
+     * the wait rather than expecting it to end by itself, with `signal` for the player's whole
+     * lifetime or `Promise.race` for the wait alone.
+     */
+    readonly ready: Promise<void>;
+    /**
+     * Start playing, muting first if that is what the far document requires, and say which happened.
+     *
+     * `play()` runs under the FAR document's autoplay policy, and no message carries a user gesture
+     * across a frame boundary: however deliberately somebody clicked over here, an unmuted element in
+     * a document nobody has touched refuses to start. Muted playback is always permitted, so this
+     * tries honestly first and falls back rather than leaving the player stopped.
+     *
+     * `muted` in the result is what the player ended up as, so an app that gets `true` can offer the
+     * viewer a way to turn sound on. That click is itself the gesture the document was missing, and
+     * clearing `muted` afterwards needs no permission from anyone.
+     *
+     * If muted playback is refused too, the FIRST error is what rejects, since a policy refusal says
+     * more than whatever the retry hit, and the player is left unmuted as it was found.
+     */
+    autoplay: () => Promise<{
+        muted: boolean;
+    }>;
+    /** stop mirroring and release the channel; the far player keeps playing */
+    destroy: () => void;
+};
+/**
+ * Where the far player is.
+ *
+ * `target` is the iframe that holds it, in the common case. A `Window` covers a frame reached some
+ * other way, and any osra transport (a `MessagePort` the two sides already share, a worker) is taken
+ * as it is.
+ *
+ * `origin` is the far side's, when the embedder knows it: both a filter on what is heard and the only
+ * origin spoken to. Left unset, whatever origin answers FIRST is pinned for the connection's life and
+ * everything after is posted to it, so a frame that later navigates elsewhere is neither heard nor
+ * told anything.
+ */
+export type MediaPlayerHandleOptions = {
+    /**
+     * Which player to mirror, when the far document serves more than one. Defaults to
+     * `DEFAULT_PLAYER_ID`. An id nothing is serving is not an error: `ready` simply stays pending until
+     * something serves it, which is how an embedder waits for a player that has not mounted yet.
+     */
+    id?: string;
+    /** the far side's origin, e.g. `https://torrent.fkn.app`; a url with a path is refused */
+    origin?: string;
+    /** must match the player's; see `PLAYER_CHANNEL` */
+    channel?: string;
+    /** closes the mirror: `ready` rejects with an AbortError and nothing more is heard */
+    signal?: AbortSignal;
+};
+/**
+ * Mirror a player another document is serving, as a media of this one.
+ *
+ * ```ts
+ * const player = mediaPlayer(iframe, { origin: 'https://torrent.fkn.app' })
+ * await player.ready
+ * await player.play()
+ * ```
+ *
+ * The handle is a `PlayerMedia`, so it can be read, written, listened to, or handed to a
+ * `<MediaPlayer media={player}>` of this document's own. Reads answer synchronously from a mirror of
+ * the far side's last snapshot; writes move that mirror at once and go out to be applied.
+ *
+ * Everything this document mirrors on one `target` shares one connection, so calling it once per
+ * player is what you should do.
+ *
+ * `ready` may never settle: an embed that serves no player, or an id nobody serves, is silence, and
+ * a transport whose peer has gone raises nothing. Bound it with `signal` or by racing it.
+ *
+ * @throws TypeError if `target` is an iframe with no window yet (append it to a document first), or
+ * if `origin` is not a serialized origin.
+ */
+export declare const mediaPlayer: (target: HTMLIFrameElement | Window | Transport, options?: MediaPlayerHandleOptions) => MediaPlayerHandle;

package/dist/remote/index.js

@@ -0,0 +1,416 @@
+import { expose as e } from "osra";
+//#region src/lib/remote/protocol.ts
+var t = [
+	"loadstart",
+	"loadedmetadata",
+	"loadeddata",
+	"durationchange",
+	"timeupdate",
+	"play",
+	"playing",
+	"pause",
+	"seeking",
+	"seeked",
+	"progress",
+	"ratechange",
+	"volumechange",
+	"ended",
+	"waiting",
+	"stalled",
+	"suspend",
+	"canplay",
+	"canplaythrough",
+	"emptied",
+	"resize",
+	"error"
+], n = [
+	"currentTime",
+	"volume",
+	"muted",
+	"playbackRate"
+], r = [
+	"play",
+	"pause",
+	"load"
+], i = "banou-media-player", a = "default", o = (e) => [
+	"loadstart",
+	...e.readyState >= 1 ? ["loadedmetadata", "durationchange"] : [],
+	...e.readyState >= 2 ? ["loadeddata"] : [],
+	...e.readyState >= 3 ? ["canplay"] : [],
+	"volumechange",
+	"ratechange",
+	"progress",
+	"resize",
+	e.paused ? "pause" : "playing",
+	...e.ended ? ["ended"] : [],
+	...e.error ? ["error"] : []
+], s = (e) => {
+	if (!e) return [];
+	let t = [];
+	for (let n = 0; n < e.length; n++) t.push([e.start(n), e.end(n)]);
+	return t;
+}, c = (e) => ({
+	currentTime: l(e.currentTime),
+	duration: l(e.duration),
+	paused: e.paused,
+	ended: e.ended ?? !1,
+	seeking: e.seeking,
+	readyState: e.readyState,
+	volume: e.volume ?? 1,
+	muted: e.muted ?? !1,
+	playbackRate: e.playbackRate ?? 1,
+	src: e.src ?? "",
+	currentSrc: e.currentSrc ?? "",
+	buffered: s(e.buffered),
+	seekable: s(e.seekable),
+	error: e.error ? {
+		code: e.error.code,
+		message: e.error.message
+	} : null,
+	videoWidth: e.videoWidth ?? 0,
+	videoHeight: e.videoHeight ?? 0
+}), l = (e) => Number.isNaN(e) ? 0 : e, u = {
+	currentTime: 0,
+	duration: 0,
+	paused: !0,
+	ended: !1,
+	seeking: !1,
+	readyState: 0,
+	volume: 1,
+	muted: !1,
+	playbackRate: 1,
+	src: "",
+	currentSrc: "",
+	buffered: [],
+	seekable: [],
+	error: null,
+	videoWidth: 0,
+	videoHeight: 0
+}, d = (e) => ({
+	length: e.length,
+	start: (t) => e[t]?.[0] ?? 0,
+	end: (t) => e[t]?.[1] ?? 0
+}), f = 1e4, p = 1500, m = () => new DOMException("the far player did not start playing", "NotAllowedError"), h = 8, g = 32, _ = (e, t = {}) => {
+	T(t.origin);
+	let n = typeof window < "u" && window.parent !== window;
+	return !t.transport && !n ? () => {} : b(t).serve(e, t);
+}, v = /* @__PURE__ */ new WeakMap(), y = /* @__PURE__ */ new Map(), b = (i) => {
+	let a = i.channel ?? "banou-media-player", s = i.transport, l = `${a}|${i.origin ?? "*"}`, d = s ? v.get(s) ?? (v.set(s, /* @__PURE__ */ new Map()), v.get(s)) : y, f = d.get(l);
+	if (f) return f;
+	let p = /* @__PURE__ */ new Map(), m = /* @__PURE__ */ new Map(), _ = (e) => m.get(e) ?? m.set(e, /* @__PURE__ */ new Set()).get(e), b = (e, t) => {
+		m.get(e)?.delete(t);
+		try {
+			t.onmessage = null, t.close();
+		} catch {}
+	}, x = (e, t, n) => {
+		for (let r of n ? [n] : [..._(e)]) try {
+			r.postMessage(t);
+		} catch {
+			b(e, r);
+		}
+	}, S = (e) => {
+		let t = p.get(e);
+		return t ? c(t) : void 0;
+	}, C = (e, t) => {
+		if (!m.get(e)?.size) return;
+		let n = S(e);
+		n && x(e, {
+			event: t,
+			snapshot: n
+		});
+	}, w = {
+		subscribe: (e, t) => {
+			if (typeof e != "string") throw TypeError("a player id must be a string");
+			if (typeof MessagePort < "u" && !(t instanceof MessagePort)) throw TypeError("subscribe takes a MessagePort");
+			if (!m.has(e) && m.size >= g) throw RangeError("too many players on this channel");
+			let n = _(e);
+			if (n.size >= h) throw RangeError("too many embedders for this player");
+			n.add(t), t.onmessage = () => b(e, t), t.start?.();
+			let r = S(e);
+			r && x(e, {
+				event: "loadstart",
+				snapshot: r
+			}, t);
+		},
+		set: (e, t, r) => {
+			let i = p.get(e);
+			if (!(!i || !n.includes(t))) try {
+				i[t] = r;
+			} catch {}
+		},
+		call: async (e, t) => {
+			let n = p.get(e);
+			if (!(!n || !r.includes(t))) try {
+				t === "play" ? await n.play() : t === "pause" ? n.pause() : n.load?.();
+			} finally {
+				C(e, "timeupdate");
+			}
+		}
+	}, T = new AbortController();
+	T.signal.addEventListener("abort", () => {
+		d.delete(l);
+		for (let [e, t] of m) for (let n of [...t]) b(e, n);
+		m.clear(), p.clear();
+	}, { once: !0 }), e(w, {
+		transport: i.transport ?? {
+			emit: window.parent,
+			receive: A(() => window.parent, i.origin)
+		},
+		origin: i.origin,
+		key: a,
+		unregisterSignal: T.signal
+	});
+	let E = { serve: (e, n) => {
+		let r = n.id ?? "default", i = t.map((t) => [t, () => {
+			p.get(r) === e && C(r, t);
+		}]);
+		for (let [t, n] of i) e.addEventListener(t, n);
+		let a = p.has(r);
+		p.set(r, e), a && x(r, {
+			event: "emptied",
+			snapshot: { ...u }
+		});
+		for (let t of o(c(e))) C(r, t);
+		let s = () => {
+			for (let [t, n] of i) e.removeEventListener(t, n);
+			p.get(r) === e && (p.delete(r), x(r, {
+				event: "emptied",
+				snapshot: { ...u }
+			}));
+		}, l = () => {
+			s(), T.abort();
+		};
+		return n.signal && (n.signal.aborted ? l() : n.signal.addEventListener("abort", l, { once: !0 })), s;
+	} };
+	return d.set(l, E), E;
+}, x = /* @__PURE__ */ new WeakMap(), S = (t, n) => {
+	let r = n.channel ?? "banou-media-player", i = `${r}|${n.origin ?? "*"}`, a = x.get(t) ?? (x.set(t, /* @__PURE__ */ new Map()), x.get(t)), o = a.get(i);
+	if (o) return o;
+	let s = O(t, n.origin), c = /* @__PURE__ */ new Set(), l = new AbortController(), u, d = (e) => {
+		try {
+			e.port?.postMessage("close");
+		} catch {}
+		try {
+			e.port?.close();
+		} catch {}
+		e.port = void 0;
+	}, f = async (e) => {
+		d(e);
+		let { port1: t, port2: n } = new MessageChannel();
+		e.port = t, t.onmessage = ({ data: t }) => {
+			l.signal.aborted || e.update(t);
+		}, await w(() => u.subscribe(e.id, n)).catch((t) => {
+			throw d(e), t;
+		});
+	}, p = () => {
+		l.abort();
+		for (let e of c) d(e);
+		c.clear(), a.delete(i);
+	};
+	(async () => {
+		for await (let t of e({}, {
+			transport: s,
+			origin: n.origin,
+			key: r,
+			unregisterSignal: l.signal
+		})) {
+			if (l.signal.aborted) return;
+			u = t;
+			for (let e of c) e.reset();
+			await Promise.allSettled([...c].map((e) => f(e)));
+		}
+		u = void 0;
+		for (let e of c) e.reset();
+	})().catch(() => {
+		u = void 0;
+		for (let e of c) e.reset();
+	});
+	let m = {
+		attach: (e) => (c.add(e), u && f(e).catch(() => {}), () => {
+			d(e), c.delete(e), c.size || p();
+		}),
+		set: (e, t, n) => u?.set(e, t, n),
+		call: async (e, t) => {
+			if (!u) throw new DOMException("the remote player was closed", "AbortError");
+			await u.call(e, t);
+		}
+	};
+	return a.set(i, m), m;
+}, C = (e, t = {}) => {
+	T(t.origin);
+	let r = new AbortController(), i = t.signal ? AbortSignal.any([t.signal, r.signal]) : r.signal, a = t.id ?? "default", s = { ...u }, c = new EventTarget(), l = (e) => c.dispatchEvent(new Event(e)), f, h, g = new Promise((e, t) => {
+		f = e, h = t;
+	});
+	g.catch(() => {});
+	let _ = () => new DOMException("the remote player was closed", "AbortError"), v = /* @__PURE__ */ new Set(), y = () => {
+		for (let e of [...v]) e(_());
+		v.clear();
+	}, b = /* @__PURE__ */ new Map(), x = !1, C = S(e, t).attach({
+		id: a,
+		reset: () => {
+			x = !1, y();
+		},
+		update: ({ event: e, snapshot: t }) => {
+			let n = !x;
+			x = !0, Object.assign(s, t);
+			for (let [e, t] of b) s[e] = t;
+			if (!n) {
+				l(e);
+				return;
+			}
+			for (let e of o(s)) l(e);
+			f();
+		}
+	}), w = () => {
+		C(), y(), h(_());
+	};
+	i.aborted ? queueMicrotask(w) : i.addEventListener("abort", w, { once: !0 });
+	let E = (e, t) => Object.defineProperty(c, e, {
+		get: () => t ? t(s[e]) : s[e],
+		enumerable: !0
+	});
+	for (let e of [
+		"duration",
+		"paused",
+		"ended",
+		"seeking",
+		"readyState",
+		"src",
+		"currentSrc",
+		"error",
+		"videoWidth",
+		"videoHeight"
+	]) E(e);
+	E("buffered", d), E("seekable", d);
+	let D = (e) => g.then(() => i.aborted ? void 0 : e()).catch(() => {}), O = S(e, t);
+	for (let e of n) Object.defineProperty(c, e, {
+		get: () => s[e],
+		set: (t) => {
+			s[e] = t, b.set(e, t), D(async () => {
+				await O.set(a, e, t), b.get(e) === t && b.delete(e);
+			});
+		},
+		enumerable: !0
+	});
+	let k = (e) => g.then(() => {
+		if (i.aborted) throw _();
+		let t = O.call(a, e);
+		return new Promise((e, n) => {
+			v.add(n), t.then(() => {
+				v.delete(n), e();
+			}, (e) => {
+				v.delete(n), n(i.aborted ? _() : e);
+			});
+		});
+	});
+	c.play = () => (s.paused = !1, k("play").catch((e) => {
+		throw s.paused = !0, e;
+	}));
+	let A = () => new Promise((e) => {
+		let t = (t) => {
+			clearTimeout(r), c.removeEventListener("playing", n), c.removeEventListener("play", n), e(t);
+		}, n = () => t(!0);
+		c.addEventListener("playing", n), c.addEventListener("play", n);
+		let r = setTimeout(() => t(!s.paused), p);
+	}), j = async () => {
+		let e = !s.paused, t;
+		try {
+			await c.play();
+		} catch (e) {
+			t = e;
+		}
+		return e ? {
+			started: !0,
+			refusal: t
+		} : {
+			started: await A(),
+			refusal: t
+		};
+	};
+	return c.autoplay = async () => {
+		let e = await j();
+		if (e.started) return { muted: c.muted };
+		if (c.muted || i.aborted) throw e.refusal ?? m();
+		c.muted = !0;
+		let t = await j();
+		if (t.started) return { muted: !0 };
+		throw c.muted = !1, e.refusal ?? t.refusal ?? m();
+	}, c.pause = () => {
+		s.paused = !0, k("pause").catch(() => {});
+	}, c.load = () => {
+		k("load").catch(() => {});
+	}, Object.defineProperty(c, "ready", {
+		value: g,
+		enumerable: !1
+	}), c.destroy = () => r.abort(), c;
+}, w = async (e) => {
+	let t;
+	try {
+		return await Promise.race([e(), new Promise((e, n) => {
+			t = setTimeout(() => n(/* @__PURE__ */ Error("the player did not answer")), f);
+		})]);
+	} finally {
+		t && clearTimeout(t);
+	}
+}, T = (e) => {
+	if (e === void 0 || e === "*") return;
+	if (e === "null") throw TypeError("an opaque origin (\"null\") cannot be spoken to; leave `origin` unset and the sender check stands alone");
+	let t;
+	try {
+		t = new URL(e);
+	} catch {
+		throw TypeError(`\`origin\` must be an origin like https://example.com, not ${e}`);
+	}
+	if (t.origin !== e) throw TypeError(`\`origin\` must be an origin like ${t.origin}, not ${e}`);
+}, E = (e) => {
+	try {
+		return !!e && typeof e == "object" && e.window === e;
+	} catch {
+		return !1;
+	}
+}, D = (e) => {
+	if (E(e)) return !1;
+	try {
+		return !!e && typeof e == "object" && "contentWindow" in e;
+	} catch {
+		return !1;
+	}
+}, O = (e, t) => {
+	if (E(e)) {
+		let n = k(t);
+		return {
+			emit: (t, r) => {
+				e.postMessage(t, n.target(), r ?? []);
+			},
+			receive: A(() => e, t, n)
+		};
+	}
+	if (D(e)) {
+		if (!e.contentWindow) throw TypeError("mediaPlayer: the iframe has no window yet; append it to a document first");
+		let n = () => e.contentWindow, r = k(t);
+		return {
+			emit: (e, t) => {
+				n()?.postMessage(e, r.target(), t ?? []);
+			},
+			receive: A(n, t, r)
+		};
+	}
+	return e;
+}, k = (e) => {
+	let t = e && e !== "*" ? e : void 0;
+	return {
+		target: () => t && t !== "null" ? t : "*",
+		admits: (e) => t ? e === t : (e && (t = e), !0)
+	};
+}, A = (e, t, n = k(t)) => (t) => {
+	let r = (r) => {
+		r.source === e() && n.admits(r.origin) && t(r.data, {
+			source: r.source,
+			origin: r.origin,
+			receiveTransport: window
+		});
+	};
+	return window.addEventListener("message", r), () => window.removeEventListener("message", r);
+};
+//#endregion
+export { a as DEFAULT_PLAYER_ID, i as PLAYER_CHANNEL, t as PLAYER_EVENTS, _ as exposePlayer, C as mediaPlayer };

package/dist/remote/protocol.d.ts

@@ -0,0 +1,91 @@
+import type { PlayerMedia, TimeRangesLike } from '../react/media';
+/**
+ * Everything readable about a player, as one plain object.
+ *
+ * A media's properties are SYNCHRONOUS (`currentTime` is a getter that must answer now) and every
+ * cross-document transport is not, so the far side is mirrored: the player's document sends one of
+ * these with every event it raises, and the embedder answers reads from the latest one it holds.
+ * Plain pairs for the ranges, because a `TimeRanges` has nothing to hand across a boundary.
+ */
+export type PlayerSnapshot = {
+    currentTime: number;
+    duration: number;
+    paused: boolean;
+    ended: boolean;
+    seeking: boolean;
+    readyState: number;
+    volume: number;
+    muted: boolean;
+    playbackRate: number;
+    src: string;
+    currentSrc: string;
+    buffered: [number, number][];
+    seekable: [number, number][];
+    error: {
+        code: number;
+        message: string;
+    } | null;
+    videoWidth: number;
+    videoHeight: number;
+};
+/**
+ * The events a player raises that an embedder can hear, each carrying a fresh snapshot.
+ *
+ * Every event video.js's own features sync on is here, `emptied` and `loadstart` included: a store
+ * attached to the mirror resets on those, and an entry costs nothing until it fires.
+ */
+export declare const PLAYER_EVENTS: readonly ['loadstart', 'loadedmetadata', 'loadeddata', 'durationchange', 'timeupdate', 'play', 'playing', 'pause', 'seeking', 'seeked', 'progress', 'ratechange', 'volumechange', 'ended', 'waiting', 'stalled', 'suspend', 'canplay', 'canplaythrough', 'emptied', 'resize', 'error'];
+export type PlayerEvent = typeof PLAYER_EVENTS[number];
+/** The properties an embedder may set. Everything else is read-only on a media, here as there. */
+export declare const WRITABLE: readonly ['currentTime', 'volume', 'muted', 'playbackRate'];
+export type Writable = typeof WRITABLE[number];
+/** The methods an embedder may call. */
+export declare const CALLABLE: readonly ['play', 'pause', 'load'];
+export type Callable = typeof CALLABLE[number];
+/** The one channel both sides default to, so a page can run other osra channels over the same window. */
+export declare const PLAYER_CHANNEL = "banou-media-player";
+/**
+ * Which player, for a document that serves more than one.
+ *
+ * A document with one player never says it; both sides default to this and find each other. A
+ * document with several gives each an id and an embedder asks for the one it wants. The ids are the
+ * serving document's to choose and the embedder has to know them, the same way it knows the url it
+ * framed.
+ */
+export declare const DEFAULT_PLAYER_ID = "default";
+/** What rides the event port: the event's name and the state right after it. */
+export type PlayerUpdate = {
+    event: PlayerEvent;
+    snapshot: PlayerSnapshot;
+};
+/**
+ * What the player's document serves, one document at a time, addressed by player id. Internal: an
+ * embedder never sees it, `mediaPlayer` wraps it.
+ *
+ * `subscribe` takes a MessagePort rather than a function on purpose. Events are ONE-WAY: the player
+ * posts every update on the port and never waits for an answer, so an embedder that vanished without
+ * closing (a tab killed, a frame torn out) pins nothing in the player's document, where a function
+ * handle called across a dead connection would leave a promise pending per event, unbounded.
+ *
+ * There is no `snapshot`: subscribing is what answers with the state, in one round trip instead of
+ * two, and it cannot miss what happened between them. Subscribing to an id nothing is serving is
+ * allowed and says nothing back until something is, which is how an embedder waits for a player that
+ * has not mounted yet.
+ */
+export type PlayerService = {
+    subscribe: (id: string, port: MessagePort) => void;
+    set: (id: string, name: Writable, value: number | boolean) => void;
+    call: (id: string, name: Callable) => Promise<void>;
+};
+/**
+ * The events that bring a store attached to the mirror up to date from a snapshot alone, in the
+ * order an element would raise them on load. Dispatched after every snapshot that arrives with no
+ * event of its own: the first one, and the one a new player connection answers with.
+ */
+export declare const syncEventsFor: (snapshot: PlayerSnapshot) => PlayerEvent[];
+/** A media as a snapshot. A NaN duration, which a bare element answers before it has metadata, is sent as 0. */
+export declare const snapshotOf: (media: PlayerMedia) => PlayerSnapshot;
+/** The snapshot an embedder holds before the player's document has said anything. */
+export declare const EMPTY_SNAPSHOT: PlayerSnapshot;
+/** Plain pairs back into the structural `TimeRanges` the player reads. */
+export declare const toTimeRanges: (ranges: [number, number][]) => TimeRangesLike;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@banou/media-player",
-  "version": "0.8.19",
+  "version": "0.8.21",
   "description": "A video player for containers and codecs the browser cannot play natively, remuxed on the fly",
   "type": "module",
   "main": "dist/index.js",
@@ -14,6 +14,10 @@
       "types": "./dist/engine/index.d.ts",
       "import": "./dist/engine/index.js"
     },
+    "./remote": {
+      "types": "./dist/remote/index.d.ts",
+      "import": "./dist/remote/index.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -43,6 +47,7 @@
     "ass-compiler": "^0.1.16",
     "jassub": "^1.8.6",
     "libav-wasm": "^0.8.4",
+    "osra": "^0.6.12",
     "react-feather": "^2.0.10",
     "react-tooltip": "^5.28.0"
   },
@@ -68,5 +73,9 @@
   },
   "overrides": {
     "vite": "npm:@voidzero-dev/vite-plus-core@0.2.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Banou26/media-player.git"
   }
 }