@moku-labs/web 1.8.2 → 1.9.0

package/dist/browser.d.mts

@@ -1920,7 +1920,7 @@ type DataProvider = {
  */
 declare const dataPlugin: import("@moku-labs/core").PluginInstance<"data", DataConfig, DataState, DataProvider, {}> & Record<never, never>;
 declare namespace types_d_exports {
-  export { Api, Article, ArticleCard, ComputedFields, Config, ContentApiContext, ContentEvents, ContentProvider, ContentProviderState, FileSystemContentOptions, Frontmatter, LoadAllOptions, State };
+  export { Api, Article, ArticleCard, ComputedFields, Config, ContentApiContext, ContentEvents, ContentProvider, ContentProviderState, FileSystemContentOptions, Frontmatter, LoadAllOptions, MermaidDiagramOptions, State };
 }
 /**
  * YAML frontmatter parsed from each article file.
@@ -2034,6 +2034,36 @@ interface ContentProvider {
    */
   invalidate?(paths: readonly string[]): void;
 }
+/**
+ * Options for build-time Mermaid diagram rendering (the `mermaid` key of
+ * {@link FileSystemContentOptions}). Rendering is delegated to the OPTIONAL
+ * peer dependency `mermaid-isomorphic`, so the config stays loosely typed —
+ * its types are never imported here.
+ *
+ * @example
+ * ```ts
+ * fileSystemContent({ contentDir: "./content", trustedContent: true, mermaid: { mermaidConfig: { theme: "dark" } } });
+ * ```
+ */
+type MermaidDiagramOptions = {
+  /**
+   * Mermaid configuration passed straight through to mermaid-isomorphic's
+   * render call (e.g. `{ theme: "dark" }`). Loosely typed as a plain record
+   * because the dependency is optional.
+   */
+  mermaidConfig?: Record<string, unknown>;
+  /**
+   * TEST-ONLY seam: replaces the real mermaid-isomorphic batch renderer so
+   * unit tests stay deterministic with no headless browser. Receives every
+   * mermaid fence source of one document in order and must resolve to exactly
+   * one SVG string per source. Never set this in an app.
+   *
+   * @param sources - Every mermaid fence source of one document, in order.
+   * @param mermaidConfig - The configured mermaid pass-through config, if any.
+   * @returns One SVG string per source, in order.
+   */
+  renderDiagrams?: (sources: readonly string[], mermaidConfig?: Record<string, unknown>) => Promise<readonly string[]>;
+};
 /**
  * Options for the node filesystem provider {@link ContentProvider} `fileSystemContent`.
  * These are the markdown-pipeline + source concerns that used to live on the content
@@ -2059,6 +2089,15 @@ type FileSystemContentOptions = {
    */
   shikiTheme?: BundledTheme | ThemeRegistrationAny; /** Author applied to articles whose frontmatter omits author. Defaults to undefined. */
   defaultAuthor?: string;
