@hyperframes/studio 0.7.55 → 0.7.57

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

@@ -0,0 +1,214 @@
+// @vitest-environment happy-dom
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { DomEditSelection } from "./domEditing";
+import type { GestureState, UseDomEditOverlayGesturesOptions } from "./domEditOverlayGestures";
+
+// Origin box (overlay px). The gesture-start center is its centroid; the
+// center-anchored resize must keep THIS point planted, which means the release
+// must commit a nonzero offset equal to minus half the size growth.
+const ORIGIN = { left: 0, top: 0, width: 200, height: 100 };
+const ORIGIN_CENTER = {
+  x: ORIGIN.left + ORIGIN.width / 2,
+  y: ORIGIN.top + ORIGIN.height / 2,
+};
+
+// Consistent geometry stub: model the physical truth the real DOM would report.
+// A CSS width/height change grows the box from its top-left, so the rendered
+// center drifts by half the size delta; the manual offset the gesture applies
+// (read back from the element's studio vars) pulls it back. `elementCornerOverlayPoints`
+// returns the four corners of that drifted box; `overlayCornersCentroid` (kept
+// real) averages them so the anchor loop can measure the true center each frame.
+vi.mock("./domEditOverlayGeometry", async () => {
+  const actual = await vi.importActual<typeof import("./domEditOverlayGeometry")>(
+    "./domEditOverlayGeometry",
+  );
+  const { readStudioBoxSize, readStudioPathOffset } = await import("./manualEditsDom");
+  const physicalCenter = (element: HTMLElement) => {
+    const size = readStudioBoxSize(element);
+    const width = size.width > 0 ? size.width : ORIGIN.width;
+    const height = size.height > 0 ? size.height : ORIGIN.height;
+    const offset = readStudioPathOffset(element);
+    return {
+      x: ORIGIN_CENTER.x + (width - ORIGIN.width) / 2 + offset.x,
+      y: ORIGIN_CENTER.y + (height - ORIGIN.height) / 2 + offset.y,
+      width,
+      height,
+    };
+  };
+  return {
+    ...actual,
+    elementCornerOverlayPoints: (_o: unknown, _i: unknown, element: HTMLElement) => {
+      const c = physicalCenter(element);
+      const hw = c.width / 2;
+      const hh = c.height / 2;
+      return {
+        nw: { x: c.x - hw, y: c.y - hh },
+        ne: { x: c.x + hw, y: c.y - hh },
+        sw: { x: c.x - hw, y: c.y + hh },
+        se: { x: c.x + hw, y: c.y + hh },
+      };
+    },
+    orientedOverlayRect: (_o: unknown, _i: unknown, element: HTMLElement) => {
+      const c = physicalCenter(element);
+      return {
+        left: c.x - c.width / 2,
+        top: c.y - c.height / 2,
+        width: c.width,
+        height: c.height,
+        editScaleX: 1,
+        editScaleY: 1,
+        angle: 0,
+      };
+    },
+  };
+});
+
+const { createDomEditOverlayGestureHandlers } = await import("./useDomEditOverlayGestures");
+
+function ref<T>(current: T) {
+  return { current };
+}
+
+interface CommitCall {
+  size: { width: number; height: number };
+  offset: { x: number; y: number } | undefined;
+}
+
+function buildHarness() {
+  const element = document.createElement("div");
+  document.body.append(element);
+
+  const selection = {
+    element,
+    id: "box",
+    selector: "#box",
+    selectorIndex: 0,
+    sourceFile: "index.html",
+    tagName: "div",
+    label: "Box",
+    textContent: "",
+    textFields: [],
+    capabilities: {
+      canEditText: false,
+      canEditLayout: true,
+      canMove: true,
+      canApplyManualOffset: true,
+      canApplyManualSize: true,
+      canApplyManualRotation: false,
+      canAdjustOpacity: true,
+      canAdjustFill: true,
+      canAdjustBorderRadius: true,
+      canAdjustStroke: true,
+      canAdjustShadow: true,
+      canAdjustZIndex: true,
+    },
+    computedStyle: { display: "block", position: "absolute" },
+  } as unknown as DomEditSelection;
+
+  const commits: CommitCall[] = [];
+  const overlayEl = document.createElement("div");
+  const iframe = document.createElement("iframe");
+
+  const opts: UseDomEditOverlayGesturesOptions = {
+    overlayRef: ref<HTMLDivElement | null>(overlayEl),
+    iframeRef: ref<HTMLIFrameElement | null>(iframe),
+    boxRef: ref<HTMLDivElement | null>(document.createElement("div")),
+    selectionRef: ref<DomEditSelection | null>(selection),
+    hoverSelectionRef: ref<DomEditSelection | null>(null),
+    overlayRectRef: ref<OverlayRectLike | null>({
+      left: ORIGIN.left,
+      top: ORIGIN.top,
+      width: ORIGIN.width,
+      height: ORIGIN.height,
+      editScaleX: 1,
+      editScaleY: 1,
+    }) as never,
+    groupOverlayItemsRef: ref([]),
+    gestureRef: ref<GestureState | null>(null),
+    groupGestureRef: ref(null),
+    blockedMoveRef: ref(null),
+    rafPausedRef: ref(false),
+    suppressNextBoxClickRef: ref(false),
+    setOverlayRect: () => {},
+    setGroupOverlayItems: () => {},
+    onBlockedMoveRef: ref(() => {}),
+    onManualDragStartRef: ref(() => {}),
+    onPathOffsetCommitRef: ref(() => {}),
+    onGroupPathOffsetCommitRef: ref(() => {}),
+    onBoxSizeCommitRef: ref((_s, size, offset) => {
+      commits.push({ size, offset });
+    }),
+    onRotationCommitRef: ref(() => {}),
+    onCanvasPointerMoveRef: ref(() => Promise.resolve(null)),
+    onCanvasMouseDown: () => {},
+    snapGuidesRef: ref(null),
+  };
+
+  const handlers = createDomEditOverlayGestureHandlers(opts);
+  return { handlers, commits, selection };
+}
+
+type OverlayRectLike = {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  editScaleX: number;
+  editScaleY: number;
+};
+
+function evt(clientX: number, clientY: number) {
+  return {
+    clientX,
+    clientY,
+    pointerId: 1,
+    button: 0,
+    altKey: false,
+    shiftKey: false,
+    preventDefault() {},
+    stopPropagation() {},
+    currentTarget: { setPointerCapture() {} },
+  } as unknown as React.PointerEvent<HTMLDivElement>;
+}
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+describe("anchored corner resize — the release commit feeds the center-pin offset", () => {
+  it("onPointerUp passes a nonzero offset that keeps the center planted", () => {
+    const { handlers, commits } = buildHarness();
+
+    // Start an SE corner resize. Pointer starts 100px right of the center.
+    handlers.startGesture("resize", evt(ORIGIN_CENTER.x + 100, ORIGIN_CENTER.y), {
+      resizeHandle: "se",
+    });
+
+    // Drag outward to radial scale 1.5 (dist 150 / 100). Several frames so the
+    // per-frame center-pin anchor accumulates and converges into g.lastResizeAnchor.
+    for (let i = 0; i < 5; i++) {
+      handlers.onPointerMove(evt(ORIGIN_CENTER.x + 150, ORIGIN_CENTER.y));
+    }
+
+    handlers.onPointerUp(evt(ORIGIN_CENTER.x + 150, ORIGIN_CENTER.y));
+
+    expect(commits).toHaveLength(1);
+    const { size, offset } = commits[0]!;
+
+    // Proportional 1.5x growth of the 200x100 base.
+    expect(size.width).toBeCloseTo(300, 0);
+    expect(size.height).toBeCloseTo(150, 0);
+
+    // The committed offset must be present and nonzero — the open question.
+    expect(offset).toBeDefined();
+    if (!offset) return;
+    expect(offset.x).not.toBe(0);
+    expect(offset.y).not.toBe(0);
+
+    // And it must equal minus half the size growth, i.e. it re-pins the center to
+    // exactly the gesture-start center (offset = -(finalSize - origin)/2).
+    expect(offset.x).toBeCloseTo(-(size.width - ORIGIN.width) / 2, 0);
+    expect(offset.y).toBeCloseTo(-(size.height - ORIGIN.height) / 2, 0);
+  });
+});

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

