nudge-ui 0.2.4 → 0.2.6

package/dist/inspector/overlay/spacingGestures.js

@@ -18,8 +18,7 @@ function boxEdges(element) {
         bottom: bottomOf(rect),
     };
 }
-// Computed style resolves to px in browsers, so drag math normalizes to px.
-// An authored rem/% is intentionally rewritten as px on commit.
+// Computed style is px; an authored rem/% is intentionally rewritten as px on commit.
 function numberValue(value) {
     const parsed = Number.parseFloat(value);
     return Number.isFinite(parsed) ? Math.max(0, parsed) : 0;
@@ -32,6 +31,12 @@ function boxModel(element) {
         bottom: numberValue(style.paddingBottom),
         left: numberValue(style.paddingLeft),
     };
+    const margin = {
+        top: numberValue(style.marginTop),
+        right: numberValue(style.marginRight),
+        bottom: numberValue(style.marginBottom),
+        left: numberValue(style.marginLeft),
+    };
     const border = {
         top: numberValue(style.borderTopWidth),
         right: numberValue(style.borderRightWidth),
@@ -51,7 +56,7 @@ function boxModel(element) {
         right: inner.right - padding.right,
         bottom: inner.bottom - padding.bottom,
     };
-    return { outer, inner, content, padding };
+    return { outer, inner, content, padding, margin };
 }
 function containsPoint(rect, x, y) {
     return x >= rect.left && x <= rect.right && y >= rect.top && y <= rect.bottom;
@@ -143,14 +148,93 @@ function paddingAffordanceAtPoint(element, x, y) {
     const model = boxModel(element);
     if (!containsPoint(model.outer, x, y))
         return null;
-    const sides = ["top", "right", "bottom", "left"];
-    for (const side of sides) {
+    for (const side of SIDES) {
         const affordance = paddingAffordanceForSide(element, side, model);
         if (affordance && containsRectPoint(affordance.hit, x, y))
             return affordance;
     }
     return null;
 }
+const MARGIN_CONFIG = {
+    top: { axis: "horizontal", dragAxis: "y", direction: -1 },
+    right: { axis: "vertical", dragAxis: "x", direction: 1 },
+    bottom: { axis: "horizontal", dragAxis: "y", direction: 1 },
+    left: { axis: "vertical", dragAxis: "x", direction: -1 },
+};
+const SIDES = ["top", "right", "bottom", "left"];
+/** Children further than this from the pointer are skipped before their styles are read. */
+const MARGIN_SCAN_DISTANCE = 512;
+/** The margin band sits outside the border box, so a drag outward (away from the element) grows it. */
+function marginAffordanceForSide(element, side, model = boxModel(element)) {
+    const { outer, margin } = model;
+    const value = margin[side];
+    if (value <= EPSILON)
+        return null;
+    const config = MARGIN_CONFIG[side];
+    const width = Math.max(0, outer.right - outer.left);
+    const height = Math.max(0, outer.bottom - outer.top);
+    const guide = config.axis === "horizontal"
+        ? { left: outer.left, top: (side === "top" ? outer.top - value / 2 : outer.bottom + value / 2) - 1, width, height: 2 }
+        : { left: (side === "left" ? outer.left - value / 2 : outer.right + value / 2) - 1, top: outer.top, width: 2, height };
+    const area = config.axis === "horizontal"
+        ? { left: outer.left, top: side === "top" ? outer.top - value : outer.bottom, width, height: value }
+        : { left: side === "left" ? outer.left - value : outer.right, top: outer.top, width: value, height };
+    return {
+        kind: "margin",
+        property: `margin-${side}`,
+        side,
+        axis: config.axis,
+        dragAxis: config.dragAxis,
+        value,
+        cursor: config.axis === "horizontal" ? "ns-resize" : "ew-resize",
+        guide,
+        affectedGuides: [guide],
+        affectedAreas: [area],
+        hit: guideHit(guide, config.axis),
+        direction: config.direction,
+        element,
+    };
+}
+function isTrackedElement(element, constructor) {
+    return element instanceof constructor && element.hasAttribute("data-cid");
+}
+function isNearPoint(rect, x, y) {
+    return x >= rect.left - MARGIN_SCAN_DISTANCE
+        && x <= rightOf(rect) + MARGIN_SCAN_DISTANCE
+        && y >= rect.top - MARGIN_SCAN_DISTANCE
+        && y <= bottomOf(rect) + MARGIN_SCAN_DISTANCE;
+}
+/**
+ * A margin lies outside its element, so the pointer over it hits the parent: the
+ * element's own margins and its tracked children's margins are both candidates.
+ */
+function marginAffordanceAtPoint(element, x, y, includeChildren, match) {
+    const HTMLElementConstructor = element.ownerDocument.defaultView?.HTMLElement;
+    if (!HTMLElementConstructor)
+        return null;
+    const owners = [
+        element,
+        ...(includeChildren
+            ? Array.from(element.children).filter((child) => isTrackedElement(child, HTMLElementConstructor))
+            : []),
+    ];
+    for (const owner of owners) {
+        if (owner !== element && !isNearPoint(owner.getBoundingClientRect(), x, y))
+            continue;
+        const model = boxModel(owner);
+        for (const side of SIDES) {
+            const affordance = marginAffordanceForSide(owner, side, model);
+            if (!affordance)
+                continue;
+            const hit = match === "handle"
+                ? containsRectPoint(affordance.hit, x, y)
+                : affordance.affectedAreas.some((area) => containsRectPoint(area, x, y));
+            if (hit)
+                return affordance;
+        }
+    }
+    return null;
+}
 function overlap(startA, endA, startB, endB) {
     return Math.min(endA, endB) - Math.max(startA, startB) > EPSILON;
 }
@@ -263,15 +347,12 @@ function gapDragHit(segment) {
     const orientation = segment.axis === "horizontal" ? "vertical" : "horizontal";
     return guideHit(gapGuide(segment), orientation);
 }
-/** Matches the padding bar whose visible area contains the pointer, whether or
- * not the point is inside the drag handle. Returns the first side by the same
- * priority order as the drag affordances so both paths agree on overlaps. */
+/** Matches the padding bar's visible area; same side priority as the drag handles. */
 function paddingAffordanceInAreaAtPoint(element, x, y) {
     const model = boxModel(element);
     if (!containsPoint(model.outer, x, y))
         return null;
-    const sides = ["top", "right", "bottom", "left"];
-    for (const side of sides) {
+    for (const side of SIDES) {
         const affordance = paddingAffordanceForSide(element, side, model);
         if (affordance
             && affordance.affectedAreas.some((area) => containsRectPoint(area, x, y))) {
@@ -280,9 +361,7 @@ function paddingAffordanceInAreaAtPoint(element, x, y) {
     }
     return null;
 }
-/** Matches a layout gap whose visible area contains the pointer, whether or not
- * the point is inside the drag handle. Shares segment priority and geometry
- * with gapAffordanceAtPoint so hover and drag agree on crossed gap properties. */
+/** Matches a layout gap's visible area; shares segment priority with gapAffordanceAtPoint. */
 function gapAffordanceInAreaAtPoint(element, x, y) {
     const segments = gapSegments(element);
     if (segments.length === 0)
@@ -314,9 +393,7 @@ function gapValue(style, property) {
         || (property === "row-gap" ? style.rowGap : style.columnGap);
     if (direct.trim())
         return numberValue(direct);
-    // jsdom and a few older browser CSSOM implementations expose `gap` but not
-    // the longhands through getPropertyValue(). Keep the gesture model aligned
-    // with the browser's shorthand fallback in those realms.
+    // jsdom and some CSSOM implementations expose only the `gap` shorthand.
     const shorthand = style.getPropertyValue("gap") || style.gap;
     const values = shorthand.trim().split(/\s+/).filter(Boolean);
     if (values.length === 0)
@@ -344,7 +421,6 @@ function trackedElementsAtPoint(doc, x, y) {
     }
     return result;
 }
-/** Finds the spacing target under a document-local pointer location. */
 export function getSpacingAffordanceAtPoint(doc, x, y) {
     const candidates = trackedElementsAtPoint(doc, x, y);
     for (const element of candidates) {
@@ -352,6 +428,11 @@ export function getSpacingAffordanceAtPoint(doc, x, y) {
         if (padding)
             return padding;
     }
+    for (const [index, element] of candidates.entries()) {
+        const margin = marginAffordanceAtPoint(element, x, y, index === 0, "handle");
+        if (margin)
+            return margin;
+    }
     for (const element of candidates) {
         const gap = gapAffordanceAtPoint(element, x, y);
         if (gap)
@@ -359,10 +440,7 @@ export function getSpacingAffordanceAtPoint(doc, x, y) {
     }
     return 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 function getSpacingHoverAtPoint(doc, x, y) {
     const candidates = trackedElementsAtPoint(doc, x, y);
     for (const element of candidates) {
@@ -370,6 +448,11 @@ export function getSpacingHoverAtPoint(doc, x, y) {
         if (padding)
             return padding;
     }
+    for (const [index, element] of candidates.entries()) {
+        const margin = marginAffordanceAtPoint(element, x, y, index === 0, "area");
+        if (margin)
+            return margin;
+    }
     for (const element of candidates) {
         const gap = gapAffordanceInAreaAtPoint(element, x, y);
         if (gap)
@@ -377,7 +460,45 @@ export function getSpacingHoverAtPoint(doc, x, y) {
     }
     return null;
 }
-/** Re-resolves a renderer-reported spacing descriptor in its owner document. */
+/** Only descendants of `element` can win: candidates run innermost first and padding beats gaps. */
+function affordanceForElement(candidates, element, padding, margin, gap) {
+    const index = candidates.indexOf(element);
+    if (index < 0)
+        return null;
+    for (let candidate = 0; candidate <= index; candidate++) {
+        const match = padding(candidates[candidate]);
+        if (match)
+            return match.element === element ? match : null;
+    }
+    // A margin belongs to a child of the hovered element (or to the element itself), so its owner may differ from `element`.
+    const marginMatch = margin(element, candidates[0] === element);
+    if (marginMatch)
+        return marginMatch;
+    let gapMatch = null;
+    for (let candidate = 0; candidate <= index && !gapMatch; candidate++) {
+        gapMatch = gap(candidates[candidate]);
+    }
+    if (gapMatch?.element !== element)
+        return null;
+    for (let candidate = index + 1; candidate < candidates.length; candidate++) {
+        if (padding(candidates[candidate]))
+            return null;
+    }
+    return gapMatch;
+}
+function elementSpacingHandle(candidates, element, x, y) {
+    return affordanceForElement(candidates, element, (candidate) => paddingAffordanceAtPoint(candidate, x, y), (candidate, includeChildren) => marginAffordanceAtPoint(candidate, x, y, includeChildren, "handle"), (candidate) => gapAffordanceAtPoint(candidate, x, y));
+}
+export function getElementSpacingHandleAtPoint(doc, element, x, y) {
+    return elementSpacingHandle(trackedElementsAtPoint(doc, x, y), element, x, y);
+}
+export function getElementSpacingAtPoint(doc, element, x, y) {
+    const candidates = trackedElementsAtPoint(doc, x, y);
+    return {
+        handle: elementSpacingHandle(candidates, element, x, y),
+        area: affordanceForElement(candidates, element, (candidate) => paddingAffordanceInAreaAtPoint(candidate, x, y), (candidate, includeChildren) => marginAffordanceAtPoint(candidate, x, y, includeChildren, "area"), (candidate) => gapAffordanceInAreaAtPoint(candidate, x, y)),
+    };
+}
 export function getSpacingAffordanceForDescriptor(element, descriptor) {
     if (descriptor.kind === "padding") {
         const side = descriptor.side;
@@ -385,6 +506,12 @@ export function getSpacingAffordanceForDescriptor(element, descriptor) {
             return null;
         return paddingAffordanceForSide(element, side);
     }
+    if (descriptor.kind === "margin") {
+        const side = descriptor.side;
+        if (!side || descriptor.property !== `margin-${side}`)
+            return null;
+        return marginAffordanceForSide(element, side);
+    }
     if (descriptor.property !== "row-gap" && descriptor.property !== "column-gap")
         return null;
     const segment = gapSegments(element).find((candidate) => candidate.property === descriptor.property);
@@ -393,14 +520,7 @@ export function getSpacingAffordanceForDescriptor(element, descriptor) {
     const guide = gapGuide(segment);
     return gapAffordanceAtPoint(element, guide.left + guide.width / 2, guide.top + guide.height / 2, descriptor.property);
 }
-/**
- * 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 function spacingValueForDrag(affordance, start, point, shiftKey = false) {
     const delta = affordance.dragAxis === "x" ? point.x - start.x : point.y - start.y;
     const signedDelta = delta * affordance.direction;
@@ -418,7 +538,7 @@ export function spacingValueForDrag(affordance, start, point, shiftKey = false)
 export function spacingValueCss(value) {
     return `${Math.max(0, Math.round(value))}px`;
 }
-/** Serializes the stable part of an affordance for renderer-to-controller messages. */
+/** The stable subset sent across the renderer boundary. */
 export function toSpacingDescriptor(affordance) {
     return {
         kind: affordance.kind,

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

@@ -1,11 +1,7 @@
 import type { SelectedElement } from "../selection/selectionStore.js";
 import { type StructuralDelete, type StructuralMove } from "../projection/structuralProjection.js";
 export type StructuralNudgeKey = "ArrowUp" | "ArrowDown" | "ArrowLeft" | "ArrowRight";
-/**
- * A temporary, document-local insertion point. It is intentionally not a
- * structural record: `moveElement` captures durable rendered-instance refs
- * before handing the canonical action to structuralProjection.
- */
+/** Temporary, document-local insertion point; canonical moves capture durable rendered-instance refs instead. */
 export interface DropLocation {
     parent: HTMLElement;
     before: Node | null;
@@ -15,14 +11,11 @@ export interface DropLocation {
     width: number;
     height: number;
 }
-/** Conservative HTML guard shared with canonical capture and document replay. */
+/** Delegates to the guard shared with canonical capture and document replay. */
 export declare function canContainElement(parent: HTMLElement, child: HTMLElement): boolean;
-/** Derives a safe insertion point; its nodes never leave this gesture module. */
 export declare function getDropLocationForElement(dragged: HTMLElement, target: HTMLElement, beforeTarget: boolean, preferContainer?: boolean): DropLocation | null;
 export declare function getDropLocationAtPoint(doc: Document, dragged: HTMLElement, x: number, y: number): DropLocation | null;
-/** Capture the move as canonical intent, then preview it in an inline host. */
 export declare function moveElement(node: HTMLElement, destination: DropLocation): StructuralMove | null;
 /** Reorder only same-parent siblings; horizontal movement needs a flex row. */
 export declare function nudgeElement(node: HTMLElement, key: StructuralNudgeKey): StructuralMove | null;
-/** Capture delete intent, then preview it in an inline host. */
 export declare function deleteElement(selected: SelectedElement): StructuralDelete | null;

package/dist/inspector/overlay/structuralGestures.js

@@ -1,6 +1,6 @@
 import { applyStructuralProjection, canContainElement as canContainStructuralElement, createStructuralDelete, createStructuralMove, getStructuralMoveLegality, getStructuralChanges, } from "../projection/structuralProjection.js";
 import { isEditorShellDocument } from "../runtime/editorShell.js";
-/** Conservative HTML guard shared with canonical capture and document replay. */
+/** Delegates to the guard shared with canonical capture and document replay. */
 export function canContainElement(parent, child) {
     return canContainStructuralElement(parent, child);
 }
@@ -96,7 +96,6 @@ function flexRowChildAtTarget(dragged, target) {
     }
     return null;
 }
-/** Derives a safe insertion point; its nodes never leave this gesture module. */
 export function getDropLocationForElement(dragged, target, beforeTarget, preferContainer = true) {
     if (target === dragged || dragged.contains(target))
         return null;
@@ -147,7 +146,6 @@ function projectInlineHost(node) {
         return;
     applyStructuralProjection(document, getStructuralChanges());
 }
-/** Capture the move as canonical intent, then preview it in an inline host. */
 export function moveElement(node, destination) {
     if (!getStructuralMoveLegality(node, destination).valid)
         return null;
@@ -170,7 +168,6 @@ export function nudgeElement(node, key) {
     const before = moveEarlier ? sibling : sibling.nextElementSibling;
     return moveElement(node, { parent, before, ...lineFor(parent, before) });
 }
-/** Capture delete intent, then preview it in an inline host. */
 export function deleteElement(selected) {
     const node = selected.domElement;
     if (!node.parentElement || !node.isConnected)

package/dist/inspector/pageInspector.d.ts

@@ -0,0 +1,33 @@
+import { type InspectorStorage } from "./runtime/inspectorStorage.js";
+import { type SketchStorage } from "./sketch/persistence.js";
+export type { InspectorStorage } from "./runtime/inspectorStorage.js";
+export { createMirroredStorage } from "./runtime/inspectorStorage.js";
+export type { SketchPersistenceSnapshot, SketchStorage, SketchStorageChange } from "./sketch/persistence.js";
+export { isSketchDocument, isSketchHandoffRecord } from "./sketch/model.js";
+export type { SketchDocument, SketchHandoffRecord } from "./sketch/model.js";
+export interface PageInspectorOptions {
+    /** Replaces `localStorage` for comments, drafts, and Canvas state. */
+    storage?: InspectorStorage;
+    /** Replaces the page origin's IndexedDB for sketch documents and handoffs. */
+    sketchStorage?: SketchStorage;
+    /** Skips the `<style>` policy probe and always uses constructable stylesheets. */
+    adoptStylesheets?: boolean;
+    /** `"editor"` requires the editor URL marker; otherwise the page itself is the only Canvas card. */
+    surface?: "editor" | "page";
+    /** Shows a short error instead of enabling inspection on an unsupported page. */
+    unavailableReason?: string;
+    /** Called whenever an editor renderer frame's document finishes parsing. */
+    onRendererFrameLoad?: () => void;
+}
+/** Published on `window` so a second injection toggles the first instance. */
+export interface PageInspectorHandle {
+    readonly surface: "editor" | "page" | "renderer";
+    /** Toggles the page inspector, or leaves the editor. */
+    toggle(): void;
+    /** Starts the `window.__nudgeUiPerformance` counters for this document. */
+    enablePerformanceDiagnostics(): void;
+}
+/** A second bundle copy in the same window toggles the first instance, whose stores own the UI. */
+export declare function startPageInspector(options?: PageInspectorOptions): Promise<void>;
+/** Only acts inside an editor Canvas frame that has no renderer yet. */
+export declare function startCanvasRenderer(options?: Pick<PageInspectorOptions, "adoptStylesheets">): void;