@hyperframes/studio 0.7.56 → 0.7.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.7.56",
+  "version": "0.7.58",
   "description": "",
   "repository": {
     "type": "git",
@@ -46,11 +46,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/player": "0.7.56",
-    "@hyperframes/studio-server": "0.7.56",
-    "@hyperframes/sdk": "0.7.56",
-    "@hyperframes/core": "0.7.56",
-    "@hyperframes/parsers": "0.7.56"
+    "@hyperframes/core": "0.7.58",
+    "@hyperframes/parsers": "0.7.58",
+    "@hyperframes/player": "0.7.58",
+    "@hyperframes/sdk": "0.7.58",
+    "@hyperframes/studio-server": "0.7.58"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -65,7 +65,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.7.56"
+    "@hyperframes/producer": "0.7.58"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -189,10 +189,10 @@ export function StudioApp() {
       }>,
       coalesceKey?: string,
       operation: TimelineMoveOperation = "timing",
+      coalesceMs?: number,
     ) => {
-      await persistTimelineMoveEditsAtomically(edits, coalesceKey, operation, {
-        handleTimelineGroupMove: timelineEditing.handleTimelineGroupMove,
-      });
+      const deps = { handleTimelineGroupMove: timelineEditing.handleTimelineGroupMove };
+      await persistTimelineMoveEditsAtomically(edits, coalesceKey, operation, deps, coalesceMs);
     },
     [timelineEditing.handleTimelineGroupMove],
   );

package/src/components/StudioFeedbackBar.tsx

