@hyperframes/studio 0.7.56 → 0.7.58

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

@@ -0,0 +1,169 @@
+// @vitest-environment jsdom
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  LAYER_REVEAL_LIFT_Z,
+  LAYER_REVEAL_PENDING_COMMIT_ATTR,
+  beginLayerRevealCommit,
+  completeLayerRevealCommit,
+  liftElementToTop,
+  restoreLiftedElement,
+  useLayerRevealOverride,
+} from "./useLayerRevealOverride";
+import { readEffectiveZIndex } from "./canvasContextMenuZOrder";
+import { getElementZIndex } from "../../player/lib/layerOrdering";
+import {
+  LAYER_REVEAL_PRIOR_Z_ATTR,
+  readTimelineElementZIndex,
+} from "../../player/lib/timelineElementHelpers";
+import { installReactActEnvironment } from "../../hooks/domSelectionTestHarness";
+
+installReactActEnvironment();
+
+function makeEl(zIndex?: string, position?: string): HTMLElement {
+  const el = document.createElement("div");
+  if (zIndex != null) el.style.zIndex = zIndex;
+  if (position != null) el.style.position = position;
+  document.body.appendChild(el);
+  return el;
+}
+
+describe("liftElementToTop / restoreLiftedElement", () => {
+  it("paints on top but every z reader keeps reporting the TRUE z", () => {
+    const el = makeEl("6", "absolute");
+    const lift = liftElementToTop(el);
+    expect(lift).not.toBeNull();
+    // The renderer sees the lifted value…
+    expect(el.style.zIndex).toBe(LAYER_REVEAL_LIFT_Z);
+    // …every studio reader sees the true z.
+    expect(readEffectiveZIndex(el)).toBe(6);
+    expect(getElementZIndex(el)).toBe(6);
+    expect(readTimelineElementZIndex(el)).toBe(6);
+
+    restoreLiftedElement(el, lift!);
+    expect(el.style.zIndex).toBe("6");
+    expect(el.hasAttribute(LAYER_REVEAL_PRIOR_Z_ATTR)).toBe(false);
+  });
+
+  it("gives a static element a temporary position:relative and restores it", () => {
+    const el = makeEl();
+    const lift = liftElementToTop(el)!;
+    expect(el.style.position).toBe("relative");
+    expect(lift.positionLifted).toBe(true);
+    restoreLiftedElement(el, lift);
+    expect(el.style.position).toBe("");
+    expect(el.style.zIndex).toBe("");
+  });
+
+  it("a z-reorder commit consumes the lift: restore becomes a no-op", () => {
+    const el = makeEl("3", "absolute");
+    const lift = liftElementToTop(el)!;
+    // Simulate handleDomZIndexReorderCommit: real z written, attrs removed.
+    el.removeAttribute(LAYER_REVEAL_PRIOR_Z_ATTR);
+    el.style.zIndex = "8";
+    restoreLiftedElement(el, lift);
+    expect(el.style.zIndex).toBe("8"); // the commit's value survives
+    expect(readEffectiveZIndex(el)).toBe(8);
+  });
+
+  it("durable z persistence consumes its pending reveal ownership", () => {
+    const el = makeEl("3", "absolute");
+    const lift = liftElementToTop(el)!;
+    const ownership = beginLayerRevealCommit(el)!;
+    el.style.zIndex = "8";
+
+    expect(el.hasAttribute(LAYER_REVEAL_PENDING_COMMIT_ATTR)).toBe(true);
+    completeLayerRevealCommit(el, ownership);
+    restoreLiftedElement(el, lift);
+
+    expect(el.style.zIndex).toBe("8");
+    expect(el.hasAttribute(LAYER_REVEAL_PENDING_COMMIT_ATTR)).toBe(false);
+    expect(el.hasAttribute(LAYER_REVEAL_PRIOR_Z_ATTR)).toBe(false);
+  });
+
+  it("does not clobber a z someone else wrote while lifted", () => {
+    const el = makeEl("3", "absolute");
+    const lift = liftElementToTop(el)!;
+    el.style.zIndex = "42"; // e.g. a GSAP seek or manual edit
+    restoreLiftedElement(el, lift);
+    expect(el.style.zIndex).toBe("42");
+  });
+});
+
+describe("useLayerRevealOverride — delayed reveal ownership", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    document.body.innerHTML = "";
+  });
+
+  it("cancels a pending reveal when selection changes or playback begins", () => {
+    const host = document.createElement("div");
+    const selected = makeEl("2", "absolute");
+    const other = makeEl("3", "absolute");
+    document.body.appendChild(host);
+    const root = createRoot(host);
+    let scheduleReveal: ((element: HTMLElement, delayMs: number) => void) | undefined;
+
+    function Harness({ element, isPlaying }: { element: HTMLElement; isPlaying: boolean }) {
+      ({ scheduleReveal } = useLayerRevealOverride({
+        isPlaying,
+        selectedElement: element,
+      }));
+      return null;
+    }
+
+    act(() => {
+      root.render(React.createElement(Harness, { element: selected, isPlaying: false }));
+    });
+    act(() => scheduleReveal!(selected, 150));
+    expect(vi.getTimerCount()).toBe(1);
+
+    act(() => {
+      root.render(React.createElement(Harness, { element: other, isPlaying: false }));
+    });
+    expect(vi.getTimerCount()).toBe(0);
+
+    act(() => scheduleReveal!(other, 150));
+    expect(vi.getTimerCount()).toBe(1);
+    act(() => {
+      root.render(React.createElement(Harness, { element: other, isPlaying: true }));
+    });
+    expect(vi.getTimerCount()).toBe(0);
+
+    act(() => vi.advanceTimersByTime(150));
+    expect(selected.style.zIndex).toBe("2");
+    expect(other.style.zIndex).toBe("3");
+    act(() => root.unmount());
+  });
+
+  it("revalidates the current selection before a delayed reveal runs", () => {
+    const host = document.createElement("div");
+    const selected = makeEl("2", "absolute");
+    const stale = makeEl("3", "absolute");
+    document.body.appendChild(host);
+    const root = createRoot(host);
+    let scheduleReveal: ((element: HTMLElement, delayMs: number) => void) | undefined;
+
+    function Harness() {
+      ({ scheduleReveal } = useLayerRevealOverride({
+        isPlaying: false,
+        selectedElement: selected,
+      }));
+      return null;
+    }
+
+    act(() => root.render(React.createElement(Harness)));
+    act(() => scheduleReveal!(stale, 150));
+    expect(vi.getTimerCount()).toBe(1);
+    act(() => vi.advanceTimersByTime(150));
+
+    expect(stale.style.zIndex).toBe("3");
+    expect(stale.hasAttribute(LAYER_REVEAL_PRIOR_Z_ATTR)).toBe(false);
+    act(() => root.unmount());
+  });
+});