@@ -8,6 +8,7 @@ import {
 } from "./manualEditsDom";
 import { buildBoxSizePatches, buildPathOffsetPatches } from "./manualEditsDomPatches";
 import { createManualOffsetDragMember, applyManualOffsetDragCommit } from "./manualOffsetDrag";
+import { computeNextResizeAnchor } from "./domEditResizeLocal";
 import type { PatchOperation } from "../../utils/sourcePatcher";
 import { splitTopLevelWhitespace } from "./manualEditsStyleHelpers";
 
@@ -16,15 +17,25 @@ import { splitTopLevelWhitespace } from "./manualEditsStyleHelpers";
  * CENTER, which must stay planted across the whole gesture — including after
  * release, on every corner and at any rotation.
  *
- * This file lands here with ONLY the persist round-trip test, which exercises the
- * real apply → persist → reload symbols that already exist at this point in the
- * stack. The two center-anchor CONVERGENCE tests (the release-shift root cause)
- * drive the exported `computeNextResizeAnchor` accumulator, which is extracted from
- * the resize pointermove branch of `useDomEditOverlayGestures.ts`. That gesture code
- * lands later in the stack (with the canvas glue swap), so those two tests are added
- * to this file at that point — importing the real production helper rather than a
- * test-local copy, so they can never pass against a stand-in that drifts from the
- * shipped math.
+ * Root cause of the original release "shift" (proved with a real-layout Chromium
+ * replay, see the anchor-loop test below): during a resize drag the per-frame
+ * anchor is derived from the element's LIVE measured center — which already carries
+ * the offset applied on the PREVIOUS frame — while `applyManualOffsetDragDraft`
+ * treats that anchor as the ABSOLUTE offset. So `fixedStart - centerNow` is really
+ * only the RESIDUAL correction, and using it as the absolute value makes the anchor
+ * OSCILLATE between the correct value and zero every frame:
+ *   frame 0: offset 0 → center shifted by the resize → anchor = full amount → apply
+ *   frame 1: offset applied → center back at fixedStart → anchor = 0 → apply 0 (un-pin!)
+ *   frame 2: offset 0 again → anchor = full amount → ...
+ * Release commits `g.lastResizeAnchor` from whichever parity the last pointermove
+ * landed on, so the element lands EITHER pinned OR un-pinned — an unpredictable
+ * post-release "shift".
+ *
+ * Fix (useDomEditOverlayGestures pointermove, resize branch, fa4f39168): accumulate
+ * the residual onto the previously-applied anchor instead of using it as the
+ * absolute offset, so the loop converges to a stable value on every frame. The
+ * per-frame accumulation is the exported `computeNextResizeAnchor` helper (the one
+ * call site in the pointermove resize branch); tests 1 & 2 drive it directly.
  */
 
 afterEach(() => {
@@ -66,10 +77,95 @@ function resolvedTranslatePx(el: HTMLElement): { x: number; y: number } {
 }
 
 describe("center-anchored corner resize — no shift after release", () => {
+  it("the per-frame center anchor converges (does NOT oscillate) — the release-shift root cause", () => {
+    // Model the pointermove anchor loop that pins the element's CENTER. The physical
+    // truth (confirmed in a real browser): the measured center sits at
+    // `fixedStart - appliedOffset` shifted by the resize — i.e. applying the offset
+    // moves the center back toward its gesture-start position. Here scale=1 so
+    // screen px == offset px. `trueAnchor` is the compensating offset that pins it.
+    const trueAnchor = { dx: -60, dy: -27 };
+    const fixedStart = { x: 500, y: 270 };
+
+    // `appliedOffset` mirrors what applyManualOffsetDragDraft set last frame.
+    let appliedOffset = { x: 0, y: 0 };
+    // `lastResizeAnchor` accumulator, exactly as g.lastResizeAnchor in the fix.
+    let lastResizeAnchor: { dx: number; dy: number } | undefined;
+
+    const anchorsSeen: Array<{ dx: number; dy: number }> = [];
+    for (let frame = 0; frame < 8; frame++) {
+      // Live measured center: the resize would put it at fixedStart + trueAnchor
+      // (un-anchored), and the currently-applied offset pulls it back by that
+      // offset. So centerNow = fixedStart - trueAnchor + appliedOffset.
+      const centerNow = {
+        x: fixedStart.x - trueAnchor.dx + appliedOffset.x,
+        y: fixedStart.y - trueAnchor.dy + appliedOffset.y,
+      };
+      // ── The fixed logic (accumulate residual onto the previous anchor) ──
+      const anchor = computeNextResizeAnchor(lastResizeAnchor, fixedStart, centerNow);
+      lastResizeAnchor = anchor;
+      anchorsSeen.push(anchor);
+      // applyManualOffsetDragDraft sets the absolute offset (scale 1) = anchor.
+      appliedOffset = { x: anchor.dx, y: anchor.dy };
+    }
+
+    // Every frame must report the same, correct anchor — no oscillation, so the
+    // committed value is parity-independent.
+    for (const a of anchorsSeen) {
+      expect(a).toEqual(trueAnchor);
+    }
+    // Guard against the OLD absolute formula regressing: with `anchor =
+    // fixedStart - centerNow` (no accumulation) the sequence would be
+    // [trueAnchor, 0, trueAnchor, 0, ...]; assert the last two frames agree.
+    expect(anchorsSeen.at(-1)).toEqual(anchorsSeen.at(-2));
+  });
+
+  it("the center stays fixed for every corner at any rotation (loop converges)", () => {
+    // The pin loop is handle- and rotation-independent: it always measures the
+    // element CENTER and drives it back to fixedStart. Simulate the loop for all
+    // four corners across unrotated + rotated gestures; the resize's raw center
+    // shift varies with corner/rotation (modelled as `rawShift`), but the loop must
+    // converge the measured center onto fixedStart every time.
+    const fixedStart = { x: 640, y: 360 };
+    const HANDLES = ["nw", "ne", "sw", "se"] as const;
+    const DEGS = [0, 30, 90, 137];
+    for (const handle of HANDLES) {
+      for (const deg of DEGS) {
+        const t = (deg * Math.PI) / 180;
+        // Raw (un-pinned) center shift the size write would cause this frame —
+        // a corner/rotation-dependent vector. Its exact value is irrelevant; the
+        // loop only needs to cancel it.
+        const seed = (HANDLES.indexOf(handle) + 1) * 11;
+        const rawShift = {
+          dx: Math.cos(t) * seed - Math.sin(t) * (seed / 2),
+          dy: Math.sin(t) * seed + Math.cos(t) * (seed / 2),
+        };
+        let appliedOffset = { x: 0, y: 0 };
+        let lastResizeAnchor: { dx: number; dy: number } | undefined;
+        let centerNow = { x: fixedStart.x, y: fixedStart.y };
+        for (let frame = 0; frame < 6; frame++) {
+          centerNow = {
+            x: fixedStart.x + rawShift.dx + appliedOffset.x,
+            y: fixedStart.y + rawShift.dy + appliedOffset.y,
+          };
+          const anchor = computeNextResizeAnchor(lastResizeAnchor, fixedStart, centerNow);
+          lastResizeAnchor = anchor;
+          appliedOffset = { x: anchor.dx, y: anchor.dy };
+        }
+        // After convergence the pinned center equals the gesture-start center.
+        const pinnedCenter = {
+          x: fixedStart.x + rawShift.dx + appliedOffset.x,
+          y: fixedStart.y + rawShift.dy + appliedOffset.y,
+        };
+        expect(pinnedCenter.x).toBeCloseTo(fixedStart.x, 9);
+        expect(pinnedCenter.y).toBeCloseTo(fixedStart.y, 9);
+      }
+    }
+  });
+
   it("net translate after persist+reload equals the committed anchor offset (non-GSAP)", () => {
     // The committed offset flows through the real apply → persist → reload chain
     // unchanged (this hop was proved clean; the shift is upstream in the anchor
-    // loop, tested with the gesture code, not in persistence).
+    // loop above, not in persistence).
     const el = document.createElement("div");
     el.style.setProperty("width", "200px");
     el.style.setProperty("height", "100px");

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", () => {