@master/css-runtime 2.0.0-rc.74 → 2.0.0-rc.76

package/README.md

@@ -10,7 +10,7 @@
         </picture>
     </a>
 </p>
-<p align="center">Run Master CSS right in the browser</p>
+<p align="center">Browser runtime for Master CSS</p>
 
 <p align="center">
     <a aria-label="GitHub release (latest by date including pre-releases)" href="https://github.com/master-co/css/releases">
@@ -81,12 +81,12 @@ Use the CDN runtime when a page only needs the default preset and zero configura
 
 ```html
 <link rel="preload" as="style" href="https://cdn.master.co/css@rc/base.css">
-<link rel="preload" as="fetch" type="application/json" crossorigin href="https://cdn.master.co/css-runtime@rc/default-manifest.json">
+<link rel="modulepreload" as="json" crossorigin href="https://cdn.master.co/css-runtime@rc/default-manifest.json">
 <link rel="stylesheet" href="https://cdn.master.co/css@rc/base.css">
 <script src="https://cdn.master.co/css-runtime@rc"></script>
 ```
 
-The IIFE fetches `default-manifest.json` next to the runtime script, starts automatically, and registers the document runtime as `globalThis.masterCSSRuntime`. It does not read global options or custom manifests. Use ESM `CSSRuntime.create({ manifest, emittedGlobals }).observe()` for custom theme tokens, utilities, modes, emitted globals, or hydration inputs.
+The IIFE imports `default-manifest.json` next to the runtime script as a JSON module, starts automatically, and registers the document runtime as `globalThis.masterCSSRuntime`. The CDN must serve the manifest with `application/json`, and the browser must support JSON modules and import attributes. It does not read global options or custom manifests. Use ESM `CSSRuntime.create({ manifest, emittedGlobals }).observe()` for custom theme tokens, utilities, modes, emitted globals, or hydration inputs.
 
 ## API
 
@@ -110,17 +110,25 @@ cssRuntime.observe()
 | `cssRuntime.host` | `Element` | Root host, usually `root.host` or `document.documentElement`. |
 | `cssRuntime.container` | `HTMLElement \| ShadowRoot` | Container for `style#master-css`. |
 | `cssRuntime.observing` | `boolean` | `true` after `observe()`, `false` after `disconnect()`. |
+| `cssRuntime.classCounts` | `Map<string, number>` | Active DOM class usage counts. This is the source of truth for observed DOM usage. |
+| `cssRuntime.classUtilities` | `Map<string, Utility[]>` | Generated rule cache. It can include retained mutation rules that are no longer active in the DOM. |
+| `cssRuntime.retainedClassNames` | `Set<string>` | Mutation-removed class names whose generated rules are temporarily retained in CSSOM. |
 | `register()` | `this` | Registers this runtime in `CSSRuntime.instances`. |
 | `unregister()` | `this` | Removes this runtime from `CSSRuntime.instances`. |
 | `needsHydrationManifest()` | `boolean` | Returns `true` when an external hydration manifest should be loaded before observation. |
-| `loadHydrationManifest()` | `Promise<this>` | Reads inline hydration data or fetches the external hydration manifest URL from `style#master-css`. |
+| `loadHydrationManifest()` | `Promise<this>` | Reads inline hydration data or imports the external hydration manifest URL from `style#master-css`. |
 | `setHydrationManifest(manifest?)` | `this` | Sets the hydration manifest used by progressive hydration. |
 | `observe()` | `this` | Observes class attribute changes. |
+| `ensureClassRules(...classNames)` | `this` | Synchronously ensures generated rules exist for class names. Use this to warm rules before DOM insertion. |
+| `deleteClassRules(...classNames)` | `void` | Synchronously deletes generated rules for class names. |
+| `flushRetainedClassRules()` | `number` | Synchronously removes retained mutation rules that are no longer active and returns the removed class count. |
 | `disconnect()` | `this \| undefined` | Cancels observation. |
 | `refresh(manifest?)` | `this` | Refreshes with a complete `MasterCSSManifest`. |
 | `reset()` | `this` | Clears rules and styles. |
 | `destroy()` | `this` | Removes this runtime from `CSSRuntime.instances`. |
 
+MutationObserver additions update `classCounts` immediately. Existing and retained generated rules are reused immediately, while first-time rules discovered by the observer are batched into the next pre-paint flush. MutationObserver removals also update `classCounts` immediately, but generated CSS rules may be retained briefly to avoid CSSOM deletion during interaction-heavy updates. Re-adding a retained class reuses the existing generated rule. Direct `cssRuntime.ensureClassRules(...)`, `cssRuntime.deleteClassRules(...)`, `refresh()`, `disconnect()`, and `destroy()` stay synchronous.
+
 ### Progressive Hydration
 
 ```ts
@@ -143,4 +151,4 @@ cssRuntime.observe()
 ## Related docs
 
 - [General installation](https://rc.css.master.co/guide/installation)
-- [Using CDNs](https://rc.css.master.co/guide/installation/cdn)
+- [Runtime rendering](https://rc.css.master.co/guide/rendering-modes#runtime-rendering)

package/dist/core.d.ts

@@ -24,10 +24,16 @@ declare class CSSRuntime extends MasterCSS {
   readonly componentsLayer: RuntimeUtilityLayer;
   readonly utilitiesLayer: RuntimeUtilityLayer;
   readonly classCounts: Map<string, number>;
+  readonly retainedClassNames: Set<string>;
   private readonly classTracker;
+  private readonly pendingAddedClassNames;
   private readonly pendingRemovedClassNames;
+  private readonly retainedClassRules;
+  private pendingAdditionFrame;
   private pendingRemovalFrame;
   private pendingRemovalFlushFrame;
+  private retainedCleanupIdleHandle;
+  private retainedCleanupTimeoutHandle;
   private hydrationFailureReason?;
   observer?: MutationObserver;
   progressive: boolean;
@@ -48,14 +54,33 @@ declare class CSSRuntime extends MasterCSS {
   private renderRuntimeStyle;
   private getAnimationFrameWindow;
   private cancelPendingRemovalFrames;
+  private cancelPendingAdditionFrame;
+  private clearPendingAddedClassNames;
   private clearPendingRemovedClassNames;
+  private getCleanupWindow;
+  private cancelRetainedClassRuleCleanup;
+  private clearRetainedClassRules;
   private cancelPendingRemovedClassNames;
+  private cancelPendingAddedClassNames;
+  private cancelRetainedClassNames;
   private schedulePendingRemovalFlush;
   private queueRemovedClassNames;
+  private schedulePendingAdditionFlush;
+  private queueAddedClassNames;
+  private estimateRetainedClassRule;
+  private getRetainedClassRuleRawBytes;
+  private exceedsRetainedClassRuleHardLimits;
+  private scheduleRetainedClassRuleCleanup;
+  private retainRemovedClassRules;
+  private getRetainedClassRuleCleanupCandidates;
+  private removeRetainedClassRules;
+  private cleanupRetainedClassRules;
+  flushRetainedClassRules(): number;
   private flushPendingRemovedClassNames;
+  private flushPendingAddedClassNames;
   private handleMutationRecords;
-  add(...classNames: string[]): this;
-  remove(...classNames: string[]): void;
+  ensureClassRules(...classNames: string[]): this;
+  deleteClassRules(...classNames: string[]): void;
   private startMutationObserver;
   private revealHostIfNeeded;
   /**