@farming-labs/docs 0.2.71 → 0.2.73

package/dist/markdown-sections-7OoA7ylx.mjs

@@ -0,0 +1,1492 @@
+import { createProcessor } from "@mdx-js/mdx";
+import { slug } from "github-slugger";
+import { parseEntities } from "parse-entities";
+import remarkGfm from "remark-gfm";
+
+//#region src/agent-contract.ts
+const PAGE_AGENT_STRUCTURED_CONTRACT_FIELDS = [
+	"task",
+	"outcome",
+	"appliesTo",
+	"prerequisites",
+	"files",
+	"commands",
+	"sideEffects",
+	"verification",
+	"rollback",
+	"failureModes"
+];
+const PAGE_AGENT_CONTRACT_FIELDS = ["tokenBudget", ...PAGE_AGENT_STRUCTURED_CONTRACT_FIELDS];
+const PAGE_AGENT_CONTRACT_FIELD_SCHEMA = {
+	tokenBudget: "number",
+	task: "string",
+	outcome: "string",
+	appliesTo: {
+		framework: "string|string[]",
+		version: "string|string[]",
+		package: "string|string[]"
+	},
+	prerequisites: "string[]",
+	files: "string[]",
+	commands: "Array<string|{run,cwd?,description?}>",
+	sideEffects: "string[]",
+	verification: "Array<string|{description?,run?,expect?}>",
+	rollback: "string[]",
+	failureModes: "Array<string|{symptom,resolution?}>"
+};
+const APPLIES_TO_FIELDS = [
+	"framework",
+	"version",
+	"package"
+];
+const COMMAND_FIELDS = [
+	"run",
+	"cwd",
+	"description"
+];
+const VERIFICATION_FIELDS = [
+	"description",
+	"run",
+	"expect"
+];
+const FAILURE_MODE_FIELDS = ["symptom", "resolution"];
+const PAGE_AGENT_CONTRACT_START_MARKER = "<!-- farming-labs:agent-contract:start -->";
+const PAGE_AGENT_CONTRACT_END_MARKER = "<!-- farming-labs:agent-contract:end -->";
+function isRecord(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeString(value) {
+	if (typeof value !== "string") return void 0;
+	return value.trim() || void 0;
+}
+function normalizeStringList(value) {
+	if (!Array.isArray(value)) return void 0;
+	const seen = /* @__PURE__ */ new Set();
+	const normalized = [];
+	for (const item of value) {
+		const text = normalizeString(item);
+		if (!text || seen.has(text)) continue;
+		seen.add(text);
+		normalized.push(text);
+	}
+	return normalized.length > 0 ? normalized : void 0;
+}
+function normalizeStringOrList(value) {
+	const single = normalizeString(value);
+	if (single) return [single];
+	return normalizeStringList(value);
+}
+function normalizeAppliesTo(value) {
+	if (!isRecord(value)) return void 0;
+	const framework = normalizeStringOrList(value.framework);
+	const version = normalizeStringOrList(value.version);
+	const packageNames = normalizeStringOrList(value.package);
+	if (!framework && !version && !packageNames) return void 0;
+	return {
+		...framework ? { framework } : {},
+		...version ? { version } : {},
+		...packageNames ? { package: packageNames } : {}
+	};
+}
+function normalizeCommands(value) {
+	if (!Array.isArray(value)) return void 0;
+	const commands = [];
+	for (const item of value) {
+		const shorthand = normalizeString(item);
+		if (shorthand) {
+			commands.push(shorthand);
+			continue;
+		}
+		if (!isRecord(item)) continue;
+		const run = normalizeString(item.run);
+		if (!run) continue;
+		const cwd = normalizeString(item.cwd);
+		const description = normalizeString(item.description);
+		commands.push({
+			run,
+			...cwd ? { cwd } : {},
+			...description ? { description } : {}
+		});
+	}
+	return commands.length > 0 ? commands : void 0;
+}
+function normalizeVerification(value) {
+	if (!Array.isArray(value)) return void 0;
+	const verification = [];
+	for (const item of value) {
+		const shorthand = normalizeString(item);
+		if (shorthand) {
+			verification.push(shorthand);
+			continue;
+		}
+		if (!isRecord(item)) continue;
+		const description = normalizeString(item.description);
+		const run = normalizeString(item.run);
+		const expect = normalizeString(item.expect);
+		if (!description && !run && !expect) continue;
+		verification.push({
+			...description ? { description } : {},
+			...run ? { run } : {},
+			...expect ? { expect } : {}
+		});
+	}
+	return verification.length > 0 ? verification : void 0;
+}
+function normalizeFailureModes(value) {
+	if (!Array.isArray(value)) return void 0;
+	const failureModes = [];
+	for (const item of value) {
+		const shorthand = normalizeString(item);
+		if (shorthand) {
+			failureModes.push(shorthand);
+			continue;
+		}
+		if (!isRecord(item)) continue;
+		const symptom = normalizeString(item.symptom);
+		if (!symptom) continue;
+		const resolution = normalizeString(item.resolution);
+		failureModes.push({
+			symptom,
+			...resolution ? { resolution } : {}
+		});
+	}
+	return failureModes.length > 0 ? failureModes : void 0;
+}
+function normalizeTokenBudget(value) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return void 0;
+	return Math.ceil(value);
+}
+/**
+* Normalize untrusted page frontmatter into the stable agent contract shape.
+* Invalid fields are omitted so malformed author input cannot break page delivery.
+*/
+function normalizePageAgentFrontmatter(value) {
+	if (!isRecord(value)) return void 0;
+	const tokenBudget = normalizeTokenBudget(value.tokenBudget);
+	const task = normalizeString(value.task);
+	const outcome = normalizeString(value.outcome);
+	const appliesTo = normalizeAppliesTo(value.appliesTo);
+	const prerequisites = normalizeStringList(value.prerequisites);
+	const files = normalizeStringList(value.files);
+	const commands = normalizeCommands(value.commands);
+	const sideEffects = normalizeStringList(value.sideEffects);
+	const verification = normalizeVerification(value.verification);
+	const rollback = normalizeStringList(value.rollback);
+	const failureModes = normalizeFailureModes(value.failureModes);
+	const normalized = {
+		...tokenBudget !== void 0 ? { tokenBudget } : {},
+		...task ? { task } : {},
+		...outcome ? { outcome } : {},
+		...appliesTo ? { appliesTo } : {},
+		...prerequisites ? { prerequisites } : {},
+		...files ? { files } : {},
+		...commands ? { commands } : {},
+		...sideEffects ? { sideEffects } : {},
+		...verification ? { verification } : {},
+		...rollback ? { rollback } : {},
+		...failureModes ? { failureModes } : {}
+	};
+	return Object.keys(normalized).length > 0 ? normalized : void 0;
+}
+function hasStructuredPageAgentContract(value) {
+	const normalized = normalizePageAgentFrontmatter(value);
+	if (!normalized) return false;
+	return PAGE_AGENT_STRUCTURED_CONTRACT_FIELDS.some((field) => normalized[field] !== void 0);
+}
+function addStringIssue(issues, object, field) {
+	if (!(field in object)) return;
+	if (!normalizeString(object[field])) issues.push({
+		path: `agent.${field}`,
+		message: "must be a non-empty string"
+	});
+}
+function addStringListIssues(issues, object, field) {
+	if (!(field in object)) return;
+	const value = object[field];
+	if (!Array.isArray(value) || value.length === 0) {
+		issues.push({
+			path: `agent.${field}`,
+			message: "must be a non-empty string array"
+		});
+		return;
+	}
+	value.forEach((item, index) => {
+		if (!normalizeString(item)) issues.push({
+			path: `agent.${field}[${index}]`,
+			message: "must be a non-empty string"
+		});
+	});
+}
+function editDistance(left, right) {
+	const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+	for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+		const current = [leftIndex];
+		for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) current[rightIndex] = Math.min((current[rightIndex - 1] ?? 0) + 1, (previous[rightIndex] ?? 0) + 1, (previous[rightIndex - 1] ?? 0) + (left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1));
+		previous.splice(0, previous.length, ...current);
+	}
+	return previous[right.length] ?? 0;
+}
+function closestKnownField(field, allowed) {
+	const closest = allowed.map((candidate) => ({
+		candidate,
+		distance: editDistance(field, candidate)
+	})).sort((left, right) => left.distance - right.distance || left.candidate.localeCompare(right.candidate))[0];
+	if (!closest) return void 0;
+	const threshold = Math.max(1, Math.min(3, Math.floor(closest.candidate.length / 3)));
+	return closest.distance <= threshold ? closest.candidate : void 0;
+}
+function addUnknownKeyIssues(issues, object, allowed, path) {
+	for (const field of Object.keys(object)) {
+		if (allowed.includes(field)) continue;
+		const suggestion = closestKnownField(field, allowed);
+		issues.push({
+			path: `${path}.${field}`,
+			message: suggestion ? `is not recognized; did you mean "${path}.${suggestion}"?` : "is not recognized"
+		});
+	}
+}
+/** Return author-facing validation issues without throwing. */
+function getPageAgentFrontmatterIssues(value) {
+	if (value === void 0) return [];
+	if (!isRecord(value)) return [{
+		path: "agent",
+		message: "must be an object"
+	}];
+	const issues = [];
+	addUnknownKeyIssues(issues, value, PAGE_AGENT_CONTRACT_FIELDS, "agent");
+	if ("tokenBudget" in value && (typeof value.tokenBudget !== "number" || !Number.isFinite(value.tokenBudget) || value.tokenBudget <= 0)) issues.push({
+		path: "agent.tokenBudget",
+		message: "must be a positive finite number"
+	});
+	addStringIssue(issues, value, "task");
+	addStringIssue(issues, value, "outcome");
+	if ("appliesTo" in value) if (!isRecord(value.appliesTo)) issues.push({
+		path: "agent.appliesTo",
+		message: "must be an object"
+	});
+	else {
+		addUnknownKeyIssues(issues, value.appliesTo, APPLIES_TO_FIELDS, "agent.appliesTo");
+		for (const field of [
+			"framework",
+			"version",
+			"package"
+		]) {
+			if (!(field in value.appliesTo)) continue;
+			const fieldValue = value.appliesTo[field];
+			if (!normalizeStringOrList(fieldValue)) {
+				issues.push({
+					path: `agent.appliesTo.${field}`,
+					message: "must be a non-empty string or string array"
+				});
+				continue;
+			}
+			if (Array.isArray(fieldValue)) fieldValue.forEach((item, index) => {
+				if (!normalizeString(item)) issues.push({
+					path: `agent.appliesTo.${field}[${index}]`,
+					message: "must be a non-empty string"
+				});
+			});
+		}
+		if (!normalizeAppliesTo(value.appliesTo)) issues.push({
+			path: "agent.appliesTo",
+			message: "must include framework, version, or package"
+		});
+	}
+	for (const field of [
+		"prerequisites",
+		"files",
+		"sideEffects",
+		"rollback"
+	]) addStringListIssues(issues, value, field);
+	if ("commands" in value) if (!Array.isArray(value.commands) || value.commands.length === 0) issues.push({
+		path: "agent.commands",
+		message: "must be a non-empty array"
+	});
+	else value.commands.forEach((command, index) => {
+		if (normalizeString(command)) return;
+		if (!isRecord(command)) {
+			issues.push({
+				path: `agent.commands[${index}]`,
+				message: "must be a command string or an object with a non-empty run field"
+			});
+			return;
+		}
+		addUnknownKeyIssues(issues, command, COMMAND_FIELDS, `agent.commands[${index}]`);
+		if (!normalizeString(command.run)) {
+			issues.push({
+				path: `agent.commands[${index}]`,
+				message: "must be a command string or an object with a non-empty run field"
+			});
+			return;
+		}
+		for (const field of ["cwd", "description"]) if (field in command && !normalizeString(command[field])) issues.push({
+			path: `agent.commands[${index}].${field}`,
+			message: "must be a non-empty string"
+		});
+	});
+	if ("verification" in value) if (!Array.isArray(value.verification) || value.verification.length === 0) issues.push({
+		path: "agent.verification",
+		message: "must be a non-empty array"
+	});
+	else value.verification.forEach((step, index) => {
+		if (normalizeString(step)) return;
+		if (!isRecord(step)) {
+			issues.push({
+				path: `agent.verification[${index}]`,
+				message: "must be a string or an object with description, run, or expect"
+			});
+			return;
+		}
+		addUnknownKeyIssues(issues, step, VERIFICATION_FIELDS, `agent.verification[${index}]`);
+		if (!normalizeVerification([step])) {
+			issues.push({
+				path: `agent.verification[${index}]`,
+				message: "must be a string or an object with description, run, or expect"
+			});
+			return;
+		}
+		for (const field of [
+			"description",
+			"run",
+			"expect"
+		]) if (field in step && !normalizeString(step[field])) issues.push({
+			path: `agent.verification[${index}].${field}`,
+			message: "must be a non-empty string"
+		});
+	});
+	if ("failureModes" in value) if (!Array.isArray(value.failureModes) || value.failureModes.length === 0) issues.push({
+		path: "agent.failureModes",
+		message: "must be a non-empty array"
+	});
+	else value.failureModes.forEach((mode, index) => {
+		if (normalizeString(mode)) return;
+		if (!isRecord(mode)) {
+			issues.push({
+				path: `agent.failureModes[${index}]`,
+				message: "must be a string or an object with a non-empty symptom field"
+			});
+			return;
+		}
+		addUnknownKeyIssues(issues, mode, FAILURE_MODE_FIELDS, `agent.failureModes[${index}]`);
+		if (!normalizeString(mode.symptom)) {
+			issues.push({
+				path: `agent.failureModes[${index}]`,
+				message: "must be a string or an object with a non-empty symptom field"
+			});
+			return;
+		}
+		if ("resolution" in mode && !normalizeString(mode.resolution)) issues.push({
+			path: `agent.failureModes[${index}].resolution`,
+			message: "must be a non-empty string"
+		});
+	});
+	return issues;
+}
+function yamlString(value) {
+	return JSON.stringify(value);
+}
+function renderYamlStringList(lines, indent, key, values) {
+	lines.push(`${indent}${key}:`);
+	for (const value of values) lines.push(`${indent}  - ${yamlString(value)}`);
+}
+function renderYamlObjectList(lines, indent, key, values, fields) {
+	lines.push(`${indent}${key}:`);
+	for (const value of values) {
+		if (typeof value === "string") {
+			lines.push(`${indent}  - ${yamlString(value)}`);
+			continue;
+		}
+		const record = value;
+		const firstField = fields.find((field) => normalizeString(record[field]));
+		if (!firstField) continue;
+		lines.push(`${indent}  - ${firstField}: ${yamlString(normalizeString(record[firstField]))}`);
+		for (const field of fields) {
+			const fieldValue = normalizeString(record[field]);
+			if (field === firstField || !fieldValue) continue;
+			lines.push(`${indent}    ${field}: ${yamlString(fieldValue)}`);
+		}
+	}
+}
+/** Render normalized `agent` YAML in a stable field order. */
+function renderPageAgentFrontmatterYamlLines(value, indentation = 0) {
+	const agent = normalizePageAgentFrontmatter(value);
+	if (!agent) return [];
+	const indent = " ".repeat(Math.max(0, indentation));
+	const child = `${indent}  `;
+	const lines = [`${indent}agent:`];
+	if (agent.tokenBudget !== void 0) lines.push(`${child}tokenBudget: ${agent.tokenBudget}`);
+	if (agent.task) lines.push(`${child}task: ${yamlString(agent.task)}`);
+	if (agent.outcome) lines.push(`${child}outcome: ${yamlString(agent.outcome)}`);
+	if (agent.appliesTo) {
+		lines.push(`${child}appliesTo:`);
+		const appliesIndent = `${child}  `;
+		for (const field of [
+			"framework",
+			"version",
+			"package"
+		]) {
+			const values = normalizeStringOrList(agent.appliesTo[field]);
+			if (values) renderYamlStringList(lines, appliesIndent, field, values);
+		}
+	}
+	if (agent.prerequisites) renderYamlStringList(lines, child, "prerequisites", agent.prerequisites);
+	if (agent.files) renderYamlStringList(lines, child, "files", agent.files);
+	if (agent.commands) renderYamlObjectList(lines, child, "commands", agent.commands, [
+		"run",
+		"cwd",
+		"description"
+	]);
+	if (agent.sideEffects) renderYamlStringList(lines, child, "sideEffects", agent.sideEffects);
+	if (agent.verification) renderYamlObjectList(lines, child, "verification", agent.verification, [
+		"description",
+		"run",
+		"expect"
+	]);
+	if (agent.rollback) renderYamlStringList(lines, child, "rollback", agent.rollback);
+	if (agent.failureModes) renderYamlObjectList(lines, child, "failureModes", agent.failureModes, ["symptom", "resolution"]);
+	return lines;
+}
+function inlineCode(value) {
+	const longestRun = Math.max(0, ...[...value.matchAll(/`+/g)].map((match) => match[0].length));
+	const fence = "`".repeat(longestRun + 1);
+	const padding = value.startsWith("`") || value.endsWith("`") ? " " : "";
+	return `${fence}${padding}${value}${padding}${fence}`;
+}
+function renderTextList(lines, title, values, code = false) {
+	lines.push("", `### ${title}`, "");
+	for (const value of values) lines.push(`- ${code ? inlineCode(value) : value}`);
+}
+/** Render the structured contract as deterministic, compact machine-readable Markdown. */
+function renderPageAgentContractMarkdown(value) {
+	const agent = normalizePageAgentFrontmatter(value);
+	if (!agent || !hasStructuredPageAgentContract(agent)) return "";
+	const lines = [PAGE_AGENT_CONTRACT_START_MARKER, "## Agent Contract"];
+	if (agent.task) lines.push("", `Task: ${agent.task}`);
+	if (agent.outcome) lines.push(`Outcome: ${agent.outcome}`);
+	if (agent.appliesTo) {
+		lines.push("", "### Applies To", "");
+		for (const [label, field] of [
+			["Framework", "framework"],
+			["Version", "version"],
+			["Package", "package"]
+		]) {
+			const values = normalizeStringOrList(agent.appliesTo[field]);
+			if (values) lines.push(`- ${label}: ${values.map(inlineCode).join(", ")}`);
+		}
+	}
+	if (agent.prerequisites) renderTextList(lines, "Prerequisites", agent.prerequisites);
+	if (agent.files) renderTextList(lines, "Files", agent.files, true);
+	if (agent.commands) {
+		lines.push("", "### Commands", "");
+		for (const command of agent.commands) {
+			if (typeof command === "string") {
+				lines.push(`- ${inlineCode(command)}`);
+				continue;
+			}
+			const details = [command.cwd ? `cwd ${inlineCode(command.cwd)}` : void 0, command.description].filter(Boolean);
+			lines.push(`- ${inlineCode(command.run)}${details.length ? ` — ${details.join("; ")}` : ""}`);
+		}
+	}
+	if (agent.sideEffects) renderTextList(lines, "Side Effects", agent.sideEffects);
+	if (agent.verification) {
+		lines.push("", "### Verification", "");
+		for (const step of agent.verification) {
+			if (typeof step === "string") {
+				lines.push(`- ${step}`);
+				continue;
+			}
+			const summary = step.description ?? (step.run ? `Run ${inlineCode(step.run)}` : step.expect ?? "Verification step");
+			lines.push(`- ${summary}`);
+			if (step.run && step.description) lines.push(`  - Run: ${inlineCode(step.run)}`);
+			if (step.expect && step.expect !== summary) lines.push(`  - Expected: ${step.expect}`);
+		}
+	}
+	if (agent.rollback) renderTextList(lines, "Rollback", agent.rollback);
+	if (agent.failureModes) {
+		lines.push("", "### Failure Modes", "");
+		for (const mode of agent.failureModes) {
+			if (typeof mode === "string") {
+				lines.push(`- ${mode}`);
+				continue;
+			}
+			lines.push(`- ${mode.symptom}${mode.resolution ? ` — Recovery: ${mode.resolution}` : ""}`);
+		}
+	}
+	lines.push(PAGE_AGENT_CONTRACT_END_MARKER);
+	return lines.join("\n");
+}
+/** Remove generated contract blocks while preserving handwritten guidance. */
+function stripGeneratedPageAgentContractMarkdown(markdown) {
+	const newline = markdown.includes("\r\n") ? "\r\n" : "\n";
+	const output = [];
+	let fence;
+	let pendingBlock;
+	let skipEmptySeparator = false;
+	for (const line of markdown.split(/\r?\n/)) {
+		if (pendingBlock) {
+			pendingBlock.push(line);
+			if (isGeneratedAgentContractMarker(line, PAGE_AGENT_CONTRACT_END_MARKER)) {
+				pendingBlock = void 0;
+				skipEmptySeparator = true;
+			}
+			continue;
+		}
+		if (!fence && isGeneratedAgentContractMarker(line, PAGE_AGENT_CONTRACT_START_MARKER)) {
+			pendingBlock = [line];
+			continue;
+		}
+		if (skipEmptySeparator && line.length === 0) continue;
+		skipEmptySeparator = false;
+		output.push(line);
+		fence = advanceMarkdownFence(line, fence);
+	}
+	if (pendingBlock) output.push(...pendingBlock);
+	while (output[0] === "") output.shift();
+	return output.join(newline);
+}
+function isGeneratedAgentContractMarker(line, marker) {
+	if (line.trim() !== marker) return false;
+	const markerIndex = line.indexOf(marker);
+	return markerIndex <= 3 && /^ *$/.test(line.slice(0, markerIndex));
+}
+function advanceMarkdownFence(line, fence) {
+	if (fence) {
+		const closing = /^ {0,3}(`+|~+)[\t ]*$/.exec(line)?.[1];
+		if (closing?.[0] === fence.character && closing.length >= fence.length) return;
+		return fence;
+	}
+	const opening = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+	if (!opening?.[1]) return void 0;
+	if (opening[1][0] === "`" && opening[2]?.includes("`")) return void 0;
+	return {
+		character: opening[1][0],
+		length: opening[1].length
+	};
+}
+function isAgentContractHeadingText(value) {
+	return value.trim().toLowerCase() === "agent contract";
+}
+function hasPageAgentContractHeading(markdown) {
+	let fence;
+	let previousLine;
+	for (const line of markdown.split(/\r?\n/)) {
+		const nextFence = advanceMarkdownFence(line, fence);
+		if (fence || nextFence) {
+			fence = nextFence;
+			previousLine = void 0;
+			continue;
+		}
+		const atxText = /^ {0,3}#{1,6}(?:[\t ]+|$)(.*)$/.exec(line)?.[1]?.replace(/[\t ]+#+[\t ]*$/, "").trim();
+		if (atxText && isAgentContractHeadingText(atxText)) return true;
+		if (previousLine && /^ {0,3}(?:=+|-+)[\t ]*$/.test(line) && isAgentContractHeadingText(previousLine)) return true;
+		previousLine = line.trim().length > 0 && !/^ {4}/.test(line) && !/^ {0,3}\t/.test(line) ? line : void 0;
+	}
+	return false;
+}
+/** Insert one generated contract unless the document already has handwritten contract guidance. */
+function upsertPageAgentContractMarkdown(markdown, value) {
+	const cleaned = stripGeneratedPageAgentContractMarkdown(markdown);
+	const contract = renderPageAgentContractMarkdown(value);
+	if (!contract || hasPageAgentContractHeading(cleaned)) return cleaned;
+	return cleaned ? `${contract}\n\n${cleaned.replace(/^\r?\n+/, "")}` : contract;
+}
+
+//#endregion
+//#region src/markdown-sections.ts
+const docsMarkdownMdxProcessor = createProcessor({ remarkPlugins: [remarkGfm] });
+function isDocsMarkdownLiteralPrompt(node) {
+	return (node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement") && node.name === "Prompt";
+}
+function collectDocsMarkdownLiteralPromptHeadings(root) {
+	const headings = [];
+	const visit = (node, insidePrompt) => {
+		const literal = insidePrompt || isDocsMarkdownLiteralPrompt(node);
+		if (literal && node.type === "heading") {
+			headings.push(node);
+			return;
+		}
+		for (const child of node.children ?? []) visit(child, literal);
+	};
+	visit(root, false);
+	return headings;
+}
+/**
+* Run a third-party heading visitor without exposing headings inside `<Prompt>`.
+*
+* Prompt children are literal, copyable input rather than rendered page content.
+* The node types are restored synchronously even when the visitor throws.
+*/
+function withDocsMarkdownRenderableHeadings(root, visitor) {
+	if (!root || typeof root !== "object") return visitor();
+	const hiddenHeadings = collectDocsMarkdownLiteralPromptHeadings(root);
+	for (const heading of hiddenHeadings) heading.type = "docsLiteralPromptHeading";
+	try {
+		return visitor();
+	} finally {
+		for (const heading of hiddenHeadings) heading.type = "heading";
+	}
+}
+function protectDocsMarkdownCodeSpans(value) {
+	const spans = [];
+	return {
+		value: value.replace(/(`+)([^]*?)\1/gu, (_match, _ticks, code) => {
+			const normalized = code.replace(/\s+/gu, " ");
+			const visible = normalized.length > 2 && normalized.startsWith(" ") && normalized.endsWith(" ") && normalized.trim() ? normalized.slice(1, -1) : normalized;
+			return `\uE000${spans.push(visible) - 1}\uE001`;
+		}),
+		restore: (resolved) => resolved.replace(/\uE000(\d+)\uE001/gu, (_match, index) => spans[Number(index)] ?? "")
+	};
+}
+function protectDocsMarkdownEscapes(value) {
+	const escapes = [];
+	return {
+		value: value.replace(/\\([!"#$%&'()*+,\-./:;<=>?@[\]^_`{|}~])/gu, (_match, punctuation) => `\uE002${escapes.push(punctuation) - 1}\uE003`),
+		restore: (resolved) => resolved.replace(/\uE002(\d+)\uE003/gu, (_match, index) => escapes[Number(index)] ?? "")
+	};
+}
+function findDocsMarkdownClosingDelimiter(value, start, open, close) {
+	let depth = 0;
+	for (let index = start; index < value.length; index += 1) {
+		if (value[index] === "\\") {
+			index += 1;
+			continue;
+		}
+		if (value[index] === open) depth += 1;
+		if (value[index] !== close) continue;
+		depth -= 1;
+		if (depth === 0) return index;
+	}
+	return -1;
+}
+function normalizeDocsMarkdownReferenceLabel(value) {
+	return parseEntities(value.replace(/\\([!"#$%&'()*+,\-./:;<=>?@[\]^_`{|}~])/gu, "$1"), { nonTerminated: false }).replace(/\s+/gu, " ").trim().toLowerCase();
+}
+function cleanDocsMarkdownLinksAndImages(value, definedReferences, restoreEscapes = (input) => input) {
+	let output = "";
+	let index = 0;
+	while (index < value.length) {
+		const image = value[index] === "!" && value[index + 1] === "[";
+		const link = value[index] === "[";
+		if (!image && !link) {
+			output += value[index];
+			index += 1;
+			continue;
+		}
+		const labelStart = index + (image ? 2 : 1);
+		const labelEnd = findDocsMarkdownClosingDelimiter(value, labelStart - 1, "[", "]");
+		if (labelEnd < 0) {
+			output += value[index];
+			index += 1;
+			continue;
+		}
+		const label = value.slice(labelStart, labelEnd);
+		let end = labelEnd + 1;
+		let inlineDestination = false;
+		let referenceLabel;
+		if (value[end] === "(") {
+			const destinationEnd = findDocsMarkdownClosingDelimiter(value, end, "(", ")");
+			if (destinationEnd < 0) {
+				output += value[index];
+				index += 1;
+				continue;
+			}
+			end = destinationEnd + 1;
+			inlineDestination = true;
+		} else if (value[end] === "[") {
+			const referenceEnd = findDocsMarkdownClosingDelimiter(value, end, "[", "]");
+			if (referenceEnd < 0) {
+				output += value[index];
+				index += 1;
+				continue;
+			}
+			referenceLabel = value.slice(end + 1, referenceEnd) || label;
+			end = referenceEnd + 1;
+		} else referenceLabel = label;
+		const hasMatchingDefinition = referenceLabel !== void 0 && definedReferences?.has(normalizeDocsMarkdownReferenceLabel(restoreEscapes(referenceLabel))) === true;
+		if (!image && (inlineDestination || hasMatchingDefinition)) output += label;
+		else if (!inlineDestination && !hasMatchingDefinition) output += value.slice(index, end);
+		index = end;
+	}
+	return output;
+}
+function stripDocsMarkdownTags(value) {
+	let output = "";
+	let index = 0;
+	while (index < value.length) {
+		if (value[index] !== "<" || !/[A-Za-z/!?]/u.test(value[index + 1] ?? "")) {
+			output += value[index];
+			index += 1;
+			continue;
+		}
+		let quote;
+		let braceDepth = 0;
+		let end = index + 1;
+		for (; end < value.length; end += 1) {
+			const character = value[end];
+			if (quote) {
+				if (character === quote && value[end - 1] !== "\\") quote = void 0;
+				continue;
+			}
+			if (character === "'" || character === "\"") {
+				quote = character;
+				continue;
+			}
+			if (character === "{") {
+				braceDepth += 1;
+				continue;
+			}
+			if (character === "}") {
+				braceDepth = Math.max(0, braceDepth - 1);
+				continue;
+			}
+			if (character === ">" && braceDepth === 0) break;
+		}
+		if (end >= value.length) {
+			output += value[index];
+			index += 1;
+			continue;
+		}
+		index = end + 1;
+	}
+	return output;
+}
+/**
+* Reduce inline Markdown in a heading to the visible label used by search and anchors.
+* This intentionally covers the common inline constructs without adding a Markdown parser
+* dependency to the runtime package.
+*/
+function cleanDocsMarkdownHeadingLabelWithReferences(value, definedReferences) {
+	const codeSpans = protectDocsMarkdownCodeSpans(value);
+	const escapes = protectDocsMarkdownEscapes(codeSpans.value);
+	const visible = stripDocsMarkdownTags(cleanDocsMarkdownLinksAndImages(escapes.value, definedReferences, escapes.restore).replace(/<((?:https?:\/\/|mailto:)[^>]+)>/giu, "$1")).replace(/`+([^`]*?)`+/gu, "$1").replace(/\*\*([^*\n]+)\*\*/gu, "$1").replace(/(?<![\\\p{L}\p{N}])__([^_\n]+)__(?![\p{L}\p{N}])/gu, "$1").replace(/\*([^*\n]+)\*/gu, "$1").replace(/(?<![\\\p{L}\p{N}])_([^_\n]+)_(?![\p{L}\p{N}])/gu, "$1").replace(/~~([^~\n]+)~~/gu, "$1").trim();
+	return codeSpans.restore(escapes.restore(parseEntities(visible, { nonTerminated: false }))).replace(/\s+/gu, " ").trim();
+}
+function cleanDocsMarkdownHeadingLabel(value) {
+	return cleanDocsMarkdownHeadingLabelWithReferences(value);
+}
+const EXPLICIT_DOCS_MARKDOWN_HEADING_ID = /\s*\\?\[#([^\]\r\n]+)\]\s*$/u;
+function createDocsHeadingAnchorState() {
+	const used = /* @__PURE__ */ new Set();
+	const suffixes = /* @__PURE__ */ new Map();
+	let headingIndex = 0;
+	return (title, explicitAnchor) => {
+		const fallback = `section-${headingIndex}`;
+		headingIndex += 1;
+		const original = explicitAnchor?.trim() || slug(title) || fallback;
+		let anchor = original;
+		let suffix = suffixes.get(original) ?? 0;
+		while (used.has(anchor)) {
+			suffix += 1;
+			anchor = `${original}-${suffix}`;
+		}
+		suffixes.set(original, suffix);
+		used.add(anchor);
+		return anchor;
+	};
+}
+/** Normalize text that has already been flattened from a rendered heading AST. */
+function cleanDocsRenderedHeadingLabel(value) {
+	return value.replace(/\s+/gu, " ").trim();
+}
+/**
+* Create a stateful resolver for text already flattened by an MDX renderer.
+*
+* Unlike the raw-Markdown resolver, this does not reinterpret inline code or a
+* literal `[#id]` as Markdown syntax.
+*/
+function createDocsRenderedHeadingAnchorResolver() {
+	const reserveAnchor = createDocsHeadingAnchorState();
+	return (value, options = {}) => {
+		const title = cleanDocsRenderedHeadingLabel(value);
+		const explicitAnchor = options.explicitAnchor?.trim();
+		return {
+			source: title,
+			title,
+			anchor: reserveAnchor(title, explicitAnchor),
+			explicit: Boolean(explicitAnchor)
+		};
+	};
+}
+/**
+* Create a stateful heading resolver compatible with Fumadocs' GitHub-style rendered IDs.
+*
+* A fresh resolver must be used for each document so duplicate and collision suffixes
+* remain deterministic in source order.
+*/
+function createDocsMarkdownHeadingAnchorResolverWithReferences(definedReferences) {
+	const reserveAnchor = createDocsHeadingAnchorState();
+	return (value) => {
+		const explicitMatch = value.match(EXPLICIT_DOCS_MARKDOWN_HEADING_ID);
+		const rawExplicitAnchor = explicitMatch?.[1]?.trim();
+		const explicitMarker = explicitMatch?.index === void 0 ? "" : value.slice(explicitMatch.index).trimStart();
+		const resolvesAsReference = Boolean(rawExplicitAnchor) && !explicitMarker.startsWith("\\[") && definedReferences?.has(normalizeDocsMarkdownReferenceLabel(`#${rawExplicitAnchor}`)) === true;
+		const explicitAnchor = rawExplicitAnchor && !resolvesAsReference ? parseEntities(rawExplicitAnchor, { nonTerminated: false }) : void 0;
+		const source = (explicitAnchor && explicitMatch ? value.slice(0, explicitMatch.index) : value).trim();
+		const title = cleanDocsMarkdownHeadingLabelWithReferences(source, definedReferences);
+		return {
+			source,
+			title,
+			anchor: reserveAnchor(title, explicitAnchor),
+			explicit: Boolean(explicitAnchor)
+		};
+	};
+}
+function createDocsMarkdownHeadingAnchorResolver() {
+	return createDocsMarkdownHeadingAnchorResolverWithReferences();
+}
+function collectDocsMarkdownAstReferenceDefinitions(root) {
+	const definitions = /* @__PURE__ */ new Set();
+	const visit = (node) => {
+		if (isDocsMarkdownLiteralPrompt(node)) return;
+		if (node.type === "definition" && typeof node.identifier === "string") definitions.add(normalizeDocsMarkdownReferenceLabel(node.identifier));
+		for (const child of node.children ?? []) visit(child);
+	};
+	visit(root);
+	return definitions;
+}
+function formatDocsMarkdownAstReference(node, definedReferences) {
+	const image = node.type === "imageReference";
+	const identifier = typeof node.identifier === "string" ? normalizeDocsMarkdownReferenceLabel(node.identifier) : "";
+	if (Boolean(identifier) && definedReferences.has(identifier)) return image ? "" : (node.children ?? []).map((child) => flattenDocsMarkdownAstNode(child, definedReferences)).join("");
+	const visibleLabel = image ? typeof node.alt === "string" ? node.alt : "" : (node.children ?? []).map((child) => flattenDocsMarkdownAstNode(child, definedReferences)).join("");
+	const referenceLabel = typeof node.label === "string" ? node.label : typeof node.identifier === "string" ? node.identifier : visibleLabel;
+	const prefix = image ? "!" : "";
+	if (node.referenceType === "collapsed") return `${prefix}[${visibleLabel}][]`;
+	if (node.referenceType === "shortcut") return `${prefix}[${visibleLabel}]`;
+	return `${prefix}[${visibleLabel}][${referenceLabel}]`;
+}
+function flattenDocsMarkdownAstNode(node, definedReferences) {
+	if (node.type === "linkReference" || node.type === "imageReference") return formatDocsMarkdownAstReference(node, definedReferences);
+	if (Array.isArray(node.children)) return node.children.map((child) => flattenDocsMarkdownAstNode(child, definedReferences)).join("");
+	return typeof node.value === "string" ? node.value : "";
+}
+function assignDocsMarkdownAstHeadingAnchors(root, options, deferHeading) {
+	const customId = options.customId ?? true;
+	const headings = [];
+	const definedReferences = collectDocsMarkdownAstReferenceDefinitions(root);
+	const visit = (node) => {
+		if (isDocsMarkdownLiteralPrompt(node)) return;
+		if (node.type === "heading") {
+			const lastNode = node.children?.at(-1);
+			let explicitAnchor;
+			if (customId && lastNode?.type === "text" && typeof lastNode.value === "string") {
+				const match = lastNode.value.match(EXPLICIT_DOCS_MARKDOWN_HEADING_ID);
+				explicitAnchor = match?.[1]?.trim();
+				if (explicitAnchor && match?.index !== void 0) lastNode.value = lastNode.value.slice(0, match.index);
+			}
+			const existingAnchor = node.data?.hProperties?.id;
+			headings.push({
+				node,
+				title: cleanDocsRenderedHeadingLabel(flattenDocsMarkdownAstNode(node, definedReferences)),
+				explicit: Boolean(explicitAnchor),
+				explicitAnchor: explicitAnchor || (typeof existingAnchor === "string" ? existingAnchor : void 0),
+				start: typeof node.position?.start?.line === "number" ? node.position.start.line - 1 : NaN
+			});
+			return;
+		}
+		for (const child of node.children ?? []) visit(child);
+	};
+	visit(root);
+	const ordered = deferHeading ? [...headings.filter((heading) => !deferHeading(heading.start)), ...headings.filter((heading) => deferHeading(heading.start))] : headings;
+	const resolveHeading = createDocsRenderedHeadingAnchorResolver();
+	for (const heading of ordered) {
+		const resolved = resolveHeading(heading.title, { explicitAnchor: heading.explicitAnchor });
+		heading.node.data ??= {};
+		heading.node.data.hProperties ??= {};
+		heading.node.data.hProperties.id = resolved.anchor;
+	}
+	return headings;
+}
+/**
+* Assign canonical IDs to every heading in an MDX syntax tree.
+*
+* Render adapters call this before Fumadocs extracts its TOC, ensuring HTML,
+* Markdown retrieval, search, Ask AI, and MCP all use the same fragments.
+*/
+function applyDocsMarkdownHeadingAnchors(root, options = {}) {
+	if (!root || typeof root !== "object") return;
+	assignDocsMarkdownAstHeadingAnchors(root, options);
+}
+/** Resolve one heading with the canonical GitHub-style anchor algorithm. */
+function slugifyDocsMarkdownHeading(value) {
+	return createDocsMarkdownHeadingAnchorResolver()(value).anchor;
+}
+function readOpeningFence(line) {
+	const match = line.match(/^ {0,3}(`{3,}|~{3,})/u);
+	if (!match) return void 0;
+	return {
+		marker: match[1][0],
+		length: match[1].length
+	};
+}
+function isClosingFence(line, fence) {
+	const marker = fence.marker === "`" ? "`" : "~";
+	const match = line.match(new RegExp(`^ {0,3}(${marker}{${fence.length},})[\\t ]*$`, "u"));
+	return Boolean(match);
+}
+function splitDocsMarkdownContainerLine(line) {
+	let prefix = "";
+	let content = line;
+	const containers = [];
+	while (content) {
+		const blockquote = content.match(/^ {0,3}>[\t ]?/u);
+		if (blockquote) {
+			prefix += blockquote[0];
+			content = content.slice(blockquote[0].length);
+			containers.push({
+				type: "blockquote",
+				continuationIndent: 0
+			});
+			continue;
+		}
+		const listItem = content.match(/^ {0,3}(?:[-+*]|\d{1,9}[.)])[\t ]+/u);
+		if (listItem) {
+			prefix += listItem[0];
+			content = content.slice(listItem[0].length);
+			containers.push({
+				type: "list",
+				continuationIndent: listItem[0].length
+			});
+			continue;
+		}
+		break;
+	}
+	return {
+		prefix,
+		content,
+		containers
+	};
+}
+function continueDocsMarkdownContainerLine(line, containers) {
+	let prefix = "";
+	let content = line;
+	for (const container of containers) {
+		if (container.type === "blockquote") {
+			const blockquote = content.match(/^ {0,3}>[\t ]?/u);
+			if (!blockquote) return void 0;
+			prefix += blockquote[0];
+			content = content.slice(blockquote[0].length);
+			continue;
+		}
+		if (!content.trim()) {
+			prefix += content;
+			content = "";
+			continue;
+		}
+		const indentation = content.match(/^[\t ]*/u)?.[0] ?? "";
+		if (indentation.replace(/\t/gu, "    ").length < container.continuationIndent) return void 0;
+		let consumedWidth = 0;
+		let consumedLength = 0;
+		while (consumedLength < indentation.length) {
+			consumedWidth += indentation[consumedLength] === "	" ? 4 : 1;
+			consumedLength += 1;
+			if (consumedWidth >= container.continuationIndent) break;
+		}
+		const consumed = content.slice(0, consumedLength);
+		prefix += consumed;
+		content = content.slice(consumedLength);
+	}
+	return {
+		prefix,
+		content,
+		containers: containers.map((container) => ({ ...container }))
+	};
+}
+function readDocsMarkdownFenceLine(line, fence) {
+	if (fence.containers.length === 0) return {
+		prefix: "",
+		content: line,
+		containers: []
+	};
+	return continueDocsMarkdownContainerLine(line, fence.containers);
+}
+function readDocsMarkdownReferenceDefinition(line) {
+	const content = line.trimStart();
+	if (!content.startsWith("[")) return void 0;
+	const labelEnd = findDocsMarkdownClosingDelimiter(content, 0, "[", "]");
+	if (labelEnd <= 1 || content[labelEnd + 1] !== ":") return void 0;
+	return normalizeDocsMarkdownReferenceLabel(content.slice(1, labelEnd)) || void 0;
+}
+function collectDocsMarkdownReferenceDefinitions(lines) {
+	const definitions = /* @__PURE__ */ new Set();
+	let openFence;
+	for (const line of lines) {
+		if (openFence) {
+			const fenceLine = readDocsMarkdownFenceLine(line, openFence);
+			if (fenceLine) {
+				if (isClosingFence(fenceLine.content, openFence)) openFence = void 0;
+				continue;
+			}
+			openFence = void 0;
+		}
+		const containerLine = splitDocsMarkdownContainerLine(line);
+		const openingFence = readOpeningFence(containerLine.content);
+		if (openingFence) {
+			openFence = {
+				...openingFence,
+				containers: containerLine.containers
+			};
+			continue;
+		}
+		const definition = readDocsMarkdownReferenceDefinition(containerLine.content);
+		if (definition) definitions.add(definition);
+	}
+	return definitions;
+}
+function scanDocsMarkdownFallbackEsmLine(line, state) {
+	for (let index = 0; index < line.length; index += 1) {
+		const character = line[index];
+		const next = line[index + 1];
+		if (state.blockComment) {
+			if (character === "*" && next === "/") {
+				state.blockComment = false;
+				index += 1;
+			}
+			continue;
+		}
+		if (state.quote) {
+			if (character === "\\") {
+				index += 1;
+				continue;
+			}
+			if (character === state.quote) state.quote = void 0;
+			continue;
+		}
+		if (character === "/" && next === "*") {
+			state.blockComment = true;
+			index += 1;
+			continue;
+		}
+		if (character === "/" && next === "/") break;
+		if (character === "'" || character === "\"" || character === "`") {
+			state.quote = character;
+			continue;
+		}
+		if (character === "{") state.braceDepth += 1;
+		if (character === "}") state.braceDepth = Math.max(0, state.braceDepth - 1);
+		if (character === "[") state.bracketDepth += 1;
+		if (character === "]") state.bracketDepth = Math.max(0, state.bracketDepth - 1);
+		if (character === "(") state.parenDepth += 1;
+		if (character === ")") state.parenDepth = Math.max(0, state.parenDepth - 1);
+	}
+	return Boolean(state.blockComment || state.quote || state.braceDepth || state.bracketDepth || state.parenDepth || /(?:[=,]|=>)\s*$/u.test(line));
+}
+function scanDocsMarkdownLiteralPromptTags(value, initialState) {
+	let delta = 0;
+	let found = Boolean(initialState);
+	let pending = initialState;
+	let index = 0;
+	while (index < value.length) {
+		if (!pending) {
+			const tagStart = value.indexOf("<", index);
+			if (tagStart < 0) break;
+			if (!found && value.slice(0, tagStart).trim()) {
+				index = tagStart + 1;
+				continue;
+			}
+			const closing = value[tagStart + 1] === "/";
+			const nameStart = tagStart + (closing ? 2 : 1);
+			if (value.slice(nameStart, nameStart + 6) !== "Prompt") {
+				index = tagStart + 1;
+				continue;
+			}
+			const boundary = value[nameStart + 6];
+			if (boundary && !/[\t\n\r />]/u.test(boundary)) {
+				index = tagStart + 1;
+				continue;
+			}
+			pending = {
+				braceDepth: 0,
+				closing,
+				lastNonWhitespace: "t"
+			};
+			found = true;
+			index = nameStart + 6;
+		}
+		while (pending && index < value.length) {
+			const character = value[index];
+			if (pending.quote) {
+				if (character === "\\") {
+					index += 2;
+					continue;
+				}
+				if (character === pending.quote) pending.quote = void 0;
+				index += 1;
+				continue;
+			}
+			if (character === "'" || character === "\"" || character === "`") {
+				pending.quote = character;
+				index += 1;
+				continue;
+			}
+			if (character === "{") {
+				pending.braceDepth += 1;
+				pending.lastNonWhitespace = character;
+				index += 1;
+				continue;
+			}
+			if (character === "}") {
+				pending.braceDepth = Math.max(0, pending.braceDepth - 1);
+				pending.lastNonWhitespace = character;
+				index += 1;
+				continue;
+			}
+			if (character === ">" && pending.braceDepth === 0) {
+				if (pending.closing) delta -= 1;
+				else if (pending.lastNonWhitespace !== "/") delta += 1;
+				pending = void 0;
+				index += 1;
+				break;
+			}
+			if (!/\s/u.test(character)) pending.lastNonWhitespace = character;
+			index += 1;
+		}
+	}
+	return {
+		delta,
+		found,
+		...pending ? { pending } : {}
+	};
+}
+function collectDocsMarkdownFallbackIgnoredLines(lines) {
+	const ignored = /* @__PURE__ */ new Set();
+	let esmState;
+	let htmlComment = false;
+	let mdxComment = false;
+	let literalPromptDepth = 0;
+	let literalPromptTagContainers = [];
+	let literalPromptTagState;
+	let openFence;
+	for (let index = 0; index < lines.length; index += 1) {
+		const line = lines[index];
+		if (literalPromptTagState) {
+			const promptTags = scanDocsMarkdownLiteralPromptTags((literalPromptTagContainers.length > 0 ? continueDocsMarkdownContainerLine(line, literalPromptTagContainers) : { content: line })?.content ?? line, literalPromptTagState);
+			ignored.add(index);
+			literalPromptDepth = Math.max(0, literalPromptDepth + promptTags.delta);
+			literalPromptTagState = promptTags.pending;
+			if (!literalPromptTagState) literalPromptTagContainers = [];
+			continue;
+		}
+		if (!esmState && !htmlComment && !mdxComment && openFence) {
+			const fenceLine = readDocsMarkdownFenceLine(line, openFence);
+			if (fenceLine) {
+				if (isClosingFence(fenceLine.content, openFence)) openFence = void 0;
+				continue;
+			}
+			openFence = void 0;
+		}
+		const containerLine = splitDocsMarkdownContainerLine(line);
+		const logicalLine = containerLine.content;
+		if (!esmState && !htmlComment && !mdxComment) {
+			const openingFence = readOpeningFence(logicalLine);
+			if (openingFence) {
+				openFence = {
+					...openingFence,
+					containers: containerLine.containers
+				};
+				continue;
+			}
+		}
+		if (mdxComment) {
+			ignored.add(index);
+			if (logicalLine.includes("*/}")) mdxComment = false;
+			continue;
+		}
+		if (htmlComment) {
+			ignored.add(index);
+			if (logicalLine.includes("-->")) htmlComment = false;
+			continue;
+		}
+		if (esmState) {
+			ignored.add(index);
+			if (!scanDocsMarkdownFallbackEsmLine(logicalLine, esmState)) esmState = void 0;
+			continue;
+		}
+		const trimmed = logicalLine.trimStart();
+		if (trimmed.startsWith("{/*")) {
+			ignored.add(index);
+			mdxComment = !trimmed.includes("*/}");
+			continue;
+		}
+		if (trimmed.startsWith("<!--")) {
+			ignored.add(index);
+			htmlComment = !trimmed.includes("-->");
+			continue;
+		}
+		if (/^(?:import|export)(?:[\t ]|[{*]|$)/u.test(trimmed)) {
+			ignored.add(index);
+			const state = {
+				blockComment: false,
+				braceDepth: 0,
+				bracketDepth: 0,
+				parenDepth: 0
+			};
+			if (scanDocsMarkdownFallbackEsmLine(logicalLine, state)) esmState = state;
+			continue;
+		}
+		const promptTags = scanDocsMarkdownLiteralPromptTags(logicalLine);
+		if (literalPromptDepth > 0 || promptTags.found) {
+			ignored.add(index);
+			literalPromptDepth = Math.max(0, literalPromptDepth + promptTags.delta);
+			literalPromptTagState = promptTags.pending;
+			if (literalPromptTagState) literalPromptTagContainers = containerLine.containers.map((container) => ({ ...container }));
+		}
+	}
+	return ignored;
+}
+function readAtxHeading(line) {
+	const match = line.match(/^ {0,3}(#{1,6})(?:[\t ]+|$)(.*)$/u);
+	if (!match) return void 0;
+	return {
+		source: match[2].replace(/[\t ]+#+[\t ]*$/u, "").trim(),
+		level: match[1].length
+	};
+}
+function readSetextLevel(line) {
+	const match = line.match(/^ {0,3}(=+|-+)[\t ]*$/u);
+	if (!match) return void 0;
+	return match[1][0] === "=" ? 1 : 2;
+}
+function normalizeDocsSectionSelector(value, extractFragment = true) {
+	let selector = value.trim();
+	const hashIndex = selector.indexOf("#");
+	if (extractFragment && hashIndex >= 0) selector = selector.slice(hashIndex + 1);
+	try {
+		selector = decodeURIComponent(selector);
+	} catch {}
+	return cleanDocsMarkdownHeadingLabel(selector).toLowerCase();
+}
+function decodeDocsSectionSelector(value) {
+	let selector = value.trim();
+	const hashIndex = selector.indexOf("#");
+	if (hashIndex >= 0) selector = selector.slice(hashIndex + 1);
+	try {
+		selector = decodeURIComponent(selector);
+	} catch {}
+	return selector;
+}
+function isTopLevelDocsMarkdownMarker(line, marker) {
+	if (line.trim() !== marker) return false;
+	const markerIndex = line.indexOf(marker);
+	return markerIndex <= 3 && /^ *$/u.test(line.slice(0, markerIndex));
+}
+function collectGeneratedAgentContractRanges(markdown) {
+	const lines = markdown.split(/\r?\n/u);
+	const ranges = [];
+	let openFence;
+	let contractStart;
+	for (let index = 0; index < lines.length; index += 1) {
+		const line = lines[index];
+		if (openFence) {
+			const fenceLine = readDocsMarkdownFenceLine(line, openFence);
+			if (fenceLine) {
+				if (isClosingFence(fenceLine.content, openFence)) openFence = void 0;
+				continue;
+			}
+			openFence = void 0;
+		}
+		const containerLine = splitDocsMarkdownContainerLine(line);
+		const openingFence = readOpeningFence(containerLine.content);
+		if (openingFence) {
+			openFence = {
+				...openingFence,
+				containers: containerLine.containers
+			};
+			continue;
+		}
+		if (containerLine.containers.length > 0) continue;
+		if (contractStart !== void 0) {
+			if (isTopLevelDocsMarkdownMarker(line, PAGE_AGENT_CONTRACT_END_MARKER)) {
+				ranges.push({
+					start: contractStart,
+					end: index
+				});
+				contractStart = void 0;
+			}
+		} else if (isTopLevelDocsMarkdownMarker(line, PAGE_AGENT_CONTRACT_START_MARKER)) contractStart = index;
+	}
+	return ranges;
+}
+/** Locate complete generated contract blocks while keeping fenced marker examples inert. */
+function findDocsGeneratedAgentContractRanges(markdown) {
+	return collectGeneratedAgentContractRanges(markdown).map(({ start, end }) => ({
+		startLine: start + 1,
+		endLine: end + 1
+	}));
+}
+/** Remove only generated boundary markers that overlap a full document or derived fragment. */
+function stripDocsGeneratedAgentContractMarkers(markdown, location) {
+	const ranges = findDocsGeneratedAgentContractRanges(location?.sourceMarkdown ?? markdown);
+	if (ranges.length === 0) return markdown;
+	const markerLines = /* @__PURE__ */ new Set();
+	for (const range of ranges) {
+		markerLines.add(range.startLine);
+		markerLines.add(range.endLine);
+	}
+	const newline = markdown.includes("\r\n") ? "\r\n" : "\n";
+	const startLine = location?.startLine ?? 1;
+	const output = markdown.split(/\r?\n/u).filter((_line, index) => !markerLines.has(startLine + index));
+	while (output[0] === "") output.shift();
+	return output.join(newline);
+}
+function isDocsMarkdownLineInRanges(line, ranges) {
+	return ranges.some((range) => line >= range.start && line <= range.end);
+}
+/**
+* Parse heading sections once for search, Ask AI hydration, and MCP tools.
+* Supports CommonMark ATX indentation, Setext headings, fenced-code exclusion,
+* visible inline labels, and stable duplicate anchors.
+*/
+function parseDocsMarkdownSectionsFallback(markdown, generatedContractRanges) {
+	const lines = markdown.split(/\r?\n/u);
+	const headings = [];
+	const ignoredLines = collectDocsMarkdownFallbackIgnoredLines(lines);
+	const definedReferences = collectDocsMarkdownReferenceDefinitions(lines.map((line, index) => ignoredLines.has(index) ? "" : line));
+	let openFence;
+	let setextCandidate;
+	const pushHeading = (value, level, start) => {
+		headings.push({
+			source: value,
+			level,
+			start
+		});
+	};
+	for (let index = 0; index < lines.length; index += 1) {
+		const line = lines[index];
+		if (openFence) {
+			const fenceLine = readDocsMarkdownFenceLine(line, openFence);
+			if (fenceLine) {
+				if (isClosingFence(fenceLine.content, openFence)) openFence = void 0;
+				setextCandidate = void 0;
+				continue;
+			}
+			openFence = void 0;
+		}
+		if (ignoredLines.has(index)) {
+			setextCandidate = void 0;
+			continue;
+		}
+		const containerLine = splitDocsMarkdownContainerLine(line);
+		const logicalLine = containerLine.content;
+		const openingFence = readOpeningFence(logicalLine);
+		if (openingFence) {
+			openFence = {
+				...openingFence,
+				containers: containerLine.containers
+			};
+			setextCandidate = void 0;
+			continue;
+		}
+		const setextLine = setextCandidate ? continueDocsMarkdownContainerLine(line, setextCandidate.containers) : void 0;
+		const setextLevel = setextLine ? readSetextLevel(setextLine.content) : void 0;
+		if (setextLevel && setextCandidate?.lastIndex === index - 1) {
+			const source = setextCandidate.values.join("\n").trim();
+			if (!source.startsWith("<")) pushHeading(source, setextLevel, setextCandidate.index);
+			setextCandidate = void 0;
+			continue;
+		}
+		const atxHeading = readAtxHeading(logicalLine);
+		if (atxHeading) {
+			pushHeading(atxHeading.source, atxHeading.level, index);
+			setextCandidate = void 0;
+			continue;
+		}
+		if (!logicalLine.trim() || /^ {4}|^\t/u.test(logicalLine)) {
+			setextCandidate = void 0;
+			continue;
+		}
+		if (readDocsMarkdownReferenceDefinition(logicalLine)) {
+			setextCandidate = void 0;
+			continue;
+		}
+		const candidate = setextCandidate;
+		const paragraphContinuation = candidate?.lastIndex === index - 1 ? continueDocsMarkdownContainerLine(line, candidate.containers) : void 0;
+		if (candidate && paragraphContinuation) {
+			candidate.values.push(paragraphContinuation.content);
+			candidate.lastIndex = index;
+			continue;
+		}
+		setextCandidate = {
+			index,
+			lastIndex: index,
+			values: [logicalLine],
+			containers: containerLine.containers
+		};
+	}
+	const resolveHeadingAnchor = createDocsMarkdownHeadingAnchorResolverWithReferences(definedReferences);
+	const orderedHeadings = [...headings.filter((heading) => !isDocsMarkdownLineInRanges(heading.start, generatedContractRanges)), ...headings.filter((heading) => isDocsMarkdownLineInRanges(heading.start, generatedContractRanges))];
+	for (const heading of orderedHeadings) heading.resolved = resolveHeadingAnchor(heading.source);
+	return headings.map((heading, index) => {
+		const end = headings.slice(index + 1).find((candidate) => candidate.level <= heading.level)?.start ?? lines.length;
+		const resolved = heading.resolved;
+		if (!resolved) throw new Error("Failed to resolve a Markdown heading anchor.");
+		return {
+			title: resolved.title,
+			anchor: resolved.anchor,
+			explicit: resolved.explicit,
+			level: heading.level,
+			content: lines.slice(heading.start, end).join("\n").trim(),
+			startLine: heading.start + 1,
+			endLine: end
+		};
+	});
+}
+function stripDocsMarkdownSectionFrontmatter(markdown) {
+	return markdown.match(/^\uFEFF?---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)([\s\S]*)$/u)?.[1] ?? markdown;
+}
+function parseDocsMarkdownAstSections(markdown, generatedContractRanges) {
+	let root;
+	try {
+		root = docsMarkdownMdxProcessor.parse(markdown);
+	} catch {
+		return;
+	}
+	const headings = assignDocsMarkdownAstHeadingAnchors(root, {}, (start) => isDocsMarkdownLineInRanges(start, generatedContractRanges)).flatMap((heading) => {
+		const level = typeof heading.node.depth === "number" ? heading.node.depth : NaN;
+		const anchor = heading.node.data?.hProperties?.id;
+		if (!Number.isInteger(level) || level < 1 || level > 6 || !Number.isInteger(heading.start) || heading.start < 0 || typeof anchor !== "string") return [];
+		return [{
+			title: heading.title,
+			anchor,
+			explicit: heading.explicit,
+			level,
+			start: heading.start
+		}];
+	});
+	const lines = markdown.split(/\r?\n/u);
+	return headings.map((heading, index) => {
+		const end = headings.slice(index + 1).find((candidate) => candidate.level <= heading.level)?.start ?? lines.length;
+		return {
+			title: heading.title,
+			anchor: heading.anchor,
+			explicit: heading.explicit,
+			level: heading.level,
+			content: lines.slice(heading.start, end).join("\n").trim(),
+			startLine: heading.start + 1,
+			endLine: end
+		};
+	});
+}
+function parseDocsMarkdownSections(markdown) {
+	const body = stripDocsMarkdownSectionFrontmatter(markdown);
+	const generatedContractRanges = collectGeneratedAgentContractRanges(body);
+	return parseDocsMarkdownAstSections(body, generatedContractRanges) ?? parseDocsMarkdownSectionsFallback(body, generatedContractRanges);
+}
+function findDocsMarkdownSection(markdown, requestedSection) {
+	const sections = parseDocsMarkdownSections(markdown);
+	const rawSelector = requestedSection.trim();
+	const rawAnchor = sections.find((section) => section.anchor === rawSelector);
+	if (rawAnchor) return rawAnchor;
+	const decodedSelector = decodeDocsSectionSelector(requestedSection);
+	const exactAnchor = sections.find((section) => section.anchor === decodedSelector);
+	if (exactAnchor) return exactAnchor;
+	const caseInsensitiveAnchors = sections.filter((section) => section.anchor.toLowerCase() === decodedSelector.toLowerCase());
+	if (caseInsensitiveAnchors.length === 1) return caseInsensitiveAnchors[0];
+	if (caseInsensitiveAnchors.length > 1) return void 0;
+	const selector = normalizeDocsSectionSelector(requestedSection);
+	if (!selector) return void 0;
+	return sections.find((section) => normalizeDocsSectionSelector(section.title, false) === selector);
+}
+
+//#endregion
+export { upsertPageAgentContractMarkdown as S, hasStructuredPageAgentContract as _, findDocsGeneratedAgentContractRanges as a, renderPageAgentFrontmatterYamlLines as b, slugifyDocsMarkdownHeading as c, PAGE_AGENT_CONTRACT_END_MARKER as d, PAGE_AGENT_CONTRACT_FIELDS as f, getPageAgentFrontmatterIssues as g, PAGE_AGENT_STRUCTURED_CONTRACT_FIELDS as h, createDocsRenderedHeadingAnchorResolver as i, stripDocsGeneratedAgentContractMarkers as l, PAGE_AGENT_CONTRACT_START_MARKER as m, cleanDocsRenderedHeadingLabel as n, findDocsMarkdownSection as o, PAGE_AGENT_CONTRACT_FIELD_SCHEMA as p, createDocsMarkdownHeadingAnchorResolver as r, parseDocsMarkdownSections as s, applyDocsMarkdownHeadingAnchors as t, withDocsMarkdownRenderableHeadings as u, normalizePageAgentFrontmatter as v, stripGeneratedPageAgentContractMarkdown as x, renderPageAgentContractMarkdown as y };