perf(studio): virtualize timeline thumbnail media

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 });

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,
@@ -111,6 +111,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);
@@ -403,6 +406,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"

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({

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,13 +89,22 @@ 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
     (el: TimelineElement, style: { clip: string; label: string }): ReactNode => {
       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],
   );
 }

packages/studio/src/hooks/useThumbnailLease.test.tsx

@@ -0,0 +1,150 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ThumbnailScheduler, type ThumbnailRequest } from "../player/lib/thumbnailScheduler";
+import { useThumbnailLease } from "./useThumbnailLease";
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+describe("useThumbnailLease", () => {
+  it("subscribes once, publishes the result, and releases on unmount", async () => {
+    const scheduler = new ThumbnailScheduler();
+    const load = vi.fn(async () => ({
+      value: { kind: "image" as const, url: "blob:poster", aspect: 16 / 9 },
+      weight: 10,
+    }));
+    const request: ThumbnailRequest = {
+      key: "poster",
+      projectId: "demo",
+      sessionEpoch: 1,
+      kind: "image",
+      priority: "visible",
+      load,
+    };
+    let status = "missing";
+
+    function Probe() {
+      status = useThumbnailLease(request, scheduler).status;
+      return null;
+    }
+
+    const root = createRoot(document.createElement("div"));
+    await act(async () => {
+      root.render(React.createElement(Probe));
+      await Promise.resolve();
+    });
+    expect(load).toHaveBeenCalledTimes(1);
+    expect(status).toBe("ready");
+    expect(scheduler.getDiagnostics().leases).toBe(1);
+
+    act(() => root.unmount());
+    expect(scheduler.getDiagnostics().leases).toBe(0);
+  });
+
+  it("does not acquire work for a null request", () => {
+    const scheduler = new ThumbnailScheduler();
+    let status = "missing";
+    function Probe() {
+      status = useThumbnailLease(null, scheduler).status;
+      return null;
+    }
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(React.createElement(Probe)));
+    expect(status).toBe("idle");
+    expect(scheduler.getDiagnostics().leases).toBe(0);
+    act(() => root.unmount());
+  });
+
+  it("updates priority without restarting the active request", async () => {
+    const scheduler = new ThumbnailScheduler();
+    let resolve!: (value: {
+      value: { kind: "image"; url: string; aspect: number };
+      weight: number;
+    }) => void;
+    const pending = new Promise<{
+      value: { kind: "image"; url: string; aspect: number };
+      weight: number;
+    }>((accept) => {
+      resolve = accept;
+    });
+    const load = vi.fn(() => pending);
+    let priority: ThumbnailRequest["priority"] = "overscan";
+    function Probe() {
+      useThumbnailLease(
+        {
+          key: "same-content",
+          projectId: "demo",
+          sessionEpoch: 1,
+          kind: "image",
+          priority,
+          load,
+        },
+        scheduler,
+      );
+      return null;
+    }
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(React.createElement(Probe)));
+    priority = "interaction";
+    act(() => root.render(React.createElement(Probe)));
+    expect(load).toHaveBeenCalledTimes(1);
+
+    await act(async () => {
+      resolve({ value: { kind: "image", url: "blob:done", aspect: 1 }, weight: 1 });
+      await pending;
+    });
+    act(() => root.unmount());
+  });
+
+  it("resubscribes when the request work shape changes", async () => {
+    const scheduler = new ThumbnailScheduler();
+    const imageLoad = vi.fn(async () => ({
+      value: { kind: "image" as const, url: "blob:image", aspect: 1 },
+      weight: 1,
+    }));
+    const videoLoad = vi.fn(async () => ({
+      value: { kind: "image" as const, url: "blob:video", aspect: 1 },
+      weight: 1,
+    }));
+    let kind: ThumbnailRequest["kind"] = "image";
+    let rich = false;
+    function Probe() {
+      useThumbnailLease(
+        {
+          key: "same-content",
+          projectId: "demo",
+          sessionEpoch: 1,
+          kind,
+          rich,
+          priority: "visible",
+          load: kind === "image" ? imageLoad : videoLoad,
+        },
+        scheduler,
+      );
+      return null;
+    }
+    const root = createRoot(document.createElement("div"));
+    await act(async () => {
+      root.render(React.createElement(Probe));
+      await Promise.resolve();
+    });
+
+    kind = "video";
+    rich = true;
+    await act(async () => {
+      root.render(React.createElement(Probe));
+      await Promise.resolve();
+    });
+
+    expect(imageLoad).toHaveBeenCalledTimes(1);
+    expect(videoLoad).toHaveBeenCalledTimes(1);
+    expect(scheduler.getDiagnostics().leases).toBe(1);
+    act(() => root.unmount());
+  });
+});

packages/studio/src/hooks/useThumbnailLease.ts

@@ -0,0 +1,44 @@
+import { useCallback, useLayoutEffect, useRef, useSyncExternalStore } from "react";
+import {
+  createThumbnailRequestIdentity,
+  thumbnailScheduler,
+  type ThumbnailRequest,
+  type ThumbnailScheduler,
+  type ThumbnailSnapshot,
+} from "../player/lib/thumbnailScheduler";
+
+const IDLE: ThumbnailSnapshot = Object.freeze({ status: "idle" });
+
+export function useThumbnailLease(
+  request: ThumbnailRequest | null,
+  scheduler: ThumbnailScheduler = thumbnailScheduler,
+): ThumbnailSnapshot {
+  const requestRef = useRef(request);
+  requestRef.current = request;
+  const leaseRef = useRef<ReturnType<ThumbnailScheduler["acquire"]> | null>(null);
+  const identity = request ? createThumbnailRequestIdentity(request) : null;
+  const priority = request?.priority;
+  const subscribe = useCallback(
+    (listener: () => void) => {
+      const current = requestRef.current;
+      if (!current || identity === null) return () => {};
+      const lease = scheduler.acquire(current, listener);
+      leaseRef.current = lease;
+      return () => {
+        if (leaseRef.current === lease) leaseRef.current = null;
+        lease.release();
+      };
+    },
+    [identity, scheduler],
+  );
+  const getSnapshot = useCallback(() => {
+    const current = requestRef.current;
+    return current && identity !== null ? scheduler.getSnapshot(current) : IDLE;
+  }, [identity, scheduler]);
+
+  useLayoutEffect(() => {
+    if (priority) leaseRef.current?.updatePriority(priority);
+  }, [priority]);
+
+  return useSyncExternalStore(subscribe, getSnapshot, () => IDLE);
+}