@hyperframes/studio 0.7.55 → 0.7.56

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/domEditNudge.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import {
+  CANVAS_NUDGE_SHIFT_STEP_PX,
+  CANVAS_NUDGE_STEP_PX,
+  canCanvasNudgeTargets,
+  resolveCanvasNudgeDelta,
+} from "./domEditNudge";
+
+function mockKeyboardEvent(
+  key: string,
+  overrides: Partial<Pick<KeyboardEvent, "altKey" | "ctrlKey" | "metaKey" | "shiftKey">> = {},
+): Pick<KeyboardEvent, "altKey" | "ctrlKey" | "metaKey" | "shiftKey" | "key"> {
+  return {
+    altKey: false,
+    ctrlKey: false,
+    metaKey: false,
+    shiftKey: false,
+    key,
+    ...overrides,
+  };
+}
+
+describe("resolveCanvasNudgeDelta", () => {
+  it("maps plain arrows to 1px composition deltas", () => {
+    expect(resolveCanvasNudgeDelta(mockKeyboardEvent("ArrowLeft"))).toEqual({
+      dx: -CANVAS_NUDGE_STEP_PX,
+      dy: 0,
+    });
+    expect(resolveCanvasNudgeDelta(mockKeyboardEvent("ArrowRight"))).toEqual({
+      dx: CANVAS_NUDGE_STEP_PX,
+      dy: 0,
+    });
+    expect(resolveCanvasNudgeDelta(mockKeyboardEvent("ArrowUp"))).toEqual({
+      dx: 0,
+      dy: -CANVAS_NUDGE_STEP_PX,
+    });
+    expect(resolveCanvasNudgeDelta(mockKeyboardEvent("ArrowDown"))).toEqual({
+      dx: 0,
+      dy: CANVAS_NUDGE_STEP_PX,
+    });
+  });
+
+  it("maps Shift+arrow to 10px deltas", () => {
+    expect(resolveCanvasNudgeDelta(mockKeyboardEvent("ArrowRight", { shiftKey: true }))).toEqual({
+      dx: CANVAS_NUDGE_SHIFT_STEP_PX,
+      dy: 0,
+    });
+    expect(resolveCanvasNudgeDelta(mockKeyboardEvent("ArrowUp", { shiftKey: true }))).toEqual({
+      dx: 0,
+      dy: -CANVAS_NUDGE_SHIFT_STEP_PX,
+    });
+  });
+
+  it("ignores browser and app shortcut chords", () => {
+    expect(resolveCanvasNudgeDelta(mockKeyboardEvent("ArrowLeft", { altKey: true }))).toBeNull();
+    expect(resolveCanvasNudgeDelta(mockKeyboardEvent("ArrowLeft", { ctrlKey: true }))).toBeNull();
+    expect(resolveCanvasNudgeDelta(mockKeyboardEvent("ArrowLeft", { metaKey: true }))).toBeNull();
+  });
+
+  it("ignores non-arrow keys", () => {
+    expect(resolveCanvasNudgeDelta(mockKeyboardEvent("Escape"))).toBeNull();
+    expect(resolveCanvasNudgeDelta(mockKeyboardEvent("a"))).toBeNull();
+  });
+});
+
+describe("canCanvasNudgeTargets", () => {
+  const movable = { capabilities: { canApplyManualOffset: true } };
+  const locked = { capabilities: { canApplyManualOffset: false } };
+
+  it("requires at least one target", () => {
+    expect(canCanvasNudgeTargets([])).toBe(false);
+  });
+
+  it("allows only when every target accepts a manual offset", () => {
+    expect(canCanvasNudgeTargets([movable])).toBe(true);
+    expect(canCanvasNudgeTargets([movable, movable])).toBe(true);
+    expect(canCanvasNudgeTargets([locked])).toBe(false);
+    expect(canCanvasNudgeTargets([movable, locked])).toBe(false);
+  });
+});

package/src/components/editor/domEditNudge.ts

