@hyperframes/studio 0.8.91 → 0.8.93

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

@@ -9,6 +9,8 @@ import {
 import type { DraggedClipState } from "./timelineClipDragTypes";
 import { commitDraggedClipMove, persistMoveEdits } from "./timelineClipDragCommit";
 import { LANE_H, RULER_H, TRACKS_TOP_PAD, TRACK_H } from "./timelineLayout";
+import { isMultiDragPassenger } from "./timelineMultiDragPreview";
+import { resolveMultiDragPreview } from "./timelineProviderStateBuilders";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Regression bed for the live-reproduced BUG 1: a PLAIN HORIZONTAL drag of a clip
@@ -168,7 +170,7 @@ describe("computeDragPreview — plain horizontal drag never arms a phantom inse
     expect(next.previewTrack).toBe(0);
   });
 
-  it("uses the expanded row midpoint when choosing the side for an automatic insert", () => {
+  it("an occupied aim in an expanded row stays on that row at the nearest free time", () => {
     const rowHeights = [TRACK_H + 2 * LANE_H, TRACK_H];
     const dragged = clip("dragged", 0, 0, 1, 3);
     const occupied = [dragged, clip("block-0", 0, 0, 1, 2), clip("block-1", 1, 0, 1, 1)];
@@ -195,11 +197,13 @@ describe("computeDragPreview — plain horizontal drag never arms a phantom inse
       ...ctx(rowHeights, occupied),
       trackOrder: [0, 1],
     });
-    expect(next.insertRow).toBe(0);
+    expect(next.insertRow).toBeNull();
+    expect(next.previewTrack).toBe(0);
+    expect(next.previewStart).toBe(1);
   });
 });
 
