@hyperframes/studio 0.7.55 → 0.7.57

package/src/components/editor/DomEditOverlay.tsx

@@ -1,10 +1,11 @@
 import { memo, useEffect, useMemo, useRef, useState, type RefObject } from "react";
-import { getPreviewTargetFromPointer } from "../../utils/studioPreviewHelpers";
 import { type DomEditSelection } from "./domEditing";
 import type { PreviewMouseDownOptions } from "../../hooks/usePreviewInteraction";
 import { useMarqueeGestures } from "./marqueeCommit";
 import { MarqueeOverlay } from "./MarqueeOverlay";
 import { resolveDomEditGroupOverlayRect } from "./domEditOverlayGeometry";
+import { useZOrderCrossedFlash, ZOrderCrossedFlash } from "./useZOrderCrossedFlash";
+import { useCanvasContextMenuState } from "./useCanvasContextMenuState";
 import {
   type BlockedMoveState,
   type DomEditGroupPathOffsetCommit,
@@ -16,17 +17,20 @@ import {
 import { useDomEditOverlayRects } from "./useDomEditOverlayRects";
 import { OffCanvasIndicators, type OffCanvasRect } from "./OffCanvasIndicators";
 import { createDomEditOverlayGestureHandlers } from "./useDomEditOverlayGestures";
+import { useDomEditNudge } from "./useDomEditNudge";
 import { SnapGuideOverlay, type SnapGuidesState } from "./SnapGuideOverlay";
 import { GridOverlay } from "./GridOverlay";
 import type { GestureRecordingState } from "./GestureRecordControl";
-import { DomEditCropHandles } from "./DomEditCropHandles";
-import { DomEditRotateHandle } from "./DomEditRotateHandle";
+import { DomEditGroupChrome, DomEditSelectionChrome } from "./DomEditSelectionChrome";
 import { hugRectForElement } from "./domEditOverlayCrop";
 import { useCropOverlay } from "../../hooks/useCropOverlay";
 import { readDomEditSelectionShapeStyles, resolveBoxChromeClass } from "./domEditOverlayShape";
 import { useDomEditCompositionRect } from "./useDomEditCompositionRect";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { startOffCanvasIndicatorRefresh } from "./offCanvasIndicatorRefresh";
+import { CanvasContextMenu } from "./CanvasContextMenu";
+import type { ZOrderAction, ZOrderPatch } from "./canvasContextMenuZOrder";
+import { getPreviewTargetFromPointer } from "../../utils/studioPreviewHelpers";
 
 // Re-exports for external consumers — preserving existing import paths.
 export {
@@ -37,7 +41,6 @@ export {
 export {
   focusDomEditOverlayElement,
   hasDomEditRotationChanged,
-  resolveDomEditResizeGesture,
   resolveDomEditRotationGesture,
 } from "./domEditOverlayGestures";
 export type { DomEditGroupPathOffsetCommit } from "./domEditOverlayGestures";
@@ -73,6 +76,8 @@ interface DomEditOverlayProps {
   onBoxSizeCommit: (
     selection: DomEditSelection,
     next: { width: number; height: number },
+    offset?: { x: number; y: number },
+    restore?: () => void,
   ) => Promise<void> | void;
   onRotationCommit: (selection: DomEditSelection, next: { angle: number }) => Promise<void> | void;
   onStyleCommit?: (property: string, value: string) => Promise<void> | void;
@@ -81,6 +86,24 @@ interface DomEditOverlayProps {
   recordingState?: GestureRecordingState;
   onToggleRecording?: () => void;
   onMarqueeSelect?: (selections: DomEditSelection[], additive: boolean) => void;
+  /**
+   * Delete the selected canvas element.
+   * Wire to handleDomEditElementDelete from useDomEditActionsContext —
+   * same handler the Delete/Backspace hotkey uses.
+   */
+  onDeleteSelection?: (selection: DomEditSelection) => void;
+  /**
+   * Called with the resolved z-order patch list and the menu action that
+   * produced it (feeds the undo coalesce key). The patch list is tie-aware and
+   * may include sibling elements (see canvasContextMenuZOrder); the live DOM is
+   * NOT yet mutated. Wire to handleDomZIndexReorderCommit from
+   * useDomEditActionsContext. See CanvasContextMenu.tsx module comment.
+   */
+  onApplyZIndex?: (
+    selection: DomEditSelection,
+    patches: ZOrderPatch[],
+    action: ZOrderAction,
+  ) => void;
 }
 
 // fallow-ignore-next-line complexity
@@ -105,6 +128,8 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   onRotationCommit,
   onStyleCommit,
   onMarqueeSelect,
+  onDeleteSelection,
+  onApplyZIndex,
 }: DomEditOverlayProps) {
   const overlayRef = useRef<HTMLDivElement | null>(null);
   const boxRef = useRef<HTMLDivElement | null>(null);
@@ -123,6 +148,11 @@ export const DomEditOverlay = memo(function DomEditOverlay({
 
   const selectionRef = useRef(selection);
   selectionRef.current = selection;
+
+  // Brief highlight on the sibling a forward/backward z step crossed — drawn
+  // in this studio overlay, never in the iframe DOM (see useZOrderCrossedFlash).
+  const { zOrderFlashRect, handleZOrderCrossed } = useZOrderCrossedFlash({ overlayRef, iframeRef });
+
   const activeCompositionPathRef = useRef(activeCompositionPath);
   activeCompositionPathRef.current = activeCompositionPath;
   const groupSelectionsRef = useRef(groupSelections);
@@ -241,6 +271,23 @@ export const DomEditOverlay = memo(function DomEditOverlay({
     snapGuidesRef,
   });
 
+  // Arrow-key nudge (1px, Shift = 10px) — commits through the same
+  // path-offset callbacks as a drag, one undo entry per key burst.
+  const { flushNudge } = useDomEditNudge({
+    selection,
+    groupSelections,
+    allowCanvasMovement,
+    selectionRef,
+    overlayRectRef,
+    groupOverlayItemsRef,
+    gestureRef,
+    groupGestureRef,
+    blockedMoveRef,
+    onManualDragStartRef,
+    onPathOffsetCommitRef,
+    onGroupPathOffsetCommitRef,
+  });
+
   const marquee = useMarqueeGestures({
     iframeRef,
     overlayRef,
@@ -370,6 +417,16 @@ export const DomEditOverlay = memo(function DomEditOverlay({
     e.stopPropagation();
   };
 
+  // Right-click state + handler: select the element under the pointer (if
+  // needed), then open the menu; closes when the selection moves off-target.
+  const { contextMenu, closeContextMenu, handleContextMenu } = useCanvasContextMenuState({
+    selection,
+    selectionRef,
+    hoverSelectionRef,
+    onCanvasPointerMoveRef,
+    onSelectionChangeRef,
+  });
+
   return (
     <div
       ref={overlayRef}
@@ -378,142 +435,59 @@ export const DomEditOverlay = memo(function DomEditOverlay({
       aria-label="Composition canvas"
       // Cursor follows marquee rect *state* (re-renders), not the mutable ref.
       style={marquee.marqueeRect ? { cursor: "crosshair" } : undefined}
-      onPointerDownCapture={(event) =>
-        focusDomEditOverlayElement(event.currentTarget as FocusableDomEditOverlay)
-      }
+      onPointerDownCapture={(event) => {
+        // A pointer gesture supersedes a pending nudge burst — commit it first
+        // so the gesture's member snapshot starts from the nudged position.
+        flushNudge();
+        focusDomEditOverlayElement(event.currentTarget as FocusableDomEditOverlay);
+      }}
       onPointerDown={handleOverlayPointerDown}
       onMouseDown={handleOverlayMouseDown}
       onPointerMove={marquee.onPointerMove}
       onPointerLeave={() => onCanvasPointerLeaveRef.current()}
       onPointerUp={marquee.onPointerUp}
       onPointerCancel={marquee.onPointerCancel}
+      onContextMenu={handleContextMenu}
     >
       {hoverSelection && hoverRect && compRect.width > 0 && (
         <div
           aria-hidden="true"
           data-dom-edit-hover-box="true"
           className="pointer-events-none absolute rounded-md border border-studio-accent/80 shadow-[0_0_0_1px_rgba(60,230,172,0.25)]"
-          style={hugRectForElement(hoverRect, hoverSelection.element)}
+          style={{
+            ...hugRectForElement(hoverRect, hoverSelection.element),
+            transform: hoverRect.angle ? `rotate(${hoverRect.angle}deg)` : undefined,
+          }}
         />
       )}
       {hasGroupSelection && groupOverlayItems.length > 1 && groupBounds && compRect.width > 0 && (
-        <>
-          {groupOverlayItems.map((item) => (
-            <div
-              key={item.key}
-              aria-hidden="true"
-              className="pointer-events-none absolute rounded-xl border border-studio-accent/70"
-              style={{
-                left: item.rect.left,
-                top: item.rect.top,
-                width: item.rect.width,
-                height: item.rect.height,
-              }}
-            />
-          ))}
-          <div
-            data-dom-edit-selection-box="true"
-            className="pointer-events-auto absolute rounded-xl border border-studio-accent shadow-[0_0_0_1px_rgba(60,230,172,0.3)]"
-            style={{
-              left: groupBounds.left,
-              top: groupBounds.top,
-              width: groupBounds.width,
-              height: groupBounds.height,
-              cursor: allowCanvasMovement && groupCanMove ? "move" : "default",
-            }}
-            onPointerDown={(e) => {
-              if (!allowCanvasMovement || !groupCanMove || e.shiftKey) return;
-              gestures.startGroupDrag(e);
-            }}
-            onMouseDown={suppressBoxMouseDown}
-            onClick={handleBoxClick}
-          />
-        </>
+        <DomEditGroupChrome
+          groupOverlayItems={groupOverlayItems}
+          groupBounds={groupBounds}
+          allowCanvasMovement={allowCanvasMovement}
+          groupCanMove={groupCanMove}
+          gestures={gestures}
+          onBoxMouseDown={suppressBoxMouseDown}
+          onBoxClick={handleBoxClick}
+        />
       )}
       {!hasGroupSelection && selection && overlayRect && compRect.width > 0 && (
-        <>
-          {allowCanvasMovement && selection.capabilities.canApplyManualRotation && (
-            <DomEditRotateHandle
-              overlayRect={overlayRect}
-              cropOutlineInsetPx={cropOutlineInsetPx}
-              onStartRotate={(e) => {
-                e.stopPropagation();
-                gestures.startGesture("rotate", e);
-              }}
-            />
-          )}
-          <div
-            key={selectionKey}
-            ref={boxRef}
-            data-dom-edit-selection-box="true"
-            className={`pointer-events-auto absolute rounded-md ${boxChromeClass}`}
-            style={{
-              left: overlayRect.left,
-              top: overlayRect.top,
-              width: overlayRect.width,
-              height: overlayRect.height,
-              clipPath: boxClipPath,
-              cursor:
-                allowCanvasMovement && selection.capabilities.canApplyManualOffset
-                  ? "move"
-                  : "default",
-            }}
-            onPointerDown={(e) => {
-              if (!allowCanvasMovement || e.shiftKey) return;
-              if (selection.capabilities.canApplyManualOffset) {
-                gestures.startGesture("drag", e);
-                return;
-              }
-              e.preventDefault();
-              e.stopPropagation();
-              e.currentTarget.setPointerCapture(e.pointerId);
-              blockedMoveRef.current = {
-                pointerId: e.pointerId,
-                startX: e.clientX,
-                startY: e.clientY,
-                notified: false,
-              };
-            }}
-            onMouseDown={suppressBoxMouseDown}
-            onClick={handleBoxClick}
-          >
-            {cropOutlineInsetPx && (
-              <div
-                className="pointer-events-none absolute rounded-md border border-studio-accent/80 shadow-[0_0_0_1px_rgba(60,230,172,0.25)]"
-                style={{
-                  left: cropOutlineInsetPx.left,
-                  top: cropOutlineInsetPx.top,
-                  right: cropOutlineInsetPx.right,
-                  bottom: cropOutlineInsetPx.bottom,
-                }}
-              />
-            )}
-            {allowCanvasMovement && selection.capabilities.canApplyManualSize && (
-              <div
-                className="absolute -right-1.5 -bottom-1.5 w-3 h-3 rounded-sm bg-studio-accent border border-studio-accent/60"
-                style={{
-                  cursor: "se-resize",
-                  touchAction: "none",
-                  ...(cropOutlineInsetPx && {
-                    right: cropOutlineInsetPx.right - 6,
-                    bottom: cropOutlineInsetPx.bottom - 6,
-                  }),
-                }}
-                onPointerDown={(e) => {
-                  e.stopPropagation();
-                  gestures.startGesture("resize", e);
-                }}
-              />
-            )}
-          </div>
-          {selection.capabilities.canCrop && groupSelections.length <= 1 && (
-            <DomEditCropHandles
-              selection={selection}
-              overlayRect={overlayRect}
-              onStyleCommit={onStyleCommitRef.current}
-            />
-          )}
-        </>
+        <DomEditSelectionChrome
+          selection={selection}
+          overlayRect={overlayRect}
+          allowCanvasMovement={allowCanvasMovement}
+          cropOutlineInsetPx={cropOutlineInsetPx ?? undefined}
+          boxRef={boxRef}
+          boxChromeClass={boxChromeClass}
+          boxClipPath={boxClipPath}
+          selectionKey={selectionKey}
+          groupSelectionCount={groupSelections.length}
+          blockedMoveRef={blockedMoveRef}
+          gestures={gestures}
+          onStyleCommit={onStyleCommitRef.current}
+          onBoxMouseDown={suppressBoxMouseDown}
+          onBoxClick={handleBoxClick}
+        />
       )}
       {childRects.length > 0 &&
         compRect.width > 0 &&
@@ -539,6 +513,31 @@ export const DomEditOverlay = memo(function DomEditOverlay({
         onSelectionChangeRef={onSelectionChangeRef}
       />
       <MarqueeOverlay candidateRects={marquee.candidateRects} marqueeRect={marquee.marqueeRect} />
+      {contextMenu && (
+        <CanvasContextMenu
+          x={contextMenu.x}
+          y={contextMenu.y}
+          selection={contextMenu.sel}
+          onClose={closeContextMenu}
+          onDelete={
+            onDeleteSelection
+              ? (sel) => {
+                  closeContextMenu();
+                  onDeleteSelection(sel);
+                }
+              : undefined
+          }
+          onApplyZIndex={
+            onApplyZIndex
+              ? (patches, action) => {
+                  onApplyZIndex(contextMenu.sel, patches, action);
+                }
+              : undefined
+          }
+          onZOrderCrossed={handleZOrderCrossed}
+        />
+      )}
+      <ZOrderCrossedFlash rect={zOrderFlashRect} />
       <GridOverlay
         visible={gridVisible}
         spacing={gridSpacing}
@@ -551,8 +550,10 @@ export const DomEditOverlay = memo(function DomEditOverlay({
       />
       <SnapGuideOverlay
         snapGuidesRef={snapGuidesRef}
-        overlayWidth={compRect.width}
-        overlayHeight={compRect.height}
+        compositionLeft={compRect.left}
+        compositionTop={compRect.top}
+        compositionWidth={compRect.width}
+        compositionHeight={compRect.height}
       />
     </div>
   );

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

@@ -0,0 +1,90 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { expect, it, vi } from "vitest";
+import type { DomEditSelection } from "./domEditing";
+import { DomEditOverlay } from "./DomEditOverlay";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const hoverState = vi.hoisted(() => ({ angle: 0 }));
+
+vi.mock("./useDomEditOverlayRects", () => ({
+  useDomEditOverlayRects: ({ hoverSelectionRef }: { hoverSelectionRef: { current: unknown } }) => ({
+    overlayRect: null,
+    overlayRectRef: { current: null },
+    setOverlayRect: () => undefined,
+    hoverRect: hoverSelectionRef.current
+      ? {
+          left: 20,
+          top: 30,
+          width: 100,
+          height: 40,
+          editScaleX: 1,
+          editScaleY: 1,
+          angle: hoverState.angle,
+        }
+      : null,
+    groupOverlayItems: [],
+    groupOverlayItemsRef: { current: [] },
+    setGroupOverlayItems: () => undefined,
+    childRects: [],
+  }),
+}));
+
+vi.mock("./useDomEditCompositionRect", () => ({
+  useDomEditCompositionRect: () => ({
+    left: 0,
+    top: 0,
+    width: 800,
+    height: 450,
+    scaleX: 1,
+    scaleY: 1,
+  }),
+}));
+
+vi.mock("./offCanvasIndicatorRefresh", () => ({
+  startOffCanvasIndicatorRefresh: () => () => undefined,
+}));
+
+function renderHover(angle: number): string {
+  hoverState.angle = angle;
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  const element = document.createElement("div");
+  const hoverSelection = { element } as unknown as DomEditSelection;
+  act(() => {
+    root.render(
+      <DomEditOverlay
+        iframeRef={{ current: document.createElement("iframe") }}
+        activeCompositionPath={null}
+        selection={null}
+        hoverSelection={hoverSelection}
+        onCanvasMouseDown={() => undefined}
+        onCanvasPointerMove={() => Promise.resolve(null)}
+        onCanvasPointerLeave={() => undefined}
+        onSelectionChange={() => undefined}
+        onBlockedMove={() => undefined}
+        onPathOffsetCommit={() => undefined}
+        onGroupPathOffsetCommit={() => undefined}
+        onBoxSizeCommit={() => undefined}
+        onRotationCommit={() => undefined}
+      />,
+    );
+  });
+  const box = host.querySelector<HTMLElement>('[data-dom-edit-hover-box="true"]');
+  const transform = box?.style.transform ?? "";
+  act(() => root.unmount());
+  host.remove();
+  return transform;
+}
+
+it("rotates the hover box with the element", () => {
+  expect(renderHover(30)).toBe("rotate(30deg)");
+});
+
+it("leaves the hover box untransformed at angle zero", () => {
+  expect(renderHover(0)).toBe("");
+});

package/src/components/editor/DomEditRotateHandle.tsx

@@ -1,8 +1,12 @@
 import type { PointerEvent as ReactPointerEvent } from "react";
 import type { OverlayRect } from "./domEditOverlayGeometry";
 
-/** Rotate grab-handle above the selection. Anchors to the crop outline when
- *  the element is cropped so it stays next to what's visible on screen. */
+/** Rotate handle below the selection: an attached circular-arrows icon chip
+ *  (no connecting stem). Anchors to the crop outline when the element is
+ *  cropped so it stays next to what's visible on screen. Presentation only —
+ *  the rotation gesture measures pointer angles from the element CENTER
+ *  (resolveDomEditRotationGesture), so the handle position doesn't affect the
+ *  math. Sits 12px below the bbox, past the bottom crop handle's hit strip. */
 export function DomEditRotateHandle({
   overlayRect,
   cropOutlineInsetPx,
@@ -15,27 +19,43 @@ export function DomEditRotateHandle({
   const inset = cropOutlineInsetPx ?? { top: 0, right: 0, bottom: 0, left: 0 };
   const visibleLeft = overlayRect.left + inset.left;
   const visibleWidth = Math.max(0, overlayRect.width - inset.left - inset.right);
-  const visibleTop = overlayRect.top + inset.top;
+  const visibleBottom = overlayRect.top + overlayRect.height - inset.bottom;
   return (
-    <div
-      className="pointer-events-none absolute"
+    <button
+      type="button"
+      className="pointer-events-auto absolute flex items-center justify-center border-0 bg-transparent p-0"
       style={{
         left: visibleLeft + visibleWidth / 2,
-        top: visibleTop - 34,
-        width: 28,
-        height: 34,
+        top: visibleBottom + 12,
+        width: 22,
+        height: 22,
         transform: "translateX(-50%)",
+        touchAction: "none",
+        // Closed-hand grab cursor: this handle is grabbed and dragged to rotate.
+        cursor: "grabbing",
       }}
+      title="Rotate"
+      aria-label="Rotate selection"
+      onPointerDown={onStartRotate}
     >
-      <div className="absolute left-1/2 top-3 bottom-0 w-px -translate-x-1/2 bg-studio-accent/60" />
-      <button
-        type="button"
-        className="pointer-events-auto absolute left-1/2 top-0 h-3 w-3 -translate-x-1/2 rounded-full border border-studio-accent bg-studio-accent p-0 shadow-[0_0_0_2px_rgba(60,230,172,0.18)]"
-        style={{ cursor: "grab", touchAction: "none" }}
-        title="Rotate"
-        aria-label="Rotate selection"
-        onPointerDown={onStartRotate}
-      />
-    </div>
+      <span className="pointer-events-none flex h-[18px] w-[18px] items-center justify-center rounded-full border border-studio-accent/70 bg-studio-surface text-studio-accent shadow-[0_0_3px_rgba(0,0,0,0.45)]">
+        <svg
+          width="11"
+          height="11"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2.5"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          aria-hidden="true"
+        >
+          <path d="M3 12a9 9 0 0 1 9-9 9.75 9.75 0 0 1 6.74 2.74L21 8" />
+          <path d="M21 3v5h-5" />
+          <path d="M21 12a9 9 0 0 1-9 9 9.75 9.75 0 0 1-6.74-2.74L3 16" />
+          <path d="M8 16H3v5" />
+        </svg>
+      </span>
+    </button>
   );
 }

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

@@ -0,0 +1,80 @@
+// @vitest-environment happy-dom
+
+import React, { act, createRef } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it, vi } from "vitest";
+import type { DomEditSelection } from "./domEditing";
+import { DomEditSelectionChrome } from "./DomEditSelectionChrome";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+describe("DomEditSelectionChrome crop composition", () => {
+  it("places rotated crop UI in exactly one oriented coordinate plane", () => {
+    const element = document.createElement("div");
+    element.id = "clip";
+    element.style.clipPath = "inset(10px)";
+    Object.defineProperties(element, {
+      offsetWidth: { value: 200 },
+      offsetHeight: { value: 100 },
+    });
+    document.body.append(element);
+    vi.spyOn(window, "getComputedStyle").mockReturnValue({
+      clipPath: "inset(10px)",
+      transform: "matrix(0.8660254, 0.5, -0.5, 0.8660254, 0, 0)",
+    } as CSSStyleDeclaration);
+    const selection = {
+      element,
+      id: "clip",
+      selector: "#clip",
+      capabilities: {
+        canCrop: true,
+        canApplyManualOffset: true,
+        canApplyManualSize: true,
+        canApplyManualRotation: true,
+      },
+    } as unknown as DomEditSelection;
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    act(() => {
+      root.render(
+        <DomEditSelectionChrome
+          selection={selection}
+          overlayRect={{
+            left: 100,
+            top: 50,
+            width: 220,
+            height: 130,
+            editScaleX: 1,
+            editScaleY: 1,
+            angle: 30,
+          }}
+          allowCanvasMovement={true}
+          boxRef={createRef()}
+          boxChromeClass=""
+          boxClipPath={undefined}
+          selectionKey="clip"
+          groupSelectionCount={0}
+          blockedMoveRef={createRef()}
+          gestures={{ startGesture: vi.fn() } as never}
+          onStyleCommit={vi.fn()}
+          onBoxMouseDown={vi.fn()}
+          onBoxClick={vi.fn()}
+        />,
+      );
+    });
+
+    const cropFrame = host.querySelector<HTMLElement>("[data-dom-edit-crop-frame]")!;
+    const rotations: string[] = [];
+    for (
+      let node: HTMLElement | null = cropFrame;
+      node && node !== host;
+      node = node.parentElement
+    ) {
+      if (node.style.transform.includes("rotate(")) rotations.push(node.style.transform);
+    }
+    expect(rotations).toHaveLength(1);
+    expect(Number.parseFloat(rotations[0]!.slice("rotate(".length))).toBeCloseTo(30, 5);
+    act(() => root.unmount());
+  });
+});