@clarify-labs/cli 0.6.4 → 0.6.6

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

@@ -11,6 +11,7 @@ import { markdownRemarkPlugins } from "@clarify-labs/renderer";
 import { remark } from "remark";
 import matter from "gray-matter";
 import SwaggerParser from "@apidevtools/swagger-parser";
+import { mkdir, writeFile } from "node:fs/promises";
 import { z } from "zod";
 import { tmpdir } from "node:os";
 import { pathToFileURL } from "node:url";
@@ -47,6 +48,11 @@ function rehypeParseCodeBlocks() {
 			const language = getLanguage(node.properties.className);
 			parentNode.properties.language = language;
 			node.properties.language = language;
+			for (const key of [
+				"title",
+				"tag",
+				"label"
+			]) if (node.properties[key] !== void 0) parentNode.properties[key] = node.properties[key];
 		});
 	};
 }
@@ -100,6 +106,191 @@ var rehypePlugins = [
 	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 /\.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，并返回可供后续流程复用的标准化正文。
@@ -155,10 +346,21 @@ 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 +419,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 +446,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 +485,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,227 +529,43 @@ 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 {
-				path: (redirect ? localizedRoutePath(basePathFromRef(redirect), locale, i18n) : void 0) ?? path,
-				title: resolveLocalizedText(title, locale, i18n.defaultLocale) ?? route?.title ?? kebabToTitle$1(basePath.split("/").pop() ?? ref),
-				icon,
-				sections: route?.sections ? navigationSections(route.sections) : void 0
-			};
-		});
-		return {
-			path: children[0]?.path ?? localizedRoutePath("/", locale, i18n),
-			title: resolveLocalizedText(group.group, locale, i18n.defaultLocale) ?? "",
-			icon: group.icon,
-			children
-		};
-	});
-}
-function buildLocalizedNavigationFromTabsConfig(routes, tabs, i18n) {
-	if (!i18n) return void 0;
-	const result = {};
-	for (const locale of i18n.locales) {
-		const localeRoutes = routes.filter((route) => route.locale === locale.code);
-		result[locale.code] = { tabs: tabs.map((tab) => {
-			const children = buildLocalizedNavigationForLocale(localeRoutes, tab.pages, locale.code, i18n);
-			return {
-				type: "tab",
-				path: firstNavigationPath(children),
-				title: resolveLocalizedText(tab.tab, locale.code, i18n.defaultLocale) ?? "",
-				icon: tab.icon,
-				children
-			};
-		}) };
-	}
-	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
-		}) }
-	};
+			return {
+				path: (redirect ? localizedRoutePath(basePathFromRef(redirect), locale, i18n) : void 0) ?? path,
+				title: resolveLocalizedText(title, locale, i18n.defaultLocale) ?? route?.title ?? kebabToTitle$1(basePath.split("/").pop() ?? ref),
+				icon,
+				sections: route?.sections ? navigationSections(route.sections) : void 0
+			};
+		});
+		return {
+			path: children[0]?.path ?? localizedRoutePath("/", locale, i18n),
+			title: resolveLocalizedText(group.group, locale, i18n.defaultLocale) ?? "",
+			icon: group.icon,
+			children
+		};
+	});
+}
+function buildLocalizedNavigationFromTabsConfig(routes, tabs, i18n) {
+	if (!i18n) return void 0;
+	const result = {};
+	for (const locale of i18n.locales) {
+		const localeRoutes = routes.filter((route) => route.locale === locale.code);
+		result[locale.code] = { tabs: tabs.map((tab) => {
+			const children = buildLocalizedNavigationForLocale(localeRoutes, tab.pages, locale.code, i18n);
+			return {
+				type: "tab",
+				path: firstNavigationPath(children),
+				title: resolveLocalizedText(tab.tab, locale.code, i18n.defaultLocale) ?? "",
+				icon: tab.icon,
+				children
+			};
+		}) };
+	}
+	return result;
 }
 //#endregion
 //#region source/plugins/openapi/parser.ts
@@ -591,21 +610,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,17 +654,89 @@ async function readOpenAPISpec(filePath) {
 	}
 }
 //#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_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 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 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:clarify-openapi-registry";
+var openApiRegistryModuleId = VIRTUAL_RUNTIME;
 function generateOpenAPIRegistryModule(openApis) {
 	return `export const openApis = ${JSON.stringify(openApis)};`;
 }
