@abinnovision/payloadcms-mcpx 1.0.0-beta.5 → 1.0.0-beta.7

package/README.md

@@ -10,7 +10,7 @@ small and static: collection slugs, locales and operations as enums, everything
 else scalars. The field shapes are pulled on demand through `describeSchema`,
 one node at a time, stopping at every blocks boundary. And every write is
 resolved server-side against the real config and the real document, so unknown
-fields, misplaced blocks and unusable rich text nodes are refused with the
+fields, misplaced blocks and unusable rich text nodes or node fields are refused with the
 valid alternatives listed, never silently dropped.
 
 Writes are RFC 6902 patches that always land as drafts; publishing stays a
@@ -142,6 +142,25 @@ Rules the tools enforce and explain in their own descriptions:
   accept; every node carries `next`, the ready-to-use paths for those blocks
   (`/layout/sections/sectionWrapper`), so pass an entry of `next` as a `paths`
   element to descend. A block is described as it exists at that position.
+- Rich text paths continue the same way. A `richText` field lists the Lexical
+  node types it accepts in `nodes`, and `next` carries a path for every node
+  type that holds fields of its own: `/content/link` for a link node,
+  `/content/block/callout` and `/content/inlineBlock/badge` for the block
+  nodes. Descending returns the real field list, so a link extended through
+  `LinkFeature({ fields })` and a Lexical block are both described rather than
+  guessed. Any feature declaring `getSubFields` is picked up, custom ones
+  included. `upload` nodes are the exception: their fields depend on the
+  collection the node points at, so they are not addressable.
+- Constraints a field declares travel with it: `minRows`/`maxRows` on arrays
+  and blocks fields, `maxLength`/`minLength` on text, `min`/`max` on numbers.
+  An array is described in its own right, so the `*` in `/items/*/title` has
+  something to read; a group or named tab only when it declares a description
+  or a constraint of its own.
+- A `richText` field also reports `nodeOptions`, the node properties its editor
+  narrows. An editor built with `HeadingFeature({ enabledHeadingSizes: ["h4"] })`
+  answers `{ "heading": { "tag": ["h4"] } }`, and a write carrying any other
+  heading tag is refused. Lexical stores whatever tag it is given, so this is
+  the only place the restriction is checked.
 - Field and collection `admin.description` values are included in
   `describeSchema` and `listCapabilities`, so intent written for the admin
   panel reaches the client. Strings and locale-keyed records pass through;
@@ -302,9 +321,11 @@ key of every user.
 
 ## Non-goals of v1 / roadmap
 
-Deletes, uploads, markdown authoring for rich text, row addressing by id
-instead of index, cross-locale publish blockers, pagination of `describeSchema`
-with `expand`, and a handler-level timeout are all deliberate omissions for now.
+Deletes, uploads, markdown authoring for rich text, addressing a rich text node
+by position in a patch (an editor state is written whole), schemas for `upload`
+node fields, row addressing by id instead of index, cross-locale publish
+blockers, pagination of `describeSchema` with `expand`, and a handler-level
+timeout are all deliberate omissions for now.
 
 ## License
 

package/dist/schema/describe.mjs

@@ -1,32 +1,86 @@
-import { blockOf, blockSlugsOf, describeFields, findBlocksField, joinPath, splitPath, targetOf } from "./walk.mjs";
+import { lexicalSubSchema, subSchemaNodeTypes } from "./lexical.mjs";
+import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextField, joinPath, splitPath, targetOf } from "./walk.mjs";
 //#region src/schema/describe.ts