+  /**
+   * Build-time Mermaid diagrams: render fenced `mermaid` code blocks to static
+   * inline SVG during the build (zero client-side JS). `true` enables with
+   * defaults; an object passes {@link MermaidDiagramOptions}. Requires
+   * `trustedContent: true` (the raw inline SVG would be stripped by the
+   * sanitize pass) and the OPTIONAL peer dependency `mermaid-isomorphic`
+   * (plus playwright with an installed browser). Defaults to disabled.
+   */
+  mermaid?: boolean | MermaidDiagramOptions;
 };
 /**
  * Internal mutable state of the filesystem provider: the lazy unified processor and

package/dist/index.cjs

@@ -1580,6 +1580,23 @@ function createContentState(_ctx) {
 function validateContentConfig(config) {
 	if (!Array.isArray(config.providers) || config.providers.length === 0) throw new Error("[web] content: no provider composed.\n  Add fileSystemContent(...) to pluginConfigs.content.providers.");
 }
+/**
+* Validates the `fileSystemContent` provider options (fail-fast at provider
+* construction). Throws when `mermaid` is enabled without `trustedContent: true`:
+* mermaid output is raw inline SVG, which the sanitize pass (the untrusted-content
+* XSS boundary) would strip — so the combination can never work. Errors use the
+* `[web]` prefix.
+*
+* @param options - The provider options to validate.
+* @throws {Error} If `mermaid` is enabled while `trustedContent` is not `true`.
+* @example
+* ```ts
+* validateFileSystemContentOptions({ contentDir: "./content", trustedContent: true, mermaid: true });
+* ```
+*/
+function validateFileSystemContentOptions(options) {
+	if (Boolean(options.mermaid) && options.trustedContent !== true) throw new Error("[web] content: `mermaid` requires `trustedContent: true`.\n  Mermaid diagrams render to raw inline SVG, which the sanitize pass would strip.\n  Set trustedContent: true ONLY for fully author-controlled Markdown.");
+}
 //#endregion
 //#region src/plugins/content/index.ts
 /**
@@ -11569,6 +11586,154 @@ function parseFrontmatter(raw, config) {
 	};
 }
 //#endregion
+//#region src/plugins/content/pipeline/mermaid.ts
+/** CSS class on the `<figure>` wrapper around each rendered diagram. */
+const MERMAID_FIGURE_CLASS = "mermaid-diagram";
+/**
+* Cached renderer promise — `createMermaidRenderer()` is called ONCE per process
+* and shared by every document (the underlying headless browser is expensive).
+*/
+let cachedRendererPromise;
+/**
+* Lazily import `mermaid-isomorphic` and create its batched renderer. The import
+* happens HERE (never at module load) so the optional dependency is only touched
+* when a document actually contains a mermaid fence. A failed import is wrapped
+* in an actionable error naming the missing package.
+*
+* @param importModule - Import thunk for the package; injectable so tests can
+* exercise both outcomes without the real dependency. Defaults to the real
+* dynamic `import("mermaid-isomorphic")`.
+* @returns The batched mermaid renderer.
+* @throws {Error} When the optional dependency cannot be loaded.
+* @example
+* ```ts
+* const renderer = await loadMermaidRenderer();
+* const results = await renderer(["graph TD; A-->B"]);
+* ```
+*/
+async function loadMermaidRenderer(importModule = () => import("mermaid-isomorphic")) {
+	let moduleExports;
+	try {
+		moduleExports = await importModule();
+	} catch (error) {
+		throw new Error("[web] content: `mermaid` is enabled but the optional dependency \"mermaid-isomorphic\" could not be loaded.\n  Install it (plus playwright and a browser):\n    bun add -d mermaid-isomorphic playwright && bunx playwright install chromium", { cause: error });
+	}
+	return moduleExports.createMermaidRenderer();
+}
+/**
+* Unwrap mermaid-isomorphic's settled results into plain SVG strings, failing
+* the build on the first rejected diagram. The error quotes the diagram's first
+* line so the author can locate the broken fence.
+*
+* @param sources - The diagram sources, in the order they were rendered.
+* @param results - The settled render results (one per source).
+* @returns One SVG string per source, in order.
+* @throws {Error} When any diagram failed to render.
+* @example
+* ```ts
+* const svgs = unwrapMermaidResults(["graph TD; A-->B"], results);
+* ```
+*/
+function unwrapMermaidResults(sources, results) {
+	return results.map((result, index) => {
+		if (result.status === "rejected") {
+			const firstLine = (sources[index] ?? "").split("\n", 1)[0] ?? "";
+			throw new Error(`[web] content: mermaid diagram failed to render (diagram starts with "${firstLine}"): ${String(result.reason)}`);
+		}
+		return result.value.svg;
+	});
+}
+/**
+* The REAL render path: lazily load mermaid-isomorphic (cached once per
+* process), render every fence of the document in ONE batched call, and unwrap
+* the results. Replaced in unit tests by the `renderDiagrams` seam.
+*
+* @param sources - Every mermaid fence source of one document, in order.
+* @param mermaidConfig - Optional mermaid configuration forwarded to the render call.
+* @returns One SVG string per source, in order.
+* @example
+* ```ts
+* const svgs = await renderWithMermaidIsomorphic(["graph TD; A-->B"]);
+* ```
+*/
+async function renderWithMermaidIsomorphic(sources, mermaidConfig) {
+	cachedRendererPromise ??= loadMermaidRenderer();
+	return unwrapMermaidResults(sources, await (await cachedRendererPromise)([...sources], mermaidConfig ? { mermaidConfig } : void 0));
+}
+/**
+* Collect every fenced `mermaid` code block in the tree (with the parent/index
+* needed to replace it later), in document order.
+*
+* @param tree - The mdast tree to scan.
+* @returns The fence sites found.
+* @example
+* ```ts
+* const fences = collectMermaidFences(tree);
+* ```
+*/
+function collectMermaidFences(tree) {
+	const fences = [];
+	(0, unist_util_visit.visit)(tree, "code", (node, index, parent) => {
+		if (node.lang !== "mermaid") return;
+		if (parent === void 0 || index === void 0) return;
+		fences.push({
+			node,
+			parent,
+			index
+		});
+	});
+	return fences;
+}
+/**
+* Normalize the provider's `mermaid` config value (`boolean | options`) to a
+* plain {@link MermaidDiagramOptions} object for the transform factory.
+*
+* @param mermaid - The raw `FileSystemContentOptions.mermaid` value (truthy).
+* @returns The options object (`{}` for the bare `true` form).
+* @example
+* ```ts
+* normalizeMermaidOptions(true); // {}
+* normalizeMermaidOptions({ mermaidConfig: { theme: "dark" } });
+* ```
+*/
+function normalizeMermaidOptions(mermaid) {
+	return typeof mermaid === "boolean" ? {} : mermaid;
+}
+/**
+* Remark transform factory: replaces every fenced `mermaid` code block with a
+* `<figure class="mermaid-diagram">` raw-HTML node carrying the diagram as
+* static inline SVG, rendered at build time (zero client-side JS). Runs at the
+* mdast stage, BEFORE remark-rehype; the bridge's `allowDangerousHtml` plus the
+* framework's `rehype-raw` default carry the SVG into the output. Documents
+* without a mermaid fence return immediately — `mermaid-isomorphic` is never
+* imported on that path. A diagram that fails to render fails the build with
+* its first line quoted.
+*
+* @param options - Mermaid options: `mermaidConfig` pass-through + the
+* test-only `renderDiagrams` seam.
+* @returns An async mdast tree transformer.
+* @example
+* ```ts
+* unified().use(remarkMermaidDiagrams, { mermaidConfig: { theme: "dark" } });
+* ```
+*/
+function remarkMermaidDiagrams(options = {}) {
+	return async (tree) => {
+		const fences = collectMermaidFences(tree);
+		if (fences.length === 0) return;
+		const sources = fences.map((fence) => fence.node.value);
+		const svgs = await (options.renderDiagrams ?? renderWithMermaidIsomorphic)(sources, options.mermaidConfig);
+		if (svgs.length !== sources.length) throw new Error(`[web] content: mermaid renderer returned ${svgs.length} result(s) for ${sources.length} diagram(s).`);
+		for (const [position, fence] of fences.entries()) {
+			const html = {
+				type: "html",
+				value: `<figure class="${MERMAID_FIGURE_CLASS}">${svgs[position] ?? ""}</figure>`
+			};
+			fence.parent.children[fence.index] = html;
+		}
+	};
+}
+//#endregion
 //#region src/plugins/content/pipeline/plugins.ts
 /**
 * Type guard for remark-directive nodes (container/leaf/text).
@@ -11704,25 +11869,31 @@ function sectionDividerPlugin() {
 }
 /**
 * The hardcoded framework default remark (Markdown-AST) plugins, in order:
-* parse, frontmatter, gfm, directive, pull-quote, then the mdast→hast bridge
-* (`remark-rehype` with `allowDangerousHtml`). Pull-quote runs on the mdast
-* before the bridge so the directive carries its `hName`/`hProperties`.
-*
+* parse, frontmatter, gfm, directive, pull-quote, the OPT-IN mermaid transform,
+* then the mdast→hast bridge (`remark-rehype` with `allowDangerousHtml`).
+* Pull-quote and mermaid run on the mdast before the bridge — pull-quote so the
+* directive carries its `hName`/`hProperties`, mermaid so the fence is replaced
+* with raw SVG HTML before Shiki could ever claim the code block.
+*
+* @param config - Optional provider configuration; only `mermaid` is read here
+* (truthy enables the mermaid transform at its fixed mdast position).
 * @returns The ordered default remark pluggables.
 * @example
 * ```ts
 * const remark = defaultRemarkPlugins();
 * ```
 */