-function generateOpenAPIModule(spec) {
+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 });
+  return createElement(OpenApiDocument, { spec, tagFilter });
 }`;
 }
 function generateOpenAPIErrorModule(diagnostic) {
@@ -666,6 +762,55 @@ export default function OpenApiErrorRoutePage() {
 }
 //#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);
+	}
+	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 {
+		...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 {
@@ -675,10 +820,16 @@ function createOpenAPIPlugin() {
 				...input,
 				routes: [...input.routes, ...findOpenAPIRoutes(input.contentRoot)]
 			}),
-			"routes:discovered": async (routes) => {
+			"routes:discovered": async (routes, ctx) => {
 				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);
+				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";
@@ -686,17 +837,24 @@ function createOpenAPIPlugin() {
 						continue;
 					}
 					const spec = result.spec;
-					specs[route.virtualModuleId] = spec;
-					specs[`virtual:clarify-page/${route.path.replace(/^\//, "")}`] = 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.sections = extractOpenAPISections(spec, route.openapiTagFilter);
 				}
-				return routes;
+				return nextRoutes;
 			},
 			"modules:before": (modules, ctx) => {
-				modules.set(openApiRegistryModuleId, generateOpenAPIRegistryModule(specs));
-				for (const [moduleId, spec] of Object.entries(specs)) modules.set(moduleId, generateOpenAPIModule(spec));
+				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;
 			}
@@ -704,6 +862,107 @@ function createOpenAPIPlugin() {
 	};
 }
 //#endregion
+//#region source/plugins/seo/artifacts.ts
+function trimTrailingSlash(value) {
+	return value.replace(/\/+$/, "");
+}
+function normalizeRoutePrefix(routePrefix) {
+	if (!routePrefix || routePrefix === "/") return "";
+	return `/${routePrefix.replace(/^\/+|\/+$/g, "")}`;
+}
+function routeUrl(siteUrl, routePrefix, routePath) {
+	const base = trimTrailingSlash(siteUrl);
+	return `${base}${normalizeRoutePrefix(routePrefix)}${routePath === "/" ? "" : routePath.replace(/^\/+/, "/")}` || base;
+}
+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 {
+		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);
+		} }
+	};
+}
+//#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 {
+		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/config-schema.ts
 var clarifyLogoConfigSchema = z.union([z.string(), z.object({
 	light: z.string().optional(),
@@ -761,6 +1020,11 @@ var clarifyFooterConfigSchema = z.object({
 	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({
@@ -772,7 +1036,8 @@ var clarifyPagesItemSchema = z.union([
 	z.object({
 		openapi: z.string(),
 		icon: z.string().optional(),
-		title: clarifyLocalizedTextSchema.optional()
+		title: clarifyLocalizedTextSchema.optional(),
+		filter: z.object({ tags: z.array(z.string()).optional() }).optional()
 	})
 ]);
 var clarifyPagesGroupSchema = z.object({
@@ -788,15 +1053,20 @@ var clarifyTabItemSchema = z.object({
 });
 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: 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()
+	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(),
@@ -812,11 +1082,14 @@ var clarifyThemeLayoutConfigSchema = z.object({ maxWidth: z.string().optional()
 var clarifyThemeConfigSchema = z.object({
 	preset: clarifyThemePresetSchema.optional(),
 	tokens: clarifyThemeTokensConfigSchema.optional(),
-	layout: clarifyThemeLayoutConfigSchema.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(),
@@ -834,14 +1107,14 @@ var clarifyThemePresets = {
 		preset: "default",
 		tokens: {
 			colors: {
-				primary: "#00D492",
-				accent: "#00F6C9",
+				primary: "#047857",
+				accent: "#0D9488",
 				background: "#ffffff",
 				foreground: "#111827",
 				surface: "#ffffff",
 				muted: "#64748b",
 				border: "rgb(15 23 42 / 0.12)",
-				codeBackground: "#f7fefb"
+				codeBackground: "#f6fbf8"
 			},
 			radius: {
 				sm: "6px",
@@ -850,7 +1123,8 @@ var clarifyThemePresets = {
 				xl: "18px"
 			}
 		},
-		layout: { maxWidth: "82rem" }
+		layout: { maxWidth: "82rem" },
+		editor: false
 	},
 	base: {
 		preset: "base",
@@ -872,7 +1146,8 @@ var clarifyThemePresets = {
 				xl: "16px"
 			}
 		},
-		layout: { maxWidth: "80rem" }
+		layout: { maxWidth: "80rem" },
+		editor: false
 	}
 };
 function resolveThemeConfig(theme = {}) {
@@ -893,7 +1168,8 @@ function resolveThemeConfig(theme = {}) {
 		layout: {
 			...presetTheme.layout,
 			...theme.layout
-		}
+		},
+		editor: theme.editor ?? presetTheme.editor
 	};
 }
 //#endregion
@@ -932,6 +1208,8 @@ 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 ?? "/",
@@ -984,12 +1262,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 +1454,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 +1499,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 +1544,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 +1556,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 +1581,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 +1598,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 +1679,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 +1703,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 +1735,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 +1761,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-DC2f5YAH.js.map