@hyperframes/studio 0.7.54 → 0.7.56

package/src/player/components/timelineMultiDragPreview.ts

@@ -0,0 +1,106 @@
+/**
+ * Pure geometry for the LIVE multi-selection drag preview.
+ *
+ * Visual model (matches main): while a selected clip is dragged, ALL selected
+ * clips move together LIVE as one rigid formation following the cursor. The
+ * GRABBED clip is drawn as the free-floating ghost; every OTHER selected member
+ * ("passenger") slides by the SAME time delta via a cheap compositor
+ * `translateX` (no re-layout). Passengers do NOT stay still, and they do NOT lag
+ * behind individually — the whole formation moves by one delta, spacing locked.
+ *
+ * That single delta is the GRABBED clip's `draggedPreviewStart − draggedOriginStart`.
+ * The preview start is ALREADY group-clamped upstream (updateDraggedClipPreview
+ * runs clampGroupMoveDelta before setting it), so this delta is the clamped delta:
+ * the instant any member would cross 0 the grabbed clip stops and every passenger
+ * stops with it — the formation never deforms. On DROP the commit shifts every
+ * selected clip by this same delta (see timelineClipDragCommit / useTimelineClipDrag).
+ *
+ * Track changes apply to the grabbed clip only (mirroring the commit); passengers
+ * keep their lanes, so only their x moves.
+ */
+
+export interface MultiDragPreviewInput {
+  /** The drag is live (past the movement threshold). */
+  dragStarted: boolean;
+  /** Key of the clip under the pointer. */
+  draggedKey: string;
+  /** The dragged clip's committed start (pre-drag). */
+  draggedOriginStart: number;
+  /** The dragged clip's live preview start (already group-clamped upstream). */
+  draggedPreviewStart: number;
+  /** The current multi-selection (store.selectedElementIds). */
+  selectedKeys: ReadonlySet<string>;
+}
+
+/**
+ * Whether a live multi-selection drag is in effect: the drag started, and the
+ * dragged clip is itself part of a 2+ multi-selection. Below this, single-drag
+ * behavior is unchanged and there are no passengers.
+ */
+export function isMultiDragActive(input: MultiDragPreviewInput): boolean {
+  return (
+    input.dragStarted && input.selectedKeys.size > 1 && input.selectedKeys.has(input.draggedKey)
+  );
+}
+
+/**
+ * The single time delta the WHOLE formation shifts by — the grabbed clip's
+ * preview start minus its origin start. Because the preview start is already
+ * group-clamped, this is the clamped delta every member (ghost + passengers)
+ * moves by. Zero when the clip hasn't moved (or no multi-drag).
+ */
+export function multiDragDeltaSeconds(input: MultiDragPreviewInput): number {
+  if (!isMultiDragActive(input)) return 0;
+  return input.draggedPreviewStart - input.draggedOriginStart;
+}
+
+/**
+ * Whether a specific rendered clip is a passenger — a selected clip that is NOT
+ * the dragged clip and NOT the same clip key. Passengers get the translateX
+ * treatment; the dragged clip is drawn as the free-floating ghost instead.
+ */
+export function isMultiDragPassenger(clipKey: string, input: MultiDragPreviewInput): boolean {
+  return (
+    isMultiDragActive(input) && clipKey !== input.draggedKey && input.selectedKeys.has(clipKey)
+  );
+}
+
+/**
+ * The passenger's rendered x offset in PIXELS (delta seconds × pixels/second),
+ * to apply as `transform: translateX(...px)`. Every passenger uses the SAME
+ * formation delta, so the group moves rigidly. Returns 0 for non-passengers so
+ * callers can compute unconditionally and only branch on the elevated styling.
+ */
+export function multiDragPassengerOffsetPx(
+  clipKey: string,
+  pixelsPerSecond: number,
+  input: MultiDragPreviewInput,
+): number {
+  if (!isMultiDragPassenger(clipKey, input)) return 0;
+  const pps = Number.isFinite(pixelsPerSecond) ? pixelsPerSecond : 0;
+  return multiDragDeltaSeconds(input) * pps;
+}
+
+/**
+ * Clamp a group move so the WHOLE selection moves as ONE rigid formation.
+ *
+ * The grabbed clip proposes a raw delta (its desired preview start minus its
+ * origin start, after its own snapping). Applied naively, a passenger could be
+ * pushed below 0 (or past any other member bound), and the commit's per-clip
+ * `Math.max(0, …)` would then deform the formation — the grabbed clip out-runs
+ * the group while a passenger sticks at the wall. This ports main's model
+ * (useTimelineClipGroupDrag / clampTimelineGroupMoveDelta): the applied delta is
+ * bounded by the MOST-CONSTRAINED member, so the grabbed clip STOPS the instant
+ * any member hits 0 and the formation never deforms.
+ *
+ * `memberStarts` are the pre-drag starts of every selected clip (the grabbed clip
+ * included). Only the lower bound (start ≥ 0) constrains a move; the timeline has
+ * no fixed right wall (the composition grows on commit).
+ */
+export function clampGroupMoveDelta(rawDelta: number, memberStarts: readonly number[]): number {
+  if (memberStarts.length === 0) return rawDelta;
+  // Leftmost member sets the floor: delta ≥ -min(start) keeps every start ≥ 0.
+  const minStart = Math.min(...memberStarts);
+  const minDelta = minStart === 0 ? 0 : -minStart; // avoid -0
+  return rawDelta < minDelta ? minDelta : rawDelta;
+}

