nudge-ui 0.2.4 → 0.2.6

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

@@ -1,6 +1,14 @@
 import { computeSpecificityCore } from "./selectorSemantics.js";
+import { resolveNestedSelector } from "./nestedSelectors.js";
+import { adoptedStylesheetKey, STATE_PREVIEW_SHEET_ID } from "../../runtime/ownedStylesheets.js";
+import { INTERACTION_CURSOR_PROPERTY } from "../../ui/customCursors.js";
 const revisionRecords = new WeakMap();
 const ruleSnapshots = new WeakMap();
+/** Bumped when a page-owned stylesheet's walk could change without replacing its CSSStyleSheet object; inspector-owned writes leave it alone. */
+const pageSheetEpochs = new WeakMap();
+function bumpPageSheetEpoch(doc) {
+    pageSheetEpochs.set(doc, (pageSheetEpochs.get(doc) ?? 0) + 1);
+}
 const documentResolutionSessions = new WeakMap();
 const documentResolutionReferences = new WeakMap();
 const registeredElements = new WeakSet();
@@ -12,10 +20,6 @@ function notifyDocumentRevision(doc) {
     const revisions = documentRevisions(doc);
     documentRevisionListeners.get(doc)?.forEach((cb) => cb({ ...revisions }));
 }
-/**
- * Subscribes to cascade revisions for one document. This is the narrow
- * document-scoped seam used by the browser inspection Module.
- */
 export function subscribeDocumentRevision(doc, cb) {
     let listeners = documentRevisionListeners.get(doc);
     if (!listeners) {
@@ -30,12 +34,7 @@ export function subscribeDocumentRevision(doc, cb) {
         }
     };
 }
