@hyperframes/studio 0.7.86 → 0.7.87

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

@@ -0,0 +1,97 @@
+// @vitest-environment happy-dom
+
+import type { SetStateAction } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { mountTimelineClipDragGestureLifecycle } from "./timelineClipDragGestureLifecycle";
+import type { DraggedClipState, ResizingClipState } from "./timelineClipDragTypes";
+
+afterEach(() => {
+  document.body.replaceChildren();
+  usePlayerStore.getState().reset();
+});
+
+describe("timeline clip drag gesture lifecycle", () => {
+  it("finishes a drag after virtualization unmounts its source row", () => {
+    const element: TimelineElement = {
+      id: "clip-1",
+      tag: "div",
+      start: 0,
+      duration: 2,
+      track: 0,
+    };
+    const drag: DraggedClipState = {
+      element,
+      originClientX: 0,
+      originClientY: 0,
+      originScrollLeft: 0,
+      originScrollTop: 0,
+      pointerClientX: 0,
+      pointerClientY: 0,
+      pointerOffsetX: 0,
+      pointerOffsetY: 0,
+      previewStart: 1,
+      previewTrack: 0,
+      desiredTrack: 0,
+      insertRow: null,
+      snapTime: null,
+      snapType: null,
+      started: true,
+    };
+    const draggedClipRef = { current: drag as DraggedClipState | null };
+    const resizingClipRef = { current: null as ResizingClipState | null };
+    const setDraggedClip = (next: SetStateAction<DraggedClipState | null>) => {
+      draggedClipRef.current = typeof next === "function" ? next(draggedClipRef.current) : next;
+    };
+    const updateDraggedClipPreview = vi.fn((previous: DraggedClipState) => ({
+      ...previous,
+      previewStart: 3,
+    }));
+    const onMoveElement = vi.fn();
+    const stopAutoScroll = vi.fn();
+    const dispose = mountTimelineClipDragGestureLifecycle({
+      draggedClipRef,
+      resizingClipRef,
+      blockedClipRef: { current: null },
+      groupResizeRef: { current: null },
+      suppressClickRef: { current: false },
+      elementsRef: { current: [element] },
+      trackOrderRef: { current: [0] },
+      setDraggedClip,
+      setResizingClip: () => {},
+      setShowPopover: () => {},
+      setRangeSelectionRef: { current: null },
+      applyResizePointerRef: { current: () => {} },
+      syncClipDragAutoScrollRef: { current: () => {} },
+      stopClipDragAutoScrollRef: { current: stopAutoScroll },
+      updateDraggedClipPreviewRef: { current: updateDraggedClipPreview },
+      restoreGroupResizeMembers: () => {},
+      updateElement: vi.fn(),
+      onMoveElementRef: { current: onMoveElement },
+      onMoveElementsRef: { current: undefined },
+      onResizeElementRef: { current: undefined },
+      onResizeElementsRef: { current: undefined },
+      onBlockedEditAttemptRef: { current: undefined },
+      readZIndexRef: { current: undefined },
+      onStackingPatchesRef: { current: undefined },
+      refreshAfterLaneMoveRef: { current: undefined },
+    });
+
+    const sourceRow = document.createElement("div");
+    sourceRow.dataset.timelineRow = "";
+    sourceRow.append(document.createElement("div"));
+    document.body.append(sourceRow);
+    sourceRow.remove();
+
+    window.dispatchEvent(new MouseEvent("pointermove", { clientX: 20, clientY: 10 }));
+    expect(updateDraggedClipPreview).toHaveBeenCalledTimes(1);
+    expect(draggedClipRef.current?.previewStart).toBe(3);
+
+    window.dispatchEvent(new MouseEvent("pointerup"));
+    expect(onMoveElement).toHaveBeenCalledWith(element, { start: 3, track: 0 });
+    expect(draggedClipRef.current).toBeNull();
+    expect(stopAutoScroll).toHaveBeenCalledTimes(1);
+
+    dispose();
+  });
+});

package/src/player/components/timelineClipDragGestureLifecycle.ts

