nudge-ui 0.2.0 → 0.2.2

package/dist/inspector/tokens/TokenField.js

@@ -1,11 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useMemo, useRef, useState } from "react";
+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 { promoteToToken, swapToken } from "./editActions.js";
 import { setStyle } from "./editActions.js";
 import { completeCssValue } from "../styleEditors/completeCssValue.js";
-import { nudgeCssValue, nudgeOpacityValue } from "../styleEditors/nudgeValue.js";
+import { canNudgeCssValueByDrag, nudgeCssValue, nudgeCssValueByDrag, nudgeOpacityValue, supportsDragNudge, } from "../styleEditors/nudgeValue.js";
 import { valuePolicyFor } from "../styleEditors/valuePolicy.js";
 import { IconButton } from "../ui/IconButton.js";
 import { PopoverListbox } from "../ui/PopoverListbox.js";
@@ -13,6 +13,8 @@ import { ColorSwatch } from "../ui/ColorSwatch.js";
 import { getStateStyleValue } from "../shell/stateValue.js";
 import { AtRuleIndicator, useFieldAtRules } from "../ui/AtRuleContext.js";
 import { TokenChip } from "./TokenChip.js";
+import { startDragPointerLock } from "./dragPointerLock.js";
+import { createChangeHistoryGroup } from "../changes/workspaceChanges.js";
 import { isMultiTarget } from "../selection/editTarget.js";
 const NON_COLOR_FACTS = { hasEmbeddedAlpha: false, isExpression: false, opacityEditable: false };
 function colorFacts(value) {
@@ -61,6 +63,16 @@ function formatNumber(value) {
 function stripCssUnit(value) {
     return value.replace(/^(-?\d+(?:\.\d+)?)(px|rem|em|vh|vw|vmin|vmax|%|ch|ex|cm|mm|in|pt|pc)$/i, "$1");
 }
+function releasePointerCapture(state) {
+    try {
+        if (state.handle.hasPointerCapture?.(state.pointerId)) {
+            state.handle.releasePointerCapture(state.pointerId);
+        }
+    }
+    catch {
+        // The browser may release capture before pointerup/pointercancel arrives.
+    }
+}
 /** Returns the first family in a CSS family list without splitting var() fallbacks. */
 function primaryFontFamily(value) {
     let depth = 0;
@@ -138,8 +150,9 @@ function browserRecognizesColor(value) {
 function NativeColorSwatch({ value, onChange, disabled, }) {
     const resolvedHex = colorValueToHex(value);
     const hex = resolvedHex ?? "#000000";
-    const hasRenderableColor = resolvedHex !== null || browserRecognizesColor(value);
-    return (_jsxs("label", { className: "token-color-control", "data-resolved": hasRenderableColor ? "true" : "false", children: [_jsx(ColorSwatch, { color: resolvedHex ?? (value.trim() || "transparent"), "data-test": "token-color-swatch" }), _jsx("input", { className: "token-color-control__input", "data-test": "token-color-input", type: "color", value: hex, disabled: disabled, "aria-label": "Choose color", onChange: (event) => onChange(event.target.value) })] }));
+    const cssColor = browserRecognizesColor(value) ? value.trim() : resolvedHex;
+    const hasRenderableColor = cssColor !== null;
+    return (_jsxs("label", { className: "token-color-control", "data-resolved": hasRenderableColor ? "true" : "false", children: [_jsx(ColorSwatch, { color: cssColor ?? "transparent", "data-test": "token-color-swatch" }), _jsx("input", { className: "token-color-control__input", "data-test": "token-color-input", type: "color", value: hex, disabled: disabled, "aria-label": "Choose color", onChange: (event) => onChange(event.target.value) })] }));
 }
 export function TokenValueField(props) {
     const { property, domElement, semanticSlot, committedValue, resolvedValue = committedValue, activeTokenName: controlledTokenName = null, entries, suggestions = [], inputDataTest = "raw-input", allowedTokenNames, isColor = false, disabled = false, mixed = false, formatRawValue = (value) => value.trim(), onCommitRaw, onSelectToken, onUnlink, attributionTokens = [], leading, trailing, className, label, opacity, color, onCommitOpacity, atRules, chipVariant = "default", } = props;
@@ -164,6 +177,8 @@ export function TokenValueField(props) {
     const selectedFromPopover = useRef(false);
     const cancelOnBlur = useRef(false);
     const isNavigatingSuggestions = useRef(false);
+    const dragNudgeRef = useRef(null);
+    const [isDraggingNudge, setIsDraggingNudge] = useState(false);
     useEffect(() => {
         setRawValue(committedValue);
         setActiveTokenName(controlledTokenName);
@@ -301,6 +316,106 @@ export function TokenValueField(props) {
             inputRef.current?.blur();
         }
     }
+    const stopDragNudge = useCallback(() => {
+        const drag = dragNudgeRef.current;
+        if (!drag)
+            return;
+        dragNudgeRef.current = null;
+        drag.pointerLock?.stop();
+        releasePointerCapture(drag);
+        setIsDraggingNudge(false);
+    }, []);
+    useEffect(() => {
+        const stopOnWindowBlur = () => stopDragNudge();
+        window.addEventListener("blur", stopOnWindowBlur);
+        return () => {
+            window.removeEventListener("blur", stopOnWindowBlur);
+            stopDragNudge();
+        };
+    }, [stopDragNudge]);
+    function handleDragNudgePointerDown(event) {
+        if (event.button !== 0)
+            return;
+        if (disabled || !supportsDragNudge(property))
+            return;
+        if (!canNudgeCssValueByDrag(property, rawValue))
+            return;
+        stopDragNudge();
+        const handle = event.currentTarget;
+        const drag = {
+            commit: createChangeHistoryGroup(),
+            handle,
+            pointerId: event.pointerId,
+            lastClientX: event.clientX,
+            deltaX: 0,
+            startValue: rawValue,
+            lastValue: rawValue,
+            shiftActive: event.shiftKey,
+            shiftSnapPending: event.shiftKey,
+        };
+        dragNudgeRef.current = drag;
+        if (typeof handle.setPointerCapture === "function")
+            handle.setPointerCapture(event.pointerId);
+        if (event.pointerType === "mouse") {
+            drag.pointerLock = startDragPointerLock(handle, { x: event.clientX, y: event.clientY }, (mouseEvent) => {
+                updateDragNudge(mouseEvent, mouseEvent.movementX);
+            }, stopDragNudge);
+        }
+        setIsDraggingNudge(true);
+        event.preventDefault();
+        event.stopPropagation();
+    }
+    function handleDragNudgePointerMove(event) {
+        const drag = dragNudgeRef.current;
+        if (!drag || drag.pointerId !== event.pointerId)
+            return;
+        if (drag.pointerLock?.isLocked())
+            return;
+        const movementX = event.clientX - drag.lastClientX;
+        drag.lastClientX = event.clientX;
+        updateDragNudge(event, movementX);
+    }
+    function updateDragNudge(event, movementX) {
+        const drag = dragNudgeRef.current;
+        if (!drag)
+            return;
+        if (event.shiftKey !== drag.shiftActive) {
+            drag.shiftActive = event.shiftKey;
+            drag.startValue = drag.lastValue;
+            drag.deltaX = 0;
+            drag.shiftSnapPending = event.shiftKey;
+        }
+        drag.deltaX += movementX;
+        const next = nudgeCssValueByDrag(property, drag.startValue, drag.deltaX, drag.shiftActive, drag.shiftActive && drag.shiftSnapPending);
+        if (next === null || next === drag.lastValue)
+            return;
+        drag.lastValue = next;
+        if (drag.shiftActive && drag.shiftSnapPending) {
+            drag.startValue = next;
+            drag.deltaX = 0;
+            drag.shiftSnapPending = false;
+        }
+        event.preventDefault();
+        event.stopPropagation();
+        setRawValue(next);
+        setActiveTokenName(null);
+        drag.commit(() => onCommitRaw(next));
+    }
+    function handleDragNudgePointerEnd(event) {
+        if (dragNudgeRef.current?.pointerId !== event.pointerId)
+            return;
+        stopDragNudge();
+    }
+    function renderLeading() {
+        if (!leading)
+            return null;
+        const canDrag = !disabled
+            && supportsDragNudge(property)
+            && canNudgeCssValueByDrag(property, rawValue);
+        if (!canDrag)
+            return _jsx("span", { className: "token-field__leading", children: leading });
+        return (_jsx("span", { className: "token-field__leading token-field__leading--nudge", "data-test": "nudge-handle", "data-dragging": isDraggingNudge ? "true" : undefined, title: `Drag to adjust ${label ?? property}`, onPointerDown: handleDragNudgePointerDown, onPointerMove: handleDragNudgePointerMove, onPointerUp: handleDragNudgePointerEnd, onPointerCancel: handleDragNudgePointerEnd, onBlur: stopDragNudge, children: leading }));
+    }
     function commitOpacityValue(value = opacityValue) {
         if (!showOpacity || !onCommitOpacity)
             return;
@@ -343,12 +458,12 @@ export function TokenValueField(props) {
     if (activeToken) {
         const chipValue = chipVariant === "small" ? stripCssUnit(activeToken.value) : activeToken.name;
         const embedColorSwatch = isColor && chipVariant !== "small";
-        return (_jsxs("span", { className: `token-field${isColor ? " token-field--color" : ""}${embedColorSwatch ? " token-field--color-chip" : ""}${className ? ` ${className}` : ""}`, "data-test": "token-field", "data-property": property, "aria-label": label, title: label, children: [leading ? _jsx("span", { className: "token-field__leading", children: leading }) : null, 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: activeToken.name, 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: disabled, onSelect: (value) => {
+        return (_jsxs("span", { className: `token-field${isColor ? " token-field--color" : ""}${embedColorSwatch ? " token-field--color-chip" : ""}${className ? ` ${className}` : ""}`, "data-test": "token-field", "data-property": property, "aria-label": label, title: 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: activeToken.name, 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: disabled, onSelect: (value) => {
                                 handleSuggestionSelect(value);
                             } }), _jsx(TokenChip.Action, { children: _jsx(IconButton, { variant: "quiet", size: "compact", style: { borderRadius: "var(--radius-4)" }, label: "Replace with raw value", "data-test": "delink-btn", disabled: disabled, 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] }));
     }
     const showPopover = isFocused && (filteredTokens.length > 0 || availableSuggestions.length > 0);
-    return (_jsxs("span", { className: `token-field token-field--raw${isColor ? " token-field--color" : ""}${className ? ` ${className}` : ""}`, "data-test": "token-field", "data-property": property, "aria-label": label, title: label, children: [leading ? _jsx("span", { className: "token-field__leading", children: leading }) : null, colorControlEl, _jsx(PopoverListbox, { query: rawValue, value: null, open: showPopover, placeholder: property, inputRef: inputRef, inputAppearance: "embedded", inputDataTest: inputDataTest, inputOnFocus: () => {
+    return (_jsxs("span", { className: `token-field token-field--raw${isColor ? " token-field--color" : ""}${className ? ` ${className}` : ""}`, "data-test": "token-field", "data-property": property, "aria-label": label, title: label, children: [renderLeading(), colorControlEl, _jsx(PopoverListbox, { query: rawValue, value: null, open: showPopover, placeholder: property, inputRef: inputRef, inputAppearance: "embedded", inputDataTest: inputDataTest, inputOnFocus: () => {
                     setIsFocused(true);
                     if (mixed && rawValue.trim().toLowerCase() === "mixed")
                         setRawValue("");
@@ -417,7 +532,15 @@ export function TokenField(props) {
     const currentToken = activeTokenName
         ? entries.find((entry) => entry.name === activeTokenName) ?? null
         : null;
-    return (_jsx(TokenValueField, { property: property, domElement: el, semanticSlot: semanticSlot, committedValue: committedValue, resolvedValue: tokenRow?.propertyOpacity?.value ?? tokenRow?.resolvedValue ?? committedValue, activeTokenName: activeTokenName, attributionTokens: attributionTokens
+    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.
+        const style = el.ownerDocument.createElement("span").style;
+        style.background = resolvedValue;
+        resolvedValue = style.backgroundColor || resolvedValue;
+    }
+    return (_jsx(TokenValueField, { property: property, domElement: el, semanticSlot: semanticSlot, committedValue: committedValue, resolvedValue: resolvedValue, activeTokenName: activeTokenName, attributionTokens: attributionTokens
             ?? (selectedProperty?.token.kind === "mixed" ? ["Mixed tokens"] : undefined)
             ?? (expression
                 ? tokenRow?.tokens?.filter((token) => token.name !== tokenRow.opacity?.tokenName).map((token) => token.name)

package/dist/inspector/tokens/TokensPanel.js

@@ -3,6 +3,7 @@ import { useMemo, useState } from "react";
 import { isTokenChange, useChanges } from "../changes/changesLog.js";
 import { TextInput } from "../ui/TextInput.js";
 import { ControlSurface } from "../ui/ControlSurface.js";
+import { Disclosure } from "../ui/Disclosure.js";
 import { TokenValueField } from "./TokenField.js";
 import { TOKEN_GROUP_LABELS, TOKEN_GROUP_ORDER, aliasName, compatibleTokenNames, contextLabel, filterTokenRows, } from "./catalog.js";
 import { setGlobalTokenValue } from "./tokenEdits.js";
@@ -43,5 +44,5 @@ function TokenCatalogItem({ row, rows, entries, }) {
     const allowed = compatibleTokenNames(effectiveRow, effectiveRows);
     const variants = row.definition.declarations.filter((declaration) => declaration !== row.activeDeclaration);
     const tokenName = row.definition.name || row.definition.cssName;
-    return (_jsxs("article", { className: "token-row", "data-test": "global-token-row", "data-token-name": row.definition.cssName, "data-active": row.activeDeclaration ? "true" : "false", children: [_jsxs("div", { className: "token-row__inline", children: [_jsx(TokenLabel, { as: "code", className: "token-row__name", title: tokenName, children: tokenName }), row.activeDeclaration ? (_jsx(ControlSurface, { children: _jsx(TokenValueField, { property: row.definition.cssName, committedValue: committedValue, resolvedValue: row.resolvedValue || committedValue, activeTokenName: activeAlias, entries: entries, allowedTokenNames: allowed, isColor: row.group === "color", onCommitRaw: (value) => setGlobalTokenValue(row, value), onSelectToken: (token) => { setGlobalTokenValue(row, `var(${token.name})`); }, onUnlink: (value) => setGlobalTokenValue(row, value) }) })) : (_jsx(TextInput, { disabled: true, value: "Inactive in current theme", "aria-label": `${row.definition.cssName} inactive` }))] }), variants.length > 0 ? (_jsxs("details", { className: "token-variants", "data-test": "token-variants", children: [_jsxs("summary", { children: ["Variants (", variants.length, ")"] }), _jsx("div", { className: "token-variants__list", children: variants.map((declaration) => (_jsxs("div", { className: "token-variant", children: [_jsx("span", { className: "token-variant__context", children: contextLabel(declaration.context) }), _jsx("code", { children: declaration.value }), _jsx("span", { children: declaration.source })] }, `${declaration.source}-${contextLabel(declaration.context)}`))) })] })) : null] }));
+    return (_jsxs("article", { className: "token-row", "data-test": "global-token-row", "data-token-name": row.definition.cssName, "data-active": row.activeDeclaration ? "true" : "false", children: [_jsxs("div", { className: "token-row__inline", children: [_jsx(TokenLabel, { as: "code", className: "token-row__name", title: tokenName, children: tokenName }), row.activeDeclaration ? (_jsx(ControlSurface, { children: _jsx(TokenValueField, { property: row.definition.cssName, committedValue: committedValue, resolvedValue: row.resolvedValue || committedValue, activeTokenName: activeAlias, entries: entries, allowedTokenNames: allowed, isColor: row.group === "color", onCommitRaw: (value) => setGlobalTokenValue(row, value), onSelectToken: (token) => { setGlobalTokenValue(row, `var(${token.name})`); }, onUnlink: (value) => setGlobalTokenValue(row, value) }) })) : (_jsx(TextInput, { disabled: true, value: "Inactive in current theme", "aria-label": `${row.definition.cssName} inactive` }))] }), variants.length > 0 ? (_jsx(Disclosure, { className: "token-variants", "data-test": "token-variants", title: `Variants (${variants.length})`, panelClassName: "token-variants__list", children: variants.map((declaration) => (_jsxs("div", { className: "token-variant", children: [_jsx("span", { className: "token-variant__context", children: contextLabel(declaration.context) }), _jsx("code", { children: declaration.value }), _jsx("span", { children: declaration.source })] }, `${declaration.source}-${contextLabel(declaration.context)}`))) })) : null] }));
 }

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

@@ -0,0 +1,8 @@
+/** Keeps mouse drags relative, including when the handle is inside a shadow root. */
+export declare function startDragPointerLock(handle: HTMLElement, point: {
+    x: number;
+    y: number;
+}, onMove: (event: MouseEvent) => void, onEnd: () => void): {
+    isLocked: () => boolean;
+    stop: () => void;
+};

package/dist/inspector/tokens/dragPointerLock.js

@@ -0,0 +1,70 @@
+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();
+    const isLocked = () => root.pointerLockElement === handle;
+    let stopped = false;
+    let pending = true;
+    let acquired = false;
+    let removeCursor;
+    function removeLockListeners() {
+        doc.removeEventListener("pointerlockchange", onLockChange);
+        doc.removeEventListener("pointerlockerror", onLockError);
+    }
+    function onLockChange() {
+        if (isLocked()) {
+            pending = false;
+            acquired = true;
+            if (stopped) {
+                doc.exitPointerLock();
+                removeLockListeners();
+            }
+            else if (!removeCursor) {
+                removeCursor = showLockedDragCursor(doc, point);
+            }
+        }
+        else if (acquired) {
+            onEnd();
+        }
+    }
+    function onLockError() {
+        pending = false;
+        removeLockListeners();
+    }
+    function onMouseMove(event) {
+        if (!stopped && isLocked())
+            onMove(event);
+    }
+    function onMouseUp(event) {
+        if (event.button === 0)
+            onEnd();
+    }
+    doc.addEventListener("mousemove", onMouseMove);
+    doc.addEventListener("mouseup", onMouseUp);
+    doc.addEventListener("pointerlockchange", onLockChange);
+    doc.addEventListener("pointerlockerror", onLockError);
+    try {
+        // Older implementations return void. Rejections retain pointer-capture dragging.
+        const request = handle.requestPointerLock();
+        if (request)
+            void request.catch(onLockError);
+    }
+    catch {
+        onLockError();
+    }
+    return {
+        isLocked,
+        stop() {
+            stopped = true;
+            removeCursor?.();
+            doc.removeEventListener("mousemove", onMouseMove);
+            doc.removeEventListener("mouseup", onMouseUp);
+            if (isLocked())
+                doc.exitPointerLock();
+            // A request can finish after mouse-up or unmount. Release that late lock too.
+            if (!pending)
+                removeLockListeners();
+        },
+    };
+}

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

@@ -22,6 +22,8 @@ export declare function swapTokens(target: EditTarget, changes: readonly TokenSw
 export interface StyleDeclaration {
     property: string;
     value: string;
+    /** Optional baseline captured before a transient preview changed the DOM. */
+    oldRawValue?: string;
     metadata?: StyleEditMetadata;
 }
 export interface ElementStyleEdit {

package/dist/inspector/tokens/editActions.js

@@ -135,7 +135,7 @@ export function setStyles(target, declarations, metadata) {
 export function setElementStyles(edits) {
     return commitElementStyles(edits);
 }
-function buildStyleRecord(el, scopePlan, { property, value, metadata }) {
+function buildStyleRecord(el, scopePlan, { property, value, oldRawValue, metadata }) {
     const cid = el.getAttribute("data-cid") ?? "";
     const { selector, state } = stateFields(el);
     if (!selector)
@@ -152,7 +152,7 @@ function buildStyleRecord(el, scopePlan, { property, value, metadata }) {
         oldToken: null,
         newToken: null,
         rawValue: value,
-        oldRawValue: getStateStyleValue(el, property) || undefined,
+        oldRawValue: (oldRawValue ?? getStateStyleValue(el, property)) || undefined,
         source: { file: source.file, line: source.line, component: cid },
         runtimeEvidence: source.runtimeEvidence,
         state,

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

@@ -15,9 +15,9 @@ export declare function subscribeDocumentRevision(doc: Document, cb: (revisions:
  * the element revision. Registration is idempotent.
  */
 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;
-/** Keeps one document's CSSOM observer alive for a browser inspection owner. */
 export declare function retainDocumentResolution(doc: Document): () => void;
 export declare function documentRevisions(doc: Document): DocumentRevisions;
 /** Invalidates CSSOM-derived snapshots after programmatic stylesheet edits. */

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

@@ -39,6 +39,13 @@ export function subscribeDocumentRevision(doc, cb) {
 export function registerResolutionElement(el) {
     registeredElements.add(el);
 }
+export function registerResolutionLineage(element) {
+    let current = element;
+    while (current) {
+        registerResolutionElement(current);
+        current = current.parentElement;
+    }
+}
 /** Releases the observer, listener, and cached state owned by one document. */
 export function disposeDocumentResolution(doc) {
     const session = documentResolutionSessions.get(doc);
@@ -54,9 +61,8 @@ export function disposeDocumentResolution(doc) {
     }
     documentResolutionReferences.delete(doc);
     // Keep revision counters monotonic per Document. Resetting them to (0,0)
-    // resurrects stale revision-keyed caches in tokens/resolution.ts
-    // (stableTokenCache, stateResolutionSnapshots, tokenEntriesCache,
-    // concreteElementMatchCaches, sourceSiteMatchCaches): an entry written at
+    // resurrects stale revision-keyed caches in property resolution, token
+    // availability, and rule matching: an entry written at
     // (0,0) before disposal matches immediately after disposal at (0,0), even
     // though the CSSOM changed while no observer was attached. Bump instead so
     // every pre-disposal cache entry misses, then let the next
@@ -73,7 +79,6 @@ export function disposeDocumentResolution(doc) {
     documentRevisionListeners.get(doc)?.clear();
     documentRevisionListeners.delete(doc);
 }
-/** Keeps one document's CSSOM observer alive for a browser inspection owner. */
 export function retainDocumentResolution(doc) {
     documentRevisions(doc);
     const session = documentResolutionSessions.get(doc);
@@ -113,7 +118,6 @@ function changesStylesheet(record) {
         || Array.from(record.addedNodes).some(isStylesheetNode)
         || Array.from(record.removedNodes).some(isStylesheetNode);
 }
-/** A node that is, or lives inside, one of the tool's own probe elements. */
 function isProbeNode(node) {
     let current = node;
     while (current && current.nodeType !== current.DOCUMENT_NODE) {

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

@@ -0,0 +1,40 @@
+import type { MatchedRule } from "../../../css/model/index.js";
+import { type InteractionState } from "../../shell/styleState.js";
+export interface ElementMatch {
+    rule: MatchedRule;
+    /** The selector actually used for matching (state-stripped for interaction states). */
+    selectorText: string;
+    branch: string;
+    specificity: number;
+}
+/**
+ * The selector set used by a resolution. Interaction states strip or drop
+ * pseudo-class rules, `live` keeps the raw CSSOM rules (used by
+ * `getResolvedProperties`), and `stable` drops transient rules (used by
+ * `getResolvedPropertiesStable`).
+ */
+type CascadeTransform = InteractionState | "live" | "stable";
+/** Test-only cache reset. */
+export declare function resetSourceSiteMatchCache(): void;
+/** Test-only cache size. */
+export declare function sourceSiteMatchCacheSize(): number;
+export declare function matchRuleForElement(el: HTMLElement, entry: {
+    rule: MatchedRule;
+    selectorText: string;
+}): ElementMatch | null;
+/**
+ * Shares dynamic matches across cache validation and ancestry within one sweep.
+ * Element-relative conditions, such as container queries, remain the resolver's
+ * responsibility; these results describe selector matches and stylesheet activity.
+ */
+export interface RuleMatcher {
+    dynamicMatchKey(element: HTMLElement): string;
+    matchesForElement(element: HTMLElement): {
+        matched: ElementMatch[];
+        allMatched: ElementMatch[];
+    };
+}
+/** Creates a matcher for one CSSOM snapshot. */
+export declare function createRuleMatcher(rules: MatchedRule[], transform: CascadeTransform): RuleMatcher;
+export declare function getAvailableInteractionStates(el: HTMLElement): InteractionState[];
+export {};