@master/css-runtime 2.0.0-rc.69 → 2.0.0-rc.70

package/dist/index.mjs

@@ -1,8 +1,10 @@
-import { Layer, withSyntaxLayer, MasterCSS, config, VariableRule, AnimationRule } from '@master/css';
+import { Layer, AnimationRule, VariableRule, compareRulePriority, ThemeLayer, MasterCSS } from '@master/css-engine';
+import { MASTER_CSS_HYDRATION_MANIFEST_ATTR, MASTER_CSS_HYDRATION_MANIFEST_SCRIPT_ID } from '@master/css-schema/hydration-manifest';
+import { MASTER_CSS_RUNTIME_STYLE_ID } from '@master/css-schema/runtime-style';
 import { installHook } from '@master/css-devtools-hook';
 
 function registerGlobal(CSSRuntime) {
-    if (!globalThis.CSSRuntime) globalThis.CSSRuntime = CSSRuntime;
+    if (!globalThis.MasterCSSRuntime) globalThis.MasterCSSRuntime = CSSRuntime;
     installHook();
 }
 
@@ -15,6 +17,10 @@ function findNativeCSSRuleIndex(cssRules, nativeRule) {
     return -1;
 }
 
+function getRuleNodes(rule) {
+    const nodes = rule.nodes;
+    return Array.isArray(nodes) ? nodes : undefined;
+}
 class RuntimeLayer extends Layer {
     name;
     cssRuntime;
@@ -33,11 +39,15 @@ class RuntimeLayer extends Layer {
         }
     }
     insert(rule, index = this.rules.length) {
+        const hadNative = !!this.native?.parentStyleSheet;
+        const wasEmpty = this.rules.length === 0;
         const insertedIndex = super.insert(rule, index);
         if (insertedIndex === undefined || !this.native) return;
+        const nativeInsertIndex = this.getNativeInsertIndex(insertedIndex);
+        const wasAttachedWithRule = !hadNative && wasEmpty;
         const insertRuleSafely = (text, position)=>{
             // Checks if the rule is inserted in a native CSS rule with this.attach()
-            if (this.rules.length === 1) {
+            if (wasAttachedWithRule) {
                 return this.native.cssRules.item(position);
             } else {
                 try {
@@ -53,17 +63,26 @@ class RuntimeLayer extends Layer {
                 }
             }
         };
-        if ('nodes' in rule) {
-            let currentIndex = insertedIndex;
-            rule.nodes.forEach((node)=>{
+        const nodes = getRuleNodes(rule);
+        if (nodes) {
+            let currentIndex = nativeInsertIndex;
+            nodes.forEach((node)=>{
                 node.native = insertRuleSafely(node.text, currentIndex);
                 if (node.native) currentIndex++;
             });
         } else {
-            rule.native = insertRuleSafely(rule.text, insertedIndex);
+            rule.native = insertRuleSafely(rule.text, nativeInsertIndex);
         }
         return insertedIndex;
     }
+    getNativeInsertIndex(index) {
+        let nativeIndex = 0;
+        for(let i = 0; i < index; i++){
+            const rule = this.rules[i];
+            nativeIndex += getRuleNodes(rule)?.length ?? 1;
+        }
+        return nativeIndex;
+    }
     detach() {
         super.detach();
         const nativeSheet = this.cssRuntime.style?.sheet;
@@ -88,8 +107,9 @@ class RuntimeLayer extends Layer {
                 }
             }
         };
-        if ('nodes' in deletedRule) {
-            deletedRule.nodes.forEach((node)=>deleteRuleSafely(node.native));
+        const nodes = getRuleNodes(deletedRule);
+        if (nodes) {
+            nodes.forEach((node)=>deleteRuleSafely(node.native));
         } else {
             deleteRuleSafely(deletedRule.native);
         }
@@ -108,291 +128,950 @@ class RuntimeLayer extends Layer {
     }
 }
 
-const RuntimeSyntaxLayer = withSyntaxLayer(RuntimeLayer);
+function findUtilityInsertIndex(rules, utility) {
+    let low = 0;
+    let high = rules.length;
+    while(low < high){
+        const mid = low + high >> 1;
+        const rule = rules[mid];
+        if (!('priority' in rule)) {
+            return findUtilityInsertIndexLinear(rules, utility);
+        }
+        if (compareRulePriority(utility, rule) < 0) {
+            high = mid;
+        } else {
+            low = mid + 1;
+        }
+    }
+    return low;
+}
+function findUtilityInsertIndexLinear(rules, utility) {
+    for(let i = 0; i < rules.length; i++){
+        const rule = rules[i];
+        if (!('priority' in rule)) continue;
+        if (compareRulePriority(utility, rule) < 0) {
+            return i;
+        }
+    }
+    return rules.length;
+}
+class RuntimeUtilityLayer extends RuntimeLayer {
+    rules = [];
+    insert(utility) {
+        if (this.get(utility.key)) return;
+        if ('valid' in utility && !utility.valid) return;
+        let index = this.rules.length;
+        if ('priority' in utility) {
+            index = findUtilityInsertIndex(this.rules, utility);
+        }
+        const insertedIndex = super.insert(utility, index);
+        if (insertedIndex === undefined) return;
+        this.insertVariables(utility);
+        this.insertAnimations(utility);
+        return insertedIndex;
+    }
+    delete(key) {
+        const utility = super.delete(key);
+        if (!utility) return;
+        const deleteLayerToken = (layerToken, layer, visited = new Set())=>{
+            if (visited.has(layerToken)) return;
+            visited.add(layerToken);
+            const count = layer.tokenCounts.get(layerToken) ?? 0;
+            const variable = layer === this.css.themeLayer ? this.css.variables.get(layerToken) : undefined;
+            if (count <= 1) {
+                const deletedRule = layer.delete(layerToken);
+                layer.tokenCounts.delete(layerToken);
+                variable?.dependencies?.forEach((dependency)=>deleteLayerToken(dependency, layer, visited));
+                return deletedRule;
+            } else {
+                layer.tokenCounts.set(layerToken, count - 1);
+                variable?.dependencies?.forEach((dependency)=>deleteLayerToken(dependency, layer, visited));
+            }
+        };
+        if ('variableNames' in utility) utility.variableNames?.forEach((eachVariableName)=>{
+            deleteLayerToken(eachVariableName, this.css.themeLayer);
+        });
+        if ('animationNames' in utility) utility.animationNames?.forEach((eachAnimationName)=>{
+            const deletedAnimationRule = deleteLayerToken(eachAnimationName, this.css.animationsNonLayer);
+            const variableNames = deletedAnimationRule && 'variableNames' in deletedAnimationRule ? deletedAnimationRule.variableNames : undefined;
+            if (variableNames) {
+                variableNames.forEach((eachVariableName)=>{
+                    deleteLayerToken(eachVariableName, this.css.themeLayer);
+                });
+            }
+        });
+        return utility;
+    }
+    insertVariables(utility) {
+        if (!('variableNames' in utility)) return;
+        const insertVariable = (eachVariableName, visited = new Set())=>{
+            if (visited.has(eachVariableName)) return;
+            visited.add(eachVariableName);
+            const variable = this.css.variables.get(eachVariableName);
+            if (!variable || variable.inline) return;
+            if (this.css.themeLayer.rules.find(({ name })=>name === eachVariableName) || this.css.isEmittedGlobalsVariable(eachVariableName)) {
+                const count = this.css.themeLayer.tokenCounts.get(eachVariableName) || 0;
+                this.css.themeLayer.tokenCounts.set(eachVariableName, count + 1);
+            } else {
+                const newRule = new VariableRule(eachVariableName, variable, this.css);
+                this.css.themeLayer.insert(newRule);
+                this.css.themeLayer.tokenCounts.set(eachVariableName, 1);
+            }
+            variable.dependencies?.forEach((dependency)=>insertVariable(dependency, visited));
+        };
+        utility.variableNames?.forEach((eachVariableName)=>insertVariable(eachVariableName));
+    }
+    insertAnimations(utility) {
+        if (!('animationNames' in utility)) return;
+        utility.animationNames?.forEach((eachAnimationName)=>{
+            const animationRule = this.css.animationsNonLayer.rules.find(({ name })=>name === eachAnimationName);
+            if (animationRule || this.css.isEmittedGlobalsAnimation(eachAnimationName)) {
+                const count = this.css.animationsNonLayer.tokenCounts.get(eachAnimationName) || 0;
+                this.css.animationsNonLayer.tokenCounts.set(eachAnimationName, count + 1);
+                if (animationRule) this.insertVariables(animationRule);
+            } else {
+                const keyframes = this.css.animations.get(eachAnimationName);
+                if (!keyframes) return;
+                const newRule = new AnimationRule(eachAnimationName, keyframes, this.css);
+                this.css.animationsNonLayer.insert(newRule);
+                this.css.animationsNonLayer.tokenCounts.set(eachAnimationName, 1);
+                this.insertVariables(newRule);
+            }
+        });
+    }
+}
+
+class RuntimeThemeLayer extends ThemeLayer {
+    name;
+    cssRuntime;
+    native = null;
+    nativeBuckets = new Map();
+    constructor(name, cssRuntime){
+        super(name, cssRuntime), this.name = name, this.cssRuntime = cssRuntime;
+    }
+    attach() {
+        super.attach();
+        const nativeSheet = this.cssRuntime.style?.sheet;
+        if (nativeSheet && !this.native?.parentStyleSheet) {
+            const insertedIndex = nativeSheet.insertRule(this.text, nativeSheet.cssRules.length);
+            this.native = nativeSheet.cssRules.item(insertedIndex);
+            this.syncNativeBuckets();
+        }
+    }
+    getBucketKey(mediaText, selectorText) {
+        const normalizedMediaText = mediaText.replace(/\s*:\s*/g, ':').replace(/\s+/g, ' ').trim();
+        const normalizedSelectorText = selectorText.replace(/\s*,\s*/g, ',').replace(/\s+/g, ' ').trim();
+        return normalizedMediaText + '\n' + normalizedSelectorText;
+    }
+    getStyleRule(nativeRule) {
+        if (nativeRule instanceof CSSStyleRule) return nativeRule;
+        if (nativeRule instanceof CSSGroupingRule) {
+            return nativeRule.cssRules.item(0);
+        }
+    }
+    syncNativeBuckets() {
+        this.nativeBuckets.clear();
+        if (!this.native) return;
+        for (const nativeRule of this.native.cssRules){
+            const styleRule = this.getStyleRule(nativeRule);
+            if (!styleRule) continue;
+            const mediaText = nativeRule instanceof CSSMediaRule ? nativeRule.conditionText : '';
+            const normalizedMediaText = mediaText ? `@media ${mediaText}` : '';
+            const key = this.getBucketKey(normalizedMediaText, styleRule.selectorText);
+            this.nativeBuckets.set(key, {
+                key,
+                mediaText: normalizedMediaText,
+                selectorText: styleRule.selectorText,
+                nativeRule,
+                styleRule
+            });
+        }
+    }
+    ensureNativeBucket(mediaText, selectorText) {
+        if (!this.native) return;
+        const key = this.getBucketKey(mediaText, selectorText);
+        let bucket = this.nativeBuckets.get(key);
+        if (bucket) return bucket;
+        const text = mediaText ? `${mediaText}{${selectorText}{}}` : `${selectorText}{}`;
+        const insertedIndex = this.native.insertRule(text, this.getNativeBucketInsertIndex(mediaText, selectorText));
+        const nativeRule = this.native.cssRules.item(insertedIndex);
+        if (!nativeRule) return;
+        const styleRule = this.getStyleRule(nativeRule);
+        if (!styleRule) return;
+        const newBucket = {
+            key,
+            mediaText,
+            selectorText,
+            nativeRule,
+            styleRule
+        };
+        this.nativeBuckets.set(key, newBucket);
+        return newBucket;
+    }
+    getNativeBucketInsertIndex(mediaText, selectorText) {
+        if (!this.native) return 0;
+        const bucket = {
+            mediaText,
+            selectorText
+        };
+        for(let index = 0; index < this.native.cssRules.length; index++){
+            const nativeRule = this.native.cssRules.item(index);
+            if (!nativeRule) continue;
+            const styleRule = this.getStyleRule(nativeRule);
+            if (!styleRule) continue;
+            const nativeMediaText = nativeRule instanceof CSSMediaRule ? `@media ${nativeRule.conditionText}` : '';
+            if (this.shouldInsertBucketBefore(bucket, {
+                mediaText: nativeMediaText,
+                selectorText: styleRule.selectorText
+            })) {
+                return index;
+            }
+        }
+        return this.native.cssRules.length;
+    }
+    insert(rule, index = this.rules.length) {
+        const wasEmpty = this.rules.length === 0;
+        const insertedIndex = super.insert(rule, index);
+        if (insertedIndex === undefined || !this.native || wasEmpty) return insertedIndex;
+        for (const node of rule.nodes){
+            const bucket = this.ensureNativeBucket(node.mediaText, node.selectorText);
+            bucket?.styleRule.style.setProperty(node.declarationName, node.declarationValue);
+            node.native = bucket?.styleRule;
+        }
+        return insertedIndex;
+    }
+    delete(key) {
+        const rule = this.rules.find((rule)=>rule.key === key);
+        const deletedRule = super.delete(key);
+        if (!rule || !deletedRule || !this.native) return deletedRule;
+        for (const node of rule.nodes){
+            const bucketKey = this.getBucketKey(node.mediaText, node.selectorText);
+            const bucket = this.nativeBuckets.get(bucketKey);
+            if (!bucket) continue;
+            bucket.styleRule.style.removeProperty(node.declarationName);
+            if (bucket.styleRule.style.length === 0) {
+                const foundIndex = findNativeCSSRuleIndex(this.native.cssRules, bucket.nativeRule);
+                if (foundIndex !== -1) {
+                    this.native.deleteRule(foundIndex);
+                }
+                this.nativeBuckets.delete(bucketKey);
+            }
+        }
+        return deletedRule;
+    }
+    detach() {
+        super.detach();
+        const nativeSheet = this.cssRuntime.style?.sheet;
+        if (nativeSheet && this.native?.parentStyleSheet) {
+            const foundIndex = findNativeCSSRuleIndex(nativeSheet.cssRules, this.native);
+            if (foundIndex !== -1) {
+                nativeSheet.deleteRule(foundIndex);
+            }
+        }
+        this.native = null;
+        this.nativeBuckets.clear();
+    }
+    reset() {
+        super.reset();
+        const nativeSheet = this.cssRuntime.style?.sheet;
+        if (this.native && nativeSheet) {
+            const foundIndex = findNativeCSSRuleIndex(nativeSheet.cssRules, this.native);
+            if (foundIndex !== -1) {
+                nativeSheet.deleteRule(foundIndex);
+            }
+        }
+        this.native = null;
+        this.nativeBuckets.clear();
+    }
+}
+
+function updateClassDelta(deltaCounts, className, delta) {
+    const nextDelta = (deltaCounts.get(className) || 0) + delta;
+    if (nextDelta) {
+        deltaCounts.set(className, nextDelta);
+    } else {
+        deltaCounts.delete(className);
+    }
+}
+function traverseElementSubtree(root, visited, callback) {
+    const stack = [
+        root
+    ];
+    while(stack.length){
+        const el = stack.pop();
+        if (visited.has(el)) continue;
+        visited.add(el);
+        callback(el);
+        for(let child = el.lastElementChild; child; child = child.previousElementSibling){
+            stack.push(child);
+        }
+    }
+}
+class RuntimeClassTracker {
+    snapshots = new WeakMap();
+    reset() {
+        this.snapshots = new WeakMap();
+    }
+    collectConnected(root, classCounts) {
+        this.reset();
+        const connectedNames = new Set();
+        for (const el of root.querySelectorAll('[class]')){
+            const classNames = this.snapshotElement(el);
+            if (!classNames) continue;
+            for (const className of classNames){
+                const count = classCounts.get(className) || 0;
+                if (!count) connectedNames.add(className);
+                classCounts.set(className, count + 1);
+            }
+        }
+        return connectedNames;
+    }
+    collectMutations(records) {
+        const deltaCounts = new Map();
+        const nodeCounts = new Map();
+        const attrRecords = new Set();
+        const visited = new WeakSet();
+        const updateNodeCount = (el, delta)=>{
+            const nextCount = (nodeCounts.get(el) || 0) + delta;
+            if (nextCount) {
+                nodeCounts.set(el, nextCount);
+            } else {
+                nodeCounts.delete(el);
+            }
+        };
+        for (const record of records){
+            if (record.type === 'childList') {
+                for (const node of record.addedNodes){
+                    if (node instanceof Element && node.isConnected) updateNodeCount(node, 1);
+                }
+                for (const node of record.removedNodes){
+                    if (node instanceof Element && !node.isConnected) updateNodeCount(node, -1);
+                }
+            } else if (record.type === 'attributes' && record.attributeName === 'class') {
+                const target = record.target;
+                if (target instanceof Element) attrRecords.add(target);
+            }
+        }
+        for (const [node, count] of nodeCounts){
+            if (count > 0) {
+                traverseElementSubtree(node, visited, (el)=>this.diffElement(el, deltaCounts));
+            } else if (count < 0 && !node.isConnected) {
+                traverseElementSubtree(node, visited, (el)=>this.removeElement(el, deltaCounts));
+            }
+        }
+        for (const el of attrRecords){
+            if (!visited.has(el)) this.diffElement(el, deltaCounts);
+        }
+        return deltaCounts;
+    }
+    snapshotElement(el) {
+        const classList = el.classList;
+        if (!classList.length) {
+            this.snapshots.delete(el);
+            return;
+        }
+        const classNames = new Set();
+        for(let i = 0; i < classList.length; i++){
+            classNames.add(classList.item(i));
+        }
+        this.snapshots.set(el, classNames);
+        return classNames;
+    }
+    diffElement(el, deltaCounts) {
+        const previousClassNames = this.snapshots.get(el);
+        const classList = el.classList;
+        let nextClassNames;
+        for(let i = 0; i < classList.length; i++){
+            const className = classList.item(i);
+            if (!previousClassNames?.has(className)) updateClassDelta(deltaCounts, className, 1);
+            (nextClassNames ??= new Set()).add(className);
+        }
+        if (previousClassNames) {
+            for (const className of previousClassNames){
+                if (!nextClassNames?.has(className)) updateClassDelta(deltaCounts, className, -1);
+            }
+        }
+        if (nextClassNames) {
+            this.snapshots.set(el, nextClassNames);
+        } else {
+            this.snapshots.delete(el);
+        }
+    }
+    removeElement(el, deltaCounts) {
+        const previousClassNames = this.snapshots.get(el);
+        if (!previousClassNames) return;
+        for (const className of previousClassNames){
+            updateClassDelta(deltaCounts, className, -1);
+        }
+        this.snapshots.delete(el);
+    }
+}
+
+function collectVariableNames(text) {
+    const variableNames = new Set();
+    for (const match of text.matchAll(/var\(\s*--([_a-zA-Z0-9-]+)/g)){
+        variableNames.add(match[1]);
+    }
+    return variableNames;
+}
+class HydratedGeneratedRuleNode {
+    text;
+    native;
+    constructor(text){
+        this.text = text;
+    }
+}
+class HydratedGeneratedRule {
+    ir;
+    layer;
+    native;
+    name;
+    key;
+    layerName;
+    type;
+    sortTier;
+    priority;
+    text;
+    valid = true;
+    fixedClass;
+    nodes;
+    variableNames;
+    animationNames;
+    selectorText;
+    constructor(ir, layer){
+        this.ir = ir;
+        this.layer = layer;
+        this.name = ir.className;
+        this.key = ir.key;
+        this.layerName = ir.layer;
+        this.type = ir.type;
+        this.sortTier = ir.sortTier;
+        this.priority = ir.priority;
+        this.text = ir.text;
+        this.selectorText = ir.selectorText;
+        if (ir.nodes?.length) {
+            this.nodes = ir.nodes.map((node)=>new HydratedGeneratedRuleNode(node.text));
+        }
+        const variableNames = collectVariableNames(ir.text);
+        ir.nodes?.forEach((node)=>{
+            collectVariableNames(node.text).forEach((variableName)=>variableNames.add(variableName));
+        });
+        ir.variableNames?.forEach((variableName)=>variableNames.add(variableName));
+        if (variableNames.size) {
+            this.variableNames = variableNames;
+        }
+        if (ir.animationNames?.length) {
+            this.animationNames = new Set(ir.animationNames);
+        }
+    }
+}
 
+const supportsCache = new Map();
+const browserNativeDeclarationMatcher = ({ property, value })=>{
+    if (property.startsWith('--')) return true;
+    const cacheKey = property + '\0' + value;
+    const cached = supportsCache.get(cacheKey);
+    if (cached !== undefined) return cached;
+    const supported = Boolean(globalThis.CSS?.supports(property, value));
+    supportsCache.set(cacheKey, supported);
+    return supported;
+};
+
+const MASTER_CSS_RUNTIME_STYLE_SELECTOR = `style#${MASTER_CSS_RUNTIME_STYLE_ID}`;
+function isDocumentRoot(root) {
+    const rootConstructorName = root?.constructor.name;
+    return rootConstructorName === 'HTMLDocument' || rootConstructorName === 'Document';
+}
+function findElementById(root, id) {
+    return isDocumentRoot(root) ? root.getElementById(id) : 'querySelector' in root ? root.querySelector(`#${id}`) : undefined;
+}
+function parseHydrationManifest(source) {
+    try {
+        const hydrationManifest = JSON.parse(source);
+        return hydrationManifest?.version === 1 && Array.isArray(hydrationManifest.rules) ? hydrationManifest : undefined;
+    } catch (error) {
+    }
+}
+function readInlineHydrationManifest(root) {
+    const element = findElementById(root, MASTER_CSS_HYDRATION_MANIFEST_SCRIPT_ID);
+    const source = element?.textContent?.trim();
+    if (!source) return;
+    return parseHydrationManifest(source);
+}
+function readExternalHydrationManifestSource(root) {
+    const styleElement = findElementById(root, MASTER_CSS_RUNTIME_STYLE_ID);
+    const HTMLStyleElementConstructor = globalThis.HTMLStyleElement;
+    return HTMLStyleElementConstructor && styleElement instanceof HTMLStyleElementConstructor ? styleElement.getAttribute(MASTER_CSS_HYDRATION_MANIFEST_ATTR) : undefined;
+}
 class CSSRuntime extends MasterCSS {
     root;
-    customConfig;
-    baseConfig;
+    hydrationManifest;
     static instances = new WeakMap();
     host;
     container;
-    baseLayer = new RuntimeSyntaxLayer('base', this);
-    themeLayer = new RuntimeLayer('theme', this);
-    presetLayer = new RuntimeSyntaxLayer('preset', this);
-    componentsLayer = new RuntimeSyntaxLayer('components', this);
-    generalLayer = new RuntimeSyntaxLayer('general', this);
+    baseLayer = new RuntimeUtilityLayer('base', this);
+    themeLayer = new RuntimeThemeLayer('theme', this);
+    defaultsLayer = new RuntimeUtilityLayer('defaults', this);
+    componentsLayer = new RuntimeUtilityLayer('components', this);
+    utilitiesLayer = new RuntimeUtilityLayer('utilities', this);
     classCounts = new Map();
+    classTracker = new RuntimeClassTracker();
+    hydrationFailureReason;
     observer;
     progressive = false;
     observing = false;
-    constructor(root = document, customConfig = config, baseConfig){
-        super(customConfig, baseConfig), this.root = root, this.customConfig = customConfig, this.baseConfig = baseConfig;
-        // Do not use instanceof here, because it will not work
-        const rootConstructorName = root?.constructor.name;
-        if (rootConstructorName === 'HTMLDocument' || rootConstructorName === 'Document') {
-            this.root.defaultView.globalThis.cssRuntime = this;
-            this.container = this.root.head;
-            this.host = this.root.documentElement;
+    static create(options) {
+        const { manifest, root = document, emittedGlobals, hydrationManifest } = options;
+        const resolvedHydrationManifest = hydrationManifest === undefined ? readInlineHydrationManifest(root) : hydrationManifest;
+        const current = globalThis.MasterCSSRuntime.instances.get(root);
+        if (current) {
+            current.registerEmittedGlobals(emittedGlobals);
+            if (resolvedHydrationManifest !== undefined) current.setHydrationManifest(resolvedHydrationManifest);
+            return current;
+        }
+        return new CSSRuntime(root, manifest, emittedGlobals, resolvedHydrationManifest).register();
+    }
+    constructor(root = document, manifest, emittedGlobals, hydrationManifest){
+        super(manifest, emittedGlobals, {
+            nativeDeclarationMatcher: browserNativeDeclarationMatcher
+        }), this.root = root, this.hydrationManifest = hydrationManifest;
+        if (isDocumentRoot(root)) {
+            this.container = root.head;
+            this.host = root.documentElement;
         } else {
             this.container = this.root;
             this.host = this.root.host;
         }
-        globalThis.CSSRuntime.instances.set(this.root, this);
-        __MASTER_CSS_DEVTOOLS_HOOK__?.emit('runtime:created', {
-            cssRuntime: this
+        this.applyEmittedGlobalsCounts({
+            variables: this.emittedGlobals.variables
         });
     }
-    /**
-     * Observe the DOM for changes and update the running stylesheet. (browser only)
-     * @param options mutation observer options
-     * @returns this
-     */ observe() {
-        if (this.observing) return this;
-        // Detect prerendered stylesheet
+    register() {
+        const registered = globalThis.MasterCSSRuntime.instances.get(this.root) === this;
+        globalThis.MasterCSSRuntime.instances.set(this.root, this);
+        if (isDocumentRoot(this.root)) {
+            this.root.defaultView.globalThis.masterCSSRuntime = this;
+        }
+        if (!registered) {
+            __MASTER_CSS_DEVTOOLS_HOOK__?.emit('runtime:created', {
+                cssRuntime: this
+            });
+        }
+        return this;
+    }
+    unregister() {
+        globalThis.MasterCSSRuntime.instances.delete(this.root);
+        if (isDocumentRoot(this.root) && this.root.defaultView.globalThis.masterCSSRuntime === this) {
+            this.root.defaultView.globalThis.masterCSSRuntime = undefined;
+        }
+        return this;
+    }
+    setHydrationManifest(hydrationManifest) {
+        this.hydrationManifest = hydrationManifest;
+        return this;
+    }
+    needsHydrationManifest() {
+        return this.hydrationManifest === undefined && Boolean(readExternalHydrationManifestSource(this.root));
+    }
+    async loadHydrationManifest() {
+        const inlineHydrationManifest = readInlineHydrationManifest(this.root);
+        if (inlineHydrationManifest) {
+            this.setHydrationManifest(inlineHydrationManifest);
+            return this;
+        }
+        const source = readExternalHydrationManifestSource(this.root);
+        if (!source) return this;
+        try {
+            const response = await fetch(source, {
+                credentials: 'same-origin'
+            });
+            if (!response.ok) return this;
+            this.setHydrationManifest(parseHydrationManifest(await response.text()));
+        } catch (error) {
+        }
+        return this;
+    }
+    createRuntimeStyle() {
+        const ownerDocument = 'createElement' in this.root ? this.root : this.root.ownerDocument;
+        this.style = ownerDocument.createElement('style');
+        this.style.id = MASTER_CSS_RUNTIME_STYLE_ID;
+        this.style.setAttribute('blocking', 'render');
+        this.container.append(this.style);
+    }
+    warnHydrationFallback(reason) {
+        console.warn(`Master CSS progressive hydration requires a matching hydration manifest. ${reason} Rebuilding ${MASTER_CSS_RUNTIME_STYLE_SELECTOR} with the runtime.`);
+    }
+    useRuntimeStyle(connectedNames, reason) {
+        if (reason) this.warnHydrationFallback(reason);
+        this.style?.remove();
+        this.style = null;
+        this.progressive = false;
+        this.createRuntimeStyle();
+        this.insertStaticResources();
+        connectedNames.forEach((cls)=>this.add(cls));
+    }
+    detectRuntimeStyle() {
         if (this.root.styleSheets) {
             for (const sheet of this.root.styleSheets){
                 const { ownerNode } = sheet;
-                if (ownerNode instanceof HTMLStyleElement && ownerNode.id === 'master') {
+                if (ownerNode instanceof HTMLStyleElement && ownerNode.id === MASTER_CSS_RUNTIME_STYLE_ID) {
                     this.style = ownerNode;
-                    if (this.style.sheet?.cssRules.length) {
-                        this.progressive = true;
-                    }
+                    this.progressive = true;
                     break;
                 }
             }
         }
-        // Prepare snapshot map
-        const elementClasses = new WeakMap();
-        // Initial scan and populate counts + snapshot
-        const connectedNames = new Set();
-        const increaseClassCount = (className)=>{
-            const count = this.classCounts.get(className) || 0;
-            if (!count) connectedNames.add(className);
-            this.classCounts.set(className, count + 1);
-        };
-        const elementsWithClass = this.root.querySelectorAll('[class]');
-        elementsWithClass.forEach((el)=>{
-            const clsList = el.classList;
-            if (clsList) {
-                el.classList.forEach(increaseClassCount);
-            }
-            elementClasses.set(el, new Set(clsList));
-        });
-        // Hydration or style creation
-        if (this.progressive) {
-            const hydrateResult = this.hydrate(this.style.sheet.cssRules);
+    }
+    collectConnectedClasses() {
+        return this.classTracker.collectConnected(this.root, this.classCounts);
+    }
+    hydrateRuntimeStyle(connectedNames) {
+        const hydrateResult = this.style?.sheet && this.hydrate(this.style.sheet.cssRules);
+        if (hydrateResult) {
+            const hydratedClassNames = new Set(hydrateResult.allUtilities.map(({ fixedClass, name })=>fixedClass || name));
             for (const cls of connectedNames){
-                if (!hydrateResult.allSyntaxRules.find((r)=>(r.fixedClass || r.name) === cls)) {
+                if (!hydratedClassNames.has(cls)) {
                     this.add(cls);
                 }
             }
         } else {
-            this.style = document.createElement('style');
-            this.style.id = 'master';
-            this.style.setAttribute('blocking', 'render');
-            this.container.append(this.style);
-            this.style.sheet.insertRule(this.layerStatementRule.text);
-            this.layerStatementRule.native = this.style.sheet.cssRules.item(0);
-            connectedNames.forEach((cls)=>this.add(cls));
-        }
-        this.observer = new MutationObserver((records)=>{
-            const deltaCounts = new Map();
-            const nodeMap = new Map();
-            const attrRecords = new Set();
-            const visited = new WeakSet();
-            const updateDelta = (cls, delta)=>deltaCounts.set(cls, (deltaCounts.get(cls) || 0) + delta);
-            const diffAndSnapshot = (el)=>{
-                const prev = new Set(elementClasses.get(el) || []);
-                const next = new Set(el.classList);
-                for (const c of next)if (!prev.has(c)) updateDelta(c, 1);
-                for (const c of prev)if (!next.has(c)) updateDelta(c, -1);
-                elementClasses.set(el, next);
-            };
-            const removeSnapshot = (el)=>{
-                for (const c of elementClasses.get(el) || [])updateDelta(c, -1);
-                elementClasses.delete(el);
-            };
-            for (const record of records){
-                if (record.type === 'childList') {
-                    for (const node of record.addedNodes)if (node instanceof Element && node.isConnected) nodeMap.set(node, (nodeMap.get(node) || 0) + 1);
-                    for (const node of record.removedNodes)if (node instanceof Element && !node.isConnected) nodeMap.set(node, (nodeMap.get(node) || 0) - 1);
-                } else if (record.type === 'attributes' && record.attributeName === 'class') {
-                    attrRecords.add(record.target);
-                }
-            }
-            const traverseIncludingSelf = (el, fn, visited)=>{
-                if (!visited.has(el)) {
-                    visited.add(el);
-                    fn(el);
-                    for (const child of el.children){
-                        traverseIncludingSelf(child, fn, visited);
-                    }
-                } else {
-                    nodeMap.delete(el);
-                }
-            };
-            for (const [node, count] of nodeMap){
-                if (count > 0) {
-                    traverseIncludingSelf(node, diffAndSnapshot, visited);
-                } else if (count < 0 && !node.isConnected) {
-                    traverseIncludingSelf(node, removeSnapshot, visited);
-                }
-            }
-            for (const el of attrRecords){
-                if (!visited.has(el)) diffAndSnapshot(el);
-            }
-            for (const [cls, change] of deltaCounts){
-                const current = this.classCounts.get(cls) || 0;
-                const next = current + change;
-                if (next > 0) {
-                    this.classCounts.set(cls, next);
-                    if (current === 0) this.add(cls);
-                } else {
-                    this.classCounts.delete(cls);
-                    this.remove(cls);
-                }
+            this.useRuntimeStyle(connectedNames, this.hydrationFailureReason || `Cannot read ${MASTER_CSS_RUNTIME_STYLE_SELECTOR} CSS rules.`);
+        }
+    }
+    renderRuntimeStyle(connectedNames) {
+        this.createRuntimeStyle();
+        this.insertStaticResources();
+        connectedNames.forEach((cls)=>this.add(cls));
+    }
+    handleMutationRecords(records) {
+        const deltaCounts = this.classTracker.collectMutations(records);
+        const addedClassNames = [];
+        const removedClassNames = [];
+        for (const [cls, change] of deltaCounts){
+            const current = this.classCounts.get(cls) || 0;
+            const next = current + change;
+            if (next > 0) {
+                this.classCounts.set(cls, next);
+                if (current === 0) addedClassNames.push(cls);
+            } else {
+                this.classCounts.delete(cls);
+                removedClassNames.push(cls);
             }
-            globalThis.__MASTER_CSS_DEVTOOLS_HOOK__?.emit('runtime:mutated', {
-                records,
-                classCounts: deltaCounts,
-                cssRuntime: this
-            });
+        }
+        if (addedClassNames.length) this.add(...addedClassNames);
+        if (removedClassNames.length) this.remove(...removedClassNames);
+        globalThis.__MASTER_CSS_DEVTOOLS_HOOK__?.emit('runtime:mutated', {
+            records,
+            classCounts: deltaCounts,
+            cssRuntime: this
         });
+    }
+    startMutationObserver() {
+        this.observer = new MutationObserver((records)=>this.handleMutationRecords(records));
         this.observer.observe(this.root, {
             childList: true,
             attributes: true,
             attributeFilter: [
                 'class'
             ],
-            attributeOldValue: true,
             subtree: true
         });
+    }
+    revealHostIfNeeded() {
         if (!this.progressive) this.host.removeAttribute('hidden');
+    }
+    /**
+     * Observe the DOM for changes and update the running stylesheet. (browser only)
+     * @param options mutation observer options
+     * @returns this
+     */ observe() {
+        if (this.observing) return this;
+        this.detectRuntimeStyle();
+        const connectedNames = this.collectConnectedClasses();
+        if (this.progressive) {
+            this.hydrateRuntimeStyle(connectedNames);
+        } else {
+            this.renderRuntimeStyle(connectedNames);
+        }
+        this.startMutationObserver();
+        this.revealHostIfNeeded();
         this.observing = true;
         globalThis.__MASTER_CSS_DEVTOOLS_HOOK__?.emit('runtime:observed', {
             cssRuntime: this
         });
         return this;
     }
+    failHydration(reason) {
+        this.hydrationFailureReason = reason;
+        return undefined;
+    }
+    getHydrationManifestLayerRules() {
+        const layers = new Map();
+        if (!this.hydrationManifest?.rules?.length) return layers;
+        for (const rule of this.hydrationManifest.rules){
+            const layerRules = layers.get(rule.layer);
+            if (layerRules) {
+                layerRules.push(rule);
+            } else {
+                layers.set(rule.layer, [
+                    rule
+                ]);
+            }
+        }
+        return layers;
+    }
+    registerHydratedClassRule(className, rule) {
+        const classUtilities = this.classUtilities;
+        const rules = classUtilities.get(className);
+        if (rules) {
+            rules.push(rule);
+        } else {
+            classUtilities.set(className, [
+                rule
+            ]);
+        }
+    }
+    getUtilityLayerByName(name) {
+        switch(name){
+            case 'base':
+                return this.baseLayer;
+            case 'defaults':
+                return this.defaultsLayer;
+            case 'components':
+                return this.componentsLayer;
+            case 'utilities':
+                return this.utilitiesLayer;
+        }
+    }
+    collectHydrationManifestVariableNames() {
+        const variableNames = new Set();
+        const collectVariableReferences = (text)=>{
+            for (const match of text.matchAll(/var\(\s*--([_a-zA-Z0-9-]+)/g)){
+                collectVariable(match[1]);
+            }
+        };
+        const collectVariable = (variableName, visited = new Set())=>{
+            if (visited.has(variableName)) return;
+            visited.add(variableName);
+            const variable = this.variables.get(variableName);
+            if (!variable) return;
+            variableNames.add(variableName);
+            variable.dependencies?.forEach((dependency)=>collectVariable(dependency, visited));
+        };
+        for (const rule of this.hydrationManifest?.rules || []){
+            rule.variableNames?.forEach((variableName)=>collectVariable(variableName));
+            collectVariableReferences(rule.text);
+            rule.nodes?.forEach((node)=>collectVariableReferences(node.text));
+            rule.animationNames?.forEach((animationName)=>{
+                const keyframes = this.animations.get(animationName);
+                if (!keyframes) return;
+                const animationRule = new AnimationRule(animationName, keyframes, this);
+                animationRule.variableNames?.forEach((variableName)=>collectVariable(variableName));
+            });
+        }
+        for (const [variableName, variable] of this.variables){
+            if (variable.static) collectVariable(variableName);
+        }
+        return variableNames;
+    }
+    collectHydrationManifestAnimationNames() {
+        const animationNames = new Set();
+        for (const rule of this.hydrationManifest?.rules || []){
+            rule.animationNames?.forEach((animationName)=>animationNames.add(animationName));
+        }
+        for (const animationName of this.animations.keys()){
+            if (this.manifest.animationOptions?.[animationName]?.static) animationNames.add(animationName);
+        }
+        return animationNames;
+    }
+    nativeThemeLayerHasOnlyEmittedGlobalsVariables(nativeThemeLayer) {
+        if (!nativeThemeLayer) return false;
+        let found = false;
+        for (const nativeRule of nativeThemeLayer.cssRules){
+            const styleRule = this.themeLayer.getStyleRule(nativeRule);
+            if (!styleRule) return false;
+            for(let index = 0; index < styleRule.style.length; index++){
+                const propertyName = styleRule.style.item(index);
+                if (!propertyName.startsWith('--')) return false;
+                found = true;
+                if (!this.isEmittedGlobalsVariable(propertyName.slice(2))) return false;
+            }
+        }
+        return found;
+    }
+    getVariableRuleBuckets(variableRules) {
+        const buckets = new Map();
+        for (const rule of variableRules){
+            for (const node of rule.nodes){
+                const key = this.themeLayer.getBucketKey(node.mediaText, node.selectorText);
+                let bucket = buckets.get(key);
+                if (!bucket) {
+                    bucket = {
+                        mediaText: node.mediaText,
+                        selectorText: node.selectorText,
+                        nodes: []
+                    };
+                    buckets.set(key, bucket);
+                }
+                bucket.nodes.push(node);
+            }
+        }
+        return Array.from(buckets.values());
+    }
+    getNativeThemeRuleBucketKey(nativeRule) {
+        const styleRule = this.themeLayer.getStyleRule(nativeRule);
+        if (!styleRule) return;
+        const mediaText = nativeRule instanceof CSSMediaRule ? `@media ${nativeRule.conditionText}` : '';
+        return {
+            key: this.themeLayer.getBucketKey(mediaText, styleRule.selectorText),
+            styleRule
+        };
+    }
+    hydrateHydrationManifestVariables(nativeThemeLayer) {
+        const variableRules = [
+            ...this.collectHydrationManifestVariableNames()
+        ].filter((variableName)=>!this.isEmittedGlobalsVariable(variableName)).map((variableName)=>{
+            const variable = this.variables.get(variableName);
+            return variable && !variable.inline ? new VariableRule(variableName, variable, this) : undefined;
+        }).filter((rule)=>Boolean(rule));
+        const expectedBuckets = this.getVariableRuleBuckets(variableRules);
+        const nativeRuleCount = nativeThemeLayer?.cssRules.length || 0;
+        if (expectedBuckets.length !== nativeRuleCount) {
+            return !variableRules.length && this.nativeThemeLayerHasOnlyEmittedGlobalsVariables(nativeThemeLayer);
+        }
+        if (!variableRules.length) return true;
+        if (!nativeThemeLayer) return false;
+        this.themeLayer.native = nativeThemeLayer;
+        const nativeBuckets = new Map();
+        for (const nativeRule of nativeThemeLayer.cssRules){
+            const nativeBucket = this.getNativeThemeRuleBucketKey(nativeRule);
+            if (!nativeBucket || nativeBuckets.has(nativeBucket.key)) return false;
+            nativeBuckets.set(nativeBucket.key, nativeBucket.styleRule);
+        }
+        for (const bucket of expectedBuckets){
+            const nativeStyleRule = nativeBuckets.get(this.themeLayer.getBucketKey(bucket.mediaText, bucket.selectorText));
+            if (!nativeStyleRule) return false;
+            for (const node of bucket.nodes){
+                node.native = nativeStyleRule;
+            }
+        }
+        this.themeLayer.rules.push(...variableRules);
+        this.themeLayer.syncNativeBuckets();
+        if (this.themeLayer.rules.length && !this.rules.includes(this.themeLayer)) {
+            this.rules.push(this.themeLayer);
+        }
+        return true;
+    }
+    hydrateHydrationManifestAnimations(nativeKeyframesRules) {
+        const animationNames = this.collectHydrationManifestAnimationNames();
+        const hydratedAnimationNames = new Set();
+        for (const animationName of animationNames){
+            if (this.isEmittedGlobalsAnimation(animationName)) {
+                if (nativeKeyframesRules.has(animationName)) hydratedAnimationNames.add(animationName);
+                continue;
+            }
+            const keyframes = this.animations.get(animationName);
+            if (!keyframes) continue;
+            const nativeRule = nativeKeyframesRules.get(animationName);
+            if (!nativeRule) return false;
+            const animationRule = new AnimationRule(animationName, keyframes, this);
+            animationRule.native = nativeRule;
+            this.animationsNonLayer.rules.push(animationRule);
+            this.rules.push(animationRule);
+            hydratedAnimationNames.add(animationName);
+        }
+        for (const animationName of nativeKeyframesRules.keys()){
+            if (!hydratedAnimationNames.has(animationName)) return false;
+        }
+        return true;
+    }
+    hydrateHydrationManifestLayer(layer, nativeLayerRule, manifestRules, result) {
+        const expectedRuleCount = manifestRules.reduce((count, rule)=>count + (rule.nodes?.length || 1), 0);
+        if (expectedRuleCount !== nativeLayerRule.cssRules.length) return false;
+        layer.native = nativeLayerRule;
+        let nativeIndex = 0;
+        for (const manifestRule of manifestRules){
+            const hydratedRule = new HydratedGeneratedRule(manifestRule, layer);
+            const nodes = hydratedRule.nodes;
+            if (nodes?.length) {
+                for (const node of nodes){
+                    node.native = nativeLayerRule.cssRules.item(nativeIndex++) || undefined;
+                }
+            } else {
+                hydratedRule.native = nativeLayerRule.cssRules.item(nativeIndex++) || undefined;
+            }
+            layer.rules.push(hydratedRule);
+            layer.insertVariables(hydratedRule);
+            layer.insertAnimations(hydratedRule);
+            this.registerHydratedClassRule(manifestRule.className, hydratedRule);
+            result.allUtilities.push(hydratedRule);
+        }
+        if (layer.rules.length && !this.rules.includes(layer)) {
+            this.rules.push(layer);
+        }
+        return true;
+    }
     hydrate(nativeLayerRules) {
-        const cssLayerRules = [];
-        const checkSheet = new CSSStyleSheet();
+        this.hydrationFailureReason = undefined;
+        if (this.hydrationManifest?.version !== 1 || !Array.isArray(this.hydrationManifest.rules)) {
+            return this.failHydration('Missing or invalid hydration manifest.');
+        }
+        if (!this.hydrationManifest.rules.length) {
+            return this.failHydration(`Hydration manifest has no generated rules for ${MASTER_CSS_RUNTIME_STYLE_SELECTOR}.`);
+        }
         const result = {
-            allSyntaxRules: []
+            allUtilities: []
         };
+        const manifestLayerRules = this.getHydrationManifestLayerRules();
+        const nativeUtilityLayerRules = new Map();
+        const nativeKeyframesRules = new Map();
+        let nativeThemeLayer;
         for(let i = 0; i < nativeLayerRules.length; i++){
             const eachNativeCSSRule = nativeLayerRules[i];
             if (eachNativeCSSRule.constructor.name === 'CSSLayerBlockRule') {
                 const eachCSSLayerRule = eachNativeCSSRule;
-                if (eachNativeCSSRule.name === 'theme') {
-                    this.themeLayer.native = eachCSSLayerRule;
-                    let variableRule;
-                    const unresolvedCSSRules = new Map();
-                    for (const rule of eachCSSLayerRule.cssRules){
-                        // trim() for fix the firefox bug that the cssText ends with \n\n
-                        unresolvedCSSRules.set(rule.cssText.trim(), rule);
-                    }
-                    for (const cssRule of eachCSSLayerRule.cssRules){
-                        if (!unresolvedCSSRules.has(cssRule.cssText)) continue;
-                        const variableCSSRule = cssRule.constructor.name === 'CSSMediaRule' ? cssRule.cssRules[0] : cssRule;
-                        const variableName = variableCSSRule.style[0].slice(2);
-                        const variable = this.variables.get(variableName);
-                        if (!variable) continue;
-                        variableRule = new VariableRule(variableName, variable, this);
-                        this.themeLayer.rules.push(variableRule);
-                        this.themeLayer.tokenCounts.set(variableRule.name, 0);
-                        variableRule.nodes.forEach((node)=>{
-                            const checkRuleIndex = checkSheet.insertRule(node.text);
-                            const checkNodeNativeRule = checkSheet.cssRules.item(checkRuleIndex);
-                            if (checkNodeNativeRule) {
-                                const checkNodeNativeRuleText = checkNodeNativeRule.cssText.trim();
-                                const match = unresolvedCSSRules.get(checkNodeNativeRuleText);
-                                if (match) {
-                                    node.native = match;
-                                    unresolvedCSSRules.delete(checkNodeNativeRuleText);
-                                    return;
-                                }
-                            }
-                        });
-                    }
-                    if (this.themeLayer.rules.length) this.rules.push(this.themeLayer);
-                } else {
-                    cssLayerRules.push(eachCSSLayerRule);
-                }
-            } else if (eachNativeCSSRule.constructor.name === 'CSSLayerStatementRule') {
-                this.layerStatementRule.native = eachNativeCSSRule;
-            } else if (eachNativeCSSRule.constructor.name === 'CSSKeyframesRule') {
-                const nativeKeyframsRule = eachNativeCSSRule;
-                const keyframes = this.animations.get(nativeKeyframsRule.name);
-                if (!keyframes) continue;
-                const animationRule = new AnimationRule(nativeKeyframsRule.name, keyframes, this);
-                animationRule.native = nativeKeyframsRule;
-                this.animationsNonLayer.rules.push(animationRule);
-                this.rules.push(animationRule);
-                this.animationsNonLayer.tokenCounts.set(animationRule.name, 0);
-            }
-        }
-        for (const eachCSSLayerRule of cssLayerRules){
-            let layer;
-            switch(eachCSSLayerRule.name){
-                case 'base':
-                    layer = this.baseLayer;
-                    break;
-                case 'preset':
-                    layer = this.presetLayer;
-                    break;
-                case 'components':
-                    layer = this.componentsLayer;
-                    break;
-                case 'general':
-                    layer = this.generalLayer;
-                    break;
-                default:
-                    console.error(`Cannot recognize the layer \`${eachCSSLayerRule.name}\`. (https://rc.css.master.co/messages/hydration-errors)`);
-                    continue;
-            }
-            layer.native = eachCSSLayerRule;
-            const unresolvedCSSRules = new Map();
-            for (const rule of eachCSSLayerRule.cssRules){
-                // trim() for fix the firefox bug that the cssText ends with \n\n
-                unresolvedCSSRules.set(rule.cssText.trim(), rule);
-            }
-            for (const eachNativeLayerRule of eachCSSLayerRule.cssRules){
-                if (!unresolvedCSSRules.has(eachNativeLayerRule.cssText)) continue;
-                const selectorText = this.getSelectorText(eachNativeLayerRule);
-                if (!selectorText) {
-                    console.error(`Cannot get the selector text from \`${eachNativeLayerRule.cssText}\`. (${layer.name}) (https://rc.css.master.co/messages/hydration-errors)`);
+                if (eachCSSLayerRule.name === 'theme') {
+                    if (nativeThemeLayer) return this.failHydration(`Duplicate theme layer in ${MASTER_CSS_RUNTIME_STYLE_SELECTOR}.`);
+                    nativeThemeLayer = eachCSSLayerRule;
                     continue;
                 }
-                const createdRules = this.createFromSelectorText(selectorText);
-                if (createdRules) {
-                    for (const createdRule of createdRules){
-                        layer.rules.push(createdRule);
-                        layer.insertVariables(createdRule);
-                        layer.insertAnimations(createdRule);
-                        result.allSyntaxRules.push(createdRule);
-                        try {
-                            const checkRuleIndex = checkSheet.insertRule(createdRule.text);
-                            const checkNodeNativeRule = checkSheet.cssRules.item(checkRuleIndex);
-                            if (checkNodeNativeRule) {
-                                const checkNodeNativeRuleText = checkNodeNativeRule.cssText.trim();
-                                const match = unresolvedCSSRules.get(checkNodeNativeRuleText);
-                                if (match) {
-                                    createdRule.native = match;
-                                    unresolvedCSSRules.delete(checkNodeNativeRuleText);
-                                    continue;
-                                }
-                            }
-                            console.error(`Cannot retrieve CSS rule for \`${createdRule.text}\`. (${layer.name}) (https://rc.css.master.co/messages/hydration-errors)`);
-                        } catch (error) {
-                        }
-                    }
-                } else {
-                    console.error(`Cannot recognize \`${eachNativeLayerRule.cssText}\`. (${layer.name}) (https://rc.css.master.co/messages/hydration-errors)`);
+                const layer = this.getUtilityLayerByName(eachCSSLayerRule.name);
+                if (!layer) return this.failHydration(`Unknown layer \`${eachCSSLayerRule.name}\` in ${MASTER_CSS_RUNTIME_STYLE_SELECTOR}.`);
+                if (nativeUtilityLayerRules.has(layer.name)) {
+                    return this.failHydration(`Duplicate layer \`${eachCSSLayerRule.name}\` in ${MASTER_CSS_RUNTIME_STYLE_SELECTOR}.`);
                 }
+                nativeUtilityLayerRules.set(layer.name, eachCSSLayerRule);
+            } else if (eachNativeCSSRule.constructor.name === 'CSSKeyframesRule') {
+                const nativeKeyframesRule = eachNativeCSSRule;
+                nativeKeyframesRules.set(nativeKeyframesRule.name, nativeKeyframesRule);
+            } else {
+                return this.failHydration(`Unknown top-level rule \`${eachNativeCSSRule.cssText}\` in ${MASTER_CSS_RUNTIME_STYLE_SELECTOR}.`);
+            }
+        }
+        for (const [layerName, manifestRules] of manifestLayerRules){
+            const nativeLayerRule = nativeUtilityLayerRules.get(layerName);
+            if (!nativeLayerRule) return this.failHydration(`Missing layer \`${layerName}\` in ${MASTER_CSS_RUNTIME_STYLE_SELECTOR}.`);
+            const expectedRuleCount = manifestRules.reduce((count, rule)=>count + (rule.nodes?.length || 1), 0);
+            if (expectedRuleCount !== nativeLayerRule.cssRules.length) {
+                return this.failHydration(`Layer \`${layerName}\` does not match the hydration manifest.`);
+            }
+        }
+        for (const [layerName, nativeLayerRule] of nativeUtilityLayerRules){
+            if (!manifestLayerRules.has(layerName) && nativeLayerRule.cssRules.length) {
+                return this.failHydration(`Layer \`${layerName}\` has no hydration manifest rules.`);
             }
-            if (layer.rules.length) this.rules.push(layer);
+        }
+        if (!this.hydrateHydrationManifestVariables(nativeThemeLayer)) {
+            return this.failHydration('Theme layer does not match the hydration manifest.');
+        }
+        if (!this.hydrateHydrationManifestAnimations(nativeKeyframesRules)) {
+            return this.failHydration('Keyframes do not match the hydration manifest.');
+        }
+        for (const [layerName, nativeLayerRule] of nativeUtilityLayerRules){
+            const manifestRules = manifestLayerRules.get(layerName);
+            if (!manifestRules?.length) continue;
+            const layer = this.getUtilityLayerByName(layerName);
+            this.hydrateHydrationManifestLayer(layer, nativeLayerRule, manifestRules, result);
         }
         globalThis.__MASTER_CSS_DEVTOOLS_HOOK__?.emit('runtime:hydrated', {
             cssRuntime: this,
@@ -400,13 +1079,6 @@ class CSSRuntime extends MasterCSS {
         });
         return result;
     }
-    getSelectorText(cssRule) {
-        if (cssRule instanceof CSSStyleRule) {
-            return cssRule.selectorText;
-        } else if (cssRule instanceof CSSGroupingRule) {
-            return this.getSelectorText(cssRule.cssRules.item(0));
-        }
-    }
     disconnect() {
         if (!this.observing) return;
         if (this.observer) {
@@ -416,7 +1088,9 @@ class CSSRuntime extends MasterCSS {
         // @ts-ignore
         this.observing = false;
         this.reset();
+        this.loadManifest(this.manifest);
         this.classCounts.clear();
+        this.classTracker.reset();
         if (!this.progressive) {
             this.style?.remove();
             this.style = null;
@@ -426,27 +1100,28 @@ class CSSRuntime extends MasterCSS {
         });
         return this;
     }
-    refresh(customConfig = this.customConfig) {
+    refresh(manifest = this.manifest) {
         if (!this.observing || !this.style.sheet) return this;
-        for(let i = 1; i <= this.style.sheet.cssRules.length - 1; i++){
+        const cssRules = this.style.sheet.cssRules;
+        for(let i = cssRules.length - 1; i >= 0; i--){
             this.style.sheet.deleteRule(i);
         }
-        super.refresh(customConfig);
+        super.refresh(manifest);
         /**
-         * 拿當前所有的 classNames 按照最新的 colors, config.rules 匹配並生成新的 style
+         * Recreate rules from the current class names against the latest manifest.
          * 所以 refresh 過後 rules 可能會變多也可能會變少
          */ this.classCounts.forEach((_, className)=>{
             this.add(className);
         });
         globalThis.__MASTER_CSS_DEVTOOLS_HOOK__?.emit('runtime:refreshed', {
             cssRuntime: this,
-            customConfig
+            manifest
         });
         return this;
     }
     destroy() {
         this.disconnect();
-        globalThis.CSSRuntime.instances.delete(this.root);
+        this.unregister();
         globalThis.__MASTER_CSS_DEVTOOLS_HOOK__?.emit('runtime:destroyed', {
             cssRuntime: this
         });
@@ -457,18 +1132,52 @@ class CSSRuntime extends MasterCSS {
     registerGlobal(CSSRuntime);
 })(CSSRuntime);
 
-/**
- * Initialize a new CSSRuntime instance and observe the target root
- * @param config master css config
- * @param root target root to observe
- * @param autoObserve auto observe the target root
- * @returns master css instance
- */ function initCSSRuntime(config$1, root = document, autoObserve = true) {
-    let cssRuntime = globalThis.CSSRuntime.instances.get(root);
-    if (cssRuntime) return cssRuntime;
-    cssRuntime = new CSSRuntime(root, config$1, config);
-    if (autoObserve) cssRuntime.observe();
-    return cssRuntime;
+function resolveManifest(host, manifest) {
+    return typeof manifest === 'function' ? manifest(host) : manifest;
+}
+function resolveRoot(host, root) {
+    return typeof root === 'function' ? root(host) : root || host.shadowRoot;
+}
+function resolveEmittedGlobals(host, emittedGlobals) {
+    return typeof emittedGlobals === 'function' ? emittedGlobals(host) : emittedGlobals;
+}
+function resolveHydrationManifest(host, hydrationManifest) {
+    return typeof hydrationManifest === 'function' ? hydrationManifest(host) : hydrationManifest;
+}
+function cssRuntime(options) {
+    return function(target) {
+        const connectedCallback = target.prototype.connectedCallback;
+        const disconnectedCallback = target.prototype.disconnectedCallback;
+        return class extends target {
+            cssRuntime;
+            connectedCallback() {
+                connectedCallback?.call(this);
+                const root = resolveRoot(this, options.root);
+                if (!root) {
+                    throw new Error('`@cssRuntime()` requires a shadow root. Provide `options.root` or create a shadow root before `connectedCallback()` finishes.');
+                }
+                const cssRuntime = CSSRuntime.create({
+                    manifest: resolveManifest(this, options.manifest),
+                    root,
+                    emittedGlobals: resolveEmittedGlobals(this, options.emittedGlobals),
+                    hydrationManifest: resolveHydrationManifest(this, options.hydrationManifest)
+                });
+                this.cssRuntime = cssRuntime;
+                if (cssRuntime.needsHydrationManifest()) {
+                    void cssRuntime.loadHydrationManifest().then(()=>{
+                        if (this.cssRuntime === cssRuntime) cssRuntime.observe();
+                    });
+                } else {
+                    cssRuntime.observe();
+                }
+            }
+            disconnectedCallback() {
+                disconnectedCallback?.call(this);
+                this.cssRuntime?.destroy();
+                this.cssRuntime = undefined;
+            }
+        };
+    };
 }
 
-export { CSSRuntime, RuntimeSyntaxLayer, CSSRuntime as default, initCSSRuntime };
+export { CSSRuntime, RuntimeUtilityLayer, cssRuntime, CSSRuntime as default };