@master/css-runtime 2.0.0-rc.73 → 2.0.0-rc.75

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) Aoyue Design LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

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/class-tracker.d.ts

@@ -1,12 +1,14 @@
+//#region src/class-tracker.d.ts
 type ClassDeltaMap = Map<string, number>;
 type ClassCountMap = Map<string, number>;
-export default class RuntimeClassTracker {
-    private snapshots;
-    reset(): void;
-    collectConnected(root: Document | ShadowRoot, classCounts: ClassCountMap): Set<string>;
-    collectMutations(records: MutationRecord[]): ClassDeltaMap;
-    private snapshotElement;
-    private diffElement;
-    private removeElement;
+declare class RuntimeClassTracker {
+  private snapshots;
+  reset(): void;
+  collectConnected(root: Document | ShadowRoot, classCounts: ClassCountMap): Set<string>;
+  collectMutations(records: MutationRecord[]): ClassDeltaMap;
+  private snapshotElement;
+  private diffElement;
+  private removeElement;
 }
-export {};
+//#endregion
+export { RuntimeClassTracker as default };

package/dist/core.d.ts

@@ -1,71 +1,111 @@
-import { MasterCSS } from '@master/css-engine';
-import type { MasterCSSManifest } from '@master/css-schema/manifest';
-import type { MasterCSSEmittedGlobals } from '@master/css-engine';
-import { type MasterCSSHydrationManifest } from '@master/css-schema/hydration-manifest';
-import { HydrateResult } from './types';
-import RuntimeUtilityLayer from './utility-layer';
-import RuntimeThemeLayer from './theme-layer';
-export interface CSSRuntimeCreateOptions {
-    manifest: MasterCSSManifest;
-    root?: Document | ShadowRoot;
-    emittedGlobals?: MasterCSSEmittedGlobals;
-    hydrationManifest?: MasterCSSHydrationManifest;
+import RuntimeUtilityLayer from "./utility-layer.js";
+import { HydrateResult } from "./types/hydrate-result.js";
+import RuntimeThemeLayer from "./theme-layer.js";
+import { MasterCSS, MasterCSSEmittedGlobals } from "@master/css-engine";
+import { MasterCSSManifest } from "@master/css-schema/manifest";
+import { MasterCSSHydrationManifest } from "@master/css-schema/hydration-manifest";
+
+//#region src/core.d.ts
+interface CSSRuntimeCreateOptions {
+  manifest: MasterCSSManifest;
+  root?: Document | ShadowRoot;
+  emittedGlobals?: MasterCSSEmittedGlobals;
+  hydrationManifest?: MasterCSSHydrationManifest;
 }
-export default class CSSRuntime extends MasterCSS {
-    root: Document | ShadowRoot;
-    hydrationManifest?: MasterCSSHydrationManifest | undefined;
-    static instances: WeakMap<Document | ShadowRoot, CSSRuntime>;
-    readonly host: Element;
-    readonly container: HTMLElement | ShadowRoot;
-    readonly baseLayer: RuntimeUtilityLayer;
-    readonly themeLayer: RuntimeThemeLayer;
-    readonly defaultsLayer: RuntimeUtilityLayer;
-    readonly componentsLayer: RuntimeUtilityLayer;
-    readonly utilitiesLayer: RuntimeUtilityLayer;
-    readonly classCounts: Map<string, number>;
-    private readonly classTracker;
-    private hydrationFailureReason?;
-    observer?: MutationObserver;
-    progressive: boolean;
-    observing: boolean;
-    static create(options: CSSRuntimeCreateOptions): CSSRuntime;
-    constructor(root: (Document | ShadowRoot) | undefined, manifest: MasterCSSManifest, emittedGlobals?: MasterCSSEmittedGlobals, hydrationManifest?: MasterCSSHydrationManifest | undefined);
-    register(): this;
-    unregister(): this;
-    setHydrationManifest(hydrationManifest?: MasterCSSHydrationManifest): this;
-    needsHydrationManifest(): boolean;
-    loadHydrationManifest(): Promise<this>;
-    private createRuntimeStyle;
-    private warnHydrationFallback;
-    private useRuntimeStyle;
-    private detectRuntimeStyle;
-    private collectConnectedClasses;
-    private hydrateRuntimeStyle;
-    private renderRuntimeStyle;
-    private handleMutationRecords;
-    private startMutationObserver;
-    private revealHostIfNeeded;
-    /**
-     * Observe the DOM for changes and update the running stylesheet. (browser only)
-     * @param options mutation observer options
-     * @returns this
-     */
-    observe(): this;
-    private failHydration;
-    private getHydrationManifestLayerRules;
-    private registerHydratedClassRule;
-    private getUtilityLayerByName;
-    private collectHydrationManifestVariableNames;
-    private collectHydrationManifestAnimationNames;
-    private nativeThemeLayerHasOnlyEmittedGlobalsVariables;
-    private getVariableRuleBuckets;
-    private isSyntheticColorSchemeDeclaration;
-    private getNativeThemeRuleBucketKey;
-    private hydrateHydrationManifestVariables;
-    private hydrateHydrationManifestAnimations;
-    private hydrateHydrationManifestLayer;
-    hydrate(nativeLayerRules: CSSRuleList): HydrateResult | undefined;
-    disconnect(): this | undefined;
-    refresh(manifest?: MasterCSSManifest): this;
-    destroy(): this;
+declare class CSSRuntime extends MasterCSS {
+  root: Document | ShadowRoot;
+  hydrationManifest?: MasterCSSHydrationManifest | undefined;
+  static instances: WeakMap<Document | ShadowRoot, CSSRuntime>;
+  readonly host: Element;
+  readonly container: HTMLElement | ShadowRoot;
+  readonly baseLayer: RuntimeUtilityLayer;
+  readonly themeLayer: RuntimeThemeLayer;
+  readonly defaultsLayer: RuntimeUtilityLayer;
+  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;
+  observing: boolean;
+  static create(options: CSSRuntimeCreateOptions): CSSRuntime;
+  constructor(root: (Document | ShadowRoot) | undefined, manifest: MasterCSSManifest, emittedGlobals?: MasterCSSEmittedGlobals, hydrationManifest?: MasterCSSHydrationManifest | undefined);
+  register(): this;
+  unregister(): this;
+  setHydrationManifest(hydrationManifest?: MasterCSSHydrationManifest): this;
+  needsHydrationManifest(): boolean;
+  loadHydrationManifest(): Promise<this>;
+  private createRuntimeStyle;
+  private warnHydrationFallback;
+  private useRuntimeStyle;
+  private detectRuntimeStyle;
+  private collectConnectedClasses;
+  private hydrateRuntimeStyle;
+  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;
+  ensureClassRules(...classNames: string[]): this;
+  deleteClassRules(...classNames: string[]): void;
+  private startMutationObserver;
+  private revealHostIfNeeded;
+  /**
+   * Observe the DOM for changes and update the running stylesheet. (browser only)
+   * @param options mutation observer options
+   * @returns this
+   */
+  observe(): this;
+  private failHydration;
+  private getHydrationManifestLayerRules;
+  private registerHydratedClassRule;
+  private getUtilityLayerByName;
+  private collectHydrationManifestVariableNames;
+  private collectHydrationManifestAnimationNames;
+  private nativeThemeLayerHasOnlyEmittedGlobalsVariables;
+  private getVariableRuleBuckets;
+  private isSyntheticColorSchemeDeclaration;
+  private getNativeThemeRuleBucketKey;
+  private hydrateHydrationManifestVariables;
+  private hydrateHydrationManifestAnimations;
+  private hydrateHydrationManifestLayer;
+  hydrate(nativeLayerRules: CSSRuleList): HydrateResult | undefined;
+  disconnect(): this | undefined;
+  refresh(manifest?: MasterCSSManifest): this;
+  destroy(): this;
 }
+//#endregion
+export { CSSRuntimeCreateOptions, CSSRuntime as default };

package/dist/css-runtime.d.ts

@@ -1,17 +1,20 @@
-import type { MasterCSSManifest } from '@master/css-schema/manifest';
-import type { MasterCSSEmittedGlobals } from '@master/css-engine';
-import type { MasterCSSHydrationManifest } from '@master/css-schema/hydration-manifest';
+import { MasterCSSEmittedGlobals } from "@master/css-engine";
+import { MasterCSSManifest } from "@master/css-schema/manifest";
+import { MasterCSSHydrationManifest } from "@master/css-schema/hydration-manifest";
+
+//#region src/css-runtime.d.ts
 type CSSRuntimeHostConstructor = new (...args: any[]) => HTMLElement;
 type CSSRuntimeManifest = MasterCSSManifest | ((host: HTMLElement) => MasterCSSManifest);
 type CSSRuntimeRoot = ShadowRoot | ((host: HTMLElement) => ShadowRoot | null | undefined);
 type CSSRuntimeEmittedGlobals = MasterCSSEmittedGlobals | ((host: HTMLElement) => MasterCSSEmittedGlobals | undefined);
 type CSSHydrationManifest = MasterCSSHydrationManifest | ((host: HTMLElement) => MasterCSSHydrationManifest | undefined);
-export interface CSSRuntimeOptions {
-    manifest: CSSRuntimeManifest;
-    root?: CSSRuntimeRoot;
-    emittedGlobals?: CSSRuntimeEmittedGlobals;
-    hydrationManifest?: CSSHydrationManifest;
+interface CSSRuntimeOptions {
+  manifest: CSSRuntimeManifest;
+  root?: CSSRuntimeRoot;
+  emittedGlobals?: CSSRuntimeEmittedGlobals;
+  hydrationManifest?: CSSHydrationManifest;
 }
-export type CSSRuntimeDecoratorOptions = CSSRuntimeOptions;
-export default function cssRuntime(options: CSSRuntimeOptions): <T extends CSSRuntimeHostConstructor>(target: T) => T;
-export {};
+type CSSRuntimeDecoratorOptions = CSSRuntimeOptions;
+declare function cssRuntime(options: CSSRuntimeOptions): <T extends CSSRuntimeHostConstructor>(target: T) => T;
+//#endregion
+export { CSSRuntimeDecoratorOptions, CSSRuntimeOptions, cssRuntime as default };

package/dist/debuggers/class-count.d.ts

@@ -1,2 +1,6 @@
-import type CSSRuntime from '../core';
-export default function debugRuntimeMutation(records: MutationRecord[], classCounts: Map<string, number>, cssRuntime: CSSRuntime): void;
+import CSSRuntime from "../core.js";
+
+//#region src/debuggers/class-count.d.ts
+declare function debugRuntimeMutation(records: MutationRecord[], classCounts: Map<string, number>, cssRuntime: CSSRuntime): void;
+//#endregion
+export { debugRuntimeMutation as default };

package/dist/debuggers/index.d.ts

@@ -1,3 +1,7 @@
-export { default as debugRuntimeMutation } from './class-count';
-export { debugRuntimeCreated, debugRuntimeDestroyed, debugRuntimeDisconnected, debugRuntimeHydrated, debugRuntimeObserved, debugRuntimeRefreshed } from './lifecycle';
-export default function startDebuggers(): void;
+import debugRuntimeMutation from "./class-count.js";
+import { debugRuntimeCreated, debugRuntimeDestroyed, debugRuntimeDisconnected, debugRuntimeHydrated, debugRuntimeObserved, debugRuntimeRefreshed } from "./lifecycle.js";
+
+//#region src/debuggers/index.d.ts
+declare function startDebuggers(): void;
+//#endregion
+export { debugRuntimeCreated, debugRuntimeDestroyed, debugRuntimeDisconnected, debugRuntimeHydrated, debugRuntimeMutation, debugRuntimeObserved, debugRuntimeRefreshed, startDebuggers as default };

package/dist/debuggers/lifecycle.d.ts

@@ -1,9 +1,13 @@
-import type CSSRuntime from '../core';
-import type { MasterCSSManifest } from '@master/css-schema/manifest';
-import type { HydrateResult } from '../types';
-export declare function debugRuntimeCreated(cssRuntime: CSSRuntime): void;
-export declare function debugRuntimeHydrated(cssRuntime: CSSRuntime, result: HydrateResult): void;
-export declare function debugRuntimeObserved(cssRuntime: CSSRuntime): void;
-export declare function debugRuntimeRefreshed(cssRuntime: CSSRuntime, manifest: MasterCSSManifest): void;
-export declare function debugRuntimeDisconnected(cssRuntime: CSSRuntime): void;
-export declare function debugRuntimeDestroyed(cssRuntime: CSSRuntime): void;
+import { HydrateResult } from "../types/hydrate-result.js";
+import CSSRuntime from "../core.js";
+import { MasterCSSManifest } from "@master/css-schema/manifest";
+
+//#region src/debuggers/lifecycle.d.ts
+declare function debugRuntimeCreated(cssRuntime: CSSRuntime): void;
+declare function debugRuntimeHydrated(cssRuntime: CSSRuntime, result: HydrateResult): void;
+declare function debugRuntimeObserved(cssRuntime: CSSRuntime): void;
+declare function debugRuntimeRefreshed(cssRuntime: CSSRuntime, manifest: MasterCSSManifest): void;
+declare function debugRuntimeDisconnected(cssRuntime: CSSRuntime): void;
+declare function debugRuntimeDestroyed(cssRuntime: CSSRuntime): void;
+//#endregion
+export { debugRuntimeCreated, debugRuntimeDestroyed, debugRuntimeDisconnected, debugRuntimeHydrated, debugRuntimeObserved, debugRuntimeRefreshed };

package/dist/debuggers/log.d.ts

@@ -1,17 +1,19 @@
+//#region src/debuggers/log.d.ts
 type ConsoleMethod = 'log' | 'debug' | 'info' | 'warn' | 'error' | 'trace' | 'table' | 'group' | 'groupCollapsed' | 'groupEnd' | 'time' | 'timeEnd';
 declare const createLogger: (type?: Exclude<ConsoleMethod, "table" | "group" | "groupCollapsed" | "groupEnd" | "time" | "timeEnd">) => (message: string, ...args: unknown[]) => void;
 declare const loggers: {
-    info: (message: string, ...args: unknown[]) => void;
-    debug: (message: string, ...args: unknown[]) => void;
-    warn: (...data: any[]) => void;
-    error: (...data: any[]) => void;
-    trace: (...data: any[]) => void;
-    table: (tabularData?: any, properties?: string[]) => void;
-    group: (...data: any[]) => void;
-    groupCollapsed: (...data: any[]) => void;
-    groupEnd: () => void;
-    time: (label?: string) => void;
-    timeEnd: (label?: string) => void;
+  info: (message: string, ...args: unknown[]) => void;
+  debug: (message: string, ...args: unknown[]) => void;
+  warn: (...data: any[]) => void;
+  error: (...data: any[]) => void;
+  trace: (...data: any[]) => void;
+  table: (tabularData?: any, properties?: string[]) => void;
+  group: (...data: any[]) => void;
+  groupCollapsed: (...data: any[]) => void;
+  groupEnd: () => void;
+  time: (label?: string) => void;
+  timeEnd: (label?: string) => void;
 };
 declare const log: ReturnType<typeof createLogger> & typeof loggers;
-export default log;
+//#endregion
+export { log as default };