nudge-ui 0.2.0 → 0.2.2

package/dist/hosts/astro/astroRuntimeConfig.js

@@ -12,7 +12,7 @@ export function createAstroRuntimeConfig(knowledge) {
         framework: "Astro",
         stylingSystem: detectStylingSystem(knowledge.tokens),
         capabilities: {
-            canvas: false,
+            canvas: true,
             componentSemantics: true,
             sourceCoordinates: ASTRO_SOURCE_COORDINATES,
             scopingSelectorPattern: ASTRO_SCOPING_SELECTOR_PATTERN,

package/dist/hosts/astro/clientTransport.js

@@ -1,10 +1,13 @@
 import {} from "../../inspector/clientManifest.js";
 import { createAstroRuntimeConfig } from "./astroRuntimeConfig.js";
 import { createAstroClientAssetHandler } from "./clientAsset.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 { startOptionalProjectBridge } from "../projectBridge.js";
+import { automationManifestFields } from "../environment.js";
 const serveClient = createAstroClientAssetHandler();
 /** Serves the prebuilt client and its host-neutral manifest in Astro dev. */
 export function createAstroClientTransportPlugin() {
+    let projectBridge = null;
     return {
         name: "nudge-ui-astro-client-transport",
         // The shared Vite plugin exposes the same route for React hosts. Astro's
@@ -15,12 +18,27 @@ export function createAstroClientTransportPlugin() {
         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)
+                    void createManifest(server, request, (bridge) => {
+                        projectBridge = bridge;
+                    })
                         .then((manifest) => {
                         response.statusCode = 200;
                         response.setHeader("Content-Type", "application/json; charset=utf-8");
@@ -33,25 +51,59 @@ export function createAstroClientTransportPlugin() {
                 next();
             });
         },
+        async closeBundle() {
+            await projectBridge?.close();
+            projectBridge = null;
+        },
     };
 }
-async function createManifest(server) {
+async function createManifest(server, request, setBridge) {
     // SAFETY: these virtual modules are generated by the shared Nudge UI plugin
     // with the exact exports described by TokenModule and ComponentModule.
     const [tokenModule, componentModule] = await Promise.all([
         server.ssrLoadModule("virtual:design-tokens"),
         server.ssrLoadModule("virtual:nudge-ui-components"),
     ]);
+    const runtime = createAstroRuntimeConfig({
+        projectId: tokenModule.nudgeUiProjectId,
+        tokenCatalog: tokenModule.tokenCatalog,
+        tokens: tokenModule.tokens,
+        tokenDiagnostics: tokenModule.tokenDiagnostics,
+        tokenGeneration: tokenModule.tokenGeneration,
+        componentContracts: componentModule.componentContracts,
+    });
+    const origin = resolvedRequestOrigin(server, request);
+    const bridge = origin
+        ? await startOptionalProjectBridge({
+            appRoot: server.config.root,
+            projectId: runtime.projectId,
+            origin,
+            info: (message) => server.config.logger.info(message),
+            warn: (message) => server.config.logger.warn(message),
+        })
+        : null;
+    setBridge(bridge);
     return {
         version: 1,
         revision: 0,
-        runtime: createAstroRuntimeConfig({
-            projectId: tokenModule.nudgeUiProjectId,
-            tokenCatalog: tokenModule.tokenCatalog,
-            tokens: tokenModule.tokens,
-            tokenDiagnostics: tokenModule.tokenDiagnostics,
-            tokenGeneration: tokenModule.tokenGeneration,
-            componentContracts: componentModule.componentContracts,
-        }),
+        runtime,
+        ...(bridge ? { agentBridge: bridge.browser } : {}),
+        ...automationManifestFields(),
     };
 }
+function resolvedRequestOrigin(server, request) {
+    const host = request.headers.host;
+    if (!host)
+        return null;
+    const candidates = [
+        ...(server.resolvedUrls?.local ?? []),
+        ...(server.resolvedUrls?.network ?? []),
+    ].map((url) => new URL(url).origin);
+    const protocols = new Set(candidates.map((candidate) => new URL(candidate).protocol));
+    for (const protocol of protocols) {
+        const requested = new URL(`${protocol}//${host}`).origin;
+        if (candidates.includes(requested))
+            return requested;
+    }
+    return null;
+}

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

@@ -11,8 +11,8 @@ export interface NudgeUiAstroOptions extends NudgeUiOptions {
 /**
  * Nudge UI host Adapter for Astro dev servers (ADR-0011).
  *
- * Dev-only by contract (ADR-0002): unless `command === "dev"` and
- * `enabled !== false`, the integration registers nothing at all — no Vite
+ * Dev-only by contract (ADR-0002): unless `command === "dev"`,
+ * `enabled !== false`, and `NUDGE_UI` is not `0`, the integration registers nothing at all — no Vite
  * plugins, no injected scripts, no middleware — so `astro build` output is
  * byte-identical to a project without the integration.
  *

package/dist/hosts/astro/integration.js

@@ -2,6 +2,7 @@ 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";
 /**
  * Adds the prebuilt client as an external module. The inspector dependency
  * graph therefore never enters Astro's Vite optimizer.
@@ -23,8 +24,8 @@ const MIDDLEWARE_ENTRYPOINT = new URL(import.meta.url.endsWith(".ts") ? "./middl
 /**
  * Nudge UI host Adapter for Astro dev servers (ADR-0011).
  *
- * Dev-only by contract (ADR-0002): unless `command === "dev"` and
- * `enabled !== false`, the integration registers nothing at all — no Vite
+ * Dev-only by contract (ADR-0002): unless `command === "dev"`,
+ * `enabled !== false`, and `NUDGE_UI` is not `0`, the integration registers nothing at all — no Vite
  * plugins, no injected scripts, no middleware — so `astro build` output is
  * byte-identical to a project without the integration.
  *
@@ -37,7 +38,7 @@ const MIDDLEWARE_ENTRYPOINT = new URL(import.meta.url.endsWith(".ts") ? "./middl
  *    identity Module.
  */
 export function nudgeUiAstro(options = {}) {
-    const enabled = options.enabled ?? true;
+    const enabled = isNudgeUiEnabled(options.enabled);
     const sharedOptions = { ...options };
     return {
         name: "nudge-ui",

package/dist/hosts/environment.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The `NUDGE_UI` environment switch shared by every development host.
+ *
+ * - `0`, `false`, or `off` disables the host Adapter for that run.
+ * - `1`, `true`, or `on` also opens the editor in automated browsers, which
+ *   otherwise receive the plain application.
+ */
+export type NudgeUiEnvironmentSwitch = "off" | "on" | null;
+export declare function readNudgeUiEnvironmentSwitch(env?: Readonly<Record<string, string | undefined>>): NudgeUiEnvironmentSwitch;
+/** An explicit `enabled: false` or `NUDGE_UI=0` disables the Adapter. */
+export declare function isNudgeUiEnabled(enabled: boolean | undefined, env?: Readonly<Record<string, string | undefined>>): boolean;
+/** Manifest fields derived from the environment at request time. */
+export declare function automationManifestFields(env?: Readonly<Record<string, string | undefined>>): {
+    inspectAutomatedBrowsers?: true;
+};

package/dist/hosts/environment.js

@@ -0,0 +1,16 @@
+export function readNudgeUiEnvironmentSwitch(env = process.env) {
+    const value = env.NUDGE_UI?.trim().toLowerCase();
+    if (value === "0" || value === "false" || value === "off")
+        return "off";
+    if (value === "1" || value === "true" || value === "on")
+        return "on";
+    return null;
+}
+/** An explicit `enabled: false` or `NUDGE_UI=0` disables the Adapter. */
+export function isNudgeUiEnabled(enabled, env = process.env) {
+    return enabled !== false && readNudgeUiEnvironmentSwitch(env) !== "off";
+}
+/** Manifest fields derived from the environment at request time. */
+export function automationManifestFields(env = process.env) {
+    return readNudgeUiEnvironmentSwitch(env) === "on" ? { inspectAutomatedBrowsers: true } : {};
+}

package/dist/hosts/next/sidecar.d.ts

@@ -17,6 +17,10 @@ export interface SidecarOptions {
      * add/change/remove transitions. Diagnostics never disable inspection.
      */
     tokens?: boolean;
+    /** Trusted browser origin established by the Next development process. */
+    projectBridgeOrigin?: string;
+    /** Canonical loopback aliases for the known development port. */
+    projectBridgeAllowedOrigins?: readonly string[];
 }
 /**
  * Starts (or returns) the sidecar for this dev-server process.

package/dist/hosts/next/sidecar.js

@@ -7,7 +7,9 @@ import { buildManifest, } from "./manifest.js";
 import { extractComponentContracts } from "../../compiler/componentContracts.js";
 import { createProjectFileWatcher, } from "../../project/files.js";
 import { createProjectTokenSnapshot } from "../../project/tokens.js";
-import { NUDGE_UI_CLIENT_PATH, NUDGE_UI_MANIFEST_PATH, NUDGE_UI_RELOAD_PATH, NUDGE_UI_ROUTE_PREFIX, } from "../../transport/index.js";
+import { NUDGE_UI_CLIENT_PATH, NUDGE_UI_EDITOR_PATH, NUDGE_UI_MANIFEST_PATH, NUDGE_UI_RELOAD_PATH, NUDGE_UI_ROUTE_PREFIX, createNudgeUiEditorDocument, isNudgeUiEditorDocumentRequest, } from "../../transport/index.js";
+import { startOptionalProjectBridge } from "../projectBridge.js";
+import { automationManifestFields } from "../environment.js";
 /**
  * Loopback-only manifest/reload sidecar (ADR-0010).
  *
@@ -221,7 +223,7 @@ export async function ensureSidecar(root, options = {}) {
     // derive every filesystem-relative computation from the canonical root.
     const fsRoot = await realpath(root).catch(() => root);
     const scanRoots = await tokenScanRoots(fsRoot, options.sourceRoots);
-    const state = globalState(`${options.tokens ? "tokens" : "manifest"}:${fsRoot}:${scanRoots.join("|")}`);
+    const state = globalState(`${options.tokens ? "tokens" : "manifest"}:${options.projectBridgeOrigin ?? "plain"}:${fsRoot}:${scanRoots.join("|")}`);
     // The settled promise doubles as the handle cache: awaiting it replays the
     // same handle for every caller until close/failure clears the slot.
     if (state.starting)
@@ -249,7 +251,36 @@ export async function ensureSidecar(root, options = {}) {
                 stream.write(`data: ${JSON.stringify({ revision: generation })}\n\n`);
             }
         };
-        const manifest = options.manifest ?? buildManifest({ root });
+        let manifest = options.manifest ?? buildManifest({ root });
+        let projectBridge = null;
+        let projectBridgeStart = null;
+        const ensureProjectBridge = () => {
+            if (!options.projectBridgeOrigin || projectBridge || projectBridgeStart) {
+                return projectBridgeStart ?? Promise.resolve();
+            }
+            projectBridgeStart = startOptionalProjectBridge({
+                appRoot: fsRoot,
+                projectId: manifest.runtime.projectId,
+                origin: options.projectBridgeOrigin,
+                ...(options.projectBridgeAllowedOrigins
+                    ? { allowedOrigins: options.projectBridgeAllowedOrigins }
+                    : {}),
+                info: (message) => console.info(message),
+                warn: (message) => console.warn(message),
+            }).then((bridge) => {
+                projectBridge = bridge;
+                if (bridge)
+                    manifest = { ...manifest, agentBridge: bridge.browser };
+            });
+            return projectBridgeStart;
+        };
+        const closeProjectBridge = async () => {
+            await projectBridgeStart;
+            const bridge = projectBridge;
+            projectBridge = null;
+            projectBridgeStart = null;
+            await bridge?.close();
+        };
         const additionalTokenRoots = scanRoots.filter((scanRoot) => scanRoot !== fsRoot);
         const tokenSnapshotOptions = {
             rootDirectory: fsRoot,
@@ -290,6 +321,7 @@ export async function ensureSidecar(root, options = {}) {
             // The port file is diagnostics-only; the rewrite carries the real
             // transport, so an unwritable .next must not break instrumentation.
         }
+        await ensureProjectBridge();
         const watchers = [];
         // The startup source scan runs regardless of the token lifecycle so a
         // restarted sidecar republishes contracts even when Turbopack's
@@ -425,7 +457,7 @@ export async function ensureSidecar(root, options = {}) {
                 // close. Closing twice must not throw.
                 if (!server.listening) {
                     state.starting = undefined;
-                    return Promise.resolve();
+                    return closeProjectBridge();
                 }
                 for (const stream of streams)
                     stream.end();
@@ -433,9 +465,13 @@ export async function ensureSidecar(root, options = {}) {
                 void Promise.all(watchers.map((watcher) => watcher.close().catch(() => { })));
                 rmSync(portFilePath(root), { force: true });
                 state.starting = undefined;
-                return new Promise((resolveClose, rejectClose) => {
+                const closeServer = new Promise((resolveClose, rejectClose) => {
                     server.close((error) => (error ? rejectClose(error) : resolveClose()));
                 });
+                return Promise.all([
+                    closeServer,
+                    closeProjectBridge(),
+                ]).then(() => undefined);
             },
         };
         return handle;
@@ -452,7 +488,8 @@ export async function ensureSidecar(root, options = {}) {
     return starting;
 }
 function respond(req, res, currentManifest, currentGeneration, streams, receiveContracts) {
-    const url = (req.url ?? "").split("?")[0];
+    const requestUrl = req.url ?? "";
+    const url = requestUrl.split("?")[0];
     // Loader postings aggregate component contracts (Stage 5). Loopback-only by
     // virtue of the bind address; payload size is capped defensively.
     if (url === `${NUDGE_UI_ROUTE_PREFIX}contracts` && req.method === "POST") {
@@ -479,6 +516,14 @@ function respond(req, res, currentManifest, currentGeneration, streams, receiveC
         });
         return;
     }
+    if (isNudgeUiEditorDocumentRequest(requestUrl, req.method, req.headers)) {
+        res.writeHead(200, {
+            "content-type": "text/html; charset=utf-8",
+            "cache-control": "no-store",
+        });
+        res.end(req.method === "HEAD" ? undefined : createNudgeUiEditorDocument());
+        return;
+    }
     if (req.method !== "GET") {
         res.writeHead(405).end();
         return;
@@ -486,7 +531,11 @@ function respond(req, res, currentManifest, currentGeneration, streams, receiveC
     if (url === NUDGE_UI_MANIFEST_PATH) {
         // The served snapshot carries its revision so clients can reconcile
         // against SSE notifications instead of guessing.
-        const body = `${JSON.stringify({ ...currentManifest(), revision: currentGeneration() })}\n`;
+        const body = `${JSON.stringify({
+            ...currentManifest(),
+            revision: currentGeneration(),
+            ...automationManifestFields(),
+        })}\n`;
         res.writeHead(200, {
             "content-type": "application/json",
             "cache-control": "no-store",

package/dist/hosts/next/wrapper.d.ts

@@ -28,6 +28,8 @@ export interface NudgeUiNextConfig {
 }
 /** Host-specific policy additions passed to the shared source compiler. */
 export interface NudgeUiNextOptions {
+    /** `false` returns the configuration untouched. `NUDGE_UI=0` has the same effect for one run. */
+    readonly enabled?: boolean;
     readonly componentProtocols?: ComponentModuleProtocols;
     /** Authored workspace directories outside the Next.js application root. */
     readonly sourceRoots?: readonly string[];

package/dist/hosts/next/wrapper.js

@@ -4,7 +4,8 @@ import { dirname, join, relative, resolve } from "node:path";
 import { ensureSidecar } from "./sidecar.js";
 import { buildManifest } from "./manifest.js";
 import { nudgeUiRepositoryPackagePath } from "./repositoryScope.js";
-import { NUDGE_UI_ROUTE_PREFIX } from "../../transport/index.js";
+import { isNudgeUiEnabled } from "../environment.js";
+import { NUDGE_UI_EDITOR_QUERY_PARAM, NUDGE_UI_EDITOR_QUERY_VALUE, NUDGE_UI_ROUTE_PREFIX, } from "../../transport/index.js";
 const NAMESPACE_PREFIX = NUDGE_UI_ROUTE_PREFIX.slice(0, -1);
 const SUPPORTED_NEXT_RANGE = ">=15.3 <17";
 /**
@@ -104,7 +105,7 @@ export function withNudgeUi(config = {}, options = {}) {
         : () => config;
     return (phase) => {
         const resolved = factory(phase);
-        if (!isDevelopmentEvaluation(phase))
+        if (!isDevelopmentEvaluation(phase) || !isNudgeUiEnabled(options.enabled))
             return resolved;
         return instrumentConfig(resolved, options);
     };
@@ -119,12 +120,15 @@ function instrumentConfig(config, options) {
         return config;
     }
     const sourceRoots = options.sourceRoots?.map((sourceRoot) => resolve(root, sourceRoot));
+    const bridgeOrigin = nextDevelopmentOrigin();
     // ensureSidecar is a per-process singleton; awaiting it wherever the port
     // is needed removes any config-evaluation race. The same authored roots
     // reach token discovery so workspace CSS is visible to both integrations.
     const sidecarPort = () => ensureSidecar(root, {
         manifest: buildManifest({ root }),
         tokens: true,
+        projectBridgeOrigin: bridgeOrigin.origin,
+        projectBridgeAllowedOrigins: bridgeOrigin.allowedOrigins,
         ...(sourceRoots ? { sourceRoots } : {}),
     })
         .then((handle) => handle.port)
@@ -280,6 +284,14 @@ function instrumentConfig(config, options) {
         source: `${NUDGE_UI_ROUTE_PREFIX}:path*`,
         destination: `http://127.0.0.1:${port}${NUDGE_UI_ROUTE_PREFIX}:path*`,
     });
+    const editorRewrite = (port, header) => ({
+        source: "/:path*",
+        has: [
+            { type: "query", key: NUDGE_UI_EDITOR_QUERY_PARAM, value: NUDGE_UI_EDITOR_QUERY_VALUE },
+            { type: "header", ...header },
+        ],
+        destination: `http://127.0.0.1:${port}/:path*`,
+    });
     const resolveRewrites = async () => {
         const port = await sidecarPort();
         const userRewrites = typeof source.rewrites === "function"
@@ -297,7 +309,12 @@ function instrumentConfig(config, options) {
             // Port 0 (sidecar failed to bind) yields a dead destination; the mount
             // surfaces an honest fetch failure instead of silently pretending to
             // work.
-            beforeFiles: [proxyRewrite(port), ...(shape.beforeFiles ?? [])],
+            beforeFiles: [
+                proxyRewrite(port),
+                editorRewrite(port, { key: "accept", value: ".*text/html.*" }),
+                editorRewrite(port, { key: "sec-fetch-dest", value: "document" }),
+                ...(shape.beforeFiles ?? []),
+            ],
             afterFiles: shape.afterFiles ?? [],
             fallback: shape.fallback ?? [],
         };
@@ -308,3 +325,15 @@ function instrumentConfig(config, options) {
     // consumers keep their NextConfig typing via the generic passthrough.
     return nextConfig;
 }
+function nextDevelopmentOrigin() {
+    const selected = process.env.__NEXT_PRIVATE_ORIGIN
+        ?? `http://localhost:${process.env.PORT ?? "3000"}`;
+    const url = new URL(selected);
+    const port = url.port || (url.protocol === "https:" ? "443" : "80");
+    const aliases = ["localhost", "127.0.0.1", "[::1]"]
+        .map((host) => `${url.protocol}//${host}:${port}`);
+    return {
+        origin: url.origin,
+        allowedOrigins: [...new Set([url.origin, ...aliases])],
+    };
+}

package/dist/hosts/projectBridge.d.ts

@@ -0,0 +1,21 @@
+export interface ProjectBridgeBrowserConfig {
+    readonly baseUrl: string;
+    readonly autoConnect: true;
+}
+/** Starts the optional project bridge installed beside the host application. */
+export declare function startOptionalProjectBridge(input: {
+    readonly appRoot: string;
+    readonly projectId: string;
+    readonly origin: string;
+    readonly allowedOrigins?: readonly string[];
+    readonly info?: (message: string) => void;
+    readonly warn?: (message: string) => void;
+}): Promise<{
+    browser: ProjectBridgeBrowserConfig;
+    close(): Promise<void>;
+} | null>;
+/** Returns the browser origin for a loopback HTTP server address. */
+export declare function loopbackOrigin(address: {
+    address: string;
+    port: number;
+}, protocol?: "http" | "https"): string;

package/dist/hosts/projectBridge.js

@@ -0,0 +1,98 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, parse } from "node:path";
+import { pathToFileURL } from "node:url";
+const runningBridges = new Map();
+/** Starts the optional project bridge installed beside the host application. */
+export async function startOptionalProjectBridge(input) {
+    const key = `${input.appRoot}\u0000${input.origin}`;
+    const running = runningBridges.get(key);
+    if (running)
+        return running;
+    const starting = launchOptionalProjectBridge(input, key);
+    runningBridges.set(key, starting);
+    void starting.then((bridge) => {
+        if (bridge === null && runningBridges.get(key) === starting)
+            runningBridges.delete(key);
+    });
+    return starting;
+}
+async function launchOptionalProjectBridge(input, key) {
+    let modulePath;
+    try {
+        if (!isPnpRuntime() && !hasProjectInstalledMcp(input.appRoot)) {
+            runningBridges.delete(key);
+            return null;
+        }
+        modulePath = createRequire(join(input.appRoot, "package.json")).resolve("@nudge-ui/mcp/project");
+    }
+    catch {
+        runningBridges.delete(key);
+        return null;
+    }
+    try {
+        const loaded = await import(__rewriteRelativeImportExtension(pathToFileURL(modulePath).href));
+        if (typeof loaded.startProjectBridge !== "function") {
+            throw new Error("the project bridge export is unavailable");
+        }
+        const runtime = await loaded.startProjectBridge({
+            appRoot: input.appRoot,
+            projectId: input.projectId,
+            origin: input.origin,
+            ...(input.allowedOrigins ? { allowedOrigins: input.allowedOrigins } : {}),
+        });
+        if (runtime.browser.projectId !== input.projectId || runtime.browser.origin !== input.origin) {
+            await runtime.close().catch(() => undefined);
+            throw new Error("the project bridge returned a different project or origin");
+        }
+        input.info?.(`[nudge-ui] project bridge ready for ${input.projectId}`);
+        let closed = false;
+        return {
+            browser: { baseUrl: runtime.browser.bridgeUrl, autoConnect: true },
+            close: async () => {
+                if (closed)
+                    return;
+                closed = true;
+                runningBridges.delete(key);
+                await runtime.close();
+            },
+        };
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        input.warn?.(`[nudge-ui] MCP project bridge failed to start: ${detail}`);
+        runningBridges.delete(key);
+        return null;
+    }
+}
+function isPnpRuntime() {
+    return typeof process.versions.pnp === "string";
+}
+function hasProjectInstalledMcp(appRoot) {
+    let directory = appRoot;
+    const root = parse(directory).root;
+    for (;;) {
+        if (existsSync(join(directory, "node_modules", "@nudge-ui", "mcp", "package.json")))
+            return true;
+        if (directory === root)
+            return false;
+        directory = dirname(directory);
+    }
+}
+/** Returns the browser origin for a loopback HTTP server address. */
+export function loopbackOrigin(address, protocol = "http") {
+    const host = address.address === "::" || address.address === "::1"
+        ? "[::1]"
+        : address.address === "0.0.0.0"
+            ? "127.0.0.1"
+            : address.address;
+    return `${protocol}://${host}:${address.port}`;
+}

package/dist/hosts/static/cli.d.ts

@@ -9,4 +9,4 @@ export declare function parseServeArguments(args: readonly string[], currentDire
 /** Starts the CLI server and waits until the process receives a termination signal. */
 export declare function runServeCommand(options: ServeCommandOptions): Promise<void>;
 /** Runs the standalone command. */
-export declare function main(args?: string[]): Promise<void>;
+export declare function main(args?: string[], packageVersion?: string): Promise<void>;

package/dist/hosts/static/cli.js

@@ -1,4 +1,5 @@
 import { resolve } from "node:path";
+import { runAgentCommand } from "../../cli/agentCommand.js";
 import { createStandaloneServer } from "./server.js";
 /** Parses the standalone CLI's intentionally small command surface. */
 export function parseServeArguments(args, currentDirectory = process.cwd()) {
@@ -44,7 +45,11 @@ export async function runServeCommand(options) {
     await waitForTermination(server);
 }
 /** Runs the standalone command. */
-export async function main(args = process.argv.slice(2)) {
+export async function main(args = process.argv.slice(2), packageVersion) {
+    if (args[0] === "agent") {
+        runAgentCommand(args.slice(1), packageVersion);
+        return;
+    }
     const options = parseServeArguments(args);
     await runServeCommand(options);
 }

package/dist/hosts/static/manifest.d.ts

@@ -1,6 +1,6 @@
 import type { NudgeUiClientManifest } from "../../inspector/clientManifest.js";
 import type { ProjectTokenSnapshot } from "../../project/tokens.js";
-export { NUDGE_UI_CLIENT_PATH, NUDGE_UI_MANIFEST_PATH, NUDGE_UI_MOUNT_ID, NUDGE_UI_RELOAD_PATH, NUDGE_UI_ROUTE_PREFIX, } from "../../transport/index.js";
+export { NUDGE_UI_CLIENT_PATH, NUDGE_UI_EDITOR_PATH, NUDGE_UI_MANIFEST_PATH, NUDGE_UI_MOUNT_ID, NUDGE_UI_RELOAD_PATH, NUDGE_UI_ROUTE_PREFIX, } from "../../transport/index.js";
 /** The serializable runtime document sent to a standalone client. */
 export interface StandaloneRuntimeManifest extends NudgeUiClientManifest {
 }

package/dist/hosts/static/manifest.js

@@ -1,5 +1,6 @@
 import { NUDGE_UI_MANIFEST_VERSION, NUDGE_UI_RELOAD_PATH } from "../../transport/index.js";
-export { NUDGE_UI_CLIENT_PATH, NUDGE_UI_MANIFEST_PATH, NUDGE_UI_MOUNT_ID, NUDGE_UI_RELOAD_PATH, NUDGE_UI_ROUTE_PREFIX, } from "../../transport/index.js";
+import { automationManifestFields } from "../environment.js";
+export { NUDGE_UI_CLIENT_PATH, NUDGE_UI_EDITOR_PATH, NUDGE_UI_MANIFEST_PATH, NUDGE_UI_MOUNT_ID, NUDGE_UI_RELOAD_PATH, NUDGE_UI_ROUTE_PREFIX, } from "../../transport/index.js";
 /**
  * Creates the first valid static-HTML runtime snapshot.
  *
@@ -39,6 +40,7 @@ export function createStandaloneRuntimeManifest(projectId, tokenSnapshot = empty
             strategy: "reload-document",
             events: ["ready", "reload"],
         },
+        ...automationManifestFields(),
     };
 }
 function emptyTokenSnapshot() {