fix(ci): measure timeline performance in production React

Author: miguel-heygen

.github/workflows/ci.yml

@@ -553,8 +553,11 @@ jobs:
           trap stop_server EXIT
 
           # Run one server at a time so the measured browser never competes with
-          # a second Vite module graph on the shared runner.
-          bun run --cwd packages/studio dev -- --port 5313 --strictPort &
+          # a second Vite module graph on the shared runner. The development
+          # server supplies the fixture API; production React matches shipped
+          # rendering behavior, and the gate asserts that runtime before timing.
+          NODE_ENV=production \
+            bun run --cwd packages/studio dev -- --port 5313 --strictPort &
           SERVER_PID=$!
           DEFAULT_STATUS=0
           if wait_for_server 5313; then
@@ -570,7 +573,8 @@ jobs:
           fi
           stop_server
 
-          VITE_STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED=0 \
+          NODE_ENV=production \
+            VITE_STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED=0 \
             bun run --cwd packages/studio dev -- --port 5314 --strictPort &
           SERVER_PID=$!
           DISABLED_STATUS=0

packages/studio/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);
+  });
+});

packages/studio/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";

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

@@ -85,6 +85,7 @@ describe("timeline performance fixture", () => {
     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,

packages/studio/src/hooks/useStudioTestHooks.ts

@@ -12,6 +12,7 @@ import {
   type TimelinePerformanceFixtureSummary,
 } from "../player/lib/timelinePerformanceFixture";
 import { TIMELINE_VIEWPORT_BUDGETS } from "../player/lib/timelineViewportBudgets";
+import { STUDIO_RUNTIME_MODE, STUDIO_TEST_HOOKS_ENABLED } from "./studioTestMode";
 
 interface StudioTestHookDeps {
   previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
@@ -23,6 +24,7 @@ interface StudioTestHookDeps {
 }
 
 interface StudioTestApi {
+  runtimeMode: typeof STUDIO_RUNTIME_MODE;
   selectByDomId: (id: string) => Promise<boolean>;
   loadTimelinePerformanceFixture: (
     spec: TimelinePerformanceFixtureSpec,
@@ -54,14 +56,9 @@ export function useStudioTestHooks({
 }: StudioTestHookDeps): void {
   // eslint-disable-next-line no-restricted-syntax
   useEffect(() => {
-    let isDev = false;
-    try {
-      isDev = import.meta.env.DEV === true;
-    } catch {
-      isDev = false;
-    }
-    if (!isDev || typeof window === "undefined") return;
+    if (!STUDIO_TEST_HOOKS_ENABLED || typeof window === "undefined") return;
     const api: StudioTestApi = {
+      runtimeMode: STUDIO_RUNTIME_MODE,
       selectByDomId: async (id: string): Promise<boolean> => {
         const element = previewIframeRef.current?.contentDocument?.getElementById(id) ?? null;
         if (!element) return false;

packages/studio/tests/e2e/timeline-virtualization.mjs

@@ -13,6 +13,8 @@
  * shared runner: no emulation, but the constrained budgets, because a hosted
  * runner is already slower and noisier than the machine the strict numbers were
  * recorded on. Throttling it further would measure the throttle, not the build.
+ * CI also requires production React and reports the observed runtime so Vite's
+ * development-only checks can never contaminate the shipped-code measurement.
  *
  * TIMELINE_ROW_VIRTUALIZATION selects which build is under test and defaults to
  * "on", the product default. The script asserts the configuration it observes
@@ -284,6 +286,14 @@ try {
   );
   await waitForStudioTestHookSettle(page);
 
+  const runtimeMode = await page.evaluate(() => window.__studioTest.runtimeMode);
+  if (TIER === "ci" && runtimeMode !== "production") {
+    throw new Error(
+      `Timeline CI must measure the production React runtime, received ${runtimeMode}. ` +
+        "Start the Studio development server with NODE_ENV=production.",
+    );
+  }
+
   await loadFixtureAndWait(page, 1_000, PROFILE);
   await client.send("HeapProfiler.collectGarbage");
   const baselineHeapBytes = await collectHeapBytes(client);
@@ -374,6 +384,7 @@ try {
       deviceScaleFactor: TIER === "high-dpr" ? 2 : 1,
       cpuThrottleRate: TIER === "low-resource" ? 4 : 1,
       tier: TIER,
+      runtimeMode,
       longTaskObserverProbe,
       rowVirtualization: ROW_VIRTUALIZATION,
       observedClipRootsAtLoad: observedClipRoots,