nudge-ui 0.2.4 → 0.2.6

package/dist/inspector/tokens/resolution.js

@@ -1,30 +1,21 @@
 import { readTailwindV4AlphaUtility, tailwindV4AlphaExpression } from "../../css/dialects/index.js";
 import { getElementComputedStyle } from "../runtime/domRealm.js";
+import { createContainerQueryEvaluator } from "./resolution/containerQueryEvaluator.js";
 import { collectRules as collectCssomRules, documentRevisions as getDocumentRevisions, registerResolutionLineage, } from "./resolution/cssomCollector.js";
-import { createRuleMatcher, matchRuleForElement } from "./resolution/ruleMatching.js";
+import { createRuleMatcher, matchRuleForElement, prewarmRuleMatching } from "./resolution/ruleMatching.js";
 import { compareAuthorCascade } from "./resolution/cascade.js";
 import { interpretValue, normalizeOpacityPercent, } from "../../css/value-semantics/index.js";
 import { createInspectorValueContext, inspectorTokenOrigin } from "./valueSemanticsAdapter.js";
 export { getAvailableInteractionStates, resetSourceSiteMatchCache, sourceSiteMatchCacheSize } from "./resolution/ruleMatching.js";
-export { buildTokenTable, getTokenTable, getAvailableTokenEntriesForElement, getAvailableTokenCatalog } from "./tokenAvailability.js";
+export { buildTokenTable, getAvailableTokenEntriesForElement, getAvailableTokenCatalog } from "./tokenAvailability.js";
 export { invalidateStyleResolutionCache } from "./resolution/cssomCollector.js";
-/**
- * Builds (or reuses) the document's CSSOM rule snapshot ahead of a resolution
- * sweep. Idempotent: the walk runs once per stylesheet revision and is a cache
- * hit afterwards, so a scheduler can warm it in its own frame to keep the
- * subsequent resolution sweep's blocking time small.
- */
+/** Idempotent per stylesheet revision; warms the snapshot ahead of a sweep so its blocking time stays small. */
 export function prewarmCssomRuleSnapshot(doc) {
-    collectCssomRules(doc);
+    prewarmRuleMatching(collectCssomRules(doc).rules);
 }
 const MAX_PROPERTIES = 100;
 const EMPTY_LOCAL_ALIASES = new Map();
