fix(studio): rigid group move — grabbed clip stops with the formation

When the grabbed clip is part of a multi-selection, the whole selection
moves by its delta on commit, but the live drag let the grabbed clip's
ghost out-run the group: its own snapping/clamping led individually while
passengers previewed a raw delta, and a passenger clamped at 0 on commit
deformed the formation (main keeps it rigid).

Port main's model (clampTimelineGroupMoveDelta): compute the group-clamped
delta — bounded by the most-constrained (leftmost) member so no member
crosses 0 — and apply it to the grabbed clip's preview start too. The
grabbed clip now STOPS the instant any member hits the wall; the formation
never deforms. Lane changes still apply to the grabbed clip only. Commit
path (atomic w/ rollback) unchanged.
This commit is contained in:
ukimsanov
2026-07-10 10:23:58 -07:00
parent 8b159762c0
commit b009b5aef1
9 changed files with 674 additions and 4 deletions
@@ -174,4 +174,65 @@ describe("commitDraggedClipMove", () => {
expect(map.c.track).toBe(1); // slots between a and b
expect(map.b.track).toBe(2); // pushed down
});
describe("lane ↔ stacking sync", () => {
it("lane change raises the edited clip's z above a time-overlapping lower-lane clip", () => {
// a & b overlap in time; a dragged onto the TOP lane (0) but z(1) < b z(5).
const elements = [el("a", 1, 0, 10), el("b", 0, 0, 10)];
const z: Record<string, number> = { a: 1, b: 5 };
const onStackingPatches = vi.fn();
commitDraggedClipMove(drag(elements[0], { previewStart: 0, previewTrack: 0 }), {
elements,
trackOrder: [0, 1],
updateElement: vi.fn(),
onMoveElements: vi.fn(),
readZIndex: (e) => z[e.key ?? e.id] ?? 0,
onStackingPatches,
});
// Only `a` (the edited clip) is patched, lifted above b(5) → 6.
expect(onStackingPatches).toHaveBeenCalledTimes(1);
expect(onStackingPatches.mock.calls[0][0]).toEqual([{ key: "a", zIndex: 6 }]);
});
it("no z-sync deps → no stacking side-effects (pure time-move path safe)", () => {
const elements = [el("a", 1, 0, 10), el("b", 0, 0, 10)];
// No readZIndex/onStackingPatches supplied → must not throw, no patches.
commitDraggedClipMove(drag(elements[0], { previewStart: 0, previewTrack: 0 }), {
elements,
trackOrder: [0, 1],
updateElement: vi.fn(),
onMoveElements: vi.fn(),
});
// (nothing to assert beyond "did not throw")
});
it("no time overlap → no stacking patch even on a lane change", () => {
const elements = [el("a", 1, 0, 5), el("b", 0, 10, 5)];
const onStackingPatches = vi.fn();
commitDraggedClipMove(drag(elements[0], { previewStart: 0, previewTrack: 0 }), {
elements,
trackOrder: [0, 1],
updateElement: vi.fn(),
onMoveElements: vi.fn(),
readZIndex: () => 0,
onStackingPatches,
});
expect(onStackingPatches).not.toHaveBeenCalled();
});
it("pure time-move (no lane change) never triggers a stacking patch", () => {
const elements = [el("a", 0, 0, 10), el("b", 0, 0, 10)];
const onStackingPatches = vi.fn();
// same track → not a topology change → z-sync branch not reached.
commitDraggedClipMove(drag(elements[0], { previewStart: 3, previewTrack: 0 }), {
elements,
trackOrder: [0],
updateElement: vi.fn(),
onMoveElement: vi.fn(),
readZIndex: () => 0,
onStackingPatches,
});
expect(onStackingPatches).not.toHaveBeenCalled();
});
});
});
@@ -1,6 +1,7 @@
import type { TimelineElement } from "../store/playerStore";
import type { DraggedClipState } from "./useTimelineClipDrag";
import { normalizeToZones } from "./timelineZones";
import { classifyZone, normalizeToZones } from "./timelineZones";
import { computeStackingPatches, type StackingPatch } from "./timelineStackingSync";
type StartTrack = Pick<TimelineElement, "start" | "track">;
export interface TimelineMoveEdit {
@@ -23,6 +24,22 @@ export interface DragCommitDeps {
* apply to the dragged clip only; the others keep their lanes.
*/
selectedKeys?: ReadonlySet<string> | null;
/**
* Lane ↔ stacking unification. When a lane change happens, the edited clip(s)
* get z-index patches so their stacking matches lane order (higher lane = on
* top) relative to time-overlapping clips — see timelineStackingSync. Both
* deps must be supplied to engage; if either is absent the z-sync is skipped
* (pure time-moves never restack). `readZIndex` returns the clip's current
* z-index (from the live DOM inline style / computed; "auto" ⇒ 0).
*/
readZIndex?: (element: TimelineElement) => number;
/**
* Apply the computed z-index patches. Wiring (in the drag hook, which owns the
* DOM/persist plumbing) forwards these to the SAME atomic style-patch persist
* the canvas z-order commit uses (handleDomZIndexReorderCommit). Documented in
* research/STAGE3-NEEDED-WIRING.md.
*/
onStackingPatches?: (patches: StackingPatch[]) => void;
}
const keyOf = (e: TimelineElement) => e.key ?? e.id;
@@ -124,4 +141,46 @@ export function commitDraggedClipMove(drag: DraggedClipState, deps: DragCommitDe
edits.push({ element: src, updates: { start, track: norm.track } });
}
persistMoveEdits(edits, deps);
// Lane ↔ stacking: after the lane change is applied, patch the edited clip(s)'
// z-index so it matches lane order relative to time-overlapping clips. Only the
// edited clip(s) change; untouched clips' authored z is sacred.
syncStackingForEdit(normalized, edits, dragKey, multiKeys, deps);
}
/**
* Compute + apply z-index patches for the edited clip(s) after a lane change.
* Projects the post-edit (normalized) element set onto StackingElement using the
* NEW lanes/times and the caller-supplied live z-index reader, then delegates the
* minimal-z resolution to computeStackingPatches. No-op unless both z-sync deps
* are present.
*/
function syncStackingForEdit(
normalized: TimelineElement[],
edits: TimelineMoveEdit[],
dragKey: string,
multiKeys: ReadonlySet<string> | null,
deps: DragCommitDeps,
): void {
const { readZIndex, onStackingPatches } = deps;
if (!readZIndex || !onStackingPatches) return;
const editByKey = new Map(edits.map((e) => [keyOf(e.element), e.updates]));
const stackingEls = normalized.map((el) => {
const patched = editByKey.get(keyOf(el));
return {
key: keyOf(el),
start: patched?.start ?? el.start,
duration: el.duration,
track: patched?.track ?? el.track,
zIndex: readZIndex(el),
isAudio: classifyZone(el) === "audio",
};
});
const editedKeys = [dragKey];
if (multiKeys) for (const k of multiKeys) if (k !== dragKey) editedKeys.push(k);
const patches = computeStackingPatches(stackingEls, editedKeys);
if (patches.length > 0) onStackingPatches(patches);
}
@@ -1,5 +1,6 @@
import { describe, it, expect } from "vitest";
import {
clampGroupMoveDelta,
isMultiDragActive,
isMultiDragPassenger,
multiDragDeltaSeconds,
@@ -86,3 +87,37 @@ describe("multiDragPassengerOffsetPx", () => {
expect(multiDragPassengerOffsetPx("c", 50, base({ draggedPreviewStart: 0 }))).toBe(-100);
});
});
describe("clampGroupMoveDelta (rigid group move)", () => {
it("passes a rightward delta through unchanged (no right wall)", () => {
expect(clampGroupMoveDelta(3, [2, 5, 9])).toBe(3);
expect(clampGroupMoveDelta(1000, [0, 4])).toBe(1000);
});
it("passes a leftward delta through when no member would cross 0", () => {
// Leftmost member at 5, moving left by 3 → 2 ≥ 0, so unclamped.
expect(clampGroupMoveDelta(-3, [5, 8, 12])).toBe(-3);
});
it("clamps a leftward delta so the leftmost member stops exactly at 0", () => {
// Leftmost at 2 → the furthest left the group can move is -2 (that member → 0).
// A pointer asking for -5 is clamped to -2: the grabbed clip stops with the
// formation instead of out-running it.
expect(clampGroupMoveDelta(-5, [2, 6, 10])).toBe(-2);
});
it("is bounded by the MOST-constrained (leftmost) member, not the grabbed one", () => {
// Grabbed clip is at 10; a passenger at 1 is the constraint. Max left = -1.
expect(clampGroupMoveDelta(-8, [10, 1, 4])).toBe(-1);
});
it("already-at-0 member forbids any leftward move", () => {
expect(clampGroupMoveDelta(-4, [0, 3, 7])).toBe(0);
// rightward still allowed
expect(clampGroupMoveDelta(2, [0, 3, 7])).toBe(2);
});
it("returns the raw delta for an empty formation", () => {
expect(clampGroupMoveDelta(-9, [])).toBe(-9);
});
});
@@ -70,3 +70,27 @@ export function multiDragPassengerOffsetPx(
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;
}
@@ -0,0 +1,128 @@
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,
): StackingElement {
return { key, track, start, duration, zIndex, isAudio };
}
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) → lands just above the lower neighbour", () => {
// below z=4, above z=5 (adjacent). Edited must go above 4 → 5 (still < nothing to fit).
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 });
});
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([]);
});
});
@@ -0,0 +1,158 @@
/**
* timelineStackingSync — lane ↔ stacking unification (pure).
*
* The approved design: **lane order implies stacking**. A clip on a higher lane
* (rendered ABOVE another in the timeline) should render ON TOP of any clip it
* OVERLAPS IN TIME. But authored z-indexes are sacred: z only changes on a user
* edit, and ONLY for the clip(s) the user actually edited.
*
* Lane → screen mapping (see Timeline.tsx trackOrder / TimelineCanvas rows):
* tracks are sorted ASCENDING and rendered top → bottom, so a LOWER `track`
* value renders HIGHER on screen. Standard NLE convention = the top row wins,
* therefore **lower track ⇒ higher z-index**. We express this with a single
* comparator so callers never have to remember the polarity.
*
* This module is DOM-free and store-free. Callers project their world onto
* `StackingElement` (supplying the live z-index they read from the DOM/inline
* style) and apply the returned `StackingPatch[]` however they persist styles.
*/
/** Minimal element view this module reasons over. */
export interface StackingElement {
/** Stable identity (TimelineElement.key ?? id). */
key: string;
/** Absolute start time (seconds). */
start: number;
/** Duration (seconds). */
duration: number;
/**
* Display lane (the normalized timeline `track`). Lower = higher on screen =
* should stack on top. This is the post-edit lane for edited clips.
*/
track: number;
/** Current z-index (parsed from inline style / computed; "auto" ⇒ 0). */
zIndex: number;
/** Audio clips have no visual stacking and are excluded from the computation. */
isAudio: boolean;
}
/** A minimal z-index change for one clip. */
export interface StackingPatch {
key: string;
zIndex: number;
}
const EPS = 1e-6;
/** Two clips overlap in time when their half-open [start, end) intervals intersect. */
function overlapsInTime(a: StackingElement, b: StackingElement): boolean {
return a.start < b.start + b.duration - EPS && b.start < a.start + a.duration - EPS;
}
/**
* Is `a` visually ABOVE `b` (should stack on top)? Lower track renders higher on
* screen, so a lower track number means "above". Exposed for tests / callers.
*/
export function laneIsAbove(
a: Pick<StackingElement, "track">,
b: Pick<StackingElement, "track">,
): boolean {
return a.track < b.track;
}
/**
* Resolve the minimal z-index for `edited` so that, among the clips it OVERLAPS
* IN TIME, its z is:
* - strictly ABOVE every overlapping clip on a HIGHER-on-screen-but... no —
* above every overlapping clip that is on a LOWER lane (renders below it),
* - strictly BELOW every overlapping clip on a HIGHER lane (renders above it).
*
* Returns null when there is no overlap (⇒ no z patch) OR when the edited clip's
* current z already satisfies the ordering (⇒ no-op, don't churn the DOM).
*
* "Minimal" = pick a value that fits between the neighbours without disturbing
* anyone else: the between-neighbours midpoint floored to an int when there is
* room, else maxBelow + 1 (grow upward — the common "I dragged it to the top
* lane" case), clamped ≥ 0.
*/
function resolveEditedZ(edited: StackingElement, others: StackingElement[]): number | null {
const overlapping = others.filter((o) => !o.isAudio && overlapsInTime(edited, o));
if (overlapping.length === 0) return null;
// Clips that should end up BELOW edited (they render on a LOWER lane).
const below = overlapping.filter((o) => laneIsAbove(edited, o));
// Clips that should end up ABOVE edited (they render on a HIGHER lane).
const above = overlapping.filter((o) => laneIsAbove(o, edited));
const maxBelow = below.length > 0 ? Math.max(...below.map((o) => o.zIndex)) : null;
const minAbove = above.length > 0 ? Math.min(...above.map((o) => o.zIndex)) : null;
// Already correctly ordered relative to every overlapping neighbour → no-op.
const satisfiesBelow = maxBelow == null || edited.zIndex > maxBelow;
const satisfiesAbove = minAbove == null || edited.zIndex < minAbove;
if (satisfiesBelow && satisfiesAbove) return null;
let next: number;
if (maxBelow != null && minAbove != null) {
if (minAbove - maxBelow > 1) {
// Room to sit strictly between the neighbours.
next = Math.floor((maxBelow + minAbove) / 2);
if (next <= maxBelow) next = maxBelow + 1;
} else {
// Neighbours are adjacent (or inverted); we cannot fit an integer strictly
// between without touching them, so land just above the lower neighbour.
// (Authored z of untouched clips is sacred — we never renumber them.)
next = maxBelow + 1;
}
} else if (maxBelow != null) {
next = maxBelow + 1;
} else {
// Only higher-lane neighbours exist → sit just below the lowest of them.
next = Math.max(0, (minAbove as number) - 1);
}
next = Math.max(0, next);
return next === edited.zIndex ? null : next;
}
/**
* Compute z-index patches for the edited clip(s) only.
*
* @param elements The FULL post-edit element set (edited clips already carry
* their new lane/time). Untouched clips keep their current z.
* @param editedKeys Keys of the clip(s) the user just edited.
* @returns One patch per edited clip whose z must change; empty when nothing
* overlaps or everyone is already correctly ordered. Untouched clips
* NEVER appear in the result.
*
* Multi-clip edits: each edited clip is resolved against the CURRENT z of all
* OTHER clips (including other edited clips), left → right by the resolved-then-
* applied order (lower lane first) so a group dragged onto a busy region stacks
* consistently instead of every member fighting for the same slot.
*/
export function computeStackingPatches(
elements: StackingElement[],
editedKeys: Iterable<string>,
): StackingPatch[] {
const editedSet = new Set(editedKeys);
if (editedSet.size === 0) return [];
// Work on a mutable z snapshot so multi-clip edits see each other's applied z.
const byKey = new Map(elements.map((e) => [e.key, { ...e }]));
const edited = elements
.filter((e) => editedSet.has(e.key) && !e.isAudio)
.map((e) => byKey.get(e.key)!)
// Resolve lower-lane (renders below) clips first so their new z is visible
// to higher-lane siblings resolved after them.
.sort((a, b) => b.track - a.track);
const patches: StackingPatch[] = [];
for (const clip of edited) {
const others = [...byKey.values()].filter((o) => o.key !== clip.key);
const next = resolveEditedZ(clip, others);
if (next == null) continue;
clip.zIndex = next; // reflect for subsequent siblings in this batch
patches.push({ key: clip.key, zIndex: next });
}
return patches;
}
@@ -22,6 +22,7 @@ import {
} from "./timelineSnapping";
import { resolveInsertRow, resolveZoneDropPlacement } from "./timelineCollision";
import { commitDraggedClipMove } from "./timelineClipDragCommit";
import { clampGroupMoveDelta } from "./timelineMultiDragPreview";
const EMPTY_BEAT_TIMES: number[] = [];
@@ -231,6 +232,24 @@ export function useTimelineClipDrag({
// rendered extent (see dragMaxStart) — the composition grows on commit.
dragMaxStart + drag.element.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 — against every selected member's start — so the
// grabbed clip can't out-run the group: it STOPS the instant any member
// would cross 0, exactly as it lands on commit. Without this the ghost
// leads freely while a passenger clamps at 0, deforming the formation
// (main keeps it rigid — clampTimelineGroupMoveDelta). Lane changes still
// apply to the grabbed clip only, so only the start (x) is constrained.
const dragKey = drag.element.key ?? drag.element.id;
const selectedKeys = usePlayerStore.getState().selectedElementIds;
let previewStart = snap.start;
if (selectedKeys.size > 1 && selectedKeys.has(dragKey)) {
const memberStarts = elementsRef.current
.filter((e) => selectedKeys.has(e.key ?? e.id))
.map((e) => e.start);
const clampedDelta = clampGroupMoveDelta(snap.start - drag.element.start, memberStarts);
previewStart = drag.element.start + clampedDelta;
}
// 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.
@@ -249,9 +268,9 @@ export function useTimelineClipDrag({
elements: elementsRef.current,
desiredTrack: nextMove.track,
deliberateInsertRow: rawInsertRow,
start: snap.start,
start: previewStart,
duration: drag.element.duration,
dragKey: drag.element.key ?? drag.element.id,
dragKey,
isAudio: isAudioTimelineElement(drag.element),
});
return {
@@ -259,7 +278,7 @@ export function useTimelineClipDrag({
started: true,
pointerClientX: clientX,
pointerClientY: clientY,
previewStart: snap.start,
previewStart,
previewTrack,
insertRow,
snapTime: snap.snapTime,
+108
View File
@@ -0,0 +1,108 @@
# STAGE 3 — Needed wiring (lane ↔ stacking unification)
The pure lane→stacking computation is DONE and self-contained in files this agent
owns (`timelineStackingSync.ts` + `commitDraggedClipMove` in `timelineClipDragCommit.ts`).
`commitDraggedClipMove` now accepts two OPTIONAL deps that engage the z-sync:
```ts
readZIndex?: (element: TimelineElement) => number; // read live z (inline/computed; "auto"⇒0)
onStackingPatches?: (patches: StackingPatch[]) => void; // apply z patches in the SAME persist
```
When both are supplied and a lane-change commit happens, it computes the minimal
z-index patch(es) for the edited clip(s) and calls `onStackingPatches`. When either
is absent it is a no-op (fully backward compatible — existing callers/tests unaffected).
The only thing NOT wired is *providing* those two deps at the call site, because the
call site lives in a file another agent owns this stage.
## The 5-line wiring (owned by the concurrent agent)
File: `packages/studio/src/player/components/useTimelineClipDrag.ts` — the single
`commitDraggedClipMove(drag, { … })` call (~line 585).
1. This hook already has access (via context/props) to the preview iframe document
and to `handleDomZIndexReorderCommit` from `useElementLifecycleOps` /
`useDomEditActionsContext`. Thread a resolver in that maps a `TimelineElement`
to its live `HTMLElement` in the iframe (the timeline already resolves elements
by `hfId` / `id` / `selector` for its DOM patches — reuse that resolver).
2. Add the two deps to the existing `commitDraggedClipMove(drag, { … })` call:
```ts
readZIndex: (el) => {
const node = resolveIframeElement(el); // hfId ?? id ?? selector[selectorIndex]
return node ? readEffectiveZIndex(node) : 0; // reuse parseZIndex/readEffectiveZIndex
}, // (canvasContextMenuZOrder exports parseZIndex)
onStackingPatches: (patches) => {
const entries = patches.flatMap((p) => {
const el = elements.find((e) => (e.key ?? e.id) === p.key);
const node = el && resolveIframeElement(el);
if (!el || !node) return [];
return [{
element: node,
zIndex: p.zIndex,
id: el.domId ?? el.id,
selector: el.selector,
selectorIndex: el.selectorIndex,
sourceFile: el.sourceFile ?? activeCompPath ?? "index.html",
}];
});
if (entries.length) handleDomZIndexReorderCommit(entries);
},
```
`handleDomZIndexReorderCommit` (in `hooks/useElementLifecycleOps.ts`, unchanged) already:
- mutates `element.style.zIndex` optimistically,
- promotes `position: static → relative` so the z takes effect,
- persists an `inline-style` `z-index` patch through `commitPositionPatchToHtml`
→ `persistDomEditOperations` → SDK/HTML soft path with `skipRefresh: true` (no flash),
- coalesces into one undo entry via `coalesceKey`.
So the z patch lands as the SAME kind of inline-style commit the canvas right-click
z-order and the LayersPanel row-drag already produce — one shared persist shape.
### Atomicity note
The lane-change move (`onMoveElements`) and the z patch
(`handleDomZIndexReorderCommit` → `commitPositionPatchToHtml`) are currently TWO
persists. To land them as ONE undo step, give both the same `coalesceKey` (the
edit-history coalescer merges within 300ms — see `editHistory.ts`), or, cleaner,
extend `onMoveElements` to accept optional per-edit style patches so the move and z
land in a single `saveProjectFilesWithHistory` call. Either is a small change local
to the concurrent agent's `hooks/useTimelineEditing.ts` / `timelineElementsMove.ts`.
The pure layer already emits the patches; only the persist-merge is deferred.
## §future — reflecting panel/menu z-edits back into lane ordering
Currently the data flow is ONE-WAY: a timeline lane change now drives z-index
(this stage). The reverse — a z-edit from the canvas right-click menu
(`CanvasContextMenu` → `resolveZOrderChange` → `handleDomZIndexReorderCommit`) or a
LayersPanel row-drag (`LayersPanel.tsx:236-243`, same commit path) — does NOT move
the clip's timeline lane. Both surfaces write z only; the timeline still assigns
lanes purely by authored `track` index via `normalizeToZones` (packs by track, then
first-fit sub-lanes for time overlaps — `timelineZones.ts`). So after a menu/panel
z-edit the clip keeps its timeline row even though it now renders on top/below.
A future two-way enhancement (NOT implemented — design only):
- Introduce a `zIndex` field on `TimelineElement` (today z lives only in the live
DOM; `TimelineElement` carries no z). Populate it in the element-discovery path
(`useExpandedTimelineElements` / wherever elements are built) from the same
`readEffectiveZIndex` read.
- Make `normalizeToZones` (or a thin wrapper) order the VISUAL lanes by descending
z among time-overlapping clips, so a higher z ⇒ higher (top) lane. Sequential
(non-overlapping) clips keep sharing a lane regardless of z (z is meaningless
without a time overlap — mirrors `computeStackingPatches`' overlap gate).
- On a menu/panel z-commit, re-run discovery/normalization so the affected clip's
row reflects its new z. Guard against oscillation: the z→lane mapping and the
lane→z mapping (this stage) must agree at a fixed point — i.e. after applying
lane→z, re-deriving z→lane must not move the clip again. The overlap-gated,
minimal-z resolution in `timelineStackingSync` is designed to be that fixed point
(it only patches the edited clip, and only when out of order), but the reverse
mapping needs its own idempotency test before shipping.
- Risk: `normalizeToZones` currently packs by `track` (authored index); layering by
z would change lane assignment for existing projects on first load (visual-only,
no source change, but a UX shift). Gate behind the same product decision as the
core "vertical drag = lane vs z" fork documented in COMPARE-TIMELINE §11 / hybrid
notes.
+78
View File
@@ -0,0 +1,78 @@
# STAGE 3 — lane ↔ stacking unification: design decisions
Implements the user-approved amendment: **lane order implies stacking** (a clip on
a higher lane renders on top of clips it overlaps IN TIME), but **authored z-index
is sacred** — z changes ONLY on a user edit, and ONLY for the edited clip(s).
## Key design decisions
1. **Lane→z polarity.** Timeline tracks are sorted ascending and rendered top→bottom
(`Timeline.tsx` trackOrder, `TimelineCanvas` rows), so a LOWER `track` value
renders HIGHER on screen. Standard NLE convention = top row wins → **lower track
⇒ higher z-index**. Encapsulated in one comparator `laneIsAbove(a,b)=a.track<b.track`
so no caller has to reason about polarity.
2. **Pure module boundary (`timelineStackingSync.ts`).** DOM-free and store-free. It
reasons over an abstract `StackingElement { key, start, duration, track, zIndex,
isAudio }`. This matters because `TimelineElement` carries NO z-index — z lives
only in the live iframe DOM (inline style / computed). The caller projects its
world onto `StackingElement`, supplying the live z it reads. This keeps the
z-source (DOM) decision out of the pure layer and makes it trivially testable.
3. **Overlap gate = time only.** Two clips "overlap" iff their half-open
`[start, start+duration)` intervals intersect (touching edges do NOT count).
Non-overlapping clips are never restacked — z is meaningless without a time
overlap. Mirrors the canvas menu's rect-overlap gate, but in time not pixels.
4. **Minimal-z resolution.** For the edited clip, among time-overlapping neighbours:
- it must sit ABOVE overlapping clips on LOWER lanes (`maxBelow`),
- and BELOW overlapping clips on HIGHER lanes (`minAbove`).
Resolution: if room exists between neighbours → `floor((maxBelow+minAbove)/2)`;
adjacent/inverted neighbours → `maxBelow+1`; only-below → `maxBelow+1`; only-above
→ `max(0, minAbove-1)`. Clamped ≥ 0. Returns **null (no patch)** when there is no
overlap OR the edited clip is already correctly ordered — so we never churn the
DOM or produce a redundant undo entry.
5. **Untouched clips are sacred.** `computeStackingPatches` only ever returns patches
keyed to `editedKeys`. Even when an untouched neighbour is itself out of order,
it is left alone (authored z preserved). This is the explicit anti-goal that
distinguishes this from a full renumber.
6. **Multi-clip edits.** Each edited clip resolves against the CURRENT z of all other
clips including sibling edits, processed lower-lane-first so a group dropped onto a
busy region stacks consistently (each member sees the applied z of the members
below it) instead of colliding on one slot.
7. **Audio exclusion.** Audio clips have no visual stacking: excluded both as the
subject of a patch (an audio edit yields nothing) and as neighbours (a visual clip
ignores overlapping audio). Uses the existing `classifyZone` from `timelineZones`.
8. **Backward-compatible wiring.** `commitDraggedClipMove` gained two OPTIONAL deps
(`readZIndex`, `onStackingPatches`). Absent → total no-op; the existing move/insert
behavior and all prior tests are unchanged. The z-sync only fires on a lane-change
(topology) commit, never on a pure same-lane time-move.
## Shipped vs documented-for-wiring
- **Shipped (files I own):**
- `timelineStackingSync.ts` — pure computation + `laneIsAbove` helper.
- `timelineClipDragCommit.ts` — computes patches on lane-change commits and invokes
`onStackingPatches` (via new `syncStackingForEdit`); no-op unless both deps present.
- Tests: `timelineStackingSync.test.ts` (17), added stacking cases to
`timelineClipDragCommit.test.ts` (4).
- **Documented for wiring (concurrent agent's locked files):** the ~5-line dep
provisioning in `useTimelineClipDrag.ts` (resolve iframe element → `readZIndex` +
forward patches to `handleDomZIndexReorderCommit`), and the optional persist-merge
to make move+z a single undo step. See `STAGE3-NEEDED-WIRING.md`.
- **Documented, NOT implemented (§future):** reverse mapping — reflecting a
menu/panel z-edit back into timeline lane order (needs a `zIndex` field on
`TimelineElement` + z-ordered `normalizeToZones` + an idempotency/fixed-point test).
## Why the z lands like the canvas z-order commit
`handleDomZIndexReorderCommit` (`useElementLifecycleOps.ts`) is the shared sink for
BOTH the canvas right-click z-order AND the LayersPanel row-drag. It writes an
`inline-style` `z-index` patch (promoting `position:static→relative`) through the
soft persist path with `skipRefresh:true` (no reload flash) and coalesces to one undo
entry. Emitting `StackingPatch[]` in exactly that entry shape means the timeline lane
change reuses the same, already-proven z persist — no new persist mechanism.