@clarify-labs/cli 0.6.4 → 0.6.5

package/output/{plugin-DChFdTyI.js → plugin-BgE7WVoS.js}

@@ -8,10 +8,11 @@ import { toString } from "mdast-util-to-string";
 import shiki from "shiki";
 import { visit } from "unist-util-visit";
 import { markdownRemarkPlugins } from "@clarify-labs/renderer";
+import { z } from "zod";
 import { remark } from "remark";
 import matter from "gray-matter";
 import SwaggerParser from "@apidevtools/swagger-parser";
-import { z } from "zod";
+import { mkdir, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { pathToFileURL } from "node:url";
 import { build, loadConfigFromFile } from "vite";
@@ -100,65 +101,520 @@ var rehypePlugins = [
 	rehypeShiki
 ];
 //#endregion
-//#region source/parsers/frontmatter.ts
-/**
-* 在内容入口统一解析 MDX frontmatter，并返回可供后续流程复用的标准化正文。
-*/
-function parseFrontmatter(content) {
-	const parsed = matter(content);
+//#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"]
+	});
+});
+var clarifyNavbarLinkSchema = z.object({
+	label: clarifyLocalizedTextSchema,
+	href: z.string(),
+	external: z.boolean().optional()
+});
+var clarifyBannerConfigSchema = z.object({
+	content: clarifyLocalizedTextSchema,
+	dismissible: z.boolean().optional()
+});
+var clarifyFooterConfigSchema = z.object({
+	links: z.array(clarifyNavbarLinkSchema).optional(),
+	socials: z.record(z.string(), z.string()).optional(),
+	copyright: clarifyLocalizedTextSchema.optional()
+});
+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(),
+		title: clarifyLocalizedTextSchema.optional(),
+		icon: z.string().optional(),
+		redirect: z.string().optional()
+	}),
+	z.object({
+		openapi: z.string(),
+		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(),
+	favicon: clarifyFaviconConfigSchema.optional(),
+	theme: clarifyThemeConfigSchema.optional(),
+	routePrefix: z.string().optional(),
+	navbar: z.object({ links: z.array(clarifyNavbarLinkSchema).optional() }).optional(),
+	banner: clarifyBannerConfigSchema.optional(),
+	footer: clarifyFooterConfigSchema.optional(),
+	i18n: clarifyI18nConfigSchema.optional(),
+	tabs: clarifyTabsConfigSchema.optional()
+});
+//#endregion
+//#region source/core/theme.ts
+var clarifyThemePresets = {
+	default: {
+		preset: "default",
+		tokens: {
+			colors: {
+				primary: "#047857",
+				accent: "#0D9488",
+				background: "#ffffff",
+				foreground: "#111827",
+				surface: "#ffffff",
+				muted: "#64748b",
+				border: "rgb(15 23 42 / 0.12)",
+				codeBackground: "#f6fbf8"
+			},
+			radius: {
+				sm: "6px",
+				md: "10px",
+				lg: "14px",
+				xl: "18px"
+			}
+		},
+		layout: { maxWidth: "82rem" },
+		editor: false
+	},
+	base: {
+		preset: "base",
+		tokens: {
+			colors: {
+				primary: "#18181b",
+				accent: "#52525b",
+				background: "#ffffff",
+				foreground: "#18181b",
+				surface: "#ffffff",
+				muted: "#71717a",
+				border: "rgb(24 24 27 / 0.12)",
+				codeBackground: "#f4f4f5"
+			},
+			radius: {
+				sm: "6px",
+				md: "8px",
+				lg: "12px",
+				xl: "16px"
+			}
+		},
+		layout: { maxWidth: "80rem" },
+		editor: false
+	}
+};
+function resolveThemeConfig(theme = {}) {
+	const preset = theme.preset ?? "default";
+	const presetTheme = clarifyThemePresets[preset];
 	return {
-		frontmatter: parsed.data,
-		content: parsed.content.replace(/^\r?\n/, "")
+		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/parsers/routes.ts
-function kebabToTitle$1(str) {
-	return str.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
-}
-function parseMdxTree(content) {
-	return remark.parse(content);
-}
-/** 从内容中提取第一个 H1 标题 */
-function extractH1(content) {
-	const tree = parseMdxTree(content);
-	let title = "";
-	visit(tree, "heading", (node) => {
-		if (!title && node.depth === 1) title = toString(node);
-	});
-	return title;
+//#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;
+	}, "");
 }