package/src/components/editor/useLayerRevealOverride.ts

@@ -0,0 +1,389 @@
+import { useCallback, useEffect, useRef } from "react";
+import {
+  LAYER_REVEAL_PRIOR_POSITION_ATTR,
+  LAYER_REVEAL_PRIOR_Z_ATTR,
+} from "../../player/lib/timelineElementHelpers";
+import { readEffectiveZIndex } from "./canvasContextMenuZOrder";
+
+/** The lifted paint order — far above any authored z. Only the RENDERER sees
+ *  it: every studio z reader is reveal-transparent (readLayerRevealPriorZ). */
+export const LAYER_REVEAL_LIFT_Z = "2147483000";
+export const LAYER_REVEAL_PENDING_COMMIT_ATTR = "data-hf-studio-reveal-pending-commit";
+
+interface RevealedNode {
+  element: HTMLElement;
+  priors: { display: string; visibility: string; opacity: string };
+  /** Values THIS override wrote — restore only while they are still in place. */
+  applied: { display?: string; visibility?: string; opacity?: string };
+}
+
+interface RevealLift {
+  priors: { zIndex: string; position: string };
+  positionLifted: boolean;
+}
+
+type PendingRevealCommit = {
+  token: string;
+  releasedPriors?: RevealLift["priors"];
+};
+
+export type LayerRevealCommitOwnership = {
+  token: string;
+  priorZ: string;
+  priorPosition: string | null;
+  activeLiftStyles: RevealLift["priors"];
+};
+
+let revealCommitSequence = 0;
+const zPersistCounts = new WeakMap<HTMLElement, number>();
+const REVEAL_RETRY_MS = 16;
+
+/** Prevent delayed reveals from capturing an optimistic z as authored state. */
+export function beginLayerZPersist(element: HTMLElement): () => void {
+  zPersistCounts.set(element, (zPersistCounts.get(element) ?? 0) + 1);
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    const remaining = (zPersistCounts.get(element) ?? 1) - 1;
+    if (remaining > 0) zPersistCounts.set(element, remaining);
+    else zPersistCounts.delete(element);
+  };
+}
+
+interface RevealState {
+  /** The layer element the reveal was applied for (deselect detection). */
+  base: HTMLElement;
+  nodes: RevealedNode[];
+  lift: RevealLift | null;
+}
+
+function restoreInline(el: HTMLElement, property: string, prior: string): void {
+  if (prior) el.style.setProperty(property, prior);
+  else el.style.removeProperty(property);
+}
+
+// This decoder owns the complete serialized reveal-commit schema. Splitting
+// field checks across helpers would create multiple authorities for validity.
+// fallow-ignore-next-line complexity
+function readPendingRevealCommit(element: HTMLElement): PendingRevealCommit | null {
+  const raw = element.getAttribute(LAYER_REVEAL_PENDING_COMMIT_ATTR);
+  if (!raw) return null;
+  try {
+    const value: unknown = JSON.parse(raw);
+    if (typeof value !== "object" || value === null || !("token" in value)) return null;
+    const token = value.token;
+    if (typeof token !== "string") return null;
+    if (!("releasedPriors" in value) || value.releasedPriors === undefined) return { token };
+    const releasedPriors = value.releasedPriors;
+    if (
+      typeof releasedPriors !== "object" ||
+      releasedPriors === null ||
+      !("zIndex" in releasedPriors) ||
+      !("position" in releasedPriors)
+    ) {
+      return null;
+    }
+    const { zIndex, position } = releasedPriors;
+    return typeof zIndex === "string" && typeof position === "string"
+      ? { token, releasedPriors: { zIndex, position } }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function writePendingRevealCommit(element: HTMLElement, state: PendingRevealCommit): void {
+  element.setAttribute(LAYER_REVEAL_PENDING_COMMIT_ATTR, JSON.stringify(state));
+}
+
+/** Hand an active reveal lift to one pending durable z commit. */
+export function beginLayerRevealCommit(element: HTMLElement): LayerRevealCommitOwnership | null {
+  const priorZ = element.getAttribute(LAYER_REVEAL_PRIOR_Z_ATTR);
+  if (priorZ == null) return null;
+  const ownership = {
+    token: `reveal-z-${revealCommitSequence++}`,
+    priorZ,
+    priorPosition: element.getAttribute(LAYER_REVEAL_PRIOR_POSITION_ATTR),
+    activeLiftStyles: { zIndex: element.style.zIndex, position: element.style.position },
+  };
+  writePendingRevealCommit(element, { token: ownership.token });
+  element.removeAttribute(LAYER_REVEAL_PRIOR_Z_ATTR);
+  element.removeAttribute(LAYER_REVEAL_PRIOR_POSITION_ATTR);
+  return ownership;
+}
+
+/** Durable success consumes the reveal regardless of whether selection released it meanwhile. */
+export function completeLayerRevealCommit(
+  element: HTMLElement,
+  ownership: LayerRevealCommitOwnership,
+): void {
+  if (readPendingRevealCommit(element)?.token === ownership.token) {
+    element.removeAttribute(LAYER_REVEAL_PENDING_COMMIT_ATTR);
+  }
+}
+
+/**
+ * Roll back only the reveal transaction this commit owns. An active reveal gets
+ * its temporary lift back; a reveal released while persistence was pending gets
+ * its exact authored inline styles back, with no resurrected metadata.
+ */
+export function rollbackLayerRevealCommit(
+  element: HTMLElement,
+  ownership: LayerRevealCommitOwnership,
+): void {
+  const pending = readPendingRevealCommit(element);
+  if (pending?.token !== ownership.token) return;
+  element.removeAttribute(LAYER_REVEAL_PENDING_COMMIT_ATTR);
+  element.removeAttribute(LAYER_REVEAL_PRIOR_Z_ATTR);
+  element.removeAttribute(LAYER_REVEAL_PRIOR_POSITION_ATTR);
+  if (pending.releasedPriors) {
+    restoreInline(element, "z-index", pending.releasedPriors.zIndex);
+    restoreInline(element, "position", pending.releasedPriors.position);
+    return;
+  }
+  restoreInline(element, "z-index", ownership.activeLiftStyles.zIndex);
+  restoreInline(element, "position", ownership.activeLiftStyles.position);
+  element.setAttribute(LAYER_REVEAL_PRIOR_Z_ATTR, ownership.priorZ);
+  if (ownership.priorPosition != null) {
+    element.setAttribute(LAYER_REVEAL_PRIOR_POSITION_ATTR, ownership.priorPosition);
+  }
+}
+
+/** Restore a property ONLY when its current inline value is still the one this
+ *  override wrote — a later real edit (commit, animation seek) is the new
+ *  truth and must not be clobbered. */
+function restoreIfOurs(
+  el: HTMLElement,
+  property: "display" | "visibility" | "opacity",
+  applied: string | undefined,
+  prior: string,
+): void {
+  if (applied == null) return;
+  if (el.style.getPropertyValue(property) !== applied) return;
+  restoreInline(el, property, prior);
+}
+
+/** What hides this node at the current frame, per computed style. */
+function readHideSignals(el: HTMLElement, win: Window) {
+  const computed = win.getComputedStyle(el);
+  const opacity = Number.parseFloat(computed.opacity);
+  return {
+    display: computed.display === "none",
+    visibility: computed.visibility === "hidden" || computed.visibility === "collapse",
+    opacity: Number.isFinite(opacity) && opacity <= 0.01,
+  };
+}
+
+/** Force one hidden node visible with inline styles; returns priors + applied. */
+function revealNode(
+  el: HTMLElement,
+  win: Window,
+  needs: ReturnType<typeof readHideSignals>,
+): RevealedNode {
+  const priors = {
+    display: el.style.display,
+    visibility: el.style.visibility,
+    opacity: el.style.opacity,
+  };
+  const applied: RevealedNode["applied"] = {};
+  if (needs.display) {
+    // Prefer whatever the stylesheet says once the inline hide is lifted;
+    // only force block when the sheet itself hides it.
+    el.style.removeProperty("display");
+    if (win.getComputedStyle(el).display === "none") el.style.display = "block";
+    applied.display = el.style.display;
+  }
+  if (needs.visibility) {
+    el.style.visibility = "visible";
+    applied.visibility = "visible";
+  }
+  if (needs.opacity) {
+    el.style.opacity = "1";
+    applied.opacity = "1";
+  }
+  return { element: el, priors, applied };
+}
+
+/** Walk `element` → body, force-revealing every hiding node; returns the touched nodes. */
+function revealHiddenChain(element: HTMLElement): RevealedNode[] {
+  const doc = element.ownerDocument;
+  const win = doc.defaultView;
+  if (!win) return [];
+  const nodes: RevealedNode[] = [];
+  let el: HTMLElement | null = element;
+  while (el && el !== doc.body && el !== doc.documentElement) {
+    let needs: ReturnType<typeof readHideSignals>;
+    try {
+      needs = readHideSignals(el, win);
+    } catch {
+      break; // detached / cross-realm — leave the rest alone
+    }
+    if (needs.display || needs.visibility || needs.opacity) nodes.push(revealNode(el, win, needs));
+    el = el.parentElement;
+  }
+  return nodes;
+}
+
+/**
+ * Lift the selected element to the TOP of the paint order while selected —
+ * regardless of its authored z or panel position. The true z is parked in
+ * LAYER_REVEAL_PRIOR_Z_ATTR so every studio z reader keeps reporting it (the
+ * lift is invisible to menus, badges, the lane mirror, and the panel sort);
+ * only the renderer sees the lifted inline value. A static element gets a
+ * temporary position:relative (layout-preserving) so the z applies, with the
+ * prior position parked in LAYER_REVEAL_PRIOR_POSITION_ATTR for the z-commit's
+ * static check. Exported for direct unit testing.
+ */
+export function liftElementToTop(element: HTMLElement): RevealLift | null {
+  const win = element.ownerDocument.defaultView;
+  if (!win) return null;
+  const priors = { zIndex: element.style.zIndex, position: element.style.position };
+  let positionLifted = false;
+  try {
+    element.setAttribute(LAYER_REVEAL_PRIOR_Z_ATTR, String(readEffectiveZIndex(element)));
+    if (win.getComputedStyle(element).position === "static") {
+      element.setAttribute(LAYER_REVEAL_PRIOR_POSITION_ATTR, "static");
+      element.style.position = "relative";
+      positionLifted = true;
+    }
+  } catch {
+    element.removeAttribute(LAYER_REVEAL_PRIOR_Z_ATTR);
+    return null; // detached / cross-realm — no lift
+  }
+  element.style.zIndex = LAYER_REVEAL_LIFT_Z;
+  return { priors, positionLifted };
+}
+
+/**
+ * Undo an active lift. Skipped entirely when the prior-z attribute is gone —
+ * a z-reorder commit consumed the lift (handleDomZIndexReorderCommit removes
+ * the attributes and writes the new real z), and that commit is the truth.
+ * Exported for direct unit testing.
+ */
+export function restoreLiftedElement(element: HTMLElement, lift: RevealLift): void {
+  if (!element.hasAttribute(LAYER_REVEAL_PRIOR_Z_ATTR)) {
+    const pending = readPendingRevealCommit(element);
+    if (pending && !pending.releasedPriors) {
+      // Persistence temporarily owns the live z. Hand it the exact authored
+      // priors so a later rejection can restore them after this hook lets go.
+      writePendingRevealCommit(element, { ...pending, releasedPriors: lift.priors });
+    }
+    return;
+  }
+  element.removeAttribute(LAYER_REVEAL_PRIOR_Z_ATTR);
+  element.removeAttribute(LAYER_REVEAL_PRIOR_POSITION_ATTR);
+  if (element.style.zIndex === LAYER_REVEAL_LIFT_Z) {
+    restoreInline(element, "z-index", lift.priors.zIndex);
+  }
+  if (lift.positionLifted && element.style.position === "relative") {
+    restoreInline(element, "position", lift.priors.position);
+  }
+}
+
+/**
+ * Temporary "show me this element" override for the Layers panel
+ * (Webflow-navigator style): clicking a layer forces it (and every hiding
+ * ancestor up to the body) visible with LIVE inline styles, and paints it on
+ * TOP of the stack while selected (see liftElementToTop).
+ *
+ * Strictly ephemeral by construction:
+ * - Exact prior inline values are recorded per touched node and restored on
+ *   every exit path — reveal of a different layer, deselect, playback start,
+ *   unmount. Nothing is ever sent to a persist path, and each property is
+ *   restored only while it still holds the value this override wrote.
+ * - A post-edit iframe reload replaces the DOM; detached nodes are skipped on
+ *   restore (the fresh document never had the override).
+ * - Scrubbing/playing lets the runtime and GSAP rewrite these same inline
+ *   styles — that is the animation showing reality, and the override is
+ *   dropped on play for exactly that reason.
+ */
+export function useLayerRevealOverride({
+  isPlaying,
+  selectedElement,
+}: {
+  isPlaying: boolean;
+  selectedElement: HTMLElement | null;
+}): {
+  scheduleReveal: (element: HTMLElement, delayMs: number) => void;
+} {
+  const stateRef = useRef<RevealState | null>(null);
+  const pendingRevealRef = useRef<{ timer: number; element: HTMLElement } | null>(null);
+  const currentRef = useRef({ isPlaying, selectedElement });
+  currentRef.current = { isPlaying, selectedElement };
+
+  const restoreReveal = useCallback(() => {
+    const state = stateRef.current;
+    stateRef.current = null;
+    if (!state) return;
+    for (const { element, priors, applied } of state.nodes) {
+      if (!element.isConnected) continue;
+      restoreIfOurs(element, "display", applied.display, priors.display);
+      restoreIfOurs(element, "visibility", applied.visibility, priors.visibility);
+      restoreIfOurs(element, "opacity", applied.opacity, priors.opacity);
+    }
+    if (state.lift && state.base.isConnected) restoreLiftedElement(state.base, state.lift);
+  }, []);
+
+  const reveal = useCallback(
+    (element: HTMLElement) => {
+      restoreReveal();
+      const nodes = revealHiddenChain(element);
+      const lift = liftElementToTop(element);
+      if (nodes.length > 0 || lift) stateRef.current = { base: element, nodes, lift };
+    },
+    [restoreReveal],
+  );
+
+  const cancelScheduledReveal = useCallback(() => {
+    const pending = pendingRevealRef.current;
+    pendingRevealRef.current = null;
+    if (pending) window.clearTimeout(pending.timer);
+  }, []);
+
+  const scheduleReveal = useCallback(
+    (element: HTMLElement, delayMs: number) => {
+      cancelScheduledReveal();
+      const current = currentRef.current;
+      if (current.isPlaying) return;
+      const attemptReveal = () => {
+        const latest = currentRef.current;
+        if (latest.isPlaying || latest.selectedElement !== element || !element.isConnected) {
+          pendingRevealRef.current = null;
+          return;
+        }
+        if (zPersistCounts.has(element)) {
+          const timer = window.setTimeout(attemptReveal, REVEAL_RETRY_MS);
+          pendingRevealRef.current = { timer, element };
+          return;
+        }
+        pendingRevealRef.current = null;
+        reveal(element);
+      };
+      const timer = window.setTimeout(attemptReveal, delayMs);
+      pendingRevealRef.current = { timer, element };
+    },
+    [cancelScheduledReveal, reveal],
+  );
+
+  // Selection and playback jointly own eligibility for both pending and active
+  // reveals. Cancel first; playback or a different selection then restores the
+  // animation/authored styles.
+  useEffect(() => {
+    const pending = pendingRevealRef.current;
+    if (isPlaying || (pending && pending.element !== selectedElement)) cancelScheduledReveal();
+    const base = stateRef.current?.base;
+    if (isPlaying || (base && selectedElement !== base)) restoreReveal();
+  }, [cancelScheduledReveal, isPlaying, restoreReveal, selectedElement]);
+
+  // Unmount: never leave a timer or override behind.
+  useEffect(
+    () => () => {
+      cancelScheduledReveal();
+      restoreReveal();
+    },
+    [cancelScheduledReveal, restoreReveal],
+  );
+
+  return { scheduleReveal };
+}

package/src/components/editor/useZOrderCrossedFlash.tsx

@@ -0,0 +1,68 @@
+/**
+ * Z-order "show your work" flash: after a bring-forward / send-backward, the
+ * sibling that was stepped over gets a brief (600ms) highlight so the action
+ * is legible even when the visual change is subtle.
+ *
+ * Drawn in the STUDIO's own overlay layer above the preview iframe — nothing
+ * is written into the iframe DOM or the composition, so a concurrent preview
+ * reload can never leave a stuck highlight; the timeout merely clears
+ * studio-local state. The crossed element is resolved by the context menu
+ * (resolveCrossedNeighbor) from the same pre-mutation render order as the
+ * z patches; z-index writes don't move layout, so measuring its rect after
+ * the commit applied live styles is still accurate.
+ */
+import { useCallback, useEffect, useRef, useState, type RefObject } from "react";
+import { toVisibleOverlayRect, type OverlayRect } from "./domEditOverlayGeometry";
+
+const Z_ORDER_CROSSED_FLASH_MS = 600;
+
+interface UseZOrderCrossedFlashParams {
+  overlayRef: RefObject<HTMLDivElement | null>;
+  iframeRef: RefObject<HTMLIFrameElement | null>;
+}
+
+export function useZOrderCrossedFlash({ overlayRef, iframeRef }: UseZOrderCrossedFlashParams): {
+  zOrderFlashRect: OverlayRect | null;
+  handleZOrderCrossed: (crossed: HTMLElement) => void;
+} {
+  const [zOrderFlashRect, setZOrderFlashRect] = useState<OverlayRect | null>(null);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(
+    () => () => {
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    },
+    [],
+  );
+
+  const handleZOrderCrossed = useCallback(
+    (crossed: HTMLElement) => {
+      const overlayEl = overlayRef.current;
+      const iframe = iframeRef.current;
+      if (!overlayEl || !iframe) return;
+      const rect = toVisibleOverlayRect(overlayEl, iframe, crossed);
+      if (!rect || rect.width <= 0 || rect.height <= 0) return;
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+      setZOrderFlashRect(rect);
+      timeoutRef.current = setTimeout(() => {
+        timeoutRef.current = null;
+        setZOrderFlashRect(null);
+      }, Z_ORDER_CROSSED_FLASH_MS);
+    },
+    [overlayRef, iframeRef],
+  );
+
+  return { zOrderFlashRect, handleZOrderCrossed };
+}
+
+/** The flash chrome itself — a pulsing accent outline over the crossed sibling. */
+export function ZOrderCrossedFlash({ rect }: { rect: OverlayRect | null }) {
+  if (!rect) return null;
+  return (
+    <div
+      aria-hidden="true"
+      data-dom-edit-z-flash="true"
+      className="pointer-events-none absolute rounded-md border-2 border-studio-accent shadow-[0_0_0_2px_rgba(60,230,172,0.35)] animate-pulse"
+      style={{ left: rect.left, top: rect.top, width: rect.width, height: rect.height }}
+    />
+  );
+}