@abinnovision/payloadcms-mcpx 1.0.0-beta.8 → 1.0.0

package/dist/schema/outline.mjs

@@ -0,0 +1,67 @@
+import { allowedNodeTypes, nodeOptions } from "./lexical.mjs";
+import { isPlainObject } from "./walk.mjs";
+//#region src/schema/outline.ts
+/**
+* Long enough to identify a paragraph, short enough that an outline of a real
+* document stays a fraction of the size of its editor state.
+*/ const TEXT_PREVIEW_LENGTH = 80;
+/**
+* Every descendant text node contributes, not only direct children, since a
+* link or a formatting mark nests the text a level deeper.
+*/ const collectText = (node) => {
+	if (node["type"] === "text") return typeof node["text"] === "string" ? node["text"] : "";
+	const children = node["children"];
+	return Array.isArray(children) ? children.filter(isPlainObject).map((child) => collectText(child)).join("") : "";
+};
+const preview = (text) => text.length > TEXT_PREVIEW_LENGTH ? `${text.slice(0, TEXT_PREVIEW_LENGTH)}…` : text;
+/**
+* Only the properties a feature actually narrows for this node type, and only
+* where the node carries a string for one. A node missing the property, or
+* carrying something the feature never produces, says nothing worth reporting.
+*/ const narrowedOptions = (node, narrowed) => {
+	if (!narrowed) return;
+	const set = Object.keys(narrowed).flatMap((property) => {
+		const value = node[property];
+		return typeof value === "string" ? [[property, value]] : [];
+	});
+	return set.length > 0 ? Object.fromEntries(set) : void 0;
+};
+const walk = (node, pointer, options, entries) => {
+	const type = node["type"];
+	if (typeof type !== "string") return;
+	const version = node["version"];
+	const text = preview(collectText(node));
+	const nodeOptionsFound = narrowedOptions(node, options?.[type]);
+	const children = node["children"];
+	const childCount = Array.isArray(children) ? children.length : 0;
+	entries.push({
+		...childCount === 0 ? {} : { children: childCount },
+		...nodeOptionsFound === void 0 ? {} : { options: nodeOptionsFound },
+		pointer,
+		...text === "" ? {} : { text },
+		type,
+		...typeof version === "number" ? { version } : {}
+	});
+	if (Array.isArray(children)) children.forEach((child, index) => {
+		if (isPlainObject(child)) walk(child, `${pointer}/children/${String(index)}`, options, entries);
+	});
+};
+/**
+* A depth-first listing of every node under an editor state's root, so an
+* agent can find a position and a sibling's `version` without reading the
+* whole state. `basePointer` is the field's own pointer, e.g. "/content"; each
+* entry's `pointer` extends it with "/root" and the node's real indices, which
+* makes it directly usable in a patch operation.
+*/ const lexicalOutline = (state, basePointer, field) => {
+	if (!isPlainObject(state)) return [];
+	const root = state["root"];
+	if (!isPlainObject(root) || !Array.isArray(root["children"])) return [];
+	const options = nodeOptions(field, allowedNodeTypes(field));
+	const entries = [];
+	root["children"].forEach((child, index) => {
+		if (isPlainObject(child)) walk(child, `${basePointer}/root/children/${String(index)}`, options, entries);
+	});
+	return entries;
+};
+//#endregion
+export { lexicalOutline };

package/dist/schema/pointer.mjs

@@ -1,6 +1,6 @@
-import { blockOf, blockSlugsOf, describeAddressableFields, findBlocksField, joinPath, splitPath, targetOf } from "./walk.mjs";
+import { blockOf, blockSlugsOf, describeAddressableFields, findBlocksField, findRichTextField, isIndexSegment, joinPath, splitPath, targetOf } from "./walk.mjs";
+import { resolveLexicalPointer } from "./lexical-pointer.mjs";
 //#region src/schema/pointer.ts