package/src/player/components/timelineOptimisticRevision.ts

@@ -0,0 +1,42 @@
+import type { TimelineElement } from "../store/playerStore";
+
+type UpdateElement = (key: string, updates: Partial<TimelineElement>) => void;
+const revisionsByUpdater = new WeakMap<UpdateElement, Map<string, number>>();
+
+export function beginTimelineOptimisticGesture(
+  updateElement: UpdateElement,
+  keys: readonly string[],
+): Map<string, number> {
+  let revisions = revisionsByUpdater.get(updateElement);
+  if (!revisions) {
+    revisions = new Map();
+    revisionsByUpdater.set(updateElement, revisions);
+  }
+  const gesture = new Map<string, number>();
+  for (const key of keys) {
+    const revision = (revisions.get(key) ?? 0) + 1;
+    revisions.set(key, revision);
+    gesture.set(key, revision);
+  }
+  return gesture;
+}
+
+export function isLatestTimelineOptimisticGesture(
+  updateElement: UpdateElement,
+  gesture: ReadonlyMap<string, number>,
+  key: string,
+): boolean {
+  return revisionsByUpdater.get(updateElement)?.get(key) === gesture.get(key);
+}
+
+export function rollbackLatestTimelineOptimisticGesture(
+  updateElement: UpdateElement,
+  gesture: ReadonlyMap<string, number>,
+  rollbacks: ReadonlyArray<{ key: string; updates: Partial<TimelineElement> }>,
+): void {
+  for (const rollback of rollbacks) {
+    if (isLatestTimelineOptimisticGesture(updateElement, gesture, rollback.key)) {
+      updateElement(rollback.key, rollback.updates);
+    }
+  }
+}

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

