@replohq/sandbox-runtime 0.1.0

package/select-mode/hooks/useParentMessaging.js

@@ -0,0 +1,74 @@
+import { useEffect, useMemo } from "react";
+import { useIframeRpcChannel } from "../../_vendor/replo-utils/react/use-iframe-rpc-channel.mjs";
+import {
+  getSelectModeIframeRpcChannel,
+  getWebsiteBuilderRpc,
+  setSelectModeParentHandlers
+} from "../iframeRpcChannel";
+function useParentMessaging({
+  applyOptimisticUpdate,
+  markCommitted,
+  resolveSessionOverrides,
+  onEnterEditMode,
+  onExitEditMode,
+  onFormatCommand,
+  revertOverride,
+  setDisplayMode,
+  setSelectionType
+}) {
+  useIframeRpcChannel(useMemo(() => getSelectModeIframeRpcChannel(), []));
+  useEffect(() => {
+    setSelectModeParentHandlers({
+      setDisplayMode: ({ displayMode }) => {
+        setDisplayMode(displayMode);
+      },
+      setSelectionType: ({ selectionType }) => {
+        setSelectionType(selectionType);
+      },
+      applyOptimisticUpdate: (message) => {
+        applyOptimisticUpdate?.({
+          editId: message.editId,
+          payload: message.payload,
+          targetSelector: message.targetSelector,
+          targetMode: message.targetMode
+        });
+      },
+      markCommitted: ({ editId, sessionId }) => {
+        markCommitted?.(editId, sessionId);
+      },
+      resolveSessionOverrides: ({ sessionId, outcome }) => {
+        resolveSessionOverrides?.(sessionId, outcome);
+      },
+      revertOverride: ({ editId }) => {
+        revertOverride?.(editId);
+      },
+      enterEditMode: () => {
+        onEnterEditMode?.();
+      },
+      exitEditMode: () => {
+        onExitEditMode?.();
+      },
+      formatCommand: ({ command }) => {
+        onFormatCommand?.(command);
+      }
+    });
+    getWebsiteBuilderRpc()?.iframeReady(void 0);
+    return () => {
+      setSelectModeParentHandlers(null);
+    };
+  }, [
+    applyOptimisticUpdate,
+    markCommitted,
+    resolveSessionOverrides,
+    onEnterEditMode,
+    onExitEditMode,
+    onFormatCommand,
+    revertOverride,
+    setDisplayMode,
+    setSelectionType
+  ]);
+}
+export {
+  useParentMessaging
+};
+//# sourceMappingURL=useParentMessaging.js.map

