@farming-labs/theme 0.2.75 → 0.2.78

package/dist/docs-api.mjs

@@ -4,8 +4,8 @@ import { BoundedRouteCache } from "./bounded-route-cache.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
-import { DEFAULT_A2A_AGENT_CARD_ROUTE, DEFAULT_AGENT_SKILLS_ARCHIVE_ROUTE_PATTERN, DEFAULT_AGENT_SKILLS_INDEX_ROUTE, DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, DEFAULT_API_CATALOG_ROUTE, DEFAULT_LEGACY_SKILLS_INDEX_ROUTE, DEFAULT_SITEMAP_MD_DOCS_ROUTE, DOCS_AGENT_MANIFEST_FORMAT, DOCS_AGENT_MANIFEST_SCHEMA_URI, DOCS_AGENT_MANIFEST_VERSION, DOCS_MARKDOWN_SECTION_INDEX_FORMAT, acceptsDocsMarkdown, buildDocsAskAIContext, buildDocsConfigMap, buildDocsDiagnostics, createDocsAgentTraceContext, createDocsAgentTraceId, createDocsMarkdownResponse, createDocsRobotsResponse, createDocsSitemapResponse, createDocsStandardsDiscoveryResponse, detectDocsMarkdownAgentRequest, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, emitDocsTelemetryAgentSurfaceEvent, emitDocsTelemetryProjectEvent, formatDocsAskAIPackageHints, getDocsAgentManifestLinkHeader, getDocsDiscoveryLinkHeader, getDocsLlmsTxtMaxCharsIssue, getDocsMcpProtectedResourceMetadataRoutes, hasDocsMarkdownSignatureAgent, inferDocsTelemetryAgentSurface, isDocsConfigRequest, isDocsDiagnosticsRequest, normalizeDocsRelated, normalizePageAgentFrontmatter, performDocsSearch, performDocsSearchWithMetadata, renderDocsLlmsTxt, renderDocsMarkdownDocument, resolveAskAISearchRequestConfig, resolveChangelogConfig, resolveDocsAgentContractMcpTools, resolveDocsAudienceMdxContent, resolveDocsI18n, resolveDocsLlmsTxtRequest, resolveDocsLlmsTxtSections, resolveDocsLocale, resolveDocsMetadataBaseUrl, resolveDocsPublishedAgentSkill, resolveDocsRequestApiRoute, resolveDocsRetrievalLastModified, resolveDocsSearchAudience, resolveDocsSearchFilters, resolveDocsSitemapConfig, resolveDocsStandardsDiscoveryRequest, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig, selectDocsLlmsTxtContent, stripGeneratedAgentProvenance } from "@farming-labs/docs";
-import { buildApiReferenceOpenApiDocumentAsync, createDocsMcpHttpHandler, createFilesystemDocsMcpSource, readDocsSitemapManifest, resolveApiReferenceConfig, resolveConfiguredAgentSkills, resolveDocsMcpConfig } from "@farming-labs/docs/server";
+import { DEFAULT_A2A_AGENT_CARD_ROUTE, DEFAULT_AGENT_SKILLS_ARCHIVE_ROUTE_PATTERN, DEFAULT_AGENT_SKILLS_INDEX_ROUTE, DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, DEFAULT_API_CATALOG_ROUTE, DEFAULT_LEGACY_SKILLS_INDEX_ROUTE, DEFAULT_SITEMAP_MD_DOCS_ROUTE, DOCS_AGENT_MANIFEST_FORMAT, DOCS_AGENT_MANIFEST_SCHEMA_URI, DOCS_AGENT_MANIFEST_VERSION, DOCS_CONTENT_CHANGES_FORMAT, DOCS_CONTENT_CHANGES_RESPONSE_VALUE, DOCS_MARKDOWN_SECTION_INDEX_FORMAT, acceptsDocsMarkdown, buildDocsAskAIContext, buildDocsConfigMap, buildDocsDiagnostics, buildDocsSearchFacets, createDocsAgentTraceContext, createDocsAgentTraceId, createDocsContentChangeFeed, createDocsContentChangesHttpResponse, createDocsMarkdownResponse, createDocsRobotsResponse, createDocsSitemapResponse, createDocsStandardsDiscoveryResponse, detectDocsMarkdownAgentRequest, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, emitDocsTelemetryAgentSurfaceEvent, emitDocsTelemetryProjectEvent, formatDocsAskAIPackageHints, getDocsAgentManifestLinkHeader, getDocsDiscoveryLinkHeader, getDocsLlmsTxtMaxCharsIssue, getDocsMcpProtectedResourceMetadataRoutes, hasDocsMarkdownSignatureAgent, inferDocsTelemetryAgentSurface, isDocsConfigRequest, isDocsContentChangesRequest, isDocsDiagnosticsRequest, normalizeDocsRelated, normalizePageAgentFrontmatter, performDocsSearch, performDocsSearchWithMetadata, renderDocsLlmsTxt, renderDocsMarkdownDocument, resolveAskAISearchRequestConfig, resolveChangelogConfig, resolveDocsAgentContractMcpTools, resolveDocsAudienceMdxContent, resolveDocsContentChangesConfig, resolveDocsI18n, resolveDocsLlmsTxtRequest, resolveDocsLlmsTxtSections, resolveDocsLocale, resolveDocsMetadataBaseUrl, resolveDocsPublishedAgentSkill, resolveDocsRequestApiRoute, resolveDocsRetrievalLastModified, resolveDocsSearchAudience, resolveDocsSearchError, resolveDocsSearchRequest, resolveDocsSitemapConfig, resolveDocsStandardsDiscoveryRequest, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig, selectDocsLlmsTxtContent, stripGeneratedAgentProvenance } from "@farming-labs/docs";
+import { buildApiReferenceOpenApiDocumentAsync, createDocsMcpHttpHandler, createFilesystemDocsMcpSource, readDocsSitemapManifest, resolveApiReferenceOpenApiDiscovery, resolveConfiguredAgentSkills, resolveDocsMcpConfig } from "@farming-labs/docs/server";
 
 //#region src/docs-api.ts
 /**
@@ -197,22 +197,11 @@ function isRobotsDiscoveryEnabled(robots) {
 function isApiReferenceOpenApiRequest(url) {
 	return url.searchParams.get("format")?.trim() === "openapi";
 }
-function resolveApiReferenceOpenApiDiscovery(value) {
-	const apiReference = resolveApiReferenceConfig(value);
-	if (!apiReference.enabled) return { enabled: false };
-	return {
-		enabled: true,
-		url: `${DEFAULT_DOCS_API_ROUTE}?format=openapi`,
-		urlSource: "default",
-		source: apiReference.specUrl ? "configured" : "generated",
-		specUrl: apiReference.specUrl,
-		apiReferencePath: `/${apiReference.path}`
-	};
-}
-function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp, feedback, llms, sitemap, robots, openapi, publishedSkills = [], agentCard }) {
+function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, contentChanges, mcp, feedback, llms, sitemap, robots, openapi, publishedSkills = [], agentCard }) {
 	const normalizedEntry = normalizePathSegment(entry) || "docs";
 	const localesEnabled = i18n !== null;
 	const searchEnabled = isSearchEnabled(search);
+	const contentChangesEnabled = resolveDocsContentChangesConfig(contentChanges).enabled;
 	const sitemapConfig = resolveDocsSitemapConfig(sitemap, { baseUrl: llms.baseUrl });
 	const robotsEnabled = isRobotsDiscoveryEnabled(robots);
 	const llmsSections = resolveDocsLlmsTxtSections(llms);
@@ -250,6 +239,7 @@ function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp
 			skills: true,
 			mcp: mcp.enabled,
 			search: searchEnabled,
+			contentChanges: contentChangesEnabled,
 			sitemap: sitemapConfig.enabled,
 			robots: robotsEnabled,
 			structuredData: true,
@@ -272,6 +262,7 @@ function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp
 			agentSpecQuery: `${apiRoute}?agent=spec`,
 			agents: `${apiRoute}?format=agents`,
 			openapi: `${apiRoute}?format=openapi`,
+			...contentChangesEnabled ? { contentChanges: `${apiRoute}?audience=agent&response=${DOCS_CONTENT_CHANGES_RESPONSE_VALUE}` } : {},
 			...apiCatalog ? {
 				apiCatalog: DEFAULT_API_CATALOG_ROUTE,
 				apiCatalogQuery: `${apiRoute}?format=api-catalog`
@@ -406,13 +397,16 @@ function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp
 			endpoint: `${apiRoute}?query={query}`,
 			agentEndpoint: `${apiRoute}?query={query}&audience=agent`,
 			structuredAgentEndpoint: `${apiRoute}?query={query}&audience=agent&response=structured`,
+			facetsEndpoint: `${apiRoute}?audience=agent&response=facets`,
 			method: "GET",
 			queryParam: "query",
 			localeParam: "lang",
 			audienceParam: "audience",
 			responseParam: "response",
 			structuredResponseValue: "structured",
+			facetsResponseValue: "facets",
 			responseFormat: "docs-search.v1",
+			facetsResponseFormat: "docs-search-facets.v1",
 			filterParams: {
 				framework: "framework",
 				version: "version",
@@ -426,9 +420,36 @@ function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp
 				"tags"
 			],
 			warningsField: "warnings",
+			facetParam: "facet",
+			limitParam: "limit",
+			cursorParam: "cursor",
+			nextCursorField: "nextCursor",
+			hasMoreField: "hasMore",
+			totalField: "total",
 			defaultAudience: "human",
 			supportedAudiences: ["human", "agent"]
 		},
+		contentChanges: {
+			enabled: contentChangesEnabled,
+			endpoint: contentChangesEnabled ? `${apiRoute}?audience=agent&response=${DOCS_CONTENT_CHANGES_RESPONSE_VALUE}` : null,
+			method: "GET",
+			audienceParam: "audience",
+			defaultAudience: "agent",
+			supportedAudiences: ["human", "agent"],
+			responseParam: "response",
+			responseValue: DOCS_CONTENT_CHANGES_RESPONSE_VALUE,
+			sinceParam: "since",
+			format: DOCS_CONTENT_CHANGES_FORMAT,
+			generationField: "indexGeneration",
+			resetRequiredField: "resetRequired",
+			modes: [
+				"snapshot",
+				"delta",
+				"reset"
+			],
+			bodyFree: true,
+			etag: true
+		},
 		agents: {
 			enabled: true,
 			file: "AGENTS.md",
@@ -1302,7 +1323,7 @@ function renderMarkdownDocument(page, options = {}) {
 		sitemap: options.sitemap
 	});
 }
-function renderSkillDocument({ origin, entry, apiRoute, apiCatalog, search, mcp, feedback, llms, sitemap, robots, openapi }) {
+function renderSkillDocument({ origin, entry, apiRoute, apiCatalog, search, contentChanges, mcp, feedback, llms, sitemap, robots, openapi }) {
 	const normalizedEntry = normalizePathSegment(entry) || "docs";
 	const siteTitle = compactSkillText(llms.siteTitle ?? "Documentation");
 	const siteDescription = llms.siteDescription ? compactSkillText(llms.siteDescription) : void 0;
@@ -1326,7 +1347,8 @@ function renderSkillDocument({ origin, entry, apiRoute, apiCatalog, search, mcp,
 	lines.push("", "## When To Use", "Use this skill when you need to read or implement against this documentation site.", "", "## Start Here", `- Fetch ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE}; fall back to ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE} or ${agentSpecRoute}.`);
 	if (apiCatalog) lines.push(`- Fetch ${DEFAULT_API_CATALOG_ROUTE} for the standards-based API catalog.`);
 	lines.push(`- Fetch ${DEFAULT_AGENT_SKILLS_INDEX_ROUTE} to discover the published site skill and verify its SHA-256 digest.`, `- Fetch /${normalizedEntry}.md for the root docs page.`, `- Fetch /${normalizedEntry}/{slug}.md for page-specific context.`, `- Fetch /${normalizedEntry}/{slug}.md?sections to list section IDs and size estimates before requesting ?section={id}.`, "- You can also request text/markdown from normal page URLs.");
-	if (searchEnabled) lines.push(`- Search with ${apiRoute}?query={query}&audience=agent&response=structured when you do not know the page; add framework, version, package, or repeated tags filters when scope matters.`);
+	if (searchEnabled) lines.push(`- Discover valid search filters with ${apiRoute}?audience=agent&response=facets before choosing framework, version, package, or tag values; continue a large field with facet={field}, limit={limit}, and its nextCursor.`, `- Search with ${apiRoute}?query={query}&audience=agent&response=structured when you do not know the page; add framework, version, package, or repeated tags filters when scope matters.`);
+	if (resolveDocsContentChangesConfig(contentChanges).enabled) lines.push(`- Synchronize changed documents with ${apiRoute}?audience=agent&response=${DOCS_CONTENT_CHANGES_RESPONSE_VALUE}; pass indexGeneration as since on the next request and clear stale state when resetRequired is true.`);
 	if (openapi.enabled && openapiUrl) lines.push(`- Fetch ${openapiUrl} for the machine-readable OpenAPI schema before scraping API reference pages.`);
 	if (llms.enabled) {
 		lines.push(`- Use ${DEFAULT_LLMS_TXT_ROUTE} for a compact docs index.`, `- Use ${DEFAULT_LLMS_FULL_TXT_ROUTE} for full markdown context.`);
@@ -1362,7 +1384,7 @@ function renderSkillDocument({ origin, entry, apiRoute, apiCatalog, search, mcp,
 	lines.push("", "## Reusable Framework Skills", "For framework setup, CLI, page actions, Ask AI, or configuration work, install the reusable Farming Labs skills:", "", "```sh", "npx skills add farming-labs/docs", "```");
 	return lines.join("\n");
 }
-function renderAgentsDocument({ origin, entry, apiRoute, apiCatalog, search, mcp, feedback, llms, sitemap, robots, openapi }) {
+function renderAgentsDocument({ origin, entry, apiRoute, apiCatalog, search, contentChanges, mcp, feedback, llms, sitemap, robots, openapi }) {
 	const normalizedEntry = normalizePathSegment(entry) || "docs";
 	const siteTitle = compactSkillText(llms.siteTitle ?? "Documentation");
 	const siteDescription = llms.siteDescription ? compactSkillText(llms.siteDescription) : void 0;
@@ -1391,7 +1413,8 @@ function renderAgentsDocument({ origin, entry, apiRoute, apiCatalog, search, mcp
 		if (sitemapConfig.xml.enabled) lines.push(`- Use ${sitemapConfig.xml.route} for canonical URLs and freshness metadata.`);
 	}
 	if (robotsEnabled) lines.push(`- Check ${DEFAULT_ROBOTS_TXT_ROUTE} before crawling broadly.`);
-	if (searchEnabled) lines.push(`- Search with ${apiRoute}?query={query}&audience=agent&response=structured when the route is unknown; add framework, version, package, or repeated tags filters when scope matters.`);
+	if (searchEnabled) lines.push(`- Discover valid search filters with ${apiRoute}?audience=agent&response=facets before choosing framework, version, package, or tag values; continue a large field with facet={field}, limit={limit}, and its nextCursor.`, `- Search with ${apiRoute}?query={query}&audience=agent&response=structured when the route is unknown; add framework, version, package, or repeated tags filters when scope matters.`);
+	if (resolveDocsContentChangesConfig(contentChanges).enabled) lines.push(`- Synchronize changed documents with ${apiRoute}?audience=agent&response=${DOCS_CONTENT_CHANGES_RESPONSE_VALUE}; pass indexGeneration as since on the next request and clear stale state when resetRequired is true.`);
 	if (openapi.enabled && openapiUrl) lines.push(`- Fetch ${openapiUrl} before scraping API reference pages; prefer schemas over prose.`);
 	if (mcp.enabled) lines.push(`- Use MCP at ${DEFAULT_MCP_PUBLIC_ROUTE} or ${DEFAULT_MCP_WELL_KNOWN_ROUTE} when your environment supports MCP tools.`);
 	if (feedback.enabled) lines.push(`- Read ${feedback.schemaRoute} before posting feedback to ${feedback.route}.`);
@@ -2462,8 +2485,10 @@ function readApiReferenceConfig(root) {
 			const pathMatch = block.match(/path\s*:\s*["']([^"']+)["']/);
 			const routeRootMatch = block.match(/routeRoot\s*:\s*["']([^"']+)["']/);
 			const specUrlMatch = block.match(/specUrl\s*:\s*["']([^"']+)["']/);
+			const catalogTargetsMatch = block.match(/catalogTargets\s*:\s*\[([\s\S]*?)\]/);
 			const rendererMatch = block.match(/renderer\s*:\s*["'](fumadocs|scalar)["']/);
 			const excludeMatch = block.match(/exclude\s*:\s*\[([\s\S]*?)\]/);
+			const catalogTargets = catalogTargetsMatch?.[1] === void 0 ? void 0 : Array.from(catalogTargetsMatch[1].matchAll(/["']([^"']+)["']/g)).map((match) => match[1]).filter(Boolean);
 			const exclude = excludeMatch?.[1] === void 0 ? void 0 : Array.from(excludeMatch[1].matchAll(/["']([^"']+)["']/g)).map((match) => match[1]).filter(Boolean);
 			const renderer = rendererMatch?.[1] === "fumadocs" || rendererMatch?.[1] === "scalar" ? rendererMatch[1] : void 0;
 			return {
@@ -2471,6 +2496,7 @@ function readApiReferenceConfig(root) {
 				path: pathMatch?.[1],
 				routeRoot: routeRootMatch?.[1],
 				specUrl: specUrlMatch?.[1],
+				catalogTargets,
 				renderer,
 				exclude
 			};
@@ -2532,6 +2558,8 @@ function createDocsAPI(options) {
 		apiRoute: configuredApiRoute
 	} : cloudConfig;
 	const searchConfig = options?.search;
+	const contentChangesConfig = resolveDocsContentChangesConfig(options?.agent?.contentChanges, { staticExport: options?.staticExport === true });
+	const contentChangeFeed = createDocsContentChangeFeed(options?.agent?.contentChanges);
 	const llmsConfig = resolveLlmsTxtConfig(options?.llmsTxt, readLlmsTxtConfig(root));
 	const apiCatalogEnabled = options?.apiCatalog ?? llmsConfig.apiCatalog ?? true;
 	const sitemapConfig = options?.sitemap ?? readSitemapConfig(root);
@@ -2564,6 +2592,7 @@ function createDocsAPI(options) {
 		contentDir,
 		telemetry: options?.telemetry,
 		search: searchConfig,
+		agent: options?.agent,
 		ai: aiConfig,
 		cloud: effectiveCloudConfig,
 		i18n: i18nConfig ?? void 0,
@@ -2585,6 +2614,7 @@ function createDocsAPI(options) {
 	setConfigMapFallback("entry", entry);
 	setConfigMapFallback("ai", Object.keys(aiConfig).length > 0 ? aiConfig : void 0);
 	setConfigMapFallback("search", searchConfig);
+	setConfigMapFallback("agent", options?.agent);
 	setConfigMapFallback("i18n", i18nConfig ?? void 0);
 	setConfigMapFallback("mcp", rawMcpConfig);
 	setConfigMapFallback("apiReference", apiReferenceConfig);
@@ -2782,6 +2812,7 @@ function createDocsAPI(options) {
 			apiCatalog: apiCatalogEnabled,
 			i18n,
 			search: searchConfig,
+			contentChanges: contentChangesConfig.enabled,
 			mcp: mcpConfig,
 			feedback: agentFeedbackConfig,
 			llms: llmsConfig,
@@ -2802,6 +2833,7 @@ function createDocsAPI(options) {
 			apiRoute,
 			i18n,
 			search: searchConfig,
+			contentChanges: contentChangesConfig.enabled,
 			mcp: mcpConfig,
 			feedback: agentFeedbackConfig,
 			llms: llmsConfig,
@@ -2867,6 +2899,7 @@ function createDocsAPI(options) {
 					apiCatalog: apiCatalogEnabled,
 					i18n,
 					search: searchConfig,
+					contentChanges: contentChangesConfig.enabled,
 					mcp: mcpConfig,
 					feedback: agentFeedbackConfig,
 					llms: llmsConfig,
@@ -2882,6 +2915,7 @@ function createDocsAPI(options) {
 							apiCatalog: apiCatalogEnabled,
 							i18n,
 							search: searchConfig,
+							contentChanges: contentChangesConfig.enabled,
 							mcp: mcpConfig,
 							feedback: agentFeedbackConfig,
 							llms: llmsConfig,
@@ -2897,6 +2931,23 @@ function createDocsAPI(options) {
 					"X-Robots-Tag": "noindex"
 				} });
 			}
+			if (isDocsContentChangesRequest(url)) {
+				if (!contentChangesConfig.enabled) return new Response("Not Found", {
+					status: 404,
+					headers: {
+						"Content-Type": "text/plain; charset=utf-8",
+						"X-Robots-Tag": "noindex"
+					}
+				});
+				return createDocsContentChangesHttpResponse({
+					request,
+					feed: contentChangeFeed,
+					pages: getIndexes(ctx),
+					search: searchConfig,
+					locale: ctx.locale,
+					baseUrl: markdownMetadataBaseUrl || url.origin
+				});
+			}
 			if (isApiReferenceOpenApiRequest(url)) {
 				if (!openapiDiscovery.enabled) return new Response("Not Found", {
 					status: 404,
@@ -2962,6 +3013,7 @@ function createDocsAPI(options) {
 					apiRoute: requestApiRoute,
 					apiCatalog: apiCatalogEnabled,
 					search: searchConfig,
+					contentChanges: contentChangesConfig.enabled,
 					mcp: mcpConfig,
 					feedback: agentFeedbackConfig,
 					llms: llmsConfig,
@@ -2994,6 +3046,7 @@ function createDocsAPI(options) {
 					apiCatalog: apiCatalogEnabled,
 					i18n,
 					search: searchConfig,
+					contentChanges: contentChangesConfig.enabled,
 					mcp: mcpConfig,
 					feedback: agentFeedbackConfig,
 					llms: llmsConfig,
@@ -3166,9 +3219,16 @@ function createDocsAPI(options) {
 			}
 			const query = url.searchParams.get("query")?.trim();
 			const audience = resolveDocsSearchAudience(url.searchParams.get("audience"));
-			const filters = resolveDocsSearchFilters(url.searchParams);
-			const structured = url.searchParams.get("response") === "structured";
-			if (!query && !structured) return new Response("[]", { headers: { "Content-Type": "application/json" } });
+			let searchRequest;
+			try {
+				searchRequest = resolveDocsSearchRequest(url.searchParams);
+			} catch (error) {
+				const searchError = resolveDocsSearchError(error);
+				if (!searchError) throw error;
+				return Response.json({ error: searchError }, { status: 400 });
+			}
+			const { filters, structured, facets, facet, cursor, limit } = searchRequest;
+			if (!query && !structured && !facets) return new Response("[]", { headers: { "Content-Type": "application/json" } });
 			const searchOptions = {
 				pages: getIndexes(ctx),
 				query: query ?? "",
@@ -3179,19 +3239,27 @@ function createDocsAPI(options) {
 				pathname: url.searchParams.get("pathname") ?? void 0,
 				siteTitle: llmsConfig.siteTitle ?? "Documentation",
 				baseUrl: markdownMetadataBaseUrl || url.origin,
-				syncBaseUrl: markdownMetadataBaseUrl ?? null
+				syncBaseUrl: markdownMetadataBaseUrl ?? null,
+				facet,
+				cursor,
+				limit
 			};
-			if (!query) {
-				const searchResponse = structured ? await performDocsSearchWithMetadata(searchOptions) : [];
-				return new Response(JSON.stringify(searchResponse), { headers: { "Content-Type": "application/json" } });
-			}
 			const searchStartedAt = Date.now();
-			const searchResponse = structured ? await performDocsSearchWithMetadata(searchOptions) : await performDocsSearch(searchOptions);
-			const resultCount = Array.isArray(searchResponse) ? searchResponse.length : searchResponse.resultCount;
+			let searchResponse;
+			try {
+				searchResponse = facets ? await buildDocsSearchFacets(searchOptions) : structured ? await performDocsSearchWithMetadata(searchOptions) : query ? await performDocsSearch(searchOptions) : [];
+			} catch (error) {
+				const searchError = resolveDocsSearchError(error);
+				if (!searchError) throw error;
+				return Response.json({ error: searchError }, { status: 400 });
+			}
+			if (facets) return Response.json(searchResponse, { headers: { "Cache-Control": "public, max-age=60, stale-while-revalidate=300" } });
+			if (!query) return Response.json(searchResponse);
+			const resultCount = Array.isArray(searchResponse) ? searchResponse.length : "resultCount" in searchResponse ? searchResponse.resultCount : searchResponse.matchedPageCount;
 			await emitDocsAnalyticsEvent(analytics, {
 				type: "api_search",
 				source: "server",
-				url: request.url,
+				url: `${url.origin}${url.pathname}`,
 				path: url.pathname,
 				locale: ctx.locale,
 				input: { query },

package/package.json

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