-function defaultRemarkPlugins() {
-	return [
+function defaultRemarkPlugins(config) {
+	const plugins = [
 		remark_parse.default,
 		remark_frontmatter.default,
 		remark_gfm.default,
 		remark_directive.default,
-		pullQuotePlugin,
-		[remark_rehype.default, { allowDangerousHtml: true }]
+		pullQuotePlugin
 	];
+	if (config?.mermaid) plugins.push([remarkMermaidDiagrams, normalizeMermaidOptions(config.mermaid)]);
+	plugins.push([remark_rehype.default, { allowDangerousHtml: true }]);
+	return plugins;
 }
 /**
 * The hardcoded framework default rehype (HTML-AST) plugins, in order:
@@ -11863,14 +12034,15 @@ function applyPluggable(processor, plugin) {
 * replacing, the defaults).
 *
 * @param processor - The unified processor under construction (mutated in place).
-* @param config - Resolved plugin configuration (provides `extraRemarkPlugins`).
+* @param config - Resolved plugin configuration (provides `extraRemarkPlugins`,
+* and `mermaid` which the defaults read to enable the mdast mermaid transform).
 * @example
 * ```ts
 * applyRemarkPlugins(processor, config);
 * ```
 */
 function applyRemarkPlugins(processor, config) {
-	for (const plugin of defaultRemarkPlugins()) applyPluggable(processor, plugin);
+	for (const plugin of defaultRemarkPlugins(config)) applyPluggable(processor, plugin);
 	for (const plugin of config.extraRemarkPlugins ?? []) applyPluggable(processor, plugin);
 }
 /**
@@ -12022,6 +12194,7 @@ async function discoverSlugs(dir) {
 * ```
 */
 function fileSystemContent(options) {
+	validateFileSystemContentOptions(options);
 	const state = {
 		processor: null,
 		slugs: null,

package/dist/index.d.cts

@@ -2671,7 +2671,7 @@ type Api$1 = {
  */
 declare const cliPlugin: import("@moku-labs/core").PluginInstance<"cli", Config$1, State$1, Api$1, {}> & Record<never, never>;
 declare namespace types_d_exports$2 {
-  export { Api, Article, ArticleCard, ComputedFields, Config, ContentApiContext, ContentEvents, ContentProvider, ContentProviderState, FileSystemContentOptions, Frontmatter, LoadAllOptions, State };
+  export { Api, Article, ArticleCard, ComputedFields, Config, ContentApiContext, ContentEvents, ContentProvider, ContentProviderState, FileSystemContentOptions, Frontmatter, LoadAllOptions, MermaidDiagramOptions, State };
 }
 /**
  * YAML frontmatter parsed from each article file.
@@ -2785,6 +2785,36 @@ interface ContentProvider {
    */
   invalidate?(paths: readonly string[]): void;
 }
+/**
+ * Options for build-time Mermaid diagram rendering (the `mermaid` key of
+ * {@link FileSystemContentOptions}). Rendering is delegated to the OPTIONAL
+ * peer dependency `mermaid-isomorphic`, so the config stays loosely typed —
+ * its types are never imported here.
+ *
+ * @example
+ * ```ts
+ * fileSystemContent({ contentDir: "./content", trustedContent: true, mermaid: { mermaidConfig: { theme: "dark" } } });
+ * ```
+ */
+type MermaidDiagramOptions = {
+  /**
+   * Mermaid configuration passed straight through to mermaid-isomorphic's
+   * render call (e.g. `{ theme: "dark" }`). Loosely typed as a plain record
+   * because the dependency is optional.
+   */
+  mermaidConfig?: Record<string, unknown>;
+  /**
+   * TEST-ONLY seam: replaces the real mermaid-isomorphic batch renderer so
+   * unit tests stay deterministic with no headless browser. Receives every
+   * mermaid fence source of one document in order and must resolve to exactly
+   * one SVG string per source. Never set this in an app.
+   *
+   * @param sources - Every mermaid fence source of one document, in order.
+   * @param mermaidConfig - The configured mermaid pass-through config, if any.
+   * @returns One SVG string per source, in order.
+   */
+  renderDiagrams?: (sources: readonly string[], mermaidConfig?: Record<string, unknown>) => Promise<readonly string[]>;
+};
 /**
  * Options for the node filesystem provider {@link ContentProvider} `fileSystemContent`.
  * These are the markdown-pipeline + source concerns that used to live on the content
@@ -2810,6 +2840,15 @@ type FileSystemContentOptions = {
    */
   shikiTheme?: BundledTheme | ThemeRegistrationAny; /** Author applied to articles whose frontmatter omits author. Defaults to undefined. */
   defaultAuthor?: string;
+  /**
+   * Build-time Mermaid diagrams: render fenced `mermaid` code blocks to static
+   * inline SVG during the build (zero client-side JS). `true` enables with
+   * defaults; an object passes {@link MermaidDiagramOptions}. Requires
+   * `trustedContent: true` (the raw inline SVG would be stripped by the
+   * sanitize pass) and the OPTIONAL peer dependency `mermaid-isomorphic`
+   * (plus playwright with an installed browser). Defaults to disabled.
+   */
+  mermaid?: boolean | MermaidDiagramOptions;
 };
 /**
  * Internal mutable state of the filesystem provider: the lazy unified processor and

package/dist/index.d.mts

@@ -2671,7 +2671,7 @@ type Api$1 = {
  */
 declare const cliPlugin: import("@moku-labs/core").PluginInstance<"cli", Config$1, State$1, Api$1, {}> & Record<never, never>;
 declare namespace types_d_exports$2 {
-  export { Api, Article, ArticleCard, ComputedFields, Config, ContentApiContext, ContentEvents, ContentProvider, ContentProviderState, FileSystemContentOptions, Frontmatter, LoadAllOptions, State };
+  export { Api, Article, ArticleCard, ComputedFields, Config, ContentApiContext, ContentEvents, ContentProvider, ContentProviderState, FileSystemContentOptions, Frontmatter, LoadAllOptions, MermaidDiagramOptions, State };
 }
 /**
  * YAML frontmatter parsed from each article file.
@@ -2785,6 +2785,36 @@ interface ContentProvider {
    */
   invalidate?(paths: readonly string[]): void;
 }
+/**
+ * Options for build-time Mermaid diagram rendering (the `mermaid` key of
+ * {@link FileSystemContentOptions}). Rendering is delegated to the OPTIONAL
+ * peer dependency `mermaid-isomorphic`, so the config stays loosely typed —
+ * its types are never imported here.
+ *
+ * @example
+ * ```ts
+ * fileSystemContent({ contentDir: "./content", trustedContent: true, mermaid: { mermaidConfig: { theme: "dark" } } });
+ * ```
+ */
+type MermaidDiagramOptions = {
+  /**
+   * Mermaid configuration passed straight through to mermaid-isomorphic's
+   * render call (e.g. `{ theme: "dark" }`). Loosely typed as a plain record
+   * because the dependency is optional.
+   */
+  mermaidConfig?: Record<string, unknown>;
+  /**
+   * TEST-ONLY seam: replaces the real mermaid-isomorphic batch renderer so
+   * unit tests stay deterministic with no headless browser. Receives every
+   * mermaid fence source of one document in order and must resolve to exactly
+   * one SVG string per source. Never set this in an app.
+   *
+   * @param sources - Every mermaid fence source of one document, in order.
+   * @param mermaidConfig - The configured mermaid pass-through config, if any.
+   * @returns One SVG string per source, in order.
+   */
+  renderDiagrams?: (sources: readonly string[], mermaidConfig?: Record<string, unknown>) => Promise<readonly string[]>;
+};
 /**
  * Options for the node filesystem provider {@link ContentProvider} `fileSystemContent`.
  * These are the markdown-pipeline + source concerns that used to live on the content
@@ -2810,6 +2840,15 @@ type FileSystemContentOptions = {
    */
   shikiTheme?: BundledTheme | ThemeRegistrationAny; /** Author applied to articles whose frontmatter omits author. Defaults to undefined. */
   defaultAuthor?: string;
+  /**
+   * Build-time Mermaid diagrams: render fenced `mermaid` code blocks to static
+   * inline SVG during the build (zero client-side JS). `true` enables with
+   * defaults; an object passes {@link MermaidDiagramOptions}. Requires
+   * `trustedContent: true` (the raw inline SVG would be stripped by the
+   * sanitize pass) and the OPTIONAL peer dependency `mermaid-isomorphic`
+   * (plus playwright with an installed browser). Defaults to disabled.
+   */
+  mermaid?: boolean | MermaidDiagramOptions;
 };
 /**
  * Internal mutable state of the filesystem provider: the lazy unified processor and

package/dist/index.mjs

@@ -1567,6 +1567,23 @@ function createContentState(_ctx) {
 function validateContentConfig(config) {
 	if (!Array.isArray(config.providers) || config.providers.length === 0) throw new Error("[web] content: no provider composed.\n  Add fileSystemContent(...) to pluginConfigs.content.providers.");
 }
+/**
+* Validates the `fileSystemContent` provider options (fail-fast at provider
+* construction). Throws when `mermaid` is enabled without `trustedContent: true`:
+* mermaid output is raw inline SVG, which the sanitize pass (the untrusted-content
+* XSS boundary) would strip — so the combination can never work. Errors use the
+* `[web]` prefix.
+*
+* @param options - The provider options to validate.
+* @throws {Error} If `mermaid` is enabled while `trustedContent` is not `true`.
+* @example
+* ```ts
+* validateFileSystemContentOptions({ contentDir: "./content", trustedContent: true, mermaid: true });
+* ```
+*/
+function validateFileSystemContentOptions(options) {
+	if (Boolean(options.mermaid) && options.trustedContent !== true) throw new Error("[web] content: `mermaid` requires `trustedContent: true`.\n  Mermaid diagrams render to raw inline SVG, which the sanitize pass would strip.\n  Set trustedContent: true ONLY for fully author-controlled Markdown.");
+}
 //#endregion
 //#region src/plugins/content/index.ts
 /**
@@ -11556,6 +11573,154 @@ function parseFrontmatter(raw, config) {
 	};
 }
 //#endregion
+//#region src/plugins/content/pipeline/mermaid.ts
+/** CSS class on the `<figure>` wrapper around each rendered diagram. */
+const MERMAID_FIGURE_CLASS = "mermaid-diagram";
+/**
+* Cached renderer promise — `createMermaidRenderer()` is called ONCE per process
+* and shared by every document (the underlying headless browser is expensive).
+*/
+let cachedRendererPromise;
+/**
+* Lazily import `mermaid-isomorphic` and create its batched renderer. The import
+* happens HERE (never at module load) so the optional dependency is only touched
+* when a document actually contains a mermaid fence. A failed import is wrapped
+* in an actionable error naming the missing package.
+*
+* @param importModule - Import thunk for the package; injectable so tests can
+* exercise both outcomes without the real dependency. Defaults to the real
+* dynamic `import("mermaid-isomorphic")`.
+* @returns The batched mermaid renderer.
+* @throws {Error} When the optional dependency cannot be loaded.
+* @example
+* ```ts
+* const renderer = await loadMermaidRenderer();
+* const results = await renderer(["graph TD; A-->B"]);
+* ```
+*/
+async function loadMermaidRenderer(importModule = () => import("mermaid-isomorphic")) {
+	let moduleExports;
+	try {
+		moduleExports = await importModule();
+	} catch (error) {
+		throw new Error("[web] content: `mermaid` is enabled but the optional dependency \"mermaid-isomorphic\" could not be loaded.\n  Install it (plus playwright and a browser):\n    bun add -d mermaid-isomorphic playwright && bunx playwright install chromium", { cause: error });
+	}
+	return moduleExports.createMermaidRenderer();
+}
+/**
+* Unwrap mermaid-isomorphic's settled results into plain SVG strings, failing
+* the build on the first rejected diagram. The error quotes the diagram's first
+* line so the author can locate the broken fence.
+*
+* @param sources - The diagram sources, in the order they were rendered.
+* @param results - The settled render results (one per source).
+* @returns One SVG string per source, in order.
+* @throws {Error} When any diagram failed to render.
+* @example
+* ```ts
+* const svgs = unwrapMermaidResults(["graph TD; A-->B"], results);
+* ```
+*/
+function unwrapMermaidResults(sources, results) {
+	return results.map((result, index) => {
+		if (result.status === "rejected") {
+			const firstLine = (sources[index] ?? "").split("\n", 1)[0] ?? "";
+			throw new Error(`[web] content: mermaid diagram failed to render (diagram starts with "${firstLine}"): ${String(result.reason)}`);
+		}
+		return result.value.svg;
+	});
+}
+/**
+* The REAL render path: lazily load mermaid-isomorphic (cached once per
+* process), render every fence of the document in ONE batched call, and unwrap
+* the results. Replaced in unit tests by the `renderDiagrams` seam.
+*
+* @param sources - Every mermaid fence source of one document, in order.
+* @param mermaidConfig - Optional mermaid configuration forwarded to the render call.
+* @returns One SVG string per source, in order.
+* @example
+* ```ts
+* const svgs = await renderWithMermaidIsomorphic(["graph TD; A-->B"]);
+* ```
+*/
+async function renderWithMermaidIsomorphic(sources, mermaidConfig) {
+	cachedRendererPromise ??= loadMermaidRenderer();
+	return unwrapMermaidResults(sources, await (await cachedRendererPromise)([...sources], mermaidConfig ? { mermaidConfig } : void 0));
+}
+/**
+* Collect every fenced `mermaid` code block in the tree (with the parent/index
+* needed to replace it later), in document order.
+*
+* @param tree - The mdast tree to scan.
+* @returns The fence sites found.
+* @example
+* ```ts
+* const fences = collectMermaidFences(tree);
+* ```
+*/
+function collectMermaidFences(tree) {
+	const fences = [];
+	visit(tree, "code", (node, index, parent) => {
+		if (node.lang !== "mermaid") return;
+		if (parent === void 0 || index === void 0) return;
+		fences.push({
+			node,
+			parent,
+			index
+		});
+	});
+	return fences;
+}
+/**
+* Normalize the provider's `mermaid` config value (`boolean | options`) to a
+* plain {@link MermaidDiagramOptions} object for the transform factory.
+*
+* @param mermaid - The raw `FileSystemContentOptions.mermaid` value (truthy).
+* @returns The options object (`{}` for the bare `true` form).
+* @example
+* ```ts
+* normalizeMermaidOptions(true); // {}
+* normalizeMermaidOptions({ mermaidConfig: { theme: "dark" } });
+* ```
+*/
+function normalizeMermaidOptions(mermaid) {
+	return typeof mermaid === "boolean" ? {} : mermaid;
+}
+/**
+* Remark transform factory: replaces every fenced `mermaid` code block with a
+* `<figure class="mermaid-diagram">` raw-HTML node carrying the diagram as
+* static inline SVG, rendered at build time (zero client-side JS). Runs at the
+* mdast stage, BEFORE remark-rehype; the bridge's `allowDangerousHtml` plus the
+* framework's `rehype-raw` default carry the SVG into the output. Documents
+* without a mermaid fence return immediately — `mermaid-isomorphic` is never
+* imported on that path. A diagram that fails to render fails the build with
+* its first line quoted.
+*
+* @param options - Mermaid options: `mermaidConfig` pass-through + the
+* test-only `renderDiagrams` seam.
+* @returns An async mdast tree transformer.
+* @example
+* ```ts
+* unified().use(remarkMermaidDiagrams, { mermaidConfig: { theme: "dark" } });
+* ```
+*/
+function remarkMermaidDiagrams(options = {}) {
+	return async (tree) => {
+		const fences = collectMermaidFences(tree);
+		if (fences.length === 0) return;
+		const sources = fences.map((fence) => fence.node.value);
+		const svgs = await (options.renderDiagrams ?? renderWithMermaidIsomorphic)(sources, options.mermaidConfig);
+		if (svgs.length !== sources.length) throw new Error(`[web] content: mermaid renderer returned ${svgs.length} result(s) for ${sources.length} diagram(s).`);
+		for (const [position, fence] of fences.entries()) {
+			const html = {
+				type: "html",
+				value: `<figure class="${MERMAID_FIGURE_CLASS}">${svgs[position] ?? ""}</figure>`
+			};
+			fence.parent.children[fence.index] = html;
+		}
+	};
+}
+//#endregion
 //#region src/plugins/content/pipeline/plugins.ts
 /**
 * Type guard for remark-directive nodes (container/leaf/text).
@@ -11691,25 +11856,31 @@ function sectionDividerPlugin() {
 }
 /**
 * The hardcoded framework default remark (Markdown-AST) plugins, in order:
-* parse, frontmatter, gfm, directive, pull-quote, then the mdast→hast bridge
-* (`remark-rehype` with `allowDangerousHtml`). Pull-quote runs on the mdast
-* before the bridge so the directive carries its `hName`/`hProperties`.
-*
+* parse, frontmatter, gfm, directive, pull-quote, the OPT-IN mermaid transform,
+* then the mdast→hast bridge (`remark-rehype` with `allowDangerousHtml`).
+* Pull-quote and mermaid run on the mdast before the bridge — pull-quote so the
+* directive carries its `hName`/`hProperties`, mermaid so the fence is replaced
+* with raw SVG HTML before Shiki could ever claim the code block.
+*
+* @param config - Optional provider configuration; only `mermaid` is read here
+* (truthy enables the mermaid transform at its fixed mdast position).
 * @returns The ordered default remark pluggables.
 * @example
 * ```ts
 * const remark = defaultRemarkPlugins();
 * ```
 */
-function defaultRemarkPlugins() {
-	return [
+function defaultRemarkPlugins(config) {
+	const plugins = [
 		remarkParse,
 		remarkFrontmatter,
 		remarkGfm,
 		remarkDirective,
-		pullQuotePlugin,
-		[remarkRehype, { allowDangerousHtml: true }]
+		pullQuotePlugin
 	];
+	if (config?.mermaid) plugins.push([remarkMermaidDiagrams, normalizeMermaidOptions(config.mermaid)]);
+	plugins.push([remarkRehype, { allowDangerousHtml: true }]);
+	return plugins;
 }
 /**
 * The hardcoded framework default rehype (HTML-AST) plugins, in order:
@@ -11850,14 +12021,15 @@ function applyPluggable(processor, plugin) {
 * replacing, the defaults).
 *
 * @param processor - The unified processor under construction (mutated in place).
-* @param config - Resolved plugin configuration (provides `extraRemarkPlugins`).
+* @param config - Resolved plugin configuration (provides `extraRemarkPlugins`,
+* and `mermaid` which the defaults read to enable the mdast mermaid transform).
 * @example
 * ```ts
 * applyRemarkPlugins(processor, config);
 * ```
 */
 function applyRemarkPlugins(processor, config) {
-	for (const plugin of defaultRemarkPlugins()) applyPluggable(processor, plugin);
+	for (const plugin of defaultRemarkPlugins(config)) applyPluggable(processor, plugin);
 	for (const plugin of config.extraRemarkPlugins ?? []) applyPluggable(processor, plugin);
 }
 /**
@@ -12009,6 +12181,7 @@ async function discoverSlugs(dir) {
 * ```
 */
 function fileSystemContent(options) {
+	validateFileSystemContentOptions(options);
 	const state = {
 		processor: null,
 		slugs: null,

package/package.json

@@ -80,9 +80,15 @@
     "unist-util-visit": "5.1.0"
   },
   "peerDependencies": {
+    "mermaid-isomorphic": "^3.0.0",
     "preact": "^10.29.2",
     "preact-render-to-string": "^6.6.0"
   },
+  "peerDependenciesMeta": {
+    "mermaid-isomorphic": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@biomejs/biome": "2.4.16",
     "@types/bun": "1.3.14",
@@ -96,6 +102,7 @@
     "happy-dom": "20.9.0",
     "jiti": "2.6.1",
     "lefthook": "2.1.1",
+    "mermaid-isomorphic": "3.1.0",
     "preact": "10.29.2",
     "preact-render-to-string": "6.6.0",
     "publint": "0.3.21",
@@ -118,5 +125,5 @@
     "test:build-e2e": "bun test src/plugins/build/__tests__/e2e/",
     "test:coverage": "vitest run --project unit --project integration --coverage"
   },
-  "version": "1.8.2"
+  "version": "1.9.0"
 }