nudge-ui 0.2.4 → 0.2.6

package/dist/inspector/tokens/TokenField.js

@@ -1,10 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { IconLinkOff } from "@tabler/icons-react";
-import { applyValueEdit, normalizeOpacityPercent, selectTokens, } from "../../css/value-semantics/index.js";
+import { applyValueEdit, isCalcExpression, normalizeOpacityPercent, selectTokens, } from "../../css/value-semantics/index.js";
 import { promoteToToken, swapToken } from "./editActions.js";
 import { setStyle } from "./editActions.js";
 import { completeCssValue } from "../styleEditors/completeCssValue.js";
+import { deriveActiveTokenName, isExpressionRow } from "../styleEditors/fieldValue.js";
 import { canNudgeCssValueByDrag, nudgeCssValue, nudgeCssValueByDrag, nudgeOpacityValue, supportsDragNudge, } from "../styleEditors/nudgeValue.js";
 import { valuePolicyFor } from "../styleEditors/valuePolicy.js";
 import { IconButton } from "../ui/IconButton.js";
@@ -16,10 +17,11 @@ import { Tooltip } from "../ui/Tooltip.js";
 import { cx } from "../ui/classNames.js";
 import { TokenChip } from "./TokenChip.js";
 import { startDragPointerLock } from "./dragPointerLock.js";
-import { createChangeHistoryGroup } from "../changes/draftChanges.js";
+import { createChangeHistoryGroup } from "../workspace/timeline.js";
 import { isMultiTarget } from "../selection/editTarget.js";
 import { inlineBlockedBy } from "../styleEditors/inlineAuthored.js";
 import { InlineStyleWarning } from "../ui/InlineStyleWarning.js";
