@hyperframes/studio 0.7.102 → 0.7.104

package/src/components/editor/groupDragMove.ts

@@ -0,0 +1,110 @@
+import { resolveDomEditGroupOverlayRect } from "./domEditOverlayGeometry";
+import {
+  resolveEquidistanceGuides,
+  resolveSnapAdjustment,
+  snapEngagedForTravel,
+  SNAP_THRESHOLD_PX,
+} from "./snapEngine";
+import { applyManualOffsetDragDraft } from "./manualOffsetDrag";
+import type { GroupGestureState, UseDomEditOverlayGesturesOptions } from "./domEditOverlayGestures";
+import type { GroupOverlayItem } from "./domEditOverlayGeometry";
+import {
+  findNonRigidMembers,
+  logDrag,
+  logDragMove,
+  readDragPositions,
+} from "../../utils/dragDebug";
+
+/**
+ * One frame of a group drag, kept out of onPointerMove — which already handles
+ * four gesture kinds and reads better without this one's snapping arithmetic.
+ * The previous frame's positions live in the closure so the rigidity check below
+ * compares against the frame before, not against whatever was last sampled.
+ */
+export function createGroupDragMover(
+  opts: UseDomEditOverlayGesturesOptions,
+  setDraftGroupOverlayItems: (items: GroupOverlayItem[]) => void,
+) {
+  let lastGroupPositions: Record<string, string> = {};
+  let lastGesture: GroupGestureState | null = null;
+
+  /** Snap the group's delta to nearby edges, publishing the guides drawn for it. */
+  // fallow-ignore-next-line complexity
+  const snapGroupDelta = (
+    groupG: GroupGestureState,
+    e: React.PointerEvent<HTMLDivElement>,
+    proposed: { dx: number; dy: number },
+  ) => {
+    const sc = groupG.snapContext;
+    if (!sc?.snapEnabled || sc.targets.length === 0) return proposed;
+    if (!snapEngagedForTravel(proposed.dx, proposed.dy)) {
+      opts.snapGuidesRef.current = null;
+      return proposed;
+    }
+    const groupBounds = resolveDomEditGroupOverlayRect(groupG.originItems.map((i) => i.rect));
+    if (!groupBounds) return proposed;
+    const allTargets = sc.compositionTarget ? [...sc.targets, sc.compositionTarget] : sc.targets;
+    const snap = resolveSnapAdjustment({
+      movingRect: groupBounds,
+      proposedDx: proposed.dx,
+      proposedDy: proposed.dy,
+      targets: allTargets,
+      gridEdges: sc.gridEdges ?? undefined,
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: e.altKey,
+    });
+    const movingRect = {
+      ...groupBounds,
+      left: groupBounds.left + snap.dx,
+      top: groupBounds.top + snap.dy,
+    };
+    const spacingGuides = e.altKey
+      ? []
+      : resolveEquidistanceGuides({
+          movingRect,
+          targets: allTargets,
+          threshold: SNAP_THRESHOLD_PX,
+        });
+    opts.snapGuidesRef.current = { guides: snap.guides, spacingGuides };
+    return { dx: snap.dx, dy: snap.dy };
+  };
+
+  /** One frame of a group drag: snap the delta, redraw the boxes, move every member. */
+  const moveGroupDrag = (groupG: GroupGestureState, e: React.PointerEvent<HTMLDivElement>) => {
+    if (groupG !== lastGesture) {
+      lastGesture = groupG;
+      lastGroupPositions = {};
+    }
+    const { dx, dy } = snapGroupDelta(groupG, e, {
+      dx: e.clientX - groupG.startX,
+      dy: e.clientY - groupG.startY,
+    });
+    groupG.lastSnappedDx = dx;
+    groupG.lastSnappedDy = dy;
+
+    setDraftGroupOverlayItems(
+      groupG.originItems.map((i) => ({
+        ...i,
+        rect: { ...i.rect, left: i.rect.left + dx, top: i.rect.top + dy },
+      })),
+    );
+    const offsets: Record<string, string> = {};
+    for (const m of groupG.members) {
+      const n = applyManualOffsetDragDraft(m, dx, dy);
+      offsets[m.key] = `${Math.round(n.x)},${Math.round(n.y)}`;
+    }
+    const at = readDragPositions(groupG.members);
+    const px = Math.round(e.clientX - groupG.startX);
+    const py = Math.round(e.clientY - groupG.startY);
+    // A member breaking away IS the fault, so it reports on the frame it happens;
+    // the throttled line below would step over it. A gap between pointer and
+    // applied there is snapping pulling the group off the cursor.
+    const trace = { pointer: `${px},${py}`, applied: `${Math.round(dx)},${Math.round(dy)}`, at };
+    const drift = findNonRigidMembers(lastGroupPositions, at);
+    if (drift.length > 0) logDrag("drift", { ...trace, drift });
+    lastGroupPositions = at;
+    logDragMove({ ...trace, offsets });
+  };
+
+  return moveGroupDrag;
+}

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

