@clarify-labs/cli 0.7.2 → 0.8.2

package/output/{plugin-o1rP_gts.js → plugin-D5EF3pYl.js}

@@ -8,13 +8,13 @@ import { toString } from "mdast-util-to-string";
 import shiki from "shiki";
 import { visit } from "unist-util-visit";
 import { markdownRemarkPlugins, themeBootstrapScript, themePresets } from "@clarify-labs/renderer";
-import { remark } from "remark";
+import { stringify } from "yaml";
 import matter from "gray-matter";
+import { remark } from "remark";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import SwaggerParser from "@apidevtools/swagger-parser";
 import { tmpdir } from "node:os";
-import { mkdir, writeFile } from "node:fs/promises";
 import { z } from "zod";
-import { pathToFileURL } from "node:url";
 import { build, loadConfigFromFile } from "vite";
 import { createRequire } from "node:module";
 //#region source/core/utils.ts
@@ -121,17 +121,16 @@ function withUtf8Signature(content) {
 }
 function shouldUseUtf8Signature(route) {
 	if (route.kind === "mdx") return true;
-	return /\.ya?ml$/i.test(route.contentArtifactUrl ?? "");
+	return false;
 }
 function routeToMarkdownArtifactUrl(routePath) {
 	return `${routePath === "/" ? "/index" : routePath.replace(/\/$/, "")}.md`;
 }
-function routeToOpenAPIArtifactUrl(routePath, filePath) {
-	const extension = extname(filePath).toLowerCase() || ".json";
-	return `${routePath === "/" ? "/index" : routePath.replace(/\/$/, "")}.openapi${extension}`;
+function 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, route.filePath) : routeToMarkdownArtifactUrl(route.path);
+	for (const route of routes) route.contentArtifactUrl = route.kind === "openapi" ? routeToOpenAPIArtifactUrl(route.path) : routeToMarkdownArtifactUrl(route.path);
 }
 function readRouteContent(route) {
 	if (route.content !== void 0) return route.content;
@@ -141,40 +140,81 @@ function readRouteArtifactContent(route) {
 	const content = readRouteContent(route);
 	return shouldUseUtf8Signature(route) ? withUtf8Signature(content) : content;
 }
-function writeContentArtifactFiles(routes, outputDirectory) {
+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 (sections?.length) return `Covers ${sections.join(", ")}.`;
+	if (route.keywords?.length) return `Related topics: ${route.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 description = llmsTxtDescription(route);
+	return description ? `- [${route.title}](${basePath}${route.contentArtifactUrl}): ${description}` : `- [${route.title}](${basePath}${route.contentArtifactUrl})`;
+}
+function llmsTxtLocaleLabel(locale, projectConfig) {
+	return projectConfig.i18n?.locales.find((item) => item.code === locale)?.label ?? locale;
+}
+function groupRoutesByLocale(routes) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const route of routes) {
+		const key = route.locale ?? "default";
+		groups.set(key, [...groups.get(key) ?? [], route]);
+	}
+	return groups;
+}
+function groupLlmsTxtRoutesByLocale(routes, projectConfig) {
+	const routesBySource = /* @__PURE__ */ new Map();
+	const defaultLocale = projectConfig.i18n?.defaultLocale;
 	for (const route of routes) {
-		if (!route.contentArtifactUrl) continue;
-		const outFile = join(outputDirectory, route.contentArtifactUrl.replace(/^\//, ""));
-		mkdirSync(dirname(outFile), { recursive: true });
-		writeFileSync(outFile, readRouteArtifactContent(route), "utf-8");
+		const sourceKey = `${route.locale ?? defaultLocale ?? "default"}:${route.basePath ?? route.contentArtifactUrl ?? route.path}`;
+		const previousRoute = routesBySource.get(sourceKey);
+		if (!previousRoute || previousRoute.locale && !route.locale) routesBySource.set(sourceKey, route);
 	}
+	return groupRoutesByLocale([...routesBySource.values()].map((route) => ({
+		...route,
+		locale: route.locale ?? defaultLocale
+	})));
+}
+function llmsTxtDocsSectionTitle(locale, groupCount, projectConfig) {
+	if (groupCount <= 1) return "Docs";
+	return `Docs - ${locale === "default" ? "Default" : llmsTxtLocaleLabel(locale, projectConfig)}`;
 }
 function createLlmsTxt(routes, projectConfig) {
 	const basePath = normalizeBasePath(projectConfig.routePrefix);
 	const lines = [`# ${projectConfig.title}`, ""];
 	if (projectConfig.description) lines.push(`> ${projectConfig.description}`, "");
-	lines.push("## Docs");
-	for (const route of routes.filter((route) => route.kind === "mdx")) {
-		if (!route.contentArtifactUrl) continue;
-		lines.push(`- [${route.title}](${basePath}${route.contentArtifactUrl})`);
+	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));
+	if (mdxRoutes.length > 0) {
+		const localizedGroups = groupLlmsTxtRoutesByLocale(mdxRoutes, projectConfig);
+		for (const [locale, localeRoutes] of localizedGroups) {
+			lines.push(`## ${llmsTxtDocsSectionTitle(locale, localizedGroups.size, projectConfig)}`);
+			for (const route of localeRoutes) {
+				const item = llmsTxtListItem(route, basePath);
+				if (item) lines.push(item);
+			}
+			lines.push("");
+		}
 	}
-	const openApiRoutes = routes.filter((route) => route.kind === "openapi");
+	const openApiRoutes = routes.filter((route) => route.kind === "openapi" && isLlmsTxtRoute(route));
 	if (openApiRoutes.length > 0) {
-		lines.push("", "## OpenAPI");
+		if (lines.at(-1) !== "") lines.push("");
+		lines.push("## OpenAPI");
 		for (const route of openApiRoutes) {
-			if (!route.contentArtifactUrl) continue;
-			lines.push(`- [${route.title}](${basePath}${route.contentArtifactUrl})`);
+			const item = llmsTxtListItem(route, basePath);
+			if (item) lines.push(item);
 		}
 	}
+	while (lines.at(-1) === "") lines.pop();
 	return `${lines.join("\n")}\n`;
 }
 function createLlmsTxtArtifact(routes, projectConfig) {
 	return withUtf8Signature(createLlmsTxt(routes, projectConfig));
 }
-function writeLlmsTxt(routes, projectConfig, outputDirectory) {
-	mkdirSync(outputDirectory, { recursive: true });
-	writeFileSync(join(outputDirectory, "llms.txt"), createLlmsTxtArtifact(routes, projectConfig), "utf-8");
-}
 //#endregion
 //#region source/plugins/content-artifacts/server.ts
 function normalizeRoutePrefix$1(routePrefix) {
@@ -187,7 +227,6 @@ function resolveContentArtifactPath(url, projectConfig) {
 	return basePath && requestPath.startsWith(basePath) ? requestPath.slice(basePath.length) || "/" : requestPath;
 }
 function resolveContentArtifactType(route) {
-	if (route.kind === "openapi" && /\.ya?ml$/i.test(route.contentArtifactUrl ?? "")) return "text/yaml; charset=utf-8";
 	return route.kind === "openapi" ? "application/json; charset=utf-8" : "text/markdown; charset=utf-8";
 }
 function serveContentArtifacts(req, res, projectConfig, routes) {
@@ -198,6 +237,18 @@ function serveContentArtifacts(req, res, projectConfig, routes) {
 		res.end(createLlmsTxtArtifact(routes, projectConfig), "utf8");
 		return true;
 	}
+	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);
+			res.statusCode = 200;
+			res.setHeader("Content-Type", "text/yaml; charset=utf-8");
+			res.end(stringify(spec, { lineWidth: 0 }), "utf8");
+			return true;
+		}
+		return false;
+	}
 	const route = routes.find((route) => route.contentArtifactUrl === contentPath);
 	if (!route) return false;
 	res.statusCode = 200;
