@hyperframes/studio 0.7.55 → 0.7.57

package/src/components/editor/resizeDraft.ts

@@ -0,0 +1,108 @@
+import type { GestureState } from "./domEditOverlayGestures";
+import { resolveResizeCenterAnchorOffset } from "./domEditOverlayGestures";
+import type { OverlayRect } from "./domEditOverlayGeometry";
+import {
+  cornerEdgeLength,
+  elementCornerOverlayPoints,
+  overlayCornersCentroid,
+} from "./domEditOverlayGeometry";
+import { computeNextResizeAnchor } from "./domEditResizeLocal";
+import { applyManualOffsetDragDraft } from "./manualOffsetDrag";
+
+type Corners = ReturnType<typeof elementCornerOverlayPoints>;
+
+/**
+ * The residual center-pin offset for this frame. With measurable corners and a
+ * fixed-center start, accumulate `fixedStart - centerNow` onto the previous
+ * anchor so it CONVERGES rather than oscillating: `applyManualOffsetDragDraft`
+ * treats its argument as the absolute offset, and `centerNow` (measured on the
+ * live element) already carries the previous frame's offset, so the difference
+ * is only the residual correction. Using it absolutely would drop the offset
+ * every other frame and un-pin the center (fa4f39168). Memberless/unmeasurable
+ * geometry falls back to the AABB half-delta.
+ */
+function resolveResizeAnchor(
+  g: GestureState,
+  corners: Corners | null,
+  measureOrientedRect: () => OverlayRect | null,
+): { dx: number; dy: number } {
+  const fixedStart = g.resizeFixedCenterStart;
+  if (corners && fixedStart) {
+    return computeNextResizeAnchor(g.lastResizeAnchor, fixedStart, overlayCornersCentroid(corners));
+  }
+  const fallbackRect = measureOrientedRect();
+  return resolveResizeCenterAnchorOffset({
+    originWidth: g.originWidth,
+    originHeight: g.originHeight,
+    overlayWidth: fallbackRect ? fallbackRect.width : g.originWidth,
+    overlayHeight: fallbackRect ? fallbackRect.height : g.originHeight,
+  });
+}
+
+/**
+ * Center-pinned draft rect: translate the element through the manual-offset
+ * channel to keep its gesture-start center planted (rotation-safe for any
+ * transform-origin), then hug its true rendered bounds. Mutates
+ * `g.lastResizeAnchor` and applies the offset draft as a side effect.
+ */
+function resolveAnchoredResizeDraft(
+  g: GestureState,
+  member: NonNullable<GestureState["pathOffsetMember"]>,
+  element: HTMLElement,
+  overlayEl: HTMLDivElement | null,
+  iframe: HTMLIFrameElement | null,
+  measureOrientedRect: () => OverlayRect | null,
+): OverlayRect {
+  // Measure real corners ONCE — reused for the anchor and the fallback size.
+  const corners =
+    overlayEl && iframe ? elementCornerOverlayPoints(overlayEl, iframe, element) : null;
+  const anchor = resolveResizeAnchor(g, corners, measureOrientedRect);
+  g.lastResizeAnchor = anchor;
+  applyManualOffsetDragDraft(member, anchor.dx, anchor.dy);
+  // Re-measure AFTER the anchor translate so it hugs the element every frame.
+  return (
+    measureOrientedRect() ?? {
+      left: g.originLeft + anchor.dx,
+      top: g.originTop + anchor.dy,
+      width: corners ? cornerEdgeLength(corners.nw, corners.ne) : g.originWidth,
+      height: corners ? cornerEdgeLength(corners.nw, corners.sw) : g.originHeight,
+      editScaleX: g.editScaleX,
+      editScaleY: g.editScaleY,
+      angle: g.actualRotation,
+    }
+  );
+}
+
+/** The overlay rect to paint for the current resize pointer-move frame. */
+export function resolveResizeDraftRect(
+  g: GestureState,
+  element: HTMLElement,
+  overlayEl: HTMLDivElement | null,
+  iframe: HTMLIFrameElement | null,
+  measureOrientedRect: () => OverlayRect | null,
+): OverlayRect {
+  if (g.pathOffsetMember) {
+    return resolveAnchoredResizeDraft(
+      g,
+      g.pathOffsetMember,
+      element,
+      overlayEl,
+      iframe,
+      measureOrientedRect,
+    );
+  }
+  // Re-measure the element's oriented box AFTER the size write. The size draft
+  // rounds/clamps and (with a centered transform-origin + GSAP scale) the real
+  // rendered size diverges from the CSS size, so measure rather than trust math.
+  return (
+    measureOrientedRect() ?? {
+      left: g.originLeft,
+      top: g.originTop,
+      width: g.originWidth,
+      height: g.originHeight,
+      editScaleX: g.editScaleX,
+      editScaleY: g.editScaleY,
+      angle: g.actualRotation,
+    }
+  );
+}

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

