@oddin-gg/havik-player 1.17.0 → 1.18.0

package/dist/index.d.cts

@@ -125,6 +125,16 @@ export declare interface CreatePlayerOptions {
     statusOverlays?: boolean;
     /** Message on the end-of-stream card. Default: "This stream has ended". */
     endedMessage?: string;
+    /**
+     * Message shown instead of {@link endedMessage} when the stream stopped but
+     * the match is still running (the server's `interrupted` reason — an ingest
+     * outage that outlived the bridge's reconnect hold). Default:
+     * "Reconnecting — please stand by" — a promise the player keeps while
+     * {@link rejoinOnLive} is on (the default; it also needs
+     * {@link liveStateEvents}). Override it if you disable auto-rejoin, since
+     * nothing will then re-attach on its own.
+     */
+    interruptedMessage?: string;
     /** Message on the fatal-error card. Default: the error's own message. */
     errorMessage?: string;
     /**
@@ -304,6 +314,22 @@ export declare interface EmbedHandle {
     destroy(): void;
 }
 
+/**
+ * Why a stream ended (havik-streams #191). `ended` alone cannot tell a viewer
+ * whether the MATCH finished or only its stream dropped — two situations that
+ * deserve opposite messaging:
+ *
+ * - `interrupted` — the match is still running; no session is serving (an
+ *   ingest outage that outlived the bridge's reconnect grace). Play is
+ *   expected to resume, so surface "reconnecting", never "this has ended".
+ * - `match_ended` — the match itself finished. A real end.
+ *
+ * Absent on every other state, and absent entirely from servers predating the
+ * field — so treat `undefined` as "unknown, assume a real end" (what clients
+ * did before it existed).
+ */
+export declare type EndedReason = 'interrupted' | 'match_ended';
+
 /**
  * Enter fullscreen for `video`, walking the capability ladder above.
  * `container` is the element to present in element fullscreen (defaults to
@@ -525,6 +551,8 @@ export declare type LiveState = 'live' | 'upcoming' | 'ended' | 'gone';
 export declare interface LiveStateEvent {
     matchUrn: string;
     state: LiveState;
+    /** Set only on `ended`; see {@link EndedReason}. */
+    reason?: EndedReason;
     /** RFC3339 server timestamp the transition was stamped at. */
     serverTime: string;
 }
