nudge-ui 0.2.0

package/dist/hosts/astro/clientAsset.js

@@ -0,0 +1,51 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+const packageRequire = createRequire(import.meta.url);
+/**
+ * Creates the Astro handler for the shared, immutable inspector client.
+ * Resolution and reads remain lazy so disabled and production integrations do
+ * not depend on a development asset being present.
+ */
+export function createAstroClientAssetHandler(dependencies = {}) {
+    const resolveClientPath = dependencies.resolveClientPath
+        ?? (() => packageRequire.resolve("nudge-ui/internal/client"));
+    const readClientFile = dependencies.readClientFile ?? readFile;
+    let cachedAsset;
+    return async (request, response) => {
+        const asset = await loadClientAsset();
+        response.setHeader("Cache-Control", "no-cache");
+        response.setHeader("ETag", asset.etag);
+        if (request.headers["if-none-match"] === asset.etag) {
+            response.statusCode = 304;
+            response.end();
+            return;
+        }
+        response.statusCode = 200;
+        response.setHeader("Content-Type", "text/javascript; charset=utf-8");
+        response.end(request.method === "HEAD" ? undefined : asset.body);
+    };
+    function loadClientAsset() {
+        if (cachedAsset)
+            return cachedAsset;
+        const current = load();
+        cachedAsset = current;
+        void current.catch(() => {
+            if (cachedAsset === current)
+                cachedAsset = undefined;
+        });
+        return current;
+    }
+    async function load() {
+        try {
+            const body = await readClientFile(resolveClientPath());
+            const digest = createHash("sha256").update(body).digest("base64url");
+            return { body, etag: `"sha256-${digest}"` };
+        }
+        catch (cause) {
+            throw new Error("Nudge UI could not load its inspector client. "
+                + "Build nudge-ui (`pnpm --filter nudge-ui build`) "
+                + "in a source workspace, or reinstall nudge-ui in an installed project.", { cause });
+        }
+    }
+}

package/dist/hosts/astro/clientTransport.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "vite";
+/** Serves the prebuilt client and its host-neutral manifest in Astro dev. */
+export declare function createAstroClientTransportPlugin(): Plugin;

package/dist/hosts/astro/clientTransport.js

@@ -0,0 +1,57 @@
+import {} from "../../inspector/clientManifest.js";
+import { createAstroRuntimeConfig } from "./astroRuntimeConfig.js";
+import { createAstroClientAssetHandler } from "./clientAsset.js";
+import { NUDGE_UI_CLIENT_PATH, NUDGE_UI_MANIFEST_PATH, } from "../../transport/index.js";
+const serveClient = createAstroClientAssetHandler();
+/** Serves the prebuilt client and its host-neutral manifest in Astro dev. */
+export function createAstroClientTransportPlugin() {
+    return {
+        name: "nudge-ui-astro-client-transport",
+        // The shared Vite plugin exposes the same route for React hosts. Astro's
+        // host-specific manifest must be installed first so that its middleware
+        // is the handler that answers /__nudge_ui__/manifest.
+        enforce: "pre",
+        apply: "serve",
+        configureServer(server) {
+            server.middlewares.use((request, response, next) => {
+                const pathname = new URL(request.url ?? "/", "http://nudge-ui.local").pathname;
+                if (pathname === NUDGE_UI_CLIENT_PATH) {
+                    void serveClient(request, response).catch(next);
+                    return;
+                }
+                if (pathname === NUDGE_UI_MANIFEST_PATH) {
+                    void createManifest(server)
+                        .then((manifest) => {
+                        response.statusCode = 200;
+                        response.setHeader("Content-Type", "application/json; charset=utf-8");
+                        response.setHeader("Cache-Control", "no-store");
+                        response.end(JSON.stringify(manifest));
+                    })
+                        .catch(next);
+                    return;
+                }
+                next();
+            });
+        },
+    };
+}
+async function createManifest(server) {
+    // SAFETY: these virtual modules are generated by the shared Nudge UI plugin
+    // with the exact exports described by TokenModule and ComponentModule.
+    const [tokenModule, componentModule] = await Promise.all([
+        server.ssrLoadModule("virtual:design-tokens"),
+        server.ssrLoadModule("virtual:nudge-ui-components"),
+    ]);
+    return {
+        version: 1,
+        revision: 0,
+        runtime: createAstroRuntimeConfig({
+            projectId: tokenModule.nudgeUiProjectId,
+            tokenCatalog: tokenModule.tokenCatalog,
+            tokens: tokenModule.tokens,
+            tokenDiagnostics: tokenModule.tokenDiagnostics,
+            tokenGeneration: tokenModule.tokenGeneration,
+            componentContracts: componentModule.componentContracts,
+        }),
+    };
+}

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

