perf(studio): clips that scroll into view get their pictures when the scroll stops

Keeping every clip's content mounted through a scroll made each jump of the 50,000-clip viewport
gate mount and lay out a screenful of new thumbnails, a 90 to 130 ms long task per run where main
has none. A clip's content now mounts only while the timeline is at rest and then stays through
later scrolls, so a picture already on screen never blanks and a scroll never mounts new ones.

Author: miguel-heygen

packages/studio/src/player/components/Timeline.virtualization.test.tsx

@@ -185,6 +185,50 @@ describe("Timeline row virtualization", { timeout: 30_000 }, () => {
     }
   });
 
+  it("gives a clip that appears mid-scroll its picture once the scroll settles", async () => {
+    const [{ Timeline }, { usePlayerStore }] = await Promise.all([
+      import("./Timeline"),
+      import("../store/playerStore"),
+    ]);
+    const clip = (id: string, start: number) => ({
+      id,
+      label: id,
+      tag: "div",
+      start,
+      duration: 5,
+      track: 0,
+    });
+    usePlayerStore.setState({ duration: 60, timelineReady: true, elements: [clip("clip-0", 0)] });
+
+    const { host, root } = await mountTimeline(
+      React.createElement(Timeline, {
+        renderClipContent: (element: { id: string }) =>
+          React.createElement("span", { "data-rich-content": element.id }),
+      }),
+    );
+    try {
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 110));
+      });
+      const scroller = host.querySelector<HTMLElement>("[data-timeline-scroll-viewport]");
+      if (scroller) await dispatchScroll(scroller);
+      act(() => {
+        usePlayerStore.setState({ elements: [clip("clip-0", 0), clip("clip-1", 5)] });
+      });
+      expect(host.querySelector('[data-el-id="clip-1"]')).not.toBeNull();
+      expect(host.querySelector('[data-rich-content="clip-1"]')).toBeNull();
+      expect(host.querySelector('[data-rich-content="clip-0"]')).not.toBeNull();
+
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 110));
+      });
+      expect(host.querySelector('[data-rich-content="clip-1"]')).not.toBeNull();
+    } finally {
+      act(() => root.unmount());
+      usePlayerStore.getState().reset();
+    }
+  });
+
   it("mounts a bounded list range over the full geometry height", async () => {
     const [{ Timeline }, { usePlayerStore }, { getTimelineCanvasHeight, TRACK_H }] =
       await Promise.all([

packages/studio/src/player/components/timelineClipChildren.tsx

@@ -1,4 +1,4 @@
-import { type ReactNode } from "react";
+import { useState, type ReactNode } from "react";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import type { TimelineTimeRange } from "../lib/timelineClipIndex";
 import type { TrackVisualStyle } from "./timelineIcons";
@@ -29,6 +29,16 @@ function ClipLintDot({ element }: { element: TimelineElement }) {
   );
 }
 
+/**
+ * Mounts a clip's content only once the timeline is at rest, then keeps it through later scrolls,
+ * so a scroll never blanks a picture already on screen and never mounts a screenful of new ones.
+ */
+export function ClipContentOnceShown({ hold, children }: { hold: boolean; children: ReactNode }) {
+  const [shown, setShown] = useState(!hold);
+  if (!shown && !hold) setShown(true);
+  return shown ? children : null;
+}
+
 export function renderClipChildren(
   element: TimelineElement,
   clipStyle: TrackVisualStyle,

packages/studio/src/player/components/useTimelineProviderState.tsx

@@ -21,6 +21,7 @@ import { useTimelineGeometry } from "./useTimelineGeometry";
 import { useAutoExpandKeyframedClips } from "./useAutoExpandKeyframedClips";
 import { GUTTER, LABEL_COL_W, TRACKS_LEFT_PAD } from "./timelineLayout";
 import { useTimelineScrollViewport } from "./useTimelineScrollViewport";
+import { ClipContentOnceShown } from "./timelineClipChildren";
 import { useResolvedTimelineEditCallbacks } from "./useResolvedTimelineEditCallbacks";
 import type { TimelineProps } from "./TimelineTypes";
 import {
@@ -508,6 +509,17 @@ export function useTimelineProviderState({
     onRazorSplit: editContext.onRazorSplit,
     onRazorSplitAll: editContext.onRazorSplitAll,
   };
+  const holdNewClipContent = timelineFocus.rowVirtualizationActive && viewport.isScrolling;
+  const timelineRenderClipContent = useMemo<typeof renderClipContent>(
+    () =>
+      renderClipContent &&
+      ((element, style, context) => (
+        <ClipContentOnceShown hold={holdNewClipContent}>
+          {renderClipContent(element, style, context)}
+        </ClipContentOnceShown>
+      )),
+    [holdNewClipContent, renderClipContent],
+  );
   const timelineMeta = buildTimelineMeta({
     emptyState: {
       isDragOver: assetDrop.isDragOver,
@@ -574,7 +586,7 @@ export function useTimelineProviderState({
       overlays,
     },
     actions: {
-      renderClipContent,
+      renderClipContent: timelineRenderClipContent,
       renderClipOverlay,
       setFocusedEaseSegment,
     },