package/select-mode/hooks/useParentMessaging.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../select-mode/hooks/useParentMessaging.ts"],
+  "sourcesContent": ["import type {\n  DisplayMode,\n  SelectModeFormatCommand,\n  SelectModeOptimisticUpdatePayload,\n  SelectModeSelectionType,\n} from \"schemas/generated/selectMode\";\n\nimport { useEffect, useMemo } from \"react\";\n\nimport { useIframeRpcChannel } from \"replo-utils/react/use-iframe-rpc-channel\";\n\nimport {\n  getSelectModeIframeRpcChannel,\n  getWebsiteBuilderRpc,\n  setSelectModeParentHandlers,\n} from \"../iframeRpcChannel\";\n\n/**\n * Inbound side of the iframe<->parent selectMode bridge.\n *\n * Listens for Website Builder \u2192 canopy methods and applies them locally:\n *  - `setDisplayMode`: switch the iframe between `browse` and `selection`.\n *  - `setSelectionType`: declarative push of the parent's current\n *    selection type. The interesting transition is `* \u2192 \"none\"`, which\n *    tears down any in-iframe selection frame / in-progress drag \u2014 agent-ui\n *    drives it from `agentUiState.selectionType` so panel dismiss / submit\n *    flow through the same path as exiting selection mode entirely. The\n *    regression test in `EditorSelection.spec.tsx` covers the case where\n *    losing this used to lock the iframe out of further selections.\n *\n * Also fires `iframeReady` on mount so the parent knows it's safe to push\n * the initial `setDisplayMode` \u2014 without this handshake the parent would\n * race the iframe's mount and the first message could be lost.\n *\n * @author Kevin O'Connell 2026-04-17\n */\nexport function useParentMessaging({\n  applyOptimisticUpdate,\n  markCommitted,\n  resolveSessionOverrides,\n  onEnterEditMode,\n  onExitEditMode,\n  onFormatCommand,\n  revertOverride,\n  setDisplayMode,\n  setSelectionType,\n}: {\n  applyOptimisticUpdate?: (input: {\n    editId: string;\n    payload: SelectModeOptimisticUpdatePayload;\n    targetSelector: string;\n    targetMode: \"primary\" | \"group\";\n  }) => void;\n  markCommitted?: (editId: string, sessionId: string) => void;\n  resolveSessionOverrides?: (\n    sessionId: string,\n    outcome: \"persisted\" | \"failed\",\n  ) => void;\n  onEnterEditMode?: () => void;\n  onExitEditMode?: () => void;\n  onFormatCommand?: (command: SelectModeFormatCommand) => void;\n  revertOverride?: (editId: string) => void;\n  setDisplayMode: (displayMode: DisplayMode) => void;\n  setSelectionType: (selectionType: SelectModeSelectionType) => void;\n}) {\n  useIframeRpcChannel(useMemo(() => getSelectModeIframeRpcChannel(), []));\n\n  // eslint-disable-next-line replo/no-use-effect -- Legacy effect - may or may not be necessary\n  useEffect(() => {\n    setSelectModeParentHandlers({\n      setDisplayMode: ({ displayMode }) => {\n        setDisplayMode(displayMode);\n      },\n      setSelectionType: ({ selectionType }) => {\n        setSelectionType(selectionType);\n      },\n      applyOptimisticUpdate: (message) => {\n        applyOptimisticUpdate?.({\n          editId: message.editId,\n          payload: message.payload,\n          targetSelector: message.targetSelector,\n          targetMode: message.targetMode,\n        });\n      },\n      markCommitted: ({ editId, sessionId }) => {\n        markCommitted?.(editId, sessionId);\n      },\n      resolveSessionOverrides: ({ sessionId, outcome }) => {\n        resolveSessionOverrides?.(sessionId, outcome);\n      },\n      revertOverride: ({ editId }) => {\n        revertOverride?.(editId);\n      },\n      enterEditMode: () => {\n        onEnterEditMode?.();\n      },\n      exitEditMode: () => {\n        onExitEditMode?.();\n      },\n      formatCommand: ({ command }) => {\n        onFormatCommand?.(command);\n      },\n    });\n    getWebsiteBuilderRpc()?.iframeReady(undefined);\n\n    return () => {\n      setSelectModeParentHandlers(null);\n    };\n  }, [\n    applyOptimisticUpdate,\n    markCommitted,\n    resolveSessionOverrides,\n    onEnterEditMode,\n    onExitEditMode,\n    onFormatCommand,\n    revertOverride,\n    setDisplayMode,\n    setSelectionType,\n  ]);\n}\n"],
+  "mappings": "AAOA,SAAS,WAAW,eAAe;AAEnC,SAAS,2BAA2B;AAEpC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAqBA,SAAS,mBAAmB;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAkBG;AACD,sBAAoB,QAAQ,MAAM,8BAA8B,GAAG,CAAC,CAAC,CAAC;AAGtE,YAAU,MAAM;AACd,gCAA4B;AAAA,MAC1B,gBAAgB,CAAC,EAAE,YAAY,MAAM;AACnC,uBAAe,WAAW;AAAA,MAC5B;AAAA,MACA,kBAAkB,CAAC,EAAE,cAAc,MAAM;AACvC,yBAAiB,aAAa;AAAA,MAChC;AAAA,MACA,uBAAuB,CAAC,YAAY;AAClC,gCAAwB;AAAA,UACtB,QAAQ,QAAQ;AAAA,UAChB,SAAS,QAAQ;AAAA,UACjB,gBAAgB,QAAQ;AAAA,UACxB,YAAY,QAAQ;AAAA,QACtB,CAAC;AAAA,MACH;AAAA,MACA,eAAe,CAAC,EAAE,QAAQ,UAAU,MAAM;AACxC,wBAAgB,QAAQ,SAAS;AAAA,MACnC;AAAA,MACA,yBAAyB,CAAC,EAAE,WAAW,QAAQ,MAAM;AACnD,kCAA0B,WAAW,OAAO;AAAA,MAC9C;AAAA,MACA,gBAAgB,CAAC,EAAE,OAAO,MAAM;AAC9B,yBAAiB,MAAM;AAAA,MACzB;AAAA,MACA,eAAe,MAAM;AACnB,0BAAkB;AAAA,MACpB;AAAA,MACA,cAAc,MAAM;AAClB,yBAAiB;AAAA,MACnB;AAAA,MACA,eAAe,CAAC,EAAE,QAAQ,MAAM;AAC9B,0BAAkB,OAAO;AAAA,MAC3B;AAAA,IACF,CAAC;AACD,yBAAqB,GAAG,YAAY,MAAS;AAE7C,WAAO,MAAM;AACX,kCAA4B,IAAI;AAAA,IAClC;AAAA,EACF,GAAG;AAAA,IACD;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC;AACH;",
+  "names": []
+}

