@hyperframes/studio 0.8.121 → 0.8.123

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.121",
+  "version": "0.8.123",
   "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.121",
-    "@hyperframes/sdk": "0.8.121",
-    "@hyperframes/shader-transitions": "0.8.121",
-    "@hyperframes/player": "0.8.121",
-    "@hyperframes/studio-server": "0.8.121",
-    "@hyperframes/parsers": "0.8.121"
+    "@hyperframes/core": "0.8.123",
+    "@hyperframes/parsers": "0.8.123",
+    "@hyperframes/player": "0.8.123",
+    "@hyperframes/sdk": "0.8.123",
+    "@hyperframes/shader-transitions": "0.8.123",
+    "@hyperframes/studio-server": "0.8.123"
   },
   "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.121"
+    "@hyperframes/producer": "0.8.123"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/FrameyGlyph.tsx

@@ -0,0 +1,52 @@
+import type { Ref } from "react";
+
+// Framey, the desktop app's cursor mascot, as hyperframes-internal packages/nib draws it: a rounded triangle with a
+// white rim and one eye. The viewBox frames the body with its rim; the tip points up and left like a cursor.
+const BODY = "M77.55 48.44 L122.77 65.85 L99.3 89.41 Z";
+const EYE = { cx: 111.6, cy: 68.2, r: 11.5 };
+
+/** `eyeRef` moves the pupils (a translate of a few px) without re-rendering. */
+export function FrameyGlyph({
+  size,
+  className,
+  eyeRef,
+}: {
+  size: number;
+  className?: string;
+  eyeRef?: Ref<SVGGElement>;
+}) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="58 30 82 76"
+      aria-hidden="true"
+      className={className}
+      overflow="visible"
+    >
+      <path
+        d={BODY}
+        fill="var(--color-white)"
+        stroke="var(--color-white)"
+        strokeWidth={24}
+        strokeLinejoin="round"
+      />
+      <path
+        d={BODY}
+        fill="var(--color-framey)"
+        stroke="var(--color-framey)"
+        strokeWidth={19}
+        strokeLinejoin="round"
+      />
+      <circle cx={EYE.cx} cy={EYE.cy} r={EYE.r} fill="var(--color-white)" />
+      <g ref={eyeRef} className="hf-framey-eye">
+        <path
+          d={`M${EYE.cx - 2.6} ${EYE.cy - 2} V${EYE.cy + 2} M${EYE.cx + 2.6} ${EYE.cy - 2} V${EYE.cy + 2}`}
+          stroke="var(--color-framey-ink)"
+          strokeWidth={2.4}
+          strokeLinecap="round"
+        />
+      </g>
+    </svg>
+  );
+}

package/src/components/OpenInDesktopButton.dom.test.tsx

@@ -0,0 +1,113 @@
+// @vitest-environment happy-dom
+
+/**
+ * "Edit with Framey": shown only where the preview server answers on macOS; a press opens the project in the app,
+ * or introduces Framey with the download while the app cannot take it or is missing.
+ */
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const showToast = vi.fn();
+vi.mock("../contexts/StudioContext", () => ({ useStudioShellContext: () => ({ showToast }) }));
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+
+const { OpenInDesktopButton } = await import("./OpenInDesktopButton");
+
+const DOWNLOAD = "https://hyperframes.dev/studio/download";
+let mounted: { root: Root; host: HTMLElement } | null = null;
+let posts: number;
+
+function serve(get: Response | null, post?: unknown) {
+  posts = 0;
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (_url: string, init?: RequestInit) => {
+      if (init?.method === "POST") {
+        posts += 1;
+        return Response.json(post);
+      }
+      return get ?? new Response("Not found", { status: 404 });
+    }),
+  );
+}
+
+async function mount(): Promise<HTMLElement> {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  mounted = { root, host };
+  await act(async () => root.render(<OpenInDesktopButton />));
+  return host;
+}
+
+const downloadHref = () =>
+  [...document.querySelectorAll("a")]
+    .find((a) => a.textContent?.includes("Get HyperFrames Studio"))
+    ?.getAttribute("href");
+
+const button = () =>
+  document.querySelector<HTMLButtonElement>('[data-testid="header-open-in-desktop"]');
+
+beforeEach(() => showToast.mockReset());
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  if (!mounted) return;
+  const { root, host } = mounted;
+  mounted = null;
+  act(() => root.unmount());
+  host.remove();
+});
+
+it("stays hidden where the server has no hand-off (the desktop's own Studio)", async () => {
+  serve(null);
+  await mount();
+  expect(button()).toBeNull();
+});
+
+it("stays hidden when the server says it cannot open the app (not macOS)", async () => {
+  serve(Response.json({ available: false }));
+  await mount();
+  expect(button()).toBeNull();
+});
+
+it("while the app cannot take a project yet, introduces Framey with the download and opens nothing", async () => {
+  serve(Response.json({ available: true, handoff: false }), { opened: true });
+  await mount();
+  await act(async () => button()!.click());
+  expect(posts).toBe(0);
+  expect(document.body.textContent).toContain("Meet Framey");
+  expect(downloadHref()).toBe(DOWNLOAD);
+});
+
+it("opens the project in the app and says so", async () => {
+  serve(Response.json({ available: true, handoff: true }), {
+    opened: true,
+    bundleId: "dev.hyperframes.desktop",
+  });
+  await mount();
+  await act(async () => button()!.click());
+  expect(posts).toBe(1);
+  expect(showToast).toHaveBeenCalledWith(
+    "Framey is opening this project in HyperFrames Studio",
+    "info",
+  );
+  expect(button()!.dataset.opening).toBe("true");
+  expect(document.body.textContent).not.toContain("Meet Framey");
+});
+
+it("introduces Framey and offers the download when the app is missing", async () => {
+  serve(Response.json({ available: true, handoff: true }), {
+    opened: false,
+    reason: "not-installed",
+    downloadUrl: DOWNLOAD,
+  });
+  await mount();
+  await act(async () => button()!.click());
+  expect(showToast).not.toHaveBeenCalled();
+  expect(document.body.textContent).toContain("Meet Framey");
+  expect(downloadHref()).toBe(DOWNLOAD);
+});

