perf(studio): define timeline viewport budgets and fixtures

Author: miguel-heygen

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

@@ -0,0 +1,141 @@
+// @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);
+    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,11 @@ interface StudioTestHookDeps {
 
 interface StudioTestApi {
   selectByDomId: (id: string) => Promise<boolean>;
+  loadTimelinePerformanceFixture: (
+    spec: TimelinePerformanceFixtureSpec,
+  ) => TimelinePerformanceFixtureSummary;
+  readTimelinePerformanceDiagnostics: () => Readonly<TimelinePerformanceDiagnostics>;
+  timelineViewportBudgets: typeof TIMELINE_VIEWPORT_BUDGETS;
 }
 
 declare global {
@@ -52,6 +68,28 @@ 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;
+      },
+      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/lib/timelinePerformanceDiagnostics.test.ts

@@ -0,0 +1,100 @@
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  getTimelineResourceBudgetStatus,
+  readTimelinePerformanceDiagnostics,
+  resolveTimelineScrollStrategy,
+} from "./timelinePerformanceDiagnostics";
+import { resolveTimelineViewportBudgets } from "./timelineViewportBudgets";
+
+describe("timeline performance diagnostics", () => {
+  afterEach(() => {
+    document.body.replaceChildren();
+  });
+
+  it("reads mounted resources without mutating the timeline", () => {
+    document.body.innerHTML = `
+      <div aria-label="Timeline" data-timeline-scheduler-queued="3"
+           data-timeline-scheduler-active="2" data-timeline-cache-bytes="4096">
+        <div data-timeline-row><div data-clip="true"></div><div data-clip="true"></div></div>
+        <div data-timeline-row><div data-clip="true"></div></div>
+        <div data-clip="true"></div>
+        <div data-timeline-grid-cell></div><div data-timeline-grid-cell></div>
+        <div data-timeline-poster-state="ready"></div>
+        <div data-timeline-poster-state="error"></div>
+        <div data-timeline-poster-state="constructor"></div>
+      </div>`;
+    const before = document.body.innerHTML;
+
+    expect(readTimelinePerformanceDiagnostics()).toMatchObject({
+      timelineRoots: 1,
+      mountedRows: 2,
+      mountedClipRoots: 4,
+      maxMountedClipRootsInOneRow: 2,
+      mountedTimeGridCells: 2,
+      schedulerQueued: 3,
+      schedulerActive: 2,
+      cacheBytes: 4096,
+      posterStates: { idle: 0, loading: 0, ready: 1, fallback: 0, error: 1 },
+    });
+    expect(document.body.innerHTML).toBe(before);
+  });
+
+  it("returns the zero baseline after unmount or reset removes the DOM", () => {
+    document.body.innerHTML = '<div aria-label="Timeline"><div data-clip="true"></div></div>';
+    expect(readTimelinePerformanceDiagnostics().mountedClipRoots).toBe(1);
+
+    document.body.replaceChildren();
+
+    expect(readTimelinePerformanceDiagnostics()).toEqual({
+      timelineRoots: 0,
+      mountedRows: 0,
+      mountedClipRoots: 0,
+      maxMountedClipRootsInOneRow: 0,
+      mountedTimeGridCells: 0,
+      mountedTimelineDescendants: 0,
+      schedulerQueued: 0,
+      schedulerActive: 0,
+      cacheBytes: 0,
+      posterStates: { idle: 0, loading: 0, ready: 0, fallback: 0, error: 0 },
+    });
+  });
+
+  it("treats every DOM ceiling as inclusive", () => {
+    const budgets = resolveTimelineViewportBudgets({
+      maxMountedClipRoots: 2,
+      maxMountedClipRootsPerRow: 1,
+      maxMountedRows: 2,
+      maxMountedTimelineDescendants: 4,
+    });
+    expect(
+      getTimelineResourceBudgetStatus(
+        {
+          ...readTimelinePerformanceDiagnostics(),
+          mountedClipRoots: 2,
+          maxMountedClipRootsInOneRow: 2,
+          mountedTimelineDescendants: 4,
+        },
+        budgets,
+      ),
+    ).toEqual({
+      timelineRoot: false,
+      rows: true,
+      clipRoots: true,
+      clipRootsPerRow: false,
+      descendants: true,
+    });
+  });
+
+  it("fails the resource status when the timeline is absent", () => {
+    expect(getTimelineResourceBudgetStatus(readTimelinePerformanceDiagnostics())).toMatchObject({
+      timelineRoot: false,
+    });
+  });
+
+  it("selects direct scrolling only through the configured safety envelope", () => {
+    expect(resolveTimelineScrollStrategy(8_000_000)).toBe("direct");
+    expect(resolveTimelineScrollStrategy(8_000_001)).toBe("segmented");
+    expect(() => resolveTimelineScrollStrategy(Number.NaN)).toThrow("content width");
+  });
+});