@@ -0,0 +1,134 @@
+import { describe, expect, it } from "vitest";
+import {
+  TIMELINE_SNAP_PX,
+  collectTimelineSnapTargets,
+  snapMoveToTargets,
+  snapTimelineTime,
+} from "./timelineSnapping";
+
+describe("collectTimelineSnapTargets", () => {
+  const elements = [
+    { start: 2, duration: 3, key: "a", id: "a" },
+    { start: 10, duration: 1.5, key: "b", id: "b" },
+  ];
+
+  it("collects clip starts and ends, playhead, and beats with types", () => {
+    const targets = collectTimelineSnapTargets({
+      elements,
+      playheadTime: 7.25,
+      beatTimes: [0.5, 1.0],
+    });
+    expect(targets).toContainEqual({ time: 2, type: "clip-edge" });
+    expect(targets).toContainEqual({ time: 5, type: "clip-edge" });
+    expect(targets).toContainEqual({ time: 10, type: "clip-edge" });
+    expect(targets).toContainEqual({ time: 11.5, type: "clip-edge" });
+    expect(targets).toContainEqual({ time: 7.25, type: "playhead" });
+    expect(targets).toContainEqual({ time: 0.5, type: "beat" });
+  });
+
+  it("excludes the dragged element's own edges", () => {
+    const targets = collectTimelineSnapTargets({
+      elements,
+      playheadTime: null,
+      beatTimes: [],
+      excludeElementKey: "a",
+    });
+    expect(targets.some((t) => t.time === 2)).toBe(false);
+    expect(targets.some((t) => t.time === 5)).toBe(false);
+    expect(targets).toContainEqual({ time: 10, type: "clip-edge" });
+  });
+
+  it("omits playhead when null and dedupes identical times preferring playhead > clip-edge > beat", () => {
+    const targets = collectTimelineSnapTargets({
+      elements: [{ start: 1, duration: 1, key: "x", id: "x" }],
+      playheadTime: 2,
+      beatTimes: [2],
+    });
+    const atTwo = targets.filter((t) => t.time === 2);
+    expect(atTwo).toEqual([{ time: 2, type: "playhead" }]);
+  });
+
+  it("dedupes a coincident clip-edge and beat preferring clip-edge (no playhead)", () => {
+    // A beat and a clip edge land on the same time (2). clip-edge has higher
+    // priority than beat, so the deduped target is clip-edge — not beat.
+    const targets = collectTimelineSnapTargets({
+      elements: [{ start: 2, duration: 3, key: "x", id: "x" }],
+      playheadTime: null,
+      beatTimes: [2],
+    });
+    const atTwo = targets.filter((t) => t.time === 2);
+    expect(atTwo).toEqual([{ time: 2, type: "clip-edge" }]);
+  });
+});
+
+describe("snapTimelineTime", () => {
+  const targets = [
+    { time: 5, type: "clip-edge" as const },
+    { time: 5.3, type: "playhead" as const },
+  ];
+
+  it("snaps to the nearest target within threshold", () => {
+    expect(snapTimelineTime(5.05, targets, 0.1)).toEqual({
+      time: 5,
+      target: { time: 5, type: "clip-edge" },
+    });
+  });
+
+  it("returns input unchanged when nothing is within threshold", () => {
+    expect(snapTimelineTime(6, targets, 0.1)).toEqual({ time: 6, target: null });
+  });
+});
+
+describe("snapMoveToTargets", () => {
+  // pps=100 → threshold = TIMELINE_SNAP_PX/100 = 0.08s
+  const targets = [{ time: 5, type: "playhead" as const }];
+
+  it("snaps the start edge when it is the closer edge", () => {
+    const r = snapMoveToTargets(5.05, 2, targets, 100, 60);
+    expect(r).toEqual({ start: 5, snapTime: 5, snapType: "playhead" });
+  });
+
+  it("snaps the end edge, shifting start so the end lands on the target", () => {
+    const r = snapMoveToTargets(3.03, 2, targets, 100, 60);
+    expect(r.start).toBeCloseTo(3, 5);
+    expect(r.snapTime).toBe(5);
+    expect(r.snapType).toBe("playhead");
+  });
+
+  it("drops the snap when clamping to timeline bounds pulls it off target", () => {
+    // duration 2, timeline 6 → maxStart 4; target at 5.05 wants start 5.05 → clamped to 4
+    const r = snapMoveToTargets(5.0, 2, [{ time: 5.05, type: "beat" }], 100, 6);
+    expect(r.snapTime).toBeNull();
+  });
+
+  it("threshold scales with pixels-per-second", () => {
+    // pps=10 → threshold 0.8s: 5.5 snaps; pps=1000 → threshold 0.008s: it does not
+    expect(snapMoveToTargets(5.5, 2, targets, 10, 60).snapTime).toBe(5);
+    expect(snapMoveToTargets(5.5, 2, targets, 1000, 60).snapTime).toBeNull();
+  });
+
+  it("TIMELINE_SNAP_PX matches the historical beat-snap threshold", () => {
+    expect(TIMELINE_SNAP_PX).toBe(8);
+  });
+
+  it("keeps the snap indicator for a frame-quantized duration (ms-rounding residue, no clamp)", () => {
+    // duration 10/3 ≈ 3.3333…; end-snap onto a clip-edge at 5 gives a candidate
+    // start of 5 - 10/3 = 1.6666…, whose ms-rounding residue (~3.3e-4) exceeds the
+    // old 1e-6 tolerance. With a huge timeline (no bounds clamp), the snap must
+    // survive — the clip snaps AND the indicator shows.
+    const duration = 10 / 3;
+    const edge = [{ time: 5, type: "clip-edge" as const }];
+    const r = snapMoveToTargets(5 - duration + 0.001, duration, edge, 100, 1000);
+    expect(r.snapTime).toBe(5);
+    expect(r.snapType).toBe("clip-edge");
+  });
+
+  it("still drops the snap when the bounds clamp genuinely moves a frame-quantized clip off target", () => {
+    // Same 10/3 duration, but the timeline is short enough that clamping to maxStart
+    // pulls the clip off the target — the indicator must still vanish (the residue
+    // widening must not mask a real clamp).
+    const duration = 10 / 3;
+    const r = snapMoveToTargets(5.0, duration, [{ time: 5.05, type: "beat" }], 100, 6);
+    expect(r.snapTime).toBeNull();
+  });
+});

