Rendering Modes

Understand how the rendering modes of Master CSS work and enhance your website's performance.

It can be runtime, zero-runtime, or even hydration.

Overview

Official build integrations default to static. Choose an explicit mode when browser rule generation or server pre-rendering is needed. The same project CSS entry graph can be used by runtime rendering, static rendering, server rendering, and progressive hydration.

Every mode uses the same cascade layer model. The default @master/css/base.css stylesheet declares @layer theme, base, defaults, components, utilities;, while generated rules are emitted into layer blocks without redeclaring the global order.

Runtime and progressive rendering optimize what CSS is delivered up front. They do not make browser style calculation free: when a highly interactive screen creates many first-time utility rules during one interaction, the browser still needs to account for those new stylesheet rules before it can paint the updated DOM.

For page-level CSS size and delivery measurements, see the benchmarks.

Shared execution contract

Build-time generation, server rendering and browser generation use the same Rust semantics. Given the same manifest and classes, they must agree on declarations, conditions, resource dependencies and cascade behavior. Their HTML, transport and hydration metadata can differ.

Static rendering is the normal choice when complete class strings are available in application sources, including conditional alternatives. Runtime generation serves classes introduced after the build, such as CMS content or a visual editor. Progressive rendering adds that capability to server-rendered CSS without changing the styling language.

Manifest compatibility

The execution format is Manifest version: 1 with languageVersion: 3. These are separate from package versions and the internal native/Wasm binding ABI. Missing or unsupported execution versions are rejected; recompile project CSS with matching packages rather than changing the version fields by hand.

Use MasterCSSManifest and serializeMasterCSSManifest from @master/css-schema/manifest when storing a manifest. The codec normalizes derived fields such as default utility layers and order metadata. It is a serializer, not a replacement for engine validation. Reloading a supported manifest must preserve execution behavior, but its serialized bytes need not reproduce the compiler input.

The public contract covers executable definitions, variables, modes, variants and their meaningful order. It does not expose matcher indexes, caches or binding session state. A manifest is not a lossless CSS source document: comments, formatting and editable source structure require a separate authoring model.

Unknown fields are not a universal extension mechanism. The Rust manifest envelope retains unknown JSON fields, while typed nested contracts can reject them. Field retention does not mean an engine understands or executes a new capability.

Hydration data also carries versioned execution information. Use the server's hydration output with the matching runtime and project manifest; do not treat a manifest generated for another language version as compatible because its outer version is still 1.

Runtime Rendering

Master CSS Runtime relies on the lifecycle of individual elements. Only the Master CSS class names connected to the DOM tree will generate corresponding CSS rules so browsers can calculate with minimal and precise CSS rules.

The runtime engine uses the standard Web APIs - Mutation Observer to observe DOM class changes at runtime. It keeps active DOM usage, generated rule cache, and retained mutation rules as separate states so the browser does not need to delete and recreate CSS rules during every interaction.

It is packaged as @master/css-runtime. Most applications start it through a framework integration or a bundler entry:

import { MasterCSSRuntime } from '@master/css-runtime'import manifest from 'virtual:master-css-manifest'import emittedGlobals from 'virtual:master-css-emitted-globals'const cssRuntime = await MasterCSSRuntime.start({ manifest, emittedGlobals })cssRuntime.observe()

Direct browser delivery is also possible when a page is not bundled, but it is not the only runtime path:

<head>  <link rel="stylesheet" href="/assets/master-css-base.css">  <script type="module" src="/assets/master-css-runtime.js"></script></head>

The following continuous DOM manipulation takes you to understand the behavior of the CSS runtime when the browser is running:

const h1 = document.createElement('h1')h1.className = 'text-center'

<h1 class="text-center">Hello World</h1> 

.text-center {   text-align: center } 

h1.classList.add('font-6xl')

<h1 class="font-6xl text-center">Hello World</h1>

.font-6xl {   font-size: 3rem } .text-center {  text-align: center}

h1.classList.remove('text-center')

<h1 class="font-6xl text-center">Hello World</h1>

.font-6xl {  font-size: 3rem}.text-center {   text-align: center } 

