@hyperframes/studio 0.8.120 → 0.8.122

package/dist/player.js

@@ -1,6 +1,6 @@
 import {
   Player
-} from "./chunk-J6Q572FA.js";
+} from "./chunk-246VB2G3.js";
 import "./chunk-5VSXRGIX.js";
 import "./chunk-5EKWJZLM.js";
 import "./chunk-PZ5AY32C.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.120",
+  "version": "0.8.122",
   "description": "",
   "repository": {
     "type": "git",
@@ -60,12 +60,12 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.120",
-    "@hyperframes/parsers": "0.8.120",
-    "@hyperframes/sdk": "0.8.120",
-    "@hyperframes/shader-transitions": "0.8.120",
-    "@hyperframes/studio-server": "0.8.120",
-    "@hyperframes/player": "0.8.120"
+    "@hyperframes/parsers": "0.8.122",
+    "@hyperframes/sdk": "0.8.122",
+    "@hyperframes/core": "0.8.122",
+    "@hyperframes/shader-transitions": "0.8.122",
+    "@hyperframes/studio-server": "0.8.122",
+    "@hyperframes/player": "0.8.122"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -81,7 +81,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.120"
+    "@hyperframes/producer": "0.8.122"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/TimelineToolbar.test.tsx

@@ -436,3 +436,28 @@ describe("TimelineToolbar — host right actions", () => {
     act(() => root.unmount());
   });
 });
+
+describe("TimelineToolbar split hint", () => {
+  async function splitTooltip(props: Partial<React.ComponentProps<typeof TimelineToolbar>>) {
+    usePlayerStore.setState({
+      elements: [{ id: "a", domId: "a", tag: "div", start: 0, duration: 4, track: 0 }],
+      selectedElementId: "a",
+      currentTime: 2,
+    });
+    const { host, root } = renderToolbar(undefined, { onSplitElement: vi.fn(), ...props });
+    const button = host.querySelector<HTMLButtonElement>('button[aria-label="Split at playhead"]');
+    act(() => button?.focus());
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+    const label = document.querySelector('[role="tooltip"]')?.textContent;
+    act(() => root.unmount());
+    usePlayerStore.setState({ elements: [], selectedElementId: null, currentTime: 0 });
+    return label;
+  }
+
+  it("names S unless the host binds Split to another key", async () => {
+    expect(await splitTooltip({})).toBe("Split at playhead (S)");
+    expect(await splitTooltip({ splitShortcut: "⌘B" })).toBe("Split at playhead (⌘B)");
+  });
+});

package/src/components/TimelineToolbar.tsx

@@ -35,6 +35,8 @@ import { LinkedSelectionToggle } from "./LinkedSelectionToggle";
 import { useProjectHasAudio } from "../utils/audioMeterMath";
 import { canAddBeatAt, addBeatAtCompositionTime } from "../utils/beatEditActions";
 import { isTypingTarget } from "../utils/typingTarget";