+import { isMacPlatform } from "../shell/shortcuts.js";
 const NON_COLOR_FACTS = { hasEmbeddedAlpha: false, isExpression: false, opacityEditable: false };
 function colorFacts(value) {
     return selectTokens({
@@ -77,7 +79,7 @@ function releasePointerCapture(state) {
         // The browser may release capture before pointerup/pointercancel arrives.
     }
 }
-/** Returns the first family in a CSS family list without splitting var() fallbacks. */
+/** First family in a CSS family list; commas inside var() fallbacks are ignored. */
 function primaryFontFamily(value) {
     let depth = 0;
     let quote = null;
@@ -202,11 +204,7 @@ export function TokenValueField(props) {
     const showOpacity = isColor && !activeTokenHasEmbeddedAlpha
         && authoredColor.opacityEditable
         && (Boolean(activeTokenName) || attributionTokens.length === 0 || Boolean(opacity));
-    // One classification pass per entries change. selectTokens costs up to
-    // three CSS.supports calls per token, so classifying per token per render
-    // (chip mode is unbounded; raw mode runs per keystroke) dominates this
-    // field's render cost. Map misses fall back to direct classification for
-    // synthetic entries that are not part of the catalog list.
+    // Classification costs up to three CSS.supports calls per token, so it runs once per entries change.
     const groupByTokenName = useMemo(() => {
         const groups = new Map();
         for (const entry of entries)
@@ -235,6 +233,10 @@ export function TokenValueField(props) {
         return Array.from(new Set(suggestions));
     }, [suggestions]);
     function handleSuggestionSelect(value) {
+        if (value === DETACH_VALUE) {
+            handleDelink();
+            return;
+        }
         const rawSuggestion = decodeRawSuggestion(value);
         if (rawSuggestion !== null) {
             selectedFromPopover.current = true;
@@ -264,8 +266,7 @@ export function TokenValueField(props) {
         onCommitRaw(formatted);
     }
     function handleDelink() {
-        // A token-backed alpha expression is represented by a chip, but unlinking
-        // it should preserve the complete authored color expression and its alpha.
+        // Unlinking must preserve the complete authored color expression and its alpha.
         const value = opacity ? committedValue : activeToken?.value || resolvedValue || committedValue;
         setActiveTokenName(null);
         setRawValue(value);
@@ -467,9 +468,20 @@ export function TokenValueField(props) {
     if (activeToken) {
         const chipValue = chipVariant === "small" ? stripCssUnit(activeToken.value) : activeToken.name;
         const embedColorSwatch = isColor && chipVariant !== "small";
-        return (_jsxs("span", { className: cx("token-field", isColor && "token-field--color", embedColorSwatch && "token-field--color-chip", blockedBy !== null && "token-field--blocked", className), "data-test": "token-field", "data-property": property, "aria-disabled": fieldDisabled || undefined, "aria-label": label, children: [renderLeading(), embedColorSwatch ? null : colorControlEl, _jsxs(TokenChip, { size: chipVariant, "data-group": groupByTokenName.get(activeToken.name) ?? tokenGroup(activeToken), children: [_jsx(PopoverListbox, { query: "", value: activeToken.name, open: isTokenPickerOpen, trigger: (_jsxs(TokenChip.Picker, { children: [embedColorSwatch ? colorControlEl : null, _jsx(TokenChip.Label, { title: chipVariant === "small" ? activeToken.name : undefined, children: chipValue })] })), triggerClassName: "token-chip__trigger", triggerDataTest: "token-chip", triggerAriaLabel: `Change ${property} token`, searchable: true, searchPlaceholder: "Search tokens\u2026", searchAriaLabel: "Search tokens", items: [...rawSuggestionItems, ...relevantTokens.map((entry) => tokenSuggestion(entry, groupByTokenName))], onQueryChange: () => undefined, onOpenChange: setTokenPickerOpen, disabled: fieldDisabled, onSelect: (value) => {
+        return (_jsxs("span", { className: cx("token-field", isColor && "token-field--color", embedColorSwatch && "token-field--color-chip", blockedBy !== null && "token-field--blocked", className), "data-test": "token-field", "data-property": property, "aria-disabled": fieldDisabled || undefined, "aria-label": label, children: [renderLeading(), embedColorSwatch ? null : colorControlEl, _jsxs(TokenChip, { size: chipVariant, "data-group": groupByTokenName.get(activeToken.name) ?? tokenGroup(activeToken), children: [_jsx(PopoverListbox, { query: "", value: activeToken.name, open: isTokenPickerOpen, trigger: (_jsxs(TokenChip.Picker, { children: [embedColorSwatch ? colorControlEl : null, _jsx(TokenChip.Label, { title: chipVariant === "small" ? activeToken.name : undefined, children: chipValue })] })), triggerClassName: "token-chip__trigger", triggerDataTest: "token-chip", triggerAriaLabel: `Change ${property} token`, searchable: true, searchPlaceholder: "Search tokens\u2026", searchAriaLabel: "Search tokens", searchOnKeyDown: (event) => {
+                                if (fieldDisabled || !isDetachKey(event))
+                                    return;
+                                event.preventDefault();
+                                event.stopPropagation();
+                                setTokenPickerOpen(false);
+                                handleDelink();
+                            }, items: [
+                                detachItem(),
+                                ...rawSuggestionItems,
+                                ...relevantTokens.map((entry) => tokenSuggestion(entry, groupByTokenName)),
+                            ], onQueryChange: () => undefined, onOpenChange: setTokenPickerOpen, disabled: fieldDisabled, onSelect: (value) => {
                                 handleSuggestionSelect(value);
-                            } }), _jsx(TokenChip.Action, { children: _jsx(Tooltip, { stableTrigger: true, children: _jsx(IconButton, { variant: "quiet", size: "compact", style: { borderRadius: "var(--radius-4)" }, label: "Replace with raw value", "data-test": "delink-btn", disabled: fieldDisabled, onClick: handleDelink, children: _jsx(IconLinkOff, { size: chipVariant === "small" ? 12 : 14, stroke: 1.75, "aria-hidden": "true" }) }) }) })] }), opacityControl, _jsx(AtRuleIndicator, { atRules: fieldAtRules }), trailing ? _jsx("span", { className: "token-field__trailing", children: trailing }) : null, _jsx(InlineStyleWarning, { blockedBy: blockedBy, dataTest: inlineWarningDataTest, tooltipDataTest: inlineWarningTooltipDataTest })] }));
+                            } }), chipVariant === "small" ? null : (_jsx(TokenChip.Action, { children: _jsx(Tooltip, { stableTrigger: true, children: _jsx(IconButton, { variant: "quiet", size: "compact", style: { borderRadius: "var(--radius-4)" }, label: "Detach token", "data-test": "delink-btn", disabled: fieldDisabled, onClick: handleDelink, children: _jsx(IconLinkOff, { size: 14, stroke: 1.75, "aria-hidden": "true" }) }) }) }))] }), opacityControl, _jsx(AtRuleIndicator, { atRules: fieldAtRules }), trailing ? _jsx("span", { className: "token-field__trailing", children: trailing }) : null, _jsx(InlineStyleWarning, { blockedBy: blockedBy, dataTest: inlineWarningDataTest, tooltipDataTest: inlineWarningTooltipDataTest })] }));
     }
     const showPopover = isFocused && (filteredTokens.length > 0 || availableSuggestions.length > 0);
     return (_jsxs("span", { className: cx("token-field", "token-field--raw", isColor && "token-field--color", blockedBy !== null && "token-field--blocked", className), "data-test": "token-field", "data-property": property, "aria-disabled": fieldDisabled || undefined, "aria-label": label, children: [renderLeading(), colorControlEl, _jsx(PopoverListbox, { query: rawValue, value: null, open: showPopover, placeholder: property, inputRef: inputRef, inputAppearance: "embedded", inputDataTest: inputDataTest, inputOnFocus: () => {
@@ -494,7 +506,7 @@ function arrowDirection(key) {
     return null;
 }
 export function TokenField(props) {
-    const { property, semanticSlot, tokenRow, selection, initialValue, displayValue, domElement: el, editTarget, entries, suggestions, inputDataTest, onAfterEdit, editMetadata, leading, trailing, className, label, chipVariant, formatRawValue: formatRawValueProp, disabled = false, mixed = false, attributionTokens, inlineWarningDataTest, inlineWarningTooltipDataTest, } = props;
+    const { property, semanticSlot, tokenRow, selection, initialValue, displayValue, domElement: el, editTarget, entries, suggestions, inputDataTest, onAfterEdit, editMetadata, leading, trailing, className, label, chipVariant, formatRawValue: formatRawValueProp, disabled = false, mixed = false, attributionTokens, inlineWarningDataTest, inlineWarningTooltipDataTest, interceptRaw, } = props;
     const selectedProperty = selection && selection.elements.length > 1
         ? selection.getProperty(property)
         : null;
@@ -510,25 +522,18 @@ export function TokenField(props) {
         && tokenRow.opacity.tokenName !== tokenRow.tokenName
         ? tokenRow.tokenName
         : null;
-    const expression = Boolean(tokenRow && (tokenRow.capability === "raw" || tokenRow.capability === "composite"
-        || tokenRow.modifiers?.some((modifier) => modifier.kind === "alpha")
-        || tokenRow.color?.isExpression));
+    const expression = isExpressionRow(tokenRow ?? null);
     const authored = tokenRow?.authored ?? tokenRow?.declaredValue ?? "";
-    const isCalcAuthored = /\bcalc\s*\(/i.test(authored);
-    const selectedTokenName = selectedProperty?.token.kind === "common"
-        ? selectedProperty.token.name
-        : null;
-    const activeTokenName = effectiveMixed
-        ? null
-        : tokenBackedOpacityName
-            ?? (expression || isCalcAuthored
-                ? null
-                : selectedProperty ? selectedTokenName : tokenRow?.tokenName ?? null);
+    const isCalcAuthored = isCalcExpression(authored);
+    const activeTokenName = deriveActiveTokenName({
+        row: tokenRow ?? null,
+        selectedProperty,
+        mixed: effectiveMixed,
+        authored,
+        override: tokenBackedOpacityName,
+    });
     const fallbackValue = initialValue ?? structuredBorderValue(property, tokenRow) ?? computedRaw(el, property);
-    // When a calc() was simplified to a numeric value we suppress the token
-    // chip so the UI shows the resolved pixel value, not the internal
-    // multiplier token (e.g. --spacing).  The authored expression stays
-    // accessible via the row for diagnostics.
+    // Suppress the chip for calc()-derived values so the UI shows the resolved pixel value, not the internal multiplier token.
     const authoredOrComputed = tokenBackedOpacityName
         ? authored
         : expression || (!activeTokenName && !isCalcAuthored)
@@ -544,8 +549,7 @@ export function TokenField(props) {
         : null;
     let resolvedValue = tokenRow?.propertyOpacity?.value ?? tokenRow?.resolvedValue ?? committedValue;
     if (property === "background-color") {
-        // Background rows can contain the complete computed shorthand. Extract
-        // its color before passing it to the color control, preserving alpha.
+        // Background rows can carry the full computed shorthand; the color control needs its color part.
         const style = el.ownerDocument.createElement("span").style;
         style.background = resolvedValue;
         resolvedValue = style.backgroundColor || resolvedValue;
@@ -559,6 +563,8 @@ export function TokenField(props) {
                 return formatRawValueProp(value);
             return completeCssValue(value.trim(), valuePolicyFor(property));
         }, onCommitRaw: (value) => {
+            if (interceptRaw?.(value))
+                return;
             if (setStyle(editTarget ?? el, property, value, effectiveMetadata))
                 onAfterEdit?.();
         }, onCommitOpacity: (value) => {
@@ -606,6 +612,21 @@ function tokenSuggestion(entry, groups) {
     };
 }
 const RAW_SUGGESTION_PREFIX = "\u0000raw:";
+const DETACH_VALUE = "\u0000detach";
+function detachItem() {
+    return {
+        value: DETACH_VALUE,
+        label: "Detach token",
+        "data-test": "detach-token-item",
+        leading: _jsx(IconLinkOff, { size: 14, stroke: 1.75, "aria-hidden": "true" }),
+        trailing: _jsx("kbd", { className: "token-shortcut", children: isMacPlatform() ? "⌫" : "Del" }),
+    };
+}
+function isDetachKey(event) {
+    return (event.key === "Backspace" || event.key === "Delete")
+        && event.currentTarget.value === ""
+        && !event.altKey && !event.ctrlKey && !event.metaKey && !event.shiftKey;
+}
 function rawSuggestion(value) {
     return {
         value: `${RAW_SUGGESTION_PREFIX}${value}`,

package/dist/inspector/tokens/TokensPanel.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo, useState } from "react";
-import { isTokenChange, useChanges } from "../changes/changesLog.js";
+import { isTokenChange } from "../changes/types.js";
+import { useChanges } from "../drafts/store.js";
 import { TextInput } from "../ui/TextInput.js";
 import { ControlSurface } from "../ui/ControlSurface.js";
 import { Disclosure } from "../ui/Disclosure.js";

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

@@ -25,16 +25,7 @@ export interface TokenRuntime {
     layerOrder(name: string): number | undefined;
 }
 export declare function isTokenContextActive(context: TokenContext, runtime: TokenRuntime): boolean;
-/**
- * Strips host-declared structural scoping markers from a selector so
- * human-facing labels present only author vocabulary (ADR-0011). The marker
- * grammar — Astro's `[data-astro-cid-<hash>]` attribute selectors or
- * `.astro-<hash>` classes, a future Vue/Svelte equivalent — is declared by
- * the host Adapter through the runtime configuration; the raw selector is
- * retained in `context.selector` so resolution keeps matching the rendered
- * DOM. A `:where(...)` wrapper left empty by the removals disappears
- * entirely.
- */
+/** Strips host-declared scoping markers for labels; `context.selector` keeps the raw selector for matching. */
 export declare function humanizeSelector(selector: string, scopingPattern: RegExp | null): string;
 export declare function contextLabel(context: TokenContext): string;
 export declare function sourceParts(source: string): {
@@ -46,6 +37,7 @@ export declare function selectorForContext(context: TokenContext): string;
 export declare function classifyCatalogToken(name: string, value?: string): TokenCatalogGroup;
 export declare function buildTokenCatalogRows(catalog: TokenDefinition[], root?: HTMLElement, suppliedRuntime?: TokenRuntime): TokenCatalogRow[];
 export declare function filterTokenRows(rows: readonly TokenCatalogRow[], query: string): TokenCatalogRow[];
+/** An alias is a whole-string reference with no fallback; a fallback changes the value. */
 export declare function aliasName(value: string): string | null;
 export declare function createsAliasCycle(tokenName: string, candidateName: string, authoredValues: ReadonlyMap<string, string>): boolean;
 export declare function compatibleTokenNames(row: TokenCatalogRow, rows: readonly TokenCatalogRow[]): Set<string>;

package/dist/inspector/tokens/catalog.js

@@ -1,6 +1,7 @@
 import { getScopingSelectorPattern } from "../runtime/runtimeConfig.js";
 import { getElementComputedStyle, getElementWindow } from "../runtime/domRealm.js";
 import { selectTokens } from "../../css/value-semantics/index.js";
+import { parseSingleVarReference } from "../../css/value-semantics/cssSyntax.js";
 import { cascadeLayerOrder } from "./resolution/cssomCollector.js";
 import { compareAuthorCascade } from "./resolution/cascade.js";
 import { computeSpecificityCore } from "./resolution/selectorSemantics.js";
@@ -83,16 +84,7 @@ function pickWinningDeclaration(declarations, runtime) {
     });
     return winner;
 }
-/**
- * Strips host-declared structural scoping markers from a selector so
- * human-facing labels present only author vocabulary (ADR-0011). The marker
- * grammar — Astro's `[data-astro-cid-<hash>]` attribute selectors or
- * `.astro-<hash>` classes, a future Vue/Svelte equivalent — is declared by
- * the host Adapter through the runtime configuration; the raw selector is
- * retained in `context.selector` so resolution keeps matching the rendered
- * DOM. A `:where(...)` wrapper left empty by the removals disappears
- * entirely.
- */
+/** Strips host-declared scoping markers for labels; `context.selector` keeps the raw selector for matching. */
 export function humanizeSelector(selector, scopingPattern) {
     const stripped = scopingPattern === null ? selector : selector.replace(scopingPattern, "");
     return stripped
@@ -160,9 +152,10 @@ export function filterTokenRows(rows, query) {
         || row.definition.cssName.toLowerCase().includes(needle)
         || row.definition.declarations.some((declaration) => declaration.value.toLowerCase().includes(needle)));
 }
-const EXACT_ALIAS = /^var\(\s*(--[\w-]+)\s*\)$/;
+/** An alias is a whole-string reference with no fallback; a fallback changes the value. */
 export function aliasName(value) {
-    return value.trim().match(EXACT_ALIAS)?.[1] ?? null;
+    const reference = parseSingleVarReference(value);
+    return reference && reference.fallback === undefined ? reference.name : null;
 }
 export function createsAliasCycle(tokenName, candidateName, authoredValues) {
     const visited = new Set([tokenName]);

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

@@ -1,4 +1,3 @@
-/** Keeps mouse drags relative, including when the handle is inside a shadow root. */
 export declare function startDragPointerLock(handle: HTMLElement, point: {
     x: number;
     y: number;

package/dist/inspector/tokens/dragPointerLock.js

@@ -1,5 +1,4 @@
 import { showLockedDragCursor } from "../ui/dragCursor.js";
-/** Keeps mouse drags relative, including when the handle is inside a shadow root. */
 export function startDragPointerLock(handle, point, onMove, onEnd) {
     const doc = handle.ownerDocument;
     const root = handle.getRootNode();
@@ -45,7 +44,7 @@ export function startDragPointerLock(handle, point, onMove, onEnd) {
     doc.addEventListener("pointerlockchange", onLockChange);
     doc.addEventListener("pointerlockerror", onLockError);
     try {
-        // Older implementations return void. Rejections retain pointer-capture dragging.
+        // Older implementations return void; a rejection still leaves pointer-capture dragging.
         const request = handle.requestPointerLock();
         if (request)
             void request.catch(onLockError);
@@ -62,7 +61,7 @@ export function startDragPointerLock(handle, point, onMove, onEnd) {
             doc.removeEventListener("mouseup", onMouseUp);
             if (isLocked())
                 doc.exitPointerLock();
-            // A request can finish after mouse-up or unmount. Release that late lock too.
+            // A pending request can acquire the lock after mouse-up; release that late lock too.
             if (!pending)
                 removeLockListeners();
         },

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

@@ -1,13 +1,13 @@
 import type { TokenEntry } from "../../css/model/index.js";
-import type { ElementChangeRecord } from "../changes/changesLog.js";
+import type { ElementChangeRecord } from "../changes/types.js";
 import { type EditTarget } from "../selection/editTarget.js";
-export type { ChangeRecord } from "../changes/changesLog.js";
-export { getPendingRules, getChangesList as getChangeRecords, clearActiveDraft as resetPendingRules } from "../changes/changesLog.js";
+export type { ChangeRecord } from "../changes/types.js";
+export { getPendingRules, getChangesList as getChangeRecords, clearActiveDraft as resetPendingRules } from "../drafts/store.js";
 export interface StyleEditMetadata {
     sourceProperty?: string;
     sourceAuthoredValue?: string;
 }
-/** Returns whether a style write can address every element in the target safely. */
+/** True only when a write can address every element in the target. */
 export declare function canEditStyles(target: EditTarget): boolean;
 export declare function buildSelector(cid: string, src: string): string | null;
 export declare function swapToken(target: EditTarget, property: string, newToken: TokenEntry, oldToken: TokenEntry | null, metadata?: StyleEditMetadata): ElementChangeRecord | null;

package/dist/inspector/tokens/editActions.js

@@ -1,9 +1,9 @@
 import { parseDataSrc } from "../selection/resolveSelection.js";
-import { appendChanges, } from "../changes/changesLog.js";
+import { appendChanges } from "../drafts/store.js";
 import { canPlanBatchEditScopes, planBatchEditScopes, selectorForElement, sourceSiteSelector } from "../selection/editScope.js";
 import { getActiveStyleState, selectorForInteractionState } from "../shell/styleState.js";
 import { getStateStyleValue } from "../shell/stateValue.js";
-import { boundRuntimeEvidence, isRuntimeCreatedElement, isRuntimeGeneratedSource, normalizeRuntimeTag, normalizeRuntimeText, } from "../runtime/staticHtmlRuntimeIdentity.js";
+import { boundRuntimeEvidence, isRuntimeCreatedElement, isRuntimeGeneratedSource, normalizeRuntimeTag, normalizeRuntimeText, runtimeDomPath, } from "../runtime/staticHtmlRuntimeIdentity.js";
 import { targetElements } from "../selection/editTarget.js";
 import { changeKey } from "../changes/model.js";
 function boundedRenderedText(el) {
@@ -18,6 +18,8 @@ function sourceFields(el) {
         text: boundedRenderedText(el),
         props: boundRuntimeEvidence(el.getAttribute("data-cprops")),
         ariaLabel: boundRuntimeEvidence(el.getAttribute("aria-label")),
+        domPath: runtimeDomPath(el),
+        elementId: boundRuntimeEvidence(el.id || null),
     });
     if (isRuntimeCreatedElement(el) || isRuntimeGeneratedSource(src)) {
         return {
@@ -28,9 +30,7 @@ function sourceFields(el) {
         };
     }
     if (!parsed) {
-        // Authored markup whose source annotation is absent or unusable — for
-        // example Astro dev-annotation degraded mode. Prompts must say the
-        // location is unknown instead of rendering a fabricated `file:0`.
+        // Unannotated authored markup (e.g. Astro degraded mode): prompts must report an unknown location, never a fabricated `file:0`.
         return {
             file: "",
             line: 0,
@@ -45,11 +45,15 @@ function sourceFields(el) {
         sourceEvidence: {
             tagName: normalizeRuntimeTag(el.tagName),
             props: boundRuntimeEvidence(el.getAttribute("data-cprops")),
+            text: boundedRenderedText(el),
+            ariaLabel: boundRuntimeEvidence(el.getAttribute("aria-label")),
+            domPath: runtimeDomPath(el),
+            elementId: boundRuntimeEvidence(el.id || null),
         },
     };
 }
-export { getPendingRules, getChangesList as getChangeRecords, clearActiveDraft as resetPendingRules } from "../changes/changesLog.js";
-/** Returns whether a style write can address every element in the target safely. */
+export { getPendingRules, getChangesList as getChangeRecords, clearActiveDraft as resetPendingRules } from "../drafts/store.js";
+/** True only when a write can address every element in the target. */
 export function canEditStyles(target) {
     return canPlanBatchEditScopes(targetElements(target));
 }

package/dist/inspector/tokens/resolution/cascade.d.ts

@@ -6,9 +6,5 @@ export interface AuthorCascadePriority {
     specificity: number;
     sourceOrder: number;
 }
-/**
- * Compares declarations from the author origin. Positive means `a` wins.
- * Normal declarations prefer unlayered rules and later layers; important
- * declarations reverse both relationships as required by the CSS cascade.
- */
+/** Positive means `a` wins; important declarations reverse layer precedence per the CSS cascade. */
 export declare function compareAuthorCascade(a: AuthorCascadePriority, b: AuthorCascadePriority): number;

package/dist/inspector/tokens/resolution/cascade.js

@@ -1,8 +1,4 @@
-/**
- * Compares declarations from the author origin. Positive means `a` wins.
- * Normal declarations prefer unlayered rules and later layers; important
- * declarations reverse both relationships as required by the CSS cascade.
- */
+/** Positive means `a` wins; important declarations reverse layer precedence per the CSS cascade. */
 export function compareAuthorCascade(a, b) {
     const aImportant = Boolean(a.important);
     const bImportant = Boolean(b.important);

package/dist/inspector/tokens/resolution/containerQueryEvaluator.d.ts

@@ -0,0 +1,11 @@
+export interface ContainerQueryPair {
+    element: HTMLElement;
+    /** Outer-to-inner conditions, including container names. */
+    conditions: readonly string[];
+}
+export interface ContainerQueryEvaluator {
+    prefetch(pairs: readonly ContainerQueryPair[]): void;
+    matches(element: HTMLElement, conditions: readonly string[]): boolean;
+}
+/** Each pair gets its own probe property so inherited values cannot answer another element's query; nothing survives a batch. */
+export declare function createContainerQueryEvaluator(doc: Document): ContainerQueryEvaluator;

package/dist/inspector/tokens/resolution/containerQueryEvaluator.js

@@ -0,0 +1,82 @@
+import { countInspectionWork } from "../../inspection/performanceDiagnostics.js";
+import { adoptStylesheet, allowsStyleElements, releaseAdoptedStylesheet } from "../../runtime/ownedStylesheets.js";
+const PROBE_SHEET_KEY = "nudge-ui-container-probe";
+let nextProbeId = 0;
+/** Each pair gets its own probe property so inherited values cannot answer another element's query; nothing survives a batch. */
+export function createContainerQueryEvaluator(doc) {
+    const results = new WeakMap();
+    const key = (conditions) => JSON.stringify(conditions);
+    function prefetch(pairs) {
+        const pending = [];
+        for (const pair of pairs) {
+            if (pair.element.ownerDocument !== doc)
+                throw new TypeError("Container query target belongs to another document.");
+            if (pair.conditions.length === 0)
+                continue;
+            let values = results.get(pair.element);
+            if (!values) {
+                values = new Map();
+                results.set(pair.element, values);
+            }
+            const conditionKey = key(pair.conditions);
+            if (values.has(conditionKey))
+                continue;
+            // Reserve the pair before collecting the rest of this batch.
+            values.set(conditionKey, false);
+            const id = ++nextProbeId;
+            pending.push({ ...pair, key: conditionKey, marker: `data-container-probe-${id}`, property: `--nudge-container-probe-${id}` });
+        }
+        if (!doc.head || pending.length === 0)
+            return;
+        const cssText = pending.map(({ conditions, marker, property }) => {
+            let rule = `[${marker}] { ${property}: 1 !important; }`;
+            for (let index = conditions.length - 1; index >= 0; index--) {
+                rule = `@container ${conditions[index]} { ${rule} }`;
+            }
+            return rule;
+        }).join("\n");
+        const sheet = allowsStyleElements(doc) ? doc.createElement("style") : null;
+        countInspectionWork(doc, "probePairs", pending.length);
+        countInspectionWork(doc, "probeBatches");
+        try {
+            for (const pair of pending)
+                pair.element.setAttribute(pair.marker, "");
+            if (sheet) {
+                sheet.setAttribute("data-nudge-ui", "container-probe");
+                sheet.textContent = cssText;
+                doc.head.append(sheet);
+            }
+            else {
+                adoptStylesheet(doc, PROBE_SHEET_KEY, cssText);
+            }
+            const styles = new Map();
+            for (const pair of pending) {
+                let style = styles.get(pair.element);
+                if (!style) {
+                    style = doc.defaultView?.getComputedStyle(pair.element);
+                    if (style)
+                        styles.set(pair.element, style);
+                }
+                results.get(pair.element).set(pair.key, style?.getPropertyValue(pair.property).trim() === "1");
+            }
+        }
+        finally {
+            if (sheet)
+                sheet.remove();
+            else
+                releaseAdoptedStylesheet(doc, PROBE_SHEET_KEY);
+            for (const pair of pending)
+                pair.element.removeAttribute(pair.marker);
+        }
+    }
+    return {
+        prefetch,
+        matches(element, conditions) {
+            countInspectionWork(doc, "containerChecks");
+            if (conditions.length === 0)
+                return true;
+            prefetch([{ element, conditions }]);
+            return results.get(element)?.get(key(conditions)) ?? false;
+        },
+    };
+}

package/dist/inspector/tokens/resolution/cssomCollector.d.ts

@@ -3,32 +3,17 @@ export interface DocumentRevisions {
     element: number;
     stylesheet: number;
 }
-/**
- * Subscribes to cascade revisions for one document. This is the narrow
- * document-scoped seam used by the browser inspection Module.
- */
 export declare function subscribeDocumentRevision(doc: Document, cb: (revisions: Readonly<DocumentRevisions>) => void): () => void;
-/**
- * Elements whose attribute changes can affect a cached cascade outcome. The
- * observer only counts attribute mutations against registered elements so
- * unrelated host churn (React commits, hover states, animations) cannot bump
- * the element revision. Registration is idempotent.
- */
+/** Only attribute mutations on registered elements bump the element revision; unrelated host churn is ignored. */
 export declare function registerResolutionElement(el: Element): void;
 export declare function registerResolutionLineage(element: HTMLElement): void;
-/** Releases the observer, listener, and cached state owned by one document. */
 export declare function disposeDocumentResolution(doc: Document): void;
 export declare function retainDocumentResolution(doc: Document): () => void;
 export declare function documentRevisions(doc: Document): DocumentRevisions;
-/** Invalidates CSSOM-derived snapshots after programmatic stylesheet edits. */
 export declare function invalidateStyleResolutionCache(doc?: Document): void;
-/**
- * Reads the declarations the browser accepted for a style rule. This is the
- * semantic source for authored values; it intentionally does not inspect the
- * stylesheet element's original text. CSSOM may expose a shorthand as empty
- * longhand entries through indexed enumeration, so prefer its serialized
- * declaration block and use enumeration as a compatibility fallback.
- */
+/** Inspector-only invalidation; page sheets are re-read only if their objects changed. */
+export declare function invalidateOwnedStyleResolution(doc?: Document): void;
+/** Prefers the serialized declaration block; enumeration is a fallback because a shorthand can enumerate empty longhands. */
 export declare function declarationsFromCssom(style: CSSStyleDeclaration): StyleDeclaration[];
 export declare function collectRules(doc: Document): {
     revision: number;