package/src/player/components/timelineSnapping.ts

@@ -0,0 +1,110 @@
+import type { TimelineElement } from "../store/playerStore";
+
+export type TimelineSnapType = "beat" | "playhead" | "clip-edge";
+
+export interface TimelineSnapTarget {
+  time: number;
+  type: TimelineSnapType;
+}
+
+/** Pixel radius within which a time snaps to a target (matches historical beat snap). */
+export const TIMELINE_SNAP_PX = 8;
+
+const TYPE_PRIORITY: Record<TimelineSnapType, number> = {
+  playhead: 0,
+  "clip-edge": 1,
+  beat: 2,
+};
+
+export function collectTimelineSnapTargets(input: {
+  elements: ReadonlyArray<Pick<TimelineElement, "start" | "duration" | "key" | "id">>;
+  playheadTime: number | null;
+  beatTimes: readonly number[];
+  excludeElementKey?: string | null;
+}): TimelineSnapTarget[] {
+  const byTime = new Map<number, TimelineSnapTarget>();
+  const add = (time: number, type: TimelineSnapType) => {
+    if (!Number.isFinite(time) || time < 0) return;
+    const rounded = Math.round(time * 1000) / 1000;
+    const existing = byTime.get(rounded);
+    if (!existing || TYPE_PRIORITY[type] < TYPE_PRIORITY[existing.type]) {
+      byTime.set(rounded, { time: rounded, type });
+    }
+  };
+
+  for (const beat of input.beatTimes) add(beat, "beat");
+  for (const el of input.elements) {
+    if (input.excludeElementKey != null && (el.key ?? el.id) === input.excludeElementKey) continue;
+    add(el.start, "clip-edge");
+    add(el.start + el.duration, "clip-edge");
+  }
+  if (input.playheadTime != null) add(input.playheadTime, "playhead");
+
+  return Array.from(byTime.values()).sort((a, b) => a.time - b.time);
+}
+
+export function snapTimelineTime(
+  time: number,
+  targets: readonly TimelineSnapTarget[],
+  thresholdSecs: number,
+): { time: number; target: TimelineSnapTarget | null } {
+  let best: TimelineSnapTarget | null = null;
+  let bestDist = thresholdSecs;
+  for (const target of targets) {
+    const d = Math.abs(target.time - time);
+    if (
+      d < bestDist ||
+      (d === bestDist && best && TYPE_PRIORITY[target.type] < TYPE_PRIORITY[best.type])
+    ) {
+      bestDist = d;
+      best = target;
+    }
+  }
+  return best ? { time: best.time, target: best } : { time, target: null };
+}
+
+/**
+ * Snap a moved clip so whichever edge (start or end) is nearest a target lands
+ * on it, keeping duration fixed. Mirrors the historical beat-snap semantics:
+ * clamp to [0, timelineDuration - duration]; if clamping pulls the clip off the
+ * target, drop the highlight.
+ */
+export function snapMoveToTargets(
+  start: number,
+  duration: number,
+  targets: readonly TimelineSnapTarget[],
+  pixelsPerSecond: number,
+  timelineDuration: number,
+): { start: number; snapTime: number | null; snapType: TimelineSnapType | null } {
+  if (targets.length === 0) return { start, snapTime: null, snapType: null };
+  const thresholdSecs = TIMELINE_SNAP_PX / Math.max(pixelsPerSecond, 1);
+  const startSnap = snapTimelineTime(start, targets, thresholdSecs);
+  const endSnap = snapTimelineTime(start + duration, targets, thresholdSecs);
+  const startMoved = startSnap.target !== null;
+  const endMoved = endSnap.target !== null;
+
+  let candidate = start;
+  let target: TimelineSnapTarget | null = null;
+  if (
+    startMoved &&
+    (!endMoved || Math.abs(startSnap.time - start) <= Math.abs(endSnap.time - (start + duration)))
+  ) {
+    candidate = startSnap.time;
+    target = startSnap.target;
+  } else if (endMoved) {
+    candidate = endSnap.time - duration;
+    target = endSnap.target;
+  }
+
+  const maxStart = Math.max(0, timelineDuration - duration);
+  // Round the candidate to ms FIRST, then compare the clamp against that rounded
+  // value — not the raw candidate. A frame-quantized duration (e.g. 1/30s, 10/3s)
+  // leaves sub-ms residue after rounding that exceeds a 1e-6 tolerance, so comparing
+  // the clamp to the raw candidate dropped the snap-line indicator on every snap
+  // even though no clamping happened. Comparing against the rounded candidate makes
+  // the residue exactly 0 unless the timeline-bounds clamp actually moved the clip.
+  const roundedCandidate = Math.round(candidate * 1000) / 1000;
+  const clamped = Math.max(0, Math.min(maxStart, roundedCandidate));
+  if (target && Math.abs(clamped - roundedCandidate) > 1e-6) target = null;
+  return { start: clamped, snapTime: target?.time ?? null, snapType: target?.type ?? null };
+}

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

