From 9fda27f93ff485ddc7ba7851caa76d7ac6e889d4 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Mon, 20 Jul 2026 19:32:57 +0200
Subject: [PATCH] perf(studio): follow playhead across virtualized rows

---
 bun.lock                                      |   5 +
 packages/studio/package.json                  |   1 +
 .../player/components/LayerDisclosureRow.tsx  |   1 +
 .../src/player/components/Timeline.test.ts    |  78 ++++++++
 .../studio/src/player/components/Timeline.tsx |  51 +++--
 .../Timeline.virtualization.test.tsx          | 104 +++++++++++
 .../src/player/components/TimelineCanvas.tsx  |   4 +-
 .../player/components/TimelineLaneTypes.ts    |   5 +
 .../src/player/components/TimelineLanes.tsx   |  46 +++--
 .../player/components/TimelineTrackRow.tsx    |  46 +++++
 .../player/components/timelineEditing.test.ts |  32 ++++
 .../src/player/components/timelineEditing.ts  |  52 +++++-
 .../components/timelineFocusIdentity.test.ts  |  21 +++
 .../components/timelineFocusIdentity.ts       |  21 +++
 .../src/player/components/timelineLayout.ts   |  41 +++++
 .../player/components/useTimelinePlayhead.ts  |  43 +++--
 .../useTimelineRowVirtualization.ts           | 135 ++++++++++++++
 .../useTimelineVirtualRows.test.tsx           | 174 ++++++++++++++++++
 .../components/useTimelineVirtualRows.ts      | 110 +++++++++++
 19 files changed, 901 insertions(+), 69 deletions(-)
 create mode 100644 packages/studio/src/player/components/Timeline.virtualization.test.tsx
 create mode 100644 packages/studio/src/player/components/TimelineTrackRow.tsx
 create mode 100644 packages/studio/src/player/components/timelineFocusIdentity.test.ts
 create mode 100644 packages/studio/src/player/components/timelineFocusIdentity.ts
 create mode 100644 packages/studio/src/player/components/useTimelineRowVirtualization.ts
 create mode 100644 packages/studio/src/player/components/useTimelineVirtualRows.test.tsx
 create mode 100644 packages/studio/src/player/components/useTimelineVirtualRows.ts

diff --git a/bun.lock b/bun.lock
index 797509c8ee..3ff8d8ced7 100644
--- a/bun.lock
+++ b/bun.lock
@@ -328,6 +328,7 @@
         "@hyperframes/sdk": "workspace:*",
         "@hyperframes/studio-server": "workspace:*",
         "@phosphor-icons/react": "^2.1.10",
+        "@tanstack/react-virtual": "^3.14.6",
         "bpm-detective": "^2.0.5",
         "dompurify": "^3.2.4",
         "gsap": "^3.13.0",
@@ -1106,6 +1107,10 @@
 
     "@swc/helpers": ["@swc/helpers@0.5.21", "", { "dependencies": { "tslib": "^2.8.0" } }, "sha512-jI/VAmtdjB/RnI8GTnokyX7Ug8c+g+ffD6QRLa6XQewtnGyukKkKSk3wLTM3b5cjt1jNh9x0jfVlagdN2gDKQg=="],
 