@@ -647,6 +675,9 @@ export declare interface PlaybackStats {
 export declare interface Player {
     readonly state: PlayerState;
     readonly descriptor: StreamDescriptor | null;
+    /** Why the stream ended, when the server said so; null otherwise. Cleared
+     *  when fresh playback commits (including a rejoin). See EndedReason. */
+    readonly endedReason: EndedReason | null;
     play(): Promise<void>;
     pause(): void;
     setMuted(muted: boolean): void;
@@ -696,7 +727,15 @@ export declare interface PlayerEventMap {
     playing: void;
     buffering: void;
     paused: void;
-    ended: void;
+    /**
+     * End of stream. The payload says WHY when the server told us
+     * (`interrupted` = the match is still running and play should resume, so
+     * do NOT say "ended"; `match_ended` = a real end); `undefined` means the
+     * end came from the HLS staleness watchdog or a server predating the
+     * field — treat it as a real end, the pre-existing behavior. Fires again
+     * with `match_ended` if an interruption later turns out to be the end.
+     */
+    ended: EndedReason | undefined;
     error: PlaybackError;
     /** Non-fatal condition (e.g. FairPlay-not-implemented passthrough, a failed license refresh). Playback continues. */
     warning: PlaybackError;

package/dist/index.d.ts

@@ -125,6 +125,16 @@ export declare interface CreatePlayerOptions {
     statusOverlays?: boolean;
     /** Message on the end-of-stream card. Default: "This stream has ended". */
     endedMessage?: string;
+    /**
+     * Message shown instead of {@link endedMessage} when the stream stopped but
+     * the match is still running (the server's `interrupted` reason — an ingest
+     * outage that outlived the bridge's reconnect hold). Default:
+     * "Reconnecting — please stand by" — a promise the player keeps while
+     * {@link rejoinOnLive} is on (the default; it also needs
+     * {@link liveStateEvents}). Override it if you disable auto-rejoin, since
+     * nothing will then re-attach on its own.
+     */
+    interruptedMessage?: string;
     /** Message on the fatal-error card. Default: the error's own message. */
     errorMessage?: string;
     /**
@@ -304,6 +314,22 @@ export declare interface EmbedHandle {
     destroy(): void;
 }
 
+/**
+ * Why a stream ended (havik-streams #191). `ended` alone cannot tell a viewer
+ * whether the MATCH finished or only its stream dropped — two situations that
+ * deserve opposite messaging:
+ *
+ * - `interrupted` — the match is still running; no session is serving (an
+ *   ingest outage that outlived the bridge's reconnect grace). Play is
+ *   expected to resume, so surface "reconnecting", never "this has ended".
+ * - `match_ended` — the match itself finished. A real end.
+ *
+ * Absent on every other state, and absent entirely from servers predating the
+ * field — so treat `undefined` as "unknown, assume a real end" (what clients
+ * did before it existed).
+ */
+export declare type EndedReason = 'interrupted' | 'match_ended';
+
 /**
  * Enter fullscreen for `video`, walking the capability ladder above.
  * `container` is the element to present in element fullscreen (defaults to
@@ -525,6 +551,8 @@ export declare type LiveState = 'live' | 'upcoming' | 'ended' | 'gone';
 export declare interface LiveStateEvent {
     matchUrn: string;
     state: LiveState;
+    /** Set only on `ended`; see {@link EndedReason}. */
+    reason?: EndedReason;
     /** RFC3339 server timestamp the transition was stamped at. */
     serverTime: string;
 }
@@ -647,6 +675,9 @@ export declare interface PlaybackStats {
 export declare interface Player {
     readonly state: PlayerState;
     readonly descriptor: StreamDescriptor | null;
+    /** Why the stream ended, when the server said so; null otherwise. Cleared
+     *  when fresh playback commits (including a rejoin). See EndedReason. */
+    readonly endedReason: EndedReason | null;
     play(): Promise<void>;
     pause(): void;
     setMuted(muted: boolean): void;
@@ -696,7 +727,15 @@ export declare interface PlayerEventMap {
     playing: void;
     buffering: void;
     paused: void;
-    ended: void;
+    /**
+     * End of stream. The payload says WHY when the server told us
+     * (`interrupted` = the match is still running and play should resume, so
+     * do NOT say "ended"; `match_ended` = a real end); `undefined` means the
+     * end came from the HLS staleness watchdog or a server predating the
+     * field — treat it as a real end, the pre-existing behavior. Fires again
+     * with `match_ended` if an interruption later turns out to be the end.
+     */
+    ended: EndedReason | undefined;
     error: PlaybackError;
     /** Non-fatal condition (e.g. FairPlay-not-implemented passthrough, a failed license refresh). Playback continues. */
     warning: PlaybackError;

package/dist/index.js

@@ -1408,7 +1408,7 @@ var qe = class {
 			keepalive: !0
 		}).catch(() => {});
 	}
-}, Je = "1.17.0", W = {
+}, Je = "1.18.0", W = {
 	accent: "#E1B600",
 	accentText: "#1B1C23",
 	background: "#0e0f13",
@@ -1505,18 +1505,20 @@ var tt = class {
 	menu;
 	statusBox = null;
 	statusKind = null;
+	statusMsg = null;
 	hasPlayed = !1;
 	lastError = null;
 	logoUrl;
 	statusOverlays;
 	endedMessage;
+	interruptedMessage;
 	errorMessage;
 	hideTimer;
 	openMenu = null;
 	scrubbing = !1;
 	offFns = [];
 	constructor(e) {
-		this.root = e.root, this.video = e.video, this.player = e.player, this.doc = e.root.ownerDocument ?? document, this.autoHideMs = e.autoHideMs ?? Qe, this.logoUrl = e.logoUrl, this.statusOverlays = e.statusOverlays !== !1, this.endedMessage = e.endedMessage ?? "This stream has ended", this.errorMessage = e.errorMessage, Xe(this.doc), this.root.classList.add("havik-player"), this.root.hasAttribute("tabindex") || (this.root.tabIndex = 0), this.root.setAttribute("role", "region"), this.root.setAttribute("aria-label", "Video player");
+		this.root = e.root, this.video = e.video, this.player = e.player, this.doc = e.root.ownerDocument ?? document, this.autoHideMs = e.autoHideMs ?? Qe, this.logoUrl = e.logoUrl, this.statusOverlays = e.statusOverlays !== !1, this.endedMessage = e.endedMessage ?? "This stream has ended", this.interruptedMessage = e.interruptedMessage ?? "Reconnecting — please stand by", this.errorMessage = e.errorMessage, Xe(this.doc), this.root.classList.add("havik-player"), this.root.hasAttribute("tabindex") || (this.root.tabIndex = 0), this.root.setAttribute("role", "region"), this.root.setAttribute("aria-label", "Video player");
 		let t = (e, t, n) => {
 			let r = this.doc.createElement(e);
 			if (r.className = t, n) for (let [e, t] of Object.entries(n)) r.setAttribute(e, t);
@@ -1570,7 +1572,7 @@ var tt = class {
 		}), this.on(this.muteBtn, "click", () => this.player.setMuted(!e.muted)), this.on(this.volSlider, "input", () => {
 			let t = Number(this.volSlider.value);
 			this.setVolumeFill(t), this.player.setVolume(t), t > 0 && e.muted && this.player.setMuted(!1);
-		}), this.on(this.liveGo, "click", () => this.player.seekToLive()), this.on(this.pipBtn, "click", () => void this.togglePip()), this.on(this.fsBtn, "click", () => void this.toggleFullscreen()), this.on(this.ccBtn, "click", () => this.toggleMenu("cc")), this.on(this.audioBtn, "click", () => this.toggleMenu("audio")), this.on(this.qualityBtn, "click", () => this.toggleMenu("quality")), this.on(this.seek, "pointerdown", (e) => this.onSeekDown(e)), this.on(this.seek, "keydown", (e) => this.onSeekKey(e)), this.on(e, "play", () => this.syncPlayPause()), this.on(e, "pause", () => this.syncPlayPause()), this.on(e, "volumechange", () => this.syncVolume()), this.on(e, "timeupdate", () => this.syncProgress()), this.on(e, "progress", () => this.syncProgress()), this.on(e, "durationchange", () => this.syncProgress()), this.offFns.push(this.player.on("statechange", () => this.syncState())), this.offFns.push(this.player.on("ready", () => this.refreshTracks())), this.offFns.push(this.player.on("qualitychange", () => this.onTracksChanged())), this.offFns.push(this.player.on("audiotrackchange", () => this.onTracksChanged())), this.offFns.push(this.player.on("texttrackchange", () => this.onTracksChanged())), this.offFns.push(this.player.on("pipchange", (e) => this.syncPip(e))), this.offFns.push(this.player.on("stats", () => this.syncLive())), this.offFns.push(this.player.on("error", (e) => {
+		}), this.on(this.liveGo, "click", () => this.player.seekToLive()), this.on(this.pipBtn, "click", () => void this.togglePip()), this.on(this.fsBtn, "click", () => void this.toggleFullscreen()), this.on(this.ccBtn, "click", () => this.toggleMenu("cc")), this.on(this.audioBtn, "click", () => this.toggleMenu("audio")), this.on(this.qualityBtn, "click", () => this.toggleMenu("quality")), this.on(this.seek, "pointerdown", (e) => this.onSeekDown(e)), this.on(this.seek, "keydown", (e) => this.onSeekKey(e)), this.on(e, "play", () => this.syncPlayPause()), this.on(e, "pause", () => this.syncPlayPause()), this.on(e, "volumechange", () => this.syncVolume()), this.on(e, "timeupdate", () => this.syncProgress()), this.on(e, "progress", () => this.syncProgress()), this.on(e, "durationchange", () => this.syncProgress()), this.offFns.push(this.player.on("statechange", () => this.syncState())), this.offFns.push(this.player.on("ended", () => this.syncState())), this.offFns.push(this.player.on("ready", () => this.refreshTracks())), this.offFns.push(this.player.on("qualitychange", () => this.onTracksChanged())), this.offFns.push(this.player.on("audiotrackchange", () => this.onTracksChanged())), this.offFns.push(this.player.on("texttrackchange", () => this.onTracksChanged())), this.offFns.push(this.player.on("pipchange", (e) => this.syncPip(e))), this.offFns.push(this.player.on("stats", () => this.syncLive())), this.offFns.push(this.player.on("error", (e) => {
 			this.lastError = e, this.statusKind = null, this.syncState();
 		})), this.on(this.root, "pointermove", () => this.poke()), this.on(this.root, "pointerleave", () => this.scheduleHide(0)), this.on(this.root, "focusin", () => this.poke()), this.on(this.root, "keydown", (e) => this.onKey(e)), this.on(this.doc, "pointerdown", (e) => this.onDocPointer(e), { capture: !0 }), this.on(this.doc, "fullscreenchange", () => this.syncFullscreen()), this.on(this.doc, "webkitfullscreenchange", () => this.syncFullscreen()), this.on(e, "webkitbeginfullscreen", () => this.syncFullscreen()), this.on(e, "webkitendfullscreen", () => this.syncFullscreen()), this.syncState();
 	}
@@ -1591,24 +1593,28 @@ var tt = class {
 		let t = null;
 		this.statusOverlays && (e === "ended" ? t = "ended" : e === "error" ? t = "error" : e === "waiting" ? t = "waiting" : !this.hasPlayed && (e === "idle" || e === "paused") && (t = "preplay")), this.renderStatus(t);
 	}
+	statusMessageFor(e) {
+		return e === "ended" ? this.player.endedReason === "interrupted" ? this.interruptedMessage : this.endedMessage : e === "waiting" ? this.hasPlayed ? "Reconnecting — please stand by" : "Starting soon…" : e === "error" ? this.errorMessage ?? this.lastError?.message ?? "Playback unavailable" : null;
+	}
 	renderStatus(e) {
-		if (e === this.statusKind || (this.statusKind = e, this.statusBox?.remove(), this.statusBox = null, this.root.classList.toggle("havik-has-status", !!e), !e)) return;
-		let t = this.doc.createElement("div");
-		if (t.className = `havik-status havik-status--${e}`, this.logoUrl) {
+		let t = this.statusMessageFor(e);
+		if (e === this.statusKind && t === this.statusMsg || (this.statusKind = e, this.statusMsg = t, this.statusBox?.remove(), this.statusBox = null, this.root.classList.toggle("havik-has-status", !!e), !e)) return;
+		let n = this.doc.createElement("div");
+		if (n.className = `havik-status havik-status--${e}`, this.logoUrl) {
 			let e = this.doc.createElement("div");
-			e.className = "havik-status__logo", t.append(e);
+			e.className = "havik-status__logo", n.append(e);
 		}
 		if (e === "preplay") {
 			let e = this.doc.createElement("button");
-			e.type = "button", e.className = "havik-status__btn havik-status__btn--play", e.setAttribute("aria-label", "Play"), e.innerHTML = J("play"), e.addEventListener("click", () => void this.player.play()), t.append(e);
+			e.type = "button", e.className = "havik-status__btn havik-status__btn--play", e.setAttribute("aria-label", "Play"), e.innerHTML = J("play"), e.addEventListener("click", () => void this.player.play()), n.append(e);
 		} else {
-			let n = this.doc.createElement("div");
-			if (n.className = "havik-status__msg", n.textContent = e === "ended" ? this.endedMessage : e === "waiting" ? this.hasPlayed ? "Reconnecting — please stand by" : "Starting soon…" : this.errorMessage ?? this.lastError?.message ?? "Playback unavailable", t.append(n), e === "error" && this.lastError && !$e.has(this.lastError.code)) {
+			let r = this.doc.createElement("div");
+			if (r.className = "havik-status__msg", r.textContent = t ?? "", n.append(r), e === "error" && this.lastError && !$e.has(this.lastError.code)) {
 				let e = this.doc.createElement("button");
-				e.type = "button", e.className = "havik-status__btn", e.innerHTML = `${J("retry")}<span>Retry</span>`, e.addEventListener("click", () => void this.player.retry()), t.append(e);
+				e.type = "button", e.className = "havik-status__btn", e.innerHTML = `${J("retry")}<span>Retry</span>`, e.addEventListener("click", () => void this.player.retry()), n.append(e);
 			}
 		}
-		this.root.append(t), this.statusBox = t, this.show();
+		this.root.append(n), this.statusBox = n, this.show();
 	}
 	syncVolume() {
 		let e = this.video, t = e.muted || e.volume === 0;
@@ -1846,6 +1852,7 @@ var lt = class {
 	loadGen = 0;
 	liveStateSub = null;
 	endedHandled = !1;
+	_endedReason = null;
 	rejoinTimer = null;
 	armingSub = null;
 	armSseTimer = null;
@@ -1862,6 +1869,9 @@ var lt = class {
 	get descriptor() {
 		return this._descriptor;
 	}
+	get endedReason() {
+		return this._endedReason;
+	}
 	async start() {
 		this.opts.muted && (this.opts.video.muted = !0), this.opts.poster && (this.opts.video.poster = this.opts.poster), this.mountControls(), this.attachPipListeners(), this.setState("loading");
 		let e = ++this.loadGen, t = this.resolveOptions();
@@ -1936,7 +1946,13 @@ var lt = class {
 			}));
 		}, g = () => {
 			a || p() || y(this.resolveOptions()).then((e) => m(e)).catch((e) => {
-				a || p() || e instanceof n && o(e.code) || (a = !0, this.closeArming(), c.abort(), this.fail(e instanceof n ? e : new n("INTERNAL", 0, String(e))));
+				if (!(a || p())) {
+					if (e instanceof n && o(e.code)) {
+						h();
+						return;
+					}
+					a = !0, this.closeArming(), c.abort(), this.fail(e instanceof n ? e : new n("INTERNAL", 0, String(e)));
+				}
 			});
 		}, _ = (e) => {
 			this.armSseTimer && clearTimeout(this.armSseTimer), this.armSseTimer = setTimeout(() => {
@@ -1968,7 +1984,7 @@ var lt = class {
 	}
 	async onResolved(e, t) {
 		if (this.destroyed || t !== this.loadGen) return;
-		this._descriptor = e, this.endedHandled = !1;
+		this._descriptor = e, this.endedHandled = !1, this._endedReason = null;
 		let n = await s(this.opts.credential);
 		if (this.destroyed || t !== this.loadGen) return;
 		this.setState("loading");
@@ -2067,7 +2083,7 @@ var lt = class {
 			matchUrn: this.opts.matchUrn,
 			credential: this.opts.credential,
 			onState: (t) => {
-				this.destroyed || e !== this.loadGen || (t.state === "gone" ? this.onStreamEnded(!0) : t.state === "ended" ? this.onStreamEnded() : t.state === "live" && this.endedHandled && this.scheduleRejoin(e));
+				this.destroyed || e !== this.loadGen || (t.state === "gone" ? this.onStreamEnded(!0, t.reason ?? "match_ended") : t.state === "ended" ? this.onStreamEnded(!1, t.reason) : t.state === "live" && this.endedHandled && this.scheduleRejoin(e));
 			},
 			onAlive: () => {
 				r = 0, i = !1;
@@ -2080,8 +2096,14 @@ var lt = class {
 	closeLiveState() {
 		this.liveStateSub?.close(), this.liveStateSub = null;
 	}
-	onStreamEnded(e = !1) {
-		this.destroyed || ((e || !this.rejoinEnabled()) && (this.cancelRejoin(), this.closeLiveState()), !this.endedHandled && (this.endedHandled = !0, this.stopRefresh(), this.engine?.stop(), this.setState("ended")));
+	onStreamEnded(e = !1, t) {
+		if (!this.destroyed) {
+			if ((e || !this.rejoinEnabled()) && (this.cancelRejoin(), this.closeLiveState()), this.endedHandled) {
+				t === "match_ended" && this._endedReason !== "match_ended" && (this._endedReason = t, this.emit("ended", t));
+				return;
+			}
+			this.endedHandled = !0, this._endedReason = t ?? null, this.stopRefresh(), this.engine?.stop(), this.setState("ended");
+		}
 	}
 	rejoinEnabled() {
 		return this.opts.rejoinOnLive !== !1 && this.opts.liveStateEvents !== !1;
@@ -2120,6 +2142,7 @@ var lt = class {
 			logoUrl: this.opts.theme?.logoUrl,
 			statusOverlays: this.opts.statusOverlays,
 			endedMessage: this.opts.endedMessage,
+			interruptedMessage: this.opts.interruptedMessage,
 			errorMessage: this.opts.errorMessage
 		});
 	}
@@ -2277,7 +2300,7 @@ var lt = class {
 			case "paused":
 				this.emit("paused");
 				break;
-			case "ended": this.emit("ended");
+			case "ended": this.emit("ended", this._endedReason ?? void 0);
 		}
 	}
 	emit(e, t) {