@hyperframes/studio 0.7.93 → 0.7.95

package/src/player/lib/thumbnailScheduler.test.ts

@@ -0,0 +1,388 @@
+import { describe, expect, it, vi } from "vitest";
+import { resolveTimelineViewportBudgets } from "./timelineViewportBudgets";
+import {
+  createThumbnailKey,
+  createThumbnailRequestIdentity,
+  ThumbnailScheduler,
+  type ThumbnailLoadedResult,
+  type ThumbnailPriority,
+  type ThumbnailRequest,
+} from "./thumbnailScheduler";
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((accept, fail) => {
+    resolve = accept;
+    reject = fail;
+  });
+  return { promise, resolve, reject };
+}
+
+function result(name: string, weight = 1, dispose = vi.fn()): ThumbnailLoadedResult {
+  return { value: { kind: "image", url: name, aspect: 1 }, weight, dispose };
+}
+
+function request(
+  key: string,
+  load: ThumbnailRequest["load"],
+  priority: ThumbnailPriority = "visible",
+  overrides: Partial<ThumbnailRequest> = {},
+): ThumbnailRequest {
+  return {
+    key,
+    projectId: "project-a",
+    sessionEpoch: 1,
+    kind: "image",
+    priority,
+    load,
+    ...overrides,
+  };
+}
+
+async function flush(): Promise<void> {
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+describe("ThumbnailScheduler", () => {
+  it("deduplicates identical requests and releases subscribers independently", async () => {
+    const scheduler = new ThumbnailScheduler();
+    const pending = deferred<ThumbnailLoadedResult>();
+    const load = vi.fn(() => pending.promise);
+    const listenerA = vi.fn();
+    const listenerB = vi.fn();
+
+    const leaseA = scheduler.acquire(request("same", load), listenerA);
+    const leaseB = scheduler.acquire(request("same", load), listenerB);
+    expect(load).toHaveBeenCalledTimes(1);
+
+    leaseA.release();
+    listenerA.mockClear();
+    pending.resolve(result("poster"));
+    await flush();
+    expect(scheduler.getSnapshot(request("same", load))).toMatchObject({
+      status: "ready",
+      value: { url: "poster" },
+    });
+    expect(listenerA).not.toHaveBeenCalled();
+    expect(listenerB).toHaveBeenCalled();
+
+    leaseB.release();
+    expect(scheduler.getDiagnostics().leases).toBe(0);
+  });
+
+  it("keeps snapshots referentially stable and supports independent leases sharing a callback", async () => {
+    const scheduler = new ThumbnailScheduler();
+    const listener = vi.fn();
+    const shared = request("stable", async () => result("stable"));
+    const first = scheduler.acquire(shared, listener);
+    const second = scheduler.acquire(shared, listener);
+    await flush();
+    expect(scheduler.getSnapshot(shared)).toBe(scheduler.getSnapshot(shared));
+    listener.mockClear();
+    scheduler.invalidateProject("project-a");
+    expect(listener).not.toHaveBeenCalled();
+    expect(scheduler.getDiagnostics().leases).toBe(2);
+    first.release();
+    second.release();
+    scheduler.invalidateProject("project-a");
+    expect(scheduler.getSnapshot(shared).status).toBe("idle");
+  });
+
+  it("scopes the same caller key by work shape", async () => {
+    const scheduler = new ThumbnailScheduler();
+    const poster = request("shared", async () => result("poster"));
+    const strip = request("shared", async () => result("strip"), "visible", {
+      kind: "video",
+      rich: true,
+    });
+
+    scheduler.acquire(poster, vi.fn());
+    scheduler.acquire(strip, vi.fn());
+    await flush();
+
+    expect(scheduler.getSnapshot(poster)).toMatchObject({
+      status: "ready",
+      value: { url: "poster" },
+    });
+    expect(scheduler.getSnapshot(strip)).toMatchObject({
+      status: "ready",
+      value: { url: "strip" },
+    });
+  });
+
+  it("orders interaction before visible before overscan when a slot opens", async () => {
+    const scheduler = new ThumbnailScheduler(
+      resolveTimelineViewportBudgets({ concurrentMetadataJobs: 1 }),
+    );
+    const first = deferred<ThumbnailLoadedResult>();
+    const starts: string[] = [];
+    const load = (name: string, pending?: ReturnType<typeof deferred<ThumbnailLoadedResult>>) =>
+      vi.fn(() => {
+        starts.push(name);
+        return pending?.promise ?? Promise.resolve(result(name));
+      });
+
+    scheduler.acquire(request("first", load("first", first)), vi.fn());
+    scheduler.acquire(request("overscan", load("overscan"), "overscan"), vi.fn());
+    scheduler.acquire(request("visible", load("visible"), "visible"), vi.fn());
+    scheduler.acquire(request("interaction", load("interaction"), "interaction"), vi.fn());
+    expect(starts).toEqual(["first"]);
+
+    first.resolve(result("first"));
+    await vi.waitFor(() => {
+      expect(starts).toEqual(["first", "interaction", "visible", "overscan"]);
+    });
+  });
+
+  it("suspends new rich work while scrolling but lets posters proceed", async () => {
+    const scheduler = new ThumbnailScheduler();
+    const richLoad = vi.fn(async () => result("rich"));
+    const posterLoad = vi.fn(async () => result("poster"));
+    scheduler.setScrolling(true);
+
+    scheduler.acquire(request("rich", richLoad, "interaction", { rich: true }), vi.fn());
+    scheduler.acquire(request("poster", posterLoad), vi.fn());
+    await flush();
+    expect(richLoad).not.toHaveBeenCalled();
+    expect(posterLoad).toHaveBeenCalledTimes(1);
+
+    scheduler.setScrolling(false);
+    await flush();
+    expect(richLoad).toHaveBeenCalledTimes(1);
+  });
+
+  it("aborts queued and active jobs after the final release", async () => {
+    const scheduler = new ThumbnailScheduler(
+      resolveTimelineViewportBudgets({ concurrentVideoDecodes: 1 }),
+    );
+    const active = deferred<ThumbnailLoadedResult>();
+    let activeSignal: AbortSignal | undefined;
+    const activeLease = scheduler.acquire(
+      request(
+        "active",
+        (signal) => {
+          activeSignal = signal;
+          return active.promise;
+        },
+        "visible",
+        { kind: "video" },
+      ),
+      vi.fn(),
+    );
+    const queuedLoad = vi.fn(async () => result("queued"));
+    const queuedLease = scheduler.acquire(
+      request("queued", queuedLoad, "visible", { kind: "video" }),
+      vi.fn(),
+    );
+
+    queuedLease.release();
+    activeLease.release();
+    expect(activeSignal?.aborted).toBe(true);
+    expect(queuedLoad).not.toHaveBeenCalled();
+    active.reject(new DOMException("aborted", "AbortError"));
+    await flush();
+    expect(scheduler.getDiagnostics()).toMatchObject({ queued: 0, active: 0, leases: 0 });
+  });
+
+  it("disposes a late result exactly once after its final lease releases", async () => {
+    const scheduler = new ThumbnailScheduler();
+    const pending = deferred<ThumbnailLoadedResult>();
+    const dispose = vi.fn();
+    const lease = scheduler.acquire(
+      request("late", () => pending.promise),
+      vi.fn(),
+    );
+
+    lease.release();
+    pending.resolve(result("late", 1, dispose));
+    await flush();
+    expect(dispose).toHaveBeenCalledTimes(1);
+    expect(scheduler.getSnapshot(request("late", () => pending.promise))).toEqual({
+      status: "idle",
+    });
+  });
+
+  it("preserves a synchronous re-acquire when an expired failure is replaced", async () => {
+    vi.useFakeTimers();
+    const scheduler = new ThumbnailScheduler(
+      resolveTimelineViewportBudgets({ metadataFailureTtlMs: 10 }),
+    );
+    const load = vi
+      .fn<ThumbnailRequest["load"]>()
+      .mockRejectedValueOnce(new Error("temporary"))
+      .mockResolvedValue(result("recovered"));
+    const failed = request("retry", load);
+    let reacquireOnNotify = false;
+    let nestedLease: ReturnType<ThumbnailScheduler["acquire"]> | undefined;
+    const firstLease = scheduler.acquire(failed, () => {
+      if (!reacquireOnNotify) return;
+      reacquireOnNotify = false;
+      nestedLease = scheduler.acquire(failed, vi.fn());
+    });
+    await flush();
+    vi.advanceTimersByTime(11);
+    reacquireOnNotify = true;
+
+    const outerLease = scheduler.acquire(failed, vi.fn());
+    await flush();
+
+    expect(load).toHaveBeenCalledTimes(2);
+    expect(scheduler.getSnapshot(failed)).toMatchObject({
+      status: "ready",
+      value: { url: "recovered" },
+    });
+    expect(scheduler.getDiagnostics().leases).toBe(2);
+    firstLease.release();
+    nestedLease?.release();
+    outerLease.release();
+    vi.useRealTimers();
+  });
+
+  it("times out a hung loader, frees its bucket, and disposes a late result", async () => {
+    vi.useFakeTimers();
+    const scheduler = new ThumbnailScheduler(
+      resolveTimelineViewportBudgets({
+        concurrentVideoDecodes: 1,
+        thumbnailLoadTimeoutMs: 10,
+      }),
+    );
+    const hung = deferred<ThumbnailLoadedResult>();
+    const dispose = vi.fn();
+    let signal: AbortSignal | undefined;
+    const hungRequest = request(
+      "hung",
+      (activeSignal) => {
+        signal = activeSignal;
+        return hung.promise;
+      },
+      "visible",
+      { kind: "video" },
+    );
+    const nextLoad = vi.fn(async () => result("next"));
+    const nextRequest = request("next", nextLoad, "visible", { kind: "video" });
+    const hungLease = scheduler.acquire(hungRequest, vi.fn());
+    const nextLease = scheduler.acquire(nextRequest, vi.fn());
+
+    await vi.advanceTimersByTimeAsync(11);
+    await flush();
+    expect(signal?.aborted).toBe(true);
+    expect(nextLoad).toHaveBeenCalledTimes(1);
+    expect(scheduler.getSnapshot(hungRequest).status).toBe("error");
+
+    hung.resolve(result("late", 1, dispose));
+    await flush();
+    expect(dispose).toHaveBeenCalledTimes(1);
+    hungLease.release();
+    nextLease.release();
+    vi.useRealTimers();
+  });
+
+  it("isolates late results by session epoch", async () => {
+    const scheduler = new ThumbnailScheduler();
+    const old = deferred<ThumbnailLoadedResult>();
+    const oldRequest = request("poster", () => old.promise, "visible", { sessionEpoch: 1 });
+    const nextRequest = request("poster", async () => result("next"), "visible", {
+      sessionEpoch: 2,
+    });
+    scheduler.acquire(oldRequest, vi.fn());
+    scheduler.acquire(nextRequest, vi.fn());
+    await flush();
+    old.resolve(result("old"));
+    await flush();
+    expect(scheduler.getSnapshot(nextRequest)).toMatchObject({
+      status: "ready",
+      value: { url: "next" },
+    });
+  });
+
+  it("turns synchronous loader errors into bounded failure snapshots", async () => {
+    const scheduler = new ThumbnailScheduler();
+    const bad = request("throws", () => {
+      throw new Error("sync failure");
+    });
+    const lease = scheduler.acquire(bad, vi.fn());
+    await flush();
+    expect(scheduler.getSnapshot(bad)).toMatchObject({ status: "error" });
+    expect(scheduler.getDiagnostics().active).toBe(0);
+    lease.release();
+  });
+
+  it("disposes uncached results after the final lease and tolerates broken disposers", async () => {
+    const scheduler = new ThumbnailScheduler(
+      resolveTimelineViewportBudgets({ thumbnailCacheBytes: 1 }),
+    );
+    const dispose = vi.fn(() => {
+      throw new Error("cleanup failure");
+    });
+    const oversized = request("oversized", async () => result("large", 2, dispose));
+    const lease = scheduler.acquire(oversized, vi.fn());
+    await flush();
+    expect(scheduler.getSnapshot(oversized).status).toBe("ready");
+    expect(() => lease.release()).not.toThrow();
+    expect(dispose).toHaveBeenCalledTimes(1);
+    expect(scheduler.getSnapshot(oversized).status).toBe("idle");
+  });
+
+  it("evicts least-recently-used unleased values by bytes, count, and project count", async () => {
+    const scheduler = new ThumbnailScheduler(
+      resolveTimelineViewportBudgets({
+        thumbnailCacheBytes: 6,
+        thumbnailCacheEntries: 2,
+        thumbnailCacheEntriesPerProject: 2,
+      }),
+    );
+    const disposals = [vi.fn(), vi.fn(), vi.fn()];
+    for (let index = 0; index < 3; index++) {
+      const lease = scheduler.acquire(
+        request(`key-${index}`, async () => result(`url-${index}`, 3, disposals[index])),
+        vi.fn(),
+      );
+      await flush();
+      lease.release();
+    }
+
+    expect(scheduler.getDiagnostics()).toMatchObject({ cacheEntries: 2, cacheBytes: 6 });
+    expect(disposals[0]).toHaveBeenCalledTimes(1);
+    expect(disposals[1]).not.toHaveBeenCalled();
+    expect(disposals[2]).not.toHaveBeenCalled();
+  });
+
+  it("keeps failed requests quiet until the TTL expires", async () => {
+    vi.useFakeTimers();
+    const scheduler = new ThumbnailScheduler(
+      resolveTimelineViewportBudgets({ metadataFailureTtlMs: 100 }),
+    );
+    const load = vi.fn(async () => {
+      throw new Error("unsupported");
+    });
+
+    const first = scheduler.acquire(request("failed", load), vi.fn());
+    await flush();
+    first.release();
+    const second = scheduler.acquire(request("failed", load), vi.fn());
+    expect(load).toHaveBeenCalledTimes(1);
+    second.release();
+
+    vi.advanceTimersByTime(101);
+    scheduler.acquire(request("failed", load), vi.fn());
+    await flush();
+    expect(load).toHaveBeenCalledTimes(2);
+    vi.useRealTimers();
+  });
+});
+
+describe("createThumbnailKey", () => {
+  it("normalizes field order and preserves sentinel zero values", () => {
+    expect(createThumbnailKey({ source: "clip a", time: 0, missing: undefined })).toBe(
+      createThumbnailKey({ time: 0, source: "clip a" }),
+    );
+  });
+
+  it("includes the work shape in request identity", () => {
+    const poster = request("shared", vi.fn(), "visible", { kind: "video" });
+    const strip = { ...poster, rich: true };
+    expect(createThumbnailRequestIdentity(poster)).not.toBe(createThumbnailRequestIdentity(strip));
+  });
+});