@hyperframes/studio 0.8.125 → 0.8.127

package/src/components/editor/MotionPathOverlay.tsx

@@ -1,18 +1,18 @@
-import { observeGsapGesture } from "../../hooks/gsapGestureOutcome";
-import { trackPreviewEditResult } from "../../utils/previewFeatureUsage";
 import { scopedElementKey } from "../../hooks/gsapKeyframeCacheHelpers";
 import { memo, useEffect, useRef, useState, type RefObject } from "react";
 import type { DomEditSelection } from "./domEditing";
 import { useDomEditContext } from "../../contexts/DomEditContext";
+import { useStudioShellContextOptional } from "../../contexts/StudioContext";
+import { useGsapInteractionFailureTelemetry } from "../../hooks/useGsapInteractionFailureTelemetry";
 import { usePlayerStore } from "../../player/store/playerStore";
 import { useLivePreviewIframe } from "../../player/store/previewIframeStore";
 import { parkPlayheadOnKeyframe } from "../../hooks/gsapDragCommit";
-import { commitWholePropertyOffset } from "../../hooks/gsapWholePropertyOffsetCommit";
-import { nearestPointOnPath, type MotionNodeRef } from "./motionPathGeometry";
+import { nearestPointOnPath, nodeCentre, type MotionNodeRef } from "./motionPathGeometry";
 import { editableAnimationId, selectorFor } from "./motionPathSelection";
-import { dotRadius, pressBelongsToLayer, pressSelectedLayer } from "./motionPathLayerNode";
+import { controlForNode, controlUnder, pressControl } from "./motionPathLayerNode";
 import { readGsapPositionFromIframe } from "../../hooks/gsapPositionDetection";
