@farming-labs/docs 0.2.120 → 0.2.121

package/dist/telemetry-runtime.mjs

@@ -0,0 +1,238 @@
+//#region src/telemetry-runtime.ts
+const DOCS_PACKAGE_NAME = "@farming-labs/docs";
+const DOCS_PACKAGE_VERSION = "0.2.25";
+const DEFAULT_DOCS_TELEMETRY_ENDPOINT = "https://docs.farming-labs.dev/api/telemetry/events";
+function getRuntimeEnv() {
+	if (typeof process === "undefined" || !process.env) return;
+	return process.env;
+}
+function readRuntimeEnv(name) {
+	const value = getRuntimeEnv()?.[name]?.trim();
+	return value ? value : void 0;
+}
+function isTruthyEnv(value) {
+	return /^(1|true|yes|on)$/i.test(value ?? "");
+}
+function isFalsyEnv(value) {
+	return /^(0|false|no|off)$/i.test(value ?? "");
+}
+function isBrowserRuntime() {
+	return typeof window !== "undefined" && typeof document !== "undefined";
+}
+function isProductionTelemetryRuntime() {
+	if (isBrowserRuntime()) return false;
+	const env = getRuntimeEnv();
+	if (!env) return true;
+	if (env.NODE_ENV === "test") return false;
+	if (env.VERCEL_ENV === "production") return true;
+	if (env.CONTEXT === "production" && isTruthyEnv(env.NETLIFY)) return true;
+	if (isTruthyEnv(env.CF_PAGES)) return true;
+	if (env.RENDER_SERVICE_ID || env.FLY_APP_NAME || env.RAILWAY_ENVIRONMENT) return true;
+	return env.NODE_ENV === "production";
+}
+function resolveDocsTelemetryConfig(telemetry) {
+	const envToggle = readRuntimeEnv("DOCS_TELEMETRY");
+	const envDisabled = readRuntimeEnv("DOCS_TELEMETRY_DISABLED");
+	if (isFalsyEnv(envToggle) || isTruthyEnv(envDisabled) || telemetry === false) return { enabled: false };
+	const objectConfig = telemetry && typeof telemetry === "object" ? telemetry : void 0;
+	if (objectConfig?.enabled === false) return { enabled: false };
+	return {
+		enabled: telemetry === true || objectConfig?.enabled === true || isTruthyEnv(envToggle) || isProductionTelemetryRuntime(),
+		endpoint: objectConfig?.endpoint?.trim() || readRuntimeEnv("DOCS_TELEMETRY_ENDPOINT") || DEFAULT_DOCS_TELEMETRY_ENDPOINT
+	};
+}
+function readRequestOrigin(request) {
+	if (!request?.url) return void 0;
+	try {
+		return new URL(request.url).origin;
+	} catch {
+		return;
+	}
+}
+/** Normalize an HTTP(S) telemetry site value to its origin. */
+function normalizeDocsTelemetryOrigin(candidate) {
+	if (typeof candidate !== "string") return void 0;
+	const trimmed = candidate.trim();
+	if (!trimmed) return void 0;
+	try {
+		const hasScheme = /^[a-z][a-z\d+.-]*:(?!\d)/i.test(trimmed);
+		const url = new URL(hasScheme ? trimmed : `https://${trimmed}`);
+		if (url.protocol !== "http:" && url.protocol !== "https:") return void 0;
+		return url.origin;
+	} catch {
+		return;
+	}
+}
+/** Return whether a telemetry origin points at a local development server. */
+function isLocalDocsTelemetryOrigin(candidate) {
+	const origin = normalizeDocsTelemetryOrigin(candidate);
+	if (!origin) return false;
+	const hostname = new URL(origin).hostname.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.+$/, "");
+	if ([
+		"localhost",
+		"localhost.localdomain",
+		"localhost6",
+		"localhost6.localdomain6",
+		"ip6-localhost",
+		"ip6-loopback"
+	].includes(hostname) || hostname.endsWith(".localhost")) return true;
+	if (hostname === "::" || hostname === "::1") return true;
+	const ipv4 = hostname.split(".").map((part) => Number(part));
+	if (ipv4.length === 4 && ipv4.every((part) => Number.isInteger(part) && part >= 0 && part <= 255)) return ipv4[0] === 127 || ipv4.every((part) => part === 0);
+	return /^::ffff:7f[0-9a-f]{2}:/.test(hostname) || hostname === "::ffff:0:0";
+}
+function isBlockedDocsTelemetryOrigin(candidate) {
+	if (candidate === void 0) return false;
+	return !normalizeDocsTelemetryOrigin(candidate) || isLocalDocsTelemetryOrigin(candidate);
+}
+function readDeploymentOrigin() {
+	const candidates = [
+		readRuntimeEnv("DOCS_SITE_URL"),
+		readRuntimeEnv("NEXT_PUBLIC_BASE_URL"),
+		readRuntimeEnv("NEXT_PUBLIC_SITE_URL"),
+		readRuntimeEnv("SITE_URL"),
+		readRuntimeEnv("URL"),
+		readRuntimeEnv("CF_PAGES_URL"),
+		readRuntimeEnv("VERCEL_PROJECT_PRODUCTION_URL"),
+		readRuntimeEnv("VERCEL_URL"),
+		readRuntimeEnv("DEPLOY_PRIME_URL")
+	];
+	for (const candidate of candidates) {
+		const origin = normalizeDocsTelemetryOrigin(candidate);
+		if (origin) return origin;
+	}
+}
+function detectDeployment() {
+	const env = getRuntimeEnv();
+	if (!env) return void 0;
+	if (env.VERCEL || env.VERCEL_ENV) return {
+		provider: "vercel",
+		environment: env.VERCEL_ENV,
+		id: env.VERCEL_DEPLOYMENT_ID ?? env.VERCEL_GIT_COMMIT_SHA,
+		region: env.VERCEL_REGION
+	};
+	if (env.NETLIFY) return {
+		provider: "netlify",
+		environment: env.CONTEXT,
+		id: env.DEPLOY_ID ?? env.COMMIT_REF
+	};
+	if (env.CF_PAGES) return {
+		provider: "cloudflare-pages",
+		environment: env.CF_PAGES_BRANCH,
+		id: env.CF_PAGES_COMMIT_SHA
+	};
+	if (env.RENDER_SERVICE_ID) return {
+		provider: "render",
+		environment: env.RENDER_ENV,
+		id: env.RENDER_SERVICE_ID
+	};
+	if (env.FLY_APP_NAME) return {
+		provider: "fly",
+		environment: env.FLY_APP_NAME,
+		id: env.FLY_ALLOC_ID,
+		region: env.FLY_REGION
+	};
+	if (env.RAILWAY_ENVIRONMENT) return {
+		provider: "railway",
+		environment: env.RAILWAY_ENVIRONMENT,
+		id: env.RAILWAY_DEPLOYMENT_ID
+	};
+	return env.NODE_ENV === "production" ? { environment: "production" } : void 0;
+}
+function detectRuntime() {
+	if (typeof process !== "undefined" && process.versions?.node) return {
+		name: "node",
+		version: process.versions.node
+	};
+	if (typeof navigator !== "undefined" && navigator.userAgent) return { name: "web-standard" };
+}
+function createDocsTelemetryEvent(config, input, context = {}, resolveFeatures) {
+	const telemetryConfig = config.telemetry && typeof config.telemetry === "object" ? config.telemetry : void 0;
+	const siteOriginCandidates = [
+		context.siteOrigin,
+		input.site?.origin,
+		telemetryConfig?.siteOrigin,
+		readRequestOrigin(context.request),
+		readDeploymentOrigin()
+	];
+	if (siteOriginCandidates.some(isBlockedDocsTelemetryOrigin)) return void 0;
+	const siteOrigin = siteOriginCandidates.map(normalizeDocsTelemetryOrigin).find((origin) => Boolean(origin));
+	const deployment = input.deployment ?? detectDeployment();
+	const properties = context.properties || input.properties ? {
+		...input.properties,
+		...context.properties
+	} : void 0;
+	return {
+		...input,
+		timestamp: input.timestamp ?? (/* @__PURE__ */ new Date()).toISOString(),
+		package: {
+			name: DOCS_PACKAGE_NAME,
+			version: DOCS_PACKAGE_VERSION,
+			...input.package
+		},
+		framework: input.framework ?? context.framework,
+		runtime: input.runtime ?? detectRuntime(),
+		site: siteOrigin ? { origin: siteOrigin } : input.site,
+		deployment,
+		features: input.features ?? resolveFeatures?.() ?? {},
+		properties
+	};
+}
+async function emitDocsTelemetryEvent(telemetry, event) {
+	const resolved = resolveDocsTelemetryConfig(telemetry);
+	const eventSiteOrigin = event.site?.origin;
+	const normalizedSiteOrigin = normalizeDocsTelemetryOrigin(eventSiteOrigin);
+	if (!resolved.enabled || !resolved.endpoint || typeof fetch !== "function" || eventSiteOrigin !== void 0 && (!normalizedSiteOrigin || isLocalDocsTelemetryOrigin(eventSiteOrigin))) return;
+	const eventToSend = normalizedSiteOrigin ? {
+		...event,
+		site: { origin: normalizedSiteOrigin }
+	} : event;
+	try {
+		const ingestKey = readRuntimeEnv("DOCS_TELEMETRY_INGEST_KEY");
+		const browserRequest = isBrowserRuntime() && !ingestKey;
+		const headers = { "content-type": browserRequest ? "text/plain;charset=UTF-8" : "application/json" };
+		if (ingestKey) headers["x-docs-telemetry-key"] = ingestKey;
+		await fetch(resolved.endpoint, {
+			method: "POST",
+			headers,
+			body: JSON.stringify({ event: eventToSend }),
+			keepalive: true,
+			...browserRequest ? {
+				credentials: "omit",
+				mode: "no-cors"
+			} : {}
+		});
+	} catch {}
+}
+/**
+* Emit a privacy-preserving browser page view for the maintainer telemetry dashboard.
+*
+* Page views include only the public site origin, pathname, locale, framework, and package
+* metadata. They never include a query string, referrer, visitor id, IP address, or user agent.
+*/
+function emitDocsTelemetryPageViewEvent(telemetry, context = {}) {
+	if (telemetry === false || telemetry && typeof telemetry === "object" && telemetry.enabled === false) return;
+	const runtimeSiteOrigin = context.siteOrigin ?? (typeof window !== "undefined" ? window.location?.origin : void 0);
+	if (isBlockedDocsTelemetryOrigin(runtimeSiteOrigin)) return;
+	const siteOrigin = (telemetry && typeof telemetry === "object" ? telemetry.siteOrigin : void 0) ?? runtimeSiteOrigin;
+	const event = createDocsTelemetryEvent({ telemetry }, {
+		type: "page_view",
+		features: {},
+		properties: {
+			trafficType: "human",
+			...context.path ? { path: context.path.slice(0, 2048) } : {},
+			...context.locale ? { locale: context.locale.slice(0, 80) } : {}
+		}
+	}, {
+		framework: context.framework,
+		siteOrigin
+	});
+	if (!event) return;
+	emitDocsTelemetryEvent(telemetry && typeof telemetry === "object" ? {
+		...telemetry,
+		enabled: true
+	} : true, event);
+}
+
+//#endregion
+export { createDocsTelemetryEvent, emitDocsTelemetryEvent, emitDocsTelemetryPageViewEvent, isLocalDocsTelemetryOrigin, normalizeDocsTelemetryOrigin, resolveDocsTelemetryConfig };