-const isIndexSegment = (segment) => segment === "-" || /^\d+$/.test(segment);
 const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isIndexSegment(segment) : part === segment);
 /**
 * Longest descriptor whose path is fully consumed by the leading segments.
@@ -9,10 +9,7 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isI
 	descriptor,
 	parts: splitPath(descriptor.path)
 })).filter(({ parts }) => parts.every((part, offset) => partMatches(part, segments[offset]))).sort((left, right) => right.consumed - left.consumed)[0];
-/**
-* Whether the segments stop part-way through some descriptor's path, which
-* means they address a subtree rather than a field.
-*/ const isSubtreePrefix = (descriptors, segments) => descriptors.some((descriptor) => {
+/** Stopping part-way through a descriptor's path means a subtree, not a field. */ const isSubtreePrefix = (descriptors, segments) => descriptors.some((descriptor) => {
 	const parts = splitPath(descriptor.path);
 	return parts.length > segments.length && segments.every((segment, offset) => {
 		const part = parts[offset];
@@ -20,15 +17,33 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isI
 	});
 });
 /**
-* Reads the value the given pointer segments address. Unlike a descriptor
-* path, the segments carry real indices, so intervening array fields are
-* descended through rather than skipped.
+* Unlike a descriptor path, the segments carry real indices, so intervening
+* array fields are descended through rather than skipped.
 */ const valueAtSegments = (data, segments) => segments.reduce((current, segment) => current === null || typeof current !== "object" ? void 0 : current[segment], data);
 /**
-* Resolves a JSON Pointer against the schema, using the stored document to
-* choose a branch at every blocks element.
-*
-* The document is required rather than optional: `/layout/sections/3/modules/1`
+* The stored row decides which block sits at an index, since a blocks field
+* admits many shapes at the same position. A row the document does not have
+* yet takes its slug from the value being added.
+*/ const stepIntoBlock = (at) => {
+	const { addedValue, config, descriptor, rows } = at;
+	const [index, ...remaining] = at.rest;
+	if (!isIndexSegment(index)) throw new Error(`"${descriptor.path}" is an array; "${index}" is not an index.`);
+	const field = findBlocksField(at.fields, splitPath(descriptor.path));
+	const existing = Array.isArray(rows) && index !== "-" ? rows[Number(index)] : void 0;
+	const slug = existing?.blockType ?? addedValue?.blockType;
+	if (!field || slug === void 0) throw new Error(`Cannot tell which block "${descriptor.path}/${index}" is. Supply a "blockType" on the value, one of: ${field ? blockSlugsOf(field).join(", ") : ""}`);
+	const block = blockOf(config, field, slug);
+	if (!block) throw new Error(`"${slug}" is not allowed at "${descriptor.path}". Allowed: ${blockSlugsOf(field).join(", ")}`);
+	return {
+		blockType: slug,
+		data: existing,
+		fields: block.flattenedFields,
+		rest: remaining
+	};
+};
+/**
+* The stored document chooses the branch at every blocks element, and is
+* required rather than optional: `/layout/sections/3/modules/1`
 * can only be resolved by reading `blockType` off `sections[3]`, since a blocks
 * field admits many shapes at the same index.
 */ const resolveDataPointer = (config, target) => {
@@ -36,6 +51,8 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isI
 	let data = target.doc;
 	let blockType;
 	let segments = splitPath(target.pointer);
+	let readOnly;
+	let inLexical;
 	while (segments.length > 0) {
 		const descriptors = describeAddressableFields(fields);
 		const match = longestMatch(descriptors, segments);
@@ -43,7 +60,7 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isI
 			if (isSubtreePrefix(descriptors, segments)) return {
 				...blockType === void 0 ? {} : { blockType },
 				fields,
-				prefix: segments
+				prefix: segments.map((segment) => isIndexSegment(segment) ? "*" : segment)
 			};
 			throw new Error(`"${joinPath(segments)}" is not a field here. Available: ${descriptors.map((descriptor) => descriptor.path).join(", ")}`);
 		}
@@ -52,28 +69,58 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isI
 			...blockType === void 0 ? {} : { blockType },
 			descriptor: match.descriptor,
 			fields,
-			prefix: []
+			prefix: [],
+			...inLexical === void 0 ? {} : { inLexical },
+			...readOnly === void 0 ? {} : { readOnly }
 		};
+		if (match.descriptor.type === "richText") {
+			const field = findRichTextField(fields, splitPath(match.descriptor.path));
+			if (!field) throw new Error(`"${match.descriptor.path}" could not be resolved.`);
+			const step = resolveLexicalPointer({
+				...target.addedValue === void 0 ? {} : { addedValue: target.addedValue },
+				config,
+				descriptor: match.descriptor,
+				field,
+				segments: rest,
+				state: valueAtSegments(data, segments.slice(0, match.consumed))
+			});
+			if (step.kind === "position") return {
+				...blockType === void 0 ? {} : { blockType },
+				descriptor: match.descriptor,
+				fields,
+				lexical: step.position,
+				prefix: [],
+				...readOnly === void 0 ? {} : { readOnly }
+			};
+			inLexical = true;
+			readOnly = match.descriptor.readOnly ?? readOnly;
+			blockType = step.blockType;
+			fields = step.fields;
+			data = step.data;
+			segments = step.rest;
+			continue;
+		}
 		if (match.descriptor.type !== "blocks") throw new Error(`"${match.descriptor.path}" is a ${match.descriptor.type} field and has no "${joinPath(rest)}" beneath it.`);
-		const [index, ...remaining] = rest;
-		if (!isIndexSegment(index)) throw new Error(`"${match.descriptor.path}" is an array; "${index}" is not an index.`);
-		const parts = splitPath(match.descriptor.path);
-		const field = findBlocksField(fields, parts);
-		const rows = valueAtSegments(data, segments.slice(0, match.consumed));
-		const existing = Array.isArray(rows) && index !== "-" ? rows[Number(index)] : void 0;
-		const slug = existing?.blockType ?? target.addedValue?.blockType;
-		if (!field || slug === void 0) throw new Error(`Cannot tell which block "${match.descriptor.path}/${index}" is. Supply a "blockType" on the value, one of: ${field ? blockSlugsOf(field).join(", ") : ""}`);
-		const block = blockOf(config, field, slug);
-		if (!block) throw new Error(`"${slug}" is not allowed at "${match.descriptor.path}". Allowed: ${blockSlugsOf(field).join(", ")}`);
-		blockType = slug;
-		fields = block.flattenedFields;
-		data = existing;
-		segments = remaining;
+		const step = stepIntoBlock({
+			addedValue: target.addedValue,
+			descriptor: match.descriptor,
+			fields,
+			rest,
+			rows: valueAtSegments(data, segments.slice(0, match.consumed)),
+			config
+		});
+		readOnly = match.descriptor.readOnly ?? readOnly;
+		blockType = step.blockType;
+		fields = step.fields;
+		data = step.data;
+		segments = step.rest;
 	}
 	return {
 		...blockType === void 0 ? {} : { blockType },
 		fields,
-		prefix: []
+		...inLexical === void 0 ? {} : { inLexical },
+		prefix: [],
+		...readOnly === void 0 ? {} : { readOnly }
 	};
 };
 //#endregion