package/src/components/OpenInDesktopButton.tsx

@@ -0,0 +1,153 @@
+import { useEffect, useRef, useState } from "react";
+import { useStudioShellContext } from "../contexts/StudioContext";
+import { studioApiFetch } from "../utils/studioApiFetch";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+import { FrameyGlyph } from "./FrameyGlyph";
+import { Button, buttonBase, buttonSizes, buttonVariants, cn, Popover } from "./ui";
+
+// "Edit with Framey": the preview server (`/api/open-in-desktop`) says whether to show it and whether the app can
+// take the project yet (its gate is the CLI's HANDOFF_READY); until then a press introduces Framey with the download.
+const ROUTE = "/api/open-in-desktop";
+const DOWNLOAD_URL = "https://hyperframes.dev/studio/download";
+/** How far the pupils travel towards the pointer, in the glyph's own units. */
+const GAZE = 2.2;
+/** Long enough for the flight to finish before the label comes back. */
+const OPENING_MS = 1600;
+
+type OpenResult = { opened: true } | { opened: false; reason: string; downloadUrl: string };
+
+/** Null hides the button: no such route (the app's own Studio), or not macOS. */
+function useDesktopRoute(): { handoff: boolean } | null {
+  const [route, setRoute] = useState<{ handoff: boolean } | null>(null);
+  useEffect(() => {
+    let live = true;
+    studioApiFetch(ROUTE)
+      .then((res) => (res.ok ? res.json() : null))
+      .then((body: { available?: unknown; handoff?: unknown } | null) => {
+        if (live && body?.available === true) setRoute({ handoff: body.handoff === true });
+      })
+      .catch(() => {});
+    return () => {
+      live = false;
+    };
+  }, []);
+  return route;
+}
+
+/** Framey looks at the pointer: one listener, one write per frame, no re-render. */
+function useGaze(
+  anchor: React.RefObject<HTMLElement | null>,
+  eye: React.RefObject<SVGGElement | null>,
+) {
+  useEffect(() => {
+    let frame = 0;
+    const look = (event: PointerEvent) => {
+      cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(() => {
+        const box = anchor.current?.getBoundingClientRect();
+        if (!box || !eye.current) return;
+        const dx = event.clientX - (box.left + box.height / 2);
+        const dy = event.clientY - (box.top + box.height / 2);
+        const distance = Math.hypot(dx, dy) || 1;
+        eye.current.style.transform = `translate(${(dx / distance) * GAZE}px, ${(dy / distance) * GAZE}px)`;
+      });
+    };
+    window.addEventListener("pointermove", look);
+    return () => {
+      cancelAnimationFrame(frame);
+      window.removeEventListener("pointermove", look);
+    };
+  }, [anchor, eye]);
+}
+
+export function OpenInDesktopButton() {
+  const { showToast } = useStudioShellContext();
+  const route = useDesktopRoute();
+  const [opening, setOpening] = useState(false);
+  // The card under the button, introducing Framey with the app's download.
+  const [downloadUrl, setDownloadUrl] = useState<string | null>(null);
+  const trigger = useRef<HTMLButtonElement>(null);
+  const eye = useRef<SVGGElement>(null);
+  useGaze(trigger, eye);
+  if (!route) return null;
+
+  const open = async () => {
+    if (!route.handoff) {
+      trackStudioEvent("toolbar_action", { action: "open_in_desktop" });
+      setDownloadUrl(DOWNLOAD_URL);
+      return;
+    }
+    if (opening) return;
+    setOpening(true);
+    trackStudioEvent("toolbar_action", { action: "open_in_desktop" });
+    try {
+      const res = await studioApiFetch(ROUTE, { method: "POST" });
+      const result = (await res.json()) as OpenResult;
+      if (result.opened) {
+        showToast("Framey is opening this project in HyperFrames Studio", "info");
+        await new Promise((done) => setTimeout(done, OPENING_MS));
+      } else setDownloadUrl(result.downloadUrl);
+    } catch {
+      showToast("Couldn't reach the preview server to open the app", "error");
+    } finally {
+      setOpening(false);
+    }
+  };
+
+  return (
+    <Popover
+      open={downloadUrl !== null}
+      // The popover owns the trigger's press: a press runs the hand-off, and the card shows only when there is
+      // something to say (the download). A second handler on the button raced this one.
+      onOpenChange={(next) => {
+        if (next) void open();
+        else setDownloadUrl(null);
+      }}
+      side="bottom"
+      align="end"
+      arrow
+      aria-label="Meet Framey"
+      className="w-72"
+      trigger={
+        <Button
+          ref={trigger}
+          variant="ghost"
+          data-testid="header-open-in-desktop"
+          data-opening={opening || undefined}
+          title="Open this project in HyperFrames Studio, the desktop app, and edit it with Framey"
+          className="hf-framey-trigger gap-1.5 pl-1.5"
+          icon={<FrameyGlyph size={20} className="hf-framey" eyeRef={eye} />}
+        >
+          {opening ? "Opening in the app…" : "Edit with Framey"}
+        </Button>
+      }
+    >
+      <div className="flex items-center gap-2.5">
+        <FrameyGlyph size={36} />
+        <p className="text-step-12 font-medium text-text-0">Meet Framey</p>
+      </div>
+      <p className="mt-2 text-text-3">
+        I live in HyperFrames Studio, the free desktop app for macOS:
+      </p>
+      <ul className="mt-1.5 grid gap-1 text-text-1">
+        <li>Chat to change anything in the video</li>
+        <li>Draw on a frame to point at it</li>
+        <li>Watch me act out each edit</li>
+      </ul>
+      <div className="mt-3 flex items-center justify-end gap-2 whitespace-nowrap">
+        <Button variant="ghost" onClick={() => setDownloadUrl(null)}>
+          Not now
+        </Button>
+        <a
+          href={downloadUrl ?? undefined}
+          target="_blank"
+          rel="noopener noreferrer"
+          className={cn(buttonBase, buttonVariants.primary, buttonSizes.md)}
+          onClick={() => trackStudioEvent("toolbar_action", { action: "get_desktop_app" })}
+        >
+          Get HyperFrames Studio
+        </a>
+      </div>
+    </Popover>
+  );
+}

