@hyperframes/studio 0.7.86 → 0.7.87

package/src/player/components/useTimelineVirtualRows.test.tsx

@@ -0,0 +1,174 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { createTimelineRowGeometry, RULER_H, TRACKS_TOP_PAD } from "./timelineLayout";
+import { extractTimelineVirtualRowRange, useTimelineVirtualRows } from "./useTimelineVirtualRows";
+import type { TimelineScrollViewportSnapshot } from "./useTimelineScrollViewport";
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+class MockResizeObserver {
+  constructor(private readonly callback: ResizeObserverCallback) {}
+  observe(target: Element) {
+    const { width, height } = target.getBoundingClientRect();
+    this.callback(
+      [
+        {
+          target,
+          borderBoxSize: [{ inlineSize: width, blockSize: height }],
+        } as unknown as ResizeObserverEntry,
+      ],
+      this as unknown as ResizeObserver,
+    );
+  }
+  unobserve() {}
+  disconnect() {}
+}
+
+const originalResizeObserver = globalThis.ResizeObserver;
+
+beforeAll(() => {
+  globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+});
+
+afterAll(() => {
+  globalThis.ResizeObserver = originalResizeObserver;
+});
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+function createScrollElement(scrollTop: number, width = 800, height = 192): HTMLDivElement {
+  const element = document.createElement("div");
+  document.body.append(element);
+  Object.defineProperties(element, {
+    scrollTop: { configurable: true, writable: true, value: scrollTop },
+    scrollLeft: { configurable: true, writable: true, value: 0 },
+    clientWidth: { configurable: true, value: width },
+    clientHeight: { configurable: true, value: height },
+    scrollWidth: { configurable: true, value: width },
+    scrollHeight: { configurable: true, value: 60_000 },
+  });
+  element.getBoundingClientRect = () =>
+    ({ width, height, top: 0, left: 0, right: width, bottom: height, x: 0, y: 0 }) as DOMRect;
+  return element;
+}
+
+function viewport(element: HTMLDivElement): TimelineScrollViewportSnapshot {
+  return {
+    scrollLeft: element.scrollLeft,
+    scrollTop: element.scrollTop,
+    clientWidth: element.clientWidth,
+    clientHeight: element.clientHeight,
+    scrollWidth: element.scrollWidth,
+    scrollHeight: element.scrollHeight,
+    isScrolling: false,
+  };
+}
+
+function createLargeGeometry(keyOffset = 0) {
+  const keys = Array.from({ length: 1_000 }, (_, index) => index + keyOffset);
+  return createTimelineRowGeometry(
+    keys,
+    keys.map(() => 48),
+  );
+}
+
+describe("extractTimelineVirtualRowRange", () => {
+  it("unions visible overscan with unique actor pins", () => {
+    expect(
+      extractTimelineVirtualRowRange(
+        { startIndex: 10, endIndex: 12, overscan: 2, count: 100 },
+        [0, 11, 99, 99, -1, 100],
+      ),
+    ).toEqual([0, 8, 9, 10, 11, 12, 13, 14, 99]);
+  });
+});
+
+describe("useTimelineVirtualRows", () => {
+  it("mounts a bounded vertical range plus the focused row", () => {
+    const geometry = createLargeGeometry(0.5);
+    const scroll = createScrollElement(RULER_H + TRACKS_TOP_PAD + 500 * 48);
+    const scrollRef = { current: scroll };
+    let rows: ReturnType<typeof useTimelineVirtualRows> = [];
+
+    function Probe() {
+      rows = useTimelineVirtualRows({
+        enabled: true,
+        scrollRef,
+        viewport: viewport(scroll),
+        rowGeometry: geometry,
+        sessionEpoch: 1,
+        pinnedRowKeys: [],
+        focusedRowKey: 900.5,
+      });
+      return null;
+    }
+
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(React.createElement(Probe)));
+    act(() => {});
+
+    expect(rows.length).toBeGreaterThan(0);
+    expect(rows.length).toBeLessThanOrEqual(16);
+    expect(rows.some((row) => row.index === 500)).toBe(true);
+    expect(rows.some((row) => row.rowKey === 900.5)).toBe(true);
+    act(() => root.unmount());
+  });
+
+  it("keeps compatibility rendering complete while the gate is disabled", () => {
+    const geometry = createTimelineRowGeometry([10, 5.5, 20], [48, 76, 48]);
+    const scroll = createScrollElement(0);
+    let rows: ReturnType<typeof useTimelineVirtualRows> = [];
+
+    function Probe() {
+      rows = useTimelineVirtualRows({
+        enabled: false,
+        scrollRef: { current: scroll },
+        viewport: viewport(scroll),
+        rowGeometry: geometry,
+        sessionEpoch: 1,
+        pinnedRowKeys: [],
+      });
+      return null;
+    }
+
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(React.createElement(Probe)));
+    expect(rows.map((row) => row.rowKey)).toEqual([10, 5.5, 20]);
+    act(() => root.unmount());
+  });
+
+  it("observes Timeline's authoritative scroll reset when the session epoch changes", () => {
+    const geometry = createLargeGeometry();
+    const scroll = createScrollElement(RULER_H + TRACKS_TOP_PAD + 500 * 48);
+    const scrollRef = { current: scroll };
+    let rows: ReturnType<typeof useTimelineVirtualRows> = [];
+
+    function Probe({ sessionEpoch }: { sessionEpoch: number }) {
+      rows = useTimelineVirtualRows({
+        enabled: true,
+        scrollRef,
+        viewport: viewport(scroll),
+        rowGeometry: geometry,
+        sessionEpoch,
+        pinnedRowKeys: [],
+      });
+      return null;
+    }
+
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(React.createElement(Probe, { sessionEpoch: 1 })));
+    expect(rows.some((row) => row.index === 500)).toBe(true);
+
+    scroll.scrollTop = 0;
+    act(() => root.render(React.createElement(Probe, { sessionEpoch: 2 })));
+    expect(rows.some((row) => row.index === 0)).toBe(true);
+    expect(rows.some((row) => row.index === 500)).toBe(false);
+
+    act(() => root.unmount());
+  });
+});

