@moku-labs/web 1.8.2 → 1.10.0

package/dist/browser.d.mts

@@ -1734,6 +1734,13 @@ declare const headPlugin: import("@moku-labs/core").PluginInstance<"head", Confi
  */
 declare function createComponent(name: string, hooks: ComponentHooks): ComponentDef;
 //#endregion
+//#region src/plugins/spa/lazy-embed.d.ts
+/**
+ * Lazy-embed island: facade button click → real `<iframe loading="lazy">`.
+ * The companion of the content pipeline's `::embed` directive.
+ */
+declare const lazyEmbed: ComponentDef;
+//#endregion
 //#region src/plugins/spa/index.d.ts
 /**
  * SPA plugin — progressive client-side navigation layered over the static site:
@@ -1920,7 +1927,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 +2041,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 +2096,24 @@ 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;
+  /**
+   * Lazy iframe embeds: rewrite `::embed{src="…" title="…"}` leaf directives
+   * into static click-to-activate facades (no iframe — and none of the target's
+   * network/JS cost — until the reader clicks). Pair with the `lazyEmbed` SPA
+   * island, which swaps the facade for the real `<iframe loading="lazy">`.
+   * Requires `trustedContent: true` (the facade is raw HTML the sanitize pass
+   * would strip). Defaults to disabled.
+   */
+  embed?: boolean;
 };
 /**
  * Internal mutable state of the filesystem provider: the lazy unified processor and
@@ -2361,4 +2416,4 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
  */
 declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$5, Events, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>>;
 //#endregion
-export { types_d_exports as Content, types_d_exports$1 as Data, types_d_exports$2 as Env, types_d_exports$3 as Head, types_d_exports$4 as Log, types_d_exports$5 as Router, types_d_exports$6 as Spa, browserEnv, buildArticleHead, canonical, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_d_exports as Content, types_d_exports$1 as Data, types_d_exports$2 as Env, types_d_exports$3 as Head, types_d_exports$4 as Log, types_d_exports$5 as Router, types_d_exports$6 as Spa, browserEnv, buildArticleHead, canonical, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };

package/dist/browser.mjs

@@ -4428,6 +4428,84 @@ function disposeSpa() {
 	}
 }
 //#endregion
+//#region src/plugins/spa/lazy-embed.ts
+/**
+* @file `lazyEmbed` island — activates the static embed facades emitted by the
+* content pipeline's `::embed` directive (pipeline/embed.ts). Mounts on every
+* `[data-component="lazy-embed"]` figure; a click on the facade's button swaps
+* it for the real `<iframe loading="lazy">`. Until that click the embedded
+* document costs the page nothing — no request, no third-party JS, no
+* scroll-jacking. Register it in `pluginConfigs.spa.components`; all visual
+* chrome (`.lazy-embed*` classes) is consumer CSS.
+*/
+/** CSS class on the injected `<iframe>` (consumer CSS sizes it). */
+const EMBED_FRAME_CLASS = "lazy-embed-frame";
+/**
+* Swap a facade `<figure>`'s content for its real `<iframe>`. The iframe
+* carries `loading="lazy"` plus fullscreen permission, and the figure gains
+* `data-embed-active` so consumer CSS can restyle the activated state.
+*
+* @param figure - The facade element carrying `data-embed-src`/`data-embed-title`.
+* @example
+* ```ts
+* activateEmbed(figure);
+* ```
+*/
+function activateEmbed(figure) {
+	const src = figure.dataset.embedSrc;
+	if (!src) return;
+	const iframe = document.createElement("iframe");
+	iframe.src = src;
+	iframe.title = figure.dataset.embedTitle ?? "";
+	iframe.className = EMBED_FRAME_CLASS;
+	iframe.setAttribute("loading", "lazy");
+	iframe.allow = "fullscreen; autoplay; gamepad";
+	iframe.allowFullscreen = true;
+	figure.replaceChildren(iframe);
+	figure.dataset.embedActive = "";
+}
+/**
+* Shared click handler (module-level so mount/unmount detach the same
+* reference): a click on the facade's button activates the embed.
+*
+* @param event - The click event from the facade figure.
+* @example
+* ```ts
+* element.addEventListener("click", onFacadeClick);
+* ```
+*/
+function onFacadeClick(event) {
+	if (!event.target.closest("button.lazy-embed-button")) return;
+	const figure = event.currentTarget;
+	if (figure instanceof HTMLElement) activateEmbed(figure);
+}
+/**
+* Lazy-embed island: facade button click → real `<iframe loading="lazy">`.
+* The companion of the content pipeline's `::embed` directive.
+*/
+const lazyEmbed = createComponent("lazy-embed", {
+	/**
+	* Bind the activation click handler when a facade mounts.
+	*
+	* @param ctx - The island lifecycle context.
+	* @example
+	* onMount(ctx);
+	*/
+	onMount(ctx) {
+		ctx.el.addEventListener("click", onFacadeClick);
+	},
+	/**
+	* Remove the activation click handler when the facade is destroyed.
+	*
+	* @param ctx - The island lifecycle context.
+	* @example
+	* onDestroy(ctx);
+	*/
+	onDestroy(ctx) {
+		ctx.el.removeEventListener("click", onFacadeClick);
+	}
+});
+//#endregion
 //#region src/plugins/spa/index.ts
 /**
 * @file spa — Complex Plugin (WIRING ONLY, ≤30 lines). All logic lives in the
@@ -5115,4 +5193,4 @@ const createApp = core.createApp;
 */
 const createPlugin = core.createPlugin;
 //#endregion
