@farming-labs/theme 0.0.33-beta.1 → 0.0.34

package/dist/ai-search-dialog.d.mts

@@ -1,3 +1,6 @@
+import * as react from "react";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+
 //#region src/ai-search-dialog.d.ts
 type AIModelOption = {
   id: string;
@@ -24,7 +27,7 @@ declare function DocsSearchDialog({
   loadingComponentHtml?: string;
   models?: AIModelOption[];
   defaultModelId?: string;
-}): any;
+}): react.ReactPortal | null;
 type FloatingPosition = "bottom-right" | "bottom-left" | "bottom-center";
 type FloatingStyle = "panel" | "modal" | "popover" | "full-modal";
 declare function FloatingAIChat({
@@ -49,7 +52,7 @@ declare function FloatingAIChat({
   loadingComponentHtml?: string;
   models?: AIModelOption[];
   defaultModelId?: string;
-}): any;
+}): react_jsx_runtime0.JSX.Element | null;
 declare function AIModalDialog({
   open,
   onOpenChange,
@@ -70,6 +73,6 @@ declare function AIModalDialog({
   loadingComponentHtml?: string;
   models?: AIModelOption[];
   defaultModelId?: string;
-}): any;
+}): react.ReactPortal | null;
 //#endregion
 export { AIModalDialog, DocsSearchDialog, FloatingAIChat };

package/dist/ai-search-dialog.mjs

@@ -1,8 +1,8 @@
 "use client";
 
 import { useCallback, useEffect, useRef, useState } from "react";
-import { createPortal } from "react-dom";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { createPortal } from "react-dom";
 import { highlight } from "sugar-high";
 
 //#region src/ai-search-dialog.tsx

package/dist/client-location.mjs

@@ -0,0 +1,43 @@
+"use client";
+
+import { useSyncExternalStore } from "react";
+
+//#region src/client-location.ts
+function patchHistoryEvents() {
+	if (typeof window === "undefined" || window.__fdHistoryPatched) return;
+	const wrap = (method) => {
+		const original = window.history[method];
+		window.history[method] = function patchedHistoryMethod(...args) {
+			const result = original.apply(this, args);
+			window.dispatchEvent(new Event("fd-location-change"));
+			return result;
+		};
+	};
+	wrap("pushState");
+	wrap("replaceState");
+	window.__fdHistoryPatched = true;
+}
+function subscribe(onStoreChange) {
+	if (typeof window === "undefined") return () => {};
+	patchHistoryEvents();
+	const notify = () => onStoreChange();
+	window.addEventListener("popstate", notify);
+	window.addEventListener("hashchange", notify);
+	window.addEventListener("fd-location-change", notify);
+	return () => {
+		window.removeEventListener("popstate", notify);
+		window.removeEventListener("hashchange", notify);
+		window.removeEventListener("fd-location-change", notify);
+	};
+}
+function getSnapshot() {
+	if (typeof window === "undefined") return "";
+	return window.location.search;
+}
+function useWindowSearchParams() {
+	const search = useSyncExternalStore(subscribe, getSnapshot, () => "");
+	return new URLSearchParams(search);
+}
+
+//#endregion
+export { useWindowSearchParams };

package/dist/code-block-copy-wrapper.mjs