+import { SPLIT_SHORTCUT_HINT } from "../player/components/studioShortcuts";
+import type { TimelineProps } from "../player/components/TimelineTypes";
 
 interface DomEditSessionSlice extends EnableKeyframesSession {
   domEditSelection: DomEditSelection | null;
@@ -44,6 +46,7 @@ interface DomEditSessionSlice extends EnableKeyframesSession {
 export interface TimelineToolbarProps {
   domEditSession?: DomEditSessionSlice;
   onSplitElement?: (element: TimelineElement, splitTime: number) => void;
+  splitShortcut?: TimelineProps["splitShortcut"];
   history?: TimelineHistoryButtonsProps;
   showHistory?: boolean;
   showSelectAroundPlayhead?: boolean;
@@ -145,6 +148,7 @@ function useKeyframeToggle(session?: DomEditSessionSlice) {
 export const TimelineToolbar = memo(function TimelineToolbar({
   domEditSession,
   onSplitElement,
+  splitShortcut = SPLIT_SHORTCUT_HINT,
   history,
   showHistory = true,
   showSelectAroundPlayhead = true,
@@ -382,7 +386,7 @@ export const TimelineToolbar = memo(function TimelineToolbar({
                 <Tooltip
                   label={
                     canSplit
-                      ? "Split at playhead (S)"
+                      ? `Split at playhead (${splitShortcut})`
                       : splittable
                         ? "Move the playhead inside the clip to split"
                         : "Select a clip to split"

package/src/components/editor/MotionPathNode.tsx

@@ -1,4 +1,5 @@
 import type React from "react";
+import { dotRadius } from "./motionPathLayerNode";
 
 // Editor primary color (themeable via --hf-accent). Applied through inline
 // style because CSS var() isn't valid in SVG presentation attributes.
@@ -29,7 +30,7 @@ export function MotionPathNode(props: {
   // Diamond matching the timeline keyframe (a 45°-rotated rounded square).
   // `side` is chosen so the diamond's points reach ~`r` from center, matching the
   // old dot's footprint; selection is shown by enlarging it (no extra shape).
-  const side = (selected ? r * 1.5 : r) * 1.414;
+  const side = dotRadius(r, selected) * 1.414;
   return (
     <g onPointerEnter={props.onEnter} onPointerLeave={props.onLeave}>
       <rect

package/src/components/editor/MotionPathOverlay.layerPress.test.tsx

@@ -0,0 +1,99 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { expect, it, vi } from "vitest";
+import { usePlayerStore } from "../../player/store/playerStore";
+import { MotionPathOverlay } from "./MotionPathOverlay";
+import type { DomEditSelection } from "./domEditing";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+vi.mock("../../contexts/DomEditContext", () => ({
+  useDomEditContext: () => ({ selectedGsapAnimations: [], commitMutation: vi.fn() }),
+}));
+vi.mock("./motionPathSelection", () => ({
+  selectorFor: () => "#box",
+  editableAnimationId: () => "a1",
+}));
+// GSAP renders the layer at the first keyframe: the playhead is on it.
+vi.mock("../../hooks/gsapPositionDetection", () => ({
+  readGsapPositionFromIframe: () => ({ x: 60, y: 30 }),
+}));
+vi.mock("./useMotionPathData", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./useMotionPathData")>()),
+  useMotionPathData: () => ({
+    rect: { left: 0, top: 0, width: 1920, height: 1080 },
+    geometry: {
+      kind: "linear",
+      points: "60,30 120,30",
+      nodes: [
+        { x: 60, y: 30, ref: { type: "keyframe", pct: 66.667 } },
+        { x: 120, y: 30, ref: { type: "keyframe", pct: 100 } },
+      ],
+    },
+    geometryResolved: true,
+    visibleInPreview: true,
+    home: { x: 0, y: 0 },
+    pScale: 1,
+  }),
+}));
+
+it("the layer's node and another node's ring inside the layer's box press the layer; a dot keeps its node", () => {
+  const box = document.createElement("div");
+  box.setAttribute("data-dom-edit-selection-box", "true");
+  const host = document.createElement("div");
+  document.body.append(box, host);
+  const boxPresses: number[] = [];
+  let boxStarts = true;
+  box.addEventListener("pointerdown", (e) => {
+    boxPresses.push((e as PointerEvent).clientX);
+    if (boxStarts) e.preventDefault();
+  });
+  const captured = vi.spyOn(Element.prototype, "setPointerCapture").mockImplementation(() => {});
+  const root = createRoot(host);
+  const selection = { element: document.createElement("div") } as unknown as DomEditSelection;
+  // Scale 1: client px are composition px. `inBox`: the layer's box is under the press.
+  const press = (node: number, x: number, inBox: boolean) => {
+    const hit = [...host.querySelectorAll("circle.pointer-events-auto")].find(
+      (c) => c.getAttribute("cx") === String(node),
+    )!;
+    document.elementsFromPoint = () => (inBox ? [hit, box] : [hit]);
+    const down = { bubbles: true, cancelable: true, button: 0, clientX: x, clientY: 30 };
+    act(() => void hit.dispatchEvent(new PointerEvent("pointerdown", down)));
+  };
+  try {
+    act(() =>
+      root.render(
+        <MotionPathOverlay
+          iframeRef={{ current: null }}
+          selection={selection}
+          compositionSize={{ width: 1920, height: 1080 }}
+          isPlaying={false}
+        />,
+      ),
+    );
+    press(60, 63, false);
+    press(120, 110, true);
+    expect(boxPresses).toEqual([63, 110]);
+    press(120, 118, true);
+    press(120, 110, false);
+    expect(boxPresses).toEqual([63, 110]);
+    // A selected node draws its dot 1.5x as large, and the larger dot is the node's.
+    act(() => usePlayerStore.setState({ activeKeyframePct: 100 }));
+    press(120, 112, true);
+    expect(boxPresses).toEqual([63, 110]);
+    act(() => usePlayerStore.setState({ activeKeyframePct: null }));
+    press(120, 112, true);
+    expect(boxPresses).toEqual([63, 110, 112]);
+    // A box that starts no gesture leaves the press to the node.
+    boxStarts = false;
+    captured.mockClear();
+    press(60, 63, false);
+    expect(captured).toHaveBeenCalledTimes(1);
+  } finally {
+    captured.mockRestore();
+    act(() => root.unmount());
+    box.remove();
+    host.remove();
+  }
+});

package/src/components/editor/MotionPathOverlay.tsx

@@ -10,6 +10,8 @@ import { parkPlayheadOnKeyframe } from "../../hooks/gsapDragCommit";
 import { commitWholePropertyOffset } from "../../hooks/gsapWholePropertyOffsetCommit";
 import { nearestPointOnPath, type MotionNodeRef } from "./motionPathGeometry";
 import { editableAnimationId, selectorFor } from "./motionPathSelection";
+import { dotRadius, pressBelongsToLayer, pressSelectedLayer } from "./motionPathLayerNode";
+import { readGsapPositionFromIframe } from "../../hooks/gsapPositionDetection";
 import { ACCENT, MotionPathNode } from "./MotionPathNode";
 import {
   KeyframeDiamondContextMenu,
@@ -310,6 +312,10 @@ export const MotionPathOverlay = memo(function MotionPathOverlay({
     if (!interactive) return;
     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;
     (e.target as Element).setPointerCapture(e.pointerId);
     dragRef.current = {
       index,

package/src/components/editor/domEditOverlayStartGesture.blocked.test.ts

@@ -0,0 +1,57 @@
+// @vitest-environment happy-dom
+import { expect, it, vi } from "vitest";
+import type { DomEditSelection } from "./domEditing";
+import { readTranslatePx } from "./plainTranslate";
+import { createDomEditOverlayGestureHandlers } from "./useDomEditOverlayGestures";
+
+vi.mock("./plainTranslate", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./plainTranslate")>()),
+  readTranslatePx: vi.fn(() => ({ x: Number.NaN, y: 0 })),
+}));
+
+it("a drag press the layer cannot take gets the notice, counts as handled, and leaves the box live", () => {
+  const element = document.body.appendChild(document.createElement("div"));
+  const ref = <T>(current: T) => ({ current });
+  const onBlockedMove = vi.fn();
+  const opts = {
+    selectionRef: ref({
+      element,
+      capabilities: { canApplyManualOffset: true },
+    } as unknown as DomEditSelection),
+    overlayRectRef: ref({ left: 0, top: 0, width: 240, height: 160, editScaleX: 1, editScaleY: 1 }),
+    boxRef: ref(document.createElement("div")),
+    overlayRef: ref(null),
+    iframeRef: ref(null),
+    gestureRef: ref(null),
+    rafPausedRef: ref(false),
+    onManualDragStartRef: ref(vi.fn()),
+    onBlockedMoveRef: ref(onBlockedMove),
+    onPathOffsetCommitRef: ref(vi.fn()),
+    snapGuidesRef: ref(null),
+    groupGestureRef: ref(null),
+    blockedMoveRef: ref(null),
+    setOverlayRect: vi.fn(),
+    suppressNextBoxClickRef: ref(false),
+    hoverSelectionRef: ref(null),
+    onCanvasMouseDown: vi.fn(),
+  };
+  const press = new PointerEvent("pointerdown", { cancelable: true });
+  const e = {
+    clientX: 10,
+    clientY: 10,
+    pointerId: 1,
+    button: 0,
+    preventDefault: () => press.preventDefault(),
+    stopPropagation() {},
+    currentTarget: { setPointerCapture() {} },
+  };
+  const handlers = createDomEditOverlayGestureHandlers(opts as never);
+  expect(handlers.startGesture("drag", e as never)).toBe(false);
+  expect(onBlockedMove).toHaveBeenCalledTimes(1);
+  expect(press.defaultPrevented).toBe(true);
+  // The release lands outside the box, so nothing would ever resume it.
+  expect(opts.rafPausedRef.current).toBe(false);
+  // Playback pauses before setup reads which timelines are running.
+  const [paused] = opts.onManualDragStartRef.current.mock.invocationCallOrder;
+  expect(paused).toBeLessThan(vi.mocked(readTranslatePx).mock.invocationCallOrder[0]!);
+});

package/src/components/editor/domEditOverlayStartGesture.ts

@@ -185,7 +185,6 @@ export function startGesture(
 
   if (kind === "drag") {
     opts.onManualDragStartRef.current?.();
-    opts.rafPausedRef.current = true;
     const result = createManualOffsetDragMember({
       key: selectionCacheKey(sel),
       selection: sel,
@@ -195,6 +194,7 @@ export function startGesture(
     });
     if (!result.ok) {
       opts.onBlockedMoveRef.current(result.selection, result.reason);
+      e.preventDefault();
       return false;
     }
     pathOffsetMember = result.member;

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

@@ -17,6 +17,16 @@ describe("buildMotionPathGeometry", () => {
     ]);
   });
 
+  it("puts an axis the tween does not animate where GSAP renders it, a folded CSS translate", () => {
+    const read: ReadTween = {
+      keyframes: [
+        { percentage: 66.667, properties: { x: 60 } },
+        { percentage: 100, properties: { x: 120 } },
+      ],
+    };
+    expect(buildMotionPathGeometry(read, { x: 40, y: 30 })!.points).toBe("60,30 120,30");
+  });
+
   it("preserves order and percentages for intermediate keyframes", () => {
     const read: ReadTween = { keyframes: [kf(0, 0, 0), kf(50, 50, 90), kf(100, 100, 0)] };
     const geo = buildMotionPathGeometry(read);

package/src/components/editor/motionPathGeometry.ts

@@ -78,7 +78,10 @@ export function nearestPointOnPath(
   return best;
 }
 
-export function buildMotionPathGeometry(read: ReadTween | null): MotionPathGeometry | null {
+export function buildMotionPathGeometry(
+  read: ReadTween | null,
+  base: { x: number; y: number } = { x: 0, y: 0 },
+): MotionPathGeometry | null {
   if (!read) return null;
   const isArc = Boolean(read.arcPath);
   const nodes: MotionPathNode[] = [];
@@ -87,8 +90,8 @@ export function buildMotionPathGeometry(read: ReadTween | null): MotionPathGeome
   // anchor. Arc waypoints always carry x/y (never filtered), so source index
   // and node order stay aligned.
   // Which axes does the tween animate at all? A single-axis tween (e.g.
-  // `to({ x: -260 })`) only carries x; its y stays at the base (0, the GSAP
-  // transform identity), so we default it and still draw a path. But if the tween
+  // `to({ x: -260 })`) only carries x; its y stays at `base`, GSAP's live y (a CSS
+  // translate it folded in, else 0), so we default it and still draw a path. But if the tween
   // DOES animate an axis and a given keyframe omits it, that value is interpolated
   // (not 0) and can't be placed here → skip that node (the prior behavior).
   const finite = (v: unknown): v is number => typeof v === "number" && isFinite(v);
@@ -100,8 +103,8 @@ export function buildMotionPathGeometry(read: ReadTween | null): MotionPathGeome
     if (tweenHasX && !finite(kf.properties.x)) return;
     if (tweenHasY && !finite(kf.properties.y)) return;
     nodes.push({
-      x: tweenHasX ? (kf.properties.x as number) : 0,
-      y: tweenHasY ? (kf.properties.y as number) : 0,
+      x: tweenHasX ? (kf.properties.x as number) : base.x,
+      y: tweenHasY ? (kf.properties.y as number) : base.y,
       ref: isArc ? { type: "waypoint", index: i } : { type: "keyframe", pct: kf.percentage },
     });
   });

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

@@ -0,0 +1,82 @@
+// @vitest-environment happy-dom
+import { expect, it } from "vitest";
+import { pressBelongsToLayer, pressSelectedLayer } from "./motionPathLayerNode";
+
+// Keyframe nodes at x 60 and 120 (y 30), drawn from home (500, 400); dots of radius 6.
+const atLayer = { x: 60, y: 30, ax: 560, ay: 430 };
+const other = { x: 120, y: 30, ax: 620, ay: 430 };
+const live = { x: 60, y: 30 };
+
+const box = document.createElement("div");
+box.setAttribute("data-dom-edit-selection-box", "true");
+const circle = document.createElementNS("http://www.w3.org/2000/svg", "circle");
+document.body.append(box, circle);
+
+/** A press on `circle` at (x, y), with `under` what the document hit-tests there. */
+function press(x: number, y: number, under: Element[]) {
+  document.elementsFromPoint = () => [circle, ...under];
+  return { currentTarget: circle, clientX: x, clientY: y } as unknown as React.PointerEvent;
+}
+
+it("the node GSAP renders the layer at is the layer, inside the box or out", () => {
+  expect(pressBelongsToLayer(press(562, 431, [box]), { x: 562, y: 431 }, atLayer, 6, live)).toBe(
+    true,
+  );
+  expect(pressBelongsToLayer(press(570, 440, []), { x: 570, y: 440 }, atLayer, 6, live)).toBe(true);
+});
+
+it("inside the layer's box another node's grab ring is the layer's; its dot stays the node's", () => {
+  expect(pressBelongsToLayer(press(610, 430, [box]), { x: 610, y: 430 }, other, 6, live)).toBe(
+    true,
+  );
+  expect(pressBelongsToLayer(press(617, 430, [box]), { x: 617, y: 430 }, other, 6, live)).toBe(
+    false,
+  );
+});
+
+it("outside the layer's box a node's whole grab ring is the node's", () => {
+  expect(pressBelongsToLayer(press(610, 430, []), { x: 610, y: 430 }, other, 6, live)).toBe(false);
+  expect(pressBelongsToLayer(press(610, 430, [box]), { x: 610, y: 430 }, other, 6, null)).toBe(
+    true,
+  );
+});
+
+it("hands a press to the selected layer's box with its pointer and position", () => {
+  const got: number[][] = [];
+  const listen = (e: Event) => {
+    const p = e as PointerEvent;
+    got.push([p.pointerId, p.clientX, p.clientY, p.button]);
+    e.preventDefault();
+  };
+  box.addEventListener("pointerdown", listen);
+  const nativeEvent = new PointerEvent("pointerdown", {
+    pointerId: 7,
+    clientX: 12,
+    clientY: 34,
+    button: 0,
+    bubbles: true,
+    cancelable: true,
+  });
+  const down = { currentTarget: circle, nativeEvent } as unknown as React.PointerEvent;
+  expect(pressSelectedLayer(down)).toBe(true);
+  expect(got).toEqual([[7, 12, 34, 0]]);
+  box.removeEventListener("pointerdown", listen);
+  box.remove();
+  expect(pressSelectedLayer(down)).toBe(false);
+  document.body.append(box);
+});
+
+it("keeps the press when the box does not start a gesture with it, or takes no pointer", () => {
+  let got = 0;
+  const listen = () => void got++;
+  box.addEventListener("pointerdown", listen);
+  const nativeEvent = new PointerEvent("pointerdown", { bubbles: true, cancelable: true });
+  const down = { currentTarget: circle, nativeEvent } as unknown as React.PointerEvent;
+  expect(pressSelectedLayer(down)).toBe(false);
+  expect(got).toBe(1);
+  box.style.pointerEvents = "none";
+  expect(pressSelectedLayer(down)).toBe(false);
+  expect(got).toBe(1);
+  box.style.pointerEvents = "";
+  box.removeEventListener("pointerdown", listen);
+});

package/src/components/editor/motionPathLayerNode.ts

@@ -0,0 +1,28 @@
+type Point = { x: number; y: number };
+type DrawnNode = Point & { ax: number; ay: number };
+
+const LAYER_BOX = '[data-dom-edit-selection-box="true"]';
+
+/** How far a node's dot reaches; a selected node draws it larger. */
+export const dotRadius = (r: number, selected: boolean) => (selected ? r * 1.5 : r);
+
+/** A press on the layer's own node, or in its box but off a node's dot, belongs to the layer. */
+export function pressBelongsToLayer(
+  e: React.PointerEvent,
+  point: Point,
+  pressed: DrawnNode,
+  dotR: number,
+  live: Point | null,
+): boolean {
+  if (live && Math.abs(pressed.x - live.x) < 0.5 && Math.abs(pressed.y - live.y) < 0.5) return true;
+  const hits = e.currentTarget.ownerDocument.elementsFromPoint(e.clientX, e.clientY);
+  const inBox = hits.some((el) => el.closest(LAYER_BOX));
+  return inBox && Math.hypot(point.x - pressed.ax, point.y - pressed.ay) > dotR;
+}
+
+/** Hands a press to the selected layer's box; true when the box started a gesture with it. */
+export function pressSelectedLayer(e: React.PointerEvent): boolean {
+  const box = e.currentTarget.ownerDocument.querySelector(LAYER_BOX);
+  if (!box || getComputedStyle(box).pointerEvents === "none") return false;
+  return !box.dispatchEvent(new PointerEvent("pointerdown", e.nativeEvent));
+}

package/src/components/editor/useDomEditNudge.test.tsx

@@ -34,9 +34,11 @@ let flushNudge = () => {};
 function Harness({
   selection,
   onPathOffsetCommit,
+  onManualDragStart = () => {},
 }: {
   selection: DomEditSelection | null;
   onPathOffsetCommit: UseDomEditNudgeParams["onPathOffsetCommitRef"]["current"];
+  onManualDragStart?: () => void;
 }) {
   flushNudge = useDomEditNudge({
     selection,
@@ -48,7 +50,7 @@ function Harness({
     gestureRef: makeRef(null),
     groupGestureRef: makeRef(null),
     blockedMoveRef: makeRef(null),
-    onManualDragStartRef: makeRef(() => {}),
+    onManualDragStartRef: makeRef(onManualDragStart),
     onBlockedMoveRef: makeRef(() => {}),
     onPathOffsetCommitRef: makeRef(onPathOffsetCommit),
     onGroupPathOffsetCommitRef: makeRef(async () => {}),
@@ -340,6 +342,56 @@ describe("useDomEditNudge carries the route its press chose", () => {
   });
 });
 
+describe("useDomEditNudge pauses playback before it snapshots the timelines", () => {
+  let reactRoot: ReturnType<typeof createRoot> | null = null;
+  const pause = vi.fn();
+  const mount = (selection: DomEditSelection | null) => {
+    reactRoot = createRoot(document.createElement("div"));
+    act(() => {
+      reactRoot!.render(
+        React.createElement(Harness, {
+          selection,
+          onPathOffsetCommit: vi.fn(),
+          onManualDragStart: pause,
+        }),
+      );
+    });
+  };
+  beforeEach(() => {
+    vi.useFakeTimers();
+    __resetForTests();
+    pause.mockReset();
+  });
+  afterEach(() => {
+    act(() => reactRoot?.unmount());
+    reactRoot = null;
+    document.body.innerHTML = "";
+    vi.useRealTimers();
+    delete (window as { __timelines?: unknown }).__timelines;
+  });
+
+  it("does not resume a timeline the playback pause stopped", () => {
+    let playing = true;
+    const root = { pause: () => void (playing = false), paused: () => !playing };
+    (window as { __timelines?: unknown }).__timelines = { root };
+    pause.mockImplementation(root.pause);
+    const element = document.body.appendChild(document.createElement("div"));
+    mount(makeSelection("Dot", element));
+
+    act(() => dispatchArrowRight());
+
+    expect(element.hasAttribute("data-hf-drag-paused-timelines")).toBe(false);
+  });
+
+  it("leaves playback alone when no layer can move", () => {
+    mount(null);
+
+    act(() => dispatchArrowRight());
+
+    expect(pause).not.toHaveBeenCalled();
+  });
+});
+
 describe("useDomEditNudge — undo right after a burst", () => {
   it("undo's drain commits a burst still inside its debounce and waits for its save", async () => {
     __resetForTests();

package/src/components/editor/useDomEditNudge.ts

@@ -212,6 +212,8 @@ export function useDomEditNudge(params: UseDomEditNudgeParams): { flushNudge: ()
       ? resolveGroupNudgeTargets(groupItems)
       : resolveSingleNudgeTarget(p.selectionRef.current, p.overlayRectRef.current);
     if (!targets) return null;
+    // Same side effect a drag start has (pauses preview playback).
+    p.onManualDragStartRef.current?.();
     const members: ManualOffsetDragMember[] = [];
     for (const target of targets) {
       const result = createManualOffsetDragMember({ ...target, gesture: "nudge" });
@@ -223,8 +225,6 @@ export function useDomEditNudge(params: UseDomEditNudgeParams): { flushNudge: ()
       members.push(result.member);
     }
     if (members.length === 0) return null;
-    // Same side effect a drag start has (pauses preview playback).
-    p.onManualDragStartRef.current?.();
     const edit = beginStudioPendingEdit(manualOffsetMoveRevert(members));
     return { members, isGroup, accum: { x: 0, y: 0 }, timer: null, edit };
   };

package/src/components/editor/useMotionPathData.test.tsx

@@ -8,6 +8,12 @@ import { usePlayerStore } from "../../player/store/playerStore";
 
 Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
 
+const runtime = vi.hoisted(() => ({ read: null as unknown, gsapPosition: null as unknown }));
+vi.mock("../../hooks/gsapRuntimeKeyframes", () => ({ readRuntimeKeyframes: () => runtime.read }));
+vi.mock("../../hooks/gsapPositionDetection", () => ({
+  readGsapPositionFromIframe: () => runtime.gsapPosition,
+}));
+
 const originalRaf = window.requestAnimationFrame;
 let frames: Array<() => void> = [];
 const runFrames = (count: number) => {
@@ -36,6 +42,30 @@ afterEach(() => {
   vi.useRealTimers();
   usePlayerStore.setState({ previewBooted: false, motionPathArmed: false });
   document.body.innerHTML = "";
+  runtime.read = runtime.gsapPosition = null;
+});
+
+it("draws an axis the tween leaves alone where GSAP renders it, so the playhead node sits on the layer", () => {
+  runtime.read = {
+    keyframes: [
+      { percentage: 66.667, properties: { x: 60 } },
+      { percentage: 100, properties: { x: 120 } },
+    ],
+  };
+  runtime.gsapPosition = { x: 60, y: 30 };
+  let points: string | undefined;
+  function Probe() {
+    const ref = useRef(document.createElement("iframe"));
+    points = useMotionPathData(ref, "#box").geometry?.points;
+    return null;
+  }
+  const root = createRoot(document.body.appendChild(document.createElement("div")));
+  try {
+    act(() => root.render(<Probe />));
+    expect(points).toBe("60,30 120,30");
+  } finally {
+    act(() => root.unmount());
+  }
 });
 
 it("reads no layout per frame until there is a path or a create ring to draw", () => {

package/src/components/editor/useMotionPathData.ts

@@ -1,5 +1,6 @@
 import { useEffect, useRef, useState, type RefObject } from "react";
 import { readRuntimeKeyframes } from "../../hooks/gsapRuntimeKeyframes";
+import { readGsapPositionFromIframe } from "../../hooks/gsapPositionDetection";
 import { isElementVisibleForOverlay } from "./domEditOverlayGeometry";
 import { buildMotionPathGeometry, type MotionPathGeometry } from "./motionPathGeometry";
 import { subscribeOverlayFrame } from "./overlayFrameLoop";
@@ -169,7 +170,8 @@ export function useMotionPathData(
     const recompute = () => {
       // Position-only: never let a co-located size/scale tween shadow the path.
       const read = readRuntimeKeyframes(iframeRef.current, selector, undefined, ["x", "y"]);
-      const next = buildMotionPathGeometry(read);
+      const base = read ? readGsapPositionFromIframe(iframeRef.current, selector) : null;
+      const next = buildMotionPathGeometry(read, base ?? undefined);
       setGeometry((prev) =>
         prev?.points === next?.points && prev?.kind === next?.kind ? prev : next,
       );