package/src/player/components/useTimelineVirtualRows.ts

@@ -0,0 +1,126 @@
+import { useCallback, useEffect, useMemo, type RefObject } from "react";
+import { defaultRangeExtractor, useVirtualizer, type Range } from "@tanstack/react-virtual";
+import { TIMELINE_VIEWPORT_BUDGETS } from "../lib/timelineViewportBudgets";
+import type { TimelineScrollViewportSnapshot } from "./useTimelineScrollViewport";
+import { RULER_H, TRACKS_TOP_PAD, type TimelineRowGeometry } from "./timelineLayout";
+
+export interface TimelineVirtualRow {
+  readonly index: number;
+  readonly rowKey: number;
+}
+
+export function extractTimelineVirtualRowRange(
+  range: Range,
+  pinnedRowIndexes: readonly number[],
+): number[] {
+  const indexes = new Set(defaultRangeExtractor(range));
+  for (const index of pinnedRowIndexes) {
+    if (index >= 0 && index < range.count) indexes.add(index);
+  }
+  return [...indexes].sort((left, right) => left - right);
+}
+
+function extractTimelineVirtualRowSeed(
+  count: number,
+  pinnedRowIndexes: readonly number[],
+): number[] {
+  const seedCount = Math.min(count, TIMELINE_VIEWPORT_BUDGETS.rowOverscanPerSide * 2 + 1);
+  const indexes = new Set(Array.from({ length: seedCount }, (_, index) => index));
+  for (const index of pinnedRowIndexes) {
+    if (index >= 0 && index < count) indexes.add(index);
+  }
+  return [...indexes].sort((left, right) => left - right);
+}
+
+interface UseTimelineVirtualRowsInput {
+  enabled: boolean;
+  scrollRef: RefObject<HTMLDivElement | null>;
+  viewport: TimelineScrollViewportSnapshot;
+  rowGeometry: TimelineRowGeometry;
+  sessionEpoch: number;
+  pinnedRowKeys: readonly number[];
+  focusedRowKey?: number;
+}
+
+export function useTimelineVirtualRows({
+  enabled,
+  scrollRef,
+  viewport,
+  rowGeometry,
+  sessionEpoch,
+  pinnedRowKeys,
+  focusedRowKey,
+}: UseTimelineVirtualRowsInput): readonly TimelineVirtualRow[] {
+  const viewportReady = viewport.clientWidth > 0 && viewport.clientHeight > 0;
+  const pinnedRowIndexes = useMemo(
+    () => [
+      ...new Set(
+        [...pinnedRowKeys, ...(focusedRowKey === undefined ? [] : [focusedRowKey])].map((key) =>
+          rowGeometry.getRowIndex(key),
+        ),
+      ),
+    ],
+    [focusedRowKey, pinnedRowKeys, rowGeometry],
+  );
+  const estimateSize = useCallback(
+    (index: number) => rowGeometry.getRowHeight(index),
+    [rowGeometry],
+  );
+  const getItemKey = useCallback(
+    (index: number) => rowGeometry.rowKeys[index] ?? index,
+    [rowGeometry],
+  );
+  const rangeExtractor = useCallback(
+    (range: Range) => extractTimelineVirtualRowRange(range, pinnedRowIndexes),
+    [pinnedRowIndexes],
+  );
+  const initialOffset = useCallback(() => viewport.scrollTop, [viewport.scrollTop]);
+  const virtualizer = useVirtualizer({
+    enabled: enabled && viewportReady,
+    useFlushSync: false,
+    count: rowGeometry.rowKeys.length,
+    getScrollElement: () => scrollRef.current,
+    estimateSize,
+    getItemKey,
+    overscan: TIMELINE_VIEWPORT_BUDGETS.rowOverscanPerSide,
+    rangeExtractor,
+    scrollMargin: RULER_H + TRACKS_TOP_PAD,
+    initialRect: { width: viewport.clientWidth, height: viewport.clientHeight },
+    initialOffset,
+  });
+
+  useEffect(() => {
+    if (!enabled || !viewportReady) return;
+    virtualizer.measure();
+    // Timeline owns the epoch reset. This event only makes the virtualizer
+    // observe the authoritative DOM offset after that reset; it never writes
+    // scrollTop itself.
+    scrollRef.current?.dispatchEvent(new Event("scroll"));
+  }, [enabled, scrollRef, sessionEpoch, viewportReady, virtualizer]);
+
+  const focusedRowIndex = focusedRowKey === undefined ? -1 : rowGeometry.getRowIndex(focusedRowKey);
+  const focusedRowHeight = focusedRowIndex < 0 ? 0 : rowGeometry.getRowHeight(focusedRowIndex);
+  useEffect(() => {
+    if (enabled && viewportReady && focusedRowIndex >= 0) {
+      virtualizer.resizeItem(focusedRowIndex, focusedRowHeight);
+    }
+  }, [enabled, focusedRowHeight, focusedRowIndex, sessionEpoch, viewportReady, virtualizer]);
+
+  const compatibilityRows = useMemo(
+    () => (enabled ? null : rowGeometry.rowKeys.map((rowKey, index) => ({ index, rowKey }))),
+    [enabled, rowGeometry],
+  );
+  if (compatibilityRows) return compatibilityRows;
+  if (!viewportReady) {
+    return extractTimelineVirtualRowSeed(rowGeometry.rowKeys.length, pinnedRowIndexes).map(
+      (index) => ({
+        index,
+        rowKey: rowGeometry.rowKeys[index] ?? index,
+      }),
+    );
+  }
+  return virtualizer.getVirtualItems().map(({ index }) => ({
+    index,
+    rowKey: rowGeometry.rowKeys[index] ?? index,
+  }));
+}