@@ -180,9 +180,9 @@ export const StudioFeedbackBar = memo(function StudioFeedbackBar() {
         </>
       ) : (
         <>
-          <span className="text-neutral-500 flex-shrink-0">How's the Studio experience?</span>
+          <span className="text-neutral-500 flex-shrink-0">Recommend HyperFrames?</span>
           <div className="flex items-center gap-0.5">
-            {[1, 2, 3, 4, 5].map((n) => (
+            {Array.from({ length: 11 }, (_, n) => n).map((n) => (
               <button
                 key={n}
                 onClick={() => handleRating(n)}

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

@@ -3,7 +3,12 @@ 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 { makeLifecycleOpsParams } from "../../hooks/elementLifecycleOpsTestUtils";
+import type { DomEditPatchBatch } from "../../hooks/domEditCommitTypes";
 import { CanvasContextMenu } from "./CanvasContextMenu";
+import type { ZOrderAction, ZOrderPatch } from "./canvasContextMenuZOrder";
 import type { DomEditSelection } from "./domEditing";
 
 installReactActEnvironment();
@@ -24,7 +29,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 +42,7 @@ function renderMenu(props: {
         selection: props.selection,
         onClose: () => {},
         onApplyZIndex: props.onApplyZIndex,
+        onZOrderCrossed: props.onZOrderCrossed,
         onDelete: props.onDelete,
       }),
     );
@@ -96,9 +103,26 @@ describe("CanvasContextMenu — handler gating", () => {
 
     renderMenu({ selection: makeSelection("Target", el), onApplyZIndex: vi.fn() });
 
-    expect(zOrderButtons()).toHaveLength(4);
+    const buttons = zOrderButtons();
+    expect(buttons).toHaveLength(4);
     expect(hasDeleteItem()).toBe(false);
     expect(document.body.querySelector(".border-t")).toBeNull();
+
+    // Labels stay the exact industry-standard names (the icons add no text)...
+    expect(buttons.map((b) => b.textContent)).toEqual([
+      "Bring to front",
+      "Bring forward",
+      "Send backward",
+      "Send to back",
+    ]);
+    // ...and each item leads with a stroke icon that inherits the item's text
+    // color (currentColor), so the disabled muted tone applies to it too.
+    for (const button of buttons) {
+      const svg = button.firstElementChild;
+      expect(svg?.tagName.toLowerCase()).toBe("svg");
+      expect(svg?.getAttribute("stroke")).toBe("currentColor");
+      expect(svg?.getAttribute("aria-hidden")).toBe("true");
+    }
   });
 
   it("shows only Delete (no z-order items, no divider) when onApplyZIndex is absent", () => {
@@ -113,3 +137,143 @@ 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(
+      makeLifecycleOpsParams({
+        commitDomEditPatchBatches: async (batches, options) => {
+          captured.push({ batches, options });
+          return { durable: true, allMatched: true, changed: true };
+        },
+      }),
+    ));
+    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,31 @@ 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).
+   *
+   * `crossed` is the sibling a forward/backward step moved past, resolved from
+   * the SAME pre-mutation render order as the patches (null for front/back or
+   * when there is no neighbor). The host uses it to mirror the z action into a
+   * timeline lane move (resolveZMirrorLaneMove's crossedKey).
    */
-  onApplyZIndex?: (patches: ZOrderPatch[]) => void;
+  onApplyZIndex?: (
+    patches: ZOrderPatch[],
+    action: ZOrderAction,
+    crossed: HTMLElement | null,
+  ) => 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.
@@ -55,10 +79,61 @@ interface CanvasContextMenuProps {
 
 type ZAction = "bring-forward" | "send-backward" | "bring-to-front" | "send-to-back";
 
+// Stacked-layer + arrow glyphs, one per z action (16px, stroke, currentColor —
+// matches the studio's inline-SVG conventions: fill="none", 1.2 stroke, round
+// caps/joins). Single actions show ONE layer diamond with the arrow stepping
+// one way; front/back show a TWO-diamond stack with the arrow piercing through
+// and beyond it. `paths` are the d attributes, drawn in order.
+const Z_ACTION_ICONS: Record<ZAction, string[]> = {
+  "bring-forward": [
+    "M3 11 L8 8.5 L13 11 L8 13.5 Z", // layer diamond (bottom)
+    "M8 8.5 L8 2", // arrow shaft up
+    "M5.5 4.5 L8 2 L10.5 4.5", // arrow head
+  ],
+  "send-backward": [
+    "M3 5 L8 2.5 L13 5 L8 7.5 Z", // layer diamond (top)
+    "M8 7.5 L8 14", // arrow shaft down
+    "M5.5 11.5 L8 14 L10.5 11.5", // arrow head
+  ],
+  "bring-to-front": [
+    "M3 9.5 L8 7 L13 9.5 L8 12 Z", // upper layer of the stack
+    "M3 12.5 L8 10 L13 12.5 L8 15 Z", // lower layer of the stack
+    "M8 12.5 L8 2", // arrow piercing up through/above the stack
+    "M5.5 4.5 L8 2 L10.5 4.5", // arrow head
+  ],
+  "send-to-back": [
+    "M3 4 L8 1.5 L13 4 L8 6.5 Z", // upper layer of the stack
+    "M3 7 L8 4.5 L13 7 L8 9.5 Z", // lower layer of the stack
+    "M8 3.5 L8 14", // arrow piercing down through/below the stack
+    "M5.5 11.5 L8 14 L10.5 11.5", // arrow head
+  ],
+};
+
+function ZActionIcon({ action }: { action: ZAction }) {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="mr-2 shrink-0"
+      aria-hidden="true"
+    >
+      {Z_ACTION_ICONS[action].map((d) => (
+        <path key={d} d={d} />
+      ))}
+    </svg>
+  );
+}
+
 const Z_ACTIONS: Array<{ action: ZAction; label: string }> = [
+  { action: "bring-to-front", label: "Bring to front" },
   { action: "bring-forward", label: "Bring forward" },
   { action: "send-backward", label: "Send backward" },
-  { action: "bring-to-front", label: "Bring to front" },
   { action: "send-to-back", label: "Send to back" },
 ];
 
@@ -68,6 +143,7 @@ export const CanvasContextMenu = memo(function CanvasContextMenu({
   selection,
   onClose,
   onApplyZIndex,
+  onZOrderCrossed,
   onDelete,
 }: CanvasContextMenuProps) {
   const menuRef = useContextMenuDismiss(onClose);
@@ -93,20 +169,21 @@ 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. Always resolved
+    // (not only for the flash): onApplyZIndex forwards it so the host can mirror
+    // the z step into a timeline lane move.
+    const crossed = resolveCrossedNeighbor(el, action);
+    // 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, crossed);
+    if (crossed && onZOrderCrossed) onZOrderCrossed(crossed, action);
     onClose();
   }
 
@@ -170,7 +247,10 @@ export const CanvasContextMenu = memo(function CanvasContextMenu({
                 if (enabled) handleZAction(action);
               }}
             >
-              {label}
+              {/* Icon inherits the item's text color via currentColor, so the
+                  disabled muted tone applies to both icon and label. */}
+              <ZActionIcon action={action} />
+              <span>{label}</span>
             </button>
           );
         })}

package/src/components/editor/DomEditOverlay.tsx

@@ -1,9 +1,11 @@
-import { memo, useCallback, useEffect, useMemo, useRef, useState, type RefObject } from "react";
+import { memo, useEffect, useMemo, useRef, useState, type RefObject } from "react";
 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,
@@ -27,7 +29,7 @@ import { useDomEditCompositionRect } from "./useDomEditCompositionRect";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { startOffCanvasIndicatorRefresh } from "./offCanvasIndicatorRefresh";
 import { CanvasContextMenu } from "./CanvasContextMenu";
-import type { ZOrderPatch } from "./canvasContextMenuZOrder";
+import type { ZOrderAction, ZOrderPatch } from "./canvasContextMenuZOrder";
 import { getPreviewTargetFromPointer } from "../../utils/studioPreviewHelpers";
 
 // Re-exports for external consumers — preserving existing import paths.
@@ -91,12 +93,20 @@ interface DomEditOverlayProps {
    */
   onDeleteSelection?: (selection: DomEditSelection) => void;
   /**
-   * Called with the resolved z-order patch list after an optimistic DOM update.
-   * The patch list is tie-aware and may include sibling elements (see
-   * canvasContextMenuZOrder). Wire to handleDomZIndexReorderCommit from
+   * 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[]) => void;
+  onApplyZIndex?: (
+    selection: DomEditSelection,
+    patches: ZOrderPatch[],
+    action: ZOrderAction,
+    /** Sibling a forward/backward step moved past (pre-mutation render order);
+     *  null for front/back. Feeds the timeline z-mirror's crossedKey. */
+    crossed: HTMLElement | null,
+  ) => void;
 }
 
 // fallow-ignore-next-line complexity
@@ -139,30 +149,12 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   const snapGuidesRef = useRef<SnapGuidesState | null>(null);
   const rafPausedRef = useRef(false);
 
-  // Context menu state: position of the right-click that opened it.
-  // contextMenuSelection 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<{
-    x: number;
-    y: number;
-    sel: DomEditSelection;
-  } | null>(null);
-
   const selectionRef = useRef(selection);
   selectionRef.current = selection;
 
-  // 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]);
+  // 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;
@@ -428,37 +420,15 @@ export const DomEditOverlay = memo(function DomEditOverlay({
     e.stopPropagation();
   };
 
-  // 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 });
-    },
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [],
-  );
+  // 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
@@ -551,24 +521,26 @@ export const DomEditOverlay = memo(function DomEditOverlay({
           x={contextMenu.x}
           y={contextMenu.y}
           selection={contextMenu.sel}
-          onClose={() => setContextMenu(null)}
+          onClose={closeContextMenu}
           onDelete={
             onDeleteSelection
               ? (sel) => {
-                  setContextMenu(null);
+                  closeContextMenu();
                   onDeleteSelection(sel);
                 }
               : undefined
           }
           onApplyZIndex={
             onApplyZIndex
-              ? (patches) => {
-                  onApplyZIndex(contextMenu.sel, patches);
+              ? (patches, action, crossed) => {
+                  onApplyZIndex(contextMenu.sel, patches, action, crossed);
                 }
               : undefined
           }
+          onZOrderCrossed={handleZOrderCrossed}
         />
       )}
+      <ZOrderCrossedFlash rect={zOrderFlashRect} />
       <GridOverlay
         visible={gridVisible}
         spacing={gridSpacing}