@hyperframes/studio 0.7.90 → 0.7.92

package/src/player/components/TimelineClipDiamonds.tsx

@@ -1,21 +1,20 @@
 import { memo, useEffect, useRef, useState } from "react";
 import { BEAT_BAND_H } from "./BeatStrip";
-import {
-  KEYFRAME_DRAG_THRESHOLD_PX,
-  previewClipPct,
-  resolveKeyframeDrag,
-} from "../../components/editor/keyframeDrag";
 import { TimelineDiamondConnectors } from "./TimelineDiamondConnectors";
-import { clipToTweenPercentage } from "../../components/editor/KeyframeNavigation";
 import { LANE_H } from "./timelineLayout";
 import { STUDIO_PREVIEW_FPS } from "../lib/time";
 import { timelineKeyframeSelectionKey } from "./timelineKeyframeIdentity";
+import {
+  beginTimelineKeyframeRetime,
+  readPendingTimelineKeyframeRetimes,
+  subscribeTimelineKeyframeRetimePreview,
+  type TimelineKeyframeRetimeHandle,
+} from "./useTimelineKeyframeHandlers";
 import {
   DIAMOND_RATIO,
   KF_MAX_PCT,
   KF_MIN_PCT,
   keyframeTarget,
-  type DragState,
   type TimelineClipDiamondsProps,
   type TimelineDiamondKeyframe,
   type TimelineDiamondLaneProps,
@@ -86,65 +85,29 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
   globalEase = "none",
 }: TimelineDiamondLaneProps) {
   // Hooks must run before the early return below.
-  const dragRef = useRef<DragState | null>(null);
-  // Pending retime destination (clip + tween %) per keyframe key, so a rapid
-  // second drag composes from where the first move left the keyframe (whose
-  // cache entry has not rebuilt yet) instead of the stale rendered value.
-  const pendingRetimeRef = useRef<Map<string, { clipPct: number; tweenPct: number }> | null>(null);
-  // Lazy: `useRef(new Map())` allocates a Map on every render and throws all but
-  // the first away, once per mounted lane.
-  pendingRetimeRef.current ??= new Map();
-  const pendingRetimes = pendingRetimeRef.current;
-  // The most recent retime dispatched from this lane, whichever diamond it came
-  // from. Selection is lane-wide, so "is my revert still relevant" is a lane-wide
-  // question, not a per-keyframe one.
-  const latestRetimeRef = useRef<{ clipPct: number; tweenPct: number } | null>(null);
-  useEffect(() => {
-    // Clear a pending entry once the authoritative cache reflects THAT keyframe
-    // at ~its destination. Match by tolerance, not equality: cache writers round
-    // clip %s, so an exact check would leak an entry after every successful
-    // retime. Match by identity too: a bare "some keyframe is near that %" test
-    // cleared the entry whenever an unrelated sibling happened to sit there,
-    // which is easy to hit on an evenly spaced row.
-    const pendingEntries = pendingRetimeRef.current;
-    if (!pendingEntries) return;
-    for (const [key, pending] of pendingEntries) {
-      const settled = keyframesData.keyframes.some(
-        (k) =>
-          timelineKeyframeSelectionKey(elementId, keyframeTarget(k)) === key &&
-          Math.abs(k.percentage - pending.clipPct) < 0.2,
-      );
-      if (settled) pendingEntries.delete(key);
-    }
-  }, [keyframesData.keyframes, elementId]);
+  // The retime itself lives on the stable scroll viewport (beginTimelineKeyframeRetime),
+  // so a row unmounted by virtualization mid-drag does not drop the gesture.
+  // This lane only arms it and renders the preview it publishes.
+  const rootRef = useRef<HTMLDivElement>(null);
+  const retimeHandleRef = useRef<TimelineKeyframeRetimeHandle | null>(null);
+  // Retime destinations already dispatched but not yet in the keyframe cache, so
+  // a rapid second drag composes from where the first move left the keyframe
+  // instead of the stale rendered value.
+  const pendingRetimes = readPendingTimelineKeyframeRetimes(rootRef.current);
   // Visual-only preview of the dragged diamond's clip-% — no runtime/GSAP hold
   // (that optimistic hold was the #1763 flake). The atomic move-keyframe commit
   // on drop re-keys the diamond from source.
   const [preview, setPreview] = useState<{ kfKey: string; clipPct: number } | null>(null);
-  // One preview render per frame: a 120Hz trackpad fires pointermove far faster
-  // than the lane can repaint, and every diamond in the row re-evaluates its
-  // memo on each of those renders.
-  const previewFrameRef = useRef<number | null>(null);
-  const cancelPreviewFrame = () => {
-    if (previewFrameRef.current === null) return;
-    cancelAnimationFrame(previewFrameRef.current);
-    previewFrameRef.current = null;
-  };
-  // Escape backs out of an in-flight retime, the way clip and element drags
-  // already do. Nothing was written yet (the commit happens on pointerup), so
-  // dropping the preview is the whole undo.
   useEffect(() => {
-    const onKeyDown = (event: KeyboardEvent) => {
-      if (event.key !== "Escape" || !dragRef.current || dragRef.current.cancelled) return;
-      dragRef.current.cancelled = true;
-      cancelPreviewFrame();
-      setPreview(null);
-    };
-    document.addEventListener("keydown", onKeyDown);
-    return () => {
-      document.removeEventListener("keydown", onKeyDown);
-      cancelPreviewFrame();
-    };
+    const source = rootRef.current;
+    if (!source) return;
+    return subscribeTimelineKeyframeRetimePreview(source, (nextPreview) => {
+      setPreview(
+        nextPreview === null
+          ? null
+          : { kfKey: nextPreview.keyframeKey, clipPct: nextPreview.clipPercentage },
+      );
+    });
   }, []);
   // The button element can re-render (reposition/unmount) synchronously from
   // the state updates onClickKeyframe/onMoveKeyframe trigger, before the
@@ -197,7 +160,7 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
   // O(keyframes squared) allocations on every playhead tick.
   const pendingClipPctOf = (keyframe: TimelineDiamondKeyframe) =>
     pendingRetimes.get(timelineKeyframeSelectionKey(elementId, keyframeTarget(keyframe)))
-      ?.clipPct ?? keyframe.percentage;
+      ?.clipPercentage ?? keyframe.percentage;
   const siblingRows = new Map<
     string | undefined,
     { keyframes: TimelineDiamondKeyframe[]; clipPcts: number[] }
@@ -247,6 +210,7 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
 
   return (
     <div
+      ref={rootRef}
       className="absolute inset-0"
       style={{
         // Above the clip's trim-handle strips (TimelineClip.tsx, z-index 4) so
@@ -294,150 +258,43 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
         const onPointerDown = (e: React.PointerEvent<HTMLButtonElement>) => {
           if (e.button !== 0) return;
           e.stopPropagation();
-          if (canDrag) {
-            e.currentTarget.setPointerCapture?.(e.pointerId);
-            dragRef.current = {
-              kfKey,
-              startX: e.clientX,
-              lastX: e.clientX,
-              index: siblingIndex,
-              fromClipPct: pendingRetimes.get(kfKey)?.clipPct ?? kf.percentage,
-              moved: false,
-            };
-          }
-        };
-        const onPointerMove = (e: React.PointerEvent<HTMLButtonElement>) => {
-          const d = dragRef.current;
-          if (!d || d.kfKey !== kfKey || d.cancelled) return;
-          d.lastX = e.clientX;
-          if (!d.moved && Math.abs(e.clientX - d.startX) >= KEYFRAME_DRAG_THRESHOLD_PX) {
-            d.moved = true;
-          }
-          if (!d.moved || previewFrameRef.current !== null) return;
-          previewFrameRef.current = requestAnimationFrame(() => {
-            previewFrameRef.current = null;
-            const live = dragRef.current;
-            if (!live || live.kfKey !== kfKey || live.cancelled) return;
-            setPreview({
-              kfKey,
-              clipPct: previewClipPct({
-                pointerDownX: live.startX,
-                pointerMoveX: live.lastX,
-                clipWidthPx,
-                draggedClipPct: live.fromClipPct,
-                draggedIndex: live.index,
-                sortedClipPcts: siblingClipPcts,
-              }),
-            });
+          if (!canDrag) return;
+          retimeHandleRef.current = beginTimelineKeyframeRetime({
+            event: e,
+            elementId,
+            keyframeKey: kfKey,
+            target,
+            keyframes: keyframesData.keyframes,
+            clipWidthPx,
+            // Clamp against this keyframe's own tween, not the whole merged row:
+            // a merged row interleaves several animations, and two colliding at
+            // one percentage would otherwise pin each other's diamonds in place.
+            draggedIndex: siblingIndex,
+            sortedClipPercentages: siblingClipPcts,
+            keyframeKeyOf: (keyframe) =>
+              timelineKeyframeSelectionKey(elementId, keyframeTarget(keyframe)),
+            onMove: (fromTarget, toClipPercentage) =>
+              onMoveKeyframe?.(fromTarget, toClipPercentage) ?? Promise.resolve(false),
+            onSelect: (nextTarget, additive) => {
+              if (additive) onShiftClickKeyframe?.(nextTarget);
+              else onClickKeyframe?.(nextTarget);
+            },
+            suppressNextClick,
           });
         };
         const onPointerUp = (e: React.PointerEvent<HTMLButtonElement>) => {
-          const d = dragRef.current;
-          if (d?.kfKey === kfKey && d.cancelled) {
-            // Escape already ended this drag; the release is not a click.
-            dragRef.current = null;
-            e.currentTarget.releasePointerCapture?.(e.pointerId);
-            suppressNextClick();
-            return;
-          }
-          // No drag armed (canDrag false / non-primary press) → treat as a click.
-          if (!d || d.kfKey !== kfKey) {
-            if (e.button !== 0) return;
-            suppressNextClick();
-            if (e.shiftKey) onShiftClickKeyframe?.(target);
-            else onClickKeyframe?.(target);
+          // The viewport coordinator owns an armed retime; this local path is
+          // only for diamonds that cannot be dragged.
+          if (canDrag) {
+            retimeHandleRef.current?.commit(e);
+            retimeHandleRef.current = null;
+            e.stopPropagation();
             return;
           }
-          e.stopPropagation();
-          dragRef.current = null;
-          cancelPreviewFrame();
-          setPreview(null);
-          e.currentTarget.releasePointerCapture?.(e.pointerId);
+          if (e.button !== 0) return;
           suppressNextClick();
-          // Single-diamond retime by design: a multi-select drag would have to
-          // move every selected keyframe as one mutation, which the script ops
-          // do not express yet. Selecting several and dragging one moves only
-          // the dragged one.
-          const res = resolveKeyframeDrag({
-            pointerDownX: d.startX,
-            pointerUpX: e.clientX,
-            clipWidthPx,
-            draggedClipPct: d.fromClipPct,
-            draggedIndex: siblingIndex,
-            sortedClipPcts: siblingClipPcts,
-          });
-          if (res.kind === "click" || res.kind === "noop") {
-            // "noop" is a press with enough pointer jitter to arm a drag (canDrag
-            // is on for every diamond once the clip is selected) that resolved
-            // back onto ~the same position — no real retime, so treat it as the
-            // click it was. Otherwise a normal click with a few px of mouse/
-            // trackpad drift silently does nothing: no selection, no move.
-            if (e.shiftKey) onShiftClickKeyframe?.(target);
-            else onClickKeyframe?.(target);
-          } else if (res.kind === "move" && res.toClipPct != null) {
-            const animKfs =
-              target.animationId === undefined
-                ? keyframesData.keyframes
-                : keyframesData.keyframes.filter((k) => k.animationId === target.animationId);
-            // Clamp to the mapped tween range: clipToTweenPercentage extrapolates
-            // linearly, so a boundary drag past the range would otherwise reselect
-            // an out-of-range tween % (e.g. 150%) even though the mutation clamps
-            // the moved endpoint back to the boundary.
-            const tweenPcts = animKfs
-              .map((k) => k.tweenPercentage)
-              .filter((v): v is number => typeof v === "number");
-            const clampTween = (v: number) =>
-              tweenPcts.length
-                ? Math.max(Math.min(...tweenPcts), Math.min(Math.max(...tweenPcts), v))
-                : v;
-            const newTweenPct = clampTween(clipToTweenPercentage(animKfs, res.toClipPct));
-            // For a rapid second retime the diamond still renders the stale cache
-            // position, so identify the FROM keyframe by the pending (already-moved)
-            // position; the mutation locates the source keyframe by this identity.
-            const pendingBefore = pendingRetimes.get(kfKey);
-            const fromTarget = pendingBefore
-              ? {
-                  ...target,
-                  percentage: pendingBefore.clipPct,
-                  tweenPercentage: pendingBefore.tweenPct,
-                }
-              : target;
-            const pending = { clipPct: res.toClipPct, tweenPct: newTweenPct };
-            pendingRetimes.set(kfKey, pending);
-            latestRetimeRef.current = pending;
-            const clearPending = () => {
-              if (pendingRetimes.get(kfKey) === pending) {
-                pendingRetimes.delete(kfKey);
-              }
-            };
-            // 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 does
-            // not exist 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 = latestRetimeRef.current === pending;
-              clearPending();
-              if (isLatest) onClickKeyframe?.(fromTarget);
-            };
-            void onMoveKeyframe?.(fromTarget, res.toClipPct).then((committed) => {
-              if (!committed) revertRetime();
-            }, revertRetime);
-            // A retime still targeted this exact diamond — park/select it at its
-            // new position, same as a plain click, or a drag that actually moved
-            // something looks identical to one that silently did nothing. Done
-            // optimistically so the gesture stays responsive; revertRetime puts
-            // it back if the move is rejected.
-            onClickKeyframe?.({
-              ...target,
-              percentage: res.toClipPct,
-              tweenPercentage: newTweenPct,
-            });
-          }
+          if (e.shiftKey) onShiftClickKeyframe?.(target);
+          else onClickKeyframe?.(target);
         };
 
         return (
@@ -476,18 +333,16 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
               overflow: "visible",
             }}
             onPointerDown={onPointerDown}
-            onPointerMove={onPointerMove}
+            onPointerMove={canDrag ? (e) => retimeHandleRef.current?.update(e) : undefined}
             onPointerUp={onPointerUp}
-            onPointerCancel={(e) => {
-              // Browser/OS cancellation (or lost capture) ends the drag without a
-              // pointerup, so clear the armed drag and preview or a ghost diamond
-              // stays stuck at the last previewed position.
-              if (dragRef.current?.kfKey !== kfKey) return;
-              dragRef.current = null;
-              cancelPreviewFrame();
-              setPreview(null);
-              e.currentTarget.releasePointerCapture?.(e.pointerId);
-            }}
+            onPointerCancel={
+              canDrag
+                ? (e) => {
+                    retimeHandleRef.current?.cancel(e);
+                    retimeHandleRef.current = null;
+                  }
+                : undefined
+            }
             onContextMenu={(e) => {
               e.preventDefault();
               e.stopPropagation();

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

@@ -0,0 +1,90 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import { defaultTimelineTheme } from "./timelineTheme";
+import { TimelineGestureOverlay } from "./TimelineGestureOverlay";
+import type { DraggedClipState } from "./timelineClipDragTypes";
+import { getTrackStyle } from "./useTimelineTrackLayout";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const drag: DraggedClipState = {
+  pointerId: 0,
+  element: { id: "hero", tag: "div", start: 2, duration: 3, track: 1 },
+  originClientX: 100,
+  originClientY: 100,
+  originScrollLeft: 0,
+  originScrollTop: 0,
+  pointerClientX: 350,
+  pointerClientY: 240,
+  pointerOffsetX: 20,
+  pointerOffsetY: 10,
+  previewStart: 4,
+  previewTrack: 2,
+  insertRow: null,
+  snapTime: null,
+  snapType: null,
+  started: true,
+};
+
+afterEach(() => document.body.replaceChildren());
+
+describe("TimelineGestureOverlay", () => {
+  it("keeps the drag actor mounted without a source-row node", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    const scroll = {
+      scrollLeft: 500,
+      scrollTop: 300,
+      getBoundingClientRect: () => ({ left: 50, top: 40 }),
+    } as HTMLDivElement;
+    act(() => {
+      root.render(
+        <TimelineGestureOverlay
+          drag={drag}
+          scrollRef={{ current: scroll }}
+          pixelsPerSecond={100}
+          rowHeight={42}
+          selectedElementId="hero"
+          currentTime={4}
+          theme={defaultTimelineTheme}
+          getTrackStyle={getTrackStyle}
+        />,
+      );
+    });
+    const actor = host.querySelector<HTMLElement>('[data-timeline-gesture-actor="hero"]');
+    expect(actor?.style.left).toBe("780px");
+    expect(actor?.style.top).toBe("490px");
+    expect(actor?.querySelector(".timeline-clip")).not.toBeNull();
+    expect(actor?.querySelector("[data-el-id]")).toBeNull();
+    expect(actor?.querySelector("[data-clip]")).toBeNull();
+    expect(host.querySelector("[data-source-row]")).toBeNull();
+    act(() => root.unmount());
+  });
+
+  it("keeps the stable overlay host after terminal cleanup", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    act(() => {
+      root.render(
+        <TimelineGestureOverlay
+          drag={null}
+          scrollRef={{ current: null }}
+          pixelsPerSecond={100}
+          rowHeight={42}
+          selectedElementId={null}
+          currentTime={0}
+          theme={defaultTimelineTheme}
+          getTrackStyle={getTrackStyle}
+        />,
+      );
+    });
+    expect(host.querySelector("[data-timeline-gesture-overlay]")).not.toBeNull();
+    expect(host.querySelector("[data-timeline-gesture-actor]")).toBeNull();
+    act(() => root.unmount());
+  });
+});

package/src/player/components/TimelineGestureOverlay.tsx

@@ -0,0 +1,96 @@
+import { memo, type ReactNode } from "react";
+import type { TimelineElement } from "../store/playerStore";
+import type { TimelineTheme } from "./timelineTheme";
+import { getRenderedTimelineElement } from "./timelineTheme";
+import { TimelineClip } from "./TimelineClip";
+import { getTimelineEditCapabilities } from "./timelineEditing";
+import { renderClipChildren } from "./timelineClipChildren";
+import { getTimelineDragOverlayPosition } from "./timelineClipDragPreview";
+import type { DraggedClipState } from "./timelineClipDragTypes";
+import type { TrackVisualStyle } from "./timelineIcons";
+import { isTimelineClipActive } from "./useTimelineActiveClips";
+
+interface TimelineGestureOverlayProps {
+  drag: DraggedClipState | null;
+  scrollRef: React.RefObject<HTMLDivElement | null>;
+  pixelsPerSecond: number;
+  rowHeight: number;
+  selectedElementId: string | null;
+  currentTime: number;
+  theme: TimelineTheme;
+  getTrackStyle: (tag: string) => TrackVisualStyle;
+  renderClipContent?: (
+    element: TimelineElement,
+    style: { clip: string; label: string },
+  ) => ReactNode;
+  renderClipOverlay?: (element: TimelineElement) => ReactNode;
+}
+
+/** Stable canvas child that owns the live drag actor independently of source rows. */
+export const TimelineGestureOverlay = memo(function TimelineGestureOverlay({
+  drag,
+  scrollRef,
+  pixelsPerSecond,
+  rowHeight,
+  selectedElementId,
+  currentTime,
+  theme,
+  getTrackStyle,
+  renderClipContent,
+  renderClipOverlay,
+}: TimelineGestureOverlayProps) {
+  const element =
+    drag?.started === true
+      ? getRenderedTimelineElement({
+          element: drag.element,
+          draggedElementId: drag.element.key ?? drag.element.id,
+          previewStart: drag.previewStart,
+          previewTrack: drag.previewTrack,
+        })
+      : null;
+  const position = drag ? getTimelineDragOverlayPosition(drag, scrollRef.current) : null;
+  return (
+    <div data-timeline-gesture-overlay className="absolute inset-0 pointer-events-none">
+      {element && position && (
+        <div
+          data-timeline-gesture-actor={element.key ?? element.id}
+          className="absolute"
+          style={{
+            top: position.top,
+            left: position.left,
+            width: Math.max(element.duration * pixelsPerSecond, 4),
+            height: rowHeight,
+            zIndex: 40,
+          }}
+        >
+          <TimelineClip
+            el={{ ...element, start: 0 }}
+            pps={pixelsPerSecond}
+            clipY={0}
+            isSelected={selectedElementId === (element.key ?? element.id)}
+            isHovered={false}
+            isDragging
+            isGestureActor
+            isActive={isTimelineClipActive(element, currentTime)}
+            hasCustomContent={!!renderClipContent}
+            capabilities={getTimelineEditCapabilities(element)}
+            theme={theme}
+            isComposition={!!element.compositionSrc}
+            onHoverStart={() => {}}
+            onHoverEnd={() => {}}
+            onResizeStart={() => {}}
+            onClick={() => {}}
+            onDoubleClick={() => {}}
+          >
+            {renderClipChildren(
+              element,
+              getTrackStyle(element.tag),
+              renderClipContent,
+              renderClipOverlay,
+            )}
+          </TimelineClip>
+        </div>
+      )}
+    </div>
+  );
+});

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

@@ -116,7 +116,6 @@ function renderLanes(options: RenderLanesOptions = {}): {
           setResizingClip={vi.fn()}
           setDraggedClip={vi.fn()}
           setSelectedElementId={vi.fn()}
-          syncClipDragAutoScroll={vi.fn()}
           shiftClickClipRef={createRef()}
           getPreviewElement={(el) => el}
           getTrackStyle={getTrackStyle}

package/src/player/components/TimelineLanes.tsx

@@ -76,7 +76,6 @@ export function TimelineLanes({
   setResizingClip,
   setDraggedClip,
   setSelectedElementId,
-  syncClipDragAutoScroll,
   shiftClickClipRef,
   getPreviewElement,
   getTrackStyle,
@@ -350,6 +349,7 @@ export function TimelineLanes({
                             setShowPopover(false);
                             setRangeSelection(null);
                             setResizingClip({
+                              pointerId: e.pointerId,
                               element: el,
                               edge,
                               originClientX: e.clientX,
@@ -388,6 +388,7 @@ export function TimelineLanes({
                                 (blockedIntent !== "move" && onResizeElement))
                             ) {
                               blockedClipRef.current = {
+                                pointerId: e.pointerId,
                                 element: el,
                                 intent: blockedIntent,
                                 originClientX: e.clientX,
@@ -401,6 +402,7 @@ export function TimelineLanes({
                             setShowPopover(false);
                             setRangeSelection(null);
                             setDraggedClip({
+                              pointerId: e.pointerId,
                               element: el,
                               originClientX: e.clientX,
                               originClientY: e.clientY,
@@ -418,7 +420,6 @@ export function TimelineLanes({
                               snapType: null,
                               started: false,
                             });
-                            syncClipDragAutoScroll(e.clientX, e.clientY);
                           }
                         }
                         onClick={