package/select-mode/hooks/useSelectModeController.d.ts

@@ -0,0 +1,8 @@
+import type { DisplayMode, SelectModeSelectionType } from "../../_vendor/schemas/generated/selectMode";
+import type { SelectModeInteractionSession } from "../selectModeSession";
+export declare function useSelectModeController(): {
+    displayMode: DisplayMode;
+    interactionSessionRef: import("react").RefObject<SelectModeInteractionSession>;
+    setDisplayMode: (nextDisplayMode: DisplayMode) => void;
+    setSelectionType: (selectionType: SelectModeSelectionType) => void;
+};

package/select-mode/hooks/useSelectModeController.js

@@ -0,0 +1,46 @@
+import { useCallback, useRef } from "react";
+import { displayModeStore, useDisplayMode } from "../displayModeStore";
+import { getWebsiteBuilderRpc } from "../iframeRpcChannel";
+import { hideSelectionFrame } from "../selectionFrame";
+import { IDLE_SESSION } from "../selectModeSession";
+function resetInteractionSession({
+  interactionSessionRef
+}) {
+  const currentSession = interactionSessionRef.current;
+  if (currentSession.type === "drag" && currentSession.hasExceededThreshold) {
+    getWebsiteBuilderRpc()?.dragRectUpdated({
+      dragRect: null,
+      selectionRects: []
+    });
+  }
+  hideSelectionFrame();
+  interactionSessionRef.current = IDLE_SESSION;
+}
+function useSelectModeController() {
+  const displayMode = useDisplayMode();
+  const interactionSessionRef = useRef(IDLE_SESSION);
+  const setSelectionType = useCallback(
+    (selectionType) => {
+      if (selectionType === "none") {
+        resetInteractionSession({ interactionSessionRef });
+      }
+    },
+    []
+  );
+  const setDisplayMode = useCallback((nextDisplayMode) => {
+    if (displayModeStore.getSnapshot() === "selection" && nextDisplayMode !== "selection") {
+      resetInteractionSession({ interactionSessionRef });
+    }
+    displayModeStore.setDisplayMode(nextDisplayMode);
+  }, []);
+  return {
+    displayMode,
+    interactionSessionRef,
+    setDisplayMode,
+    setSelectionType
+  };
+}
+export {
+  useSelectModeController
+};
+//# sourceMappingURL=useSelectModeController.js.map

