nudge-ui 0.2.4 → 0.2.6

package/dist/inspector/changes/previewDiagnostics.js

@@ -1,4 +1,4 @@
-import { getActiveDraftChanges, getDraftChanges } from "./draftChanges.js";
+import { getActiveDraftChanges, getDraftChanges } from "../drafts/store.js";
 const HOST_DOCUMENT = {
     logicalDocument: "host",
     sessionId: "host-document",
@@ -25,11 +25,9 @@ function notify() {
     for (const listener of listeners)
         listener();
 }
-/** Returns the stable host-document identity for this inspector lifetime. */
 export function getHostPreviewDocument() {
     return { ...HOST_DOCUMENT, draftId: getActiveDraftChanges().draftId };
 }
-/** Starts or replaces the live session for one logical document. */
 export function startPreviewDocumentSession(document) {
     const previousSession = activeSessions.get(document.logicalDocument);
     if (previousSession === document.sessionId)
@@ -46,7 +44,7 @@ export function startPreviewDocumentSession(document) {
     if (changed || previousSession !== undefined)
         notify();
 }
-/** Invalidates a live document session and rejects all of its late results. */
+/** Late results from an invalidated session are rejected. */
 export function invalidatePreviewDocumentSession(logicalDocument, sessionId) {
     const activeSession = activeSessions.get(logicalDocument);
     if (activeSession === undefined || (sessionId !== undefined && activeSession !== sessionId))
@@ -63,7 +61,6 @@ export function invalidatePreviewDocumentSession(logicalDocument, sessionId) {
     if (changed || activeSession !== undefined)
         notify();
 }
-/** Opens a verification attempt for the currently active document session. */
 export function beginPreviewAttempt(document, revision = getDraftChanges(document.draftId ?? getActiveDraftChanges().draftId).revision) {
     const draftId = document.draftId ?? getActiveDraftChanges().draftId;
     if (revision !== getDraftChanges(draftId).revision || activeSessions.get(document.logicalDocument) !== document.sessionId) {
@@ -71,13 +68,9 @@ export function beginPreviewAttempt(document, revision = getDraftChanges(documen
     }
     const attempt = (attemptsBySession.get(sessionKey(document)) ?? 0) + 1;
     attemptsBySession.set(sessionKey(document), attempt);
-    // Do not delete existing diagnostics here. The attempt stamp already
-    // rejects late publishes per key; wiping would drop every other change's
-    // status before it is re-verified (and drop all host status when Canvas
-    // verification returns null).
+    // The attempt stamp already rejects late publishes per key; wiping here would drop other changes' statuses before re-verification.
     return { ...document, draftId, draftRevision: revision, attempt };
 }
-/** Publishes only a result from the active revision, session, and attempt. */
 export function publishPreviewDiagnostic(attempt, changeKey, result) {
     if (attempt.draftRevision !== getDraftChanges(attempt.draftId).revision
         || activeSessions.get(attempt.logicalDocument) !== attempt.sessionId
@@ -97,7 +90,6 @@ export function publishPreviewDiagnostic(attempt, changeKey, result) {
     notify();
     return true;
 }
-/** Removes diagnostics for the supplied canonical keys across live documents. */
 export function clearPreviewDiagnostics(changeKeys) {
     const keys = changeKeys ? new Set(changeKeys) : null;
     let changed = false;
@@ -110,25 +102,17 @@ export function clearPreviewDiagnostics(changeKeys) {
     if (changed)
         notify();
 }
-/** Notifies consumers when verification state changes without a result. */
 export function notifyPreviewDiagnostics() {
     notify();
 }
 export function getPreviewDiagnostic(changeKey, logicalDocument = HOST_DOCUMENT.logicalDocument, draftId = getActiveDraftChanges().draftId) {
-    // Pure getter: never sync or notify. It runs on the React render path via
-    // StaleChangeIndicator, so side effects here would clear state mid-render.
-    // Diagnostics survive workspace revisions until overwritten or explicitly
-    // cleared; publish-time stamps reject stale results per key.
+    // Pure getter: it runs on the React render path, so side effects here would clear state mid-render.
     const sessionId = activeSessions.get(logicalDocument);
     if (!sessionId)
         return undefined;
     return diagnostics.get(storageKey({ logicalDocument, sessionId, draftId }, changeKey));
 }
-/**
- * Host-first read across live documents. The per-document store is observable
- * here so a Canvas-only conflict is not write-only; host remains the default
- * for single-document consumers.
- */
+/** Also reads non-host documents so Canvas-only conflicts are not write-only. */
 export function getAnyPreviewDiagnostic(changeKey) {
     const host = getPreviewDiagnostic(changeKey, HOST_DOCUMENT.logicalDocument);
     if (host)

package/dist/inspector/changes/previewVerification.d.ts

@@ -0,0 +1,25 @@
+import { type ChangeRecord, type PreviewableChangeRecord } from "./types.js";
+import { type PreviewAttempt } from "./previewDiagnostics.js";
+import type { PreviewResult } from "../projection/managedStylesheet.js";
+/** The two effects the cycle performs; tests replace them to observe sequencing. */
+export interface PreviewVerificationEffects {
+    verify(change: PreviewableChangeRecord, target: HTMLElement | null, document: Document): PreviewResult | null;
+    publish(attempt: PreviewAttempt, key: string, result: PreviewResult): void;
+}
+export interface PreviewVerificationRequest {
+    /** The full surviving change set: cascade and specificity make earlier results depend on later rules. */
+    readonly changes: readonly ChangeRecord[];
+    readonly document: Document;
+    readonly attempt: PreviewAttempt;
+    /** Resolves the element a change was committed against; null verifies against the document alone. */
+    readonly targetFor: (change: PreviewableChangeRecord) => HTMLElement | null;
+    /** False when a newer revision replaced this attempt. */
+    readonly isCurrent?: () => boolean;
+    /** Runs a follow-up check after the browser settles an animation; omitted to skip the retry. */
+    readonly retryAnimation?: (run: () => void) => void;
+}
+/**
+ * Owns the verify-and-publish cycle shared by the host document and Canvas frames:
+ * one preview attempt, every previewable change, one diagnostic per conflict.
+ */
+export declare function verifyPreviewChanges(request: PreviewVerificationRequest, effects?: PreviewVerificationEffects): void;

package/dist/inspector/changes/previewVerification.js

@@ -0,0 +1,34 @@
+import { changeKey } from "./model.js";
+import { verifyManagedStyleProjection } from "./managedStyleProjection.js";
+import { isPreviewableChange } from "./types.js";
+import { publishPreviewDiagnostic } from "./previewDiagnostics.js";
+const defaultEffects = {
+    verify: (change, target, document) => verifyManagedStyleProjection(change, target, document),
+    publish: (attempt, key, result) => publishPreviewDiagnostic(attempt, key, result),
+};
+/**
+ * Owns the verify-and-publish cycle shared by the host document and Canvas frames:
+ * one preview attempt, every previewable change, one diagnostic per conflict.
+ */
+export function verifyPreviewChanges(request, effects = defaultEffects) {
+    for (const change of request.changes) {
+        if (!isPreviewableChange(change))
+            continue;
+        const result = effects.verify(change, request.targetFor(change), request.document);
+        if (!result)
+            continue;
+        effects.publish(request.attempt, changeKey(change), result);
+        if (result.status === "conflict" && result.reason === "animation") {
+            scheduleSettledRetry(request, change, effects);
+        }
+    }
+}
+function scheduleSettledRetry(request, change, effects) {
+    request.retryAnimation?.(() => {
+        if (request.isCurrent && !request.isCurrent())
+            return;
+        const settled = effects.verify(change, request.targetFor(change), request.document);
+        if (settled)
+            effects.publish(request.attempt, changeKey(change), settled);
+    });
+}

package/dist/inspector/changes/structuralTypes.d.ts

@@ -1,15 +1,13 @@
 import type { RenderedInstanceRef } from "./editModel.js";
-/** Controller-owned intent to remove one rendered instance. */
 export interface StructuralDelete {
     id: string;
     kind: "delete";
     target: RenderedInstanceRef;
     /** Hash-independent route where the target was captured. */
     route?: string;
-    /** Bounded view identity where the target was captured. */
+    /** View identity where the target was captured. */
     state?: string;
 }
-/** Controller-owned intent to move one rendered instance. */
 export interface StructuralMove {
     id: string;
     kind: "move";
@@ -34,6 +32,6 @@ export type StructuralProjectionReason = "target" | "source-parent" | "destinati
 export interface StructuralProjectionReport {
     changeId: string;
     status: StructuralProjectionStatus;
-    /** Bounded diagnostic data; it never changes canonical structural intent. */
+    /** Diagnostic only; never changes canonical structural intent. */
     reason?: StructuralProjectionReason;
 }

package/dist/inspector/changes/types.d.ts

@@ -1,22 +1,25 @@
 import type { TokenEntry } from "../../css/model/index.js";
 import type { ComponentChangeRecord } from "../componentSemantics/types.js";
 import type { EditScope, RenderedInstanceOverride, StyleRuleContext, TextContentChangeRecord } from "./editModel.js";
-/** Bounded rendered facts retained for one element without an authored source location. */
 export interface RuntimeElementEvidence {
-    /**
-     * Why the location is unknown; prompts phrase their guidance accordingly.
-     * Omitted by legacy records, which are all runtime-created DOM.
-     */
+    /** Omitted by legacy records, which are all runtime-created DOM. */
     reason?: "runtime-created" | "unannotated";
     tagName: string;
     text: string | null;
     props: string | null;
     ariaLabel: string | null;
+    /** Nearest-ancestor selector path; omitted by records captured before it existed. */
+    domPath?: string | null;
+    elementId?: string | null;
 }
-/** Bounded authored facts for one annotated element. */
 export interface SourceElementEvidence {
     tagName: string;
     props: string | null;
+    /** Omitted by older saved changes. */
+    text?: string | null;
+    ariaLabel?: string | null;
+    domPath?: string | null;
+    elementId?: string | null;
 }
 export interface ElementChangeRecord {
     kind?: "element";
@@ -27,7 +30,6 @@ export interface ElementChangeRecord {
     column?: number;
     selector: string;
     property: string;
-    /** CSSOM-declared source context that the inspector projection came from. */
     sourceProperty?: string;
     /** Best-effort CSSOM serialization; not an exact source-text quote. */
     sourceAuthoredValue?: string;
@@ -40,11 +42,12 @@ export interface ElementChangeRecord {
         line: number;
         component: string;
     };
-    /** Present when the selected element has a document-local runtime identity. */
     runtimeEvidence?: RuntimeElementEvidence;
     /** Authored facts that relocate the source site after its position shifts. */
     sourceEvidence?: SourceElementEvidence;
     scope?: EditScope;
+    /** Presentation only; absent from older edits. */
+    sourceInstanceCount?: number;
     /** Durable, controller-owned target for one rendered output. */
     instanceOverride?: RenderedInstanceOverride;
     state?: "base" | "hover" | "active" | "focus" | "focus-visible" | "disabled";

package/dist/inspector/clientManifest.d.ts

@@ -1,13 +1,13 @@
 import { type NudgeUiRuntimeConfig } from "./runtime/runtimeConfig.js";
+import { NUDGE_UI_MANIFEST_VERSION } from "../transport/index.js";
 export type { NudgeUiRuntimeConfig, NudgeUiRuntimeFeatures } from "./runtime/runtimeConfig.js";
 export { detectStylingSystem } from "./runtime/runtimeConfig.js";
-/** Version of the host-to-inspector runtime manifest Interface. */
-export declare const NUDGE_UI_CLIENT_MANIFEST_VERSION = 1;
-/** Runtime document consumed by the self-contained inspector client. */
-export interface NudgeUiClientManifest {
+/** The client envelope shares one version with the transport module that serves it. */
+export declare const NUDGE_UI_CLIENT_MANIFEST_VERSION: typeof NUDGE_UI_MANIFEST_VERSION;
+export interface NudgeUiClientManifest<Runtime extends NudgeUiRuntimeConfig = NudgeUiRuntimeConfig> {
     readonly version: typeof NUDGE_UI_CLIENT_MANIFEST_VERSION;
     readonly revision: number;
-    readonly runtime: NudgeUiRuntimeConfig;
+    readonly runtime: Runtime;
     /** Project-owned, loopback-only agent bridge started by the dev host. */
     readonly agentBridge?: {
         readonly baseUrl: string;
@@ -27,5 +27,16 @@ export interface NudgeUiClientManifest {
     /** Set by `NUDGE_UI=1`: automated browsers open the editor instead of the plain app. */
     readonly inspectAutomatedBrowsers?: true;
 }
-/** Parses and normalizes an external manifest before it replaces inspector state. */
+/** Everything host Adapters supply; the envelope fields are owned here. */
+export interface NudgeUiClientManifestInput<Runtime extends NudgeUiRuntimeConfig = NudgeUiRuntimeConfig> {
+    readonly runtime: Runtime;
+    readonly revision?: number;
+    readonly agentBridge?: NudgeUiClientManifest["agentBridge"];
+    readonly document?: NudgeUiClientManifest["document"];
+    readonly reload?: NudgeUiClientManifest["reload"];
+    readonly inspectAutomatedBrowsers?: true;
+}
+/** Builds one envelope so every host publishes the same version and field set. */
+export declare function createNudgeUiClientManifest<Runtime extends NudgeUiRuntimeConfig>(input: NudgeUiClientManifestInput<Runtime>): NudgeUiClientManifest<Runtime>;
+/** Narrows and normalizes an untrusted manifest before it replaces inspector state. */
 export declare function parseNudgeUiClientManifest(value: unknown): NudgeUiClientManifest | null;

package/dist/inspector/clientManifest.js

@@ -1,8 +1,21 @@
 import { normalizeNudgeUiRuntimeConfig, } from "./runtime/runtimeConfig.js";
+import { NUDGE_UI_MANIFEST_VERSION } from "../transport/index.js";
 export { detectStylingSystem } from "./runtime/runtimeConfig.js";
-/** Version of the host-to-inspector runtime manifest Interface. */
-export const NUDGE_UI_CLIENT_MANIFEST_VERSION = 1;
-/** Parses and normalizes an external manifest before it replaces inspector state. */
+/** The client envelope shares one version with the transport module that serves it. */
+export const NUDGE_UI_CLIENT_MANIFEST_VERSION = NUDGE_UI_MANIFEST_VERSION;
+/** Builds one envelope so every host publishes the same version and field set. */
+export function createNudgeUiClientManifest(input) {
+    return {
+        version: NUDGE_UI_CLIENT_MANIFEST_VERSION,
+        revision: input.revision ?? 0,
+        runtime: input.runtime,
+        ...(input.agentBridge ? { agentBridge: input.agentBridge } : {}),
+        ...(input.document ? { document: input.document } : {}),
+        ...(input.reload ? { reload: input.reload } : {}),
+        ...(input.inspectAutomatedBrowsers ? { inspectAutomatedBrowsers: true } : {}),
+    };
+}
+/** Narrows and normalizes an untrusted manifest before it replaces inspector state. */
 export function parseNudgeUiClientManifest(
 // JSON is untrusted at this I/O boundary and is narrowed below.
 // oxlint-disable-next-line anti-slop/no-unknown-parameters

package/dist/inspector/comments/CommentsOverlay.js

@@ -4,7 +4,9 @@ import { IconCheck, IconTrash } from "@tabler/icons-react";
 import { useCanvasMode } from "../canvas/viewStore.js";
 import { getRegisteredFrames } from "../canvas/projection.js";
 import { subscribeCanvasRendererMessages } from "../canvas/rendererMessageRouter.js";
-import { RENDERER_ELEMENT_ID_ATTR } from "../canvas/rendererCidIndex.js";
+import { measureFrameViewport, toViewportPoint } from "../canvas/frameConnection.js";
+import { canvasFrameElement } from "../canvas/canvasFrame.js";
+import { getElementComputedStyle } from "../runtime/domRealm.js";
 import { captureRenderedInstance } from "../projection/renderedInstance.js";
 import { IconButton } from "../ui/IconButton.js";
 import { TextInput } from "../ui/TextInput.js";
@@ -12,21 +14,23 @@ import { commentFingerprint, commentViewport, resolveCommentElement } from "./el
 import { commentRoute, getCommentClearRevision, isCommentToolActive, removeComment, saveComment, subscribeComments, useComments, useCommentToolActive } from "./store.js";
 import { isReadingCommentSource, readCommentSource, reconcileComments } from "./verification.js";
 const styles = ".comment-pin {\n  position: fixed;\n  z-index: 10;\n  display: grid;\n  place-items: center;\n  width: var(--icon-size-large);\n  height: var(--icon-size-large);\n  padding: 0;\n  border: 2px solid var(--surface-raised-2x);\n  border-radius: 50%;\n  background: var(--accent);\n  box-shadow: var(--shadow-popup);\n  cursor: pointer;\n  pointer-events: auto;\n}\n\n.comment-editor-backdrop {\n  position: fixed;\n  inset: 0;\n  z-index: 11;\n  pointer-events: auto;\n}\n\n.comment-editor {\n  position: fixed;\n  z-index: 12;\n  display: flex;\n  align-items: center;\n  gap: var(--space-4);\n  width: min(384px, calc(100vw - 16px));\n  box-sizing: border-box;\n  padding: var(--space-8);\n  border-radius: var(--radius-12);\n  background: var(--surface-raised-2x);\n  box-shadow: var(--shadow-popup);\n  pointer-events: auto;\n}\n\n.comment-editor .text-input { flex: 1; min-width: 0; padding-inline: var(--space-8); }\n.comment-editor__error { position: absolute; top: 100%; left: 0; padding: var(--space-8); background: var(--surface-raised-2x); color: var(--text-primary); border-radius: var(--radius-control); }\n";
+import { InspectorStyle } from "../ui/InspectorStyle.js";
+const CHECK_DELAY_MS = 450;
+const MAX_CHECK_DELAY_MS = 8_000;
 function sameAnchor(left, right) {
     return left?.left === right?.left && left?.top === right?.top;
 }
 function anchorFor(iframe, element) {
     if (!element.isConnected || iframe.contentDocument !== element.ownerDocument)
         return null;
-    // Focus view keeps other frames mounted, but their pins must stay hidden.
-    if (getComputedStyle(iframe).visibility !== "visible")
+    // Focus view keeps real frames mounted, but their pins must stay hidden.
+    const frameElement = canvasFrameElement(iframe);
+    if (frameElement && getElementComputedStyle(frameElement).visibility !== "visible")
         return null;
-    const frame = iframe.getBoundingClientRect();
+    const frame = measureFrameViewport(iframe);
     const rect = element.getBoundingClientRect();
-    const scale = frame.width / (iframe.clientWidth || frame.width);
-    const left = frame.left + rect.right * scale;
-    const top = frame.top + rect.top * scale;
-    if (top < frame.top || top > frame.bottom || left < frame.left || left > frame.right)
+    const { x: left, y: top } = toViewportPoint(frame, { x: rect.right, y: rect.top });
+    if (top < frame.top || top > frame.top + frame.height || left < frame.left || left > frame.left + frame.width)
         return null;
     return { left, top };
 }
@@ -75,17 +79,17 @@ export function CommentsOverlay() {
         window.addEventListener("keydown", dismissOnEscape, true);
         return () => window.removeEventListener("keydown", dismissOnEscape, true);
     }, [draft]);
-    useEffect(() => subscribeCanvasRendererMessages(({ iframe, message }) => {
+    useEffect(() => subscribeCanvasRendererMessages(({ frame, message }) => {
         if (message.type === "element-click" && isCommentToolActive()) {
-            const element = iframe.contentDocument?.querySelector(`[${RENDERER_ELEMENT_ID_ATTR}="${message.elementId}"]`);
-            if (element && element.getAttribute("data-cid") === message.cid && (element.getAttribute("data-src") ?? "") === message.src) {
-                openDraft({ element, iframe });
-            }
+            const element = frame.element(message);
+            if (element)
+                openDraft({ element, iframe: frame.iframe });
         }
         if (message.type === "element-deselect")
             setDraft(null);
-        if (message.type === "frame-ready" && iframe.contentDocument) {
-            void reconcileComments(iframe.contentDocument).catch(() => undefined);
+        const frameDocument = frame.document();
+        if (message.type === "frame-ready" && frameDocument) {
+            void reconcileComments(frameDocument).catch(() => undefined);
         }
     }), []);
     useEffect(() => {
@@ -147,6 +151,35 @@ export function CommentsOverlay() {
     useEffect(() => {
         if (!comments.some((comment) => comment.handedOff))
             return;
+        // A check briefly removes every preview, so checks that resolve nothing back off to avoid flashing on continuously mutating pages.
+        const run = (doc, observation) => {
+            observation.timer = null;
+            if (observation.checking)
+                return;
+            observation.checking = true;
+            void reconcileComments(doc).then((removed) => {
+                observation.interval = removed > 0 ? CHECK_DELAY_MS : Math.min(observation.interval * 2, MAX_CHECK_DELAY_MS);
+            }, () => undefined).finally(() => {
+                observation.lastCheckEndedAt = Date.now();
+                setTimeout(() => {
+                    observation.checking = false;
+                    if (!observation.pending || observations.current.get(doc) !== observation)
+                        return;
+                    observation.pending = false;
+                    schedule(doc, observation);
+                }, 0);
+            });
+        };
+        const schedule = (doc, observation) => {
+            if (observation.checking) {
+                observation.pending = true;
+                return;
+            }
+            if (observation.timer !== null)
+                return;
+            // Let the change that triggered this settle, and keep the backoff interval.
+            observation.timer = setTimeout(() => run(doc, observation), Math.max(CHECK_DELAY_MS, observation.lastCheckEndedAt + observation.interval - Date.now()));
+        };
         const refresh = () => {
             const documents = new Set([...getRegisteredFrames()].map(([, iframe]) => iframe.contentDocument).filter((doc) => doc !== null));
             for (const [doc, observation] of observations.current) {
@@ -171,21 +204,31 @@ export function CommentsOverlay() {
                                 return false;
                             return true;
                         });
-                        if (!sourceChanged)
-                            return;
-                        if (observation.timer)
-                            clearTimeout(observation.timer);
-                        observation.timer = setTimeout(() => { void reconcileComments(doc).catch(() => undefined); }, 200);
-                    }), timer: null };
+                        if (sourceChanged)
+                            schedule(doc, observation);
+                    }), timer: null, checking: false, pending: false, interval: CHECK_DELAY_MS, lastCheckEndedAt: -Infinity };
                 observation.observer.observe(doc.documentElement, { subtree: true, childList: true, characterData: true, attributes: true });
                 observations.current.set(doc, observation);
-                void reconcileComments(doc).catch(() => undefined);
+                run(doc, observation);
+            }
+        };
+        // Returning to the page is when an agent's source edit is most likely to have landed.
+        const returned = () => {
+            for (const [doc, observation] of observations.current) {
+                observation.interval = CHECK_DELAY_MS;
+                observation.lastCheckEndedAt = -Infinity;
+                if (observation.timer)
+                    clearTimeout(observation.timer);
+                observation.timer = null;
+                schedule(doc, observation);
             }
         };
         refresh();
         const timer = setInterval(refresh, 500);
+        window.addEventListener("focus", returned);
         return () => {
             clearInterval(timer);
+            window.removeEventListener("focus", returned);
             for (const observation of observations.current.values()) {
                 observation.observer.disconnect();
                 if (observation.timer)
@@ -239,7 +282,7 @@ export function CommentsOverlay() {
     }
     if (mode !== "canvas")
         return null;
-    return _jsxs(_Fragment, { children: [_jsx("style", { children: styles }), comments.flatMap((comment) => [...anchors].filter(([key]) => key.startsWith(`${comment.id}:`)).map(([key, anchor]) => (_jsx("button", { type: "button", className: "comment-pin", "data-test": "comment-pin", "aria-label": `Comment: ${comment.note}`, title: comment.note, style: anchor, onClick: () => {
+    return _jsxs(_Fragment, { children: [_jsx(InspectorStyle, { css: styles }), comments.flatMap((comment) => [...anchors].filter(([key]) => key.startsWith(`${comment.id}:`)).map(([key, anchor]) => (_jsx("button", { type: "button", className: "comment-pin", "data-test": "comment-pin", "aria-label": `Comment: ${comment.note}`, title: comment.note, style: anchor, onClick: () => {
                     const bound = bindings.current.get(key);
                     if (bound)
                         openDraft({ ...bound, existing: comment });

package/dist/inspector/comments/element.d.ts

@@ -1,6 +1,5 @@
 import type { RenderedInstanceRef } from "../changes/editModel.js";
-/** Retains a changed target only when its source site still identifies one output. */
 export declare function resolveCommentElement(doc: Document, target: RenderedInstanceRef): HTMLElement | null;
 export declare function commentViewport(doc: Document): string;
-/** Captures rendered content and appearance, excluding inspector identity and transient cursors. */
+/** Ignores inspector identity attributes and transient cursor styling. */
 export declare function commentFingerprint(element: HTMLElement): string;

package/dist/inspector/comments/element.js

@@ -1,6 +1,5 @@
 import { resolveRenderedInstance } from "../projection/renderedInstance.js";
 import { relocateSourceSite, sourceSiteSelector } from "../selection/sourceSite.js";
-/** Retains a changed target only when its source site still identifies one output. */
 export function resolveCommentElement(doc, target) {
     const exact = resolveRenderedInstance(doc, target);
     if (exact.status === "resolved")
@@ -28,7 +27,7 @@ export function resolveCommentElement(doc, target) {
 export function commentViewport(doc) {
     return `${doc.defaultView?.innerWidth}:${doc.defaultView?.innerHeight}`;
 }
-/** Captures rendered content and appearance, excluding inspector identity and transient cursors. */
+/** Ignores inspector identity attributes and transient cursor styling. */
 export function commentFingerprint(element) {
     const clone = element.cloneNode(true);
     for (const node of [clone, ...clone.querySelectorAll("*")]) {

package/dist/inspector/comments/store.d.ts

@@ -21,7 +21,7 @@ export declare function removeComment(id: string): void;
 export declare function getCommentClearRevision(): number;
 /** Clears saved notes and invalidates any open or saving comment draft. */
 export declare function clearComments(target?: DraftTarget): void;
-/** Arms only the exact notes successfully copied or accepted by an agent. */
+/** Marks only exact id+note matches, so an edited note is not marked handed off. */
 export declare function markCommentsHandedOff(sent: readonly ElementComment[]): void;
 export declare function setCommentToolActive(active: boolean): void;
 export declare function isCommentToolActive(): boolean;

package/dist/inspector/comments/store.js

@@ -1,3 +1,4 @@
+import { inspectorStorage } from "../runtime/inspectorStorage.js";
 import { useSyncExternalStore } from "react";
 import { isRenderedInstanceRef } from "../changes/editModel.js";
 import { useCanvasCards, useFocusedCardId, useSelectedCardId } from "../canvas/canvasStore.js";
@@ -29,7 +30,7 @@ export function getComments() {
         loadedKey = key;
         loadedDemo = demo;
         try {
-            const saved = demo ? [] : JSON.parse(localStorage.getItem(key) ?? "[]");
+            const saved = demo ? [] : JSON.parse(inspectorStorage()?.getItem(key) ?? "[]");
             comments = Array.isArray(saved) ? saved.filter(isComment) : [];
         }
         catch {
@@ -51,7 +52,7 @@ function publish(next) {
     comments = next;
     if (getNudgeUiRuntimeConfig().demo !== true) {
         try {
-            localStorage.setItem(storageKey(), JSON.stringify(next));
+            inspectorStorage()?.setItem(storageKey(), JSON.stringify(next));
         }
         catch { }
     }
@@ -93,7 +94,7 @@ export function clearComments(target) {
     const cleared = new Set((target ? getCommentsForTarget(target) : getComments()).map((comment) => comment.id));
     publish(getComments().filter((comment) => !cleared.has(comment.id)));
 }
-/** Arms only the exact notes successfully copied or accepted by an agent. */
+/** Marks only exact id+note matches, so an edited note is not marked handed off. */
 export function markCommentsHandedOff(sent) {
     publish(getComments().map((item) => sent.some((candidate) => candidate.id === item.id && candidate.note === item.note)
         ? { ...item, handedOff: true } : item));

package/dist/inspector/comments/verification.d.ts

@@ -1,5 +1,11 @@
+import { isCanvasProjectionRevisionCurrent, projectDraftToDocument } from "../canvas/projection.js";
+/** Controller transport used while reconciling notes; tests replace the renderer round-trip. */
+export interface CommentProjectionTransport {
+    readonly projectDraftToDocument: typeof projectDraftToDocument;
+    readonly isCanvasProjectionRevisionCurrent: typeof isCanvasProjectionRevisionCurrent;
+}
 export declare function isReadingCommentSource(doc: Document): boolean;
 /** Serializes clean reads and restores the latest previews even if the read fails. */
-export declare function readCommentSource<T>(doc: Document, read: () => T): Promise<T | null>;
+export declare function readCommentSource<T>(doc: Document, read: () => T, transport?: CommentProjectionTransport): Promise<T | null>;
 /** Changed, uniquely located elements resolve after handoff; missing and ambiguous targets remain. */
-export declare function reconcileComments(doc: Document): Promise<void>;
+export declare function reconcileComments(doc: Document, transport?: CommentProjectionTransport): Promise<number>;

package/dist/inspector/comments/verification.js

@@ -1,25 +1,29 @@
-import { getDraftChanges } from "../changes/draftChanges.js";
+import { getDraftChanges } from "../drafts/store.js";
 import { documentTarget, targetKey } from "../drafts/model.js";
 import { isCanvasProjectionRevisionCurrent, projectDraftToDocument } from "../canvas/projection.js";
 import { commentFingerprint, commentViewport, resolveCommentElement } from "./element.js";
 import { commentRoute, getCommentClearRevision, getComments, removeComment } from "./store.js";
 const documentReads = new WeakMap();
 const readingDocuments = new WeakSet();
+const controllerTransport = {
+    projectDraftToDocument,
+    isCanvasProjectionRevisionCurrent,
+};
 export function isReadingCommentSource(doc) { return readingDocuments.has(doc); }
 /** Serializes clean reads and restores the latest previews even if the read fails. */
-export function readCommentSource(doc, read) {
+export function readCommentSource(doc, read, transport = controllerTransport) {
     const previous = documentReads.get(doc) ?? Promise.resolve();
     const operation = previous.catch(() => undefined).then(async () => {
         readingDocuments.add(doc);
         try {
-            const revision = await projectDraftToDocument(doc, { changes: [], structuralChanges: [] });
-            if (revision === null || !isCanvasProjectionRevisionCurrent(doc, revision))
+            const revision = await transport.projectDraftToDocument(doc, { changes: [], structuralChanges: [] });
+            if (revision === null || !transport.isCanvasProjectionRevisionCurrent(doc, revision))
                 return null;
             return read();
         }
         finally {
             try {
-                await projectDraftToDocument(doc, getDraftChanges(targetKey(documentTarget(doc.location.href))));
+                await transport.projectDraftToDocument(doc, getDraftChanges(targetKey(documentTarget(doc.location.href))));
                 // Deliver projection mutation records before accepting another source signal.
                 await new Promise((resolve) => setTimeout(resolve, 0));
             }
@@ -32,21 +36,25 @@ export function readCommentSource(doc, read) {
     return operation;
 }
 /** Changed, uniquely located elements resolve after handoff; missing and ambiguous targets remain. */
-export async function reconcileComments(doc) {
+export async function reconcileComments(doc, transport = controllerTransport) {
     const revision = getCommentClearRevision();
     const sent = getComments().filter((item) => item.handedOff && item.route === commentRoute(doc));
     if (sent.length === 0)
-        return;
+        return 0;
     const resolved = await readCommentSource(doc, () => sent.filter((item) => {
         if (item.viewport !== commentViewport(doc))
             return false;
         const element = resolveCommentElement(doc, item.target);
         return element !== null && commentFingerprint(element) !== item.baseline;
-    }));
+    }), transport);
     if (revision !== getCommentClearRevision())
-        return;
+        return 0;
+    let removed = 0;
     for (const item of resolved ?? []) {
-        if (getComments().some((current) => current.id === item.id && current.note === item.note && current.handedOff))
-            removeComment(item.id);
+        if (!getComments().some((current) => current.id === item.id && current.note === item.note && current.handedOff))
+            continue;
+        removeComment(item.id);
+        removed += 1;
     }
+    return removed;
 }

package/dist/inspector/componentSemantics/ComponentPropsSection.d.ts

@@ -1,5 +1,13 @@
 import type { ReactElement } from "react";
 import type { SelectedElement } from "../selection/selectionStore.js";
+import { useChanges } from "../drafts/store.js";
+import type { ComponentPropContract, EditableComponentTarget } from "./types.js";
+export interface ComponentPropsView {
+    target: EditableComponentTarget;
+    visibleProps: ComponentPropContract[];
+    changes: ReturnType<typeof useChanges>;
+}
+export declare function useComponentProps(selected: SelectedElement | null): ComponentPropsView | null;
 export declare function ComponentPropsSection({ selected }: {
     selected: SelectedElement;
 }): ReactElement | null;