@@ -0,0 +1,244 @@
+import { describe, expect, it } from "vitest";
+import { computeStackingPatches, laneIsAbove, type StackingElement } from "./timelineStackingSync";
+
+function el(
+  key: string,
+  track: number,
+  start: number,
+  duration: number,
+  zIndex: number,
+  isAudio = false,
+  domIndex?: number,
+): StackingElement {
+  return { key, track, start, duration, zIndex, isAudio, domIndex };
+}
+
+function patchMap(elements: StackingElement[], edited: string[]): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const p of computeStackingPatches(elements, edited)) out[p.key] = p.zIndex;
+  return out;
+}
+
+describe("laneIsAbove", () => {
+  it("lower track renders above (top of timeline wins)", () => {
+    expect(laneIsAbove({ track: 0 }, { track: 1 })).toBe(true);
+    expect(laneIsAbove({ track: 2 }, { track: 1 })).toBe(false);
+    expect(laneIsAbove({ track: 1 }, { track: 1 })).toBe(false);
+  });
+});
+
+describe("computeStackingPatches", () => {
+  it("no overlapping clips → no patch", () => {
+    // a (0..5 on track 0) and b (10..15 on track 1) never overlap in time.
+    const elements = [el("a", 0, 0, 5, 10), el("b", 1, 10, 5, 5)];
+    expect(patchMap(elements, ["a"])).toEqual({});
+  });
+
+  it("edited clip moved to a HIGHER lane (top) but z too low → raised above the below-neighbour", () => {
+    // a on top lane (0) overlaps b on lane 1; a.z=1 is below b.z=5 → wrong.
+    const elements = [el("a", 0, 0, 10, 1), el("b", 1, 0, 10, 5)];
+    // Only a is edited → only a gets a patch, lifting it above b (5) → 6.
+    expect(patchMap(elements, ["a"])).toEqual({ a: 6 });
+  });
+
+  it("edited clip moved to a LOWER lane (bottom) but z too high → lowered below the above-neighbour", () => {
+    // a on lane 2 (bottom) overlaps b on lane 0 (top); a.z=9 above b.z=5 → wrong.
+    const elements = [el("a", 2, 0, 10, 9), el("b", 0, 0, 10, 5)];
+    expect(patchMap(elements, ["a"])).toEqual({ a: 4 });
+  });
+
+  it("edited clip already correctly ordered → no patch (authored z preserved)", () => {
+    // a on top lane already has higher z than the lower-lane b it overlaps.
+    const elements = [el("a", 0, 0, 10, 8), el("b", 1, 0, 10, 3)];
+    expect(patchMap(elements, ["a"])).toEqual({});
+  });
+
+  it("untouched clips never get a patch even when they overlap the edit", () => {
+    // b is out of order relative to a, but a is the only edited clip.
+    const elements = [el("a", 0, 0, 10, 1), el("b", 1, 0, 10, 5), el("c", 2, 0, 10, 9)];
+    const patches = computeStackingPatches(elements, ["a"]);
+    expect(patches.map((p) => p.key)).toEqual(["a"]);
+  });
+
+  it("sits strictly between neighbours when there is integer room", () => {
+    // edited a on middle lane 1 between below-lane-2 (z=2) and above-lane-0 (z=10).
+    const elements = [el("a", 1, 0, 10, 0), el("below", 2, 0, 10, 2), el("above", 0, 0, 10, 10)];
+    // Between 2 and 10 → floor((2+10)/2)=6.
+    expect(patchMap(elements, ["a"])).toEqual({ a: 6 });
+  });
+
+  it("adjacent neighbours (no integer gap) → edited lands above lower, upper is bumped", () => {
+    // below z=4, above z=5 (adjacent). There is no integer strictly between 4 and
+    // 5, so the old single-patch a=5 left `a` TIED with `above` — and with no DOM
+    // order to break the tie, `above` no longer paints strictly above `a` (the
+    // under-patch bug). Tie-aware cascade: a→5 (above below's 4) AND above→6 so it
+    // stays strictly on top. Minimal: only the two overlapping neighbours move.
+    const elements = [el("a", 1, 0, 10, 0), el("below", 2, 0, 10, 4), el("above", 0, 0, 10, 5)];
+    expect(patchMap(elements, ["a"])).toEqual({ a: 5, above: 6 });
+  });
+
+  it("audio clips are excluded — an audio edit yields no patch", () => {
+    const elements = [el("music", 3, 0, 10, 0, true), el("v", 0, 0, 10, 5)];
+    expect(patchMap(elements, ["music"])).toEqual({});
+  });
+
+  it("audio clips are excluded as neighbours — a visual edit ignores overlapping audio", () => {
+    // The only overlapping clip is audio → treated as no visual overlap → no patch.
+    const elements = [el("v", 0, 0, 10, 3), el("music", 3, 0, 10, 99, true)];
+    expect(patchMap(elements, ["v"])).toEqual({});
+  });
+
+  it("only-below neighbours → maxBelow + 1", () => {
+    const elements = [el("a", 0, 0, 10, 0), el("b", 1, 0, 10, 3), el("c", 2, 0, 10, 7)];
+    // a on top overlaps b(3) and c(7), both below → 7+1=8.
+    expect(patchMap(elements, ["a"])).toEqual({ a: 8 });
+  });
+
+  it("only-above neighbours → minAbove - 1 (clamped ≥ 0)", () => {
+    const elements = [el("a", 2, 0, 10, 9), el("b", 0, 0, 10, 1), el("c", 1, 0, 10, 4)];
+    // a on bottom overlaps b(1) and c(4), both above → min(1)-1=0.
+    expect(patchMap(elements, ["a"])).toEqual({ a: 0 });
+  });
+
+  it("partial time overlap still counts", () => {
+    // a: 0..6, b: 5..15 overlap in [5,6).
+    const elements = [el("a", 0, 0, 6, 1), el("b", 1, 5, 10, 5)];
+    expect(patchMap(elements, ["a"])).toEqual({ a: 6 });
+  });
+
+  it("touching-but-not-overlapping intervals do NOT count", () => {
+    // a ends exactly where b starts (t=5) → half-open, no overlap.
+    const elements = [el("a", 0, 0, 5, 1), el("b", 1, 5, 5, 5)];
+    expect(patchMap(elements, ["a"])).toEqual({});
+  });
+
+  it("multi-clip edit: two dragged clips resolve consistently against the region", () => {
+    // Drag a (lane 0) and b (lane 1) onto a region already holding c (lane 2, z=5).
+    // Both overlap c. Lower-lane b resolves first (above c → 6), then a (above b → 7).
+    const elements = [el("a", 0, 0, 10, 0), el("b", 1, 0, 10, 0), el("c", 2, 0, 10, 5)];
+    expect(patchMap(elements, ["a", "b"])).toEqual({ a: 7, b: 6 });
+  });
+
+  it("multi-clip edit skips a member that is already correctly ordered", () => {
+    const elements = [el("a", 0, 0, 10, 20), el("b", 1, 0, 10, 0), el("c", 2, 0, 10, 5)];
+    // a(20) already above everything → no patch. b (lane 1) sits between
+    // below-neighbour c(5) and above-neighbour a(20) → floor((5+20)/2)=12.
+    expect(patchMap(elements, ["a", "b"])).toEqual({ b: 12 });
+  });
+
+  it("empty edited set → no patches", () => {
+    const elements = [el("a", 0, 0, 10, 1), el("b", 1, 0, 10, 5)];
+    expect(computeStackingPatches(elements, [])).toEqual([]);
+  });
+
+  it("item 13: an unresolved neighbour (non-finite z) is EXCLUDED, not treated as z=0", () => {
+    // `ghost` is an overlapping upper-lane clip whose live node could not be
+    // resolved, so its z came back NaN. If it were fabricated to 0 it would be a
+    // real above-neighbour at the z-floor and drag the edited clip's cascade down.
+    // Excluded, the only real overlap is below-neighbour b(3) → a rises to 4.
+    const elements = [
+      el("a", 1, 0, 10, 0),
+      el("b", 2, 0, 10, 3),
+      el("ghost", 0, 0, 10, Number.NaN),
+    ];
+    expect(patchMap(elements, ["a"])).toEqual({ a: 4 });
+  });
+
+  it("item 13: an edited clip whose own z is unresolved (non-finite) yields no patch", () => {
+    // The edited clip itself couldn't be resolved → it is dropped from the working
+    // set and produces nothing (no fabricated-0 self-patch).
+    const elements = [el("a", 0, 0, 10, Number.NaN), el("b", 1, 0, 10, 5)];
+    expect(patchMap(elements, ["a"])).toEqual({});
+  });
+});
+
+describe("computeStackingPatches — tie-aware cascade (lane move always realisable)", () => {
+  it("drag below an overlapping z=0 neighbour → cascade bumps the neighbour, edit→0", () => {
+    // edited `v` (z=2) dragged to the BOTTOM lane, overlapping `r` (z=0) which is
+    // now on the upper lane. No z ≥ 0 fits strictly below 0, so the old resolver
+    // clamped v to 0 (tied with r) and nothing changed on canvas — the reported
+    // bug. Tie-aware: v→0 AND r bumped to 1 so r paints strictly above v.
+    const elements = [el("v", 1, 0, 10, 2), el("r", 0, 0, 10, 0)];
+    expect(patchMap(elements, ["v"])).toEqual({ v: 0, r: 1 });
+  });
+
+  it("equal-z + domIndex: dragging the LATER-in-DOM clip below is realised via a bump", () => {
+    // Two equal-z clips; `v` is later in DOM (domIndex 1) so it currently paints
+    // ON TOP of `r` (domIndex 0). User drags v to the lower lane (track 1). With
+    // domIndex the sync SEES that v is currently above r and must be lowered:
+    // v→0 (already 0, stays) then r bumped to 1 so r wins. Without domIndex the
+    // equal z would look already-correct and under-patch.
+    const elements = [el("r", 0, 0, 10, 0, false, 0), el("v", 1, 0, 10, 0, false, 1)];
+    expect(patchMap(elements, ["v"])).toEqual({ r: 1 });
+  });
+
+  it("equal-z without domIndex is ambiguous → conservatively bumps to guarantee order", () => {
+    // Same shape but NO domIndex: equal z is ambiguous, so the resolver cannot
+    // prove v is already below r and patches to make the order explicit (r above).
+    const elements = [el("r", 0, 0, 10, 0), el("v", 1, 0, 10, 0)];
+    const out = patchMap(elements, ["v"]);
+    // r must end up strictly above v (higher z) regardless of the exact numbers.
+    const vz = out.v ?? 0;
+    const rz = out.r ?? 0;
+    expect(rz).toBeGreaterThan(vz);
+  });
+
+  it("#2198 (Abhai repro): a lift cascades transitively so an UNTOUCHED pair never inverts", () => {
+    // m (z1, lane0, dom0), n (z0, lane1, dom1), e (z2, lane2, dom2, edited).
+    // e overlaps n [5,10); n overlaps m [12,15); e does NOT overlap m.
+    // Dragging e to the bottom lane forces n up to paint above e. A naive lift sets
+    // n→1, which TIES m (z1) and — n being later in the DOM — paints n above m,
+    // inverting the untouched (m,n) pair (which the next normalize would reshuffle).
+    // The transitive cascade lifts m too (→2) so m stays strictly above n.
+    const elements = [
+      el("m", 0, 12, 8, 1, false, 0),
+      el("n", 1, 5, 10, 0, false, 1),
+      el("e", 2, 0, 10, 2, false, 2),
+    ];
+    expect(patchMap(elements, ["e"])).toEqual({ e: 0, n: 1, m: 2 });
+  });
+
+  it("cascade patches as FEW clips as possible (only the blockers move)", () => {
+    // v dragged to bottom under r(z0) and s(z0) both on higher lanes; a distant
+    // non-overlapping clip x is never touched.
+    const elements = [
+      el("v", 2, 0, 10, 5),
+      el("r", 0, 0, 10, 0),
+      el("s", 1, 0, 10, 0),
+      el("x", 3, 50, 10, 0), // no time overlap → untouched
+    ];
+    const out = patchMap(elements, ["v"]);
+    expect("x" in out).toBe(false);
+    // v below both r and s.
+    expect(out.v).toBeLessThan(out.r ?? 0);
+    expect(out.v).toBeLessThan(out.s ?? 0);
+  });
+});
+
+describe("computeStackingPatches — DOM tie-break gates the cascade (item 12)", () => {
+  it("tie ACCEPTABLE: edited may sit AT minAbove when the above-neighbour is later in DOM → single patch, no neighbour bump", () => {
+    // below b (z3, lane2, dom0), edited e (lane1, dom1), above a (z4, lane0, dom2).
+    // e must paint above b and below a. There is no integer strictly between 3 and
+    // 4, but a is LATER in the DOM, so e=4 ties a and a still paints on top by DOM
+    // order — a valid SINGLE patch. The old gap<2 rule cascaded and needlessly
+    // bumped a's authored z (the over-patch). Only e changes here.
+    const elements = [
+      el("b", 2, 0, 10, 3, false, 0),
+      el("e", 1, 0, 10, 0, false, 1),
+      el("a", 0, 0, 10, 4, false, 2),
+    ];
+    expect(patchMap(elements, ["e"])).toEqual({ e: 4 });
+  });
+
+  it("tie INVERTING: edited tying minAbove would paint ABOVE it (earlier in DOM) → cascade bumps the neighbour", () => {
+    // Same z's, but a is EARLIER in the DOM than e (dom0 vs dom2). Now e=4 would
+    // tie a AND paint on top (e later in DOM), violating the lane order, so the
+    // tie-break can't save it: e→4 and a is bumped to 5.
+    const elements = [
+      el("a", 0, 0, 10, 4, false, 0),
+      el("b", 2, 0, 10, 3, false, 1),
+      el("e", 1, 0, 10, 0, false, 2),
+    ];
+    expect(patchMap(elements, ["e"])).toEqual({ e: 4, a: 5 });
+  });
+});