feat(studio): lane-model timeline — vertical drag restacks via z-index#2068
Open
miguel-heygen wants to merge 22 commits into
Open
feat(studio): lane-model timeline — vertical drag restacks via z-index#2068miguel-heygen wants to merge 22 commits into
miguel-heygen wants to merge 22 commits into
Conversation
miguel-heygen
changed the title
Timeline rows now order by scoped stacking (z-index per stacking context) instead of data-track-index, and dragging a clip up/down commits a targeted z-index change through the same shared path the layers panel uses. Both panels stay consistent and moving a clip actually changes front/back. data-track-index is demoted to time-overlap layout only; no bulk z-index injection (#958 intact). Also restores beat-snapping on keyframe retiming (re-wires snapKeyframePctToBeat, orphaned when keyframe dragging was removed) which surfaced while unifying the model. Extracts pure track-ordering logic to timelineTrackOrder.ts, the stacking reorder commit + deleteSelectedKeyframes to timelineEditingHelpers.ts, to keep StudioApp / the timeline hook / Timeline under the studio 600-LOC cap. U3: scoped stacking row order in the timeline U4: vertical drag commits z-index via the shared reorder commit U8: restore keyframe beat-snap on retime
…io reorder The element stacking key (element.key ?? id) was recomputed in four places (reorder-intent generation, row ordering, the commit-time sibling lookup via a threaded keyOf param, and resolveTimelineMove). Any drift would silently break the sibling lookup and no-op the reorder. Route all of them through the existing getTimelineElementIdentity owner, share one toStackingOrderItem mapper between row ordering and reorder intent, and drop the keyOf parameter. Also enforce the audio side-effect invariant in the single mutation owner (applyTimelineStackingReorder): dragging an audio clip has no visual layer to restack, so it never writes z-index. Covered by a new hook test.
createTimelineElementFromManifestClip used `clip.zIndex ?? computed`, but the runtime reports inline-only z-index (0 for CSS-rule authored z-index), and `0 ?? x` keeps the 0 — so every CSS-styled clip collapsed to a z=0 tie. The timeline then ordered rows by DOM position instead of true stacking, and the first vertical drag renumbered the whole tie group, clobbering the author's z-index. Prefer the effective computed read from the live element (the same read the reorder commit uses); fall back to the runtime value only when the element isn't live.
Re-architect the timeline row model from data-track-index rows to stacking layers. Rows represent stacking layers per context: explicit-z clips merge onto one track when they share a z and don't overlap in time; auto-z clips stay one row each (DOM order); audio is pulled into its own bottom lanes. Rows keyed by a stable layer id, not data-track-index. Vertical drag always writes z-index, never track: drop onto a layer joins it (same z), between layers interpolates a new z, past the ends creates a new front/back layer. data-track-index is never rewritten; #958 holds. Adds hasExplicitZIndex capture (computed z != auto). L1: hasExplicitZIndex on the element model L2: buildStackingTimelineLayers (layer-based rows) L3: layer-aware vertical drag (join / interpolate / new-extreme)
applyTimelineStackingReorder resolves the live clip from the preview IFRAME,
then gated it with `element instanceof HTMLElement` against the MAIN window's
constructor. Cross-realm instanceof is always false, so every timeline z-index
commit silently bailed ("element not live in iframe") — the drag resolved the
right z but never wrote it. Use the element's own-realm HTMLElement constructor
(matching timelineDOM.ts). Verified end-to-end: dragging a card down now lowers
its z-index and reorders the row, leaving sibling z-indexes untouched.
Unit tests missed this because the happy-dom test iframe shares a realm; caught
via a real-browser Puppeteer E2E drag.
…ntent applyTimelineStackingReorder resolved each z-index change by looking the clip up in the top-level timelineElements list, but sub-composition children live only in the expanded list, so the lookup missed them and the reorder silently bailed. Carry the element's locator (domId/selector/sourceFile) on each z-index change so the commit resolves the live element directly from the preview DOM. Verified E2E: dragging a clip inside a sub-composition restacks it and patches the sub-comp source, while the parent composition is untouched. Adds timelineEditingHelpers.test.ts (locator-based commit + audio no-op).
…affordances L4 polish for the stacking-layer timeline: - Sub-composition layers group under a slim "Inside: <comp>" header with a green accent, so it reads that restacking there is scoped to that context. - Audio clips render in a distinct bottom lane: separator border, muted row bg, music glyph in the gutter, beat strip — clearly not part of the z-order stack. - During a vertical drag, a drop affordance shows join-vs-insert: an "onto" target highlights the row (join that layer / same z); "between"/"above"/ "below" shows an insertion line (new layer here). New pure helper timelineDropIndicator.ts (+ test) maps placement -> indicator; row-group rendering extracted into TimelineLayerGroupHeader / TimelineLayerGutter / TimelineDropInsertionLine / TimelineDragGhost to keep files under the 600 cap.
Rework the timeline row model from one-row-per-stacking-layer to NLE "lanes": a row holds a time-sequence of non-overlapping clips, ordered top = front. Stacking only matters between clips that overlap in time. - Lane packing: per stacking context, sort clips by effective z-index desc (DOM order tiebreak) and greedily pack each onto the first lane whose members don't overlap it in time; else open a new lane. Lane's representative z is the max member z. Audio stays one clip per lane. - Lane-aware drag: dropping onto a lane joins it (clip takes the lane's z) when there's no time-conflict; a conflicting drop is rejected and the preview snaps to the nearest valid lane or a new-lane insertion. Between/above/below still create a new lane at that stacking level. - Overlap checks use the drag-preview start/duration, so conflict is judged by where the clip lands, not where it started. Only explicit drags write z-index; authored z is preserved and data-track-index is never rewritten.
Dragging a timeline clip (or its right resize edge) past the end of the video now extends the composition duration on drop, instead of clamping the clip at the current end. Extend-only and undoable. - Relax the move/resize horizontal clamps that pinned a clip's end at the current duration; effectiveDuration now folds in the active drag/resize preview so the ruler and track width grow live as you drag past the end. - On drop, extend the root composition data-duration (and the store) when the clip's new end exceeds it, via a shared extendRootDurationInSource helper extracted from the block installer (now the single owner of that logic). An extending edit routes through the server persist path since the SDK setTiming op can't express the root composition's own duration.
…a no-op A vertical drag onto a lane whose clips overlap the dragged clip in time used to resolve to the "nearest valid lane", which included the clip's own lane — so a small drag snapped straight back and felt like the editor refused the move. Overlapping clips can't share a row (a row is 1-D in time), but the drag should still restack, never reject. Now a conflicting onto-drop converts to an edge insertion adjacent to the target by drag direction (up -> above, down -> below): the clip lands on its own lane just in front of / behind the target, with its time unchanged. Non-overlapping drops still join the lane. Deletes the nearest-valid-placement search (~90 lines) this replaces.
Timeline moves and resizes previously snapped only to the beat grid; they now also snap the dragged edge to other clips' start/end, the playhead, and the composition bounds, whichever is nearest within the existing threshold. Beats fold in as one target kind, so beat snapping is unchanged. Snap logic lives in a new pure timelineSnapTargets module with unit tests; a snapped edge shows a guide line (beat highlight, else a thin accent line) for both drag and resize.
Dragging a clip past the video end fed back on itself: the growing preview length shrank the fit-to-width zoom, which remapped the pointer, moved the clip, and grew the length again (visible jumping). Split the committed basis duration (drives zoom) from the displayed effective duration (adds the live preview for ruler + width). Zoom holds fixed through the gesture and the extra length scrolls; it re-fits once on drop. Duration math extracted to pure tested helpers in timelineLayout.
…mount Extending a clip past the video end used to force the server-fallback path that fully remounts the preview iframe (the SDK fast path can't express the root composition's data-duration, and the runtime bakes+drops data-duration at load so it can't be patched live). On a large comp that remount is a visible hitch. Add a runtime control-bridge action set-root-duration -> clock.setDuration, so the studio can grow the transport length in place. On an extend the studio now posts it (and patches the clip's own timing live) instead of reloading; it only reloads when a GSAP source rewrite actually happened (the gsap-mutation endpoints now report a mutated flag). Non-animated extends — the common case — commit as fast as a normal edit. Verified: bridge dispatch + studio no-reload/post-message paths unit- tested; core/studio/studio-server typecheck + suites green; the built runtime artifact carries the handler; E2E confirms the extend no longer remounts the preview and still persists.
…ootDurationToPreview CI file-size check and fallow audit caught two issues the --no-verify commits skipped: Timeline.tsx sat at 602 (max 600) and postRootDurationToPreview was an unused export (only called in-file). Trim a comment to hit 600; drop the export.
Lane/overlap resolution now uses the clip's authored time span instead of the live dragged start. A diagonal drag that drifts the clip out of overlap no longer flips the placement from restack to lane-join, so the two axes never fight.
…s the row Clips share a lane only when they carry the same z-index and don't overlap in time. Previously a non-overlapping clip packed into the first time-compatible row regardless of z, so restacking changed the z-index but the clip's row never followed.
… playhead The structural refresh now force-syncs data-active on freshly queried clip nodes instead of diffing. A clip that changes lanes on a reorder remounts as a new DOM node; if it stayed under the playhead the diff skipped it and it rendered as inactive.
When the composition is narrower than the panel (zoomed out) the track lanes, ruler bar, and context header now fill the whole timeline instead of stopping at the content width and leaving a flat dark void. Content stays in composition coordinates, so ticks, clips, and the playhead are unaffected.
The ruler now generates ticks across the visible width instead of stopping at the composition end, so a zoomed-out ruler stays labelled to the right edge. The tick interval stays pps-driven, so spacing is unchanged. Logic lives in a new generateVisibleTicks helper to keep Timeline.tsx under the 600-line cap.
miguel-heygen
force-pushed
the
worktree-fix-timeline-zindex-reorder
branch
from
54634cc to
6f0bf75
Compare
…gonal drag A drag that both moved a clip in time and restacked it fired two writers on the same file via separate queues (a targeted z-index patch and a full-file timing overwrite), so the overwrite could clobber the just-persisted z-index and the restack silently vanished after reload. The move now awaits the z-index commit before persisting timing, giving the file one ordered writer per gesture. Adds a regression test that gates the commit and asserts the timing write waits.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
In Studio, dragging a timeline clip up/down changed
data-track-index, which (per #958) has no effect on visual stacking — so clips never came to front/back. The Layers panel already restacked via z-index; the timeline didn't.What this does
Makes the timeline a stacking-layer editor (NLE convention: higher = front). A track is a stacking layer; a vertical drag writes z-index, not
data-track-index.data-track-indexis never rewritten; (studio) timeline drag rewrites HTML with inverted inline z-index on every clip, overrides CSS z-index documented as layering source of truth #958's no-bulk-injection contract holds (only the explicit drag writes z, via the same shared commit the Layers panel uses).Notable fixes found while building
isHTMLElement— the commit gated the live clip withinstanceof HTMLElementfrom the main window, but clips live in the preview iframe (a different realm), so every timeline z-index commit silently bailed. Now uses the element's own-realm constructor.Verification
Design note / trade-off
data-track-indexis demoted to splitting time-overlapping clips within a layer. Existing projects whose authored track-index disagreed with stacking will see their timeline rows re-sort to reflect true stacking on open — a one-time visual correction; rendered output is unchanged and source is untouched until an explicit drag.