h1.remove()

<h1 class="font-6xl">Hello World</h1> 

.font-6xl {   font-size: 3rem } 

Due to its runtime execution nature, you can modify the class name directly in the browser by inspecting the element and seeing its changes.

Running style sheet

Where are the generated CSS rules inserted? The runtime engine appends <style id="master-css"> in <head> during initialization:

<head>  <meta charset="utf-8">  <meta name="viewport" content="width=device-width, initial-scale=1">  <link rel="stylesheet" href="/assets/master-css-base.css">  <script type="module" src="/main.js"></script>  <style id="master-css"></style> </head>

It uses the .insertRule() and .deleteRule() methods of Web APIs - CSSStyleSheet to manipulate native CSS rules. The text content of style#master-css is not a reliable live view after the runtime starts; inspect the stylesheet object when you need to see the current CSSOM.

Still, you can detect the CSS rules in the current style sheet like this:

const sheet = document.querySelector('style[id="master-css"]').sheetconsole.log(sheet.cssRules)

When runtime code needs project tokens, modes, or component definitions, load the compiled runtime inputs from the integration. virtual:master-css-manifest resolves the canonical project-level manifest discovered from the CSS entry, and virtual:master-css-emitted-globals records variables and keyframes that the entry already emitted.

import { MasterCSSRuntime } from '@master/css-runtime'import manifest from 'virtual:master-css-manifest'import emittedGlobals from 'virtual:master-css-emitted-globals'const cssRuntime = await MasterCSSRuntime.start({ manifest, emittedGlobals })cssRuntime.observe()

The manifest tells the runtime how to interpret project-specific tokens, modes, components, utilities, and variants. The emittedGlobals object is narrower: it only records variables and keyframes that the build already emitted from the CSS entry output. Dynamic classes can still be generated later, but shared global CSS is not duplicated when those classes reference an already-loaded variable or animation.

Runtime state

Runtime rendering separates the question "is this class currently used by the DOM?" from "does the runtime already have generated CSS for this class?"

Call snapshot() when application or debugging code needs an immutable view of runtime state:

const snapshot = cssRuntime.snapshot()console.log(snapshot.usageCounts['btn'])console.log(snapshot.classRules['btn']?.retained)console.log(snapshot.classRules['btn']?.rules)

Direct runtime APIs are rule APIs, not DOM usage APIs. ensureClassRules(classNames) accepts an array and synchronously generates or reuses rules, so it is the explicit warming path before inserting a large dynamic view. deleteClassRules(classNames) accepts an array, synchronously removes generated rules, and bypasses retention. The MutationObserver path is more conservative: a removed DOM class disappears from snapshot().usageCounts immediately, while its generated rules can be retained and cleaned later outside the interaction window.

Interaction-heavy screens

Runtime and progressive rendering work best when the classes used during interaction are already generated, hydrated, retained, or warmed. A large interaction that inserts many elements with first-time class names still asks the browser to process DOM changes and new CSS rules in the same frame window.

For highly interactive UI such as editors, builders, data grids, virtualized lists, drag surfaces, or dashboards with many per-item values, prefer a mixed strategy:

• Keep stable layout, typography, state, and component classes in Master CSS.
• Warm predictable runtime classes with ensureClassRules(['grid', 'gap-md']) before inserting a large dynamic view.
• Use inline styles or CSS variables for volatile per-element values such as coordinates, dimensions, transforms, or user-generated colors.
• Use top-level native CSS or component-authored CSS for large repeated interaction states that are easier to model as selectors than as many runtime-generated utilities.

This does not change class syntax or cascade semantics. It is a delivery choice: avoid making the browser generate a large number of new utility rules during the same user interaction that mutates a large DOM subtree.

Project manifest delivery

virtual:master-css-manifest is the project-level runtime input. It represents the compiled CSS entry graph, so it can include project tokens, modes, component definitions, utility definitions, variants, and managed keyframes.

