perf(studio): stop timeline scroll work when row virtualization is off

The row virtualization stack made the timeline publish a viewport snapshot
on every scroll frame and swap `renderClipContent` across every mounted clip
at gesture start and settle. Both are windowing concessions, and neither was
gated on the flag, so the build users actually run paid for them while
mounting all 1,000 clips anyway. Measured on a 3,000-clip project: median
scroll step 16.6ms to 76.9ms, p95 17.9ms to 189.4ms, 40 long tasks to 247.

Gate both on the row virtualization flag. The scroll path now stops at the
door when the flag is off, so `isScrolling` stays false and resize-driven
and programmatic syncs still publish through the immediate path.

The flag moves into its own module: the scroll-viewport hook needs to read
it, and the virtualization hook already imports the viewport snapshot type
back, which would have closed an import cycle.

Also release the perf fixture lease from the fixture rather than from the
test-hook effect. Loading a fixture writes player state, which changed that
effect's dependency identities and tore it down on the next frame, so the
lease was revoked moments after it was taken and live iframe discovery
overwrote the fixture before the gate could measure it.

The e2e gate gains a flag-off arm (`test:timeline-default`, 1,000 elements)
next to the existing flag-on one. It refuses the 50,000-element combination,
verifies from the mounted DOM that the server under test matches the
requested flag, and skips the DOM-size budgets for the unvirtualized build
rather than relaxing them, so a skipped budget never reads as a passed one.

Verified against a live Studio dev server on the fixture project:

  flag off, before: interactionP95 303.1ms, longest task 194ms, 0/5 runs pass
  flag off, after:  interactionP95  33.6ms, longest task   0ms, 5/5 runs pass
  flag on,  after:  interactionP95  33.2ms, 4/5 runs pass, exit 0

The flag-on arm's fourth run reproducibly reports a 55-58ms long task
against a 50ms budget. That is the residual tail of the window swap itself,
tracked separately and not addressed here.

Author: miguel-heygen

packages/studio/package.json

@@ -49,9 +49,10 @@
     "build": "vite build && tsup",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "test:timeline-virtualization": "node tests/e2e/timeline-virtualization.mjs",
+    "test:timeline-virtualization": "TIMELINE_ROW_VIRTUALIZATION=on TIMELINE_ELEMENT_COUNT=50000 node tests/e2e/timeline-virtualization.mjs",
     "test:watch": "vitest",