@@ -221,12 +272,28 @@ function createContentArtifactsPlugin() {
 					next();
 				});
 			},
-			"build:done": (ctx) => {
-				const outputDirectory = ctx.generateOptions.outputDirectory;
-				if (!outputDirectory) return;
-				const outputRoot = join(ctx.generateOptions.projectRoot, outputDirectory);
-				writeContentArtifactFiles(ctx.routes, outputRoot);
-				writeLlmsTxt(ctx.routes, ctx.projectConfig, outputRoot);
+			"build:assets": (ctx) => {
+				const assets = [];
+				for (const route of ctx.routes) {
+					if (!route.contentArtifactUrl) continue;
+					assets.push({
+						fileName: route.contentArtifactUrl.replace(/^\//, ""),
+						source: readRouteArtifactContent(route)
+					});
+					if (route.kind === "openapi" && route.content) {
+						const yamlFileName = route.contentArtifactUrl.replace(/\.json$/, ".yaml");
+						const spec = JSON.parse(route.content);
+						assets.push({
+							fileName: yamlFileName.replace(/^\//, ""),
+							source: stringify(spec, { lineWidth: 0 })
+						});
+					}
+				}
+				assets.push({
+					fileName: "llms.txt",
+					source: createLlmsTxtArtifact(ctx.routes, ctx.projectConfig)
+				});
+				return assets;
 			}
 		}
 	};
@@ -302,8 +369,103 @@ function parseFrontmatter(content) {
 	};
 }
 //#endregion
+//#region source/parsers/content.ts
+async function transformContent(transform, input) {
+	return transform ? await transform(input) : input;
+}
+function createContentProcessor(transform) {
+	return {
+		async processMdx(source, filePath) {
+			const { frontmatter, content } = parseFrontmatter(source);
+			const transformed = await transformContent(transform, {
+				kind: "mdx",
+				source,
+				filePath,
+				frontmatter,
+				content
+			});
+			return {
+				frontmatter: transformed.frontmatter,
+				content: transformed.content
+			};
+		},
+		async processText(source, kind, filePath) {
+			return (await transformContent(transform, {
+				kind,
+				source,
+				filePath,
+				frontmatter: {},
+				content: source
+			})).content;
+		}
+	};
+}
+//#endregion
+//#region source/core/hooks.ts
+async function runHooks(plugins, hookName, input, ctx) {
+	let result = input;
+	for (const plugin of plugins) {
+		const hook = plugin.hooks?.[hookName];
+		if (!hook) continue;
+		try {
+			result = await hook(result, ctx);
+		} catch (err) {
+			throw new Error(`[clarify] plugin "${plugin.name}" hook "${hookName}" failed: ${err}`, { cause: err });
+		}
+	}
+	return result;
+}
+async function runDevConfigureServerHooks(plugins, server, ctx) {
+	for (const plugin of plugins) {
+		const hook = plugin.hooks?.["dev:configureServer"];
+		if (!hook) continue;
+		try {
+			await hook(server, ctx);
+		} catch (err) {
+			throw new Error(`[clarify] plugin "${plugin.name}" hook "dev:configureServer" failed: ${err}`, { cause: err });
+		}
+	}
+}
+async function runBuildAssetsHooks(plugins, ctx) {
+	const assets = [];
+	for (const plugin of plugins) {
+		const hook = plugin.hooks?.["build:assets"];
+		if (!hook) continue;
+		try {
+			const pluginAssets = await hook(ctx);
+			assets.push(...pluginAssets);
+		} catch (err) {
+			throw new Error(`[clarify] plugin "${plugin.name}" hook "build:assets" failed: ${err}`, { cause: err });
+		}
+	}
+	return assets;
+}
+async function runBuildDoneHooks(plugins, ctx) {
+	for (const plugin of plugins) {
+		const hook = plugin.hooks?.["build:done"];
+		if (!hook) continue;
+		try {
+			await hook(ctx);
+		} catch (err) {
+			throw new Error(`[clarify] plugin "${plugin.name}" hook "build:done" failed: ${err}`, { cause: err });
+		}
+	}
+}
+//#endregion
+//#region source/core/content.ts
+var contentProcessors = /* @__PURE__ */ new WeakMap();
+function createProjectContentProcessor(plugins, ctx) {
+	return createContentProcessor((input) => runHooks(plugins, "content:transform", input, ctx));
+}
+function setProjectContentProcessor(ctx, processor) {
+	contentProcessors.set(ctx, processor);
+}
+function getProjectContentProcessor(ctx) {
+	return contentProcessors.get(ctx);
+}
+//#endregion
 //#region source/parsers/routes.ts
