nudge-ui 0.2.1 → 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,8 +1,10 @@
+import { handleHtmlArtifactRequest } from "../../project/artifacts.js";
 import {} from "../../inspector/clientManifest.js";
 import { createAstroRuntimeConfig } from "./astroRuntimeConfig.js";
 import { createAstroClientAssetHandler } from "./clientAsset.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() {
@@ -16,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() {
@@ -55,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
@@ -77,6 +84,7 @@ async function createManifest(server, request, setBridge) {
             appRoot: server.config.root,
             projectId: runtime.projectId,
             origin,
+            info: (message) => server.config.logger.info(message),
             warn: (message) => server.config.logger.warn(message),
         })
         : null;
@@ -86,6 +94,7 @@ async function createManifest(server, request, setBridge) {
         revision: 0,
         runtime,
         ...(bridge ? { agentBridge: bridge.browser } : {}),
+        ...automationManifestFields(),
     };
 }
 function resolvedRequestOrigin(server, request) {

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

@@ -1,7 +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.
@@ -23,8 +26,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,19 +40,21 @@ 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",
         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/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/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";
@@ -9,6 +10,7 @@ import { createProjectFileWatcher, } from "../../project/files.js";
 import { createProjectTokenSnapshot } from "../../project/tokens.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).
  *
@@ -264,6 +266,7 @@ export async function ensureSidecar(root, options = {}) {
                 ...(options.projectBridgeAllowedOrigins
                     ? { allowedOrigins: options.projectBridgeAllowedOrigins }
                     : {}),
+                info: (message) => console.info(message),
                 warn: (message) => console.warn(message),
             }).then((bridge) => {
                 projectBridge = bridge;
@@ -297,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);
@@ -529,7 +535,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,6 +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 { 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);
     };

package/dist/hosts/projectBridge.d.ts

@@ -8,6 +8,7 @@ export declare function startOptionalProjectBridge(input: {
     readonly projectId: string;
     readonly origin: string;
     readonly allowedOrigins?: readonly string[];
+    readonly info?: (message: string) => void;
     readonly warn?: (message: string) => void;
 }): Promise<{
     browser: ProjectBridgeBrowserConfig;

package/dist/hosts/projectBridge.js

@@ -53,6 +53,7 @@ async function launchOptionalProjectBridge(input, key) {
             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 },

package/dist/hosts/static/manifest.js

@@ -1,4 +1,5 @@
 import { NUDGE_UI_MANIFEST_VERSION, NUDGE_UI_RELOAD_PATH } 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.
@@ -23,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,
@@ -39,6 +40,7 @@ export function createStandaloneRuntimeManifest(projectId, tokenSnapshot = empty
             strategy: "reload-document",
             events: ["ready", "reload"],
         },
+        ...automationManifestFields(),
     };
 }
 function emptyTokenSnapshot() {

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";
@@ -157,6 +158,7 @@ export function createStandaloneServer(options) {
                             appRoot: rootDirectory,
                             projectId,
                             origin: address.url.replace(/\/$/, ""),
+                            info: (message) => console.info(message),
                             warn: (message) => console.warn(message),
                         }).then((bridge) => {
                             projectBridge = bridge;
@@ -382,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
@@ -18,6 +19,7 @@ export interface VanillaExtractOptions {
     source?: string;
 }
 export interface NudgeUiOptions extends ReactOptions {
+    /** `false` registers nothing. `NUDGE_UI=0` has the same effect for one run. */
     enabled?: boolean;
     /** Enables experimental DOM parent/child navigation in the Inspector. */
     debug?: boolean;
@@ -27,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";
@@ -8,6 +9,7 @@ import { catalogSourcePath, createViteStylesheetArtifact, isHostApplicationSourc
 import { interpretDialects } from "../../css/dialects/index.js";
 import { detectStylingSystem, } from "../../inspector/clientManifest.js";
 import { loopbackOrigin, startOptionalProjectBridge, } from "../projectBridge.js";
+import { automationManifestFields, isNudgeUiEnabled } from "../environment.js";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -80,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>")) {
@@ -101,7 +105,7 @@ function invalidateHmrModules(server, modules, timestamp) {
  * here has grown a React assumption.
  */
 export function createVitePlugins(options = {}, createFramework = null) {
-    const enabled = options.enabled ?? true;
+    const enabled = isNudgeUiEnabled(options.enabled);
     let root;
     let buildOutputDirectory;
     let command = "serve";
@@ -484,6 +488,7 @@ export function createVitePlugins(options = {}, createFramework = null) {
             revision: 0,
             runtime: buildRuntimeSnapshot(),
             ...(projectBridge ? { agentBridge: projectBridge.browser } : {}),
+            ...automationManifestFields(),
         };
     }
     function startProjectBridge(server) {
@@ -506,6 +511,7 @@ export function createVitePlugins(options = {}, createFramework = null) {
             projectId: options.projectId ?? basename(root),
             origin,
             ...(allowedOrigins.length > 0 ? { allowedOrigins } : {}),
+            info: (message) => server.config.logger.info(message),
             warn: (message) => server.config.logger.warn(message),
         }).then((bridge) => {
             projectBridge = bridge;
@@ -530,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 })),
@@ -551,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;
@@ -583,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"
@@ -598,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) {
@@ -715,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,',