@farming-labs/theme 0.1.144 → 0.2.0

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

@@ -6,11 +6,17 @@ type AIModelOption = {
   id: string;
   label: string;
 };
+type AIRequestMode = "openai-chat" | "docs-cloud";
+type AIRequestHeaders = Record<string, string>;
+type AIRequestStream = boolean;
 type LoaderVariant = "shimmer-dots" | "circular" | "dots" | "typing" | "wave" | "bars" | "pulse" | "pulse-dot" | "terminal" | "text-blink" | "text-shimmer" | "loading-dots";
 declare function DocsSearchDialog({
   open,
   onOpenChange,
   api,
+  requestMode,
+  requestHeaders,
+  requestStream,
   suggestedQuestions,
   aiLabel,
   loaderVariant,
@@ -23,6 +29,9 @@ declare function DocsSearchDialog({
   open: boolean;
   onOpenChange: (open: boolean) => void;
   api?: string;
+  requestMode?: AIRequestMode;
+  requestHeaders?: AIRequestHeaders;
+  requestStream?: AIRequestStream;
   suggestedQuestions?: string[];
   aiLabel?: string;
   loaderVariant?: LoaderVariant;
@@ -36,6 +45,9 @@ type FloatingPosition = "bottom-right" | "bottom-left" | "bottom-center";
 type FloatingStyle = "panel" | "modal" | "popover" | "full-modal";
 declare function FloatingAIChat({
   api,
+  requestMode,
+  requestHeaders,
+  requestStream,
   position,
   floatingStyle,
   triggerComponentHtml,
@@ -49,6 +61,9 @@ declare function FloatingAIChat({
   feedbackEnabled
 }: {
   api?: string;
+  requestMode?: AIRequestMode;
+  requestHeaders?: AIRequestHeaders;
+  requestStream?: AIRequestStream;
   position?: FloatingPosition;
   floatingStyle?: FloatingStyle;
   triggerComponentHtml?: string;
@@ -65,6 +80,9 @@ declare function AIModalDialog({
   open,
   onOpenChange,
   api,
+  requestMode,
+  requestHeaders,
+  requestStream,
   suggestedQuestions,
   aiLabel,
   loaderVariant,
@@ -77,6 +95,9 @@ declare function AIModalDialog({
   open: boolean;
   onOpenChange: (open: boolean) => void;
   api?: string;
+  requestMode?: AIRequestMode;
+  requestHeaders?: AIRequestHeaders;
+  requestStream?: AIRequestStream;
   suggestedQuestions?: string[];
   aiLabel?: string;
   loaderVariant?: LoaderVariant;

package/dist/ai-search-dialog.mjs

@@ -23,6 +23,158 @@ function createAIMessageId() {
 	aiMessageId += 1;
 	return `ai_${Date.now().toString(36)}_${aiMessageId.toString(36)}`;
 }
+function isPlainObject(value) {
+	return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function buildAIRequestHeaders(requestHeaders, requestStream = true) {
+	return {
+		Accept: requestStream ? "text/event-stream, application/json" : "application/json",
+		"Content-Type": "application/json",
+		...requestHeaders
+	};
+}
+function buildAIRequestBody(options) {
+	const messages = options.messages.map((message) => ({
+		role: message.role,
+		content: message.content
+	}));
+	if (options.requestMode === "docs-cloud") return JSON.stringify({
+		question: options.question,
+		messages,
+		answerMode: "auto",
+		answerStyle: "public",
+		modelPreference: options.model,
+		stream: options.requestStream !== false
+	});
+	return JSON.stringify({
+		messages,
+		model: options.model,
+		stream: options.requestStream !== false
+	});
+}
+function getOpenAICompatibleDeltaContent(value) {
+	if (!isPlainObject(value)) return void 0;
+	const firstChoice = Array.isArray(value.choices) ? value.choices[0] : void 0;
+	if (!isPlainObject(firstChoice)) return void 0;
+	const delta = firstChoice.delta;
+	if (!isPlainObject(delta)) return void 0;
+	return typeof delta.content === "string" ? delta.content : void 0;
+}
+function getDocsCloudAnswerContent(value) {
+	if (typeof value === "string") return value;
+	if (!isPlainObject(value)) return void 0;
+	for (const key of [
+		"answer",
+		"content",
+		"text",
+		"delta"
+	]) {
+		const content = value[key];
+		if (typeof content === "string") return content;
+	}
+}
+async function readAIResponseContent(response, onContent) {
+	if ((response.headers.get("content-type")?.toLowerCase() ?? "").includes("application/json")) {
+		const answer = getDocsCloudAnswerContent(await response.json().catch(() => null)) ?? "";
+		if (answer) onContent(answer);
+		return answer;
+	}
+	if (!response.body) return "";
+	const reader = response.body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	let assistantContent = "";
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		buffer += decoder.decode(value, { stream: true });
+		const lines = buffer.split("\n");
+		buffer = lines.pop() || "";
+		for (const line of lines) {
+			if (!line.startsWith("data: ")) continue;
+			const data = line.slice(6).trim();
+			if (!data || data === "[DONE]") continue;
+			try {
+				const json = JSON.parse(data);
+				const content = getOpenAICompatibleDeltaContent(json) ?? getDocsCloudAnswerContent(json);
+				if (content) {
+					assistantContent += content;
+					onContent(assistantContent);
+				}
+			} catch {}
+		}
+	}
+	return assistantContent;
+}
+function createSmoothAIStreamRenderer(onRender) {
+	let targetContent = "";
+	let visibleContent = "";
+	let frameId = null;
+	let lastFrameAt = 0;
+	let finishing = false;
+	let cancelled = false;
+	let resolveFinish;
+	const scheduleFrame = () => {
+		if (frameId !== null || cancelled) return;
+		if (typeof window !== "undefined" && typeof window.requestAnimationFrame === "function") {
+			frameId = window.requestAnimationFrame(renderFrame);
+			return;
+		}
+		frameId = setTimeout(() => renderFrame(Date.now()), 16);
+	};
+	const completeIfReady = () => {
+		if (!finishing || visibleContent !== targetContent || !resolveFinish) return;
+		const resolve = resolveFinish;
+		resolveFinish = void 0;
+		resolve(visibleContent);
+	};
+	const nextRevealCount = (gap, elapsedMs) => {
+		if (gap <= 0) return 0;
+		let charsPerSecond = 900;
+		if (gap > 2400) charsPerSecond = finishing ? 3600 : 3e3;
+		else if (gap > 1e3) charsPerSecond = finishing ? 2400 : 2e3;
+		else if (gap > 220) charsPerSecond = finishing ? 1600 : 1300;
+		return Math.max(1, Math.min(gap, Math.ceil(charsPerSecond * elapsedMs / 1e3)));
+	};
+	function renderFrame(timestamp) {
+		frameId = null;
+		if (cancelled) return;
+		const elapsedMs = lastFrameAt ? Math.min(48, Math.max(8, timestamp - lastFrameAt)) : 16;
+		lastFrameAt = timestamp;
+		const gap = targetContent.length - visibleContent.length;
+		if (gap > 0) {
+			const nextLength = visibleContent.length + nextRevealCount(gap, elapsedMs);
+			visibleContent = targetContent.slice(0, nextLength);
+			onRender(visibleContent);
+		}
+		if (visibleContent.length < targetContent.length) {
+			scheduleFrame();
+			return;
+		}
+		completeIfReady();
+	}
+	return {
+		push(content) {
+			if (cancelled) return;
+			targetContent = content;
+			scheduleFrame();
+		},
+		finish() {
+			finishing = true;
+			if (visibleContent === targetContent) return Promise.resolve(visibleContent);
+			return new Promise((resolve) => {
+				resolveFinish = resolve;
+				scheduleFrame();
+			});
+		},
+		cancel() {
+			cancelled = true;
+			if (frameId !== null) if (typeof window !== "undefined" && typeof window.cancelAnimationFrame === "function") window.cancelAnimationFrame(frameId);
+			else clearTimeout(frameId);
+			frameId = null;
+		}
+	};
+}
 function getLastUserQuestion(messages, assistantIndex) {
 	for (let i = assistantIndex - 1; i >= 0; i -= 1) {
 		const message = messages[i];
@@ -561,7 +713,7 @@ function AIFeedbackControls({ value, onCopy, onSelect }) {
 		]
 	});
 }
-function AIChat({ api, messages, setMessages, aiInput, setAiInput, isStreaming, setIsStreaming, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics, feedbackEnabled = true, surface = "chat" }) {
+function AIChat({ api, requestMode, requestHeaders, requestStream = true, messages, setMessages, aiInput, setAiInput, isStreaming, setIsStreaming, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics, feedbackEnabled = true, surface = "chat" }) {
 	const label = aiLabel || "AI";
 	const aiInputRef = useRef(null);
 	const messagesEndRef = useRef(null);
@@ -571,8 +723,8 @@ function AIChat({ api, messages, setMessages, aiInput, setAiInput, isStreaming,
 	});
 	const effectiveModelId = selectedModel || (Array.isArray(models) && models.length > 0 ? models[0].id : void 0);
 	useEffect(() => {
-		messagesEndRef.current?.scrollIntoView({ behavior: "smooth" });
-	}, [messages]);
+		messagesEndRef.current?.scrollIntoView({ behavior: isStreaming ? "auto" : "smooth" });
+	}, [isStreaming, messages]);
 	useEffect(() => {
 		aiInputRef.current?.focus();
 	}, []);
@@ -602,15 +754,16 @@ function AIChat({ api, messages, setMessages, aiInput, setAiInput, isStreaming,
 				model: effectiveModelId
 			}
 		});
+		let streamRenderer;
 		try {
 			const res = await fetch(api, {
 				method: "POST",
-				headers: { "Content-Type": "application/json" },
-				body: JSON.stringify({
-					messages: newMessages.map((m) => ({
-						role: m.role,
-						content: m.content
-					})),
+				headers: buildAIRequestHeaders(requestHeaders, requestStream),
+				body: buildAIRequestBody({
+					requestMode,
+					requestStream,
+					question,
+					messages: newMessages,
 					model: effectiveModelId
 				})
 			});
@@ -636,46 +789,32 @@ function AIChat({ api, messages, setMessages, aiInput, setAiInput, isStreaming,
 				});
 				return;
 			}
-			const reader = res.body.getReader();
-			const decoder = new TextDecoder();
-			let buffer = "";
-			let assistantContent = "";
-			while (true) {
-				const { done, value } = await reader.read();
-				if (done) break;
-				buffer += decoder.decode(value, { stream: true });
-				const lines = buffer.split("\n");
-				buffer = lines.pop() || "";
-				for (const line of lines) if (line.startsWith("data: ")) {
-					const data = line.slice(6).trim();
-					if (data === "[DONE]") continue;
-					try {
-						const content = JSON.parse(data).choices?.[0]?.delta?.content;
-						if (content) {
-							assistantContent += content;
-							setMessages([...newMessages, {
-								...assistantMessage,
-								content: assistantContent
-							}]);
-						}
-					} catch {}
-				}
-			}
-			if (assistantContent) setMessages([...newMessages, {
+			streamRenderer = createSmoothAIStreamRenderer((content) => {
+				setMessages([...newMessages, {
+					...assistantMessage,
+					content
+				}]);
+			});
+			const assistantContent = await readAIResponseContent(res, (content) => {
+				streamRenderer?.push(content);
+			});
+			const finalContent = await streamRenderer.finish() || assistantContent;
+			if (finalContent) setMessages([...newMessages, {
 				...assistantMessage,
-				content: assistantContent
+				content: finalContent
 			}]);
 			if (analytics) emitClientAnalyticsEvent({
 				type: "ai_response",
 				properties: {
 					surface,
 					questionLength: question.length,
-					responseLength: assistantContent.length,
+					responseLength: finalContent.length,
 					durationMs: Math.max(0, Date.now() - startedAt),
 					model: effectiveModelId
 				}
 			});
 		} catch {
+			streamRenderer?.cancel();
 			setMessages([...newMessages, {
 				...assistantMessage,
 				content: "Failed to connect. Please try again.",
@@ -694,6 +833,9 @@ function AIChat({ api, messages, setMessages, aiInput, setAiInput, isStreaming,
 	}, [
 		messages,
 		api,
+		requestMode,
+		requestHeaders,
+		requestStream,
 		isStreaming,
 		setMessages,
 		setAiInput,
@@ -860,7 +1002,7 @@ function AIChat({ api, messages, setMessages, aiInput, setAiInput, isStreaming,
 		})]
 	});
 }
-function DocsSearchDialog({ open, onOpenChange, api = "/api/docs", suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics = false, feedbackEnabled = true }) {
+function DocsSearchDialog({ open, onOpenChange, api = "/api/docs", requestMode, requestHeaders, requestStream, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics = false, feedbackEnabled = true }) {
 	const [tab, setTab] = useState("search");
 	const [searchQuery, setSearchQuery] = useState("");
 	const [searchResults, setSearchResults] = useState([]);
@@ -1096,6 +1238,9 @@ function DocsSearchDialog({ open, onOpenChange, api = "/api/docs", suggestedQues
 			}),
 			tab === "ai" && /* @__PURE__ */ jsx(AIChat, {
 				api,
+				requestMode,
+				requestHeaders,
+				requestStream,
 				messages,
 				setMessages,
 				aiInput,
@@ -1184,7 +1329,7 @@ function getContainerStyles(style, position) {
 function getAnimation(style) {
 	return style === "modal" ? "fd-ai-float-center-in 200ms ease-out" : "fd-ai-float-in 200ms ease-out";
 }
-function FloatingAIChat({ api = "/api/docs", position = "bottom-right", floatingStyle = "panel", triggerComponentHtml, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics = false, feedbackEnabled = true }) {
+function FloatingAIChat({ api = "/api/docs", requestMode, requestHeaders, requestStream, position = "bottom-right", floatingStyle = "panel", triggerComponentHtml, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics = false, feedbackEnabled = true }) {
 	const [mounted, setMounted] = useState(false);
 	const [isOpen, setIsOpen] = useState(false);
 	const [messages, setMessages] = useState([]);
@@ -1224,6 +1369,9 @@ function FloatingAIChat({ api = "/api/docs", position = "bottom-right", floating
 	if (!mounted) return null;
 	if (floatingStyle === "full-modal") return /* @__PURE__ */ jsx(FullModalAIChat, {
 		api,
+		requestMode,
+		requestHeaders,
+		requestStream,
 		isOpen,
 		setIsOpen,
 		closeAI: closeFloatingAI,
@@ -1280,6 +1428,9 @@ function FloatingAIChat({ api = "/api/docs", position = "bottom-right", floating
 				]
 			}), /* @__PURE__ */ jsx(AIChat, {
 				api,
+				requestMode,
+				requestHeaders,
+				requestStream,
 				messages,
 				setMessages,
 				aiInput,
@@ -1329,7 +1480,7 @@ function FloatingAIChat({ api = "/api/docs", position = "bottom-right", floating
 		}))
 	] }), document.body);
 }
-function FullModalAIChat({ api, isOpen, setIsOpen, closeAI, messages, setMessages, aiInput, setAiInput, isStreaming, setIsStreaming, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, triggerComponentHtml, position, models, defaultModelId, analytics, feedbackEnabled = true }) {
+function FullModalAIChat({ api, requestMode, requestHeaders, requestStream, isOpen, setIsOpen, closeAI, messages, setMessages, aiInput, setAiInput, isStreaming, setIsStreaming, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, triggerComponentHtml, position, models, defaultModelId, analytics, feedbackEnabled = true }) {
 	const label = aiLabel || "AI";
 	const inputRef = useRef(null);
 	const listRef = useRef(null);
@@ -1345,9 +1496,9 @@ function FullModalAIChat({ api, isOpen, setIsOpen, closeAI, messages, setMessage
 	useEffect(() => {
 		if (listRef.current) listRef.current.scrollTo({
 			top: listRef.current.scrollHeight,
-			behavior: "smooth"
+			behavior: isStreaming ? "auto" : "smooth"
 		});
-	}, [messages]);
+	}, [isStreaming, messages]);
 	const submitQuestion = useCallback(async (question) => {
 		if (!question.trim() || isStreaming) return;
 		const userMessage = {
@@ -1374,15 +1525,16 @@ function FullModalAIChat({ api, isOpen, setIsOpen, closeAI, messages, setMessage
 				model: effectiveModelId
 			}
 		});
+		let streamRenderer;
 		try {
 			const res = await fetch(api, {
 				method: "POST",
-				headers: { "Content-Type": "application/json" },
-				body: JSON.stringify({
-					messages: newMessages.map((m) => ({
-						role: m.role,
-						content: m.content
-					})),
+				headers: buildAIRequestHeaders(requestHeaders, requestStream),
+				body: buildAIRequestBody({
+					requestMode,
+					requestStream,
+					question,
+					messages: newMessages,
 					model: effectiveModelId
 				})
 			});
@@ -1408,46 +1560,32 @@ function FullModalAIChat({ api, isOpen, setIsOpen, closeAI, messages, setMessage
 				});
 				return;
 			}
-			const reader = res.body.getReader();
-			const decoder = new TextDecoder();
-			let buffer = "";
-			let assistantContent = "";
-			while (true) {
-				const { done, value } = await reader.read();
-				if (done) break;
-				buffer += decoder.decode(value, { stream: true });
-				const lines = buffer.split("\n");
-				buffer = lines.pop() || "";
-				for (const line of lines) if (line.startsWith("data: ")) {
-					const data = line.slice(6).trim();
-					if (data === "[DONE]") continue;
-					try {
-						const content = JSON.parse(data).choices?.[0]?.delta?.content;
-						if (content) {
-							assistantContent += content;
-							setMessages([...newMessages, {
-								...assistantMessage,
-								content: assistantContent
-							}]);
-						}
-					} catch {}
-				}
-			}
-			if (assistantContent) setMessages([...newMessages, {
+			streamRenderer = createSmoothAIStreamRenderer((content) => {
+				setMessages([...newMessages, {
+					...assistantMessage,
+					content
+				}]);
+			});
+			const assistantContent = await readAIResponseContent(res, (content) => {
+				streamRenderer?.push(content);
+			});
+			const finalContent = await streamRenderer.finish() || assistantContent;
+			if (finalContent) setMessages([...newMessages, {
 				...assistantMessage,
-				content: assistantContent
+				content: finalContent
 			}]);
 			if (analytics) emitClientAnalyticsEvent({
 				type: "ai_response",
 				properties: {
 					surface: "full-modal",
 					questionLength: question.length,
-					responseLength: assistantContent.length,
+					responseLength: finalContent.length,
 					durationMs: Math.max(0, Date.now() - startedAt),
 					model: effectiveModelId
 				}
 			});
 		} catch {
+			streamRenderer?.cancel();
 			setMessages([...newMessages, {
 				...assistantMessage,
 				content: "Failed to connect. Please try again.",
@@ -1466,6 +1604,9 @@ function FullModalAIChat({ api, isOpen, setIsOpen, closeAI, messages, setMessage
 	}, [
 		messages,
 		api,
+		requestMode,
+		requestHeaders,
+		requestStream,
 		isStreaming,
 		setMessages,
 		setAiInput,
@@ -1677,7 +1818,7 @@ function TrashIcon() {
 		]
 	});
 }
-function AIModalDialog({ open, onOpenChange, api = "/api/docs", suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics = false, feedbackEnabled = true }) {
+function AIModalDialog({ open, onOpenChange, api = "/api/docs", requestMode, requestHeaders, requestStream, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics = false, feedbackEnabled = true }) {
 	const [messages, setMessages] = useState([]);
 	const [aiInput, setAiInput] = useState("");
 	const [isStreaming, setIsStreaming] = useState(false);
@@ -1746,6 +1887,9 @@ function AIModalDialog({ open, onOpenChange, api = "/api/docs", suggestedQuestio
 			}),
 			/* @__PURE__ */ jsx(AIChat, {
 				api,
+				requestMode,
+				requestHeaders,
+				requestStream,
 				messages,
 				setMessages,
 				aiInput,

package/dist/docs-ai-features.d.mts

@@ -4,6 +4,9 @@ import * as react_jsx_runtime0 from "react/jsx-runtime";
 interface DocsAIFeaturesProps {
   mode: "search" | "floating" | "sidebar-icon";
   api?: string;
+  requestMode?: "openai-chat" | "docs-cloud";
+  requestHeaders?: Record<string, string>;
+  requestStream?: boolean;
   locale?: string;
   position?: "bottom-right" | "bottom-left" | "bottom-center";
   floatingStyle?: "panel" | "modal" | "popover" | "full-modal";
@@ -23,6 +26,9 @@ interface DocsAIFeaturesProps {
 declare function DocsAIFeatures({
   mode,
   api,
+  requestMode,
+  requestHeaders,
+  requestStream,
   locale,
   position,
   floatingStyle,

package/dist/docs-ai-features.mjs

@@ -22,10 +22,13 @@ import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 * This component is rendered inside the docs layout so the user's root layout
 * 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, analytics = false, feedbackEnabled = true }) {
+function DocsAIFeatures({ mode, api = "/api/docs", requestMode, requestHeaders, requestStream, locale, position = "bottom-right", floatingStyle = "panel", triggerComponentHtml, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics = false, feedbackEnabled = true }) {
 	const localizedApi = withLangInUrl(api, resolveClientLocale(useWindowSearchParams(), locale));
 	if (mode === "search") return /* @__PURE__ */ jsx(SearchModeAI, {
 		api: localizedApi,
+		requestMode,
+		requestHeaders,
+		requestStream,
 		suggestedQuestions,
 		aiLabel,
 		loaderVariant,
@@ -37,6 +40,9 @@ function DocsAIFeatures({ mode, api = "/api/docs", locale, position = "bottom-ri
 	});
 	if (mode === "sidebar-icon") return /* @__PURE__ */ jsx(SidebarIconModeAI, {
 		api: localizedApi,
+		requestMode,
+		requestHeaders,
+		requestStream,
 		suggestedQuestions,
 		aiLabel,
 		loaderVariant,
@@ -48,6 +54,9 @@ function DocsAIFeatures({ mode, api = "/api/docs", locale, position = "bottom-ri
 	});
 	return /* @__PURE__ */ jsx(FloatingAIChat, {
 		api: localizedApi,
+		requestMode,
+		requestHeaders,
+		requestStream,
 		position,
 		floatingStyle,
 		triggerComponentHtml,
@@ -61,7 +70,7 @@ function DocsAIFeatures({ mode, api = "/api/docs", locale, position = "bottom-ri
 		feedbackEnabled
 	});
 }
-function SearchModeAI({ api, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics, feedbackEnabled }) {
+function SearchModeAI({ api, requestMode, requestHeaders, requestStream, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics, feedbackEnabled }) {
 	const [open, setOpen] = useState(false);
 	useEffect(() => {
 		function handler(e) {
@@ -108,6 +117,9 @@ function SearchModeAI({ api, suggestedQuestions, aiLabel, loaderVariant, loading
 		open,
 		onOpenChange: setOpen,
 		api,
+		requestMode,
+		requestHeaders,
+		requestStream,
 		suggestedQuestions,
 		aiLabel,
 		loaderVariant,
@@ -118,7 +130,7 @@ function SearchModeAI({ api, suggestedQuestions, aiLabel, loaderVariant, loading
 		feedbackEnabled
 	});
 }
-function SidebarIconModeAI({ api, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics, feedbackEnabled }) {
+function SidebarIconModeAI({ api, requestMode, requestHeaders, requestStream, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics, feedbackEnabled }) {
 	const [searchOpen, setSearchOpen] = useState(false);
 	const [aiOpen, setAiOpen] = useState(false);
 	useEffect(() => {
@@ -165,6 +177,9 @@ function SidebarIconModeAI({ api, suggestedQuestions, aiLabel, loaderVariant, lo
 		open: searchOpen,
 		onOpenChange: setSearchOpen,
 		api,
+		requestMode,
+		requestHeaders,
+		requestStream,
 		suggestedQuestions,
 		aiLabel,
 		loaderVariant,
@@ -177,6 +192,9 @@ function SidebarIconModeAI({ api, suggestedQuestions, aiLabel, loaderVariant, lo
 		open: aiOpen,
 		onOpenChange: setAiOpen,
 		api,
+		requestMode,
+		requestHeaders,
+		requestStream,
 		suggestedQuestions,
 		aiLabel,
 		loaderVariant,

package/dist/docs-api.d.mts

@@ -16,6 +16,7 @@ interface AIModelConfig {
 }
 interface AIOptions {
   enabled?: boolean;
+  provider?: string;
   model?: string | AIModelConfig;
   providers?: Record<string, AIProviderConfig>;
   systemPrompt?: string;
@@ -29,6 +30,7 @@ interface AIOptions {
   apiKey?: string;
   maxResults?: number;
   useMcp?: boolean | DocsAskAIMcpConfig;
+  stream?: boolean;
 }
 interface DocsAPIOptions {
   rootDir?: string;
@@ -44,6 +46,8 @@ interface DocsAPIOptions {
   language?: string;
   /** AI chat configuration */
   ai?: AIOptions;
+  /** Hosted Docs Cloud configuration. */
+  cloud?: DocsConfig["cloud"];
   /** i18n config (optional) */
   i18n?: DocsI18nConfig;
   /** Search configuration */

package/dist/docs-api.mjs

@@ -35,6 +35,8 @@ const FILE_EXTS = [
 	"js"
 ];
 const DEFAULT_DOCS_API_ROUTE = "/api/docs";
+const DEFAULT_DOCS_CLOUD_API_BASE_URL = "https://docs-app.farming-labs.dev";
+const DEFAULT_DOCS_CLOUD_API_KEY_ENV = "DOCS_CLOUD_API_KEY";
 const DEFAULT_AGENT_SPEC_ROUTE = "/api/docs/agent/spec";
 const DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE = "/.well-known/agent";
 const DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE = "/.well-known/agent.json";
@@ -513,21 +515,25 @@ function readAIConfig(root) {
 			if (!content.includes("ai:") && !content.includes("ai :")) return {};
 			const enabledMatch = content.match(/ai\s*:\s*\{[^}]*enabled\s*:\s*(true|false)/s);
 			if (enabledMatch && enabledMatch[1] === "false") return {};
+			const providerMatch = content.match(/ai\s*:\s*\{[^}]*provider\s*:\s*["']([^"']+)["']/s);
 			const modelMatch = content.match(/ai\s*:\s*\{[^}]*model\s*:\s*["']([^"']+)["']/s);
 			const baseUrlMatch = content.match(/ai\s*:\s*\{[^}]*baseUrl\s*:\s*["']([^"']+)["']/s);
 			const apiKeyMatch = content.match(/ai\s*:\s*\{[^}]*apiKey\s*:\s*process\.env\.(\w+)/s);
 			const maxResultsMatch = content.match(/ai\s*:\s*\{[^}]*maxResults\s*:\s*(\d+)/s);
 			const useMcpMatch = content.match(/ai\s*:\s*\{[^}]*useMcp\s*:\s*(true|false)/s);
+			const streamMatch = content.match(/ai\s*:\s*\{[^}]*stream\s*:\s*(true|false)/s);
 			const systemPromptMatch = content.match(/ai\s*:\s*\{[^}]*systemPrompt\s*:\s*["'`]([^"'`]+)["'`]/s);
 			const packageNameMatch = content.match(/ai\s*:\s*\{[^}]*packageName\s*:\s*["'`]([^"'`]+)["'`]/s);
 			const docsUrlMatch = content.match(/ai\s*:\s*\{[^}]*docsUrl\s*:\s*["'`]([^"'`]+)["'`]/s);
 			return {
 				enabled: true,
+				provider: providerMatch?.[1],
 				model: modelMatch?.[1],
 				baseUrl: baseUrlMatch?.[1],
 				apiKey: apiKeyMatch?.[1] ? process.env[apiKeyMatch[1]] : void 0,
 				maxResults: maxResultsMatch ? parseInt(maxResultsMatch[1], 10) : void 0,
 				useMcp: useMcpMatch ? useMcpMatch[1] === "true" : void 0,
+				stream: streamMatch ? streamMatch[1] === "true" : void 0,
 				systemPrompt: systemPromptMatch?.[1],
 				packageName: packageNameMatch?.[1],
 				docsUrl: docsUrlMatch?.[1]
@@ -536,6 +542,22 @@ function readAIConfig(root) {
 	}
 	return {};
 }
+function readCloudConfig(root) {
+	for (const ext of FILE_EXTS) {
+		const configPath = path.join(root, `docs.config.${ext}`);
+		if (!fs.existsSync(configPath)) continue;
+		try {
+			const content = fs.readFileSync(configPath, "utf-8");
+			const sanitized = stripCommentsAndStrings(content);
+			const configObject = extractRootConfigObject(content, sanitized);
+			const cloudBlock = extractObjectLiteral(configObject?.content ?? content, configObject?.sanitized ?? sanitized, "cloud");
+			if (!cloudBlock) continue;
+			const apiKeyBlock = extractObjectLiteral(cloudBlock, stripCommentsAndStrings(cloudBlock), "apiKey");
+			const apiKeyEnv = apiKeyBlock ? readStringFromBlock(apiKeyBlock, "env") : void 0;
+			return apiKeyEnv ? { apiKey: { env: apiKeyEnv } } : {};
+		} catch {}
+	}
+}
 function readMcpConfig(root) {
 	for (const ext of FILE_EXTS) {
 		const configPath = path.join(root, `docs.config.${ext}`);
@@ -1294,6 +1316,121 @@ function resolveModelAndProvider(aiConfig, requestedModelId) {
 		apiKey
 	};
 }
+function readRuntimeEnv(name) {
+	const value = process.env[name]?.trim();
+	return value ? value : void 0;
+}
+function resolveDocsCloudApiBaseUrl() {
+	return (readRuntimeEnv("DOCS_CLOUD_API_URL") ?? readRuntimeEnv("NEXT_PUBLIC_DOCS_CLOUD_URL") ?? DEFAULT_DOCS_CLOUD_API_BASE_URL).replace(/\/+$/, "");
+}
+function resolveDocsCloudProjectId() {
+	return readRuntimeEnv("NEXT_PUBLIC_DOCS_CLOUD_PROJECT_ID") ?? readRuntimeEnv("DOCS_CLOUD_PROJECT_ID");
+}
+function resolveDocsCloudApiKey(cloudConfig) {
+	const envName = cloudConfig?.apiKey?.env?.trim() || DEFAULT_DOCS_CLOUD_API_KEY_ENV;
+	return {
+		envName,
+		apiKey: readRuntimeEnv(envName)
+	};
+}
+function createOpenAICompatibleSseChunk(content) {
+	return `data: ${JSON.stringify({ choices: [{ delta: { content } }] })}\n\n`;
+}
+function createOpenAICompatibleSseResponse(content) {
+	const encoder = new TextEncoder();
+	const stream = new ReadableStream({ start(controller) {
+		if (content) controller.enqueue(encoder.encode(createOpenAICompatibleSseChunk(content)));
+		controller.enqueue(encoder.encode("data: [DONE]\n\n"));
+		controller.close();
+	} });
+	return new Response(stream, { headers: {
+		"Content-Type": "text/event-stream",
+		"Cache-Control": "no-cache",
+		Connection: "keep-alive"
+	} });
+}
+function getOpenAICompatibleDeltaContent(value) {
+	if (!isPlainObject(value)) return void 0;
+	const firstChoice = Array.isArray(value.choices) ? value.choices[0] : void 0;
+	if (!isPlainObject(firstChoice)) return void 0;
+	const delta = firstChoice.delta;
+	if (!isPlainObject(delta)) return void 0;
+	return typeof delta.content === "string" ? delta.content : void 0;
+}
+function getDocsCloudStreamContent(value) {
+	if (typeof value === "string") return value;
+	if (!isPlainObject(value)) return void 0;
+	for (const key of [
+		"content",
+		"text",
+		"answer",
+		"delta"
+	]) {
+		const content = value[key];
+		if (typeof content === "string") return content;
+	}
+}
+function createDocsCloudSseProxyResponse(body) {
+	if (!body) return createOpenAICompatibleSseResponse("");
+	const decoder = new TextDecoder();
+	const encoder = new TextEncoder();
+	const stream = new ReadableStream({ async start(controller) {
+		const reader = body.getReader();
+		let buffer = "";
+		let doneSent = false;
+		const enqueue = (chunk) => {
+			controller.enqueue(encoder.encode(chunk));
+		};
+		const flushEvent = (event) => {
+			const data = event.split(/\r?\n/).filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trim()).filter(Boolean).join("\n").trim();
+			if (!data) return;
+			if (data === "[DONE]") {
+				doneSent = true;
+				enqueue("data: [DONE]\n\n");
+				return;
+			}
+			try {
+				const parsed = JSON.parse(data);
+				if (getOpenAICompatibleDeltaContent(parsed) !== void 0) {
+					enqueue(`data: ${data}\n\n`);
+					return;
+				}
+				const content = getDocsCloudStreamContent(parsed);
+				if (content) enqueue(createOpenAICompatibleSseChunk(content));
+			} catch {
+				enqueue(createOpenAICompatibleSseChunk(data));
+			}
+		};
+		try {
+			while (true) {
+				const { value, done } = await reader.read();
+				if (done) break;
+				buffer += decoder.decode(value, { stream: true });
+				const events = buffer.split(/\r?\n\r?\n/);
+				buffer = events.pop() ?? "";
+				for (const event of events) flushEvent(event);
+			}
+			buffer += decoder.decode();
+			if (buffer.trim()) flushEvent(buffer);
+			if (!doneSent) enqueue("data: [DONE]\n\n");
+			controller.close();
+		} catch (error) {
+			controller.error(error);
+		}
+	} });
+	return new Response(stream, { headers: {
+		"Content-Type": "text/event-stream",
+		"Cache-Control": "no-cache",
+		Connection: "keep-alive"
+	} });
+}
+function getDocsCloudAnswerFromPayload(payload) {
+	if (!isPlainObject(payload)) return "";
+	const answer = payload.answer;
+	if (typeof answer === "string") return answer;
+	const text = payload.text;
+	return typeof text === "string" ? text : "";
+}
 function safeUrlOrigin(value) {
 	try {
 		return new URL(value).origin;
@@ -1305,7 +1442,7 @@ function getRequestAnalyticsProperties(request) {
 	const userAgent = request.headers.get("user-agent")?.trim();
 	return userAgent ? { userAgent } : {};
 }
-async function handleAskAI(request, indexes, aiConfig, search, analytics, observability, analyticsContext = {}) {
+async function handleAskAI(request, indexes, aiConfig, cloudConfig, search, analytics, observability, analyticsContext = {}) {
 	const url = new URL(request.url);
 	const requestAnalyticsProperties = getRequestAnalyticsProperties(request);
 	const requestStartedAt = Date.now();
@@ -1387,6 +1524,7 @@ async function handleAskAI(request, indexes, aiConfig, search, analytics, observ
 		return Response.json({ error: "Invalid JSON body. Expected { messages: [...] }" }, { status: 400 });
 	}
 	const messages = body.messages;
+	const shouldStreamResponse = body.stream !== false && (request.headers.get("accept")?.toLowerCase().includes("text/event-stream") ?? true);
 	if (!Array.isArray(messages) || messages.length === 0) {
 		await emitDocsAnalyticsEvent(analytics, {
 			type: "api_ai_error",
@@ -1440,6 +1578,286 @@ async function handleAskAI(request, indexes, aiConfig, search, analytics, observ
 			requestedModel: typeof body.model === "string" && body.model.trim().length > 0 ? body.model.trim() : void 0
 		}
 	});
+	if (aiConfig.provider === "docs-cloud") {
+		const requestedModel = typeof body.model === "string" && body.model.trim().length > 0 ? body.model.trim() : void 0;
+		const model = requestedModel ?? "docs-cloud";
+		const projectId = resolveDocsCloudProjectId();
+		const { envName, apiKey } = resolveDocsCloudApiKey(cloudConfig);
+		const cloudApiBaseUrl = resolveDocsCloudApiBaseUrl();
+		const cloudAskUrl = projectId ? `${cloudApiBaseUrl}/v1/projects/${encodeURIComponent(projectId)}/knowledge/ask` : void 0;
+		if (!projectId || !apiKey || !cloudAskUrl) {
+			const reason = !projectId ? "missing_docs_cloud_project_id" : "missing_docs_cloud_api_key";
+			await emitDocsAnalyticsEvent(analytics, {
+				type: "api_ai_error",
+				source: "server",
+				url: request.url,
+				path: url.pathname,
+				locale: analyticsContext.locale,
+				input: { question: query },
+				properties: {
+					...requestAnalyticsProperties,
+					reason,
+					provider: "docs-cloud",
+					messageCount: messages.length,
+					questionLength: query.length,
+					model,
+					envName: !apiKey ? envName : void 0,
+					durationMs: Math.max(0, Date.now() - requestStartedAt)
+				}
+			});
+			await emitRunError(reason, {
+				status: 500,
+				provider: "docs-cloud",
+				messageCount: messages.length,
+				questionLength: query.length,
+				model,
+				envName: !apiKey ? envName : void 0
+			});
+			return Response.json({ error: !projectId ? "AI provider docs-cloud requires NEXT_PUBLIC_DOCS_CLOUD_PROJECT_ID or DOCS_CLOUD_PROJECT_ID." : `AI provider docs-cloud requires ${envName} to be set on the server.` }, { status: 500 });
+		}
+		await emitDocsAnalyticsEvent(analytics, {
+			type: "api_ai_request",
+			source: "server",
+			url: request.url,
+			path: url.pathname,
+			locale: analyticsContext.locale,
+			input: { question: query },
+			properties: {
+				...requestAnalyticsProperties,
+				provider: "docs-cloud",
+				messageCount: messages.length,
+				questionLength: query.length,
+				model
+			}
+		});
+		const modelStartedAt = Date.now();
+		const modelStartedAtIso = (/* @__PURE__ */ new Date()).toISOString();
+		const modelSpanId = createDocsAgentTraceId("span");
+		const providerOrigin = safeUrlOrigin(cloudApiBaseUrl);
+		await emitTrace({
+			type: "model.call",
+			name: model,
+			spanId: modelSpanId,
+			parentSpanId: runSpanId,
+			startedAt: modelStartedAtIso,
+			status: "started",
+			inputPreview: {
+				messageCount: messages.length,
+				stream: shouldStreamResponse,
+				providerOrigin
+			},
+			metadata: {
+				model,
+				provider: "docs-cloud"
+			}
+		});
+		let cloudResponse;
+		try {
+			cloudResponse = await fetch(cloudAskUrl, {
+				method: "POST",
+				headers: {
+					Accept: shouldStreamResponse ? "text/event-stream, application/json" : "application/json",
+					"Content-Type": "application/json",
+					Authorization: `Bearer ${apiKey}`
+				},
+				body: JSON.stringify({
+					question: query,
+					answerMode: "auto",
+					answerStyle: "public",
+					modelPreference: requestedModel,
+					stream: shouldStreamResponse
+				})
+			});
+		} catch (error) {
+			const elapsed = Math.max(0, Date.now() - modelStartedAt);
+			const message = error instanceof Error ? error.message : "Unknown error";
+			await emitTrace({
+				type: "model.error",
+				name: model,
+				parentSpanId: modelSpanId,
+				startedAt: modelStartedAtIso,
+				endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				durationMs: elapsed,
+				status: "error",
+				outputPreview: { message },
+				metadata: {
+					model,
+					provider: "docs-cloud",
+					providerOrigin
+				}
+			});
+			await emitDocsAnalyticsEvent(analytics, {
+				type: "api_ai_error",
+				source: "server",
+				url: request.url,
+				path: url.pathname,
+				locale: analyticsContext.locale,
+				input: { question: query },
+				properties: {
+					...requestAnalyticsProperties,
+					reason: "docs_cloud_fetch_error",
+					provider: "docs-cloud",
+					messageCount: messages.length,
+					questionLength: query.length,
+					model,
+					durationMs: Math.max(0, Date.now() - requestStartedAt)
+				}
+			});
+			await emitRunError("docs_cloud_fetch_error", {
+				status: 502,
+				provider: "docs-cloud",
+				messageCount: messages.length,
+				questionLength: query.length,
+				model
+			});
+			return Response.json({ error: "Docs Cloud Ask AI request failed." }, { status: 502 });
+		}
+		if (!cloudResponse.ok) {
+			const errText = await cloudResponse.text().catch(() => "Unknown error");
+			const elapsed = Math.max(0, Date.now() - modelStartedAt);
+			await emitTrace({
+				type: "model.error",
+				name: model,
+				parentSpanId: modelSpanId,
+				startedAt: modelStartedAtIso,
+				endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				durationMs: elapsed,
+				status: "error",
+				outputPreview: {
+					status: cloudResponse.status,
+					errorChars: errText.length
+				},
+				metadata: {
+					model,
+					provider: "docs-cloud",
+					providerOrigin
+				}
+			});
+			await emitDocsAnalyticsEvent(analytics, {
+				type: "api_ai_error",
+				source: "server",
+				url: request.url,
+				path: url.pathname,
+				locale: analyticsContext.locale,
+				input: { question: query },
+				properties: {
+					...requestAnalyticsProperties,
+					reason: "docs_cloud_error",
+					provider: "docs-cloud",
+					status: cloudResponse.status,
+					messageCount: messages.length,
+					questionLength: query.length,
+					model,
+					durationMs: Math.max(0, Date.now() - requestStartedAt)
+				}
+			});
+			await emitRunError("docs_cloud_error", {
+				status: 502,
+				modelStatus: cloudResponse.status,
+				provider: "docs-cloud",
+				messageCount: messages.length,
+				questionLength: query.length,
+				model
+			});
+			return Response.json({ error: `Docs Cloud Ask AI error (${cloudResponse.status}).` }, { status: 502 });
+		}
+		await emitDocsAnalyticsEvent(analytics, {
+			type: "api_ai_response",
+			source: "server",
+			url: request.url,
+			path: url.pathname,
+			locale: analyticsContext.locale,
+			input: { question: query },
+			properties: {
+				...requestAnalyticsProperties,
+				provider: "docs-cloud",
+				messageCount: messages.length,
+				questionLength: query.length,
+				model,
+				durationMs: Math.max(0, Date.now() - requestStartedAt)
+			}
+		});
+		const responseEndedAt = (/* @__PURE__ */ new Date()).toISOString();
+		const modelDurationMs = Math.max(0, Date.now() - modelStartedAt);
+		const contentType = cloudResponse.headers.get("content-type") ?? void 0;
+		await emitTrace({
+			type: "model.response",
+			name: model,
+			parentSpanId: modelSpanId,
+			startedAt: modelStartedAtIso,
+			endedAt: responseEndedAt,
+			durationMs: modelDurationMs,
+			status: "success",
+			outputPreview: {
+				status: cloudResponse.status,
+				stream: shouldStreamResponse,
+				contentType
+			},
+			metadata: {
+				model,
+				provider: "docs-cloud",
+				providerOrigin
+			}
+		});
+		await emitTrace({
+			type: "model.stream",
+			name: model,
+			parentSpanId: modelSpanId,
+			startedAt: modelStartedAtIso,
+			endedAt: responseEndedAt,
+			durationMs: modelDurationMs,
+			status: "success",
+			outputPreview: { stream: shouldStreamResponse },
+			metadata: {
+				model,
+				provider: "docs-cloud"
+			}
+		});
+		const runDurationMs = Math.max(0, Date.now() - requestStartedAt);
+		await emitTrace({
+			type: "agent.final",
+			name: "ask-ai",
+			parentSpanId: runSpanId,
+			startedAt: trace.startedAt,
+			endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			durationMs: runDurationMs,
+			status: "success",
+			outputPreview: {
+				stream: shouldStreamResponse,
+				provider: "docs-cloud"
+			},
+			metadata: {
+				model,
+				provider: "docs-cloud"
+			}
+		});
+		await emitTrace({
+			type: "run.end",
+			name: "ask-ai",
+			spanId: runSpanId,
+			startedAt: trace.startedAt,
+			endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			durationMs: runDurationMs,
+			status: "success",
+			outputPreview: {
+				stream: shouldStreamResponse,
+				provider: "docs-cloud"
+			},
+			metadata: {
+				model,
+				provider: "docs-cloud"
+			}
+		});
+		if (shouldStreamResponse && contentType?.includes("text/event-stream")) return createDocsCloudSseProxyResponse(cloudResponse.body);
+		const cloudBody = await cloudResponse.text();
+		let answer = cloudBody;
+		let cloudPayload;
+		try {
+			cloudPayload = JSON.parse(cloudBody);
+			answer = getDocsCloudAnswerFromPayload(cloudPayload);
+		} catch {}
+		return shouldStreamResponse ? createOpenAICompatibleSseResponse(answer) : Response.json(isPlainObject(cloudPayload) ? cloudPayload : { answer });
+	}
 	const retrievalStartedAt = Date.now();
 	const retrievalStartedAtIso = (/* @__PURE__ */ new Date()).toISOString();
 	const retrievalSpanId = createDocsAgentTraceId("span");
@@ -1923,6 +2341,7 @@ function createDocsAPI(options) {
 	const agentFeedbackConfig = resolveAgentFeedbackConfig(options?.feedback);
 	const i18n = resolveDocsI18n(options?.i18n ?? readI18nConfig(root));
 	const aiConfig = options?.ai ?? readAIConfig(root);
+	const cloudConfig = options?.cloud ?? readCloudConfig(root);
 	const searchConfig = options?.search;
 	const llmsConfig = resolveLlmsTxtConfig(options?.llmsTxt, readLlmsTxtConfig(root));
 	const sitemapConfig = options?.sitemap ?? readSitemapConfig(root);
@@ -2496,7 +2915,7 @@ function createDocsAPI(options) {
 				return Response.json({ error: "AI is not enabled. Set `ai: { enabled: true }` in your docs.config to enable it." }, { status: 404 });
 			}
 			const ctx = resolveContextFromRequest(request);
-			return handleAskAI(request, getIndexes(ctx), aiConfig, resolveAskAISearchRequestConfig({
+			return handleAskAI(request, getIndexes(ctx), aiConfig, cloudConfig, resolveAskAISearchRequestConfig({
 				search: searchConfig,
 				useMcp: aiConfig.useMcp,
 				mcpEndpoint: mcpConfig.route,

package/dist/docs-cloud-ai-client.mjs

@@ -0,0 +1,44 @@
+//#region src/docs-cloud-ai-client.ts
+const DEFAULT_DOCS_API_ROUTE = "/api/docs";
+const DEFAULT_DOCS_CLOUD_API_BASE_URL = "https://docs-app.farming-labs.dev";
+const DEFAULT_PUBLIC_DOCS_CLOUD_API_KEY_ENV = "NEXT_PUBLIC_DOCS_CLOUD_API_KEY";
+function readRuntimeEnv(name) {
+	const value = process.env[name]?.trim();
+	return value ? value : void 0;
+}
+function resolveDocsCloudApiBaseUrl() {
+	return (readRuntimeEnv("NEXT_PUBLIC_DOCS_CLOUD_URL") ?? readRuntimeEnv("DOCS_CLOUD_API_URL") ?? DEFAULT_DOCS_CLOUD_API_BASE_URL).replace(/\/+$/, "");
+}
+function resolveDocsCloudProjectId() {
+	return readRuntimeEnv("NEXT_PUBLIC_DOCS_CLOUD_PROJECT_ID") ?? readRuntimeEnv("DOCS_CLOUD_PROJECT_ID");
+}
+function resolvePublicDocsCloudApiKey(config) {
+	const configuredEnv = config.cloud?.apiKey?.env?.trim();
+	if (!configuredEnv) return readRuntimeEnv(DEFAULT_PUBLIC_DOCS_CLOUD_API_KEY_ENV);
+	if (!configuredEnv.startsWith("NEXT_PUBLIC_")) return void 0;
+	return readRuntimeEnv(configuredEnv);
+}
+function resolveDocsCloudAIStream(config) {
+	const aiConfig = config.ai;
+	const stream = aiConfig?.stream ?? aiConfig?.streaming;
+	return typeof stream === "boolean" ? stream : true;
+}
+function resolveDocsCloudAIClientRequest(config, fallbackApi = DEFAULT_DOCS_API_ROUTE) {
+	if (config.ai?.provider !== "docs-cloud") return { api: fallbackApi };
+	const projectId = resolveDocsCloudProjectId();
+	const apiKey = resolvePublicDocsCloudApiKey(config);
+	const requestStream = resolveDocsCloudAIStream(config);
+	if (!projectId || !apiKey) return {
+		api: fallbackApi,
+		requestStream
+	};
+	return {
+		api: `${resolveDocsCloudApiBaseUrl()}/v1/projects/${encodeURIComponent(projectId)}/knowledge/ask`,
+		requestMode: "docs-cloud",
+		requestStream,
+		requestHeaders: { Authorization: `Bearer ${apiKey}` }
+	};
+}
+
+//#endregion
+export { resolveDocsCloudAIClientRequest };

package/dist/docs-layout.mjs

@@ -2,6 +2,7 @@ import { serializeIcon } from "./serialize-icon.mjs";
 import { withLangInUrl } from "./i18n.mjs";
 import { DocsPageClient } from "./docs-page-client.mjs";
 import { DocsAIFeatures } from "./docs-ai-features.mjs";
+import { resolveDocsCloudAIClientRequest } from "./docs-cloud-ai-client.mjs";
 import { DocsCommandSearch } from "./docs-command-search.mjs";
 import { resolveOpenDocsProviders } from "./open-docs-providers.mjs";
 import { resolvePageReadingTime, resolveReadingTimeOptions } from "./reading-time.mjs";
@@ -632,6 +633,7 @@ function createDocsLayout(config, options) {
 	const i18n = resolveDocsI18nConfig(getDocsI18n(config));
 	const activeLocale = localeContext.locale ?? i18n?.defaultLocale;
 	const docsApiUrl = withLangInUrl("/api/docs", activeLocale);
+	const aiClientRequest = resolveDocsCloudAIClientRequest(config, docsApiUrl);
 	const changelogConfig = resolveChangelogConfig(config.changelog);
 	const changelogBasePath = changelogConfig.enabled ? publicDocsRoute(localeContext, [changelogConfig.path]) : void 0;
 	const navTitle = config.nav?.title ?? "Docs";
@@ -758,7 +760,10 @@ function createDocsLayout(config, options) {
 					fallback: null,
 					children: /* @__PURE__ */ jsx(DocsAIFeatures, {
 						mode: aiMode,
-						api: docsApiUrl,
+						api: aiClientRequest.api,
+						requestMode: aiClientRequest.requestMode,
+						requestHeaders: aiClientRequest.requestHeaders,
+						requestStream: aiClientRequest.requestStream,
 						locale: activeLocale,
 						position: aiPosition,
 						floatingStyle: aiFloatingStyle,

package/dist/tanstack-layout.mjs

@@ -2,6 +2,7 @@ import { withLangInUrl } from "./i18n.mjs";
 import { escapeJsonLdForScript } from "./json-ld.mjs";
 import { DocsPageClient } from "./docs-page-client.mjs";
 import { DocsAIFeatures } from "./docs-ai-features.mjs";
+import { resolveDocsCloudAIClientRequest } from "./docs-cloud-ai-client.mjs";
 import { DocsCommandSearch } from "./docs-command-search.mjs";
 import { resolveOpenDocsProviders } from "./open-docs-providers.mjs";
 import { resolveReadingTimeOptions } from "./reading-time.mjs";
@@ -220,6 +221,7 @@ function TanstackDocsLayout({ config, tree, locale, description, readingTime, la
 	const tocStyle = tocConfig?.style;
 	const analyticsEnabled = resolveDocsAnalyticsConfig(config.analytics).enabled;
 	const docsApiUrl = withLangInUrl("/api/docs", locale);
+	const aiClientRequest = resolveDocsCloudAIClientRequest(config, docsApiUrl);
 	const navTitle = config.nav?.title ?? "Docs";
 	const navUrl = withLangInUrl(config.nav?.url ?? `/${config.entry ?? "docs"}`, locale);
 	const themeSwitch = resolveThemeSwitch(config.themeToggle);
@@ -327,7 +329,10 @@ function TanstackDocsLayout({ config, tree, locale, description, readingTime, la
 				fallback: null,
 				children: /* @__PURE__ */ jsx(DocsAIFeatures, {
 					mode: aiMode,
-					api: docsApiUrl,
+					api: aiClientRequest.api,
+					requestMode: aiClientRequest.requestMode,
+					requestHeaders: aiClientRequest.requestHeaders,
+					requestStream: aiClientRequest.requestStream,
 					locale,
 					position: aiPosition,
 					floatingStyle: aiFloatingStyle,

package/dist/threadline/index.mjs

@@ -140,7 +140,7 @@ const threadlinePageActions = {
 				name: "T3 Chat",
 				urlTemplate: "https://t3.chat/new?q={prompt}",
 				promptUrlTemplate: "https://t3.chat/new?q={prompt}",
-				icon: `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" aria-hidden="true"><path d="M4.5 5.5h15v9.75h-7.2L8 19.25v-4H4.5V5.5Z" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.8"/><path d="M8 9h8M8 12h5.5" stroke="currentColor" stroke-linecap="round" stroke-width="1.8"/></svg>`
+				icon: `<svg width="16" height="16" viewBox="0 0 512 512" fill="none" aria-hidden="true"><path fill="var(--color-fd-foreground, currentColor)" d="M115.3 407.6c-4.7 2.7-10.4-1.1-9.7-6.5l11.7-87.8C100.9 292.3 92 267.9 92 242c0-80.7 83.7-146.2 187-146.2S466 161.3 466 242 382.3 388.2 279 388.2c-28.2 0-55-4.9-78.9-13.6l-84.8 33Z"/></svg>`
 			}
 		]
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/theme",
-  "version": "0.1.144",
+  "version": "0.2.0",
   "description": "Theme package for @farming-labs/docs — layout, provider, MDX components, and styles",
   "keywords": [
     "docs",
@@ -145,7 +145,7 @@
     "tsdown": "^0.20.3",
     "typescript": "^5.9.3",
     "vitest": "^4.1.8",
-    "@farming-labs/docs": "0.1.144"
+    "@farming-labs/docs": "0.2.0"
   },
   "peerDependencies": {
     "@farming-labs/docs": ">=0.0.1",

package/styles/ai.css

@@ -777,20 +777,32 @@
 
 /* ─── Streaming cursor ───────────────────────────────────────────── */
 
+.fd-ai-streaming {
+  text-rendering: optimizeLegibility;
+}
+
 .fd-ai-streaming::after {
   content: "";
   display: inline-block;
   width: 2px;
-  height: 1em;
+  height: 0.95em;
   background: var(--color-fd-primary, #6366f1);
-  margin-left: 2px;
+  border-radius: 999px;
+  margin-left: 3px;
   vertical-align: text-bottom;
-  animation: fd-ai-cursor-blink 0.8s step-end infinite;
+  animation: fd-ai-cursor-blink 900ms ease-in-out infinite;
+  box-shadow: 0 0 10px color-mix(in srgb, var(--color-fd-primary, #6366f1) 35%, transparent);
 }
 
 @keyframes fd-ai-cursor-blink {
   0%, 100% { opacity: 1; }
-  50% { opacity: 0; }
+  50% { opacity: 0.25; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .fd-ai-streaming::after {
+    animation: none;
+  }
 }
 
 /* ─── Floating trigger button ────────────────────────────────────── */