nudge-ui 0.2.0

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

@@ -0,0 +1,64 @@
+/**
+ * Structured and box value interpretation (plan slice 3.5).
+ *
+ * One browser-safe Module turns an authored CSSOM value for a box/border/
+ * radius/font property into a structured projection tree: the physical sides,
+ * border longhands, radius corners, or font longhands it expands to, each with
+ * source-property provenance and its own token interpretation.
+ *
+ * One interpretation tree: each distinct authored component is token-interpreted
+ * once and every projected field that carries that component reuses the same
+ * interpretation (tokenName, tokens, opacity, modifiers, cycle). A border color
+ * token, a multi-value spacing token, or a radius token is therefore resolved
+ * once per declaration, not once per projected longhand.
+ *
+ * Conservative fallbacks: ambiguous borders, slash-separated radius forms,
+ * complex fonts, and everything outside the supported families stay a single
+ * raw/composite row with the resolution's existing capability classification.
+ *
+ * Browser-safe contract: this module imports only the shared model and the
+ * other value-semantics Modules. Directionality is an explicit input fact; it
+ * never walks the DOM or CSSOM.
+ */
+import type { BorderStructure, ColorOpacity, EditCapability, OpacityValue, TokenReference, ValueModifier } from "../model/index.js";
+import { type TokenInterpretationContext, type TokenValueInterpretation } from "./tokenInterpretation.js";
+import { type Directionality } from "./boxSemantics.js";
+export type { Directionality } from "./boxSemantics.js";
+/** One projected longhand row from the structured interpretation. */
+export interface StructuredField {
+    property: string;
+    /** The authored value projected to this field (per-side/corner/longhand). */
+    declaredValue: string;
+    /** The shorthand the field came from (e.g. `"border"`, `"padding-inline"`). */
+    sourceProperty: string;
+    tokenName: string | null;
+    resolvedValue: string;
+    tokens: TokenReference[];
+    opacity?: ColorOpacity;
+    propertyOpacity?: OpacityValue;
+    color?: TokenValueInterpretation["color"];
+    modifiers: ValueModifier[];
+    capability: EditCapability;
+    structure?: BorderStructure;
+    diagnostic?: string;
+}
+/** Explicit, DOM-free facts the structured interpretation needs. */
+export interface StructuredValuesContext {
+    /** Token table plus the integration's token-interpretation policies. */
+    tokenContext: TokenInterpretationContext;
+    /**
+     * Writing-mode/direction facts for logical→physical mapping. Absent →
+     * `ltr` / `horizontal-tb`.
+     */
+    directionality?: Directionality;
+}
+/**
+ * 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.
+ */
+export declare function interpretValue(property: string, authored: string, ctx: StructuredValuesContext): StructuredField[];
+/** @internal Use the package-level `interpretValue` Interface in production. */
+export declare const interpretStructuredValue: typeof interpretValue;

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

