@clarify-labs/cli 0.9.3 → 0.10.0

package/output/{plugin-poS3N83A.js → engine-3f5Tpa-6.js}

@@ -1,28 +1,30 @@
-import { createReadStream, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import mdxPlugin from "@mdx-js/rollup";
 import tailwindcss from "@tailwindcss/vite";
 import react from "@vitejs/plugin-react";
+import { compile } from "@mdx-js/mdx";
 import GithubSlugger, { slug } from "github-slugger";
 import { toString } from "mdast-util-to-string";
-import shiki from "shiki";
+import { bundledLanguages, createCssVariablesTheme, createHighlighter } from "shiki";
 import { visit } from "unist-util-visit";
 import { markdownRemarkPlugins, themeBootstrapScript, themePresets } from "@clarify-labs/renderer";
-import { stringify } from "yaml";
-import matter from "gray-matter";
+import { readFile, readdir, stat } from "node:fs/promises";
 import { remark } from "remark";
+import matter from "gray-matter";
+import { createReadStream, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { build, loadConfigFromFile } from "vite";
+import { z } from "zod";
+import { stringify } from "yaml";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import SwaggerParser from "@apidevtools/swagger-parser";
 import { tmpdir } from "node:os";
-import { z } from "zod";
-import { build, loadConfigFromFile } from "vite";
 import { createRequire } from "node:module";
-//#region source/core/utils.ts
+//#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/parsers/mdx.ts
+//#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";
 }
@@ -34,11 +36,21 @@ function getTextContent(node) {
 function renderPlainCode(code) {
 	return code.split("\n").map((line) => `<span>${escapeHtml(line)}</span>`).join("\n");
 }
+function isBundledLanguage(language) {
+	return language in bundledLanguages;
+}
 var highlighter;
+var cssVariablesTheme = createCssVariablesTheme();
 async function getHighlighter() {
-	highlighter = highlighter ?? await shiki.getHighlighter({ theme: "css-variables" });
+	highlighter = highlighter ?? await createHighlighter({
+		themes: [cssVariablesTheme],
+		langs: []
+	});
 	return highlighter;
 }
+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) => {
 		visit(tree, "element", (node, _nodeIndex, parentNode) => {
@@ -59,6 +71,15 @@ function rehypeParseCodeBlocks() {
 function rehypeShiki() {
 	return async (tree) => {
 		const shikiHighlighter = await getHighlighter();
+		const languages = /* @__PURE__ */ new Set();
+		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);
 		visit(tree, "element", (node) => {
 			if (node.tagName !== "pre") return;
 			const codeNode = node.children?.[0];
@@ -72,12 +93,10 @@ function rehypeShiki() {
 			codeNode.properties.language = language;
 			let highlighted = renderPlainCode(code);
 			if (language && language !== "txt") try {
-				const tokens = shikiHighlighter.codeToThemedTokens(code, language);
-				highlighted = shiki.renderToHtml(tokens, { elements: {
-					pre: ({ children }) => children,
-					code: ({ children }) => children,
-					line: ({ children }) => `<span>${children}</span>`
-				} });
+				highlighted = renderHighlightedCode(shikiHighlighter.codeToHtml(code, {
+					lang: language,
+					theme: cssVariablesTheme
+				}));
 			} catch {
 				highlighted = renderPlainCode(code);
 			}
@@ -105,271 +124,116 @@ var rehypePlugins = [
 	rehypeParseCodeBlocks,
 	rehypeShiki
 ];
-//#endregion
-//#region source/plugins/content-artifacts/artifacts.ts
-var UTF8_SIGNATURE = "";
-function normalizeBasePath(basePath) {
-	if (!basePath || basePath === "/") return "";
-	return "/" + basePath.replace(/^\/+|\/+$/g, "");
-}
-function containsNonAscii(content) {
-	return [...content].some((character) => character.codePointAt(0) > 127);
-}
-function withUtf8Signature(content) {
-	if (!containsNonAscii(content) || content.startsWith(UTF8_SIGNATURE)) return content;
-	return `${UTF8_SIGNATURE}${content}`;
-}
-function shouldUseUtf8Signature(route) {
-	if (route.kind === "mdx") return true;
-	return false;
-}
-function routeToMarkdownArtifactUrl(routePath) {
-	return `${routePath === "/" ? "/index" : routePath.replace(/\/$/, "")}.md`;
-}
-function routeToOpenAPIArtifactUrl(routePath) {
-	return `${routePath === "/" ? "/index" : routePath.replace(/\/$/, "")}.openapi.json`;
-}
-function attachContentArtifactUrls(routes) {
-	for (const route of routes) route.contentArtifactUrl = route.kind === "openapi" ? routeToOpenAPIArtifactUrl(route.path) : routeToMarkdownArtifactUrl(route.path);
-}
-function readRouteContent(route) {
-	if (route.content !== void 0) return route.content;
-	throw new Error(`Route content is missing from route context: ${route.filePath}`);
-}
-function readRouteArtifactContent(route) {
-	const content = readRouteContent(route);
-	return shouldUseUtf8Signature(route) ? withUtf8Signature(content) : content;
-}
-function isLlmsTxtRoute(route) {
-	return !route.path.split("/").includes("404");
-}
-function llmsTxtDescription(route) {
-	if (route.description) return route.description;
-	const sections = route.sections?.filter((section) => section.level === 2).slice(0, 3).map((section) => section.title);
-	if (sections?.length) return `Covers ${sections.join(", ")}.`;
-	if (route.keywords?.length) return `Related topics: ${route.keywords.join(", ")}.`;
-	if (route.kind === "openapi") return "OpenAPI artifact for machine-readable API reference data.";
-}
-function llmsTxtListItem(route, basePath) {
-	if (!route.contentArtifactUrl) return void 0;
-	const description = llmsTxtDescription(route);
-	return description ? `- [${route.title}](${basePath}${route.contentArtifactUrl}): ${description}` : `- [${route.title}](${basePath}${route.contentArtifactUrl})`;
-}
-function llmsTxtLocaleLabel(locale, projectConfig) {
-	return projectConfig.i18n?.locales.find((item) => item.code === locale)?.label ?? locale;
+function formatMdxDiagnostic(error) {
+	if (error instanceof Error) return error.message;
+	return String(error);
 }
-function groupRoutesByLocale(routes) {
-	const groups = /* @__PURE__ */ new Map();
-	for (const route of routes) {
-		const key = route.locale ?? "default";
-		groups.set(key, [...groups.get(key) ?? [], route]);
+/**
+* Validate MDX content for diagnostics WITHOUT running the build-time rehype
+* pipeline (Shiki highlighting, slug injection, code-block parsing).
+*
+* `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
+* 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
+* "不应在 core 中执行代码高亮".
+*
+* The remark pipeline still runs (shared with the Vite plugin via
+* `remarkPlugins`), so MDX/JSX syntax errors — the only class of error this
+* diagnostic is meant to surface ahead of the Vite build — are caught. The
+* output is discarded; only the thrown error is used.
+*/
+async function compileMdxContent(content, filePath, projectRoot) {
+	try {
+		await compile(content, {
+			jsx: true,
+			providerImportSource: "@clarify-labs/renderer",
+			remarkPlugins
+		});
+		return { ok: true };
+	} 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)
+			}
+		};
 	}
-	return groups;
 }
-function groupLlmsTxtRoutesByLocale(routes, projectConfig) {
-	const routesBySource = /* @__PURE__ */ new Map();
-	const defaultLocale = projectConfig.i18n?.defaultLocale;
-	for (const route of routes) {
-		const sourceKey = `${route.locale ?? defaultLocale ?? "default"}:${route.basePath ?? route.contentArtifactUrl ?? route.path}`;
-		const previousRoute = routesBySource.get(sourceKey);
-		if (!previousRoute || previousRoute.locale && !route.locale) routesBySource.set(sourceKey, route);
+//#endregion
+//#region source/core/plugin/hooks.ts
+async function runHooks(plugins, hookName, input, ctx) {
+	let result = input;
+	for (const plugin of plugins) {
+		const hook = plugin.hooks?.[hookName];
+		if (!hook) continue;
+		try {
+			result = await hook(result, ctx);
+		} catch (err) {
+			throw new Error(`[clarify] plugin "${plugin.name}" hook "${hookName}" failed: ${err}`, { cause: err });
+		}
 	}
-	return groupRoutesByLocale([...routesBySource.values()].map((route) => ({
-		...route,
-		locale: route.locale ?? defaultLocale
-	})));
-}
-function llmsTxtDocsSectionTitle(locale, groupCount, projectConfig) {
-	if (groupCount <= 1) return "Docs";
-	return `Docs - ${locale === "default" ? "Default" : llmsTxtLocaleLabel(locale, projectConfig)}`;
+	return result;
 }
-function createLlmsTxt(routes, projectConfig) {
-	const basePath = normalizeBasePath(projectConfig.routePrefix);
-	const lines = [`# ${projectConfig.title}`, ""];
-	if (projectConfig.description) lines.push(`> ${projectConfig.description}`, "");
-	lines.push("This file lists the source-ready Markdown and OpenAPI artifacts for this documentation site.", "");
-	const mdxRoutes = routes.filter((route) => route.kind === "mdx" && isLlmsTxtRoute(route) && !route.isBareAlias);
-	if (mdxRoutes.length > 0) {
-		const localizedGroups = groupLlmsTxtRoutesByLocale(mdxRoutes, projectConfig);
-		for (const [locale, localeRoutes] of localizedGroups) {
-			lines.push(`## ${llmsTxtDocsSectionTitle(locale, localizedGroups.size, projectConfig)}`);
-			for (const route of localeRoutes) {
-				const item = llmsTxtListItem(route, basePath);
-				if (item) lines.push(item);
-			}
-			lines.push("");
+async function runDevConfigureServerHooks(plugins, server, ctx) {
+	for (const plugin of plugins) {
+		const hook = plugin.hooks?.["dev:configureServer"];
+		if (!hook) continue;
+		try {
+			await hook(server, ctx);
+		} catch (err) {
+			throw new Error(`[clarify] plugin "${plugin.name}" hook "dev:configureServer" failed: ${err}`, { cause: err });
 		}
 	}
-	const openApiRoutes = routes.filter((route) => route.kind === "openapi" && isLlmsTxtRoute(route) && !route.isBareAlias);
-	if (openApiRoutes.length > 0) {
-		if (lines.at(-1) !== "") lines.push("");
-		lines.push("## OpenAPI");
-		for (const route of openApiRoutes) {
-			const item = llmsTxtListItem(route, basePath);
-			if (item) lines.push(item);
+}
+async function runCollectorHooks(plugins, hookName, ctx) {
+	const results = [];
+	for (const plugin of plugins) {
+		const hook = plugin.hooks?.[hookName];
+		if (!hook) continue;
+		try {
+			const pluginResults = await hook(ctx);
+			results.push(...pluginResults);
+		} catch (err) {
+			throw new Error(`[clarify] plugin "${plugin.name}" hook "${hookName}" failed: ${err}`, { cause: err });
 		}
 	}
-	while (lines.at(-1) === "") lines.pop();
-	return `${lines.join("\n")}\n`;
-}
-function createLlmsTxtArtifact(routes, projectConfig) {
-	return withUtf8Signature(createLlmsTxt(routes, projectConfig));
-}
-//#endregion
-//#region source/plugins/content-artifacts/server.ts
-function normalizeRoutePrefix$1(routePrefix) {
-	if (!routePrefix || routePrefix === "/") return "";
-	return `/${routePrefix.replace(/^\/+|\/+$/g, "")}`;
-}
-function resolveContentArtifactPath(url, projectConfig) {
-	const requestPath = url?.split("?")[0] ?? "";
-	const basePath = normalizeRoutePrefix$1(projectConfig.routePrefix);
-	return basePath && requestPath.startsWith(basePath) ? requestPath.slice(basePath.length) || "/" : requestPath;
+	return results;
 }
-function resolveContentArtifactType(route) {
-	return route.kind === "openapi" ? "application/json; charset=utf-8" : "text/markdown; charset=utf-8";
+async function runBuildAssetsHooks(plugins, ctx) {
+	return runCollectorHooks(plugins, "build:assets", ctx);
 }
-function serveContentArtifacts(req, res, projectConfig, routes) {
-	const contentPath = resolveContentArtifactPath(req.url, projectConfig);
-	if (contentPath === "/llms.txt") {
-		res.statusCode = 200;
-		res.setHeader("Content-Type", "text/plain; charset=utf-8");
-		res.end(createLlmsTxtArtifact(routes, projectConfig), "utf8");
-		return true;
-	}
-	if (contentPath.endsWith(".openapi.yaml")) {
-		const jsonPath = contentPath.replace(/\.yaml$/, ".json");
-		const route = routes.find((r) => r.contentArtifactUrl === jsonPath);
-		if (route?.kind === "openapi" && route.content) {
-			const spec = JSON.parse(route.content);
-			res.statusCode = 200;
-			res.setHeader("Content-Type", "text/yaml; charset=utf-8");
-			res.end(stringify(spec, { lineWidth: 0 }), "utf8");
-			return true;
+async function runBuildDoneHooks(plugins, ctx) {
+	for (const plugin of plugins) {
+		const hook = plugin.hooks?.["build:done"];
+		if (!hook) continue;
+		try {
+			await hook(ctx);
+		} catch (err) {
+			throw new Error(`[clarify] plugin "${plugin.name}" hook "build:done" failed: ${err}`, { cause: err });
 		}
-		return false;
 	}
-	const route = routes.find((route) => route.contentArtifactUrl === contentPath);
-	if (!route) return false;
-	res.statusCode = 200;
-	res.setHeader("Content-Type", resolveContentArtifactType(route));
-	res.end(readRouteArtifactContent(route), "utf8");
-	return true;
 }
 //#endregion
-//#region source/plugins/content-artifacts/index.ts
-function createContentArtifactsPlugin() {
+//#region source/parsers/markdown/frontmatter.ts
+/**
+* 在内容入口统一解析 MDX frontmatter，并返回可供后续流程复用的标准化正文。
+*/
+function parseFrontmatter(content) {
+	const parsed = matter(content);
 	return {
-		name: "clarify:content-artifacts",
-		hooks: {
-			"routes:resolved": (input) => {
-				attachContentArtifactUrls(input.routes);
-				return input;
-			},
-			"dev:configureServer": (server, ctx) => {
-				server.middlewares.use((req, res, next) => {
-					if (serveContentArtifacts(req, res, ctx.projectConfig, ctx.routes)) return;
-					next();
-				});
-			},
-			"build:assets": (ctx) => {
-				const assets = [];
-				for (const route of ctx.routes) {
-					if (!route.contentArtifactUrl) continue;
-					assets.push({
-						fileName: route.contentArtifactUrl.replace(/^\//, ""),
-						source: readRouteArtifactContent(route)
-					});
-					if (route.kind === "openapi" && route.content) {
-						const yamlFileName = route.contentArtifactUrl.replace(/\.json$/, ".yaml");
-						const spec = JSON.parse(route.content);
-						assets.push({
-							fileName: yamlFileName.replace(/^\//, ""),
-							source: stringify(spec, { lineWidth: 0 })
-						});
-					}
-				}
-				assets.push({
-					fileName: "llms.txt",
-					source: createLlmsTxtArtifact(ctx.routes, ctx.projectConfig)
-				});
-				return assets;
-			}
-		}
+		frontmatter: parsed.data,
+		content: parsed.content.replace(/^\r?\n/, "")
 	};
 }
 //#endregion
-//#region source/plugins/html-shell/index.ts
-var REL_ICON_RE = /<link\s+[^>]*rel=["'][^"']*\bicon\b[^"']*["'][^>]*>/i;
-function inferIconType(href) {
-	const path = href.split(/[?#]/, 1)[0]?.toLowerCase() ?? href.toLowerCase();
-	if (path.endsWith(".svg")) return "image/svg+xml";
-	if (path.endsWith(".png")) return "image/png";
-	if (path.endsWith(".ico")) return "image/x-icon";
-	if (path.endsWith(".webp")) return "image/webp";
-}
-function createIconTag(href, media) {
-	return {
-		tag: "link",
-		attrs: {
-			rel: "icon",
-			...inferIconType(href) ? { type: inferIconType(href) } : {},
-			href,
-			...media ? { media } : {}
-		},
-		injectTo: "head"
-	};
-}
-function createIconTags(icon) {
-	if (!icon) return [];
-	if (typeof icon === "string") return [createIconTag(icon)];
-	const lightIcon = icon.light ?? icon.dark;
-	const darkIcon = icon.dark ?? icon.light;
-	if (!lightIcon || !darkIcon) return [];
-	if (lightIcon === darkIcon) return [createIconTag(lightIcon)];
-	return [createIconTag(lightIcon, "(prefers-color-scheme: light)"), createIconTag(darkIcon, "(prefers-color-scheme: dark)")];
-}
-function createHtmlShellPlugin() {
-	return {
-		name: "clarify:html-shell",
-		hooks: { "html:transform": (input, ctx) => ({
-			html: input.html,
-			tags: [
-				...input.tags,
-				...REL_ICON_RE.test(input.html) ? [] : createIconTags(ctx.projectConfig.favicon ?? ctx.projectConfig.logo),
-				{
-					tag: "script",
-					children: themeBootstrapScript(ctx.projectConfig.theme),
-					injectTo: "head-prepend"
-				},
-				{
-					tag: "script",
-					attrs: {
-						type: "module",
-						src: input.clientEntryId
-					},
-					injectTo: "body"
-				}
-			],
-			clientEntryId: input.clientEntryId,
-			dev: input.dev
-		}) }
-	};
-}
-//#endregion
-//#region source/parsers/frontmatter.ts
-/**
-* 在内容入口统一解析 MDX frontmatter，并返回可供后续流程复用的标准化正文。
-*/
-function parseFrontmatter(content) {
-	const parsed = matter(content);
-	return {
-		frontmatter: parsed.data,
-		content: parsed.content.replace(/^\r?\n/, "")
-	};
-}
-//#endregion
-//#region source/parsers/content.ts
+//#region source/parsers/content/content.ts
 async function transformContent(transform, input) {
 	return transform ? await transform(input) : input;
 }
@@ -400,71 +264,19 @@ function createContentProcessor(transform) {
 		}
 	};
 }
-//#endregion
-//#region source/core/hooks.ts
-async function runHooks(plugins, hookName, input, ctx) {
-	let result = input;
-	for (const plugin of plugins) {
-		const hook = plugin.hooks?.[hookName];
-		if (!hook) continue;
-		try {
-			result = await hook(result, ctx);
-		} catch (err) {
-			throw new Error(`[clarify] plugin "${plugin.name}" hook "${hookName}" failed: ${err}`, { cause: err });
-		}
-	}
-	return result;
-}
-async function runDevConfigureServerHooks(plugins, server, ctx) {
-	for (const plugin of plugins) {
-		const hook = plugin.hooks?.["dev:configureServer"];
-		if (!hook) continue;
-		try {
-			await hook(server, ctx);
-		} catch (err) {
-			throw new Error(`[clarify] plugin "${plugin.name}" hook "dev:configureServer" failed: ${err}`, { cause: err });
-		}
-	}
-}
-async function runBuildAssetsHooks(plugins, ctx) {
-	const assets = [];
-	for (const plugin of plugins) {
-		const hook = plugin.hooks?.["build:assets"];
-		if (!hook) continue;
-		try {
-			const pluginAssets = await hook(ctx);
-			assets.push(...pluginAssets);
-		} catch (err) {
-			throw new Error(`[clarify] plugin "${plugin.name}" hook "build:assets" failed: ${err}`, { cause: err });
-		}
-	}
-	return assets;
-}
-async function runBuildDoneHooks(plugins, ctx) {
-	for (const plugin of plugins) {
-		const hook = plugin.hooks?.["build:done"];
-		if (!hook) continue;
-		try {
-			await hook(ctx);
-		} catch (err) {
-			throw new Error(`[clarify] plugin "${plugin.name}" hook "build:done" failed: ${err}`, { cause: err });
-		}
-	}
-}
-//#endregion
-//#region source/core/content.ts
-var contentProcessors = /* @__PURE__ */ new WeakMap();
+/**
+* Creates a ContentProcessor that forwards each piece of content through the
+* `content:transform` pipeline hook before it is parsed.
+*
+* Plugins that need to read content (site-discovery, openapi) call this with
+* the plugins list from their hook context. There is no global registry -
+* each call produces an independent processor bound to the given plugins.
+*/
 function createProjectContentProcessor(plugins, ctx) {
 	return createContentProcessor((input) => runHooks(plugins, "content:transform", input, ctx));
 }
-function setProjectContentProcessor(ctx, processor) {
-	contentProcessors.set(ctx, processor);
-}
-function getProjectContentProcessor(ctx) {
-	return contentProcessors.get(ctx);
-}
 //#endregion
-//#region source/parsers/routes.ts
+//#region source/parsers/routes/routes.ts
 function kebabToTitle(str) {
 	return str.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
 }
@@ -542,8 +354,14 @@ function resolveLocalizedText(text, locale, fallbackLocale) {
 }
 async function findContentRoutes(dir, base = dir, options = {}) {
 	const routes = [];
-	if (!existsSync(dir)) return routes;
-	const entries = readdirSync(dir, { withFileTypes: true });
+	let dirStat;
+	try {
+		dirStat = await stat(dir);
+	} catch {
+		return routes;
+	}
+	if (!dirStat.isDirectory()) return routes;
+	const entries = await readdir(dir, { withFileTypes: true });
 	for (const entry of entries) {
 		const fullPath = join(dir, entry.name);
 		if (entry.isDirectory()) routes.push(...await findContentRoutes(fullPath, base, options));
@@ -551,30 +369,41 @@ async function findContentRoutes(dir, base = dir, options = {}) {
 			const relativePath = relative(base, fullPath);
 			const pathParts = relativePath.replace(/\.mdx?$/, "").split("/");
 			const cleanPath = ("/" + pathParts.map((p) => p === "index" ? "" : p).filter(Boolean).join("/")).replace(/\/+/g, "/").replace(/\/$/, "") || "/";
-			const source = readFileSync(fullPath, "utf-8");
+			const source = await readFile(fullPath, "utf-8");
 			const { frontmatter, content } = await (options.contentProcessor ?? createContentProcessor()).processMdx(source, fullPath);
-			let title = typeof frontmatter.title === "string" ? frontmatter.title : "";
+			const page = {
+				path: cleanPath,
+				filePath: fullPath,
+				frontmatter,
+				content
+			};
+			const mdxResult = await compileMdxContent(page.content, fullPath, base);
+			let title = typeof page.frontmatter.title === "string" ? page.frontmatter.title : "";
 			if (!title) {
 				const lastPart = pathParts[pathParts.length - 1] ?? "";
-				title = kebabToTitle(lastPart === "index" ? pathParts.length >= 2 ? pathParts[pathParts.length - 2] : extractH1(content) : lastPart) || "Untitled";
+				title = kebabToTitle(lastPart === "index" ? pathParts.length >= 2 ? pathParts[pathParts.length - 2] : extractH1(page.content) : lastPart) || "Untitled";
 			}
 			routes.push({
+				kind: "mdx",
+				title,
 				path: cleanPath,
 				basePath: cleanPath,
 				filePath: fullPath,
 				virtualModuleId: "virtual:clarify-page/" + relativePath.replace(/\.mdx?$/, "").replace(/\/+/g, "/"),
-				title,
-				description: typeof frontmatter.description === "string" ? frontmatter.description : void 0,
-				keywords: frontmatterKeywords(frontmatter),
-				kind: "mdx",
-				frontmatter,
-				content,
-				sections: extractMdxSections(content)
+				description: typeof page.frontmatter.description === "string" ? page.frontmatter.description : void 0,
+				keywords: frontmatterKeywords(page.frontmatter),
+				frontmatter: page.frontmatter,
+				content: page.content,
+				sections: extractMdxSections(page.content),
+				diagnostic: mdxResult.ok ? void 0 : mdxResult.diagnostic
 			});
 		}
 	}
 	return routes;
 }
+function virtualModuleIdForLocalizedRoute(contentRoot, filePath) {
+	return "virtual:clarify-page/" + relative(contentRoot, filePath).replace(/\.mdx?$/, "").replace(/\.openapi\.(json|yaml|yml)$/, "").replace(/\/+/g, "/");
+}
 function frontmatterKeywords(frontmatter) {
 	const value = frontmatter.keywords ?? frontmatter.keyword ?? frontmatter.tags;
 	const keywords = Array.isArray(value) ? value.filter((item) => typeof item === "string") : typeof value === "string" ? value.split(",").map((keyword) => keyword.trim()).filter(Boolean) : [];
@@ -592,6 +421,63 @@ function withAlternates(route, routes, i18n) {
 		alternates
 	};
 }
+/**
+* 为默认语言的 locale-prefixed 路由生成无前缀的"裸路径别名"，方便不带语言
+* 前缀的 URL 也能访问。标记 `isBareAlias` 以便搜索索引生成时过滤重复索引。
+*/
+function generateBareAliases(routes, i18n) {
+	const bareRoutes = [];
+	const seenBare = new Set(routes.map((r) => r.path));
+	for (const route of routes) {
+		if (route.locale !== i18n.defaultLocale) continue;
+		const bp = route.basePath ?? route.path;
+		if (bp === route.path || seenBare.has(bp)) continue;
+		seenBare.add(bp);
+		bareRoutes.push({
+			...route,
+			path: bp,
+			isBareAlias: true
+		});
+	}
+	return bareRoutes;
+}
+async function findLocalizedContentRoutes(contentRoot, i18n, options = {}) {
+	if (!i18n) return findContentRoutes(contentRoot, contentRoot, options);
+	const localizedRoutes = [];
+	for (const locale of i18n.locales) {
+		const localeRoot = join(contentRoot, locale.code);
+		const discovered = await findContentRoutes(localeRoot, localeRoot, options);
+		for (const route of discovered) {
+			const basePath = route.basePath ?? route.path;
+			localizedRoutes.push({
+				...route,
+				path: localizedRoutePath(basePath, locale.code, i18n),
+				basePath,
+				locale: locale.code,
+				virtualModuleId: virtualModuleIdForLocalizedRoute(contentRoot, route.filePath)
+			});
+		}
+	}
+	if (i18n.missing === "fallback") {
+		const routeByLocaleAndBase = new Map(localizedRoutes.map((route) => [`${route.locale ?? ""}:${route.basePath ?? route.path}`, route]));
+		const defaultRoutes = localizedRoutes.filter((route) => route.locale === i18n.defaultLocale);
+		for (const sourceRoute of defaultRoutes) {
+			const basePath = sourceRoute.basePath ?? sourceRoute.path;
+			for (const locale of i18n.locales) {
+				const key = `${locale.code}:${basePath}`;
+				if (routeByLocaleAndBase.has(key)) continue;
+				localizedRoutes.push({
+					...sourceRoute,
+					path: localizedRoutePath(basePath, locale.code, i18n),
+					locale: locale.code,
+					isFallback: true
+				});
+			}
+		}
+	}
+	const routesWithAlternates = localizedRoutes.map((route) => withAlternates(route, localizedRoutes, i18n));
+	return [...routesWithAlternates, ...generateBareAliases(routesWithAlternates, i18n)];
+}
 function buildNavigation(routes) {
 	const root = [];
 	for (const route of routes) {
@@ -678,19 +564,7 @@ function applyConfiguredPageRoutePaths(routes, tabs, i18n) {
 	const nextRoutes = [...routes, ...additions];
 	const routesWithAlternates = i18n ? nextRoutes.map((route) => withAlternates(route, nextRoutes, i18n)) : nextRoutes;
 	if (!i18n) return routesWithAlternates;
-	const bareRoutes = [];
-	const seenBare = new Set(routesWithAlternates.map((r) => r.path));
-	for (const route of routesWithAlternates) {
-		if (route.locale !== i18n.defaultLocale) continue;
-		const bp = route.basePath ?? route.path;
-		if (bp === route.path || seenBare.has(bp)) continue;
-		seenBare.add(bp);
-		bareRoutes.push({
-			...route,
-			path: bp
-		});
-	}
-	return [...routesWithAlternates, ...bareRoutes];
+	return [...routesWithAlternates, ...generateBareAliases(routesWithAlternates, i18n)];
 }
 function buildNavigationFromPagesConfig(routes, config) {
 	if (!config || config === "FileTree") return buildNavigation(routes);
@@ -794,1108 +668,1802 @@ function buildLocalizedNavigationFromTabsConfig(routes, tabs, i18n) {
 	}
 	return result;
 }
-//#endregion
-//#region source/plugins/openapi/parser.ts
-var OPENAPI_HTTP_METHODS = [
-	"get",
-	"put",
-	"post",
-	"delete",
-	"options",
-	"head",
-	"patch",
-	"trace"
-];
-function errorMessage(error) {
-	return error instanceof Error ? error.message : String(error);
-}
-function isSameOpenAPIFile(url, filePath) {
-	try {
-		return resolve(fileURLToPath(url)) === resolve(filePath);
-	} catch {
-		return resolve(url) === resolve(filePath);
-	}
-}
-function findOpenAPIRoutes(dir, base = dir) {
-	const routes = [];
-	if (!existsSync(dir)) return routes;
-	const entries = readdirSync(dir, { withFileTypes: true });
-	for (const entry of entries) {
-		const fullPath = join(dir, entry.name);
-		if (entry.isDirectory()) {
-			routes.push(...findOpenAPIRoutes(fullPath, base));
-			continue;
-		}
-		if (!entry.isFile() || !/\.openapi\.(json|yaml|yml)$/.test(entry.name)) continue;
-		const ref = relative(base, fullPath);
-		const cleanPath = routePathFromRef(ref);
-		routes.push({
-			path: cleanPath,
-			basePath: cleanPath,
-			filePath: fullPath,
-			virtualModuleId: virtualModuleIdFromRef(ref),
-			title: kebabToTitle(cleanPath.split("/").pop() ?? "API"),
-			kind: "openapi"
-		});
-	}
-	return routes;
-}
-function operationMatchesTags(operationTags, filterTags) {
-	if (!filterTags?.length) return true;
-	return operationTags?.some((tag) => filterTags.includes(tag)) ?? false;
-}
-/** Filter an OpenAPI spec to only include paths that have at least one operation matching the given tags. */
-function filterSpecByTags(spec, tags) {
-	const filteredPaths = {};
-	const paths = spec.paths ?? {};
-	for (const path of Object.keys(paths)) {
-		const pathItem = paths[path];
-		if (!pathItem) continue;
-		if (Object.values(pathItem).some((op) => op && typeof op === "object" && operationMatchesTags(op.tags, tags))) filteredPaths[path] = pathItem;
-	}
+/** Serialize a ContentRoute into the minimal shape exposed to tooling. */
+function toDevRouteEntry(route) {
 	return {
-		...spec,
-		paths: filteredPaths
+		path: route.path,
+		filePath: route.filePath,
+		locale: route.locale,
+		basePath: route.basePath,
+		kind: route.kind,
+		title: route.title
 	};
 }
-/** Extract endpoint operations from an OpenAPI spec as page sections. */
-function extractOpenAPISections(spec, filterTags) {
-	const sections = [];
-	const paths = spec.paths ?? {};
-	for (const [path, pathItem] of Object.entries(paths)) {
-		if (!pathItem) continue;
-		for (const method of OPENAPI_HTTP_METHODS) {
-			const op = pathItem[method];
-			if (!op || !operationMatchesTags(op.tags, filterTags)) continue;
-			const title = op.summary ?? `${method.toUpperCase()} ${path}`;
-			sections.push({
-				id: slug(`${method} ${path}`),
-				title,
-				level: 2,
-				badge: method.toUpperCase(),
-				tags: op.tags
-			});
-		}
+/**
+* Resolve a single file path to its preview route.
+*
+* Selection order:
+*  1. Routes whose `filePath` exactly matches.
+*  2. Among matches, prefer the one whose `locale` matches the file's locale
+*     directory (e.g. `source/zh-CN/x.mdx` → locale `zh-CN`).
+*  3. If no locale match, fall back to the default locale (if i18n is enabled)
+*     or the first match.
+*/
+function resolveRouteForFile(filePath, routes, defaultLocale) {
+	const matches = routes.filter((r) => r.filePath === filePath);
+	if (matches.length === 0) return void 0;
+	if (matches.length === 1) return matches[0];
+	const fileLocale = inferLocaleFromPath(filePath);
+	if (fileLocale) {
+		const localeMatch = matches.find((r) => r.locale === fileLocale);
+		if (localeMatch) return localeMatch;
 	}
-	return sections;
-}
-async function readOpenAPISpec(filePath, contentProcessor) {
-	try {
-		if (!contentProcessor) return {
-			ok: true,
-			spec: await SwaggerParser.dereference(filePath)
-		};
-		const source = readFileSync(filePath, "utf-8");
-		const transformedSource = await contentProcessor.processText(source, "openapi", filePath);
-		if (transformedSource === source) return {
-			ok: true,
-			spec: await SwaggerParser.dereference(filePath)
-		};
-		return {
-			ok: true,
-			spec: await SwaggerParser.dereference(filePath, { resolve: { transformedOpenAPISource: {
-				order: 1,
-				canRead: (file) => isSameOpenAPIFile(file.url, filePath),
-				read: () => transformedSource
-			} } })
-		};
-	} catch (error) {
-		return {
-			ok: false,
-			diagnostic: {
-				title: "OpenAPI spec parse failed",
-				message: `Clarify could not parse ${filePath}.`,
-				filePath,
-				cause: errorMessage(error)
-			}
-		};
+	if (defaultLocale) {
+		const defaultMatch = matches.find((r) => r.locale === defaultLocale);
+		if (defaultMatch) return defaultMatch;
 	}
-}
-//#endregion
-//#region source/core/virtual-modules.ts
-var VIRTUAL_CONFIG = "virtual:clarify/config";
-var VIRTUAL_ROUTES = "virtual:clarify/routes";
-var VIRTUAL_SERVER_ROUTES = "virtual:clarify/routes/server";
-var VIRTUAL_OPENAPI = "virtual:clarify/openapi";
-var VIRTUAL_SLOTS = "virtual:clarify/slots";
-var VIRTUAL_SLOT = "virtual:clarify/slot";
-var VIRTUAL_CLIENT_ENTRY = "virtual:clarify/entry-client";
-var RESOLVED_CLIENT_ENTRY = "\0virtual:clarify/entry-client";
-function resolveVirtualId(id) {
-	return "\0" + id;
-}
-function stripVirtualPrefix(id) {
-	return id.startsWith("\0") ? id.slice(1) : id;
-}
-function generateConfigModule(projectConfig, buildOptions) {
-	return `export const config = ${JSON.stringify({
-		...projectConfig,
-		...buildOptions
-	})};`;
-}
-function moduleSpecifier(value) {
-	return JSON.stringify(value);
-}
-function generateRoutesModule(routes, resolvedNavigation, projectConfig, mode = "client") {
-	const imports = mode === "server" ? routes.map((r, i) => `import Page${i} from ${moduleSpecifier(r.virtualModuleId)};`).join("\n") : "";
-	const routesArray = routes.map((r, i) => {
-		const sections = r.sections && r.sections.length > 0 ? `, sections: ${JSON.stringify(r.sections.map((s) => ({
-			id: s.id,
-			title: s.title,
-			level: s.level,
-			badge: s.badge,
-			tags: s.tags
-		})))}` : "";
-		const contentArtifactUrl = r.contentArtifactUrl ? `, contentArtifactUrl: ${JSON.stringify(r.contentArtifactUrl)}` : "";
-		const basePath = r.basePath ? `, basePath: ${JSON.stringify(r.basePath)}` : "";
-		const locale = r.locale ? `, locale: ${JSON.stringify(r.locale)}` : "";
-		const isFallback = r.isFallback ? ", isFallback: true" : "";
-		const isBareAlias = r.isBareAlias ? ", isBareAlias: true" : "";
-		const alternates = r.alternates ? `, alternates: ${JSON.stringify(r.alternates)}` : "";
-		const description = r.description ? `, description: ${JSON.stringify(r.description)}` : "";
-		const keywords = r.keywords && r.keywords.length > 0 ? `, keywords: ${JSON.stringify(r.keywords)}` : "";
-		const sourceUrl = r.sourceUrl ? `, sourceUrl: ${JSON.stringify(r.sourceUrl)}` : "";
-		const component = mode === "server" ? `Page${i}` : `() => import(${moduleSpecifier(r.virtualModuleId)})`;
-		const lazy = mode === "client" ? ", lazy: true" : "";
-		return `  { path: ${JSON.stringify(r.path)}, title: ${JSON.stringify(r.title)}, component: ${component}${lazy}, kind: ${JSON.stringify(r.kind)}${basePath}${locale}${isFallback}${isBareAlias}${alternates}${description}${keywords}${sections}${contentArtifactUrl}${sourceUrl} }`;
-	}).join(",\n");
-	const navigation = resolvedNavigation ?? (projectConfig?.tabs ? projectConfig.i18n ? buildLocalizedNavigationFromTabsConfig(routes, projectConfig.tabs, projectConfig.i18n) ?? {} : buildNavigationFromTabsConfig(routes, projectConfig.tabs) : buildNavigation(routes));
-	return `${imports}\n\nexport const routes = [\n${routesArray}\n];\n\nexport const navigation = ${JSON.stringify(navigation, null, 2)};\n`;
-}
-function createClientEntryModule(options = {}) {
-	return `
-import '@clarify-labs/renderer/style.css';
-import { render } from '@clarify-labs/renderer/client';
-import { routes, navigation } from '${VIRTUAL_ROUTES}';
-import { config } from '${VIRTUAL_CONFIG}';
-import { openApis } from '${VIRTUAL_OPENAPI}';
-import { runtimeSlots } from '${VIRTUAL_SLOTS}';
-render({ config, routes, navigation, openApis, runtimeSlots, themeEditor: ${JSON.stringify(options.themeEditor ?? false)} });`;
+	return matches[0];
 }
 /**
-* Collect every plugin's `slots` declarations into a single runtime registry
-* module. Component modules are exported as lazy import factories so the
-* renderer can decide whether to code-split (client) or pre-resolve (SSR).
-*
-* Relative component paths are resolved against the project `root` so that
-* the generated `import()` call uses an absolute specifier — Vite cannot
-* resolve relative imports from virtual modules.
+* Derive a best-effort preview route for a file that is not in the route
+* manifest (e.g. a draft or newly created file). The path is computed from the
+* file's location relative to the content root, following the same convention
+* as route discovery (`source/{locale}/path/index.mdx` → `/{locale}/path`).
 *
-* Slot name validity is enforced at compile time by the `UISlotName`
-* type — no runtime validation is needed.
+* Returns null when the file is outside the content root or is not a
+* recognized content file type.
 */
-function createRuntimeSlotsModule(plugins = [], root = process.cwd()) {
-	const registrations = [];
-	for (const plugin of plugins) for (const slot of plugin.slots ?? []) registrations.push({
-		plugin: plugin.name,
-		slot
+function inferRouteForFile(filePath, contentRoot, defaultLocale) {
+	const ref = relative(contentRoot, filePath);
+	if (!ref || ref.startsWith("..")) return null;
+	const isMdx = /\.mdx?$/.test(filePath);
+	const isOpenApi = /\.openapi\.(json|ya?ml)$/.test(filePath);
+	if (!isMdx && !isOpenApi) return null;
+	const segments = ref.split("/");
+	const fileLocale = inferLocaleFromPath(filePath);
+	const localeSegmentIndex = fileLocale ? segments.indexOf(fileLocale) : -1;
+	const basePath = basePathFromRef(localeSegmentIndex >= 0 ? segments.slice(localeSegmentIndex + 1).join("/") : ref);
+	const path = fileLocale && defaultLocale ? localizedRoutePath(basePath, fileLocale, {
+		defaultLocale,
+		missing: "fallback",
+		locales: []
+	}) : basePath;
+	const title = segments[segments.length - 1]?.replace(/\.(mdx?|openapi\.(json|ya?ml))$/, "") || "Untitled";
+	return {
+		path: normalizePath(path),
+		filePath,
+		locale: fileLocale,
+		basePath: normalizePath(basePath),
+		kind: isMdx ? "mdx" : "openapi",
+		title,
+		inferred: true
+	};
+}
+/** Best-effort locale inference from a file path segment like `.../zh-CN/x.mdx`. */
+function inferLocaleFromPath(filePath) {
+	const segments = filePath.split("/");
+	for (const segment of segments) if (/^[a-z]{2,3}(-[A-Z][a-z]{3})?(-[A-Z]{2})?$/.test(segment)) return segment;
+}
+/** Read and parse the JSON body of an IncomingMessage. */
+function readJsonBody(req) {
+	return new Promise((resolveBody, reject) => {
+		const chunks = [];
+		req.on("data", (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+		req.on("error", reject);
+		req.on("end", () => {
+			const raw = Buffer.concat(chunks).toString("utf-8").trim();
+			if (!raw) return resolveBody({});
+			try {
+				resolveBody(JSON.parse(raw));
+			} catch (err) {
+				reject(err);
+			}
+		});
 	});
-	if (registrations.length === 0) return "export const runtimeSlots = {};\n";
-	const grouped = /* @__PURE__ */ new Map();
-	for (const { plugin, slot } of registrations) {
-		if (slot.name.endsWith(".replace")) {
-			const existing = grouped.get(slot.name);
-			if (existing) console.warn(`[clarify] Multiple plugins register slot "${slot.name}": "${plugin}" overrides "${existing[existing.length - 1]}". Only the last registration is used.`);
-		}
-		if (!slot.component.startsWith("/")) throw new Error(`[clarify] Plugin "${plugin}" slot "${slot.name}" has an invalid component path "${slot.component}". Component paths must start with "/" to reference the project root.`);
-		const componentPath = root + slot.component;
-		const entry = `{ plugin: ${JSON.stringify(plugin)}, component: () => import(${moduleSpecifier(componentPath)}) }`;
-		const list = grouped.get(slot.name) ?? [];
-		list.push(entry);
-		grouped.set(slot.name, list);
-	}
-	return `export const runtimeSlots = {\n${[...grouped.entries()].map(([name, list]) => `  ${JSON.stringify(name)}: [\n    ${list.join(",\n    ")}\n  ]`).join(",\n")}\n};\n`;
 }
 /**
-* Re-exports the slot context hook from the renderer so plugin components can
-* `import { useSlot } from 'virtual:clarify/slot'` without depending on
-* renderer internals directly.
+* Handle a request to the dev route endpoint. Pure function — does not touch
+* the network directly, only reads the request body and writes to `res`.
 */
-function createSlotModule() {
-	return `export { useSlot } from '@clarify-labs/renderer';\n`;
-}
-function buildVirtualModules(args) {
-	const modules = /* @__PURE__ */ new Map();
-	const clientEntryModule = createClientEntryModule({ themeEditor: args.themeEditor });
-	const allPlugins = [...args.plugins ?? []];
-	modules.set(VIRTUAL_CONFIG, generateConfigModule(args.projectConfig, args.generateOptions));
-	modules.set(VIRTUAL_ROUTES, generateRoutesModule(args.routes, args.navigation, args.projectConfig, "client"));
-	modules.set(VIRTUAL_SERVER_ROUTES, generateRoutesModule(args.routes, args.navigation, args.projectConfig, "server"));
-	modules.set(VIRTUAL_SLOTS, createRuntimeSlotsModule(allPlugins, args.generateOptions.projectRoot));
-	modules.set(VIRTUAL_OPENAPI, generateOpenApiModule());
-	modules.set(VIRTUAL_SLOT, createSlotModule());
-	modules.set(VIRTUAL_CLIENT_ENTRY, clientEntryModule);
-	modules.set(RESOLVED_CLIENT_ENTRY, clientEntryModule);
-	for (const route of args.routes) modules.set(route.virtualModuleId, `export { default } from ${moduleSpecifier(route.filePath)};`);
-	return modules;
-}
-function generateOpenApiModule() {
-	return `export const openApis = {};`;
+async function handleDevRouteRequest(req, res, routes, context) {
+	res.setHeader("Content-Type", "application/json; charset=utf-8");
+	let body;
+	try {
+		body = await readJsonBody(req);
+	} catch {
+		res.statusCode = 400;
+		res.end(JSON.stringify({ error: "Invalid JSON body" }));
+		return;
+	}
+	const file = typeof body === "object" && body !== null ? body.file : void 0;
+	if (typeof file === "string" && file.length > 0) {
+		const route = resolveRouteForFile(file, routes, context.projectConfig.i18n?.defaultLocale);
+		if (route) {
+			res.end(JSON.stringify(toDevRouteEntry(route)));
+			return;
+		}
+		const inferred = inferRouteForFile(file, context.contentRoot, context.projectConfig.i18n?.defaultLocale);
+		res.end(JSON.stringify(inferred));
+		return;
+	}
+	res.end(JSON.stringify(routes.map(toDevRouteEntry)));
 }
 //#endregion
-//#region source/plugins/openapi/virtual-modules.ts
-var openApiRegistryModuleId = VIRTUAL_OPENAPI;
-var OPENAPI_SPEC_PREFIX = "virtual:clarify/openapi-spec/";
-function specVirtualModuleId(specKey) {
-	return `${OPENAPI_SPEC_PREFIX}${specKey}`;
-}
-function generateOpenAPIRegistryModule(openApis) {
-	return `export const openApis = ${JSON.stringify(openApis)};`;
-}
-/** Generate a virtual module that exports a single spec as default. */
-function generateOpenAPISpecModule(spec) {
-	return `export default ${JSON.stringify(spec)};`;
-}
-function generateOpenAPIPageModule(opts) {
-	const { specKey, specRegistryKey, tagFilter } = opts;
-	return [
-		`import { createElement, useState, useEffect, useRef } from 'react';`,
-		`import { OpenApiDocument, useOpenApis } from '@clarify-labs/renderer';`,
-		`const SPEC_KEY = ${JSON.stringify(specRegistryKey)};`,
-		`const TAG_FILTER = ${JSON.stringify(tagFilter ?? void 0)};`,
-		`let loadPromise = null;`,
-		`function loadSpec() {`,
-		`  if (!loadPromise) loadPromise = import(${JSON.stringify(specVirtualModuleId(specKey))}).then(function(m) { return m.default; });`,
-		`  return loadPromise;`,
-		`}`,
-		`export default function OpenApiRoutePage() {`,
-		`  const specs = useOpenApis();`,
-		`  const serverSpec = specs[SPEC_KEY];`,
-		`  const [spec, setSpec] = useState(serverSpec || null);`,
-		`  const mountedRef = useRef(false);`,
-		`  useEffect(function() {`,
-		`    if (mountedRef.current) return;`,
-		`    mountedRef.current = true;`,
-		`    if (spec) return;`,
-		`    loadSpec().then(setSpec);`,
-		`  }, []);`,
-		`  if (!spec) return null;`,
-		`  return createElement(OpenApiDocument, { spec: spec, tagFilter: TAG_FILTER });`,
-		`}`
-	].join("\n");
-}
-function generateOpenAPIErrorModule(diagnostic) {
-	return `import { createElement } from 'react';
-const diagnostic = ${JSON.stringify(diagnostic)};
-export default function OpenApiErrorRoutePage() {
-  return createElement('article', { className: 'flex h-full flex-col pt-16 pb-10' },
-    createElement('div', { className: 'prose max-w-none flex-auto dark:prose-invert' },
-      createElement('p', { className: 'mb-3 text-xs/6 font-medium tracking-widest text-red-500 uppercase dark:text-red-400' }, 'OpenAPI Error'),
-      createElement('h1', null, diagnostic.title),
-      createElement('p', { className: 'lead' }, diagnostic.message),
-      diagnostic.filePath ? createElement('div', { className: 'not-prose mt-6 rounded-lg border border-zinc-200 bg-zinc-50 p-4 text-sm dark:border-white/10 dark:bg-white/5' },
-        createElement('div', { className: 'mb-1 font-semibold text-zinc-900 dark:text-white' }, 'File'),
-        createElement('code', { className: 'break-all text-zinc-700 dark:text-zinc-300' }, diagnostic.filePath)
-      ) : null,
-      diagnostic.cause ? createElement('div', { className: 'not-prose mt-4 rounded-lg border border-red-200 bg-red-50 p-4 text-sm text-red-800 dark:border-red-500/30 dark:bg-red-500/10 dark:text-red-200' },
-        createElement('div', { className: 'mb-1 font-semibold' }, 'Why it happened'),
-        createElement('pre', { className: 'whitespace-pre-wrap break-words text-xs' }, diagnostic.cause)
-      ) : null
-    )
-  );
-}`;
+//#region source/parsers/theme.ts
+function resolveThemeConfig(theme = {}) {
+	const preset = theme.preset ?? "default";
+	const presetTheme = themePresets[preset];
+	return {
+		preset,
+		tokens: {
+			colors: {
+				...presetTheme.tokens.colors,
+				...theme.tokens?.colors
+			},
+			radius: {
+				...presetTheme.tokens.radius,
+				...theme.tokens?.radius
+			}
+		},
+		layout: {
+			...presetTheme.layout,
+			...theme.layout
+		},
+		editor: theme.editor ?? presetTheme.editor
+	};
 }
 //#endregion
-//#region source/plugins/openapi/index.ts
-function collectOpenAPIPageItems(config) {
-	const items = [];
-	function visitPages(pages) {
-		if (!pages || pages === "FileTree") return;
-		for (const group of pages) for (const item of group.pages) if (typeof item !== "string" && "openapi" in item && (item.path || item.filter?.tags?.length)) items.push(item);
+//#region source/core/config/config-schema.ts
+var clarifyLogoConfigSchema = z.union([z.string(), z.object({
+	light: z.string().optional(),
+	dark: z.string().optional()
+})]);
+var clarifyFaviconConfigSchema = z.union([z.string(), z.object({
+	light: z.string().optional(),
+	dark: z.string().optional()
+})]);
+var clarifyLocalizedTextSchema = z.union([z.string(), z.record(z.string(), z.string())]);
+var clarifyLocaleConfigSchema = z.object({
+	code: z.string(),
+	label: z.string(),
+	dir: z.union([z.literal("ltr"), z.literal("rtl")]).optional()
+});
+var clarifyI18nConfigSchema = z.object({
+	defaultLocale: z.string().optional(),
+	missing: z.union([
+		z.literal("fallback"),
+		z.literal("404"),
+		z.literal("hide")
+	]).optional(),
+	locales: z.array(clarifyLocaleConfigSchema).min(1)
+}).superRefine((config, ctx) => {
+	const localeCodes = /* @__PURE__ */ new Set();
+	for (const [index, locale] of config.locales.entries()) {
+		if (localeCodes.has(locale.code)) ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			message: `Duplicate locale code "${locale.code}"`,
+			path: [
+				"locales",
+				index,
+				"code"
+			]
+		});
+		localeCodes.add(locale.code);
+	}
+	if (config.defaultLocale && !localeCodes.has(config.defaultLocale)) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		message: "defaultLocale must be one of i18n.locales",
+		path: ["defaultLocale"]
+	});
+});
+var clarifyNavbarLinkSchema = z.object({
+	label: clarifyLocalizedTextSchema,
+	href: z.string(),
+	external: z.boolean().optional()
+});
+var clarifyBannerConfigOptionsSchema = z.object({
+	content: clarifyLocalizedTextSchema,
+	dismissible: z.boolean().optional(),
+	link: clarifyNavbarLinkSchema.optional()
+}).strict();
+var clarifyFooterConfigSchema = z.object({
+	links: z.array(clarifyNavbarLinkSchema).optional(),
+	socials: z.record(z.string(), z.string()).optional(),
+	copyright: clarifyLocalizedTextSchema.optional()
+}).strict();
+var clarifyVariableValueSchema = z.lazy(() => z.union([
+	z.string(),
+	z.number(),
+	z.boolean(),
+	z.record(z.string(), clarifyVariableValueSchema)
+]));
+var clarifyVariablesConfigSchema = z.record(z.string(), clarifyVariableValueSchema);
+var clarifySourceConfigSchema = z.object({
+	repository: z.string(),
+	branch: z.string().optional(),
+	directory: z.string().optional()
+});
+var clarifyPagesItemSchema = z.union([
+	z.string(),
+	z.object({
+		page: z.string(),
+		path: z.string().optional(),
+		title: clarifyLocalizedTextSchema.optional(),
+		icon: z.string().optional(),
+		redirect: z.string().optional()
+	}),
+	z.object({
+		openapi: z.string(),
+		path: z.string().optional(),
+		icon: z.string().optional(),
+		title: clarifyLocalizedTextSchema.optional(),
+		filter: z.object({ tags: z.array(z.string()).optional() }).optional()
+	})
+]);
+var clarifyPagesGroupSchema = z.object({
+	group: clarifyLocalizedTextSchema,
+	icon: z.string().optional(),
+	pages: z.array(clarifyPagesItemSchema)
+});
+var clarifyPagesConfigSchema = z.union([z.array(clarifyPagesGroupSchema), z.literal("FileTree")]);
+var clarifyTabItemSchema = z.object({
+	tab: clarifyLocalizedTextSchema,
+	icon: z.string().optional(),
+	pages: clarifyPagesConfigSchema.optional()
+});
+var clarifyTabsConfigSchema = z.array(clarifyTabItemSchema);
+var clarifyThemePresetSchema = z.enum(["default", "base"]);
+var clarifyThemeModeColorValueSchema = z.object({
+	light: z.string().optional(),
+	dark: z.string().optional()
+});
+var clarifyThemeColorValueSchema = z.union([z.string(), clarifyThemeModeColorValueSchema]);
+var clarifyThemeColorTokensConfigSchema = z.object({
+	primary: clarifyThemeColorValueSchema.optional(),
+	accent: clarifyThemeColorValueSchema.optional(),
+	background: clarifyThemeColorValueSchema.optional(),
+	foreground: clarifyThemeColorValueSchema.optional(),
+	surface: clarifyThemeColorValueSchema.optional(),
+	muted: clarifyThemeColorValueSchema.optional(),
+	border: clarifyThemeColorValueSchema.optional(),
+	codeBackground: clarifyThemeColorValueSchema.optional()
+});
+var clarifyThemeRadiusTokensConfigSchema = z.object({
+	sm: z.string().optional(),
+	md: z.string().optional(),
+	lg: z.string().optional(),
+	xl: z.string().optional()
+});
+var clarifyThemeTokensConfigSchema = z.object({
+	colors: clarifyThemeColorTokensConfigSchema.optional(),
+	radius: clarifyThemeRadiusTokensConfigSchema.optional()
+});
+var clarifyThemeLayoutConfigSchema = z.object({ maxWidth: z.string().optional() });
+var clarifyThemeConfigSchema = z.object({
+	preset: clarifyThemePresetSchema.optional(),
+	tokens: clarifyThemeTokensConfigSchema.optional(),
+	layout: clarifyThemeLayoutConfigSchema.optional(),
+	editor: z.boolean().optional()
+});
+var clarifyProjectConfigSchema = z.object({
+	title: z.string().optional(),
+	description: z.string().optional(),
+	siteUrl: z.string().optional(),
+	source: clarifySourceConfigSchema.optional(),
+	logo: clarifyLogoConfigSchema.optional(),
+	homeUrl: z.string().optional(),
+	favicon: clarifyFaviconConfigSchema.optional(),
+	theme: clarifyThemeConfigSchema.optional(),
+	routePrefix: z.string().optional(),
+	assetPrefix: z.string().optional(),
+	navbar: z.object({ links: z.array(clarifyNavbarLinkSchema).optional() }).optional(),
+	banner: clarifyBannerConfigOptionsSchema.optional(),
+	footer: clarifyFooterConfigSchema.optional(),
+	variables: clarifyVariablesConfigSchema.optional(),
+	i18n: clarifyI18nConfigSchema.optional(),
+	tabs: clarifyTabsConfigSchema.optional()
+});
+//#endregion
+//#region source/core/config/config.ts
+function formatIssuePath(path) {
+	return path.reduce((result, segment) => {
+		if (typeof segment === "number") return `${result}[${segment}]`;
+		const key = String(segment);
+		return result ? `${result}.${key}` : key;
+	}, "");
+}
+function formatProjectConfigError(error) {
+	const issue = error.issues[0];
+	if (!issue) return "[clarify] config is invalid";
+	const path = formatIssuePath(issue.path);
+	if (!path) return `[clarify] config must contain an object: ${issue.message}`;
+	return `[clarify] config field "${path}" is invalid: ${issue.message}`;
+}
+function validateProjectConfig(value) {
+	const result = clarifyProjectConfigSchema.safeParse(value);
+	if (!result.success) throw new Error(formatProjectConfigError(result.error));
+	return result.data;
+}
+function resolveI18nConfig(i18n) {
+	if (!i18n) return void 0;
+	const firstLocale = i18n.locales[0]?.code;
+	const defaultLocale = i18n.defaultLocale ?? firstLocale;
+	if (!defaultLocale) return void 0;
+	return {
+		defaultLocale,
+		missing: i18n.missing ?? "fallback",
+		locales: i18n.locales
+	};
+}
+function resolveRoutePrefix(routePrefix) {
+	const trimmed = routePrefix?.trim();
+	if (!trimmed || trimmed === "/") return "/";
+	return `/${trimmed.replace(/^\/+|\/+$/g, "")}/`;
+}
+function resolveAssetPrefix(assetPrefix, routePrefix) {
+	const trimmed = assetPrefix?.trim();
+	if (trimmed === void 0) return routePrefix;
+	if (trimmed === "./" || trimmed === "") return trimmed || "/";
+	if (!trimmed || trimmed === "/") return "/";
+	if (/^[a-z][a-z\d+.-]*:\/\//i.test(trimmed)) return trimmed.endsWith("/") ? trimmed : `${trimmed}/`;
+	if (trimmed.startsWith("./") || trimmed.startsWith("../")) return trimmed.endsWith("/") ? trimmed : `${trimmed}/`;
+	return `/${trimmed.replace(/^\/+|\/+$/g, "")}/`;
+}
+function resolveProjectConfig(config = {}) {
+	const routePrefix = resolveRoutePrefix(config.routePrefix);
+	return {
+		title: config.title ?? "Clarify Docs",
+		description: config.description ?? "",
+		siteUrl: config.siteUrl,
+		source: config.source,
+		logo: config.logo,
+		homeUrl: config.homeUrl,
+		favicon: config.favicon,
+		routePrefix,
+		assetPrefix: resolveAssetPrefix(config.assetPrefix, routePrefix),
+		theme: resolveThemeConfig(config.theme),
+		navbar: config.navbar,
+		banner: config.banner,
+		footer: config.footer,
+		variables: config.variables ?? {},
+		i18n: resolveI18nConfig(config.i18n),
+		tabs: config.tabs
+	};
+}
+//#endregion
+//#region source/core/config/user-config.ts
+function defineConfig(config) {
+	validateProjectConfig(config);
+	return config;
+}
+/**
+* Config filenames Clarify CLI looks for at the project root, in resolution
+* order. Exported so other modules (e.g. the dev `project-info` endpoint) can
+* surface the same list to tooling without duplicating it.
+*/
+var CONFIG_FILENAMES = [
+	"clarify.ts",
+	"clarify.js",
+	"clarify.json"
+];
+function findClarifyConfigFile(root) {
+	for (const filename of CONFIG_FILENAMES) {
+		const filePath = resolve(root, filename);
+		if (existsSync(filePath)) return filePath;
+	}
+}
+function assertConfigObject(config, configFile) {
+	if (!config || typeof config !== "object" || Array.isArray(config)) throw new Error(`[clarify] ${configFile} must export a configuration object`);
+	return config;
+}
+function loadJsonConfig(configFile) {
+	const config = assertConfigObject(JSON.parse(readFileSync(configFile, "utf-8")), configFile);
+	const projectConfig = validateProjectConfig(config);
+	const ssg = config.ssg && typeof config.ssg === "object" && !Array.isArray(config.ssg) ? config.ssg : void 0;
+	return {
+		...projectConfig,
+		...ssg ? { ssg } : {}
+	};
+}
+async function loadClarifyConfig(root, env) {
+	const configFile = findClarifyConfigFile(root);
+	if (!configFile) return {};
+	if (configFile.endsWith(".json")) return loadJsonConfig(configFile);
+	return assertConfigObject((await loadConfigFromFile(env, configFile, root, "silent"))?.config, configFile);
+}
+/**
+* File extensions Clarify treats as content files. Kept in sync with the
+* patterns used by route discovery in `parsers/routes.ts` and the OpenAPI
+* page generator. Exposed to tooling so the extension's "is this a content
+* file?" check stays accurate without duplicating the regex.
+*/
+var CONTENT_FILE_EXTENSIONS = [
+	".md",
+	".mdx",
+	".openapi.json",
+	".openapi.yaml",
+	".openapi.yml"
+];
+/**
+* Build the project-info response payload from the resolved plugin state.
+*/
+function buildProjectInfo(context) {
+	const { projectRoot, contentRoot, projectConfig } = context;
+	const response = {
+		configFilenames: CONFIG_FILENAMES,
+		contentFileExtensions: CONTENT_FILE_EXTENSIONS,
+		contentRoot: (contentRoot.startsWith(projectRoot) ? contentRoot.slice(projectRoot.length).replace(/^[/\\]+/, "") : contentRoot) || "source",
+		projectRoot
+	};
+	if (projectConfig.i18n) response.i18n = {
+		defaultLocale: projectConfig.i18n.defaultLocale,
+		locales: projectConfig.i18n.locales.map((l) => l.code)
+	};
+	return response;
+}
+/**
+* Handle a request to the project-info endpoint. Responds to any method
+* (GET is typical) with the JSON payload — there is no request body to parse.
+*/
+function handleProjectInfoRequest(_req, res, context) {
+	res.setHeader("Content-Type", "application/json; charset=utf-8");
+	res.end(JSON.stringify(buildProjectInfo(context)));
+}
+//#endregion
+//#region source/core/runtime/virtual-modules.ts
+var VIRTUAL_CONFIG = "virtual:clarify/config";
+var VIRTUAL_ROUTES = "virtual:clarify/routes";
+var VIRTUAL_SERVER_ROUTES = "virtual:clarify/routes/server";
+var VIRTUAL_OPENAPI = "virtual:clarify/openapi";
+var VIRTUAL_SLOTS = "virtual:clarify/slots";
+var VIRTUAL_SLOT = "virtual:clarify/slot";
+var VIRTUAL_CLIENT_ENTRY = "virtual:clarify/entry-client";
+var RESOLVED_CLIENT_ENTRY = "\0virtual:clarify/entry-client";
+function resolveVirtualId(id) {
+	return "\0" + id;
+}
+function stripVirtualPrefix(id) {
+	return id.startsWith("\0") ? id.slice(1) : id;
+}
+/**
+* Fixed virtual module IDs (excluding the client entry, which has a special
+* resolved form). Used to avoid hardcoding the constant list in every
+* `resolveId` implementation.
+*/
+var FIXED_VIRTUAL_IDS = [
+	VIRTUAL_CONFIG,
+	VIRTUAL_ROUTES,
+	VIRTUAL_SERVER_ROUTES,
+	VIRTUAL_OPENAPI,
+	VIRTUAL_SLOTS,
+	VIRTUAL_SLOT
+];
+/**
+* Shared `resolveId` logic for all Clarify virtual modules. Used by both the
+* Vite core plugin (dev + build) and the SSG virtual plugin so the ID-to-
+* resolved-ID mapping has a single source of truth.
+*
+* Returns the resolved ID (with `\0` prefix per Vite convention) or `null`
+* if the ID is not a Clarify virtual module.
+*/
+function resolveVirtualModuleId(id, modules, routes) {
+	if (id === "virtual:clarify/entry-client" || id === RESOLVED_CLIENT_ENTRY) return RESOLVED_CLIENT_ENTRY;
+	for (const virtualId of FIXED_VIRTUAL_IDS) if (id === virtualId || id === resolveVirtualId(virtualId)) return resolveVirtualId(virtualId);
+	const moduleId = stripVirtualPrefix(id);
+	if (modules.has(moduleId)) return resolveVirtualId(moduleId);
+	const route = routes.find((route) => route.virtualModuleId === id || route.virtualModuleId === moduleId);
+	if (route) return resolveVirtualId(route.virtualModuleId);
+	return null;
+}
+function generateConfigModule(projectConfig, buildOptions, version) {
+	const runtimeConfig = {
+		...projectConfig,
+		...buildOptions
+	};
+	if (version) runtimeConfig.version = version;
+	return `export const config = ${JSON.stringify(runtimeConfig)};`;
+}
+function moduleSpecifier(value) {
+	return JSON.stringify(value);
+}
+function routeToRuntimeObject(route, component, mode) {
+	const obj = {
+		path: route.path,
+		title: route.title,
+		component,
+		kind: route.kind
+	};
+	if (mode === "client") obj.lazy = true;
+	if (route.basePath) obj.basePath = route.basePath;
+	if (route.locale) obj.locale = route.locale;
+	if (route.isFallback) obj.isFallback = true;
+	if (route.isBareAlias) obj.isBareAlias = true;
+	if (route.alternates) obj.alternates = route.alternates;
+	if (route.description) obj.description = route.description;
+	if (route.keywords?.length) obj.keywords = route.keywords;
+	if (route.contentArtifactUrl) obj.contentArtifactUrl = route.contentArtifactUrl;
+	if (route.sourceUrl) obj.sourceUrl = route.sourceUrl;
+	if (route.sections?.length) obj.sections = route.sections.map((s) => ({
+		id: s.id,
+		title: s.title,
+		level: s.level,
+		badge: s.badge,
+		tags: s.tags
+	}));
+	return obj;
+}
+function generateRoutesModule(routes, navigation, mode = "client") {
+	return `${mode === "server" ? routes.map((r, i) => `import Page${i} from ${moduleSpecifier(r.virtualModuleId)};`).join("\n") : `import { createContentDiagnosticComponent } from '@clarify-labs/renderer';`}\n\nexport const routes = [\n${routes.map((r, i) => {
+		const component = mode === "server" ? `Page${i}` : `() => import(${moduleSpecifier(r.virtualModuleId)}).catch((error) => Promise.resolve({ default: createContentDiagnosticComponent({ kind: 'route-load', title: 'This page could not be loaded', message: error instanceof Error ? error.message : String(error), details: error instanceof Error ? error.stack : undefined }) }))`;
+		const placeholder = `__COMPONENT_${i}__`;
+		const obj = routeToRuntimeObject(r, placeholder, mode);
+		return `  ${JSON.stringify(obj, null, 0).replace(`"${placeholder}"`, component).replace(/"([A-Za-z_$][\w$]*)":/g, "$1: ")}`;
+	}).join(",\n")}\n];\n\nexport const navigation = ${JSON.stringify(navigation, null, 2)};\n`;
+}
+function createClientEntryModule(options = {}) {
+	return `
+import '@clarify-labs/renderer/style.css';
+import { render } from '@clarify-labs/renderer/client';
+import { routes, navigation } from '${VIRTUAL_ROUTES}';
+import { config } from '${VIRTUAL_CONFIG}';
+import { openApis } from '${VIRTUAL_OPENAPI}';
+import { runtimeSlots } from '${VIRTUAL_SLOTS}';
+render({ config, routes, navigation, openApis, runtimeSlots, themeEditor: ${JSON.stringify(options.themeEditor ?? false)} });`;
+}
+/**
+* Collect every plugin's `slots` declarations into a single runtime registry
+* module. Component modules are exported as lazy import factories so the
+* renderer can decide whether to code-split (client) or pre-resolve (SSR).
+*
+* Relative component paths are resolved against the project `root` so that
+* the generated `import()` call uses an absolute specifier — Vite cannot
+* resolve relative imports from virtual modules.
+*
+* Slot name validity is enforced at compile time by the `UISlotName`
+* type — no runtime validation is needed.
+*/
+function createRuntimeSlotsModule(plugins = [], root = process.cwd()) {
+	const registrations = [];
+	for (const plugin of plugins) for (const slot of plugin.slots ?? []) registrations.push({
+		plugin: plugin.name,
+		slot
+	});
+	if (registrations.length === 0) return "export const runtimeSlots = {};\n";
+	const grouped = /* @__PURE__ */ new Map();
+	for (const { plugin, slot } of registrations) {
+		if (slot.name.endsWith(".replace")) {
+			const existing = grouped.get(slot.name);
+			if (existing) console.warn(`[clarify] Multiple plugins register slot "${slot.name}": "${plugin}" overrides "${existing[existing.length - 1]}". Only the last registration is used.`);
+		}
+		if (!slot.component.startsWith("/")) throw new Error(`[clarify] Plugin "${plugin}" slot "${slot.name}" has an invalid component path "${slot.component}". Component paths must start with "/" to reference the project root.`);
+		const componentPath = root + slot.component;
+		const entry = `{ plugin: ${JSON.stringify(plugin)}, component: () => import(${moduleSpecifier(componentPath)}) }`;
+		const list = grouped.get(slot.name) ?? [];
+		list.push(entry);
+		grouped.set(slot.name, list);
+	}
+	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) {
+	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 default createContentDiagnosticComponent(contentDiagnostic);
+`;
+}
+function buildVirtualModules(args) {
+	const modules = /* @__PURE__ */ new Map();
+	const clientEntryModule = createClientEntryModule({ themeEditor: args.themeEditor });
+	const allPlugins = [...args.plugins ?? []];
+	modules.set(VIRTUAL_CONFIG, generateConfigModule(args.projectConfig, args.generateOptions, args.version));
+	modules.set(VIRTUAL_ROUTES, generateRoutesModule(args.routes, args.navigation, "client"));
+	modules.set(VIRTUAL_SERVER_ROUTES, generateRoutesModule(args.routes, args.navigation, "server"));
+	modules.set(VIRTUAL_SLOTS, createRuntimeSlotsModule(allPlugins, args.generateOptions.projectRoot));
+	modules.set(VIRTUAL_OPENAPI, "export const openApis = {};");
+	modules.set(VIRTUAL_SLOT, "export { useSlot } from '@clarify-labs/renderer';\n");
+	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.filePath)};`;
+		modules.set(route.virtualModuleId, moduleContent);
+	}
+	return modules;
+}
+//#endregion
+//#region source/core/adapters.ts
+function invalidateVirtualModules(engine, server) {
+	for (const id of engine.modules.keys()) {
+		const moduleNode = server.moduleGraph.getModuleById(resolveVirtualId(id));
+		if (moduleNode) server.moduleGraph.invalidateModule(moduleNode);
+	}
+}
+async function refreshDevServer(engine, server) {
+	await engine.refresh();
+	invalidateVirtualModules(engine, server);
+}
+function createNormalizedMdxContentPlugin(engine) {
+	return {
+		name: "clarify:normalized-mdx-content",
+		enforce: "pre",
+		transform(_code, id) {
+			if (!/\.mdx?(?:\?|$)/.test(id)) return null;
+			const filePath = id.replace(/\?.*$/, "");
+			const route = engine.routes.find((route) => route.kind === "mdx" && route.filePath === filePath);
+			if (!route || route.content === void 0) return null;
+			return {
+				code: route.content,
+				map: null
+			};
+		}
+	};
+}
+function createMdxPlugin() {
+	return mdxPlugin({
+		include: ["**/*.{md,mdx}"],
+		jsxImportSource: "react",
+		providerImportSource: "@clarify-labs/renderer",
+		remarkPlugins,
+		rehypePlugins
+	});
+}
+function createClarifyViteCorePlugin(engine, normalizedMdxContentPlugin, mdx) {
+	let viteConfig;
+	return {
+		name: "clarify:core",
+		async config() {
+			return {
+				base: engine.projectConfig.assetPrefix,
+				build: {
+					...engine.generateOptions.outputDirectory ? { outDir: engine.generateOptions.outputDirectory } : {},
+					manifest: true
+				}
+			};
+		},
+		configResolved(config) {
+			viteConfig = config;
+			engine.configureRuntime({
+				command: config.command,
+				mode: config.mode,
+				outputDirectory: config.build.outDir
+			});
+			if (!engine.generateOptions.outputDirectory) engine.generateOptions.outputDirectory = config.build.outDir;
+		},
+		async buildStart() {
+			if (!await engine.beginBuild()) return;
+			engine.writeEnvTypes();
+		},
+		async handleHotUpdate(ctx) {
+			const changedFile = isAbsolute(ctx.file) ? ctx.file : join(engine.root, ctx.file);
+			if (engine.configFilePath && changedFile === engine.configFilePath) {
+				await engine.prepare({
+					command: "serve",
+					mode: viteConfig.mode
+				}, engine.options, { force: true });
+				invalidateVirtualModules(engine, ctx.server);
+				ctx.server.ws.send({ type: "full-reload" });
+				return [];
+			}
+			const relativeContentFile = relative(engine.contentRoot, changedFile);
+			if (!(relativeContentFile && !relativeContentFile.startsWith("..") && !isAbsolute(relativeContentFile)) || !engine.hasContentRouteForFile(changedFile)) return;
+			await refreshDevServer(engine, ctx.server);
+			return [];
+		},
+		resolveId(id) {
+			return resolveVirtualModuleId(id, engine.modules, engine.routes);
+		},
+		load(id) {
+			return engine.loadModule(id);
+		},
+		async configureServer(server) {
+			server.watcher.add(engine.contentRoot);
+			if (engine.configFilePath) server.watcher.add(engine.configFilePath);
+			let reloadQueued = false;
+			const invalidateAndReload = () => {
+				if (reloadQueued) return;
+				reloadQueued = true;
+				queueMicrotask(() => {
+					reloadQueued = false;
+					invalidateVirtualModules(engine, server);
+					server.ws.send({ type: "full-reload" });
+				});
+			};
+			engine.ctx.onRoutesChange(invalidateAndReload);
+			engine.ctx.onNavigationChange(invalidateAndReload);
+			server.middlewares.use((req, res, next) => {
+				if (req.url === "/dev/query-preview-route" && req.method === "POST") return handleDevRouteRequest(req, res, engine.routes, engine.runtimeContext());
+				if (req.url === "/dev/project-info" && (req.method === "GET" || req.method === "HEAD")) return handleProjectInfoRequest(req, res, engine.runtimeContext());
+				next();
+			});
+			const handleContentTreeChange = async (filePath) => {
+				const changedFile = isAbsolute(filePath) ? filePath : join(engine.root, filePath);
+				const relativeContentFile = relative(engine.contentRoot, changedFile);
+				if (!(relativeContentFile && !relativeContentFile.startsWith("..") && !isAbsolute(relativeContentFile))) return;
+				await refreshDevServer(engine, server);
+			};
+			server.watcher.on("add", handleContentTreeChange);
+			server.watcher.on("unlink", handleContentTreeChange);
+			await engine.configureDevServer(server);
+		},
+		transformIndexHtml: {
+			order: "pre",
+			async handler(html, transformCtx) {
+				const clientEntryId = transformCtx.server ? `/@id/${VIRTUAL_CLIENT_ENTRY}` : VIRTUAL_CLIENT_ENTRY;
+				const result = await engine.transformHtml({
+					html,
+					tags: [],
+					clientEntryId,
+					dev: Boolean(transformCtx.server)
+				});
+				return {
+					html: result.html,
+					tags: result.tags
+				};
+			}
+		},
+		async generateBundle() {
+			const assets = await engine.collectBuildAssets();
+			for (const asset of assets) this.emitFile({
+				type: "asset",
+				fileName: asset.fileName,
+				source: asset.source
+			});
+			await engine.endBuild();
+		},
+		async closeBundle() {
+			if (!engine.shouldRunBuild()) return;
+			engine.configureRuntime({
+				outputDirectory: viteConfig.build.outDir,
+				ssrPlugins: [
+					engine.createSSGVirtualPlugin(),
+					normalizedMdxContentPlugin,
+					mdx
+				]
+			});
+			await engine.runSSG();
+		}
+	};
+}
+/**
+* Creates the Clarify Vite plugins bound to an already-prepared engine.
+*
+* The caller is responsible for running `engine.prepare()` (initialize +
+* discoverSite + buildModules) before constructing the Vite config that
+* includes these plugins. The adapter never initializes or discovers the
+* site itself - it only bridges Vite lifecycle hooks to the engine.
+*/
+function createViteAdapter(engine) {
+	const normalizedMdxContentPlugin = createNormalizedMdxContentPlugin(engine);
+	const mdx = createMdxPlugin();
+	const tailwind = tailwindcss();
+	return [
+		...react(),
+		...Array.isArray(tailwind) ? tailwind : [tailwind],
+		normalizedMdxContentPlugin,
+		createClarifyViteCorePlugin(engine, normalizedMdxContentPlugin, mdx),
+		mdx
+	];
+}
+var cliPackageVersion = {
+	name: "@clarify-labs/cli",
+	version: "0.10.0",
+	license: "AGPL-3.0-only",
+	type: "module",
+	repository: {
+		"type": "git",
+		"url": "https://github.com/taicode-labs/clarify",
+		"directory": "packages/cli"
+	},
+	main: "output/index.cjs",
+	module: "output/index.js",
+	types: "output/index.d.ts",
+	bin: { "clarify": "bin/clarify.js" },
+	exports: {
+		".": {
+			"types": "./output/index.d.ts",
+			"import": "./output/index.js",
+			"require": "./output/index.cjs",
+			"default": "./output/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	files: [
+		"LICENSE",
+		"bin",
+		"output"
+	],
+	scripts: {
+		"dev": "vite build --watch",
+		"build": "vite build",
+		"lint": "eslint source/",
+		"lint:fix": "eslint source/ --fix",
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"test": "vitest run",
+		"test:watch": "vitest"
+	},
+	dependencies: {
+		"@apidevtools/swagger-parser": "^12.1.0",
+		"@clarify-labs/renderer": "workspace:*",
+		"@clarify-labs/templates": "workspace:*",
+		"@mdx-js/mdx": "^3.1.1",
+		"@mdx-js/rollup": "^3.1.1",
+		"@tailwindcss/vite": "^4.3.2",
+		"@vitejs/plugin-react": "^6.0.3",
+		"cac": "^7.0.0",
+		"github-slugger": "^2.0.0",
+		"gray-matter": "^4.0.3",
+		"mdast-util-to-string": "^4.0.0",
+		"mermaid": "^11.4.0",
+		"openapi-types": "^12.1.3",
+		"pagefind": "^1.5.2",
+		"react": "^19.1.0",
+		"react-dom": "^19.1.0",
+		"react-router": "^7.0.0",
+		"react-router-dom": "^7.0.0",
+		"react-zoom-pan-pinch": "^4.0.3",
+		"remark": "^15.0.1",
+		"remark-gfm": "^4.0.1",
+		"shiki": "4.3.0",
+		"unist-util-visit": "^5.1.0",
+		"vite": "^8.1.4",
+		"yaml": "^2.9.0",
+		"zod": "^4.4.3"
+	},
+	devDependencies: {
+		"@types/react": "^19.2.17",
+		"typescript": "^6.0.3",
+		"vite-plugin-dts": "^5.0.3",
+		"vitest": "^4.1.10"
 	}
-	for (const tab of config.tabs ?? []) visitPages(tab.pages);
-	return items;
+}.version ?? "0.0.0";
+var cliPackageVersionWithCaret = `^${cliPackageVersion}`;
+//#endregion
+//#region source/core/config/options.ts
+function resolveBuildOptions(options = {}) {
+	return {
+		projectRoot: options.projectRoot ?? process.cwd(),
+		rootDirectory: options.rootDirectory ?? "source",
+		outputDirectory: options.outputDirectory,
+		ssg: { failOnError: options.ssg?.failOnError ?? true }
+	};
 }
-function virtualModuleIdFromPath(path) {
-	return `virtual:clarify-page/${path.replace(/^\/+/, "") || "index"}`;
+//#endregion
+//#region source/plugins/content-artifacts/artifacts.ts
+var UTF8_SIGNATURE = "";
+function normalizeBasePath(basePath) {
+	if (!basePath || basePath === "/") return "";
+	return "/" + basePath.replace(/^\/+|\/+$/g, "");
 }
-function createConfiguredOpenAPIRoutes(routes, config) {
-	const pageItems = collectOpenAPIPageItems(config);
-	if (!pageItems.length) return routes;
-	const additions = [];
-	const existingKeys = new Set(routes.map((route) => `${route.locale ?? ""}:${route.basePath ?? route.path}`));
-	for (const item of pageItems) {
-		const tagFilter = item.filter?.tags?.filter(Boolean);
-		const sourceBasePath = openAPIPagePathFromRef(item.openapi);
-		const targetBasePath = openAPIPagePathFromRef(item.openapi, tagFilter, item.path);
-		if (sourceBasePath === targetBasePath && !tagFilter?.length) continue;
-		for (const route of routes) {
-			if (route.kind !== "openapi" || (route.basePath ?? route.path) !== sourceBasePath) continue;
-			const key = `${route.locale ?? ""}:${targetBasePath}`;
-			if (existingKeys.has(key)) continue;
-			existingKeys.add(key);
-			additions.push({
-				...route,
-				path: route.locale && config.i18n ? localizedRoutePath(targetBasePath, route.locale, config.i18n) : targetBasePath,
-				basePath: targetBasePath,
-				title: route.title,
-				virtualModuleId: virtualModuleIdFromPath(targetBasePath),
-				openapiTagFilter: tagFilter?.length ? tagFilter : void 0
-			});
+function containsNonAscii(content) {
+	return [...content].some((character) => character.codePointAt(0) > 127);
+}
+function withUtf8Signature(content) {
+	if (!containsNonAscii(content) || content.startsWith(UTF8_SIGNATURE)) return content;
+	return `${UTF8_SIGNATURE}${content}`;
+}
+function shouldUseUtf8Signature(route) {
+	if (route.kind === "mdx") return true;
+	return false;
+}
+function routeToMarkdownArtifactUrl(routePath) {
+	return `${routePath === "/" ? "/index" : routePath.replace(/\/$/, "")}.md`;
+}
+function routeToOpenAPIArtifactUrl(routePath) {
+	return `${routePath === "/" ? "/index" : routePath.replace(/\/$/, "")}.openapi.json`;
+}
+function attachContentArtifactUrls(routes) {
+	for (const route of routes) route.contentArtifactUrl = route.kind === "openapi" ? routeToOpenAPIArtifactUrl(route.path) : routeToMarkdownArtifactUrl(route.path);
+}
+function readRouteContent(route) {
+	if (route.content !== void 0) return route.content;
+	throw new Error(`Route content is missing from route context: ${route.filePath}`);
+}
+function readRouteArtifactContent(route) {
+	const content = readRouteContent(route);
+	return shouldUseUtf8Signature(route) ? withUtf8Signature(content) : content;
+}
+function isLlmsTxtRoute(route) {
+	return !route.path.split("/").includes("404");
+}
+function llmsTxtDescription(route) {
+	if (route.description) return route.description;
+	const sections = route.sections?.filter((section) => section.level === 2).slice(0, 3).map((section) => section.title);
+	if (sections?.length) return `Covers ${sections.join(", ")}.`;
+	if (route.keywords?.length) return `Related topics: ${route.keywords.join(", ")}.`;
+	if (route.kind === "openapi") return "OpenAPI artifact for machine-readable API reference data.";
+}
+function llmsTxtListItem(route, basePath) {
+	if (!route.contentArtifactUrl) return void 0;
+	const description = llmsTxtDescription(route);
+	return description ? `- [${route.title}](${basePath}${route.contentArtifactUrl}): ${description}` : `- [${route.title}](${basePath}${route.contentArtifactUrl})`;
+}
+function llmsTxtLocaleLabel(locale, projectConfig) {
+	return projectConfig.i18n?.locales.find((item) => item.code === locale)?.label ?? locale;
+}
+function groupRoutesByLocale(routes) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const route of routes) {
+		const key = route.locale ?? "default";
+		groups.set(key, [...groups.get(key) ?? [], route]);
+	}
+	return groups;
+}
+function groupLlmsTxtRoutesByLocale(routes, projectConfig) {
+	const routesBySource = /* @__PURE__ */ new Map();
+	const defaultLocale = projectConfig.i18n?.defaultLocale;
+	for (const route of routes) {
+		const sourceKey = `${route.locale ?? defaultLocale ?? "default"}:${route.basePath ?? route.contentArtifactUrl ?? route.path}`;
+		const previousRoute = routesBySource.get(sourceKey);
+		if (!previousRoute || previousRoute.locale && !route.locale) routesBySource.set(sourceKey, route);
+	}
+	return groupRoutesByLocale([...routesBySource.values()].map((route) => ({
+		...route,
+		locale: route.locale ?? defaultLocale
+	})));
+}
+function llmsTxtDocsSectionTitle(locale, groupCount, projectConfig) {
+	if (groupCount <= 1) return "Docs";
+	return `Docs - ${locale === "default" ? "Default" : llmsTxtLocaleLabel(locale, projectConfig)}`;
+}
+function createLlmsTxt(routes, projectConfig) {
+	const basePath = normalizeBasePath(projectConfig.routePrefix);
+	const lines = [`# ${projectConfig.title}`, ""];
+	if (projectConfig.description) lines.push(`> ${projectConfig.description}`, "");
+	lines.push("This file lists the source-ready Markdown and OpenAPI artifacts for this documentation site.", "");
+	const mdxRoutes = routes.filter((route) => route.kind === "mdx" && isLlmsTxtRoute(route) && !route.isBareAlias);
+	if (mdxRoutes.length > 0) {
+		const localizedGroups = groupLlmsTxtRoutesByLocale(mdxRoutes, projectConfig);
+		for (const [locale, localeRoutes] of localizedGroups) {
+			lines.push(`## ${llmsTxtDocsSectionTitle(locale, localizedGroups.size, projectConfig)}`);
+			for (const route of localeRoutes) {
+				const item = llmsTxtListItem(route, basePath);
+				if (item) lines.push(item);
+			}
+			lines.push("");
 		}
 	}
-	const nextRoutes = [...routes, ...additions];
-	return config.i18n ? nextRoutes.map((route) => withAlternates(route, nextRoutes, config.i18n)) : nextRoutes;
+	const openApiRoutes = routes.filter((route) => route.kind === "openapi" && isLlmsTxtRoute(route) && !route.isBareAlias);
+	if (openApiRoutes.length > 0) {
+		if (lines.at(-1) !== "") lines.push("");
+		lines.push("## OpenAPI");
+		for (const route of openApiRoutes) {
+			const item = llmsTxtListItem(route, basePath);
+			if (item) lines.push(item);
+		}
+	}
+	while (lines.at(-1) === "") lines.pop();
+	return `${lines.join("\n")}\n`;
 }
-/** Derive a stable, deduplicated key from an absolute spec file path. */
-function specFileKeyFromPath(filePath, projectRoot) {
-	return relative(projectRoot, filePath).replace(/[^a-zA-Z0-9_-]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
+function createLlmsTxtArtifact(routes, projectConfig) {
+	return withUtf8Signature(createLlmsTxt(routes, projectConfig));
 }
-function createOpenAPIPlugin() {
-	/** specs keyed by specFileKey (deduplicated per source file). */
-	const specs = /* @__PURE__ */ new Map();
+//#endregion
+//#region source/plugins/content-artifacts/server.ts
+function normalizeRoutePrefix$1(routePrefix) {
+	if (!routePrefix || routePrefix === "/") return "";
+	return `/${routePrefix.replace(/^\/+|\/+$/g, "")}`;
+}
+function resolveContentArtifactPath(url, projectConfig) {
+	const requestPath = url?.split("?")[0] ?? "";
+	const basePath = normalizeRoutePrefix$1(projectConfig.routePrefix);
+	return basePath && requestPath.startsWith(basePath) ? requestPath.slice(basePath.length) || "/" : requestPath;
+}
+function resolveContentArtifactType(route) {
+	return route.kind === "openapi" ? "application/json; charset=utf-8" : "text/markdown; charset=utf-8";
+}
+function serveContentArtifacts(req, res, projectConfig, routes) {
+	const contentPath = resolveContentArtifactPath(req.url, projectConfig);
+	if (contentPath === "/llms.txt") {
+		res.statusCode = 200;
+		res.setHeader("Content-Type", "text/plain; charset=utf-8");
+		res.end(createLlmsTxtArtifact(routes, projectConfig), "utf8");
+		return true;
+	}
+	if (contentPath.endsWith(".openapi.yaml")) {
+		const jsonPath = contentPath.replace(/\.yaml$/, ".json");
+		const route = routes.find((r) => r.contentArtifactUrl === jsonPath);
+		if (route?.kind === "openapi" && route.content) {
+			const spec = JSON.parse(route.content);
+			res.statusCode = 200;
+			res.setHeader("Content-Type", "text/yaml; charset=utf-8");
+			res.end(stringify(spec, { lineWidth: 0 }), "utf8");
+			return true;
+		}
+		return false;
+	}
+	const route = routes.find((route) => route.contentArtifactUrl === contentPath);
+	if (!route) return false;
+	res.statusCode = 200;
+	res.setHeader("Content-Type", resolveContentArtifactType(route));
+	res.end(readRouteArtifactContent(route), "utf8");
+	return true;
+}
+//#endregion
+//#region source/plugins/content-artifacts/index.ts
+function createContentArtifactsPlugin() {
 	return {
-		name: "clarify:openapi",
+		name: "clarify:content-artifacts",
 		hooks: {
-			"routes:discover": (input) => ({
-				...input,
-				routes: [...input.routes, ...findOpenAPIRoutes(input.contentRoot)]
-			}),
-			"routes:discovered": async (routes, ctx) => {
-				specs.clear();
-				const nextRoutes = createConfiguredOpenAPIRoutes(routes, ctx.projectConfig);
-				const specByFilePath = /* @__PURE__ */ new Map();
-				for (const route of nextRoutes.filter((route) => route.kind === "openapi")) {
-					const specFromCache = specByFilePath.get(route.filePath);
-					const result = specFromCache ? {
-						ok: true,
-						spec: specFromCache
-					} : await readOpenAPISpec(route.filePath, getProjectContentProcessor(ctx));
-					if (!result.ok) {
-						route.diagnostic = result.diagnostic;
-						route.title = route.title || "OpenAPI parse error";
-						route.sections = [];
-						continue;
-					}
-					const spec = result.spec;
-					specByFilePath.set(route.filePath, spec);
-					const specKey = specFileKeyFromPath(route.filePath, ctx.generateOptions.projectRoot);
-					route.specFileKey = specKey;
-					specs.set(specKey, {
-						spec,
-						filePath: route.filePath
-					});
-					route.title = spec.info?.title ?? route.title;
-					route.description = spec.info?.description ?? route.description;
-					route.sections = extractOpenAPISections(spec, route.openapiTagFilter);
-					const pageSpec = route.openapiTagFilter?.length ? filterSpecByTags(spec, route.openapiTagFilter) : spec;
-					route.content = JSON.stringify(pageSpec);
-				}
-				return nextRoutes;
+			"routes:resolved": (input) => {
+				attachContentArtifactUrls(input.routes);
+				return input;
 			},
-			"modules:before": (modules, ctx) => {
-				const registryEntries = {};
-				for (const route of ctx.routes) {
-					if (route.kind !== "openapi" || !route.specFileKey) continue;
-					const spec = specs.get(route.specFileKey)?.spec;
-					if (!spec) continue;
-					const base = (route.basePath ?? route.path).replace(/^\//, "");
-					const registryKey = route.locale ? `virtual:clarify-page/${route.locale}/${base}` : `virtual:clarify-page/${base}`;
-					registryEntries[registryKey] = spec;
-				}
-				modules.set(openApiRegistryModuleId, generateOpenAPIRegistryModule(registryEntries));
-				for (const [specKey, entry] of specs) modules.set(specVirtualModuleId(specKey), generateOpenAPISpecModule(entry.spec));
+			"dev:configureServer": (server, ctx) => {
+				server.middlewares.use((req, res, next) => {
+					if (serveContentArtifacts(req, res, ctx.projectConfig, ctx.routes)) return;
+					next();
+				});
+			},
+			"build:assets": (ctx) => {
+				const assets = [];
 				for (const route of ctx.routes) {
-					if (route.kind !== "openapi") continue;
-					if (route.diagnostic) modules.set(route.virtualModuleId, generateOpenAPIErrorModule(route.diagnostic));
-					else if (route.specFileKey) {
-						const base = (route.basePath ?? route.path).replace(/^\//, "");
-						const specRegistryKey = route.locale ? `virtual:clarify-page/${route.locale}/${base}` : `virtual:clarify-page/${base}`;
-						modules.set(route.virtualModuleId, generateOpenAPIPageModule({
-							specKey: route.specFileKey,
-							specRegistryKey,
-							tagFilter: route.openapiTagFilter
-						}));
+					if (!route.contentArtifactUrl) continue;
+					assets.push({
+						fileName: route.contentArtifactUrl.replace(/^\//, ""),
+						source: readRouteArtifactContent(route)
+					});
+					if (route.kind === "openapi" && route.content) {
+						const yamlFileName = route.contentArtifactUrl.replace(/\.json$/, ".yaml");
+						const spec = JSON.parse(route.content);
+						assets.push({
+							fileName: yamlFileName.replace(/^\//, ""),
+							source: stringify(spec, { lineWidth: 0 })
+						});
 					}
 				}
-				return modules;
+				assets.push({
+					fileName: "llms.txt",
+					source: createLlmsTxtArtifact(ctx.routes, ctx.projectConfig)
+				});
+				return assets;
 			}
 		}
 	};
 }
 //#endregion
-//#region source/core/search-language.ts
-function toPagefindLanguage(locale) {
-	return locale?.trim().replace(/_/g, "-").split("-").filter(Boolean).join("-").toLowerCase() || "en";
-}
-//#endregion
-//#region source/core/temp-dir.ts
-function createClarifyTempDir(name) {
-	return mkdtempSync(join(tmpdir(), `clarify-${name}-`));
+//#region source/plugins/html-shell/index.ts
+var REL_ICON_RE = /<link\s+[^>]*rel=["'][^"']*\bicon\b[^"']*["'][^>]*>/i;
+function inferIconType(href) {
+	const path = href.split(/[?#]/, 1)[0]?.toLowerCase() ?? href.toLowerCase();
+	if (path.endsWith(".svg")) return "image/svg+xml";
+	if (path.endsWith(".png")) return "image/png";
+	if (path.endsWith(".ico")) return "image/x-icon";
+	if (path.endsWith(".webp")) return "image/webp";
 }
-function removeClarifyTempDir(path) {
-	if (!path) return;
-	rmSync(path, {
-		recursive: true,
-		force: true
-	});
+function createIconTag(href, media) {
+	return {
+		tag: "link",
+		attrs: {
+			rel: "icon",
+			...inferIconType(href) ? { type: inferIconType(href) } : {},
+			href,
+			...media ? { media } : {}
+		},
+		injectTo: "head"
+	};
 }
-//#endregion
-//#region source/plugins/search-index/index.ts
-var pagefindContentTypes = {
-	".css": "text/css; charset=utf-8",
-	".js": "text/javascript; charset=utf-8",
-	".json": "application/json; charset=utf-8",
-	".wasm": "application/wasm"
-};
-function assertNoPagefindErrors(action, errors) {
-	if (!errors?.length) return;
-	throw new Error(`[clarify] Pagefind ${action} failed:\n${errors.join("\n")}`);
+function createIconTags(icon) {
+	if (!icon) return [];
+	if (typeof icon === "string") return [createIconTag(icon)];
+	const lightIcon = icon.light ?? icon.dark;
+	const darkIcon = icon.dark ?? icon.light;
+	if (!lightIcon || !darkIcon) return [];
+	if (lightIcon === darkIcon) return [createIconTag(lightIcon)];
+	return [createIconTag(lightIcon, "(prefers-color-scheme: light)"), createIconTag(darkIcon, "(prefers-color-scheme: dark)")];
 }
-async function generatePagefindIndex(options) {
-	const pagefind = await import("pagefind");
-	const { errors, index } = await pagefind.createIndex({
-		excludeSelectors: [
-			"[data-pagefind-ignore]",
-			"script",
-			"style",
-			"svg"
-		],
-		includeCharacters: "._-/#:@",
-		keepIndexUrl: false,
-		verbose: false,
-		writePlayground: false
-	});
-	assertNoPagefindErrors("createIndex", errors);
-	if (!index) throw new Error("[clarify] Pagefind did not create an index.");
-	try {
-		const addResult = await index.addDirectory({
-			path: options.sourceRoot ?? options.outputRoot,
-			glob: "**/*.html"
-		});
-		assertNoPagefindErrors("addDirectory", addResult.errors);
-		assertNoPagefindErrors("writeFiles", (await index.writeFiles({ outputPath: join(options.outputRoot, "pagefind") })).errors);
-		return addResult.page_count;
-	} finally {
-		await index.deleteIndex();
-		await pagefind.close();
-	}
+function createHtmlShellPlugin() {
+	return {
+		name: "clarify:html-shell",
+		hooks: { "html:transform": (input, ctx) => ({
+			html: input.html,
+			tags: [
+				...input.tags,
+				...REL_ICON_RE.test(input.html) ? [] : createIconTags(ctx.projectConfig.favicon ?? ctx.projectConfig.logo),
+				{
+					tag: "script",
+					children: themeBootstrapScript(ctx.projectConfig.theme),
+					injectTo: "head-prepend"
+				},
+				{
+					tag: "script",
+					attrs: {
+						type: "module",
+						src: input.clientEntryId
+					},
+					injectTo: "body"
+				}
+			],
+			clientEntryId: input.clientEntryId,
+			dev: input.dev
+		}) }
+	};
 }
-function routeSearchContent(route) {
-	return [
-		route.title,
-		route.description,
-		route.keywords?.join(" "),
-		route.sections?.map((section) => section.title).join(" "),
-		route.content
-	].filter(Boolean).join("\n\n");
+//#endregion
+//#region source/plugins/openapi/parser.ts
+var OPENAPI_HTTP_METHODS = [
+	"get",
+	"put",
+	"post",
+	"delete",
+	"options",
+	"head",
+	"patch",
+	"trace"
+];
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
 }
-async function generateDevSearchIndex(ctx, root) {
-	const pagefind = await import("pagefind");
-	const { errors, index } = await pagefind.createIndex({
-		includeCharacters: "._-/#:@",
-		keepIndexUrl: false,
-		verbose: false,
-		writePlayground: false
-	});
-	assertNoPagefindErrors("createIndex", errors);
-	if (!index) throw new Error("[clarify] Pagefind did not create an index.");
+function isSameOpenAPIFile(url, filePath) {
 	try {
-		let pageCount = 0;
-		for (const route of ctx.routes) {
-			if (route.isBareAlias) continue;
-			const content = routeSearchContent(route);
-			if (!content.trim()) continue;
-			const result = await index.addCustomRecord({
-				url: route.path,
-				content,
-				language: toPagefindLanguage(route.locale ?? ctx.projectConfig.i18n?.defaultLocale),
-				meta: { title: route.title }
-			});
-			assertNoPagefindErrors(`addCustomRecord ${route.path}`, result.errors);
-			pageCount += 1;
-		}
-		assertNoPagefindErrors("writeFiles", (await index.writeFiles({ outputPath: join(root, "pagefind") })).errors);
-		console.log(`[clarify] Dev search index generated for ${pageCount} pages.`);
-	} finally {
-		await index.deleteIndex();
-		await pagefind.close();
+		return resolve(fileURLToPath(url)) === resolve(filePath);
+	} catch {
+		return resolve(url) === resolve(filePath);
 	}
 }
-function normalizeDevPagefindPath(rawUrl, routePrefix) {
-	const pathname = rawUrl?.split("?")[0];
-	if (!pathname) return void 0;
-	const normalizedPrefix = routePrefix && routePrefix !== "/" ? `/${routePrefix.replace(/^\/+|\/+$/g, "")}` : "";
-	const pagefindPath = normalizedPrefix && pathname.startsWith(`${normalizedPrefix}/pagefind/`) ? pathname.slice(normalizedPrefix.length) : pathname;
-	return pagefindPath.startsWith("/pagefind/") ? pagefindPath : void 0;
-}
-function serveDevPagefind(server, getRoot, ctx) {
-	server.middlewares.use((req, res, next) => {
-		const root = getRoot();
-		const pagefindPath = normalizeDevPagefindPath(req.url, ctx.projectConfig.routePrefix);
-		if (!root || !pagefindPath) {
-			next();
-			return;
-		}
-		const filePath = join(root, pagefindPath);
-		const relativePath = relative(root, filePath);
-		if (relativePath.startsWith("..") || relativePath === "" || !existsSync(filePath)) {
-			next();
-			return;
-		}
-		const contentType = pagefindContentTypes[extname(filePath)] ?? "application/octet-stream";
-		res.setHeader("Content-Type", contentType);
-		createReadStream(filePath).pipe(res);
-	});
-}
-function createSearchIndexPlugin() {
-	return {
-		name: "clarify:search-index",
-		hooks: {
-			async "dev:configureServer"(server, ctx) {
-				let currentRoot;
-				const staleRoots = /* @__PURE__ */ new Set();
-				const replaceDevIndex = async () => {
-					const nextRoot = createClarifyTempDir("pagefind");
-					await generateDevSearchIndex(ctx, nextRoot);
-					const previousRoot = currentRoot;
-					currentRoot = nextRoot;
-					if (previousRoot) {
-						staleRoots.add(previousRoot);
-						setTimeout(() => {
-							staleRoots.delete(previousRoot);
-							removeClarifyTempDir(previousRoot);
-						}, 3e4).unref?.();
-					}
-				};
-				serveDevPagefind(server, () => currentRoot, ctx);
-				await replaceDevIndex();
-				let regenerateTimer;
-				const regenerate = (filePath) => {
-					if (!/\.(md|mdx|json|ya?ml)$/i.test(filePath)) return;
-					if (regenerateTimer) clearTimeout(regenerateTimer);
-					regenerateTimer = setTimeout(() => {
-						replaceDevIndex().catch((err) => {
-							console.error("[clarify] Failed to regenerate dev search index:", err);
-						});
-					}, 100);
-				};
-				server.watcher.on("add", regenerate);
-				server.watcher.on("change", regenerate);
-				server.watcher.on("unlink", regenerate);
-				server.httpServer?.once("close", () => {
-					if (regenerateTimer) clearTimeout(regenerateTimer);
-					removeClarifyTempDir(currentRoot);
-					for (const staleRoot of staleRoots) removeClarifyTempDir(staleRoot);
-				});
-			},
-			async "build:done"(ctx) {
-				const outputDirectory = ctx.generateOptions.outputDirectory;
-				if (!outputDirectory) return;
-				const pageCount = await generatePagefindIndex({ outputRoot: resolve(ctx.generateOptions.projectRoot, outputDirectory) });
-				console.log(`[clarify] Search index generated for ${pageCount} pages.`);
-			}
+function findOpenAPIRoutes(dir, base = dir) {
+	const routes = [];
+	if (!existsSync(dir)) return routes;
+	const entries = readdirSync(dir, { withFileTypes: true });
+	for (const entry of entries) {
+		const fullPath = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			routes.push(...findOpenAPIRoutes(fullPath, base));
+			continue;
 		}
-	};
+		if (!entry.isFile() || !/\.openapi\.(json|yaml|yml)$/.test(entry.name)) continue;
+		const ref = relative(base, fullPath);
+		const cleanPath = routePathFromRef(ref);
+		routes.push({
+			path: cleanPath,
+			basePath: cleanPath,
+			filePath: fullPath,
+			virtualModuleId: virtualModuleIdFromRef(ref),
+			title: kebabToTitle(cleanPath.split("/").pop() ?? "API"),
+			kind: "openapi"
+		});
+	}
+	return routes;
 }
-//#endregion
-//#region source/plugins/seo/artifacts.ts
-function trimTrailingSlash(value) {
-	return value.replace(/\/+$/, "");
+function operationMatchesTags(operationTags, filterTags) {
+	if (!filterTags?.length) return true;
+	return operationTags?.some((tag) => filterTags.includes(tag)) ?? false;
 }
-function normalizeRoutePrefix(routePrefix) {
-	if (!routePrefix || routePrefix === "/") return "";
-	return `/${routePrefix.replace(/^\/+|\/+$/g, "")}`;
+/** Filter an OpenAPI spec to only include paths that have at least one operation matching the given tags. */
+function filterSpecByTags(spec, tags) {
+	const filteredPaths = {};
+	const paths = spec.paths ?? {};
+	for (const path of Object.keys(paths)) {
+		const pathItem = paths[path];
+		if (!pathItem) continue;
+		if (Object.values(pathItem).some((op) => op && typeof op === "object" && operationMatchesTags(op.tags, tags))) filteredPaths[path] = pathItem;
+	}
+	return {
+		...spec,
+		paths: filteredPaths
+	};
 }
-function routeUrl(siteUrl, routePrefix, routePath) {
-	const base = trimTrailingSlash(siteUrl);
-	return `${base}${normalizeRoutePrefix(routePrefix)}${routePath === "/" ? "" : routePath.replace(/^\/+/, "/")}` || base;
+/** Extract endpoint operations from an OpenAPI spec as page sections. */
+function extractOpenAPISections(spec, filterTags) {
+	const sections = [];
+	const paths = spec.paths ?? {};
+	for (const [path, pathItem] of Object.entries(paths)) {
+		if (!pathItem) continue;
+		for (const method of OPENAPI_HTTP_METHODS) {
+			const op = pathItem[method];
+			if (!op || !operationMatchesTags(op.tags, filterTags)) continue;
+			const title = op.summary ?? `${method.toUpperCase()} ${path}`;
+			sections.push({
+				id: slug(`${method} ${path}`),
+				title,
+				level: 2,
+				badge: method.toUpperCase(),
+				tags: op.tags
+			});
+		}
+	}
+	return sections;
 }
-function escapeXml(value) {
-	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
+async function readOpenAPISpec(filePath, contentProcessor) {
+	try {
+		if (!contentProcessor) return {
+			ok: true,
+			spec: await SwaggerParser.dereference(filePath)
+		};
+		const source = readFileSync(filePath, "utf-8");
+		const transformedSource = await contentProcessor.processText(source, "openapi", filePath);
+		if (transformedSource === source) return {
+			ok: true,
+			spec: await SwaggerParser.dereference(filePath)
+		};
+		return {
+			ok: true,
+			spec: await SwaggerParser.dereference(filePath, { resolve: { transformedOpenAPISource: {
+				order: 1,
+				canRead: (file) => isSameOpenAPIFile(file.url, filePath),
+				read: () => transformedSource
+			} } })
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			diagnostic: {
+				kind: "openapi",
+				title: "OpenAPI spec parse failed",
+				message: `Clarify could not parse ${filePath}.`,
+				filePath,
+				details: errorMessage(error)
+			}
+		};
+	}
 }
-function publicRoutes(routes) {
-	return routes.filter((route) => route.path !== "/404" && !route.isBareAlias);
+//#endregion
+//#region source/plugins/openapi/virtual-modules.ts
+var openApiRegistryModuleId = VIRTUAL_OPENAPI;
+var OPENAPI_SPEC_PREFIX = "virtual:clarify/openapi-spec/";
+function specVirtualModuleId(specKey) {
+	return `${OPENAPI_SPEC_PREFIX}${specKey}`;
 }
-function createSitemapXml(routes, config) {
-	if (!config.siteUrl) return void 0;
-	return [
-		"<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
-		"<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">",
-		...publicRoutes(routes).map((route) => routeUrl(config.siteUrl, config.routePrefix, route.path)).filter((url, index, list) => list.indexOf(url) === index).sort().map((url) => `  <url><loc>${escapeXml(url)}</loc></url>`),
-		"</urlset>",
-		""
-	].join("\n");
+function generateOpenAPIRegistryModule(openApis) {
+	return `export const openApis = ${JSON.stringify(openApis)};`;
 }
-function createRobotsTxt(config) {
-	if (!config.siteUrl) return void 0;
-	return [
-		"User-agent: *",
-		"Allow: /",
-		`Sitemap: ${routeUrl(config.siteUrl, config.routePrefix, "/sitemap.xml")}`,
-		""
-	].join("\n");
+/** Generate a virtual module that exports a single spec as default. */
+function generateOpenAPISpecModule(spec) {
+	return `export default ${JSON.stringify(spec)};`;
 }
-//#endregion
-//#region source/plugins/seo/index.ts
-function createSeoPlugin() {
-	return {
-		name: "clarify:seo",
-		hooks: { "build:assets"(ctx) {
-			const sitemap = createSitemapXml(ctx.routes, ctx.projectConfig);
-			const robots = createRobotsTxt(ctx.projectConfig);
-			if (!sitemap || !robots) return [];
-			return [{
-				fileName: "sitemap.xml",
-				source: sitemap
-			}, {
-				fileName: "robots.txt",
-				source: robots
-			}];
-		} }
-	};
+function generateOpenAPIPageModule(opts) {
+	return `import { createOpenApiRouteComponent } from '@clarify-labs/renderer';
+
+export const routeData = ${JSON.stringify({
+		spec: opts.spec,
+		tagFilter: opts.tagFilter
+	})};
+
+export default createOpenApiRouteComponent(routeData);
+`;
 }
-//#endregion
-//#region source/plugins/source-links/source-links.ts
-function trimSlashes(value) {
-	return value.replace(/^\/+|\/+$/g, "");
+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);
+`;
 }
-function normalizeRepositoryUrl(repository) {
-	return repository.replace(/\.git$/, "").replace(/\/+$/, "");
+//#endregion
+//#region source/plugins/openapi/index.ts
+function collectOpenAPIPageItems(config) {
+	const items = [];
+	function visitPages(pages) {
+		if (!pages || pages === "FileTree") return;
+		for (const group of pages) for (const item of group.pages) if (typeof item !== "string" && "openapi" in item && (item.path || item.filter?.tags?.length)) items.push(item);
+	}
+	for (const tab of config.tabs ?? []) visitPages(tab.pages);
+	return items;
 }
-function encodePath(path) {
-	return path.split("/").filter(Boolean).map((segment) => encodeURIComponent(segment)).join("/");
+function virtualModuleIdFromPath(path) {
+	return `virtual:clarify-page/${path.replace(/^\/+/, "") || "index"}`;
 }
-function createSourceUrl(filePath, contentRoot, source) {
-	const repository = normalizeRepositoryUrl(source.repository);
-	const branch = source.branch ?? "main";
-	const sourcePath = [source.directory ? trimSlashes(source.directory) : "", relative(contentRoot, filePath).replaceAll("\\", "/")].filter(Boolean).join("/");
-	return `${repository}/edit/${encodeURIComponent(branch)}/${encodePath(sourcePath)}`;
+function createConfiguredOpenAPIRoutes(routes, config) {
+	const pageItems = collectOpenAPIPageItems(config);
+	if (!pageItems.length) return routes;
+	const additions = [];
+	const existingKeys = new Set(routes.map((route) => `${route.locale ?? ""}:${route.basePath ?? route.path}`));
+	for (const item of pageItems) {
+		const tagFilter = item.filter?.tags?.filter(Boolean);
+		const sourceBasePath = openAPIPagePathFromRef(item.openapi);
+		const targetBasePath = openAPIPagePathFromRef(item.openapi, tagFilter, item.path);
+		if (sourceBasePath === targetBasePath && !tagFilter?.length) continue;
+		for (const route of routes) {
+			if (route.kind !== "openapi" || (route.basePath ?? route.path) !== sourceBasePath) continue;
+			const key = `${route.locale ?? ""}:${targetBasePath}`;
+			if (existingKeys.has(key)) continue;
+			existingKeys.add(key);
+			additions.push({
+				...route,
+				path: route.locale && config.i18n ? localizedRoutePath(targetBasePath, route.locale, config.i18n) : targetBasePath,
+				basePath: targetBasePath,
+				title: route.title,
+				virtualModuleId: virtualModuleIdFromPath(targetBasePath),
+				openapiTagFilter: tagFilter?.length ? tagFilter : void 0
+			});
+		}
+	}
+	const nextRoutes = [...routes, ...additions];
+	return config.i18n ? nextRoutes.map((route) => withAlternates(route, nextRoutes, config.i18n)) : nextRoutes;
 }
-function attachSourceUrls(routes, contentRoot, source) {
-	if (!source) return;
-	for (const route of routes) route.sourceUrl = createSourceUrl(route.filePath, contentRoot, source);
+/** Derive a stable, deduplicated key from an absolute spec file path. */
+function specFileKeyFromPath(filePath, projectRoot) {
+	return relative(projectRoot, filePath).replace(/[^a-zA-Z0-9_-]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
 }
-//#endregion
-//#region source/plugins/source-links/index.ts
-function createSourceLinksPlugin() {
+function createOpenAPIPlugin() {
+	/** specs keyed by specFileKey (deduplicated per source file). */
+	const specs = /* @__PURE__ */ new Map();
 	return {
-		name: "clarify:source-links",
-		hooks: { "routes:discovered": (routes, ctx) => {
-			attachSourceUrls(routes, join(ctx.generateOptions.projectRoot, ctx.generateOptions.rootDirectory), ctx.projectConfig.source);
-			return routes;
-		} }
+		name: "clarify:openapi",
+		hooks: {
+			"routes:discover": (input) => ({
+				...input,
+				routes: [...input.routes, ...findOpenAPIRoutes(input.contentRoot)]
+			}),
+			"routes:discovered": async (routes, ctx) => {
+				specs.clear();
+				const nextRoutes = createConfiguredOpenAPIRoutes(routes, ctx.projectConfig);
+				const specByFilePath = /* @__PURE__ */ new Map();
+				for (const route of nextRoutes.filter((route) => route.kind === "openapi")) {
+					const specFromCache = specByFilePath.get(route.filePath);
+					const processor = createProjectContentProcessor(ctx.plugins, ctx);
+					const result = specFromCache ? {
+						ok: true,
+						spec: specFromCache
+					} : await readOpenAPISpec(route.filePath, processor);
+					if (!result.ok) {
+						route.diagnostic = result.diagnostic;
+						route.title = route.title || "OpenAPI parse error";
+						route.sections = [];
+						continue;
+					}
+					const spec = result.spec;
+					specByFilePath.set(route.filePath, spec);
+					const specKey = specFileKeyFromPath(route.filePath, ctx.generateOptions.projectRoot);
+					route.specFileKey = specKey;
+					specs.set(specKey, {
+						spec,
+						filePath: route.filePath
+					});
+					route.title = spec.info?.title ?? route.title;
+					route.description = spec.info?.description ?? route.description;
+					route.sections = extractOpenAPISections(spec, route.openapiTagFilter);
+					const pageSpec = route.openapiTagFilter?.length ? filterSpecByTags(spec, route.openapiTagFilter) : spec;
+					route.content = JSON.stringify(pageSpec);
+				}
+				return nextRoutes;
+			},
+			"modules:before": (modules, ctx) => {
+				const registryEntries = {};
+				for (const route of ctx.routes) {
+					if (route.kind !== "openapi" || !route.specFileKey) continue;
+					const spec = specs.get(route.specFileKey)?.spec;
+					if (!spec) continue;
+					const base = (route.basePath ?? route.path).replace(/^\//, "");
+					const registryKey = route.locale ? `virtual:clarify-page/${route.locale}/${base}` : `virtual:clarify-page/${base}`;
+					registryEntries[registryKey] = spec;
+				}
+				modules.set(openApiRegistryModuleId, generateOpenAPIRegistryModule(registryEntries));
+				for (const [specKey, entry] of specs) modules.set(specVirtualModuleId(specKey), generateOpenAPISpecModule(entry.spec));
+				for (const route of ctx.routes) {
+					if (route.kind !== "openapi") continue;
+					if (route.diagnostic) modules.set(route.virtualModuleId, generateOpenAPIErrorModule(route.diagnostic));
+					else if (route.specFileKey) {
+						const entry = specs.get(route.specFileKey);
+						if (!entry) continue;
+						modules.set(route.virtualModuleId, generateOpenAPIPageModule({
+							spec: entry.spec,
+							tagFilter: route.openapiTagFilter
+						}));
+					}
+				}
+				return modules;
+			}
+		}
 	};
 }
 //#endregion
-//#region source/parsers/variables.ts
-var variablePattern = /{{\s*([A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*)\s*}}/g;
-function getVariableValue(variables, path) {
-	let current = variables;
-	for (const segment of path.split(".")) {
-		if (!current || typeof current !== "object" || Array.isArray(current)) return void 0;
-		current = current[segment];
-	}
-	return current;
-}
-function stringifyVariableValue(variables, path, stack) {
-	if (stack.includes(path)) throw new Error(`[clarify] variable "${path}" contains a circular reference: ${[...stack, path].join(" -> ")}`);
-	const value = getVariableValue(variables, path);
-	if (value === void 0 || typeof value === "object") return void 0;
-	if (typeof value !== "string") return String(value);
-	return value.replace(variablePattern, (match, nestedPath) => stringifyVariableValue(variables, nestedPath, [...stack, path]) ?? match);
+//#region source/core/project/temp-dir.ts
+function createClarifyTempDir(name) {
+	return mkdtempSync(join(tmpdir(), `clarify-${name}-`));
 }
-function applyVariables(content, variables = {}) {
-	return content.replace(variablePattern, (match, path) => stringifyVariableValue(variables, path, []) ?? match);
+function removeClarifyTempDir(path) {
+	if (!path) return;
+	rmSync(path, {
+		recursive: true,
+		force: true
+	});
 }
 //#endregion
-//#region source/plugins/variables/index.ts
-function applyVariablesToFrontmatter(frontmatter, variables) {
-	const nextFrontmatter = { ...frontmatter };
-	for (const key of ["title", "description"]) {
-		if (typeof nextFrontmatter[key] !== "string") continue;
-		nextFrontmatter[key] = applyVariables(nextFrontmatter[key], variables);
-	}
-	return nextFrontmatter;
-}
-function createVariablesPlugin() {
-	return {
-		name: "clarify:variables",
-		hooks: { "content:transform": (input, ctx) => ({
-			...input,
-			frontmatter: applyVariablesToFrontmatter(input.frontmatter, ctx.projectConfig.variables),
-			content: applyVariables(input.content, ctx.projectConfig.variables)
-		}) }
-	};
+//#region source/plugins/search-index/search-language.ts
+function toPagefindLanguage(locale) {
+	return locale?.trim().replace(/_/g, "-").split("-").filter(Boolean).join("-").toLowerCase() || "en";
 }
 //#endregion
-//#region source/core/builtin.ts
-function createBuiltinPlugins(options = {}) {
-	const plugins = [
-		createVariablesPlugin(),
-		createOpenAPIPlugin(),
-		createSourceLinksPlugin(),
-		createContentArtifactsPlugin(),
-		createSeoPlugin(),
-		createSearchIndexPlugin()
-	];
-	if (options.htmlShell ?? true) plugins.push(createHtmlShellPlugin());
-	return plugins;
+//#region source/plugins/search-index/index.ts
+var pagefindContentTypes = {
+	".css": "text/css; charset=utf-8",
+	".js": "text/javascript; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+	".wasm": "application/wasm"
+};
+function assertNoPagefindErrors(action, errors) {
+	if (!errors?.length) return;
+	throw new Error(`[clarify] Pagefind ${action} failed:\n${errors.join("\n")}`);
 }
-//#endregion
-//#region source/core/config-schema.ts
-var clarifyLogoConfigSchema = z.union([z.string(), z.object({
-	light: z.string().optional(),
-	dark: z.string().optional()
-})]);
-var clarifyFaviconConfigSchema = z.union([z.string(), z.object({
-	light: z.string().optional(),
-	dark: z.string().optional()
-})]);
-var clarifyLocalizedTextSchema = z.union([z.string(), z.record(z.string(), z.string())]);
-var clarifyLocaleConfigSchema = z.object({
-	code: z.string(),
-	label: z.string(),
-	dir: z.union([z.literal("ltr"), z.literal("rtl")]).optional()
-});
-var clarifyI18nConfigSchema = z.object({
-	defaultLocale: z.string().optional(),
-	missing: z.union([
-		z.literal("fallback"),
-		z.literal("404"),
-		z.literal("hide")
-	]).optional(),
-	locales: z.array(clarifyLocaleConfigSchema).min(1)
-}).superRefine((config, ctx) => {
-	const localeCodes = /* @__PURE__ */ new Set();
-	for (const [index, locale] of config.locales.entries()) {
-		if (localeCodes.has(locale.code)) ctx.addIssue({
-			code: z.ZodIssueCode.custom,
-			message: `Duplicate locale code "${locale.code}"`,
-			path: [
-				"locales",
-				index,
-				"code"
-			]
-		});
-		localeCodes.add(locale.code);
-	}
-	if (config.defaultLocale && !localeCodes.has(config.defaultLocale)) ctx.addIssue({
-		code: z.ZodIssueCode.custom,
-		message: "defaultLocale must be one of i18n.locales",
-		path: ["defaultLocale"]
+async function generatePagefindIndex(options, pagefind) {
+	const runtime = pagefind ?? await import("pagefind");
+	const { errors, index } = await runtime.createIndex({
+		excludeSelectors: [
+			"[data-pagefind-ignore]",
+			"script",
+			"style",
+			"svg"
+		],
+		includeCharacters: "._-/#:@",
+		keepIndexUrl: false,
+		verbose: false,
+		writePlayground: false
 	});
-});
-var clarifyNavbarLinkSchema = z.object({
-	label: clarifyLocalizedTextSchema,
-	href: z.string(),
-	external: z.boolean().optional()
-});
-var clarifyBannerConfigSchema = z.object({
-	content: clarifyLocalizedTextSchema,
-	dismissible: z.boolean().optional(),
-	link: clarifyNavbarLinkSchema.optional()
-}).strict();
-var clarifyFooterConfigSchema = z.object({
-	links: z.array(clarifyNavbarLinkSchema).optional(),
-	socials: z.record(z.string(), z.string()).optional(),
-	copyright: clarifyLocalizedTextSchema.optional()
-}).strict();
-var clarifyVariableValueSchema = z.lazy(() => z.union([
-	z.string(),
-	z.number(),
-	z.boolean(),
-	z.record(z.string(), clarifyVariableValueSchema)
-]));
-var clarifyVariablesConfigSchema = z.record(z.string(), clarifyVariableValueSchema);
-var clarifySourceConfigSchema = z.object({
-	repository: z.string(),
-	branch: z.string().optional(),
-	directory: z.string().optional()
-});
-var clarifyPagesItemSchema = z.union([
-	z.string(),
-	z.object({
-		page: z.string(),
-		path: z.string().optional(),
-		title: clarifyLocalizedTextSchema.optional(),
-		icon: z.string().optional(),
-		redirect: z.string().optional()
-	}),
-	z.object({
-		openapi: z.string(),
-		path: z.string().optional(),
-		icon: z.string().optional(),
-		title: clarifyLocalizedTextSchema.optional(),
-		filter: z.object({ tags: z.array(z.string()).optional() }).optional()
-	})
-]);
-var clarifyPagesGroupSchema = z.object({
-	group: clarifyLocalizedTextSchema,
-	icon: z.string().optional(),
-	pages: z.array(clarifyPagesItemSchema)
-});
-var clarifyPagesConfigSchema = z.union([z.array(clarifyPagesGroupSchema), z.literal("FileTree")]);
-var clarifyTabItemSchema = z.object({
-	tab: clarifyLocalizedTextSchema,
-	icon: z.string().optional(),
-	pages: clarifyPagesConfigSchema.optional()
-});
-var clarifyTabsConfigSchema = z.array(clarifyTabItemSchema);
-var clarifyThemePresetSchema = z.enum(["default", "base"]);
-var clarifyThemeModeColorValueSchema = z.object({
-	light: z.string().optional(),
-	dark: z.string().optional()
-});
-var clarifyThemeColorValueSchema = z.union([z.string(), clarifyThemeModeColorValueSchema]);
-var clarifyThemeColorTokensConfigSchema = z.object({
-	primary: clarifyThemeColorValueSchema.optional(),
-	accent: clarifyThemeColorValueSchema.optional(),
-	background: clarifyThemeColorValueSchema.optional(),
-	foreground: clarifyThemeColorValueSchema.optional(),
-	surface: clarifyThemeColorValueSchema.optional(),
-	muted: clarifyThemeColorValueSchema.optional(),
-	border: clarifyThemeColorValueSchema.optional(),
-	codeBackground: clarifyThemeColorValueSchema.optional()
-});
-var clarifyThemeRadiusTokensConfigSchema = z.object({
-	sm: z.string().optional(),
-	md: z.string().optional(),
-	lg: z.string().optional(),
-	xl: z.string().optional()
-});
-var clarifyThemeTokensConfigSchema = z.object({
-	colors: clarifyThemeColorTokensConfigSchema.optional(),
-	radius: clarifyThemeRadiusTokensConfigSchema.optional()
-});
-var clarifyThemeLayoutConfigSchema = z.object({ maxWidth: z.string().optional() });
-var clarifyThemeConfigSchema = z.object({
-	preset: clarifyThemePresetSchema.optional(),
-	tokens: clarifyThemeTokensConfigSchema.optional(),
-	layout: clarifyThemeLayoutConfigSchema.optional(),
-	editor: z.boolean().optional()
-});
-var clarifyProjectConfigSchema = z.object({
-	title: z.string().optional(),
-	description: z.string().optional(),
-	siteUrl: z.string().optional(),
-	source: clarifySourceConfigSchema.optional(),
-	logo: clarifyLogoConfigSchema.optional(),
-	homeUrl: z.string().optional(),
-	favicon: clarifyFaviconConfigSchema.optional(),
-	theme: clarifyThemeConfigSchema.optional(),
-	routePrefix: z.string().optional(),
-	assetPrefix: z.string().optional(),
-	navbar: z.object({ links: z.array(clarifyNavbarLinkSchema).optional() }).optional(),
-	banner: clarifyBannerConfigSchema.optional(),
-	footer: clarifyFooterConfigSchema.optional(),
-	variables: clarifyVariablesConfigSchema.optional(),
-	i18n: clarifyI18nConfigSchema.optional(),
-	tabs: clarifyTabsConfigSchema.optional()
-});
-//#endregion
-//#region source/core/theme.ts
-function resolveThemeConfig(theme = {}) {
-	const preset = theme.preset ?? "default";
-	const presetTheme = themePresets[preset];
+	assertNoPagefindErrors("createIndex", errors);
+	if (!index) throw new Error("[clarify] Pagefind did not create an index.");
+	try {
+		const addResult = await index.addDirectory({
+			path: options.sourceRoot ?? options.outputRoot,
+			glob: "**/*.html"
+		});
+		assertNoPagefindErrors("addDirectory", addResult.errors);
+		assertNoPagefindErrors("writeFiles", (await index.writeFiles({ outputPath: join(options.outputRoot, "pagefind") })).errors);
+		return addResult.page_count;
+	} finally {
+		await index.deleteIndex();
+		if (!pagefind) await runtime.close();
+	}
+}
+function routeSearchContent(route) {
+	return [
+		route.title,
+		route.description,
+		route.keywords?.join(" "),
+		route.sections?.map((section) => section.title).join(" "),
+		route.content
+	].filter(Boolean).join("\n\n");
+}
+async function generateDevSearchIndex(ctx, root, pagefind) {
+	const { errors, index } = await pagefind.createIndex({
+		includeCharacters: "._-/#:@",
+		keepIndexUrl: false,
+		verbose: false,
+		writePlayground: false
+	});
+	assertNoPagefindErrors("createIndex", errors);
+	if (!index) throw new Error("[clarify] Pagefind did not create an index.");
+	try {
+		let pageCount = 0;
+		for (const route of ctx.routes) {
+			if (route.isBareAlias) continue;
+			const content = routeSearchContent(route);
+			if (!content.trim()) continue;
+			const result = await index.addCustomRecord({
+				url: route.path,
+				content,
+				language: toPagefindLanguage(route.locale ?? ctx.projectConfig.i18n?.defaultLocale),
+				meta: { title: route.title }
+			});
+			assertNoPagefindErrors(`addCustomRecord ${route.path}`, result.errors);
+			pageCount += 1;
+		}
+		assertNoPagefindErrors("writeFiles", (await index.writeFiles({ outputPath: join(root, "pagefind") })).errors);
+		console.log(`[clarify] Dev search index generated for ${pageCount} pages.`);
+	} finally {
+		await index.deleteIndex();
+	}
+}
+function normalizeDevPagefindPath(rawUrl, routePrefix) {
+	const pathname = rawUrl?.split("?")[0];
+	if (!pathname) return void 0;
+	const normalizedPrefix = routePrefix && routePrefix !== "/" ? `/${routePrefix.replace(/^\/+|\/+$/g, "")}` : "";
+	const pagefindPath = normalizedPrefix && pathname.startsWith(`${normalizedPrefix}/pagefind/`) ? pathname.slice(normalizedPrefix.length) : pathname;
+	return pagefindPath.startsWith("/pagefind/") ? pagefindPath : void 0;
+}
+function serveDevPagefind(server, getRoot, ctx) {
+	server.middlewares.use((req, res, next) => {
+		const root = getRoot();
+		const pagefindPath = normalizeDevPagefindPath(req.url, ctx.projectConfig.routePrefix);
+		if (!root || !pagefindPath) {
+			next();
+			return;
+		}
+		const filePath = join(root, pagefindPath);
+		const relativePath = relative(root, filePath);
+		if (relativePath.startsWith("..") || relativePath === "" || !existsSync(filePath)) {
+			next();
+			return;
+		}
+		const contentType = pagefindContentTypes[extname(filePath)] ?? "application/octet-stream";
+		res.setHeader("Content-Type", contentType);
+		createReadStream(filePath).pipe(res);
+	});
+}
+function createSearchIndexPlugin() {
 	return {
-		preset,
-		tokens: {
-			colors: {
-				...presetTheme.tokens.colors,
-				...theme.tokens?.colors
+		name: "clarify:search-index",
+		hooks: {
+			async "dev:configureServer"(server, ctx) {
+				const pagefind = await import("pagefind");
+				let currentRoot;
+				const staleRoots = /* @__PURE__ */ new Set();
+				const replaceDevIndex = async () => {
+					const nextRoot = createClarifyTempDir("pagefind");
+					await generateDevSearchIndex(ctx, nextRoot, pagefind);
+					const previousRoot = currentRoot;
+					currentRoot = nextRoot;
+					if (previousRoot) {
+						staleRoots.add(previousRoot);
+						setTimeout(() => {
+							staleRoots.delete(previousRoot);
+							removeClarifyTempDir(previousRoot);
+						}, 3e4).unref?.();
+					}
+				};
+				serveDevPagefind(server, () => currentRoot, ctx);
+				await replaceDevIndex();
+				let regenerateTimer;
+				const regenerate = (filePath) => {
+					if (!/\.(md|mdx|json|ya?ml)$/i.test(filePath)) return;
+					if (regenerateTimer) clearTimeout(regenerateTimer);
+					regenerateTimer = setTimeout(() => {
+						replaceDevIndex().catch((err) => {
+							console.error("[clarify] Failed to regenerate dev search index:", err);
+						});
+					}, 100);
+				};
+				server.watcher.on("add", regenerate);
+				server.watcher.on("change", regenerate);
+				server.watcher.on("unlink", regenerate);
+				server.httpServer?.once("close", () => {
+					if (regenerateTimer) clearTimeout(regenerateTimer);
+					removeClarifyTempDir(currentRoot);
+					for (const staleRoot of staleRoots) removeClarifyTempDir(staleRoot);
+					pagefind.close().catch(() => void 0);
+				});
 			},
-			radius: {
-				...presetTheme.tokens.radius,
-				...theme.tokens?.radius
+			async "build:done"(ctx) {
+				const outputDirectory = ctx.generateOptions.outputDirectory;
+				if (!outputDirectory) return;
+				const pageCount = await generatePagefindIndex({ outputRoot: resolve(ctx.generateOptions.projectRoot, outputDirectory) });
+				console.log(`[clarify] Search index generated for ${pageCount} pages.`);
 			}
-		},
-		layout: {
-			...presetTheme.layout,
-			...theme.layout
-		},
-		editor: theme.editor ?? presetTheme.editor
+		}
 	};
 }
 //#endregion
-//#region source/core/config.ts
-function formatIssuePath(path) {
-	return path.reduce((result, segment) => {
-		if (typeof segment === "number") return `${result}[${segment}]`;
-		const key = String(segment);
-		return result ? `${result}.${key}` : key;
-	}, "");
+//#region source/plugins/seo/artifacts.ts
+function trimTrailingSlash(value) {
+	return value.replace(/\/+$/, "");
 }
-function formatProjectConfigError(error) {
-	const issue = error.issues[0];
-	if (!issue) return "[clarify] config is invalid";
-	const path = formatIssuePath(issue.path);
-	if (!path) return `[clarify] config must contain an object: ${issue.message}`;
-	return `[clarify] config field "${path}" is invalid: ${issue.message}`;
+function normalizeRoutePrefix(routePrefix) {
+	if (!routePrefix || routePrefix === "/") return "";
+	return `/${routePrefix.replace(/^\/+|\/+$/g, "")}`;
 }
-function validateProjectConfig(value) {
-	const result = clarifyProjectConfigSchema.safeParse(value);
-	if (!result.success) throw new Error(formatProjectConfigError(result.error));
-	return result.data;
+function routeUrl(siteUrl, routePrefix, routePath) {
+	const base = trimTrailingSlash(siteUrl);
+	return `${base}${normalizeRoutePrefix(routePrefix)}${routePath === "/" ? "" : routePath.replace(/^\/+/, "/")}` || base;
 }
-function resolveI18nConfig(i18n) {
-	if (!i18n) return void 0;
-	const firstLocale = i18n.locales[0]?.code;
-	const defaultLocale = i18n.defaultLocale ?? firstLocale;
-	if (!defaultLocale) return void 0;
-	return {
-		defaultLocale,
-		missing: i18n.missing ?? "fallback",
-		locales: i18n.locales
-	};
+function escapeXml(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
 }
-function resolveRoutePrefix(routePrefix) {
-	const trimmed = routePrefix?.trim();
-	if (!trimmed || trimmed === "/") return "/";
-	return `/${trimmed.replace(/^\/+|\/+$/g, "")}/`;
+function publicRoutes(routes) {
+	return routes.filter((route) => route.path !== "/404" && !route.isBareAlias);
 }
-function resolveAssetPrefix(assetPrefix, routePrefix) {
-	const trimmed = assetPrefix?.trim();
-	if (trimmed === void 0) return routePrefix;
-	if (trimmed === "./" || trimmed === "") return trimmed || "/";
-	if (!trimmed || trimmed === "/") return "/";
-	if (/^[a-z][a-z\d+.-]*:\/\//i.test(trimmed)) return trimmed.endsWith("/") ? trimmed : `${trimmed}/`;
-	if (trimmed.startsWith("./") || trimmed.startsWith("../")) return trimmed.endsWith("/") ? trimmed : `${trimmed}/`;
-	return `/${trimmed.replace(/^\/+|\/+$/g, "")}/`;
+function createSitemapXml(routes, config) {
+	if (!config.siteUrl) return void 0;
+	return [
+		"<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
+		"<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">",
+		...publicRoutes(routes).map((route) => routeUrl(config.siteUrl, config.routePrefix, route.path)).filter((url, index, list) => list.indexOf(url) === index).sort().map((url) => `  <url><loc>${escapeXml(url)}</loc></url>`),
+		"</urlset>",
+		""
+	].join("\n");
 }
-function resolveProjectConfig(config = {}) {
-	const routePrefix = resolveRoutePrefix(config.routePrefix);
+function createRobotsTxt(config) {
+	if (!config.siteUrl) return void 0;
+	return [
+		"User-agent: *",
+		"Allow: /",
+		`Sitemap: ${routeUrl(config.siteUrl, config.routePrefix, "/sitemap.xml")}`,
+		""
+	].join("\n");
+}
+//#endregion
+//#region source/plugins/seo/index.ts
+function createSeoPlugin() {
 	return {
-		title: config.title ?? "Clarify Docs",
-		description: config.description ?? "",
-		siteUrl: config.siteUrl,
-		source: config.source,
-		logo: config.logo,
-		homeUrl: config.homeUrl,
-		favicon: config.favicon,
-		routePrefix,
-		assetPrefix: resolveAssetPrefix(config.assetPrefix, routePrefix),
-		theme: resolveThemeConfig(config.theme),
-		navbar: config.navbar,
-		banner: config.banner,
-		footer: config.footer,
-		variables: config.variables ?? {},
-		i18n: resolveI18nConfig(config.i18n),
-		tabs: config.tabs
+		name: "clarify:seo",
+		hooks: { "build:assets"(ctx) {
+			const sitemap = createSitemapXml(ctx.routes, ctx.projectConfig);
+			const robots = createRobotsTxt(ctx.projectConfig);
+			if (!sitemap || !robots) return [];
+			return [{
+				fileName: "sitemap.xml",
+				source: sitemap
+			}, {
+				fileName: "robots.txt",
+				source: robots
+			}];
+		} }
 	};
 }
-/** Serialize a ContentRoute into the minimal shape exposed to tooling. */
-function toDevRouteEntry(route) {
+//#endregion
+//#region source/plugins/source-links/source-links.ts
+function trimSlashes(value) {
+	return value.replace(/^\/+|\/+$/g, "");
+}
+function normalizeRepositoryUrl(repository) {
+	return repository.replace(/\.git$/, "").replace(/\/+$/, "");
+}
+function encodePath(path) {
+	return path.split("/").filter(Boolean).map((segment) => encodeURIComponent(segment)).join("/");
+}
+function createSourceUrl(filePath, contentRoot, source) {
+	const repository = normalizeRepositoryUrl(source.repository);
+	const branch = source.branch ?? "main";
+	const sourcePath = [source.directory ? trimSlashes(source.directory) : "", relative(contentRoot, filePath).replaceAll("\\", "/")].filter(Boolean).join("/");
+	return `${repository}/edit/${encodeURIComponent(branch)}/${encodePath(sourcePath)}`;
+}
+function attachSourceUrls(routes, contentRoot, source) {
+	if (!source) return;
+	for (const route of routes) route.sourceUrl = createSourceUrl(route.filePath, contentRoot, source);
+}
+//#endregion
+//#region source/plugins/source-links/index.ts
+function createSourceLinksPlugin() {
 	return {
-		path: route.path,
-		filePath: route.filePath,
-		locale: route.locale,
-		basePath: route.basePath,
-		kind: route.kind,
-		title: route.title
+		name: "clarify:source-links",
+		hooks: { "routes:discovered": (routes, ctx) => {
+			attachSourceUrls(routes, join(ctx.generateOptions.projectRoot, ctx.generateOptions.rootDirectory), ctx.projectConfig.source);
+			return routes;
+		} }
 	};
 }
-/**
-* Resolve a single file path to its preview route.
-*
-* Selection order:
-*  1. Routes whose `filePath` exactly matches.
-*  2. Among matches, prefer the one whose `locale` matches the file's locale
-*     directory (e.g. `source/zh-CN/x.mdx` → locale `zh-CN`).
-*  3. If no locale match, fall back to the default locale (if i18n is enabled)
-*     or the first match.
-*/
-function resolveRouteForFile(filePath, routes, defaultLocale) {
-	const matches = routes.filter((r) => r.filePath === filePath);
-	if (matches.length === 0) return void 0;
-	if (matches.length === 1) return matches[0];
-	const fileLocale = inferLocaleFromPath(filePath);
-	if (fileLocale) {
-		const localeMatch = matches.find((r) => r.locale === fileLocale);
-		if (localeMatch) return localeMatch;
+//#endregion
+//#region source/plugins/variables/index.ts
+var variablePattern = /{{\s*([A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*)\s*}}/g;
+function getVariableValue(variables, path) {
+	let current = variables;
+	for (const segment of path.split(".")) {
+		if (!current || typeof current !== "object" || Array.isArray(current)) return void 0;
+		current = current[segment];
 	}
-	if (defaultLocale) {
-		const defaultMatch = matches.find((r) => r.locale === defaultLocale);
-		if (defaultMatch) return defaultMatch;
+	return current;
+}
+function stringifyVariableValue(variables, path, stack) {
+	if (stack.includes(path)) throw new Error(`[clarify] variable "${path}" contains a circular reference: ${[...stack, path].join(" -> ")}`);
+	const value = getVariableValue(variables, path);
+	if (value === void 0 || typeof value === "object") return void 0;
+	if (typeof value !== "string") return String(value);
+	return value.replace(variablePattern, (match, nestedPath) => stringifyVariableValue(variables, nestedPath, [...stack, path]) ?? match);
+}
+function applyVariables(content, variables = {}) {
+	return content.replace(variablePattern, (match, path) => stringifyVariableValue(variables, path, []) ?? match);
+}
+function applyVariablesToFrontmatter(frontmatter, variables) {
+	const nextFrontmatter = { ...frontmatter };
+	for (const key of ["title", "description"]) {
+		if (typeof nextFrontmatter[key] !== "string") continue;
+		nextFrontmatter[key] = applyVariables(nextFrontmatter[key], variables);
 	}
-	return matches[0];
+	return nextFrontmatter;
 }
-/**
-* Derive a best-effort preview route for a file that is not in the route
-* manifest (e.g. a draft or newly created file). The path is computed from the
-* file's location relative to the content root, following the same convention
-* as route discovery (`source/{locale}/path/index.mdx` → `/{locale}/path`).
-*
-* Returns null when the file is outside the content root or is not a
-* recognized content file type.
-*/
-function inferRouteForFile(filePath, contentRoot, defaultLocale) {
-	const ref = relative(contentRoot, filePath);
-	if (!ref || ref.startsWith("..")) return null;
-	const isMdx = /\.mdx?$/.test(filePath);
-	const isOpenApi = /\.openapi\.(json|ya?ml)$/.test(filePath);
-	if (!isMdx && !isOpenApi) return null;
-	const segments = ref.split("/");
-	const fileLocale = inferLocaleFromPath(filePath);
-	const localeSegmentIndex = fileLocale ? segments.indexOf(fileLocale) : -1;
-	const basePath = basePathFromRef(localeSegmentIndex >= 0 ? segments.slice(localeSegmentIndex + 1).join("/") : ref);
-	const path = fileLocale && defaultLocale ? localizedRoutePath(basePath, fileLocale, {
-		defaultLocale,
-		missing: "fallback",
-		locales: []
-	}) : basePath;
-	const title = segments[segments.length - 1]?.replace(/\.(mdx?|openapi\.(json|ya?ml))$/, "") || "Untitled";
+function createVariablesPlugin() {
 	return {
-		path: normalizePath(path),
-		filePath,
-		locale: fileLocale,
-		basePath: normalizePath(basePath),
-		kind: isMdx ? "mdx" : "openapi",
-		title,
-		inferred: true
+		name: "clarify:variables",
+		hooks: { "content:transform": (input, ctx) => ({
+			...input,
+			frontmatter: applyVariablesToFrontmatter(input.frontmatter, ctx.projectConfig.variables),
+			content: applyVariables(input.content, ctx.projectConfig.variables)
+		}) }
 	};
 }
-/** Best-effort locale inference from a file path segment like `.../zh-CN/x.mdx`. */
-function inferLocaleFromPath(filePath) {
-	const segments = filePath.split("/");
-	for (const segment of segments) if (/^[a-z]{2,3}(-[A-Z][a-z]{3})?(-[A-Z]{2})?$/.test(segment)) return segment;
-}
-/** Read and parse the JSON body of an IncomingMessage. */
-function readJsonBody(req) {
-	return new Promise((resolveBody, reject) => {
-		const chunks = [];
-		req.on("data", (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
-		req.on("error", reject);
-		req.on("end", () => {
-			const raw = Buffer.concat(chunks).toString("utf-8").trim();
-			if (!raw) return resolveBody({});
-			try {
-				resolveBody(JSON.parse(raw));
-			} catch (err) {
-				reject(err);
-			}
-		});
-	});
+//#endregion
+//#region source/core/plugin/builtin.ts
+function createBuiltinPlugins(options = {}) {
+	const plugins = [
+		createVariablesPlugin(),
+		createOpenAPIPlugin(),
+		createSourceLinksPlugin(),
+		createContentArtifactsPlugin(),
+		createSeoPlugin(),
+		createSearchIndexPlugin()
+	];
+	if (options.htmlShell ?? true) plugins.push(createHtmlShellPlugin());
+	return plugins;
 }
-/**
-* Handle a request to the dev route endpoint. Pure function — does not touch
-* the network directly, only reads the request body and writes to `res`.
-*/
-async function handleDevRouteRequest(req, res, routes, projectConfig, contentRoot) {
-	res.setHeader("Content-Type", "application/json; charset=utf-8");
-	let body;
-	try {
-		body = await readJsonBody(req);
-	} catch {
-		res.statusCode = 400;
-		res.end(JSON.stringify({ error: "Invalid JSON body" }));
-		return;
+//#endregion
+//#region source/core/plugin/manager.ts
+function pluginWeight(plugin) {
+	return (plugin.enforce === "pre" ? 1e6 : plugin.enforce === "post" ? -1e6 : 0) + (plugin.priority ?? 0);
+}
+function sortPlugins(plugins) {
+	const entries = plugins.map((plugin, index) => ({
+		plugin,
+		index
+	}));
+	const byName = /* @__PURE__ */ new Map();
+	for (const { plugin } of entries) {
+		if (byName.has(plugin.name)) throw new Error(`[clarify] Duplicate plugin name: ${plugin.name}`);
+		byName.set(plugin.name, plugin);
 	}
-	const file = typeof body === "object" && body !== null ? body.file : void 0;
-	if (typeof file === "string" && file.length > 0) {
-		const route = resolveRouteForFile(file, routes, projectConfig.i18n?.defaultLocale);
-		if (route) {
-			res.end(JSON.stringify(toDevRouteEntry(route)));
-			return;
+	const sortedByWeight = [...entries].sort((left, right) => {
+		const weightDiff = pluginWeight(right.plugin) - pluginWeight(left.plugin);
+		return weightDiff === 0 ? left.index - right.index : weightDiff;
+	});
+	const visitOrder = new Map(sortedByWeight.map((entry, index) => [entry.plugin.name, index]));
+	const visiting = /* @__PURE__ */ new Set();
+	const visited = /* @__PURE__ */ new Set();
+	const sorted = [];
+	function visit(plugin) {
+		if (visited.has(plugin.name)) return;
+		if (visiting.has(plugin.name)) throw new Error(`[clarify] Circular plugin dependency detected: ${plugin.name}`);
+		visiting.add(plugin.name);
+		const dependencies = [...plugin.dependsOn ?? []].sort((left, right) => (visitOrder.get(left) ?? 0) - (visitOrder.get(right) ?? 0));
+		for (const dependencyName of dependencies) {
+			const dependency = byName.get(dependencyName);
+			if (!dependency) throw new Error(`[clarify] Plugin ${plugin.name} depends on missing plugin: ${dependencyName}`);
+			visit(dependency);
 		}
-		const inferred = inferRouteForFile(file, contentRoot, projectConfig.i18n?.defaultLocale);
-		res.end(JSON.stringify(inferred));
-		return;
+		visiting.delete(plugin.name);
+		visited.add(plugin.name);
+		sorted.push(plugin);
 	}
-	res.end(JSON.stringify(routes.map(toDevRouteEntry)));
+	for (const { plugin } of sortedByWeight) visit(plugin);
+	return sorted;
+}
+function loadPlugins(options = {}) {
+	return sortPlugins([...createBuiltinPlugins({ htmlShell: options.htmlShell }), ...options.userPlugins ?? []]);
+}
+function loadBuildPlugins(options = {}, pluginOptions = {}) {
+	return loadPlugins({
+		...pluginOptions,
+		userPlugins: options.plugins
+	});
+}
+//#endregion
+//#region source/core/project/project-context.ts
+async function resolveProjectContext(options = {}, env = {
+	command: "build",
+	mode: "production"
+}) {
+	const projectRoot = resolve(options.projectRoot ?? process.cwd());
+	const initialBuildOptions = resolveBuildOptions(options);
+	const contentRoot = join(projectRoot, initialBuildOptions.rootDirectory);
+	const configFilePath = findClarifyConfigFile(projectRoot);
+	const config = configFilePath && existsSync(configFilePath) ? await loadClarifyConfig(projectRoot, env) : {};
+	const mergedOptions = {
+		...config,
+		...options,
+		projectRoot,
+		rootDirectory: initialBuildOptions.rootDirectory,
+		outputDirectory: initialBuildOptions.outputDirectory
+	};
+	const resolvedProjectConfig = resolveProjectConfig(mergedOptions);
+	const resolvedBuildOptions = resolveBuildOptions(mergedOptions);
+	return {
+		projectRoot,
+		contentRoot,
+		configFilePath,
+		projectConfig: resolvedProjectConfig,
+		buildOptions: resolvedBuildOptions,
+		resolvedOptions: mergedOptions,
+		config,
+		projectContext: {
+			projectRoot,
+			contentRoot,
+			version: cliPackageVersion,
+			projectConfig: resolvedProjectConfig,
+			generateOptions: resolvedBuildOptions
+		}
+	};
 }
 //#endregion
-//#region source/core/env-types.ts
+//#region source/core/runtime/env-types.ts
 var GENERATED_FILE_NAME = "clarify-env.d.ts";
 /**
 * Template for the generated `clarify-env.d.ts` file.
@@ -1911,18 +2479,6 @@ declare module 'virtual:clarify/slot' {
 
   export function useSlot(): SlotContext
 }
-
-declare module 'virtual:clarify/slots' {
-  import type { ComponentType } from 'react'
-
-  export type RuntimeSlotEntry = {
-    plugin: string
-    /** Lazy import factory — yields the default-exported React component. */
-    component: () => Promise<{ default: ComponentType }>
-  }
-
-  export const runtimeSlots: Record<string, RuntimeSlotEntry[]>
-}
 `;
 function generateClarifyEnvDts(_plugins) {
 	return CLARIFY_ENV_TEMPLATE;
@@ -1943,191 +2499,79 @@ function writeClarifyEnvDts(projectRoot, plugins) {
 	writeFileSync(filePath, next, "utf-8");
 }
 //#endregion
-//#region source/core/options.ts
-function resolveBuildOptions(options = {}) {
-	return {
-		projectRoot: options.projectRoot ?? process.cwd(),
-		rootDirectory: options.rootDirectory ?? "source",
-		outputDirectory: options.outputDirectory,
-		ssg: { failOnError: options.ssg?.failOnError ?? true }
-	};
-}
-//#endregion
-//#region source/core/user-config.ts
-function defineConfig(config) {
-	validateProjectConfig(config);
-	return config;
-}
+//#region source/core/runtime/html-template.ts
 /**
-* Config filenames Clarify CLI looks for at the project root, in resolution
-* order. Exported so other modules (e.g. the dev `project-info` endpoint) can
-* surface the same list to tooling without duplicating it.
+* HTML template manipulation helpers used during SSG.
+*
+* The SSG renderer needs to mutate the built `index.html` per route
+* (title, description/keywords meta, canonical link, `<html lang/dir>`,
+* and the root `<div>` content). These operations are all string-based
+* because the template is a raw HTML string, not a parsed DOM. Keeping them
+* in one module centralizes every HTML-mutation regex so they can be audited
+* together and so `ssg.ts` stays focused on the render pipeline.
 */
-var CONFIG_FILENAMES = [
-	"clarify.ts",
-	"clarify.js",
-	"clarify.json"
-];
-function findClarifyConfigFile(root) {
-	for (const filename of CONFIG_FILENAMES) {
-		const filePath = resolve(root, filename);
-		if (existsSync(filePath)) return filePath;
-	}
-}
-function assertConfigObject(config, configFile) {
-	if (!config || typeof config !== "object" || Array.isArray(config)) throw new Error(`[clarify] ${configFile} must export a configuration object`);
-	return config;
+function resolveProjectConfigFromContext(contextOrConfig) {
+	return "projectConfig" in contextOrConfig ? contextOrConfig.projectConfig : contextOrConfig;
 }
-function loadJsonConfig(configFile) {
-	const config = assertConfigObject(JSON.parse(readFileSync(configFile, "utf-8")), configFile);
-	const projectConfig = validateProjectConfig(config);
-	const ssg = config.ssg && typeof config.ssg === "object" && !Array.isArray(config.ssg) ? config.ssg : void 0;
-	return {
-		...projectConfig,
-		...ssg ? { ssg } : {}
-	};
+function routeTitle(contextOrConfig, route) {
+	const projectConfig = resolveProjectConfigFromContext(contextOrConfig);
+	const title = route?.title?.trim();
+	if (!title || title === projectConfig.title) return projectConfig.title;
+	return `${title} - ${projectConfig.title}`;
 }
-async function loadClarifyConfig(root, env) {
-	const configFile = findClarifyConfigFile(root);
-	if (!configFile) return {};
-	if (configFile.endsWith(".json")) return loadJsonConfig(configFile);
-	return assertConfigObject((await loadConfigFromFile(env, configFile, root, "silent"))?.config, configFile);
+function canonicalUrl(contextOrConfig, route) {
+	const projectConfig = resolveProjectConfigFromContext(contextOrConfig);
+	if (!projectConfig.siteUrl || !route.alternates || !route.locale) return void 0;
+	const prefixedPath = route.alternates[route.locale];
+	if (!prefixedPath || prefixedPath === route.path) return void 0;
+	return `${projectConfig.siteUrl.replace(/\/+$/, "")}${!projectConfig.routePrefix || projectConfig.routePrefix === "/" ? "" : `/${projectConfig.routePrefix.replace(/^\/+|\/+$/g, "")}`}${prefixedPath}`;
 }
-/**
-* File extensions Clarify treats as content files. Kept in sync with the
-* patterns used by route discovery in `parsers/routes.ts` and the OpenAPI
-* page generator. Exposed to tooling so the extension's "is this a content
-* file?" check stays accurate without duplicating the regex.
-*/
-var CONTENT_FILE_EXTENSIONS = [
-	".md",
-	".mdx",
-	".openapi.json",
-	".openapi.yaml",
-	".openapi.yml"
-];
-/**
-* Build the project-info response payload from the resolved plugin state.
-*/
-function buildProjectInfo(projectRoot, contentRoot, projectConfig) {
-	const response = {
-		configFilenames: CONFIG_FILENAMES,
-		contentFileExtensions: CONTENT_FILE_EXTENSIONS,
-		contentRoot: (contentRoot.startsWith(projectRoot) ? contentRoot.slice(projectRoot.length).replace(/^[/\\]+/, "") : contentRoot) || "source",
-		projectRoot
-	};
-	if (projectConfig.i18n) response.i18n = {
-		defaultLocale: projectConfig.i18n.defaultLocale,
-		locales: projectConfig.i18n.locales.map((l) => l.code)
-	};
-	return response;
+/** Inject `lang` (and optional `dir`) onto the `<html>` tag for the route locale. */
+function injectHtmlLocaleAttributes(html, contextOrConfig, route) {
+	const projectConfig = resolveProjectConfigFromContext(contextOrConfig);
+	const localeCode = route?.locale ?? projectConfig.i18n?.defaultLocale;
+	if (!localeCode) return html;
+	const dir = (projectConfig.i18n?.locales.find((locale) => locale.code === localeCode))?.dir;
+	return html.replace(/<html\b([^>]*)>/i, (_match, attributes) => {
+		let nextAttributes = attributes.replace(/\s+lang=("[^"]*"|'[^']*'|[^\s>]*)/i, "").replace(/\s+dir=("[^"]*"|'[^']*'|[^\s>]*)/i, "");
+		nextAttributes = `${nextAttributes} lang="${escapeHtml(localeCode)}"`;
+		if (dir) nextAttributes = `${nextAttributes} dir="${escapeHtml(dir)}"`;
+		return `<html${nextAttributes}>`;
+	});
+}
+/** Set, replace, or remove a `<meta name="...">` tag in `<head>`. */
+function setNamedMeta(html, name, content) {
+	const metaPattern = new RegExp(`<meta\\b(?=[^>]*\\bname=["']${name}["'])[^>]*>\\n?`, "i");
+	if (!content) return html.replace(metaPattern, "");
+	const meta = `<meta name="${name}" content="${escapeHtml(content)}" />`;
+	if (metaPattern.test(html)) return html.replace(metaPattern, meta);
+	return html.replace("</head>", `  ${meta}\n  </head>`);
+}
+/** Remove any existing canonical link and (if a URL is resolved) inject a fresh one. */
+function injectCanonicalUrl(html, contextOrConfig, route) {
+	const url = route ? canonicalUrl(contextOrConfig, route) : void 0;
+	html = html.replace(/<link\b[^>]*\brel=["']canonical["'][^>]*\/?>\n?/gi, "");
+	if (!url) return html;
+	return html.replace("</head>", `  <link rel="canonical" href="${escapeHtml(url)}" />\n  </head>`);
 }
 /**
-* Handle a request to the project-info endpoint. Responds to any method
-* (GET is typical) with the JSON payload — there is no request body to parse.
+* Render the SSR result into the built HTML template: set `<title>`, the
+* description/keywords meta, the canonical link, the `<html lang/dir>`, and
+* replace the `#root` content with the rendered app HTML.
 */
-function handleProjectInfoRequest(_req, res, projectRoot, contentRoot, projectConfig) {
-	res.setHeader("Content-Type", "application/json; charset=utf-8");
-	res.end(JSON.stringify(buildProjectInfo(projectRoot, contentRoot, projectConfig)));
-}
-//#endregion
-//#region source/core/site.ts
-async function discoverRoutesForRoot(routeRoot, locale, plugins, ctx) {
-	return (await runHooks(plugins, "routes:discover", {
-		contentRoot: routeRoot,
-		locale,
-		routes: await findContentRoutes(routeRoot, routeRoot, { contentProcessor: getProjectContentProcessor(ctx) })
-	}, ctx)).routes;
-}
-async function discoverRoutes(root, contentRoot, plugins, ctx) {
-	const i18n = ctx.projectConfig.i18n;
-	if (!i18n) return discoverRoutesForRoot(contentRoot, void 0, plugins, ctx);
-	const localizedRoutes = [];
-	for (const locale of i18n.locales) {
-		const discovered = await discoverRoutesForRoot(join(contentRoot, locale.code), locale.code, plugins, ctx);
-		for (const route of discovered) {
-			const basePath = route.basePath ?? route.path;
-			localizedRoutes.push({
-				...route,
-				path: localizedRoutePath(basePath, locale.code, i18n),
-				basePath,
-				locale: locale.code,
-				virtualModuleId: virtualModuleIdFromRef(relative(contentRoot, route.filePath))
-			});
-		}
-	}
-	if (i18n.missing === "fallback") {
-		const routeByLocaleAndBase = new Map(localizedRoutes.map((route) => [`${route.locale ?? ""}:${route.basePath ?? route.path}`, route]));
-		const defaultRoutes = localizedRoutes.filter((route) => route.locale === i18n.defaultLocale);
-		for (const sourceRoute of defaultRoutes) {
-			const basePath = sourceRoute.basePath ?? sourceRoute.path;
-			for (const locale of i18n.locales) {
-				const key = `${locale.code}:${basePath}`;
-				if (routeByLocaleAndBase.has(key)) continue;
-				localizedRoutes.push({
-					...sourceRoute,
-					path: localizedRoutePath(basePath, locale.code, i18n),
-					locale: locale.code,
-					isFallback: true
-				});
-			}
-		}
-	}
-	const routesWithAlternates = localizedRoutes.map((route) => withAlternates(route, localizedRoutes, i18n));
-	const defaultLocale = i18n.defaultLocale;
-	const bareRoutes = [];
-	const seenBare = new Set(routesWithAlternates.map((r) => r.path));
-	for (const route of routesWithAlternates) {
-		if (route.locale !== defaultLocale) continue;
-		const bp = route.basePath ?? route.path;
-		if (bp === route.path || seenBare.has(bp)) continue;
-		seenBare.add(bp);
-		bareRoutes.push({
-			...route,
-			path: bp,
-			isBareAlias: true
-		});
-	}
-	return [...routesWithAlternates, ...bareRoutes];
-}
-async function resolveClarifySite(options = {}, resolveOptions = {}) {
-	const root = options.projectRoot ?? process.cwd();
-	const projectConfig = resolveProjectConfig(options);
-	const generateOptions = resolveBuildOptions(options);
-	const contentRoot = join(root, generateOptions.rootDirectory);
-	const plugins = [...createBuiltinPlugins({ htmlShell: resolveOptions.includeHtmlShellPlugin }), ...options.plugins ?? []];
-	const ctx = {
-		projectConfig,
-		generateOptions,
-		routes: [],
-		navigation: []
-	};
-	setProjectContentProcessor(ctx, createProjectContentProcessor(plugins, ctx));
-	let routes = await discoverRoutes(root, contentRoot, plugins, ctx);
-	routes = await runHooks(plugins, "routes:discovered", routes, ctx);
-	routes = applyConfiguredPageRoutePaths(routes, projectConfig.tabs, projectConfig.i18n);
-	const defaultNavigation = projectConfig.tabs ? projectConfig.i18n ? buildLocalizedNavigationFromTabsConfig(routes, projectConfig.tabs, projectConfig.i18n) ?? {} : buildNavigationFromTabsConfig(routes, projectConfig.tabs) : buildNavigation(routes);
-	const resolved = await runHooks(plugins, "routes:resolved", {
-		routes,
-		navigation: defaultNavigation
-	}, ctx);
-	routes = resolved.routes;
-	const navigation = resolved.navigation;
-	ctx.routes = routes;
-	ctx.navigation = navigation;
-	return {
-		root,
-		contentRoot,
-		projectConfig,
-		generateOptions,
-		plugins,
-		ctx,
-		routes,
-		navigation
-	};
+function injectSSRIntoTemplate(template, appHtml, contextOrConfig, route) {
+	const projectConfig = resolveProjectConfigFromContext(contextOrConfig);
+	let html = injectHtmlLocaleAttributes(template, contextOrConfig, route);
+	html = html.replace(/<title>.*?<\/title>/, `<title>${escapeHtml(routeTitle(contextOrConfig, route))}</title>`);
+	html = setNamedMeta(html, "description", route?.description ?? projectConfig.description);
+	html = setNamedMeta(html, "keywords", route?.keywords?.join(", "));
+	html = injectCanonicalUrl(html, contextOrConfig, route);
+	const dataPagefindIgnore = route?.isBareAlias ? " data-pagefind-ignore" : "";
+	html = html.replace(/<div id="root">([\s\S]*?)<\/div>/, `<div id="root"${dataPagefindIgnore}>${appHtml}</div>`);
+	return html;
 }
 //#endregion
-//#region source/core/runtime-deps.ts
+//#region source/core/runtime/runtime-deps.ts
 var requireFromCli = createRequire(import.meta.url);
 function resolveCliDependency(id) {
 	return requireFromCli.resolve(id);
@@ -2173,6 +2617,26 @@ function createClarifyRuntimeAliases() {
 			find: /^react\/jsx-runtime$/,
 			replacement: resolveCliDependency("react/jsx-runtime")
 		},
+		{
+			find: /^react-dom\/client$/,
+			replacement: resolveCliDependency("react-dom/client")
+		},
+		{
+			find: /^react-dom\/server$/,
+			replacement: resolveCliDependency("react-dom/server")
+		},
+		{
+			find: /^react-dom$/,
+			replacement: resolveCliDependency("react-dom")
+		},
+		{
+			find: /^react-router-dom$/,
+			replacement: resolveCliDependency("react-router-dom")
+		},
+		{
+			find: /^react-router$/,
+			replacement: resolveCliDependency("react-router")
+		},
 		{
 			find: /^mermaid$/,
 			replacement: resolveCliDependency("mermaid")
@@ -2188,7 +2652,7 @@ function createClarifyRuntimeAliases() {
 	];
 }
 //#endregion
-//#region source/core/ssg.ts
+//#region source/core/runtime/ssg.ts
 function readIndexHtml(outputDirectory) {
 	const indexPath = join(outputDirectory, "index.html");
 	if (!existsSync(indexPath)) return void 0;
@@ -2198,51 +2662,6 @@ function readIndexHtml(outputDirectory) {
 		return;
 	}
 }
-function injectHtmlLocaleAttributes(html, projectConfig, route) {
-	const localeCode = route?.locale ?? projectConfig.i18n?.defaultLocale;
-	if (!localeCode) return html;
-	const dir = (projectConfig.i18n?.locales.find((locale) => locale.code === localeCode))?.dir;
-	return html.replace(/<html\b([^>]*)>/i, (_match, attributes) => {
-		let nextAttributes = attributes.replace(/\s+lang=("[^"]*"|'[^']*'|[^\s>]*)/i, "").replace(/\s+dir=("[^"]*"|'[^']*'|[^\s>]*)/i, "");
-		nextAttributes = `${nextAttributes} lang="${escapeHtml(localeCode)}"`;
-		if (dir) nextAttributes = `${nextAttributes} dir="${escapeHtml(dir)}"`;
-		return `<html${nextAttributes}>`;
-	});
-}
-function routeTitle(projectConfig, route) {
-	const title = route?.title?.trim();
-	if (!title || title === projectConfig.title) return projectConfig.title;
-	return `${title} - ${projectConfig.title}`;
-}
-function setNamedMeta(html, name, content) {
-	const metaPattern = new RegExp(`<meta\\b(?=[^>]*\\bname=["']${name}["'])[^>]*>\\n?`, "i");
-	if (!content) return html.replace(metaPattern, "");
-	const meta = `<meta name="${name}" content="${escapeHtml(content)}" />`;
-	if (metaPattern.test(html)) return html.replace(metaPattern, meta);
-	return html.replace("</head>", `  ${meta}\n  </head>`);
-}
-function canonicalUrl(projectConfig, route) {
-	if (!projectConfig.siteUrl || !route.alternates || !route.locale) return void 0;
-	const prefixedPath = route.alternates[route.locale];
-	if (!prefixedPath || prefixedPath === route.path) return void 0;
-	return `${projectConfig.siteUrl.replace(/\/+$/, "")}${!projectConfig.routePrefix || projectConfig.routePrefix === "/" ? "" : `/${projectConfig.routePrefix.replace(/^\/+|\/+$/g, "")}`}${prefixedPath}`;
-}
-function injectCanonicalUrl(html, projectConfig, route) {
-	const url = route ? canonicalUrl(projectConfig, route) : void 0;
-	html = html.replace(/<link\b[^>]*\brel=["']canonical["'][^>]*\/?>\n?/gi, "");
-	if (!url) return html;
-	return html.replace("</head>", `  <link rel="canonical" href="${escapeHtml(url)}" />\n  </head>`);
-}
-function injectSSRIntoTemplate(template, appHtml, projectConfig, route) {
-	let html = injectHtmlLocaleAttributes(template, projectConfig, route);
-	html = html.replace(/<title>.*?<\/title>/, `<title>${escapeHtml(routeTitle(projectConfig, route))}</title>`);
-	html = setNamedMeta(html, "description", route?.description ?? projectConfig.description);
-	html = setNamedMeta(html, "keywords", route?.keywords?.join(", "));
-	html = injectCanonicalUrl(html, projectConfig, route);
-	const dataPagefindIgnore = route?.isBareAlias ? " data-pagefind-ignore" : "";
-	html = html.replace(/<div id="root">([\s\S]*?)<\/div>/, `<div id="root"${dataPagefindIgnore}>${appHtml}</div>`);
-	return html;
-}
 function isNotFoundRoute(route) {
 	return (route.basePath ?? route.path) === "/404";
 }
@@ -2290,12 +2709,12 @@ async function buildSSRBundle(root, ssrEntry, ssrOutDir, plugins) {
 		}
 	});
 }
-async function renderSSGRoutes(routes, projectConfig, outputDirectory, ssrBundlePath, failOnError = true) {
+async function renderSSGRoutes(routes, contextOrConfig, outputDirectory, ssrBundlePath, failOnError = true) {
 	const { render } = await import(pathToFileURL(ssrBundlePath).href);
 	const template = readIndexHtml(outputDirectory);
 	if (!template) throw new Error(`[clarify] index.html not found in outputDirectory "${outputDirectory}". Make sure Vite build produces it.`);
 	for (const route of routes) try {
-		const finalHtml = injectSSRIntoTemplate(template, await render(route.path), projectConfig, route);
+		const finalHtml = injectSSRIntoTemplate(template, await render(route.path), contextOrConfig, route);
 		for (const outFile of routeOutputFiles(outputDirectory, route)) {
 			mkdirSync(dirname(outFile), { recursive: true });
 			writeFileSync(outFile, finalHtml, "utf-8");
@@ -2306,239 +2725,419 @@ async function renderSSGRoutes(routes, projectConfig, outputDirectory, ssrBundle
 	}
 }
 //#endregion
-//#region source/core/plugin.ts
+//#region source/core/runtime/startup.ts
+function contentDirectoryLabel(projectRoot, contentRoot) {
+	const relativePath = relative(projectRoot, contentRoot);
+	return relativePath && relativePath !== "." ? relativePath : "source";
+}
+function contentFileExampleLabel(projectRoot, contentRoot) {
+	return `${contentDirectoryLabel(projectRoot, contentRoot)}/index.mdx`;
+}
+function getStartupHints(options) {
+	const hints = [];
+	if (!options.contentDirExists) {
+		const label = contentDirectoryLabel(options.projectRoot, options.contentRoot);
+		hints.push(`Content directory "${label}" was not found. Create it or pass --content <dir> to point Clarify at a different directory.`);
+	} else if (!options.hasRoutes) {
+		const example = contentFileExampleLabel(options.projectRoot, options.contentRoot);
+		hints.push(`No content pages were found yet. Add ${example} to get started.`);
+	}
+	return hints;
+}
+function logStartupHints(options) {
+	const hints = getStartupHints(options);
+	if (hints.length === 0) return;
+	const message = hints.map((hint) => `[clarify] ${hint}`).join("\n");
+	console.warn(message);
+}
+//#endregion
+//#region source/core/engine/context.ts
+var ClarifyContext = class {
+	projectRoot;
+	contentRoot;
+	projectConfig;
+	generateOptions;
+	version;
+	values = /* @__PURE__ */ new Map();
+	routeListeners = /* @__PURE__ */ new Set();
+	navigationListeners = /* @__PURE__ */ new Set();
+	currentRoutes;
+	currentNavigation;
+	currentPlugins;
+	constructor(init) {
+		this.projectRoot = init.projectRoot;
+		this.contentRoot = init.contentRoot;
+		this.projectConfig = init.projectConfig;
+		this.generateOptions = init.generateOptions;
+		this.version = init.version;
+		this.currentRoutes = init.routes ?? [];
+		this.currentNavigation = init.navigation ?? [];
+		this.currentPlugins = init.plugins ?? [];
+	}
+	get routes() {
+		return this.currentRoutes;
+	}
+	set routes(routes) {
+		this.currentRoutes = routes;
+		this.notify(this.routeListeners);
+	}
+	get navigation() {
+		return this.currentNavigation;
+	}
+	set navigation(navigation) {
+		this.currentNavigation = navigation;
+		this.notify(this.navigationListeners);
+	}
+	get plugins() {
+		return this.currentPlugins;
+	}
+	set plugins(plugins) {
+		this.currentPlugins = plugins;
+	}
+	get isI18n() {
+		return Boolean(this.projectConfig.i18n);
+	}
+	get defaultLocale() {
+		return this.projectConfig.i18n?.defaultLocale;
+	}
+	get(key) {
+		return this.values.get(key);
+	}
+	set(key, value) {
+		this.values.set(key, value);
+	}
+	has(key) {
+		return this.values.has(key);
+	}
+	delete(key) {
+		return this.values.delete(key);
+	}
+	onRoutesChange(listener) {
+		this.routeListeners.add(listener);
+		return () => this.routeListeners.delete(listener);
+	}
+	onNavigationChange(listener) {
+		this.navigationListeners.add(listener);
+		return () => this.navigationListeners.delete(listener);
+	}
+	updateProjectState(update) {
+		if (update.projectRoot !== void 0) this.projectRoot = update.projectRoot;
+		if (update.contentRoot !== void 0) this.contentRoot = update.contentRoot;
+		if (update.projectConfig !== void 0) this.projectConfig = update.projectConfig;
+		if (update.generateOptions !== void 0) this.generateOptions = update.generateOptions;
+		if (update.version !== void 0) this.version = update.version;
+	}
+	notify(listeners) {
+		for (const listener of listeners) listener();
+	}
+};
+//#endregion
+//#region source/core/engine/phases.ts
+async function runTapHooks(plugins, hookName, ctx) {
+	for (const plugin of plugins) {
+		const hook = plugin.hooks?.[hookName];
+		if (!hook) continue;
+		try {
+			await hook(ctx);
+		} catch (err) {
+			throw new Error(`[clarify] plugin "${plugin.name}" hook "${hookName}" failed: ${err}`, { cause: err });
+		}
+	}
+}
+async function runInterceptHooks(plugins, hookName, ctx) {
+	for (const plugin of plugins) {
+		const hook = plugin.hooks?.[hookName];
+		if (!hook) continue;
+		try {
+			if (await hook(ctx) === false) return false;
+		} catch (err) {
+			throw new Error(`[clarify] plugin "${plugin.name}" hook "${hookName}" failed: ${err}`, { cause: err });
+		}
+	}
+	return true;
+}
+async function runPhase(plugins, phase, ctx, task) {
+	await runTapHooks(plugins, `before:${phase}`, ctx);
+	const result = await task();
+	await runTapHooks(plugins, `after:${phase}`, ctx);
+	return result;
+}
+//#endregion
+//#region source/core/engine/engine.ts
 function loadVirtualModule(id, modules) {
 	const bareId = stripVirtualPrefix(id);
 	return modules.get(bareId) ?? modules.get(id) ?? null;
 }
-function clarifyPlugin(options = {}) {
-	const root = resolve(options.projectRoot ?? process.cwd());
-	let projectConfig = resolveProjectConfig(options);
-	let generateOptions = resolveBuildOptions(options);
-	const contentRoot = join(root, generateOptions.rootDirectory);
-	const configFilePath = findClarifyConfigFile(root);
-	let routes = [];
-	let clarifyPlugins = [...createBuiltinPlugins(), ...options.plugins ?? []];
-	const ctx = {
-		projectConfig,
-		generateOptions,
-		routes,
-		navigation: []
+var ClarifyEngine = class {
+	options;
+	root;
+	configFilePath;
+	ctx;
+	runtime = {
+		command: "build",
+		mode: "production"
 	};
-	let viteConfig;
-	let resolvedNavigation = [];
-	let virtualModules = /* @__PURE__ */ new Map();
-	async function resolveRoutesAndSpecs(overrides) {
-		const site = await resolveClarifySite(overrides ?? options);
-		projectConfig = site.projectConfig;
-		generateOptions = site.generateOptions;
-		routes = site.routes;
-		resolvedNavigation = site.navigation;
-		clarifyPlugins = site.plugins;
-		ctx.projectConfig = projectConfig;
-		ctx.generateOptions = generateOptions;
-		ctx.routes = routes;
-		ctx.navigation = resolvedNavigation;
-	}
-	async function rebuildVirtualModules() {
-		virtualModules = buildVirtualModules({
-			projectConfig,
-			generateOptions,
-			routes,
-			navigation: resolvedNavigation,
-			plugins: clarifyPlugins,
-			themeEditor: viteConfig.command === "serve" || projectConfig.theme.editor
+	virtualModules = /* @__PURE__ */ new Map();
+	buildEnabled = true;
+	initializedOptions;
+	constructor(options = {}) {
+		this.options = options;
+		this.root = resolve(options.projectRoot ?? process.cwd());
+		this.configFilePath = findClarifyConfigFile(this.root) ?? void 0;
+		const placeholderConfig = resolveProjectConfig({});
+		const placeholderOptions = resolveBuildOptions(options);
+		this.ctx = new ClarifyContext({
+			projectRoot: this.root,
+			contentRoot: join(this.root, placeholderOptions.rootDirectory),
+			projectConfig: placeholderConfig,
+			generateOptions: placeholderOptions,
+			version: cliPackageVersion,
+			routes: [],
+			navigation: [],
+			plugins: []
 		});
-		virtualModules = await runHooks(clarifyPlugins, "modules:before", virtualModules, ctx);
 	}
-	function invalidateVirtualModules(server) {
-		for (const id of virtualModules.keys()) {
-			const moduleNode = server.moduleGraph.getModuleById(resolveVirtualId(id));
-			if (moduleNode) server.moduleGraph.invalidateModule(moduleNode);
-		}
+	configureRuntime(runtime) {
+		this.runtime = {
+			...this.runtime,
+			...runtime
+		};
 	}
-	async function refreshDevServer(server) {
-		await resolveRoutesAndSpecs();
-		await rebuildVirtualModules();
-		invalidateVirtualModules(server);
-		server.ws.send({ type: "full-reload" });
+	async initialize(env = {
+		command: this.runtime.command,
+		mode: this.runtime.mode
+	}, options = this.options, prepareOptions = {}) {
+		if (this.initializedOptions && !prepareOptions.force) return this.initializedOptions;
+		const seedPlugins = loadBuildPlugins(options, { htmlShell: prepareOptions.htmlShell });
+		this.ctx.plugins = seedPlugins;
+		const context = await runPhase(seedPlugins, "config:load", this.ctx, () => resolveProjectContext(options, env));
+		this.configFilePath = context.configFilePath;
+		this.ctx.updateProjectState({
+			projectRoot: context.projectRoot,
+			contentRoot: context.contentRoot,
+			projectConfig: context.projectConfig,
+			generateOptions: context.buildOptions,
+			version: context.projectContext.version
+		});
+		await runPhase(seedPlugins, "config:resolve", this.ctx, () => void 0);
+		const finalPlugins = loadBuildPlugins(context.resolvedOptions, { htmlShell: prepareOptions.htmlShell });
+		this.ctx.plugins = finalPlugins;
+		await runPhase(finalPlugins, "plugins:load", this.ctx, () => void 0);
+		this.initializedOptions = context.resolvedOptions;
+		return context.resolvedOptions;
 	}
-	function hasContentRouteForFile(filePath) {
-		return routes.some((route) => route.filePath === filePath);
+	/**
+	* Runs the full pre-build/pre-dev preparation: initialize (config load +
+	* resolve + plugins:load), site discovery (routes + navigation), and module
+	* building. This is the single entry point that prepares the engine before
+	* handing it to a Vite adapter or running a check, so callers never need to
+	* call initialize/discoverSite separately.
+	*
+	* Options:
+	* - `force`: re-run even if already prepared (config-file hot reload).
+	* - `htmlShell`: toggle the HTML shell builtin plugin (default true).
+	* - `skipModules`: skip `buildModules()` (check command).
+	* - `skipHints`: skip `logStartupHints()` (check command).
+	*
+	* Idempotent: calling prepare() again with the same env is a no-op unless
+	* `force` is set.
+	*/
+	async prepare(env = {
+		command: this.runtime.command,
+		mode: this.runtime.mode
+	}, options = this.options, prepareOptions = {}) {
+		this.configureRuntime({
+			command: env.command,
+			mode: env.mode
+		});
+		const resolvedOptions = await this.initialize(env, options, prepareOptions);
+		await this.discoverSite();
+		if (!prepareOptions.skipModules) await this.buildModules();
+		if (!prepareOptions.skipHints) this.logStartupHints();
+		return resolvedOptions;
 	}
-	const normalizedMdxContentPlugin = {
-		name: "clarify:normalized-mdx-content",
-		enforce: "pre",
-		transform(_code, id) {
-			if (!/\.mdx?(?:\?|$)/.test(id)) return null;
-			const filePath = id.replace(/\?.*$/, "");
-			const route = routes.find((route) => route.kind === "mdx" && route.filePath === filePath);
-			if (!route || route.content === void 0) return null;
-			return {
-				code: route.content,
-				map: null
-			};
-		}
-	};
-	const mdx = mdxPlugin({
-		include: ["**/*.{md,mdx}"],
-		jsxImportSource: "react",
-		providerImportSource: "@clarify-labs/renderer",
-		remarkPlugins,
-		rehypePlugins
-	});
-	return [
-		react(),
-		tailwindcss(),
-		normalizedMdxContentPlugin,
-		{
-			name: "clarify:core",
-			async config() {
-				await resolveRoutesAndSpecs();
+	get projectConfig() {
+		return this.ctx.projectConfig;
+	}
+	get generateOptions() {
+		return this.ctx.generateOptions;
+	}
+	get contentRoot() {
+		return this.ctx.contentRoot;
+	}
+	get routes() {
+		return this.ctx.routes;
+	}
+	get navigation() {
+		return this.ctx.navigation;
+	}
+	get plugins() {
+		return this.ctx.plugins;
+	}
+	get modules() {
+		return this.virtualModules;
+	}
+	loadModule(id) {
+		return loadVirtualModule(id, this.virtualModules);
+	}
+	async discoverSite() {
+		const plugins = this.ctx.plugins;
+		const contentRoot = this.ctx.contentRoot;
+		const { i18n, tabs } = this.ctx.projectConfig;
+		let routes = await runPhase(plugins, "site:discover", this.ctx, async () => {
+			const options = { contentProcessor: createProjectContentProcessor(plugins, this.ctx) };
+			const discovered = i18n ? await findLocalizedContentRoutes(contentRoot, i18n, options) : await findContentRoutes(contentRoot, contentRoot, options);
+			const result = await runHooks(plugins, "routes:discover", {
+				contentRoot,
+				routes: discovered
+			}, this.ctx);
+			return runHooks(plugins, "routes:discovered", result.routes, this.ctx);
+		});
+		routes = await runPhase(plugins, "content:process", this.ctx, async () => {
+			const pages = routes.map((route) => ({
+				path: route.path,
+				filePath: route.filePath,
+				frontmatter: route.frontmatter ?? {},
+				content: route.content ?? ""
+			}));
+			const resolvedPages = await runHooks(plugins, "pages:resolved", pages, this.ctx);
+			const pageByPath = new Map(resolvedPages.map((p) => [p.path, p]));
+			return routes.map((route) => {
+				const page = pageByPath.get(route.path);
+				if (!page) return route;
 				return {
-					base: projectConfig.assetPrefix,
-					build: {
-						...generateOptions.outputDirectory ? { outDir: generateOptions.outputDirectory } : {},
-						manifest: true
-					}
-				};
-			},
-			configResolved(config) {
-				viteConfig = config;
-				if (!generateOptions.outputDirectory) generateOptions.outputDirectory = config.build.outDir;
-			},
-			async buildStart() {
-				await rebuildVirtualModules();
-				writeClarifyEnvDts(root, clarifyPlugins);
-			},
-			async handleHotUpdate(ctx) {
-				const changedFile = isAbsolute(ctx.file) ? ctx.file : join(root, ctx.file);
-				if (configFilePath && changedFile === configFilePath) {
-					await resolveRoutesAndSpecs({
-						...await loadClarifyConfig(root, {
-							command: "serve",
-							mode: viteConfig.mode
-						}),
-						projectRoot: options.projectRoot,
-						rootDirectory: options.rootDirectory,
-						outputDirectory: options.outputDirectory
-					});
-					await rebuildVirtualModules();
-					invalidateVirtualModules(ctx.server);
-					ctx.server.ws.send({ type: "full-reload" });
-					return [];
-				}
-				const relativeContentFile = relative(contentRoot, changedFile);
-				if (!(relativeContentFile && !relativeContentFile.startsWith("..") && !isAbsolute(relativeContentFile)) || !hasContentRouteForFile(changedFile)) return;
-				await refreshDevServer(ctx.server);
-				return [];
-			},
-			resolveId(id) {
-				if (id === "virtual:clarify/entry-client" || id === "\0virtual:clarify/entry-client") return RESOLVED_CLIENT_ENTRY;
-				if (id === "virtual:clarify/config" || id === resolveVirtualId("virtual:clarify/config")) return resolveVirtualId(VIRTUAL_CONFIG);
-				if (id === "virtual:clarify/routes" || id === resolveVirtualId("virtual:clarify/routes")) return resolveVirtualId(VIRTUAL_ROUTES);
-				if (id === "virtual:clarify/routes/server" || id === resolveVirtualId("virtual:clarify/routes/server")) return resolveVirtualId(VIRTUAL_SERVER_ROUTES);
-				if (id === "virtual:clarify/openapi" || id === resolveVirtualId("virtual:clarify/openapi")) return resolveVirtualId(VIRTUAL_OPENAPI);
-				if (id === "virtual:clarify/slots" || id === resolveVirtualId("virtual:clarify/slots")) return resolveVirtualId(VIRTUAL_SLOTS);
-				if (id === "virtual:clarify/slot" || id === resolveVirtualId("virtual:clarify/slot")) return resolveVirtualId(VIRTUAL_SLOT);
-				const moduleId = stripVirtualPrefix(id);
-				if (virtualModules.has(moduleId)) return resolveVirtualId(moduleId);
-				const route = routes.find((r) => r.virtualModuleId === id || r.virtualModuleId === moduleId);
-				if (route) return resolveVirtualId(route.virtualModuleId);
-				return null;
-			},
-			load(id) {
-				return loadVirtualModule(id, virtualModules);
-			},
-			async configureServer(server) {
-				server.watcher.add(contentRoot);
-				if (configFilePath) server.watcher.add(configFilePath);
-				server.middlewares.use((req, res, next) => {
-					if (req.url === "/dev/query-preview-route" && req.method === "POST") return handleDevRouteRequest(req, res, routes, projectConfig, contentRoot);
-					if (req.url === "/dev/project-info" && (req.method === "GET" || req.method === "HEAD")) return handleProjectInfoRequest(req, res, root, contentRoot, projectConfig);
-					next();
-				});
-				const handleContentTreeChange = async (filePath) => {
-					const relativeContentFile = relative(contentRoot, isAbsolute(filePath) ? filePath : join(root, filePath));
-					if (!(relativeContentFile && !relativeContentFile.startsWith("..") && !isAbsolute(relativeContentFile))) return;
-					await refreshDevServer(server);
+					...route,
+					frontmatter: page.frontmatter,
+					content: page.content
 				};
-				server.watcher.on("add", handleContentTreeChange);
-				server.watcher.on("unlink", handleContentTreeChange);
-				await runDevConfigureServerHooks(clarifyPlugins, server, ctx);
-			},
-			transformIndexHtml: {
-				order: "pre",
-				async handler(html, transformCtx) {
-					const clientEntryId = transformCtx.server ? `/@id/${VIRTUAL_CLIENT_ENTRY}` : VIRTUAL_CLIENT_ENTRY;
-					const result = await runHooks(clarifyPlugins, "html:transform", {
-						html,
-						tags: [],
-						clientEntryId,
-						dev: Boolean(transformCtx.server)
-					}, ctx);
-					return {
-						html: result.html,
-						tags: result.tags
-					};
-				}
-			},
-			async generateBundle(_opts, _bundle) {
-				const assets = await runBuildAssetsHooks(clarifyPlugins, ctx);
-				for (const asset of assets) this.emitFile({
-					type: "asset",
-					fileName: asset.fileName,
-					source: asset.source
+			});
+		});
+		routes = applyConfiguredPageRoutePaths(routes, tabs, i18n);
+		const navigation = tabs ? i18n ? buildLocalizedNavigationFromTabsConfig(routes, tabs, i18n) ?? {} : buildNavigationFromTabsConfig(routes, tabs) : buildNavigation(routes);
+		const resolved = await runHooks(plugins, "routes:resolved", {
+			routes,
+			navigation
+		}, this.ctx);
+		this.ctx.routes = resolved.routes;
+		this.ctx.navigation = resolved.navigation;
+	}
+	logStartupHints() {
+		logStartupHints({
+			projectRoot: this.root,
+			contentRoot: this.contentRoot,
+			contentDirExists: existsSync(this.contentRoot),
+			hasRoutes: this.routes.length > 0
+		});
+	}
+	async buildModules() {
+		await runPhase(this.plugins, "modules:build", this.ctx, async () => {
+			this.virtualModules = buildVirtualModules({
+				projectConfig: this.projectConfig,
+				generateOptions: this.generateOptions,
+				routes: this.routes,
+				navigation: this.navigation,
+				plugins: this.plugins,
+				themeEditor: this.runtime.command === "serve" || this.runtime.themeEditor === true || this.projectConfig.theme.editor,
+				version: this.ctx.version
+			});
+			this.virtualModules = await runHooks(this.plugins, "modules:before", this.virtualModules, this.ctx);
+		});
+	}
+	writeEnvTypes() {
+		writeClarifyEnvDts(this.root, this.plugins);
+	}
+	hasContentRouteForFile(filePath) {
+		return this.routes.some((route) => route.filePath === filePath);
+	}
+	async collectBuildAssets() {
+		if (!this.buildEnabled) return [];
+		return runBuildAssetsHooks(this.plugins, this.ctx);
+	}
+	async beginBuild() {
+		this.buildEnabled = await runInterceptHooks(this.plugins, "build:shouldRun", this.ctx);
+		if (!this.buildEnabled) return false;
+		await runTapHooks(this.plugins, "before:build", this.ctx);
+		return true;
+	}
+	async endBuild() {
+		if (!this.buildEnabled) return;
+		await runTapHooks(this.plugins, "after:build", this.ctx);
+	}
+	shouldRunBuild() {
+		return this.buildEnabled;
+	}
+	async configureDevServer(server) {
+		await runPhase(this.plugins, "dev:server", this.ctx, async () => {
+			await runDevConfigureServerHooks(this.plugins, server, this.ctx);
+		});
+	}
+	async runBuildDone() {
+		if (!this.buildEnabled) return;
+		await runBuildDoneHooks(this.plugins, this.ctx);
+	}
+	async runSSG() {
+		if (!this.buildEnabled) return;
+		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;
+			const outputDir = this.runtime.outputDirectory ?? this.generateOptions.outputDirectory;
+			if (!outputDir) throw new Error("[clarify] outputDirectory is required before SSG runs");
+			const ssrOutputDir = join(outputDir, ".ssr");
+			let tempEntryPath;
+			try {
+				tempEntryPath = createTempEntryFile(SSR_ENTRY_CODE);
+				await (this.runtime.buildSSRBundle ?? ((options) => buildSSRBundle(options.root, options.ssrEntry, options.ssrOutDir, options.plugins)))({
+					root: this.root,
+					ssrEntry: tempEntryPath,
+					ssrOutDir: ssrOutputDir,
+					plugins: this.runtime.ssrPlugins ?? []
 				});
-			},
-			async closeBundle() {
-				if (process.env.SKIP_CLARIFY_SSG) {
-					await runBuildDoneHooks(clarifyPlugins, ctx);
-					return;
-				}
-				const outputDir = viteConfig.build.outDir;
-				const ssrOutputDir = join(outputDir, ".ssr");
-				let tempEntryPath;
-				try {
-					tempEntryPath = createTempEntryFile(SSR_ENTRY_CODE);
-					await buildSSRBundle(root, tempEntryPath, ssrOutputDir, [
-						{
-							name: "clarify:virtual-ssg",
-							resolveId(id) {
-								if (id === "virtual:clarify/entry-client") return RESOLVED_CLIENT_ENTRY;
-								if (id === "\0virtual:clarify/entry-client") return RESOLVED_CLIENT_ENTRY;
-								if (id === "virtual:clarify/routes/server") return id;
-								if (id === "virtual:clarify/openapi") return id;
-								if (id === "virtual:clarify/config") return id;
-								if (id === "virtual:clarify/routes") return id;
-								if (id === "virtual:clarify/slots") return id;
-								if (id === "virtual:clarify/slot") return id;
-								if (virtualModules.has(stripVirtualPrefix(id))) return stripVirtualPrefix(id);
-								if (routes.find((r) => r.virtualModuleId === id)) return id;
-								return null;
-							},
-							load: (id) => loadVirtualModule(id, virtualModules)
-						},
-						normalizedMdxContentPlugin,
-						mdx
-					]);
-					const ssrBundlePath = join(ssrOutputDir, "entry-server.js");
-					await renderSSGRoutes(routes, projectConfig, outputDir, ssrBundlePath, generateOptions.ssg.failOnError);
-				} catch (err) {
-					console.error("[clarify] SSG failed:", err);
-					if (generateOptions.ssg.failOnError) throw err;
-				} finally {
-					if (tempEntryPath) try {
-						rmSync(tempEntryPath, { force: true });
-					} catch {}
-				}
-				await runBuildDoneHooks(clarifyPlugins, ctx);
+				const ssrBundlePath = join(ssrOutputDir, "entry-server.js");
+				await renderSSGRoutes(this.routes, this.runtimeContext(), outputDir, ssrBundlePath, this.generateOptions.ssg.failOnError);
+			} catch (err) {
+				console.error("[clarify] SSG failed:", err);
+				if (this.generateOptions.ssg.failOnError) throw err;
+			} finally {
+				if (tempEntryPath) try {
+					rmSync(tempEntryPath, { force: true });
+				} catch {}
 			}
-		},
-		mdx
-	].flat().filter(Boolean);
+		});
+		await this.runBuildDone();
+	}
+	async refresh() {
+		await this.discoverSite();
+		await this.buildModules();
+	}
+	/**
+	* Runs the `html:transform` pipeline hook and returns the transformed
+	* input. Adapters call this from their `transformIndexHtml` hook instead
+	* of invoking `runHooks` directly, keeping hook execution inside Engine.
+	*/
+	async transformHtml(input) {
+		return runHooks(this.plugins, "html:transform", input, this.ctx);
+	}
+	runtimeContext() {
+		return {
+			projectRoot: this.root,
+			contentRoot: this.contentRoot,
+			projectConfig: this.projectConfig,
+			generateOptions: this.generateOptions,
+			version: this.ctx.version
+		};
+	}
+	createSSGVirtualPlugin() {
+		return {
+			name: "clarify:virtual-ssg",
+			resolveId: (id) => resolveVirtualModuleId(id, this.virtualModules, this.routes),
+			load: (id) => this.loadModule(id)
+		};
+	}
+};
+function createClarifyEngine(options = {}) {
+	return new ClarifyEngine(options);
 }
 //#endregion
-export { loadClarifyConfig as a, defineConfig as i, createClarifyRuntimeAliases as n, createClarifyTempDir as o, resolveClarifySite as r, clarifyPlugin as t };
+export { cliPackageVersion as a, defineConfig as c, createClarifyTempDir as i, createClarifyEngine as n, cliPackageVersionWithCaret as o, createClarifyRuntimeAliases as r, createViteAdapter as s, ClarifyEngine as t };
 
-//# sourceMappingURL=plugin-poS3N83A.js.map
+//# sourceMappingURL=engine-3f5Tpa-6.js.map