@clarify-labs/cli 0.10.0 → 0.10.2

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

@@ -2,13 +2,16 @@ import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path
 import mdxPlugin from "@mdx-js/rollup";
 import tailwindcss from "@tailwindcss/vite";
 import react from "@vitejs/plugin-react";
+import rehypeRaw from "rehype-raw";
 import { compile } from "@mdx-js/mdx";
-import GithubSlugger, { slug } from "github-slugger";
-import { toString } from "mdast-util-to-string";
-import { bundledLanguages, createCssVariablesTheme, createHighlighter } from "shiki";
+import rehypeShiki from "@shikijs/rehype";
+import rehypeSlug from "rehype-slug";
+import { createCssVariablesTheme } from "shiki";
 import { visit } from "unist-util-visit";
-import { markdownRemarkPlugins, themeBootstrapScript, themePresets } from "@clarify-labs/renderer";
+import { markdownRemarkPlugins, parseCodeMeta, themeBootstrapScript, themePresets } from "@clarify-labs/renderer";
 import { readFile, readdir, stat } from "node:fs/promises";
+import GithubSlugger, { slug } from "github-slugger";
+import { toString } from "mdast-util-to-string";
 import { remark } from "remark";
 import matter from "gray-matter";
 import { createReadStream, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
@@ -19,38 +22,11 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import SwaggerParser from "@apidevtools/swagger-parser";
 import { tmpdir } from "node:os";
 import { createRequire } from "node:module";
-//#region source/parsers/markdown/utils.ts
-function escapeHtml(text) {
-	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
-}
-//#endregion
 //#region source/parsers/markdown/mdx.ts
 function getLanguage(className) {
 	return (Array.isArray(className) ? className : typeof className === "string" ? className.split(/\s+/) : []).find((item) => typeof item === "string" && item.startsWith("language-"))?.replace(/^language-/, "") || "txt";
 }
-function getTextContent(node) {
-	if (!node) return "";
-	if (typeof node.value === "string") return node.value;
-	return node.children?.map(getTextContent).join("") ?? "";
-}
-function renderPlainCode(code) {
-	return code.split("\n").map((line) => `<span>${escapeHtml(line)}</span>`).join("\n");
-}
-function isBundledLanguage(language) {
-	return language in bundledLanguages;
-}
-var highlighter;
 var cssVariablesTheme = createCssVariablesTheme();
-async function getHighlighter() {
-	highlighter = highlighter ?? await createHighlighter({
-		themes: [cssVariablesTheme],
-		langs: []
-	});
-	return highlighter;
-}
-function renderHighlightedCode(html) {
-	return (/<code[^>]*>([\s\S]*?)<\/code>/.exec(html)?.[1] ?? html).split("\n").map((line) => line.trimStart().startsWith("<span") ? line : `<span>${line}</span>`).join("\n");
-}
 function rehypeParseCodeBlocks() {
 	return (tree) => {
 		visit(tree, "element", (node, _nodeIndex, parentNode) => {
@@ -68,61 +44,18 @@ function rehypeParseCodeBlocks() {
 		});
 	};
 }
-function rehypeShiki() {
-	return async (tree) => {
-		const shikiHighlighter = await getHighlighter();
-		const languages = /* @__PURE__ */ new Set();
-		visit(tree, "element", (node) => {
-			if (node.tagName !== "pre") return;
-			const codeNode = node.children?.[0];
-			if (codeNode?.tagName !== "code") return;
-			const language = typeof node.properties?.language === "string" ? node.properties.language : getLanguage(codeNode.properties?.className);
-			if (language && language !== "txt" && isBundledLanguage(language)) languages.add(language);
-		});
-		if (languages.size > 0) await shikiHighlighter.loadLanguage(...languages);
-		visit(tree, "element", (node) => {
-			if (node.tagName !== "pre") return;
-			const codeNode = node.children?.[0];
-			if (codeNode?.tagName !== "code") return;
-			node.properties = node.properties ?? {};
-			codeNode.properties = codeNode.properties ?? {};
-			const code = getTextContent(codeNode);
-			const language = typeof node.properties.language === "string" ? node.properties.language : getLanguage(codeNode.properties.className);
-			node.properties.code = code;
-			codeNode.properties.code = code;
-			codeNode.properties.language = language;
-			let highlighted = renderPlainCode(code);
-			if (language && language !== "txt") try {
-				highlighted = renderHighlightedCode(shikiHighlighter.codeToHtml(code, {
-					lang: language,
-					theme: cssVariablesTheme
-				}));
-			} catch {
-				highlighted = renderPlainCode(code);
-			}
-			codeNode.children = [{
-				type: "text",
-				value: highlighted
-			}];
-		});
-	};
-}
-function rehypeSlugSections() {
-	return (tree) => {
-		const slugger = new GithubSlugger();
-		visit(tree, "element", (node) => {
-			if (node.tagName !== "h2" && node.tagName !== "h3") return;
-			node.properties = node.properties ?? {};
-			if (node.properties.id) return;
-			node.properties.id = slugger.slug(toString(node));
-		});
-	};
-}
 var remarkPlugins = markdownRemarkPlugins;
 var rehypePlugins = [
-	rehypeSlugSections,
+	rehypeSlug,
 	rehypeParseCodeBlocks,
-	rehypeShiki
+	[rehypeShiki, {
+		theme: cssVariablesTheme,
+		langs: [],
+		lazy: true,
+		addLanguageClass: true,
+		fallbackLanguage: "text",
+		parseMetaString: parseCodeMeta
+	}]
 ];
 function formatMdxDiagnostic(error) {
 	if (error instanceof Error) return error.message;
@@ -134,7 +67,8 @@ function formatMdxDiagnostic(error) {
 *
 * `rehypePlugins` includes `rehypeShiki`, which loads grammar/WASM assets and
 * is expensive. The real highlighting happens at Vite build time via the
-* `@mdx-js/rollup` plugin (see `createMdxPlugin` in `core/adapters.ts`), which
+* `@mdx-js/rollup` plugins (see `createMarkdownPlugin` and `createMdxPlugin`
+* in `core/adapters.ts`), which
 * runs the full remark + rehype pipeline. Re-running it here, during route
 * discovery (Phase 3), would compile every `.mdx` file twice and invoke Shiki
 * once per file per `engine.refresh()` — see ARCHITECTURE.md §2.2 which states
@@ -283,6 +217,11 @@ function kebabToTitle(str) {
 function parseMdxTree(content) {
 	return remark.parse(content);
 }
+async function compileRouteDiagnostic(content, filePath, baseDir) {
+	if (extname(filePath).toLowerCase() !== ".mdx") return void 0;
+	const result = await compileMdxContent(content, filePath, baseDir);
+	return result.ok ? void 0 : result.diagnostic;
+}
 /** 从内容中提取第一个 H1 标题 */
 function extractH1(content) {
 	const tree = parseMdxTree(content);
@@ -308,12 +247,12 @@ function extractMdxSections(content) {
 	return sections;
 }
 function navigationSections(sections) {
-	return sections.map((s) => ({
-		id: s.id,
-		title: s.title,
-		level: s.level,
-		badge: s.badge,
-		tags: s.tags
+	return sections.map((section) => ({
+		id: section.id,
+		title: section.title,
+		level: section.level,
+		badge: section.badge,
+		tags: section.tags
 	}));
 }
 function normalizePath(path) {
@@ -377,7 +316,7 @@ async function findContentRoutes(dir, base = dir, options = {}) {
 				frontmatter,
 				content
 			};
-			const mdxResult = await compileMdxContent(page.content, fullPath, base);
+			const diagnostic = await compileRouteDiagnostic(page.content, fullPath, base);
 			let title = typeof page.frontmatter.title === "string" ? page.frontmatter.title : "";
 			if (!title) {
 				const lastPart = pathParts[pathParts.length - 1] ?? "";
@@ -385,17 +324,21 @@ async function findContentRoutes(dir, base = dir, options = {}) {
 			}
 			routes.push({
 				kind: "mdx",
-				title,
 				path: cleanPath,
 				basePath: cleanPath,
-				filePath: fullPath,
-				virtualModuleId: "virtual:clarify-page/" + relativePath.replace(/\.mdx?$/, "").replace(/\/+/g, "/"),
-				description: typeof page.frontmatter.description === "string" ? page.frontmatter.description : void 0,
-				keywords: frontmatterKeywords(page.frontmatter),
-				frontmatter: page.frontmatter,
-				content: page.content,
-				sections: extractMdxSections(page.content),
-				diagnostic: mdxResult.ok ? void 0 : mdxResult.diagnostic
+				meta: {
+					title,
+					description: typeof page.frontmatter.description === "string" ? page.frontmatter.description : void 0,
+					keywords: frontmatterKeywords(page.frontmatter),
+					sections: extractMdxSections(page.content)
+				},
+				module: { virtualModuleId: "virtual:clarify-page/" + relativePath.replace(/\.mdx?$/, "").replace(/\/+/g, "/") },
+				source: {
+					filePath: fullPath,
+					frontmatter: page.frontmatter,
+					content: page.content
+				},
+				diagnostic
 			});
 		}
 	}
@@ -454,7 +397,7 @@ async function findLocalizedContentRoutes(contentRoot, i18n, options = {}) {
 				path: localizedRoutePath(basePath, locale.code, i18n),
 				basePath,
 				locale: locale.code,
-				virtualModuleId: virtualModuleIdForLocalizedRoute(contentRoot, route.filePath)
+				module: { virtualModuleId: virtualModuleIdForLocalizedRoute(contentRoot, route.source.filePath) }
 			});
 		}
 	}
@@ -490,12 +433,12 @@ function buildNavigation(routes) {
 			if (!node) {
 				node = {
 					path: pathSoFar,
-					title: i === parts.length - 1 ? route.title : kebabToTitle(parts[i]),
+					title: i === parts.length - 1 ? route.meta.title : kebabToTitle(parts[i]),
 					children: []
 				};
 				current.push(node);
 			}
-			if (i === parts.length - 1 && route.sections) node.sections = navigationSections(route.sections);
+			if (i === parts.length - 1 && route.meta.sections) node.sections = navigationSections(route.meta.sections);
 			if (i < parts.length - 1) {
 				node.children = node.children ?? [];
 				current = node.children;
@@ -504,17 +447,22 @@ function buildNavigation(routes) {
 	}
 	return root;
 }
-function resolvePageItem(item) {
-	if (typeof item === "string") return { pageRef: item };
+function routeIntentFromPagesItem(item) {
+	if (typeof item === "string") return {
+		kind: "page",
+		ref: item
+	};
 	if ("openapi" in item) return {
-		openapiRef: item.openapi,
-		openapiTagFilter: item.filter?.tags,
+		kind: "openapi",
+		ref: item.openapi,
+		tagFilter: item.filter?.tags,
 		path: item.path,
 		title: item.title,
 		icon: item.icon
 	};
 	return {
-		pageRef: item.page,
+		kind: "page",
+		ref: item.page,
 		path: item.path,
 		redirect: item.redirect,
 		title: item.title,
@@ -529,25 +477,28 @@ function firstNavigationPath(nodes) {
 	}
 	return "/";
 }
-function collectExplicitPagePathItems(tabs) {
-	const items = [];
+function collectExplicitPagePathIntents(tabs) {
+	const intents = [];
 	for (const tab of tabs ?? []) {
 		if (!tab.pages || tab.pages === "FileTree") continue;
-		for (const group of tab.pages) for (const item of group.pages) if (typeof item !== "string" && "page" in item && item.path) items.push({
-			pageRef: item.page,
-			path: item.path
-		});
+		for (const group of tab.pages) for (const item of group.pages) if (typeof item !== "string" && "page" in item && item.path) {
+			const intent = routeIntentFromPagesItem(item);
+			if (intent.kind === "page" && intent.path) intents.push({
+				...intent,
+				path: intent.path
+			});
+		}
 	}
-	return items;
+	return intents;
 }
 function applyConfiguredPageRoutePaths(routes, tabs, i18n) {
-	const pageItems = collectExplicitPagePathItems(tabs);
-	if (!pageItems.length) return routes;
+	const pageIntents = collectExplicitPagePathIntents(tabs);
+	if (!pageIntents.length) return routes;
 	const additions = [];
 	const existingKeys = new Set(routes.map((route) => `${route.locale ?? ""}:${route.basePath ?? route.path}`));
-	for (const item of pageItems) {
-		const sourceBasePath = routePathFromRef(item.pageRef);
-		const targetBasePath = routePathFromRef(item.pageRef, item.path);
+	for (const intent of pageIntents) {
+		const sourceBasePath = routePathFromRef(intent.ref);
+		const targetBasePath = routePathFromRef(intent.ref, intent.path);
 		if (sourceBasePath === targetBasePath) continue;
 		for (const route of routes) {
 			if (route.kind !== "mdx" || (route.basePath ?? route.path) !== sourceBasePath) continue;
@@ -571,40 +522,42 @@ function buildNavigationFromPagesConfig(routes, config) {
 	return buildNavigationFromConfig(routes, config);
 }
 function buildNavigationFromTabsConfig(routes, tabs) {
-	return { tabs: tabs.map((tab) => {
-		const children = buildNavigationFromPagesConfig(routes, tab.pages);
-		return {
-			type: "tab",
-			path: firstNavigationPath(children),
-			title: resolveLocalizedText(tab.tab, "", "") ?? "",
-			icon: tab.icon,
-			children
-		};
-	}) };
+	return {
+		kind: "tabbed",
+		tabs: tabs.map((tab) => {
+			const children = buildNavigationFromPagesConfig(routes, tab.pages);
+			return {
+				type: "tab",
+				path: firstNavigationPath(children),
+				title: resolveLocalizedText(tab.tab, "", "") ?? "",
+				icon: tab.icon,
+				children
+			};
+		})
+	};
 }
 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, openapiTagFilter, path: explicitPath, redirect, title, icon } = resolvePageItem(item);
-			if (openapiRef) {
-				const path = openAPIPagePathFromRef(openapiRef, openapiTagFilter, explicitPath);
+			const intent = routeIntentFromPagesItem(item);
+			if (intent.kind === "openapi") {
+				const path = openAPIPagePathFromRef(intent.ref, intent.tagFilter, intent.path);
 				const route = routeMap.get(path);
 				return {
 					path,
-					title: resolveLocalizedText(title, "", "") ?? route?.title ?? kebabToTitle(path.split("/").pop() ?? openapiRef),
-					icon,
-					sections: route?.sections ? navigationSections(route.sections) : void 0
+					title: resolveLocalizedText(intent.title, "", "") ?? route?.meta.title ?? kebabToTitle(path.split("/").pop() ?? intent.ref),
+					icon: intent.icon,
+					sections: route?.meta.sections ? navigationSections(route.meta.sections) : void 0
 				};
 			}
-			const ref = pageRef ?? "";
-			const path = routePathFromRef(ref, explicitPath);
+			const path = routePathFromRef(intent.ref, intent.path);
 			const route = routeMap.get(path);
 			return {
-				path: redirect ? normalizePath(redirect) : path,
-				title: resolveLocalizedText(title, "", "") ?? route?.title ?? kebabToTitle(path.split("/").pop() ?? ref),
-				icon,
-				sections: route?.sections ? navigationSections(route.sections) : void 0
+				path: intent.redirect ? normalizePath(intent.redirect) : path,
+				title: resolveLocalizedText(intent.title, "", "") ?? route?.meta.title ?? kebabToTitle(path.split("/").pop() ?? intent.ref),
+				icon: intent.icon,
+				sections: route?.meta.sections ? navigationSections(route.meta.sections) : void 0
 			};
 		});
 		return {
@@ -630,16 +583,15 @@ 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, openapiTagFilter, path: explicitPath, redirect, title, icon } = resolvePageItem(item);
-			const ref = openapiRef ?? pageRef ?? "";
-			const basePath = openapiRef ? openAPIPagePathFromRef(openapiRef, openapiTagFilter, explicitPath) : routePathFromRef(ref, explicitPath);
+			const intent = routeIntentFromPagesItem(item);
+			const basePath = intent.kind === "openapi" ? openAPIPagePathFromRef(intent.ref, intent.tagFilter, intent.path) : routePathFromRef(intent.ref, intent.path);
 			const route = routeMap.get(basePath);
 			const path = route?.path ?? localizedRoutePath(basePath, locale, i18n);
 			return {
-				path: (redirect ? localizedRoutePath(routePathFromRef(redirect), locale, i18n) : void 0) ?? path,
-				title: resolveLocalizedText(title, locale, i18n.defaultLocale) ?? route?.title ?? kebabToTitle(basePath.split("/").pop() ?? ref),
-				icon,
-				sections: route?.sections ? navigationSections(route.sections) : void 0
+				path: (intent.kind === "page" && intent.redirect ? localizedRoutePath(routePathFromRef(intent.redirect), locale, i18n) : void 0) ?? path,
+				title: resolveLocalizedText(intent.title, locale, i18n.defaultLocale) ?? route?.meta.title ?? kebabToTitle(basePath.split("/").pop() ?? intent.ref),
+				icon: intent.icon,
+				sections: route?.meta.sections ? navigationSections(route.meta.sections) : void 0
 			};
 		});
 		return {
@@ -652,10 +604,10 @@ function buildLocalizedNavigationForLocale(routes, config, locale, i18n) {
 }
 function buildLocalizedNavigationFromTabsConfig(routes, tabs, i18n) {
 	if (!i18n) return void 0;
-	const result = {};
+	const locales = {};
 	for (const locale of i18n.locales) {
 		const localeRoutes = routes.filter((route) => route.locale === locale.code);
-		result[locale.code] = { tabs: tabs.map((tab) => {
+		locales[locale.code] = { tabs: tabs.map((tab) => {
 			const children = buildLocalizedNavigationForLocale(localeRoutes, tab.pages, locale.code, i18n);
 			return {
 				type: "tab",
@@ -666,17 +618,20 @@ function buildLocalizedNavigationFromTabsConfig(routes, tabs, i18n) {
 			};
 		}) };
 	}
-	return result;
+	return {
+		kind: "localized-tabbed",
+		locales
+	};
 }
 /** Serialize a ContentRoute into the minimal shape exposed to tooling. */
 function toDevRouteEntry(route) {
 	return {
 		path: route.path,
-		filePath: route.filePath,
+		filePath: route.source.filePath,
 		locale: route.locale,
 		basePath: route.basePath,
 		kind: route.kind,
-		title: route.title
+		title: route.meta.title
 	};
 }
 /**
@@ -690,7 +645,7 @@ function toDevRouteEntry(route) {
 *     or the first match.
 */
 function resolveRouteForFile(filePath, routes, defaultLocale) {
-	const matches = routes.filter((r) => r.filePath === filePath);
+	const matches = routes.filter((r) => r.source.filePath === filePath);
 	if (matches.length === 0) return void 0;
 	if (matches.length === 1) return matches[0];
 	const fileLocale = inferLocaleFromPath(filePath);
@@ -1115,6 +1070,7 @@ var VIRTUAL_CONFIG = "virtual:clarify/config";
 var VIRTUAL_ROUTES = "virtual:clarify/routes";
 var VIRTUAL_SERVER_ROUTES = "virtual:clarify/routes/server";
 var VIRTUAL_OPENAPI = "virtual:clarify/openapi";
+var VIRTUAL_OPENAPI_SERVER = "virtual:clarify/openapi/server";
 var VIRTUAL_SLOTS = "virtual:clarify/slots";
 var VIRTUAL_SLOT = "virtual:clarify/slot";
 var VIRTUAL_CLIENT_ENTRY = "virtual:clarify/entry-client";
@@ -1135,6 +1091,7 @@ var FIXED_VIRTUAL_IDS = [
 	VIRTUAL_ROUTES,
 	VIRTUAL_SERVER_ROUTES,
 	VIRTUAL_OPENAPI,
+	VIRTUAL_OPENAPI_SERVER,
 	VIRTUAL_SLOTS,
 	VIRTUAL_SLOT
 ];
@@ -1151,8 +1108,8 @@ function resolveVirtualModuleId(id, modules, routes) {
 	for (const virtualId of FIXED_VIRTUAL_IDS) if (id === virtualId || id === resolveVirtualId(virtualId)) return resolveVirtualId(virtualId);
 	const moduleId = stripVirtualPrefix(id);
 	if (modules.has(moduleId)) return resolveVirtualId(moduleId);
-	const route = routes.find((route) => route.virtualModuleId === id || route.virtualModuleId === moduleId);
-	if (route) return resolveVirtualId(route.virtualModuleId);
+	const route = routes.find((route) => route.module.virtualModuleId === id || route.module.virtualModuleId === moduleId);
+	if (route) return resolveVirtualId(route.module.virtualModuleId);
 	return null;
 }
 function generateConfigModule(projectConfig, buildOptions, version) {
@@ -1166,38 +1123,38 @@ function generateConfigModule(projectConfig, buildOptions, version) {
 function moduleSpecifier(value) {
 	return JSON.stringify(value);
 }
-function routeToRuntimeObject(route, component, mode) {
-	const obj = {
+function routeToRuntimeManifestEntry(route, component, mode) {
+	const entry = {
 		path: route.path,
-		title: route.title,
+		title: route.meta.title,
 		component,
 		kind: route.kind
 	};
-	if (mode === "client") obj.lazy = true;
-	if (route.basePath) obj.basePath = route.basePath;
-	if (route.locale) obj.locale = route.locale;
-	if (route.isFallback) obj.isFallback = true;
-	if (route.isBareAlias) obj.isBareAlias = true;
-	if (route.alternates) obj.alternates = route.alternates;
-	if (route.description) obj.description = route.description;
-	if (route.keywords?.length) obj.keywords = route.keywords;
-	if (route.contentArtifactUrl) obj.contentArtifactUrl = route.contentArtifactUrl;
-	if (route.sourceUrl) obj.sourceUrl = route.sourceUrl;
-	if (route.sections?.length) obj.sections = route.sections.map((s) => ({
-		id: s.id,
-		title: s.title,
-		level: s.level,
-		badge: s.badge,
-		tags: s.tags
+	if (mode === "client") entry.lazy = true;
+	if (route.basePath) entry.basePath = route.basePath;
+	if (route.locale) entry.locale = route.locale;
+	if (route.isFallback) entry.isFallback = true;
+	if (route.isBareAlias) entry.isBareAlias = true;
+	if (route.alternates) entry.alternates = route.alternates;
+	if (route.meta.description) entry.description = route.meta.description;
+	if (route.meta.keywords?.length) entry.keywords = route.meta.keywords;
+	if (route.artifacts?.contentArtifactUrl) entry.contentArtifactUrl = route.artifacts.contentArtifactUrl;
+	if (route.source?.sourceEditUrl) entry.sourceEditUrl = route.source.sourceEditUrl;
+	if (route.meta.sections?.length) entry.sections = route.meta.sections.map((section) => ({
+		id: section.id,
+		title: section.title,
+		level: section.level,
+		badge: section.badge,
+		tags: section.tags
 	}));
-	return obj;
+	return entry;
 }
 function generateRoutesModule(routes, navigation, mode = "client") {
-	return `${mode === "server" ? routes.map((r, i) => `import Page${i} from ${moduleSpecifier(r.virtualModuleId)};`).join("\n") : `import { createContentDiagnosticComponent } from '@clarify-labs/renderer';`}\n\nexport const routes = [\n${routes.map((r, i) => {
-		const component = mode === "server" ? `Page${i}` : `() => import(${moduleSpecifier(r.virtualModuleId)}).catch((error) => Promise.resolve({ default: createContentDiagnosticComponent({ kind: 'route-load', title: 'This page could not be loaded', message: error instanceof Error ? error.message : String(error), details: error instanceof Error ? error.stack : undefined }) }))`;
+	return `${mode === "server" ? routes.map((r, i) => `import Page${i} from ${moduleSpecifier(r.module.virtualModuleId)};`).join("\n") : `import { createContentDiagnosticComponent } from '@clarify-labs/renderer';`}\n\nexport const routes = [\n${routes.map((r, i) => {
+		const component = mode === "server" ? `Page${i}` : `() => import(${moduleSpecifier(r.module.virtualModuleId)}).catch((error) => Promise.resolve({ default: createContentDiagnosticComponent({ kind: 'route-load', title: 'This page could not be loaded', message: error instanceof Error ? error.message : String(error), details: error instanceof Error ? error.stack : undefined }) }))`;
 		const placeholder = `__COMPONENT_${i}__`;
-		const obj = routeToRuntimeObject(r, placeholder, mode);
-		return `  ${JSON.stringify(obj, null, 0).replace(`"${placeholder}"`, component).replace(/"([A-Za-z_$][\w$]*)":/g, "$1: ")}`;
+		const manifestEntry = routeToRuntimeManifestEntry(r, placeholder, mode);
+		return `  ${JSON.stringify(manifestEntry, null, 0).replace(`"${placeholder}"`, component).replace(/"([A-Za-z_$][\w$]*)":/g, "$1: ")}`;
 	}).join(",\n")}\n];\n\nexport const navigation = ${JSON.stringify(navigation, null, 2)};\n`;
 }
 function createClientEntryModule(options = {}) {
@@ -1206,9 +1163,15 @@ import '@clarify-labs/renderer/style.css';
 import { render } from '@clarify-labs/renderer/client';
 import { routes, navigation } from '${VIRTUAL_ROUTES}';
 import { config } from '${VIRTUAL_CONFIG}';
-import { openApis } from '${VIRTUAL_OPENAPI}';
+import { openApiSpecs } from '${VIRTUAL_OPENAPI}';
 import { runtimeSlots } from '${VIRTUAL_SLOTS}';
-render({ config, routes, navigation, openApis, runtimeSlots, themeEditor: ${JSON.stringify(options.themeEditor ?? false)} });`;
+const renderOptions = { config, routes, navigation, openApiSpecs, runtimeSlots, themeEditor: ${JSON.stringify(options.themeEditor ?? false)} };
+render(renderOptions);
+if (import.meta.hot) {
+  import.meta.hot.accept('${VIRTUAL_ROUTES}', (mod) => {
+    render({ ...renderOptions, routes: mod.routes, navigation: mod.navigation });
+  });
+}`;
 }
 /**
 * Collect every plugin's `slots` declarations into a single runtime registry
@@ -1237,7 +1200,7 @@ function createRuntimeSlotsModule(plugins = [], root = process.cwd()) {
 		}
 		if (!slot.component.startsWith("/")) throw new Error(`[clarify] Plugin "${plugin}" slot "${slot.name}" has an invalid component path "${slot.component}". Component paths must start with "/" to reference the project root.`);
 		const componentPath = root + slot.component;
-		const entry = `{ plugin: ${JSON.stringify(plugin)}, component: () => import(${moduleSpecifier(componentPath)}) }`;
+		const entry = `{ plugin: ${JSON.stringify(plugin)}, loadComponent: () => import(${moduleSpecifier(componentPath)}) }`;
 		const list = grouped.get(slot.name) ?? [];
 		list.push(entry);
 		grouped.set(slot.name, list);
@@ -1266,18 +1229,34 @@ function buildVirtualModules(args) {
 	modules.set(VIRTUAL_ROUTES, generateRoutesModule(args.routes, args.navigation, "client"));
 	modules.set(VIRTUAL_SERVER_ROUTES, generateRoutesModule(args.routes, args.navigation, "server"));
 	modules.set(VIRTUAL_SLOTS, createRuntimeSlotsModule(allPlugins, args.generateOptions.projectRoot));
-	modules.set(VIRTUAL_OPENAPI, "export const openApis = {};");
+	modules.set(VIRTUAL_OPENAPI, "export const openApiSpecs = {};");
 	modules.set(VIRTUAL_SLOT, "export { useSlot } from '@clarify-labs/renderer';\n");
 	modules.set(VIRTUAL_CLIENT_ENTRY, clientEntryModule);
 	modules.set(RESOLVED_CLIENT_ENTRY, clientEntryModule);
 	for (const route of args.routes) {
-		const moduleContent = route.diagnostic ? generateMdxErrorModule(route.diagnostic) : `export { default } from ${moduleSpecifier(route.filePath)};`;
-		modules.set(route.virtualModuleId, moduleContent);
+		const moduleContent = route.diagnostic ? generateMdxErrorModule(route.diagnostic) : `export { default } from ${moduleSpecifier(route.source.filePath)};`;
+		modules.set(route.module.virtualModuleId, moduleContent);
 	}
 	return modules;
 }
 //#endregion
 //#region source/core/adapters.ts
+function routeStructure(route) {
+	const { content: _content, ...source } = route.source;
+	return {
+		...route,
+		source
+	};
+}
+function createDevStructureSnapshot(routes, navigation) {
+	return {
+		routes: JSON.stringify(routes.map(routeStructure)),
+		navigation: JSON.stringify(navigation)
+	};
+}
+function hasDevStructureChanged(before, after) {
+	return before.routes !== after.routes || before.navigation !== after.navigation;
+}
 function invalidateVirtualModules(engine, server) {
 	for (const id of engine.modules.keys()) {
 		const moduleNode = server.moduleGraph.getModuleById(resolveVirtualId(id));
@@ -1285,20 +1264,22 @@ function invalidateVirtualModules(engine, server) {
 	}
 }
 async function refreshDevServer(engine, server) {
+	const before = createDevStructureSnapshot(engine.routes, engine.navigation);
 	await engine.refresh();
 	invalidateVirtualModules(engine, server);
+	return hasDevStructureChanged(before, createDevStructureSnapshot(engine.routes, engine.navigation));
 }
-function createNormalizedMdxContentPlugin(engine) {
+function createNormalizedContentPlugin(engine) {
 	return {
-		name: "clarify:normalized-mdx-content",
+		name: "clarify:normalized-content",
 		enforce: "pre",
 		transform(_code, id) {
 			if (!/\.mdx?(?:\?|$)/.test(id)) return null;
 			const filePath = id.replace(/\?.*$/, "");
-			const route = engine.routes.find((route) => route.kind === "mdx" && route.filePath === filePath);
-			if (!route || route.content === void 0) return null;
+			const route = engine.routes.find((route) => route.kind === "mdx" && route.source.filePath === filePath);
+			if (!route || route.source.content === void 0) return null;
 			return {
-				code: route.content,
+				code: route.source.content,
 				map: null
 			};
 		}
@@ -1306,14 +1287,26 @@ function createNormalizedMdxContentPlugin(engine) {
 }
 function createMdxPlugin() {
 	return mdxPlugin({
-		include: ["**/*.{md,mdx}"],
+		include: ["**/*.mdx"],
+		format: "mdx",
 		jsxImportSource: "react",
 		providerImportSource: "@clarify-labs/renderer",
 		remarkPlugins,
 		rehypePlugins
 	});
 }
-function createClarifyViteCorePlugin(engine, normalizedMdxContentPlugin, mdx) {
+function createMarkdownPlugin() {
+	return mdxPlugin({
+		include: ["**/*.md"],
+		format: "md",
+		jsxImportSource: "react",
+		providerImportSource: "@clarify-labs/renderer",
+		remarkPlugins,
+		remarkRehypeOptions: { allowDangerousHtml: true },
+		rehypePlugins: [rehypeRaw, ...rehypePlugins]
+	});
+}
+function createClarifyViteCorePlugin(engine, normalizedContentPlugin, markdown, mdx) {
 	let viteConfig;
 	return {
 		name: "clarify:core",
@@ -1352,8 +1345,13 @@ function createClarifyViteCorePlugin(engine, normalizedMdxContentPlugin, mdx) {
 			}
 			const relativeContentFile = relative(engine.contentRoot, changedFile);
 			if (!(relativeContentFile && !relativeContentFile.startsWith("..") && !isAbsolute(relativeContentFile)) || !engine.hasContentRouteForFile(changedFile)) return;
-			await refreshDevServer(engine, ctx.server);
-			return [];
+			if (await refreshDevServer(engine, ctx.server)) {
+				const routesModule = ctx.server.moduleGraph.getModuleById(resolveVirtualId(VIRTUAL_ROUTES));
+				if (routesModule) return [...ctx.modules, routesModule];
+				ctx.server.ws.send({ type: "full-reload" });
+				return [];
+			}
+			return ctx.modules;
 		},
 		resolveId(id) {
 			return resolveVirtualModuleId(id, engine.modules, engine.routes);
@@ -1364,18 +1362,6 @@ function createClarifyViteCorePlugin(engine, normalizedMdxContentPlugin, mdx) {
 		async configureServer(server) {
 			server.watcher.add(engine.contentRoot);
 			if (engine.configFilePath) server.watcher.add(engine.configFilePath);
-			let reloadQueued = false;
-			const invalidateAndReload = () => {
-				if (reloadQueued) return;
-				reloadQueued = true;
-				queueMicrotask(() => {
-					reloadQueued = false;
-					invalidateVirtualModules(engine, server);
-					server.ws.send({ type: "full-reload" });
-				});
-			};
-			engine.ctx.onRoutesChange(invalidateAndReload);
-			engine.ctx.onNavigationChange(invalidateAndReload);
 			server.middlewares.use((req, res, next) => {
 				if (req.url === "/dev/query-preview-route" && req.method === "POST") return handleDevRouteRequest(req, res, engine.routes, engine.runtimeContext());
 				if (req.url === "/dev/project-info" && (req.method === "GET" || req.method === "HEAD")) return handleProjectInfoRequest(req, res, engine.runtimeContext());
@@ -1385,7 +1371,7 @@ function createClarifyViteCorePlugin(engine, normalizedMdxContentPlugin, mdx) {
 				const changedFile = isAbsolute(filePath) ? filePath : join(engine.root, filePath);
 				const relativeContentFile = relative(engine.contentRoot, changedFile);
 				if (!(relativeContentFile && !relativeContentFile.startsWith("..") && !isAbsolute(relativeContentFile))) return;
-				await refreshDevServer(engine, server);
+				if (await refreshDevServer(engine, server)) server.ws.send({ type: "full-reload" });
 			};
 			server.watcher.on("add", handleContentTreeChange);
 			server.watcher.on("unlink", handleContentTreeChange);
@@ -1422,7 +1408,8 @@ function createClarifyViteCorePlugin(engine, normalizedMdxContentPlugin, mdx) {
 				outputDirectory: viteConfig.build.outDir,
 				ssrPlugins: [
 					engine.createSSGVirtualPlugin(),
-					normalizedMdxContentPlugin,
+					normalizedContentPlugin,
+					markdown,
 					mdx
 				]
 			});
@@ -1439,20 +1426,22 @@ function createClarifyViteCorePlugin(engine, normalizedMdxContentPlugin, mdx) {
 * site itself - it only bridges Vite lifecycle hooks to the engine.
 */
 function createViteAdapter(engine) {
-	const normalizedMdxContentPlugin = createNormalizedMdxContentPlugin(engine);
+	const normalizedContentPlugin = createNormalizedContentPlugin(engine);
+	const markdown = createMarkdownPlugin();
 	const mdx = createMdxPlugin();
 	const tailwind = tailwindcss();
 	return [
 		...react(),
 		...Array.isArray(tailwind) ? tailwind : [tailwind],
-		normalizedMdxContentPlugin,
-		createClarifyViteCorePlugin(engine, normalizedMdxContentPlugin, mdx),
+		normalizedContentPlugin,
+		createClarifyViteCorePlugin(engine, normalizedContentPlugin, markdown, mdx),
+		markdown,
 		mdx
 	];
 }
 var cliPackageVersion = {
 	name: "@clarify-labs/cli",
-	version: "0.10.0",
+	version: "0.10.2",
 	license: "AGPL-3.0-only",
 	type: "module",
 	repository: {
@@ -1493,6 +1482,7 @@ var cliPackageVersion = {
 		"@clarify-labs/templates": "workspace:*",
 		"@mdx-js/mdx": "^3.1.1",
 		"@mdx-js/rollup": "^3.1.1",
+		"@shikijs/rehype": "^4.3.0",
 		"@tailwindcss/vite": "^4.3.2",
 		"@vitejs/plugin-react": "^6.0.3",
 		"cac": "^7.0.0",
@@ -1507,6 +1497,8 @@ var cliPackageVersion = {
 		"react-router": "^7.0.0",
 		"react-router-dom": "^7.0.0",
 		"react-zoom-pan-pinch": "^4.0.3",
+		"rehype-raw": "^7.0.0",
+		"rehype-slug": "^6.0.0",
 		"remark": "^15.0.1",
 		"remark-gfm": "^4.0.1",
 		"shiki": "4.3.0",
@@ -1558,11 +1550,14 @@ function routeToOpenAPIArtifactUrl(routePath) {
 	return `${routePath === "/" ? "/index" : routePath.replace(/\/$/, "")}.openapi.json`;
 }
 function attachContentArtifactUrls(routes) {
-	for (const route of routes) route.contentArtifactUrl = route.kind === "openapi" ? routeToOpenAPIArtifactUrl(route.path) : routeToMarkdownArtifactUrl(route.path);
+	for (const route of routes) route.artifacts = {
+		...route.artifacts,
+		contentArtifactUrl: route.kind === "openapi" ? routeToOpenAPIArtifactUrl(route.path) : routeToMarkdownArtifactUrl(route.path)
+	};
 }
 function readRouteContent(route) {
-	if (route.content !== void 0) return route.content;
-	throw new Error(`Route content is missing from route context: ${route.filePath}`);
+	if (route.source.content !== void 0) return route.source.content;
+	throw new Error(`Route content is missing from route context: ${route.source.filePath}`);
 }
 function readRouteArtifactContent(route) {
 	const content = readRouteContent(route);
@@ -1572,16 +1567,17 @@ function isLlmsTxtRoute(route) {
 	return !route.path.split("/").includes("404");
 }
 function llmsTxtDescription(route) {
-	if (route.description) return route.description;
-	const sections = route.sections?.filter((section) => section.level === 2).slice(0, 3).map((section) => section.title);
+	if (route.meta.description) return route.meta.description;
+	const sections = route.meta.sections?.filter((section) => section.level === 2).slice(0, 3).map((section) => section.title);
 	if (sections?.length) return `Covers ${sections.join(", ")}.`;
-	if (route.keywords?.length) return `Related topics: ${route.keywords.join(", ")}.`;
+	if (route.meta.keywords?.length) return `Related topics: ${route.meta.keywords.join(", ")}.`;
 	if (route.kind === "openapi") return "OpenAPI artifact for machine-readable API reference data.";
 }
 function llmsTxtListItem(route, basePath) {
-	if (!route.contentArtifactUrl) return void 0;
+	const contentArtifactUrl = route.artifacts?.contentArtifactUrl;
+	if (!contentArtifactUrl) return void 0;
 	const description = llmsTxtDescription(route);
-	return description ? `- [${route.title}](${basePath}${route.contentArtifactUrl}): ${description}` : `- [${route.title}](${basePath}${route.contentArtifactUrl})`;
+	return description ? `- [${route.meta.title}](${basePath}${contentArtifactUrl}): ${description}` : `- [${route.meta.title}](${basePath}${contentArtifactUrl})`;
 }
 function llmsTxtLocaleLabel(locale, projectConfig) {
 	return projectConfig.i18n?.locales.find((item) => item.code === locale)?.label ?? locale;
@@ -1598,7 +1594,7 @@ function groupLlmsTxtRoutesByLocale(routes, projectConfig) {
 	const routesBySource = /* @__PURE__ */ new Map();
 	const defaultLocale = projectConfig.i18n?.defaultLocale;
 	for (const route of routes) {
-		const sourceKey = `${route.locale ?? defaultLocale ?? "default"}:${route.basePath ?? route.contentArtifactUrl ?? route.path}`;
+		const sourceKey = `${route.locale ?? defaultLocale ?? "default"}:${route.basePath ?? route.artifacts?.contentArtifactUrl ?? route.path}`;
 		const previousRoute = routesBySource.get(sourceKey);
 		if (!previousRoute || previousRoute.locale && !route.locale) routesBySource.set(sourceKey, route);
 	}
@@ -1667,9 +1663,9 @@ function serveContentArtifacts(req, res, projectConfig, routes) {
 	}
 	if (contentPath.endsWith(".openapi.yaml")) {
 		const jsonPath = contentPath.replace(/\.yaml$/, ".json");
-		const route = routes.find((r) => r.contentArtifactUrl === jsonPath);
-		if (route?.kind === "openapi" && route.content) {
-			const spec = JSON.parse(route.content);
+		const route = routes.find((route) => route.artifacts?.contentArtifactUrl === jsonPath);
+		if (route?.kind === "openapi" && route.source.content) {
+			const spec = JSON.parse(route.source.content);
 			res.statusCode = 200;
 			res.setHeader("Content-Type", "text/yaml; charset=utf-8");
 			res.end(stringify(spec, { lineWidth: 0 }), "utf8");
@@ -1677,7 +1673,7 @@ function serveContentArtifacts(req, res, projectConfig, routes) {
 		}
 		return false;
 	}
-	const route = routes.find((route) => route.contentArtifactUrl === contentPath);
+	const route = routes.find((route) => route.artifacts?.contentArtifactUrl === contentPath);
 	if (!route) return false;
 	res.statusCode = 200;
 	res.setHeader("Content-Type", resolveContentArtifactType(route));
@@ -1703,14 +1699,15 @@ function createContentArtifactsPlugin() {
 			"build:assets": (ctx) => {
 				const assets = [];
 				for (const route of ctx.routes) {
-					if (!route.contentArtifactUrl) continue;
+					const contentArtifactUrl = route.artifacts?.contentArtifactUrl;
+					if (!contentArtifactUrl) continue;
 					assets.push({
-						fileName: route.contentArtifactUrl.replace(/^\//, ""),
+						fileName: contentArtifactUrl.replace(/^\//, ""),
 						source: readRouteArtifactContent(route)
 					});
-					if (route.kind === "openapi" && route.content) {
-						const yamlFileName = route.contentArtifactUrl.replace(/\.json$/, ".yaml");
-						const spec = JSON.parse(route.content);
+					if (route.kind === "openapi" && route.source.content) {
+						const yamlFileName = contentArtifactUrl.replace(/\.json$/, ".yaml");
+						const spec = JSON.parse(route.source.content);
 						assets.push({
 							fileName: yamlFileName.replace(/^\//, ""),
 							source: stringify(spec, { lineWidth: 0 })
@@ -1796,6 +1793,7 @@ var OPENAPI_HTTP_METHODS = [
 	"patch",
 	"trace"
 ];
+var CLARIFY_OPENAPI_SECTION_ID_EXTENSION = "x-clarify-section-id";
 function errorMessage(error) {
 	return error instanceof Error ? error.message : String(error);
 }
@@ -1822,10 +1820,10 @@ function findOpenAPIRoutes(dir, base = dir) {
 		routes.push({
 			path: cleanPath,
 			basePath: cleanPath,
-			filePath: fullPath,
-			virtualModuleId: virtualModuleIdFromRef(ref),
-			title: kebabToTitle(cleanPath.split("/").pop() ?? "API"),
-			kind: "openapi"
+			kind: "openapi",
+			meta: { title: kebabToTitle(cleanPath.split("/").pop() ?? "API") },
+			module: { virtualModuleId: virtualModuleIdFromRef(ref) },
+			source: { filePath: fullPath }
 		});
 	}
 	return routes;
@@ -1834,36 +1832,80 @@ function operationMatchesTags(operationTags, filterTags) {
 	if (!filterTags?.length) return true;
 	return operationTags?.some((tag) => filterTags.includes(tag)) ?? false;
 }
+function filterPathItemsByTags(items, tags) {
+	const filteredItems = {};
+	for (const path of Object.keys(items)) {
+		const pathItem = items[path];
+		if (!pathItem) continue;
+		if (OPENAPI_HTTP_METHODS.map((method) => pathItem[method]).some((op) => op && typeof op === "object" && operationMatchesTags(op.tags, tags))) filteredItems[path] = pathItem;
+	}
+	return filteredItems;
+}
+function createOperationSectionId(operation, method, path, kind) {
+	return (typeof operation.operationId === "string" ? operation.operationId.trim() : "") || slug(`${kind === "webhook" ? "webhook " : ""}${method.toLowerCase()} ${path}`);
+}
+function operationSectionId(operation) {
+	const sectionId = operation[CLARIFY_OPENAPI_SECTION_ID_EXTENSION];
+	return typeof sectionId === "string" ? sectionId : "";
+}
+function normalizeOpenAPISpecSectionIds(spec) {
+	const items = [...Object.entries(spec.paths ?? {}).map(([path, pathItem]) => ({
+		path,
+		pathItem,
+		kind: "path"
+	})), ...Object.entries(spec.webhooks ?? {}).map(([path, pathItem]) => ({
+		path,
+		pathItem,
+		kind: "webhook"
+	}))];
+	for (const { path, pathItem, kind } of items) {
+		if (!pathItem || typeof pathItem !== "object") continue;
+		const operations = pathItem;
+		for (const method of OPENAPI_HTTP_METHODS) {
+			const op = operations[method];
+			if (!op || typeof op !== "object") continue;
+			op[CLARIFY_OPENAPI_SECTION_ID_EXTENSION] = createOperationSectionId(op, method, path, kind);
+		}
+	}
+	return spec;
+}
 /** Filter an OpenAPI spec to only include paths that have at least one operation matching the given tags. */
 function filterSpecByTags(spec, tags) {
-	const filteredPaths = {};
 	const paths = spec.paths ?? {};
-	for (const path of Object.keys(paths)) {
-		const pathItem = paths[path];
-		if (!pathItem) continue;
-		if (Object.values(pathItem).some((op) => op && typeof op === "object" && operationMatchesTags(op.tags, tags))) filteredPaths[path] = pathItem;
-	}
+	const webhooks = spec.webhooks ?? {};
 	return {
 		...spec,
-		paths: filteredPaths
+		paths: filterPathItemsByTags(paths, tags),
+		webhooks: filterPathItemsByTags(webhooks, tags)
 	};
 }
 /** Extract endpoint operations from an OpenAPI spec as page sections. */
 function extractOpenAPISections(spec, filterTags) {
+	normalizeOpenAPISpecSectionIds(spec);
 	const sections = [];
-	const paths = spec.paths ?? {};
-	for (const [path, pathItem] of Object.entries(paths)) {
+	const items = [...Object.entries(spec.paths ?? {}).map(([path, pathItem]) => ({
+		path,
+		pathItem,
+		kind: "path"
+	})), ...Object.entries(spec.webhooks ?? {}).map(([path, pathItem]) => ({
+		path,
+		pathItem,
+		kind: "webhook"
+	}))];
+	for (const { path, pathItem, kind } of items) {
 		if (!pathItem) continue;
+		const operations = pathItem;
 		for (const method of OPENAPI_HTTP_METHODS) {
-			const op = pathItem[method];
-			if (!op || !operationMatchesTags(op.tags, filterTags)) continue;
-			const title = op.summary ?? `${method.toUpperCase()} ${path}`;
+			const op = operations[method];
+			const tags = Array.isArray(op?.tags) ? op.tags : void 0;
+			if (!op || !operationMatchesTags(tags, filterTags)) continue;
+			const title = typeof op.summary === "string" ? op.summary : `${method.toUpperCase()} ${path}`;
 			sections.push({
-				id: slug(`${method} ${path}`),
+				id: operationSectionId(op),
 				title,
 				level: 2,
-				badge: method.toUpperCase(),
-				tags: op.tags
+				badge: kind === "webhook" ? "WEBHOOK" : method.toUpperCase(),
+				tags
 			});
 		}
 	}
@@ -1905,12 +1947,16 @@ async function readOpenAPISpec(filePath, contentProcessor) {
 //#endregion
 //#region source/plugins/openapi/virtual-modules.ts
 var openApiRegistryModuleId = VIRTUAL_OPENAPI;
+var openApiServerRegistryModuleId = VIRTUAL_OPENAPI_SERVER;
 var OPENAPI_SPEC_PREFIX = "virtual:clarify/openapi-spec/";
 function specVirtualModuleId(specKey) {
 	return `${OPENAPI_SPEC_PREFIX}${specKey}`;
 }
-function generateOpenAPIRegistryModule(openApis) {
-	return `export const openApis = ${JSON.stringify(openApis)};`;
+function generateOpenAPIRegistryModule(openApiSpecs) {
+	return `export const openApiSpecs = {\n${Object.entries(openApiSpecs).map(([key, moduleId]) => `  ${JSON.stringify(key)}: () => import(${JSON.stringify(moduleId)}),`).join("\n")}\n};`;
+}
+function generateOpenAPIServerRegistryModule(openApiSpecs) {
+	return `export const openApiSpecs = ${JSON.stringify(openApiSpecs)};`;
 }
 /** Generate a virtual module that exports a single spec as default. */
 function generateOpenAPISpecModule(spec) {
@@ -1918,13 +1964,11 @@ function generateOpenAPISpecModule(spec) {
 }
 function generateOpenAPIPageModule(opts) {
 	return `import { createOpenApiRouteComponent } from '@clarify-labs/renderer';
+import spec from ${JSON.stringify(opts.specModuleId)};
 
-export const routeData = ${JSON.stringify({
-		spec: opts.spec,
-		tagFilter: opts.tagFilter
-	})};
+export const routeData = {};
 
-export default createOpenApiRouteComponent(routeData);
+export default createOpenApiRouteComponent({ ...routeData, spec });
 `;
 }
 function generateOpenAPIErrorModule(diagnostic) {
@@ -1943,115 +1987,212 @@ export default createContentDiagnosticComponent(contentDiagnostic);
 }
 //#endregion
 //#region source/plugins/openapi/index.ts
-function collectOpenAPIPageItems(config) {
-	const items = [];
+function collectOpenAPIPageIntents(config) {
+	const intents = [];
 	function visitPages(pages) {
 		if (!pages || pages === "FileTree") return;
-		for (const group of pages) for (const item of group.pages) if (typeof item !== "string" && "openapi" in item && (item.path || item.filter?.tags?.length)) items.push(item);
+		for (const group of pages) for (const item of group.pages) {
+			const intent = routeIntentFromPagesItem(item);
+			if (intent.kind === "openapi" && (intent.path || intent.tagFilter?.length)) intents.push(intent);
+		}
 	}
 	for (const tab of config.tabs ?? []) visitPages(tab.pages);
-	return items;
+	return intents;
 }
 function virtualModuleIdFromPath(path) {
 	return `virtual:clarify-page/${path.replace(/^\/+/, "") || "index"}`;
 }
+function cloneOpenAPIRoute(route, overrides = {}) {
+	return {
+		...route,
+		meta: {
+			...route.meta,
+			sections: route.meta.sections ? [...route.meta.sections] : void 0
+		},
+		module: { ...route.module },
+		source: { ...route.source },
+		openapi: route.openapi ? {
+			...route.openapi,
+			tagFilter: route.openapi.tagFilter ? [...route.openapi.tagFilter] : void 0
+		} : void 0,
+		alternates: route.alternates ? { ...route.alternates } : void 0,
+		...overrides
+	};
+}
+function findOpenAPIRoutesForContentRoot(contentRoot, i18n) {
+	if (!i18n) return findOpenAPIRoutes(contentRoot);
+	const localizedRoutes = [];
+	for (const locale of i18n.locales) {
+		const localeRoot = join(contentRoot, locale.code);
+		for (const route of findOpenAPIRoutes(localeRoot, localeRoot)) {
+			const basePath = route.basePath ?? route.path;
+			const path = localizedRoutePath(basePath, locale.code, i18n);
+			localizedRoutes.push({
+				...route,
+				path,
+				basePath,
+				locale: locale.code,
+				module: { virtualModuleId: virtualModuleIdFromPath(path) }
+			});
+		}
+	}
+	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;
+				const path = localizedRoutePath(basePath, locale.code, i18n);
+				localizedRoutes.push(cloneOpenAPIRoute(sourceRoute, {
+					path,
+					locale: locale.code,
+					module: { virtualModuleId: virtualModuleIdFromPath(path) },
+					isFallback: true
+				}));
+			}
+		}
+	}
+	return localizedRoutes;
+}
 function createConfiguredOpenAPIRoutes(routes, config) {
-	const pageItems = collectOpenAPIPageItems(config);
-	if (!pageItems.length) return routes;
+	const openAPIIntents = collectOpenAPIPageIntents(config);
+	if (!openAPIIntents.length) return routes;
 	const additions = [];
 	const existingKeys = new Set(routes.map((route) => `${route.locale ?? ""}:${route.basePath ?? route.path}`));
-	for (const item of pageItems) {
-		const tagFilter = item.filter?.tags?.filter(Boolean);
-		const sourceBasePath = openAPIPagePathFromRef(item.openapi);
-		const targetBasePath = openAPIPagePathFromRef(item.openapi, tagFilter, item.path);
+	for (const intent of openAPIIntents) {
+		const tagFilter = intent.tagFilter?.filter(Boolean);
+		const sourceBasePath = openAPIPagePathFromRef(intent.ref);
+		const targetBasePath = openAPIPagePathFromRef(intent.ref, tagFilter, intent.path);
 		if (sourceBasePath === targetBasePath && !tagFilter?.length) continue;
 		for (const route of routes) {
 			if (route.kind !== "openapi" || (route.basePath ?? route.path) !== sourceBasePath) continue;
 			const key = `${route.locale ?? ""}:${targetBasePath}`;
 			if (existingKeys.has(key)) continue;
 			existingKeys.add(key);
-			additions.push({
-				...route,
-				path: route.locale && config.i18n ? localizedRoutePath(targetBasePath, route.locale, config.i18n) : targetBasePath,
+			const path = route.locale && config.i18n ? localizedRoutePath(targetBasePath, route.locale, config.i18n) : targetBasePath;
+			additions.push(cloneOpenAPIRoute(route, {
+				path,
 				basePath: targetBasePath,
-				title: route.title,
-				virtualModuleId: virtualModuleIdFromPath(targetBasePath),
-				openapiTagFilter: tagFilter?.length ? tagFilter : void 0
-			});
+				module: { virtualModuleId: virtualModuleIdFromPath(path) },
+				openapi: {
+					...route.openapi,
+					tagFilter: tagFilter?.length ? tagFilter : void 0
+				}
+			}));
 		}
 	}
 	const nextRoutes = [...routes, ...additions];
-	return config.i18n ? nextRoutes.map((route) => withAlternates(route, nextRoutes, config.i18n)) : nextRoutes;
+	if (!config.i18n) return nextRoutes;
+	const routesWithAlternates = nextRoutes.map((route) => withAlternates(route, nextRoutes, config.i18n));
+	const bareAliases = [];
+	const seenBare = new Set(routesWithAlternates.map((route) => route.path));
+	for (const route of routesWithAlternates) {
+		if (route.locale !== config.i18n.defaultLocale) continue;
+		const basePath = route.basePath ?? route.path;
+		if (basePath === route.path || seenBare.has(basePath)) continue;
+		seenBare.add(basePath);
+		bareAliases.push(cloneOpenAPIRoute(route, {
+			path: basePath,
+			module: { virtualModuleId: virtualModuleIdFromPath(basePath) },
+			isBareAlias: true
+		}));
+	}
+	return [...routesWithAlternates, ...bareAliases];
 }
-/** Derive a stable, deduplicated key from an absolute spec file path. */
-function specFileKeyFromPath(filePath, projectRoot) {
+/** Derive a stable, deduplicated id from an absolute spec file path. */
+function sourceSpecIdFromPath(filePath, projectRoot) {
 	return relative(projectRoot, filePath).replace(/[^a-zA-Z0-9_-]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
 }
+function routeSpecModuleIdFromSourceSpecId(sourceSpecId, tagFilter) {
+	if (!tagFilter?.length) return sourceSpecId;
+	return `${sourceSpecId}_tags_${tagFilter.map((tag) => tag.replace(/[^a-zA-Z0-9_-]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "") || "tag").join("_")}`;
+}
+function openAPIRegistryKeys(route) {
+	const keys = /* @__PURE__ */ new Set();
+	const path = (route.path || "/").replace(/^\//, "");
+	const base = (route.basePath ?? route.path).replace(/^\//, "");
+	if (route.locale) keys.add(`virtual:clarify-page/${route.locale}/${base}`);
+	if (path) keys.add(`virtual:clarify-page/${path}`);
+	else keys.add("virtual:clarify-page/index");
+	if (!route.locale && base) keys.add(`virtual:clarify-page/${base}`);
+	return [...keys];
+}
 function createOpenAPIPlugin() {
-	/** specs keyed by specFileKey (deduplicated per source file). */
+	/** specs keyed by sourceSpecId (deduplicated per source file). */
 	const specs = /* @__PURE__ */ new Map();
+	const specModules = /* @__PURE__ */ new Map();
 	return {
 		name: "clarify:openapi",
 		hooks: {
-			"routes:discover": (input) => ({
+			"routes:discover": (input, ctx) => ({
 				...input,
-				routes: [...input.routes, ...findOpenAPIRoutes(input.contentRoot)]
+				routes: [...input.routes, ...findOpenAPIRoutesForContentRoot(input.contentRoot, ctx.projectConfig.i18n)]
 			}),
 			"routes:discovered": async (routes, ctx) => {
 				specs.clear();
+				specModules.clear();
 				const nextRoutes = createConfiguredOpenAPIRoutes(routes, ctx.projectConfig);
 				const specByFilePath = /* @__PURE__ */ new Map();
 				for (const route of nextRoutes.filter((route) => route.kind === "openapi")) {
-					const specFromCache = specByFilePath.get(route.filePath);
+					const specFromCache = specByFilePath.get(route.source.filePath);
 					const processor = createProjectContentProcessor(ctx.plugins, ctx);
 					const result = specFromCache ? {
 						ok: true,
 						spec: specFromCache
-					} : await readOpenAPISpec(route.filePath, processor);
+					} : await readOpenAPISpec(route.source.filePath, processor);
 					if (!result.ok) {
 						route.diagnostic = result.diagnostic;
-						route.title = route.title || "OpenAPI parse error";
-						route.sections = [];
+						route.meta.title = route.meta.title || "OpenAPI parse error";
+						route.meta.sections = [];
 						continue;
 					}
-					const spec = result.spec;
-					specByFilePath.set(route.filePath, spec);
-					const specKey = specFileKeyFromPath(route.filePath, ctx.generateOptions.projectRoot);
-					route.specFileKey = specKey;
-					specs.set(specKey, {
+					const spec = normalizeOpenAPISpecSectionIds(result.spec);
+					specByFilePath.set(route.source.filePath, spec);
+					const sourceSpecId = sourceSpecIdFromPath(route.source.filePath, ctx.generateOptions.projectRoot);
+					route.openapi = {
+						...route.openapi,
+						sourceSpecId
+					};
+					specs.set(sourceSpecId, {
 						spec,
-						filePath: route.filePath
+						filePath: route.source.filePath
 					});
-					route.title = spec.info?.title ?? route.title;
-					route.description = spec.info?.description ?? route.description;
-					route.sections = extractOpenAPISections(spec, route.openapiTagFilter);
-					const pageSpec = route.openapiTagFilter?.length ? filterSpecByTags(spec, route.openapiTagFilter) : spec;
-					route.content = JSON.stringify(pageSpec);
+					route.meta.title = spec.info?.title ?? route.meta.title;
+					route.meta.description = spec.info?.description ?? route.meta.description;
+					route.meta.sections = extractOpenAPISections(spec, route.openapi?.tagFilter);
+					const pageSpec = route.openapi?.tagFilter?.length ? filterSpecByTags(spec, route.openapi.tagFilter) : spec;
+					const routeSpecModuleId = routeSpecModuleIdFromSourceSpecId(sourceSpecId, route.openapi?.tagFilter);
+					route.openapi.routeSpecModuleId = routeSpecModuleId;
+					specModules.set(routeSpecModuleId, pageSpec);
+					route.source.content = JSON.stringify(pageSpec);
 				}
 				return nextRoutes;
 			},
 			"modules:before": (modules, ctx) => {
 				const registryEntries = {};
+				const serverRegistryEntries = {};
 				for (const route of ctx.routes) {
-					if (route.kind !== "openapi" || !route.specFileKey) continue;
-					const spec = specs.get(route.specFileKey)?.spec;
+					if (route.kind !== "openapi" || !route.openapi?.sourceSpecId) continue;
+					const routeSpecModuleId = route.openapi.routeSpecModuleId ?? route.openapi.sourceSpecId;
+					const spec = specModules.get(routeSpecModuleId) ?? specs.get(route.openapi.sourceSpecId)?.spec;
 					if (!spec) continue;
-					const base = (route.basePath ?? route.path).replace(/^\//, "");
-					const registryKey = route.locale ? `virtual:clarify-page/${route.locale}/${base}` : `virtual:clarify-page/${base}`;
-					registryEntries[registryKey] = spec;
+					for (const registryKey of openAPIRegistryKeys(route)) {
+						registryEntries[registryKey] = specVirtualModuleId(routeSpecModuleId);
+						serverRegistryEntries[registryKey] = spec;
+					}
 				}
 				modules.set(openApiRegistryModuleId, generateOpenAPIRegistryModule(registryEntries));
-				for (const [specKey, entry] of specs) modules.set(specVirtualModuleId(specKey), generateOpenAPISpecModule(entry.spec));
+				modules.set(openApiServerRegistryModuleId, generateOpenAPIServerRegistryModule(serverRegistryEntries));
+				for (const [routeSpecModuleId, spec] of specModules) modules.set(specVirtualModuleId(routeSpecModuleId), generateOpenAPISpecModule(spec));
 				for (const route of ctx.routes) {
 					if (route.kind !== "openapi") continue;
-					if (route.diagnostic) modules.set(route.virtualModuleId, generateOpenAPIErrorModule(route.diagnostic));
-					else if (route.specFileKey) {
-						const entry = specs.get(route.specFileKey);
-						if (!entry) continue;
-						modules.set(route.virtualModuleId, generateOpenAPIPageModule({
-							spec: entry.spec,
-							tagFilter: route.openapiTagFilter
-						}));
+					if (route.diagnostic) modules.set(route.module.virtualModuleId, generateOpenAPIErrorModule(route.diagnostic));
+					else if (route.openapi?.sourceSpecId) {
+						const routeSpecModuleId = route.openapi.routeSpecModuleId ?? route.openapi.sourceSpecId;
+						if (!specModules.has(routeSpecModuleId)) continue;
+						modules.set(route.module.virtualModuleId, generateOpenAPIPageModule({ specModuleId: specVirtualModuleId(routeSpecModuleId) }));
 					}
 				}
 				return modules;
@@ -2119,11 +2260,11 @@ async function generatePagefindIndex(options, pagefind) {
 }
 function routeSearchContent(route) {
 	return [
-		route.title,
-		route.description,
-		route.keywords?.join(" "),
-		route.sections?.map((section) => section.title).join(" "),
-		route.content
+		route.meta.title,
+		route.meta.description,
+		route.meta.keywords?.join(" "),
+		route.meta.sections?.map((section) => section.title).join(" "),
+		route.source.content
 	].filter(Boolean).join("\n\n");
 }
 async function generateDevSearchIndex(ctx, root, pagefind) {
@@ -2145,7 +2286,7 @@ async function generateDevSearchIndex(ctx, root, pagefind) {
 				url: route.path,
 				content,
 				language: toPagefindLanguage(route.locale ?? ctx.projectConfig.i18n?.defaultLocale),
-				meta: { title: route.title }
+				meta: { title: route.meta.title }
 			});
 			assertNoPagefindErrors(`addCustomRecord ${route.path}`, result.errors);
 			pageCount += 1;
@@ -2302,15 +2443,18 @@ function normalizeRepositoryUrl(repository) {
 function encodePath(path) {
 	return path.split("/").filter(Boolean).map((segment) => encodeURIComponent(segment)).join("/");
 }
-function createSourceUrl(filePath, contentRoot, source) {
+function createSourceEditUrl(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) {
+function attachSourceEditUrls(routes, contentRoot, source) {
 	if (!source) return;
-	for (const route of routes) route.sourceUrl = createSourceUrl(route.filePath, contentRoot, source);
+	for (const route of routes) route.source = {
+		...route.source,
+		sourceEditUrl: createSourceEditUrl(route.source.filePath, contentRoot, source)
+	};
 }
 //#endregion
 //#region source/plugins/source-links/index.ts
@@ -2318,7 +2462,7 @@ function createSourceLinksPlugin() {
 	return {
 		name: "clarify:source-links",
 		hooks: { "routes:discovered": (routes, ctx) => {
-			attachSourceUrls(routes, join(ctx.generateOptions.projectRoot, ctx.generateOptions.rootDirectory), ctx.projectConfig.source);
+			attachSourceEditUrls(routes, join(ctx.generateOptions.projectRoot, ctx.generateOptions.rootDirectory), ctx.projectConfig.source);
 			return routes;
 		} }
 	};
@@ -2475,9 +2619,9 @@ var CLARIFY_ENV_TEMPLATE = `// This file is generated by Clarify. Do not edit it
 // plugin and slot code, so the TypeScript language service can resolve them.
 
 declare module 'virtual:clarify/slot' {
-  import type { SlotContext } from '@clarify-labs/cli'
+  import type { UISlotContext } from '@clarify-labs/cli'
 
-  export function useSlot(): SlotContext
+  export function useSlot(): UISlotContext
 }
 `;
 function generateClarifyEnvDts(_plugins) {
@@ -2499,6 +2643,11 @@ function writeClarifyEnvDts(projectRoot, plugins) {
 	writeFileSync(filePath, next, "utf-8");
 }
 //#endregion
+//#region source/parsers/markdown/utils.ts
+function escapeHtml(text) {
+	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+//#endregion
 //#region source/core/runtime/html-template.ts
 /**
 * HTML template manipulation helpers used during SSG.
@@ -2515,7 +2664,7 @@ function resolveProjectConfigFromContext(contextOrConfig) {
 }
 function routeTitle(contextOrConfig, route) {
 	const projectConfig = resolveProjectConfigFromContext(contextOrConfig);
-	const title = route?.title?.trim();
+	const title = route?.meta.title.trim();
 	if (!title || title === projectConfig.title) return projectConfig.title;
 	return `${title} - ${projectConfig.title}`;
 }
@@ -2563,8 +2712,8 @@ function injectSSRIntoTemplate(template, appHtml, contextOrConfig, route) {
 	const projectConfig = resolveProjectConfigFromContext(contextOrConfig);
 	let html = injectHtmlLocaleAttributes(template, contextOrConfig, route);
 	html = html.replace(/<title>.*?<\/title>/, `<title>${escapeHtml(routeTitle(contextOrConfig, route))}</title>`);
-	html = setNamedMeta(html, "description", route?.description ?? projectConfig.description);
-	html = setNamedMeta(html, "keywords", route?.keywords?.join(", "));
+	html = setNamedMeta(html, "description", route?.meta.description ?? projectConfig.description);
+	html = setNamedMeta(html, "keywords", route?.meta.keywords?.join(", "));
 	html = injectCanonicalUrl(html, contextOrConfig, route);
 	const dataPagefindIgnore = route?.isBareAlias ? " data-pagefind-ignore" : "";
 	html = html.replace(/<div id="root">([\s\S]*?)<\/div>/, `<div id="root"${dataPagefindIgnore}>${appHtml}</div>`);
@@ -2673,7 +2822,7 @@ function routeOutputFiles(outputDirectory, route) {
 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';
+import { openApiSpecs } from 'virtual:clarify/openapi/server';
 import { runtimeSlots } from 'virtual:clarify/slots';
 
 export async function render(url) {
@@ -2681,10 +2830,10 @@ export async function render(url) {
   // them synchronously (renderToString has no Suspense support).
   const entries = Object.values(runtimeSlots).flat()
   await Promise.all(entries.map(async (entry) => {
-    const mod = await entry.component()
+    const mod = await entry.loadComponent()
     entry._resolved = mod.default
   }))
-  return renderToHTML({ config, routes, navigation, openApis, runtimeSlots, url, themeEditor: config.theme.editor });
+  return renderToHTML({ config, routes, navigation, openApiSpecs, runtimeSlots, url, themeEditor: config.theme.editor });
 }`;
 function createTempEntryFile(content) {
 	const entryPath = join(createClarifyTempDir("ssr"), "entry-server.ts");
@@ -2771,7 +2920,10 @@ var ClarifyContext = class {
 		this.generateOptions = init.generateOptions;
 		this.version = init.version;
 		this.currentRoutes = init.routes ?? [];
-		this.currentNavigation = init.navigation ?? [];
+		this.currentNavigation = init.navigation ?? {
+			kind: "flat",
+			nodes: []
+		};
 		this.currentPlugins = init.plugins ?? [];
 	}
 	get routes() {
@@ -2893,7 +3045,10 @@ var ClarifyEngine = class {
 			generateOptions: placeholderOptions,
 			version: cliPackageVersion,
 			routes: [],
-			navigation: [],
+			navigation: {
+				kind: "flat",
+				nodes: []
+			},
 			plugins: []
 		});
 	}
@@ -2996,9 +3151,9 @@ var ClarifyEngine = class {
 		routes = await runPhase(plugins, "content:process", this.ctx, async () => {
 			const pages = routes.map((route) => ({
 				path: route.path,
-				filePath: route.filePath,
-				frontmatter: route.frontmatter ?? {},
-				content: route.content ?? ""
+				filePath: route.source.filePath,
+				frontmatter: route.source.frontmatter ?? {},
+				content: route.source.content ?? ""
 			}));
 			const resolvedPages = await runHooks(plugins, "pages:resolved", pages, this.ctx);
 			const pageByPath = new Map(resolvedPages.map((p) => [p.path, p]));
@@ -3007,13 +3162,22 @@ var ClarifyEngine = class {
 				if (!page) return route;
 				return {
 					...route,
-					frontmatter: page.frontmatter,
-					content: page.content
+					source: {
+						...route.source,
+						frontmatter: page.frontmatter,
+						content: page.content
+					}
 				};
 			});
 		});
 		routes = applyConfiguredPageRoutePaths(routes, tabs, i18n);
-		const navigation = tabs ? i18n ? buildLocalizedNavigationFromTabsConfig(routes, tabs, i18n) ?? {} : buildNavigationFromTabsConfig(routes, tabs) : buildNavigation(routes);
+		const navigation = tabs ? i18n ? buildLocalizedNavigationFromTabsConfig(routes, tabs, i18n) ?? {
+			kind: "localized-tabbed",
+			locales: {}
+		} : buildNavigationFromTabsConfig(routes, tabs) : {
+			kind: "flat",
+			nodes: buildNavigation(routes)
+		};
 		const resolved = await runHooks(plugins, "routes:resolved", {
 			routes,
 			navigation
@@ -3047,7 +3211,7 @@ var ClarifyEngine = class {
 		writeClarifyEnvDts(this.root, this.plugins);
 	}
 	hasContentRouteForFile(filePath) {
-		return this.routes.some((route) => route.filePath === filePath);
+		return this.routes.some((route) => route.source.filePath === filePath);
 	}
 	async collectBuildAssets() {
 		if (!this.buildEnabled) return [];
@@ -3140,4 +3304,4 @@ function createClarifyEngine(options = {}) {
 //#endregion
 export { cliPackageVersion as a, defineConfig as c, createClarifyTempDir as i, createClarifyEngine as n, cliPackageVersionWithCaret as o, createClarifyRuntimeAliases as r, createViteAdapter as s, ClarifyEngine as t };
 
-//# sourceMappingURL=engine-3f5Tpa-6.js.map
+//# sourceMappingURL=engine-CSSL_gGd.js.map