hdoc-tools 0.61.0 → 0.62.0

package/hdoc-mermaid.js

@@ -1,204 +1,204 @@
-// In-process Mermaid -> SVG renderer.
-//
-// Replaces the previous `@mermaid-js/mermaid-cli` (mmdc) integration. Instead of
-// shelling out to the CLI (which spawned a fresh Chromium per diagram and pinned
-// puppeteer to <=24 via its peerDependency), this renders Mermaid using the
-// `mermaid` library directly inside a puppeteer browser supplied by the caller —
-// the very same browser hdoc-build already launches for PDF/link work.
-//
-// The render path (Interceptor + page evaluation) is ported from mermaid-cli
-// (MIT licensed): https://github.com/mermaid-js/mermaid-cli
-// Trimmed to the SVG-only case we need, plus ELK layout support (required by
-// books that use `layout: elk`). zenuml / tidy-tree / icon-packs / png / pdf are
-// intentionally dropped — no hdocbook content uses them.
-
-const { readFile, realpath } = require("node:fs/promises");
-const path = require("node:path");
-const url = require("node:url");
-
-// ESM bundle locations inside the installed packages. Both packages expose
-// "./*": "./*" in their exports map, so the dist files resolve directly.
-const mermaidESMPath = require.resolve("mermaid/dist/mermaid.esm.mjs");
-const elkESMPath = require.resolve(
-	"@mermaid-js/layout-elk/dist/mermaid-layout-elk.esm.mjs",
-);
-
-/**
- * Guesses the MIME-type of a file based on its extension. Only the handful of
- * types the Mermaid ESM bundles actually request are supported.
- */
-function getContentTypeFromFileExtension(filePath) {
-	const ext = path.extname(filePath).toLowerCase();
-	switch (ext) {
-		case ".css":
-			// Force UTF-8 so puppeteer doesn't mis-parse as Latin-1.
-			return "text/css;charset=UTF-8";
-		case ".js":
-		case ".mjs":
-			return "application/javascript";
-		case ".woff2":
-			return "font/woff2";
-		default:
-			throw new Error(`Unsupported file extension for intercept: ${ext}`);
-	}
-}
-
-/**
- * Puppeteer can't `import` ESM modules from `file://` URLs. Rather than stand up
- * a real HTTP server (ports/firewalls), we intercept requests to a dummy
- * `https://hdoc-mermaid-intercept.invalid` origin and serve the corresponding
- * local file. Ported verbatim from mermaid-cli's puppeteerIntercept.js.
- */
-class Interceptor {
-	#INTERCEPT_ORIGIN = "https://hdoc-mermaid-intercept.invalid";
-
-	/** @type {Set<string>} resolved (realpath) dirs allowed to be served. */
-	#allowedDirs = new Set();
-
-	async fileUrlToInterceptUrl(fileUrl, { allowParentDirectoryLevel = 1 } = {}) {
-		fileUrl = new URL(fileUrl);
-		if (fileUrl.protocol !== "file:") {
-			throw new Error(`Invalid file URL: ${fileUrl}`);
-		}
-		let parentDirectory = await realpath(url.fileURLToPath(fileUrl));
-		while (allowParentDirectoryLevel-- >= 0) {
-			parentDirectory = path.dirname(parentDirectory);
-		}
-		this.#allowedDirs.add(parentDirectory);
-		return `${this.#INTERCEPT_ORIGIN}${fileUrl.pathname}`;
-	}
-
-	async interceptUrlToFileUrl(interceptUrl) {
-		interceptUrl = new URL(interceptUrl);
-		if (interceptUrl.origin !== this.#INTERCEPT_ORIGIN) {
-			throw new Error(`Invalid intercept URL: ${interceptUrl}`);
-		}
-		const fileUrl = new URL(
-			interceptUrl.href.slice(this.#INTERCEPT_ORIGIN.length),
-			"file://",
-		);
-		const filePath = await realpath(url.fileURLToPath(fileUrl));
-		if (
-			![...this.#allowedDirs].some((dir) =>
-				path.relative(filePath, dir).startsWith(".."),
-			)
-		) {
-			throw new Error(
-				`Intercept URL is not in an allowed directory: ${interceptUrl}`,
-			);
-		}
-		return fileUrl;
-	}
-
-	async #interceptRequestHandler(request) {
-		try {
-			if (request.url().startsWith(this.#INTERCEPT_ORIGIN)) {
-				const fileUrl = await this.interceptUrlToFileUrl(request.url());
-				return request.respond({
-					status: 200,
-					headers: { "Access-Control-Allow-Origin": "*" },
-					contentType: getContentTypeFromFileExtension(
-						url.fileURLToPath(fileUrl),
-					),
-					body: await readFile(fileUrl),
-				});
-			}
-		} catch (error) {
-			console.error(
-				`Error handling intercept request for ${request.url()}:`,
-				error,
-			);
-			request.abort();
-			return;
-		}
-		request.continue();
-	}
-
-	get interceptRequestHandler() {
-		return this.#interceptRequestHandler.bind(this);
-	}
-}
-
-/**
- * Render a single Mermaid definition to an SVG string.
- *
- * @param {import('puppeteer').Browser} browser - An open puppeteer browser.
- * @param {string} definition - Mermaid source (may include `--- config: ---` frontmatter).
- * @param {{ backgroundColor?: string }} [opts]
- * @returns {Promise<string>} the serialized `<svg>`.
- */
-async function render_svg(browser, definition, { backgroundColor = "transparent" } = {}) {
-	const page = await browser.newPage();
-	// Surface in-page warnings/errors (e.g. mermaid parse errors) to the build log.
-	page.on("console", (msg) => {
-		if (msg.type() === "error" || msg.type() === "warning") {
-			console.warn(msg.text());
-		}
-	});
-	try {
-		await page.setContent(
-			"<!doctype html><html><body><div id=\"container\"></div></body></html>",
-		);
-		await page.$eval(
-			"body",
-			(body, bg) => {
-				body.style.background = bg;
-			},
-			backgroundColor,
-		);
-
-		const interceptor = new Interceptor();
-		const mermaidUrl = await interceptor.fileUrlToInterceptUrl(
-			url.pathToFileURL(mermaidESMPath),
-		);
-		const elkUrl = await interceptor.fileUrlToInterceptUrl(
-			url.pathToFileURL(elkESMPath),
-		);
-
-		page.on("request", interceptor.interceptRequestHandler);
-		await page.setRequestInterception(true);
-
-		await page.$eval(
-			"#container",
-			async (container, { definition, mermaidUrl, elkUrl, backgroundColor }) => {
-				const { default: mermaid } = await import(mermaidUrl);
-				const { default: elkLayouts } = await import(elkUrl);
-
-				await Promise.all(
-					Array.from(document.fonts, (font) => font.load()),
-				);
-
-				mermaid.registerLayoutLoaders(elkLayouts);
-				mermaid.initialize({ startOnLoad: false });
-
-				// Throws on invalid diagrams — propagates out of $eval as a rejection.
-				const { svg: svgText } = await mermaid.render(
-					"hdoc-svg",
-					definition,
-					container,
-				);
-				container.innerHTML = svgText;
-
-				const svg = container.getElementsByTagName?.("svg")?.[0];
-				if (svg?.style) {
-					svg.style.backgroundColor = backgroundColor;
-				}
-			},
-			{ definition, mermaidUrl, elkUrl, backgroundColor },
-		);
-
-		// Serialize via XMLSerializer so HTML <foreignObject> content (e.g. <br>)
-		// becomes valid XML in the saved .svg file.
-		const svgXML = await page.$eval("svg", (svg) => {
-			// eslint-disable-next-line no-undef
-			const xmlSerializer = new XMLSerializer();
-			return xmlSerializer.serializeToString(svg);
-		});
-
-		return svgXML;
-	} finally {
-		await page.close();
-	}
-}
-
-module.exports = { render_svg, Interceptor };
+// In-process Mermaid -> SVG renderer.
+//
+// Replaces the previous `@mermaid-js/mermaid-cli` (mmdc) integration. Instead of
+// shelling out to the CLI (which spawned a fresh Chromium per diagram and pinned
+// puppeteer to <=24 via its peerDependency), this renders Mermaid using the
+// `mermaid` library directly inside a puppeteer browser supplied by the caller —
+// the very same browser hdoc-build already launches for PDF/link work.
+//
+// The render path (Interceptor + page evaluation) is ported from mermaid-cli
+// (MIT licensed): https://github.com/mermaid-js/mermaid-cli
+// Trimmed to the SVG-only case we need, plus ELK layout support (required by
+// books that use `layout: elk`). zenuml / tidy-tree / icon-packs / png / pdf are
+// intentionally dropped — no hdocbook content uses them.
+
+const { readFile, realpath } = require("node:fs/promises");
+const path = require("node:path");
+const url = require("node:url");
+
+// ESM bundle locations inside the installed packages. Both packages expose
+// "./*": "./*" in their exports map, so the dist files resolve directly.
+const mermaidESMPath = require.resolve("mermaid/dist/mermaid.esm.mjs");
+const elkESMPath = require.resolve(
+	"@mermaid-js/layout-elk/dist/mermaid-layout-elk.esm.mjs",
+);
+
+/**
+ * Guesses the MIME-type of a file based on its extension. Only the handful of
+ * types the Mermaid ESM bundles actually request are supported.
+ */
+function getContentTypeFromFileExtension(filePath) {
+	const ext = path.extname(filePath).toLowerCase();
+	switch (ext) {
+		case ".css":
+			// Force UTF-8 so puppeteer doesn't mis-parse as Latin-1.
+			return "text/css;charset=UTF-8";
+		case ".js":
+		case ".mjs":
+			return "application/javascript";
+		case ".woff2":
+			return "font/woff2";
+		default:
+			throw new Error(`Unsupported file extension for intercept: ${ext}`);
+	}
+}
+
+/**
+ * Puppeteer can't `import` ESM modules from `file://` URLs. Rather than stand up
+ * a real HTTP server (ports/firewalls), we intercept requests to a dummy
+ * `https://hdoc-mermaid-intercept.invalid` origin and serve the corresponding
+ * local file. Ported verbatim from mermaid-cli's puppeteerIntercept.js.
+ */
+class Interceptor {
+	#INTERCEPT_ORIGIN = "https://hdoc-mermaid-intercept.invalid";
+
+	/** @type {Set<string>} resolved (realpath) dirs allowed to be served. */
+	#allowedDirs = new Set();
+
+	async fileUrlToInterceptUrl(fileUrl, { allowParentDirectoryLevel = 1 } = {}) {
+		fileUrl = new URL(fileUrl);
+		if (fileUrl.protocol !== "file:") {
+			throw new Error(`Invalid file URL: ${fileUrl}`);
+		}
+		let parentDirectory = await realpath(url.fileURLToPath(fileUrl));
+		while (allowParentDirectoryLevel-- >= 0) {
+			parentDirectory = path.dirname(parentDirectory);
+		}
+		this.#allowedDirs.add(parentDirectory);
+		return `${this.#INTERCEPT_ORIGIN}${fileUrl.pathname}`;
+	}
+
+	async interceptUrlToFileUrl(interceptUrl) {
+		interceptUrl = new URL(interceptUrl);
+		if (interceptUrl.origin !== this.#INTERCEPT_ORIGIN) {
+			throw new Error(`Invalid intercept URL: ${interceptUrl}`);
+		}
+		const fileUrl = new URL(
+			interceptUrl.href.slice(this.#INTERCEPT_ORIGIN.length),
+			"file://",
+		);
+		const filePath = await realpath(url.fileURLToPath(fileUrl));
+		if (
+			![...this.#allowedDirs].some((dir) =>
+				path.relative(filePath, dir).startsWith(".."),
+			)
+		) {
+			throw new Error(
+				`Intercept URL is not in an allowed directory: ${interceptUrl}`,
+			);
+		}
+		return fileUrl;
+	}
+
+	async #interceptRequestHandler(request) {
+		try {
+			if (request.url().startsWith(this.#INTERCEPT_ORIGIN)) {
+				const fileUrl = await this.interceptUrlToFileUrl(request.url());
+				return request.respond({
+					status: 200,
+					headers: { "Access-Control-Allow-Origin": "*" },
+					contentType: getContentTypeFromFileExtension(
+						url.fileURLToPath(fileUrl),
+					),
+					body: await readFile(fileUrl),
+				});
+			}
+		} catch (error) {
+			console.error(
+				`Error handling intercept request for ${request.url()}:`,
+				error,
+			);
+			request.abort();
+			return;
+		}
+		request.continue();
+	}
+
+	get interceptRequestHandler() {
+		return this.#interceptRequestHandler.bind(this);
+	}
+}
+
+/**
+ * Render a single Mermaid definition to an SVG string.
+ *
+ * @param {import('puppeteer').Browser} browser - An open puppeteer browser.
+ * @param {string} definition - Mermaid source (may include `--- config: ---` frontmatter).
+ * @param {{ backgroundColor?: string }} [opts]
+ * @returns {Promise<string>} the serialized `<svg>`.
+ */
+async function render_svg(browser, definition, { backgroundColor = "transparent" } = {}) {
+	const page = await browser.newPage();
+	// Surface in-page warnings/errors (e.g. mermaid parse errors) to the build log.
+	page.on("console", (msg) => {
+		if (msg.type() === "error" || msg.type() === "warning") {
+			console.warn(msg.text());
+		}
+	});
+	try {
+		await page.setContent(
+			"<!doctype html><html><body><div id=\"container\"></div></body></html>",
+		);
+		await page.$eval(
+			"body",
+			(body, bg) => {
+				body.style.background = bg;
+			},
+			backgroundColor,
+		);
+
+		const interceptor = new Interceptor();
+		const mermaidUrl = await interceptor.fileUrlToInterceptUrl(
+			url.pathToFileURL(mermaidESMPath),
+		);
+		const elkUrl = await interceptor.fileUrlToInterceptUrl(
+			url.pathToFileURL(elkESMPath),
+		);
+
+		page.on("request", interceptor.interceptRequestHandler);
+		await page.setRequestInterception(true);
+
+		await page.$eval(
+			"#container",
+			async (container, { definition, mermaidUrl, elkUrl, backgroundColor }) => {
+				const { default: mermaid } = await import(mermaidUrl);
+				const { default: elkLayouts } = await import(elkUrl);
+
+				await Promise.all(
+					Array.from(document.fonts, (font) => font.load()),
+				);
+
+				mermaid.registerLayoutLoaders(elkLayouts);
+				mermaid.initialize({ startOnLoad: false });
+
+				// Throws on invalid diagrams — propagates out of $eval as a rejection.
+				const { svg: svgText } = await mermaid.render(
+					"hdoc-svg",
+					definition,
+					container,
+				);
+				container.innerHTML = svgText;
+
+				const svg = container.getElementsByTagName?.("svg")?.[0];
+				if (svg?.style) {
+					svg.style.backgroundColor = backgroundColor;
+				}
+			},
+			{ definition, mermaidUrl, elkUrl, backgroundColor },
+		);
+
+		// Serialize via XMLSerializer so HTML <foreignObject> content (e.g. <br>)
+		// becomes valid XML in the saved .svg file.
+		const svgXML = await page.$eval("svg", (svg) => {
+			// eslint-disable-next-line no-undef
+			const xmlSerializer = new XMLSerializer();
+			return xmlSerializer.serializeToString(svg);
+		});
+
+		return svgXML;
+	} finally {
+		await page.close();
+	}
+}
+
+module.exports = { render_svg, Interceptor };