nudge-ui 0.2.4 → 0.2.6

package/dist/hosts/static/cli.js

@@ -1,7 +1,6 @@
 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()) {
     if (args[0] !== "serve") {
         throw new Error("Usage: nudge-ui serve [directory] [--port <port>] [--host <loopback>]");
@@ -37,14 +36,12 @@ export function parseServeArguments(args, currentDirectory = process.cwd()) {
     }
     return { rootDirectory: resolve(currentDirectory, directory), host, port };
 }
-/** Starts the CLI server and waits until the process receives a termination signal. */
 export async function runServeCommand(options) {
     const server = createStandaloneServer(options);
     const address = await server.start();
     console.log(`Nudge UI serving ${server.rootDirectory} at ${address.url}`);
     await waitForTermination(server);
 }
-/** Runs the standalone command. */
 export async function main(args = process.argv.slice(2), packageVersion) {
     if (args[0] === "agent") {
         runAgentCommand(args.slice(1), packageVersion);

package/dist/hosts/static/html/bootstrap.d.ts

@@ -1,27 +1,10 @@
-/** Options for source-preserving standalone bootstrap injection. */
 export interface StandaloneBootstrapOptions {
-    /** The browser client URL. */
     readonly clientPath?: string;
-    /** The runtime manifest URL passed to the browser client. */
     readonly manifestPath?: string;
 }
-/** The result of injecting the standalone bootstrap into one HTML response. */
 export interface StandaloneBootstrapResult {
-    /** The response source after any missing bootstrap nodes are inserted. */
     readonly html: string;
-    /** Whether at least one node was inserted. */
     readonly injected: boolean;
 }
-/**
- * Adds the standalone mount and external client script to an HTML response.
- *
- * The function only inserts text at an existing HTML boundary. It does not
- * parse and reserialize the document, so authored bytes remain unchanged
- * except for the server-owned nodes. Marker checks make a second response
- * pass idempotent.
- *
- * @param html The transformed HTML response body.
- * @param options Bootstrap URLs and mount identity.
- * @returns The response body and whether anything was added.
- */
+/** Inserts text at an existing boundary rather than reserializing, and marker checks make a second pass idempotent. */
 export declare function injectStandaloneBootstrap(html: string, options?: StandaloneBootstrapOptions): StandaloneBootstrapResult;

package/dist/hosts/static/html/bootstrap.js

@@ -2,18 +2,7 @@ import { NUDGE_UI_CLIENT_PATH, NUDGE_UI_MOUNT_ID, NUDGE_UI_MANIFEST_PATH, } from
 import { parse } from "parse5";
 const CLIENT_MARKER = "data-nudge-ui-client";
 const MOUNT_MARKER = "data-nudge-ui-mount";
-/**
- * Adds the standalone mount and external client script to an HTML response.
- *
- * The function only inserts text at an existing HTML boundary. It does not
- * parse and reserialize the document, so authored bytes remain unchanged
- * except for the server-owned nodes. Marker checks make a second response
- * pass idempotent.
- *
- * @param html The transformed HTML response body.
- * @param options Bootstrap URLs and mount identity.
- * @returns The response body and whether anything was added.
- */
+/** Inserts text at an existing boundary rather than reserializing, and marker checks make a second pass idempotent. */
 export function injectStandaloneBootstrap(html, options = {}) {
     const clientPath = options.clientPath ?? NUDGE_UI_CLIENT_PATH;
     const manifestPath = options.manifestPath ?? NUDGE_UI_MANIFEST_PATH;
@@ -60,8 +49,7 @@ function inspectSource(document, clientPath) {
         if (tagName === "html" && endOffset !== undefined)
             facts.htmlEndOffset = endOffset;
     });
-    // Only live body descendants can reserve the mount. Template content is
-    // inert and must not suppress injection into the document.
+    // Template content is inert, so only live body descendants can reserve the mount.
     if (body) {
         visitElements(body, (element) => {
             if (element !== body && attributeValue(element, "id") === NUDGE_UI_MOUNT_ID) {

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

@@ -1,18 +1,5 @@
-import type { NudgeUiClientManifest } from "../../inspector/clientManifest.js";
+import { type NudgeUiClientManifest } from "../../inspector/clientManifest.js";
 import type { ProjectTokenSnapshot } from "../../project/tokens.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 {
-}
-/**
- * Creates the first valid static-HTML runtime snapshot.
- *
- * Stage 4 replaces the empty token arrays with the CSS token-inventory
- * snapshot. Keeping this constructor here makes the manifest contract
- * explicit and prevents the server from manufacturing a partial runtime
- * configuration.
- *
- * @param projectId The deterministic identity of the served project.
- * @returns A complete runtime manifest with no framework contracts or tokens.
- */
+export type StandaloneRuntimeManifest = NudgeUiClientManifest;
 export declare function createStandaloneRuntimeManifest(projectId: string, tokenSnapshot?: ProjectTokenSnapshot, revision?: number): StandaloneRuntimeManifest;

package/dist/hosts/static/manifest.js

@@ -1,29 +1,16 @@
-import { NUDGE_UI_MANIFEST_VERSION, NUDGE_UI_RELOAD_PATH } from "../../transport/index.js";
+import { createNudgeUiClientManifest, } from "../../inspector/clientManifest.js";
+import { 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.
- *
- * Stage 4 replaces the empty token arrays with the CSS token-inventory
- * snapshot. Keeping this constructor here makes the manifest contract
- * explicit and prevents the server from manufacturing a partial runtime
- * configuration.
- *
- * @param projectId The deterministic identity of the served project.
- * @returns A complete runtime manifest with no framework contracts or tokens.
- */
 export function createStandaloneRuntimeManifest(projectId, tokenSnapshot = emptyTokenSnapshot(), revision = 0) {
-    return {
-        version: NUDGE_UI_MANIFEST_VERSION,
+    return createNudgeUiClientManifest({
         revision,
         runtime: {
             projectId,
             host: "static-html",
             framework: "HTML",
             stylingSystem: "CSS custom properties",
-            // 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.
+            // Canvas shares the Vite host's controller/renderer runtime (ADR-0012).
             capabilities: { canvas: true, componentSemantics: false, domNavigation: true },
             tokenCatalog: tokenSnapshot.tokenCatalog,
             tokens: tokenSnapshot.tokens,
@@ -41,7 +28,7 @@ export function createStandaloneRuntimeManifest(projectId, tokenSnapshot = empty
             events: ["ready", "reload"],
         },
         ...automationManifestFields(),
-    };
+    });
 }
 function emptyTokenSnapshot() {
     return {

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

@@ -1,34 +1,27 @@
 import { type Server } from "node:http";
 import { type StandaloneRuntimeManifest } from "./manifest.js";
-/** Options for the loopback-only standalone static server. */
+import { isReservedNudgeUiRoute } from "../../transport/index.js";
+export { isReservedNudgeUiRoute };
 export interface StandaloneServerOptions {
     /** The explicit directory whose files may be served. */
     readonly rootDirectory: string;
-    /** The loopback address to bind. Defaults to `127.0.0.1`. */
     readonly host?: "127.0.0.1" | "::1" | "localhost";
-    /** The TCP port. Use `0` to ask the operating system for an available port. */
     readonly port?: number;
-    /** The prebuilt browser client artifact. */
     readonly clientPath?: string;
     /** Override the deterministic project identity in tests or embedding hosts. */
     readonly projectId?: string;
     /** Debounce interval for source changes before one reload revision. */
     readonly watchDebounceMs?: number;
 }
-/** A canonical file resolved below the configured project root. */
 export interface StaticFileResolution {
-    /** The canonical file path on disk. */
     readonly absolutePath: string;
-    /** The slash-separated project-relative path used for source identity. */
     readonly projectPath: string;
 }
-/** The address returned after the server starts listening. */
 export interface StandaloneServerAddress {
     readonly host: string;
     readonly port: number;
     readonly url: string;
 }
-/** The running standalone server and its lifecycle methods. */
 export interface StandaloneServer {
     readonly httpServer: Server;
     readonly rootDirectory: string;
@@ -37,36 +30,9 @@ export interface StandaloneServer {
     start(): Promise<StandaloneServerAddress>;
     close(): Promise<void>;
 }
-/**
- * Creates a Nudge UI-owned static server for one explicit project root.
- *
- * The server binds to loopback, reserves its own route namespace, and only
- * reads prototype files. HTML instrumentation and bootstrap nodes exist in
- * response memory; the configured source directory is never rewritten.
- *
- * @param options Server root, address, port, and client artifact options.
- * @returns A server that has not started listening yet.
- * @throws If the root is missing, not a directory, or the host is not loopback.
- */
+/** Serves one explicit project root over loopback, reserving its own route namespace; the configured source directory is never rewritten. */
 export declare function createStandaloneServer(options: StandaloneServerOptions): StandaloneServer;
-/**
- * Resolves one URL pathname to a canonical file under the project root.
- *
- * URL decoding occurs before path normalization, which makes encoded dot
- * segments subject to the same confinement check as ordinary traversal. The
- * canonical existing ancestor check also rejects a symlink that escapes the
- * root when the requested leaf does not yet exist. Hidden path segments are
- * refused, including encoded and multiply encoded forms, and a visible
- * symlink cannot be used to reach a hidden target.
- *
- * @param rootDirectory The configured project root.
- * @param requestPath A request target or URL pathname.
- * @returns A file resolution, or `null` for malformed, missing, or unsafe paths.
- */
+/** Decodes before normalizing so encoded dot segments face the same confinement check; the canonical-ancestor check also rejects escaping symlinks. */
 export declare function resolveStaticFile(rootDirectory: string, requestPath: string): StaticFileResolution | null;
-/** Returns the deterministic project identity used for session persistence. */
 export declare function createStandaloneProjectId(rootDirectory: string): string;
-/** Returns a common response content type for a project-relative file. */
 export declare function contentTypeForPath(filePath: string): string;
-/** Returns whether a decoded pathname belongs to the server-owned route space. */
-export declare function isReservedNudgeUiRoute(pathname: string): boolean;

package/dist/hosts/static/server.js

@@ -8,7 +8,9 @@ import { createRequire } from "node:module";
 import { instrumentSourceHtml } from "../../html/identity.js";
 import { injectStandaloneBootstrap } from "./html/bootstrap.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 { createStandaloneRuntimeManifest, NUDGE_UI_CLIENT_PATH, NUDGE_UI_EDITOR_PATH, NUDGE_UI_MANIFEST_PATH, NUDGE_UI_RELOAD_PATH, } from "./manifest.js";
+import { isReservedNudgeUiRoute } from "../../transport/index.js";
+export { isReservedNudgeUiRoute };
 import { startOptionalProjectBridge } from "../projectBridge.js";
 import { createProjectTokenSnapshot, EMPTY_PROJECT_TOKEN_SNAPSHOT } from "../../project/tokens.js";
 import { createProjectFileWatcher, isSensitiveProjectPath, } from "../../project/files.js";
@@ -16,17 +18,7 @@ const LOOPBACK_HOSTS = new Set(["127.0.0.1", "::1", "localhost"]);
 const HTML_EXTENSIONS = new Set([".html", ".htm"]);
 const DEFAULT_PORT = 4173;
 const packageRequire = createRequire(import.meta.url);
-/**
- * Creates a Nudge UI-owned static server for one explicit project root.
- *
- * The server binds to loopback, reserves its own route namespace, and only
- * reads prototype files. HTML instrumentation and bootstrap nodes exist in
- * response memory; the configured source directory is never rewritten.
- *
- * @param options Server root, address, port, and client artifact options.
- * @returns A server that has not started listening yet.
- * @throws If the root is missing, not a directory, or the host is not loopback.
- */
+/** Serves one explicit project root over loopback, reserving its own route namespace; the configured source directory is never rewritten. */
 export function createStandaloneServer(options) {
     const rootDirectory = canonicalDirectory(options.rootDirectory);
     const host = options.host ?? "127.0.0.1";
@@ -40,14 +32,12 @@ export function createStandaloneServer(options) {
     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.
+    // start() awaits the initial scan so the first request observes complete token knowledge.
     const initialTokens = createProjectTokenSnapshot({ rootDirectory, generationLabel: "static-html" }).then((tokens) => {
         manifest = createStandaloneRuntimeManifest(projectId, tokens, revision);
         return tokens;
     });
-    // start() awaits and surfaces scan failures; this second handler only
-    // prevents an unhandled rejection when a server is created but never started.
+    // Prevents an unhandled rejection when a server is created but never started.
     void initialTokens.catch(() => undefined);
     const reloadClients = new Set();
     let fileWatcher = null;
@@ -77,10 +67,8 @@ export function createStandaloneServer(options) {
     };
     const processSettledChanges = (_changes) => {
         changeQueue = changeQueue.then(async () => {
-            // Rebuild every settled batch. fs.watch can report a directory or omit a
-            // filename, so an extension check cannot reliably identify CSS changes.
-            // The scan is asynchronous and bounded to the project root; rebuilding
-            // once per settled batch keeps the manifest coherent before reload.
+            // fs.watch can omit a filename, so CSS changes cannot be identified by extension:
+            // rebuild once per settled batch to keep the manifest coherent before reload.
             const tokens = await createProjectTokenSnapshot({ rootDirectory, generationLabel: "static-html" });
             manifest = {
                 ...createStandaloneRuntimeManifest(projectId, tokens, revision + 1),
@@ -89,9 +77,7 @@ export function createStandaloneServer(options) {
             revision += 1;
             notifyReload();
         }).catch((error) => {
-            // A later settled batch can still rebuild the snapshot after a failed
-            // callback. Source edits must not terminate the static server, but a
-            // skipped reload must be visible to the developer.
+            // A failed rebuild must not terminate the server, but a skipped reload must stay visible.
             console.warn("Nudge UI standalone reload was skipped because rebuilding token knowledge failed:", error);
         });
     };
@@ -218,20 +204,7 @@ export function createStandaloneServer(options) {
     };
     return server;
 }
-/**
- * Resolves one URL pathname to a canonical file under the project root.
- *
- * URL decoding occurs before path normalization, which makes encoded dot
- * segments subject to the same confinement check as ordinary traversal. The
- * canonical existing ancestor check also rejects a symlink that escapes the
- * root when the requested leaf does not yet exist. Hidden path segments are
- * refused, including encoded and multiply encoded forms, and a visible
- * symlink cannot be used to reach a hidden target.
- *
- * @param rootDirectory The configured project root.
- * @param requestPath A request target or URL pathname.
- * @returns A file resolution, or `null` for malformed, missing, or unsafe paths.
- */
+/** Decodes before normalizing so encoded dot segments face the same confinement check; the canonical-ancestor check also rejects escaping symlinks. */
 export function resolveStaticFile(rootDirectory, requestPath) {
     const root = canonicalDirectoryOrNull(rootDirectory);
     if (!root)
@@ -274,21 +247,14 @@ function resolveDecodedStaticFile(root, decodedPath) {
         return null;
     return { absolutePath: filePath, projectPath: relativePath };
 }
-/** Returns the deterministic project identity used for session persistence. */
 export function createStandaloneProjectId(rootDirectory) {
     const canonicalRoot = canonicalDirectory(rootDirectory);
     const digest = createHash("sha256").update(canonicalRoot).digest("hex").slice(0, 24);
     return `static-html:${digest}`;
 }
-/** Returns a common response content type for a project-relative file. */
 export function contentTypeForPath(filePath) {
     const extension = extname(filePath).toLowerCase();
-    return MIME_TYPES[extension] ?? "application/octet-stream";
-}
-/** Returns whether a decoded pathname belongs to the server-owned route space. */
-export function isReservedNudgeUiRoute(pathname) {
-    return pathname === NUDGE_UI_ROUTE_PREFIX.slice(0, -1)
-        || pathname.startsWith(NUDGE_UI_ROUTE_PREFIX);
+    return MIME_TYPES.get(extension) ?? "application/octet-stream";
 }
 function canonicalDirectory(directory) {
     const canonical = canonicalDirectoryOrNull(directory);
@@ -327,12 +293,7 @@ function decodeRequestPath(requestPath) {
         return null;
     return pathname;
 }
-/**
- * Detects suspicious paths that become hidden or traversal paths after a
- * second URL decode. The server resolves request URLs exactly once so literal
- * percent-containing filenames continue to work, but nested encodings must
- * not provide an alternate spelling for a sensitive path.
- */
+/** Request URLs are decoded exactly once, so a second decode must not yield an alternate spelling of a sensitive path. */
 function hasNestedUnsafePathEncoding(pathname) {
     let candidate = pathname;
     for (let depth = 0; depth < 5; depth += 1) {
@@ -414,11 +375,8 @@ async function handleRequest(input) {
     const isHtml = HTML_EXTENSIONS.has(extname(resolution.projectPath).toLowerCase());
     const contentType = contentTypeForPath(resolution.projectPath);
     if (request.method === "HEAD") {
-        // HEAD answers headers without running the response transform: the body
-        // would be discarded anyway, and the instrumented GET length cannot be
-        // known without performing it. Content-Length is omitted for HTML so the
-        // header cannot disagree with a subsequent GET body; untransformed files
-        // report their exact length.
+        // HEAD answers headers without the response transform; Content-Length is omitted for
+        // HTML so it cannot disagree with a subsequent GET body.
         const body = await readProjectFile(resolution.absolutePath);
         if (isHtml) {
             response.writeHead(200, {
@@ -439,15 +397,7 @@ async function handleRequest(input) {
     }
     sendBody(response, 200, body, contentType, isHtml ? { "Cache-Control": "no-cache" } : {});
 }
-/**
- * Instruments one HTML response while guaranteeing byte preservation.
- *
- * The identity inserter only edits the decoded string at parser offsets, so
- * the decode itself must be lossless. A non-UTF-8 document cannot round-trip
- * through `toString("utf8")` without replacing every invalid sequence with
- * U+FFFD, so such documents are served untouched with a warning instead of
- * being silently corrupted.
- */
+/** Served untouched when not valid UTF-8: identity insertion works at parser offsets, so a lossy decode would corrupt the document. */
 function instrumentHtmlResponse(body, projectPath) {
     let source;
     try {
@@ -570,7 +520,7 @@ function sendBody(response, status, body, contentType, headers = {}) {
     else
         response.end();
 }
-const MIME_TYPES = {
+const MIME_TYPES = new Map(Object.entries({
     ".avif": "image/avif",
     ".css": "text/css; charset=utf-8",
     ".csv": "text/csv; charset=utf-8",
@@ -596,4 +546,4 @@ const MIME_TYPES = {
     ".woff": "font/woff",
     ".woff2": "font/woff2",
     ".xml": "application/xml; charset=utf-8",
-};
+}));

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

@@ -1,16 +1,6 @@
 import type { Plugin, UserConfigExport } from "vite";
 import { type NudgeUiOptions } from "./vite.js";
-/**
- * Composes two independent halves: `./vite.ts` owns the build tool and knows
- * nothing about JSX, `./react.ts` owns React and knows nothing about Vite.
- * This is deliberately the only file that names both.
- */
 export declare function nudgeUi(options?: NudgeUiOptions): Plugin[];
-/**
- * Adds this host to an existing Vite configuration export. Object, promise,
- * and function forms are resolved at the same boundary Vite uses, so the host
- * keeps ownership of its runtime root and dependency graph.
- */
 export declare function withNudgeUi(config: UserConfigExport, options?: NudgeUiOptions): UserConfigExport;
 export type { NudgeUiOptions, VanillaExtractOptions } from "./vite.js";
 export { extractViteModuleCss, transformIndexHtmlHtml } from "./vite.js";

package/dist/hosts/vite/index.js

@@ -1,18 +1,8 @@
 import { createVitePlugins } from "./vite.js";
 import { createReactSupport } from "./react.js";
-/**
- * Composes two independent halves: `./vite.ts` owns the build tool and knows
- * nothing about JSX, `./react.ts` owns React and knows nothing about Vite.
- * This is deliberately the only file that names both.
- */
 export function nudgeUi(options = {}) {
     return createVitePlugins(options, createReactSupport);
 }
-/**
- * Adds this host to an existing Vite configuration export. Object, promise,
- * and function forms are resolved at the same boundary Vite uses, so the host
- * keeps ownership of its runtime root and dependency graph.
- */
 export function withNudgeUi(config, options = {}) {
     if (typeof config === "function") {
         // SAFETY: The typeof guard selects the function form of UserConfigExport, whose signature this cast states.

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

@@ -3,42 +3,32 @@ import { injectIdentity } from "../../compiler/reactIdentity.js";
 import type { ComponentContract } from "../../compiler/index.js";
 import { type ComponentInstrumentationOptions, type ComponentModuleProtocols } from "../../compiler/index.js";
 export interface ReactOptions {
-    /**
-     * Skip the React aliases used only by the legacy bundled landing demo.
-     * @deprecated Normal development clients no longer add React aliases.
-     */
+    /** @deprecated Normal development clients no longer add React aliases. */
     skipReactAliases?: boolean;
     /** Fills gaps for packages whose public type graph cannot describe an editable prop. */
     componentMetadata?: ComponentContract[];
     /** Package imports are fail-closed unless listed here or described by a component protocol. */
     compatibleComponentImports?: ComponentInstrumentationOptions["compatibleComponentImports"];
-    /** Additional package or project component protocols resolved by the host. */
     componentProtocols?: ComponentModuleProtocols;
 }
-/** Everything React needs from whichever host is driving it. */
 export interface FrameworkHost {
     root(): string | undefined;
-    /** True when a module belongs to the application rather than a dependency. */
     isHostSource(id: string): boolean;
     /** The project-relative path recorded in contracts and diagnostics. */
     catalogPath(id: string): string;
 }
-/** The parts of a transform hook React uses, named without the build tool. */
 export interface FrameworkTransformContext {
     resolve(specifier: string, importer: string): Promise<string | null>;
     warn(message: string): void;
 }
 export declare function createReactSupport(options: ReactOptions, host: FrameworkHost): {
-    /** Manifest labels for a host composing React. */
     hostLabel: "vite-react";
     framework: "React";
     virtualModuleId: string;
+    /** Lets live preview reach React's renderer, which loads before any module the host controls. */
+    documentHeadScript: string;
     owns(id: string): boolean;
-    /**
-     * Dedupe is the load-bearing part: instrumented callsites must use the
-     * application's own React, and a linked or nested copy would create a
-     * second runtime.
-     */
+    /** Dedupe is load-bearing: instrumented callsites must use the application's own React, not a linked or nested copy. */
     viteConfig(context: {
         projectRoot: string;
         demo: boolean;
@@ -54,14 +44,11 @@ export declare function createReactSupport(options: ReactOptions, host: Framewor
     };
     /** Not fatal, but a packed install that cannot resolve it fails later at the importing module. */
     unresolvedRuntimeWarning(): string | null;
-    /** Cold-start scan, so the first manifest is not missing every contract. */
     warmUp(): void;
     observe(id: string, code: string, refreshPackages?: boolean): void;
-    /** Drops a module whose source could not be read after a change. */
     forget(id: string): void;
     transform(context: FrameworkTransformContext, code: string, id: string): Promise<ReturnType<typeof injectIdentity>>;
     contracts(): ComponentContract[];
     serializeVirtualModule(contracts: readonly ComponentContract[]): string;
 };
-/** The framework support a host composes, or `null` for no framework at all. */
 export type FrameworkSupport = ReturnType<typeof createReactSupport>;

package/dist/hosts/vite/react.js

@@ -3,25 +3,19 @@ import { createRequire } from "node:module";
 import { join } from "node:path";
 import { injectIdentity } from "../../compiler/reactIdentity.js";
 import { extractComponentContracts } from "../../compiler/componentContracts.js";
-import { collectPackageComponentModules, extractPackageComponentContractCatalog, } from "../../compiler/packageComponentContracts.js";
+import { collectPackageComponentImports, extractPackageComponentContractCatalog, } from "../../compiler/packageComponentContracts.js";
+import { REACT_RENDERER_CAPTURE_SCRIPT } from "../reactRendererCapture.js";
 import { defaultReactComponentProtocols, formatComponentPolicyWarning, groupComponentPolicyDiagnostics, mergeComponentModuleProtocols, resolveHostComponentPolicy, } from "../../compiler/index.js";
-/**
- * What React means to a host, with no knowledge of which host is asking. The
- * Vite host owns the build tool; this module owns React semantics. `FrameworkHost`
- * is everything React needs back, and the Vite host accepts `null` in its place,
- * which is what proves it does not secretly depend on any of this.
- */
 const COMPONENT_EXTENSION = /\.(?:tsx|jsx)(?:$|[?#])/;
 const COMPONENT_RUNTIME_MODULE = "nudge-ui/internal/component-runtime";
 const packageRequire = createRequire(import.meta.url);
 export function createReactSupport(options, host) {
     const contractsByFile = new Map();
-    const packageModulesByFile = new Map();
+    const packageImportsByFile = new Map();
     const reportedPolicyDiagnostics = new Set();
     const manualComponentIds = new Set(options.componentMetadata?.map((contract) => contract.componentId) ?? []);
     let packageFingerprint = "";
-    // Aliased so the injected specifier resolves in a packed install, where the
-    // application's dependency graph has never heard of it.
+    // Aliased so the injected specifier resolves in a packed install, where the application's graph has never heard of it.
     const componentRuntimePath = resolveComponentRuntime();
     if (options.componentMetadata?.length) {
         contractsByFile.set("package-manifests", options.componentMetadata.map((contract) => ({
@@ -29,22 +23,15 @@ export function createReactSupport(options, host) {
             provenance: "package-manifest",
         })));
     }
-    /**
-     * Fingerprinted on the module-to-importer mapping so an unchanged import
-     * graph costs nothing; every component edit reaches this path.
-     */
+    /** Fingerprinted on the rendered package exports, so an unchanged import graph costs nothing. */
     function refreshPackageContracts() {
-        const hostByModule = new Map();
-        for (const [hostFile, modules] of [...packageModulesByFile].sort(([left], [right]) => left.localeCompare(right))) {
-            for (const moduleSpecifier of modules) {
-                if (!hostByModule.has(moduleSpecifier))
-                    hostByModule.set(moduleSpecifier, hostFile);
+        const importsByKey = new Map();
+        for (const imports of packageImportsByFile.values()) {
+            for (const packageImport of imports) {
+                importsByKey.set(`${packageImport.moduleSpecifier}#${packageImport.exportName}`, packageImport);
             }
         }
-        const fingerprint = [...hostByModule]
-            .sort(([left], [right]) => left.localeCompare(right))
-            .map(([moduleSpecifier, hostFile]) => `${moduleSpecifier}\0${hostFile}`)
-            .join("\n");
+        const fingerprint = [...importsByKey.keys()].sort().join("\n");
         if (fingerprint === packageFingerprint)
             return;
         for (const key of [...contractsByFile.keys()]) {
@@ -55,27 +42,25 @@ export function createReactSupport(options, host) {
         const catalog = root
             ? extractPackageComponentContractCatalog({
                 hostFile: join(root, "__nudge_ui_package_contracts__.tsx"),
-                moduleSpecifiers: [...hostByModule.keys()],
+                imports: [...importsByKey.values()],
             })
             : [];
-        for (const moduleSpecifier of hostByModule.keys()) {
+        const moduleSpecifiers = new Set([...importsByKey.values()].map((entry) => entry.moduleSpecifier));
+        for (const moduleSpecifier of moduleSpecifiers) {
             contractsByFile.set(`package-types:${moduleSpecifier}`, catalog.filter((contract) => contract.file === moduleSpecifier && !manualComponentIds.has(contract.componentId)));
         }
         packageFingerprint = fingerprint;
     }
     return {
-        /** Manifest labels for a host composing React. */
         hostLabel: "vite-react",
         framework: "React",
         virtualModuleId: "virtual:nudge-ui-components",
+        /** Lets live preview reach React's renderer, which loads before any module the host controls. */
+        documentHeadScript: REACT_RENDERER_CAPTURE_SCRIPT,
         owns(id) {
             return COMPONENT_EXTENSION.test(id);
         },
-        /**
-         * Dedupe is the load-bearing part: instrumented callsites must use the
-         * application's own React, and a linked or nested copy would create a
-         * second runtime.
-         */
+        /** Dedupe is load-bearing: instrumented callsites must use the application's own React, not a linked or nested copy. */
         viteConfig(context) {
             const demoAliases = context.demo && options.skipReactAliases !== true
                 ? resolveReactAliases(context.projectRoot)
@@ -105,7 +90,6 @@ export function createReactSupport(options, host) {
             return `[nudge-ui] Could not resolve ${COMPONENT_RUNTIME_MODULE} from the Vite adapter. `
                 + "Semantic component callsites will fall back to application resolution of that specifier.";
         },
-        /** Cold-start scan, so the first manifest is not missing every contract. */
         warmUp() {
             const root = host.root();
             if (!root)
@@ -125,14 +109,13 @@ export function createReactSupport(options, host) {
                 return;
             const fileId = id.split(/[?#]/, 1)[0] ?? id;
             contractsByFile.set(fileId, extractComponentContracts(code, host.catalogPath(fileId)));
-            packageModulesByFile.set(fileId, collectPackageComponentModules(code, fileId));
+            packageImportsByFile.set(fileId, collectPackageComponentImports(code, fileId));
             if (refreshPackages)
                 refreshPackageContracts();
         },
-        /** Drops a module whose source could not be read after a change. */
         forget(id) {
             contractsByFile.set(id, []);
-            packageModulesByFile.delete(id);
+            packageImportsByFile.delete(id);
             refreshPackageContracts();
         },
         async transform(context, code, id) {

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

@@ -1,8 +1,3 @@
-/**
- * The token catalog must follow only stylesheets the application imports. This
- * small graph walker deliberately has no filesystem traversal: callers supply
- * the host CSS entry files, a Vite-backed resolver, and a reader.
- */
 export interface CssImportGraph {
     files: Map<string, string>;
     /** CSS cascade order: imported sheets precede the sheet that imports them. */
@@ -19,10 +14,6 @@ export interface CssImportGraphDependencies {
 }
 export declare function stripCssQuery(id: string): string;
 export declare function isCssStylesheet(id: string): boolean;
-/** Extract quoted and url(...) @import targets while ignoring CSS comments. */
 export declare function cssImportSpecifiers(css: string): string[];
-/**
- * Resolve every CSS file reached from the supplied host stylesheets. Missing
- * and unreadable imports are reported but never make the catalog unavailable.
- */
+/** Missing and unreadable imports are reported, never fatal to the catalog. */
 export declare function discoverCssImportGraph(entryFiles: readonly string[], dependencies: CssImportGraphDependencies): Promise<CssImportGraph>;