mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-16 22:58:02 +00:00
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:
@@ -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,
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user