@@ -0,0 +1,3 @@
+export { instrumentRenderedHtml, type HtmlIdentityDiagnostic, type HtmlIdentityDiagnosticCode, type HtmlIdentityResult, type RenderedHtmlIdentityOptions, } from "../../html/identity.js";
+export { nudgeUiAstro, withNudgeUi } from "./integration.js";
+export type { NudgeUiAstroOptions, NudgeUiOptions } from "./integration.js";

package/dist/hosts/astro/index.js

@@ -0,0 +1,2 @@
+export { instrumentRenderedHtml, } from "../../html/identity.js";
+export { nudgeUiAstro, withNudgeUi } from "./integration.js";

package/dist/hosts/astro/integration.d.ts

@@ -0,0 +1,35 @@
+import type { AstroIntegration, AstroUserConfig } from "astro";
+import { type NudgeUiOptions } from "../vite/index.js";
+export type { NudgeUiOptions };
+/**
+ * Options for `nudgeUiAstro`. The token/component knowledge options are
+ * forwarded to the shared Vite plugin unchanged; Astro-specific concerns
+ * (gating, injection, instrumentation) stay internal.
+ */
+export interface NudgeUiAstroOptions extends NudgeUiOptions {
+}
+/**
+ * Nudge UI host Adapter for Astro dev servers (ADR-0011).
+ *
+ * Dev-only by contract (ADR-0002): unless `command === "dev"` and
+ * `enabled !== false`, the integration registers nothing at all — no Vite
+ * plugins, no injected scripts, no middleware — so `astro build` output is
+ * byte-identical to a project without the integration.
+ *
+ * In dev it wires three pieces:
+ * 1. the shared `nudgeUi()` Vite plugin (token knowledge and island JSX
+ *    identity transforms), the client transport, and project context;
+ * 2. one external client script, injected on every rendered page;
+ * 3. an `addMiddleware` response instrumentation that buffers rendered HTML
+ *    responses and adds the response-level identity layer through the
+ *    identity Module.
+ */
+export declare function nudgeUiAstro(options?: NudgeUiAstroOptions): AstroIntegration;
+/**
+ * Adds Nudge UI to an Astro configuration without inspecting its shape.
+ *
+ * This wrapper is the stable installer seam. It works with shorthand,
+ * variable, spread, and computed integration lists because it treats the
+ * configuration as a value rather than rewriting `integrations`.
+ */
+export declare function withNudgeUi(config: AstroUserConfig, options?: NudgeUiAstroOptions): AstroUserConfig;

package/dist/hosts/astro/integration.js