-export { types_exports as Content, types_exports$1 as Data, types_exports$2 as Env, types_exports$3 as Head, types_exports$4 as Log, types_exports$5 as Router, types_exports$6 as Spa, browserEnv, buildArticleHead, canonical, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_exports as Content, types_exports$1 as Data, types_exports$2 as Env, types_exports$3 as Head, types_exports$4 as Log, types_exports$5 as Router, types_exports$6 as Spa, browserEnv, buildArticleHead, canonical, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };

package/dist/index.cjs

@@ -1580,6 +1580,25 @@ 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` or `embed` is enabled without
+* `trustedContent: true`: both emit raw HTML (inline SVG / the embed facade),
+* 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` or `embed` 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.");
+	if (Boolean(options.embed) && options.trustedContent !== true) throw new Error("[web] content: `embed` requires `trustedContent: true`.\n  Embed directives render to a raw-HTML facade, which the sanitize pass would strip\n  (and embedding third-party iframes is never safe for untrusted Markdown).\n  Set trustedContent: true ONLY for fully author-controlled Markdown.");
+}
 //#endregion
 //#region src/plugins/content/index.ts
 /**
@@ -11295,6 +11314,84 @@ function disposeSpa() {
 	}
 }
 //#endregion
+//#region src/plugins/spa/lazy-embed.ts
+/**
+* @file `lazyEmbed` island — activates the static embed facades emitted by the
+* content pipeline's `::embed` directive (pipeline/embed.ts). Mounts on every
+* `[data-component="lazy-embed"]` figure; a click on the facade's button swaps
+* it for the real `<iframe loading="lazy">`. Until that click the embedded
+* document costs the page nothing — no request, no third-party JS, no
+* scroll-jacking. Register it in `pluginConfigs.spa.components`; all visual
+* chrome (`.lazy-embed*` classes) is consumer CSS.
+*/
+/** CSS class on the injected `<iframe>` (consumer CSS sizes it). */
+const EMBED_FRAME_CLASS = "lazy-embed-frame";
+/**
+* Swap a facade `<figure>`'s content for its real `<iframe>`. The iframe
+* carries `loading="lazy"` plus fullscreen permission, and the figure gains
+* `data-embed-active` so consumer CSS can restyle the activated state.
+*
+* @param figure - The facade element carrying `data-embed-src`/`data-embed-title`.
+* @example
+* ```ts
+* activateEmbed(figure);
+* ```
+*/
+function activateEmbed(figure) {
+	const src = figure.dataset.embedSrc;
+	if (!src) return;
+	const iframe = document.createElement("iframe");
+	iframe.src = src;
+	iframe.title = figure.dataset.embedTitle ?? "";
+	iframe.className = EMBED_FRAME_CLASS;
+	iframe.setAttribute("loading", "lazy");
+	iframe.allow = "fullscreen; autoplay; gamepad";
+	iframe.allowFullscreen = true;
+	figure.replaceChildren(iframe);
+	figure.dataset.embedActive = "";
+}
+/**
+* Shared click handler (module-level so mount/unmount detach the same
+* reference): a click on the facade's button activates the embed.
+*
+* @param event - The click event from the facade figure.
+* @example
+* ```ts
+* element.addEventListener("click", onFacadeClick);
+* ```
+*/
+function onFacadeClick(event) {
+	if (!event.target.closest("button.lazy-embed-button")) return;
+	const figure = event.currentTarget;
+	if (figure instanceof HTMLElement) activateEmbed(figure);
+}
+/**
+* Lazy-embed island: facade button click → real `<iframe loading="lazy">`.
+* The companion of the content pipeline's `::embed` directive.
+*/
+const lazyEmbed = createComponent("lazy-embed", {
+	/**
+	* Bind the activation click handler when a facade mounts.
+	*
+	* @param ctx - The island lifecycle context.
+	* @example
+	* onMount(ctx);
+	*/
+	onMount(ctx) {
+		ctx.el.addEventListener("click", onFacadeClick);
+	},
+	/**
+	* Remove the activation click handler when the facade is destroyed.
+	*
+	* @param ctx - The island lifecycle context.
+	* @example
+	* onDestroy(ctx);
+	*/
+	onDestroy(ctx) {
+		ctx.el.removeEventListener("click", onFacadeClick);
+	}
+});
+//#endregion
 //#region src/plugins/spa/index.ts
 /**
 * @file spa — Complex Plugin (WIRING ONLY, ≤30 lines). All logic lives in the
@@ -11569,6 +11666,269 @@ function parseFrontmatter(raw, config) {
 	};
 }
 //#endregion
+//#region src/plugins/content/pipeline/embed.ts
+/** CSS class on the `<figure>` facade wrapping each embed. */
+const EMBED_FIGURE_CLASS = "lazy-embed";
+/** `data-component` name binding the facade to the `lazyEmbed` SPA island. */
+const EMBED_COMPONENT_NAME = "lazy-embed";
+/** CSS class on the facade's activation button. */
+const EMBED_BUTTON_CLASS = "lazy-embed-button";
+/** CSS class on the title span inside the activation button. */
+const EMBED_TITLE_CLASS = "lazy-embed-title";
+/**
+* Type guard for an `::embed` leaf directive.
+*
+* @param node - AST node to test.
+* @returns `true` when the node is an `::embed` leaf directive.
+* @example
+* ```ts
+* if (isEmbedDirective(node)) console.log(node.attributes?.src);
+* ```
+*/
+function isEmbedDirective(node) {
+	return node.type === "leafDirective" && node.name === "embed";
+}
+/**
+* Escape a string for safe interpolation into a double-quoted HTML attribute.
+*
+* @param value - The raw attribute value.
+* @returns The escaped value.
+* @example
+* ```ts
+* escapeAttribute('He said "hi" & left'); // "He said &quot;hi&quot; &amp; left"
+* ```
+*/
+function escapeAttribute(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
+}
+/**
+* Validate an embed `src` URL: only `https:`/`http:` absolute URLs and
+* root-relative paths are embeddable — anything else (`javascript:`, `data:`,
+* scheme-relative, …) fails the build.
+*
+* @param src - The raw `src` attribute value.
+* @returns `true` when the URL is embeddable.
+* @example
+* ```ts
+* isEmbeddableUrl("https://game.example.com/"); // true
+* isEmbeddableUrl("javascript:alert(1)"); // false
+* ```
+*/
+function isEmbeddableUrl(src) {
+	if (src.startsWith("/") && !src.startsWith("//")) return true;
+	return /^https?:\/\//i.test(src);
+}
+/**
+* Build the static facade HTML for one embed: the `<figure>` carrying the
+* target in data attributes plus the activation `<button>` (the button label
+* is the embed's title; visual chrome is consumer CSS).
+*
+* @param src - The validated embed URL.
+* @param title - The human-readable embed title (button label, iframe title).
+* @returns The facade HTML string.
+* @example
+* ```ts
+* embedFacadeHtml("https://game.example.com/", "My Game");
+* ```
+*/
+function embedFacadeHtml(src, title) {
+	const safeSource = escapeAttribute(src);
+	const safeTitle = escapeAttribute(title);
+	return `<figure class="${EMBED_FIGURE_CLASS}" data-component="${EMBED_COMPONENT_NAME}" data-embed-src="${safeSource}" data-embed-title="${safeTitle}"><button type="button" class="${EMBED_BUTTON_CLASS}" aria-label="Load embed: ${safeTitle}"><span class="${EMBED_TITLE_CLASS}">${safeTitle}</span></button></figure>`;
+}
+/**
+* Mdast transformer rewriting every `::embed` leaf directive to its facade
+* HTML node. A directive missing `src`/`title`, or carrying a non-embeddable
+* URL, fails the build with the offending value quoted.
+*
+* @param tree - The mdast tree to mutate.
+* @throws {Error} When an `::embed` directive is missing `src` or `title`, or
+* its `src` is not an embeddable URL.
+* @example
+* ```ts
+* embedTransform(tree);
+* ```
+*/
+function embedTransform(tree) {
+	(0, unist_util_visit.visit)(tree, (node, index, parent) => {
+		if (!isEmbedDirective(node)) return;
+		if (parent === void 0 || index === void 0) return;
+		const src = node.attributes?.src ?? "";
+		const title = node.attributes?.title ?? "";
+		if (src === "" || title === "") throw new Error("[web] content: `::embed` requires both `src` and `title` attributes, e.g. ::embed{src=\"https://…\" title=\"…\"}.");
+		if (!isEmbeddableUrl(src)) throw new Error(`[web] content: \`::embed\` src must be an http(s) URL or a root-relative path (got "${src}").`);
+		const html = {
+			type: "html",
+			value: embedFacadeHtml(src, title)
+		};
+		parent.children[index] = html;
+	});
+}
+/**
+* Remark transform: rewrites `::embed{src="…" title="…"}` leaf directives into
+* static click-to-activate facades (no iframe until the reader clicks — see
+* the file header). Opt-in via the provider's `embed` option; requires
+* `trustedContent: true` because the facade is raw HTML the sanitize pass
+* would strip.
+*
+* @returns An mdast tree transformer.
+* @example
+* ```ts
+* unified().use(embedPlugin);
+* ```
+*/
+function embedPlugin() {
+	return embedTransform;
+}
+//#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 +12064,35 @@ 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 embed + mermaid
+* transforms, then the mdast→hast bridge (`remark-rehype` with
+* `allowDangerousHtml`). Pull-quote, embed and mermaid run on the mdast before
+* the bridge — pull-quote so the directive carries its `hName`/`hProperties`,
+* embed so the directive is replaced with its raw facade HTML, mermaid so the
+* fence is replaced with raw SVG HTML before Shiki could ever claim the code
+* block.
+*
+* @param config - Optional provider configuration; only the opt-in flags are
+* read here: `mermaid` and `embed` (each truthy value enables its transform at
+* a 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?.embed) plugins.push(embedPlugin);
+	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 +12233,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 +12393,7 @@ async function discoverSlugs(dir) {
 * ```
 */
 function fileSystemContent(options) {
+	validateFileSystemContentOptions(options);
 	const state = {
 		processor: null,
 		slugs: null,
@@ -12273,6 +12645,7 @@ exports.headPlugin = headPlugin;
 exports.hreflang = hreflang;
 exports.i18nPlugin = i18nPlugin;
 exports.jsonLd = jsonLd;
+exports.lazyEmbed = lazyEmbed;
 exports.logPlugin = logPlugin;
 exports.meta = meta;
 exports.og = og;

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,24 @@ 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;
+  /**
+   * Lazy iframe embeds: rewrite `::embed{src="…" title="…"}` leaf directives
+   * into static click-to-activate facades (no iframe — and none of the target's
+   * network/JS cost — until the reader clicks). Pair with the `lazyEmbed` SPA
+   * island, which swaps the facade for the real `<iframe loading="lazy">`.
+   * Requires `trustedContent: true` (the facade is raw HTML the sanitize pass
+   * would strip). Defaults to disabled.
+   */
+  embed?: boolean;
 };
 /**
  * Internal mutable state of the filesystem provider: the lazy unified processor and
@@ -3447,6 +3495,13 @@ declare const sitePlugin: import("@moku-labs/core").PluginInstance<"site", Confi
  */
 declare function createComponent(name: string, hooks: ComponentHooks): ComponentDef;
 //#endregion
+//#region src/plugins/spa/lazy-embed.d.ts
+/**
+ * Lazy-embed island: facade button click → real `<iframe loading="lazy">`.
+ * The companion of the content pipeline's `::embed` directive.
+ */
+declare const lazyEmbed: ComponentDef;
+//#endregion
 //#region src/plugins/spa/index.d.ts
 /**
  * SPA plugin — progressive client-side navigation layered over the static site:
@@ -3648,4 +3703,4 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
  */
 declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$8, Events, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>>;
 //#endregion
-export { types_d_exports as Build, types_d_exports$1 as Cli, types_d_exports$2 as Content, types_d_exports$3 as Data, types_d_exports$4 as Deploy, types_d_exports$5 as Env, types_d_exports$6 as Head, types_d_exports$7 as Log, types_d_exports$8 as Router, types_d_exports$9 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_d_exports as Build, types_d_exports$1 as Cli, types_d_exports$2 as Content, types_d_exports$3 as Data, types_d_exports$4 as Deploy, types_d_exports$5 as Env, types_d_exports$6 as Head, types_d_exports$7 as Log, types_d_exports$8 as Router, types_d_exports$9 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };

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,24 @@ 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;
+  /**
+   * Lazy iframe embeds: rewrite `::embed{src="…" title="…"}` leaf directives
+   * into static click-to-activate facades (no iframe — and none of the target's
+   * network/JS cost — until the reader clicks). Pair with the `lazyEmbed` SPA
+   * island, which swaps the facade for the real `<iframe loading="lazy">`.
+   * Requires `trustedContent: true` (the facade is raw HTML the sanitize pass
+   * would strip). Defaults to disabled.
+   */
+  embed?: boolean;
 };
 /**
  * Internal mutable state of the filesystem provider: the lazy unified processor and
@@ -3447,6 +3495,13 @@ declare const sitePlugin: import("@moku-labs/core").PluginInstance<"site", Confi
  */
 declare function createComponent(name: string, hooks: ComponentHooks): ComponentDef;
 //#endregion
+//#region src/plugins/spa/lazy-embed.d.ts
+/**
+ * Lazy-embed island: facade button click → real `<iframe loading="lazy">`.
+ * The companion of the content pipeline's `::embed` directive.
+ */
+declare const lazyEmbed: ComponentDef;
+//#endregion
 //#region src/plugins/spa/index.d.ts
 /**
  * SPA plugin — progressive client-side navigation layered over the static site:
@@ -3648,4 +3703,4 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
  */
 declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$8, Events, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>>;
 //#endregion
-export { types_d_exports as Build, types_d_exports$1 as Cli, types_d_exports$2 as Content, types_d_exports$3 as Data, types_d_exports$4 as Deploy, types_d_exports$5 as Env, types_d_exports$6 as Head, types_d_exports$7 as Log, types_d_exports$8 as Router, types_d_exports$9 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_d_exports as Build, types_d_exports$1 as Cli, types_d_exports$2 as Content, types_d_exports$3 as Data, types_d_exports$4 as Deploy, types_d_exports$5 as Env, types_d_exports$6 as Head, types_d_exports$7 as Log, types_d_exports$8 as Router, types_d_exports$9 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };

package/dist/index.mjs

@@ -1567,6 +1567,25 @@ 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` or `embed` is enabled without
+* `trustedContent: true`: both emit raw HTML (inline SVG / the embed facade),
+* 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` or `embed` 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.");
+	if (Boolean(options.embed) && options.trustedContent !== true) throw new Error("[web] content: `embed` requires `trustedContent: true`.\n  Embed directives render to a raw-HTML facade, which the sanitize pass would strip\n  (and embedding third-party iframes is never safe for untrusted Markdown).\n  Set trustedContent: true ONLY for fully author-controlled Markdown.");
+}
 //#endregion
 //#region src/plugins/content/index.ts
 /**
@@ -11282,6 +11301,84 @@ function disposeSpa() {
 	}
 }
 //#endregion
+//#region src/plugins/spa/lazy-embed.ts
+/**
+* @file `lazyEmbed` island — activates the static embed facades emitted by the
+* content pipeline's `::embed` directive (pipeline/embed.ts). Mounts on every
+* `[data-component="lazy-embed"]` figure; a click on the facade's button swaps
+* it for the real `<iframe loading="lazy">`. Until that click the embedded
+* document costs the page nothing — no request, no third-party JS, no
+* scroll-jacking. Register it in `pluginConfigs.spa.components`; all visual
+* chrome (`.lazy-embed*` classes) is consumer CSS.
+*/
+/** CSS class on the injected `<iframe>` (consumer CSS sizes it). */
+const EMBED_FRAME_CLASS = "lazy-embed-frame";
+/**
+* Swap a facade `<figure>`'s content for its real `<iframe>`. The iframe
+* carries `loading="lazy"` plus fullscreen permission, and the figure gains
+* `data-embed-active` so consumer CSS can restyle the activated state.
+*
+* @param figure - The facade element carrying `data-embed-src`/`data-embed-title`.
+* @example
+* ```ts
+* activateEmbed(figure);
+* ```
+*/
+function activateEmbed(figure) {
+	const src = figure.dataset.embedSrc;
+	if (!src) return;
+	const iframe = document.createElement("iframe");
+	iframe.src = src;
+	iframe.title = figure.dataset.embedTitle ?? "";
+	iframe.className = EMBED_FRAME_CLASS;
+	iframe.setAttribute("loading", "lazy");
+	iframe.allow = "fullscreen; autoplay; gamepad";
+	iframe.allowFullscreen = true;
+	figure.replaceChildren(iframe);
+	figure.dataset.embedActive = "";
+}
+/**
+* Shared click handler (module-level so mount/unmount detach the same
+* reference): a click on the facade's button activates the embed.
+*
+* @param event - The click event from the facade figure.
+* @example
+* ```ts
+* element.addEventListener("click", onFacadeClick);
+* ```
+*/
+function onFacadeClick(event) {
+	if (!event.target.closest("button.lazy-embed-button")) return;
+	const figure = event.currentTarget;
+	if (figure instanceof HTMLElement) activateEmbed(figure);
+}
+/**
+* Lazy-embed island: facade button click → real `<iframe loading="lazy">`.
+* The companion of the content pipeline's `::embed` directive.
+*/
+const lazyEmbed = createComponent("lazy-embed", {
+	/**
+	* Bind the activation click handler when a facade mounts.
+	*
+	* @param ctx - The island lifecycle context.
+	* @example
+	* onMount(ctx);
+	*/
+	onMount(ctx) {
+		ctx.el.addEventListener("click", onFacadeClick);
+	},
+	/**
+	* Remove the activation click handler when the facade is destroyed.
+	*
+	* @param ctx - The island lifecycle context.
+	* @example
+	* onDestroy(ctx);
+	*/
+	onDestroy(ctx) {
+		ctx.el.removeEventListener("click", onFacadeClick);
+	}
+});
+//#endregion
 //#region src/plugins/spa/index.ts
 /**
 * @file spa — Complex Plugin (WIRING ONLY, ≤30 lines). All logic lives in the
@@ -11556,6 +11653,269 @@ function parseFrontmatter(raw, config) {
 	};
 }
 //#endregion
+//#region src/plugins/content/pipeline/embed.ts
+/** CSS class on the `<figure>` facade wrapping each embed. */
+const EMBED_FIGURE_CLASS = "lazy-embed";
+/** `data-component` name binding the facade to the `lazyEmbed` SPA island. */
+const EMBED_COMPONENT_NAME = "lazy-embed";
+/** CSS class on the facade's activation button. */
+const EMBED_BUTTON_CLASS = "lazy-embed-button";
+/** CSS class on the title span inside the activation button. */
+const EMBED_TITLE_CLASS = "lazy-embed-title";
+/**
+* Type guard for an `::embed` leaf directive.
+*
+* @param node - AST node to test.
+* @returns `true` when the node is an `::embed` leaf directive.
+* @example
+* ```ts
+* if (isEmbedDirective(node)) console.log(node.attributes?.src);
+* ```
+*/
+function isEmbedDirective(node) {
+	return node.type === "leafDirective" && node.name === "embed";
+}
+/**
+* Escape a string for safe interpolation into a double-quoted HTML attribute.
+*
+* @param value - The raw attribute value.
+* @returns The escaped value.
+* @example
+* ```ts
+* escapeAttribute('He said "hi" & left'); // "He said &quot;hi&quot; &amp; left"
+* ```
+*/
+function escapeAttribute(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
+}
+/**
+* Validate an embed `src` URL: only `https:`/`http:` absolute URLs and
+* root-relative paths are embeddable — anything else (`javascript:`, `data:`,
+* scheme-relative, …) fails the build.
+*
+* @param src - The raw `src` attribute value.
+* @returns `true` when the URL is embeddable.
+* @example
+* ```ts
+* isEmbeddableUrl("https://game.example.com/"); // true
+* isEmbeddableUrl("javascript:alert(1)"); // false
+* ```
+*/
+function isEmbeddableUrl(src) {
+	if (src.startsWith("/") && !src.startsWith("//")) return true;
+	return /^https?:\/\//i.test(src);
+}
+/**
+* Build the static facade HTML for one embed: the `<figure>` carrying the
+* target in data attributes plus the activation `<button>` (the button label
+* is the embed's title; visual chrome is consumer CSS).
+*
+* @param src - The validated embed URL.
+* @param title - The human-readable embed title (button label, iframe title).
+* @returns The facade HTML string.
+* @example
+* ```ts
+* embedFacadeHtml("https://game.example.com/", "My Game");
+* ```
+*/
+function embedFacadeHtml(src, title) {
+	const safeSource = escapeAttribute(src);
+	const safeTitle = escapeAttribute(title);
+	return `<figure class="${EMBED_FIGURE_CLASS}" data-component="${EMBED_COMPONENT_NAME}" data-embed-src="${safeSource}" data-embed-title="${safeTitle}"><button type="button" class="${EMBED_BUTTON_CLASS}" aria-label="Load embed: ${safeTitle}"><span class="${EMBED_TITLE_CLASS}">${safeTitle}</span></button></figure>`;
+}
+/**
+* Mdast transformer rewriting every `::embed` leaf directive to its facade
+* HTML node. A directive missing `src`/`title`, or carrying a non-embeddable
+* URL, fails the build with the offending value quoted.
+*
+* @param tree - The mdast tree to mutate.
+* @throws {Error} When an `::embed` directive is missing `src` or `title`, or
+* its `src` is not an embeddable URL.
+* @example
+* ```ts
+* embedTransform(tree);
+* ```
+*/
+function embedTransform(tree) {
+	visit(tree, (node, index, parent) => {
+		if (!isEmbedDirective(node)) return;
+		if (parent === void 0 || index === void 0) return;
+		const src = node.attributes?.src ?? "";
+		const title = node.attributes?.title ?? "";
+		if (src === "" || title === "") throw new Error("[web] content: `::embed` requires both `src` and `title` attributes, e.g. ::embed{src=\"https://…\" title=\"…\"}.");
+		if (!isEmbeddableUrl(src)) throw new Error(`[web] content: \`::embed\` src must be an http(s) URL or a root-relative path (got "${src}").`);
+		const html = {
+			type: "html",
+			value: embedFacadeHtml(src, title)
+		};
+		parent.children[index] = html;
+	});
+}
+/**
+* Remark transform: rewrites `::embed{src="…" title="…"}` leaf directives into
+* static click-to-activate facades (no iframe until the reader clicks — see
+* the file header). Opt-in via the provider's `embed` option; requires
+* `trustedContent: true` because the facade is raw HTML the sanitize pass
+* would strip.
+*
+* @returns An mdast tree transformer.
+* @example
+* ```ts
+* unified().use(embedPlugin);
+* ```
+*/
+function embedPlugin() {
+	return embedTransform;
+}
+//#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 +12051,35 @@ 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 embed + mermaid
+* transforms, then the mdast→hast bridge (`remark-rehype` with
+* `allowDangerousHtml`). Pull-quote, embed and mermaid run on the mdast before
+* the bridge — pull-quote so the directive carries its `hName`/`hProperties`,
+* embed so the directive is replaced with its raw facade HTML, mermaid so the
+* fence is replaced with raw SVG HTML before Shiki could ever claim the code
+* block.
+*
+* @param config - Optional provider configuration; only the opt-in flags are
+* read here: `mermaid` and `embed` (each truthy value enables its transform at
+* a 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?.embed) plugins.push(embedPlugin);
+	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 +12220,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 +12380,7 @@ async function discoverSlugs(dir) {
 * ```
 */
 function fileSystemContent(options) {
+	validateFileSystemContentOptions(options);
 	const state = {
 		processor: null,
 		slugs: null,
@@ -12178,4 +12550,4 @@ const createApp = core.createApp;
 */
 const createPlugin = core.createPlugin;
 //#endregion
-export { types_exports as Build, types_exports$1 as Cli, types_exports$2 as Content, types_exports$3 as Data, types_exports$4 as Deploy, types_exports$5 as Env, types_exports$6 as Head, types_exports$7 as Log, types_exports$8 as Router, types_exports$9 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_exports as Build, types_exports$1 as Cli, types_exports$2 as Content, types_exports$3 as Data, types_exports$4 as Deploy, types_exports$5 as Env, types_exports$6 as Head, types_exports$7 as Log, types_exports$8 as Router, types_exports$9 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };

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.10.0"
 }