package/src/player/hooks/timelinePlayerSync.ts

@@ -0,0 +1,20 @@
+import type { TimelineElement } from "../store/playerStore";
+
+/** Whether a derived timeline changes any field that affects rendering. */
+export function timelineElementsChanged(
+  previous: TimelineElement[],
+  next: TimelineElement[],
+): boolean {
+  if (next.length !== previous.length) return true;
+  return next.some((element, index) => {
+    const prior = previous[index];
+    return (
+      !prior ||
+      element.id !== prior.id ||
+      element.start !== prior.start ||
+      element.duration !== prior.duration ||
+      element.track !== prior.track ||
+      element.sourceDuration !== prior.sourceDuration
+    );
+  });
+}

package/src/player/hooks/useTimelinePlayer.seek.test.ts

@@ -5,6 +5,7 @@ import { createRoot } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { useTimelinePlayer } from "./useTimelinePlayer";
 import { liveTime, usePlayerStore } from "../store/playerStore";
+import { setTimelinePerformanceFixtureLease } from "../lib/timelinePerformanceFixture";
 
 globalThis.IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -40,10 +41,30 @@ function renderTimelinePlayerHarness() {
 }
 
 afterEach(() => {
+  setTimelinePerformanceFixtureLease(false);
   document.body.innerHTML = "";
   resetPlayerStore();
 });
 