Next.js delivers this manifest as a standard ESM data module; its bundler manages chunks, caching and URLs. Other integrations can serve the manifest as an inline virtual module during development. In production runtime builds, official integrations may emit it as a hashed JSON asset and make the virtual module import that asset before the runtime starts. Runtime-only pages need this JSON before they can interpret classes, so integrations that inject the runtime can also add:

<link rel="modulepreload" as="json" crossorigin href="/assets/master-css-manifest.<hash>.json">

This does not change generated CSS or cascade order. It only moves discovery of the project manifest earlier so the runtime's later import can reuse the browser's preloaded module.

Progressive Rendering

Master CSS Progressive Rendering works by pre-rendering page CSS on the server or during a static build and injecting it into the page HTML. On the client, the CSS runtime hydrates these rules into a virtual stylesheet, initializing a lifecycle-aware system that can respond to class name changes in real time. Progressive hydration depends on two pieces of data: style#master-css contains the pre-rendered CSS that can paint the first screen, and the page hydration manifest describes the generated rules that style block contains.

Progressive outputs use a page hydration manifest to hand generated rules to the runtime. Static and pre-render modes do not require runtime engine, Wasm or a runtime manifest:

<style id="master-css" data-master-css-hydration-manifest="/_master-css/hydration/master-css-hydration.<hash>.json">...</style>

The /_master-css/hydration/ path above is the integration-neutral route. Framework adapters can place the same artifact under their own static asset namespace. In Next.js, @master/css-next uses:

<style id="master-css" data-master-css-hydration-manifest="/_next/static/master-css/hydration/master-css-hydration.<hash>.json">...</style>

This keeps the first-render CSS in the HTML while moving the runtime handoff data into a cacheable route-level JSON file. The browser can paint from style#master-css without waiting for the manifest request. When the runtime starts, it imports the manifest as a JSON module, adopts the existing native CSS rules, and continues observing dynamic classes. If a pre-rendered style has no manifest pointer, or a loaded manifest no longer matches style#master-css, the runtime warns and rebuilds the stylesheet from connected DOM classes. If an inline or external manifest is referenced but cannot be loaded or validated, startup rejects with INVALID_HYDRATION_MANIFEST so a broken deployment is not silently accepted.

After adoption, progressive rendering uses the same runtime state model as runtime rendering. Hydrated rules become runtime-managed rule objects, new classes can be generated later, and mutation-driven removals can enter the retained-rule cache before idle cleanup. This keeps the first paint deterministic while still avoiding repeated CSSOM insertion/deletion during interactive updates.

Inline script#master-css-hydration-manifest is still supported for compatibility and for dynamic SSR responses that cannot write a stable public JSON asset. Pages with no generated rules do not need a hydration manifest pointer.

Do not preload the page hydration manifest. It is different from the runtime project manifest: the browser already has the CSS needed for first paint in style#master-css, and the hydration manifest only tells the runtime how to adopt those existing rules.

Pre-rendering — SSG, SSR

For example, the following HTML:

<!DOCTYPE html><html lang="en"><head>  <meta charset="utf-8">  <meta name="viewport" content="width=device-width, initial-scale=1">  <script type="module" src="/main.js"></script></head><body>  <h1 class="font-5xl font-heavy">Hello World</h1></body>

Render the HTML:

import { readFileSync } from 'node:fs'import { createServerRenderer } from '@master/css-server'import manifest from 'virtual:master-css-manifest'const indexHTML = readFileSync('./index.html', 'utf-8')const renderer = createServerRenderer({ manifest, maxCachedClasses: Infinity })const { html } = renderer.renderHTML(indexHTML)renderer.dispose()

The manifest-scoped server renderer reuses generated class rules across pages while producing isolated CSS for each page. Recreate it when the manifest changes and dispose it when the build ends. Pre-render mode does not need a browser runtime or hydration manifest:

<!DOCTYPE html><html lang="en"><head>  <meta charset="utf-8">  <meta name="viewport" content="width=device-width, initial-scale=1">  <style id="master-css">     @layer theme { :root, :host { --font-size-5xl: 2.5rem } }     @layer utilities { .font-5xl { font-size: var(--font-size-5xl) } }   </style> </head><body>  <h1 class="font-5xl">Hello World</h1></body>

