@ox-content/vite-plugin 2.88.0 → 2.90.0

package/dist/index.cjs

@@ -109,6 +109,119 @@ function createMarkdownEnvironment(options) {
 	};
 }
 //#endregion
+//#region src/highlight-native.ts
+/**
+* Extract text content from a hast node.
+*/
+function getTextContent(node) {
+	let text = "";
+	if ("children" in node) {
+		for (const child of node.children) if (child.type === "text") text += child.value;
+		else if (child.type === "element") text += getTextContent(child);
+	}
+	return text;
+}
+function normalizeClassName(className) {
+	if (Array.isArray(className)) return className.filter((value) => typeof value === "string");
+	if (typeof className === "string" && className) return className.split(/\s+/).filter(Boolean);
+	return [];
+}
+/**
+* Highlights with the native tree-sitter engine, or `null` when it has no
+* grammar for `lang`.
+*
+* Parsing once and walking the tree is roughly eight times faster than
+* matching TextMate patterns line by line — 10.5 ms against 81.5 ms over the
+* documentation corpus's code blocks — and it emits the same
+* `--octc-shiki-*` markup, so themes are unaffected.
+*/
+function highlightNatively(code, lang) {
+	try {
+		return require_vitepress.importNapiModuleSync().highlightCodeBlock(code, lang);
+	} catch {
+		return null;
+	}
+}
+/** Whether the native engine claims `lang`. */
+function nativeSupports(lang) {
+	try {
+		return require_vitepress.importNapiModuleSync().supportsHighlightLanguage(lang);
+	} catch {
+		return false;
+	}
+}
+/**
+* Whether any block in this tree still needs Shiki.
+*
+* Creating a Shiki highlighter parses two dozen TextMate grammars, about
+* 190 ms, so a document whose languages are all covered natively must not
+* touch it at all.
+*/
+function treeNeedsShiki(tree, nativeThemeApplies) {
+	if (!nativeThemeApplies) return true;
+	let needed = false;
+	const walk = (node) => {
+		if (needed || !("children" in node)) return;
+		for (const child of node.children) {
+			if (child.type !== "element") continue;
+			if (child.tagName === "code") {
+				const lang = languageOf(child);
+				if (lang !== null && !nativeSupports(lang)) {
+					needed = true;
+					return;
+				}
+			}
+			walk(child);
+		}
+	};
+	walk(tree);
+	return needed;
+}
+/** The `language-*` class on a `<code>` element, if it carries one. */
+function languageOf(codeElement) {
+	const className = normalizeClassName(codeElement.properties?.className).find((value) => value.startsWith("language-"));
+	return className ? className.slice(9) : null;
+}
+/**
+* Highlights every code block in a rendered document in one native call.
+*
+* Returns the rewritten HTML and the languages it declined, so the caller
+* knows whether Shiki still has to run over the result. Returns `null` when
+* the native module is unavailable.
+*
+* This exists because the plumbing dwarfed the work: walking each page
+* through an HTML parser and serializer to find `<pre>` elements cost 139 ms
+* over the documentation corpus, and re-parsing each highlighted block to
+* splice it back cost another 38 ms, against 14 ms of actual highlighting.
+*
+* It runs off the main thread. The synchronous binding held the event loop
+* for the whole pass, so a build asking for several pages at once still got
+* them one at a time — `Promise.all` over the corpus measured the same as
+* awaiting each page in turn.
+*/
+async function highlightDocumentNatively(html) {
+	try {
+		return await require_vitepress.importNapiModuleSync().highlightHtmlCodeBlocksAsync(html);
+	} catch {
+		return null;
+	}
+}
+/**
+* Splices `replacements` back over the blocks the native pass left pending.
+*
+* Entry `i` is the highlighted `<pre>` for pending block `i`, or an empty
+* string to leave that block alone. This keeps a page that needs one exotic
+* grammar — a Vue SFC, a Mermaid diagram — off the HTML round trip, rather
+* than surrendering the whole document for it.
+*/
+function applyPendingHighlights(html, replacements) {
+	try {
+		return require_vitepress.importNapiModuleSync().applyPendingHighlights(html, replacements);
+	} catch {
+		return html;
+	}
+}
+//#endregion
 //#region src/shiki-theme.ts
 /**
 * Name callers pass as `highlightTheme` to render syntax colors as CSS custom
@@ -233,17 +346,19 @@ function rehypeShikiHighlight(options) {
 	const { theme, langs } = options;
 	return async (tree) => {
 		const { themeName } = normalizeThemeInput(theme);
-		const highlighter = await getHighlighter(theme, langs);
+		const nativeThemeApplies = themeName === CSS_VARIABLES_THEME;
+		const highlighter = treeNeedsShiki(tree, nativeThemeApplies) ? await getHighlighter(theme, langs) : void 0;
 		const highlightBlockCode = (codeElement) => {
 			let lang = "text";
 			const langClass = normalizeClassName(codeElement.properties?.className).find((value) => value.startsWith("language-"));
 			if (langClass) lang = langClass.replace("language-", "");
 			const codeText = getTextContent(codeElement);
 			try {
-				const highlighted = highlighter.codeToHtml(codeText, {
+				const highlighted = (nativeThemeApplies ? highlightNatively(codeText, lang) : null) ?? highlighter?.codeToHtml(codeText, {
 					lang,
 					theme: themeName
 				});
+				if (highlighted === void 0) return null;
 				const parsed = (0, unified.unified)().use(rehypeParse$3, { fragment: true }).parse(highlighted);
 				if (parsed.children[0]?.type === "element") {
 					const highlightedPre = parsed.children[0];
@@ -262,10 +377,11 @@ function rehypeShikiHighlight(options) {
 			lang = langClass.replace("language-", "");
 			const codeText = getTextContent(codeElement);
 			try {
-				const highlighted = highlighter.codeToHtml(codeText, {
+				const highlighted = (nativeThemeApplies ? highlightNatively(codeText, lang) : null) ?? highlighter?.codeToHtml(codeText, {
 					lang,
 					theme: themeName
 				});
+				if (highlighted === void 0) return null;
 				const parsed = (0, unified.unified)().use(rehypeParse$3, { fragment: true }).parse(highlighted);
 				if (parsed.children[0]?.type === "element") {
 					const highlightedCode = parsed.children[0].children.find((child) => child.type === "element" && child.tagName === "code");
@@ -289,7 +405,8 @@ function rehypeShikiHighlight(options) {
 				const child = node.children[i];
 				if (child.type === "element" && child.tagName === "pre") {
 					const codeElement = child.children.find((c) => c.type === "element" && c.tagName === "code");
-					if (codeElement) {
+					const alreadyHighlighted = normalizeClassName(child.properties?.className).includes("shiki");
+					if (codeElement && !alreadyHighlighted) {
 						const highlightedPre = highlightBlockCode(codeElement);
 						if (highlightedPre) node.children[i] = highlightedPre;
 					}
@@ -303,22 +420,6 @@ function rehypeShikiHighlight(options) {
 	};
 }
 /**
-* Extract text content from a hast node.
-*/
-function getTextContent(node) {
-	let text = "";
-	if ("children" in node) {
-		for (const child of node.children) if (child.type === "text") text += child.value;
-		else if (child.type === "element") text += getTextContent(child);
-	}
-	return text;
-}
-function normalizeClassName(className) {
-	if (Array.isArray(className)) return className.filter((value) => typeof value === "string");
-	if (typeof className === "string" && className) return className.split(/\s+/).filter(Boolean);
-	return [];
-}
-/**
 * Apply syntax highlighting to HTML using Shiki.
 */
 async function highlightCode(html, theme = CSS_VARIABLES_THEME, langs = []) {
@@ -329,6 +430,83 @@ async function highlightCode(html, theme = CSS_VARIABLES_THEME, langs = []) {
 	return String(result);
 }
 //#endregion
+//#region src/highlight-pending.ts
+/**
+* Highlighting the blocks the native pass could not claim.
+*
+* These arrive already named — the native pass reports each one's language —
+* which lets this load exactly the grammars a page needs instead of the whole
+* bundled set, and splice each result back without an HTML parser.
+*/
+/**
+* A highlighter that starts with no grammars and gains them on demand.
+*
+* `getHighlighter` loads all two dozen `BUILTIN_LANGS` up front, because the
+* tree walk it serves discovers a page's languages only while rewriting it.
+* The pending list does not have that problem — it names every language it
+* needs — and paying for two dozen TextMate grammars to highlight one Vue
+* block is most of what a page with an exotic block costs.
+*/
+const lazyHighlighterCache = /* @__PURE__ */ new Map();
+const loadedLangs = /* @__PURE__ */ new WeakMap();
+async function getLazyHighlighter(theme, customLangs, wanted) {
+	const { themeInput } = normalizeThemeInput(theme);
+	const cacheKey = JSON.stringify({
+		theme: themeInput,
+		langs: customLangs
+	});
+	let highlighterPromise = lazyHighlighterCache.get(cacheKey);
+	if (!highlighterPromise) {
+		highlighterPromise = (0, shiki.createHighlighter)({
+			themes: [themeInput],
+			langs: customLangs
+		});
+		lazyHighlighterCache.set(cacheKey, highlighterPromise);
+	}
+	const highlighter = await highlighterPromise;
+	let loaded = loadedLangs.get(highlighter);
+	if (!loaded) {
+		loaded = /* @__PURE__ */ new Set();
+		loadedLangs.set(highlighter, loaded);
+	}
+	const missing = [...new Set(wanted.filter((lang) => !loaded.has(lang) && BUILTIN_LANGS.includes(lang)))];
+	if (missing.length > 0) await Promise.all(missing.map(async (lang) => {
+		try {
+			await highlighter.loadLanguage(lang);
+			loaded.add(lang);
+		} catch {}
+	}));
+	return highlighter;
+}
+/**
+* Highlight the blocks the native pass left pending, in order.
+*
+* Entry `i` of the result is the `<pre>` for block `i`, or an empty string
+* when Shiki has no grammar for it either — in which case the block is left
+* exactly as it arrived, the same outcome the tree walk reached by keeping the
+* original element.
+*
+* This is the whole point of the pending list: a page whose only unsupported
+* block is a Mermaid diagram used to be handed to the tree walk in full, which
+* re-highlighted every one of its other blocks and paid for a parse and a
+* serialize of the page to do it.
+*/
+async function highlightPendingBlocks(blocks, theme = CSS_VARIABLES_THEME, langs = []) {
+	if (blocks.length === 0) return [];
+	const { themeName } = normalizeThemeInput(theme);
+	const highlighter = await getLazyHighlighter(theme, langs, blocks.map((block) => block.language));
+	return blocks.map((block) => {
+		try {
+			return highlighter.codeToHtml(block.source, {
+				lang: block.language,
+				theme: themeName
+			});
+		} catch {
+			return "";
+		}
+	});
+}
+//#endregion
 //#region src/plugins/mermaid.ts
 /**
 * Mermaid Plugin - Native Rust renderer via NAPI
@@ -342,21 +520,21 @@ var mermaid_exports = /* @__PURE__ */ require_vitepress.__exportAll({
 	transformMermaidStatic: () => transformMermaidStatic
 });
 /** Cached NAPI bindings */
-let napiBindings$1 = null;
-let napiLoadAttempted$1 = false;
+let napiBindings = null;
+let napiLoadAttempted = false;
 async function loadNapi() {
-	if (napiLoadAttempted$1) return napiBindings$1;
-	napiLoadAttempted$1 = true;
+	if (napiLoadAttempted) return napiBindings;
+	napiLoadAttempted = true;
 	try {
 		const binding = await require_vitepress.importNapiModule();
 		if (typeof binding.transformMermaid !== "function") {
-			napiBindings$1 = null;
+			napiBindings = null;
 			return null;
 		}
-		napiBindings$1 = binding;
+		napiBindings = binding;
 		return binding;
 	} catch {
-		napiBindings$1 = null;
+		napiBindings = null;
 		return null;
 	}
 }
@@ -1947,24 +2125,25 @@ function normalizeDiagnostic(diagnostic) {
 //#endregion
 //#region src/transform.ts
 /**
-* Cached NAPI bindings instance.
-* Loaded on first use and reused for subsequent transformations.
-* @internal
-*/
-let napiBindings;
-/**
-* Flag to prevent repeated NAPI loading attempts.
-* Set to true after first load attempt (success or failure).
+* The NAPI load, cached as the promise rather than as its result.
+*
+* The load yields, and a caller arriving during that yield has to wait for it
+* rather than read a result that is not there yet. Holding the promise is what
+* makes every caller wait for the same load; holding an "already attempted"
+* flag beside an unset result meant the first page to arrive loaded the module
+* and every page behind it concluded there were no bindings at all.
+*
 * @internal
 */
-let napiLoadAttempted = false;
+let napiLoad;
 /**
 * Lazily loads and caches NAPI bindings.
 *
 * This function uses lazy loading to defer the import of NAPI bindings
 * until they're actually needed. The bindings are loaded only once and
-* cached for subsequent uses. If loading fails (e.g., bindings not built),
-* the failure is cached to avoid repeated load attempts.
+* cached for subsequent uses, including by callers that ask for them while
+* that first load is still in flight. If loading fails (e.g., bindings not
+* built), the failure is cached to avoid repeated load attempts.
 *
 * ## Performance Considerations
 *
@@ -1995,18 +2174,12 @@ let napiLoadAttempted = false;
 *
 * @internal
 */
-async function loadNapiBindings() {
-	if (napiLoadAttempted) return napiBindings ?? null;
-	napiLoadAttempted = true;
-	try {
-		const mod = await require_vitepress.importNapiModule();
-		napiBindings = mod;
-		return mod;
-	} catch (error) {
+function loadNapiBindings() {
+	napiLoad ??= require_vitepress.importNapiModule().catch((error) => {
 		if (process.env.DEBUG) console.debug("[ox-content] NAPI bindings load failed:", error);
-		napiBindings = null;
 		return null;
-	}
+	});
+	return napiLoad;
 }
 async function transformMarkdown(source, filePath, options, ssgOptions) {
 	const napi = await loadNapiBindings();
@@ -2061,9 +2234,18 @@ async function transformMarkdown(source, filePath, options, ssgOptions) {
 	const { html: protectedHtml, svgs } = protectMermaidSvgs(html);
 	html = protectedHtml;
 	if (options.highlight) {
-		const originalHtml = html;
-		const highlightedHtml = await highlightCode(html, options.highlightTheme, options.highlightLangs);
-		html = napi.mergeHighlightedCodeBlocks(originalHtml, highlightedHtml);
+		const native = options.highlightTheme === void 0 || options.highlightTheme === "css-variables" ? await highlightDocumentNatively(html) : null;
+		if (native && native.skipped.length === 0) {
+			html = native.html;
+			if (native.pending.length > 0) {
+				const replacements = await highlightPendingBlocks(native.pending, options.highlightTheme, options.highlightLangs);
+				html = applyPendingHighlights(html, replacements);
+			}
+		} else {
+			const originalHtml = html;
+			const highlightedHtml = await highlightCode(html, options.highlightTheme, options.highlightLangs);
+			html = napi.mergeHighlightedCodeBlocks(originalHtml, highlightedHtml);
+		}
 	}
 	html = await transformBuiltinEmbeds(html, options.embeds ?? {
 		github: {},
@@ -2177,6 +2359,56 @@ if (import.meta.hot) {
 }
 //#endregion
 //#region src/docs.ts
+/**
+* Source Documentation Extraction and Generation
+*
+* This module provides comprehensive tools for extracting JSDoc/TSDoc comments
+* from TypeScript/JavaScript source files and automatically generating Markdown
+* documentation.
+*
+* ## Features
+*
+* - **Automatic Extraction**: Parses JSDoc comments from functions, classes, interfaces, and types
+* - **Flexible Filtering**: Include/exclude patterns for selective documentation
+* - **Markdown Generation**: Converts extracted docs to organized Markdown files
+* - **Navigation Generation**: Auto-generates sidebar navigation metadata
+* - **GitHub Links**: Includes clickable links to source code on GitHub
+*
+* ## Supported JSDoc Tags
+*
+* - `@param {type} name - description` - Function parameter documentation
+* - `@returns {type} description` - Return value documentation
+* - `@example` - Code examples (multi-line blocks)
+* - `@private` - Mark item as private (excluded from docs if private=false)
+* - `@default value` - Default parameter value
+* - Custom tags are preserved in the `tags` field
+*
+* ## Usage Flow
+*
+* 1. Call `extractDocs()` to parse source files
+* 2. Call `generateMarkdown()` to create Markdown content
+* 3. Call `writeDocs()` to write files to output directory
+* 4. Generated nav.ts can be imported for sidebar navigation
+*
+* @example
+* ```typescript
+* import { extractDocs, generateMarkdown, writeDocs } from './docs';
+*
+* const docsOptions = {
+*   enabled: true,
+*   src: ['./src'],
+*   out: './docs/api',
+*   include: ['**\/*.ts'],
+*   exclude: ['**\/*.test.ts'],
+*   groupBy: 'file',
+*   githubUrl: 'https://github.com/user/project',
+* };
+*
+* const extracted = await extractDocs(['./src'], docsOptions);
+* const markdown = generateMarkdown(extracted, docsOptions);
+* await writeDocs(markdown, './docs/api', extracted, docsOptions);
+* ```
+*/
 const DEFAULT_DOCS_INCLUDE = [
 	"**/*.ts",
 	"**/*.tsx",
@@ -2317,7 +2549,7 @@ async function writeDocs(docs, outDir, extractedDocs, options) {
 	napi.writeGeneratedDocs(docs, outDir, extractedDocs ? toRustDocsModules(extractedDocs) : void 0, {
 		generateNav: options?.generateNav ?? false,
 		groupBy: options?.groupBy ?? "file",
-		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		generatedAt: existingGeneratedAt(outDir) ?? (/* @__PURE__ */ new Date()).toISOString(),
 		basePath: options?.basePath,
 		pathStrategy: options?.pathStrategy,
 		groupOrder: options?.groupOrder,
@@ -2327,6 +2559,15 @@ async function writeDocs(docs, outDir, extractedDocs, options) {
 		singleEntryRoot: options?.singleEntryRoot
 	});
 }
+/** Keep `docs.json`'s timestamp stable across regenerations of the same tree. */
+function existingGeneratedAt(outDir) {
+	try {
+		const parsed = JSON.parse((0, node_fs.readFileSync)(node_path.join(outDir, "docs.json"), "utf8"));
+		return typeof parsed.generatedAt === "string" && parsed.generatedAt.length > 0 ? parsed.generatedAt : void 0;
+	} catch {
+		return;
+	}
+}
 function toRustDocsModules(docs) {
 	return docs.map((doc) => ({
 		file: doc.file,
@@ -2767,6 +3008,45 @@ async function resolveTemplate(options, root) {
 	}
 }
 /**
+* Matches this package and every subpath it exports.
+*
+* A template's natural runtime is whatever renders it, and for the
+* framework-less kinds that is this package: `renderToString`, `raw`, `when`
+* and `each` live at its root, and the JSX runtime under `./jsx-runtime`.
+* Inlining them instead drags the entire plugin — chokidar, fsevents and all
+* — into the template bundle, which is what made importing it fail outright.
+*/
+const OX_CONTENT_PACKAGE = /^@ox-content\/vite-plugin(\/.*)?$/;
+/**
+* Whether `id` is a bare specifier, and so resolvable at runtime rather than
+* something the template bundle has to inline.
+*
+* Template bundles are written to `<root>/.cache/og-images/` and imported
+* from there, so Node resolves anything left external against the project's
+* own `node_modules`. Relative and absolute imports still bundle, which is
+* what a template actually needs — its own components travel with it.
+*/
+function isBareSpecifier(id) {
+	if (id.startsWith(".") || id.startsWith("/") || id.startsWith("\0")) return false;
+	return !/^[a-zA-Z]:[\\/]/.test(id);
+}
+/**
+* Rolldown input options for a `.ts` template bundle.
+*
+* A `.ts` template is the framework-less kind, so it has no single runtime to
+* externalize the way the `.vue`, `.svelte` and `.tsx` paths do — anything
+* from `node_modules` is better resolved at import time than inlined. Nothing
+* on this path has a compiler plugin, so nothing here needed bundling to be
+* loadable in the first place.
+*/
+function tsTemplateBundleOptions(templatePath) {
+	return {
+		input: templatePath,
+		platform: "node",
+		external: (id) => isBareSpecifier(id)
+	};
+}
+/**
 * Resolves a plain TypeScript template (existing behavior).
 */
 async function resolveTsTemplate(templatePath, options, root) {
@@ -2775,10 +3055,7 @@ async function resolveTsTemplate(templatePath, options, root) {
 	const cacheDir = path.join(root, ".cache", "og-images");
 	await fs.mkdir(cacheDir, { recursive: true });
 	const outfile = path.join(cacheDir, "_template.mjs");
-	const bundle = await rolldown({
-		input: templatePath,
-		platform: "node"
-	});
+	const bundle = await rolldown(tsTemplateBundleOptions(templatePath));
 	await bundle.write({
 		file: outfile,
 		format: "esm"
@@ -2800,11 +3077,16 @@ async function resolveVueTemplate(templatePath, options, root) {
 	const cacheDir = path.join(root, ".cache", "og-images");
 	await fs.mkdir(cacheDir, { recursive: true });
 	const outfile = path.join(cacheDir, "_template_vue.mjs");
+	const plugins = options.vuePlugin === "vizejs" ? await getVizejsPlugin() : [createVueCompilerPlugin()];
 	const bundle = await rolldown({
 		input: templatePath,
 		platform: "node",
-		external: ["vue", "vue/server-renderer"],
-		plugins: options.vuePlugin === "vizejs" ? await getVizejsPlugin() : [createVueCompilerPlugin()]
+		external: [
+			"vue",
+			"vue/server-renderer",
+			OX_CONTENT_PACKAGE
+		],
+		plugins
 	});
 	await bundle.write({
 		file: outfile,
@@ -2906,7 +3188,8 @@ async function resolveSvelteTemplate(templatePath, root) {
 			"svelte",
 			"svelte/server",
 			"svelte/internal",
-			"svelte/internal/server"
+			"svelte/internal/server",
+			OX_CONTENT_PACKAGE
 		],
 		plugins: [createSvelteCompilerPlugin()]
 	});
@@ -2965,7 +3248,8 @@ async function resolveReactTemplate(templatePath, root) {
 			"react/jsx-runtime",
 			"react/jsx-dev-runtime",
 			"react-dom",
-			"react-dom/server"
+			"react-dom/server",
+			OX_CONTENT_PACKAGE
 		],
 		transform: { jsx: "react-jsx" }
 	});
@@ -3297,311 +3581,676 @@ initIslands((el, props) => {
 `;
 }
 //#endregion
-//#region src/ssg.ts
-/**
-* SSG (Static Site Generation) module for ox-content
-*/
-/**
-* Deprecated compatibility export for consumers that imported the former
-* TypeScript SSG template. HTML generation is Rust-backed now.
-*
-* @deprecated Use `generateHtmlPage`/`buildSsg` instead.
-*/
-const DEFAULT_HTML_TEMPLATE = "<!-- ox-content default HTML template is Rust-backed -->";
+//#region src/page-context.ts
+var page_context_exports = /* @__PURE__ */ require_vitepress.__exportAll({
+	clearRenderContext: () => clearRenderContext,
+	generateFrontmatterTypes: () => generateFrontmatterTypes,
+	inferType: () => inferType,
+	setRenderContext: () => setRenderContext,
+	useIsActive: () => useIsActive,
+	useNav: () => useNav,
+	usePageProps: () => usePageProps,
+	useRenderContext: () => useRenderContext,
+	useSiteConfig: () => useSiteConfig
+});
 /**
-* Resolves SSG options with defaults.
+* Sets the current render context.
+* Called internally during page rendering.
+* @internal
 */
-function resolveSsgOptions(ssg) {
-	if (ssg === false) return {
-		enabled: false,
-		extension: ".html",
-		clean: false,
-		bare: false,
-		generateOgImage: false,
-		lastUpdated: false
-	};
-	if (ssg === true || ssg === void 0) return {
-		enabled: true,
-		extension: ".html",
-		clean: false,
-		bare: false,
-		generateOgImage: false,
-		lastUpdated: false,
-		theme: require_vitepress.resolveTheme(void 0)
-	};
-	return {
-		enabled: ssg.enabled ?? true,
-		extension: ssg.extension ?? ".html",
-		clean: ssg.clean ?? false,
-		bare: ssg.bare ?? false,
-		siteName: ssg.siteName,
-		ogImage: ssg.ogImage,
-		generateOgImage: ssg.generateOgImage ?? false,
-		lastUpdated: ssg.lastUpdated ?? false,
-		siteUrl: ssg.siteUrl,
-		theme: require_vitepress.resolveTheme(ssg.theme),
-		navigation: ssg.navigation
-	};
+function setRenderContext(ctx) {
+	currentContext = ctx;
 }
 /**
-* Extracts title from content or frontmatter.
+* Clears the current render context.
+* Called internally after page rendering.
+* @internal
 */
-function extractTitle$1(content, frontmatter) {
-	return require_vitepress.importNapiModuleSync().extractSsgTitle(content, typeof frontmatter.title === "string" ? frontmatter.title : void 0);
+function clearRenderContext() {
+	currentContext = null;
 }
 /**
-* Generates bare HTML page (no navigation, no styles).
+* Gets the current page props.
+*
+* @returns The current page props
+* @throws Error if called outside of a render context
+*
+* @example
+* ```tsx
+* function PageTitle() {
+*   const page = usePageProps();
+*   return <h1>{page.title}</h1>;
+* }
+* ```
 */
-function generateBareHtmlPage(content, title) {
-	return require_vitepress.importNapiModuleSync().generateSsgBareHtml(content, title);
+function usePageProps() {
+	if (!currentContext) throw new Error("[ox-content] usePageProps() must be called during page rendering. Make sure you are using it inside a theme component.");
+	return currentContext.page;
 }
 /**
-* Per-build cache for the Rust-facing nav conversion. `navGroups` is the same
-* `context.navItems` reference for every page in a build, so the deep recursive
-* copy below only needs to run once per build instead of once per page.
-*/
-const navGroupsForRustCache = /* @__PURE__ */ new WeakMap();
-function toRustNavItem(item) {
-	return {
-		title: item.title,
-		path: item.path,
-		href: item.href,
-		children: item.children?.map(toRustNavItem),
-		collapsed: item.collapsed,
-		stickyCollapsed: item.stickyCollapsed
-	};
-}
-function convertNavGroupsForRust(navGroups) {
-	const cached = navGroupsForRustCache.get(navGroups);
-	if (cached) return cached;
-	const converted = navGroups.map((group) => ({
-		title: group.title,
-		collapsed: group.collapsed,
-		stickyCollapsed: group.stickyCollapsed,
-		items: group.items.map(toRustNavItem)
-	}));
-	navGroupsForRustCache.set(navGroups, converted);
-	return converted;
+* Gets the site configuration.
+*
+* @returns The site configuration
+* @throws Error if called outside of a render context
+*
+* @example
+* ```tsx
+* function SiteHeader() {
+*   const site = useSiteConfig();
+*   return <header>{site.name}</header>;
+* }
+* ```
+*/
+function useSiteConfig() {
+	if (!currentContext) throw new Error("[ox-content] useSiteConfig() must be called during page rendering. Make sure you are using it inside a theme component.");
+	return currentContext.site;
 }
 /**
-* Converts a `TocEntry` tree into the plain shape the Rust binding expects.
-* Hoisted to module scope so it isn't reallocated for every page; the
-* per-page `.map` over `pageData.toc` still runs since the TOC is page-specific.
+* Gets the full render context.
+*
+* @returns The complete render context
+* @throws Error if called outside of a render context
+*
+* @example
+* ```tsx
+* function Layout({ children }) {
+*   const ctx = useRenderContext();
+*   return (
+*     <html>
+*       <head><title>{ctx.page.title} - {ctx.site.name}</title></head>
+*       <body>{children}</body>
+*     </html>
+*   );
+* }
+* ```
 */
-function toRustTocEntry(entry) {
-	return {
-		depth: entry.depth,
-		text: entry.text,
-		slug: entry.slug,
-		children: entry.children?.map(toRustTocEntry) ?? []
-	};
+function useRenderContext() {
+	if (!currentContext) throw new Error("[ox-content] useRenderContext() must be called during page rendering. Make sure you are using it inside a theme component.");
+	return currentContext;
 }
 /**
-* Per-build cache for the Rust-facing locale list. `i18n.locales` is the same
-* reference for every page in a build, so this mapping (and the `?? "ltr"`
-* default) only runs once per build instead of once per page.
+* Gets the navigation groups.
+*
+* @example
+* ```tsx
+* function Sidebar() {
+*   const nav = useNav();
+*   return (
+*     <nav>
+*       {each(nav, (group) => (
+*         <div>
+*           <h3>{group.title}</h3>
+*           <ul>
+*             {each(group.items, (item) => (
+*               <li><a href={item.href}>{item.title}</a></li>
+*             ))}
+*           </ul>
+*         </div>
+*       ))}
+*     </nav>
+*   );
+* }
+* ```
 */
-const rustLocalesCache = /* @__PURE__ */ new WeakMap();
-function toRustLocales(locales) {
-	const cached = rustLocalesCache.get(locales);
-	if (cached) return cached;
-	const converted = locales.map((locale) => ({
-		code: locale.code,
-		name: locale.name,
-		dir: locale.dir ?? "ltr"
-	}));
-	rustLocalesCache.set(locales, converted);
-	return converted;
+function useNav() {
+	return useSiteConfig().nav;
 }
 /**
-* Per-build cache for the locale-code list passed to `getSsgPageLocale`. The
-* `i18n.locales` reference is stable across a build, so the `.map` to codes
-* runs once instead of once per page.
+* Checks if the given path is the current page.
+*
+* @example
+* ```tsx
+* function NavLink({ href, children }) {
+*   const isActive = useIsActive(href);
+*   return <a href={href} class={isActive ? 'active' : ''}>{children}</a>;
+* }
+* ```
 */
-const localeCodesCache = /* @__PURE__ */ new WeakMap();
-function localeCodesFor(locales) {
-	const cached = localeCodesCache.get(locales);
-	if (cached) return cached;
-	const codes = locales.map((locale) => locale.code);
-	localeCodesCache.set(locales, codes);
-	return codes;
+function useIsActive(path) {
+	const page = usePageProps();
+	return page.path === path || page.url === path;
 }
 /**
-* Generates HTML page with navigation using Rust NAPI bindings.
+* Infers TypeScript types from frontmatter values.
 */
-async function generateHtmlPage(pageData, navGroups, siteName, base, ogImage, theme, locale, availableLocales) {
-	const mod = await require_vitepress.importNapiModule();
-	const tocForRust = pageData.toc.map(toRustTocEntry);
-	const navGroupsForRust = convertNavGroupsForRust(navGroups);
-	const themeForRust = theme ? require_vitepress.themeToNapi(theme) : void 0;
-	const entryPageForRust = pageData.entryPage ? {
-		hero: pageData.entryPage.hero ? {
-			name: pageData.entryPage.hero.name,
-			text: pageData.entryPage.hero.text,
-			tagline: pageData.entryPage.hero.tagline,
-			notice: pageData.entryPage.hero.notice ? {
-				title: pageData.entryPage.hero.notice.title,
-				body: pageData.entryPage.hero.notice.body
-			} : void 0,
-			image: pageData.entryPage.hero.image ? {
-				src: pageData.entryPage.hero.image.src,
-				lightSrc: pageData.entryPage.hero.image.lightSrc,
-				darkSrc: pageData.entryPage.hero.image.darkSrc,
-				alt: pageData.entryPage.hero.image.alt,
-				width: pageData.entryPage.hero.image.width,
-				height: pageData.entryPage.hero.image.height
-			} : void 0,
-			actions: pageData.entryPage.hero.actions?.map((a) => ({
-				theme: a.theme,
-				text: a.text,
-				link: a.link
-			}))
-		} : void 0,
-		features: pageData.entryPage.features?.map((f) => ({
-			icon: f.icon,
-			title: f.title,
-			details: f.details,
-			link: f.link,
-			linkText: f.linkText
-		}))
-	} : void 0;
-	return mod.generateSsgHtml({
-		title: pageData.title,
-		description: pageData.description,
-		content: pageData.content,
-		toc: tocForRust,
-		lastUpdated: pageData.lastUpdated,
-		path: pageData.path,
-		entryPage: entryPageForRust
-	}, navGroupsForRust, {
-		siteName,
-		base,
-		ogImage,
-		theme: themeForRust,
-		locale,
-		availableLocales: availableLocales ? toRustLocales(availableLocales) : void 0
-	});
-}
-async function externalizeSharedPageAssets(pages, outDir, base) {
-	const optimized = (await require_vitepress.importNapiModule()).externalizeSsgAssets(pages, outDir, base);
-	await Promise.all(optimized.assets.map(async (asset) => {
-		await fs_promises.mkdir(path.dirname(asset.outputPath), { recursive: true });
-		await fs_promises.writeFile(asset.outputPath, asset.content, "utf-8");
-	}));
-	return {
-		pages: optimized.pages,
-		assets: optimized.assets.map((asset) => asset.outputPath)
-	};
+function inferType(value) {
+	if (value === null) return "null";
+	if (value === void 0) return "undefined";
+	if (typeof value === "string") return "string";
+	if (typeof value === "number") return "number";
+	if (typeof value === "boolean") return "boolean";
+	if (Array.isArray(value)) {
+		if (value.length === 0) return "unknown[]";
+		const itemTypes = [...new Set(value.map(inferType))];
+		if (itemTypes.length === 1) return `${itemTypes[0]}[]`;
+		return `(${itemTypes.join(" | ")})[]`;
+	}
+	if (typeof value === "object") {
+		const entries = Object.entries(value);
+		if (entries.length === 0) return "Record<string, unknown>";
+		return `{ ${entries.map(([k, v]) => `${k}: ${inferType(v)}`).join("; ")} }`;
+	}
+	return "unknown";
 }
 /**
-* Converts a markdown file path to a relative URL path.
+* Generates TypeScript interface from frontmatter samples.
 */
-function getUrlPath$1(inputPath, srcDir) {
-	return require_vitepress.importNapiModuleSync().getSsgUrlPath(inputPath, srcDir);
+function generateFrontmatterTypes(samples, interfaceName = "PageFrontmatter") {
+	const fields = /* @__PURE__ */ new Map();
+	for (const sample of samples) for (const [key, value] of Object.entries(sample)) {
+		const existing = fields.get(key) ?? {
+			types: /* @__PURE__ */ new Set(),
+			count: 0
+		};
+		existing.types.add(inferType(value));
+		existing.count++;
+		fields.set(key, existing);
+	}
+	const lines = [
+		"/**",
+		" * Auto-generated frontmatter type based on your pages.",
+		" * DO NOT EDIT - this file is generated by ox-content.",
+		" */",
+		"",
+		`export interface ${interfaceName} {`
+	];
+	for (const [name, { types, count }] of fields) {
+		const isOptional = count < samples.length;
+		const typeStr = [...types].join(" | ");
+		const optionalMark = isOptional ? "?" : "";
+		lines.push(`  ${name}${optionalMark}: ${typeStr};`);
+	}
+	lines.push("}");
+	lines.push("");
+	lines.push(`export type PageProps = import('@ox-content/vite-plugin').PageProps<${interfaceName}>;`);
+	lines.push("");
+	return lines.join("\n");
 }
+var currentContext;
+var init_page_context = require_vitepress.__esmMin((() => {
+	currentContext = null;
+}));
+//#endregion
+//#region src/theme-renderer.ts
 /**
-* Resolves manual navigation config to the format used by the built-in SSG renderer.
+* Theme Renderer for Static HTML Generation
+*
+* Renders JSX theme components to static HTML strings.
+* No client-side JavaScript is included by default.
 */
-function resolveNavigationGroups(navigation, base, extension) {
-	if (!navigation) return;
-	return require_vitepress.importNapiModuleSync().resolveSsgNavigationGroups(navigation, base, extension);
-}
-function getPageLocale(urlPath, i18n) {
-	if (!i18n) return void 0;
-	return require_vitepress.importNapiModuleSync().getSsgPageLocale(urlPath, i18n.defaultLocale, localeCodesFor(i18n.locales)) ?? void 0;
-}
-function getRoutePaths(inputPath, srcDir, outDir, base, extension, siteUrl) {
-	return require_vitepress.importNapiModuleSync().resolveSsgRoutePaths(inputPath, srcDir, outDir, base, extension, siteUrl);
+init_page_context();
+/**
+* Renders a page using the theme component.
+*
+* @param page - Page data to render
+* @param options - Theme render options
+* @returns Rendered HTML string
+*/
+function renderPage(page, options) {
+	const { theme, siteName, base, nav, pages } = options;
+	setRenderContext({
+		page: {
+			title: page.title,
+			description: page.description,
+			html: page.html,
+			toc: page.toc,
+			lastUpdated: page.lastUpdated,
+			path: page.path,
+			url: page.url,
+			frontmatter: page.frontmatter,
+			layout: page.layout
+		},
+		site: {
+			name: siteName,
+			base,
+			nav,
+			pages: pages.map((p) => ({
+				title: p.title,
+				description: p.description,
+				html: p.html,
+				toc: p.toc,
+				lastUpdated: p.lastUpdated,
+				path: p.path,
+				url: p.url,
+				frontmatter: p.frontmatter,
+				layout: p.layout
+			}))
+		}
+	});
+	try {
+		const result = theme({ children: require_jsx_html.raw(page.html) });
+		const html = require_jsx_html.renderToString(result);
+		if (!html.trimStart().toLowerCase().startsWith("<!doctype")) return `<!DOCTYPE html>\n${html}`;
+		return html;
+	} finally {
+		clearRenderContext();
+	}
 }
 /**
-* Formats a file/dir name as a title.
+* Renders all pages and generates type definitions.
+*
+* @param pages - All pages to render
+* @param options - Theme render options
+* @returns Map of output paths to rendered HTML
 */
-function formatTitle(name) {
-	return require_vitepress.importNapiModuleSync().formatSsgTitle(name);
+async function renderAllPages(pages, options) {
+	const results = /* @__PURE__ */ new Map();
+	for (const page of pages) {
+		const html = renderPage(page, {
+			...options,
+			pages
+		});
+		results.set(page.url, html);
+	}
+	if (options.typesOutDir) await generateTypes(pages, options.typesOutDir);
+	return results;
 }
 /**
-* Collects all markdown files from the source directory.
+* Generates TypeScript type definitions from page frontmatter.
+*
+* @param pages - All pages
+* @param outDir - Output directory for types
 */
-async function collectMarkdownFiles(srcDir, extensions = DEFAULT_MARKDOWN_EXTENSIONS) {
-	return require_vitepress.importNapiModuleSync().collectSsgMarkdownFiles(srcDir, [...extensions]);
+async function generateTypes(pages, outDir) {
+	const types = generateFrontmatterTypes(pages.map((p) => p.frontmatter));
+	const typesPath = (0, node_path.join)(outDir, "page-props.d.ts");
+	await (0, node_fs_promises.mkdir)((0, node_path.dirname)(typesPath), { recursive: true });
+	await (0, node_fs_promises.writeFile)(typesPath, types, "utf-8");
 }
 /**
-* Builds navigation items from markdown files, grouped by directory.
+* Default theme component.
+* A minimal theme that renders page content with basic styling.
 */
-function buildNavItems(markdownFiles, srcDir, base, extension) {
-	return require_vitepress.importNapiModuleSync().buildSsgNavItems(markdownFiles, srcDir, base, extension);
+function DefaultTheme({ children }) {
+	const { usePageProps, useSiteConfig } = (init_page_context(), require_vitepress.__toCommonJS(page_context_exports));
+	const page = usePageProps();
+	const site = useSiteConfig();
+	return { __html: `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${escapeHtml(page.title)} - ${escapeHtml(site.name)}</title>
+  ${page.description ? `<meta name="description" content="${escapeHtml(page.description)}">` : ""}
+  <style>
+    :root {
+      --octc-color-primary: #4f6fae;
+      --octc-color-text: #131a30;
+      --octc-color-bg: #ffffff;
+      --octc-color-bg-alt: #f5f7fb;
+      --octc-color-text-muted: #4f607b;
+      --octc-color-border: #d2dbea;
+    }
+    body {
+      font-family: "IBM Plex Sans", "Avenir Next", "Segoe UI Variable", "Segoe UI", sans-serif;
+      line-height: 1.7;
+      color: var(--octc-color-text);
+      background: var(--octc-color-bg);
+      max-width: 800px;
+      margin: 0 auto;
+      padding: 2rem;
+    }
+    a { color: var(--octc-color-primary); }
+  </style>
+</head>
+<body>
+  <header>
+    <h1>${escapeHtml(site.name)}</h1>
+  </header>
+  <main>
+    ${children.__html}
+  </main>
+</body>
+</html>` };
+}
+function escapeHtml(str) {
+	return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
 /**
-* Builds navigation items from an explicit theme sidebar tree.
+* Creates a theme with layout switching support.
+*
+* @example
+* ```tsx
+* import { createTheme } from '@ox-content/vite-plugin';
+* import { DefaultLayout } from './layouts/Default';
+* import { EntryLayout } from './layouts/Entry';
+*
+* export default createTheme({
+*   layouts: {
+*     default: DefaultLayout,
+*     entry: EntryLayout,
+*   },
+* });
+* ```
 */
-function buildThemeNavItems(sidebar, base, extension) {
-	return require_vitepress.importNapiModuleSync().buildSsgThemeNavItems(sidebar, base, extension);
+function createTheme(config) {
+	const { layouts, defaultLayout = "default" } = config;
+	return function ThemeWithLayouts({ children }) {
+		const layoutName = usePageProps().layout ?? defaultLayout;
+		const Layout = layouts[layoutName] ?? layouts[defaultLayout];
+		if (!Layout) throw new Error(`[ox-content] Layout "${layoutName}" not found. Available layouts: ${Object.keys(layouts).join(", ")}`);
+		return Layout({ children });
+	};
 }
+//#endregion
+//#region src/ssg.ts
 /**
-* Builds all markdown files to static HTML.
+* SSG (Static Site Generation) module for ox-content
 */
-async function buildSsg(options, root) {
-	const ssgOptions = options.ssg;
-	if (!ssgOptions.enabled) return {
-		files: [],
-		errors: []
+/**
+* Deprecated compatibility export for consumers that imported the former
+* TypeScript SSG template. HTML generation is Rust-backed now.
+*
+* @deprecated Use `generateHtmlPage`/`buildSsg` instead.
+*/
+const DEFAULT_HTML_TEMPLATE = "<!-- ox-content default HTML template is Rust-backed -->";
+/**
+* Resolves SSG options with defaults.
+*/
+function resolveSsgOptions(ssg) {
+	if (ssg === false) return {
+		enabled: false,
+		extension: ".html",
+		clean: false,
+		bare: false,
+		generateOgImage: false,
+		lastUpdated: false
 	};
-	const srcDir = path.resolve(root, options.srcDir);
-	const outDir = path.resolve(root, options.outDir);
-	const generatedFiles = [];
-	const errors = [];
-	await cleanOutputDirectory(ssgOptions, outDir);
-	const markdownFiles = await collectMarkdownFiles(srcDir, options.extensions);
-	const context = await createBuildSsgContext(options, root, srcDir, outDir, markdownFiles);
-	const collected = await collectPageResults(context, markdownFiles);
-	errors.push(...collected.errors);
-	await generateOgImageAssets(context, collected, generatedFiles, errors);
-	await writeGeneratedPages(await generateHtmlPages(context, collected.pageResults, collected, errors), context, generatedFiles);
-	return {
-		files: generatedFiles,
-		errors
+	if (ssg === true || ssg === void 0) return {
+		enabled: true,
+		extension: ".html",
+		clean: false,
+		bare: false,
+		generateOgImage: false,
+		lastUpdated: false,
+		theme: require_vitepress.resolveTheme(void 0)
 	};
-}
-async function cleanOutputDirectory(ssgOptions, outDir) {
-	if (!ssgOptions.clean) return;
-	try {
-		await fs_promises.rm(outDir, {
-			recursive: true,
-			force: true
-		});
-	} catch {}
-}
-async function createBuildSsgContext(options, root, srcDir, outDir, markdownFiles) {
-	const ssgOptions = options.ssg;
-	const base = options.base.endsWith("/") ? options.base : options.base + "/";
 	return {
-		options,
-		ssgOptions,
-		root,
-		srcDir,
-		outDir,
-		base,
-		navItems: resolveNavigationGroups(ssgOptions.navigation, base, ssgOptions.extension) ?? (ssgOptions.theme?.sidebar.length ? buildThemeNavItems(ssgOptions.theme.sidebar, base, ssgOptions.extension) : buildNavItems(markdownFiles, srcDir, base, ssgOptions.extension)),
-		siteName: await resolveSiteName$1(root, ssgOptions),
-		shouldGenerateOgImages: shouldGenerateOgImages(options),
-		napi: ssgOptions.lastUpdated ? await require_vitepress.importNapiModule() : void 0
+		enabled: ssg.enabled ?? true,
+		extension: ssg.extension ?? ".html",
+		clean: ssg.clean ?? false,
+		bare: ssg.bare ?? false,
+		render: ssg.render,
+		lang: ssg.lang,
+		head: ssg.head,
+		bodyStart: ssg.bodyStart,
+		bodyEnd: ssg.bodyEnd,
+		siteName: ssg.siteName,
+		ogImage: ssg.ogImage,
+		generateOgImage: ssg.generateOgImage ?? false,
+		lastUpdated: ssg.lastUpdated ?? false,
+		siteUrl: ssg.siteUrl,
+		theme: require_vitepress.resolveTheme(ssg.theme),
+		navigation: ssg.navigation
 	};
 }
 /**
-* Whether this build emits one Open Graph image per page.
+* Extracts title from content or frontmatter.
+*/
+function extractTitle$1(content, frontmatter) {
+	return require_vitepress.importNapiModuleSync().extractSsgTitle(content, typeof frontmatter.title === "string" ? frontmatter.title : void 0);
+}
+/**
+* Generates a bare HTML page carrying head metadata and injected markup.
 *
-* `ssg.bare` deliberately does not turn this off. Bare mode only drops the
-* generated page shell, and bringing your own shell is exactly the case where
-* per-page OG images are still wanted — the images are written to the output
-* tree and the consumer injects the `<meta>` tags itself. Nothing in the bare
-* HTML references them, because bare output has no `<head>` to put them in.
+* Bare mode leaves the shell to the consumer, but the metadata here is
+* already computed for the themed page and cannot be recovered afterwards —
+* the generated OG image in particular was only discoverable by guessing at
+* the output directory. A page with none of it set renders exactly what bare
+* mode emitted before, which keeps the no-JS size baseline honest.
 */
-function shouldGenerateOgImages(options) {
-	return options.ogImage || options.ssg.generateOgImage;
+function generateBarePage(page) {
+	return require_vitepress.importNapiModuleSync().generateSsgBarePage(page);
 }
-async function resolveSiteName$1(root, ssgOptions) {
-	if (ssgOptions.siteName) return ssgOptions.siteName;
-	try {
+/**
+* Per-build cache for the Rust-facing nav conversion. `navGroups` is the same
+* `context.navItems` reference for every page in a build, so the deep recursive
+* copy below only needs to run once per build instead of once per page.
+*/
+const navGroupsForRustCache = /* @__PURE__ */ new WeakMap();
+function toRustNavItem(item) {
+	return {
+		title: item.title,
+		path: item.path,
+		href: item.href,
+		children: item.children?.map(toRustNavItem),
+		collapsed: item.collapsed,
+		stickyCollapsed: item.stickyCollapsed
+	};
+}
+function convertNavGroupsForRust(navGroups) {
+	const cached = navGroupsForRustCache.get(navGroups);
+	if (cached) return cached;
+	const converted = navGroups.map((group) => ({
+		title: group.title,
+		collapsed: group.collapsed,
+		stickyCollapsed: group.stickyCollapsed,
+		items: group.items.map(toRustNavItem)
+	}));
+	navGroupsForRustCache.set(navGroups, converted);
+	return converted;
+}
+/**
+* Converts a `TocEntry` tree into the plain shape the Rust binding expects.
+* Hoisted to module scope so it isn't reallocated for every page; the
+* per-page `.map` over `pageData.toc` still runs since the TOC is page-specific.
+*/
+function toRustTocEntry(entry) {
+	return {
+		depth: entry.depth,
+		text: entry.text,
+		slug: entry.slug,
+		children: entry.children?.map(toRustTocEntry) ?? []
+	};
+}
+/**
+* Per-build cache for the Rust-facing locale list. `i18n.locales` is the same
+* reference for every page in a build, so this mapping (and the `?? "ltr"`
+* default) only runs once per build instead of once per page.
+*/
+const rustLocalesCache = /* @__PURE__ */ new WeakMap();
+function toRustLocales(locales) {
+	const cached = rustLocalesCache.get(locales);
+	if (cached) return cached;
+	const converted = locales.map((locale) => ({
+		code: locale.code,
+		name: locale.name,
+		dir: locale.dir ?? "ltr"
+	}));
+	rustLocalesCache.set(locales, converted);
+	return converted;
+}
+/**
+* Per-build cache for the locale-code list passed to `getSsgPageLocale`. The
+* `i18n.locales` reference is stable across a build, so the `.map` to codes
+* runs once instead of once per page.
+*/
+const localeCodesCache = /* @__PURE__ */ new WeakMap();
+function localeCodesFor(locales) {
+	const cached = localeCodesCache.get(locales);
+	if (cached) return cached;
+	const codes = locales.map((locale) => locale.code);
+	localeCodesCache.set(locales, codes);
+	return codes;
+}
+/**
+* Generates HTML page with navigation using Rust NAPI bindings.
+*/
+async function generateHtmlPage(pageData, navGroups, siteName, base, ogImage, theme, locale, availableLocales) {
+	const mod = await require_vitepress.importNapiModule();
+	const tocForRust = pageData.toc.map(toRustTocEntry);
+	const navGroupsForRust = convertNavGroupsForRust(navGroups);
+	const themeForRust = theme ? require_vitepress.themeToNapi(theme) : void 0;
+	const entryPageForRust = pageData.entryPage ? {
+		hero: pageData.entryPage.hero ? {
+			name: pageData.entryPage.hero.name,
+			text: pageData.entryPage.hero.text,
+			tagline: pageData.entryPage.hero.tagline,
+			notice: pageData.entryPage.hero.notice ? {
+				title: pageData.entryPage.hero.notice.title,
+				body: pageData.entryPage.hero.notice.body
+			} : void 0,
+			image: pageData.entryPage.hero.image ? {
+				src: pageData.entryPage.hero.image.src,
+				lightSrc: pageData.entryPage.hero.image.lightSrc,
+				darkSrc: pageData.entryPage.hero.image.darkSrc,
+				alt: pageData.entryPage.hero.image.alt,
+				width: pageData.entryPage.hero.image.width,
+				height: pageData.entryPage.hero.image.height
+			} : void 0,
+			actions: pageData.entryPage.hero.actions?.map((a) => ({
+				theme: a.theme,
+				text: a.text,
+				link: a.link
+			}))
+		} : void 0,
+		features: pageData.entryPage.features?.map((f) => ({
+			icon: f.icon,
+			title: f.title,
+			details: f.details,
+			link: f.link,
+			linkText: f.linkText
+		}))
+	} : void 0;
+	return mod.generateSsgHtml({
+		title: pageData.title,
+		description: pageData.description,
+		content: pageData.content,
+		toc: tocForRust,
+		lastUpdated: pageData.lastUpdated,
+		path: pageData.path,
+		entryPage: entryPageForRust
+	}, navGroupsForRust, {
+		siteName,
+		base,
+		ogImage,
+		theme: themeForRust,
+		locale,
+		availableLocales: availableLocales ? toRustLocales(availableLocales) : void 0
+	});
+}
+async function externalizeSharedPageAssets(pages, outDir, base) {
+	const optimized = (await require_vitepress.importNapiModule()).externalizeSsgAssets(pages, outDir, base);
+	await Promise.all(optimized.assets.map(async (asset) => {
+		await fs_promises.mkdir(path.dirname(asset.outputPath), { recursive: true });
+		await fs_promises.writeFile(asset.outputPath, asset.content, "utf-8");
+	}));
+	return {
+		pages: optimized.pages,
+		assets: optimized.assets.map((asset) => asset.outputPath)
+	};
+}
+/**
+* Converts a markdown file path to a relative URL path.
+*/
+function getUrlPath$1(inputPath, srcDir) {
+	return require_vitepress.importNapiModuleSync().getSsgUrlPath(inputPath, srcDir);
+}
+/**
+* Resolves manual navigation config to the format used by the built-in SSG renderer.
+*/
+function resolveNavigationGroups(navigation, base, extension) {
+	if (!navigation) return;
+	return require_vitepress.importNapiModuleSync().resolveSsgNavigationGroups(navigation, base, extension);
+}
+function getPageLocale(urlPath, i18n) {
+	if (!i18n) return void 0;
+	return require_vitepress.importNapiModuleSync().getSsgPageLocale(urlPath, i18n.defaultLocale, localeCodesFor(i18n.locales)) ?? void 0;
+}
+function getRoutePaths(inputPath, srcDir, outDir, base, extension, siteUrl) {
+	return require_vitepress.importNapiModuleSync().resolveSsgRoutePaths(inputPath, srcDir, outDir, base, extension, siteUrl);
+}
+/**
+* Formats a file/dir name as a title.
+*/
+function formatTitle(name) {
+	return require_vitepress.importNapiModuleSync().formatSsgTitle(name);
+}
+/**
+* Collects all markdown files from the source directory.
+*/
+async function collectMarkdownFiles(srcDir, extensions = DEFAULT_MARKDOWN_EXTENSIONS) {
+	return require_vitepress.importNapiModuleSync().collectSsgMarkdownFiles(srcDir, [...extensions]);
+}
+/**
+* Builds navigation items from markdown files, grouped by directory.
+*/
+function buildNavItems(markdownFiles, srcDir, base, extension) {
+	return require_vitepress.importNapiModuleSync().buildSsgNavItems(markdownFiles, srcDir, base, extension);
+}
+/**
+* Builds navigation items from an explicit theme sidebar tree.
+*/
+function buildThemeNavItems(sidebar, base, extension) {
+	return require_vitepress.importNapiModuleSync().buildSsgThemeNavItems(sidebar, base, extension);
+}
+/**
+* Builds all markdown files to static HTML.
+*/
+async function buildSsg(options, root) {
+	const ssgOptions = options.ssg;
+	if (!ssgOptions.enabled) return {
+		files: [],
+		errors: [],
+		ogImages: {}
+	};
+	const srcDir = path.resolve(root, options.srcDir);
+	const outDir = path.resolve(root, options.outDir);
+	const generatedFiles = [];
+	const errors = [];
+	await cleanOutputDirectory(ssgOptions, outDir);
+	const markdownFiles = await collectMarkdownFiles(srcDir, options.extensions);
+	const context = await createBuildSsgContext(options, root, srcDir, outDir, markdownFiles);
+	const collected = await collectPageResults(context, markdownFiles);
+	errors.push(...collected.errors);
+	await generateOgImageAssets(context, collected, generatedFiles, errors);
+	await writeGeneratedPages(await generateHtmlPages(context, collected.pageResults, collected, errors), context, generatedFiles);
+	return {
+		files: generatedFiles,
+		errors,
+		ogImages: Object.fromEntries(collected.ogImageUrlMap)
+	};
+}
+async function cleanOutputDirectory(ssgOptions, outDir) {
+	if (!ssgOptions.clean) return;
+	try {
+		await fs_promises.rm(outDir, {
+			recursive: true,
+			force: true
+		});
+	} catch {}
+}
+async function createBuildSsgContext(options, root, srcDir, outDir, markdownFiles) {
+	const ssgOptions = options.ssg;
+	const base = options.base.endsWith("/") ? options.base : options.base + "/";
+	return {
+		options,
+		ssgOptions,
+		root,
+		srcDir,
+		outDir,
+		base,
+		navItems: resolveNavigationGroups(ssgOptions.navigation, base, ssgOptions.extension) ?? (ssgOptions.theme?.sidebar.length ? buildThemeNavItems(ssgOptions.theme.sidebar, base, ssgOptions.extension) : buildNavItems(markdownFiles, srcDir, base, ssgOptions.extension)),
+		siteName: await resolveSiteName$1(root, ssgOptions),
+		shouldGenerateOgImages: shouldGenerateOgImages(options),
+		napi: ssgOptions.lastUpdated ? await require_vitepress.importNapiModule() : void 0
+	};
+}
+/**
+* Whether this build emits one Open Graph image per page.
+*
+* `ssg.bare` deliberately does not turn this off. Bare mode only drops the
+* generated page shell, and bringing your own shell is exactly the case where
+* per-page OG images are still wanted — the images are written to the output
+* tree and the consumer injects the `<meta>` tags itself. Nothing in the bare
+* HTML references them, because bare output has no `<head>` to put them in.
+*/
+function shouldGenerateOgImages(options) {
+	return options.ogImage || options.ssg.generateOgImage;
+}
+async function resolveSiteName$1(root, ssgOptions) {
+	if (ssgOptions.siteName) return ssgOptions.siteName;
+	try {
 		const pkgPath = path.join(root, "package.json");
 		const pkg = JSON.parse(await fs_promises.readFile(pkgPath, "utf-8"));
 		return pkg.name ? formatTitle(pkg.name) : "Documentation";
@@ -3721,7 +4370,7 @@ async function generateHtmlPages(context, pageResults, collected, errors) {
 		generatedPages.push({
 			inputPath: pageResult.inputPath,
 			outputPath: pageResult.routePaths.outputPath,
-			html: await renderSsgPage(context, pageResult, collected.ogImageUrlMap)
+			html: await renderSsgPage(context, pageResult, collected, pageResults)
 		});
 	} catch (err) {
 		const errorMessage = err instanceof Error ? err.message : String(err);
@@ -3729,16 +4378,61 @@ async function generateHtmlPages(context, pageResults, collected, errors) {
 	}
 	return generatedPages;
 }
-async function renderSsgPage(context, pageResult, ogImageUrlMap) {
-	if (context.ssgOptions.bare) return generateBareHtmlPage(pageResult.transformedHtml, pageResult.title);
-	const pageData = createSsgPageData(pageResult);
+async function renderSsgPage(context, pageResult, collected, allPageResults) {
+	const { ogImageUrlMap } = collected;
 	const pageOgImage = context.shouldGenerateOgImages && ogImageUrlMap.has(pageResult.inputPath) ? ogImageUrlMap.get(pageResult.inputPath) : context.ssgOptions.ogImage;
+	if (context.ssgOptions.render) return renderPage(toThemePageData(pageResult), {
+		theme: context.ssgOptions.render,
+		siteName: context.siteName,
+		base: context.base,
+		nav: context.navItems,
+		pages: allPageResults.map(toThemePageData)
+	});
+	if (context.ssgOptions.bare) return generateBarePage({
+		title: pageResult.title,
+		content: pageResult.transformedHtml,
+		lang: context.ssgOptions.lang ?? getPageLocale(pageResult.routePaths.urlPath, context.options.i18n),
+		description: pageResult.description,
+		canonicalUrl: canonicalPageUrl(context, pageResult.routePaths.urlPath),
+		siteName: context.ssgOptions.siteName,
+		ogImage: pageOgImage,
+		head: context.ssgOptions.head,
+		bodyStart: context.ssgOptions.bodyStart,
+		bodyEnd: context.ssgOptions.bodyEnd
+	});
+	const pageData = createSsgPageData(pageResult);
 	return generateHtmlPage(pageData, context.navItems, context.siteName, context.base, pageOgImage, context.ssgOptions.theme, getPageLocale(pageData.path, context.options.i18n), context.options.i18n ? context.options.i18n.locales : void 0);
 }
-function createSsgPageData(pageResult) {
-	const { frontmatter } = pageResult;
-	const entryPage = frontmatter.layout === "entry" ? {
-		hero: frontmatter.hero,
+/** Maps an internal page result onto the theme renderer's page shape. */
+function toThemePageData(pageResult) {
+	return {
+		title: pageResult.title,
+		description: pageResult.description,
+		html: pageResult.transformedHtml,
+		toc: pageResult.toc,
+		lastUpdated: pageResult.lastUpdated,
+		path: pageResult.inputPath,
+		url: pageResult.routePaths.href,
+		frontmatter: pageResult.frontmatter,
+		layout: typeof pageResult.frontmatter.layout === "string" ? pageResult.frontmatter.layout : void 0
+	};
+}
+/**
+* Absolute URL of a page, or `undefined` when `ssg.siteUrl` is not set.
+*
+* Built the same way `get_og_image_url` builds the image URL next to it, so
+* the canonical link and `og:image` always agree about where the page lives.
+*/
+function canonicalPageUrl(context, urlPath) {
+	const siteUrl = context.ssgOptions.siteUrl?.replace(/\/+$/, "");
+	if (!siteUrl) return;
+	if (urlPath === "/" || urlPath === "") return `${siteUrl}${context.base}`;
+	return `${siteUrl}${context.base}${urlPath}/`;
+}
+function createSsgPageData(pageResult) {
+	const { frontmatter } = pageResult;
+	const entryPage = frontmatter.layout === "entry" ? {
+		hero: frontmatter.hero,
 		features: frontmatter.features
 	} : void 0;
 	return {
@@ -5753,359 +6447,6 @@ function createEmptyLintResult() {
 	};
 }
 //#endregion
-//#region src/page-context.ts
-var page_context_exports = /* @__PURE__ */ require_vitepress.__exportAll({
-	clearRenderContext: () => clearRenderContext,
-	generateFrontmatterTypes: () => generateFrontmatterTypes,
-	inferType: () => inferType,
-	setRenderContext: () => setRenderContext,
-	useIsActive: () => useIsActive,
-	useNav: () => useNav,
-	usePageProps: () => usePageProps,
-	useRenderContext: () => useRenderContext,
-	useSiteConfig: () => useSiteConfig
-});
-/**
-* Sets the current render context.
-* Called internally during page rendering.
-* @internal
-*/
-function setRenderContext(ctx) {
-	currentContext = ctx;
-}
-/**
-* Clears the current render context.
-* Called internally after page rendering.
-* @internal
-*/
-function clearRenderContext() {
-	currentContext = null;
-}
-/**
-* Gets the current page props.
-*
-* @returns The current page props
-* @throws Error if called outside of a render context
-*
-* @example
-* ```tsx
-* function PageTitle() {
-*   const page = usePageProps();
-*   return <h1>{page.title}</h1>;
-* }
-* ```
-*/
-function usePageProps() {
-	if (!currentContext) throw new Error("[ox-content] usePageProps() must be called during page rendering. Make sure you are using it inside a theme component.");
-	return currentContext.page;
-}
-/**
-* Gets the site configuration.
-*
-* @returns The site configuration
-* @throws Error if called outside of a render context
-*
-* @example
-* ```tsx
-* function SiteHeader() {
-*   const site = useSiteConfig();
-*   return <header>{site.name}</header>;
-* }
-* ```
-*/
-function useSiteConfig() {
-	if (!currentContext) throw new Error("[ox-content] useSiteConfig() must be called during page rendering. Make sure you are using it inside a theme component.");
-	return currentContext.site;
-}
-/**
-* Gets the full render context.
-*
-* @returns The complete render context
-* @throws Error if called outside of a render context
-*
-* @example
-* ```tsx
-* function Layout({ children }) {
-*   const ctx = useRenderContext();
-*   return (
-*     <html>
-*       <head><title>{ctx.page.title} - {ctx.site.name}</title></head>
-*       <body>{children}</body>
-*     </html>
-*   );
-* }
-* ```
-*/
-function useRenderContext() {
-	if (!currentContext) throw new Error("[ox-content] useRenderContext() must be called during page rendering. Make sure you are using it inside a theme component.");
-	return currentContext;
-}
-/**
-* Gets the navigation groups.
-*
-* @example
-* ```tsx
-* function Sidebar() {
-*   const nav = useNav();
-*   return (
-*     <nav>
-*       {each(nav, (group) => (
-*         <div>
-*           <h3>{group.title}</h3>
-*           <ul>
-*             {each(group.items, (item) => (
-*               <li><a href={item.href}>{item.title}</a></li>
-*             ))}
-*           </ul>
-*         </div>
-*       ))}
-*     </nav>
-*   );
-* }
-* ```
-*/
-function useNav() {
-	return useSiteConfig().nav;
-}
-/**
-* Checks if the given path is the current page.
-*
-* @example
-* ```tsx
-* function NavLink({ href, children }) {
-*   const isActive = useIsActive(href);
-*   return <a href={href} class={isActive ? 'active' : ''}>{children}</a>;
-* }
-* ```
-*/
-function useIsActive(path) {
-	const page = usePageProps();
-	return page.path === path || page.url === path;
-}
-/**
-* Infers TypeScript types from frontmatter values.
-*/
-function inferType(value) {
-	if (value === null) return "null";
-	if (value === void 0) return "undefined";
-	if (typeof value === "string") return "string";
-	if (typeof value === "number") return "number";
-	if (typeof value === "boolean") return "boolean";
-	if (Array.isArray(value)) {
-		if (value.length === 0) return "unknown[]";
-		const itemTypes = [...new Set(value.map(inferType))];
-		if (itemTypes.length === 1) return `${itemTypes[0]}[]`;
-		return `(${itemTypes.join(" | ")})[]`;
-	}
-	if (typeof value === "object") {
-		const entries = Object.entries(value);
-		if (entries.length === 0) return "Record<string, unknown>";
-		return `{ ${entries.map(([k, v]) => `${k}: ${inferType(v)}`).join("; ")} }`;
-	}
-	return "unknown";
-}
-/**
-* Generates TypeScript interface from frontmatter samples.
-*/
-function generateFrontmatterTypes(samples, interfaceName = "PageFrontmatter") {
-	const fields = /* @__PURE__ */ new Map();
-	for (const sample of samples) for (const [key, value] of Object.entries(sample)) {
-		const existing = fields.get(key) ?? {
-			types: /* @__PURE__ */ new Set(),
-			count: 0
-		};
-		existing.types.add(inferType(value));
-		existing.count++;
-		fields.set(key, existing);
-	}
-	const lines = [
-		"/**",
-		" * Auto-generated frontmatter type based on your pages.",
-		" * DO NOT EDIT - this file is generated by ox-content.",
-		" */",
-		"",
-		`export interface ${interfaceName} {`
-	];
-	for (const [name, { types, count }] of fields) {
-		const isOptional = count < samples.length;
-		const typeStr = [...types].join(" | ");
-		const optionalMark = isOptional ? "?" : "";
-		lines.push(`  ${name}${optionalMark}: ${typeStr};`);
-	}
-	lines.push("}");
-	lines.push("");
-	lines.push(`export type PageProps = import('@ox-content/vite-plugin').PageProps<${interfaceName}>;`);
-	lines.push("");
-	return lines.join("\n");
-}
-var currentContext;
-var init_page_context = require_vitepress.__esmMin((() => {
-	currentContext = null;
-}));
-//#endregion
-//#region src/theme-renderer.ts
-/**
-* Theme Renderer for Static HTML Generation
-*
-* Renders JSX theme components to static HTML strings.
-* No client-side JavaScript is included by default.
-*/
-init_page_context();
-/**
-* Renders a page using the theme component.
-*
-* @param page - Page data to render
-* @param options - Theme render options
-* @returns Rendered HTML string
-*/
-function renderPage(page, options) {
-	const { theme, siteName, base, nav, pages } = options;
-	setRenderContext({
-		page: {
-			title: page.title,
-			description: page.description,
-			html: page.html,
-			toc: page.toc,
-			lastUpdated: page.lastUpdated,
-			path: page.path,
-			url: page.url,
-			frontmatter: page.frontmatter,
-			layout: page.layout
-		},
-		site: {
-			name: siteName,
-			base,
-			nav,
-			pages: pages.map((p) => ({
-				title: p.title,
-				description: p.description,
-				html: p.html,
-				toc: p.toc,
-				lastUpdated: p.lastUpdated,
-				path: p.path,
-				url: p.url,
-				frontmatter: p.frontmatter,
-				layout: p.layout
-			}))
-		}
-	});
-	try {
-		const result = theme({ children: require_jsx_html.raw(page.html) });
-		const html = require_jsx_html.renderToString(result);
-		if (!html.trimStart().toLowerCase().startsWith("<!doctype")) return `<!DOCTYPE html>\n${html}`;
-		return html;
-	} finally {
-		clearRenderContext();
-	}
-}
-/**
-* Renders all pages and generates type definitions.
-*
-* @param pages - All pages to render
-* @param options - Theme render options
-* @returns Map of output paths to rendered HTML
-*/
-async function renderAllPages(pages, options) {
-	const results = /* @__PURE__ */ new Map();
-	for (const page of pages) {
-		const html = renderPage(page, {
-			...options,
-			pages
-		});
-		results.set(page.url, html);
-	}
-	if (options.typesOutDir) await generateTypes(pages, options.typesOutDir);
-	return results;
-}
-/**
-* Generates TypeScript type definitions from page frontmatter.
-*
-* @param pages - All pages
-* @param outDir - Output directory for types
-*/
-async function generateTypes(pages, outDir) {
-	const types = generateFrontmatterTypes(pages.map((p) => p.frontmatter));
-	const typesPath = (0, node_path.join)(outDir, "page-props.d.ts");
-	await (0, node_fs_promises.mkdir)((0, node_path.dirname)(typesPath), { recursive: true });
-	await (0, node_fs_promises.writeFile)(typesPath, types, "utf-8");
-}
-/**
-* Default theme component.
-* A minimal theme that renders page content with basic styling.
-*/
-function DefaultTheme({ children }) {
-	const { usePageProps, useSiteConfig } = (init_page_context(), require_vitepress.__toCommonJS(page_context_exports));
-	const page = usePageProps();
-	const site = useSiteConfig();
-	return { __html: `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>${escapeHtml(page.title)} - ${escapeHtml(site.name)}</title>
-  ${page.description ? `<meta name="description" content="${escapeHtml(page.description)}">` : ""}
-  <style>
-    :root {
-      --octc-color-primary: #4f6fae;
-      --octc-color-text: #131a30;
-      --octc-color-bg: #ffffff;
-      --octc-color-bg-alt: #f5f7fb;
-      --octc-color-text-muted: #4f607b;
-      --octc-color-border: #d2dbea;
-    }
-    body {
-      font-family: "IBM Plex Sans", "Avenir Next", "Segoe UI Variable", "Segoe UI", sans-serif;
-      line-height: 1.7;
-      color: var(--octc-color-text);
-      background: var(--octc-color-bg);
-      max-width: 800px;
-      margin: 0 auto;
-      padding: 2rem;
-    }
-    a { color: var(--octc-color-primary); }
-  </style>
-</head>
-<body>
-  <header>
-    <h1>${escapeHtml(site.name)}</h1>
-  </header>
-  <main>
-    ${children.__html}
-  </main>
-</body>
-</html>` };
-}
-function escapeHtml(str) {
-	return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
-}
-/**
-* Creates a theme with layout switching support.
-*
-* @example
-* ```tsx
-* import { createTheme } from '@ox-content/vite-plugin';
-* import { DefaultLayout } from './layouts/Default';
-* import { EntryLayout } from './layouts/Entry';
-*
-* export default createTheme({
-*   layouts: {
-*     default: DefaultLayout,
-*     entry: EntryLayout,
-*   },
-* });
-* ```
-*/
-function createTheme(config) {
-	const { layouts, defaultLayout = "default" } = config;
-	return function ThemeWithLayouts({ children }) {
-		const { usePageProps } = (init_page_context(), require_vitepress.__toCommonJS(page_context_exports));
-		const layoutName = usePageProps().layout ?? defaultLayout;
-		const Layout = layouts[layoutName] ?? layouts[defaultLayout];
-		if (!Layout) throw new Error(`[ox-content] Layout "${layoutName}" not found. Available layouts: ${Object.keys(layouts).join(", ")}`);
-		return Layout({ children });
-	};
-}
-//#endregion
 //#region src/index.ts
 /**
 * Vite Plugin for Ox Content