nudge-ui 0.2.4 → 0.2.6

package/dist/hosts/vite/tokens/activeStylesheets.js

@@ -4,7 +4,6 @@ export function stripCssQuery(id) {
 export function isCssStylesheet(id) {
     return /\.css(?:$|[?#])/i.test(id);
 }
-/** Extract quoted and url(...) @import targets while ignoring CSS comments. */
 export function cssImportSpecifiers(css) {
     const withoutComments = css.replace(/\/\*[\s\S]*?\*\//g, "");
     const imports = [];
@@ -17,10 +16,7 @@ export function cssImportSpecifiers(css) {
     }
     return imports;
 }
-/**
- * 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 async function discoverCssImportGraph(entryFiles, dependencies) {
     const files = new Map();
     const order = [];
@@ -54,9 +50,8 @@ export async function discoverCssImportGraph(entryFiles, dependencies) {
                 unresolved.push({ importer: fileId, specifier });
                 continue;
             }
-            // A processor-owned import such as Tailwind's package entry may resolve
-            // to JavaScript and later emit CSS during transform. It is outside this
-            // ordinary-CSS graph, but it is not an unresolved stylesheet failure.
+            // A processor-owned import such as Tailwind's package entry may resolve to JavaScript
+            // and emit CSS during transform; it is outside this graph, not an unresolved failure.
             if (!isCssStylesheet(resolved))
                 continue;
             await visit(resolved);

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

@@ -1,2 +1 @@
-/** A string-keyed file map used in CSS import graph tests. */
 export type FileMap = Record<string, string>;

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

@@ -1,14 +1,6 @@
 import type { ArtifactStage, StylesheetArtifact } from "../../../css/token-inventory/index.js";
 import type { CssImportGraph } from "./activeStylesheets.js";
-/**
- * Source directories that a Vite host explicitly owns.
- *
- * Vite's resolved root is always included by the adapter. `sourceRoots` lets a
- * monorepo host add authored workspace packages without treating every file
- * reachable through Vite's module graph as application code. Generated roots
- * are excluded even when a caller accidentally includes them in a source
- * root.
- */
+/** Vite's resolved root is always included; generated roots are excluded even when nested in a source root. */
 export interface ViteSourceScopeOptions {
     readonly sourceRoots?: readonly string[];
     readonly generatedRoots?: readonly string[];
@@ -30,7 +22,6 @@ export interface ViteStylesheetArtifactInput {
     /** Explicit graph-level v4 detection avoids mistaking Tailwind v3 --tw helpers for v4. */
     readonly tailwindV4?: boolean;
 }
-/** Map Vite-specific identity and evidence into the neutral artifact contract. */
 export declare function createViteStylesheetArtifact(input: ViteStylesheetArtifactInput): StylesheetArtifact;
 export interface OrderedViteStylesheet {
     readonly id: string;
@@ -38,9 +29,5 @@ export interface OrderedViteStylesheet {
     readonly order?: number;
     readonly discoveryOrder?: number;
 }
-/**
- * A single active root proves nested CSS import order. Multiple independent
- * roots have no proven cross-root cascade order, so their traversal rank stays
- * discovery evidence.
- */
+/** A single active root proves nested CSS import order; multiple roots have no cross-root cascade order, so their rank stays discovery evidence. */
 export declare function orderViteStylesheetGraph(graph: CssImportGraph, activeRootCount: number): OrderedViteStylesheet[];

package/dist/hosts/vite/tokens/viteStylesheetArtifacts.js

@@ -32,10 +32,8 @@ export function isHostApplicationSource(id, projectRoot, options = {}) {
     const sourceRoot = roots.find((candidate) => isInsideRoot(absoluteFile, candidate));
     if (!sourceRoot)
         return false;
-    // A generated directory can be nested in an authored workspace package, so a
-    // declared source root keeps a conservative name-based guard. The primary
-    // root does not: there, a directory named `build` may be ordinary authored
-    // source, and the resolved output directory is already excluded above.
+    // A declared source root keeps a name-based guard against nested generated directories;
+    // the primary root does not, since a directory named `build` may be authored source there.
     if (sourceRoot !== primaryRoot) {
         const pathSegments = relative(sourceRoot, absoluteFile).split(sep).filter(Boolean);
         if (pathSegments.some((segment) => GENERATED_DIRECTORY_NAMES.has(segment))) {
@@ -60,7 +58,6 @@ export function catalogSourcePath(id, projectRoot, options = {}) {
         return relative(projectRoot, fileId).replace(/\\/g, "/");
     return fileId.replace(/^\//, "");
 }
-/** Map Vite-specific identity and evidence into the neutral artifact contract. */
 export function createViteStylesheetArtifact(input) {
     const fileId = stripCssQuery(input.id);
     // The artifact input already carries the scope fields, so it is the scope.
@@ -89,11 +86,7 @@ function isInsideRoot(file, root) {
         && !relativeFile.startsWith(`..${sep}`)
         && !isAbsolute(relativeFile);
 }
-/**
- * A single active root proves nested CSS import order. Multiple independent
- * roots have no proven cross-root cascade order, so their traversal rank stays
- * discovery evidence.
- */
+/** A single active root proves nested CSS import order; multiple roots have no cross-root cascade order, so their rank stays discovery evidence. */
 export function orderViteStylesheetGraph(graph, activeRootCount) {
     const authoritative = activeRootCount === 1;
     return graph.order.map((id, index) => ({

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

@@ -2,19 +2,12 @@ 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
- * is a host capability, so the specifier lives here; what the contract means
- * is interpreted in `nudge-ui/css/dialects`.
- */
 export interface VanillaExtractOptions {
     themeContract?: ThemeContract;
     /** A Vite-resolvable module exporting a published compiled contract. */
     themeContractModule?: string;
-    /** Defaults to `vars`. */
     themeContractExport?: string;
     themeContractPrefix?: string;
-    /** Known compiled values by custom-property name. */
     cssValues?: Readonly<Record<string, string>>;
     source?: string;
 }
@@ -29,7 +22,7 @@ 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. */
+    /** 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;
@@ -39,32 +32,18 @@ export interface NudgeUiOptions extends ReactOptions {
         source?: string;
     };
     vanillaExtract?: VanillaExtractOptions;
-    /**
-     * Authored workspace directories outside Vite's resolved root. Dependencies
-     * and generated output stay excluded even when a broad directory is given.
-     */
+    /** Authored workspace directories outside Vite's resolved root; dependencies and generated output stay excluded. */
     sourceRoots?: readonly string[];
 }
-/**
- * Extracts the stylesheet string Vite embeds in dev CSS-module JS wrappers
- * (`const __vite__css = "…"`). Returns null for anything that is not such a
- * wrapper, so callers can feed the original code unchanged.
- */
 export declare function extractViteModuleCss(code: string): string | null;
 export interface TransformIndexHtmlOptions {
-    /** Inject the debug mount div instead of the standard one. */
     debug?: boolean;
     /** Keep the injection in a `build` command (explicit demo builds only). */
     demoBuild?: boolean;
     /** Keep the route-sensitive landing demo on its build-time virtual module. */
     demo?: boolean;
+    /** Inline classic script that must run before any application module. */
+    headScript?: string;
 }
-export declare function transformIndexHtmlHtml(html: string, command: "serve" | "build", { debug, demoBuild, demo }?: TransformIndexHtmlOptions): string | null;
-/**
- * Owns the build tool and nothing else: module graph, CSS observation, token
- * inventory, transport middleware, bootstrap injection, HMR. Framework
- * semantics arrive through `createFramework`; passing `null` is a supported
- * composition, and `vite.noFramework.test.ts` exercises it to prove nothing
- * here has grown a React assumption.
- */
+export declare function transformIndexHtmlHtml(html: string, command: "serve" | "build", { debug, demoBuild, demo, headScript }?: TransformIndexHtmlOptions): string | null;
 export declare function createVitePlugins(options?: NudgeUiOptions, createFramework?: ((options: NudgeUiOptions, host: FrameworkHost) => FrameworkSupport) | null): Plugin[];

package/dist/hosts/vite/vite.js

@@ -7,7 +7,7 @@ import { NUDGE_UI_CLIENT_PATH, NUDGE_UI_EDITOR_PATH, NUDGE_UI_MANIFEST_PATH, cre
 import { discoverCssImportGraph, stripCssQuery } from "./tokens/activeStylesheets.js";
 import { catalogSourcePath, createViteStylesheetArtifact, isHostApplicationSource, isPackageStylesheet, orderViteStylesheetGraph, } from "./tokens/viteStylesheetArtifacts.js";
 import { interpretDialects } from "../../css/dialects/index.js";
-import { detectStylingSystem, } from "../../inspector/clientManifest.js";
+import { createNudgeUiClientManifest, detectStylingSystem, } from "../../inspector/clientManifest.js";
 import { loopbackOrigin, startOptionalProjectBridge, } from "../projectBridge.js";
 import { automationManifestFields, isNudgeUiEnabled } from "../environment.js";
 function isRecord(value) {
@@ -26,11 +26,6 @@ const MOUNT_DIV = `<div id="nudge-ui-root"></div>`;
 const DEBUG_MOUNT_DIV = `<div id="nudge-ui-root" data-nudge-ui-debug="true"></div>`;
 const INSPECTOR_SCRIPT = `<script type="module" src="${CLIENT_PATH}" data-nudge-ui-client data-nudge-ui-manifest="${MANIFEST_PATH}"></script>`;
 const LEGACY_INSPECTOR_SCRIPT = `<script type="module" src="/@id/__x00__virtual:nudge-ui-inspector"></script>`;
-/**
- * Extracts the stylesheet string Vite embeds in dev CSS-module JS wrappers
- * (`const __vite__css = "…"`). Returns null for anything that is not such a
- * wrapper, so callers can feed the original code unchanged.
- */
 export function extractViteModuleCss(code) {
     const match = /(?:^|;)\s*(?:const|let|var)\s+__vite__css\s*=\s*("(?:[^"\\]|\\.)*")/m.exec(code);
     if (!match)
@@ -79,17 +74,26 @@ function scanCssFiles(rootDir, files = [], dir = rootDir, ignoredDirectory) {
     }
     return files;
 }
-export function transformIndexHtmlHtml(html, command, { debug = false, demoBuild = false, demo = false } = {}) {
+export function transformIndexHtmlHtml(html, command, { debug = false, demoBuild = false, demo = false, headScript } = {}) {
     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>")) {
-        return html.replace("</body>", `${inject}</body>`);
+    const withHead = headScript ? prependToHead(html, `<script data-nudge-ui-head>${headScript}</script>`) : html;
+    if (withHead.includes("</body>")) {
+        return withHead.replace("</body>", `${inject}</body>`);
     }
-    return html + inject;
+    return withHead + inject;
+}
+/** Classic inline scripts run in document order, ahead of every module script. */
+function prependToHead(html, tag) {
+    const head = /<head(?:\s[^>]*)?>/i.exec(html);
+    if (!head)
+        return `${tag}\n${html}`;
+    const at = head.index + head[0].length;
+    return `${html.slice(0, at)}\n${tag}${html.slice(at)}`;
 }
 function invalidateHmrModules(server, modules, timestamp) {
     const invalidated = new Set();
@@ -97,13 +101,6 @@ function invalidateHmrModules(server, modules, timestamp) {
         server.moduleGraph.invalidateModule(module, invalidated, timestamp, true);
     }
 }
-/**
- * Owns the build tool and nothing else: module graph, CSS observation, token
- * inventory, transport middleware, bootstrap injection, HMR. Framework
- * semantics arrive through `createFramework`; passing `null` is a supported
- * composition, and `vite.noFramework.test.ts` exercises it to prove nothing
- * here has grown a React assumption.
- */
 export function createVitePlugins(options = {}, createFramework = null) {
     const enabled = isNudgeUiEnabled(options.enabled);
     let root;
@@ -116,7 +113,7 @@ export function createVitePlugins(options = {}, createFramework = null) {
     let postTransformPromise = null;
     const inventory = createTokenInventory();
     const activeHostCssFiles = new Set();
-    // Belongs to the artifact, not one observation: a transform hook has no import-graph ordering.
+    // Ordered per artifact, not per observation: a transform hook has no import-graph ordering.
     const stylesheetOrdering = new Map();
     // Detected from the authored graph: v3 also emits --tw-* helpers, so transformed output is not a safe signal.
     const tailwindV4SourceFiles = new Set();
@@ -129,7 +126,6 @@ export function createVitePlugins(options = {}, createFramework = null) {
     let contractDiagnostics = [];
     let activeGraphDiagnostics = [];
     const sourceScanDiagnostics = new Map();
-    /** Generation of the last snapshot actually serialized into the virtual module. */
     let lastPublishedGeneration = null;
     /** Resolved at hook time: Vite's root and output directory are unknown when `nudgeUi()` is called. */
     function sourceScope() {
@@ -147,7 +143,6 @@ export function createVitePlugins(options = {}, createFramework = null) {
     function catalogPath(id) {
         return catalogSourcePath(id, root, sourceScope());
     }
-    // Everything below reaches the framework through optional chaining, so `null` is a working configuration.
     const frameworkModuleId = (id) => framework !== null && (id === framework.virtualModuleId || id === resolvedFrameworkModule());
     const resolvedFrameworkModule = () => framework === null ? null : `\0${framework.virtualModuleId}`;
     const framework = createFramework?.(options, {
@@ -169,20 +164,14 @@ export function createVitePlugins(options = {}, createFramework = null) {
         const relativeFile = relative(root, absoluteFile);
         return relativeFile === "build" || relativeFile.startsWith(`build${sep}`);
     }
-    /**
-     * Authored and transformed observations of the same id are fed as two
-     * artifacts. The inventory keeps both: the transformed one is the
-     * browser-relevant fact set, while names authored in the same artifact keep
-     * project provenance.
-     */
+    /** Authored and transformed observations of one id stay separate artifacts; the transformed one is the browser-relevant fact set. */
     function feedCssArtifact(id, rawCode, stage, ordering = {}) {
         if (!CSS_EXT.test(id))
             return;
         let code = rawCode;
         const fileId = id.split(/[?#]/, 1)[0] ?? id;
-        // Astro compiles component <style> blocks into JS wrappers with no authored .css
-        // artifact, so unwrap the embedded stylesheet or the catalog never sees
-        // component-scoped custom properties (ADR-0011).
+        // Astro compiles component <style> blocks into JS wrappers with no authored .css artifact,
+        // so unwrap the embedded stylesheet or the catalog never sees scoped custom properties (ADR-0011).
         if (!CSS_EXT.test(fileId)) {
             const unwrapped = extractViteModuleCss(code);
             if (unwrapped !== null)
@@ -210,7 +199,6 @@ export function createVitePlugins(options = {}, createFramework = null) {
         inventory.apply(artifact);
         sourceScanDiagnostics.delete(artifact.id);
     }
-    /** Drop every observation and temporary provenance fact for one stylesheet. */
     function feedCssRemoval(id) {
         const fileId = id.split(/[?#]/, 1)[0] ?? id;
         tailwindV4SourceFiles.delete(fileId);
@@ -224,7 +212,6 @@ export function createVitePlugins(options = {}, createFramework = null) {
         sourceScanDiagnostics.delete(artifact.id);
         inventory.apply(artifact);
     }
-    /** The inventory keeps the last valid authored observation and records a recoverable diagnostic. */
     function feedCssTransformFailure(id) {
         if (!CSS_EXT.test(id))
             return;
@@ -251,7 +238,7 @@ export function createVitePlugins(options = {}, createFramework = null) {
             resolvedId = (await devServer.pluginContainer.resolveId(moduleSpecifier))?.id ?? null;
         }
         catch {
-            // The diagnostic below explains it without making the CSS catalog unavailable.
+            // The diagnostic below explains the failure without making the CSS catalog unavailable.
         }
         if (!resolvedId) {
             contractDiagnostics = [{
@@ -304,12 +291,7 @@ export function createVitePlugins(options = {}, createFramework = null) {
             return;
         await refreshPublishedThemeContract();
     }
-    /**
-     * Hands everything this host observed about CSS dialects to the interpreter
-     * and applies what comes back, so the snapshot carries final labels. Every
-     * contribution is id-keyed and replaceable, so repeating this with unchanged
-     * facts is a no-op and load() shares one path with the HMR exactly-once guard.
-     */
+    /** Id-keyed, replaceable contributions: repeating this with unchanged facts is a no-op. */
     function syncInventoryContributions() {
         const { contributions } = interpretDialects({
             ...(options.tailwindV3 === undefined ? {} : { tailwindV3: options.tailwindV3 }),
@@ -342,11 +324,7 @@ export function createVitePlugins(options = {}, createFramework = null) {
         for (const contribution of contributions)
             inventory.applyContribution(contribution);
     }
-    /**
-     * Publishes exactly once per observable snapshot change. Every HMR feed for
-     * an event settles first, so identical facts do not bump the generation, and
-     * contributions sync first so the guard compares what load() would serialize.
-     */
+    /** Publishes exactly once per observable snapshot change: callers settle every feed first, and this compares what `load()` would serialize. */
     function invalidateTokensIfChanged(server) {
         const generation = currentTokenGeneration();
         if (generation === lastPublishedGeneration)
@@ -460,8 +438,8 @@ export function createVitePlugins(options = {}, createFramework = null) {
             return Promise.resolve();
         if (postTransformPromise)
             return postTransformPromise;
-        // The module graph decides reachability: transforming only those entries drives
-        // them through the observer plugin below without activating dead CSS files.
+        // The module graph decides reachability: only the reachable entries are transformed,
+        // without activating dead CSS files.
         postTransformPromise = (async () => {
             await refreshActiveStylesheetTokens();
             const cssPaths = activeHostCssFiles.size > 0
@@ -483,17 +461,14 @@ export function createVitePlugins(options = {}, createFramework = null) {
         await projectBridgeStart;
         await ensurePostTransformCss();
         await ensurePublishedThemeContract();
-        return {
-            version: 1,
-            revision: 0,
+        return createNudgeUiClientManifest({
             runtime: buildRuntimeSnapshot(),
             ...(projectBridge ? { agentBridge: projectBridge.browser } : {}),
             ...automationManifestFields(),
-        };
+        });
     }
     function startProjectBridge(server) {
-        // The public demo uses the shared editor runtime without project-owned
-        // sessions, an agent bridge, or filesystem persistence.
+        // The demo runs without project-owned sessions, an agent bridge, or filesystem persistence.
         if (options.demo === true || !root || projectBridgeStart)
             return;
         const address = server.httpServer?.address();
@@ -528,8 +503,7 @@ export function createVitePlugins(options = {}, createFramework = null) {
         }));
         return {
             projectId: options.projectId ?? (root ? basename(root) : "vite"),
-            // Without a framework there are no component boundaries to describe, so the
-            // project is HTML and CSS as far as the inspector is concerned.
+            // Without a framework there are no component boundaries to describe, so the project is HTML and CSS.
             host: framework?.hostLabel ?? "static-html",
             framework: framework?.framework ?? "HTML",
             stylingSystem: detectStylingSystem(snapshot.tokens),
@@ -654,8 +628,8 @@ export function createVitePlugins(options = {}, createFramework = null) {
             server.watcher?.on("unlink", (file) => handleStylesheetWatchEvent(server, file, "unlink"));
         },
         buildStart() {
-            // The browser imports virtual:design-tokens before styles.css is necessarily
-            // transformed, so transform-only collection would yield an empty first load.
+            // The browser imports virtual:design-tokens before styles.css is necessarily transformed,
+            // so transform-only collection would yield an empty first load.
             if (!enabled || (command !== "serve" && !demoBuild) || !root)
                 return;
             for (const cssPath of scanCssFiles(root, [], root, buildOutputDirectory)) {
@@ -693,14 +667,12 @@ export function createVitePlugins(options = {}, createFramework = null) {
                 }
                 await ensurePostTransformCss();
                 await ensurePublishedThemeContract();
-                // Contributions merge inside the inventory; load() serializes one immutable
-                // snapshot verbatim, so there is no post-snapshot enrichment or TOCTOU.
+                // One immutable snapshot is serialized verbatim; there is no post-snapshot enrichment.
                 const runtime = buildRuntimeSnapshot();
                 lastPublishedGeneration = runtime.tokenGeneration;
                 return `export const tokenCatalog = ${JSON.stringify(runtime.tokenCatalog)};\nexport const tokens = ${JSON.stringify(runtime.tokens)};\nexport const tokenDiagnostics = ${JSON.stringify(runtime.tokenDiagnostics)};\nexport const tokenGeneration = ${JSON.stringify(runtime.tokenGeneration)};\nexport const nudgeUiProjectId = ${JSON.stringify(runtime.projectId)};\nexport default tokens;\n`;
             }
             if (id === RESOLVED_INSPECTOR_ID) {
-                // ADR-0002: normal production builds receive no inspector bootstrap.
                 if (command === "build" && !demoBuild) {
                     return `export {};\n`;
                 }
@@ -708,8 +680,7 @@ export function createVitePlugins(options = {}, createFramework = null) {
                     const demoControllerExpression = demoBuild
                         ? "true"
                         : '(import.meta.env.DEV && window.location.pathname === "/")';
-                    // Taken from the composed framework, so the demo bootstrap cannot drift
-                    // from the manifest the transport serves.
+                    // Taken from the composed framework, so the demo bootstrap cannot drift from the served manifest.
                     const identity = buildRuntimeSnapshot();
                     return [
                         'import { bootstrapNudgeUi, configureNudgeUiRuntime, createNudgeUiEditorUrl, detectFramework, hasNudgeUiDirectTabIntent, isCanvasRenderer, isNudgeUiDirectUrl, readNudgeUiEditorTarget, rememberNudgeUiDirectTabIntent } from "nudge-ui/internal/inspector";',
@@ -758,15 +729,13 @@ export function createVitePlugins(options = {}, createFramework = null) {
                 return null;
             }
             if (framework && id === resolvedFrameworkModule()) {
-                // ADR-0002: production builds receive an empty catalog.
                 const productionBuild = command === "build" && !demoBuild;
                 return framework.serializeVirtualModule(productionBuild ? [] : framework.contracts());
             }
             return null;
         },
-        // React's Vite plugin is also `enforce: "pre"` with no explicit hook order, so
-        // hook-level `order: "pre"` is what parses authored TSX before Babel prepends
-        // refresh helpers and shifts the AST locations data-src depends on.
+        // React's Vite plugin is also `enforce: "pre"` with no explicit hook order, so hook-level
+        // `order: "pre"` is what parses authored TSX before Babel shifts the AST locations data-src depends on.
         transform: {
             order: "pre",
             async handler(code, id) {
@@ -783,7 +752,6 @@ export function createVitePlugins(options = {}, createFramework = null) {
                     feedCssArtifact(id, code, "authored");
                     return null; // let Vite's CSS pipeline handle the actual stylesheet
                 }
-                // Everything past CSS belongs to the framework; with none, source modules are untouched.
                 if (!framework)
                     return null;
                 return framework.transform({
@@ -796,14 +764,17 @@ export function createVitePlugins(options = {}, createFramework = null) {
             },
         },
         transformIndexHtml(html) {
-            // The landing app's static demo build imports the virtual module from the app
-            // entry, because Vite cannot preserve the dev HTML virtual-module URL.
+            // The static demo build imports the virtual module from the app entry, because Vite
+            // cannot preserve the dev HTML virtual-module URL.
             if (!enabled || demoBuild)
                 return;
+            // Demo builds return above: they ship production React, which has no prop-editing toolkit.
+            const headScript = framework?.documentHeadScript;
             const out = transformIndexHtmlHtml(html, command, {
                 debug: options.debug === true,
                 demoBuild,
                 demo: options.demo === true,
+                ...(headScript ? { headScript } : {}),
             });
             return out === null ? undefined : out;
         },
@@ -815,7 +786,6 @@ export function createVitePlugins(options = {}, createFramework = null) {
                 invalidateHmrModules(ctx.server, ctx.modules, ctx.timestamp);
                 publishedThemeContractLoaded = false;
                 await ensurePublishedThemeContract();
-                // Same exactly-once path as the CSS branch.
                 const { changed, generation, virtual } = invalidateTokensIfChanged(ctx.server);
                 if (changed && virtual)
                     return [...ctx.modules, virtual];
@@ -833,8 +803,7 @@ export function createVitePlugins(options = {}, createFramework = null) {
                 catch {
                     framework.forget(ctx.file);
                 }
-                // Vite must update importer edges first: a component can add or remove a
-                // stylesheet import while every CSS file remains on disk.
+                // Vite must update importer edges first: a component can add or remove a stylesheet import.
                 invalidateHmrModules(ctx.server, ctx.modules, ctx.timestamp);
                 try {
                     await ctx.server.transformRequest(ctx.file);
@@ -886,20 +855,17 @@ export function createVitePlugins(options = {}, createFramework = null) {
                 }
             }
             await refreshActiveStylesheetTokens();
-            // ctx.read() returns authored source, so re-run it through Vite to pick up
-            // Tailwind's generated stylesheet before invalidating below.
+            // ctx.read() returns authored source, so re-run it through Vite to pick up Tailwind's generated stylesheet.
             postTransformPromise = null;
             try {
                 await ctx.server.transformRequest(ctx.file);
             }
             catch {
-                // Marks the transform failed so authored rows survive with a recoverable
-                // diagnostic. A deleted file has no authored read and is a removal instead.
+                // Marks the transform failed so authored rows survive with a recoverable diagnostic.
                 if (hasAuthoredObservation)
                     feedCssTransformFailure(ctx.file);
             }
-            // Every feed for this event has settled, so invalidate only on a real
-            // generation change. Vite's own CSS update below still runs either way.
+            // Every feed for this event has settled, so invalidate only on a real generation change.
             const { changed, generation, virtual } = invalidateTokensIfChanged(ctx.server);
             if (generation !== previousGeneration && !virtual) {
                 ctx.server.ws.send({ type: "full-reload", path: "*" });
@@ -911,7 +877,6 @@ export function createVitePlugins(options = {}, createFramework = null) {
                 if (m)
                     modules.push(m);
             }
-            // Deduplicate while preserving order.
             const seen = new Set();
             return modules.filter((m) => {
                 if (seen.has(m.id ?? ""))
@@ -921,9 +886,8 @@ export function createVitePlugins(options = {}, createFramework = null) {
             });
         },
     };
-    // Tailwind's generator is a pre-transform hook, so this companion stays in Vite's
-    // normal group: after every pre plugin regardless of user order, and before Vite's
-    // CSS-post JavaScript wrapper. The main plugin stays pre-ordered for TSX locations.
+    // Tailwind's generator is a pre-transform hook, so this companion stays in Vite's normal
+    // group: after every pre plugin regardless of user order, and before Vite's CSS-post wrapper.
     const transformedCssObserver = {
         name: "nudge-ui:transformed-css",
         apply: "serve",

package/dist/html/dom.d.ts

@@ -8,6 +8,5 @@ export type StartTagLocation = NonNullable<ElementLocation["startTag"]>;
 export declare function isElement(node: DefaultTreeAdapterTypes.ChildNode): node is HtmlElement;
 export declare function hasAttribute(element: HtmlElement, name: string, value?: string): boolean;
 export declare function getAttributeValue(element: HtmlElement, name: string): string | undefined;
-/** Every `<body>` in the document, skipping inert `<template>` content. */
 export declare function findBodyElements(document: DefaultTreeAdapterTypes.Document): HtmlElement[];
 export declare function escapeAttributeValue(value: string): string;

package/dist/html/dom.js

@@ -19,7 +19,6 @@ export function hasAttribute(element, name, value) {
 export function getAttributeValue(element, name) {
     return element.attrs.find((candidate) => candidate.name === name)?.value;
 }
-/** Every `<body>` in the document, skipping inert `<template>` content. */
 export function findBodyElements(document) {
     const bodies = [];
     const visit = (parent) => {

package/dist/html/identity.d.ts

@@ -1,12 +1,3 @@
-/**
- * Adds source identity to HTML without reserializing it. The two hosts differ
- * only in where identity comes from: the static-HTML host owns the file and
- * uses parser offsets, Astro does not own the response and reads its
- * compiler's annotations. Both share the traversal below.
- *
- * Attributes are inserted only where missing, at the end of the opening tag,
- * so everything outside those insertions stays byte-for-byte unchanged.
- */
 export interface HtmlIdentityDiagnostic {
     readonly code: HtmlIdentityDiagnosticCode;
     readonly severity: "warning";
@@ -26,15 +17,10 @@ export interface HtmlIdentityResult {
     readonly diagnostics: readonly HtmlIdentityDiagnostic[];
     readonly insertedAttributeCount: number;
 }
-/** Instruments an HTML file the host owns on disk, using parser offsets for position. */
 export declare function instrumentSourceHtml(source: string, file: string): HtmlIdentityResult;
 export interface RenderedHtmlIdentityOptions {
     /** Relativizes absolute annotation paths. Omit to forward them unchanged. */
     readonly projectRoot?: string;
 }
-/**
- * Instruments a rendered Astro dev response from Astro's own compiler
- * annotations. Elements without them degrade to an `astro:<Tag>` label and no
- * position, because a guessed `data-src` would be worse than none.
- */
+/** Elements without Astro compiler annotations degrade to an `astro:<Tag>` label and no position. */
 export declare function instrumentRenderedHtml(html: string, options?: RenderedHtmlIdentityOptions): HtmlIdentityResult;

package/dist/html/identity.js

@@ -84,7 +84,6 @@ function runIdentityPass(source, pass) {
         insertedAttributeCount: insertions.reduce((count, i) => count + i.attributeCount, 0),
     };
 }
-/** Instruments an HTML file the host owns on disk, using parser offsets for position. */
 export function instrumentSourceHtml(source, file) {
     return runIdentityPass(source, {
         file,
@@ -104,11 +103,7 @@ export function instrumentSourceHtml(source, file) {
 const ASTRO_ISLAND_TAG_NAME = "astro-island";
 const ASTRO_SOURCE_FILE_ATTRIBUTE = "data-astro-source-file";
 const ASTRO_SOURCE_LOC_ATTRIBUTE = "data-astro-source-loc";
-/**
- * Instruments a rendered Astro dev response from Astro's own compiler
- * annotations. Elements without them degrade to an `astro:<Tag>` label and no
- * position, because a guessed `data-src` would be worse than none.
- */
+/** Elements without Astro compiler annotations degrade to an `astro:<Tag>` label and no position. */
 export function instrumentRenderedHtml(html, options = {}) {
     let sawSourceAnnotation = false;
     const result = runIdentityPass(html, {
@@ -167,7 +162,6 @@ function readAstroSourceIdentity(element, projectRoot, report, position) {
     const file = projectRelativePath(trimmedFile, projectRoot);
     return loc.column === undefined ? `${file}:${loc.line}` : `${file}:${loc.line}:${loc.column}`;
 }
-/** Parses "line:column". A bare integer is accepted as a line with no column. */
 function parseAstroSourceLoc(value) {
     const match = /^\s*(\d+)(?:\s*:\s*(\d+))?\s*$/.exec(value);
     const lineText = match?.[1];
@@ -180,7 +174,6 @@ function parseAstroSourceLoc(value) {
     const column = Number(columnText);
     return line >= 1 && column >= 1 ? { line, column } : null;
 }
-/** Separators are normalized to forward slashes so values stay portable. */
 function projectRelativePath(filePath, projectRoot) {
     const normalized = filePath.replaceAll("\\", "/");
     if (projectRoot === undefined || !path.isAbsolute(normalized))

package/dist/html/insertions.d.ts

@@ -1,5 +1,4 @@
 import type { StartTagLocation } from "./dom.js";
-/** Attribute text to splice into the original source at one byte offset. */
 export interface Insertion {
     readonly offset: number;
     readonly text: string;
@@ -7,14 +6,9 @@ export interface Insertion {
 }
 /** Offset just inside the opening tag's `>`, or null if it is not a tag boundary. */
 export declare function insertionOffsetFor(source: string, startTag: StartTagLocation): number | null;
-/** Splices insertions into the source, leaving every other byte untouched. */
+/** Leaves every other byte untouched. */
 export declare function applyInsertions(source: string, insertions: readonly Insertion[]): string;
-/**
- * One-based positions computed from the original source, not from parse5,
- * which normalizes `\r\n` and lone `\r` to `\n` and would drift from the bytes
- * these operations preserve. Columns count UTF-16 code units, so a tab is one
- * column, matching grep-style tooling rather than editor tab stops.
- */
+/** One-based; computed from the original source because parse5 normalizes line endings. Columns count UTF-16 code units. */
 export interface SourcePositionIndex {
     readonly lineStarts: readonly number[];
 }

package/dist/html/insertions.js

@@ -10,7 +10,7 @@ export function insertionOffsetFor(source, startTag) {
     // Insert before a self-closing slash: `<input data-cid="..." />`.
     return source[endOffset - 2] === "/" ? endOffset - 2 : endOffset - 1;
 }
-/** Splices insertions into the source, leaving every other byte untouched. */
+/** Leaves every other byte untouched. */
 export function applyInsertions(source, insertions) {
     const byOffset = new Map();
     for (const insertion of insertions) {