fix(studio): stop a group drag from jumping one element back

Dragging several elements at once and dropping them made one of them snap
back to where it started for a frame or two, then jump forward again.

Each member of the group is written separately, and every write patched the
live GSAP tween in place and then seeked the player. A seek re-renders the
WHOLE timeline, not the tween that changed, so the members still queued
behind that write got repainted from their un-patched tweens: back to their
pre-drag position, where they sat until their own write landed. Only members
whose tween actually renders at the playhead showed it, which is why a group
of three flashed one element and left the others still.

The group commit now defers the seek for every member but the last, so the
queued members keep the transform the gesture left on them and the whole
group repaints once, from the fully patched timeline.
This commit is contained in:
Miguel Angel Simon Sierra
2026-08-09 19:41:51 -04:00
parent 560ff338db
commit 30b651335a
7 changed files with 89 additions and 4 deletions
@@ -524,6 +524,7 @@ export function restoreManualOffsetDragMembers(members: ManualOffsetDragMember[]
}
}
/** Teardown after a COMMITTED drag. */
export function endManualOffsetDragMembers(members: ManualOffsetDragMember[]): void {
for (const member of members) {
endStudioManualEditGesture(member.element, member.gestureToken);
@@ -552,6 +553,7 @@ export function endManualOffsetDragMembers(members: ManualOffsetDragMember[]): v
}
}
/** Release the timelines this gesture paused, re-rendering at the playhead. */
export function resumeGsapTimelines(element: HTMLElement): void {
const ids = element.getAttribute("data-hf-drag-paused-timelines");
element.removeAttribute("data-hf-drag-paused-timelines");
@@ -523,3 +523,46 @@ describe("patchRuntimeTweenInPlace — composition isolation", () => {
expect(otherTween.invalidate).not.toHaveBeenCalled();
});
});
describe("patchRuntimeTweenInPlace — deferSeek", () => {
/**
* A group drag commits one member at a time. Each in-place patch used to seek,
* and a seek re-renders the WHOLE timeline — so every member still queued behind
* the current one got repainted from its un-patched tween, back to where it sat
* before the drag, and stayed there until its own patch landed. That is the jump.
*/
it("does not seek while a group commit is still writing its other members", () => {
const a = { id: "a" };
const rendered = { a: 0, b: 0 };
const tweenA = makeTween({ vars: { x: 0 }, targetIds: ["a"], duration: 0 }, a);
const tweenB = makeTween({ vars: { x: 0 }, targetIds: ["b"], duration: 0 }, a);
const { iframe, seek } = fakeIframe(a, [tweenA, tweenB], {
onSeek: () => {
rendered.a = tweenA.vars.x as number;
rendered.b = tweenB.vars.x as number;
},
});
const first = patchRuntimeTweenInPlace(
iframe,
"#a",
{ kind: "set", props: { x: 500 } },
undefined,
true,
);
expect(first).toBe(true);
expect(tweenA.vars.x).toBe(500);
// No repaint yet: "b" keeps the transform the gesture left on it instead of
// being rendered from its own tween, which still holds the pre-drag value.
expect(seek).not.toHaveBeenCalled();
expect(rendered).toEqual({ a: 0, b: 0 });
tweenB.vars.x = 600;
const last = patchRuntimeTweenInPlace(iframe, "#a", { kind: "set", props: { x: 500 } });
expect(last).toBe(true);
expect(seek).toHaveBeenCalledTimes(1);
expect(rendered).toEqual({ a: 500, b: 600 });
});
});
+11 -1
View File
@@ -277,12 +277,16 @@ function applyChange(tween: RuntimeTween, change: RuntimeTweenChange): boolean {
/**
* Edit one tween in `window.__timelines` in place + re-seek to the current playhead.
* Returns `true` on a confident patch, `false` otherwise (caller soft-reloads).
*
* `deferSeek` skips the re-render, for a caller patching several tweens in a row
* that will render once after the last one.
*/
export function patchRuntimeTweenInPlace(
iframe: HTMLIFrameElement | null,
selector: string,
change: RuntimeTweenChange,
compositionId?: string,
deferSeek = false,
): boolean {
if (!iframe) return false;
// A base `gsap.set` has no timeline tween to resolve — apply the value straight
@@ -312,7 +316,13 @@ export function patchRuntimeTweenInPlace(
if (change.kind !== "keyframe-rebuild") {
tween.invalidate?.();
}
seekToCurrent(iframe, timeline);
// A seek re-renders the WHOLE timeline, not just the tween we patched. Under a
// multi-element commit that is a visible jump: the members still queued behind
// this one get repainted from their un-patched tweens, back to where they were
// before the gesture, and stay there until their own patch lands. Deferring
// leaves them showing the gesture's own transform, and the caller's last patch
// seeks once for the whole group.
if (!deferSeek) seekToCurrent(iframe, timeline);
return true;
} catch {
return false;
@@ -22,6 +22,16 @@ export interface CommitMutationOptions {
coalesceMs?: number;
softReload?: boolean;
skipReload?: boolean;
/**
* Write the source but leave the preview alone; the caller renders once when it
* is done. For a multi-write action like a group drag, rendering after each
* write shows a source where the members not yet written still hold their old
* values, so they snap back until their own write lands. This also defers the
* in-place runtime patch's seek, which re-renders the whole timeline and repaints
* the queued members the same way. Unlike `skipReload` this changes nothing about
* error handling — a failed write still throws.
*/
deferPreviewSync?: boolean;
beforeReload?: () => void;
/**
* Serialize this commit against others sharing the same key. Used to chain
@@ -155,11 +155,20 @@ export function useGsapAwareEditing({
// it survives the N sequential server round-trips) onto each commit —
// otherwise each member records its own entry and it takes N presses to undo.
const coalesceKey = `group-drag:${++groupDragCommitCounter}`;
// Members are written one at a time, and a write that re-renders the preview
// re-runs the whole script — which still holds the OLD position of every
// member not yet written. Those members snap back to where they started and
// stay there until their own write lands, which is the single element seen
// jumping mid-commit while the rest of the group sat still. The drafted
// positions are already on screen, so holding the render until the last
// member has been written costs nothing and never shows a half-moved group.
let renderOnCommit = false;
const coalescedCommit: typeof gsapCommitMutation = (selection, mutation, options) =>
gsapCommitMutation(selection, mutation, {
...options,
coalesceKey,
coalesceMs: Number.POSITIVE_INFINITY,
deferPreviewSync: !renderOnCommit,
});
const preflightAnimations = new Map<DomEditSelection, GsapAnimation[]>();
// Editability is user-atomic: prove every member can be written before
@@ -185,7 +194,8 @@ export function useGsapAwareEditing({
throw error;
}
}
for (const { selection, next } of updates) {
for (const [index, { selection, next }] of updates.entries()) {
renderOnCommit = index === updates.length - 1;
try {
const outcome = await tryGsapDragIntercept(
selection,
@@ -76,7 +76,10 @@ describe("applyPreviewSync", () => {
expect(patchRuntimeTweenInPlace).toHaveBeenCalledWith(FAKE_IFRAME, "#a", {
kind: "set",
props: { x: 10 },
});
},
undefined,
false,
);
expect(applySoftReload).not.toHaveBeenCalled();
expect(reloadPreview).not.toHaveBeenCalled();
});
@@ -341,7 +344,10 @@ describe("runCommit — instantPatch wiring", () => {
expect(patchRuntimeTweenInPlace).toHaveBeenCalledWith(FAKE_IFRAME, "#a", {
kind: "set",
props: { x: 485, y: 311 },
});
},
undefined,
false,
);
expect(deps.reloadPreview).not.toHaveBeenCalled();
});
@@ -254,6 +254,8 @@ export function applyPreviewSync(
iframe,
options.instantPatch.selector,
options.instantPatch.change,
undefined,
options.deferPreviewSync === true,
);
// Patched in place — element is already correct on screen; no reload needed.
if (patched) return;
@@ -262,6 +264,8 @@ export function applyPreviewSync(
trackStudioEvent("gsap_instant_patch_fallback", { selector: options.instantPatch.selector });
// Fall through to the soft/full reload path below.
}
// Written, but the caller has more writes to make and will render after the last.
if (options.deferPreviewSync) return;
if (options.softReload && result.scriptText) {
// A soft-reloadable edit escalates to a full iframe remount ONLY on the
// PERMANENT "cannot-soft-reload" result (the preview is genuinely stale/