@master/css-server 0.0.0-site.1793659883.g69c9aebcf628

package/README.md

@@ -0,0 +1,118 @@
+<br>
+<div align="center">
+
+<p align="center">
+  <a href="https://css.master.co">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/33840671/201701649-3bb7d698-abec-4d5f-ac30-ccc4d7bafcd4.svg">
+      <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/33840671/201703010-77bf2373-9899-40cc-98f5-30cf9b546941.svg">
+      <img alt="Master CSS" src="https://user-images.githubusercontent.com/33840671/201703010-77bf2373-9899-40cc-98f5-30cf9b546941.svg" width="100%">
+    </picture>
+  </a>
+</p>
+<p align="center">Server-side HTML renderer 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">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/github/v/release/master-co/css?include_prereleases&color=212022&label=&style=for-the-badge&logo=github&logoColor=fff">
+      <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/github/v/release/master-co/css?include_prereleases&color=f6f7f8&label=&style=for-the-badge&logo=github&logoColor=%23000">
+      <img alt="NPM Version" src="https://img.shields.io/github/v/release/master-co/css?include_prereleases&color=f6f7f8&label=&style=for-the-badge&logo=github">
+    </picture>
+  </a>
+  <a aria-label="NPM Package" href="https://www.npmjs.com/package/@master/css-server">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/npm/dm/@master/css-server?color=212022&label=%20&logo=npm&style=for-the-badge">
+      <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/npm/dm/@master/css-server?color=f6f7f8&label=%20&logo=npm&style=for-the-badge">
+      <img alt="NPM package ( download / month )" src="https://img.shields.io/npm/dm/@master/css-server?color=f6f7f8&label=%20&logo=npm&style=for-the-badge">
+    </picture>
+  </a>
+  <a aria-label="Discord Community" href="https://discord.gg/sZNKpAAAw6">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/discord/917780624314613760?color=212022&label=%20&logo=discord&style=for-the-badge">
+      <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/discord/917780624314613760?color=f6f7f8&label=%20&logo=discord&style=for-the-badge">
+      <img alt="Discord online" src="https://img.shields.io/discord/917780624314613760?color=f6f7f8&label=%20&logo=discord&style=for-the-badge">
+    </picture>
+  </a>
+  <a aria-label="Follow @mastercorg" href="https://twitter.com/mastercorg">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/static/v1?label=%20&message=twitter&color=212022&logo=twitter&style=for-the-badge">
+      <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/static/v1?label=%20&message=twitter&color=f6f7f8&logo=twitter&style=for-the-badge">
+      <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/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/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>
+
+## Installation
+
+```bash
+npm install @master/css-server
+```
+
+`@master/css-server` owns HTML parsing and style/hydration injection. Every entry
+requires an explicit `MasterCSSManifest`; class-only rendering belongs to
+`@master/css/node`.
+
+## API
+
+### `renderHTML()`
+
+The one-shot API owns and releases its render session. Its result is an immutable
+snapshot and does not expose DOM nodes, bindings, or disposable CSS state.
+
+```ts
+import { renderHTML } from '@master/css-server'
+
+const result = renderHTML('<div class="text-center"></div>', {
+  manifest,
+  hydrationManifest: 'inline'
+})
+
+console.log(result.html)
+console.log(result.cssText)
+console.log(result.classNames)
+console.log(result.diagnostics)
+```
+
+### `createServerRenderer()`
+
+Create a manifest-scoped renderer when one process renders multiple documents.
+Generated rules are cached across calls while every call returns an independent
+snapshot.
+
+```ts
+import { createServerRenderer } from '@master/css-server'
+
+const renderer = createServerRenderer({ manifest })
+const first = renderer.renderHTML('<div class="text-center"></div>')
+const second = renderer.renderHTML('<div class="fg-red"></div>')
+
+renderer.dispose()
+```
+
+Long-lived renderers cache up to 8192 unique classes before starting a new cache generation. Finite build jobs can pass `{ maxCachedClasses: Infinity }` and dispose the renderer when the build ends. Recreate the renderer whenever its manifest changes.
+
+### `createHTMLRenderSession()`
+
+Use one session per streaming document. `write()` accepts successive chunks and
+`end()` returns the final transformed chunk plus the complete immutable snapshot.
+The session owns its renderer and releases it after `end()`, failure, or `dispose()`.
+
+```ts
+import { createHTMLRenderSession } from '@master/css-server'
+
+const session = createHTMLRenderSession({ manifest })
+const firstChunk = session.write('<html><head>')
+const final = session.end('</head><body class="block"></body></html>')
+```
+
+Use official framework integrations when possible; they compose this package with manifest loading, source scanning, and runtime hydration.