package/src/components/StudioHeader.dom.test.tsx

@@ -40,6 +40,8 @@ vi.mock("../contexts/PanelLayoutContext", () => ({
 }));
 
 vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+// Probes the preview server on mount; covered in OpenInDesktopButton.dom.test.tsx.
+vi.mock("./OpenInDesktopButton", () => ({ OpenInDesktopButton: () => null }));
 
 const { StudioHeader } = await import("./StudioHeader");
 const { ShowThemeToggle } = await import("./ThemeToggle");

package/src/components/StudioHeader.tsx

@@ -6,6 +6,7 @@ import { trackStudioEvent } from "../utils/studioTelemetry";
 import { Button, buttonBase, buttonSizes, buttonVariants, cn, Tooltip } from "./ui";
 import { Dock } from "./dock/Dock";
 import { InspectorIcon } from "./icons/InspectorIcon";
+import { OpenInDesktopButton } from "./OpenInDesktopButton";
 import { HyperframesLogo } from "./ui/HyperframesLogo";
 import { ShowThemeToggle, ThemeToggle } from "./ThemeToggle";
 
@@ -151,6 +152,7 @@ export const StudioHeader = memo(function StudioHeader({
         </div>
         {showThemeToggle && <ThemeToggle />}
         <Dock.WindowMenu />
+        <OpenInDesktopButton />
         <Tooltip
           label={
             ffmpegMissing

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);