@hyperframes/studio 0.7.86 → 0.7.88

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.7.86",
+  "version": "0.7.88",
   "description": "",
   "repository": {
     "type": "git",
@@ -41,16 +41,17 @@
     "@codemirror/theme-one-dark": "^6.1.2",
     "@codemirror/view": "6.40.0",
     "@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",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.7.86",
-    "@hyperframes/parsers": "0.7.86",
-    "@hyperframes/player": "0.7.86",
-    "@hyperframes/sdk": "0.7.86",
-    "@hyperframes/studio-server": "0.7.86"
+    "@hyperframes/core": "0.7.88",
+    "@hyperframes/parsers": "0.7.88",
+    "@hyperframes/player": "0.7.88",
+    "@hyperframes/sdk": "0.7.88",
+    "@hyperframes/studio-server": "0.7.88"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -65,7 +66,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.7.86"
+    "@hyperframes/producer": "0.7.88"
   },
   "peerDependencies": {
     "react": "19",
@@ -77,7 +78,9 @@
     "build": "vite build && tsup",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "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": "bun run test:timeline-virtualization"
   }
 }

package/src/components/TimelineToolbar.tsx

@@ -118,8 +118,13 @@ export function TimelineToolbar({ domEditSession, onSplitElement }: TimelineTool
   // the selection changes, not only on the next playhead tick.
   const selectedElementId = usePlayerStore((s) => s.selectedElementId);
   const elements = usePlayerStore((s) => s.elements);
+  const timelineFitPps = usePlayerStore((s) => s.timelineFitPps);
   const { zoomMode, manualZoomPercent, setZoomMode, setManualZoomPercent } = useTimelineZoom();
-  const displayedTimelineZoomPercent = getTimelineZoomPercent(zoomMode, manualZoomPercent);
+  const displayedTimelineZoomPercent = getTimelineZoomPercent(
+    zoomMode,
+    manualZoomPercent,
+    timelineFitPps,
+  );
   const {
     state: keyframeState,
     isMotionPath: keyframeIsMotionPath,
@@ -418,7 +423,7 @@ export function TimelineToolbar({ domEditSession, onSplitElement }: TimelineTool
               onClick={() => {
                 setZoomMode("manual");
                 setManualZoomPercent(
-                  getNextTimelineZoomPercent("out", zoomMode, manualZoomPercent),
+                  getNextTimelineZoomPercent("out", zoomMode, manualZoomPercent, timelineFitPps),
                 );
               }}
               className={flatIdle}
@@ -430,12 +435,14 @@ export function TimelineToolbar({ domEditSession, onSplitElement }: TimelineTool
             type="range"
             min="0"
             max="100"
-            value={timelineZoomPercentToSlider(displayedTimelineZoomPercent)}
+            value={timelineZoomPercentToSlider(displayedTimelineZoomPercent, timelineFitPps)}
             title={`${displayedTimelineZoomPercent}%`}
             aria-label="Timeline zoom"
             onChange={(e) => {
               setZoomMode("manual");
-              setManualZoomPercent(timelineSliderToZoomPercent(Number(e.target.value)));
+              setManualZoomPercent(
+                timelineSliderToZoomPercent(Number(e.target.value), timelineFitPps),
+              );
             }}
             // h-6 on the input is the 24x24 WCAG 2.2 (2.5.8) target: the visible
             // track stays 2px and the thumb 10px, only the pointer box grows.
@@ -447,7 +454,9 @@ export function TimelineToolbar({ domEditSession, onSplitElement }: TimelineTool
               aria-label="Zoom in"
               onClick={() => {
                 setZoomMode("manual");
-                setManualZoomPercent(getNextTimelineZoomPercent("in", zoomMode, manualZoomPercent));
+                setManualZoomPercent(
+                  getNextTimelineZoomPercent("in", zoomMode, manualZoomPercent, timelineFitPps),
+                );
               }}
               className={flatIdle}
             >

package/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,

package/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}

package/src/hooks/studioTestMode.test.ts

@@ -0,0 +1,35 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.resetModules();
+});
+
+describe("Studio test mode", () => {
+  it("exposes hooks in the normal development runtime", async () => {
+    const { STUDIO_RUNTIME_MODE, STUDIO_TEST_HOOKS_ENABLED } = await import("./studioTestMode");
+
+    expect(STUDIO_RUNTIME_MODE).toBe("development");
+    expect(STUDIO_TEST_HOOKS_ENABLED).toBe(true);
+  });
+
+  it("keeps hooks on the development server while it uses production React", async () => {
+    vi.stubEnv("DEV", false);
+    vi.stubEnv("MODE", "development");
+
+    const { STUDIO_RUNTIME_MODE, STUDIO_TEST_HOOKS_ENABLED } = await import("./studioTestMode");
+
+    expect(STUDIO_RUNTIME_MODE).toBe("production");
+    expect(STUDIO_TEST_HOOKS_ENABLED).toBe(true);
+  });
+
+  it("keeps test hooks out of an ordinary production build", async () => {
+    vi.stubEnv("DEV", false);
+    vi.stubEnv("MODE", "production");
+
+    const { STUDIO_RUNTIME_MODE, STUDIO_TEST_HOOKS_ENABLED } = await import("./studioTestMode");
+
+    expect(STUDIO_RUNTIME_MODE).toBe("production");
+    expect(STUDIO_TEST_HOOKS_ENABLED).toBe(false);
+  });
+});

package/src/hooks/studioTestMode.ts

@@ -0,0 +1,23 @@
+export type StudioRuntimeMode = "development" | "production";
+
+function readStudioImportMetaEnv(): ImportMetaEnv | undefined {
+  try {
+    return import.meta.env;
+  } catch {
+    return undefined;
+  }
+}
+
+const studioImportMetaEnv = readStudioImportMetaEnv();
+
+/**
+ * Test hooks belong to Vite's development server, even when that server uses
+ * production React for performance measurement. A production build has neither
+ * DEV nor the development server mode, so the API stays out of shipped assets.
+ */
+export const STUDIO_RUNTIME_MODE: StudioRuntimeMode = studioImportMetaEnv?.DEV
+  ? "development"
+  : "production";
+
+export const STUDIO_TEST_HOOKS_ENABLED =
+  studioImportMetaEnv?.DEV === true || studioImportMetaEnv?.MODE === "development";

package/src/hooks/useGestureRecording.test.tsx

@@ -0,0 +1,120 @@
+// @vitest-environment jsdom
+
+import React, { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { mountReactHarness } from "./domSelectionTestHarness";
+import { useGestureRecording, type GestureSample } from "./useGestureRecording";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  document.body.replaceChildren();
+});
+
+describe("useGestureRecording", () => {
+  it("keeps only the latest gesture sample in each output frame", () => {
+    const animationFrames: FrameRequestCallback[] = [];
+    vi.stubGlobal(
+      "requestAnimationFrame",
+      vi.fn((callback: FrameRequestCallback) => {
+        animationFrames.push(callback);
+        return animationFrames.length;
+      }),
+    );
+    vi.stubGlobal("cancelAnimationFrame", vi.fn());
+    let nowMs = 0;
+    vi.spyOn(performance, "now").mockImplementation(() => nowMs);
+
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    const element = iframe.contentDocument!.createElement("div");
+    element.id = "card";
+    iframe.contentDocument!.body.append(element);
+
+    let recording: ReturnType<typeof useGestureRecording> | null = null;
+    function Harness() {
+      recording = useGestureRecording();
+      return null;
+    }
+    const root = mountReactHarness(<Harness />);
+
+    act(() => recording?.startRecording(element, iframe));
+    document.dispatchEvent(new MouseEvent("pointermove", { bubbles: true, clientX: 10 }));
+    nowMs = 1;
+    act(() => animationFrames.shift()?.(1));
+    document.dispatchEvent(new MouseEvent("pointermove", { bubbles: true, clientX: 20 }));
+    nowMs = 10;
+    act(() => animationFrames.shift()?.(10));
+    document.dispatchEvent(new MouseEvent("pointermove", { bubbles: true, clientX: 40 }));
+    nowMs = 20;
+    act(() => animationFrames.shift()?.(20));
+    document.dispatchEvent(new MouseEvent("pointermove", { bubbles: true, clientX: 50 }));
+    nowMs = 30;
+    act(() => animationFrames.shift()?.(30));
+
+    let samples: GestureSample[] = [];
+    act(() => {
+      samples = recording?.stopRecording() ?? [];
+    });
+
+    expect(samples).toEqual([
+      { time: 0, properties: { x: 10, y: 0 } },
+      { time: 1 / 30, properties: { x: 40, y: 0 } },
+    ]);
+    act(() => root.unmount());
+  });
+
+  it("releases the preview runtime when unmounted during a recording", () => {
+    const cancelAnimationFrame = vi.fn();
+    vi.stubGlobal(
+      "requestAnimationFrame",
+      vi.fn(() => 17),
+    );
+    vi.stubGlobal("cancelAnimationFrame", cancelAnimationFrame);
+
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    const previewDocument = iframe.contentDocument!;
+    const element = previewDocument.createElement("div");
+    element.id = "card";
+    element.style.visibility = "hidden";
+    element.style.setProperty("translate", "10px 20px");
+    element.style.setProperty("--hf-studio-offset-x", "12px");
+    element.style.setProperty("--hf-studio-offset-y", "-8px");
+    previewDocument.body.append(element);
+
+    const set = vi.fn();
+    const seek = vi.fn();
+    Reflect.set(iframe.contentWindow!, "gsap", {
+      getProperty: vi.fn(() => 0),
+      set,
+    });
+    Reflect.set(iframe.contentWindow!, "__timelines", {
+      main: { duration: () => 5, seek },
+    });
+    Reflect.set(iframe.contentWindow!, "__player", { getTime: () => 1 });
+
+    let recording: ReturnType<typeof useGestureRecording> | null = null;
+    function Harness() {
+      recording = useGestureRecording();
+      return null;
+    }
+    const root = mountReactHarness(<Harness />);
+
+    act(() => recording?.startRecording(element, iframe, 4));
+    expect(element.style.getPropertyValue("--hf-studio-offset-x")).toBe("0px");
+    expect(element.style.getPropertyValue("--hf-studio-offset-y")).toBe("0px");
+
+    act(() => root.unmount());
+
+    expect(cancelAnimationFrame).toHaveBeenCalledWith(17);
+    expect(set).toHaveBeenCalledWith("#card", {
+      clearProps: "x,y,scale,scaleX,scaleY,rotation,rotationX,rotationY,opacity,z",
+    });
+    expect(element.style.visibility).toBe("hidden");
+    expect(element.style.getPropertyValue("translate")).toBe("10px 20px");
+    expect(element.style.getPropertyValue("--hf-studio-offset-x")).toBe("12px");
+    expect(element.style.getPropertyValue("--hf-studio-offset-y")).toBe("-8px");
+  });
+});

package/src/hooks/useGestureRecording.ts

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { usePlayerStore, liveTime } from "../player/store/playerStore";
+import { frameToSeconds, secondsToFrame } from "../player/lib/time";
 
 export interface GestureSample {
   time: number;
@@ -28,8 +29,8 @@ interface BasePosition {
 }
 
 interface GsapRuntime {
-  seek: (t: number) => void;
-  set: (target: string, vars: Record<string, number | string>) => void;
+  timeline: { seek: (t: number) => void };
+  gsap: { set: (target: string, vars: Record<string, number | string>) => void };
   selector: string;
   element: HTMLElement;
   startTime: number;
@@ -100,8 +101,8 @@ function connectGsapRuntime(
     if (win?.gsap?.set && tl?.seek && selector) {
       const tlDuration = tl.duration();
       return {
-        seek: tl.seek.bind(tl),
-        set: win.gsap.set.bind(win.gsap),
+        timeline: tl,
+        gsap: win.gsap,
         selector,
         element,
         startTime: win.__player?.getTime() ?? 0,
@@ -123,9 +124,9 @@ function applyRuntimePreview(
   properties: Record<string, number>,
 ): void {
   const seekTime = Math.min(runtime.startTime + time, runtime.maxSeekTime);
-  runtime.seek(seekTime);
+  runtime.timeline.seek(seekTime);
   runtime.element.style.setProperty("translate", "none");
-  runtime.set(runtime.selector, { ...properties });
+  runtime.gsap.set(runtime.selector, { ...properties });
   runtime.element.style.visibility = "visible";
   liveTime.notify(seekTime);
   usePlayerStore.getState().setCurrentTime(seekTime);
@@ -139,7 +140,18 @@ function recordSample(r: RecordingRefs, time: number, properties: Record<string,
   // stripStudioEditsFromTarget in studio-api), so the keyframes must already
   // include it. Subtracting it made the committed gesture play shoved off by the
   // offset (the offset was removed twice).
-  r.samples.push({ time, properties: { ...properties } });
+  const frame = secondsToFrame(time);
+  const sample = { time: frameToSeconds(frame), properties: { ...properties } };
+  const lastIndex = r.samples.length - 1;
+  const lastSample = r.samples[lastIndex];
+  // Gesture events follow the display refresh rate (often 60/120Hz), but the
+  // Studio preview is authored at 30fps. Keep the latest pointer state for each
+  // output frame so recording cannot create visually indistinguishable piles.
+  if (lastSample?.time === sample.time) {
+    r.samples[lastIndex] = sample;
+  } else {
+    r.samples.push(sample);
+  }
   r.trail.push({ x: r.pointer.x, y: r.pointer.y });
 }
 
@@ -237,6 +249,26 @@ function createRecordingRefs(): RecordingRefs {
   };
 }
 
+function releaseRuntimePreview(r: RecordingRefs): void {
+  const runtime = r.runtime;
+  if (!runtime) return;
+  const { element, savedVisibility, savedTranslate } = runtime;
+  element.style.visibility = savedVisibility;
+  element.style.setProperty("translate", savedTranslate || "");
+  try {
+    runtime.gsap.set(runtime.selector, {
+      clearProps: "x,y,scale,scaleX,scaleY,rotation,rotationX,rotationY,opacity,z",
+    });
+  } catch {
+    /* runtime gone */
+  }
+  if (r.cssVarOffset.x || r.cssVarOffset.y) {
+    element.style.setProperty("--hf-studio-offset-x", `${r.cssVarOffset.x}px`);
+    element.style.setProperty("--hf-studio-offset-y", `${r.cssVarOffset.y}px`);
+  }
+  r.runtime = null;
+}
+
 // ---------------------------------------------------------------------------
 // Hook
 // ---------------------------------------------------------------------------
@@ -259,9 +291,10 @@ export function useGestureRecording() {
   useEffect(() => {
     const r = refs.current;
     return () => {
+      isRecordingRef.current = false;
+      releaseRuntimePreview(r);
       r.cleanup?.();
       r.cleanup = null;
-      isRecordingRef.current = false;
     };
   }, []);
 
@@ -290,15 +323,15 @@ export function useGestureRecording() {
       // this scale to convert them to the iframe's composition pixels.
       r.scale = computeIframeScale(iframeEl);
 
-      // Now clear the optimistic path offset (already folded into baseX/baseY).
-      if (base.cssOffX || base.cssOffY) {
-        element.style.setProperty("--hf-studio-offset-x", "0px");
-        element.style.setProperty("--hf-studio-offset-y", "0px");
-      }
-
       // --- Phase 3: Connect to the iframe GSAP runtime ---
       const selector = element.id ? `#${element.id}` : null;
       r.runtime = connectGsapRuntime(element, iframeEl, selector, elementEndTime);
+      // Clear the optimistic path offset only while a live runtime owns the
+      // preview. releaseRuntimePreview restores it on every exit path.
+      if (r.runtime && (base.cssOffX || base.cssOffY)) {
+        element.style.setProperty("--hf-studio-offset-x", "0px");
+        element.style.setProperty("--hf-studio-offset-y", "0px");
+      }
 
       // --- Phase 5: Attach event listeners ---
       const handlePointerMove = (e: PointerEvent) => {
@@ -378,7 +411,7 @@ export function useGestureRecording() {
           } catch {
             // Preview failed — disable it for the rest of the gesture (recording
             // continues). `r.runtime` is nulled so we don't retry on every frame.
-            r.runtime = null;
+            releaseRuntimePreview(r);
           }
         }
 
@@ -407,31 +440,7 @@ export function useGestureRecording() {
     if (!isRecordingRef.current) return [];
     isRecordingRef.current = false;
     const r = refs.current;
-    if (r.runtime) {
-      const { element: el, savedVisibility, savedTranslate } = r.runtime;
-      el.style.visibility = savedVisibility;
-      el.style.setProperty("translate", savedTranslate || "");
-      // Drop the gesture's inline gsap transform before re-applying the path
-      // offset below, so the two don't briefly stack (the recorded keyframes
-      // already encode the full position, offset included). On commit the
-      // re-seek lands on the gesture's first keyframe; on cancel this leaves the
-      // element at its pre-recording position.
-      try {
-        r.runtime.set(r.runtime.selector, {
-          clearProps: "x,y,scale,scaleX,scaleY,rotation,rotationX,rotationY,opacity,z",
-        });
-      } catch {
-        /* runtime gone */
-      }
-    }
-    if (r.cssVarOffset.x || r.cssVarOffset.y) {
-      const el = r.runtime?.element;
-      if (el) {
-        el.style.setProperty("--hf-studio-offset-x", `${r.cssVarOffset.x}px`);
-        el.style.setProperty("--hf-studio-offset-y", `${r.cssVarOffset.y}px`);
-      }
-    }
-    r.runtime = null;
+    releaseRuntimePreview(r);
     r.cleanup?.();
     r.cleanup = null;
     const frozen = r.samples.slice();

package/src/hooks/useStudioTestHooks.test.tsx

@@ -0,0 +1,161 @@
+// @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");
+    expect(api.runtimeMode).toBe("development");
+    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();
+    // 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", () => {
+    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());
+  });
+});