nudge-ui 0.2.2 → 0.2.3

package/dist/css/value-semantics/colorSemantics.d.ts

@@ -78,6 +78,10 @@ export declare function interpretColorValue(value: string, ctx: ColorSemanticsCo
  * unparseable opacities return an explicit `ok: false`.
  */
 export declare function applyColorOpacity(value: string, opacity: string): ColorEditResult;
+/** Applies opacity using RGB channels for hex colors so field edits retain percentage precision. */
+export declare function withColorOpacity(color: string, opacity: string): ColorEditResult;
+/** Preserves the previous opacity when the replacement color has no explicit alpha. */
+export declare function replaceColorPreservingOpacity(previous: string, color: string, context: ColorSemanticsContext): ColorEditResult;
 /**
  * Replaces only the color token in a separable color expression. Keeping this
  * separate from a plain token swap preserves authored alpha modifiers, for

package/dist/css/value-semantics/colorSemantics.js

@@ -398,6 +398,23 @@ export function applyColorOpacity(value, opacity) {
     }
     return { ok: false, reason: "unsupported" };
 }
+/** Applies opacity using RGB channels for hex colors so field edits retain percentage precision. */
+export function withColorOpacity(color, opacity) {
+    const hex = /^#([\da-f]{3}|[\da-f]{4}|[\da-f]{6}|[\da-f]{8})$/i.exec(color.trim());
+    if (hex) {
+        const raw = hex[1];
+        const channels = rgbTuple(`#${raw.slice(0, raw.length <= 4 ? 3 : 6)}`);
+        color = `rgb(${channels.join(" ")} / 100%)`;
+    }
+    return applyColorOpacity(color, opacity);
+}
+/** Preserves the previous opacity when the replacement color has no explicit alpha. */
+export function replaceColorPreservingOpacity(previous, color, context) {
+    const opacity = interpretColorOpacity(previous, context);
+    return opacity && !colorValueHasEmbeddedAlpha(color)
+        ? withColorOpacity(color, opacity.value)
+        : { ok: true, value: color };
+}
 function tokenReferenceName(entry) {
     const name = entry.cssName ?? entry.name;
     return name.startsWith("--") ? name : null;

package/dist/hosts/astro/astroRuntimeConfig.js

@@ -14,6 +14,7 @@ export function createAstroRuntimeConfig(knowledge) {
         capabilities: {
             canvas: true,
             componentSemantics: true,
+            domNavigation: true,
             sourceCoordinates: ASTRO_SOURCE_COORDINATES,
             scopingSelectorPattern: ASTRO_SCOPING_SELECTOR_PATTERN,
         },

package/dist/hosts/astro/clientTransport.js

@@ -1,3 +1,4 @@
+import { handleHtmlArtifactRequest } from "../../project/artifacts.js";
 import {} from "../../inspector/clientManifest.js";
 import { createAstroRuntimeConfig } from "./astroRuntimeConfig.js";
 import { createAstroClientAssetHandler } from "./clientAsset.js";
@@ -17,38 +18,9 @@ export function createAstroClientTransportPlugin() {
         apply: "serve",
         configureServer(server) {
             server.middlewares.use((request, response, next) => {
-                const pathname = new URL(request.url ?? "/", "http://nudge-ui.local").pathname;
-                if (isNudgeUiEditorDocumentRequest(request.url ?? "/", request.method, request.headers)) {
-                    if (request.method !== "GET" && request.method !== "HEAD") {
-                        response.statusCode = 405;
-                        response.setHeader("Allow", "GET, HEAD");
-                        response.end();
-                        return;
-                    }
-                    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 === NUDGE_UI_CLIENT_PATH) {
-                    void serveClient(request, response).catch(next);
-                    return;
-                }
-                if (pathname === NUDGE_UI_MANIFEST_PATH) {
-                    void createManifest(server, request, (bridge) => {
-                        projectBridge = bridge;
-                    })
-                        .then((manifest) => {
-                        response.statusCode = 200;
-                        response.setHeader("Content-Type", "application/json; charset=utf-8");
-                        response.setHeader("Cache-Control", "no-store");
-                        response.end(JSON.stringify(manifest));
-                    })
-                        .catch(next);
-                    return;
-                }
-                next();
+                void handleHtmlArtifactRequest(request, response, server.config.root)
+                    .then((handled) => { if (!handled)
+                    handleClientRequest(server, request, response, next); }).catch(next);
             });
         },
         async closeBundle() {
@@ -56,6 +28,40 @@ export function createAstroClientTransportPlugin() {
             projectBridge = null;
         },
     };
+    function handleClientRequest(server, request, response, next) {
+        const pathname = new URL(request.url ?? "/", "http://nudge-ui.local").pathname;
+        if (isNudgeUiEditorDocumentRequest(request.url ?? "/", request.method, request.headers)) {
+            if (request.method !== "GET" && request.method !== "HEAD") {
+                response.statusCode = 405;
+                response.setHeader("Allow", "GET, HEAD");
+                response.end();
+                return;
+            }
+            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 === NUDGE_UI_CLIENT_PATH) {
+            void serveClient(request, response).catch(next);
+            return;
+        }
+        if (pathname === NUDGE_UI_MANIFEST_PATH) {
+            void createManifest(server, request, (bridge) => {
+                projectBridge = bridge;
+            })
+                .then((manifest) => {
+                response.statusCode = 200;
+                response.setHeader("Content-Type", "application/json; charset=utf-8");
+                response.setHeader("Cache-Control", "no-store");
+                response.end(JSON.stringify(manifest));
+            })
+                .catch(next);
+            return;
+        }
+        next();
+    }
 }
 async function createManifest(server, request, setBridge) {
     // SAFETY: these virtual modules are generated by the shared Nudge UI plugin

package/dist/hosts/astro/integration.js

@@ -1,8 +1,10 @@
+import { fileURLToPath } from "node:url";
 import { nudgeUi } from "../vite/index.js";
 import { NUDGE_UI_CLIENT_PATH, NUDGE_UI_MANIFEST_PATH } from "../../transport/index.js";
 import { createAstroClientTransportPlugin, } from "./clientTransport.js";
 import { createProjectContextPlugin } from "./projectContext.js";
 import { isNudgeUiEnabled } from "../environment.js";
+import { installMarkdownIdentity } from "./markdownIdentity.js";
 /**
  * Adds the prebuilt client as an external module. The inspector dependency
  * graph therefore never enters Astro's Vite optimizer.
@@ -43,14 +45,16 @@ export function nudgeUiAstro(options = {}) {
     return {
         name: "nudge-ui",
         hooks: {
-            "astro:config:setup"({ command, updateConfig, injectScript, addMiddleware }) {
+            "astro:config:setup"({ command, config, updateConfig, injectScript, addMiddleware }) {
                 if (!enabled || command !== "dev")
                     return;
+                const markdown = installMarkdownIdentity(config.markdown, fileURLToPath(config.root));
                 // The shared plugin objects are plain Vite plugin records, but this
                 // monorepo typechecks them against a different Vite major than the
                 // installed Astro resolves internally; the runtime contract
                 // (config/resolveId/load/transform hooks) is identical.
                 updateConfig({
+                    ...(markdown ? { markdown } : {}),
                     vite: {
                         // SAFETY: Astro and this package resolve different Vite type
                         // versions, but both consume the same runtime Plugin contract.

package/dist/hosts/astro/markdownIdentity.d.ts

@@ -0,0 +1,28 @@
+import type { Element, Root } from "hast";
+/** Adds authored Markdown positions through the remark/rehype pipeline. */
+export declare function createMarkdownIdentityPlugin(projectRoot: string): () => (tree: Root, file: {
+    path?: string;
+}) => void;
+/** Adds the same identity through Astro's Sätteri visitor API. */
+export declare function createSatteriIdentityPlugin(projectRoot: string): {
+    name: string;
+    options: {
+        position: boolean;
+    };
+    element: {
+        filter: string[];
+        visit(node: Readonly<Element>, context: {
+            fileURL: URL | undefined;
+            setProperty(node: Readonly<Element>, key: string, value: string): void;
+        }): void;
+    };
+};
+/** Extends supported processors without replacing the consumer's pipeline. */
+export declare function installMarkdownIdentity(markdown: {
+    processor?: {
+        name: string;
+        options: object;
+    };
+}, projectRoot: string): {
+    rehypePlugins: ReturnType<typeof createMarkdownIdentityPlugin>[];
+} | undefined;

package/dist/hosts/astro/markdownIdentity.js

@@ -0,0 +1,81 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const PROSE_TAGS = [
+    "p", "h1", "h2", "h3", "h4", "h5", "h6", "ul", "ol", "li",
+    "blockquote", "a", "em", "strong", "del", "code", "pre", "hr", "br",
+    "table", "thead", "tbody", "tr", "th", "td",
+];
+const proseTags = new Set(PROSE_TAGS);
+function attributesFor(node, file, projectRoot) {
+    const start = node.position?.start;
+    if (!start || start.line < 1 || start.column < 1 || !proseTags.has(node.tagName))
+        return {};
+    const relative = path.relative(projectRoot, file).replaceAll("\\", "/");
+    const attributes = {};
+    const properties = node.properties;
+    if (properties["data-cid"] === undefined && properties.dataCid === undefined) {
+        attributes["data-cid"] = `astro:${node.tagName.charAt(0).toUpperCase()}${node.tagName.slice(1)}`;
+    }
+    if (properties["data-src"] === undefined && properties.dataSrc === undefined) {
+        attributes["data-src"] = `${relative}:${start.line}:${start.column}`;
+    }
+    return attributes;
+}
+/** Adds authored Markdown positions through the remark/rehype pipeline. */
+export function createMarkdownIdentityPlugin(projectRoot) {
+    return function nudgeMarkdownIdentity() {
+        return (tree, file) => {
+            if (!file.path || !/\.mdx?$/.test(file.path))
+                return;
+            const sourceFile = file.path;
+            const visit = (node) => {
+                if (node.type === "element") {
+                    Object.assign(node.properties, attributesFor(node, sourceFile, projectRoot));
+                }
+                if ("children" in node) {
+                    for (const child of node.children)
+                        visit(child);
+                }
+            };
+            visit(tree);
+        };
+    };
+}
+/** Adds the same identity through Astro's Sätteri visitor API. */
+export function createSatteriIdentityPlugin(projectRoot) {
+    return {
+        name: "nudge-ui-markdown-identity",
+        options: { position: true },
+        element: {
+            filter: PROSE_TAGS,
+            visit(node, context) {
+                if (!context.fileURL || context.fileURL.protocol !== "file:")
+                    return;
+                const file = fileURLToPath(context.fileURL);
+                if (!/\.mdx?$/.test(file))
+                    return;
+                for (const [key, value] of Object.entries(attributesFor(node, file, projectRoot))) {
+                    context.setProperty(node, key, value);
+                }
+            },
+        },
+    };
+}
+/** Extends supported processors without replacing the consumer's pipeline. */
+export function installMarkdownIdentity(markdown, projectRoot) {
+    const processor = markdown.processor;
+    if (!processor)
+        return { rehypePlugins: [createMarkdownIdentityPlugin(projectRoot)] };
+    if (processor.name !== "unified" && processor.name !== "satteri")
+        return undefined;
+    // SAFETY: Astro's supported processors expose mutable plugin arrays. This
+    // adapter only appends plugins and does not inspect existing entries.
+    const options = processor.options;
+    if (processor.name === "unified") {
+        (options.rehypePlugins ??= []).push(createMarkdownIdentityPlugin(projectRoot));
+    }
+    else if (processor.name === "satteri") {
+        (options.hastPlugins ??= []).push(createSatteriIdentityPlugin(projectRoot));
+    }
+    return undefined;
+}

package/dist/hosts/next/manifest.js

@@ -15,7 +15,7 @@ export function buildManifest(input) {
             stylingSystem: "CSS custom properties",
             // Canvas shares the Vite host's controller/renderer runtime (ADR-0006);
             // the mount in every document bootstraps as a renderer inside cards.
-            capabilities: { canvas: true, componentSemantics: true },
+            capabilities: { canvas: true, componentSemantics: true, domNavigation: true },
             tokenCatalog: [],
             tokens: [],
             tokenDiagnostics: [],

package/dist/hosts/next/sidecar.js

@@ -1,3 +1,4 @@
+import { handleHtmlArtifactRequest } from "../../project/artifacts.js";
 import { createServer } from "node:http";
 import { createRequire } from "node:module";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
@@ -299,7 +300,10 @@ export async function ensureSidecar(root, options = {}) {
                 contractsTimer = setTimeout(flushContracts, 120);
         };
         const server = createServer((req, res) => {
-            respond(req, res, () => manifest, () => generation, streams, receiveContracts);
+            void handleHtmlArtifactRequest(req, res, fsRoot).then((handled) => {
+                if (!handled)
+                    respond(req, res, () => manifest, () => generation, streams, receiveContracts);
+            });
         });
         const port = await new Promise((resolvePort, rejectPort) => {
             server.once("error", rejectPort);

package/dist/hosts/static/manifest.js

@@ -24,7 +24,7 @@ export function createStandaloneRuntimeManifest(projectId, tokenSnapshot = empty
             // Canvas shares the Vite host's controller/renderer runtime (ADR-0012):
             // every served document carries the bootstrap, so card iframes boot as
             // renderers without host-specific code.
-            capabilities: { canvas: true, componentSemantics: false },
+            capabilities: { canvas: true, componentSemantics: false, domNavigation: true },
             tokenCatalog: tokenSnapshot.tokenCatalog,
             tokens: tokenSnapshot.tokens,
             tokenDiagnostics: tokenSnapshot.tokenDiagnostics,

package/dist/hosts/static/server.js

@@ -1,3 +1,4 @@
+import { handleHtmlArtifactRequest } from "../../project/artifacts.js";
 import { createHash } from "node:crypto";
 import { createServer, } from "node:http";
 import { constants, existsSync, realpathSync, statSync, } from "node:fs";
@@ -383,6 +384,8 @@ function isWithin(root, candidate) {
 }
 async function handleRequest(input) {
     const { request, response } = input;
+    if (await handleHtmlArtifactRequest(request, response, input.rootDirectory))
+        return;
     if (request.method !== "GET" && request.method !== "HEAD") {
         sendText(response, 405, "Method Not Allowed", { Allow: "GET, HEAD" });
         return;

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

@@ -1,5 +1,6 @@
 import type { Plugin } from "vite";
 import type { TailwindV3Config, ThemeContract } from "../../css/dialects/index.js";
+import { type NudgeUiRuntimeConfig } from "../../inspector/clientManifest.js";
 import type { FrameworkHost, FrameworkSupport, ReactOptions } from "./react.js";
 /**
  * How to find the project's vanilla-extract theme contract. Loading a module
@@ -28,6 +29,8 @@ export interface NudgeUiOptions extends ReactOptions {
     demoPages?: readonly string[];
     /** Labels for the seeded demo cards in display order, including the primary card. */
     demoCardLabels?: readonly string[];
+    /** Product features exposed by the inspector runtime. Omitted flags remain enabled. */
+    features?: NudgeUiRuntimeConfig["features"];
     /** 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

@@ -1,3 +1,4 @@
+import { handleHtmlArtifactRequest } from "../../project/artifacts.js";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { basename, join, relative, resolve, sep, } from "node:path";
@@ -81,6 +82,8 @@ function scanCssFiles(rootDir, files = [], dir = rootDir, ignoredDirectory) {
 export function transformIndexHtmlHtml(html, command, { debug = false, demoBuild = false, demo = false } = {}) {
     if (command === "build" && !demoBuild)
         return null;
+    if (html.includes("data-nudge-ui-client"))
+        return null;
     const script = demo || demoBuild ? LEGACY_INSPECTOR_SCRIPT : INSPECTOR_SCRIPT;
     const inject = `\n${debug ? DEBUG_MOUNT_DIV : MOUNT_DIV}\n${script}\n`;
     if (html.includes("</body>")) {
@@ -533,7 +536,8 @@ export function createVitePlugins(options = {}, createFramework = null) {
             ...(options.demo === true ? { demo: true } : {}),
             ...(options.demoPages === undefined ? {} : { demoPages: options.demoPages }),
             ...(options.demoCardLabels === undefined ? {} : { demoCardLabels: options.demoCardLabels }),
-            capabilities: { canvas: true, componentSemantics: framework !== null },
+            ...(options.features === undefined ? {} : { features: options.features }),
+            capabilities: { canvas: true, componentSemantics: framework !== null, domNavigation: true },
             tokenCatalog: snapshot.definitions.map((definition) => ({
                 ...definition,
                 declarations: definition.declarations.map((declaration) => ({ ...declaration })),
@@ -554,11 +558,24 @@ export function createVitePlugins(options = {}, createFramework = null) {
             if (!enabled || env.command !== "serve")
                 return;
             // Module resolution is a framework concern; without one this host asks nothing of the resolver.
-            return framework?.viteConfig({
+            const frameworkConfig = framework?.viteConfig({
                 projectRoot: userConfig.root ?? process.cwd(),
                 demo: options.demo === true,
                 existingDedupe: userConfig.resolve?.dedupe ?? [],
             });
+            const ignored = userConfig.server?.watch?.ignored;
+            return {
+                ...frameworkConfig,
+                server: {
+                    watch: {
+                        ignored: [
+                            ...(ignored === undefined ? [] : Array.isArray(ignored) ? ignored : [ignored]),
+                            "**/.nudge",
+                            "**/.nudge/**",
+                        ],
+                    },
+                },
+            };
         },
         configResolved(config) {
             root = config.root;
@@ -586,6 +603,8 @@ export function createVitePlugins(options = {}, createFramework = null) {
             if (runtimeWarning)
                 server.config.logger.warn(runtimeWarning);
             server.middlewares?.use(async (request, response, next) => {
+                if (await handleHtmlArtifactRequest(request, response, root ?? process.cwd(), (html) => server.transformIndexHtml(request.url ?? "/", html)))
+                    return;
                 const pathname = new URL(request.url ?? "/", "http://nudge-ui.local").pathname;
                 const invalidReservedMethod = (pathname === CLIENT_PATH || pathname === MANIFEST_PATH)
                     ? request.method !== "GET"
@@ -601,7 +620,7 @@ export function createVitePlugins(options = {}, createFramework = null) {
                     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());
+                    response.end(request.method === "HEAD" ? undefined : await server.transformIndexHtml(request.url ?? NUDGE_UI_EDITOR_PATH, createNudgeUiEditorDocument()));
                     return;
                 }
                 if (pathname === CLIENT_PATH) {
@@ -718,7 +737,8 @@ export function createVitePlugins(options = {}, createFramework = null) {
                         '    demo: true,',
                         `    demoPages: ${JSON.stringify(options.demoPages ?? [])},`,
                         `    demoCardLabels: ${JSON.stringify(options.demoCardLabels ?? [])},`,
-                        `    capabilities: { canvas: true, componentSemantics: ${String(framework !== null)} },`,
+                        `    features: ${JSON.stringify(options.features ?? {})},`,
+                        `    capabilities: { canvas: true, componentSemantics: ${String(framework !== null)}, domNavigation: true },`,
                         '    tokenCatalog,',
                         '    tokens,',
                         '    tokenDiagnostics,',

package/dist/inspector/agent/McpConnectionDialog.js

@@ -1,33 +1,28 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useMemo, useRef, useState } from "react";
 import { Dialog } from "@base-ui/react/dialog";
-import { IconCheck, IconClipboard, IconExternalLink, IconPlugConnected, IconRefresh, IconUnlink, IconX, } from "@tabler/icons-react";
+import { IconCheck, IconCopy, IconPlugConnected, IconRefresh, IconUnlink, IconX, } from "@tabler/icons-react";
 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 { IconButton } from "../ui/IconButton.js";
 import { StatusCallout } from "../ui/StatusCallout.js";
+import { portalContainer } from "../ui/portalContainer.js";
 export const MCP_DOCS_URL = "https://github.com/charlessmart/nudge-ui#connect-a-coding-agent";
 /** 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"
-        ? document.getElementById("nudge-ui-root")?.shadowRoot ?? document.body
-        : null;
-}
 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, onTakeOver, onDisconnect, onCheckAgain, }) {
     const [checking, setChecking] = useState(false);
-    const [setupMethod, setSetupMethod] = useState("ai");
     const [copiedCommand, setCopiedCommand] = useState(false);
     const [copiedPrompt, setCopiedPrompt] = useState(false);
-    const [copiedListener, setCopiedListener] = useState(false);
+    const [copiedDoctor, setCopiedDoctor] = useState(false);
     const [copyError, setCopyError] = useState();
     const [checkError, setCheckError] = useState();
     const setupCommand = createMcpSetupCommand();
@@ -39,8 +34,10 @@ export function McpConnectionContent({ projectId, origin, snapshot, onConnect, o
         "",
         "Start the application normally. Reload the agent if needed, then listen to Nudge.",
     ].join("\n"), [setupCommand]);
-    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 doctorCommand = "nudge-ui agent doctor";
     const status = getAgentConnectionStatus(snapshot);
+    const showConnectionStatus = status.kind !== "not-found"
+        || Boolean(snapshot.error || checkError || snapshot.request?.summary || snapshot.request?.error);
     const canConnect = snapshot.companionReachable
         && !snapshot.paired
         && !snapshot.pairedElsewhere
@@ -90,21 +87,18 @@ export function McpConnectionContent({ projectId, origin, snapshot, onConnect, o
             setCopyError("The AI setup prompt could not be copied. Select it and copy it manually.");
         }
     }
-    async function handleCopyListener() {
+    async function handleCopyDoctor() {
         setCopyError(undefined);
         try {
-            await copyToClipboard(listenerInstruction);
-            setCopiedListener(true);
-            window.setTimeout(() => setCopiedListener(false), 1500);
+            await copyToClipboard(doctorCommand);
+            setCopiedDoctor(true);
+            window.setTimeout(() => setCopiedDoctor(false), 1500);
         }
         catch {
-            setCopyError("The listener instruction could not be copied. Select it and copy it manually.");
+            setCopyError("The diagnostic command 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.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 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"] })] }));
+    return (_jsxs(_Fragment, { children: [showConnectionStatus ? (_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] })) : null, _jsxs("ol", { className: "mcp-connection__timeline", "data-test": "mcp-connection-timeline", children: [_jsxs(TimelineStep, { number: 1, complete: snapshot.companionReachable || snapshot.listenerActive || snapshot.request !== null, title: "Set up agent", children: [_jsx("p", { className: "mcp-connection__copy", children: "Agent prompt" }), _jsxs("div", { className: "mcp-connection__command-block", children: [_jsx(IconButton, { className: "mcp-connection__copy-button", variant: "quiet", size: "compact", label: copiedPrompt ? "Copied" : "Copy setup instructions", "data-test": "mcp-copy-setup-prompt", onClick: () => void handleCopyPrompt(), children: copiedPrompt ? _jsx(IconCheck, { size: 16, "aria-hidden": "true" }) : _jsx(IconCopy, { size: 16, "aria-hidden": "true" }) }), _jsx("pre", { className: "mcp-connection__command", children: _jsx("code", { "data-test": "mcp-setup-prompt", children: setupPrompt }) })] }), _jsx("p", { className: "mcp-connection__copy", children: "Or, terminal command" }), _jsxs("div", { className: "mcp-connection__command-block", children: [_jsx(IconButton, { className: "mcp-connection__copy-button", variant: "quiet", size: "compact", label: copiedCommand ? "Copied" : "Copy command", "data-test": "mcp-copy-command", onClick: () => void handleCopyCommand(), children: copiedCommand ? _jsx(IconCheck, { size: 16, "aria-hidden": "true" }) : _jsx(IconCopy, { size: 16, "aria-hidden": "true" }) }), _jsx("pre", { className: "mcp-connection__command", children: _jsx("code", { "data-test": "mcp-setup-command", children: setupCommand }) })] })] }), _jsx(TimelineStep, { number: 2, complete: snapshot.listenerActive, title: "Tell agent to listen for instructions", children: _jsx("p", { className: "mcp-connection__copy", children: "Tell your coding agent: \u201CListen to Nudge.\u201D" }) })] }), _jsxs(Disclosure, { className: "mcp-connection__details", title: "Troubleshooting", defaultOpen: true, children: [_jsx("p", { className: "mcp-connection__copy", children: "To diagnose setup" }), _jsxs("div", { className: "mcp-connection__command-block", children: [_jsx(IconButton, { className: "mcp-connection__copy-button", variant: "quiet", size: "compact", label: copiedDoctor ? "Copied" : "Copy diagnostic command", "data-test": "mcp-copy-doctor", onClick: () => void handleCopyDoctor(), children: copiedDoctor ? _jsx(IconCheck, { size: 16, "aria-hidden": "true" }) : _jsx(IconCopy, { size: 16, "aria-hidden": "true" }) }), _jsx("pre", { className: "mcp-connection__command", children: _jsx("code", { children: doctorCommand }) })] }), _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: projectId })] }), _jsxs("div", { className: "mcp-connection__diagnostic", children: [_jsx("dt", { children: "Origin" }), _jsx("dd", { "data-test": "mcp-origin", 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…" : "Refresh connection"] }), 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] }));
 }
 /**
  * Explains and controls the project-scoped MCP companion connection.

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

@@ -0,0 +1,18 @@
+import type { DraftTarget } from "../drafts/model.js";
+import type { AgentActivity } from "./protocol.js";
+export interface ActivityFile extends AgentActivity {
+    readonly expiresAt: number;
+}
+export interface AgentActivitySnapshot {
+    readonly requestId: string | null;
+    readonly targets: readonly string[];
+    readonly target?: DraftTarget;
+    readonly files: readonly ActivityFile[];
+}
+/** Pins submitted frames before dispatch. Activity never selects or edits a draft. */
+export declare function beginActivityDispatch(projectId: string, dispatchId: string, targets: readonly string[], target?: DraftTarget): void;
+/** Dispatch and status are the only authority for the layer's lifetime. */
+export declare function synchronizeAgentActivity(projectId: string, requestId: string | undefined, working: boolean, dispatchId?: string): void;
+export declare function reportAgentActivity(projectId: string, activity: AgentActivity): void;
+export declare function getAgentActivity(projectId: string): AgentActivitySnapshot;
+export declare function useAgentActivity(projectId: string): AgentActivitySnapshot;

package/dist/inspector/agent/activity.js

@@ -0,0 +1,70 @@
+import { useSyncExternalStore } from "react";
+const EMPTY = Object.freeze({ requestId: null, targets: [], files: [] });
+const projects = new Map();
+function project(id) {
+    let state = projects.get(id);
+    if (!state) {
+        state = { snapshot: EMPTY, listeners: new Set() };
+        projects.set(id, state);
+    }
+    return state;
+}
+function publish(state, snapshot) {
+    state.snapshot = snapshot;
+    for (const listener of state.listeners)
+        listener();
+}
+/** Pins submitted frames before dispatch. Activity never selects or edits a draft. */
+export function beginActivityDispatch(projectId, dispatchId, targets, target) {
+    project(projectId).dispatch = { id: dispatchId, targets: [...targets], target };
+}
+/** Dispatch and status are the only authority for the layer's lifetime. */
+export function synchronizeAgentActivity(projectId, requestId, working, dispatchId) {
+    const state = project(projectId);
+    if (!working || !requestId) {
+        if (state.timer)
+            clearTimeout(state.timer);
+        state.timer = undefined;
+        state.dispatch = undefined;
+        if (state.snapshot !== EMPTY)
+            publish(state, EMPTY);
+        return;
+    }
+    if (state.snapshot.requestId === requestId)
+        return;
+    if (state.timer)
+        clearTimeout(state.timer);
+    const dispatch = state.dispatch?.id === dispatchId ? state.dispatch : undefined;
+    publish(state, { requestId, targets: dispatch?.targets ?? [], ...(dispatch?.target ? { target: dispatch.target } : {}), files: [] });
+}
+export function reportAgentActivity(projectId, activity) {
+    const state = project(projectId);
+    if (state.snapshot.requestId !== activity.requestId)
+        return;
+    const now = Date.now();
+    const files = state.snapshot.files.filter((file) => file.expiresAt > now && file.file !== activity.file);
+    files.push({ ...activity, expiresAt: now + (activity.operation === "read" ? 8_000 : 12_000) });
+    publish(state, { ...state.snapshot, files: files.slice(-64) });
+    scheduleExpiry(state);
+}
+function scheduleExpiry(state) {
+    if (state.timer)
+        clearTimeout(state.timer);
+    const deadline = Math.min(...state.snapshot.files.map((file) => file.expiresAt));
+    if (!Number.isFinite(deadline)) {
+        state.timer = undefined;
+        return;
+    }
+    state.timer = setTimeout(() => {
+        publish(state, { ...state.snapshot, files: state.snapshot.files.filter((file) => file.expiresAt > Date.now()) });
+        scheduleExpiry(state);
+    }, Math.max(0, deadline - Date.now()));
+}
+export function getAgentActivity(projectId) { return project(projectId).snapshot; }
+export function useAgentActivity(projectId) {
+    return useSyncExternalStore((listener) => {
+        const state = project(projectId);
+        state.listeners.add(listener);
+        return () => { state.listeners.delete(listener); };
+    }, () => getAgentActivity(projectId), () => EMPTY);
+}

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

@@ -15,6 +15,7 @@ export interface AgentClientSnapshot {
     /** Companion state, using the shared protocol vocabulary. */
     readonly connection: AgentStatusSnapshot["connection"];
     readonly listenerActive: boolean;
+    readonly agentClientName?: string;
     /** Whether the last valid discovery response came from the local companion. */
     readonly companionReachable: boolean;
     readonly paired: boolean;
@@ -51,6 +52,7 @@ export declare class AgentClient {
     private started;
     private connection;
     private listenerActive;
+    private agentClientName;
     private companionReachable;
     private paired;
     private pairedElsewhere;