perf(studio): add timeline clip-window index primitive

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

packages/studio/src/components/nle/NLEContext.tsx

@@ -48,6 +48,7 @@ export interface NLEContextValue {
   compositionLoading: boolean;
   setCompositionLoading: (loading: boolean) => void;
   timelineDisabled: boolean;
+  timelineSessionEpoch: number;
   hasLoadedOnceRef: React.MutableRefObject<boolean>;
   // preview composition size (for preview block drop)
   previewCompositionSize: { width: number; height: number } | null;
@@ -103,7 +104,7 @@ export function NLEProvider({
   // project would otherwise keep rendering (and re-fetching from) the old project
   // after switching.
   useEffect(() => {
-    usePlayerStore.getState().reset();
+    usePlayerStore.getState().beginTimelineSession(projectId);
     useAssetPreviewStore.getState().clearPreviewAsset();
   }, [projectId]);
 
@@ -289,6 +290,7 @@ export function NLEProvider({
     setCompositionLoadingRaw(loading);
   }, []);
   const timelineDisabled = shouldDisableTimelineWhileCompositionLoading(compositionLoading);
+  const timelineSessionEpoch = usePlayerStore((state) => state.timelineSessionEpoch);
 
   useEffect(() => {
     onCompositionLoadingChange?.(compositionLoading);
@@ -319,6 +321,7 @@ export function NLEProvider({
     compositionLoading,
     setCompositionLoading,
     timelineDisabled,
+    timelineSessionEpoch,
     hasLoadedOnceRef,
     previewCompositionSize,
     setPreviewCompositionSize,

packages/studio/src/components/nle/TimelinePane.tsx

@@ -127,6 +127,7 @@ export function TimelinePane({
     persistTimelineH,
     containerRef,
     timelineDisabled,
+    timelineSessionEpoch,
   } = useNLEContext();
 
   // Move/resize/split come from the timeline edit context, not props — the
@@ -271,6 +272,7 @@ export function TimelinePane({
         >
           <div className="flex-shrink-0">{timelineToolbar}</div>
           <Timeline
+            sessionEpoch={timelineSessionEpoch}
             onSeek={seek}
             onDrillDown={handleDrillDown}
             renderClipContent={renderClipContent}

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

@@ -0,0 +1,156 @@
+// @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,
+  hasTimelinePerformanceFixtureLease,
+  setTimelinePerformanceFixtureLease,
+  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(() => {
+    setTimelinePerformanceFixtureLease(false);
+    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);
+    expect(hasTimelinePerformanceFixtureLease()).toBe(true);
+
+    api.resetTimelinePerformanceFixture();
+    expect(notifications).toBe(2);
+    expect(usePlayerStore.getState()).toMatchObject({
+      isPlaying: false,
+      duration: 0,
+      timelineReady: false,
+      elements: [],
+    });
+    expect(hasTimelinePerformanceFixtureLease()).toBe(true);
+    unsubscribe();
+    act(() => root.unmount());
+    expect(window.__studioTest).toBeUndefined();
+    expect(hasTimelinePerformanceFixtureLease()).toBe(false);
+  });
+
+  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,17 @@
 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,
+  setTimelinePerformanceFixtureLease,
+  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 +24,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,9 +70,36 @@ export function useStudioTestHooks({
         applyDomSelection(selection, { revealPanel: true });
         return true;
       },
+      loadTimelinePerformanceFixture: (spec) => {
+        const fixture = createTimelinePerformanceFixture(spec);
+        setTimelinePerformanceFixtureLease(true);
+        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 () => {
+      setTimelinePerformanceFixtureLease(false);
       // 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/BeatStrip.tsx

@@ -1,7 +1,8 @@
 import { memo, useRef, useState } from "react";
 import { moveBeatCompositionTime, deleteBeatAtCompositionTime } from "../../utils/beatEditActions";
 import { usePlayerStore } from "../store/playerStore";
-import { CLIP_Y } from "./timelineLayout";
+import { CLIP_Y, getTimelineBeatEntries } from "./timelineLayout";
+import type { TimelineTimeRange } from "../lib/timelineClipIndex";
 
 export const BEAT_BAND_H = 14; // dark band height at top of track
 const BEAT_HIT_W = 12; // grab width per beat (px)
@@ -24,23 +25,30 @@ export const BeatBackgroundLines = memo(function BeatBackgroundLines({
   beatStrengths,
   pps,
   highlightTime,
+  renderTimeRange,
 }: {
   beatTimes: number[] | undefined;
   beatStrengths: number[] | undefined;
   pps: number;
   /** Snap guide time — drawn as a bright line even when it is not a beat. */
   highlightTime?: number | null;
+  renderTimeRange?: TimelineTimeRange;
 }) {
   const visibleBeatTimes = beatTimes && !beatsTooDense(beatTimes, pps) ? beatTimes : null;
   const highlightIsBeat =
     highlightTime != null &&
     visibleBeatTimes?.some((t) => Math.abs(t - highlightTime) < 1e-3) === true;
   if (!visibleBeatTimes && highlightTime == null) return null;
+  const beatEntries = getTimelineBeatEntries(
+    visibleBeatTimes ?? undefined,
+    beatStrengths,
+    renderTimeRange,
+  );
   return (
     <div className="absolute inset-0 pointer-events-none" style={{ zIndex: 0 }}>
-      {visibleBeatTimes?.map((t, i) => {
+      {beatEntries.map(({ time: t, index: i, strength: beatStrength }) => {
         const isHighlight = highlightTime != null && Math.abs(t - highlightTime) < 1e-3;
-        const strength = Math.pow(Math.min(1, beatStrengths?.[i] ?? 0.5), 2.2);
+        const strength = Math.pow(Math.min(1, beatStrength ?? 0.5), 2.2);
         const opacity = isHighlight ? 1 : 0.06 + strength * 0.16;
         return (
           <div
@@ -81,26 +89,34 @@ export const BeatStrip = memo(function BeatStrip({
   beatTimes,
   beatStrengths,
   pps,
+  renderTimeRange,
 }: {
   beatTimes: number[] | undefined;
   beatStrengths: number[] | undefined;
   pps: number;
+  renderTimeRange?: TimelineTimeRange;
 }) {
   // Active drag: which beat and how far (px) it's been dragged.
   const [drag, setDrag] = useState<{ index: number; dx: number } | null>(null);
   const dragRef = useRef<{ index: number; startX: number; origTime: number } | null>(null);
 
   if (!beatTimes || beatsTooDense(beatTimes, pps)) return null;
   const cy = BEAT_BAND_H / 2;
+  const beatEntries = getTimelineBeatEntries(
+    beatTimes,
+    beatStrengths,
+    renderTimeRange,
+    drag ? new Set([drag.index]) : undefined,
+  );
 
   return (
     <div
       className="absolute left-0 right-0 pointer-events-none"
       style={{ top: CLIP_Y, height: BEAT_BAND_H, background: "rgba(0,0,0,0.28)", zIndex: 11 }}
     >
-      {beatTimes.map((t, i) => {
+      {beatEntries.map(({ time: t, index: i, strength: beatStrength }) => {
         // Louder beats → larger, brighter dot. Gamma curve widens the contrast.
-        const strength = Math.pow(Math.min(1, beatStrengths?.[i] ?? 0.5), 2.2);
+        const strength = Math.pow(Math.min(1, beatStrength ?? 0.5), 2.2);
         const r = 1.5 + strength * 2.5;
         const opacity = 0.25 + strength * 0.75;
         const dxPx = drag?.index === i ? drag.dx : 0;