-/** 从 MDX/Markdown 内容中提取 H2/H3 章节 */
-function extractMdxSections(content) {
-	const sections = [];
-	const slugger = new GithubSlugger();
-	visit(parseMdxTree(content), "heading", (node) => {
-		if (node.depth !== 2 && node.depth !== 3) return;
-		const title = toString(node);
-		sections.push({
-			id: slugger.slug(title),
-			title,
-			level: node.depth
-		});
-	});
-	return sections;
+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 navigationSections(sections) {
-	return sections.map((s) => ({
-		id: s.id,
-		title: s.title,
-		badge: s.badge,
-		tags: s.tags
-	}));
+function validateProjectConfig(value) {
+	const result = clarifyProjectConfigSchema.safeParse(value);
+	if (!result.success) throw new Error(formatProjectConfigError(result.error));
+	return result.data;
 }
-function normalizePath(path) {
-	const clean = "/" + path.replace(/^\/+|\/+$/g, "");
-	return clean === "/" ? "/" : clean.replace(/\/+/g, "/");
+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 basePathFromRef(ref) {
+function resolveProjectConfig(config = {}) {
+	return {
+		title: config.title ?? "Clarify Docs",
+		description: config.description ?? "",
+		siteUrl: config.siteUrl,
+		source: config.source,
+		logo: config.logo,
+		favicon: config.favicon,
+		routePrefix: config.routePrefix ?? "/",
+		theme: resolveThemeConfig(config.theme),
+		navbar: config.navbar,
+		banner: config.banner,
+		footer: config.footer,
+		i18n: resolveI18nConfig(config.i18n),
+		tabs: config.tabs
+	};
+}
+//#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 /\.ya?ml$/i.test(route.contentArtifactUrl ?? "");
+}
+function routeToMarkdownArtifactUrl(routePath) {
+	return `${routePath === "/" ? "/index" : routePath.replace(/\/$/, "")}.md`;
+}
+function routeToOpenAPIArtifactUrl(routePath, filePath) {
+	const extension = extname(filePath).toLowerCase() || ".json";
+	return `${routePath === "/" ? "/index" : routePath.replace(/\/$/, "")}.openapi${extension}`;
+}
+function attachContentArtifactUrls(routes) {
+	for (const route of routes) route.contentArtifactUrl = route.kind === "openapi" ? routeToOpenAPIArtifactUrl(route.path, route.filePath) : 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 writeContentArtifactFiles(routes, outputDirectory) {
+	for (const route of routes) {
+		if (!route.contentArtifactUrl) continue;
+		const outFile = join(outputDirectory, route.contentArtifactUrl.replace(/^\//, ""));
+		mkdirSync(dirname(outFile), { recursive: true });
+		writeFileSync(outFile, readRouteArtifactContent(route), "utf-8");
+	}
+}
+function createLlmsTxt(routes, projectConfig) {
+	const basePath = normalizeBasePath(projectConfig.routePrefix);
+	const lines = [`# ${projectConfig.title}`, ""];
+	if (projectConfig.description) lines.push(`> ${projectConfig.description}`, "");
+	lines.push("## Docs");
+	for (const route of routes.filter((route) => route.kind === "mdx")) {
+		if (!route.contentArtifactUrl) continue;
+		lines.push(`- [${route.title}](${basePath}${route.contentArtifactUrl})`);
+	}
+	const openApiRoutes = routes.filter((route) => route.kind === "openapi");
+	if (openApiRoutes.length > 0) {
+		lines.push("", "## OpenAPI");
+		for (const route of openApiRoutes) {
+			if (!route.contentArtifactUrl) continue;
+			lines.push(`- [${route.title}](${basePath}${route.contentArtifactUrl})`);
+		}
+	}
+	return `${lines.join("\n")}\n`;
+}
+function createLlmsTxtArtifact(routes, projectConfig) {
+	return withUtf8Signature(createLlmsTxt(routes, projectConfig));
+}
+function writeLlmsTxt(routes, projectConfig, outputDirectory) {
+	mkdirSync(outputDirectory, { recursive: true });
+	writeFileSync(join(outputDirectory, "llms.txt"), createLlmsTxtArtifact(routes, projectConfig), "utf-8");
+}
+//#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) {
+	if (route.kind === "openapi" && /\.ya?ml$/i.test(route.contentArtifactUrl ?? "")) return "text/yaml; charset=utf-8";
+	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;
+	}
+	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: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:done": (ctx) => {
+				const outputDirectory = ctx.generateOptions.outputDirectory;
+				if (!outputDirectory) return;
+				const outputRoot = join(ctx.generateOptions.projectRoot, outputDirectory);
+				writeContentArtifactFiles(ctx.routes, outputRoot);
+				writeLlmsTxt(ctx.routes, ctx.projectConfig, outputRoot);
+			}
+		}
+	};
+}
+//#endregion
+//#region source/plugins/html-shell/index.ts
+var THEME_BOOTSTRAP_SCRIPT = `(function(){try{var e=localStorage.getItem('clarify:theme');var t=e==='dark'||e==='light'||e==='system'?e:'system';var r=t==='system'?window.matchMedia('(prefers-color-scheme: dark)').matches:t==='dark';document.documentElement.classList.toggle('dark',r);document.documentElement.style.colorScheme=r?'dark':'light'}catch(e){}})();`;
+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: THEME_BOOTSTRAP_SCRIPT,
+					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/routes.ts
+function kebabToTitle$1(str) {
+	return str.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
+function parseMdxTree(content) {
+	return remark.parse(content);
+}
+/** 从内容中提取第一个 H1 标题 */
+function extractH1(content) {
+	const tree = parseMdxTree(content);
+	let title = "";
+	visit(tree, "heading", (node) => {
+		if (!title && node.depth === 1) title = toString(node);
+	});
+	return title;
+}
+/** 从 MDX/Markdown 内容中提取 H2/H3 章节 */
+function extractMdxSections(content) {
+	const sections = [];
+	const slugger = new GithubSlugger();
+	visit(parseMdxTree(content), "heading", (node) => {
+		if (node.depth !== 2 && node.depth !== 3) return;
+		const title = toString(node);
+		sections.push({
+			id: slugger.slug(title),
+			title,
+			level: node.depth
+		});
+	});
+	return sections;
+}
+function navigationSections(sections) {
+	return sections.map((s) => ({
+		id: s.id,
+		title: s.title,
+		badge: s.badge,
+		tags: s.tags
+	}));
+}
+function normalizePath(path) {
+	const clean = "/" + path.replace(/^\/+|\/+$/g, "");
+	return clean === "/" ? "/" : clean.replace(/\/+/g, "/");
+}
+function pathSegmentFromOpenAPITag(tag) {
+	return tag.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "tag";
+}
+function openAPITagsPathSegment(tags) {
+	return tags.map(pathSegmentFromOpenAPITag).join("-");
+}
+function basePathFromRef(ref) {
 	const withoutExtension = ref.replace(/\.mdx?$/, "").replace(/\.openapi\.(json|yaml|yml)$/, "");
 	return normalizePath(withoutExtension === "index" ? "/" : withoutExtension.replace(/\/index$/, ""));
 }
+function openAPIPagePathFromRef(ref, tagFilter) {
+	const basePath = basePathFromRef(ref);
+	if (!tagFilter?.length) return basePath;
+	return normalizePath(`${basePath}/${openAPITagsPathSegment(tagFilter)}`);
+}
 function routePathFromRef(ref) {
 	return basePathFromRef(ref);
 }
@@ -217,7 +673,7 @@ function frontmatterKeywords(frontmatter) {
 function buildNavigation(routes) {
 	const root = [];
 	for (const route of routes) {
-		if (route.path === "/") continue;
+		if (route.path === "/" || (route.basePath ?? route.path) === "/404") continue;
 		const parts = route.path.replace(/^\//, "").split("/");
 		let current = root;
 		for (let i = 0; i < parts.length; i++) {
@@ -244,6 +700,7 @@ function resolvePageItem(item) {
 	if (typeof item === "string") return { pageRef: item };
 	if ("openapi" in item) return {
 		openapiRef: item.openapi,
+		openapiTagFilter: item.filter?.tags,
 		title: item.title,
 		icon: item.icon
 	};
@@ -282,9 +739,9 @@ function buildNavigationFromConfig(routes, config) {
 	const routeMap = new Map(routes.map((r) => [r.path, r]));
 	return config.map((group) => {
 		const children = group.pages.map((item) => {
-			const { pageRef, openapiRef, redirect, title, icon } = resolvePageItem(item);
+			const { pageRef, openapiRef, openapiTagFilter, redirect, title, icon } = resolvePageItem(item);
 			if (openapiRef) {
-				const path = "/" + openapiRef.replace(/\.openapi\.(json|yaml|yml)$/, "");
+				const path = openAPIPagePathFromRef(openapiRef, openapiTagFilter);
 				const route = routeMap.get(path);
 				return {
 					path,
@@ -326,9 +783,9 @@ function buildLocalizedNavigationForLocale(routes, config, locale, i18n) {
 	const routeMap = new Map(routes.map((route) => [route.basePath ?? route.path, route]));
 	return config.map((group) => {
 		const children = group.pages.map((item) => {
-			const { pageRef, openapiRef, redirect, title, icon } = resolvePageItem(item);
+			const { pageRef, openapiRef, openapiTagFilter, redirect, title, icon } = resolvePageItem(item);
 			const ref = openapiRef ?? pageRef ?? "";
-			const basePath = basePathFromRef(ref);
+			const basePath = openapiRef ? openAPIPagePathFromRef(openapiRef, openapiTagFilter) : basePathFromRef(ref);
 			const route = routeMap.get(basePath);
 			const path = route?.path ?? localizedRoutePath(basePath, locale, i18n);
 			return {
@@ -365,190 +822,6 @@ function buildLocalizedNavigationFromTabsConfig(routes, tabs, i18n) {
 	return result;
 }
 //#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 /\.ya?ml$/i.test(route.contentArtifactUrl ?? "");
-}
-function routeToMarkdownArtifactUrl(routePath) {
-	return `${routePath === "/" ? "/index" : routePath.replace(/\/$/, "")}.md`;
-}
-function routeToOpenAPIArtifactUrl(routePath, filePath) {
-	const extension = extname(filePath).toLowerCase() || ".json";
-	return `${routePath === "/" ? "/index" : routePath.replace(/\/$/, "")}.openapi${extension}`;
-}
-function attachContentArtifactUrls(routes) {
-	for (const route of routes) route.contentArtifactUrl = route.kind === "openapi" ? routeToOpenAPIArtifactUrl(route.path, route.filePath) : 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 writeContentArtifactFiles(routes, outputDirectory) {
-	for (const route of routes) {
-		if (!route.contentArtifactUrl) continue;
-		const outFile = join(outputDirectory, route.contentArtifactUrl.replace(/^\//, ""));
-		mkdirSync(dirname(outFile), { recursive: true });
-		writeFileSync(outFile, readRouteArtifactContent(route), "utf-8");
-	}
-}
-function createLlmsTxt(routes, projectConfig) {
-	const basePath = normalizeBasePath(projectConfig.routePrefix);
-	const lines = [`# ${projectConfig.title}`, ""];
-	if (projectConfig.description) lines.push(`> ${projectConfig.description}`, "");
-	lines.push("## Docs");
-	for (const route of routes.filter((route) => route.kind === "mdx")) {
-		if (!route.contentArtifactUrl) continue;
-		lines.push(`- [${route.title}](${basePath}${route.contentArtifactUrl})`);
-	}
-	const openApiRoutes = routes.filter((route) => route.kind === "openapi");
-	if (openApiRoutes.length > 0) {
-		lines.push("", "## OpenAPI");
-		for (const route of openApiRoutes) {
-			if (!route.contentArtifactUrl) continue;
-			lines.push(`- [${route.title}](${basePath}${route.contentArtifactUrl})`);
-		}
-	}
-	return `${lines.join("\n")}\n`;
-}
-function createLlmsTxtArtifact(routes, projectConfig) {
-	return withUtf8Signature(createLlmsTxt(routes, projectConfig));
-}
-function writeLlmsTxt(routes, projectConfig, outputDirectory) {
-	mkdirSync(outputDirectory, { recursive: true });
-	writeFileSync(join(outputDirectory, "llms.txt"), createLlmsTxtArtifact(routes, projectConfig), "utf-8");
-}
-//#endregion
-//#region source/plugins/content-artifacts/server.ts
-function normalizeRoutePrefix(routePrefix) {
-	if (!routePrefix || routePrefix === "/") return "";
-	return `/${routePrefix.replace(/^\/+|\/+$/g, "")}`;
-}
-function resolveContentArtifactPath(url, projectConfig) {
-	const requestPath = url?.split("?")[0] ?? "";
-	const basePath = normalizeRoutePrefix(projectConfig.routePrefix);
-	return basePath && requestPath.startsWith(basePath) ? requestPath.slice(basePath.length) || "/" : requestPath;
-}
-function resolveContentArtifactType(route) {
-	if (route.kind === "openapi" && /\.ya?ml$/i.test(route.contentArtifactUrl ?? "")) return "text/yaml; charset=utf-8";
-	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;
-	}
-	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: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:done": (ctx) => {
-				const outputDirectory = ctx.generateOptions.outputDirectory;
-				if (!outputDirectory) return;
-				writeContentArtifactFiles(ctx.routes, outputDirectory);
-				writeLlmsTxt(ctx.routes, ctx.projectConfig, outputDirectory);
-			}
-		}
-	};
-}
-//#endregion
-//#region source/plugins/html-shell/index.ts
-var THEME_BOOTSTRAP_SCRIPT = `(function(){try{var e=localStorage.getItem('clarify:theme');var t=e==='dark'||e==='light'||e==='system'?e:'system';var r=t==='system'?window.matchMedia('(prefers-color-scheme: dark)').matches:t==='dark';document.documentElement.classList.toggle('dark',r);document.documentElement.style.colorScheme=r?'dark':'light'}catch(e){}})();`;
-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: THEME_BOOTSTRAP_SCRIPT,
-					injectTo: "head-prepend"
-				},
-				{
-					tag: "script",
-					attrs: {
-						type: "module",
-						src: input.clientEntryId
-					},
-					injectTo: "body"
-				}
-			],
-			clientEntryId: input.clientEntryId,
-			dev: input.dev
-		}) }
-	};
-}
-//#endregion
 //#region source/plugins/openapi/parser.ts
 var OPENAPI_HTTP_METHODS = [
 	"get",
@@ -591,21 +864,26 @@ function findOpenAPIRoutes(dir, base = dir) {
 	}
 	return routes;
 }
+function operationMatchesTags(operationTags, filterTags) {
+	if (!filterTags?.length) return true;
+	return operationTags?.some((tag) => filterTags.includes(tag)) ?? false;
+}
 /** Extract endpoint operations from an OpenAPI spec as page sections. */
-function extractOpenAPISections(spec) {
+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) continue;
+			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()
+				badge: method.toUpperCase(),
+				tags: op.tags
 			});
 		}
 	}
@@ -630,320 +908,315 @@ async function readOpenAPISpec(filePath) {
 	}
 }
 //#endregion
-//#region source/plugins/openapi/virtual-modules.ts
-var openApiRegistryModuleId = "virtual:clarify-openapi-registry";
-function generateOpenAPIRegistryModule(openApis) {
-	return `export const openApis = ${JSON.stringify(openApis)};`;
+//#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_RUNTIME = "virtual:clarify-runtime";
+var VIRTUAL_CLIENT_ENTRY = "virtual:clarify-entry-client";
+var RESOLVED_CLIENT_ENTRY = "\0virtual:clarify-entry-client";
+function resolveVirtualId(id) {
+	return "\0" + id;
 }
-function generateOpenAPIModule(spec) {
-	return `import { createElement } from 'react';
-import { OpenApiDocument } from '@clarify-labs/renderer';
-const spec = ${JSON.stringify(spec)};
-export default function OpenApiRoutePage() {
-  return createElement(OpenApiDocument, { spec });
-}`;
+function stripVirtualPrefix(id) {
+	return id.startsWith("\0") ? id.slice(1) : id;
 }
-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
-    )
-  );
-}`;
+function generateConfigModule(projectConfig, buildOptions) {
+	return `export const config = ${JSON.stringify({
+		...projectConfig,
+		...buildOptions
+	})};`;
 }
-//#endregion
-//#region source/plugins/openapi/index.ts
-function createOpenAPIPlugin() {
-	const specs = {};
-	return {
-		name: "clarify:openapi",
-		hooks: {
-			"routes:discover": (input) => ({
-				...input,
-				routes: [...input.routes, ...findOpenAPIRoutes(input.contentRoot)]
-			}),
-			"routes:discovered": async (routes) => {
-				for (const key of Object.keys(specs)) delete specs[key];
-				for (const route of routes.filter((route) => route.kind === "openapi")) {
-					const result = await readOpenAPISpec(route.filePath);
-					if (!result.ok) {
-						route.diagnostic = result.diagnostic;
-						route.title = route.title || "OpenAPI parse error";
-						route.sections = [];
-						continue;
-					}
-					const spec = result.spec;
-					specs[route.virtualModuleId] = spec;
-					specs[`virtual:clarify-page/${route.path.replace(/^\//, "")}`] = spec;
-					route.title = spec.info?.title ?? route.title;
-					route.description = spec.info?.description ?? route.description;
-					route.sections = extractOpenAPISections(spec);
-				}
-				return routes;
-			},
-			"modules:before": (modules, ctx) => {
-				modules.set(openApiRegistryModuleId, generateOpenAPIRegistryModule(specs));
-				for (const [moduleId, spec] of Object.entries(specs)) modules.set(moduleId, generateOpenAPIModule(spec));
-				for (const route of ctx.routes.filter((route) => route.kind === "openapi" && route.diagnostic)) if (route.diagnostic) modules.set(route.virtualModuleId, generateOpenAPIErrorModule(route.diagnostic));
-				return modules;
-			}
-		}
-	};
+function moduleSpecifier(value) {
+	return JSON.stringify(value);
 }
-//#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"]
-	});
-});
-var clarifyNavbarLinkSchema = z.object({
-	label: clarifyLocalizedTextSchema,
-	href: z.string(),
-	external: z.boolean().optional()
-});
-var clarifyBannerConfigSchema = z.object({
-	content: clarifyLocalizedTextSchema,
-	dismissible: z.boolean().optional()
-});
-var clarifyFooterConfigSchema = z.object({
-	links: z.array(clarifyNavbarLinkSchema).optional(),
-	socials: z.record(z.string(), z.string()).optional(),
-	copyright: clarifyLocalizedTextSchema.optional()
-});
-var clarifyPagesItemSchema = z.union([
-	z.string(),
-	z.object({
-		page: z.string(),
-		title: clarifyLocalizedTextSchema.optional(),
-		icon: z.string().optional(),
-		redirect: z.string().optional()
-	}),
-	z.object({
-		openapi: z.string(),
-		icon: z.string().optional(),
-		title: clarifyLocalizedTextSchema.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 clarifyThemeColorTokensConfigSchema = z.object({
-	primary: z.string().optional(),
-	accent: z.string().optional(),
-	background: z.string().optional(),
-	foreground: z.string().optional(),
-	surface: z.string().optional(),
-	muted: z.string().optional(),
-	border: z.string().optional(),
-	codeBackground: z.string().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()
-});
-var clarifyProjectConfigSchema = z.object({
-	title: z.string().optional(),
-	description: z.string().optional(),
-	logo: clarifyLogoConfigSchema.optional(),
-	favicon: clarifyFaviconConfigSchema.optional(),
-	theme: clarifyThemeConfigSchema.optional(),
-	routePrefix: z.string().optional(),
-	navbar: z.object({ links: z.array(clarifyNavbarLinkSchema).optional() }).optional(),
-	banner: clarifyBannerConfigSchema.optional(),
-	footer: clarifyFooterConfigSchema.optional(),
-	i18n: clarifyI18nConfigSchema.optional(),
-	tabs: clarifyTabsConfigSchema.optional()
-});
-//#endregion
-//#region source/core/theme.ts
-var clarifyThemePresets = {
-	default: {
-		preset: "default",
-		tokens: {
-			colors: {
-				primary: "#00D492",
-				accent: "#00F6C9",
-				background: "#ffffff",
-				foreground: "#111827",
-				surface: "#ffffff",
-				muted: "#64748b",
-				border: "rgb(15 23 42 / 0.12)",
-				codeBackground: "#f7fefb"
-			},
-			radius: {
-				sm: "6px",
-				md: "10px",
-				lg: "14px",
-				xl: "18px"
-			}
-		},
-		layout: { maxWidth: "82rem" }
-	},
-	base: {
-		preset: "base",
-		tokens: {
-			colors: {
-				primary: "#18181b",
-				accent: "#52525b",
-				background: "#ffffff",
-				foreground: "#18181b",
-				surface: "#ffffff",
-				muted: "#71717a",
-				border: "rgb(24 24 27 / 0.12)",
-				codeBackground: "#f4f4f5"
-			},
-			radius: {
-				sm: "6px",
-				md: "8px",
-				lg: "12px",
-				xl: "16px"
-			}
-		},
-		layout: { maxWidth: "80rem" }
+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,
+			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 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}${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 createRuntimeModule() {
+	return "export const openApis = {};";
+}
+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_RUNTIME}';
+render({ config, routes, navigation, openApis, themeEditor: ${JSON.stringify(options.themeEditor ?? false)} });`;
+}
+function buildVirtualModules(args) {
+	const modules = /* @__PURE__ */ new Map();
+	const clientEntryModule = createClientEntryModule({ themeEditor: args.themeEditor });
+	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_RUNTIME, createRuntimeModule());
+	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;
+}
+//#endregion
+//#region source/plugins/openapi/virtual-modules.ts
+var openApiRegistryModuleId = VIRTUAL_RUNTIME;
+function generateOpenAPIRegistryModule(openApis) {
+	return `export const openApis = ${JSON.stringify(openApis)};`;
+}
+function generateOpenAPIModule(spec, tagFilter) {
+	return `import { createElement } from 'react';
+import { OpenApiDocument } from '@clarify-labs/renderer';
+const spec = ${JSON.stringify(spec)};
+const tagFilter = ${JSON.stringify(tagFilter)};
+export default function OpenApiRoutePage() {
+  return createElement(OpenApiDocument, { spec, tagFilter });
+}`;
+}
+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
+    )
+  );
+}`;
+}
+//#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.filter?.tags?.length) items.push(item);
 	}
-};
-function resolveThemeConfig(theme = {}) {
-	const preset = theme.preset ?? "default";
-	const presetTheme = clarifyThemePresets[preset];
+	for (const tab of config.tabs ?? []) visitPages(tab.pages);
+	return items;
+}
+function withAlternates$1(route, routes, i18n) {
+	const basePath = route.basePath ?? route.path;
+	const routeByLocaleAndBase = new Map(routes.map((route) => [`${route.locale ?? ""}:${route.basePath ?? route.path}`, route]));
+	const alternates = Object.fromEntries(i18n.locales.flatMap((locale) => {
+		const alternate = routeByLocaleAndBase.get(`${locale.code}:${basePath}`);
+		return alternate ? [[locale.code, alternate.path]] : [];
+	}));
 	return {
-		preset,
-		tokens: {
-			colors: {
-				...presetTheme.tokens.colors,
-				...theme.tokens?.colors
+		...route,
+		alternates
+	};
+}
+function createTaggedOpenAPIRoutes(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);
+		if (!tagFilter?.length) continue;
+		const sourceBasePath = openAPIPagePathFromRef(item.openapi);
+		const filteredBasePath = openAPIPagePathFromRef(item.openapi, tagFilter);
+		for (const route of routes) {
+			if (route.kind !== "openapi" || (route.basePath ?? route.path) !== sourceBasePath) continue;
+			const key = `${route.locale ?? ""}:${filteredBasePath}`;
+			if (existingKeys.has(key)) continue;
+			existingKeys.add(key);
+			additions.push({
+				...route,
+				path: route.locale && config.i18n ? localizedRoutePath(filteredBasePath, route.locale, config.i18n) : filteredBasePath,
+				basePath: filteredBasePath,
+				title: route.title,
+				virtualModuleId: `${route.virtualModuleId}/${openAPITagsPathSegment(tagFilter)}`,
+				openapiTagFilter: tagFilter
+			});
+		}
+	}
+	const nextRoutes = [...routes, ...additions];
+	return config.i18n ? nextRoutes.map((route) => withAlternates$1(route, nextRoutes, config.i18n)) : nextRoutes;
+}
+function createOpenAPIPlugin() {
+	const specs = {};
+	return {
+		name: "clarify:openapi",
+		hooks: {
+			"routes:discover": (input) => ({
+				...input,
+				routes: [...input.routes, ...findOpenAPIRoutes(input.contentRoot)]
+			}),
+			"routes:discovered": async (routes, ctx) => {
+				for (const key of Object.keys(specs)) delete specs[key];
+				const nextRoutes = createTaggedOpenAPIRoutes(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);
+					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);
+					specs[route.virtualModuleId] = {
+						spec,
+						tagFilter: route.openapiTagFilter
+					};
+					specs[`virtual:clarify-page/${route.path.replace(/^\//, "")}`] = {
+						spec,
+						tagFilter: route.openapiTagFilter
+					};
+					route.title = spec.info?.title ?? route.title;
+					route.description = spec.info?.description ?? route.description;
+					route.sections = extractOpenAPISections(spec, route.openapiTagFilter);
+				}
+				return nextRoutes;
 			},
-			radius: {
-				...presetTheme.tokens.radius,
-				...theme.tokens?.radius
+			"modules:before": (modules, ctx) => {
+				modules.set(openApiRegistryModuleId, generateOpenAPIRegistryModule(Object.fromEntries(Object.entries(specs).map(([moduleId, entry]) => [moduleId, entry.spec]))));
+				for (const [moduleId, entry] of Object.entries(specs)) modules.set(moduleId, generateOpenAPIModule(entry.spec, entry.tagFilter));
+				for (const route of ctx.routes.filter((route) => route.kind === "openapi" && route.diagnostic)) if (route.diagnostic) modules.set(route.virtualModuleId, generateOpenAPIErrorModule(route.diagnostic));
+				return modules;
 			}
-		},
-		layout: {
-			...presetTheme.layout,
-			...theme.layout
 		}
 	};
 }
 //#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;
+function escapeXml(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
+}
+function publicRoutes(routes) {
+	return routes.filter((route) => route.path !== "/404");
+}
+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 createRobotsTxt(config) {
+	if (!config.siteUrl) return void 0;
+	return [
+		"User-agent: *",
+		"Allow: /",
+		`Sitemap: ${routeUrl(config.siteUrl, config.routePrefix, "/sitemap.xml")}`,
+		""
+	].join("\n");
+}
+async function writeSeoFiles(outputRoot, routes, config) {
+	const sitemap = createSitemapXml(routes, config);
+	const robots = createRobotsTxt(config);
+	if (!sitemap || !robots) return;
+	await mkdir(outputRoot, { recursive: true });
+	await Promise.all([writeFile(join(outputRoot, "sitemap.xml"), sitemap, "utf-8"), writeFile(join(outputRoot, "robots.txt"), robots, "utf-8")]);
+}
+//#endregion
+//#region source/plugins/seo/index.ts
+function createSeoPlugin() {
 	return {
-		defaultLocale,
-		missing: i18n.missing ?? "fallback",
-		locales: i18n.locales
+		name: "clarify:seo",
+		hooks: { async "build:done"(ctx) {
+			const outputDirectory = ctx.generateOptions.outputDirectory;
+			if (!outputDirectory) return;
+			await writeSeoFiles(join(ctx.generateOptions.projectRoot, outputDirectory), ctx.routes, ctx.projectConfig);
+		} }
 	};
 }
-function resolveProjectConfig(config = {}) {
+//#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 {
-		title: config.title ?? "Clarify Docs",
-		description: config.description ?? "",
-		logo: config.logo,
-		favicon: config.favicon,
-		routePrefix: config.routePrefix ?? "/",
-		theme: resolveThemeConfig(config.theme),
-		navbar: config.navbar,
-		banner: config.banner,
-		footer: config.footer,
-		i18n: resolveI18nConfig(config.i18n),
-		tabs: config.tabs
+		name: "clarify:source-links",
+		hooks: { "routes:discovered": (routes, ctx) => {
+			attachSourceUrls(routes, join(ctx.generateOptions.projectRoot, ctx.generateOptions.rootDirectory), ctx.projectConfig.source);
+			return routes;
+		} }
 	};
 }
 //#endregion
