@hyperframes/studio 0.7.89 → 0.7.92

package/src/player/components/timelineClipDragGestureLifecycle.ts

@@ -14,20 +14,44 @@ import {
 } from "./timelineOptimisticRevision";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import type { StackingPatch } from "./timelineStackingSync";
-import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import type { TimelineElement, usePlayerStore } from "../store/playerStore";
+
+export type TimelineGestureKind = "drag" | "resize";
+type TimelineGesturePhase = "active" | "committing" | "cancelled" | "complete";
+
+export interface TimelineGestureLifecycle {
+  kind: TimelineGestureKind | null;
+  phase: TimelineGesturePhase;
+  pointerId: number | null;
+  sessionEpoch: number;
+}
+
+interface TimelineGestureCommit {
+  kind: TimelineGestureKind;
+  drag: DraggedClipState | null;
+  resize: ResizingClipState | null;
+  groupResize: TimelineGroupResizeSession | null;
+}
 
 type UpdateElement = ReturnType<typeof usePlayerStore.getState>["updateElement"];
 
 interface TimelineClipDragGestureLifecycleInput {
+  lifecycleRef: RefObject<TimelineGestureLifecycle>;
+  sessionEpochRef: RefObject<number>;
+  cancelGestureRef: RefObject<
+    (options?: { updateReact?: boolean; suppressClick?: boolean }) => boolean
+  >;
+  scrollRef: RefObject<HTMLDivElement | null>;
   draggedClipRef: RefObject<DraggedClipState | null>;
   resizingClipRef: RefObject<ResizingClipState | null>;
   blockedClipRef: RefObject<BlockedClipState | null>;
   groupResizeRef: RefObject<TimelineGroupResizeSession | null>;
   suppressClickRef: RefObject<boolean>;
+  gestureSelectedKeysRef: RefObject<ReadonlySet<string>>;
   elementsRef: RefObject<TimelineElement[]>;
   trackOrderRef: RefObject<number[]>;
-  setDraggedClip: Dispatch<SetStateAction<DraggedClipState | null>>;
-  setResizingClip: Dispatch<SetStateAction<ResizingClipState | null>>;
+  setDraggedClipState: Dispatch<SetStateAction<DraggedClipState | null>>;
+  setResizingClipState: Dispatch<SetStateAction<ResizingClipState | null>>;
   setShowPopover: (show: boolean) => void;
   setRangeSelectionRef: RefObject<((selection: null) => void) | null>;
   applyResizePointerRef: RefObject<(resize: ResizingClipState, clientX: number) => void>;
@@ -36,7 +60,7 @@ interface TimelineClipDragGestureLifecycleInput {
   updateDraggedClipPreviewRef: RefObject<
     (drag: DraggedClipState, clientX: number, clientY: number) => DraggedClipState
   >;
-  restoreGroupResizeMembers: (session: TimelineGroupResizeSession, all?: boolean) => void;
+  publishDraggedClip: (next: DraggedClipState | null) => void;
   updateElement: UpdateElement;
   onMoveElementRef: RefObject<TimelineEditCallbacks["onMoveElement"]>;
   onMoveElementsRef: RefObject<TimelineEditCallbacks["onMoveElements"]>;
@@ -55,22 +79,27 @@ interface TimelineClipDragGestureLifecycleInput {
 export function mountTimelineClipDragGestureLifecycle({
   // The explicit destructuring mirrors the single call site's dependency object by design.
   // fallow-ignore-next-line code-duplication
+  lifecycleRef,
+  sessionEpochRef,
+  cancelGestureRef,
+  scrollRef,
   draggedClipRef,
   resizingClipRef,
   blockedClipRef,
   groupResizeRef,
   suppressClickRef,
+  gestureSelectedKeysRef,
   elementsRef,
   trackOrderRef,
-  setDraggedClip,
-  setResizingClip,
+  setDraggedClipState,
+  setResizingClipState,
   setShowPopover,
   setRangeSelectionRef,
   applyResizePointerRef,
   syncClipDragAutoScrollRef,
   stopClipDragAutoScrollRef,
   updateDraggedClipPreviewRef,
-  restoreGroupResizeMembers,
+  publishDraggedClip,
   updateElement,
   onMoveElementRef,
   onMoveElementsRef,
@@ -87,9 +116,65 @@ export function mountTimelineClipDragGestureLifecycle({
     });
   };
 
+  const pointerMatchesGesture = (event: PointerEvent): boolean => {
+    const pointerId = lifecycleRef.current.pointerId;
+    return pointerId === null || event.pointerId === pointerId;
+  };
+
+  const releasePointerCapture = (pointerId: number | null) => {
+    if (pointerId === null) return;
+    const scroll = scrollRef.current;
+    try {
+      if (scroll?.hasPointerCapture(pointerId)) scroll.releasePointerCapture(pointerId);
+    } catch {
+      // Window listeners are authoritative when native capture is unavailable.
+    }
+  };
+
+  const capturePointer = (pointerId: number | null) => {
+    if (pointerId === null) return;
+    try {
+      scrollRef.current?.setPointerCapture(pointerId);
+    } catch {
+      // Window listeners remain authoritative when native capture is unavailable.
+    }
+  };
+
+  const clearGestureProjection = (updateReact: boolean) => {
+    draggedClipRef.current = null;
+    resizingClipRef.current = null;
+    groupResizeRef.current = null;
+    if (updateReact) {
+      setDraggedClipState(null);
+      setResizingClipState(null);
+    }
+  };
+
+  const cancelGesture = ({
+    updateReact = true,
+    suppressClick = false,
+  }: {
+    updateReact?: boolean;
+    suppressClick?: boolean;
+  } = {}): boolean => {
+    const lifecycle = lifecycleRef.current;
+    if (lifecycle.phase !== "active") return false;
+    lifecycle.phase = "cancelled";
+    stopClipDragAutoScrollRef.current();
+    clearGestureProjection(updateReact);
+    releasePointerCapture(lifecycle.pointerId);
+    if (suppressClick) suppressClickRef.current = true;
+    lifecycle.kind = null;
+    lifecycle.pointerId = null;
+    lifecycle.phase = "complete";
+    return true;
+  };
+  cancelGestureRef.current = cancelGesture;
+
   const handleResizePointerMove = (event: PointerEvent, resize: ResizingClipState) => {
     const distance = Math.abs(event.clientX - resize.originClientX);
     if (!resize.started && distance < 2) return;
+    if (!resize.started) capturePointer(resize.pointerId);
     setShowPopover(false);
     setRangeSelectionRef.current?.(null);
     applyResizePointerRef.current(resize, event.clientX);
@@ -106,6 +191,7 @@ export function mountTimelineClipDragGestureLifecycle({
     if (!blocked.started) {
       blocked.started = true;
       blockedClipRef.current = blocked;
+      capturePointer(blocked.pointerId);
       suppressClickRef.current = true;
       setShowPopover(false);
       setRangeSelectionRef.current?.(null);
@@ -119,34 +205,33 @@ export function mountTimelineClipDragGestureLifecycle({
       event.clientY - drag.originClientY,
     );
     if (!drag.started && distance < 4) return;
+    if (!drag.started) capturePointer(drag.pointerId);
     setShowPopover(false);
     setRangeSelectionRef.current?.(null);
-    setDraggedClip((previous) =>
-      previous
-        ? updateDraggedClipPreviewRef.current(previous, event.clientX, event.clientY)
-        : previous,
-    );
+    publishDraggedClip(updateDraggedClipPreviewRef.current(drag, event.clientX, event.clientY));
     syncClipDragAutoScrollRef.current(event.clientX, event.clientY);
   };
 
   const handleWindowPointerMove = (event: PointerEvent) => {
     const resize = resizingClipRef.current;
-    if (resize) return handleResizePointerMove(event, resize);
+    if (resize) {
+      if (!pointerMatchesGesture(event)) return;
+      return handleResizePointerMove(event, resize);
+    }
     const blocked = blockedClipRef.current;
-    if (blocked) return handleBlockedPointerMove(event, blocked);
+    if (blocked) {
+      if (blocked.pointerId !== event.pointerId) return;
+      return handleBlockedPointerMove(event, blocked);
+    }
     const drag = draggedClipRef.current;
-    if (drag) handleDragPointerMove(event, drag);
+    if (drag && pointerMatchesGesture(event)) 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;
-    }
+  const commitResizePointerUp = (
+    resize: ResizingClipState,
+    groupSession: TimelineGroupResizeSession | null,
+  ) => {
+    if (!resize.started) return;
     suppressClickRef.current = true;
     clearSuppressedClick();
     if (groupSession) {
@@ -193,8 +278,6 @@ export function mountTimelineClipDragGestureLifecycle({
   };
 
   const commitDragPointerUp = (drag: DraggedClipState) => {
-    draggedClipRef.current = null;
-    setDraggedClip(null);
     if (!drag.started) return;
     suppressClickRef.current = true;
     clearSuppressedClick();
@@ -204,25 +287,96 @@ export function mountTimelineClipDragGestureLifecycle({
       updateElement,
       onMoveElement: onMoveElementRef.current,
       onMoveElements: onMoveElementsRef.current,
-      selectedKeys: usePlayerStore.getState().selectedElementIds,
+      selectedKeys: gestureSelectedKeysRef.current,
       readZIndex: readZIndexRef.current,
       onStackingPatches: onStackingPatchesRef.current,
       refreshAfterLaneMove: refreshAfterLaneMoveRef.current,
     });
   };
 
-  const handleWindowPointerUp = () => {
+  /** Group gestures commit atomically: one missing member cancels the whole resize. */
+  const gestureSourcesStillExist = (): boolean => {
+    const gestureElements = groupResizeRef.current?.members.map((member) => member.element) ?? [
+      resizingClipRef.current?.element ?? draggedClipRef.current?.element,
+    ];
+    const liveKeys = new Set(elementsRef.current.map((element) => element.key ?? element.id));
+    return gestureElements.every(
+      (element) => element === undefined || liveKeys.has(element.key ?? element.id),
+    );
+  };
+
+  const claimActiveGesture = (event: PointerEvent): TimelineGestureCommit | "ignored" | null => {
+    const lifecycle = lifecycleRef.current;
+    if (lifecycle.phase !== "active") return null;
+    if (!pointerMatchesGesture(event)) return "ignored";
+    if (lifecycle.sessionEpoch !== sessionEpochRef.current) {
+      cancelGesture();
+      return "ignored";
+    }
+    if (!gestureSourcesStillExist()) {
+      cancelGesture();
+      return "ignored";
+    }
+    lifecycle.phase = "committing";
+    const claimed = lifecycle.kind
+      ? {
+          kind: lifecycle.kind,
+          drag: draggedClipRef.current,
+          resize: resizingClipRef.current,
+          groupResize: groupResizeRef.current,
+        }
+      : "ignored";
     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();
+    clearGestureProjection(true);
+    releasePointerCapture(lifecycle.pointerId);
+    if (claimed === "ignored") lifecycle.phase = "complete";
+    return claimed;
+  };
+
+  const commitClaimedGesture = (gesture: TimelineGestureCommit) => {
+    try {
+      if (gesture.kind === "resize" && gesture.resize) {
+        commitResizePointerUp(gesture.resize, gesture.groupResize);
+      } else if (gesture.kind === "drag" && gesture.drag) {
+        commitDragPointerUp(gesture.drag);
+      }
+    } finally {
+      const lifecycle = lifecycleRef.current;
+      lifecycle.kind = null;
+      lifecycle.pointerId = null;
+      lifecycle.phase = "complete";
+    }
+  };
+
+  const handleWindowPointerUp = (event: PointerEvent) => {
+    const claimed = claimActiveGesture(event);
+    if (claimed === "ignored") return;
+    if (claimed) {
+      commitClaimedGesture(claimed);
       return;
     }
-    commitDragPointerUp(drag);
+    const blocked = blockedClipRef.current;
+    if (blocked) {
+      if (blocked.pointerId !== event.pointerId) return;
+      return finishBlockedPointerUp(blocked);
+    }
+    if (suppressClickRef.current) clearSuppressedClick();
+  };
+
+  const handleWindowPointerCancel = (event: PointerEvent) => {
+    if (lifecycleRef.current.phase === "active" && pointerMatchesGesture(event)) {
+      if (cancelGesture({ suppressClick: true })) clearSuppressedClick();
+    }
+    const blocked = blockedClipRef.current;
+    if (blocked && blocked.pointerId !== event.pointerId) return;
+    blockedClipRef.current = null;
+    if (suppressClickRef.current) clearSuppressedClick();
+  };
+
+  const handleLostPointerCapture = (event: PointerEvent) => {
+    if (lifecycleRef.current.phase === "active" && pointerMatchesGesture(event)) {
+      if (cancelGesture({ suppressClick: true })) clearSuppressedClick();
+    }
   };
 
   const handleWindowKeyDown = (event: KeyboardEvent) => {
@@ -234,28 +388,22 @@ export function mountTimelineClipDragGestureLifecycle({
     });
     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;
+    cancelGesture({ suppressClick: decision.suppressClick });
   };
 
   window.addEventListener("pointermove", handleWindowPointerMove);
   window.addEventListener("pointerup", handleWindowPointerUp);
-  window.addEventListener("pointercancel", handleWindowPointerUp);
-  window.addEventListener("keydown", handleWindowKeyDown, true);
+  window.addEventListener("pointercancel", handleWindowPointerCancel);
+  window.addEventListener("lostpointercapture", handleLostPointerCapture);
+  window.addEventListener("keydown", handleWindowKeyDown);
   return () => {
-    stopClipDragAutoScrollRef.current();
+    cancelGesture({ updateReact: false });
+    cancelGestureRef.current = () => false;
     window.removeEventListener("pointermove", handleWindowPointerMove);
     window.removeEventListener("pointerup", handleWindowPointerUp);
-    window.removeEventListener("pointercancel", handleWindowPointerUp);
-    window.removeEventListener("keydown", handleWindowKeyDown, true);
+    window.removeEventListener("pointercancel", handleWindowPointerCancel);
+    window.removeEventListener("lostpointercapture", handleLostPointerCapture);
+    window.removeEventListener("keydown", handleWindowKeyDown);
   };
 }

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

@@ -3,6 +3,7 @@ import type { TimelineElement } from "../store/playerStore";
 import {
   computeDragPreview,
   computeResizePreview,
+  getTimelineDragOverlayPosition,
   type DragPreviewContext,
 } from "./timelineClipDragPreview";
 import type { DraggedClipState } from "./timelineClipDragTypes";
@@ -84,6 +85,7 @@ function horizontalDrag(
   const originClientX = 800;
   const originClientY = yForRow(grabRowFloat);
   const drag: DraggedClipState = {
+    pointerId: 0,
     element,
     originClientX,
     originClientY,
@@ -129,6 +131,7 @@ describe("computeDragPreview — plain horizontal drag never arms a phantom inse
     const originClientX = 800;
     const originClientY = yForRow(0.5);
     const drag: DraggedClipState = {
+      pointerId: 0,
       element: moodboard,
       originClientX,
       originClientY,
@@ -170,6 +173,7 @@ describe("computeDragPreview — plain horizontal drag never arms a phantom inse
     const occupied = [dragged, clip("block-0", 0, 0, 1, 2), clip("block-1", 1, 0, 1, 1)];
     const clientY = RULER_H + TRACKS_TOP_PAD + 30;
     const drag: DraggedClipState = {
+      pointerId: 0,
       element: dragged,
       originClientX: 0,
       originClientY: clientY,
@@ -221,3 +225,32 @@ describe("computeResizePreview — composition source continuity", () => {
     });
   });
 });
+
+describe("getTimelineDragOverlayPosition", () => {
+  it("keeps the gesture actor under the pointer across two-axis autoscroll", () => {
+    const { drag } = horizontalDrag(moodboard, 0.5, 2);
+    const scroll = {
+      scrollLeft: 500,
+      scrollTop: 300,
+      getBoundingClientRect: () => ({ left: 20, top: 40 }),
+    } as Pick<HTMLDivElement, "scrollLeft" | "scrollTop" | "getBoundingClientRect">;
+    expect(
+      getTimelineDragOverlayPosition(
+        {
+          ...drag,
+          pointerClientX: 900,
+          pointerClientY: 700,
+          pointerOffsetX: 25,
+          pointerOffsetY: 10,
+        },
+        scroll,
+      ),
+    ).toEqual({ left: 1_355, top: 950 });
+  });
+
+  it("does not mount an actor before threshold or without the stable viewport", () => {
+    const { drag } = horizontalDrag(moodboard, 0.5, 2);
+    expect(getTimelineDragOverlayPosition({ ...drag, started: false }, fakeScroll())).toBeNull();
+    expect(getTimelineDragOverlayPosition(drag, null)).toBeNull();
+  });
+});

package/src/player/components/timelineClipDragPreview.ts

@@ -45,6 +45,19 @@ export interface DragPreviewContext {
   audioTracks?: ReadonlySet<number>;
 }
 
+/** Content-space position for the stable viewport drag actor. */
+export function getTimelineDragOverlayPosition(
+  drag: DraggedClipState,
+  scroll: Pick<HTMLDivElement, "scrollLeft" | "scrollTop" | "getBoundingClientRect"> | null,
+): { left: number; top: number } | null {
+  if (!drag.started || !scroll) return null;
+  const rect = scroll.getBoundingClientRect();
+  return {
+    left: drag.pointerClientX - rect.left + scroll.scrollLeft - drag.pointerOffsetX,
+    top: drag.pointerClientY - rect.top + scroll.scrollTop - drag.pointerOffsetY,
+  };
+}
+
 /**
  * Max start a drag may reach. Allow dragging past the current content into the
  * rendered timeline extent (the viewport-fill keeps that ≥ the viewport width).
@@ -328,29 +341,22 @@ export function computeResizePreview(
 
 /**
  * Apply a rigid group-resize preview: fold the grabbed clip's raw delta into the
- * session, preview every non-grabbed member through the store (`updateElement`),
- * and set the grabbed clip's preview state (it renders from resizingClip state, so
- * its store value stays pristine until commit — like the single-clip path).
+ * session and publish a coordinator-owned projection. Canonical elements stay
+ * pristine until the exactly-once commit.
  */
 export function previewGroupResize(
   session: TimelineGroupResizeSession,
   next: ResizePreviewResult,
-  grabbedKey: string,
-  updateElement: (
-    key: string,
-    patch: { start: number; duration: number; playbackStart?: number },
+  setResizeState: (
+    v: ResizePreviewResult & { groupPreview: TimelineGroupResizeSession["changes"] },
   ) => void,
-  setResizeState: (v: ResizePreviewResult) => void,
 ): void {
   const grabbedChange = applyTimelineGroupResizePreview(session, next);
-  for (const c of session.changes) {
-    if (c.key === grabbedKey) continue;
-    updateElement(c.key, { start: c.start, duration: c.duration, playbackStart: c.playbackStart });
-  }
   setResizeState({
     originScrollLeft: next.originScrollLeft,
     previewStart: grabbedChange?.start ?? next.previewStart,
     previewDuration: grabbedChange?.duration ?? next.previewDuration,
     previewPlaybackStart: grabbedChange?.playbackStart ?? next.previewPlaybackStart,
+    groupPreview: session.changes,
   });
 }

package/src/player/components/timelineClipDragTypes.ts

@@ -4,6 +4,8 @@ import type { BlockedTimelineEditIntent } from "./timelineEditing";
 
 /* ── Shared clip-drag state types ───────────────────────────────── */
 export interface DraggedClipState {
+  /** Pointer captured by the stable viewport coordinator for this gesture. */
+  pointerId: number;
   element: TimelineElement;
   originClientX: number;
   originClientY: number;
@@ -39,6 +41,8 @@ export interface DraggedClipState {
 }
 
 export interface ResizingClipState {
+  /** Pointer captured by the stable viewport coordinator for this gesture. */
+  pointerId: number;
   element: TimelineElement;
   edge: "start" | "end";
   originClientX: number;
@@ -53,10 +57,18 @@ export interface ResizingClipState {
   previewStart: number;
   previewDuration: number;
   previewPlaybackStart?: number;
+  /** Coordinator-owned group projection; canonical elements change only on commit. */
+  groupPreview?: readonly {
+    key: string;
+    start: number;
+    duration: number;
+    playbackStart?: number;
+  }[];
   started: boolean;
 }
 
 export interface BlockedClipState {
+  pointerId: number;
   element: TimelineElement;
   intent: BlockedTimelineEditIntent;
   originClientX: number;

package/src/player/components/timelineDiamondTypes.ts

@@ -93,20 +93,6 @@ export const DIAMOND_RATIO = 0.8;
 export const KF_MIN_PCT = -5;
 export const KF_MAX_PCT = 105;
 
-export type DragState = {
-  kfKey: string;
-  startX: number;
-  fromClipPct: number;
-  moved: boolean;
-  /** Latest pointer x, flushed to the preview once per frame. */
-  lastX: number;
-  /** Index in the sorted row, needed by the neighbour clamp off the render path. */
-  index: number;
-  /** Escape was pressed: the drag is dead, and the pointerup that follows is
-   *  swallowed rather than falling through to the click branch. */
-  cancelled?: boolean;
-};
-
 /**
  * The full identity of a diamond, used by every callback and by the selection
  * key. Collapsed clip rows and expanded property lanes read the same cache, so
@@ -115,7 +101,11 @@ export type DragState = {
  * the other, and would strip the animation id the retime/delete mutations use to
  * pick between two animations that collide at one percentage.
  */
-export function keyframeTarget(keyframe: TimelineDiamondKeyframe): TimelineKeyframeTarget {
+export function keyframeTarget(
+  // The identity fields only, so callers holding a narrower keyframe row (the
+  // retime coordinator's) build the same key instead of re-listing the shape.
+  keyframe: Omit<TimelineDiamondKeyframe, "properties">,
+): TimelineKeyframeTarget {
   return {
     percentage: keyframe.percentage,
     tweenPercentage: keyframe.tweenPercentage,