-import { ACCENT, MotionPathNode } from "./MotionPathNode";
+import { isHtmlElement } from "@hyperframes/core/runtime/dom-realm";
+import { ACCENT, MotionPathLine, MotionPathNode } from "./MotionPathNode";
 import {
   KeyframeDiamondContextMenu,
   type KeyframeDiamondContextMenuState,
@@ -22,16 +22,12 @@ import {
   commitAddKeyframe,
   commitAddWaypoint,
   commitCreatePath,
-  commitNode,
+  commitNodeDrop,
   commitRemoveWaypoint,
+  nodeDropLabel,
 } from "./motionPathCommit";
-import {
-  elementHome,
-  hasMotionPathPlugin,
-  isPreviewHtmlElement,
-  transformWDivisor,
-  useMotionPathData,
-} from "./useMotionPathData";
+import { elementHome } from "./motionPathHome";
+import { hasMotionPathPlugin, transformWDivisor, useMotionPathData } from "./useMotionPathData";
 
 interface MotionPathOverlayProps {
   iframeRef: RefObject<HTMLIFrameElement | null>;
@@ -70,6 +66,7 @@ const NODE_PX = 6; // node radius in screen pixels (kept constant across zoom)
 // (select the keyframe); at or above it the gesture commits a move. Screen-space
 // (not composition px) so it behaves identically at any zoom.
 const DRAG_THRESHOLD_PX = 3;
+const noToast = () => {};
 
 /**
  * Draws the selected element's GSAP motion path over the canvas — a dashed
@@ -95,12 +92,18 @@ export const MotionPathOverlay = memo(function MotionPathOverlay({
     handleGsapRemoveAllKeyframes,
     handleGsapMoveKeyframeToPlayhead,
   } = useDomEditContext();
+  const shell = useStudioShellContextOptional();
+  const reportFailure = useGsapInteractionFailureTelemetry(
+    shell?.activeCompPath ?? null,
+    shell?.showToast ?? noToast,
+  );
   const { rect, geometry, geometryResolved, visibleInPreview, home, pScale } = useMotionPathData(
     iframeRef,
     selectorFor(selection),
   );
   const [draft, setDraft] = useState<Draft | null>(null);
   const [ghost, setGhost] = useState<{ x: number; y: number; segIndex: number } | null>(null);
+  const [lineCursor, setLineCursor] = useState("copy");
   const [hoverNode, setHoverNode] = useState<number | null>(null);
   // Right-click context menu on a path node — same delete actions as the
   // timeline keyframe diamond. The node it was opened on rides along, because
@@ -194,7 +197,7 @@ export const MotionPathOverlay = memo(function MotionPathOverlay({
       // Resolve the element LIVE from the current iframe document — the selected
       // node may be detached after a soft-reload, which would skew home.
       const live = frame.contentDocument?.querySelector(createSelector);
-      if (!isPreviewHtmlElement(live, frame)) return;
+      if (!isHtmlElement(live)) return;
       e.stopPropagation();
       e.preventDefault();
       const sc = r.width / compW;
@@ -284,12 +287,12 @@ export const MotionPathOverlay = memo(function MotionPathOverlay({
   // pivot (transform-origin), so it stays put; only the offsets foreshorten. 2D
   // elements have pScale = 1 (no change). Inverse (de-magnify) applied wherever a
   // pointer position is mapped back to a stored offset (create + node drag).
-  const abs = nodes.map((n) => ({
-    ...n,
-    ax: home.x + n.x * pScale,
-    ay: home.y + n.y * pScale,
-  }));
+  const abs = nodes.map((n) => {
+    const c = nodeCentre(n, home, pScale);
+    return { ...n, ax: c.x, ay: c.y };
+  });
   const points = abs.map((p) => `${p.ax},${p.ay}`).join(" ");
+  const startAt = geometry.start && nodeCentre(geometry.start, home, pScale);
   // Map a VIEWPORT pointer to composition space. Use the iframe's LIVE viewport
   // rect, not `rect` — `rect.left/top` are stored pan-surface-relative (for the
   // absolute-positioned SVG), so subtracting them from a viewport clientX/Y would
@@ -313,9 +316,7 @@ export const MotionPathOverlay = memo(function MotionPathOverlay({
     if (e.button !== 0) return;
     e.stopPropagation();
     const live = readGsapPositionFromIframe(iframeRef.current, selectorFor(selection) ?? "");
-    const dotR = dotRadius(nodeR, ref.type === "keyframe" && ref.pct === activeKeyframePct);
-    if (pressBelongsToLayer(e, clientToComp(e), abs[index]!, dotR, live) && pressSelectedLayer(e))
-      return;
+    if (pressControl(e, controlForNode(e, abs[index]!, live))) return;
     (e.target as Element).setPointerCapture(e.pointerId);
     dragRef.current = {
       index,
@@ -378,36 +379,19 @@ export const MotionPathOverlay = memo(function MotionPathOverlay({
     // high zoom) would commit an identical value — a no-op undo entry. Skip the
     // commit, but don't treat it as a click either (the user did drag).
     if (x === Math.round(d.initX) && y === Math.round(d.initY)) return;
-    // With auto-keyframe off (#1808), dragging a keyframe's node on the motion
-    // path (the common way to nudge a KEYFRAMED element's position on canvas,
-    // since the element renders exactly at its current keyframe) shifts the
-    // whole path instead of moving just that one keyframe.
     const anim =
       d.ref.type === "keyframe" ? selectedGsapAnimations?.find((a) => a.id === animId) : undefined;
-    if (
-      d.ref.type === "keyframe" &&
-      anim &&
-      selection &&
-      !usePlayerStore.getState().autoKeyframeEnabled
-    ) {
-      const writes = observeGsapGesture((_sel, mutation, options) =>
-        commitMutation(mutation, options),
-      );
-      void commitWholePropertyOffset(
-        selection,
-        anim,
-        { x, y },
-        d.ref.pct,
-        iframeRef.current,
-        { commitMutation: writes.commit! },
-        "Move animation path",
-      ).then(() => trackPreviewEditResult("motion_path", "drag", writes.finish()));
-    } else {
-      void commitNode(d.ref, x, y, animId, commitMutation);
-    }
-    // Park the playhead on the edited keyframe's time so the element previews AT
-    // that keyframe. Without it, a playhead sitting before the tween renders the
-    // element's base pose — the edit (correct on the path) looks like it vanished.
+    const label = nodeDropLabel(d.ref);
+    commitNodeDrop({
+      ref: d.ref,
+      at: { x, y },
+      animId,
+      anim,
+      selection,
+      iframe: iframeRef.current,
+      commitMutation,
+    }).catch((error: unknown) => reportFailure(error, selection, "drag", label));
+    // Park on the edited keyframe, or a playhead before the tween hides the edit.
     if (d.ref.type === "keyframe" && anim) {
       parkPlayheadOnKeyframe(anim, d.ref.pct);
     }
@@ -415,15 +399,21 @@ export const MotionPathOverlay = memo(function MotionPathOverlay({
 
   // Ghost "add" affordance: project the cursor onto the path; click inserts.
   const onPathHover = (e: React.PointerEvent) => {
+    const control = controlUnder(e);
+    setLineCursor(control ? getComputedStyle(control).cursor : "copy");
     const c = clientToComp(e);
     const np = nearestPointOnPath(
       c.x,
       c.y,
       abs.map((p) => ({ x: p.ax, y: p.ay })),
     );
-    setGhost(np ? { x: np.x, y: np.y, segIndex: np.segIndex } : null);
+    setGhost(np && !control ? { x: np.x, y: np.y, segIndex: np.segIndex } : null);
   };
   const onPathDown = (e: React.PointerEvent) => {
+    if (pressControl(e, controlUnder(e))) {
+      e.stopPropagation();
+      return;
+    }
     if (!animId) return;
     // Compute the insertion point from the event directly so a click works
     // without (or faster than) a preceding hover.
@@ -434,8 +424,9 @@ export const MotionPathOverlay = memo(function MotionPathOverlay({
       abs.map((p) => ({ x: p.ax, y: p.ay })),
     );
     if (!np) return;
-    const x = Math.round(np.x - home.x);
-    const y = Math.round(np.y - home.y);
+    const [a, b] = [abs[np.segIndex]!, abs[np.segIndex + 1]!];
+    const x = Math.round(a.x + np.t * (b.x - a.x));
+    const y = Math.round(a.y + np.t * (b.y - a.y));
     if (geometry.kind === "arc") {
       e.stopPropagation();
       void commitAddWaypoint(animId, np.segIndex + 1, x, y, commitMutation);
@@ -458,10 +449,8 @@ export const MotionPathOverlay = memo(function MotionPathOverlay({
   };
 
   const elementId = selection?.id ?? null;
-  // Right-click any path node → the timeline's keyframe context menu (delete this
-  // one / delete all), so path nodes are removable in place. Waypoints open it
-  // too: returning early for them let the browser's own context menu open over
-  // the editor overlay, which is never what a right-click on a node should do.
+  // Right-click any path node → the timeline's keyframe menu. Waypoints too, or the
+  // browser's own context menu opens over the editor.
   const onNodeContextMenu = (e: React.MouseEvent, ref: MotionNodeRef) => {
     if (!animId || !elementId || !timelineElement) return;
     e.preventDefault();
@@ -525,39 +514,13 @@ export const MotionPathOverlay = memo(function MotionPathOverlay({
             stroke="transparent"
             strokeWidth={14 / scale}
             className="pointer-events-auto"
-            style={{ cursor: "copy" }}
+            style={{ cursor: lineCursor }}
             onPointerMove={onPathHover}
             onPointerLeave={() => setGhost(null)}
             onPointerDown={onPathDown}
           />
         )}
-        <polyline
-          points={points}
-          fill="none"
-          style={{ stroke: ACCENT }}
-          strokeWidth={1.5}
-          strokeDasharray="5 5"
-          strokeLinejoin="round"
-          strokeLinecap="round"
-          vectorEffect="non-scaling-stroke"
-          opacity={0.85}
-        />
-        {ghost && (
-          <rect
-            x={ghost.x - nodeR * 0.707}
-            y={ghost.y - nodeR * 0.707}
-            width={nodeR * 1.414}
-            height={nodeR * 1.414}
-            rx={nodeR * 0.24}
-            transform={`rotate(45 ${ghost.x} ${ghost.y})`}
-            fill="none"
-            strokeWidth={1.5}
-            strokeDasharray="2 2"
-            vectorEffect="non-scaling-stroke"
-            className="pointer-events-none"
-            style={{ stroke: ACCENT }}
-          />
-        )}
+        <MotionPathLine points={points} start={startAt} ghost={ghost} r={nodeR} />
         {abs.map((p, i) => (
           <MotionPathNode
             key={i}

package/src/components/editor/canvasContextMenuZOrder.ts

@@ -124,17 +124,8 @@ export function readEffectiveZIndex(el: HTMLElement): number {
   return 0;
 }
 
-/**
- * Realm-safe HTMLElement check. The target lives in the preview IFRAME's
- * document, but this module runs in the top window, so `child instanceof
- * HTMLElement` (top-window constructor) is ALWAYS false for iframe elements —
- * which silently emptied the sibling list and left every z-order action
- * permanently disabled. Compare against the element's own realm instead, with
- * a nodeType fallback for detached / cross-realm edge cases.
- */
+/** Any element, asked structurally: the preview's nodes are not this window's. */
 function isElementNode(node: Node): node is HTMLElement {
-  const view = node.ownerDocument?.defaultView;
-  if (view && node instanceof view.HTMLElement) return true;
   return node.nodeType === 1;
 }
 

package/src/components/editor/manualEditsSeekReapply.ts

@@ -1,4 +1,5 @@
 // Puts Studio's committed edits back after a timeline seek has rendered over them.
+import { isHtmlElement } from "@hyperframes/core/runtime/dom-realm";
 import {
   STUDIO_BOX_SIZE_ATTR,
   STUDIO_HEIGHT_PROP,
@@ -15,15 +16,11 @@ import { STUDIO_MOTION_ATTR, STUDIO_MOTION_TIMELINE_ID } from "./studioMotionTyp
 import { gsapWritesChannels } from "../../hooks/gsapRuntimeKeyframes";
 
 function queryStudioElements(doc: Document, attr: string): HTMLElement[] {
-  const ctor = doc.defaultView?.HTMLElement;
-  if (!ctor) return [];
-  const elements = Array.from(doc.querySelectorAll(`[${attr}="true"]`)).filter(
-    (el): el is HTMLElement => el instanceof ctor,
-  );
+  const elements = Array.from(doc.querySelectorAll(`[${attr}="true"]`)).filter(isHtmlElement);
   // Handle legacy HTML files where attributes were persisted with a double data- prefix
   const legacyAttr = `data-${attr}`;
   for (const el of doc.querySelectorAll(`[${legacyAttr}="true"]`)) {
-    if (el instanceof ctor && !el.hasAttribute(attr)) {
+    if (isHtmlElement(el) && !el.hasAttribute(attr)) {
       el.setAttribute(attr, "true");
       el.removeAttribute(legacyAttr);
       elements.push(el);

package/src/components/editor/manualOffsetDrag.ts

@@ -1,3 +1,4 @@
+import { isHtmlElement } from "@hyperframes/core/runtime/dom-realm";
 import type { DomEditSelection } from "./domEditing";
 import {
   applyStudioPathOffset,
@@ -131,9 +132,7 @@ function getFrameElement(win: Window): HTMLElement | null {
   try {
     const frameElement = win.frameElement;
     if (!frameElement) return null;
-    const ownerWin = frameElement.ownerDocument.defaultView;
-    const htmlElement = ownerWin?.HTMLElement;
-    return htmlElement && frameElement instanceof htmlElement ? frameElement : null;
+    return isHtmlElement(frameElement) ? frameElement : null;
   } catch {
     return null;
   }

package/src/components/editor/motionPathCommit.nodeDrop.test.ts

@@ -0,0 +1,212 @@
+// @vitest-environment happy-dom
+import { afterEach, expect, it, onTestFinished, vi } from "vitest";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "./domEditing";
+import { boxSteps, previewWith, tween } from "../../hooks/gsapParsedTween.test-helpers";
+import { usePlayerStore } from "../../player/store/playerStore";
+import { GsapEditBlockedError } from "../../hooks/gsapEditOutcome";
+import { commitNodeDrop, nodeDropLabel, type CommitFn } from "./motionPathCommit";
+
+it("names a node drop for its undo entry by what it moved", () => {
+  const { autoKeyframeEnabled } = usePlayerStore.getState();
+  onTestFinished(() => usePlayerStore.setState({ autoKeyframeEnabled }));
+  usePlayerStore.setState({ autoKeyframeEnabled: true });
+  expect(nodeDropLabel({ type: "keyframe", pct: 50 })).toBe("Move keyframe");
+  usePlayerStore.setState({ autoKeyframeEnabled: false });
+  expect(nodeDropLabel({ type: "keyframe", pct: 50 })).toBe("Move animation path");
+  expect(nodeDropLabel({ type: "waypoint", index: 0 })).toBe("Move waypoint");
+});
+
+afterEach(() => {
+  usePlayerStore.setState({ currentTime: 0, activeKeyframePct: null, requestedSeekTime: null });
+  document.body.innerHTML = "";
+});
+
+function box(id = "box") {
+  const element = document.body.appendChild(document.createElement("div"));
+  element.id = id;
+  return { element, selection: { id, selector: `#${id}`, element } as DomEditSelection };
+}
+
+type Drop = Parameters<typeof commitNodeDrop>[0];
+
+function drop(fields: Omit<Drop, "animId" | "commitMutation"> & { anim: GsapAnimation }) {
+  const commitMutation = vi.fn<CommitFn>(async () => {});
+  const done = commitNodeDrop({ ...fields, animId: fields.anim.id, commitMutation });
+  const written = () =>
+    (commitMutation.mock.calls[0]![0] as { keyframes: { properties: object }[] }).keyframes.map(
+      (kf) => kf.properties,
+    );
+  return { done, commitMutation, written };
+}
+
+it("a keyframe node's drop changes that keyframe and keeps a newly animated channel on the others", async () => {
+  const { element, selection } = box();
+  // Over a CSS translate GSAP reads as y 30.
+  const { keys, live } = boxSteps([
+    [2, { x: 60 }],
+    [1, { x: 120 }],
+  ]);
+  usePlayerStore.setState({ currentTime: 2, autoKeyframeEnabled: true });
+
+  const { done, commitMutation, written } = drop({
+    ref: { type: "keyframe", pct: 100 },
+    at: { x: 150, y: 90 },
+    anim: keys,
+    selection,
+    iframe: previewWith(element, [live(element)], { x: 60, y: 30 }),
+  });
+  await done;
+
+  expect(commitMutation.mock.calls[0]![0].type).toBe("replace-with-keyframes");
+  expect(written()).toEqual([
+    { x: 60, y: 30 },
+    { x: 150, y: 90 },
+  ]);
+});
+
+it("a drop on an array step's node edits that step, though the path spaces nodes evenly", async () => {
+  const { element, selection } = box();
+  // Step ends at 2 s and 3 s; the path draws the first node at 0%, the parser and lane at 66.7%.
+  const { keys, live } = boxSteps([
+    [2, { x: 60, y: 30 }],
+    [1, { x: 120, y: 30 }],
+  ]);
+  usePlayerStore.setState({ currentTime: 1, autoKeyframeEnabled: true, activeKeyframePct: null });
+
+  const { done, written } = drop({
+    ref: { type: "keyframe", pct: 0, step: 0 },
+    at: { x: 40, y: 90 },
+    anim: keys,
+    selection,
+    iframe: previewWith(element, [live(element)], { x: 60, y: 30 }),
+  });
+  await done;
+
+  expect(written()).toEqual([
+    { x: 40, y: 90 },
+    { x: 120, y: 30 },
+  ]);
+  expect(usePlayerStore.getState().requestedSeekTime).toBe(2);
+});
+
+it("a drop the writer refuses rejects with the reason, writes nothing and selects nothing", async () => {
+  const [a, b] = [box("a"), box("b")];
+  for (const { element } of [a, b]) element.className = "card";
+  const shared = tween({
+    targetSelector: ".card",
+    method: "to",
+    properties: {},
+    resolvedStart: 0,
+    duration: 1,
+    keyframes: { format: "percentage", keyframes: [{ percentage: 100, properties: { x: 20 } }] },
+  });
+  usePlayerStore.setState({ autoKeyframeEnabled: true, activeKeyframePct: null });
+
+  const { done, commitMutation } = drop({
+    ref: { type: "keyframe", pct: 100 },
+    at: { x: 5, y: 0 },
+    anim: shared,
+    selection: a.selection,
+    iframe: previewWith(b.element, [], { x: 0, y: 0 }),
+  });
+
+  await expect(done).rejects.toBeInstanceOf(GsapEditBlockedError);
+  expect(commitMutation).not.toHaveBeenCalled();
+  expect(usePlayerStore.getState().activeKeyframePct).toBeNull();
+});
+
+it.each([true, false])(
+  "a drop on a step list with a step delay says the delay blocks it and writes nothing (auto-keyframe %s)",
+  async (autoKeyframeEnabled) => {
+    const { element, selection } = box();
+    const { keys } = boxSteps([
+      [1.5, { x: 100, delay: 0.5 }],
+      [1.5, { x: 200, delay: 0.5 }],
+    ]);
+    usePlayerStore.setState({ autoKeyframeEnabled, activeKeyframePct: null });
+
+    const { done, commitMutation } = drop({
+      ref: { type: "keyframe", pct: 100 },
+      at: { x: 150, y: 0 },
+      anim: keys,
+      selection,
+      iframe: previewWith(element, [], { x: 0, y: 0 }),
+    });
+
+    await expect(done).rejects.toThrow(/its own delay.*Code tab/);
+    expect(commitMutation).not.toHaveBeenCalled();
+  },
+);
+
+it("with auto-keyframe off, a step's node shifts the path by its own keyframe's move", async () => {
+  const { selection } = box();
+  // Steps of 4 s, 1 s and 1 s: drawn at 0/50/100%, parsed at their step ends.
+  const { keys } = boxSteps([
+    [4, { x: 60, y: 0 }],
+    [1, { x: 120, y: 0 }],
+    [1, { x: 180, y: 0 }],
+  ]);
+  usePlayerStore.setState({ autoKeyframeEnabled: false, activeKeyframePct: null });
+
+  const { done, written } = drop({
+    ref: { type: "keyframe", pct: 50, step: 1 },
+    at: { x: 157, y: 0 },
+    anim: keys,
+    selection,
+    iframe: null,
+  });
+  await done;
+
+  expect(written().map((props) => (props as { x: number }).x)).toEqual([97, 157, 217]);
+});
+
+it("a drop on an inner keyframe of a tween eased as a whole changes that keyframe", async () => {
+  const { element, selection } = box();
+  const keys = tween({
+    id: "#box-to-0-position",
+    method: "to",
+    properties: {},
+    resolvedStart: 0,
+    duration: 2,
+    ease: "power1.inOut",
+    keyframes: {
+      format: "percentage",
+      keyframes: [0, 100, 200].map((x, i) => ({ percentage: i * 50, properties: { x, y: 0 } })),
+    },
+  });
+  usePlayerStore.setState({ autoKeyframeEnabled: true, activeKeyframePct: null });
+
+  const { done, written } = drop({
+    ref: { type: "keyframe", pct: 50 },
+    at: { x: 150, y: 0 },
+    anim: keys,
+    selection,
+    iframe: previewWith(element, [], { x: 0, y: 0 }),
+  });
+  await done;
+
+  expect(written().map((props) => (props as { x: number }).x)).toEqual([0, 150, 200]);
+});
+
+it("a drop on a short step under 1% from the one before edits the dragged step", async () => {
+  const { element, selection } = box();
+  // Parsed at 50, 50.5 and 100%: a 0.05 s pop step in a 10 s list.
+  const { keys, live } = boxSteps([
+    [5, { x: 0, y: 0 }],
+    [0.05, { x: 100, y: 0 }],
+    [4.95, { x: 100, y: 0 }],
+  ]);
+  usePlayerStore.setState({ autoKeyframeEnabled: true, activeKeyframePct: null });
+
+  const { done, written } = drop({
+    ref: { type: "keyframe", pct: 50, step: 1 },
+    at: { x: 150, y: 0 },
+    anim: keys,
+    selection,
+    iframe: previewWith(element, [live(element)], { x: 0, y: 0 }),
+  });
+  await done;
+
+  expect(written().map((props) => (props as { x: number }).x)).toEqual([0, 150, 100]);
+});

package/src/components/editor/motionPathCommit.ts

@@ -5,7 +5,17 @@ import { trackPreviewFeatureUsed, type PreviewMethod } from "../../utils/preview
  * GSAP source mutation routed through the (selection-bound) commit facade, which
  * handles the soft reload, undo snapshot, and save-failure feedback.
  */
+import type { GsapAnimation } from "@hyperframes/parsers/gsap-parser";
+import { assertGsapEditPersisted } from "../../hooks/gsapEditOutcome";
+import { observeGsapGesture } from "../../hooks/gsapGestureOutcome";
+import { readGsapPositionFromIframe } from "../../hooks/gsapPositionDetection";
+import { commitValueAtPlayhead } from "../../hooks/gsapValueAtPlayhead";
+import { commitWholePropertyOffset } from "../../hooks/gsapWholePropertyOffsetCommit";
+import { usePlayerStore } from "../../player/store/playerStore";
+import { trackPreviewEditResult } from "../../utils/previewFeatureUsage";
+import type { DomEditSelection } from "./domEditing";
 import type { MotionNodeRef } from "./motionPathGeometry";
+import { selectorFor } from "./motionPathSelection";
 
 export type CommitFn = (
   mutation: Record<string, unknown>,
@@ -41,6 +51,54 @@ export function commitNode(
   );
 }
 
+type NodeDrop = {
+  ref: MotionNodeRef;
+  at: { x: number; y: number };
+  animId: string;
+  anim: GsapAnimation | undefined;
+  selection: DomEditSelection | null;
+  iframe: HTMLIFrameElement | null;
+  commitMutation: CommitFn;
+};
+
+/** What a node drop does, for its undo entry and its failure report. */
+export function nodeDropLabel(ref: MotionNodeRef): string {
+  if (ref.type !== "keyframe") return "Move waypoint";
+  return usePlayerStore.getState().autoKeyframeEnabled ? "Move keyframe" : "Move animation path";
+}
+
+/** A dropped keyframe goes through the layer drag's writer, GSAP's live values backfilling others
+ *  (auto-keyframe off, #1808: the whole path shifts); a waypoint moves in place. */
+export function commitNodeDrop(drop: NodeDrop): Promise<void> {
+  const { ref, at, anim, selection, iframe, commitMutation } = drop;
+  if (ref.type !== "keyframe" || !anim || !selection)
+    return commitNode(ref, at.x, at.y, drop.animId, commitMutation);
+  const writes = observeGsapGesture((_sel, mutation, options) => commitMutation(mutation, options));
+  const callbacks = { commitMutation: writes.commit! };
+  let done: Promise<unknown>;
+  const store = usePlayerStore.getState();
+  const step = ref.step == null ? undefined : anim.keyframes?.keyframes[ref.step];
+  const pct = step?.percentage ?? ref.pct;
+  if (store.autoKeyframeEnabled) {
+    const selected = store.activeKeyframePct;
+    store.setActiveKeyframePct(pct);
+    const live = readGsapPositionFromIframe(iframe, selectorFor(selection) ?? "");
+    done = commitValueAtPlayhead(selection, anim, at, iframe, callbacks, {
+      label: nodeDropLabel(ref),
+      backfill: live ?? undefined,
+    })
+      .then(assertGsapEditPersisted)
+      .catch((error: unknown) => {
+        usePlayerStore.getState().setActiveKeyframePct(selected);
+        throw error;
+      });
+  } else {
+    const label = nodeDropLabel(ref);
+    done = commitWholePropertyOffset(selection, anim, at, pct, iframe, callbacks, label);
+  }
+  return done.then(() => trackPreviewEditResult("motion_path", "drag", writes.finish()));
+}
+
 export function commitAddWaypoint(
   animationId: string,
   index: number,

package/src/components/editor/motionPathGeometry.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { buildMotionPathGeometry, nearestPointOnPath } from "./motionPathGeometry";
+import { buildMotionPathGeometry, nearestPointOnPath, nodeCentre } from "./motionPathGeometry";
 import type { ReadTween } from "../../hooks/gsapRuntimeKeyframes";
 
 const kf = (percentage: number, x: number, y: number) => ({ percentage, properties: { x, y } });
@@ -135,3 +135,63 @@ describe("nearestPointOnPath", () => {
     expect(nearestPointOnPath(0, 0, [{ x: 0, y: 0 }])).toBeNull();
   });
 });
+
+describe("nodeCentre", () => {
+  // The edit bench's `keys` layer at 1 s: left 560, 260 wide now, GSAP x 50; it reaches x 60 and
+  // width 280 at 2 s, x 120 and width 320 at 3 s, so its centre is then at 760 and 840.
+  const home = { x: 690, y: 380, w: 260, h: 160, ax: 0.5, ay: 0.5 };
+  const read: ReadTween = {
+    keyframes: [
+      { percentage: 66.667, properties: { x: 60, width: 280 } },
+      { percentage: 100, properties: { x: 120, width: 320 } },
+    ],
+  };
+
+  it("draws a keyframe that also sets the size where the layer's centre is at that keyframe", () => {
+    const geo = buildMotionPathGeometry(read, { x: 50, y: 30 })!;
+    expect(geo.nodes.map((n) => nodeCentre(n, home, 1))).toEqual([
+      { x: 760, y: 410 },
+      { x: 840, y: 410 },
+    ]);
+  });
+
+  it("keeps a layer centred by xPercent/yPercent -50 on its centre as a keyframe resizes it", () => {
+    const geo = buildMotionPathGeometry(read, { x: 50, y: 30 })!;
+    const centred = { ...home, ax: 0, ay: 0 };
+    expect(geo.nodes.map((n) => nodeCentre(n, centred, 1).x)).toEqual([750, 810]);
+  });
+
+  it("keeps a keyframe that sets no size at home plus its offset", () => {
+    const geo = buildMotionPathGeometry({ keyframes: [kf(0, 10, 20), kf(100, 200, 80)] })!;
+    expect(nodeCentre(geo.nodes[1]!, home, 1)).toEqual({ x: 890, y: 460 });
+  });
+});
+
+describe("start", () => {
+  it("keeps where GSAP started a tween whose first keyframe comes later, with the size it had", () => {
+    const read: ReadTween = {
+      keyframes: [kf(66.667, 60, 30), kf(100, 120, 30)],
+      start: { x: 40, y: 30, width: 260 },
+    };
+    expect(buildMotionPathGeometry(read)?.start).toEqual({ x: 40, y: 30, w: 260 });
+  });
+
+  it("draws no start when GSAP has not read one", () => {
+    expect(buildMotionPathGeometry({ keyframes: [kf(50, 60, 30), kf(100, 120, 30)] })?.start).toBe(
+      undefined,
+    );
+  });
+});
+
+it("an array step's node carries its step, so a drop finds that keyframe whatever its time", () => {
+  const read = {
+    keyframes: [
+      { percentage: 0, properties: { x: 60 }, step: 0 },
+      { percentage: 100, properties: { x: 120 }, step: 1 },
+    ],
+  };
+  expect(buildMotionPathGeometry(read)!.nodes.map((n) => n.ref)).toEqual([
+    { type: "keyframe", pct: 0, step: 0 },
+    { type: "keyframe", pct: 100, step: 1 },
+  ]);
+});