package/dist/create-server-renderer.d.ts

@@ -0,0 +1,23 @@
+import { MasterCSSRenderSessionOptions } from "@master/css/node";
+import { MasterCSSHTMLDocumentOptions, MasterCSSHTMLRenderResult } from "./render.js";
+interface MasterCSSServerRendererOptions extends MasterCSSRenderSessionOptions {
+  readonly maxCachedClasses?: number;
+}
+declare class MasterCSSServerRenderer implements Disposable {
+  private readonly options;
+  readonly maxCachedClasses: number;
+  private readonly cachedClassNames;
+  private renderSession;
+  private disposed;
+  private constructor();
+  renderHTML(html: string, options?: MasterCSSHTMLDocumentOptions): MasterCSSHTMLRenderResult;
+  createHTMLRenderSession(options?: MasterCSSHTMLDocumentOptions): import("./html-render-session.js").MasterCSSHTMLRenderSession;
+  dispose(): void;
+  [Symbol.dispose](): void;
+  private renderClassNames;
+  private renderOptions;
+  private createRenderSession;
+  private assertActive;
+}
+declare function createServerRenderer(options: MasterCSSServerRendererOptions): MasterCSSServerRenderer;
+export { MasterCSSServerRenderer, MasterCSSServerRendererOptions, createServerRenderer };

package/dist/create-server-renderer.js

@@ -0,0 +1,86 @@
+import { bindHTMLRenderSessionInternal } from "./html-render-session.js";
+import parseHTML from "./parse-html.js";
+import { collectNativeStylesheets } from "./native-stylesheets.js";
+import { renderHTMLWithSnapshot } from "./render.js";
+import { createRenderSessionSync, renderClassNamesSync } from "@master/css/node";
+import { MasterCSSError } from "@master/css-schema";
+// src/create-server-renderer.ts
+const DEFAULT_MAX_CACHED_CLASSES = 8192;
+let bindServerRenderer;
+var MasterCSSServerRenderer = class MasterCSSServerRenderer {
+	options;
+	maxCachedClasses;
+	cachedClassNames = /* @__PURE__ */ new Set();
+	renderSession;
+	disposed = false;
+	constructor(options) {
+		this.options = options;
+		this.maxCachedClasses = options.maxCachedClasses ?? DEFAULT_MAX_CACHED_CLASSES;
+		if (this.maxCachedClasses !== Infinity && (!Number.isInteger(this.maxCachedClasses) || this.maxCachedClasses <= 0)) throw new TypeError("maxCachedClasses must be a positive integer or Infinity.");
+		this.renderSession = this.createRenderSession();
+	}
+	renderHTML(html, options = {}) {
+		this.assertActive();
+		const document = parseHTML(html);
+		const native = collectNativeStylesheets(document, options.stylesheets, options.documentURL);
+		if (native.length) {
+			using session = this.createRenderSession();
+			for (const css of native) session.ensureStylesheetResources(css);
+			session.ensureClassRules(document.classes);
+			return renderHTMLWithSnapshot(html, document, session.snapshot(), options);
+		}
+		const snapshot = this.renderClassNames(document.classes);
+		return renderHTMLWithSnapshot(html, document, snapshot, options);
+	}
+	createHTMLRenderSession(options = {}) {
+		this.assertActive();
+		return bindHTMLRenderSessionInternal(this, options);
+	}
+	dispose() {
+		if (this.disposed) return;
+		this.renderSession.dispose();
+		this.cachedClassNames.clear();
+		this.disposed = true;
+	}
+	[Symbol.dispose]() {
+		this.dispose();
+	}
+	renderClassNames(classNames) {
+		const classes = [...new Set(classNames.filter(Boolean))];
+		if (classes.length > this.maxCachedClasses) return renderClassNamesSync(classes, this.renderOptions());
+		const newClassNames = classes.filter((className) => !this.cachedClassNames.has(className));
+		let classesToEnsure = newClassNames;
+		if (this.cachedClassNames.size + newClassNames.length > this.maxCachedClasses) {
+			this.renderSession.dispose();
+			this.renderSession = this.createRenderSession();
+			this.cachedClassNames.clear();
+			classesToEnsure = classes;
+		}
+		if (classesToEnsure.length) this.renderSession.ensureClassRules(classesToEnsure);
+		for (const className of classes) this.cachedClassNames.add(className);
+		return this.renderSession.snapshotForClassNames(classes);
+	}
+	renderOptions() {
+		return {
+			manifest: this.options.manifest,
+			emittedGlobals: this.options.emittedGlobals
+		};
+	}
+	createRenderSession() {
+		return createRenderSessionSync(this.renderOptions());
+	}
+	assertActive() {
+		if (this.disposed) throw new MasterCSSError({
+			code: "SESSION_DISPOSED",
+			domain: "server",
+			message: "The Master CSS server renderer has been disposed."
+		});
+	}
+	static {
+		bindServerRenderer = (options) => new MasterCSSServerRenderer(options);
+	}
+};
+function createServerRenderer(options) {
+	return bindServerRenderer(options);
+}
+export { MasterCSSServerRenderer, createServerRenderer };

