nudge-ui 0.2.4 → 0.2.6

package/dist/hosts/astro/responseInstrumentation.js

@@ -1,41 +1,15 @@
 import { instrumentRenderedHtml } from "../../html/identity.js";
 const HTML_MEDIA_TYPE_PATTERN = /^text\/html$/i;
-/**
- * Measures `Content-Length` in bytes without assuming a Node global; the
- * middleware itself may run on any runtime that serves Astro's dev server.
- */
+// Measures Content-Length in bytes without assuming a Node global; the middleware may run on any runtime.
 const HTML_BYTE_LENGTH_ENCODER = new TextEncoder();
-/**
- * Classifies a response Content-Type header. Only `text/html` responses
- * (with optional parameters such as charset) are eligible for identity
- * instrumentation; everything else must pass through untouched.
- */
+/** Only `text/html` (with optional parameters such as charset) is eligible; everything else passes through untouched. */
 export function isHtmlContentType(contentType) {
     if (contentType === undefined)
         return false;
     const mediaType = contentType.split(";", 1)[0]?.trim() ?? "";
     return HTML_MEDIA_TYPE_PATTERN.test(mediaType);
 }
-/**
- * Instruments one rendered dev response at the Astro middleware seam
- * (ADR-0011).
- *
- * HTML bodies are materialized once, transformed through the identity Module,
- * and re-emitted as a new `Response` whose headers carry a corrected
- * `Content-Length`; every other response is returned by reference with its
- * stream untouched. If the body read or instrumentation throws, the original
- * response forwards so identity extraction can never break a dev page load —
- * a failed read returns the original response by reference (its stream is the
- * only remaining representation), while a failed transform returns a fresh
- * `Response` over the already-materialized body. Diagnostics always
- * accompany the result so callers can surface degraded identity.
- *
- * @param response The response produced downstream (the rendered page).
- * @param projectRoot Project root used to relativize annotation paths.
- * @param instrument Identity transform to apply; defaults to the real
- *   `instrumentRenderedHtml`. Tests inject a failing implementation to exercise
- *   the catch branch.
- */
+/** HTML bodies are materialized once to re-emit with a corrected Content-Length; every other response is returned by reference, stream untouched. */
 export async function instrumentAstroResponse(response, projectRoot, instrument = instrumentRenderedHtml) {
     const contentType = response.headers.get("content-type") ?? undefined;
     if (!isHtmlContentType(contentType))
@@ -47,9 +21,7 @@ export async function instrumentAstroResponse(response, projectRoot, instrument
         source = await response.text();
     }
     catch {
-        // The body read itself failed; the original response is the only
-        // remaining representation of the body, so forward it by reference
-        // instead of rejecting into the middleware chain.
+        // Forward the original response by reference: its stream is the only remaining body.
         return { response, diagnostics: [] };
     }
     try {
@@ -66,8 +38,7 @@ export async function instrumentAstroResponse(response, projectRoot, instrument
         };
     }
     catch {
-        // Identity extraction must never break a dev page load; forward the
-        // untouched body instead.
+        // Identity extraction must never break a dev page load; forward the untouched body.
         return {
             response: new Response(source, {
                 status: response.status,

package/dist/hosts/environment.d.ts

@@ -1,13 +1,5 @@
-/**
- * The `NUDGE_UI` environment switch shared by every development host.
- *
- * - `0`, `false`, or `off` disables the host Adapter for that run.
- * - `1`, `true`, or `on` also opens the editor in automated browsers, which
- *   otherwise receive the plain application.
- */
 export type NudgeUiEnvironmentSwitch = "off" | "on" | null;
 export declare function readNudgeUiEnvironmentSwitch(env?: Readonly<Record<string, string | undefined>>): NudgeUiEnvironmentSwitch;
-/** An explicit `enabled: false` or `NUDGE_UI=0` disables the Adapter. */
 export declare function isNudgeUiEnabled(enabled: boolean | undefined, env?: Readonly<Record<string, string | undefined>>): boolean;
 /** Manifest fields derived from the environment at request time. */
 export declare function automationManifestFields(env?: Readonly<Record<string, string | undefined>>): {

package/dist/hosts/environment.js

@@ -6,7 +6,6 @@ export function readNudgeUiEnvironmentSwitch(env = process.env) {
         return "on";
     return null;
 }
-/** An explicit `enabled: false` or `NUDGE_UI=0` disables the Adapter. */
 export function isNudgeUiEnabled(enabled, env = process.env) {
     return enabled !== false && readNudgeUiEnvironmentSwitch(env) !== "off";
 }

package/dist/hosts/next/index.js

@@ -2,6 +2,4 @@ export { withNudgeUi, } from "./wrapper.js";
 export { buildManifest, nextjsProjectId } from "./manifest.js";
 export { ensureSidecar, clearStaleSidecarState, } from "./sidecar.js";
 export { transformNextModuleSource, hasUseClientDirective, directivePrologueEnd, instrumentRootLayout, } from "./loader.js";
-// `./loader-plugin.cts` is the compiler-facing entry; it is CommonJS by
-// contract (see its header) and is therefore not re-exported through this
-// ESM surface.
+// `./loader-plugin.cts` is CommonJS by contract and deliberately not re-exported through this ESM surface.

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

@@ -1,66 +1,27 @@
 import type { SourceMap } from "magic-string";
 import type { HostComponentPolicy } from "../../compiler/componentPolicyResolution.js";
 export interface NextModuleTransformOptions {
-    /**
-     * Project root used to compute project-relative `data-src` values. Matches
-     * the Vite Adapter's semantics: paths outside the root fall back to the
-     * absolute path with its leading slash stripped.
-     */
+    /** Paths outside the project root fall back to the absolute path with its leading slash stripped (matches Vite). */
     root?: string;
-    /**
-     * Directory name of the Pages Router route root. Modules resolved under it
-     * are client components even without a `"use client"` directive.
-     */
+    /** Pages Router route root; modules under it are client components even without a `"use client"` directive. */
     pagesDir?: string;
-    /** Import provenance and slot policy resolved by the Next host Adapter. */
     hostPolicy?: HostComponentPolicy;
-    /** Whether this module belongs to the Adapter's explicit semantic source scope. */
     instrumentComponents?: boolean;
-    /** Module specifier resolved by the Next host for semantic boundaries. */
     componentRuntimeModule?: string;
 }
 export interface NextModuleTransformResult {
     code: string;
     map: SourceMap | null;
-    /** True when the module qualifies as a client component (directive or Pages Router rule). */
     clientComponent: boolean;
-    /** True when a root-layout mount element was appended. */
     layoutInstrumented: boolean;
 }
-/**
- * Transforms one application module for development rendering, or returns
- * `null` when nothing applies and the caller must serve the original bytes.
- *
- * `moduleId` is an absolute or project-relative path; only path shapes are
- * inspected, never the filesystem.
- */
+/** Returns `null` when nothing applies and the caller must serve the original bytes; `moduleId` is inspected as a path only, never as the filesystem. */
 export declare function transformNextModuleSource(source: string, moduleId: string, options?: NextModuleTransformOptions): NextModuleTransformResult | null;
-/**
- * Detects a module-level `"use client"` directive without a full parse.
- *
- * Only comments, whitespace, a shebang, and other directive prologues may
- * precede it; anything else ends the directive prologue per the ECMAScript
- * spec, which keeps the scan exact rather than a loose substring search.
- */
 export declare function hasUseClientDirective(source: string): boolean;
-/**
- * Appends the inspector mount as the last child of a literal rendered `<body>`
- * element. The server-rendered script must be in the initial document so it
- * does not rely on hydration of a client component in the root layout. A
- * layout with no literal body is left unchanged rather than emitting an
- * invalid direct child of `<html>`.
- *
- * Idempotence: the aliased mount import doubles as the marker — a module that
- * already carries it is left untouched, so running the loader twice (as
- * Turbopack does across react-server and client conditions) cannot stack
- * duplicates.
- */
+/** Appends the mount as the last child of a literal `<body>` so the script ships in the initial document; a module that already carries the aliased import is left untouched. */
 export declare function instrumentRootLayout(source: string): {
     code: string;
     map: SourceMap;
 } | null;
-/**
- * Offset just past the directive prologue (shebang, comments, directive
- * statements) — the only legal insertion point for new import statements.
- */
+/** Offset just past the directive prologue — the only legal insertion point for new imports. */
 export declare function directivePrologueEnd(source: string): number;

package/dist/hosts/next/loader.js

@@ -2,51 +2,20 @@ import { parse } from "@babel/parser";
 import MagicString from "magic-string";
 import { posix } from "node:path";
 import { injectIdentity } from "../../compiler/reactIdentity.js";
-/**
- * Pure Next.js identity-loader Module (ADR-0010).
- *
- * Wraps the shared `injectIdentity` Module with Next-specific policy:
- *
- * - client-component detection gates the semantic runtime import (directive
- *   scan, Pages Router rule); server-component modules receive identity
- *   attributes only and fail closed;
- * - `<html>`-rendering App Router root layouts receive a dev-only server
- *   script inside `<body>` that bootstraps the inspector;
- * - excluded paths are rejected before any parse work happens.
- *
- * The transform is deterministic by contract: Turbopack compiles each module
- * once per environment (react-server and client conditions), so identical
- * input must produce identical output across repeated runs.
- */
-/** Extensions whose sources can carry JSX and therefore identity targets. */
 const APP_SOURCE_EXT = /\.([cm]?[jt]sx?)$/i;
-/** Parseable-by-the-shared-Module extensions (must contain JSX). */
 const JSX_SOURCE_EXT = /\.(tsx|jsx)$/;
-/** Directory segments never instrumented (build output and dependencies). */
 const EXCLUDED_SEGMENTS = /(^|\/)(node_modules|\.next)\//i;
 const MOUNT_LOCAL_NAME = "__NudgeUiMountElement";
 const NEXT_COMPONENT_RUNTIME_MODULE = "nudge-ui/internal/component-runtime";
 const MOUNT_IMPORT = `import { createElement as __NudgeUiCreateElement } from "react";\n`
     + `import { NudgeUiMount as ${MOUNT_LOCAL_NAME} } from "nudge-ui/internal/next/mount";\n`;
-// The mount renders through an expression container invoking createElement
-// rather than through a JSX element: a bare `{Component}` would hand React
-// the function itself ("Functions are not valid as a React child"), while an
-// element `<Cmp />` would be visible to later identity passes. A
-// `createElement(...)` call produces no JSX nodes — nothing to attribute or
-// wrap — while still yielding a real element for React to render.
+// Rendered through createElement rather than as a JSX element: a bare `{Component}` is not
+// a valid React child, and a `<Cmp />` element would be visible to later identity passes.
 const MOUNT_JSX = `\n    {__NudgeUiCreateElement(${MOUNT_LOCAL_NAME})}\n  `;
-/**
- * Transforms one application module for development rendering, or returns
- * `null` when nothing applies and the caller must serve the original bytes.
- *
- * `moduleId` is an absolute or project-relative path; only path shapes are
- * inspected, never the filesystem.
- */
+/** Returns `null` when nothing applies and the caller must serve the original bytes; `moduleId` is inspected as a path only, never as the filesystem. */
 export function transformNextModuleSource(source, moduleId, options = {}) {
-    // ADR-0002 phase gate, defense-in-depth beneath the wrapper: Next sets
-    // NEXT_PHASE per invocation, so even a misconfigured
-    // NODE_ENV=development production build refuses every transform here.
-    // Absent phases still transform — exotic dev harnesses keep working.
+    // Defense-in-depth beneath the wrapper: Next sets NEXT_PHASE per invocation, so even a
+    // misconfigured production build refuses every transform here; absent phases still transform.
     if (process.env.NEXT_PHASE === "phase-production-build")
         return null;
     const normalized = moduleId.split("\\").join("/");
@@ -64,12 +33,9 @@ export function transformNextModuleSource(source, moduleId, options = {}) {
     let map = identity ? identity.map : null;
     let layoutInstrumented = false;
     if (identity && clientComponent) {
-        // The shared Module PREPENDS the runtime import, which is fine under
-        // Vite but fatal under SWC: a module starting with an import is no
-        // longer a directive prologue, so Next rejects the file ("use client
-        // must be placed before other expressions"). Relocate the prepended
-        // import to just past the directive prologue.
-        code = relocatePrependedRuntimeImport(code, options.componentRuntimeModule ?? NEXT_COMPONENT_RUNTIME_MODULE);
+        // The shared module prepends the runtime import, which SWC rejects ahead of a
+        // `"use client"` directive; relocate it past the directive prologue.
+        code = relocatePrependedRuntimePrelude(code, identity.prelude);
     }
     if (isAppRootLayoutPath(normalized)) {
         const mounted = instrumentRootLayout(code);
@@ -81,39 +47,23 @@ export function transformNextModuleSource(source, moduleId, options = {}) {
     }
     if (!identity && !layoutInstrumented)
         return null;
-    // When both passes ran, the layout map is composed against the identity
-    // pass's output rather than the original source. Dev-only tooling tolerates
-    // this v1 simplification; the identity map (the one prompts rely on) is
-    // always against the original bytes because the layout pass runs after it.
+    // When both passes ran, the layout map is composed against the identity pass's output
+    // rather than the original source; the identity map prompts rely on stays against original bytes.
     return { code, map, clientComponent, layoutInstrumented };
 }
-/**
- * Moves the shared Module's prepended runtime import past the directive
- * prologue when the source began with one. Sources without a leading
- * directive are returned untouched (the import is already first).
- */
-function relocatePrependedRuntimeImport(code, runtimeModule) {
-    const runtimeImport = `import { instrumentReactComponent as __nudgeUiInstrumentComponent } from ${JSON.stringify(runtimeModule)};\n`;
-    if (!code.startsWith(runtimeImport))
+function relocatePrependedRuntimePrelude(code, prelude) {
+    if (!prelude || !code.startsWith(prelude))
         return code;
-    const rest = code.slice(runtimeImport.length);
+    const rest = code.slice(prelude.length);
     const insertAt = directivePrologueEnd(rest);
-    return rest.slice(0, insertAt) + runtimeImport + rest.slice(insertAt);
+    return rest.slice(0, insertAt) + prelude + rest.slice(insertAt);
 }
-/**
- * True when the module resolves inside the Pages Router directory, anchored
- * to the router root: only `pages/**` or `src/pages/**` count. An App Router
- * route nested at `app/pages/Card.tsx` is a server component and MUST NOT
- * match — wrapping it with the client runtime would break the RSC graph.
- *
- * `pagesDir` may itself contain slashes ("src/pages") for exotic layouts.
- */
+/** Only `pages/**` and `src/pages/**` count: an App Router route at `app/pages/Card.tsx` must not match, or wrapping it breaks the RSC graph. */
 function isPagesRouterModule(normalizedId, options) {
     const pagesDir = (options.pagesDir ?? "pages").split("\\").join("/").replace(/^\/+|\/+$/g, "");
     if (pagesDir.length === 0)
         return false;
-    // Anchor against the project root when known; without a root we cannot
-    // distinguish router roots from same-named directories, so fail closed.
+    // Anchor against the project root when known; without a root, same-named directories cannot be ruled out, so fail closed.
     const root = options.root ? options.root.split("\\").join("/").replace(/\/+$/, "") : null;
     const relative = root
         ? normalizedId.startsWith(`${root}/`)
@@ -127,11 +77,7 @@ function isPagesRouterModule(normalizedId, options) {
         || (relative.startsWith("src/")
             && (relative.slice(4) === pagesDir || relative.slice(4).startsWith(`${pagesDir}/`)));
 }
-/**
- * True for App Router layout modules. Route groups nest more `app` segments
- * (`app/(marketing)/layout.tsx`), so any `app` ancestor segment counts; the
- * `<html>` guard decides whether a mount actually belongs.
- */
+/** Any `app` ancestor segment counts because route groups nest (`app/(marketing)/layout.tsx`); the `<html>` guard decides whether a mount belongs. */
 function isAppRootLayoutPath(normalizedId) {
     if (!JSX_SOURCE_EXT.test(normalizedId))
         return false;
@@ -140,17 +86,9 @@ function isAppRootLayoutPath(normalizedId) {
         return false;
     return parsed.dir === "app" || parsed.dir.endsWith("/app") || parsed.dir.includes("/app/");
 }
-/**
- * Detects a module-level `"use client"` directive without a full parse.
- *
- * Only comments, whitespace, a shebang, and other directive prologues may
- * precede it; anything else ends the directive prologue per the ECMAScript
- * spec, which keeps the scan exact rather than a loose substring search.
- */
 export function hasUseClientDirective(source) {
     let index = 0;
     const length = source.length;
-    // A shebang may precede the directive prologue.
     if (source.startsWith("#!")) {
         const lineEnd = source.indexOf("\n", index);
         if (lineEnd === -1)
@@ -200,15 +138,13 @@ export function hasUseClientDirective(source) {
                 return false;
             if (literal === "use client")
                 return true;
-            // Another directive prologue ("use strict", "use server", …) may still
-            // be followed by the target directive; anything else ends the scan.
+            // Other directive prologues may still be followed by `"use client"`; anything else ends the scan.
             let after = cursor + 1;
             while (after < length && /\s/.test(source.charAt(after)))
                 after += 1;
             if (source.charAt(after) === ";")
                 after += 1;
-            // A directive must be its own statement; a string expression used as a
-            // value would be followed by other tokens on the same statement.
+            // A directive must be its own statement — a string used as a value continues with other tokens.
             if (after < length && !/[\n\r;]/.test(source.charAt(after)) && source[after - 1] !== ";") {
                 return false;
             }
@@ -219,18 +155,7 @@ export function hasUseClientDirective(source) {
     }
     return false;
 }
-/**
- * Appends the inspector mount as the last child of a literal rendered `<body>`
- * element. The server-rendered script must be in the initial document so it
- * does not rely on hydration of a client component in the root layout. A
- * layout with no literal body is left unchanged rather than emitting an
- * invalid direct child of `<html>`.
- *
- * Idempotence: the aliased mount import doubles as the marker — a module that
- * already carries it is left untouched, so running the loader twice (as
- * Turbopack does across react-server and client conditions) cannot stack
- * duplicates.
- */
+/** Appends the mount as the last child of a literal `<body>` so the script ships in the initial document; a module that already carries the aliased import is left untouched. */
 export function instrumentRootLayout(source) {
     if (source.includes(MOUNT_LOCAL_NAME))
         return null;
@@ -251,17 +176,12 @@ export function instrumentRootLayout(source) {
     if (!bodyElement?.closingElement?.start)
         return null;
     const ms = new MagicString(source);
-    // The import must land after any directive prologue: prepending ahead of a
-    // `"use client"` directive would strip it of prologue status and silently
-    // change the module's compilation environment.
+    // Must land after any directive prologue, or a leading `"use client"` loses prologue status.
     ms.appendLeft(directivePrologueEnd(source), MOUNT_IMPORT);
     ms.appendLeft(bodyElement.closingElement.start, MOUNT_JSX);
     return { code: ms.toString(), map: ms.generateMap({ hires: true }) };
 }
-/**
- * Offset just past the directive prologue (shebang, comments, directive
- * statements) — the only legal insertion point for new import statements.
- */
+/** Offset just past the directive prologue — the only legal insertion point for new imports. */
 export function directivePrologueEnd(source) {
     let index = 0;
     const length = source.length;
@@ -303,7 +223,6 @@ export function directivePrologueEnd(source) {
                     break;
                 cursor += 1;
             }
-            // Consume the statement terminator of this directive, then continue.
             let after = cursor + 1;
             while (after < length && /\s/.test(source.charAt(after)))
                 after += 1;