yaakdoc 0.0.0-stage → 0.1.0

package/dist/preview-2YFamRKo.js

@@ -0,0 +1,1184 @@
+import { createRequire } from "node:module";
+import { builtinSnippets, generateExamples } from "@yaakdoc/snippets";
+import { copyFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { absoluteUrl, escapeRegExp, findWorkspace, isUrl, normalize, prepareDocument, sanitizeExport, selectEnvironment, summarize } from "@yaakdoc/core";
+import { build, createServer, isRunnableDevEnvironment, searchForWorkspaceRoot } from "vite";
+import { createHash } from "node:crypto";
+import { createReadStream, existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { loadConfig } from "@yaakdoc/config/node";
+import { detectExport, readExport } from "@yaakdoc/core/node";
+import { folderToMarkdown, indexToMarkdown, llmsFullTxt, llmsTxt, requestToMarkdown } from "@yaakdoc/markdown";
+import rehypeShikiFromHighlighter from "@shikijs/rehype/core";
+import { createJiti } from "jiti";
+import rehypeSanitize, { defaultSchema } from "rehype-sanitize";
+import rehypeStringify from "rehype-stringify";
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import remarkRehype from "remark-rehype";
+import { bundledLanguages, createHighlighter } from "shiki";
+import { unified } from "unified";
+import { tmpdir } from "node:os";
+import { createServer as createServer$1 } from "node:http";
+import { consola } from "consola";
+import colors from "picocolors";
+import { glob } from "tinyglobby";
+import sirv from "sirv";
+//#region src/node/render.ts
+const PRELOADED_LANGUAGES = [
+	"bash",
+	"javascript",
+	"typescript",
+	"python",
+	"go",
+	"json",
+	"graphql",
+	"xml",
+	"html",
+	"yaml",
+	"http"
+];
+/** Highlights a delimited region as GraphQL (opening captures: prefix tokens, then the delimiter). */
+const embeddedGraphql = (begin, end, prefixScopes) => ({
+	begin,
+	beginCaptures: Object.fromEntries(prefixScopes.map((name, index) => [index + 1, { name }])),
+	end,
+	endCaptures: { 0: { name: prefixScopes.at(-1) } },
+	contentName: "meta.embedded.block.graphql",
+	patterns: [{ include: "source.graphql" }]
+});
+/**
+* Injection grammar highlighting GraphQL inside code examples (like VS Code's GraphQL extension):
+* `/* GraphQL *\/ \`…\`` and `gql\`…\`` in JavaScript, `query = """…"""` in Python and
+* `query := \`…\`` in Go.
+*/
+const GRAPHQL_INJECTION = {
+	name: "yaakdoc-graphql-injection",
+	scopeName: "inline.graphql.yaakdoc",
+	injectTo: [
+		"source.js",
+		"source.ts",
+		"source.python",
+		"source.go"
+	],
+	injectionSelector: "L:source -comment -string",
+	embeddedLangs: ["graphql"],
+	patterns: [
+		embeddedGraphql("(/\\*\\s*GraphQL\\s*\\*/)\\s*(`)", "`", ["comment.block.js", "punctuation.definition.string.template.begin.js"]),
+		embeddedGraphql("\\b(gql|graphql)(`)", "`", ["entity.name.function.tagged-template.js", "punctuation.definition.string.template.begin.js"]),
+		embeddedGraphql("\\b(query)\\s*(=)\\s*(\"\"\")", "\"\"\"", [
+			"variable.other.python",
+			"keyword.operator.assignment.python",
+			"punctuation.definition.string.begin.python"
+		]),
+		embeddedGraphql("\\b(query)\\s*(:=)\\s*(`)", "`", [
+			"variable.other.go",
+			"keyword.operator.assignment.go",
+			"punctuation.definition.string.begin.go"
+		])
+	]
+};
+const highlighters = /* @__PURE__ */ new Map();
+function getHighlighter(themes) {
+	const key = `${themes.light}|${themes.dark}`;
+	let highlighter = highlighters.get(key);
+	if (!highlighter) {
+		highlighter = createHighlighter({
+			themes: [themes.light, themes.dark],
+			langs: [...PRELOADED_LANGUAGES, GRAPHQL_INJECTION]
+		});
+		highlighters.set(key, highlighter);
+	}
+	return highlighter;
+}
+const LANGUAGE_ALIASES = {
+	shell: "bash",
+	sh: "bash",
+	js: "javascript",
+	ts: "typescript",
+	text: "text",
+	plain: "text"
+};
+async function ensureLanguage(highlighter, language) {
+	const lang = LANGUAGE_ALIASES[language] ?? language;
+	if (lang === "text" || highlighter.getLoadedLanguages().includes(lang)) return lang;
+	if (lang in bundledLanguages) {
+		await highlighter.loadLanguage(lang);
+		return lang;
+	}
+	return "text";
+}
+const sanitizeSchema = {
+	...defaultSchema,
+	attributes: {
+		...defaultSchema.attributes,
+		code: [...defaultSchema.attributes?.code ?? [], ["className", /^language-./]]
+	}
+};
+/**
+* Creates the Markdown/code renderer: GFM, sanitized HTML (descriptions come from exports that may
+* be shared by others), and Shiki highlighting with dual light/dark themes via CSS variables.
+*/
+async function createRenderer(themes) {
+	const highlighter = await getHighlighter(themes);
+	const shikiOptions = {
+		themes,
+		defaultColor: false
+	};
+	const processor = unified().use(remarkParse).use(remarkGfm).use(remarkRehype).use(rehypeSanitize, sanitizeSchema).use(rehypeShikiFromHighlighter, highlighter, {
+		...shikiOptions,
+		fallbackLanguage: "text",
+		lazy: true
+	}).use(rehypeStringify);
+	return {
+		markdown: async (source) => String(await processor.process(source)),
+		highlight: async (code, language) => highlighter.codeToHtml(code, {
+			...shikiOptions,
+			lang: await ensureLanguage(highlighter, language)
+		})
+	};
+}
+/** Loads snippet generators by built-in id or module path/package (default export or `snippet`). */
+async function loadSnippets(ids, root) {
+	const jiti = createJiti(`${root}/`, { interopDefault: true });
+	const snippets = [];
+	for (const id of ids) {
+		const builtin = builtinSnippets[id];
+		if (builtin) {
+			snippets.push(builtin);
+			continue;
+		}
+		if (!existsSync(id) && !id.includes("/") && !id.startsWith("@")) throw new Error(`Unknown snippet "${id}". Built-in snippets: ${Object.keys(builtinSnippets).join(", ")}.`);
+		const mod = await jiti.import(id);
+		const loaded = "default" in mod ? mod.default : mod;
+		for (const snippet of Array.isArray(loaded) ? loaded : [loaded]) {
+			if (!snippet || typeof snippet.generate !== "function") throw new Error(`Snippet module "${id}" must export a snippet created with defineSnippet().`);
+			snippets.push(snippet);
+		}
+	}
+	return snippets;
+}
+//#endregion
+//#region src/node/resolve.ts
+/** Directory of the installed `yaakdoc` package. */
+const ENGINE_DIR = (() => {
+	let dir = dirname(fileURLToPath(import.meta.url));
+	while (!existsSync(join(dir, "package.json"))) dir = dirname(dir);
+	return dir;
+})();
+/** A file inside the engine package, used as importer for fallback resolution. */
+const ENGINE_ANCHOR = join(ENGINE_DIR, "package.json");
+/**
+* Resolves an ESM specifier as if imported from `fromFile`. Returns an absolute path or null.
+*/
+function resolveFrom(specifier, fromFile) {
+	try {
+		const resolved = createJiti(fromFile).esmResolve(specifier, { try: true });
+		return resolved ? resolved.startsWith("file:") ? fileURLToPath(resolved) : resolved : null;
+	} catch {
+		return null;
+	}
+}
+/** Resolves a package directory (the folder containing its package.json). */
+function resolvePackageDir(name, fromFile) {
+	const entry = resolveFrom(`${name}/package.json`, fromFile);
+	if (entry) return dirname(entry);
+	const main = resolveFrom(name, fromFile);
+	if (!main) return null;
+	let dir = dirname(main);
+	while (dir !== dirname(dir)) {
+		if (existsSync(join(dir, "package.json")) && dir.endsWith(name.split("/").at(-1))) return dir;
+		dir = dirname(dir);
+	}
+	return null;
+}
+//#endregion
+//#region src/node/theme.ts
+var ThemeError = class extends Error {
+	name = "ThemeError";
+};
+const MANIFEST_NAMES = [
+	"theme.ts",
+	"theme.mts",
+	"theme.js",
+	"theme.mjs",
+	"index.ts",
+	"index.js"
+];
+/** Candidate package names for a theme spec: `kiseki` → `@yaakdoc/theme-kiseki`, `yaakdoc-theme-kiseki`. */
+function themePackageCandidates(spec) {
+	if (spec.startsWith("@") || spec.includes("/") || spec.startsWith("yaakdoc-theme-")) return [spec];
+	return [
+		`@yaakdoc/theme-${spec}`,
+		`yaakdoc-theme-${spec}`,
+		spec
+	];
+}
+const isLocal = (spec) => spec.startsWith(".") || isAbsolute(spec);
+function findManifest(path) {
+	if (existsSync(path) && statSync(path).isFile()) return path;
+	for (const name of MANIFEST_NAMES) {
+		const candidate = join(path, name);
+		if (existsSync(candidate)) return candidate;
+	}
+	throw new ThemeError(`No theme manifest (${MANIFEST_NAMES.join(", ")}) found in ${path}`);
+}
+/** Built-in theme package directories, used to resolve dependencies of ejected themes. */
+function builtinFallbacks() {
+	const kiseki = resolvePackageDir("@yaakdoc/theme-kiseki", ENGINE_ANCHOR);
+	return [ENGINE_ANCHOR, ...kiseki ? [join(kiseki, "package.json")] : []];
+}
+/** Loads and validates a theme from a short name, package name or local path. */
+async function resolveTheme(spec, options) {
+	const userAnchor = join(options.root, "package.json");
+	let manifest = null;
+	let packageName = null;
+	if (isLocal(spec)) manifest = findManifest(resolve(options.root, spec));
+	else {
+		for (const candidate of themePackageCandidates(spec)) {
+			const resolved = resolveFrom(candidate, userAnchor) ?? resolveFrom(candidate, ENGINE_ANCHOR);
+			if (resolved) {
+				manifest = resolved;
+				packageName = candidate;
+				break;
+			}
+		}
+		if (!manifest) throw new ThemeError(`Theme "${spec}" not found. Install it (e.g. npm i -D ${themePackageCandidates(spec)[0]}) or use a local path.`);
+	}
+	const fallbackImporters = builtinFallbacks();
+	const alias = buildAliases(manifest, fallbackImporters);
+	const jiti = createJiti(manifest, {
+		alias,
+		moduleCache: false,
+		interopDefault: true
+	});
+	let definition;
+	try {
+		definition = await jiti.import(manifest, { default: true });
+	} catch (error) {
+		throw new ThemeError(`Failed to load theme ${manifest}: ${error.message}`);
+	}
+	if (!definition || typeof definition !== "object" || !definition.entry) throw new ThemeError(`Theme ${manifest} must default-export defineTheme({ name, entry, ... }).`);
+	const root = dirname(manifest);
+	const abs = (path) => resolve(root, path);
+	let themeOptions = options.themeOptions;
+	if (definition.options) try {
+		themeOptions = definition.options.parse(options.themeOptions);
+	} catch (error) {
+		throw new ThemeError(`Invalid themeOptions for theme "${definition.name}":\n${error.message}`);
+	}
+	return {
+		name: definition.name,
+		definition,
+		root,
+		manifest,
+		entry: abs(definition.entry),
+		client: definition.client ? abs(definition.client) : null,
+		styles: (definition.styles ?? []).map(abs),
+		options: themeOptions,
+		packageName,
+		fallbackImporters,
+		highlight: definition.highlight ?? {
+			light: "github-light",
+			dark: "github-dark"
+		}
+	};
+}
+/**
+* jiti aliases so a theme manifest (e.g. an ejected theme in a project without dependencies) can
+* import `@yaakdoc/react/theme` and the built-in themes' dependencies.
+*/
+function buildAliases(manifest, fallbacks) {
+	const specs = /* @__PURE__ */ new Set(["@yaakdoc/react/theme", "@yaakdoc/react"]);
+	for (const fallback of fallbacks) try {
+		const pkg = JSON.parse(readFileSync(fallback, "utf8"));
+		for (const name of Object.keys(pkg.dependencies ?? {})) specs.add(name);
+	} catch {}
+	const alias = {};
+	for (const spec of specs) {
+		if (resolveFrom(spec, manifest)) continue;
+		for (const fallback of fallbacks) {
+			const resolved = resolveFrom(spec, fallback);
+			if (resolved) {
+				alias[spec] = resolved;
+				break;
+			}
+		}
+	}
+	return alias;
+}
+//#endregion
+//#region src/node/context.ts
+const VERSION = JSON.parse(readFileSync(resolve(ENGINE_DIR, "package.json"), "utf8")).version;
+/** Loads config, export and theme, and prepares everything needed to render the site. */
+async function resolveContext(options = {}) {
+	const cwd = resolve(options.cwd ?? process.cwd());
+	const { config, configFile, root } = await loadConfig({
+		cwd,
+		...options.configFile ? { configFile: options.configFile } : {},
+		...options.overrides ? { overrides: options.overrides } : {}
+	});
+	const exportPath = config.export ?? await detectExport(root);
+	const rawExport = await readExport(exportPath);
+	const source = normalize(rawExport);
+	const workspace = findWorkspace(source, config.workspace);
+	const environments = config.environments === "public" ? workspace.environments.filter((env) => env.public) : (config.environments ?? []).map((name) => selectEnvironment(workspace, name));
+	const environment = config.environment === false ? null : config.environment === void 0 && environments[0] ? environments[0] : selectEnvironment(workspace, config.environment);
+	const theme = await resolveTheme(config.theme, {
+		root,
+		themeOptions: config.themeOptions
+	});
+	const renderer = await createRenderer(theme.highlight);
+	const snippets = await loadSnippets(config.snippets, root);
+	const document = await prepareDocument({
+		workspace,
+		environment,
+		environments,
+		pages: config.pages,
+		base: config.base,
+		variables: config.variables,
+		filter: config.filter,
+		renderMarkdown: renderer.markdown,
+		highlight: renderer.highlight,
+		examples: (request) => generateExamples(request, snippets),
+		meta: {
+			yaakVersion: source.yaakVersion,
+			exportedAt: source.exportedAt
+		}
+	});
+	const assets = /* @__PURE__ */ new Map();
+	const asset = (path) => publicAsset(path, config.base, assets);
+	const site = await createSiteData(config, document, theme, asset, renderer.markdown);
+	const { routes, notFound } = createRoutes(document, site);
+	const markdownOptions = {
+		title: site.title,
+		description: site.description,
+		base: config.base,
+		...site.url ? { siteUrl: site.url } : {}
+	};
+	const textFiles = /* @__PURE__ */ new Map();
+	if (config.llms.enabled) {
+		textFiles.set(`${config.base}index.md`, config.pages === "single" ? llmsFullTxt(document, markdownOptions) : indexToMarkdown(document, markdownOptions));
+		for (const folder of Object.values(document.folders)) textFiles.set(folder.markdownUrl, folderToMarkdown(document, folder, markdownOptions));
+		for (const request of Object.values(document.requests)) textFiles.set(request.markdownUrl, requestToMarkdown(request, markdownOptions));
+		textFiles.set(`${config.base}llms.txt`, llmsTxt(document, {
+			...markdownOptions,
+			...config.llms.full ? { fullTextUrl: `${config.base}llms-full.txt` } : {}
+		}));
+		if (config.llms.full) textFiles.set(`${config.base}llms-full.txt`, llmsFullTxt(document, markdownOptions));
+	}
+	const externalExport = typeof config.runInYaak === "object" && config.runInYaak.url;
+	if (site.runInYaak && !externalExport) {
+		const shared = shareableExport(rawExport, workspace, document, config.variables.hide);
+		textFiles.set(site.runInYaak.dataUrl, JSON.stringify(shared, null, 2));
+	}
+	return {
+		cwd,
+		root,
+		configFile,
+		config,
+		exportPath,
+		source,
+		theme,
+		document,
+		site,
+		routes,
+		notFound,
+		textFiles,
+		assets,
+		watchFiles: [
+			exportPath,
+			...configFile ? [configFile] : [],
+			...assets.values()
+		]
+	};
+}
+/** The export restricted to what the docs show, safe to publish for "Run in Yaak". */
+function shareableExport(raw, workspace, document, hide) {
+	const environmentIds = new Set(document.environments.map((env) => env.id));
+	if (document.environment) environmentIds.add(document.environment.id);
+	if (workspace.baseEnvironment) environmentIds.add(workspace.baseEnvironment.id);
+	for (const folderId of Object.keys(document.folders)) for (const env of workspace.folderEnvironments[folderId] ?? []) environmentIds.add(env.id);
+	return sanitizeExport(raw, {
+		workspaceId: workspace.id,
+		folderIds: new Set(Object.keys(document.folders)),
+		requestIds: new Set(Object.keys(document.requests)),
+		environmentIds,
+		hide
+	});
+}
+/**
+* Maps a local asset (logo, favicon) to a public URL under `<base>_yaakdoc/`. URLs and site-root
+* paths that don't exist on disk (e.g. `/logo.svg` served from `public/`) are kept as is.
+*/
+function publicAsset(path, base, assets) {
+	if (!path) return null;
+	if (isUrl(path) || !existsSync(path)) return path;
+	const hash = createHash("sha256").update(path).digest("hex").slice(0, 8);
+	const url = `${base}_yaakdoc/${basename(path, extname(path))}-${hash}${extname(path)}`;
+	assets.set(url, path);
+	return url;
+}
+async function createSiteData(config, document, theme, asset, markdown) {
+	const { branding } = config;
+	const title = branding.title ?? document.workspace.name;
+	let logo = null;
+	if (typeof branding.logo === "string") logo = {
+		light: asset(branding.logo) ?? void 0,
+		alt: title,
+		href: config.base
+	};
+	else if (branding.logo) logo = {
+		...branding.logo.light ? { light: asset(branding.logo.light) } : {},
+		...branding.logo.dark ? { dark: asset(branding.logo.dark) } : {},
+		alt: branding.logo.alt ?? title,
+		href: branding.logo.href ?? config.base,
+		...branding.logo.width ? { width: branding.logo.width } : {},
+		...branding.logo.height ? { height: branding.logo.height } : {}
+	};
+	return {
+		title,
+		description: branding.description ?? summarize(document.workspace.description, 200),
+		url: branding.url ?? null,
+		base: config.base,
+		pages: config.pages,
+		logo,
+		favicon: asset(branding.favicon),
+		colors: branding.colors ?? {},
+		fonts: branding.fonts ?? {},
+		links: branding.links,
+		footerHtml: branding.footer ? await markdown(branding.footer) : null,
+		defaultColorMode: branding.defaultColorMode,
+		colorModeToggle: branding.colorModeToggle,
+		llms: {
+			...config.llms,
+			txtUrl: config.llms.enabled ? `${config.base}llms.txt` : null,
+			fullTxtUrl: config.llms.enabled && config.llms.full ? `${config.base}llms-full.txt` : null
+		},
+		showVariables: config.variables.show,
+		runInYaak: config.runInYaak ? {
+			name: typeof config.runInYaak === "object" && config.runInYaak.name || title,
+			dataUrl: typeof config.runInYaak === "object" && config.runInYaak.url || `${config.base}yaak.json`
+		} : null,
+		head: config.head,
+		themeOptions: theme.options,
+		generator: `yaakdoc ${VERSION}`
+	};
+}
+function createRoutes(document, site) {
+	const { base } = site;
+	const llms = site.llms.enabled;
+	const routes = [{
+		path: base,
+		file: "index.html",
+		page: {
+			kind: "index",
+			id: null,
+			path: base,
+			title: "",
+			description: site.description,
+			markdownUrl: llms ? `${base}index.md` : null
+		}
+	}];
+	if (site.pages === "per-request") {
+		for (const folder of Object.values(document.folders)) routes.push({
+			path: folder.href,
+			file: `${folder.slug}/index.html`,
+			page: {
+				kind: "folder",
+				id: folder.id,
+				path: folder.href,
+				title: folder.name,
+				description: folder.summary,
+				markdownUrl: llms ? folder.markdownUrl : null
+			}
+		});
+		for (const request of Object.values(document.requests)) routes.push({
+			path: request.href,
+			file: `${request.slug}/index.html`,
+			page: {
+				kind: "request",
+				id: request.id,
+				path: request.href,
+				title: request.name,
+				description: request.summary,
+				markdownUrl: llms ? request.markdownUrl : null
+			}
+		});
+	}
+	return {
+		routes,
+		notFound: {
+			path: `${base}404.html`,
+			file: "404.html",
+			page: {
+				kind: "not-found",
+				id: null,
+				path: `${base}404.html`,
+				title: "Page not found",
+				description: "",
+				markdownUrl: null
+			}
+		}
+	};
+}
+/** Finds the route for a URL path (ignoring query/hash; `/x` matches `/x/`). */
+function matchRoute(context, pathname) {
+	const path = decodeURIComponent(pathname.split(/[?#]/)[0] ?? "/");
+	const normalized = path.endsWith("/") || path.endsWith(".html") ? path : `${path}/`;
+	return context.routes.find((route) => route.path === normalized || `${route.path}index.html` === path) ?? null;
+}
+//#endregion
+//#region src/node/plugin.ts
+const VIRTUAL_SERVER = "virtual:yaakdoc/entry-server";
+const VIRTUAL_CLIENT = "virtual:yaakdoc/entry-client";
+const RESOLVED = (id) => `\0${id}`;
+const isBare = (id) => !id.startsWith(".") && !id.startsWith("/") && !id.startsWith("\0") && !/^[a-z]+:/i.test(id) && !id.startsWith("@/");
+const json = (value) => JSON.stringify(value);
+const REACT_RE = /^react(-dom)?(\/|$)/;
+const CJS_PREFIX = "\0yaakdoc-cjs:";
+const IDENTIFIER_RE = /^[A-Za-z_$][\w$]*$/;
+/** ESM module re-exporting a CommonJS module required from yaakdoc's installation. */
+function cjsWrapper(specifier) {
+	const mod = createRequire(ENGINE_ANCHOR)(specifier);
+	const names = Object.keys(mod).filter((name) => name !== "default" && IDENTIFIER_RE.test(name));
+	return [
+		`import { createRequire } from "node:module";`,
+		`const mod = createRequire(${json(ENGINE_ANCHOR)})(${json(specifier)});`,
+		"export default mod;",
+		names.length > 0 ? `export const { ${names.join(", ")} } = mod;` : ""
+	].join("\n");
+}
+/**
+* The yaakdoc Vite plugin: virtual SSR/client entries, theme-scoped `@/` alias, and fallback
+* resolution of theme dependencies from the yaakdoc installation (so ejected themes and `npx` work
+* without installing anything in the project).
+*/
+function yaakdocPlugin(getContext, onSsrUpdate) {
+	return {
+		name: "yaakdoc",
+		enforce: "pre",
+		async resolveId(source, importer, options) {
+			if (source === "virtual:yaakdoc/entry-server" || source === "virtual:yaakdoc/entry-client") return RESOLVED(source);
+			const { theme } = getContext();
+			if (source.startsWith("@/") && importer?.startsWith(theme.root + sep)) return this.resolve(join(theme.root, "src", source.slice(2)), importer, {
+				...options,
+				skipSelf: true
+			});
+			if (!isBare(source)) return null;
+			const server = this.environment.config.consumer === "server";
+			const finish = (resolved) => {
+				if (!resolved) return null;
+				if (server) return REACT_RE.test(source) ? {
+					...resolved,
+					external: true
+				} : resolved;
+				return optimized(this.environment, resolved, options.scan);
+			};
+			if (REACT_RE.test(source) && server && this.environment.mode === "dev") return `${CJS_PREFIX}${source}`;
+			if (REACT_RE.test(source)) return finish(await this.resolve(source, ENGINE_ANCHOR, {
+				...options,
+				skipSelf: true
+			}));
+			if (!(!importer || importer.startsWith("\0"))) {
+				const resolved = await this.resolve(source, importer, {
+					...options,
+					skipSelf: true
+				});
+				if (resolved) return finish(resolved);
+			}
+			for (const fallback of [
+				ENGINE_ANCHOR,
+				...theme.fallbackImporters,
+				join(theme.root, "package.json")
+			]) {
+				const resolved = await this.resolve(source, fallback, {
+					...options,
+					skipSelf: true
+				});
+				if (resolved) return finish(resolved);
+			}
+			return null;
+		},
+		load(id) {
+			if (id.startsWith(CJS_PREFIX)) return cjsWrapper(id.slice(13));
+			const context = getContext();
+			if (id === RESOLVED("virtual:yaakdoc/entry-server")) return [
+				`import theme from ${json(context.theme.entry)};`,
+				`import { renderPage } from "@yaakdoc/react/server";`,
+				"export function render(input) {",
+				"  return renderPage({ theme, ...input });",
+				"}"
+			].join("\n");
+			if (id === RESOLVED("virtual:yaakdoc/entry-client")) return [
+				...styleEntries(context).map((style) => `import ${json(style)};`),
+				`import { hydrateIslands } from "@yaakdoc/react/client";`,
+				context.theme.client ? `import islands from ${json(context.theme.client)};` : `import { builtinIslands as islands } from "@yaakdoc/react/islands";`,
+				"hydrateIslands(islands);"
+			].join("\n");
+			return null;
+		},
+		hotUpdate({ modules, file }) {
+			if (this.environment.name !== "ssr" || modules.length === 0 || /\.css($|\?)/.test(file)) return;
+			onSsrUpdate?.();
+		}
+	};
+}
+const NODE_MODULES_RE = /[\\/]node_modules[\\/]/;
+const JS_RE = /\.(m?js|cjs)$/;
+/**
+* Dev only: maps a dependency in node_modules to its pre-bundled version.
+*
+* Vite skips dependency discovery for imports coming from inside node_modules – which is where
+* yaakdoc and its theme live when run with `npx`. Such dependencies are registered here by absolute
+* path (reusing an existing entry for the same file), so they are served pre-bundled as ESM.
+*/
+function optimized(environment, resolved, scan) {
+	const optimizer = environment.mode === "dev" ? environment.depsOptimizer : void 0;
+	if (!optimizer || scan || resolved.external) return resolved;
+	const file = resolved.id.split("?")[0];
+	if (!NODE_MODULES_RE.test(file) || !JS_RE.test(file) || optimizer.isOptimizedDepFile(file)) return resolved;
+	const { optimized: done, discovered } = optimizer.metadata;
+	const info = done[file] ?? discovered[file] ?? [...Object.values(done), ...Object.values(discovered)].find((dep) => dep.src === file) ?? optimizer.registerMissingImport(file, file);
+	return optimizer.getOptimizedDepId(info);
+}
+/** CSS entries loaded on every page: the theme's styles, then `branding.customCss`. */
+function styleEntries(context) {
+	const { customCss } = context.config.branding;
+	return [...context.theme.styles, ...customCss ? [customCss] : []];
+}
+const nodeModulesRoot = (file) => {
+	const index = file.lastIndexOf(`${sep}node_modules${sep}`);
+	return index === -1 ? dirname(file) : file.slice(0, index + `${sep}node_modules`.length);
+};
+//#endregion
+//#region src/node/vite.ts
+/** Base Vite config shared by the dev server and builds. */
+async function createViteConfig(getContext, mode, extra = {}) {
+	const context = getContext();
+	const themePlugins = await context.theme.definition.vitePlugins?.() ?? [];
+	const publicDir = join(context.root, "public");
+	const cacheDir = existsSync(join(context.root, "node_modules")) ? join(context.root, "node_modules", ".vite-yaakdoc") : join(tmpdir(), "yaakdoc-vite", createHash("sha256").update(context.root).digest("hex").slice(0, 12));
+	return {
+		configFile: false,
+		envDir: false,
+		root: context.root,
+		base: context.config.base,
+		mode,
+		logLevel: extra.logLevel ?? "warn",
+		clearScreen: false,
+		publicDir: existsSync(publicDir) ? publicDir : false,
+		cacheDir,
+		plugins: [yaakdocPlugin(getContext, extra.onSsrUpdate), ...themePlugins],
+		resolve: { alias: styleAliases(context) },
+		oxc: { jsx: {
+			runtime: "automatic",
+			importSource: "react"
+		} },
+		ssr: { noExternal: [
+			"@yaakdoc/react",
+			/^@yaakdoc\/theme-/,
+			/^yaakdoc-theme-/
+		] },
+		optimizeDeps: { entries: [] },
+		build: { rolldownOptions: { onLog(level, log, handler) {
+			if (log.code === "MODULE_LEVEL_DIRECTIVE") return;
+			handler(level, log);
+		} } },
+		server: { fs: { allow: [
+			searchForWorkspaceRoot(context.root),
+			cacheDir,
+			context.theme.root,
+			nodeModulesRoot(ENGINE_DIR),
+			...context.theme.fallbackImporters.map(nodeModulesRoot)
+		] } }
+	};
+}
+/**
+* CSS `@import "pkg"` is resolved by Vite's CSS resolver (aliases only, no plugins). For CSS packages
+* an ejected theme doesn't have installed (e.g. `tailwindcss`), alias them to yaakdoc's copy.
+*/
+function styleAliases(context) {
+	const themeAnchor = join(context.theme.root, "package.json");
+	const aliases = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const fallback of context.theme.fallbackImporters) {
+		let dependencies = [];
+		try {
+			dependencies = Object.keys(JSON.parse(readFileSync(fallback, "utf8")).dependencies ?? {});
+		} catch {}
+		for (const name of dependencies) {
+			if (seen.has(name)) continue;
+			seen.add(name);
+			if (resolveFrom(`${name}/package.json`, themeAnchor)) continue;
+			const pkgJson = resolveFrom(`${name}/package.json`, fallback);
+			if (!pkgJson) continue;
+			const pkg = JSON.parse(readFileSync(pkgJson, "utf8"));
+			const root = pkg.exports?.["."];
+			const style = typeof root === "object" && root && "style" in root ? root.style : pkg.style;
+			if (typeof style === "string") aliases.push({
+				find: new RegExp(`^${escapeRegExp(name)}$`),
+				replacement: join(dirname(pkgJson), style)
+			});
+		}
+	}
+	return aliases;
+}
+//#endregion
+//#region src/node/build.ts
+const SSR_DIR = ".yaakdoc-ssr";
+/** Builds the static site: client assets, prerendered HTML for every route, Markdown and llms.txt. */
+async function build$1(options = {}) {
+	const previousEnv = process.env.NODE_ENV;
+	process.env.NODE_ENV = "production";
+	try {
+		return await buildWithContext(await resolveContext(options));
+	} finally {
+		if (previousEnv === void 0) delete process.env.NODE_ENV;
+		else process.env.NODE_ENV = previousEnv;
+	}
+}
+async function buildWithContext(context) {
+	const outDir = context.config.outDir;
+	assertSafeOutDir(outDir, context.root);
+	const getContext = () => context;
+	const base = await createViteConfig(getContext, "production");
+	await build({
+		...base,
+		build: {
+			outDir,
+			emptyOutDir: true,
+			manifest: true,
+			assetsDir: "_yaakdoc",
+			copyPublicDir: true,
+			rolldownOptions: {
+				...base.build?.rolldownOptions,
+				input: { client: VIRTUAL_CLIENT }
+			}
+		}
+	});
+	const ssrOutDir = join(outDir, SSR_DIR);
+	await build({
+		...base,
+		publicDir: false,
+		define: { "process.env.NODE_ENV": JSON.stringify("production") },
+		ssr: {
+			...base.ssr,
+			noExternal: true
+		},
+		build: {
+			ssr: true,
+			outDir: ssrOutDir,
+			emptyOutDir: true,
+			copyPublicDir: false,
+			rolldownOptions: {
+				...base.build?.rolldownOptions,
+				input: { "entry-server": VIRTUAL_SERVER },
+				output: {
+					entryFileNames: "[name].mjs",
+					format: "esm"
+				}
+			}
+		}
+	});
+	const assets = assetsFromManifest(JSON.parse(await readFile(join(outDir, ".vite", "manifest.json"), "utf8")), context.config.base);
+	const { render } = await import(pathToFileURL(join(ssrOutDir, "entry-server.mjs")).href);
+	const files = [];
+	const write = async (file, content) => {
+		const target = join(outDir, file);
+		await mkdir(dirname(target), { recursive: true });
+		await writeFile(target, content);
+		files.push(file);
+	};
+	for (const route of [...context.routes, context.notFound]) await write(route.file, await render({
+		document: context.document,
+		site: context.site,
+		page: route.page,
+		assets
+	}));
+	for (const [url, content] of context.textFiles) await write(stripBase(url, context.config.base), content);
+	for (const [url, source] of context.assets) {
+		const file = stripBase(url, context.config.base);
+		await mkdir(dirname(join(outDir, file)), { recursive: true });
+		await copyFile(source, join(outDir, file));
+		files.push(file);
+	}
+	if (context.site.url) await write("sitemap.xml", sitemap(context));
+	await write(".nojekyll", "");
+	await rm(ssrOutDir, {
+		recursive: true,
+		force: true
+	});
+	await rm(join(outDir, ".vite"), {
+		recursive: true,
+		force: true
+	});
+	return {
+		outDir,
+		files,
+		context
+	};
+}
+function assetsFromManifest(manifest, base) {
+	const entry = Object.values(manifest).find((chunk) => chunk.isEntry);
+	if (!entry) throw new Error("Client build produced no entry chunk.");
+	const collectImports = (keys = [], seen = /* @__PURE__ */ new Set()) => keys.flatMap((key) => {
+		if (seen.has(key)) return [];
+		seen.add(key);
+		const chunk = manifest[key];
+		return chunk ? [chunk.file, ...collectImports(chunk.imports, seen)] : [];
+	});
+	const css = /* @__PURE__ */ new Set([...entry.css ?? []]);
+	for (const key of entry.imports ?? []) for (const file of manifest[key]?.css ?? []) css.add(file);
+	return {
+		styles: [...css].map((file) => base + file),
+		scripts: [base + entry.file],
+		inlineStyles: [],
+		modulePreloads: collectImports(entry.imports).map((file) => base + file)
+	};
+}
+const stripBase = (url, base) => url.startsWith(base) ? url.slice(base.length) : url.replace(/^\//, "");
+function sitemap(context) {
+	return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${context.routes.map((route) => absoluteUrl(context.site.url, context.config.base, route.path)).map((url) => `  <url><loc>${url}</loc></url>`).join("\n")}\n</urlset>\n`;
+}
+/** Refuses to empty the project directory (or a parent of it). */
+function assertSafeOutDir(outDir, root) {
+	const rel = relative(resolve(outDir), resolve(root));
+	if (rel === "" || !rel.startsWith("..") && !rel.startsWith(sep) && !rel.includes(":")) throw new Error(`Refusing to use ${outDir} as outDir: it contains the project directory and would be emptied.`);
+}
+//#endregion
+//#region src/node/server.ts
+const CONTENT_TYPES = {
+	".md": "text/markdown; charset=utf-8",
+	".txt": "text/plain; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+	".svg": "image/svg+xml",
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".gif": "image/gif",
+	".webp": "image/webp",
+	".avif": "image/avif",
+	".ico": "image/x-icon",
+	".css": "text/css; charset=utf-8",
+	".woff2": "font/woff2"
+};
+/** Interface to listen on: a given host, all interfaces (`true`), or localhost. */
+const listenHostname = (host) => typeof host === "string" ? host : host ? "0.0.0.0" : "localhost";
+/** URL to print/open for a server (all-interfaces hosts are shown as localhost). */
+function serverUrl(host, port, base) {
+	const hostname = listenHostname(host);
+	return `http://${hostname === "0.0.0.0" ? "localhost" : hostname}:${port}${base}`;
+}
+/** Listens on `port`, trying the next ports when it is taken. */
+function listen(server, port, host) {
+	const hostname = listenHostname(host);
+	return new Promise((resolvePort, reject) => {
+		let attempt = 0;
+		const tryListen = (candidate) => {
+			server.once("error", (error) => {
+				if (error.code === "EADDRINUSE" && attempt++ < 20 && port !== 0) tryListen(candidate + 1);
+				else reject(error);
+			});
+			server.listen(candidate, hostname, () => resolvePort(server.address().port));
+		};
+		tryListen(port);
+	});
+}
+//#endregion
+//#region src/node/dev.ts
+/** Starts the development server with SSR, HMR for theme code/CSS and reload on export changes. */
+async function createDevServer(options = {}) {
+	let context = await resolveContext(options);
+	const getContext = () => context;
+	const httpServer = createServer$1();
+	let vite;
+	const fullReload = () => vite?.ws.send({
+		type: "full-reload",
+		path: "*"
+	});
+	const config = await createViteConfig(getContext, "development", { onSsrUpdate: fullReload });
+	vite = await createServer({
+		...config,
+		appType: "custom",
+		server: {
+			...config.server,
+			middlewareMode: true,
+			hmr: { server: httpServer }
+		}
+	});
+	const ssr = vite.environments.ssr;
+	if (!ssr || !isRunnableDevEnvironment(ssr)) throw new Error("The Vite SSR environment is not runnable.");
+	const render = async (route, url) => {
+		const { render } = await ssr.runner.import(VIRTUAL_SERVER);
+		const inlineStyles = await Promise.all(styleEntries(context).map(async (file) => {
+			return {
+				id: file,
+				css: (await ssr.runner.import(`${file}?inline`)).default
+			};
+		}));
+		const html = await render({
+			document: context.document,
+			site: context.site,
+			page: route.page,
+			assets: {
+				styles: [],
+				inlineStyles,
+				scripts: [`${context.config.base}@id/__x00__${VIRTUAL_CLIENT}`],
+				modulePreloads: []
+			}
+		});
+		return vite.transformIndexHtml(url, html);
+	};
+	vite.middlewares.use(async (req, res, next) => {
+		const url = req.url ?? "/";
+		const pathname = decodeURIComponent(url.split(/[?#]/)[0] ?? "/");
+		try {
+			const assetFile = context.assets.get(pathname);
+			if (assetFile && existsSync(assetFile)) {
+				res.setHeader("Content-Type", CONTENT_TYPES[extname(assetFile)] ?? "application/octet-stream");
+				createReadStream(assetFile).pipe(res);
+				return;
+			}
+			const route = matchRoute(context, pathname);
+			const text = context.textFiles.get(pathname) ?? (route && wantsMarkdown(req) ? context.textFiles.get(route.page.markdownUrl ?? "") : void 0);
+			if (text !== void 0) {
+				res.setHeader("Content-Type", CONTENT_TYPES[extname(pathname)] ?? CONTENT_TYPES[".md"]);
+				res.end(text);
+				return;
+			}
+			if (req.method !== "GET" && req.method !== "HEAD") return next();
+			if (route || isHtmlRequest(req, pathname)) {
+				const html = await render(route ?? context.notFound, url);
+				res.statusCode = route ? 200 : 404;
+				res.setHeader("Content-Type", "text/html; charset=utf-8");
+				res.end(html);
+				return;
+			}
+			next();
+		} catch (error) {
+			vite.ssrFixStacktrace(error);
+			consola.error(error);
+			res.statusCode = 500;
+			res.setHeader("Content-Type", "text/html; charset=utf-8");
+			res.end(errorPage(error));
+		}
+	});
+	httpServer.on("request", vite.middlewares);
+	if (options.watch !== false) {
+		const watched = new Set(context.watchFiles.map((file) => resolve(file)));
+		vite.watcher.add([...watched]);
+		let timer;
+		const onChange = (file) => {
+			if (!watched.has(resolve(file))) return;
+			clearTimeout(timer);
+			timer = setTimeout(async () => {
+				try {
+					const previous = context;
+					const next = await resolveContext(options);
+					if (next.theme.root !== previous.theme.root || next.config.base !== previous.config.base) consola.warn("The theme or base path changed. Restart yaakdoc to apply it.");
+					context = next;
+					for (const file of next.watchFiles) if (!watched.has(resolve(file))) {
+						watched.add(resolve(file));
+						vite.watcher.add(file);
+					}
+					const mod = ssr.moduleGraph.getModuleById(`\0${VIRTUAL_SERVER}`);
+					if (mod) ssr.moduleGraph.invalidateModule(mod);
+					consola.success(`Reloaded ${colors.dim(file.replace(`${context.root}/`, ""))}`);
+					options.onReload?.(context);
+					fullReload();
+				} catch (error) {
+					consola.error(error.message);
+				}
+			}, 50);
+		};
+		vite.watcher.on("change", onChange);
+		vite.watcher.on("add", onChange);
+	}
+	const port = await listen(httpServer, options.port ?? context.config.server.port, options.host ?? context.config.server.host);
+	const url = serverUrl(options.host ?? context.config.server.host, port, context.config.base);
+	if (options.open ?? context.config.server.open) {
+		const { default: openBrowser } = await import("./open-C4Bh1af9.js");
+		openBrowser(url);
+	}
+	return {
+		url,
+		vite,
+		httpServer,
+		getContext,
+		close: async () => {
+			await vite.close();
+			await new Promise((done) => httpServer.close(() => done()));
+		}
+	};
+}
+function wantsMarkdown(req) {
+	const accept = req.headers.accept ?? "";
+	return accept.includes("text/markdown") && !accept.includes("text/html");
+}
+function isHtmlRequest(req, pathname) {
+	return (req.headers.accept ?? "").includes("text/html") && !extname(pathname);
+}
+const escapeHtml = (value) => value.replace(/[&<>"]/g, (char) => ({
+	"&": "&amp;",
+	"<": "&lt;",
+	">": "&gt;",
+	"\"": "&quot;"
+})[char]);
+function errorPage(error) {
+	return `<!doctype html><meta charset="utf-8"><title>yaakdoc error</title><style>body{font:14px/1.5 ui-monospace,monospace;padding:2rem;background:#1e1e2e;color:#f5e0dc}pre{white-space:pre-wrap;color:#f38ba8}</style><h1>Render error</h1><pre>${escapeHtml(error.stack ?? error.message)}</pre><script type="module" src="/@vite/client"><\/script>`;
+}
+//#endregion
+//#region src/node/fs.ts
+/** Writes pretty-printed JSON with a trailing newline (like editors and formatters do). */
+function writeJson(file, value) {
+	return writeFile(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+//#endregion
+//#region src/node/init.ts
+/** `$schema` value for yaakdoc.config.json: local copy when installed, otherwise unpkg. */
+function schemaUrl(cwd) {
+	const local = join(cwd, "node_modules", "yaakdoc", "config.schema.json");
+	return existsSync(local) ? "./node_modules/yaakdoc/config.schema.json" : `https://unpkg.com/yaakdoc@${VERSION}/config.schema.json`;
+}
+/** Writes a yaakdoc.config.json (with `$schema` for editor autocomplete). */
+async function init(options = {}) {
+	const cwd = resolve(options.cwd ?? process.cwd());
+	const file = join(cwd, "yaakdoc.config.json");
+	if (existsSync(file) && !options.force) throw new Error("yaakdoc.config.json already exists.");
+	const config = {
+		$schema: schemaUrl(cwd),
+		...options.config
+	};
+	if (!config.export) try {
+		config.export = `./${relative(cwd, await detectExport(cwd))}`;
+	} catch {}
+	await writeJson(file, config);
+	return {
+		file,
+		config
+	};
+}
+//#endregion
+//#region src/node/eject.ts
+const DEFAULT_IGNORE = [
+	"node_modules/**",
+	"dist/**",
+	"package.json",
+	"CHANGELOG.md",
+	"**/*.test.*",
+	"test/**"
+];
+/** Copies the current theme's source into the project so it can be customized freely. */
+async function eject(options = {}) {
+	const cwd = resolve(options.cwd ?? process.cwd());
+	const { config, configFile, root } = await loadConfig({
+		cwd,
+		...options.configFile ? { configFile: options.configFile } : {}
+	});
+	const theme = await resolveTheme(config.theme, {
+		root,
+		themeOptions: config.themeOptions
+	});
+	const out = resolve(cwd, options.out ?? "theme");
+	if (out === theme.root) throw new Error(`The theme is already located at ${out}.`);
+	if (existsSync(out) && readdirSync(out).length > 0 && !options.force) throw new Error(`${relative(cwd, out) || out} already exists and is not empty. Use --force to overwrite.`);
+	const files = await glob(theme.definition.eject?.files ?? ["**/*"], {
+		cwd: theme.root,
+		ignore: DEFAULT_IGNORE,
+		dot: false,
+		onlyFiles: true
+	});
+	if (!files.some((file) => resolve(theme.root, file) === theme.manifest)) files.push(relative(theme.root, theme.manifest));
+	for (const file of files) {
+		const target = join(out, file);
+		await mkdir(dirname(target), { recursive: true });
+		await copyFile(join(theme.root, file), target);
+	}
+	let configResult = null;
+	if (options.updateConfig !== false) {
+		const themePath = `./${relative(configFile ? dirname(configFile) : cwd, out).split("\\").join("/")}`;
+		if (configFile && extname(configFile).startsWith(".json")) {
+			const json = JSON.parse(await readFile(configFile, "utf8"));
+			json.theme = themePath;
+			await writeJson(configFile, json);
+			configResult = {
+				file: configFile,
+				updated: true,
+				created: false
+			};
+		} else if (configFile) configResult = {
+			file: configFile,
+			updated: false,
+			created: false
+		};
+		else {
+			const file = join(cwd, "yaakdoc.config.json");
+			await writeJson(file, {
+				$schema: schemaUrl(cwd),
+				theme: themePath
+			});
+			configResult = {
+				file,
+				updated: true,
+				created: true
+			};
+		}
+	}
+	return {
+		out,
+		files: files.sort(),
+		theme: theme.name,
+		dependencies: theme.definition.eject?.dependencies ?? [],
+		config: configResult
+	};
+}
+//#endregion
+//#region src/node/preview.ts
+/** Serves a built site (like a static host would, including 404.html and base path). */
+async function preview(options = {}) {
+	const { config } = await loadConfig({
+		cwd: options.cwd ?? process.cwd(),
+		...options.configFile ? { configFile: options.configFile } : {}
+	});
+	const outDir = options.outDir ? resolve(options.cwd ?? process.cwd(), options.outDir) : config.outDir;
+	if (!existsSync(join(outDir, "index.html"))) throw new Error(`No build found in ${outDir}. Run \`yaakdoc build\` first.`);
+	const serve = sirv(outDir, {
+		dev: true,
+		etag: true,
+		extensions: ["html"],
+		setHeaders: (res, pathname) => {
+			const type = CONTENT_TYPES[extname(pathname)];
+			if (type) res.setHeader("Content-Type", type);
+		}
+	});
+	const notFoundFile = join(outDir, "404.html");
+	const base = config.base;
+	const server = createServer$1((req, res) => {
+		const url = req.url ?? "/";
+		if (!url.startsWith(base) && base !== "/") {
+			res.writeHead(302, { Location: base });
+			res.end();
+			return;
+		}
+		req.url = base === "/" ? url : url.slice(base.length - 1);
+		serve(req, res, () => {
+			res.statusCode = 404;
+			if (existsSync(notFoundFile)) {
+				res.setHeader("Content-Type", "text/html; charset=utf-8");
+				res.end(readFileSync(notFoundFile));
+			} else res.end("Not found");
+		});
+	});
+	const host = options.host ?? config.server.host;
+	const url = serverUrl(host, await listen(server, options.port ?? config.server.port, host), base);
+	if (options.open) (await import("./open-C4Bh1af9.js")).default(url);
+	return {
+		url,
+		server,
+		close: () => new Promise((done) => server.close(() => done()))
+	};
+}
+//#endregion
+export { createDevServer as a, VIRTUAL_SERVER as c, matchRoute as d, resolveContext as f, themePackageCandidates as h, schemaUrl as i, yaakdocPlugin as l, resolveTheme as m, eject as n, build$1 as o, ThemeError as p, init as r, VIRTUAL_CLIENT as s, preview as t, VERSION as u };