The server renderer generates page CSS from the class names present in rendered HTML. The amount of CSS depends on the page and project manifest.

Progressive mode adds a hydration manifest when the browser runtime must adopt that inline CSS and continue generating rules. Externalizing the manifest does not make first paint faster by itself; the first paint still comes from style#master-css.

CSS hydration

Master CSS hydration is the process that restores the server-side or build-time rendered CSS on the client. This includes reusing the pre-rendered CSS structures, persisting the application CSS state, and reconstructing the style sheet into virtual memory.

The runtime reads explicit hydrationManifest options first. Without an explicit option, MasterCSSRuntime.start() reads inline script#master-css-hydration-manifest or imports the URL from style#master-css[data-master-css-hydration-manifest] before it returns. Call runtime.observe() after startup completes.

Each manifest rule stores the class name, layer, priority, selector text, generated CSS text, and any referenced variables or animations. The server and client discover variables and animations in the manifest's sorted rule order, so DOM class order and warmed server caches produce the same resource buckets. The manifest's resourceOrder records that order for validation. During hydration, the runtime compares that IR with the native rules already present in style#master-css. When they match, it attaches those native CSS rules to runtime-managed rule objects instead of regenerating them.

Hydration also checks CSSOM rule counts and order, including theme buckets whose order affects the cascade. Missing, extra, duplicated, or reordered rules trigger a warning and rebuilding of style#master-css from the currently connected DOM classes.

Once hydrated, Master CSS can efficiently detect new or removed class names and update styles accordingly, without needing to reparse or regenerate previously defined rules. Classes that were not present in the initial HTML are still generated at runtime. Classes removed after hydration disappear from snapshot().usageCounts immediately; their generated rules may be retained briefly and removed later by idle cleanup.

The CSS runtime then takes over to detect any changes in dynamic class names.

This page hydration manifest is different from the project manifest and emittedGlobals. The project manifest tells the runtime how to interpret tokens, modes, components, utilities, and variants. emittedGlobals records variables and keyframes that the CSS entry already emitted. The page hydration manifest only describes the CSS rules that were generated into one rendered page.

Static Rendering

Static rendering is a zero-runtime rendering mode where the build scans source files, finds complete Master CSS class strings, validates them with the active engine manifest, and writes the resulting CSS before deployment.

The source scanner does not observe the DOM and does not execute application code. Its input is source text, CSS entries, scanner options, and the compiled project manifest. Its output is a CSS asset that the browser loads like any other stylesheet.

The CSS entry point is explicit: import @master/css from the stylesheet that should receive generated Master CSS. In static mode, integrations replace that import with generated CSS and preserve native CSS by default.

@import '@master/css';

<button class="btn text-center">Save</button>

@layer components {  .btn {    display: inline-flex;    padding-inline: var(--spacing-md);  }}

@layer components {  .btn {    display: inline-flex;    padding-inline: var(--spacing-md);  }}@layer utilities {  .text-center {    text-align: center;  }}

Generated stylesheet entry

In static mode, import the generated stylesheet from the stylesheet your framework already bundles.

@import '@master/css';

Use one @import '@master/css' entry for each generated stylesheet root. That import is also the insertion point for generated Master CSS, default base styles, theme variables, and utilities required by detected classes.

@import '@master/css' may be placed anywhere inside the top-level CSS import block. Ordinary CSS imports in that block are still emitted before generated Master CSS; keep the Master CSS import before normal style rules.

Native CSS entries

Regular CSS outside Master CSS directives remains native CSS. Integrations preserve it by default, including selectors whose classes do not appear in scanned source. Enable pruneNativeCSS: true for project-owned sources when pruning is intentional, or use @prune native; for one source file.

Those native rules can also pull matching theme variables referenced by var(--*) and managed @theme keyframes referenced by animation declarations. When integration-level pruning is enabled, @preserve native; excludes one source file.

@import '@master/css';.native-card {  border: 1px solid rgb(0 0 0 / 12%);}.unused-card {  color: red;}

<article class="btn native-card">Card</article>