-/**
- * 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 function registerResolutionElement(el) {
     registeredElements.add(el);
 }
@@ -46,7 +45,6 @@ export function registerResolutionLineage(element) {
         current = current.parentElement;
     }
 }
-/** Releases the observer, listener, and cached state owned by one document. */
 export function disposeDocumentResolution(doc) {
     const session = documentResolutionSessions.get(doc);
     if (session) {
@@ -60,14 +58,7 @@ export function disposeDocumentResolution(doc) {
         documentResolutionSessions.delete(doc);
     }
     documentResolutionReferences.delete(doc);
-    // Keep revision counters monotonic per Document. Resetting them to (0,0)
-    // 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
-    // documentRevisions() observe from the bumped baseline. Only bump when a
-    // session was actually torn down so repeated disposes stay idempotent.
+    // Counters stay monotonic: resetting to (0,0) would resurrect stale revision-keyed caches written before disposal.
     if (session) {
         const record = revisionRecords.get(doc);
         if (record) {
@@ -76,6 +67,7 @@ export function disposeDocumentResolution(doc) {
         }
     }
     ruleSnapshots.delete(doc);
+    bumpPageSheetEpoch(doc);
     documentRevisionListeners.get(doc)?.clear();
     documentRevisionListeners.delete(doc);
 }
@@ -132,19 +124,35 @@ const MANAGED_SHEET_ID = "nudge-ui-styles";
 function isManagedStylesheetNode(node) {
     return isStylesheetNode(node) && node.id === MANAGED_SHEET_ID;
 }
-/**
- * Records that cannot affect cascade outcomes are skipped: mutations made by
- * the tool's own probes (attribution, container-query, and value), attribute
- * churn on elements outside the resolution registry, and the container-query
- * marker attribute set on registered elements. Managed stylesheet text is
- * intentionally observed because it is a real cascade input.
- */
+function isPageStylesheetNode(node) {
+    return isStylesheetNode(node) && !isManagedStylesheetNode(node);
+}
+function changesPageStylesheet(record) {
+    if (record.type === "attributes")
+        return isPageStylesheetNode(record.target);
+    if (record.type === "characterData")
+        return isPageStylesheetNode(record.target.parentElement);
+    return isPageStylesheetNode(record.target)
+        || Array.from(record.addedNodes).some(isPageStylesheetNode)
+        || Array.from(record.removedNodes).some(isPageStylesheetNode);
+}
+// The renderer rewrites these on hover and spacing drags; bumping the element revision would re-resolve the cascade per pointer move.
+const RENDERER_INLINE_CURSOR_PROPERTIES = ["cursor", INTERACTION_CURSOR_PROPERTY];
+function styleTextWithoutCursor(doc, text) {
+    const scratch = doc.createElement("div");
+    scratch.style.cssText = text ?? "";
+    for (const property of RENDERER_INLINE_CURSOR_PROPERTIES)
+        scratch.style.removeProperty(property);
+    return scratch.style.cssText;
+}
+function isCursorOnlyStyleChange(target, oldValue) {
+    const doc = target.ownerDocument;
+    return styleTextWithoutCursor(doc, oldValue) === styleTextWithoutCursor(doc, target.getAttribute("style"));
+}
 function isProbeMutation(record) {
     if (record.type === "attributes") {
         const target = record.target;
-        // Stylesheet attributes change which rules are present or active even when
-        // the stylesheet element has never been registered as a resolution target.
-        // Handle them before the generic unregistered-element fast path.
+        // Stylesheet attributes change the rules even for unregistered elements, so check them before the registry fast path.
         if (isStylesheetNode(target)) {
             const name = record.attributeName ?? "";
             if (isManagedStylesheetNode(target))
@@ -152,23 +160,21 @@ function isProbeMutation(record) {
             return name.startsWith("data-nudge-ui");
         }
         const name = record.attributeName ?? "";
-        // Renderer-owned IDs are lookup metadata, not authored cascade inputs.
-        // Ignore them before the registry check so hovering an unregistered canvas
-        // node does not invalidate the selected element's resolution snapshot.
+        // data-renderer-id is lookup metadata, not a cascade input; ignore it before the registry check.
         if (name === "data-renderer-id")
             return true;
         if (!registeredElements.has(target))
             return true;
         return name.startsWith("data-nudge-ui")
-            || CONTAINER_PROBE_MARKER.test(name);
+            || CONTAINER_PROBE_MARKER.test(name)
+            || (name === "style" && isCursorOnlyStyleChange(target, record.oldValue));
     }
     if (record.type === "characterData") {
         return isProbeNode(record.target) && !isManagedStylesheetNode(record.target.parentElement);
     }
     if (isProbeNode(record.target) && !isManagedStylesheetNode(record.target))
         return true;
-    // Removed nodes are already disconnected, so their ancestor chain is gone;
-    // check the record's target subtree and the nodes themselves instead.
+    // Removed nodes are already disconnected, so check their own attributes instead of an ancestor chain.
     const nodes = [...record.addedNodes, ...record.removedNodes];
     if (nodes.some(isManagedStylesheetNode))
         return false;
@@ -180,10 +186,7 @@ export function documentRevisions(doc) {
         record = { element: 0, stylesheet: 0 };
         revisionRecords.set(doc, record);
     }
-    // A disposed document keeps its monotonic record (see
-    // disposeDocumentResolution) but loses its observer session. Recreate the
-    // session so later mutations are observed from the bumped baseline instead
-    // of silently freezing the counters.
+    // A disposed document keeps its record but loses its observer; recreate the session so mutations are not silently unobserved.
     if (documentResolutionSessions.get(doc))
         return record;
     const session = {
@@ -193,9 +196,7 @@ export function documentRevisions(doc) {
         resizeListener: null,
     };
     documentResolutionSessions.set(doc, session);
-    // MutationObserver is a global constructor of the document realm, but it is
-    // not a property in every TypeScript Window declaration used by consumers.
-    // Keep the cast local so the observer and its callback remain document-local.
+    // Not every TypeScript Window declaration types MutationObserver; the local cast keeps the observer document-local.
     const viewWithObserver = session.view;
     const Observer = viewWithObserver?.MutationObserver
         ?? (typeof MutationObserver !== "undefined" ? MutationObserver : undefined);
@@ -210,11 +211,14 @@ export function documentRevisions(doc) {
             record.element++;
             if (relevant.some(changesStylesheet))
                 record.stylesheet++;
+            if (relevant.some(changesPageStylesheet))
+                bumpPageSheetEpoch(doc);
             notifyDocumentRevision(doc);
         });
         session.observer = observer;
         observer.observe(root, {
             attributes: true,
+            attributeOldValue: true,
             childList: true,
             characterData: true,
             subtree: true,
@@ -224,6 +228,7 @@ export function documentRevisions(doc) {
                 return;
             record.element++;
             record.stylesheet++;
+            bumpPageSheetEpoch(doc);
             notifyDocumentRevision(doc);
         };
         session.resizeListener = resizeListener;
@@ -234,8 +239,16 @@ export function documentRevisions(doc) {
 function stylesheetRevision(doc) {
     return documentRevisions(doc).stylesheet;
 }
-/** Invalidates CSSOM-derived snapshots after programmatic stylesheet edits. */
 export function invalidateStyleResolutionCache(doc = document) {
+    const record = documentRevisions(doc);
+    record.element++;
+    record.stylesheet++;
+    ruleSnapshots.delete(doc);
+    bumpPageSheetEpoch(doc);
+    notifyDocumentRevision(doc);
+}
+/** Inspector-only invalidation; page sheets are re-read only if their objects changed. */
+export function invalidateOwnedStyleResolution(doc = document) {
     const record = documentRevisions(doc);
     record.element++;
     record.stylesheet++;
@@ -249,13 +262,7 @@ function isStyleRuleInDocument(rule, doc) {
     return rule.type === (doc.defaultView?.CSSRule.STYLE_RULE ?? 1)
         && "selectorText" in rule && "style" in rule;
 }
-/**
- * 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.
- */
+/** Prefers the serialized declaration block; enumeration is a fallback because a shorthand can enumerate empty longhands. */
 export function declarationsFromCssom(style) {
     const declarations = parseCssomDeclarations(style.cssText);
     const seen = new Set(declarations.map((declaration) => declaration.property));
@@ -378,13 +385,13 @@ function contextForRule(cssText, record) {
         return params ? { kind: "media", params } : null;
     }
     if (/^\s*@container\b/i.test(cssText)) {
-        // CSSContainerRule exposes `conditionText` and `containerName` in modern
-        // engines. Fall back to the serialised prelude so named, style, and newer
-        // container queries remain presentable without hand-parsing their grammar.
+        // conditionText includes the container name in some engines and omits it in others; prepend only when missing.
         const containerName = record.containerName?.trim();
-        const fromInterfaces = [containerName && containerName !== "none" ? containerName : undefined, record.conditionText?.trim()]
-            .filter((part) => Boolean(part))
-            .join(" ");
+        const condition = record.conditionText?.trim() ?? "";
+        const hasName = Boolean(containerName) && containerName !== "none";
+        const conditionNamed = hasName && condition.startsWith(containerName)
+            && /^(?:$|[\s(])/.test(condition.slice(containerName.length));
+        const fromInterfaces = hasName && !conditionNamed ? `${containerName} ${condition}`.trim() : condition;
         const params = fromInterfaces || atRuleParams(cssText, "container");
         return params ? { kind: "container", params } : null;
     }
@@ -397,83 +404,84 @@ function contextForRule(cssText, record) {
 function isNestedDeclarations(rule, doc) {
     if (isStyleRuleInDocument(rule, doc) || !("style" in rule) || "selectorText" in rule)
         return false;
-    // Chromium represents declarations nested in a style rule's @supports /
-    // @media block as CSSNestedDeclarations. Its public type is not yet in
-    // lib.dom, so identify its declaration-only CSSOM shape conservatively.
+    // Chromium's CSSNestedDeclarations is not yet in lib.dom; identify its declaration-only shape conservatively.
     return !/^\s*@/.test(rule.cssText ?? "") && typeof rule.style === "object";
 }
-export function collectRules(doc) {
-    const revision = stylesheetRevision(doc);
-    const cached = ruleSnapshots.get(doc);
-    if (cached?.revision === revision) {
-        return {
-            rules: cached.rules,
-            layerOrder: cached.layerOrder,
-            inaccessible: cached.inaccessible,
-        };
+/** Page-owned walks survive inspector edits; walkStillValid() defines when one must be re-read. */
+const pageSheetWalks = new WeakMap();
+function walkStillValid(walk, rules, epoch, view) {
+    if (walk.epoch !== epoch || walk.ruleCount !== rules.length)
+        return false;
+    for (const [condition, matches] of walk.media) {
+        if ((view ? view.matchMedia(condition).matches : false) !== matches)
+            return false;
     }
-    const out = [];
-    const layerOrder = new Map();
-    let inaccessible = false;
-    let sourceOrder = 0;
-    const registerLayer = (name) => {
-        const normalized = name.trim();
-        if (!normalized)
-            return undefined;
-        if (!layerOrder.has(normalized))
-            layerOrder.set(normalized, layerOrder.size);
-        return normalized;
-    };
+    return true;
+}
+function walkSheet(rules, doc) {
+    const events = [];
+    const media = new Map();
+    const view = doc.defaultView;
     const nestedLayerName = (parent, child) => {
         const normalized = child.trim();
         if (!normalized)
             return parent;
-        return registerLayer(parent ? `${parent}.${normalized}` : normalized);
+        const name = parent ? `${parent}.${normalized}` : normalized;
+        events.push({ layer: name });
+        return name;
     };
-    const walkRules = (rules, active = true, layer, atRules = [], inheritedSelector, source) => {
+    const mediaMatches = (condition) => {
+        let matches = media.get(condition);
+        if (matches === undefined) {
+            matches = view ? view.matchMedia(condition).matches : false;
+            media.set(condition, matches);
+        }
+        return matches;
+    };
+    const walkRules = (rules, active = true, layer, atRules = [], inheritedSelector) => {
         for (const rule of Array.from(rules)) {
-            const serializedRule = rule.cssText ?? "";
-            const layerStatement = /^\s*@layer\s+([^;{]+)\s*;/i.exec(serializedRule);
-            if (layerStatement && !("cssRules" in rule)) {
-                layerStatement[1].split(",").forEach((name) => nestedLayerName(layer, name));
-                continue;
-            }
             if (isStyleRuleInDocument(rule, doc)) {
                 try {
-                    out.push({
-                        selectorText: rule.selectorText,
-                        specificity: computeSpecificityCore(rule.selectorText),
-                        declarations: declarationsFromCssom(rule.style),
-                        source,
-                        sourceOrder: sourceOrder++,
-                        active,
-                        layer,
-                        layerOrder: layer ? layerOrder.get(layer) : undefined,
-                        atRules: atRules.length > 0 ? atRules : undefined,
-                    });
+                    const selectorText = inheritedSelector
+                        ? resolveNestedSelector(rule.selectorText, inheritedSelector)
+                        : rule.selectorText;
+                    events.push({ rule: {
+                            selectorText,
+                            specificity: computeSpecificityCore(selectorText),
+                            declarations: declarationsFromCssom(rule.style),
+                            active,
+                            layer,
+                            atRules: atRules.length > 0 ? atRules : undefined,
+                        } });
                     const nested = rule.cssRules;
                     if (nested?.length)
-                        walkRules(nested, active, layer, atRules, rule.selectorText, source);
+                        walkRules(nested, active, layer, atRules, selectorText);
                 }
                 catch {
                     continue;
                 }
+                continue;
             }
-            else if (isNestedDeclarations(rule, doc)) {
+            // Serializing a style rule's declaration block is costly, so only other
+            // rule kinds are serialized to recognise their at-rule.
+            const serializedRule = rule.cssText ?? "";
+            const layerStatement = /^\s*@layer\s+([^;{]+)\s*;/i.exec(serializedRule);
+            if (layerStatement && !("cssRules" in rule)) {
+                layerStatement[1].split(",").forEach((name) => nestedLayerName(layer, name));
+                continue;
+            }
+            if (isNestedDeclarations(rule, doc)) {
                 if (!inheritedSelector)
                     continue;
                 try {
-                    out.push({
-                        selectorText: inheritedSelector,
-                        specificity: computeSpecificityCore(inheritedSelector),
-                        declarations: declarationsFromCssom(rule.style),
-                        source,
-                        sourceOrder: sourceOrder++,
-                        active,
-                        layer,
-                        layerOrder: layer ? layerOrder.get(layer) : undefined,
-                        atRules: atRules.length > 0 ? atRules : undefined,
-                    });
+                    events.push({ rule: {
+                            selectorText: inheritedSelector,
+                            specificity: computeSpecificityCore(inheritedSelector),
+                            declarations: declarationsFromCssom(rule.style),
+                            active,
+                            layer,
+                            atRules: atRules.length > 0 ? atRules : undefined,
+                        } });
                 }
                 catch {
                     continue;
@@ -483,24 +491,20 @@ export function collectRules(doc) {
                 try {
                     const record = rule;
                     let childActive = active;
-                    const cssText = rule.cssText ?? "";
+                    const cssText = serializedRule;
                     const isMedia = /^\s*@media\b/i.test(cssText);
                     const isSupports = /^\s*@supports\b/i.test(cssText);
                     const isLayer = /^\s*@layer\b/i.test(cssText);
-                    const view = doc.defaultView;
                     if (isMedia && record.conditionText)
-                        childActive = active && (view ? view.matchMedia(record.conditionText).matches : false);
+                        childActive = active && mediaMatches(record.conditionText);
                     else if (isSupports && record.conditionText)
-                        childActive = active && (doc.defaultView?.CSS?.supports(record.conditionText) ?? false);
-                    // A container query is evaluated relative to the styled element, so
-                    // it cannot be answered while walking a document-level stylesheet.
-                    // Resolution evaluates its retained context against the selected
-                    // element using a harmless browser probe.
+                        childActive = active && (view?.CSS?.supports(record.conditionText) ?? false);
+                    // A container query depends on the styled element, so the walk only retains it; resolution evaluates it against the selection.
                     const context = contextForRule(cssText, record);
                     const childLayer = isLayer
                         ? nestedLayerName(layer, record.name ?? cssText.slice(6, cssText.indexOf("{")).trim())
                         : layer;
-                    walkRules(record.cssRules, childActive, childLayer, context ? [...atRules, context] : atRules, inheritedSelector, source);
+                    walkRules(record.cssRules, childActive, childLayer, context ? [...atRules, context] : atRules, inheritedSelector);
                 }
                 catch {
                     continue;
@@ -508,21 +512,81 @@ export function collectRules(doc) {
             }
         }
     };
+    walkRules(rules);
+    return { events, media };
+}
+export function collectRules(doc) {
+    const revision = stylesheetRevision(doc);
+    const cached = ruleSnapshots.get(doc);
+    if (cached?.revision === revision) {
+        return {
+            rules: cached.rules,
+            layerOrder: cached.layerOrder,
+            inaccessible: cached.inaccessible,
+        };
+    }
+    const out = [];
+    const layerOrder = new Map();
+    let inaccessible = false;
+    const epoch = pageSheetEpochs.get(doc) ?? 0;
+    const append = (events, source) => {
+        for (const event of events) {
+            if ("layer" in event) {
+                if (!layerOrder.has(event.layer))
+                    layerOrder.set(event.layer, layerOrder.size);
+                continue;
+            }
+            const { rule } = event;
+            out.push({
+                selectorText: rule.selectorText,
+                specificity: rule.specificity,
+                declarations: rule.declarations,
+                source,
+                sourceOrder: out.length,
+                active: rule.active,
+                layer: rule.layer,
+                layerOrder: rule.layer ? layerOrder.get(rule.layer) : undefined,
+                atRules: rule.atRules,
+            });
+        }
+    };
+    const sheetEvents = (sheet, pageOwned) => {
+        const rules = sheet.cssRules;
+        if (!pageOwned)
+            return walkSheet(rules, doc).events;
+        const previous = pageSheetWalks.get(sheet);
+        if (previous && walkStillValid(previous, rules, epoch, doc.defaultView))
+            return previous.events;
+        const walk = { epoch, ruleCount: rules.length, ...walkSheet(rules, doc) };
+        pageSheetWalks.set(sheet, walk);
+        return walk.events;
+    };
     const stylesheetNodes = Array.from(doc.querySelectorAll('style, link[rel~="stylesheet"]'));
     for (const [index, sheet] of Array.from(doc.styleSheets).entries()) {
         try {
             // jsdom does not currently expose CSSStyleSheet.ownerNode; the document
             // stylesheet list and stylesheet element list retain the same order.
             const owner = sheet.ownerNode ?? stylesheetNodes[index] ?? null;
+            if (owner?.id === STATE_PREVIEW_SHEET_ID)
+                continue;
             const source = owner?.dataset?.viteDevId
                 ?? sheet.href
                 ?? (owner?.id ? `#${owner.id}` : `stylesheet:${index + 1}`);
-            walkRules(sheet.cssRules, true, undefined, [], undefined, source);
+            const inspectorOwned = typeof owner?.hasAttribute === "function" && owner.hasAttribute("data-nudge-ui");
+            append(sheetEvents(sheet, !inspectorOwned), source);
         }
         catch {
             inaccessible = true;
         }
     }
+    // Adopted sheets cascade after document stylesheets. Under a strict
+    // style-src policy they also hold the inspector's own managed rules.
+    for (const [index, sheet] of Array.from(doc.adoptedStyleSheets ?? []).entries()) {
+        const key = adoptedStylesheetKey(doc, sheet);
+        if (key === STATE_PREVIEW_SHEET_ID)
+            continue;
+        append(sheetEvents(sheet, key === null), key ? `#${key}` : `adopted:${index + 1}`);
+    }
     const snapshot = { revision, rules: out, layerOrder, inaccessible };
     ruleSnapshots.set(doc, snapshot);
     return snapshot;

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

@@ -0,0 +1,2 @@
+/** `:is(parent)` keeps nesting's maximum parent-list specificity without expanding every combination. */
+export declare function resolveNestedSelector(selector: string, parent: string): string;

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

@@ -0,0 +1,63 @@
+/** `:is(parent)` keeps nesting's maximum parent-list specificity without expanding every combination. */
+export function resolveNestedSelector(selector, parent) {
+    const subject = `:is(${parent})`;
+    const branches = [];
+    let branch = "";
+    let hasNesting = false;
+    let parentheses = 0;
+    let brackets = 0;
+    let quote = null;
+    const finishBranch = () => {
+        branches.push(hasNesting ? branch.trim() : `${subject} ${branch.trim()}`);
+        branch = "";
+        hasNesting = false;
+    };
+    for (let index = 0; index < selector.length; index++) {
+        const character = selector[index];
+        if (character === "\\") {
+            branch += character + (selector[++index] ?? "");
+            continue;
+        }
+        if (quote) {
+            branch += character;
+            if (character === quote)
+                quote = null;
+            continue;
+        }
+        if (character === '"' || character === "'") {
+            quote = character;
+        }
+        else if (character === "/" && selector[index + 1] === "*") {
+            const end = selector.indexOf("*/", index + 2);
+            if (end < 0)
+                return "";
+            branch += selector.slice(index, end + 2);
+            index = end + 1;
+            continue;
+        }
+        else if (character === "[") {
+            brackets++;
+        }
+        else if (character === "]") {
+            brackets--;
+        }
+        else if (brackets === 0) {
+            if (character === "(")
+                parentheses++;
+            else if (character === ")")
+                parentheses--;
+            else if (character === "&") {
+                branch += subject;
+                hasNesting = true;
+                continue;
+            }
+            else if (character === "," && parentheses === 0) {
+                finishBranch();
+                continue;
+            }
+        }
+        branch += character;
+    }
+    finishBranch();
+    return branches.join(", ");
+}

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

@@ -7,26 +7,15 @@ export interface ElementMatch {
     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`).
- */
+/** Resolution vocabulary: interaction states strip matching pseudo-classes, `stable` drops transient rules, `live` keeps raw CSSOM rules. */
 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.
- */
+/** Element-relative conditions (container queries) stay the resolver's job; these describe selector matches and stylesheet activity. */
 export interface RuleMatcher {
     dynamicMatchKey(element: HTMLElement): string;
     matchesForElement(element: HTMLElement): {
@@ -34,7 +23,8 @@ export interface RuleMatcher {
         allMatched: ElementMatch[];
     };
 }
-/** Creates a matcher for one CSSOM snapshot. */
 export declare function createRuleMatcher(rules: MatchedRule[], transform: CascadeTransform): RuleMatcher;
+/** Warms transforms, buckets, and class indexes so an idle frame pays their parsing cost. */
+export declare function prewarmRuleMatching(rules: MatchedRule[]): void;
 export declare function getAvailableInteractionStates(el: HTMLElement): InteractionState[];
 export {};