@hyperframes/studio 0.8.125 → 0.8.126

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.125",
+  "version": "0.8.126",
   "description": "",
   "repository": {
     "type": "git",
@@ -60,12 +60,12 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/parsers": "0.8.125",
-    "@hyperframes/player": "0.8.125",
-    "@hyperframes/core": "0.8.125",
-    "@hyperframes/sdk": "0.8.125",
-    "@hyperframes/shader-transitions": "0.8.125",
-    "@hyperframes/studio-server": "0.8.125"
+    "@hyperframes/core": "0.8.126",
+    "@hyperframes/sdk": "0.8.126",
+    "@hyperframes/shader-transitions": "0.8.126",
+    "@hyperframes/player": "0.8.126",
+    "@hyperframes/parsers": "0.8.126",
+    "@hyperframes/studio-server": "0.8.126"
   },
   "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.125"
+    "@hyperframes/producer": "0.8.126"
   },
   "peerDependencies": {
     "react": "19",
@@ -101,6 +101,7 @@
     "test:timeline-virtualization": "TIMELINE_ROW_VIRTUALIZATION=on TIMELINE_ELEMENT_COUNT=50000 node tests/e2e/timeline-virtualization.mjs",
     "test:watch": "vitest",
     "test:colors:browser": "node tests/e2e/native-css-colors.mjs",
+    "test:motion-path-home:browser": "node tests/e2e/motion-path-home.mjs",
     "report:sdk-cutover": "bun src/utils/sdkCutoverPolicy.report.ts",
     "test:timeline-default": "bun run test:timeline-virtualization"
   }

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

@@ -5,6 +5,7 @@ import { createRoot } from "react-dom/client";
 import { describe, expect, it, vi } from "vitest";
 import type { DomEditSelection } from "./domEditing";
 import { DomEditGroupChrome, DomEditSelectionChrome } from "./DomEditSelectionChrome";
+import { SELECTION_CHROME } from "./motionPathLayerNode";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -127,6 +128,10 @@ describe("DomEditSelectionChrome crop composition", () => {
     }
     expect(rotations).toHaveLength(1);
     expect(Number.parseFloat(rotations[0]!.slice("rotate(".length))).toBeCloseTo(30, 5);
+    // A motion-path node over any of these hands its press to it.
+    const controls = [...host.querySelectorAll(".pointer-events-auto, button")];
+    expect(controls.length).toBeGreaterThan(8);
+    for (const control of controls) expect(control.closest(SELECTION_CHROME)).not.toBeNull();
     act(() => root.unmount());
   });
 });

package/src/components/editor/DomEditSelectionChrome.tsx

