@hyperframes/studio 0.7.86 → 0.7.88

package/src/hooks/useStudioTestHooks.ts

@@ -1,5 +1,18 @@
 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";
+import { STUDIO_RUNTIME_MODE, STUDIO_TEST_HOOKS_ENABLED } from "./studioTestMode";
 
 interface StudioTestHookDeps {
   previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
@@ -11,7 +24,14 @@ interface StudioTestHookDeps {
 }
 
 interface StudioTestApi {
+  runtimeMode: typeof STUDIO_RUNTIME_MODE;
   selectByDomId: (id: string) => Promise<boolean>;
+  loadTimelinePerformanceFixture: (
+    spec: TimelinePerformanceFixtureSpec,
+  ) => TimelinePerformanceFixtureSummary;
+  resetTimelinePerformanceFixture: () => void;
+  readTimelinePerformanceDiagnostics: () => Readonly<TimelinePerformanceDiagnostics>;
+  timelineViewportBudgets: typeof TIMELINE_VIEWPORT_BUDGETS;
 }
 
 declare global {
@@ -36,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;
@@ -52,9 +67,41 @@ 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 () => {
+      // The lease is deliberately NOT released here. Loading a fixture writes
+      // player state, which changes this effect's dependency identities and
+      // tears the effect down on the very next frame. Releasing on teardown
+      // therefore revoked the lease moments after it was taken, and live iframe
+      // discovery overwrote the fixture the loader had just installed. The
+      // lease belongs to the fixture, and a page reload clears it.
       // delete, not `= undefined`: an own key holding undefined keeps
       // `"__studioTest" in window` true, which defeats feature detection.
       delete window.__studioTest;

package/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,10 +89,12 @@ 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);
@@ -92,15 +102,21 @@ export const BeatStrip = memo(function BeatStrip({
 
   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;

package/src/player/components/CompositionThumbnail.test.ts

@@ -1,5 +1,54 @@
-import { describe, expect, it } from "vitest";
-import { buildCompositionThumbnailUrl } from "./CompositionThumbnail";
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { buildCompositionThumbnailUrl, CompositionThumbnail } from "./CompositionThumbnail";
+
+Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", {
+  configurable: true,
+  value: true,
+});
+
+class MockResizeObserver {
+  observe() {}
+  disconnect() {}
+  unobserve() {}
+}
+
+class MockImage {
+  static instances: MockImage[] = [];
+  onload: (() => void) | null = null;
+  onerror: (() => void) | null = null;
+  naturalWidth = 0;
+  naturalHeight = 0;
+  src = "";
+
+  constructor() {
+    MockImage.instances.push(this);
+  }
+}
+
+const originalResizeObserver = globalThis.ResizeObserver;
+const originalImage = globalThis.Image;
+let host: HTMLDivElement;
+let root: Root | null = null;
+
+beforeEach(() => {
+  globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+  globalThis.Image = MockImage as unknown as typeof Image;
+  MockImage.instances = [];
+  host = document.createElement("div");
+  document.body.append(host);
+});
+
+afterEach(() => {
+  act(() => root?.unmount());
+  root = null;
+  globalThis.ResizeObserver = originalResizeObserver;
+  globalThis.Image = originalImage;
+  document.body.replaceChildren();
+});
 
 describe("buildCompositionThumbnailUrl", () => {
   it("includes selector and occurrence index for precise element thumbnails", () => {
@@ -17,3 +66,48 @@ describe("buildCompositionThumbnailUrl", () => {
     );
   });
 });
+
+describe("CompositionThumbnail", () => {
+  function renderThumbnail(): MockImage {
+    root = createRoot(host);
+    act(() => {
+      root!.render(
+        React.createElement(CompositionThumbnail, {
+          previewUrl: "/api/projects/demo/preview",
+          label: "",
+          labelColor: "#fff",
+        }),
+      );
+    });
+    const probe = MockImage.instances[0];
+    if (!probe) throw new Error("Expected an image probe");
+    return probe;
+  }
+
+  it("renders visible tiles after the off-DOM probe loads", () => {
+    const probe = renderThumbnail();
+
+    act(() => {
+      probe.naturalWidth = 1920;
+      probe.naturalHeight = 1080;
+      probe.onload?.();
+    });
+
+    const tiles = [...host.querySelectorAll("img")];
+    expect(tiles.length).toBeGreaterThan(0);
+    expect(tiles.every((tile) => !tile.classList.contains("hidden"))).toBe(true);
+  });
+
+  it("aborts its off-DOM image probe when unmounted", () => {
+    const probe = renderThumbnail();
+    expect(host.querySelector("img")).toBeNull();
+    expect(probe.src).toContain("/api/projects/demo/thumbnail/index.html");
+
+    act(() => root?.unmount());
+    root = null;
+
+    expect(probe.onload).toBeNull();
+    expect(probe.onerror).toBeNull();
+    expect(probe.src).toBe("");
+  });
+});

package/src/player/components/CompositionThumbnail.tsx

@@ -1,4 +1,4 @@
-import { memo, useCallback, useState, useRef } from "react";
+import { memo, useCallback, useEffect, useState, useRef } from "react";
 import { useMountEffect } from "../../hooks/useMountEffect";
 
 interface CompositionThumbnailProps {
@@ -88,26 +88,39 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
     selectorIndex,
     origin: window.location.origin,
   });
+
+  // Probe outside React's DOM and explicitly abort on URL changes/unmount. A
+  // hidden React <img> keeps its Fiber reachable from Blink's pending-activity
+  // queue while a request is unresolved.
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    let cancelled = false;
+    setLoaded(false);
+    const probe = new Image();
+    probe.onload = () => {
+      if (cancelled) return;
+      if (probe.naturalWidth > 0 && probe.naturalHeight > 0) {
+        setAspect(probe.naturalWidth / probe.naturalHeight);
+      }
+      setLoaded(true);
+    };
+    probe.onerror = () => {
+      if (!cancelled) setLoaded(false);
+    };
+    probe.src = url;
+    return () => {
+      cancelled = true;
+      probe.onload = null;
+      probe.onerror = null;
+      probe.src = "";
+    };
+  }, [url]);
+
   const frameW = Math.max(48, Math.round(CLIP_HEIGHT * aspect));
   const frameCount = containerWidth > 0 ? Math.max(1, Math.ceil(containerWidth / frameW)) : 1;
 
   return (
     <div ref={setContainerRef} className="absolute inset-0 overflow-hidden">
-      <img
-        src={url}
-        alt=""
-        draggable={false}
-        loading="eager"
-        onLoad={(e) => {
-          const img = e.currentTarget;
-          if (img.naturalWidth > 0 && img.naturalHeight > 0) {
-            setAspect(img.naturalWidth / img.naturalHeight);
-          }
-          setLoaded(true);
-        }}
-        className="hidden"
-      />
-
       {loaded && (
         <div
           className="absolute inset-0 flex"

package/src/player/components/Timeline.test.ts

@@ -12,11 +12,14 @@ import {
   getTimelineCanvasHeight,
   resolveTimelineAssetDrop,
   getTimelinePlayheadLeft,
+  getTimelinePlaybackFollowScrollLeft,
   getTimelineScrollLeftForZoomAnchor,
   getTimelineScrollLeftForZoomTransition,
   shouldShowTimelineShortcutHint,
   shouldHandleTimelineDeleteKey,
   shouldAutoScrollTimeline,
+  getTimelineVisibleTimeRange,
+  getTimelineScrollTopForGeometryChange,
 } from "./Timeline";
 import {
   CLIP_Y,
@@ -32,11 +35,16 @@ import {
   getTimelineDisplayContentWidth,
   getTimelineFitPps,
   getTimelineLaneTop,
+  createTimelineRowGeometry,
 } from "./timelineLayout";
 import { formatTime } from "../lib/time";
 import { usePlayerStore } from "../store/playerStore";
 import { TimelineEditProvider } from "../../contexts/TimelineEditContext";
 
+vi.mock("./timelineRowVirtualizationFlag", () => ({
+  STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED: false,
+}));
+
 globalThis.IS_REACT_ACT_ENVIRONMENT = true;
 
 afterEach(() => {
@@ -44,6 +52,25 @@ afterEach(() => {
   usePlayerStore.getState().reset();
 });
 
+describe("timeline viewport geometry", () => {
+  it("derives a clamped visible time range from the raw viewport", () => {
+    expect(
+      getTimelineVisibleTimeRange({ scrollLeft: 300, clientWidth: 500 }, 100, 200, 20),
+    ).toEqual({ start: 1, end: 6 });
+    expect(getTimelineVisibleTimeRange({ scrollLeft: 0, clientWidth: 100 }, 100, 200, 20)).toEqual({
+      start: 0,
+      end: 0,
+    });
+  });
+
+  it("keeps the same row anchored when a row above it expands", () => {
+    const previous = createTimelineRowGeometry([1, 2, 3], [48, 48, 48]);
+    const next = createTimelineRowGeometry([1, 2, 3], [104, 48, 48]);
+    const scrollTop = previous.getRowTop(2) - RULER_H + 6;
+    expect(getTimelineScrollTopForGeometryChange(previous, next, scrollTop)).toBe(scrollTop + 56);
+  });
+});
+
 function getHorizontalGeometry(host: HTMLElement, clipId: string, tickLabel: string) {
   const clip = host.querySelector<HTMLElement>(`[data-el-id="${clipId}"]`);
   if (!clip) throw new Error(`Missing timeline clip ${clipId}`);
@@ -252,6 +279,33 @@ describe("Timeline provider boundary", () => {
     act(() => root.unmount());
   });
 
+  it("renders the complete track list while row virtualization is gated off", () => {
+    const host = createSizedTimelineHost(640);
+    usePlayerStore.setState({
+      duration: 4,
+      timelineReady: true,
+      elements: Array.from({ length: 12 }, (_, track) => ({
+        id: `clip-${track}`,
+        tag: "div",
+        start: 0,
+        duration: 2,
+        track,
+      })),
+    });
+    const root = createRoot(host);
+    act(() => root.render(React.createElement(Timeline)));
+
+    const list = host.querySelector<HTMLElement>('[role="list"]');
+    const rows = list?.querySelectorAll('[role="listitem"]') ?? [];
+    expect(rows).toHaveLength(12);
+    expect(rows[0]?.getAttribute("aria-posinset")).toBe("1");
+    expect(rows[0]?.getAttribute("aria-setsize")).toBe("12");
+    expect(rows[11]?.getAttribute("aria-posinset")).toBe("12");
+
+    act(() => root.unmount());
+  });
+
+  // fallow-ignore-next-line code-duplication
   it("renders the gutter without legacy icons or hue dots", () => {
     const { host, root } = renderBasicTimeline();
 
@@ -954,6 +1008,56 @@ describe("getTimelinePlayheadLeft", () => {
   });
 });
 
+describe("getTimelinePlaybackFollowScrollLeft", () => {
+  it("holds the viewport still while the playhead remains inside the comfort area", () => {
+    expect(
+      getTimelinePlaybackFollowScrollLeft({
+        playheadX: 700,
+        currentScrollLeft: 100,
+        viewportWidth: 1000,
+        contentOrigin: 264,
+        maxScrollLeft: 2000,
+      }),
+    ).toBe(100);
+  });
+
+  it("follows forward playback at the right-side comfort line", () => {
+    expect(
+      getTimelinePlaybackFollowScrollLeft({
+        playheadX: 1200,
+        currentScrollLeft: 100,
+        viewportWidth: 1000,
+        contentOrigin: 264,
+        maxScrollLeft: 2000,
+      }),
+    ).toBe(384);
+  });
+
+  it("returns to the matching earlier viewport after a playback loop", () => {
+    expect(
+      getTimelinePlaybackFollowScrollLeft({
+        playheadX: 264,
+        currentScrollLeft: 900,
+        viewportWidth: 1000,
+        contentOrigin: 264,
+        maxScrollLeft: 2000,
+      }),
+    ).toBe(0);
+  });
+
+  it("clamps at the end of the scrollable timeline", () => {
+    expect(
+      getTimelinePlaybackFollowScrollLeft({
+        playheadX: 5000,
+        currentScrollLeft: 100,
+        viewportWidth: 1000,
+        contentOrigin: 264,
+        maxScrollLeft: 1500,
+      }),
+    ).toBe(1500);
+  });
+});
+
 describe("getTimelineCanvasHeight", () => {
   it("includes bottom scroll buffer below the last track", () => {
     expect(getTimelineCanvasHeight([TRACK_H, TRACK_H, TRACK_H])).toBeGreaterThan(