@master/css-runtime 2.0.0-rc.8 → 2.0.0-rc.81

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 the 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">
@@ -48,17 +48,108 @@
             <img alt="Follow @mastercorg" src="https://img.shields.io/static/v1?label=%20&message=twitter&color=f6f7f8&logo=twitter&style=for-the-badge">
         </picture>
     </a>
-    <a aria-label="Github Actions" href="https://github.com/1aron/repo/actions/workflows/release.yml">
+    <a aria-label="Github Actions" href="https://github.com/master-co/css/actions/workflows/ci-release.yml">
         <picture>
-            <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/github/actions/workflow/status/master-co/css/release.yml?branch=rc&label=%20&message=twitter&color=212022&logo=githubactions&style=for-the-badge">
-            <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/github/actions/workflow/status/master-co/css/release.yml?branch=rc&label=%20&message=twitter&color=f6f7f8&logo=githubactions&style=for-the-badge&logoColor=%23000">
-            <img alt="Github release actions" src="https://img.shields.io/github/actions/workflow/status/master-co/css/release.yml?branch=rc&label=%20&message=twitter&color=f6f7f8&logo=githubactions&style=for-the-badge&logoColor=%23000">
+            <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/github/actions/workflow/status/master-co/css/ci-release.yml?branch=rc&label=%20&message=twitter&color=212022&logo=githubactions&style=for-the-badge">
+            <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/github/actions/workflow/status/master-co/css/ci-release.yml?branch=rc&label=%20&message=twitter&color=f6f7f8&logo=githubactions&style=for-the-badge&logoColor=%23000">
+            <img alt="Github release actions" src="https://img.shields.io/github/actions/workflow/status/master-co/css/ci-release.yml?branch=rc&label=%20&message=twitter&color=f6f7f8&logo=githubactions&style=for-the-badge&logoColor=%23000">
         </picture>
     </a>
 </p>
 
 </div>
 
-## Documentation
-- [General Installation](https://rc.css.master.co/docs/installation/general)
-- [Using CDNs](https://rc.css.master.co/docs/installation/cdn)
+## Installation
+
+```bash
+npm install @master/css-runtime
+```
+
+Initialize the runtime with the project manifest and emitted global CSS state provided by an official integration:
+
+```js
+import CSSRuntime from '@master/css-runtime'
+import manifest from 'virtual:master-css-manifest'
+import emittedGlobals from 'virtual:master-css-emitted-globals'
+
+CSSRuntime.create({ manifest, emittedGlobals }).observe()
+```
+
+## CDN IIFE
+
+Use the CDN runtime when a page only needs the default preset and zero configuration:
+
+```html
+<link rel="preload" as="style" href="https://cdn.master.co/css@rc/base.css">
+<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 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
+
+### `CSSRuntime`
+
+```ts
+import CSSRuntime from '@master/css-runtime'
+import manifest from 'virtual:master-css-manifest'
+
+const cssRuntime = CSSRuntime.create({ manifest })
+cssRuntime.observe()
+```
+
+`CSSRuntime` runs in the browser and extends the manifest-driven `MasterCSS` engine. Use `CSSRuntime.create({ manifest })` when the runtime should reuse an existing runtime for the same root.
+
+| API | Type | Description |
+| --- | --- | --- |
+| `CSSRuntime.instances` | `WeakMap<Document \| ShadowRoot, CSSRuntime>` | Runtime instances keyed by root. |
+| `CSSRuntime.create(options)` | `CSSRuntime` | Creates or reuses a registered runtime for `options.root`. |
+| `cssRuntime.root` | `Document \| ShadowRoot` | Observed root. |
+| `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 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
+import CSSRuntime from '@master/css-runtime'
+import manifest from 'virtual:master-css-manifest'
+import emittedGlobals from 'virtual:master-css-emitted-globals'
+
+const cssRuntime = CSSRuntime.create({
+    manifest,
+    emittedGlobals,
+})
+if (cssRuntime.needsHydrationManifest()) {
+    await cssRuntime.loadHydrationManifest()
+}
+cssRuntime.observe()
+```
+
+`emittedGlobals` tells the runtime which variables and keyframes were already emitted by the project CSS entry, so future dynamic classes can reuse them without inserting duplicate global CSS.
+
+## 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

@@ -0,0 +1,14 @@
+//#region src/class-tracker.d.ts
+type ClassDeltaMap = Map<string, number>;
+type ClassCountMap = Map<string, number>;
+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;
+}
+//#endregion
+export { RuntimeClassTracker as default };

package/dist/core.d.ts

@@ -1,23 +1,111 @@
-import { MasterCSS } from '@master/css';
-import type { Config } from '@master/css';
-import './types/global';
-export declare class CSSRuntime extends MasterCSS {
-    root: Document | ShadowRoot | undefined | null;
-    customConfig: Config;
-    readonly host: Element;
-    readonly observing = false;
-    readonly container: HTMLElement | ShadowRoot;
-    observer?: MutationObserver | null;
-    constructor(root?: Document | ShadowRoot | undefined | null, customConfig?: Config);
-    /**
-     * Observe the DOM for changes and update the running stylesheet. (browser only)
-     * @param options mutation observer options
-     * @returns this
-     */
-    observe(options?: MutationObserverInit): this;
-    refresh(customConfig?: Config): this;
-    reset(): this;
-    disconnect(): this;
-    destroy(): this;
+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 declare const cssRuntimes: CSSRuntime[];
+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

@@ -0,0 +1,20 @@
+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);
+interface CSSRuntimeOptions {
+  manifest: CSSRuntimeManifest;
+  root?: CSSRuntimeRoot;
+  emittedGlobals?: CSSRuntimeEmittedGlobals;
+  hydrationManifest?: CSSHydrationManifest;
+}
+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

@@ -0,0 +1,6 @@
+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

@@ -0,0 +1,7 @@
+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

@@ -0,0 +1,13 @@
+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

@@ -0,0 +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;
+};
+declare const log: ReturnType<typeof createLogger> & typeof loggers;
+//#endregion
+export { log as default };