@hyperframes/studio 0.7.55 → 0.7.57

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

@@ -3,7 +3,11 @@ import React, { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { installReactActEnvironment, makeSelection } from "../../hooks/domSelectionTestHarness";
+import { resolveZIndexEntries } from "../nle/PreviewOverlays";
+import { useElementLifecycleOps } from "../../hooks/useElementLifecycleOps";
+import type { DomEditPatchBatch } from "../../hooks/domEditCommitTypes";
 import { CanvasContextMenu } from "./CanvasContextMenu";
+import type { ZOrderAction, ZOrderPatch } from "./canvasContextMenuZOrder";
 import type { DomEditSelection } from "./domEditing";
 
 installReactActEnvironment();
@@ -24,7 +28,8 @@ afterEach(() => {
 
 function renderMenu(props: {
   selection: DomEditSelection;
-  onApplyZIndex?: () => void;
+  onApplyZIndex?: (patches: ZOrderPatch[], action: ZOrderAction) => void;
+  onZOrderCrossed?: (crossed: HTMLElement, action: ZOrderAction) => void;
   onDelete?: (selection: DomEditSelection) => void;
 }) {
   root = createRoot(host);
@@ -36,6 +41,7 @@ function renderMenu(props: {
         selection: props.selection,
         onClose: () => {},
         onApplyZIndex: props.onApplyZIndex,
+        onZOrderCrossed: props.onZOrderCrossed,
         onDelete: props.onDelete,
       }),
     );
@@ -113,3 +119,148 @@ describe("CanvasContextMenu — handler gating", () => {
     expect(document.body.querySelector(".border-t")).toBeNull();
   });
 });
+
+// ── Menu z-action → commit path (wired the way PreviewOverlays wires the app) ──
+
+function pressMenuItem(label: string) {
+  const button = zOrderButtons().find((b) => b.textContent === label);
+  expect(button).toBeDefined();
+  act(() => {
+    button!.dispatchEvent(
+      new PointerEvent("pointerdown", { bubbles: true, cancelable: true, button: 0 }),
+    );
+  });
+}
+
+/** Target (static, earlier in DOM) below an equal-z sibling — z action must renumber. */
+function makeStaticFamily() {
+  const parent = document.createElement("div");
+  const target = document.createElement("div");
+  target.id = "target";
+  // In happy-dom an unset computed position is "" (not "static"), which would
+  // skip the commit hook's static-position injection; declare it explicitly so
+  // the test exercises the browser default.
+  target.style.position = "static";
+  const other = document.createElement("div");
+  other.id = "other";
+  parent.append(target, other);
+  document.body.append(parent);
+  return { parent, target, other };
+}
+
+interface CapturedBatchCall {
+  batches: DomEditPatchBatch[];
+  options: { label: string; coalesceKey: string };
+}
+
+/** Mount the REAL commit hook (persist layer mocked at commitDomEditPatchBatches). */
+function renderCommitHook(captured: CapturedBatchCall[]) {
+  type Commit = ReturnType<typeof useElementLifecycleOps>["handleDomZIndexReorderCommit"];
+  let commit: Commit | undefined;
+  function Harness() {
+    ({ handleDomZIndexReorderCommit: commit } = useElementLifecycleOps({
+      activeCompPath: "index.html",
+      showToast: vi.fn(),
+      writeProjectFile: vi.fn(async () => {}),
+      domEditSaveTimestampRef: { current: 0 },
+      editHistory: { recordEdit: vi.fn(async () => {}) },
+      projectIdRef: { current: null },
+      reloadPreview: vi.fn(),
+      clearDomSelection: vi.fn(),
+      commitDomEditPatchBatches: async (batches, options) => {
+        captured.push({ batches, options });
+      },
+    }));
+    return null;
+  }
+  const hookHost = document.createElement("div");
+  document.body.append(hookHost);
+  const hookRoot = createRoot(hookHost);
+  act(() => hookRoot.render(<Harness />));
+  return { commit: commit!, cleanup: () => act(() => hookRoot.unmount()) };
+}
+
+describe("CanvasContextMenu — z-action commit path", () => {
+  it("never mutates live styles itself and persists the position patch for a static element", async () => {
+    const { target } = makeStaticFamily();
+    const selection = makeSelection("Target", target);
+    const captured: CapturedBatchCall[] = [];
+    const { commit, cleanup } = renderCommitHook(captured);
+
+    // Wire onApplyZIndex the way the app does (PreviewOverlays → the commit
+    // hook), asserting the menu has NOT touched the DOM when it fires — the
+    // hook must capture true pre-change styles for its rollback.
+    const stylesAtApply: Array<{ zIndex: string; position: string }> = [];
+    renderMenu({
+      selection,
+      onApplyZIndex: (patches, action) => {
+        stylesAtApply.push({ zIndex: target.style.zIndex, position: target.style.position });
+        const { entries } = resolveZIndexEntries(selection, patches);
+        void commit(entries, undefined, action);
+      },
+    });
+
+    await act(async () => pressMenuItem("Bring forward"));
+
+    // The menu left the element pristine; only the commit hook wrote styles.
+    expect(stylesAtApply).toEqual([{ zIndex: "", position: "static" }]);
+    expect(target.style.zIndex).toBe("1");
+    expect(target.style.position).toBe("relative");
+
+    // The persisted payload carries BOTH the z-index and the injected position,
+    // so the reorder survives the post-commit reloadPreview().
+    expect(captured).toHaveLength(1);
+    const targetPatch = captured[0]?.batches
+      .flatMap((batch) => batch.patches)
+      .find((patch) => patch.target.id === "target");
+    expect(targetPatch?.operations).toEqual(
+      expect.arrayContaining([
+        { type: "inline-style", property: "z-index", value: "1" },
+        { type: "inline-style", property: "position", value: "relative" },
+      ]),
+    );
+    // F7: the action kind is part of the default undo coalesce key, so two
+    // different menu actions never merge into one undo step.
+    expect(captured[0]?.options.coalesceKey).toContain("bring-forward");
+
+    cleanup();
+  });
+
+  it("reports the crossed sibling to onZOrderCrossed for a forward step (resolved pre-mutation)", async () => {
+    // target (earlier in DOM) and other are tied — bring-forward steps over
+    // `other`, and the flash callback must receive exactly that element, after
+    // onApplyZIndex ran (call order lets the host measure post-commit rects).
+    const { target, other } = makeStaticFamily();
+    const selection = makeSelection("Target", target);
+    const calls: Array<{ kind: string; crossed?: HTMLElement }> = [];
+
+    renderMenu({
+      selection,
+      onApplyZIndex: () => calls.push({ kind: "apply" }),
+      onZOrderCrossed: (crossed, action) => {
+        expect(action).toBe("bring-forward");
+        calls.push({ kind: "crossed", crossed });
+      },
+    });
+
+    await act(async () => pressMenuItem("Bring forward"));
+
+    expect(calls.map((c) => c.kind)).toEqual(["apply", "crossed"]);
+    expect(calls[1]?.crossed).toBe(other);
+  });
+
+  it("does not call onZOrderCrossed for bring-to-front", async () => {
+    const { target } = makeStaticFamily();
+    const onZOrderCrossed = vi.fn();
+
+    renderMenu({
+      selection: makeSelection("Target", target),
+      onApplyZIndex: vi.fn(),
+      onZOrderCrossed,
+    });
+
+    await act(async () => pressMenuItem("Bring to front"));
+
+    expect(onZOrderCrossed).not.toHaveBeenCalled();
+  });
+});

package/src/components/editor/CanvasContextMenu.tsx

@@ -7,10 +7,13 @@
  * useContextMenuDismiss.
  *
  * ── Wiring (z-order persistence) ─────────────────────────────────────────────
- * Z-index changes are applied optimistically to the live iframe element(s) via
+ * Z-index changes are resolved against the live iframe DOM via
  * `resolveZOrderChange`, which returns a MULTI-element patch list (tie-aware:
  * moving a target past an equal-z sibling can require renumbering the affected
- * set). The patches are surfaced through the `onApplyZIndex` prop.
+ * set). The patches are surfaced through the `onApplyZIndex` prop; the menu
+ * itself never mutates element styles — handleDomZIndexReorderCommit applies
+ * the live z-index (and injects position when needed) in the same synchronous
+ * flow, and captures the TRUE prior styles for its failure rollback.
  *
  * The prop MUST be wired at the call site to route through the full persist
  * path. PreviewOverlays.tsx builds the per-patch PatchTargets (the selected
@@ -26,7 +29,9 @@ import type { DomEditSelection } from "./domEditing";
 import { useContextMenuDismiss } from "../../hooks/useContextMenuDismiss";
 import {
   isZOrderActionEnabled,
+  resolveCrossedNeighbor,
   resolveZOrderChange,
+  type ZOrderAction,
   type ZOrderPatch,
 } from "./canvasContextMenuZOrder";
 
@@ -38,12 +43,22 @@ interface CanvasContextMenuProps {
   selection: DomEditSelection;
   onClose: () => void;
   /**
-   * Called with the resolved z-order patch list after an optimistic DOM update.
-   * Each patch is an { element, zIndex } pair (the target and, when a renumber
-   * is needed, affected siblings). Wire to handleDomZIndexReorderCommit (see
-   * module-level wiring comment).
+   * Called with the resolved z-order patch list and the menu action that
+   * produced it (the action feeds the undo coalesce key, so two DIFFERENT
+   * actions never merge into one undo step). Each patch is an
+   * { element, zIndex } pair (the target and, when a renumber is needed,
+   * affected siblings). The menu does NOT touch the live DOM — wire to
+   * handleDomZIndexReorderCommit, which applies the live styles itself
+   * (see module-level wiring comment).
    */
-  onApplyZIndex?: (patches: ZOrderPatch[]) => void;
+  onApplyZIndex?: (patches: ZOrderPatch[], action: ZOrderAction) => void;
+  /**
+   * Called after a successful bring-forward / send-backward with the sibling
+   * the target stepped over (resolved from the SAME pre-mutation state as the
+   * patches), so the host can flash a highlight on it in the studio overlay.
+   * Never called for front/back or no-op actions.
+   */
+  onZOrderCrossed?: (crossed: HTMLElement, action: ZOrderAction) => void;
   /**
    * Delete the selected element. Wire to handleDomEditElementDelete from
    * useDomEditActionsContext — same path as the Delete/Backspace hotkey.
@@ -68,6 +83,7 @@ export const CanvasContextMenu = memo(function CanvasContextMenu({
   selection,
   onClose,
   onApplyZIndex,
+  onZOrderCrossed,
   onDelete,
 }: CanvasContextMenuProps) {
   const menuRef = useContextMenuDismiss(onClose);
@@ -93,20 +109,19 @@ export const CanvasContextMenu = memo(function CanvasContextMenu({
   const el = selection.element;
 
   function handleZAction(action: ZAction) {
-    // No persist handler → do NOT touch the live iframe DOM. An optimistic
-    // write with nothing to persist just reverts on the next reload.
     if (!onApplyZIndex) return;
     const patches = resolveZOrderChange(el, action);
     if (patches === null) return;
-    // Optimistic update — visible immediately even before persist completes.
-    for (const patch of patches) {
-      patch.element.style.zIndex = String(patch.zIndex);
-      const view = patch.element.ownerDocument?.defaultView;
-      if (view && view.getComputedStyle(patch.element).position === "static") {
-        patch.element.style.position = "relative";
-      }
-    }
-    onApplyZIndex(patches);
+    // Resolve the crossed neighbor BEFORE the commit path mutates live styles —
+    // both resolvers must read the same pre-change render order.
+    const crossed = onZOrderCrossed ? resolveCrossedNeighbor(el, action) : null;
+    // Do NOT pre-apply styles here: handleDomZIndexReorderCommit writes the
+    // live z-index (and injects position:relative for static elements) in the
+    // same synchronous flow, so feedback is still instant — and it must read
+    // the PRE-change styles itself, both to capture true rollback values and
+    // to detect a static position that needs persisting.
+    onApplyZIndex(patches, action);
+    if (crossed && onZOrderCrossed) onZOrderCrossed(crossed, action);
     onClose();
   }
 

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

@@ -1,7 +1,7 @@
 // @vitest-environment happy-dom
 import React, { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import type { DomEditSelection } from "./domEditing";
 import type { OverlayRect } from "./domEditOverlayGeometry";
 import { DomEditCropHandles } from "./DomEditCropHandles";
@@ -33,7 +33,10 @@ function makeEl(id: string, clip: string): HTMLElement {
   return el;
 }
 
-function render(el: HTMLElement): { root: Root; rerender: (next: HTMLElement) => void } {
+function render(
+  el: HTMLElement,
+  onStyleCommit: (property: string, value: string) => Promise<void> | void = () => undefined,
+): { root: Root; rerender: (next: HTMLElement) => void } {
   const host = document.createElement("div");
   document.body.append(host);
   const root = createRoot(host);
@@ -43,7 +46,7 @@ function render(el: HTMLElement): { root: Root; rerender: (next: HTMLElement) =>
         <DomEditCropHandles
           selection={selectionFor(target)}
           overlayRect={overlayRect}
-          onStyleCommit={() => undefined}
+          onStyleCommit={onStyleCommit}
         />,
       );
     });
@@ -83,4 +86,72 @@ describe("DomEditCropHandles clip lift/restore", () => {
     act(() => root.unmount());
     expect(a.style.getPropertyValue("clip-path")).toBe("circle(50% at 50% 50%)");
   });
+
+  it("re-lifts synchronously after the commit path re-applies the cropped value", async () => {
+    const a = makeEl("a", "inset(10px)");
+    let resolveCommit: (() => void) | undefined;
+    const pendingCommit = new Promise<void>((resolve) => {
+      resolveCommit = resolve;
+    });
+    const onStyleCommit = vi.fn((property: string, value: string) => {
+      a.style.setProperty(property, value);
+      return pendingCommit;
+    });
+    const { root } = render(a, onStyleCommit);
+    const handle = document.querySelector<HTMLButtonElement>('[aria-label="Crop right"]');
+    expect(handle).toBeTruthy();
+
+    act(() =>
+      handle!.dispatchEvent(
+        new PointerEvent("pointerdown", { bubbles: true, pointerId: 1, clientX: 100 }),
+      ),
+    );
+    act(() =>
+      handle!.dispatchEvent(
+        new PointerEvent("pointermove", { bubbles: true, pointerId: 1, clientX: 80 }),
+      ),
+    );
+    act(() =>
+      handle!.dispatchEvent(
+        new PointerEvent("pointerup", { bubbles: true, pointerId: 1, clientX: 80 }),
+      ),
+    );
+
+    expect(onStyleCommit).toHaveBeenCalledWith("clip-path", "inset(10px 30px 10px 10px)");
+    expect(a.style.getPropertyValue("clip-path")).toBe("none");
+    resolveCommit?.();
+    await act(async () => pendingCommit);
+    act(() => root.unmount());
+    expect(a.style.getPropertyValue("clip-path")).toBe("inset(10px 30px 10px 10px)");
+  });
+
+  it("re-lifts when the crop commit rejects", async () => {
+    const a = makeEl("a", "inset(10px)");
+    const onStyleCommit = vi.fn((property: string, value: string) => {
+      a.style.setProperty(property, value);
+      return Promise.reject(new Error("persist failed"));
+    });
+    const { root } = render(a, onStyleCommit);
+    const handle = document.querySelector<HTMLButtonElement>('[aria-label="Crop right"]');
+
+    act(() =>
+      handle!.dispatchEvent(
+        new PointerEvent("pointerdown", { bubbles: true, pointerId: 2, clientX: 100 }),
+      ),
+    );
+    act(() =>
+      handle!.dispatchEvent(
+        new PointerEvent("pointermove", { bubbles: true, pointerId: 2, clientX: 80 }),
+      ),
+    );
+    await act(async () => {
+      handle!.dispatchEvent(
+        new PointerEvent("pointerup", { bubbles: true, pointerId: 2, clientX: 80 }),
+      );
+      await Promise.resolve();
+    });
+
+    expect(a.style.getPropertyValue("clip-path")).toBe("none");
+    act(() => root.unmount());
+  });
 });

package/src/components/editor/DomEditCropHandles.tsx

@@ -31,12 +31,16 @@ interface DomEditCropHandlesProps {
   onStyleCommit?: (property: string, value: string) => Promise<void> | void;
 }
 
-// Gap (px) between an edge handle and the element edge, so the handle sits
-// clear of the element body and can't intercept a move-drag.
-const EDGE_HANDLE_GAP = 8;
+// Hit-strip size (px) for an edge crop handle: THICKNESS extends outward from
+// the crop edge (flush against it, never over the element body, so a body
+// drag always MOVES), LENGTH runs along the edge. The visible pill is smaller
+// and centered inside the strip.
+const EDGE_HIT_THICKNESS = 12;
+const EDGE_HIT_LENGTH = 32;
 
-/** Place an edge handle just OUTSIDE the given crop edge (translate pushes it
- *  fully past the boundary). Keeps the element body free for moving. */
+/** Place an edge handle's hit strip just OUTSIDE the given crop edge
+ *  (translate pushes it fully past the boundary). Keeps the element body free
+ *  for moving. Corners stay free for the selection's own resize handles. */
 function edgeHandlePlacement(
   edge: CropEdge,
   rect: { left: number; top: number; width: number; height: number },
@@ -44,27 +48,36 @@ function edgeHandlePlacement(
   const cx = rect.left + rect.width / 2;
   const cy = rect.top + rect.height / 2;
   if (edge === "top") {
-    return { left: cx, top: rect.top - EDGE_HANDLE_GAP, transform: "translate(-50%, -100%)" };
+    return { left: cx, top: rect.top, transform: "translate(-50%, -100%)" };
   }
   if (edge === "bottom") {
-    return {
-      left: cx,
-      top: rect.top + rect.height + EDGE_HANDLE_GAP,
-      transform: "translate(-50%, 0)",
-    };
+    return { left: cx, top: rect.top + rect.height, transform: "translate(-50%, 0)" };
   }
   if (edge === "left") {
-    return { left: rect.left - EDGE_HANDLE_GAP, top: cy, transform: "translate(-100%, -50%)" };
+    return { left: rect.left, top: cy, transform: "translate(-100%, -50%)" };
   }
-  return {
-    left: rect.left + rect.width + EDGE_HANDLE_GAP,
-    top: cy,
-    transform: "translate(0, -50%)",
-  };
+  return { left: rect.left + rect.width, top: cy, transform: "translate(0, -50%)" };
 }
 
 const EDGES: CropEdge[] = ["top", "right", "bottom", "left"];
 
+/** Hit-strip + pill dimensions for an edge handle, keyed on its orientation. */
+function edgeHandleMetrics(vertical: boolean): {
+  hitWidth: number;
+  hitHeight: number;
+  cursor: string;
+  pillWidth: number;
+  pillHeight: number;
+} {
+  return {
+    hitWidth: vertical ? EDGE_HIT_THICKNESS : EDGE_HIT_LENGTH,
+    hitHeight: vertical ? EDGE_HIT_LENGTH : EDGE_HIT_THICKNESS,
+    cursor: vertical ? "ew-resize" : "ns-resize",
+    pillWidth: vertical ? 4 : 24,
+    pillHeight: vertical ? 24 : 4,
+  };
+}
+
 /**
  * Always-on crop, integrated with the selection (no crop "mode"): while a
  * croppable element is selected its clip is lifted so the FULL content shows and
@@ -83,6 +96,7 @@ export function DomEditCropHandles({
 }: DomEditCropHandlesProps) {
   const gestureRef = useRef<CropGestureState | null>(null);
   const [dragging, setDragging] = useState(false);
+  const [hotEdge, setHotEdge] = useState<CropEdge | null>(null);
   // readElementCropInsets returns null for a clip this tool can't represent
   // (circle/polygon/non-px inset): the crop UI must fully stand down for that
   // element — no lift, no handles — or select+deselect replaces the authored
@@ -209,10 +223,9 @@ export function DomEditCropHandles({
     setDragging(false);
     if (!gesture.didMove) return;
     // Commit to the file. The commit path re-applies the value to the live
-    // element, so re-lift afterwards to keep showing the full content + dim while
-    // the element stays selected. Re-lift on both fulfilment and rejection so a
-    // failed commit still restores the crop-mode presentation (and the rejection
-    // is handled rather than left unhandled).
+    // element synchronously, so re-lift in the same turn to keep showing the full
+    // content + dim while selected. Re-lift again on rejection so a failed commit
+    // still restores crop-mode presentation without an unhandled rejection.
     const el = selection.element;
     const reLift = () => {
       if (liftedRef.current) el.style.setProperty("clip-path", "none");
@@ -223,12 +236,16 @@ export function DomEditCropHandles({
       state.insets.right > 0 ||
       state.insets.bottom > 0 ||
       state.insets.left > 0;
-    void Promise.resolve(onStyleCommit?.("clip-path", committedValue)).then(() => {
+    const commit = onStyleCommit?.("clip-path", committedValue);
+    // handleDomStyleCommit applies the persisted value to the live element
+    // synchronously before its first await. Restore the crop-mode lift in this
+    // same turn so the browser never paints that intermediate cropped state.
+    reLift();
+    void Promise.resolve(commit).then(() => {
       // Only a landed commit makes the rebuilt inset the restore value; a
       // failed one keeps restoring the pre-lift clip. Store the value itself —
       // by deselect time, render state describes the next selection.
       committedClipRef.current = cropped ? committedValue : "";
-      reLift();
     }, reLift);
   };
 
@@ -304,6 +321,7 @@ export function DomEditCropHandles({
         <button
           type="button"
           aria-label="Reposition crop"
+          title="Reposition crop"
           data-dom-edit-crop-handle="true"
           className="pointer-events-auto absolute rounded-full border-2 border-studio-accent bg-studio-accent/30 shadow-[0_0_0_1px_rgba(0,0,0,0.4)]"
           style={{
@@ -323,31 +341,48 @@ export function DomEditCropHandles({
       )}
       {/* Edge handles — drag a side to crop it. Positioned just OUTSIDE the crop
           edge (via edgeHandlePlacement) so they never overlap the element body:
-          dragging the body always MOVES, only a handle crops. */}
+          dragging the body always MOVES, only a handle crops. The pill is
+          hover-revealed (or shown while dragging / once a crop exists) so the
+          resting selection chrome stays uncluttered; the hit strip is always
+          live, and the title names the affordance. */}
       {EDGES.map((edge) => {
         const vertical = edge === "left" || edge === "right";
         const place = edgeHandlePlacement(edge, cropRect);
+        const revealed = dragging || hasCrop || hotEdge === edge;
+        const m = edgeHandleMetrics(vertical);
         return (
           <button
             key={edge}
             type="button"
             aria-label={`Crop ${edge}`}
+            title="Crop"
             data-dom-edit-crop-handle="true"
-            className="pointer-events-auto absolute rounded-full bg-studio-accent shadow-[0_0_0_1px_rgba(0,0,0,0.4)]"
+            className="pointer-events-auto absolute flex items-center justify-center border-0 bg-transparent p-0"
             style={{
               left: place.left,
               top: place.top,
-              width: vertical ? 5 : 26,
-              height: vertical ? 26 : 5,
+              width: m.hitWidth,
+              height: m.hitHeight,
               transform: place.transform,
-              cursor: vertical ? "ew-resize" : "ns-resize",
+              cursor: m.cursor,
               touchAction: "none",
             }}
+            onPointerEnter={() => setHotEdge(edge)}
+            onPointerLeave={() => setHotEdge((prev) => (prev === edge ? null : prev))}
             onPointerDown={(event) => startCropGesture(edge, event)}
             onPointerMove={updateCropGesture}
             onPointerUp={finishCropGesture}
             onPointerCancel={cancelCropGesture}
-          />
+          >
+            <span
+              className="pointer-events-none rounded-full bg-studio-accent/90 shadow-[0_0_0_1px_rgba(0,0,0,0.4)] transition-opacity duration-100"
+              style={{
+                width: m.pillWidth,
+                height: m.pillHeight,
+                opacity: revealed ? 1 : 0,
+              }}
+            />
+          </button>
         );
       })}
     </div>