nudge-ui 0.2.4 → 0.2.6

package/dist/css/value-semantics/structuredValues.js

@@ -1,4 +1,4 @@
-import { splitTopLevelWhitespace, topLevelSlashIndex } from "./cssSyntax.js";
+import { isSingleVarReference, splitTopLevelWhitespace, topLevelSlashIndex } from "./cssSyntax.js";
 import { parseBorderComponents } from "./borderSemantics.js";
 import { parseFontShorthand } from "./fontSemantics.js";
 import { normalizeOpacityPercent } from "./colorSemantics.js";
@@ -76,17 +76,12 @@ function fieldFor(property, declaredValue, sourceProperty, ctx) {
         capability: classifyEditCapability(property, declaredValue),
     });
 }
-/**
- * Expands authored raw values into per-position entries, deriving each
- * component's token interpretation once. A bare `var()` whose resolved value
- * is multiple lengths expands into multiple positions, preserving the token
- * on every one.
- */
+/** A multi-length `var()` expands into one position per length, each keeping the token. */
 function expandPositionValues(rawValues, ctx) {
     return rawValues.flatMap((rawValue) => {
         const res = interpretTokenValue(rawValue, ctx.tokenContext);
         const tokenValues = res.tokenName ? splitTopLevelWhitespace(res.resolvedValue) : [];
-        if (res.tokenName && /^var\(\s*--[\w-]+(?:\s*,[\s\S]*)?\s*\)$/.test(rawValue) && tokenValues.length > 1) {
+        if (res.tokenName && isSingleVarReference(rawValue) && tokenValues.length > 1) {
             return tokenValues.map((resolvedValue) => ({
                 declaredValue: rawValue,
                 resolvedValue,
@@ -114,7 +109,7 @@ function expandBorder(lower, property, authored, ctx) {
     const sourceProperty = lower;
     const sidePrefix = sourceProperty === "border" ? "" : `${sourceProperty}-`;
     // Interpret each distinct component once; every projected longhand reuses
-    // that component result rather than resolving the same token repeatedly.
+    // that component result instead of re-resolving the same token.
     const { widthResult, styleResult, colorResult } = components;
     const scopedStructure = {
         kind: "border",
@@ -197,13 +192,7 @@ function expandGap(property, axes, authored, ctx) {
         return null;
     return axes.map((longhand, index) => projectPositionField(longhand, property, axisValues[index]));
 }
-/**
- * Interprets one authored value for a property into a structured projection
- * tree. Returns the projected fields, or a single conservative raw/composite
- * field when the value cannot be decomposed faithfully. The declared order of
- * the families mirrors CSS projection precedence: logical sides, border, font,
- * border-radius corners, gap, physical spacing, then the raw fallback.
- */
+/** Values that cannot be decomposed faithfully collapse to one conservative raw/composite field; families are checked in CSS precedence order. */
 export function interpretValue(property, authored, ctx) {
     const lower = property.toLowerCase();
     if (lower === "opacity")
@@ -246,5 +235,5 @@ export function interpretValue(property, authored, ctx) {
     }
     return [rawField(property, authored, ctx)];
 }
-/** @internal Use the package-level `interpretValue` Interface in production. */
+/** @internal Use `interpretValue` in production. */
 export const interpretStructuredValue = interpretValue;

package/dist/css/value-semantics/tokenInterpretation.d.ts

@@ -1,27 +1,5 @@
-/**
- * Token-reference, alias, and modifier interpretation (plan slice 3.2).
- *
- * This is the deep value-semantics Module for token attribution: it turns one
- * CSSOM-authored value into the structured token facts an inspector needs —
- * the primary field token, every referenced token with its origin, the leaf
- * token behind chained aliases, explicit modifiers (fallbacks and alpha), and
- * a `cycle` diagnostic when alias traversal loops.
- *
- * Interface invariants:
- * - the Module never touches the DOM or CSSOM; the token table, local
- *   aliases, color/opacity reading, direct-literal attribution, and alias
- *   attribution are all explicit inputs (`TokenInterpretationContext`);
- * - the primary token, all referenced tokens, and implementation aliases stay
- *   distinct;
- * - alias cycles terminate and surface a `cycle` diagnostic;
- * - arbitrary input does not throw through `interpretTokenValue`;
- * - framework-specific policy — Tailwind `--tw-*` aliases, adapter-derived
- *   token origins, direct Tailwind v3 color attribution — is injected by the
- *   integration, never encoded here.
- */
 import type { ColorOpacity, ColorValueFacts, TokenEntry, TokenOrigin, TokenReference, TokenTable, ValueModifier } from "../model/index.js";
 export { extractVarCalls } from "./cssSyntax.js";
-/** The structured token interpretation of one authored CSSOM value. */
 export interface TokenValueInterpretation {
     /** The primary field token, or null when no non-alpha token is primary. */
     tokenName: string | null;
@@ -29,30 +7,22 @@ export interface TokenValueInterpretation {
     resolvedValue: string;
     /** Every referenced token (primary, fallback, opacity), deduped, with origin. */
     tokens: TokenReference[];
-    /** Normalized opacity when the value carries an alpha component. */
     opacity?: ColorOpacity;
-    /** Color-shape facts projected to UI without reparsing authored expressions there. */
+    /** Color-shape facts projected for the UI. */
     color: ColorValueFacts;
-    /** Explicit fallback and alpha modifiers derived from the authored value. */
     modifiers: ValueModifier[];
     /** The token reached after traversing chained aliases from `tokenName`. */
     leafTokenName: string | null;
-    /** The alias reference that repeated during traversal, when a cycle exists. */
+    /** The alias reference that repeated, when a cycle exists. */
     cycle?: string;
 }
-/** The interpretation of a token's own value after alias traversal. */
 export interface AliasInnerResult {
     tokenName: string | null;
     resolvedValue: string;
     leafTokenName: string | null;
     cycle?: string;
 }
-/**
- * How a local alias reference is attributed after its value is resolved.
- * The neutral default authors the alias name itself; the Tailwind `--tw-*`
- * policy (attributing to the catalog token an implementation alias points at)
- * is supplied by the integration.
- */
+/** Attribution policy for a local alias reference; framework-specific behaviour is injected. */
 export interface AliasAttribution {
     known: boolean;
     tokenName: string | null;
@@ -60,31 +30,19 @@ export interface AliasAttribution {
     leafTokenName: string | null;
     cycle?: string;
 }
-/** Facts the token interpretation needs that are not part of the authored text. */
 export interface TokenInterpretationContext {
     /** Resolved token table (custom-property name → entry). */
     table: TokenTable;
     /** Local aliases collected from the selected element's cascade. */
     localAliases?: ReadonlyMap<string, string>;
-    /**
-     * Direct literal attribution: a token entry matched to the authored value
-     * before var() interpretation (integration policy, e.g. Tailwind v3 config
-     * tokens). Absent when no direct attribution applies.
-     */
+    /** Direct literal attribution before var() interpretation (e.g. Tailwind v3 config tokens). */
     resolveDirectToken?: (value: string) => TokenEntry | undefined;
-    /** Token-origin derivation. Default: `entry.origin ?? "project"` (undefined → "runtime"). */
+    /** Defaults to `entry.origin ?? "project"`. */
     resolveOrigin?: (entry: TokenEntry | undefined) => TokenOrigin;
-    /** Local-alias attribution policy. Default attributes the alias reference itself. */
+    /** Default attributes the alias reference itself. */
     resolveAlias?: (ref: string, inner: AliasInnerResult) => AliasAttribution;
 }
-/**
- * Neutral token-origin derivation. Adapter-name heuristics ("tailwind-v3"
- * → "framework", "vanilla-extract" → "project") remain integration policy.
- */
+/** Neutral derivation; adapter-name heuristics stay integration policy. */
 export declare function defaultTokenOrigin(entry: TokenEntry | undefined): TokenOrigin;
-/**
- * Interprets the token references, aliases, and modifiers of one authored
- * CSSOM value against explicit token knowledge. Returns the primary token,
- * every referenced token, the leaf token, modifiers, and a cycle diagnostic.
- */
+/** Interprets token references, aliases, and modifiers against explicit token knowledge. */
 export declare function interpretTokenValue(value: string, ctx: TokenInterpretationContext): TokenValueInterpretation;

package/dist/css/value-semantics/tokenInterpretation.js

@@ -2,10 +2,7 @@ import { interpretColorValue, } from "./colorSemantics.js";
 export { extractVarCalls } from "./cssSyntax.js";
 import { extractVarCalls } from "./cssSyntax.js";
 const EMPTY_LOCAL_ALIASES = new Map();
-/**
- * Neutral token-origin derivation. Adapter-name heuristics ("tailwind-v3"
- * → "framework", "vanilla-extract" → "project") remain integration policy.
- */
+/** Neutral derivation; adapter-name heuristics stay integration policy. */
 export function defaultTokenOrigin(entry) {
     if (!entry)
         return "runtime";
@@ -59,11 +56,7 @@ function resolveTokenValueInner(value, table, visited, localAliases, ctx) {
     }
     return { tokenName: null, resolvedValue: trimmed, leafTokenName: null };
 }
-/**
- * Interprets the token references, aliases, and modifiers of one authored
- * CSSOM value against explicit token knowledge. Returns the primary token,
- * every referenced token, the leaf token, modifiers, and a cycle diagnostic.
- */
+/** Interprets token references, aliases, and modifiers against explicit token knowledge. */
 export function interpretTokenValue(value, ctx) {
     const authored = value.trim();
     const table = ctx.table;
@@ -122,11 +115,10 @@ export function interpretTokenValue(value, ctx) {
     if (opacity)
         modifiers.push({ kind: "alpha", value: opacity.value });
     const inner = resolveTokenValueInner(authored, table, new Set(), localAliases, ctx);
-    // An alpha variable is still a token reference, but it is not the color
-    // token represented by the field. For example, in
-    // `rgb(37 99 235 / var(--opacity-muted))`, the color is literal and only
-    // the opacity is token-backed. Keep that distinction in `tokenName` so the
-    // UI can render a base color chip only when one actually exists.
+    // An alpha variable is still a token reference, but it is not the field's
+    // color token (`rgb(37 99 235 / var(--opacity-muted))` is literal color plus
+    // token-backed alpha). Keeping that distinction lets the UI render a base
+    // color chip only when one actually exists.
     const alphaTokenName = opacity?.tokenName;
     const baseKnown = firstKnown && firstKnown.tokenName !== alphaTokenName ? firstKnown : null;
     const baseInner = inner.tokenName && inner.tokenName !== alphaTokenName ? inner : null;
@@ -149,13 +141,7 @@ export function interpretTokenValue(value, ctx) {
         cycle: primary?.cycle,
     };
 }
-/**
- * Resolves a `var()` component of a color expression (for example an opacity
- * token) through the same interpretation context as the authored value. This
- * is what the color Module's `interpretColorOpacity` uses to attribute
- * token-backed alpha components, keeping alias and framework attribution in
- * the token interpretation.
- */
+/** Resolves a `var()` component (e.g. an opacity token) through the same context as the authored value. */
 function resolveComponentReference(value, ctx) {
     const calls = extractVarCalls(value);
     if (calls.length === 0)

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

@@ -7,6 +7,5 @@ interface AstroRuntimeKnowledge {
     readonly tokenGeneration: string;
     readonly componentContracts: NudgeUiRuntimeConfig["componentContracts"];
 }
-/** Builds the runtime knowledge shared by both Astro client transports. */
 export declare function createAstroRuntimeConfig(knowledge: AstroRuntimeKnowledge): NudgeUiRuntimeConfig;
 export {};

package/dist/hosts/astro/astroRuntimeConfig.js

@@ -4,7 +4,6 @@ const ASTRO_SOURCE_COORDINATES = {
     exactCidPrefixes: ["astro:"],
     exactFileExtensions: [".astro", ".html", ".htm"],
 };
-/** Builds the runtime knowledge shared by both Astro client transports. */
 export function createAstroRuntimeConfig(knowledge) {
     return {
         projectId: knowledge.projectId,

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

@@ -3,10 +3,6 @@ interface ClientAssetDependencies {
     readonly resolveClientPath?: () => string;
     readonly readClientFile?: (path: string) => Promise<Buffer>;
 }
-/**
- * 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.
- */
+/** Resolution and reads stay lazy so disabled and production integrations never need the development asset. */
 export declare function createAstroClientAssetHandler(dependencies?: ClientAssetDependencies): (request: IncomingMessage, response: ServerResponse) => Promise<void>;
 export {};

package/dist/hosts/astro/clientAsset.js

@@ -2,11 +2,7 @@ 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.
- */
+/** Resolution and reads stay lazy so disabled and production integrations never need the development asset. */
 export function createAstroClientAssetHandler(dependencies = {}) {
     const resolveClientPath = dependencies.resolveClientPath
         ?? (() => packageRequire.resolve("nudge-ui/internal/client"));

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

@@ -1,3 +1,2 @@
 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

@@ -1,19 +1,16 @@
 import { handleHtmlArtifactRequest } from "../../project/artifacts.js";
-import {} from "../../inspector/clientManifest.js";
+import { createNudgeUiClientManifest, } from "../../inspector/clientManifest.js";
 import { createAstroRuntimeConfig } from "./astroRuntimeConfig.js";
 import { createAstroClientAssetHandler } from "./clientAsset.js";
 import { NUDGE_UI_CLIENT_PATH, NUDGE_UI_EDITOR_PATH, NUDGE_UI_MANIFEST_PATH, createNudgeUiEditorDocument, isNudgeUiEditorDocumentRequest, } from "../../transport/index.js";
 import { startOptionalProjectBridge } from "../projectBridge.js";
 import { automationManifestFields } from "../environment.js";
 const serveClient = createAstroClientAssetHandler();
-/** Serves the prebuilt client and its host-neutral manifest in Astro dev. */
 export function createAstroClientTransportPlugin() {
     let projectBridge = null;
     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.
+        // Installed before the shared Vite plugin so Astro's own manifest handler answers /__nudge_ui__/manifest.
         enforce: "pre",
         apply: "serve",
         configureServer(server) {
@@ -89,13 +86,11 @@ async function createManifest(server, request, setBridge) {
         })
         : null;
     setBridge(bridge);
-    return {
-        version: 1,
-        revision: 0,
+    return createNudgeUiClientManifest({
         runtime,
         ...(bridge ? { agentBridge: bridge.browser } : {}),
         ...automationManifestFields(),
-    };
+    });
 }
 function resolvedRequestOrigin(server, request) {
     const host = request.headers.host;

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

@@ -1,35 +1,9 @@
 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"`,
- * `enabled !== false`, and `NUDGE_UI` is not `0`, 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.
- */
+/** Dev-only by contract: outside `command === "dev"` with Nudge UI enabled, nothing is registered, so `astro build` output is byte-identical to a project without the integration. */
 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`.
- */
+/** Treats the configuration as a value, so shorthand, variable, spread and computed integration lists all work. */
 export declare function withNudgeUi(config: AstroUserConfig, options?: NudgeUiAstroOptions): AstroUserConfig;

package/dist/hosts/astro/integration.js

@@ -5,10 +5,7 @@ import { createAstroClientTransportPlugin, } from "./clientTransport.js";
 import { createProjectContextPlugin } from "./projectContext.js";
 import { isNudgeUiEnabled } from "../environment.js";
 import { installMarkdownIdentity } from "./markdownIdentity.js";
-/**
- * Adds the prebuilt client as an external module. The inspector dependency
- * graph therefore never enters Astro's Vite optimizer.
- */
+/** Loads the prebuilt client as an external module so the inspector graph never enters Astro's Vite optimizer. */
 const BOOTSTRAP_ENTRY_CONTENT = [
     'if (!document.querySelector("script[data-nudge-ui-client]")) {',
     '  const script = document.createElement("script");',
@@ -19,26 +16,10 @@ const BOOTSTRAP_ENTRY_CONTENT = [
     "  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.
+// Astro loads this URL directly from the installed package: the .ts sibling serves
+// workspace dev, while the compiled .js sibling ships in the published package.
 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"`,
- * `enabled !== false`, and `NUDGE_UI` is not `0`, 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.
- */
+/** Dev-only by contract: outside `command === "dev"` with Nudge UI enabled, nothing is registered, so `astro build` output is byte-identical to a project without the integration. */
 export function nudgeUiAstro(options = {}) {
     const enabled = isNudgeUiEnabled(options.enabled);
     const sharedOptions = { ...options };
@@ -49,10 +30,8 @@ export function nudgeUiAstro(options = {}) {
                 if (!enabled || command !== "dev")
                     return;
                 const markdown = installMarkdownIdentity(config.markdown, fileURLToPath(config.root));
-                // 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.
+                // Plain Vite plugin records; the monorepo typechecks them against a different Vite
+                // major than Astro resolves, but the runtime contract is identical.
                 updateConfig({
                     ...(markdown ? { markdown } : {}),
                     vite: {
@@ -65,21 +44,13 @@ export function nudgeUiAstro(options = {}) {
                         ],
                     },
                 });
-                // 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`.
- */
+/** Treats the configuration as a value, so shorthand, variable, spread and computed integration lists all work. */
 export function withNudgeUi(config, options = {}) {
     const integrations = config.integrations ?? [];
     if (containsNudgeUiIntegration(integrations))

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

@@ -1,9 +1,7 @@
 import type { Element, Root } from "hast";
-/** Adds authored Markdown positions through the remark/rehype pipeline. */
 export declare function createMarkdownIdentityPlugin(projectRoot: string): () => (tree: Root, file: {
     path?: string;
 }) => void;
-/** Adds the same identity through Astro's Sätteri visitor API. */
 export declare function createSatteriIdentityPlugin(projectRoot: string): {
     name: string;
     options: {
@@ -17,7 +15,6 @@ export declare function createSatteriIdentityPlugin(projectRoot: string): {
         }): void;
     };
 };
-/** Extends supported processors without replacing the consumer's pipeline. */
 export declare function installMarkdownIdentity(markdown: {
     processor?: {
         name: string;

package/dist/hosts/astro/markdownIdentity.js

@@ -21,7 +21,6 @@ function attributesFor(node, file, projectRoot) {
     }
     return attributes;
 }
-/** Adds authored Markdown positions through the remark/rehype pipeline. */
 export function createMarkdownIdentityPlugin(projectRoot) {
     return function nudgeMarkdownIdentity() {
         return (tree, file) => {
@@ -41,7 +40,6 @@ export function createMarkdownIdentityPlugin(projectRoot) {
         };
     };
 }
-/** Adds the same identity through Astro's Sätteri visitor API. */
 export function createSatteriIdentityPlugin(projectRoot) {
     return {
         name: "nudge-ui-markdown-identity",
@@ -61,7 +59,6 @@ export function createSatteriIdentityPlugin(projectRoot) {
         },
     };
 }
-/** Extends supported processors without replacing the consumer's pipeline. */
 export function installMarkdownIdentity(markdown, projectRoot) {
     const processor = markdown.processor;
     if (!processor)

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

@@ -1,13 +1,2 @@
-/**
- * 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.
- */
+/** Runs at `order: "pre"` so identity lands before any client script can strip Astro's annotations. */
 export declare const onRequest: (_context: unknown, next: () => Promise<Response>) => Promise<Response>;

package/dist/hosts/astro/middleware.js

@@ -1,17 +1,6 @@
 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.
- */
+/** Runs at `order: "pre"` so identity lands before any client script can strip Astro's annotations. */
 export const onRequest = async (_context, next) => {
     const response = await next();
     const result = await instrumentAstroResponse(response, projectRoot === "" ? undefined : projectRoot);

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

@@ -1,11 +1,3 @@
 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.
- */
+/** The middleware entrypoint has no integration hook argument, so the Vite-resolved root is published as a module value. */
 export declare function createProjectContextPlugin(): Plugin;

package/dist/hosts/astro/projectContext.js

@@ -1,14 +1,6 @@
 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.
- */
+/** The middleware entrypoint has no integration hook argument, so the Vite-resolved root is published as a module value. */
 export function createProjectContextPlugin() {
     let projectRoot;
     return {
@@ -26,8 +18,7 @@ export function createProjectContextPlugin() {
         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.
+            // Empty root degrades to undefined so annotation paths stay unchanged.
             return `export const projectRoot = ${JSON.stringify(projectRoot ?? "")};\n`;
         },
     };

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

@@ -1,41 +1,12 @@
 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.
- */
+/** Only `text/html` (with optional parameters such as charset) is eligible; everything else passes 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. */
+    /** 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.
- */
+/** Injectable so failure handling can be driven through a real seam rather than by replacing the identity module. */
 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.
- */
+/** HTML bodies are materialized once to re-emit with a corrected Content-Length; every other response is returned by reference, stream untouched. */
 export declare function instrumentAstroResponse(response: Response, projectRoot: string | undefined, instrument?: AstroHtmlInstrumenter): Promise<InstrumentedAstroResponse>;