@@ -0,0 +1,96 @@
+import { nudgeUi } from "../vite/index.js";
+import { NUDGE_UI_CLIENT_PATH, NUDGE_UI_MANIFEST_PATH } from "../../transport/index.js";
+import { createAstroClientTransportPlugin, } from "./clientTransport.js";
+import { createProjectContextPlugin } from "./projectContext.js";
+/**
+ * Adds the prebuilt client as an external module. The inspector dependency
+ * graph therefore never enters Astro's Vite optimizer.
+ */
+const BOOTSTRAP_ENTRY_CONTENT = [
+    'if (!document.querySelector("script[data-nudge-ui-client]")) {',
+    '  const script = document.createElement("script");',
+    '  script.type = "module";',
+    `  script.src = ${JSON.stringify(NUDGE_UI_CLIENT_PATH)};`,
+    '  script.setAttribute("data-nudge-ui-client", "");',
+    `  script.dataset.nudgeUiManifest = ${JSON.stringify(NUDGE_UI_MANIFEST_PATH)};`,
+    "  document.head.append(script);",
+    "}",
+].join("\n");
+// Astro loads this URL directly from the installed package. Keep the source
+// suffix for the workspace test/dev path and select the compiled sibling in a
+// published package, where `middleware.ts` is intentionally not shipped.
+const MIDDLEWARE_ENTRYPOINT = new URL(import.meta.url.endsWith(".ts") ? "./middleware.ts" : "./middleware.js", import.meta.url);
+/**
+ * Nudge UI host Adapter for Astro dev servers (ADR-0011).
+ *
+ * Dev-only by contract (ADR-0002): unless `command === "dev"` and
+ * `enabled !== false`, the integration registers nothing at all — no Vite
+ * plugins, no injected scripts, no middleware — so `astro build` output is
+ * byte-identical to a project without the integration.
+ *
+ * In dev it wires three pieces:
+ * 1. the shared `nudgeUi()` Vite plugin (token knowledge and island JSX
+ *    identity transforms), the client transport, and project context;
+ * 2. one external client script, injected on every rendered page;
+ * 3. an `addMiddleware` response instrumentation that buffers rendered HTML
+ *    responses and adds the response-level identity layer through the
+ *    identity Module.
+ */
+export function nudgeUiAstro(options = {}) {
+    const enabled = options.enabled ?? true;
+    const sharedOptions = { ...options };
+    return {
+        name: "nudge-ui",
+        hooks: {
+            "astro:config:setup"({ command, updateConfig, injectScript, addMiddleware }) {
+                if (!enabled || command !== "dev")
+                    return;
+                // The shared plugin objects are plain Vite plugin records, but this
+                // monorepo typechecks them against a different Vite major than the
+                // installed Astro resolves internally; the runtime contract
+                // (config/resolveId/load/transform hooks) is identical.
+                updateConfig({
+                    vite: {
+                        // SAFETY: Astro and this package resolve different Vite type
+                        // versions, but both consume the same runtime Plugin contract.
+                        plugins: [
+                            createAstroClientTransportPlugin(),
+                            ...nudgeUi(sharedOptions),
+                            createProjectContextPlugin(),
+                        ],
+                    },
+                });
+                // The page stage runs on every rendered page. It only appends an
+                // external script; no inspector dependency enters Vite's graph.
+                injectScript("page", BOOTSTRAP_ENTRY_CONTENT);
+                addMiddleware({ entrypoint: MIDDLEWARE_ENTRYPOINT, order: "pre" });
+            },
+        },
+    };
+}
+/**
+ * Adds Nudge UI to an Astro configuration without inspecting its shape.
+ *
+ * This wrapper is the stable installer seam. It works with shorthand,
+ * variable, spread, and computed integration lists because it treats the
+ * configuration as a value rather than rewriting `integrations`.
+ */
+export function withNudgeUi(config, options = {}) {
+    const integrations = config.integrations ?? [];
+    if (containsNudgeUiIntegration(integrations))
+        return config;
+    return {
+        ...config,
+        integrations: [...integrations, nudgeUiAstro(options)],
+    };
+}
+function containsNudgeUiIntegration(integrations) {
+    return integrations.some((integration) => {
+        if (Array.isArray(integration))
+            return containsNudgeUiIntegration(integration);
+        return integration !== false
+            && integration !== null
+            && integration !== undefined
+            && integration.name === "nudge-ui";
+    });
+}

package/dist/hosts/astro/middleware.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Dev-only response instrumentation middleware (ADR-0011).
+ *
+ * Registered through `addMiddleware({ order: "pre" })`, this runs inside
+ * Astro's own middleware chain — before user middleware, around page
+ * rendering. It buffers the rendered HTML response, adds the Nudge UI
+ * identity layer server-side (before any client script can strip Astro's
+ * annotations), and forwards every non-HTML response untouched.
+ *
+ * Identity diagnostics are logged rather than swallowed so degraded identity
+ * (for example a disabled dev toolbar) is observable in the dev server output.
+ */
+export declare const onRequest: (_context: unknown, next: () => Promise<Response>) => Promise<Response>;

package/dist/hosts/astro/middleware.js

@@ -0,0 +1,22 @@
+import { projectRoot } from "virtual:nudge-ui-astro-context";
+import { instrumentAstroResponse } from "./responseInstrumentation.js";
+/**
+ * Dev-only response instrumentation middleware (ADR-0011).
+ *
+ * Registered through `addMiddleware({ order: "pre" })`, this runs inside
+ * Astro's own middleware chain — before user middleware, around page
+ * rendering. It buffers the rendered HTML response, adds the Nudge UI
+ * identity layer server-side (before any client script can strip Astro's
+ * annotations), and forwards every non-HTML response untouched.
+ *
+ * Identity diagnostics are logged rather than swallowed so degraded identity
+ * (for example a disabled dev toolbar) is observable in the dev server output.
+ */
+export const onRequest = async (_context, next) => {
+    const response = await next();
+    const result = await instrumentAstroResponse(response, projectRoot === "" ? undefined : projectRoot);
+    for (const diagnostic of result.diagnostics) {
+        console.warn(`[nudge-ui] ${diagnostic.code}: ${diagnostic.message}`);
+    }
+    return result.response;
+};

package/dist/hosts/astro/projectContext.d.ts

@@ -0,0 +1,11 @@
+import type { Plugin } from "vite";
+/**
+ * Supplies the dev-only server context (project root) to the instrumentation
+ * middleware through a virtual module.
+ *
+ * The middleware entrypoint is loaded by Astro's SSR pipeline, where no
+ * integration hook argument is available; the Vite-resolved project root is
+ * therefore published as a module value instead of being read from ambient
+ * process state.
+ */
+export declare function createProjectContextPlugin(): Plugin;

package/dist/hosts/astro/projectContext.js