-describe("computeDragPreview — magnetic first clip on an empty main track", () => {
+describe("computeDragPreview — a clip landing on an empty main track keeps its released start", () => {
   // v-lower sits alone on lane 1; lane 0 (the main track) is empty.
   const vLower = clip("v-lower", 1, 10, 4, 5);
 
@@ -236,11 +240,11 @@ describe("computeDragPreview — magnetic first clip on an empty main track", ()
     });
   }
 
-  it("dragging straight up onto the empty main track snaps the preview start to 0", () => {
+  it("dragging straight up onto the empty main track keeps the start", () => {
     const next = dragUpToMainTrack([vLower]);
     expect(next.previewTrack).toBe(0);
     expect(next.insertRow).toBeNull();
-    expect(next.previewStart).toBe(0);
+    expect(next.previewStart).toBe(10);
   });
 
   it("does not touch the start once the main track already holds a clip", () => {
@@ -249,13 +253,13 @@ describe("computeDragPreview — magnetic first clip on an empty main track", ()
     expect(next.previewStart).toBe(10); // unchanged — main track wasn't empty
   });
 
-  it("aiming the top gutter over an empty main track snaps the ghost: the insert renumbers onto track 0", () => {
+  it("aiming the space above an empty main track opens a track there and keeps the start", () => {
     const next = dragUpToMainTrack([vLower], -0.6);
     expect(next.insertRow).toBe(0);
-    expect(next.previewStart).toBe(0);
+    expect(next.previewStart).toBe(10);
   });
 
-  it("does not retime the rest of a multi-selection when the grabbed clip lands on the empty main track", () => {
+  it("does not retime a multi-selection whose grabbed clip lands on the empty main track", () => {
     const vOther = clip("v-other", 1, 15, 3, 5);
     const next = dragUpToMainTrack([vLower, vOther], 0.5, new Set(["v-lower", "v-other"]));
     expect(next.previewTrack).toBe(0);
@@ -425,29 +429,107 @@ describe("computeDragPreview — the ghost start is the committed start", () =>
 
   it("plain move onto the empty main track", () => {
     const ghost = preview(lower, [lower], 1, 0.5);
-    expect(ghost.previewStart).toBe(0);
+    expect(ghost.previewStart).toBe(10);
     expect(committedStart(ghost, lower, [lower])).toBe(ghost.previewStart);
   });
 
-  it("top-gutter insert that pushes the old track-0 clip down lands on track 0 at 0", () => {
+  it("top-gutter insert that pushes the old track-0 clip down keeps the pointer start", () => {
     const oldMain = clip("old-main", 0, 0, 3, 5);
     const elements = [oldMain, lower];
     const ghost = preview(lower, elements, 1, -0.6);
     expect(ghost.insertRow).toBe(0);
-    expect(ghost.previewStart).toBe(0);
-    expect(committedStart(ghost, lower, elements)).toBe(0);
-  });
-
-  it("top-gutter insert with a clip staying on track 0 keeps the pointer start", () => {
-    const stays = clip("stays", 0, 0, 3, 5);
-    const elements = [stays, lower];
-    // Insert between lane 0 and 1: the resident track-0 clip does not move.
-    const ghost = preview(lower, elements, 1, 1.0);
     expect(ghost.previewStart).toBe(10);
     expect(committedStart(ghost, lower, elements)).toBe(10);
   });
 
-  it("expanded child dragged with its host: the host commits at 0 and the ghost matches", () => {
+  it("a move onto an occupied row lands at its nearest free time, ghost and commit alike", () => {
+    const blocker = clip("blocker", 0, 8, 4, 5);
+    const elements = [blocker, lower];
+    const ghost = preview(lower, elements, 1, 0.5);
+    expect(ghost.insertRow).toBeNull();
+    expect(ghost.previewTrack).toBe(0);
+    expect(ghost.previewStart).toBe(12);
+    expect(committedStart(ghost, lower, elements)).toBe(12);
+  });
+
+  describe("a drop onto an occupied row stays on that row", () => {
+    const title = clip("title", 0, 0, 10, 3, "text");
+    const subtitle = clip("subtitle", 1, 0, 6, 2, "text");
+    const tag = clip("tag", 2, 2, 5, 1, "text");
+    const rows = [title, subtitle, tag];
+
+    it("Tag dropped on the Subtitle row lands right after Subtitle, with no new track", () => {
+      const ghost = preview(tag, rows, 2, 1.5);
+      expect(ghost).toMatchObject({ insertRow: null, previewTrack: 1, previewStart: 6 });
+      expect(committedStart(ghost, tag, rows)).toBe(6);
+    });
+
+    it("Tag dropped on the top Title row stays on track 0 after Title, not snapped to 0", () => {
+      const ghost = preview(tag, rows, 2, 0.5);
+      expect(ghost).toMatchObject({ insertRow: null, previewTrack: 0, previewStart: 10 });
+      expect(committedStart(ghost, tag, rows)).toBe(10);
+    });
+
+    it("the edge of a row is still that row, not a new track", () => {
+      for (const edge of [0.02, 0.98, 1.02]) {
+        const ghost = preview(tag, rows, 2, edge);
+        expect(ghost.insertRow).toBeNull();
+        expect(ghost.previewTrack).toBe(Math.floor(edge));
+      }
+    });
+  });
+
+  describe("a clip released on or near its own spot stays there", () => {
+    // Frame-aligned edges with three decimals: no centisecond start fits m's own slot.
+    const a = clip("a", 0, 0, 3.333, 1);
+    const m = clip("m", 0, 3.333, 3.333, 1);
+    const b = clip("b", 0, 6.666, 4, 1);
+    const row = [a, m, b];
+
+    it("keeps its start and writes nothing when released where it started", () => {
+      const ghost = preview(m, row, 0, 0.5);
+      expect(ghost).toMatchObject({ previewTrack: 0, insertRow: null, previewStart: 3.333 });
+      expect(committedStart(ghost, m, row)).toBeUndefined();
+    });
+
+    it("goes back to its own spot from a small nudge, snapped or not", () => {
+      const snapped = [{ time: 3.333, type: "clip-edge" as const }];
+      for (const targets of [[], snapped]) {
+        const { drag, clientX, clientY } = horizontalDrag(m, 0.5, 0.1);
+        const ghost = computeDragPreview(drag, clientX, clientY, {
+          ...ctx(undefined, row),
+          buildSnapTargets: () => targets,
+        });
+        expect(ghost).toMatchObject({ previewTrack: 0, previewStart: 3.333 });
+      }
+    });
+
+    it("counts its own start only on its own row, where keeping it rewrites nothing", () => {
+      // Row 1 has the same off-grid slot, but a move there writes a rounded start that would overlap.
+      const c = clip("c", 1, 0, 3.333, 1);
+      const d = clip("d", 1, 6.666, 4, 1);
+      const ghost = preview(m, [...row, c, d], 0, 1.5);
+      expect(ghost).toMatchObject({ previewTrack: 1, insertRow: null, previewStart: 10.67 });
+    });
+  });
+
+  it("drops the snap guide when the row moves the clip off the snapped time", () => {
+    const a = clip("a", 0, 0, 6, 1);
+    const b = clip("b", 1, 3, 2, 1);
+    const { drag, clientX } = horizontalDrag(b, 1.5, 0);
+    const ghost = computeDragPreview(drag, clientX, yForRow(0.5), {
+      ...ctx(undefined, [a, b]),
+      buildSnapTargets: () => [{ time: 3, type: "beat" }],
+    });
+    expect(ghost).toMatchObject({
+      previewTrack: 0,
+      previewStart: 6,
+      snapTime: null,
+      snapType: null,
+    });
+  });
+
+  it("expanded child dragged with its host: the host keeps its start and the ghost matches", () => {
     for (const [hostStart, childStart] of [
       [30, 32],
       [20, 22],
@@ -461,12 +543,121 @@ describe("computeDragPreview — the ghost start is the committed start", () =>
       const keys = new Set(["host", "child"]);
       const ghost = preview(child, elements, 2, 0.5, keys);
       expect(ghost.previewTrack).toBe(0);
-      expect(ghost.previewStart).toBe(childStart - hostStart);
-      expect(committedStart(ghost, host, elements, keys)).toBe(0);
+      expect(ghost.previewStart).toBe(childStart);
+      expect(committedStart(ghost, host, elements, keys)).toBe(hostStart);
     }
   });
 });
 
+describe("computeDragPreview — a group move keeps its shape", () => {
+  it("never bumps the grabbed clip further left than the group's 0 limit", () => {
+    const a = clip("a", 1, 0.5, 1, 1);
+    const b = clip("b", 2, 7, 2, 1);
+    const c = clip("c", 0, 6.4, 3.6, 1);
+    const elements = [c, a, b];
+    const selectedKeys = new Set(["a", "b"]);
+    const { drag } = horizontalDrag(b, 2.5, 0);
+    // Up two rows and 0.5 s left: the group limit allows 6.5 s, which overlaps c.
+    const ghost = computeDragPreview(drag, 800 - 0.5 * PPS, yForRow(0.5), {
+      ...ctx(undefined, elements),
+      selectedKeys,
+    });
+    expect(ghost).toMatchObject({ previewTrack: 0, insertRow: null, previewStart: 10 });
+    const onMoveElements = vi.fn();
+    commitDraggedClipMove(ghost, {
+      elements,
+      trackOrder: [0, 1, 2],
+      updateElement: vi.fn(),
+      onMoveElement: vi.fn(),
+      onMoveElements,
+      selectedKeys,
+    });
+    const edits = onMoveElements.mock.calls[0][0] as Array<{
+      element: TimelineElement;
+      updates: { start: number };
+    }>;
+    const moved = Object.fromEntries(
+      edits.map((e) => [e.element.id, e.updates.start - e.element.start]),
+    );
+    expect(moved).toEqual({ a: 3, b: 3 });
+  });
+
+  // Drags `grabbed` by `seconds` onto `row` and commits; returns each written clip's start.
+  function groupMove(
+    grabbed: TimelineElement,
+    elements: TimelineElement[],
+    selectedKeys: ReadonlySet<string>,
+    row: number,
+    seconds: number,
+  ) {
+    const { drag } = horizontalDrag(grabbed, grabbed.track + 0.5, 0);
+    const ghost = computeDragPreview(drag, 800 + seconds * PPS, yForRow(row + 0.5), {
+      ...ctx(undefined, elements),
+      selectedKeys,
+    });
+    const onMoveElements = vi.fn();
+    commitDraggedClipMove(ghost, {
+      elements,
+      trackOrder: [0, 1, 2],
+      updateElement: vi.fn(),
+      onMoveElement: vi.fn(),
+      onMoveElements,
+      selectedKeys,
+    });
+    const edits = onMoveElements.mock.calls[0][0] as Array<{
+      element: TimelineElement;
+      updates: { start: number; track: number };
+    }>;
+    return Object.fromEntries(edits.map((e) => [e.element.id, e.updates]));
+  }
+
+  it("lets a group whose leftmost clip starts off the centisecond grid reach 0 exactly", () => {
+    const a = clip("a", 1, 0.333, 1, 1);
+    const b = clip("b", 0, 7, 2, 1);
+    const written = groupMove(b, [a, b], new Set(["a", "b"]), 0, -20);
+    expect(written.a.start).toBe(0);
+    expect(written.b.start).toBeCloseTo(6.667, 6);
+  });
+
+  it("does not treat the clips moving with it as obstacles", () => {
+    const a = clip("a", 0, 0, 2, 1);
+    const b = clip("b", 0, 3, 2, 1);
+    const { drag, clientX, clientY } = horizontalDrag(a, 0.5, 2);
+    const ghost = computeDragPreview(drag, clientX, clientY, {
+      ...ctx(undefined, [a, b]),
+      selectedKeys: new Set(["a", "b"]),
+    });
+    // b moves 2 s too, so a may take 2 to 4 s; were b an obstacle, a would stop at 1 s.
+    expect(ghost).toMatchObject({ previewTrack: 0, previewStart: 2 });
+  });
+
+  it("treats a locked clip swept into the selection as an obstacle, since it does not move", () => {
+    const locked: TimelineElement = { ...clip("locked", 0, 4, 2, 1), timelineLocked: true };
+    const b = clip("b", 1, 0, 1, 1);
+    const written = groupMove(b, [locked, b], new Set(["locked", "b"]), 0, 4.5);
+    // 4.5 s overlaps the locked 4-6 s clip; 3 s and 6 s are equally near, and a tie goes later.
+    expect(written).toEqual({ b: { start: 6, track: 0 } });
+  });
+});
+
+describe("resolveMultiDragPreview — the live ghosts follow the clips that move", () => {
+  it("slides the movable selected clips but not a locked one swept into the selection", () => {
+    const locked: TimelineElement = { ...clip("locked", 0, 4, 2, 1), timelineLocked: true };
+    const b = clip("b", 1, 0, 1, 1);
+    const rider = clip("rider", 2, 8, 1, 1);
+    const elements = [locked, b, rider];
+    const selectedKeys = new Set(["locked", "b", "rider"]);
+    const { drag } = horizontalDrag(b, 1.5, 0);
+    const ghost = computeDragPreview(drag, 800 + 4.5 * PPS, yForRow(0.5), {
+      ...ctx(undefined, elements),
+      selectedKeys,
+    });
+    const preview = resolveMultiDragPreview(ghost, selectedKeys, elements);
+    expect(preview && isMultiDragPassenger("rider", preview)).toBe(true);
+    expect(preview && isMultiDragPassenger("locked", preview)).toBe(false);
+  });
+});
+
 describe("a nested clip's drop stops at its host's start in the preview", () => {
   // Host at 2 s: the clip may not start before 2 unless it was authored there.
   const logo: TimelineElement = { ...clip("logo", 0, 5, 5, 0, "div"), parentCompositionStart: 2 };

package/src/player/components/timelineClipDragPreview.ts

@@ -6,12 +6,7 @@ import {
 } from "./timelineGroupEditing";
 import type { TimelineElement } from "../store/playerStore";
 import { clampToHostStart } from "../store/timelineElement";
-import {
-  getTimelineInsertBoundaryBand,
-  getTimelineRowFromY,
-  getTimelineRowHeight,
-  getTimelineRowPositionFromY,
-} from "./timelineLayout";
+import { getTimelineRowFromY } from "./timelineLayout";
 import { isMusicTrack, isAudioTimelineElement } from "../../utils/timelineInspector";
 import {
   TIMELINE_SNAP_PX,
@@ -25,9 +20,8 @@ import {
   applyTimelineGroupResizePreview,
   type TimelineGroupResizeSession,
 } from "./timelineGroupEditing";
-import { clampGroupMoveDelta } from "./timelineMultiDragPreview";
+import { groupMoveFloor, resolveGroupMovers } from "./timelineMultiDragPreview";
 import type { DraggedClipState, ResizingClipState } from "./timelineClipDragTypes";
-import { resolveDragLandingStart } from "./timelineDragLanding";
 import { STUDIO_PREVIEW_FPS } from "../lib/time";
 
 /** Snap-target builder closure supplied by the hook (closes over refs + store). */
@@ -78,74 +72,61 @@ function resolveDragMaxStart(scroll: HTMLDivElement | null, pps: number, duratio
   return Math.max(duration, scroll && pps > 0 ? scroll.scrollWidth / pps : duration);
 }
 
-/**
- * Rigid group move: when the grabbed clip is part of a multi-selection, the
- * WHOLE formation shifts by its delta on commit (see timelineClipDragCommit).
- * Clamp that delta here, and a lone clip's as a group of one, so the grabbed
- * clip STOPS the instant any member would cross its floor (clampToHostStart),
- * exactly as it lands on commit. Lane changes still apply to the grabbed clip
- * only, so only the start (x) is constrained.
- */
-function resolveGroupClampedStart(
-  snapStart: number,
-  element: TimelineElement,
-  dragKey: string,
-  elements: TimelineElement[],
-  selectedKeys: ReadonlySet<string>,
-): number {
-  const inGroup = selectedKeys.size > 1 && selectedKeys.has(dragKey);
-  const members = inGroup ? elements.filter((e) => selectedKeys.has(e.key ?? e.id)) : [element];
-  const floors = members.map((e) => ({ start: e.start, minStart: clampToHostStart(e, 0) }));
-  return element.start + clampGroupMoveDelta(snapStart - element.start, floors);
-}
-
-/**
- * The whole drop decision (no same-track overlap, zone-respecting, relocate or
- * create) — one tested pure function, so what runs here is what's verified.
- */
+/** The drop decision for the pointer's row (see resolveZoneDropPlacement). */
 function resolveDropPlacement(
   drag: DraggedClipState,
   clientY: number,
   previewStart: number,
   desiredTrack: number,
   ctx: DragPreviewContext,
-): { track: number; insertRow: number | null } {
+  group: GroupDrag,
+): { track: number; insertRow: number | null; start: number } {
   const { scroll, trackOrder, rowHeights, elements } = ctx;
-  // rowFloat = the pointer's position in track-heights from the top lane; a
-  // near-boundary hover requests a deliberate new-track insert. Uses the
-  // shared row→y inverse so the top breathing pad is subtracted consistently.
-  const rowPosition = scroll
-    ? getTimelineRowPositionFromY(
+  const rowFloat = scroll
+    ? getTimelineRowFromY(
         clientY - scroll.getBoundingClientRect().top + scroll.scrollTop,
         rowHeights,
       )
-    : { rowFloat: 0, row: 0, fraction: 0, rowHeight: getTimelineRowHeight(0, rowHeights) };
-  // Geometry-exact band (the clip inset divided by this row's actual height) so
-  // an insert only arms in the visible gutter between clip bodies.
-  const rawInsertRow = resolveInsertRow(
-    rowPosition.rowFloat,
-    trackOrder.length,
-    getTimelineInsertBoundaryBand(rowPosition.rowHeight),
-  );
-  // Pointer sub-row half: when a drop must auto-create a track (aimed span
-  // occupied, no free lane), open it on the side the pointer is nearer.
-  const preferInsertAbove = rowPosition.fraction < 0.5;
+    : 0;
+  const dragKey = drag.element.key ?? drag.element.id;
   const audioTracks =
     ctx.audioTracks ?? new Set(elements.filter(isAudioTimelineElement).map((e) => e.track));
   return resolveZoneDropPlacement({
     order: trackOrder,
     audioTracks,
-    elements,
+    elements: group.obstacles,
     desiredTrack,
-    deliberateInsertRow: rawInsertRow,
+    deliberateInsertRow: resolveInsertRow(rowFloat, trackOrder.length),
     start: previewStart,
     duration: drag.element.duration,
-    dragKey: drag.element.key ?? drag.element.id,
+    dragKey,
     isAudio: isAudioTimelineElement(drag.element),
-    preferInsertAbove,
+    minStart: group.floor,
+    origin: { track: drag.element.track, start: drag.element.start },
   });
 }
 
+interface GroupDrag {
+  /** Clips the grabbed clip may not overlap: everything but the clips that move with it. */
+  obstacles: TimelineElement[];
+  /** Lowest start the grabbed clip may take (see groupMoveFloor). */
+  floor: number;
+}
+
+function resolveGroupDrag(drag: DraggedClipState, ctx: DragPreviewContext): GroupDrag {
+  const movers = resolveGroupMovers(
+    ctx.elements,
+    ctx.selectedKeys,
+    drag.element.key ?? drag.element.id,
+  );
+  if (!movers) return { obstacles: ctx.elements, floor: groupMoveFloor(drag.element, []) };
+  const moving = new Set(movers.map((e) => e.key ?? e.id));
+  return {
+    obstacles: ctx.elements.filter((e) => !moving.has(e.key ?? e.id)),
+    floor: groupMoveFloor(drag.element, movers),
+  };
+}
+
 /** Recompute the dragged-clip preview (move + snap + group clamp + drop placement). */
 export function computeDragPreview(
   drag: DraggedClipState,
@@ -153,7 +134,7 @@ export function computeDragPreview(
   clientY: number,
   ctx: DragPreviewContext,
 ): DraggedClipState {
-  const { scroll, pps, duration, trackOrder, elements, selectedKeys, buildSnapTargets } = ctx;
+  const { scroll, pps, duration, trackOrder, buildSnapTargets } = ctx;
   const dragMaxStart = resolveDragMaxStart(scroll, pps, duration);
   const scrollTop = scroll?.scrollTop ?? drag.originScrollTop;
   const scrollRectTop = scroll?.getBoundingClientRect().top ?? 0;
@@ -196,40 +177,24 @@ export function computeDragPreview(
     // rendered extent (see dragMaxStart) — the composition grows on commit.
     dragMaxStart + drag.element.duration,
   );
-  const dragKey = drag.element.key ?? drag.element.id;
-  const previewStart = resolveGroupClampedStart(
-    snap.start,
-    drag.element,
-    dragKey,
-    elements,
-    selectedKeys,
-  );
-  const { track: previewTrack, insertRow } = resolveDropPlacement(
-    drag,
-    clientY,
-    previewStart,
-    nextMove.track,
-    ctx,
-  );
-  const placed = { ...drag, previewStart, previewTrack, insertRow };
-  const snappedStart = resolveDragLandingStart(placed, {
-    elements,
-    trackOrder,
-    selectedKeys,
-  });
+  // A group moves rigidly: the grabbed clip stops where any mover would cross its host's start.
+  const group = resolveGroupDrag(drag, ctx);
+  const previewStart = Math.max(snap.start, group.floor);
+  const placement = resolveDropPlacement(drag, clientY, previewStart, nextMove.track, ctx, group);
+  const { track: previewTrack, insertRow } = placement;
   return {
     ...drag,
     started: true,
     pointerClientX: clientX,
     pointerClientY: clientY,
-    previewStart: snappedStart,
+    previewStart: placement.start,
     previewTrack,
-    // The lane the POINTER aims at (pre-collision): the commit reads it to tell a
-    // deliberate vertical lane change from a horizontal drag merely bumped sideways.
+    // The lane the POINTER aims at (before the zone clamp): the commit reads it to
+    // tell a deliberate vertical lane change from a horizontal drag.
     desiredTrack: nextMove.track,
     insertRow,
-    snapTime: previewStart === snap.start ? snap.snapTime : null,
-    snapType: previewStart === snap.start ? snap.snapType : null,
+    snapTime: placement.start === snap.start ? snap.snapTime : null,
+    snapType: placement.start === snap.start ? snap.snapType : null,
   };
 }
 

package/src/player/components/timelineClipDragTypes.ts

@@ -18,14 +18,9 @@ export interface DraggedClipState {
   previewStart: number;
   previewTrack: number;
   /**
-   * The lane the POINTER aims at (from the drag's vertical position), before
-   * collision resolution. `previewTrack` is where the clip actually LANDS —
-   * which may differ from `desiredTrack` when the aimed span is occupied and the
-   * collision rules bump the dragged clip to a free lane. The commit reads this
-   * to tell a deliberate VERTICAL lane change (pointer aimed at another lane →
-   * stacking sync allowed) from a plain HORIZONTAL drag whose clip merely got
-   * bumped sideways (never touches z). Optional: when absent the commit falls
-   * back to `previewTrack` (pre-existing behaviour).
+   * The lane the POINTER aims at, before the kind-zone clamp picks `previewTrack`.
+   * The commit reads it to tell a deliberate vertical lane change (stacking sync
+   * allowed) from a horizontal drag. Absent: the commit falls back to `previewTrack`.
    */
   desiredTrack?: number;
   /**