From 1a85c92881910e1a3001f859c6f3751babe133c7 Mon Sep 17 00:00:00 2001
From: Codex <codex@local>
Date: Mon, 20 Jul 2026 21:44:01 +0200
Subject: [PATCH] perf(studio): schedule adaptive timeline thumbnails

---
 .../src/components/TimelineToolbar.test.tsx   |  21 +-
 .../studio/src/components/TimelineToolbar.tsx |  30 +-
 .../src/hooks/useRenderClipContent.test.ts    |   5 +-
 .../studio/src/hooks/useRenderClipContent.ts  |  13 +-
 .../src/player/lib/thumbnailPolicy.test.ts    |  14 +
 .../studio/src/player/lib/thumbnailPolicy.ts  |  21 +
 .../src/player/lib/thumbnailScheduler.test.ts | 281 ++++++++++++
 .../src/player/lib/thumbnailScheduler.ts      | 425 ++++++++++++++++++
 .../studio/src/player/store/playerStore.ts    |   8 +
 .../src/utils/studioUiPreferences.test.ts     |  14 +
 .../studio/src/utils/studioUiPreferences.ts   |   6 +
 11 files changed, 834 insertions(+), 4 deletions(-)
 create mode 100644 packages/studio/src/player/lib/thumbnailPolicy.test.ts
 create mode 100644 packages/studio/src/player/lib/thumbnailPolicy.ts
 create mode 100644 packages/studio/src/player/lib/thumbnailScheduler.test.ts
 create mode 100644 packages/studio/src/player/lib/thumbnailScheduler.ts

diff --git a/packages/studio/src/components/TimelineToolbar.test.tsx b/packages/studio/src/components/TimelineToolbar.test.tsx
index 0050dcfc95..2e7900e826 100644
--- a/packages/studio/src/components/TimelineToolbar.test.tsx
+++ b/packages/studio/src/components/TimelineToolbar.test.tsx
@@ -12,7 +12,7 @@ import { TimelineToolbar } from "./TimelineToolbar";
 
 afterEach(() => {
   document.body.innerHTML = "";
-  usePlayerStore.setState({ autoKeyframeEnabled: true });
+  usePlayerStore.setState({ autoKeyframeEnabled: true, thumbnailMode: "adaptive" });
 });
 
 function renderToolbar(
@@ -58,6 +58,25 @@ describe("TimelineToolbar — auto-keyframe toggle (#1808)", () => {
     act(() => root.unmount());
   });
 });
