nudge-ui 0.2.0

package/dist/inspector/overlay/InspectorOverlay.js

@@ -0,0 +1,328 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { useInspectorOpen } from "../shell/openStore.js";
+import { getSelectedElements, useSelectedElement, useSelectedElements } from "../selection/selectionStore.js";
+import { installElementSelector } from "./elementSelector.js";
+import { getMarginFills, getMarginGuides, readBorderWidths, readMargins, toRect, } from "./overlayGeometry.js";
+import { observeSelectedGeometry } from "./selectedGeometry.js";
+import { getDropLocationAtPoint, moveElement } from "./structuralGestures.js";
+import { resolveSelectionFromElement } from "../selection/resolveSelection.js";
+import { setSelectedElement } from "../selection/selectionStore.js";
+import { installInteractionStyles } from "./interactionStyles.js";
+import { clearDropGuide, showDropGuide, useDropGuide } from "./dropGuide.js";
+import { DropGuideOverlay } from "./DropGuideOverlay.js";
+import { createFrameThrottle } from "./frameThrottle.js";
+import { getMeasurementGeometry } from "./measurementGeometry.js";
+import { MeasurementGuideOverlay } from "./MeasurementGuideOverlay.js";
+import { resolveSelectionTarget, selectionTargetMode } from "../selection/selectionTarget.js";
+import { isInlineTextEditingActive, useInlineTextSession } from "../inline-text/inlineTextEditor.js";
+import { EMPTY_TEXT_PROJECTION_ATTR } from "../projection/textProjection.js";
+export { getMarginFills, getMarginGuides, } from "./overlayGeometry.js";
+function overlayStyle(rect) {
+    return {
+        position: "fixed",
+        left: rect.left,
+        top: rect.top,
+        width: rect.width,
+        height: rect.height,
+        pointerEvents: "none",
+    };
+}
+export function InspectorOverlay({ host }) {
+    const open = useInspectorOpen();
+    const selected = useSelectedElement();
+    const selectedElements = useSelectedElements();
+    const inlineTextSession = useInlineTextSession();
+    const [hoverRect, setHoverRect] = useState(null);
+    const [hoverMargins, setHoverMargins] = useState(null);
+    const [hoverBorders, setHoverBorders] = useState(null);
+    const [selectedRects, setSelectedRects] = useState([]);
+    const [selectedBorders, setSelectedBorders] = useState(null);
+    const [optionDown, setOptionDown] = useState(false);
+    const [pointerOverPage, setPointerOverPage] = useState(false);
+    const dropGuide = useDropGuide("inspect");
+    const hoverElRef = useRef(null);
+    const isDraggingRef = useRef(false);
+    const rafRef = useRef(0);
+    useEffect(() => {
+        if (!open) {
+            setHoverRect(null);
+            setHoverMargins(null);
+            setHoverBorders(null);
+            hoverElRef.current = null;
+            setPointerOverPage(false);
+            return;
+        }
+        let observedHover = null;
+        const ResizeObserverCtor = window.ResizeObserver;
+        const hoverResizeObserver = ResizeObserverCtor ? new ResizeObserverCtor(scheduleHoverRecalc) : null;
+        function clearHover() {
+            hoverElRef.current = null;
+            setHoverRect(null);
+            setHoverMargins(null);
+            setHoverBorders(null);
+            hoverResizeObserver?.disconnect();
+            observedHover = null;
+        }
+        function observeHover(el) {
+            if (observedHover === el)
+                return;
+            hoverResizeObserver?.disconnect();
+            hoverResizeObserver?.observe(el);
+            observedHover = el;
+        }
+        function recalcHover() {
+            if (isDraggingRef.current)
+                return;
+            const el = hoverElRef.current;
+            if (!el) {
+                setHoverRect(null);
+                setHoverMargins(null);
+                setHoverBorders(null);
+                return;
+            }
+            setHoverRect(toRect(el.getBoundingClientRect()));
+            setHoverMargins(readMargins(el));
+            setHoverBorders(readBorderWidths(el));
+        }
+        function scheduleHoverRecalc() {
+            if (isDraggingRef.current)
+                return;
+            cancelAnimationFrame(rafRef.current);
+            rafRef.current = requestAnimationFrame(recalcHover);
+        }
+        function onMouseOver(e) {
+            if (isDraggingRef.current)
+                return;
+            const target = e.target;
+            if (!(target instanceof HTMLElement))
+                return;
+            if (host === target || host.contains(target)) {
+                setPointerOverPage(false);
+                clearHover();
+                return;
+            }
+            setPointerOverPage(true);
+            const el = resolveSelectionTarget(target, selectionTargetMode(e));
+            if (!el) {
+                clearHover();
+                return;
+            }
+            hoverElRef.current = el;
+            observeHover(el);
+            scheduleHoverRecalc();
+        }
+        function onMouseOut(e) {
+            if (isDraggingRef.current)
+                return;
+            const related = e.relatedTarget;
+            if (!related || !(related instanceof Node)) {
+                setPointerOverPage(false);
+                clearHover();
+                return;
+            }
+            if (host === related || host.contains(related)) {
+                setPointerOverPage(false);
+                clearHover();
+                return;
+            }
+            const nearest = resolveSelectionTarget(related, selectionTargetMode(e));
+            if (nearest !== hoverElRef.current)
+                clearHover();
+        }
+        document.addEventListener("mouseover", onMouseOver, true);
+        document.addEventListener("mouseout", onMouseOut, true);
+        window.addEventListener("resize", scheduleHoverRecalc);
+        window.addEventListener("scroll", scheduleHoverRecalc, true);
+        const removeClickCapture = installElementSelector(host);
+        return () => {
+            cancelAnimationFrame(rafRef.current);
+            document.removeEventListener("mouseover", onMouseOver, true);
+            document.removeEventListener("mouseout", onMouseOut, true);
+            removeClickCapture();
+            window.removeEventListener("resize", scheduleHoverRecalc);
+            window.removeEventListener("scroll", scheduleHoverRecalc, true);
+            hoverResizeObserver?.disconnect();
+        };
+    }, [open, host]);
+    useEffect(() => {
+        let raf = 0;
+        function recalc() {
+            setSelectedRects(selectedElements.map((candidate) => toRect(candidate.domElement.getBoundingClientRect())));
+            if (selected) {
+                setSelectedBorders(readBorderWidths(selected.domElement));
+            }
+            else {
+                setSelectedBorders(null);
+            }
+        }
+        function schedule() {
+            cancelAnimationFrame(raf);
+            raf = requestAnimationFrame(recalc);
+        }
+        recalc();
+        const stopObserving = selectedElements.map((candidate) => observeSelectedGeometry(candidate.domElement, schedule));
+        return () => {
+            cancelAnimationFrame(raf);
+            stopObserving.forEach((stop) => stop());
+        };
+    }, [selectedElements]);
+    useEffect(() => {
+        if (!open) {
+            setOptionDown(false);
+            return;
+        }
+        function updateOptionState(event) {
+            setOptionDown(event.altKey);
+        }
+        function clearOptionState() {
+            setOptionDown(false);
+        }
+        window.addEventListener("keydown", updateOptionState);
+        window.addEventListener("keyup", updateOptionState);
+        window.addEventListener("blur", clearOptionState);
+        return () => {
+            window.removeEventListener("keydown", updateOptionState);
+            window.removeEventListener("keyup", updateOptionState);
+            window.removeEventListener("blur", clearOptionState);
+        };
+    }, [open]);
+    useEffect(() => {
+        if (!open)
+            return;
+        const removeInteractionStyles = installInteractionStyles();
+        let candidate = null;
+        let dragging = false;
+        let start = null;
+        function updateGuide(point) {
+            if (!candidate)
+                return;
+            const drop = getDropLocationAtPoint(document, candidate, point.x, point.y);
+            if (drop)
+                showDropGuide("inspect", document, drop);
+            else
+                clearDropGuide("inspect");
+        }
+        const guideUpdate = createFrameThrottle(updateGuide);
+        function clear() {
+            guideUpdate.cancel();
+            isDraggingRef.current = false;
+            candidate = null;
+            dragging = false;
+            start = null;
+            clearDropGuide("inspect");
+        }
+        function onPointerDown(event) {
+            if (isInlineTextEditingActive())
+                return;
+            if (getSelectedElements().length > 1)
+                return;
+            if (event.button !== 0 || !(event.target instanceof HTMLElement))
+                return;
+            if (host === event.target || host.contains(event.target))
+                return;
+            if (event.target.closest(`[${EMPTY_TEXT_PROJECTION_ATTR}]`))
+                return;
+            const target = resolveSelectionTarget(event.target, selectionTargetMode(event));
+            if (!target)
+                return;
+            candidate = target;
+            start = { x: event.clientX, y: event.clientY };
+        }
+        function onPointerMove(event) {
+            if (isInlineTextEditingActive())
+                return;
+            if (!candidate || !start)
+                return;
+            if (!dragging && Math.hypot(event.clientX - start.x, event.clientY - start.y) < 6)
+                return;
+            event.preventDefault();
+            const point = { x: event.clientX, y: event.clientY };
+            if (!dragging) {
+                dragging = true;
+                isDraggingRef.current = true;
+                hoverElRef.current = null;
+                setHoverRect(null);
+                setHoverMargins(null);
+                const selected = resolveSelectionFromElement(candidate);
+                if (selected)
+                    setSelectedElement(selected);
+                updateGuide(point);
+                return;
+            }
+            guideUpdate.schedule(point);
+        }
+        function onPointerUp(event) {
+            if (isInlineTextEditingActive())
+                return;
+            if (!candidate || !dragging) {
+                clear();
+                return;
+            }
+            event.preventDefault();
+            const drop = getDropLocationAtPoint(document, candidate, event.clientX, event.clientY);
+            if (drop)
+                moveElement(candidate, drop);
+            const selected = resolveSelectionFromElement(candidate);
+            if (selected)
+                setSelectedElement(selected);
+            clear();
+        }
+        document.addEventListener("mousedown", onPointerDown, true);
+        document.addEventListener("mousemove", onPointerMove, true);
+        document.addEventListener("mouseup", onPointerUp, true);
+        return () => {
+            document.removeEventListener("mousedown", onPointerDown, true);
+            document.removeEventListener("mousemove", onPointerMove, true);
+            document.removeEventListener("mouseup", onPointerUp, true);
+            guideUpdate.cancel();
+            isDraggingRef.current = false;
+            clearDropGuide("inspect");
+            removeInteractionStyles();
+        };
+    }, [open, host]);
+    const selectedGeometry = selectedElements.flatMap((candidate, index) => {
+        const rect = selectedRects[index];
+        return rect ? [{ element: candidate, rect }] : [];
+    });
+    const selectedPrimaryIndex = selectedElements.findIndex((candidate) => candidate.domElement === selected?.domElement);
+    const selectedRect = selectedRects[selectedPrimaryIndex >= 0 ? selectedPrimaryIndex : 0] ?? null;
+    const hoverStyle = hoverRect ? overlayStyle(hoverRect) : { display: "none" };
+    const hoverMarginGuides = hoverRect && hoverMargins
+        ? getMarginGuides(hoverRect, hoverMargins)
+        : [];
+    const hoverMarginFills = hoverRect && hoverMargins
+        ? getMarginFills(hoverRect, hoverMargins)
+        : [];
+    const showGuideOverlay = open
+        && selectedElements.length === 1
+        && optionDown
+        && pointerOverPage
+        && selectedRect;
+    const showMeasurement = showGuideOverlay
+        && hoverRect
+        && hoverElRef.current !== selected?.domElement;
+    const measurement = showMeasurement && selectedRect && hoverRect
+        ? getMeasurementGeometry(selectedRect, hoverRect, {
+            selectedBorders: selectedBorders ?? undefined,
+            hoveredBorders: hoverBorders ?? undefined,
+        })
+        : null;
+    return (_jsxs(_Fragment, { children: [showGuideOverlay && selectedRect ? (_jsx(MeasurementGuideOverlay, { selectedRect: selectedRect, segments: measurement?.segments ?? [] })) : null, open && hoverRect ? (_jsxs(_Fragment, { children: [hoverMarginFills.map((fill) => (_jsx("div", { className: "hover-margin-fill", "data-side": fill.side, style: {
+                            position: "fixed",
+                            left: fill.left,
+                            top: fill.top,
+                            width: fill.width,
+                            height: fill.height,
+                            pointerEvents: "none",
+                        }, "aria-hidden": "true" }, fill.side))), _jsx("div", { className: "hover-outline", style: hoverStyle, "aria-hidden": "true" }), hoverMarginGuides.map((guide) => (_jsx("div", { className: "hover-margin", "data-axis": guide.axis, "data-distance": guide.distance, "data-side": guide.side, style: {
+                            position: "fixed",
+                            left: guide.left,
+                            top: guide.top,
+                            width: guide.width,
+                            height: guide.height,
+                            pointerEvents: "none",
+                        }, "aria-hidden": "true" }, guide.side)))] })) : null, open && !inlineTextSession ? selectedGeometry.map(({ element, rect }, index) => (_jsx("div", { className: "selected-outline", "data-test": "selected-outline", "data-selected-cid": element.cid, "data-selected-index": index, "data-selected-src": element.src, style: overlayStyle(rect), "aria-hidden": "true" }, `${element.domElement.getAttribute("data-cid") ?? "element"}-${index}`))) : null, open && selectedElements.length === 1 ? _jsx(DropGuideOverlay, { guide: dropGuide?.document === document
+                    ? { orientation: dropGuide.orientation, line: dropGuide.line, target: dropGuide.target }
+                    : null, lineClassName: "dom-drop-line", lineTestId: "dom-drop-line", targetClassName: "dom-drop-target", targetTestId: "dom-drop-target" }) : null] }));
+}

