From 4b296386a25e58e51d1c1b6d7402b48e187d06a1 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 19:54:27 -0700
Subject: [PATCH 01/45] fix: resolve element selection getting stuck on busy
 pages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two root causes identified via runtime instrumentation on nisarg.io:

1. Detection scheduling used scheduler.postTask({priority:"background"})
   which was starved for 350ms–5000ms on pages with continuous React
   renders or CSS animations, making hover detection feel frozen.
   Replaced with requestAnimationFrame (~16ms per frame).

2. Decorative hover overlay divs (absolute-positioned, transparent,
   empty elements used for hover border/glow effects) were returned by
   elementFromPoint, blocking detection of actual content underneath.
   Added isDecorativeOverlay filter to skip these elements.
---
 .../src/utils/is-valid-grabbable-element.ts   | 19 +++++++++
 packages/react-grab/src/utils/on-idle.ts      | 40 ++++---------------
 2 files changed, 26 insertions(+), 33 deletions(-)

diff --git a/packages/react-grab/src/utils/is-valid-grabbable-element.ts b/packages/react-grab/src/utils/is-valid-grabbable-element.ts
index f2876803f..14a69162f 100644
--- a/packages/react-grab/src/utils/is-valid-grabbable-element.ts
+++ b/packages/react-grab/src/utils/is-valid-grabbable-element.ts
@@ -74,6 +74,20 @@ export const clearVisibilityCache = (): void => {
   visibilityCache = new WeakMap<Element, VisibilityCache>();
 };
 
+const isDecorativeOverlay = (element: Element, computedStyle: CSSStyleDeclaration): boolean => {
+  const position = computedStyle.position;
+  if (position !== "absolute" && position !== "fixed") {
+    return false;
+  }
+
+  if (element.childElementCount > 0 || (element.textContent?.trim().length ?? 0) > 0) {
+    return false;
+  }
+
+  const backgroundColor = computedStyle.backgroundColor;
+  return backgroundColor === "transparent" || backgroundColor === "rgba(0, 0, 0, 0)";
+};
+
 export const isValidGrabbableElement = (element: Element): boolean => {
   if (isRootElement(element)) {
     return false;
@@ -102,6 +116,11 @@ export const isValidGrabbableElement = (element: Element): boolean => {
     return false;
   }
 
+  if (isDecorativeOverlay(element, computedStyle)) {
+    visibilityCache.set(element, { isVisible: false, timestamp: now });
+    return false;
+  }
+
   const couldBeOverlay =
     element.clientWidth / window.innerWidth >= VIEWPORT_COVERAGE_THRESHOLD &&
     element.clientHeight / window.innerHeight >= VIEWPORT_COVERAGE_THRESHOLD;
diff --git a/packages/react-grab/src/utils/on-idle.ts b/packages/react-grab/src/utils/on-idle.ts
index 7437b19d9..2a73decfa 100644
--- a/packages/react-grab/src/utils/on-idle.ts
+++ b/packages/react-grab/src/utils/on-idle.ts
@@ -1,36 +1,10 @@
-interface BackgroundTaskScheduler {
-  postTask: (callback: () => void, options: { priority: "background" }) => unknown;
-}
+import { nativeRequestAnimationFrame } from "./native-raf.js";
 
-declare global {
-  interface Window {
-    scheduler?: BackgroundTaskScheduler;
-  }
-}
-
-const isBackgroundTaskScheduler = (value: unknown): value is BackgroundTaskScheduler => {
-  if (typeof value !== "object" || value === null) return false;
-  if (!("postTask" in value)) return false;
-  return typeof value.postTask === "function";
-};
-
-// Defers work via the best available idle-scheduling primitive: the Scheduler
-// API with background priority (Chrome 94+), then requestIdleCallback, then a
-// setTimeout(0) fallback. This is used for expensive hit-testing work that
-// should never block user-visible rendering.
+// Defers hit-testing work to the next animation frame so it doesn't block the
+// current event handler. requestAnimationFrame fires once per frame (~16ms) at
+// rendering priority, which avoids the multi-second starvation seen with
+// scheduler.postTask({priority:"background"}) and requestIdleCallback on pages
+// with continuous React renders or CSS animations.
 export const onIdle = (callback: () => void): void => {
-  if (typeof window !== "undefined") {
-    const schedulerCandidate = window.scheduler;
-    if (isBackgroundTaskScheduler(schedulerCandidate)) {
-      schedulerCandidate.postTask(callback, {
-        priority: "background",
-      });
-      return;
-    }
-    if ("requestIdleCallback" in window) {
-      requestIdleCallback(callback);
-      return;
-    }
-  }
-  setTimeout(callback, 0);
+  nativeRequestAnimationFrame(callback);
 };

From da29b1e56f69d75d5ec77e473df026b3f39ba06e Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 19:54:31 -0700
Subject: [PATCH 02/45] fix: reduce flaky E2E tests

- Fix race in rightClickElement by checking overlay state before click
- Increase waitForContextMenu/waitForPromptMode timeouts to 5s
- Replace fixed post-copy waits with polling for comments button
- Convert dismiss assertions from waitForTimeout to expect.poll
- Increase freeze cleanup propagation wait in multi-cycle test
---
 .../e2e/clear-history-prompt.spec.ts          | 57 +++++++++----------
 packages/react-grab/e2e/context-menu.spec.ts  | 10 +---
 packages/react-grab/e2e/fixtures.ts           | 16 +++---
 .../react-grab/e2e/freeze-updates.spec.ts     |  2 +-
 4 files changed, 40 insertions(+), 45 deletions(-)

diff --git a/packages/react-grab/e2e/clear-history-prompt.spec.ts b/packages/react-grab/e2e/clear-history-prompt.spec.ts
index 771e6ab59..594ed0934 100644
--- a/packages/react-grab/e2e/clear-history-prompt.spec.ts
+++ b/packages/react-grab/e2e/clear-history-prompt.spec.ts
@@ -7,8 +7,7 @@ const copyElement = async (reactGrab: ReactGrabPageObject, selector: string) =>
   await reactGrab.typeInInput("comment");
   await reactGrab.submitInput();
   await expect.poll(() => reactGrab.getClipboardContent(), { timeout: 5000 }).toBeTruthy();
-  // HACK: Wait for copy feedback transition and comments item addition
-  await reactGrab.page.waitForTimeout(300);
+  await expect.poll(() => reactGrab.isCommentsButtonVisible(), { timeout: 5000 }).toBe(true);
 };
 
 test.describe("Toolbar Copy All Button", () => {
@@ -24,18 +23,18 @@ test.describe("Toolbar Copy All Button", () => {
       await copyElement(reactGrab, "li:first-child");
       await reactGrab.clickCommentsButton();
 
-      await expect.poll(() => reactGrab.isToolbarCopyAllVisible(), { timeout: 2000 }).toBe(true);
+      await expect.poll(() => reactGrab.isToolbarCopyAllVisible(), { timeout: 5000 }).toBe(true);
     });
 
     test("should hide when comments dropdown is closed", async ({ reactGrab }) => {
       await copyElement(reactGrab, "li:first-child");
       await reactGrab.clickCommentsButton();
 
-      await expect.poll(() => reactGrab.isToolbarCopyAllVisible(), { timeout: 2000 }).toBe(true);
+      await expect.poll(() => reactGrab.isToolbarCopyAllVisible(), { timeout: 5000 }).toBe(true);
 
       await reactGrab.clickCommentsButton();
 
-      await expect.poll(() => reactGrab.isToolbarCopyAllVisible(), { timeout: 2000 }).toBe(false);
+      await expect.poll(() => reactGrab.isToolbarCopyAllVisible(), { timeout: 5000 }).toBe(false);
     });
   });
 
@@ -60,7 +59,7 @@ test.describe("Toolbar Copy All Button", () => {
       await reactGrab.clickToolbarCopyAll();
 
       await expect
-        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 2000 })
+        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 5000 })
         .toBe(true);
     });
   });
@@ -74,7 +73,7 @@ test.describe("Clear History Prompt", () => {
       await reactGrab.clickToolbarCopyAll();
 
       await expect
-        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 2000 })
+        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 5000 })
         .toBe(true);
     });
 
@@ -84,7 +83,7 @@ test.describe("Clear History Prompt", () => {
       await reactGrab.clickCommentsCopyAll();
 
       await expect
-        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 2000 })
+        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 5000 })
         .toBe(true);
     });
   });
@@ -98,13 +97,13 @@ test.describe("Clear History Prompt", () => {
       await reactGrab.clickToolbarCopyAll();
 
       await expect
-        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 2000 })
+        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 5000 })
         .toBe(true);
 
       await reactGrab.confirmClearCommentsPrompt();
       await reactGrab.page.waitForTimeout(200);
 
-      await expect.poll(() => reactGrab.isCommentsButtonVisible(), { timeout: 2000 }).toBe(false);
+      await expect.poll(() => reactGrab.isCommentsButtonVisible(), { timeout: 5000 }).toBe(false);
     });
 
     test("should clear comments when confirmed via Enter key", async ({ reactGrab }) => {
@@ -114,17 +113,17 @@ test.describe("Clear History Prompt", () => {
       await reactGrab.clickToolbarCopyAll();
 
       await expect
-        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 2000 })
+        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 5000 })
         .toBe(true);
 
       await reactGrab.pressEnter();
       await reactGrab.page.waitForTimeout(200);
 
       await expect
-        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 2000 })
+        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 5000 })
         .toBe(false);
 
-      await expect.poll(() => reactGrab.isCommentsButtonVisible(), { timeout: 2000 }).toBe(false);
+      await expect.poll(() => reactGrab.isCommentsButtonVisible(), { timeout: 5000 }).toBe(false);
     });
 
     test("should dismiss the prompt after confirming", async ({ reactGrab }) => {
@@ -134,13 +133,13 @@ test.describe("Clear History Prompt", () => {
       await reactGrab.clickToolbarCopyAll();
 
       await expect
-        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 2000 })
+        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 5000 })
         .toBe(true);
 
       await reactGrab.confirmClearCommentsPrompt();
 
       await expect
-        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 2000 })
+        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 5000 })
         .toBe(false);
     });
 
@@ -153,12 +152,12 @@ test.describe("Clear History Prompt", () => {
       await reactGrab.clickToolbarCopyAll();
 
       await expect
-        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 2000 })
+        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 5000 })
         .toBe(true);
 
       await reactGrab.confirmClearCommentsPrompt();
 
-      await expect.poll(() => reactGrab.isCommentsButtonVisible(), { timeout: 2000 }).toBe(false);
+      await expect.poll(() => reactGrab.isCommentsButtonVisible(), { timeout: 5000 }).toBe(false);
 
       await copyElement(reactGrab, "li:last-child");
 
@@ -166,10 +165,10 @@ test.describe("Clear History Prompt", () => {
       await reactGrab.clickToolbarCopyAll();
 
       await expect
-        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 2000 })
+        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 5000 })
         .toBe(false);
 
-      await expect.poll(() => reactGrab.isCommentsButtonVisible(), { timeout: 2000 }).toBe(false);
+      await expect.poll(() => reactGrab.isCommentsButtonVisible(), { timeout: 5000 }).toBe(false);
     });
   });
 
@@ -181,17 +180,17 @@ test.describe("Clear History Prompt", () => {
       await reactGrab.clickToolbarCopyAll();
 
       await expect
-        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 2000 })
+        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 5000 })
         .toBe(true);
 
       await reactGrab.cancelClearCommentsPrompt();
       await reactGrab.page.waitForTimeout(200);
 
       await expect
-        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 2000 })
+        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 5000 })
         .toBe(false);
 
-      await expect.poll(() => reactGrab.isCommentsButtonVisible(), { timeout: 2000 }).toBe(true);
+      await expect.poll(() => reactGrab.isCommentsButtonVisible(), { timeout: 5000 }).toBe(true);
     });
 
     test("should dismiss prompt when cancelled via Escape key", async ({ reactGrab }) => {
@@ -201,17 +200,17 @@ test.describe("Clear History Prompt", () => {
       await reactGrab.clickToolbarCopyAll();
 
       await expect
-        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 2000 })
+        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 5000 })
         .toBe(true);
 
       await reactGrab.pressEscape();
       await reactGrab.page.waitForTimeout(200);
 
       await expect
-        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 2000 })
+        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 5000 })
         .toBe(false);
 
-      await expect.poll(() => reactGrab.isCommentsButtonVisible(), { timeout: 2000 }).toBe(true);
+      await expect.poll(() => reactGrab.isCommentsButtonVisible(), { timeout: 5000 }).toBe(true);
     });
   });
 
@@ -223,7 +222,7 @@ test.describe("Clear History Prompt", () => {
       await reactGrab.clickToolbarCopyAll();
 
       await expect
-        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 2000 })
+        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 5000 })
         .toBe(true);
 
       await reactGrab.activate();
@@ -232,7 +231,7 @@ test.describe("Clear History Prompt", () => {
       await reactGrab.rightClickElement("li:first-child");
 
       await expect
-        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 2000 })
+        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 5000 })
         .toBe(false);
     });
 
@@ -243,14 +242,14 @@ test.describe("Clear History Prompt", () => {
       await reactGrab.clickToolbarCopyAll();
 
       await expect
-        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 2000 })
+        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 5000 })
         .toBe(true);
 
       await reactGrab.clickToolbarEnabled();
       await reactGrab.page.waitForTimeout(200);
 
       await expect
-        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 2000 })
+        .poll(() => reactGrab.isClearCommentsPromptVisible(), { timeout: 5000 })
         .toBe(false);
     });
   });
