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

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">Run Master CSS right in the browser</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,99 @@
             <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="preload" as="fetch" type="application/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.
+
+## 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()`. |
+| `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`. |
+| `setHydrationManifest(manifest?)` | `this` | Sets the hydration manifest used by progressive hydration. |
+| `observe()` | `this` | Observes class attribute changes. |
+| `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`. |
+
+### 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)

package/dist/class-tracker.d.ts

@@ -0,0 +1,12 @@
+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;
+}
+export {};

package/dist/core.d.ts

@@ -1,23 +1,70 @@
-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;
+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;
+}
+export default class CSSRuntime extends MasterCSS {
+    root: Document | ShadowRoot;
+    hydrationManifest?: MasterCSSHydrationManifest | undefined;
+    static instances: WeakMap<Document | ShadowRoot, CSSRuntime>;
     readonly host: Element;
-    readonly observing = false;
     readonly container: HTMLElement | ShadowRoot;
-    observer?: MutationObserver | null;
-    constructor(root?: Document | ShadowRoot | undefined | null, customConfig?: Config);
+    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(options?: MutationObserverInit): this;
-    refresh(customConfig?: Config): this;
-    reset(): this;
-    disconnect(): this;
+    observe(): this;
+    private failHydration;
+    private getHydrationManifestLayerRules;
+    private registerHydratedClassRule;
+    private getUtilityLayerByName;
+    private collectHydrationManifestVariableNames;
+    private collectHydrationManifestAnimationNames;
+    private nativeThemeLayerHasOnlyEmittedGlobalsVariables;
+    private getVariableRuleBuckets;
+    private getNativeThemeRuleBucketKey;
+    private hydrateHydrationManifestVariables;
+    private hydrateHydrationManifestAnimations;
+    private hydrateHydrationManifestLayer;
+    hydrate(nativeLayerRules: CSSRuleList): HydrateResult | undefined;
+    disconnect(): this | undefined;
+    refresh(manifest?: MasterCSSManifest): this;
     destroy(): this;
 }
-export declare const cssRuntimes: CSSRuntime[];

package/dist/css-runtime.d.ts

@@ -0,0 +1,17 @@
+import type { MasterCSSManifest } from '@master/css-schema/manifest';
+import type { MasterCSSEmittedGlobals } from '@master/css-engine';
+import type { MasterCSSHydrationManifest } from '@master/css-schema/hydration-manifest';
+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;
+}
+export type CSSRuntimeDecoratorOptions = CSSRuntimeOptions;
+export default function cssRuntime(options: CSSRuntimeOptions): <T extends CSSRuntimeHostConstructor>(target: T) => T;
+export {};

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

@@ -0,0 +1 @@
+export default function registerClassCountDebugger(): void;

package/dist/debuggers/index.d.ts

@@ -0,0 +1 @@
+export default function startDebuggers(): void;

package/dist/debuggers/lifecycle.d.ts

@@ -0,0 +1 @@
+export default function registerLifecycleDebugger(): void;

package/dist/debuggers/log.d.ts

@@ -0,0 +1,17 @@
+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;
+export default log;