package/dist/inspector/overlay/MeasurementGuideOverlay.d.ts

@@ -0,0 +1,19 @@
+import { type ReactElement } from "react";
+import type { Rect } from "./overlayGeometry.js";
+import type { MeasurementSegment } from "./measurementGeometry.js";
+interface MeasurementGuideOverlayProps {
+    /** The selected element in the overlay's screen coordinate system. */
+    selectedRect: Rect;
+    /** The viewport that alignment guides should span. */
+    guideViewport?: Rect;
+    /** Measurement geometry in the overlay's screen coordinate system. */
+    segments: MeasurementSegment[];
+    testId?: string;
+}
+/**
+ * Renders measurement geometry over a viewport. The Inspect surface passes
+ * browser coordinates directly; Canvas projects iframe-local coordinates into
+ * the same screen coordinate system before rendering here.
+ */
+export declare function MeasurementGuideOverlay({ selectedRect, guideViewport, segments, testId, }: MeasurementGuideOverlayProps): ReactElement;
+export {};

package/dist/inspector/overlay/MeasurementGuideOverlay.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+/**
+ * Renders measurement geometry over a viewport. The Inspect surface passes
+ * browser coordinates directly; Canvas projects iframe-local coordinates into
+ * the same screen coordinate system before rendering here.
+ */
+export function MeasurementGuideOverlay({ selectedRect, guideViewport, segments, testId = "measurement-overlay", }) {
+    const [windowViewport, setWindowViewport] = useState(() => ({
+        width: window.innerWidth,
+        height: window.innerHeight,
+    }));
+    useEffect(() => {
+        function updateViewport() {
+            setWindowViewport({ width: window.innerWidth, height: window.innerHeight });
+        }
+        window.addEventListener("resize", updateViewport);
+        return () => window.removeEventListener("resize", updateViewport);
+    }, []);
+    const resolvedGuideViewport = guideViewport ?? {
+        left: 0,
+        top: 0,
+        width: windowViewport.width,
+        height: windowViewport.height,
+    };
+    const guideRight = resolvedGuideViewport.left + resolvedGuideViewport.width;
+    const guideBottom = resolvedGuideViewport.top + resolvedGuideViewport.height;
+    const selectedRight = selectedRect.left + selectedRect.width;
+    const selectedBottom = selectedRect.top + selectedRect.height;
+    return (_jsxs("svg", { className: "measurement-overlay", "data-test": testId, width: windowViewport.width, height: windowViewport.height, viewBox: `0 0 ${windowViewport.width} ${windowViewport.height}`, "aria-hidden": "true", children: [_jsx("line", { className: "alignment-guide", x1: resolvedGuideViewport.left, y1: selectedRect.top, x2: guideRight, y2: selectedRect.top }), _jsx("line", { className: "alignment-guide", x1: resolvedGuideViewport.left, y1: selectedBottom, x2: guideRight, y2: selectedBottom }), _jsx("line", { className: "alignment-guide", x1: selectedRect.left, y1: resolvedGuideViewport.top, x2: selectedRect.left, y2: guideBottom }), _jsx("line", { className: "alignment-guide", x1: selectedRight, y1: resolvedGuideViewport.top, x2: selectedRight, y2: guideBottom }), segments.map((segment) => {
+                const labelX = (segment.from.x + segment.to.x) / 2;
+                const labelY = (segment.from.y + segment.to.y) / 2;
+                const isHorizontal = segment.axis === "horizontal";
+                const labelText = segment.distance === undefined ? null : `${Math.round(segment.distance)}px`;
+                const labelWidth = labelText ? labelText.length * 7 + 10 : 0;
+                const textX = isHorizontal ? labelX : labelX + 6;
+                const textY = isHorizontal ? labelY - 6 : labelY + 4;
+                return (_jsxs("g", { children: [_jsx("line", { className: segment.kind === "projection" ? "measurement-projection" : "measurement-ruler", "data-test": segment.kind === "projection" ? "measurement-projection" : "measurement-ruler", "data-segment-id": segment.id, "data-axis": segment.axis, x1: segment.from.x, y1: segment.from.y, x2: segment.to.x, y2: segment.to.y }), labelText ? (_jsxs(_Fragment, { children: [_jsx("rect", { className: "measurement-label-chip", "data-test": "measurement-label-chip", x: isHorizontal ? textX - labelWidth / 2 : textX - 4, y: textY - 12, width: labelWidth, height: "16", rx: "2" }), _jsx("text", { className: "measurement-label", "data-test": "measurement-label", x: textX, y: textY, textAnchor: isHorizontal ? "middle" : "start", children: labelText })] })) : null] }, segment.id));
+            })] }));
+}

