perf(studio): schedule adaptive timeline thumbnails

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,
@@ -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"

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/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");
+  });
+});

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