@@ -0,0 +1,250 @@
+import { splitTopLevelWhitespace, topLevelSlashIndex } from "./cssSyntax.js";
+import { parseBorderComponents } from "./borderSemantics.js";
+import { parseFontShorthand } from "./fontSemantics.js";
+import { normalizeOpacityPercent } from "./colorSemantics.js";
+import { classifyEditCapability } from "./propertyPolicy.js";
+import { interpretTokenValue } from "./tokenInterpretation.js";
+import { BORDER_RADIUS_CORNERS, GAP_AXES, SPACING_SIDES, expandFourValueShorthand, expandTwoValueShorthand, logicalPhysicalSides, } from "./boxSemantics.js";
+function propertyOpacityFor(authored, interpretation, capability) {
+    const value = normalizeOpacityPercent(interpretation.resolvedValue);
+    if (value === null)
+        return undefined;
+    const token = interpretation.tokenName
+        ? interpretation.tokens.find((reference) => reference.name === interpretation.tokenName)
+        : undefined;
+    return {
+        value,
+        authoredValue: authored.trim(),
+        tokenName: interpretation.tokenName,
+        ...(token ? { token } : {}),
+        editable: capability !== "raw" && !/\b(?:calc|min|max|clamp|env|anchor-size)\s*\(/i.test(authored),
+    };
+}
+function cycleDiagnostic(cycle) {
+    return `custom-property alias cycle includes ${cycle}`;
+}
+function projectField(projection) {
+    const { interpretation } = projection;
+    return {
+        property: projection.property,
+        declaredValue: projection.declaredValue,
+        sourceProperty: projection.sourceProperty,
+        tokenName: interpretation.tokenName,
+        resolvedValue: projection.resolvedValue ?? interpretation.resolvedValue,
+        tokens: interpretation.tokens,
+        opacity: interpretation.opacity,
+        ...(projection.property.toLowerCase() === "opacity"
+            ? { propertyOpacity: propertyOpacityFor(projection.declaredValue, interpretation, projection.capability) }
+            : {}),
+        color: interpretation.color,
+        modifiers: interpretation.modifiers,
+        capability: projection.capability,
+        diagnostic: projection.diagnostic
+            ?? (interpretation.cycle ? cycleDiagnostic(interpretation.cycle) : undefined),
+        structure: projection.structure,
+    };
+}
+function rawField(property, authored, ctx) {
+    const trimmed = authored.trim();
+    const interpretation = interpretTokenValue(trimmed, ctx.tokenContext);
+    const capability = property.toLowerCase() === "border" ? "raw" : classifyEditCapability(property, authored);
+    return projectField({
+        property,
+        declaredValue: trimmed,
+        sourceProperty: property,
+        interpretation,
+        capability,
+        diagnostic: capability === "composite" ? `unsupported composite value for ${property}` : undefined,
+    });
+}
+function unsupportedField(property, authored, ctx) {
+    const field = rawField(property, authored, ctx);
+    return {
+        ...field,
+        capability: "raw",
+        diagnostic: field.diagnostic?.startsWith("custom-property alias cycle")
+            ? field.diagnostic
+            : `unsupported structured value for ${property}`,
+    };
+}
+function fieldFor(property, declaredValue, sourceProperty, ctx) {
+    return projectField({
+        property,
+        declaredValue,
+        sourceProperty,
+        interpretation: interpretTokenValue(declaredValue, ctx.tokenContext),
+        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.
+ */
+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) {
+            return tokenValues.map((resolvedValue) => ({
+                declaredValue: rawValue,
+                resolvedValue,
+                interpretation: res,
+            }));
+        }
+        return [{ declaredValue: rawValue, resolvedValue: res.resolvedValue, interpretation: res }];
+    });
+}
+function expandLogicalSides(sides, property, authored, ctx) {
+    const rawValues = splitTopLevelWhitespace(authored);
+    const positions = expandPositionValues(rawValues, ctx);
+    const values = sides.length === 1
+        ? positions.length === 1 ? [positions[0]] : null
+        : expandTwoValueShorthand(positions);
+    if (!values)
+        return null;
+    return sides.map((side, index) => projectPositionField(side, property, values[index]));
+}
+function expandBorder(lower, property, authored, ctx) {
+    const components = parseBorderComponents(authored.trim(), ctx.tokenContext);
+    if (!components)
+        return null;
+    // SAFETY: lower is one of the known border structure source properties from the parser typed union.
+    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.
+    const { widthResult, styleResult, colorResult } = components;
+    const scopedStructure = {
+        kind: "border",
+        sourceProperty,
+        width: components.width,
+        style: components.style,
+        color: components.color,
+        colorTokenName: colorResult.tokenName,
+    };
+    const authoredValue = authored.trim();
+    const entries = sidePrefix
+        ? [[`${sidePrefix}width`, components.width], [`${sidePrefix}style`, components.style], [`${sidePrefix}color`, components.color]]
+        : [
+            ["border-width", components.width], ["border-style", components.style], ["border-color", components.color],
+            ["border-top-width", components.width], ["border-right-width", components.width], ["border-bottom-width", components.width], ["border-left-width", components.width],
+            ["border-top-style", components.style], ["border-right-style", components.style], ["border-bottom-style", components.style], ["border-left-style", components.style],
+            ["border-top-color", components.color], ["border-right-color", components.color], ["border-bottom-color", components.color], ["border-left-color", components.color],
+        ];
+    return entries.map(([longhand, component]) => {
+        const result = longhand.endsWith("color")
+            ? colorResult
+            : longhand.endsWith("style") ? styleResult : widthResult;
+        return projectField({
+            property: longhand,
+            declaredValue: authoredValue,
+            sourceProperty: property,
+            interpretation: result,
+            resolvedValue: result.resolvedValue || component,
+            capability: "structured",
+            structure: scopedStructure,
+        });
+    });
+}
+function expandFont(property, authored, ctx) {
+    const parts = parseFontShorthand(authored);
+    if (!parts)
+        return null;
+    return Object.entries(parts).map(([longhand, declaredValue]) => fieldFor(longhand, declaredValue, property, ctx));
+}
+function expandCorners(property, corners, authored, ctx) {
+    const rawValues = splitTopLevelWhitespace(authored);
+    // Slash-separated radius forms stay conservative: a single raw row.
+    if (topLevelSlashIndex(authored) >= 0 || rawValues.length === 0 || rawValues.length > 4) {
+        return [unsupportedField(property, authored, ctx)];
+    }
+    const positions = expandPositionValues(rawValues, ctx);
+    const resolvedSlash = positions.some(({ interpretation }) => topLevelSlashIndex(interpretation.resolvedValue) >= 0
+        || interpretation.modifiers.some((modifier) => modifier.kind === "fallback" && topLevelSlashIndex(modifier.value) >= 0));
+    if (resolvedSlash)
+        return [unsupportedField(property, authored, ctx)];
+    const cornerValues = expandFourValueShorthand(positions);
+    if (!cornerValues)
+        return [unsupportedField(property, authored, ctx)];
+    return corners.map((longhand, index) => projectPositionField(longhand, property, cornerValues[index]));
+}
+function projectPositionField(longhand, sourceProperty, value) {
+    return projectField({
+        property: longhand,
+        declaredValue: value.declaredValue,
+        sourceProperty,
+        interpretation: value.interpretation,
+        resolvedValue: value.resolvedValue,
+        capability: classifyEditCapability(longhand, value.declaredValue),
+    });
+}
+function expandSides(property, sides, authored, ctx) {
+    const rawValues = splitTopLevelWhitespace(authored);
+    if (rawValues.length === 0 || rawValues.length > 4)
+        return null;
+    const sideValues = expandFourValueShorthand(expandPositionValues(rawValues, ctx));
+    if (!sideValues)
+        return null;
+    return sides.map((longhand, index) => projectPositionField(longhand, property, sideValues[index]));
+}
+function expandGap(property, axes, authored, ctx) {
+    const rawValues = splitTopLevelWhitespace(authored);
+    const positions = expandPositionValues(rawValues, ctx);
+    const axisValues = expandTwoValueShorthand(positions);
+    if (!axisValues)
+        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.
+ */
+export function interpretValue(property, authored, ctx) {
+    const lower = property.toLowerCase();
+    if (lower === "opacity")
+        return [rawField(property, authored, ctx)];
+    const logicalSides = logicalPhysicalSides(lower, ctx.directionality);
+    if (logicalSides) {
+        const fields = expandLogicalSides(logicalSides, property, authored, ctx);
+        if (fields)
+            return fields;
+        return [unsupportedField(property, authored, ctx)];
+    }
+    if (lower === "border" || /^border-(?:top|right|bottom|left)$/.test(lower)) {
+        const fields = expandBorder(lower, property, authored, ctx);
+        if (fields)
+            return fields;
+        return [unsupportedField(property, authored, ctx)];
+    }
+    if (lower === "font") {
+        const fields = expandFont(property, authored, ctx);
+        if (fields)
+            return fields;
+        return [unsupportedField(property, authored, ctx)];
+    }
+    const corners = BORDER_RADIUS_CORNERS[lower];
+    if (corners)
+        return expandCorners(property, corners, authored, ctx);
+    const gapAxes = GAP_AXES[lower];
+    if (gapAxes) {
+        const fields = expandGap(property, gapAxes, authored, ctx);
+        if (fields)
+            return fields;
+        return [unsupportedField(property, authored, ctx)];
+    }
+    const sides = SPACING_SIDES[lower];
+    if (sides) {
+        const fields = expandSides(property, sides, authored, ctx);
+        if (fields)
+            return fields;
+        return [unsupportedField(property, authored, ctx)];
+    }
+    return [rawField(property, authored, ctx)];
+}
+/** @internal Use the package-level `interpretValue` Interface in production. */
+export const interpretStructuredValue = interpretValue;

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

@@ -0,0 +1,90 @@
+/**
+ * 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;
+    /** The authored value with the primary reference substituted by its leaf. */
+    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: 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. */
+    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.
+ */
+export interface AliasAttribution {
+    known: boolean;
+    tokenName: string | null;
+    resolvedValue: string;
+    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.
+     */
+    resolveDirectToken?: (value: string) => TokenEntry | undefined;
+    /** Token-origin derivation. Default: `entry.origin ?? "project"` (undefined → "runtime"). */
+    resolveOrigin?: (entry: TokenEntry | undefined) => TokenOrigin;
+    /** Local-alias attribution policy. 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.
+ */
+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.
+ */
+export declare function interpretTokenValue(value: string, ctx: TokenInterpretationContext): TokenValueInterpretation;

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

@@ -0,0 +1,193 @@
+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.
+ */
+export function defaultTokenOrigin(entry) {
+    if (!entry)
+        return "runtime";
+    return entry.origin ?? "project";
+}
+function defaultAliasAttribution(ref, inner) {
+    return {
+        known: true,
+        tokenName: ref,
+        resolvedValue: inner.resolvedValue,
+        leafTokenName: inner.leafTokenName ?? ref,
+        cycle: inner.cycle,
+    };
+}
+function resolveRef(ref, table, visited, localAliases, ctx) {
+    if (visited.has(ref)) {
+        const entry = table[ref];
+        return {
+            known: entry !== undefined,
+            tokenName: entry ? entry.name : null,
+            resolvedValue: entry ? entry.value : `var(${ref})`,
+            leafTokenName: entry ? entry.name : null,
+            cycle: ref,
+        };
+    }
+    const entry = table[ref];
+    if (entry) {
+        const nextVisited = new Set(visited);
+        nextVisited.add(ref);
+        const inner = resolveTokenValueInner(entry.value, table, nextVisited, localAliases, ctx);
+        return { known: true, tokenName: entry.name, resolvedValue: inner.resolvedValue, leafTokenName: inner.leafTokenName ?? entry.name, cycle: inner.cycle };
+    }
+    const localValue = localAliases.get(ref);
+    if (localValue === undefined) {
+        return { known: false, tokenName: null, resolvedValue: `var(${ref})`, leafTokenName: null };
+    }
+    const nextVisited = new Set(visited);
+    nextVisited.add(ref);
+    const inner = resolveTokenValueInner(localValue, table, nextVisited, localAliases, ctx);
+    return (ctx.resolveAlias ?? defaultAliasAttribution)(ref, inner);
+}
+function resolveTokenValueInner(value, table, visited, localAliases, ctx) {
+    const trimmed = value.trim();
+    const refs = extractVarCalls(trimmed).map((call) => call.name);
+    if (refs.length === 0)
+        return { tokenName: null, resolvedValue: trimmed, leafTokenName: null };
+    for (const ref of refs) {
+        const res = resolveRef(ref, table, visited, localAliases, ctx);
+        if (res.known)
+            return { tokenName: res.tokenName, resolvedValue: res.resolvedValue, leafTokenName: res.leafTokenName, cycle: res.cycle };
+    }
+    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.
+ */
+export function interpretTokenValue(value, ctx) {
+    const authored = value.trim();
+    const table = ctx.table;
+    const localAliases = ctx.localAliases ?? EMPTY_LOCAL_ALIASES;
+    const resolveOrigin = ctx.resolveOrigin ?? defaultTokenOrigin;
+    const calls = extractVarCalls(authored);
+    const references = [];
+    let firstKnown = null;
+    const directToken = ctx.resolveDirectToken?.(authored);
+    if (directToken) {
+        firstKnown = { tokenName: directToken.name, leafTokenName: directToken.name, resolvedValue: directToken.value };
+        references.push({ name: directToken.name, origin: resolveOrigin(directToken) });
+    }
+    for (const call of calls) {
+        const result = resolveRef(call.name, table, new Set(), localAliases, ctx);
+        if (result.known) {
+            if (!references.some((token) => token.name === result.tokenName)) {
+                references.push({
+                    name: result.tokenName ?? call.name,
+                    origin: resolveOrigin(table[call.name] ?? table[result.tokenName ?? ""]),
+                });
+            }
+            if (!firstKnown) {
+                firstKnown = {
+                    tokenName: result.tokenName ?? call.name,
+                    leafTokenName: result.leafTokenName,
+                    resolvedValue: result.resolvedValue,
+                    cycle: result.cycle,
+                };
+            }
+        }
+        if (call.fallback) {
+            const fallback = call.fallback.trim();
+            if (fallback) {
+                const fallbackResult = interpretTokenValue(fallback, ctx);
+                references.push(...fallbackResult.tokens.filter((token) => !references.some((seen) => seen.name === token.name)));
+                if (!firstKnown && fallbackResult.tokenName) {
+                    firstKnown = {
+                        tokenName: fallbackResult.tokenName,
+                        leafTokenName: fallbackResult.leafTokenName,
+                        resolvedValue: fallbackResult.resolvedValue,
+                        cycle: fallbackResult.cycle,
+                    };
+                }
+            }
+        }
+    }
+    const colorContext = {
+        tokenTable: table,
+        localAliases,
+        resolveTokenReference: (value) => resolveComponentReference(value, ctx),
+    };
+    const authoredColor = interpretColorValue(authored, colorContext);
+    const opacity = authoredColor.opacity;
+    const modifiers = calls.flatMap((call) => call.fallback ? [{ kind: "fallback", value: call.fallback }] : []);
+    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.
+    const alphaTokenName = opacity?.tokenName;
+    const baseKnown = firstKnown && firstKnown.tokenName !== alphaTokenName ? firstKnown : null;
+    const baseInner = inner.tokenName && inner.tokenName !== alphaTokenName ? inner : null;
+    const primary = baseKnown ?? baseInner;
+    const resolvedColor = primary?.resolvedValue
+        ? interpretColorValue(primary.resolvedValue, colorContext)
+        : null;
+    return {
+        tokenName: primary?.tokenName ?? (alphaTokenName ? null : firstKnown?.tokenName ?? inner.tokenName),
+        resolvedValue: primary?.resolvedValue ?? (alphaTokenName ? authored : inner.resolvedValue),
+        tokens: references,
+        opacity,
+        color: {
+            hasEmbeddedAlpha: authoredColor.facts.hasEmbeddedAlpha || Boolean(resolvedColor?.facts.hasEmbeddedAlpha),
+            isExpression: authoredColor.facts.isExpression,
+            opacityEditable: authoredColor.facts.opacityEditable && !resolvedColor?.facts.hasEmbeddedAlpha,
+        },
+        modifiers,
+        leafTokenName: primary?.leafTokenName ?? primary?.tokenName ?? null,
+        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.
+ */
+function resolveComponentReference(value, ctx) {
+    const calls = extractVarCalls(value);
+    if (calls.length === 0)
+        return null;
+    const table = ctx.table;
+    const localAliases = ctx.localAliases ?? EMPTY_LOCAL_ALIASES;
+    const resolveOrigin = ctx.resolveOrigin ?? defaultTokenOrigin;
+    const references = [];
+    let firstKnown = null;
+    for (const call of calls) {
+        const result = resolveRef(call.name, table, new Set(), localAliases, ctx);
+        if (result.known) {
+            if (!references.some((token) => token.name === result.tokenName)) {
+                references.push({
+                    name: result.tokenName ?? call.name,
+                    origin: resolveOrigin(table[call.name] ?? table[result.tokenName ?? ""]),
+                });
+            }
+            if (!firstKnown) {
+                firstKnown = { tokenName: result.tokenName ?? call.name, resolvedValue: result.resolvedValue };
+            }
+        }
+        if (call.fallback) {
+            const fallback = call.fallback.trim();
+            if (fallback) {
+                const fallbackResult = interpretTokenValue(fallback, ctx);
+                references.push(...fallbackResult.tokens.filter((token) => !references.some((seen) => seen.name === token.name)));
+                if (!firstKnown && fallbackResult.tokenName) {
+                    firstKnown = { tokenName: fallbackResult.tokenName, resolvedValue: fallbackResult.resolvedValue };
+                }
+            }
+        }
+    }
+    return firstKnown ? { tokenName: firstKnown.tokenName, resolvedValue: firstKnown.resolvedValue, tokens: references } : null;
+}

package/dist/css/virtual-design-tokens.d.ts

@@ -0,0 +1,17 @@
+/** Canonical ambient transport contract published by the Vite Adapter. */
+declare module "virtual:design-tokens" {
+  export type {
+    TokenCatalogDiagnostic,
+    TokenContext,
+    TokenContextWrapper,
+    TokenContextWrapperKind,
+    TokenDeclaration,
+    TokenDefinition,
+    TokenEntry,
+  } from "./model/index.js";
+  export const tokens: TokenEntry[];
+  export const tokenCatalog: TokenDefinition[];
+  export const tokenDiagnostics: TokenCatalogDiagnostic[];
+  export const tokenGeneration: string;
+  export const nudgeUiProjectId: string;
+}

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

@@ -0,0 +1,12 @@
+import { type NudgeUiRuntimeConfig } from "../../inspector/clientManifest.js";
+interface AstroRuntimeKnowledge {
+    readonly projectId: string;
+    readonly tokenCatalog: NudgeUiRuntimeConfig["tokenCatalog"];
+    readonly tokens: NudgeUiRuntimeConfig["tokens"];
+    readonly tokenDiagnostics: NudgeUiRuntimeConfig["tokenDiagnostics"];
+    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

@@ -0,0 +1,26 @@
+import { detectStylingSystem, } from "../../inspector/clientManifest.js";
+const ASTRO_SCOPING_SELECTOR_PATTERN = "\\[data-astro-cid-[^\\]]*\\]|\\.astro-[a-zA-Z0-9_-]+";
+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,
+        host: "astro",
+        framework: "Astro",
+        stylingSystem: detectStylingSystem(knowledge.tokens),
+        capabilities: {
+            canvas: false,
+            componentSemantics: true,
+            sourceCoordinates: ASTRO_SOURCE_COORDINATES,
+            scopingSelectorPattern: ASTRO_SCOPING_SELECTOR_PATTERN,
+        },
+        tokenCatalog: knowledge.tokenCatalog,
+        tokens: knowledge.tokens,
+        tokenDiagnostics: knowledge.tokenDiagnostics,
+        tokenGeneration: knowledge.tokenGeneration,
+        componentContracts: knowledge.componentContracts,
+    };
+}

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

@@ -0,0 +1,12 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+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.
+ */
+export declare function createAstroClientAssetHandler(dependencies?: ClientAssetDependencies): (request: IncomingMessage, response: ServerResponse) => Promise<void>;
+export {};