fix(studio): a row move restacks only the clip you moved, so nothing else goes behind (#5057)

* fix(studio): a row move restacks only the clip you moved, so nothing else goes behind

Moved up, the clip rises above the clips it overlaps on the rows now below it; moved down, it
sinks below the ones now above it, never under z-index 0. Neighbours keep their z, so a
full-frame scene on the top row no longer jumps over a caption moved up a row beneath it.

* refactor(studio): stacking sync comments match the moved-clip-only rule

Drops the stale cascade wording, checks the time overlap before the paint-scope string compare,
and every test case names its move direction.

* fix(studio): a row move restacks only the dragged clip and a move down never hides it

Selected clips that only shifted in time keep their z-index. A move down stops at the clips on
lower rows it paints over, instead of dropping under them when z-index 0 cannot get it behind
the clip above.

* style(studio): drop a comment the drag commit's doc already covers

Author: miguel-heygen

packages/studio/src/player/components/timelineClipDragCommit.test.ts

@@ -588,6 +588,28 @@ describe("commitDraggedClipMove", () => {
       expectZLiftedToSix(onStackingPatches);
     });
 
+    it("a multi-selection lane move restacks only the dragged clip", async () => {
+      // a moves up from row 2 to row 1 over c; the selected scene keeps its row, so it keeps its z.
+      const elements = [
+        el("scene", 0, 0, 10),
+        el("b", 1, 5, 5),
+        el("a", 2, 0, 4),
+        el("c", 3, 0, 4),
+      ];
+      const z: Record<string, number> = { scene: 0, b: 2, a: 1, c: 3 };
+      const onStackingPatches = vi.fn();
+      runClipMove(drag(elements[2], { previewStart: 0, previewTrack: 1 }), {
+        elements,
+        trackOrder: [0, 1, 2, 3],
+        selectedKeys: new Set(["a", "scene"]),
+        readZIndex: (e) => z[e.key ?? e.id] ?? 0,
+        onStackingPatches,
+      });
+      await flushMicrotasks();
+      expect(onStackingPatches).toHaveBeenCalledTimes(1);
+      expect(onStackingPatches.mock.calls[0][0]).toEqual([{ key: "a", zIndex: 4 }]);
+    });
+
     it("partial z-sync deps (no readZIndex) → move persists but no stacking call", async () => {
       const elements = [el("a", 1, 0, 10), el("b", 0, 0, 10)];
       // onStackingPatches present but readZIndex absent → syncStackingForEdit needs

packages/studio/src/player/components/timelineClipDragCommit.ts

@@ -337,7 +337,6 @@ export function commitDraggedClipMove(drag: DraggedClipState, deps: DragCommitDe
     if (multi?.keys.has(keyOf(e))) return { ...e, start: multi.movedStart(e) };
     return e;
   });
-  const multiKeys = multi ? multi.keys : null;
   if (!isVertical || !deps.readZIndex || !deps.onStackingPatches) {
     void refreshAfterDurableLaneMove(
       persistMoveEdits(edits, deps, coalesceKey, "lane-reorder"),
@@ -354,7 +353,6 @@ export function commitDraggedClipMove(drag: DraggedClipState, deps: DragCommitDe
           dragKey,
           drag.element.track,
           drag.previewTrack,
-          multiKeys,
           deps,
           coalesceKey,
         ),
@@ -472,7 +470,6 @@ function commitTrackInsert(
           dragKey,
           drag.element.track,
           drag.insertRow!,
-          multi ? multi.keys : null,
           deps,
           coalesceKey,
         ),
@@ -532,8 +529,8 @@ export function commitZMirrorLaneMove(
  * vertical lane change. Projects the drop-intent element set (`candidate`: the
  * dragged clip at its new / fractional-insert lane, others at their current tracks)
  * onto StackingElement using the caller-supplied live z-index reader, then
- * delegates the minimal-z resolution to computeStackingPatches — a clip on the
- * upper lane paints above every clip it time-overlaps. No-op unless both z-sync
+ * delegates to computeStackingPatches — the moved clip alone rises (moved up) or
+ * sinks (moved down) past the clips it time-overlaps. No-op unless both z-sync
  * deps are present, and never when the gesture aimed at the clip's OWN current
  * lane (`aimedLane === currentLane` — not a relocation).
  */
@@ -542,7 +539,6 @@ function syncStackingForEdit(
   dragKey: string,
   currentLane: number,
   aimedLane: number,
-  multiKeys: ReadonlySet<string> | null,
   deps: DragCommitDeps,
   coalesceKey?: string,
 ): Promise<void> {
@@ -567,10 +563,11 @@ function syncStackingForEdit(
     stackingContextId: el.stackingContextId ?? null,
   }));
 
-  const editedKeys = [dragKey];
-  if (multiKeys) for (const k of multiKeys) if (k !== dragKey) editedKeys.push(k);
-
-  const patches = computeStackingPatches(stackingEls, editedKeys);
+  const patches = computeStackingPatches(
+    stackingEls,
+    [dragKey],
+    aimedLane < currentLane ? "up" : "down",
+  );
   if (patches.length === 0) return Promise.resolve();
   return Promise.resolve(onStackingPatches(patches, coalesceKey)).then(() => undefined);
 }