nudge-ui 0.2.4 → 0.2.5

package/dist/inspector/agent/httpTransport.js

@@ -1,4 +1,4 @@
-import { AGENT_PROTOCOL_VERSION, defaultBridgePort, isAgentPromptRequest, isAgentActivity, } from "./protocol.js";
+import { AGENT_PROTOCOL_VERSION, 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"]');
@@ -75,12 +74,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}`;
@@ -123,83 +122,6 @@ async function readJson(response) {
     }
     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,
-    };
-}
-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;
@@ -223,7 +145,7 @@ export class HttpAgentBridgeTransport {
         this.config = config;
     }
     async discover(request, signal) {
-        const url = endpointUrl(this.config, request.projectId, "healthUrl", "/health", pageOrigin());
+        const url = endpointUrl(this.config, "healthUrl", "/health", pageOrigin());
         if (!url || typeof fetch !== "function")
             return null;
         const response = await fetch(withQuery(url, {
@@ -238,10 +160,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", "/pair", pageOrigin());
         if (!url || typeof fetch !== "function")
             throw new Error("Agent bridge is unavailable.");
         const response = await fetch(url, {
@@ -250,26 +172,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", "/takeover", pageOrigin());
         if (!url || typeof fetch !== "function")
             throw new Error("Agent bridge is unavailable.");
         const response = await fetch(url, {
@@ -278,42 +187,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", "/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", "/events", pageOrigin());
         if (!url || typeof EventSource !== "function") {
             queueMicrotask(() => handlers.onDisconnect("Agent event transport is unavailable."));
             return { close: () => undefined };
@@ -325,10 +218,13 @@ 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))
+            const envelope = eventData(event);
+            if (!isRecord(envelope)
+                || envelope.protocolVersion !== AGENT_PROTOCOL_VERSION
+                || envelope.projectId !== request.projectId
+                || envelope.sessionToken !== request.sessionToken)
                 return;
-            const parsed = eventPayload(value);
+            const parsed = decodeBridgeEvent(envelope.event);
             if (parsed)
                 handlers.onEvent(parsed);
         };
@@ -355,7 +251,7 @@ export class HttpAgentBridgeTransport {
         };
     }
     async dispatch(request, signal) {
-        const url = endpointUrl(this.config, request.projectId, "promptUrl", "/prompt", pageOrigin());
+        const url = endpointUrl(this.config, "promptUrl", "/prompt", pageOrigin());
         if (!url || typeof fetch !== "function")
             throw new Error("Agent bridge is unavailable.");
         const response = await fetch(url, {
@@ -364,25 +260,13 @@ export class HttpAgentBridgeTransport {
             body: JSON.stringify(request),
             signal,
         });
-        const payload = await readJson(response);
-        if (!isRecord(payload.request) || payload.status !== "working") {
+        const dispatched = decodePromptDispatchResponse(await readJson(response), request.projectId);
+        if (!dispatched)
             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) {
-            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", "/disconnect", pageOrigin());
         if (!url || typeof fetch !== "function")
             return;
         await fetch(url, {
@@ -393,7 +277,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", "/canvas/ack", pageOrigin());
         if (!url || typeof fetch !== "function")
             return;
         await fetch(url, {

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

@@ -7,7 +7,7 @@ import type { AgentActivity, AgentStatusSnapshot, CanvasCommand, CanvasCommandAc
  * 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, 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;

package/dist/inspector/agent/protocol.js

@@ -6,4 +6,4 @@
  * 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, 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;

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";
@@ -283,10 +282,14 @@ export async function verifyAndReconcileHandoff(snapshot, doc = handoffDocument(
     finally {
         // Reconciliation reapplies the canonical set. If it was unable to write
         // (for example, a read-only Canvas lease), restore the untouched set here.
+        // A Canvas restore settles on the renderer's acknowledgement: that
+        // acknowledgement invalidates the frame's stylesheet revision, and a
+        // caller still inside this verification must not mistake it for a source
+        // change and schedule another verification.
         if (doc === document)
             await applyProjection(getActiveDraftChanges());
         else
-            restoreCanonicalFrameProjection(doc);
+            await restoreCanonicalFrameProjection(doc);
     }
 }
 export function documentBelongsToHandoff(doc, owner) {

package/dist/inspector/boot.d.ts

@@ -0,0 +1,3 @@
+export declare function bootstrapNudgeUi(inspectorHost: HTMLElement): void;
+export declare function mountInspector(host: HTMLElement): void;
+export declare function unmountInspector(): void;

package/dist/inspector/boot.js

@@ -0,0 +1,297 @@
+import { startWorkspaceController } from "./workspace/controller.js";
+import { createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { toggleInspector, setInspectorOpen } from "./shell/openStore.js";
+import { setSelectedElement } from "./selection/selectionStore.js";
+import { removeManagedSheet } from "./projection/managedStylesheet.js";
+import { isInspectorToggleShortcut, isOriginalPreviewShortcut, SEND_PROMPT_HOTKEY_EVENT, } from "./shell/shortcuts.js";
+import { isCanvasRenderer } from "./canvas/roleDetection.js";
+import { isPageSurface } from "./canvas/pageSurface.js";
+import { isKeyboardShortcutMessage } from "./canvas/frameProtocol.js";
+import { subscribeCanvasRendererMessages } from "./canvas/rendererMessageRouter.js";
+import { bootstrapRenderer } from "./canvas/rendererBootstrap.js";
+import { setRestoreCount, } from "./canvas/sessionStore.js";
+import { getChangesList } from "./drafts/store.js";
+import { acquireLease, enableWriteGuard, hasWriteLease, releaseLease, subscribeOwnership, } from "./canvas/workspaceLease.js";
+import { cancelStaleDetection, startStaleDetection } from "./canvas/staleChangeDetector.js";
+import { LockedWorkspaceNotice } from "./canvas/LockedWorkspaceNotice.js";
+import { AppShell } from "./shell/AppShell.js";
+import { installInspectionBridge } from "./inspection/bridge.js";
+import { releaseDocumentProjection, getStructuralChanges } from "./projection/structuralProjection.js";
+import { cancelInlineTextEdit } from "./inline-text/inlineTextEditor.js";
+import { configureNudgeUiRuntime, getNudgeUiRuntimeConfig, isDemoRuntime } from "./runtime/runtimeConfig.js";
+import { setCanvasMode } from "./canvas/viewStore.js";
+import { isNudgeUiDev, setNudgeUiHostDevFlag } from "./runtime/devFlag.js";
+import { clearClipboardHandoff, } from "./prompt/clipboardHandoff.js";
+import { createWorkspace, InspectorSessionProvider, } from "./session/index.js";
+import { clearSketchClipboardHandoff } from "./sketch/handoff.js";
+import { cancelSketchInteraction, isSketchInteractionActive } from "./sketch/interaction.js";
+import { setOriginalPreviewActive } from "./shell/originalPreview.js";
+import { initializeSketchStore } from "./sketch/store.js";
+import { inspectorStorage } from "./runtime/inspectorStorage.js";
+import { disposeRuntimeIdentityClaims } from "./runtime/runtimeIdentityClaims.js";
+let hostElement = null;
+let reactRoot = null;
+let lockedRoot = null;
+const workspace = createWorkspace();
+let inspectorSession = null;
+let rendererBootstrapHandle = null;
+let workspaceController = null;
+let unsubscribeOwnership = null;
+let removeInspectionBridge = null;
+let controllerStartId = 0;
+let keyboardPeekHeld = false;
+function onKeydown(e) {
+    if (isSketchInteractionActive())
+        return;
+    if (isInspectorToggleShortcut(e)) {
+        toggleInspector();
+        e.preventDefault();
+        return;
+    }
+    if (isOriginalPreviewShortcut(e)) {
+        keyboardPeekHeld = true;
+        setOriginalPreviewActive(true);
+        e.preventDefault();
+    }
+}
+function onKeyup(e) {
+    // Release only a keyboard-started peek so a button-held preview survives
+    // unrelated Backslash keyups (e.g. the panel-toggle shortcuts pressed
+    // mid-hold). A guarded keydown never sets the flag, so this stays a no-op
+    // for keyups without a matching hold.
+    if (e.code === "Backslash" && keyboardPeekHeld) {
+        keyboardPeekHeld = false;
+        setOriginalPreviewActive(false);
+    }
+}
+function onRendererKeyboardShortcut(message, identity) {
+    if (!isKeyboardShortcutMessage(message, identity))
+        return;
+    if (message.code === "KeyS" && message.phase === "keydown") {
+        window.dispatchEvent(new Event(SEND_PROMPT_HOTKEY_EVENT));
+        return;
+    }
+    if (message.code !== "Backslash")
+        return;
+    if (message.phase === "keydown") {
+        keyboardPeekHeld = true;
+        setOriginalPreviewActive(true);
+    }
+    else if (keyboardPeekHeld) {
+        keyboardPeekHeld = false;
+        setOriginalPreviewActive(false);
+    }
+}
+function disposeInspectorSession() {
+    const session = inspectorSession;
+    inspectorSession = null;
+    session?.dispose();
+}
+export function bootstrapNudgeUi(inspectorHost) {
+    controllerStartId += 1;
+    const runtimeConfig = getNudgeUiRuntimeConfig();
+    const explicitDemo = isDemoRuntime();
+    if (!isNudgeUiDev() && !explicitDemo)
+        return;
+    if (explicitDemo) {
+        rendererBootstrapHandle?.teardown();
+        rendererBootstrapHandle = null;
+        // ADR-0014: only the configured demo runtime opens the shared dev gate
+        // for its own document. The bundle mode name alone must never flip it,
+        // so every build without both opt-ins stays governed by ADR-0002.
+        setNudgeUiHostDevFlag(true);
+        if (runtimeConfig.capabilities.canvas && isCanvasRenderer()) {
+            rendererBootstrapHandle = bootstrapRenderer() ?? null;
+            return;
+        }
+        // The public demo shares the iframe editor while keeping the write lease,
+        // persistence, and agent bridge disabled.
+        setCanvasMode("canvas");
+        workspaceController?.dispose();
+        workspaceController = startWorkspaceController();
+        mountInspector(inspectorHost);
+        setInspectorOpen(false);
+        return;
+    }
+    if (!runtimeConfig.capabilities.canvas) {
+        // A project can be reopened with a runtime that does not expose Canvas.
+        // Clear any stale in-memory mode before mounting the static inspector.
+        setCanvasMode("inspect");
+    }
+    rendererBootstrapHandle?.teardown();
+    rendererBootstrapHandle = null;
+    removeInspectionBridge?.();
+    removeInspectionBridge = installInspectionBridge();
+    if (getNudgeUiRuntimeConfig().capabilities.canvas && isCanvasRenderer()) {
+        rendererBootstrapHandle = bootstrapRenderer() ?? null;
+        return;
+    }
+    enableWriteGuard();
+    const leaseGranted = acquireLease();
+    if (!leaseGranted) {
+        mountLockedNotice(inspectorHost);
+        return;
+    }
+    void startController(inspectorHost);
+}
+async function startController(inspectorHost) {
+    const startId = ++controllerStartId;
+    if (!hasWriteLease()) {
+        mountLockedNotice(inspectorHost);
+        return;
+    }
+    // Ownership prevents the previous tab from saving after this snapshot.
+    // Refresh on remount as well as explicit takeover, before hydration writes.
+    try {
+        const storage = inspectorStorage();
+        if (storage?.refresh)
+            await storage.refresh();
+    }
+    catch {
+        if (startId !== controllerStartId)
+            return;
+        releaseLease();
+        mountLockedNotice(inspectorHost, true);
+        return;
+    }
+    if (startId !== controllerStartId)
+        return;
+    if (!hasWriteLease()) {
+        mountLockedNotice(inspectorHost);
+        return;
+    }
+    if (lockedRoot) {
+        lockedRoot.unmount();
+        lockedRoot = null;
+    }
+    void initializeSketchStore(getNudgeUiRuntimeConfig().projectId).catch(() => undefined);
+    unsubscribeOwnership?.();
+    unsubscribeOwnership = subscribeOwnership((hasLease) => {
+        if (!hasLease) {
+            workspaceController?.dispose();
+            workspaceController = null;
+            mountLockedNotice(inspectorHost);
+        }
+    });
+    workspaceController?.dispose();
+    const result = startWorkspaceController();
+    workspaceController = result;
+    if (result.restored) {
+        setRestoreCount(getChangesList().length + getStructuralChanges().length);
+        const restored = getChangesList();
+        if (restored.length > 0) {
+            startStaleDetection(restored);
+        }
+    }
+    if (getNudgeUiRuntimeConfig().capabilities.canvas) {
+        // Normal controllers always host the iframe workspace. Hydration runs
+        // first so this mode change cannot discard cards, camera, or edits.
+        setCanvasMode("canvas");
+    }
+    mountInspector(inspectorHost);
+    if (getNudgeUiRuntimeConfig().capabilities.canvas && isPageSurface()) {
+        rendererBootstrapHandle = bootstrapRenderer() ?? null;
+    }
+}
+function mountLockedNotice(host, storageError = false) {
+    controllerStartId += 1;
+    if (reactRoot) {
+        reactRoot.unmount();
+        reactRoot = null;
+    }
+    try {
+        disposeInspectorSession();
+    }
+    finally {
+        cancelStaleDetection();
+        setInspectorOpen(false);
+        cancelInlineTextEdit();
+        cancelSketchInteraction();
+        clearSketchClipboardHandoff();
+        setSelectedElement(null);
+        removeManagedSheet();
+        disposeRuntimeIdentityClaims(document);
+        releaseDocumentProjection(document);
+        hostElement = null;
+        unsubscribeOwnership?.();
+        unsubscribeOwnership = null;
+    }
+    const shadow = host.shadowRoot ?? host.attachShadow({ mode: "open" });
+    if (!lockedRoot) {
+        lockedRoot = createRoot(shadow);
+    }
+    lockedRoot.render(createElement(LockedWorkspaceNotice, {
+        onTakeover: () => startController(host),
+        storageError,
+    }));
+}
+export function mountInspector(host) {
+    const demo = isDemoRuntime();
+    if (!demo && !hasWriteLease())
+        return;
+    const runtimeConfig = getNudgeUiRuntimeConfig();
+    if (runtimeConfig.capabilities.domNavigation !== true) {
+        configureNudgeUiRuntime({
+            ...runtimeConfig,
+            capabilities: { ...runtimeConfig.capabilities, domNavigation: true },
+        });
+    }
+    if (lockedRoot) {
+        lockedRoot.unmount();
+        lockedRoot = null;
+    }
+    if (!hostElement)
+        hostElement = host;
+    const shadow = host.shadowRoot ?? host.attachShadow({ mode: "open" });
+    if (!reactRoot) {
+        reactRoot = createRoot(shadow);
+        inspectorSession = workspace.createInspectorSession(host);
+        inspectorSession.registerCleanup(() => window.removeEventListener("keydown", onKeydown));
+        inspectorSession.registerCleanup(() => window.removeEventListener("keyup", onKeyup));
+        inspectorSession.registerCleanup(subscribeCanvasRendererMessages(({ frame, message }) => {
+            onRendererKeyboardShortcut(message, frame.identity);
+        }));
+        reactRoot.render(createElement(InspectorSessionProvider, { inspector: inspectorSession, documentSession: null }, createElement(AppShell)));
+        window.addEventListener("keydown", onKeydown);
+        window.addEventListener("keyup", onKeyup);
+    }
+    setInspectorOpen(true);
+}
+export function unmountInspector() {
+    controllerStartId += 1;
+    rendererBootstrapHandle?.teardown();
+    rendererBootstrapHandle = null;
+    workspaceController?.dispose();
+    workspaceController = null;
+    unsubscribeOwnership?.();
+    unsubscribeOwnership = null;
+    if (lockedRoot) {
+        lockedRoot.unmount();
+        lockedRoot = null;
+    }
+    cancelStaleDetection();
+    cancelInlineTextEdit();
+    cancelSketchInteraction();
+    setSelectedElement(null);
+    if (reactRoot) {
+        reactRoot.unmount();
+        reactRoot = null;
+    }
+    try {
+        disposeInspectorSession();
+    }
+    finally {
+        // Document-session cleanup already releases host projection when a
+        // session exists; release directly as well so projection applied outside
+        // a session (gestures, workspace projection) cannot leak across unmount.
+        disposeRuntimeIdentityClaims(document);
+        releaseDocumentProjection(document);
+        clearClipboardHandoff();
+        clearSketchClipboardHandoff();
+        removeManagedSheet();
+        removeInspectionBridge?.();
+        removeInspectionBridge = null;
+        hostElement = null;
+    }
+}

package/dist/inspector/canvas/AgentActivityOverlay.d.ts

@@ -1,3 +1,4 @@
+import { type CanvasFrame } from "./canvasFrame.js";
 import { type ActivityFile } from "../agent/activity.js";
 import { type FrameContent } from "./frameContent.js";
 export interface ActivityAttribution {
@@ -9,5 +10,5 @@ export declare function attributeActivity(content: FrameContent, document: Docum
 export declare function AgentActivityOverlay({ cardId, content, iframe }: {
     cardId: string;
     content: FrameContent;
-    iframe: HTMLIFrameElement | null;
+    iframe: CanvasFrame | null;
 }): import("react").JSX.Element | null;