@@ -5,8 +5,8 @@ import {
   buildCompositionSnapTarget,
   buildGridSnapEdges,
   resolveSnapAdjustment,
-  resolveResizeSnapAdjustment,
   resolveEquidistanceGuides,
+  resolveGuideLineRect,
   SNAP_THRESHOLD_PX,
   type SnapTarget,
 } from "./snapEngine";
@@ -385,88 +385,22 @@ describe("resolveSnapAdjustment", () => {
 });
 
 // ---------------------------------------------------------------------------
-// resolveResizeSnapAdjustment
+// resolveGuideLineRect
 // ---------------------------------------------------------------------------
 
-describe("resolveResizeSnapAdjustment", () => {
-  test("only right edge snaps on X", () => {
-    // Moving rect at (100, 100) size 50x50, right=150.
-    // Target left at 200. Propose dx=47 => proposed right=197. Dist to 200=3.
-    const t = target("a", 200, 100, 100, 100);
-    const result = resolveResizeSnapAdjustment({
-      movingRect: rect(100, 100, 50, 50),
-      proposedDx: 47,
-      proposedDy: 0,
-      targets: [t],
-      threshold: SNAP_THRESHOLD_PX,
-      disabled: false,
-    });
-    expect(result.dx).toBe(50); // right edge snaps to 200
-  });
+describe("resolveGuideLineRect", () => {
+  const composition = rect(120, 80, 640, 360); // letterboxed inside the overlay
 
-  test("only bottom edge snaps on Y", () => {
-    // Moving rect at (100, 100) size 50x50, bottom=150.
-    // Target top at 200. Propose dy=47 => proposed bottom=197. Dist to 200=3.
-    const t = target("a", 100, 200, 100, 100);
-    const result = resolveResizeSnapAdjustment({
-      movingRect: rect(100, 100, 50, 50),
-      proposedDx: 0,
-      proposedDy: 47,
-      targets: [t],
-      threshold: SNAP_THRESHOLD_PX,
-      disabled: false,
-    });
-    expect(result.dy).toBe(50); // bottom edge snaps to 200
-  });
-
-  test("left edge does NOT snap during resize", () => {
-    // Target right at 150. Moving rect left=100. If drag were active,
-    // left would snap. But during resize, only right edge snaps.
-    // Moving rect at (100, 100) size 200x200, right=300.
-    // Target right=150. Proposed dx=-153 => proposed right=147. Dist to 150=3.
-    // This SHOULD snap right to 150 (dx = -150). But left stays at 100.
-    const t = target("a", 50, 100, 100, 100); // right=150
-    const result = resolveResizeSnapAdjustment({
-      movingRect: rect(100, 100, 200, 200),
-      proposedDx: -153,
-      proposedDy: 0,
-      targets: [t],
-      threshold: SNAP_THRESHOLD_PX,
-      disabled: false,
-    });
-    // Right edge: 300 + (-153) = 147 => snaps to 150, adjustment = +3, dx = -150
-    expect(result.dx).toBe(-150);
-  });
-
-  test("disabled=true returns passthrough for resize", () => {
-    const t = target("a", 200, 200, 100, 100);
-    const result = resolveResizeSnapAdjustment({
-      movingRect: rect(100, 100, 50, 50),
-      proposedDx: 47,
-      proposedDy: 47,
-      targets: [t],
-      threshold: SNAP_THRESHOLD_PX,
-      disabled: true,
-    });
-    expect(result.dx).toBe(47);
-    expect(result.dy).toBe(47);
-    expect(result.guides).toHaveLength(0);
+  test("vertical guide (axis x) spans the composition's height at the snap x", () => {
+    expect(resolveGuideLineRect({ axis: "x", position: 440, from: 0, to: 0 }, composition)).toEqual(
+      { left: 440, top: 80, width: 1, height: 360 },
+    );
   });
 
-  test("resize produces guide lines", () => {
-    const t = target("a", 200, 100, 100, 100);
-    const result = resolveResizeSnapAdjustment({
-      movingRect: rect(100, 100, 50, 50),
-      proposedDx: 47,
-      proposedDy: 0,
-      targets: [t],
-      threshold: SNAP_THRESHOLD_PX,
-      disabled: false,
-    });
-    expect(result.guides.length).toBeGreaterThanOrEqual(1);
-    const xGuide = result.guides.find((g) => g.axis === "x");
-    expect(xGuide).toBeDefined();
-    expect(xGuide!.position).toBe(200);
+  test("horizontal guide (axis y) spans the composition's width at the snap y", () => {
+    expect(resolveGuideLineRect({ axis: "y", position: 260, from: 0, to: 0 }, composition)).toEqual(
+      { left: 120, top: 260, width: 640, height: 1 },
+    );
   });
 });
 

package/src/components/editor/snapEngine.ts

@@ -410,62 +410,22 @@ export function resolveSnapAdjustment(input: {
 }
 
 // ---------------------------------------------------------------------------
-// resolveResizeSnapAdjustment — resize variant (only right/bottom snap)
+// resolveGuideLineRect — screen rect for rendering a snap guide line
 // ---------------------------------------------------------------------------
 
-// fallow-ignore-next-line complexity
-export function resolveResizeSnapAdjustment(input: {
-  movingRect: Rect;
-  proposedDx: number;
-  proposedDy: number;
-  targets: SnapTarget[];
-  gridEdges?: { x: SnapEdge[]; y: SnapEdge[] };
-  threshold: number;
-  disabled: boolean;
-}): SnapResult {
-  if (input.disabled || input.threshold <= 0) {
-    return DISABLED_RESULT(input.proposedDx, input.proposedDy);
+/**
+ * Full-length guide line spanning the composition: a vertical line (axis "x")
+ * runs the composition's height at the snapped x position; a horizontal line
+ * (axis "y") runs the composition's width. `composition` is the composition
+ * rect in overlay space — guide positions are already overlay-space, so the
+ * line must be offset by the composition's left/top (the canvas is usually
+ * letterboxed inside the overlay).
+ */
+export function resolveGuideLineRect(guide: SnapGuide, composition: Rect): Rect {
+  if (guide.axis === "x") {
+    return { left: guide.position, top: composition.top, width: 1, height: composition.height };
   }
-
-  const mr = input.movingRect;
-  const proposedRight = rectRight(mr) + input.proposedDx;
-  const proposedBottom = rectBottom(mr) + input.proposedDy;
-
-  const xCandidates = collectCandidates(
-    [proposedRight],
-    input.targets,
-    (t) => [t.left, t.centerX, t.right],
-    input.gridEdges?.x,
-    input.threshold,
-  );
-  const yCandidates = collectCandidates(
-    [proposedBottom],
-    input.targets,
-    (t) => [t.top, t.centerY, t.bottom],
-    input.gridEdges?.y,
-    input.threshold,
-  );
-
-  const bestX = pickBest(xCandidates);
-  const bestY = pickBest(yCandidates);
-  const adjustedDx = input.proposedDx + (bestX?.adjustment ?? 0);
-  const adjustedDy = input.proposedDy + (bestY?.adjustment ?? 0);
-
-  const adjustedRect: Rect = {
-    left: mr.left,
-    top: mr.top,
-    width: mr.width + adjustedDx,
-    height: mr.height + adjustedDy,
-  };
-
-  const targetMap = new Map(input.targets.map((t) => [t.id, t]));
-
-  return {
-    dx: adjustedDx,
-    dy: adjustedDy,
-    guides: buildGuidesFromMatches(bestX, bestY, adjustedRect, targetMap),
-    spacingGuides: [], // computed separately via resolveEquidistanceGuides
-  };
+  return { left: composition.left, top: guide.position, width: composition.width, height: 1 };
 }
 
 // ---------------------------------------------------------------------------

package/src/components/editor/useCanvasContextMenuState.ts

@@ -0,0 +1,92 @@
+/**
+ * Canvas right-click context-menu state for DomEditOverlay: where the menu is
+ * open (viewport x/y) and which selection it targets, plus the right-click
+ * handler that resolves/selects the element under the pointer before opening.
+ */
+import { useCallback, useEffect, useState, type RefObject } from "react";
+import type { DomEditSelection } from "./domEditing";
+
+export interface CanvasContextMenuState {
+  x: number;
+  y: number;
+  sel: DomEditSelection;
+}
+
+interface UseCanvasContextMenuStateParams {
+  selection: DomEditSelection | null;
+  selectionRef: RefObject<DomEditSelection | null>;
+  hoverSelectionRef: RefObject<DomEditSelection | null>;
+  onCanvasPointerMoveRef: RefObject<
+    (
+      event: React.PointerEvent<HTMLDivElement>,
+      options?: { preferClipAncestor?: boolean },
+    ) => Promise<DomEditSelection | null>
+  >;
+  onSelectionChangeRef: RefObject<
+    (selection: DomEditSelection, options?: { revealPanel?: boolean; additive?: boolean }) => void
+  >;
+}
+
+export function useCanvasContextMenuState({
+  selection,
+  selectionRef,
+  hoverSelectionRef,
+  onCanvasPointerMoveRef,
+  onSelectionChangeRef,
+}: UseCanvasContextMenuStateParams): {
+  contextMenu: CanvasContextMenuState | null;
+  closeContextMenu: () => void;
+  handleContextMenu: (event: React.MouseEvent<HTMLDivElement>) => Promise<void>;
+} {
+  // Context menu state: position of the right-click that opened it.
+  // contextMenu.sel is the element the menu targets — captured at right-click
+  // time so the menu can open even before the React selection state settles.
+  const [contextMenu, setContextMenu] = useState<CanvasContextMenuState | null>(null);
+  const closeContextMenu = useCallback(() => setContextMenu(null), []);
+
+  // Close the context menu whenever the selection moves off the element the menu
+  // targets (a click that reselects elsewhere, a deselect, or a preview reload
+  // that rebuilds the selection). Without this the menu can linger — orphaned —
+  // over a stale target after the underlying element is gone. A right-click that
+  // OPENS the menu also selects its target, so the common open path keeps the
+  // menu (same element) rather than immediately dismissing it.
+  useEffect(() => {
+    if (!contextMenu) return;
+    if (!selection || selection.element !== contextMenu.sel.element) {
+      setContextMenu(null);
+    }
+  }, [selection, contextMenu]);
+
+  // Right-click: select element first (if not already selected), then open menu.
+  const handleContextMenu = useCallback(
+    async (event: React.MouseEvent<HTMLDivElement>) => {
+      event.preventDefault();
+
+      // If no element is selected yet, resolve it from the pointer position first.
+      const currentSel = selectionRef.current;
+      let activeSel: DomEditSelection | null = currentSel;
+      if (!currentSel) {
+        const pointerEvent = event as unknown as React.PointerEvent<HTMLDivElement>;
+        const resolved = await onCanvasPointerMoveRef.current(pointerEvent);
+        if (!resolved) return; // Nothing under the cursor — skip menu.
+        onSelectionChangeRef.current(resolved, { revealPanel: true });
+        // Use `resolved` directly: React state (and therefore selectionRef) won't
+        // update synchronously after onSelectionChange — we'd be reading stale null.
+        activeSel = resolved;
+      } else {
+        // Check if the user right-clicked on an unselected element (hover target).
+        const hover = hoverSelectionRef.current;
+        if (hover && hover.element !== currentSel.element) {
+          onSelectionChangeRef.current(hover, { revealPanel: true });
+          activeSel = hover;
+        }
+      }
+
+      if (!activeSel) return;
+      setContextMenu({ x: event.clientX, y: event.clientY, sel: activeSel });
+    },
+    [selectionRef, hoverSelectionRef, onCanvasPointerMoveRef, onSelectionChangeRef],
+  );
+
+  return { contextMenu, closeContextMenu, handleContextMenu };
+}

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

@@ -0,0 +1,228 @@
+// @vitest-environment happy-dom
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { installReactActEnvironment, makeSelection } from "../../hooks/domSelectionTestHarness";
+import { useDomEditNudge, type UseDomEditNudgeParams } from "./useDomEditNudge";
+import { CANVAS_NUDGE_COMMIT_DEBOUNCE_MS, CANVAS_NUDGE_STEP_PX } from "./domEditNudge";
+import { __resetForTests } from "../../utils/canvasNudgeGate";
+import type { DomEditSelection } from "./domEditing";
+import type { OverlayRect } from "./domEditOverlayGeometry";
+
+installReactActEnvironment();
+
+function makeRef<T>(current: T): { current: T } {
+  return { current };
+}
+
+const REST_RECT: OverlayRect = {
+  left: 0,
+  top: 0,
+  width: 100,
+  height: 50,
+  editScaleX: 1,
+  editScaleY: 1,
+};
+
+// Stable across renders on purpose: the test targets the `selection` identity
+// key specifically, so `groupSelections` must not itself be a source of churn.
+const EMPTY_GROUP_SELECTIONS: DomEditSelection[] = [];
+
+function Harness({
+  selection,
+  onPathOffsetCommit,
+}: {
+  selection: DomEditSelection | null;
+  onPathOffsetCommit: UseDomEditNudgeParams["onPathOffsetCommitRef"]["current"];
+}) {
+  useDomEditNudge({
+    selection,
+    groupSelections: EMPTY_GROUP_SELECTIONS,
+    allowCanvasMovement: true,
+    selectionRef: makeRef(selection),
+    overlayRectRef: makeRef(REST_RECT),
+    groupOverlayItemsRef: makeRef([]),
+    gestureRef: makeRef(null),
+    groupGestureRef: makeRef(null),
+    blockedMoveRef: makeRef(null),
+    onManualDragStartRef: makeRef(() => {}),
+    onPathOffsetCommitRef: makeRef(onPathOffsetCommit),
+    onGroupPathOffsetCommitRef: makeRef(async () => {}),
+  });
+  return null;
+}
+
+function dispatchArrowRight(): void {
+  window.dispatchEvent(
+    new KeyboardEvent("keydown", { key: "ArrowRight", bubbles: true, cancelable: true }),
+  );
+}
+
+describe("useDomEditNudge — selection cleanup keyed on stable identity", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    __resetForTests();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("keeps a nudge burst alive when the parent hands down a new selection object for the same element", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+
+    const element = document.createElement("div");
+    element.id = "dot-a";
+    document.body.append(element);
+
+    const commit = vi.fn();
+    const firstSelection = makeSelection("Dot", element);
+
+    act(() => {
+      root.render(
+        React.createElement(Harness, { selection: firstSelection, onPathOffsetCommit: commit }),
+      );
+    });
+
+    act(() => {
+      dispatchArrowRight();
+    });
+    expect(commit).not.toHaveBeenCalled();
+
+    // Re-render with a BRAND NEW selection object describing the SAME element
+    // (same id) — exactly what an un-memoized parent does on every render.
+    // Before the fix, the cleanup effect was keyed on this object's identity
+    // and would flush the burst right here, one arrow-press early.
+    const secondSelection = makeSelection("Dot", element);
+    act(() => {
+      root.render(
+        React.createElement(Harness, { selection: secondSelection, onPathOffsetCommit: commit }),
+      );
+    });
+    expect(commit).not.toHaveBeenCalled();
+
+    act(() => {
+      dispatchArrowRight();
+    });
+    expect(commit).not.toHaveBeenCalled();
+
+    act(() => {
+      vi.advanceTimersByTime(CANVAS_NUDGE_COMMIT_DEBOUNCE_MS + 10);
+    });
+
+    // One combined commit for both presses, not two separate (premature) ones.
+    expect(commit).toHaveBeenCalledTimes(1);
+    const [, next] = commit.mock.calls[0] as [DomEditSelection, { x: number; y: number }];
+    expect(next.x).toBeCloseTo(2 * CANVAS_NUDGE_STEP_PX);
+    expect(next.y).toBeCloseTo(0);
+
+    act(() => root.unmount());
+    host.remove();
+    element.remove();
+  });
+
+  it("still flushes the burst when the selection actually changes to a different element", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+
+    const elementA = document.createElement("div");
+    elementA.id = "dot-a";
+    document.body.append(elementA);
+    const elementB = document.createElement("div");
+    elementB.id = "dot-b";
+    document.body.append(elementB);
+
+    const commit = vi.fn();
+    const selectionA = makeSelection("Dot A", elementA);
+    const selectionB = makeSelection("Dot B", elementB);
+
+    act(() => {
+      root.render(
+        React.createElement(Harness, { selection: selectionA, onPathOffsetCommit: commit }),
+      );
+    });
+
+    act(() => {
+      dispatchArrowRight();
+    });
+    expect(commit).not.toHaveBeenCalled();
+
+    // A genuine selection change (different id) must still flush immediately —
+    // only same-identity re-renders should be ignored.
+    act(() => {
+      root.render(
+        React.createElement(Harness, { selection: selectionB, onPathOffsetCommit: commit }),
+      );
+    });
+    expect(commit).toHaveBeenCalledTimes(1);
+    const [committedSelection, next] = commit.mock.calls[0] as [
+      DomEditSelection,
+      { x: number; y: number },
+    ];
+    expect(committedSelection.element).toBe(elementA);
+    expect(next.x).toBeCloseTo(CANVAS_NUDGE_STEP_PX);
+
+    act(() => root.unmount());
+    host.remove();
+    elementA.remove();
+    elementB.remove();
+  });
+
+  it("flushes the burst when switching between two id-less siblings that share a selector", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+
+    // Two id-less siblings with the SAME selector — distinguished only by
+    // selectorIndex. Under the old `id ?? selector ?? label` key they shared
+    // one identity, so selecting B mid-burst didn't flush A and the next arrow
+    // kept moving A. The key now folds in selectorIndex, so they're distinct.
+    const elementA = document.createElement("div");
+    document.body.append(elementA);
+    const elementB = document.createElement("div");
+    document.body.append(elementB);
+
+    const commit = vi.fn();
+    const base = (label: string, element: HTMLElement) => ({
+      ...makeSelection(label, element),
+      id: undefined,
+      selector: "div.row",
+    });
+    const selectionA: DomEditSelection = { ...base("Row", elementA), selectorIndex: 0 };
+    const selectionB: DomEditSelection = { ...base("Row", elementB), selectorIndex: 1 };
+
+    act(() => {
+      root.render(
+        React.createElement(Harness, { selection: selectionA, onPathOffsetCommit: commit }),
+      );
+    });
+
+    act(() => {
+      dispatchArrowRight();
+    });
+    expect(commit).not.toHaveBeenCalled();
+
+    act(() => {
+      root.render(
+        React.createElement(Harness, { selection: selectionB, onPathOffsetCommit: commit }),
+      );
+    });
+
+    // The sibling switch must flush A's pending burst exactly once, for A.
+    expect(commit).toHaveBeenCalledTimes(1);
+    const [committedSelection, next] = commit.mock.calls[0] as [
+      DomEditSelection,
+      { x: number; y: number },
+    ];
+    expect(committedSelection.element).toBe(elementA);
+    expect(next.x).toBeCloseTo(CANVAS_NUDGE_STEP_PX);
+
+    act(() => root.unmount());
+    host.remove();
+    elementA.remove();
+    elementB.remove();
+  });
+});