@hyperframes/studio 0.7.90 → 0.7.93

package/src/player/components/useTimelineKeyframeHandlers.ts

@@ -1,13 +1,475 @@
-import { useCallback, type MouseEvent as ReactMouseEvent } from "react";
+import {
+  useCallback,
+  type MouseEvent as ReactMouseEvent,
+  type PointerEvent as ReactPointerEvent,
+} from "react";
+import { clipToTweenPercentage } from "../../components/editor/KeyframeNavigation";
+import {
+  KEYFRAME_DRAG_THRESHOLD_PX,
+  previewClipPct,
+  resolveKeyframeDrag,
+} from "../../components/editor/keyframeDrag";
 import { trackStudioSegmentEaseEdit } from "../../telemetry/events";
+import type { AnimationKeyframeTarget } from "../../hooks/gsapTweenSynth";
 import type { TimelineElement, KeyframeCacheEntry } from "../store/playerStore";
 import { usePlayerStore } from "../store/playerStore";
 import type { KeyframeDiamondContextMenuState } from "./KeyframeDiamondContextMenu";
+import {
+  applyTimelineHorizontalAutoScrollStep,
+  resolveTimelineAutoScrollLoopAction,
+} from "./timelineEditing";
 import {
   timelineKeyframeSelectionKey,
   type TimelineKeyframeTarget,
 } from "./timelineKeyframeIdentity";
 