@@ -0,0 +1,44 @@
+/**
+ * Pure helpers for the canvas arrow-key nudge (DomEditOverlay).
+ *
+ * Mirrors captions/keyboard.ts conventions; the two nudge surfaces can't
+ * double-fire because PreviewOverlays mounts CaptionOverlay and DomEditOverlay
+ * mutually exclusively (caption edit mode returns before the DOM overlay).
+ */
+
+const CANVAS_NUDGE_KEYS = new Set(["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"]);
+
+export const CANVAS_NUDGE_STEP_PX = 1;
+export const CANVAS_NUDGE_SHIFT_STEP_PX = 10;
+/** One undo entry per key burst: the commit fires after this idle gap. */
+export const CANVAS_NUDGE_COMMIT_DEBOUNCE_MS = 400;
+
+type CanvasNudgeKeyEvent = Pick<
+  KeyboardEvent,
+  "altKey" | "ctrlKey" | "metaKey" | "shiftKey" | "key"
+>;
+
+/**
+ * Arrow key → composition-px delta (Shift = 10). Null when the key is not a
+ * plain/Shift arrow, so browser and app shortcut chords pass through.
+ */
+export function resolveCanvasNudgeDelta(
+  event: CanvasNudgeKeyEvent,
+): { dx: number; dy: number } | null {
+  if (event.metaKey || event.ctrlKey || event.altKey) return null;
+  if (!CANVAS_NUDGE_KEYS.has(event.key)) return null;
+  const step = event.shiftKey ? CANVAS_NUDGE_SHIFT_STEP_PX : CANVAS_NUDGE_STEP_PX;
+  return {
+    dx: event.key === "ArrowLeft" ? -step : event.key === "ArrowRight" ? step : 0,
+    dy: event.key === "ArrowUp" ? -step : event.key === "ArrowDown" ? step : 0,
+  };
+}
+
+export interface CanvasNudgeTarget {
+  capabilities: { canApplyManualOffset: boolean };
+}
+
+/** A nudge needs at least one target and every target must accept manual offsets. */
+export function canCanvasNudgeTargets(targets: ReadonlyArray<CanvasNudgeTarget>): boolean {
+  return targets.length > 0 && targets.every((t) => t.capabilities.canApplyManualOffset);
+}

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

@@ -1,6 +1,37 @@
 // @vitest-environment jsdom
 import { describe, expect, it } from "vitest";
