refactor(studio): isolate clip drag lifecycle

packages/studio/package.json

@@ -49,6 +49,7 @@
     "build": "vite build && tsup",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "test:timeline-virtualization": "node tests/e2e/timeline-virtualization.mjs",
     "test:watch": "vitest",
     "report:sdk-cutover": "bun src/utils/sdkCutoverPolicy.report.ts"
   },

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

@@ -0,0 +1,150 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore } from "../player/store/playerStore";
+import {
+  createTimelinePerformanceFixture,
+  type TimelinePerformanceFixtureProfile,
+} from "../player/lib/timelinePerformanceFixture";
+import { useStudioTestHooks } from "./useStudioTestHooks";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+const PROFILES: readonly TimelinePerformanceFixtureProfile[] = [
+  "dense-short",
+  "long-overlap",
+  "keyframe-heavy-expanded",
+  "composition-heavy",
+  "remote-unsupported",
+];
+
+function Probe(): null {
+  useStudioTestHooks({
+    previewIframeRef: { current: null },
+    buildDomSelectionFromTarget: vi.fn(),
+    applyDomSelection: vi.fn(),
+  });
+  return null;
+}
+
+describe("timeline performance fixture", () => {
+  afterEach(() => {
+    window.__studioTest = undefined;
+    usePlayerStore.getState().reset();
+  });
+
+  it("generates the expected dense-short 50k distribution", () => {
+    const first = createTimelinePerformanceFixture({
+      elementCount: 50_000,
+      profile: "dense-short",
+    });
+
+    expect(first.summary).toEqual({
+      elementCount: 50_000,
+      profile: "dense-short",
+      duration: 120,
+      trackCount: 1_000,
+      keyframedElementCount: 0,
+      expandedElementCount: 0,
+    });
+    expect(new Set(first.elements.map((element) => element.track)).size).toBe(1_000);
+    const perTrack = new Map<number, number>();
+    for (const element of first.elements) {
+      perTrack.set(element.track, (perTrack.get(element.track) ?? 0) + 1);
+    }
+    expect(Math.max(...perTrack.values())).toBeLessThanOrEqual(128);
+  });
+
+  it.each(PROFILES)("generates an identical 50k %s fixture", (profile) => {
+    const first = createTimelinePerformanceFixture({ elementCount: 50_000, profile });
+    const second = createTimelinePerformanceFixture({ elementCount: 50_000, profile });
+    expect(second).toEqual(first);
+  });
+
+  it.each(PROFILES)("builds the %s 1k scale profile", (profile) => {
+    const fixture = createTimelinePerformanceFixture({ elementCount: 1_000, profile });
+    expect(fixture.elements).toHaveLength(1_000);
+    expect(fixture.summary.elementCount).toBe(1_000);
+    expect(fixture.summary.duration).toBeGreaterThan(0);
+    expect(new Set(fixture.elements.map((element) => element.key)).size).toBe(1_000);
+    if (profile === "keyframe-heavy-expanded") {
+      expect(fixture.keyframeCache.size).toBe(1_000);
+      expect(fixture.gsapAnimations.size).toBe(1_000);
+      expect(fixture.expandedClipIds.size).toBe(1_000);
+    }
+  });
+
+  it("publishes one dev-only loader that replaces fixture state atomically", () => {
+    const host = document.createElement("div");
+    const root = createRoot(host);
+    act(() => root.render(<Probe />));
+    const api = window.__studioTest;
+    expect(api).toBeDefined();
+    if (!api) throw new Error("Expected dev Studio test API");
+    let notifications = 0;
+    usePlayerStore.setState({
+      isPlaying: true,
+      requestedSeekTime: 42,
+      clipRevealRequest: { elementId: "stale", nonce: 7 },
+      clipManifest: [],
+      lintFindingsByElement: new Map([["stale", { count: 1, messages: ["stale"] }]]),
+    });
+    const unsubscribe = usePlayerStore.subscribe(() => {
+      notifications += 1;
+    });
+
+    const summary = api.loadTimelinePerformanceFixture({
+      elementCount: 1_000,
+      profile: "keyframe-heavy-expanded",
+    });
+
+    expect(summary.elementCount).toBe(1_000);
+    expect(notifications).toBe(1);
+    expect(usePlayerStore.getState()).toMatchObject({
+      isPlaying: false,
+      requestedSeekTime: null,
+      clipRevealRequest: null,
+      clipManifest: null,
+      duration: 600,
+      timelineReady: true,
+    });
+    expect(usePlayerStore.getState().lintFindingsByElement.size).toBe(0);
+    expect(usePlayerStore.getState().elements).toHaveLength(1_000);
+    expect(usePlayerStore.getState().expandedClipIds.size).toBe(1_000);
+
+    api.resetTimelinePerformanceFixture();
+    expect(notifications).toBe(2);
+    expect(usePlayerStore.getState()).toMatchObject({
+      isPlaying: false,
+      duration: 0,
+      timelineReady: false,
+      elements: [],
+    });
+    unsubscribe();
+    act(() => root.unmount());
+    expect(window.__studioTest).toBeUndefined();
+  });
+
+  it("does not mutate state when the fixture request is invalid", () => {
+    const host = document.createElement("div");
+    const root = createRoot(host);
+    act(() => root.render(<Probe />));
+    const api = window.__studioTest;
+    if (!api) throw new Error("Expected dev Studio test API");
+    const before = usePlayerStore.getState().elements;
+
+    expect(() =>
+      Reflect.apply(api.loadTimelinePerformanceFixture, api, [
+        { elementCount: 999, profile: "dense-short" },
+      ]),
+    ).toThrow("elementCount must be 1000 or 50000");
+    expect(usePlayerStore.getState().elements).toBe(before);
+    expect(() =>
+      Reflect.apply(api.loadTimelinePerformanceFixture, api, [
+        { elementCount: 1_000, profile: "constructor" },
+      ]),
+    ).toThrow("Unknown timeline performance fixture profile");
+    act(() => root.unmount());
+  });
+});