+function attachIframeWindow(
+  api: ReturnType<typeof useTimelinePlayer>,
+  iframeWindow: Record<string, unknown>,
+): void {
+  const iframe = document.createElement("iframe");
+  Object.defineProperty(iframe, "contentWindow", {
+    value: iframeWindow,
+    configurable: true,
+  });
+  Object.defineProperty(iframe, "contentDocument", {
+    value: document.implementation.createHTMLDocument("preview"),
+    configurable: true,
+  });
+  act(() => {
+    api.iframeRef.current = iframe;
+    api.onIframeLoad();
+  });
+}
+
 function attachIframeAdapter(
   api: ReturnType<typeof useTimelinePlayer>,
   options: {
@@ -52,7 +73,6 @@ function attachIframeAdapter(
     duration?: number;
   } = {},
 ) {
-  const iframe = document.createElement("iframe");
   let currentTime = 0;
   let playing = false;
   const adapter = {
@@ -69,24 +89,13 @@ function attachIframeAdapter(
     getDuration: () => options.duration ?? 30,
     isPlaying: () => playing,
   };
-  Object.defineProperty(iframe, "contentWindow", {
-    value: {
-      __player: adapter,
-      __timelines: options.timelines,
-      postMessage: options.postMessage ?? (() => {}),
-      scrollTo: () => {},
-      addEventListener: () => {},
-      removeEventListener: () => {},
-    },
-    configurable: true,
-  });
-  Object.defineProperty(iframe, "contentDocument", {
-    value: document.implementation.createHTMLDocument("preview"),
-    configurable: true,
-  });
-  act(() => {
-    api.iframeRef.current = iframe;
-    api.onIframeLoad();
+  attachIframeWindow(api, {
+    __player: adapter,
+    __timelines: options.timelines,
+    postMessage: options.postMessage ?? (() => {}),
+    scrollTo: () => {},
+    addEventListener: () => {},
+    removeEventListener: () => {},
   });
   return adapter;
 }
@@ -129,6 +138,61 @@ function expectStorePlaybackState(
 }
 
 describe("useTimelinePlayer seek hydration", () => {
+  it("ignores runtime timeline work while the performance fixture lease is active", () => {
+    const { api, root } = renderTimelinePlayerHarness();
+    attachIframeAdapter(api);
+    const iframeWindow = api.iframeRef.current?.contentWindow;
+    const iframeDocument = api.iframeRef.current?.contentDocument;
+    if (!iframeWindow || !iframeDocument) throw new Error("iframe did not attach");
+    const querySelector = vi.spyOn(iframeDocument, "querySelector");
+    const clips = [
+      {
+        id: "runtime-clip",
+        label: "Runtime clip",
+        start: 0,
+        duration: 1,
+        track: 0,
+        kind: "element",
+        tagName: "div",
+        compositionId: null,
+        parentCompositionId: null,
+        compositionSrc: null,
+        assetUrl: null,
+      },
+    ];
+    const dispatchTimeline = () =>
+      window.dispatchEvent(
+        new MessageEvent("message", {
+          source: iframeWindow,
+          data: {
+            source: "hf-preview",
+            type: "timeline",
+            clips,
+            durationInFrames: 30,
+            fps: 30,
+          },
+        }),
+      );
+    try {
+      act(() => {
+        usePlayerStore.setState({ clipManifest: null });
+        setTimelinePerformanceFixtureLease(true);
+        dispatchTimeline();
+      });
+      expect(usePlayerStore.getState().clipManifest).toBeNull();
+      expect(querySelector).not.toHaveBeenCalled();
+
+      act(() => {
+        setTimelinePerformanceFixtureLease(false);
+        dispatchTimeline();
+      });
+      expect(usePlayerStore.getState().clipManifest).toEqual(clips);
+      expect(querySelector).toHaveBeenCalled();
+    } finally {
+      unmountWithAct(root);
+    }
+  });
+
   it("keeps an external seek request until the iframe adapter is ready", () => {
     const observedTimes: number[] = [];
     const unsubscribe = liveTime.subscribe((time) => {
@@ -156,26 +220,13 @@ describe("useTimelinePlayer seek hydration", () => {
 
   it("does not settle from an unsupported runtime protocol message", () => {
     const { api, root } = renderTimelinePlayerHarness();
-    const iframe = document.createElement("iframe");
     const iframeWindow = {
       postMessage: vi.fn(),
       scrollTo: vi.fn(),
       addEventListener: vi.fn(),
       removeEventListener: vi.fn(),
     } as Record<string, unknown>;
-    Object.defineProperty(iframe, "contentWindow", {
-      value: iframeWindow,
-      configurable: true,
-    });
-    Object.defineProperty(iframe, "contentDocument", {
-      value: document.implementation.createHTMLDocument("preview"),
-      configurable: true,
-    });
-
-    act(() => {
-      api.iframeRef.current = iframe;
-      api.onIframeLoad();
-    });
+    attachIframeWindow(api, iframeWindow);
     expect(usePlayerStore.getState().timelineReady).toBe(false);
 
     iframeWindow.__player = {
@@ -339,7 +390,6 @@ describe("useTimelinePlayer RAF loop wrap-around", () => {
   type SeekCall = { time: number; options?: { keepPlaying?: boolean } };
 
   function attachInstrumentedAdapter(api: ReturnType<typeof useTimelinePlayer>, duration = 30) {
-    const iframe = document.createElement("iframe");
     let currentTime = 0;
     let playing = false;
     const seekCalls: SeekCall[] = [];
@@ -361,23 +411,12 @@ describe("useTimelinePlayer RAF loop wrap-around", () => {
         currentTime = t;
       },
     };
-    Object.defineProperty(iframe, "contentWindow", {
-      value: {
-        __player: adapter,
-        postMessage: () => {},
-        scrollTo: () => {},
-        addEventListener: () => {},
-        removeEventListener: () => {},
-      },
-      configurable: true,
-    });
-    Object.defineProperty(iframe, "contentDocument", {
-      value: document.implementation.createHTMLDocument("preview"),
-      configurable: true,
-    });
-    act(() => {
-      api.iframeRef.current = iframe;
-      api.onIframeLoad();
+    attachIframeWindow(api, {
+      __player: adapter,
+      postMessage: () => {},
+      scrollTo: () => {},
+      addEventListener: () => {},
+      removeEventListener: () => {},
     });
     return { adapter, seekCalls };
   }

package/src/player/hooks/useTimelinePlayer.ts

@@ -39,30 +39,12 @@ import {
 import { normalizeToZones } from "../components/timelineZones";
 import { setPreviewMediaMuted, setPreviewPlaybackRate } from "../lib/timelineIframeHelpers";
 import { scrubMusicAtSeek, stopScrubPreviewAudio } from "../lib/playbackScrub";
+import { hasTimelinePerformanceFixtureLease } from "../lib/timelinePerformanceFixture";
 import { applyCachedSourceDurations, probeMissingSourceDurations } from "../lib/mediaProbe";
 import { shouldResumeForwardPlaybackAfterSeek, shouldStopAfterSeek } from "../lib/playbackSeek";
 import { applyPreviewVariablesToUrl } from "../../hooks/previewVariablesStore";
 import { acceptStudioRuntimeMessage } from "../lib/runtimeProtocol";
-
-/**
- * Whether the derived elements differ from the current ones in any field that
- * affects rendering (identity, timing, track, or source length) — used to skip
- * redundant store writes.
- */
-function timelineElementsChanged(prev: TimelineElement[], next: TimelineElement[]): boolean {
-  if (next.length !== prev.length) return true;
-  return next.some((el, i) => {
-    const p = prev[i];
-    return (
-      !p ||
-      el.id !== p.id ||
-      el.start !== p.start ||
-      el.duration !== p.duration ||
-      el.track !== p.track ||
-      el.sourceDuration !== p.sourceDuration
-    );
-  });
-}
+import { timelineElementsChanged } from "./timelinePlayerSync";
 
 export function useTimelinePlayer() {
   const iframeRef = useRef<HTMLIFrameElement | null>(null);
@@ -81,8 +63,13 @@ export function useTimelinePlayer() {
   const { setIsPlaying, setCurrentTime, setDuration, setTimelineReady, setElements } =
     usePlayerStore.getState();
 
+  // The fixture lease belongs at this shared synchronization boundary so every
+  // iframe discovery path has the same owner for deciding whether it may write.
   const syncTimelineElements = useCallback(
+    // The lease guard adds one deliberate branch at the shared synchronization boundary.
+    // fallow-ignore-next-line complexity
     (elements: TimelineElement[], nextDuration?: number) => {
+      if (hasTimelinePerformanceFixtureLease()) return;
       const state = usePlayerStore.getState();
       const resolvedDuration = nextDuration ?? state.duration;
       // applyCachedSourceDurations re-applies the cached probe duration: re-derived
@@ -480,6 +467,7 @@ export function useTimelinePlayer() {
     // Pre-existing message-router complexity — surfaced by line shifts, not new logic.
     // fallow-ignore-next-line complexity
     const handleMessage = (e: MessageEvent) => {
+      if (hasTimelinePerformanceFixtureLease()) return;
       const data = e.data;
       const ourIframe = iframeRef.current;
       if (e.source && ourIframe && e.source !== ourIframe.contentWindow) {

package/src/player/lib/playbackScrub.ts

@@ -1,6 +1,6 @@
 import { usePlayerStore } from "../store/playerStore";
-import { isMusicTrack } from "../../utils/timelineInspector";
 import { scrubPreviewAudio, stopScrubPreviewAudio } from "./timelineIframeHelpers";
+import { getTimelineElementIndexes } from "./timelineElementIndexes";
 
 export { stopScrubPreviewAudio };
 
@@ -8,7 +8,7 @@ export { stopScrubPreviewAudio };
 // Skipped when audio is muted or the time falls outside the music clip.
 export function scrubMusicAtSeek(iframe: HTMLIFrameElement | null, nextTime: number): void {
   const s = usePlayerStore.getState();
-  const music = s.elements.find(isMusicTrack);
+  const music = getTimelineElementIndexes(s.elements).musicElement;
   if (!music || s.audioMuted) return;
   const rel = nextTime - music.start;
   const audioFileTime = rel >= 0 && rel <= music.duration ? (music.playbackStart ?? 0) + rel : null;