-    "report:sdk-cutover": "bun src/utils/sdkCutoverPolicy.report.ts"
+    "report:sdk-cutover": "bun src/utils/sdkCutoverPolicy.report.ts",
+    "test:timeline-default": "TIMELINE_ROW_VIRTUALIZATION=off TIMELINE_ELEMENT_COUNT=1000 node tests/e2e/timeline-virtualization.mjs"
   },
   "dependencies": {
     "@codemirror/autocomplete": "^6.20.1",

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

@@ -119,7 +119,11 @@ describe("timeline performance fixture", () => {
     unsubscribe();
     act(() => root.unmount());
     expect(window.__studioTest).toBeUndefined();
-    expect(hasTimelinePerformanceFixtureLease()).toBe(false);
+    // The lease outlives the effect on purpose. Loading a fixture changes the
+    // player state this effect depends on, so the effect tears down right after
+    // the loader runs; releasing the lease there let live iframe discovery
+    // overwrite the fixture before anything could measure it.
+    expect(hasTimelinePerformanceFixtureLease()).toBe(true);
   });
 
   it("does not mutate state when the fixture request is invalid", () => {

packages/studio/src/hooks/useStudioTestHooks.ts

@@ -95,7 +95,12 @@ export function useStudioTestHooks({
     };
     window.__studioTest = api;
     return () => {
-      setTimelinePerformanceFixtureLease(false);
+      // The lease is deliberately NOT released here. Loading a fixture writes
+      // player state, which changes this effect's dependency identities and
+      // tears the effect down on the very next frame. Releasing on teardown
+      // therefore revoked the lease moments after it was taken, and live iframe
+      // discovery overwrote the fixture the loader had just installed. The
+      // lease belongs to the fixture, and a page reload clears it.
       // delete, not `= undefined`: an own key holding undefined keeps
       // `"__studioTest" in window` true, which defeats feature detection.
       delete window.__studioTest;

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

@@ -530,7 +530,10 @@ export const Timeline = memo(function Timeline({
           blockedClipRef={blockedClipRef}
           suppressClickRef={suppressClickRef}
           scrollRef={scrollRef}
-          renderClipContent={viewport.isScrolling ? undefined : renderClipContent}
+          // Windowing drops content to mount a row cheaply; unvirtualized it is pure cost.
+          renderClipContent={
+            rowVirtualizationActive && viewport.isScrolling ? undefined : renderClipContent
+          }
           renderClipOverlay={renderClipOverlay}
           playheadRef={playheadRef}
           onDrillDown={onDrillDown}

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

@@ -255,3 +255,118 @@ describe("Timeline row virtualization", { timeout: 30_000 }, () => {
     usePlayerStore.getState().reset();
   });
 });
+
+/**
+ * The flag-off build is the one users get today. It mounts every clip, so the
+ * scroll-time concessions windowing makes are pure cost there: this block pins
+ * the timeline to doing no per-frame work at all while a gesture runs.
+ */
+describe("Timeline without row virtualization", { timeout: 30_000 }, () => {
+  async function renderUnvirtualizedTimeline() {
+    vi.stubEnv("VITE_STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED", "0");
+    vi.resetModules();
+    const [{ Timeline }, { usePlayerStore }] = await Promise.all([
+      import("./Timeline"),
+      import("../store/playerStore"),
+    ]);
+    usePlayerStore.setState({
+      duration: 60,
+      timelineReady: true,
+      selectedElementId: "clip-0",
+      elements: Array.from({ length: 40 }, (_, track) => ({
+        id: `clip-${track}`,
+        label: `Clip ${track}`,
+        tag: "div",
+        start: 0,
+        duration: 10,
+        track,
+      })),
+    });
+
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    await act(async () =>
+      root.render(
+        React.createElement(Timeline, {
+          renderClipContent: () => React.createElement("span", { "data-rich-content": true }),
+        }),
+      ),
+    );
+    await act(async () => {});
+    return {
+      host,
+      dispose: () => {
+        act(() => root.unmount());
+        usePlayerStore.getState().reset();
+        vi.stubEnv("VITE_STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED", "1");
+        vi.resetModules();
+      },
+    };
+  }
+
+  it("mounts every clip rather than a window", async () => {
+    const { host, dispose } = await renderUnvirtualizedTimeline();
+    try {
+      expect(host.querySelectorAll("[data-clip]").length).toBe(40);
+    } finally {
+      dispose();
+    }
+  });
+
+  it("keeps clip content mounted across a scroll gesture", async () => {
+    const { host, dispose } = await renderUnvirtualizedTimeline();
+    try {
+      const scroller = host.querySelector<HTMLElement>("[data-timeline-scroll-viewport]");
+      expect(scroller).not.toBeNull();
+      const richBefore = host.querySelectorAll("[data-rich-content]").length;
+      expect(richBefore).toBe(40);
+
+      await act(async () => {
+        scroller?.dispatchEvent(new Event("scroll"));
+        await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+      });
+
+      expect(host.querySelectorAll("[data-rich-content]").length).toBe(richBefore);
+    } finally {
+      dispose();
+    }
+  });
+
+  it("does not swap clip content back in after the gesture settles", async () => {
+    const { host, dispose } = await renderUnvirtualizedTimeline();
+    try {
+      const scroller = host.querySelector<HTMLElement>("[data-timeline-scroll-viewport]");
+      const clip = host.querySelector<HTMLElement>('[data-el-id="clip-0"]');
+      await act(async () => {
+        scroller?.dispatchEvent(new Event("scroll"));
+        await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+      });
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 150));
+      });
+
+      expect(host.querySelector('[data-el-id="clip-0"]')).toBe(clip);
+      expect(host.querySelectorAll("[data-rich-content]").length).toBe(40);
+    } finally {
+      dispose();
+    }
+  });
+
+  it("leaves the scroll position alone, so no snapshot round trip happens", async () => {
+    const { host, dispose } = await renderUnvirtualizedTimeline();
+    try {
+      const scroller = host.querySelector<HTMLElement>("[data-timeline-scroll-viewport]");
+      if (!scroller) throw new Error("Expected a timeline scroll viewport");
+      scroller.scrollTop = 400;
+      await act(async () => {
+        scroller.dispatchEvent(new Event("scroll"));
+        await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+      });
+
+      expect(scroller.scrollTop).toBe(400);
+    } finally {
+      dispose();
+    }
+  });
+});

packages/studio/src/player/components/timelineRowVirtualizationFlag.ts

@@ -0,0 +1,11 @@
+/**
+ * Row virtualization opt-in. Disabled until horizontal windowing and stable
+ * gesture lifetime land.
+ *
+ * It lives in its own module so the scroll-viewport hook can read it without
+ * importing the virtualization hook that already imports the viewport snapshot
+ * type back, which would close an import cycle.
+ */
+export const STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED =
+  import.meta.env.DEV === true &&
+  import.meta.env.VITE_STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED === "1";

packages/studio/src/player/components/useTimelineRowVirtualization.ts

@@ -4,10 +4,8 @@ import { resolveTimelineFocusIdentity } from "./timelineFocusIdentity";
 import { getTimelineScrollTopForGeometryChange } from "./timelineViewportGeometry";
 import type { TimelineRowGeometry } from "./timelineLayout";
 import type { TimelineScrollViewportSnapshot } from "./useTimelineScrollViewport";
-import {
-  STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED,
-  useTimelineVirtualRows,
-} from "./useTimelineVirtualRows";
+import { STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED } from "./timelineRowVirtualizationFlag";
+import { useTimelineVirtualRows } from "./useTimelineVirtualRows";
 
 interface UseTimelineRowVirtualizationInput {
   scrollRef: RefObject<HTMLDivElement | null>;