@@ -169,6 +169,7 @@ export function DomEditSelectionChrome({
   return (
     <>
       <div
+        data-dom-edit-chrome="true"
         className="pointer-events-none absolute inset-0"
         style={{
           transformOrigin: `${overlayRect.left + overlayRect.width / 2}px ${overlayRect.top + overlayRect.height / 2}px`,

package/src/components/editor/MotionPathNode.tsx

@@ -98,3 +98,59 @@ export function MotionPathNode(props: {
     </g>
   );
 }
+
+type Point = { x: number; y: number };
+
+/** The drawn path from GSAP's start (a passive mark) through the nodes, and the add-on-line ghost. */
+export function MotionPathLine(props: {
+  points: string;
+  start?: Point;
+  ghost: Point | null;
+  r: number;
+}) {
+  const { points, start, ghost, r: nodeR } = props;
+  return (
+    <>
+      <polyline
+        points={start ? `${start.x},${start.y} ${points}` : points}
+        fill="none"
+        style={{ stroke: ACCENT }}
+        strokeWidth={1.5}
+        strokeDasharray="5 5"
+        strokeLinejoin="round"
+        strokeLinecap="round"
+        vectorEffect="non-scaling-stroke"
+        opacity={0.85}
+      />
+      {start && (
+        <circle
+          data-motion-path-start
+          cx={start.x}
+          cy={start.y}
+          r={nodeR * 0.6}
+          fill="none"
+          strokeWidth={1.5}
+          vectorEffect="non-scaling-stroke"
+          className="pointer-events-none"
+          style={{ stroke: ACCENT }}
+        />
+      )}
+      {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 }}
+        />
+      )}
+    </>
+  );
+}

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

@@ -1,15 +1,18 @@
 // @vitest-environment happy-dom
 import { act } from "react";
 import { createRoot } from "react-dom/client";
-import { expect, it, vi } from "vitest";
+import { afterEach, 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);
 
+const { commitMutation } = vi.hoisted(() => ({
+  commitMutation: vi.fn(async (..._args: unknown[]) => {}),
+}));
 vi.mock("../../contexts/DomEditContext", () => ({
-  useDomEditContext: () => ({ selectedGsapAnimations: [], commitMutation: vi.fn() }),
+  useDomEditContext: () => ({ selectedGsapAnimations: [], commitMutation }),
 }));
 vi.mock("./motionPathSelection", () => ({
   selectorFor: () => "#box",
@@ -28,72 +31,161 @@ vi.mock("./useMotionPathData", async (importOriginal) => ({
       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 } },
+        // 140 wide there against 100 now: drawn 20 px right, where the layer's centre will be.
+        { x: 120, y: 30, w: 140, ref: { type: "keyframe", pct: 100 } },
       ],
+      start: { x: 40, y: 30, w: 120 },
     },
     geometryResolved: true,
     visibleInPreview: true,
-    home: { x: 0, y: 0 },
+    home: { x: 0, y: 0, w: 100, h: 50, ax: 0.5, ay: 0.5 },
     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 cleanups: Array<() => void> = [];
+afterEach(() => {
+  while (cleanups.length) cleanups.pop()!();
+  commitMutation.mockClear();
+});
+
+/** What lies under the pointer below the path: the layer's box, a handle over it, a marker, or nothing. */
+type Under = boolean | "handle" | "marker";
+
+/** The overlay over a selected layer's box and a crop handle, scale 1: client px are composition px. */
+function mount() {
+  const overlay = document.createElement("div");
+  const chrome = overlay.appendChild(document.createElement("div"));
+  chrome.setAttribute("data-dom-edit-chrome", "true");
   const box = document.createElement("div");
   box.setAttribute("data-dom-edit-selection-box", "true");
+  box.style.cursor = "move";
+  const handle = document.createElement("button");
+  handle.style.cursor = "ew-resize";
+  chrome.append(box, handle);
+  // Another layer's off-canvas marker: no handler of its own, so a press on it reaches the overlay's marquee.
+  const marker = overlay.appendChild(document.createElement("div"));
+  overlay.addEventListener("pointerdown", (e) => {
+    if (!(e.target as Element).closest("[data-dom-edit-chrome]")) e.preventDefault();
+  });
   const host = document.createElement("div");
-  document.body.append(box, host);
+  document.body.append(overlay, host);
+  const handlePresses: number[] = [];
+  handle.addEventListener("pointerdown", (e) => {
+    handlePresses.push((e as PointerEvent).clientX);
+    e.preventDefault();
+  });
   const boxPresses: number[] = [];
-  let boxStarts = true;
+  const state = { boxStarts: true };
   box.addEventListener("pointerdown", (e) => {
     boxPresses.push((e as PointerEvent).clientX);
-    if (boxStarts) e.preventDefault();
+    if (state.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) => {
+  act(() =>
+    root.render(
+      <MotionPathOverlay
+        iframeRef={{ current: null }}
+        selection={selection}
+        compositionSize={{ width: 1920, height: 1080 }}
+        isPlaying={false}
+      />,
+    ),
+  );
+  cleanups.push(() => {
+    captured.mockRestore();
+    act(() => root.unmount());
+    overlay.remove();
+    host.remove();
+  });
+  /** Fires `type` at `target`; `under`: the layer's box, a handle over the box, or only the canvas. */
+  const fire = (target: Element, type: string, x: number, under: Under) => {
+    const stack = { handle: [handle, box], marker: [marker], true: [box], false: [] }[
+      String(under)
+    ]!;
+    document.elementsFromPoint = () => [target, ...stack, overlay];
+    const init = { bubbles: true, cancelable: true, button: 0, clientX: x, clientY: 30 };
+    act(() => void target.dispatchEvent(new PointerEvent(type, init)));
+  };
+  return { host, boxPresses, handlePresses, state, captured, fire };
+}
+
+it("the layer's node, and any node inside the layer's box, press the layer; outside it a node keeps the press", () => {
+  const { host, boxPresses, state, captured, fire } = mount();
+  const press = (node: number, x: number, inBox: Under) => {
     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)));
+    fire(hit, "pointerdown", x, inBox);
   };
-  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();
-  }
+  press(60, 63, false);
+  press(140, 130, true);
+  // On the dot itself: a drag from the layer's middle moves the layer (the edit bench's keys case).
+  press(140, 140, true);
+  expect(boxPresses).toEqual([63, 130, 140]);
+  act(() => usePlayerStore.setState({ activeKeyframePct: 100 }));
+  press(140, 140, true);
+  act(() => usePlayerStore.setState({ activeKeyframePct: null }));
+  expect(boxPresses).toEqual([63, 130, 140, 140]);
+  press(140, 138, false);
+  expect(boxPresses).toEqual([63, 130, 140, 140]);
+  // Over another layer's off-canvas marker the node keeps its press; the canvas starts no marquee.
+  captured.mockClear();
+  press(140, 138, "marker");
+  expect(captured).toHaveBeenCalledTimes(1);
+  expect(boxPresses).toEqual([63, 130, 140, 140]);
+  // A box that starts no gesture leaves the press to the node.
+  state.boxStarts = false;
+  captured.mockClear();
+  press(60, 63, false);
+  expect(captured).toHaveBeenCalledTimes(1);
+});
+
+it("the path's line inside the layer's box moves the layer and offers no add; outside it adds a keyframe", async () => {
+  const { host, boxPresses, fire } = mount();
+  const line = host.querySelector("polyline.pointer-events-auto") as SVGElement;
+  const ghost = () => host.querySelector("rect.pointer-events-none");
+
+  fire(line, "pointermove", 90, true);
+  expect(line.style.cursor).toBe("move");
+  expect(ghost()).toBeNull();
+  fire(line, "pointerdown", 90, true);
+  expect(boxPresses).toEqual([90]);
+  expect(commitMutation).not.toHaveBeenCalled();
+
+  fire(line, "pointermove", 90, false);
+  expect(line.style.cursor).toBe("copy");
+  expect(ghost()).not.toBeNull();
+  // Halfway along the drawn segment 60 to 140: halfway between the stored offsets 60 and 120.
+  fire(line, "pointerdown", 100, false);
+  expect(boxPresses).toEqual([90]);
+  await vi.waitFor(() => expect(commitMutation).toHaveBeenCalledTimes(1));
+  expect(commitMutation.mock.calls[0]![0]).toMatchObject({ properties: { x: 90, y: 30 } });
+});
+
+it("a crop or resize handle over a node or the line takes the press, not the node or the layer", () => {
+  const { host, boxPresses, handlePresses, captured, fire } = mount();
+  const node = host.querySelector('circle.pointer-events-auto[cx="140"]')!;
+  const line = host.querySelector("polyline.pointer-events-auto") as SVGElement;
+  captured.mockClear();
+  fire(node, "pointerdown", 142, "handle");
+  fire(line, "pointermove", 100, "handle");
+  expect(line.style.cursor).toBe("ew-resize");
+  fire(line, "pointerdown", 100, "handle");
+  expect(handlePresses).toEqual([142, 100]);
+  expect(boxPresses).toEqual([]);
+  expect(captured).not.toHaveBeenCalled();
+  expect(commitMutation).not.toHaveBeenCalled();
+});
+
+it("draws where GSAP started the tween before the first keyframe, as a mark that takes no press", () => {
+  const { host } = mount();
+  const start = host.querySelector("circle[data-motion-path-start]")!;
+  // 120 wide at the start against 100 now: drawn 10 px right.
+  expect([start.getAttribute("cx"), start.getAttribute("cy")]).toEqual(["50", "30"]);
+  expect(start.classList.contains("pointer-events-none")).toBe(true);
+  const drawn = host.querySelector("polyline:not(.pointer-events-auto)")!;
+  expect(drawn.getAttribute("points")).toBe("50,30 60,30 140,30");
 });

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

@@ -6,12 +6,17 @@ import { MotionPathOverlay } from "./MotionPathOverlay";
 import { usePlayerStore } from "../../player/store/playerStore";
 import { usePreviewIframeStore } from "../../player/store/previewIframeStore";
 import type { DomEditSelection } from "./domEditing";
+import { commitCreatePath } from "./motionPathCommit";
 
 Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
 
 vi.mock("../../contexts/DomEditContext", () => ({
   useDomEditContext: () => ({ selectedGsapAnimations: [] }),
 }));
+vi.mock("./motionPathCommit", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./motionPathCommit")>()),
+  commitCreatePath: vi.fn(),
+}));
 vi.mock("./motionPathSelection", () => ({
   selectorFor: () => "#box",
   editableAnimationId: () => null,
@@ -63,3 +68,43 @@ it("re-evaluates set-destination availability when a reload swaps the live ifram
     after.remove();
   }
 });
+
+it("sets a destination on a layer whichever window built its node", () => {
+  const host = document.createElement("div");
+  const surface = document.createElement("div");
+  surface.setAttribute("data-preview-pan-surface", "");
+  const frame = document.createElement("iframe");
+  document.body.append(host, surface, frame);
+  Reflect.set(frame.contentWindow as object, "MotionPathPlugin", {});
+  frame.getBoundingClientRect = () => new DOMRect(0, 0, 1920, 1080);
+  // As on the loads that hid the path, the layer's node carries the editor window's prototypes.
+  const box = document.createElement("div");
+  box.id = "box";
+  frame.contentDocument!.body.append(box);
+  const root = createRoot(host);
+  const selection = { element: box } as unknown as DomEditSelection;
+  try {
+    act(() => usePreviewIframeStore.getState().setIframe(frame));
+    act(() =>
+      root.render(
+        <MotionPathOverlay
+          iframeRef={{ current: frame }}
+          selection={selection}
+          compositionSize={{ width: 1920, height: 1080 }}
+          isPlaying={false}
+        />,
+      ),
+    );
+    act(() => usePlayerStore.getState().setMotionPathArmed(true));
+    const press = { bubbles: true, button: 0, clientX: 100, clientY: 100 };
+    act(() => void surface.dispatchEvent(new PointerEvent("pointerdown", press)));
+    expect(commitCreatePath).toHaveBeenCalledTimes(1);
+  } finally {
+    act(() => usePlayerStore.getState().setMotionPathArmed(false));
+    act(() => root.unmount());
+    usePreviewIframeStore.setState({ iframe: null });
+    host.remove();
+    surface.remove();
+    frame.remove();
+  }
+});

package/src/components/editor/MotionPathOverlay.tsx

@@ -8,11 +8,12 @@ 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,
@@ -25,13 +26,8 @@ import {
   commitNode,
   commitRemoveWaypoint,
 } 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>;
@@ -101,6 +97,7 @@ export const MotionPathOverlay = memo(function MotionPathOverlay({
   );
   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 +191,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 +281,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 +310,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,10 +373,7 @@ 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.
+    // Auto-keyframe off (#1808): dragging a keyframe's node shifts the whole path.
     const anim =
       d.ref.type === "keyframe" ? selectedGsapAnimations?.find((a) => a.id === animId) : undefined;
     if (
@@ -405,9 +397,7 @@ export const MotionPathOverlay = memo(function MotionPathOverlay({
     } 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.
+    // 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 +405,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 +430,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 +455,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 +520,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);