@hyperframes/studio 0.7.56 → 0.7.57

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

@@ -1,8 +1,10 @@
 // @vitest-environment jsdom
 import { describe, expect, it } from "vitest";
 import {
+  isElementVisibleForZOrder,
   isZOrderActionEnabled,
   parseZIndex,
+  resolveCrossedNeighbor,
   resolveZOrderChange,
   type ZOrderAction,
   type ZOrderPatch,
@@ -48,8 +50,12 @@ function makeFamily(
 }
 
 /** Resolve a z-order change and assert it produced patches (fails otherwise). */
-function resolveZOrderPatches(target: HTMLElement, action: ZOrderAction): ZOrderPatch[] {
-  const patches = resolveZOrderChange(target, action);
+function resolveZOrderPatches(
+  target: HTMLElement,
+  action: ZOrderAction,
+  options?: { isVisible?: (el: HTMLElement) => boolean },
+): ZOrderPatch[] {
+  const patches = resolveZOrderChange(target, action, options);
   expect(patches).not.toBeNull();
   if (!patches) throw new Error("expected z-order patches");
   return patches;
@@ -375,6 +381,27 @@ describe("resolveZOrderChange – excludes non-painting siblings", () => {
     expect(order.indexOf("target")).toBeLessThan(order.indexOf("a"));
   });
 
+  it("ignores <template>/<noscript> siblings in the family", () => {
+    // A renumber fallback once wrote z-index/position into <template> source
+    // markup because templates entered the sibling family. They never paint —
+    // exclude them like audio/script/style.
+    const parent = document.createElement("div");
+    const a = makeEl("a", "0");
+    const template = document.createElement("template");
+    template.style.zIndex = "2";
+    const noscript = document.createElement("noscript");
+    const target = makeEl("target", "0");
+    parent.append(a, template, noscript, target);
+
+    const patches = resolveZOrderPatches(target, "send-to-back");
+    for (const p of patches) {
+      expect(p.element).not.toBe(template);
+      expect(p.element).not.toBe(noscript);
+    }
+    const order = renderOrderIds(parent, { a, target }, patches);
+    expect(order.indexOf("target")).toBeLessThan(order.indexOf("a"));
+  });
+
   it("a lone painting element beside only non-painting siblings has no family → null", () => {
     const parent = document.createElement("div");
     const target = makeEl("target", "1");
@@ -392,6 +419,163 @@ describe("resolveZOrderChange – excludes non-painting siblings", () => {
   });
 });
 
+// ── visibility scoping (forward/backward step over VISIBLE siblings only) ──────
+//
+// The visibility probe is injectable (ZOrderResolveOptions.isVisible) exactly
+// like rect reading is stubbable — these tests drive the scoping logic with a
+// stub, without a real style engine.
+
+describe("resolveZOrderChange – visibility scoping (injectable stub)", () => {
+  /** Probe that hides exactly the given elements. */
+  function hiding(...hidden: HTMLElement[]) {
+    return { isVisible: (el: HTMLElement) => !hidden.includes(el) };
+  }
+
+  it("bring-forward steps over the next VISIBLE sibling, ignoring an invisible z-neighbor", () => {
+    // Render order: target(1), hidden(2), vis(3). The nearest z-neighbor above
+    // is invisible at the current frame — forward must land the target above
+    // `vis` (the next VISIBLE overlapping sibling), leaving `hidden` untouched.
+    const { target, byId } = makeFamily("1", [
+      ["hidden", "2"],
+      ["vis", "3"],
+    ]);
+    const patches = resolveZOrderPatches(target, "bring-forward", hiding(byId.hidden!));
+    expect(patches).toHaveLength(1);
+    expect(patchFor(patches, byId, "target")?.zIndex).toBe(4);
+    expect(patchFor(patches, byId, "hidden")).toBeUndefined();
+  });
+
+  it("send-backward steps below the next VISIBLE sibling, ignoring an invisible z-neighbor", () => {
+    // Render order: vis(1), hidden(2), target(3). Backward must drop the target
+    // below `vis`, not merely below the invisible `hidden`.
+    const { target, byId } = makeFamily("3", [
+      ["vis", "1"],
+      ["hidden", "2"],
+    ]);
+    const patches = resolveZOrderPatches(target, "send-backward", hiding(byId.hidden!));
+    expect(patches).toHaveLength(1);
+    expect(patchFor(patches, byId, "target")?.zIndex).toBe(0);
+    expect(patchFor(patches, byId, "hidden")).toBeUndefined();
+  });
+
+  it("forward/backward are no-ops when every overlapping sibling is invisible", () => {
+    const { target, byId } = makeFamily("1", [["hidden", "2"]]);
+    const opts = hiding(byId.hidden!);
+    expect(resolveZOrderChange(target, "bring-forward", opts)).toBeNull();
+    expect(resolveZOrderChange(target, "send-backward", opts)).toBeNull();
+  });
+
+  it("bring-to-front / send-to-back keep the FULL painting family (invisible siblings included)", () => {
+    // Unchanged semantics: front/back operate across all siblings, so an
+    // invisible sibling still counts and the actions stay meaningful.
+    const { target, byId } = makeFamily("1", [["hidden", "2"]]);
+    const opts = hiding(byId.hidden!);
+    const patches = resolveZOrderPatches(target, "bring-to-front", opts);
+    expect(patchFor(patches, byId, "target")?.zIndex).toBe(3);
+    expect(resolveZOrderChange(target, "send-to-back", opts)).toBeNull(); // already bottom
+  });
+
+  it("the target itself is retained even when the probe reports it invisible", () => {
+    const { target, byId } = makeFamily("1", [["vis", "2"]]);
+    const patches = resolveZOrderPatches(target, "bring-forward", hiding(target));
+    expect(patchFor(patches, byId, "target")?.zIndex).toBe(3);
+  });
+
+  it("isZOrderActionEnabled matches the resolver under the same visibility scope", () => {
+    const { target, byId } = makeFamily("1", [["hidden", "2"]]);
+    const opts = hiding(byId.hidden!);
+    // Forward/backward: scoped set collapses to the target alone → disabled.
+    expect(isZOrderActionEnabled(target, "bring-forward", opts)).toBe(false);
+    expect(isZOrderActionEnabled(target, "send-backward", opts)).toBe(false);
+    // Front/back: full family → enabled exactly where the resolver acts.
+    expect(isZOrderActionEnabled(target, "bring-to-front", opts)).toBe(true);
+    expect(isZOrderActionEnabled(target, "send-to-back", opts)).toBe(false);
+  });
+});
+
+// ── default visibility probe (element-level computed style) ───────────────────
+
+describe("isElementVisibleForZOrder – default probe", () => {
+  function attachedEl(style: Partial<CSSStyleDeclaration> = {}): HTMLElement {
+    const el = document.createElement("div");
+    Object.assign(el.style, style);
+    document.body.appendChild(el);
+    return el;
+  }
+
+  it("treats display:none / visibility:hidden / opacity≈0 as invisible", () => {
+    expect(isElementVisibleForZOrder(attachedEl({ display: "none" }))).toBe(false);
+    expect(isElementVisibleForZOrder(attachedEl({ visibility: "hidden" }))).toBe(false);
+    expect(isElementVisibleForZOrder(attachedEl({ opacity: "0" }))).toBe(false);
+    expect(isElementVisibleForZOrder(attachedEl({ opacity: "0.005" }))).toBe(false);
+  });
+
+  it("treats normal, translucent, and unstyled elements as visible", () => {
+    expect(isElementVisibleForZOrder(attachedEl())).toBe(true);
+    expect(isElementVisibleForZOrder(attachedEl({ opacity: "0.5" }))).toBe(true);
+    expect(isElementVisibleForZOrder(attachedEl({ visibility: "visible" }))).toBe(true);
+  });
+
+  it("exempts a hidden color-grading source (its canvas paints in its place)", () => {
+    const el = attachedEl({ opacity: "0" });
+    el.setAttribute("data-hf-color-grading-source-hidden", "");
+    expect(isElementVisibleForZOrder(el)).toBe(true);
+  });
+
+  it("is the default probe: the runtime's inline visibility:hidden on a time-inactive clip is skipped", () => {
+    // End-to-end through resolveZOrderChange with NO injected probe: the
+    // runtime hides inactive clips with inline `visibility:hidden` (see core
+    // runtime syncTimedElementVisibility) — computed style picks that up.
+    const parent = document.createElement("div");
+    const target = makeEl("target", "1");
+    const hidden = makeEl("hidden", "2");
+    hidden.style.visibility = "hidden";
+    const vis = makeEl("vis", "3");
+    parent.append(target, hidden, vis);
+    document.body.appendChild(parent);
+    const patches = resolveZOrderPatches(target, "bring-forward");
+    expect(patchFor(patches, { target, hidden, vis }, "target")?.zIndex).toBe(4);
+    expect(patchFor(patches, { target, hidden, vis }, "hidden")).toBeUndefined();
+  });
+});
+
+// ── resolveCrossedNeighbor (the "show your work" flash target) ────────────────
+
+describe("resolveCrossedNeighbor", () => {
+  it("returns the visible sibling directly above for bring-forward", () => {
+    const { target, byId } = makeFamily("1", [
+      ["hidden", "2"],
+      ["vis", "3"],
+    ]);
+    const opts = { isVisible: (el: HTMLElement) => el !== byId.hidden };
+    expect(resolveCrossedNeighbor(target, "bring-forward", opts)).toBe(byId.vis);
+  });
+
+  it("returns the visible sibling directly below for send-backward", () => {
+    const { target, byId } = makeFamily("3", [
+      ["vis", "1"],
+      ["hidden", "2"],
+    ]);
+    const opts = { isVisible: (el: HTMLElement) => el !== byId.hidden };
+    expect(resolveCrossedNeighbor(target, "send-backward", opts)).toBe(byId.vis);
+  });
+
+  it("returns null for front/back actions and for no-op steps", () => {
+    const { target } = makeFamily("1", [["a", "2"]]);
+    expect(resolveCrossedNeighbor(target, "bring-to-front")).toBeNull();
+    expect(resolveCrossedNeighbor(target, "send-to-back")).toBeNull();
+    expect(resolveCrossedNeighbor(target, "send-backward")).toBeNull(); // already bottom
+    const { target: top } = makeFamily("5", [["a", "2"]]);
+    expect(resolveCrossedNeighbor(top, "bring-forward")).toBeNull(); // already top
+  });
+
+  it("returns null when there are no siblings", () => {
+    const solo = makeEl("solo", "1");
+    document.createElement("div").appendChild(solo);
+    expect(resolveCrossedNeighbor(solo, "bring-forward")).toBeNull();
+  });
+});
+
 // ── isZOrderActionEnabled ─────────────────────────────────────────────────────
 
 describe("isZOrderActionEnabled", () => {

package/src/components/editor/canvasContextMenuZOrder.ts

@@ -7,8 +7,23 @@
  * the computed value. Treat missing / "auto" as 0 for comparison purposes.
  *
  * "Overlapping siblings" = siblings whose bounding rects intersect the
- * target's bounding rect. Forward/backward operate within that set;
- * front/back operate across all siblings.
+ * target's bounding rect AND are actually visible at the current frame.
+ * Forward/backward operate within that set; front/back operate across all
+ * siblings (full painting family, visible or not — unchanged semantics).
+ *
+ * ── Visibility ───────────────────────────────────────────────────────────────
+ * In HyperFrames compositions the nearest z-neighbor is often INVISIBLE at the
+ * paused frame: the runtime hides time-inactive clips with inline
+ * `visibility:hidden` / `display:none` (see core runtime
+ * syncTimedElementVisibility), and GSAP timelines park elements at `opacity:0`.
+ * Stepping "forward" over such a sibling looks like a silent no-op. The
+ * forward/backward comparison set therefore keeps only siblings whose
+ * element-level computed style is visible (display ≠ none, visibility ≠
+ * hidden, opacity > 0.01) — all runtime hiding signals are inline styles, so
+ * computed style covers them. Ancestor-chain checks are unnecessary here:
+ * siblings share the target's ancestors. The probe is injectable
+ * (ZOrderResolveOptions.isVisible) so the pure-module tests stay meaningful
+ * without a real style engine, mirroring how tests stub rect reading.
  *
  * ── Tie-awareness ────────────────────────────────────────────────────────────
  * CSS paint order for elements that share a z-index is DOM document order:
@@ -26,6 +41,8 @@
  * (project convention clamps z ≥ 0).
  */
 
+import { COLOR_GRADING_SOURCE_HIDDEN_ATTR } from "@hyperframes/core/color-grading";
+
 export type ZOrderAction = "bring-forward" | "send-backward" | "bring-to-front" | "send-to-back";
 
 /** A resolved change: set `element`'s z-index to `zIndex`. */
@@ -34,6 +51,48 @@ export interface ZOrderPatch {
   zIndex: number;
 }
 
+/** Injectable knobs for the pure resolver (kept mockable like rect reading). */
+export interface ZOrderResolveOptions {
+  /**
+   * Element-level visibility probe used to scope the forward/backward
+   * comparison set. Defaults to `isElementVisibleForZOrder` (computed-style
+   * display/visibility/opacity). Injectable so tests can run without a real
+   * style engine.
+   */
+  isVisible?: (el: HTMLElement) => boolean;
+}
+
+/**
+ * Default visibility probe: is this element itself visible at the current
+ * frame? Element-level only (siblings share the target's ancestor chain).
+ * Covers the runtime's inactive-clip hiding (inline `visibility:hidden` /
+ * `display:none`) and animation-parked `opacity:0`, all of which surface
+ * through computed style. A color-grading source (hidden at opacity:0 while
+ * its canvas paints in its place) still counts as visible, matching
+ * isElementVisibleThroughAncestors in domEditingDom.
+ */
+export function isElementVisibleForZOrder(el: HTMLElement): boolean {
+  try {
+    const win = el.ownerDocument?.defaultView;
+    if (!win) return true;
+    const computed = win.getComputedStyle(el);
+    if (computed.display === "none") return false;
+    if (computed.visibility === "hidden" || computed.visibility === "collapse") return false;
+    const opacity = Number.parseFloat(computed.opacity);
+    if (
+      Number.isFinite(opacity) &&
+      opacity <= 0.01 &&
+      !el.hasAttribute(COLOR_GRADING_SOURCE_HIDDEN_ATTR)
+    ) {
+      return false;
+    }
+    return true;
+  } catch {
+    /* cross-origin / detached — assume visible (fail open, matches rect fallback) */
+    return true;
+  }
+}
+
 interface RenderEntry {
   element: HTMLElement;
   zIndex: number;
@@ -81,8 +140,18 @@ function isElementNode(node: Node): node is HTMLElement {
  * z-index onto the qa-clean audio element, and counting it as a sibling skews the
  * renumber for the visible elements. `<script>/<style>/<link>/<meta>` are also
  * non-painting and could otherwise pad the family / eat a z slot.
+ * `<template>/<noscript>` never paint either — letting them in meant renumber
+ * fallbacks wrote z-index/position into template source markup.
  */
-const NON_PAINTING_TAGS = new Set(["AUDIO", "SCRIPT", "STYLE", "LINK", "META"]);
+const NON_PAINTING_TAGS = new Set([
+  "AUDIO",
+  "SCRIPT",
+  "STYLE",
+  "LINK",
+  "META",
+  "TEMPLATE",
+  "NOSCRIPT",
+]);
 
 /** A painting element: an element node whose tag actually renders pixels. */
 function isPaintingElement(node: Node): node is HTMLElement {
@@ -112,7 +181,7 @@ function getFamily(target: HTMLElement): { entries: RenderEntry[]; targetIndex:
   return { entries, targetIndex };
 }
 
-/** True if two DOM bounding rects intersect (even if touching). */
+/** True if two DOM bounding rects strictly overlap (rects that merely touch do NOT intersect). */
 function rectsIntersect(
   a: { left: number; top: number; right: number; bottom: number },
   b: { left: number; top: number; right: number; bottom: number },
@@ -121,26 +190,35 @@ function rectsIntersect(
 }
 
 /**
- * Restrict a family to the target plus siblings whose bounding rect overlaps
- * the target's rect. The target is always retained. If the target's rect is
- * unavailable or empty (headless / happy-dom returns 0×0), all entries are
- * kept — matching the prior behavior.
+ * Restrict a family to the target plus siblings that are VISIBLE and whose
+ * bounding rect overlaps the target's rect. The target is always retained
+ * (even when itself hidden at the current frame — it is the user's explicit
+ * selection). If the target's rect is unavailable or empty (headless /
+ * happy-dom returns 0×0), the overlap filter is skipped and all VISIBLE
+ * entries are kept — matching the prior rect-fallback behavior.
  */
-function getOverlappingFamily(target: HTMLElement, entries: RenderEntry[]): RenderEntry[] {
+function getOverlappingFamily(
+  target: HTMLElement,
+  entries: RenderEntry[],
+  isVisible: (el: HTMLElement) => boolean,
+): RenderEntry[] {
+  const visibleEntries = entries.filter(
+    (entry) => entry.element === target || isVisible(entry.element),
+  );
   let targetRect: DOMRect;
   try {
     targetRect = target.getBoundingClientRect();
   } catch {
-    return entries;
+    return visibleEntries;
   }
-  if (targetRect.width === 0 && targetRect.height === 0) return entries;
+  if (targetRect.width === 0 && targetRect.height === 0) return visibleEntries;
   const tr = {
     left: targetRect.left,
     top: targetRect.top,
     right: targetRect.right,
     bottom: targetRect.bottom,
   };
-  return entries.filter((entry) => {
+  return visibleEntries.filter((entry) => {
     if (entry.element === target) return true;
     try {
       const r = entry.element.getBoundingClientRect();
@@ -296,28 +374,46 @@ function buildGlobalOrder(
 }
 
 /**
- * Resolve the z-order patches for an action.
- *
- * Returns null when the action is a no-op (target already at the relevant
- * end of its set), otherwise the minimal list of {element, zIndex} changes.
+ * The shared scoping pipeline: full painting family for front/back, visible
+ * overlapping siblings for forward/backward, sorted into render order with the
+ * target's position. Null when the family/scope is too small to act on.
  */
-export function resolveZOrderChange(
+function resolveScopedRenderOrder(
   target: HTMLElement,
   action: ZOrderAction,
-): ZOrderPatch[] | null {
+  options?: ZOrderResolveOptions,
+): { entries: RenderEntry[]; order: RenderEntry[]; pos: number } | null {
   const { entries } = getFamily(target);
   // Family always includes the target; fewer than 2 means no siblings at all.
   if (entries.length < 2) return null;
 
+  const isVisible = options?.isVisible ?? isElementVisibleForZOrder;
   const scoped =
     action === "bring-to-front" || action === "send-to-back"
       ? entries
-      : getOverlappingFamily(target, entries);
+      : getOverlappingFamily(target, entries, isVisible);
   if (scoped.length < 2) return null;
 
   const order = toRenderOrder(scoped);
   const pos = order.findIndex((e) => e.element === target);
   if (pos === -1) return null;
+  return { entries, order, pos };
+}
+
+/**
+ * Resolve the z-order patches for an action.
+ *
+ * Returns null when the action is a no-op (target already at the relevant
+ * end of its set), otherwise the minimal list of {element, zIndex} changes.
+ */
+export function resolveZOrderChange(
+  target: HTMLElement,
+  action: ZOrderAction,
+  options?: ZOrderResolveOptions,
+): ZOrderPatch[] | null {
+  const resolved = resolveScopedRenderOrder(target, action, options);
+  if (!resolved) return null;
+  const { entries, order, pos } = resolved;
 
   const desired = [...order];
   const [moved] = desired.splice(pos, 1);
@@ -343,10 +439,36 @@ export function resolveZOrderChange(
   return realizeOrder(order, desired, target, entries);
 }
 
+/**
+ * The sibling a forward/backward step crosses: the visible overlapping
+ * neighbor directly above (bring-forward) or below (send-backward) the target
+ * in render order. Null for front/back, for a no-op step, or when the scope is
+ * too small. Uses the SAME scoping as resolveZOrderChange, so call it with the
+ * same options BEFORE any live styles are applied.
+ */
+export function resolveCrossedNeighbor(
+  target: HTMLElement,
+  action: ZOrderAction,
+  options?: ZOrderResolveOptions,
+): HTMLElement | null {
+  if (action !== "bring-forward" && action !== "send-backward") return null;
+  const resolved = resolveScopedRenderOrder(target, action, options);
+  if (!resolved) return null;
+  const { order, pos } = resolved;
+  const neighbor = action === "bring-forward" ? order[pos + 1] : order[pos - 1];
+  return neighbor?.element ?? null;
+}
+
 /**
  * Whether a z-order action is available for the target.
- * "disabled" = the element is already at that limit.
+ * "disabled" = the element is already at that limit. Shares the resolver (and
+ * its visibility scoping), so enable/disable always matches what the action
+ * would actually do.
  */
-export function isZOrderActionEnabled(target: HTMLElement, action: ZOrderAction): boolean {
-  return resolveZOrderChange(target, action) !== null;
+export function isZOrderActionEnabled(
+  target: HTMLElement,
+  action: ZOrderAction,
+  options?: ZOrderResolveOptions,
+): boolean {
+  return resolveZOrderChange(target, action, options) !== null;
 }

package/src/components/editor/propertyPanelColorGradingSection.tsx

@@ -24,6 +24,10 @@ import type { DomEditSelection } from "./domEditing";
 import { ColorGradingControls } from "./propertyPanelColorGradingControls";
 import { stripQueryAndHash } from "./propertyPanelHelpers";
 import { Section } from "./propertyPanelPrimitives";
+import {
+  acceptStudioRuntimeMessage,
+  postRuntimeControlMessage,
+} from "../../player/lib/runtimeProtocol";
 
 const COLOR_GRADING_DATA_KEY = HF_COLOR_GRADING_ATTR.replace(/^data-/, "");
 const RUNTIME_STATUS_REFRESH_DELAYS = [50, 250, 1000, 2500] as const;
@@ -393,35 +397,23 @@ export function ColorGradingSection({
 
   const postColorGrading = useCallback(
     (nextGrading: NormalizedHfColorGrading) => {
-      previewIframeRef?.current?.contentWindow?.postMessage(
-        {
-          source: "hf-parent",
-          type: "control",
-          action: "set-color-grading",
-          target,
-          grading: toBridgeColorGrading(nextGrading),
-        },
-        "*",
-      );
+      postRuntimeControlMessage(previewIframeRef?.current?.contentWindow, "set-color-grading", {
+        target,
+        grading: toBridgeColorGrading(nextGrading),
+      });
     },
     [previewIframeRef, target],
   );
 
   const postCompare = useCallback(
     (enabled: boolean) => {
-      previewIframeRef?.current?.contentWindow?.postMessage(
+      postRuntimeControlMessage(
+        previewIframeRef?.current?.contentWindow,
+        "set-color-grading-compare",
         {
-          source: "hf-parent",
-          type: "control",
-          action: "set-color-grading-compare",
           target,
-          compare: {
-            enabled,
-            position: 1,
-            lineWidth: 0,
-          },
+          compare: { enabled, position: 1, lineWidth: 0 },
         },
-        "*",
       );
     },
     [previewIframeRef, target],
@@ -440,7 +432,9 @@ export function ColorGradingSection({
     const onMessage = (event: MessageEvent) => {
       if (event.source !== iframe.contentWindow) return;
       const data = event.data as { source?: unknown; type?: unknown } | null;
-      if (data?.source === "hf-preview" && data.type === "ready") refreshAndReplay();
+      if (data?.source !== "hf-preview" || data.type !== "ready") return;
+      if (!acceptStudioRuntimeMessage(data)) return;
+      refreshAndReplay();
     };
     iframe.addEventListener("load", refreshAndReplay);
     window.addEventListener("message", onMessage);

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 };
+}