nudge-ui 0.2.5 → 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

@@ -3,6 +3,7 @@ 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. */
@@ -11,10 +12,7 @@ export interface PageInspectorOptions {
     sketchStorage?: SketchStorage;
     /** Skips the `<style>` policy probe and always uses constructable stylesheets. */
     adoptStylesheets?: boolean;
-    /**
-     * `"editor"` turns a document whose URL carries the editor marker into the
-     * iframe editor; otherwise the page itself is the only Canvas card.
-     */
+    /** `"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;
@@ -29,14 +27,7 @@ export interface PageInspectorHandle {
     /** Starts the `window.__nudgeUiPerformance` counters for this document. */
     enablePerformanceDiagnostics(): void;
 }
-/**
- * Starts the inspector on the current page. Running a second bundle copy in
- * the same window toggles the first instance instead, because only the first
- * copy's stores drive the UI.
- */
+/** 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>;
-/**
- * Starts the renderer in an editor's Canvas frame. Does nothing in any other
- * document, or when the frame already runs one.
- */
+/** Only acts inside an editor Canvas frame that has no renderer yet. */
 export declare function startCanvasRenderer(options?: Pick<PageInspectorOptions, "adoptStylesheets">): void;

package/dist/inspector/pageInspector.js

@@ -1,13 +1,4 @@
-/**
- * Entry for loading the inspector into any page without a host Adapter.
- *
- * Everything a host normally supplies is derived from the live document:
- * runtime identity is assigned lazily under the pointer, and tokens come from
- * readable stylesheets plus the root's computed custom properties. Source
- * locations, component semantics, iterations, and the agent bridge are
- * unavailable. In editor mode the application runs in Canvas frames;
- * otherwise the page itself is the only Canvas card.
- */
+/** Loads the inspector into a page without a host Adapter; everything a host normally supplies is derived from the live document. */
 import { bootstrapNudgeUi, configureNudgeUiRuntime, getNudgeUiRuntimeConfig, isCanvasRenderer, readNudgeUiEditorTarget, setInspectorOpen, unmountInspector, } from "./index.js";
 import { CANVAS_RENDERER_ATTR } from "./canvas/roleDetection.js";
 import { releaseLease } from "./canvas/workspaceLease.js";
@@ -20,6 +11,7 @@ import { enableInspectionPerformanceDiagnostics } from "./inspection/performance
 import { installLazyRuntimeIdentity } from "./runtime/staticHtmlRuntimeIdentity.js";
 import { createTokenInventory } from "../css/token-inventory/inventory.js";
 export { createMirroredStorage } from "./runtime/inspectorStorage.js";
+export { isSketchDocument, isSketchHandoffRecord } from "./sketch/model.js";
 const MOUNT_ID = "nudge-ui-root";
 const LOADED_FLAG = "__NUDGE_UI_PAGE_INSPECTOR__";
 const COMPUTED_ROOT_ID = "computed:root";
@@ -60,11 +52,7 @@ async function collectSheet(sheet, index, base) {
         return { id, readError: "cross-origin stylesheet without CORS access" };
     }
 }
