@hyperframes/studio 0.7.86 → 0.7.88

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

@@ -0,0 +1,202 @@
+// @vitest-environment happy-dom
+
+import React, { act, useRef } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+let resizeCallback: ResizeObserverCallback | null = null;
+class MockResizeObserver {
+  constructor(callback: ResizeObserverCallback) {
+    resizeCallback = callback;
+  }
+  observe() {}
+  disconnect() {}
+}
+
+const originalResizeObserver = globalThis.ResizeObserver;
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllEnvs();
+  globalThis.ResizeObserver = originalResizeObserver;
+  resizeCallback = null;
+  document.body.innerHTML = "";
+});
+
+interface Harness {
+  hook: () => ReturnType<
+    typeof import("./useTimelineScrollViewport").useTimelineScrollViewport
+  > | null;
+  element: HTMLDivElement;
+  values: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    scrollWidth: number;
+    scrollHeight: number;
+  };
+  unmount: () => void;
+}
+
+/**
+ * The row-virtualization flag is a module constant, so the env stub has to be in
+ * place before the hook module is imported. Each harness therefore resets the
+ * module registry and imports fresh, which is what lets one file exercise both
+ * flag states.
+ */
+async function mountHarness(rowVirtualizationEnabled: boolean): Promise<Harness> {
+  vi.stubEnv(
+    "VITE_STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED",
+    rowVirtualizationEnabled ? "1" : "0",
+  );
+  vi.resetModules();
+  const { useTimelineScrollViewport } = await import("./useTimelineScrollViewport");
+
+  let current: ReturnType<typeof useTimelineScrollViewport> | null = null;
+  function Probe() {
+    current = useTimelineScrollViewport(useRef<HTMLDivElement>(null), []);
+    return null;
+  }
+
+  const root = createRoot(document.createElement("div"));
+  act(() => root.render(React.createElement(Probe)));
+
+  const element = document.createElement("div");
+  const values = {
+    left: 0,
+    top: 0,
+    width: 640,
+    height: 240,
+    scrollWidth: 1200,
+    scrollHeight: 800,
+  };
+  Object.defineProperties(element, {
+    scrollLeft: { configurable: true, get: () => values.left },
+    scrollTop: { configurable: true, get: () => values.top },
+    clientWidth: { configurable: true, get: () => values.width },
+    clientHeight: { configurable: true, get: () => values.height },
+    scrollWidth: { configurable: true, get: () => values.scrollWidth },
+    scrollHeight: { configurable: true, get: () => values.scrollHeight },
+  });
+
+  return { hook: () => current, element, values, unmount: () => act(() => root.unmount()) };
+}
+
+function attachScrollElement({ hook, element }: Harness): void {
+  act(() => hook()?.setScrollRef(element));
+}
+
+function publishResize(harness: Harness, width: number): void {
+  harness.values.width = width;
+  act(() => resizeCallback?.([], {} as ResizeObserver));
+}
+
+function publishScroll(
+  harness: Harness,
+  { left, top }: { left: number; top: number },
+  isScrolling = true,
+): void {
+  harness.values.left = left;
+  harness.values.top = top;
+  act(() => harness.hook()?.syncScrollViewport(harness.element, isScrolling));
+  act(() => vi.advanceTimersByTime(16));
+}
+
+function expectResizePublication(harness: Harness): void {
+  attachScrollElement(harness);
+  expect(harness.hook()?.viewport.clientWidth).toBe(640);
+
+  publishResize(harness, 800);
+  expect(harness.hook()?.viewport.clientWidth).toBe(800);
+}
+
+describe("useTimelineScrollViewport with row virtualization on", () => {
+  it("publishes resize, scroll, and settled snapshots", async () => {
+    const harness = await mountHarness(true);
+    const { hook, unmount } = harness;
+
+    expectResizePublication(harness);
+
+    publishScroll(harness, { left: 120, top: 48 });
+    expect(hook()?.viewport).toMatchObject({ scrollLeft: 120, scrollTop: 48, isScrolling: true });
+
+    act(() => vi.advanceTimersByTime(100));
+    expect(hook()?.viewport.isScrolling).toBe(false);
+    unmount();
+  });
+});
+
+describe("useTimelineScrollViewport with row virtualization off", () => {
+  it("publishes nothing while scrolling", async () => {
+    const harness = await mountHarness(false);
+    const { hook, unmount } = harness;
+
+    attachScrollElement(harness);
+    const before = hook()?.viewport;
+
+    publishScroll(harness, { left: 120, top: 48 });
+
+    expect(hook()?.viewport).toBe(before);
+    expect(hook()?.viewport.scrollLeft).toBe(0);
+    unmount();
+  });
+
+  it("never reports isScrolling, so the settle timer has nothing to undo", async () => {
+    const harness = await mountHarness(false);
+    const { hook, unmount } = harness;
+
+    attachScrollElement(harness);
+    publishScroll(harness, { left: 0, top: 0 });
+    act(() => vi.advanceTimersByTime(500));
+
+    expect(hook()?.viewport.isScrolling).toBe(false);
+    unmount();
+  });
+
+  it("schedules no frame or timer for a scroll sync", async () => {
+    const harness = await mountHarness(false);
+    const { hook, element, unmount } = harness;
+    attachScrollElement(harness);
+
+    const rafSpy = vi.spyOn(globalThis, "requestAnimationFrame");
+    const timerSpy = vi.spyOn(globalThis, "setTimeout");
+    act(() => hook()?.syncScrollViewport(element, true));
+
+    expect(rafSpy).not.toHaveBeenCalled();
+    expect(timerSpy).not.toHaveBeenCalled();
+    rafSpy.mockRestore();
+    timerSpy.mockRestore();
+    unmount();
+  });
+
+  it("still publishes resize-driven snapshots", async () => {
+    const harness = await mountHarness(false);
+    const { unmount } = harness;
+
+    expectResizePublication(harness);
+    unmount();
+  });
+
+  it("still publishes programmatic non-scrolling syncs", async () => {
+    const harness = await mountHarness(false);
+    const { hook, unmount } = harness;
+
+    attachScrollElement(harness);
+    publishScroll(harness, { left: 240, top: 96 }, false);
+
+    expect(hook()?.viewport).toMatchObject({
+      scrollLeft: 240,
+      scrollTop: 96,
+      isScrolling: false,
+    });
+    unmount();
+  });
+});