@@ -0,0 +1,261 @@
+import type { Dispatch, RefObject, SetStateAction } from "react";
+import { resolveTimelineDragEscape } from "./timelineEditing";
+import { commitDraggedClipMove } from "./timelineClipDragCommit";
+import type {
+  BlockedClipState,
+  DraggedClipState,
+  ResizingClipState,
+} from "./timelineClipDragTypes";
+import type { TimelineGroupResizeSession } from "./timelineGroupEditing";
+import { commitTimelineGroupResize } from "./timelineGroupResizeCommit";
+import {
+  beginTimelineOptimisticGesture,
+  rollbackLatestTimelineOptimisticGesture,
+} from "./timelineOptimisticRevision";
+import type { TimelineEditCallbacks } from "./timelineCallbacks";
+import type { StackingPatch } from "./timelineStackingSync";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+
+type UpdateElement = ReturnType<typeof usePlayerStore.getState>["updateElement"];
+
+interface TimelineClipDragGestureLifecycleInput {
+  draggedClipRef: RefObject<DraggedClipState | null>;
+  resizingClipRef: RefObject<ResizingClipState | null>;
+  blockedClipRef: RefObject<BlockedClipState | null>;
+  groupResizeRef: RefObject<TimelineGroupResizeSession | null>;
+  suppressClickRef: RefObject<boolean>;
+  elementsRef: RefObject<TimelineElement[]>;
+  trackOrderRef: RefObject<number[]>;
+  setDraggedClip: Dispatch<SetStateAction<DraggedClipState | null>>;
+  setResizingClip: Dispatch<SetStateAction<ResizingClipState | null>>;
+  setShowPopover: (show: boolean) => void;
+  setRangeSelectionRef: RefObject<((selection: null) => void) | null>;
+  applyResizePointerRef: RefObject<(resize: ResizingClipState, clientX: number) => void>;
+  syncClipDragAutoScrollRef: RefObject<(clientX: number, clientY: number) => void>;
+  stopClipDragAutoScrollRef: RefObject<() => void>;
+  updateDraggedClipPreviewRef: RefObject<
+    (drag: DraggedClipState, clientX: number, clientY: number) => DraggedClipState
+  >;
+  restoreGroupResizeMembers: (session: TimelineGroupResizeSession, all?: boolean) => void;
+  updateElement: UpdateElement;
+  onMoveElementRef: RefObject<TimelineEditCallbacks["onMoveElement"]>;
+  onMoveElementsRef: RefObject<TimelineEditCallbacks["onMoveElements"]>;
+  onResizeElementRef: RefObject<TimelineEditCallbacks["onResizeElement"]>;
+  onResizeElementsRef: RefObject<TimelineEditCallbacks["onResizeElements"]>;
+  onBlockedEditAttemptRef: RefObject<
+    ((element: TimelineElement, intent: BlockedClipState["intent"]) => void) | undefined
+  >;
+  readZIndexRef: RefObject<((element: TimelineElement) => number) | undefined>;
+  onStackingPatchesRef: RefObject<
+    ((patches: StackingPatch[]) => Promise<unknown> | void) | undefined
+  >;
+  refreshAfterLaneMoveRef: RefObject<(() => void) | undefined>;
+}
+
+export function mountTimelineClipDragGestureLifecycle({
+  // The explicit destructuring mirrors the single call site's dependency object by design.
+  // fallow-ignore-next-line code-duplication
+  draggedClipRef,
+  resizingClipRef,
+  blockedClipRef,
+  groupResizeRef,
+  suppressClickRef,
+  elementsRef,
+  trackOrderRef,
+  setDraggedClip,
+  setResizingClip,
+  setShowPopover,
+  setRangeSelectionRef,
+  applyResizePointerRef,
+  syncClipDragAutoScrollRef,
+  stopClipDragAutoScrollRef,
+  updateDraggedClipPreviewRef,
+  restoreGroupResizeMembers,
+  updateElement,
+  onMoveElementRef,
+  onMoveElementsRef,
+  onResizeElementRef,
+  onResizeElementsRef,
+  onBlockedEditAttemptRef,
+  readZIndexRef,
+  onStackingPatchesRef,
+  refreshAfterLaneMoveRef,
+}: TimelineClipDragGestureLifecycleInput): () => void {
+  const clearSuppressedClick = () => {
+    requestAnimationFrame(() => {
+      suppressClickRef.current = false;
+    });
+  };
+
+  const handleResizePointerMove = (event: PointerEvent, resize: ResizingClipState) => {
+    const distance = Math.abs(event.clientX - resize.originClientX);
+    if (!resize.started && distance < 2) return;
+    setShowPopover(false);
+    setRangeSelectionRef.current?.(null);
+    applyResizePointerRef.current(resize, event.clientX);
+    syncClipDragAutoScrollRef.current(event.clientX, event.clientY);
+  };
+
+  const handleBlockedPointerMove = (event: PointerEvent, blocked: BlockedClipState) => {
+    const distance = Math.hypot(
+      event.clientX - blocked.originClientX,
+      event.clientY - blocked.originClientY,
+    );
+    const threshold = blocked.intent === "move" ? 4 : 2;
+    if (!blocked.started && distance < threshold) return;
+    if (!blocked.started) {
+      blocked.started = true;
+      blockedClipRef.current = blocked;
+      suppressClickRef.current = true;
+      setShowPopover(false);
+      setRangeSelectionRef.current?.(null);
+      onBlockedEditAttemptRef.current?.(blocked.element, blocked.intent);
+    }
+  };
+
+  const handleDragPointerMove = (event: PointerEvent, drag: DraggedClipState) => {
+    const distance = Math.hypot(
+      event.clientX - drag.originClientX,
+      event.clientY - drag.originClientY,
+    );
+    if (!drag.started && distance < 4) return;
+    setShowPopover(false);
+    setRangeSelectionRef.current?.(null);
+    setDraggedClip((previous) =>
+      previous
+        ? updateDraggedClipPreviewRef.current(previous, event.clientX, event.clientY)
+        : previous,
+    );
+    syncClipDragAutoScrollRef.current(event.clientX, event.clientY);
+  };
+
+  const handleWindowPointerMove = (event: PointerEvent) => {
+    const resize = resizingClipRef.current;
+    if (resize) return handleResizePointerMove(event, resize);
+    const blocked = blockedClipRef.current;
+    if (blocked) return handleBlockedPointerMove(event, blocked);
+    const drag = draggedClipRef.current;
+    if (drag) handleDragPointerMove(event, drag);
+  };
+
+  const commitResizePointerUp = (resize: ResizingClipState) => {
+    resizingClipRef.current = null;
+    setResizingClip(null);
+    const groupSession = groupResizeRef.current;
+    groupResizeRef.current = null;
+    if (!resize.started) {
+      if (groupSession) restoreGroupResizeMembers(groupSession);
+      return;
+    }
+    suppressClickRef.current = true;
+    clearSuppressedClick();
+    if (groupSession) {
+      commitTimelineGroupResize(groupSession, updateElement, onResizeElementsRef.current);
+      return;
+    }
+    const hasChanged =
+      resize.previewStart !== resize.element.start ||
+      resize.previewDuration !== resize.element.duration ||
+      resize.previewPlaybackStart !== resize.element.playbackStart;
+    if (!hasChanged) return;
+
+    const resizeKey = resize.element.key ?? resize.element.id;
+    const revision = beginTimelineOptimisticGesture(updateElement, [resizeKey]);
+    updateElement(resizeKey, {
+      start: resize.previewStart,
+      duration: resize.previewDuration,
+      playbackStart: resize.previewPlaybackStart,
+    });
+    Promise.resolve(
+      onResizeElementRef.current?.(resize.element, {
+        start: resize.previewStart,
+        duration: resize.previewDuration,
+        playbackStart: resize.previewPlaybackStart,
+      }),
+    ).catch((error) => {
+      rollbackLatestTimelineOptimisticGesture(updateElement, revision, [
+        {
+          key: resizeKey,
+          updates: {
+            start: resize.element.start,
+            duration: resize.element.duration,
+            playbackStart: resize.element.playbackStart,
+          },
+        },
+      ]);
+      console.error("[Timeline] Failed to persist clip resize", error);
+    });
+  };
+
+  const finishBlockedPointerUp = (blocked: BlockedClipState) => {
+    blockedClipRef.current = null;
+    if (blocked.started) clearSuppressedClick();
+  };
+
+  const commitDragPointerUp = (drag: DraggedClipState) => {
+    draggedClipRef.current = null;
+    setDraggedClip(null);
+    if (!drag.started) return;
+    suppressClickRef.current = true;
+    clearSuppressedClick();
+    commitDraggedClipMove(drag, {
+      elements: elementsRef.current,
+      trackOrder: trackOrderRef.current,
+      updateElement,
+      onMoveElement: onMoveElementRef.current,
+      onMoveElements: onMoveElementsRef.current,
+      selectedKeys: usePlayerStore.getState().selectedElementIds,
+      readZIndex: readZIndexRef.current,
+      onStackingPatches: onStackingPatchesRef.current,
+      refreshAfterLaneMove: refreshAfterLaneMoveRef.current,
+    });
+  };
+
+  const handleWindowPointerUp = () => {
+    stopClipDragAutoScrollRef.current();
+    const resize = resizingClipRef.current;
+    if (resize) return commitResizePointerUp(resize);
+    const blocked = blockedClipRef.current;
+    if (blocked) return finishBlockedPointerUp(blocked);
+    const drag = draggedClipRef.current;
+    if (!drag) {
+      if (suppressClickRef.current) clearSuppressedClick();
+      return;
+    }
+    commitDragPointerUp(drag);
+  };
+
+  const handleWindowKeyDown = (event: KeyboardEvent) => {
+    const decision = resolveTimelineDragEscape({
+      key: event.key,
+      drag: draggedClipRef.current,
+      resize: resizingClipRef.current,
+      blocked: blockedClipRef.current,
+    });
+    if (!decision.cancel) return;
+    event.preventDefault();
+    event.stopPropagation();
+    stopClipDragAutoScrollRef.current();
+    draggedClipRef.current = null;
+    setDraggedClip(null);
+    resizingClipRef.current = null;
+    setResizingClip(null);
+    const groupSession = groupResizeRef.current;
+    groupResizeRef.current = null;
+    if (groupSession) restoreGroupResizeMembers(groupSession);
+    blockedClipRef.current = null;
+    if (decision.suppressClick) suppressClickRef.current = true;
+  };
+
+  window.addEventListener("pointermove", handleWindowPointerMove);
+  window.addEventListener("pointerup", handleWindowPointerUp);
+  window.addEventListener("pointercancel", handleWindowPointerUp);
+  window.addEventListener("keydown", handleWindowKeyDown, true);
+  return () => {
+    stopClipDragAutoScrollRef.current();
+    window.removeEventListener("pointermove", handleWindowPointerMove);
+    window.removeEventListener("pointerup", handleWindowPointerUp);
+    window.removeEventListener("pointercancel", handleWindowPointerUp);
+    window.removeEventListener("keydown", handleWindowKeyDown, true);
+  };
+}

