@hyperframes/studio 0.8.90 → 0.8.91

package/src/hooks/gsapRuntimeBridge.sharedTween.test.ts

@@ -0,0 +1,157 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { tryGsapDragIntercept } from "./gsapRuntimeBridge";
+
+const WORDS = ["How", "we", "build", "videos", "at", "scale", "every", "day"];
+
+function mountPhrase(): HTMLElement[] {
+  document.body.innerHTML = `<h1>${WORDS.map(
+    (word, i) => `<span class="w" data-hf-id="hf-w${i}">${word}</span>`,
+  ).join("")}</h1>`;
+  return [...document.querySelectorAll<HTMLElement>(".w")];
+}
+
+function wordSelection(element: HTMLElement, index: number): DomEditSelection {
+  return {
+    selector: ".w",
+    selectorIndex: index,
+    hfId: element.getAttribute("data-hf-id") ?? undefined,
+    element,
+  } as unknown as DomEditSelection;
+}
+
+// One staggered entrance on the shared class, the way generated titles are written.
+const staggerIn = {
+  id: ".w-from-200",
+  targetSelector: ".w",
+  method: "from",
+  properties: { y: 60, opacity: 0 },
+  position: 0.2,
+  resolvedStart: 0.2,
+  duration: 0.6,
+  stagger: 0.08,
+} as unknown as GsapAnimation;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  vi.restoreAllMocks();
+});
+
+describe("tryGsapDragIntercept: one word of a staggered phrase", () => {
+  it("leaves the shared tween alone and hands the move to that word's own offset", async () => {
+    const words = mountPhrase();
+    const commitMutation = vi.fn();
+    const outcome = await tryGsapDragIntercept(
+      wordSelection(words[0]!, 0),
+      { x: -40, y: 0 },
+      [staggerIn],
+      null,
+      commitMutation,
+      async () => [staggerIn],
+    );
+    expect(outcome).toEqual({ status: "element-offset" });
+    expect(commitMutation).not.toHaveBeenCalled();
+  });
+
+  it("still edits a tween that targets only the dragged word", async () => {
+    const words = mountPhrase();
+    const own = { ...staggerIn, id: "own", targetSelector: '[data-hf-id="hf-w0"]' };
+    const commitMutation = vi.fn();
+    const outcome = await tryGsapDragIntercept(
+      wordSelection(words[0]!, 0),
+      { x: -40, y: 0 },
+      [own as GsapAnimation],
+      null,
+      commitMutation,
+      async () => [own as GsapAnimation],
+    );
+    expect(outcome.status).toBe("persisted");
+    expect(commitMutation).toHaveBeenCalled();
+  });
+});
+
+describe("tryGsapDragIntercept: which tweens a word's drag may use", () => {
+  it("edits the word's own position tween, not the shared one, when it has both", async () => {
+    const words = mountPhrase();
+    const own = {
+      ...staggerIn,
+      id: "own",
+      method: "set",
+      targetSelector: '[data-hf-id="hf-w0"]',
+      properties: { x: 10, y: 0 },
+      duration: 0,
+      propertyGroup: "position",
+    } as unknown as GsapAnimation;
+    const commitMutation = vi.fn();
+    const outcome = await tryGsapDragIntercept(
+      wordSelection(words[0]!, 0),
+      { x: -40, y: 0 },
+      [staggerIn, own],
+      null,
+      commitMutation,
+      async () => [staggerIn, own],
+    );
+    expect(outcome.status).toBe("persisted");
+    const touched = commitMutation.mock.calls.map((call) => JSON.stringify(call[1]));
+    expect(touched.length).toBeGreaterThan(0);
+    expect(touched.every((m) => !m.includes(staggerIn.id))).toBe(true);
+    expect(touched.some((m) => m.includes('"own"'))).toBe(true);
+  });
+
+  it("ignores a tween whose target never reaches the word", async () => {
+    document.body.innerHTML = `<div id="title"><span class="w">A</span><span class="w">B</span></div>
+      <div id="subtitle"><span class="w" data-hf-id="hf-s0">C</span></div>`;
+    const word = document.querySelector<HTMLElement>('[data-hf-id="hf-s0"]')!;
+    const titleOnly = { ...staggerIn, id: "title-only", targetSelector: "#title .w" };
+    const commitMutation = vi.fn();
+    const outcome = await tryGsapDragIntercept(
+      wordSelection(word, 2),
+      { x: -40, y: 0 },
+      [titleOnly as GsapAnimation],
+      null,
+      commitMutation,
+      async () => [titleOnly as GsapAnimation],
+    );
+    expect(outcome.status).toBe("persisted");
+    const touched = commitMutation.mock.calls.map((call) => JSON.stringify(call[1]));
+    expect(touched.every((m) => !m.includes("title-only"))).toBe(true);
+  });
+});
+
+describe("tryGsapDragIntercept: one drag is one undo step", () => {
+  it("records the split and the move under one gesture key", async () => {
+    document.body.innerHTML = `<div id="hero"></div>`;
+    const hero = document.getElementById("hero")!;
+    const mixed = {
+      id: "#hero-fromTo-0",
+      targetSelector: "#hero",
+      method: "fromTo",
+      fromProperties: { x: 0, opacity: 0 },
+      properties: { x: 100, opacity: 1 },
+      position: 0,
+      resolvedStart: 0,
+      duration: 1,
+    } as unknown as GsapAnimation;
+    const split = [
+      { ...mixed, id: "#hero-fromTo-0-position", propertyGroup: "position" },
+      { ...mixed, id: "#hero-fromTo-0-opacity", propertyGroup: "opacity" },
+    ] as GsapAnimation[];
+    let fetches = 0;
+    const commitMutation = vi.fn();
+    await tryGsapDragIntercept(
+      { id: "hero", selector: "#hero", element: hero } as unknown as DomEditSelection,
+      { x: 20, y: 0 },
+      [mixed],
+      null,
+      commitMutation,
+      async () => (fetches++ === 0 ? [mixed] : split),
+    );
+    const options = commitMutation.mock.calls.map((call) => call[2]);
+    expect(options.length).toBeGreaterThan(1);
+    expect(new Set(options.map((o) => o.coalesceKey)).size).toBe(1);
+    expect(options[0].coalesceKey).toMatch(/^gsap:drag:/);
+    expect(options.every((o) => o.coalesceMs === Number.POSITIVE_INFINITY)).toBe(true);
+  });
+});

