nudge-ui 0.2.0 → 0.2.2

package/dist/hosts/static/server.js

@@ -6,7 +6,9 @@ import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path
 import { createRequire } from "node:module";
 import { instrumentSourceHtml } from "../../html/identity.js";
 import { injectStandaloneBootstrap } from "./html/bootstrap.js";
-import { createStandaloneRuntimeManifest, NUDGE_UI_CLIENT_PATH, NUDGE_UI_MANIFEST_PATH, NUDGE_UI_RELOAD_PATH, NUDGE_UI_ROUTE_PREFIX, } from "./manifest.js";
+import { createNudgeUiEditorDocument, isNudgeUiEditorDocumentRequest } from "../../transport/editor.js";
+import { createStandaloneRuntimeManifest, NUDGE_UI_CLIENT_PATH, NUDGE_UI_EDITOR_PATH, NUDGE_UI_MANIFEST_PATH, NUDGE_UI_RELOAD_PATH, NUDGE_UI_ROUTE_PREFIX, } from "./manifest.js";
+import { startOptionalProjectBridge } from "../projectBridge.js";
 import { createProjectTokenSnapshot, EMPTY_PROJECT_TOKEN_SNAPSHOT } from "../../project/tokens.js";
 import { createProjectFileWatcher, isSensitiveProjectPath, } from "../../project/files.js";
 const LOOPBACK_HOSTS = new Set(["127.0.0.1", "::1", "localhost"]);