+    "@tanstack/react-virtual": ["@tanstack/react-virtual@3.14.6", "", { "dependencies": { "@tanstack/virtual-core": "3.17.4" }, "peerDependencies": { "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }, "sha512-4+Uq8m0/gzO4kMCHUEpTtGX1RnONK0C+g88b2ltwPMWUBiaVarBuWKoPJaz7gj1cKCVRAdyu+U8GcKhwCc2beA=="],
+
+    "@tanstack/virtual-core": ["@tanstack/virtual-core@3.17.4", "", {}, "sha512-nGm5KteqxasUdThLc2izl6dHUqLv0LQj7Nuyo5gYalTPf/U8a9ermvsl7reT+6ioBW1l8WfpP/mcU338nLXpqw=="],
+
     "@tootallnate/once": ["@tootallnate/once@2.0.1", "", {}, "sha512-HqmEUIGRJ5fSXchkVgR5F7qn48bDBzv0kWj/Kfu5e6uci4UlEeng4331LnBkWffb++Ei3FOVLxo8JJWMFBDMeQ=="],
 
     "@tootallnate/quickjs-emscripten": ["@tootallnate/quickjs-emscripten@0.23.0", "", {}, "sha512-C5Mc6rdnsaJDjO3UpGW/CQTHtCKaYlScZTly4JIu97Jxo/odCiH0ITnDXSJPTOrEKk/ycSZ0AOgTmkDtkOsvIA=="],
diff --git a/packages/studio/package.json b/packages/studio/package.json
index b5971ff4ec..fd51b6c838 100644
--- a/packages/studio/package.json
+++ b/packages/studio/package.json
@@ -71,6 +71,7 @@
     "@hyperframes/sdk": "workspace:*",
     "@hyperframes/studio-server": "workspace:*",
     "@phosphor-icons/react": "^2.1.10",
+    "@tanstack/react-virtual": "^3.14.6",
     "bpm-detective": "^2.0.5",
     "dompurify": "^3.2.4",
     "gsap": "^3.13.0",
diff --git a/packages/studio/src/player/components/LayerDisclosureRow.tsx b/packages/studio/src/player/components/LayerDisclosureRow.tsx
index b630482d69..2535ee2e09 100644
--- a/packages/studio/src/player/components/LayerDisclosureRow.tsx
+++ b/packages/studio/src/player/components/LayerDisclosureRow.tsx
@@ -28,6 +28,7 @@ export function LayerDisclosureRow({
     >
       <button
         type="button"
+        aria-expanded={isExpanded}
         aria-label={`${isExpanded ? "Collapse" : "Expand"} ${name} keyframes`}
         title={`${isExpanded ? "Collapse" : "Expand"} keyframe lanes`}
         className="flex h-5 w-4 shrink-0 items-center justify-center rounded border-0 bg-transparent p-0 text-white/55 hover:text-white focus-visible:outline focus-visible:outline-1 focus-visible:outline-[#3CE6AC]"
diff --git a/packages/studio/src/player/components/Timeline.test.ts b/packages/studio/src/player/components/Timeline.test.ts
index 164dcf9fd1..f0dd3d890e 100644
--- a/packages/studio/src/player/components/Timeline.test.ts
+++ b/packages/studio/src/player/components/Timeline.test.ts
@@ -12,6 +12,7 @@ import {
   getTimelineCanvasHeight,
   resolveTimelineAssetDrop,
   getTimelinePlayheadLeft,
+  getTimelinePlaybackFollowScrollLeft,
   getTimelineScrollLeftForZoomAnchor,
   getTimelineScrollLeftForZoomTransition,
   shouldShowTimelineShortcutHint,
@@ -274,6 +275,33 @@ describe("Timeline provider boundary", () => {
     act(() => root.unmount());
   });
 
+  it("renders the complete track list while row virtualization is gated off", () => {
+    const host = createSizedTimelineHost(640);
+    usePlayerStore.setState({
+      duration: 4,
+      timelineReady: true,
+      elements: Array.from({ length: 12 }, (_, track) => ({
+        id: `clip-${track}`,
+        tag: "div",
+        start: 0,
+        duration: 2,
+        track,
+      })),
+    });
+    const root = createRoot(host);
+    act(() => root.render(React.createElement(Timeline)));
+
+    const list = host.querySelector<HTMLElement>('[role="list"]');
+    const rows = list?.querySelectorAll('[role="listitem"]') ?? [];
+    expect(rows).toHaveLength(12);
+    expect(rows[0]?.getAttribute("aria-posinset")).toBe("1");
+    expect(rows[0]?.getAttribute("aria-setsize")).toBe("12");
+    expect(rows[11]?.getAttribute("aria-posinset")).toBe("12");
+
+    act(() => root.unmount());
+  });
+
+  // fallow-ignore-next-line code-duplication
   it("renders the gutter without legacy icons or hue dots", () => {
     const { host, root } = renderBasicTimeline();
 
@@ -974,6 +1002,56 @@ describe("getTimelinePlayheadLeft", () => {
   });
 });
 
+describe("getTimelinePlaybackFollowScrollLeft", () => {
+  it("holds the viewport still while the playhead remains inside the comfort area", () => {
+    expect(
+      getTimelinePlaybackFollowScrollLeft({
+        playheadX: 700,
+        currentScrollLeft: 100,
+        viewportWidth: 1000,
+        contentOrigin: 264,
+        maxScrollLeft: 2000,
+      }),
+    ).toBe(100);
+  });
+
+  it("follows forward playback at the right-side comfort line", () => {
+    expect(
+      getTimelinePlaybackFollowScrollLeft({
+        playheadX: 1200,
+        currentScrollLeft: 100,
+        viewportWidth: 1000,
+        contentOrigin: 264,
+        maxScrollLeft: 2000,
+      }),
+    ).toBe(384);
+  });
+
+  it("returns to the matching earlier viewport after a playback loop", () => {
+    expect(
+      getTimelinePlaybackFollowScrollLeft({
+        playheadX: 264,
+        currentScrollLeft: 900,
+        viewportWidth: 1000,
+        contentOrigin: 264,
+        maxScrollLeft: 2000,
+      }),
+    ).toBe(0);
+  });
+
+  it("clamps at the end of the scrollable timeline", () => {
+    expect(
+      getTimelinePlaybackFollowScrollLeft({
+        playheadX: 5000,
+        currentScrollLeft: 100,
+        viewportWidth: 1000,
+        contentOrigin: 264,
+        maxScrollLeft: 1500,
+      }),
+    ).toBe(1500);
+  });
+});
+
 describe("getTimelineCanvasHeight", () => {
   it("includes bottom scroll buffer below the last track", () => {
     expect(getTimelineCanvasHeight(3)).toBeGreaterThan(RULER_H + 3 * TRACK_H);
diff --git a/packages/studio/src/player/components/Timeline.tsx b/packages/studio/src/player/components/Timeline.tsx
index 6dc27f8660..318c408092 100644
--- a/packages/studio/src/player/components/Timeline.tsx
+++ b/packages/studio/src/player/components/Timeline.tsx
@@ -1,4 +1,4 @@
-import { useRef, useMemo, useCallback, useState, useLayoutEffect, memo } from "react";
+import { useRef, useMemo, useCallback, useState, memo } from "react";
 import { useMusicBeatAnalysis } from "../../hooks/useMusicBeatAnalysis";
 import { remapBeatAnalysisToComposition } from "../../utils/beatEditActions";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
@@ -42,7 +42,7 @@ import { useTimelineSelectionLifecycle } from "./useTimelineSelectionLifecycle";
 import { useTimelineShiftModifier } from "./useTimelineShiftModifier";
 import { useTimelineTicks } from "./useTimelineTicks";
 import { getTimelineElementIndexes } from "../lib/timelineElementIndexes";
-import { getTimelineScrollTopForGeometryChange } from "./timelineViewportGeometry";
+import { useTimelineRowVirtualization } from "./useTimelineRowVirtualization";
 
 // Re-export pure utilities so existing imports from "./Timeline" still resolve.
 export {
@@ -51,6 +51,7 @@ export {
   shouldAutoScrollTimeline,
   getTimelineScrollLeftForZoomTransition,
   getTimelineScrollLeftForZoomAnchor,
+  getTimelinePlaybackFollowScrollLeft,
   getTimelinePlayheadLeft,
   getTimelineCanvasHeight,
   shouldShowTimelineShortcutHint,
@@ -126,6 +127,7 @@ export const Timeline = memo(function Timeline({
   const timelineReady = usePlayerStore((s) => s.timelineReady);
   const selectedElementId = usePlayerStore((s) => s.selectedElementId);
   const selectedElementIds = usePlayerStore((s) => s.selectedElementIds);
+  const clipRevealRequest = usePlayerStore((s) => s.clipRevealRequest);
   const gsapAnimations = usePlayerStore((s) => s.gsapAnimations);
   // Label mode = comp has keyframed clips (not just when expanded): keeps the layer
   // disclosure + property column visible and reserves a GUTTER before 0s (Figma).
@@ -284,32 +286,21 @@ export const Timeline = memo(function Timeline({
       expandedElements.length,
       displayLayout.totalH,
     ]);
-  const previousLayoutRef = useRef(displayLayout.rowGeometry);
-  const previousSessionEpochRef = useRef(sessionEpoch);
-  useLayoutEffect(() => {
-    const scroll = scrollRef.current;
-    const previousGeometry = previousLayoutRef.current;
-    if (previousSessionEpochRef.current !== sessionEpoch) {
-      previousSessionEpochRef.current = sessionEpoch;
-      lastScrollLeftRef.current = 0;
-      if (scroll) {
-        scroll.scrollLeft = 0;
-        scroll.scrollTop = 0;
-        syncScrollViewport(scroll);
-      }
-    } else if (scroll && previousGeometry !== displayLayout.rowGeometry) {
-      const nextScrollTop = getTimelineScrollTopForGeometryChange(
-        previousGeometry,
-        displayLayout.rowGeometry,
-        scroll.scrollTop,
-      );
-      if (nextScrollTop !== scroll.scrollTop) {
-        scroll.scrollTop = nextScrollTop;
-        syncScrollViewport(scroll);
-      }
-    }
-    previousLayoutRef.current = displayLayout.rowGeometry;
-  }, [displayLayout.rowGeometry, sessionEpoch, syncScrollViewport]);
+  const { enabled: rowVirtualizationActive, virtualRows } = useTimelineRowVirtualization({
+    scrollRef,
+    viewport,
+    rowGeometry: displayLayout.rowGeometry,
+    sessionEpoch,
+    elements: expandedElements,
+    selectedElementId,
+    revealElementId: clipRevealRequest?.elementId ?? null,
+    draggedRowKey: draggedClip?.started ? draggedClip.previewTrack : undefined,
+    resizingRowKey: resizingClip?.element.track,
+    clipContextMenuRowKey: clipContextMenu?.element.track,
+    keyframeContextMenuRowKey: kfContextMenu?.element.track,
+    lastScrollLeftRef,
+    syncScrollViewport,
+  });
   const selectedKeyframes = usePlayerStore((s) => s.selectedKeyframes);
   const toggleSelectedKeyframe = usePlayerStore((s) => s.toggleSelectedKeyframe);
   const { onClickKeyframe, onSelectSegment, onShiftClickKeyframe, onContextMenuKeyframe } =
@@ -462,6 +453,7 @@ export const Timeline = memo(function Timeline({
       <div
         ref={setScrollRef}
         data-timeline-scroll-viewport
+        data-timeline-auto-scroll-left-inset={labelMode ? LABEL_COL_W : 0}
         tabIndex={-1}
         className={`${zoomMode === "fit" ? "overflow-x-hidden" : "overflow-x-auto"} overflow-y-auto h-full outline-none`}
         onScroll={(e) => {
@@ -498,6 +490,9 @@ export const Timeline = memo(function Timeline({
           theme={theme}
           displayTrackOrder={displayLayout.displayTrackOrder}
           rowHeights={displayLayout.displayRowHeights}
+          rowGeometry={displayLayout.rowGeometry}
+          virtualRows={virtualRows}
+          rowsVirtualized={rowVirtualizationActive}
           trackOrder={trackOrder}
           tracks={tracks}
           trackStyles={trackStyles}
diff --git a/packages/studio/src/player/components/Timeline.virtualization.test.tsx b/packages/studio/src/player/components/Timeline.virtualization.test.tsx
new file mode 100644
index 0000000000..8202758794
--- /dev/null
+++ b/packages/studio/src/player/components/Timeline.virtualization.test.tsx
@@ -0,0 +1,104 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+class MockResizeObserver {
+  constructor(private readonly callback: ResizeObserverCallback) {}
+  observe(target: Element) {
+    this.callback(
+      [
+        {
+          target,
+          borderBoxSize: [{ inlineSize: target.clientWidth, blockSize: target.clientHeight }],
+        } as unknown as ResizeObserverEntry,
+      ],
+      this as unknown as ResizeObserver,
+    );
+  }
+  unobserve() {}
+  disconnect() {}
+}
+
+const originalResizeObserver = globalThis.ResizeObserver;
+const originalClientWidth = Object.getOwnPropertyDescriptor(HTMLElement.prototype, "clientWidth");
+const originalClientHeight = Object.getOwnPropertyDescriptor(HTMLElement.prototype, "clientHeight");
+
+beforeAll(() => {
+  vi.stubEnv("VITE_STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED", "1");
+  globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+  Object.defineProperty(HTMLElement.prototype, "clientWidth", {
+    configurable: true,
+    get: () => 900,
+  });
+  Object.defineProperty(HTMLElement.prototype, "clientHeight", {
+    configurable: true,
+    get: () => 240,
+  });
+});
+
+afterAll(() => {
+  vi.unstubAllEnvs();
+  globalThis.ResizeObserver = originalResizeObserver;
+  if (originalClientWidth)
+    Object.defineProperty(HTMLElement.prototype, "clientWidth", originalClientWidth);
+  if (originalClientHeight)
+    Object.defineProperty(HTMLElement.prototype, "clientHeight", originalClientHeight);
+  document.body.innerHTML = "";
+});
+
+describe("Timeline row virtualization", () => {
+  it("mounts a bounded list range over the full geometry height", async () => {
+    const [{ Timeline }, { usePlayerStore }, { getTimelineCanvasHeight }] = await Promise.all([
+      import("./Timeline"),
+      import("../store/playerStore"),
+      import("./timelineLayout"),
+    ]);
+    usePlayerStore.setState({
+      duration: 60,
+      timelineReady: true,
+      elements: Array.from({ length: 1_000 }, (_, track) => ({
+        id: `clip-${track}`,
+        tag: "div",
+        start: 0,
+        duration: 1,
+        track,
+      })),
+    });
+
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    await act(async () => root.render(React.createElement(Timeline, { sessionEpoch: 3 })));
+    await act(async () => {});
+
+    const list = host.querySelector<HTMLElement>('[role="list"]');
+    const rows = list?.querySelectorAll('[role="listitem"]') ?? [];
+    expect(rows.length).toBeGreaterThan(0);
+    expect(rows.length).toBeLessThanOrEqual(16);
+    expect(rows[0]?.getAttribute("aria-posinset")).toBe("1");
+    expect(rows[0]?.getAttribute("aria-setsize")).toBe("1000");
+    expect(list?.parentElement?.style.height).toBe(`${getTimelineCanvasHeight(1_000)}px`);
+
+    const firstRow = rows[0] as HTMLElement;
+    const focusedControl = firstRow.querySelector<HTMLButtonElement>("button");
+    expect(focusedControl).not.toBeNull();
+    act(() => focusedControl?.focus());
+    const scroller = host.querySelector<HTMLElement>("[data-timeline-scroll-viewport]");
+    expect(scroller).not.toBeNull();
+    if (scroller) {
+      scroller.scrollTop = 500 * 48;
+      await act(async () => {
+        scroller.dispatchEvent(new Event("scroll"));
+      });
+    }
+    expect(list?.querySelector('[data-timeline-row-key="0"]')).not.toBeNull();
+    expect(document.activeElement).toBe(focusedControl);
+
+    act(() => root.unmount());
+    usePlayerStore.getState().reset();
+  }, 10_000);
+});
diff --git a/packages/studio/src/player/components/TimelineCanvas.tsx b/packages/studio/src/player/components/TimelineCanvas.tsx
index 73b268e81e..c951fae98c 100644
--- a/packages/studio/src/player/components/TimelineCanvas.tsx
+++ b/packages/studio/src/player/components/TimelineCanvas.tsx
@@ -125,7 +125,7 @@ export const TimelineCanvas = memo(function TimelineCanvas(props: TimelineCanvas
 
       {/* Breathing room between the sticky ruler and the first track lane — the
           top half of the CapCut-style padding (see TRACKS_TOP_PAD). */}
-      <div aria-hidden="true" style={{ height: TRACKS_TOP_PAD }} />
+      <div aria-hidden="true" style={{ height: props.rowsVirtualized ? 0 : TRACKS_TOP_PAD }} />
 
       <TimelineLanes
         {...props}
@@ -142,7 +142,7 @@ export const TimelineCanvas = memo(function TimelineCanvas(props: TimelineCanvas
       {/* Breathing room below the last track lane (~1.5 track heights) — a real
           scrollable surface, so a clip can be dragged into the void to create a
           new bottom track comfortably (see TRACKS_BOTTOM_PAD / getTimelineCanvasHeight). */}
-      <div aria-hidden="true" style={{ height: TRACKS_BOTTOM_PAD }} />
+      <div aria-hidden="true" style={{ height: props.rowsVirtualized ? 0 : TRACKS_BOTTOM_PAD }} />
 
       {/* Gap strips — loud dashed fill for the gap(s) a hovered "Close gap(s)"
           menu row would collapse; a quiet tint for every gap on the selected
diff --git a/packages/studio/src/player/components/TimelineLaneTypes.ts b/packages/studio/src/player/components/TimelineLaneTypes.ts
index 2b35f89c16..f6a324e128 100644
--- a/packages/studio/src/player/components/TimelineLaneTypes.ts
+++ b/packages/studio/src/player/components/TimelineLaneTypes.ts
@@ -6,6 +6,8 @@ import type { TimelineTheme } from "./timelineTheme";
 import type { BlockedClipState, DraggedClipState, ResizingClipState } from "./useTimelineClipDrag";
 import type { TrackVisualStyle } from "./timelineIcons";
 import type { KeyframeCacheEntry, TimelineElement } from "../store/playerStore";
+import type { TimelineRowGeometry } from "./timelineLayout";
+import type { TimelineVirtualRow } from "./useTimelineVirtualRows";
 
 /** Props shared by TimelineCanvas and its lane renderer. */
 export interface TimelineLaneBaseProps {
@@ -16,6 +18,9 @@ export interface TimelineLaneBaseProps {
   theme: TimelineTheme;
   displayTrackOrder: number[];
   rowHeights: readonly number[];
+  rowGeometry: TimelineRowGeometry;
+  virtualRows: readonly TimelineVirtualRow[];
+  rowsVirtualized: boolean;
   trackOrder: number[];
   tracks: [number, TimelineElement[]][];
   trackStyles: Map<number, TrackVisualStyle>;
diff --git a/packages/studio/src/player/components/TimelineLanes.tsx b/packages/studio/src/player/components/TimelineLanes.tsx
index 2428c85669..ee00598667 100644
--- a/packages/studio/src/player/components/TimelineLanes.tsx
+++ b/packages/studio/src/player/components/TimelineLanes.tsx
@@ -5,7 +5,7 @@ import { TimelinePropertyLanes } from "./TimelinePropertyLanes";
 import { TimelineTrackHeader } from "./TimelineTrackHeader";
 import { resolveTrackKeyframeClip } from "./useTimelineTrackLayout";
 import { getTimelineEditCapabilities, resolveBlockedTimelineEditIntent } from "./timelineEditing";
-import { CLIP_Y, CLIP_HANDLE_W, TRACK_H, getTimelineRowHeight } from "./timelineLayout";
+import { CLIP_Y, CLIP_HANDLE_W, TRACK_H } from "./timelineLayout";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import {
   isMultiDragPassenger,
@@ -19,6 +19,7 @@ import { SPLIT_BOUNDARY_EPSILON_S } from "../../utils/timelineElementSplit";
 import { isAudioTimelineElement, isMusicTrack } from "../../utils/timelineInspector";
 import { renderClipChildren } from "./timelineClipChildren";
 import type { TimelineLaneBaseProps } from "./TimelineLaneTypes";
+import { TimelineTrackRow } from "./TimelineTrackRow";
 
 interface TimelineLanesProps extends TimelineLaneBaseProps {
   /** Live-derived by TimelineCanvas from {@link TimelineLaneBaseProps.draggedClip}. */
@@ -39,7 +40,9 @@ export function TimelineLanes({
   trackContentWidth,
   theme,
   displayTrackOrder,
-  rowHeights,
+  rowGeometry,
+  virtualRows,
+  rowsVirtualized,
   trackOrder,
   tracks,
   trackStyles,
@@ -95,16 +98,17 @@ export function TimelineLanes({
     toggleClipExpanded(key);
   };
   return (
-    <>
+    <div
+      role="list"
+      aria-label="Timeline tracks"
+      className={rowsVirtualized ? "absolute inset-0" : undefined}
+    >
       {
-        // NOTE (deliberate no-virtualization): lanes and their clips render via a
-        // plain `.map()` inside the scroll container rather than a windowing/virtualized
-        // list. NLE clip counts are small (dozens to low hundreds), so the DOM cost is
-        // bounded and virtualization's complexity isn't worth it. TODO: revisit and swap
-        // in a virtualizer if editorial workflows ever push very high clip counts.
         // fallow-ignore-next-line complexity
-        displayTrackOrder.map((trackNum, row) => {
-          const rowHeight = getTimelineRowHeight(row, rowHeights);
+        virtualRows.map(({ index: row, rowKey }) => {
+          const trackNum = displayTrackOrder[row];
+          if (trackNum === undefined) return null;
+          const rowHeight = rowGeometry.getRowHeight(row);
           const els = tracks.find(([t]) => t === trackNum)?.[1] ?? [];
           const ts = trackStyles.get(trackNum) ?? getTrackStyle("");
           const isPendingTrack =
@@ -131,14 +135,16 @@ export function TimelineLanes({
           const keyframeClipExpanded =
             keyframeClipKey != null && expandedClipIds.has(keyframeClipKey);
           return (
-            <div
-              key={trackNum}
-              className="relative flex"
-              style={{
-                height: rowHeight,
-                background: rowBackground,
-                borderBottom: `1px solid ${theme.rowBorder}`,
-              }}
+            <TimelineTrackRow
+              key={rowKey}
+              index={row}
+              rowKey={rowKey}
+              rowCount={displayTrackOrder.length}
+              top={rowGeometry.getRowTop(row)}
+              height={rowHeight}
+              virtualized={rowsVirtualized}
+              background={rowBackground}
+              borderColor={theme.rowBorder}
             >
               <TimelineTrackHeader
                 trackNumber={trackNum}
@@ -501,10 +507,10 @@ export function TimelineLanes({
                   })
                 }
               </div>
-            </div>
+            </TimelineTrackRow>
           );
         })
       }
-    </>
+    </div>
   );
 }
diff --git a/packages/studio/src/player/components/TimelineTrackRow.tsx b/packages/studio/src/player/components/TimelineTrackRow.tsx
new file mode 100644
index 0000000000..de1865a416
--- /dev/null
+++ b/packages/studio/src/player/components/TimelineTrackRow.tsx
@@ -0,0 +1,46 @@
+import type { ReactNode } from "react";
+
+interface TimelineTrackRowProps {
+  index: number;
+  rowKey: number;
+  rowCount: number;
+  top: number;
+  height: number;
+  virtualized: boolean;
+  background: string;
+  borderColor: string;
+  children: ReactNode;
+}
+
+/** Accessible row shell; edit geometry owns its exact top and height. */
+export function TimelineTrackRow({
+  index,
+  rowKey,
+  rowCount,
+  top,
+  height,
+  virtualized,
+  background,
+  borderColor,
+  children,
+}: TimelineTrackRowProps) {
+  return (
+    <div
+      role="listitem"
+      aria-posinset={index + 1}
+      aria-setsize={rowCount}
+      data-index={index}
+      data-timeline-row={index}
+      data-timeline-row-key={rowKey}
+      className={`${virtualized ? "absolute left-0 right-0" : "relative"} flex`}
+      style={{
+        top: virtualized ? top : undefined,
+        height,
+        background,
+        borderBottom: `1px solid ${borderColor}`,
+      }}
+    >
+      {children}
+    </div>
+  );
+}
diff --git a/packages/studio/src/player/components/timelineEditing.test.ts b/packages/studio/src/player/components/timelineEditing.test.ts
index f2c2913ead..c4771e230f 100644
--- a/packages/studio/src/player/components/timelineEditing.test.ts
+++ b/packages/studio/src/player/components/timelineEditing.test.ts
@@ -677,6 +677,38 @@ describe("resolveTimelineAutoScroll", () => {
       ),
     ).toEqual({ x: 9, y: 6 });
   });
+
+  it("uses the time-grid edge instead of the viewport edge when labels are sticky", () => {
+    expect(
+      resolveTimelineAutoScroll(
+        {
+          left: 100,
+          top: 100,
+          right: 700,
+          bottom: 400,
+        },
+        340,
+        250,
+        232,
+      ),
+    ).toEqual({ x: -10, y: 0 });
+  });
+
+  it("caps auto-scroll speed when the pointer moves inside the sticky labels", () => {
+    expect(
+      resolveTimelineAutoScroll(
+        {
+          left: 100,
+          top: 100,
+          right: 700,
+          bottom: 400,
+        },
+        120,
+        250,
+        232,
+      ),
+    ).toEqual({ x: -12, y: 0 });
+  });
 });
 
 describe("buildTimelineAgentPrompt", () => {
diff --git a/packages/studio/src/player/components/timelineEditing.ts b/packages/studio/src/player/components/timelineEditing.ts
index 9b08a67ce6..13343f927f 100644
--- a/packages/studio/src/player/components/timelineEditing.ts
+++ b/packages/studio/src/player/components/timelineEditing.ts
@@ -86,21 +86,24 @@ export function resolveTimelineAutoScroll(
   bounds: TimelineAutoScrollBounds,
   clientX: number,
   clientY: number,
+  leftInset = 0,
 ): { x: number; y: number } {
   const getAxisDelta = (start: number, end: number, pointer: number) => {
     if (pointer < start + AUTO_SCROLL_EDGE_ZONE) {
-      const proximity = Math.max(0, 1 - (pointer - start) / AUTO_SCROLL_EDGE_ZONE);
+      const proximity = Math.min(1, Math.max(0, 1 - (pointer - start) / AUTO_SCROLL_EDGE_ZONE));
       return -Math.round(AUTO_SCROLL_MAX_SPEED * proximity);
     }
     if (pointer > end - AUTO_SCROLL_EDGE_ZONE) {
-      const proximity = Math.max(0, 1 - (end - pointer) / AUTO_SCROLL_EDGE_ZONE);
+      const proximity = Math.min(1, Math.max(0, 1 - (end - pointer) / AUTO_SCROLL_EDGE_ZONE));
       return Math.round(AUTO_SCROLL_MAX_SPEED * proximity);
     }
     return 0;
   };
 
+  const horizontalStart = Math.min(bounds.right, bounds.left + Math.max(0, leftInset));
+
   return {
-    x: getAxisDelta(bounds.left, bounds.right, clientX),
+    x: getAxisDelta(horizontalStart, bounds.right, clientX),
     y: getAxisDelta(bounds.top, bounds.bottom, clientY),
   };
 }
@@ -486,7 +489,41 @@ export function applyTimelineAutoScrollStep(
   clientX: number,
   clientY: number,
 ): boolean {
-  const delta = resolveTimelineAutoScroll(scroll.getBoundingClientRect(), clientX, clientY);
+  return applyTimelineAutoScrollDelta(
+    scroll,
+    resolveTimelineAutoScroll(
+      scroll.getBoundingClientRect(),
+      clientX,
+      clientY,
+      getTimelineAutoScrollLeftInset(scroll),
+    ),
+  );
+}
+
+/** Apply one horizontal edge-scroll step while scrubbing the ruler/playhead. */
+export function applyTimelineHorizontalAutoScrollStep(
+  scroll: HTMLElement,
+  clientX: number,
+): boolean {
+  const bounds = scroll.getBoundingClientRect();
+  const delta = resolveTimelineAutoScroll(
+    bounds,
+    clientX,
+    bounds.top + (bounds.bottom - bounds.top) / 2,
+    getTimelineAutoScrollLeftInset(scroll),
+  );
+  return applyTimelineAutoScrollDelta(scroll, { x: delta.x, y: 0 });
+}
+
+function getTimelineAutoScrollLeftInset(scroll: HTMLElement): number {
+  const inset = Number(scroll.dataset.timelineAutoScrollLeftInset);
+  return Number.isFinite(inset) ? Math.max(0, inset) : 0;
+}
+
+function applyTimelineAutoScrollDelta(
+  scroll: HTMLElement,
+  delta: { x: number; y: number },
+): boolean {
   if (delta.x === 0 && delta.y === 0) return false;
   const maxScrollLeft = Math.max(0, scroll.scrollWidth - scroll.clientWidth);
   const maxScrollTop = Math.max(0, scroll.scrollHeight - scroll.clientHeight);
@@ -511,7 +548,12 @@ export function resolveTimelineAutoScrollLoopAction(
   rafActive: boolean,
 ): "start" | "stop" | "none" {
   if (!scroll) return "none";
-  const delta = resolveTimelineAutoScroll(scroll.getBoundingClientRect(), clientX, clientY);
+  const delta = resolveTimelineAutoScroll(
+    scroll.getBoundingClientRect(),
+    clientX,
+    clientY,
+    getTimelineAutoScrollLeftInset(scroll),
+  );
   if (delta.x === 0 && delta.y === 0) return rafActive ? "stop" : "none";
   return rafActive ? "none" : "start";
 }
diff --git a/packages/studio/src/player/components/timelineFocusIdentity.test.ts b/packages/studio/src/player/components/timelineFocusIdentity.test.ts
new file mode 100644
index 0000000000..edd7f4f176
--- /dev/null
+++ b/packages/studio/src/player/components/timelineFocusIdentity.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import { resolveTimelineFocusIdentity } from "./timelineFocusIdentity";
+
+describe("timeline focus identity", () => {
+  const elements: TimelineElement[] = [
+    { id: "clip/a", key: "stable:key", tag: "div", start: 0, duration: 1, track: 7.5 },
+  ];
+
+  it("resolves a stable element id and fractional display row from model identity", () => {
+    expect(resolveTimelineFocusIdentity(elements, "stable:key")).toEqual({
+      elementId: "stable:key",
+      rowKey: 7.5,
+    });
+  });
+
+  it("does not invent focus for a missing or cleared identity", () => {
+    expect(resolveTimelineFocusIdentity(elements, "missing")).toBeNull();
+    expect(resolveTimelineFocusIdentity(elements, null)).toBeNull();
+  });
+});
diff --git a/packages/studio/src/player/components/timelineFocusIdentity.ts b/packages/studio/src/player/components/timelineFocusIdentity.ts
new file mode 100644
index 0000000000..0f1f24e5a4
--- /dev/null
+++ b/packages/studio/src/player/components/timelineFocusIdentity.ts
@@ -0,0 +1,21 @@
+import type { TimelineElement } from "../store/playerStore";
+import { getTimelineElementIndexes } from "../lib/timelineElementIndexes";
+
+export interface TimelineFocusIdentity {
+  readonly elementId: string;
+  readonly rowKey: number;
+}
+
+/** Resolve logical focus from model identity; mount state is deliberately irrelevant. */
+export function resolveTimelineFocusIdentity(
+  elements: readonly TimelineElement[],
+  elementId: string | null,
+): TimelineFocusIdentity | null {
+  if (!elementId) return null;
+  const element = getTimelineElementIndexes(elements).byKey.get(elementId);
+  if (!element) return null;
+  return {
+    elementId,
+    rowKey: element.track,
+  };
+}
diff --git a/packages/studio/src/player/components/timelineLayout.ts b/packages/studio/src/player/components/timelineLayout.ts
index 302a84d60b..03688a8ec5 100644
--- a/packages/studio/src/player/components/timelineLayout.ts
+++ b/packages/studio/src/player/components/timelineLayout.ts
@@ -395,6 +395,47 @@ export function getTimelinePlayheadLeft(
   return contentOrigin + Math.max(0, time) * Math.max(0, pixelsPerSecond) - PLAYHEAD_HEAD_W / 2;
 }
 
+const PLAYBACK_FOLLOW_POSITION = 0.75;
+
+/**
+ * Keep a playing timeline calm until the playhead crosses the right-side
+ * comfort line, then advance the viewport just enough to hold it there. A
+ * loop/reverse jump that leaves the playhead behind the sticky labels restores
+ * the matching earlier viewport instead.
+ */
+export function getTimelinePlaybackFollowScrollLeft(input: {
+  playheadX: number;
+  currentScrollLeft: number;
+  viewportWidth: number;
+  contentOrigin: number;
+  maxScrollLeft: number;
+}): number {
+  const current = Number.isFinite(input.currentScrollLeft)
+    ? Math.max(0, input.currentScrollLeft)
+    : 0;
+  const max = Number.isFinite(input.maxScrollLeft) ? Math.max(0, input.maxScrollLeft) : 0;
+  const visibleTimelineWidth = input.viewportWidth - input.contentOrigin;
+  if (
+    !Number.isFinite(input.playheadX) ||
+    !Number.isFinite(input.contentOrigin) ||
+    !Number.isFinite(visibleTimelineWidth) ||
+    visibleTimelineWidth <= 0 ||
+    max <= 0
+  ) {
+    return Math.min(max, current);
+  }
+
+  const visibleStart = current + input.contentOrigin;
+  const followLine = visibleStart + visibleTimelineWidth * PLAYBACK_FOLLOW_POSITION;
+  let next = current;
+  if (input.playheadX > followLine) {
+    next = input.playheadX - input.contentOrigin - visibleTimelineWidth * PLAYBACK_FOLLOW_POSITION;
+  } else if (input.playheadX < visibleStart) {
+    next = input.playheadX - input.contentOrigin;
+  }
+  return Math.max(0, Math.min(max, next));
+}
+
 export function getTimelineCanvasHeight(trackCountOrHeights: number | readonly number[]): number {
   // RULER_H + top pad + lanes + bottom pad. The old TIMELINE_SCROLL_BUFFER is
   // subsumed by TRACKS_BOTTOM_PAD (which is larger), so the drag-into-void space
diff --git a/packages/studio/src/player/components/useTimelinePlayhead.ts b/packages/studio/src/player/components/useTimelinePlayhead.ts
index 245d04c4dd..c3dc027025 100644
--- a/packages/studio/src/player/components/useTimelinePlayhead.ts
+++ b/packages/studio/src/player/components/useTimelinePlayhead.ts
@@ -1,14 +1,16 @@
 import { useRef, useCallback, useEffect, useLayoutEffect } from "react";
-import { liveTime, type ZoomMode } from "../store/playerStore";
+import { liveTime, usePlayerStore, type ZoomMode } from "../store/playerStore";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { getPinchTimelineZoomPercent } from "./timelineZoom";
 import {
   getTimelineContentXFromClient,
+  getTimelinePlaybackFollowScrollLeft,
   getTimelinePlayheadLeft,
   getTimelineScrollLeftForZoomTransition,
   getTimelineScrollLeftForZoomAnchor,
   shouldAutoScrollTimeline,
 } from "./timelineLayout";
+import { applyTimelineHorizontalAutoScrollStep } from "./timelineEditing";
 
 interface UseTimelinePlayheadInput {
   playheadRef: React.RefObject<HTMLDivElement | null>;
@@ -121,9 +123,31 @@ export function useTimelinePlayhead({
   useMountEffect(() => {
     const unsub = liveTime.subscribe((t) => {
       if (!playheadRef.current || durationRef.current <= 0) return;
-      // Playback deliberately does NOT scroll the viewport to chase the playhead —
-      // the user's scroll position is theirs; the playhead may run off-screen.
-      playheadRef.current.style.left = `${getTimelinePlayheadLeft(t, ppsRef.current, contentOriginRef.current)}px`;
+      const playheadX = contentOriginRef.current + Math.max(0, t) * ppsRef.current;
+      playheadRef.current.style.left = `${getTimelinePlayheadLeft(
+        t,
+        ppsRef.current,
+        contentOriginRef.current,
+      )}px`;
+      const scroll = scrollRef.current;
+      if (
+        !scroll ||
+        !usePlayerStore.getState().isPlaying ||
+        isDragging.current ||
+        zoomModeRef.current === "fit"
+      ) {
+        return;
+      }
+      const nextScrollLeft = getTimelinePlaybackFollowScrollLeft({
+        playheadX,
+        currentScrollLeft: scroll.scrollLeft,
+        viewportWidth: scroll.clientWidth,
+        contentOrigin: contentOriginRef.current,
+        maxScrollLeft: scroll.scrollWidth - scroll.clientWidth,
+      });
+      if (Math.abs(nextScrollLeft - scroll.scrollLeft) >= 0.5) {
+        scroll.scrollLeft = nextScrollLeft;
+      }
     });
     return unsub;
   });
@@ -157,16 +181,7 @@ export function useTimelinePlayhead({
         !shouldAutoScrollTimeline(zoomModeRef.current, el.scrollWidth, el.clientWidth)
       )
         return;
-      const rect = el.getBoundingClientRect();
-      const edgeZone = 40;
-      const maxSpeed = 12;
-      let scrollDelta = 0;
-      if (clientX < rect.left + edgeZone)
-        scrollDelta = -maxSpeed * Math.max(0, 1 - (clientX - rect.left) / edgeZone);
-      else if (clientX > rect.right - edgeZone)
-        scrollDelta = maxSpeed * Math.max(0, 1 - (rect.right - clientX) / edgeZone);
-      if (scrollDelta !== 0) {
-        el.scrollLeft += scrollDelta;
+      if (applyTimelineHorizontalAutoScrollStep(el, clientX)) {
         seekFromX(clientX);
         dragScrollRaf.current = requestAnimationFrame(() => autoScrollDuringDrag(clientX));
       }
diff --git a/packages/studio/src/player/components/useTimelineRowVirtualization.ts b/packages/studio/src/player/components/useTimelineRowVirtualization.ts
new file mode 100644
index 0000000000..5bebda0861
--- /dev/null
+++ b/packages/studio/src/player/components/useTimelineRowVirtualization.ts
@@ -0,0 +1,135 @@
+import { useEffect, useLayoutEffect, useMemo, useRef, useState, type RefObject } from "react";
+import type { TimelineElement } from "../store/playerStore";
+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";
+
+interface UseTimelineRowVirtualizationInput {
+  scrollRef: RefObject<HTMLDivElement | null>;
+  viewport: TimelineScrollViewportSnapshot;
+  rowGeometry: TimelineRowGeometry;
+  sessionEpoch: number;
+  elements: TimelineElement[];
+  selectedElementId: string | null;
+  revealElementId: string | null;
+  draggedRowKey?: number;
+  resizingRowKey?: number;
+  clipContextMenuRowKey?: number;
+  keyframeContextMenuRowKey?: number;
+  lastScrollLeftRef: RefObject<number>;
+  syncScrollViewport: (element: HTMLDivElement, isScrolling?: boolean) => void;
+}
+
+function getFocusedTimelineRowKey(target: EventTarget | null): number | undefined {
+  if (!(target instanceof Element)) return undefined;
+  const value = target.closest<HTMLElement>("[data-timeline-row-key]")?.dataset.timelineRowKey;
+  if (value === undefined) return undefined;
+  const rowKey = Number(value);
+  return Number.isFinite(rowKey) ? rowKey : undefined;
+}
+
+export function useTimelineRowVirtualization({
+  scrollRef,
+  viewport,
+  rowGeometry,
+  sessionEpoch,
+  elements,
+  selectedElementId,
+  revealElementId,
+  draggedRowKey,
+  resizingRowKey,
+  clipContextMenuRowKey,
+  keyframeContextMenuRowKey,
+  lastScrollLeftRef,
+  syncScrollViewport,
+}: UseTimelineRowVirtualizationInput) {
+  const enabled =
+    STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED &&
+    viewport.clientWidth > 0 &&
+    viewport.clientHeight > 0;
+  const [domFocusedRowKey, setDomFocusedRowKey] = useState<number>();
+  useEffect(() => {
+    const scroll = scrollRef.current;
+    if (!scroll) return;
+    const handleFocusIn = (event: FocusEvent) => {
+      setDomFocusedRowKey(getFocusedTimelineRowKey(event.target));
+    };
+    const handleFocusOut = (event: FocusEvent) => {
+      setDomFocusedRowKey(getFocusedTimelineRowKey(event.relatedTarget));
+    };
+    scroll.addEventListener("focusin", handleFocusIn);
+    scroll.addEventListener("focusout", handleFocusOut);
+    return () => {
+      scroll.removeEventListener("focusin", handleFocusIn);
+      scroll.removeEventListener("focusout", handleFocusOut);
+    };
+  }, [scrollRef, sessionEpoch]);
+  const focusIdentity = useMemo(
+    () => resolveTimelineFocusIdentity(elements, selectedElementId),
+    [elements, selectedElementId],
+  );
+  const revealIdentity = useMemo(
+    () => resolveTimelineFocusIdentity(elements, revealElementId),
+    [elements, revealElementId],
+  );
+  const pinnedRowKeys = useMemo(
+    () =>
+      [
+        draggedRowKey,
+        resizingRowKey,
+        revealIdentity?.rowKey,
+        clipContextMenuRowKey,
+        keyframeContextMenuRowKey,
+      ].filter((rowKey): rowKey is number => rowKey !== undefined),
+    [
+      clipContextMenuRowKey,
+      draggedRowKey,
+      keyframeContextMenuRowKey,
+      resizingRowKey,
+      revealIdentity,
+    ],
+  );
+  const virtualRows = useTimelineVirtualRows({
+    enabled,
+    scrollRef,
+    viewport,
+    rowGeometry,
+    sessionEpoch,
+    pinnedRowKeys,
+    focusedRowKey: domFocusedRowKey ?? focusIdentity?.rowKey,
+  });
+
+  const previousLayoutRef = useRef(rowGeometry);
+  const previousSessionEpochRef = useRef(sessionEpoch);
+  useLayoutEffect(() => {
+    const scroll = scrollRef.current;
+    const previousGeometry = previousLayoutRef.current;
+    if (previousSessionEpochRef.current !== sessionEpoch) {
+      previousSessionEpochRef.current = sessionEpoch;
+      lastScrollLeftRef.current = 0;
+      if (scroll) {
+        scroll.scrollLeft = 0;
+        scroll.scrollTop = 0;
+        syncScrollViewport(scroll);
+      }
+    } else if (scroll && previousGeometry !== rowGeometry) {
+      const nextScrollTop = getTimelineScrollTopForGeometryChange(
+        previousGeometry,
+        rowGeometry,
+        scroll.scrollTop,
+      );
+      if (nextScrollTop !== scroll.scrollTop) {
+        scroll.scrollTop = nextScrollTop;
+        syncScrollViewport(scroll);
+      }
+    }
+    previousLayoutRef.current = rowGeometry;
+  }, [lastScrollLeftRef, rowGeometry, scrollRef, sessionEpoch, syncScrollViewport]);
+
+  return { enabled, virtualRows };
+}
diff --git a/packages/studio/src/player/components/useTimelineVirtualRows.test.tsx b/packages/studio/src/player/components/useTimelineVirtualRows.test.tsx
new file mode 100644
index 0000000000..582fbfeeb0
--- /dev/null
+++ b/packages/studio/src/player/components/useTimelineVirtualRows.test.tsx
@@ -0,0 +1,174 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { createTimelineRowGeometry, RULER_H, TRACKS_TOP_PAD } from "./timelineLayout";
+import { extractTimelineVirtualRowRange, useTimelineVirtualRows } from "./useTimelineVirtualRows";
+import type { TimelineScrollViewportSnapshot } from "./useTimelineScrollViewport";
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+class MockResizeObserver {
+  constructor(private readonly callback: ResizeObserverCallback) {}
+  observe(target: Element) {
+    const { width, height } = target.getBoundingClientRect();
+    this.callback(
+      [
+        {
+          target,
+          borderBoxSize: [{ inlineSize: width, blockSize: height }],
+        } as unknown as ResizeObserverEntry,
+      ],
+      this as unknown as ResizeObserver,
+    );
+  }
+  unobserve() {}
+  disconnect() {}
+}
+
+const originalResizeObserver = globalThis.ResizeObserver;
+
+beforeAll(() => {
+  globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+});
+
+afterAll(() => {
+  globalThis.ResizeObserver = originalResizeObserver;
+});
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+function createScrollElement(scrollTop: number, width = 800, height = 192): HTMLDivElement {
+  const element = document.createElement("div");
+  document.body.append(element);
+  Object.defineProperties(element, {
+    scrollTop: { configurable: true, writable: true, value: scrollTop },
+    scrollLeft: { configurable: true, writable: true, value: 0 },
+    clientWidth: { configurable: true, value: width },
+    clientHeight: { configurable: true, value: height },
+    scrollWidth: { configurable: true, value: width },
+    scrollHeight: { configurable: true, value: 60_000 },
+  });
+  element.getBoundingClientRect = () =>
+    ({ width, height, top: 0, left: 0, right: width, bottom: height, x: 0, y: 0 }) as DOMRect;
+  return element;
+}
+
+function viewport(element: HTMLDivElement): TimelineScrollViewportSnapshot {
+  return {
+    scrollLeft: element.scrollLeft,
+    scrollTop: element.scrollTop,
+    clientWidth: element.clientWidth,
+    clientHeight: element.clientHeight,
+    scrollWidth: element.scrollWidth,
+    scrollHeight: element.scrollHeight,
+    isScrolling: false,
+  };
+}
+
+function createLargeGeometry(keyOffset = 0) {
+  const keys = Array.from({ length: 1_000 }, (_, index) => index + keyOffset);
+  return createTimelineRowGeometry(
+    keys,
+    keys.map(() => 48),
+  );
+}
+
+describe("extractTimelineVirtualRowRange", () => {
+  it("unions visible overscan with unique actor pins", () => {
+    expect(
+      extractTimelineVirtualRowRange(
+        { startIndex: 10, endIndex: 12, overscan: 2, count: 100 },
+        [0, 11, 99, 99, -1, 100],
+      ),
+    ).toEqual([0, 8, 9, 10, 11, 12, 13, 14, 99]);
+  });
+});
+
+describe("useTimelineVirtualRows", () => {
+  it("mounts a bounded vertical range plus the focused row", () => {
+    const geometry = createLargeGeometry(0.5);
+    const scroll = createScrollElement(RULER_H + TRACKS_TOP_PAD + 500 * 48);
+    const scrollRef = { current: scroll };
+    let rows: ReturnType<typeof useTimelineVirtualRows> = [];
+
+    function Probe() {
+      rows = useTimelineVirtualRows({
+        enabled: true,
+        scrollRef,
+        viewport: viewport(scroll),
+        rowGeometry: geometry,
+        sessionEpoch: 1,
+        pinnedRowKeys: [],
+        focusedRowKey: 900.5,
+      });
+      return null;
+    }
+
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(React.createElement(Probe)));
+    act(() => {});
+
+    expect(rows.length).toBeGreaterThan(0);
+    expect(rows.length).toBeLessThanOrEqual(16);
+    expect(rows.some((row) => row.index === 500)).toBe(true);
+    expect(rows.some((row) => row.rowKey === 900.5)).toBe(true);
+    act(() => root.unmount());
+  });
+
+  it("keeps compatibility rendering complete while the gate is disabled", () => {
+    const geometry = createTimelineRowGeometry([10, 5.5, 20], [48, 76, 48]);
+    const scroll = createScrollElement(0);
+    let rows: ReturnType<typeof useTimelineVirtualRows> = [];
+
+    function Probe() {
+      rows = useTimelineVirtualRows({
+        enabled: false,
+        scrollRef: { current: scroll },
+        viewport: viewport(scroll),
+        rowGeometry: geometry,
+        sessionEpoch: 1,
+        pinnedRowKeys: [],
+      });
+      return null;
+    }
+
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(React.createElement(Probe)));
+    expect(rows.map((row) => row.rowKey)).toEqual([10, 5.5, 20]);
+    act(() => root.unmount());
+  });
+
+  it("observes Timeline's authoritative scroll reset when the session epoch changes", () => {
+    const geometry = createLargeGeometry();
+    const scroll = createScrollElement(RULER_H + TRACKS_TOP_PAD + 500 * 48);
+    const scrollRef = { current: scroll };
+    let rows: ReturnType<typeof useTimelineVirtualRows> = [];
+
+    function Probe({ sessionEpoch }: { sessionEpoch: number }) {
+      rows = useTimelineVirtualRows({
+        enabled: true,
+        scrollRef,
+        viewport: viewport(scroll),
+        rowGeometry: geometry,
+        sessionEpoch,
+        pinnedRowKeys: [],
+      });
+      return null;
+    }
+
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(React.createElement(Probe, { sessionEpoch: 1 })));
+    expect(rows.some((row) => row.index === 500)).toBe(true);
+
+    scroll.scrollTop = 0;
+    act(() => root.render(React.createElement(Probe, { sessionEpoch: 2 })));
+    expect(rows.some((row) => row.index === 0)).toBe(true);
+    expect(rows.some((row) => row.index === 500)).toBe(false);
+
+    act(() => root.unmount());
+  });
+});
diff --git a/packages/studio/src/player/components/useTimelineVirtualRows.ts b/packages/studio/src/player/components/useTimelineVirtualRows.ts
new file mode 100644
index 0000000000..d891474059
--- /dev/null
+++ b/packages/studio/src/player/components/useTimelineVirtualRows.ts
@@ -0,0 +1,110 @@
+import { useCallback, useEffect, useMemo, type RefObject } from "react";
+import { defaultRangeExtractor, useVirtualizer, type Range } from "@tanstack/react-virtual";
+import { TIMELINE_VIEWPORT_BUDGETS } from "../lib/timelineViewportBudgets";
+import type { TimelineScrollViewportSnapshot } from "./useTimelineScrollViewport";
+import { RULER_H, TRACKS_TOP_PAD, type TimelineRowGeometry } from "./timelineLayout";
+
+/** Disabled until horizontal windowing and stable gesture lifetime land. */
+export const STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED =
+  import.meta.env.DEV === true &&
+  import.meta.env.VITE_STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED === "1";
+
+export interface TimelineVirtualRow {
+  readonly index: number;
+  readonly rowKey: number;
+}
+
+export function extractTimelineVirtualRowRange(
+  range: Range,
+  pinnedRowIndexes: readonly number[],
+): number[] {
+  const indexes = new Set(defaultRangeExtractor(range));
+  for (const index of pinnedRowIndexes) {
+    if (index >= 0 && index < range.count) indexes.add(index);
+  }
+  return [...indexes].sort((left, right) => left - right);
+}
+
+interface UseTimelineVirtualRowsInput {
+  enabled: boolean;
+  scrollRef: RefObject<HTMLDivElement | null>;
+  viewport: TimelineScrollViewportSnapshot;
+  rowGeometry: TimelineRowGeometry;
+  sessionEpoch: number;
+  pinnedRowKeys: readonly number[];
+  focusedRowKey?: number;
+}
+
+export function useTimelineVirtualRows({
+  enabled,
+  scrollRef,
+  viewport,
+  rowGeometry,
+  sessionEpoch,
+  pinnedRowKeys,
+  focusedRowKey,
+}: UseTimelineVirtualRowsInput): readonly TimelineVirtualRow[] {
+  const pinnedRowIndexes = useMemo(
+    () => [
+      ...new Set(
+        [...pinnedRowKeys, ...(focusedRowKey === undefined ? [] : [focusedRowKey])].map((key) =>
+          rowGeometry.getRowIndex(key),
+        ),
+      ),
+    ],
+    [focusedRowKey, pinnedRowKeys, rowGeometry],
+  );
+  const estimateSize = useCallback(
+    (index: number) => rowGeometry.getRowHeight(index),
+    [rowGeometry],
+  );
+  const getItemKey = useCallback(
+    (index: number) => rowGeometry.rowKeys[index] ?? index,
+    [rowGeometry],
+  );
+  const rangeExtractor = useCallback(
+    (range: Range) => extractTimelineVirtualRowRange(range, pinnedRowIndexes),
+    [pinnedRowIndexes],
+  );
+  const initialOffset = useCallback(() => viewport.scrollTop, [viewport.scrollTop]);
+  const virtualizer = useVirtualizer({
+    enabled,
+    useFlushSync: false,
+    count: rowGeometry.rowKeys.length,
+    getScrollElement: () => scrollRef.current,
+    estimateSize,
+    getItemKey,
+    overscan: TIMELINE_VIEWPORT_BUDGETS.rowOverscanPerSide,
+    rangeExtractor,
+    scrollMargin: RULER_H + TRACKS_TOP_PAD,
+    initialRect: { width: viewport.clientWidth, height: viewport.clientHeight },
+    initialOffset,
+  });
+
+  useEffect(() => {
+    if (!enabled) return;
+    virtualizer.measure();
+    // Timeline owns the epoch reset. This event only makes the virtualizer
+    // observe the authoritative DOM offset after that reset; it never writes
+    // scrollTop itself.
+    scrollRef.current?.dispatchEvent(new Event("scroll"));
+  }, [enabled, scrollRef, sessionEpoch, virtualizer]);
+
+  const focusedRowIndex = focusedRowKey === undefined ? -1 : rowGeometry.getRowIndex(focusedRowKey);
+  const focusedRowHeight = focusedRowIndex < 0 ? 0 : rowGeometry.getRowHeight(focusedRowIndex);
+  useEffect(() => {
+    if (enabled && focusedRowIndex >= 0) {
+      virtualizer.resizeItem(focusedRowIndex, focusedRowHeight);
+    }
+  }, [enabled, focusedRowHeight, focusedRowIndex, sessionEpoch, virtualizer]);
+
+  const allRows = useMemo(
+    () => rowGeometry.rowKeys.map((rowKey, index) => ({ index, rowKey })),
+    [rowGeometry],
+  );
+  if (!enabled) return allRows;
+  return virtualizer.getVirtualItems().map(({ index }) => ({
+    index,
+    rowKey: rowGeometry.rowKeys[index] ?? index,
+  }));
+}