nudge-ui 0.2.4 → 0.2.6

package/dist/inspector/agent/httpTransport.d.ts

@@ -1,18 +1,10 @@
 import { type AgentBridgeTransport, type AgentBridgeEndpointConfig, type AgentDiscoveryRequest, type AgentEventHandlers, type AgentEventSubscription, type AgentEventsRequest, type AgentPairRequest, type AgentPromptDispatch, type AgentDisconnectRequest, type AgentCanvasAcknowledgementRequest, type AgentSessionRequest, type AgentStatusSnapshot, type PairingResponse, type PromptDispatchResponse } from "./protocol.js";
-/** Returns whether the dev host supplied a trusted project bridge endpoint. */
 export declare function shouldAutoConnectAgentBridge(): boolean;
 export declare class AgentBridgeHttpError extends Error {
     readonly status: number;
     readonly code?: string;
     constructor(status: number, message: string, code?: string);
 }
-/**
- * HTTP/SSE browser adapter for the companion's canonical endpoints.
- *
- * The adapter is inert when no endpoint is configured. A host can publish an
- * endpoint with `window.__NUDGE_UI_AGENT_BRIDGE__` or the meta tag named
- * `nudge-ui-agent-bridge`; tests can inject a transport directly instead.
- */
 export declare class HttpAgentBridgeTransport implements AgentBridgeTransport {
     private readonly config;
     constructor(config?: AgentBridgeEndpointConfig);

package/dist/inspector/agent/httpTransport.js

@@ -1,4 +1,4 @@
-import { AGENT_PROTOCOL_VERSION, defaultBridgePort, isAgentPromptRequest, isAgentActivity, } from "./protocol.js";
+import { AGENT_PROTOCOL_VERSION, BRIDGE_ENDPOINTS, decodeAgentStatusSnapshot, decodeBridgeEvent, decodePairingResponse, decodePromptDispatchResponse, } from "./protocol.js";
 import { getActiveCanvasDocument } from "../canvas/activeCanvasDocument.js";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -27,8 +27,7 @@ function configuredEndpointInDocument(doc) {
     const target = doc.defaultView;
     if (!target)
         return undefined;
-    const globalConfig = endpointValue(target.__NUDGE_UI_AGENT_BRIDGE__)
-        ?? endpointValue(target.__NUDGE_UI_AGENT__);
+    const globalConfig = endpointValue(target.__NUDGE_UI_AGENT_BRIDGE__);
     if (globalConfig)
         return globalConfig;
     const meta = doc.querySelector('meta[name="nudge-ui-agent-bridge"]');
@@ -44,7 +43,6 @@ function configuredEndpoint() {
     const previewDocument = getActiveCanvasDocument();
     return previewDocument ? configuredEndpointInDocument(previewDocument) : undefined;
 }
-/** Returns whether the dev host supplied a trusted project bridge endpoint. */
 export function shouldAutoConnectAgentBridge() {
     return configuredEndpoint()?.autoConnect === true;
 }
@@ -65,8 +63,7 @@ function safeUrl(value, origin) {
         const url = new URL(value, origin);
         if (url.protocol !== "http:" && url.protocol !== "https:")
             return null;
-        // A same-origin reverse proxy is valid; a separately hosted bridge must
-        // remain loopback-only to match ADR-0013.
+        // A separately hosted bridge must remain loopback-only; a same-origin reverse proxy is valid.
         if (url.origin !== origin && !isLoopback(url.hostname))
             return null;
         return url;
@@ -75,12 +72,12 @@ function safeUrl(value, origin) {
         return null;
     }
 }
-function endpointUrl(config, projectId, key, fallbackPath, origin) {
+/** Null when the host published no endpoint; the browser never guesses a bridge port. */
+function endpointUrl(config, key, fallbackPath, origin) {
     const explicit = config[key];
     if (explicit && key !== "baseUrl")
         return safeUrl(explicit, origin);
-    const baseValue = config.baseUrl ?? `http://127.0.0.1:${defaultBridgePort(projectId)}`;
-    const base = safeUrl(baseValue, origin);
+    const base = config.baseUrl ? safeUrl(config.baseUrl, origin) : null;
     if (!base)
         return null;
     base.pathname = `${base.pathname.replace(/\/$/, "")}${fallbackPath}`;
@@ -108,122 +105,23 @@ export class AgentBridgeHttpError extends Error {
     }
 }
 async function readJson(response) {
-    let payload;
-    try {
-        payload = await response.json();
-    }
-    catch {
-        payload = {};
-    }
+    const body = await response.json().catch(() => null);
+    const payload = isRecord(body) ? body : {};
     if (!response.ok) {
-        const error = isRecord(payload) && isRecord(payload.error) ? payload.error : payload;
+        const error = isRecord(payload.error) ? payload.error : payload;
         const message = isRecord(error) ? stringValue(error.message) : undefined;
         const code = isRecord(error) ? stringValue(error.code) : undefined;
         throw new AgentBridgeHttpError(response.status, message ?? `Agent bridge request failed (${response.status}).`, code);
     }
-    return isRecord(payload) ? payload : {};
-}
-function statusPayload(value) {
-    if (!isRecord(value))
-        return null;
-    const status = isRecord(value.status) ? value.status : value;
-    if (typeof status.projectId !== "string"
-        || (status.connection !== "offline"
-            && status.connection !== "listening"
-            && status.connection !== "paired"
-            && status.connection !== "working")
-        || typeof status.listenerActive !== "boolean"
-        || typeof status.paired !== "boolean")
-        return null;
-    if (status.protocolVersion !== undefined && status.protocolVersion !== AGENT_PROTOCOL_VERSION)
-        return null;
-    const rawRequest = status.request;
-    let request = null;
-    if (rawRequest !== null && rawRequest !== undefined) {
-        if (!isRecord(rawRequest)
-            || (rawRequest.status !== "working"
-                && rawRequest.status !== "completed"
-                && rawRequest.status !== "failed"
-                && rawRequest.status !== "interrupted"))
-            return null;
-        const requestCandidate = {
-            requestId: rawRequest.requestId,
-            projectId: rawRequest.projectId,
-            prompt: rawRequest.prompt,
-            ...(typeof rawRequest.changeRevision === "number" ? { changeRevision: rawRequest.changeRevision } : {}),
-            ...(rawRequest.clientDispatchId === undefined ? {} : { clientDispatchId: rawRequest.clientDispatchId }),
-            ...(rawRequest.sketches === undefined ? {} : { sketches: rawRequest.sketches }),
-        };
-        if (!isAgentPromptRequest(requestCandidate))
-            return null;
-        request = {
-            ...requestCandidate,
-            status: rawRequest.status,
-            ...(typeof rawRequest.summary === "string" ? { summary: rawRequest.summary } : {}),
-            ...(typeof rawRequest.error === "string" ? { error: rawRequest.error } : {}),
-        };
-    }
-    return {
-        protocolVersion: AGENT_PROTOCOL_VERSION,
-        projectId: status.projectId,
-        connection: status.connection,
-        listenerActive: status.listenerActive,
-        ...(typeof status.agentClientName === "string" ? { agentClientName: status.agentClientName.slice(0, 120) } : {}),
-        paired: status.paired,
-        request,
-    };
+    return payload;
 }
-function eventPayload(value) {
-    if (!isRecord(value))
-        return null;
-    const envelope = value;
-    const event = isRecord(envelope.event) ? envelope.event : value;
-    const type = stringValue(event.type);
-    if (type === "status") {
-        const status = statusPayload(event.status);
-        return status ? { type: "status", status } : null;
-    }
-    if (type === "connected") {
-        const status = statusPayload(event.status);
-        return status ? { type: "connected", status } : null;
-    }
-    if (type === "disconnected") {
-        return { type: "disconnected", ...(stringValue(event.reason) ? { reason: stringValue(event.reason) } : {}) };
-    }
-    if (type === "activity" && isAgentActivity(event.activity))
-        return { type: "activity", activity: event.activity };
-    if (type === "canvas-command" && isRecord(event.command)) {
-        // The Canvas controller owns command validation. Preserve the shared
-        // shape here so the parent stage can consume this event without a second
-        // protocol vocabulary.
-        return { type: "canvas-command", command: event.command };
-    }
-    return null;
-}
-function eventData(event) {
-    if (typeof event.data !== "string")
-        return event.data;
-    try {
-        return JSON.parse(event.data);
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * HTTP/SSE browser adapter for the companion's canonical endpoints.
- *
- * The adapter is inert when no endpoint is configured. A host can publish an
- * endpoint with `window.__NUDGE_UI_AGENT_BRIDGE__` or the meta tag named
- * `nudge-ui-agent-bridge`; tests can inject a transport directly instead.
- */
 export class HttpAgentBridgeTransport {
     config;
     constructor(config = configuredEndpoint() ?? {}) {
         this.config = config;
     }
     async discover(request, signal) {
-        const url = endpointUrl(this.config, request.projectId, "healthUrl", "/health", pageOrigin());
+        const url = endpointUrl(this.config, "healthUrl", BRIDGE_ENDPOINTS.health, pageOrigin());
         if (!url || typeof fetch !== "function")
             return null;
         const response = await fetch(withQuery(url, {
@@ -238,10 +136,10 @@ export class HttpAgentBridgeTransport {
             || payload.projectId !== request.projectId
             || (payload.origin !== undefined && payload.origin !== null && payload.origin !== request.origin))
             return null;
-        return statusPayload(payload.status);
+        return decodeAgentStatusSnapshot(payload.status);
     }
     async pair(request, signal) {
-        const url = endpointUrl(this.config, request.projectId, "pairUrl", "/pair", pageOrigin());
+        const url = endpointUrl(this.config, "pairUrl", BRIDGE_ENDPOINTS.pair, pageOrigin());
         if (!url || typeof fetch !== "function")
             throw new Error("Agent bridge is unavailable.");
         const response = await fetch(url, {
@@ -250,26 +148,13 @@ export class HttpAgentBridgeTransport {
             body: JSON.stringify(request),
             signal,
         });
-        const payload = await readJson(response);
-        if (payload.protocolVersion !== AGENT_PROTOCOL_VERSION
-            || payload.projectId !== request.projectId
-            || payload.origin !== request.origin
-            || typeof payload.sessionToken !== "string") {
+        const pairing = decodePairingResponse(await readJson(response), request);
+        if (!pairing)
             throw new Error("Agent bridge returned an invalid pairing response.");
-        }
-        const status = statusPayload(payload.status);
-        if (!status)
-            throw new Error("Agent bridge returned an invalid status.");
-        return {
-            protocolVersion: AGENT_PROTOCOL_VERSION,
-            projectId: request.projectId,
-            origin: request.origin,
-            sessionToken: payload.sessionToken,
-            status,
-        };
+        return pairing;
     }
     async takeOver(request, signal) {
-        const url = endpointUrl(this.config, request.projectId, "takeoverUrl", "/takeover", pageOrigin());
+        const url = endpointUrl(this.config, "takeoverUrl", BRIDGE_ENDPOINTS.takeover, pageOrigin());
         if (!url || typeof fetch !== "function")
             throw new Error("Agent bridge is unavailable.");
         const response = await fetch(url, {
@@ -278,42 +163,26 @@ export class HttpAgentBridgeTransport {
             body: JSON.stringify(request),
             signal,
         });
-        const payload = await readJson(response);
-        if (payload.protocolVersion !== AGENT_PROTOCOL_VERSION
-            || payload.projectId !== request.projectId
-            || payload.origin !== request.origin
-            || typeof payload.sessionToken !== "string") {
+        const pairing = decodePairingResponse(await readJson(response), request);
+        if (!pairing)
             throw new Error("Agent bridge returned an invalid takeover response.");
-        }
-        const status = statusPayload(payload.status);
-        if (!status)
-            throw new Error("Agent bridge returned an invalid status.");
-        return {
-            protocolVersion: AGENT_PROTOCOL_VERSION,
-            projectId: request.projectId,
-            origin: request.origin,
-            sessionToken: payload.sessionToken,
-            status,
-        };
+        return pairing;
     }
     async restore(request, signal) {
-        const url = endpointUrl(this.config, request.projectId, "statusUrl", "/status", pageOrigin());
+        const url = endpointUrl(this.config, "statusUrl", BRIDGE_ENDPOINTS.status, pageOrigin());
         if (!url || typeof fetch !== "function")
             return null;
         const response = await fetch(withQuery(url, {
             projectId: request.projectId,
             sessionToken: request.sessionToken,
         }), { method: "GET", headers: headers(), signal });
-        const payload = await readJson(response);
-        if (payload.protocolVersion !== AGENT_PROTOCOL_VERSION || payload.projectId !== request.projectId)
-            return null;
-        const status = statusPayload(payload);
-        if (!status || !status.paired)
+        const status = decodeAgentStatusSnapshot(await readJson(response));
+        if (!status || status.projectId !== request.projectId || !status.paired)
             return null;
         return status;
     }
     openEvents(request, handlers) {
-        const url = endpointUrl(this.config, request.projectId, "eventsUrl", "/events", pageOrigin());
+        const url = endpointUrl(this.config, "eventsUrl", BRIDGE_ENDPOINTS.events, pageOrigin());
         if (!url || typeof EventSource !== "function") {
             queueMicrotask(() => handlers.onDisconnect("Agent event transport is unavailable."));
             return { close: () => undefined };
@@ -325,10 +194,19 @@ export class HttpAgentBridgeTransport {
         const source = new EventSource(eventUrl.href);
         let closed = false;
         const handleMessage = (event) => {
-            const value = eventData(event);
-            if (isRecord(value) && "event" in value && (value.protocolVersion !== AGENT_PROTOCOL_VERSION || value.projectId !== request.projectId || value.sessionToken !== request.sessionToken))
+            let envelope;
+            try {
+                envelope = JSON.parse(event.data);
+            }
+            catch {
                 return;
-            const parsed = eventPayload(value);
+            }
+            if (!isRecord(envelope)
+                || envelope.protocolVersion !== AGENT_PROTOCOL_VERSION
+                || envelope.projectId !== request.projectId
+                || envelope.sessionToken !== request.sessionToken)
+                return;
+            const parsed = decodeBridgeEvent(envelope.event);
             if (parsed)
                 handlers.onEvent(parsed);
         };
@@ -355,7 +233,7 @@ export class HttpAgentBridgeTransport {
         };
     }
     async dispatch(request, signal) {
-        const url = endpointUrl(this.config, request.projectId, "promptUrl", "/prompt", pageOrigin());
+        const url = endpointUrl(this.config, "promptUrl", BRIDGE_ENDPOINTS.prompt, pageOrigin());
         if (!url || typeof fetch !== "function")
             throw new Error("Agent bridge is unavailable.");
         const response = await fetch(url, {
@@ -364,25 +242,13 @@ export class HttpAgentBridgeTransport {
             body: JSON.stringify(request),
             signal,
         });
-        const payload = await readJson(response);
-        if (!isRecord(payload.request) || payload.status !== "working") {
-            throw new Error("Agent bridge returned an invalid prompt response.");
-        }
-        const requestCandidate = {
-            requestId: payload.request.requestId,
-            projectId: payload.request.projectId,
-            prompt: payload.request.prompt,
-            ...(typeof payload.request.changeRevision === "number" ? { changeRevision: payload.request.changeRevision } : {}),
-            ...(payload.request.clientDispatchId === undefined ? {} : { clientDispatchId: payload.request.clientDispatchId }),
-            ...(payload.request.sketches === undefined ? {} : { sketches: payload.request.sketches }),
-        };
-        if (!isAgentPromptRequest(requestCandidate) || requestCandidate.projectId !== request.projectId) {
+        const dispatched = decodePromptDispatchResponse(await readJson(response), request.projectId);
+        if (!dispatched)
             throw new Error("Agent bridge returned an invalid prompt response.");
-        }
-        return { request: requestCandidate, status: "working" };
+        return dispatched;
     }
     async disconnect(request, signal) {
-        const url = endpointUrl(this.config, request.projectId, "disconnectUrl", "/disconnect", pageOrigin());
+        const url = endpointUrl(this.config, "disconnectUrl", BRIDGE_ENDPOINTS.disconnect, pageOrigin());
         if (!url || typeof fetch !== "function")
             return;
         await fetch(url, {
@@ -393,7 +259,7 @@ export class HttpAgentBridgeTransport {
         });
     }
     async acknowledgeCanvasCommand(request, signal) {
-        const url = endpointUrl(this.config, request.projectId, "canvasAckUrl", "/canvas/ack", pageOrigin());
+        const url = endpointUrl(this.config, "canvasAckUrl", BRIDGE_ENDPOINTS.canvasAcknowledgement, pageOrigin());
         if (!url || typeof fetch !== "function")
             return;
         await fetch(url, {

package/dist/inspector/agent/protocol.d.ts

@@ -1,13 +1,5 @@
 import type { AgentActivity, AgentStatusSnapshot, CanvasCommand, CanvasCommandAcknowledgement, CanvasCommandResult, AgentSketchAttachment, PairingResponse, PromptDispatchResponse } from "../../internal/agent-protocol.js";
-/**
- * Browser transport port for the shared Nudge agent protocol.
- *
- * Domain messages come from the private shared protocol module; this file only
- * adds the browser's injectable HTTP/SSE transport boundary. Keeping that
- * boundary local lets inspector tests use a deterministic fake while the
- * companion remains the owner of MCP and Node-specific code.
- */
-export { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, defaultBridgePort, CANVAS_COMMAND_TYPES, canonicalOrigin, isAgentPromptRequest, isAgentSketchAttachment, isAgentSketchAnnotation, isAgentSketchCaptureMetadata, isAgentSketchMetadata, isAgentStatusUpdate, isAgentActivity, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isCanonicalOrigin, isProjectIdentity, isSameOriginRoute, protocolError, validateSketchAttachments, validateRoutes, } from "../../internal/agent-protocol.js";
+export { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, BRIDGE_ENDPOINTS, CANVAS_COMMAND_TYPES, canonicalOrigin, decodeAgentStatusSnapshot, decodeBridgeEvent, decodePairingResponse, decodePromptDispatchResponse, deriveConnectionState, isAgentPromptRequest, isAgentSketchAttachment, isAgentSketchAnnotation, isAgentSketchCaptureMetadata, isAgentSketchMetadata, isAgentStatusUpdate, isAgentActivity, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isCanonicalOrigin, isProjectIdentity, isSameOriginRoute, protocolError, validateSketchAttachments, validateRoutes, } from "../../internal/agent-protocol.js";
 export type { AgentActivity, BridgeActivityEvent, AgentConnectionState, AgentProjectIdentity, AgentPromptRequest, AgentDeliveredPrompt, AgentSketchAttachment, AgentSketchAnnotation, AgentSketchCaptureMetadata, AgentSketchMetadata, AgentRequestOutcome, AgentRequestStatus, AgentRoute, AgentStatusSnapshot, AgentStatusUpdate, BridgeCanvasCommandEvent, BridgeConnectedEvent, BridgeDisconnectedEvent, BridgeEnvelope, BridgeEvent, BridgeEventType, BridgeStatusEvent, CanvasCommand, CanvasCommandAcknowledgement, CanvasCommandError, CanvasCommandResult, CanvasGroup, CanvasGroupOwner, CanvasState, FitCanvasCommand, FocusCanvasGroupCommand, PairingRequest, PairingResponse, PresentRoutesCommand, PromptDispatchRequest, PromptDispatchResponse, ReadCanvasStateCommand, RemoveCanvasGroupCommand, StatusEventRequest, AgentProtocolVersion, } from "../../internal/agent-protocol.js";
 export interface AgentBridgeEndpointConfig {
     readonly baseUrl?: string;
@@ -67,7 +59,6 @@ export interface AgentEventHandlers {
 export interface AgentEventSubscription {
     readonly close: () => void;
 }
-/** Events delivered by the companion's SSE stream. */
 export type AgentBridgeEvent = {
     readonly type: "activity";
     readonly activity: AgentActivity;

package/dist/inspector/agent/protocol.js

@@ -1,9 +1 @@
-/**
- * Browser transport port for the shared Nudge agent protocol.
- *
- * Domain messages come from the private shared protocol module; this file only
- * adds the browser's injectable HTTP/SSE transport boundary. Keeping that
- * boundary local lets inspector tests use a deterministic fake while the
- * companion remains the owner of MCP and Node-specific code.
- */
-export { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, defaultBridgePort, CANVAS_COMMAND_TYPES, canonicalOrigin, isAgentPromptRequest, isAgentSketchAttachment, isAgentSketchAnnotation, isAgentSketchCaptureMetadata, isAgentSketchMetadata, isAgentStatusUpdate, isAgentActivity, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isCanonicalOrigin, isProjectIdentity, isSameOriginRoute, protocolError, validateSketchAttachments, validateRoutes, } from "../../internal/agent-protocol.js";
+export { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, BRIDGE_ENDPOINTS, CANVAS_COMMAND_TYPES, canonicalOrigin, decodeAgentStatusSnapshot, decodeBridgeEvent, decodePairingResponse, decodePromptDispatchResponse, deriveConnectionState, isAgentPromptRequest, isAgentSketchAttachment, isAgentSketchAnnotation, isAgentSketchCaptureMetadata, isAgentSketchMetadata, isAgentStatusUpdate, isAgentActivity, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isCanonicalOrigin, isProjectIdentity, isSameOriginRoute, protocolError, validateSketchAttachments, validateRoutes, } from "../../internal/agent-protocol.js";

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

@@ -1,5 +1,5 @@
 import { type DraftTarget } from "../drafts/model.js";
-import { type ChangeRecord } from "../changes/changesLog.js";
+import { type ChangeRecord } from "../changes/types.js";
 import { type StructuralChange } from "../projection/structuralProjection.js";
 export interface HandoffOwner {
     readonly draftId: string;
@@ -13,35 +13,18 @@ export interface HandoffSnapshot {
     readonly changes: readonly ChangeRecord[];
     readonly structuralChanges: readonly StructuralChange[];
 }
-/** Stable, preview-metadata-free identity for one prompt handoff record. */
 export declare function handoffChangeFingerprint(change: ChangeRecord): string;
-/** Stable identity for one structural record included in a prompt handoff. */
 export declare function handoffStructuralFingerprint(change: StructuralChange): string;
-/**
- * Positively verifies browser-observable source results after the inspector's
- * own projections have been removed. Component props and interaction states
- * intentionally remain unresolved because rendered output alone cannot prove
- * that their source was updated.
- */
+/** Component props and interaction states stay unresolved: rendered output alone cannot prove their source changed. */
 export declare function verifiedChangeKeys(sentChanges: readonly ChangeRecord[], doc?: Document): Set<string>;
-/** Captures the exact canonical edits associated with one dispatched prompt. */
 export declare function recordAgentDispatch(revision: number, changes: readonly ChangeRecord[], structuralChanges?: readonly StructuralChange[], owner?: HandoffOwner): void;
-/** Drops a captured revision when the bridge rejects its dispatch. */
 export declare function discardAgentDispatch(revision: number): void;
-/** Returns how many canonical edits were in flight for one dispatch. */
 export declare function getAgentDispatchSize(revision: number): number;
-/**
- * Reconciles only records that still equal the sent snapshot and that remain
- * observable after removing Nudge's own preview. Newer edits and ambiguous
- * records are preserved.
- */
+/** Newer edits and ambiguous records are preserved. */
 export declare function verifyAndReconcileHandoff(snapshot: HandoffSnapshot, doc?: Document | null): Promise<number>;
 export declare function documentBelongsToHandoff(doc: Document, owner: HandoffOwner): boolean;
-/** Returns the records captured for one dispatch until it is reconciled. */
 export declare function getAgentDispatch(revision: number): HandoffSnapshot | null;
-/** Records in the owner draft that still equal what a handoff sent. */
 export declare function unchangedHandoffRecords(snapshot: HandoffSnapshot): Pick<HandoffSnapshot, "changes" | "structuralChanges">;
-/** Reconciles the captured records for one completed connected-agent request. */
 export declare function verifyAndReconcileAgentDispatch(revision: number): Promise<number>;
 /** Test/session reset for in-memory dispatch snapshots. */
 export declare function resetAgentVerification(): void;

package/dist/inspector/agent/verification.js

@@ -1,11 +1,10 @@
-import { draftIdForCard } from "../drafts/store.js";
+import { draftIdForCard, getActiveDraftChanges, getDraftChanges, reconcileDraftChanges } from "../drafts/store.js";
 import { getCanvasCards } from "../canvas/canvasStore.js";
 import { getRegisteredFrames, getCanvasCardIdForDocument } from "../canvas/projection.js";
 import { applicationTarget, targetFromKey, targetKey } from "../drafts/model.js";
 import { changeKey, tokenReference } from "../changes/model.js";
 import { selectorForManagedChange } from "../changes/managedStyleProjection.js";
-import { getActiveDraftChanges, getDraftChanges, reconcileDraftChanges } from "../changes/draftChanges.js";
-import { isComponentChange, isTextContentChange, isTokenChange, } from "../changes/changesLog.js";
+import { isComponentChange, isTextContentChange, isTokenChange, } from "../changes/types.js";
 import { verifyPreview } from "../projection/managedStylesheet.js";
 import { resolveMovedRenderedInstance } from "../projection/renderedInstance.js";
 import { relocateSourceSite, sourceSiteSelector } from "../selection/sourceSite.js";
@@ -35,11 +34,9 @@ function stableJsonValue(value) {
 function stableSerialized(value) {
     return JSON.stringify(stableJsonValue(value));
 }
-/** Stable, preview-metadata-free identity for one prompt handoff record. */
 export function handoffChangeFingerprint(change) {
     return stableSerialized(change);
 }
-/** Stable identity for one structural record included in a prompt handoff. */
 export function handoffStructuralFingerprint(change) {
     return stableSerialized(change);
 }
@@ -60,7 +57,7 @@ function queryTargets(doc, selector) {
         return [];
     }
 }
-/** Resolves current style targets, following a source site whose position shifted. */
+/** Falls back to relocating a shifted source site. */
 function styleTargets(change, doc) {
     if (isTokenChange(change))
         return queryTargets(doc, change.selector);
@@ -107,12 +104,7 @@ function verifyText(change, doc) {
         && change.after.length === 0
         && (resolved.element.textContent ?? "") === "";
 }
-/**
- * A delete verifies when its target no longer resolves in the document once
- * the preview is lifted: the source really removed it. Ambiguous evidence
- * still means identical elements are present, so only a definitive miss
- * verifies.
- */
+/** Only a definitive miss verifies; ambiguous evidence still means identical elements are present. */
 function verifyStructuralDelete(change, doc) {
     if (!change.route || !change.state || !doc.location)
         return false;
@@ -129,12 +121,7 @@ function verifyStructuralDelete(change, doc) {
         && documentStateKey(doc) === change.state
         && resolveMovedRenderedInstance(doc, change.target).status === "missing";
 }
-/**
- * A move verifies when the element sits at its recorded destination without
- * the preview holding it there. The projection rebuild returns a cleanly
- * applied move preview to its captured origin, so such records conservatively
- * stay unverified instead of trusting rendered placement alone.
- */
+/** A cleanly applied preview returns to its captured origin, so only a move that stays at its recorded destination verifies. */
 function verifyStructuralMove(change, doc) {
     const target = resolveMovedRenderedInstance(doc, change.target);
     if (target.status !== "resolved")
@@ -160,12 +147,7 @@ function verifiedStructuralChangeIds(eligible, doc) {
     }
     return verified;
 }
-/**
- * Positively verifies browser-observable source results after the inspector's
- * own projections have been removed. Component props and interaction states
- * intentionally remain unresolved because rendered output alone cannot prove
- * that their source was updated.
- */
+/** Component props and interaction states stay unresolved: rendered output alone cannot prove their source changed. */
 export function verifiedChangeKeys(sentChanges, doc = document) {
     const verified = new Set();
     for (const change of sentChanges) {
@@ -179,7 +161,6 @@ export function verifiedChangeKeys(sentChanges, doc = document) {
     }
     return verified;
 }
-/** Captures the exact canonical edits associated with one dispatched prompt. */
 export function recordAgentDispatch(revision, changes, structuralChanges = [], owner = captureHandoffOwner()) {
     dispatches.set(revision, {
         owner: structuredClone(owner),
@@ -187,11 +168,9 @@ export function recordAgentDispatch(revision, changes, structuralChanges = [], o
         structuralChanges: structuralChanges.map((change) => structuredClone(change)),
     });
 }
-/** Drops a captured revision when the bridge rejects its dispatch. */
 export function discardAgentDispatch(revision) {
     dispatches.delete(revision);
 }
-/** Returns how many canonical edits were in flight for one dispatch. */
 export function getAgentDispatchSize(revision) {
     const snapshot = dispatches.get(revision);
     if (!snapshot)
@@ -220,11 +199,7 @@ function afterBrowserPaint(doc) {
         });
     });
 }
-/**
- * Reconciles only records that still equal the sent snapshot and that remain
- * observable after removing Nudge's own preview. Newer edits and ambiguous
- * records are preserved.
- */
+/** Newer edits and ambiguous records are preserved. */
 export async function verifyAndReconcileHandoff(snapshot, doc = handoffDocument(snapshot.owner)) {
     if (!doc || !documentBelongsToHandoff(doc, snapshot.owner))
         return 0;
@@ -242,8 +217,6 @@ export async function verifyAndReconcileHandoff(snapshot, doc = handoffDocument(
     const eligible = current.filter((change) => sentByKey.get(changeKey(change)) === handoffChangeFingerprint(change));
     const eligibleKeys = new Set(eligible.map(changeKey));
     const remaining = current.filter((change) => !eligibleKeys.has(changeKey(change)));
-    // The same "still unchanged" rule for structural intent: only canonical
-    // records byte-identical to the dispatched snapshot may be reconciled.
     const sentStructural = new Map(snapshot.structuralChanges.map((change) => [change.id, handoffStructuralFingerprint(change)]));
     const currentStructural = getDraftChanges(snapshot.owner.draftId).structuralChanges;
     const eligibleStructural = currentStructural.filter((change) => sentStructural.get(change.id) === handoffStructuralFingerprint(change));
@@ -266,9 +239,7 @@ export async function verifyAndReconcileHandoff(snapshot, doc = handoffDocument(
             return 0;
         const verified = verifiedChangeKeys(eligible, doc);
         const verifiedStructural = verifiedStructuralChangeIds(eligibleStructural, doc);
-        // A user can make another inspector edit while the two-frame verification
-        // window is open. Recheck byte identity immediately before reconciliation
-        // so a newer value at the same key can never be removed.
+        // Recheck byte identity before reconciling; a user edit can land while the two-frame window is open.
         const currentByKey = new Map(getDraftChanges(snapshot.owner.draftId).changes.map((change) => [changeKey(change), handoffChangeFingerprint(change)]));
         const stillVerified = new Set([...verified].filter((key) => currentByKey.get(key) === sentByKey.get(key)));
         const currentStructuralById = new Map(getDraftChanges(snapshot.owner.draftId).structuralChanges.map((change) => [change.id, handoffStructuralFingerprint(change)]));
@@ -281,12 +252,11 @@ export async function verifyAndReconcileHandoff(snapshot, doc = handoffDocument(
         return reconcileDraftChanges(snapshot.owner.draftId, stillVerified, stillVerifiedStructural);
     }
     finally {
-        // Reconciliation reapplies the canonical set. If it was unable to write
-        // (for example, a read-only Canvas lease), restore the untouched set here.
+        // If reconciliation could not write (read-only Canvas lease), restore the untouched set; a Canvas restore settles on the renderer's acknowledgement.
         if (doc === document)
             await applyProjection(getActiveDraftChanges());
         else
-            restoreCanonicalFrameProjection(doc);
+            await restoreCanonicalFrameProjection(doc);
     }
 }
 export function documentBelongsToHandoff(doc, owner) {
@@ -308,11 +278,9 @@ function handoffDocument(owner) {
     }
     return owner.target.kind === "application" && !isEditorShellDocument() ? document : null;
 }
-/** Returns the records captured for one dispatch until it is reconciled. */
 export function getAgentDispatch(revision) {
     return dispatches.get(revision) ?? null;
 }
-/** Records in the owner draft that still equal what a handoff sent. */
 export function unchangedHandoffRecords(snapshot) {
     const sent = new Set(snapshot.changes.map(handoffChangeFingerprint));
     const sentStructural = new Set(snapshot.structuralChanges.map(handoffStructuralFingerprint));
@@ -322,7 +290,6 @@ export function unchangedHandoffRecords(snapshot) {
         structuralChanges: current.structuralChanges.filter((change) => sentStructural.has(handoffStructuralFingerprint(change))),
     };
 }
-/** Reconciles the captured records for one completed connected-agent request. */
 export async function verifyAndReconcileAgentDispatch(revision) {
     const snapshot = dispatches.get(revision);
     if (!snapshot)

package/dist/inspector/boot.d.ts

@@ -0,0 +1,5 @@
+import { type ReactElement } from "react";
+export type InspectorShell = () => ReactElement;
+export declare function bootstrapNudgeUi(inspectorHost: HTMLElement, shell?: InspectorShell): void;
+export declare function mountInspector(host: HTMLElement): void;
+export declare function unmountInspector(): void;