package/select-mode/hooks/useSelectModeController.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../select-mode/hooks/useSelectModeController.ts"],
+  "sourcesContent": ["import type {\n  DisplayMode,\n  SelectModeSelectionType,\n} from \"schemas/generated/selectMode\";\nimport type { SelectModeInteractionSession } from \"../selectModeSession\";\n\nimport { useCallback, useRef } from \"react\";\n\nimport { displayModeStore, useDisplayMode } from \"../displayModeStore\";\nimport { getWebsiteBuilderRpc } from \"../iframeRpcChannel\";\nimport { hideSelectionFrame } from \"../selectionFrame\";\nimport { IDLE_SESSION } from \"../selectModeSession\";\n\n/**\n * Tear down any in-progress drag/selection. Re-used by both the\n * display-mode flip-out path (defensive: belt-and-braces with the\n * parent's `setSelectionType(\"none\")` push) and by the explicit\n * `setSelectionType(\"none\")` path below.\n */\nfunction resetInteractionSession({\n  interactionSessionRef,\n}: {\n  interactionSessionRef: React.MutableRefObject<SelectModeInteractionSession>;\n}) {\n  const currentSession = interactionSessionRef.current;\n  if (currentSession.type === \"drag\" && currentSession.hasExceededThreshold) {\n    getWebsiteBuilderRpc()?.dragRectUpdated({\n      dragRect: null,\n      selectionRects: [],\n    });\n  }\n  hideSelectionFrame();\n  interactionSessionRef.current = IDLE_SESSION;\n}\n\nexport function useSelectModeController() {\n  // Display mode lives in a module singleton so the sibling `LinkInterceptor`\n  // can read it (and stand down during selection) without a shared provider.\n  const displayMode = useDisplayMode();\n  const interactionSessionRef =\n    useRef<SelectModeInteractionSession>(IDLE_SESSION);\n\n  // The parent is authoritative for \"is there a current selection?\". Canopy\n  // originates selections via pointer events, posts them up, agent-ui\n  // mirrors `selection.type` into `agentUiState`, and the result is pushed\n  // back down here. When the parent says `none` (panel dismissed / submit /\n  // exit selection mode) we tear down the in-iframe frame; the matching\n  // commit-side paths are in `useSelectionInteractions`.\n  const setSelectionType = useCallback(\n    (selectionType: SelectModeSelectionType) => {\n      if (selectionType === \"none\") {\n        resetInteractionSession({ interactionSessionRef });\n      }\n    },\n    [],\n  );\n\n  const setDisplayMode = useCallback((nextDisplayMode: DisplayMode) => {\n    if (\n      displayModeStore.getSnapshot() === \"selection\" &&\n      nextDisplayMode !== \"selection\"\n    ) {\n      resetInteractionSession({ interactionSessionRef });\n    }\n\n    displayModeStore.setDisplayMode(nextDisplayMode);\n  }, []);\n\n  return {\n    displayMode,\n    interactionSessionRef,\n    setDisplayMode,\n    setSelectionType,\n  };\n}\n"],
+  "mappings": "AAMA,SAAS,aAAa,cAAc;AAEpC,SAAS,kBAAkB,sBAAsB;AACjD,SAAS,4BAA4B;AACrC,SAAS,0BAA0B;AACnC,SAAS,oBAAoB;AAQ7B,SAAS,wBAAwB;AAAA,EAC/B;AACF,GAEG;AACD,QAAM,iBAAiB,sBAAsB;AAC7C,MAAI,eAAe,SAAS,UAAU,eAAe,sBAAsB;AACzE,yBAAqB,GAAG,gBAAgB;AAAA,MACtC,UAAU;AAAA,MACV,gBAAgB,CAAC;AAAA,IACnB,CAAC;AAAA,EACH;AACA,qBAAmB;AACnB,wBAAsB,UAAU;AAClC;AAEO,SAAS,0BAA0B;AAGxC,QAAM,cAAc,eAAe;AACnC,QAAM,wBACJ,OAAqC,YAAY;AAQnD,QAAM,mBAAmB;AAAA,IACvB,CAAC,kBAA2C;AAC1C,UAAI,kBAAkB,QAAQ;AAC5B,gCAAwB,EAAE,sBAAsB,CAAC;AAAA,MACnD;AAAA,IACF;AAAA,IACA,CAAC;AAAA,EACH;AAEA,QAAM,iBAAiB,YAAY,CAAC,oBAAiC;AACnE,QACE,iBAAiB,YAAY,MAAM,eACnC,oBAAoB,aACpB;AACA,8BAAwB,EAAE,sBAAsB,CAAC;AAAA,IACnD;AAEA,qBAAiB,eAAe,eAAe;AAAA,EACjD,GAAG,CAAC,CAAC;AAEL,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;",
+  "names": []
+}

package/select-mode/hooks/useSelectionHover.d.ts

@@ -0,0 +1,22 @@
+import type { MutableRefObject } from "react";
+import type { DisplayMode } from "../../_vendor/schemas/generated/selectMode";
+import type { SelectModeInteractionSession } from "../selectModeSession";
+/**
+ * Tracks whichever element is under the user's pointer while in `selection`
+ * mode and reports its bounding rect to the parent so the parent can render
+ * the hover overlay.
+ *
+ * Two behaviors worth knowing about:
+ *  - During an active drag we suppress hover updates; the drag overlay is
+ *    the only highlight we want visible.
+ *  - On scroll/wheel/resize we re-run the hover lookup from the last known
+ *    pointer position (we use rAF to coalesce). Without this, scrolling
+ *    over an already-hovered element wouldn't update the highlight to the
+ *    new element actually under the cursor.
+ *
+ * @author Kevin O'Connell 2026-04-17
+ */
+export declare function useSelectionHover({ displayMode, interactionSessionRef, }: {
+    displayMode: DisplayMode;
+    interactionSessionRef: MutableRefObject<SelectModeInteractionSession>;
+}): void;