+
+describe("TimelineToolbar — adaptive thumbnails", () => {
+  it("keeps a user-controlled hidden mode as the rollback path", () => {
+    const { host, root } = renderToolbar();
+    const button = host.querySelector<HTMLButtonElement>(
+      'button[aria-label="Hide thumbnails — labels only"]',
+    );
+    if (!button) throw new Error("thumbnail toggle not rendered");
+
+    act(() => button.click());
+
+    expect(usePlayerStore.getState().thumbnailMode).toBe("hidden");
+    expect(button.getAttribute("aria-label")).toBe(
+      "Show thumbnails — posters stay visible; richer previews appear on interaction",
+    );
+    act(() => root.unmount());
+  });
+});
+
 describe("TimelineToolbar — motion path endpoints", () => {
   it("does not advertise a destructive keyframe toggle for a required endpoint", () => {
     usePlayerStore.setState({ currentTime: 10 });
diff --git a/packages/studio/src/components/TimelineToolbar.tsx b/packages/studio/src/components/TimelineToolbar.tsx
index 43416414d5..99928935da 100644
--- a/packages/studio/src/components/TimelineToolbar.tsx
+++ b/packages/studio/src/components/TimelineToolbar.tsx
@@ -1,5 +1,5 @@
 import { useEffect, useRef } from "react";
-import { Magnet, MagnifyingGlassMinus, MagnifyingGlassPlus } from "@phosphor-icons/react";
+import { Image, Magnet, MagnifyingGlassMinus, MagnifyingGlassPlus } from "@phosphor-icons/react";
 import {
   useEnableKeyframes,
   isPlayheadWithinTween,
@@ -115,6 +115,9 @@ export function TimelineToolbar({ domEditSession, onSplitElement }: TimelineTool
   const setTimelineSnapEnabled = usePlayerStore((s) => s.setTimelineSnapEnabled);
   const autoKeyframeEnabled = usePlayerStore((s) => s.autoKeyframeEnabled);
   const setAutoKeyframeEnabled = usePlayerStore((s) => s.setAutoKeyframeEnabled);
+  const thumbnailMode = usePlayerStore((s) => s.thumbnailMode);
+  const setThumbnailMode = usePlayerStore((s) => s.setThumbnailMode);
+  const thumbnailsVisible = thumbnailMode === "adaptive";
   // Subscribe so the add-beat button reacts to playhead movement and analysis load.
   const currentTime = usePlayerStore((s) => s.currentTime);
   const beatAnalysisReady = usePlayerStore((s) => s.beatAnalysis !== null);
@@ -410,6 +413,31 @@ export function TimelineToolbar({ domEditSession, onSplitElement }: TimelineTool
           })()}
         </div>
         <div className="flex items-center gap-0.5">
+          <Tooltip
+            label={
+              thumbnailsVisible
+                ? "Hide thumbnails — labels only"
+                : "Show thumbnails — posters stay visible; richer previews appear on interaction"
+            }
+          >
+            <button
+              type="button"
+              aria-label={
+                thumbnailsVisible
+                  ? "Hide thumbnails — labels only"
+                  : "Show thumbnails — posters stay visible; richer previews appear on interaction"
+              }
+              aria-pressed={thumbnailsVisible}
+              onClick={() => setThumbnailMode(thumbnailsVisible ? "hidden" : "adaptive")}
+              className={`h-7 px-2 rounded-md text-[11px] font-medium transition-colors ${
+                thumbnailsVisible
+                  ? "bg-studio-accent/10 text-studio-accent"
+                  : "text-neutral-400 hover:bg-white/[0.06] hover:text-neutral-200"
+              }`}
+            >
+              <Image size={16} aria-hidden="true" />
+            </button>
+          </Tooltip>
           <Tooltip label="Fit timeline to width">
             <button
               type="button"
diff --git a/packages/studio/src/hooks/useRenderClipContent.test.ts b/packages/studio/src/hooks/useRenderClipContent.test.ts
index 057cf04824..2c33e27909 100644
--- a/packages/studio/src/hooks/useRenderClipContent.test.ts
+++ b/packages/studio/src/hooks/useRenderClipContent.test.ts
@@ -5,13 +5,14 @@ import { createRoot } from "react-dom/client";
 import { afterEach, describe, expect, it } from "vitest";
 import { CompositionThumbnail, VideoThumbnail } from "../player";
 import { AudioWaveform } from "../player/components/AudioWaveform";
-import type { TimelineElement } from "../player/store/playerStore";
+import { usePlayerStore, type TimelineElement } from "../player/store/playerStore";
 import { normalizeCompositionSrc } from "./useRenderClipContent";
 import { useRenderClipContent } from "./useRenderClipContent";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
 afterEach(() => {
+  usePlayerStore.setState({ thumbnailMode: "hidden" });
   document.body.innerHTML = "";
 });
 
@@ -106,6 +107,8 @@ describe("useRenderClipContent", () => {
   });
 
   it("passes empty labels to thumbnail content so TimelineClip owns clip names", () => {
+    usePlayerStore.setState({ thumbnailMode: "adaptive" });
+
     const cases: Array<{ content: ReactNode; type: unknown }> = [
       {
         content: renderClipContent({
diff --git a/packages/studio/src/hooks/useRenderClipContent.ts b/packages/studio/src/hooks/useRenderClipContent.ts
index 0e01c381fa..3cc7a56b88 100644
--- a/packages/studio/src/hooks/useRenderClipContent.ts
+++ b/packages/studio/src/hooks/useRenderClipContent.ts
@@ -5,6 +5,8 @@ import type { TimelineElement } from "../player";
 import { AudioWaveform } from "../player/components/AudioWaveform";
 import { ImageThumbnail } from "../player/components/ImageThumbnail";
 import { encodePreviewPath, resolveMediaPreviewUrl } from "../player/components/thumbnailUtils";
+import { usePlayerStore } from "../player/store/playerStore";
+import { effectiveThumbnailMode } from "../player/lib/thumbnailPolicy";
 
 export function normalizeCompositionSrc(
   compSrc: string,
@@ -87,6 +89,9 @@ export function useRenderClipContent({
   activePreviewUrl,
   effectiveTimelineDuration,
 }: UseRenderClipContentOptions) {
+  // Self-sourced so the adaptive policy gates thumbnail generation without App plumbing.
+  const thumbnailMode = usePlayerStore((s) => s.thumbnailMode);
+  const effectiveMode = effectiveThumbnailMode(thumbnailMode);
   return useCallback(
     // Pre-existing clip-content dispatcher; reduced by extracting renderAudioClip.
     // fallow-ignore-next-line complexity
@@ -94,6 +99,12 @@ export function useRenderClipContent({
       const pid = projectIdRef.current;
       if (!pid) return null;
 
+      // Thumbnail generation disabled (perf) -> plain clip bars. Audio still shows
+      // its waveform (cheap, not a frame thumbnail). Toggle: timeline toolbar.
+      if (effectiveMode === "hidden") {
+        return el.tag === "audio" ? renderAudioClip(el, pid, style.label) : null;
+      }
+
       let compSrc = el.compositionSrc;
       if (compSrc) {
         compSrc = normalizeCompositionSrc(compSrc, pid, window.location.origin);
@@ -182,6 +193,6 @@ export function useRenderClipContent({
 
       return null;
     },
-    [projectIdRef, compIdToSrc, activePreviewUrl, effectiveTimelineDuration],
+    [projectIdRef, compIdToSrc, activePreviewUrl, effectiveTimelineDuration, effectiveMode],
   );
 }
diff --git a/packages/studio/src/player/lib/thumbnailPolicy.test.ts b/packages/studio/src/player/lib/thumbnailPolicy.test.ts
new file mode 100644
index 0000000000..675a49140e
--- /dev/null
+++ b/packages/studio/src/player/lib/thumbnailPolicy.test.ts
@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import { defaultThumbnailMode, effectiveThumbnailMode } from "./thumbnailPolicy";
+
+describe("thumbnail runtime policy", () => {
+  it("defaults missing preferences adaptively after activation", () => {
+    expect(defaultThumbnailMode(undefined, "follow-preference")).toBe("adaptive");
+    expect(defaultThumbnailMode(undefined, "legacy-default")).toBe("hidden");
+  });
+
+  it("forces the safe renderer without overwriting user intent", () => {
+    expect(effectiveThumbnailMode("adaptive", "force-hidden")).toBe("hidden");
+    expect(effectiveThumbnailMode("adaptive", "follow-preference")).toBe("adaptive");
+  });
+});
diff --git a/packages/studio/src/player/lib/thumbnailPolicy.ts b/packages/studio/src/player/lib/thumbnailPolicy.ts
new file mode 100644
index 0000000000..2953e4990c
--- /dev/null
+++ b/packages/studio/src/player/lib/thumbnailPolicy.ts
@@ -0,0 +1,21 @@
+export type ThumbnailMode = "adaptive" | "hidden";
+export type ThumbnailRuntimePolicy = "follow-preference" | "force-hidden" | "legacy-default";
+
+const rawPolicy = import.meta.env.VITE_STUDIO_TIMELINE_THUMBNAIL_POLICY;
+
+const studioThumbnailRuntimePolicy: ThumbnailRuntimePolicy =
+  rawPolicy === "force-hidden" || rawPolicy === "legacy-default" ? rawPolicy : "follow-preference";
+
+export function defaultThumbnailMode(
+  storedMode: ThumbnailMode | undefined,
+  policy: ThumbnailRuntimePolicy = studioThumbnailRuntimePolicy,
+): ThumbnailMode {
+  return storedMode ?? (policy === "legacy-default" ? "hidden" : "adaptive");
+}
+
+export function effectiveThumbnailMode(
+  preferredMode: ThumbnailMode,
+  policy: ThumbnailRuntimePolicy = studioThumbnailRuntimePolicy,
+): ThumbnailMode {
+  return policy === "force-hidden" ? "hidden" : preferredMode;
+}
diff --git a/packages/studio/src/player/lib/thumbnailScheduler.test.ts b/packages/studio/src/player/lib/thumbnailScheduler.test.ts
new file mode 100644
index 0000000000..a9e1b678dc
--- /dev/null
+++ b/packages/studio/src/player/lib/thumbnailScheduler.test.ts
@@ -0,0 +1,281 @@
+import { describe, expect, it, vi } from "vitest";
+import { resolveTimelineViewportBudgets } from "./timelineViewportBudgets";
+import {
+  createThumbnailKey,
+  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();
+    first.release();
+    scheduler.invalidateProject("project-a");
+    expect(listener).toHaveBeenCalledTimes(1);
+    second.release();
+  });
+
+  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 project invalidation", async () => {
+    const scheduler = new ThumbnailScheduler();
+    const pending = deferred<ThumbnailLoadedResult>();
+    const dispose = vi.fn();
+    scheduler.acquire(
+      request("late", () => pending.promise),
+      vi.fn(),
+    );
+
+    scheduler.invalidateProject("project-a");
+    pending.resolve(result("late", 1, dispose));
+    await flush();
+    expect(dispose).toHaveBeenCalledTimes(1);
+    expect(scheduler.getSnapshot(request("late", () => pending.promise))).toEqual({
+      status: "idle",
+    });
+  });
+
+  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" }),
+    );
+  });
+});
diff --git a/packages/studio/src/player/lib/thumbnailScheduler.ts b/packages/studio/src/player/lib/thumbnailScheduler.ts
new file mode 100644
index 0000000000..75ad9f9348
--- /dev/null
+++ b/packages/studio/src/player/lib/thumbnailScheduler.ts
@@ -0,0 +1,425 @@
+import { TIMELINE_VIEWPORT_BUDGETS, type TimelineViewportBudgets } from "./timelineViewportBudgets";
+
+export type ThumbnailPriority = "overscan" | "visible" | "interaction";
+export type ThumbnailJobKind = "video" | "image" | "composition" | "waveform";
+
+export type ThumbnailValue =
+  | { kind: "image"; url: string; aspect: number }
+  | { kind: "filmstrip"; urls: readonly string[]; aspect: number }
+  | { kind: "waveform"; peaks: readonly number[] };
+
+export interface ThumbnailLoadedResult {
+  value: ThumbnailValue;
+  /** Estimated decoded/object-URL bytes retained by this result. */
+  weight: number;
+  dispose?: () => void;
+}
+
+export interface ThumbnailRequest {
+  key: string;
+  projectId: string;
+  sessionEpoch: number;
+  kind: ThumbnailJobKind;
+  priority: ThumbnailPriority;
+  /** Rich work is paused while the timeline is fast-scrolling. */
+  rich?: boolean;
+  load: (signal: AbortSignal) => Promise<ThumbnailLoadedResult>;
+}
+
+export type ThumbnailSnapshot =
+  | { status: "idle" | "queued" | "loading" }
+  | { status: "ready"; value: ThumbnailValue }
+  | { status: "error"; error: Error };
+
+export interface ThumbnailLease {
+  updatePriority(priority: ThumbnailPriority): void;
+  release(): void;
+}
+
+export interface ThumbnailSchedulerDiagnostics {
+  queued: number;
+  active: number;
+  leases: number;
+  cacheEntries: number;
+  cacheBytes: number;
+  waveformCacheEntries: number;
+  waveformCacheBytes: number;
+  activeByKind: Readonly<Record<ThumbnailJobKind, number>>;
+}
+
+type EntryState = "queued" | "loading" | "ready" | "error";
+
+interface ThumbnailEntry {
+  request: ThumbnailRequest;
+  scopedKey: string;
+  state: EntryState;
+  leases: Map<number, ThumbnailPriority>;
+  listeners: Map<number, () => void>;
+  controller: AbortController | null;
+  value?: ThumbnailValue;
+  error?: Error;
+  failedAt?: number;
+  weight: number;
+  dispose?: () => void;
+  disposed: boolean;
+  cached: boolean;
+  lastAccess: number;
+  snapshot: ThumbnailSnapshot;
+}
+
+const PRIORITY_SCORE: Readonly<Record<ThumbnailPriority, number>> = {
+  overscan: 0,
+  visible: 1,
+  interaction: 2,
+};
+
+const EMPTY_SNAPSHOT: ThumbnailSnapshot = Object.freeze({ status: "idle" });
+
+function concurrencyBucket(kind: ThumbnailJobKind): "video" | "composition" | "general" {
+  if (kind === "video") return "video";
+  if (kind === "composition") return "composition";
+  return "general";
+}
+
+function errorFrom(reason: unknown): Error {
+  return reason instanceof Error ? reason : new Error(String(reason));
+}
+
+export function createThumbnailKey(parts: Readonly<Record<string, string | number | undefined>>) {
+  return Object.entries(parts)
+    .filter((entry): entry is [string, string | number] => entry[1] !== undefined)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([name, value]) => `${encodeURIComponent(name)}=${encodeURIComponent(String(value))}`)
+    .join("&");
+}
+
+/** Sole client owner for thumbnail work, cached resources, and cleanup. */
+export class ThumbnailScheduler {
+  private readonly entries = new Map<string, ThumbnailEntry>();
+  private readonly budgets: Readonly<TimelineViewportBudgets>;
+  private nextLeaseId = 1;
+  private nextSequence = 1;
+  private scrolling = false;
+  private cacheBytes = 0;
+  private waveformCacheBytes = 0;
+  private readonly activeByBucket = { video: 0, composition: 0, general: 0 };
+  private readonly activeByKind: Record<ThumbnailJobKind, number> = {
+    video: 0,
+    image: 0,
+    composition: 0,
+    waveform: 0,
+  };
+  private readonly now: () => number;
+
+  constructor(
+    budgets: Readonly<TimelineViewportBudgets> = TIMELINE_VIEWPORT_BUDGETS,
+    now: () => number = Date.now,
+  ) {
+    this.budgets = budgets;
+    this.now = now;
+  }
+
+  acquire(request: ThumbnailRequest, listener: () => void): ThumbnailLease {
+    const scopedKey = this.scopedKey(request);
+    let entry = this.entries.get(scopedKey);
+    if (
+      entry?.state === "error" &&
+      entry.failedAt !== undefined &&
+      this.now() - entry.failedAt >= this.budgets.metadataFailureTtlMs
+    ) {
+      this.deleteEntry(scopedKey, entry);
+      entry = undefined;
+    }
+    if (!entry) {
+      entry = {
+        request,
+        scopedKey,
+        state: "queued",
+        leases: new Map(),
+        listeners: new Map(),
+        controller: null,
+        weight: 0,
+        disposed: false,
+        cached: false,
+        lastAccess: this.nextSequence++,
+        snapshot: Object.freeze({ status: "queued" }),
+      };
+      this.entries.set(scopedKey, entry);
+    } else if (
+      entry.request.kind !== request.kind ||
+      Boolean(entry.request.rich) !== Boolean(request.rich)
+    ) {
+      throw new Error(`Thumbnail key collision for ${request.key}`);
+    }
+
+    const leaseId = this.nextLeaseId++;
+    entry.leases.set(leaseId, request.priority);
+    entry.listeners.set(leaseId, listener);
+    entry.lastAccess = this.nextSequence++;
+    this.pump();
+
+    let released = false;
+    return {
+      updatePriority: (priority) => {
+        const current = this.entries.get(scopedKey);
+        if (!current || !current.leases.has(leaseId)) return;
+        current.leases.set(leaseId, priority);
+        current.lastAccess = this.nextSequence++;
+        this.pump();
+      },
+      release: () => {
+        if (released) return;
+        released = true;
+        const current = this.entries.get(scopedKey);
+        if (!current) return;
+        current.leases.delete(leaseId);
+        current.listeners.delete(leaseId);
+        if (current.leases.size === 0) {
+          if (current.state === "queued") {
+            this.deleteEntry(scopedKey, current);
+          } else if (current.state === "loading") {
+            current.controller?.abort();
+            this.deleteEntry(scopedKey, current);
+          } else if (current.state === "ready" && !current.cached) {
+            this.deleteEntry(scopedKey, current);
+          }
+        }
+        this.evict();
+      },
+    };
+  }
+
+  getSnapshot(
+    request: Pick<ThumbnailRequest, "key" | "projectId" | "sessionEpoch">,
+  ): ThumbnailSnapshot {
+    const entry = this.entries.get(this.scopedKey(request));
+    if (!entry) return EMPTY_SNAPSHOT;
+    return entry.snapshot;
+  }
+
+  setScrolling(scrolling: boolean): void {
+    if (this.scrolling === scrolling) return;
+    this.scrolling = scrolling;
+    if (!scrolling) this.pump();
+  }
+
+  invalidateProject(projectId: string): void {
+    for (const [key, entry] of this.entries) {
+      if (entry.request.projectId !== projectId) continue;
+      entry.controller?.abort();
+      this.deleteEntry(key, entry);
+    }
+  }
+
+  clear(): void {
+    for (const [key, entry] of this.entries) {
+      entry.controller?.abort();
+      this.deleteEntry(key, entry);
+    }
+  }
+
+  getDiagnostics(): ThumbnailSchedulerDiagnostics {
+    let queued = 0;
+    let active = 0;
+    let leases = 0;
+    let cacheEntries = 0;
+    let waveformCacheEntries = 0;
+    for (const entry of this.entries.values()) {
+      if (entry.state === "queued") queued++;
+      if (entry.state === "loading") active++;
+      if (entry.cached) {
+        if (entry.request.kind === "waveform") waveformCacheEntries++;
+        else cacheEntries++;
+      }
+      leases += entry.leases.size;
+    }
+    return {
+      queued,
+      active,
+      leases,
+      cacheEntries,
+      cacheBytes: this.cacheBytes,
+      waveformCacheEntries,
+      waveformCacheBytes: this.waveformCacheBytes,
+      activeByKind: { ...this.activeByKind },
+    };
+  }
+
+  private pump(): void {
+    const queued = Array.from(this.entries.values())
+      .filter((entry) => entry.state === "queued" && entry.leases.size > 0)
+      .sort((left, right) => {
+        const priorityDelta = this.entryPriority(right) - this.entryPriority(left);
+        return priorityDelta || left.lastAccess - right.lastAccess;
+      });
+
+    for (const entry of queued) {
+      if (this.scrolling && entry.request.rich) continue;
+      const bucket = concurrencyBucket(entry.request.kind);
+      if (this.activeByBucket[bucket] >= this.bucketLimit(bucket)) continue;
+      this.start(entry, bucket);
+    }
+  }
+
+  private start(entry: ThumbnailEntry, bucket: "video" | "composition" | "general"): void {
+    entry.state = "loading";
+    entry.snapshot = Object.freeze({ status: "loading" });
+    const controller = new AbortController();
+    entry.controller = controller;
+    this.activeByBucket[bucket]++;
+    this.activeByKind[entry.request.kind]++;
+    this.notify(entry);
+
+    let pending: Promise<ThumbnailLoadedResult>;
+    try {
+      pending = entry.request.load(controller.signal);
+    } catch (reason) {
+      pending = Promise.reject(reason);
+    }
+    void pending
+      .then((result) => {
+        if (controller.signal.aborted || this.entries.get(entry.scopedKey) !== entry) {
+          this.safeDispose(result.dispose);
+          return;
+        }
+        if (!Number.isFinite(result.weight) || result.weight < 0) {
+          this.safeDispose(result.dispose);
+          throw new RangeError("Thumbnail result weight must be finite and non-negative");
+        }
+        entry.state = "ready";
+        entry.value = result.value;
+        entry.weight = Math.max(0, result.weight);
+        entry.dispose = result.dispose;
+        const isWaveform = entry.request.kind === "waveform";
+        const cacheBudget = isWaveform
+          ? this.budgets.waveformCacheBytes
+          : this.budgets.thumbnailCacheBytes;
+        entry.cached = entry.weight <= cacheBudget;
+        if (entry.cached) {
+          if (isWaveform) this.waveformCacheBytes += entry.weight;
+          else this.cacheBytes += entry.weight;
+        }
+        entry.snapshot = Object.freeze({ status: "ready", value: result.value });
+        this.notify(entry);
+        this.evict();
+        if (!entry.cached && entry.leases.size === 0) this.deleteEntry(entry.scopedKey, entry);
+      })
+      .catch((reason: unknown) => {
+        if (this.entries.get(entry.scopedKey) !== entry) return;
+        if (controller.signal.aborted && entry.leases.size === 0) {
+          this.deleteEntry(entry.scopedKey, entry);
+          return;
+        }
+        entry.state = "error";
+        entry.error = errorFrom(reason);
+        entry.failedAt = this.now();
+        entry.snapshot = Object.freeze({ status: "error", error: entry.error });
+        this.notify(entry);
+        this.evictFailures();
+      })
+      .finally(() => {
+        if (entry.controller === controller) entry.controller = null;
+        this.activeByBucket[bucket]--;
+        this.activeByKind[entry.request.kind]--;
+        this.pump();
+      });
+  }
+
+  private entryPriority(entry: ThumbnailEntry): number {
+    let score = -1;
+    for (const priority of entry.leases.values()) {
+      score = Math.max(score, PRIORITY_SCORE[priority]);
+    }
+    return score;
+  }
+
+  private bucketLimit(bucket: "video" | "composition" | "general"): number {
+    if (bucket === "video") return this.budgets.concurrentVideoDecodes;
+    if (bucket === "composition") return this.budgets.concurrentCompositionFetches;
+    return this.budgets.concurrentMetadataJobs;
+  }
+
+  private evict(): void {
+    this.evictPartition(false);
+    this.evictPartition(true);
+  }
+
+  private evictPartition(waveform: boolean): void {
+    const cached = Array.from(this.entries.values()).filter(
+      (entry) => entry.cached && (entry.request.kind === "waveform") === waveform,
+    );
+    const perProject = new Map<string, number>();
+    for (const entry of cached) {
+      perProject.set(entry.request.projectId, (perProject.get(entry.request.projectId) ?? 0) + 1);
+    }
+    cached.sort((left, right) => left.lastAccess - right.lastAccess);
+
+    let cacheEntries = cached.length;
+    for (const entry of cached) {
+      const projectEntries = perProject.get(entry.request.projectId) ?? 0;
+      const overBudget =
+        cacheEntries >
+          (waveform ? this.budgets.waveformCacheEntries : this.budgets.thumbnailCacheEntries) ||
+        (waveform ? this.waveformCacheBytes : this.cacheBytes) >
+          (waveform ? this.budgets.waveformCacheBytes : this.budgets.thumbnailCacheBytes) ||
+        (!waveform && projectEntries > this.budgets.thumbnailCacheEntriesPerProject);
+      if (!overBudget) continue;
+      entry.cached = false;
+      if (waveform) this.waveformCacheBytes -= entry.weight;
+      else this.cacheBytes -= entry.weight;
+      cacheEntries--;
+      perProject.set(entry.request.projectId, projectEntries - 1);
+      if (entry.leases.size === 0) this.deleteEntry(entry.scopedKey, entry);
+    }
+  }
+
+  private notify(entry: ThumbnailEntry): void {
+    for (const listener of new Set(entry.listeners.values())) listener();
+  }
+
+  private deleteEntry(key: string, entry: ThumbnailEntry): void {
+    if (this.entries.get(key) !== entry) return;
+    entry.snapshot = EMPTY_SNAPSHOT;
+    this.notify(entry);
+    this.entries.delete(key);
+    if (entry.cached) {
+      entry.cached = false;
+      if (entry.request.kind === "waveform") this.waveformCacheBytes -= entry.weight;
+      else this.cacheBytes -= entry.weight;
+    }
+    if (!entry.disposed) {
+      entry.disposed = true;
+      this.safeDispose(entry.dispose);
+    }
+    entry.listeners.clear();
+    entry.leases.clear();
+  }
+
+  private evictFailures(): void {
+    const failed = Array.from(this.entries.values())
+      .filter((entry) => entry.state === "error" && entry.leases.size === 0)
+      .sort((left, right) => left.lastAccess - right.lastAccess);
+    const overflow = failed.length - this.budgets.thumbnailCacheEntries;
+    for (const entry of failed.slice(0, Math.max(0, overflow))) {
+      this.deleteEntry(entry.scopedKey, entry);
+    }
+  }
+
+  private safeDispose(dispose: (() => void) | undefined): void {
+    try {
+      dispose?.();
+    } catch {
+      // Cleanup is best-effort; one broken resource must not block the remaining cleanup.
+    }
+  }
+
+  private scopedKey(request: Pick<ThumbnailRequest, "key" | "projectId" | "sessionEpoch">) {
+    return createThumbnailKey({
+      project: request.projectId,
+      session: request.sessionEpoch,
+      request: request.key,
+    });
+  }
+}
+
+export const thumbnailScheduler = new ThumbnailScheduler();
diff --git a/packages/studio/src/player/store/playerStore.ts b/packages/studio/src/player/store/playerStore.ts
index ff5400c6c8..48bc3c63b9 100644
--- a/packages/studio/src/player/store/playerStore.ts
+++ b/packages/studio/src/player/store/playerStore.ts
@@ -5,6 +5,7 @@ import type { ClipManifestClip } from "../lib/playbackTypes";
 import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
 import { computePinnedZoomPercent } from "../components/timelineZoom";
 import { createKeyframeSlice, type KeyframeSlice } from "./keyframeSlice";
+import { defaultThumbnailMode, type ThumbnailMode } from "../lib/thumbnailPolicy";
 
 export type { KeyframeCacheEntry } from "./keyframeSlice";
 
@@ -107,6 +108,7 @@ interface PlayerState extends KeyframeSlice {
   timelineProjectId: string | null;
   /** True while a beat dot is being dragged — hides the playhead guideline. */
   beatDragging: boolean;
+  thumbnailMode: ThumbnailMode;
   elements: TimelineElement[];
   selectedElementId: string | null;
   playbackRate: number;
@@ -185,6 +187,7 @@ interface PlayerState extends KeyframeSlice {
   setPlaybackRate: (rate: number) => void;
   setAudioMuted: (muted: boolean) => void;
   setLoopEnabled: (enabled: boolean) => void;
+  setThumbnailMode: (mode: ThumbnailMode) => void;
   setTimelineReady: (ready: boolean) => void;
   setBeatDragging: (dragging: boolean) => void;
   setElements: (elements: TimelineElement[]) => void;
@@ -328,6 +331,7 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   timelineSessionEpoch: 0,
   timelineProjectId: null,
   beatDragging: false,
+  thumbnailMode: defaultThumbnailMode(readStudioUiPreferences().thumbnailMode),
   elements: [],
   selectedElementId: null,
   playbackRate: readStudioUiPreferences().playbackRate ?? 1,
@@ -450,6 +454,10 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
     set({ audioMuted: muted });
   },
   setLoopEnabled: (enabled) => set({ loopEnabled: enabled }),
+  setThumbnailMode: (mode) => {
+    writeStudioUiPreferences({ thumbnailMode: mode });
+    set({ thumbnailMode: mode });
+  },
   setZoomMode: (mode) => set({ zoomMode: mode }),
   clearSelectedElementIds: () => set({ selectedElementIds: new Set() }),
   setSelectedElementIds: (ids: Set<string>) => set({ selectedElementIds: new Set(ids) }),
diff --git a/packages/studio/src/utils/studioUiPreferences.test.ts b/packages/studio/src/utils/studioUiPreferences.test.ts
index 5e335cf5d3..7312714242 100644
--- a/packages/studio/src/utils/studioUiPreferences.test.ts
+++ b/packages/studio/src/utils/studioUiPreferences.test.ts
@@ -65,6 +65,20 @@ describe("timelineSnapEnabled preference", () => {
   });
 });
 
+describe("thumbnailMode preference", () => {
+  it("round-trips the adaptive mode", () => {
+    const storage = createStorage();
+    writeStudioUiPreferences({ thumbnailMode: "adaptive" }, storage);
+    expect(readStudioUiPreferences(storage).thumbnailMode).toBe("adaptive");
+  });
+
+  it("migrates the legacy boolean without retaining two owners", () => {
+    const storage = createStorage();
+    storage.setItem("hf-studio-ui-preferences", JSON.stringify({ thumbnailsEnabled: false }));
+    expect(readStudioUiPreferences(storage).thumbnailMode).toBe("hidden");
+  });
+});
+
 describe("timeline zoom pin persistence", () => {
   it("round-trips a pinned manual zoom (survives the post-edit reload)", () => {
     const storage = createStorage();
diff --git a/packages/studio/src/utils/studioUiPreferences.ts b/packages/studio/src/utils/studioUiPreferences.ts
index 6548a58eba..e7dd877370 100644
--- a/packages/studio/src/utils/studioUiPreferences.ts
+++ b/packages/studio/src/utils/studioUiPreferences.ts
@@ -10,6 +10,7 @@ export interface StudioUiPreferences {
   timelineHeight?: number;
   playbackRate?: number;
   audioMuted?: boolean;
+  thumbnailMode?: "adaptive" | "hidden";
   previewZoom?: StoredPreviewZoomState;
   recentBlocks?: string[];
   snapEnabled?: boolean;
@@ -70,6 +71,11 @@ function readStorage(storage: Storage | null): StudioUiPreferences {
     if (typeof parsed.audioMuted === "boolean") {
       preferences.audioMuted = parsed.audioMuted;
     }
+    if (parsed.thumbnailMode === "adaptive" || parsed.thumbnailMode === "hidden") {
+      preferences.thumbnailMode = parsed.thumbnailMode;
+    } else if (typeof parsed.thumbnailsEnabled === "boolean") {
+      preferences.thumbnailMode = parsed.thumbnailsEnabled ? "adaptive" : "hidden";
+    }
     if (isRecord(parsed.previewZoom)) {
       const { zoomPercent, panX, panY } = parsed.previewZoom;
       if (