package/dist/telemetry.d.mts

@@ -0,0 +1,15 @@
+import { DocsConfig, DocsTelemetryAgentSurface, DocsTelemetryFeatures } from "./types.mjs";
+import { DocsTelemetryAgentSurfaceContext, DocsTelemetryAgentSurfaceRequestOptions, DocsTelemetryContext, DocsTelemetryPageViewContext, ResolvedDocsTelemetryConfig, emitDocsTelemetryEvent, emitDocsTelemetryPageViewEvent, isLocalDocsTelemetryOrigin, normalizeDocsTelemetryOrigin, resolveDocsTelemetryConfig } from "./telemetry-runtime.mjs";
+
+//#region src/telemetry.d.ts
+declare function getDocsTelemetryFeatures(config: Partial<DocsConfig>): DocsTelemetryFeatures;
+declare function emitDocsTelemetryProjectEvent(config: Partial<DocsConfig>, context?: DocsTelemetryContext): void;
+declare function emitDocsTelemetryAgentSurfaceEvent(config: Partial<DocsConfig>, context: DocsTelemetryAgentSurfaceContext): void;
+declare function emitDocsTelemetryMcpToolEvent(config: Partial<DocsConfig>, context: DocsTelemetryContext & {
+  tool: string;
+  locale?: string;
+  resultCount?: number;
+}): void;
+declare function inferDocsTelemetryAgentSurface(request: Request, options: DocsTelemetryAgentSurfaceRequestOptions): DocsTelemetryAgentSurface | undefined;
+//#endregion
+export { emitDocsTelemetryAgentSurfaceEvent, emitDocsTelemetryMcpToolEvent, emitDocsTelemetryProjectEvent, getDocsTelemetryFeatures, inferDocsTelemetryAgentSurface };

