@farming-labs/docs 0.0.61 → 0.0.63

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { A as SidebarNode, C as PageActionsConfig, D as SidebarComponentProps, E as PageTwitter, F as UIConfig, M as SidebarTree, N as ThemeToggleConfig, O as SidebarConfig, P as TypographyConfig, S as OrderingItem, T as PageOpenGraph, _ as LlmsTxtConfig, a as CopyMarkdownConfig, b as OpenDocsProvider, c as DocsFeedbackValue, d as DocsNav, f as DocsTheme, g as LastUpdatedConfig, h as GithubConfig, i as CodeBlockCopyData, j as SidebarPageNode, k as SidebarFolderNode, l as DocsI18nConfig, m as FontStyle, n as ApiReferenceConfig, o as DocsConfig, p as FeedbackConfig, r as BreadcrumbConfig, s as DocsFeedbackData, t as AIConfig, u as DocsMetadata, v as OGConfig, w as PageFrontmatter, x as OpenGraphImage, y as OpenDocsConfig } from "./types-CjzUmIVM.mjs";
+import { A as SidebarNode, C as PageActionsConfig, D as SidebarComponentProps, E as PageTwitter, F as UIConfig, M as SidebarTree, N as ThemeToggleConfig, O as SidebarConfig, P as TypographyConfig, S as OrderingItem, T as PageOpenGraph, _ as LlmsTxtConfig, a as CopyMarkdownConfig, b as OpenDocsProvider, c as DocsFeedbackValue, d as DocsNav, f as DocsTheme, g as LastUpdatedConfig, h as GithubConfig, i as CodeBlockCopyData, j as SidebarPageNode, k as SidebarFolderNode, l as DocsI18nConfig, m as FontStyle, n as ApiReferenceConfig, o as DocsConfig, p as FeedbackConfig, r as BreadcrumbConfig, s as DocsFeedbackData, t as AIConfig, u as DocsMetadata, v as OGConfig, w as PageFrontmatter, x as OpenGraphImage, y as OpenDocsConfig } from "./types-DpijZMth.mjs";
 
 //#region src/define-docs.d.ts
 /**

package/dist/server.d.mts

@@ -1,4 +1,4 @@
-import { n as ApiReferenceConfig, o as DocsConfig } from "./types-CjzUmIVM.mjs";
+import { o as DocsConfig } from "./types-DpijZMth.mjs";
 
 //#region src/api-reference.d.ts
 type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD";
@@ -13,6 +13,13 @@ interface ApiReferenceRoute {
   tag: string;
   parameters: Array<Record<string, unknown>>;
 }
+interface ResolvedApiReferenceConfig {
+  enabled: boolean;
+  path: string;
+  specUrl?: string;
+  routeRoot: string;
+  exclude: string[];
+}
 interface BuildApiReferenceOptions {
   framework: ApiReferenceFramework;
   rootDir?: string;
@@ -20,10 +27,12 @@ interface BuildApiReferenceOptions {
 interface BuildApiReferenceHtmlOptions extends BuildApiReferenceOptions {
   title?: string;
 }
-declare function resolveApiReferenceConfig(value: DocsConfig["apiReference"]): Required<ApiReferenceConfig>;
+declare function resolveApiReferenceConfig(value: DocsConfig["apiReference"]): ResolvedApiReferenceConfig;
 declare function buildApiReferencePageTitle(config: DocsConfig, title?: string): string;
 declare function buildApiReferenceScalarCss(config: DocsConfig): string;
 declare function buildApiReferenceOpenApiDocument(config: DocsConfig, options: BuildApiReferenceOptions): Record<string, unknown>;
+declare function buildApiReferenceOpenApiDocumentAsync(config: DocsConfig, options: BuildApiReferenceOptions): Promise<Record<string, unknown>>;
 declare function buildApiReferenceHtmlDocument(config: DocsConfig, options: BuildApiReferenceHtmlOptions): string;
+declare function buildApiReferenceHtmlDocumentAsync(config: DocsConfig, options: BuildApiReferenceHtmlOptions): Promise<string>;
 //#endregion
-export { type ApiReferenceFramework, type ApiReferenceRoute, buildApiReferenceHtmlDocument, buildApiReferenceOpenApiDocument, buildApiReferencePageTitle, buildApiReferenceScalarCss, resolveApiReferenceConfig };
+export { type ApiReferenceFramework, type ApiReferenceRoute, type ResolvedApiReferenceConfig, buildApiReferenceHtmlDocument, buildApiReferenceHtmlDocumentAsync, buildApiReferenceOpenApiDocument, buildApiReferenceOpenApiDocumentAsync, buildApiReferencePageTitle, buildApiReferenceScalarCss, resolveApiReferenceConfig };

package/dist/server.mjs

@@ -25,22 +25,30 @@ function resolveApiReferenceConfig(value) {
 	if (value === true) return {
 		enabled: true,
 		path: "api-reference",
+		specUrl: void 0,
 		routeRoot: "api",
 		exclude: []
 	};
 	if (!value) return {
 		enabled: false,
 		path: "api-reference",
+		specUrl: void 0,
 		routeRoot: "api",
 		exclude: []
 	};
 	return {
 		enabled: value.enabled !== false,
 		path: normalizePathSegment(value.path ?? "api-reference"),
+		specUrl: normalizeRemoteSpecUrl(value.specUrl),
 		routeRoot: normalizePathSegment(value.routeRoot ?? "api") || "api",
 		exclude: normalizeApiReferenceExcludes(value.exclude)
 	};
 }
+function normalizeRemoteSpecUrl(value) {
+	const trimmed = value?.trim();
+	if (!trimmed) return void 0;
+	return trimmed;
+}
 function buildApiReferencePageTitle(config, title = "API Reference") {
 	const template = config.metadata?.titleTemplate;
 	if (!template) return title;
@@ -51,17 +59,24 @@ function buildApiReferenceScalarCss(config) {
 	const colors = theme?.ui?.colors;
 	const typography = theme?.ui?.typography?.font?.style;
 	const layout = theme?.ui?.layout;
+	const radius = resolveApiReferenceRadius(theme);
 	const primary = colors?.primary ?? "#6366f1";
 	const border = colors?.border ?? "#2a2a2a";
 	const muted = colors?.muted ?? "#64748b";
 	const background = colors?.background ?? "#ffffff";
 	const card = colors?.card ?? background;
-	const foreground = colors?.foreground ?? "#1b1b1b";
+	const foreground = colors?.foreground ?? inferApiReferenceForeground(theme, background);
+	const primaryForeground = colors?.primaryForeground ?? inferContrastingForeground(primary, theme, background);
 	const sidebarWidth = layout?.sidebarWidth ?? 280;
+	const sans = typography?.sans ?? "\"Geist\", \"Inter\", \"Segoe UI\", sans-serif";
+	const mono = typography?.mono ?? "\"Geist Mono\", \"SFMono-Regular\", \"Menlo\", monospace";
+	const isPixelBorder = theme?.name?.includes("pixel-border");
 	return `
 :root {
-  --scalar-font: ${typography?.sans ?? "\"Geist\", \"Inter\", \"Segoe UI\", sans-serif"};
-  --scalar-font-code: ${typography?.mono ?? "\"Geist Mono\", \"SFMono-Regular\", \"Menlo\", monospace"};
+  --scalar-font: ${sans};
+  --scalar-font-code: ${mono};
+  --scalar-radius: ${radius};
+  --scalar-radius-sm: calc(${radius} + 2px);
   --scalar-theme-primary: ${primary};
   --scalar-theme-border: ${border};
   --scalar-theme-muted: ${muted};
@@ -71,26 +86,37 @@ function buildApiReferenceScalarCss(config) {
 }
 
 .dark-mode {
-  --scalar-background-1: color-mix(in srgb, #0b0c0b 98%, var(--scalar-theme-primary) 2%);
-  --scalar-background-2: color-mix(in srgb, #111311 96%, var(--scalar-theme-primary) 4%);
-  --scalar-background-3: color-mix(in srgb, #171917 95%, var(--scalar-theme-primary) 5%);
-  --scalar-color-1: rgba(255, 255, 255, 0.96);
-  --scalar-color-2: rgba(255, 255, 255, 0.72);
-  --scalar-color-3: rgba(255, 255, 255, 0.5);
+  --scalar-background-1: color-mix(
+    in srgb,
+    var(--scalar-theme-background) 96%,
+    var(--scalar-theme-primary) 4%
+  );
+  --scalar-background-2: color-mix(in srgb, var(--scalar-theme-card) 94%, var(--scalar-theme-primary) 6%);
+  --scalar-background-3: color-mix(
+    in srgb,
+    var(--scalar-theme-card) 90%,
+    var(--scalar-theme-foreground) 10%
+  );
+  --scalar-color-1: var(--scalar-theme-foreground);
+  --scalar-color-2: color-mix(in srgb, var(--scalar-theme-foreground) 72%, transparent);
+  --scalar-color-3: color-mix(in srgb, var(--scalar-theme-foreground) 52%, transparent);
   --scalar-color-accent: var(--scalar-theme-primary);
+  --scalar-sidebar-background-1: var(--scalar-background-1);
+  --scalar-sidebar-background-2: var(--scalar-background-2);
+  --scalar-sidebar-color-1: var(--scalar-color-1);
+  --scalar-sidebar-color-2: var(--scalar-color-2);
+  --scalar-sidebar-search-background: var(--scalar-background-2);
+  --scalar-sidebar-search-border-color: var(--scalar-border-color);
+  --scalar-sidebar-search-color: var(--scalar-color-2);
   --scalar-sidebar-color-active: var(--scalar-theme-primary);
   --scalar-sidebar-item-active-background: color-mix(
     in srgb,
     var(--scalar-theme-primary) 7%,
     transparent
   );
-  --scalar-border-color: color-mix(
-    in srgb,
-    var(--scalar-theme-border) 14%,
-    rgba(255, 255, 255, 0.02)
-  );
+  --scalar-border-color: ${isPixelBorder ? "color-mix(in srgb, var(--scalar-theme-foreground) 10%, transparent)" : "color-mix(in srgb, var(--scalar-theme-border) 14%, rgba(255, 255, 255, 0.02))"};
   --scalar-button-1: var(--scalar-theme-primary);
-  --scalar-button-1-color: #ffffff;
+  --scalar-button-1-color: ${primaryForeground};
   --scalar-button-1-hover: color-mix(in srgb, var(--scalar-theme-primary) 88%, white 12%);
 }
 
@@ -102,20 +128,28 @@ function buildApiReferenceScalarCss(config) {
   --scalar-color-2: var(--scalar-theme-muted);
   --scalar-color-3: color-mix(in srgb, var(--scalar-theme-muted) 78%, white 22%);
   --scalar-color-accent: var(--scalar-theme-primary);
+  --scalar-sidebar-background-1: var(--scalar-background-1);
+  --scalar-sidebar-background-2: var(--scalar-background-2);
+  --scalar-sidebar-color-1: var(--scalar-color-1);
+  --scalar-sidebar-color-2: var(--scalar-color-2);
+  --scalar-sidebar-search-background: var(--scalar-background-2);
+  --scalar-sidebar-search-border-color: var(--scalar-border-color);
+  --scalar-sidebar-search-color: var(--scalar-color-2);
   --scalar-sidebar-color-active: var(--scalar-theme-primary);
   --scalar-sidebar-item-active-background: color-mix(
     in srgb,
     var(--scalar-theme-primary) 5%,
     transparent
   );
-  --scalar-border-color: color-mix(in srgb, var(--scalar-theme-border) 30%, white 70%);
+  --scalar-border-color: ${isPixelBorder ? "color-mix(in srgb, var(--scalar-theme-foreground) 14%, transparent)" : "color-mix(in srgb, var(--scalar-theme-border) 30%, white 70%)"};
   --scalar-button-1: var(--scalar-theme-primary);
-  --scalar-button-1-color: #ffffff;
+  --scalar-button-1-color: ${primaryForeground};
   --scalar-button-1-hover: color-mix(in srgb, var(--scalar-theme-primary) 88%, black 12%);
 }
 
 body {
   background: var(--scalar-background-1);
+  color: var(--scalar-color-1);
 }
 
 .t-doc__sidebar {
@@ -144,12 +178,12 @@ body {
 }
 
 .t-doc__sidebar .sidebar-search input {
-  border-radius: 14px;
+  border-radius: var(--scalar-radius-sm);
 }
 
 .t-doc__sidebar .sidebar-item,
 .t-doc__sidebar .sidebar-heading {
-  border-radius: 14px;
+  border-radius: var(--scalar-radius-sm);
 }
 
 .t-doc__sidebar .sidebar-group-label {
@@ -166,7 +200,7 @@ body {
 .scalar-card,
 .references-layout .reference-layout__content .request-card,
 .references-layout .reference-layout__content .response-card {
-  border-radius: 18px;
+  border-radius: var(--scalar-radius);
 }
 
 .references-layout .reference-layout__content {
@@ -188,10 +222,210 @@ body {
 .references-layout .scalar-codeblock {
   font-family: var(--scalar-font-code);
 }
+
+.references-layout,
+.references-layout * {
+  color: inherit;
+}
+
+.references-layout .reference-layout__content .introduction,
+.references-layout .reference-layout__content .section,
+.references-layout .reference-layout__content .section-container,
+.references-layout .reference-layout__content .operation-details,
+.references-layout .reference-layout__content .markdown,
+.references-layout .reference-layout__content .markdown *,
+.references-layout .reference-layout__content .property,
+.references-layout .reference-layout__content .property *,
+.references-layout .reference-layout__content .parameter-item,
+.references-layout .reference-layout__content .parameter-item *,
+.references-layout .reference-layout__content .response-card,
+.references-layout .reference-layout__content .response-card *,
+.references-layout .reference-layout__content .request-card,
+.references-layout .reference-layout__content .request-card * {
+  color: var(--scalar-color-1);
+}
+
+.references-layout a,
+.references-layout button {
+  color: var(--scalar-color-1);
+}
+
+${isPixelBorder ? buildPixelBorderScalarCss() : ""}
 `;
 }
+function buildPixelBorderScalarCss() {
+	return `
+.t-doc__sidebar,
+.references-layout .reference-layout__content {
+  background-image:
+    repeating-linear-gradient(
+      -45deg,
+      color-mix(in srgb, var(--scalar-theme-border) 12%, transparent),
+      color-mix(in srgb, var(--scalar-theme-border) 12%, transparent) 1px,
+      transparent 1px,
+      transparent 8px
+    );
+}
+
+.t-doc__sidebar .sidebar-group-label,
+.t-doc__sidebar .sidebar-item,
+.references-layout .reference-layout__content .section-header {
+  font-family: var(--scalar-font-code);
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+}
+`;
+}
+function inferApiReferenceForeground(theme, background) {
+	if (looksDarkTheme(theme, background)) return "#f5f5f4";
+	return "#1b1b1b";
+}
+function resolveApiReferenceRadius(theme) {
+	if (theme?.ui?.radius) return theme.ui.radius;
+	const name = theme?.name?.toLowerCase() ?? "";
+	if (name.includes("pixel-border") || name.includes("darksharp")) return "0px";
+	return "var(--radius, 0.75rem)";
+}
+function inferContrastingForeground(value, theme, background) {
+	const rgb = parseCssColor(value);
+	if (rgb) return relativeLuminance(rgb) > .58 ? "#0b0b0b" : "#ffffff";
+	if (theme?.name?.includes("pixel-border")) return "#0b0b0b";
+	if (looksDarkTheme(theme, background)) return "#0b0b0b";
+	return "#ffffff";
+}
+function looksDarkTheme(theme, background) {
+	const name = theme?.name?.toLowerCase() ?? "";
+	if (name.includes("pixel-border") || name.includes("darksharp")) return true;
+	const rgb = parseCssColor(background);
+	if (!rgb) return false;
+	return relativeLuminance(rgb) < .45;
+}
+function parseCssColor(value) {
+	const normalized = value.trim().toLowerCase();
+	if (normalized.startsWith("#")) return parseHexColor(normalized);
+	const rgbMatch = normalized.match(/^rgba?\((.+)\)$/);
+	if (rgbMatch) {
+		const [r, g, b] = rgbMatch[1].split(",").slice(0, 3).map((part) => Number.parseFloat(part.trim()));
+		if ([
+			r,
+			g,
+			b
+		].every((channel) => Number.isFinite(channel))) return [
+			r,
+			g,
+			b
+		];
+	}
+	const hslMatch = normalized.match(/^hsla?\((.+)\)$/);
+	if (hslMatch) {
+		const [h, s, l] = hslMatch[1].split(/[\s,\/]+/).filter(Boolean).slice(0, 3);
+		const hue = Number.parseFloat(h);
+		const saturation = Number.parseFloat(s.replace("%", ""));
+		const lightness = Number.parseFloat(l.replace("%", ""));
+		if ([
+			hue,
+			saturation,
+			lightness
+		].every((channel) => Number.isFinite(channel))) return hslToRgb(hue, saturation / 100, lightness / 100);
+	}
+	const oklchMatch = normalized.match(/^oklch\((.+)\)$/);
+	if (oklchMatch) {
+		const [l, c, h] = oklchMatch[1].split(/[\s/]+/).filter(Boolean);
+		const lightness = Number.parseFloat(l);
+		const chroma = Number.parseFloat(c);
+		const hue = Number.parseFloat(h);
+		if ([
+			lightness,
+			chroma,
+			hue
+		].every((channel) => Number.isFinite(channel))) return oklchToRgb(lightness, chroma, hue);
+	}
+}
+function oklchToRgb(l, c, h) {
+	const hue = h * Math.PI / 180;
+	const a = Math.cos(hue) * c;
+	const b = Math.sin(hue) * c;
+	const l_ = l + .3963377774 * a + .2158037573 * b;
+	const m_ = l - .1055613458 * a - .0638541728 * b;
+	const s_ = l - .0894841775 * a - 1.291485548 * b;
+	const l3 = l_ ** 3;
+	const m3 = m_ ** 3;
+	const s3 = s_ ** 3;
+	const linearR = 4.0767416621 * l3 - 3.3077115913 * m3 + .2309699292 * s3;
+	const linearG = -1.2684380046 * l3 + 2.6097574011 * m3 - .3413193965 * s3;
+	const linearB = -.0041960863 * l3 - .7034186147 * m3 + 1.707614701 * s3;
+	return [
+		srgbFromLinear(linearR),
+		srgbFromLinear(linearG),
+		srgbFromLinear(linearB)
+	];
+}
+function srgbFromLinear(value) {
+	const normalized = value <= .0031308 ? value * 12.92 : 1.055 * value ** (1 / 2.4) - .055;
+	return Math.max(0, Math.min(255, Math.round(normalized * 255)));
+}
+function parseHexColor(value) {
+	const raw = value.slice(1);
+	if (raw.length === 3) return [
+		Number.parseInt(raw[0] + raw[0], 16),
+		Number.parseInt(raw[1] + raw[1], 16),
+		Number.parseInt(raw[2] + raw[2], 16)
+	];
+	if (raw.length === 6 || raw.length === 8) return [
+		Number.parseInt(raw.slice(0, 2), 16),
+		Number.parseInt(raw.slice(2, 4), 16),
+		Number.parseInt(raw.slice(4, 6), 16)
+	];
+}
+function hslToRgb(h, s, l) {
+	const hue = (h % 360 + 360) % 360 / 360;
+	if (s === 0) {
+		const gray = Math.round(l * 255);
+		return [
+			gray,
+			gray,
+			gray
+		];
+	}
+	const q = l < .5 ? l * (1 + s) : l + s - l * s;
+	const p = 2 * l - q;
+	const convert = (channel) => {
+		let t = channel;
+		if (t < 0) t += 1;
+		if (t > 1) t -= 1;
+		if (t < 1 / 6) return p + (q - p) * 6 * t;
+		if (t < 1 / 2) return q;
+		if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+		return p;
+	};
+	return [
+		Math.round(convert(hue + 1 / 3) * 255),
+		Math.round(convert(hue) * 255),
+		Math.round(convert(hue - 1 / 3) * 255)
+	];
+}
+function relativeLuminance([r, g, b]) {
+	const normalize = (channel) => {
+		const value = channel / 255;
+		return value <= .03928 ? value / 12.92 : ((value + .055) / 1.055) ** 2.4;
+	};
+	return .2126 * normalize(r) + .7152 * normalize(g) + .0722 * normalize(b);
+}
 function buildApiReferenceOpenApiDocument(config, options) {
+	if (resolveApiReferenceConfig(config.apiReference).specUrl) return buildUnavailableOpenApiDocument(config, `Remote OpenAPI specs require the async API reference builder. Use the framework route helper or buildApiReferenceOpenApiDocumentAsync().`);
 	const routes = buildApiReferenceRoutes(config, options);
+	return buildOpenApiDocumentFromRoutes(config, options.framework, routes);
+}
+async function buildApiReferenceOpenApiDocumentAsync(config, options) {
+	const apiReference = resolveApiReferenceConfig(config.apiReference);
+	if (!apiReference.specUrl) return buildApiReferenceOpenApiDocument(config, options);
+	try {
+		return normalizeRemoteOpenApiDocument(await fetchRemoteOpenApiDocument(apiReference.specUrl), config);
+	} catch (error) {
+		return buildUnavailableOpenApiDocument(config, `Unable to load the remote OpenAPI JSON. ${error instanceof Error ? error.message : "Unknown error"}`);
+	}
+}
+function buildOpenApiDocumentFromRoutes(config, framework, routes) {
 	const tags = Array.from(new Set(routes.map((route) => route.tag))).map((name) => ({
 		name,
 		description: `${name} endpoints`
@@ -200,7 +434,7 @@ function buildApiReferenceOpenApiDocument(config, options) {
 		openapi: "3.1.0",
 		info: {
 			title: "API Reference",
-			description: config.metadata?.description ?? `Generated API reference for ${options.framework}.`,
+			description: config.metadata?.description ?? `Generated API reference for ${framework}.`,
 			version: "0.0.0"
 		},
 		servers: [{ url: "/" }],
@@ -209,16 +443,18 @@ function buildApiReferenceOpenApiDocument(config, options) {
 	};
 }
 function buildApiReferenceHtmlDocument(config, options) {
+	return buildApiReferenceHtmlDocumentFromDocument(config, options, buildApiReferenceOpenApiDocument(config, options));
+}
+async function buildApiReferenceHtmlDocumentAsync(config, options) {
+	return buildApiReferenceHtmlDocumentFromDocument(config, options, await buildApiReferenceOpenApiDocumentAsync(config, options));
+}
+function buildApiReferenceHtmlDocumentFromDocument(config, options, document) {
 	const apiReference = resolveApiReferenceConfig(config.apiReference);
-	const rootDir = options.rootDir ?? process.cwd();
 	const title = options.title ?? "API Reference";
 	return getHtmlDocument({
 		pageTitle: buildApiReferencePageTitle(config, title),
 		title,
-		content: () => buildApiReferenceOpenApiDocument(config, {
-			framework: options.framework,
-			rootDir
-		}),
+		content: () => document,
 		theme: "deepSpace",
 		layout: "modern",
 		customCss: buildApiReferenceScalarCss(config),
@@ -235,6 +471,55 @@ function buildApiReferenceHtmlDocument(config, options) {
 		documentDownloadType: "json"
 	});
 }
+async function fetchRemoteOpenApiDocument(specUrl) {
+	let url;
+	try {
+		url = new URL(specUrl);
+	} catch {
+		throw new Error("`apiReference.specUrl` must be an absolute URL.");
+	}
+	const response = await fetch(url, { headers: { accept: "application/json" } });
+	if (!response.ok) throw new Error(`Received ${response.status} ${response.statusText}`.trim());
+	const body = await response.text();
+	if (!body.trim()) throw new Error("The remote endpoint returned an empty response.");
+	let parsed;
+	try {
+		parsed = JSON.parse(body);
+	} catch {
+		throw new Error("The remote endpoint did not return valid JSON.");
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("The remote endpoint returned a JSON value instead of an OpenAPI object.");
+	if (!("openapi" in parsed) && !("swagger" in parsed)) throw new Error("The remote JSON does not look like an OpenAPI document.");
+	return parsed;
+}
+function normalizeRemoteOpenApiDocument(document, config) {
+	const info = document.info && typeof document.info === "object" && !Array.isArray(document.info) ? document.info : {};
+	return {
+		...document,
+		info: {
+			title: "API Reference",
+			version: "0.0.0",
+			...info,
+			description: typeof info.description === "string" && info.description.trim() ? info.description : config.metadata?.description
+		}
+	};
+}
+function buildUnavailableOpenApiDocument(config, description) {
+	return {
+		openapi: "3.1.0",
+		info: {
+			title: "API Reference",
+			description,
+			version: "0.0.0"
+		},
+		servers: [{ url: "/" }],
+		tags: [{
+			name: "Unavailable",
+			description: config.metadata?.description ?? "OpenAPI spec could not be loaded."
+		}],
+		paths: {}
+	};
+}
 function buildApiReferenceRoutes(config, options) {
 	const apiReference = resolveApiReferenceConfig(config.apiReference);
 	if (!apiReference.enabled) return [];
@@ -514,4 +799,4 @@ function humanizeSegment(value) {
 }
 
 //#endregion
-export { buildApiReferenceHtmlDocument, buildApiReferenceOpenApiDocument, buildApiReferencePageTitle, buildApiReferenceScalarCss, resolveApiReferenceConfig };
+export { buildApiReferenceHtmlDocument, buildApiReferenceHtmlDocumentAsync, buildApiReferenceOpenApiDocument, buildApiReferenceOpenApiDocumentAsync, buildApiReferencePageTitle, buildApiReferenceScalarCss, resolveApiReferenceConfig };

package/dist/{types-CjzUmIVM.d.mts → types-DpijZMth.d.mts}

@@ -1076,6 +1076,21 @@ interface ApiReferenceConfig {
    * @default "api-reference"
    */
   path?: string;
