@clarify-labs/cli 0.11.4 → 0.11.5

package/output/{engine-CJmXVTo5.js → engine-DuiJVdO8.js}

@@ -81,7 +81,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`,
@@ -127,7 +127,7 @@ async function compileMdxContent(content, options = {}) {
 		return {
 			ok: false,
 			diagnostic: createContentCompileDiagnostic({
-				format: "mdx",
+				format: "markdown+jsx",
 				phase: "syntax",
 				error,
 				filePath,
@@ -137,6 +137,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 = relative(contentRoot, filePath).replace(/\\/g, "/");
+	if (!sourcePath || sourcePath.startsWith("../") || 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;
@@ -152,32 +167,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) {
@@ -212,7 +238,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,
@@ -364,9 +390,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);
@@ -409,7 +432,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: {
@@ -418,7 +441,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,
@@ -430,14 +456,24 @@ async function findContentRoutes(dir, base = dir, options = {}) {
 	}
 	return routes;
 }
-function virtualModuleIdForLocalizedRoute(contentRoot, filePath) {
-	return "virtual:clarify-page/" + relative(contentRoot, filePath).replace(/\.mdx?$/, "").replace(/\.openapi\.(json|yaml|yml)$/, "").replace(/\/+/g, "/");
+function pageVirtualModuleIdForLocalizedRoute(contentRoot, filePath) {
+	return pageVirtualModuleIdFromRef(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]));
@@ -463,8 +499,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
 		});
 	}
@@ -483,7 +518,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)
+				}
 			});
 		}
 	}
@@ -495,9 +534,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
 				});
@@ -592,13 +631,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
 			});
 		}
@@ -606,7 +645,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);
@@ -800,7 +840,7 @@ function inferRouteForFile(filePath, contentRoot, defaultLocale) {
 		filePath,
 		locale: fileLocale,
 		basePath: normalizePath(basePath),
-		kind: isMdx ? "mdx" : "openapi",
+		kind: isMdx ? "markdown+jsx" : "openapi",
 		title,
 		inferred: true
 	};
@@ -1219,6 +1259,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
@@ -1246,8 +1289,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) {
@@ -1301,8 +1346,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: ")}`;
@@ -1374,13 +1419,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;
 }
@@ -1421,7 +1467,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,
@@ -1536,7 +1582,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",
@@ -1591,7 +1640,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) {
@@ -1611,7 +1660,7 @@ function createViteAdapter(engine) {
 }
 var cliPackageVersion = {
 	name: "@clarify-labs/cli",
-	version: "0.11.4",
+	version: "0.11.5",
 	license: "AGPL-3.0-only",
 	type: "module",
 	repository: {
@@ -1711,7 +1760,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) {
@@ -1783,9 +1832,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) {
@@ -1862,10 +1911,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 = [];
@@ -2356,7 +2407,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 }
 		});
 	}
@@ -2480,34 +2531,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) {
@@ -2527,9 +2551,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,
@@ -2547,7 +2568,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) {
@@ -2560,31 +2581,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 = [];
@@ -2603,7 +2623,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
@@ -2617,19 +2637,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 relative(projectRoot, filePath).replace(/[^a-zA-Z0-9_-]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
 }
@@ -2641,90 +2689,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)
 		}
 	};
 }
@@ -3133,6 +3185,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";
 /**
@@ -3673,7 +3864,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);
@@ -3681,43 +3872,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;
 	}
@@ -3767,8 +3925,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() {
@@ -3839,6 +3997,6 @@ function createClarifyEngine(options = {}) {
 	return new ClarifyEngine(options);
 }
 //#endregion
-export { deserializeSearchIndex as a, cliPackageVersionWithCaret as c, createClarifyTempDir as i, createViteAdapter as l, createClarifyEngine as n, searchMcpIndex as o, createClarifyRuntimeAliases as r, cliPackageVersion as s, ClarifyEngine as t, defineConfig as u };
+export { createClarifyTempDir as a, cliPackageVersion as c, defineConfig as d, findRouteConflicts as i, cliPackageVersionWithCaret as l, createClarifyEngine as n, deserializeSearchIndex as o, createClarifyRuntimeAliases as r, searchMcpIndex as s, ClarifyEngine as t, createViteAdapter as u };
 
-//# sourceMappingURL=engine-CJmXVTo5.js.map
+//# sourceMappingURL=engine-DuiJVdO8.js.map