@@ -10,7 +10,12 @@ import { jsx } from "react/jsx-runtime";
 * The actual copy-to-clipboard is still done by the default component.
 */
 function createPreWithCopyCallback(DefaultPre, onCopyClick) {
-	if (!onCopyClick) return typeof DefaultPre === "string" ? DefaultPre : DefaultPre;
+	if (!onCopyClick) {
+		if (typeof DefaultPre !== "string") return DefaultPre;
+		return function NativePre(props) {
+			return /* @__PURE__ */ jsx("pre", { ...props });
+		};
+	}
 	function PreWithCopyCallback(props) {
 		const ref = React$1.useRef(null);
 		React$1.useEffect(() => {
@@ -25,8 +30,9 @@ function createPreWithCopyCallback(DefaultPre, onCopyClick) {
 				const content = code.textContent ?? "";
 				const url = typeof window !== "undefined" ? window.location.href : "";
 				const language = code.getAttribute("data-language") ?? figure.getAttribute("data-language") ?? void 0;
-				onCopyClick({
-					title: figure.querySelector("[data-title]")?.textContent?.trim() ?? figure.querySelector(".fd-codeblock-title-text")?.textContent?.trim() ?? void 0,
+				const title = figure.querySelector("[data-title]")?.textContent?.trim() ?? figure.querySelector(".fd-codeblock-title-text")?.textContent?.trim() ?? void 0;
+				onCopyClick?.({
+					title,
 					content,
 					url,
 					language

package/dist/docs-ai-features.mjs

@@ -1,9 +1,9 @@
 "use client";
 
+import { useWindowSearchParams } from "./client-location.mjs";
 import { resolveClientLocale, withLangInUrl } from "./i18n.mjs";
 import { AIModalDialog, DocsSearchDialog, FloatingAIChat } from "./ai-search-dialog.mjs";
 import { useEffect, useState } from "react";
-import { useSearchParams } from "next/navigation";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/docs-ai-features.tsx
@@ -22,7 +22,7 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 * never needs to be modified — AI features work purely from `docs.config.ts`.
 */
 function DocsAIFeatures({ mode, api = "/api/docs", locale, position = "bottom-right", floatingStyle = "panel", triggerComponentHtml, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId }) {
-	const localizedApi = withLangInUrl(api, resolveClientLocale(useSearchParams(), locale));
+	const localizedApi = withLangInUrl(api, resolveClientLocale(useWindowSearchParams(), locale));
 	if (mode === "search") return /* @__PURE__ */ jsx(SearchModeAI, {
 		api: localizedApi,
 		suggestedQuestions,

package/dist/docs-api.mjs

@@ -51,7 +51,7 @@ function readI18nConfig(root) {
 			if (!content.includes("i18n")) continue;
 			const localesMatch = content.match(/i18n\s*:\s*\{[\s\S]*?locales\s*:\s*\[([^\]]+)\]/);
 			if (!localesMatch) continue;
-			const locales = localesMatch[1].split(",").map((l) => l.trim().replace(/^['\"`]|['\"`]$/g, "")).filter(Boolean);
+			const locales = localesMatch[1].split(",").map((l) => l.trim().replace(/^['"`]|['"`]$/g, "")).filter(Boolean);
 			if (locales.length === 0) continue;
 			return {
 				locales,

package/dist/docs-command-search.d.mts

@@ -1,3 +1,5 @@
+import * as React$1 from "react";
+
 //#region src/docs-command-search.d.ts
 /**
  * Built-in docs search command palette.
@@ -11,6 +13,6 @@ declare function DocsCommandSearch({
 }: {
   api?: string;
   locale?: string;
-}): any;
+}): React$1.ReactPortal | null;
 //#endregion
 export { DocsCommandSearch };

package/dist/docs-command-search.mjs

@@ -1,10 +1,10 @@
 "use client";
 
+import { useWindowSearchParams } from "./client-location.mjs";
 import { resolveClientLocale, withLangInUrl } from "./i18n.mjs";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { createPortal } from "react-dom";
-import { useSearchParams } from "next/navigation";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { createPortal } from "react-dom";
 
 //#region src/docs-command-search.tsx
 function cn(...classes) {
@@ -308,7 +308,7 @@ function DocsCommandSearch({ api = "/api/docs", locale }) {
 	const [activeIndex, setActiveIndex] = useState(0);
 	const [recents, setRecents] = useState([]);
 	const [mounted, setMounted] = useState(false);
-	const activeLocale = resolveClientLocale(useSearchParams(), locale);
+	const activeLocale = resolveClientLocale(useWindowSearchParams(), locale);
 	const searchApi = useMemo(() => withLangInUrl(api, activeLocale), [activeLocale, api]);
 	const inputRef = useRef(null);
 	const listRef = useRef(null);

package/dist/docs-layout.mjs

@@ -52,17 +52,25 @@ function resolveDocsI18nConfig(i18n) {
 }
 function resolveDocsLocaleContext(config, locale) {
 	const entryBase = config.entry ?? "docs";
-	const appDir = getNextAppDir(process.cwd());
 	const i18n = resolveDocsI18nConfig(getDocsI18n(config));
+	const contentDir = config.contentDir;
+	function resolveContentDir(localeValue) {
+		if (!contentDir) {
+			const appDir = getNextAppDir(process.cwd());
+			return path.join(process.cwd(), appDir, entryBase, ...localeValue ? [localeValue] : []);
+		}
+		const base = path.isAbsolute(contentDir) ? contentDir : path.join(process.cwd(), contentDir);
+		return localeValue ? path.join(base, localeValue) : base;
+	}
 	if (!i18n) return {
 		entryPath: entryBase,
-		docsDir: path.join(process.cwd(), appDir, entryBase)
+		docsDir: resolveContentDir()
 	};
 	const resolvedLocale = locale && i18n.locales.includes(locale) ? locale : i18n.defaultLocale;
 	return {
 		entryPath: entryBase,
 		locale: resolvedLocale,
-		docsDir: path.join(process.cwd(), appDir, entryBase, resolvedLocale)
+		docsDir: resolveContentDir(resolvedLocale)
 	};
 }
 function buildTree(config, ctx, flat = false) {
@@ -467,6 +475,7 @@ function createDocsLayout(config, options) {
 	const githubUrl = typeof githubRaw === "string" ? githubRaw.replace(/\/$/, "") : githubRaw?.url.replace(/\/$/, "");
 	const githubBranch = typeof githubRaw === "object" ? githubRaw.branch ?? "main" : "main";
 	const githubDirectory = typeof githubRaw === "object" ? githubRaw.directory?.replace(/^\/|\/$/g, "") : void 0;
+	const contentDir = config.contentDir;
 	const staticExport = !!config.staticExport;
 	const aiConfig = config.ai;
 	const aiEnabled = !staticExport && !!aiConfig?.enabled;
@@ -572,6 +581,7 @@ function createDocsLayout(config, options) {
 							pageActionsPosition,
 							pageActionsAlignment,
 							githubUrl,
+							contentDir,
 							githubBranch,
 							githubDirectory,
 							lastModifiedMap,

package/dist/docs-page-client.d.mts

@@ -25,12 +25,18 @@ interface DocsPageClientProps {
   pageActionsAlignment?: "left" | "right";
   /** GitHub repository URL (e.g. "https://github.com/user/repo") */
   githubUrl?: string;
+  /** Path to docs content relative to the repo root (used for Edit on GitHub outside Next.js app/docs) */
+  contentDir?: string;
   /** GitHub branch name @default "main" */
   githubBranch?: string;
   /** Subdirectory in the repo where the docs site lives (for monorepos) */
   githubDirectory?: string;
+  /** Direct GitHub URL override for the current page. */
+  editOnGithubUrl?: string;
   /** Map of pathname → formatted last-modified date string */
   lastModifiedMap?: Record<string, string>;
+  /** Direct last-modified value override for the current page. */
+  lastModified?: string;
   /** Whether to show "Last updated" at all */
   lastUpdatedEnabled?: boolean;
   /** Where to show the "Last updated" date: "footer" (next to Edit on GitHub) or "below-title" */
@@ -55,9 +61,12 @@ declare function DocsPageClient({
   pageActionsPosition,
   pageActionsAlignment,
   githubUrl,
+  contentDir,
   githubBranch,
   githubDirectory,
+  editOnGithubUrl,
   lastModifiedMap,
+  lastModified: lastModifiedProp,
   lastUpdatedEnabled,
   lastUpdatedPosition,
   llmsTxtEnabled,

package/dist/docs-page-client.mjs

@@ -1,11 +1,11 @@
 "use client";
 
 import { PageActions } from "./page-actions.mjs";
+import { useWindowSearchParams } from "./client-location.mjs";
 import { resolveClientLocale, withLangInUrl } from "./i18n.mjs";
-import { useEffect, useState } from "react";
+import { Children, cloneElement, isValidElement, useEffect, useState } from "react";
 import { DocsBody, DocsPage, EditOnGitHub } from "fumadocs-ui/layouts/docs/page";
-import { createPortal } from "react-dom";
-import { usePathname, useRouter, useSearchParams } from "next/navigation";
+import { usePathname, useRouter } from "fumadocs-core/framework";
 import { jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/docs-page-client.tsx
@@ -62,13 +62,14 @@ function PathBreadcrumb({ pathname, entry, locale }) {
 *   No directory:  https://github.com/user/repo/edit/main/app/docs/cli/page.mdx
 *   With directory: https://github.com/farming-labs/docs/edit/main/website/app/docs/cli/page.mdx
 */
-function buildGithubFileUrl(githubUrl, branch, pathname, entry, locale, directory) {
+function buildGithubFileUrl(githubUrl, branch, pathname, entry, locale, directory, contentDir) {
 	const normalizedEntry = entry.replace(/^\/+|\/+$/g, "") || "docs";
+	const normalizedContentDir = contentDir?.replace(/^\/+|\/+$/g, "");
 	const entryParts = normalizedEntry.split("/").filter(Boolean);
 	const pathnameParts = pathname.replace(/^\/+|\/+$/g, "").split("/").filter(Boolean);
 	const slugParts = pathnameParts.slice(0, entryParts.length).join("/") === entryParts.join("/") ? pathnameParts.slice(entryParts.length) : pathnameParts;
 	const dirPrefix = directory ? `${directory}/` : "";
-	const basePath = `app/${normalizedEntry}`;
+	const basePath = normalizedContentDir || `app/${normalizedEntry}`;
 	const relativePath = [locale, slugParts.join("/")].filter(Boolean).join("/");
 	return `${githubUrl}/edit/${branch}/${`${dirPrefix}${basePath}${relativePath ? `/${relativePath}` : ""}/page.mdx`}`;
 }
@@ -86,13 +87,44 @@ function localizeInternalLinks(root, locale) {
 		} catch {}
 	}
 }
-function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled = true, entry = "docs", locale, copyMarkdown = false, openDocs = false, openDocsProviders, pageActionsPosition = "below-title", pageActionsAlignment = "left", githubUrl, githubBranch = "main", githubDirectory, lastModifiedMap, lastUpdatedEnabled = true, lastUpdatedPosition = "footer", llmsTxtEnabled = false, descriptionMap, description, children }) {
+function injectTitleDecorations(node, { description, belowTitle }) {
+	if (!description && !belowTitle) return node;
+	let inserted = false;
+	const extras = [description, belowTitle].filter(Boolean);
+	if (extras.length === 0) return node;
+	function visit(current) {
+		if (current == null || typeof current === "boolean") return current;
+		if (inserted) return current;
+		if (Array.isArray(current)) return current.flatMap((child) => {
+			const next = visit(child);
+			return Array.isArray(next) ? next : [next];
+		});
+		if (!isValidElement(current)) return current;
+		if (typeof current.type === "string" && current.type === "h1") {
+			inserted = true;
+			return [current, ...extras];
+		}
+		const childProps = current.props ?? null;
+		if (childProps?.children === void 0) return current;
+		const nextChildren = Children.toArray(childProps.children).flatMap((child) => {
+			const next = visit(child);
+			return Array.isArray(next) ? next : [next];
+		});
+		if (!inserted) return current;
+		return cloneElement(current, void 0, nextChildren);
+	}
+	if (Array.isArray(node)) return node.flatMap((child) => {
+		const next = visit(child);
+		return Array.isArray(next) ? next : [next];
+	});
+	return visit(node);
+}
+function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled = true, entry = "docs", locale, copyMarkdown = false, openDocs = false, openDocsProviders, pageActionsPosition = "below-title", pageActionsAlignment = "left", githubUrl, contentDir, githubBranch = "main", githubDirectory, editOnGithubUrl, lastModifiedMap, lastModified: lastModifiedProp, lastUpdatedEnabled = true, lastUpdatedPosition = "footer", llmsTxtEnabled = false, descriptionMap, description, children }) {
 	const fdTocStyle = tocStyle === "directional" ? "clerk" : void 0;
 	const [toc, setToc] = useState([]);
 	const pathname = usePathname();
-	const activeLocale = resolveClientLocale(useSearchParams(), locale);
+	const activeLocale = resolveClientLocale(useWindowSearchParams(), locale);
 	const llmsLangParam = activeLocale ? `&lang=${encodeURIComponent(activeLocale)}` : "";
-	const [actionsPortalTarget, setActionsPortalTarget] = useState(null);
 	const pageDescription = description ?? descriptionMap?.[pathname.replace(/\/$/, "") || "/"];
 	useEffect(() => {
 		if (!tocEnabled) return;
@@ -109,26 +141,7 @@ function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled =
 		return () => cancelAnimationFrame(timer);
 	}, [tocEnabled, pathname]);
 	useEffect(() => {
-		if (!pageDescription) return;
-		const timer = requestAnimationFrame(() => {
-			const container = document.getElementById("nd-page");
-			if (!container) return;
-			const existingDesc = container.querySelector(".fd-page-description");
-			if (existingDesc) existingDesc.remove();
-			const h1 = container.querySelector("h1");
-			if (!h1) return;
-			const descEl = document.createElement("p");
-			descEl.className = "fd-page-description";
-			descEl.textContent = pageDescription;
-			h1.insertAdjacentElement("afterend", descEl);
-		});
-		return () => {
-			cancelAnimationFrame(timer);
-			const desc = document.querySelector("#nd-page .fd-page-description");
-			if (desc) desc.remove();
-		};
-	}, [pageDescription, pathname]);
-	useEffect(() => {
+		if (!activeLocale) return;
 		const timer = requestAnimationFrame(() => {
 			const container = document.getElementById("nd-page");
 			if (!container) return;
@@ -141,59 +154,40 @@ function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled =
 		pathname
 	]);
 	const showActions = copyMarkdown || openDocs;
-	const githubFileUrl = githubUrl ? buildGithubFileUrl(githubUrl, githubBranch, pathname, entry, activeLocale, githubDirectory) : void 0;
+	const showActionsBelowTitle = showActions && pageActionsPosition === "below-title";
+	const showActionsAboveTitle = showActions && pageActionsPosition === "above-title";
+	const githubFileUrl = editOnGithubUrl ?? (githubUrl ? buildGithubFileUrl(githubUrl, githubBranch, pathname, entry, activeLocale, githubDirectory, contentDir) : void 0);
 	const normalizedPath = pathname.replace(/\/$/, "") || "/";
-	const lastModified = lastUpdatedEnabled ? lastModifiedMap?.[normalizedPath] : void 0;
+	const lastModified = lastUpdatedEnabled ? lastModifiedProp ?? lastModifiedMap?.[normalizedPath] : void 0;
 	const showLastUpdatedBelowTitle = !!lastModified && lastUpdatedPosition === "below-title";
 	const showLastUpdatedInFooter = !!lastModified && lastUpdatedPosition === "footer";
 	const showFooter = !!githubFileUrl || showLastUpdatedInFooter || llmsTxtEnabled;
-	const needsBelowTitleBlock = showLastUpdatedBelowTitle || showActions;
-	useEffect(() => {
-		if (!needsBelowTitleBlock) return;
-		const timer = requestAnimationFrame(() => {
-			const container = document.getElementById("nd-page");
-			if (!container) return;
-			container.querySelectorAll(".fd-below-title-block").forEach((el) => el.remove());
-			const h1 = container.querySelector("h1");
-			if (!h1) return;
-			let insertAfter = h1;
-			const desc = container.querySelector(".fd-page-description");
-			if (desc) insertAfter = desc;
-			const wrapper = document.createElement("div");
-			wrapper.className = "fd-below-title-block not-prose";
-			if (showLastUpdatedBelowTitle) {
-				const lastUpdatedEl = document.createElement("p");
-				lastUpdatedEl.className = "fd-last-updated-inline";
-				lastUpdatedEl.textContent = `Last updated ${lastModified}`;
-				wrapper.appendChild(lastUpdatedEl);
-			}
-			if (showLastUpdatedBelowTitle || showActions) {
-				const hr = document.createElement("hr");
-				hr.className = "fd-title-separator";
-				wrapper.appendChild(hr);
-			}
-			if (showActions) {
-				const portalEl = document.createElement("div");
-				portalEl.className = "fd-actions-portal";
-				portalEl.setAttribute("data-actions-alignment", pageActionsAlignment);
-				wrapper.appendChild(portalEl);
-				setActionsPortalTarget(portalEl);
-			}
-			insertAfter.insertAdjacentElement("afterend", wrapper);
-		});
-		return () => {
-			cancelAnimationFrame(timer);
-			setActionsPortalTarget(null);
-			document.querySelectorAll("#nd-page .fd-below-title-block").forEach((el) => el.remove());
-		};
-	}, [
-		lastModified,
-		needsBelowTitleBlock,
-		showLastUpdatedBelowTitle,
-		showActions,
-		pageActionsAlignment,
-		pathname
-	]);
+	const decoratedChildren = injectTitleDecorations(children, {
+		description: pageDescription ? /* @__PURE__ */ jsx("p", {
+			className: "fd-page-description",
+			children: pageDescription
+		}) : void 0,
+		belowTitle: showLastUpdatedBelowTitle || showActionsBelowTitle ? /* @__PURE__ */ jsxs("div", {
+			className: "fd-below-title-block not-prose",
+			children: [
+				showLastUpdatedBelowTitle && /* @__PURE__ */ jsxs("p", {
+					className: "fd-last-updated-inline",
+					children: ["Last updated ", lastModified]
+				}),
+				/* @__PURE__ */ jsx("hr", { className: "fd-title-separator" }),
+				showActionsBelowTitle && /* @__PURE__ */ jsx("div", {
+					className: "fd-actions-portal",
+					"data-actions-alignment": pageActionsAlignment,
+					children: /* @__PURE__ */ jsx(PageActions, {
+						copyMarkdown,
+						openDocs,
+						providers: openDocsProviders,
+						githubFileUrl
+					})
+				})
+			]
+		}) : void 0
+	});
 	return /* @__PURE__ */ jsxs(DocsPage, {
 		toc,
 		tableOfContent: {
@@ -211,12 +205,15 @@ function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled =
 				entry,
 				locale: activeLocale
 			}),
-			showActions && actionsPortalTarget && createPortal(/* @__PURE__ */ jsx(PageActions, {
-				copyMarkdown,
-				openDocs,
-				providers: openDocsProviders,
-				githubFileUrl
-			}), actionsPortalTarget),
+			showActionsAboveTitle && /* @__PURE__ */ jsx("div", {
+				className: "fd-below-title-block not-prose",
+				children: /* @__PURE__ */ jsx(PageActions, {
+					copyMarkdown,
+					openDocs,
+					providers: openDocsProviders,
+					githubFileUrl
+				})
+			}),
 			/* @__PURE__ */ jsxs(DocsBody, {
 				style: {
 					display: "flex",
@@ -224,7 +221,7 @@ function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled =
 				},
 				children: [/* @__PURE__ */ jsx("div", {
 					style: { flex: 1 },
-					children
+					children: decoratedChildren
 				}), showFooter && /* @__PURE__ */ jsxs("div", {
 					className: "not-prose fd-page-footer",
 					children: [

package/dist/locale-theme-control.mjs

@@ -1,8 +1,9 @@
 "use client";
 
+import { useWindowSearchParams } from "./client-location.mjs";
 import { resolveClientLocale, withLangInUrl } from "./i18n.mjs";
 import { useEffect, useMemo, useState } from "react";
-import { usePathname, useRouter, useSearchParams } from "next/navigation";
+import { usePathname, useRouter } from "fumadocs-core/framework";
 import { jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/locale-theme-control.tsx
@@ -102,7 +103,7 @@ function ChevronDownIcon() {
 function LocaleThemeControl({ locales, defaultLocale, locale, showThemeToggle = true, themeMode = "light-dark" }) {
 	const router = useRouter();
 	const pathname = usePathname();
-	const searchParams = useSearchParams();
+	const searchParams = useWindowSearchParams();
 	const [mounted, setMounted] = useState(false);
 	const [themeValue, setThemeValue] = useState("system");
 	const [resolvedTheme, setResolvedTheme] = useState("light");

package/dist/mdx-img.d.mts

@@ -1,6 +1,6 @@
 import { ComponentProps } from "react";
+import { Image } from "fumadocs-core/framework";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
-import Image from "next/image";
 
 //#region src/mdx-img.d.ts
 type ImgProps = ComponentProps<typeof Image>;

package/dist/mdx-img.mjs

@@ -1,14 +1,13 @@
 "use client";
 
+import { Image } from "fumadocs-core/framework";
 import { jsx } from "react/jsx-runtime";
-import Image from "next/image";
 
 //#region src/mdx-img.tsx
 /**
 * MDX image component that works with ![alt](url) when width/height are not provided.
-* Fumadocs-ui's default img uses Next.js Image which requires width and height;
-* markdown image syntax cannot provide these. This override uses unoptimized Image
-* with default dimensions when missing, so external (e.g. GitHub) images work.
+* Fumadocs-ui's framework-aware image component keeps Next.js optimization when available
+* and falls back to a plain <img> in other runtimes.
 */
 const DEFAULT_WIDTH = 800;
 const DEFAULT_HEIGHT = 600;
@@ -19,7 +18,6 @@ function MDXImg(props) {
 		alt,
 		width: width != null ? Number(width) : DEFAULT_WIDTH,
 		height: height != null ? Number(height) : DEFAULT_HEIGHT,
-		unoptimized: !(width != null && height != null),
 		style: {
 			maxWidth: "100%",
 			height: "auto",

package/dist/page-actions.mjs

@@ -1,7 +1,7 @@
 "use client";
 
 import { useCallback, useEffect, useRef, useState } from "react";
-import { usePathname } from "next/navigation";
+import { usePathname } from "fumadocs-core/framework";
 import { jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/page-actions.tsx

package/dist/provider-tanstack.d.mts

@@ -0,0 +1,14 @@
+import { ComponentPropsWithoutRef } from "react";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+import { RootProvider as RootProvider$1 } from "fumadocs-ui/provider/tanstack";
+
+//#region src/provider-tanstack.d.ts
+type FumadocsProviderProps = ComponentPropsWithoutRef<typeof RootProvider$1>;
+interface DocsTanstackRootProviderProps extends FumadocsProviderProps {}
+declare function RootProvider({
+  children,
+  search,
+  ...props
+}: DocsTanstackRootProviderProps): react_jsx_runtime0.JSX.Element;
+//#endregion
+export { DocsTanstackRootProviderProps, RootProvider };

package/dist/provider-tanstack.mjs

@@ -0,0 +1,22 @@
+"use client";
+
+import { jsx } from "react/jsx-runtime";
+import { RootProvider as RootProvider$1 } from "fumadocs-ui/provider/tanstack";
+
+//#region src/provider-tanstack.tsx
+function RootProvider({ children, search, ...props }) {
+	return /* @__PURE__ */ jsx(RootProvider$1, {
+		search: {
+			...search,
+			options: {
+				api: "/api/docs",
+				...search?.options
+			}
+		},
+		...props,
+		children
+	});
+}
+
+//#endregion
+export { RootProvider };

package/dist/tanstack-layout.d.mts

@@ -0,0 +1,45 @@
+import { ReactNode } from "react";
+import { DocsConfig } from "@farming-labs/docs";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/tanstack-layout.d.ts
+interface PageNode {
+  type: "page";
+  name: string;
+  url: string;
+  icon?: ReactNode;
+}
+interface FolderNode {
+  type: "folder";
+  name: string;
+  icon?: ReactNode;
+  index?: PageNode;
+  children: (PageNode | FolderNode)[];
+  collapsible?: boolean;
+  defaultOpen?: boolean;
+}
+type TreeNode = PageNode | FolderNode;
+interface TreeRoot {
+  name: string;
+  children: TreeNode[];
+}
+interface TanstackDocsLayoutProps {
+  config: DocsConfig;
+  tree: TreeRoot;
+  locale?: string;
+  description?: string;
+  lastModified?: string;
+  editOnGithubUrl?: string;
+  children: ReactNode;
+}
+declare function TanstackDocsLayout({
+  config,
+  tree,
+  locale,
+  description,
+  lastModified,
+  editOnGithubUrl,
+  children
+}: TanstackDocsLayoutProps): react_jsx_runtime0.JSX.Element;
+//#endregion
+export { TanstackDocsLayout, TanstackDocsLayoutProps };

package/dist/tanstack-layout.mjs

@@ -0,0 +1,328 @@
+import { withLangInUrl } from "./i18n.mjs";
+import { DocsPageClient } from "./docs-page-client.mjs";
+import { DocsAIFeatures } from "./docs-ai-features.mjs";
+import { DocsCommandSearch } from "./docs-command-search.mjs";
+import { SidebarSearchWithAI } from "./sidebar-search-ai.mjs";
+import { LocaleThemeControl } from "./locale-theme-control.mjs";
+import { DocsLayout } from "fumadocs-ui/layouts/docs";
+import { Suspense } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/tanstack-layout.tsx
+function resolveTreeIcon(icon, registry) {
+	if (!icon) return void 0;
+	if (typeof icon !== "string") return icon;
+	const fromRegistry = registry?.[icon];
+	if (fromRegistry) return fromRegistry;
+}
+function resolveTreeIcons(tree, registry) {
+	function mapNode(node) {
+		if (node.type === "page") return {
+			...node,
+			icon: resolveTreeIcon(node.icon, registry)
+		};
+		return {
+			...node,
+			icon: resolveTreeIcon(node.icon, registry),
+			index: node.index ? {
+				...node.index,
+				icon: resolveTreeIcon(node.index.icon, registry)
+			} : void 0,
+			children: node.children.map(mapNode)
+		};
+	}
+	return {
+		...tree,
+		children: tree.children.map(mapNode)
+	};
+}
+function localizeTreeUrls(tree, locale) {
+	function mapNode(node) {
+		if (node.type === "page") return {
+			...node,
+			url: withLangInUrl(node.url, locale)
+		};
+		return {
+			...node,
+			index: node.index ? {
+				...node.index,
+				url: withLangInUrl(node.index.url, locale)
+			} : void 0,
+			children: node.children.map(mapNode)
+		};
+	}
+	return {
+		...tree,
+		children: tree.children.map(mapNode)
+	};
+}
+function resolveThemeSwitch(toggle) {
+	if (toggle === void 0 || toggle === true) return { enabled: true };
+	if (toggle === false) return { enabled: false };
+	return {
+		enabled: toggle.enabled !== false,
+		mode: toggle.mode
+	};
+}
+function resolveSidebar(sidebar) {
+	if (sidebar === void 0 || sidebar === true) return {};
+	if (sidebar === false) return { enabled: false };
+	return {
+		enabled: sidebar.enabled !== false,
+		componentFn: typeof sidebar.component === "function" ? sidebar.component : void 0,
+		footer: sidebar.footer,
+		banner: sidebar.banner,
+		collapsible: sidebar.collapsible,
+		flat: sidebar.flat
+	};
+}
+const COLOR_MAP = {
+	primary: "--color-fd-primary",
+	primaryForeground: "--color-fd-primary-foreground",
+	background: "--color-fd-background",
+	foreground: "--color-fd-foreground",
+	muted: "--color-fd-muted",
+	mutedForeground: "--color-fd-muted-foreground",
+	border: "--color-fd-border",
+	card: "--color-fd-card",
+	cardForeground: "--color-fd-card-foreground",
+	accent: "--color-fd-accent",
+	accentForeground: "--color-fd-accent-foreground",
+	popover: "--color-fd-popover",
+	popoverForeground: "--color-fd-popover-foreground",
+	secondary: "--color-fd-secondary",
+	secondaryForeground: "--color-fd-secondary-foreground",
+	ring: "--color-fd-ring"
+};
+function buildColorsCSS(colors) {
+	if (!colors) return "";
+	const vars = [];
+	for (const [key, value] of Object.entries(colors)) {
+		if (!value || !COLOR_MAP[key]) continue;
+		vars.push(`${COLOR_MAP[key]}: ${value};`);
+	}
+	if (vars.length === 0) return "";
+	const block = vars.join("\n  ");
+	return `:root {\n  ${block}\n}\n.dark {\n  ${block}\n}`;
+}
+function ColorStyle({ colors }) {
+	const css = buildColorsCSS(colors);
+	if (!css) return null;
+	return /* @__PURE__ */ jsx("style", { dangerouslySetInnerHTML: { __html: css } });
+}
+function buildFontStyleVars(prefix, style) {
+	if (!style) return "";
+	const parts = [];
+	if (style.size) parts.push(`${prefix}-size: ${style.size};`);
+	if (style.weight != null) parts.push(`${prefix}-weight: ${style.weight};`);
+	if (style.lineHeight) parts.push(`${prefix}-line-height: ${style.lineHeight};`);
+	if (style.letterSpacing) parts.push(`${prefix}-letter-spacing: ${style.letterSpacing};`);
+	return parts.join("\n  ");
+}
+function buildTypographyCSS(typo) {
+	if (!typo?.font) return "";
+	const vars = [];
+	const fontStyle = typo.font.style;
+	if (fontStyle?.sans) vars.push(`--fd-font-sans: ${fontStyle.sans};`);
+	if (fontStyle?.mono) vars.push(`--fd-font-mono: ${fontStyle.mono};`);
+	for (const element of [
+		"h1",
+		"h2",
+		"h3",
+		"h4",
+		"body",
+		"small"
+	]) {
+		const style = typo.font[element];
+		if (style) {
+			const cssVars = buildFontStyleVars(`--fd-${element}`, style);
+			if (cssVars) vars.push(cssVars);
+		}
+	}
+	if (vars.length === 0) return "";
+	return `:root {\n  ${vars.join("\n  ")}\n}`;
+}
+function TypographyStyle({ typography }) {
+	const css = buildTypographyCSS(typography);
+	if (!css) return null;
+	return /* @__PURE__ */ jsx("style", { dangerouslySetInnerHTML: { __html: css } });
+}
+function LayoutStyle({ layout }) {
+	if (!layout) return null;
+	const rootVars = [];
+	const desktopRootVars = [];
+	const desktopGridVars = [];
+	if (layout.sidebarWidth) {
+		const value = `--fd-sidebar-width: ${layout.sidebarWidth}px`;
+		desktopRootVars.push(`${value};`);
+		desktopGridVars.push(`${value} !important;`);
+	}
+	if (layout.contentWidth) rootVars.push(`--fd-content-width: ${layout.contentWidth}px;`);
+	if (layout.tocWidth) {
+		const value = `--fd-toc-width: ${layout.tocWidth}px`;
+		desktopRootVars.push(`${value};`);
+		desktopGridVars.push(`${value} !important;`);
+	}
+	if (rootVars.length === 0 && desktopRootVars.length === 0) return null;
+	const parts = [];
+	if (rootVars.length > 0) parts.push(`:root {\n  ${rootVars.join("\n  ")}\n}`);
+	if (desktopRootVars.length > 0) {
+		const inner = [`:root {\n    ${desktopRootVars.join("\n    ")}\n  }`];
+		if (desktopGridVars.length > 0) inner.push(`[style*="fd-sidebar-col"] {\n    ${desktopGridVars.join("\n    ")}\n  }`);
+		parts.push(`@media (min-width: 1024px) {\n  ${inner.join("\n  ")}\n}`);
+	}
+	return /* @__PURE__ */ jsx("style", { dangerouslySetInnerHTML: { __html: parts.join("\n") } });
+}
+function resolveBool(value) {
+	if (value === void 0) return false;
+	if (typeof value === "boolean") return value;
+	return value.enabled !== false;
+}
+function ForcedThemeScript({ theme }) {
+	return /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: `document.documentElement.classList.remove('light','dark');document.documentElement.classList.add('${theme === "light" || theme === "dark" ? theme : "light"}');` } });
+}
+function TanstackDocsLayout({ config, tree, locale, description, lastModified, editOnGithubUrl, children }) {
+	const tocConfig = config.theme?.ui?.layout?.toc;
+	const tocEnabled = tocConfig?.enabled !== false;
+	const tocStyle = tocConfig?.style;
+	const docsApiUrl = withLangInUrl("/api/docs", locale);
+	const navTitle = config.nav?.title ?? "Docs";
+	const navUrl = withLangInUrl(config.nav?.url ?? `/${config.entry ?? "docs"}`, locale);
+	const themeSwitch = resolveThemeSwitch(config.themeToggle);
+	const toggleConfig = typeof config.themeToggle === "object" ? config.themeToggle : void 0;
+	const forcedTheme = themeSwitch.enabled === false && toggleConfig?.default && toggleConfig.default !== "system" ? toggleConfig.default : void 0;
+	const resolvedSidebar = resolveSidebar(config.sidebar);
+	const sidebarFlat = resolvedSidebar.flat;
+	const sidebarComponentFn = resolvedSidebar.componentFn;
+	const { flat: _sidebarFlat, componentFn: _componentFn, ...sidebarProps } = resolvedSidebar;
+	const breadcrumbConfig = config.breadcrumb;
+	const breadcrumbEnabled = breadcrumbConfig === void 0 || breadcrumbConfig === true || typeof breadcrumbConfig === "object" && breadcrumbConfig.enabled !== false;
+	const colors = config.theme?._userColorOverrides;
+	const typography = config.theme?.ui?.typography;
+	const layoutDimensions = config.theme?.ui?.layout;
+	const pageActions = config.pageActions;
+	const copyMarkdownEnabled = resolveBool(pageActions?.copyMarkdown);
+	const openDocsEnabled = resolveBool(pageActions?.openDocs);
+	const pageActionsPosition = pageActions?.position ?? "below-title";
+	const pageActionsAlignment = pageActions?.alignment ?? "left";
+	const lastUpdatedRaw = config.lastUpdated;
+	const lastUpdatedEnabled = lastUpdatedRaw !== false && (typeof lastUpdatedRaw !== "object" || lastUpdatedRaw.enabled !== false);
+	const lastUpdatedPosition = typeof lastUpdatedRaw === "object" ? lastUpdatedRaw.position ?? "footer" : "footer";
+	const llmsTxtEnabled = resolveBool(config.llmsTxt);
+	const staticExport = !!config.staticExport;
+	const openDocsProviders = (typeof pageActions?.openDocs === "object" && pageActions.openDocs.providers ? pageActions.openDocs.providers : void 0)?.map((provider) => ({
+		name: provider.name,
+		urlTemplate: provider.urlTemplate
+	}));
+	const aiConfig = config.ai;
+	const aiEnabled = !staticExport && !!aiConfig?.enabled;
+	const aiMode = aiConfig?.mode ?? "search";
+	const aiPosition = aiConfig?.position ?? "bottom-right";
+	const aiFloatingStyle = aiConfig?.floatingStyle ?? "panel";
+	const aiSuggestedQuestions = aiConfig?.suggestedQuestions;
+	const aiLabel = aiConfig?.aiLabel;
+	const aiLoaderVariant = aiConfig?.loader;
+	const rawModelConfig = aiConfig?.model;
+	let aiModels = aiConfig?.models;
+	let aiDefaultModelId = aiConfig?.defaultModel ?? (typeof aiConfig?.model === "string" ? aiConfig.model : void 0);
+	if (rawModelConfig && typeof rawModelConfig === "object") {
+		aiModels = rawModelConfig.models ?? aiModels;
+		aiDefaultModelId = rawModelConfig.defaultModel ?? rawModelConfig.models?.[0]?.id ?? aiDefaultModelId;
+	}
+	const i18n = config.i18n;
+	const resolvedTree = resolveTreeIcons(locale ? localizeTreeUrls(tree, locale) : tree, config.icons);
+	const finalSidebarProps = { ...sidebarProps };
+	const sidebarFooter = sidebarProps.footer;
+	if (locale && i18n?.locales && i18n.defaultLocale) finalSidebarProps.footer = /* @__PURE__ */ jsxs("div", {
+		style: {
+			display: "flex",
+			flexDirection: "column",
+			gap: 12
+		},
+		children: [sidebarFooter, /* @__PURE__ */ jsx(Suspense, {
+			fallback: null,
+			children: /* @__PURE__ */ jsx(LocaleThemeControl, {
+				locales: i18n.locales,
+				defaultLocale: i18n.defaultLocale,
+				locale,
+				showThemeToggle: themeSwitch.enabled !== false,
+				themeMode: themeSwitch.mode
+			})
+		})]
+	});
+	if (sidebarComponentFn) finalSidebarProps.component = sidebarComponentFn({
+		tree: resolvedTree,
+		collapsible: sidebarProps.collapsible !== false,
+		flat: !!sidebarFlat
+	});
+	return /* @__PURE__ */ jsx("div", {
+		id: "nd-docs-layout",
+		style: { display: "contents" },
+		children: /* @__PURE__ */ jsxs(DocsLayout, {
+			tree: resolvedTree,
+			nav: {
+				title: navTitle,
+				url: navUrl
+			},
+			themeSwitch: locale && i18n?.locales ? {
+				...themeSwitch,
+				enabled: false
+			} : themeSwitch,
+			sidebar: finalSidebarProps,
+			...aiMode === "sidebar-icon" && aiEnabled ? { searchToggle: { components: { lg: /* @__PURE__ */ jsx(SidebarSearchWithAI, {}) } } } : {},
+			children: [
+				/* @__PURE__ */ jsx(ColorStyle, { colors }),
+				/* @__PURE__ */ jsx(TypographyStyle, { typography }),
+				/* @__PURE__ */ jsx(LayoutStyle, { layout: layoutDimensions }),
+				forcedTheme && /* @__PURE__ */ jsx(ForcedThemeScript, { theme: forcedTheme }),
+				!staticExport && /* @__PURE__ */ jsx(Suspense, {
+					fallback: null,
+					children: /* @__PURE__ */ jsx(DocsCommandSearch, {
+						api: docsApiUrl,
+						locale
+					})
+				}),
+				aiEnabled && /* @__PURE__ */ jsx(Suspense, {
+					fallback: null,
+					children: /* @__PURE__ */ jsx(DocsAIFeatures, {
+						mode: aiMode,
+						api: docsApiUrl,
+						locale,
+						position: aiPosition,
+						floatingStyle: aiFloatingStyle,
+						suggestedQuestions: aiSuggestedQuestions,
+						aiLabel,
+						loaderVariant: aiLoaderVariant,
+						models: aiModels,
+						defaultModelId: aiDefaultModelId
+					})
+				}),
+				/* @__PURE__ */ jsx(Suspense, {
+					fallback: children,
+					children: /* @__PURE__ */ jsx(DocsPageClient, {
+						tocEnabled,
+						tocStyle,
+						breadcrumbEnabled,
+						entry: config.entry ?? "docs",
+						locale,
+						copyMarkdown: copyMarkdownEnabled,
+						openDocs: openDocsEnabled,
+						openDocsProviders,
+						pageActionsPosition,
+						pageActionsAlignment,
+						editOnGithubUrl,
+						lastUpdatedEnabled,
+						lastUpdatedPosition,
+						lastModified,
+						llmsTxtEnabled,
+						description,
+						children
+					})
+				})
+			]
+		})
+	});
+}
+
+//#endregion
+export { TanstackDocsLayout };

package/dist/tanstack.d.mts

@@ -0,0 +1,3 @@
+import { RootProvider } from "./provider-tanstack.mjs";
+import { TanstackDocsLayout } from "./tanstack-layout.mjs";
+export { RootProvider, TanstackDocsLayout };

package/dist/tanstack.mjs

@@ -0,0 +1,4 @@
+import { RootProvider } from "./provider-tanstack.mjs";
+import { TanstackDocsLayout } from "./tanstack-layout.mjs";
+
+export { RootProvider, TanstackDocsLayout };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/theme",
-  "version": "0.0.33-beta.1",
+  "version": "0.0.34",
   "description": "Theme package for @farming-labs/docs — layout, provider, MDX components, and styles",
   "keywords": [
     "docs",
@@ -73,6 +73,11 @@
       "import": "./dist/docs-api.mjs",
       "default": "./dist/docs-api.mjs"
     },
+    "./tanstack": {
+      "types": "./dist/tanstack.d.mts",
+      "import": "./dist/tanstack.mjs",
+      "default": "./dist/tanstack.mjs"
+    },
     "./ai": {
       "types": "./dist/ai-search-dialog.d.mts",
       "import": "./dist/ai-search-dialog.mjs",
@@ -100,11 +105,12 @@
   "devDependencies": {
     "@types/node": "^22.10.0",
     "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
     "next": ">=14.0.0",
     "tsdown": "^0.20.3",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4",
-    "@farming-labs/docs": "0.0.33-beta.1"
+    "@farming-labs/docs": "0.0.34"
   },
   "peerDependencies": {
     "@farming-labs/docs": ">=0.0.1",