nudge-ui 0.2.5 → 0.2.6

package/dist/inspector/iterations/capture.js

@@ -1,6 +1,5 @@
 import { HTML_ARTIFACT_REVISION_ATTRIBUTE } from "../../transport/artifacts.js";
 import { FRAME_SCROLLBAR_STYLE_ID } from "../canvas/frameScrollbarStyles.js";
-/** Captures the visible DOM of a same-origin frame as a script-free HTML iteration. */
 export async function captureHtmlIteration(frame) {
     const source = frame.contentDocument;
     const view = frame.contentWindow;
@@ -19,11 +18,9 @@ export async function captureHtmlIteration(frame) {
         const copied = copiedElements[index];
         if (sourceElement.nodeType !== 1 || copied.nodeType !== 1)
             continue;
-        // Renderer IDs belong to the source iframe's node registry. The iteration's
-        // fresh registry can reuse those values for different nodes.
+        // Renderer IDs belong to the source iframe's registry; the iteration's fresh registry can reuse them for different nodes.
         copied.removeAttribute("data-renderer-id");
-        // Preserve authored inline values (percentages, variables, and calc), rather
-        // than replacing them with computed dimensions at the capture viewport.
+        // Keep authored inline values (percentages, variables, calc) instead of computed dimensions.
         const inline = copied.getAttribute("style");
         if (inline)
             copied.setAttribute("style", await resolveCssUrls(inline, source.baseURI, assets));
@@ -100,8 +97,7 @@ async function captureStylesheets(document, copy, sourceElements, copiedElements
                 css = await response.text();
             }
             catch {
-                // Keep the stylesheet link when CORS prevents embedding it. Its URL
-                // still resolves against the original base and retains responsiveness.
+                // Keep the stylesheet link when CORS prevents embedding it; its URL still resolves against the original base.
                 continue;
             }
         }
@@ -112,8 +108,7 @@ async function captureStylesheets(document, copy, sourceElements, copiedElements
             }
         }
         style.textContent = await resolveCssUrls(css, sheet.href ?? document.baseURI, assets);
