@hyperframes/studio 0.7.85 → 0.7.87

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

@@ -1,7 +1,28 @@
 // @vitest-environment happy-dom
 
-import { describe, expect, it } from "vitest";
-import { summarizeTimelinePerformance } from "./useTimelinePerformanceTelemetry";
+import { act, createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const trackStudioTimelinePerformance = vi.hoisted(() => vi.fn());
+
+vi.mock("../../telemetry/events", () => ({
+  trackStudioTimelinePerformance,
+}));
+
+import {
+  summarizeTimelinePerformance,
+  useTimelinePerformanceTelemetry,
+} from "./useTimelinePerformanceTelemetry";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+afterEach(() => {
+  trackStudioTimelinePerformance.mockReset();
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
 
 describe("summarizeTimelinePerformance", () => {
   it("reports raw mounted work and p95 scroll timings", () => {
@@ -52,3 +73,48 @@ describe("summarizeTimelinePerformance", () => {
     ).toBeNull();
   });
 });
+
+describe("useTimelinePerformanceTelemetry", () => {
+  it("measures callback delivery when the animation-frame timestamp predates the scroll", () => {
+    vi.useFakeTimers();
+    let frameCallback: FrameRequestCallback | undefined;
+    vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => {
+      frameCallback = callback;
+      return 1;
+    });
+    vi.stubGlobal("cancelAnimationFrame", vi.fn());
+
+    let recordTimelineScroll: ((scroll: HTMLDivElement) => void) | undefined;
+    function Probe() {
+      recordTimelineScroll = useTimelinePerformanceTelemetry({
+        totalClipCount: 1,
+        totalRowCount: 1,
+        zoomMode: "manual",
+      }).recordTimelineScroll;
+      return null;
+    }
+
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(createElement(Probe)));
+
+    try {
+      vi.spyOn(performance, "now")
+        .mockReturnValueOnce(100)
+        .mockReturnValueOnce(108)
+        .mockReturnValueOnce(500);
+
+      recordTimelineScroll?.(document.createElement("div"));
+      frameCallback?.(99);
+      vi.advanceTimersByTime(400);
+
+      expect(trackStudioTimelinePerformance).toHaveBeenCalledWith(
+        expect.objectContaining({
+          scroll_frame_latency_p95_ms: 8,
+          scroll_frame_latency_max_ms: 8,
+        }),
+      );
+    } finally {
+      act(() => root.unmount());
+    }
+  });
+});

package/src/player/components/useTimelinePerformanceTelemetry.ts

@@ -87,7 +87,7 @@ export function useTimelinePerformanceTelemetry(context: TimelinePerformanceCont
       state.pendingScrollStartedAt = now;
       state.frameRequest = requestAnimationFrame((frameAt) => {
         state.frameRequest = 0;
-        state.frameLatencies.push(frameAt - state.pendingScrollStartedAt);
+        state.frameLatencies.push(performance.now() - state.pendingScrollStartedAt);
         if (state.previousFrameAt !== null) {
           state.frameIntervals.push(frameAt - state.previousFrameAt);
         }

package/src/player/components/useTimelinePlayhead.ts

@@ -1,14 +1,16 @@
 import { useRef, useCallback, useEffect, useLayoutEffect } from "react";
-import { liveTime, type ZoomMode } from "../store/playerStore";
+import { liveTime, usePlayerStore, type ZoomMode } from "../store/playerStore";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { getPinchTimelineZoomPercent } from "./timelineZoom";
 import {
+  getTimelinePlaybackFollowScrollLeft,
   getTimelinePlayheadLeft,
   getTimelineScrubTime,
   getTimelineScrollLeftForZoomTransition,
   getTimelineScrollLeftForZoomAnchor,
   shouldAutoScrollTimeline,
 } from "./timelineLayout";
+import { applyTimelineHorizontalAutoScrollStep } from "./timelineEditing";
 
 interface UseTimelinePlayheadInput {
   playheadRef: React.RefObject<HTMLDivElement | null>;
@@ -121,9 +123,31 @@ export function useTimelinePlayhead({
   useMountEffect(() => {
     const unsub = liveTime.subscribe((t) => {
       if (!playheadRef.current || durationRef.current <= 0) return;
-      // Playback deliberately does NOT scroll the viewport to chase the playhead —
-      // the user's scroll position is theirs; the playhead may run off-screen.
-      playheadRef.current.style.left = `${getTimelinePlayheadLeft(t, ppsRef.current, contentOriginRef.current)}px`;
+      const playheadX = contentOriginRef.current + Math.max(0, t) * ppsRef.current;
+      playheadRef.current.style.left = `${getTimelinePlayheadLeft(
+        t,
+        ppsRef.current,
+        contentOriginRef.current,
+      )}px`;
+      const scroll = scrollRef.current;
+      if (
+        !scroll ||
+        !usePlayerStore.getState().isPlaying ||
+        isDragging.current ||
+        zoomModeRef.current === "fit"
+      ) {
+        return;
+      }
+      const nextScrollLeft = getTimelinePlaybackFollowScrollLeft({
+        playheadX,
+        currentScrollLeft: scroll.scrollLeft,
+        viewportWidth: scroll.clientWidth,
+        contentOrigin: contentOriginRef.current,
+        maxScrollLeft: scroll.scrollWidth - scroll.clientWidth,
+      });
+      if (Math.abs(nextScrollLeft - scroll.scrollLeft) >= 0.5) {
+        scroll.scrollLeft = nextScrollLeft;
+      }
     });
     return unsub;
   });
@@ -157,16 +181,7 @@ export function useTimelinePlayhead({
         !shouldAutoScrollTimeline(zoomModeRef.current, el.scrollWidth, el.clientWidth)
       )
         return;
-      const rect = el.getBoundingClientRect();
-      const edgeZone = 40;
-      const maxSpeed = 12;
-      let scrollDelta = 0;
-      if (clientX < rect.left + edgeZone)
-        scrollDelta = -maxSpeed * Math.max(0, 1 - (clientX - rect.left) / edgeZone);
-      else if (clientX > rect.right - edgeZone)
-        scrollDelta = maxSpeed * Math.max(0, 1 - (rect.right - clientX) / edgeZone);
-      if (scrollDelta !== 0) {
-        el.scrollLeft += scrollDelta;
+      if (applyTimelineHorizontalAutoScrollStep(el, clientX)) {
         seekFromX(clientX);
         dragScrollRaf.current = requestAnimationFrame(() => autoScrollDuringDrag(clientX));
       }
@@ -187,6 +202,7 @@ export function useTimelinePlayhead({
         e.deltaY,
         zoomModeRef.current,
         manualZoomPercentRef.current,
+        fitPpsRef.current,
       );
       if (nextZoomPercent === manualZoomPercentRef.current && zoomModeRef.current === "manual")
         return;

package/src/player/components/useTimelineRangeSelection.ts

@@ -16,6 +16,7 @@ import {
   type MarqueeClipInput,
 } from "./timelineMarquee";
 import type { Rect } from "../../utils/marqueeGeometry";
+import type { TimelineRowGeometry } from "./timelineLayout";
 
 interface UseTimelineRangeSelectionInput {
   scrollRef: React.RefObject<HTMLDivElement | null>;
@@ -30,7 +31,7 @@ interface UseTimelineRangeSelectionInput {
   setShowPopover: (v: boolean) => void;
   elementsRef: React.RefObject<TimelineElement[]>;
   trackOrderRef: React.RefObject<number[]>;
-  rowHeightsRef: React.RefObject<readonly number[]>;
+  rowGeometryRef: React.RefObject<TimelineRowGeometry>;
   onSelectElement?: (element: TimelineElement | null) => void;
   contentOrigin: number;
 }
@@ -107,7 +108,7 @@ export function useTimelineRangeSelection({
   setShowPopover,
   elementsRef,
   trackOrderRef,
-  rowHeightsRef,
+  rowGeometryRef,
   onSelectElement,
   contentOrigin,
 }: UseTimelineRangeSelectionInput) {
@@ -176,12 +177,12 @@ export function useTimelineRangeSelection({
         marquee,
         elementsRef.current ?? [],
         trackOrderRef.current ?? [],
-        rowHeightsRef.current,
+        rowGeometryRef.current.rowHeights,
         ppsRef.current,
         contentOrigin,
       );
     },
-    [toContentPoint, elementsRef, trackOrderRef, rowHeightsRef, ppsRef, contentOrigin],
+    [toContentPoint, elementsRef, trackOrderRef, rowGeometryRef, ppsRef, contentOrigin],
   );
 
   const stopMarqueeAutoScroll = useCallback(() => {

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

@@ -8,6 +8,7 @@ import React, { act } from "react";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { mountReactHarness } from "../../hooks/domSelectionTestHarness";
 import { useTimelineRangeSelection } from "./useTimelineRangeSelection";
+import { getTimelineRowGeometry } from "./timelineLayout";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -60,7 +61,7 @@ function setup(): { handlers: () => Handlers; seekFromX: ReturnType<typeof vi.fn
   const isDragging = { current: false };
   const elementsRef = { current: [] };
   const trackOrderRef = { current: [] };
-  const rowHeightsRef = { current: [] };
+  const rowGeometryRef = { current: getTimelineRowGeometry([]) };
 
   function Probe(): null {
     latest = useTimelineRangeSelection({
@@ -75,7 +76,7 @@ function setup(): { handlers: () => Handlers; seekFromX: ReturnType<typeof vi.fn
       setShowPopover: vi.fn(),
       elementsRef,
       trackOrderRef,
-      rowHeightsRef,
+      rowGeometryRef,
       contentOrigin: 0,
     });
     return null;

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

@@ -0,0 +1,139 @@
+// @vitest-environment happy-dom
+
+import React, { act, useRef } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import { usePlayerStore } from "../store/playerStore";
+import { createTimelineRowGeometry } from "./timelineLayout";
+import { useTimelineRevealClip } from "./useTimelineRevealClip";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const element: TimelineElement = {
+  id: "hero",
+  tag: "div",
+  start: 20,
+  duration: 2,
+  track: 1,
+};
+const geometry = createTimelineRowGeometry([1], [48]);
+
+function createHarnessRoot() {
+  const host = document.createElement("div");
+  document.body.append(host);
+  return { host, root: createRoot(host) };
+}
+
+interface HarnessProps {
+  mounted: boolean;
+  version: number;
+  width?: number;
+  height?: number;
+  deferFocusUntilViewportUpdate?: boolean;
+  focusedElementId?: string;
+}
+
+function Harness({
+  mounted,
+  version,
+  width = 300,
+  height = 100,
+  deferFocusUntilViewportUpdate = false,
+  focusedElementId,
+}: HarnessProps) {
+  const scrollRef = useRef<HTMLDivElement>(null);
+  useTimelineRevealClip({
+    scrollRef,
+    elements: [element],
+    rowGeometry: geometry,
+    pixelsPerSecond: 100,
+    contentOrigin: 32,
+    allowHorizontal: true,
+    deferFocusUntilViewportUpdate,
+    focusedElementId,
+    viewportVersion: version,
+    sessionEpoch: 1,
+  });
+  return (
+    <div
+      ref={(node) => {
+        scrollRef.current = node;
+        if (node) {
+          Object.defineProperty(node, "clientWidth", { configurable: true, value: width });
+          Object.defineProperty(node, "clientHeight", { configurable: true, value: height });
+        }
+      }}
+    >
+      {mounted && <div data-el-id="hero" tabIndex={-1} />}
+    </div>
+  );
+}
+
+async function renderHarness(root: Root, props: HarnessProps): Promise<void> {
+  await act(async () => root.render(<Harness {...props} />));
+}
+
+afterEach(() => {
+  usePlayerStore.getState().reset();
+  document.body.replaceChildren();
+});
+
+describe("useTimelineRevealClip", () => {
+  it("scrolls from model coordinates, then consumes only after the clip mounts", async () => {
+    const { host, root } = createHarnessRoot();
+    usePlayerStore.getState().requestClipReveal("hero");
+
+    await renderHarness(root, { mounted: false, version: 0 });
+    const scroll = host.firstElementChild as HTMLDivElement;
+    expect(scroll.scrollLeft).toBe(1_944);
+    expect(usePlayerStore.getState().clipRevealRequest?.elementId).toBe("hero");
+
+    await renderHarness(root, { mounted: true, version: 1 });
+    expect(usePlayerStore.getState().clipRevealRequest).toBeNull();
+    expect(document.activeElement?.getAttribute("data-el-id")).toBe("hero");
+
+    scroll.scrollLeft = 0;
+    await act(async () => usePlayerStore.getState().requestClipReveal("hero"));
+    await renderHarness(root, { mounted: true, version: 2 });
+    expect(scroll.scrollLeft).toBe(1_944);
+    expect(usePlayerStore.getState().clipRevealRequest).toBeNull();
+    await act(async () => root.unmount());
+  });
+
+  it("consumes an invalid target without scrolling", async () => {
+    const { root } = createHarnessRoot();
+    usePlayerStore.getState().requestClipReveal("missing");
+    await renderHarness(root, { mounted: false, version: 0 });
+    expect(usePlayerStore.getState().clipRevealRequest).toBeNull();
+    await act(async () => root.unmount());
+  });
+
+  it("keeps a reveal pending through zero-size viewport and virtualized focus handoff", async () => {
+    const { host, root } = createHarnessRoot();
+    usePlayerStore.getState().requestClipReveal("hero");
+
+    await renderHarness(root, { mounted: true, version: 0, width: 0, height: 0 });
+    const scroll = host.firstElementChild as HTMLDivElement;
+    expect(scroll.scrollLeft).toBe(0);
+    expect(usePlayerStore.getState().clipRevealRequest?.elementId).toBe("hero");
+    expect(document.activeElement?.getAttribute("data-el-id")).not.toBe("hero");
+
+    await renderHarness(root, {
+      mounted: true,
+      version: 1,
+      deferFocusUntilViewportUpdate: true,
+    });
+    expect(scroll.scrollLeft).toBe(1_944);
+    expect(usePlayerStore.getState().clipRevealRequest?.elementId).toBe("hero");
+    await renderHarness(root, {
+      mounted: true,
+      version: 2,
+      deferFocusUntilViewportUpdate: true,
+      focusedElementId: "hero",
+    });
+    expect(usePlayerStore.getState().clipRevealRequest).toBeNull();
+    expect(document.activeElement?.getAttribute("data-el-id")).toBe("hero");
+    await act(async () => root.unmount());
+  });
+});

package/src/player/components/useTimelineRevealClip.ts

@@ -1,56 +1,180 @@
-/**
- * Consumes playerStore.clipRevealRequest: when another surface (the sidebar
- * asset card / audio row) asks for a clip to be revealed, smooth-scroll the
- * timeline's scroll container so that clip is visible — horizontally to its
- * time and vertically to its lane.
- *
- * The request is consumed (cleared) whether or not the clip node is found, so
- * a stale request can never replay a scroll later. Respects zoom mode: in
- * "fit" the timeline disables horizontal scrolling (overflow-x-hidden), so
- * only the vertical axis is scrolled there.
- */
-import { useEffect } from "react";
+import { useEffect, useRef } from "react";
+import type { TimelineElement } from "../store/playerStore";
 import { usePlayerStore } from "../store/playerStore";
-import { GUTTER, RULER_H } from "./timelineLayout";
+import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
+import { CLIP_Y, RULER_H, type TimelineRowGeometry } from "./timelineLayout";
 import { computeRevealScroll } from "./timelineRevealScroll";
 
-export function useTimelineRevealClip(scrollRef: React.RefObject<HTMLDivElement | null>): void {
-  const revealRequest = usePlayerStore((s) => s.clipRevealRequest);
+interface UseTimelineRevealClipInput {
+  scrollRef: React.RefObject<HTMLDivElement | null>;
+  elements: readonly TimelineElement[];
+  rowGeometry: TimelineRowGeometry;
+  pixelsPerSecond: number;
+  contentOrigin: number;
+  allowHorizontal: boolean;
+  deferFocusUntilViewportUpdate: boolean;
+  focusedElementId?: string;
+  viewportVersion: unknown;
+  sessionEpoch: number;
+}
 
-  useEffect(() => {
-    if (!revealRequest) return;
-    // Consume the request first — reveal is one-shot, even when the clip node
-    // isn't currently rendered (e.g. drilled into a different composition).
+function escapeSelectorValue(value: string): string {
+  return typeof CSS !== "undefined" && typeof CSS.escape === "function"
+    ? CSS.escape(value)
+    : value.replace(/["\\]/g, "\\$&");
+}
+
+function scrollToTimelineElement(
+  container: HTMLDivElement,
+  element: TimelineElement,
+  row: number,
+  rowGeometry: TimelineRowGeometry,
+  pixelsPerSecond: number,
+  contentOrigin: number,
+  allowHorizontal: boolean,
+): boolean {
+  const clipLeft = contentOrigin + element.start * pixelsPerSecond;
+  const target = computeRevealScroll({
+    scrollLeft: container.scrollLeft,
+    scrollTop: container.scrollTop,
+    viewportWidth: container.clientWidth,
+    viewportHeight: container.clientHeight,
+    clipLeft,
+    clipRight: clipLeft + Math.max(element.duration * pixelsPerSecond, 4),
+    clipTop: rowGeometry.getRowTop(row) + CLIP_Y,
+    clipBottom: rowGeometry.getRowTop(row) + rowGeometry.getRowHeight(row) - CLIP_Y,
+    stickyLeft: contentOrigin,
+    stickyTop: RULER_H,
+    allowHorizontal,
+  });
+  if (target.left !== null) container.scrollLeft = target.left;
+  if (target.top !== null) container.scrollTop = target.top;
+  const didScroll = target.left !== null || target.top !== null;
+  if (didScroll) container.dispatchEvent(new Event("scroll"));
+  return didScroll;
+}
+
+function focusRevealedElement(container: HTMLDivElement, elementId: string): boolean {
+  const clip = container.querySelector(`[data-el-id="${escapeSelectorValue(elementId)}"]`);
+  if (!(clip instanceof HTMLElement)) return false;
+  const alreadyHighlighted = clip.hasAttribute("data-reveal-highlight");
+  clip.setAttribute("data-reveal-highlight", "true");
+  clip.focus({ preventScroll: true });
+  if (document.activeElement !== clip) {
+    clip.removeAttribute("data-reveal-highlight");
+    return false;
+  }
+  if (!alreadyHighlighted) {
+    clip.addEventListener("blur", () => clip.removeAttribute("data-reveal-highlight"), {
+      once: true,
+    });
+  }
+  return true;
+}
+
+function focusAndConsumeReveal(
+  container: HTMLDivElement,
+  request: { elementId: string; nonce: number },
+  deferUntilFocusPin: boolean,
+  focusedElementId?: string,
+): void {
+  if (!focusRevealedElement(container, request.elementId)) return;
+  if (deferUntilFocusPin && focusedElementId !== request.elementId) return;
+  if (usePlayerStore.getState().clipRevealRequest === request) {
     usePlayerStore.getState().clearClipRevealRequest();
+  }
+}
 
+function resolveRevealTarget(
+  elements: readonly TimelineElement[],
+  rowGeometry: TimelineRowGeometry,
+  elementId: string,
+): { element: TimelineElement; row: number } | null {
+  const element = elements.find((candidate) => getTimelineElementIdentity(candidate) === elementId);
+  if (!element) return null;
+  const row = rowGeometry.getRowIndex(element.track);
+  return row < 0 ? null : { element, row };
+}
+
+function shouldScrollReveal(
+  previous: { request: { elementId: string; nonce: number }; sessionEpoch: number } | null,
+  request: { elementId: string; nonce: number },
+  sessionEpoch: number,
+): boolean {
+  return previous?.request !== request || previous.sessionEpoch !== sessionEpoch;
+}
+
+/** Coordinate-first reveal; the request remains pinned until its clip mounts. */
+export function useTimelineRevealClip({
+  scrollRef,
+  elements,
+  rowGeometry,
+  pixelsPerSecond,
+  contentOrigin,
+  allowHorizontal,
+  deferFocusUntilViewportUpdate,
+  focusedElementId,
+  viewportVersion,
+  sessionEpoch,
+}: UseTimelineRevealClipInput): void {
+  const revealRequest = usePlayerStore((state) => state.clipRevealRequest);
+  const scrolledRequestRef = useRef<{
+    request: { elementId: string; nonce: number };
+    sessionEpoch: number;
+  } | null>(null);
+
+  useEffect(() => {
+    if (!revealRequest) {
+      scrolledRequestRef.current = null;
+      return;
+    }
+    const target = resolveRevealTarget(elements, rowGeometry, revealRequest.elementId);
+    if (!target) {
+      usePlayerStore.getState().clearClipRevealRequest();
+      return;
+    }
     const container = scrollRef.current;
     if (!container) return;
-    const clip = container.querySelector(`[data-el-id="${CSS.escape(revealRequest.elementId)}"]`);
-    if (!(clip instanceof HTMLElement)) return;
-
-    const containerRect = container.getBoundingClientRect();
-    const clipRect = clip.getBoundingClientRect();
-    const clipLeft = clipRect.left - containerRect.left + container.scrollLeft;
-    const clipTop = clipRect.top - containerRect.top + container.scrollTop;
-
-    const target = computeRevealScroll({
-      scrollLeft: container.scrollLeft,
-      scrollTop: container.scrollTop,
-      viewportWidth: container.clientWidth,
-      viewportHeight: container.clientHeight,
-      clipLeft,
-      clipRight: clipLeft + clipRect.width,
-      clipTop,
-      clipBottom: clipTop + clipRect.height,
-      stickyLeft: GUTTER,
-      stickyTop: RULER_H,
-      allowHorizontal: usePlayerStore.getState().zoomMode === "manual",
-    });
-    if (target.left === null && target.top === null) return;
-    container.scrollTo({
-      left: target.left ?? container.scrollLeft,
-      top: target.top ?? container.scrollTop,
-      behavior: "smooth",
-    });
-  }, [revealRequest, scrollRef]);
+    if (container.clientWidth <= 0 || container.clientHeight <= 0) return;
+
+    if (shouldScrollReveal(scrolledRequestRef.current, revealRequest, sessionEpoch)) {
+      scrolledRequestRef.current = { request: revealRequest, sessionEpoch };
+      const didScroll = scrollToTimelineElement(
+        container,
+        target.element,
+        target.row,
+        rowGeometry,
+        pixelsPerSecond,
+        contentOrigin,
+        allowHorizontal,
+      );
+      // Keep the reveal pin alive until the scroll snapshot catches up. If the
+      // request were consumed here, horizontal windowing could unmount and
+      // recreate the focused clip between the programmatic scroll and the next
+      // viewport publication.
+      if (didScroll && deferFocusUntilViewportUpdate) return;
+    }
+
+    // Focus is the durable row/clip pin. Do not consume the reveal pin until
+    // the focus listener has published that replacement, or windowing can
+    // briefly unmount and recreate the element between the two owners.
+    focusAndConsumeReveal(
+      container,
+      revealRequest,
+      deferFocusUntilViewportUpdate,
+      focusedElementId,
+    );
+  }, [
+    allowHorizontal,
+    contentOrigin,
+    deferFocusUntilViewportUpdate,
+    elements,
+    focusedElementId,
+    pixelsPerSecond,
+    revealRequest,
+    rowGeometry,
+    scrollRef,
+    sessionEpoch,
+    viewportVersion,
+  ]);
 }