package/src/player/components/timelineDiamondTypes.ts

@@ -29,6 +29,8 @@ export interface TimelineClipDiamondsProps {
   keyframesData: KeyframeCacheEntry;
   clipWidthPx: number;
   clipHeightPx: number;
+  /** Needed to compare the playhead to keyframes in output-frame time. */
+  clipDuration: number;
   /** Beat-dot strip is shown on this track → shrink diamonds + drop them into
    *  the bottom half so they clear the strip at the top. */
   beatsActive?: boolean;
@@ -70,7 +72,10 @@ export interface TimelineDiamondLaneProps extends Omit<
   | "onContextMenuKeyframe"
   | "onMoveKeyframe"
   | "onSelectSegment"
+  | "clipDuration"
 > {
+  /** Isolated lanes may omit timing; without it no playhead diamond is marked. */
+  clipDuration?: number;
   groupAware?: boolean;
   globalEase?: string;
   onSelectSegment?: (target: TimelineKeyframeTarget) => void;

package/src/player/components/timelineDragDrop.ts

@@ -5,7 +5,7 @@ import {
   TIMELINE_COMPOSITION_MIME,
 } from "../../utils/timelineCompositionDrop";
 import { usePlayerStore } from "../store/playerStore";
-import { resolveTimelineAssetDrop } from "./timelineLayout";
+import { resolveTimelineAssetDrop, type TimelineRowGeometry } from "./timelineLayout";
 import type { TimelineDropCallbacks } from "./timelineCallbacks";
 
 interface UseTimelineAssetDropOptions extends TimelineDropCallbacks {
@@ -13,7 +13,7 @@ interface UseTimelineAssetDropOptions extends TimelineDropCallbacks {
   ppsRef: RefObject<number>;
   durationRef: RefObject<number>;
   trackOrderRef: RefObject<number[]>;
-  rowHeightsRef: RefObject<readonly number[]>;
+  rowGeometryRef: RefObject<TimelineRowGeometry>;
   contentOrigin: number;
 }
 
@@ -56,7 +56,7 @@ export function useTimelineAssetDrop({
   ppsRef,
   durationRef,
   trackOrderRef,
-  rowHeightsRef,
+  rowGeometryRef,
   contentOrigin,
   onFileDrop,
   onAssetDrop,
@@ -93,7 +93,7 @@ export function useTimelineAssetDrop({
           pixelsPerSecond: ppsRef.current,
           duration: durationRef.current,
           clampStartToDuration: !usePointerStart,
-          rowHeights: rowHeightsRef.current,
+          rowHeights: rowGeometryRef.current.rowHeights,
           trackOrder: trackOrderRef.current,
         },
         clientX,
@@ -104,7 +104,7 @@ export function useTimelineAssetDrop({
         track: pointer.track,
       };
     },
-    [scrollRef, ppsRef, durationRef, trackOrderRef, rowHeightsRef, contentOrigin],
+    [scrollRef, ppsRef, durationRef, trackOrderRef, rowGeometryRef, contentOrigin],
   );
 
   const handleAssetDrop = useCallback(

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

@@ -669,6 +669,38 @@ describe("resolveTimelineAutoScroll", () => {
       ),
     ).toEqual({ x: 9, y: 6 });
   });
+
+  it("uses the time-grid edge instead of the viewport edge when labels are sticky", () => {
+    expect(
+      resolveTimelineAutoScroll(
+        {
+          left: 100,
+          top: 100,
+          right: 700,
+          bottom: 400,
+        },
+        340,
+        250,
+        232,
+      ),
+    ).toEqual({ x: -10, y: 0 });
+  });
+
+  it("caps auto-scroll speed when the pointer moves inside the sticky labels", () => {
+    expect(
+      resolveTimelineAutoScroll(
+        {
+          left: 100,
+          top: 100,
+          right: 700,
+          bottom: 400,
+        },
+        120,
+        250,
+        232,
+      ),
+    ).toEqual({ x: -12, y: 0 });
+  });
 });
 
 describe("buildTimelineAgentPrompt", () => {

package/src/player/components/timelineEditing.ts

@@ -84,21 +84,24 @@ export function resolveTimelineAutoScroll(
   bounds: TimelineAutoScrollBounds,
   clientX: number,
   clientY: number,
+  leftInset = 0,
 ): { x: number; y: number } {
   const getAxisDelta = (start: number, end: number, pointer: number) => {
     if (pointer < start + AUTO_SCROLL_EDGE_ZONE) {
-      const proximity = Math.max(0, 1 - (pointer - start) / AUTO_SCROLL_EDGE_ZONE);
+      const proximity = Math.min(1, Math.max(0, 1 - (pointer - start) / AUTO_SCROLL_EDGE_ZONE));
       return -Math.round(AUTO_SCROLL_MAX_SPEED * proximity);
     }
     if (pointer > end - AUTO_SCROLL_EDGE_ZONE) {
-      const proximity = Math.max(0, 1 - (end - pointer) / AUTO_SCROLL_EDGE_ZONE);
+      const proximity = Math.min(1, Math.max(0, 1 - (end - pointer) / AUTO_SCROLL_EDGE_ZONE));
       return Math.round(AUTO_SCROLL_MAX_SPEED * proximity);
     }
     return 0;
   };
 
+  const horizontalStart = Math.min(bounds.right, bounds.left + Math.max(0, leftInset));
+
   return {
-    x: getAxisDelta(bounds.left, bounds.right, clientX),
+    x: getAxisDelta(horizontalStart, bounds.right, clientX),
     y: getAxisDelta(bounds.top, bounds.bottom, clientY),
   };
 }
@@ -485,7 +488,41 @@ export function applyTimelineAutoScrollStep(
   clientX: number,
   clientY: number,
 ): boolean {
-  const delta = resolveTimelineAutoScroll(scroll.getBoundingClientRect(), clientX, clientY);
+  return applyTimelineAutoScrollDelta(
+    scroll,
+    resolveTimelineAutoScroll(
+      scroll.getBoundingClientRect(),
+      clientX,
+      clientY,
+      getTimelineAutoScrollLeftInset(scroll),
+    ),
+  );
+}
+
+/** Apply one horizontal edge-scroll step while scrubbing the ruler/playhead. */
+export function applyTimelineHorizontalAutoScrollStep(
+  scroll: HTMLElement,
+  clientX: number,
+): boolean {
+  const bounds = scroll.getBoundingClientRect();
+  const delta = resolveTimelineAutoScroll(
+    bounds,
+    clientX,
+    bounds.top + (bounds.bottom - bounds.top) / 2,
+    getTimelineAutoScrollLeftInset(scroll),
+  );
+  return applyTimelineAutoScrollDelta(scroll, { x: delta.x, y: 0 });
+}
+
+function getTimelineAutoScrollLeftInset(scroll: HTMLElement): number {
+  const inset = Number(scroll.dataset.timelineAutoScrollLeftInset);
+  return Number.isFinite(inset) ? Math.max(0, inset) : 0;
+}
+
+function applyTimelineAutoScrollDelta(
+  scroll: HTMLElement,
+  delta: { x: number; y: number },
+): boolean {
   if (delta.x === 0 && delta.y === 0) return false;
   const maxScrollLeft = Math.max(0, scroll.scrollWidth - scroll.clientWidth);
   const maxScrollTop = Math.max(0, scroll.scrollHeight - scroll.clientHeight);
@@ -510,7 +547,12 @@ export function resolveTimelineAutoScrollLoopAction(
   rafActive: boolean,
 ): "start" | "stop" | "none" {
   if (!scroll) return "none";
-  const delta = resolveTimelineAutoScroll(scroll.getBoundingClientRect(), clientX, clientY);
+  const delta = resolveTimelineAutoScroll(
+    scroll.getBoundingClientRect(),
+    clientX,
+    clientY,
+    getTimelineAutoScrollLeftInset(scroll),
+  );
   if (delta.x === 0 && delta.y === 0) return rafActive ? "stop" : "none";
   return rafActive ? "none" : "start";
 }

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

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import { resolveTimelineFocusIdentity } from "./timelineFocusIdentity";
+
+describe("timeline focus identity", () => {
+  const elements: TimelineElement[] = [
+    { id: "clip/a", key: "stable:key", tag: "div", start: 0, duration: 1, track: 7.5 },
+  ];
+
+  it("resolves a stable element id and fractional display row from model identity", () => {
+    expect(resolveTimelineFocusIdentity(elements, "stable:key")).toEqual({
+      elementId: "stable:key",
+      rowKey: 7.5,
+    });
+  });
+
+  it("does not invent focus for a missing or cleared identity", () => {
+    expect(resolveTimelineFocusIdentity(elements, "missing")).toBeNull();
+    expect(resolveTimelineFocusIdentity(elements, null)).toBeNull();
+  });
+});

package/src/player/components/timelineFocusIdentity.ts

@@ -0,0 +1,21 @@
+import type { TimelineElement } from "../store/playerStore";
+import { getTimelineElementIndexes } from "../lib/timelineElementIndexes";
+
+export interface TimelineFocusIdentity {
+  readonly elementId: string;
+  readonly rowKey: number;
+}
+
+/** Resolve logical focus from model identity; mount state is deliberately irrelevant. */
+export function resolveTimelineFocusIdentity(
+  elements: readonly TimelineElement[],
+  elementId: string | null,
+): TimelineFocusIdentity | null {
+  if (!elementId) return null;
+  const element = getTimelineElementIndexes(elements).byKey.get(elementId);
+  if (!element) return null;
+  return {
+    elementId,
+    rowKey: element.track,
+  };
+}

package/src/player/components/timelineLaneProps.ts

@@ -6,6 +6,9 @@ import type { TimelineKeyframeTarget } from "./timelineKeyframeIdentity";
 import type { TimelineTheme } from "./timelineTheme";
 import type { TrackVisualStyle } from "./timelineIcons";
 import type { DraggedClipState, ResizingClipState, BlockedClipState } from "./useTimelineClipDrag";
+import type { TimelineClipIndex, TimelineTimeRange } from "../lib/timelineClipIndex";
+import type { TimelineRowGeometry } from "./timelineLayout";
+import type { TimelineVirtualRow } from "./useTimelineVirtualRows";
 
 /**
  * Props shared by the scroll container ({@link import("./TimelineCanvas")}) and
@@ -22,6 +25,12 @@ export interface TimelineLaneBaseProps {
   theme: TimelineTheme;
   displayTrackOrder: number[];
   rowHeights: readonly number[];
+  rowGeometry: TimelineRowGeometry;
+  virtualRows: readonly TimelineVirtualRow[];
+  rowsVirtualized: boolean;
+  clipIndex: TimelineClipIndex;
+  renderTimeRange: TimelineTimeRange;
+  pinnedClipIdentities: ReadonlySet<string>;
   trackOrder: number[];
   tracks: [number, TimelineElement[]][];
   trackStyles: Map<number, TrackVisualStyle>;

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

@@ -15,9 +15,50 @@ import {
   getTimelineRowFromY,
   getTimelineRowOffsets,
   getTimelineCanvasHeight,
+  createTimelineRowGeometry,
+  getTimelineRowGeometry,
   trackHeights,
   resolveTimelineAssetDrop,
+  getTimelineBeatEntries,
 } from "./timelineLayout";
+import { generateTicks, getTimelineMajorTickInterval } from "./timelineRulerGeometry";
+import { getTimelineRenderTimeRange } from "./timelineViewportGeometry";
+
+describe("horizontal timeline window", () => {
+  it("adds the shared quarter-viewport overscan on each side and clamps to duration", () => {
+    expect(getTimelineRenderTimeRange({ scrollLeft: 300, clientWidth: 500 }, 100, 200, 20)).toEqual(
+      { start: 0, end: 7.25 },
+    );
+    expect(
+      getTimelineRenderTimeRange({ scrollLeft: 1_900, clientWidth: 500 }, 100, 200, 20),
+    ).toEqual({ start: 15.75, end: 20 });
+  });
+
+  it("generates globally aligned ticks directly inside the bounded window", () => {
+    const ticks = generateTicks(10_000, 100, undefined, { start: 500.2, end: 501.8 });
+    const interval = getTimelineMajorTickInterval(10_000, 100);
+    expect(ticks.major.every((time) => time >= 500.2 && time <= 501.8)).toBe(true);
+    expect(
+      ticks.major.every((time) => Math.abs(time / interval - Math.round(time / interval)) < 1e-6),
+    ).toBe(true);
+    expect(ticks.major.length + ticks.minor.length).toBeLessThan(100);
+  });
+
+  it("slices beat records with original strength indexes and unions a pinned beat", () => {
+    expect(
+      getTimelineBeatEntries(
+        [0, 1, 2, 3],
+        [0.1, 0.2, 0.3, 0.4],
+        { start: 1, end: 3 },
+        new Set([3]),
+      ),
+    ).toEqual([
+      { index: 1, time: 1, strength: 0.2 },
+      { index: 2, time: 2, strength: 0.3 },
+      { index: 3, time: 3, strength: 0.4 },
+    ]);
+  });
+});
 
 /** N collapsed rows, the shape every caller passes when nothing is expanded. */
 const baseRows = (count: number) => Array.from({ length: count }, () => TRACK_H);
@@ -64,6 +105,24 @@ describe("variable timeline row geometry", () => {
       RULER_H + TRACKS_TOP_PAD + 3 * TRACK_H + 2 * LANE_H + TRACKS_BOTTOM_PAD,
     );
   });
+
+  it("reuses one immutable geometry snapshot for one height array", () => {
+    const heights = trackHeights(tracks, new Set(["b"]));
+    const first = getTimelineRowGeometry(heights);
+    expect(getTimelineRowGeometry(heights)).toBe(first);
+    expect(Object.isFrozen(first)).toBe(true);
+    expect(Object.isFrozen(first.rowOffsets)).toBe(true);
+  });
+
+  it("looks up row boundaries through the precomputed geometry", () => {
+    const geometry = createTimelineRowGeometry([4, 8, 12], [48, 104, 76]);
+    expect(getTimelineRowGeometry(geometry.rowHeights)).toBe(geometry);
+    expect(geometry.getRowIndex(8)).toBe(1);
+    expect(geometry.getRowFromY(geometry.getRowTop(1))).toBe(1);
+    expect(geometry.getRowFromY(geometry.getRowTop(2) - 0.001)).toBeLessThan(2);
+    expect(geometry.getRowFromY(geometry.getRowTop(2))).toBe(2);
+    expect(geometry.canvasHeight).toBe(RULER_H + TRACKS_TOP_PAD + 228 + TRACKS_BOTTOM_PAD);
+  });
 });
 
 describe("collapsed timeline row geometry characterization", () => {