nudge-ui 0.2.4 → 0.2.6

package/dist/compiler/reactIdentity.js

@@ -3,6 +3,7 @@ import { posix } from "node:path";
 import { elementName, isNode, jsxMemberName, parseModule, SKIP_KEYS, } from "./ast.js";
 import { createComponentInstrumentationPolicy, } from "./componentInstrumentation.js";
 import { relativePath, stripModuleExtension } from "./sourcePaths.js";
+import { IDENTITY_ATTRIBUTES } from "./identityAttributes.js";
 export const DEFAULT_COMPONENT_RUNTIME_MODULE = "nudge-ui/internal/component-runtime";
 const PARSEABLE_EXT = /\.(tsx|jsx)$/;
 const EXPRESSION_SCOPE_TYPES = new Set([
@@ -10,15 +11,12 @@ const EXPRESSION_SCOPE_TYPES = new Set([
     "ArrowFunctionExpression",
     "ClassExpression",
 ]);
-// Scopes that contribute an id to the scope stack: declarations push their
-// own name; expressions are pushed at their VariableDeclarator binding, or
-// here by their own id (may be null) when anonymous.
 const ALL_SCOPE_TYPES = new Set([
     "FunctionDeclaration",
     "ClassDeclaration",
     ...EXPRESSION_SCOPE_TYPES,
 ]);
-const IDENTITY_ATTRS = new Set(["data-cid", "data-src", "data-cprops"]);
+const IDENTITY_ATTRS = new Set(IDENTITY_ATTRIBUTES);
 function isComponentName(name) {
     return /^[A-Z]/.test(name);
 }
@@ -78,9 +76,7 @@ function serialiseAttribute(attr) {
         if (expr.type === "BooleanLiteral") {
             return `${key}:${expr.value ? "true" : "false"}`;
         }
-        // Inline function expressions are rendered as `fn(key)` per PLAN.md.
-        // Bare identifiers are omitted (they may reference any type — PLAN.md's
-        // canonical example omits `onClick={handleClick}`).
+        // Inline functions render as `fn(key)`; bare identifiers and other expressions are omitted.
         if (expr.type === "ArrowFunctionExpression" ||
             expr.type === "FunctionExpression") {
             return `${key}:fn(${key})`;
@@ -135,11 +131,7 @@ function authoredPropKinds(attrs, children = []) {
         result.children = childKind;
     return result;
 }
-/**
- * Preserve the authored shape of primitive JSX children in invocation
- * metadata. This is metadata for the dev runtime only; it does not add a
- * production attribute or wrapper to the application output.
- */
+/** Dev-runtime metadata only; nothing here reaches production output. */
 function authoredChildrenKind(children) {
     if (children.length === 0)
         return null;
@@ -193,9 +185,7 @@ function walkChildren(node, scopeStack, ms, relPath, options, state, allowCompon
         if (Array.isArray(value)) {
             for (const child of value) {
                 if (isNode(child)) {
-                    // A component can inspect its children or slot props before React
-                    // renders them. Preserve those element values unless the receiving
-                    // interface explicitly promises to render them.
+                    // A component may inspect children or slot props before rendering them; only promised slots are traversed.
                     const renderedChild = !customElement
                         || (key === "children" && state.componentPolicy.rendersChildren(componentName))
                         || (key === "attributes" && state.componentPolicy.rendersProp(componentName, elementName(child.name) ?? ""))
@@ -210,8 +200,7 @@ function walkChildren(node, scopeStack, ms, relPath, options, state, allowCompon
     }
 }
 function walk(node, parent, scopeStack, ms, relPath, options, state, allowComponentWrapping) {
-    // A function/class expression bound to a variable inherits the variable's
-    // name as its component name (arrows have no own id).
+    // A function/class expression inherits the variable's name as its component name (arrows have no own id).
     if (node.type === "VariableDeclarator") {
         const init = node.init ?? null;
         const varName = node.id?.name ?? null;
@@ -223,13 +212,12 @@ function walk(node, parent, scopeStack, ms, relPath, options, state, allowCompon
         }
     }
     if (ALL_SCOPE_TYPES.has(node.type)) {
-        // Named/anonymous function and class scopes: push their own id (may be null).
         scopeStack.push(getScopeName(node));
         walkChildren(node, scopeStack, ms, relPath, options, state, allowComponentWrapping);
         scopeStack.pop();
         return;
     }
-    if (node.type === "JSXElement" && options.instrumentComponents && allowComponentWrapping) {
+    if (node.type === "JSXElement" && options.instrumentComponents) {
         const opening = node.openingElement;
         const openingName = opening?.name;
         const componentName = elementName(openingName);
@@ -238,14 +226,11 @@ function walk(node, parent, scopeStack, ms, relPath, options, state, allowCompon
         const loc = openingName?.loc;
         const line = loc?.start?.line;
         const column = loc?.start?.column;
+        const attrs = opening?.attributes ?? [];
         if (componentName
             && (isComponentName(componentName) || componentName.includes("."))
-            && state.componentPolicy.canWrap(componentName)
-            && typeof start === "number"
-            && typeof end === "number"
             && typeof line === "number"
             && typeof column === "number") {
-            const attrs = opening?.attributes ?? [];
             const meta = {
                 callsiteId: `${relPath}:${line}:${column + 1}`,
                 componentId: state.componentPolicy.componentId(componentName)
@@ -256,25 +241,28 @@ function walk(node, parent, scopeStack, ms, relPath, options, state, allowCompon
                 column: column + 1,
                 authoredProps: authoredPropKinds(attrs, node.children ?? []),
             };
-            const needsExpression = parent?.type === "JSXElement" || parent?.type === "JSXFragment";
-            // appendRight preserves insertion order when two JSX siblings have no
-            // whitespace between them. At the shared `</First><Second>` boundary,
-            // the first component's closing wrapper must be emitted before the
-            // second component's opening wrapper.
-            ms.appendRight(start, `${needsExpression ? "{" : ""}__nudgeUiInstrumentComponent(`);
-            ms.appendRight(end, `, ${JSON.stringify(meta)})${needsExpression ? "}" : ""}`);
-            state.changed = true;
-            state.instrumentedComponents = true;
+            if (allowComponentWrapping
+                && state.componentPolicy.canWrap(componentName)
+                && typeof start === "number"
+                && typeof end === "number") {
+                const needsExpression = parent?.type === "JSXElement" || parent?.type === "JSXFragment";
+                // appendRight preserves insertion order at a shared `</First><Second>` boundary.
+                ms.appendRight(start, `${needsExpression ? "{" : ""}__nudgeUiInstrumentComponent(`);
+                ms.appendRight(end, `, ${JSON.stringify(meta)})${needsExpression ? "}" : ""}`);
+                state.changed = true;
+                state.instrumentedComponents = true;
+            }
+            else if (!hasAttr(attrs, "data-src")) {
+                // Not safe to wrap; the injected `data-src` still reaches the component's props, which is all the runtime needs to name it.
+                state.registeredCallsites.push(meta);
+                state.changed = true;
+            }
         }
     }
     if (node.type === "JSXOpeningElement") {
         const attrs = node.attributes ?? [];
         const nameNode = node.name;
-        // TypeScript JSX type arguments sit between the component name and its
-        // attributes (`<Button<Props> size="small" />`). Injecting immediately
-        // after the name would produce the invalid `<Button data-cid...<Props>`
-        // shape, so place identity attributes after the complete type argument
-        // list when one is present.
+        // JSX type arguments (`<Button<Props> size="small" />`) must stay adjacent to the name, so attributes go after the complete type argument list.
         const typeArguments = node.typeArguments ??
             node.typeParameters;
         const end = typeArguments?.end ??
@@ -321,19 +309,29 @@ export function injectIdentity(code, id, root, options = {}) {
         changed: false,
         instrumentedComponents: false,
         componentPolicy: createComponentInstrumentationPolicy(ast, options),
+        registeredCallsites: [],
     };
     walk(ast, null, [], ms, relPath, options, state, true);
     if (!state.changed)
         return null;
-    if (state.instrumentedComponents) {
-        const runtimeModule = options.componentRuntimeModule ?? DEFAULT_COMPONENT_RUNTIME_MODULE;
-        ms.prepend(`import { instrumentReactComponent as __nudgeUiInstrumentComponent } from ${JSON.stringify(runtimeModule)};\n`);
-    }
+    const prelude = componentRuntimePrelude(options.componentRuntimeModule ?? DEFAULT_COMPONENT_RUNTIME_MODULE, state);
+    if (prelude)
+        ms.prepend(prelude);
     return {
         code: ms.toString(),
         map: ms.generateMap({ source: id, hires: true }),
+        prelude,
     };
 }
-export function injectDataCid(code, id, root) {
-    return injectIdentity(code, id, root);
+function componentRuntimePrelude(runtimeModule, state) {
+    const bindings = [
+        ...(state.instrumentedComponents ? ["instrumentReactComponent as __nudgeUiInstrumentComponent"] : []),
+        ...(state.registeredCallsites.length > 0 ? ["registerReactCallsites as __nudgeUiRegisterCallsites"] : []),
+    ];
+    if (bindings.length === 0)
+        return null;
+    const registration = state.registeredCallsites.length > 0
+        ? ` __nudgeUiRegisterCallsites(${JSON.stringify(state.registeredCallsites)});`
+        : "";
+    return `import { ${bindings.join(", ")} } from ${JSON.stringify(runtimeModule)};${registration}\n`;
 }

package/dist/compiler/sourcePaths.d.ts

@@ -1,12 +1,8 @@
-/** Strip a TypeScript or JavaScript module extension from a resolved path. */
 export declare function stripModuleExtension(value: string): string;
 /**
- * Project-relative source path used by `data-src`, callsite identity, and
- * catalog keys.
- *
- * A file outside the project root (an authored workspace package) keeps a
- * `../`-prefixed relative path, so identity stays unique across packages and
- * machine paths never reach the DOM or a prompt. Every host Adapter reads this
- * function so their identity strings cannot drift.
+ * The one component identity format: extensionless module source, a `#` marker,
+ * then the export name. Identity and policy both match on this exact string.
  */
+export declare function componentIdentity(moduleSource: string, exportName: string): string;
+/** Project-relative identity path; files outside the root keep a `../` prefix so ids stay unique and machine paths never reach the DOM or a prompt. */
 export declare function relativePath(id: string, root?: string): string;

package/dist/compiler/sourcePaths.js

@@ -1,17 +1,15 @@
 import { posix } from "node:path";
-/** Strip a TypeScript or JavaScript module extension from a resolved path. */
 export function stripModuleExtension(value) {
     return value.replace(/\.(?:d\.)?[cm]?[jt]sx?$/, "");
 }
 /**
- * Project-relative source path used by `data-src`, callsite identity, and
- * catalog keys.
- *
- * A file outside the project root (an authored workspace package) keeps a
- * `../`-prefixed relative path, so identity stays unique across packages and
- * machine paths never reach the DOM or a prompt. Every host Adapter reads this
- * function so their identity strings cannot drift.
+ * The one component identity format: extensionless module source, a `#` marker,
+ * then the export name. Identity and policy both match on this exact string.
  */
+export function componentIdentity(moduleSource, exportName) {
+    return `${stripModuleExtension(moduleSource)}#${exportName}`;
+}
+/** Project-relative identity path; files outside the root keep a `../` prefix so ids stay unique and machine paths never reach the DOM or a prompt. */
 export function relativePath(id, root) {
     if (root) {
         const rootPrefix = root.endsWith("/") ? root : `${root}/`;

package/dist/css/dialects/index.d.ts

@@ -2,43 +2,28 @@ import type { TokenCatalogDiagnostic } from "../model/index.js";
 import type { InventoryDiagnostic, TokenContribution } from "../token-inventory/types.js";
 export * from "./tailwind.js";
 export * from "./vanillaExtract.js";
-/**
- * Host-neutral interpretation of CSS dialects. Hosts see very different things
- * — a Vite host watches the whole transform pipeline, a static-file host only
- * reads `.css` off disk — so each supplies the evidence it can observe and this
- * module turns exactly that into token knowledge. It is pure, so the same
- * evidence yields the same tokens on every host and dialect behaviour can be
- * tested without a build tool. A host that observes less reports less through
- * `DialectObservation` rather than quietly producing a thinner catalog.
- */
 export type DialectName = "tailwind-v3" | "tailwind-v4" | "vanilla-extract";
 export interface TailwindV3Evidence {
     readonly config: unknown;
-    /** Path recorded on the resulting tokens. */
     readonly source?: string;
 }
-/** A theme contract written inline in host configuration. */
 export interface InlineThemeContractEvidence {
     readonly contract: unknown;
-    /** Compiled values by custom-property name, when the host observed the CSS. */
+    /** Only when the host observed the emitted CSS. */
     readonly cssValues?: Readonly<Record<string, string>>;
     readonly source?: string;
 }
-/** A theme contract loaded from a published module. */
 export interface PublishedThemeContractEvidence {
     /** Separates "never looked" from "looked and found nothing"; only the latter clears a held contract. */
     readonly attempted: boolean;
     readonly contract: unknown;
-    /** Whether the contract came from a dependency rather than project source. */
     readonly fromPackage?: boolean;
     readonly prefix?: string;
     readonly source?: string;
     readonly diagnostics?: readonly TokenCatalogDiagnostic[];
 }
-/** Everything a host managed to observe about the project's dialects. */
 export interface DialectEvidence {
     readonly tailwindV3?: TailwindV3Evidence;
-    /** True when any observed stylesheet carried Tailwind v4 markers. */
     readonly tailwindV4Css?: boolean;
     readonly inlineThemeContract?: InlineThemeContractEvidence;
     readonly publishedThemeContract?: PublishedThemeContractEvidence;
@@ -54,9 +39,5 @@ export interface DialectInterpretation {
     readonly contributions: readonly TokenContribution[];
     readonly observed: readonly DialectObservation[];
 }
-/**
- * Every contribution is emitted on every call, empty when a dialect has no
- * evidence: they are id-keyed and replaceable, so omitting one would leave
- * stale facts in the inventory rather than clearing them.
- */
+/** Emitted even with no evidence: contributions are id-keyed, so omitting one would leave stale facts. */
 export declare function interpretDialects(evidence?: DialectEvidence): DialectInterpretation;

package/dist/css/dialects/index.js

@@ -2,11 +2,7 @@ import { isTailwindV3Config, readTailwindV3Config, tailwindV4Relabelling } from
 import { readThemeContract } from "./vanillaExtract.js";
 export * from "./tailwind.js";
 export * from "./vanillaExtract.js";
-/**
- * Every contribution is emitted on every call, empty when a dialect has no
- * evidence: they are id-keyed and replaceable, so omitting one would leave
- * stale facts in the inventory rather than clearing them.
- */
+/** Emitted even with no evidence: contributions are id-keyed, so omitting one would leave stale facts. */
 export function interpretDialects(evidence = {}) {
     const observed = [];
     const tailwindV3Tokens = readTailwindV3Evidence(evidence.tailwindV3);
@@ -54,10 +50,7 @@ function readInlineContract(evidence) {
         ...(evidence.cssValues === undefined ? {} : { cssValues: evidence.cssValues }),
     });
 }
-/**
- * Contributes identity only: the emitted CSS stays authoritative on value,
- * cascade, and editability, so entries carry no declarations and merge by CSS name.
- */
+/** Contributes identity only: the emitted CSS stays authoritative on value and editability. */
 function readPublishedContract(evidence) {
     const empty = { id: "vanilla-extract-contract", order: 1 };
     if (evidence === undefined || !evidence.attempted)

package/dist/css/dialects/tailwind.d.ts

@@ -1,30 +1,18 @@
 import type { TokenEntry } from "../model/index.js";
 import type { TokenContribution } from "../token-inventory/types.js";
-/** Markers proving a stylesheet participates in Tailwind v4. */
 export declare function detectTailwindV4(css: string): boolean;
-/**
- * v4 tokens reach the CSS whether authored or Tailwind-generated, and the
- * generic parser cannot tell those apart. Authored `@theme` entries stay
- * project-owned and editable; generated ones are framework-owned and are not.
- */
+/** The generic parser cannot tell authored from generated v4 tokens, so this corrects provenance and editability. */
 export declare function tailwindV4Relabelling(): TokenContribution;
 /** A color utility that applies alpha to a catalog token, e.g. `bg-brand/40`. */
 export interface TailwindAlphaUtility {
     readonly utility: string;
-    /** The base catalog token the utility draws its color from. */
     readonly baseName: string;
     /** Normalized alpha, always percent-suffixed. */
     readonly alpha: string;
 }
-/**
- * Null when the class is not an alpha utility. The build-time catalog and the
- * browser runtime both parse this and must agree, or an edit gets attributed
- * to the wrong token.
- */
+/** Parsed by both the build-time catalog and the browser runtime, which must agree on attribution. */
 export declare function readTailwindV4AlphaUtility(className: string): TailwindAlphaUtility | null;
-/** The CSS Tailwind v4 emits for an alpha utility. */
 export declare function tailwindV4AlphaExpression(baseCssName: string, alpha: string): string;
-/** The parts of a v3 config that carry design tokens. */
 export interface TailwindV3Config {
     theme?: {
         colors?: Record<string, unknown>;
@@ -40,7 +28,5 @@ export interface TailwindV3Config {
     plugins?: unknown[];
     [key: string]: unknown;
 }
-/** Distinguishes a v3 config object from a v4 one, which has no `theme` key. */
 export declare function isTailwindV3Config(config: unknown): config is TailwindV3Config;
-/** Flattens a v3 config's theme into token entries, applying `theme.extend`. */
 export declare function readTailwindV3Config(config: TailwindV3Config, source?: string): TokenEntry[];

package/dist/css/dialects/tailwind.js

@@ -1,26 +1,10 @@
-/**
- * Tailwind's two major versions keep tokens in different places, so they get
- * separate treatment rather than a shared "Tailwind" concept. v3 keeps them in
- * a JavaScript config and compiles literal values into utilities, making the
- * config the only source of authored names. v4 declares them as custom
- * properties in `@theme`, so parsed CSS is the source of truth and this module
- * only corrects provenance the generic parser cannot infer.
- */
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-// ---------------------------------------------------------------------------
-// Tailwind v4
-// ---------------------------------------------------------------------------
-/** Markers proving a stylesheet participates in Tailwind v4. */
 export function detectTailwindV4(css) {
     return /@(?:import\s+["']tailwindcss|theme\b)/i.test(css) || /--tw-[\w-]+/.test(css);
 }
-/**
- * v4 tokens reach the CSS whether authored or Tailwind-generated, and the
- * generic parser cannot tell those apart. Authored `@theme` entries stay
- * project-owned and editable; generated ones are framework-owned and are not.
- */
+/** The generic parser cannot tell authored from generated v4 tokens, so this corrects provenance and editability. */
 export function tailwindV4Relabelling() {
     return {
         id: "tailwind-v4-naming",
@@ -32,11 +16,7 @@ export function tailwindV4Relabelling() {
     };
 }
 const V4_ALPHA_UTILITY = /^bg-([\w-]+)\/(\d{1,3}%?)$/;
-/**
- * Null when the class is not an alpha utility. The build-time catalog and the
- * browser runtime both parse this and must agree, or an edit gets attributed
- * to the wrong token.
- */
+/** Parsed by both the build-time catalog and the browser runtime, which must agree on attribution. */
 export function readTailwindV4AlphaUtility(className) {
     const match = V4_ALPHA_UTILITY.exec(className.trim());
     const color = match?.[1];
@@ -48,11 +28,9 @@ export function readTailwindV4AlphaUtility(className) {
         return null;
     return { utility: className, baseName: `--color-${color}`, alpha: `${numeric}%` };
 }
-/** The CSS Tailwind v4 emits for an alpha utility. */
 export function tailwindV4AlphaExpression(baseCssName, alpha) {
     return `color-mix(in oklab, var(${baseCssName}) ${alpha}, transparent)`;
 }
-/** Distinguishes a v3 config object from a v4 one, which has no `theme` key. */
 export function isTailwindV3Config(config) {
     return isRecord(config)
         && isRecord(config.theme)
@@ -109,7 +87,6 @@ function sectionEntries(values, section, source, path = []) {
     }
     return entries;
 }
-/** Flattens a v3 config's theme into token entries, applying `theme.extend`. */
 export function readTailwindV3Config(config, source = "tailwind.config.js") {
     return TOKEN_SECTIONS.flatMap((section) => {
         const base = isRecord(config.theme?.[section]) ? config.theme[section] : {};

package/dist/css/dialects/vanillaExtract.d.ts

@@ -1,20 +1,12 @@
 import type { TokenEntry } from "../model/index.js";
-/**
- * vanilla-extract generates the custom-property names, so the contract is the
- * only place the authored path (`theme.color.brand`) survives. Reading it is
- * how a host recovers names the emitted CSS cannot supply.
- */
-/** A compiled contract: nested objects whose leaves are `var()` references. */
+/** vanilla-extract generates custom-property names, so the contract is the only source of the authored path. */
 export type ThemeContract = Record<string, unknown>;
 export interface ReadThemeContractOptions {
-    /** Prefix for generated token paths. Defaults to `theme`. */
     readonly prefix?: string;
-    /** Source label recorded on every entry. */
     readonly source: string;
     readonly origin: TokenEntry["origin"];
     readonly editable: boolean;
     /** Omit when the host did not observe the emitted CSS; entries then keep their `var()` reference. */
     readonly cssValues?: Readonly<Record<string, string>>;
 }
-/** Flattens a contract into token entries keyed by their authored path. */
 export declare function readThemeContract(contract: unknown, options: ReadThemeContractOptions): TokenEntry[];

package/dist/css/dialects/vanillaExtract.js

@@ -3,7 +3,6 @@ const CONTRACT_REFERENCE = /^var\(\s*(--[\w-]+)(?:\s*,[\s\S]*)?\)$/;
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/** Flattens a contract into token entries keyed by their authored path. */
 export function readThemeContract(contract, options) {
     const entries = [];
     const walk = (value, path) => {

package/dist/css/index.d.ts

@@ -1,10 +1,2 @@
-/**
- * `nudge-ui/css` — shared, browser-safe CSS/token knowledge.
- *
- * Root entry re-exports the browser-safe subpaths only. The Node/build-time
- * token-inventory subpath arrives in Stage 2 and must NOT be reachable from
- * this entry so importing value semantics cannot pull PostCSS or filesystem
- * assumptions into the inspector bundle.
- */
 export * from "./model/index.js";
 export * from "./value-semantics/index.js";

package/dist/css/index.js

@@ -1,10 +1,2 @@
-/**
- * `nudge-ui/css` — shared, browser-safe CSS/token knowledge.
- *
- * Root entry re-exports the browser-safe subpaths only. The Node/build-time
- * token-inventory subpath arrives in Stage 2 and must NOT be reachable from
- * this entry so importing value semantics cannot pull PostCSS or filesystem
- * assumptions into the inspector bundle.
- */
 export * from "./model/index.js";
 export * from "./value-semantics/index.js";

package/dist/css/model/index.d.ts

@@ -1,15 +1,4 @@
-/**
- * Shared CSS/token knowledge types for `nudge-ui/css`.
- *
- * This module is the browser-safe shared model consumed by the runtime
- * inspector (`nudge-ui/internal/inspector`), the Vite adapter transport
- * (`virtual:design-tokens`), and — in later slices — the token inventory
- * Module. It MUST NOT import React, Vite, PostCSS, Node, or filesystem code;
- * the import-graph test in `src/importGraph.test.ts` enforces that contract.
- */
-/** Provenance of a token entry or definition. */
 export type TokenOrigin = "project" | "package" | "framework" | "generated" | "runtime";
-/** How faithfully an authored value can be edited by the inspector. */
 export type EditCapability = "atomic" | "color" | "box-sides" | "structured" | "composite" | "raw";
 export interface TokenReference {
     name: string;
@@ -26,7 +15,6 @@ export interface ColorOpacity {
     tokenName: string | null;
     token?: TokenReference;
 }
-/** The effective opacity of an element's `opacity` property. */
 export interface OpacityValue {
     value: string;
     authoredValue: string;
@@ -35,7 +23,7 @@ export interface OpacityValue {
     /** False when the authored expression cannot be rewritten losslessly. */
     editable: boolean;
 }
-/** UI-relevant color facts derived by value semantics, never by React fields. */
+/** Derived by value semantics, never by React fields. */
 export interface ColorValueFacts {
     /** The authored or resolved color already carries an alpha channel. */
     hasEmbeddedAlpha: boolean;
@@ -63,19 +51,12 @@ export interface AttributionEvidence {
     inaccessibleStylesheet?: boolean;
     reason: string;
 }
-/**
- * A token as published by the Vite transport or materialized by a styling
- * adapter. `name` is the human/design name, `cssName` is the CSS custom
- * property implementation name; they may differ and must not be conflated.
- */
+/** `name` is the human/design name, `cssName` the custom-property implementation name; they may differ and must not be conflated. */
 export interface TokenEntry {
     name: string;
     value: string;
     source: string;
-    /**
-     * CSS to place in a managed preview when this token has no CSS custom
-     * property. Tailwind v3 config tokens compile to literals, for example.
-     */
+    /** Managed-preview CSS for tokens with no custom property (e.g. Tailwind v3 config literals). */
     cssValue?: string;
     adapter?: string;
     cssName?: string;
@@ -83,10 +64,7 @@ export interface TokenEntry {
     editable?: boolean;
 }
 export type TokenContextWrapperKind = "media" | "supports" | "scope" | "layer";
-/**
- * An ordered source wrapper around a token declaration. Keeping one stack
- * retains nesting and interleaving, including repeated wrapper kinds.
- */
+/** One ordered stack preserves nesting and interleaving, including repeated kinds. */
 export interface TokenContextWrapper {
     kind: TokenContextWrapperKind;
     params: string;
@@ -113,7 +91,6 @@ export interface TokenDefinition {
     origin?: TokenOrigin;
     editable?: boolean;
 }
-/** Diagnostic codes emitted by token sources and the token inventory Module. */
 export type TokenCatalogDiagnosticCode = "vanilla-extract-contract-unresolved" | "vanilla-extract-contract-missing-export" | "vanilla-extract-contract-unsupported-shape" | "stylesheet-unreadable" | "stylesheet-unresolved" | "stylesheet-unsupported" | "stylesheet-parse-failed" | "transform-observation-failed" | "token-order-unresolved";
 export interface TokenCatalogDiagnostic {
     code: TokenCatalogDiagnosticCode;
@@ -137,7 +114,6 @@ export interface AtRuleContext {
     /** The CSSOM-normalised prelude, without the leading `@kind`. */
     params: string;
 }
-/** A conditional wrapper that participates in a property's source candidates. */
 export interface AtRuleCandidate extends AtRuleContext {
     /** True when this context belongs to the declaration currently winning the cascade. */
     active: boolean;
@@ -155,16 +131,12 @@ export interface MatchedRule {
     active?: boolean;
     atRules?: AtRuleContext[];
 }
-/** One attributed, resolvable property on the inspected element. */
 export interface ResolvedProperty {
     property: string;
     tokenName: string | null;
     declaredValue: string;
     resolvedValue: string;
-    /**
-     * CSSOM-declared serialization used by the UI as the authored expression.
-     * This preserves CSS meaning, not the source file's exact spelling.
-     */
+    /** CSSOM serialization used as the authored expression; preserves CSS meaning, not source spelling. */
     authored?: string;
     sourceProperty?: string;
     computed?: string;
@@ -177,11 +149,7 @@ export interface ResolvedProperty {
     resolvedTokenValue?: string;
     diagnostic?: string;
     structure?: BorderStructure;
-    /**
-     * Conditional source wrappers that apply to the declaration currently
-     * attributed to this field. These include responsive, container, and
-     * capability conditions which can affect the winning declaration.
-     */
+    /** Conditional wrappers affecting the declaration attributed to this field. */
     atRules?: AtRuleContext[];
     /** All media-query contexts found on declarations for this property. */
     atRuleCandidates?: AtRuleCandidate[];

package/dist/css/model/index.js

@@ -1,10 +1 @@
-/**
- * Shared CSS/token knowledge types for `nudge-ui/css`.
- *
- * This module is the browser-safe shared model consumed by the runtime
- * inspector (`nudge-ui/internal/inspector`), the Vite adapter transport
- * (`virtual:design-tokens`), and — in later slices — the token inventory
- * Module. It MUST NOT import React, Vite, PostCSS, Node, or filesystem code;
- * the import-graph test in `src/importGraph.test.ts` enforces that contract.
- */
 export {};

package/dist/css/token-inventory/index.d.ts

@@ -1,26 +1,3 @@
-/**
- * `nudge-ui/css/token-inventory` — Node/build-time stylesheet parsing and
- * aggregation.
- *
- * This subpath is intentionally NOT browser-safe (see the import-graph test):
- * importing it pulls PostCSS into the consumer. Node consumers use it directly
- * through `nudge-ui/css/token-inventory`; the root `nudge-ui/css`
- * entry stays browser-safe and never re-exports this module.
- *
- * The deep Interface is `createTokenInventory()` — feed ordered stylesheet
- * artifacts and Adapter literal tokens, read immutable deterministic snapshots.
- * Parsing and policy remain internal seams used by the engine and direct tests.
- *
- * ## Deletion test
- *
- * This Module earns its seam: deleting it would force the Vite Adapter to
- * re-own PostCSS parsing, authored/transformed reconciliation, declaration
- * identity and ordering, project/package/generated provenance, contribution
- * merging, structured diagnostics, and the generation fingerprint that
- * `BrowserTokenKnowledge` uses to refresh inspection sessions. The Adapter
- * would also have to re-solve the determinism/no-op guarantees that keep
- * equivalent HMR event batches from churning the snapshot.
- */
 export { createTokenInventory } from "./inventory.js";
 export type { TokenInventory } from "./inventory.js";
 export type { ArtifactProvenance, ArtifactStage, TokenDefinitionRelabelling, ArtifactDiagnosticInput, InventoryContribution, InventoryDiagnostic, InventoryOrderEvidence, InventorySnapshot, InventoryTokenDeclaration, InventoryTokenDefinition, StylesheetArtifact, TokenContribution, } from "./types.js";

package/dist/css/token-inventory/index.js

@@ -1,24 +1 @@
-/**
- * `nudge-ui/css/token-inventory` — Node/build-time stylesheet parsing and
- * aggregation.
- *
- * This subpath is intentionally NOT browser-safe (see the import-graph test):
- * importing it pulls PostCSS into the consumer. Node consumers use it directly
- * through `nudge-ui/css/token-inventory`; the root `nudge-ui/css`
- * entry stays browser-safe and never re-exports this module.
- *
- * The deep Interface is `createTokenInventory()` — feed ordered stylesheet
- * artifacts and Adapter literal tokens, read immutable deterministic snapshots.
- * Parsing and policy remain internal seams used by the engine and direct tests.
- *
- * ## Deletion test
- *
- * This Module earns its seam: deleting it would force the Vite Adapter to
- * re-own PostCSS parsing, authored/transformed reconciliation, declaration
- * identity and ordering, project/package/generated provenance, contribution
- * merging, structured diagnostics, and the generation fingerprint that
- * `BrowserTokenKnowledge` uses to refresh inspection sessions. The Adapter
- * would also have to re-solve the determinism/no-op guarantees that keep
- * equivalent HMR event batches from churning the snapshot.
- */
 export { createTokenInventory } from "./inventory.js";