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