-import { selectionCacheKey } from "./domEditOverlayGeometry";
+import {
+  orientedOverlayRect,
+  orientedGroupAwareOverlayRect,
+  overlayCornersCentroid,
+  selectionCacheKey,
+} from "./domEditOverlayGeometry";
+
+describe("overlayCornersCentroid", () => {
+  it("averages the four corners (the rendered rotation center)", () => {
+    expect(
+      overlayCornersCentroid({
+        nw: { x: 10, y: 20 },
+        ne: { x: 110, y: 20 },
+        se: { x: 110, y: 80 },
+        sw: { x: 10, y: 80 },
+      }),
+    ).toEqual({ x: 60, y: 50 });
+  });
+
+  it("is unchanged by rotation — a rotated square's corners average to its center", () => {
+    // Unit square centered at (5,5), rotated 45deg about its center: corners land
+    // on the axis midpoints, whose average is still the center.
+    const c = overlayCornersCentroid({
+      nw: { x: 5, y: 5 - Math.SQRT2 / 2 },
+      ne: { x: 5 + Math.SQRT2 / 2, y: 5 },
+      se: { x: 5, y: 5 + Math.SQRT2 / 2 },
+      sw: { x: 5 - Math.SQRT2 / 2, y: 5 },
+    });
+    expect(c.x).toBeCloseTo(5, 9);
+    expect(c.y).toBeCloseTo(5, 9);
+  });
+});
 
 describe("selectionCacheKey — hfId collision (R7)", () => {
   it("produces distinct keys for two elements that differ only by hfId", () => {
@@ -11,3 +42,138 @@ describe("selectionCacheKey — hfId collision (R7)", () => {
     expect(a).not.toBe(b);
   });
 });
+
+describe("orientedOverlayRect — rotation gate (perf fix, V15 18a/18b)", () => {
+  // jsdom has no DOMMatrix/DOMPoint; a minimal stand-in is enough to exercise the
+  // real (unmocked) orientedOverlayRect, unlike DomEditOverlay.test.ts and
+  // anchoredResizeCommitFeedsOffset.test.ts, which mock this module entirely.
+  class FakeDOMMatrix {
+    a = 1;
+    b = 0;
+    c = 0;
+    d = 1;
+    e = 0;
+    f = 0;
+    constructor(init?: string) {
+      const m = init ? /matrix\(([^)]+)\)/.exec(init) : null;
+      if (!m) return;
+      const parts = m[1]!.split(",").map((s) => Number.parseFloat(s.trim()));
+      [this.a, this.b, this.c, this.d, this.e, this.f] = parts as [
+        number,
+        number,
+        number,
+        number,
+        number,
+        number,
+      ];
+    }
+    transformPoint(pt: { x: number; y: number }) {
+      return {
+        x: this.a * pt.x + this.c * pt.y + this.e,
+        y: this.b * pt.x + this.d * pt.y + this.f,
+      };
+    }
+  }
+  class FakeDOMPoint {
+    constructor(
+      public x: number,
+      public y: number,
+    ) {}
+  }
+  // matrix() form of rotate(30deg), so the module's `new DOMMatrix(cs.transform)`
+  // parse (which expects "matrix(...)", not "rotate(...)") resolves correctly.
+  const ROTATE_30DEG_MATRIX =
+    "matrix(0.8660254037844387, 0.49999999999999994, -0.49999999999999994, 0.8660254037844387, 0, 0)";
+
+  function stubRect(
+    el: Element,
+    rect: { left: number; top: number; width: number; height: number },
+  ) {
+    (el as unknown as { getBoundingClientRect: () => DOMRect }).getBoundingClientRect = () =>
+      ({
+        left: rect.left,
+        top: rect.top,
+        width: rect.width,
+        height: rect.height,
+        right: rect.left + rect.width,
+        bottom: rect.top + rect.height,
+        x: rect.left,
+        y: rect.top,
+        toJSON() {
+          return this;
+        },
+      }) as DOMRect;
+  }
+
+  function buildHarness() {
+    const overlayEl = document.createElement("div");
+    document.body.appendChild(overlayEl);
+    stubRect(overlayEl, { left: 0, top: 0, width: 1000, height: 1000 });
+
+    const iframe = document.createElement("iframe");
+    document.body.appendChild(iframe);
+    stubRect(iframe, { left: 0, top: 0, width: 1000, height: 1000 });
+
+    const doc = iframe.contentDocument!;
+    const root = doc.createElement("div");
+    root.setAttribute("data-composition-id", "root");
+    root.setAttribute("data-width", "1000");
+    root.setAttribute("data-height", "1000");
+    doc.body.appendChild(root);
+
+    const el = doc.createElement("div");
+    root.appendChild(el);
+    stubRect(el, { left: 400, top: 450, width: 200, height: 100 });
+    Object.defineProperty(el, "offsetWidth", { value: 200, configurable: true });
+    Object.defineProperty(el, "offsetHeight", { value: 100, configurable: true });
+
+    const win = iframe.contentWindow as unknown as Window & {
+      DOMMatrix: unknown;
+      DOMPoint: unknown;
+    };
+    win.DOMMatrix = FakeDOMMatrix;
+    win.DOMPoint = FakeDOMPoint;
+
+    return { overlayEl, iframe, el };
+  }
+
+  it("unrotated element takes the cheap AABB path — matches the raw bounding rect, angle 0", () => {
+    const { overlayEl, iframe, el } = buildHarness();
+    const rect = orientedOverlayRect(overlayEl, iframe, el);
+    expect(rect).not.toBeNull();
+    expect(rect!.left).toBeCloseTo(400, 5);
+    expect(rect!.top).toBeCloseTo(450, 5);
+    expect(rect!.width).toBeCloseTo(200, 5);
+    expect(rect!.height).toBeCloseTo(100, 5);
+    expect(rect!.angle ?? 0).toBe(0);
+  });
+
+  it("rotated element takes the corner-geometry path — reports the live angle", () => {
+    const { overlayEl, iframe, el } = buildHarness();
+    el.style.transform = ROTATE_30DEG_MATRIX;
+    const rect = orientedOverlayRect(overlayEl, iframe, el);
+    expect(rect).not.toBeNull();
+    expect(rect!.angle).toBeCloseTo(30, 3);
+  });
+
+  it("preserves an ordinary element's rotation through the group-aware entry point", () => {
+    const { overlayEl, iframe, el } = buildHarness();
+    el.style.transform = ROTATE_30DEG_MATRIX;
+    const rect = orientedGroupAwareOverlayRect(overlayEl, iframe, el);
+    expect(rect!.angle).toBeCloseTo(30, 3);
+  });
+
+  it("gate re-evaluates every call — editing an element to rotated mid-session flips the path immediately", () => {
+    const { overlayEl, iframe, el } = buildHarness();
+    const before = orientedOverlayRect(overlayEl, iframe, el);
+    expect(before?.angle ?? 0).toBe(0);
+
+    el.style.transform = ROTATE_30DEG_MATRIX;
+    const after = orientedOverlayRect(overlayEl, iframe, el);
+    expect(after!.angle).toBeCloseTo(30, 3);
+
+    el.style.transform = "";
+    const restored = orientedOverlayRect(overlayEl, iframe, el);
+    expect(restored?.angle ?? 0).toBe(0);
+  });
+});