+  /**
+   * Absolute URL to a remote OpenAPI JSON document.
+   *
+   * When provided, the API reference is generated from this hosted spec instead
+   * of scanning local framework route files.
+   *
+   * @example
+   * ```ts
+   * apiReference: {
+   *   enabled: true,
+   *   specUrl: "https://petstore3.swagger.io/api/v3/openapi.json",
+   * }
+   * ```
+   */
+  specUrl?: string;
   /**
    * Filesystem route root to scan for API handlers.
    *
@@ -1388,9 +1403,8 @@ interface DocsConfig {
    */
   llmsTxt?: boolean | LlmsTxtConfig;
   /**
-   * Generated API reference pages from framework route conventions.
-   *
-   * The first implementation targets Next.js route handlers under `app/api/<segments>/route.ts`.
+   * Generated API reference pages from framework route conventions or a hosted
+   * OpenAPI JSON document.
    *
    * @example
    * ```ts
@@ -1400,6 +1414,14 @@ interface DocsConfig {
    *   routeRoot: "api",
    * }
    * ```
+   *
+   * @example
+   * ```ts
+   * apiReference: {
+   *   enabled: true,
+   *   specUrl: "https://example.com/openapi.json",
+   * }
+   * ```
    */
   apiReference?: boolean | ApiReferenceConfig;
   /** SEO metadata - separate from theme */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/docs",
-  "version": "0.0.61",
+  "version": "0.0.63",
   "description": "Modern, flexible MDX-based docs framework — core types, config, and CLI",
   "keywords": [
     "docs",