-/**
- * Returns true when a `calc()` expression is safe to treat as a simple
- * numeric value. We exclude percentages, viewport units, and font-relative
- * units because those depend on context the browser cannot freeze into a
- * single pixel value safely.
- */
+/** Excludes context-dependent units (%, vw, em, ...) that cannot be frozen into one safe pixel value. */
 function canBecomeNumeric(value) {
     const v = value.trim();
     if (/\b(?:min|max|clamp|env|anchor-size)\s*\(/i.test(v))
@@ -55,11 +46,6 @@ function candidateMatchesPainted(el, row, painted) {
         return false;
     return normalizeInElementContext(el, row.property, row.declaredValue) === painted.trim();
 }
-/**
- * Resolves one authored value through the value-semantics Module using the
- * inspector's integration context. Value semantics remains the sole
- * interpretation authority.
- */
 function resolveTokenValue(value, tokenTable, localAliases = EMPTY_LOCAL_ALIASES) {
     return interpretValue("--nudge-ui-token", value, createInspectorValueContext(tokenTable, localAliases))[0];
 }
@@ -75,13 +61,7 @@ function elementDirectionality(el) {
 function isLogicalBoxProperty(property) {
     return /^(?:margin|padding|inset)-(?:inline|block)(?:-(?:start|end))?$/i.test(property);
 }
-/**
- * Coordinates cascade facts with the value-semantics Module. All property-family
- * decomposition (logical sides, border, font, radius corners, physical spacing)
- * lives in `interpretValue`; this function only supplies the token
- * context and directionality facts, then projects the Module's fields onto the
- * `ResolvedDeclaration` shape.
- */
+/** Decomposition lives in `interpretValue`; this supplies the token context and projects its fields. */
 function resolveDeclaration(declaration, tokenTable, localAliases = EMPTY_LOCAL_ALIASES, directionality) {
     const fields = interpretValue(declaration.property, declaration.value, createInspectorValueContext(tokenTable, localAliases, directionality));
     return fields.map((field) => ({
@@ -126,51 +106,15 @@ function hydratePropertyOpacityRows(rows, computed) {
 function capabilityFor(property, value, tokenTable) {
     return interpretValue(property, value, createInspectorValueContext(tokenTable))[0].capability;
 }
-let containerProbeSequence = 0;
-/**
- * Container conditions are element-relative. CSSOM exposes their text but has
- * no `matches` API, so ask the browser by applying an inert custom property to
- * the selected element inside an equivalent temporary @container wrapper.
- */
-function matchesContainerQuery(el, params) {
-    const doc = el.ownerDocument;
-    if (!doc.head || !params)
-        return false;
-    const id = ++containerProbeSequence;
-    const marker = `data-container-probe-${id}`;
-    const property = `--container-probe-${id}`;
-    const style = doc.createElement("style");
-    style.setAttribute("data-nudge-ui", "container-probe");
-    style.textContent = `@container ${params} { [${marker}] { ${property}: 1; } }`;
-    el.setAttribute(marker, "");
-    doc.head.appendChild(style);
-    try {
-        return getElementComputedStyle(el).getPropertyValue(property).trim() === "1";
-    }
-    catch {
-        return false;
-    }
-    finally {
-        style.remove();
-        el.removeAttribute(marker);
-    }
-}
-function atRulesApplyToElement(el, atRules) {
+function atRulesApplyToElement(el, atRules, evaluator) {
     const view = el.ownerDocument.defaultView;
-    return (atRules ?? []).every((atRule) => {
-        if (atRule.kind === "container")
-            return matchesContainerQuery(el, atRule.params);
-        if (atRule.kind === "supports")
-            return view?.CSS?.supports(atRule.params) ?? false;
-        return true;
-    });
+    if ((atRules ?? []).some((rule) => rule.kind === "supports" && !view?.CSS?.supports(rule.params)))
+        return false;
+    const conditions = (atRules ?? []).filter((rule) => rule.kind === "container").map((rule) => rule.params);
+    return conditions.length === 0 || evaluator.matches(el, conditions);
 }
-function collectLocalAliases(el, rules, ruleApplies) {
-    // Custom properties inherit independently of the property being resolved.
-    // Resolve the winning declaration separately for each element in the
-    // ancestor chain, then let the nearest declaration override inherited ones.
-    // This covers local aliases such as --color-error and inherited page tokens
-    // such as --color-ink without widening the build-time global catalog.
+function collectLocalAliases(el, rules) {
+    // Custom properties inherit independently, so each ancestor resolves its own winner and the nearest declaration wins.
     const lineage = [];
     let current = el;
     while (current) {
@@ -179,15 +123,18 @@ function collectLocalAliases(el, rules, ruleApplies) {
     }
     const aliases = new Map();
     for (const element of lineage.reverse()) {
+        const ruleApplies = makeRuleApplies(element);
         const candidates = new Map();
         rules.forEach((rule, index) => {
             if (rule.active === false)
                 return;
-            if (!ruleApplies(rule))
-                return;
             const match = matchRuleForElement(element, { rule, selectorText: rule.selectorText });
             if (!match)
                 return;
+            if (!rule.declarations.some((declaration) => declaration.property.startsWith("--")))
+                return;
+            if (!ruleApplies(rule))
+                return;
             const sourceOrder = rule.sourceOrder ?? index;
             const { specificity } = match;
             for (const declaration of rule.declarations) {
@@ -207,9 +154,7 @@ function collectLocalAliases(el, rules, ruleApplies) {
                 }
             }
         });
-        // Inline custom properties are also inherited by descendants. They are
-        // explicit cascade winners for their element, so include them at inline
-        // specificity without changing the managed-style rule contract.
+        // Inline custom properties are inherited too; at inline specificity they are explicit cascade winners.
         for (const property of Array.from(element.style)) {
             if (!property.startsWith("--"))
                 continue;
@@ -230,7 +175,7 @@ function collectLocalAliases(el, rules, ruleApplies) {
     }
     return aliases;
 }
-function makeRuleApplies(el) {
+function makeRuleApplies(el, evaluator = createContainerQueryEvaluator(el.ownerDocument)) {
     const matchingContexts = new Map();
     return (rule) => {
         const atRules = rule.atRules;
@@ -240,99 +185,95 @@ function makeRuleApplies(el) {
         const cached = matchingContexts.get(key);
         if (cached !== undefined)
             return cached;
-        const result = atRulesApplyToElement(el, atRules);
+        const result = atRulesApplyToElement(el, atRules, evaluator);
         matchingContexts.set(key, result);
         return result;
     };
 }
-/**
- * One matching pass over the rules for the element and its ancestors, with the
- * selector-match results shared between the element's own resolution and the
- * inherited phase. Local aliases are collected per element so no ancestor
- * re-walks the lineage × rules.
- */
-function resolveLineage(el, matcher) {
-    const lineage = [];
-    let current = el;
-    while (current) {
-        lineage.push(current);
-        current = current.parentElement;
+function relevantAncestorRule(rule) {
+    return rule.declarations.some(({ property }) => property.startsWith("--") || INHERITED_PROPERTIES.has(property));
+}
+function lineageElements(el) {
+    const elements = [];
+    for (let current = el; current; current = current.parentElement)
+        elements.unshift(current);
+    return elements;
+}
+function queryPairs(el, matcher) {
+    const pairs = [];
+    for (const element of lineageElements(el)) {
+        for (const { rule } of matcher.matchesForElement(element).matched) {
+            if (element !== el && !relevantAncestorRule(rule))
+                continue;
+            if (rule.declarations.length === 0)
+                continue;
+            if (rule.atRules?.some((context) => context.kind === "supports" && !element.ownerDocument.defaultView?.CSS?.supports(context.params)))
+                continue;
+            const conditions = (rule.atRules ?? []).filter((context) => context.kind === "container").map((context) => context.params);
+            if (conditions.length > 0)
+                pairs.push({ element, conditions });
+        }
     }
-    lineage.reverse();
-    const selectorMatches = new Map();
-    const allSelectorMatches = new Map();
-    for (const element of lineage) {
-        const { matched, allMatched } = matcher.matchesForElement(element);
-        selectorMatches.set(element, matched);
-        allSelectorMatches.set(element, allMatched);
+    return pairs;
+}
+/** Prepares both cascades together so a selection refresh inserts one probe sheet. */
+export function prefetchContainerQueries(elements, state, evaluator) {
+    const pairs = [];
+    for (const element of elements) {
+        const { rules } = collectCssomRules(element.ownerDocument);
+        pairs.push(...queryPairs(element, createRuleMatcher(rules, state)));
+        if (state === "base")
+            pairs.push(...queryPairs(element, createRuleMatcher(rules, "stable")));
     }
+    evaluator.prefetch(pairs);
+}
+function resolveLineage(el, matcher, evaluator) {
+    const lineage = lineageElements(el);
+    evaluator.prefetch(queryPairs(el, matcher));
     const byElement = new Map();
-    for (let index = 0; index < lineage.length; index++) {
-        const element = lineage[index];
-        const ruleApplies = makeRuleApplies(element);
-        const aliases = new Map();
-        for (const lineageElement of lineage.slice(0, index + 1)) {
-            const candidates = new Map();
-            for (const match of selectorMatches.get(lineageElement) ?? []) {
-                if (!ruleApplies(match.rule))
-                    continue;
-                const sourceOrder = match.rule.sourceOrder ?? 0;
-                for (const declaration of match.rule.declarations) {
-                    if (!declaration.property.startsWith("--"))
-                        continue;
-                    const candidate = {
-                        value: declaration.value.trim(),
-                        important: declaration.important,
-                        layer: match.rule.layer,
-                        layerOrder: match.rule.layerOrder,
-                        specificity: match.specificity,
-                        sourceOrder,
-                    };
-                    const previous = candidates.get(declaration.property);
-                    if (!previous || compareAuthorCascade(candidate, previous) >= 0) {
-                        candidates.set(declaration.property, candidate);
-                    }
-                }
-            }
-            for (const property of Array.from(lineageElement.style)) {
-                if (!property.startsWith("--"))
+    const inheritedAliases = new Map();
+    for (const element of lineage) {
+        const ruleApplies = makeRuleApplies(element, evaluator);
+        const { matched: selectorMatches, allMatched } = matcher.matchesForElement(element);
+        const matched = selectorMatches.filter(({ rule }) => (element === el || relevantAncestorRule(rule)) && rule.declarations.length > 0 && ruleApplies(rule));
+        const candidates = new Map();
+        for (const match of matched) {
+            // Conditions are evaluated against the declaration's own element; descendants inherit the alias, not the condition.
+            for (const declaration of match.rule.declarations) {
+                if (!declaration.property.startsWith("--"))
                     continue;
                 const candidate = {
-                    value: lineageElement.style.getPropertyValue(property).trim(),
-                    important: lineageElement.style.getPropertyPriority(property) === "important",
-                    inline: true,
-                    specificity: 100000000,
-                    sourceOrder: Number.MAX_SAFE_INTEGER,
+                    value: declaration.value.trim(), important: declaration.important,
+                    layer: match.rule.layer, layerOrder: match.rule.layerOrder,
+                    specificity: match.specificity, sourceOrder: match.rule.sourceOrder ?? 0,
                 };
-                const previous = candidates.get(property);
-                if (!previous || compareAuthorCascade(candidate, previous) >= 0) {
-                    candidates.set(property, candidate);
-                }
+                const previous = candidates.get(declaration.property);
+                if (!previous || compareAuthorCascade(candidate, previous) >= 0)
+                    candidates.set(declaration.property, candidate);
             }
-            for (const [name, candidate] of candidates)
-                aliases.set(name, candidate.value);
         }
-        const matched = [];
-        for (const match of selectorMatches.get(element) ?? []) {
-            if (!ruleApplies(match.rule))
+        for (const property of Array.from(element.style)) {
+            if (!property.startsWith("--"))
                 continue;
-            matched.push(match);
+            const candidate = {
+                value: element.style.getPropertyValue(property).trim(),
+                important: element.style.getPropertyPriority(property) === "important", inline: true,
+                specificity: 100000000, sourceOrder: Number.MAX_SAFE_INTEGER,
+            };
+            const previous = candidates.get(property);
+            if (!previous || compareAuthorCascade(candidate, previous) >= 0)
+                candidates.set(property, candidate);
         }
-        byElement.set(element, {
-            element,
-            matched,
-            allMatched: allSelectorMatches.get(element) ?? matched,
-            aliases,
-        });
+        for (const [name, candidate] of candidates)
+            inheritedAliases.set(name, candidate.value);
+        byElement.set(element, { element, matched, allMatched, aliases: new Map(inheritedAliases) });
     }
     return { lineage, byElement };
 }
 function rowsFromMatches(el, matched, aliases, tokenTable, allMatched = matched) {
     const map = new Map();
     const mediaCandidatesByProperty = new Map();
-    // Sort by source order ascending so rules are processed lowest-first.
-    // Map.set() naturally overwrites: higher specificity rules processed later win,
-    // and equal-specificity rules get "last in stylesheet order wins" (stable sort).
+    // Ascending source order with Map.set overwrite gives later-wins for equal specificity; relies on a stable sort.
     const sorted = [...matched].sort((a, b) => (a.rule.sourceOrder ?? 0) - (b.rule.sourceOrder ?? 0));
     const needsDirectionality = sorted.some(({ rule }) => rule.declarations.some(({ property }) => isLogicalBoxProperty(property)));
     const directionality = needsDirectionality ? elementDirectionality(el) : undefined;
@@ -432,12 +373,7 @@ function rowsFromMatches(el, matched, aliases, tokenTable, allMatched = matched)
     }
     return rows;
 }
-/**
- * Package-private cascade fixture seam. This exercises selector, layer,
- * importance, and interaction-state coordination while still crossing the
- * public value-semantics Interface through `resolveDeclaration`.
- * It is intentionally absent from the package exports.
- */
+/** Test-only cascade fixture seam, intentionally absent from the package exports. */
 export function resolveRuleFixture(el, rules, tokenTable) {
     const ruleApplies = makeRuleApplies(el);
     const matched = [];
@@ -453,7 +389,7 @@ export function resolveRuleFixture(el, rules, tokenTable) {
             continue;
         matched.push(match);
     }
-    const localAliases = collectLocalAliases(el, rules, ruleApplies);
+    const localAliases = collectLocalAliases(el, rules);
     return rowsFromMatches(el, matched, localAliases, tokenTable, allMatched);
 }
 function compareCandidate(a, b) {
@@ -553,8 +489,7 @@ function annotatePaintedValues(el, result, computed, inaccessible, mode) {
     for (const prop of result) {
         const cv = computed.getPropertyValue(prop.property);
         if (cv && !/\b(?:var|calc)\s*\(/.test(cv)) {
-            // A hypothetical state retains its authored value while `computed`
-            // records what the browser is painting. Live and base use painted values.
+            // Hypothetical states keep the authored value; live/base take the painted value.
             if (mode === "live" || mode === "base" || !prop.resolvedValue)
                 prop.resolvedValue = cv;
             prop.computed = cv;
@@ -569,15 +504,14 @@ function annotatePaintedValues(el, result, computed, inaccessible, mode) {
         }
     }
 }
-export function getResolvedProperties(el, tokenTable) {
+export function getResolvedProperties(el, tokenTable, evaluator = createContainerQueryEvaluator(el.ownerDocument)) {
     const doc = el.ownerDocument ?? document;
     const { rules, inaccessible } = collectCssomRules(doc);
-    const lineage = resolveLineage(el, createRuleMatcher(rules, "live"));
+    const lineage = resolveLineage(el, createRuleMatcher(rules, "live"), evaluator);
     return resolveMatchedProperties(el, tokenTable, lineage, inaccessible, "live");
 }
 function applyInlineDeclarations(el, result, tokenTable, computed, inaccessible) {
-    // Inline declarations participate in the cascade and are explicit evidence,
-    // but token attribution is only exact when the authored inline value uses a known token.
+    // Inline declarations are explicit evidence, but attribution is exact only for a known token.
     const inlineProperties = Array.from(el.style);
     const directionality = inlineProperties.some(isLogicalBoxProperty)
         ? directionalityFromComputed(el, computed)
@@ -624,10 +558,7 @@ function applyInlineDeclarations(el, result, tokenTable, computed, inaccessible)
     }
 }
 function promoteNumericCalcRows(result, tokenTable) {
-    // When a calc() expression only references static tokens the browser has
-    // already resolved it to a pixel value.  Reclassify the row so the UI
-    // shows the pixel value instead of the raw calc() string and allows
-    // numeric editing (nudge / token swap).
+    // A static-token calc() is already resolved to a pixel value; reclassify so the UI allows numeric editing.
     for (const prop of result) {
         if (prop.capability !== "raw" || prop.diagnostic)
             continue;
@@ -640,13 +571,8 @@ function promoteNumericCalcRows(result, tokenTable) {
         prop.capability = capabilityFor(prop.property, numeric, tokenTable);
     }
 }
-/**
- * Resolve the authored cascade for a chosen interaction state without relying
- * on the pointer's current location. This is intentionally attribution-first:
- * values with no authored declaration still fall back to the browser's live
- * computed value in the field layer.
- */
-export function getResolvedPropertiesForState(el, tokenTable, state) {
+/** Authored cascade for a chosen interaction state, independent of the pointer's live paint. */
+export function getResolvedPropertiesForState(el, tokenTable, state, evaluator = createContainerQueryEvaluator(el.ownerDocument)) {
     const doc = el.ownerDocument ?? document;
     const revisions = getDocumentRevisions(doc);
     const { rules, inaccessible } = collectCssomRules(doc);
@@ -659,13 +585,14 @@ export function getResolvedPropertiesForState(el, tokenTable, state) {
     }
     const cached = snapshots.get(state);
     if (cached
+        && queryPairs(el, matcher).length === 0
         && cached.elementRevision === revisions.element
         && cached.stylesheetRevision === revisions.stylesheet
         && cached.tokenTable === tokenTable
         && cached.dynamicMatchKey === dynamicMatchKey) {
         return cached.rows;
     }
-    const lineage = resolveLineage(el, matcher);
+    const lineage = resolveLineage(el, matcher, evaluator);
     const rows = resolveMatchedProperties(el, tokenTable, lineage, inaccessible, state);
     registerResolutionLineage(el);
     snapshots.set(state, {
@@ -678,12 +605,8 @@ export function getResolvedPropertiesForState(el, tokenTable, state) {
     return rows;
 }
 const stableTokenCache = new WeakMap();
-/**
- * Resolves the cascade with transient interaction selectors removed. Used when
- * an editor must stay linked to the stable token beneath a live :hover/:focus
- * paint. Memoized per (element, revisions, tokenTable).
- */
-export function getResolvedPropertiesStable(el, tokenTable) {
+/** Cascade with transient interaction selectors removed, so an editor stays linked to the token beneath a live :hover/:focus paint. */
+export function getResolvedPropertiesStable(el, tokenTable, evaluator = createContainerQueryEvaluator(el.ownerDocument)) {
     const doc = el.ownerDocument ?? document;
     const revisions = getDocumentRevisions(doc);
     const { rules, inaccessible } = collectCssomRules(doc);
@@ -691,13 +614,14 @@ export function getResolvedPropertiesStable(el, tokenTable) {
     const dynamicMatchKey = matcher.dynamicMatchKey(el);
     const cached = stableTokenCache.get(el);
     if (cached
+        && queryPairs(el, matcher).length === 0
         && cached.elementRevision === revisions.element
         && cached.stylesheetRevision === revisions.stylesheet
         && cached.tokenTable === tokenTable
         && cached.dynamicMatchKey === dynamicMatchKey) {
         return cached.rows;
     }
-    const lineage = resolveLineage(el, matcher);
+    const lineage = resolveLineage(el, matcher, evaluator);
     const rows = resolveMatchedProperties(el, tokenTable, lineage, inaccessible, "stable");
     stableTokenCache.set(el, {
         elementRevision: revisions.element,

package/dist/inspector/tokens/tokenAvailability.d.ts

@@ -1,18 +1,6 @@
 import type { TokenDefinition, TokenEntry, TokenTable } from "../../css/model/index.js";
 export declare function buildTokenTable(entries: readonly TokenEntry[]): TokenTable;
-export declare function getTokenTable(): TokenTable;
-/**
- * The build-time catalog is intentionally an inventory of every project token.
- * Element edits must instead use only custom properties resolved in that
- * element's cascade; a token defined by a lazy stylesheet is not usable until
- * that stylesheet is attached to the document. Entries are cached per element
- * until the element or stylesheet revision changes; the derived table reuses
- * `buildTokenTable`'s input-identity memo.
- */
+/** Element edits may use only custom properties resolved in this element's cascade; cached until the element or stylesheet revision changes. */
 export declare function getAvailableTokenEntriesForElement(el: HTMLElement, definitions?: readonly TokenDefinition[]): TokenEntry[];
-/**
- * Produces the page catalog used by the global Tokens settings section. When
- * the document exposes mappable source identities, declarations from unloaded
- * CSS files are removed. Opaque compiled URLs leave the adapter catalog intact.
- */
+/** Page catalog for the global Tokens section; declarations from unloaded CSS files are dropped when source identities are mappable. */
 export declare function getAvailableTokenCatalog(root?: HTMLElement, definitions?: readonly TokenDefinition[]): TokenDefinition[];

package/dist/inspector/tokens/tokenAvailability.js

@@ -17,16 +17,6 @@ export function buildTokenTable(entries) {
     tokenTableMemo.set(entries, table);
     return table;
 }
-let tableCache = null;
-let tableSource = null;
-export function getTokenTable() {
-    const { tokens } = getNudgeUiRuntimeConfig();
-    if (tableCache !== null && tableSource === tokens)
-        return tableCache;
-    tableCache = buildTokenTable(tokens);
-    tableSource = tokens;
-    return tableCache;
-}
 function isCustomPropertyToken(definition) {
     return definition.cssName.startsWith("--");
 }
@@ -43,14 +33,7 @@ function entryFromDefinition(definition, value) {
     };
 }
 const tokenEntriesCache = new WeakMap();
-/**
- * The build-time catalog is intentionally an inventory of every project token.
- * Element edits must instead use only custom properties resolved in that
- * element's cascade; a token defined by a lazy stylesheet is not usable until
- * that stylesheet is attached to the document. Entries are cached per element
- * until the element or stylesheet revision changes; the derived table reuses
- * `buildTokenTable`'s input-identity memo.
- */
+/** Element edits may use only custom properties resolved in this element's cascade; cached until the element or stylesheet revision changes. */
 export function getAvailableTokenEntriesForElement(el, definitions = getNudgeUiRuntimeConfig().tokenCatalog) {
     const revisions = getDocumentRevisions(el.ownerDocument ?? document);
     const cached = tokenEntriesCache.get(el);
@@ -63,8 +46,7 @@ export function getAvailableTokenEntriesForElement(el, definitions = getNudgeUiR
     const computed = getElementComputedStyle(el);
     const available = definitions.flatMap((definition) => {
         if (!isCustomPropertyToken(definition)) {
-            // Literal adapters (for example Tailwind v3) do not have a browser
-            // custom property to probe. Their adapter owns their availability.
+            // Literal adapters (e.g. Tailwind v3) have no custom property to probe; the adapter owns their availability.
             return [entryFromDefinition(definition, definition.declarations[0]?.value ?? "")];
         }
         const value = computed.getPropertyValue(definition.cssName).trim();
@@ -83,10 +65,7 @@ export function getAvailableTokenEntriesForElement(el, definitions = getNudgeUiR
     });
     return entries;
 }
-/**
- * Replaces build-time token declaration hints with declarations serialized by
- * the browser from the stylesheets currently attached to this document.
- */
+/** Replaces build-time declaration hints with declarations serialized from the attached stylesheets. */
 function hydrateTokenCatalogFromCssom(definitions, doc = document) {
     const needsHydration = (definition) => definition.declarations.length === 0
         || (definition.adapter === "vanilla-extract" && definition.declarations.every((declaration) => declaration.value.trim() === `var(${definition.cssName})`
@@ -160,13 +139,7 @@ function isLoadedCssSource(source, loadedSources) {
         || loaded.endsWith(`/${normalizedFile}`)
         || normalizedFile.endsWith(`/${loaded}`));
 }
-/**
- * Returns stylesheet identities only when the browser gave us a complete,
- * authored-source mapping. A compiled host can expose a mixture of source-like
- * and opaque CSS URLs; treating the mapped subset as complete would make
- * declarations behind the opaque URLs look lazy even while their variables are
- * live in the document.
- */
+/** Identities only for a complete authored-source mapping; a mapped subset cannot stand in for opaque compiled URLs. */
 function confidentlyLoadedStylesheetSources(definitions, loadedSources) {
     const cssSources = definitions.flatMap((definition) => definition.declarations
         .map((declaration) => declaration.source)
@@ -178,17 +151,12 @@ function confidentlyLoadedStylesheetSources(definitions, loadedSources) {
             known.add(loaded.path);
             continue;
         }
-        // One opaque compiled URL can contain any authored declaration, so the
-        // document does not provide enough evidence to remove unloaded sources.
+        // One opaque compiled URL can contain any authored declaration, so unloaded sources cannot be ruled out.
         return [];
     }
     return [...known];
 }
-/**
- * Produces the page catalog used by the global Tokens settings section. When
- * the document exposes mappable source identities, declarations from unloaded
- * CSS files are removed. Opaque compiled URLs leave the adapter catalog intact.
- */
+/** Page catalog for the global Tokens section; declarations from unloaded CSS files are dropped when source identities are mappable. */
 export function getAvailableTokenCatalog(root = document.documentElement, definitions = getNudgeUiRuntimeConfig().tokenCatalog) {
     const computed = getElementComputedStyle(root);
     const hydrated = hydrateTokenCatalogFromCssom(definitions, root.ownerDocument ?? document);

package/dist/inspector/tokens/tokenEdits.d.ts

@@ -1,3 +1,3 @@
-import type { TokenChangeRecord } from "../changes/changesLog.js";
+import type { TokenChangeRecord } from "../changes/types.js";
 import type { TokenCatalogRow } from "./catalog.js";
 export declare function setGlobalTokenValue(row: TokenCatalogRow, value: string): TokenChangeRecord | null;

package/dist/inspector/tokens/tokenEdits.js

@@ -1,4 +1,4 @@
-import { appendChange } from "../changes/changesLog.js";
+import { appendChange } from "../drafts/store.js";
 export function setGlobalTokenValue(row, value) {
     const nextValue = value.trim();
     if (!row.activeDeclaration || !nextValue)

package/dist/inspector/tokens/valueSemanticsAdapter.d.ts

@@ -2,5 +2,4 @@ import type { TokenEntry } from "../../css/model/index.js";
 import type { TokenOrigin, TokenTable } from "../../css/model/index.js";
 import type { Directionality, ValueSemanticsContext } from "../../css/value-semantics/index.js";
 export declare function inspectorTokenOrigin(entry: TokenEntry | undefined): TokenOrigin;
-/** Inspector Adapter for framework-specific token attribution facts. */
 export declare function createInspectorValueContext(tokenTable: TokenTable, localAliases?: ReadonlyMap<string, string>, directionality?: Directionality): ValueSemanticsContext;

package/dist/inspector/tokens/valueSemanticsAdapter.js

@@ -21,11 +21,28 @@ function colorTuple(value) {
     const rgb = /^rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)/.exec(trimmed);
     return rgb ? [rgb[1], rgb[2], rgb[3]].map((part) => String(Math.round(Number(part)))).join(",") : null;
 }
+const frameworkColorIndexes = new WeakMap();
+/** First Tailwind v3 token per color tuple. */
+function frameworkColorIndex(tokenTable) {
+    let index = frameworkColorIndexes.get(tokenTable);
+    if (index)
+        return index;
+    index = new Map();
+    for (const entry of Object.values(tokenTable)) {
+        if (entry.adapter !== "tailwind-v3")
+            continue;
+        const tuple = colorTuple(entry.value);
+        if (tuple && !index.has(tuple))
+            index.set(tuple, entry);
+    }
+    frameworkColorIndexes.set(tokenTable, index);
+    return index;
+}
 function directFrameworkColor(value, tokenTable) {
     const tuple = colorTuple(value);
     if (!tuple)
         return undefined;
-    return Object.values(tokenTable).find((entry) => entry.adapter === "tailwind-v3" && colorTuple(entry.value) === tuple);
+    return frameworkColorIndex(tokenTable).get(tuple);
 }
 function twLocalAliasPolicy(ref, inner) {
     if (!ref.startsWith("--tw-")) {
@@ -53,7 +70,6 @@ function twLocalAliasPolicy(ref, inner) {
             cycle: inner.cycle,
         };
 }
-/** Inspector Adapter for framework-specific token attribution facts. */
 export function createInspectorValueContext(tokenTable, localAliases = EMPTY_LOCAL_ALIASES, directionality) {
     return {
         tokenContext: {

package/dist/inspector/ui/AtRuleContext.d.ts

@@ -4,15 +4,15 @@ export interface AtRuleContextProviderProps {
     rows: readonly ResolvedProperty[];
     children?: ReactNode;
 }
-/**
- * Makes the active conditional source context available to fields that only
- * receive a property name (not their resolved property row) as props.
- */
+/** Fields that only receive a property name read their conditional context here. */
 export declare function AtRuleContextProvider({ rows, children }: AtRuleContextProviderProps): ReactElement;
 export declare function useFieldAtRules(property: string): readonly AtRuleCandidate[];
 export interface AtRuleIndicatorProps {
     atRules?: readonly (AtRuleContext | AtRuleCandidate)[];
     className?: string;
 }
-/** Compact, field-level attribution for the conditional rule that currently wins. */
+/**
+ * A ruler along the field's left edge: one segment per conditional rule plus the base, with the
+ * declaration currently winning the cascade highlighted. Hovering it lists the rules.
+ */
 export declare function AtRuleIndicator({ atRules, className }: AtRuleIndicatorProps): ReactElement | null;