@clarify-labs/cli 0.10.1 → 0.10.3

package/output/{engine-5bdNX2Oo.cjs → engine-BDdPszs2.cjs}

@@ -27,14 +27,20 @@ let _tailwindcss_vite = require("@tailwindcss/vite");
 _tailwindcss_vite = __toESM(_tailwindcss_vite, 1);
 let _vitejs_plugin_react = require("@vitejs/plugin-react");
 _vitejs_plugin_react = __toESM(_vitejs_plugin_react, 1);
+let rehype_raw = require("rehype-raw");
+rehype_raw = __toESM(rehype_raw, 1);
 let _mdx_js_mdx = require("@mdx-js/mdx");
-let github_slugger = require("github-slugger");
-github_slugger = __toESM(github_slugger, 1);
-let mdast_util_to_string = require("mdast-util-to-string");
+let _shikijs_rehype = require("@shikijs/rehype");
+_shikijs_rehype = __toESM(_shikijs_rehype, 1);
+let rehype_slug = require("rehype-slug");
+rehype_slug = __toESM(rehype_slug, 1);
 let shiki = require("shiki");
 let unist_util_visit = require("unist-util-visit");
 let _clarify_labs_renderer = require("@clarify-labs/renderer");
 let node_fs_promises = require("node:fs/promises");
+let github_slugger = require("github-slugger");
+github_slugger = __toESM(github_slugger, 1);
+let mdast_util_to_string = require("mdast-util-to-string");
 let remark = require("remark");
 let gray_matter = require("gray-matter");
 gray_matter = __toESM(gray_matter, 1);
@@ -47,38 +53,29 @@ let _apidevtools_swagger_parser = require("@apidevtools/swagger-parser");
 _apidevtools_swagger_parser = __toESM(_apidevtools_swagger_parser, 1);
 let node_os = require("node:os");
 let node_module = require("node:module");