package/dist/schema/shape.mjs

@@ -1,26 +1,27 @@
-import { lexicalSubSchema } from "./lexical.mjs";
-import { blockOf, blockSlugsOf, describeAddressableFields, findBlocksField, findRichTextField, splitPath } from "./walk.mjs";
+import { ROOT_PROPERTIES, constrainsFields, lexicalSubSchema, nodeProblems, propertyProblem, rootProblems } from "./lexical.mjs";
+import { blockOf, blockSlugsOf, describeAddressableFields, findBlocksField, findRichTextField, isPlainObject, splitPath } from "./walk.mjs";
 //#region src/schema/shape.ts
-/**
-* Keys Payload manages on a row that a client may echo back harmlessly.
-*/ const TOLERATED_VALUE_KEYS = /* @__PURE__ */ new Set([
+const TOLERATED_VALUE_KEYS = /* @__PURE__ */ new Set([
 	"blockName",
 	"blockType",
 	"id"
 ]);
-const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
-* Checks the fields a single Lexical node carries against the schema its
-* feature declares for that node type.
-*
-* A node with nothing to declare, and one whose sub-fields cannot be named at
-* a position, are both left alone.
+* Lexical refuses to hydrate a state whose root holds nothing: `isEmpty` is a
+* node map of one, and the editor throws on it rather than rendering nothing.
+* An empty field is stored as null instead, so this is only ever reached by
+* emptying one that was there.
+*/ const EMPTY_ROOT = "an editor state needs at least one node. Clear the field with null instead.";
+const quoted = (properties) => properties.map((property) => `"${property}"`).join(", ");
+/**
+* A node with nothing to declare, and one whose sub-fields cannot be named at a
+* position, are both left alone.
 */ const checkNodeFields = (scope, field, node) => {
 	const sub = lexicalSubSchema(field, node.type);
 	if (!sub) return;
 	const data = node.fields;
 	if (!isPlainObject(data)) {
-		scope.problems.push(`${scope.pointer}: a "${node.type}" node carries a "fields" object.`);
+		if (!constrainsFields(node.type)) scope.problems.push(`${scope.pointer}: a "${node.type}" node carries a "fields" object.`);
 		return;
 	}
 	const nested = {
@@ -47,48 +48,126 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 	}, data);
 };
 /**
-* Checks an editor state against what the field's editor can actually
-* produce: every node type, and the fields each node carries.
+* An absent property is already reported as missing. Anything else present is
+* checked, not just a string: Lexical stores a heading tag of 3 as readily as
+* one of "h3".
+*/ const checkNarrowedProperty = (scope, at, value) => {
+	if (value !== void 0 && !(typeof value === "string" && at.values.includes(value))) scope.problems.push(`${at.pointer}: ${JSON.stringify(value)} is not available for a "${at.type}" node in this field's editor. Allowed: ${at.values.join(", ")}`);
+};
+/**
+* One node, wherever it came from. `pointer` addresses the node itself, so a
+* node written at a position and a node written inside a whole editor state
+* are held to the same rules and report them the same way.
 *
-* Payload does not: the Lexical validator runs node validations only for the
-* few node types that register one, so a `heading` inside a field whose
-* editor has no heading feature is stored without complaint and only fails
-* later, at render or when the document is reopened in the admin editor. A key
-* a node's fields do not declare is dropped just as silently. The same holds
-* one level down, for the node properties a feature narrows: an `h3` in an
-* editor restricted to `h4` is stored as readily as an `h4`.
-*/ const checkRichText = (scope, editor, value) => {
+* Payload does not check any of this: the Lexical validator runs node
+* validations only for the few node types that register one, so a `heading`
+* inside a field whose editor has no heading feature is stored without
+* complaint and only fails later, at render or when the document is reopened
+* in the admin editor. A key a node's fields do not declare is dropped just as
+* silently. The same holds one level down, for the node properties a feature
+* narrows: an `h3` in an editor restricted to `h4` is stored as readily as an
+* `h4`, and a node written without the properties its class hydrates from is
+* stored and then throws when the editor opens it.
+*/ const checkNode = (scope, editor, node, pointer) => {
+	if (!isPlainObject(node) || typeof node["type"] !== "string") {
+		scope.problems.push(`${pointer}: every node needs a "type".`);
+		return;
+	}
+	const type = node["type"];
+	if (!editor.allowed.includes(type)) {
+		scope.problems.push(`${pointer}: "${type}" is not available in this field's editor. Allowed: ${editor.allowed.join(", ")}`);
+		return;
+	}
+	const problems = nodeProblems(node);
+	if (problems.missing.length > 0) scope.problems.push(`${pointer}: a "${type}" node is missing ${quoted(problems.missing)}. Write nodes as Lexical serializes them.`);
+	for (const problem of problems.rejected) scope.problems.push(`${pointer}/${problem.property}: a "${type}" node needs ${problem.needs} here.`);
+	for (const [property, values] of Object.entries(editor.nodeOptions?.[type] ?? {})) checkNarrowedProperty(scope, {
+		pointer: `${pointer}/${property}`,
+		type,
+		values
+	}, node[property]);
+	if (editor.field) checkNodeFields({
+		...scope,
+		pointer
+	}, editor.field, {
+		fields: node["fields"],
+		type
+	});
+	checkNodes(scope, editor, node["children"], `${pointer}/children`);
+};
+/** `pointer` addresses the list. A node holding none is left alone. */ const checkNodes = (scope, editor, nodes, pointer) => {
+	if (!Array.isArray(nodes)) return;
+	nodes.forEach((node, index) => {
+		checkNode(scope, editor, node, `${pointer}/${String(index)}`);
+	});
+};
+const checkRichText = (scope, editor, value) => {
 	if (!isPlainObject(value) || !isPlainObject(value["root"])) {
 		scope.problems.push(`${scope.pointer}: expected a Lexical editor state with a "root".`);
 		return;
 	}
-	const walk = (nodes, pointer) => {
-		if (!Array.isArray(nodes)) return;
-		nodes.forEach((node, index) => {
-			const at = `${pointer}/${String(index)}`;
-			if (!isPlainObject(node) || typeof node["type"] !== "string") {
-				scope.problems.push(`${at}: every node needs a "type".`);
-				return;
-			}
-			if (!editor.allowed.includes(node["type"])) {
-				scope.problems.push(`${at}: "${node["type"]}" is not available in this field's editor. Allowed: ${editor.allowed.join(", ")}`);
-				return;
-			}
-			for (const [property, values] of Object.entries(editor.nodeOptions?.[node["type"]] ?? {})) {
-				const value = node[property];
-				if (typeof value === "string" && !values.includes(value)) scope.problems.push(`${at}/${property}: "${value}" is not available for a "${node["type"]}" node in this field's editor. Allowed: ${values.join(", ")}`);
-			}
-			if (editor.field) checkNodeFields({
-				...scope,
-				pointer: at
-			}, editor.field, {
-				fields: node["fields"],
-				type: node["type"]
-			});
-			walk(node["children"], `${at}/children`);
-		});
+	const root = value["root"];
+	const { missing, rejected, unexpected } = rootProblems(root);
+	if (missing.length > 0) scope.problems.push(`${scope.pointer}/root: the root node is missing ${quoted(missing)}. Write nodes as Lexical serializes them.`);
+	for (const problem of rejected) scope.problems.push(`${scope.pointer}/root/${problem.property}: the root node needs ${problem.needs} here.`);
+	for (const property of unexpected) scope.problems.push(`${scope.pointer}/root/${property}: no such property on the root node. Available: ${Object.keys(ROOT_PROPERTIES).join(", ")}`);
+	if (Array.isArray(root["children"]) && root["children"].length === 0) scope.problems.push(`${scope.pointer}/root/children: ${EMPTY_ROOT}`);
+	checkNodes(scope, editor, root["children"], `${scope.pointer}/root/children`);
+};
+/**
+* `type` decides how every other property on a node is read, so replacing it
+* alone would leave a heading shaped like a text node. Everything else is held
+* to the constraint the node walk holds it to and nothing more, since a
+* feature may put any property on a node.
+*/ const checkNodeProperty = (scope, editor, position, value) => {
+	const { nodeType: type, property } = position;
+	if (property === "type") {
+		scope.problems.push(`${scope.pointer}: a node's "type" cannot be replaced on its own. Replace the whole node.`);
+		return;
+	}
+	if (position.isRoot && !(property in ROOT_PROPERTIES)) {
+		scope.problems.push(`${scope.pointer}: no such property on the root node. Available: ${Object.keys(ROOT_PROPERTIES).join(", ")}`);
+		return;
+	}
+	const problem = propertyProblem(type, property, value);
+	if (problem) scope.problems.push(`${scope.pointer}: a "${type}" node needs ${problem.needs} here.`);
+	const values = editor.nodeOptions?.[type]?.[property];
+	if (values) checkNarrowedProperty(scope, {
+		pointer: scope.pointer,
+		type,
+		values
+	}, value);
+};
+/**
+* A value written at a position inside an editor state rather than as the
+* whole state.
+*/ const checkLexicalWrite = (scope, position, value) => {
+	const editor = {
+		allowed: position.descriptor.nodes ?? [],
+		field: position.field,
+		nodeOptions: position.descriptor.nodeOptions
 	};
-	walk(value["root"]["children"], `${scope.pointer}/root/children`);
+	if (position.kind === "property") {
+		checkNodeProperty(scope, editor, position, value);
+		return;
+	}
+	if (position.kind === "nodes") {
+		if (!Array.isArray(value)) {
+			scope.problems.push(`${scope.pointer}: expected an array of nodes.`);
+			return;
+		}
+		if (position.isRoot && value.length === 0) {
+			scope.problems.push(`${scope.pointer}: ${EMPTY_ROOT}`);
+			return;
+		}
+		checkNodes(scope, editor, value, scope.pointer);
+		return;
+	}
+	if (position.isRoot) {
+		scope.problems.push(`${scope.pointer}: the root of an editor state cannot be replaced on its own. Write the whole field instead.`);
+		return;
+	}
+	checkNode(scope, editor, value, scope.pointer);
 };
 const checkLeafValue = (scope, descriptor, value) => {
 	if (descriptor.readOnly) {
@@ -126,8 +205,7 @@ const checkLeafValue = (scope, descriptor, value) => {
 	});
 };
 /**
-* Walks an incoming value against the schema, reporting every shape problem
-* rather than the first.
+* Reports every shape problem rather than the first.
 *
 * Shape only: unknown field names, unknown block slugs, read-only fields, and
 * rich text nodes or node properties the field's editor cannot produce.
@@ -197,6 +275,10 @@ const checkLeafValue = (scope, descriptor, value) => {
 		prefix: target.resolution.prefix,
 		problems
 	};
+	if (target.resolution.lexical) {
+		checkLexicalWrite(scope, target.resolution.lexical, value);
+		return problems;
+	}
 	if (target.resolution.descriptor) {
 		checkLeafValue(scope, target.resolution.descriptor, value);
 		return problems;
@@ -205,4 +287,4 @@ const checkLeafValue = (scope, descriptor, value) => {
 	return problems;
 };
 //#endregion
-export { validateWriteValue };
+export { EMPTY_ROOT, validateWriteValue };

package/dist/schema/walk.mjs

@@ -2,50 +2,39 @@ import { allowedNodeTypes, nodeOptions } from "./lexical.mjs";
 import { translateAny } from "../i18n.mjs";
 import { fieldIsHiddenOrDisabled, fieldIsVirtual } from "payload/shared";
 //#region src/schema/walk.ts
-/**
-* Fields Payload maintains, which a client may neither address nor supply.
-*/ const RESERVED_FIELD_NAMES = /* @__PURE__ */ new Set([
+const RESERVED_FIELD_NAMES = /* @__PURE__ */ new Set([
 	"_status",
 	"createdAt",
 	"deletedAt",
 	"id",
 	"updatedAt"
 ]);
+const JSON_POINTER_PATTERN = /^(\/([^~/]|~[01])*)*$/;
+/** No segments is the root pointer, `""`. */ const joinPath = (parts) => parts.map((part) => `/${part.replace(/~/g, "~0").replace(/\//g, "~1")}`).join("");
+/** Unescapes `~1` and `~0`. The root pointer yields no segments. */ const splitPath = (path) => path.split("/").slice(1).map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
+/** `-` included, since RFC 6901 reads it as the position after the last. */ const isIndexSegment = (segment) => segment === "-" || /^\d+$/.test(segment);
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
-* Shape a JSON Pointer must have to be parseable at all.
-*/ const JSON_POINTER_PATTERN = /^(\/([^~/]|~[01])*)*$/;
-/**
-* Joins segments into a JSON Pointer, so the segments `items`, `*`, `title`
-* read as one path to a subfield of every element of `items`. No segments is
-* the root pointer, `""`.
-*/ const joinPath = (parts) => parts.map((part) => `/${part.replace(/~/g, "~0").replace(/\//g, "~1")}`).join("");
-/**
-* Splits a JSON Pointer into its segments, unescaping `~1` and `~0`. The root
-* pointer yields no segments.
-*/ const splitPath = (path) => path.split("/").slice(1).map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
-/**
-* Restates a path Payload reports on a validation error (`layout.0.title`) as
-* a JSON Pointer, so everything this plugin hands back addresses documents the
-* same way. Payload's path already carries real indices, so it maps directly.
+* A path Payload reports on a validation error (`layout.0.title`) as a JSON
+* Pointer, so everything handed back addresses documents the same way. The
+* path already carries real indices, so it maps directly.
 */ const pointerFromPayloadPath = (path) => path ? joinPath(path.split(".")) : "";
+/** On a flattened field, whichever of `blockReferences` and `blocks` was declared. */ const blockSlugsOf = (field) => [...new Set((field.blockReferences ?? field.blocks).map((block) => typeof block === "string" ? block : block.slug))];
 /**
-* Blocks a blocks field accepts, by slug. On a flattened field, whichever of
-* `blockReferences` and `blocks` was declared carries the definitions.
-*/ const blockSlugsOf = (field) => [...new Set((field.blockReferences ?? field.blocks).map((block) => typeof block === "string" ? block : block.slug))];
-/**
-* Resolves one of a blocks field's slugs to its definition.
-*
-* A definition inlined on the field wins over the shared registry. A block's
-* own fields are identical wherever it appears, but the blocks its children
-* accept are not, so an inline definition has to be read at its position.
-* The registry (`config.blocks`) is the fallback for slugs referenced by name.
+* An inlined definition wins over the registry (`config.blocks`). A block's own
+* fields are identical wherever it appears, but the blocks its children accept
+* are not, so an inline definition has to be read at its position.
 */ const blockOf = (config, field, slug) => {
 	const declared = field.blockReferences ?? field.blocks;
 	const inline = declared.find((block) => typeof block !== "string" && block.slug === slug);
 	if (inline) return inline;
 	return declared.includes(slug) ? config.blocks?.find((block) => block.slug === slug) : void 0;
 };
-const isSkipped = (field) => !("name" in field) || field.type === "join" || RESERVED_FIELD_NAMES.has(field.name) || fieldIsVirtual(field) || fieldIsHiddenOrDisabled(field);
+/**
+* Payload's `fieldIsHiddenOrDisabled` reads `hidden` and `admin.disabled`, not
+* `admin.hidden`, which is what its own upload base fields carry.
+*/ const isAdminHidden = (field) => "admin" in field && field.admin.hidden === true;
+/** A field kept out of the admin panel is kept out of the MCP surface too. */ const isSkipped = (field) => !("name" in field) || field.type === "join" || RESERVED_FIELD_NAMES.has(field.name) || fieldIsVirtual(field) || isAdminHidden(field) || fieldIsHiddenOrDisabled(field);
 const isReadOnly = (field) => "admin" in field && field.admin.readOnly === true;
 const describeBase = (field, { path, readOnly, translate }) => {
 	const description = translate("admin" in field ? field.admin.description : void 0);
@@ -80,11 +69,9 @@ const withRows = (descriptor, field) => ({
 	...field.maxRows === void 0 ? {} : { maxRows: field.maxRows }
 });
 /**
-* Whether a descriptor stands for a construct that only holds other fields.
-*
-* These describe a position rather than a value, so everything that resolves a
-* path to something writable skips them; only {@link describeNode} reports
-* them, to carry what the container itself declares.
+* A container describes a position rather than a value, so everything resolving
+* a path to something writable skips it. Only {@link nodeDescriber} reports one,
+* to carry what the container itself declares.
 */ const isContainer = (descriptor) => descriptor.type === "array" || descriptor.type === "group" || descriptor.type === "tab";
 /**
 * Whether a container declares anything a client could not infer from the
@@ -93,20 +80,16 @@ const withRows = (descriptor, field) => ({
 /**
 * Flattens a field list into descriptors addressed relative to the node.
 *
-* The input is Payload's own flattened shape, which has already merged every
-* construct that exists only in the admin UI (unnamed tabs, unnamed groups,
-* `row`, `collapsible`) and dropped `ui` fields. Named tabs, groups and
-* arrays contribute a path segment, and are described in their own right when
-* they declare something of their own: an array always, since its row counts
-* live nowhere else, a group or tab only when it carries a description or a
-* constraint. The walk stops at every blocks field and names the slugs instead
-* of descending, which keeps a node proportional to the number of blocks it
-* allows rather than to the size of their definitions.
+* The input is Payload's own flattened shape, so the admin-only constructs
+* (unnamed tabs and groups, `row`, `collapsible`, `ui`) are already gone. Named
+* tabs, groups and arrays contribute a path segment, and are described in their
+* own right when they declare something of their own: an array always, since
+* its row counts live nowhere else, a group or tab only when it carries a
+* description or a constraint. The walk stops at every blocks field and names
+* the slugs, which keeps a node proportional to the number of blocks it allows
+* rather than to the size of their definitions.
 *
-* `translate` resolves each `admin.description` to the request's language.
-* Callers that walk for paths alone leave it out and get the language-agnostic
-* default, so a missing argument costs language selection, never the
-* description itself.
+* Omitting `translate` costs language selection, never the description itself.
 */ const describeFields = (fields, translate = translateAny) => {
 	const walk = (current, prefix, parentReadOnly) => current.flatMap((field) => {
 		if (isSkipped(field)) return [];
@@ -133,33 +116,30 @@ const withRows = (descriptor, field) => ({
 /**
 * The descriptors that address a value, which is what every walk resolving a
 * path against a document needs. A container describes a position rather than
-* a value, so only {@link describeNode} reports one.
+* a value, so only {@link nodeDescriber} reports one.
 */ const describeAddressableFields = (fields) => describeFields(fields).filter((descriptor) => !isContainer(descriptor));
-/**
-* Locates the blocks field that a resolved descriptor path refers to.
-*/ const findBlocksField = (fields, path) => {
+const findFieldAt = (fields, path, type) => {
 	for (const field of fields) {
 		if (!("name" in field) || field.name !== path[0]) continue;
-		if (field.type === "blocks" && path.length === 1) return field;
-		if (field.type === "tab" || field.type === "group") return findBlocksField(field.flattenedFields, path.slice(1));
-		if (field.type === "array" && path[1] === "*") return findBlocksField(field.flattenedFields, path.slice(2));
+		if (field.type === type && path.length === 1) return field;
+		if (field.type === "tab" || field.type === "group") return findFieldAt(field.flattenedFields, path.slice(1), type);
+		if (field.type === "array" && path[1] === "*") return findFieldAt(field.flattenedFields, path.slice(2), type);
 	}
 };
+const findBlocksField = (fields, path) => findFieldAt(fields, path, "blocks");
 /**
 * Locates the rich text field that a resolved descriptor path refers to, so
 * its editor can be introspected for the fields its nodes carry.
-*/ const findRichTextField = (fields, path) => {
-	for (const field of fields) {
-		if (!("name" in field) || field.name !== path[0]) continue;
-		if (field.type === "richText" && path.length === 1) return field;
-		if (field.type === "tab" || field.type === "group") return findRichTextField(field.flattenedFields, path.slice(1));
-		if (field.type === "array" && path[1] === "*") return findRichTextField(field.flattenedFields, path.slice(2));
-	}
-};
-const targetOf = (config, ref) => {
+*/ const findRichTextField = (fields, path) => findFieldAt(fields, path, "richText");
+/**
+* Looks up the sanitized config for a collection or global, as a
+* {@link SchemaTarget}. Throws on an unknown slug rather than returning
+* undefined, because a reference reaching here has already been checked against
+* the key's capabilities and a miss means the config changed underneath it.
+*/ const targetOf = (config, ref) => {
 	const found = ref.kind === "collection" ? config.collections.find((candidate) => candidate.slug === ref.slug) : config.globals.find((candidate) => candidate.slug === ref.slug);
 	if (!found) throw new Error(`Unknown ${ref.kind} "${ref.slug}".`);
 	return found;
 };
 //#endregion
-export { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, blockSlugsOf, describeAddressableFields, describeFields, findBlocksField, findRichTextField, joinPath, pointerFromPayloadPath, splitPath, targetOf };
+export { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, blockSlugsOf, describeAddressableFields, describeFields, findBlocksField, findRichTextField, isIndexSegment, isPlainObject, joinPath, pointerFromPayloadPath, splitPath, targetOf };