package/src/hooks/gsapRuntimeBridge.ts

@@ -24,6 +24,8 @@ import {
   materializeIfDynamic,
 } from "./gsapDragCommit";
 import { commitWholePropertyOffset } from "./gsapWholePropertyOffsetCommit";
+import { isGestureTransactionCommit } from "./gestureTransaction";
+import { tweenReach, tweensForThisElement } from "./gsapTweenReach";
 import { resolveTweenDuration } from "../utils/globalTimeCompiler";
 import type { GsapDragCommitCallbacks } from "./gsapDragCommit";
 import { isInstantHold, selectorFromSelection, writeTargetSelector } from "./gsapShared";
@@ -128,12 +130,18 @@ export async function resolveGroupTween(
 
 export type { GsapDragCommitCallbacks };
 
-/**
- * Attempt to handle a drag commit via the GSAP script mutation path.
- *
- * Returns an explicit persisted/blocked outcome. Callers must reject blocked
- * outcomes so the gesture layer restores its runtime and overlay drafts.
- */
+const writesPosition = (a: GsapAnimation) => animationWritesAnyProperty(a, POSITION_CHANNEL_SET);
+
+/** Only a tween shared with siblings positions this element (a stagger on `.w`). */
+function positionedOnlyBySharedTween(selection: DomEditSelection, animations: GsapAnimation[]) {
+  const positioning = animations.filter(writesPosition);
+  return (
+    positioning.some((a) => tweenReach(a, selection.element) === "shared") &&
+    tweensForThisElement(selection, positioning).length === 0
+  );
+}
+
+// fallow-ignore-next-line complexity
 async function preflightGsapDragIntercept(
   selection: DomEditSelection,
   animations: GsapAnimation[],
@@ -161,9 +169,18 @@ export function dragEditOutcome(
   // set as well: ignoring it would let a transient fetch failure bypass helper /
   // runtime-source ownership and reach a destructive split or property write.
   const allKnownAnimations = [...animations, ...fetchedAnimations];
-  const editability = directEditOutcomeForProperties(allKnownAnimations, POSITION_CHANNEL_SET);
+  const reaching = allKnownAnimations.filter(
+    (a) => tweenReach(a, selection.element) !== "elsewhere",
+  );
+  const editability = directEditOutcomeForProperties(reaching, POSITION_CHANNEL_SET);
   if (editability.status === "blocked") return editability;
-  const sourceAnimations = fetchedAnimations.length > 0 ? fetchedAnimations : animations;
+  if (positionedOnlyBySharedTween(selection, allKnownAnimations)) {
+    return { status: "element-offset" };
+  }
+  const sourceAnimations = tweensForThisElement(
+    selection,
+    fetchedAnimations.length > 0 ? fetchedAnimations : animations,
+  );
   // In a group only a tween naming this member by id or by its own selector counts,
   // so a class tween shared with id-selected members cannot take one member's write.
   const positionSources = group
@@ -187,13 +204,28 @@ export function dragEditOutcome(
   return { status: "persisted" };
 }
 
+let dragGestureCounter = 0;
+
+/** Every write one drag makes (a split, then the move) records as ONE undo step. A
+ *  transaction or group commit already owns its key. */
+function oneUndoStep(
+  commit: GsapDragCommitCallbacks["commitMutation"],
+): GsapDragCommitCallbacks["commitMutation"] {
+  if (isGestureTransactionCommit(commit)) return commit;
+  const coalesceKey = `gsap:drag:${++dragGestureCounter}`;
+  return (selection, mutation, options) =>
+    commit(selection, mutation, { ...options, coalesceKey, coalesceMs: Number.POSITIVE_INFINITY });
+}
+
+/** Commits a drag through the GSAP script. Callers reject `blocked` (the gesture layer
+ *  restores its drafts) and save `element-offset` on the element itself. */
 export async function tryGsapDragIntercept(
   selection: DomEditSelection,
   offset: { x: number; y: number },
-  animations: GsapAnimation[],
+  allAnimations: GsapAnimation[],
   iframe: HTMLIFrameElement | null,
-  commitMutation: GsapDragCommitCallbacks["commitMutation"],
-  fetchFallbackAnimations?: () => Promise<GsapAnimation[]>,
+  gestureCommit: GsapDragCommitCallbacks["commitMutation"],
+  fetchAllAnimations?: () => Promise<GsapAnimation[]>,
   options?: {
     altKey?: boolean;
     preflightOnly?: boolean;
@@ -204,16 +236,20 @@ export async function tryGsapDragIntercept(
   if (!options?.preflightPassed) {
     const preflight = await preflightGsapDragIntercept(
       selection,
-      animations,
+      allAnimations,
       iframe,
-      fetchFallbackAnimations,
+      fetchAllAnimations,
       options?.group,
     );
-    if (preflight.status === "blocked" || options?.preflightOnly) return preflight;
+    if (preflight.status !== "persisted" || options?.preflightOnly) return preflight;
   }
+  const animations = tweensForThisElement(selection, allAnimations);
+  const fetchFallbackAnimations =
+    fetchAllAnimations && (async () => tweensForThisElement(selection, await fetchAllAnimations()));
   const selector = selectorFromSelection(selection);
   // The preflight above proves this; retain a defensive result for DOM churn.
   if (!selector) return { status: "blocked", reason: "no-selector" };
+  const commitMutation = oneUndoStep(gestureCommit);
 
   // Self-heal: enforce a single position write BEFORE committing. A corrupted
   // file can carry 2+ conflicting position writes for one selector (e.g. a

package/src/hooks/gsapShared.test.ts

@@ -195,7 +195,7 @@ describe("resolveClipTimingBasis", () => {
   it("rebases an expanded sub-comp child by its host mount", () => {
     // Expanded children carry host-ABSOLUTE display starts; the tweens they own are
     // still composition-local, so the basis is the child's local start.
-    const pill = { id: "pill", domId: "pill", start: 8, duration: 4, expandedParentStart: 6 };
+    const pill = { id: "pill", domId: "pill", start: 8, duration: 4, parentCompositionStart: 6 };
     expect(resolveClipTimingBasis("pill", "scene.html", [pill], [])).toEqual({
       elStart: 2,
       elDuration: 4,

package/src/hooks/gsapShared.ts

@@ -10,6 +10,7 @@ import {
   resolveTweenStart,
   resolveTweenDuration,
 } from "../utils/globalTimeCompiler";
+import { toCompositionTime } from "../player/store/timelineElement";
 
 // ── Types ─────────────────────────────────────────────────────────────────────
 
@@ -165,14 +166,16 @@ export function resolveSelectorElementIds(
 }
 
 /**
- * The clip start in the frame the element's OWN tweens are measured in. An
- * expanded sub-composition child sits on the master timeline at a host-absolute
- * `start`, but its tweens are parsed from its own source file and are local to
- * it, so the two must be brought into one frame before any clip-% math — or
- * every keyframe rebases to a percentage far outside the clip.
+ * The clip start in the frame the element's OWN tweens are measured in. A nested
+ * row sits on the master timeline at a master `start`, but its tweens are local
+ * to its composition, so the two must be brought into one frame before any clip-%
+ * math — or every keyframe rebases to a percentage far outside the clip.
  */
-export function clipTimingStart(element: { start: number; expandedParentStart?: number }): number {
-  return element.start - (element.expandedParentStart ?? 0);
+export function clipTimingStart(element: {
+  start: number;
+  parentCompositionStart?: number;
+}): number {
+  return toCompositionTime(element, element.start);
 }
 
 export function selectorFromSelection(selection: DomEditSelection): string | null {
@@ -476,8 +479,8 @@ export function toAbsoluteTime(tweenPos: number, tweenDur: number, percentage: n
  * timeline element's start is main-timeline absolute, so passing the raw element
  * start subtracted two different frames from each other: a host mounted at 1.5s
  * cached its 0s tween at -12%, and a clip-relative percentage can never be
- * negative. The composition's mount is `expandedParentStart` for an expanded
- * child, the parent composition clip's start otherwise, and 0 for a
+ * negative. The composition's mount is the row's `parentCompositionStart` when
+ * set, the parent composition clip's start otherwise, and 0 for a
  * root-composition element, whose start already IS the tween frame.
  */
 export function resolveClipTimingBasis(
@@ -489,7 +492,7 @@ export function resolveClipTimingBasis(
     id: string;
     start: number;
     duration: number;
-    expandedParentStart?: number;
+    parentCompositionStart?: number;
     parentCompositionId?: string | null;
   }>,
   domClipChildren: ReadonlyArray<{ id: string; hostId: string }>,
@@ -502,8 +505,9 @@ export function resolveClipTimingBasis(
     const parent = parentId
       ? elements.find((el) => el.domId === parentId || el.id === parentId)
       : undefined;
-    const mount = direct.expandedParentStart ?? parent?.start;
-    if (mount !== undefined) return { elStart: direct.start - mount, elDuration: direct.duration };
+    if (direct.parentCompositionStart !== undefined)
+      return { elStart: clipTimingStart(direct), elDuration: direct.duration };
+    if (parent) return { elStart: direct.start - parent.start, elDuration: direct.duration };
     // No parent composition named, so this IS a main-timeline clip and its own
     // start is already the basis.
     if (!parentId) return { elStart: direct.start, elDuration: direct.duration };

package/src/hooks/gsapTweenReach.ts

@@ -0,0 +1,30 @@
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+
+type TweenReach = "own" | "shared" | "elsewhere" | "unknown";
+
+/** Which elements a tween's target resolves to in the live preview, relative to `el`. */
+export function tweenReach(animation: GsapAnimation, el: Element | null | undefined): TweenReach {
+  const doc = el?.ownerDocument;
+  if (!el?.isConnected || !doc || animation.hasUnresolvedSelector) return "unknown";
+  let hits: Element[];
+  try {
+    hits = [...doc.querySelectorAll(animation.targetSelector)];
+  } catch {
+    return "unknown";
+  }
+  if (!hits.includes(el)) return "elsewhere";
+  return hits.length === 1 ? "own" : "shared";
+}
+
+/** The tweens a one-element edit may rewrite: not one shared with siblings, nor one
+ *  that never reaches the element. */
+export function tweensForThisElement(
+  selection: DomEditSelection,
+  animations: GsapAnimation[],
+): GsapAnimation[] {
+  return animations.filter((a) => {
+    const reach = tweenReach(a, selection.element);
+    return reach === "own" || reach === "unknown";
+  });
+}

package/src/hooks/timelineEditingHelpers.ts

@@ -1,4 +1,5 @@
 import { type TimelineElement, usePlayerStore } from "../player/store/playerStore";
+import { toAuthoredStart } from "../player/store/timelineElement";
 import {
   applyPatchByTarget,
   findTagByTarget,
@@ -274,7 +275,7 @@ export function buildTimelineResizeTimingPatch(
   let patched = applyPatchByTarget(original, target, {
     type: "attribute",
     property: "start",
-    value: formatTimelineAttributeNumber(updates.start),
+    value: formatTimelineAttributeNumber(toAuthoredStart(element, updates.start)),
   });
   patched = applyPatchByTarget(patched, target, {
     type: "attribute",

package/src/hooks/useClipboard.source.test.ts

@@ -336,6 +336,64 @@ describe("copy order", () => {
   });
 });
 
+describe("duplicate of a clip inside a sub-composition", () => {
+  it("writes the copy at local time right after the original", async () => {
+    // Host at 2 s, so the clip's local 1-3 s shows as a 3-5 s master row.
+    const sub: TimelineElement = {
+      id: SUB_HF_ID,
+      hfId: SUB_HF_ID,
+      tag: "h2",
+      start: 3,
+      duration: 2,
+      track: 0,
+      authoredTrack: 0,
+      sourceFile: "compositions/sub.html",
+      parentCompositionStart: 2,
+    };
+    usePlayerStore.setState({
+      elements: [TITLE, sub],
+      selectedElementId: sub.id,
+      selectedElementIds: new Set([sub.id]),
+    });
+    const { clipboard, writes } = mountClipboard(null, SUB, (host) =>
+      host.setAttribute("data-start", "2"),
+    );
+    await clipboard().handleDuplicate();
+    const starts = [...(writes[0] ?? "").matchAll(/<h2[^>]*data-start="([^"]+)"/g)].map(
+      (m) => m[1],
+    );
+    expect(starts.sort()).toEqual(["1", "3"]);
+  });
+
+  it("moves the copy off a lane its own file already fills right after the original", async () => {
+    // Host at 10 s: the clip is local 1-3 (master 11-13); its neighbour is local 3-5,
+    // exactly where the copy lands, so the lane check must compare in local time.
+    const sub: TimelineElement = {
+      id: SUB_HF_ID,
+      hfId: SUB_HF_ID,
+      tag: "h2",
+      start: 11,
+      duration: 2,
+      track: 0,
+      authoredTrack: 0,
+      sourceFile: "compositions/sub.html",
+      parentCompositionStart: 10,
+    };
+    const neighbour: TimelineElement = { ...sub, id: "next", hfId: "next", start: 13 };
+    usePlayerStore.setState({
+      elements: [TITLE, sub, neighbour],
+      selectedElementId: sub.id,
+      selectedElementIds: new Set([sub.id]),
+    });
+    const { clipboard, writes } = mountClipboard(null, SUB, (host) =>
+      host.setAttribute("data-start", "10"),
+    );
+    await clipboard().handleDuplicate();
+    const copy = /<h2[^>]*data-start="3"[^>]*>/.exec(writes[0] ?? "")?.[0] ?? "";
+    expect(copy).toContain('data-track-index="1"');
+  });
+});
+
 describe("a copy that fails", () => {
   it("leaves the previous copy on the clipboard", async () => {
     selectTitle();

package/src/hooks/useClipboard.ts

@@ -2,6 +2,7 @@ import { useCallback, useRef } from "react";
 import { EXCLUDED_TAGS, mintHfId, walkCompositionDescendants } from "@hyperframes/parsers/hf-ids";
 import type { TimelineElement } from "../player";
 import { usePlayerStore } from "../player";
+import { toAuthoredStart } from "../player/store/timelineElement";
 import type { DomEditSelection } from "../components/editor/domEditing";
 import {
   type ClipboardPayload,
@@ -416,14 +417,22 @@ export function useClipboard({
     if (!pid) return false;
 
     const { elements } = targets;
-    const targetPath = elements[0]?.sourceFile || activeCompPath || "index.html";
-    const anchorTime = Math.max(...elements.map((el) => el.start + el.duration));
+    const pathOf = (el: TimelineElement) => el.sourceFile || activeCompPath || "index.html";
+    const targetPath = pathOf(elements[0]!);
+    // The copy lands in targetPath's own clock, so anchor and lane check are local to it.
+    const anchorTime = toAuthoredStart(
+      elements[0]!,
+      Math.max(...elements.map((el) => el.start + el.duration)),
+    );
 
     try {
       const clips = await readClips(targets);
       let ids: string[] = [];
       const duplicate = (originalContent: string) => {
-        const liveElements = usePlayerStore.getState().elements;
+        const liveElements = usePlayerStore
+          .getState()
+          .elements.filter((el) => pathOf(el) === targetPath)
+          .map((el) => ({ ...el, start: toAuthoredStart(el, el.start) }));
         const pasted = pasteTimelineClips(originalContent, clips, anchorTime, liveElements);
         ids = pasted.ids;
         return extendRootDurationInSource(pasted.content, pasted.requiredEnd);

package/src/hooks/useCommitPreflightCapabilities.ts

@@ -51,8 +51,8 @@ const MANUAL_FLAGS = [
 /** Null when the commit would go through; "" while the check is still running. */
 function refusal(preflight: CommitPreflight | null, check: keyof CommitPreflight): string | null {
   const outcome = preflight?.[check];
-  if (outcome?.status === "persisted") return null;
-  return outcome ? GSAP_EDIT_BLOCK_COPY[outcome.reason] : "";
+  if (!outcome) return "";
+  return outcome.status === "blocked" ? GSAP_EDIT_BLOCK_COPY[outcome.reason] : null;
 }
 
 /** Closes each manual flag whose commit Studio would refuse, and says why. */

package/src/hooks/useDomEditCommits.ts

@@ -269,6 +269,7 @@ export function useDomEditCommits({
   // ── Geometry commits (path offset, box size, rotation) ──
 
   const {
+    stageElementPositionOffset,
     handleDomPathOffsetCommit,
     handleDomBoxSizeCommit,
     handleDomRotationCommit,
@@ -312,6 +313,7 @@ export function useDomEditCommits({
     handleDomTextFieldStyleCommit,
     handleDomAddTextField,
     handleDomRemoveTextField,
+    stageElementPositionOffset,
     handleDomPathOffsetCommit,
     handleDomBoxSizeCommit,
     handleDomRotationCommit,

package/src/hooks/useDomEditPositionPatchCommit.ts

@@ -4,6 +4,7 @@ import type { PatchOperation } from "../utils/sourcePatcher";
 import { trackStudioSaveFailure } from "../utils/studioSaveDiagnostics";
 import { DomEditSaveQueueOpenError } from "../utils/domEditSaveQueue";
 import type { PersistDomEditOperations } from "./domEditCommitTypes";
+import { wasAlreadyToasted } from "./domEditPersistFailure";
 
 interface UseDomEditPositionPatchCommitParams {
   activeCompPath: string | null;
@@ -39,7 +40,9 @@ export function useDomEditPositionPatchCommit({
           // resolved the commit, which skipped the caller's revert, so the element
           // stayed where the drag put it while nothing reached the file.
           if (error instanceof DomEditSaveQueueOpenError) throw error;
-          showToast(error instanceof Error ? error.message : "Failed to save position");
+          if (!wasAlreadyToasted(error)) {
+            showToast(error instanceof Error ? error.message : "Failed to save position");
+          }
           trackStudioSaveFailure({
             source: "dom_edit",
             error,

package/src/hooks/useDomEditSession.ts

@@ -229,6 +229,7 @@ export function useDomEditSession({
     handleDomTextFieldStyleCommit,
     handleDomAddTextField,
     handleDomRemoveTextField,
+    stageElementPositionOffset,
     handleDomBoxSizeCommit,
     handleDomManualEditsReset,
     handleDomEditElementsDelete,
@@ -487,6 +488,7 @@ export function useDomEditSession({
     bumpGsapCache,
     makeFetchFallback,
     trackGsapInteractionFailure,
+    stageElementPositionOffset,
     handleDomBoxSizeCommit,
     addGsapAnimation,
     convertToKeyframes,

package/src/hooks/useDomGeometryCommit.test.tsx

@@ -224,3 +224,105 @@ describe("useDomGeometryCommit, from the package entry", () => {
     unmount();
   });
 });
+
+describe("useDomGeometryCommit, one word of a staggered phrase", () => {
+  const WORDS = ["How", "we", "build", "videos", "at", "scale", "every", "day"];
+  const PHRASE = WORDS.map((w, i) => `<span class="w" data-hf-id="hf-w${i}">${w}</span>`).join("");
+
+  function stubPhraseServer(patchStatuses: number[] = []) {
+    const calls = { patches: [] as unknown[], gsapMutations: [] as unknown[] };
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+        const url = String(input instanceof Request ? input.url : input);
+        const json = (body: unknown) =>
+          new Response(JSON.stringify(body), { headers: { "content-type": "application/json" } });
+        if (url.includes("/api/projects/p1/gsap-animations/")) {
+          return json({
+            animations: [
+              {
+                id: ".w-from-200",
+                targetSelector: ".w",
+                method: "from",
+                position: 0.2,
+                duration: 0.6,
+                properties: { y: 60, opacity: 0 },
+              },
+            ],
+          });
+        }
+        if (url.includes("/api/projects/p1/files/")) return json({ content: PHRASE });
+        if (url.includes("/api/projects/p1/file-mutations/patch-element/")) {
+          calls.patches.push(JSON.parse(String(init?.body)));
+          const status = patchStatuses.shift();
+          if (status) {
+            return new Response(JSON.stringify({ error: "the file changed on disk" }), {
+              status,
+              headers: { "content-type": "application/json" },
+            });
+          }
+          return json({ ok: true, changed: true, matched: true, content: "AFTER", version: "v2" });
+        }
+        if (url.includes("/api/projects/p1/gsap-mutations/")) {
+          calls.gsapMutations.push(JSON.parse(String(init?.body)));
+          return json({ ok: true, changed: true, before: "B", after: "A" });
+        }
+        throw new Error(`Unexpected fetch: ${url}`);
+      }),
+    );
+    return calls;
+  }
+
+  function mountWord(element: HTMLElement) {
+    element.ownerDocument.body.innerHTML = PHRASE;
+    const word = element.ownerDocument.querySelector<HTMLElement>('[data-hf-id="hf-w0"]')!;
+    Object.defineProperties(word, {
+      offsetLeft: { get: () => 100 + (Number.parseFloat(word.style.left) || 0) },
+      offsetTop: { get: () => 200 + (Number.parseFloat(word.style.top) || 0) },
+    });
+    return { ...makeSelection("How", word), id: undefined, selector: ".w", hfId: "hf-w0" };
+  }
+
+  it("saves left/top on the dragged word only and never rewrites the shared tween", async () => {
+    const calls = stubPhraseServer();
+    const { element, recordEdit, hook, unmount } = renderHost();
+    const selection = mountWord(element);
+
+    await expect(hook().commitPathOffset(selection, { x: 40, y: 20 })).resolves.toEqual({
+      ok: true,
+    });
+
+    expect(calls.gsapMutations).toHaveLength(0);
+    expect(calls.patches).toEqual([
+      expect.objectContaining({
+        target: expect.objectContaining({ hfId: "hf-w0" }),
+        operations: [
+          { type: "inline-style", property: "position", value: "relative" },
+          { type: "inline-style", property: "left", value: "40px" },
+          { type: "inline-style", property: "top", value: "20px" },
+        ],
+      }),
+    ]);
+    expect(recordEdit).toHaveBeenCalledTimes(1);
+    unmount();
+  });
+
+  it("saves a later move after a conflict refused the first, and says what happened", async () => {
+    const calls = stubPhraseServer([409]);
+    const showToast = vi.fn();
+    const { element, recordEdit, hook, unmount } = renderHost({ showToast });
+    const selection = mountWord(element);
+
+    await expect(hook().commitPathOffset(selection, { x: 40, y: 20 })).rejects.toThrow();
+    expect(showToast.mock.calls.map((call) => call[0])).toEqual([
+      "Couldn't save edit: the file changed on disk",
+    ]);
+    await expect(hook().commitPathOffset(selection, { x: 40, y: 20 })).resolves.toEqual({
+      ok: true,
+    });
+
+    expect(calls.patches).toHaveLength(2);
+    expect(recordEdit).toHaveBeenCalledTimes(1);
+    unmount();
+  });
+});