package/select-mode/hooks/useSelectionHover.js

@@ -0,0 +1,110 @@
+import { useEffect } from "react";
+import { getNearestSelectableElement } from "../descriptor/elementDescriptor";
+import { getWebsiteBuilderRpc } from "../iframeRpcChannel";
+import { getElementBoundingRect } from "../interactions/selectionGeometry";
+function useSelectionHover({
+  displayMode,
+  interactionSessionRef
+}) {
+  useEffect(() => {
+    if (displayMode !== "selection") {
+      return;
+    }
+    let hoverSyncAnimationFrameId = null;
+    let lastPointerClientPosition = null;
+    const postHoveredElement = (element) => {
+      getWebsiteBuilderRpc()?.hoverElement({
+        rect: element ? getElementBoundingRect(element) : null
+      });
+    };
+    const syncCurrentHover = (pointerClientPosition = lastPointerClientPosition) => {
+      let hoveredElement = null;
+      if (pointerClientPosition) {
+        const isPointerWithinViewport = pointerClientPosition.x >= 0 && pointerClientPosition.y >= 0 && pointerClientPosition.x <= window.innerWidth && pointerClientPosition.y <= window.innerHeight;
+        if (isPointerWithinViewport) {
+          hoveredElement = document.elementFromPoint(
+            pointerClientPosition.x,
+            pointerClientPosition.y
+          );
+        }
+      }
+      if (!hoveredElement) {
+        const hoveredElementStack = document.querySelectorAll(":hover");
+        hoveredElement = hoveredElementStack[hoveredElementStack.length - 1] ?? null;
+      }
+      postHoveredElement(
+        hoveredElement ? getNearestSelectableElement(hoveredElement) : null
+      );
+    };
+    const scheduleHoverSync = () => {
+      if (interactionSessionRef.current.type === "drag" || hoverSyncAnimationFrameId !== null) {
+        return;
+      }
+      hoverSyncAnimationFrameId = requestAnimationFrame(() => {
+        hoverSyncAnimationFrameId = null;
+        syncCurrentHover();
+      });
+    };
+    const handlePointerMove = (event) => {
+      lastPointerClientPosition = {
+        x: event.clientX,
+        y: event.clientY
+      };
+      if (interactionSessionRef.current.type === "drag") {
+        return;
+      }
+      syncCurrentHover(lastPointerClientPosition);
+    };
+    const handlePointerOver = (event) => {
+      lastPointerClientPosition = {
+        x: event.clientX,
+        y: event.clientY
+      };
+      if (interactionSessionRef.current.type === "drag") {
+        return;
+      }
+      syncCurrentHover(lastPointerClientPosition);
+    };
+    const handlePointerOut = (event) => {
+      if (interactionSessionRef.current.type === "drag") {
+        return;
+      }
+      const nextRelatedTarget = event.relatedTarget;
+      if (nextRelatedTarget instanceof Node && document.contains(nextRelatedTarget)) {
+        return;
+      }
+      lastPointerClientPosition = null;
+      postHoveredElement(null);
+    };
+    const handleViewportChange = () => {
+      scheduleHoverSync();
+    };
+    syncCurrentHover();
+    document.addEventListener("pointermove", handlePointerMove, true);
+    document.addEventListener("pointerover", handlePointerOver, true);
+    document.addEventListener("pointerout", handlePointerOut, true);
+    document.addEventListener("scroll", handleViewportChange, true);
+    document.addEventListener("wheel", handleViewportChange, {
+      capture: true,
+      passive: true
+    });
+    window.addEventListener("resize", handleViewportChange);
+    return () => {
+      if (hoverSyncAnimationFrameId !== null) {
+        cancelAnimationFrame(hoverSyncAnimationFrameId);
+      }
+      document.removeEventListener("pointermove", handlePointerMove, true);
+      document.removeEventListener("pointerover", handlePointerOver, true);
+      document.removeEventListener("pointerout", handlePointerOut, true);
+      document.removeEventListener("scroll", handleViewportChange, true);
+      document.removeEventListener("wheel", handleViewportChange, {
+        capture: true
+      });
+      window.removeEventListener("resize", handleViewportChange);
+    };
+  }, [displayMode, interactionSessionRef]);
+}
+export {
+  useSelectionHover
+};
+//# sourceMappingURL=useSelectionHover.js.map

