nudge-ui 0.2.0 → 0.2.1

package/dist/hosts/vite/vite.js

@@ -2,11 +2,12 @@ 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";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -106,6 +107,8 @@ export function createVitePlugins(options = {}, createFramework = null) {
     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 +476,41 @@ 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 } : {}),
         };
     }
+    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 } : {}),
+            warn: (message) => server.config.logger.warn(message),
+        }).then((bridge) => {
+            projectBridge = bridge;
+        });
+    }
     function buildRuntimeSnapshot() {
         syncInventoryContributions();
         const snapshot = inventory.snapshot();
@@ -497,6 +527,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 +569,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 +683,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 +725,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,8 +1,8 @@
 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;

package/dist/inspector/agent/McpConnectionDialog.js

@@ -8,32 +8,9 @@ import { Button } from "../ui/Button.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"
@@ -52,17 +29,16 @@ 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
@@ -118,10 +94,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("details", { className: "mcp-connection__details", children: [_jsx("summary", { children: "Connection details and recovery" }), _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: [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.
@@ -131,5 +107,5 @@ export function McpConnectionContent({ projectId, origin, snapshot, onConnect, o
  */
 export function McpConnectionDialog({ open, projectId, origin, snapshot, onOpenChange, onConnect, 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, 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;
@@ -20,7 +22,7 @@ export interface AgentClientSnapshot {
     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.
  *
@@ -50,6 +52,8 @@ export declare class AgentClient {
     private companionReachable;
     private paired;
     private lastError;
+    private readonly autoConnect;
+    private autoConnectSuppressed;
     constructor(options: AgentClientOptions);
     /** Installs the controller callback used to acknowledge Canvas commands. */
     setCanvasCommandHandler(handler: AgentClientOptions["canvasCommandHandler"]): void;
@@ -72,7 +76,10 @@ export declare class AgentClient {
      * 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;

package/dist/inspector/agent/client.js

@@ -1,7 +1,7 @@
 import { useEffect, useMemo, useSyncExternalStore } from "react";
 import { isNudgeUiDev } from "../runtime/devFlag.js";
 import { isDemoRuntime } from "../runtime/runtimeConfig.js";
-import { HttpAgentBridgeTransport } from "./httpTransport.js";
+import { HttpAgentBridgeTransport, shouldAutoConnectAgentBridge } from "./httpTransport.js";
 import { AGENT_PROTOCOL_VERSION, } from "./protocol.js";
 const DISABLED_SNAPSHOT = Object.freeze({
     state: "disabled",
@@ -13,6 +13,7 @@ const DISABLED_SNAPSHOT = Object.freeze({
 });
 const DEFAULT_DISCOVERY_INTERVAL_MS = 2_000;
 const SESSION_STORAGE_PREFIX = "nudge-ui-agent-session:";
+const AUTO_CONNECT_DISABLED_PREFIX = "nudge-ui-agent-auto-connect-disabled:";
 function randomId(prefix) {
     const random = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
         ? crypto.randomUUID()
@@ -68,6 +69,31 @@ function clearStoredSession(projectId) {
         // Ignore storage failures; disconnect still clears the live connection.
     }
 }
+function autoConnectDisabled(projectId) {
+    if (typeof localStorage === "undefined")
+        return false;
+    try {
+        return localStorage.getItem(`${AUTO_CONNECT_DISABLED_PREFIX}${encodeURIComponent(projectId)}`) === "true";
+    }
+    catch {
+        return false;
+    }
+}
+function setAutoConnectDisabled(projectId, disabled) {
+    if (typeof localStorage === "undefined")
+        return;
+    try {
+        const key = `${AUTO_CONNECT_DISABLED_PREFIX}${encodeURIComponent(projectId)}`;
+        if (disabled)
+            localStorage.setItem(key, "true");
+        else
+            localStorage.removeItem(key);
+    }
+    catch {
+        // Privacy settings can disable storage. The current document still keeps
+        // the explicit disconnect preference in memory.
+    }
+}
 function statusForConnection(status) {
     if (status.connection === "working" || status.request?.status === "working")
         return "working";
@@ -90,10 +116,10 @@ function hashRevision(value) {
     return (hash >>> 0) & 0x7fff_ffff;
 }
 /** Creates a stable numeric revision for one prompt snapshot. */
-export function createPromptRevision(changes, structuralChanges = []) {
+export function createPromptRevision(changes, structuralChanges = [], sketches = []) {
     let serialized;
     try {
-        serialized = JSON.stringify({ changes, structuralChanges }) ?? "";
+        serialized = JSON.stringify({ changes, structuralChanges, sketches }) ?? "";
     }
     catch {
         serialized = `${changes.length}:${structuralChanges.length}`;
@@ -129,12 +155,16 @@ export class AgentClient {
     companionReachable = false;
     paired = false;
     lastError;
+    autoConnect;
+    autoConnectSuppressed = false;
     constructor(options) {
         this.projectId = options.projectId;
         this.origin = options.origin ?? (typeof window !== "undefined" ? window.location.origin : "http://localhost");
         this.transport = options.transport ?? new HttpAgentBridgeTransport(options.endpoint);
         this.discoveryIntervalMs = options.discoveryIntervalMs ?? DEFAULT_DISCOVERY_INTERVAL_MS;
         this.canvasCommandHandler = options.canvasCommandHandler;
+        this.autoConnect = options.autoConnect ?? shouldAutoConnectAgentBridge();
+        this.autoConnectSuppressed = this.autoConnect && autoConnectDisabled(this.projectId);
         // The public demo renders the real inspector but intentionally keeps the
         // local MCP/agent bridge inert.
         this.enabled = isNudgeUiDev() && !isDemoRuntime();
@@ -269,6 +299,8 @@ export class AgentClient {
     async connect() {
         if (!this.enabled || !this.started || this.pairingAbort || this.paired || !this.companionReachable)
             return false;
+        this.autoConnectSuppressed = false;
+        setAutoConnectDisabled(this.projectId, false);
         if (this.connection === "working" || this.activeRequest?.status === "working")
             return false;
         const idleListenerActive = this.listenerActive;
@@ -351,7 +383,7 @@ export class AgentClient {
      * synchronously, before the transport promise resolves, so the UI cannot
      * issue a second prompt while the first one is in flight.
      */
-    async dispatchPrompt(prompt, changeRevision) {
+    async dispatchPrompt(prompt, changeRevision, options = {}) {
         if (!this.enabled || !this.started || !this.paired || !this.listenerActive || !this.sessionToken)
             return null;
         if (!prompt || this.activeRequest?.status === "working")
@@ -362,12 +394,17 @@ export class AgentClient {
             sessionToken: this.sessionToken,
             prompt,
             ...(changeRevision === undefined ? {} : { changeRevision }),
+            ...(options.clientDispatchId === undefined ? {} : { clientDispatchId: options.clientDispatchId }),
+            ...(options.attachments === undefined ? {} : { attachments: options.attachments }),
         };
+        const sketches = options.attachments?.map(({ data: _data, ...metadata }) => metadata);
         this.activeRequest = {
             localRequestId,
             requestId: localRequestId,
             prompt,
             ...(changeRevision === undefined ? {} : { changeRevision }),
+            ...(options.clientDispatchId === undefined ? {} : { clientDispatchId: options.clientDispatchId }),
+            ...(sketches === undefined ? {} : { sketches }),
             status: "working",
         };
         this.connection = "working";
@@ -381,7 +418,12 @@ export class AgentClient {
                 return null;
             if (response?.request?.requestId) {
                 this.activeRequest = this.activeRequest && this.activeRequest.localRequestId === localRequestId
-                    ? { ...this.activeRequest, requestId: response.request.requestId }
+                    ? {
+                        ...this.activeRequest,
+                        requestId: response.request.requestId,
+                        ...(response.request.clientDispatchId === undefined ? {} : { clientDispatchId: response.request.clientDispatchId }),
+                        ...(response.request.sketches === undefined ? {} : { sketches: response.request.sketches }),
+                    }
                     : this.activeRequest;
             }
             if (response?.status && response.status !== "working") {
@@ -405,6 +447,9 @@ export class AgentClient {
     }
     /** Interrupts local request state and asks the companion to revoke pairing. */
     disconnect(reason = "browser_disconnected") {
+        this.autoConnectSuppressed = true;
+        if (this.autoConnect)
+            setAutoConnectDisabled(this.projectId, true);
         const token = this.sessionToken;
         const active = this.activeRequest;
         if (active?.status === "working") {
@@ -454,7 +499,21 @@ export class AgentClient {
                 else {
                     this.companionReachable = true;
                     if (this.connection !== "paired" && this.connection !== "working" && !this.pairingAbort) {
-                        this.applyStatus(status);
+                        // Discovery is unauthenticated. Another browser tab can own the
+                        // pairing, so do not adopt `paired` until this tab restores the
+                        // shared token. The next poll runs restore first in case a sibling
+                        // tab has just stored that token.
+                        this.applyStatus(status.paired ? {
+                            ...status,
+                            connection: status.listenerActive ? "listening" : "offline",
+                            paired: false,
+                            request: null,
+                        } : status);
+                        if (this.autoConnect
+                            && !status.paired
+                            && !this.autoConnectSuppressed
+                            && !autoConnectDisabled(this.projectId))
+                            void this.connect();
                     }
                 }
             }
@@ -491,7 +550,7 @@ export class AgentClient {
             return;
         this.discoveryTimer = setTimeout(() => {
             this.discoveryTimer = null;
-            void this.discover();
+            void this.restoreOrDiscover();
         }, this.discoveryIntervalMs);
     }
     scheduleReconnect() {
@@ -538,6 +597,12 @@ export class AgentClient {
                 },
             };
         }
+        // Every tab with the shared browser session receives the SSE command, but
+        // only the Canvas lease owner may answer it. A read-only tab reports this
+        // local sentinel; leave the command pending for the owning tab instead of
+        // racing its acknowledgement with a false failure.
+        if (!acknowledgement.ok && acknowledgement.error?.code === "workspace-locked")
+            return;
         if (acknowledgement.commandId !== command.commandId) {
             acknowledgement = {
                 commandId: command.commandId,
@@ -570,7 +635,7 @@ export class AgentClient {
             this.discoveryTimer = null;
         }
         if (status.request) {
-            this.applyRequestStatus(status.request.status, status.request.requestId, status.request.summary, status.request.error, status.request.changeRevision);
+            this.applyRequestStatus(status.request.status, status.request.requestId, status.request.summary, status.request.error, status.request.changeRevision, status.request.clientDispatchId, status.request.sketches);
         }
         else if (status.listenerActive && status.paired && this.activeRequest?.status !== "working") {
             // A re-armed MCP listen call is the lifecycle boundary for the previous
@@ -598,7 +663,7 @@ export class AgentClient {
         this.paired = false;
         this.publish();
     }
-    applyRequestStatus(status, requestId, summary, error, changeRevision) {
+    applyRequestStatus(status, requestId, summary, error, changeRevision, clientDispatchId, sketches) {
         const active = this.activeRequest;
         if (active && active.requestId !== requestId && active.localRequestId !== requestId) {
             // A fresh server id can arrive before the POST response. Associate it
@@ -613,6 +678,8 @@ export class AgentClient {
                 requestId,
                 prompt: "",
                 ...(changeRevision === undefined ? {} : { changeRevision }),
+                ...(clientDispatchId === undefined ? {} : { clientDispatchId }),
+                ...(sketches === undefined ? {} : { sketches }),
                 status,
                 ...(summary === undefined ? {} : { summary }),
                 ...(error === undefined ? {} : { error }),
@@ -624,6 +691,8 @@ export class AgentClient {
                 requestId,
                 status,
                 ...(changeRevision === undefined ? {} : { changeRevision }),
+                ...(clientDispatchId === undefined ? {} : { clientDispatchId }),
+                ...(sketches === undefined ? {} : { sketches }),
                 ...(summary === undefined ? {} : { summary }),
                 ...(error === undefined ? {} : { error }),
             };
@@ -659,6 +728,8 @@ export class AgentClient {
             request: request ? {
                 requestId: request.requestId,
                 ...(request.changeRevision === undefined ? {} : { changeRevision: request.changeRevision }),
+                ...(request.clientDispatchId === undefined ? {} : { clientDispatchId: request.clientDispatchId }),
+                ...(request.sketches === undefined ? {} : { sketches: request.sketches }),
                 status: request.status,
                 ...(request.summary === undefined ? {} : { summary: request.summary }),
                 ...(request.error === undefined ? {} : { error: request.error }),

package/dist/inspector/agent/connectionStatus.js

@@ -15,20 +15,20 @@ export function getAgentConnectionStatus(snapshot) {
     if (snapshot.paired && !snapshot.listenerActive) {
         return {
             kind: "connected-not-listening",
-            label: "Connected, not listening",
+            label: "Project connected · Ask agent to listen",
             tone: "accent",
             action: { kind: "setup", label: "Set up" },
         };
     }
     if (!snapshot.companionReachable) {
-        return { kind: "not-found", label: "Companion not found", tone: "neutral" };
+        return { kind: "not-found", label: "Project bridge unavailable", tone: "neutral" };
     }
     if (snapshot.listenerActive) {
         return { kind: "listening", label: "Agent listening", tone: "accent" };
     }
     return {
         kind: "ready-to-connect",
-        label: "Ready to connect agent",
+        label: "Project available · Connect this page",
         tone: "accent",
         action: { kind: "connect", label: "Connect" },
     };

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

@@ -1,4 +1,6 @@
 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;
 /**
  * HTTP/SSE browser adapter for the companion's canonical endpoints.
  *