-//#region source/parsers/markdown/utils.ts
-function escapeHtml(text) {
-	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+//#region source/parsers/content/diagnostic.ts
+function displayPath(filePath, projectRoot) {
+	if (!filePath) return void 0;
+	if (!projectRoot) return filePath.replace(/^[A-Za-z]:\//, "").replace(/^\/+/, "");
+	const normalized = (0, node_path.relative)(projectRoot, filePath);
+	return normalized && !normalized.startsWith("..") && !(0, node_path.isAbsolute)(normalized) ? normalized : filePath.replace(/^[A-Za-z]:\//, "").replace(/^\/+/, "");
+}
+function createContentDiagnostic(options) {
+	const { error } = options;
+	return {
+		kind: options.kind,
+		title: options.title,
+		message: options.message,
+		filePath: displayPath(options.filePath, options.projectRoot),
+		details: error instanceof Error ? options.includeStack ? error.stack ?? error.message : error.message : String(error)
+	};
 }
 //#endregion
 //#region source/parsers/markdown/mdx.ts
 function getLanguage(className) {
 	return (Array.isArray(className) ? className : typeof className === "string" ? className.split(/\s+/) : []).find((item) => typeof item === "string" && item.startsWith("language-"))?.replace(/^language-/, "") || "txt";
 }
-function getTextContent(node) {
-	if (!node) return "";
-	if (typeof node.value === "string") return node.value;
-	return node.children?.map(getTextContent).join("") ?? "";
-}
-function renderPlainCode(code) {
-	return code.split("\n").map((line) => `<span>${escapeHtml(line)}</span>`).join("\n");
-}
-function isBundledLanguage(language) {
-	return language in shiki.bundledLanguages;
-}
-var highlighterPromise;
 var cssVariablesTheme = (0, shiki.createCssVariablesTheme)();
-async function getHighlighter() {
-	highlighterPromise = highlighterPromise ?? (0, shiki.createHighlighter)({
-		themes: [cssVariablesTheme],
-		langs: []
-	});
-	return highlighterPromise;
-}
-function renderHighlightedCode(html) {
-	return (/<code[^>]*>([\s\S]*?)<\/code>/.exec(html)?.[1] ?? html).split("\n").map((line) => line.trimStart().startsWith("<span") ? line : `<span>${line}</span>`).join("\n");
-}
 function rehypeParseCodeBlocks() {
 	return (tree) => {
 		(0, unist_util_visit.visit)(tree, "element", (node, _nodeIndex, parentNode) => {
@@ -96,65 +93,31 @@ function rehypeParseCodeBlocks() {
 		});
 	};
 }
-function rehypeShiki() {
-	return async (tree) => {
-		const shikiHighlighter = await getHighlighter();
-		const languages = /* @__PURE__ */ new Set();
-		(0, unist_util_visit.visit)(tree, "element", (node) => {
-			if (node.tagName !== "pre") return;
-			const codeNode = node.children?.[0];
-			if (codeNode?.tagName !== "code") return;
-			const language = typeof node.properties?.language === "string" ? node.properties.language : getLanguage(codeNode.properties?.className);
-			if (language && language !== "txt" && isBundledLanguage(language)) languages.add(language);
-		});
-		if (languages.size > 0) await shikiHighlighter.loadLanguage(...languages);
-		(0, unist_util_visit.visit)(tree, "element", (node) => {
-			if (node.tagName !== "pre") return;
-			const codeNode = node.children?.[0];
-			if (codeNode?.tagName !== "code") return;
-			node.properties = node.properties ?? {};
-			codeNode.properties = codeNode.properties ?? {};
-			const code = getTextContent(codeNode);
-			const language = typeof node.properties.language === "string" ? node.properties.language : getLanguage(codeNode.properties.className);
-			node.properties.code = code;
-			codeNode.properties.code = code;
-			codeNode.properties.language = language;
-			let highlighted = renderPlainCode(code);
-			if (language && language !== "txt") try {
-				highlighted = renderHighlightedCode(shikiHighlighter.codeToHtml(code, {
-					lang: language,
-					theme: cssVariablesTheme
-				}));
-			} catch {
-				highlighted = renderPlainCode(code);
-			}
-			codeNode.children = [{
-				type: "text",
-				value: highlighted
-			}];
-		});
-	};
-}
-function rehypeSlugSections() {
-	return (tree) => {
-		const slugger = new github_slugger.default();
-		(0, unist_util_visit.visit)(tree, "element", (node) => {
-			if (node.tagName !== "h2" && node.tagName !== "h3") return;
-			node.properties = node.properties ?? {};
-			if (node.properties.id) return;
-			node.properties.id = slugger.slug((0, mdast_util_to_string.toString)(node));
-		});
-	};
-}
 var remarkPlugins = _clarify_labs_renderer.markdownRemarkPlugins;
 var rehypePlugins = [
-	rehypeSlugSections,
+	rehype_slug.default,
 	rehypeParseCodeBlocks,
-	rehypeShiki
+	[_shikijs_rehype.default, {
+		theme: cssVariablesTheme,
+		langs: [],
+		lazy: true,
+		addLanguageClass: true,
+		fallbackLanguage: "text",
+		parseMetaString: _clarify_labs_renderer.parseCodeMeta
+	}]
 ];
-function formatMdxDiagnostic(error) {
-	if (error instanceof Error) return error.message;
-	return String(error);
+function createContentCompileDiagnostic(options) {
+	const { format, phase, error, filePath, projectRoot } = options;
+	const label = format === "mdx" ? "MDX" : "Markdown";
+	return createContentDiagnostic({
+		kind: format,
+		title: `${label} ${phase} error`,
+		message: phase === "syntax" ? "This page could not be compiled. Fix the MDX syntax or component usage above, then reload the route." : `This page could not be compiled. Fix the ${label} syntax or plugin error below, then reload the route.`,
+		error,
+		filePath,
+		projectRoot,
+		includeStack: phase === "compilation"
+	});
 }
 /**
 * Validate MDX content for diagnostics WITHOUT running the build-time rehype
@@ -162,7 +125,8 @@ function formatMdxDiagnostic(error) {
 *
 * `rehypePlugins` includes `rehypeShiki`, which loads grammar/WASM assets and
 * is expensive. The real highlighting happens at Vite build time via the
-* `@mdx-js/rollup` plugin (see `createMdxPlugin` in `core/adapters.ts`), which
+* `@mdx-js/rollup` plugins (see `createMarkdownPlugin` and `createMdxPlugin`
+* in `core/adapters.ts`), which
 * runs the full remark + rehype pipeline. Re-running it here, during route
 * discovery (Phase 3), would compile every `.mdx` file twice and invoke Shiki
 * once per file per `engine.refresh()` — see ARCHITECTURE.md §2.2 which states
@@ -184,13 +148,13 @@ async function compileMdxContent(content, filePath, projectRoot) {
 	} catch (error) {
 		return {
 			ok: false,
-			diagnostic: {
-				kind: "mdx",
-				title: "MDX syntax error",
-				message: "This page could not be compiled. Fix the MDX syntax or component usage above, then reload the route.",
-				filePath: filePath && projectRoot ? filePath.replace(projectRoot + "/", "").replace(/^\/+/, "") : filePath ? filePath.replace(/^[A-Za-z]:\//, "").replace(/^\/+/, "") : void 0,
-				details: formatMdxDiagnostic(error)
-			}
+			diagnostic: createContentCompileDiagnostic({
+				format: "mdx",
+				phase: "syntax",
+				error,
+				filePath,
+				projectRoot
+			})
 		};
 	}
 }
@@ -311,6 +275,11 @@ function kebabToTitle(str) {
 function parseMdxTree(content) {
 	return remark.remark.parse(content);
 }
+async function compileRouteDiagnostic(content, filePath, baseDir) {
+	if ((0, node_path.extname)(filePath).toLowerCase() !== ".mdx") return void 0;
+	const result = await compileMdxContent(content, filePath, baseDir);
+	return result.ok ? void 0 : result.diagnostic;
+}
 /** 从内容中提取第一个 H1 标题 */
 function extractH1(content) {
 	const tree = parseMdxTree(content);
@@ -405,7 +374,7 @@ async function findContentRoutes(dir, base = dir, options = {}) {
 				frontmatter,
 				content
 			};
-			const mdxResult = await compileMdxContent(page.content, fullPath, base);
+			const diagnostic = await compileRouteDiagnostic(page.content, fullPath, base);
 			let title = typeof page.frontmatter.title === "string" ? page.frontmatter.title : "";
 			if (!title) {
 				const lastPart = pathParts[pathParts.length - 1] ?? "";
@@ -427,7 +396,7 @@ async function findContentRoutes(dir, base = dir, options = {}) {
 					frontmatter: page.frontmatter,
 					content: page.content
 				},
-				diagnostic: mdxResult.ok ? void 0 : mdxResult.diagnostic
+				diagnostic
 			});
 		}
 	}
@@ -541,6 +510,7 @@ function routeIntentFromPagesItem(item) {
 		kind: "page",
 		ref: item
 	};
+	if ("group" in item) throw new Error("Navigation groups do not resolve to route intents");
 	if ("openapi" in item) return {
 		kind: "openapi",
 		ref: item.openapi,
@@ -568,15 +538,19 @@ function firstNavigationPath(nodes) {
 }
 function collectExplicitPagePathIntents(tabs) {
 	const intents = [];
-	for (const tab of tabs ?? []) {
-		if (!tab.pages || tab.pages === "FileTree") continue;
-		for (const group of tab.pages) for (const item of group.pages) if (typeof item !== "string" && "page" in item && item.path) {
+	const collectItems = (items) => {
+		for (const item of items) if (typeof item !== "string" && "group" in item) collectItems(item.pages);
+		else if (typeof item !== "string" && "page" in item && item.path) {
 			const intent = routeIntentFromPagesItem(item);
 			if (intent.kind === "page" && intent.path) intents.push({
 				...intent,
 				path: intent.path
 			});
 		}
+	};
+	for (const tab of tabs ?? []) {
+		if (!tab.pages || tab.pages === "FileTree") continue;
+		for (const group of tab.pages) collectItems(group.pages);
 	}
 	return intents;
 }
@@ -627,28 +601,38 @@ function buildNavigationFromTabsConfig(routes, tabs) {
 }
 function buildNavigationFromConfig(routes, config) {
 	const routeMap = new Map(routes.map((r) => [r.path, r]));
-	return config.map((group) => {
-		const children = group.pages.map((item) => {
-			const intent = routeIntentFromPagesItem(item);
-			if (intent.kind === "openapi") {
-				const path = openAPIPagePathFromRef(intent.ref, intent.tagFilter, intent.path);
-				const route = routeMap.get(path);
-				return {
-					path,
-					title: resolveLocalizedText(intent.title, "", "") ?? route?.meta.title ?? kebabToTitle(path.split("/").pop() ?? intent.ref),
-					icon: intent.icon,
-					sections: route?.meta.sections ? navigationSections(route.meta.sections) : void 0
-				};
-			}
-			const path = routePathFromRef(intent.ref, intent.path);
+	const buildItem = (item) => {
+		if (typeof item !== "string" && "group" in item) {
+			const children = item.pages.map(buildItem);
+			return {
+				path: firstNavigationPath(children),
+				title: resolveLocalizedText(item.group, "", "") ?? "",
+				icon: item.icon,
+				children
+			};
+		}
+		const intent = routeIntentFromPagesItem(item);
+		if (intent.kind === "openapi") {
+			const path = openAPIPagePathFromRef(intent.ref, intent.tagFilter, intent.path);
 			const route = routeMap.get(path);
 			return {
-				path: intent.redirect ? normalizePath(intent.redirect) : path,
+				path,
 				title: resolveLocalizedText(intent.title, "", "") ?? route?.meta.title ?? kebabToTitle(path.split("/").pop() ?? intent.ref),
 				icon: intent.icon,
 				sections: route?.meta.sections ? navigationSections(route.meta.sections) : void 0
 			};
-		});
+		}
+		const path = routePathFromRef(intent.ref, intent.path);
+		const route = routeMap.get(path);
+		return {
+			path: intent.redirect ? normalizePath(intent.redirect) : path,
+			title: resolveLocalizedText(intent.title, "", "") ?? route?.meta.title ?? kebabToTitle(path.split("/").pop() ?? intent.ref),
+			icon: intent.icon,
+			sections: route?.meta.sections ? navigationSections(route.meta.sections) : void 0
+		};
+	};
+	return config.map((group) => {
+		const children = group.pages.map(buildItem);
 		return {
 			path: children[0]?.path ?? "/",
 			title: resolveLocalizedText(group.group, "", "") ?? "",
@@ -670,19 +654,29 @@ function buildLocalizedNavigationForLocale(routes, config, locale, i18n) {
 		path: route.basePath ?? route.path
 	}))), locale, i18n);
 	const routeMap = new Map(routes.map((route) => [route.basePath ?? route.path, route]));
-	return config.map((group) => {
-		const children = group.pages.map((item) => {
-			const intent = routeIntentFromPagesItem(item);
-			const basePath = intent.kind === "openapi" ? openAPIPagePathFromRef(intent.ref, intent.tagFilter, intent.path) : routePathFromRef(intent.ref, intent.path);
-			const route = routeMap.get(basePath);
-			const path = route?.path ?? localizedRoutePath(basePath, locale, i18n);
+	const buildItem = (item) => {
+		if (typeof item !== "string" && "group" in item) {
+			const children = item.pages.map(buildItem);
 			return {
-				path: (intent.kind === "page" && intent.redirect ? localizedRoutePath(routePathFromRef(intent.redirect), locale, i18n) : void 0) ?? path,
-				title: resolveLocalizedText(intent.title, locale, i18n.defaultLocale) ?? route?.meta.title ?? kebabToTitle(basePath.split("/").pop() ?? intent.ref),
-				icon: intent.icon,
-				sections: route?.meta.sections ? navigationSections(route.meta.sections) : void 0
+				path: firstNavigationPath(children),
+				title: resolveLocalizedText(item.group, locale, i18n.defaultLocale) ?? "",
+				icon: item.icon,
+				children
 			};
-		});
+		}
+		const intent = routeIntentFromPagesItem(item);
+		const basePath = intent.kind === "openapi" ? openAPIPagePathFromRef(intent.ref, intent.tagFilter, intent.path) : routePathFromRef(intent.ref, intent.path);
+		const route = routeMap.get(basePath);
+		const path = route?.path ?? localizedRoutePath(basePath, locale, i18n);
+		return {
+			path: (intent.kind === "page" && intent.redirect ? localizedRoutePath(routePathFromRef(intent.redirect), locale, i18n) : void 0) ?? path,
+			title: resolveLocalizedText(intent.title, locale, i18n.defaultLocale) ?? route?.meta.title ?? kebabToTitle(basePath.split("/").pop() ?? intent.ref),
+			icon: intent.icon,
+			sections: route?.meta.sections ? navigationSections(route.meta.sections) : void 0
+		};
+	};
+	return config.map((group) => {
+		const children = group.pages.map(buildItem);
 		return {
 			path: children[0]?.path ?? localizedRoutePath("/", locale, i18n),
 			title: resolveLocalizedText(group.group, locale, i18n.defaultLocale) ?? "",
@@ -927,8 +921,9 @@ var clarifySourceConfigSchema = zod.z.object({
 	branch: zod.z.string().optional(),
 	directory: zod.z.string().optional()
 });
-var clarifyPagesItemSchema = zod.z.union([
+var clarifyPagesItemSchema = zod.z.lazy(() => zod.z.union([
 	zod.z.string(),
+	clarifyPagesGroupSchema,
 	zod.z.object({
 		page: zod.z.string(),
 		path: zod.z.string().optional(),
@@ -943,12 +938,12 @@ var clarifyPagesItemSchema = zod.z.union([
 		title: clarifyLocalizedTextSchema.optional(),
 		filter: zod.z.object({ tags: zod.z.array(zod.z.string()).optional() }).optional()
 	})
-]);
-var clarifyPagesGroupSchema = zod.z.object({
+]));
+var clarifyPagesGroupSchema = zod.z.lazy(() => zod.z.object({
 	group: clarifyLocalizedTextSchema,
 	icon: zod.z.string().optional(),
 	pages: zod.z.array(clarifyPagesItemSchema)
-});
+}));
 var clarifyPagesConfigSchema = zod.z.union([zod.z.array(clarifyPagesGroupSchema), zod.z.literal("FileTree")]);
 var clarifyTabItemSchema = zod.z.object({
 	tab: clarifyLocalizedTextSchema,
@@ -1296,16 +1291,10 @@ function createRuntimeSlotsModule(plugins = [], root = process.cwd()) {
 	}
 	return `export const runtimeSlots = {\n${[...grouped.entries()].map(([name, list]) => `  ${JSON.stringify(name)}: [\n    ${list.join(",\n    ")}\n  ]`).join(",\n")}\n};\n`;
 }
-function generateMdxErrorModule(diagnostic) {
+function generateContentDiagnosticModule(diagnostic) {
 	return `import { createContentDiagnosticComponent } from '@clarify-labs/renderer';
 
-export const contentDiagnostic = ${JSON.stringify({
-		kind: diagnostic.kind ?? "mdx",
-		title: diagnostic.title,
-		message: diagnostic.message,
-		filePath: diagnostic.filePath,
-		details: diagnostic.details
-	})};
+export const contentDiagnostic = ${JSON.stringify(diagnostic)};
 
 export default createContentDiagnosticComponent(contentDiagnostic);
 `;
@@ -1323,7 +1312,7 @@ function buildVirtualModules(args) {
 	modules.set(VIRTUAL_CLIENT_ENTRY, clientEntryModule);
 	modules.set(RESOLVED_CLIENT_ENTRY, clientEntryModule);
 	for (const route of args.routes) {
-		const moduleContent = route.diagnostic ? generateMdxErrorModule(route.diagnostic) : `export { default } from ${moduleSpecifier(route.source.filePath)};`;
+		const moduleContent = route.diagnostic ? generateContentDiagnosticModule(route.diagnostic) : `export { default } from ${moduleSpecifier(route.source.filePath)};`;
 		modules.set(route.module.virtualModuleId, moduleContent);
 	}
 	return modules;
@@ -1358,9 +1347,9 @@ async function refreshDevServer(engine, server) {
 	invalidateVirtualModules(engine, server);
 	return hasDevStructureChanged(before, createDevStructureSnapshot(engine.routes, engine.navigation));
 }
-function createNormalizedMdxContentPlugin(engine) {
+function createNormalizedContentPlugin(engine) {
 	return {
-		name: "clarify:normalized-mdx-content",
+		name: "clarify:normalized-content",
 		enforce: "pre",
 		transform(_code, id) {
 			if (!/\.mdx?(?:\?|$)/.test(id)) return null;
@@ -1374,16 +1363,44 @@ function createNormalizedMdxContentPlugin(engine) {
 		}
 	};
 }
-function createMdxPlugin() {
-	return (0, _mdx_js_rollup.default)({
-		include: ["**/*.{md,mdx}"],
+function createContentCompileTransform(transform, format, projectRoot, errorPolicy = () => "diagnostic") {
+	return async function contentCompileTransform(code, id) {
+		try {
+			return await transform.call(this, code, id);
+		} catch (error) {
+			if (errorPolicy() === "throw") throw error;
+			return {
+				code: generateContentDiagnosticModule(createContentCompileDiagnostic({
+					format,
+					phase: "compilation",
+					error,
+					filePath: id.replace(/\?.*$/, ""),
+					projectRoot
+				})),
+				map: null
+			};
+		}
+	};
+}
+function createContentCompilerPlugin(format, projectRoot, errorPolicy) {
+	const markdown = format === "markdown";
+	const plugin = (0, _mdx_js_rollup.default)({
+		include: [markdown ? "**/*.md" : "**/*.mdx"],
+		format: markdown ? "md" : "mdx",
 		jsxImportSource: "react",
 		providerImportSource: "@clarify-labs/renderer",
 		remarkPlugins,
-		rehypePlugins
+		...markdown ? { remarkRehypeOptions: { allowDangerousHtml: true } } : {},
+		rehypePlugins: markdown ? [rehype_raw.default, ...rehypePlugins] : rehypePlugins
 	});
+	const transform = typeof plugin.transform === "function" ? plugin.transform : plugin.transform?.handler;
+	if (!transform) return plugin;
+	return {
+		...plugin,
+		transform: createContentCompileTransform(transform, format, projectRoot, errorPolicy)
+	};
 }
-function createClarifyViteCorePlugin(engine, normalizedMdxContentPlugin, mdx) {
+function createClarifyViteCorePlugin(engine, normalizedContentPlugin, markdown, mdx) {
 	let viteConfig;
 	return {
 		name: "clarify:core",
@@ -1485,7 +1502,8 @@ function createClarifyViteCorePlugin(engine, normalizedMdxContentPlugin, mdx) {
 				outputDirectory: viteConfig.build.outDir,
 				ssrPlugins: [
 					engine.createSSGVirtualPlugin(),
-					normalizedMdxContentPlugin,
+					normalizedContentPlugin,
+					markdown,
 					mdx
 				]
 			});
@@ -1502,20 +1520,31 @@ function createClarifyViteCorePlugin(engine, normalizedMdxContentPlugin, mdx) {
 * site itself - it only bridges Vite lifecycle hooks to the engine.
 */
 function createViteAdapter(engine) {
-	const normalizedMdxContentPlugin = createNormalizedMdxContentPlugin(engine);
-	const mdx = createMdxPlugin();
+	let contentCompileErrorPolicy = "diagnostic";
+	const errorPolicy = () => contentCompileErrorPolicy;
+	const normalizedContentPlugin = createNormalizedContentPlugin(engine);
+	const markdown = createContentCompilerPlugin("markdown", engine.root, errorPolicy);
+	const mdx = createContentCompilerPlugin("mdx", engine.root, errorPolicy);
+	const compilePolicyPlugin = {
+		name: "clarify:content-compile-policy",
+		configResolved(config) {
+			contentCompileErrorPolicy = config.command === "build" && engine.generateOptions.ssg.failOnError ? "throw" : "diagnostic";
+		}
+	};
 	const tailwind = (0, _tailwindcss_vite.default)();
 	return [
 		...(0, _vitejs_plugin_react.default)(),
 		...Array.isArray(tailwind) ? tailwind : [tailwind],
-		normalizedMdxContentPlugin,
-		createClarifyViteCorePlugin(engine, normalizedMdxContentPlugin, mdx),
+		compilePolicyPlugin,
+		normalizedContentPlugin,
+		createClarifyViteCorePlugin(engine, normalizedContentPlugin, markdown, mdx),
+		markdown,
 		mdx
 	];
 }
 var cliPackageVersion = {
 	name: "@clarify-labs/cli",
-	version: "0.10.1",
+	version: "0.10.3",
 	license: "AGPL-3.0-only",
 	type: "module",
 	repository: {
@@ -1556,6 +1585,7 @@ var cliPackageVersion = {
 		"@clarify-labs/templates": "workspace:*",
 		"@mdx-js/mdx": "^3.1.1",
 		"@mdx-js/rollup": "^3.1.1",
+		"@shikijs/rehype": "^4.3.0",
 		"@tailwindcss/vite": "^4.3.2",
 		"@vitejs/plugin-react": "^6.0.3",
 		"cac": "^7.0.0",
@@ -1570,6 +1600,8 @@ var cliPackageVersion = {
 		"react-router": "^7.0.0",
 		"react-router-dom": "^7.0.0",
 		"react-zoom-pan-pinch": "^4.0.3",
+		"rehype-raw": "^7.0.0",
+		"rehype-slug": "^6.0.0",
 		"remark": "^15.0.1",
 		"remark-gfm": "^4.0.1",
 		"shiki": "4.3.0",
@@ -1865,9 +1897,6 @@ var OPENAPI_HTTP_METHODS = [
 	"trace"
 ];
 var CLARIFY_OPENAPI_SECTION_ID_EXTENSION = "x-clarify-section-id";
-function errorMessage(error) {
-	return error instanceof Error ? error.message : String(error);
-}
 function isSameOpenAPIFile(url, filePath) {
 	try {
 		return (0, node_path.resolve)((0, node_url.fileURLToPath)(url)) === (0, node_path.resolve)(filePath);
@@ -1982,7 +2011,7 @@ function extractOpenAPISections(spec, filterTags) {
 	}
 	return sections;
 }
-async function readOpenAPISpec(filePath, contentProcessor) {
+async function readOpenAPISpec(filePath, contentProcessor, projectRoot) {
 	try {
 		if (!contentProcessor) return {
 			ok: true,
@@ -2005,13 +2034,14 @@ async function readOpenAPISpec(filePath, contentProcessor) {
 	} catch (error) {
 		return {
 			ok: false,
-			diagnostic: {
+			diagnostic: createContentDiagnostic({
 				kind: "openapi",
 				title: "OpenAPI spec parse failed",
-				message: `Clarify could not parse ${filePath}.`,
+				message: "Clarify could not parse this OpenAPI specification.",
+				error,
 				filePath,
-				details: errorMessage(error)
-			}
+				projectRoot
+			})
 		};
 	}
 }
@@ -2042,31 +2072,24 @@ export const routeData = {};
 export default createOpenApiRouteComponent({ ...routeData, spec });
 `;
 }
-function generateOpenAPIErrorModule(diagnostic) {
-	return `import { createContentDiagnosticComponent } from '@clarify-labs/renderer';
-
-export const contentDiagnostic = ${JSON.stringify({
-		kind: diagnostic.kind ?? "openapi",
-		title: diagnostic.title,
-		message: diagnostic.message,
-		filePath: diagnostic.filePath,
-		details: diagnostic.details
-	})};
-
-export default createContentDiagnosticComponent(contentDiagnostic);
-`;
-}
 //#endregion
 //#region source/plugins/openapi/index.ts
 function collectOpenAPIPageIntents(config) {
 	const intents = [];
-	function visitPages(pages) {
-		if (!pages || pages === "FileTree") return;
-		for (const group of pages) for (const item of group.pages) {
+	function visitItems(items) {
+		for (const item of items) {
+			if (typeof item !== "string" && "group" in item) {
+				visitItems(item.pages);
+				continue;
+			}
 			const intent = routeIntentFromPagesItem(item);
 			if (intent.kind === "openapi" && (intent.path || intent.tagFilter?.length)) intents.push(intent);
 		}
 	}
+	function visitPages(pages) {
+		if (!pages || pages === "FileTree") return;
+		for (const group of pages) visitItems(group.pages);
+	}
 	for (const tab of config.tabs ?? []) visitPages(tab.pages);
 	return intents;
 }
@@ -2212,7 +2235,7 @@ function createOpenAPIPlugin() {
 					const result = specFromCache ? {
 						ok: true,
 						spec: specFromCache
-					} : await readOpenAPISpec(route.source.filePath, processor);
+					} : await readOpenAPISpec(route.source.filePath, processor, ctx.generateOptions.projectRoot);
 					if (!result.ok) {
 						route.diagnostic = result.diagnostic;
 						route.meta.title = route.meta.title || "OpenAPI parse error";
@@ -2259,7 +2282,7 @@ function createOpenAPIPlugin() {
 				for (const [routeSpecModuleId, spec] of specModules) modules.set(specVirtualModuleId(routeSpecModuleId), generateOpenAPISpecModule(spec));
 				for (const route of ctx.routes) {
 					if (route.kind !== "openapi") continue;
-					if (route.diagnostic) modules.set(route.module.virtualModuleId, generateOpenAPIErrorModule(route.diagnostic));
+					if (route.diagnostic) modules.set(route.module.virtualModuleId, generateContentDiagnosticModule(route.diagnostic));
 					else if (route.openapi?.sourceSpecId) {
 						const routeSpecModuleId = route.openapi.routeSpecModuleId ?? route.openapi.sourceSpecId;
 						if (!specModules.has(routeSpecModuleId)) continue;
@@ -2714,6 +2737,11 @@ function writeClarifyEnvDts(projectRoot, plugins) {
 	(0, node_fs.writeFileSync)(filePath, next, "utf-8");
 }
 //#endregion
+//#region source/parsers/markdown/utils.ts
+function escapeHtml(text) {
+	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+//#endregion
 //#region source/core/runtime/html-template.ts
 /**
 * HTML template manipulation helpers used during SSG.
@@ -3086,6 +3114,12 @@ function loadVirtualModule(id, modules) {
 	const bareId = stripVirtualPrefix(id);
 	return modules.get(bareId) ?? modules.get(id) ?? null;
 }
+function assertNoContentDiagnostics(routes) {
+	const failures = routes.filter((route) => route.diagnostic);
+	if (failures.length === 0) return;
+	const summary = failures.map((route) => `- ${route.path}: ${route.diagnostic?.title ?? "Content error"}${route.diagnostic?.filePath ? ` (${route.diagnostic.filePath})` : ""}`).join("\n");
+	throw new Error(`[clarify] Content diagnostics prevented the build:\n${summary}`);
+}
 var ClarifyEngine = class {
 	options;
 	root;
@@ -3310,6 +3344,7 @@ var ClarifyEngine = class {
 		await runPhase(this.plugins, "ssg", this.ctx, async () => {
 			if (process.env.SKIP_CLARIFY_SSG) return;
 			if (!await runInterceptHooks(this.plugins, "ssg:shouldRun", this.ctx)) return;
+			if (this.generateOptions.ssg.failOnError) assertNoContentDiagnostics(this.routes);
 			const outputDir = this.runtime.outputDirectory ?? this.generateOptions.outputDirectory;
 			if (!outputDir) throw new Error("[clarify] outputDirectory is required before SSG runs");
 			const ssrOutputDir = (0, node_path.join)(outputDir, ".ssr");
@@ -3417,4 +3452,4 @@ Object.defineProperty(exports, "defineConfig", {
 	}
 });
 
-//# sourceMappingURL=engine-5bdNX2Oo.cjs.map
+//# sourceMappingURL=engine-BDdPszs2.cjs.map