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

package/src/__tests__/player/SquareScreenPlayer.test.ts

@@ -1,840 +0,0 @@
-// @vitest-environment jsdom
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import type {
-  EmergencyAlert,
-  NetworkDataSource,
-  Playlist,
-  SquareScreenCacheProvider,
-} from "../../core/types";
-import { SquareScreenPlayer } from "../../player/SquareScreenPlayer";
-
-// ---------------------------------------------------------------------------
-// Factories
-// ---------------------------------------------------------------------------
-
-function makeItem(
-  overrides: Partial<Playlist["items"][number]> = {},
-): Playlist["items"][number] {
-  return {
-    uuid: "item-1",
-    name: "Item 1",
-    type: "image",
-    url: "https://cdn.example.com/1.jpg",
-    duration: 5,
-    ...overrides,
-  };
-}
-
-function makePlaylist(overrides: Partial<Playlist> = {}): Playlist {
-  return {
-    uuid: "playlist-1",
-    cachedAt: Date.now(),
-    strategy: { loop: true, shuffle: false, preloadCount: 0 },
-    items: [makeItem()],
-    ...overrides,
-  };
-}
-
-function makeAlert(overrides: Partial<EmergencyAlert> = {}): EmergencyAlert {
-  return {
-    id: 1,
-    uuid: "alert-1",
-    companyId: 42,
-    title: "Emergency",
-    message: "Stay indoors",
-    backgroundColor: "#FF0000",
-    textColor: "#FFFFFF",
-    targetScope: "all",
-    isActive: true,
-    startedAt: new Date().toISOString(),
-    ...overrides,
-  };
-}
-
-function makeNetwork(playlist: Playlist = makePlaylist()): NetworkDataSource {
-  return {
-    fetchPlaylist: vi.fn().mockResolvedValue({ success: true, data: playlist }),
-    fetchVideoPlaylist: vi.fn().mockResolvedValue({ success: true, data: playlist }),
-    fetchImagePlaylist: vi.fn().mockResolvedValue({ success: true, data: playlist }),
-    checkForEmergencyAlert: vi.fn().mockResolvedValue({ success: true, data: null }),
-    healthCheck: vi.fn().mockResolvedValue({ success: true, data: { received: true } }),
-    reportPlaybackEvent: vi
-      .fn()
-      .mockResolvedValue({ success: true, data: { recorded: true } }),
-  };
-}
-
-function makeCache(): SquareScreenCacheProvider {
-  return {
-    getPlaylist: vi.fn().mockResolvedValue(null),
-    savePlaylist: vi.fn().mockResolvedValue(undefined),
-    getMediaUrl: vi.fn().mockResolvedValue(null),
-    saveMedia: vi.fn().mockResolvedValue("blob:mock"),
-    clear: vi.fn().mockResolvedValue(undefined),
-  };
-}
-
-/** Shared config defaults — override per-test as needed. */
-function makeConfig(
-  network: NetworkDataSource,
-  cache: SquareScreenCacheProvider,
-  overrides: Record<string, unknown> = {},
-) {
-  return {
-    deviceId: "unused",
-    deviceToken: "unused",
-    version: "1.0.0",
-    pollInterval: 30_000,
-    emergencyPollInterval: 15_000,
-    heartbeatInterval: 60_000,
-    networkDataSource: network,
-    cacheProvider: cache,
-    ...overrides,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Setup / teardown
-// ---------------------------------------------------------------------------
-
-beforeEach(() => {
-  vi.useFakeTimers();
-  vi.stubGlobal(
-    "fetch",
-    vi.fn().mockResolvedValue({
-      ok: true,
-      blob: () => Promise.resolve(new Blob(["data"], { type: "image/jpeg" })),
-    }),
-  );
-});
-
-afterEach(() => {
-  vi.clearAllTimers();
-  vi.useRealTimers();
-  vi.unstubAllGlobals();
-  vi.restoreAllMocks();
-  localStorage.clear();
-});
-
-// ---------------------------------------------------------------------------
-// Initialization guards
-// ---------------------------------------------------------------------------
-
-describe("initialization", () => {
-  it("throws if deviceId is missing and no networkDataSource is provided", () => {
-    expect(() => new SquareScreenPlayer({
-      deviceId: "",
-      deviceToken: "tok-1",
-      version: "1.0.0",
-    })).toThrow("deviceId is required");
-  });
-
-  it("throws if deviceToken is missing and no networkDataSource is provided", () => {
-    expect(() => new SquareScreenPlayer({
-      deviceId: "dev-1",
-      deviceToken: "",
-      version: "1.0.0",
-    })).toThrow("deviceToken is required");
-  });
-
-  it("does not throw when credentials are missing if networkDataSource is provided", () => {
-    expect(() => new SquareScreenPlayer({
-      deviceId: "",
-      deviceToken: "",
-      version: "1.0.0",
-      networkDataSource: makeNetwork(),
-    })).not.toThrow();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Startup
-// ---------------------------------------------------------------------------
-
-describe("startup", () => {
-  it("emits statuschange → online, playlistupdate and itemchange on a successful fetch", async () => {
-    const network = makeNetwork();
-    const cache = makeCache();
-    const player = new SquareScreenPlayer(makeConfig(network, cache));
-
-    const statuschange = vi.fn();
-    const playlistupdate = vi.fn();
-    const itemchange = vi.fn();
-    player.addEventListener("statuschange", statuschange);
-    player.addEventListener("playlistupdate", playlistupdate);
-    player.addEventListener("itemchange", itemchange);
-
-    await player.start();
-
-    expect(statuschange).toHaveBeenCalledTimes(1);
-    expect(statuschange.mock.calls[0][0].detail.status).toBe("online");
-    expect(playlistupdate).toHaveBeenCalledTimes(1);
-    expect(itemchange).toHaveBeenCalledTimes(1);
-    expect(player.currentItem?.uuid).toBe("item-1");
-
-    player.stop();
-  });
-
-  it("emits statuschange → offline and no itemchange when the network fetch fails and there is no cached fallback", async () => {
-    const network = makeNetwork();
-    network.fetchPlaylist = vi
-      .fn()
-      .mockResolvedValue({ success: false, error: { kind: "network", code: 0, message: "down" } });
-
-    const cache = makeCache();
-    const player = new SquareScreenPlayer(makeConfig(network, cache));
-
-    const statuschange = vi.fn();
-    const itemchange = vi.fn();
-    player.addEventListener("statuschange", statuschange);
-    player.addEventListener("itemchange", itemchange);
-
-    await player.start();
-
-    expect(statuschange.mock.calls[0][0].detail.status).toBe("offline");
-    expect(itemchange).not.toHaveBeenCalled();
-
-    player.stop();
-  });
-
-  it("does not emit a duplicate statuschange when the status is unchanged between polls", async () => {
-    const network = makeNetwork();
-    const cache = makeCache();
-    const player = new SquareScreenPlayer(
-      makeConfig(network, cache, { pollInterval: 1_000 }),
-    );
-
-    const statuschange = vi.fn();
-    player.addEventListener("statuschange", statuschange);
-
-    await player.start();
-    expect(statuschange).toHaveBeenCalledTimes(1); // connecting → online
-
-    await vi.advanceTimersByTimeAsync(1_000); // trigger poll — still online
-    expect(statuschange).toHaveBeenCalledTimes(1); // no second event
-
-    player.stop();
-  });
-
-  it("saves the playlist to cache with the configured TTL", async () => {
-    const network = makeNetwork();
-    const cache = makeCache();
-    const player = new SquareScreenPlayer(
-      makeConfig(network, cache, { ttl: 120_000 }),
-    );
-
-    await player.start();
-
-    expect(cache.savePlaylist).toHaveBeenCalledWith(
-      expect.objectContaining({ uuid: "playlist-1" }),
-      120_000,
-    );
-
-    player.stop();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Media resolution
-// ---------------------------------------------------------------------------
-
-describe("media resolution", () => {
-  it("serves a blob URL from cache without hitting the network", async () => {
-    const network = makeNetwork();
-    const cache = makeCache();
-    vi.mocked(cache.getMediaUrl).mockResolvedValue("blob:cached");
-
-    const player = new SquareScreenPlayer(makeConfig(network, cache));
-    const itemchange = vi.fn();
-    player.addEventListener("itemchange", itemchange);
-
-    await player.start();
-
-    expect(fetch).not.toHaveBeenCalled();
-    expect(itemchange.mock.calls[0][0].detail.item.url).toBe("blob:cached");
-
-    player.stop();
-  });
-
-  it("dispatches the raw URL immediately on a cache miss and downloads in background", async () => {
-    const network = makeNetwork();
-    const cache = makeCache();
-
-    const player = new SquareScreenPlayer(makeConfig(network, cache));
-    const itemchange = vi.fn();
-    player.addEventListener("itemchange", itemchange);
-
-    await player.start();
-
-    // itemchange fires immediately with the raw URL — no inline fetch blocks it
-    expect(itemchange).toHaveBeenCalledTimes(1);
-    expect(itemchange.mock.calls[0][0].detail.item.url).toBe("https://cdn.example.com/1.jpg");
-
-    // background download is triggered (fire-and-forget)
-    expect(fetch).toHaveBeenCalledWith("https://cdn.example.com/1.jpg", { mode: "cors" });
-
-    player.stop();
-  });
-
-  it("falls back to the raw URL when fetch throws", async () => {
-    vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("offline")));
-
-    const network = makeNetwork();
-    const cache = makeCache();
-    const player = new SquareScreenPlayer(makeConfig(network, cache));
-    const itemchange = vi.fn();
-    player.addEventListener("itemchange", itemchange);
-
-    await player.start();
-
-    expect(itemchange.mock.calls[0][0].detail.item.url).toBe(
-      "https://cdn.example.com/1.jpg",
-    );
-
-    player.stop();
-  });
-
-  it("falls back to the raw URL when fetch returns a non-OK status", async () => {
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockResolvedValue({ ok: false, status: 403, blob: vi.fn() }),
-    );
-
-    const network = makeNetwork();
-    const cache = makeCache();
-    const player = new SquareScreenPlayer(makeConfig(network, cache));
-    const itemchange = vi.fn();
-    player.addEventListener("itemchange", itemchange);
-
-    await player.start();
-
-    expect(itemchange.mock.calls[0][0].detail.item.url).toBe(
-      "https://cdn.example.com/1.jpg",
-    );
-    expect(cache.saveMedia).not.toHaveBeenCalled();
-
-    player.stop();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Offline fallback
-// ---------------------------------------------------------------------------
-
-describe("offline fallback", () => {
-  it("loads the stale cached playlist when the network fails", async () => {
-    const fallback = makePlaylist({
-      uuid: "cached-playlist",
-      items: [makeItem({ uuid: "cached-item", url: "https://cdn.example.com/cached.jpg" })],
-    });
-
-    const network = makeNetwork();
-    network.fetchPlaylist = vi
-      .fn()
-      .mockResolvedValue({ success: false, error: { kind: "network", code: 0, message: "down" } });
-
-    const cache = makeCache();
-    vi.mocked(cache.getPlaylist).mockResolvedValueOnce(fallback);
-    localStorage.setItem("square-screen:last-playlist-uuid", "cached-playlist");
-
-    const player = new SquareScreenPlayer(makeConfig(network, cache));
-    const itemchange = vi.fn();
-    player.addEventListener("itemchange", itemchange);
-
-    await player.start();
-
-    expect(cache.getPlaylist).toHaveBeenCalledWith("cached-playlist", true);
-    expect(itemchange).toHaveBeenCalledTimes(1);
-    expect(player.currentItem?.uuid).toBe("cached-item");
-
-    player.stop();
-  });
-
-  it("emits no itemchange when the network fails and no last-UUID is stored", async () => {
-    const network = makeNetwork();
-    network.fetchPlaylist = vi
-      .fn()
-      .mockResolvedValue({ success: false, error: { kind: "network", code: 0, message: "down" } });
-
-    const player = new SquareScreenPlayer(makeConfig(network, makeCache()));
-    const itemchange = vi.fn();
-    player.addEventListener("itemchange", itemchange);
-
-    await player.start();
-
-    expect(itemchange).not.toHaveBeenCalled();
-
-    player.stop();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Item advancement
-// ---------------------------------------------------------------------------
-
-describe("item advancement", () => {
-  it("advances to the next item after the duration timer fires", async () => {
-    const playlist = makePlaylist({
-      items: [
-        makeItem({ uuid: "item-1", url: "https://cdn.example.com/1.jpg", duration: 5 }),
-        makeItem({ uuid: "item-2", url: "https://cdn.example.com/2.jpg", duration: 3 }),
-      ],
-    });
-
-    const network = makeNetwork(playlist);
-    const cache = makeCache();
-    const player = new SquareScreenPlayer(makeConfig(network, cache));
-    const itemchange = vi.fn();
-    player.addEventListener("itemchange", itemchange);
-
-    await player.start();
-    expect(itemchange).toHaveBeenCalledTimes(1);
-    expect(itemchange.mock.calls[0][0].detail.item.uuid).toBe("item-1");
-
-    await vi.advanceTimersByTimeAsync(5_000);
-
-    expect(itemchange).toHaveBeenCalledTimes(2);
-    expect(itemchange.mock.calls[1][0].detail.item.uuid).toBe("item-2");
-
-    player.stop();
-  });
-
-  it("loops back to item 0 after the last item when loop is true", async () => {
-    const playlist = makePlaylist({
-      items: [
-        makeItem({ uuid: "item-1", duration: 2 }),
-        makeItem({ uuid: "item-2", duration: 2 }),
-      ],
-      strategy: { loop: true, shuffle: false, preloadCount: 0 },
-    });
-
-    const network = makeNetwork(playlist);
-    const player = new SquareScreenPlayer(makeConfig(network, makeCache()));
-    const itemchange = vi.fn();
-    player.addEventListener("itemchange", itemchange);
-
-    await player.start();
-    await vi.advanceTimersByTimeAsync(2_000); // → item-2
-    await vi.advanceTimersByTimeAsync(2_000); // → item-1 (loop)
-
-    expect(itemchange).toHaveBeenCalledTimes(3);
-    expect(itemchange.mock.calls[2][0].detail.item.uuid).toBe("item-1");
-
-    player.stop();
-  });
-
-  it("stops after the last item when loop is false", async () => {
-    const playlist = makePlaylist({
-      items: [
-        makeItem({ uuid: "item-1", duration: 2 }),
-        makeItem({ uuid: "item-2", duration: 2 }),
-      ],
-      strategy: { loop: false, shuffle: false, preloadCount: 0 },
-    });
-
-    const network = makeNetwork(playlist);
-    const player = new SquareScreenPlayer(makeConfig(network, makeCache()));
-    const itemchange = vi.fn();
-    player.addEventListener("itemchange", itemchange);
-
-    await player.start();
-    await vi.advanceTimersByTimeAsync(2_000); // → item-2
-    await vi.advanceTimersByTimeAsync(2_000); // end — no more itemchange
-
-    expect(itemchange).toHaveBeenCalledTimes(2);
-    expect(itemchange.mock.calls[1][0].detail.item.uuid).toBe("item-2");
-
-    player.stop();
-  });
-
-  it("reports a playback event to the network when advancing", async () => {
-    const playlist = makePlaylist({
-      items: [
-        makeItem({ uuid: "item-1", duration: 3 }),
-        makeItem({ uuid: "item-2", duration: 3 }),
-      ],
-    });
-
-    const network = makeNetwork(playlist);
-    const player = new SquareScreenPlayer(makeConfig(network, makeCache()));
-
-    await player.start();
-    await vi.advanceTimersByTimeAsync(3_000);
-
-    expect(network.reportPlaybackEvent).toHaveBeenCalledWith(
-      expect.objectContaining({
-        media_uuid: "item-1",
-        playlist_uuid: "playlist-1",
-        completed: true,
-      }),
-    );
-
-    player.stop();
-  });
-
-  it("emits itemchange with the correct index and total", async () => {
-    const playlist = makePlaylist({
-      items: [
-        makeItem({ uuid: "item-1", duration: 2 }),
-        makeItem({ uuid: "item-2", duration: 2 }),
-        makeItem({ uuid: "item-3", duration: 2 }),
-      ],
-    });
-
-    const network = makeNetwork(playlist);
-    const player = new SquareScreenPlayer(makeConfig(network, makeCache()));
-    const itemchange = vi.fn();
-    player.addEventListener("itemchange", itemchange);
-
-    await player.start();
-    await vi.advanceTimersByTimeAsync(2_000);
-
-    const detail = itemchange.mock.calls[1][0].detail;
-    expect(detail.index).toBe(1);
-    expect(detail.total).toBe(3);
-
-    player.stop();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Polling
-// ---------------------------------------------------------------------------
-
-describe("polling", () => {
-  it("calls fetchPlaylist again after the poll interval", async () => {
-    const network = makeNetwork();
-    const cache = makeCache();
-    const player = new SquareScreenPlayer(
-      makeConfig(network, cache, { pollInterval: 5_000 }),
-    );
-
-    await player.start();
-    expect(network.fetchPlaylist).toHaveBeenCalledTimes(1);
-
-    await vi.advanceTimersByTimeAsync(5_000);
-    expect(network.fetchPlaylist).toHaveBeenCalledTimes(2);
-
-    player.stop();
-  });
-
-  it("emits playlistupdate but not a new itemchange when the same UUID is re-fetched", async () => {
-    // Use a long duration so the item-advance timer doesn't fire before the poll.
-    const playlist = makePlaylist({ items: [makeItem({ duration: 3600 })] });
-    const network = makeNetwork(playlist);
-    const cache = makeCache();
-    const player = new SquareScreenPlayer(
-      makeConfig(network, cache, { pollInterval: 1_000 }),
-    );
-
-    const itemchange = vi.fn();
-    const playlistupdate = vi.fn();
-    player.addEventListener("itemchange", itemchange);
-    player.addEventListener("playlistupdate", playlistupdate);
-
-    await player.start();
-    expect(itemchange).toHaveBeenCalledTimes(1);
-    expect(playlistupdate).toHaveBeenCalledTimes(1);
-
-    await vi.advanceTimersByTimeAsync(1_000);
-
-    expect(playlistupdate).toHaveBeenCalledTimes(2);
-    expect(itemchange).toHaveBeenCalledTimes(1); // same UUID → no reset
-
-    player.stop();
-  });
-
-  it("restarts playback from item 0 when a new playlist UUID is fetched", async () => {
-    const first = makePlaylist({ uuid: "playlist-1", items: [makeItem({ duration: 3600 })] });
-    const second = makePlaylist({
-      uuid: "playlist-2",
-      items: [makeItem({ uuid: "new-item" })],
-    });
-
-    const network = makeNetwork(first);
-    const cache = makeCache();
-    const player = new SquareScreenPlayer(
-      makeConfig(network, cache, { pollInterval: 1_000 }),
-    );
-
-    const itemchange = vi.fn();
-    player.addEventListener("itemchange", itemchange);
-
-    await player.start();
-    expect(itemchange).toHaveBeenCalledTimes(1);
-
-    vi.mocked(network.fetchPlaylist).mockResolvedValue({ success: true, data: second });
-    await vi.advanceTimersByTimeAsync(1_000);
-
-    expect(itemchange).toHaveBeenCalledTimes(2);
-    expect(itemchange.mock.calls[1][0].detail.item.uuid).toBe("new-item");
-
-    player.stop();
-  });
-
-  it("refreshPlaylist() triggers an immediate fetch outside the poll interval", async () => {
-    const network = makeNetwork();
-    const player = new SquareScreenPlayer(makeConfig(network, makeCache()));
-
-    await player.start();
-    expect(network.fetchPlaylist).toHaveBeenCalledTimes(1);
-
-    player.refreshPlaylist();
-    await Promise.resolve();
-
-    expect(network.fetchPlaylist).toHaveBeenCalledTimes(2);
-
-    player.stop();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Emergency alerts
-// ---------------------------------------------------------------------------
-
-describe("emergency alerts", () => {
-  it("does not emit emergencyalert when no alert is active", async () => {
-    const network = makeNetwork();
-    const player = new SquareScreenPlayer(makeConfig(network, makeCache()));
-    const emergencyalert = vi.fn();
-    player.addEventListener("emergencyalert", emergencyalert);
-
-    await player.start();
-
-    expect(emergencyalert).not.toHaveBeenCalled();
-
-    player.stop();
-  });
-
-  it("emits emergencyalert when an alert becomes active", async () => {
-    const alert = makeAlert();
-    const network = makeNetwork();
-    network.checkForEmergencyAlert = vi
-      .fn()
-      .mockResolvedValueOnce({ success: true, data: null })
-      .mockResolvedValue({ success: true, data: alert });
-
-    const player = new SquareScreenPlayer(
-      makeConfig(network, makeCache(), { emergencyPollInterval: 1_000 }),
-    );
-    const emergencyalert = vi.fn();
-    player.addEventListener("emergencyalert", emergencyalert);
-
-    await player.start();
-    await vi.advanceTimersByTimeAsync(1_000);
-
-    expect(emergencyalert).toHaveBeenCalledTimes(1);
-    expect(emergencyalert.mock.calls[0][0].detail.alert.uuid).toBe("alert-1");
-
-    player.stop();
-  });
-
-  it("emits emergencyalert with null when the alert is cleared", async () => {
-    const alert = makeAlert();
-    const network = makeNetwork();
-    network.checkForEmergencyAlert = vi
-      .fn()
-      .mockResolvedValueOnce({ success: true, data: alert })   // startup → alert active
-      .mockResolvedValue({ success: true, data: null });        // poll → cleared
-
-    const player = new SquareScreenPlayer(
-      makeConfig(network, makeCache(), { emergencyPollInterval: 1_000 }),
-    );
-    const emergencyalert = vi.fn();
-    player.addEventListener("emergencyalert", emergencyalert);
-
-    await player.start(); // fires alert
-    await vi.advanceTimersByTimeAsync(1_000); // fires null (cleared)
-
-    expect(emergencyalert).toHaveBeenCalledTimes(2);
-    expect(emergencyalert.mock.calls[1][0].detail.alert).toBeNull();
-
-    player.stop();
-  });
-
-  it("does not emit emergencyalert again when the same alert persists across polls", async () => {
-    const alert = makeAlert();
-    const network = makeNetwork();
-    network.checkForEmergencyAlert = vi
-      .fn()
-      .mockResolvedValue({ success: true, data: alert });
-
-    const player = new SquareScreenPlayer(
-      makeConfig(network, makeCache(), { emergencyPollInterval: 1_000 }),
-    );
-    const emergencyalert = vi.fn();
-    player.addEventListener("emergencyalert", emergencyalert);
-
-    await player.start();
-    await vi.advanceTimersByTimeAsync(3_000); // 3 more polls, same alert UUID
-
-    expect(emergencyalert).toHaveBeenCalledTimes(1); // only the initial activation
-
-    player.stop();
-  });
-
-  it("emits emergencyalert when the alert UUID changes", async () => {
-    const first = makeAlert({ uuid: "alert-1" });
-    const second = makeAlert({ uuid: "alert-2" });
-    const network = makeNetwork();
-    network.checkForEmergencyAlert = vi
-      .fn()
-      .mockResolvedValueOnce({ success: true, data: first })
-      .mockResolvedValue({ success: true, data: second });
-
-    const player = new SquareScreenPlayer(
-      makeConfig(network, makeCache(), { emergencyPollInterval: 1_000 }),
-    );
-    const emergencyalert = vi.fn();
-    player.addEventListener("emergencyalert", emergencyalert);
-
-    await player.start();
-    await vi.advanceTimersByTimeAsync(1_000);
-
-    expect(emergencyalert).toHaveBeenCalledTimes(2);
-    expect(emergencyalert.mock.calls[1][0].detail.alert.uuid).toBe("alert-2");
-
-    player.stop();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Preloading
-// ---------------------------------------------------------------------------
-
-describe("preloading", () => {
-  it("does not trigger any background download when preloadCount is 0", async () => {
-    const playlist = makePlaylist({
-      items: [
-        makeItem({ uuid: "item-1", url: "https://cdn.example.com/1.jpg" }),
-        makeItem({ uuid: "item-2", url: "https://cdn.example.com/2.jpg" }),
-      ],
-      strategy: { loop: true, shuffle: false, preloadCount: 0 },
-    });
-
-    const network = makeNetwork(playlist);
-    const cache = makeCache();
-    const player = new SquareScreenPlayer(makeConfig(network, cache));
-
-    await player.start();
-
-    // Only item-1's URL should have been checked (for the current item).
-    expect(cache.getMediaUrl).toHaveBeenCalledWith("https://cdn.example.com/1.jpg");
-    expect(cache.getMediaUrl).not.toHaveBeenCalledWith("https://cdn.example.com/2.jpg");
-
-    player.stop();
-  });
-
-  it("triggers a background download for the next item when preloadCount is 1", async () => {
-    const playlist = makePlaylist({
-      items: [
-        makeItem({ uuid: "item-1", url: "https://cdn.example.com/1.jpg", duration: 5 }),
-        makeItem({ uuid: "item-2", url: "https://cdn.example.com/2.jpg", duration: 5 }),
-      ],
-      strategy: { loop: true, shuffle: false, preloadCount: 1 },
-    });
-
-    const network = makeNetwork(playlist);
-    const cache = makeCache();
-    const player = new SquareScreenPlayer(makeConfig(network, cache));
-
-    await player.start();
-    // Let the fire-and-forget getMediaUrl call for item-2 resolve.
-    await Promise.resolve();
-
-    expect(cache.getMediaUrl).toHaveBeenCalledWith("https://cdn.example.com/2.jpg");
-
-    player.stop();
-  });
-
-  it("preloads all items when preloadCount is undefined", async () => {
-    const playlist = makePlaylist({
-      items: [
-        makeItem({ uuid: "item-1", url: "https://cdn.example.com/1.jpg", duration: 5 }),
-        makeItem({ uuid: "item-2", url: "https://cdn.example.com/2.jpg", duration: 5 }),
-        makeItem({ uuid: "item-3", url: "https://cdn.example.com/3.jpg", duration: 5 }),
-      ],
-      strategy: { loop: true, shuffle: false },
-    });
-
-    const network = makeNetwork(playlist);
-    const cache = makeCache();
-    const player = new SquareScreenPlayer(makeConfig(network, cache));
-
-    await player.start();
-    await Promise.resolve();
-
-    expect(cache.getMediaUrl).toHaveBeenCalledWith("https://cdn.example.com/2.jpg");
-    expect(cache.getMediaUrl).toHaveBeenCalledWith("https://cdn.example.com/3.jpg");
-
-    player.stop();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Heartbeat
-// ---------------------------------------------------------------------------
-
-describe("heartbeat", () => {
-  it("calls healthCheck after the heartbeat interval", async () => {
-    const network = makeNetwork();
-    const player = new SquareScreenPlayer(
-      makeConfig(network, makeCache(), { heartbeatInterval: 10_000 }),
-    );
-
-    await player.start();
-    expect(network.healthCheck).not.toHaveBeenCalled();
-
-    await vi.advanceTimersByTimeAsync(10_000);
-
-    expect(network.healthCheck).toHaveBeenCalledWith(
-      expect.objectContaining({ playerVersion: "1.0.0" }),
-    );
-
-    player.stop();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// stop()
-// ---------------------------------------------------------------------------
-
-describe("stop()", () => {
-  it("clears all timers so no further fetches or advances occur", async () => {
-    const network = makeNetwork();
-    const player = new SquareScreenPlayer(
-      makeConfig(network, makeCache(), { pollInterval: 5_000, heartbeatInterval: 10_000 }),
-    );
-
-    await player.start();
-    player.stop();
-
-    await vi.advanceTimersByTimeAsync(30_000);
-
-    // Only the initial start() call — no subsequent polls or heartbeats.
-    expect(network.fetchPlaylist).toHaveBeenCalledTimes(1);
-    expect(network.healthCheck).not.toHaveBeenCalled();
-  });
-
-  it("prevents itemchange from firing when stop() is called before media resolves", async () => {
-    const network = makeNetwork();
-    const cache = makeCache();
-
-    let resolveMedia!: (url: string | null) => void;
-    vi.mocked(cache.getMediaUrl).mockReturnValue(
-      new Promise<string | null>((res) => { resolveMedia = res; }),
-    );
-
-    const player = new SquareScreenPlayer(makeConfig(network, cache));
-    const itemchange = vi.fn();
-    player.addEventListener("itemchange", itemchange);
-
-    const started = player.start();
-    player.stop();
-    resolveMedia(null);
-    await started;
-    await Promise.resolve();
-
-    expect(itemchange).not.toHaveBeenCalled();
-  });
-});