-const blocksDescriptors = (fields) => describeFields(fields).filter((descriptor) => descriptor.type === "blocks");
+/**
+* The longest descriptor path that is a prefix of `remaining`. Blocks and rich
+* text fields are both leaves of the walk, so at most one can match.
+*/ const longestMatch = (descriptors, remaining) => descriptors.map((descriptor) => splitPath(descriptor.path)).filter((parts) => parts.every((part, offset) => part === remaining[offset])).sort((left, right) => right.length - left.length)[0];
+/**
+* Walks one step of a schema path through a blocks field.
+*/ const stepThroughBlocks = ({ config, fields, match, remaining }) => {
+	const field = findBlocksField(fields, match);
+	if (!field) throw new Error(`"${joinPath(match)}" could not be resolved.`);
+	const slug = remaining.at(match.length);
+	if (slug === void 0) throw new Error(`"${joinPath(match)}" is a blocks field; append one of: ${blockSlugsOf(field).join(", ")}`);
+	const block = blockOf(config, field, slug);
+	if (!block) throw new Error(`"${slug}" is not allowed at "${joinPath(match)}". Allowed: ${blockSlugsOf(field).join(", ")}`);
+	return {
+		blockType: slug,
+		fields: block.flattenedFields,
+		rest: remaining.slice(match.length + 1)
+	};
+};
+/**
+* Walks one step of a schema path into a Lexical node's own fields.
+*
+* A node that picks a block by slug takes one segment more, so `/content/block`
+* addresses the choice and `/content/block/callout` the definition. Everything
+* else, a link node being the usual case, resolves in a single segment.
+*/ const stepThroughLexical = ({ config, fields, match, remaining }) => {
+	const field = findRichTextField(fields, match);
+	if (!field) throw new Error(`"${joinPath(match)}" could not be resolved.`);
+	const available = subSchemaNodeTypes(field).join(", ") || "none";
+	const nodeType = remaining.at(match.length);
+	if (nodeType === void 0) throw new Error(`"${joinPath(match)}" is a rich text field; append one of: ${available}`);
+	const sub = lexicalSubSchema(field, nodeType);
+	const reached = joinPath([...match, nodeType]);
+	if (!sub) throw new Error(`"${nodeType}" carries no fields in this field's editor. Node types with fields here: ${available}`);
+	if (sub.kind === "fields") return {
+		fields: sub.fields,
+		rest: remaining.slice(match.length + 1)
+	};
+	const slug = remaining.at(match.length + 1);
+	const slugs = blockSlugsOf(sub.blocksField).join(", ");
+	if (slug === void 0) throw new Error(`"${reached}" selects a block; append one of: ${slugs}`);
+	const block = blockOf(config, sub.blocksField, slug);
+	if (!block) throw new Error(`"${slug}" is not allowed at "${reached}". Allowed: ${slugs}`);
+	return {
+		blockType: slug,
+		fields: block.flattenedFields,
+		rest: remaining.slice(match.length + 2)
+	};
+};
 /**
 * Walks a schema path to the field list it addresses.
 *
 * A schema path alternates a blocks field's own path with the slug of one of
 * the blocks it accepts, so `/layout/sections/sectionWrapper/modules/hero`
 * reaches `hero` as it exists under `pages` specifically. The slug sits where
-* a pointer into a document would carry the element's index.
+* a pointer into a document would carry the element's index. A rich text
+* field's path continues the same way, naming a Lexical node type and, for the
+* block nodes, the slug it holds.
 */ const fieldsAtSchemaPath = (config, target, schemaPath) => {
 	let fields = target.flattenedFields;
 	let blockType;
 	let remaining = splitPath(schemaPath);
 	while (remaining.length > 0) {
+		const descendable = describeFields(fields).filter((descriptor) => descriptor.type === "blocks" || descriptor.type === "richText");
 		/**
-		* A blocks field's own path may span several segments
-		* (`/layout/sections`), so the longest matching one is taken.
-		*/ const match = blocksDescriptors(fields).map((descriptor) => splitPath(descriptor.path)).filter((parts) => parts.every((part, offset) => part === remaining[offset])).sort((left, right) => right.length - left.length)[0];
-		if (!match) throw new Error(`"${joinPath(remaining)}" does not address a blocks field. Blocks fields here: ${blocksDescriptors(fields).map((descriptor) => descriptor.path).join(", ") || "none"}`);
-		const slug = remaining.at(match.length);
-		const field = findBlocksField(fields, match);
-		if (!field) throw new Error(`"${joinPath(match)}" could not be resolved.`);
-		if (slug === void 0) throw new Error(`"${joinPath(match)}" is a blocks field; append one of: ${blockSlugsOf(field).join(", ")}`);
-		const block = blockOf(config, field, slug);
-		if (!block) throw new Error(`"${slug}" is not allowed at "${joinPath(match)}". Allowed: ${blockSlugsOf(field).join(", ")}`);
-		fields = block.flattenedFields;
-		blockType = slug;
-		remaining = remaining.slice(match.length + 1);
+		* A field's own path may span several segments (`/layout/sections`), so
+		* the longest matching one is taken. Blocks and rich text fields are both
+		* leaves of the walk, so no two of these paths overlap.
+		*/ const match = longestMatch(descendable, remaining);
+		if (!match) throw new Error(`"${joinPath(remaining)}" does not address a blocks or rich text field. Available here: ${descendable.map((descriptor) => descriptor.path).join(", ") || "none"}`);
+		const at = {
+			config,
+			fields,
+			match,
+			remaining
+		};
+		const step = findBlocksField(fields, match) === void 0 ? stepThroughLexical(at) : stepThroughBlocks(at);
+		blockType = step.blockType;
+		fields = step.fields;
+		remaining = step.rest;
 	}
 	return {
 		...blockType === void 0 ? {} : { blockType },
@@ -34,12 +88,37 @@ const blocksDescriptors = (fields) => describeFields(fields).filter((descriptor)
 	};
 };
 /**
-* Describes a collection or global root, or one block reached through a schema
-* path.
+* Where a descriptor can be drilled into: one branch per block a blocks field
+* accepts, and one per Lexical node type that carries fields.
+*/ const branchesOf = (fields, descriptor, schemaPath) => {
+	const base = `${schemaPath}${descriptor.path}`;
+	if (descriptor.type === "richText") {
+		const field = findRichTextField(fields, splitPath(descriptor.path));
+		if (!field) return [];
+		return subSchemaNodeTypes(field).flatMap((nodeType) => {
+			const sub = lexicalSubSchema(field, nodeType);
+			if (sub?.kind !== "blocks") return [{
+				path: `${base}/${nodeType}`,
+				token: `lexical:${nodeType}`
+			}];
+			return blockSlugsOf(sub.blocksField).map((slug) => ({
+				path: `${base}/${nodeType}/${slug}`,
+				token: `lexical:${nodeType}:${slug}`
+			}));
+		});
+	}
+	return (descriptor.blocks ?? []).map((slug) => ({
+		path: `${base}/${slug}`,
+		token: slug
+	}));
+};
+/**
+* Describes a collection or global root, one block reached through a schema
+* path, or the fields a Lexical node carries.
 */ const describeNode = (config, ref, schemaPath = "") => {
 	const { blockType, fields } = fieldsAtSchemaPath(config, targetOf(config, ref), schemaPath);
 	const descriptors = describeFields(fields);
-	const next = descriptors.flatMap((descriptor) => (descriptor.blocks ?? []).map((slug) => `${schemaPath}${descriptor.path}/${slug}`));
+	const next = descriptors.flatMap((descriptor) => branchesOf(fields, descriptor, schemaPath).map((branch) => branch.path));
 	return {
 		...blockType === void 0 ? {} : { blockType },
 		...ref.kind === "collection" ? { collection: ref.slug } : { global: ref.slug },
@@ -61,9 +140,10 @@ const blocksDescriptors = (fields) => describeFields(fields).filter((descriptor)
 			return;
 		}
 		seen.push(schemaPath);
-		for (const descriptor of describeNode(config, ref, schemaPath).fields) for (const slug of descriptor.blocks ?? []) {
-			if (visited.includes(slug)) continue;
-			walk(`${schemaPath}${descriptor.path}/${slug}`, [...visited, slug]);
+		const { fields } = fieldsAtSchemaPath(config, targetOf(config, ref), schemaPath);
+		for (const descriptor of describeFields(fields)) for (const branch of branchesOf(fields, descriptor, schemaPath)) {
+			if (visited.includes(branch.token)) continue;
+			walk(branch.path, [...visited, branch.token]);
 		}
 	};
 	walk("", []);

package/dist/schema/lexical.d.mts

@@ -0,0 +1 @@
+import "payload";

package/dist/schema/lexical.mjs

@@ -1,3 +1,4 @@
+import { flattenAllFields } from "payload";
 //#region src/schema/lexical.ts
 /**
 * Node types Lexical registers itself.
@@ -12,14 +13,105 @@
 	"tab"
 ];
 /**
+* Node types whose sub-fields exist but cannot be addressed by a schema path.
+*
+* Asked without a node, `upload` answers with every enabled collection's
+* upload fields concatenated, so the result describes no single position. It
+* would need addressing by `relationTo` to mean anything.
+*/ const OPAQUE_NODE_TYPES = /* @__PURE__ */ new Set(["upload"]);
+/**
+* Sub-schemas per rich text field, keyed by node type. `null` records a node
+* type that was asked and has nothing to describe, so it is asked only once.
+*
+* Worth caching because the describe and validate paths resolve the same field
+* repeatedly, and because the block features build their answer from scratch on
+* every call. Keyed weakly on the sanitized field, which lives as long as the
+* config does.
+*/ const subSchemaCache = /* @__PURE__ */ new WeakMap();
+const featuresOf = (field) => field.editor?.editorConfig?.features;
+/**
 * Node types a rich text field accepts. Editors other than Lexical report
 * only the core nodes.
 */ const allowedNodeTypes = (field) => {
-	const registered = (field.editor?.editorConfig?.features?.nodes ?? []).flatMap((entry) => {
+	const registered = (featuresOf(field)?.nodes ?? []).flatMap((entry) => {
 		const type = entry.node?.getType?.();
 		return type ? [type] : [];
 	});
 	return [.../* @__PURE__ */ new Set([...LEXICAL_CORE_NODES, ...registered])];
 };
+const resolveSubSchema = (field, nodeType) => {
+	if (OPAQUE_NODE_TYPES.has(nodeType)) return null;
+	const fields = featuresOf(field)?.getSubFields?.get(nodeType)?.({});
+	if (!fields?.length) return null;
+	const flattened = flattenAllFields({ fields });
+	const only = flattened.length === 1 ? flattened[0] : void 0;
+	return only?.type === "blocks" ? {
+		blocksField: only,
+		kind: "blocks"
+	} : {
+		fields: flattened,
+		kind: "fields"
+	};
+};
+/**
+* The sub-schema behind one node type of a rich text field, or `undefined`
+* when that node carries no addressable fields.
+*/ const lexicalSubSchema = (field, nodeType) => {
+	let cached = subSchemaCache.get(field);
+	if (!cached) {
+		cached = /* @__PURE__ */ new Map();
+		subSchemaCache.set(field, cached);
+	}
+	if (!cached.has(nodeType)) cached.set(nodeType, resolveSubSchema(field, nodeType));
+	return cached.get(nodeType) ?? void 0;
+};
+/**
+* Node types of a rich text field that have a sub-schema, in the order their
+* features registered them.
+*/ const subSchemaNodeTypes = (field) => [...featuresOf(field)?.getSubFields?.keys() ?? []].filter((nodeType) => lexicalSubSchema(field, nodeType) !== void 0);
+/**
+* Node properties worth reporting and enforcing.
+*
+* Only properties a feature narrows and Lexical does not check on its own
+* belong here. Everything else a feature restricts is already visible: a
+* link's targets through its sub-schema, a block node's choices through the
+* slugs it accepts.
+*/ const NODE_OPTION_SOURCES = [{
+	defaults: [
+		"h1",
+		"h2",
+		"h3",
+		"h4",
+		"h5",
+		"h6"
+	],
+	featureKey: "heading",
+	featureProp: "enabledHeadingSizes",
+	nodeProp: "tag",
+	nodeType: "heading"
+}];
+/**
+* The props a feature was resolved with.
+*
+* Sanitizing the editor drops every feature's props from `editorConfig.features`
+* but leaves them on `resolvedFeatureMap`. A feature that declares no server
+* props keeps only the client ones, so both are tried.
+*/ const featurePropsOf = (field, featureKey) => {
+	const resolved = field.editor?.editorConfig?.resolvedFeatureMap?.get(featureKey);
+	const props = resolved?.sanitizedServerFeatureProps ?? resolved?.clientFeatureProps;
+	return typeof props === "object" && props !== null ? props : void 0;
+};
+const stringList = (value) => Array.isArray(value) && value.every((entry) => typeof entry === "string") ? value : void 0;
+/**
+* The narrowed node properties of a rich text field, for the node types it
+* actually accepts.
+*/ const nodeOptions = (field, allowed) => {
+	const entries = NODE_OPTION_SOURCES.flatMap((source) => {
+		if (!allowed.includes(source.nodeType)) return [];
+		const values = stringList(featurePropsOf(field, source.featureKey)?.[source.featureProp]) ?? [...source.defaults];
+		return [[source.nodeType, { [source.nodeProp]: values }]];
+	});
+	return entries.length > 0 ? Object.fromEntries(entries) : void 0;
+};
 //#endregion
-export { allowedNodeTypes };
+export { allowedNodeTypes, lexicalSubSchema, nodeOptions, subSchemaNodeTypes };

package/dist/schema/pointer.mjs

@@ -1,4 +1,4 @@
-import { blockOf, blockSlugsOf, describeFields, findBlocksField, joinPath, splitPath, targetOf } from "./walk.mjs";
+import { blockOf, blockSlugsOf, describeAddressableFields, findBlocksField, joinPath, splitPath, targetOf } from "./walk.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);
@@ -37,7 +37,7 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isI
 	let blockType;
 	let segments = splitPath(target.pointer);
 	while (segments.length > 0) {
-		const descriptors = describeFields(fields);
+		const descriptors = describeAddressableFields(fields);
 		const match = longestMatch(descriptors, segments);
 		if (!match) {
 			if (isSubtreePrefix(descriptors, segments)) return {

package/dist/schema/shape.mjs

@@ -1,4 +1,5 @@
-import { blockOf, blockSlugsOf, describeFields, findBlocksField, splitPath } from "./walk.mjs";
+import { lexicalSubSchema } from "./lexical.mjs";
+import { blockOf, blockSlugsOf, describeAddressableFields, findBlocksField, findRichTextField, splitPath } from "./walk.mjs";
 //#region src/schema/shape.ts
 /**
 * Keys Payload manages on a row that a client may echo back harmlessly.
@@ -9,30 +10,85 @@ import { blockOf, blockSlugsOf, describeFields, findBlocksField, splitPath } fro
 ]);
 const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
-* Checks every node type in an editor state against what the field's editor
-* can actually produce.
+* 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.
+*/ 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.`);
+		return;
+	}
+	const nested = {
+		...scope,
+		pointer: `${scope.pointer}/fields`,
+		prefix: []
+	};
+	if (sub.kind === "fields") {
+		checkValue({
+			...nested,
+			fields: sub.fields
+		}, data);
+		return;
+	}
+	const slug = data["blockType"];
+	const block = typeof slug === "string" ? blockOf(scope.config, sub.blocksField, slug) : void 0;
+	if (!block) {
+		scope.problems.push(`${scope.pointer}/fields: "${String(slug)}" is not allowed here. Allowed: ${blockSlugsOf(sub.blocksField).join(", ")}`);
+		return;
+	}
+	checkValue({
+		...nested,
+		fields: block.flattenedFields
+	}, data);
+};
+/**
+* Checks an editor state against what the field's editor can actually
+* produce: every node type, and the fields each node carries.
 *
 * 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.
-*/ const checkRichText = (scope, allowed, value) => {
+* 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) => {
 	if (!isPlainObject(value) || !isPlainObject(value["root"])) {
 		scope.problems.push(`${scope.pointer}: expected a Lexical editor state with a "root".`);
 		return;
 	}
-	const walk = (nodes) => {
+	const walk = (nodes, pointer) => {
 		if (!Array.isArray(nodes)) return;
-		for (const node of nodes) {
+		nodes.forEach((node, index) => {
+			const at = `${pointer}/${String(index)}`;
 			if (!isPlainObject(node) || typeof node["type"] !== "string") {
-				scope.problems.push(`${scope.pointer}: every node needs a "type".`);
-				continue;
+				scope.problems.push(`${at}: every node needs a "type".`);
+				return;
 			}
-			if (!allowed.includes(node["type"])) scope.problems.push(`${scope.pointer}: "${node["type"]}" is not available in this field's editor. Allowed: ${allowed.join(", ")}`);
-			walk(node["children"]);
-		}
+			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`);
+		});
 	};
-	walk(value["root"]["children"]);
+	walk(value["root"]["children"], `${scope.pointer}/root/children`);
 };
 const checkLeafValue = (scope, descriptor, value) => {
 	if (descriptor.readOnly) {
@@ -40,7 +96,11 @@ const checkLeafValue = (scope, descriptor, value) => {
 		return;
 	}
 	if (descriptor.type === "richText") {
-		checkRichText(scope, descriptor.nodes ?? [], value);
+		checkRichText(scope, {
+			allowed: descriptor.nodes ?? [],
+			field: findRichTextField(scope.fields, splitPath(descriptor.path)),
+			nodeOptions: descriptor.nodeOptions
+		}, value);
 		return;
 	}
 	if (descriptor.type !== "blocks") return;
@@ -69,15 +129,16 @@ const checkLeafValue = (scope, descriptor, value) => {
 * Walks an incoming value against the schema, reporting every shape problem
 * rather than the first.
 *
-* Shape only: unknown field names, unknown block slugs, read-only fields and
-* unusable rich text nodes. Required-ness, row counts, enum membership and
-* relationship existence stay with Payload, which already checks them and
-* reports them per field. Without this pass a misspelled field inside a new
-* block would be stripped in silence.
+* Shape only: unknown field names, unknown block slugs, read-only fields, and
+* rich text nodes or node properties the field's editor cannot produce.
+* Required-ness, row counts, lengths, enum membership and relationship
+* existence stay with Payload, which already checks them and reports them per
+* field. Without this pass a misspelled field inside a new block would be
+* stripped in silence.
 */ const checkValue = (scope, value) => {
 	if (!isPlainObject(value)) return;
 	const prefixParts = scope.prefix;
-	const relative = describeFields(scope.fields).flatMap((descriptor) => {
+	const relative = describeAddressableFields(scope.fields).flatMap((descriptor) => {
 		const parts = splitPath(descriptor.path);
 		return prefixParts.every((part, offset) => part === parts[offset]) ? [{
 			descriptor,

package/dist/schema/walk.d.mts

@@ -1 +1,2 @@
+import "./lexical.mjs";
 import "payload";

package/dist/schema/walk.mjs

@@ -1,4 +1,4 @@
-import { allowedNodeTypes } from "./lexical.mjs";
+import { allowedNodeTypes, nodeOptions } from "./lexical.mjs";
 import { fieldIsHiddenOrDisabled, fieldIsVirtual } from "payload/shared";
 //#region src/schema/walk.ts
 /**
@@ -70,7 +70,15 @@ const describeLeaf = (field, path, readOnly) => {
 	if (field.type === "select" || field.type === "radio") descriptor.options = field.options.map((option) => typeof option === "string" ? option : option.value);
 	if (field.type === "relationship" || field.type === "upload") descriptor.relationTo = field.relationTo;
 	if ((field.type === "select" || field.type === "relationship" || field.type === "upload") && field.hasMany === true) descriptor.hasMany = true;
-	if (field.type === "richText") descriptor.nodes = allowedNodeTypes(field);
+	if ((field.type === "text" || field.type === "textarea") && field.maxLength !== void 0) descriptor.maxLength = field.maxLength;
+	if ((field.type === "text" || field.type === "textarea") && field.minLength !== void 0) descriptor.minLength = field.minLength;
+	if (field.type === "number" && field.max !== void 0) descriptor.max = field.max;
+	if (field.type === "number" && field.min !== void 0) descriptor.min = field.min;
+	if (field.type === "richText") {
+		descriptor.nodes = allowedNodeTypes(field);
+		const options = nodeOptions(field, descriptor.nodes);
+		if (options) descriptor.nodeOptions = options;
+	}
 	return descriptor;
 };
 const withRows = (descriptor, field) => ({
@@ -79,20 +87,37 @@ 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.
+*/ const isContainer = (descriptor) => descriptor.type === "array" || descriptor.type === "group" || descriptor.type === "tab";
+/**
+* Whether a container declares anything a client could not infer from the
+* fields beneath it. A group that exists only to nest is not worth reporting.
+*/ const isInformative = (descriptor) => descriptor.description !== void 0 || descriptor.required === true || descriptor.localized === true;
+/**
 * 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. 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.
+* 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.
 */ const describeFields = (fields, prefix = [], parentReadOnly = false) => fields.flatMap((field) => {
 	if (isSkipped(field)) return [];
 	const readOnly = parentReadOnly || isReadOnly(field);
 	const path = [...prefix, field.name];
-	if (field.type === "tab" || field.type === "group") return describeFields(field.flattenedFields, path, readOnly);
-	if (field.type === "array") return describeFields(field.flattenedFields, [...path, "*"], readOnly);
+	if (field.type === "tab" || field.type === "group") {
+		const own = describeBase(field, joinPath(path), readOnly);
+		return [...isInformative(own) ? [own] : [], ...describeFields(field.flattenedFields, path, readOnly)];
+	}
+	if (field.type === "array") return [withRows(describeBase(field, joinPath(path), readOnly), field), ...describeFields(field.flattenedFields, [...path, "*"], readOnly)];
 	if (field.type === "blocks") return [withRows({
 		...describeBase(field, joinPath(path), readOnly),
 		blocks: blockSlugsOf(field)
@@ -100,6 +125,11 @@ const withRows = (descriptor, field) => ({
 	return [describeLeaf(field, joinPath(path), readOnly)];
 });
 /**
+* 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.
+*/ const describeAddressableFields = (fields) => describeFields(fields).filter((descriptor) => !isContainer(descriptor));
+/**
 * Locates the blocks field that a resolved descriptor path refers to.
 */ const findBlocksField = (fields, path) => {
 	for (const field of fields) {
@@ -109,10 +139,21 @@ const withRows = (descriptor, field) => ({
 		if (field.type === "array" && path[1] === "*") return findBlocksField(field.flattenedFields, path.slice(2));
 	}
 };
+/**
+* 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 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, describeFields, findBlocksField, joinPath, pointerFromPayloadPath, splitPath, staticDescription, targetOf };
+export { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, blockSlugsOf, describeAddressableFields, describeFields, findBlocksField, findRichTextField, joinPath, pointerFromPayloadPath, splitPath, staticDescription, targetOf };

package/dist/tools/describe-schema.mjs

@@ -12,6 +12,8 @@ Pass exactly one of "collection" and "global". A global is a singleton: it has n
 
 Call it with no "paths" to get a collection's own fields. Every "blocks" field stops there and lists the block slugs it accepts instead of nesting them; each node's "next" lists the ready-to-use paths for those blocks, so pass any entry of "next" as a "paths" element to descend, e.g. "/layout/sections/sectionWrapper" and then "/layout/sections/sectionWrapper/modules/hero". A block is described as it exists at that position, because the same block can accept different children elsewhere.
 
+A "richText" field stops there too. It lists the Lexical node types it accepts in "nodes", and "next" carries a path for every node type that holds fields of its own: "/content/link" for a link node, "/content/block/callout" and "/content/inlineBlock/badge" for the block nodes. Descend to get the real field list instead of guessing what a node carries. Upload nodes are not addressable, because their fields depend on the collection the node points at.
+
 Paths here use the same JSON Pointer syntax as getDocument and patchDocument, and are already resolved through anything that does not nest in the stored document. The difference is only what stands in an element position: a path names an array element "*" and a block by its slug, where a pointer into a document carries a 0-based index. So "/items/*/title" is written at "/items/0/title", and "/layout/sections/hero" at "/layout/sections/0".
 
 Fields Payload maintains (id, _status, createdAt, updatedAt) are never listed and cannot be written. Fields marked readOnly are listed but refused on write.`,

package/dist/write/patch.mjs

@@ -1,4 +1,4 @@
-import { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, describeFields, findBlocksField, splitPath } from "../schema/walk.mjs";
+import { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, describeAddressableFields, findBlocksField, splitPath } from "../schema/walk.mjs";
 import { validateWriteValue } from "../schema/shape.mjs";
 import { resolveDataPointer } from "../schema/pointer.mjs";
 import { z } from "zod";
@@ -154,7 +154,7 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 * is left out, so the write-back carries only what a client could have set.
 */ const pickDescribed = (config, value, at) => {
 	const { fields, prefix, isRow } = at;
-	const relative = describeFields(fields).flatMap((descriptor) => {
+	const relative = describeAddressableFields(fields).flatMap((descriptor) => {
 		const parts = splitPath(descriptor.path);
 		return prefix.every((part, offset) => part === parts[offset]) ? [{
 			descriptor,

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@abinnovision/payloadcms-mcpx",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.7",
   "description": "Payload CMS plugin exposing a fixed, schema-aware MCP tool surface with draft-only writes and per-API-key capabilities.",
   "keywords": [
     "payload",