nudge-ui 0.2.0 → 0.2.2

package/dist/inspector/inline-text/textEditChange.js

@@ -0,0 +1,165 @@
+import { createComponentPropChange } from "../componentSemantics/changeModel.js";
+import { captureTextProjectionTarget, textProjectionSelector } from "../projection/textProjection.js";
+export function initialTextEditDecision(candidate) {
+    return {
+        bindingIndex: candidate.bindingChoices?.length === 1 ? 0 : null,
+        scope: candidate.scope ?? (candidate.binding.kind === "rendered-text" ? "rendered-instance" : "source-site"),
+    };
+}
+export function chooseTextEditBinding(candidate, index) {
+    const choice = candidate.bindingChoices?.[index];
+    if (!choice)
+        return null;
+    return {
+        bindingIndex: index,
+        scope: choice.mountedCount > 1 ? "rendered-instance" : "source-site",
+    };
+}
+function selectedBinding(candidate, decision) {
+    return decision.bindingIndex === null ? null : candidate.bindingChoices?.[decision.bindingIndex] ?? null;
+}
+export function getTextEditScopeChoices(candidate, decision) {
+    const choice = selectedBinding(candidate, decision);
+    if (!choice)
+        return candidate.scopeChoices ?? [];
+    return choice.mountedCount > 1 && choice.authoredAs === "literal"
+        ? ["rendered-instance", "source-site"]
+        : [];
+}
+export function getTextEditBinding(candidate, decision, capturedTarget) {
+    const choice = selectedBinding(candidate, decision);
+    if (!choice)
+        return candidate.binding;
+    if (choice.mountedCount > 1 && choice.authoredAs !== "literal") {
+        const target = choice.renderedTarget ?? candidate.renderedTarget ?? capturedTarget;
+        return target ? { kind: "rendered-text", target } : choice.binding;
+    }
+    return choice.binding;
+}
+function sourceForChoice(candidate, choice) {
+    if (choice?.renderedSource)
+        return choice.renderedSource;
+    if (candidate.renderedSource
+        && (!choice || candidate.renderedSource.evidence?.callsiteId === choice.binding.target.callsiteId
+            && candidate.renderedSource.evidence.property === choice.binding.property)) {
+        return candidate.renderedSource;
+    }
+    const parsed = /^(.*):(\d+):(\d+)$/.exec(candidate.element.getAttribute("data-src") ?? "");
+    const target = choice?.binding.target;
+    const authoredAs = choice?.authoredAs === "literal"
+        ? "literal"
+        : choice?.authoredAs === "expression" || choice?.authoredAs === "spread"
+            ? "expression"
+            : "unknown";
+    return {
+        file: target?.file ?? parsed?.[1] ?? candidate.element.getAttribute("data-src") ?? "",
+        line: target?.line ?? Number(parsed?.[2] ?? 0),
+        column: target?.column ?? Number(parsed?.[3] ?? 0),
+        component: target?.componentName ?? candidate.element.getAttribute("data-cid") ?? "Rendered text",
+        selector: candidate.binding.kind === "rendered-text"
+            ? textProjectionSelector(candidate.binding.target) ?? ""
+            : "",
+        authoredAs,
+        evidence: choice ? {
+            callsiteId: choice.binding.target.callsiteId,
+            componentName: choice.binding.target.componentName,
+            property: choice.binding.property,
+            mountedCount: choice.mountedCount,
+        } : undefined,
+    };
+}
+function componentEvidence(candidate, choice) {
+    const target = choice.renderedTarget
+        ?? candidate.renderedTarget
+        ?? captureTextProjectionTarget(candidate.element, candidate.before, candidate.textNode);
+    return {
+        occurrence: target?.occurrence ?? 0,
+        props: target?.props ?? candidate.element.getAttribute("data-cprops"),
+        ariaLabel: target?.ariaLabel ?? candidate.element.getAttribute("aria-label"),
+        beforeText: candidate.before,
+        mountedCount: choice.mountedCount,
+    };
+}
+function textTargetFor(candidate, binding, choice) {
+    if (choice?.renderedTarget)
+        return choice.renderedTarget;
+    if (candidate.renderedTarget)
+        return candidate.renderedTarget;
+    if (binding.kind === "rendered-text")
+        return binding.target;
+    return captureTextProjectionTarget(candidate.element, candidate.before, candidate.textNode);
+}
+function choiceForCommit(candidate, selectedChoice) {
+    const choice = selectedChoice ?? candidate.bindingChoices?.[0];
+    const target = candidate.editableTarget;
+    if (choice || !target || candidate.mountedCount === undefined)
+        return choice ?? null;
+    const property = candidate.binding.kind === "component-prop"
+        ? candidate.binding.property
+        : "children";
+    return {
+        binding: candidate.binding.kind === "component-prop"
+            ? candidate.binding
+            : {
+                kind: "component-prop",
+                property,
+                target: {
+                    framework: target.framework,
+                    componentId: target.contract.componentId,
+                    callsiteId: target.meta.callsiteId,
+                    componentName: target.meta.componentName,
+                    file: target.meta.file,
+                    line: target.meta.line,
+                    column: target.meta.column,
+                },
+            },
+        editableTarget: target,
+        mountedCount: candidate.mountedCount,
+        authoredAs: target.meta.authoredProps[property] ?? "default",
+        renderedTarget: candidate.renderedTarget ?? null,
+        renderedSource: candidate.renderedSource,
+    };
+}
+/** Builds a canonical record without changing the DOM, appending history, or ending a draft. */
+export function prepareTextEditChange(candidate, decision, capturedTarget, after) {
+    if ((candidate.bindingChoices?.length ?? 0) > 1 && decision.bindingIndex === null)
+        return null;
+    const binding = getTextEditBinding(candidate, decision, capturedTarget);
+    const choice = choiceForCommit(candidate, selectedBinding(candidate, decision));
+    if (binding.kind === "component-prop" && decision.scope === "source-site") {
+        const editableTarget = choice?.editableTarget ?? candidate.editableTarget;
+        const prop = editableTarget?.contract.props.find((item) => item.name === binding.property && item.control === "text");
+        if (!editableTarget || !prop)
+            return null;
+        return createComponentPropChange(editableTarget, prop, after, {
+            scope: "source-site",
+            evidence: choice && choice.mountedCount > 1
+                ? componentEvidence(candidate, choice)
+                : undefined,
+        });
+    }
+    const textTarget = textTargetFor(candidate, binding, choice);
+    const source = sourceForChoice(candidate, choice);
+    const renderedSource = source.selector || !textTarget
+        ? source
+        : { ...source, selector: textProjectionSelector(textTarget) ?? "" };
+    if (!textTarget || !renderedSource.selector)
+        return null;
+    return {
+        kind: "text-content",
+        id: `text-${globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`}`,
+        target: textTarget,
+        source: {
+            file: renderedSource.file,
+            line: renderedSource.line,
+            column: renderedSource.column,
+            component: renderedSource.component,
+        },
+        selector: renderedSource.selector,
+        before: candidate.before,
+        after,
+        authoredAs: renderedSource.authoredAs,
+        scope: decision.scope,
+        evidence: renderedSource.evidence,
+    };
+}

package/dist/inspector/inspection/selectionProperty.d.ts

@@ -19,6 +19,7 @@ export interface SelectionProperty {
     value: SelectionValue;
     token: SelectionToken;
     primaryRow: ResolvedProperty | null;
+    rows: readonly (ResolvedProperty | null)[];
 }
 /**
  * Projects browser values and authored inspection rows into group-safe facts.

package/dist/inspector/inspection/selectionProperty.js

@@ -22,6 +22,7 @@ export function projectSelectionProperty(property, rows, values, primaryIndex) {
         value: common ? { kind: "common", value: first } : { kind: "mixed" },
         token: tokenFor(rows),
         primaryRow: rows[primaryIndex] ?? null,
+        rows,
     };
 }
 /** Returns the token entries available to every inspected target. */

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

@@ -0,0 +1,10 @@
+import { type ReactElement } from "react";
+import type { SelectedElement } from "../selection/selectionStore.js";
+import type { Rect } from "./overlayGeometry.js";
+export interface DomNavigatorProps {
+    selected: SelectedElement;
+    hierarchy: HTMLElement[];
+    anchor: Rect;
+    project: (element: HTMLElement) => Rect | null;
+}
+export declare function DomNavigator({ selected, hierarchy, anchor, project }: DomNavigatorProps): ReactElement | null;

package/dist/inspector/overlay/DomNavigator.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useState } from "react";
+import { setSelectedElement } from "../selection/selectionStore.js";
+import { computeNavigationNodes } from "../selection/hierarchy.js";
+import { resolveSelectionFromElement } from "../selection/resolveSelection.js";
+function nodeLabel(node) {
+    return node.getAttribute("data-cid") ?? node.localName;
+}
+function nodeDescription(node) {
+    const id = node.id ? `#${node.id}` : "";
+    const className = typeof node.className === "string"
+        ? node.className.trim().split(/\s+/).filter(Boolean).slice(0, 2).map((name) => `.${name}`).join("")
+        : "";
+    const source = node.getAttribute("data-src");
+    return `${node.localName}${id}${className}${source ? ` — ${source}` : ""}`;
+}
+function selectNode(node) {
+    const resolved = resolveSelectionFromElement(node);
+    if (resolved)
+        setSelectedElement(resolved);
+}
+export function DomNavigator({ selected, hierarchy, anchor, project }) {
+    const nodes = computeNavigationNodes(selected.domElement, hierarchy);
+    const [expanded, setExpanded] = useState(false);
+    const [hovered, setHovered] = useState(null);
+    if (nodes.length === 0)
+        return null;
+    const preview = hovered ? project(hovered) : null;
+    const close = () => {
+        setExpanded(false);
+        setHovered(null);
+    };
+    return (_jsxs(_Fragment, { children: [preview ? _jsx("div", { className: "dom-navigator-preview", "data-test": "dom-navigator-preview", style: preview, "aria-hidden": "true" }) : null, _jsxs("div", { className: "dom-navigator", "data-test": "dom-navigator", "aria-label": "DOM navigator", style: { left: Math.max(4, anchor.left), top: Math.max(4, anchor.top) }, onMouseEnter: () => setExpanded(true), onMouseLeave: close, onFocus: () => setExpanded(true), onBlur: (event) => {
+                    if (!(event.relatedTarget instanceof Node) || !event.currentTarget.contains(event.relatedTarget))
+                        close();
+                }, children: [_jsxs("button", { type: "button", className: "dom-navigator__trigger", "data-test": "dom-navigator-trigger", "aria-expanded": expanded, "aria-haspopup": "menu", title: nodeDescription(selected.domElement), onMouseEnter: () => setHovered(null), children: [_jsx("span", { children: nodeLabel(selected.domElement) }), _jsx("span", { "aria-hidden": "true", children: "\u2304" })] }), expanded ? (_jsx("div", { className: "dom-navigator__menu", role: "menu", children: nodes.map((node) => (_jsxs("button", { type: "button", className: "dom-navigator__item", "data-test": "dom-navigator-item", "data-direction": node.direction, "data-depth": node.depth, "data-cid": node.element.getAttribute("data-cid") ?? undefined, title: nodeDescription(node.element), role: "menuitem", onMouseEnter: () => setHovered(node.element), onClick: () => {
+                                selectNode(node.element);
+                                close();
+                            }, children: [_jsx("span", { "aria-hidden": "true", children: node.direction === "up" ? "↑" : "↓" }), _jsx("span", { children: nodeLabel(node.element) })] }, `${node.direction}-${node.depth}-${node.element.getAttribute("data-cid") ?? node.element.localName}`))) })) : null] })] }));
+}