By default, the generated CSS contains .native-card, .unused-card, and the on-demand .btn rule. With native pruning enabled, .unused-card is removed because no scanned source uses it.

Dynamic class limitations

Static rendering depends on complete class strings that exist in scanned source files. It cannot evaluate conditions, run helper functions, resolve remote content, or predict classes assembled by string concatenation.

Do not construct partial class names.

const className = 'bg:' + (error ? 'red': 'green')

Map states to complete class names.

const className = error ? 'bg-red' : 'bg-green'

Pass dynamic values through CSS variables while keeping the class static.

<div className="font-size:var(--size)@sm" style={{ '--size': size }}></div>

For the full source scanning model, see Scanning latent classes. For native CSS pruning, see Native CSS pruning.

Shared rendering pipeline

Rendering modes change delivery, not the authoring model. The source of truth is the project CSS entry graph. A stylesheet becomes part of that graph when it contains a top-level @master entry; marker or imports @master/css. Use @master entry; when the file only needs to declare manifest input, and use @import '@master/css' when the stylesheet should also receive generated CSS in static builds.

@import '@master/css';@theme {  --color-primary: #4f46e5;  --breakpoint-md: 48rem;  @keyframes fade-in {    from { opacity: 0; }    to { opacity: 1; }  }}@custom-variant motion-safe {  @media (prefers-reduced-motion: no-preference) {    @slot;  }}@layer components {  .btn {    display: inline-flex;    align-items: center;    border-radius: var(--radius-md);    padding-block: var(--spacing-xs);    padding-inline: var(--spacing-md);    background: var(--color-primary);  }}

These CSS-first directives are manifest inputs. The compiler lowers tokens, managed keyframes, settings, variants, utilities and native variant blocks into a MasterCSSManifest. Runtime rendering, static rendering, server rendering, language tooling, linting, and framework integrations all consume that same IR, so class syntax and cascade behavior stay consistent even when CSS is delivered differently.

Comparisons

This section provides a detailed comparison of different rendering modes. Each mode is evaluated based on various criteria such as application scenarios, performance, and generated source.

Engine state for custom hosts

The engine returned by createEngine() exposes a synchronous executionState(classNames) query for hosts that track generated rules. Ensure classes first, then request their stored rule references and the current resource state:

import { createEngine } from '@master/css'import manifest from 'virtual:master-css-manifest'using engine = await createEngine({ manifest })engine.ensureClassRules(['block', 'hidden'])const state = engine.executionState(['block', 'missing'])// state.classes[0].references: [{ layer: 'utilities', key: 'block' }]// state.classes[1].references: []// state.resources: current theme, variable and animation state

The result has the following readonly shape:

interface MasterCSSEngineExecutionState {  readonly classes: readonly {    readonly className: string    readonly references: readonly {      readonly layer: MasterCSSManifestUtilityLayerName      readonly key: string    }[]  }[]  readonly resources: MasterCSSEngineResources}

Classes follow the requested order, including repeated names. Unknown classes and valid classes that have never been ensured have empty references. The query reads stored references without generating rules or returning utility rule text. inspect() remains an independent rule inspection; it does not ensure a class. Use snapshot() when you need complete rules and CSS, including hydration data.

inspect(className) reports matchStatus, cssSyntaxStatus, cssValueStatus and browserSupport separately. Its optional diagnostics array includes codes, messages and, when available, notes about ambiguous tokens or invalid conditions. An inspection can recognize padding:red as declaration syntax while leaving its CSS value and browser support not-checked. Use the validator from @master/css-tooling for value validation; a matched rule alone is not a validation result. Inspection results are immutable and do not register classes with the engine.

A host must synchronize resource state even when a transition contains no CSS mutations. Theme updates are coalesced at the outermost engine batch: a changed theme produces at most one delete and one insert at the beginning of the transition. An unchanged theme produces neither. Utility and keyframe mutations retain their relative order and indexes. Manifest v1, hydration v1 and transition v1 keep their existing shapes.

Custom engine or binding implementations must add this query when upgrading to the current binding ABI 13.