package/dist/decode-html.d.ts

@@ -0,0 +1,3 @@
+/** Decode as an HTML attribute while preserving the document's original markup. */
+declare function decodeHTML(html: string): string;
+export { decodeHTML as default };

package/dist/decode-html.js

@@ -0,0 +1,12 @@
+import { Parser } from "htmlparser2";
+// src/decode-html.ts
+/** Decode as an HTML attribute while preserving the document's original markup. */
+function decodeHTML(html) {
+	if (!html.includes("&")) return html;
+	let decoded = html;
+	new Parser({ onattribute(name, value) {
+		if (name === "class") decoded = value;
+	} }, { decodeEntities: true }).end(`<span class="${html.replaceAll("\"", "&quot;")}">`);
+	return decoded;
+}
+export { decodeHTML as default };

package/dist/html-render-session.d.ts

@@ -0,0 +1,18 @@
+import { MasterCSSHTMLDocumentOptions, MasterCSSHTMLRenderResult } from "./render.js";
+import { MasterCSSServerRenderer } from "./create-server-renderer.js";
+interface MasterCSSHTMLStreamEndResult {
+  readonly chunk: string;
+  readonly result: MasterCSSHTMLRenderResult;
+}
+declare class MasterCSSHTMLRenderSession implements Disposable {
+  #private;
+  private constructor();
+  write(chunk: string): string;
+  end(finalChunk?: string): MasterCSSHTMLStreamEndResult;
+  dispose(): void;
+  [Symbol.dispose](): void;
+  private assertWritable;
+}
+/** @internal */
+declare function bindHTMLRenderSessionInternal(renderer: MasterCSSServerRenderer, options: MasterCSSHTMLDocumentOptions, ownsRenderer?: boolean): MasterCSSHTMLRenderSession;
+export { MasterCSSHTMLRenderSession, MasterCSSHTMLStreamEndResult, bindHTMLRenderSessionInternal };

package/dist/html-render-session.js

