@farming-labs/theme 0.1.19 → 0.1.21

package/dist/docs-api.d.mts

@@ -1,4 +1,4 @@
-import { ChangelogConfig, DocsI18nConfig, DocsMcpConfig, DocsSearchConfig, OrderingItem } from "@farming-labs/docs";
+import { ChangelogConfig, DocsI18nConfig, DocsMcpConfig, DocsSearchConfig, FeedbackConfig, OrderingItem } from "@farming-labs/docs";
 
 //#region src/docs-api.d.ts
 interface AIProviderConfig {
@@ -41,6 +41,8 @@ interface DocsAPIOptions {
   i18n?: DocsI18nConfig;
   /** Search configuration */
   search?: boolean | DocsSearchConfig;
+  /** Feedback configuration */
+  feedback?: boolean | FeedbackConfig;
 }
 interface DocsMCPAPIOptions {
   rootDir?: string;

package/dist/docs-api.mjs

@@ -32,6 +32,201 @@ const FILE_EXTS = [
 	"jsx",
 	"js"
 ];
+const DEFAULT_AGENT_FEEDBACK_ROUTE = "/api/docs/agent/feedback";
+const DEFAULT_AGENT_FEEDBACK_PAYLOAD_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		task: {
+			type: "string",
+			description: "Short description of what the agent was trying to do."
+		},
+		understanding: {
+			type: "string",
+			description: "How well the docs supported the task, e.g. \"partial\" or \"clear\"."
+		},
+		outcome: {
+			type: "string",
+			description: "What happened after reading the docs, e.g. \"implemented\" or \"blocked\"."
+		},
+		confidence: {
+			type: "number",
+			minimum: 0,
+			maximum: 1,
+			description: "Confidence score from 0 to 1."
+		},
+		neededCodeReading: {
+			type: "boolean",
+			description: "Whether the agent still needed to inspect repository code."
+		},
+		missingContext: {
+			type: "array",
+			items: { type: "string" },
+			description: "Important details the docs did not provide clearly enough."
+		},
+		docIssues: {
+			type: "array",
+			items: { type: "string" },
+			description: "Specific documentation problems encountered during the task."
+		},
+		suggestedImprovement: {
+			type: "string",
+			description: "Concrete suggestion for improving the docs page or examples."
+		}
+	},
+	required: ["task", "outcome"]
+};
+function normalizeAgentFeedbackRoute(route, fallback = DEFAULT_AGENT_FEEDBACK_ROUTE) {
+	if (!route || route.trim().length === 0) return fallback;
+	const normalized = `/${route}`.replace(/\/+/g, "/");
+	return normalized !== "/" ? normalized.replace(/\/+$/, "") : fallback;
+}
+function buildAgentFeedbackSchema(payloadSchema) {
+	return {
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			context: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					page: { type: "string" },
+					url: { type: "string" },
+					slug: { type: "string" },
+					locale: { type: "string" },
+					source: { type: "string" }
+				}
+			},
+			payload: payloadSchema
+		},
+		required: ["payload"]
+	};
+}
+function resolveAgentFeedbackConfig(feedback) {
+	const route = normalizeAgentFeedbackRoute();
+	const disabled = {
+		enabled: false,
+		route,
+		schemaRoute: `${route}/schema`,
+		payloadSchema: DEFAULT_AGENT_FEEDBACK_PAYLOAD_SCHEMA,
+		schema: buildAgentFeedbackSchema(DEFAULT_AGENT_FEEDBACK_PAYLOAD_SCHEMA)
+	};
+	if (!feedback || typeof feedback !== "object") return disabled;
+	const agent = feedback.agent;
+	if (!agent) return disabled;
+	if (agent === true) return {
+		enabled: true,
+		route,
+		schemaRoute: `${route}/schema`,
+		payloadSchema: DEFAULT_AGENT_FEEDBACK_PAYLOAD_SCHEMA,
+		schema: buildAgentFeedbackSchema(DEFAULT_AGENT_FEEDBACK_PAYLOAD_SCHEMA)
+	};
+	const resolvedRoute = normalizeAgentFeedbackRoute(agent.route, route);
+	const resolvedSchemaRoute = normalizeAgentFeedbackRoute(agent.schemaRoute, `${resolvedRoute}/schema`);
+	const payloadSchema = agent.schema ?? DEFAULT_AGENT_FEEDBACK_PAYLOAD_SCHEMA;
+	return {
+		enabled: agent.enabled !== false,
+		route: resolvedRoute,
+		schemaRoute: resolvedSchemaRoute,
+		payloadSchema,
+		schema: buildAgentFeedbackSchema(payloadSchema),
+		onFeedback: agent.onFeedback
+	};
+}
+function resolveAgentFeedbackRequest(url, feedback) {
+	if (!feedback.enabled) return null;
+	const feedbackMode = url.searchParams.get("feedback")?.trim();
+	const schemaMode = url.searchParams.get("schema")?.trim();
+	if (feedbackMode === "agent") return { kind: schemaMode === "1" || schemaMode === "true" ? "schema" : "submit" };
+	const pathname = normalizeUrlPath(url.pathname);
+	if (pathname === feedback.schemaRoute) return { kind: "schema" };
+	if (pathname === feedback.route) return { kind: "submit" };
+	return null;
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeAgentFeedbackContext(value) {
+	if (!isPlainObject(value)) return void 0;
+	const context = {};
+	if (typeof value.page === "string") context.page = value.page;
+	if (typeof value.url === "string") context.url = value.url;
+	if (typeof value.slug === "string") context.slug = value.slug;
+	if (typeof value.locale === "string") context.locale = value.locale;
+	if (typeof value.source === "string") context.source = value.source;
+	return Object.keys(context).length > 0 ? context : void 0;
+}
+async function parseAgentFeedbackData(request) {
+	let body;
+	try {
+		body = await request.json();
+	} catch {
+		return {
+			ok: false,
+			response: Response.json({ error: "Agent feedback body must be valid JSON" }, { status: 400 })
+		};
+	}
+	if (!isPlainObject(body)) return {
+		ok: false,
+		response: Response.json({ error: "Agent feedback body must be an object" }, { status: 400 })
+	};
+	if (!isPlainObject(body.payload)) return {
+		ok: false,
+		response: Response.json({ error: "Agent feedback body must include a payload object" }, { status: 400 })
+	};
+	return {
+		ok: true,
+		data: {
+			context: normalizeAgentFeedbackContext(body.context),
+			payload: body.payload
+		}
+	};
+}
+function validateAgentFeedbackPayload(value, schema, valuePath = "payload") {
+	const schemaType = typeof schema.type === "string" ? schema.type : void 0;
+	if (Array.isArray(schema.enum) && !schema.enum.some((entry) => Object.is(entry, value))) return `${valuePath} must be one of the configured enum values`;
+	if (schemaType === "object" || !schemaType && (schema.properties || schema.required)) {
+		if (!isPlainObject(value)) return `${valuePath} must be an object`;
+		const properties = isPlainObject(schema.properties) ? schema.properties : {};
+		const required = Array.isArray(schema.required) ? schema.required.filter((entry) => typeof entry === "string") : [];
+		for (const key of required) if (!(key in value)) return `${valuePath}.${key} is required`;
+		if (schema.additionalProperties === false) {
+			for (const key of Object.keys(value)) if (!(key in properties)) return `${valuePath}.${key} is not allowed`;
+		}
+		for (const [key, propertySchema] of Object.entries(properties)) {
+			if (!(key in value)) continue;
+			if (!isPlainObject(propertySchema)) continue;
+			const error = validateAgentFeedbackPayload(value[key], propertySchema, `${valuePath}.${key}`);
+			if (error) return error;
+		}
+		return;
+	}
+	if (schemaType === "array") {
+		if (!Array.isArray(value)) return `${valuePath} must be an array`;
+		if (!isPlainObject(schema.items)) return void 0;
+		for (const [index, item] of value.entries()) {
+			const error = validateAgentFeedbackPayload(item, schema.items, `${valuePath}[${index}]`);
+			if (error) return error;
+		}
+		return;
+	}
+	if (schemaType === "string") {
+		if (typeof value !== "string") return `${valuePath} must be a string`;
+		if (typeof schema.minLength === "number" && value.length < schema.minLength) return `${valuePath} must be at least ${schema.minLength} characters`;
+		if (typeof schema.maxLength === "number" && value.length > schema.maxLength) return `${valuePath} must be at most ${schema.maxLength} characters`;
+		return;
+	}
+	if (schemaType === "number") {
+		if (typeof value !== "number" || !Number.isFinite(value)) return `${valuePath} must be a number`;
+		if (typeof schema.minimum === "number" && value < schema.minimum) return `${valuePath} must be >= ${schema.minimum}`;
+		if (typeof schema.maximum === "number" && value > schema.maximum) return `${valuePath} must be <= ${schema.maximum}`;
+		return;
+	}
+	if (schemaType === "boolean") {
+		if (typeof value !== "boolean") return `${valuePath} must be a boolean`;
+		return;
+	}
+}
 function readEntry(root) {
 	for (const ext of FILE_EXTS) {
 		const configPath = path.join(root, `docs.config.${ext}`);
@@ -444,6 +639,15 @@ function findDocsMcpPage(entry, pages, requestedPath) {
 	for (const page of pages) if (normalizePathSegment(page.slug) === normalizedSlug) return page;
 	return null;
 }
+function resolveMarkdownRequest(entry, url) {
+	if (url.searchParams.get("format")?.trim() === "markdown") return { requestedPath: url.searchParams.get("path")?.trim() ?? "" };
+	const pathname = normalizeUrlPath(url.pathname);
+	const normalizedEntry = `/${normalizePathSegment(entry)}`;
+	if (pathname === `${normalizedEntry}.md`) return { requestedPath: "" };
+	const slugPrefix = `${normalizedEntry}/`;
+	if (pathname.startsWith(slugPrefix) && pathname.endsWith(".md")) return { requestedPath: pathname.slice(slugPrefix.length, -3) };
+	return null;
+}
 function renderMarkdownDocument(page) {
 	if ("agentRawContent" in page && page.agentRawContent !== void 0) return page.agentRawContent;
 	const lines = [`# ${page.title}`, `URL: ${page.url}`];
@@ -599,6 +803,7 @@ function createDocsAPI(options) {
 	const appDir = getNextAppDir(root);
 	const contentDir = options?.contentDir ?? path.join(appDir, entry);
 	const changelogConfig = resolveChangelogConfig(options?.changelog);
+	const agentFeedbackConfig = resolveAgentFeedbackConfig(options?.feedback);
 	const i18n = resolveDocsI18n(options?.i18n ?? readI18nConfig(root));
 	const aiConfig = options?.ai ?? readAIConfig(root);
 	const searchConfig = options?.search;
@@ -722,9 +927,21 @@ function createDocsAPI(options) {
 		async GET(request) {
 			const ctx = resolveContextFromRequest(request);
 			const url = new URL(request.url);
-			const format = url.searchParams.get("format");
-			if (format === "markdown") {
-				const document = await getMarkdownDocument(ctx, url.searchParams.get("path")?.trim() ?? "");
+			const agentFeedbackRequest = resolveAgentFeedbackRequest(url, agentFeedbackConfig);
+			if (agentFeedbackRequest) {
+				if (agentFeedbackRequest.kind === "submit") return Response.json({ error: "Method Not Allowed" }, {
+					status: 405,
+					headers: { Allow: "POST" }
+				});
+				return new Response(JSON.stringify(agentFeedbackConfig.schema, null, 2), { headers: {
+					"Content-Type": "application/schema+json; charset=utf-8",
+					"Cache-Control": "public, max-age=0, s-maxage=3600",
+					"X-Robots-Tag": "noindex"
+				} });
+			}
+			const markdownRequest = resolveMarkdownRequest(entry, url);
+			if (markdownRequest) {
+				const document = await getMarkdownDocument(ctx, markdownRequest.requestedPath);
 				if (!document) return new Response("Not Found", {
 					status: 404,
 					headers: {
@@ -738,6 +955,7 @@ function createDocsAPI(options) {
 					"X-Robots-Tag": "noindex"
 				} });
 			}
+			const format = url.searchParams.get("format");
 			if (format === "llms") return new Response(getLlmsContent(ctx).llmsTxt, { headers: {
 				"Content-Type": "text/plain; charset=utf-8",
 				"Cache-Control": "public, max-age=3600"
@@ -759,6 +977,26 @@ function createDocsAPI(options) {
 			return new Response(JSON.stringify(results), { headers: { "Content-Type": "application/json" } });
 		},
 		async POST(request) {
+			const agentFeedbackRequest = resolveAgentFeedbackRequest(new URL(request.url), agentFeedbackConfig);
+			if (agentFeedbackRequest) {
+				if (agentFeedbackRequest.kind === "schema") return Response.json({ error: "Method Not Allowed" }, {
+					status: 405,
+					headers: { Allow: "GET" }
+				});
+				const parsed = await parseAgentFeedbackData(request);
+				if (!parsed.ok) return parsed.response;
+				const payloadError = validateAgentFeedbackPayload(parsed.data.payload, agentFeedbackConfig.payloadSchema);
+				if (payloadError) return Response.json({ error: payloadError }, { status: 400 });
+				if (!agentFeedbackConfig.onFeedback) return Response.json({
+					ok: true,
+					handled: false
+				}, { status: 202 });
+				await agentFeedbackConfig.onFeedback(parsed.data);
+				return Response.json({
+					ok: true,
+					handled: true
+				}, { status: 201 });
+			}
 			if (!aiConfig.enabled) return Response.json({ error: "AI is not enabled. Set `ai: { enabled: true }` in your docs.config to enable it." }, { status: 404 });
 			return handleAskAI(request, getIndexes(resolveContextFromRequest(request)), aiConfig);
 		}

package/dist/docs-layout.mjs

@@ -716,8 +716,9 @@ function resolveFeedbackConfig(feedback) {
 		...defaults,
 		enabled: true
 	};
+	const hasHumanFeedbackConfig = feedback.enabled !== void 0 || feedback.question !== void 0 || feedback.placeholder !== void 0 || feedback.positiveLabel !== void 0 || feedback.negativeLabel !== void 0 || feedback.submitLabel !== void 0 || feedback.onFeedback !== void 0;
 	return {
-		enabled: feedback.enabled !== false,
+		enabled: feedback.enabled === true || feedback.enabled !== false && hasHumanFeedbackConfig,
 		question: feedback.question ?? defaults.question,
 		placeholder: feedback.placeholder ?? defaults.placeholder,
 		positiveLabel: feedback.positiveLabel ?? defaults.positiveLabel,

package/dist/tanstack-layout.mjs

@@ -192,8 +192,9 @@ function resolveFeedbackConfig(feedback) {
 		...defaults,
 		enabled: true
 	};
+	const hasHumanFeedbackConfig = feedback.enabled !== void 0 || feedback.question !== void 0 || feedback.placeholder !== void 0 || feedback.positiveLabel !== void 0 || feedback.negativeLabel !== void 0 || feedback.submitLabel !== void 0 || feedback.onFeedback !== void 0;
 	return {
-		enabled: feedback.enabled !== false,
+		enabled: feedback.enabled === true || feedback.enabled !== false && hasHumanFeedbackConfig,
 		question: feedback.question ?? defaults.question,
 		placeholder: feedback.placeholder ?? defaults.placeholder,
 		positiveLabel: feedback.positiveLabel ?? defaults.positiveLabel,

package/package.json

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