-        // Captured edits become the iteration's base. The renderer must create its own
-        // managed stylesheet for new edits instead of clearing these captured rules.
+        // Captured edits become the iteration's base; the renderer must create its own managed stylesheet for new edits.
         if (style.id === "nudge-ui-styles") {
             style.removeAttribute("id");
             style.removeAttribute("data-nudge-ui");

package/dist/inspector/iterations/client.d.ts

@@ -2,7 +2,6 @@ import type { CanvasFrame } from "../canvas/canvasFrame.js";
 import { type HtmlArtifactRevision } from "../../transport/artifacts.js";
 export declare function artifactDocumentUrl(id: string): string;
 export declare function readHtmlArtifactRevision(id: string): Promise<HtmlArtifactRevision>;
-/** Checks the editing base before saving and promoting a captured document. */
 export declare function commitHtmlArtifact(id: string, expected: HtmlArtifactRevision, html?: string): Promise<HtmlArtifactRevision>;
 export declare function createHtmlArtifact(frame: CanvasFrame, sourceUrl: string, title: string, capturedHtml?: string): Promise<string>;
 export declare function removeHtmlArtifact(id: string): Promise<void>;

package/dist/inspector/iterations/client.js

@@ -13,7 +13,6 @@ export async function readHtmlArtifactRevision(id) {
         throw new Error("The HTML iteration returned an invalid revision.");
     return revision;
 }
-/** Checks the editing base before saving and promoting a captured document. */
 export async function commitHtmlArtifact(id, expected, html) {
     const response = await fetch(`${NUDGE_UI_ARTIFACTS_PATH}/${id}/commit`, {
         method: "POST",

package/dist/inspector/iterations/coordinator.d.ts

@@ -6,7 +6,6 @@ export interface HtmlIterationStorage {
     readRevision(id: string): Promise<HtmlArtifactRevision>;
     commit(id: string, expected: HtmlArtifactRevision, html?: string): Promise<HtmlArtifactRevision>;
 }
-/** Owns save ordering, draft settlement, and external document promotion. */
 export declare function createHtmlIterationCoordinator(storage: HtmlIterationStorage): {
     prepare(cardId: string, artifactId: string, baseRevision: string, capture: () => Promise<string>): Promise<DraftContents>;
     refresh(cardId: string, artifactId: string, baseRevision: string, available: () => boolean): Promise<boolean>;

package/dist/inspector/iterations/coordinator.js

@@ -6,7 +6,6 @@ import { projectDraftToDocument, isCanvasProjectionRevisionCurrent, projectToAll
 import { isInlineTextEditingActive } from "../inline-text/inlineTextEditor.js";
 import { captureHtmlIteration } from "./capture.js";
 import { artifactDocumentUrl, commitHtmlArtifact, readHtmlArtifactRevision } from "./client.js";
-/** Owns save ordering, draft settlement, and external document promotion. */
 export function createHtmlIterationCoordinator(storage) {
     const operations = new Map();
     async function serialize(id, operation) {

package/dist/inspector/iterations/prompt.d.ts

@@ -1,3 +1,2 @@
-/** Defines the edit destination for every HTML-iteration handoff, including fallback copies. */
 export declare function htmlIterationPrompt(id: string, changes: string, noInspectorChanges: boolean, hasSketches: boolean, customInstructions?: string): string;
 export declare function htmlIterationImplementationPrompt(id: string, label: string, page: string, changes: string): string;

package/dist/inspector/iterations/prompt.js

@@ -1,5 +1,4 @@
 import { withPromptContext } from "../prompt/promptDocument.js";
-/** Defines the edit destination for every HTML-iteration handoff, including fallback copies. */
 export function htmlIterationPrompt(id, changes, noInspectorChanges, hasSketches, customInstructions = "") {
     const directory = `.nudge/artifacts/${id}`;
     return withPromptContext([

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

@@ -6,5 +6,7 @@ export interface DomNavigatorProps {
     hierarchy: HTMLElement[];
     anchor: Rect;
     project: (element: HTMLElement) => Rect | null;
+    /** The selection is a component or shares its source with other elements. */
+    linked?: boolean;
 }
-export declare function DomNavigator({ selected, hierarchy, anchor, project }: DomNavigatorProps): ReactElement | null;
+export declare function DomNavigator({ selected, hierarchy, anchor, project, linked }: DomNavigatorProps): ReactElement | null;

package/dist/inspector/overlay/DomNavigator.js

@@ -1,9 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useState } from "react";
-import { IconMenu2 } from "@tabler/icons-react";
+import { IconChevronDown, IconChevronRight, IconMenu2 } from "@tabler/icons-react";
 import { Popover as BasePopover } from "@base-ui/react/popover";
 import { setSelectedElement } from "../selection/selectionStore.js";
-import { computeNavigationNodes } from "../selection/hierarchy.js";
+import { computeNavigationParents, computeTrackedChildren, hasTrackedChildren } from "../selection/hierarchy.js";
 import { resolveSelectionFromElement } from "../selection/resolveSelection.js";
 import { portalContainer } from "../ui/portalContainer.js";
 import { cx } from "../ui/classNames.js";
@@ -19,28 +19,52 @@ function selectNode(node) {
     if (resolved)
         setSelectedElement(resolved);
 }
-export function DomNavigator({ selected, hierarchy, anchor, project }) {
-    const nodes = computeNavigationNodes(selected.domElement, hierarchy);
-    const parents = nodes.filter((node) => node.direction === "up");
-    const children = nodes.filter((node) => node.direction === "down");
+export function DomNavigator({ selected, hierarchy, anchor, project, linked = false }) {
+    const children = computeTrackedChildren(selected.domElement);
+    const parents = computeNavigationParents(hierarchy, children.elements.length > 0);
     const [expanded, setExpanded] = useState(false);
     const [hovered, setHovered] = useState(null);
-    if (nodes.length === 0)
+    const [opened, setOpened] = useState(new Set());
+    if (parents.length === 0 && children.elements.length === 0)
         return null;
     const preview = hovered ? project(hovered) : null;
     const setOpen = (next) => {
         setExpanded(next);
-        if (!next)
+        if (!next) {
             setHovered(null);
+            setOpened(new Set());
+        }
     };
-    const renderItem = (node, depth) => {
-        const current = node === null;
-        const element = current ? selected.domElement : node.element;
-        return (_jsx("button", { type: "button", className: cx("dom-navigator__item", current && "dom-navigator__item--selected"), "data-test": "dom-navigator-item", "data-current": current ? "true" : undefined, "data-direction": node?.direction, "data-depth": depth, "data-cid": element.getAttribute("data-cid") ?? undefined, style: { paddingLeft: `calc(var(--space-8) + ${depth * 16}px)` }, role: "menuitem", "aria-current": current ? "true" : undefined, onMouseEnter: () => setHovered(current ? null : element), onClick: () => {
+    const toggleOpened = (element) => {
+        setOpened((current) => {
+            const next = new Set(current);
+            if (!next.delete(element))
+                next.add(element);
+            return next;
+        });
+    };
+    const renderItem = (key, element, depth) => {
+        const current = element === null;
+        const target = element ?? selected.domElement;
+        return (_jsx("button", { type: "button", className: cx("dom-navigator__item", current && "dom-navigator__item--selected"), "data-test": "dom-navigator-item", "data-current": current ? "true" : undefined, "data-depth": depth, "data-cid": target.getAttribute("data-cid") ?? undefined, style: { paddingLeft: `calc(var(--space-8) + ${depth * 16}px)` }, role: "menuitem", "aria-current": current ? "true" : undefined, onMouseEnter: () => setHovered(current ? null : target), onClick: () => {
                 if (!current)
-                    selectNode(element);
+                    selectNode(target);
                 setOpen(false);
-            }, children: _jsx("span", { children: nodeDescription(element) }) }, current ? "current" : `${node.direction}-${node.depth}-${element.getAttribute("data-cid") ?? element.localName}`));
+            }, children: _jsx("span", { children: nodeDescription(target) }) }, key));
     };
-    return (_jsxs(_Fragment, { children: [preview ? _jsx("div", { className: "dom-navigator-preview", "data-test": "dom-navigator-preview", style: preview, "aria-hidden": "true" }) : null, _jsx("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 - 28) }, children: _jsxs(BasePopover.Root, { open: expanded, onOpenChange: setOpen, children: [_jsx(BasePopover.Trigger, { render: _jsx("button", { type: "button", className: "dom-navigator__trigger", "data-test": "dom-navigator-trigger", "aria-label": "Open DOM navigator", "aria-haspopup": "menu", "aria-expanded": expanded, onMouseEnter: () => setHovered(null) }), children: _jsx(IconMenu2, { size: 14, "aria-hidden": "true" }) }), _jsx("span", { className: "dom-navigator__label", children: nodeDescription(selected.domElement) }), _jsx(BasePopover.Portal, { container: portalContainer(), children: _jsx(BasePopover.Positioner, { className: "dom-navigator__positioner", side: "top", align: "start", sideOffset: 4, children: _jsxs(BasePopover.Popup, { className: "dom-navigator__menu", role: "menu", "aria-label": "DOM navigator", onMouseLeave: () => setHovered(null), children: [parents.slice().reverse().map((node) => renderItem(node, parents.length - node.depth)), renderItem(null, parents.length), children.map((node) => renderItem(node, parents.length + node.depth))] }) }) })] }) })] }));
+    const renderChildren = (list, depth, path) => [
+        ...list.elements.flatMap((element, index) => {
+            const key = `${path}/${index}`;
+            const nested = opened.has(element) ? computeTrackedChildren(element) : null;
+            const expandable = hasTrackedChildren(element);
+            return [
+                _jsxs("div", { className: "dom-navigator__row", "data-test": "dom-navigator-row", children: [expandable ? (_jsx("button", { type: "button", className: "dom-navigator__expander", "data-test": "dom-navigator-expander", "aria-label": `${nested ? "Collapse" : "Expand"} ${nodeDescription(element)}`, "aria-expanded": nested !== null, style: { left: `calc(var(--space-4) + ${(depth - 1) * 16}px)` }, onMouseEnter: () => setHovered(null), onClick: () => toggleOpened(element), children: nested ? _jsx(IconChevronDown, { size: 12, "aria-hidden": "true" }) : _jsx(IconChevronRight, { size: 12, "aria-hidden": "true" }) })) : null, renderItem(key, element, depth)] }, key),
+                ...(nested ? renderChildren(nested, depth + 1, key) : []),
+            ];
+        }),
+        ...(list.hidden > 0
+            ? [(_jsxs("div", { className: "dom-navigator__more", "data-test": "dom-navigator-more", style: { paddingLeft: `calc(var(--space-8) + ${depth * 16}px)` }, children: ["+", list.hidden, " more"] }, `${path}/more`))]
+            : []),
+    ];
+    return (_jsxs(_Fragment, { children: [preview ? _jsx("div", { className: "dom-navigator-preview", "data-test": "dom-navigator-preview", style: preview, "aria-hidden": "true" }) : null, _jsx("div", { className: "dom-navigator", "data-test": "dom-navigator", "data-linked": linked ? "true" : undefined, "aria-label": "DOM navigator", style: { left: Math.max(4, anchor.left), top: Math.max(4, anchor.top - 28) }, children: _jsxs(BasePopover.Root, { open: expanded, onOpenChange: setOpen, children: [_jsx(BasePopover.Trigger, { render: _jsx("button", { type: "button", className: "dom-navigator__trigger", "data-test": "dom-navigator-trigger", "aria-label": "Open DOM navigator", "aria-haspopup": "menu", "aria-expanded": expanded, onMouseEnter: () => setHovered(null) }), children: _jsx(IconMenu2, { size: 14, "aria-hidden": "true" }) }), _jsx("span", { className: "dom-navigator__label", children: nodeDescription(selected.domElement) }), _jsx(BasePopover.Portal, { container: portalContainer(), children: _jsx(BasePopover.Positioner, { className: "dom-navigator__positioner", side: "top", align: "start", sideOffset: 4, children: _jsxs(BasePopover.Popup, { className: "dom-navigator__menu", role: "menu", "aria-label": "DOM navigator", onMouseLeave: () => setHovered(null), children: [parents.slice().reverse().map((element, index) => renderItem(`up-${index}`, element, index)), renderItem("current", null, parents.length), renderChildren(children, parents.length + 1, "down")] }) }) })] }) })] }));
 }

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

@@ -12,6 +12,5 @@ interface DropGuideOverlayProps {
     targetClassName?: string;
     targetTestId?: string;
 }
-/** Shared visual wrapper; each view only supplies its projected viewport geometry. */
 export declare function DropGuideOverlay({ guide, lineClassName, lineTestId, targetClassName, targetTestId, }: DropGuideOverlayProps): ReactElement | null;
 export {};

package/dist/inspector/overlay/DropGuideOverlay.js

@@ -9,7 +9,6 @@ function fixedRect(rect) {
         pointerEvents: "none",
     };
 }
-/** Shared visual wrapper; each view only supplies its projected viewport geometry. */
 export function DropGuideOverlay({ guide, lineClassName, lineTestId, targetClassName, targetTestId, }) {
     if (!guide)
         return null;

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

@@ -2,18 +2,11 @@ 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.
- */
+/** Geometry arrives in the overlay's screen coordinates; Canvas projects iframe-local coordinates before rendering here. */
 export declare function MeasurementGuideOverlay({ selectedRect, guideViewport, segments, testId, }: MeasurementGuideOverlayProps): ReactElement;
 export {};

package/dist/inspector/overlay/MeasurementGuideOverlay.js

@@ -1,10 +1,6 @@
 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.
- */
+/** Geometry arrives in the overlay's screen coordinates; Canvas projects iframe-local coordinates before rendering here. */
 export function MeasurementGuideOverlay({ selectedRect, guideViewport, segments, testId = "measurement-overlay", }) {
     const [windowViewport, setWindowViewport] = useState(() => ({
         width: window.innerWidth,

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

@@ -1,23 +1,12 @@
 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.
- */
+/** Press/release gestures widgets use to open menus and popovers before any `click` fires. */
 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;
-/**
- * Only input from a person becomes inspector selection. Script events such
- * as `element.click()` keep reaching the application.
- */
+/** Synthetic events like `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.
- */
+/** Document-level listeners, 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,8 +1,4 @@
-/**
- * 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.
- */
+/** Press/release gestures widgets use to open menus and popovers before any `click` fires. */
 export const APPLICATION_GESTURE_EVENTS = [
     "pointerdown",
     "pointerup",
@@ -17,10 +13,7 @@ export const APPLICATION_GESTURE_EVENTS = [
 export function isDeepSelectionClick(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.
- */
+/** Synthetic events like `element.click()` keep reaching the application. */
 export function isUserClick(event) {
     return event.isTrusted;
 }
@@ -30,14 +23,10 @@ export function isInlineEditorTarget(target) {
         && 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.
- */
+/** Document-level listeners, 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) {
     event.preventDefault();
     event.stopPropagation();

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

@@ -14,9 +14,6 @@ export interface DropGuide {
     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

@@ -17,7 +17,6 @@ function sameRect(left, right) {
         && 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 = {
@@ -35,14 +34,12 @@ export function showDropGuide(owner, document, drop) {
     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/frameThrottle.d.ts

@@ -2,7 +2,6 @@ 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;

package/dist/inspector/overlay/frameThrottle.js

@@ -2,7 +2,6 @@ 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;

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

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

package/dist/inspector/overlay/interactionStyles.js

@@ -20,13 +20,7 @@ const INTERACTION_CSS = `
     outline: 0 !important;
   }
 
-  /*
-   * An empty rendered-text projection has no glyph for the browser to hit
-   * test. The projection module inserts this inspector-owned slot beside the
-   * original empty Text node. It is intentionally borderless: the blue fill
-   * is the affordance, while the normal selected-element outline remains a
-   * separate overlay.
-   */
+  /* Inspector-owned hit target for empty text projections, which have no glyph to hit test. */
   [data-empty-text] {
     display: inline-block !important;
     width: 0.75em !important;
@@ -46,7 +40,7 @@ const INTERACTION_CSS = `
 export function isInteractionStylesInstalled(doc = document) {
     return interactionStyleDocuments.has(doc);
 }
-/** Installs temporary interaction affordances without mutating tracked nodes. */
+/** Installs affordances via a stylesheet, leaving tracked nodes untouched. */
 export function installInteractionStyles(doc = document) {
     if (!allowsStyleElements(doc))
         return installAdoptedInteractionStyles(doc);

package/dist/inspector/overlay/measurementGeometry.js

@@ -22,11 +22,7 @@ function centerFromBounds(range) {
 function hasLength(from, to) {
     return Math.abs(to - from) > EPSILON;
 }
-/**
- * Finds the labelled ruler(s) for one axis. A positive gap gets a single
- * nearest-edge ruler. On overlap, the measurement changes to the hovered
- * element's far edge; containment has two meaningful inset measurements.
- */
+/** On overlap the ruler switches to the hovered element's far edge; containment gets two inset measurements. */
 function getAxisRulers(selected, hovered, selectedInner, hoveredInner) {
     if (selected.max < hovered.min - EPSILON) {
         return [{ selectedEdge: selected.max, hoveredEdge: hovered.min }];
@@ -56,8 +52,8 @@ function getAxisRulers(selected, hovered, selectedInner, hoveredInner) {
             { selectedEdge: selected.max, hoveredEdge: hoveredInner.max },
         ].filter((ruler) => hasLength(ruler.selectedEdge, ruler.hoveredEdge));
     }
-    // The boxes partially overlap. Measure from the selected outside edge to
-    // the hover's far edge rather than rendering a zero or negative gap.
+    // Partially overlapping boxes measure from the selected outside edge to the
+    // hover's far edge rather than a zero or negative gap.
     if (centerFromBounds(selected) >= centerFromBounds(hovered)) {
         return [{ selectedEdge: selected.min, hoveredEdge: hovered.min }];
     }
@@ -74,11 +70,7 @@ function createSegment(id, kind, axis, from, to, cross) {
         ...(kind === "ruler" ? { distance: Math.abs(to - from) } : {}),
     };
 }
-/**
- * Solid rulers always run through the selected element's centerline. If the
- * centerline does not meet the hovered edge, a perpendicular dotted extension
- * starts at that hovered edge and joins the ruler.
- */
+/** A perpendicular dotted extension joins the centerline ruler when it misses the hovered edge. */
 function appendPrimaryRulers(segments, selected, hovered, axis, options) {
     const crossAxis = axis === "horizontal" ? "vertical" : "horizontal";
     const cross = center(selected, crossAxis);

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

@@ -1,7 +1,2 @@
-/**
- * Watches the small set of browser events that can change a selected element's
- * viewport rect without changing its selection identity. Structural gestures
- * can move a selected element between containers, so the child-list observer
- * follows the element's current parent after each mutation.
- */
+/** Follows the element's current parent after mutations, since gestures can move it between containers. */
 export declare function observeSelectedGeometry(element: HTMLElement, onChange: () => void): () => void;

package/dist/inspector/overlay/selectedGeometry.js

@@ -1,14 +1,7 @@
 import { getElementWindow } from "../runtime/domRealm.js";
-/**
- * Watches the small set of browser events that can change a selected element's
- * viewport rect without changing its selection identity. Structural gestures
- * can move a selected element between containers, so the child-list observer
- * follows the element's current parent after each mutation.
- */
+/** Follows the element's current parent after mutations, since gestures can move it between containers. */
 export function observeSelectedGeometry(element, onChange) {
     const view = getElementWindow(element);
-    // getElementWindow returns the cross-realm Window interface, while the
-    // project-wide browser global also carries the observer constructors.
     // SAFETY: view is a same-realm Window, and the runtime realm exposes the observer constructors as project-wide globals.
     const { ResizeObserver: ResizeObserverCtor, MutationObserver: MutationObserverCtor } = view;
     let frame = null;

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

@@ -1,13 +1,13 @@
 import type { Rect } from "./overlayGeometry.js";
-export type PaddingSide = "top" | "right" | "bottom" | "left";
-export type SpacingKind = "padding" | "gap";
+export type BoxSide = "top" | "right" | "bottom" | "left";
+export type SpacingKind = "padding" | "margin" | "gap";
 export type SpacingAxis = "horizontal" | "vertical";
 export type SpacingDragAxis = "x" | "y";
-export type SpacingProperty = `padding-${PaddingSide}` | "row-gap" | "column-gap";
+export type SpacingProperty = `padding-${BoxSide}` | `margin-${BoxSide}` | "row-gap" | "column-gap";
 export interface SpacingGuideData {
     kind: SpacingKind;
     property: SpacingProperty;
-    side: PaddingSide | null;
+    side: BoxSide | null;
     axis: SpacingAxis;
     dragAxis: SpacingDragAxis;
     value: number;
@@ -16,7 +16,7 @@ export interface SpacingGuideData {
     guide: Rect;
     affectedGuides: Rect[];
     affectedAreas: Rect[];
-    /** A 16px-thick pointer target centred on the visible, up-to-40px guide handle. */
+    /** Pointer target centred on the visible guide handle. */
     hit: Rect;
 }
 export interface SpacingAffordance extends SpacingGuideData {
@@ -25,26 +25,19 @@ export interface SpacingAffordance extends SpacingGuideData {
 export interface SpacingDescriptor {
     kind: SpacingKind;
     property: SpacingProperty;
-    side: PaddingSide | null;
+    side: BoxSide | 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;
-/** Finds the spacing target whose visible padding or gap area contains the
- * pointer, even when the pointer is outside the drag handle. Hover previews use
- * this; drags and the resize cursor still require the handle hit from
- * getSpacingAffordanceAtPoint. */
+/** Hover previews use this; drags and the resize cursor require the handle from getSpacingAffordanceAtPoint. */
 export declare function getSpacingHoverAtPoint(doc: Document, x: number, y: number): SpacingAffordance | null;
-/** Re-resolves a renderer-reported spacing descriptor in its owner document. */
+export declare function getElementSpacingHandleAtPoint(doc: Document, element: HTMLElement, x: number, y: number): SpacingAffordance | null;
+export declare function getElementSpacingAtPoint(doc: Document, element: HTMLElement, x: number, y: number): {
+    handle: SpacingAffordance | null;
+    area: SpacingAffordance | null;
+};
 export declare function getSpacingAffordanceForDescriptor(element: HTMLElement, descriptor: SpacingDescriptor): SpacingAffordance | null;
-/**
- * Calculates a direct-manipulation value, optionally stepping changes by 8px.
- * While Shift is held the value snaps to a step anchor: the first displacement
- * picks the nearest multiple of 8 from the authored value in the drag
- * direction (ties resolve upward), and further movement adds whole 8px steps
- * from that anchor, so the result is always a multiple of 8 once the drag
- * moves. At the exact start point the authored value is preserved.
- */
+/** With Shift, snaps to a multiple of 8 from the authored value in the drag direction. */
 export declare function spacingValueForDrag(affordance: Pick<SpacingAffordance, "dragAxis" | "direction" | "value">, start: {
     x: number;
     y: number;
@@ -53,5 +46,5 @@ export declare function spacingValueForDrag(affordance: Pick<SpacingAffordance,
     y: number;
 }, shiftKey?: boolean): number;
 export declare function spacingValueCss(value: number): string;
-/** Serializes the stable part of an affordance for renderer-to-controller messages. */
+/** The stable subset sent across the renderer boundary. */
 export declare function toSpacingDescriptor(affordance: SpacingAffordance): SpacingDescriptor;