package/dist/inspector/overlay/InspectorOverlay.js

@@ -1,7 +1,7 @@
 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 { getSelectedElements, useHierarchy, 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";
@@ -17,6 +17,8 @@ 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";
+import { useNudgeUiRuntimeConfig } from "../runtime/useRuntimeConfig.js";
+import { DomNavigator } from "./DomNavigator.js";
 export { getMarginFills, getMarginGuides, } from "./overlayGeometry.js";
 function overlayStyle(rect) {
     return {
@@ -32,6 +34,8 @@ export function InspectorOverlay({ host }) {
     const open = useInspectorOpen();
     const selected = useSelectedElement();
     const selectedElements = useSelectedElements();
+    const hierarchy = useHierarchy();
+    const domNavigationEnabled = useNudgeUiRuntimeConfig().capabilities.domNavigation === true;
     const inlineTextSession = useInlineTextSession();
     const [hoverRect, setHoverRect] = useState(null);
     const [hoverMargins, setHoverMargins] = useState(null);
@@ -322,7 +326,7 @@ export function InspectorOverlay({ host }) {
                             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
+                        }, "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 && domNavigationEnabled && !inlineTextSession && selectedElements.length === 1 && selected && selectedRect ? (_jsx(DomNavigator, { selected: selected, hierarchy: hierarchy, anchor: selectedRect, project: (element) => toRect(element.getBoundingClientRect()) })) : 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/clickPolicy.d.ts

@@ -1,7 +1,23 @@
 export type ClickModifiers = Pick<MouseEvent, "ctrlKey" | "metaKey" | "shiftKey">;
+/**
+ * Press and release gestures that application widgets use to open menus,
+ * dialogs, and popovers before any `click` fires. The Design tool keeps them
+ * from reaching the application.
+ */
+export declare const APPLICATION_GESTURE_EVENTS: readonly ["pointerdown", "pointerup", "mousedown", "mouseup", "touchstart", "touchend", "auxclick", "contextmenu"];
 /** 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;
+/**
+ * Only input from a person becomes inspector selection. Script events such
+ * as `element.click()` keep reaching the application.
+ */
+export declare function isUserClick(event: Pick<Event, "isTrusted">): boolean;
+/** The active inline text editor needs native press events for caret placement. */
+export declare function isInlineEditorTarget(target: EventTarget | null): boolean;
+/**
+ * Keeps an application press gesture from reaching application listeners.
+ * Listeners on the document itself, including the inspector's own, still run.
+ */
+export declare function blockApplicationGesture(event: Event): void;
 /** Prevent an inspected application click from reaching the host application. */
 export declare function blockApplicationClick(event: MouseEvent): void;

package/dist/inspector/overlay/clickPolicy.js

@@ -1,10 +1,41 @@
+/**
+ * Press and release gestures that application widgets use to open menus,
+ * dialogs, and popovers before any `click` fires. The Design tool keeps them
+ * from reaching the application.
+ */
+export const APPLICATION_GESTURE_EVENTS = [
+    "pointerdown",
+    "pointerup",
+    "mousedown",
+    "mouseup",
+    "touchstart",
+    "touchend",
+    "auxclick",
+    "contextmenu",
+];
 /** 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;
+/**
+ * Only input from a person becomes inspector selection. Script events such
+ * as `element.click()` keep reaching the application.
+ */
+export function isUserClick(event) {
+    return event.isTrusted;
+}
+/** The active inline text editor needs native press events for caret placement. */
+export function isInlineEditorTarget(target) {
+    return typeof Element !== "undefined"
+        && target instanceof Element
+        && target.closest('[data-inline-editor="true"]') !== null;
+}
+/**
+ * Keeps an application press gesture from reaching application listeners.
+ * Listeners on the document itself, including the inspector's own, still run.
+ */
+export function blockApplicationGesture(event) {
+    event.stopPropagation();
 }
 /** Prevent an inspected application click from reaching the host application. */
 export function blockApplicationClick(event) {

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

@@ -1 +1 @@
-export declare function installElementSelector(inspectorHost: HTMLElement): () => void;
+export declare function installElementSelector(inspectorHost: HTMLElement, acceptsClick?: (event: Event) => boolean): () => void;

package/dist/inspector/overlay/elementSelector.js

@@ -3,8 +3,8 @@ 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) {
+import { APPLICATION_GESTURE_EVENTS, blockApplicationClick, blockApplicationGesture, isInlineEditorTarget, isUserClick, } from "./clickPolicy.js";
+export function installElementSelector(inspectorHost, acceptsClick = isUserClick) {
     function applyInlineTextDisposition(event, disposition) {
         if (disposition === "pass-through")
             return;
@@ -43,7 +43,7 @@ export function installElementSelector(inspectorHost) {
         return root instanceof ShadowRoot && root.host === inspectorHost;
     }
     function onClick(e) {
-        if (!getOpen())
+        if (!getOpen() || !acceptsClick(e))
             return;
         if (isInsideInspectorUi(e)) {
             // The selector guards the inspected application only. Clicks on the
@@ -61,13 +61,10 @@ export function installElementSelector(inspectorHost) {
             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.
+        // ordered group; Command/Ctrl-click selects the deepest tracked element.
         const sel = resolveSelectionFromEvent(e, inspectorHost);
         blockApplicationClick(e);
         if (sel) {
@@ -89,12 +86,26 @@ export function installElementSelector(inspectorHost) {
             clickCount: e.detail,
         }));
     }
+    function onApplicationGesture(e) {
+        if (!getOpen() || !acceptsClick(e) || isInlineEditorTarget(e.target))
+            return;
+        if (e.target instanceof Element
+            && (e.target === inspectorHost || inspectorHost.contains(e.target)))
+            return;
+        blockApplicationGesture(e);
+    }
     document.addEventListener("mousedown", onMouseDown, true);
     document.addEventListener("dblclick", onDoubleClick, true);
     document.addEventListener("click", onClick, true);
+    for (const type of APPLICATION_GESTURE_EVENTS) {
+        document.addEventListener(type, onApplicationGesture, true);
+    }
     return () => {
         document.removeEventListener("mousedown", onMouseDown, true);
         document.removeEventListener("dblclick", onDoubleClick, true);
         document.removeEventListener("click", onClick, true);
+        for (const type of APPLICATION_GESTURE_EVENTS) {
+            document.removeEventListener(type, onApplicationGesture, true);
+        }
     };
 }

package/dist/inspector/overlay/selectedGeometry.js

@@ -20,6 +20,24 @@ export function observeSelectedGeometry(element, onChange) {
             onChange();
         });
     }
+    let scrollTargets = [];
+    function unbindScrollTargets() {
+        for (const target of scrollTargets)
+            target.removeEventListener("scroll", schedule, true);
+        scrollTargets = [];
+    }
+    function bindScrollTargets() {
+        unbindScrollTargets();
+        const targets = [view, view.document];
+        let ancestor = element.parentElement;
+        while (ancestor) {
+            targets.push(ancestor);
+            ancestor = ancestor.parentElement;
+        }
+        scrollTargets = [...new Set(targets)];
+        for (const target of scrollTargets)
+            target.addEventListener("scroll", schedule, true);
+    }
     const resizeObserver = ResizeObserverCtor
         ? new ResizeObserverCtor(schedule)
         : null;
@@ -32,6 +50,7 @@ export function observeSelectedGeometry(element, onChange) {
             mutationObserver?.disconnect();
             if (observedParent)
                 mutationObserver?.observe(observedParent, { childList: true });
+            bindScrollTargets();
         }
         schedule();
     }) : null;
@@ -39,13 +58,13 @@ export function observeSelectedGeometry(element, onChange) {
     if (observedParent)
         mutationObserver?.observe(observedParent, { childList: true });
     view.addEventListener("resize", schedule);
-    view.addEventListener("scroll", schedule, true);
+    bindScrollTargets();
     return () => {
         if (frame !== null)
             view.cancelAnimationFrame(frame);
         resizeObserver?.disconnect();
         mutationObserver?.disconnect();
         view.removeEventListener("resize", schedule);
-        view.removeEventListener("scroll", schedule, true);
+        unbindScrollTargets();
     };
 }

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

@@ -0,0 +1,45 @@
+import type { Rect } from "./overlayGeometry.js";
+export type PaddingSide = "top" | "right" | "bottom" | "left";
+export type SpacingKind = "padding" | "gap";
+export type SpacingAxis = "horizontal" | "vertical";
+export type SpacingDragAxis = "x" | "y";
+export type SpacingProperty = `padding-${PaddingSide}` | "row-gap" | "column-gap";
+export interface SpacingGuideData {
+    kind: SpacingKind;
+    property: SpacingProperty;
+    side: PaddingSide | null;
+    axis: SpacingAxis;
+    dragAxis: SpacingDragAxis;
+    value: number;
+    direction: 1 | -1;
+    cursor: "ew-resize" | "ns-resize";
+    guide: Rect;
+    affectedGuides: Rect[];
+    affectedAreas: Rect[];
+    /** A 16px-thick pointer target centred on the visible, up-to-40px guide handle. */
+    hit: Rect;
+}
+export interface SpacingAffordance extends SpacingGuideData {
+    element: HTMLElement;
+}
+export interface SpacingDescriptor {
+    kind: SpacingKind;
+    property: SpacingProperty;
+    side: PaddingSide | null;
+}
+export declare const SPACING_GUIDE_HANDLE_LENGTH = 40;
+/** Finds the spacing target under a document-local pointer location. */
+export declare function getSpacingAffordanceAtPoint(doc: Document, x: number, y: number): SpacingAffordance | null;
+/** Re-resolves a renderer-reported spacing descriptor in its owner document. */
+export declare function getSpacingAffordanceForDescriptor(element: HTMLElement, descriptor: SpacingDescriptor): SpacingAffordance | null;
+/** Calculates a direct-manipulation value, optionally stepping changes by 8px. */
+export declare function spacingValueForDrag(affordance: Pick<SpacingAffordance, "dragAxis" | "direction" | "value">, start: {
+    x: number;
+    y: number;
+}, point: {
+    x: number;
+    y: number;
+}, shiftKey?: boolean): number;
+export declare function spacingValueCss(value: number): string;
+/** Serializes the stable part of an affordance for renderer-to-controller messages. */
+export declare function toSpacingDescriptor(affordance: SpacingAffordance): SpacingDescriptor;