package/src/player/components/useTimelineScrollViewport.ts

@@ -1,6 +1,45 @@
 import { useCallback, useEffect, useRef, useState, type RefObject } from "react";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { shouldShowTimelineShortcutHint } from "./timelineLayout";
+import { STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED } from "./timelineRowVirtualizationFlag";
+
+export interface TimelineScrollViewportSnapshot {
+  readonly scrollLeft: number;
+  readonly scrollTop: number;
+  readonly clientWidth: number;
+  readonly clientHeight: number;
+  readonly scrollWidth: number;
+  readonly scrollHeight: number;
+  readonly isScrolling: boolean;
+}
+
+const EMPTY_VIEWPORT: TimelineScrollViewportSnapshot = Object.freeze({
+  scrollLeft: 0,
+  scrollTop: 0,
+  clientWidth: 0,
+  clientHeight: 0,
+  scrollWidth: 0,
+  scrollHeight: 0,
+  isScrolling: false,
+});
+
+function readTimelineScrollViewport(
+  element: Pick<
+    HTMLElement,
+    "scrollLeft" | "scrollTop" | "clientWidth" | "clientHeight" | "scrollWidth" | "scrollHeight"
+  >,
+  isScrolling: boolean,
+): TimelineScrollViewportSnapshot {
+  return {
+    scrollLeft: element.scrollLeft,
+    scrollTop: element.scrollTop,
+    clientWidth: element.clientWidth,
+    clientHeight: element.clientHeight,
+    scrollWidth: element.scrollWidth,
+    scrollHeight: element.scrollHeight,
+    isScrolling,
+  };
+}
 
 /**
  * The timeline scroll container's viewport plumbing — extracted verbatim from
@@ -14,14 +53,46 @@ export function useTimelineScrollViewport(
   scrollRef: RefObject<HTMLDivElement | null>,
   resyncShortcutHintOn: ReadonlyArray<unknown>,
 ): {
-  viewportWidth: number;
+  viewport: TimelineScrollViewportSnapshot;
   showShortcutHint: boolean;
   setScrollRef: (el: HTMLDivElement | null) => void;
+  syncScrollViewport: (el: HTMLDivElement, isScrolling?: boolean) => void;
 } {
-  const [viewportWidth, setViewportWidth] = useState(0);
+  const [viewport, setViewport] = useState<TimelineScrollViewportSnapshot>(EMPTY_VIEWPORT);
   const [showShortcutHint, setShowShortcutHint] = useState(true);
   const roRef = useRef<ResizeObserver | null>(null);
   const shortcutHintRafRef = useRef(0);
+  const viewportRafRef = useRef(0);
+  const scrollSettledTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const scrollingRef = useRef(false);
+
+  const syncScrollViewport = useCallback((el: HTMLDivElement, isScrolling = false) => {
+    // Row virtualization is the only consumer of the per-frame scroll snapshot.
+    // With the flag off, publishing it re-rendered every mounted clip on every
+    // scroll frame and bought nothing, so the scroll path stops here and
+    // `isScrolling` stays false. Resize-driven and programmatic syncs arrive
+    // through the immediate path below and still publish.
+    if (isScrolling && !STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED) return;
+    scrollingRef.current = isScrolling;
+    const publish = () => {
+      viewportRafRef.current = 0;
+      setViewport(readTimelineScrollViewport(el, scrollingRef.current));
+    };
+    if (isScrolling) {
+      if (!viewportRafRef.current) viewportRafRef.current = requestAnimationFrame(publish);
+    } else {
+      if (viewportRafRef.current) cancelAnimationFrame(viewportRafRef.current);
+      publish();
+      return;
+    }
+    if (scrollSettledTimerRef.current) clearTimeout(scrollSettledTimerRef.current);
+    scrollSettledTimerRef.current = setTimeout(() => {
+      scrollSettledTimerRef.current = null;
+      scrollingRef.current = false;
+      if (viewportRafRef.current) cancelAnimationFrame(viewportRafRef.current);
+      publish();
+    }, 100);
+  }, []);
 
   const syncShortcutHintVisibility = useCallback(() => {
     const scroll = scrollRef.current;
@@ -45,23 +116,30 @@ export function useTimelineScrollViewport(
         roRef.current = null;
       }
       scrollRef.current = el;
-      if (!el) return;
+      if (!el) {
+        if (scrollSettledTimerRef.current) clearTimeout(scrollSettledTimerRef.current);
+        scrollSettledTimerRef.current = null;
+        scrollingRef.current = false;
+        return;
+      }
 
-      const syncScrollViewport = () => {
-        setViewportWidth(el.clientWidth);
+      const syncResize = () => {
+        syncScrollViewport(el, scrollingRef.current);
         scheduleShortcutHintVisibilitySync();
       };
 
-      syncScrollViewport();
-      roRef.current = new ResizeObserver(syncScrollViewport);
+      syncResize();
+      roRef.current = new ResizeObserver(syncResize);
       roRef.current.observe(el);
     },
-    [scrollRef, scheduleShortcutHintVisibilitySync],
+    [scrollRef, scheduleShortcutHintVisibilitySync, syncScrollViewport],
   );
 
   useMountEffect(() => () => {
     roRef.current?.disconnect();
     if (shortcutHintRafRef.current) cancelAnimationFrame(shortcutHintRafRef.current);
+    if (viewportRafRef.current) cancelAnimationFrame(viewportRafRef.current);
+    if (scrollSettledTimerRef.current) clearTimeout(scrollSettledTimerRef.current);
   });
 
   useEffect(() => {
@@ -69,5 +147,5 @@ export function useTimelineScrollViewport(
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [syncShortcutHintVisibility, ...resyncShortcutHintOn]);
 
-  return { viewportWidth, showShortcutHint, setScrollRef };
+  return { viewport, showShortcutHint, setScrollRef, syncScrollViewport };
 }

package/src/player/components/useTimelineSelectionLifecycle.ts

@@ -0,0 +1,29 @@
+import { useEffect, useMemo, useRef } from "react";
+import type { TimelineElement } from "../store/playerStore";
+import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
+
+export function useTimelineSelectionLifecycle(
+  elements: TimelineElement[],
+  selectedElementId: string | null,
+  setShowPopover: (show: boolean) => void,
+  clearRangeSelection: () => void,
+): void {
+  const selectedElement = useMemo(
+    () =>
+      elements.find((element) => getTimelineElementIdentity(element) === selectedElementId) ?? null,
+    [elements, selectedElementId],
+  );
+  const selectedElementRef = useRef<TimelineElement | null>(selectedElement);
+  selectedElementRef.current = selectedElement;
+  const previousSelectedRef = useRef(selectedElementRef.current);
+  // eslint-disable-next-line no-restricted-syntax, react-hooks/exhaustive-deps
+  useEffect(() => {
+    const previous = previousSelectedRef.current;
+    const current = selectedElementRef.current;
+    previousSelectedRef.current = current;
+    if (previous && !current) {
+      setShowPopover(false);
+      clearRangeSelection();
+    }
+  });
+}

package/src/player/components/useTimelineShiftModifier.ts

@@ -0,0 +1,20 @@
+import { useState } from "react";
+import { useMountEffect } from "../../hooks/useMountEffect";
+
+export function useTimelineShiftModifier(): boolean {
+  const [shiftHeld, setShiftHeld] = useState(false);
+  useMountEffect(() => {
+    const handleKey = (event: KeyboardEvent) =>
+      event.key === "Shift" && setShiftHeld(event.type === "keydown");
+    const handleBlur = () => setShiftHeld(false);
+    window.addEventListener("keydown", handleKey);
+    window.addEventListener("keyup", handleKey);
+    window.addEventListener("blur", handleBlur);
+    return () => {
+      window.removeEventListener("keydown", handleKey);
+      window.removeEventListener("keyup", handleKey);
+      window.removeEventListener("blur", handleBlur);
+    };
+  });
+  return shiftHeld;
+}

package/src/player/components/useTimelineTicks.ts

@@ -0,0 +1,22 @@
+import { useMemo } from "react";
+import { STUDIO_PREVIEW_FPS } from "../lib/time";
+import type { TimelineTimeDisplayMode } from "../../utils/studioUiPreferences";
+import type { TimelineTimeRange } from "../lib/timelineClipIndex";
+import { generateTicks, getTimelineMajorTickInterval } from "./timelineRulerGeometry";
+
+export function useTimelineTicks(
+  duration: number,
+  pixelsPerSecond: number,
+  timeDisplayMode: TimelineTimeDisplayMode,
+  renderTimeRange?: TimelineTimeRange,
+) {
+  const frameRate = timeDisplayMode === "frame" ? STUDIO_PREVIEW_FPS : undefined;
+  const ticks = useMemo(
+    () => generateTicks(duration, pixelsPerSecond, frameRate, renderTimeRange),
+    [duration, frameRate, pixelsPerSecond, renderTimeRange],
+  );
+  return {
+    ...ticks,
+    majorTickInterval: getTimelineMajorTickInterval(duration, pixelsPerSecond, frameRate),
+  };
+}

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

@@ -15,6 +15,28 @@ afterEach(() => {
   usePlayerStore.getState().reset();
 });
 
+function renderTrackLayout(
+  elements: TimelineElement[],
+  animations: Map<string, GsapAnimation[]>,
+): {
+  layout: ReturnType<typeof useTimelineTrackLayout>;
+  unmount: () => void;
+} {
+  usePlayerStore.setState({ expandedClipIds: new Set(["clip-1"]) });
+
+  let layout: ReturnType<typeof useTimelineTrackLayout> | undefined;
+  function Probe() {
+    layout = useTimelineTrackLayout(elements, animations, null, new Set());
+    return null;
+  }
+
+  const root = createRoot(document.createElement("div"));
+  act(() => root.render(React.createElement(Probe)));
+  if (!layout) throw new Error("Timeline track layout did not render");
+
+  return { layout, unmount: () => act(() => root.unmount()) };
+}
+
 describe("useTimelineTrackLayout", () => {
   it("counts a flat tween lane and reserves its expanded row height", () => {
     const elements: TimelineElement[] = [
@@ -36,20 +58,13 @@ describe("useTimelineTrackLayout", () => {
         ],
       ],
     ]);
-    usePlayerStore.setState({ expandedClipIds: new Set(["clip-1"]) });
+    const { layout, unmount } = renderTrackLayout(elements, animations);
 
-    let layout: ReturnType<typeof useTimelineTrackLayout> | undefined;
-    function Probe() {
-      layout = useTimelineTrackLayout(elements, animations, null, new Set());
-      return null;
-    }
-
-    const root = createRoot(document.createElement("div"));
-    act(() => root.render(React.createElement(Probe)));
-
-    expect(layout?.laneCounts.get("clip-1")).toBe(1);
-    expect(layout?.rowHeights).toEqual([TRACK_H + LANE_H]);
-    act(() => root.unmount());
+    expect(layout.laneCounts.get("clip-1")).toBe(1);
+    expect(layout.rowHeights).toEqual([TRACK_H + LANE_H]);
+    expect(layout.rowGeometry.rowKeys).toEqual([0]);
+    expect(layout.rowGeometry.canvasHeight).toBeGreaterThan(TRACK_H + LANE_H);
+    unmount();
   });
 
   // The row height reserved here and the lanes actually rendered are two
@@ -69,20 +84,11 @@ describe("useTimelineTrackLayout", () => {
       properties: { x: 420, opacity: 1 },
     };
     const animations = new Map<string, GsapAnimation[]>([["clip-1", [mixed]]]);
-    usePlayerStore.setState({ expandedClipIds: new Set(["clip-1"]) });
-
-    let layout: ReturnType<typeof useTimelineTrackLayout> | undefined;
-    function Probe() {
-      layout = useTimelineTrackLayout(elements, animations, null, new Set());
-      return null;
-    }
-
-    const root = createRoot(document.createElement("div"));
-    act(() => root.render(React.createElement(Probe)));
+    const { layout, unmount } = renderTrackLayout(elements, animations);
 
     expect(getTimelinePropertyLanes([mixed], 0, 1)).toHaveLength(2);
-    expect(layout?.laneCounts.get("clip-1")).toBe(2);
-    expect(layout?.rowHeights).toEqual([TRACK_H + 2 * LANE_H]);
-    act(() => root.unmount());
+    expect(layout.laneCounts.get("clip-1")).toBe(2);
+    expect(layout.rowHeights).toEqual([TRACK_H + 2 * LANE_H]);
+    unmount();
   });
 });

package/src/player/components/useTimelineTrackLayout.ts

@@ -6,8 +6,8 @@ import type { DraggedClipState } from "./timelineClipDragTypes";
 import { useTimelineTrackDerivations } from "./useTimelineTrackDerivations";
 import {
   TRACK_H,
-  getTimelineCanvasHeight,
-  getTimelineRowHeight,
+  createTimelineRowGeometry,
+  type TimelineRowGeometry,
   trackHeights,
   type TimelineTrackHeightClip,
 } from "./timelineLayout";
@@ -72,7 +72,7 @@ function useTimelineRowHeights(
   selectedElementIds: ReadonlySet<string>,
 ) {
   const expandedClipIds = usePlayerStore((s) => s.expandedClipIds);
-  const { laneCounts, rowHeights } = useMemo(() => {
+  const { laneCounts, rowGeometry } = useMemo(() => {
     const laneCounts = computeLaneCounts(tracks, gsapAnimations);
     // Row height follows only the active keyframe clip, so a track with several
     // keyframed elements never reserves empty lanes for the ones not shown.
@@ -87,14 +87,23 @@ function useTimelineRowHeights(
       const clipId = active.key ?? active.id;
       return [{ clipId, laneCount: laneCounts.get(clipId) ?? 0 }];
     });
+    const rowHeights = trackHeights(heightTracks, expandedClipIds);
     return {
       laneCounts,
-      rowHeights: trackHeights(heightTracks, expandedClipIds),
+      rowGeometry: createTimelineRowGeometry(
+        tracks.map(([track]) => track),
+        rowHeights,
+      ),
     };
   }, [expandedClipIds, gsapAnimations, tracks, selectedElementId, selectedElementIds]);
-  const rowHeightsRef = useRef<readonly number[]>(rowHeights);
-  rowHeightsRef.current = rowHeights;
-  return { laneCounts, rowHeights, rowHeightsRef };
+  const rowGeometryRef = useRef<TimelineRowGeometry>(rowGeometry);
+  rowGeometryRef.current = rowGeometry;
+  return {
+    laneCounts,
+    rowGeometry,
+    rowGeometryRef,
+    rowHeights: rowGeometry.rowHeights,
+  };
 }
 
 export function useTimelineTrackLayout(
@@ -106,7 +115,7 @@ export function useTimelineTrackLayout(
   const { tracks, trackStyles, trackOrder } = useTimelineTrackDerivations(expandedElements);
   const trackOrderRef = useRef(trackOrder);
   trackOrderRef.current = trackOrder;
-  const { laneCounts, rowHeights, rowHeightsRef } = useTimelineRowHeights(
+  const { laneCounts, rowGeometry, rowGeometryRef, rowHeights } = useTimelineRowHeights(
     tracks,
     gsapAnimations,
     selectedElementId,
@@ -119,23 +128,23 @@ export function useTimelineTrackLayout(
     trackOrder,
     trackOrderRef,
     laneCounts,
+    rowGeometry,
+    rowGeometryRef,
     rowHeights,
-    rowHeightsRef,
   };
 }
 
 function useDisplayRowHeights(
   displayTrackOrder: readonly number[],
-  trackOrder: readonly number[],
-  rowHeights: readonly number[],
+  rowGeometry: TimelineRowGeometry,
 ) {
   return useMemo(
     () =>
       displayTrackOrder.map((track) => {
-        const row = trackOrder.indexOf(track);
-        return row < 0 ? TRACK_H : getTimelineRowHeight(row, rowHeights);
+        const row = rowGeometry.getRowIndex(track);
+        return row < 0 ? TRACK_H : rowGeometry.getRowHeight(row);
       }),
-    [displayTrackOrder, trackOrder, rowHeights],
+    [displayTrackOrder, rowGeometry],
   );
 }
 
@@ -149,10 +158,18 @@ function useDisplayTrackOrder(draggedClip: DraggedClipState | null, trackOrder:
 export function useTimelineDisplayLayout(
   draggedClip: DraggedClipState | null,
   trackOrder: number[],
-  rowHeights: readonly number[],
+  rowGeometry: TimelineRowGeometry,
 ) {
   const displayTrackOrder = useDisplayTrackOrder(draggedClip, trackOrder);
-  const displayRowHeights = useDisplayRowHeights(displayTrackOrder, trackOrder, rowHeights);
-  const totalH = getTimelineCanvasHeight(displayRowHeights);
-  return { displayTrackOrder, displayRowHeights, totalH };
+  const displayRowHeights = useDisplayRowHeights(displayTrackOrder, rowGeometry);
+  const displayRowGeometry = useMemo(
+    () => createTimelineRowGeometry(displayTrackOrder, displayRowHeights),
+    [displayTrackOrder, displayRowHeights],
+  );
+  return {
+    displayTrackOrder,
+    displayRowHeights: displayRowGeometry.rowHeights,
+    rowGeometry: displayRowGeometry,
+    totalH: displayRowGeometry.canvasHeight,
+  };
 }