-/**
- * Custom properties visible on the root element but absent from readable
- * stylesheets: definitions in cross-origin sheets without CORS, scoped theme
- * rules the inventory rejects, or variables set from JavaScript.
- */
+/** Root custom properties missing from readable stylesheets: CORS-blocked sheets, rejected scoped rules, or JS-set variables. */
 function computedRootDeclarations(doc, definedNames) {
     const declarations = [];
     const view = doc.defaultView ?? window;
@@ -153,7 +141,7 @@ function runtimeConfig(tokens, unavailableReason) {
         framework: "HTML",
         stylingSystem: "CSS custom properties",
         capabilities: { canvas: !unavailableReason, componentSemantics: false, domNavigation: !unavailableReason },
-        features: { canvasIterations: false, ...(unavailableReason ? { sketch: false } : {}) },
+        features: { canvasIterations: false, mcp: false, ...(unavailableReason ? { sketch: false } : {}) },
         ...(unavailableReason ? { inspectionUnavailableReason: unavailableReason } : {}),
         componentContracts: [],
         ...tokens,
@@ -194,11 +182,10 @@ function mountPageInspector() {
             enable();
     };
 }
-/**
- * Replaces the page's content with the iframe editor. The application runs in
- * Canvas renderer frames, which the caller loads the inspector into.
- */
+/** Replaces the page content with the iframe editor; the caller loads the inspector into its renderer frames. */
 function mountEditor(onRendererFrameLoad) {
+    // The editor never owns the tab title; it shows the application's own title.
+    const pageTitle = document.title;
     document.head.replaceChildren();
     document.body.replaceChildren();
     for (const element of [document.documentElement, document.body]) {
@@ -206,7 +193,7 @@ function mountEditor(onRendererFrameLoad) {
         element.removeAttribute("hidden");
         element.removeAttribute("inert");
     }
-    document.title = "Nudge UI";
+    document.title = pageTitle;
     const layout = new CSSStyleSheet();
     layout.replaceSync(`html, body, #${MOUNT_ID} { display: block; width: 100%; height: 100%; margin: 0; overflow: hidden; }`);
     document.adoptedStyleSheets = [layout];
@@ -240,7 +227,21 @@ function mountEditor(onRendererFrameLoad) {
             onRendererFrameLoad?.();
         }
     };
-    window.setInterval(announceReadyDocuments, 100);
+    // Mirrors the primary application frame's title, which follows its navigation.
+    const syncApplicationTitle = () => {
+        for (const frame of frames()) {
+            const frameTitle = applicationDocument(frame)?.title;
+            if (frameTitle) {
+                if (document.title !== frameTitle)
+                    document.title = frameTitle;
+                return;
+            }
+        }
+    };
+    window.setInterval(() => {
+        announceReadyDocuments();
+        syncApplicationTitle();
+    }, 100);
     // Script-built styles exist only in the application frames, not in this document.
     const collectFrameTokens = (frame) => {
         const frameDocument = applicationDocument(frame);
@@ -267,15 +268,10 @@ function mountEditor(onRendererFrameLoad) {
     new MutationObserver(watch).observe(root, { childList: true, subtree: true });
     watch();
 }
-/** Leaves the editor by loading the application URL it frames. */
 function exitEditor() {
     location.replace(readNudgeUiEditorTarget(location.href) ?? location.href);
 }
-/**
- * Starts the inspector on the current page. Running a second bundle copy in
- * the same window toggles the first instance instead, because only the first
- * copy's stores drive the UI.
- */
+/** A second bundle copy in the same window toggles the first instance, whose stores own the UI. */
 export async function startPageInspector(options = {}) {
     const target = window;
     const loaded = target[LOADED_FLAG];
@@ -309,10 +305,7 @@ export async function startPageInspector(options = {}) {
     console.info(`[nudge-ui] Inspector loaded in ${editor ? "editor" : "page"} mode with ${tokens.tokenCatalog.length} tokens`
         + (tokens.tokenDiagnostics.length > 0 ? ` and ${tokens.tokenDiagnostics.length} stylesheet diagnostics.` : "."), tokens.tokenDiagnostics);
 }
-/**
- * Starts the renderer in an editor's Canvas frame. Does nothing in any other
- * document, or when the frame already runs one.
- */
+/** Only acts inside an editor Canvas frame that has no renderer yet. */
 export function startCanvasRenderer(options = {}) {
     const target = window;
     if (!isCanvasRenderer() || target[LOADED_FLAG])

package/dist/inspector/projection/cssEscapes.d.ts

@@ -1,3 +1,2 @@
-/** CSS-string escaping for selectors assembled from runtime DOM metadata. */
 export declare function escapeCssString(value: string): string;
 export declare function escapeAttrValue(value: string): string;

package/dist/inspector/projection/cssEscapes.js

@@ -1,8 +1,6 @@
-/** CSS-string escaping for selectors assembled from runtime DOM metadata. */
 export function escapeCssString(value) {
-    // Keep ordinary source selectors readable and byte-compatible. Once a
-    // string contains a quote, backslash, or control character, hex-escape the
-    // complete value so punctuation cannot terminate the CSS string early.
+    // Keep ordinary selectors byte-compatible; a value containing a quote,
+    // backslash, or control character is hex-escaped whole to prevent an early string end.
     if (!/["\\\0-\x1f\x7f]/.test(value))
         return value;
     let escaped = "";

package/dist/inspector/projection/draftProjection.d.ts

@@ -15,7 +15,6 @@ export interface CompiledManagedStyles {
 export interface SerializedManagedStyles {
     readonly css: string;
 }
-/** A complete, read-only projection for one document-local runtime. */
 export interface DraftProjectionPlan<ManagedStyles> {
     readonly sourceRevision: number;
     readonly managedStyles: ManagedStyles;
@@ -23,13 +22,9 @@ export interface DraftProjectionPlan<ManagedStyles> {
     readonly structuralChanges: readonly StructuralChange[];
     readonly textContentChanges: readonly TextContentChangeRecord[];
     readonly componentOverrides: readonly ComponentOverride[];
-    /**
-     * Generated identities the saved edits refer to. Omitted by plans that
-     * only hide edits (hold-to-view-original), which keep the attached ones.
-     */
+    /** Omitted by hold-to-view-original plans, which keep the attached identities. */
     readonly runtimeIdentities?: readonly RuntimeIdentityClaim[];
 }
-/** Applies every projection dimension to one document-local runtime. */
 export interface DocumentProjectionAdapter<ManagedStyles> {
     applyRuntimeIdentities(claims: readonly RuntimeIdentityClaim[]): void;
     applyStructural(changes: readonly StructuralChange[]): void;
@@ -39,13 +34,6 @@ export interface DocumentProjectionAdapter<ManagedStyles> {
     applyManagedStyles(styles: ManagedStyles): void;
 }
 export declare function compileDraftProjection(snapshot: DraftProjectionSource): DraftProjectionPlan<CompiledManagedStyles>;
-/**
- * Replaces one document projection in the required order.
- *
- * Generated identities are attached first: every selector and resolver below
- * looks elements up by them. Structural intent follows because later rendered-instance evidence
- * can depend on the restored element order. Managed CSS is applied last so
- * selectors can use the document-local instance markers installed above.
- */
+/** Order matters: identities first (selectors resolve by them), then structural, then managed CSS last (selectors use the instance markers above). */
 export declare function applyDraftProjection<ManagedStyles>(adapter: DocumentProjectionAdapter<ManagedStyles>, plan: DraftProjectionPlan<ManagedStyles>): void;
 export declare function applyHostDraftProjection(plan: DraftProjectionPlan<CompiledManagedStyles>): void;

package/dist/inspector/projection/draftProjection.js

@@ -26,14 +26,7 @@ export function compileDraftProjection(snapshot) {
         runtimeIdentities: collectRuntimeIdentityClaims(snapshot),
     };
 }
-/**
- * Replaces one document projection in the required order.
- *
- * Generated identities are attached first: every selector and resolver below
- * looks elements up by them. Structural intent follows because later rendered-instance evidence
- * can depend on the restored element order. Managed CSS is applied last so
- * selectors can use the document-local instance markers installed above.
- */
+/** Order matters: identities first (selectors resolve by them), then structural, then managed CSS last (selectors use the instance markers above). */
 export function applyDraftProjection(adapter, plan) {
     if (plan.runtimeIdentities)
         adapter.applyRuntimeIdentities(plan.runtimeIdentities);

package/dist/inspector/projection/managedStylesheet.d.ts

@@ -20,14 +20,8 @@ export interface PreviewResult {
 }
 export declare function ensureManagedSheet(): void;
 export declare function rulesToCssText(rules: StyleRule[]): string;
-/** Synchronous serialized view of the rules currently projected into the managed sheet. */
 export declare function getManagedSheetText(): string;
-/**
- * Replaces the managed sheet with the canonical projection. Keeping the
- * serialized rules authoritative avoids stale CSSStyleRule references when a
- * framework dev server reparses or reattaches style nodes during a render.
- */
+/** Serialized rules stay authoritative to avoid stale CSSStyleRule references when a framework reparses style nodes. */
 export declare function applyRules(rules: StyleRule[]): void;
-/** Verify what the browser painted after the managed sheet was projected. */
 export declare function verifyPreview(el: HTMLElement | null, property: string, requestedValue: string): PreviewResult;
 export declare function removeManagedSheet(): void;