+interface TimelineRetimeKeyframe {
+  percentage: number;
+  tweenPercentage?: number;
+  propertyGroup?: string;
+  animationId?: string;
+  collidingAnimationTargets?: AnimationKeyframeTarget[];
+}
+
+interface TimelineKeyframeRetimeInput {
+  event: ReactPointerEvent<HTMLElement>;
+  elementId: string;
+  keyframeKey: string;
+  target: TimelineKeyframeTarget;
+  keyframes: readonly TimelineRetimeKeyframe[];
+  clipWidthPx: number;
+  draggedIndex: number;
+  sortedClipPercentages: readonly number[];
+  onMove: (target: TimelineKeyframeTarget, toClipPercentage: number) => Promise<boolean>;
+  onSelect: (target: TimelineKeyframeTarget, additive: boolean) => void;
+  suppressNextClick: () => void;
+  /**
+   * Selection key of a cache keyframe, used to retire a pending entry once the
+   * authoritative cache reflects THAT keyframe at its destination. Without it a
+   * bare "some keyframe is near that %" test retires the entry whenever an
+   * unrelated sibling happens to sit there, which is easy to hit on an evenly
+   * spaced row.
+   */
+  keyframeKeyOf: (keyframe: TimelineRetimeKeyframe) => string;
+}
+
+interface PendingTimelineKeyframeRetime {
+  elementId: string;
+  clipPercentage: number;
+  tweenPercentage: number;
+  destinationKeyframeKey: string;
+  sessionEpoch: number;
+}
+
+interface TimelineKeyframeRetimePreview {
+  keyframeKey: string;
+  clipPercentage: number;
+}
+
+interface TimelineKeyframeRetimeActor extends TimelineKeyframeRetimeInput {
+  phase: "active" | "committing" | "cancelled" | "complete";
+  pointerId: number | null;
+  pointerDownX: number;
+  lastClientX: number;
+  lastClientY: number;
+  originScrollLeft: number;
+  fromClipPercentage: number;
+  moved: boolean;
+  sessionEpoch: number;
+  sourceWasPresent: boolean;
+  scrollRaf: number;
+  unsubscribeStore: (() => void) | null;
+  teardownListeners: (() => void) | null;
+}
+
+interface TimelineKeyframeRetimeCoordinator {
+  actor: TimelineKeyframeRetimeActor | null;
+  pending: Map<string, PendingTimelineKeyframeRetime>;
+  preview: TimelineKeyframeRetimePreview | null;
+  previewListeners: Set<(preview: TimelineKeyframeRetimePreview | null) => void>;
+  /**
+   * The most recent retime dispatched through this viewport, whichever diamond
+   * it came from. Selection is viewport-wide, so "is my revert still relevant"
+   * is a viewport-wide question, not a per-keyframe one.
+   */
+  latest: PendingTimelineKeyframeRetime | null;
+}
+
+type TimelineRetimePointerEvent = Pick<
+  PointerEvent,
+  "clientX" | "clientY" | "pointerId" | "shiftKey"
+>;
+
+const keyframeRetimeCoordinators = new WeakMap<EventTarget, TimelineKeyframeRetimeCoordinator>();
+
+function getRetimeOwner(target: HTMLElement): EventTarget {
+  return target.closest<HTMLElement>("[data-timeline-scroll-viewport]") ?? target.ownerDocument;
+}
+
+function getRetimeCoordinator(owner: EventTarget): TimelineKeyframeRetimeCoordinator {
+  const existing = keyframeRetimeCoordinators.get(owner);
+  if (existing) return existing;
+  const coordinator: TimelineKeyframeRetimeCoordinator = {
+    actor: null,
+    pending: new Map(),
+    preview: null,
+    previewListeners: new Set(),
+    latest: null,
+  };
+  keyframeRetimeCoordinators.set(owner, coordinator);
+  return coordinator;
+}
+
+function stablePointerId(pointerId: number): number | null {
+  return Number.isFinite(pointerId) ? pointerId : null;
+}
+
+/**
+ * The retime destinations already dispatched from `source`'s viewport but not
+ * yet reflected in the keyframe cache. A renderer clamping a drag against its
+ * neighbours has to compose these in, or a second drag can cross a neighbour
+ * that already moved past it.
+ */
+export function readPendingTimelineKeyframeRetimes(
+  source: HTMLElement | null | undefined,
+): ReadonlyMap<string, { clipPercentage: number; tweenPercentage: number }> {
+  if (!source) return EMPTY_PENDING_RETIMES;
+  return keyframeRetimeCoordinators.get(getRetimeOwner(source))?.pending ?? EMPTY_PENDING_RETIMES;
+}
+
+const EMPTY_PENDING_RETIMES: ReadonlyMap<
+  string,
+  { clipPercentage: number; tweenPercentage: number }
+> = new Map();
+
+function publishRetimePreview(
+  coordinator: TimelineKeyframeRetimeCoordinator,
+  preview: TimelineKeyframeRetimePreview | null,
+): void {
+  coordinator.preview = preview;
+  for (const listener of coordinator.previewListeners) listener(preview);
+}
+
+export function subscribeTimelineKeyframeRetimePreview(
+  source: HTMLElement,
+  listener: (preview: TimelineKeyframeRetimePreview | null) => void,
+): () => void {
+  const coordinator = getRetimeCoordinator(getRetimeOwner(source));
+  coordinator.previewListeners.add(listener);
+  listener(coordinator.preview);
+  return () => coordinator.previewListeners.delete(listener);
+}
+
+function resolveRetimeTweenPercentage(
+  actor: TimelineKeyframeRetimeActor,
+  toClipPercentage: number,
+): number {
+  const animationKeyframes =
+    actor.target.animationId === undefined
+      ? actor.keyframes
+      : actor.keyframes.filter((keyframe) => keyframe.animationId === actor.target.animationId);
+  const tweenPercentages = animationKeyframes
+    .map((keyframe) => keyframe.tweenPercentage)
+    .filter((value): value is number => typeof value === "number");
+  const mapped = clipToTweenPercentage(animationKeyframes, toClipPercentage);
+  if (tweenPercentages.length === 0) return mapped;
+  return Math.max(Math.min(...tweenPercentages), Math.min(Math.max(...tweenPercentages), mapped));
+}
+
+export interface TimelineKeyframeRetimeHandle {
+  update: (event: ReactPointerEvent<HTMLElement>) => void;
+  commit: (event: ReactPointerEvent<HTMLElement>) => void;
+  cancel: (event: ReactPointerEvent<HTMLElement>) => void;
+}
+
+/**
+ * Starts a keyframe retime on the stable timeline viewport. The row/button is
+ * only an entry point: window listeners own the gesture through virtualization.
+ */
+export function beginTimelineKeyframeRetime(
+  input: TimelineKeyframeRetimeInput,
+): TimelineKeyframeRetimeHandle {
+  const source = input.event.currentTarget;
+  const owner = getRetimeOwner(source);
+  const viewport = owner instanceof HTMLElement ? owner : null;
+  const coordinator = getRetimeCoordinator(owner);
+  const sessionEpoch = usePlayerStore.getState().timelineSessionEpoch;
+
+  const cancel = (actor: TimelineKeyframeRetimeActor) => {
+    if (actor.phase !== "active") return;
+    actor.phase = "cancelled";
+    publishRetimePreview(coordinator, null);
+    if (actor.scrollRaf) cancelAnimationFrame(actor.scrollRaf);
+    actor.unsubscribeStore?.();
+    actor.teardownListeners?.();
+    if (viewport && actor.pointerId !== null) {
+      try {
+        viewport.releasePointerCapture(actor.pointerId);
+      } catch {
+        // Window listeners remain the native fallback when capture is unavailable.
+      }
+    }
+    if (coordinator.actor === actor) {
+      coordinator.actor = null;
+    }
+    actor.phase = "complete";
+  };
+
+  if (coordinator.actor) cancel(coordinator.actor);
+
+  for (const [key, pending] of coordinator.pending) {
+    if (pending.sessionEpoch !== sessionEpoch) coordinator.pending.delete(key);
+  }
+
+  for (const [key, pending] of coordinator.pending) {
+    // Tolerance, not equality: cache writers round clip %s, so an exact check
+    // would leak an entry after every successful retime.
+    if (
+      pending.elementId === input.elementId &&
+      input.keyframes.some(
+        (keyframe) =>
+          input.keyframeKeyOf(keyframe) === pending.destinationKeyframeKey &&
+          Math.abs(keyframe.percentage - pending.clipPercentage) < 0.2,
+      )
+    ) {
+      coordinator.pending.delete(key);
+    }
+  }
+
+  const pending = coordinator.pending.get(input.keyframeKey);
+  const actor: TimelineKeyframeRetimeActor = {
+    ...input,
+    phase: "active",
+    pointerId: stablePointerId(input.event.pointerId),
+    pointerDownX: input.event.clientX,
+    lastClientX: input.event.clientX,
+    lastClientY: input.event.clientY,
+    originScrollLeft: viewport?.scrollLeft ?? 0,
+    fromClipPercentage: pending?.clipPercentage ?? input.target.percentage,
+    moved: false,
+    sessionEpoch,
+    sourceWasPresent: usePlayerStore
+      .getState()
+      .elements.some((element) => (element.key ?? element.id) === input.elementId),
+    scrollRaf: 0,
+    unsubscribeStore: null,
+    teardownListeners: null,
+  };
+  coordinator.actor = actor;
+
+  const matchesPointer = (event: TimelineRetimePointerEvent) =>
+    actor.pointerId === null || event.pointerId === actor.pointerId;
+  const pointerXWithScroll = () =>
+    actor.lastClientX + (viewport?.scrollLeft ?? 0) - actor.originScrollLeft;
+  const publishPreview = () => {
+    publishRetimePreview(coordinator, {
+      keyframeKey: actor.keyframeKey,
+      clipPercentage: previewClipPct({
+        pointerDownX: actor.pointerDownX,
+        pointerMoveX: pointerXWithScroll(),
+        clipWidthPx: actor.clipWidthPx,
+        draggedClipPct: actor.fromClipPercentage,
+        draggedIndex: actor.draggedIndex,
+        sortedClipPcts: actor.sortedClipPercentages,
+      }),
+    });
+  };
+  const stopAutoScroll = () => {
+    if (actor.scrollRaf) cancelAnimationFrame(actor.scrollRaf);
+    actor.scrollRaf = 0;
+  };
+  const stepAutoScroll = () => {
+    actor.scrollRaf = 0;
+    if (
+      actor.phase !== "active" ||
+      !viewport ||
+      !applyTimelineHorizontalAutoScrollStep(viewport, actor.lastClientX)
+    ) {
+      return;
+    }
+    publishPreview();
+    actor.scrollRaf = requestAnimationFrame(stepAutoScroll);
+  };
+  const syncAutoScroll = () => {
+    if (!viewport || !actor.moved) return;
+    const action = resolveTimelineAutoScrollLoopAction(
+      viewport,
+      actor.lastClientX,
+      actor.lastClientY,
+      actor.scrollRaf !== 0,
+    );
+    if (action === "stop") stopAutoScroll();
+    else if (action === "start") actor.scrollRaf = requestAnimationFrame(stepAutoScroll);
+  };
+  const teardown = () => {
+    stopAutoScroll();
+    actor.unsubscribeStore?.();
+    actor.unsubscribeStore = null;
+    actor.teardownListeners?.();
+    actor.teardownListeners = null;
+  };
+  const releaseCapture = () => {
+    if (!viewport || actor.pointerId === null) return;
+    try {
+      viewport.releasePointerCapture(actor.pointerId);
+    } catch {
+      // Capture may already have been released by the browser.
+    }
+  };
+
+  const claimActorForCommit = (event: TimelineRetimePointerEvent): boolean => {
+    if (actor.phase !== "active" || !matchesPointer(event)) return false;
+    if (actor.sessionEpoch !== usePlayerStore.getState().timelineSessionEpoch) {
+      cancel(actor);
+      return false;
+    }
+    actor.phase = "committing";
+    actor.lastClientX = event.clientX;
+    actor.lastClientY = event.clientY;
+    teardown();
+    releaseCapture();
+    publishRetimePreview(coordinator, null);
+    if (coordinator.actor === actor) {
+      coordinator.actor = null;
+    }
+    actor.suppressNextClick();
+    return true;
+  };
+
+  const commitMove = (toClipPercentage: number) => {
+    const newTweenPercentage = resolveRetimeTweenPercentage(actor, toClipPercentage);
+    const pendingBefore = coordinator.pending.get(actor.keyframeKey);
+    const fromTarget = pendingBefore
+      ? {
+          ...actor.target,
+          percentage: pendingBefore.clipPercentage,
+          tweenPercentage: pendingBefore.tweenPercentage,
+        }
+      : actor.target;
+    const nextPending = {
+      elementId: actor.elementId,
+      clipPercentage: toClipPercentage,
+      tweenPercentage: newTweenPercentage,
+      destinationKeyframeKey: timelineKeyframeSelectionKey(actor.elementId, {
+        ...actor.target,
+        percentage: toClipPercentage,
+        tweenPercentage: newTweenPercentage,
+      }),
+      sessionEpoch: actor.sessionEpoch,
+    };
+    coordinator.pending.set(actor.keyframeKey, nextPending);
+    coordinator.latest = nextPending;
+    const clearPending = () => {
+      if (coordinator.pending.get(actor.keyframeKey) === nextPending) {
+        coordinator.pending.delete(actor.keyframeKey);
+      }
+    };
+    // A rejected drop (the destination time is already occupied) snaps the
+    // diamond back to its source position, so the pending entry AND the
+    // selection have to revert with it: parking on the ghost drop position
+    // strands the playhead + selection on a keyframe that is not there.
+    const revertRetime = () => {
+      // Only the newest gesture owns the selection. A rejected first drag
+      // whose commit settles after a second one started would otherwise park
+      // the selection back on ITS source keyframe, undoing a retime the user
+      // has already made and moving the playhead with it.
+      const isLatest = coordinator.latest === nextPending;
+      clearPending();
+      if (isLatest) actor.onSelect(fromTarget, false);
+    };
+    void actor.onMove(fromTarget, toClipPercentage).then((committed) => {
+      if (!committed) revertRetime();
+    }, revertRetime);
+    actor.onSelect(
+      {
+        ...actor.target,
+        percentage: toClipPercentage,
+        tweenPercentage: newTweenPercentage,
+      },
+      false,
+    );
+  };
+
+  const finishCommit = (event: TimelineRetimePointerEvent) => {
+    if (!claimActorForCommit(event)) return;
+    const result = resolveKeyframeDrag({
+      pointerDownX: actor.pointerDownX,
+      pointerUpX: pointerXWithScroll(),
+      clipWidthPx: actor.clipWidthPx,
+      draggedClipPct: actor.fromClipPercentage,
+      draggedIndex: actor.draggedIndex,
+      sortedClipPcts: actor.sortedClipPercentages,
+    });
+    if (result.kind === "move" && result.toClipPct !== undefined) {
+      commitMove(result.toClipPct);
+    } else {
+      actor.onSelect(actor.target, event.shiftKey);
+    }
+    actor.phase = "complete";
+  };
+  const onPointerMove = (event: TimelineRetimePointerEvent) => {
+    if (actor.phase !== "active" || !matchesPointer(event)) return;
+    actor.lastClientX = event.clientX;
+    actor.lastClientY = event.clientY;
+    if (
+      !actor.moved &&
+      Math.abs(pointerXWithScroll() - actor.pointerDownX) >= KEYFRAME_DRAG_THRESHOLD_PX
+    ) {
+      actor.moved = true;
+    }
+    if (actor.moved) publishPreview();
+    syncAutoScroll();
+  };
+  const onPointerUp = (event: TimelineRetimePointerEvent) => finishCommit(event);
+  const onPointerCancel = (event: TimelineRetimePointerEvent) => {
+    if (actor.phase === "active" && matchesPointer(event)) cancel(actor);
+  };
+  const onLostPointerCapture = (event: PointerEvent) => {
+    if (actor.phase === "active" && matchesPointer(event)) cancel(actor);
+  };
+  const onKeyDown = (event: KeyboardEvent) => {
+    if (event.key === "Escape") cancel(actor);
+  };
+
+  window.addEventListener("pointermove", onPointerMove, true);
+  window.addEventListener("pointerup", onPointerUp, true);
+  window.addEventListener("pointercancel", onPointerCancel, true);
+  window.addEventListener("keydown", onKeyDown);
+  viewport?.addEventListener("lostpointercapture", onLostPointerCapture);
+  actor.teardownListeners = () => {
+    window.removeEventListener("pointermove", onPointerMove, true);
+    window.removeEventListener("pointerup", onPointerUp, true);
+    window.removeEventListener("pointercancel", onPointerCancel, true);
+    window.removeEventListener("keydown", onKeyDown);
+    viewport?.removeEventListener("lostpointercapture", onLostPointerCapture);
+  };
+  actor.unsubscribeStore = usePlayerStore.subscribe((state) => {
+    const sourceStillPresent = state.elements.some(
+      (element) => (element.key ?? element.id) === actor.elementId,
+    );
+    if (state.timelineSessionEpoch !== actor.sessionEpoch) {
+      coordinator.pending.clear();
+      coordinator.latest = null;
+      cancel(actor);
+    } else if (actor.sourceWasPresent && !sourceStillPresent) {
+      for (const [key, pending] of coordinator.pending) {
+        if (pending.elementId === actor.elementId) coordinator.pending.delete(key);
+      }
+      if (coordinator.latest?.elementId === actor.elementId) coordinator.latest = null;
+      cancel(actor);
+    }
+  });
+
+  if (viewport && actor.pointerId !== null) {
+    try {
+      viewport.setPointerCapture(actor.pointerId);
+    } catch {
+      // Window listeners are the native fallback when capture is unavailable.
+    }
+  }
+  return { update: onPointerMove, commit: onPointerUp, cancel: onPointerCancel };
+}
+
 interface UseTimelineKeyframeHandlersInput {
   expandedElements: TimelineElement[];
   keyframeCache: Map<string, KeyframeCacheEntry>;
@@ -88,12 +550,13 @@ export function useTimelineKeyframeHandlers({
       setKfContextMenu({
         x: e.clientX + 4,
         y: e.clientY + 2,
+        sessionEpoch: usePlayerStore.getState().timelineSessionEpoch,
+        element: el,
         elementId: elId,
         percentage: target.percentage,
         tweenPercentage: target.tweenPercentage ?? kf?.tweenPercentage,
         propertyGroup: target.propertyGroup,
         animationId: target.animationId,
-        element: el,
         currentEase: kf?.ease ?? kfData?.ease,
       });
     },

package/src/player/components/useTimelineLaneMoveRefresh.ts

@@ -0,0 +1,7 @@
+import { useCallback } from "react";
+import { useStudioPlaybackContextOptional } from "../../contexts/StudioContext";
+
+export function useTimelineLaneMoveRefresh(): () => void {
+  const setRefreshKey = useStudioPlaybackContextOptional()?.setRefreshKey;
+  return useCallback(() => setRefreshKey?.((key) => key + 1), [setRefreshKey]);
+}

package/src/player/components/useTimelineLogicalFocus.ts

@@ -0,0 +1,80 @@
+import type { RefObject } from "react";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { TimelineElement } from "../store/playerStore";
+import type { TimelineRowGeometry } from "./timelineLayout";
+import type { TimelineScrollViewportSnapshot } from "./useTimelineScrollViewport";
+import { useTimelineFocusCoordinator } from "./useTimelineFocusCoordinator";
+import { usePlayerStore } from "../store/playerStore";
+import { useTimelineLogicalRows } from "./useTimelineLogicalRows";
+import { useTimelineRowVirtualization } from "./useTimelineRowVirtualization";
+
+interface TimelineLogicalFocusInput {
+  scrollRef: RefObject<HTMLDivElement | null>;
+  tracks: readonly (readonly [number, readonly TimelineElement[]])[];
+  layout: { displayTrackOrder: readonly number[]; rowGeometry: TimelineRowGeometry };
+  laneCounts: ReadonlyMap<string, number>;
+  selectedElementId: string | null;
+  selectedElementIds: ReadonlySet<string>;
+  gsapAnimations: ReadonlyMap<string, readonly GsapAnimation[]>;
+  elements: readonly TimelineElement[];
+  pixelsPerSecond: number;
+  contentOrigin: number;
+  allowHorizontal: boolean;
+  viewport: TimelineScrollViewportSnapshot;
+  sessionEpoch: number;
+  draggedRowKey?: number;
+  resizingElementIds?: readonly string[];
+  clipContextMenuRowKey?: number;
+  keyframeContextMenuRowKey?: number;
+  lastScrollLeftRef: RefObject<number>;
+  syncScrollViewport: (element: HTMLDivElement) => void;
+}
+
+export function useTimelineLogicalFocus(input: TimelineLogicalFocusInput) {
+  const expandedClipIds = usePlayerStore((state) => state.expandedClipIds);
+  const projectId = usePlayerStore((state) => state.timelineProjectId);
+  const logicalRows = useTimelineLogicalRows({
+    tracks: input.tracks,
+    displayTrackOrder: input.layout.displayTrackOrder,
+    laneCounts: input.laneCounts,
+    selectedElementId: input.selectedElementId,
+    selectedElementIds: input.selectedElementIds,
+    expandedClipIds,
+    gsapAnimations: input.gsapAnimations,
+  });
+  const focus = useTimelineFocusCoordinator({
+    scrollRef: input.scrollRef,
+    logicalRows,
+    elements: input.elements,
+    rowGeometry: input.layout.rowGeometry,
+    pixelsPerSecond: input.pixelsPerSecond,
+    contentOrigin: input.contentOrigin,
+    allowHorizontal: input.allowHorizontal,
+    viewportVersion: input.viewport,
+    projectId,
+    sessionEpoch: input.sessionEpoch,
+    syncScrollViewport: input.syncScrollViewport,
+  });
+  const rows = useTimelineRowVirtualization({
+    scrollRef: input.scrollRef,
+    viewport: input.viewport,
+    rowGeometry: input.layout.rowGeometry,
+    sessionEpoch: input.sessionEpoch,
+    elements: input.elements,
+    selectedElementId: input.selectedElementId,
+    focusedRowKey: focus.focusedRowKey,
+    draggedRowKey: input.draggedRowKey,
+    resizingElementIds: input.resizingElementIds,
+    clipContextMenuRowKey: input.clipContextMenuRowKey,
+    keyframeContextMenuRowKey: input.keyframeContextMenuRowKey,
+    lastScrollLeftRef: input.lastScrollLeftRef,
+    syncScrollViewport: input.syncScrollViewport,
+  });
+  return {
+    logicalRows,
+    ...focus,
+    rowVirtualizationActive: rows.enabled,
+    virtualRows: rows.virtualRows,
+    timelineFocusProps: rows.timelineFocusProps,
+  };
+}

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

@@ -0,0 +1,57 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import { usePlayerStore } from "../store/playerStore";
+import type { TimelineLogicalRow } from "./timelineKeyboardNavigation";
+import { useTimelineLogicalRows } from "./useTimelineLogicalRows";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const tracks = Array.from(
+  { length: 1_000 },
+  (_, track) =>
+    [
+      track,
+      [{ id: `clip-${track}`, tag: "div", track, start: track, duration: 1 }],
+    ] as const satisfies readonly [number, readonly TimelineElement[]],
+);
+const displayTrackOrder = tracks.map(([track]) => track);
+const laneCounts = new Map<string, number>();
+const selectedElementIds = new Set<string>();
+const expandedClipIds = new Set<string>();
+const gsapAnimations = new Map();
+
+function Harness({ snapshots }: { snapshots: Array<readonly TimelineLogicalRow[]> }) {
+  usePlayerStore((state) => state.requestedSeekTime);
+  const logicalRows = useTimelineLogicalRows({
+    tracks,
+    displayTrackOrder,
+    laneCounts,
+    selectedElementId: null,
+    selectedElementIds,
+    expandedClipIds,
+    gsapAnimations,
+  });
+  snapshots.push(logicalRows);
+  return null;
+}
+
+afterEach(() => usePlayerStore.getState().reset());
+
+describe("useTimelineLogicalRows", () => {
+  it("preserves the dense logical model across an unrelated store update", () => {
+    const host = document.createElement("div");
+    const root = createRoot(host);
+    const snapshots: Array<readonly TimelineLogicalRow[]> = [];
+    act(() => root.render(<Harness snapshots={snapshots} />));
+    const first = snapshots.at(-1);
+
+    act(() => usePlayerStore.setState({ requestedSeekTime: 1 }));
+
+    expect(snapshots.at(-1)).toBe(first);
+    act(() => root.unmount());
+  });
+});

package/src/player/components/useTimelineLogicalRows.ts

@@ -0,0 +1,47 @@
+import { useMemo } from "react";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { TimelineElement } from "../store/playerStore";
+import { buildTimelineLogicalRows } from "./timelineKeyboardNavigation";
+
+interface TimelineLogicalRowsInput {
+  tracks: readonly (readonly [number, readonly TimelineElement[]])[];
+  displayTrackOrder: readonly number[];
+  laneCounts: ReadonlyMap<string, number>;
+  selectedElementId: string | null;
+  selectedElementIds: ReadonlySet<string>;
+  expandedClipIds: ReadonlySet<string>;
+  gsapAnimations: ReadonlyMap<string, readonly GsapAnimation[]>;
+}
+
+/** Shared by rendering and focus coordination; stable input refs preserve memo identity. */
+export function useTimelineLogicalRows({
+  tracks,
+  displayTrackOrder,
+  laneCounts,
+  selectedElementId,
+  selectedElementIds,
+  expandedClipIds,
+  gsapAnimations,
+}: TimelineLogicalRowsInput) {
+  return useMemo(
+    () =>
+      buildTimelineLogicalRows({
+        tracks,
+        displayTrackOrder,
+        laneCounts,
+        selectedElementId,
+        selectedElementIds,
+        expandedClipIds,
+        gsapAnimations,
+      }),
+    [
+      displayTrackOrder,
+      expandedClipIds,
+      gsapAnimations,
+      laneCounts,
+      selectedElementId,
+      selectedElementIds,
+      tracks,
+    ],
+  );
+}