package/dist/inspector/overlay/clickPolicy.d.ts

@@ -0,0 +1,7 @@
+export type ClickModifiers = Pick<MouseEvent, "ctrlKey" | "metaKey" | "shiftKey">;
+/** Command/Ctrl-click selects the deepest tracked element unless Shift is held. */
+export declare function isDeepSelectionClick(event: ClickModifiers): boolean;
+/** Command/Ctrl+Shift-click intentionally lets the application receive its click. */
+export declare function isApplicationActivationClick(event: ClickModifiers): boolean;
+/** Prevent an inspected application click from reaching the host application. */
+export declare function blockApplicationClick(event: MouseEvent): void;

package/dist/inspector/overlay/clickPolicy.js

@@ -0,0 +1,13 @@
+/** Command/Ctrl-click selects the deepest tracked element unless Shift is held. */
+export function isDeepSelectionClick(event) {
+    return (event.ctrlKey || event.metaKey) && !event.shiftKey;
+}
+/** Command/Ctrl+Shift-click intentionally lets the application receive its click. */
+export function isApplicationActivationClick(event) {
+    return (event.ctrlKey || event.metaKey) && event.shiftKey;
+}
+/** Prevent an inspected application click from reaching the host application. */
+export function blockApplicationClick(event) {
+    event.preventDefault();
+    event.stopPropagation();
+}

