@farming-labs/docs 0.2.120 → 0.2.122

package/dist/api-reference.mjs

@@ -0,0 +1,1481 @@
+import { toDocsMarkdownUrl } from "./urls.mjs";
+import { acceptsDocsMarkdown, createDocsMarkdownResponse, detectDocsMarkdownAgentRequest, hasDocsMarkdownSignatureAgent, renderDocsMarkdownDocument } from "./agent.mjs";
+import { buildNormalizedOpenApiModel } from "./openapi-operations.mjs";
+import { assertValidOpenApiContract } from "./openapi-contract.mjs";
+import { applyOpenApiOverlayDocuments } from "./openapi-overlays.mjs";
+import { renderNativeApiReferenceHtml } from "./native-api-reference.mjs";
+import { resolveOpenApiReferences, resolveOpenApiReferencesSync } from "./openapi-references.mjs";
+import { parse } from "yaml";
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { basename, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { getHtmlDocument } from "@scalar/core/libs/html-rendering";
+
+//#region src/api-reference.ts
+const NEXT_ROUTE_FILE_RE = /^route\.(ts|tsx|js|jsx)$/;
+const SVELTE_ROUTE_FILE_RE = /^\+server\.(ts|js)$/;
+const ASTRO_ROUTE_FILE_RE = /^[^.].*\.(ts|js|mts|mjs)$/;
+const NUXT_ROUTE_FILE_RE = /^[^.].*\.(ts|js|mts|mjs)$/;
+const TANSTACK_ROUTE_FILE_RE = /\.(ts|tsx|js|jsx)$/;
+const METHOD_RE = /export\s+(?:async\s+function|function|const)\s+(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD|ALL)\b/g;
+const METHOD_NAMES = [
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE",
+	"OPTIONS",
+	"HEAD"
+];
+const DEFAULT_API_REFERENCE_OPENAPI_ROUTE = "/api/docs?format=openapi";
+const OPENAPI_SPEC_FETCH_TIMEOUT_MS = 1e4;
+const OPENAPI_SPEC_MAX_BYTES = 5 * 1024 * 1024;
+function normalizePathSegment(value) {
+	return value.replace(/^\/+|\/+$/g, "");
+}
+function resolveApiReferenceConfig(value) {
+	if (value === true) return {
+		enabled: true,
+		path: "api-reference",
+		specUrl: void 0,
+		overlays: [],
+		versions: [],
+		defaultVersion: void 0,
+		catalogTargets: void 0,
+		renderer: void 0,
+		rendererOptions: void 0,
+		mcp: void 0,
+		routeRoot: "api",
+		exclude: []
+	};
+	if (!value) return {
+		enabled: false,
+		path: "api-reference",
+		specUrl: void 0,
+		overlays: [],
+		versions: [],
+		defaultVersion: void 0,
+		catalogTargets: void 0,
+		renderer: void 0,
+		rendererOptions: void 0,
+		mcp: void 0,
+		routeRoot: "api",
+		exclude: []
+	};
+	const specUrl = normalizeRemoteSpecUrl(value.specUrl);
+	const overlays = normalizeOpenApiOverlaySources(value.overlays, "apiReference.overlays");
+	const { versions, defaultVersion } = resolveApiReferenceVersions(value);
+	if (versions.length > 0 && specUrl) throw new Error("`apiReference.versions` cannot be combined with `apiReference.specUrl`.");
+	if (versions.length > 0 && overlays.length > 0) throw new Error("`apiReference.versions` cannot be combined with top-level `apiReference.overlays`; configure overlays on each version instead.");
+	const renderer = normalizeApiReferenceRenderer(value.renderer);
+	return {
+		enabled: value.enabled !== false,
+		path: normalizePathSegment(value.path ?? "api-reference"),
+		specUrl,
+		overlays,
+		versions,
+		defaultVersion,
+		catalogTargets: normalizeApiReferenceCatalogTargets(value.catalogTargets),
+		renderer: renderer?.name,
+		rendererOptions: renderer?.options,
+		mcp: resolveOpenApiMcpConfig(value.mcp),
+		routeRoot: normalizePathSegment(value.routeRoot ?? "api") || "api",
+		exclude: normalizeApiReferenceExcludes(value.exclude)
+	};
+}
+function normalizeOpenApiOverlaySources(value, location) {
+	if (value === void 0) return [];
+	if (!Array.isArray(value)) throw new Error(`\`${location}\` must be an array of sources.`);
+	return value.map((source, index) => {
+		if (typeof source !== "string" || !source.trim()) throw new Error(`\`${location}[${index}]\` must be a non-empty string.`);
+		return source.trim();
+	});
+}
+function resolveApiReferenceVersions(value) {
+	if (value.versions === void 0) {
+		if (value.defaultVersion !== void 0) throw new Error("`apiReference.defaultVersion` requires `apiReference.versions`.");
+		return { versions: [] };
+	}
+	if (!value.versions || typeof value.versions !== "object" || Array.isArray(value.versions)) throw new Error("`apiReference.versions` must be an object keyed by version identifier.");
+	const entries = Object.entries(value.versions);
+	if (entries.length === 0) throw new Error("`apiReference.versions` must not be empty.");
+	const defaultVersion = value.defaultVersion?.trim();
+	if (!defaultVersion) throw new Error("`apiReference.defaultVersion` is required when versions are configured.");
+	if (!Object.prototype.hasOwnProperty.call(value.versions, defaultVersion)) throw new Error(`\`apiReference.defaultVersion\` references unknown version \`${defaultVersion}\`.`);
+	return {
+		versions: entries.map(([id, rawVersion]) => resolveApiReferenceVersionConfig(id, rawVersion, defaultVersion)),
+		defaultVersion
+	};
+}
+function resolveApiReferenceVersionConfig(rawId, value, defaultVersion) {
+	const id = rawId.trim();
+	if (!id || !/^[a-zA-Z0-9](?:[a-zA-Z0-9._-]*[a-zA-Z0-9])?$/.test(id)) throw new Error(`OpenAPI version identifier \`${rawId}\` must be URL-safe and contain only letters, numbers, dots, underscores, or hyphens.`);
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`\`apiReference.versions.${id}\` must be an object.`);
+	const specUrl = normalizeRemoteSpecUrl(value.specUrl);
+	if (!specUrl) throw new Error(`\`apiReference.versions.${id}.specUrl\` is required.`);
+	return {
+		id,
+		label: value.label?.trim() || id,
+		specUrl,
+		overlays: normalizeOpenApiOverlaySources(value.overlays, `apiReference.versions.${id}.overlays`),
+		default: id === defaultVersion
+	};
+}
+function resolveOpenApiMcpConfig(value) {
+	if (!value) return void 0;
+	return value === true ? { enabled: true } : {
+		...value,
+		enabled: value.enabled !== false
+	};
+}
+function isApiReferenceRenderer(value) {
+	return value === "farming-labs" || value === "fumadocs" || value === "scalar";
+}
+function normalizeApiReferenceRenderer(value) {
+	if (isApiReferenceRenderer(value)) return { name: value };
+	if (!value || typeof value !== "object" || !isApiReferenceRenderer(value.name)) return;
+	if (value.options !== void 0 && (!value.options || typeof value.options !== "object" || Array.isArray(value.options))) return;
+	return {
+		name: value.name,
+		options: value.options
+	};
+}
+function resolveApiReferenceRenderer(value, _framework) {
+	const config = resolveApiReferenceConfig(value);
+	if (config.renderer) return config.renderer;
+	return "farming-labs";
+}
+function resolveApiReferenceOpenApiDiscovery(value, options = {}) {
+	const config = resolveApiReferenceConfig(value);
+	if (!config.enabled) return { enabled: false };
+	const selectedSpecUrl = resolveApiReferenceVersion(config)?.specUrl ?? config.specUrl;
+	const catalogTargets = config.catalogTargets ?? (!selectedSpecUrl || isRequestRelativeSpecUrl(selectedSpecUrl) ? ["/"] : void 0);
+	const route = options.route ?? DEFAULT_API_REFERENCE_OPENAPI_ROUTE;
+	const versions = config.versions.length > 0 ? config.versions.map((version) => ({
+		id: version.id,
+		label: version.label,
+		default: version.default,
+		url: appendUrlSearchParam(route, "version", version.id),
+		apiReferencePath: `/${config.path}/${encodeURIComponent(version.id)}`,
+		specUrl: isLocalSpecSource(version.specUrl) ? void 0 : version.specUrl
+	})) : void 0;
+	return {
+		enabled: true,
+		url: route,
+		urlSource: options.route === void 0 ? "default" : "configured",
+		source: selectedSpecUrl ? "configured" : "generated",
+		specUrl: isLocalSpecSource(selectedSpecUrl) ? void 0 : selectedSpecUrl,
+		apiReferencePath: `/${config.path}`,
+		catalogTargets,
+		versions
+	};
+}
+function appendUrlSearchParam(url, name, value) {
+	const [withoutHash, hash] = url.split("#", 2);
+	return `${withoutHash}${withoutHash.includes("?") ? "&" : "?"}${encodeURIComponent(name)}=${encodeURIComponent(value)}${hash === void 0 ? "" : `#${hash}`}`;
+}
+function resolveApiReferenceVersion(config, requestedVersion) {
+	if (config.versions.length === 0) return void 0;
+	const versionId = requestedVersion?.trim() || config.defaultVersion;
+	return config.versions.find((version) => version.id === versionId);
+}
+function resolveApiReferenceVersionFromPathname(value, pathname) {
+	const config = resolveApiReferenceConfig(value);
+	if (config.versions.length === 0) return void 0;
+	const pathSegments = normalizePathSegment(config.path).split("/").filter(Boolean);
+	const pathnameSegments = pathname.split("/").filter(Boolean);
+	if (!pathSegments.every((segment, index) => pathnameSegments[index] === segment)) return;
+	const rawVersion = pathnameSegments[pathSegments.length];
+	if (!rawVersion) return void 0;
+	try {
+		return resolveApiReferenceVersion(config, decodeURIComponent(rawVersion));
+	} catch {
+		return;
+	}
+}
+function isApiReferenceOpenApiRequest(url) {
+	return url.searchParams.get("format")?.trim() === "openapi";
+}
+function normalizeRemoteSpecUrl(value) {
+	const trimmed = value?.trim();
+	if (!trimmed) return void 0;
+	return trimmed;
+}
+function normalizeApiReferenceCatalogTargets(value) {
+	if (value === void 0) return void 0;
+	return Array.from(new Set(value.filter((target) => typeof target === "string").map((target) => target.trim()).filter(Boolean)));
+}
+function isRequestRelativeSpecUrl(value) {
+	return typeof value === "string" && value.startsWith("/") && !value.startsWith("//");
+}
+function isRemoteSpecUrl(value) {
+	return /^(?:https?:)?\/\//i.test(value);
+}
+function isLocalSpecSource(value) {
+	if (!value) return false;
+	if (value.startsWith("file:")) return true;
+	return !isRemoteSpecUrl(value) && !isRequestRelativeSpecUrl(value) && !/^[a-z][a-z\d+.-]*:/i.test(value);
+}
+function buildApiReferencePageTitle(config, title = "API Reference") {
+	const template = config.metadata?.titleTemplate;
+	if (!template) return title;
+	return template.replace("%s", title);
+}
+function buildApiReferenceScalarCss(config) {
+	const theme = resolveTheme(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 ?? 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: ${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};
+  --scalar-theme-background: ${background};
+  --scalar-theme-card: ${card};
+  --scalar-theme-foreground: ${foreground};
+}
+
+.dark-mode {
+  --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: ${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: ${primaryForeground};
+  --scalar-button-1-hover: color-mix(in srgb, var(--scalar-theme-primary) 88%, white 12%);
+}
+
+.light-mode {
+  --scalar-background-1: var(--scalar-theme-background);
+  --scalar-background-2: color-mix(in srgb, var(--scalar-theme-card) 92%, white 8%);
+  --scalar-background-3: color-mix(in srgb, var(--scalar-theme-card) 84%, black 4%);
+  --scalar-color-1: var(--scalar-theme-foreground);
+  --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: ${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: ${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 {
+  width: min(${sidebarWidth}px, 100vw);
+  border-right: 1px solid var(--scalar-border-color);
+}
+
+.scalar-card,
+.t-doc__sidebar,
+.references-layout .reference-layout__content .request-card,
+.references-layout .reference-layout__content .response-card,
+.references-layout .reference-layout__content .scalar-card-header,
+.references-layout .reference-layout__content .scalar-card-footer,
+.references-layout .reference-layout__content .section,
+.references-layout .reference-layout__content .section-container {
+  border-color: var(--scalar-border-color) !important;
+}
+
+.t-doc__sidebar,
+.t-doc__sidebar * {
+  font-family: var(--scalar-font);
+}
+
+.t-doc__sidebar .sidebar-search {
+  margin: 0.5rem 0 1rem;
+}
+
+.t-doc__sidebar .sidebar-search input {
+  border-radius: var(--scalar-radius-sm);
+}
+
+.t-doc__sidebar .sidebar-item,
+.t-doc__sidebar .sidebar-heading {
+  border-radius: var(--scalar-radius-sm);
+}
+
+.t-doc__sidebar .sidebar-group-label {
+  font-size: 0.72rem;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--scalar-color-3);
+}
+
+.t-doc__sidebar .sidebar-item--active {
+  font-weight: 600;
+}
+
+.scalar-card,
+.references-layout .reference-layout__content .request-card,
+.references-layout .reference-layout__content .response-card {
+  border-radius: var(--scalar-radius);
+}
+
+.references-layout .reference-layout__content {
+  padding-top: 1.5rem;
+}
+
+.references-layout .section-content,
+.references-layout .section-flare {
+  background: transparent;
+}
+
+.references-layout .reference-layout__content,
+.references-layout .reference-layout__content * {
+  font-family: var(--scalar-font);
+}
+
+.references-layout code,
+.references-layout pre,
+.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) {
+	const apiReference = resolveApiReferenceConfig(config.apiReference);
+	const selectedVersion = resolveApiReferenceVersion(apiReference, options.version);
+	if (apiReference.versions.length > 0 && !selectedVersion) return buildUnavailableOpenApiDocument(config, `Unknown OpenAPI version \`${options.version}\`. Available versions: ${apiReference.versions.map((version) => version.id).join(", ")}.`);
+	const specUrl = selectedVersion?.specUrl ?? apiReference.specUrl;
+	const overlays = selectedVersion?.overlays ?? apiReference.overlays;
+	if (specUrl) {
+		if (isLocalSpecSource(specUrl)) try {
+			if (overlays.some((overlay) => !isLocalSpecSource(overlay))) throw new Error("Remote OpenAPI overlays require the async API reference builder.");
+			return normalizeConfiguredOpenApiDocument(readLocalOpenApiDocument(specUrl, options.rootDir, overlays), config, options.baseUrl, specUrl, selectedVersion);
+		} catch (error) {
+			return buildUnavailableOpenApiDocument(config, `Unable to load the configured OpenAPI document. ${error instanceof Error ? error.message : "Unknown error"}`);
+		}
+		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, options.baseUrl);
+}
+async function buildApiReferenceOpenApiDocumentAsync(config, options) {
+	try {
+		return await loadApiReferenceOpenApiDocumentAsync(config, options);
+	} catch (error) {
+		return buildUnavailableOpenApiDocument(config, `Unable to load the configured OpenAPI document. ${error instanceof Error ? error.message : "Unknown error"}`);
+	}
+}
+/**
+* Load the resolved OpenAPI document without replacing diagnostics with an unavailable schema.
+* This is used by CLI health checks that need the original parsing, reference, and overlay error.
+*/
+async function loadApiReferenceOpenApiDocumentAsync(config, options) {
+	const apiReference = resolveApiReferenceConfig(config.apiReference);
+	const selectedVersion = resolveApiReferenceVersion(apiReference, options.version);
+	if (apiReference.versions.length > 0 && !selectedVersion) throw new Error(`Unknown OpenAPI version \`${options.version}\`. Available versions: ${apiReference.versions.map((version) => version.id).join(", ")}.`);
+	const specUrl = selectedVersion?.specUrl ?? apiReference.specUrl;
+	const overlays = selectedVersion?.overlays ?? apiReference.overlays;
+	if (!specUrl) return buildApiReferenceOpenApiDocument(config, options);
+	return normalizeConfiguredOpenApiDocument(isLocalSpecSource(specUrl) ? await readLocalOpenApiDocumentAsync(specUrl, options.rootDir, overlays, options.baseUrl) : await fetchRemoteOpenApiDocument(specUrl, options.baseUrl, overlays, options.rootDir), config, options.baseUrl, specUrl, selectedVersion);
+}
+/**
+* Build deterministic, operation-level source pages from every configured OpenAPI version.
+*
+* These pages are framework-neutral projections used by documentation search and other
+* read-only knowledge surfaces. They never inherit MCP execution headers or credentials.
+*/
+async function buildApiReferenceOperationPagesAsync(config, options) {
+	const apiReference = resolveApiReferenceConfig(config.apiReference);
+	if (!apiReference.enabled) return [];
+	const versions = apiReference.versions.length > 0 ? apiReference.versions : [void 0];
+	return (await Promise.all(versions.map(async (version) => {
+		const model = buildNormalizedOpenApiModel(await buildApiReferenceOpenApiDocumentAsync(config, {
+			...options,
+			version: version?.id
+		}));
+		const basePath = `/${apiReference.path}${version ? `/${encodeURIComponent(version.id)}` : ""}`;
+		return model.operations.map((operation) => {
+			const url = `${basePath}/operations/${encodeURIComponent(operation.slug)}`;
+			const content = renderApiReferenceOperationMarkdown(operation, {
+				apiTitle: model.title,
+				apiVersion: version?.label ?? model.version,
+				specificationVersion: model.specificationVersion
+			});
+			const description = operation.summary ?? operation.description ?? operation.selector;
+			return {
+				title: operation.title,
+				url,
+				canonicalUrl: url,
+				content,
+				description,
+				rawContent: content,
+				agentContent: content,
+				agentRawContent: content,
+				type: "api",
+				...options.locale ? { locale: options.locale } : {},
+				...version?.id || model.version ? { version: version?.id ?? model.version } : {},
+				tags: Array.from(new Set([
+					"openapi",
+					operation.method.toLowerCase(),
+					...operation.tags
+				]))
+			};
+		});
+	}))).flat();
+}
+function normalizeApiReferenceMarkdownPath(value) {
+	const trimmed = value.trim().replace(/\.md$/i, "");
+	if (!trimmed) return "/";
+	return `/${trimmed.replace(/^\/+|\/+$/g, "")}`.replace(/\/{2,}/g, "/");
+}
+function isApiReferenceOperationPath(pathname, apiReferencePath) {
+	const basePath = `/${normalizePathSegment(apiReferencePath)}`;
+	if (!pathname.startsWith(`${basePath}/`)) return false;
+	const segments = pathname.slice(basePath.length + 1).split("/");
+	return segments.length === 2 && segments[0] === "operations" && Boolean(segments[1]) || segments.length === 3 && segments[1] === "operations" && Boolean(segments[0] && segments[2]);
+}
+function resolveApiReferenceOperationMarkdownPath(request, apiReferencePath, apiRoute = "/api/docs") {
+	if (request.method !== "GET" && request.method !== "HEAD") return null;
+	const url = new URL(request.url);
+	const pathname = normalizeApiReferenceMarkdownPath(url.pathname);
+	if (pathname === normalizeApiReferenceMarkdownPath(apiRoute) && url.searchParams.get("format")?.trim() === "markdown") {
+		const requestedPath = normalizeApiReferenceMarkdownPath(url.searchParams.get("path")?.trim() ?? "");
+		return isApiReferenceOperationPath(requestedPath, apiReferencePath) ? requestedPath : null;
+	}
+	if (url.pathname.toLowerCase().endsWith(".md")) return isApiReferenceOperationPath(pathname, apiReferencePath) ? pathname : null;
+	return (acceptsDocsMarkdown(request) || hasDocsMarkdownSignatureAgent(request) || detectDocsMarkdownAgentRequest(request).detected) && isApiReferenceOperationPath(pathname, apiReferencePath) ? pathname : null;
+}
+/**
+* Resolve a public per-operation Markdown request using the same generated projection as search,
+* Ask AI, and MCP. Returns `null` when the request is not an API operation Markdown route.
+*/
+async function createApiReferenceOperationMarkdownResponse(config, options) {
+	const apiReference = resolveApiReferenceConfig(config.apiReference);
+	if (!apiReference.enabled) return null;
+	const requestedPath = resolveApiReferenceOperationMarkdownPath(options.request, apiReference.path, options.apiRoute);
+	if (!requestedPath) return null;
+	const requestUrl = new URL(options.request.url);
+	const origin = options.origin ?? options.baseUrl ?? requestUrl.origin;
+	const operationPages = options.operationPages ? await (typeof options.operationPages === "function" ? options.operationPages() : options.operationPages) : await buildApiReferenceOperationPagesAsync(config, {
+		framework: options.framework,
+		rootDir: options.rootDir,
+		baseUrl: options.baseUrl ?? requestUrl.origin,
+		locale: options.locale
+	});
+	const page = operationPages.find((candidate) => normalizeApiReferenceMarkdownPath(candidate.url) === requestedPath);
+	const canonicalPath = page?.canonicalUrl ?? page?.url ?? requestedPath;
+	const canonicalUrl = new URL(canonicalPath, origin).toString();
+	const contentLocation = new URL(toDocsMarkdownUrl(page?.url ?? requestedPath), origin).toString();
+	const relativeRequestedPath = requestedPath.slice(`/${apiReference.path}`.length).replace(/^\/+/, "");
+	return createDocsMarkdownResponse({
+		request: options.request,
+		apiRoute: options.apiRoute,
+		document: page ? renderDocsMarkdownDocument(page, {
+			origin,
+			sitemap: options.sitemap,
+			okf: options.okf
+		}) : null,
+		entry: apiReference.path,
+		requestedPath: relativeRequestedPath,
+		origin,
+		locale: options.locale,
+		canonicalUrl,
+		contentLocation,
+		pages: [...options.pages ?? [], ...operationPages],
+		sitemap: options.sitemap
+	});
+}
+function renderApiReferenceOperationMarkdown(operation, metadata) {
+	const lines = [
+		`# ${operation.title}`,
+		"",
+		`\`${operation.method} ${operation.path}\``,
+		"",
+		`- Operation ID: \`${operation.operationId}\``,
+		`- API: ${metadata.apiTitle}`,
+		`- API version: ${metadata.apiVersion}`,
+		`- OpenAPI: ${metadata.specificationVersion}`
+	];
+	if (operation.tags.length > 0) lines.push(`- Tags: ${operation.tags.join(", ")}`);
+	if (operation.deprecated) lines.push("- Deprecated: yes");
+	if (operation.description && operation.description !== operation.title) lines.push("", operation.description);
+	if (operation.servers.length > 0) lines.push("", "## Servers", "", ...operation.servers.map((server) => `- ${server}`));
+	if (operation.parameters.length > 0) {
+		lines.push("", "## Parameters", "");
+		for (const parameter of operation.parameters) lines.push(renderApiReferenceParameter(parameter));
+	}
+	if (operation.requestBody) {
+		lines.push("", "## Request body", "");
+		if (operation.requestBody.description) lines.push(operation.requestBody.description, "");
+		lines.push(`Required: ${operation.requestBody.required ? "yes" : "no"}`);
+		appendApiReferenceMediaTypes(lines, operation.requestBody.content);
+	}
+	if (operation.responses.length > 0) {
+		lines.push("", "## Responses", "");
+		for (const response of operation.responses) {
+			lines.push(`### ${response.status}`, "", response.description ?? "No response description.");
+			appendApiReferenceMediaTypes(lines, response.content);
+			lines.push("");
+		}
+	}
+	if (operation.security.length > 0) {
+		lines.push("", "## Security", "");
+		for (const requirement of operation.security) {
+			const schemes = Object.entries(requirement).map(([name, scopes]) => scopes.length > 0 ? `${name} (${scopes.join(", ")})` : name);
+			lines.push(`- ${schemes.join(" and ")}`);
+		}
+	}
+	return `${lines.join("\n").trim()}\n`;
+}
+function renderApiReferenceParameter(parameter) {
+	const details = [parameter.in, parameter.required ? "required" : "optional"];
+	const schema = renderApiReferenceSchema(parameter.schema);
+	if (schema) details.push(schema);
+	return `- \`${parameter.name}\` (${details.join(", ")})${parameter.description ? ` — ${parameter.description}` : ""}`;
+}
+function appendApiReferenceMediaTypes(lines, content) {
+	for (const media of content) {
+		lines.push("", `- Content type: \`${media.mediaType}\``);
+		const schema = renderApiReferenceSchema(media.schema);
+		if (schema) lines.push(`  Schema: \`${schema}\``);
+		for (const example of media.examples) {
+			const value = renderApiReferenceSchema(example.value);
+			lines.push(`  Example ${example.name}: ${value ? `\`${value}\`` : "available"}`);
+		}
+	}
+}
+function renderApiReferenceSchema(value) {
+	if (value === void 0) return void 0;
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean" || value === null) return String(value);
+	try {
+		const serialized = JSON.stringify(value);
+		return serialized.length > 500 ? `${serialized.slice(0, 497)}...` : serialized;
+	} catch {
+		return;
+	}
+}
+function buildOpenApiDocumentFromRoutes(config, framework, routes, baseUrl) {
+	const tags = Array.from(new Set(routes.map((route) => route.tag))).map((name) => ({
+		name,
+		description: `${name} endpoints`
+	}));
+	return {
+		openapi: "3.1.0",
+		info: {
+			title: "API Reference",
+			description: config.metadata?.description ?? `Generated API reference for ${framework}.`,
+			version: "0.0.0"
+		},
+		servers: [{ url: baseUrl ?? "/" }],
+		tags,
+		paths: buildOpenApiPaths(routes)
+	};
+}
+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 version = resolveApiReferenceVersion(apiReference, options.version);
+	const basePath = `/${apiReference.path}${version ? `/${encodeURIComponent(version.id)}` : ""}`;
+	if (resolveApiReferenceRenderer(config.apiReference, options.framework) === "farming-labs") {
+		const model = buildNormalizedOpenApiModel(document);
+		const info = document.info && typeof document.info === "object" && !Array.isArray(document.info) ? document.info : void 0;
+		const title = options.title ?? model.title;
+		const openApiUrl = version ? appendUrlSearchParam(DEFAULT_API_REFERENCE_OPENAPI_ROUTE, "version", version.id) : DEFAULT_API_REFERENCE_OPENAPI_ROUTE;
+		return renderNativeApiReferenceHtml({
+			model,
+			pageTitle: buildApiReferencePageTitle(config, version ? `${title} – ${version.label}` : title),
+			title: version ? `${title} – ${version.label}` : title,
+			description: typeof info?.description === "string" && info.description.trim() ? info.description : config.metadata?.description,
+			basePath,
+			openApiUrl,
+			activeVersion: version?.id,
+			versions: apiReference.versions.map((entry) => ({
+				id: entry.id,
+				label: entry.label,
+				href: `/${apiReference.path}/${encodeURIComponent(entry.id)}`,
+				active: entry.id === version?.id
+			})),
+			theme: resolveTheme(config)
+		});
+	}
+	const title = options.title ?? "API Reference";
+	return getHtmlDocument({
+		pageTitle: buildApiReferencePageTitle(config, title),
+		title,
+		content: () => document,
+		theme: "deepSpace",
+		layout: "modern",
+		customCss: buildApiReferenceScalarCss(config),
+		pathRouting: { basePath },
+		showSidebar: true,
+		defaultOpenFirstTag: true,
+		tagsSorter: "alpha",
+		operationsSorter: "alpha",
+		operationTitleSource: "summary",
+		defaultHttpClient: {
+			targetKey: "shell",
+			clientKey: "curl"
+		},
+		documentDownloadType: "json"
+	});
+}
+async function fetchRemoteOpenApiDocument(specUrl, baseUrl, overlays = [], rootDir = process.cwd()) {
+	let url;
+	try {
+		url = baseUrl ? new URL(specUrl, baseUrl) : new URL(specUrl);
+	} catch {
+		throw new Error(baseUrl ? "`apiReference.specUrl` must be an absolute URL or a request-relative path." : "`apiReference.specUrl` must be an absolute URL.");
+	}
+	const entry = await fetchOpenApiReferenceDocument(url, true);
+	return resolveOpenApiReferences(await applyConfiguredOpenApiOverlaysAsync(entry.document, overlays, rootDir, baseUrl), {
+		sourceUri: entry.uri,
+		loadDocument: async (referenceUrl) => {
+			if (referenceUrl.protocol !== "http:" && referenceUrl.protocol !== "https:") throw new Error(`Remote OpenAPI documents cannot load non-HTTP references: ${referenceUrl.href}`);
+			return fetchOpenApiReferenceDocument(referenceUrl, false);
+		}
+	});
+}
+async function fetchOpenApiReferenceDocument(url, validateContract) {
+	if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error("`apiReference.specUrl` must use HTTP or HTTPS for remote documents.");
+	const abortController = new AbortController();
+	const timeout = setTimeout(() => abortController.abort(), OPENAPI_SPEC_FETCH_TIMEOUT_MS);
+	let response;
+	let body;
+	try {
+		response = await fetch(url, {
+			headers: { accept: "application/json, application/yaml, application/x-yaml, text/yaml, text/x-yaml" },
+			redirect: "follow",
+			signal: abortController.signal
+		});
+		if (!response.ok) throw new Error(`Received ${response.status} ${response.statusText}`.trim());
+		if (response.url) {
+			const responseUrl = new URL(response.url);
+			if (responseUrl.protocol !== "http:" && responseUrl.protocol !== "https:") throw new Error("The remote OpenAPI endpoint redirected to a non-HTTP URL.");
+		}
+		body = await readOpenApiResponseBody(response);
+	} catch (error) {
+		if (abortController.signal.aborted) throw new Error(`The remote OpenAPI endpoint did not respond within ${OPENAPI_SPEC_FETCH_TIMEOUT_MS / 1e3} seconds.`);
+		throw error;
+	} finally {
+		clearTimeout(timeout);
+	}
+	if (!body.trim()) throw new Error("The remote endpoint returned an empty response.");
+	const sourceUri = response.url || url.href;
+	return {
+		uri: sourceUri,
+		document: parseOpenApiDocument(body, sourceUri, response.headers.get("content-type"), "remote", validateContract)
+	};
+}
+async function readOpenApiResponseBody(response) {
+	const contentLength = response.headers.get("content-length");
+	if (contentLength) {
+		const declaredBytes = Number(contentLength);
+		if (Number.isFinite(declaredBytes) && declaredBytes > OPENAPI_SPEC_MAX_BYTES) throw new Error(`The remote OpenAPI document exceeds the ${formatByteLimit(OPENAPI_SPEC_MAX_BYTES)} size limit.`);
+	}
+	if (!response.body) return "";
+	const reader = response.body.getReader();
+	const decoder = new TextDecoder();
+	let receivedBytes = 0;
+	let body = "";
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			receivedBytes += value.byteLength;
+			if (receivedBytes > OPENAPI_SPEC_MAX_BYTES) {
+				await reader.cancel();
+				throw new Error(`The remote OpenAPI document exceeds the ${formatByteLimit(OPENAPI_SPEC_MAX_BYTES)} size limit.`);
+			}
+			body += decoder.decode(value, { stream: true });
+		}
+		body += decoder.decode();
+		return body;
+	} finally {
+		reader.releaseLock();
+	}
+}
+function formatByteLimit(bytes) {
+	return `${bytes / (1024 * 1024)} MiB`;
+}
+function readLocalOpenApiDocument(specUrl, rootDir = process.cwd(), overlays = []) {
+	const filePath = resolveLocalOpenApiFilePath(specUrl, rootDir);
+	const document = readOpenApiFileDocument(filePath, true);
+	const trustedRoot = specUrl.startsWith("file:") ? void 0 : realpathSync(resolve(rootDir));
+	return resolveOpenApiReferencesSync(applyConfiguredOpenApiOverlaysSync(document, overlays, rootDir), {
+		sourceUri: pathToFileURL(filePath).href,
+		loadDocument: (referenceUrl) => {
+			if (referenceUrl.protocol === "http:" || referenceUrl.protocol === "https:") throw new Error("Remote OpenAPI references require the async API reference builder.");
+			return readOpenApiFileReference(referenceUrl, trustedRoot);
+		}
+	});
+}
+async function readLocalOpenApiDocumentAsync(specUrl, rootDir = process.cwd(), overlays = [], baseUrl) {
+	const filePath = resolveLocalOpenApiFilePath(specUrl, rootDir);
+	const document = await readOpenApiFileDocumentAsync(filePath, true);
+	const trustedRoot = specUrl.startsWith("file:") ? void 0 : realpathSync(resolve(rootDir));
+	return resolveOpenApiReferences(await applyConfiguredOpenApiOverlaysAsync(document, overlays, rootDir, baseUrl), {
+		sourceUri: pathToFileURL(filePath).href,
+		loadDocument: async (referenceUrl, fromUrl) => {
+			if (referenceUrl.protocol === "http:" || referenceUrl.protocol === "https:") return fetchOpenApiReferenceDocument(referenceUrl, false);
+			if (fromUrl.protocol === "http:" || fromUrl.protocol === "https:") throw new Error(`Remote OpenAPI documents cannot load local file references: ${referenceUrl.href}`);
+			return readOpenApiFileReferenceAsync(referenceUrl, trustedRoot);
+		}
+	});
+}
+function applyConfiguredOpenApiOverlaysSync(document, overlays, rootDir) {
+	if (overlays.length === 0) return document;
+	const result = applyOpenApiOverlayDocuments(document, overlays.map((source) => {
+		if (!isLocalSpecSource(source)) throw new Error("Remote OpenAPI overlays require the async API reference builder.");
+		return {
+			source,
+			document: readOpenApiFileDocument(resolveLocalOpenApiFilePath(source, rootDir), false)
+		};
+	}));
+	assertValidOpenApiContract(result);
+	return result;
+}
+async function applyConfiguredOpenApiOverlaysAsync(document, overlays, rootDir, baseUrl) {
+	if (overlays.length === 0) return document;
+	const result = applyOpenApiOverlayDocuments(document, await Promise.all(overlays.map(async (source) => {
+		if (isLocalSpecSource(source)) return {
+			source,
+			document: await readOpenApiFileDocumentAsync(resolveLocalOpenApiFilePath(source, rootDir), false)
+		};
+		let url;
+		try {
+			url = baseUrl ? new URL(source, baseUrl) : new URL(source);
+		} catch {
+			throw new Error(baseUrl ? `OpenAPI overlay \`${source}\` must be an absolute URL or a request-relative path.` : `OpenAPI overlay \`${source}\` must be an absolute URL.`);
+		}
+		return {
+			source,
+			document: (await fetchOpenApiReferenceDocument(url, false)).document
+		};
+	})));
+	assertValidOpenApiContract(result);
+	return result;
+}
+function readOpenApiFileReference(url, trustedRoot) {
+	if (url.protocol !== "file:") throw new Error(`Local OpenAPI documents cannot load this reference: ${url.href}`);
+	const filePath = resolveReferencedOpenApiFilePath(url, trustedRoot);
+	return {
+		uri: pathToFileURL(filePath).href,
+		document: readOpenApiFileDocument(filePath, false)
+	};
+}
+async function readOpenApiFileReferenceAsync(url, trustedRoot) {
+	if (url.protocol !== "file:") throw new Error(`Local OpenAPI documents cannot load this reference: ${url.href}`);
+	const filePath = resolveReferencedOpenApiFilePath(url, trustedRoot);
+	return {
+		uri: pathToFileURL(filePath).href,
+		document: await readOpenApiFileDocumentAsync(filePath, false)
+	};
+}
+function readOpenApiFileDocument(filePath, validateContract) {
+	assertOpenApiFileSize(filePath);
+	const body = readFileSync(filePath, "utf-8");
+	if (!body.trim()) throw new Error(`The local OpenAPI file is empty: ${filePath}`);
+	return parseOpenApiDocument(body, filePath, void 0, "local", validateContract);
+}
+async function readOpenApiFileDocumentAsync(filePath, validateContract) {
+	assertOpenApiFileSize(filePath);
+	const body = await readFile(filePath, "utf-8");
+	if (!body.trim()) throw new Error(`The local OpenAPI file is empty: ${filePath}`);
+	return parseOpenApiDocument(body, filePath, void 0, "local", validateContract);
+}
+function assertOpenApiFileSize(filePath) {
+	if (statSync(filePath).size > OPENAPI_SPEC_MAX_BYTES) throw new Error(`The local OpenAPI document exceeds the ${formatByteLimit(OPENAPI_SPEC_MAX_BYTES)} size limit: ${filePath}`);
+}
+function resolveLocalOpenApiFilePath(specUrl, rootDir) {
+	if (specUrl.startsWith("file:")) return fileURLToPath(new URL(specUrl));
+	const resolvedRoot = resolve(rootDir);
+	return resolveContainedOpenApiFilePath(resolve(resolvedRoot, specUrl), realpathSync(resolvedRoot));
+}
+function resolveReferencedOpenApiFilePath(url, trustedRoot) {
+	const filePath = fileURLToPath(url);
+	return trustedRoot ? resolveContainedOpenApiFilePath(filePath, trustedRoot) : realpathSync(filePath);
+}
+function resolveContainedOpenApiFilePath(filePath, realRoot) {
+	const realFilePath = realpathSync(filePath);
+	const relativePath = relative(realRoot, realFilePath);
+	if (relativePath === ".." || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath)) throw new Error("Project-relative OpenAPI files must stay inside the project root. Use an explicit `file:` URL for an external local file.");
+	return realFilePath;
+}
+function parseOpenApiDocument(body, source, contentType, sourceKind, validateContract = true) {
+	const extension = getOpenApiSourceExtension(source);
+	const normalizedContentType = contentType?.split(";", 1)[0]?.trim().toLowerCase();
+	const format = normalizedContentType?.includes("yaml") || extension === ".yaml" || extension === ".yml" ? "yaml" : normalizedContentType?.includes("json") || extension === ".json" ? "json" : "auto";
+	let parsed;
+	try {
+		if (format === "yaml") parsed = parse(body);
+		else if (format === "json") parsed = JSON.parse(body);
+		else try {
+			parsed = JSON.parse(body);
+		} catch {
+			parsed = parse(body);
+		}
+	} catch {
+		const location = sourceKind === "remote" ? "remote endpoint" : "local file";
+		const verb = sourceKind === "remote" ? "return" : "contain";
+		const expectedFormat = format === "auto" ? "JSON or YAML" : format.toUpperCase();
+		throw new Error(`The ${location} did not ${verb} valid ${expectedFormat}.`);
+	}
+	if (validateContract && (!parsed || typeof parsed !== "object" || Array.isArray(parsed))) throw new Error("The configured source contains a value instead of an OpenAPI object.");
+	if (validateContract) assertValidOpenApiContract(parsed);
+	return parsed;
+}
+function getOpenApiSourceExtension(source) {
+	try {
+		return extname(new URL(source, "https://farming-labs.invalid").pathname).toLowerCase();
+	} catch {
+		return extname(source).toLowerCase();
+	}
+}
+function normalizeConfiguredOpenApiDocument(document, config, baseUrl, specUrl, version) {
+	const info = document.info && typeof document.info === "object" && !Array.isArray(document.info) ? document.info : {};
+	const model = buildNormalizedOpenApiModel(document);
+	const normalizedPaths = normalizeRemoteOpenApiPaths(document.paths);
+	const normalizedTags = normalizeRemoteOpenApiTags(document.tags, normalizedPaths, model.tags);
+	const normalizedServers = isRequestRelativeSpecUrl(specUrl) ? [{ url: baseUrl ?? "/" }] : document.servers;
+	return {
+		...document,
+		info: {
+			title: "API Reference",
+			version: "0.0.0",
+			...info,
+			description: typeof info.description === "string" && info.description.trim() ? info.description : config.metadata?.description
+		},
+		servers: normalizedServers,
+		paths: normalizedPaths,
+		tags: normalizedTags,
+		...version ? { "x-farming-labs-api-version": {
+			id: version.id,
+			label: version.label,
+			default: version.default
+		} } : {}
+	};
+}
+function normalizeRemoteOpenApiPaths(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return;
+	const paths = value;
+	const normalized = {};
+	for (const [routePath, pathItem] of Object.entries(paths)) {
+		if (!pathItem || typeof pathItem !== "object" || Array.isArray(pathItem)) continue;
+		const normalizedPathItem = { ...pathItem };
+		for (const method of [
+			"get",
+			"post",
+			"put",
+			"patch",
+			"delete",
+			"options",
+			"head",
+			"trace"
+		]) {
+			const operation = normalizedPathItem[method];
+			if (!operation || typeof operation !== "object" || Array.isArray(operation)) continue;
+			const operationRecord = operation;
+			const tags = Array.isArray(operationRecord.tags) ? operationRecord.tags.filter((tag) => typeof tag === "string" && tag.trim().length > 0) : [];
+			normalizedPathItem[method] = {
+				...operationRecord,
+				tags: tags.length > 0 ? tags : [inferRemoteOpenApiTag(routePath)]
+			};
+		}
+		normalized[routePath] = normalizedPathItem;
+	}
+	return normalized;
+}
+function inferRemoteOpenApiTag(routePath) {
+	return humanizeSegment(routePath.split("/").filter(Boolean).find((value) => !value.startsWith("{")) ?? "general");
+}
+function normalizeRemoteOpenApiTags(value, paths, modelTags = []) {
+	const existingTags = Array.isArray(value) ? value.filter((tag) => !!tag && typeof tag === "object") : [];
+	const tagsByName = /* @__PURE__ */ new Map();
+	for (const tag of existingTags) {
+		const name = typeof tag.name === "string" && tag.name.trim() ? tag.name.trim() : void 0;
+		if (!name) continue;
+		tagsByName.set(name, tag);
+	}
+	for (const name of modelTags) if (!tagsByName.has(name)) tagsByName.set(name, {
+		name,
+		description: `${name} endpoints`
+	});
+	if (paths) for (const pathItem of Object.values(paths)) for (const method of [
+		"get",
+		"post",
+		"put",
+		"patch",
+		"delete",
+		"options",
+		"head",
+		"trace"
+	]) {
+		const operation = pathItem[method];
+		if (!operation || typeof operation !== "object" || Array.isArray(operation)) continue;
+		const tags = Array.isArray(operation.tags) ? operation.tags : [];
+		for (const tag of tags) {
+			if (typeof tag !== "string" || !tag.trim()) continue;
+			if (!tagsByName.has(tag)) tagsByName.set(tag, {
+				name: tag,
+				description: `${tag} endpoints`
+			});
+		}
+	}
+	if (tagsByName.size === 0) return [{
+		name: "General",
+		description: "General endpoints"
+	}];
+	return Array.from(tagsByName.values());
+}
+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 [];
+	const rootDir = options.rootDir ?? process.cwd();
+	switch (options.framework) {
+		case "next": return buildFileConventionRoutes({
+			rootDir,
+			sourceDir: resolveRootedDir(rootDir, apiReference.routeRoot, getNextAppDir(rootDir)),
+			routePathBase: toRouteBase(apiReference.routeRoot, getNextAppDir(rootDir)),
+			isRouteFile: (name) => NEXT_ROUTE_FILE_RE.test(name),
+			toRouteSegments: (relativeFile) => relativeFile.split("/").slice(0, -1).filter(Boolean),
+			exclude: apiReference.exclude
+		});
+		case "farmjs": return buildFileConventionRoutes({
+			rootDir,
+			sourceDir: resolveRootedDir(rootDir, apiReference.routeRoot, getFarmAppDir(rootDir)),
+			routePathBase: toRouteBase(apiReference.routeRoot, getFarmAppDir(rootDir)),
+			isRouteFile: (name) => NEXT_ROUTE_FILE_RE.test(name),
+			toRouteSegments: (relativeFile) => relativeFile.split("/").slice(0, -1).filter(Boolean),
+			exclude: apiReference.exclude
+		});
+		case "sveltekit": return buildFileConventionRoutes({
+			rootDir,
+			sourceDir: resolveRootedDir(rootDir, apiReference.routeRoot, "src/routes"),
+			routePathBase: toRouteBase(apiReference.routeRoot, "src/routes"),
+			isRouteFile: (name) => SVELTE_ROUTE_FILE_RE.test(name),
+			toRouteSegments: (relativeFile) => relativeFile.split("/").slice(0, -1).filter(Boolean),
+			exclude: apiReference.exclude
+		});
+		case "astro": return buildFileConventionRoutes({
+			rootDir,
+			sourceDir: resolveRootedDir(rootDir, apiReference.routeRoot, "src/pages"),
+			routePathBase: toRouteBase(apiReference.routeRoot, "src/pages"),
+			isRouteFile: (name) => ASTRO_ROUTE_FILE_RE.test(name),
+			toRouteSegments: (relativeFile) => routeSegmentsFromEndpointFile(relativeFile),
+			exclude: apiReference.exclude
+		});
+		case "nuxt": return buildFileConventionRoutes({
+			rootDir,
+			sourceDir: resolveRootedDir(rootDir, apiReference.routeRoot, "server"),
+			routePathBase: toRouteBase(apiReference.routeRoot, "server"),
+			isRouteFile: (name) => NUXT_ROUTE_FILE_RE.test(name),
+			toRouteSegments: (relativeFile) => routeSegmentsFromEndpointFile(stripNuxtMethodSuffix(relativeFile)),
+			exclude: apiReference.exclude,
+			getMethods: (source, file) => extractNuxtMethods(source, file)
+		});
+		case "tanstack-start": return buildTanstackRoutes(rootDir, apiReference);
+	}
+}
+function getFarmAppDir(rootDir) {
+	return existsSync(join(rootDir, "src", "app")) ? "src/app" : "app";
+}
+function buildFileConventionRoutes({ rootDir, sourceDir, routePathBase, isRouteFile, toRouteSegments, exclude, getMethods = extractMethods }) {
+	const files = scanRouteFiles(sourceDir, isRouteFile);
+	const routes = [];
+	for (const file of files) {
+		const source = readFileSync(file, "utf-8");
+		const methods = getMethods(source, file);
+		if (methods.length === 0) continue;
+		const relativeFile = relative(sourceDir, file).replace(/\\/g, "/");
+		const routeSegments = toRouteSegments(relativeFile);
+		const routePath = buildRoutePath(routePathBase, routeSegments);
+		if (shouldExcludeRoute(exclude, routePath, relativeFile, routeSegments.join("/"))) continue;
+		routes.push(createApiReferenceRoute({
+			rootDir,
+			file,
+			source,
+			methods,
+			routePath
+		}));
+	}
+	return routes.sort((a, b) => a.routePath.localeCompare(b.routePath));
+}
+function buildTanstackRoutes(rootDir, apiReference) {
+	const routesDir = join(rootDir, "src", "routes");
+	const files = scanRouteFiles(routesDir, (name) => TANSTACK_ROUTE_FILE_RE.test(name));
+	const routeBase = `/${normalizePathSegment(apiReference.routeRoot)}`;
+	const routes = [];
+	for (const file of files) {
+		const source = readFileSync(file, "utf-8");
+		if (!source.includes("createFileRoute(") || !source.includes("handlers")) continue;
+		const pathMatch = source.match(/createFileRoute\(\s*["'`]([^"'`]+)["'`]\s*\)/);
+		if (!pathMatch) continue;
+		const routePath = normalizeTanstackRoutePath(pathMatch[1]);
+		if (!routePath.startsWith(routeBase)) continue;
+		const methods = extractTanstackMethods(source);
+		if (methods.length === 0) continue;
+		const relativeFile = relative(routesDir, file).replace(/\\/g, "/");
+		if (shouldExcludeRoute(apiReference.exclude, routePath, relativeFile, relativeFile)) continue;
+		routes.push(createApiReferenceRoute({
+			rootDir,
+			file,
+			source,
+			methods,
+			routePath
+		}));
+	}
+	return routes.sort((a, b) => a.routePath.localeCompare(b.routePath));
+}
+function createApiReferenceRoute({ rootDir, file, source, methods, routePath }) {
+	const docBlock = extractDocBlock(source);
+	const pathSegments = routePath.split("/").filter(Boolean);
+	const titleSegment = pathSegments[pathSegments.length - 1] ?? "overview";
+	const tagSegment = pathSegments[0] ?? "general";
+	const title = humanizeSegment(titleSegment);
+	return {
+		title,
+		summary: docBlock.summary ?? `${title} endpoint`,
+		description: docBlock.description,
+		routePath,
+		sourceFile: relative(rootDir, file).replace(/\\/g, "/"),
+		methods,
+		tag: humanizeSegment(tagSegment),
+		parameters: buildPathParameters(routePath)
+	};
+}
+function buildPathParameters(routePath) {
+	const parameters = [];
+	for (const segment of routePath.split("/")) {
+		const match = segment.match(/^\{(.+)\}$/);
+		if (!match) continue;
+		parameters.push({
+			name: match[1],
+			in: "path",
+			required: true,
+			description: `${humanizeSegment(match[1])} path parameter.`,
+			schema: { type: "string" }
+		});
+	}
+	return parameters;
+}
+function buildOpenApiPaths(routes) {
+	const paths = {};
+	for (const route of routes) {
+		const pathItem = {};
+		for (const method of route.methods) pathItem[method.toLowerCase()] = {
+			tags: [route.tag],
+			summary: route.summary,
+			description: route.description ?? route.summary,
+			operationId: createOperationId(route, method),
+			...route.parameters.length > 0 ? { parameters: route.parameters } : {},
+			...buildRequestBody(method) ? { requestBody: buildRequestBody(method) } : {},
+			responses: buildResponses(method),
+			"x-farming-labs-source": route.sourceFile
+		};
+		paths[route.routePath] = pathItem;
+	}
+	return paths;
+}
+function buildRequestBody(method) {
+	if (![
+		"POST",
+		"PUT",
+		"PATCH"
+	].includes(method)) return void 0;
+	return {
+		required: method === "POST",
+		content: { "application/json": {
+			schema: {
+				type: "object",
+				additionalProperties: true
+			},
+			example: { example: true }
+		} }
+	};
+}
+function buildResponses(method) {
+	return { "200": {
+		description: method === "DELETE" ? "Resource removed successfully." : "Request completed successfully.",
+		content: { "application/json": {
+			schema: {
+				type: "object",
+				additionalProperties: true
+			},
+			example: { ok: true }
+		} }
+	} };
+}
+function createOperationId(route, method) {
+	return `${method.toLowerCase()}_${route.routePath.replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "")}`;
+}
+function resolveTheme(config) {
+	return config.theme;
+}
+function normalizeApiReferenceExcludes(values) {
+	return (values ?? []).map(normalizeExcludeMatcher).filter(Boolean);
+}
+function normalizeExcludeMatcher(value) {
+	return value.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "").replace(/\.(ts|tsx|js|jsx|mjs|mts)$/i, "").replace(/\/route$/i, "").replace(/\/\+server$/i, "").replace(/\/index$/i, "").replace(/\.(get|post|put|patch|delete|options|head)$/i, "");
+}
+function shouldExcludeRoute(excludes, routePath, relativeFile, relativeDir) {
+	if (excludes.length === 0) return false;
+	const candidates = new Set([
+		normalizeExcludeMatcher(routePath),
+		normalizeExcludeMatcher(routePath.replace(/^\/+/, "")),
+		normalizeExcludeMatcher(relativeFile),
+		normalizeExcludeMatcher(relativeDir)
+	]);
+	return excludes.some((entry) => candidates.has(entry));
+}
+function scanRouteFiles(dir, isRouteFile) {
+	if (!existsSync(dir)) return [];
+	const results = [];
+	for (const name of readdirSync(dir)) {
+		const full = join(dir, name);
+		if (statSync(full).isDirectory()) {
+			results.push(...scanRouteFiles(full, isRouteFile));
+			continue;
+		}
+		if (isRouteFile(name)) results.push(full);
+	}
+	return results;
+}
+function resolveRootedDir(rootDir, routeRoot, defaultRoot) {
+	const normalized = normalizePathSegment(routeRoot) || "api";
+	if (normalized === defaultRoot || normalized.startsWith(`${defaultRoot}/`)) return join(rootDir, ...normalized.split("/"));
+	return join(rootDir, ...defaultRoot.split("/"), ...normalized.split("/"));
+}
+function toRouteBase(routeRoot, defaultRoot) {
+	const normalized = normalizePathSegment(routeRoot) || "api";
+	return `/${normalizePathSegment(normalized === defaultRoot || normalized.startsWith(`${defaultRoot}/`) ? normalized.slice(defaultRoot.length).replace(/^\/+/, "") : normalized)}`;
+}
+function getNextAppDir(rootDir) {
+	if (existsSync(join(rootDir, "src", "app"))) return "src/app";
+	return "app";
+}
+function routeSegmentsFromEndpointFile(relativeFile) {
+	const segments = relativeFile.split("/");
+	const name = (segments.pop() ?? "").replace(/\.(ts|js|mts|mjs)$/i, "");
+	if (name !== "index") segments.push(name);
+	return segments.filter(Boolean);
+}
+function stripNuxtMethodSuffix(relativeFile) {
+	return relativeFile.replace(/\.(get|post|put|patch|delete|options|head)(?=\.(ts|js|mts|mjs)$)/i, "");
+}
+function buildRoutePath(basePath, rawSegments) {
+	const segments = rawSegments.filter(Boolean).map((segment) => endpointSegmentFromConvention(segment)).join("/");
+	const path = [normalizePathSegment(basePath), segments].filter(Boolean).join("/");
+	return path ? `/${path}` : "/";
+}
+function endpointSegmentFromConvention(value) {
+	if (value.startsWith("[[...") && value.endsWith("]]")) return `{${value.slice(5, -2)}}`;
+	if (value.startsWith("[...") && value.endsWith("]")) return `{${value.slice(4, -1)}}`;
+	if (value.startsWith("[") && value.endsWith("]")) return `{${value.slice(1, -1)}}`;
+	return value;
+}
+function normalizeTanstackRoutePath(value) {
+	return `/${value.replace(/^\/+|\/+$/g, "").split("/").map((segment) => segment.startsWith("$") ? `{${segment.slice(1)}}` : segment).filter(Boolean).join("/")}`;
+}
+function extractDocBlock(source) {
+	const match = source.match(/\/\*\*([\s\S]*?)\*\//);
+	if (!match) return {};
+	const lines = match[1].split("\n").map((line) => line.replace(/^\s*\*\s?/, "").trim()).filter(Boolean).filter((line) => !line.startsWith("@"));
+	if (lines.length === 0) return {};
+	return {
+		summary: lines[0],
+		description: lines.slice(1).join(" ")
+	};
+}
+function extractMethods(source) {
+	const methods = /* @__PURE__ */ new Set();
+	for (const match of source.matchAll(METHOD_RE)) {
+		if (match[1] === "ALL") {
+			METHOD_NAMES.forEach((method) => methods.add(method));
+			continue;
+		}
+		methods.add(match[1]);
+	}
+	return Array.from(methods);
+}
+function extractNuxtMethods(source, file) {
+	const methods = extractMethods(source);
+	if (methods.length > 0) return methods;
+	const suffix = basename(file).match(/\.(get|post|put|patch|delete|options|head)\.(ts|js|mts|mjs)$/i);
+	if (suffix) return [suffix[1].toUpperCase()];
+	if (/defineEventHandler|eventHandler/.test(source)) return ["GET"];
+	return [];
+}
+function extractTanstackMethods(source) {
+	const methods = /* @__PURE__ */ new Set();
+	const handlersMatch = source.match(/handlers\s*:\s*\{([\s\S]*?)\}/m);
+	if (!handlersMatch) return [];
+	for (const match of handlersMatch[1].matchAll(/\b(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD)\s*:/g)) methods.add(match[1]);
+	return Array.from(methods);
+}
+function humanizeSegment(value) {
+	return value.replace(/^\{/, "").replace(/\}$/, "").replace(/^\[\[?\.{3}/, "").replace(/^\[/, "").replace(/\]\]?$/, "").replace(/^\$/, "").replace(/-/g, " ").replace(/\b\w/g, (char) => char.toUpperCase());
+}
+
+//#endregion
+export { DEFAULT_API_REFERENCE_OPENAPI_ROUTE, buildApiReferenceHtmlDocument, buildApiReferenceHtmlDocumentAsync, buildApiReferenceOpenApiDocument, buildApiReferenceOpenApiDocumentAsync, buildApiReferenceOperationPagesAsync, buildApiReferencePageTitle, buildApiReferenceScalarCss, createApiReferenceOperationMarkdownResponse, isApiReferenceOpenApiRequest, loadApiReferenceOpenApiDocumentAsync, resolveApiReferenceConfig, resolveApiReferenceOpenApiDiscovery, resolveApiReferenceRenderer, resolveApiReferenceVersion, resolveApiReferenceVersionFromPathname };