nudge-ui 0.2.4 → 0.2.6

package/dist/hosts/next/sidecar.js

@@ -11,33 +11,11 @@ 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).
- *
- * One server per dev-server process, guarded against double-spawn because
- * Next re-evaluates `next.config` more than once. Same-origin access without
- * CORS comes from a `beforeFiles` rewrite proxying `/__nudge_ui__/*` to the
- * sidecar port — both are wrapper-owned config, so the user touchpoint stays
- * at one line.
- *
- * Routes:
- * - GET /__nudge_ui__/client.mjs — the shared self-contained inspector client.
- * - GET /__nudge_ui__/manifest — the frozen runtime snapshot, including
- *   the Stage 4 token lifecycle when `tokens` is enabled: scanned project CSS
- *   feeds a deterministic generation, and each settled watcher batch bumps
- *   the generation and emits exactly one reload notification.
- * - GET /__nudge_ui__/reload  — SSE revision notifications after settled
- *   file changes.
- */
 const STATE_DIR_SEGMENT = ".next";
 const packageRequire = createRequire(import.meta.url);
 let inspectorClientPath;
 const GLOBAL_KEY = Symbol.for("nudge-ui/next/sidecar");
-/**
- * One sidecar per process per configuration. The key keeps a token-enabled
- * server from being conflated with a bare manifest-only server created
- * elsewhere in the same process (tests, multiple projects).
- */
+/** One sidecar per process per configuration: the key keeps token-enabled and manifest-only servers distinct. */
 function globalState(key) {
     // SAFETY: The GLOBAL_KEY symbol names the one global slot this module owns and writes itself.
     const holder = globalThis;
@@ -58,9 +36,7 @@ function portFilePath(root) {
 }
 const CONTRACT_SOURCE_EXT = /\.(tsx|jsx)$/;
 const SCAN_EXCLUDED_SEGMENTS = new Set([".git", ".next", "build", "dist", "node_modules"]);
-/** Upper bound on examined project source files; truncation is announced. */
 const SCAN_MAX_SOURCES = 5000;
-/** Returns whether a directory declares a package-manager workspace. */
 function hasWorkspaceManifest(directory) {
     if (existsSync(join(directory, "pnpm-workspace.yaml")))
         return true;
@@ -79,18 +55,8 @@ function hasWorkspaceManifest(directory) {
         return false;
     }
 }
-/** Upper bound on ancestors examined when searching for a workspace root. */
 const MAX_WORKSPACE_SEARCH_DEPTH = 5;
-/**
- * Finds the nearest declared workspace root by walking upward from the app.
- *
- * A Next app normally runs with its app directory as `process.cwd()`. When a
- * workspace manifest is present above that directory, the workspace is the
- * smallest safe default that can include sibling authored stylesheets. The
- * walk is bounded and never promotes the filesystem root itself, so a stray
- * manifest at `/` cannot turn the whole machine into the token scan root.
- * With no manifest found, scanning remains confined to the app root.
- */
+/** Bounded upward walk; never promotes the filesystem root, so a stray manifest at `/` cannot become the scan root. */
 function nearestWorkspaceRoot(root) {
     let directory = root;
     for (let depth = 0; depth <= MAX_WORKSPACE_SEARCH_DEPTH; depth += 1) {
@@ -120,17 +86,8 @@ function isWithinRoot(root, candidate) {
             && !isAbsolute(pathFromRoot));
 }
 /**
- * Extracts component contracts directly from project sources.
- *
- * Compile-time loader postings alone leave a restart gap: Turbopack's
- * persistent cache serves previously compiled modules without re-running
- * loaders, so a fresh sidecar would publish an empty contract catalog until
- * every file happens to recompile. Reading the same authored sources the
- * loader reads keeps the manifest coherent across dev-server restarts.
- *
- * `canonicalRoot` must be the realpath'd project root so aggregation keys
- * match both loader postings and watcher events regardless of how the host
- * spelled the working directory.
+ * Reads authored sources directly because Turbopack's persistent cache can skip
+ * loader re-runs; `canonicalRoot` must be realpath'd so keys match loader postings.
  */
 async function scanProjectContracts(canonicalRoot, apply) {
     const queue = [canonicalRoot];
@@ -178,12 +135,7 @@ async function scanProjectContracts(canonicalRoot, apply) {
     }
     return { truncated, files };
 }
-/**
- * Reads one source file only while its size is stable across the read.
- * Editors that truncate-then-write can expose half a file at read time; a
- * syntactically valid prefix would otherwise replace good contracts with
- * wrong ones until the next settled batch.
- */
+/** Null unless the size is stable across the read: truncate-then-write editors can expose a syntactically valid prefix. */
 function readStableSource(absolutePath) {
     try {
         const sizeBefore = statSync(absolutePath).size;
@@ -197,14 +149,12 @@ function readStableSource(absolutePath) {
         return null;
     }
 }
-/** Removes a stale port file left by a crashed previous run. */
 export function clearStaleSidecarState(root) {
     try {
         // SAFETY: The JSON.parse result is validated by the typeof guard below before use.
         const raw = JSON.parse(readFileSync(portFilePath(root), "utf8"));
         if (typeof raw.pid === "number" && raw.pid !== process.pid) {
-            // A previous process's record: safe to drop. The loopback socket it
-            // named cannot be trusted for reuse and is never dialled here.
+            // Previous process's record: the socket it named is never dialled, so dropping it is safe.
             rmSync(portFilePath(root), { force: true });
         }
     }
@@ -212,16 +162,9 @@ export function clearStaleSidecarState(root) {
         // Absent or unreadable state is fine; a fresh record gets written below.
     }
 }
-/**
- * Starts (or returns) the sidecar for this dev-server process.
- *
- * `root` is the project root; the manifest names itself from it. The server
- * binds 127.0.0.1 exclusively.
- */
 export async function ensureSidecar(root, options = {}) {
-    // Watchers and removal events report REAL paths; on macOS the tmp/root
-    // prefix may differ (e.g. /tmp -> /private/tmp), so canonicalize once and
-    // derive every filesystem-relative computation from the canonical root.
+    // Watchers report REAL paths; on macOS the textual form can differ from root
+    // (/tmp -> /private/tmp), so canonicalize once and derive everything from fsRoot.
     const fsRoot = await realpath(root).catch(() => root);
     const scanRoots = await tokenScanRoots(fsRoot, options.sourceRoots);
     const state = globalState(`${options.tokens ? "tokens" : "manifest"}:${options.projectBridgeOrigin ?? "plain"}:${fsRoot}:${scanRoots.join("|")}`);
@@ -232,11 +175,6 @@ export async function ensureSidecar(root, options = {}) {
     const starting = (async () => {
         let generation = 0;
         const streams = new Set();
-        // Token knowledge lives in a mutable holder so settled batches can swap
-        // the snapshot without rebuilding the rest of the manifest.
-        // Component contracts aggregate across loader postings, keyed by file so
-        // recompiles replace rather than duplicate (Stage 5). A debounced flush
-        // publishes one revision per settled burst of compilations.
         const contractsByFile = new Map();
         let contractsTimer = null;
         const flushContracts = () => {
@@ -307,8 +245,7 @@ export async function ensureSidecar(root, options = {}) {
         });
         const port = await new Promise((resolvePort, rejectPort) => {
             server.once("error", rejectPort);
-            // Port 0 asks the kernel for a free loopback port, so concurrent
-            // projects on one machine never collide.
+            // Port 0 lets concurrent projects on one machine pick distinct free loopback ports.
             server.listen(0, "127.0.0.1", () => {
                 const address = server.address();
                 if (address && typeof address === "object")
@@ -322,14 +259,11 @@ export async function ensureSidecar(root, options = {}) {
             writeFileSync(portFilePath(root), `${JSON.stringify({ pid: process.pid, port })}\n`);
         }
         catch {
-            // The port file is diagnostics-only; the rewrite carries the real
-            // transport, so an unwritable .next must not break instrumentation.
+            // The port file is diagnostics-only; 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
-        // persistent cache skips every loader re-run.
+        // Runs even without the token lifecycle so a restarted sidecar republishes contracts.
         try {
             await scanProjectContracts(fsRoot, (file, list) => {
                 contractsByFile.set(file, list);
@@ -341,9 +275,7 @@ export async function ensureSidecar(root, options = {}) {
             /* an unreadable tree keeps whatever knowledge postings provided */
         }
         if (options.tokens) {
-            // Initial scan before the first manifest response so early clients see
-            // tokens without waiting for a watcher tick. Failures degrade to the
-            // empty snapshot already present in the manifest.
+            // Scan before the first manifest response so early clients see tokens without waiting for a watcher tick.
             try {
                 applySnapshot(await createProjectTokenSnapshot(tokenSnapshotOptions));
             }
@@ -362,16 +294,12 @@ export async function ensureSidecar(root, options = {}) {
             };
             const settleProjectChanges = async (changes) => {
                 let needsContractRescan = false;
-                // Changed or deleted component sources update their aggregated
-                // contracts directly: deletions must prune (or stale controls
-                // survive forever), and edits re-extract from the authored bytes
-                // even if a compiler cache never re-runs the loader. A read that
-                // lands mid-write is skipped — the next settled batch retries.
+                // Deletions must prune or stale controls survive forever; a read that
+                // lands mid-write is skipped and retried on the next settled batch.
                 for (const change of changes) {
                     const normalized = change.absolutePath.split("\\").join("/");
-                    // fs.watch can report a directory or omit a filename. In that
-                    // case the exact source is unknown, so a bounded project scan is
-                    // the only way to keep the contract catalog coherent.
+                    // fs.watch can report a directory or omit the filename, leaving the
+                    // source unknown; a bounded rescan is then the only way to stay coherent.
                     if (!CONTRACT_SOURCE_EXT.test(normalized)) {
                         needsContractRescan = true;
                         continue;
@@ -410,14 +338,10 @@ export async function ensureSidecar(root, options = {}) {
                 }
                 await settleTokens();
             };
-            // Always keep the application watcher responsible for component
-            // contracts. Additional workspace roots only need token updates; using
-            // them for contract rescans would broaden the contract root silently.
-            // Roots nested inside the app are already covered by the app watcher.
+            // Extra workspace roots refresh tokens only; contract rescans stay
+            // within the app root (nested roots are already covered by the app watcher).
             const additionalRoots = scanRoots.filter((scanRoot) => scanRoot !== fsRoot && !isWithinRoot(fsRoot, scanRoot));
-            // Additional roots can overlap each other (for example an explicit
-            // source root inside the workspace). Keep only the outermost so one
-            // sibling edit settles into one token scan.
+            // Roots can nest; keep only the outermost so one sibling edit settles into one token scan.
             const outerAdditionalRoots = additionalRoots
                 .sort((a, b) => a.length - b.length)
                 .filter((scanRoot, index, list) => !list.slice(0, index).some((outer) => isWithinRoot(outer, scanRoot)));
@@ -433,9 +357,8 @@ export async function ensureSidecar(root, options = {}) {
                     rootDirectory: tokenRoot,
                     debounceMs: 60,
                     onSettled: async (changes) => {
-                        // A workspace root contains the app tree, so app edits fire this
-                        // watcher too. The app watcher already refreshes tokens for those
-                        // edits, so only changes outside the app need a second scan.
+                        // App edits fire this watcher too; the app watcher already covers them,
+                        // so only changes outside the app need a second scan.
                         const outside = isWithinRoot(tokenRoot, fsRoot)
                             ? changes.filter((change) => !isWithinRoot(fsRoot, change.absolutePath))
                             : changes;
@@ -456,9 +379,7 @@ export async function ensureSidecar(root, options = {}) {
                     stream.write(`data: ${JSON.stringify({ revision })}\n\n`);
             },
             close() {
-                // Idempotent: the singleton handle can be reached from several test
-                // files in one worker, and a dev server shutdown may race an explicit
-                // close. Closing twice must not throw.
+                // Idempotent: the singleton can be closed twice (tests, shutdown race) without throwing.
                 if (!server.listening) {
                     state.starting = undefined;
                     return closeProjectBridge();
@@ -480,10 +401,8 @@ export async function ensureSidecar(root, options = {}) {
         };
         return handle;
     })();
-    // A failed start must not wedge the singleton forever: the Symbol.for key
-    // survives HMR re-evaluation, so a cached rejected promise would be
-    // replayed to every later caller. Observe the rejection and clear the slot
-    // (identity-checked so a concurrent successful start is never discarded).
+    // A failed start must not wedge the singleton (the Symbol.for key survives
+    // HMR): clear the slot, identity-checked so a concurrent start is not discarded.
     starting.catch(() => {
         if (state.starting === starting)
             state.starting = undefined;
@@ -494,8 +413,6 @@ export async function ensureSidecar(root, options = {}) {
 function respond(req, res, currentManifest, currentGeneration, streams, receiveContracts) {
     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") {
         let body = "";
         req.on("data", (chunk) => {
@@ -533,8 +450,6 @@ function respond(req, res, currentManifest, currentGeneration, streams, receiveC
         return;
     }
     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(),
@@ -571,7 +486,7 @@ function respond(req, res, currentManifest, currentGeneration, streams, receiveC
         res.write(": nudge-ui reload stream\n\n");
         streams.add(res);
         res.on("close", () => streams.delete(res));
-        // Announce the current generation so late subscribers can reconcile.
+        // Send the current revision first so late subscribers do not miss a change.
         res.write(`data: ${JSON.stringify({ revision: currentGeneration() })}\n\n`);
         return;
     }

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

@@ -1,18 +1,4 @@
 import type { ComponentModuleProtocols } from "../../compiler/componentPolicyResolution.js";
-/**
- * `withNudgeUi(nextConfig)` — the single user touchpoint (ADR-0010).
- *
- * Development-phase gated per ADR-0002: the returned config factory
- * instruments only `next dev` (`PHASE_DEVELOPMENT_SERVER` with
- * `NODE_ENV=development`). Every other phase returns the original
- * configuration untouched and nothing is registered, spawned, or injected.
- * Production builds cannot observe Nudge UI.
- *
- * The wrapper is written against a structural subset of Next's config types
- * so this package stays typecheckable without `next` installed; consumers
- * pass their real NextConfig object straight through.
- */
-/** Structural subset of Next.js config this wrapper reads and writes. */
 export interface NudgeUiNextConfig {
     [key: string]: unknown;
     turbopack?: {
@@ -26,7 +12,6 @@ export interface NudgeUiNextConfig {
     rewrites?: (() => Promise<RewritesShape> | RewritesShape) | RewritesShape;
     transpilePackages?: string[];
 }
-/** 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;
@@ -47,22 +32,6 @@ export interface RewritesShape {
 }
 /** Mirrors next/constants PHASE_DEVELOPMENT_SERVER. */
 export declare const DEVELOPMENT_SERVER_PHASE = "phase-development-server";
-/**
- * Wraps a Next.js configuration with Nudge UI instrumentation.
- *
- * Two input forms are supported:
- *
- * - **Function form (recommended):** pass `(phase) => nextConfig`; the
- *   wrapper resolves and instruments ONLY for PHASE_DEVELOPMENT_SERVER, so
- *   `NODE_ENV=development next build` cannot register instrumentation
- *   (ADR-0002) regardless of environment tricks.
- * - **Object form:** converted to a phase-aware config factory. This keeps
- *   the convenient `withNudgeUi(nextConfig)` invocation while ensuring Next
- *   supplies the phase before any instrumentation can be registered.
- *
- * @param config The application's existing configuration or a config factory.
- * @returns A configuration (or factory) to export in its place.
- */
 /** Function form: gates instrumentation on PHASE_DEVELOPMENT_SERVER. */
 export declare function withNudgeUi<T extends object>(factory: (phase: string) => T, options?: NudgeUiNextOptions): (phase: string) => T;
 /** Object form: returns a phase-aware Next.js config factory. */

package/dist/hosts/next/wrapper.js

@@ -8,11 +8,7 @@ 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";
-/**
- * Resolved from the package root so the path is identical whether this module
- * runs from `src/hosts/next/` during development or `dist/hosts/next/` when
- * installed. The loaders only ever exist in `dist`.
- */
+/** Resolved from the package root so the path is the same from `src/` and `dist/`. */
 function loaderPaths() {
     const loaders = new URL("../../../dist/hosts/next/loaders/", import.meta.url);
     return {
@@ -20,7 +16,6 @@ function loaderPaths() {
         identity: fileURLToPath(new URL("identity-loader.cjs", loaders)),
     };
 }
-/** Absolute directory of a package installed in the host project, or null. */
 function hostPackageDir(root, name) {
     try {
         const require = createRequire(join(root, "package.json"));
@@ -30,7 +25,6 @@ function hostPackageDir(root, name) {
         return null;
     }
 }
-/** Absolute path for an Adapter-owned package export, resolved beside this package. */
 function adapterPackageExport(specifier) {
     try {
         return createRequire(import.meta.url).resolve(specifier);
@@ -52,14 +46,7 @@ function resolveNextVersion(root) {
         return null;
     }
 }
-/**
- * ADR-0010 gates instrumentation on the supported range: a RESOLVED version
- * outside it fails closed (no registration) with a diagnostic — instrumenting
- * an unsupported compiler risks breaking the host build. An unresolvable
- * version gets the benefit of the doubt and proceeds with a diagnostic,
- * since refusing to work because we could not read a version number would
- * make the adapter brittle for no safety gain.
- */
+/** Fails closed on a resolved unsupported version; an unresolvable one proceeds with a diagnostic. */
 function gateUnsupportedVersion(version) {
     if (version && isVersionSupported(version))
         return true;
@@ -74,7 +61,6 @@ function isVersionSupported(version) {
         return false;
     const major = Number(match[1]);
     const minor = Number(match[2]);
-    // >=15.3 <17
     return (major === 15 && minor >= 3) || (major >= 16 && major < 17);
 }
 function collectUserRewriteSources(rewrites) {
@@ -88,14 +74,7 @@ function collectUserRewriteSources(rewrites) {
 }
 /** Mirrors next/constants PHASE_DEVELOPMENT_SERVER. */
 export const DEVELOPMENT_SERVER_PHASE = "phase-development-server";
-/**
- * Returns whether this config evaluation belongs to Next's development
- * server. The phase argument is supplied by Next when it invokes a config
- * factory, so object exports are converted to factories before any
- * instrumentation can run. Keeping the phase check here means an object
- * export cannot accidentally instrument `next build` when a caller has
- * forced `NODE_ENV=development`.
- */
+/** Object exports are converted to factories so the phase is always available; the phase gate keeps `NODE_ENV=development next build` uninstrumented. */
 function isDevelopmentEvaluation(phase) {
     return process.env.NODE_ENV === "development" && phase === DEVELOPMENT_SERVER_PHASE;
 }
@@ -111,19 +90,15 @@ export function withNudgeUi(config = {}, options = {}) {
     };
 }
 function instrumentConfig(config, options) {
-    // Consumers pass their real NextConfig object; the structural subset is an
-    // internal view so this package stays typecheckable without next installed.
+    // Consumers pass their real NextConfig; the structural view keeps this package typecheckable without next installed.
     const source = config;
     const root = process.cwd();
-    // Fail closed per ADR-0010 when the resolved version is unsupported.
     if (!gateUnsupportedVersion(resolveNextVersion(root))) {
         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.
+    // ensureSidecar is a per-process singleton; awaiting it wherever the port is needed removes any config-evaluation race.
     const sidecarPort = () => ensureSidecar(root, {
         manifest: buildManifest({ root }),
         tokens: true,
@@ -137,14 +112,7 @@ function instrumentConfig(config, options) {
         return 0;
     });
     const nextConfig = { ...source };
-    // --- transpilePackages -------------------------------------------------
-    // Workspace Nudge UI packages ship raw TypeScript that SWC refuses to
-    // compile from node_modules unless listed (see feature-plan appendix).
-    const nudgeUiPackages = [
-        "nudge-ui",
-        "../../inspector/index.ts",
-        "../../css/index.ts",
-    ];
+    const nudgeUiPackages = ["nudge-ui"];
     const userTranspile = Array.isArray(source.transpilePackages)
         ? source.transpilePackages
         : [];
@@ -152,7 +120,6 @@ function instrumentConfig(config, options) {
         ...userTranspile,
         ...nudgeUiPackages.filter((name) => !userTranspile.includes(name)),
     ];
-    // --- Turbopack rules (primary compiler) ---------------------------------
     const turbopackRules = {
         ...(source.turbopack?.rules ?? {}),
     };
@@ -168,18 +135,12 @@ function instrumentConfig(config, options) {
                     loader: paths.plugin,
                     options: loaderOptions,
                 }],
-            // 'foreign' is Turbopack's builtin condition for dependency code, so
-            // `not: foreign` confines the loader to first-party sources. The path
-            // guard additionally keeps build output (.next) out of scope.
+            // 'foreign' marks dependency code in Turbopack; `not: foreign` plus the path guard confines the loader to first-party sources outside .next.
             condition: {
                 all: [
                     { not: "foreign" },
                     { not: { path: "(**/)?\\.next/**" } },
-                    // Workspace symlinks are NOT foreign (they are source-backed), so
-                    // the Nudge UI packages themselves must be excluded explicitly:
-                    // instrumenting the inspector's own UI would wrap every control in
-                    // override boundaries and pollute the panel with identity attrs.
-                    // The list is shared with the loader's runtime scope check.
+                    // Workspace symlinks are not 'foreign', so Nudge UI's own packages must be excluded explicitly or the inspector would instrument itself.
                     {
                         not: {
                             path: nudgeUiRepositoryPackagePath,
@@ -188,11 +149,7 @@ function instrumentConfig(config, options) {
                 ],
             },
         };
-        /**
-         * Rules are COMPOSED with any user rule for the same key by building a
-         * rule collection (Next supports arrays of items per glob) — silently
-         * overwriting host configuration is never acceptable.
-         */
+        /** Composed with any user rule for the same key: silently overwriting host configuration is never acceptable. */
         const compose = (key, rule) => {
             const existing = turbopackRules[key];
             if (existing === undefined) {
@@ -205,12 +162,8 @@ function instrumentConfig(config, options) {
         compose("*.tsx", { ...identityRule });
         compose("*.jsx", { ...identityRule });
     }
-    // --- Single React instance (ADR-0004 via module resolution) -------------
-    // Nudge UI packages carry their own react dependency for standalone
-    // consumers. Without an alias, SWC resolves their `react` imports against
-    // those copies while the host application runs its own — two Reacts in one
-    // document, and inspector state updates silently stop rendering. Aliasing
-    // to the host project's copies pins one instance for every compilation.
+    // Nudge UI carries its own react copy for standalone consumers; without an alias
+    // SWC loads both, and two Reacts in one document silently break inspector rendering.
     const hostReact = hostPackageDir(root, "react");
     const hostReactDom = hostPackageDir(root, "react-dom");
     const componentRuntime = adapterPackageExport("nudge-ui/internal/component-runtime");
@@ -234,7 +187,6 @@ function instrumentConfig(config, options) {
         ...(nextConfig.turbopack ?? {}),
         rules: turbopackRules,
     };
-    // --- Webpack mode (secondary target, Stage 6 verifies parity) ----------
     const userWebpack = source.webpack;
     nextConfig.webpack = (webpackConfig, context) => {
         const merged = userWebpack ? userWebpack(webpackConfig, context) : webpackConfig;
@@ -245,11 +197,8 @@ function instrumentConfig(config, options) {
         const userAlias = (resolveConfig.alias ?? {});
         const rules = Array.isArray(module.rules) ? [...module.rules] : [];
         const paths = loaderPaths();
-        // Next 16 removed the webpack CSS pipeline entirely
-        // (nextjs.org/docs/messages/built-in-css-disabled): applications using
-        // stylesheets cannot run under `next dev --webpack` on 16 at all,
-        // with or without Nudge UI. Registration stays so Next 15.x within
-        // the supported range keeps working; flag the combination loudly.
+        // Next 16 removed the webpack CSS pipeline entirely (nextjs.org/docs/messages/built-in-css-disabled);
+        // registration stays so Next 15.x works, and the combination is flagged loudly.
         const version = resolveNextVersion(root);
         if (version && Number(version.split(".")[0]) >= 16) {
             console.warn("[nudge-ui] Next.js " + version + " webpack dev mode has no CSS support "
@@ -279,7 +228,6 @@ function instrumentConfig(config, options) {
             module: { ...module, rules },
         };
     };
-    // --- Manifest transport rewrite ----------------------------------------
     const proxyRewrite = (port) => ({
         source: `${NUDGE_UI_ROUTE_PREFIX}:path*`,
         destination: `http://127.0.0.1:${port}${NUDGE_UI_ROUTE_PREFIX}:path*`,
@@ -306,9 +254,7 @@ function instrumentConfig(config, options) {
                 + "your rewrites also declare it and will be shadowed:", collisions);
         }
         return {
-            // Port 0 (sidecar failed to bind) yields a dead destination; the mount
-            // surfaces an honest fetch failure instead of silently pretending to
-            // work.
+            // Port 0 (failed sidecar) yields a dead destination: an honest fetch failure beats silently pretending to work.
             beforeFiles: [
                 proxyRewrite(port),
                 editorRewrite(port, { key: "accept", value: ".*text/html.*" }),
@@ -319,10 +265,7 @@ function instrumentConfig(config, options) {
             fallback: shape.fallback ?? [],
         };
     };
-    // Preserve callability while keeping our async resolver.
     nextConfig.rewrites = resolveRewrites;
-    // The structural view carries every original field through the spread;
-    // consumers keep their NextConfig typing via the generic passthrough.
     return nextConfig;
 }
 function nextDevelopmentOrigin() {

package/dist/hosts/projectBridge.d.ts

@@ -2,7 +2,6 @@ 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;
@@ -14,7 +13,6 @@ export declare function startOptionalProjectBridge(input: {
     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;

package/dist/hosts/projectBridge.js

@@ -6,12 +6,11 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
-import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, join, parse } from "node:path";
+import { join } from "node:path";
 import { pathToFileURL } from "node:url";
+import { findProjectMcpRoot } from "../project/mcpPackage.js";
 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);
@@ -28,7 +27,7 @@ export async function startOptionalProjectBridge(input) {
 async function launchOptionalProjectBridge(input, key) {
     let modulePath;
     try {
-        if (!isPnpRuntime() && !hasProjectInstalledMcp(input.appRoot)) {
+        if (findProjectMcpRoot(input.appRoot) === null) {
             runningBridges.delete(key);
             return null;
         }
@@ -73,21 +72,6 @@ async function launchOptionalProjectBridge(input, 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]"

package/dist/hosts/reactRendererCapture.d.ts

@@ -0,0 +1,2 @@
+/** Must run before the application's renderer loads; extends any existing DevTools hook and never replaces it. */
+export declare const REACT_RENDERER_CAPTURE_SCRIPT: string;

package/dist/hosts/reactRendererCapture.js

@@ -0,0 +1,12 @@
+/** Must run before the application's renderer loads; extends any existing DevTools hook and never replaces it. */
+export const REACT_RENDERER_CAPTURE_SCRIPT = [
+    "(function(w){",
+    "var h=w.__REACT_DEVTOOLS_GLOBAL_HOOK__;",
+    "if(!h){var n=0;h=w.__REACT_DEVTOOLS_GLOBAL_HOOK__={renderers:new Map(),supportsFiber:true,",
+    "inject:function(i){var id=n++;h.renderers.set(id,i);return id},",
+    "onScheduleFiberRoot:function(){},onCommitFiberRoot:function(){},onCommitFiberUnmount:function(){}};return}",
+    "if(h.__nudgeUiRendererCapture||typeof h.inject!=='function'||!(h.renderers instanceof Map))return;",
+    "h.__nudgeUiRendererCapture=true;var inject=h.inject;",
+    "h.inject=function(i){var id=inject.apply(this,arguments);if(!h.renderers.has(id))h.renderers.set(id,i);return id}",
+    "})(window);",
+].join("");

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

@@ -1,12 +1,8 @@
-/** Parsed arguments for `nudge-ui serve`. */
 export interface ServeCommandOptions {
     readonly rootDirectory: string;
     readonly host: "127.0.0.1" | "::1" | "localhost";
     readonly port: number;
 }
-/** Parses the standalone CLI's intentionally small command surface. */
 export declare function parseServeArguments(args: readonly string[], currentDirectory?: string): ServeCommandOptions;
-/** 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[], packageVersion?: string): Promise<void>;