diff --git a/packages/studio/src/player/components/timelineClipDragCommit.test.ts b/packages/studio/src/player/components/timelineClipDragCommit.test.ts index 7771b8c94c..e8c0236ab0 100644 --- a/packages/studio/src/player/components/timelineClipDragCommit.test.ts +++ b/packages/studio/src/player/components/timelineClipDragCommit.test.ts @@ -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 = { 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(); + }); + }); }); diff --git a/packages/studio/src/player/components/timelineClipDragCommit.ts b/packages/studio/src/player/components/timelineClipDragCommit.ts index 4e7baace9b..08b816a031 100644 --- a/packages/studio/src/player/components/timelineClipDragCommit.ts +++ b/packages/studio/src/player/components/timelineClipDragCommit.ts @@ -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; export interface TimelineMoveEdit { @@ -23,6 +24,22 @@ export interface DragCommitDeps { * apply to the dragged clip only; the others keep their lanes. */ selectedKeys?: ReadonlySet | 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 | 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); } diff --git a/packages/studio/src/player/components/timelineMultiDragPreview.test.ts b/packages/studio/src/player/components/timelineMultiDragPreview.test.ts index 60d54a6a4b..cee885a33a 100644 --- a/packages/studio/src/player/components/timelineMultiDragPreview.test.ts +++ b/packages/studio/src/player/components/timelineMultiDragPreview.test.ts @@ -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); + }); +}); diff --git a/packages/studio/src/player/components/timelineMultiDragPreview.ts b/packages/studio/src/player/components/timelineMultiDragPreview.ts index 0d6612b47a..f48e0897af 100644 --- a/packages/studio/src/player/components/timelineMultiDragPreview.ts +++ b/packages/studio/src/player/components/timelineMultiDragPreview.ts @@ -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; +} diff --git a/packages/studio/src/player/components/timelineStackingSync.test.ts b/packages/studio/src/player/components/timelineStackingSync.test.ts new file mode 100644 index 0000000000..aaa09a86bc --- /dev/null +++ b/packages/studio/src/player/components/timelineStackingSync.test.ts @@ -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 { + const out: Record = {}; + 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([]); + }); +}); diff --git a/packages/studio/src/player/components/timelineStackingSync.ts b/packages/studio/src/player/components/timelineStackingSync.ts new file mode 100644 index 0000000000..c0e9fc173d --- /dev/null +++ b/packages/studio/src/player/components/timelineStackingSync.ts @@ -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, + b: Pick, +): 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, +): 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; +} diff --git a/packages/studio/src/player/components/useTimelineClipDrag.ts b/packages/studio/src/player/components/useTimelineClipDrag.ts index 96de096290..352618710f 100644 --- a/packages/studio/src/player/components/useTimelineClipDrag.ts +++ b/packages/studio/src/player/components/useTimelineClipDrag.ts @@ -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, diff --git a/research/STAGE3-NEEDED-WIRING.md b/research/STAGE3-NEEDED-WIRING.md new file mode 100644 index 0000000000..eeed3f6f8f --- /dev/null +++ b/research/STAGE3-NEEDED-WIRING.md @@ -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. diff --git a/research/STAGE3-REPORT.md b/research/STAGE3-REPORT.md new file mode 100644 index 0000000000..0866636c78 --- /dev/null +++ b/research/STAGE3-REPORT.md @@ -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