@@ -0,0 +1,71 @@
+import { MasterCSSError } from "@master/css-schema";
+// src/html-render-session.ts
+let bindHTMLRenderSession;
+var MasterCSSHTMLRenderSession = class MasterCSSHTMLRenderSession {
+	#sourceHTML = "";
+	#emittedPrefix = "";
+	#ended = false;
+	#renderer;
+	#options;
+	#ownsRenderer = false;
+	constructor() {}
+	write(chunk) {
+		this.assertWritable();
+		this.#sourceHTML += chunk;
+		if (this.#emittedPrefix) return "";
+		const prefix = this.#sourceHTML.match(/^(?:(?:<!doctype html>|<!DOCTYPE html>)\s*)?<html>\s*<head>/)?.[0];
+		if (!prefix) return "";
+		this.#emittedPrefix = prefix;
+		return prefix;
+	}
+	end(finalChunk = "") {
+		this.assertWritable();
+		const finalPrefix = finalChunk ? this.write(finalChunk) : "";
+		try {
+			const result = this.#renderer.renderHTML(this.#sourceHTML, this.#options);
+			if (this.#emittedPrefix && !result.html.startsWith(this.#emittedPrefix)) throw new MasterCSSError({
+				code: "STREAM_PREFIX_MISMATCH",
+				domain: "server",
+				message: "The rendered document no longer matches the emitted HTML stream prefix."
+			});
+			const chunk = finalPrefix + result.html.slice(this.#emittedPrefix.length);
+			return Object.freeze({
+				chunk,
+				result
+			});
+		} finally {
+			this.dispose();
+		}
+	}
+	dispose() {
+		if (this.#ended) return;
+		this.#sourceHTML = "";
+		this.#emittedPrefix = "";
+		this.#ended = true;
+		if (this.#ownsRenderer) this.#renderer.dispose();
+	}
+	[Symbol.dispose]() {
+		this.dispose();
+	}
+	assertWritable() {
+		if (this.#ended) throw new MasterCSSError({
+			code: "SESSION_DISPOSED",
+			domain: "server",
+			message: "The Master CSS HTML render session has ended."
+		});
+	}
+	static {
+		bindHTMLRenderSession = (renderer, options, ownsRenderer) => {
+			const session = new MasterCSSHTMLRenderSession();
+			session.#renderer = renderer;
+			session.#options = options;
+			session.#ownsRenderer = ownsRenderer;
+			return session;
+		};
+	}
+};
+/** @internal */
+function bindHTMLRenderSessionInternal(renderer, options, ownsRenderer = false) {
+	return bindHTMLRenderSession(renderer, options, ownsRenderer);
+}
+export { MasterCSSHTMLRenderSession, bindHTMLRenderSessionInternal };

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { MasterCSSExternalHydrationManifestOptions, MasterCSSExternalHydrationManifestSource, MasterCSSHTMLDocumentOptions, MasterCSSHTMLRenderResult, MasterCSSHydrationManifestRenderMode } from "./render.js";
+import { MasterCSSServerRenderer, MasterCSSServerRendererOptions, createServerRenderer } from "./create-server-renderer.js";
+import { MasterCSSHTMLRenderSession, MasterCSSHTMLStreamEndResult } from "./html-render-session.js";
+import { MasterCSSHTMLRenderOptions, createHTMLRenderSession, renderHTML } from "./render-html.js";
+import { MasterCSSServerStylesheet } from "./native-stylesheets.js";
+export { type MasterCSSExternalHydrationManifestOptions, type MasterCSSExternalHydrationManifestSource, type MasterCSSHTMLDocumentOptions, type MasterCSSHTMLRenderOptions, type MasterCSSHTMLRenderResult, MasterCSSHTMLRenderSession, type MasterCSSHTMLStreamEndResult, type MasterCSSHydrationManifestRenderMode, MasterCSSServerRenderer, type MasterCSSServerRendererOptions, type MasterCSSServerStylesheet, createHTMLRenderSession, createServerRenderer, renderHTML };

package/dist/index.js

@@ -0,0 +1,4 @@
+import { MasterCSSHTMLRenderSession } from "./html-render-session.js";
+import { MasterCSSServerRenderer, createServerRenderer } from "./create-server-renderer.js";
+import { createHTMLRenderSession, renderHTML } from "./render-html.js";
+export { MasterCSSHTMLRenderSession, MasterCSSServerRenderer, createHTMLRenderSession, createServerRenderer, renderHTML };

package/dist/native-stylesheets.d.ts

@@ -0,0 +1,15 @@
+import parseHTML from "./parse-html.js";
+/** A final stylesheet a rendered page may link. */
+interface MasterCSSServerStylesheet {
+  readonly href: string;
+  readonly css: string;
+  /** Hrefs of the stylesheets it imports, in order, relative to `href`. */
+  readonly imports?: readonly string[];
+}
+/**
+ * The CSS a page delivers natively, in document order: its inline styles, then each
+ * linked stylesheet followed by the ones it imports. Theme variables these declare
+ * are not generated again.
+ */
+declare function collectNativeStylesheets(document: ReturnType<typeof parseHTML>, stylesheets?: readonly MasterCSSServerStylesheet[], documentURL?: string): string[];
+export { MasterCSSServerStylesheet, collectNativeStylesheets };

package/dist/native-stylesheets.js

@@ -0,0 +1,27 @@
+// src/native-stylesheets.ts
+/**
+* The CSS a page delivers natively, in document order: its inline styles, then each
+* linked stylesheet followed by the ones it imports. Theme variables these declare
+* are not generated again.
+*/
+function collectNativeStylesheets(document, stylesheets = [], documentURL = "https://master-css-render.invalid/") {
+	const byHref = new Map(stylesheets.map((stylesheet) => [new URL(stylesheet.href, documentURL).href, stylesheet]));
+	const sources = document.nativeStyleElements.map((style) => style.childNodes.map((node) => "data" in node ? node.data : "").join(""));
+	const visited = /* @__PURE__ */ new Set();
+	const collect = (href) => {
+		const stylesheet = byHref.get(href);
+		if (!stylesheet || visited.has(href)) return;
+		visited.add(href);
+		sources.push(stylesheet.css);
+		for (const imported of stylesheet.imports ?? []) collect(new URL(imported, href).href);
+	};
+	const visit = (nodes) => {
+		for (const node of nodes) {
+			if ("attribs" in node && node.name === "link" && node.attribs.rel === "stylesheet" && node.attribs.href && node.attribs.disabled === void 0) collect(new URL(node.attribs.href, documentURL).href);
+			if ("childNodes" in node) visit(node.childNodes);
+		}
+	};
+	visit(document.nodes);
+	return sources;
+}
+export { collectNativeStylesheets };

package/dist/parse-html.d.ts

@@ -0,0 +1,14 @@
+import { ChildNode, Element } from "domhandler";
+/**
+ * @param html
+ * @returns {classes from html, root element}
+ */
+declare function parseHTML(html: string): {
+  classes: string[];
+  nodes: ChildNode[];
+  htmlElement: Element | null;
+  headElement: Element | null;
+  styleElement: Element | null;
+  nativeStyleElements: Element[];
+};
+export { parseHTML as default };

package/dist/parse-html.js

@@ -0,0 +1,41 @@
+import decodeHTML from "./decode-html.js";
+import { DomHandler, Parser } from "htmlparser2";
+import { MASTER_CSS_RUNTIME_STYLE_ID } from "@master/css-schema/runtime-style";
+// src/parse-html.ts
+/**
+* @param html
+* @returns {classes from html, root element}
+*/
+function parseHTML(html) {
+	const classes = /* @__PURE__ */ new Set();
+	let htmlElement = null;
+	let headElement = null;
+	let styleElement = null;
+	const nativeStyleElements = [];
+	const handler = new DomHandler(void 0, {}, (element) => {
+		if (element.type === "tag") switch (element.name) {
+			case "html":
+				htmlElement = element;
+				break;
+			case "head": headElement = element;
+		}
+		else if (element.type === "style") {
+			if (element.attribs.id === MASTER_CSS_RUNTIME_STYLE_ID) styleElement = element;
+			else if (!element.attribs.type || element.attribs.type === "text/css") nativeStyleElements.push(element);
+		}
+		if (element.attribs.class) decodeHTML(element.attribs.class).split(/[\t\n\f\r ]+/).forEach((className) => {
+			if (!className) return;
+			classes.add(className);
+		});
+	});
+	new Parser(handler, { decodeEntities: false }).end(html);
+	return {
+		classes: [...classes],
+		nodes: handler.root.childNodes,
+		htmlElement,
+		headElement,
+		styleElement,
+		nativeStyleElements
+	};
+}
+export { parseHTML as default };

package/dist/render-html.d.ts

@@ -0,0 +1,7 @@
+import { MasterCSSHTMLDocumentOptions, MasterCSSHTMLRenderResult } from "./render.js";
+import { MasterCSSServerRendererOptions } from "./create-server-renderer.js";
+import { MasterCSSHTMLRenderSession } from "./html-render-session.js";
+interface MasterCSSHTMLRenderOptions extends MasterCSSServerRendererOptions, MasterCSSHTMLDocumentOptions {}
+declare function renderHTML(html: string, options: MasterCSSHTMLRenderOptions): MasterCSSHTMLRenderResult;
+declare function createHTMLRenderSession(options: MasterCSSHTMLRenderOptions): MasterCSSHTMLRenderSession;
+export { MasterCSSHTMLRenderOptions, createHTMLRenderSession, renderHTML };

package/dist/render-html.js

@@ -0,0 +1,34 @@
+import { bindHTMLRenderSessionInternal } from "./html-render-session.js";
+import { createServerRenderer } from "./create-server-renderer.js";
+// src/render-html.ts
+function renderHTML(html, options) {
+	const { hydrationManifest, stylesheets, documentURL, manifest, emittedGlobals, maxCachedClasses } = options;
+	const renderer = createServerRenderer({
+		manifest,
+		emittedGlobals,
+		maxCachedClasses
+	});
+	try {
+		return renderer.renderHTML(html, {
+			hydrationManifest,
+			stylesheets,
+			documentURL
+		});
+	} finally {
+		renderer.dispose();
+	}
+}
+function createHTMLRenderSession(options) {
+	const { hydrationManifest, stylesheets, documentURL, manifest, emittedGlobals, maxCachedClasses } = options;
+	const renderer = createServerRenderer({
+		manifest,
+		emittedGlobals,
+		maxCachedClasses
+	});
+	return bindHTMLRenderSessionInternal(renderer, {
+		hydrationManifest,
+		stylesheets,
+		documentURL
+	}, true);
+}
+export { createHTMLRenderSession, renderHTML };

package/dist/render.d.ts

@@ -0,0 +1,28 @@
+import { MasterCSSRenderSnapshot } from "@master/css/node";
+import { MasterCSSDiagnostic } from "@master/css-schema";
+import { MasterCSSHydrationManifest } from "@master/css-schema/hydration-manifest";
+import { MasterCSSServerStylesheet } from "./native-stylesheets.js";
+import parseHTML from "./parse-html.js";
+type MasterCSSExternalHydrationManifestSource = string | ((json: string, hydrationManifest: MasterCSSHydrationManifest) => string);
+interface MasterCSSExternalHydrationManifestOptions {
+  readonly type: 'external';
+  readonly source: MasterCSSExternalHydrationManifestSource;
+}
+type MasterCSSHydrationManifestRenderMode = 'return' | 'inject' | false | MasterCSSExternalHydrationManifestOptions;
+interface MasterCSSHTMLDocumentOptions {
+  readonly hydrationManifest?: MasterCSSHydrationManifestRenderMode;
+  /** Final stylesheets the page may link, whose theme variables it does not repeat. */
+  readonly stylesheets?: readonly MasterCSSServerStylesheet[];
+  /** Resolves the page's stylesheet links. */
+  readonly documentURL?: string;
+}
+interface MasterCSSHTMLRenderResult {
+  readonly html: string;
+  readonly cssText: string;
+  readonly classNames: readonly string[];
+  readonly invalidClassNames: readonly string[];
+  readonly hydrationManifest?: MasterCSSHydrationManifest;
+  readonly diagnostics: readonly MasterCSSDiagnostic[];
+}
+declare function renderHTMLWithSnapshot(html: string, context: ReturnType<typeof parseHTML>, snapshot: MasterCSSRenderSnapshot | undefined, options: MasterCSSHTMLDocumentOptions): MasterCSSHTMLRenderResult;
+export { MasterCSSExternalHydrationManifestOptions, MasterCSSExternalHydrationManifestSource, MasterCSSHTMLDocumentOptions, MasterCSSHTMLRenderResult, MasterCSSHydrationManifestRenderMode, renderHTMLWithSnapshot };

package/dist/render.js

@@ -0,0 +1,117 @@
+import { MASTER_CSS_RUNTIME_STYLE_ID } from "@master/css-schema/runtime-style";
+import { MASTER_CSS_HYDRATION_MANIFEST_ATTR, MASTER_CSS_HYDRATION_MANIFEST_SCRIPT_ID, serializeMasterCSSHydrationManifest } from "@master/css-schema/hydration-manifest";
+import { Element, Text } from "domhandler";
+import serialize from "dom-serializer";
+// src/render.ts
+function hydrationScript(hydrationManifest) {
+	return new Element("script", {
+		type: "application/json",
+		id: MASTER_CSS_HYDRATION_MANIFEST_SCRIPT_ID
+	}, [new Text(serializeMasterCSSHydrationManifest(hydrationManifest))]);
+}
+function isHydrationScript(node) {
+	return node.type === "script" && node.name === "script" && node.attribs.id === MASTER_CSS_HYDRATION_MANIFEST_SCRIPT_ID;
+}
+function findHydrationScripts(childNodes, matches = []) {
+	for (let index = 0; index < childNodes.length; index++) {
+		const node = childNodes[index];
+		if (isHydrationScript(node)) matches.push({
+			element: node,
+			childNodes,
+			index
+		});
+		if ("childNodes" in node) findHydrationScripts(node.childNodes, matches);
+	}
+	return matches;
+}
+function removeHydrationScripts(nodes) {
+	const scripts = findHydrationScripts(nodes);
+	for (let index = scripts.length - 1; index >= 0; index--) {
+		const script = scripts[index];
+		script.childNodes.splice(script.index, 1);
+	}
+}
+function removeNode(nodes, target) {
+	const index = nodes.indexOf(target);
+	if (index !== -1) {
+		nodes.splice(index, 1);
+		return true;
+	}
+	for (const node of nodes) if ("childNodes" in node && removeNode(node.childNodes, target)) return true;
+	return false;
+}
+function injectHydrationScript(nodes, htmlElement, headElement, styleElement, hydrationManifest) {
+	if (styleElement) delete styleElement.attribs[MASTER_CSS_HYDRATION_MANIFEST_ATTR];
+	const scripts = findHydrationScripts(nodes);
+	if (scripts.length) {
+		const [first, ...duplicates] = scripts;
+		first.element.attribs.type = "application/json";
+		first.element.childNodes = [new Text(serializeMasterCSSHydrationManifest(hydrationManifest))];
+		for (let index = duplicates.length - 1; index >= 0; index--) {
+			const duplicate = duplicates[index];
+			duplicate.childNodes.splice(duplicate.index, 1);
+		}
+		return;
+	}
+	const script = hydrationScript(hydrationManifest);
+	if (headElement) headElement.childNodes.push(script);
+	else if (htmlElement) htmlElement.childNodes.unshift(new Element("head", {}, [script]));
+	else nodes.unshift(script);
+}
+function externalSource(option, hydrationManifest) {
+	const json = serializeMasterCSSHydrationManifest(hydrationManifest);
+	return typeof option.source === "function" ? option.source(json, hydrationManifest) : option.source;
+}
+function result(html, classNames, snapshot, hydrationManifest) {
+	return Object.freeze({
+		html,
+		cssText: snapshot?.cssText ?? "",
+		classNames: Object.freeze([...classNames]),
+		invalidClassNames: Object.freeze([...snapshot?.invalidClassNames ?? []]),
+		...hydrationManifest ? { hydrationManifest } : {},
+		diagnostics: Object.freeze([])
+	});
+}
+function styleText(css) {
+	return css.replace(/(\\*)<\/style/gi, (match, escapes) => {
+		return escapes.slice(0, escapes.length - escapes.length % 2) + "\\3c " + match.slice(escapes.length + 1);
+	});
+}
+function renderHTMLWithSnapshot(html, context, snapshot, options) {
+	const { nodes, htmlElement, classes: classNames } = context;
+	let { headElement, styleElement } = context;
+	const hydrationOption = options.hydrationManifest ?? "return";
+	const hydrationManifest = hydrationOption === false ? void 0 : snapshot?.hydrationManifest;
+	const external = typeof hydrationOption === "object" ? hydrationOption : void 0;
+	if (!snapshot?.cssText) {
+		if ((hydrationOption === "inject" || external) && styleElement) {
+			removeNode(nodes, styleElement);
+			styleElement = null;
+		}
+		if (external) removeHydrationScripts(nodes);
+		return result(external || styleElement !== context.styleElement ? serialize(nodes, {
+			decodeEntities: false,
+			encodeEntities: false
+		}) : html, classNames, snapshot, hydrationManifest);
+	}
+	const safeStyleText = styleText(snapshot.cssText);
+	if (styleElement) styleElement.childNodes = [new Text(safeStyleText)];
+	else {
+		styleElement = new Element("style", { id: MASTER_CSS_RUNTIME_STYLE_ID }, [new Text(safeStyleText)]);
+		if (headElement) headElement.childNodes.push(styleElement);
+		else if (htmlElement) {
+			headElement = new Element("head", {}, [styleElement]);
+			htmlElement.childNodes.unshift(headElement);
+		} else nodes.unshift(styleElement);
+	}
+	if (hydrationOption === "inject" && hydrationManifest && snapshot.rules.length) injectHydrationScript(nodes, htmlElement, headElement, styleElement, hydrationManifest);
+	else if (external && hydrationManifest && snapshot.rules.length) {
+		removeHydrationScripts(nodes);
+		styleElement.attribs[MASTER_CSS_HYDRATION_MANIFEST_ATTR] = externalSource(external, hydrationManifest);
+	} else delete styleElement.attribs[MASTER_CSS_HYDRATION_MANIFEST_ATTR];
+	return result(serialize(nodes, {
+		decodeEntities: false,
+		encodeEntities: false
+	}), classNames, snapshot, hydrationManifest);
+}
+export { renderHTMLWithSnapshot };

package/package.json

@@ -0,0 +1,54 @@
+{
+    "name": "@master/css-server",
+    "type": "module",
+    "engines": {
+        "node": "^24"
+    },
+    "license": "MIT",
+    "description": "Server-side HTML renderer for Master CSS",
+    "author": "Aoyue Design LLC.",
+    "homepage": "https://css.master.co",
+    "bugs": {
+        "url": "https://github.com/master-co/css/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/master-co/css.git",
+        "directory": "packages/server"
+    },
+    "keywords": [
+        "server",
+        "static",
+        "html",
+        "markup",
+        "dom",
+        "css",
+        "mastercss"
+    ],
+    "sideEffects": false,
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "default": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "publishConfig": {
+        "access": "public",
+        "provenance": true
+    },
+    "dependencies": {
+        "@master/css": "0.0.0-site.1793659883.g69c9aebcf628",
+        "@master/css-tooling": "0.0.0-site.1793659883.g69c9aebcf628",
+        "dom-serializer": "^3.1.1",
+        "domhandler": "^6.0.1",
+        "htmlparser2": "^12.0.0",
+        "@master/css-schema": "0.0.0-site.1793659883.g69c9aebcf628"
+    },
+    "version": "0.0.0-site.1793659883.g69c9aebcf628",
+    "gitHead": "69c9aebcf628eb529001b9fa1b3536306f1b139e"
+}