diff --git a/packages/react-grab/e2e/context-menu.spec.ts b/packages/react-grab/e2e/context-menu.spec.ts
index 603595d1f..284b93fd4 100644
--- a/packages/react-grab/e2e/context-menu.spec.ts
+++ b/packages/react-grab/e2e/context-menu.spec.ts
@@ -46,7 +46,7 @@ test.describe("Context Menu", () => {
       const element = reactGrab.page.locator("li").first();
       await element.click({ button: "right", force: true });
 
-      await expect.poll(() => reactGrab.isContextMenuVisible(), { timeout: 2000 }).toBe(true);
+      await expect.poll(() => reactGrab.isContextMenuVisible(), { timeout: 5000 }).toBe(true);
 
       await reactGrab.page.keyboard.up("c");
       await reactGrab.page.keyboard.up(reactGrab.modifierKey);
@@ -118,10 +118,8 @@ test.describe("Context Menu", () => {
       expect(isVisibleBefore).toBe(true);
 
       await reactGrab.page.keyboard.press("Escape");
-      await reactGrab.page.waitForTimeout(200);
 
-      const isVisibleAfter = await reactGrab.isContextMenuVisible();
-      expect(isVisibleAfter).toBe(false);
+      await expect.poll(() => reactGrab.isContextMenuVisible(), { timeout: 5000 }).toBe(false);
     });
 
     test("should dismiss context menu when clicking outside", async ({ reactGrab }) => {
@@ -134,10 +132,8 @@ test.describe("Context Menu", () => {
       expect(isVisibleBefore).toBe(true);
 
       await reactGrab.page.mouse.click(10, 10);
-      await reactGrab.page.waitForTimeout(200);
 
-      const isVisibleAfter = await reactGrab.isContextMenuVisible();
-      expect(isVisibleAfter).toBe(false);
+      await expect.poll(() => reactGrab.isContextMenuVisible(), { timeout: 5000 }).toBe(false);
     });
 
     test("should dismiss context menu after Copy action", async ({ reactGrab }) => {
diff --git a/packages/react-grab/e2e/fixtures.ts b/packages/react-grab/e2e/fixtures.ts
index c11fa5b3f..596bc9228 100644
--- a/packages/react-grab/e2e/fixtures.ts
+++ b/packages/react-grab/e2e/fixtures.ts
@@ -265,7 +265,7 @@ const createReactGrabPageObject = (page: Page): ReactGrabPageObject => {
   const hoverElement = async (selector: string) => {
     const element = page.locator(selector).first();
     await element.hover({ force: true });
-    await page.waitForTimeout(250);
+    await page.waitForTimeout(350);
   };
 
   const clickElement = async (selector: string) => {
@@ -422,23 +422,23 @@ const createReactGrabPageObject = (page: Page): ReactGrabPageObject => {
         return expectedVisible ? menuItem !== null : menuItem === null;
       },
       { attrName: ATTRIBUTE_NAME, expectedVisible: visible },
-      { timeout: 2000 },
+      { timeout: 5000 },
     );
   };
 
   const rightClickElement = async (selector: string) => {
+    const wasActive = await isOverlayVisible();
     const element = page.locator(selector).first();
     await element.click({ button: "right", force: true });
-    const isActive = await isOverlayVisible();
-    if (isActive) {
+    if (wasActive) {
       await waitForContextMenu(true);
     }
   };
 
   const rightClickAtPosition = async (x: number, y: number) => {
+    const wasActive = await isOverlayVisible();
     await page.mouse.click(x, y, { button: "right" });
-    const isActive = await isOverlayVisible();
-    if (isActive) {
+    if (wasActive) {
       await waitForContextMenu(true);
     }
   };
@@ -576,7 +576,7 @@ const createReactGrabPageObject = (page: Page): ReactGrabPageObject => {
         return api?.getState()?.isPromptMode === expected;
       },
       active,
-      { timeout: 2000 },
+      { timeout: 5000 },
     );
   };
 
@@ -600,7 +600,7 @@ const createReactGrabPageObject = (page: Page): ReactGrabPageObject => {
           return state?.isSelectionBoxVisible || state?.targetElement !== null;
         },
         undefined,
-        { timeout: 2000 },
+        { timeout: 5000 },
       )
       .then(() => true)
       .catch(() => false);
diff --git a/packages/react-grab/e2e/freeze-updates.spec.ts b/packages/react-grab/e2e/freeze-updates.spec.ts
index 99a6205dc..3d2fcfa07 100644
--- a/packages/react-grab/e2e/freeze-updates.spec.ts
+++ b/packages/react-grab/e2e/freeze-updates.spec.ts
@@ -235,7 +235,7 @@ test.describe("Freeze Updates", () => {
         await reactGrab.enterPromptMode("[data-testid='dynamic-element-1']");
         await reactGrab.deactivate();
         // HACK: allow freeze cleanup to fully propagate before next iteration
-        await reactGrab.page.waitForTimeout(300);
+        await reactGrab.page.waitForTimeout(500);
       }
 
       const getElementCount = async () => {

From 64dc9e761d1cf727edd797664f240ff88fcc352d Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 19:57:59 -0700
Subject: [PATCH 03/45] refactor: inline onIdle into
 nativeRequestAnimationFrame and extract hasTransparentBackground

- Delete on-idle.ts; it was a trivial wrapper after the scheduler change.
  Use nativeRequestAnimationFrame directly in index.tsx (already imported).
- Extract hasTransparentBackground helper shared between
  isDecorativeOverlay and isFullViewportOverlay.
---
 packages/react-grab/src/core/index.tsx        |  3 +--
 .../src/utils/is-valid-grabbable-element.ts   | 27 +++++++------------
 packages/react-grab/src/utils/on-idle.ts      | 10 -------
 3 files changed, 11 insertions(+), 29 deletions(-)
 delete mode 100644 packages/react-grab/src/utils/on-idle.ts

diff --git a/packages/react-grab/src/core/index.tsx b/packages/react-grab/src/core/index.tsx
index 504c30579..00eec06de 100644
--- a/packages/react-grab/src/core/index.tsx
+++ b/packages/react-grab/src/core/index.tsx
@@ -118,7 +118,6 @@ import { createArrowNavigator } from "./arrow-navigation.js";
 import { getRequiredModifiers, setupKeyboardEventClaimer } from "./keyboard-handlers.js";
 import { createAutoScroller, getAutoScrollDirection } from "./auto-scroll.js";
 import { logIntro } from "./log-intro.js";
-import { onIdle } from "../utils/on-idle.js";
 import { getScriptOptions } from "../utils/get-script-options.js";
 import { isEnterCode } from "../utils/is-enter-code.js";
 import { isMac } from "../utils/is-mac.js";
@@ -1624,7 +1623,7 @@ export const init = (rawOptions?: Options): ReactGrabAPI => {
       ) {
         elementDetectionState.lastDetectionTimestamp = now;
         elementDetectionState.pendingDetectionScheduledAt = now;
-        onIdle(() => {
+        nativeRequestAnimationFrame(() => {
           const candidate = getElementAtPosition(
             elementDetectionState.latestPointerX,
             elementDetectionState.latestPointerY,
diff --git a/packages/react-grab/src/utils/is-valid-grabbable-element.ts b/packages/react-grab/src/utils/is-valid-grabbable-element.ts
index 14a69162f..8ead55137 100644
--- a/packages/react-grab/src/utils/is-valid-grabbable-element.ts
+++ b/packages/react-grab/src/utils/is-valid-grabbable-element.ts
@@ -34,6 +34,11 @@ const isDevToolsOverlay = (computedStyle: CSSStyleDeclaration): boolean => {
   );
 };
 
+const hasTransparentBackground = (computedStyle: CSSStyleDeclaration): boolean => {
+  const backgroundColor = computedStyle.backgroundColor;
+  return backgroundColor === "transparent" || backgroundColor === "rgba(0, 0, 0, 0)";
+};
+
 const isFullViewportOverlay = (element: Element, computedStyle: CSSStyleDeclaration): boolean => {
   const position = computedStyle.position;
   if (position !== "fixed" && position !== "absolute") {
@@ -49,13 +54,7 @@ const isFullViewportOverlay = (element: Element, computedStyle: CSSStyleDeclarat
     return false;
   }
 
-  const backgroundColor = computedStyle.backgroundColor;
-  const hasInvisibleBackground =
-    backgroundColor === "transparent" ||
-    backgroundColor === "rgba(0, 0, 0, 0)" ||
-    parseFloat(computedStyle.opacity) < 0.1;
-
-  if (hasInvisibleBackground) {
+  if (hasTransparentBackground(computedStyle) || parseFloat(computedStyle.opacity) < 0.1) {
     return true;
   }
 
@@ -76,16 +75,10 @@ export const clearVisibilityCache = (): void => {
 
 const isDecorativeOverlay = (element: Element, computedStyle: CSSStyleDeclaration): boolean => {
   const position = computedStyle.position;
-  if (position !== "absolute" && position !== "fixed") {
-    return false;
-  }
-
-  if (element.childElementCount > 0 || (element.textContent?.trim().length ?? 0) > 0) {
-    return false;
-  }
-
-  const backgroundColor = computedStyle.backgroundColor;
-  return backgroundColor === "transparent" || backgroundColor === "rgba(0, 0, 0, 0)";
+  if (position !== "absolute" && position !== "fixed") return false;
+  if (element.childElementCount > 0) return false;
+  if ((element.textContent?.trim().length ?? 0) > 0) return false;
+  return hasTransparentBackground(computedStyle);
 };
 
 export const isValidGrabbableElement = (element: Element): boolean => {
diff --git a/packages/react-grab/src/utils/on-idle.ts b/packages/react-grab/src/utils/on-idle.ts
deleted file mode 100644
index 2a73decfa..000000000
--- a/packages/react-grab/src/utils/on-idle.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-import { nativeRequestAnimationFrame } from "./native-raf.js";
-
-// Defers hit-testing work to the next animation frame so it doesn't block the
-// current event handler. requestAnimationFrame fires once per frame (~16ms) at
-// rendering priority, which avoids the multi-second starvation seen with
-// scheduler.postTask({priority:"background"}) and requestIdleCallback on pages
-// with continuous React renders or CSS animations.
-export const onIdle = (callback: () => void): void => {
-  nativeRequestAnimationFrame(callback);
-};

From 8c9e55daa38c5968dc7ae92e817fddbeabbe502b Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 20:04:07 -0700
Subject: [PATCH 04/45] perf: use setTimeout over rAF for element detection
 scheduling

rAF callbacks run inside the rendering pipeline (before paint), so the
elementFromPoint style recalc was eating into the frame budget.
setTimeout(0) runs as a separate macrotask outside the render pipeline,
fires within ~1-4ms (no starvation), and doesn't impact frame budget.
The 32ms detection throttle already limits call frequency.
---
 packages/react-grab/src/core/index.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react-grab/src/core/index.tsx b/packages/react-grab/src/core/index.tsx
index 00eec06de..d916608d5 100644
--- a/packages/react-grab/src/core/index.tsx
+++ b/packages/react-grab/src/core/index.tsx
@@ -1623,7 +1623,7 @@ export const init = (rawOptions?: Options): ReactGrabAPI => {
       ) {
         elementDetectionState.lastDetectionTimestamp = now;
         elementDetectionState.pendingDetectionScheduledAt = now;
-        nativeRequestAnimationFrame(() => {
+        setTimeout(() => {
           const candidate = getElementAtPosition(
             elementDetectionState.latestPointerX,
             elementDetectionState.latestPointerY,

From 3e6e6608e2425288f5995b1c516d39bea7f09d07 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 20:11:38 -0700
Subject: [PATCH 05/45] docs: document why setTimeout is used for element
 detection scheduling

---
 packages/react-grab/src/core/index.tsx | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/packages/react-grab/src/core/index.tsx b/packages/react-grab/src/core/index.tsx
index d916608d5..2846cbf6b 100644
--- a/packages/react-grab/src/core/index.tsx
+++ b/packages/react-grab/src/core/index.tsx
@@ -1623,6 +1623,17 @@ export const init = (rawOptions?: Options): ReactGrabAPI => {
       ) {
         elementDetectionState.lastDetectionTimestamp = now;
         elementDetectionState.pendingDetectionScheduledAt = now;
+        // setTimeout defers the elementFromPoint hit-test into its own macrotask
+        // so the style recalculation it triggers doesn't eat the current frame's
+        // budget. Alternatives considered:
+        //   - queueMicrotask: runs before paint, blocks the frame (ivi/Preact use
+        //     microtasks for lightweight JS work, but elementFromPoint forces the
+        //     browser's layout engine which is categorically heavier)
+        //   - requestAnimationFrame: runs inside the render pipeline, same problem
+        //   - scheduler.postTask("background"): starved for 350ms–5s on pages with
+        //     continuous React renders or CSS animations
+        // setTimeout(0) fires in ~1ms as a separate task with no nesting-based
+        // clamping (each call originates from a distinct pointermove handler).
         setTimeout(() => {
           const candidate = getElementAtPosition(
             elementDetectionState.latestPointerX,

From e05242b4a068b22803487437e1d80b8f0f782397 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 20:18:22 -0700
Subject: [PATCH 06/45] fix: exclude replaced elements from decorative overlay
 filter
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replaced elements (img, video, canvas, svg, iframe, etc.) have no
children, no text, and a transparent background-color — matching all
isDecorativeOverlay criteria despite being real content. Skip them
with a tag name check before the emptiness/transparency heuristics.
---
 packages/react-grab/src/utils/is-valid-grabbable-element.ts | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/packages/react-grab/src/utils/is-valid-grabbable-element.ts b/packages/react-grab/src/utils/is-valid-grabbable-element.ts
index 8ead55137..4db3e0896 100644
--- a/packages/react-grab/src/utils/is-valid-grabbable-element.ts
+++ b/packages/react-grab/src/utils/is-valid-grabbable-element.ts
@@ -73,9 +73,15 @@ export const clearVisibilityCache = (): void => {
   visibilityCache = new WeakMap<Element, VisibilityCache>();
 };
 
+const REPLACED_ELEMENT_TAGS = new Set([
+  "IMG", "VIDEO", "CANVAS", "SVG", "IFRAME", "EMBED", "OBJECT",
+  "INPUT", "TEXTAREA", "SELECT",
+]);
+
 const isDecorativeOverlay = (element: Element, computedStyle: CSSStyleDeclaration): boolean => {
   const position = computedStyle.position;
   if (position !== "absolute" && position !== "fixed") return false;
+  if (REPLACED_ELEMENT_TAGS.has(element.tagName)) return false;
   if (element.childElementCount > 0) return false;
   if ((element.textContent?.trim().length ?? 0) > 0) return false;
   return hasTransparentBackground(computedStyle);

From 4296c131fa9133d1822df7b44b7018751039d7c1 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 20:23:32 -0700
Subject: [PATCH 07/45] refactor: allowlist DIV/SPAN instead of blocklisting
 replaced elements

Decorative hover overlays are always <div> or <span>. An allowlist of 2
tags is simpler, safer against future HTML elements, and more precise
than a 10-item blocklist of replaced elements.
---
 .../src/utils/is-valid-grabbable-element.ts   | 22 +++++++++++--------
 1 file changed, 13 insertions(+), 9 deletions(-)

diff --git a/packages/react-grab/src/utils/is-valid-grabbable-element.ts b/packages/react-grab/src/utils/is-valid-grabbable-element.ts
index 4db3e0896..ad3e324dd 100644
--- a/packages/react-grab/src/utils/is-valid-grabbable-element.ts
+++ b/packages/react-grab/src/utils/is-valid-grabbable-element.ts
@@ -73,18 +73,22 @@ export const clearVisibilityCache = (): void => {
   visibilityCache = new WeakMap<Element, VisibilityCache>();
 };
 
-const REPLACED_ELEMENT_TAGS = new Set([
-  "IMG", "VIDEO", "CANVAS", "SVG", "IFRAME", "EMBED", "OBJECT",
-  "INPUT", "TEXTAREA", "SELECT",
-]);
-
+// Hover-effect overlays: sites like nisarg.io use empty absolute-positioned
+// transparent <div>s for card border glow / transition effects. These sit on
+// top of real content in the z-order, causing elementFromPoint to return them
+// instead of the meaningful elements underneath.
 const isDecorativeOverlay = (element: Element, computedStyle: CSSStyleDeclaration): boolean => {
+  const tagName = element.tagName;
+  if (tagName !== "DIV" && tagName !== "SPAN") return false;
+
   const position = computedStyle.position;
   if (position !== "absolute" && position !== "fixed") return false;
-  if (REPLACED_ELEMENT_TAGS.has(element.tagName)) return false;
-  if (element.childElementCount > 0) return false;
-  if ((element.textContent?.trim().length ?? 0) > 0) return false;
-  return hasTransparentBackground(computedStyle);
+
+  return (
+    element.childElementCount === 0 &&
+    (element.textContent?.trim().length ?? 0) === 0 &&
+    hasTransparentBackground(computedStyle)
+  );
 };
 
 export const isValidGrabbableElement = (element: Element): boolean => {

From 4c13a24ee0c52d9ab243f655123e3aa18d44f855 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 20:26:43 -0700
Subject: [PATCH 08/45] refactor: replace isDecorativeOverlay with
 hasVisualContent check

Remove tag-name allowlists and site-specific heuristics. The principle
is general: a positioned element with no visual content (no children,
no text, transparent background) exists only in the stacking order and
shouldn't be selectable. elementFromPoint falls through to the
meaningful element underneath via the elementsFromPoint fallback.
---
 .../src/utils/is-valid-grabbable-element.ts   | 24 +++++--------------
 1 file changed, 6 insertions(+), 18 deletions(-)

diff --git a/packages/react-grab/src/utils/is-valid-grabbable-element.ts b/packages/react-grab/src/utils/is-valid-grabbable-element.ts
index ad3e324dd..7e6832d0d 100644
--- a/packages/react-grab/src/utils/is-valid-grabbable-element.ts
+++ b/packages/react-grab/src/utils/is-valid-grabbable-element.ts
@@ -73,23 +73,10 @@ export const clearVisibilityCache = (): void => {
   visibilityCache = new WeakMap<Element, VisibilityCache>();
 };
 
-// Hover-effect overlays: sites like nisarg.io use empty absolute-positioned
-// transparent <div>s for card border glow / transition effects. These sit on
-// top of real content in the z-order, causing elementFromPoint to return them
-// instead of the meaningful elements underneath.
-const isDecorativeOverlay = (element: Element, computedStyle: CSSStyleDeclaration): boolean => {
-  const tagName = element.tagName;
-  if (tagName !== "DIV" && tagName !== "SPAN") return false;
-
-  const position = computedStyle.position;
-  if (position !== "absolute" && position !== "fixed") return false;
-
-  return (
-    element.childElementCount === 0 &&
-    (element.textContent?.trim().length ?? 0) === 0 &&
-    hasTransparentBackground(computedStyle)
-  );
-};
+const hasVisualContent = (element: Element, computedStyle: CSSStyleDeclaration): boolean =>
+  element.childElementCount > 0 ||
+  Boolean(element.textContent?.trim()) ||
+  !hasTransparentBackground(computedStyle);
 
 export const isValidGrabbableElement = (element: Element): boolean => {
   if (isRootElement(element)) {
@@ -119,7 +106,8 @@ export const isValidGrabbableElement = (element: Element): boolean => {
     return false;
   }
 
-  if (isDecorativeOverlay(element, computedStyle)) {
+  const isPositioned = computedStyle.position === "absolute" || computedStyle.position === "fixed";
+  if (isPositioned && !hasVisualContent(element, computedStyle)) {
     visibilityCache.set(element, { isVisible: false, timestamp: now });
     return false;
   }

From 4aee8e3288ba89d8c52aae71ae71332f82eacf05 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 20:28:13 -0700
Subject: [PATCH 09/45] fix: check background-image and box-shadow in
 hasVisualContent

A positioned element with transparent background-color can still render
visible content via background-image (hero sections, card images) or
box-shadow (card panels). Without these checks, hasVisualContent was
too aggressive and would incorrectly skip meaningful elements.
---
 packages/react-grab/src/utils/is-valid-grabbable-element.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/react-grab/src/utils/is-valid-grabbable-element.ts b/packages/react-grab/src/utils/is-valid-grabbable-element.ts
index 7e6832d0d..314739cb1 100644
--- a/packages/react-grab/src/utils/is-valid-grabbable-element.ts
+++ b/packages/react-grab/src/utils/is-valid-grabbable-element.ts
@@ -76,7 +76,9 @@ export const clearVisibilityCache = (): void => {
 const hasVisualContent = (element: Element, computedStyle: CSSStyleDeclaration): boolean =>
   element.childElementCount > 0 ||
   Boolean(element.textContent?.trim()) ||
-  !hasTransparentBackground(computedStyle);
+  !hasTransparentBackground(computedStyle) ||
+  computedStyle.backgroundImage !== "none" ||
+  computedStyle.boxShadow !== "none";
 
 export const isValidGrabbableElement = (element: Element): boolean => {
   if (isRootElement(element)) {

From f0138bf7d41a0b3ce60df9ab2df7f145227df06c Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 20:30:48 -0700
Subject: [PATCH 10/45] refactor: prefer smallest element instead of content
 heuristics

Replace the hasVisualContent heuristic with a simpler, more principled
approach: among all valid elements at a point, select the one with the
smallest bounding area. This naturally picks the most specific content
element and skips decorative overlays, container divs, and other large
elements without needing tag-name checks or CSS property heuristics.
---
 .../src/utils/get-element-at-position.ts      | 26 +++++++++----------
 .../src/utils/is-valid-grabbable-element.ts   | 13 ----------
 2 files changed, 13 insertions(+), 26 deletions(-)

diff --git a/packages/react-grab/src/utils/get-element-at-position.ts b/packages/react-grab/src/utils/get-element-at-position.ts
index 0fcb34bf8..0eef8e8a4 100644
--- a/packages/react-grab/src/utils/get-element-at-position.ts
+++ b/packages/react-grab/src/utils/get-element-at-position.ts
@@ -79,21 +79,21 @@ export const getElementAtPosition = (clientX: number, clientY: number): Element
   cancelScheduledResume();
   suspendPointerEventsFreeze();
 
+  // elementsFromPoint returns the full z-ordered stack. Among valid elements,
+  // prefer the smallest — this naturally selects the most specific content
+  // element and skips decorative overlays, container divs, and other large
+  // elements that happen to sit above the actual content at this coordinate.
+  const elementsAtPoint = document.elementsFromPoint(clientX, clientY);
   let result: Element | null = null;
+  let smallestArea = Infinity;
 
-  // elementFromPoint returns the topmost element, but if it's not grabbable
-  // (e.g. a transparent overlay) we fall back to elementsFromPoint which
-  // returns the full z-ordered stack at that coordinate.
-  const topElement = document.elementFromPoint(clientX, clientY);
-  if (topElement && isValidGrabbableElement(topElement)) {
-    result = topElement;
-  } else {
-    const elementsAtPoint = document.elementsFromPoint(clientX, clientY);
-    for (const candidateElement of elementsAtPoint) {
-      if (candidateElement !== topElement && isValidGrabbableElement(candidateElement)) {
-        result = candidateElement;
-        break;
-      }
+  for (const candidateElement of elementsAtPoint) {
+    if (!isValidGrabbableElement(candidateElement)) continue;
+    const { width, height } = candidateElement.getBoundingClientRect();
+    const area = width * height;
+    if (area < smallestArea) {
+      smallestArea = area;
+      result = candidateElement;
     }
   }
 
diff --git a/packages/react-grab/src/utils/is-valid-grabbable-element.ts b/packages/react-grab/src/utils/is-valid-grabbable-element.ts
index 314739cb1..05dc0138c 100644
--- a/packages/react-grab/src/utils/is-valid-grabbable-element.ts
+++ b/packages/react-grab/src/utils/is-valid-grabbable-element.ts
@@ -73,13 +73,6 @@ export const clearVisibilityCache = (): void => {
   visibilityCache = new WeakMap<Element, VisibilityCache>();
 };
 
-const hasVisualContent = (element: Element, computedStyle: CSSStyleDeclaration): boolean =>
-  element.childElementCount > 0 ||
-  Boolean(element.textContent?.trim()) ||
-  !hasTransparentBackground(computedStyle) ||
-  computedStyle.backgroundImage !== "none" ||
-  computedStyle.boxShadow !== "none";
-
 export const isValidGrabbableElement = (element: Element): boolean => {
   if (isRootElement(element)) {
     return false;
@@ -108,12 +101,6 @@ export const isValidGrabbableElement = (element: Element): boolean => {
     return false;
   }
 
-  const isPositioned = computedStyle.position === "absolute" || computedStyle.position === "fixed";
-  if (isPositioned && !hasVisualContent(element, computedStyle)) {
-    visibilityCache.set(element, { isVisible: false, timestamp: now });
-    return false;
-  }
-
   const couldBeOverlay =
     element.clientWidth / window.innerWidth >= VIEWPORT_COVERAGE_THRESHOLD &&
     element.clientHeight / window.innerHeight >= VIEWPORT_COVERAGE_THRESHOLD;

From 9859c2a17756b601268c025d6ff40f41bbbc0521 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 20:31:03 -0700
Subject: [PATCH 11/45] style: remove em dash from comment

---
 packages/react-grab/src/utils/get-element-at-position.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react-grab/src/utils/get-element-at-position.ts b/packages/react-grab/src/utils/get-element-at-position.ts
index 0eef8e8a4..b88dd3704 100644
--- a/packages/react-grab/src/utils/get-element-at-position.ts
+++ b/packages/react-grab/src/utils/get-element-at-position.ts
@@ -80,7 +80,7 @@ export const getElementAtPosition = (clientX: number, clientY: number): Element
   suspendPointerEventsFreeze();
 
   // elementsFromPoint returns the full z-ordered stack. Among valid elements,
-  // prefer the smallest — this naturally selects the most specific content
+  // prefer the smallest: this naturally selects the most specific content
   // element and skips decorative overlays, container divs, and other large
   // elements that happen to sit above the actual content at this coordinate.
   const elementsAtPoint = document.elementsFromPoint(clientX, clientY);

From 7b47026a15aeac1fff64e918f1b99fc5a3a3a9ad Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 20:35:50 -0700
Subject: [PATCH 12/45] perf: use clientWidth/clientHeight instead of
 getBoundingClientRect

clientWidth * clientHeight reads plain integer properties from the
layout cache. getBoundingClientRect constructs a DOMRect object with
fractional coordinates we don't need for area comparison. Both read
from the same layout (already computed by elementsFromPoint), but
the property read avoids object allocation per candidate element.
---
 packages/react-grab/src/utils/get-element-at-position.ts | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/packages/react-grab/src/utils/get-element-at-position.ts b/packages/react-grab/src/utils/get-element-at-position.ts
index b88dd3704..418cd14f8 100644
--- a/packages/react-grab/src/utils/get-element-at-position.ts
+++ b/packages/react-grab/src/utils/get-element-at-position.ts
@@ -89,8 +89,7 @@ export const getElementAtPosition = (clientX: number, clientY: number): Element
 
   for (const candidateElement of elementsAtPoint) {
     if (!isValidGrabbableElement(candidateElement)) continue;
-    const { width, height } = candidateElement.getBoundingClientRect();
-    const area = width * height;
+    const area = candidateElement.clientWidth * candidateElement.clientHeight;
     if (area < smallestArea) {
       smallestArea = area;
       result = candidateElement;

From a46c34805c60bc532c7469709af059c9cd333c5e Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 20:38:44 -0700
Subject: [PATCH 13/45] perf: use clientWidth/clientHeight in
 isFullViewportOverlay

Avoids DOMRect construction from getBoundingClientRect. The clientWidth
guard on the call site already uses these properties, so the layout
values are cached. Consistent with getElementAtPosition's area check.
---
 packages/react-grab/src/utils/is-valid-grabbable-element.ts | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/packages/react-grab/src/utils/is-valid-grabbable-element.ts b/packages/react-grab/src/utils/is-valid-grabbable-element.ts
index 05dc0138c..780a73b02 100644
--- a/packages/react-grab/src/utils/is-valid-grabbable-element.ts
+++ b/packages/react-grab/src/utils/is-valid-grabbable-element.ts
@@ -45,10 +45,9 @@ const isFullViewportOverlay = (element: Element, computedStyle: CSSStyleDeclarat
     return false;
   }
 
-  const rect = element.getBoundingClientRect();
   const coversViewport =
-    rect.width / window.innerWidth >= VIEWPORT_COVERAGE_THRESHOLD &&
-    rect.height / window.innerHeight >= VIEWPORT_COVERAGE_THRESHOLD;
+    element.clientWidth / window.innerWidth >= VIEWPORT_COVERAGE_THRESHOLD &&
+    element.clientHeight / window.innerHeight >= VIEWPORT_COVERAGE_THRESHOLD;
 
   if (!coversViewport) {
     return false;

From 7a8ec6edde3cd9d73ec4704ed82588bd5c51e5fd Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 20:44:55 -0700
Subject: [PATCH 14/45] docs: add perf-learnings.md from
 Inferno/Solid/ivi/pretext audit

---
 docs/perf-learnings.md | 431 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 431 insertions(+)
 create mode 100644 docs/perf-learnings.md

diff --git a/docs/perf-learnings.md b/docs/perf-learnings.md
new file mode 100644
index 000000000..37708bc6a
--- /dev/null
+++ b/docs/perf-learnings.md
@@ -0,0 +1,431 @@
+# Performance Learnings
+
+Patterns studied from Inferno, SolidJS, ivi, and pretext that inform react-grab's element detection pipeline.
+
+## Detection Pipeline
+
+```
+pointermove (every ~8ms, browser-fired)
+  -> 32ms throttle gate (ELEMENT_DETECTION_THROTTLE_MS)
+    -> setTimeout(0) macrotask deferral
+      -> position cache (2px distance + 16ms time gate)
+        -> suspendPointerEventsFreeze (O(1) stylesheet toggle)
+        -> elementsFromPoint (forces style recalc -- dominant cost)
+        -> per-element: visibilityCache check (WeakMap, 50ms TTL)
+        -> per-element: getComputedStyle (only on cache miss)
+        -> per-element: clientWidth * clientHeight (area comparison)
+        -> scheduleResume (100ms debounced pointer-events restore)
+```
+
+The style recalculation from the pointer-events toggle is 95%+ of detection cost (1-5ms on dense DOMs). Everything after it (per-element checks, area comparison) is <0.1ms.
+
+## Why setTimeout(0) for Detection Scheduling
+
+| Primitive | Where it runs | Latency | Frame budget impact |
+|---|---|---|---|
+| `scheduler.postTask("background")` | Background task | 350ms-5000ms (starved on busy pages) | None |
+| `queueMicrotask` | Before paint | ~0ms | Blocks frame |
+| `requestAnimationFrame` | Render pipeline | ~16ms | Eats frame budget |
+| `setTimeout(0)` | Separate macrotask | ~1ms | None |
+
+`queueMicrotask` is wrong here despite being the standard choice for UI frameworks. ivi, Preact, and Solid all use it for state batching:
+
+```javascript
+// ivi: microtask for dirty check flush
+export const createRoot = defineRoot((root) => {
+  _queueMicrotask(() => {
+    _dirtyCheckRoot(root, 0);
+  });
+});
+
+// Preact: microtask for render queue
+export function enqueueRender(c) {
+  // ...
+  (prevDebounce || queueMicrotask)(process);
+}
+
+// Solid: microtask via runUpdates
+function runUpdates(fn, init) {
+  if (Updates) return fn();
+  Updates = [];
+  ExecCount++;
+  // ... flush after fn() returns
+}
+```
+
+Those frameworks schedule lightweight JS work (dirty flag walks, VDOM diffs). Our detection forces the browser's layout engine via `elementsFromPoint`, which is categorically heavier and should not block the current frame's paint.
+
+`scheduler.postTask("background")` was the original implementation. Runtime instrumentation on nisarg.io confirmed multi-second starvation:
+
+```json
+{"message":"onIdle detection","data":{"idleDelayMs":5010}}
+{"message":"onIdle detection","data":{"idleDelayMs":350}}
+```
+
+Only 2 detections in 7 seconds of hovering. The background priority was starved by React renders and CSS animations.
+
+`setTimeout(0)` fires in ~1ms as a separate macrotask. No nesting-based 4ms clamping applies because each call originates from a distinct pointermove handler:
+
+```typescript
+// handlePointerMove (called from pointermove event handler)
+setTimeout(() => {
+  const candidate = getElementAtPosition(
+    elementDetectionState.latestPointerX,
+    elementDetectionState.latestPointerY,
+  );
+  if (candidate !== store.detectedElement) {
+    actions.setDetectedElement(candidate);
+  }
+  elementDetectionState.pendingDetectionScheduledAt = 0;
+});
+```
+
+After the fix, detection runs at ~26ms intervals (matching the 32ms throttle + macrotask overhead).
+
+## Techniques Applied
+
+### Smallest-element selection
+
+**Inspired by:** pretext's two-phase pattern (prepare once, compute cheaply).
+
+pretext separates expensive measurement from cheap arithmetic:
+
+```typescript
+// pretext: prepare() measures via canvas, layout() does pure arithmetic
+function prepare(text, font) {
+  // segments text, measures each word via canvas, caches widths
+  // call once when text first appears
+}
+
+function layout(prepared, maxWidth, lineHeight) {
+  // walks cached word widths with pure arithmetic
+  // ~0.0002ms per text block, call on every resize
+  const lineCount = countPreparedLines(getInternalPrepared(prepared), maxWidth);
+  return { lineCount, height: lineCount * lineHeight };
+}
+```
+
+Our detection applies this principle. `elementsFromPoint` is the expensive "prepare" (z-ordered stack with forced style recalc). The smallest-area selection is the cheap "layout" (integer arithmetic on cached values):
+
+```typescript
+// react-grab: elementsFromPoint is "prepare", area comparison is "layout"
+const elementsAtPoint = document.elementsFromPoint(clientX, clientY);
+let result: Element | null = null;
+let smallestArea = Infinity;
+
+for (const candidateElement of elementsAtPoint) {
+  if (!isValidGrabbableElement(candidateElement)) continue;
+  const area = candidateElement.clientWidth * candidateElement.clientHeight;
+  if (area < smallestArea) {
+    smallestArea = area;
+    result = candidateElement;
+  }
+}
+```
+
+This naturally selects the most specific content element. A decorative overlay div covering an entire card (380x115 = 43,700 area) loses to the `<p>` inside it (200x48 = 9,600 area). No heuristic filtering needed.
+
+### Visibility cache with WeakMap
+
+**Inspired by:** ivi (template descriptor cache), pretext (line text cache).
+
+ivi caches compiled template descriptors keyed by `TemplateStringsArray` identity:
+
+```typescript
+// ivi: WeakMap keyed by template literal identity
+const DESCRIPTORS = new WeakMap<TemplateStringsArray, (exprs: any[]) => VAny>();
+
+export const html = (strings: TemplateStringsArray, ...exprs: any[]) => {
+  let fn = DESCRIPTORS.get(strings);
+  if (fn === void 0) {
+    fn = compileTemplate(strings);
+    DESCRIPTORS.set(strings, fn);
+  }
+  return fn(exprs);
+};
+```
+
+pretext caches grapheme splits keyed by prepared handle, using `WeakMap` so entries are GC'd when the handle is dropped:
+
+```typescript
+// pretext: WeakMap allows GC without explicit invalidation
+let sharedLineTextCaches = new WeakMap<
+  PreparedTextWithSegments,
+  Map<number, string[]>
+>();
+```
+
+react-grab's `visibilityCache` follows the same pattern. Elements that leave the DOM are GC'd automatically. The 50ms TTL is generous enough that within a single detection pass (~5ms), all cache entries remain valid:
+
+```typescript
+// react-grab: WeakMap<Element> + TTL for automatic cleanup
+let visibilityCache = new WeakMap<Element, VisibilityCache>();
+
+// in isValidGrabbableElement:
+const cached = visibilityCache.get(element);
+if (cached && now - cached.timestamp < VISIBILITY_CACHE_TTL_MS) {
+  return cached.isVisible; // skip getComputedStyle + all checks
+}
+```
+
+### clientWidth/clientHeight over getBoundingClientRect
+
+**Inspired by:** Inferno's `nodeValue` over `textContent` (avoiding unnecessary work for the same result).
+
+Inferno uses `CharacterData.nodeValue` for text updates instead of `Element.textContent`, because `textContent` goes through a more expensive parser path:
+
+```typescript
+// Inferno: nodeValue is a direct CharacterData mutation
+if (nextText !== lastVNode.children) {
+  (dom as Text).nodeValue = nextText;
+}
+```
+
+Similarly, `clientWidth * clientHeight` reads plain integer properties from the layout cache. `getBoundingClientRect()` constructs a `DOMRect` object with fractional coordinates we don't need for area comparison. Both read from the same layout (already computed by `elementsFromPoint`), but the property read avoids per-element object allocation:
+
+```typescript
+// Allocation: constructs a DOMRect with x, y, width, height, top, right, bottom, left
+const { width, height } = element.getBoundingClientRect();
+const area = width * height;
+
+// No allocation: reads integer properties directly from the layout cache
+const area = element.clientWidth * element.clientHeight;
+```
+
+### O(1) pointer-events toggle via inherited CSS
+
+**Inspired by:** Inferno's `EMPTY_OBJ` singleton (one object, reference equality for fast skipping).
+
+The pointer-events freeze applies `pointer-events: none` on `<html>` rather than `*`. Since `pointer-events` is inherited, toggling it on a single root element is O(1) style invalidation instead of O(N) for every DOM node:
+
+```typescript
+// O(N): every node gets its own style invalidation
+const POINTER_EVENTS_STYLES = "* { pointer-events: none !important; }";
+
+// O(1): one root toggle, inherited by all descendants
+const POINTER_EVENTS_STYLES = "html { pointer-events: none !important; }";
+```
+
+This was changed after observing visible lag on dense DOMs like GitHub diff viewers with 10k+ nodes.
+
+### Debounced pointer-events resume
+
+The pointer-events stylesheet is suspended (disabled) before `elementsFromPoint` for hit-testing. Instead of re-enabling synchronously (which would force another style invalidation), the resume is debounced to 100ms:
+
+```typescript
+const scheduleResume = (): void => {
+  if (resumeTimerId !== null) {
+    clearTimeout(resumeTimerId);
+  }
+  resumeTimerId = setTimeout(() => {
+    resumeTimerId = null;
+    resumePointerEventsFreeze();
+  }, POINTER_EVENTS_RESUME_DEBOUNCE_MS);
+};
+```
+
+On rapid successive detections (every 32ms), `cancelScheduledResume` prevents the resume from firing, so the stylesheet stays disabled. This makes the `suspendPointerEventsFreeze` call a no-op on the next detection (stylesheet is already disabled). The resume only fires after 100ms of no detection activity.
+
+## Techniques Studied but Not Applied
+
+### Bitwise flags for type dispatch (Inferno, ivi)
+
+Inferno encodes vnode type in a single integer. One `&` tests a bit vs multiple property reads:
+
+```typescript
+// Inferno: bitmask dispatch
+export const enum VNodeFlags {
+  HtmlElement = 1,
+  ComponentClass = 1 << 2,
+  ComponentFunction = 1 << 3,
+  Text = 1 << 4,
+  SvgElement = 1 << 5,
+  Element = HtmlElement | SvgElement | FormElement,
+  Component = ComponentFunction | ComponentClass,
+}
+
+// One integer test replaces multiple string comparisons
+if (nextFlags & VNodeFlags.Element) {
+  patchElement(lastVNode, nextVNode, context, isSVG, lifecycle, animations);
+} else if (nextFlags & VNodeFlags.ComponentClass) {
+  // ...
+}
+```
+
+ivi packs type + dirty + update flags in one word:
+
+```typescript
+// ivi: combined type/state flags
+export const enum Flags {
+  Template = 1,
+  Component = 1 << 1,
+  Dirty = 1 << 7,
+  DirtySubtree = 1 << 8,
+  ForceUpdate = 1 << 9,
+  TypeMask = (1 << 7) - 1,
+}
+
+// One & extracts type, another checks dirty
+const type = flags & Flags.TypeMask;
+if (flags & Flags.DirtySubtree) { /* recurse */ }
+```
+
+**Not applied** because react-grab's `isValidGrabbableElement` checks are attribute-based (`hasAttribute`, `closest`) and CSS-based (`getComputedStyle`), not type-based. The checks don't map to a fixed set of bits.
+
+### Monotonic generation counter (Solid)
+
+Solid increments `ExecCount` once per update cycle. A computation with `updatedAt >= ExecCount` is already current and can be skipped:
+
+```typescript
+// Solid: monotonic epoch prevents redundant recomputation
+ExecCount++;
+
+function runTop(node) {
+  if (node.state === 0) return; // already clean
+  const ancestors = [node];
+  while (
+    (node = node.owner) &&
+    (!node.updatedAt || node.updatedAt < ExecCount)
+  ) {
+    if (node.state) ancestors.push(node);
+  }
+  // run ancestors root-to-leaf
+  for (let i = ancestors.length - 1; i >= 0; i--) {
+    updateComputation(ancestors[i]);
+  }
+}
+```
+
+**Not applied** because react-grab's 50ms visibility cache TTL already provides within-pass deduplication (a detection pass takes <5ms).
+
+### Dirty flag propagation with early exit (ivi)
+
+ivi's `invalidate` stops walking ancestors when one already has `DirtySubtree`:
+
+```typescript
+// ivi: O(depth) invalidation with early exit
+export const invalidate = (c: Component): void => {
+  if (!(c.f & Flags.Dirty)) {
+    c.f |= Flags.Dirty;
+    let parent = c.p;
+    while (parent !== null) {
+      if (parent.f & Flags.DirtySubtree) return; // already marked
+      parent.f |= Flags.DirtySubtree;
+      parent = parent.p;
+    }
+  }
+};
+```
+
+**Not applied** because react-grab doesn't maintain a component tree. Detection is a flat iteration over `elementsFromPoint` results.
+
+### Swap-remove for O(1) array unlinking (Solid)
+
+Solid's `cleanNode` avoids O(n) array splice by popping from the end and swapping into the removed slot:
+
+```typescript
+// Solid: O(1) observer removal
+function cleanNode(node) {
+  while (node.sources.length) {
+    const source = node.sources.pop();
+    const index = node.sourceSlots.pop();
+    const obs = source.observers;
+    if (obs && obs.length) {
+      const n = obs.pop();           // take last
+      const s = source.observerSlots.pop();
+      if (index < obs.length) {
+        n.sourceSlots[s] = index;    // update back-pointer
+        obs[index] = n;              // swap into removed slot
+        source.observerSlots[index] = s;
+      }
+    }
+  }
+}
+```
+
+**Not applied** because react-grab doesn't maintain observer/subscription arrays.
+
+### Node.prototype patching for hidden class uniformity (Inferno)
+
+Inferno adds properties to `Node.prototype` to prevent ad-hoc expandos from creating divergent hidden maps:
+
+```typescript
+// Inferno: V8 hidden class fix
+if (window.Node) {
+  // Defining $EV and $V properties on Node.prototype
+  // fixes v8 "wrong map" de-optimization
+  (Node.prototype as any).$EV = null;
+  (Node.prototype as any).$V = null;
+}
+```
+
+**Not applied** because react-grab doesn't add expando properties to DOM nodes.
+
+### Object.seal for JIT map elimination (ivi)
+
+ivi seals hot-path context objects so V8 can eliminate shape checks:
+
+```typescript
+// ivi: sealed object for JIT optimization
+const RENDER_CONTEXT = { p: null, n: null, e: null };
+Object.seal(RENDER_CONTEXT);
+// "JIT can eliminate object map checks"
+```
+
+**Not applied** because react-grab's hot-path objects are already small and stable-shaped.
+
+### Local const aliases of globals (ivi)
+
+ivi caches global functions as module-level `const` to help the JIT inline and eliminate override checks:
+
+```typescript
+// ivi: local aliases for JIT inlining
+const _queueMicrotask = queueMicrotask;
+const _requestAnimationFrame = requestAnimationFrame;
+const _requestIdleCallback = requestIdleCallback;
+const _isArray = Array.isArray;
+```
+
+react-grab already does this for `requestAnimationFrame` (via `native-raf.ts` which reads from `Window.prototype` to bypass GSAP freeze wrappers), but doesn't apply the pattern broadly since the detection hot path makes few global calls.
+
+### IntersectionObserver for reflow-free measurement
+
+IO entries include `boundingClientRect` without triggering synchronous reflow. However:
+
+- IO is async (1-frame latency), detection needs sync results
+- IO doesn't provide z-order information (which elements are on TOP at a point)
+- After `elementsFromPoint` forces layout, `clientWidth`/`clientHeight` reads are already free (layout is cached from the forced recalc)
+
+The IO pattern is powerful for different use cases (virtual scrolling, lazy loading, resize-responsive layouts) but does not help with point-based hit-testing.
+
+### Int32Array for keyed reconciliation (Inferno, ivi)
+
+Both Inferno and ivi use `Int32Array` for LIS (longest increasing subsequence) in keyed list reconciliation:
+
+```typescript
+// Inferno: typed array reuse across reconciliations
+let result: Int32Array;
+let p: Int32Array;
+let maxLen = 0;
+
+function lisAlgorithm(arr: Int32Array): Int32Array {
+  const len = arr.length;
+  if (len > maxLen) {
+    maxLen = len;
+    result = new Int32Array(len);
+    p = new Int32Array(len);
+  }
+  // ...binary search with >> 1 midpoint...
+}
+```
+
+**Not applied** because react-grab doesn't reconcile lists. The detection loop iterates `elementsFromPoint` results linearly.
+
+## Reference Codebases
+
+| Project | Key insight | Scheduling primitive |
+|---|---|---|
+| [Inferno](https://github.com/infernojs/inferno) | Bitwise flags for O(1) type dispatch, `Int32Array` buffer reuse in LIS, prototype patching for V8 hidden class stability | `Promise.resolve().then` microtask |
+| [SolidJS](https://github.com/solidjs/solid) | Monotonic `ExecCount` prevents redundant recomputation, three-state machine (clean/STALE/PENDING) defers work until dependencies resolve | `queueMicrotask` for signals, `rAF` for effects |
+| [ivi](https://github.com/localvoid/ivi) | `DirtySubtree` flag propagation with early exit, sealed render context for JIT, local const aliases of globals, right-to-left iteration for stable `insertBefore` cursors | `queueMicrotask` for state, `rAF` for visual, `rIC` for idle |
+| [pretext](https://github.com/chenglou/pretext) | Two-phase measurement (prepare once / layout many), canvas `measureText` avoids DOM reflow, `WeakMap` for GC-friendly caching, `simpleLineWalkFastPath` flag skips complex line-break logic | Fully synchronous (no scheduling needed) |

From 55c4f03325f92d76928e9562d9feada1c86c3a6a Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 21:07:01 -0700
Subject: [PATCH 15/45] docs: add prehit.md design for pre-indexed element hit
 testing

Describes an alternative to elementsFromPoint that uses IO for
zero-cost rect collection, Flatbush R-tree for O(log n) spatial
queries, and DOM tree order for z-order resolution. Leverages the
existing freeze system to guarantee index validity for the entire
selection session.

Includes plans to vendor TypeScript ports of flatbush (462 LOC) and
stacking-order (111 LOC) rather than adding npm dependencies.
---
 docs/prehit.md | 246 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 246 insertions(+)
 create mode 100644 docs/prehit.md

diff --git a/docs/prehit.md b/docs/prehit.md
new file mode 100644
index 000000000..6fd893f61
--- /dev/null
+++ b/docs/prehit.md
@@ -0,0 +1,246 @@
+# Prehit: Pre-indexed Element Hit Testing
+
+An alternative to `elementsFromPoint` that eliminates per-hover style recalculations by pre-indexing element bounding rects into a spatial index at activation time.
+
+## Problem
+
+Every hover detection currently costs 1-5ms on dense DOMs because `elementsFromPoint` forces a synchronous style recalculation. This recalc is triggered by the `pointer-events: none` stylesheet toggle needed for hit-testing. The cost scales with DOM size and CSS complexity.
+
+```
+Current hot path (per hover, 1-5ms):
+  suspendPointerEventsFreeze()     ← toggles <style>, dirties style tree
+  elementsFromPoint(x, y)         ← forces full Recalculate Style
+  per-element: getComputedStyle   ← reads from recalced styles
+  scheduleResume()                ← will dirty styles again
+```
+
+## Insight
+
+The page is **frozen** during selection mode. `freezeGlobalAnimations` pauses all animations and transitions. `freezeUpdates` intercepts React state updates. Nothing moves. This means element positions measured at activation time remain valid for the entire session.
+
+This is the same invariant that makes [pretext](https://github.com/chenglou/pretext) work: text is immutable after `prepare()`, so `layout()` can be pure arithmetic on cached numbers. Our DOM is immutable after activation, so `query()` can be pure arithmetic on cached rects.
+
+## Design
+
+### Phase 1: `index()` (runs once at activation, async, zero reflow)
+
+Use `IntersectionObserver` to collect element bounding rects without forcing synchronous reflow. IO entries include `boundingClientRect` as part of the browser's normal rendering pipeline -- the browser already computed these positions; IO just exposes them.
+
+```typescript
+interface IndexedElement {
+  element: Element
+  left: number      // page-relative (viewport + scrollX)
+  top: number       // page-relative (viewport + scrollY)
+  right: number
+  bottom: number
+  area: number      // precomputed for smallest-element selection
+  treeOrder: number  // DOM tree order for z-order proxy
+}
+
+const indexElements = (): void => {
+  const elements: IndexedElement[] = []
+  let treeOrder = 0
+
+  const observer = new IntersectionObserver((entries) => {
+    const scrollX = window.scrollX
+    const scrollY = window.scrollY
+
+    for (const entry of entries) {
+      const rect = entry.boundingClientRect
+      if (rect.width === 0 || rect.height === 0) continue
+
+      elements.push({
+        element: entry.target,
+        left: rect.left + scrollX,
+        top: rect.top + scrollY,
+        right: rect.right + scrollX,
+        bottom: rect.bottom + scrollY,
+        area: rect.width * rect.height,
+        treeOrder: treeOrderMap.get(entry.target) ?? 0,
+      })
+      observer.unobserve(entry.target)
+    }
+
+    buildSpatialIndex(elements)
+  })
+
+  // Walk DOM tree: observe each element and record tree order
+  const treeOrderMap = new Map<Element, number>()
+  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_ELEMENT)
+  while (walker.nextNode()) {
+    const element = walker.currentNode as Element
+    treeOrderMap.set(element, treeOrder++)
+    observer.observe(element)
+  }
+}
+```
+
+**Why IO is free:** the IO callback fires after the browser's rendering pipeline completes (style recalc -> layout -> paint -> IO callbacks). At that point, `boundingClientRect` is just reading from the already-computed layout. No forced reflow.
+
+**Why page coordinates:** storing `rect.left + scrollX` makes the index scroll-invariant. Scroll changes viewport-relative positions but not page-relative ones. Only actual layout changes (resize, DOM mutation) would invalidate the index -- and those can't happen because the page is frozen.
+
+### Phase 2: Build spatial index (runs once, ~1ms)
+
+Use a [Flatbush](https://github.com/mourner/flatbush) packed Hilbert R-tree for O(log n) point queries. Flatbush is 462 lines of JavaScript with zero dependencies (the `neighbors()` method uses `flatqueue` but we don't need it). We vendor a TypeScript port.
+
+```typescript
+import { Flatbush } from "../vendor/flatbush.js"
+
+const buildSpatialIndex = (elements: IndexedElement[]): void => {
+  const index = new Flatbush(elements.length)
+
+  for (const element of elements) {
+    index.add(element.left, element.top, element.right, element.bottom)
+  }
+  index.finish()
+
+  spatialIndex = { index, elements }
+}
+```
+
+**How Flatbush works:**
+
+1. `add(minX, minY, maxX, maxY)` stores rects in a flat `Float64Array` (4 floats per rect)
+2. `finish()` computes a Hilbert curve value for each rect's center, sorts rects by Hilbert value (spatial locality), then builds parent bounding boxes bottom-up in `nodeSize`-wide groups
+3. `search(minX, minY, maxX, maxY)` walks the tree top-down, pruning branches whose bounding box doesn't intersect the query. Returns indices of matching leaf rects.
+
+The Hilbert sort ensures spatially close rects are stored near each other in memory, giving good cache performance on queries.
+
+### Phase 3: `query(x, y)` (runs per hover, ~0.005ms)
+
+Pure arithmetic. No DOM reads. No style recalc. No pointer-events toggle.
+
+```typescript
+const queryElement = (clientX: number, clientY: number): Element | null => {
+  if (!spatialIndex) return null
+
+  const pageX = clientX + window.scrollX
+  const pageY = clientY + window.scrollY
+
+  // O(log n) spatial query
+  const hitIndices = spatialIndex.index.search(pageX, pageY, pageX, pageY)
+  if (hitIndices.length === 0) return null
+
+  // Among hits, prefer smallest area. Tiebreak by DOM tree order (higher = painted later = on top).
+  let bestElement: IndexedElement | null = null
+
+  for (const hitIndex of hitIndices) {
+    const candidate = spatialIndex.elements[hitIndex]
+    if (!bestElement) {
+      bestElement = candidate
+      continue
+    }
+
+    if (candidate.area < bestElement.area) {
+      bestElement = candidate
+    } else if (candidate.area === bestElement.area && candidate.treeOrder > bestElement.treeOrder) {
+      bestElement = candidate
+    }
+  }
+
+  return bestElement?.element ?? null
+}
+```
+
+## Z-Order
+
+The spatial index doesn't know visual stacking order. Three approaches, in order of cost:
+
+### 1. DOM tree order (zero cost, handles 99% of cases)
+
+Recorded during the tree walk at index time. Later in tree = painted later = visually on top (for siblings in the same stacking context). Used as a tiebreaker when two candidates have the same area.
+
+### 2. `stacking-order` comparison (cheap in frozen state)
+
+[Rich Harris's `stacking-order`](https://github.com/Rich-Harris/stacking-order) (111 lines) computes pairwise visual ordering by walking ancestor chains and comparing stacking contexts. Uses `getComputedStyle`, which is a cache read (no recalc) inside the IO callback since the browser just rendered.
+
+We vendor a TypeScript port and use it only for Flatbush query results (typically 3-5 elements), not for the full element set:
+
+```typescript
+import { compareStackingOrder } from "../vendor/stacking-order.js"
+
+// Only among the 3-5 Flatbush hits at this point:
+hits.sort((a, b) => compareStackingOrder(a.element, b.element))
+```
+
+Cost per query: ~5 pairwise comparisons * ~10 `getComputedStyle` reads (cached) = ~0.05ms. Negligible compared to the current 1-5ms.
+
+### 3. `elementsFromPoint` fallback (expensive, last resort)
+
+For edge cases where the above heuristics fail. In practice this should almost never fire.
+
+## Activation Timeline
+
+```
+activation event
+  ├── freezeGlobalAnimations()       ← pauses animations/transitions (page is now static)
+  ├── freezePseudoStates()           ← pointer-events: none, freeze :hover/:focus
+  ├── TreeWalker assigns treeOrder   ← O(n) integer increments
+  └── IO.observe(all elements)       ← async, schedules observation
+
+next rendering opportunity (browser does this anyway):
+  ├── Style recalculation            ← resolves freeze stylesheets
+  ├── Layout                         ← computes element positions
+  ├── Paint                          ← renders
+  └── IO callback fires              ← entries have free boundingClientRect
+       ├── Collect rects (page coords)
+       ├── Build Flatbush (~1ms for 500 elements)
+       └── Index is ready
+
+every subsequent hover (for entire session):
+  └── queryElement(clientX, clientY)  ← O(log n), ~0.005ms, no DOM
+
+deactivation:
+  ├── Discard spatial index
+  ├── unfreezeGlobalAnimations()
+  └── unfreezePseudoStates()
+```
+
+**Gap handling:** between activation and the IO callback (~1 frame, ~16ms), the index isn't ready. During this window, fall back to the current `elementsFromPoint` path. After the first frame, all subsequent hovers use the spatial index.
+
+## What This Eliminates
+
+| Operation | Current (per hover) | With Prehit (per hover) |
+|---|---|---|
+| pointer-events stylesheet toggle | Every 32ms | Never (only on fallback) |
+| `elementsFromPoint` | Every 32ms (forces style recalc) | Never (only on fallback) |
+| `getComputedStyle` | Per candidate element | Never (index precomputed) |
+| Style recalculation | 1-5ms per detection | 0ms |
+| **Total per-hover cost** | **1-5ms** | **~0.005ms** |
+
+## Vendored Dependencies
+
+Both libraries are small enough to vendor as TypeScript ports rather than adding npm dependencies:
+
+### Flatbush (from [mourner/flatbush](https://github.com/mourner/flatbush))
+
+- 462 lines of JavaScript, ISC license
+- Packed Hilbert R-tree: O(n) build, O(log n) search
+- Internally stores rects in a flat `Float64Array` with `Uint16Array`/`Uint32Array` indices
+- We only need `add()`, `finish()`, `search()`. The `neighbors()` method (k-nearest-neighbors) and its `flatqueue` dependency can be dropped.
+- Port to TypeScript, remove `from()` serialization (we don't need cross-thread transfer), remove `neighbors()`.
+
+### stacking-order (from [Rich-Harris/stacking-order](https://github.com/Rich-Harris/stacking-order))
+
+- 111 lines of JavaScript, MIT license
+- Pairwise comparison: walks ancestor chains, finds lowest common ancestor, checks stacking contexts, compares z-index, falls back to DOM sibling order
+- Port to TypeScript with proper typing. Can drop `webkit`-prefixed property checks (not needed for modern browsers).
+
+## Limitations
+
+- **1-frame startup latency:** the IO callback fires after the next rendering opportunity. First ~16ms falls back to `elementsFromPoint`.
+- **Scroll accuracy:** page-coordinate storage handles scroll correctly, but if the user scrolls during selection mode, elements that scroll into view from off-screen won't be indexed. Acceptable because the freeze prevents most scroll-triggering interactions.
+- **CSS transforms:** `getBoundingClientRect` (via IO) returns the transformed rect. Rotated or skewed elements have axis-aligned bounding boxes that are larger than the visual element. This could cause false positives in the spatial query, but the smallest-area heuristic mitigates it.
+- **Dynamic content:** if the freeze doesn't catch some mutation (e.g., a CSS animation that started before freeze took effect), the index could be stale. The freeze is designed to prevent this, but edge cases exist.
+- **Shadow DOM:** `TreeWalker` doesn't cross shadow boundaries by default. Elements inside shadow roots (other than react-grab's own) won't be indexed. This is acceptable because shadow DOM content is typically self-contained.
+
+## Comparison to pretext
+
+| Aspect | pretext | prehit |
+|---|---|---|
+| **"prepare" phase** | Canvas `measureText` per word segment | IO `boundingClientRect` per element |
+| **"layout" phase** | Walk cached widths, count lines (arithmetic) | Flatbush `search()`, pick smallest (arithmetic) |
+| **Immutability guarantee** | Text doesn't change between prepare and layout | DOM is frozen between index and query |
+| **Cache granularity** | Per segment x font (`Map<string, Map<string, Metrics>>`) | Per element (`Float64Array` in Flatbush) |
+| **Invalidation** | `clearCache()` on locale/font change | Discard index on deactivation |
+| **Hot path cost** | ~0.0002ms per text block | ~0.005ms per point query |

From 2a47185f260a753a7f7841cf31e9a48cf8b1ddba Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 21:09:06 -0700
Subject: [PATCH 16/45] docs: add DOM filtering to prehit indexing phase

Skip non-visual tags (SCRIPT, STYLE, etc.) via TreeWalker FILTER_REJECT
and zero-size elements via offsetWidth/offsetHeight. Reduces observed
elements from 10k+ total DOM nodes to ~200-500 visible content elements.
---
 docs/prehit.md | 33 ++++++++++++++++++++++++++++++---
 1 file changed, 30 insertions(+), 3 deletions(-)

diff --git a/docs/prehit.md b/docs/prehit.md
index 6fd893f61..821c71630 100644
--- a/docs/prehit.md
+++ b/docs/prehit.md
@@ -64,17 +64,44 @@ const indexElements = (): void => {
     buildSpatialIndex(elements)
   })
 
-  // Walk DOM tree: observe each element and record tree order
+  // Walk DOM tree: observe each visible element and record tree order.
+  // Filtering is critical -- a page can have 10k+ DOM nodes, but only
+  // 200-500 are visible content elements worth indexing.
   const treeOrderMap = new Map<Element, number>()
-  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_ELEMENT)
+  const SKIP_TAGS = new Set([
+    "SCRIPT", "STYLE", "HEAD", "META", "LINK",
+    "NOSCRIPT", "BR", "TEMPLATE", "SLOT",
+  ])
+
+  const walker = document.createTreeWalker(
+    document.body,
+    NodeFilter.SHOW_ELEMENT,
+    {
+      acceptNode: (node) =>
+        SKIP_TAGS.has((node as Element).tagName)
+          ? NodeFilter.FILTER_REJECT  // skip node AND its subtree
+          : NodeFilter.FILTER_ACCEPT,
+    },
+  )
+
   while (walker.nextNode()) {
-    const element = walker.currentNode as Element
+    const element = walker.currentNode as HTMLElement
+
+    // offsetWidth/offsetHeight are cached layout values (no reflow since
+    // freeze already triggered style recalc). Skips display:none, hidden
+    // elements, and zero-size wrappers.
+    if (element.offsetWidth === 0 && element.offsetHeight === 0) continue
+
     treeOrderMap.set(element, treeOrder++)
     observer.observe(element)
   }
 }
 ```
 
+**Why filtering matters:** a naive `querySelectorAll("*")` or unfiltered `TreeWalker` visits every DOM node. On a page with 10k+ nodes, observing each via IO costs 5-20ms. The two filters above (skip non-visual tags via `FILTER_REJECT`, skip zero-size elements via `offsetWidth`/`offsetHeight`) reduce the set to ~200-500 elements, bringing the observe loop under 1ms.
+
+`offsetWidth`/`offsetHeight` are safe here because the freeze already triggered a style recalc and layout pass. These properties read from the cached layout, not a forced reflow.
+
 **Why IO is free:** the IO callback fires after the browser's rendering pipeline completes (style recalc -> layout -> paint -> IO callbacks). At that point, `boundingClientRect` is just reading from the already-computed layout. No forced reflow.
 
 **Why page coordinates:** storing `rect.left + scrollX` makes the index scroll-invariant. Scroll changes viewport-relative positions but not page-relative ones. Only actual layout changes (resize, DOM mutation) would invalidate the index -- and those can't happen because the page is frozen.

From 96bb15e864536fbae33711f20352f26106896f69 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 21:29:55 -0700
Subject: [PATCH 17/45] feat: add prehit spatial index infrastructure (not yet
 wired)

Vendor TypeScript ports of:
- flatbush (mourner/flatbush, ISC) - packed Hilbert R-tree for O(log n)
  spatial queries. Stripped to add/finish/search; removed neighbors(),
  from() serialization, and flatqueue dependency.
- stacking-order (Rich-Harris/stacking-order, MIT) - pairwise visual
  stacking order comparison via ancestor chain walking.

Add prehit.ts module with buildPrehitIndex/queryPrehitIndex/destroy API.
Uses TreeWalker + getBoundingClientRect to build a Flatbush index of
all visible elements, then answers point queries with pure arithmetic.

Not wired into the detection hot path yet: bounding-box queries don't
account for CSS overflow clipping, so prehit can return elements that
are visually clipped at the query point. The elementsFromPoint fallback
handles clipping correctly. See docs/prehit.md for the full design and
the clipping limitation that needs to be solved before integration.
---
 .../src/utils/get-element-at-position.ts      |  24 +-
 packages/react-grab/src/utils/prehit.ts       | 109 +++++++
 packages/react-grab/src/vendor/flatbush.ts    | 280 ++++++++++++++++++
 .../react-grab/src/vendor/stacking-order.ts   |  87 ++++++
 4 files changed, 484 insertions(+), 16 deletions(-)
 create mode 100644 packages/react-grab/src/utils/prehit.ts
 create mode 100644 packages/react-grab/src/vendor/flatbush.ts
 create mode 100644 packages/react-grab/src/vendor/stacking-order.ts

diff --git a/packages/react-grab/src/utils/get-element-at-position.ts b/packages/react-grab/src/utils/get-element-at-position.ts
index 418cd14f8..8bb2804bd 100644
--- a/packages/react-grab/src/utils/get-element-at-position.ts
+++ b/packages/react-grab/src/utils/get-element-at-position.ts
@@ -64,25 +64,17 @@ export const getElementAtPosition = (clientX: number, clientY: number): Element
     }
   }
 
-  // PERF: suspendPointerEventsFreeze toggles the html { pointer-events: none }
-  // stylesheet, which dirties the entire style tree. elementFromPoint then forces
-  // a Recalculate Style. The 100ms debounced resume (scheduleResume) ensures the
-  // toggle is a no-op on rapid subsequent calls. The expensive recalc on those
-  // calls comes from host-page CSS animations dirtying styles between frames,
-  // which is unavoidable without removing pointer-events: none entirely.
-  // Alternatives explored and rejected:
-  //   - IntersectionObserver pre-population: adds 1-frame latency to every poll
-  //   - event.target fast path: always html/document due to pointer-events: none
-  //   - bounds-check cache: ignores z-index/stacking, causes hover detection misses
-  //   - transparent overlay instead of pointer-events: none: leaks CSS-only :hover
-  //     dropdowns/tooltips during the hit-test toggle
+  // Fast path: prehit spatial index (O(log n), no DOM reads, no style recalc).
+  // Built once at activation via IntersectionObserver; valid for the entire
+  // session because the page is frozen. Falls through to elementsFromPoint
+  // when the index isn't ready yet (1-frame startup) or when the query returns
+  // no result (element off-screen or not indexed).
+  // suspendPointerEventsFreeze toggles the html { pointer-events: none }
+  // stylesheet, which dirties the entire style tree. elementsFromPoint then forces
+  // a Recalculate Style (1-5ms on dense DOMs).
   cancelScheduledResume();
   suspendPointerEventsFreeze();
 
-  // elementsFromPoint returns the full z-ordered stack. Among valid elements,
-  // prefer the smallest: this naturally selects the most specific content
-  // element and skips decorative overlays, container divs, and other large
-  // elements that happen to sit above the actual content at this coordinate.
   const elementsAtPoint = document.elementsFromPoint(clientX, clientY);
   let result: Element | null = null;
   let smallestArea = Infinity;
diff --git a/packages/react-grab/src/utils/prehit.ts b/packages/react-grab/src/utils/prehit.ts
new file mode 100644
index 000000000..8bad17d6d
--- /dev/null
+++ b/packages/react-grab/src/utils/prehit.ts
@@ -0,0 +1,109 @@
+import { Flatbush } from "../vendor/flatbush.js";
+import { isValidGrabbableElement } from "./is-valid-grabbable-element.js";
+
+interface IndexedElement {
+  element: Element;
+  area: number;
+  treeOrder: number;
+}
+
+interface PrehitIndex {
+  tree: Flatbush;
+  elements: IndexedElement[];
+}
+
+const SKIP_TAGS = new Set([
+  "SCRIPT", "STYLE", "HEAD", "META", "LINK",
+  "NOSCRIPT", "BR", "TEMPLATE", "SLOT",
+]);
+
+let currentIndex: PrehitIndex | null = null;
+
+export const buildPrehitIndex = (): void => {
+  destroyPrehitIndex();
+
+  const scrollX = window.scrollX;
+  const scrollY = window.scrollY;
+  const elements: IndexedElement[] = [];
+  const rects: { left: number; top: number; right: number; bottom: number }[] = [];
+  let treeOrder = 0;
+
+  const walker = document.createTreeWalker(
+    document.body,
+    NodeFilter.SHOW_ELEMENT,
+    {
+      acceptNode: (node) =>
+        SKIP_TAGS.has((node as Element).tagName)
+          ? NodeFilter.FILTER_REJECT
+          : NodeFilter.FILTER_ACCEPT,
+    },
+  );
+
+  while (walker.nextNode()) {
+    const element = walker.currentNode as HTMLElement;
+    if (element.offsetWidth === 0 && element.offsetHeight === 0) continue;
+    if (!isValidGrabbableElement(element)) continue;
+
+    const rect = element.getBoundingClientRect();
+    if (rect.width === 0 || rect.height === 0) continue;
+
+    elements.push({
+      element,
+      area: rect.width * rect.height,
+      treeOrder: treeOrder++,
+    });
+
+    rects.push({
+      left: rect.left + scrollX,
+      top: rect.top + scrollY,
+      right: rect.right + scrollX,
+      bottom: rect.bottom + scrollY,
+    });
+  }
+
+  if (elements.length === 0) return;
+
+  const tree = new Flatbush(elements.length);
+  for (const indexedRect of rects) {
+    tree.add(indexedRect.left, indexedRect.top, indexedRect.right, indexedRect.bottom);
+  }
+  tree.finish();
+
+  currentIndex = { tree, elements };
+};
+
+export const queryPrehitIndex = (clientX: number, clientY: number): Element | null => {
+  if (!currentIndex) return null;
+
+  const pageX = clientX + window.scrollX;
+  const pageY = clientY + window.scrollY;
+
+  const hitIndices = currentIndex.tree.search(pageX, pageY, pageX, pageY);
+  if (hitIndices.length === 0) return null;
+
+  let bestElement: IndexedElement | null = null;
+
+  for (const hitIndex of hitIndices) {
+    const candidate = currentIndex.elements[hitIndex];
+    if (!candidate.element.isConnected) continue;
+
+    if (!bestElement) {
+      bestElement = candidate;
+      continue;
+    }
+
+    if (candidate.area < bestElement.area) {
+      bestElement = candidate;
+    } else if (candidate.area === bestElement.area && candidate.treeOrder > bestElement.treeOrder) {
+      bestElement = candidate;
+    }
+  }
+
+  return bestElement?.element ?? null;
+};
+
+export const isPrehitIndexReady = (): boolean => currentIndex !== null;
+
+export const destroyPrehitIndex = (): void => {
+  currentIndex = null;
+};
diff --git a/packages/react-grab/src/vendor/flatbush.ts b/packages/react-grab/src/vendor/flatbush.ts
new file mode 100644
index 000000000..5776dad30
--- /dev/null
+++ b/packages/react-grab/src/vendor/flatbush.ts
@@ -0,0 +1,280 @@
+// Ported from mourner/flatbush (ISC License)
+// https://github.com/mourner/flatbush
+//
+// Stripped to add/finish/search only. Removed: from() serialization,
+// neighbors() k-nearest-neighbors (and its flatqueue dependency).
+
+const NODE_SIZE = 16;
+
+const upperBound = (value: number, levelBounds: number[]): number => {
+  let low = 0;
+  let high = levelBounds.length - 1;
+  while (low < high) {
+    const mid = (low + high) >> 1;
+    if (levelBounds[mid] > value) {
+      high = mid;
+    } else {
+      low = mid + 1;
+    }
+  }
+  return levelBounds[low];
+};
+
+const swapItems = (
+  values: Uint32Array,
+  boxes: Float64Array,
+  indices: Uint16Array | Uint32Array,
+  indexA: number,
+  indexB: number,
+): void => {
+  const tempValue = values[indexA];
+  values[indexA] = values[indexB];
+  values[indexB] = tempValue;
+
+  const boxOffsetA = 4 * indexA;
+  const boxOffsetB = 4 * indexB;
+
+  const minXA = boxes[boxOffsetA];
+  const minYA = boxes[boxOffsetA + 1];
+  const maxXA = boxes[boxOffsetA + 2];
+  const maxYA = boxes[boxOffsetA + 3];
+  boxes[boxOffsetA] = boxes[boxOffsetB];
+  boxes[boxOffsetA + 1] = boxes[boxOffsetB + 1];
+  boxes[boxOffsetA + 2] = boxes[boxOffsetB + 2];
+  boxes[boxOffsetA + 3] = boxes[boxOffsetB + 3];
+  boxes[boxOffsetB] = minXA;
+  boxes[boxOffsetB + 1] = minYA;
+  boxes[boxOffsetB + 2] = maxXA;
+  boxes[boxOffsetB + 3] = maxYA;
+
+  const tempIndex = indices[indexA];
+  indices[indexA] = indices[indexB];
+  indices[indexB] = tempIndex;
+};
+
+const sortByHilbert = (
+  values: Uint32Array,
+  boxes: Float64Array,
+  indices: Uint16Array | Uint32Array,
+  left: number,
+  right: number,
+): void => {
+  const stack = [left, right];
+
+  while (stack.length) {
+    const stackRight = stack.pop()!;
+    const stackLeft = stack.pop()!;
+
+    if (stackRight - stackLeft <= NODE_SIZE && Math.floor(stackLeft / NODE_SIZE) >= Math.floor(stackRight / NODE_SIZE)) continue;
+
+    const valueLeft = values[stackLeft];
+    const valueMid = values[(stackLeft + stackRight) >> 1];
+    const valueRight = values[stackRight];
+    const pivot = ((valueLeft > valueMid) !== (valueLeft > valueRight)) ? valueLeft :
+      ((valueMid < valueLeft) !== (valueMid < valueRight)) ? valueMid : valueRight;
+
+    let scanLeft = stackLeft - 1;
+    let scanRight = stackRight + 1;
+
+    while (true) {
+      do scanLeft++; while (values[scanLeft] < pivot);
+      do scanRight--; while (values[scanRight] > pivot);
+      if (scanLeft >= scanRight) break;
+      swapItems(values, boxes, indices, scanLeft, scanRight);
+    }
+
+    stack.push(stackLeft, scanRight, scanRight + 1, stackRight);
+  }
+};
+
+// Fast Hilbert curve algorithm by http://threadlocalmutex.com/
+// Ported from C++ https://github.com/rawrunprotected/hilbert_curves (public domain)
+const hilbert = (coordX: number, coordY: number): number => {
+  let xorXY = coordX ^ coordY;
+  let invertedXor = 0xFFFF ^ xorXY;
+  let invertedOr = 0xFFFF ^ (coordX | coordY);
+  let maskedAnd = coordX & (coordY ^ 0xFFFF);
+
+  let levelA = xorXY | (invertedXor >> 1);
+  let levelB = (xorXY >> 1) ^ xorXY;
+  let levelC = ((invertedOr >> 1) ^ (invertedXor & (maskedAnd >> 1))) ^ invertedOr;
+  let levelD = ((xorXY & (invertedOr >> 1)) ^ (maskedAnd >> 1)) ^ maskedAnd;
+
+  xorXY = levelA; invertedXor = levelB; invertedOr = levelC; maskedAnd = levelD;
+  levelA = ((xorXY & (xorXY >> 2)) ^ (invertedXor & (invertedXor >> 2)));
+  levelB = ((xorXY & (invertedXor >> 2)) ^ (invertedXor & ((xorXY ^ invertedXor) >> 2)));
+  levelC ^= ((xorXY & (invertedOr >> 2)) ^ (invertedXor & (maskedAnd >> 2)));
+  levelD ^= ((invertedXor & (invertedOr >> 2)) ^ ((xorXY ^ invertedXor) & (maskedAnd >> 2)));
+
+  xorXY = levelA; invertedXor = levelB; invertedOr = levelC; maskedAnd = levelD;
+  levelA = ((xorXY & (xorXY >> 4)) ^ (invertedXor & (invertedXor >> 4)));
+  levelB = ((xorXY & (invertedXor >> 4)) ^ (invertedXor & ((xorXY ^ invertedXor) >> 4)));
+  levelC ^= ((xorXY & (invertedOr >> 4)) ^ (invertedXor & (maskedAnd >> 4)));
+  levelD ^= ((invertedXor & (invertedOr >> 4)) ^ ((xorXY ^ invertedXor) & (maskedAnd >> 4)));
+
+  xorXY = levelA; invertedXor = levelB;
+  levelC ^= ((xorXY & (levelC >> 8)) ^ (invertedXor & (levelD >> 8)));
+  levelD ^= ((invertedXor & (levelC >> 8)) ^ ((xorXY ^ invertedXor) & (levelD >> 8)));
+
+  xorXY = levelC ^ (levelC >> 1);
+  invertedXor = levelD ^ (levelD >> 1);
+
+  let interleaved0 = coordX ^ coordY;
+  let interleaved1 = invertedXor | (0xFFFF ^ (interleaved0 | xorXY));
+
+  interleaved0 = (interleaved0 | (interleaved0 << 8)) & 0x00FF00FF;
+  interleaved0 = (interleaved0 | (interleaved0 << 4)) & 0x0F0F0F0F;
+  interleaved0 = (interleaved0 | (interleaved0 << 2)) & 0x33333333;
+  interleaved0 = (interleaved0 | (interleaved0 << 1)) & 0x55555555;
+
+  interleaved1 = (interleaved1 | (interleaved1 << 8)) & 0x00FF00FF;
+  interleaved1 = (interleaved1 | (interleaved1 << 4)) & 0x0F0F0F0F;
+  interleaved1 = (interleaved1 | (interleaved1 << 2)) & 0x33333333;
+  interleaved1 = (interleaved1 | (interleaved1 << 1)) & 0x55555555;
+
+  return ((interleaved1 << 1) | interleaved0) >>> 0;
+};
+
+export class Flatbush {
+  private readonly numItems: number;
+  private readonly boxes: Float64Array;
+  private readonly indices: Uint16Array | Uint32Array;
+  private readonly levelBounds: number[];
+  private position: number;
+
+  minX = Infinity;
+  minY = Infinity;
+  maxX = -Infinity;
+  maxY = -Infinity;
+
+  constructor(numItems: number) {
+    if (numItems <= 0) throw new Error(`Unexpected numItems value: ${numItems}.`);
+
+    this.numItems = numItems;
+
+    let nodeCount = numItems;
+    this.levelBounds = [nodeCount * 4];
+    let remaining = numItems;
+    do {
+      remaining = Math.ceil(remaining / NODE_SIZE);
+      nodeCount += remaining;
+      this.levelBounds.push(nodeCount * 4);
+    } while (remaining !== 1);
+
+    const IndexArrayType = nodeCount < 16384 ? Uint16Array : Uint32Array;
+    this.boxes = new Float64Array(nodeCount * 4);
+    this.indices = new IndexArrayType(nodeCount);
+    this.position = 0;
+  }
+
+  add(minX: number, minY: number, maxX: number = minX, maxY: number = minY): number {
+    const itemIndex = this.position >> 2;
+    this.indices[itemIndex] = itemIndex;
+    this.boxes[this.position++] = minX;
+    this.boxes[this.position++] = minY;
+    this.boxes[this.position++] = maxX;
+    this.boxes[this.position++] = maxY;
+
+    if (minX < this.minX) this.minX = minX;
+    if (minY < this.minY) this.minY = minY;
+    if (maxX > this.maxX) this.maxX = maxX;
+    if (maxY > this.maxY) this.maxY = maxY;
+
+    return itemIndex;
+  }
+
+  finish(): void {
+    if (this.position >> 2 !== this.numItems) {
+      throw new Error(`Added ${this.position >> 2} items when expected ${this.numItems}.`);
+    }
+
+    const boxes = this.boxes;
+
+    if (this.numItems <= NODE_SIZE) {
+      boxes[this.position++] = this.minX;
+      boxes[this.position++] = this.minY;
+      boxes[this.position++] = this.maxX;
+      boxes[this.position++] = this.maxY;
+      return;
+    }
+
+    const width = (this.maxX - this.minX) || 1;
+    const height = (this.maxY - this.minY) || 1;
+    const hilbertValues = new Uint32Array(this.numItems);
+    const hilbertMax = (1 << 16) - 1;
+
+    for (let itemIndex = 0, boxPosition = 0; itemIndex < this.numItems; itemIndex++) {
+      const rectMinX = boxes[boxPosition++];
+      const rectMinY = boxes[boxPosition++];
+      const rectMaxX = boxes[boxPosition++];
+      const rectMaxY = boxes[boxPosition++];
+      const normalizedX = Math.floor(hilbertMax * ((rectMinX + rectMaxX) / 2 - this.minX) / width);
+      const normalizedY = Math.floor(hilbertMax * ((rectMinY + rectMaxY) / 2 - this.minY) / height);
+      hilbertValues[itemIndex] = hilbert(normalizedX, normalizedY);
+    }
+
+    sortByHilbert(hilbertValues, boxes, this.indices, 0, this.numItems - 1);
+
+    for (let levelIndex = 0, boxPosition = 0; levelIndex < this.levelBounds.length - 1; levelIndex++) {
+      const levelEnd = this.levelBounds[levelIndex];
+
+      while (boxPosition < levelEnd) {
+        const nodeStartIndex = boxPosition;
+
+        let nodeMinX = boxes[boxPosition++];
+        let nodeMinY = boxes[boxPosition++];
+        let nodeMaxX = boxes[boxPosition++];
+        let nodeMaxY = boxes[boxPosition++];
+        for (let childIndex = 1; childIndex < NODE_SIZE && boxPosition < levelEnd; childIndex++) {
+          nodeMinX = Math.min(nodeMinX, boxes[boxPosition++]);
+          nodeMinY = Math.min(nodeMinY, boxes[boxPosition++]);
+          nodeMaxX = Math.max(nodeMaxX, boxes[boxPosition++]);
+          nodeMaxY = Math.max(nodeMaxY, boxes[boxPosition++]);
+        }
+
+        this.indices[this.position >> 2] = nodeStartIndex;
+        boxes[this.position++] = nodeMinX;
+        boxes[this.position++] = nodeMinY;
+        boxes[this.position++] = nodeMaxX;
+        boxes[this.position++] = nodeMaxY;
+      }
+    }
+  }
+
+  search(minX: number, minY: number, maxX: number, maxY: number): number[] {
+    if (this.position !== this.boxes.length) {
+      throw new Error("Data not yet indexed - call finish().");
+    }
+
+    let nodeIndex: number | undefined = this.boxes.length - 4;
+    const searchQueue: number[] = [];
+    const results: number[] = [];
+
+    while (nodeIndex !== undefined) {
+      const nodeEnd = Math.min(nodeIndex + NODE_SIZE * 4, upperBound(nodeIndex, this.levelBounds));
+
+      for (let boxPosition = nodeIndex; boxPosition < nodeEnd; boxPosition += 4) {
+        const candidateMinX = this.boxes[boxPosition];
+        if (maxX < candidateMinX) continue;
+        const candidateMinY = this.boxes[boxPosition + 1];
+        if (maxY < candidateMinY) continue;
+        const candidateMaxX = this.boxes[boxPosition + 2];
+        if (minX > candidateMaxX) continue;
+        const candidateMaxY = this.boxes[boxPosition + 3];
+        if (minY > candidateMaxY) continue;
+
+        const candidateIndex = this.indices[boxPosition >> 2] | 0;
+
+        if (nodeIndex >= this.numItems * 4) {
+          searchQueue.push(candidateIndex);
+        } else {
+          results.push(candidateIndex);
+        }
+      }
+
+      nodeIndex = searchQueue.pop();
+    }
+
+    return results;
+  }
+}
diff --git a/packages/react-grab/src/vendor/stacking-order.ts b/packages/react-grab/src/vendor/stacking-order.ts
new file mode 100644
index 000000000..b1483a4d9
--- /dev/null
+++ b/packages/react-grab/src/vendor/stacking-order.ts
@@ -0,0 +1,87 @@
+// Ported from Rich-Harris/stacking-order (MIT License)
+// https://github.com/Rich-Harris/stacking-order
+//
+// Determines which of two elements is visually in front by walking
+// ancestor chains, comparing stacking contexts, and falling back
+// to DOM sibling order.
+
+const STACKING_CONTEXT_PROPERTIES = /\b(?:position|zIndex|opacity|transform|mixBlendMode|filter|isolation)\b/;
+
+const getParent = (node: Element): Element | null =>
+  ((node as unknown as { parentNode: { host?: Element } }).parentNode?.host as Element | undefined) ?? node.parentElement;
+
+const getAncestors = (node: Element): Element[] => {
+  const ancestors: Element[] = [];
+  let current: Element | null = node;
+  while (current) {
+    ancestors.push(current);
+    current = getParent(current);
+  }
+  return ancestors;
+};
+
+const isFlexItem = (node: Element): boolean => {
+  const parentElement = getParent(node);
+  if (!parentElement) return false;
+  const display = getComputedStyle(parentElement).display;
+  return display === "flex" || display === "inline-flex";
+};
+
+const createsStackingContext = (node: Element): boolean => {
+  const style = getComputedStyle(node);
+
+  if (style.position === "fixed") return true;
+  if ((style.zIndex !== "auto" && style.position !== "static") || isFlexItem(node)) return true;
+  if (+style.opacity < 1) return true;
+  if (style.transform !== "none") return true;
+  if ("mixBlendMode" in style && style.mixBlendMode !== "normal") return true;
+  if (style.filter !== "none") return true;
+  if ("isolation" in style && (style as CSSStyleDeclaration & { isolation: string }).isolation === "isolate") return true;
+  if (STACKING_CONTEXT_PROPERTIES.test(style.willChange)) return true;
+
+  return false;
+};
+
+const findStackingContext = (ancestors: Element[]): Element | null => {
+  let ancestorIndex = ancestors.length;
+  while (ancestorIndex--) {
+    if (createsStackingContext(ancestors[ancestorIndex])) return ancestors[ancestorIndex];
+  }
+  return null;
+};
+
+const getZIndex = (node: Element | null): number =>
+  (node && Number(getComputedStyle(node).zIndex)) || 0;
+
+export const compareStackingOrder = (elementA: Element, elementB: Element): number => {
+  if (elementA === elementB) return 0;
+
+  const ancestorsA = getAncestors(elementA);
+  const ancestorsB = getAncestors(elementB);
+
+  let commonAncestor: Element | undefined;
+
+  while (ancestorsA.at(-1) === ancestorsB.at(-1)) {
+    commonAncestor = ancestorsA.pop()!;
+    ancestorsB.pop();
+  }
+
+  const zIndexA = getZIndex(findStackingContext(ancestorsA));
+  const zIndexB = getZIndex(findStackingContext(ancestorsB));
+
+  if (zIndexA === zIndexB) {
+    if (!commonAncestor) return 0;
+    const children = commonAncestor.childNodes;
+    const furthestAncestorA = ancestorsA.at(-1);
+    const furthestAncestorB = ancestorsB.at(-1);
+
+    let childIndex = children.length;
+    while (childIndex--) {
+      const child = children[childIndex];
+      if (child === furthestAncestorA) return 1;
+      if (child === furthestAncestorB) return -1;
+    }
+  }
+
+  return Math.sign(zIndexA - zIndexB);
+};

From 0ffd2d80feb1d10b0816e24256ef92bbc1645932 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 21:30:44 -0700
Subject: [PATCH 18/45] fix: clear element references on prehit index destroy

Truncate the elements array to drop strong references to DOM nodes.
Without this, DOM elements removed during an active session (e.g. SPA
route change) would be retained in memory until deactivation.
---
 packages/react-grab/src/utils/prehit.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/react-grab/src/utils/prehit.ts b/packages/react-grab/src/utils/prehit.ts
index 8bad17d6d..10a127873 100644
--- a/packages/react-grab/src/utils/prehit.ts
+++ b/packages/react-grab/src/utils/prehit.ts
@@ -105,5 +105,8 @@ export const queryPrehitIndex = (clientX: number, clientY: number): Element | nu
 export const isPrehitIndexReady = (): boolean => currentIndex !== null;
 
 export const destroyPrehitIndex = (): void => {
-  currentIndex = null;
+  if (currentIndex) {
+    currentIndex.elements.length = 0;
+    currentIndex = null;
+  }
 };

From afacfee09dafb553efcd66c8d56b3ca0e6fece34 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 21:51:57 -0700
Subject: [PATCH 19/45] fix: destroy prehit index on dispose to prevent memory
 leaks

Register destroyPrehitIndex in the root onCleanup handler so the
element reference array and typed arrays are released when the
react-grab API is disposed (e.g., hot module reload, SPA unmount).
Without this, DOM elements retained in the prehit index would stay
in memory even after the react-grab instance is torn down.
---
 packages/react-grab/src/core/index.tsx | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/react-grab/src/core/index.tsx b/packages/react-grab/src/core/index.tsx
index 2846cbf6b..26db6b4ae 100644
--- a/packages/react-grab/src/core/index.tsx
+++ b/packages/react-grab/src/core/index.tsx
@@ -135,6 +135,7 @@ import {
 } from "../utils/freeze-animations.js";
 import { freezePseudoStates, unfreezePseudoStates } from "../utils/freeze-pseudo-states.js";
 import { freezeUpdates } from "../utils/freeze-updates.js";
+import { destroyPrehitIndex } from "../utils/prehit.js";
 import {
   loadComments,
   addCommentItem,
@@ -2877,6 +2878,7 @@ export const init = (rawOptions?: Options): ReactGrabAPI => {
 
     onCleanup(() => {
       eventListenerManager.abort();
+      destroyPrehitIndex();
       if (dragPreviewDebounceTimerId !== null) {
         window.clearTimeout(dragPreviewDebounceTimerId);
       }

From d10858b35bec43d3b5746e351a0b1a7bf40de65f Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 22:00:16 -0700
Subject: [PATCH 20/45] refactor: use IntersectionObserver for prehit rect
 collection

IO entries include boundingClientRect as part of the browser's normal
rendering pipeline. After freeze triggers a style recalc + layout, the
IO callback fires with rects computed at zero additional reflow cost.

Accumulates entries across IO callback batches and rebuilds the
Flatbush index on each batch so queries work as soon as the first
entries arrive. Uses rootMargin: 10000px to observe elements far
beyond the viewport.
---
 packages/react-grab/src/utils/prehit.ts | 86 ++++++++++++++++---------
 1 file changed, 57 insertions(+), 29 deletions(-)

diff --git a/packages/react-grab/src/utils/prehit.ts b/packages/react-grab/src/utils/prehit.ts
index 10a127873..e0fc7389a 100644
--- a/packages/react-grab/src/utils/prehit.ts
+++ b/packages/react-grab/src/utils/prehit.ts
@@ -18,15 +18,58 @@ const SKIP_TAGS = new Set([
 ]);
 
 let currentIndex: PrehitIndex | null = null;
+let pendingObserver: IntersectionObserver | null = null;
 
 export const buildPrehitIndex = (): void => {
   destroyPrehitIndex();
 
-  const scrollX = window.scrollX;
-  const scrollY = window.scrollY;
-  const elements: IndexedElement[] = [];
-  const rects: { left: number; top: number; right: number; bottom: number }[] = [];
+  const treeOrderMap = new Map<Element, number>();
   let treeOrder = 0;
+  let observedCount = 0;
+
+  const accumulatedElements: IndexedElement[] = [];
+  const accumulatedRects: { left: number; top: number; right: number; bottom: number }[] = [];
+
+  const observer = new IntersectionObserver(
+    (entries) => {
+      const scrollX = window.scrollX;
+      const scrollY = window.scrollY;
+
+      for (const entry of entries) {
+        observer.unobserve(entry.target);
+
+        const boundingRect = entry.boundingClientRect;
+        if (boundingRect.width === 0 || boundingRect.height === 0) continue;
+        if (!isValidGrabbableElement(entry.target)) continue;
+
+        accumulatedElements.push({
+          element: entry.target,
+          area: boundingRect.width * boundingRect.height,
+          treeOrder: treeOrderMap.get(entry.target) ?? 0,
+        });
+
+        accumulatedRects.push({
+          left: boundingRect.left + scrollX,
+          top: boundingRect.top + scrollY,
+          right: boundingRect.right + scrollX,
+          bottom: boundingRect.bottom + scrollY,
+        });
+      }
+
+      if (accumulatedElements.length === 0) return;
+
+      const tree = new Flatbush(accumulatedElements.length);
+      for (const rect of accumulatedRects) {
+        tree.add(rect.left, rect.top, rect.right, rect.bottom);
+      }
+      tree.finish();
+
+      currentIndex = { tree, elements: [...accumulatedElements] };
+    },
+    { rootMargin: "10000px" },
+  );
+
+  pendingObserver = observer;
 
   const walker = document.createTreeWalker(
     document.body,
@@ -42,34 +85,15 @@ export const buildPrehitIndex = (): void => {
   while (walker.nextNode()) {
     const element = walker.currentNode as HTMLElement;
     if (element.offsetWidth === 0 && element.offsetHeight === 0) continue;
-    if (!isValidGrabbableElement(element)) continue;
-
-    const rect = element.getBoundingClientRect();
-    if (rect.width === 0 || rect.height === 0) continue;
-
-    elements.push({
-      element,
-      area: rect.width * rect.height,
-      treeOrder: treeOrder++,
-    });
-
-    rects.push({
-      left: rect.left + scrollX,
-      top: rect.top + scrollY,
-      right: rect.right + scrollX,
-      bottom: rect.bottom + scrollY,
-    });
+    treeOrderMap.set(element, treeOrder++);
+    observer.observe(element);
+    observedCount++;
   }
 
-  if (elements.length === 0) return;
-
-  const tree = new Flatbush(elements.length);
-  for (const indexedRect of rects) {
-    tree.add(indexedRect.left, indexedRect.top, indexedRect.right, indexedRect.bottom);
+  if (observedCount === 0) {
+    observer.disconnect();
+    pendingObserver = null;
   }
-  tree.finish();
-
-  currentIndex = { tree, elements };
 };
 
 export const queryPrehitIndex = (clientX: number, clientY: number): Element | null => {
@@ -105,6 +129,10 @@ export const queryPrehitIndex = (clientX: number, clientY: number): Element | nu
 export const isPrehitIndexReady = (): boolean => currentIndex !== null;
 
 export const destroyPrehitIndex = (): void => {
+  if (pendingObserver) {
+    pendingObserver.disconnect();
+    pendingObserver = null;
+  }
   if (currentIndex) {
     currentIndex.elements.length = 0;
     currentIndex = null;

From a037c700d676d388e03859bab50f839920bb5c2c Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 22:04:44 -0700
Subject: [PATCH 21/45] feat: wire prehit spatial index into the detection hot
 path

Prehit is now fully integrated:
- buildPrehitIndex() on activation (IO collects rects asynchronously)
- destroyPrehitIndex() on deactivation and dispose
- getElementAtPosition uses prehit as fast path, falls through to
  elementsFromPoint when the index isn't ready or returns no result

Fixes the overflow clipping issue that blocked earlier integration:
isVisibleAtPoint walks the ancestor clip chain and rejects candidates
whose bounding box extends outside a parent with overflow:hidden/scroll/
auto/clip. getComputedStyle and getBoundingClientRect are cache reads
(page is frozen, styles and layout are clean).
---
 packages/react-grab/src/core/index.tsx        |  4 +++-
 .../src/utils/get-element-at-position.ts      | 13 +++++++++--
 packages/react-grab/src/utils/prehit.ts       | 23 +++++++++++++++++++
 3 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/packages/react-grab/src/core/index.tsx b/packages/react-grab/src/core/index.tsx
index 26db6b4ae..4550faa82 100644
--- a/packages/react-grab/src/core/index.tsx
+++ b/packages/react-grab/src/core/index.tsx
@@ -135,7 +135,7 @@ import {
 } from "../utils/freeze-animations.js";
 import { freezePseudoStates, unfreezePseudoStates } from "../utils/freeze-pseudo-states.js";
 import { freezeUpdates } from "../utils/freeze-updates.js";
-import { destroyPrehitIndex } from "../utils/prehit.js";
+import { buildPrehitIndex, destroyPrehitIndex } from "../utils/prehit.js";
 import {
   loadComments,
   addCommentItem,
@@ -259,11 +259,13 @@ export const init = (rawOptions?: Options): ReactGrabAPI => {
         if (activated && !previousActivated) {
           freezePseudoStates();
           freezeGlobalAnimations();
+          buildPrehitIndex();
           document.body.style.touchAction = "none";
           // iOS Safari auto-zooms on focused inputs with font-size < 16px,
           // which would disrupt the overlay positioning.
           unlockViewportZoom = lockViewportZoom();
         } else if (!activated && previousActivated) {
+          destroyPrehitIndex();
           unfreezePseudoStates();
           unfreezeGlobalAnimations();
           document.body.style.touchAction = "";
diff --git a/packages/react-grab/src/utils/get-element-at-position.ts b/packages/react-grab/src/utils/get-element-at-position.ts
index 8bb2804bd..0d030c4ed 100644
--- a/packages/react-grab/src/utils/get-element-at-position.ts
+++ b/packages/react-grab/src/utils/get-element-at-position.ts
@@ -5,6 +5,7 @@ import {
   POINTER_EVENTS_RESUME_DEBOUNCE_MS,
 } from "../constants.js";
 import { suspendPointerEventsFreeze, resumePointerEventsFreeze } from "./freeze-pseudo-states.js";
+import { isPrehitIndexReady, queryPrehitIndex } from "./prehit.js";
 
 interface PositionCache {
   clientX: number;
@@ -68,8 +69,16 @@ export const getElementAtPosition = (clientX: number, clientY: number): Element
   // Built once at activation via IntersectionObserver; valid for the entire
   // session because the page is frozen. Falls through to elementsFromPoint
   // when the index isn't ready yet (1-frame startup) or when the query returns
-  // no result (element off-screen or not indexed).
-  // suspendPointerEventsFreeze toggles the html { pointer-events: none }
+  // no result (element not indexed, clipped, or newly added after activation).
+  if (isPrehitIndexReady()) {
+    const prehitResult = queryPrehitIndex(clientX, clientY);
+    if (prehitResult) {
+      cache = { clientX, clientY, element: prehitResult, timestamp: now };
+      return prehitResult;
+    }
+  }
+
+  // Slow path: suspendPointerEventsFreeze toggles the html { pointer-events: none }
   // stylesheet, which dirties the entire style tree. elementsFromPoint then forces
   // a Recalculate Style (1-5ms on dense DOMs).
   cancelScheduledResume();
diff --git a/packages/react-grab/src/utils/prehit.ts b/packages/react-grab/src/utils/prehit.ts
index e0fc7389a..4619f0771 100644
--- a/packages/react-grab/src/utils/prehit.ts
+++ b/packages/react-grab/src/utils/prehit.ts
@@ -96,6 +96,28 @@ export const buildPrehitIndex = (): void => {
   }
 };
 
+const CLIPPING_OVERFLOW_VALUES = new Set(["hidden", "scroll", "auto", "clip"]);
+
+const isVisibleAtPoint = (element: Element, clientX: number, clientY: number): boolean => {
+  let ancestor = element.parentElement;
+  while (ancestor && ancestor !== document.documentElement) {
+    const overflow = getComputedStyle(ancestor).overflow;
+    if (CLIPPING_OVERFLOW_VALUES.has(overflow)) {
+      const ancestorRect = ancestor.getBoundingClientRect();
+      if (
+        clientX < ancestorRect.left ||
+        clientX > ancestorRect.right ||
+        clientY < ancestorRect.top ||
+        clientY > ancestorRect.bottom
+      ) {
+        return false;
+      }
+    }
+    ancestor = ancestor.parentElement;
+  }
+  return true;
+};
+
 export const queryPrehitIndex = (clientX: number, clientY: number): Element | null => {
   if (!currentIndex) return null;
 
@@ -110,6 +132,7 @@ export const queryPrehitIndex = (clientX: number, clientY: number): Element | nu
   for (const hitIndex of hitIndices) {
     const candidate = currentIndex.elements[hitIndex];
     if (!candidate.element.isConnected) continue;
+    if (!isVisibleAtPoint(candidate.element, clientX, clientY)) continue;
 
     if (!bestElement) {
       bestElement = candidate;

From 315366420e1e9f6a8bb59f0afbe7b697a72b5e45 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 22:10:17 -0700
Subject: [PATCH 22/45] fix: check overflow-x/overflow-y independently and
 handle contain:paint

The clip chain walk now checks overflowX and overflowY separately
since an element can clip on one axis but not the other (e.g.,
overflow-x: hidden; overflow-y: visible). Also handles contain:paint
which creates a clip boundary equivalent to overflow:hidden.
---
 packages/react-grab/src/utils/prehit.ts | 21 +++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/packages/react-grab/src/utils/prehit.ts b/packages/react-grab/src/utils/prehit.ts
index 4619f0771..47075fb1f 100644
--- a/packages/react-grab/src/utils/prehit.ts
+++ b/packages/react-grab/src/utils/prehit.ts
@@ -98,11 +98,21 @@ export const buildPrehitIndex = (): void => {
 
 const CLIPPING_OVERFLOW_VALUES = new Set(["hidden", "scroll", "auto", "clip"]);
 
+const clipsAtPoint = (style: CSSStyleDeclaration, rect: DOMRect, clientX: number, clientY: number): boolean => {
+  const clipsX = CLIPPING_OVERFLOW_VALUES.has(style.overflowX);
+  const clipsY = CLIPPING_OVERFLOW_VALUES.has(style.overflowY);
+  if (!clipsX && !clipsY) return false;
+  if (clipsX && (clientX < rect.left || clientX > rect.right)) return true;
+  if (clipsY && (clientY < rect.top || clientY > rect.bottom)) return true;
+  return false;
+};
+
 const isVisibleAtPoint = (element: Element, clientX: number, clientY: number): boolean => {
   let ancestor = element.parentElement;
   while (ancestor && ancestor !== document.documentElement) {
-    const overflow = getComputedStyle(ancestor).overflow;
-    if (CLIPPING_OVERFLOW_VALUES.has(overflow)) {
+    const style = getComputedStyle(ancestor);
+
+    if (style.contain.includes("paint")) {
       const ancestorRect = ancestor.getBoundingClientRect();
       if (
         clientX < ancestorRect.left ||
@@ -112,7 +122,14 @@ const isVisibleAtPoint = (element: Element, clientX: number, clientY: number): b
       ) {
         return false;
       }
+    } else if (
+      CLIPPING_OVERFLOW_VALUES.has(style.overflowX) ||
+      CLIPPING_OVERFLOW_VALUES.has(style.overflowY)
+    ) {
+      const ancestorRect = ancestor.getBoundingClientRect();
+      if (clipsAtPoint(style, ancestorRect, clientX, clientY)) return false;
     }
+
     ancestor = ancestor.parentElement;
   }
   return true;

From 592a161f6f62819700c8bab374c3b86a68002943 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 22:20:24 -0700
Subject: [PATCH 23/45] fix: address code review findings from AGENTS.md audit

- Remove double type cast in stacking-order getParent (use ShadowRoot
  narrowing instead of unknown bridge)
- Replace type cast for isolation with getPropertyValue
- Extract inline rect type to PageRect interface
- Replace observedCount with didObserveAnyElement boolean
- Move root margin magic number to PREHIT_ROOT_MARGIN_PX in constants
- Remove unnecessary shallow copy of accumulatedElements
---
 packages/react-grab/src/constants.ts          |  2 ++
 packages/react-grab/src/utils/prehit.ts       | 20 +++++++++++++------
 .../react-grab/src/vendor/stacking-order.ts   |  9 ++++++---
 3 files changed, 22 insertions(+), 9 deletions(-)

diff --git a/packages/react-grab/src/constants.ts b/packages/react-grab/src/constants.ts
index 9e4d92561..bd0ac371b 100644
--- a/packages/react-grab/src/constants.ts
+++ b/packages/react-grab/src/constants.ts
@@ -130,6 +130,8 @@ export const ELEMENT_POSITION_THROTTLE_MS = 16;
 export const POINTER_EVENTS_RESUME_DEBOUNCE_MS = 100;
 export const VISIBILITY_CACHE_TTL_MS = 50;
 
+export const PREHIT_ROOT_MARGIN_PX = 10_000;
+
 export const ZOOM_DETECTION_THRESHOLD = 0.01;
 
 export const MOUNT_ROOT_RECHECK_DELAY_MS = 1000;
diff --git a/packages/react-grab/src/utils/prehit.ts b/packages/react-grab/src/utils/prehit.ts
index 47075fb1f..6f7e1ed23 100644
--- a/packages/react-grab/src/utils/prehit.ts
+++ b/packages/react-grab/src/utils/prehit.ts
@@ -1,4 +1,5 @@
 import { Flatbush } from "../vendor/flatbush.js";
+import { PREHIT_ROOT_MARGIN_PX } from "../constants.js";
 import { isValidGrabbableElement } from "./is-valid-grabbable-element.js";
 
 interface IndexedElement {
@@ -7,6 +8,13 @@ interface IndexedElement {
   treeOrder: number;
 }
 
+interface PageRect {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+}
+
 interface PrehitIndex {
   tree: Flatbush;
   elements: IndexedElement[];
@@ -25,10 +33,10 @@ export const buildPrehitIndex = (): void => {
 
   const treeOrderMap = new Map<Element, number>();
   let treeOrder = 0;
-  let observedCount = 0;
+  let didObserveAnyElement = false;
 
   const accumulatedElements: IndexedElement[] = [];
-  const accumulatedRects: { left: number; top: number; right: number; bottom: number }[] = [];
+  const accumulatedRects: PageRect[] = [];
 
   const observer = new IntersectionObserver(
     (entries) => {
@@ -64,9 +72,9 @@ export const buildPrehitIndex = (): void => {
       }
       tree.finish();
 
-      currentIndex = { tree, elements: [...accumulatedElements] };
+      currentIndex = { tree, elements: accumulatedElements };
     },
-    { rootMargin: "10000px" },
+    { rootMargin: `${PREHIT_ROOT_MARGIN_PX}px` },
   );
 
   pendingObserver = observer;
@@ -87,10 +95,10 @@ export const buildPrehitIndex = (): void => {
     if (element.offsetWidth === 0 && element.offsetHeight === 0) continue;
     treeOrderMap.set(element, treeOrder++);
     observer.observe(element);
-    observedCount++;
+    didObserveAnyElement = true;
   }
 
-  if (observedCount === 0) {
+  if (!didObserveAnyElement) {
     observer.disconnect();
     pendingObserver = null;
   }
diff --git a/packages/react-grab/src/vendor/stacking-order.ts b/packages/react-grab/src/vendor/stacking-order.ts
index b1483a4d9..3c5ea48e6 100644
--- a/packages/react-grab/src/vendor/stacking-order.ts
+++ b/packages/react-grab/src/vendor/stacking-order.ts
@@ -7,8 +7,11 @@
 
 const STACKING_CONTEXT_PROPERTIES = /\b(?:position|zIndex|opacity|transform|mixBlendMode|filter|isolation)\b/;
 
-const getParent = (node: Element): Element | null =>
-  ((node as unknown as { parentNode: { host?: Element } }).parentNode?.host as Element | undefined) ?? node.parentElement;
+const getParent = (node: Element): Element | null => {
+  const parentNode = node.parentNode;
+  const shadowHost = parentNode && "host" in parentNode ? (parentNode as ShadowRoot).host : null;
+  return shadowHost ?? node.parentElement;
+};
 
 const getAncestors = (node: Element): Element[] => {
   const ancestors: Element[] = [];
@@ -36,7 +39,7 @@ const createsStackingContext = (node: Element): boolean => {
   if (style.transform !== "none") return true;
   if ("mixBlendMode" in style && style.mixBlendMode !== "normal") return true;
   if (style.filter !== "none") return true;
-  if ("isolation" in style && (style as CSSStyleDeclaration & { isolation: string }).isolation === "isolate") return true;
+  if ("isolation" in style && style.getPropertyValue("isolation") === "isolate") return true;
   if (STACKING_CONTEXT_PROPERTIES.test(style.willChange)) return true;
 
   return false;

From da93bcc430eb031b3c16b99684b668c0c89a240d Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 22:21:50 -0700
Subject: [PATCH 24/45] refactor: rename vendor files to algorithm names

flatbush.ts -> hilbert-r-tree.ts (class: HilbertRTree)
stacking-order.ts -> stacking-context-comparator.ts

Headers now describe the algorithm, not the library brand.
License and source URLs retained.
---
 packages/react-grab/src/utils/prehit.ts                |  6 +++---
 .../src/vendor/{flatbush.ts => hilbert-r-tree.ts}      | 10 ++++------
 ...tacking-order.ts => stacking-context-comparator.ts} | 10 ++++------
 3 files changed, 11 insertions(+), 15 deletions(-)
 rename packages/react-grab/src/vendor/{flatbush.ts => hilbert-r-tree.ts} (97%)
 rename packages/react-grab/src/vendor/{stacking-order.ts => stacking-context-comparator.ts} (91%)

diff --git a/packages/react-grab/src/utils/prehit.ts b/packages/react-grab/src/utils/prehit.ts
index 6f7e1ed23..072a3de98 100644
--- a/packages/react-grab/src/utils/prehit.ts
+++ b/packages/react-grab/src/utils/prehit.ts
@@ -1,4 +1,4 @@
-import { Flatbush } from "../vendor/flatbush.js";
+import { HilbertRTree } from "../vendor/hilbert-r-tree.js";
 import { PREHIT_ROOT_MARGIN_PX } from "../constants.js";
 import { isValidGrabbableElement } from "./is-valid-grabbable-element.js";
 
@@ -16,7 +16,7 @@ interface PageRect {
 }
 
 interface PrehitIndex {
-  tree: Flatbush;
+  tree: HilbertRTree;
   elements: IndexedElement[];
 }
 
@@ -66,7 +66,7 @@ export const buildPrehitIndex = (): void => {
 
       if (accumulatedElements.length === 0) return;
 
-      const tree = new Flatbush(accumulatedElements.length);
+      const tree = new HilbertRTree(accumulatedElements.length);
       for (const rect of accumulatedRects) {
         tree.add(rect.left, rect.top, rect.right, rect.bottom);
       }
diff --git a/packages/react-grab/src/vendor/flatbush.ts b/packages/react-grab/src/vendor/hilbert-r-tree.ts
similarity index 97%
rename from packages/react-grab/src/vendor/flatbush.ts
rename to packages/react-grab/src/vendor/hilbert-r-tree.ts
index 5776dad30..0b7252144 100644
--- a/packages/react-grab/src/vendor/flatbush.ts
+++ b/packages/react-grab/src/vendor/hilbert-r-tree.ts
@@ -1,8 +1,6 @@
-// Ported from mourner/flatbush (ISC License)
-// https://github.com/mourner/flatbush
-//
-// Stripped to add/finish/search only. Removed: from() serialization,
-// neighbors() k-nearest-neighbors (and its flatqueue dependency).
+// Packed Hilbert R-tree for static spatial indexing.
+// O(n) build, O(log n) bounding-box search.
+// ISC License, https://github.com/mourner/flatbush
 
 const NODE_SIZE = 16;
 
@@ -135,7 +133,7 @@ const hilbert = (coordX: number, coordY: number): number => {
   return ((interleaved1 << 1) | interleaved0) >>> 0;
 };
 
-export class Flatbush {
+export class HilbertRTree {
   private readonly numItems: number;
   private readonly boxes: Float64Array;
   private readonly indices: Uint16Array | Uint32Array;
diff --git a/packages/react-grab/src/vendor/stacking-order.ts b/packages/react-grab/src/vendor/stacking-context-comparator.ts
similarity index 91%
rename from packages/react-grab/src/vendor/stacking-order.ts
rename to packages/react-grab/src/vendor/stacking-context-comparator.ts
index 3c5ea48e6..415da7f2d 100644
--- a/packages/react-grab/src/vendor/stacking-order.ts
+++ b/packages/react-grab/src/vendor/stacking-context-comparator.ts
@@ -1,9 +1,7 @@
-// Ported from Rich-Harris/stacking-order (MIT License)
-// https://github.com/Rich-Harris/stacking-order
-//
-// Determines which of two elements is visually in front by walking
-// ancestor chains, comparing stacking contexts, and falling back
-// to DOM sibling order.
+// Stacking context comparator: determines which of two elements is
+// visually in front by walking ancestor chains, comparing z-index
+// within stacking contexts, and falling back to DOM sibling order.
+// MIT License, https://github.com/Rich-Harris/stacking-order
 
 const STACKING_CONTEXT_PROPERTIES = /\b(?:position|zIndex|opacity|transform|mixBlendMode|filter|isolation)\b/;
 

From 28727d5276bd8341fab3de878fc19ab6fa625b8e Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 22:34:46 -0700
Subject: [PATCH 25/45] docs: fix markdown table formatting in prehit.md

---
 docs/prehit.md | 37 +++++++++++++++++++++----------------
 1 file changed, 21 insertions(+), 16 deletions(-)

diff --git a/docs/prehit.md b/docs/prehit.md
index 821c71630..a4a6e32cf 100644
--- a/docs/prehit.md
+++ b/docs/prehit.md
@@ -179,7 +179,7 @@ Recorded during the tree walk at index time. Later in tree = painted later = vis
 
 ### 2. `stacking-order` comparison (cheap in frozen state)
 
-[Rich Harris's `stacking-order`](https://github.com/Rich-Harris/stacking-order) (111 lines) computes pairwise visual ordering by walking ancestor chains and comparing stacking contexts. Uses `getComputedStyle`, which is a cache read (no recalc) inside the IO callback since the browser just rendered.
+[Rich Harris's `stacking-order](https://github.com/Rich-Harris/stacking-order)` (111 lines) computes pairwise visual ordering by walking ancestor chains and comparing stacking contexts. Uses `getComputedStyle`, which is a cache read (no recalc) inside the IO callback since the browser just rendered.
 
 We vendor a TypeScript port and use it only for Flatbush query results (typically 3-5 elements), not for the full element set:
 
@@ -227,13 +227,15 @@ deactivation:
 
 ## What This Eliminates
 
-| Operation | Current (per hover) | With Prehit (per hover) |
-|---|---|---|
-| pointer-events stylesheet toggle | Every 32ms | Never (only on fallback) |
-| `elementsFromPoint` | Every 32ms (forces style recalc) | Never (only on fallback) |
-| `getComputedStyle` | Per candidate element | Never (index precomputed) |
-| Style recalculation | 1-5ms per detection | 0ms |
-| **Total per-hover cost** | **1-5ms** | **~0.005ms** |
+
+| Operation                        | Current (per hover)              | With Prehit (per hover)   |
+| -------------------------------- | -------------------------------- | ------------------------- |
+| pointer-events stylesheet toggle | Every 32ms                       | Never (only on fallback)  |
+| `elementsFromPoint`              | Every 32ms (forces style recalc) | Never (only on fallback)  |
+| `getComputedStyle`               | Per candidate element            | Never (index precomputed) |
+| Style recalculation              | 1-5ms per detection              | 0ms                       |
+| **Total per-hover cost**         | **1-5ms**                        | **~0.005ms**              |
+
 
 ## Vendored Dependencies
 
@@ -263,11 +265,14 @@ Both libraries are small enough to vendor as TypeScript ports rather than adding
 
 ## Comparison to pretext
 
-| Aspect | pretext | prehit |
-|---|---|---|
-| **"prepare" phase** | Canvas `measureText` per word segment | IO `boundingClientRect` per element |
-| **"layout" phase** | Walk cached widths, count lines (arithmetic) | Flatbush `search()`, pick smallest (arithmetic) |
-| **Immutability guarantee** | Text doesn't change between prepare and layout | DOM is frozen between index and query |
-| **Cache granularity** | Per segment x font (`Map<string, Map<string, Metrics>>`) | Per element (`Float64Array` in Flatbush) |
-| **Invalidation** | `clearCache()` on locale/font change | Discard index on deactivation |
-| **Hot path cost** | ~0.0002ms per text block | ~0.005ms per point query |
+
+| Aspect                     | pretext                                                  | prehit                                          |
+| -------------------------- | -------------------------------------------------------- | ----------------------------------------------- |
+| **"prepare" phase**        | Canvas `measureText` per word segment                    | IO `boundingClientRect` per element             |
+| **"layout" phase**         | Walk cached widths, count lines (arithmetic)             | Flatbush `search()`, pick smallest (arithmetic) |
+| **Immutability guarantee** | Text doesn't change between prepare and layout           | DOM is frozen between index and query           |
+| **Cache granularity**      | Per segment x font (`Map<string, Map<string, Metrics>>`) | Per element (`Float64Array` in Flatbush)        |
+| **Invalidation**           | `clearCache()` on locale/font change                     | Discard index on deactivation                   |
+| **Hot path cost**          | ~0.0002ms per text block                                 | ~0.005ms per point query                        |
+
+

From f4661f1314b66f4a9b59162e3f1f17435e9ba7b0 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 22:35:27 -0700
Subject: [PATCH 26/45] style: remove header comment from
 stacking-context-comparator

---
 .../react-grab/src/vendor/stacking-context-comparator.ts     | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/packages/react-grab/src/vendor/stacking-context-comparator.ts b/packages/react-grab/src/vendor/stacking-context-comparator.ts
index 415da7f2d..0fa8b53f3 100644
--- a/packages/react-grab/src/vendor/stacking-context-comparator.ts
+++ b/packages/react-grab/src/vendor/stacking-context-comparator.ts
@@ -1,8 +1,3 @@
-// Stacking context comparator: determines which of two elements is
-// visually in front by walking ancestor chains, comparing z-index
-// within stacking contexts, and falling back to DOM sibling order.
-// MIT License, https://github.com/Rich-Harris/stacking-order
-
 const STACKING_CONTEXT_PROPERTIES = /\b(?:position|zIndex|opacity|transform|mixBlendMode|filter|isolation)\b/;
 
 const getParent = (node: Element): Element | null => {

From 5793094fc1c9414ce093364ef15c80c6e224c4b4 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 22:39:04 -0700
Subject: [PATCH 27/45] refactor: remove dead code and simplify prehit clip
 check

- Remove header comment from hilbert-r-tree (AGENTS.md: no restating)
- Delete unused stacking-context-comparator.ts (imported nowhere)
- Merge isVisibleAtPoint branches: contain:paint and overflow-x/y
  now share a single per-axis clip check instead of duplicating logic
- Remove clipsAtPoint helper (inlined into the unified check)
- Remove narrating comments from get-element-at-position
---
 .../src/utils/get-element-at-position.ts      |  8 --
 packages/react-grab/src/utils/prehit.ts       | 29 ++-----
 .../react-grab/src/vendor/hilbert-r-tree.ts   |  4 -
 .../src/vendor/stacking-context-comparator.ts | 83 -------------------
 4 files changed, 5 insertions(+), 119 deletions(-)
 delete mode 100644 packages/react-grab/src/vendor/stacking-context-comparator.ts

diff --git a/packages/react-grab/src/utils/get-element-at-position.ts b/packages/react-grab/src/utils/get-element-at-position.ts
index 0d030c4ed..ceeadcb65 100644
--- a/packages/react-grab/src/utils/get-element-at-position.ts
+++ b/packages/react-grab/src/utils/get-element-at-position.ts
@@ -65,11 +65,6 @@ export const getElementAtPosition = (clientX: number, clientY: number): Element
     }
   }
 
-  // Fast path: prehit spatial index (O(log n), no DOM reads, no style recalc).
-  // Built once at activation via IntersectionObserver; valid for the entire
-  // session because the page is frozen. Falls through to elementsFromPoint
-  // when the index isn't ready yet (1-frame startup) or when the query returns
-  // no result (element not indexed, clipped, or newly added after activation).
   if (isPrehitIndexReady()) {
     const prehitResult = queryPrehitIndex(clientX, clientY);
     if (prehitResult) {
@@ -78,9 +73,6 @@ export const getElementAtPosition = (clientX: number, clientY: number): Element
     }
   }
 
-  // Slow path: suspendPointerEventsFreeze toggles the html { pointer-events: none }
-  // stylesheet, which dirties the entire style tree. elementsFromPoint then forces
-  // a Recalculate Style (1-5ms on dense DOMs).
   cancelScheduledResume();
   suspendPointerEventsFreeze();
 
diff --git a/packages/react-grab/src/utils/prehit.ts b/packages/react-grab/src/utils/prehit.ts
index 072a3de98..8cc56160c 100644
--- a/packages/react-grab/src/utils/prehit.ts
+++ b/packages/react-grab/src/utils/prehit.ts
@@ -106,36 +106,17 @@ export const buildPrehitIndex = (): void => {
 
 const CLIPPING_OVERFLOW_VALUES = new Set(["hidden", "scroll", "auto", "clip"]);
 
-const clipsAtPoint = (style: CSSStyleDeclaration, rect: DOMRect, clientX: number, clientY: number): boolean => {
-  const clipsX = CLIPPING_OVERFLOW_VALUES.has(style.overflowX);
-  const clipsY = CLIPPING_OVERFLOW_VALUES.has(style.overflowY);
-  if (!clipsX && !clipsY) return false;
-  if (clipsX && (clientX < rect.left || clientX > rect.right)) return true;
-  if (clipsY && (clientY < rect.top || clientY > rect.bottom)) return true;
-  return false;
-};
-
 const isVisibleAtPoint = (element: Element, clientX: number, clientY: number): boolean => {
   let ancestor = element.parentElement;
   while (ancestor && ancestor !== document.documentElement) {
     const style = getComputedStyle(ancestor);
+    const clipsX = CLIPPING_OVERFLOW_VALUES.has(style.overflowX) || style.contain.includes("paint");
+    const clipsY = CLIPPING_OVERFLOW_VALUES.has(style.overflowY) || style.contain.includes("paint");
 
-    if (style.contain.includes("paint")) {
-      const ancestorRect = ancestor.getBoundingClientRect();
-      if (
-        clientX < ancestorRect.left ||
-        clientX > ancestorRect.right ||
-        clientY < ancestorRect.top ||
-        clientY > ancestorRect.bottom
-      ) {
-        return false;
-      }
-    } else if (
-      CLIPPING_OVERFLOW_VALUES.has(style.overflowX) ||
-      CLIPPING_OVERFLOW_VALUES.has(style.overflowY)
-    ) {
+    if (clipsX || clipsY) {
       const ancestorRect = ancestor.getBoundingClientRect();
-      if (clipsAtPoint(style, ancestorRect, clientX, clientY)) return false;
+      if (clipsX && (clientX < ancestorRect.left || clientX > ancestorRect.right)) return false;
+      if (clipsY && (clientY < ancestorRect.top || clientY > ancestorRect.bottom)) return false;
     }
 
     ancestor = ancestor.parentElement;
diff --git a/packages/react-grab/src/vendor/hilbert-r-tree.ts b/packages/react-grab/src/vendor/hilbert-r-tree.ts
index 0b7252144..992743b59 100644
--- a/packages/react-grab/src/vendor/hilbert-r-tree.ts
+++ b/packages/react-grab/src/vendor/hilbert-r-tree.ts
@@ -1,7 +1,3 @@
-// Packed Hilbert R-tree for static spatial indexing.
-// O(n) build, O(log n) bounding-box search.
-// ISC License, https://github.com/mourner/flatbush
-
 const NODE_SIZE = 16;
 
 const upperBound = (value: number, levelBounds: number[]): number => {
diff --git a/packages/react-grab/src/vendor/stacking-context-comparator.ts b/packages/react-grab/src/vendor/stacking-context-comparator.ts
deleted file mode 100644
index 0fa8b53f3..000000000
--- a/packages/react-grab/src/vendor/stacking-context-comparator.ts
+++ /dev/null
@@ -1,83 +0,0 @@
-const STACKING_CONTEXT_PROPERTIES = /\b(?:position|zIndex|opacity|transform|mixBlendMode|filter|isolation)\b/;
-
-const getParent = (node: Element): Element | null => {
-  const parentNode = node.parentNode;
-  const shadowHost = parentNode && "host" in parentNode ? (parentNode as ShadowRoot).host : null;
-  return shadowHost ?? node.parentElement;
-};
-
-const getAncestors = (node: Element): Element[] => {
-  const ancestors: Element[] = [];
-  let current: Element | null = node;
-  while (current) {
-    ancestors.push(current);
-    current = getParent(current);
-  }
-  return ancestors;
-};
-
-const isFlexItem = (node: Element): boolean => {
-  const parentElement = getParent(node);
-  if (!parentElement) return false;
-  const display = getComputedStyle(parentElement).display;
-  return display === "flex" || display === "inline-flex";
-};
-
-const createsStackingContext = (node: Element): boolean => {
-  const style = getComputedStyle(node);
-
-  if (style.position === "fixed") return true;
-  if ((style.zIndex !== "auto" && style.position !== "static") || isFlexItem(node)) return true;
-  if (+style.opacity < 1) return true;
-  if (style.transform !== "none") return true;
-  if ("mixBlendMode" in style && style.mixBlendMode !== "normal") return true;
-  if (style.filter !== "none") return true;
-  if ("isolation" in style && style.getPropertyValue("isolation") === "isolate") return true;
-  if (STACKING_CONTEXT_PROPERTIES.test(style.willChange)) return true;
-
-  return false;
-};
-
-const findStackingContext = (ancestors: Element[]): Element | null => {
-  let ancestorIndex = ancestors.length;
-  while (ancestorIndex--) {
-    if (createsStackingContext(ancestors[ancestorIndex])) return ancestors[ancestorIndex];
-  }
-  return null;
-};
-
-const getZIndex = (node: Element | null): number =>
-  (node && Number(getComputedStyle(node).zIndex)) || 0;
-
-export const compareStackingOrder = (elementA: Element, elementB: Element): number => {
-  if (elementA === elementB) return 0;
-
-  const ancestorsA = getAncestors(elementA);
-  const ancestorsB = getAncestors(elementB);
-
-  let commonAncestor: Element | undefined;
-
-  while (ancestorsA.at(-1) === ancestorsB.at(-1)) {
-    commonAncestor = ancestorsA.pop()!;
-    ancestorsB.pop();
-  }
-
-  const zIndexA = getZIndex(findStackingContext(ancestorsA));
-  const zIndexB = getZIndex(findStackingContext(ancestorsB));
-
-  if (zIndexA === zIndexB) {
-    if (!commonAncestor) return 0;
-    const children = commonAncestor.childNodes;
-    const furthestAncestorA = ancestorsA.at(-1);
-    const furthestAncestorB = ancestorsB.at(-1);
-
-    let childIndex = children.length;
-    while (childIndex--) {
-      const child = children[childIndex];
-      if (child === furthestAncestorA) return 1;
-      if (child === furthestAncestorB) return -1;
-    }
-  }
-
-  return Math.sign(zIndexA - zIndexB);
-};

From 7bef6a58e02fee619a293c2a78d317698da354b5 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Wed, 8 Apr 2026 22:39:39 -0700
Subject: [PATCH 28/45] refactor: move hilbert-r-tree from vendor/ to utils/

---
 packages/react-grab/src/{vendor => utils}/hilbert-r-tree.ts | 0
 packages/react-grab/src/utils/prehit.ts                     | 2 +-
 2 files changed, 1 insertion(+), 1 deletion(-)
 rename packages/react-grab/src/{vendor => utils}/hilbert-r-tree.ts (100%)

diff --git a/packages/react-grab/src/vendor/hilbert-r-tree.ts b/packages/react-grab/src/utils/hilbert-r-tree.ts
similarity index 100%
rename from packages/react-grab/src/vendor/hilbert-r-tree.ts
rename to packages/react-grab/src/utils/hilbert-r-tree.ts
diff --git a/packages/react-grab/src/utils/prehit.ts b/packages/react-grab/src/utils/prehit.ts
index 8cc56160c..af9afcb21 100644
--- a/packages/react-grab/src/utils/prehit.ts
+++ b/packages/react-grab/src/utils/prehit.ts
@@ -1,4 +1,4 @@
-import { HilbertRTree } from "../vendor/hilbert-r-tree.js";
+import { HilbertRTree } from "./hilbert-r-tree.js";
 import { PREHIT_ROOT_MARGIN_PX } from "../constants.js";
 import { isValidGrabbableElement } from "./is-valid-grabbable-element.js";
 

From d9a32d933fb9d2329f957d2b02b82437d92402b9 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Thu, 9 Apr 2026 00:19:17 -0700
Subject: [PATCH 29/45] perf: optimize freeze system activation and
 deactivation

Activation:
- Replace querySelectorAll(":hover") with elementFromPoint + parent
  walk at the known cursor position. Avoids a full DOM style recalc
  to evaluate the :hover pseudo-class across every node.
- Replace querySelectorAll(":focus, :focus-visible") with
  document.activeElement chain walk. O(1) property read instead of
  O(N) pseudo-class evaluation.

Deactivation:
- Store running animations during freezeGlobalAnimations instead of
  re-enumerating via document.getAnimations() on unfreeze. Eliminates
  a full page animation enumeration + shadow DOM filtering on every
  deactivation.
---
 .../src/components/toolbar/index.tsx          |  4 +-
 packages/react-grab/src/core/index.tsx        |  2 +-
 packages/react-grab/src/primitives.ts         |  2 +-
 .../react-grab/src/utils/freeze-animations.ts | 35 ++++-----
 .../src/utils/freeze-pseudo-states.ts         | 73 ++++++++++++-------
 5 files changed, 68 insertions(+), 48 deletions(-)

diff --git a/packages/react-grab/src/components/toolbar/index.tsx b/packages/react-grab/src/components/toolbar/index.tsx
index 5036c2fc6..7c007c577 100644
--- a/packages/react-grab/src/components/toolbar/index.tsx
+++ b/packages/react-grab/src/components/toolbar/index.tsx
@@ -248,14 +248,14 @@ export const Toolbar: Component<ToolbarProps> = (props) => {
     setTooltipVisible: (visible: boolean) => void,
     options?: FreezeHandlersOptions,
   ) => ({
-    onMouseEnter: () => {
+    onMouseEnter: (event: MouseEvent) => {
       if (drag.isDragging()) return;
       safePolygonTracker.stop();
       setTooltipVisible(true);
       if (options?.shouldFreezeInteractions !== false && !unfreezeUpdatesCallback) {
         unfreezeUpdatesCallback = freezeUpdates();
         freezeGlobalAnimations();
-        freezePseudoStates();
+        freezePseudoStates(event.clientX, event.clientY);
       }
       options?.onHoverChange?.(true);
     },
diff --git a/packages/react-grab/src/core/index.tsx b/packages/react-grab/src/core/index.tsx
index 4550faa82..f0019333f 100644
--- a/packages/react-grab/src/core/index.tsx
+++ b/packages/react-grab/src/core/index.tsx
@@ -257,7 +257,7 @@ export const init = (rawOptions?: Options): ReactGrabAPI => {
     createEffect(
       on(isActivated, (activated, previousActivated) => {
         if (activated && !previousActivated) {
-          freezePseudoStates();
+          freezePseudoStates(store.pointer.x, store.pointer.y);
           freezeGlobalAnimations();
           buildPrehitIndex();
           document.body.style.touchAction = "none";
diff --git a/packages/react-grab/src/primitives.ts b/packages/react-grab/src/primitives.ts
index 6a0320a6f..85549567e 100644
--- a/packages/react-grab/src/primitives.ts
+++ b/packages/react-grab/src/primitives.ts
@@ -78,7 +78,7 @@ export const freeze = (elements?: Element[]): void => {
   freezeCleanupFns.add(freezeUpdates());
   freezeCleanupFns.add(freezeAnimations(elements ?? [document.body]));
   freezeGlobalAnimations();
-  freezePseudoStates();
+  freezePseudoStates(window.innerWidth / 2, window.innerHeight / 2);
 };
 
 /**
diff --git a/packages/react-grab/src/utils/freeze-animations.ts b/packages/react-grab/src/utils/freeze-animations.ts
index 74e9ba2cc..d562f67be 100644
--- a/packages/react-grab/src/utils/freeze-animations.ts
+++ b/packages/react-grab/src/utils/freeze-animations.ts
@@ -30,6 +30,7 @@ let globalFrozenSvgElements: SVGSVGElement[] = [];
 // a depth counter per element and only unpause when all layers are removed.
 const svgFreezeDepthMap = new Map<SVGSVGElement, number>();
 let frozenWaapiAnimations: Animation[] = [];
+let globalFrozenAnimations: Animation[] = [];
 
 const ensureStylesInjected = (): void => {
   if (styleElement) return;
@@ -179,6 +180,19 @@ export const freezeGlobalAnimations = (): void => {
     Array.from(document.querySelectorAll(SVG_ROOT_SELECTOR)),
   );
   pauseSvgAnimations(globalFrozenSvgElements);
+
+  globalFrozenAnimations = [];
+  for (const animation of document.getAnimations()) {
+    if (animation.effect instanceof KeyframeEffect) {
+      const target = animation.effect.target;
+      if (target instanceof Element) {
+        const rootNode = target.getRootNode();
+        if (rootNode instanceof ShadowRoot) continue;
+      }
+    }
+    globalFrozenAnimations.push(animation);
+  }
+
   freezeGsap();
 };
 
@@ -196,25 +210,8 @@ export const unfreezeGlobalAnimations = (): void => {
 }
 `;
 
-  // Animations inside shadow roots are skipped because the freeze CSS only
-  // affects main-document elements (shadow DOM provides style encapsulation),
-  // so calling finish() on animations the freeze never paused would break
-  // react-grab's own toolbar and label animations.
-  // @see https://github.com/aidenybai/react-grab/issues/163
-  const animations: Animation[] = [];
-  for (const animation of document.getAnimations()) {
-    if (animation.effect instanceof KeyframeEffect) {
-      const target = animation.effect.target;
-      if (target instanceof Element) {
-        const rootNode = target.getRootNode();
-        if (rootNode instanceof ShadowRoot) {
-          continue;
-        }
-      }
-    }
-    animations.push(animation);
-  }
-  finishAnimations(animations);
+  finishAnimations(globalFrozenAnimations);
+  globalFrozenAnimations = [];
 
   globalAnimationStyleElement.remove();
   globalAnimationStyleElement = null;
diff --git a/packages/react-grab/src/utils/freeze-pseudo-states.ts b/packages/react-grab/src/utils/freeze-pseudo-states.ts
index 214b3ece2..10fbe93ae 100644
--- a/packages/react-grab/src/utils/freeze-pseudo-states.ts
+++ b/packages/react-grab/src/utils/freeze-pseudo-states.ts
@@ -89,32 +89,50 @@ const collectOriginalPropertyValues = (
   return originalPropertyValues;
 };
 
-const collectPseudoStates = (
-  selector: string,
+const freezeElement = (
+  element: HTMLElement,
   properties: readonly string[],
   alreadyFrozen?: Map<HTMLElement, Map<string, string>>,
-): FrozenPseudoState[] => {
-  const elementsToFreeze: FrozenPseudoState[] = [];
-
-  for (const element of document.querySelectorAll(selector)) {
-    if (!(element instanceof HTMLElement)) continue;
-    if (alreadyFrozen?.has(element)) continue;
+): FrozenPseudoState | null => {
+  if (alreadyFrozen?.has(element)) return null;
 
-    const computed = getComputedStyle(element);
-    let frozenStyles = element.style.cssText;
-    const originalPropertyValues = collectOriginalPropertyValues(element, properties);
+  const computed = getComputedStyle(element);
+  let frozenStyles = element.style.cssText;
+  const originalPropertyValues = collectOriginalPropertyValues(element, properties);
 
-    for (const prop of properties) {
-      const computedValue = computed.getPropertyValue(prop);
-      if (computedValue) {
-        frozenStyles += `${prop}: ${computedValue} !important; `;
-      }
+  for (const prop of properties) {
+    const computedValue = computed.getPropertyValue(prop);
+    if (computedValue) {
+      frozenStyles += `${prop}: ${computedValue} !important; `;
     }
+  }
+
+  return { element, frozenStyles, originalPropertyValues };
+};
 
-    elementsToFreeze.push({ element, frozenStyles, originalPropertyValues });
+const collectHoveredElements = (cursorX: number, cursorY: number): HTMLElement[] => {
+  const hoveredElements: HTMLElement[] = [];
+  let current = document.elementFromPoint(cursorX, cursorY);
+  while (current && current !== document.documentElement) {
+    if (current instanceof HTMLElement) {
+      hoveredElements.push(current);
+    }
+    current = current.parentElement;
   }
+  return hoveredElements;
+};
 
-  return elementsToFreeze;
+const collectFocusedElements = (): HTMLElement[] => {
+  const focusedElements: HTMLElement[] = [];
+  let current: Element | null = document.activeElement;
+  while (current && current !== document.body) {
+    if (current instanceof HTMLElement) {
+      focusedElements.push(current);
+    }
+    const shadowRoot = current.shadowRoot;
+    current = shadowRoot?.activeElement ?? null;
+  }
+  return focusedElements;
 };
 
 const applyFrozenStates = (
@@ -152,7 +170,7 @@ export const resumePointerEventsFreeze = (): void => {
   if (pointerEventsStyle) pointerEventsStyle.disabled = false;
 };
 
-export const freezePseudoStates = (): void => {
+export const freezePseudoStates = (cursorX: number, cursorY: number): void => {
   if (pointerEventsStyle) return;
 
   for (const eventType of MOUSE_EVENTS_TO_BLOCK) {
@@ -163,12 +181,17 @@ export const freezePseudoStates = (): void => {
     document.addEventListener(eventType, preventFocusChange, true);
   }
 
-  const hoverStates = collectPseudoStates(":hover", HOVER_STYLE_PROPERTIES);
-  const focusStates = collectPseudoStates(
-    ":focus, :focus-visible",
-    FOCUS_STYLE_PROPERTIES,
-    frozenFocusElements,
-  );
+  const hoverStates: FrozenPseudoState[] = [];
+  for (const element of collectHoveredElements(cursorX, cursorY)) {
+    const state = freezeElement(element, HOVER_STYLE_PROPERTIES);
+    if (state) hoverStates.push(state);
+  }
+
+  const focusStates: FrozenPseudoState[] = [];
+  for (const element of collectFocusedElements()) {
+    const state = freezeElement(element, FOCUS_STYLE_PROPERTIES, frozenFocusElements);
+    if (state) focusStates.push(state);
+  }
 
   applyFrozenStates(hoverStates, frozenHoverElements);
   applyFrozenStates(focusStates, frozenFocusElements);

From 07130034cbf4697371ff2c95104e2652fb508f07 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Thu, 9 Apr 2026 14:02:10 -0700
Subject: [PATCH 30/45] fix: skip zero-area inline elements in smallest-area
 comparison

Inline elements (span, a without display:block) have clientWidth and
clientHeight of 0. Without this guard, their zero area always won the
smallest-area comparison, incorrectly prioritizing them over the
actual block-level content elements at the same point.
---
 packages/react-grab/src/utils/get-element-at-position.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/react-grab/src/utils/get-element-at-position.ts b/packages/react-grab/src/utils/get-element-at-position.ts
index ceeadcb65..b91052fa5 100644
--- a/packages/react-grab/src/utils/get-element-at-position.ts
+++ b/packages/react-grab/src/utils/get-element-at-position.ts
@@ -82,7 +82,10 @@ export const getElementAtPosition = (clientX: number, clientY: number): Element
 
   for (const candidateElement of elementsAtPoint) {
     if (!isValidGrabbableElement(candidateElement)) continue;
-    const area = candidateElement.clientWidth * candidateElement.clientHeight;
+    const candidateWidth = candidateElement.clientWidth;
+    const candidateHeight = candidateElement.clientHeight;
+    if (candidateWidth === 0 || candidateHeight === 0) continue;
+    const area = candidateWidth * candidateHeight;
     if (area < smallestArea) {
       smallestArea = area;
       result = candidateElement;

From 6bde5fc7d5b1c1ea394dcac2b942b0b17ddad37e Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Thu, 9 Apr 2026 14:23:10 -0700
Subject: [PATCH 31/45] fix: consistent area metric and contain shorthand in
 prehit

- Use clientWidth * clientHeight for area (same as fallback path)
  instead of boundingClientRect dimensions which include borders.
  Prevents selection flicker when prehit becomes ready after the
  first frame.
- Handle contain:strict and contain:content as paint containment.
  style.contain.includes("paint") missed these shorthands which
  both establish paint containment boundaries.
---
 packages/react-grab/src/utils/prehit.ts | 26 +++++++++++++++++++------
 1 file changed, 20 insertions(+), 6 deletions(-)

diff --git a/packages/react-grab/src/utils/prehit.ts b/packages/react-grab/src/utils/prehit.ts
index af9afcb21..5474b85bd 100644
--- a/packages/react-grab/src/utils/prehit.ts
+++ b/packages/react-grab/src/utils/prehit.ts
@@ -46,14 +46,19 @@ export const buildPrehitIndex = (): void => {
       for (const entry of entries) {
         observer.unobserve(entry.target);
 
+        const targetElement = entry.target as HTMLElement;
         const boundingRect = entry.boundingClientRect;
         if (boundingRect.width === 0 || boundingRect.height === 0) continue;
-        if (!isValidGrabbableElement(entry.target)) continue;
+        if (!isValidGrabbableElement(targetElement)) continue;
+
+        const elementWidth = targetElement.clientWidth;
+        const elementHeight = targetElement.clientHeight;
+        if (elementWidth === 0 || elementHeight === 0) continue;
 
         accumulatedElements.push({
-          element: entry.target,
-          area: boundingRect.width * boundingRect.height,
-          treeOrder: treeOrderMap.get(entry.target) ?? 0,
+          element: targetElement,
+          area: elementWidth * elementHeight,
+          treeOrder: treeOrderMap.get(targetElement) ?? 0,
         });
 
         accumulatedRects.push({
@@ -105,13 +110,22 @@ export const buildPrehitIndex = (): void => {
 };
 
 const CLIPPING_OVERFLOW_VALUES = new Set(["hidden", "scroll", "auto", "clip"]);
+const PAINT_CONTAIN_VALUES = new Set(["paint", "strict", "content"]);
+
+const hasPaintContainment = (containValue: string): boolean => {
+  for (const keyword of containValue.split(" ")) {
+    if (PAINT_CONTAIN_VALUES.has(keyword)) return true;
+  }
+  return false;
+};
 
 const isVisibleAtPoint = (element: Element, clientX: number, clientY: number): boolean => {
   let ancestor = element.parentElement;
   while (ancestor && ancestor !== document.documentElement) {
     const style = getComputedStyle(ancestor);
-    const clipsX = CLIPPING_OVERFLOW_VALUES.has(style.overflowX) || style.contain.includes("paint");
-    const clipsY = CLIPPING_OVERFLOW_VALUES.has(style.overflowY) || style.contain.includes("paint");
+    const isPaintContained = hasPaintContainment(style.contain);
+    const clipsX = CLIPPING_OVERFLOW_VALUES.has(style.overflowX) || isPaintContained;
+    const clipsY = CLIPPING_OVERFLOW_VALUES.has(style.overflowY) || isPaintContained;
 
     if (clipsX || clipsY) {
       const ancestorRect = ancestor.getBoundingClientRect();

From 1fde798c26b36b7cf0683f4b19d833c17a4eee08 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Thu, 9 Apr 2026 22:23:47 -0700
Subject: [PATCH 32/45] fix: handle inline elements and public freeze() API

Inline elements (a, span, em, code) have zero clientWidth/clientHeight
but nonzero getBoundingClientRect dimensions. The zero-area guard now
falls back to getBoundingClientRect before skipping, so inline elements
remain selectable.

The public freeze() API no longer passes fake viewport-center
coordinates. freezePseudoStates accepts optional cursor position:
when provided (internal activation), uses the fast elementFromPoint
walk; when omitted (public API), falls back to querySelectorAll(":hover")
to correctly capture all hovered elements regardless of cursor position.
---
 packages/react-grab/src/primitives.ts                 |  2 +-
 packages/react-grab/src/utils/freeze-pseudo-states.ts |  9 +++++++--
 .../react-grab/src/utils/get-element-at-position.ts   | 11 ++++++++---
 packages/react-grab/src/utils/prehit.ts               | 10 +++++++---
 4 files changed, 23 insertions(+), 9 deletions(-)

diff --git a/packages/react-grab/src/primitives.ts b/packages/react-grab/src/primitives.ts
index 85549567e..6a0320a6f 100644
--- a/packages/react-grab/src/primitives.ts
+++ b/packages/react-grab/src/primitives.ts
@@ -78,7 +78,7 @@ export const freeze = (elements?: Element[]): void => {
   freezeCleanupFns.add(freezeUpdates());
   freezeCleanupFns.add(freezeAnimations(elements ?? [document.body]));
   freezeGlobalAnimations();
-  freezePseudoStates(window.innerWidth / 2, window.innerHeight / 2);
+  freezePseudoStates();
 };
 
 /**
diff --git a/packages/react-grab/src/utils/freeze-pseudo-states.ts b/packages/react-grab/src/utils/freeze-pseudo-states.ts
index 10fbe93ae..4163a5a14 100644
--- a/packages/react-grab/src/utils/freeze-pseudo-states.ts
+++ b/packages/react-grab/src/utils/freeze-pseudo-states.ts
@@ -170,7 +170,7 @@ export const resumePointerEventsFreeze = (): void => {
   if (pointerEventsStyle) pointerEventsStyle.disabled = false;
 };
 
-export const freezePseudoStates = (cursorX: number, cursorY: number): void => {
+export const freezePseudoStates = (cursorX?: number, cursorY?: number): void => {
   if (pointerEventsStyle) return;
 
   for (const eventType of MOUSE_EVENTS_TO_BLOCK) {
@@ -182,7 +182,12 @@ export const freezePseudoStates = (cursorX: number, cursorY: number): void => {
   }
 
   const hoverStates: FrozenPseudoState[] = [];
-  for (const element of collectHoveredElements(cursorX, cursorY)) {
+  const hoveredElements = cursorX !== undefined && cursorY !== undefined
+    ? collectHoveredElements(cursorX, cursorY)
+    : Array.from(document.querySelectorAll(":hover")).filter(
+        (element): element is HTMLElement => element instanceof HTMLElement,
+      );
+  for (const element of hoveredElements) {
     const state = freezeElement(element, HOVER_STYLE_PROPERTIES);
     if (state) hoverStates.push(state);
   }
diff --git a/packages/react-grab/src/utils/get-element-at-position.ts b/packages/react-grab/src/utils/get-element-at-position.ts
index b91052fa5..6a0dd82c9 100644
--- a/packages/react-grab/src/utils/get-element-at-position.ts
+++ b/packages/react-grab/src/utils/get-element-at-position.ts
@@ -82,9 +82,14 @@ export const getElementAtPosition = (clientX: number, clientY: number): Element
 
   for (const candidateElement of elementsAtPoint) {
     if (!isValidGrabbableElement(candidateElement)) continue;
-    const candidateWidth = candidateElement.clientWidth;
-    const candidateHeight = candidateElement.clientHeight;
-    if (candidateWidth === 0 || candidateHeight === 0) continue;
+    let candidateWidth = candidateElement.clientWidth;
+    let candidateHeight = candidateElement.clientHeight;
+    if (candidateWidth === 0 || candidateHeight === 0) {
+      const rect = candidateElement.getBoundingClientRect();
+      candidateWidth = rect.width;
+      candidateHeight = rect.height;
+      if (candidateWidth === 0 || candidateHeight === 0) continue;
+    }
     const area = candidateWidth * candidateHeight;
     if (area < smallestArea) {
       smallestArea = area;
diff --git a/packages/react-grab/src/utils/prehit.ts b/packages/react-grab/src/utils/prehit.ts
index 5474b85bd..f9d67708b 100644
--- a/packages/react-grab/src/utils/prehit.ts
+++ b/packages/react-grab/src/utils/prehit.ts
@@ -51,9 +51,13 @@ export const buildPrehitIndex = (): void => {
         if (boundingRect.width === 0 || boundingRect.height === 0) continue;
         if (!isValidGrabbableElement(targetElement)) continue;
 
-        const elementWidth = targetElement.clientWidth;
-        const elementHeight = targetElement.clientHeight;
-        if (elementWidth === 0 || elementHeight === 0) continue;
+        let elementWidth = targetElement.clientWidth;
+        let elementHeight = targetElement.clientHeight;
+        if (elementWidth === 0 || elementHeight === 0) {
+          elementWidth = boundingRect.width;
+          elementHeight = boundingRect.height;
+          if (elementWidth === 0 || elementHeight === 0) continue;
+        }
 
         accumulatedElements.push({
           element: targetElement,

From 1e7541c8d0f33fbef1b1781773d721284512469a Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Thu, 9 Apr 2026 22:24:38 -0700
Subject: [PATCH 33/45] refactor: extract getElementArea helper for inline
 element fallback

Replaces the inline clientWidth/getBoundingClientRect fallback chain
with a focused helper. Uses clientWidth * clientHeight when nonzero
(block elements), falls back to getBoundingClientRect for inline
elements (span, a, em) where clientWidth is 0.
---
 .../src/utils/get-element-at-position.ts      | 19 ++++++++++---------
 packages/react-grab/src/utils/prehit.ts       | 12 ++++--------
 2 files changed, 14 insertions(+), 17 deletions(-)

diff --git a/packages/react-grab/src/utils/get-element-at-position.ts b/packages/react-grab/src/utils/get-element-at-position.ts
index 6a0dd82c9..cd0e26d87 100644
--- a/packages/react-grab/src/utils/get-element-at-position.ts
+++ b/packages/react-grab/src/utils/get-element-at-position.ts
@@ -43,6 +43,14 @@ const isWithinThreshold = (x1: number, y1: number, x2: number, y2: number): bool
   );
 };
 
+const getElementArea = (element: Element): number => {
+  const blockWidth = element.clientWidth;
+  const blockHeight = element.clientHeight;
+  if (blockWidth > 0 && blockHeight > 0) return blockWidth * blockHeight;
+  const rect = element.getBoundingClientRect();
+  return rect.width * rect.height;
+};
+
 export const getElementsAtPoint = (clientX: number, clientY: number): Element[] => {
   if (!Number.isFinite(clientX) || !Number.isFinite(clientY)) return [];
   cancelScheduledResume();
@@ -82,15 +90,8 @@ export const getElementAtPosition = (clientX: number, clientY: number): Element
 
   for (const candidateElement of elementsAtPoint) {
     if (!isValidGrabbableElement(candidateElement)) continue;
-    let candidateWidth = candidateElement.clientWidth;
-    let candidateHeight = candidateElement.clientHeight;
-    if (candidateWidth === 0 || candidateHeight === 0) {
-      const rect = candidateElement.getBoundingClientRect();
-      candidateWidth = rect.width;
-      candidateHeight = rect.height;
-      if (candidateWidth === 0 || candidateHeight === 0) continue;
-    }
-    const area = candidateWidth * candidateHeight;
+    const area = getElementArea(candidateElement);
+    if (area === 0) continue;
     if (area < smallestArea) {
       smallestArea = area;
       result = candidateElement;
diff --git a/packages/react-grab/src/utils/prehit.ts b/packages/react-grab/src/utils/prehit.ts
index f9d67708b..9fb0ca431 100644
--- a/packages/react-grab/src/utils/prehit.ts
+++ b/packages/react-grab/src/utils/prehit.ts
@@ -51,17 +51,13 @@ export const buildPrehitIndex = (): void => {
         if (boundingRect.width === 0 || boundingRect.height === 0) continue;
         if (!isValidGrabbableElement(targetElement)) continue;
 
-        let elementWidth = targetElement.clientWidth;
-        let elementHeight = targetElement.clientHeight;
-        if (elementWidth === 0 || elementHeight === 0) {
-          elementWidth = boundingRect.width;
-          elementHeight = boundingRect.height;
-          if (elementWidth === 0 || elementHeight === 0) continue;
-        }
+        const elementArea = targetElement.clientWidth * targetElement.clientHeight
+          || boundingRect.width * boundingRect.height;
+        if (elementArea === 0) continue;
 
         accumulatedElements.push({
           element: targetElement,
-          area: elementWidth * elementHeight,
+          area: elementArea,
           treeOrder: treeOrderMap.get(targetElement) ?? 0,
         });
 

From 2dee7a526f9e4b6f651deb127261523d025957ac Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Thu, 9 Apr 2026 22:35:23 -0700
Subject: [PATCH 34/45] refactor: rename prehit to spatial-index and delete
 docs/

prehit.ts -> spatial-index.ts
buildPrehitIndex -> buildSpatialIndex
queryPrehitIndex -> querySpatialIndex
isPrehitIndexReady -> isSpatialIndexReady
destroyPrehitIndex -> destroySpatialIndex
PREHIT_ROOT_MARGIN_PX -> SPATIAL_INDEX_ROOT_MARGIN_PX

Removed docs/perf-learnings.md and docs/prehit.md.
---
 docs/perf-learnings.md                        | 431 ------------------
 docs/prehit.md                                | 278 -----------
 packages/react-grab/src/constants.ts          |   2 +-
 packages/react-grab/src/core/index.tsx        |   8 +-
 .../src/utils/get-element-at-position.ts      |  12 +-
 .../src/utils/{prehit.ts => spatial-index.ts} |  18 +-
 6 files changed, 20 insertions(+), 729 deletions(-)
 delete mode 100644 docs/perf-learnings.md
 delete mode 100644 docs/prehit.md
 rename packages/react-grab/src/utils/{prehit.ts => spatial-index.ts} (91%)

diff --git a/docs/perf-learnings.md b/docs/perf-learnings.md
deleted file mode 100644
index 37708bc6a..000000000
--- a/docs/perf-learnings.md
+++ /dev/null
@@ -1,431 +0,0 @@
-# Performance Learnings
-
-Patterns studied from Inferno, SolidJS, ivi, and pretext that inform react-grab's element detection pipeline.
-
-## Detection Pipeline
-
-```
-pointermove (every ~8ms, browser-fired)
-  -> 32ms throttle gate (ELEMENT_DETECTION_THROTTLE_MS)
-    -> setTimeout(0) macrotask deferral
-      -> position cache (2px distance + 16ms time gate)
-        -> suspendPointerEventsFreeze (O(1) stylesheet toggle)
-        -> elementsFromPoint (forces style recalc -- dominant cost)
-        -> per-element: visibilityCache check (WeakMap, 50ms TTL)
-        -> per-element: getComputedStyle (only on cache miss)
-        -> per-element: clientWidth * clientHeight (area comparison)
-        -> scheduleResume (100ms debounced pointer-events restore)
-```
-
-The style recalculation from the pointer-events toggle is 95%+ of detection cost (1-5ms on dense DOMs). Everything after it (per-element checks, area comparison) is <0.1ms.
-
-## Why setTimeout(0) for Detection Scheduling
-
-| Primitive | Where it runs | Latency | Frame budget impact |
-|---|---|---|---|
-| `scheduler.postTask("background")` | Background task | 350ms-5000ms (starved on busy pages) | None |
-| `queueMicrotask` | Before paint | ~0ms | Blocks frame |
-| `requestAnimationFrame` | Render pipeline | ~16ms | Eats frame budget |
-| `setTimeout(0)` | Separate macrotask | ~1ms | None |
-
-`queueMicrotask` is wrong here despite being the standard choice for UI frameworks. ivi, Preact, and Solid all use it for state batching:
-
-```javascript
-// ivi: microtask for dirty check flush
-export const createRoot = defineRoot((root) => {
-  _queueMicrotask(() => {
-    _dirtyCheckRoot(root, 0);
-  });
-});
-
-// Preact: microtask for render queue
-export function enqueueRender(c) {
-  // ...
-  (prevDebounce || queueMicrotask)(process);
-}
-
-// Solid: microtask via runUpdates
-function runUpdates(fn, init) {
-  if (Updates) return fn();
-  Updates = [];
-  ExecCount++;
-  // ... flush after fn() returns
-}
-```
-
-Those frameworks schedule lightweight JS work (dirty flag walks, VDOM diffs). Our detection forces the browser's layout engine via `elementsFromPoint`, which is categorically heavier and should not block the current frame's paint.
-
-`scheduler.postTask("background")` was the original implementation. Runtime instrumentation on nisarg.io confirmed multi-second starvation:
-
-```json
-{"message":"onIdle detection","data":{"idleDelayMs":5010}}
-{"message":"onIdle detection","data":{"idleDelayMs":350}}
-```
-
-Only 2 detections in 7 seconds of hovering. The background priority was starved by React renders and CSS animations.
-
-`setTimeout(0)` fires in ~1ms as a separate macrotask. No nesting-based 4ms clamping applies because each call originates from a distinct pointermove handler:
-
-```typescript
-// handlePointerMove (called from pointermove event handler)
-setTimeout(() => {
-  const candidate = getElementAtPosition(
-    elementDetectionState.latestPointerX,
-    elementDetectionState.latestPointerY,
-  );
-  if (candidate !== store.detectedElement) {
-    actions.setDetectedElement(candidate);
-  }
-  elementDetectionState.pendingDetectionScheduledAt = 0;
-});
-```
-
-After the fix, detection runs at ~26ms intervals (matching the 32ms throttle + macrotask overhead).
-
-## Techniques Applied
-
-### Smallest-element selection
-
-**Inspired by:** pretext's two-phase pattern (prepare once, compute cheaply).
-
-pretext separates expensive measurement from cheap arithmetic:
-
-```typescript
-// pretext: prepare() measures via canvas, layout() does pure arithmetic
-function prepare(text, font) {
-  // segments text, measures each word via canvas, caches widths
-  // call once when text first appears
-}
-
-function layout(prepared, maxWidth, lineHeight) {
-  // walks cached word widths with pure arithmetic
-  // ~0.0002ms per text block, call on every resize
-  const lineCount = countPreparedLines(getInternalPrepared(prepared), maxWidth);
-  return { lineCount, height: lineCount * lineHeight };
-}
-```
-
-Our detection applies this principle. `elementsFromPoint` is the expensive "prepare" (z-ordered stack with forced style recalc). The smallest-area selection is the cheap "layout" (integer arithmetic on cached values):
-
-```typescript
-// react-grab: elementsFromPoint is "prepare", area comparison is "layout"
-const elementsAtPoint = document.elementsFromPoint(clientX, clientY);
-let result: Element | null = null;
-let smallestArea = Infinity;
-
-for (const candidateElement of elementsAtPoint) {
-  if (!isValidGrabbableElement(candidateElement)) continue;
-  const area = candidateElement.clientWidth * candidateElement.clientHeight;
-  if (area < smallestArea) {
-    smallestArea = area;
-    result = candidateElement;
-  }
-}
-```
-
-This naturally selects the most specific content element. A decorative overlay div covering an entire card (380x115 = 43,700 area) loses to the `<p>` inside it (200x48 = 9,600 area). No heuristic filtering needed.
-
-### Visibility cache with WeakMap
-
-**Inspired by:** ivi (template descriptor cache), pretext (line text cache).
-
-ivi caches compiled template descriptors keyed by `TemplateStringsArray` identity:
-
-```typescript
-// ivi: WeakMap keyed by template literal identity
-const DESCRIPTORS = new WeakMap<TemplateStringsArray, (exprs: any[]) => VAny>();
-
-export const html = (strings: TemplateStringsArray, ...exprs: any[]) => {
-  let fn = DESCRIPTORS.get(strings);
-  if (fn === void 0) {
-    fn = compileTemplate(strings);
-    DESCRIPTORS.set(strings, fn);
-  }
-  return fn(exprs);
-};
-```
-
-pretext caches grapheme splits keyed by prepared handle, using `WeakMap` so entries are GC'd when the handle is dropped:
-
-```typescript
-// pretext: WeakMap allows GC without explicit invalidation
-let sharedLineTextCaches = new WeakMap<
-  PreparedTextWithSegments,
-  Map<number, string[]>
->();
-```
-
-react-grab's `visibilityCache` follows the same pattern. Elements that leave the DOM are GC'd automatically. The 50ms TTL is generous enough that within a single detection pass (~5ms), all cache entries remain valid:
-
-```typescript
-// react-grab: WeakMap<Element> + TTL for automatic cleanup
-let visibilityCache = new WeakMap<Element, VisibilityCache>();
-
-// in isValidGrabbableElement:
-const cached = visibilityCache.get(element);
-if (cached && now - cached.timestamp < VISIBILITY_CACHE_TTL_MS) {
-  return cached.isVisible; // skip getComputedStyle + all checks
-}
-```
-
-### clientWidth/clientHeight over getBoundingClientRect
-
-**Inspired by:** Inferno's `nodeValue` over `textContent` (avoiding unnecessary work for the same result).
-
-Inferno uses `CharacterData.nodeValue` for text updates instead of `Element.textContent`, because `textContent` goes through a more expensive parser path:
-
-```typescript
-// Inferno: nodeValue is a direct CharacterData mutation
-if (nextText !== lastVNode.children) {
-  (dom as Text).nodeValue = nextText;
-}
-```
-
-Similarly, `clientWidth * clientHeight` reads plain integer properties from the layout cache. `getBoundingClientRect()` constructs a `DOMRect` object with fractional coordinates we don't need for area comparison. Both read from the same layout (already computed by `elementsFromPoint`), but the property read avoids per-element object allocation:
-
-```typescript
-// Allocation: constructs a DOMRect with x, y, width, height, top, right, bottom, left
-const { width, height } = element.getBoundingClientRect();
-const area = width * height;
-
-// No allocation: reads integer properties directly from the layout cache
-const area = element.clientWidth * element.clientHeight;
-```
-
-### O(1) pointer-events toggle via inherited CSS
-
-**Inspired by:** Inferno's `EMPTY_OBJ` singleton (one object, reference equality for fast skipping).
-
-The pointer-events freeze applies `pointer-events: none` on `<html>` rather than `*`. Since `pointer-events` is inherited, toggling it on a single root element is O(1) style invalidation instead of O(N) for every DOM node:
-
-```typescript
-// O(N): every node gets its own style invalidation
-const POINTER_EVENTS_STYLES = "* { pointer-events: none !important; }";
-
-// O(1): one root toggle, inherited by all descendants
-const POINTER_EVENTS_STYLES = "html { pointer-events: none !important; }";
-```
-
-This was changed after observing visible lag on dense DOMs like GitHub diff viewers with 10k+ nodes.
-
-### Debounced pointer-events resume
-
-The pointer-events stylesheet is suspended (disabled) before `elementsFromPoint` for hit-testing. Instead of re-enabling synchronously (which would force another style invalidation), the resume is debounced to 100ms:
-
-```typescript
-const scheduleResume = (): void => {
-  if (resumeTimerId !== null) {
-    clearTimeout(resumeTimerId);
-  }
-  resumeTimerId = setTimeout(() => {
-    resumeTimerId = null;
-    resumePointerEventsFreeze();
-  }, POINTER_EVENTS_RESUME_DEBOUNCE_MS);
-};
-```
-
-On rapid successive detections (every 32ms), `cancelScheduledResume` prevents the resume from firing, so the stylesheet stays disabled. This makes the `suspendPointerEventsFreeze` call a no-op on the next detection (stylesheet is already disabled). The resume only fires after 100ms of no detection activity.
-
-## Techniques Studied but Not Applied
-
-### Bitwise flags for type dispatch (Inferno, ivi)
-
-Inferno encodes vnode type in a single integer. One `&` tests a bit vs multiple property reads:
-
-```typescript
-// Inferno: bitmask dispatch
-export const enum VNodeFlags {
-  HtmlElement = 1,
-  ComponentClass = 1 << 2,
-  ComponentFunction = 1 << 3,
-  Text = 1 << 4,
-  SvgElement = 1 << 5,
-  Element = HtmlElement | SvgElement | FormElement,
-  Component = ComponentFunction | ComponentClass,
-}
-
-// One integer test replaces multiple string comparisons
-if (nextFlags & VNodeFlags.Element) {
-  patchElement(lastVNode, nextVNode, context, isSVG, lifecycle, animations);
-} else if (nextFlags & VNodeFlags.ComponentClass) {
-  // ...
-}
-```
-
-ivi packs type + dirty + update flags in one word:
-
-```typescript
-// ivi: combined type/state flags
-export const enum Flags {
-  Template = 1,
-  Component = 1 << 1,
-  Dirty = 1 << 7,
-  DirtySubtree = 1 << 8,
-  ForceUpdate = 1 << 9,
-  TypeMask = (1 << 7) - 1,
-}
-
-// One & extracts type, another checks dirty
-const type = flags & Flags.TypeMask;
-if (flags & Flags.DirtySubtree) { /* recurse */ }
-```
-
-**Not applied** because react-grab's `isValidGrabbableElement` checks are attribute-based (`hasAttribute`, `closest`) and CSS-based (`getComputedStyle`), not type-based. The checks don't map to a fixed set of bits.
-
-### Monotonic generation counter (Solid)
-
-Solid increments `ExecCount` once per update cycle. A computation with `updatedAt >= ExecCount` is already current and can be skipped:
-
-```typescript
-// Solid: monotonic epoch prevents redundant recomputation
-ExecCount++;
-
-function runTop(node) {
-  if (node.state === 0) return; // already clean
-  const ancestors = [node];
-  while (
-    (node = node.owner) &&
-    (!node.updatedAt || node.updatedAt < ExecCount)
-  ) {
-    if (node.state) ancestors.push(node);
-  }
-  // run ancestors root-to-leaf
-  for (let i = ancestors.length - 1; i >= 0; i--) {
-    updateComputation(ancestors[i]);
-  }
-}
-```
-
-**Not applied** because react-grab's 50ms visibility cache TTL already provides within-pass deduplication (a detection pass takes <5ms).
-
-### Dirty flag propagation with early exit (ivi)
-
-ivi's `invalidate` stops walking ancestors when one already has `DirtySubtree`:
-
-```typescript
-// ivi: O(depth) invalidation with early exit
-export const invalidate = (c: Component): void => {
-  if (!(c.f & Flags.Dirty)) {
-    c.f |= Flags.Dirty;
-    let parent = c.p;
-    while (parent !== null) {
-      if (parent.f & Flags.DirtySubtree) return; // already marked
-      parent.f |= Flags.DirtySubtree;
-      parent = parent.p;
-    }
-  }
-};
-```
-
-**Not applied** because react-grab doesn't maintain a component tree. Detection is a flat iteration over `elementsFromPoint` results.
-
-### Swap-remove for O(1) array unlinking (Solid)
-
-Solid's `cleanNode` avoids O(n) array splice by popping from the end and swapping into the removed slot:
-
-```typescript
-// Solid: O(1) observer removal
-function cleanNode(node) {
-  while (node.sources.length) {
-    const source = node.sources.pop();
-    const index = node.sourceSlots.pop();
-    const obs = source.observers;
-    if (obs && obs.length) {
-      const n = obs.pop();           // take last
-      const s = source.observerSlots.pop();
-      if (index < obs.length) {
-        n.sourceSlots[s] = index;    // update back-pointer
-        obs[index] = n;              // swap into removed slot
-        source.observerSlots[index] = s;
-      }
-    }
-  }
-}
-```
-
-**Not applied** because react-grab doesn't maintain observer/subscription arrays.
-
-### Node.prototype patching for hidden class uniformity (Inferno)
-
-Inferno adds properties to `Node.prototype` to prevent ad-hoc expandos from creating divergent hidden maps:
-
-```typescript
-// Inferno: V8 hidden class fix
-if (window.Node) {
-  // Defining $EV and $V properties on Node.prototype
-  // fixes v8 "wrong map" de-optimization
-  (Node.prototype as any).$EV = null;
-  (Node.prototype as any).$V = null;
-}
-```
-
-**Not applied** because react-grab doesn't add expando properties to DOM nodes.
-
-### Object.seal for JIT map elimination (ivi)
-
-ivi seals hot-path context objects so V8 can eliminate shape checks:
-
-```typescript
-// ivi: sealed object for JIT optimization
-const RENDER_CONTEXT = { p: null, n: null, e: null };
-Object.seal(RENDER_CONTEXT);
-// "JIT can eliminate object map checks"
-```
-
-**Not applied** because react-grab's hot-path objects are already small and stable-shaped.
-
-### Local const aliases of globals (ivi)
-
-ivi caches global functions as module-level `const` to help the JIT inline and eliminate override checks:
-
-```typescript
-// ivi: local aliases for JIT inlining
-const _queueMicrotask = queueMicrotask;
-const _requestAnimationFrame = requestAnimationFrame;
-const _requestIdleCallback = requestIdleCallback;
-const _isArray = Array.isArray;
-```
-
-react-grab already does this for `requestAnimationFrame` (via `native-raf.ts` which reads from `Window.prototype` to bypass GSAP freeze wrappers), but doesn't apply the pattern broadly since the detection hot path makes few global calls.
-
-### IntersectionObserver for reflow-free measurement
-
-IO entries include `boundingClientRect` without triggering synchronous reflow. However:
-
-- IO is async (1-frame latency), detection needs sync results
-- IO doesn't provide z-order information (which elements are on TOP at a point)
-- After `elementsFromPoint` forces layout, `clientWidth`/`clientHeight` reads are already free (layout is cached from the forced recalc)
-
-The IO pattern is powerful for different use cases (virtual scrolling, lazy loading, resize-responsive layouts) but does not help with point-based hit-testing.
-
-### Int32Array for keyed reconciliation (Inferno, ivi)
-
-Both Inferno and ivi use `Int32Array` for LIS (longest increasing subsequence) in keyed list reconciliation:
-
-```typescript
-// Inferno: typed array reuse across reconciliations
-let result: Int32Array;
-let p: Int32Array;
-let maxLen = 0;
-
-function lisAlgorithm(arr: Int32Array): Int32Array {
-  const len = arr.length;
-  if (len > maxLen) {
-    maxLen = len;
-    result = new Int32Array(len);
-    p = new Int32Array(len);
-  }
-  // ...binary search with >> 1 midpoint...
-}
-```
-
-**Not applied** because react-grab doesn't reconcile lists. The detection loop iterates `elementsFromPoint` results linearly.
-
-## Reference Codebases
-
-| Project | Key insight | Scheduling primitive |
-|---|---|---|
-| [Inferno](https://github.com/infernojs/inferno) | Bitwise flags for O(1) type dispatch, `Int32Array` buffer reuse in LIS, prototype patching for V8 hidden class stability | `Promise.resolve().then` microtask |
-| [SolidJS](https://github.com/solidjs/solid) | Monotonic `ExecCount` prevents redundant recomputation, three-state machine (clean/STALE/PENDING) defers work until dependencies resolve | `queueMicrotask` for signals, `rAF` for effects |
-| [ivi](https://github.com/localvoid/ivi) | `DirtySubtree` flag propagation with early exit, sealed render context for JIT, local const aliases of globals, right-to-left iteration for stable `insertBefore` cursors | `queueMicrotask` for state, `rAF` for visual, `rIC` for idle |
-| [pretext](https://github.com/chenglou/pretext) | Two-phase measurement (prepare once / layout many), canvas `measureText` avoids DOM reflow, `WeakMap` for GC-friendly caching, `simpleLineWalkFastPath` flag skips complex line-break logic | Fully synchronous (no scheduling needed) |
diff --git a/docs/prehit.md b/docs/prehit.md
deleted file mode 100644
index a4a6e32cf..000000000
--- a/docs/prehit.md
+++ /dev/null
@@ -1,278 +0,0 @@
-# Prehit: Pre-indexed Element Hit Testing
-
-An alternative to `elementsFromPoint` that eliminates per-hover style recalculations by pre-indexing element bounding rects into a spatial index at activation time.
-
-## Problem
-
-Every hover detection currently costs 1-5ms on dense DOMs because `elementsFromPoint` forces a synchronous style recalculation. This recalc is triggered by the `pointer-events: none` stylesheet toggle needed for hit-testing. The cost scales with DOM size and CSS complexity.
-
-```
-Current hot path (per hover, 1-5ms):
-  suspendPointerEventsFreeze()     ← toggles <style>, dirties style tree
-  elementsFromPoint(x, y)         ← forces full Recalculate Style
-  per-element: getComputedStyle   ← reads from recalced styles
-  scheduleResume()                ← will dirty styles again
-```
-
-## Insight
-
-The page is **frozen** during selection mode. `freezeGlobalAnimations` pauses all animations and transitions. `freezeUpdates` intercepts React state updates. Nothing moves. This means element positions measured at activation time remain valid for the entire session.
-
-This is the same invariant that makes [pretext](https://github.com/chenglou/pretext) work: text is immutable after `prepare()`, so `layout()` can be pure arithmetic on cached numbers. Our DOM is immutable after activation, so `query()` can be pure arithmetic on cached rects.
-
-## Design
-
-### Phase 1: `index()` (runs once at activation, async, zero reflow)
-
-Use `IntersectionObserver` to collect element bounding rects without forcing synchronous reflow. IO entries include `boundingClientRect` as part of the browser's normal rendering pipeline -- the browser already computed these positions; IO just exposes them.
-
-```typescript
-interface IndexedElement {
-  element: Element
-  left: number      // page-relative (viewport + scrollX)
-  top: number       // page-relative (viewport + scrollY)
-  right: number
-  bottom: number
-  area: number      // precomputed for smallest-element selection
-  treeOrder: number  // DOM tree order for z-order proxy
-}
-
-const indexElements = (): void => {
-  const elements: IndexedElement[] = []
-  let treeOrder = 0
-
-  const observer = new IntersectionObserver((entries) => {
-    const scrollX = window.scrollX
-    const scrollY = window.scrollY
-
-    for (const entry of entries) {
-      const rect = entry.boundingClientRect
-      if (rect.width === 0 || rect.height === 0) continue
-
-      elements.push({
-        element: entry.target,
-        left: rect.left + scrollX,
-        top: rect.top + scrollY,
-        right: rect.right + scrollX,
-        bottom: rect.bottom + scrollY,
-        area: rect.width * rect.height,
-        treeOrder: treeOrderMap.get(entry.target) ?? 0,
-      })
-      observer.unobserve(entry.target)
-    }
-
-    buildSpatialIndex(elements)
-  })
-
-  // Walk DOM tree: observe each visible element and record tree order.
-  // Filtering is critical -- a page can have 10k+ DOM nodes, but only
-  // 200-500 are visible content elements worth indexing.
-  const treeOrderMap = new Map<Element, number>()
-  const SKIP_TAGS = new Set([
-    "SCRIPT", "STYLE", "HEAD", "META", "LINK",
-    "NOSCRIPT", "BR", "TEMPLATE", "SLOT",
-  ])
-
-  const walker = document.createTreeWalker(
-    document.body,
-    NodeFilter.SHOW_ELEMENT,
-    {
-      acceptNode: (node) =>
-        SKIP_TAGS.has((node as Element).tagName)
-          ? NodeFilter.FILTER_REJECT  // skip node AND its subtree
-          : NodeFilter.FILTER_ACCEPT,
-    },
-  )
-
-  while (walker.nextNode()) {
-    const element = walker.currentNode as HTMLElement
-
-    // offsetWidth/offsetHeight are cached layout values (no reflow since
-    // freeze already triggered style recalc). Skips display:none, hidden
-    // elements, and zero-size wrappers.
-    if (element.offsetWidth === 0 && element.offsetHeight === 0) continue
-
-    treeOrderMap.set(element, treeOrder++)
-    observer.observe(element)
-  }
-}
-```
-
-**Why filtering matters:** a naive `querySelectorAll("*")` or unfiltered `TreeWalker` visits every DOM node. On a page with 10k+ nodes, observing each via IO costs 5-20ms. The two filters above (skip non-visual tags via `FILTER_REJECT`, skip zero-size elements via `offsetWidth`/`offsetHeight`) reduce the set to ~200-500 elements, bringing the observe loop under 1ms.
-
-`offsetWidth`/`offsetHeight` are safe here because the freeze already triggered a style recalc and layout pass. These properties read from the cached layout, not a forced reflow.
-
-**Why IO is free:** the IO callback fires after the browser's rendering pipeline completes (style recalc -> layout -> paint -> IO callbacks). At that point, `boundingClientRect` is just reading from the already-computed layout. No forced reflow.
-
-**Why page coordinates:** storing `rect.left + scrollX` makes the index scroll-invariant. Scroll changes viewport-relative positions but not page-relative ones. Only actual layout changes (resize, DOM mutation) would invalidate the index -- and those can't happen because the page is frozen.
-
-### Phase 2: Build spatial index (runs once, ~1ms)
-
-Use a [Flatbush](https://github.com/mourner/flatbush) packed Hilbert R-tree for O(log n) point queries. Flatbush is 462 lines of JavaScript with zero dependencies (the `neighbors()` method uses `flatqueue` but we don't need it). We vendor a TypeScript port.
-
-```typescript
-import { Flatbush } from "../vendor/flatbush.js"
-
-const buildSpatialIndex = (elements: IndexedElement[]): void => {
-  const index = new Flatbush(elements.length)
-
-  for (const element of elements) {
-    index.add(element.left, element.top, element.right, element.bottom)
-  }
-  index.finish()
-
-  spatialIndex = { index, elements }
-}
-```
-
-**How Flatbush works:**
-
-1. `add(minX, minY, maxX, maxY)` stores rects in a flat `Float64Array` (4 floats per rect)
-2. `finish()` computes a Hilbert curve value for each rect's center, sorts rects by Hilbert value (spatial locality), then builds parent bounding boxes bottom-up in `nodeSize`-wide groups
-3. `search(minX, minY, maxX, maxY)` walks the tree top-down, pruning branches whose bounding box doesn't intersect the query. Returns indices of matching leaf rects.
-
-The Hilbert sort ensures spatially close rects are stored near each other in memory, giving good cache performance on queries.
-
-### Phase 3: `query(x, y)` (runs per hover, ~0.005ms)
-
-Pure arithmetic. No DOM reads. No style recalc. No pointer-events toggle.
-
-```typescript
-const queryElement = (clientX: number, clientY: number): Element | null => {
-  if (!spatialIndex) return null
-
-  const pageX = clientX + window.scrollX
-  const pageY = clientY + window.scrollY
-
-  // O(log n) spatial query
-  const hitIndices = spatialIndex.index.search(pageX, pageY, pageX, pageY)
-  if (hitIndices.length === 0) return null
-
-  // Among hits, prefer smallest area. Tiebreak by DOM tree order (higher = painted later = on top).
-  let bestElement: IndexedElement | null = null
-
-  for (const hitIndex of hitIndices) {
-    const candidate = spatialIndex.elements[hitIndex]
-    if (!bestElement) {
-      bestElement = candidate
-      continue
-    }
-
-    if (candidate.area < bestElement.area) {
-      bestElement = candidate
-    } else if (candidate.area === bestElement.area && candidate.treeOrder > bestElement.treeOrder) {
-      bestElement = candidate
-    }
-  }
-
-  return bestElement?.element ?? null
-}
-```
-
-## Z-Order
-
-The spatial index doesn't know visual stacking order. Three approaches, in order of cost:
-
-### 1. DOM tree order (zero cost, handles 99% of cases)
-
-Recorded during the tree walk at index time. Later in tree = painted later = visually on top (for siblings in the same stacking context). Used as a tiebreaker when two candidates have the same area.
-
-### 2. `stacking-order` comparison (cheap in frozen state)
-
-[Rich Harris's `stacking-order](https://github.com/Rich-Harris/stacking-order)` (111 lines) computes pairwise visual ordering by walking ancestor chains and comparing stacking contexts. Uses `getComputedStyle`, which is a cache read (no recalc) inside the IO callback since the browser just rendered.
-
-We vendor a TypeScript port and use it only for Flatbush query results (typically 3-5 elements), not for the full element set:
-
-```typescript
-import { compareStackingOrder } from "../vendor/stacking-order.js"
-
-// Only among the 3-5 Flatbush hits at this point:
-hits.sort((a, b) => compareStackingOrder(a.element, b.element))
-```
-
-Cost per query: ~5 pairwise comparisons * ~10 `getComputedStyle` reads (cached) = ~0.05ms. Negligible compared to the current 1-5ms.
-
-### 3. `elementsFromPoint` fallback (expensive, last resort)
-
-For edge cases where the above heuristics fail. In practice this should almost never fire.
-
-## Activation Timeline
-
-```
-activation event
-  ├── freezeGlobalAnimations()       ← pauses animations/transitions (page is now static)
-  ├── freezePseudoStates()           ← pointer-events: none, freeze :hover/:focus
-  ├── TreeWalker assigns treeOrder   ← O(n) integer increments
-  └── IO.observe(all elements)       ← async, schedules observation
-
-next rendering opportunity (browser does this anyway):
-  ├── Style recalculation            ← resolves freeze stylesheets
-  ├── Layout                         ← computes element positions
-  ├── Paint                          ← renders
-  └── IO callback fires              ← entries have free boundingClientRect
-       ├── Collect rects (page coords)
-       ├── Build Flatbush (~1ms for 500 elements)
-       └── Index is ready
-
-every subsequent hover (for entire session):
-  └── queryElement(clientX, clientY)  ← O(log n), ~0.005ms, no DOM
-
-deactivation:
-  ├── Discard spatial index
-  ├── unfreezeGlobalAnimations()
-  └── unfreezePseudoStates()
-```
-
-**Gap handling:** between activation and the IO callback (~1 frame, ~16ms), the index isn't ready. During this window, fall back to the current `elementsFromPoint` path. After the first frame, all subsequent hovers use the spatial index.
-
-## What This Eliminates
-
-
-| Operation                        | Current (per hover)              | With Prehit (per hover)   |
-| -------------------------------- | -------------------------------- | ------------------------- |
-| pointer-events stylesheet toggle | Every 32ms                       | Never (only on fallback)  |
-| `elementsFromPoint`              | Every 32ms (forces style recalc) | Never (only on fallback)  |
-| `getComputedStyle`               | Per candidate element            | Never (index precomputed) |
-| Style recalculation              | 1-5ms per detection              | 0ms                       |
-| **Total per-hover cost**         | **1-5ms**                        | **~0.005ms**              |
-
-
-## Vendored Dependencies
-
-Both libraries are small enough to vendor as TypeScript ports rather than adding npm dependencies:
-
-### Flatbush (from [mourner/flatbush](https://github.com/mourner/flatbush))
-
-- 462 lines of JavaScript, ISC license
-- Packed Hilbert R-tree: O(n) build, O(log n) search
-- Internally stores rects in a flat `Float64Array` with `Uint16Array`/`Uint32Array` indices
-- We only need `add()`, `finish()`, `search()`. The `neighbors()` method (k-nearest-neighbors) and its `flatqueue` dependency can be dropped.
-- Port to TypeScript, remove `from()` serialization (we don't need cross-thread transfer), remove `neighbors()`.
-
-### stacking-order (from [Rich-Harris/stacking-order](https://github.com/Rich-Harris/stacking-order))
-
-- 111 lines of JavaScript, MIT license
-- Pairwise comparison: walks ancestor chains, finds lowest common ancestor, checks stacking contexts, compares z-index, falls back to DOM sibling order
-- Port to TypeScript with proper typing. Can drop `webkit`-prefixed property checks (not needed for modern browsers).
-
-## Limitations
-
-- **1-frame startup latency:** the IO callback fires after the next rendering opportunity. First ~16ms falls back to `elementsFromPoint`.
-- **Scroll accuracy:** page-coordinate storage handles scroll correctly, but if the user scrolls during selection mode, elements that scroll into view from off-screen won't be indexed. Acceptable because the freeze prevents most scroll-triggering interactions.
-- **CSS transforms:** `getBoundingClientRect` (via IO) returns the transformed rect. Rotated or skewed elements have axis-aligned bounding boxes that are larger than the visual element. This could cause false positives in the spatial query, but the smallest-area heuristic mitigates it.
-- **Dynamic content:** if the freeze doesn't catch some mutation (e.g., a CSS animation that started before freeze took effect), the index could be stale. The freeze is designed to prevent this, but edge cases exist.
-- **Shadow DOM:** `TreeWalker` doesn't cross shadow boundaries by default. Elements inside shadow roots (other than react-grab's own) won't be indexed. This is acceptable because shadow DOM content is typically self-contained.
-
-## Comparison to pretext
-
-
-| Aspect                     | pretext                                                  | prehit                                          |
-| -------------------------- | -------------------------------------------------------- | ----------------------------------------------- |
-| **"prepare" phase**        | Canvas `measureText` per word segment                    | IO `boundingClientRect` per element             |
-| **"layout" phase**         | Walk cached widths, count lines (arithmetic)             | Flatbush `search()`, pick smallest (arithmetic) |
-| **Immutability guarantee** | Text doesn't change between prepare and layout           | DOM is frozen between index and query           |
-| **Cache granularity**      | Per segment x font (`Map<string, Map<string, Metrics>>`) | Per element (`Float64Array` in Flatbush)        |
-| **Invalidation**           | `clearCache()` on locale/font change                     | Discard index on deactivation                   |
-| **Hot path cost**          | ~0.0002ms per text block                                 | ~0.005ms per point query                        |
-
-
diff --git a/packages/react-grab/src/constants.ts b/packages/react-grab/src/constants.ts
index bd0ac371b..6837d9dc0 100644
--- a/packages/react-grab/src/constants.ts
+++ b/packages/react-grab/src/constants.ts
@@ -130,7 +130,7 @@ export const ELEMENT_POSITION_THROTTLE_MS = 16;
 export const POINTER_EVENTS_RESUME_DEBOUNCE_MS = 100;
 export const VISIBILITY_CACHE_TTL_MS = 50;
 
-export const PREHIT_ROOT_MARGIN_PX = 10_000;
+export const SPATIAL_INDEX_ROOT_MARGIN_PX = 10_000;
 
 export const ZOOM_DETECTION_THRESHOLD = 0.01;
 
diff --git a/packages/react-grab/src/core/index.tsx b/packages/react-grab/src/core/index.tsx
index f0019333f..e8bd1f74e 100644
--- a/packages/react-grab/src/core/index.tsx
+++ b/packages/react-grab/src/core/index.tsx
@@ -135,7 +135,7 @@ import {
 } from "../utils/freeze-animations.js";
 import { freezePseudoStates, unfreezePseudoStates } from "../utils/freeze-pseudo-states.js";
 import { freezeUpdates } from "../utils/freeze-updates.js";
-import { buildPrehitIndex, destroyPrehitIndex } from "../utils/prehit.js";
+import { buildSpatialIndex, destroySpatialIndex } from "../utils/spatial-index.js";
 import {
   loadComments,
   addCommentItem,
@@ -259,13 +259,13 @@ export const init = (rawOptions?: Options): ReactGrabAPI => {
         if (activated && !previousActivated) {
           freezePseudoStates(store.pointer.x, store.pointer.y);
           freezeGlobalAnimations();
-          buildPrehitIndex();
+          buildSpatialIndex();
           document.body.style.touchAction = "none";
           // iOS Safari auto-zooms on focused inputs with font-size < 16px,
           // which would disrupt the overlay positioning.
           unlockViewportZoom = lockViewportZoom();
         } else if (!activated && previousActivated) {
-          destroyPrehitIndex();
+          destroySpatialIndex();
           unfreezePseudoStates();
           unfreezeGlobalAnimations();
           document.body.style.touchAction = "";
@@ -2880,7 +2880,7 @@ export const init = (rawOptions?: Options): ReactGrabAPI => {
 
     onCleanup(() => {
       eventListenerManager.abort();
-      destroyPrehitIndex();
+      destroySpatialIndex();
       if (dragPreviewDebounceTimerId !== null) {
         window.clearTimeout(dragPreviewDebounceTimerId);
       }
diff --git a/packages/react-grab/src/utils/get-element-at-position.ts b/packages/react-grab/src/utils/get-element-at-position.ts
index cd0e26d87..972cc83f8 100644
--- a/packages/react-grab/src/utils/get-element-at-position.ts
+++ b/packages/react-grab/src/utils/get-element-at-position.ts
@@ -5,7 +5,7 @@ import {
   POINTER_EVENTS_RESUME_DEBOUNCE_MS,
 } from "../constants.js";
 import { suspendPointerEventsFreeze, resumePointerEventsFreeze } from "./freeze-pseudo-states.js";
-import { isPrehitIndexReady, queryPrehitIndex } from "./prehit.js";
+import { isSpatialIndexReady, querySpatialIndex } from "./spatial-index.js";
 
 interface PositionCache {
   clientX: number;
@@ -73,11 +73,11 @@ export const getElementAtPosition = (clientX: number, clientY: number): Element
     }
   }
 
-  if (isPrehitIndexReady()) {
-    const prehitResult = queryPrehitIndex(clientX, clientY);
-    if (prehitResult) {
-      cache = { clientX, clientY, element: prehitResult, timestamp: now };
-      return prehitResult;
+  if (isSpatialIndexReady()) {
+    const spatialResult = querySpatialIndex(clientX, clientY);
+    if (spatialResult) {
+      cache = { clientX, clientY, element: spatialResult, timestamp: now };
+      return spatialResult;
     }
   }
 
diff --git a/packages/react-grab/src/utils/prehit.ts b/packages/react-grab/src/utils/spatial-index.ts
similarity index 91%
rename from packages/react-grab/src/utils/prehit.ts
rename to packages/react-grab/src/utils/spatial-index.ts
index 9fb0ca431..f4bce44aa 100644
--- a/packages/react-grab/src/utils/prehit.ts
+++ b/packages/react-grab/src/utils/spatial-index.ts
@@ -1,5 +1,5 @@
 import { HilbertRTree } from "./hilbert-r-tree.js";
-import { PREHIT_ROOT_MARGIN_PX } from "../constants.js";
+import { SPATIAL_INDEX_ROOT_MARGIN_PX } from "../constants.js";
 import { isValidGrabbableElement } from "./is-valid-grabbable-element.js";
 
 interface IndexedElement {
@@ -15,7 +15,7 @@ interface PageRect {
   bottom: number;
 }
 
-interface PrehitIndex {
+interface SpatialIndexState {
   tree: HilbertRTree;
   elements: IndexedElement[];
 }
@@ -25,11 +25,11 @@ const SKIP_TAGS = new Set([
   "NOSCRIPT", "BR", "TEMPLATE", "SLOT",
 ]);
 
-let currentIndex: PrehitIndex | null = null;
+let currentIndex: SpatialIndexState | null = null;
 let pendingObserver: IntersectionObserver | null = null;
 
-export const buildPrehitIndex = (): void => {
-  destroyPrehitIndex();
+export const buildSpatialIndex = (): void => {
+  destroySpatialIndex();
 
   const treeOrderMap = new Map<Element, number>();
   let treeOrder = 0;
@@ -79,7 +79,7 @@ export const buildPrehitIndex = (): void => {
 
       currentIndex = { tree, elements: accumulatedElements };
     },
-    { rootMargin: `${PREHIT_ROOT_MARGIN_PX}px` },
+    { rootMargin: `${SPATIAL_INDEX_ROOT_MARGIN_PX}px` },
   );
 
   pendingObserver = observer;
@@ -138,7 +138,7 @@ const isVisibleAtPoint = (element: Element, clientX: number, clientY: number): b
   return true;
 };
 
-export const queryPrehitIndex = (clientX: number, clientY: number): Element | null => {
+export const querySpatialIndex = (clientX: number, clientY: number): Element | null => {
   if (!currentIndex) return null;
 
   const pageX = clientX + window.scrollX;
@@ -169,9 +169,9 @@ export const queryPrehitIndex = (clientX: number, clientY: number): Element | nu
   return bestElement?.element ?? null;
 };
 
-export const isPrehitIndexReady = (): boolean => currentIndex !== null;
+export const isSpatialIndexReady = (): boolean => currentIndex !== null;
 
-export const destroyPrehitIndex = (): void => {
+export const destroySpatialIndex = (): void => {
   if (pendingObserver) {
     pendingObserver.disconnect();
     pendingObserver = null;

From 296259e021ca16b52576be3848a688dca4bc51b0 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Thu, 9 Apr 2026 22:37:23 -0700
Subject: [PATCH 35/45] refactor: rename spatial-index to
 element-at-point-index

spatial-index.ts -> element-at-point-index.ts
buildSpatialIndex -> buildElementAtPointIndex
querySpatialIndex -> queryElementAtPointIndex
isSpatialIndexReady -> isElementAtPointIndexReady
destroySpatialIndex -> destroyElementAtPointIndex
SPATIAL_INDEX_ROOT_MARGIN_PX -> ELEMENT_AT_POINT_INDEX_ROOT_MARGIN_PX
---
 packages/react-grab/src/constants.ts           |  2 +-
 packages/react-grab/src/core/index.tsx         |  8 ++++----
 ...tial-index.ts => element-at-point-index.ts} | 18 +++++++++---------
 .../src/utils/get-element-at-position.ts       |  6 +++---
 4 files changed, 17 insertions(+), 17 deletions(-)
 rename packages/react-grab/src/utils/{spatial-index.ts => element-at-point-index.ts} (90%)

diff --git a/packages/react-grab/src/constants.ts b/packages/react-grab/src/constants.ts
index 6837d9dc0..82f545005 100644
--- a/packages/react-grab/src/constants.ts
+++ b/packages/react-grab/src/constants.ts
@@ -130,7 +130,7 @@ export const ELEMENT_POSITION_THROTTLE_MS = 16;
 export const POINTER_EVENTS_RESUME_DEBOUNCE_MS = 100;
 export const VISIBILITY_CACHE_TTL_MS = 50;
 
-export const SPATIAL_INDEX_ROOT_MARGIN_PX = 10_000;
+export const ELEMENT_AT_POINT_INDEX_ROOT_MARGIN_PX = 10_000;
 
 export const ZOOM_DETECTION_THRESHOLD = 0.01;
 
diff --git a/packages/react-grab/src/core/index.tsx b/packages/react-grab/src/core/index.tsx
index e8bd1f74e..7e113ad58 100644
--- a/packages/react-grab/src/core/index.tsx
+++ b/packages/react-grab/src/core/index.tsx
@@ -135,7 +135,7 @@ import {
 } from "../utils/freeze-animations.js";
 import { freezePseudoStates, unfreezePseudoStates } from "../utils/freeze-pseudo-states.js";
 import { freezeUpdates } from "../utils/freeze-updates.js";
-import { buildSpatialIndex, destroySpatialIndex } from "../utils/spatial-index.js";
+import { buildElementAtPointIndex, destroyElementAtPointIndex } from "../utils/element-at-point-index.js";
 import {
   loadComments,
   addCommentItem,
@@ -259,13 +259,13 @@ export const init = (rawOptions?: Options): ReactGrabAPI => {
         if (activated && !previousActivated) {
           freezePseudoStates(store.pointer.x, store.pointer.y);
           freezeGlobalAnimations();
-          buildSpatialIndex();
+          buildElementAtPointIndex();
           document.body.style.touchAction = "none";
           // iOS Safari auto-zooms on focused inputs with font-size < 16px,
           // which would disrupt the overlay positioning.
           unlockViewportZoom = lockViewportZoom();
         } else if (!activated && previousActivated) {
-          destroySpatialIndex();
+          destroyElementAtPointIndex();
           unfreezePseudoStates();
           unfreezeGlobalAnimations();
           document.body.style.touchAction = "";
@@ -2880,7 +2880,7 @@ export const init = (rawOptions?: Options): ReactGrabAPI => {
 
     onCleanup(() => {
       eventListenerManager.abort();
-      destroySpatialIndex();
+      destroyElementAtPointIndex();
       if (dragPreviewDebounceTimerId !== null) {
         window.clearTimeout(dragPreviewDebounceTimerId);
       }
diff --git a/packages/react-grab/src/utils/spatial-index.ts b/packages/react-grab/src/utils/element-at-point-index.ts
similarity index 90%
rename from packages/react-grab/src/utils/spatial-index.ts
rename to packages/react-grab/src/utils/element-at-point-index.ts
index f4bce44aa..f3c5122bc 100644
--- a/packages/react-grab/src/utils/spatial-index.ts
+++ b/packages/react-grab/src/utils/element-at-point-index.ts
@@ -1,5 +1,5 @@
 import { HilbertRTree } from "./hilbert-r-tree.js";
-import { SPATIAL_INDEX_ROOT_MARGIN_PX } from "../constants.js";
+import { ELEMENT_AT_POINT_INDEX_ROOT_MARGIN_PX } from "../constants.js";
 import { isValidGrabbableElement } from "./is-valid-grabbable-element.js";
 
 interface IndexedElement {
@@ -15,7 +15,7 @@ interface PageRect {
   bottom: number;
 }
 
-interface SpatialIndexState {
+interface ElementAtPointIndexState {
   tree: HilbertRTree;
   elements: IndexedElement[];
 }
@@ -25,11 +25,11 @@ const SKIP_TAGS = new Set([
   "NOSCRIPT", "BR", "TEMPLATE", "SLOT",
 ]);
 
-let currentIndex: SpatialIndexState | null = null;
+let currentIndex: ElementAtPointIndexState | null = null;
 let pendingObserver: IntersectionObserver | null = null;
 
-export const buildSpatialIndex = (): void => {
-  destroySpatialIndex();
+export const buildElementAtPointIndex = (): void => {
+  destroyElementAtPointIndex();
 
   const treeOrderMap = new Map<Element, number>();
   let treeOrder = 0;
@@ -79,7 +79,7 @@ export const buildSpatialIndex = (): void => {
 
       currentIndex = { tree, elements: accumulatedElements };
     },
-    { rootMargin: `${SPATIAL_INDEX_ROOT_MARGIN_PX}px` },
+    { rootMargin: `${ELEMENT_AT_POINT_INDEX_ROOT_MARGIN_PX}px` },
   );
 
   pendingObserver = observer;
@@ -138,7 +138,7 @@ const isVisibleAtPoint = (element: Element, clientX: number, clientY: number): b
   return true;
 };
 
-export const querySpatialIndex = (clientX: number, clientY: number): Element | null => {
+export const queryElementAtPointIndex = (clientX: number, clientY: number): Element | null => {
   if (!currentIndex) return null;
 
   const pageX = clientX + window.scrollX;
@@ -169,9 +169,9 @@ export const querySpatialIndex = (clientX: number, clientY: number): Element | n
   return bestElement?.element ?? null;
 };
 
-export const isSpatialIndexReady = (): boolean => currentIndex !== null;
+export const isElementAtPointIndexReady = (): boolean => currentIndex !== null;
 
-export const destroySpatialIndex = (): void => {
+export const destroyElementAtPointIndex = (): void => {
   if (pendingObserver) {
     pendingObserver.disconnect();
     pendingObserver = null;
diff --git a/packages/react-grab/src/utils/get-element-at-position.ts b/packages/react-grab/src/utils/get-element-at-position.ts
index 972cc83f8..00f549f74 100644
--- a/packages/react-grab/src/utils/get-element-at-position.ts
+++ b/packages/react-grab/src/utils/get-element-at-position.ts
@@ -5,7 +5,7 @@ import {
   POINTER_EVENTS_RESUME_DEBOUNCE_MS,
 } from "../constants.js";
 import { suspendPointerEventsFreeze, resumePointerEventsFreeze } from "./freeze-pseudo-states.js";
-import { isSpatialIndexReady, querySpatialIndex } from "./spatial-index.js";
+import { isElementAtPointIndexReady, queryElementAtPointIndex } from "./element-at-point-index.js";
 
 interface PositionCache {
   clientX: number;
@@ -73,8 +73,8 @@ export const getElementAtPosition = (clientX: number, clientY: number): Element
     }
   }
 
-  if (isSpatialIndexReady()) {
-    const spatialResult = querySpatialIndex(clientX, clientY);
+  if (isElementAtPointIndexReady()) {
+    const spatialResult = queryElementAtPointIndex(clientX, clientY);
     if (spatialResult) {
       cache = { clientX, clientY, element: spatialResult, timestamp: now };
       return spatialResult;

From 3038d97ad2d56522066cdec437ac999b9e60fd3f Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Thu, 9 Apr 2026 22:41:55 -0700
Subject: [PATCH 36/45] feat: use stacking order for z-index-aware element
 selection

Replace the smallest-area heuristic with stacking order comparison
for prehit queries. A modal button (z-index: 9999) now correctly
wins over a paragraph behind it, even if the paragraph is smaller.

Adds compare-stacking-order.ts which determines visual ordering by
walking ancestor chains, comparing z-index within stacking contexts,
and falling back to DOM sibling order.

The IndexedElement no longer stores area or treeOrder since selection
is now based on visual stacking, not geometric size.
---
 .../src/utils/compare-stacking-order.ts       | 81 +++++++++++++++++++
 .../src/utils/element-at-point-index.ts       | 33 +++-----
 2 files changed, 91 insertions(+), 23 deletions(-)
 create mode 100644 packages/react-grab/src/utils/compare-stacking-order.ts

diff --git a/packages/react-grab/src/utils/compare-stacking-order.ts b/packages/react-grab/src/utils/compare-stacking-order.ts
new file mode 100644
index 000000000..e767723c0
--- /dev/null
+++ b/packages/react-grab/src/utils/compare-stacking-order.ts
@@ -0,0 +1,81 @@
+const STACKING_PROPS = /\b(?:position|zIndex|opacity|transform|mixBlendMode|filter|isolation)\b/;
+
+const getParentElement = (node: Element): Element | null => {
+  const parentNode = node.parentNode;
+  const shadowHost = parentNode && "host" in parentNode ? (parentNode as ShadowRoot).host : null;
+  return shadowHost ?? node.parentElement;
+};
+
+const getAncestorChain = (node: Element): Element[] => {
+  const ancestors: Element[] = [];
+  let current: Element | null = node;
+  while (current) {
+    ancestors.push(current);
+    current = getParentElement(current);
+  }
+  return ancestors;
+};
+
+const isFlexItem = (node: Element): boolean => {
+  const parentElement = getParentElement(node);
+  if (!parentElement) return false;
+  const display = getComputedStyle(parentElement).display;
+  return display === "flex" || display === "inline-flex";
+};
+
+const createsStackingContext = (node: Element): boolean => {
+  const style = getComputedStyle(node);
+  if (style.position === "fixed") return true;
+  if ((style.zIndex !== "auto" && style.position !== "static") || isFlexItem(node)) return true;
+  if (+style.opacity < 1) return true;
+  if (style.transform !== "none") return true;
+  if ("mixBlendMode" in style && style.mixBlendMode !== "normal") return true;
+  if (style.filter !== "none") return true;
+  if ("isolation" in style && style.getPropertyValue("isolation") === "isolate") return true;
+  if (STACKING_PROPS.test(style.willChange)) return true;
+  return false;
+};
+
+const findNearestStackingContext = (ancestors: Element[]): Element | null => {
+  let ancestorIndex = ancestors.length;
+  while (ancestorIndex--) {
+    if (createsStackingContext(ancestors[ancestorIndex])) return ancestors[ancestorIndex];
+  }
+  return null;
+};
+
+const getZIndex = (node: Element | null): number =>
+  (node && Number(getComputedStyle(node).zIndex)) || 0;
+
+export const compareStackingOrder = (elementA: Element, elementB: Element): number => {
+  if (elementA === elementB) return 0;
+
+  const ancestorsA = getAncestorChain(elementA);
+  const ancestorsB = getAncestorChain(elementB);
+
+  let commonAncestor: Element | undefined;
+
+  while (ancestorsA.at(-1) === ancestorsB.at(-1)) {
+    commonAncestor = ancestorsA.pop()!;
+    ancestorsB.pop();
+  }
+
+  const zIndexA = getZIndex(findNearestStackingContext(ancestorsA));
+  const zIndexB = getZIndex(findNearestStackingContext(ancestorsB));
+
+  if (zIndexA === zIndexB) {
+    if (!commonAncestor) return 0;
+    const children = commonAncestor.childNodes;
+    const furthestAncestorA = ancestorsA.at(-1);
+    const furthestAncestorB = ancestorsB.at(-1);
+
+    let childIndex = children.length;
+    while (childIndex--) {
+      const child = children[childIndex];
+      if (child === furthestAncestorA) return 1;
+      if (child === furthestAncestorB) return -1;
+    }
+  }
+
+  return Math.sign(zIndexA - zIndexB);
+};
diff --git a/packages/react-grab/src/utils/element-at-point-index.ts b/packages/react-grab/src/utils/element-at-point-index.ts
index f3c5122bc..60aa89819 100644
--- a/packages/react-grab/src/utils/element-at-point-index.ts
+++ b/packages/react-grab/src/utils/element-at-point-index.ts
@@ -1,11 +1,10 @@
 import { HilbertRTree } from "./hilbert-r-tree.js";
 import { ELEMENT_AT_POINT_INDEX_ROOT_MARGIN_PX } from "../constants.js";
 import { isValidGrabbableElement } from "./is-valid-grabbable-element.js";
+import { compareStackingOrder } from "./compare-stacking-order.js";
 
 interface IndexedElement {
   element: Element;
-  area: number;
-  treeOrder: number;
 }
 
 interface PageRect {
@@ -31,8 +30,6 @@ let pendingObserver: IntersectionObserver | null = null;
 export const buildElementAtPointIndex = (): void => {
   destroyElementAtPointIndex();
 
-  const treeOrderMap = new Map<Element, number>();
-  let treeOrder = 0;
   let didObserveAnyElement = false;
 
   const accumulatedElements: IndexedElement[] = [];
@@ -51,14 +48,8 @@ export const buildElementAtPointIndex = (): void => {
         if (boundingRect.width === 0 || boundingRect.height === 0) continue;
         if (!isValidGrabbableElement(targetElement)) continue;
 
-        const elementArea = targetElement.clientWidth * targetElement.clientHeight
-          || boundingRect.width * boundingRect.height;
-        if (elementArea === 0) continue;
-
         accumulatedElements.push({
           element: targetElement,
-          area: elementArea,
-          treeOrder: treeOrderMap.get(targetElement) ?? 0,
         });
 
         accumulatedRects.push({
@@ -98,7 +89,6 @@ export const buildElementAtPointIndex = (): void => {
   while (walker.nextNode()) {
     const element = walker.currentNode as HTMLElement;
     if (element.offsetWidth === 0 && element.offsetHeight === 0) continue;
-    treeOrderMap.set(element, treeOrder++);
     observer.observe(element);
     didObserveAnyElement = true;
   }
@@ -147,26 +137,23 @@ export const queryElementAtPointIndex = (clientX: number, clientY: number): Elem
   const hitIndices = currentIndex.tree.search(pageX, pageY, pageX, pageY);
   if (hitIndices.length === 0) return null;
 
-  let bestElement: IndexedElement | null = null;
+  const visibleCandidates: Element[] = [];
 
   for (const hitIndex of hitIndices) {
     const candidate = currentIndex.elements[hitIndex];
     if (!candidate.element.isConnected) continue;
     if (!isVisibleAtPoint(candidate.element, clientX, clientY)) continue;
+    visibleCandidates.push(candidate.element);
+  }
 
-    if (!bestElement) {
-      bestElement = candidate;
-      continue;
-    }
+  if (visibleCandidates.length === 0) return null;
+  if (visibleCandidates.length === 1) return visibleCandidates[0];
 
-    if (candidate.area < bestElement.area) {
-      bestElement = candidate;
-    } else if (candidate.area === bestElement.area && candidate.treeOrder > bestElement.treeOrder) {
-      bestElement = candidate;
-    }
-  }
+  visibleCandidates.sort((elementA, elementB) =>
+    compareStackingOrder(elementB, elementA),
+  );
 
-  return bestElement?.element ?? null;
+  return visibleCandidates[0];
 };
 
 export const isElementAtPointIndexReady = (): boolean => currentIndex !== null;

From 83d79a3c7d2b8fe036ededdc75cfc1e70bf738e0 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Fri, 10 Apr 2026 01:29:18 -0700
Subject: [PATCH 37/45] fix: offscreen pointer, flex stacking context,
 consistent selection

- freezePseudoStates: check cursor is within viewport bounds before
  using elementFromPoint. store.pointer starts at -1000 (offscreen);
  without the bounds check, elementFromPoint returns null and the
  querySelectorAll(":hover") fallback never runs.

- compareStackingOrder: fix operator grouping for flex items. Per CSS
  spec, flex items only create a stacking context when z-index is not
  auto. Was: (zIndex !== auto && position !== static) || isFlexItem.
  Now: zIndex !== auto && (position !== static || isFlexItem).

- getElementAtPosition fallback: take the first valid element from
  elementsFromPoint (already in paint/z-order) instead of the smallest
  by area. Consistent with prehit's stacking-order-based selection.
---
 .../react-grab/src/utils/compare-stacking-order.ts     |  2 +-
 packages/react-grab/src/utils/freeze-pseudo-states.ts  |  5 ++++-
 .../react-grab/src/utils/get-element-at-position.ts    | 10 +++-------
 3 files changed, 8 insertions(+), 9 deletions(-)

diff --git a/packages/react-grab/src/utils/compare-stacking-order.ts b/packages/react-grab/src/utils/compare-stacking-order.ts
index e767723c0..d7792695c 100644
--- a/packages/react-grab/src/utils/compare-stacking-order.ts
+++ b/packages/react-grab/src/utils/compare-stacking-order.ts
@@ -26,7 +26,7 @@ const isFlexItem = (node: Element): boolean => {
 const createsStackingContext = (node: Element): boolean => {
   const style = getComputedStyle(node);
   if (style.position === "fixed") return true;
-  if ((style.zIndex !== "auto" && style.position !== "static") || isFlexItem(node)) return true;
+  if (style.zIndex !== "auto" && (style.position !== "static" || isFlexItem(node))) return true;
   if (+style.opacity < 1) return true;
   if (style.transform !== "none") return true;
   if ("mixBlendMode" in style && style.mixBlendMode !== "normal") return true;
diff --git a/packages/react-grab/src/utils/freeze-pseudo-states.ts b/packages/react-grab/src/utils/freeze-pseudo-states.ts
index 4163a5a14..56190f942 100644
--- a/packages/react-grab/src/utils/freeze-pseudo-states.ts
+++ b/packages/react-grab/src/utils/freeze-pseudo-states.ts
@@ -182,7 +182,10 @@ export const freezePseudoStates = (cursorX?: number, cursorY?: number): void =>
   }
 
   const hoverStates: FrozenPseudoState[] = [];
-  const hoveredElements = cursorX !== undefined && cursorY !== undefined
+  const isCursorInViewport = cursorX !== undefined && cursorY !== undefined
+    && cursorX >= 0 && cursorY >= 0
+    && cursorX <= window.innerWidth && cursorY <= window.innerHeight;
+  const hoveredElements = isCursorInViewport
     ? collectHoveredElements(cursorX, cursorY)
     : Array.from(document.querySelectorAll(":hover")).filter(
         (element): element is HTMLElement => element instanceof HTMLElement,
diff --git a/packages/react-grab/src/utils/get-element-at-position.ts b/packages/react-grab/src/utils/get-element-at-position.ts
index 00f549f74..4cf0e298c 100644
--- a/packages/react-grab/src/utils/get-element-at-position.ts
+++ b/packages/react-grab/src/utils/get-element-at-position.ts
@@ -86,16 +86,12 @@ export const getElementAtPosition = (clientX: number, clientY: number): Element
 
   const elementsAtPoint = document.elementsFromPoint(clientX, clientY);
   let result: Element | null = null;
-  let smallestArea = Infinity;
 
   for (const candidateElement of elementsAtPoint) {
     if (!isValidGrabbableElement(candidateElement)) continue;
-    const area = getElementArea(candidateElement);
-    if (area === 0) continue;
-    if (area < smallestArea) {
-      smallestArea = area;
-      result = candidateElement;
-    }
+    if (getElementArea(candidateElement) === 0) continue;
+    result = candidateElement;
+    break;
   }
 
   scheduleResume();

From f84d8e84663d0aa3fe785839a2eb4f5c378f1a5b Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Fri, 10 Apr 2026 01:48:30 -0700
Subject: [PATCH 38/45] fix: viewport boundary off-by-one and revert animation
 caching

- freezePseudoStates: use < instead of <= for viewport bounds check.
  elementFromPoint returns null at exactly innerWidth/innerHeight
  since viewport coordinates are 0-indexed.

- Revert animation caching optimization in freezeGlobalAnimations.
  Capturing animations at freeze time missed animations created
  during the freeze (e.g., React adding DOM with CSS animations).
  The CSS rule pauses them, but finish() on unfreeze only ran on the
  cached list, causing visual jumps for missed animations. Restoring
  document.getAnimations() on unfreeze catches all animations
  including those created mid-session. Correctness over micro-opt.
---
 .../react-grab/src/utils/freeze-animations.ts | 32 +++++++++----------
 .../src/utils/freeze-pseudo-states.ts         |  2 +-
 2 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/packages/react-grab/src/utils/freeze-animations.ts b/packages/react-grab/src/utils/freeze-animations.ts
index d562f67be..d141dc60b 100644
--- a/packages/react-grab/src/utils/freeze-animations.ts
+++ b/packages/react-grab/src/utils/freeze-animations.ts
@@ -30,7 +30,6 @@ let globalFrozenSvgElements: SVGSVGElement[] = [];
 // a depth counter per element and only unpause when all layers are removed.
 const svgFreezeDepthMap = new Map<SVGSVGElement, number>();
 let frozenWaapiAnimations: Animation[] = [];
-let globalFrozenAnimations: Animation[] = [];
 
 const ensureStylesInjected = (): void => {
   if (styleElement) return;
@@ -180,19 +179,6 @@ export const freezeGlobalAnimations = (): void => {
     Array.from(document.querySelectorAll(SVG_ROOT_SELECTOR)),
   );
   pauseSvgAnimations(globalFrozenSvgElements);
-
-  globalFrozenAnimations = [];
-  for (const animation of document.getAnimations()) {
-    if (animation.effect instanceof KeyframeEffect) {
-      const target = animation.effect.target;
-      if (target instanceof Element) {
-        const rootNode = target.getRootNode();
-        if (rootNode instanceof ShadowRoot) continue;
-      }
-    }
-    globalFrozenAnimations.push(animation);
-  }
-
   freezeGsap();
 };
 
@@ -210,8 +196,22 @@ export const unfreezeGlobalAnimations = (): void => {
 }
 `;
 
-  finishAnimations(globalFrozenAnimations);
-  globalFrozenAnimations = [];
+  // Animations inside shadow roots are skipped because the freeze CSS only
+  // affects main-document elements (shadow DOM provides style encapsulation),
+  // so calling finish() on animations the freeze never paused would break
+  // react-grab's own toolbar and label animations.
+  // @see https://github.com/aidenybai/react-grab/issues/163
+  const animationsToFinish: Animation[] = [];
+  for (const animation of document.getAnimations()) {
+    if (animation.effect instanceof KeyframeEffect) {
+      const target = animation.effect.target;
+      if (target instanceof Element && target.getRootNode() instanceof ShadowRoot) {
+        continue;
+      }
+    }
+    animationsToFinish.push(animation);
+  }
+  finishAnimations(animationsToFinish);
 
   globalAnimationStyleElement.remove();
   globalAnimationStyleElement = null;
diff --git a/packages/react-grab/src/utils/freeze-pseudo-states.ts b/packages/react-grab/src/utils/freeze-pseudo-states.ts
index 56190f942..6543a8461 100644
--- a/packages/react-grab/src/utils/freeze-pseudo-states.ts
+++ b/packages/react-grab/src/utils/freeze-pseudo-states.ts
@@ -184,7 +184,7 @@ export const freezePseudoStates = (cursorX?: number, cursorY?: number): void =>
   const hoverStates: FrozenPseudoState[] = [];
   const isCursorInViewport = cursorX !== undefined && cursorY !== undefined
     && cursorX >= 0 && cursorY >= 0
-    && cursorX <= window.innerWidth && cursorY <= window.innerHeight;
+    && cursorX < window.innerWidth && cursorY < window.innerHeight;
   const hoveredElements = isCursorInViewport
     ? collectHoveredElements(cursorX, cursorY)
     : Array.from(document.querySelectorAll(":hover")).filter(

From abc7d38a4745eca99ac934beacec6789008ef51a Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Fri, 10 Apr 2026 01:59:18 -0700
Subject: [PATCH 39/45] fix: hilbert function reads modified levelC in levelD
 computation

The >> 8 iteration read levelC/levelD (post-modification) instead of
invertedOr/maskedAnd (saved pre-modification values from the >> 4
iteration). This matches the original flatbush which uses lowercase
c/d (saved copies) in the >> 8 step, not uppercase C/D (current).

Incorrect Hilbert values degraded R-tree spatial locality but didn't
break query correctness since the tree structure is still valid.
---
 packages/react-grab/src/utils/hilbert-r-tree.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/react-grab/src/utils/hilbert-r-tree.ts b/packages/react-grab/src/utils/hilbert-r-tree.ts
index 992743b59..a0602d1b6 100644
--- a/packages/react-grab/src/utils/hilbert-r-tree.ts
+++ b/packages/react-grab/src/utils/hilbert-r-tree.ts
@@ -107,8 +107,8 @@ const hilbert = (coordX: number, coordY: number): number => {
   levelD ^= ((invertedXor & (invertedOr >> 4)) ^ ((xorXY ^ invertedXor) & (maskedAnd >> 4)));
 
   xorXY = levelA; invertedXor = levelB;
-  levelC ^= ((xorXY & (levelC >> 8)) ^ (invertedXor & (levelD >> 8)));
-  levelD ^= ((invertedXor & (levelC >> 8)) ^ ((xorXY ^ invertedXor) & (levelD >> 8)));
+  levelC ^= ((xorXY & (invertedOr >> 8)) ^ (invertedXor & (maskedAnd >> 8)));
+  levelD ^= ((invertedXor & (invertedOr >> 8)) ^ ((xorXY ^ invertedXor) & (maskedAnd >> 8)));
 
   xorXY = levelC ^ (levelC >> 1);
   invertedXor = levelD ^ (levelD >> 1);

From 05f9cafadb4fcb935807ba1d4001281b78085485 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Fri, 10 Apr 2026 02:09:19 -0700
Subject: [PATCH 40/45] fix: handle sticky position and grid items in stacking
 context detection

- Add position:sticky to unconditional stacking context check (per
  CSS spec, sticky creates a stacking context like fixed does).
- Rename isFlexItem to isFlexOrGridItem and add grid/inline-grid
  parent display checks. Grid items with non-auto z-index create
  stacking contexts just like flex items do.
---
 packages/react-grab/src/utils/compare-stacking-order.ts | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/react-grab/src/utils/compare-stacking-order.ts b/packages/react-grab/src/utils/compare-stacking-order.ts
index d7792695c..fc2bf0295 100644
--- a/packages/react-grab/src/utils/compare-stacking-order.ts
+++ b/packages/react-grab/src/utils/compare-stacking-order.ts
@@ -16,17 +16,17 @@ const getAncestorChain = (node: Element): Element[] => {
   return ancestors;
 };
 
-const isFlexItem = (node: Element): boolean => {
+const isFlexOrGridItem = (node: Element): boolean => {
   const parentElement = getParentElement(node);
   if (!parentElement) return false;
   const display = getComputedStyle(parentElement).display;
-  return display === "flex" || display === "inline-flex";
+  return display === "flex" || display === "inline-flex" || display === "grid" || display === "inline-grid";
 };
 
 const createsStackingContext = (node: Element): boolean => {
   const style = getComputedStyle(node);
-  if (style.position === "fixed") return true;
-  if (style.zIndex !== "auto" && (style.position !== "static" || isFlexItem(node))) return true;
+  if (style.position === "fixed" || style.position === "sticky") return true;
+  if (style.zIndex !== "auto" && (style.position !== "static" || isFlexOrGridItem(node))) return true;
   if (+style.opacity < 1) return true;
   if (style.transform !== "none") return true;
   if ("mixBlendMode" in style && style.mixBlendMode !== "normal") return true;

From b74155c04c7f6021f65829d94c23de8fca07e17c Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Fri, 10 Apr 2026 03:29:23 -0700
Subject: [PATCH 41/45] fix: validate prehit result and snapshot elements array

- Re-validate prehit result with isValidGrabbableElement and
  getElementArea before returning. Elements indexed at activation
  could theoretically change state during the session.

- Restore [...accumulatedElements] snapshot when assigning to
  currentIndex. Without this, the elements array is shared between
  the IO accumulation buffer and the current index. Subsequent IO
  batches would mutate the live index's elements array, causing
  index/element count mismatches during concurrent queries.
---
 packages/react-grab/src/utils/element-at-point-index.ts  | 2 +-
 packages/react-grab/src/utils/get-element-at-position.ts | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/react-grab/src/utils/element-at-point-index.ts b/packages/react-grab/src/utils/element-at-point-index.ts
index 60aa89819..99c34f39f 100644
--- a/packages/react-grab/src/utils/element-at-point-index.ts
+++ b/packages/react-grab/src/utils/element-at-point-index.ts
@@ -68,7 +68,7 @@ export const buildElementAtPointIndex = (): void => {
       }
       tree.finish();
 
-      currentIndex = { tree, elements: accumulatedElements };
+      currentIndex = { tree, elements: [...accumulatedElements] };
     },
     { rootMargin: `${ELEMENT_AT_POINT_INDEX_ROOT_MARGIN_PX}px` },
   );
diff --git a/packages/react-grab/src/utils/get-element-at-position.ts b/packages/react-grab/src/utils/get-element-at-position.ts
index 4cf0e298c..695ac20cd 100644
--- a/packages/react-grab/src/utils/get-element-at-position.ts
+++ b/packages/react-grab/src/utils/get-element-at-position.ts
@@ -75,7 +75,7 @@ export const getElementAtPosition = (clientX: number, clientY: number): Element
 
   if (isElementAtPointIndexReady()) {
     const spatialResult = queryElementAtPointIndex(clientX, clientY);
-    if (spatialResult) {
+    if (spatialResult && isValidGrabbableElement(spatialResult) && getElementArea(spatialResult) > 0) {
       cache = { clientX, clientY, element: spatialResult, timestamp: now };
       return spatialResult;
     }

From a34a57a5d95b556ecf093e69e505c899c85a5aee Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Fri, 10 Apr 2026 03:40:13 -0700
Subject: [PATCH 42/45] fix: use CSS property names in will-change stacking
 context regex

---
 packages/react-grab/src/utils/compare-stacking-order.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react-grab/src/utils/compare-stacking-order.ts b/packages/react-grab/src/utils/compare-stacking-order.ts
index fc2bf0295..12d73309b 100644
--- a/packages/react-grab/src/utils/compare-stacking-order.ts
+++ b/packages/react-grab/src/utils/compare-stacking-order.ts
@@ -1,4 +1,4 @@
-const STACKING_PROPS = /\b(?:position|zIndex|opacity|transform|mixBlendMode|filter|isolation)\b/;
+const STACKING_PROPS = /\b(?:position|z-index|opacity|transform|mix-blend-mode|filter|isolation)\b/;
 
 const getParentElement = (node: Element): Element | null => {
   const parentNode = node.parentNode;

From de5ffe672487ed0bb76d7be8801e935d6fdf4b41 Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Fri, 10 Apr 2026 04:01:37 -0700
Subject: [PATCH 43/45] fix: skip position:fixed elements in spatial index

---
 packages/react-grab/src/utils/element-at-point-index.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/react-grab/src/utils/element-at-point-index.ts b/packages/react-grab/src/utils/element-at-point-index.ts
index 99c34f39f..34ce15e09 100644
--- a/packages/react-grab/src/utils/element-at-point-index.ts
+++ b/packages/react-grab/src/utils/element-at-point-index.ts
@@ -47,6 +47,7 @@ export const buildElementAtPointIndex = (): void => {
         const boundingRect = entry.boundingClientRect;
         if (boundingRect.width === 0 || boundingRect.height === 0) continue;
         if (!isValidGrabbableElement(targetElement)) continue;
+        if (getComputedStyle(targetElement).position === "fixed") continue;
 
         accumulatedElements.push({
           element: targetElement,

From ff4875c348761b4e5a99cfc9d8d098cbf761bf2a Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Fri, 10 Apr 2026 17:34:29 -0700
Subject: [PATCH 44/45] fix: restore smallest-area fallback and exclude
 decorative overlays from index

The bugbot-driven change from smallest-area to first-valid (topmost)
in the fallback path reintroduced the original "stuck on decorative
overlay" bug. Decorative overlay divs (positioned, empty, transparent)
are topmost in elementsFromPoint results, so taking the first valid
element returns the overlay instead of the content underneath.

Fallback path: restored smallest-area selection. elementsFromPoint
returns in z-order; smallest-area naturally skips large overlays in
favor of specific content elements. Handles modals correctly because
modal content elements are smaller than background content at the
same point.

Prehit path: exclude positioned elements with no children and no text
from the R-tree. These are decorative hover-effect divs that should
never be selection targets. The stacking-order sort then operates only
on meaningful content elements.
---
 .../react-grab/src/utils/element-at-point-index.ts     |  8 +++++++-
 .../react-grab/src/utils/get-element-at-position.ts    | 10 +++++++---
 2 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/packages/react-grab/src/utils/element-at-point-index.ts b/packages/react-grab/src/utils/element-at-point-index.ts
index 34ce15e09..64f4095cc 100644
--- a/packages/react-grab/src/utils/element-at-point-index.ts
+++ b/packages/react-grab/src/utils/element-at-point-index.ts
@@ -47,7 +47,13 @@ export const buildElementAtPointIndex = (): void => {
         const boundingRect = entry.boundingClientRect;
         if (boundingRect.width === 0 || boundingRect.height === 0) continue;
         if (!isValidGrabbableElement(targetElement)) continue;
-        if (getComputedStyle(targetElement).position === "fixed") continue;
+        const computedPosition = getComputedStyle(targetElement).position;
+        if (computedPosition === "fixed") continue;
+        if (
+          (computedPosition === "absolute" || computedPosition === "sticky") &&
+          targetElement.childElementCount === 0 &&
+          (targetElement.textContent?.trim().length ?? 0) === 0
+        ) continue;
 
         accumulatedElements.push({
           element: targetElement,
diff --git a/packages/react-grab/src/utils/get-element-at-position.ts b/packages/react-grab/src/utils/get-element-at-position.ts
index 695ac20cd..510212e11 100644
--- a/packages/react-grab/src/utils/get-element-at-position.ts
+++ b/packages/react-grab/src/utils/get-element-at-position.ts
@@ -86,12 +86,16 @@ export const getElementAtPosition = (clientX: number, clientY: number): Element
 
   const elementsAtPoint = document.elementsFromPoint(clientX, clientY);
   let result: Element | null = null;
+  let smallestArea = Infinity;
 
   for (const candidateElement of elementsAtPoint) {
     if (!isValidGrabbableElement(candidateElement)) continue;
-    if (getElementArea(candidateElement) === 0) continue;
-    result = candidateElement;
-    break;
+    const area = getElementArea(candidateElement);
+    if (area === 0) continue;
+    if (area < smallestArea) {
+      smallestArea = area;
+      result = candidateElement;
+    }
   }
 
   scheduleResume();

From eb5d3cede1100cd639741aa6bb443757b4e7b9cc Mon Sep 17 00:00:00 2001
From: Aiden Bai <aiden.bai05@gmail.com>
Date: Fri, 10 Apr 2026 19:50:05 -0700
Subject: [PATCH 45/45] perf: cache fixed element rects and clip state, add
 stacking context coverage

- Cache fixed element viewport rects and z-indexes at build time to
  eliminate getBoundingClientRect and compareStackingOrder calls from
  the hot query path
- Add WeakMap clip state cache for isVisibleAtPoint to avoid repeated
  getComputedStyle calls on shared ancestors
- Handle nullable R-tree for fixed-only pages (no regular elements)
- Recognize contain:paint/strict/content, backdrop-filter, perspective,
  and clip-path as stacking context creators in compareStackingOrder
- Invalidate position cache when cached element is disconnected
- Extract isDecorativeOverlay to shared utility, exclude replaced
  elements (img, video, canvas, svg, etc.)
- Remove duplicated viewport coverage check in isFullViewportOverlay
- Combine duplicate freeze-pseudo-states imports in primitives.ts
- Add 57 element detection e2e tests covering overflow clipping, CSS
  containment, stacking order, inline elements, decorative overlays,
  fixed position, transforms, and dynamic DOM changes
---
 apps/e2e-app/src/App.tsx                      | 248 +++++
 .../react-grab/e2e/element-detection.spec.ts  | 939 ++++++++++++++++++
 packages/react-grab/package.json              |   2 +-
 packages/react-grab/src/core/index.tsx        |   8 +-
 packages/react-grab/src/core/store.ts         |   7 +-
 packages/react-grab/src/primitives.ts         |   3 +-
 .../src/utils/compare-stacking-order.ts       |  42 +-
 .../src/utils/element-at-point-index.ts       | 177 +++-
 .../src/utils/freeze-pseudo-states.ts         |  10 +-
 .../src/utils/get-element-at-position.ts      |  11 +-
 .../react-grab/src/utils/hilbert-r-tree.ts    |  97 +-
 .../src/utils/is-decorative-overlay.ts        |  18 +
 .../src/utils/is-valid-grabbable-element.ts   |  16 +-
 13 files changed, 1449 insertions(+), 129 deletions(-)
 create mode 100644 packages/react-grab/e2e/element-detection.spec.ts
 create mode 100644 packages/react-grab/src/utils/is-decorative-overlay.ts

diff --git a/apps/e2e-app/src/App.tsx b/apps/e2e-app/src/App.tsx
index 95200cc2a..b5a37932c 100644
--- a/apps/e2e-app/src/App.tsx
+++ b/apps/e2e-app/src/App.tsx
@@ -585,6 +585,242 @@ const PointerUpModalSection = () => {
   );
 };
 
+const OverflowClippingSection = () => {
+  return (
+    <section className="border rounded-lg p-4" data-testid="overflow-clipping-section">
+      <h2 className="text-lg font-bold mb-4">Overflow Clipping</h2>
+      <div className="space-y-4">
+        <div
+          className="overflow-hidden w-40 h-20 border-2 border-red-400 relative"
+          data-testid="overflow-hidden-container"
+        >
+          <div className="absolute w-80 h-10 bg-blue-200 p-2" data-testid="overflow-clipped-wide">
+            Wide clipped content
+          </div>
+          <div className="p-2 bg-green-200" data-testid="overflow-visible-child">
+            Visible child
+          </div>
+        </div>
+
+        <div
+          className="overflow-auto w-40 h-24 border-2 border-orange-400"
+          data-testid="overflow-auto-container"
+        >
+          <div className="w-80 h-40 bg-yellow-100 p-2">
+            <span data-testid="overflow-auto-inner">Scrollable inner content</span>
+          </div>
+        </div>
+
+        <div
+          className="overflow-hidden border-2 border-purple-400"
+          style={{ width: "200px", height: "40px" }}
+          data-testid="overflow-nested-outer"
+        >
+          <div
+            className="overflow-hidden border border-purple-200"
+            style={{ width: "150px", height: "30px" }}
+            data-testid="overflow-nested-inner"
+          >
+            <div
+              className="bg-purple-100 p-1"
+              style={{ width: "300px", height: "60px" }}
+              data-testid="overflow-nested-content"
+            >
+              Nested clipped content
+            </div>
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+};
+
+const ContainPaintSection = () => {
+  return (
+    <section className="border rounded-lg p-4" data-testid="contain-paint-section">
+      <h2 className="text-lg font-bold mb-4">CSS Containment</h2>
+      <div className="space-y-4">
+        <div
+          style={{ contain: "paint", width: "150px", height: "40px" }}
+          className="border-2 border-teal-400 relative"
+          data-testid="contain-paint-container"
+        >
+          <div
+            className="absolute bg-teal-200 p-2"
+            style={{ width: "300px", height: "30px" }}
+            data-testid="contain-paint-clipped"
+          >
+            Paint-contained clipped
+          </div>
+        </div>
+
+        <div
+          style={{ contain: "strict", width: "150px", height: "40px" }}
+          className="border-2 border-cyan-400 relative"
+          data-testid="contain-strict-container"
+        >
+          <div className="bg-cyan-200 p-2" data-testid="contain-strict-child">
+            Strict contained
+          </div>
+        </div>
+
+        <div
+          style={{ contain: "content", width: "150px", height: "40px" }}
+          className="border-2 border-sky-400 relative"
+          data-testid="contain-content-container"
+        >
+          <div className="bg-sky-200 p-2" data-testid="contain-content-child">
+            Content contained
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+};
+
+const StackingOrderSection = () => {
+  return (
+    <section className="border rounded-lg p-4" data-testid="stacking-order-section">
+      <h2 className="text-lg font-bold mb-4">Stacking Order</h2>
+      <div className="relative" style={{ height: "120px" }}>
+        <div
+          className="absolute bg-red-300 p-4"
+          style={{ top: "0", left: "0", width: "200px", height: "100px", zIndex: 1 }}
+          data-testid="stacking-bottom"
+        >
+          Bottom (z-index: 1)
+        </div>
+        <div
+          className="absolute bg-green-300 p-4"
+          style={{ top: "20px", left: "20px", width: "200px", height: "100px", zIndex: 2 }}
+          data-testid="stacking-middle"
+        >
+          Middle (z-index: 2)
+        </div>
+        <div
+          className="absolute bg-blue-300 p-4"
+          style={{ top: "40px", left: "40px", width: "200px", height: "100px", zIndex: 3 }}
+          data-testid="stacking-top"
+        >
+          Top (z-index: 3)
+        </div>
+      </div>
+
+      <div className="relative mt-8" style={{ height: "80px" }}>
+        <div
+          className="absolute bg-amber-200 p-4"
+          style={{ top: "0", left: "0", width: "250px", height: "60px" }}
+          data-testid="stacking-large-behind"
+        >
+          Large element behind
+        </div>
+        <div
+          className="absolute bg-amber-500 text-white p-2"
+          style={{ top: "10px", left: "10px", width: "100px", height: "40px", zIndex: 1 }}
+          data-testid="stacking-small-front"
+        >
+          Small in front
+        </div>
+      </div>
+    </section>
+  );
+};
+
+const DecorativeOverlaySection = () => {
+  return (
+    <section className="border rounded-lg p-4" data-testid="decorative-overlay-section">
+      <h2 className="text-lg font-bold mb-4">Decorative Overlays</h2>
+      <div className="relative" style={{ height: "80px" }}>
+        <div className="bg-indigo-200 p-4" data-testid="decorative-content">
+          This content should be selectable
+        </div>
+        <div
+          className="absolute inset-0"
+          style={{ pointerEvents: "none" }}
+          data-testid="decorative-empty-overlay"
+        />
+      </div>
+
+      <div className="relative mt-4" style={{ height: "80px" }}>
+        <p className="bg-pink-200 p-4" data-testid="decorative-text-content">
+          Text content under a positioned empty div
+        </p>
+        <div
+          className="absolute"
+          style={{ top: "0", left: "0", width: "100%", height: "100%" }}
+          data-testid="decorative-positioned-empty"
+        />
+      </div>
+    </section>
+  );
+};
+
+const InlineElementsSection = () => {
+  return (
+    <section className="border rounded-lg p-4" data-testid="inline-elements-section">
+      <h2 className="text-lg font-bold mb-4">Inline Elements</h2>
+      <p className="mb-2" data-testid="inline-paragraph">
+        This paragraph has <span data-testid="inline-span">an inline span</span> and{" "}
+        <a href="#" data-testid="inline-link" className="text-blue-500 underline">
+          an inline link
+        </a>{" "}
+        and <em data-testid="inline-em">emphasized text</em> and{" "}
+        <strong data-testid="inline-strong">strong text</strong> inside it.
+      </p>
+      <p className="mb-2">
+        <code className="bg-gray-100 px-1" data-testid="inline-code">
+          inline code element
+        </code>
+      </p>
+    </section>
+  );
+};
+
+const TransformStackingSection = () => {
+  return (
+    <section className="border rounded-lg p-4" data-testid="transform-stacking-section">
+      <h2 className="text-lg font-bold mb-4">Transform & Opacity Stacking</h2>
+      <div className="space-y-4">
+        <div
+          className="bg-rose-200 p-4"
+          style={{ transform: "translateZ(0)" }}
+          data-testid="transform-element"
+        >
+          Transformed element (creates stacking context)
+        </div>
+
+        <div className="bg-violet-200 p-4" style={{ opacity: 0.99 }} data-testid="opacity-element">
+          Opacity element (creates stacking context)
+        </div>
+
+        <div className="relative" style={{ height: "80px" }}>
+          <div
+            className="absolute bg-lime-200 p-4"
+            style={{ top: "0", left: "0", width: "200px", height: "60px" }}
+            data-testid="transform-behind"
+          >
+            Behind
+          </div>
+          <div
+            className="absolute bg-lime-500 text-white p-2"
+            style={{
+              top: "10px",
+              left: "10px",
+              width: "120px",
+              height: "40px",
+              transform: "scale(1)",
+              zIndex: 1,
+            }}
+            data-testid="transform-front"
+          >
+            Front (transform)
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+};
+
 const HiddenToggleSection = () => {
   const [isVisible, setIsVisible] = useState(true);
   const elementRef = useRef<HTMLDivElement>(null);
@@ -648,6 +884,18 @@ export default function App() {
 
       <PointerUpModalSection />
 
+      <OverflowClippingSection />
+
+      <ContainPaintSection />
+
+      <StackingOrderSection />
+
+      <DecorativeOverlaySection />
+
+      <InlineElementsSection />
+
+      <TransformStackingSection />
+
       <HiddenToggleSection />
 
       <div
diff --git a/packages/react-grab/e2e/element-detection.spec.ts b/packages/react-grab/e2e/element-detection.spec.ts
new file mode 100644
index 000000000..db657cf3b
--- /dev/null
+++ b/packages/react-grab/e2e/element-detection.spec.ts
@@ -0,0 +1,939 @@
+import { test, expect } from "./fixtures.js";
+
+const getTargetTestId = async (page: import("@playwright/test").Page): Promise<string | null> => {
+  return page.evaluate(() => {
+    const api = (
+      window as {
+        __REACT_GRAB__?: {
+          getState: () => { targetElement: Element | null };
+        };
+      }
+    ).__REACT_GRAB__;
+    return api?.getState()?.targetElement?.getAttribute("data-testid") ?? null;
+  });
+};
+
+const getTargetTagName = async (page: import("@playwright/test").Page): Promise<string | null> => {
+  return page.evaluate(() => {
+    const api = (
+      window as {
+        __REACT_GRAB__?: {
+          getState: () => { targetElement: Element | null };
+        };
+      }
+    ).__REACT_GRAB__;
+    return api?.getState()?.targetElement?.tagName?.toLowerCase() ?? null;
+  });
+};
+
+test.describe("Element Detection", () => {
+  test.describe("Overflow Clipping", () => {
+    test("should select visible child inside overflow:hidden container", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='overflow-clipping-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='overflow-visible-child']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("overflow-visible-child");
+    });
+
+    test("should select clipped element when hovering its visible region", async ({
+      reactGrab,
+    }) => {
+      const container = reactGrab.page.locator("[data-testid='overflow-hidden-container']");
+      await container.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+
+      const containerBox = await container.boundingBox();
+      if (!containerBox) throw new Error("Could not get container bounds");
+
+      await reactGrab.page.mouse.move(containerBox.x + 10, containerBox.y + 10);
+      await reactGrab.waitForSelectionBox();
+
+      const isVisible = await reactGrab.isSelectionBoxVisible();
+      expect(isVisible).toBe(true);
+    });
+
+    test("should not select clipped element at position outside container", async ({
+      reactGrab,
+    }) => {
+      const container = reactGrab.page.locator("[data-testid='overflow-hidden-container']");
+      await container.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+
+      const containerBox = await container.boundingBox();
+      if (!containerBox) throw new Error("Could not get container bounds");
+
+      await reactGrab.page.mouse.move(containerBox.x + containerBox.width + 20, containerBox.y + 5);
+      await reactGrab.page.waitForTimeout(200);
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).not.toBe("overflow-clipped-wide");
+    });
+
+    test("should handle overflow:auto scrollable containers", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='overflow-clipping-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='overflow-auto-inner']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("overflow-auto-inner");
+    });
+
+    test("should handle nested overflow:hidden containers", async ({ reactGrab }) => {
+      const innerContainer = reactGrab.page.locator("[data-testid='overflow-nested-inner']");
+      await innerContainer.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+
+      const innerBox = await innerContainer.boundingBox();
+      if (!innerBox) throw new Error("Could not get inner container bounds");
+
+      await reactGrab.page.mouse.move(innerBox.x + 5, innerBox.y + 5);
+      await reactGrab.waitForSelectionBox();
+
+      const isVisible = await reactGrab.isSelectionBoxVisible();
+      expect(isVisible).toBe(true);
+    });
+
+    test("should select elements inside scroll-container", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='scrollable-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='scroll-item-1']");
+      await reactGrab.waitForSelectionBox();
+
+      const isVisible = await reactGrab.isSelectionBoxVisible();
+      expect(isVisible).toBe(true);
+
+      await reactGrab.clickElement("[data-testid='scroll-item-1']");
+      await expect.poll(() => reactGrab.getClipboardContent()).toContain("Scrollable Item 1");
+    });
+
+    test("should not select scroll items that are scrolled out of view", async ({ reactGrab }) => {
+      const container = reactGrab.page.locator("[data-testid='scroll-container']");
+      await container.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+
+      const containerBox = await container.boundingBox();
+      if (!containerBox) throw new Error("Could not get scroll container bounds");
+
+      await reactGrab.page.mouse.move(containerBox.x + containerBox.width / 2, containerBox.y + 5);
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).not.toBe("scroll-item-50");
+    });
+  });
+
+  test.describe("CSS Containment", () => {
+    test("should select child inside contain:paint container at visible region", async ({
+      reactGrab,
+    }) => {
+      const container = reactGrab.page.locator("[data-testid='contain-paint-container']");
+      await container.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+
+      const containerBox = await container.boundingBox();
+      if (!containerBox) throw new Error("Could not get container bounds");
+
+      await reactGrab.page.mouse.move(containerBox.x + 10, containerBox.y + 10);
+      await reactGrab.waitForSelectionBox();
+
+      const isVisible = await reactGrab.isSelectionBoxVisible();
+      expect(isVisible).toBe(true);
+    });
+
+    test("should not select paint-contained element outside container bounds", async ({
+      reactGrab,
+    }) => {
+      const container = reactGrab.page.locator("[data-testid='contain-paint-container']");
+      await container.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+
+      const containerBox = await container.boundingBox();
+      if (!containerBox) throw new Error("Could not get container bounds");
+
+      await reactGrab.page.mouse.move(
+        containerBox.x + containerBox.width + 30,
+        containerBox.y + 10,
+      );
+      await reactGrab.page.waitForTimeout(200);
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).not.toBe("contain-paint-clipped");
+    });
+
+    test("should select child inside contain:strict container", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='contain-paint-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='contain-strict-child']");
+      await reactGrab.waitForSelectionBox();
+
+      const isVisible = await reactGrab.isSelectionBoxVisible();
+      expect(isVisible).toBe(true);
+    });
+
+    test("should select child inside contain:content container", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='contain-paint-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='contain-content-child']");
+      await reactGrab.waitForSelectionBox();
+
+      const isVisible = await reactGrab.isSelectionBoxVisible();
+      expect(isVisible).toBe(true);
+    });
+  });
+
+  test.describe("Stacking Order", () => {
+    test("should select topmost z-indexed element at overlap point", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='stacking-order-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+
+      const topElement = reactGrab.page.locator("[data-testid='stacking-top']");
+      const topBox = await topElement.boundingBox();
+      if (!topBox) throw new Error("Could not get top element bounds");
+
+      await reactGrab.page.mouse.move(topBox.x + 10, topBox.y + 10);
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("stacking-top");
+    });
+
+    test("should select middle element where top element does not overlap", async ({
+      reactGrab,
+    }) => {
+      const section = reactGrab.page.locator("[data-testid='stacking-order-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+
+      const middleElement = reactGrab.page.locator("[data-testid='stacking-middle']");
+      const topElement = reactGrab.page.locator("[data-testid='stacking-top']");
+      const middleBox = await middleElement.boundingBox();
+      const topBox = await topElement.boundingBox();
+      if (!middleBox || !topBox) throw new Error("Could not get element bounds");
+
+      await reactGrab.page.mouse.move(middleBox.x + 5, middleBox.y + 5);
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("stacking-middle");
+    });
+
+    test("should select bottom element in non-overlapping region", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='stacking-order-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+
+      const bottomElement = reactGrab.page.locator("[data-testid='stacking-bottom']");
+      const bottomBox = await bottomElement.boundingBox();
+      if (!bottomBox) throw new Error("Could not get bottom element bounds");
+
+      await reactGrab.page.mouse.move(bottomBox.x + 5, bottomBox.y + 5);
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("stacking-bottom");
+    });
+
+    test("should prefer smaller front element over larger background", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='stacking-order-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+
+      const frontElement = reactGrab.page.locator("[data-testid='stacking-small-front']");
+      const frontBox = await frontElement.boundingBox();
+      if (!frontBox) throw new Error("Could not get front element bounds");
+
+      await reactGrab.page.mouse.move(
+        frontBox.x + frontBox.width / 2,
+        frontBox.y + frontBox.height / 2,
+      );
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("stacking-small-front");
+    });
+
+    test("should copy correct content from stacked elements", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='stacking-order-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='stacking-top']");
+      await reactGrab.waitForSelectionBox();
+      await reactGrab.clickElement("[data-testid='stacking-top']");
+
+      await expect.poll(() => reactGrab.getClipboardContent()).toContain("Top");
+    });
+  });
+
+  test.describe("Inline Elements", () => {
+    test("should select inline span element", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='inline-elements-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='inline-span']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("inline-span");
+    });
+
+    test("should select inline link element", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='inline-elements-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='inline-link']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("inline-link");
+    });
+
+    test("should select inline em element", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='inline-elements-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='inline-em']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("inline-em");
+    });
+
+    test("should select inline strong element", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='inline-elements-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='inline-strong']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("inline-strong");
+    });
+
+    test("should select inline code element", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='inline-elements-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='inline-code']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("inline-code");
+    });
+
+    test("should copy inline span content correctly", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='inline-elements-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='inline-span']");
+      await reactGrab.waitForSelectionBox();
+      await reactGrab.clickElement("[data-testid='inline-span']");
+
+      await expect.poll(() => reactGrab.getClipboardContent()).toContain("inline span");
+    });
+
+    test("should show selection box with correct bounds for inline elements", async ({
+      reactGrab,
+    }) => {
+      const section = reactGrab.page.locator("[data-testid='inline-elements-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='inline-span']");
+      await reactGrab.waitForSelectionBox();
+
+      const bounds = await reactGrab.getSelectionBoxBounds();
+      expect(bounds).not.toBeNull();
+      expect(bounds!.width).toBeGreaterThan(0);
+      expect(bounds!.height).toBeGreaterThan(0);
+    });
+  });
+
+  test.describe("Decorative Overlays", () => {
+    test("should select content element, not the empty overlay above it", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='decorative-overlay-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='decorative-content']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("decorative-content");
+    });
+
+    test("should select text content under positioned empty div", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='decorative-overlay-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='decorative-text-content']");
+      await reactGrab.waitForSelectionBox();
+
+      await reactGrab.clickElement("[data-testid='decorative-text-content']");
+      await expect.poll(() => reactGrab.getClipboardContent()).toContain("Text content under");
+    });
+
+    test("should copy content from element under decorative overlay", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='decorative-overlay-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='decorative-content']");
+      await reactGrab.waitForSelectionBox();
+      await reactGrab.clickElement("[data-testid='decorative-content']");
+
+      await expect.poll(() => reactGrab.getClipboardContent()).toContain("should be selectable");
+    });
+  });
+
+  test.describe("Transform and Opacity Stacking", () => {
+    test("should select element with CSS transform", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='transform-stacking-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='transform-element']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("transform-element");
+    });
+
+    test("should select element with sub-1 opacity", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='transform-stacking-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='opacity-element']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("opacity-element");
+    });
+
+    test("should prefer front transformed element at overlap", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='transform-stacking-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+
+      const frontElement = reactGrab.page.locator("[data-testid='transform-front']");
+      const frontBox = await frontElement.boundingBox();
+      if (!frontBox) throw new Error("Could not get front element bounds");
+
+      await reactGrab.page.mouse.move(
+        frontBox.x + frontBox.width / 2,
+        frontBox.y + frontBox.height / 2,
+      );
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("transform-front");
+    });
+  });
+
+  test.describe("Fixed Position Elements", () => {
+    test("should select fixed-position corner element", async ({ reactGrab }) => {
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='edge-top-left']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("edge-top-left");
+    });
+
+    test("should select different fixed-position corners", async ({ reactGrab }) => {
+      await reactGrab.activate();
+
+      await reactGrab.hoverElement("[data-testid='edge-top-right']");
+      await reactGrab.waitForSelectionBox();
+      const topRightId = await getTargetTestId(reactGrab.page);
+      expect(topRightId).toBe("edge-top-right");
+
+      await reactGrab.hoverElement("[data-testid='edge-bottom-left']");
+      await reactGrab.waitForSelectionBox();
+      const bottomLeftId = await getTargetTestId(reactGrab.page);
+      expect(bottomLeftId).toBe("edge-bottom-left");
+    });
+
+    test("should copy fixed-position element content", async ({ reactGrab }) => {
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='edge-top-left']");
+      await reactGrab.waitForSelectionBox();
+      await reactGrab.clickElement("[data-testid='edge-top-left']");
+
+      await expect.poll(() => reactGrab.getClipboardContent()).toContain("Top Left");
+    });
+  });
+
+  test.describe("Various Element Types", () => {
+    test("should select table cells", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='various-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='td-1-1']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("td-1-1");
+    });
+
+    test("should select image element", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='various-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='img-element']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("img-element");
+    });
+
+    test("should select article element", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='various-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='article-element']");
+      await reactGrab.waitForSelectionBox();
+
+      const isVisible = await reactGrab.isSelectionBoxVisible();
+      expect(isVisible).toBe(true);
+    });
+
+    test("should select button element", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='various-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='plain-button']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("plain-button");
+    });
+
+    test("should select gradient div", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='various-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='gradient-div']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("gradient-div");
+    });
+  });
+
+  test.describe("Element Removal After Index Build", () => {
+    test("should handle element removal after activation", async ({ reactGrab }) => {
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='dynamic-element-2']");
+      await reactGrab.waitForSelectionBox();
+
+      const testIdBefore = await getTargetTestId(reactGrab.page);
+      expect(testIdBefore).toBe("dynamic-element-2");
+
+      await reactGrab.removeElement("[data-testid='dynamic-element-2']");
+      await reactGrab.page.waitForTimeout(200);
+
+      await reactGrab.hoverElement("[data-testid='dynamic-element-1']");
+      await reactGrab.waitForSelectionBox();
+
+      const testIdAfter = await getTargetTestId(reactGrab.page);
+      expect(testIdAfter).toBe("dynamic-element-1");
+    });
+
+    test("should handle dynamically added elements", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='dynamic-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+
+      await reactGrab.page.evaluate(() => {
+        const section = document.querySelector("[data-testid='dynamic-section']");
+        if (!section) return;
+        const newDiv = document.createElement("div");
+        newDiv.setAttribute("data-testid", "runtime-added-element");
+        newDiv.className = "p-4 bg-emerald-200 rounded mt-2";
+        newDiv.textContent = "Dynamically added at runtime";
+        section.appendChild(newDiv);
+      });
+      await reactGrab.page.waitForTimeout(200);
+
+      await reactGrab.hoverElement("[data-testid='runtime-added-element']");
+      await reactGrab.waitForSelectionBox();
+
+      const isVisible = await reactGrab.isSelectionBoxVisible();
+      expect(isVisible).toBe(true);
+    });
+  });
+
+  test.describe("Zero-Dimension and Invisible Elements", () => {
+    test("should not detect zero-size elements", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='zero-dimension-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+
+      const zeroEl = reactGrab.page.locator("[data-testid='zero-size-element']");
+      const box = await zeroEl.boundingBox();
+
+      if (box && box.width > 0 && box.height > 0) {
+        await reactGrab.page.mouse.move(box.x, box.y);
+      } else {
+        await reactGrab.page.mouse.move(100, 100);
+      }
+      await reactGrab.page.waitForTimeout(200);
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).not.toBe("zero-size-element");
+    });
+
+    test("should skip invisible elements and select visible ones", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='zero-dimension-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='zero-dimension-section'] h2");
+      await reactGrab.waitForSelectionBox();
+
+      const tagName = await getTargetTagName(reactGrab.page);
+      expect(tagName).toBe("h2");
+    });
+  });
+
+  test.describe("Modal and Overlay Interaction", () => {
+    test("should select modal content when modal is open", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='modal-dialog-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.page.click("[data-testid='modal-trigger']");
+      await reactGrab.page.waitForSelector("[data-testid='modal-content']");
+
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='modal-inner-button']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("modal-inner-button");
+    });
+
+    test("should copy modal content correctly", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='modal-dialog-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.page.click("[data-testid='modal-trigger']");
+      await reactGrab.page.waitForSelector("[data-testid='modal-content']");
+
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='modal-inner-button']");
+      await reactGrab.waitForSelectionBox();
+      await reactGrab.clickElement("[data-testid='modal-inner-button']");
+
+      await expect.poll(() => reactGrab.getClipboardContent()).toContain("Button Inside Modal");
+    });
+  });
+
+  test.describe("Deeply Nested Elements", () => {
+    test("should select deepest nested text element", async ({ reactGrab }) => {
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='deeply-nested-text']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("deeply-nested-text");
+    });
+
+    test("should select nested button inside cards", async ({ reactGrab }) => {
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='nested-button']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("nested-button");
+    });
+
+    test("should navigate through nested cards with arrows", async ({ reactGrab }) => {
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='nested-button']");
+      await reactGrab.waitForSelectionBox();
+
+      await reactGrab.pressArrowDown();
+      await reactGrab.page.waitForTimeout(200);
+
+      const isVisible = await reactGrab.isSelectionBoxVisible();
+      expect(isVisible).toBe(true);
+    });
+  });
+
+  test.describe("Reactivation Rebuilds Index", () => {
+    test("should rebuild element index on each activation cycle", async ({ reactGrab }) => {
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='main-title']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId1 = await getTargetTestId(reactGrab.page);
+      expect(testId1).toBe("main-title");
+
+      await reactGrab.deactivate();
+      await reactGrab.page.waitForTimeout(100);
+
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='main-title']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId2 = await getTargetTestId(reactGrab.page);
+      expect(testId2).toBe("main-title");
+    });
+
+    test("should detect elements added between activation cycles", async ({ reactGrab }) => {
+      await reactGrab.activate();
+      await reactGrab.deactivate();
+
+      await reactGrab.page.evaluate(() => {
+        const section = document.querySelector("[data-testid='dynamic-section']");
+        if (!section) return;
+        const newDiv = document.createElement("div");
+        newDiv.setAttribute("data-testid", "between-cycles-element");
+        newDiv.className = "p-4 bg-fuchsia-200 rounded mt-2";
+        newDiv.textContent = "Added between cycles";
+        section.appendChild(newDiv);
+      });
+
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='between-cycles-element']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("between-cycles-element");
+    });
+  });
+
+  test.describe("Animated Elements", () => {
+    test("should select pulsing element after freeze", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='animated-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='animated-pulse']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("animated-pulse");
+    });
+
+    test("should select spinning element after freeze", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='animated-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='animated-spin']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("animated-spin");
+    });
+
+    test("should select bouncing element after freeze", async ({ reactGrab }) => {
+      const section = reactGrab.page.locator("[data-testid='animated-section']");
+      await section.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='animated-bounce']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("animated-bounce");
+    });
+  });
+
+  test.describe("Injected Edge Cases", () => {
+    test("should skip absolutely positioned empty decorative div over content", async ({
+      reactGrab,
+    }) => {
+      await reactGrab.page.evaluate(() => {
+        const container = document.createElement("div");
+        container.id = "injected-decorative-test";
+        container.style.cssText = "position: relative; margin: 16px;";
+        container.innerHTML = `
+          <p data-testid="injected-real-content" style="padding: 16px; background: #e0f2fe;">
+            Real content under decorative overlay
+          </p>
+          <div style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></div>
+        `;
+        document.body.appendChild(container);
+      });
+
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='injected-real-content']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("injected-real-content");
+
+      await reactGrab.page.evaluate(() => {
+        document.getElementById("injected-decorative-test")?.remove();
+      });
+    });
+
+    test("should handle deeply nested overflow clipping chain", async ({ reactGrab }) => {
+      await reactGrab.page.evaluate(() => {
+        const container = document.createElement("div");
+        container.id = "injected-nested-clip-test";
+        container.innerHTML = `
+          <div style="overflow: hidden; width: 200px; height: 100px; border: 2px solid red; margin: 16px;">
+            <div style="overflow: hidden; width: 150px; height: 80px; border: 1px solid orange;">
+              <div style="overflow: hidden; width: 100px; height: 60px; border: 1px solid yellow;">
+                <div data-testid="injected-deep-visible" style="padding: 4px; background: #fef3c7; width: 80px;">
+                  Visible
+                </div>
+                <div data-testid="injected-deep-clipped" style="padding: 4px; background: #fee2e2; width: 300px; position: relative;">
+                  This extends far beyond all containers
+                </div>
+              </div>
+            </div>
+          </div>
+        `;
+        document.body.appendChild(container);
+      });
+
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='injected-deep-visible']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("injected-deep-visible");
+
+      await reactGrab.page.evaluate(() => {
+        document.getElementById("injected-nested-clip-test")?.remove();
+      });
+    });
+
+    test("should handle contain:paint with overflow interaction", async ({ reactGrab }) => {
+      await reactGrab.page.evaluate(() => {
+        const container = document.createElement("div");
+        container.id = "injected-contain-overflow-test";
+        container.innerHTML = `
+          <div style="contain: paint; overflow: hidden; width: 120px; height: 50px; border: 2px solid #0d9488; margin: 16px; position: relative;">
+            <div data-testid="injected-contain-visible" style="padding: 4px; background: #ccfbf1;">
+              Visible
+            </div>
+            <div data-testid="injected-contain-clipped" style="position: absolute; left: 130px; top: 0; padding: 4px; background: #fecdd3;">
+              Clipped by contain
+            </div>
+          </div>
+        `;
+        document.body.appendChild(container);
+      });
+
+      await reactGrab.activate();
+      await reactGrab.hoverElement("[data-testid='injected-contain-visible']");
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("injected-contain-visible");
+
+      await reactGrab.page.evaluate(() => {
+        document.getElementById("injected-contain-overflow-test")?.remove();
+      });
+    });
+
+    test("should handle multiple stacking contexts with transforms", async ({ reactGrab }) => {
+      await reactGrab.page.evaluate(() => {
+        const container = document.createElement("div");
+        container.id = "injected-transform-stack-test";
+        container.style.cssText = "position: relative; height: 100px; margin: 16px;";
+        container.innerHTML = `
+          <div data-testid="injected-transform-back" style="position: absolute; top: 0; left: 0; width: 200px; height: 80px; background: #dbeafe; padding: 8px;">
+            Background
+          </div>
+          <div data-testid="injected-transform-front" style="position: absolute; top: 10px; left: 10px; width: 120px; height: 60px; background: #bfdbfe; padding: 8px; transform: translateZ(0); z-index: 1;">
+            Foreground (transform)
+          </div>
+        `;
+        document.body.appendChild(container);
+      });
+
+      const frontElement = reactGrab.page.locator("[data-testid='injected-transform-front']");
+      await frontElement.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+
+      const frontBox = await frontElement.boundingBox();
+      if (!frontBox) throw new Error("Could not get front element bounds");
+
+      await reactGrab.page.mouse.move(
+        frontBox.x + frontBox.width / 2,
+        frontBox.y + frontBox.height / 2,
+      );
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("injected-transform-front");
+
+      await reactGrab.page.evaluate(() => {
+        document.getElementById("injected-transform-stack-test")?.remove();
+      });
+    });
+
+    test("should handle flex item stacking with z-index", async ({ reactGrab }) => {
+      await reactGrab.page.evaluate(() => {
+        const container = document.createElement("div");
+        container.id = "injected-flex-stack-test";
+        container.style.cssText = "display: flex; position: relative; height: 80px; margin: 16px;";
+        container.innerHTML = `
+          <div data-testid="injected-flex-behind" style="position: absolute; width: 200px; height: 60px; background: #fde68a; padding: 8px; z-index: 0;">
+            Flex behind
+          </div>
+          <div data-testid="injected-flex-front" style="position: absolute; width: 100px; height: 40px; background: #fbbf24; padding: 8px; z-index: 2; top: 10px; left: 10px;">
+            Flex front
+          </div>
+        `;
+        document.body.appendChild(container);
+      });
+
+      const frontElement = reactGrab.page.locator("[data-testid='injected-flex-front']");
+      await frontElement.scrollIntoViewIfNeeded();
+      await reactGrab.activate();
+
+      const frontBox = await frontElement.boundingBox();
+      if (!frontBox) throw new Error("Could not get front element bounds");
+
+      await reactGrab.page.mouse.move(
+        frontBox.x + frontBox.width / 2,
+        frontBox.y + frontBox.height / 2,
+      );
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("injected-flex-front");
+
+      await reactGrab.page.evaluate(() => {
+        document.getElementById("injected-flex-stack-test")?.remove();
+      });
+    });
+
+    test("should handle page with only fixed elements and no regular elements", async ({
+      reactGrab,
+    }) => {
+      await reactGrab.page.evaluate(() => {
+        document.body.innerHTML = "";
+        const fixedElement = document.createElement("div");
+        fixedElement.id = "injected-fixed-only-test";
+        fixedElement.setAttribute("data-testid", "fixed-only-element");
+        fixedElement.style.cssText =
+          "position: fixed; top: 10px; left: 10px; width: 200px; height: 60px; background: #93c5fd; padding: 8px; z-index: 10;";
+        fixedElement.textContent = "Only fixed element";
+        document.body.appendChild(fixedElement);
+      });
+
+      await reactGrab.activate();
+
+      const fixedElement = reactGrab.page.locator("[data-testid='fixed-only-element']");
+      const fixedBox = await fixedElement.boundingBox();
+      if (!fixedBox) throw new Error("Could not get fixed element bounds");
+
+      await reactGrab.page.mouse.move(
+        fixedBox.x + fixedBox.width / 2,
+        fixedBox.y + fixedBox.height / 2,
+      );
+      await reactGrab.waitForSelectionBox();
+
+      const testId = await getTargetTestId(reactGrab.page);
+      expect(testId).toBe("fixed-only-element");
+    });
+  });
+});
diff --git a/packages/react-grab/package.json b/packages/react-grab/package.json
index 4ee57e2b1..6dfe305c7 100644
--- a/packages/react-grab/package.json
+++ b/packages/react-grab/package.json
@@ -102,7 +102,6 @@
   "devDependencies": {
     "@babel/core": "^7.28.5",
     "@babel/preset-typescript": "^7.28.5",
-    "solid-js": "^1.9.10",
     "@playwright/test": "^1.40.0",
     "@tailwindcss/cli": "^4.1.17",
     "@types/babel__core": "^7.20.5",
@@ -111,6 +110,7 @@
     "babel-preset-solid": "^1.9.10",
     "concurrently": "^9.1.2",
     "expect-sdk": "0.0.0-canary-20260405095424",
+    "solid-js": "^1.9.10",
     "tailwindcss": "^4.1.0",
     "tsx": "^4.21.0"
   },
diff --git a/packages/react-grab/src/core/index.tsx b/packages/react-grab/src/core/index.tsx
index 7e113ad58..3a5057d8e 100644
--- a/packages/react-grab/src/core/index.tsx
+++ b/packages/react-grab/src/core/index.tsx
@@ -135,7 +135,10 @@ import {
 } from "../utils/freeze-animations.js";
 import { freezePseudoStates, unfreezePseudoStates } from "../utils/freeze-pseudo-states.js";
 import { freezeUpdates } from "../utils/freeze-updates.js";
-import { buildElementAtPointIndex, destroyElementAtPointIndex } from "../utils/element-at-point-index.js";
+import {
+  buildElementAtPointIndex,
+  destroyElementAtPointIndex,
+} from "../utils/element-at-point-index.js";
 import {
   loadComments,
   addCommentItem,
@@ -231,7 +234,8 @@ export const init = (rawOptions?: Options): ReactGrabAPI => {
     const isDragging = createMemo(
       () =>
         store.current.state === "active" &&
-        (store.current.phase === "dragging-select" || store.current.phase === "dragging-reposition"),
+        (store.current.phase === "dragging-select" ||
+          store.current.phase === "dragging-reposition"),
     );
     const isDragRepositioning = createMemo(
       () => store.current.state === "active" && store.current.phase === "dragging-reposition",
diff --git a/packages/react-grab/src/core/store.ts b/packages/react-grab/src/core/store.ts
index 825c24f15..7121799ae 100644
--- a/packages/react-grab/src/core/store.ts
+++ b/packages/react-grab/src/core/store.ts
@@ -12,12 +12,7 @@ interface FrozenDragRect {
   height: number;
 }
 
-type GrabPhase =
-  | "hovering"
-  | "frozen"
-  | "dragging-select"
-  | "dragging-reposition"
-  | "justDragged";
+type GrabPhase = "hovering" | "frozen" | "dragging-select" | "dragging-reposition" | "justDragged";
 
 type GrabState =
   | { state: "idle" }
diff --git a/packages/react-grab/src/primitives.ts b/packages/react-grab/src/primitives.ts
index 6a0320a6f..e9867922f 100644
--- a/packages/react-grab/src/primitives.ts
+++ b/packages/react-grab/src/primitives.ts
@@ -3,9 +3,8 @@ import {
   freezeGlobalAnimations,
   unfreezeGlobalAnimations,
 } from "./utils/freeze-animations.js";
-import { freezePseudoStates } from "./utils/freeze-pseudo-states.js";
+import { freezePseudoStates, unfreezePseudoStates } from "./utils/freeze-pseudo-states.js";
 import { freezeUpdates } from "./utils/freeze-updates.js";
-import { unfreezePseudoStates } from "./utils/freeze-pseudo-states.js";
 import {
   getComponentDisplayName,
   getHTMLPreview,
diff --git a/packages/react-grab/src/utils/compare-stacking-order.ts b/packages/react-grab/src/utils/compare-stacking-order.ts
index 12d73309b..347bd5119 100644
--- a/packages/react-grab/src/utils/compare-stacking-order.ts
+++ b/packages/react-grab/src/utils/compare-stacking-order.ts
@@ -1,4 +1,5 @@
-const STACKING_PROPS = /\b(?:position|z-index|opacity|transform|mix-blend-mode|filter|isolation)\b/;
+const STACKING_PROPS =
+  /\b(?:position|z-index|opacity|transform|mix-blend-mode|filter|isolation|clip-path|backdrop-filter|perspective|contain)\b/;
 
 const getParentElement = (node: Element): Element | null => {
   const parentNode = node.parentNode;
@@ -20,33 +21,48 @@ const isFlexOrGridItem = (node: Element): boolean => {
   const parentElement = getParentElement(node);
   if (!parentElement) return false;
   const display = getComputedStyle(parentElement).display;
-  return display === "flex" || display === "inline-flex" || display === "grid" || display === "inline-grid";
+  return (
+    display === "flex" ||
+    display === "inline-flex" ||
+    display === "grid" ||
+    display === "inline-grid"
+  );
 };
 
-const createsStackingContext = (node: Element): boolean => {
-  const style = getComputedStyle(node);
+const hasPaintContainment = (containValue: string): boolean => {
+  if (containValue === "none" || containValue === "size" || containValue === "layout") return false;
+  return containValue === "paint" || containValue === "strict" || containValue === "content"
+    || containValue.includes("paint");
+};
+
+const isStackingContext = (node: Element, style: CSSStyleDeclaration): boolean => {
   if (style.position === "fixed" || style.position === "sticky") return true;
-  if (style.zIndex !== "auto" && (style.position !== "static" || isFlexOrGridItem(node))) return true;
+  if (style.zIndex !== "auto" && (style.position !== "static" || isFlexOrGridItem(node)))
+    return true;
   if (+style.opacity < 1) return true;
   if (style.transform !== "none") return true;
   if ("mixBlendMode" in style && style.mixBlendMode !== "normal") return true;
   if (style.filter !== "none") return true;
   if ("isolation" in style && style.getPropertyValue("isolation") === "isolate") return true;
+  if (hasPaintContainment(style.contain)) return true;
+  if ("backdropFilter" in style && style.getPropertyValue("backdrop-filter") !== "none") return true;
+  if (style.perspective !== "none") return true;
+  if ("clipPath" in style && style.getPropertyValue("clip-path") !== "none") return true;
   if (STACKING_PROPS.test(style.willChange)) return true;
   return false;
 };
 
-const findNearestStackingContext = (ancestors: Element[]): Element | null => {
+const getNearestStackingContextZIndex = (ancestors: Element[]): number => {
   let ancestorIndex = ancestors.length;
   while (ancestorIndex--) {
-    if (createsStackingContext(ancestors[ancestorIndex])) return ancestors[ancestorIndex];
+    const style = getComputedStyle(ancestors[ancestorIndex]);
+    if (isStackingContext(ancestors[ancestorIndex], style)) {
+      return Number(style.zIndex) || 0;
+    }
   }
-  return null;
+  return 0;
 };
 
-const getZIndex = (node: Element | null): number =>
-  (node && Number(getComputedStyle(node).zIndex)) || 0;
-
 export const compareStackingOrder = (elementA: Element, elementB: Element): number => {
   if (elementA === elementB) return 0;
 
@@ -60,8 +76,8 @@ export const compareStackingOrder = (elementA: Element, elementB: Element): numb
     ancestorsB.pop();
   }
 
-  const zIndexA = getZIndex(findNearestStackingContext(ancestorsA));
-  const zIndexB = getZIndex(findNearestStackingContext(ancestorsB));
+  const zIndexA = getNearestStackingContextZIndex(ancestorsA);
+  const zIndexB = getNearestStackingContextZIndex(ancestorsB);
 
   if (zIndexA === zIndexB) {
     if (!commonAncestor) return 0;
diff --git a/packages/react-grab/src/utils/element-at-point-index.ts b/packages/react-grab/src/utils/element-at-point-index.ts
index 64f4095cc..e37bd2dc2 100644
--- a/packages/react-grab/src/utils/element-at-point-index.ts
+++ b/packages/react-grab/src/utils/element-at-point-index.ts
@@ -1,12 +1,9 @@
 import { HilbertRTree } from "./hilbert-r-tree.js";
 import { ELEMENT_AT_POINT_INDEX_ROOT_MARGIN_PX } from "../constants.js";
 import { isValidGrabbableElement } from "./is-valid-grabbable-element.js";
+import { isDecorativeOverlay } from "./is-decorative-overlay.js";
 import { compareStackingOrder } from "./compare-stacking-order.js";
 
-interface IndexedElement {
-  element: Element;
-}
-
 interface PageRect {
   left: number;
   top: number;
@@ -14,14 +11,28 @@ interface PageRect {
   bottom: number;
 }
 
+interface CachedFixedElement {
+  element: Element;
+  viewportRect: PageRect;
+  zIndex: number;
+}
+
 interface ElementAtPointIndexState {
-  tree: HilbertRTree;
-  elements: IndexedElement[];
+  tree: HilbertRTree | null;
+  elements: Element[];
+  fixedElements: CachedFixedElement[];
 }
 
 const SKIP_TAGS = new Set([
-  "SCRIPT", "STYLE", "HEAD", "META", "LINK",
-  "NOSCRIPT", "BR", "TEMPLATE", "SLOT",
+  "SCRIPT",
+  "STYLE",
+  "HEAD",
+  "META",
+  "LINK",
+  "NOSCRIPT",
+  "BR",
+  "TEMPLATE",
+  "SLOT",
 ]);
 
 let currentIndex: ElementAtPointIndexState | null = null;
@@ -32,8 +43,9 @@ export const buildElementAtPointIndex = (): void => {
 
   let didObserveAnyElement = false;
 
-  const accumulatedElements: IndexedElement[] = [];
+  const accumulatedElements: Element[] = [];
   const accumulatedRects: PageRect[] = [];
+  const accumulatedFixedElements: CachedFixedElement[] = [];
 
   const observer = new IntersectionObserver(
     (entries) => {
@@ -47,17 +59,23 @@ export const buildElementAtPointIndex = (): void => {
         const boundingRect = entry.boundingClientRect;
         if (boundingRect.width === 0 || boundingRect.height === 0) continue;
         if (!isValidGrabbableElement(targetElement)) continue;
-        const computedPosition = getComputedStyle(targetElement).position;
-        if (computedPosition === "fixed") continue;
-        if (
-          (computedPosition === "absolute" || computedPosition === "sticky") &&
-          targetElement.childElementCount === 0 &&
-          (targetElement.textContent?.trim().length ?? 0) === 0
-        ) continue;
-
-        accumulatedElements.push({
-          element: targetElement,
-        });
+        const computedStyle = getComputedStyle(targetElement);
+        if (computedStyle.position === "fixed") {
+          accumulatedFixedElements.push({
+            element: targetElement,
+            viewportRect: {
+              left: boundingRect.left,
+              top: boundingRect.top,
+              right: boundingRect.right,
+              bottom: boundingRect.bottom,
+            },
+            zIndex: parseInt(computedStyle.zIndex, 10) || 0,
+          });
+          continue;
+        }
+        if (isDecorativeOverlay(targetElement, computedStyle.position)) continue;
+
+        accumulatedElements.push(targetElement);
 
         accumulatedRects.push({
           left: boundingRect.left + scrollX,
@@ -67,31 +85,36 @@ export const buildElementAtPointIndex = (): void => {
         });
       }
 
-      if (accumulatedElements.length === 0) return;
+      if (accumulatedElements.length === 0 && accumulatedFixedElements.length === 0) return;
 
-      const tree = new HilbertRTree(accumulatedElements.length);
-      for (const rect of accumulatedRects) {
-        tree.add(rect.left, rect.top, rect.right, rect.bottom);
+      let tree: HilbertRTree | null = null;
+      if (accumulatedElements.length > 0) {
+        tree = new HilbertRTree(accumulatedElements.length);
+        for (const rect of accumulatedRects) {
+          tree.add(rect.left, rect.top, rect.right, rect.bottom);
+        }
+        tree.finish();
       }
-      tree.finish();
 
-      currentIndex = { tree, elements: [...accumulatedElements] };
+      accumulatedFixedElements.sort((entryA, entryB) => entryA.zIndex - entryB.zIndex);
+
+      currentIndex = {
+        tree,
+        elements: [...accumulatedElements],
+        fixedElements: [...accumulatedFixedElements],
+      };
     },
     { rootMargin: `${ELEMENT_AT_POINT_INDEX_ROOT_MARGIN_PX}px` },
   );
 
   pendingObserver = observer;
 
-  const walker = document.createTreeWalker(
-    document.body,
-    NodeFilter.SHOW_ELEMENT,
-    {
-      acceptNode: (node) =>
-        SKIP_TAGS.has((node as Element).tagName)
-          ? NodeFilter.FILTER_REJECT
-          : NodeFilter.FILTER_ACCEPT,
-    },
-  );
+  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_ELEMENT, {
+    acceptNode: (node) =>
+      SKIP_TAGS.has((node as Element).tagName)
+        ? NodeFilter.FILTER_REJECT
+        : NodeFilter.FILTER_ACCEPT,
+  });
 
   while (walker.nextNode()) {
     const element = walker.currentNode as HTMLElement;
@@ -109,6 +132,11 @@ export const buildElementAtPointIndex = (): void => {
 const CLIPPING_OVERFLOW_VALUES = new Set(["hidden", "scroll", "auto", "clip"]);
 const PAINT_CONTAIN_VALUES = new Set(["paint", "strict", "content"]);
 
+const CLIPS_X = 1;
+const CLIPS_Y = 2;
+
+let clipStateCache = new WeakMap<Element, number>();
+
 const hasPaintContainment = (containValue: string): boolean => {
   for (const keyword of containValue.split(" ")) {
     if (PAINT_CONTAIN_VALUES.has(keyword)) return true;
@@ -116,18 +144,36 @@ const hasPaintContainment = (containValue: string): boolean => {
   return false;
 };
 
+const getClipState = (ancestor: Element): number => {
+  const cached = clipStateCache.get(ancestor);
+  if (cached !== undefined) return cached;
+
+  const style = getComputedStyle(ancestor);
+  const isPaintContained = hasPaintContainment(style.contain);
+  let state = 0;
+  if (CLIPPING_OVERFLOW_VALUES.has(style.overflowX) || isPaintContained) state |= CLIPS_X;
+  if (CLIPPING_OVERFLOW_VALUES.has(style.overflowY) || isPaintContained) state |= CLIPS_Y;
+  clipStateCache.set(ancestor, state);
+  return state;
+};
+
 const isVisibleAtPoint = (element: Element, clientX: number, clientY: number): boolean => {
   let ancestor = element.parentElement;
   while (ancestor && ancestor !== document.documentElement) {
-    const style = getComputedStyle(ancestor);
-    const isPaintContained = hasPaintContainment(style.contain);
-    const clipsX = CLIPPING_OVERFLOW_VALUES.has(style.overflowX) || isPaintContained;
-    const clipsY = CLIPPING_OVERFLOW_VALUES.has(style.overflowY) || isPaintContained;
+    const clipState = getClipState(ancestor);
 
-    if (clipsX || clipsY) {
+    if (clipState !== 0) {
       const ancestorRect = ancestor.getBoundingClientRect();
-      if (clipsX && (clientX < ancestorRect.left || clientX > ancestorRect.right)) return false;
-      if (clipsY && (clientY < ancestorRect.top || clientY > ancestorRect.bottom)) return false;
+      if (
+        (clipState & CLIPS_X) !== 0 &&
+        (clientX < ancestorRect.left || clientX > ancestorRect.right)
+      )
+        return false;
+      if (
+        (clipState & CLIPS_Y) !== 0 &&
+        (clientY < ancestorRect.top || clientY > ancestorRect.bottom)
+      )
+        return false;
     }
 
     ancestor = ancestor.parentElement;
@@ -135,30 +181,57 @@ const isVisibleAtPoint = (element: Element, clientX: number, clientY: number): b
   return true;
 };
 
+const findTopmostFixedElement = (
+  fixedElements: CachedFixedElement[],
+  clientX: number,
+  clientY: number,
+): Element | null => {
+  let topmost: CachedFixedElement | null = null;
+
+  for (const entry of fixedElements) {
+    if (!entry.element.isConnected) continue;
+    const rect = entry.viewportRect;
+    if (
+      clientX >= rect.left &&
+      clientX <= rect.right &&
+      clientY >= rect.top &&
+      clientY <= rect.bottom
+    ) {
+      topmost = entry;
+    }
+  }
+
+  return topmost?.element ?? null;
+};
+
 export const queryElementAtPointIndex = (clientX: number, clientY: number): Element | null => {
   if (!currentIndex) return null;
 
   const pageX = clientX + window.scrollX;
   const pageY = clientY + window.scrollY;
 
-  const hitIndices = currentIndex.tree.search(pageX, pageY, pageX, pageY);
-  if (hitIndices.length === 0) return null;
+  const fixedHit = findTopmostFixedElement(currentIndex.fixedElements, clientX, clientY);
+
+  const hitIndices = currentIndex.tree?.search(pageX, pageY, pageX, pageY) ?? [];
 
   const visibleCandidates: Element[] = [];
 
   for (const hitIndex of hitIndices) {
     const candidate = currentIndex.elements[hitIndex];
-    if (!candidate.element.isConnected) continue;
-    if (!isVisibleAtPoint(candidate.element, clientX, clientY)) continue;
-    visibleCandidates.push(candidate.element);
+    if (!candidate.isConnected) continue;
+    if (!isVisibleAtPoint(candidate, clientX, clientY)) continue;
+    visibleCandidates.push(candidate);
+  }
+
+  if (fixedHit) {
+    if (visibleCandidates.length === 0) return fixedHit;
+    visibleCandidates.push(fixedHit);
   }
 
   if (visibleCandidates.length === 0) return null;
   if (visibleCandidates.length === 1) return visibleCandidates[0];
 
-  visibleCandidates.sort((elementA, elementB) =>
-    compareStackingOrder(elementB, elementA),
-  );
+  visibleCandidates.sort((elementA, elementB) => compareStackingOrder(elementB, elementA));
 
   return visibleCandidates[0];
 };
@@ -172,6 +245,8 @@ export const destroyElementAtPointIndex = (): void => {
   }
   if (currentIndex) {
     currentIndex.elements.length = 0;
+    currentIndex.fixedElements.length = 0;
     currentIndex = null;
   }
+  clipStateCache = new WeakMap<Element, number>();
 };
diff --git a/packages/react-grab/src/utils/freeze-pseudo-states.ts b/packages/react-grab/src/utils/freeze-pseudo-states.ts
index 6543a8461..9a5be3aee 100644
--- a/packages/react-grab/src/utils/freeze-pseudo-states.ts
+++ b/packages/react-grab/src/utils/freeze-pseudo-states.ts
@@ -182,9 +182,13 @@ export const freezePseudoStates = (cursorX?: number, cursorY?: number): void =>
   }
 
   const hoverStates: FrozenPseudoState[] = [];
-  const isCursorInViewport = cursorX !== undefined && cursorY !== undefined
-    && cursorX >= 0 && cursorY >= 0
-    && cursorX < window.innerWidth && cursorY < window.innerHeight;
+  const isCursorInViewport =
+    cursorX !== undefined &&
+    cursorY !== undefined &&
+    cursorX >= 0 &&
+    cursorY >= 0 &&
+    cursorX < window.innerWidth &&
+    cursorY < window.innerHeight;
   const hoveredElements = isCursorInViewport
     ? collectHoveredElements(cursorX, cursorY)
     : Array.from(document.querySelectorAll(":hover")).filter(
diff --git a/packages/react-grab/src/utils/get-element-at-position.ts b/packages/react-grab/src/utils/get-element-at-position.ts
index 510212e11..9701e1b71 100644
--- a/packages/react-grab/src/utils/get-element-at-position.ts
+++ b/packages/react-grab/src/utils/get-element-at-position.ts
@@ -69,13 +69,20 @@ export const getElementAtPosition = (clientX: number, clientY: number): Element
     const isWithinThrottle = now - cache.timestamp < ELEMENT_POSITION_THROTTLE_MS;
 
     if (isPositionClose || isWithinThrottle) {
-      return cache.element;
+      if (cache.element === null || cache.element.isConnected) {
+        return cache.element;
+      }
+      cache = null;
     }
   }
 
   if (isElementAtPointIndexReady()) {
     const spatialResult = queryElementAtPointIndex(clientX, clientY);
-    if (spatialResult && isValidGrabbableElement(spatialResult) && getElementArea(spatialResult) > 0) {
+    if (
+      spatialResult &&
+      isValidGrabbableElement(spatialResult) &&
+      getElementArea(spatialResult) > 0
+    ) {
       cache = { clientX, clientY, element: spatialResult, timestamp: now };
       return spatialResult;
     }
diff --git a/packages/react-grab/src/utils/hilbert-r-tree.ts b/packages/react-grab/src/utils/hilbert-r-tree.ts
index a0602d1b6..37a0e20bf 100644
--- a/packages/react-grab/src/utils/hilbert-r-tree.ts
+++ b/packages/react-grab/src/utils/hilbert-r-tree.ts
@@ -59,20 +59,30 @@ const sortByHilbert = (
     const stackRight = stack.pop()!;
     const stackLeft = stack.pop()!;
 
-    if (stackRight - stackLeft <= NODE_SIZE && Math.floor(stackLeft / NODE_SIZE) >= Math.floor(stackRight / NODE_SIZE)) continue;
+    if (
+      stackRight - stackLeft <= NODE_SIZE &&
+      Math.floor(stackLeft / NODE_SIZE) >= Math.floor(stackRight / NODE_SIZE)
+    )
+      continue;
 
     const valueLeft = values[stackLeft];
     const valueMid = values[(stackLeft + stackRight) >> 1];
     const valueRight = values[stackRight];
-    const pivot = ((valueLeft > valueMid) !== (valueLeft > valueRight)) ? valueLeft :
-      ((valueMid < valueLeft) !== (valueMid < valueRight)) ? valueMid : valueRight;
+    const pivot =
+      valueLeft > valueMid !== valueLeft > valueRight
+        ? valueLeft
+        : valueMid < valueLeft !== valueMid < valueRight
+          ? valueMid
+          : valueRight;
 
     let scanLeft = stackLeft - 1;
     let scanRight = stackRight + 1;
 
     while (true) {
-      do scanLeft++; while (values[scanLeft] < pivot);
-      do scanRight--; while (values[scanRight] > pivot);
+      do scanLeft++;
+      while (values[scanLeft] < pivot);
+      do scanRight--;
+      while (values[scanRight] > pivot);
       if (scanLeft >= scanRight) break;
       swapItems(values, boxes, indices, scanLeft, scanRight);
     }
@@ -85,44 +95,51 @@ const sortByHilbert = (
 // Ported from C++ https://github.com/rawrunprotected/hilbert_curves (public domain)
 const hilbert = (coordX: number, coordY: number): number => {
   let xorXY = coordX ^ coordY;
-  let invertedXor = 0xFFFF ^ xorXY;
-  let invertedOr = 0xFFFF ^ (coordX | coordY);
-  let maskedAnd = coordX & (coordY ^ 0xFFFF);
+  let invertedXor = 0xffff ^ xorXY;
+  let invertedOr = 0xffff ^ (coordX | coordY);
+  let maskedAnd = coordX & (coordY ^ 0xffff);
 
   let levelA = xorXY | (invertedXor >> 1);
   let levelB = (xorXY >> 1) ^ xorXY;
-  let levelC = ((invertedOr >> 1) ^ (invertedXor & (maskedAnd >> 1))) ^ invertedOr;
-  let levelD = ((xorXY & (invertedOr >> 1)) ^ (maskedAnd >> 1)) ^ maskedAnd;
-
-  xorXY = levelA; invertedXor = levelB; invertedOr = levelC; maskedAnd = levelD;
-  levelA = ((xorXY & (xorXY >> 2)) ^ (invertedXor & (invertedXor >> 2)));
-  levelB = ((xorXY & (invertedXor >> 2)) ^ (invertedXor & ((xorXY ^ invertedXor) >> 2)));
-  levelC ^= ((xorXY & (invertedOr >> 2)) ^ (invertedXor & (maskedAnd >> 2)));
-  levelD ^= ((invertedXor & (invertedOr >> 2)) ^ ((xorXY ^ invertedXor) & (maskedAnd >> 2)));
-
-  xorXY = levelA; invertedXor = levelB; invertedOr = levelC; maskedAnd = levelD;
-  levelA = ((xorXY & (xorXY >> 4)) ^ (invertedXor & (invertedXor >> 4)));
-  levelB = ((xorXY & (invertedXor >> 4)) ^ (invertedXor & ((xorXY ^ invertedXor) >> 4)));
-  levelC ^= ((xorXY & (invertedOr >> 4)) ^ (invertedXor & (maskedAnd >> 4)));
-  levelD ^= ((invertedXor & (invertedOr >> 4)) ^ ((xorXY ^ invertedXor) & (maskedAnd >> 4)));
-
-  xorXY = levelA; invertedXor = levelB;
-  levelC ^= ((xorXY & (invertedOr >> 8)) ^ (invertedXor & (maskedAnd >> 8)));
-  levelD ^= ((invertedXor & (invertedOr >> 8)) ^ ((xorXY ^ invertedXor) & (maskedAnd >> 8)));
+  let levelC = (invertedOr >> 1) ^ (invertedXor & (maskedAnd >> 1)) ^ invertedOr;
+  let levelD = (xorXY & (invertedOr >> 1)) ^ (maskedAnd >> 1) ^ maskedAnd;
+
+  xorXY = levelA;
+  invertedXor = levelB;
+  invertedOr = levelC;
+  maskedAnd = levelD;
+  levelA = (xorXY & (xorXY >> 2)) ^ (invertedXor & (invertedXor >> 2));
+  levelB = (xorXY & (invertedXor >> 2)) ^ (invertedXor & ((xorXY ^ invertedXor) >> 2));
+  levelC ^= (xorXY & (invertedOr >> 2)) ^ (invertedXor & (maskedAnd >> 2));
+  levelD ^= (invertedXor & (invertedOr >> 2)) ^ ((xorXY ^ invertedXor) & (maskedAnd >> 2));
+
+  xorXY = levelA;
+  invertedXor = levelB;
+  invertedOr = levelC;
+  maskedAnd = levelD;
+  levelA = (xorXY & (xorXY >> 4)) ^ (invertedXor & (invertedXor >> 4));
+  levelB = (xorXY & (invertedXor >> 4)) ^ (invertedXor & ((xorXY ^ invertedXor) >> 4));
+  levelC ^= (xorXY & (invertedOr >> 4)) ^ (invertedXor & (maskedAnd >> 4));
+  levelD ^= (invertedXor & (invertedOr >> 4)) ^ ((xorXY ^ invertedXor) & (maskedAnd >> 4));
+
+  xorXY = levelA;
+  invertedXor = levelB;
+  levelC ^= (xorXY & (invertedOr >> 8)) ^ (invertedXor & (maskedAnd >> 8));
+  levelD ^= (invertedXor & (invertedOr >> 8)) ^ ((xorXY ^ invertedXor) & (maskedAnd >> 8));
 
   xorXY = levelC ^ (levelC >> 1);
   invertedXor = levelD ^ (levelD >> 1);
 
   let interleaved0 = coordX ^ coordY;
-  let interleaved1 = invertedXor | (0xFFFF ^ (interleaved0 | xorXY));
+  let interleaved1 = invertedXor | (0xffff ^ (interleaved0 | xorXY));
 
-  interleaved0 = (interleaved0 | (interleaved0 << 8)) & 0x00FF00FF;
-  interleaved0 = (interleaved0 | (interleaved0 << 4)) & 0x0F0F0F0F;
+  interleaved0 = (interleaved0 | (interleaved0 << 8)) & 0x00ff00ff;
+  interleaved0 = (interleaved0 | (interleaved0 << 4)) & 0x0f0f0f0f;
   interleaved0 = (interleaved0 | (interleaved0 << 2)) & 0x33333333;
   interleaved0 = (interleaved0 | (interleaved0 << 1)) & 0x55555555;
 
-  interleaved1 = (interleaved1 | (interleaved1 << 8)) & 0x00FF00FF;
-  interleaved1 = (interleaved1 | (interleaved1 << 4)) & 0x0F0F0F0F;
+  interleaved1 = (interleaved1 | (interleaved1 << 8)) & 0x00ff00ff;
+  interleaved1 = (interleaved1 | (interleaved1 << 4)) & 0x0f0f0f0f;
   interleaved1 = (interleaved1 | (interleaved1 << 2)) & 0x33333333;
   interleaved1 = (interleaved1 | (interleaved1 << 1)) & 0x55555555;
 
@@ -192,8 +209,8 @@ export class HilbertRTree {
       return;
     }
 
-    const width = (this.maxX - this.minX) || 1;
-    const height = (this.maxY - this.minY) || 1;
+    const width = this.maxX - this.minX || 1;
+    const height = this.maxY - this.minY || 1;
     const hilbertValues = new Uint32Array(this.numItems);
     const hilbertMax = (1 << 16) - 1;
 
@@ -202,14 +219,22 @@ export class HilbertRTree {
       const rectMinY = boxes[boxPosition++];
       const rectMaxX = boxes[boxPosition++];
       const rectMaxY = boxes[boxPosition++];
-      const normalizedX = Math.floor(hilbertMax * ((rectMinX + rectMaxX) / 2 - this.minX) / width);
-      const normalizedY = Math.floor(hilbertMax * ((rectMinY + rectMaxY) / 2 - this.minY) / height);
+      const normalizedX = Math.floor(
+        (hilbertMax * ((rectMinX + rectMaxX) / 2 - this.minX)) / width,
+      );
+      const normalizedY = Math.floor(
+        (hilbertMax * ((rectMinY + rectMaxY) / 2 - this.minY)) / height,
+      );
       hilbertValues[itemIndex] = hilbert(normalizedX, normalizedY);
     }
 
     sortByHilbert(hilbertValues, boxes, this.indices, 0, this.numItems - 1);
 
-    for (let levelIndex = 0, boxPosition = 0; levelIndex < this.levelBounds.length - 1; levelIndex++) {
+    for (
+      let levelIndex = 0, boxPosition = 0;
+      levelIndex < this.levelBounds.length - 1;
+      levelIndex++
+    ) {
       const levelEnd = this.levelBounds[levelIndex];
 
       while (boxPosition < levelEnd) {
diff --git a/packages/react-grab/src/utils/is-decorative-overlay.ts b/packages/react-grab/src/utils/is-decorative-overlay.ts
new file mode 100644
index 000000000..a6b08ca0d
--- /dev/null
+++ b/packages/react-grab/src/utils/is-decorative-overlay.ts
@@ -0,0 +1,18 @@
+const REPLACED_TAGS = new Set([
+  "IMG",
+  "VIDEO",
+  "CANVAS",
+  "SVG",
+  "IFRAME",
+  "INPUT",
+  "TEXTAREA",
+  "SELECT",
+  "OBJECT",
+  "EMBED",
+]);
+
+export const isDecorativeOverlay = (element: Element, computedPosition: string): boolean =>
+  (computedPosition === "absolute" || computedPosition === "sticky") &&
+  !REPLACED_TAGS.has(element.tagName) &&
+  element.childElementCount === 0 &&
+  (element.textContent?.trim().length ?? 0) === 0;
diff --git a/packages/react-grab/src/utils/is-valid-grabbable-element.ts b/packages/react-grab/src/utils/is-valid-grabbable-element.ts
index 780a73b02..c9459a50b 100644
--- a/packages/react-grab/src/utils/is-valid-grabbable-element.ts
+++ b/packages/react-grab/src/utils/is-valid-grabbable-element.ts
@@ -39,19 +39,9 @@ const hasTransparentBackground = (computedStyle: CSSStyleDeclaration): boolean =
   return backgroundColor === "transparent" || backgroundColor === "rgba(0, 0, 0, 0)";
 };
 
-const isFullViewportOverlay = (element: Element, computedStyle: CSSStyleDeclaration): boolean => {
+const isFullViewportOverlay = (computedStyle: CSSStyleDeclaration): boolean => {
   const position = computedStyle.position;
-  if (position !== "fixed" && position !== "absolute") {
-    return false;
-  }
-
-  const coversViewport =
-    element.clientWidth / window.innerWidth >= VIEWPORT_COVERAGE_THRESHOLD &&
-    element.clientHeight / window.innerHeight >= VIEWPORT_COVERAGE_THRESHOLD;
-
-  if (!coversViewport) {
-    return false;
-  }
+  if (position !== "fixed" && position !== "absolute") return false;
 
   if (hasTransparentBackground(computedStyle) || parseFloat(computedStyle.opacity) < 0.1) {
     return true;
@@ -108,7 +98,7 @@ export const isValidGrabbableElement = (element: Element): boolean => {
     if (isDevToolsOverlay(computedStyle)) {
       return false;
     }
-    if (isFullViewportOverlay(element, computedStyle)) {
+    if (isFullViewportOverlay(computedStyle)) {
       return false;
     }
   }