packages/studio/src/hooks/useStudioTestHooks.ts

@@ -1,5 +1,16 @@
 import { useEffect } from "react";
 import type { DomEditSelection } from "../components/editor/domEditing";
+import { createTimelineResetState, usePlayerStore } from "../player/store/playerStore";
+import {
+  readTimelinePerformanceDiagnostics,
+  type TimelinePerformanceDiagnostics,
+} from "../player/lib/timelinePerformanceDiagnostics";
+import {
+  createTimelinePerformanceFixture,
+  type TimelinePerformanceFixtureSpec,
+  type TimelinePerformanceFixtureSummary,
+} from "../player/lib/timelinePerformanceFixture";
+import { TIMELINE_VIEWPORT_BUDGETS } from "../player/lib/timelineViewportBudgets";
 
 interface StudioTestHookDeps {
   previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
@@ -12,6 +23,12 @@ interface StudioTestHookDeps {
 
 interface StudioTestApi {
   selectByDomId: (id: string) => Promise<boolean>;
+  loadTimelinePerformanceFixture: (
+    spec: TimelinePerformanceFixtureSpec,
+  ) => TimelinePerformanceFixtureSummary;
+  resetTimelinePerformanceFixture: () => void;
+  readTimelinePerformanceDiagnostics: () => Readonly<TimelinePerformanceDiagnostics>;
+  timelineViewportBudgets: typeof TIMELINE_VIEWPORT_BUDGETS;
 }
 
 declare global {
@@ -52,6 +69,31 @@ export function useStudioTestHooks({
         applyDomSelection(selection, { revealPanel: true });
         return true;
       },
+      loadTimelinePerformanceFixture: (spec) => {
+        const fixture = createTimelinePerformanceFixture(spec);
+        usePlayerStore.setState({
+          ...createTimelineResetState(),
+          currentTime: 0,
+          duration: fixture.summary.duration,
+          timelineReady: true,
+          loopEnabled: false,
+          zoomMode: "manual",
+          manualZoomPercent: 2_000,
+          elements: fixture.elements,
+          selectedElementId: null,
+          selectedElementIds: new Set(),
+          selectedKeyframes: new Set(),
+          keyframeCache: fixture.keyframeCache,
+          gsapAnimations: fixture.gsapAnimations,
+          expandedClipIds: fixture.expandedClipIds,
+        });
+        return fixture.summary;
+      },
+      resetTimelinePerformanceFixture: () => {
+        usePlayerStore.getState().reset();
+      },
+      readTimelinePerformanceDiagnostics: () => readTimelinePerformanceDiagnostics(),
+      timelineViewportBudgets: TIMELINE_VIEWPORT_BUDGETS,
     };
     window.__studioTest = api;
     return () => {

packages/studio/src/player/components/TimelineLanes.test.tsx

@@ -144,6 +144,7 @@ describe("TimelineLanes track numbering", () => {
     });
 
     expect(visibilityLabels(view.host)).toEqual(["Hide track 1", "Hide track 2"]);
+    expect(view.host.querySelectorAll("[data-timeline-row]")).toHaveLength(2);
     expect(view.host.innerHTML).not.toContain("0.16666666666666666");
     act(() => view.root.unmount());
   });

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

@@ -150,6 +150,7 @@ export function TimelineLanes({
           return (
             <div
               key={trackNum}
+              data-timeline-row
               className="relative flex"
               style={{
                 height: rowHeight,

packages/studio/src/player/components/timelineClipDragGestureLifecycle.test.ts

@@ -0,0 +1,97 @@
+// @vitest-environment happy-dom
+
+import type { SetStateAction } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { mountTimelineClipDragGestureLifecycle } from "./timelineClipDragGestureLifecycle";
+import type { DraggedClipState, ResizingClipState } from "./timelineClipDragTypes";
+
+afterEach(() => {
+  document.body.replaceChildren();
+  usePlayerStore.getState().reset();
+});
+
+describe("timeline clip drag gesture lifecycle", () => {
+  it("finishes a drag after virtualization unmounts its source row", () => {
+    const element: TimelineElement = {
+      id: "clip-1",
+      tag: "div",
+      start: 0,
+      duration: 2,
+      track: 0,
+    };
+    const drag: DraggedClipState = {
+      element,
+      originClientX: 0,
+      originClientY: 0,
+      originScrollLeft: 0,
+      originScrollTop: 0,
+      pointerClientX: 0,
+      pointerClientY: 0,
+      pointerOffsetX: 0,
+      pointerOffsetY: 0,
+      previewStart: 1,
+      previewTrack: 0,
+      desiredTrack: 0,
+      insertRow: null,
+      snapTime: null,
+      snapType: null,
+      started: true,
+    };
+    const draggedClipRef = { current: drag as DraggedClipState | null };
+    const resizingClipRef = { current: null as ResizingClipState | null };
+    const setDraggedClip = (next: SetStateAction<DraggedClipState | null>) => {
+      draggedClipRef.current = typeof next === "function" ? next(draggedClipRef.current) : next;
+    };
+    const updateDraggedClipPreview = vi.fn((previous: DraggedClipState) => ({
+      ...previous,
+      previewStart: 3,
+    }));
+    const onMoveElement = vi.fn();
+    const stopAutoScroll = vi.fn();
+    const dispose = mountTimelineClipDragGestureLifecycle({
+      draggedClipRef,
+      resizingClipRef,
+      blockedClipRef: { current: null },
+      groupResizeRef: { current: null },
+      suppressClickRef: { current: false },
+      elementsRef: { current: [element] },
+      trackOrderRef: { current: [0] },
+      setDraggedClip,
+      setResizingClip: () => {},
+      setShowPopover: () => {},
+      setRangeSelectionRef: { current: null },
+      applyResizePointerRef: { current: () => {} },
+      syncClipDragAutoScrollRef: { current: () => {} },
+      stopClipDragAutoScrollRef: { current: stopAutoScroll },
+      updateDraggedClipPreviewRef: { current: updateDraggedClipPreview },
+      restoreGroupResizeMembers: () => {},
+      updateElement: vi.fn(),
+      onMoveElementRef: { current: onMoveElement },
+      onMoveElementsRef: { current: undefined },
+      onResizeElementRef: { current: undefined },
+      onResizeElementsRef: { current: undefined },
+      onBlockedEditAttemptRef: { current: undefined },
+      readZIndexRef: { current: undefined },
+      onStackingPatchesRef: { current: undefined },
+      refreshAfterLaneMoveRef: { current: undefined },
+    });
+
+    const sourceRow = document.createElement("div");
+    sourceRow.dataset.timelineRow = "";
+    sourceRow.append(document.createElement("div"));
+    document.body.append(sourceRow);
+    sourceRow.remove();
+
+    window.dispatchEvent(new MouseEvent("pointermove", { clientX: 20, clientY: 10 }));
+    expect(updateDraggedClipPreview).toHaveBeenCalledTimes(1);
+    expect(draggedClipRef.current?.previewStart).toBe(3);
+
+    window.dispatchEvent(new MouseEvent("pointerup"));
+    expect(onMoveElement).toHaveBeenCalledWith(element, { start: 3, track: 0 });
+    expect(draggedClipRef.current).toBeNull();
+    expect(stopAutoScroll).toHaveBeenCalledTimes(1);
+
+    dispose();
+  });
+});