nudge-ui 0.2.5 → 0.2.6

package/dist/inspector/changes/managedStyleProjection.js

@@ -60,22 +60,16 @@ export function buildManagedStyleRules(changes) {
             });
         }
     }
-    // Source-site rules remain the default; exact rendered-instance rules are
-    // emitted afterwards so their additional marker specificity wins.
+    // Source-site rules are the default; rendered-instance rules come last so their extra marker specificity wins.
     return [...sourceRules.values(), ...instanceRules.values()];
 }
 export function verifyManagedStyleProjection(change, selectedElement, ownerDocument = document) {
-    // Deferred verification must use the selection that existed when the
-    // projection was committed. Reading the live selection here can make a
-    // host-document change verify against a later canvas selection (or vice
-    // versa) and manufacture a conflict for the wrong document.
+    // Deferred verification must use the selection from commit time; the live selection can belong to the wrong document and manufacture a conflict.
     const selected = selectedElement === undefined
         ? getSelectedElement()?.domElement ?? null
         : selectedElement;
     const requestedValue = requestedStyleValue(change);
-    // A Canvas-only selection belongs to an iframe. The controller stylesheet
-    // cannot verify it synchronously; leave its result unknown until the frame
-    // has received the canonical projection rather than claiming it is stale.
+    // A Canvas-only iframe selection cannot be verified synchronously; leave the result unknown rather than claiming it is stale.
     if (selected && selected.ownerDocument !== ownerDocument) {
         return null;
     }
@@ -87,11 +81,7 @@ export function verifyManagedStyleProjection(change, selectedElement, ownerDocum
     catch {
         targets = [];
     }
-    // Probe targets lazily in DOM order and stop at the first conflicting
-    // preview: the reported result is exactly "first conflict ?? first target",
-    // so probing the remaining instances cannot change the outcome. A
-    // source-site selector matched by many rendered instances (one callsite,
-    // hundreds of nodes) otherwise pays a probe + important-rule scan per match.
+    // Early exit is safe: the result is "first conflict ?? first target", so later probes cannot change it.
     let firstApplied = null;
     let previewResult = null;
     for (const target of targets) {

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

@@ -1,10 +1,5 @@
 import type { TokenEntry } from "../../css/model/index.js";
 import { type ChangeRecord } from "./types.js";
-/**
- * The CSS value a token swap writes into the managed stylesheet and the
- * prompt must describe: an adapter-provided literal when present, otherwise a
- * var() reference on the authored cssName (falling back to the entry name).
- */
 export declare function tokenReference(token: TokenEntry): string;
 export declare function changeKey(change: ChangeRecord): string;
 export declare function mergeChange(current: ChangeRecord[], incoming: ChangeRecord): ChangeRecord[];

package/dist/inspector/changes/model.js

@@ -1,9 +1,4 @@
 import { isComponentChange, isElementChange, isTextContentChange, isTokenChange, } from "./types.js";
-/**
- * The CSS value a token swap writes into the managed stylesheet and the
- * prompt must describe: an adapter-provided literal when present, otherwise a
- * var() reference on the authored cssName (falling back to the entry name).
- */
 export function tokenReference(token) {
     return token.cssValue ?? `var(${token.cssName ?? token.name})`;
 }
@@ -27,9 +22,7 @@ export function changeKey(change) {
         ].join("\u0000");
     }
     if (isTextContentChange(change)) {
-        // The marker id is document-local projection identity. `beforeText` is
-        // part of the durable evidence: two outputs at one source site may have
-        // different initial copy and must remain distinct canonical intents.
+        // Two outputs at one source site may have different initial copy, so beforeText keeps them distinct.
         return [
             "text-content",
             change.target.sourceSite.cid,

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

@@ -14,26 +14,16 @@ export interface PreviewDiagnostic extends PreviewAttempt {
     readonly changeKey: string;
     readonly result: PreviewResult;
 }
-/** Returns the stable host-document identity for this inspector lifetime. */
 export declare function getHostPreviewDocument(): PreviewDocument;
-/** Starts or replaces the live session for one logical document. */
 export declare function startPreviewDocumentSession(document: PreviewDocument): void;
-/** Invalidates a live document session and rejects all of its late results. */
+/** Late results from an invalidated session are rejected. */
 export declare function invalidatePreviewDocumentSession(logicalDocument: string, sessionId?: string): void;
-/** Opens a verification attempt for the currently active document session. */
 export declare function beginPreviewAttempt(document: PreviewDocument, revision?: number): PreviewAttempt | null;
-/** Publishes only a result from the active revision, session, and attempt. */
 export declare function publishPreviewDiagnostic(attempt: PreviewAttempt, changeKey: string, result: PreviewResult): boolean;
-/** Removes diagnostics for the supplied canonical keys across live documents. */
 export declare function clearPreviewDiagnostics(changeKeys?: Iterable<string>): void;
-/** Notifies consumers when verification state changes without a result. */
 export declare function notifyPreviewDiagnostics(): void;
 export declare function getPreviewDiagnostic(changeKey: string, logicalDocument?: string, draftId?: string): PreviewDiagnostic | undefined;
-/**
- * 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 declare function getAnyPreviewDiagnostic(changeKey: string): PreviewDiagnostic | undefined;
 export declare function subscribePreviewDiagnostics(listener: () => void): () => void;
 export declare function getPreviewDiagnosticRevision(): number;

package/dist/inspector/changes/previewDiagnostics.js

@@ -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,12 +1,8 @@
 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 element has no authored source location.
-     * 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;
@@ -16,11 +12,10 @@ export interface RuntimeElementEvidence {
     domPath?: string | null;
     elementId?: string | null;
 }
-/** Bounded authored facts for one annotated element. */
 export interface SourceElementEvidence {
     tagName: string;
     props: string | null;
-    /** Rendered identification details; omitted by older saved changes. */
+    /** Omitted by older saved changes. */
     text?: string | null;
     ariaLabel?: string | null;
     domPath?: string | null;
@@ -35,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;
@@ -48,12 +42,11 @@ 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;
-    /** Matching rendered items when captured; presentation only, absent in older edits. */
+    /** Presentation only; absent from older edits. */
     sourceInstanceCount?: number;
     /** Durable, controller-owned target for one rendered output. */
     instanceOverride?: RenderedInstanceOverride;

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

@@ -15,6 +15,8 @@ import { commentRoute, getCommentClearRevision, isCommentToolActive, removeComme
 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;
 }
@@ -149,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) {
@@ -173,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)

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

@@ -94,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

@@ -5,21 +5,25 @@ import { commentFingerprint, commentViewport, resolveCommentElement } from "./el
 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;