+//#region source/core/builtin.ts
+function createBuiltinPlugins(options = {}) {
+	const plugins = [
+		createOpenAPIPlugin(),
+		createSourceLinksPlugin(),
+		createContentArtifactsPlugin(),
+		createSeoPlugin()
+	];
+	if (options.htmlShell ?? true) plugins.push(createHtmlShellPlugin());
+	return plugins;
+}
+//#endregion
 //#region source/core/hooks.ts
 async function runHooks(plugins, hookName, input, ctx) {
 	let result = input;
@@ -984,12 +1257,104 @@ async function runBuildDoneHooks(plugins, ctx) {
 //#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/site.ts
+function withAlternates(route, routeList, i18n) {
+	const basePath = route.basePath ?? route.path;
+	const routeByLocaleAndBase = new Map(routeList.map((route) => [`${route.locale ?? ""}:${route.basePath ?? route.path}`, route]));
+	const alternates = Object.fromEntries(i18n.locales.flatMap((locale) => {
+		const alternate = routeByLocaleAndBase.get(`${locale.code}:${basePath}`);
+		return alternate ? [[locale.code, alternate.path]] : [];
+	}));
+	return {
+		...route,
+		alternates
+	};
+}
+async function discoverRoutesForRoot(routeRoot, locale, plugins, ctx) {
+	return (await runHooks(plugins, "routes:discover", {
+		contentRoot: routeRoot,
+		locale,
+		routes: findContentRoutes(routeRoot)
+	}, 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
+				});
+			}
+		}
+	}
+	return localizedRoutes.map((route) => withAlternates(route, localizedRoutes, i18n));
+}
+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: []
+	};
+	let routes = await discoverRoutes(root, contentRoot, plugins, ctx);
+	routes = await runHooks(plugins, "routes:discovered", routes, ctx);
+	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
+	};
+}
+//#endregion
 //#region source/core/runtime-deps.ts
 var requireFromCli = createRequire(import.meta.url);
 function resolveCliDependency(id) {
@@ -1084,13 +1449,21 @@ function injectSSRIntoTemplate(template, appHtml, projectConfig, route) {
 	html = html.replace(/<div id="root">[\s\S]*?<\/div>/, `<div id="root">${appHtml}</div>`);
 	return html;
 }
+function isNotFoundRoute(route) {
+	return (route.basePath ?? route.path) === "/404";
+}
+function routeOutputFiles(outputDirectory, route) {
+	const files = [join(outputDirectory, route.path, "index.html")];
+	if (isNotFoundRoute(route) && (!route.locale || route.path === "/404")) files.push(join(outputDirectory, "404.html"));
+	return files;
+}
 var SSR_ENTRY_CODE = `import { renderToHTML } from '@clarify-labs/renderer/server';
 import { routes, navigation } from 'virtual:clarify-routes/server';
 import { config } from 'virtual:clarify-config';
-import { openApis } from 'virtual:clarify-openapi-registry';
+import { openApis } from 'virtual:clarify-runtime';
 
 export function render(url) {
-  return renderToHTML({ config, routes, navigation, openApis, url });
+  return renderToHTML({ config, routes, navigation, openApis, url, themeEditor: config.theme.editor });
 }`;
 function createTempEntryFile(content) {
 	const entryPath = join(mkdtempSync(join(tmpdir(), "clarify-ssr-")), "entry-server.ts");
@@ -1121,9 +1494,10 @@ async function renderSSGRoutes(routes, projectConfig, outputDirectory, ssrBundle
 	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, render(route.path), projectConfig, route);
-		const outFile = join(outputDirectory, route.path, "index.html");
-		mkdirSync(dirname(outFile), { recursive: true });
-		writeFileSync(outFile, finalHtml, "utf-8");
+		for (const outFile of routeOutputFiles(outputDirectory, route)) {
+			mkdirSync(dirname(outFile), { recursive: true });
+			writeFileSync(outFile, finalHtml, "utf-8");
+		}
 	} catch (err) {
 		console.error(`[clarify] Failed to render route "${route.path}":`, err);
 		if (failOnError) throw err;
@@ -1165,75 +1539,6 @@ async function loadClarifyConfig(root, env) {
 	return assertConfigObject((await loadConfigFromFile(env, configFile, root, "silent"))?.config, configFile);
 }
 //#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_REGISTRY = openApiRegistryModuleId;
-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,
-			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 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 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}${alternates}${description}${keywords}${sections}${contentArtifactUrl} }`;
-	}).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() {
-	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_REGISTRY}';
-render({ config, routes, navigation, openApis });`;
-}
-function buildVirtualModules(args) {
-	const modules = /* @__PURE__ */ new Map();
-	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_OPENAPI_REGISTRY, "export const openApis = {};");
-	modules.set(VIRTUAL_CLIENT_ENTRY, createClientEntryModule());
-	modules.set(RESOLVED_CLIENT_ENTRY, createClientEntryModule());
-	for (const route of args.routes) {
-		if (route.kind === "openapi") continue;
-		modules.set(route.virtualModuleId, `export { default } from ${moduleSpecifier(route.filePath)};`);
-	}
-	return modules;
-}
-//#endregion
 //#region source/core/plugin.ts
 function loadVirtualModule(id, modules) {
 	const bareId = stripVirtualPrefix(id);
@@ -1246,12 +1551,7 @@ function clarifyPlugin(options = {}) {
 	const contentRoot = join(root, generateOptions.rootDirectory);
 	const configFilePath = findClarifyConfigFile(root);
 	let routes = [];
-	const clarifyPlugins = [
-		createOpenAPIPlugin(),
-		createContentArtifactsPlugin(),
-		createHtmlShellPlugin(),
-		...options.plugins ?? []
-	];
+	let clarifyPlugins = [...createBuiltinPlugins(), ...options.plugins ?? []];
 	const ctx = {
 		projectConfig,
 		generateOptions,
@@ -1276,71 +1576,15 @@ function clarifyPlugin(options = {}) {
 		ctx.projectConfig = projectConfig;
 		ctx.generateOptions = generateOptions;
 	}
-	function withAlternates(route, routeList, i18n) {
-		const basePath = route.basePath ?? route.path;
-		const routeByLocaleAndBase = new Map(routeList.map((route) => [`${route.locale ?? ""}:${route.basePath ?? route.path}`, route]));
-		const alternates = Object.fromEntries(i18n.locales.flatMap((locale) => {
-			const alternate = routeByLocaleAndBase.get(`${locale.code}:${basePath}`);
-			return alternate ? [[locale.code, alternate.path]] : [];
-		}));
-		return {
-			...route,
-			alternates
-		};
-	}
-	async function discoverRoutesForRoot(routeRoot, locale) {
-		return (await runHooks(clarifyPlugins, "routes:discover", {
-			contentRoot: routeRoot,
-			locale,
-			routes: findContentRoutes(routeRoot)
-		}, ctx)).routes;
-	}
-	async function discoverRoutes() {
-		const i18n = projectConfig.i18n;
-		if (!i18n) return discoverRoutesForRoot(contentRoot);
-		const localizedRoutes = [];
-		for (const locale of i18n.locales) {
-			const discovered = await discoverRoutesForRoot(join(contentRoot, locale.code), locale.code);
-			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
-					});
-				}
-			}
-		}
-		return localizedRoutes.map((route) => withAlternates(route, localizedRoutes, i18n));
-	}
 	async function resolveRoutesAndSpecs() {
-		routes = await discoverRoutes();
-		routes = await runHooks(clarifyPlugins, "routes:discovered", routes, ctx);
-		const defaultNavigation = projectConfig.tabs ? projectConfig.i18n ? buildLocalizedNavigationFromTabsConfig(routes, projectConfig.tabs, projectConfig.i18n) ?? {} : buildNavigationFromTabsConfig(routes, projectConfig.tabs) : buildNavigation(routes);
-		const resolved = await runHooks(clarifyPlugins, "routes:resolved", {
-			routes,
-			navigation: defaultNavigation
-		}, ctx);
-		routes = resolved.routes;
-		resolvedNavigation = resolved.navigation;
+		const site = await resolveClarifySite(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;
 	}
@@ -1349,7 +1593,8 @@ function clarifyPlugin(options = {}) {
 			projectConfig,
 			generateOptions,
 			routes,
-			navigation: resolvedNavigation
+			navigation: resolvedNavigation,
+			themeEditor: viteConfig.command === "serve" || projectConfig.theme.editor
 		});
 		virtualModules = await runHooks(clarifyPlugins, "modules:before", virtualModules, ctx);
 	}