package/select-mode/hooks/useSelectionHover.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../select-mode/hooks/useSelectionHover.ts"],
+  "sourcesContent": ["import type { MutableRefObject } from \"react\";\nimport type { DisplayMode } from \"schemas/generated/selectMode\";\nimport type { SelectModeInteractionSession } from \"../selectModeSession\";\n\nimport { useEffect } from \"react\";\n\nimport { getNearestSelectableElement } from \"../descriptor/elementDescriptor\";\nimport { getWebsiteBuilderRpc } from \"../iframeRpcChannel\";\nimport { getElementBoundingRect } from \"../interactions/selectionGeometry\";\n\n/**\n * Tracks whichever element is under the user's pointer while in `selection`\n * mode and reports its bounding rect to the parent so the parent can render\n * the hover overlay.\n *\n * Two behaviors worth knowing about:\n *  - During an active drag we suppress hover updates; the drag overlay is\n *    the only highlight we want visible.\n *  - On scroll/wheel/resize we re-run the hover lookup from the last known\n *    pointer position (we use rAF to coalesce). Without this, scrolling\n *    over an already-hovered element wouldn't update the highlight to the\n *    new element actually under the cursor.\n *\n * @author Kevin O'Connell 2026-04-17\n */\nexport function useSelectionHover({\n  displayMode,\n  interactionSessionRef,\n}: {\n  displayMode: DisplayMode;\n  interactionSessionRef: MutableRefObject<SelectModeInteractionSession>;\n}) {\n  // eslint-disable-next-line replo/no-use-effect -- Legacy effect - may or may not be necessary\n  useEffect(() => {\n    if (displayMode !== \"selection\") {\n      return;\n    }\n\n    let hoverSyncAnimationFrameId: number | null = null;\n    let lastPointerClientPosition: { x: number; y: number } | null = null;\n\n    // NOTE (Kevin O'Connell, 2026-04-20): `null` is the deliberate \"no element\n    // under pointer / pointer left viewport\" signal \u2014 it produces a\n    // clear-hover notification to the parent, not an error.\n    const postHoveredElement = (element: Element | null) => {\n      // The hover overlay only needs the element rect \u2014 serializing the full\n      // styled outerHTML on every pointer move would be wasteful and never\n      // consumed by the parent.\n      getWebsiteBuilderRpc()?.hoverElement({\n        rect: element ? getElementBoundingRect(element) : null,\n      });\n    };\n\n    const syncCurrentHover = (\n      pointerClientPosition = lastPointerClientPosition,\n    ) => {\n      let hoveredElement: Element | null = null;\n\n      if (pointerClientPosition) {\n        const isPointerWithinViewport =\n          pointerClientPosition.x >= 0 &&\n          pointerClientPosition.y >= 0 &&\n          pointerClientPosition.x <= window.innerWidth &&\n          pointerClientPosition.y <= window.innerHeight;\n\n        if (isPointerWithinViewport) {\n          hoveredElement = document.elementFromPoint(\n            pointerClientPosition.x,\n            pointerClientPosition.y,\n          );\n        }\n      }\n\n      if (!hoveredElement) {\n        const hoveredElementStack = document.querySelectorAll(\":hover\");\n        hoveredElement =\n          hoveredElementStack[hoveredElementStack.length - 1] ?? null;\n      }\n\n      postHoveredElement(\n        hoveredElement ? getNearestSelectableElement(hoveredElement) : null,\n      );\n    };\n\n    const scheduleHoverSync = () => {\n      if (\n        interactionSessionRef.current.type === \"drag\" ||\n        hoverSyncAnimationFrameId !== null\n      ) {\n        return;\n      }\n\n      hoverSyncAnimationFrameId = requestAnimationFrame(() => {\n        hoverSyncAnimationFrameId = null;\n        syncCurrentHover();\n      });\n    };\n\n    const handlePointerMove = (event: PointerEvent) => {\n      lastPointerClientPosition = {\n        x: event.clientX,\n        y: event.clientY,\n      };\n\n      if (interactionSessionRef.current.type === \"drag\") {\n        return;\n      }\n\n      syncCurrentHover(lastPointerClientPosition);\n    };\n\n    // Catches the \"cursor is already inside the iframe when select mode\n    // toggles on\" case \u2014 pointermove only fires on motion, so a stationary\n    // cursor would otherwise wait forever for the first hover sync.\n    const handlePointerOver = (event: PointerEvent) => {\n      lastPointerClientPosition = {\n        x: event.clientX,\n        y: event.clientY,\n      };\n\n      if (interactionSessionRef.current.type === \"drag\") {\n        return;\n      }\n\n      syncCurrentHover(lastPointerClientPosition);\n    };\n\n    const handlePointerOut = (event: PointerEvent) => {\n      if (interactionSessionRef.current.type === \"drag\") {\n        return;\n      }\n\n      const nextRelatedTarget = event.relatedTarget;\n      if (\n        nextRelatedTarget instanceof Node &&\n        document.contains(nextRelatedTarget)\n      ) {\n        return;\n      }\n\n      lastPointerClientPosition = null;\n      postHoveredElement(null);\n    };\n\n    const handleViewportChange = () => {\n      scheduleHoverSync();\n    };\n\n    syncCurrentHover();\n    document.addEventListener(\"pointermove\", handlePointerMove, true);\n    document.addEventListener(\"pointerover\", handlePointerOver, true);\n    document.addEventListener(\"pointerout\", handlePointerOut, true);\n    document.addEventListener(\"scroll\", handleViewportChange, true);\n    document.addEventListener(\"wheel\", handleViewportChange, {\n      capture: true,\n      passive: true,\n    });\n    window.addEventListener(\"resize\", handleViewportChange);\n\n    return () => {\n      if (hoverSyncAnimationFrameId !== null) {\n        cancelAnimationFrame(hoverSyncAnimationFrameId);\n      }\n      document.removeEventListener(\"pointermove\", handlePointerMove, true);\n      document.removeEventListener(\"pointerover\", handlePointerOver, true);\n      document.removeEventListener(\"pointerout\", handlePointerOut, true);\n      document.removeEventListener(\"scroll\", handleViewportChange, true);\n      document.removeEventListener(\"wheel\", handleViewportChange, {\n        capture: true,\n      });\n      window.removeEventListener(\"resize\", handleViewportChange);\n    };\n  }, [displayMode, interactionSessionRef]);\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/select-mode/hooks/useSelectionInteractions.d.ts

@@ -0,0 +1,37 @@
+import type { MutableRefObject } from "react";
+import type { DisplayMode, SelectableData } from "../../_vendor/schemas/generated/selectMode";
+import type { SelectModeInteractionSession } from "../selectModeSession";
+/**
+ * Owns the iframe-side pointer interactions that drive selection:
+ *
+ *  - On `pointerdown` we open a `drag` session (storing both client + page
+ *    coords plus the current scroll offset). We don't yet know if this will
+ *    become a click or an actual drag.
+ *  - On `pointermove` we update the drag rect and post `DRAG_RECT_UPDATED`
+ *    to the parent so the live drag rectangle can render. We only flip
+ *    `hasExceededThreshold` once the rect grows past 6×6 px so that a tiny
+ *    accidental drag still resolves as a click.
+ *  - On `pointerup` we either:
+ *      - resolve as an `ELEMENT_SELECTED` (single click / sub-threshold drag)
+ *      - resolve as an `AREA_SELECTED` (drag past threshold), filtering the
+ *        candidates snapshotted at drag start against the final rectangle to
+ *        enumerate which descendants the user enclosed.
+ *  - During an active drag a `requestAnimationFrame` loop keeps the rect in
+ *    sync with the page scroll so the rectangle visually "sticks" to the
+ *    page rather than the viewport.
+ *
+ * We capture-listen and `preventDefault`/`stopPropagation` clicks so the
+ * underlying page can't navigate or trigger handlers while the user is
+ * working in selection mode.
+ *
+ * @author Kevin O'Connell 2026-04-17
+ */
+export declare function useSelectionInteractions({ displayMode, editingElementRef, interactionSessionRef, onBeginEditing, }: {
+    displayMode: DisplayMode;
+    editingElementRef?: MutableRefObject<HTMLElement | null>;
+    interactionSessionRef: MutableRefObject<SelectModeInteractionSession>;
+    onBeginEditing: (args: {
+        element: Element;
+        descriptorPromise: Promise<SelectableData>;
+    }) => void;
+}): void;