@@ -0,0 +1,34 @@
+const VIRTUAL_CONTEXT_ID = "virtual:nudge-ui-astro-context";
+const RESOLVED_CONTEXT_ID = `\0${VIRTUAL_CONTEXT_ID}`;
+/**
+ * Supplies the dev-only server context (project root) to the instrumentation
+ * middleware through a virtual module.
+ *
+ * The middleware entrypoint is loaded by Astro's SSR pipeline, where no
+ * integration hook argument is available; the Vite-resolved project root is
+ * therefore published as a module value instead of being read from ambient
+ * process state.
+ */
+export function createProjectContextPlugin() {
+    let projectRoot;
+    return {
+        name: "nudge-ui-astro-context",
+        apply: "serve",
+        configResolved(config) {
+            projectRoot = config.root;
+        },
+        resolveId(id) {
+            if (id === VIRTUAL_CONTEXT_ID || id === RESOLVED_CONTEXT_ID) {
+                return RESOLVED_CONTEXT_ID;
+            }
+            return null;
+        },
+        load(id) {
+            if (id !== RESOLVED_CONTEXT_ID)
+                return null;
+            // An empty root degrades to undefined so annotation paths forward
+            // unchanged instead of relativizing against the wrong base.
+            return `export const projectRoot = ${JSON.stringify(projectRoot ?? "")};\n`;
+        },
+    };
+}

package/dist/hosts/astro/responseInstrumentation.d.ts

@@ -0,0 +1,41 @@
+import { instrumentRenderedHtml, type HtmlIdentityDiagnostic } from "../../html/identity.js";
+/**
+ * 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.
+ */
+export declare function isHtmlContentType(contentType: string | undefined): boolean;
+/** The instrumented response plus the identity diagnostics it produced. */
+export interface InstrumentedAstroResponse {
+    /** A response safe to hand back to Astro. */
+    readonly response: Response;
+    /** Identity diagnostics in source order; empty for untouched responses. */
+    readonly diagnostics: readonly HtmlIdentityDiagnostic[];
+}
+/**
+ * The identity transform applied to an eligible HTML body. Injectable so the
+ * failure-tolerance suite can drive the catch branch through a real seam
+ * instead of replacing the identity module wholesale.
+ */
+export type AstroHtmlInstrumenter = typeof instrumentRenderedHtml;
+/**
+ * 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.
+ */
+export declare function instrumentAstroResponse(response: Response, projectRoot: string | undefined, instrument?: AstroHtmlInstrumenter): Promise<InstrumentedAstroResponse>;

package/dist/hosts/astro/responseInstrumentation.js

@@ -0,0 +1,80 @@
+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.
+ */
+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.
+ */
+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.
+ */
+export async function instrumentAstroResponse(response, projectRoot, instrument = instrumentRenderedHtml) {
+    const contentType = response.headers.get("content-type") ?? undefined;
+    if (!isHtmlContentType(contentType))
+        return { response, diagnostics: [] };
+    if (response.body === null)
+        return { response, diagnostics: [] };
+    let source;
+    try {
+        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.
+        return { response, diagnostics: [] };
+    }
+    try {
+        const result = instrument(source, { projectRoot });
+        const headers = new Headers(response.headers);
+        headers.set("content-length", String(HTML_BYTE_LENGTH_ENCODER.encode(result.html).length));
+        return {
+            response: new Response(result.html, {
+                status: response.status,
+                statusText: response.statusText,
+                headers,
+            }),
+            diagnostics: result.diagnostics,
+        };
+    }
+    catch {
+        // Identity extraction must never break a dev page load; forward the
+        // untouched body instead.
+        return {
+            response: new Response(source, {
+                status: response.status,
+                statusText: response.statusText,
+                headers: response.headers,
+            }),
+            diagnostics: [],
+        };
+    }
+}

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

@@ -0,0 +1,4 @@
+export { withNudgeUi, type NudgeUiNextConfig, type NudgeUiNextOptions, type RewritesShape, type RewritesSource, } from "./wrapper.js";
+export { buildManifest, nextjsProjectId, type NudgeUiManifest } from "./manifest.js";
+export { ensureSidecar, clearStaleSidecarState, type SidecarHandle, } from "./sidecar.js";
+export { transformNextModuleSource, hasUseClientDirective, directivePrologueEnd, instrumentRootLayout, type NextModuleTransformOptions, type NextModuleTransformResult, } from "./loader.js";

package/dist/hosts/next/index.js

@@ -0,0 +1,7 @@
+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.

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

@@ -0,0 +1,66 @@
+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.
+     */
+    root?: string;
+    /**
+     * Directory name of the Pages Router route root. Modules resolved 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.
+ */
+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.
+ */
+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.
+ */
+export declare function directivePrologueEnd(source: string): number;