@@ -1429,8 +1674,9 @@ function clarifyPlugin(options = {}) {
 				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_OPENAPI_REGISTRY || id === resolveVirtualId(VIRTUAL_OPENAPI_REGISTRY)) return resolveVirtualId(VIRTUAL_OPENAPI_REGISTRY);
-				const route = routes.find((r) => r.virtualModuleId === id || r.virtualModuleId === stripVirtualPrefix(id));
+				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;
 			},
@@ -1452,10 +1698,11 @@ function clarifyPlugin(options = {}) {
 			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: transformCtx.server ? `/@id/${VIRTUAL_CLIENT_ENTRY}` : VIRTUAL_CLIENT_ENTRY,
+						clientEntryId,
 						dev: Boolean(transformCtx.server)
 					}, ctx);
 					return {
@@ -1483,7 +1730,7 @@ function clarifyPlugin(options = {}) {
 								if (id === "virtual:clarify-config") return id;
 								if (id === "virtual:clarify-routes") return id;
 								if (id === "virtual:clarify-routes/server") return id;
-								if (id === VIRTUAL_OPENAPI_REGISTRY) return id;
+								if (virtualModules.has(stripVirtualPrefix(id))) return stripVirtualPrefix(id);
 								if (routes.find((r) => r.virtualModuleId === id)) return id;
 								return null;
 							},
@@ -1509,6 +1756,6 @@ function clarifyPlugin(options = {}) {
 	].flat().filter(Boolean);
 }
 //#endregion
-export { createClarifyRuntimeAliases as i, defineConfig as n, loadClarifyConfig as r, clarifyPlugin as t };
+export { resolveClarifySite as a, createClarifyRuntimeAliases as i, defineConfig as n, loadClarifyConfig as r, clarifyPlugin as t };
 
-//# sourceMappingURL=plugin-DChFdTyI.js.map
+//# sourceMappingURL=plugin-BgE7WVoS.js.map