@@ -36,6 +38,7 @@ export function createStandaloneServer(options) {
     const projectId = options.projectId ?? createStandaloneProjectId(rootDirectory);
     let revision = 0;
     let manifest = createStandaloneRuntimeManifest(projectId, EMPTY_PROJECT_TOKEN_SNAPSHOT, revision);
+    let projectBridge = null;
     // The initial scan runs asynchronously; start() awaits it so the first
     // request and manifest always observe the complete project token knowledge.
     const initialTokens = createProjectTokenSnapshot({ rootDirectory, generationLabel: "static-html" }).then((tokens) => {
@@ -78,7 +81,10 @@ export function createStandaloneServer(options) {
             // The scan is asynchronous and bounded to the project root; rebuilding
             // once per settled batch keeps the manifest coherent before reload.
             const tokens = await createProjectTokenSnapshot({ rootDirectory, generationLabel: "static-html" });
-            manifest = createStandaloneRuntimeManifest(projectId, tokens, revision + 1);
+            manifest = {
+                ...createStandaloneRuntimeManifest(projectId, tokens, revision + 1),
+                ...(projectBridge ? { agentBridge: projectBridge.browser } : {}),
+            };
             revision += 1;
             notifyReload();
         }).catch((error) => {
@@ -146,7 +152,23 @@ export function createStandaloneServer(options) {
                             rejectStart(new Error("Standalone server closed during startup."));
                             return;
                         }
-                        resolveStart(readAddress(httpServer, host));
+                        const address = readAddress(httpServer, host);
+                        void startOptionalProjectBridge({
+                            appRoot: rootDirectory,
+                            projectId,
+                            origin: address.url.replace(/\/$/, ""),
+                            info: (message) => console.info(message),
+                            warn: (message) => console.warn(message),
+                        }).then((bridge) => {
+                            projectBridge = bridge;
+                            if (bridge)
+                                manifest = { ...manifest, agentBridge: bridge.browser };
+                            if (closeRequested) {
+                                rejectStart(new Error("Standalone server closed during startup."));
+                                return;
+                            }
+                            resolveStart(address);
+                        });
                     });
                 };
                 httpServer.once("error", onError);
@@ -165,6 +187,10 @@ export function createStandaloneServer(options) {
             closeReloadClients();
             const closing = closeWatcher
                 .then(() => pendingStart?.catch(() => undefined))
+                .then(async () => {
+                await projectBridge?.close();
+                projectBridge = null;
+            })
                 .then(() => changeQueue)
                 .then(() => {
                 if (!httpServer.listening)
@@ -370,6 +396,13 @@ async function handleRequest(input) {
         await handleNudgeUiRoute(input, decodedPath);
         return;
     }
+    if (isNudgeUiEditorDocumentRequest(request.url ?? "/", request.method, request.headers)) {
+        const body = request.method === "HEAD"
+            ? Buffer.alloc(0)
+            : Buffer.from(createNudgeUiEditorDocument(), "utf8");
+        sendBody(response, 200, body, "text/html; charset=utf-8", { "Cache-Control": "no-store" });
+        return;
+    }
     const resolution = resolveDecodedStaticFile(input.rootDirectory, decodedPath);
     if (!resolution) {
         sendText(response, 404, "Not Found");
@@ -434,6 +467,15 @@ async function handleNudgeUiRoute(input, pathname) {
         });
         return;
     }
+    if (pathname === NUDGE_UI_EDITOR_PATH) {
+        const body = input.request.method === "HEAD"
+            ? Buffer.alloc(0)
+            : Buffer.from(createNudgeUiEditorDocument(), "utf8");
+        sendBody(input.response, 200, body, "text/html; charset=utf-8", {
+            "Cache-Control": "no-store",
+        });
+        return;
+    }
     if (pathname === NUDGE_UI_CLIENT_PATH) {
         try {
             const body = await readFileFromDescriptor(input.clientPath ?? resolveDefaultClientPath());

package/dist/hosts/vite/vite.d.ts

@@ -18,11 +18,16 @@ export interface VanillaExtractOptions {
     source?: string;
 }
 export interface NudgeUiOptions extends ReactOptions {
+    /** `false` registers nothing. `NUDGE_UI=0` has the same effect for one run. */
     enabled?: boolean;
     /** Enables experimental DOM parent/child navigation in the Inspector. */
     debug?: boolean;
-    /** The landing app's demo runtime: mounted at root in dev and `nudge-demo` builds, or via `?nudgeDemo=1`. */
+    /** Enables the landing app's restricted, iframe-backed demo runtime. */
     demo?: boolean;
+    /** Additional same-origin routes shown when the public demo opens. */
+    demoPages?: readonly string[];
+    /** Labels for the seeded demo cards in display order, including the primary card. */
+    demoCardLabels?: readonly string[];
     /** Explicit project ID for browser-storage keys (defaults to root directory basename). */
     projectId?: string;
     /** Optional static v3 config for fixture/app integrations; dynamic configs are not executed. */

package/dist/hosts/vite/vite.js

@@ -2,11 +2,13 @@ import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { basename, join, relative, resolve, sep, } from "node:path";
 import { createTokenInventory, } from "../../css/token-inventory/index.js";
-import { NUDGE_UI_CLIENT_PATH, NUDGE_UI_MANIFEST_PATH } from "../../transport/index.js";
+import { NUDGE_UI_CLIENT_PATH, NUDGE_UI_EDITOR_PATH, NUDGE_UI_MANIFEST_PATH, createNudgeUiEditorDocument, isNudgeUiEditorDocumentRequest, } from "../../transport/index.js";
 import { discoverCssImportGraph, stripCssQuery } from "./tokens/activeStylesheets.js";
 import { catalogSourcePath, createViteStylesheetArtifact, isHostApplicationSource, isPackageStylesheet, orderViteStylesheetGraph, } from "./tokens/viteStylesheetArtifacts.js";
 import { interpretDialects } from "../../css/dialects/index.js";
 import { detectStylingSystem, } from "../../inspector/clientManifest.js";
+import { loopbackOrigin, startOptionalProjectBridge, } from "../projectBridge.js";
+import { automationManifestFields, isNudgeUiEnabled } from "../environment.js";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -100,12 +102,14 @@ function invalidateHmrModules(server, modules, timestamp) {
  * here has grown a React assumption.
  */
 export function createVitePlugins(options = {}, createFramework = null) {
-    const enabled = options.enabled ?? true;
+    const enabled = isNudgeUiEnabled(options.enabled);
     let root;
     let buildOutputDirectory;
     let command = "serve";
     let demoBuild = false;
     let devServer;
+    let projectBridge = null;
+    let projectBridgeStart = null;
     let postTransformPromise = null;
     const inventory = createTokenInventory();
     const activeHostCssFiles = new Set();
@@ -473,14 +477,43 @@ export function createVitePlugins(options = {}, createFramework = null) {
         return postTransformPromise;
     }
     async function buildClientManifest() {
+        await projectBridgeStart;
         await ensurePostTransformCss();
         await ensurePublishedThemeContract();
         return {
             version: 1,
             revision: 0,
             runtime: buildRuntimeSnapshot(),
+            ...(projectBridge ? { agentBridge: projectBridge.browser } : {}),
+            ...automationManifestFields(),
         };
     }
+    function startProjectBridge(server) {
+        // The public demo uses the shared editor runtime without project-owned
+        // sessions, an agent bridge, or filesystem persistence.
+        if (options.demo === true || !root || projectBridgeStart)
+            return;
+        const address = server.httpServer?.address();
+        if (!address || typeof address === "string")
+            return;
+        const origin = server.resolvedUrls?.local[0]
+            ? new URL(server.resolvedUrls.local[0]).origin
+            : loopbackOrigin(address, server.config.server.https ? "https" : "http");
+        const allowedOrigins = [
+            ...(server.resolvedUrls?.local ?? []),
+            ...(server.resolvedUrls?.network ?? []),
+        ].map((url) => new URL(url).origin);
+        projectBridgeStart = startOptionalProjectBridge({
+            appRoot: root,
+            projectId: options.projectId ?? basename(root),
+            origin,
+            ...(allowedOrigins.length > 0 ? { allowedOrigins } : {}),
+            info: (message) => server.config.logger.info(message),
+            warn: (message) => server.config.logger.warn(message),
+        }).then((bridge) => {
+            projectBridge = bridge;
+        });
+    }
     function buildRuntimeSnapshot() {
         syncInventoryContributions();
         const snapshot = inventory.snapshot();
@@ -497,6 +530,9 @@ export function createVitePlugins(options = {}, createFramework = null) {
             host: framework?.hostLabel ?? "static-html",
             framework: framework?.framework ?? "HTML",
             stylingSystem: detectStylingSystem(snapshot.tokens),
+            ...(options.demo === true ? { demo: true } : {}),
+            ...(options.demoPages === undefined ? {} : { demoPages: options.demoPages }),
+            ...(options.demoCardLabels === undefined ? {} : { demoCardLabels: options.demoCardLabels }),
             capabilities: { canvas: true, componentSemantics: framework !== null },
             tokenCatalog: snapshot.definitions.map((definition) => ({
                 ...definition,
@@ -536,16 +572,38 @@ export function createVitePlugins(options = {}, createFramework = null) {
             if (!enabled || command !== "serve")
                 return;
             devServer = server;
+            if (server.httpServer?.listening)
+                startProjectBridge(server);
+            else
+                server.httpServer?.once("listening", () => startProjectBridge(server));
+            server.httpServer?.once("close", () => {
+                void projectBridgeStart?.then(() => projectBridge?.close()).finally(() => {
+                    projectBridge = null;
+                    projectBridgeStart = null;
+                });
+            });
             const runtimeWarning = framework?.unresolvedRuntimeWarning();
             if (runtimeWarning)
                 server.config.logger.warn(runtimeWarning);
             server.middlewares?.use(async (request, response, next) => {
                 const pathname = new URL(request.url ?? "/", "http://nudge-ui.local").pathname;
-                if ((pathname === CLIENT_PATH || pathname === MANIFEST_PATH) && request.method !== "GET") {
+                const invalidReservedMethod = (pathname === CLIENT_PATH || pathname === MANIFEST_PATH)
+                    ? request.method !== "GET"
+                    : pathname === NUDGE_UI_EDITOR_PATH
+                        && request.method !== "GET"
+                        && request.method !== "HEAD";
+                if (invalidReservedMethod) {
                     response.statusCode = 405;
                     response.end();
                     return;
                 }
+                if (isNudgeUiEditorDocumentRequest(request.url ?? "/", request.method, request.headers)) {
+                    response.statusCode = 200;
+                    response.setHeader("Content-Type", "text/html; charset=utf-8");
+                    response.setHeader("Cache-Control", "no-store");
+                    response.end(request.method === "HEAD" ? undefined : createNudgeUiEditorDocument());
+                    return;
+                }
                 if (pathname === CLIENT_PATH) {
                     try {
                         response.statusCode = 200;
@@ -628,29 +686,39 @@ export function createVitePlugins(options = {}, createFramework = null) {
                     return `export {};\n`;
                 }
                 if (options.demo === true) {
-                    const landingDemoExpression = demoBuild
+                    const demoControllerExpression = demoBuild
                         ? "true"
                         : '(import.meta.env.DEV && window.location.pathname === "/")';
                     // Taken from the composed framework, so the demo bootstrap cannot drift
                     // from the manifest the transport serves.
                     const identity = buildRuntimeSnapshot();
                     return [
-                        'import { bootstrapNudgeUi, configureNudgeUiRuntime, detectFramework, setInspectorOpen } from "nudge-ui/internal/inspector";',
+                        'import { bootstrapNudgeUi, configureNudgeUiRuntime, createNudgeUiEditorUrl, detectFramework, hasNudgeUiDirectTabIntent, isCanvasRenderer, isNudgeUiDirectUrl, readNudgeUiEditorTarget, rememberNudgeUiDirectTabIntent } from "nudge-ui/internal/inspector";',
                         'import { tokenCatalog, tokens, tokenDiagnostics, tokenGeneration, nudgeUiProjectId } from "virtual:design-tokens";',
                         ...(framework
                             ? [`import { componentContracts } from ${JSON.stringify(framework.virtualModuleId)};`]
                             : []),
-                        'const __nudge_ui_demo_frame = new URLSearchParams(window.location.search).get("nudgeDemo") === "1";',
-                        `const __nudge_ui_landing_demo = ${landingDemoExpression};`,
-                        'const __nudge_ui_demo_runtime = __nudge_ui_demo_frame || __nudge_ui_landing_demo;',
-                        'if (__nudge_ui_demo_runtime || (import.meta.env.DEV && window.location.pathname !== "/demo")) {',
+                        'const __nudge_ui_renderer = isCanvasRenderer();',
+                        'const __nudge_ui_explicit_direct = isNudgeUiDirectUrl(window.location.href);',
+                        'if (__nudge_ui_explicit_direct) rememberNudgeUiDirectTabIntent();',
+                        'const __nudge_ui_direct_tab = hasNudgeUiDirectTabIntent();',
+                        `const __nudge_ui_demo_controller = !__nudge_ui_renderer && !__nudge_ui_explicit_direct && !__nudge_ui_direct_tab && ${demoControllerExpression};`,
+                        'const __nudge_ui_editor_target = readNudgeUiEditorTarget(window.location.href) ?? (__nudge_ui_demo_controller ? window.location.href : null);',
+                        'if (__nudge_ui_demo_controller && readNudgeUiEditorTarget(window.location.href) === null) {',
+                        '  window.history.replaceState(window.history.state, "", createNudgeUiEditorUrl(window.location.href));',
+                        '}',
+                        'if (__nudge_ui_editor_target) document.documentElement.setAttribute("data-nudge-ui-editor", "");',
+                        'if (__nudge_ui_renderer) document.documentElement.setAttribute("data-nudge-ui-renderer", "");',
+                        'if (__nudge_ui_editor_target || __nudge_ui_renderer) {',
                         '  configureNudgeUiRuntime({',
                         '    projectId: nudgeUiProjectId,',
                         `    host: ${JSON.stringify(identity.host)},`,
                         `    framework: ${JSON.stringify(identity.framework)},`,
                         '    stylingSystem: detectFramework(tokens).stylingSystem,',
-                        '    ...(__nudge_ui_demo_runtime ? { demo: true } : {}),',
-                        `    capabilities: { canvas: __nudge_ui_demo_runtime ? false : true, componentSemantics: ${String(framework !== null)} },`,
+                        '    demo: true,',
+                        `    demoPages: ${JSON.stringify(options.demoPages ?? [])},`,
+                        `    demoCardLabels: ${JSON.stringify(options.demoCardLabels ?? [])},`,
+                        `    capabilities: { canvas: true, componentSemantics: ${String(framework !== null)} },`,
                         '    tokenCatalog,',
                         '    tokens,',
                         '    tokenDiagnostics,',
@@ -660,12 +728,11 @@ export function createVitePlugins(options = {}, createFramework = null) {
                         '  const __dt_root = document.getElementById("nudge-ui-root");',
                         '  if (__dt_root) {',
                         '    bootstrapNudgeUi(__dt_root);',
-                        '    if (__nudge_ui_demo_runtime) {',
-                        '      setInspectorOpen(false);',
-                        '      window.addEventListener("nudge-ui:open", () => setInspectorOpen(true));',
-                        '    }',
                         '  }',
                         '}',
+                        'window.addEventListener("nudge-ui:open", () => {',
+                        '  if (!__nudge_ui_renderer && (__nudge_ui_explicit_direct || __nudge_ui_direct_tab)) window.location.assign(createNudgeUiEditorUrl(window.location.href));',
+                        '});',
                     ].join("\n");
                 }
                 return null;

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

@@ -1,13 +1,14 @@
 import type { ReactElement } from "react";
 import type { AgentClientSnapshot } from "./client.js";
 export declare const MCP_DOCS_URL = "https://github.com/charlessmart/nudge-ui#connect-a-coding-agent";
-/** Builds the project-local add-mcp command shown by the connection panel. */
-export declare function createMcpSetupCommand(projectId: string, origin: string): string;
+/** Uses the guided installer so browser diagnostics never become shell arguments. */
+export declare function createMcpSetupCommand(): string;
 export interface McpConnectionContentProps {
     readonly projectId: string;
     readonly origin: string;
     readonly snapshot: AgentClientSnapshot;
     readonly onConnect: () => Promise<boolean> | boolean | void;
+    readonly onTakeOver: () => Promise<boolean> | boolean | void;
     readonly onDisconnect: () => void;
     readonly onCheckAgain: () => Promise<void>;
 }
@@ -16,11 +17,11 @@ export interface McpConnectionDialogProps extends McpConnectionContentProps {
     readonly onOpenChange: (open: boolean) => void;
 }
 /** Renders the MCP setup and pairing flow without owning a dialog surface. */
-export declare function McpConnectionContent({ projectId, origin, snapshot, onConnect, onDisconnect, onCheckAgain, }: McpConnectionContentProps): ReactElement;
+export declare function McpConnectionContent({ projectId, origin, snapshot, onConnect, onTakeOver, onDisconnect, onCheckAgain, }: McpConnectionContentProps): ReactElement;
 /**
  * Explains and controls the project-scoped MCP companion connection.
  *
  * This compatibility wrapper keeps the existing standalone MCP surface while
  * the shared content is also embedded in the general settings modal.
  */
-export declare function McpConnectionDialog({ open, projectId, origin, snapshot, onOpenChange, onConnect, onDisconnect, onCheckAgain, }: McpConnectionDialogProps): ReactElement;
+export declare function McpConnectionDialog({ open, projectId, origin, snapshot, onOpenChange, onConnect, onTakeOver, onDisconnect, onCheckAgain, }: McpConnectionDialogProps): ReactElement;

package/dist/inspector/agent/McpConnectionDialog.js

@@ -5,35 +5,13 @@ import { IconCheck, IconClipboard, IconExternalLink, IconPlugConnected, IconRefr
 import { getAgentConnectionStatus } from "./connectionStatus.js";
 import { copyToClipboard } from "../prompt/copyToClipboard.js";
 import { Button } from "../ui/Button.js";
+import { Disclosure } from "../ui/Disclosure.js";
 import { SegmentedControl } from "../ui/SegmentedControl.js";
 import { StatusCallout } from "../ui/StatusCallout.js";
 export const MCP_DOCS_URL = "https://github.com/charlessmart/nudge-ui#connect-a-coding-agent";
-/** Quotes one value for a POSIX shell command. */
-function shellQuote(value) {
-    return `'${value.replaceAll("'", "'\\''")}'`;
-}
-function shellArgument(value) {
-    // Keep the usual command readable while quoting values that could be
-    // interpreted as shell syntax when add-mcp runs the nested command.
-    return /^[A-Za-z0-9_./:@%+=,-]+$/.test(value) ? value : shellQuote(value);
-}
-/** Builds the project-local add-mcp command shown by the connection panel. */
-export function createMcpSetupCommand(projectId, origin) {
-    const serverCommand = [
-        "npx -y @nudge-ui/mcp@latest",
-        "--project-id",
-        shellArgument(projectId),
-        "--origin",
-        shellArgument(origin),
-        "--workspace-root .",
-    ].join(" ");
-    return `npx add-mcp ${shellQuote(serverCommand)} --name nudge_ui`;
-}
-function formatMcpSetupCommand(command) {
-    return command
-        .replace(" --project-id ", "\n  --project-id ")
-        .replace(" --origin ", "\n  --origin ")
-        .replace(" --workspace-root ", "\n  --workspace-root ");
+/** Uses the guided installer so browser diagnostics never become shell arguments. */
+export function createMcpSetupCommand() {
+    return "npx nudge-ui agent setup";
 }
 function portalContainer() {
     return typeof document !== "undefined"
@@ -44,7 +22,7 @@ function TimelineStep({ number, complete, title, children, }) {
     return (_jsxs("li", { className: `mcp-connection__timeline-step${complete ? " mcp-connection__timeline-step--complete" : ""}`, "data-test": `mcp-step-${number}`, "data-complete": complete ? "true" : "false", children: [_jsx("div", { className: "mcp-connection__timeline-marker", "aria-hidden": "true", children: complete ? _jsx(IconCheck, { size: "var(--icon-size-small)", stroke: 2 }) : number }), _jsxs("section", { className: "mcp-connection__timeline-content", children: [_jsx("h3", { className: "mcp-connection__section-title", children: title }), children] })] }));
 }
 /** Renders the MCP setup and pairing flow without owning a dialog surface. */
-export function McpConnectionContent({ projectId, origin, snapshot, onConnect, onDisconnect, onCheckAgain, }) {
+export function McpConnectionContent({ projectId, origin, snapshot, onConnect, onTakeOver, onDisconnect, onCheckAgain, }) {
     const [checking, setChecking] = useState(false);
     const [setupMethod, setSetupMethod] = useState("ai");
     const [copiedCommand, setCopiedCommand] = useState(false);
@@ -52,24 +30,29 @@ export function McpConnectionContent({ projectId, origin, snapshot, onConnect, o
     const [copiedListener, setCopiedListener] = useState(false);
     const [copyError, setCopyError] = useState();
     const [checkError, setCheckError] = useState();
-    const setupCommand = useMemo(() => createMcpSetupCommand(projectId, origin), [origin, projectId]);
-    const displaySetupCommand = useMemo(() => formatMcpSetupCommand(setupCommand), [setupCommand]);
+    const setupCommand = createMcpSetupCommand();
     const setupPrompt = useMemo(() => [
-        "Please configure the Nudge MCP companion for this project.",
+        "Please set up the Nudge coding-agent integration for this application.",
         "",
-        "Run this command from the project root:",
+        "Run this command from the application directory and select this coding agent:",
         setupCommand,
         "",
-        "Then restart or refresh the MCP server so Nudge can connect.",
+        "Start the application normally. Reload the agent if needed, then listen to Nudge.",
     ].join("\n"), [setupCommand]);
-    const listenerInstruction = "Call nudge_listen now and wait for my Nudge UI prompt. After applying it, call nudge_report_status and listen again.";
+    const listenerInstruction = "Listen to Nudge for this application in the current worktree. Use nudge_list_sessions if selection is ambiguous, then call nudge_listen. After applying each prompt, call nudge_report_status and listen again until I ask you to stop.";
     const status = getAgentConnectionStatus(snapshot);
     const canConnect = snapshot.companionReachable
         && !snapshot.paired
+        && !snapshot.pairedElsewhere
         && snapshot.state !== "pairing"
         && snapshot.state !== "working"
         && snapshot.request?.status !== "working";
     const canDisconnect = snapshot.paired || snapshot.request?.status === "working";
+    const canTakeOver = snapshot.companionReachable
+        && snapshot.pairedElsewhere
+        && snapshot.state !== "pairing"
+        && snapshot.state !== "working"
+        && snapshot.request?.status !== "working";
     async function handleCheckAgain() {
         if (checking)
             return;
@@ -118,10 +101,10 @@ export function McpConnectionContent({ projectId, origin, snapshot, onConnect, o
             setCopyError("The listener instruction could not be copied. Select it and copy it manually.");
         }
     }
-    return (_jsxs(_Fragment, { children: [_jsxs(StatusCallout, { className: "mcp-connection__status", tone: status.tone, "data-test": "mcp-connection-status", children: [_jsx("span", { className: "mcp-connection__status-label", role: "status", children: status.label }), snapshot.error ? (_jsx("span", { className: "mcp-connection__status-detail", children: snapshot.error })) : null, checkError ? _jsx("span", { role: "alert", children: checkError }) : null, snapshot.request?.summary ? (_jsx("span", { className: "mcp-connection__status-detail", children: snapshot.request.summary })) : null, snapshot.request?.error ? (_jsx("span", { className: "mcp-connection__status-detail", children: snapshot.request.error })) : null] }), _jsxs("ol", { className: "mcp-connection__timeline", "data-test": "mcp-connection-timeline", children: [_jsxs(TimelineStep, { number: 1, complete: snapshot.companionReachable, title: "Configure the MCP host", children: [_jsx(SegmentedControl, { "aria-label": "MCP setup method", className: "mcp-connection__setup-tabs", "data-test": "mcp-setup-tabs", value: setupMethod, options: [
+    return (_jsxs(_Fragment, { children: [_jsxs(StatusCallout, { className: "mcp-connection__status", tone: status.tone, "data-test": "mcp-connection-status", children: [_jsx("span", { className: "mcp-connection__status-label", role: "status", children: status.label }), snapshot.error ? (_jsx("span", { className: "mcp-connection__status-detail", children: snapshot.error })) : null, checkError ? _jsx("span", { role: "alert", children: checkError }) : null, snapshot.request?.summary ? (_jsx("span", { className: "mcp-connection__status-detail", children: snapshot.request.summary })) : null, snapshot.request?.error ? (_jsx("span", { className: "mcp-connection__status-detail", children: snapshot.request.error })) : null] }), _jsxs("ol", { className: "mcp-connection__timeline", "data-test": "mcp-connection-timeline", children: [_jsxs(TimelineStep, { number: 1, complete: snapshot.listenerActive || snapshot.request !== null, title: "Set up your agent once", children: [_jsx(SegmentedControl, { "aria-label": "MCP setup method", className: "mcp-connection__setup-tabs", "data-test": "mcp-setup-tabs", value: setupMethod, options: [
                                     { value: "ai", label: "AI instructions", testId: "mcp-setup-tab-ai" },
                                     { value: "terminal", label: "Terminal command", testId: "mcp-setup-tab-terminal" },
-                                ], onChange: setSetupMethod }), setupMethod === "terminal" ? (_jsxs(_Fragment, { children: [_jsx("p", { className: "mcp-connection__copy", children: "Run this command from your project root." }), _jsx("pre", { className: "mcp-connection__command", children: _jsx("code", { "data-test": "mcp-setup-command", children: displaySetupCommand }) }), _jsx("div", { className: "mcp-connection__command-actions", children: _jsxs(Button, { variant: "secondary", "data-test": "mcp-copy-command", type: "button", onClick: () => void handleCopyCommand(), children: [copiedCommand ? _jsx(IconCheck, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) : _jsx(IconClipboard, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), copiedCommand ? "Copied" : "Copy command"] }) })] })) : (_jsxs(_Fragment, { children: [_jsx("p", { className: "mcp-connection__copy", children: "Copy this prompt into your coding agent to configure Nudge MCP." }), _jsx("pre", { className: "mcp-connection__command", children: _jsx("code", { "data-test": "mcp-setup-prompt", children: setupPrompt }) }), _jsx("div", { className: "mcp-connection__command-actions", children: _jsxs(Button, { variant: "secondary", "data-test": "mcp-copy-setup-prompt", type: "button", onClick: () => void handleCopyPrompt(), children: [copiedPrompt ? _jsx(IconCheck, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) : _jsx(IconClipboard, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), copiedPrompt ? "Copied" : "Copy prompt"] }) })] }))] }), _jsxs(TimelineStep, { number: 2, complete: snapshot.paired, title: "Connect this page", children: [_jsxs("dl", { className: "mcp-connection__diagnostics", "data-test": "mcp-connection-diagnostics", children: [_jsxs("div", { className: "mcp-connection__diagnostic", children: [_jsx("dt", { children: "Project ID" }), _jsx("dd", { "data-test": "mcp-project-id", children: _jsx("code", { children: projectId }) })] }), _jsxs("div", { className: "mcp-connection__diagnostic", children: [_jsx("dt", { children: "Origin" }), _jsx("dd", { "data-test": "mcp-origin", children: _jsx("code", { children: origin }) })] })] }), _jsxs("div", { className: "mcp-connection__actions", children: [canConnect ? (_jsxs(Button, { variant: "primary", "data-test": "mcp-connect", type: "button", onClick: () => void onConnect(), children: [_jsx(IconPlugConnected, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), "Connect"] })) : null, _jsxs(Button, { variant: "quiet", "data-test": "mcp-check-again", type: "button", disabled: checking || snapshot.state === "disabled" || snapshot.state === "pairing", onClick: () => void handleCheckAgain(), children: [_jsx(IconRefresh, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), checking ? "Checking…" : "Check again"] }), canDisconnect ? (_jsxs(Button, { variant: "danger", "data-test": "mcp-disconnect", type: "button", onClick: onDisconnect, children: [_jsx(IconUnlink, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), snapshot.paired ? "Disconnect" : "Forget connection"] })) : null] })] }), _jsxs(TimelineStep, { number: 3, complete: snapshot.listenerActive, title: "Start the agent listener", children: [_jsxs("p", { className: "mcp-connection__copy", children: ["Ask your coding agent to call ", _jsx("code", { children: "nudge_listen" }), " and keep it active."] }), _jsx("div", { className: "mcp-connection__command-actions", children: _jsxs(Button, { variant: "secondary", "data-test": "mcp-copy-listener", type: "button", onClick: () => void handleCopyListener(), children: [copiedListener ? _jsx(IconCheck, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) : _jsx(IconClipboard, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), copiedListener ? "Copied" : "Copy listener instruction"] }) })] })] }), copyError ? _jsx("p", { className: "mcp-connection__error", role: "alert", children: copyError }) : null, _jsxs("a", { className: "mcp-connection__docs", "data-test": "mcp-docs-link", href: MCP_DOCS_URL, target: "_blank", rel: "noreferrer", children: [_jsx(IconExternalLink, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), "Read the MCP connection guide"] })] }));
+                                ], onChange: setSetupMethod }), setupMethod === "terminal" ? (_jsxs(_Fragment, { children: [_jsx("p", { className: "mcp-connection__copy", children: "Run this command from the application directory, then start your app normally." }), _jsx("pre", { className: "mcp-connection__command", children: _jsx("code", { "data-test": "mcp-setup-command", children: setupCommand }) }), _jsx("div", { className: "mcp-connection__command-actions", children: _jsxs(Button, { variant: "secondary", "data-test": "mcp-copy-command", type: "button", onClick: () => void handleCopyCommand(), children: [copiedCommand ? _jsx(IconCheck, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) : _jsx(IconClipboard, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), copiedCommand ? "Copied" : "Copy command"] }) })] })) : (_jsxs(_Fragment, { children: [_jsx("p", { className: "mcp-connection__copy", children: "Copy these setup instructions into your coding agent." }), _jsx("pre", { className: "mcp-connection__command", children: _jsx("code", { "data-test": "mcp-setup-prompt", children: setupPrompt }) }), _jsx("div", { className: "mcp-connection__command-actions", children: _jsxs(Button, { variant: "secondary", "data-test": "mcp-copy-setup-prompt", type: "button", onClick: () => void handleCopyPrompt(), children: [copiedPrompt ? _jsx(IconCheck, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) : _jsx(IconClipboard, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), copiedPrompt ? "Copied" : "Copy prompt"] }) })] }))] }), _jsxs(TimelineStep, { number: 2, complete: snapshot.listenerActive, title: "Listen in this agent session", children: [_jsx("p", { className: "mcp-connection__copy", children: "Tell your coding agent: \u201CListen to Nudge.\u201D Reload the agent if Nudge tools are unavailable." }), _jsx("div", { className: "mcp-connection__command-actions", children: _jsxs(Button, { variant: "secondary", "data-test": "mcp-copy-listener", type: "button", onClick: () => void handleCopyListener(), children: [copiedListener ? _jsx(IconCheck, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) : _jsx(IconClipboard, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), copiedListener ? "Copied" : "Copy listening instruction"] }) })] })] }), _jsxs(Disclosure, { className: "mcp-connection__details", title: "Connection details and recovery", children: [_jsxs("p", { className: "mcp-connection__copy", children: ["The page connects automatically when the development integration is available. To diagnose setup, run ", _jsx("code", { children: "nudge-ui agent doctor" }), " from the application directory."] }), _jsxs("dl", { className: "mcp-connection__diagnostics", "data-test": "mcp-connection-diagnostics", children: [_jsxs("div", { className: "mcp-connection__diagnostic", children: [_jsx("dt", { children: "Project ID" }), _jsx("dd", { "data-test": "mcp-project-id", children: _jsx("code", { children: projectId }) })] }), _jsxs("div", { className: "mcp-connection__diagnostic", children: [_jsx("dt", { children: "Origin" }), _jsx("dd", { "data-test": "mcp-origin", children: _jsx("code", { children: origin }) })] })] }), _jsxs("div", { className: "mcp-connection__actions", children: [canTakeOver ? (_jsxs(Button, { variant: "primary", "data-test": "mcp-takeover", type: "button", onClick: () => void onTakeOver(), children: [_jsx(IconPlugConnected, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), "Take over"] })) : null, canConnect ? (_jsxs(Button, { variant: "primary", "data-test": "mcp-connect", type: "button", onClick: () => void onConnect(), children: [_jsx(IconPlugConnected, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), "Connect"] })) : null, _jsxs(Button, { variant: "quiet", "data-test": "mcp-check-again", type: "button", disabled: checking || snapshot.state === "disabled" || snapshot.state === "pairing", onClick: () => void handleCheckAgain(), children: [_jsx(IconRefresh, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), checking ? "Checking…" : "Check again"] }), canDisconnect ? (_jsxs(Button, { variant: "danger", "data-test": "mcp-disconnect", type: "button", onClick: onDisconnect, children: [_jsx(IconUnlink, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), snapshot.paired ? "Disconnect" : "Forget connection"] })) : null] })] }), copyError ? _jsx("p", { className: "mcp-connection__error", role: "alert", children: copyError }) : null, _jsxs("a", { className: "mcp-connection__docs", "data-test": "mcp-docs-link", href: MCP_DOCS_URL, target: "_blank", rel: "noreferrer", children: [_jsx(IconExternalLink, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), "Read the MCP connection guide"] })] }));
 }
 /**
  * Explains and controls the project-scoped MCP companion connection.
@@ -129,7 +112,7 @@ export function McpConnectionContent({ projectId, origin, snapshot, onConnect, o
  * This compatibility wrapper keeps the existing standalone MCP surface while
  * the shared content is also embedded in the general settings modal.
  */
-export function McpConnectionDialog({ open, projectId, origin, snapshot, onOpenChange, onConnect, onDisconnect, onCheckAgain, }) {
+export function McpConnectionDialog({ open, projectId, origin, snapshot, onOpenChange, onConnect, onTakeOver, onDisconnect, onCheckAgain, }) {
     const closeRef = useRef(null);
-    return (_jsx(Dialog.Root, { open: open, onOpenChange: onOpenChange, children: _jsxs(Dialog.Portal, { container: portalContainer(), children: [_jsx(Dialog.Backdrop, { className: "mcp-connection__backdrop", "data-test": "mcp-connection-backdrop" }), _jsxs(Dialog.Popup, { className: "mcp-connection__popup", "data-test": "mcp-connection-dialog", initialFocus: closeRef, children: [_jsxs("div", { className: "mcp-connection__header", children: [_jsxs("div", { children: [_jsx(Dialog.Title, { className: "mcp-connection__title", children: "Connect MCP" }), _jsx(Dialog.Description, { className: "mcp-connection__description", children: "Pair this page with your coding agent. You can connect before the agent starts listening." })] }), _jsx(Dialog.Close, { ref: closeRef, className: "icon-button icon-button--quiet mcp-connection__close", "aria-label": "Close MCP connection", "data-test": "mcp-connection-close", type: "button", children: _jsx(IconX, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) })] }), _jsx(McpConnectionContent, { projectId: projectId, origin: origin, snapshot: snapshot, onConnect: onConnect, onDisconnect: onDisconnect, onCheckAgain: onCheckAgain })] })] }) }));
+    return (_jsx(Dialog.Root, { open: open, onOpenChange: onOpenChange, children: _jsxs(Dialog.Portal, { container: portalContainer(), children: [_jsx(Dialog.Backdrop, { className: "mcp-connection__backdrop", "data-test": "mcp-connection-backdrop" }), _jsxs(Dialog.Popup, { className: "mcp-connection__popup", "data-test": "mcp-connection-dialog", initialFocus: closeRef, children: [_jsxs("div", { className: "mcp-connection__header", children: [_jsxs("div", { children: [_jsx(Dialog.Title, { className: "mcp-connection__title", children: "Connect MCP" }), _jsx(Dialog.Description, { className: "mcp-connection__description", children: "Set up your coding agent once, then ask it to listen to Nudge in this worktree." })] }), _jsx(Dialog.Close, { ref: closeRef, className: "icon-button icon-button--quiet mcp-connection__close", "aria-label": "Close MCP connection", "data-test": "mcp-connection-close", type: "button", children: _jsx(IconX, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) })] }), _jsx(McpConnectionContent, { projectId: projectId, origin: origin, snapshot: snapshot, onConnect: onConnect, onTakeOver: onTakeOver, onDisconnect: onDisconnect, onCheckAgain: onCheckAgain })] })] }) }));
 }

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

@@ -1,8 +1,10 @@
-import { type AgentBridgeTransport, type AgentClientOptions, type AgentRequestStatus, type AgentStatusSnapshot, type PromptDispatchResponse } from "./protocol.js";
+import { type AgentBridgeTransport, type AgentClientOptions, type AgentSketchAttachment, type AgentSketchMetadata, type AgentRequestStatus, type AgentStatusSnapshot, type PromptDispatchResponse } from "./protocol.js";
 export type AgentClientState = "disabled" | "disconnected" | "available" | "pairing" | "connected" | "working" | "completed" | "failed" | "interrupted";
 export interface AgentRequestSnapshot {
     readonly requestId: string;
     readonly changeRevision?: number;
+    readonly clientDispatchId?: string;
+    readonly sketches?: readonly AgentSketchMetadata[];
     readonly status: AgentRequestStatus;
     readonly summary?: string;
     readonly error?: string;
@@ -16,11 +18,13 @@ export interface AgentClientSnapshot {
     /** Whether the last valid discovery response came from the local companion. */
     readonly companionReachable: boolean;
     readonly paired: boolean;
+    /** Whether another browser currently owns this project's pairing. */
+    readonly pairedElsewhere: boolean;
     readonly request: AgentRequestSnapshot | null;
     readonly error?: string;
 }
 /** Creates a stable numeric revision for one prompt snapshot. */
-export declare function createPromptRevision(changes: readonly unknown[], structuralChanges?: readonly unknown[]): number;
+export declare function createPromptRevision(changes: readonly unknown[], structuralChanges?: readonly unknown[], sketches?: readonly unknown[]): number;
 /**
  * Browser-side companion client.
  *
@@ -49,7 +53,10 @@ export declare class AgentClient {
     private listenerActive;
     private companionReachable;
     private paired;
+    private pairedElsewhere;
     private lastError;
+    private readonly autoConnect;
+    private autoConnectSuppressed;
     constructor(options: AgentClientOptions);
     /** Installs the controller callback used to acknowledge Canvas commands. */
     setCanvasCommandHandler(handler: AgentClientOptions["canvasCommandHandler"]): void;
@@ -66,13 +73,19 @@ export declare class AgentClient {
     reconnect(): void;
     /** Pairs the browser with a reachable companion, including an idle agent. */
     connect(): Promise<boolean>;
+    /** Replaces an existing browser pairing after an explicit user action. */
+    takeOver(): Promise<boolean>;
+    private pairWith;
     private openEvents;
     /**
      * Dispatches one immutable prompt revision. The request enters `working`
      * synchronously, before the transport promise resolves, so the UI cannot
      * issue a second prompt while the first one is in flight.
      */
-    dispatchPrompt(prompt: string, changeRevision?: number): Promise<PromptDispatchResponse | null>;
+    dispatchPrompt(prompt: string, changeRevision?: number, options?: {
+        readonly clientDispatchId?: string;
+        readonly attachments?: readonly AgentSketchAttachment[];
+    }): Promise<PromptDispatchResponse | null>;
     /** Interrupts local request state and asks the companion to revoke pairing. */
     disconnect(reason?: string): void;
     private discover;