package/dist/telemetry.mjs

@@ -0,0 +1,117 @@
+import { isDocsContentChangesRequest, resolveDocsContentChangesConfig } from "./content-changes.mjs";
+import { isDocsAgentDiscoveryRequest, isDocsAgentsRequest, isDocsSkillRequest, resolveDocsAgentFeedbackConfig, resolveDocsAgentFeedbackRequest, resolveDocsAgentsFormat, resolveDocsLlmsTxtRequest, resolveDocsMarkdownRequest, resolveDocsSkillFormat } from "./agent.mjs";
+import { createDocsTelemetryEvent, emitDocsTelemetryEvent, emitDocsTelemetryPageViewEvent, isLocalDocsTelemetryOrigin, normalizeDocsTelemetryOrigin, resolveDocsTelemetryConfig } from "./telemetry-runtime.mjs";
+
+//#region src/telemetry.ts
+const PROJECT_TELEMETRY_CACHE_TTL_MS = 1440 * 60 * 1e3;
+const PROJECT_TELEMETRY_CACHE_MAX_KEYS = 256;
+function isObjectConfigEnabled(value, defaultEnabled) {
+	if (value === false) return false;
+	if (value === true) return true;
+	if (value && typeof value === "object" && !Array.isArray(value)) {
+		const enabled = value.enabled;
+		return enabled === false ? false : defaultEnabled || enabled === true;
+	}
+	return defaultEnabled;
+}
+function hasObjectConfig(value) {
+	return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function getDocsTelemetryFeatures(config) {
+	const pageActions = config.pageActions;
+	const feedback = config.feedback;
+	return {
+		search: isObjectConfigEnabled(config.search, true),
+		contentChanges: resolveDocsContentChangesConfig(config.agent?.contentChanges, { staticExport: config.staticExport === true }).enabled,
+		ai: isObjectConfigEnabled(config.ai, false),
+		mcp: isObjectConfigEnabled(config.mcp, true),
+		llmsTxt: isObjectConfigEnabled(config.llmsTxt, true),
+		pageActions: hasObjectConfig(pageActions),
+		feedback: feedback === true || hasObjectConfig(feedback) && feedback.enabled !== false,
+		agentFeedback: feedback !== false && !(hasObjectConfig(feedback) && feedback.agent === false) && !(hasObjectConfig(feedback) && hasObjectConfig(feedback.agent) && feedback.agent.enabled === false),
+		sitemap: isObjectConfigEnabled(config.sitemap, true),
+		robots: isObjectConfigEnabled(config.robots, true),
+		apiReference: isObjectConfigEnabled(config.apiReference, false),
+		staticExport: config.staticExport === true,
+		changelog: isObjectConfigEnabled(config.changelog, false),
+		cloud: typeof config.cloud !== "undefined" && isObjectConfigEnabled(config.cloud, true),
+		review: isObjectConfigEnabled(config.review, true),
+		codeBlocksValidate: hasObjectConfig(config.codeBlocks) && Boolean(config.codeBlocks.validate)
+	};
+}
+function projectEventKey(event) {
+	return [
+		event.package.name,
+		event.package.version,
+		event.framework ?? "",
+		event.site?.origin ?? "",
+		event.deployment?.provider ?? "",
+		event.deployment?.environment ?? "",
+		event.deployment?.id ?? ""
+	].join("|");
+}
+function getSentProjectKeys() {
+	const globalValue = globalThis;
+	globalValue.__farmingLabsDocsTelemetryProjectKeys__ ??= /* @__PURE__ */ new Map();
+	return globalValue.__farmingLabsDocsTelemetryProjectKeys__;
+}
+function pruneSentProjectKeys(sent, now) {
+	for (const [key, expiresAt] of sent) if (expiresAt <= now) sent.delete(key);
+	while (sent.size >= PROJECT_TELEMETRY_CACHE_MAX_KEYS) {
+		const oldestKey = sent.keys().next().value;
+		if (!oldestKey) return;
+		sent.delete(oldestKey);
+	}
+}
+function emitDocsTelemetryProjectEvent(config, context = {}) {
+	const event = createDocsTelemetryEvent(config, { type: "project_detected" }, context, () => getDocsTelemetryFeatures(config));
+	if (!event) return;
+	const key = projectEventKey(event);
+	const sent = getSentProjectKeys();
+	const now = Date.now();
+	const expiresAt = sent.get(key);
+	if (expiresAt && expiresAt > now) return;
+	if (typeof expiresAt === "number") sent.delete(key);
+	pruneSentProjectKeys(sent, now);
+	sent.set(key, now + PROJECT_TELEMETRY_CACHE_TTL_MS);
+	emitDocsTelemetryEvent(config.telemetry, event);
+}
+function emitDocsTelemetryAgentSurfaceEvent(config, context) {
+	const event = createDocsTelemetryEvent(config, {
+		type: context.surface === "mcp" ? "mcp_request" : "agent_surface_used",
+		properties: { surface: context.surface }
+	}, context, () => getDocsTelemetryFeatures(config));
+	if (!event) return;
+	emitDocsTelemetryEvent(config.telemetry, event);
+}
+function emitDocsTelemetryMcpToolEvent(config, context) {
+	const event = createDocsTelemetryEvent(config, {
+		type: "mcp_tool_used",
+		properties: {
+			tool: context.tool,
+			locale: context.locale,
+			resultCount: context.resultCount
+		}
+	}, context, () => getDocsTelemetryFeatures(config));
+	if (!event) return;
+	emitDocsTelemetryEvent(config.telemetry, event);
+}
+function inferDocsTelemetryAgentSurface(request, options) {
+	const url = new URL(request.url);
+	const method = request.method.toUpperCase();
+	const feedbackRequest = resolveDocsAgentFeedbackRequest(url, resolveDocsAgentFeedbackConfig(options.feedback));
+	if ((method === "GET" || method === "HEAD") && isDocsAgentDiscoveryRequest(url)) return "agent_spec";
+	if ((method === "GET" || method === "HEAD") && feedbackRequest?.kind === "schema") return "agent_feedback_schema";
+	if (method === "POST" && feedbackRequest?.kind === "submit") return "agent_feedback_submit";
+	if (method === "GET" || method === "HEAD") {
+		if (isDocsContentChangesRequest(url)) return "content_changes";
+		if (isDocsAgentsRequest(url) || resolveDocsAgentsFormat(url) === "agents") return "agents";
+		if (isDocsSkillRequest(url) || resolveDocsSkillFormat(url) === "skill") return "skill";
+		if (resolveDocsMarkdownRequest(options.entry, url, request)) return "markdown";
+		if (resolveDocsLlmsTxtRequest(url, options.llmsTxt, options.entry)) return "llms";
+	}
+	if (method === "POST") return "ask_ai";
+}
+
+//#endregion
+export { emitDocsTelemetryAgentSurfaceEvent, emitDocsTelemetryMcpToolEvent, emitDocsTelemetryProjectEvent, getDocsTelemetryFeatures, inferDocsTelemetryAgentSurface };

package/dist/{types-BJFeMXWZ.d.mts → types.d.mts}

@@ -1960,7 +1960,8 @@ type ReadingTimeFormat = "long" | "short";
 interface ReadingTimeConfig {
   /**
    * Whether to show the estimated reading time.
-   * @default true
+   * This must be set to `true` to opt in when using an options object.
+   * @default false
    */
   enabled?: boolean;
   /**
@@ -4192,4 +4193,4 @@ interface DocsConfig {
   og?: OGConfig;
 }
 //#endregion
-export { DocsAgentGoldenAuthenticatedContentExpectation as $, DocsSearchExplanation as $n, PageAgentFailureMode as $r, DocsFeedbackData as $t, DocsAgentA2AOAuthImplicitFlow as A, DocsPaginatedSearchResponse as An, FeedbackConfig as Ar, DocsAskAIMcpConfig as At, DocsAgentContentChangesConfig as B, DocsRobotsConfig as Bn, OpenDocsConfig as Br, DocsCodeBlocksRunnerProvider as Bt, DocsAgentA2AInterfaceConfig as C, DocsOkfTrustMetadata as Cn, DocsTelemetryConfig as Cr, DocsAnalyticsSource as Ct, DocsAgentA2AOAuthClientCredentialsFlow as D, DocsOpenApiMcpCredentialContext as Dn, DocsTelemetryFeatures as Dr, DocsAskAIFeedbackData as Dt, DocsAgentA2AOAuthAuthorizationCodeFlow as E, DocsOpenApiMcpConfig as En, DocsTelemetryEventType as Er, DocsAskAIFeedbackConfig as Et, DocsAgentA2ASecurityScheme as F, DocsReviewCiMode as Fn, LlmsTxtMaxCharsConfig as Fr, DocsCloudPublishConfig as Ft, DocsAgentEvaluationAnswerRunner as G, DocsSearchAdapterPage as Gn, OpenGraphImage as Gr, DocsContentChangeDocument as Gt, DocsAgentEvaluationAnswerProvider as H, DocsSearchAdapter as Hn, OpenDocsProviderConfig as Hr, DocsCodeBlocksValidationMode as Ht, DocsAgentA2ASecurityScopeList as I, DocsReviewConfig as In, LlmsTxtMaxCharsMode as Ir, DocsCodeBlocksConfig as It, DocsAgentEvaluationTaskInput as J, DocsSearchAmbiguityResolution as Jn, PageActionInstallSkillsConfig as Jr, DocsContentChangeSnapshotSaver as Jt, DocsAgentEvaluationSourceReference as K, DocsSearchAmbiguityDecision as Kn, OrderingItem as Kr, DocsContentChangeSnapshotContext as Kt, DocsAgentA2ASkill as L, DocsReviewRulesConfig as Ln, LlmsTxtSectionConfig as Lr, DocsCodeBlocksPlannerConfig as Lt, DocsAgentA2AOpenIdConnectSecurityScheme as M, DocsRetrievalSourceProvenance as Mn, GithubConfig as Mr, DocsCloudConfig as Mt, DocsAgentA2AProtocolBinding as N, DocsRetrievalSourceScope as Nn, LastUpdatedConfig as Nr, DocsCloudFeatureConfig as Nt, DocsAgentA2AOAuthDeviceCodeFlow as O, DocsOpenApiMcpHeaders as On, DocsTelemetryFramework as Or, DocsAskAIFeedbackMessage as Ot, DocsAgentA2ASecurityRequirement as P, DocsReviewCiConfig as Pn, LlmsTxtConfig as Pr, DocsCloudPreviewConfig as Pt, DocsAgentGoldenAnswerExpectation as Q, DocsSearchEmbeddingsConfig as Qn, PageAgentCommand as Qr, DocsContentSnapshotDocument as Qt, DocsAgentCompactConfig as R, DocsReviewScoreConfig as Rn, McpDocsSearchConfig as Rr, DocsCodeBlocksPlannerProvider as Rt, DocsAgentA2AHttpAuthSecurityScheme as S, DocsOkfStatus as Sn, DocsTelemetryAgentSurface as Sr, DocsAnalyticsInput as St, DocsAgentA2AOAuth2SecurityScheme as T, DocsOkfTrustTier as Tn, DocsTelemetryEventInput as Tr, DocsAskAIActionType as Tt, DocsAgentEvaluationAnswerRequest as U, DocsSearchAdapterContext as Un, OpenDocsProviderId as Ur, DocsCodeBlocksValidationPolicy as Ut, DocsAgentEvaluationAnswerInput as V, DocsRobotsRule as Vn, OpenDocsProvider as Vr, DocsCodeBlocksValidateConfig as Vt, DocsAgentEvaluationAnswerResult as W, DocsSearchAdapterFactory as Wn, OpenDocsTarget as Wr, DocsConfig as Wt, DocsAgentFeedbackContext as X, DocsSearchConfig as Xn, PageActionsConfig as Xr, DocsContentChangesResponse as Xt, DocsAgentEvaluationsConfig as Y, DocsSearchChunkingConfig as Yn, PageActionMcpProvider as Yr, DocsContentChangedDocument as Yt, DocsAgentFeedbackData as Z, DocsSearchDocument as Zn, PageAgentAppliesTo as Zr, DocsContentSnapshot as Zt, DocsAccessPrincipal as _, ThemeToggleConfig as _i, DocsObservabilityEvent as _n, DocsSearchResultType as _r, DocsAgentTraceStatus as _t, ApiReferenceRenderer as a, PageTwitter as ai, DocsMcpAuthenticateContext as an, DocsSearchFilterField as ar, DocsAgentGoldenQueryVariant as at, DocsAgentA2AConfig as b, UIConfig as bi, DocsOkfConfig as bn, DocsSearchWarningCode as br, DocsAnalyticsEventInput as bt, ApiReferenceVersionConfig as c, ResolvedDocsRelatedLink as ci, DocsMcpCorsConfig as cn, DocsSearchMatchField as cr, DocsAgentGoldenTask as ct, ChangelogFrontmatter as d, SidebarFolderIndexBehavior as di, DocsMcpProtectedResourceConfig as dn, DocsSearchRankingReason as dr, DocsAgentSkillsCompatibilityPolicy as dt, PageAgentFrontmatter as ei, DocsFeedbackValue as en, DocsSearchFacet as er, DocsAgentGoldenCoverageApplicability as et, CodeBlockCopyData as f, SidebarFolderNode as fi, DocsMcpSecurityConfig as fn, DocsSearchRankingReasonCode as fr, DocsAgentSkillsConfig as ft, DocsAccessClaimValue as g, SimpleDocsSearchConfig as gi, DocsObservabilityConfig as gn, DocsSearchResult as gr, DocsAgentTraceEventType as gt, CustomDocsSearchConfig as h, SidebarTree as hi, DocsNav as hn, DocsSearchResponse as hr, DocsAgentTraceEventInput as ht, ApiReferenceConfig as i, PageSidebarFrontmatter as ii, DocsMcpAuthenticate as in, DocsSearchFilterDecisionOutcome as ir, DocsAgentGoldenPromptInjectionExpectation as it, DocsAgentA2AOAuthPasswordFlow as j, DocsRelatedItem as jn, FontStyle as jr, DocsCloudApiKeyConfig as jt, DocsAgentA2AOAuthFlows as k, DocsPageAccessPolicy as kn, DocsTheme as kr, DocsAskAIFeedbackValue as kt, BreadcrumbConfig as l, SidebarComponentProps as li, DocsMcpOriginContext as ln, DocsSearchMatchedTerm as lr, DocsAgentGoldenTaskExpectation as lt, CopyMarkdownFormat as m, SidebarPageNode as mi, DocsMetadata as mn, DocsSearchRequest as mr, DocsAgentSkillsProgressiveDisclosureConfig as mt, AgentFeedbackConfig as n, PageFrontmatter as ni, DocsMcpAllowedOrigins as nn, DocsSearchFacetsResponse as nr, DocsAgentGoldenExpectedExample as nt, ApiReferenceRendererConfig as o, ReadingTimeConfig as oi, DocsMcpAuthenticateResult as on, DocsSearchFilterInput as or, DocsAgentGoldenQueryVariantKind as ot, CopyMarkdownConfig as p, SidebarNode as pi, DocsMcpToolsConfig as pn, DocsSearchRankingStrategy as pr, DocsAgentSkillsInput as pt, DocsAgentEvaluationSurface as q, DocsSearchAmbiguityDecisionStatus as qn, PageActionConnectMcpConfig as qr, DocsContentChangeSnapshotLoader as qt, AlgoliaDocsSearchConfig as r, PageOpenGraph as ri, DocsMcpAuthPrincipal as rn, DocsSearchFilterDecision as rr, DocsAgentGoldenFreshnessExpectation as rt, ApiReferenceRendererInput as s, ReadingTimeFormat as si, DocsMcpConfig as sn, DocsSearchFilters as sr, DocsAgentGoldenSafetyExpectation as st, AIConfig as t, PageAgentVerification as ti, DocsI18nConfig as tn, DocsSearchFacetValue as tr, DocsAgentGoldenExampleVerification as tt, ChangelogConfig as u, SidebarConfig as ui, DocsMcpPromptsConfig as un, DocsSearchQuery as ur, DocsAgentGoldenTaskFilters as ut, DocsAgentA2AApiKeySecurityScheme as v, TypesenseDocsSearchConfig as vi, DocsObservabilityEventInput as vn, DocsSearchSourcePage as vr, DocsAnalyticsConfig as vt, DocsAgentA2AMutualTlsSecurityScheme as w, DocsOkfTrustMetadataInput as wn, DocsTelemetryEvent as wr, DocsAskAIActionData as wt, DocsAgentA2AExtension as x, DocsOkfSource as xn, DocsSitemapConfig as xr, DocsAnalyticsEventType as xt, DocsAgentA2ACapabilities as y, TypographyConfig as yi, DocsOkfActorTimestamp as yn, DocsSearchWarning as yr, DocsAnalyticsEvent as yt, DocsAgentConfig as z, DocsReviewSeverity as zn, OGConfig as zr, DocsCodeBlocksRunnerConfig as zt };
+export { AIConfig, AgentFeedbackConfig, AlgoliaDocsSearchConfig, ApiReferenceConfig, ApiReferenceRenderer, ApiReferenceRendererConfig, ApiReferenceRendererInput, ApiReferenceVersionConfig, BreadcrumbConfig, ChangelogConfig, ChangelogFrontmatter, CodeBlockCopyData, CopyMarkdownConfig, CopyMarkdownFormat, CustomDocsSearchConfig, DocsAccessClaimValue, DocsAccessPrincipal, DocsAgentA2AApiKeySecurityScheme, DocsAgentA2ACapabilities, DocsAgentA2AConfig, DocsAgentA2AExtension, DocsAgentA2AHttpAuthSecurityScheme, DocsAgentA2AInterfaceConfig, DocsAgentA2AMutualTlsSecurityScheme, DocsAgentA2AOAuth2SecurityScheme, DocsAgentA2AOAuthAuthorizationCodeFlow, DocsAgentA2AOAuthClientCredentialsFlow, DocsAgentA2AOAuthDeviceCodeFlow, DocsAgentA2AOAuthFlows, DocsAgentA2AOAuthImplicitFlow, DocsAgentA2AOAuthPasswordFlow, DocsAgentA2AOpenIdConnectSecurityScheme, DocsAgentA2AProtocolBinding, DocsAgentA2ASecurityRequirement, DocsAgentA2ASecurityScheme, DocsAgentA2ASecurityScopeList, DocsAgentA2ASkill, DocsAgentCompactConfig, DocsAgentConfig, DocsAgentContentChangesConfig, DocsAgentEvaluationAnswerInput, DocsAgentEvaluationAnswerProvider, DocsAgentEvaluationAnswerRequest, DocsAgentEvaluationAnswerResult, DocsAgentEvaluationAnswerRunner, DocsAgentEvaluationSourceReference, DocsAgentEvaluationSurface, DocsAgentEvaluationTaskInput, DocsAgentEvaluationsConfig, DocsAgentFeedbackContext, DocsAgentFeedbackData, DocsAgentGoldenAnswerExpectation, DocsAgentGoldenAuthenticatedContentExpectation, DocsAgentGoldenCoverageApplicability, DocsAgentGoldenExampleVerification, DocsAgentGoldenExpectedExample, DocsAgentGoldenFreshnessExpectation, DocsAgentGoldenPromptInjectionExpectation, DocsAgentGoldenQueryVariant, DocsAgentGoldenQueryVariantKind, DocsAgentGoldenSafetyExpectation, DocsAgentGoldenTask, DocsAgentGoldenTaskExpectation, DocsAgentGoldenTaskFilters, DocsAgentSkillsCompatibilityPolicy, DocsAgentSkillsConfig, DocsAgentSkillsInput, DocsAgentSkillsProgressiveDisclosureConfig, DocsAgentTraceEventInput, DocsAgentTraceEventType, DocsAgentTraceStatus, DocsAnalyticsConfig, DocsAnalyticsEvent, DocsAnalyticsEventInput, DocsAnalyticsEventType, DocsAnalyticsInput, DocsAnalyticsSource, DocsAskAIActionData, DocsAskAIActionType, DocsAskAIFeedbackConfig, DocsAskAIFeedbackData, DocsAskAIFeedbackMessage, DocsAskAIFeedbackValue, DocsAskAIMcpConfig, DocsCloudApiKeyConfig, DocsCloudConfig, DocsCloudFeatureConfig, DocsCloudPreviewConfig, DocsCloudPublishConfig, DocsCodeBlocksConfig, DocsCodeBlocksPlannerConfig, DocsCodeBlocksPlannerProvider, DocsCodeBlocksRunnerConfig, DocsCodeBlocksRunnerProvider, DocsCodeBlocksValidateConfig, DocsCodeBlocksValidationMode, DocsCodeBlocksValidationPolicy, DocsConfig, DocsContentChangeDocument, DocsContentChangeSnapshotContext, DocsContentChangeSnapshotLoader, DocsContentChangeSnapshotSaver, DocsContentChangedDocument, DocsContentChangesResponse, DocsContentSnapshot, DocsContentSnapshotDocument, DocsFeedbackData, DocsFeedbackValue, DocsI18nConfig, DocsMcpAllowedOrigins, DocsMcpAuthPrincipal, DocsMcpAuthenticate, DocsMcpAuthenticateContext, DocsMcpAuthenticateResult, DocsMcpConfig, DocsMcpCorsConfig, DocsMcpOriginContext, DocsMcpPromptsConfig, DocsMcpProtectedResourceConfig, DocsMcpSecurityConfig, DocsMcpToolsConfig, DocsMetadata, DocsNav, DocsObservabilityConfig, DocsObservabilityEvent, DocsObservabilityEventInput, DocsOkfActorTimestamp, DocsOkfConfig, DocsOkfSource, DocsOkfStatus, DocsOkfTrustMetadata, DocsOkfTrustMetadataInput, DocsOkfTrustTier, DocsOpenApiMcpConfig, DocsOpenApiMcpCredentialContext, DocsOpenApiMcpHeaders, DocsPageAccessPolicy, DocsPaginatedSearchResponse, DocsRelatedItem, DocsRetrievalSourceProvenance, DocsRetrievalSourceScope, DocsReviewCiConfig, DocsReviewCiMode, DocsReviewConfig, DocsReviewRulesConfig, DocsReviewScoreConfig, DocsReviewSeverity, DocsRobotsConfig, DocsRobotsRule, DocsSearchAdapter, DocsSearchAdapterContext, DocsSearchAdapterFactory, DocsSearchAdapterPage, DocsSearchAmbiguityDecision, DocsSearchAmbiguityDecisionStatus, DocsSearchAmbiguityResolution, DocsSearchChunkingConfig, DocsSearchConfig, DocsSearchDocument, DocsSearchEmbeddingsConfig, DocsSearchExplanation, DocsSearchFacet, DocsSearchFacetValue, DocsSearchFacetsResponse, DocsSearchFilterDecision, DocsSearchFilterDecisionOutcome, DocsSearchFilterField, DocsSearchFilterInput, DocsSearchFilters, DocsSearchMatchField, DocsSearchMatchedTerm, DocsSearchQuery, DocsSearchRankingReason, DocsSearchRankingReasonCode, DocsSearchRankingStrategy, DocsSearchRequest, DocsSearchResponse, DocsSearchResult, DocsSearchResultType, DocsSearchSourcePage, DocsSearchWarning, DocsSearchWarningCode, DocsSitemapConfig, DocsTelemetryAgentSurface, DocsTelemetryConfig, DocsTelemetryEvent, DocsTelemetryEventInput, DocsTelemetryEventType, DocsTelemetryFeatures, DocsTelemetryFramework, DocsTheme, FeedbackConfig, FontStyle, GithubConfig, LastUpdatedConfig, LlmsTxtConfig, LlmsTxtMaxCharsConfig, LlmsTxtMaxCharsMode, LlmsTxtSectionConfig, McpDocsSearchConfig, OGConfig, OpenDocsConfig, OpenDocsProvider, OpenDocsProviderConfig, OpenDocsProviderId, OpenDocsTarget, OpenGraphImage, OrderingItem, PageActionConnectMcpConfig, PageActionInstallSkillsConfig, PageActionMcpProvider, PageActionsConfig, PageAgentAppliesTo, PageAgentCommand, PageAgentFailureMode, PageAgentFrontmatter, PageAgentVerification, PageFrontmatter, PageOpenGraph, PageSidebarFrontmatter, PageTwitter, ReadingTimeConfig, ReadingTimeFormat, ResolvedDocsRelatedLink, SidebarComponentProps, SidebarConfig, SidebarFolderIndexBehavior, SidebarFolderNode, SidebarNode, SidebarPageNode, SidebarTree, SimpleDocsSearchConfig, ThemeToggleConfig, TypesenseDocsSearchConfig, TypographyConfig, UIConfig };

package/dist/urls.d.mts

@@ -0,0 +1,7 @@
+//#region src/urls.d.ts
+declare function normalizeDocsUrlPath(value: string): string;
+declare function toDocsMarkdownUrl(url: string, options?: {
+  locale?: string;
+}): string;
+//#endregion
+export { normalizeDocsUrlPath, toDocsMarkdownUrl };

package/dist/urls.mjs

@@ -0,0 +1,21 @@
+//#region src/urls.ts
+function normalizeDocsUrlPath(value) {
+	const normalized = value.replace(/\/+/g, "/");
+	if (normalized === "/") return normalized;
+	return normalized.replace(/\/+$/, "");
+}
+function toDocsMarkdownUrl(url, options = {}) {
+	const hashIndex = url.indexOf("#");
+	const withoutHash = hashIndex >= 0 ? url.slice(0, hashIndex) : url;
+	const hash = hashIndex >= 0 ? url.slice(hashIndex + 1) : "";
+	const [pathname, query = ""] = withoutHash.split("?", 2);
+	const normalizedPath = normalizeDocsUrlPath(pathname || "/");
+	const markdownPath = normalizedPath.endsWith(".md") ? normalizedPath : `${normalizedPath}.md`;
+	const params = new URLSearchParams(query);
+	if (options.locale && !params.has("lang")) params.set("lang", options.locale);
+	const search = params.toString();
+	return `${markdownPath}${search ? `?${search}` : ""}${hash ? `#${hash}` : ""}`;
+}
+
+//#endregion
+export { normalizeDocsUrlPath, toDocsMarkdownUrl };

package/dist/utils.d.mts

@@ -0,0 +1,8 @@
+//#region src/utils.d.ts
+/**
+ * Deep merge utility for theme overrides.
+ * Merges objects recursively; later values override earlier ones.
+ */
+declare function deepMerge<T extends Record<string, unknown>>(target: T, ...sources: Partial<T>[]): T;
+//#endregion
+export { deepMerge };

package/dist/utils.mjs

@@ -0,0 +1,22 @@
+//#region src/utils.ts
+/**
+* Deep merge utility for theme overrides.
+* Merges objects recursively; later values override earlier ones.
+*/
+function deepMerge(target, ...sources) {
+	if (!sources.length) return target;
+	const source = sources.shift();
+	if (!source) return target;
+	const result = { ...target };
+	for (const key of Object.keys(source)) {
+		const sourceVal = source[key];
+		const targetVal = result[key];
+		if (sourceVal && typeof sourceVal === "object" && !Array.isArray(sourceVal) && targetVal && typeof targetVal === "object" && !Array.isArray(targetVal)) result[key] = deepMerge(targetVal, sourceVal);
+		else if (sourceVal !== void 0) result[key] = sourceVal;
+	}
+	if (sources.length) return deepMerge(result, ...sources);
+	return result;
+}
+
+//#endregion
+export { deepMerge };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/docs",
-  "version": "0.2.120",
+  "version": "0.2.121",
   "description": "Modern, flexible MDX-based docs framework — core types, config, and CLI",
   "keywords": [
     "docs",
@@ -19,6 +19,10 @@
     "dist",
     "styles"
   ],
+  "sideEffects": [
+    "**/*.css",
+    "./dist/cli/**"
+  ],
   "type": "module",
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",
@@ -39,6 +43,11 @@
       "import": "./dist/runtime.mjs",
       "default": "./dist/runtime.mjs"
     },
+    "./mdx": {
+      "types": "./dist/mdx.d.mts",
+      "import": "./dist/mdx.mjs",
+      "default": "./dist/mdx.mjs"
+    },
     "./markdown-rendering": {
       "types": "./dist/markdown-rendering.d.mts",
       "import": "./dist/markdown-rendering.mjs",
@@ -79,14 +88,18 @@
       "import": "./dist/mcp.mjs",
       "default": "./dist/mcp.mjs"
     },
-    "./styles/themes/shadcn.css": "./styles/themes/shadcn.css"
+    "./styles/themes/shadcn.css": "./styles/themes/shadcn.css",
+    "./build": {
+      "types": "./dist/build.d.mts",
+      "import": "./dist/build.mjs",
+      "default": "./dist/build.mjs"
+    }
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
     "@mdx-js/mdx": "^3.1.1",
     "@modelcontextprotocol/server": "2.0.0",
     "@scalar/core": "^0.4.3",
-    "@vercel/sandbox": "^2.0.0",
     "github-slugger": "^2.0.0",
     "gray-matter": "^4.0.3",
     "jiti": "^2.7.0",
@@ -98,9 +111,13 @@
     "zod": "^4.3.6"
   },
   "peerDependencies": {
+    "@vercel/sandbox": "^2.0.0",
     "react": ">=19.2.0"
   },
   "peerDependenciesMeta": {
+    "@vercel/sandbox": {
+      "optional": true
+    },
     "react": {
       "optional": true
     }
@@ -109,6 +126,7 @@
     "@modelcontextprotocol/client": "2.2.0",
     "@types/node": "^22.10.0",
     "@types/react": "^19.2.2",
+    "@vercel/sandbox": "^2.0.0",
     "ajv": "^8.18.0",
     "ajv-formats": "^3.0.1",
     "react": "^19.2.0",