@clarify-labs/cli 0.11.4 → 0.11.6

package/output/{engine-Cgc71w13.cjs → engine-DVw8CV5R.cjs}

@@ -112,7 +112,7 @@ var rehypePlugins = [
 ];
 function createContentCompileDiagnostic(options) {
 	const { format, phase, error, filePath, projectRoot } = options;
-	const label = format === "mdx" ? "MDX" : "Markdown";
+	const label = format === "markdown+jsx" ? "MDX" : "Markdown";
 	return createContentDiagnostic({
 		kind: format,
 		title: `${label} ${phase} error`,
@@ -158,7 +158,7 @@ async function compileMdxContent(content, options = {}) {
 		return {
 			ok: false,
 			diagnostic: createContentCompileDiagnostic({
-				format: "mdx",
+				format: "markdown+jsx",
 				phase: "syntax",
 				error,
 				filePath,
@@ -168,6 +168,21 @@ async function compileMdxContent(content, options = {}) {
 	}
 }
 //#endregion
+//#region source/core/runtime/module-ids.ts
+var PAGE_PREFIX = "virtual:clarify-page/";
+var CONTENT_PREFIX = "virtual:clarify-content/";
+function pageVirtualModuleId(path) {
+	return `${PAGE_PREFIX}${path.replace(/^\/+/, "").replace(/\/index$/, "").replace(/\/+/g, "/") || "index"}`;
+}
+function pageVirtualModuleIdFromRef(ref) {
+	return pageVirtualModuleId(ref.replace(/\.mdx?$/, "").replace(/\.openapi\.(json|yaml|yml)$/, ""));
+}
+function contentVirtualModuleId(filePath, contentRoot) {
+	const sourcePath = (0, node_path.relative)(contentRoot, filePath).replace(/\\/g, "/");
+	if (!sourcePath || sourcePath.startsWith("../") || (0, node_path.isAbsolute)(sourcePath)) throw new Error(`Content source must be inside the content root: ${filePath}`);
+	return `${CONTENT_PREFIX}${sourcePath}`;
+}
+//#endregion
 //#region source/core/plugin/hooks.ts
 async function runHooks(plugins, hookName, input, ctx) {
 	let result = input;
@@ -183,32 +198,43 @@ async function runHooks(plugins, hookName, input, ctx) {
 	return result;
 }
 async function runDevConfigureServerHooks(plugins, server, ctx) {
+	const postHooks = [];
 	for (const plugin of plugins) {
 		const hook = plugin.hooks?.["dev:configureServer"];
 		if (!hook) continue;
 		try {
-			await hook(server, ctx);
+			const postHook = await hook(server, ctx);
+			if (postHook) postHooks.push(postHook);
 		} catch (err) {
 			throw new Error(`[clarify] plugin "${plugin.name}" hook "dev:configureServer" failed: ${err}`, { cause: err });
 		}
 	}
+	return postHooks;
 }
-async function runCollectorHooks(plugins, hookName, ctx) {
-	const results = [];
+async function runBuildAssetsHooks(plugins, ctx) {
+	const assets = [];
+	const producerByFileName = /* @__PURE__ */ new Map();
 	for (const plugin of plugins) {
-		const hook = plugin.hooks?.[hookName];
+		const hook = plugin.hooks?.["build:assets"];
 		if (!hook) continue;
+		let pluginAssets;
 		try {
-			const pluginResults = await hook(ctx);
-			results.push(...pluginResults);
+			pluginAssets = await hook(ctx);
 		} catch (err) {
-			throw new Error(`[clarify] plugin "${plugin.name}" hook "${hookName}" failed: ${err}`, { cause: err });
+			throw new Error(`[clarify] plugin "${plugin.name}" hook "build:assets" failed: ${err}`, { cause: err });
+		}
+		for (const asset of pluginAssets) {
+			const fileName = asset.fileName.replace(/\\/g, "/").replace(/^\/+/, "");
+			const previousProducer = producerByFileName.get(fileName);
+			if (previousProducer) throw new Error(`[clarify] build asset "${fileName}" is emitted by both plugin "${previousProducer}" and plugin "${plugin.name}"`);
+			producerByFileName.set(fileName, plugin.name);
+			assets.push({
+				...asset,
+				fileName
+			});
 		}
 	}
-	return results;
-}
-async function runBuildAssetsHooks(plugins, ctx) {
-	return runCollectorHooks(plugins, "build:assets", ctx);
+	return assets;
 }
 async function runBuildDoneHooks(plugins, ctx) {
 	for (const plugin of plugins) {
@@ -243,7 +269,7 @@ function createContentProcessor(transform) {
 		async processMdx(source, filePath) {
 			const { frontmatter, content } = parseFrontmatter(source);
 			const transformed = await transformContent(transform, {
-				kind: "mdx",
+				kind: "markdown+jsx",
 				source,
 				filePath,
 				frontmatter,
@@ -395,9 +421,6 @@ function openAPIPagePathFromRef(ref, tagFilter, explicitPath) {
 function routePathFromRef(ref, explicitPath) {
 	return explicitPath ? normalizePath(explicitPath) : basePathFromRef(ref);
 }
-function virtualModuleIdFromRef(ref) {
-	return "virtual:clarify-page/" + ref.replace(/\.mdx?$/, "").replace(/\.openapi\.(json|yaml|yml)$/, "").replace(/\/+/g, "/");
-}
 function localizedRoutePath(basePath, locale, _i18n) {
 	const normalizedBasePath = normalizePath(basePath);
 	const prefix = normalizePath(locale);
@@ -440,7 +463,7 @@ async function findContentRoutes(dir, base = dir, options = {}) {
 				title = kebabToTitle(lastPart === "index" ? pathParts.length >= 2 ? pathParts[pathParts.length - 2] : extractH1(page.content) : lastPart) || "Untitled";
 			}
 			routes.push({
-				kind: "mdx",
+				kind: entry.name.toLowerCase().endsWith(".mdx") ? "markdown+jsx" : "markdown",
 				path: cleanPath,
 				basePath: cleanPath,
 				meta: {
@@ -449,7 +472,10 @@ async function findContentRoutes(dir, base = dir, options = {}) {
 					keywords: frontmatterKeywords(page.frontmatter),
 					sections: extractMdxSections(page.content)
 				},
-				module: { virtualModuleId: "virtual:clarify-page/" + relativePath.replace(/\.mdx?$/, "").replace(/\/+/g, "/") },
+				module: {
+					pageVirtualModuleId: pageVirtualModuleId(relativePath.replace(/\.mdx?$/, "")),
+					contentVirtualModuleId: contentVirtualModuleId(fullPath, base)
+				},
 				source: {
 					filePath: fullPath,
 					frontmatter: page.frontmatter,
@@ -461,14 +487,24 @@ async function findContentRoutes(dir, base = dir, options = {}) {
 	}
 	return routes;
 }
-function virtualModuleIdForLocalizedRoute(contentRoot, filePath) {
-	return "virtual:clarify-page/" + (0, node_path.relative)(contentRoot, filePath).replace(/\.mdx?$/, "").replace(/\.openapi\.(json|yaml|yml)$/, "").replace(/\/+/g, "/");
+function pageVirtualModuleIdForLocalizedRoute(contentRoot, filePath) {
+	return pageVirtualModuleIdFromRef((0, node_path.relative)(contentRoot, filePath));
 }
 function frontmatterKeywords(frontmatter) {
 	const value = frontmatter.keywords ?? frontmatter.keyword ?? frontmatter.tags;
 	const keywords = Array.isArray(value) ? value.filter((item) => typeof item === "string") : typeof value === "string" ? value.split(",").map((keyword) => keyword.trim()).filter(Boolean) : [];
 	return keywords.length > 0 ? keywords : void 0;
 }
+function withPageIdentity(route, path) {
+	return {
+		...route,
+		path,
+		module: {
+			...route.module,
+			pageVirtualModuleId: pageVirtualModuleId(path)
+		}
+	};
+}
 function withAlternates(route, routes, locales) {
 	const basePath = route.basePath ?? route.path;
 	const routeByLocaleAndBase = new Map(routes.filter((r) => !r.locale || r.path === `/${r.locale}` || r.path.startsWith(`/${r.locale}/`)).map((r) => [`${r.locale ?? ""}:${r.basePath ?? r.path}`, r]));
@@ -494,8 +530,7 @@ function generateBareAliases(routes, locales) {
 		if (bp === route.path || seenBare.has(bp)) continue;
 		seenBare.add(bp);
 		bareRoutes.push({
-			...route,
-			path: bp,
+			...withPageIdentity(route, bp),
 			isBareAlias: true
 		});
 	}
@@ -514,7 +549,11 @@ async function findLocalizedContentRoutes(contentRoot, locales, options = {}) {
 				path: localizedRoutePath(basePath, locale.code, locales),
 				basePath,
 				locale: locale.code,
-				module: { virtualModuleId: virtualModuleIdForLocalizedRoute(contentRoot, route.source.filePath) }
+				module: {
+					...route.module,
+					pageVirtualModuleId: pageVirtualModuleIdForLocalizedRoute(contentRoot, route.source.filePath),
+					contentVirtualModuleId: contentVirtualModuleId(route.source.filePath, contentRoot)
+				}
 			});
 		}
 	}
@@ -526,9 +565,9 @@ async function findLocalizedContentRoutes(contentRoot, locales, options = {}) {
 			for (const locale of locales.locales) {
 				const key = `${locale.code}:${basePath}`;
 				if (routeByLocaleAndBase.has(key)) continue;
+				const path = localizedRoutePath(basePath, locale.code, locales);
 				localizedRoutes.push({
-					...sourceRoute,
-					path: localizedRoutePath(basePath, locale.code, locales),
+					...withPageIdentity(sourceRoute, path),
 					locale: locale.code,
 					isFallback: true
 				});
@@ -623,13 +662,13 @@ function applyConfiguredPageRoutePaths(routes, tabs, locales) {
 		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;
+			if (route.kind === "openapi" || (route.basePath ?? route.path) !== sourceBasePath) continue;
 			const key = `${route.locale ?? ""}:${targetBasePath}`;
 			if (existingKeys.has(key)) continue;
 			existingKeys.add(key);
+			const path = route.locale && locales ? localizedRoutePath(targetBasePath, route.locale, locales) : targetBasePath;
 			additions.push({
-				...route,
-				path: route.locale && locales ? localizedRoutePath(targetBasePath, route.locale, locales) : targetBasePath,
+				...withPageIdentity(route, path),
 				basePath: targetBasePath
 			});
 		}
@@ -637,7 +676,8 @@ function applyConfiguredPageRoutePaths(routes, tabs, locales) {
 	const nextRoutes = [...routes, ...additions];
 	const routesWithAlternates = locales ? nextRoutes.map((route) => withAlternates(route, nextRoutes, locales)) : nextRoutes;
 	if (!locales) return routesWithAlternates;
-	return [...routesWithAlternates, ...generateBareAliases(routesWithAlternates, locales)];
+	const markdownRoutes = routesWithAlternates.filter((route) => route.kind !== "openapi");
+	return [...routesWithAlternates, ...generateBareAliases(markdownRoutes, locales)];
 }
 function buildNavigationFromPagesConfig(routes, config) {
 	if (!config || config === "FileTree") return buildNavigation(routes);
@@ -831,7 +871,7 @@ function inferRouteForFile(filePath, contentRoot, defaultLocale) {
 		filePath,
 		locale: fileLocale,
 		basePath: normalizePath(basePath),
-		kind: isMdx ? "mdx" : "openapi",
+		kind: isMdx ? "markdown+jsx" : "openapi",
 		title,
 		inferred: true
 	};
@@ -1250,6 +1290,9 @@ function resolveVirtualId(id) {
 function stripVirtualPrefix(id) {
 	return id.startsWith("\0") ? id.slice(1) : id;
 }
+function virtualContentModuleId(route) {
+	return route.module.contentVirtualModuleId;
+}
 /**
 * Fixed virtual module IDs (excluding the client entry, which has a special
 * resolved form). Used to avoid hardcoding the constant list in every
@@ -1277,8 +1320,10 @@ 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.module.virtualModuleId === id || route.module.virtualModuleId === moduleId);
-	if (route) return resolveVirtualId(route.module.virtualModuleId);
+	const contentRoute = routes.find((route) => (route.kind === "markdown" || route.kind === "markdown+jsx") && route.module.contentVirtualModuleId === moduleId);
+	if (contentRoute) return contentRoute.source.filePath;
+	const route = routes.find((route) => route.module.pageVirtualModuleId === id || route.module.pageVirtualModuleId === moduleId);
+	if (route) return resolveVirtualId(route.module.pageVirtualModuleId);
 	return null;
 }
 function generateConfigModule(projectConfig, version) {
@@ -1332,8 +1377,8 @@ function routeToRuntimeManifestEntry(route, component, mode) {
 	return entry;
 }
 function generateRoutesModule(routes, navigation, mode = "client") {
-	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 }) }))`;
+	return `${mode === "server" ? routes.map((r, i) => `import Page${i} from ${moduleSpecifier(r.module.pageVirtualModuleId)};`).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.pageVirtualModuleId)}).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 manifestEntry = routeToRuntimeManifestEntry(r, placeholder, mode);
 		return `  ${JSON.stringify(manifestEntry, null, 0).replace(`"${placeholder}"`, component).replace(/"([A-Za-z_$][\w$]*)":/g, "$1: ")}`;
@@ -1405,13 +1450,14 @@ 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 openApiSpecs = {};");
 	modules.set(VIRTUAL_SLOT, "export { useSlot } from '@clarify-labs/renderer';\n");
-	modules.set(VIRTUAL_CLIENT_ENTRY, clientEntryModule);
+	modules.set(VIRTUAL_OPENAPI, "export const openApiSpecs = {};");
 	modules.set(RESOLVED_CLIENT_ENTRY, clientEntryModule);
+	modules.set(VIRTUAL_CLIENT_ENTRY, clientEntryModule);
 	for (const route of args.routes) {
-		const moduleContent = route.diagnostic ? generateContentDiagnosticModule(route.diagnostic) : `export { default } from ${moduleSpecifier(route.source.filePath)};`;
-		modules.set(route.module.virtualModuleId, moduleContent);
+		const moduleContent = route.diagnostic ? generateContentDiagnosticModule(route.diagnostic) : route.kind === "markdown" || route.kind === "markdown+jsx" ? `export { default } from ${moduleSpecifier(virtualContentModuleId(route))};` : null;
+		if (moduleContent === null) continue;
+		modules.set(route.module.pageVirtualModuleId, moduleContent);
 	}
 	return modules;
 }
@@ -1452,7 +1498,7 @@ function createNormalizedContentPlugin(engine) {
 		transform(_code, id) {
 			if (!/\.mdx?(?:\?|$)/.test(id)) return null;
 			const filePath = id.replace(/\?.*$/, "");
-			const route = engine.routes.find((route) => route.kind === "mdx" && route.source.filePath === filePath);
+			const route = engine.routes.find((route) => (route.kind === "markdown+jsx" || route.kind === "markdown") && route.source.filePath === filePath);
 			if (!route || route.source.content === void 0) return null;
 			return {
 				code: route.source.content,
@@ -1567,7 +1613,10 @@ function createClarifyViteCorePlugin(engine, normalizedContentPlugin, markdown,
 			};
 			server.watcher.on("add", handleContentTreeChange);
 			server.watcher.on("unlink", handleContentTreeChange);
-			await engine.configureDevServer(server);
+			const postHooks = await engine.configureDevServer(server);
+			if (postHooks.length > 0) return () => {
+				for (const postHook of postHooks) postHook();
+			};
 		},
 		transformIndexHtml: {
 			order: "pre",
@@ -1622,7 +1671,7 @@ function createViteAdapter(engine) {
 	const errorPolicy = () => contentCompileErrorPolicy;
 	const normalizedContentPlugin = createNormalizedContentPlugin(engine);
 	const markdown = createContentCompilerPlugin("markdown", engine.root, errorPolicy);
-	const mdx = createContentCompilerPlugin("mdx", engine.root, errorPolicy);
+	const mdx = createContentCompilerPlugin("markdown+jsx", engine.root, errorPolicy);
 	const compilePolicyPlugin = {
 		name: "clarify:content-compile-policy",
 		configResolved(config) {
@@ -1642,7 +1691,7 @@ function createViteAdapter(engine) {
 }
 var cliPackageVersion = {
 	name: "@clarify-labs/cli",
-	version: "0.11.4",
+	version: "0.11.6",
 	license: "AGPL-3.0-only",
 	type: "module",
 	repository: {
@@ -1742,7 +1791,7 @@ function withUtf8Signature(content) {
 	return `${UTF8_SIGNATURE}${content}`;
 }
 function shouldUseUtf8Signature(route) {
-	if (route.kind === "mdx") return true;
+	if (route.kind === "markdown+jsx" || route.kind === "markdown") return true;
 	return false;
 }
 function routeToMarkdownArtifactUrl(routePath) {
@@ -1814,9 +1863,9 @@ function createLlmsTxt(routes, projectConfig) {
 	const lines = [`# ${projectConfig.title}`, ""];
 	if (projectConfig.description) lines.push(`> ${projectConfig.description}`, "");
 	lines.push("This file lists the source-ready Markdown and OpenAPI artifacts for this documentation site.", "");
-	const mdxRoutes = routes.filter((route) => route.kind === "mdx" && isLlmsTxtRoute(route) && !route.isBareAlias);
-	if (mdxRoutes.length > 0) {
-		const localizedGroups = groupLlmsTxtRoutesByLocale(mdxRoutes, projectConfig);
+	const markdownRoutes = routes.filter((route) => (route.kind === "markdown+jsx" || route.kind === "markdown") && isLlmsTxtRoute(route) && !route.isBareAlias);
+	if (markdownRoutes.length > 0) {
+		const localizedGroups = groupLlmsTxtRoutesByLocale(markdownRoutes, projectConfig);
 		for (const [locale, localeRoutes] of localizedGroups) {
 			lines.push(`## ${llmsTxtDocsSectionTitle(locale, localizedGroups.size, projectConfig)}`);
 			for (const route of localeRoutes) {
@@ -1893,10 +1942,12 @@ function createContentArtifactsPlugin() {
 				return input;
 			},
 			"dev:configureServer": (server, ctx) => {
-				server.middlewares.use((req, res, next) => {
-					if (serveContentArtifacts(req, res, ctx.projectConfig, ctx.routes)) return;
-					next();
-				});
+				return () => {
+					server.middlewares.use((req, res, next) => {
+						if (serveContentArtifacts(req, res, ctx.projectConfig, ctx.routes)) return;
+						next();
+					});
+				};
 			},
 			"build:assets": (ctx) => {
 				const assets = [];
@@ -2387,7 +2438,7 @@ function findOpenAPIRoutes(dir, base = dir) {
 			basePath: cleanPath,
 			kind: "openapi",
 			meta: { title: kebabToTitle(cleanPath.split("/").pop() ?? "API") },
-			module: { virtualModuleId: virtualModuleIdFromRef(ref) },
+			module: { pageVirtualModuleId: pageVirtualModuleIdFromRef(ref) },
 			source: { filePath: fullPath }
 		});
 	}
@@ -2511,34 +2562,7 @@ async function readOpenAPISpec(filePath, contentProcessor, projectRoot) {
 	}
 }
 //#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(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) {
-	return `export default ${JSON.stringify(spec)};`;
-}
-function generateOpenAPIPageModule(opts) {
-	return `import { createOpenApiRouteComponent } from '@clarify-labs/renderer';
-import spec from ${JSON.stringify(opts.specModuleId)};
-
-export const routeData = {};
-
-export default createOpenApiRouteComponent({ ...routeData, spec });
-`;
-}
-//#endregion
-//#region source/plugins/openapi/index.ts
+//#region source/plugins/openapi/routes.ts
 function collectOpenAPIPageIntents(config) {
 	const intents = [];
 	function visitItems(items) {
@@ -2558,9 +2582,6 @@ function collectOpenAPIPageIntents(config) {
 	for (const tab of config.navigation?.tabs ?? []) visitPages(tab.pages);
 	return intents;
 }
-function virtualModuleIdFromPath(path) {
-	return `virtual:clarify-page/${path.replace(/^\/+/, "") || "index"}`;
-}
 function cloneOpenAPIRoute(route, overrides = {}) {
 	return {
 		...route,
@@ -2578,7 +2599,7 @@ function cloneOpenAPIRoute(route, overrides = {}) {
 		...overrides
 	};
 }
-function findOpenAPIRoutesForContentRoot(contentRoot, locales) {
+function discoverOpenAPIRoutes(contentRoot, locales) {
 	if (!locales) return findOpenAPIRoutes(contentRoot);
 	const localizedRoutes = [];
 	for (const locale of locales.locales) {
@@ -2591,31 +2612,30 @@ function findOpenAPIRoutesForContentRoot(contentRoot, locales) {
 				path,
 				basePath,
 				locale: locale.code,
-				module: { virtualModuleId: virtualModuleIdFromPath(path) }
+				module: { pageVirtualModuleId: pageVirtualModuleId(path) }
 			});
 		}
 	}
-	if (locales.missing === "fallback") {
-		const routeByLocaleAndBase = new Map(localizedRoutes.map((route) => [`${route.locale ?? ""}:${route.basePath ?? route.path}`, route]));
-		const defaultRoutes = localizedRoutes.filter((route) => route.locale === locales.default);
-		for (const sourceRoute of defaultRoutes) {
-			const basePath = sourceRoute.basePath ?? sourceRoute.path;
-			for (const locale of locales.locales) {
-				const key = `${locale.code}:${basePath}`;
-				if (routeByLocaleAndBase.has(key)) continue;
-				const path = localizedRoutePath(basePath, locale.code, locales);
-				localizedRoutes.push(cloneOpenAPIRoute(sourceRoute, {
-					path,
-					locale: locale.code,
-					module: { virtualModuleId: virtualModuleIdFromPath(path) },
-					isFallback: true
-				}));
-			}
+	if (locales.missing !== "fallback") return localizedRoutes;
+	const routeByLocaleAndBase = new Map(localizedRoutes.map((route) => [`${route.locale ?? ""}:${route.basePath ?? route.path}`, route]));
+	const defaultRoutes = localizedRoutes.filter((route) => route.locale === locales.default);
+	for (const sourceRoute of defaultRoutes) {
+		const basePath = sourceRoute.basePath ?? sourceRoute.path;
+		for (const locale of locales.locales) {
+			const key = `${locale.code}:${basePath}`;
+			if (routeByLocaleAndBase.has(key)) continue;
+			const path = localizedRoutePath(basePath, locale.code, locales);
+			localizedRoutes.push(cloneOpenAPIRoute(sourceRoute, {
+				path,
+				locale: locale.code,
+				module: { pageVirtualModuleId: pageVirtualModuleId(path) },
+				isFallback: true
+			}));
 		}
 	}
 	return localizedRoutes;
 }
-function createConfiguredOpenAPIRoutes(routes, config) {
+function expandConfiguredOpenAPIRoutes(routes, config) {
 	const openAPIIntents = collectOpenAPIPageIntents(config);
 	if (!openAPIIntents.length) return routes;
 	const additions = [];
@@ -2634,7 +2654,7 @@ function createConfiguredOpenAPIRoutes(routes, config) {
 			additions.push(cloneOpenAPIRoute(route, {
 				path,
 				basePath: targetBasePath,
-				module: { virtualModuleId: virtualModuleIdFromPath(path) },
+				module: { pageVirtualModuleId: pageVirtualModuleId(path) },
 				openapi: {
 					...route.openapi,
 					tagFilter: tagFilter?.length ? tagFilter : void 0
@@ -2648,19 +2668,47 @@ function createConfiguredOpenAPIRoutes(routes, config) {
 	const bareAliases = [];
 	const seenBare = new Set(routesWithAlternates.map((route) => route.path));
 	for (const route of routesWithAlternates) {
-		if (route.locale !== config.locales.default) continue;
+		if (route.kind !== "openapi" || route.locale !== config.locales.default) 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) },
+			module: { pageVirtualModuleId: pageVirtualModuleId(basePath) },
 			isBareAlias: true
 		}));
 	}
 	return [...routesWithAlternates, ...bareAliases];
 }
-/** Derive a stable, deduplicated id from an absolute spec file path. */
+//#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(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) {
+	return `export default ${JSON.stringify(spec)};`;
+}
+function generateOpenAPIPageModule(opts) {
+	return `import { createOpenApiRouteComponent } from '@clarify-labs/renderer';
+import spec from ${JSON.stringify(opts.specModuleId)};
+
+export const routeData = {};
+
+export default createOpenApiRouteComponent({ ...routeData, spec });
+`;
+}
+//#endregion
+//#region source/plugins/openapi/state.ts
 function sourceSpecIdFromPath(filePath, projectRoot) {
 	return (0, node_path.relative)(projectRoot, filePath).replace(/[^a-zA-Z0-9_-]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
 }
@@ -2672,90 +2720,94 @@ 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}`);
+	if (route.locale) keys.add(pageVirtualModuleId(`${route.locale}/${base}`));
+	keys.add(pageVirtualModuleId(path));
+	if (!route.locale && base) keys.add(pageVirtualModuleId(base));
 	return [...keys];
 }
+var OpenAPIPluginState = class {
+	specModules = /* @__PURE__ */ new Map();
+	async enrichRoutes(routes, ctx) {
+		this.specModules.clear();
+		const specByFilePath = /* @__PURE__ */ new Map();
+		for (const route of routes) {
+			if (route.kind !== "openapi") continue;
+			const specFromCache = specByFilePath.get(route.source.filePath);
+			const processor = createProjectContentProcessor(ctx.plugins, ctx);
+			const result = specFromCache ? {
+				ok: true,
+				spec: specFromCache
+			} : await readOpenAPISpec(route.source.filePath, processor, ctx.generateOptions.projectRoot);
+			if (!result.ok) {
+				route.diagnostic = result.diagnostic;
+				route.meta.title = route.meta.title || "OpenAPI parse error";
+				route.meta.sections = [];
+				continue;
+			}
+			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
+			};
+			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;
+			this.specModules.set(routeSpecModuleId, pageSpec);
+			route.source.content = JSON.stringify(pageSpec);
+		}
+		return routes;
+	}
+	contributeModules(modules, routes) {
+		const registryEntries = {};
+		const serverRegistryEntries = {};
+		for (const route of routes) {
+			if (route.kind !== "openapi" || !route.openapi?.sourceSpecId) continue;
+			const routeSpecModuleId = route.openapi.routeSpecModuleId ?? route.openapi.sourceSpecId;
+			const spec = this.specModules.get(routeSpecModuleId);
+			if (!spec) continue;
+			for (const registryKey of openAPIRegistryKeys(route)) {
+				registryEntries[registryKey] = specVirtualModuleId(routeSpecModuleId);
+				serverRegistryEntries[registryKey] = spec;
+			}
+		}
+		modules.set(openApiRegistryModuleId, generateOpenAPIRegistryModule(registryEntries));
+		modules.set(openApiServerRegistryModuleId, generateOpenAPIServerRegistryModule(serverRegistryEntries));
+		for (const [routeSpecModuleId, spec] of this.specModules) modules.set(specVirtualModuleId(routeSpecModuleId), generateOpenAPISpecModule(spec));
+		for (const route of routes) {
+			if (route.kind !== "openapi") continue;
+			if (route.diagnostic) {
+				modules.set(route.module.pageVirtualModuleId, generateContentDiagnosticModule(route.diagnostic));
+				continue;
+			}
+			if (!route.openapi?.sourceSpecId) continue;
+			const routeSpecModuleId = route.openapi.routeSpecModuleId ?? route.openapi.sourceSpecId;
+			if (!this.specModules.has(routeSpecModuleId)) continue;
+			modules.set(route.module.pageVirtualModuleId, generateOpenAPIPageModule({ specModuleId: specVirtualModuleId(routeSpecModuleId) }));
+		}
+		return modules;
+	}
+};
+//#endregion
+//#region source/plugins/openapi/index.ts
 function createOpenAPIPlugin() {
-	/** specs keyed by sourceSpecId (deduplicated per source file). */
-	const specs = /* @__PURE__ */ new Map();
-	const specModules = /* @__PURE__ */ new Map();
+	const state = new OpenAPIPluginState();
 	return {
 		name: "clarify:openapi",
 		hooks: {
 			"routes:discover": (input, ctx) => ({
 				...input,
-				routes: [...input.routes, ...findOpenAPIRoutesForContentRoot(input.contentRoot, ctx.projectConfig.locales)]
+				routes: [...input.routes, ...discoverOpenAPIRoutes(input.contentRoot, ctx.projectConfig.locales)]
 			}),
 			"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.source.filePath);
-					const processor = createProjectContentProcessor(ctx.plugins, ctx);
-					const result = specFromCache ? {
-						ok: true,
-						spec: specFromCache
-					} : await readOpenAPISpec(route.source.filePath, processor, ctx.generateOptions.projectRoot);
-					if (!result.ok) {
-						route.diagnostic = result.diagnostic;
-						route.meta.title = route.meta.title || "OpenAPI parse error";
-						route.meta.sections = [];
-						continue;
-					}
-					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.source.filePath
-					});
-					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;
+				const expandedRoutes = expandConfiguredOpenAPIRoutes(routes, ctx.projectConfig);
+				return state.enrichRoutes(expandedRoutes, ctx);
 			},
-			"modules:before": (modules, ctx) => {
-				const registryEntries = {};
-				const serverRegistryEntries = {};
-				for (const route of ctx.routes) {
-					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;
-					for (const registryKey of openAPIRegistryKeys(route)) {
-						registryEntries[registryKey] = specVirtualModuleId(routeSpecModuleId);
-						serverRegistryEntries[registryKey] = spec;
-					}
-				}
-				modules.set(openApiRegistryModuleId, generateOpenAPIRegistryModule(registryEntries));
-				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.module.virtualModuleId, generateContentDiagnosticModule(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;
-			}
+			"modules:before": (modules, ctx) => state.contributeModules(modules, ctx.routes)
 		}
 	};
 }
@@ -3164,6 +3216,145 @@ async function resolveProjectContext(options = {}, env = {
 	};
 }
 //#endregion
+//#region source/core/routing/route-analysis.ts
+function routeDescription(route) {
+	return `${route.kind} ${route.source.filePath}`;
+}
+function collectConflicts(routes, keyOf) {
+	const grouped = /* @__PURE__ */ new Map();
+	for (const route of routes) {
+		const key = keyOf(route);
+		grouped.set(key, [...grouped.get(key) ?? [], route]);
+	}
+	return grouped;
+}
+function describeRouteConflict(route) {
+	return routeDescription(route);
+}
+function findRouteConflicts(routes) {
+	const conflicts = [];
+	for (const [path, pathRoutes] of collectConflicts(routes, (route) => route.path)) {
+		if (pathRoutes.length < 2) continue;
+		conflicts.push({
+			kind: "path",
+			key: path,
+			label: `path ${path}`,
+			routes: pathRoutes
+		});
+	}
+	for (const [pageModuleId, moduleRoutes] of collectConflicts(routes, (route) => route.module.pageVirtualModuleId)) {
+		if (moduleRoutes.length < 2) continue;
+		if (moduleRoutes.every((route) => route.path === moduleRoutes[0].path)) continue;
+		conflicts.push({
+			kind: "page-module",
+			key: pageModuleId,
+			label: `page module ${pageModuleId}`,
+			routes: moduleRoutes
+		});
+	}
+	return conflicts;
+}
+function formatRouteConflicts(conflicts) {
+	return conflicts.map((conflict) => `- ${conflict.label}: ${conflict.routes.map(describeRouteConflict).join(", ")}`).join("\n");
+}
+//#endregion
+//#region source/core/routing/route-resolution.ts
+async function resolveRoutePages(routes, plugins, ctx) {
+	const routeToken = Symbol("clarifyRouteToken");
+	const resolvedPages = await runHooks(plugins, "pages:resolved", routes.map((route, routeIndex) => ({
+		path: route.path,
+		filePath: route.source.filePath,
+		frontmatter: route.source.frontmatter ?? {},
+		content: route.source.content ?? "",
+		[routeToken]: routeIndex
+	})), ctx);
+	const pageByRouteIndex = /* @__PURE__ */ new Map();
+	for (const page of resolvedPages) {
+		const routeIndex = page[routeToken];
+		if (!Number.isInteger(routeIndex) || routeIndex < 0 || routeIndex >= routes.length) throw new Error("[clarify] pages:resolved hooks must preserve each page route identity");
+		if (pageByRouteIndex.has(routeIndex)) throw new Error("[clarify] pages:resolved hooks returned the same page route identity more than once");
+		pageByRouteIndex.set(routeIndex, page);
+	}
+	if (pageByRouteIndex.size !== routes.length) throw new Error("[clarify] pages:resolved hooks must return exactly one page for each route");
+	return routes.map((route, routeIndex) => {
+		const page = pageByRouteIndex.get(routeIndex);
+		return {
+			...route,
+			source: {
+				...route.source,
+				frontmatter: page.frontmatter,
+				content: page.content
+			}
+		};
+	});
+}
+function buildNavigationTree(routes, ctx) {
+	const tabs = ctx.projectConfig.navigation?.tabs;
+	if (!tabs) return {
+		kind: "flat",
+		nodes: buildNavigation(routes)
+	};
+	if (!ctx.projectConfig.locales) return buildNavigationFromTabsConfig(routes, tabs);
+	return buildLocalizedNavigationFromTabsConfig(routes, tabs, ctx.projectConfig.locales) ?? {
+		kind: "localized-tabbed",
+		locales: {}
+	};
+}
+function assertNoRouteConflicts(routes) {
+	const conflicts = findRouteConflicts(routes);
+	if (conflicts.length > 0) throw new Error(`[clarify] Route conflicts prevent the site from being built:\n${formatRouteConflicts(conflicts)}`);
+}
+function createRouteConflictDiagnostic(label, routes) {
+	return {
+		kind: "route-load",
+		title: "Route conflict",
+		message: `This page cannot be rendered because ${label} is used by multiple routes.`,
+		details: routes.map(describeRouteConflict).join("\n")
+	};
+}
+function createDevRouteConflictRoutes(routes) {
+	const conflicts = findRouteConflicts(routes);
+	if (conflicts.length === 0) return routes;
+	const conflictedRoutes = /* @__PURE__ */ new Map();
+	for (const conflict of conflicts) for (const route of conflict.routes) conflictedRoutes.set(route, conflict);
+	function createConflictRoute(route, conflict) {
+		return {
+			...route,
+			module: {
+				...route.module,
+				pageVirtualModuleId: `${route.module.pageVirtualModuleId}__conflict`
+			},
+			diagnostic: createRouteConflictDiagnostic(conflict.label, conflict.routes)
+		};
+	}
+	const usedPaths = /* @__PURE__ */ new Set();
+	return routes.flatMap((route) => {
+		const conflict = conflictedRoutes.get(route);
+		if (!conflict) return [route];
+		if (usedPaths.has(route.path)) return [];
+		usedPaths.add(route.path);
+		return [createConflictRoute(route, conflict)];
+	});
+}
+function handleRouteConflicts(routes, development) {
+	if (development) return createDevRouteConflictRoutes(routes);
+	assertNoRouteConflicts(routes);
+	return routes;
+}
+async function resolveRouteState(routes, plugins, ctx, development) {
+	const tabs = ctx.projectConfig.navigation?.tabs;
+	const configuredRoutes = applyConfiguredPageRoutePaths(routes, tabs, ctx.projectConfig.locales);
+	const resolved = await runHooks(plugins, "routes:resolved", {
+		routes: configuredRoutes,
+		navigation: buildNavigationTree(configuredRoutes, ctx)
+	}, ctx);
+	const finalRoutes = handleRouteConflicts(resolved.routes, development);
+	return {
+		routes: finalRoutes,
+		navigation: finalRoutes === resolved.routes ? resolved.navigation : buildNavigationTree(finalRoutes, ctx)
+	};
+}
+//#endregion
 //#region source/core/runtime/env-types.ts
 var GENERATED_FILE_NAME = "clarify-env.d.ts";
 /**
@@ -3704,7 +3895,7 @@ var ClarifyEngine = class {
 	async discoverSite() {
 		const plugins = this.ctx.plugins;
 		const contentRoot = this.ctx.contentRoot;
-		const { locales, navigation: navigationConfig } = this.ctx.projectConfig;
+		const { locales } = this.ctx.projectConfig;
 		let routes = await runPhase(plugins, "site:discover", this.ctx, async () => {
 			const options = { contentProcessor: createProjectContentProcessor(plugins, this.ctx) };
 			const discovered = locales ? await findLocalizedContentRoutes(contentRoot, locales, options) : await findContentRoutes(contentRoot, contentRoot, options);
@@ -3712,43 +3903,10 @@ var ClarifyEngine = class {
 				contentRoot,
 				routes: discovered
 			}, this.ctx);
-			return runHooks(plugins, "routes:discovered", result.routes, this.ctx);
+			return await runHooks(plugins, "routes:discovered", result.routes, this.ctx);
 		});
-		routes = await runPhase(plugins, "content:process", this.ctx, async () => {
-			const pages = routes.map((route) => ({
-				path: route.path,
-				filePath: route.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]));
-			return routes.map((route) => {
-				const page = pageByPath.get(route.path);
-				if (!page) return route;
-				return {
-					...route,
-					source: {
-						...route.source,
-						frontmatter: page.frontmatter,
-						content: page.content
-					}
-				};
-			});
-		});
-		const tabs = navigationConfig?.tabs;
-		routes = applyConfiguredPageRoutePaths(routes, tabs, locales);
-		const navigation = tabs ? locales ? buildLocalizedNavigationFromTabsConfig(routes, tabs, locales) ?? {
-			kind: "localized-tabbed",
-			locales: {}
-		} : buildNavigationFromTabsConfig(routes, tabs) : {
-			kind: "flat",
-			nodes: buildNavigation(routes)
-		};
-		const resolved = await runHooks(plugins, "routes:resolved", {
-			routes,
-			navigation
-		}, this.ctx);
+		routes = await runPhase(plugins, "content:process", this.ctx, () => resolveRoutePages(routes, plugins, this.ctx));
+		const resolved = await resolveRouteState(routes, plugins, this.ctx, this.runtime.command === "serve");
 		this.ctx.routes = resolved.routes;
 		this.ctx.navigation = resolved.navigation;
 	}
@@ -3798,8 +3956,8 @@ var ClarifyEngine = class {
 		return this.buildEnabled;
 	}
 	async configureDevServer(server) {
-		await runPhase(this.plugins, "dev:server", this.ctx, async () => {
-			await runDevConfigureServerHooks(this.plugins, server, this.ctx);
+		return runPhase(this.plugins, "dev:server", this.ctx, () => {
+			return runDevConfigureServerHooks(this.plugins, server, this.ctx);
 		});
 	}
 	async runBuildDone() {
@@ -3924,6 +4082,12 @@ Object.defineProperty(exports, "deserializeSearchIndex", {
 		return deserializeSearchIndex;
 	}
 });
+Object.defineProperty(exports, "findRouteConflicts", {
+	enumerable: true,
+	get: function() {
+		return findRouteConflicts;
+	}
+});
 Object.defineProperty(exports, "searchMcpIndex", {
 	enumerable: true,
 	get: function() {
@@ -3931,4 +4095,4 @@ Object.defineProperty(exports, "searchMcpIndex", {
 	}
 });
 
-//# sourceMappingURL=engine-Cgc71w13.cjs.map
+//# sourceMappingURL=engine-DVw8CV5R.cjs.map