@glivion/square-screen-js-sdk 0.1.0 → 1.0.1

package/dist/index.mjs

@@ -0,0 +1,870 @@
+import { deleteDB, openDB } from "idb";
+//#region src/constants.ts
+/**
+* Production root URL for the SquareScreen REST API.
+*
+* {@link SquareScreenPlayer} uses this for all network requests. Integrators cannot
+* override it via player configuration; supply a custom {@link NetworkDataSource}
+* only if you must talk to a different host (e.g. tests or a private gateway).
+*/
+const SQUARESCREEN_API_BASE_URL = "https://square-screen-api-development-f7zuxa.laravel.cloud/api/v1";
+//#endregion
+//#region src/network/mappers.ts
+/** Maps a raw playlist item to the core PlaylistItem type. */
+function mapPlaylistItem(raw) {
+	return {
+		uuid: raw.uuid,
+		name: raw.name,
+		type: raw.type,
+		url: raw.url,
+		duration: raw.duration_seconds,
+		...raw.transition !== void 0 && { transition: raw.transition },
+		...raw.width !== void 0 && { width: raw.width },
+		...raw.height !== void 0 && { height: raw.height },
+		...raw.title !== void 0 && { title: raw.title },
+		...raw.thumbnail !== void 0 && { thumbnail: raw.thumbnail }
+	};
+}
+/**
+* Maps the raw strategy field to a PlaybackStrategy.
+* Returns undefined when the API sends an empty array instead of a real object.
+*/
+function mapPlaybackStrategy(raw) {
+	if (Array.isArray(raw)) return void 0;
+	return {
+		loop: raw.loop,
+		shuffle: raw.shuffle,
+		preloadCount: raw.preload_count ?? 0
+	};
+}
+/** Maps a raw playlist response to the core Playlist type. */
+function mapPlaylistResponse(raw) {
+	return {
+		uuid: raw.playlist.uuid,
+		items: raw.items.map(mapPlaylistItem),
+		strategy: mapPlaybackStrategy(raw.strategy),
+		schedule: raw.schedule,
+		playlistMeta: raw.playlist,
+		cachedAt: Date.now()
+	};
+}
+/**
+* Maps a raw emergency response to an EmergencyAlert.
+* Returns null when no emergency is active.
+*/
+function mapEmergencyResponse(raw) {
+	if (raw.emergency === null) return null;
+	return {
+		id: raw.emergency.id,
+		uuid: raw.emergency.uuid,
+		companyId: raw.emergency.company_id,
+		title: raw.emergency.title,
+		message: raw.emergency.message,
+		backgroundColor: raw.emergency.background_color,
+		textColor: raw.emergency.text_color,
+		targetScope: raw.emergency.target_scope,
+		isActive: raw.emergency.is_active,
+		startedAt: raw.emergency.started_at,
+		...raw.emergency.ended_at !== void 0 && { endedAt: raw.emergency.ended_at }
+	};
+}
+/** Maps a raw heartbeat acknowledgement to the core HeartbeatAck type. */
+function mapHeartbeatAck(raw) {
+	return { received: raw.received };
+}
+function mapHeartbeatPayload(raw) {
+	return {
+		cpu_usage: raw.cpuUsage,
+		memory_usage: raw.memoryUsage,
+		disk_usage: raw.diskUsage,
+		temperature: raw.temperature,
+		os_version: raw.osVersion,
+		app_version: raw.playerVersion
+	};
+}
+//#endregion
+//#region src/network/NetworkClient.ts
+/**
+* Handles all HTTP communication with the SquareScreen API.
+*
+* Implements {@link NetworkDataSource} and is the only class in the SDK
+* that calls `fetch` directly. Auth headers are injected automatically on
+* every request — callers never set them manually.
+*
+* This class is internal to the SDK. Consumers interact with it only through
+* the `NetworkDataSource` interface via the player module.
+*/
+var NetworkClient = class {
+	/**
+	* @param baseUrl     - Root URL of the SquareScreen API, e.g. `"https://api.squarescreen.io/api/v1"`.
+	* @param deviceId    - Unique identifier for this device.
+	* @param deviceToken - Secret token used to authenticate this device. Never log or expose this value.
+	*/
+	constructor(baseUrl, deviceId, deviceToken) {
+		this.baseUrl = baseUrl;
+		this.deviceId = deviceId;
+		this.deviceToken = deviceToken;
+	}
+	/**
+	* Central fetch wrapper used by all public methods.
+	*
+	* Injects auth headers, separates HTTP errors from network failures,
+	* and isolates JSON parse errors — so callers always receive a
+	* {@link SquareScreenResult} and never an uncaught exception.
+	*
+	* Error mapping:
+	* - 401/403 → `AuthError`
+	* - Other non-2xx → `NetworkError`
+	* - JSON parse failure → `ParseError`
+	* - `fetch` throw (no internet, CORS, timeout) → `NetworkError` with code `0`
+	*/
+	async fetchWrapper(endpoint, options) {
+		try {
+			const response = await fetch(`${this.baseUrl}${endpoint}`, {
+				...options,
+				headers: {
+					...options?.headers ?? {},
+					"Content-Type": "application/json",
+					"X-Device-Id": this.deviceId,
+					"X-Device-Token": this.deviceToken
+				}
+			});
+			if (!response.ok) {
+				if (response.status === 401) return {
+					success: false,
+					error: {
+						kind: "auth",
+						message: "Unauthorized"
+					}
+				};
+				if (response.status === 403) return {
+					success: false,
+					error: {
+						kind: "auth",
+						message: "Forbidden"
+					}
+				};
+				return {
+					success: false,
+					error: {
+						kind: "network",
+						code: response.status,
+						message: response.statusText || `HTTP error ${response.status}`
+					}
+				};
+			}
+			try {
+				return {
+					success: true,
+					data: await response.json()
+				};
+			} catch {
+				return {
+					success: false,
+					error: {
+						kind: "parse",
+						message: "Response could not be parsed as JSON"
+					}
+				};
+			}
+		} catch (err) {
+			return {
+				success: false,
+				error: {
+					kind: "network",
+					code: 0,
+					message: err instanceof Error ? err.message : "Network request failed"
+				}
+			};
+		}
+	}
+	/** Fetches the full active playlist for this device. */
+	async fetchPlaylist() {
+		const result = await this.fetchWrapper("/screen/now-playing", { method: "GET" });
+		if (!result.success) return result;
+		return {
+			success: true,
+			data: mapPlaylistResponse(result.data)
+		};
+	}
+	/** Fetches a playlist filtered to video items only. */
+	async fetchVideoPlaylist(params) {
+		const query = new URLSearchParams({
+			type: "video",
+			...params.category && { category: params.category },
+			...params.quality && { quality: params.quality },
+			...params.limit && { limit: String(params.limit) },
+			...params.tags && { tags: params.tags.join(",") }
+		});
+		const result = await this.fetchWrapper(`/screen/now-playing?${query}`, { method: "GET" });
+		if (!result.success) return result;
+		return {
+			success: true,
+			data: mapPlaylistResponse(result.data)
+		};
+	}
+	/** Fetches a playlist filtered to image items only. */
+	async fetchImagePlaylist(params) {
+		const query = new URLSearchParams({
+			type: "image",
+			...params.category && { category: params.category },
+			...params.limit && { limit: String(params.limit) },
+			...params.tags && { tags: params.tags.join(",") }
+		});
+		const result = await this.fetchWrapper(`/screen/now-playing?${query}`, { method: "GET" });
+		if (!result.success) return result;
+		return {
+			success: true,
+			data: mapPlaylistResponse(result.data)
+		};
+	}
+	/**
+	* Checks whether an emergency broadcast is currently active for this device.
+	* Resolves to `null` when no emergency is active.
+	*/
+	async checkForEmergencyAlert() {
+		const result = await this.fetchWrapper("/screen/emergency", { method: "GET" });
+		if (!result.success) return result;
+		return {
+			success: true,
+			data: mapEmergencyResponse(result.data)
+		};
+	}
+	/**
+	* Posts device health metrics to the server.
+	* The payload is mapped to snake_case before sending to match the API's expected format.
+	*
+	* @param payload - Collected device metrics. Hardware fields are optional;
+	*                  `playerVersion` is always required.
+	*/
+	async healthCheck(payload) {
+		const result = await this.fetchWrapper("/screen/heartbeat", {
+			method: "POST",
+			body: JSON.stringify(mapHeartbeatPayload(payload))
+		});
+		if (!result.success) return result;
+		return {
+			success: true,
+			data: mapHeartbeatAck(result.data)
+		};
+	}
+	/** Reports a playback event to the server.
+	* @param event - The playback event to report.
+	* @returns A result indicating whether the event was recorded successfully.
+	* @example
+	* const result = await networkClient.reportPlaybackEvent({
+	*   media_uuid: "mf-00000001-0000-0000-0000-000000000001",
+	*   playlist_uuid: "pl-00000001-0000-0000-0000-000000000001",
+	*   schedule_uuid: "sc-00000001-0000-0000-0000-000000000001",
+	*   started_at: "2026-04-28T07:05:00Z",
+	*   ended_at: "2026-04-28T07:05:10Z",
+	* });
+	*/
+	async reportPlaybackEvent(event) {
+		const result = await this.fetchWrapper("/screen/playback", {
+			method: "POST",
+			body: JSON.stringify(event)
+		});
+		if (!result.success) return result;
+		return {
+			success: true,
+			data: { recorded: result.data.recorded }
+		};
+	}
+};
+//#endregion
+//#region src/cache/SquareScreenCache.ts
+const DEFAULT_DB_NAME = "square-screen-cache";
+const DEFAULT_CACHE_NAME = "square-screen-cache";
+/**
+* Default {@link SquareScreenCacheProvider} backed by IndexedDB (playlist metadata)
+* and the Cache API (media blobs).
+*
+* **IndexedDB** — a single `playlists` object store holds one document per
+* playlist UUID. A private `_ttl` field (milliseconds) is stored alongside the
+* record and stripped before returning data to callers.
+*
+* **Cache API** — media files are stored under their original URL as the cache
+* key, matching the same URL-keyed approach used by the Android SDK's
+* `MediaFileCache`. Once a blob is retrieved from the Cache API it is wrapped
+* in a `URL.createObjectURL` handle that is kept in an in-memory map and reused
+* on subsequent calls to avoid redundant allocations. All handles are revoked
+* when {@link clear} is called.
+*
+* Integrators who need different storage behaviour (a service-worker cache,
+* an in-memory store for tests, a custom database) should implement
+* {@link SquareScreenCacheProvider} and pass it via
+* `SquareScreenPlayerConfig.cacheProvider`.
+*/
+var SquareScreenCache = class {
+	/**
+	* @param dbName    Name of the IndexedDB database. Override in tests to isolate state.
+	* @param cacheName Name of the Cache API bucket. Override in tests to isolate state.
+	*/
+	constructor({ dbName = DEFAULT_DB_NAME, cacheName = DEFAULT_CACHE_NAME } = {}) {
+		this.objectUrls = /* @__PURE__ */ new Map();
+		this.dbName = dbName;
+		this.cacheName = cacheName;
+	}
+	/** Opens (or lazily creates) the IndexedDB database with the `playlists` object store. */
+	openDB() {
+		return openDB(this.dbName, 1, { upgrade(db) {
+			if (!db.objectStoreNames.contains("playlists")) db.createObjectStore("playlists", { keyPath: "uuid" });
+		} });
+	}
+	/**
+	* Returns the cached playlist for the given UUID, or `null` if:
+	* - nothing has been stored for that UUID, or
+	* - the record's age exceeds its TTL and `allowStale` is `false`.
+	*
+	* @param uuid       The playlist UUID to look up.
+	* @param allowStale When `true`, expired records are returned as-is (useful
+	*                   for serving a fallback when the network is unreachable).
+	*/
+	async getPlaylist(uuid, allowStale = false) {
+		const record = await (await this.openDB()).get("playlists", uuid);
+		if (!record) return null;
+		if (!allowStale && Date.now() - record.cachedAt > record._ttl) return null;
+		const { _ttl, ...playlist } = record;
+		return playlist;
+	}
+	/**
+	* Persists a playlist to IndexedDB, overwriting any previous record with the
+	* same UUID. `cachedAt` is set to the current wall-clock time so that TTL
+	* checks in {@link getPlaylist} have an accurate baseline.
+	*
+	* @param playlist The playlist to store. Items are persisted inline as part
+	*                 of the same document — no separate per-item records.
+	* @param ttlMs    How long (in milliseconds) the record is considered fresh.
+	*                 Passed through `SquareScreenPlayerConfig.ttl` by the player.
+	*/
+	async savePlaylist(playlist, ttlMs) {
+		await (await this.openDB()).put("playlists", {
+			...playlist,
+			cachedAt: Date.now(),
+			_ttl: ttlMs
+		});
+	}
+	/**
+	* Returns a blob URL for the locally cached copy of `url`, or `null` if the
+	* media has not been downloaded yet.
+	*
+	* The blob URL is created once and stored in an in-memory map. Subsequent
+	* calls for the same `url` return the same handle without re-reading the
+	* Cache API, which avoids both I/O and unnecessary `URL.createObjectURL`
+	* allocations on long-running signage devices.
+	*
+	* @param url The original remote URL used as the Cache API key.
+	*/
+	async getMediaUrl(url) {
+		const existing = this.objectUrls.get(url);
+		if (existing) return existing;
+		const response = await (await caches.open(this.cacheName)).match(url);
+		if (!response) return null;
+		const blob = await response.blob();
+		const objectUrl = URL.createObjectURL(blob);
+		this.objectUrls.set(url, objectUrl);
+		return objectUrl;
+	}
+	/**
+	* Stores `blob` in the Cache API under `url` and returns a blob URL for
+	* immediate use by the renderer.
+	*
+	* Called by the player after a successful `fetch()` so that subsequent
+	* {@link getMediaUrl} calls for the same URL skip the network entirely.
+	*
+	* @param url  The original remote URL — used as the Cache API key so that
+	*             {@link getMediaUrl} can retrieve the entry with a simple `match`.
+	* @param blob The downloaded media blob to persist.
+	* @returns    A blob URL that the renderer can set as `src` on an
+	*             `<img>` or `<video>` element.
+	*/
+	async saveMedia(url, blob) {
+		await (await caches.open(this.cacheName)).put(url, new Response(blob));
+		const objectUrl = URL.createObjectURL(blob);
+		this.objectUrls.set(url, objectUrl);
+		return objectUrl;
+	}
+	/**
+	* Wipes all cached data:
+	* - Revokes every outstanding blob URL to release the underlying Blob references.
+	* - Deletes the IndexedDB database entirely (recreated on next access).
+	* - Removes all entries from the Cache API bucket.
+	*
+	* Useful for a "factory reset" flow or in tests to guarantee a clean slate.
+	*/
+	async clear() {
+		for (const url of this.objectUrls.values()) URL.revokeObjectURL(url);
+		this.objectUrls.clear();
+		(await this.openDB()).close();
+		await deleteDB(this.dbName);
+		const cache = await caches.open(this.cacheName);
+		const keys = await cache.keys();
+		await Promise.all(keys.map((req) => cache.delete(req)));
+	}
+};
+//#endregion
+//#region src/player/SquareScreenPlayer.ts
+const LAST_PLAYLIST_KEY = "square-screen:last-playlist-uuid";
+/**
+* Headless, framework-agnostic player that manages playlist fetching, caching,
+* item advancement, preloading, polling, and emergency alerts.
+*
+* Extends `EventTarget` — use `addEventListener` / `removeEventListener` to
+* react to player events. No DOM or rendering logic lives here.
+*
+* @example
+* const player = new SquareScreenPlayer({ deviceId, deviceToken, version: "1.0.0" });
+* player.addEventListener("itemchange", ({ detail }) => render(detail.item));
+* player.addEventListener("emergencyalert", ({ detail }) => showAlert(detail.alert));
+* await player.start();
+*/
+var SquareScreenPlayer = class extends EventTarget {
+	constructor(config) {
+		super();
+		this.playlist = null;
+		this.stopped = false;
+		this.currentIndex = 0;
+		this.status = "connecting";
+		this.activeAlert = null;
+		this.currentItemStartTime = null;
+		this.itemTimer = null;
+		this.playlistPollTimer = null;
+		this.emergencyPollTimer = null;
+		this.heartbeatTimer = null;
+		if (!config.networkDataSource) {
+			if (!config.deviceId) throw new Error("SquareScreenPlayer: deviceId is required.");
+			if (!config.deviceToken) throw new Error("SquareScreenPlayer: deviceToken is required.");
+		}
+		this.network = config.networkDataSource ?? new NetworkClient("https://square-screen-api-development-f7zuxa.laravel.cloud/api/v1", config.deviceId, config.deviceToken);
+		this.cache = config.cacheProvider ?? new SquareScreenCache();
+		const { networkDataSource: _n, cacheProvider: _c, ...rest } = config;
+		this.config = {
+			ttl: 300 * 1e3,
+			pollInterval: 3e4,
+			emergencyPollInterval: 15e3,
+			heartbeatInterval: 6e4,
+			...rest
+		};
+	}
+	/** The playlist item currently being displayed, or null if no playlist is loaded. */
+	get currentItem() {
+		return this.playlist?.items[this.currentIndex] ?? null;
+	}
+	/**
+	* Starts the player: fetches the playlist, begins playback, and starts polling
+	* and heartbeat intervals. Safe to await — resolves once the first playlist load
+	* attempt completes (whether from network or cache fallback).
+	*/
+	async start() {
+		this.stopped = false;
+		this.setStatus("connecting");
+		await this.loadPlaylist();
+		await this.checkEmergencyAlert();
+		this.startPolling();
+		this.startHeartbeat();
+	}
+	/** Stops all timers and clears internal state. Call this when tearing down the player. */
+	stop() {
+		if (this.itemTimer) clearTimeout(this.itemTimer);
+		if (this.playlistPollTimer) clearInterval(this.playlistPollTimer);
+		if (this.emergencyPollTimer) clearInterval(this.emergencyPollTimer);
+		if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+		this.itemTimer = null;
+		this.playlistPollTimer = null;
+		this.emergencyPollTimer = null;
+		this.heartbeatTimer = null;
+		this.stopped = true;
+		this.playlist = null;
+	}
+	/**
+	* Network-first playlist load. On success the playlist is saved to cache and
+	* applied if the UUID changed. On failure the player falls back to the last
+	* known playlist UUID stored in `localStorage`, loading it from cache with
+	* `allowStale = true` so it is served even after its TTL has expired.
+	*/
+	async loadPlaylist() {
+		const result = await this.network.fetchPlaylist();
+		if (result.success) {
+			this.setStatus("online");
+			const playlist = result.data;
+			localStorage.setItem(LAST_PLAYLIST_KEY, playlist.uuid);
+			await this.cache.savePlaylist(playlist, this.config.ttl);
+			if (!this.playlist || this.playlist.uuid !== playlist.uuid) await this.applyPlaylist(playlist);
+			else this.dispatch("playlistupdate", { playlist });
+		} else {
+			this.setStatus("offline");
+			if (!this.playlist) {
+				const lastUuid = localStorage.getItem(LAST_PLAYLIST_KEY);
+				if (lastUuid) {
+					const cached = await this.cache.getPlaylist(lastUuid, true);
+					if (cached) await this.applyPlaylist(cached);
+				}
+			}
+		}
+	}
+	/**
+	* Activates a playlist: optionally shuffles the items, resets the index to 0,
+	* emits `playlistupdate`, and kicks off the first `scheduleItem` call.
+	* Bails out immediately if `stop()` has been called.
+	*/
+	async applyPlaylist(playlist) {
+		if (this.stopped) return;
+		const items = playlist.strategy?.shuffle ? [...playlist.items].sort(() => Math.random() - .5) : playlist.items;
+		this.playlist = {
+			...playlist,
+			items
+		};
+		this.currentIndex = 0;
+		this.dispatch("playlistupdate", { playlist: this.playlist });
+		this.scheduleItem();
+	}
+	refreshPlaylist() {
+		this.loadPlaylist();
+	}
+	/**
+	* Emits `itemchange` immediately with either the cached blob URL or the raw
+	* HTTPS URL, then arms the advancement timer. Never blocks on a network fetch —
+	* if the media isn't cached yet the browser loads it directly while
+	* `preloadNext` / `downloadInBackground` cache it for the next cycle.
+	*
+	* Guards against `stop()` being called while awaiting the cache lookup.
+	*/
+	async scheduleItem() {
+		if (this.itemTimer) clearTimeout(this.itemTimer);
+		const item = this.currentItem;
+		if (!item || !this.playlist) return;
+		this.currentItemStartTime = Date.now();
+		const url = await this.cache.getMediaUrl(item.url) ?? item.url;
+		if (!this.playlist) return;
+		this.dispatch("itemchange", {
+			item: {
+				...item,
+				url
+			},
+			index: this.currentIndex,
+			total: this.playlist.items.length
+		});
+		if (url === item.url) this.downloadInBackground(item.url);
+		this.preloadNext();
+		const elapsed = Date.now() - this.currentItemStartTime;
+		const remaining = Math.max(0, item.duration * 1e3 - elapsed);
+		this.itemTimer = setTimeout(() => this.advance(), remaining);
+	}
+	/**
+	* Schedules background downloads for upcoming items while the current one
+	* is playing, so subsequent transitions can serve blob URLs immediately.
+	*
+	* - `preloadCount: 0` — disabled; nothing is downloaded.
+	* - `preloadCount: N` — downloads the next N items ahead (wraps at end).
+	* - `preloadCount` absent — downloads all items in the playlist up front.
+	*/
+	preloadNext() {
+		if (!this.playlist) return;
+		const preloadCount = this.playlist.strategy?.preloadCount;
+		if (preloadCount === 0) return;
+		const count = preloadCount ?? this.playlist.items.length;
+		for (let i = 1; i <= count; i++) {
+			const idx = (this.currentIndex + i) % this.playlist.items.length;
+			this.downloadInBackground(this.playlist.items[idx].url);
+		}
+	}
+	/**
+	* Fire-and-forget download. Checks the cache first; if the media is already
+	* present the call is a no-op. Errors are silently swallowed — a failed
+	* download is not fatal; the raw URL will be used until the next successful download.
+	*/
+	downloadInBackground(url) {
+		this.cache.getMediaUrl(url).then((cached) => {
+			if (cached || !this.playlist) return;
+			return fetch(url, { mode: "cors" }).then((r) => r.ok ? r.blob() : Promise.reject(/* @__PURE__ */ new Error(`HTTP ${r.status}`))).then((blob) => this.cache.saveMedia(url, blob));
+		}).catch(() => {});
+	}
+	/**
+	* Moves to the next item. Reports the completed playback event, then either
+	* wraps back to index 0 (when `loop` is true or absent) or halts when
+	* `loop: false` and the last item has finished.
+	*/
+	advance() {
+		if (!this.playlist) return;
+		const total = this.playlist.items.length;
+		const next = this.currentIndex + 1;
+		this.reportPlaybackEvent();
+		if (next >= total) if (this.playlist.strategy?.loop ?? true) this.currentIndex = 0;
+		else return;
+		else this.currentIndex = next;
+		this.scheduleItem();
+	}
+	/** Sends a proof-of-play event to the server. Fire-and-forget; failures are not surfaced. */
+	async reportPlaybackEvent() {
+		if (!this.currentItemStartTime) return;
+		if (!this.currentItem || !this.playlist) return;
+		const endedAt = Date.now();
+		const event = {
+			media_uuid: this.currentItem.uuid,
+			playlist_uuid: this.playlist.uuid,
+			schedule_uuid: this.playlist.schedule?.uuid ?? "",
+			started_at: new Date(this.currentItemStartTime).toISOString(),
+			ended_at: new Date(endedAt).toISOString(),
+			duration_seconds: Math.round((endedAt - this.currentItemStartTime) / 1e3),
+			completed: true
+		};
+		this.network.reportPlaybackEvent(event);
+	}
+	/** Arms the playlist-refresh and emergency-alert polling intervals. */
+	startPolling() {
+		this.playlistPollTimer = setInterval(() => this.loadPlaylist(), this.config.pollInterval);
+		this.emergencyPollTimer = setInterval(() => this.checkEmergencyAlert(), this.config.emergencyPollInterval);
+	}
+	/** Arms the periodic heartbeat that keeps the device registration alive. */
+	startHeartbeat() {
+		this.heartbeatTimer = setInterval(async () => {
+			await this.network.healthCheck({ playerVersion: this.config.version });
+		}, this.config.heartbeatInterval);
+	}
+	/**
+	* Polls the server for an active emergency alert. Emits `emergencyalert` only
+	* when the state actually changes (alert activated, cleared, or replaced by a
+	* different UUID) to avoid redundant re-renders on the consumer side.
+	*/
+	async checkEmergencyAlert() {
+		const result = await this.network.checkForEmergencyAlert();
+		if (!result.success) return;
+		const incoming = result.data;
+		const wasActive = this.activeAlert !== null;
+		const isActive = incoming !== null;
+		const alertChanged = isActive && incoming.uuid !== this.activeAlert?.uuid;
+		if (wasActive !== isActive || alertChanged) {
+			this.activeAlert = incoming;
+			this.dispatch("emergencyalert", { alert: incoming });
+		}
+	}
+	setStatus(status) {
+		if (this.status === status) return;
+		this.status = status;
+		this.dispatch("statuschange", { status });
+	}
+	dispatch(type, detail) {
+		this.dispatchEvent(new CustomEvent(type, { detail }));
+	}
+	addEventListener(type, listener, options) {
+		super.addEventListener(type, listener, options);
+	}
+	removeEventListener(type, listener, options) {
+		super.removeEventListener(type, listener, options);
+	}
+};
+//#endregion
+//#region src/renderer/SquareScreenRenderer.ts
+/**
+* Optional vanilla JS renderer that wires a {@link SquareScreenPlayer} to a DOM container.
+* Handles `<img>` / `<video>` element lifecycle, autoplay, transitions, and emergency alerts.
+*
+* When an emergency alert is active it renders a full-screen overlay on top of all content.
+* Normal playback resumes automatically once the alert is cleared.
+*
+* @example
+* const player = new SquareScreenPlayer({ ... });
+* const renderer = new SquareScreenRenderer(document.getElementById("screen"), player);
+* renderer.mount();
+* await player.start();
+*
+* // Tear down
+* player.stop();
+* renderer.unmount();
+*/
+var SquareScreenRenderer = class {
+	constructor(container, player, config = {}) {
+		this.wrapper = null;
+		this.slots = null;
+		this.activeSlot = 0;
+		this.alertOverlay = null;
+		this.container = container;
+		this.player = player;
+		this.config = {
+			defaultTransition: "none",
+			transitionDuration: 500,
+			canPlayTimeout: 3e3,
+			...config
+		};
+		this.onItemChange = (e) => this.handleItemChange(e.detail.item);
+		this.onEmergencyAlert = (e) => this.handleEmergencyAlert(e.detail.alert);
+	}
+	/** Injects the renderer DOM into the container and begins listening to the player. */
+	mount() {
+		this.buildDOM();
+		this.player.addEventListener("itemchange", this.onItemChange);
+		this.player.addEventListener("emergencyalert", this.onEmergencyAlert);
+	}
+	/** Removes the renderer DOM and stops listening to the player. */
+	unmount() {
+		this.player.removeEventListener("itemchange", this.onItemChange);
+		this.player.removeEventListener("emergencyalert", this.onEmergencyAlert);
+		if (this.wrapper && this.container.contains(this.wrapper)) this.container.removeChild(this.wrapper);
+		this.wrapper = null;
+		this.slots = null;
+	}
+	buildDOM() {
+		this.wrapper = document.createElement("div");
+		Object.assign(this.wrapper.style, {
+			position: "relative",
+			width: "100%",
+			height: "100%",
+			overflow: "hidden",
+			backgroundColor: "#000"
+		});
+		const slotA = this.createSlot(true);
+		const slotB = this.createSlot(false);
+		this.wrapper.appendChild(slotA);
+		this.wrapper.appendChild(slotB);
+		this.slots = [slotA, slotB];
+		this.alertOverlay = document.createElement("div");
+		Object.assign(this.alertOverlay.style, {
+			display: "none",
+			position: "absolute",
+			top: "0",
+			right: "0",
+			bottom: "0",
+			left: "0",
+			zIndex: "9999",
+			flexDirection: "column",
+			alignItems: "center",
+			justifyContent: "center",
+			padding: "2rem",
+			textAlign: "center",
+			boxSizing: "border-box"
+		});
+		this.wrapper.appendChild(this.alertOverlay);
+		this.container.appendChild(this.wrapper);
+	}
+	createSlot(visible) {
+		const slot = document.createElement("div");
+		Object.assign(slot.style, {
+			position: "absolute",
+			top: "0",
+			right: "0",
+			bottom: "0",
+			left: "0",
+			display: "flex",
+			alignItems: "center",
+			justifyContent: "center",
+			opacity: visible ? "1" : "0",
+			transition: `opacity ${this.config.transitionDuration}ms ease`
+		});
+		return slot;
+	}
+	async handleItemChange(item) {
+		if (!this.slots) return;
+		const nextIndex = (this.activeSlot + 1) % 2;
+		const currentSlot = this.slots[this.activeSlot];
+		const nextSlot = this.slots[nextIndex];
+		nextSlot.innerHTML = "";
+		const media = item.type === "video" ? this.createVideo(item.url) : this.createImage(item.url);
+		nextSlot.appendChild(media);
+		if (item.type === "video") await this.waitForCanPlay(media);
+		const transitionType = item.transition ?? this.config.defaultTransition;
+		await this.applyTransition(currentSlot, nextSlot, transitionType);
+		this.activeSlot = nextIndex;
+	}
+	handleEmergencyAlert(alert) {
+		if (!this.alertOverlay) return;
+		if (!alert) {
+			this.alertOverlay.style.display = "none";
+			this.alertOverlay.innerHTML = "";
+			return;
+		}
+		this.alertOverlay.style.display = "flex";
+		this.alertOverlay.style.backgroundColor = alert.backgroundColor;
+		this.alertOverlay.style.color = alert.textColor;
+		const title = document.createElement("h1");
+		title.textContent = alert.title;
+		Object.assign(title.style, {
+			margin: "0 0 1rem",
+			fontSize: "2.5rem",
+			fontWeight: "bold"
+		});
+		const message = document.createElement("p");
+		message.textContent = alert.message;
+		Object.assign(message.style, {
+			margin: "0",
+			fontSize: "1.5rem"
+		});
+		this.alertOverlay.innerHTML = "";
+		this.alertOverlay.appendChild(title);
+		this.alertOverlay.appendChild(message);
+	}
+	createImage(src) {
+		const img = document.createElement("img");
+		Object.assign(img.style, {
+			maxWidth: "100%",
+			maxHeight: "100%",
+			objectFit: "contain"
+		});
+		img.src = src;
+		return img;
+	}
+	createVideo(src) {
+		const video = document.createElement("video");
+		Object.assign(video.style, {
+			width: "100%",
+			height: "100%",
+			objectFit: "contain"
+		});
+		video.src = src;
+		video.autoplay = true;
+		video.muted = true;
+		video.playsInline = true;
+		video.loop = true;
+		return video;
+	}
+	waitForCanPlay(video) {
+		return new Promise((resolve) => {
+			if (video.readyState >= HTMLMediaElement.HAVE_FUTURE_DATA) {
+				resolve();
+				return;
+			}
+			const timeout = this.config.canPlayTimeout;
+			const timer = timeout > 0 ? setTimeout(resolve, timeout) : null;
+			const handler = () => {
+				if (timer) clearTimeout(timer);
+				video.removeEventListener("canplay", handler);
+				resolve();
+			};
+			video.addEventListener("canplay", handler);
+		});
+	}
+	async applyTransition(from, to, type) {
+		const duration = this.config.transitionDuration;
+		if (type === "none" || duration === 0) {
+			from.style.opacity = "0";
+			to.style.opacity = "1";
+		} else if (type === "fade") {
+			to.style.opacity = "1";
+			from.style.opacity = "0";
+			await this.wait(duration);
+		} else if (type === "slide") {
+			to.style.transition = "none";
+			to.style.transform = "translateX(100%)";
+			to.style.opacity = "1";
+			to.offsetWidth;
+			to.style.transition = `transform ${duration}ms ease`;
+			from.style.transition = `transform ${duration}ms ease`;
+			to.style.transform = "translateX(0)";
+			from.style.transform = "translateX(-100%)";
+			await this.wait(duration);
+		}
+		from.style.transition = `opacity ${duration}ms ease`;
+		from.style.transform = "";
+		from.style.opacity = "0";
+		to.style.transition = `opacity ${duration}ms ease`;
+		to.style.transform = "";
+		to.style.opacity = "1";
+	}
+	wait(ms) {
+		return new Promise((resolve) => setTimeout(resolve, ms));
+	}
+};
+//#endregion
+export { SQUARESCREEN_API_BASE_URL, SquareScreenCache, SquareScreenPlayer, SquareScreenRenderer };
+
+//# sourceMappingURL=index.mjs.map