@@ -0,0 +1,70 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, vi } from "vitest";
+import { createDomEditOverlayGestureHandlers } from "./useDomEditOverlayGestures";
+import type { GroupGestureState } from "./domEditOverlayGestures";
+
+/**
+ * A group drag ended by deselecting the group it had just moved.
+ *
+ * Every pointerup trails a click. The gesture ref is cleared before the commit,
+ * so by the time that click arrives the box no longer looks busy and it reaches
+ * the canvas as an ordinary click — landing in the gap between the members,
+ * resolving to nothing, and clearing the selection. Captured live as a
+ * `[hf-select] clear` with `hadGroup: 3` two milliseconds after the drop.
+ *
+ * The under-threshold path already ate that click; the committed path has to as
+ * well, and the flag is set before the two diverge so neither can forget.
+ */
+describe("dropping a dragged group eats the click that follows", () => {
+  function harness(travel: { dx: number; dy: number }) {
+    const suppressNextBoxClickRef = { current: false };
+    const groupGestureRef = {
+      current: {
+        startX: 0,
+        startY: 0,
+        originItems: [],
+        members: [],
+      } as unknown as GroupGestureState,
+    };
+    const handlers = createDomEditOverlayGestureHandlers({
+      overlayRef: { current: null },
+      iframeRef: { current: null },
+      boxRef: { current: null },
+      selectionRef: { current: null },
+      hoverSelectionRef: { current: null },
+      overlayRectRef: { current: null },
+      groupOverlayItemsRef: { current: [] },
+      gestureRef: { current: null },
+      groupGestureRef,
+      blockedMoveRef: { current: null },
+      rafPausedRef: { current: false },
+      suppressNextBoxClickRef,
+      setOverlayRect: vi.fn(),
+      setGroupOverlayItems: vi.fn(),
+      onBlockedMoveRef: { current: vi.fn() },
+      onManualDragStartRef: { current: vi.fn() },
+      onPathOffsetCommitRef: { current: vi.fn() },
+      onGroupPathOffsetCommitRef: { current: vi.fn() },
+      onBoxSizeCommitRef: { current: vi.fn() },
+      onRotationCommitRef: { current: vi.fn() },
+      onCanvasPointerMoveRef: { current: vi.fn() },
+      onCanvasMouseDown: vi.fn(),
+      snapGuidesRef: { current: null },
+    } as never);
+
+    handlers.onPointerUp({
+      clientX: travel.dx,
+      clientY: travel.dy,
+      currentTarget: { releasePointerCapture: vi.fn() },
+    } as never);
+    return suppressNextBoxClickRef;
+  }
+
+  it("eats the click after a drag that moved", () => {
+    expect(harness({ dx: 120, dy: 60 }).current).toBe(true);
+  });
+
+  it("still eats it after a press that never travelled", () => {
+    expect(harness({ dx: 1, dy: 0 }).current).toBe(true);
+  });
+});

package/src/components/editor/manualEditsDom.ts

@@ -221,6 +221,7 @@ function isIdentityAfterTranslateStrip(m: DOMMatrix): boolean {
   return m.is2D && m.a === 1 && m.b === 0 && m.c === 0 && m.d === 1;
 }
 
