nudge-ui 0.2.0 → 0.2.1

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,12 @@
 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";
 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 +17,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 +50,57 @@ 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,
+            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 } : {}),
     };
 }
+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/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,8 @@ 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";
 /**
  * Loopback-only manifest/reload sidecar (ADR-0010).
  *
@@ -221,7 +222,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 +250,35 @@ 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 }
+                    : {}),
+                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 +319,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 +455,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 +463,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 +486,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 +514,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;

package/dist/hosts/next/wrapper.js

@@ -4,7 +4,7 @@ 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 { 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";
 /**
@@ -119,12 +119,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 +283,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 +308,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 +324,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,20 @@
+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 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,97 @@
+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");
+        }
+        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,5 @@
 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";
+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.
  *

package/dist/hosts/static/server.js

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

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

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