package/dist/inspector/overlay/dropGuide.d.ts

@@ -0,0 +1,22 @@
+import type { DropLocation } from "./structuralGestures.js";
+export type DropGuideOwner = "inspect" | "canvas";
+export interface DropGuideRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** A document-local guide. Visual adapters are responsible for projecting it. */
+export interface DropGuide {
+    owner: DropGuideOwner;
+    document: Document;
+    orientation: DropLocation["orientation"];
+    line: DropGuideRect;
+    target: DropGuideRect;
+}
+/** Publishes one guide model from a DOM insertion location. */
+export declare function showDropGuide(owner: DropGuideOwner, document: Document, drop: DropLocation): void;
+/** Clears only the guide belonging to the caller, preserving another active view. */
+export declare function clearDropGuide(owner: DropGuideOwner): void;
+/** Subscribes a visual adapter to its guide without exposing shared mutable state. */
+export declare function useDropGuide(owner: DropGuideOwner): DropGuide | null;

package/dist/inspector/overlay/dropGuide.js

@@ -0,0 +1,48 @@
+import { useSyncExternalStore } from "react";
+let currentGuide = null;
+const listeners = new Set();
+function notify() {
+    listeners.forEach((listener) => listener());
+}
+function subscribe(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+function snapshotFor(owner) {
+    return currentGuide?.owner === owner ? currentGuide : null;
+}
+function sameRect(left, right) {
+    return left.left === right.left
+        && left.top === right.top
+        && left.width === right.width
+        && left.height === right.height;
+}
+/** Publishes one guide model from a DOM insertion location. */
+export function showDropGuide(owner, document, drop) {
+    const target = drop.parent.getBoundingClientRect();
+    const nextGuide = {
+        owner,
+        document,
+        orientation: drop.orientation,
+        line: { left: drop.left, top: drop.top, width: drop.width, height: drop.height },
+        target: { left: target.left, top: target.top, width: target.width, height: target.height },
+    };
+    if (currentGuide?.owner === owner
+        && currentGuide.document === document
+        && sameRect(currentGuide.line, nextGuide.line)
+        && sameRect(currentGuide.target, nextGuide.target))
+        return;
+    currentGuide = nextGuide;
+    notify();
+}
+/** Clears only the guide belonging to the caller, preserving another active view. */
+export function clearDropGuide(owner) {
+    if (currentGuide?.owner !== owner)
+        return;
+    currentGuide = null;
+    notify();
+}
+/** Subscribes a visual adapter to its guide without exposing shared mutable state. */
+export function useDropGuide(owner) {
+    return useSyncExternalStore(subscribe, () => snapshotFor(owner), () => null);
+}

package/dist/inspector/overlay/elementSelector.d.ts

@@ -0,0 +1 @@
+export declare function installElementSelector(inspectorHost: HTMLElement): () => void;

package/dist/inspector/overlay/elementSelector.js

@@ -0,0 +1,100 @@
+import { getSelectedElements, setSelectedElement, toggleSelectedElement } from "../selection/selectionStore.js";
+import { getOpen } from "../shell/openStore.js";
+import { resolveSelectionFromEvent } from "../selection/resolveSelection.js";
+import { handleInlineTextEditIntent, isInlineTextEditingActive, } from "../inline-text/inlineTextEditor.js";
+import { EMPTY_TEXT_PROJECTION_ATTR } from "../projection/textProjection.js";
+import { blockApplicationClick, isApplicationActivationClick } from "./clickPolicy.js";
+export function installElementSelector(inspectorHost) {
+    function applyInlineTextDisposition(event, disposition) {
+        if (disposition === "pass-through")
+            return;
+        if (disposition === "suppress")
+            event.preventDefault();
+        event.stopPropagation();
+    }
+    function onDoubleClick(e) {
+        if (!getOpen())
+            return;
+        if (isInsideInspectorUi(e))
+            return;
+        if (getSelectedElements().length > 1) {
+            e.preventDefault();
+            e.stopPropagation();
+            return;
+        }
+        if (!(e.target instanceof Element))
+            return;
+        applyInlineTextDisposition(e, handleInlineTextEditIntent({
+            kind: "double-click",
+            target: e.target,
+            point: { x: e.clientX, y: e.clientY },
+        }));
+    }
+    function isInsideInspectorUi(event) {
+        const target = event.target;
+        if (!(target instanceof Element))
+            return false;
+        if (inspectorHost === target || inspectorHost.contains(target))
+            return true;
+        // Composed clicks originating inside the inspector's shadow root are
+        // retargeted to the host before document-level listeners observe them;
+        // this branch covers dispatch paths where retargeting has not applied.
+        const root = target.getRootNode();
+        return root instanceof ShadowRoot && root.host === inspectorHost;
+    }
+    function onClick(e) {
+        if (!getOpen())
+            return;
+        if (isInsideInspectorUi(e)) {
+            // The selector guards the inspected application only. Clicks on the
+            // inspector's own controls must keep their native behavior, so they
+            // pass through untouched (no preventDefault / stopPropagation).
+            return;
+        }
+        if (isInlineTextEditingActive()) {
+            e.preventDefault();
+            e.stopPropagation();
+            return;
+        }
+        if (e.target instanceof Element
+            && e.target.closest(`[${EMPTY_TEXT_PROJECTION_ATTR}]`)) {
+            blockApplicationClick(e);
+            return;
+        }
+        if (isApplicationActivationClick(e))
+            return;
+        // The inspector is an editing surface while open. Capture every ordinary
+        // application click so buttons, links, and untracked controls cannot run
+        // alongside selection. Shift-click toggles the primary target in the
+        // ordered group; Command/Ctrl-click still selects the deepest tracked
+        // element, and Command/Ctrl+Shift-click remains the activation escape hatch.
+        const sel = resolveSelectionFromEvent(e, inspectorHost);
+        blockApplicationClick(e);
+        if (sel) {
+            if (e.shiftKey && !e.metaKey && !e.ctrlKey)
+                toggleSelectedElement(sel);
+            else
+                setSelectedElement(sel);
+        }
+    }
+    function onMouseDown(e) {
+        if (!getOpen() || isInsideInspectorUi(e))
+            return;
+        if (!(e.target instanceof Element))
+            return;
+        applyInlineTextDisposition(e, handleInlineTextEditIntent({
+            kind: "pointer-down",
+            target: e.target,
+            point: { x: e.clientX, y: e.clientY },
+            clickCount: e.detail,
+        }));
+    }
+    document.addEventListener("mousedown", onMouseDown, true);
+    document.addEventListener("dblclick", onDoubleClick, true);
+    document.addEventListener("click", onClick, true);
+    return () => {
+        document.removeEventListener("mousedown", onMouseDown, true);
+        document.removeEventListener("dblclick", onDoubleClick, true);
+        document.removeEventListener("click", onClick, true);
+    };
+}

package/dist/inspector/overlay/frameThrottle.d.ts

@@ -0,0 +1,10 @@
+export interface FrameScheduler {
+    request(callback: FrameRequestCallback): number;
+    cancel(handle: number): void;
+}
+/** Retains only the newest value and performs at most one update per frame. */
+export declare function createFrameThrottle<T>(run: (value: T) => void, scheduler?: FrameScheduler): {
+    schedule(value: T): void;
+    flush: () => void;
+    cancel(): void;
+};

package/dist/inspector/overlay/frameThrottle.js

@@ -0,0 +1,38 @@
+const browserScheduler = {
+    request: (callback) => requestAnimationFrame(callback),
+    cancel: (handle) => cancelAnimationFrame(handle),
+};
+/** Retains only the newest value and performs at most one update per frame. */
+export function createFrameThrottle(run, scheduler = browserScheduler) {
+    let handle = 0;
+    let latest = null;
+    function runLatest() {
+        handle = 0;
+        const value = latest;
+        latest = null;
+        if (value !== null)
+            run(value);
+    }
+    function flush() {
+        if (handle)
+            scheduler.cancel(handle);
+        runLatest();
+    }
+    const scheduledFlush = () => {
+        runLatest();
+    };
+    return {
+        schedule(value) {
+            latest = value;
+            if (!handle)
+                handle = scheduler.request(scheduledFlush);
+        },
+        flush,
+        cancel() {
+            if (handle)
+                scheduler.cancel(handle);
+            handle = 0;
+            latest = null;
+        },
+    };
+}

package/dist/inspector/overlay/interactionStyles.d.ts

@@ -0,0 +1,3 @@
+export declare function isInteractionStylesInstalled(doc?: Document): boolean;
+/** Installs temporary interaction affordances without mutating tracked nodes. */
+export declare function installInteractionStyles(doc?: Document): () => void;