+// fallow-ignore-next-line complexity
 function stripGsapTranslateFromTransform(element: HTMLElement): void {
   if (element.hasAttribute(STUDIO_MANUAL_EDIT_GESTURE_ATTR)) return;
   const transform = element.style.getPropertyValue("transform");
@@ -256,6 +257,7 @@ function stripGsapTranslateFromTransform(element: HTMLElement): void {
 // and push the offset straight into GSAP's x/y via gsap.set; the var() offset is
 // still persisted (buildPathOffsetPatches), and GSAP re-reads it at init on
 // reload. Returns true when handled as GSAP (caller must skip the CSS path).
+// fallow-ignore-next-line complexity
 function applyStudioPathOffsetViaGsap(
   element: HTMLElement,
   offset: { x: number; y: number },
@@ -553,26 +555,26 @@ function queryStudioElements(doc: Document, attr: string): HTMLElement[] {
 
 function reapplyPathOffsets(doc: Document): void {
   for (const el of queryStudioElements(doc, STUDIO_PATH_OFFSET_ATTR)) {
-    const gsapSkip = gsapAnimatesProperty(el, "x", "y");
+    // Unlike size below, the offset channels COMPOSE — applying both doubles the move.
+    if (gsapAnimatesProperty(el, "x", "y")) continue;
     const x = el.style.getPropertyValue(STUDIO_OFFSET_X_PROP);
     const y = el.style.getPropertyValue(STUDIO_OFFSET_Y_PROP);
-    if (gsapSkip) continue;
-    if (x || y) {
-      applyStudioPathOffset(
-        el,
-        {
-          x: Number.parseFloat(x) || 0,
-          y: Number.parseFloat(y) || 0,
-        },
-        { updateBase: false },
-      );
-    }
+    if (!x && !y) continue;
+    const offset = { x: Number.parseFloat(x) || 0, y: Number.parseFloat(y) || 0 };
+    applyStudioPathOffset(el, offset, { updateBase: false });
   }
 }
 
+/**
+ * Put the studio's committed size back after a seek, GSAP-sized elements included.
+ * Size does not compose the way the offset above does: both channels write width
+ * and height, so the later write wins on the same number. Standing aside meant
+ * nothing held the size while a soft reload reverted the old timeline (GSAP hands
+ * back each tween's recorded starting width), so the element sat at its stylesheet
+ * size until the new one rendered — the jump after a resize.
+ */
 function reapplyBoxSizes(doc: Document): void {
   for (const el of queryStudioElements(doc, STUDIO_BOX_SIZE_ATTR)) {
-    if (gsapAnimatesProperty(el, "width", "height")) continue;
     const w = Number.parseFloat(el.style.getPropertyValue(STUDIO_WIDTH_PROP));
     const h = Number.parseFloat(el.style.getPropertyValue(STUDIO_HEIGHT_PROP));
     if (Number.isFinite(w) && Number.isFinite(h) && w > 0 && h > 0) {

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

@@ -88,6 +88,41 @@ describe("measureManualOffsetDragScreenToOffsetMatrix", () => {
     expect(element.style.getPropertyValue("translate")).toBe("");
   });
 
+  /**
+   * The element that has never been offset is the common case, and it used to skip
+   * the measurement and assume the canvas zoom was the whole story. Any transform
+   * above the element makes that assumption wrong: the mirrored parent here sends a
+   * rightward drag left, so the overlay followed the pointer while the element went
+   * the other way, and only on drop did the overlay jump to where the element really
+   * was. The fixture mirrors x and scales both axes by 1.2, as a `rotationY: 180`
+   * card at `scale: 1.2` does.
+   */
+  it("measures a mirrored parent even when the element carries no offset yet", () => {
+    const window = new Window();
+    const element = window.document.createElement("div");
+    window.document.body.append(element);
+
+    element.getBoundingClientRect = () => {
+      const offsetX = Number.parseFloat(element.style.getPropertyValue(STUDIO_OFFSET_X_PROP)) || 0;
+      const offsetY = Number.parseFloat(element.style.getPropertyValue(STUDIO_OFFSET_Y_PROP)) || 0;
+      return new window.DOMRect(100 - 1.2 * offsetX, 200 + 1.2 * offsetY, 40, 20);
+    };
+
+    const measured = measureManualOffsetDragScreenToOffsetMatrix(element, { x: 0, y: 0 });
+    if (!measured.ok) throw new Error(measured.reason);
+
+    // Dragging one screen px right must move the element one screen px right, which
+    // on a mirrored parent means writing a NEGATIVE offset.
+    const offset = resolveManualOffsetForPointerDelta({
+      initialOffset: { x: 0, y: 0 },
+      screenToOffset: measured.matrix,
+      dx: 60,
+      dy: 60,
+    });
+    expect(offset.x).toBeCloseTo(-50, 6);
+    expect(offset.y).toBeCloseTo(50, 6);
+  });
+
   it("measures movement in parent viewport pixels when the element is inside a scaled iframe", () => {
     const window = new Window();
     const iframe = window.document.createElement("iframe");
@@ -133,7 +168,12 @@ describe("measureManualOffsetDragScreenToOffsetMatrix", () => {
     expect(nextOffset).toEqual({ x: 100, y: 50 });
   });
 
-  it("returns identity matrix for non-path-offset elements with zero initial offset", () => {
+  // Carrying no path offset used to be taken as permission to assume the response
+  // instead of measuring it. It is not a signal about the transforms above the
+  // element, so it no longer changes the answer: an element that does not move is
+  // unmeasurable either way, and the caller falls back rather than being handed a
+  // matrix that was never checked.
+  it("does not treat a missing path offset as a measurable response", () => {
     const window = new Window();
     const element = window.document.createElement("div");
     window.document.body.append(element);
@@ -141,10 +181,7 @@ describe("measureManualOffsetDragScreenToOffsetMatrix", () => {
 
     const measured = measureManualOffsetDragScreenToOffsetMatrix(element, { x: 0, y: 0 });
 
-    expect(measured.ok).toBe(true);
-    if (measured.ok) {
-      expectMatrixClose(measured.matrix, { a: 1, b: 0, c: 0, d: 1 });
-    }
+    expect(measured.ok).toBe(false);
   });
 
   it("rejects path-offset elements whose movement response cannot be measured", () => {
@@ -160,6 +197,56 @@ describe("measureManualOffsetDragScreenToOffsetMatrix", () => {
   });
 });
 
+/**
+ * A group drag is rigid: every member is handed the SAME pointer delta and must
+ * travel the same distance on screen, or the group visibly comes apart mid-drag.
+ * Members do not share a mapping though — each measures its own, because each can
+ * sit under different ancestor transforms. A member whose movement cannot be
+ * measured falls back to a guess, and this pins what that guess costs the group.
+ */
+describe("group drag stays rigid", () => {
+  function member(key: string, response: number, measurable: boolean) {
+    const window = new Window();
+    const element = window.document.createElement("div");
+    window.document.body.append(element);
+    element.getBoundingClientRect = () => {
+      const ox = Number.parseFloat(element.style.getPropertyValue(STUDIO_OFFSET_X_PROP)) || 0;
+      const oy = Number.parseFloat(element.style.getPropertyValue(STUDIO_OFFSET_Y_PROP)) || 0;
+      const move = measurable ? response : 0;
+      return new window.DOMRect(100 + move * ox, 200 + move * oy, 40, 20);
+    };
+    const result = createManualOffsetDragMember({
+      key,
+      selection: { element } as never,
+      element,
+      rect: { left: 100, top: 200, width: 40, height: 20, editScaleX: 1, editScaleY: 1 },
+    });
+    if (!result.ok) throw new Error(result.reason);
+    return { member: result.member, response };
+  }
+
+  /** Screen distance this member travels for a pointer delta of `d`. */
+  function screenTravel(entry: ReturnType<typeof member>, d: number): number {
+    const offset = resolveManualOffsetForPointerDelta({
+      initialOffset: entry.member.initialOffset,
+      screenToOffset: entry.member.screenToOffset,
+      dx: d,
+      dy: 0,
+    });
+    return offset.x * entry.response;
+  }
+
+  it("moves every measurable member the same distance for one pointer delta", () => {
+    // Two members under different ancestor scales: one 1:1, one inside a half-scale
+    // parent. Different offsets, identical screen travel — that is what rigid means.
+    const a = member("a", 1, true);
+    const b = member("b", 0.5, true);
+
+    expect(screenTravel(a, 60)).toBeCloseTo(60, 6);
+    expect(screenTravel(b, 60)).toBeCloseTo(60, 6);
+  });
+});
+
 describe("createManualOffsetDragMember uses raw CSS var offset", () => {
   it("ignores GSAP transform — initialOffset comes from CSS vars only", () => {
     const window = new Window();

package/src/components/editor/manualOffsetDrag.ts

@@ -213,9 +213,9 @@ export function applyManualOffsetDragMatrix(matrix: ManualOffsetDragMatrix, poin
  * The perspective w-divisor (matrix3d m44) of the element's current transform.
  * For a plain `translateZ(z)` under `perspective(p)`, m44 = (p - z) / p, so the
  * element renders 1/m44× larger and a translate of `d` composition px moves
- * `d / m44` px on screen. Returns 1 for 2D transforms (no foreshortening). Used
- * to keep the drag offset → screen-movement mapping correct for depth elements,
- * which the flat-scale fast path below would otherwise get wrong by 1/m44.
+ * `d / m44` px on screen. Returns 1 for 2D transforms (no foreshortening). Only
+ * the unmeasurable-element fallback needs this — the measured path reads the
+ * foreshortening off the element's real movement along with everything else.
  */
 function readTransformWDivisor(element: HTMLElement): number {
   const t = element.ownerDocument.defaultView?.getComputedStyle(element).transform;
@@ -225,25 +225,25 @@ function readTransformWDivisor(element: HTMLElement): number {
   return Number.isFinite(w) && w > 0 ? w : 1;
 }
 
+/**
+ * How far the element actually moves on screen per unit of drag offset, measured
+ * rather than assumed.
+ *
+ * The offset is written on the element, but what reaches the screen is that offset
+ * put through every transform above it. A parent carrying a rotation, a mirror, a
+ * scale or a perspective changes both the direction and the distance — a card at
+ * `rotationY: 180` sends a rightward drag left. Guessing this from the canvas zoom
+ * alone was wrong for every such element: the overlay tracked the pointer while the
+ * element went somewhere else, and the overlay only jumped to the truth on drop,
+ * when it re-measured. Moving the element and watching where it lands costs three
+ * layout reads once per gesture and is right for any transform, including ones no
+ * closed-form fast path would cover.
+ */
 export function measureManualOffsetDragScreenToOffsetMatrix(
   element: HTMLElement,
   initialOffset: { x: number; y: number },
   options: { probeSize?: number; scaleX?: number; scaleY?: number } = {},
 ): { ok: true; matrix: ManualOffsetDragMatrix } | { ok: false; reason: string } {
-  if (
-    !element.hasAttribute("data-hf-studio-path-offset") &&
-    initialOffset.x === 0 &&
-    initialOffset.y === 0
-  ) {
-    const sx = options.scaleX || 1;
-    const sy = options.scaleY || 1;
-    // Fold in the perspective foreshortening: a depth element (z≠0) moves
-    // 1/m44× faster on screen than its flat scale implies, so the screen→offset
-    // matrix must scale by m44 or the element outruns the pointer/overlay.
-    const w = readTransformWDivisor(element);
-    return { ok: true, matrix: { a: w / sx, b: 0, c: 0, d: w / sy } };
-  }
-
   const probeSize = options.probeSize ?? DEFAULT_OFFSET_PROBE_PX;
   if (!Number.isFinite(probeSize) || probeSize <= 0) {
     return { ok: false, reason: "Invalid movement probe size." };
@@ -325,6 +325,8 @@ export function resolveManualOffsetForPointerDelta(input: {
   };
 }
 
+// Pre-existing complexity — surfaced by this branch touching the file, not by new logic.
+// fallow-ignore-next-line complexity
 export function createManualOffsetDragMember(input: {
   key: string;
   selection: DomEditSelection;
@@ -515,6 +517,7 @@ function restoreManualOffsetDragMember(member: ManualOffsetDragMember): void {
   endStudioManualEditGesture(member.element, member.gestureToken);
 }
 
+/** Roll back a FAILED drag to the exact gesture-start state. */
 export function restoreManualOffsetDragMembers(members: ManualOffsetDragMember[]): void {
   for (const member of members) {
     restoreManualOffsetDragMember(member);
@@ -522,6 +525,7 @@ export function restoreManualOffsetDragMembers(members: ManualOffsetDragMember[]
   }
 }
 
+/** Teardown after a COMMITTED drag. */
 export function endManualOffsetDragMembers(members: ManualOffsetDragMember[]): void {
   for (const member of members) {
     endStudioManualEditGesture(member.element, member.gestureToken);
@@ -550,6 +554,7 @@ export function endManualOffsetDragMembers(members: ManualOffsetDragMember[]): v
   }
 }
 
+/** Shared timeline teardown for either the committed or restored path. */
 export function resumeGsapTimelines(element: HTMLElement): void {
   const ids = element.getAttribute("data-hf-drag-paused-timelines");
   element.removeAttribute("data-hf-drag-paused-timelines");

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

@@ -0,0 +1,64 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from "vitest";
+import { reapplyPositionEditsAfterSeek } from "./manualEditsDom";
+import { STUDIO_BOX_SIZE_ATTR, STUDIO_HEIGHT_PROP, STUDIO_WIDTH_PROP } from "./manualEditsTypes";
+
+/**
+ * A resize commit hands the size to a GSAP tween, and a soft reload reverts the
+ * old timeline before the new one renders — GSAP restores each tween's recorded
+ * starting width on the way out. Nothing else held the size across that window,
+ * so the element sat at its stylesheet size for a few hundred milliseconds: the
+ * jump after a resize. Worse, the next gesture then started from a box that
+ * disagreed with the studio's own vars and snapped on its first move.
+ *
+ * The seek reapply is what closes the window, and it used to stand aside for
+ * exactly the elements that need it — the ones GSAP sizes.
+ */
+describe("box size survives a seek while GSAP owns the size", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    Reflect.deleteProperty(window, "__timelines");
+  });
+
+  function cardSizedByGsap(): HTMLElement {
+    const el = document.createElement("div");
+    el.id = "card";
+    el.setAttribute(STUDIO_BOX_SIZE_ATTR, "true");
+    el.style.setProperty(STUDIO_WIDTH_PROP, "305px");
+    el.style.setProperty(STUDIO_HEIGHT_PROP, "202px");
+    document.body.append(el);
+    // A timeline that animates this element's width/height, as the committed
+    // resize leaves behind.
+    Object.assign(window, {
+      __timelines: {
+        main: {
+          getChildren: () => [{ targets: () => [el], vars: { width: 305, height: 202 } }],
+        },
+      },
+    });
+    return el;
+  }
+
+  it("re-applies the committed size after the timeline gave it back", () => {
+    const el = cardSizedByGsap();
+    // The revert: GSAP puts the tween's recorded starting size back.
+    el.style.width = "395px";
+    el.style.height = "261px";
+
+    reapplyPositionEditsAfterSeek(document);
+
+    expect(el.style.width).toBe("305px");
+    expect(el.style.height).toBe("202px");
+  });
+
+  it("leaves an element alone once its studio size is cleared", () => {
+    const el = cardSizedByGsap();
+    el.style.removeProperty(STUDIO_WIDTH_PROP);
+    el.style.removeProperty(STUDIO_HEIGHT_PROP);
+    el.style.width = "395px";
+
+    reapplyPositionEditsAfterSeek(document);
+
+    expect(el.style.width).toBe("395px");
+  });
+});

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

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import {
+  resolveSnapAdjustment,
+  snapEngagedForTravel,
+  SNAP_THRESHOLD_PX,
+  type SnapTarget,
+} from "./snapEngine";
+
+/**
+ * Picking a selection up used to move it. An element resting within the snap
+ * threshold of a guide is already snappable, so the snap computed on the first
+ * frame of a drag displaced it by up to the threshold while the pointer had not
+ * moved at all — captured live as `pointer "0,0"` against `applied "4,-3"`, with
+ * every member of the group jumping 12,-8 composition px before the drag had
+ * started. Snapping pulls toward a guide as you drag; it has nothing to say about
+ * a gesture that has not moved.
+ */
+describe("snapping waits for the drag to travel", () => {
+  // Moving box's right edge is at 150; the target's left edge is at 154, so the
+  // pair is 4px apart — inside the threshold, and snappable the moment it is asked.
+  const movingRect = { left: 100, top: 50, width: 50, height: 40 };
+  const target: SnapTarget = {
+    left: 154,
+    top: 50,
+    right: 254,
+    bottom: 90,
+    centerX: 204,
+    centerY: 70,
+    id: "neighbour",
+  };
+
+  const snapAt = (dx: number, dy: number) =>
+    resolveSnapAdjustment({
+      movingRect,
+      proposedDx: dx,
+      proposedDy: dy,
+      targets: [target],
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+      disabledForTravel: !snapEngagedForTravel(dx, dy),
+    });
+
+  it("does not move a selection that has not been dragged yet", () => {
+    expect(snapAt(0, 0)).toMatchObject({ dx: 0, dy: 0 });
+  });
+
+  it("leaves a sub-threshold twitch alone", () => {
+    expect(snapAt(1, -1)).toMatchObject({ dx: 1, dy: -1 });
+  });
+
+  it("still snaps once the drag is a real one", () => {
+    expect(snapEngagedForTravel(0, 0)).toBe(false);
+    expect(snapEngagedForTravel(10, 0)).toBe(true);
+    // Without the travel gate the same delta snaps, which is the behaviour to keep.
+    const engaged = resolveSnapAdjustment({
+      movingRect,
+      proposedDx: 0,
+      proposedDy: 0,
+      targets: [target],
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+    });
+    expect(engaged.dx).toBe(4);
+  });
+});

package/src/components/editor/snapEngine.ts

@@ -3,6 +3,24 @@
 // All position values are in overlay-space (screen) pixels.
 
 export const SNAP_THRESHOLD_PX = 6;
+/**
+ * Pointer travel a MOVE must reach before snapping is allowed to touch it.
+ *
+ * An element resting within the threshold of a guide is already "snappable", so
+ * a snap computed on the very first frame displaces it by up to the threshold
+ * while the pointer has moved nothing — pick a selection up and the whole thing
+ * teleports before you have dragged at all. Snapping is meant to pull toward a
+ * guide as the user drags, so it does not participate until the drag is real.
+ * The value matches the distance a drag must cover to count as a drag rather
+ * than a click, so nothing below it moves anything.
+ */
+const SNAP_ENGAGE_TRAVEL_PX = 4;
+
+/** Whether a move of this size has travelled far enough for snapping to apply. */
+export function snapEngagedForTravel(dx: number, dy: number): boolean {
+  return Math.hypot(dx, dy) >= SNAP_ENGAGE_TRAVEL_PX;
+}
+
 const EQUIDISTANCE_TOLERANCE_PX = 1;
 
 // ---------------------------------------------------------------------------
@@ -359,8 +377,10 @@ export function resolveSnapAdjustment(input: {
   gridEdges?: { x: SnapEdge[]; y: SnapEdge[] };
   threshold: number;
   disabled: boolean;
+  /** Set when the gesture has not travelled far enough for snapping yet. */
+  disabledForTravel?: boolean;
 }): SnapResult {
-  if (input.disabled || input.threshold <= 0) {
+  if (input.disabled || input.disabledForTravel || input.threshold <= 0) {
     return DISABLED_RESULT(input.proposedDx, input.proposedDy);
   }