-function kebabToTitle$1(str) {
+function kebabToTitle(str) {
 	return str.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
 }
 function parseMdxTree(content) {
@@ -368,32 +530,33 @@ function routePathFromRef(ref, explicitPath) {
 function virtualModuleIdFromRef(ref) {
 	return "virtual:clarify-page/" + ref.replace(/\.mdx?$/, "").replace(/\.openapi\.(json|yaml|yml)$/, "").replace(/\/+/g, "/");
 }
-function localizedRoutePath(basePath, locale, i18n) {
+function localizedRoutePath(basePath, locale, _i18n) {
 	const normalizedBasePath = normalizePath(basePath);
-	if (locale === i18n.defaultLocale) return normalizedBasePath;
 	const prefix = normalizePath(locale);
 	return normalizedBasePath === "/" ? prefix : normalizePath(`${prefix}${normalizedBasePath}`);
 }
 function resolveLocalizedText(text, locale, fallbackLocale) {
-	if (typeof text === "string" || text === void 0) return text;
+	if (typeof text === "string") return text;
+	if (text === void 0) return void 0;
 	return text[locale] ?? (fallbackLocale ? text[fallbackLocale] : void 0) ?? Object.values(text)[0];
 }
-function findContentRoutes(dir, base = dir) {
+async function findContentRoutes(dir, base = dir, options = {}) {
 	const routes = [];
 	if (!existsSync(dir)) return routes;
 	const entries = readdirSync(dir, { withFileTypes: true });
 	for (const entry of entries) {
 		const fullPath = join(dir, entry.name);
-		if (entry.isDirectory()) routes.push(...findContentRoutes(fullPath, base));
+		if (entry.isDirectory()) routes.push(...await findContentRoutes(fullPath, base, options));
 		else if (entry.isFile() && /\.mdx?$/.test(entry.name)) {
 			const relativePath = relative(base, fullPath);
 			const pathParts = relativePath.replace(/\.mdx?$/, "").split("/");
 			const cleanPath = ("/" + pathParts.map((p) => p === "index" ? "" : p).filter(Boolean).join("/")).replace(/\/+/g, "/").replace(/\/$/, "") || "/";
-			const { frontmatter, content } = parseFrontmatter(readFileSync(fullPath, "utf-8"));
+			const source = readFileSync(fullPath, "utf-8");
+			const { frontmatter, content } = await (options.contentProcessor ?? createContentProcessor()).processMdx(source, fullPath);
 			let title = typeof frontmatter.title === "string" ? frontmatter.title : "";
 			if (!title) {
 				const lastPart = pathParts[pathParts.length - 1] ?? "";
-				title = kebabToTitle$1(lastPart === "index" ? pathParts.length >= 2 ? pathParts[pathParts.length - 2] : extractH1(content) : lastPart) || "Untitled";
+				title = kebabToTitle(lastPart === "index" ? pathParts.length >= 2 ? pathParts[pathParts.length - 2] : extractH1(content) : lastPart) || "Untitled";
 			}
 			routes.push({
 				path: cleanPath,
@@ -417,9 +580,9 @@ function frontmatterKeywords(frontmatter) {
 	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 withAlternates$2(route, routes, i18n) {
+function withAlternates(route, routes, i18n) {
 	const basePath = route.basePath ?? route.path;
-	const routeByLocaleAndBase = new Map(routes.map((route) => [`${route.locale ?? ""}:${route.basePath ?? route.path}`, route]));
+	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]));
 	const alternates = Object.fromEntries(i18n.locales.flatMap((locale) => {
 		const alternate = routeByLocaleAndBase.get(`${locale.code}:${basePath}`);
 		return alternate ? [[locale.code, alternate.path]] : [];
@@ -441,7 +604,7 @@ function buildNavigation(routes) {
 			if (!node) {
 				node = {
 					path: pathSoFar,
-					title: i === parts.length - 1 ? route.title : kebabToTitle$1(parts[i]),
+					title: i === parts.length - 1 ? route.title : kebabToTitle(parts[i]),
 					children: []
 				};
 				current.push(node);
@@ -513,7 +676,21 @@ function applyConfiguredPageRoutePaths(routes, tabs, i18n) {
 		}
 	}
 	const nextRoutes = [...routes, ...additions];
-	return i18n ? nextRoutes.map((route) => withAlternates$2(route, nextRoutes, i18n)) : nextRoutes;
+	const routesWithAlternates = i18n ? nextRoutes.map((route) => withAlternates(route, nextRoutes, i18n)) : nextRoutes;
+	if (!i18n) return routesWithAlternates;
+	const bareRoutes = [];
+	const seenBare = new Set(routesWithAlternates.map((r) => r.path));
+	for (const route of routesWithAlternates) {
+		if (route.locale !== i18n.defaultLocale) continue;
+		const bp = route.basePath ?? route.path;
+		if (bp === route.path || seenBare.has(bp)) continue;
+		seenBare.add(bp);
+		bareRoutes.push({
+			...route,
+			path: bp
+		});
+	}
+	return [...routesWithAlternates, ...bareRoutes];
 }
 function buildNavigationFromPagesConfig(routes, config) {
 	if (!config || config === "FileTree") return buildNavigation(routes);
@@ -541,7 +718,7 @@ function buildNavigationFromConfig(routes, config) {
 				const route = routeMap.get(path);
 				return {
 					path,
-					title: resolveLocalizedText(title, "", "") ?? route?.title ?? kebabToTitle$1(path.split("/").pop() ?? openapiRef),
+					title: resolveLocalizedText(title, "", "") ?? route?.title ?? kebabToTitle(path.split("/").pop() ?? openapiRef),
 					icon,
 					sections: route?.sections ? navigationSections(route.sections) : void 0
 				};
@@ -551,7 +728,7 @@ function buildNavigationFromConfig(routes, config) {
 			const route = routeMap.get(path);
 			return {
 				path: redirect ? normalizePath(redirect) : path,
-				title: resolveLocalizedText(title, "", "") ?? route?.title ?? kebabToTitle$1(path.split("/").pop() ?? ref),
+				title: resolveLocalizedText(title, "", "") ?? route?.title ?? kebabToTitle(path.split("/").pop() ?? ref),
 				icon,
 				sections: route?.sections ? navigationSections(route.sections) : void 0
 			};
@@ -586,7 +763,7 @@ function buildLocalizedNavigationForLocale(routes, config, locale, i18n) {
 			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$1(basePath.split("/").pop() ?? ref),
+				title: resolveLocalizedText(title, locale, i18n.defaultLocale) ?? route?.title ?? kebabToTitle(basePath.split("/").pop() ?? ref),
 				icon,
 				sections: route?.sections ? navigationSections(route.sections) : void 0
 			};
@@ -632,8 +809,12 @@ var OPENAPI_HTTP_METHODS = [
 function errorMessage(error) {
 	return error instanceof Error ? error.message : String(error);
 }
-function kebabToTitle(str) {
-	return str.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+function isSameOpenAPIFile(url, filePath) {
+	try {
+		return resolve(fileURLToPath(url)) === resolve(filePath);
+	} catch {
+		return resolve(url) === resolve(filePath);
+	}
 }
 function findOpenAPIRoutes(dir, base = dir) {
 	const routes = [];
@@ -654,8 +835,7 @@ function findOpenAPIRoutes(dir, base = dir) {
 			filePath: fullPath,
 			virtualModuleId: virtualModuleIdFromRef(ref),
 			title: kebabToTitle(cleanPath.split("/").pop() ?? "API"),
-			kind: "openapi",
-			content: readFileSync(fullPath, "utf-8")
+			kind: "openapi"
 		});
 	}
 	return routes;
@@ -664,6 +844,20 @@ function operationMatchesTags(operationTags, filterTags) {
 	if (!filterTags?.length) return true;
 	return operationTags?.some((tag) => filterTags.includes(tag)) ?? false;
 }
+/** 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;
+	}
+	return {
+		...spec,
+		paths: filteredPaths
+	};
+}
 /** Extract endpoint operations from an OpenAPI spec as page sections. */
 function extractOpenAPISections(spec, filterTags) {
 	const sections = [];
@@ -685,12 +879,26 @@ function extractOpenAPISections(spec, filterTags) {
 	}
 	return sections;
 }
-async function readOpenAPISpec(filePath) {
+async function readOpenAPISpec(filePath, contentProcessor) {
 	try {
-		return {
+		if (!contentProcessor) return {
+			ok: true,
+			spec: await SwaggerParser.dereference(filePath)
+		};
+		const source = readFileSync(filePath, "utf-8");
+		const transformedSource = await contentProcessor.processText(source, "openapi", filePath);
+		if (transformedSource === source) return {
 			ok: true,
 			spec: await SwaggerParser.dereference(filePath)
 		};
+		return {
+			ok: true,
+			spec: await SwaggerParser.dereference(filePath, { resolve: { transformedOpenAPISource: {
+				order: 1,
+				canRead: (file) => isSameOpenAPIFile(file.url, filePath),
+				read: () => transformedSource
+			} } })
+		};
 	} catch (error) {
 		return {
 			ok: false,
@@ -705,12 +913,14 @@ async function readOpenAPISpec(filePath) {
 }
 //#endregion
 //#region source/core/virtual-modules.ts
-var VIRTUAL_CONFIG = "virtual:clarify-config";
-var VIRTUAL_ROUTES = "virtual:clarify-routes";
-var VIRTUAL_SERVER_ROUTES = "virtual:clarify-routes/server";
-var VIRTUAL_RUNTIME = "virtual:clarify-runtime";
-var VIRTUAL_CLIENT_ENTRY = "virtual:clarify-entry-client";
-var RESOLVED_CLIENT_ENTRY = "\0virtual:clarify-entry-client";
+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_SLOTS = "virtual:clarify/slots";
+var VIRTUAL_SLOT = "virtual:clarify/slot";
+var VIRTUAL_CLIENT_ENTRY = "virtual:clarify/entry-client";
+var RESOLVED_CLIENT_ENTRY = "\0virtual:clarify/entry-client";
 function resolveVirtualId(id) {
 	return "\0" + id;
 }
@@ -751,65 +961,117 @@ function generateRoutesModule(routes, resolvedNavigation, projectConfig, mode =
 	const navigation = resolvedNavigation ?? (projectConfig?.tabs ? projectConfig.i18n ? buildLocalizedNavigationFromTabsConfig(routes, projectConfig.tabs, projectConfig.i18n) ?? {} : buildNavigationFromTabsConfig(routes, projectConfig.tabs) : buildNavigation(routes));
 	return `${imports}\n\nexport const routes = [\n${routesArray}\n];\n\nexport const navigation = ${JSON.stringify(navigation, null, 2)};\n`;
 }
-function createRuntimeModule(options = {}) {
-	const imports = [options.bannerComponentSource === "path" && options.imports?.bannerComponent ? `import BannerComponent from ${moduleSpecifier(options.imports.bannerComponent)};` : void 0, options.footerComponentSource === "path" && options.imports?.footerComponent ? `import FooterComponent from ${moduleSpecifier(options.imports.footerComponent)};` : void 0].filter(Boolean).join("\n");
-	const exports = `export const openApis = {};
-export const bannerComponent = ${options.bannerComponentSource === "path" ? "BannerComponent" : "undefined"};
-export const footerComponent = ${options.footerComponentSource === "path" ? "FooterComponent" : "undefined"};`;
-	return imports ? `${imports}\n${exports}` : exports;
-}
 function createClientEntryModule(options = {}) {
 	return `
 import '@clarify-labs/renderer/style.css';
 import { render } from '@clarify-labs/renderer/client';
 import { routes, navigation } from '${VIRTUAL_ROUTES}';
 import { config } from '${VIRTUAL_CONFIG}';
-import { openApis, bannerComponent, footerComponent } from '${VIRTUAL_RUNTIME}';
-render({ config, routes, navigation, openApis, bannerComponent, footerComponent, themeEditor: ${JSON.stringify(options.themeEditor ?? false)} });`;
+import { openApis } from '${VIRTUAL_OPENAPI}';
+import { runtimeSlots } from '${VIRTUAL_SLOTS}';
+render({ config, routes, navigation, openApis, runtimeSlots, themeEditor: ${JSON.stringify(options.themeEditor ?? false)} });`;
+}
+/**
+* Collect every plugin's `slots` declarations into a single runtime registry
+* module. Component modules are exported as lazy import factories so the
+* renderer can decide whether to code-split (client) or pre-resolve (SSR).
+*
+* Relative component paths are resolved against the project `root` so that
+* the generated `import()` call uses an absolute specifier — Vite cannot
+* resolve relative imports from virtual modules.
+*
+* Slot name validity is enforced at compile time by the `UISlotName`
+* type — no runtime validation is needed.
+*/
+function createRuntimeSlotsModule(plugins = [], root = process.cwd()) {
+	const registrations = [];
+	for (const plugin of plugins) for (const slot of plugin.slots ?? []) registrations.push({
+		plugin: plugin.name,
+		slot
+	});
+	if (registrations.length === 0) return "export const runtimeSlots = {};\n";
+	const grouped = /* @__PURE__ */ new Map();
+	for (const { plugin, slot } of registrations) {
+		if (slot.name.endsWith(".replace")) {
+			const existing = grouped.get(slot.name);
+			if (existing) console.warn(`[clarify] Multiple plugins register slot "${slot.name}": "${plugin}" overrides "${existing[existing.length - 1]}". Only the last registration is used.`);
+		}
+		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 list = grouped.get(slot.name) ?? [];
+		list.push(entry);
+		grouped.set(slot.name, list);
+	}
+	return `export const runtimeSlots = {\n${[...grouped.entries()].map(([name, list]) => `  ${JSON.stringify(name)}: [\n    ${list.join(",\n    ")}\n  ]`).join(",\n")}\n};\n`;
+}
+/**
+* Re-exports the slot context hook from the renderer so plugin components can
+* `import { useSlot } from 'virtual:clarify/slot'` without depending on
+* renderer internals directly.
+*/
+function createSlotModule() {
+	return `export { useSlot } from '@clarify-labs/renderer';\n`;
 }
 function buildVirtualModules(args) {
 	const modules = /* @__PURE__ */ new Map();
 	const clientEntryModule = createClientEntryModule({ themeEditor: args.themeEditor });
-	const bannerComponent = args.projectConfig.banner;
-	const bannerComponentSource = typeof bannerComponent === "string" ? "path" : void 0;
-	const bannerComponentImport = typeof bannerComponent === "string" ? bannerComponent : void 0;
-	const footerComponent = args.projectConfig.footer;
-	const footerComponentSource = typeof footerComponent === "string" ? "path" : void 0;
-	const footerComponentImport = typeof footerComponent === "string" ? footerComponent : void 0;
+	const allPlugins = [...args.plugins ?? []];
 	modules.set(VIRTUAL_CONFIG, generateConfigModule(args.projectConfig, args.generateOptions));
 	modules.set(VIRTUAL_ROUTES, generateRoutesModule(args.routes, args.navigation, args.projectConfig, "client"));
 	modules.set(VIRTUAL_SERVER_ROUTES, generateRoutesModule(args.routes, args.navigation, args.projectConfig, "server"));
-	modules.set(VIRTUAL_RUNTIME, createRuntimeModule({
-		bannerComponentSource,
-		footerComponentSource,
-		imports: {
-			bannerComponent: bannerComponentImport,
-			footerComponent: footerComponentImport
-		}
-	}));
+	modules.set(VIRTUAL_SLOTS, createRuntimeSlotsModule(allPlugins, args.generateOptions.projectRoot));
+	modules.set(VIRTUAL_OPENAPI, generateOpenApiModule());
+	modules.set(VIRTUAL_SLOT, createSlotModule());
 	modules.set(VIRTUAL_CLIENT_ENTRY, clientEntryModule);
 	modules.set(RESOLVED_CLIENT_ENTRY, clientEntryModule);
 	for (const route of args.routes) modules.set(route.virtualModuleId, `export { default } from ${moduleSpecifier(route.filePath)};`);
 	return modules;
 }
+function generateOpenApiModule() {
+	return `export const openApis = {};`;
+}
 //#endregion
 //#region source/plugins/openapi/virtual-modules.ts
-var openApiRegistryModuleId = VIRTUAL_RUNTIME;
-function generateOpenAPIRegistryModule(openApis, runtimeModule = "") {
-	const openApisExport = `export const openApis = ${JSON.stringify(openApis)};`;
-	const openApisPlaceholder = /export const openApis = \{\};?/;
-	if (!runtimeModule) return openApisExport;
-	if (openApisPlaceholder.test(runtimeModule)) return runtimeModule.replace(openApisPlaceholder, openApisExport);
-	return runtimeModule;
-}
-function generateOpenAPIModule(spec, tagFilter) {
-	return `import { createElement } from 'react';
-import { OpenApiDocument } from '@clarify-labs/renderer';
-const spec = ${JSON.stringify(spec)};
-const tagFilter = ${JSON.stringify(tagFilter)};
-export default function OpenApiRoutePage() {
-  return createElement(OpenApiDocument, { spec, tagFilter });
-}`;
+var openApiRegistryModuleId = VIRTUAL_OPENAPI;
+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)};`;
+}
+/** Generate a virtual module that exports a single spec as default. */
+function generateOpenAPISpecModule(spec) {
+	return `export default ${JSON.stringify(spec)};`;
+}
+function generateOpenAPIPageModule(opts) {
+	const { specKey, specRegistryKey, tagFilter } = opts;
+	return [
+		`import { createElement, useState, useEffect, useRef } from 'react';`,
+		`import { OpenApiDocument, useOpenApis } from '@clarify-labs/renderer';`,
+		`const SPEC_KEY = ${JSON.stringify(specRegistryKey)};`,
+		`const TAG_FILTER = ${JSON.stringify(tagFilter ?? void 0)};`,
+		`let loadPromise = null;`,
+		`function loadSpec() {`,
+		`  if (!loadPromise) loadPromise = import(${JSON.stringify(specVirtualModuleId(specKey))}).then(function(m) { return m.default; });`,
+		`  return loadPromise;`,
+		`}`,
+		`export default function OpenApiRoutePage() {`,
+		`  const specs = useOpenApis();`,
+		`  const serverSpec = specs[SPEC_KEY];`,
+		`  const [spec, setSpec] = useState(serverSpec || null);`,
+		`  const mountedRef = useRef(false);`,
+		`  useEffect(function() {`,
+		`    if (mountedRef.current) return;`,
+		`    mountedRef.current = true;`,
+		`    if (spec) return;`,
+		`    loadSpec().then(setSpec);`,
+		`  }, []);`,
+		`  if (!spec) return null;`,
+		`  return createElement(OpenApiDocument, { spec: spec, tagFilter: TAG_FILTER });`,
+		`}`
+	].join("\n");
 }
 function generateOpenAPIErrorModule(diagnostic) {
 	return `import { createElement } from 'react';
@@ -843,18 +1105,6 @@ function collectOpenAPIPageItems(config) {
 	for (const tab of config.tabs ?? []) visitPages(tab.pages);
 	return items;
 }
-function withAlternates$1(route, routes, i18n) {
-	const basePath = route.basePath ?? route.path;
-	const routeByLocaleAndBase = new Map(routes.map((route) => [`${route.locale ?? ""}:${route.basePath ?? route.path}`, route]));
-	const alternates = Object.fromEntries(i18n.locales.flatMap((locale) => {
-		const alternate = routeByLocaleAndBase.get(`${locale.code}:${basePath}`);
-		return alternate ? [[locale.code, alternate.path]] : [];
-	}));
-	return {
-		...route,
-		alternates
-	};
-}
 function virtualModuleIdFromPath(path) {
 	return `virtual:clarify-page/${path.replace(/^\/+/, "") || "index"}`;
 }
@@ -884,10 +1134,15 @@ function createConfiguredOpenAPIRoutes(routes, config) {
 		}
 	}
 	const nextRoutes = [...routes, ...additions];
-	return config.i18n ? nextRoutes.map((route) => withAlternates$1(route, nextRoutes, config.i18n)) : nextRoutes;
+	return config.i18n ? nextRoutes.map((route) => withAlternates(route, nextRoutes, config.i18n)) : nextRoutes;
+}
+/** Derive a stable, deduplicated key from an absolute spec file path. */
+function specFileKeyFromPath(filePath, projectRoot) {
+	return relative(projectRoot, filePath).replace(/[^a-zA-Z0-9_-]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
 }
 function createOpenAPIPlugin() {
-	const specs = {};
+	/** specs keyed by specFileKey (deduplicated per source file). */
+	const specs = /* @__PURE__ */ new Map();
 	return {
 		name: "clarify:openapi",
 		hooks: {
@@ -896,7 +1151,7 @@ function createOpenAPIPlugin() {
 				routes: [...input.routes, ...findOpenAPIRoutes(input.contentRoot)]
 			}),
 			"routes:discovered": async (routes, ctx) => {
-				for (const key of Object.keys(specs)) delete specs[key];
+				specs.clear();
 				const nextRoutes = createConfiguredOpenAPIRoutes(routes, ctx.projectConfig);
 				const specByFilePath = /* @__PURE__ */ new Map();
 				for (const route of nextRoutes.filter((route) => route.kind === "openapi")) {
@@ -904,7 +1159,7 @@ function createOpenAPIPlugin() {
 					const result = specFromCache ? {
 						ok: true,
 						spec: specFromCache
-					} : await readOpenAPISpec(route.filePath);
+					} : await readOpenAPISpec(route.filePath, getProjectContentProcessor(ctx));
 					if (!result.ok) {
 						route.diagnostic = result.diagnostic;
 						route.title = route.title || "OpenAPI parse error";
@@ -913,24 +1168,45 @@ function createOpenAPIPlugin() {
 					}
 					const spec = result.spec;
 					specByFilePath.set(route.filePath, spec);
-					specs[route.virtualModuleId] = {
+					const specKey = specFileKeyFromPath(route.filePath, ctx.generateOptions.projectRoot);
+					route.specFileKey = specKey;
+					specs.set(specKey, {
 						spec,
-						tagFilter: route.openapiTagFilter
-					};
-					specs[`virtual:clarify-page/${route.path.replace(/^\//, "")}`] = {
-						spec,
-						tagFilter: route.openapiTagFilter
-					};
+						filePath: route.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);
 				}
 				return nextRoutes;
 			},
 			"modules:before": (modules, ctx) => {
-				modules.set(openApiRegistryModuleId, generateOpenAPIRegistryModule(Object.fromEntries(Object.entries(specs).map(([moduleId, entry]) => [moduleId, entry.spec])), modules.get(openApiRegistryModuleId)));
-				for (const [moduleId, entry] of Object.entries(specs)) modules.set(moduleId, generateOpenAPIModule(entry.spec, entry.tagFilter));
-				for (const route of ctx.routes.filter((route) => route.kind === "openapi" && route.diagnostic)) if (route.diagnostic) modules.set(route.virtualModuleId, generateOpenAPIErrorModule(route.diagnostic));
+				const registryEntries = {};
+				for (const route of ctx.routes) {
+					if (route.kind !== "openapi" || !route.specFileKey) continue;
+					const spec = specs.get(route.specFileKey)?.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;
+				}
+				modules.set(openApiRegistryModuleId, generateOpenAPIRegistryModule(registryEntries));
+				for (const [specKey, entry] of specs) modules.set(specVirtualModuleId(specKey), generateOpenAPISpecModule(entry.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 base = (route.basePath ?? route.path).replace(/^\//, "");
+						const specRegistryKey = route.locale ? `virtual:clarify-page/${route.locale}/${base}` : `virtual:clarify-page/${base}`;
+						modules.set(route.virtualModuleId, generateOpenAPIPageModule({
+							specKey: route.specFileKey,
+							specRegistryKey,
+							tagFilter: route.openapiTagFilter
+						}));
+					}
+				}
 				return modules;
 			}
 		}
@@ -1148,22 +1424,22 @@ function createRobotsTxt(config) {
 		""
 	].join("\n");
 }
-async function writeSeoFiles(outputRoot, routes, config) {
-	const sitemap = createSitemapXml(routes, config);
-	const robots = createRobotsTxt(config);
-	if (!sitemap || !robots) return;
-	await mkdir(outputRoot, { recursive: true });
-	await Promise.all([writeFile(join(outputRoot, "sitemap.xml"), sitemap, "utf-8"), writeFile(join(outputRoot, "robots.txt"), robots, "utf-8")]);
-}
 //#endregion
 //#region source/plugins/seo/index.ts
 function createSeoPlugin() {
 	return {
 		name: "clarify:seo",
-		hooks: { async "build:done"(ctx) {
-			const outputDirectory = ctx.generateOptions.outputDirectory;
-			if (!outputDirectory) return;
-			await writeSeoFiles(join(ctx.generateOptions.projectRoot, outputDirectory), ctx.routes, ctx.projectConfig);
+		hooks: { "build:assets"(ctx) {
+			const sitemap = createSitemapXml(ctx.routes, ctx.projectConfig);
+			const robots = createRobotsTxt(ctx.projectConfig);
+			if (!sitemap || !robots) return [];
+			return [{
+				fileName: "sitemap.xml",
+				source: sitemap
+			}, {
+				fileName: "robots.txt",
+				source: robots
+			}];
 		} }
 	};
 }
@@ -1200,9 +1476,51 @@ function createSourceLinksPlugin() {
 	};
 }
 //#endregion
+//#region source/parsers/variables.ts
+var variablePattern = /{{\s*([A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*)\s*}}/g;
+function getVariableValue(variables, path) {
+	let current = variables;
+	for (const segment of path.split(".")) {
+		if (!current || typeof current !== "object" || Array.isArray(current)) return void 0;
+		current = current[segment];
+	}
+	return current;
+}
+function stringifyVariableValue(variables, path, stack) {
+	if (stack.includes(path)) throw new Error(`[clarify] variable "${path}" contains a circular reference: ${[...stack, path].join(" -> ")}`);
+	const value = getVariableValue(variables, path);
+	if (value === void 0 || typeof value === "object") return void 0;
+	if (typeof value !== "string") return String(value);
+	return value.replace(variablePattern, (match, nestedPath) => stringifyVariableValue(variables, nestedPath, [...stack, path]) ?? match);
+}
+function applyVariables(content, variables = {}) {
+	return content.replace(variablePattern, (match, path) => stringifyVariableValue(variables, path, []) ?? match);
+}
+//#endregion
+//#region source/plugins/variables/index.ts
+function applyVariablesToFrontmatter(frontmatter, variables) {
+	const nextFrontmatter = { ...frontmatter };
+	for (const key of ["title", "description"]) {
+		if (typeof nextFrontmatter[key] !== "string") continue;
+		nextFrontmatter[key] = applyVariables(nextFrontmatter[key], variables);
+	}
+	return nextFrontmatter;
+}
+function createVariablesPlugin() {
+	return {
+		name: "clarify:variables",
+		hooks: { "content:transform": (input, ctx) => ({
+			...input,
+			frontmatter: applyVariablesToFrontmatter(input.frontmatter, ctx.projectConfig.variables),
+			content: applyVariables(input.content, ctx.projectConfig.variables)
+		}) }
+	};
+}
+//#endregion
 //#region source/core/builtin.ts
 function createBuiltinPlugins(options = {}) {
 	const plugins = [
+		createVariablesPlugin(),
 		createOpenAPIPlugin(),
 		createSourceLinksPlugin(),
 		createContentArtifactsPlugin(),
@@ -1261,18 +1579,23 @@ var clarifyNavbarLinkSchema = z.object({
 	href: z.string(),
 	external: z.boolean().optional()
 });
-var clarifyBannerConfigOptionsSchema = z.object({
+var clarifyBannerConfigSchema = z.object({
 	content: clarifyLocalizedTextSchema,
 	dismissible: z.boolean().optional(),
 	link: clarifyNavbarLinkSchema.optional()
 }).strict();
-var clarifyBannerConfigSchema = z.union([clarifyBannerConfigOptionsSchema, z.string()]);
-var clarifyFooterLinksConfigSchema = z.object({
+var clarifyFooterConfigSchema = z.object({
 	links: z.array(clarifyNavbarLinkSchema).optional(),
 	socials: z.record(z.string(), z.string()).optional(),
 	copyright: clarifyLocalizedTextSchema.optional()
 }).strict();
-var clarifyFooterConfigSchema = z.union([clarifyFooterLinksConfigSchema, z.string()]);
+var clarifyVariableValueSchema = z.lazy(() => z.union([
+	z.string(),
+	z.number(),
+	z.boolean(),
+	z.record(z.string(), clarifyVariableValueSchema)
+]));
+var clarifyVariablesConfigSchema = z.record(z.string(), clarifyVariableValueSchema);
 var clarifySourceConfigSchema = z.object({
 	repository: z.string(),
 	branch: z.string().optional(),
@@ -1350,9 +1673,11 @@ var clarifyProjectConfigSchema = z.object({
 	favicon: clarifyFaviconConfigSchema.optional(),
 	theme: clarifyThemeConfigSchema.optional(),
 	routePrefix: z.string().optional(),
+	assetPrefix: z.string().optional(),
 	navbar: z.object({ links: z.array(clarifyNavbarLinkSchema).optional() }).optional(),
 	banner: clarifyBannerConfigSchema.optional(),
 	footer: clarifyFooterConfigSchema.optional(),
+	variables: clarifyVariablesConfigSchema.optional(),
 	i18n: clarifyI18nConfigSchema.optional(),
 	tabs: clarifyTabsConfigSchema.optional()
 });
@@ -1412,7 +1737,22 @@ function resolveI18nConfig(i18n) {
 		locales: i18n.locales
 	};
 }
+function resolveRoutePrefix(routePrefix) {
+	const trimmed = routePrefix?.trim();
+	if (!trimmed || trimmed === "/") return "/";
+	return `/${trimmed.replace(/^\/+|\/+$/g, "")}/`;
+}
+function resolveAssetPrefix(assetPrefix, routePrefix) {
+	const trimmed = assetPrefix?.trim();
+	if (trimmed === void 0) return routePrefix;
+	if (trimmed === "./" || trimmed === "") return trimmed || "/";
+	if (!trimmed || trimmed === "/") return "/";
+	if (/^[a-z][a-z\d+.-]*:\/\//i.test(trimmed)) return trimmed.endsWith("/") ? trimmed : `${trimmed}/`;
+	if (trimmed.startsWith("./") || trimmed.startsWith("../")) return trimmed.endsWith("/") ? trimmed : `${trimmed}/`;
+	return `/${trimmed.replace(/^\/+|\/+$/g, "")}/`;
+}
 function resolveProjectConfig(config = {}) {
+	const routePrefix = resolveRoutePrefix(config.routePrefix);
 	return {
 		title: config.title ?? "Clarify Docs",
 		description: config.description ?? "",
@@ -1421,51 +1761,64 @@ function resolveProjectConfig(config = {}) {
 		logo: config.logo,
 		homeUrl: config.homeUrl,
 		favicon: config.favicon,
-		routePrefix: config.routePrefix ?? "/",
+		routePrefix,
+		assetPrefix: resolveAssetPrefix(config.assetPrefix, routePrefix),
 		theme: resolveThemeConfig(config.theme),
 		navbar: config.navbar,
 		banner: config.banner,
 		footer: config.footer,
+		variables: config.variables ?? {},
 		i18n: resolveI18nConfig(config.i18n),
 		tabs: config.tabs
 	};
 }
 //#endregion
-//#region source/core/hooks.ts
-async function runHooks(plugins, hookName, input, ctx) {
-	let result = input;
-	for (const plugin of plugins) {
-		const hook = plugin.hooks[hookName];
-		if (!hook) continue;
-		try {
-			result = await hook(result, ctx);
-		} catch (err) {
-			throw new Error(`[clarify] plugin "${plugin.name}" hook "${hookName}" failed: ${err}`, { cause: err });
-		}
-	}
-	return result;
+//#region source/core/env-types.ts
+var GENERATED_FILE_NAME = "clarify-env.d.ts";
+/**
+* Template for the generated `clarify-env.d.ts` file.
+* Edit this template directly if you need to change the type declarations.
+* This avoids the complexity of reading external files at runtime after bundling.
+*/
+var CLARIFY_ENV_TEMPLATE = `// This file is generated by Clarify. Do not edit it manually.
+// It provides ambient type declarations for Clarify virtual modules used in
+// plugin and slot code, so the TypeScript language service can resolve them.
+
+declare module 'virtual:clarify/slot' {
+  import type { SlotContext } from '@clarify-labs/cli'
+
+  export function useSlot(): SlotContext
 }
-async function runDevConfigureServerHooks(plugins, server, ctx) {
-	for (const plugin of plugins) {
-		const hook = plugin.hooks["dev:configureServer"];
-		if (!hook) continue;
-		try {
-			await hook(server, ctx);
-		} catch (err) {
-			throw new Error(`[clarify] plugin "${plugin.name}" hook "dev:configureServer" failed: ${err}`, { cause: err });
-		}
-	}
+
+declare module 'virtual:clarify/slots' {
+  import type { ComponentType } from 'react'
+
+  export type RuntimeSlotEntry = {
+    plugin: string
+    /** Lazy import factory — yields the default-exported React component. */
+    component: () => Promise<{ default: ComponentType }>
+  }
+
+  export const runtimeSlots: Record<string, RuntimeSlotEntry[]>
 }
-async function runBuildDoneHooks(plugins, ctx) {
-	for (const plugin of plugins) {
-		const hook = plugin.hooks["build:done"];
-		if (!hook) continue;
-		try {
-			await hook(ctx);
-		} catch (err) {
-			throw new Error(`[clarify] plugin "${plugin.name}" hook "build:done" failed: ${err}`, { cause: err });
-		}
+`;
+function generateClarifyEnvDts(_plugins) {
+	return CLARIFY_ENV_TEMPLATE;
+}
+/**
+* Writes `clarify-env.d.ts` into the project root. Only rewrites when content
+* changes to avoid triggering unnecessary file watchers, and never overwrites a
+* user-authored file that does not carry the generated marker.
+*/
+function writeClarifyEnvDts(projectRoot, plugins) {
+	const filePath = join(projectRoot, GENERATED_FILE_NAME);
+	const next = generateClarifyEnvDts(plugins);
+	if (existsSync(filePath)) {
+		const current = readFileSync(filePath, "utf-8");
+		if (current === next) return;
+		if (!current.startsWith("// This file is generated by Clarify.")) return;
 	}
+	writeFileSync(filePath, next, "utf-8");
 }
 //#endregion
 //#region source/core/options.ts
@@ -1479,23 +1832,11 @@ function resolveBuildOptions(options = {}) {
 }
 //#endregion
 //#region source/core/site.ts
-function withAlternates(route, routeList, i18n) {
-	const basePath = route.basePath ?? route.path;
-	const routeByLocaleAndBase = new Map(routeList.map((route) => [`${route.locale ?? ""}:${route.basePath ?? route.path}`, route]));
-	const alternates = Object.fromEntries(i18n.locales.flatMap((locale) => {
-		const alternate = routeByLocaleAndBase.get(`${locale.code}:${basePath}`);
-		return alternate ? [[locale.code, alternate.path]] : [];
-	}));
-	return {
-		...route,
-		alternates
-	};
-}
 async function discoverRoutesForRoot(routeRoot, locale, plugins, ctx) {
 	return (await runHooks(plugins, "routes:discover", {
 		contentRoot: routeRoot,
 		locale,
-		routes: findContentRoutes(routeRoot)
+		routes: await findContentRoutes(routeRoot, routeRoot, { contentProcessor: getProjectContentProcessor(ctx) })
 	}, ctx)).routes;
 }
 async function discoverRoutes(root, contentRoot, plugins, ctx) {
@@ -1532,7 +1873,21 @@ async function discoverRoutes(root, contentRoot, plugins, ctx) {
 			}
 		}
 	}
-	return localizedRoutes.map((route) => withAlternates(route, localizedRoutes, i18n));
+	const routesWithAlternates = localizedRoutes.map((route) => withAlternates(route, localizedRoutes, i18n));
+	const defaultLocale = i18n.defaultLocale;
+	const bareRoutes = [];
+	const seenBare = new Set(routesWithAlternates.map((r) => r.path));
+	for (const route of routesWithAlternates) {
+		if (route.locale !== defaultLocale) continue;
+		const bp = route.basePath ?? route.path;
+		if (bp === route.path || seenBare.has(bp)) continue;
+		seenBare.add(bp);
+		bareRoutes.push({
+			...route,
+			path: bp
+		});
+	}
+	return [...routesWithAlternates, ...bareRoutes];
 }
 async function resolveClarifySite(options = {}, resolveOptions = {}) {
 	const root = options.projectRoot ?? process.cwd();
@@ -1546,6 +1901,7 @@ async function resolveClarifySite(options = {}, resolveOptions = {}) {
 		routes: [],
 		navigation: []
 	};
+	setProjectContentProcessor(ctx, createProjectContentProcessor(plugins, ctx));
 	let routes = await discoverRoutes(root, contentRoot, plugins, ctx);
 	routes = await runHooks(plugins, "routes:discovered", routes, ctx);
 	routes = applyConfiguredPageRoutePaths(routes, projectConfig.tabs, projectConfig.i18n);
@@ -1608,13 +1964,21 @@ function createClarifyRuntimeAliases() {
 			find: /^@clarify-labs\/renderer$/,
 			replacement: resolvePackageExport("@clarify-labs/renderer", "")
 		},
+		{
+			find: /^react\/jsx-dev-runtime$/,
+			replacement: resolveCliDependency("react/jsx-dev-runtime")
+		},
 		{
 			find: /^react\/jsx-runtime$/,
 			replacement: resolveCliDependency("react/jsx-runtime")
 		},
 		{
-			find: /^react\/jsx-dev-runtime$/,
-			replacement: resolveCliDependency("react/jsx-dev-runtime")
+			find: /^mermaid$/,
+			replacement: resolveCliDependency("mermaid")
+		},
+		{
+			find: /^react-zoom-pan-pinch$/,
+			replacement: resolveCliDependency("react-zoom-pan-pinch")
 		},
 		{
 			find: /^react$/,
@@ -1656,11 +2020,24 @@ function setNamedMeta(html, name, content) {
 	if (metaPattern.test(html)) return html.replace(metaPattern, meta);
 	return html.replace("</head>", `  ${meta}\n  </head>`);
 }
+function canonicalUrl(projectConfig, route) {
+	if (!projectConfig.siteUrl || !route.alternates || !route.locale) return void 0;
+	const prefixedPath = route.alternates[route.locale];
+	if (!prefixedPath || prefixedPath === route.path) return void 0;
+	return `${projectConfig.siteUrl.replace(/\/+$/, "")}${!projectConfig.routePrefix || projectConfig.routePrefix === "/" ? "" : `/${projectConfig.routePrefix.replace(/^\/+|\/+$/g, "")}`}${prefixedPath}`;
+}
+function injectCanonicalUrl(html, projectConfig, route) {
+	const url = route ? canonicalUrl(projectConfig, route) : void 0;
+	html = html.replace(/<link\b[^>]*\brel=["']canonical["'][^>]*\/?>\n?/gi, "");
+	if (!url) return html;
+	return html.replace("</head>", `  <link rel="canonical" href="${escapeHtml(url)}" />\n  </head>`);
+}
 function injectSSRIntoTemplate(template, appHtml, projectConfig, route) {
 	let html = injectHtmlLocaleAttributes(template, projectConfig, route);
 	html = html.replace(/<title>.*?<\/title>/, `<title>${escapeHtml(routeTitle(projectConfig, route))}</title>`);
 	html = setNamedMeta(html, "description", route?.description ?? projectConfig.description);
 	html = setNamedMeta(html, "keywords", route?.keywords?.join(", "));
+	html = injectCanonicalUrl(html, projectConfig, route);
 	html = html.replace(/<div id="root">[\s\S]*?<\/div>/, `<div id="root">${appHtml}</div>`);
 	return html;
 }
@@ -1673,12 +2050,20 @@ function routeOutputFiles(outputDirectory, route) {
 	return files;
 }
 var SSR_ENTRY_CODE = `import { renderToHTML } from '@clarify-labs/renderer/server';
-import { routes, navigation } from 'virtual:clarify-routes/server';
-import { config } from 'virtual:clarify-config';
-import { openApis, bannerComponent, footerComponent } from 'virtual:clarify-runtime';
+import { routes, navigation } from 'virtual:clarify/routes/server';
+import { config } from 'virtual:clarify/config';
+import { openApis } from 'virtual:clarify/openapi';
+import { runtimeSlots } from 'virtual:clarify/slots';
 
-export function render(url) {
-  return renderToHTML({ config, routes, navigation, openApis, bannerComponent, footerComponent, url, themeEditor: config.theme.editor });
+export async function render(url) {
+  // Pre-resolve every slot component factory so renderToString can use
+  // 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()
+    entry._resolved = mod.default
+  }))
+  return renderToHTML({ config, routes, navigation, openApis, runtimeSlots, url, themeEditor: config.theme.editor });
 }`;
 function createTempEntryFile(content) {
 	const entryPath = join(createClarifyTempDir("ssr"), "entry-server.ts");
@@ -1708,7 +2093,7 @@ async function renderSSGRoutes(routes, projectConfig, outputDirectory, ssrBundle
 	const template = readIndexHtml(outputDirectory);
 	if (!template) throw new Error(`[clarify] index.html not found in outputDirectory "${outputDirectory}". Make sure Vite build produces it.`);
 	for (const route of routes) try {
-		const finalHtml = injectSSRIntoTemplate(template, render(route.path), projectConfig, route);
+		const finalHtml = injectSSRIntoTemplate(template, await render(route.path), projectConfig, route);
 		for (const outFile of routeOutputFiles(outputDirectory, route)) {
 			mkdirSync(dirname(outFile), { recursive: true });
 			writeFileSync(outFile, finalHtml, "utf-8");
@@ -1777,23 +2162,8 @@ function clarifyPlugin(options = {}) {
 	let viteConfig;
 	let resolvedNavigation = [];
 	let virtualModules = /* @__PURE__ */ new Map();
-	async function reloadProjectConfig() {
-		const buildOptions = {
-			...await loadClarifyConfig(root, {
-				command: "serve",
-				mode: viteConfig.mode
-			}),
-			projectRoot: options.projectRoot,
-			rootDirectory: options.rootDirectory,
-			outputDirectory: options.outputDirectory
-		};
-		projectConfig = resolveProjectConfig(buildOptions);
-		generateOptions = resolveBuildOptions(buildOptions);
-		ctx.projectConfig = projectConfig;
-		ctx.generateOptions = generateOptions;
-	}
-	async function resolveRoutesAndSpecs() {
-		const site = await resolveClarifySite(options);
+	async function resolveRoutesAndSpecs(overrides) {
+		const site = await resolveClarifySite(overrides ?? options);
 		projectConfig = site.projectConfig;
 		generateOptions = site.generateOptions;
 		routes = site.routes;
@@ -1810,6 +2180,7 @@ function clarifyPlugin(options = {}) {
 			generateOptions,
 			routes,
 			navigation: resolvedNavigation,
+			plugins: clarifyPlugins,
 			themeEditor: viteConfig.command === "serve" || projectConfig.theme.editor
 		});
 		virtualModules = await runHooks(clarifyPlugins, "modules:before", virtualModules, ctx);
@@ -1859,7 +2230,7 @@ function clarifyPlugin(options = {}) {
 			async config() {
 				await resolveRoutesAndSpecs();
 				return {
-					base: projectConfig.routePrefix,
+					base: projectConfig.assetPrefix,
 					build: {
 						...generateOptions.outputDirectory ? { outDir: generateOptions.outputDirectory } : {},
 						manifest: true
@@ -1872,12 +2243,23 @@ function clarifyPlugin(options = {}) {
 			},
 			async buildStart() {
 				await rebuildVirtualModules();
+				writeClarifyEnvDts(root, clarifyPlugins);
 			},
 			async handleHotUpdate(ctx) {
 				const changedFile = isAbsolute(ctx.file) ? ctx.file : join(root, ctx.file);
 				if (configFilePath && changedFile === configFilePath) {
-					await reloadProjectConfig();
-					await refreshDevServer(ctx.server);
+					await resolveRoutesAndSpecs({
+						...await loadClarifyConfig(root, {
+							command: "serve",
+							mode: viteConfig.mode
+						}),
+						projectRoot: options.projectRoot,
+						rootDirectory: options.rootDirectory,
+						outputDirectory: options.outputDirectory
+					});
+					await rebuildVirtualModules();
+					invalidateVirtualModules(ctx.server);
+					ctx.server.ws.send({ type: "full-reload" });
 					return [];
 				}
 				const relativeContentFile = relative(contentRoot, changedFile);
@@ -1886,10 +2268,13 @@ function clarifyPlugin(options = {}) {
 				return [];
 			},
 			resolveId(id) {
-				if (id === "virtual:clarify-entry-client" || id === "\0virtual:clarify-entry-client") return RESOLVED_CLIENT_ENTRY;
-				if (id === "virtual:clarify-config" || id === resolveVirtualId("virtual:clarify-config")) return resolveVirtualId(VIRTUAL_CONFIG);
-				if (id === "virtual:clarify-routes" || id === resolveVirtualId("virtual:clarify-routes")) return resolveVirtualId(VIRTUAL_ROUTES);
-				if (id === "virtual:clarify-routes/server" || id === resolveVirtualId("virtual:clarify-routes/server")) return resolveVirtualId(VIRTUAL_SERVER_ROUTES);
+				if (id === "virtual:clarify/entry-client" || id === "\0virtual:clarify/entry-client") return RESOLVED_CLIENT_ENTRY;
+				if (id === "virtual:clarify/config" || id === resolveVirtualId("virtual:clarify/config")) return resolveVirtualId(VIRTUAL_CONFIG);
+				if (id === "virtual:clarify/routes" || id === resolveVirtualId("virtual:clarify/routes")) return resolveVirtualId(VIRTUAL_ROUTES);
+				if (id === "virtual:clarify/routes/server" || id === resolveVirtualId("virtual:clarify/routes/server")) return resolveVirtualId(VIRTUAL_SERVER_ROUTES);
+				if (id === "virtual:clarify/openapi" || id === resolveVirtualId("virtual:clarify/openapi")) return resolveVirtualId(VIRTUAL_OPENAPI);
+				if (id === "virtual:clarify/slots" || id === resolveVirtualId("virtual:clarify/slots")) return resolveVirtualId(VIRTUAL_SLOTS);
+				if (id === "virtual:clarify/slot" || id === resolveVirtualId("virtual:clarify/slot")) return resolveVirtualId(VIRTUAL_SLOT);
 				const moduleId = stripVirtualPrefix(id);
 				if (virtualModules.has(moduleId)) return resolveVirtualId(moduleId);
 				const route = routes.find((r) => r.virtualModuleId === id || r.virtualModuleId === moduleId);
@@ -1927,6 +2312,14 @@ function clarifyPlugin(options = {}) {
 					};
 				}
 			},
+			async generateBundle(_opts, _bundle) {
+				const assets = await runBuildAssetsHooks(clarifyPlugins, ctx);
+				for (const asset of assets) this.emitFile({
+					type: "asset",
+					fileName: asset.fileName,
+					source: asset.source
+				});
+			},
 			async closeBundle() {
 				if (process.env.SKIP_CLARIFY_SSG) {
 					await runBuildDoneHooks(clarifyPlugins, ctx);
@@ -1941,11 +2334,14 @@ function clarifyPlugin(options = {}) {
 						{
 							name: "clarify:virtual-ssg",
 							resolveId(id) {
-								if (id === "virtual:clarify-entry-client") return RESOLVED_CLIENT_ENTRY;
-								if (id === "\0virtual:clarify-entry-client") return RESOLVED_CLIENT_ENTRY;
-								if (id === "virtual:clarify-config") return id;
-								if (id === "virtual:clarify-routes") return id;
-								if (id === "virtual:clarify-routes/server") return id;
+								if (id === "virtual:clarify/entry-client") return RESOLVED_CLIENT_ENTRY;
+								if (id === "\0virtual:clarify/entry-client") return RESOLVED_CLIENT_ENTRY;
+								if (id === "virtual:clarify/routes/server") return id;
+								if (id === "virtual:clarify/openapi") return id;
+								if (id === "virtual:clarify/config") return id;
+								if (id === "virtual:clarify/routes") return id;
+								if (id === "virtual:clarify/slots") return id;
+								if (id === "virtual:clarify/slot") return id;
 								if (virtualModules.has(stripVirtualPrefix(id))) return stripVirtualPrefix(id);
 								if (routes.find((r) => r.virtualModuleId === id)) return id;
 								return null;
@@ -1974,4 +2370,4 @@ function clarifyPlugin(options = {}) {
 //#endregion
 export { resolveClarifySite as a, createClarifyRuntimeAliases as i, defineConfig as n, createClarifyTempDir as o, loadClarifyConfig as r, clarifyPlugin as t };
 
-//# sourceMappingURL=plugin-o1rP_gts.js.map
+//# sourceMappingURL=plugin-D5EF3pYl.js.map