@abinnovision/payloadcms-mcpx 1.0.0-beta.15 → 1.0.0-beta.16

package/README.md

@@ -228,6 +228,24 @@ Rules the tools enforce and explain in their own descriptions:
   when the document is opened, and a heading whose `tag` is `3` comes back
   untagged, none of which Payload notices on write. A write breaking either is
   refused, and the message names the property and what belongs there.
+- A rich text field's value is addressable, so a small edit does not have to
+  rewrite the whole state. `/content/root/children/2` is a node,
+  `/content/root/children/2/tag` one of its properties, and
+  `/content/root/children/2/fields/url` a field the node carries, resolved
+  through the same node schema `describeSchema` publishes. A node written at a
+  position is held to exactly what a node inside a whole state is held to. The
+  root and a node's `type` cannot be replaced on their own, and a node property
+  cannot be removed, because a node needs it.
+- Node positions shift the moment anything is added or removed, and a text or
+  paragraph node carries no id to fall back on. `getDocument` with `outline`
+  answers with one line per node, its pointer, its `version` and an excerpt, so
+  a position can be chosen and a complete node written without holding the
+  whole state. `expectedUpdatedAt` still guards the document, and a `test`
+  operation on a node's `type` guards the position.
+- A state whose root holds nothing is refused, however it is written. Lexical
+  reads such a state as empty and throws rather than rendering it, so neither a
+  whole-field write of one, nor emptying the node list, nor removing the last
+  node is allowed. An empty field is stored as null instead.
 - Where Payload states the shape itself, that statement is what is enforced: its
   `outputSchema` declares `version` required on every node, and gives the root
   exactly `children`, `direction`, `format`, `indent`, `type` and `version`, so
@@ -517,9 +535,8 @@ How the draft and publish guarantees are enforced, and where they stop, is in
 ## Non-goals of v1 / roadmap
 
 Unpublishing, `versions.drafts.localizeStatus`, deletes, creating upload
-documents and any file handling, 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,
+documents and any file handling, markdown authoring for rich text, 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.
 

package/dist/schema/index.mjs

@@ -1,6 +1,8 @@
-import { REQUIRED_NODE_PROPERTIES, ROOT_PROPERTIES, allowedNodeTypes, constrainsFields, lexicalSubSchema, nodeOptions, nodeProblems, rootProblems, subSchemaNodeTypes } from "./lexical.mjs";
-import { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, blockSlugsOf, describeAddressableFields, describeFields, findBlocksField, findRichTextField, joinPath, pointerFromPayloadPath, splitPath, targetOf } from "./walk.mjs";
+import { REQUIRED_NODE_PROPERTIES, ROOT_PROPERTIES, allowedNodeTypes, constrainsFields, lexicalSubSchema, nodeOptions, nodeProblems, propertyProblem, rootProblems, subSchemaNodeTypes } from "./lexical.mjs";
+import { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, blockSlugsOf, describeAddressableFields, describeFields, findBlocksField, findRichTextField, isIndexSegment, isPlainObject, joinPath, pointerFromPayloadPath, splitPath, targetOf } from "./walk.mjs";
 import { nodeDescriber, reachableSchemaPaths } from "./describe.mjs";
+import { resolveLexicalPointer } from "./lexical-pointer.mjs";
+import { lexicalOutline } from "./outline.mjs";
 import { resolveDataPointer } from "./pointer.mjs";
-import { validateWriteValue } from "./shape.mjs";
-export { JSON_POINTER_PATTERN, REQUIRED_NODE_PROPERTIES, RESERVED_FIELD_NAMES, ROOT_PROPERTIES, allowedNodeTypes, blockOf, blockSlugsOf, constrainsFields, describeAddressableFields, describeFields, findBlocksField, findRichTextField, joinPath, lexicalSubSchema, nodeDescriber, nodeOptions, nodeProblems, pointerFromPayloadPath, reachableSchemaPaths, resolveDataPointer, rootProblems, splitPath, subSchemaNodeTypes, targetOf, validateWriteValue };
+import { EMPTY_ROOT, validateWriteValue } from "./shape.mjs";
+export { EMPTY_ROOT, JSON_POINTER_PATTERN, REQUIRED_NODE_PROPERTIES, RESERVED_FIELD_NAMES, ROOT_PROPERTIES, allowedNodeTypes, blockOf, blockSlugsOf, constrainsFields, describeAddressableFields, describeFields, findBlocksField, findRichTextField, isIndexSegment, isPlainObject, joinPath, lexicalOutline, lexicalSubSchema, nodeDescriber, nodeOptions, nodeProblems, pointerFromPayloadPath, propertyProblem, reachableSchemaPaths, resolveDataPointer, resolveLexicalPointer, rootProblems, splitPath, subSchemaNodeTypes, targetOf, validateWriteValue };

package/dist/schema/lexical-pointer.mjs

@@ -0,0 +1,125 @@
+import { lexicalSubSchema, subSchemaNodeTypes } from "./lexical.mjs";
+import { blockOf, blockSlugsOf, isIndexSegment, isPlainObject, joinPath } from "./walk.mjs";
+//#region src/schema/lexical-pointer.ts
+/**
+* A node's `fields` is ordinary Payload field-land, reached either through the
+* schema a feature declares for the node or, where the node picks a block by
+* slug, through that block.
+*/ const stepIntoFields = (at) => {
+	const { addedValue, config, field, node, nodeType, rest } = at;
+	const sub = lexicalSubSchema(field, nodeType);
+	if (!sub) throw new Error(`"${nodeType}" nodes carry no addressable fields in this field's editor. Node types with fields here: ${subSchemaNodeTypes(field).join(", ")}`);
+	const data = node?.["fields"];
+	if (sub.kind === "fields") return {
+		data,
+		fields: sub.fields,
+		kind: "fields",
+		rest
+	};
+	const added = addedValue?.fields;
+	const slug = (isPlainObject(data) ? data["blockType"] : void 0) ?? (isPlainObject(added) ? added["blockType"] : void 0);
+	if (typeof slug !== "string") throw new Error(`Cannot tell which block a "${nodeType}" node holds. Supply a "blockType" on the value, one of: ${blockSlugsOf(sub.blocksField).join(", ")}`);
+	const block = blockOf(config, sub.blocksField, slug);
+	if (!block) throw new Error(`"${slug}" is not allowed in a "${nodeType}" node here. Allowed: ${blockSlugsOf(sub.blocksField).join(", ")}`);
+	return {
+		blockType: slug,
+		data,
+		fields: block.flattenedFields,
+		kind: "fields",
+		rest
+	};
+};
+/**
+* Walks the segments left over once a pointer has reached a rich text field.
+*
+* The stored state chooses the branch at every index, exactly as the stored
+* document chooses it at a blocks element: an editor state admits many node
+* shapes at the same position, and only what is there says which one it is.
+* A position the document does not have yet takes its type from the value
+* being added, and is addressable no further.
+*/ const resolveLexicalPointer = (at) => {
+	const { addedValue, config, descriptor, field, state } = at;
+	const base = {
+		descriptor,
+		field
+	};
+	if (!isPlainObject(state) || !isPlainObject(state["root"])) throw new Error(`"${descriptor.path}" holds no editor state yet. Write the whole field once, then address positions inside it.`);
+	const [entry, ...rest] = at.segments;
+	if (entry !== "root") throw new Error(`"${String(entry)}" is not a position in a rich text field. An editor state is entered at "root", e.g. "${descriptor.path}/root/children/0".`);
+	let node = state["root"];
+	let nodeType = "root";
+	let segments = rest;
+	let walked = ["root"];
+	for (;;) {
+		if (segments.length === 0) return {
+			kind: "position",
+			position: {
+				...base,
+				...nodeType === "root" ? { isRoot: true } : {},
+				kind: "node",
+				nodeType
+			}
+		};
+		const [segment, ...remaining] = segments;
+		if (segment === "children") {
+			if (remaining.length === 0) return {
+				kind: "position",
+				position: {
+					...base,
+					...nodeType === "root" ? { isRoot: true } : {},
+					kind: "nodes",
+					nodeType
+				}
+			};
+			const [index, ...beyond] = remaining;
+			if (!isIndexSegment(index)) throw new Error(`"${descriptor.path}${joinPath([...walked, "children"])}" is a list; "${index}" is not an index.`);
+			const children = node?.["children"];
+			const child = Array.isArray(children) && index !== "-" ? children[Number(index)] : void 0;
+			const type = isPlainObject(child) ? child["type"] : addedValue?.type;
+			if (typeof type !== "string") {
+				if (beyond.length === 0) return {
+					kind: "position",
+					position: {
+						...base,
+						kind: "node"
+					}
+				};
+				throw new Error(`Cannot tell which node "${descriptor.path}${joinPath([
+					...walked,
+					"children",
+					index
+				])}" is. Read the document first, or address an existing position.`);
+			}
+			node = isPlainObject(child) ? child : void 0;
+			nodeType = type;
+			segments = beyond;
+			walked = [
+				...walked,
+				"children",
+				index
+			];
+			continue;
+		}
+		if (segment === "fields") return stepIntoFields({
+			addedValue,
+			config,
+			field,
+			node,
+			nodeType,
+			rest: remaining
+		});
+		if (remaining.length > 0) throw new Error(`"${segment}" is a property of a "${nodeType}" node and nothing beneath it can be addressed.`);
+		return {
+			kind: "position",
+			position: {
+				...base,
+				...nodeType === "root" ? { isRoot: true } : {},
+				kind: "property",
+				nodeType,
+				property: segment
+			}
+		};
+	}
+};
+//#endregion
+export { resolveLexicalPointer };

package/dist/schema/lexical.mjs

@@ -205,6 +205,20 @@ const nodeProblems = (node) => check(node, {
 	unexpected: Object.keys(root).filter((property) => !(property in ROOT_PROPERTIES))
 });
 /**
+* What one serialized property has to be, for a write addressing a property
+* rather than a whole node.
+*
+* Absent where the table says nothing, which is the same tolerance the node
+* walk shows: a project's own node may carry any property, and guessing at one
+* would reject content that works.
+*/ const propertyProblem = (nodeType, property, value) => {
+	const constraint = (nodeType === "root" ? ROOT_PROPERTIES : {
+		...UNIVERSAL_PROPERTIES,
+		...REQUIRED_NODE_PROPERTIES[nodeType] ?? {}
+	})[property];
+	return constraint === void 0 || accepts(constraint, value) ? void 0 : { needs: needs(constraint) };
+};
+/**
 * 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
@@ -247,4 +261,4 @@ const stringList = (value) => Array.isArray(value) && value.every((entry) => typ
 	return entries.length > 0 ? Object.fromEntries(entries) : void 0;
 };
 //#endregion
-export { REQUIRED_NODE_PROPERTIES, ROOT_PROPERTIES, allowedNodeTypes, constrainsFields, lexicalSubSchema, nodeOptions, nodeProblems, rootProblems, subSchemaNodeTypes };
+export { REQUIRED_NODE_PROPERTIES, ROOT_PROPERTIES, allowedNodeTypes, constrainsFields, lexicalSubSchema, nodeOptions, nodeProblems, propertyProblem, rootProblems, subSchemaNodeTypes };

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.
@@ -21,6 +21,27 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isI
 * 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);
 /**
+* 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
@@ -30,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);
@@ -46,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,12 +1,17 @@
-import { ROOT_PROPERTIES, constrainsFields, lexicalSubSchema, nodeProblems, rootProblems } 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
 const TOLERATED_VALUE_KEYS = /* @__PURE__ */ new Set([
 	"blockName",
 	"blockType",
 	"id"
 ]);
-const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* 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
@@ -43,16 +48,60 @@ const quoted = (properties) => properties.map((property) => `"${property}"`).joi
 	}, data);
 };
 /**
-* Payload does not check 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 checkRichText = (scope, editor, value) => {
+* 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 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;
@@ -62,36 +111,63 @@ const quoted = (properties) => properties.map((property) => `"${property}"`).joi
 	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(", ")}`);
-	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;
-			}
-			const problems = nodeProblems(node);
-			if (problems.missing.length > 0) scope.problems.push(`${at}: a "${node["type"]}" node is missing ${quoted(problems.missing)}. Write nodes as Lexical serializes them.`);
-			for (const problem of problems.rejected) scope.problems.push(`${at}/${problem.property}: a "${node["type"]}" node needs ${problem.needs} here.`);
-			for (const [property, values] of Object.entries(editor.nodeOptions?.[node["type"]] ?? {})) {
-				const value = node[property];
-				if (value !== void 0 && !(typeof value === "string" && values.includes(value))) scope.problems.push(`${at}/${property}: ${JSON.stringify(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`);
-		});
+	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(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) {
@@ -199,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;
@@ -207,4 +287,4 @@ const checkLeafValue = (scope, descriptor, value) => {
 	return problems;
 };
 //#endregion
-export { validateWriteValue };
+export { EMPTY_ROOT, validateWriteValue };

package/dist/schema/walk.mjs

@@ -12,6 +12,8 @@ const RESERVED_FIELD_NAMES = /* @__PURE__ */ new Set([
 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);
 /**
 * 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
@@ -140,4 +142,4 @@ const findBlocksField = (fields, path) => findFieldAt(fields, path, "blocks");
 	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 };

package/dist/tools/describe-schema.mjs

@@ -22,7 +22,9 @@ Call it with no "paths" to get a collection's own fields. Every "blocks" field s
 
 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.
 
-Write each Lexical node the way Lexical serializes it, with every property its type carries rather than a trimmed subset, and with the value Lexical would have written there. Every node needs a "version"; the root takes exactly "children", "direction", "format", "indent", "type" and "version" and refuses anything else; each node type adds its own on top. The admin editor rehydrates nodes through their classes, so a list item whose "indent" is missing, null or a string is stored and then throws on open, and a heading whose "tag" is a number is stored untagged. A write naming a property means exactly that.
+Write each Lexical node the way Lexical serializes it, with every property its type carries rather than a trimmed subset, and with the value Lexical would have written there. Every node needs a "version"; the root takes exactly "children", "direction", "format", "indent", "type" and "version" and refuses anything else; each node type adds its own on top. The admin editor rehydrates nodes through their classes, so a list item whose "indent" is missing, null or a string is stored and then throws on open, and a heading whose "tag" is a number is stored untagged. A write naming a property means exactly that. A state whose root holds no children is refused however it is written, because Lexical reads it as empty and throws; clear a field with null instead.
+
+A rich text field's value is addressable too, so an edit does not have to rewrite the whole state: "/content/root/children/0" is the first top-level node, "/content/root/children/0/children/1" a node inside it, "/content/root/children/0/tag" one property of a node, and "/content/root/children/0/fields/url" a field of a node, described at the "next" path for that node type. Append a node with "/-". Read the document first: which node sits at an index is only knowable from what is stored.
 
 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".
 

package/dist/tools/get-document.mjs

@@ -1,11 +1,15 @@
 import { errorResult, jsonResult } from "../result.mjs";
-import { JSON_POINTER_PATTERN } from "../schema/walk.mjs";
+import { JSON_POINTER_PATTERN, findRichTextField, splitPath } from "../schema/walk.mjs";
+import { lexicalOutline } from "../schema/outline.mjs";
+import { resolveDataPointer } from "../schema/pointer.mjs";
 import "../schema/index.mjs";
 import { depthShape, idShape, localeOf, localeShape, targetShape } from "./shared.mjs";
-import { requireIdFor, resolveTarget } from "./target.mjs";
+import { refOf, requireIdFor, resolveTarget } from "./target.mjs";
 import { defineMcpxTool } from "../types.mjs";
 import { z } from "zod";
 import { Pointer } from "rfc6902";
+//#region src/tools/get-document.ts
+const OUTLINE_ERROR = "\"outline\" applies to a rich text field; give \"path\" for one.";
 /**
 * With `path` the handler returns the subtree plus the `id`, `_status` and
 * `updatedAt` a client needs to write back, so a caller reading one branch
@@ -14,7 +18,9 @@ import { Pointer } from "rfc6902";
 	name: "getDocument",
 	description: `Reads one document, or one subtree of it when "path" is given as a JSON pointer such as "/layout/sections/2". Returns the latest draft by default. Read before patching: the response carries "updatedAt" for expectedUpdatedAt and the indices pointers need.
 
-Pass exactly one of "collection" and "global". "id" is required with "collection" and must be omitted with "global", because a global is a singleton.`,
+Pass exactly one of "collection" and "global". "id" is required with "collection" and must be omitted with "global", because a global is a singleton.
+
+Set "outline" on a rich text "path" to get a compact positional listing of its nodes instead of the raw editor state.`,
 	annotations: {
 		readOnlyHint: true,
 		openWorldHint: false
@@ -32,7 +38,8 @@ Pass exactly one of "collection" and "global". "id" is required with "collection
 			required: false,
 			description: "Locale to read. Defaults to the default locale."
 		}),
-		draft: z.boolean().optional().describe("Return the latest draft. Default true.")
+		draft: z.boolean().optional().describe("Return the latest draft. Default true."),
+		outline: z.boolean().optional().describe("For a rich text field, return a compact positional outline instead of the editor state. Requires \"path\".")
 	}),
 	handler: async ({ args, scope }) => {
 		const target = resolveTarget(scope, args, "read");
@@ -53,20 +60,42 @@ Pass exactly one of "collection" and "global". "id" is required with "collection
 			...shared,
 			slug: target.slug
 		}));
-		if (args.path === void 0 || args.path === "") return jsonResult(doc);
+		if (args.path === void 0 || args.path === "") {
+			if (args.outline) return errorResult(OUTLINE_ERROR);
+			return jsonResult(doc);
+		}
 		let value;
 		try {
 			value = Pointer.fromJSON(args.path).get(doc);
 		} catch {
 			return errorResult(`"${args.path}" is not a valid JSON pointer.`);
 		}
-		return jsonResult({
+		const envelope = {
 			...target.kind === "collection" ? { id: doc["id"] } : { global: target.slug },
 			status: doc["_status"],
 			updatedAt: doc["updatedAt"],
-			path: args.path,
+			path: args.path
+		};
+		if (!args.outline) return jsonResult({
+			...envelope,
 			value
 		});
+		let resolution;
+		try {
+			resolution = resolveDataPointer(scope.req.payload.config, {
+				doc,
+				pointer: args.path,
+				ref: refOf(target)
+			});
+		} catch (error) {
+			return errorResult(error instanceof Error ? error.message : OUTLINE_ERROR);
+		}
+		const field = resolution.descriptor?.type === "richText" && !resolution.lexical ? findRichTextField(resolution.fields, splitPath(resolution.descriptor.path)) : void 0;
+		if (!field) return errorResult(OUTLINE_ERROR);
+		return jsonResult({
+			...envelope,
+			outline: lexicalOutline(value, args.path, field)
+		});
 	}
 });
 //#endregion

package/dist/tools/patch-document.mjs

@@ -18,6 +18,10 @@ Only the fields describeSchema lists can be addressed. A pointer that does not r
 
 Adding a block requires "blockType" on the value. Append with "/-" as the last segment. To clear a field use "replace" with null; an array or blocks field refuses null and is emptied with [] instead. "remove" is only for list elements, because a field left out of a write is kept rather than cleared. Read the document first to learn the indices, and pass its "updatedAt" as expectedUpdatedAt so an edit made since that read is refused rather than overwritten.
 
+Inside a rich text field a pointer keeps going: "/content/root/children/2" is a node, "/content/root/children/2/tag" one of its properties, and "/content/root/children/2/fields/url" a field it carries. A node written at a position must carry everything Lexical serializes, "version" included, exactly as one written inside a whole state must; getDocument with "outline" returns each node's pointer and version, which is the cheapest way to get both right. A node's "type" cannot be replaced on its own, and neither can the root.
+
+Node positions shift as soon as anything is added or removed, so read immediately before patching, order removals from the last index to the first, and use a "test" operation on "/content/root/children/2/type" to assert a position is what you think it is before writing to it.
+
 A successful write may come back with "publishBlockers": everything still wrong with the draft, such as required fields left empty. Those do not fail the write, because a draft is allowed to be incomplete, but the document cannot be published until the list is empty. "notApplied" lists pointers whose value Payload kept unchanged, which happens when field-level access denies the update. "publishBlockersUnavailable" means the check itself failed, so the empty list says nothing about whether the document is publishable.`;
 const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**

package/dist/write/patch.mjs

@@ -1,6 +1,6 @@
-import { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, describeAddressableFields, findBlocksField, joinPath, splitPath } from "../schema/walk.mjs";
+import { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, describeAddressableFields, findBlocksField, isIndexSegment, joinPath, splitPath } from "../schema/walk.mjs";
 import { resolveDataPointer } from "../schema/pointer.mjs";
-import { validateWriteValue } from "../schema/shape.mjs";
+import { EMPTY_ROOT, validateWriteValue } from "../schema/shape.mjs";
 import "../schema/index.mjs";
 import { z } from "zod";
 import { Pointer, applyPatch } from "rfc6902";
@@ -43,8 +43,7 @@ const droppedPointer = (operation) => {
 	return operation.op === "move" ? operation.from : void 0;
 };
 const isElementPointer = (pointer) => {
-	const last = pointer.split("/").pop() ?? "";
-	return last === "-" || /^\d+$/.test(last);
+	return isIndexSegment(pointer.split("/").pop() ?? "");
 };
 const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /** Its nodes manage their own ids, so it is never descended into. */ const isRichTextState = (value) => isPlainObject(value["root"]) && Array.isArray(value["root"]["children"]);
@@ -108,6 +107,7 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 	return "from" in operation ? Pointer.fromJSON(operation.from).get(doc) : void 0;
 };
 /** A pointer stopping short addresses a subtree; the fields beneath decide. */ const resolvesReadOnly = (resolution) => {
+	if (resolution.readOnly) return true;
 	if (resolution.descriptor) return resolution.descriptor.readOnly === true;
 	const below = describeAddressableFields(resolution.fields).filter((descriptor) => resolution.prefix.every((part, offset) => part === splitPath(descriptor.path)[offset]));
 	return below.length > 0 && below.every((descriptor) => descriptor.readOnly);
@@ -117,6 +117,43 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 	pointer: isElementPointer(target.pointer) ? joinPath(splitPath(target.pointer).slice(0, -1)) : target.pointer,
 	ref: target.ref
 }));
+/** Unresolvable pointers say nothing here; the caller reports them anyway. */ const resolutionAt = (config, target) => {
+	try {
+		return resolveDataPointer(config, {
+			doc: target.doc,
+			pointer: target.pointer,
+			ref: target.ref
+		});
+	} catch {
+		return;
+	}
+};
+/**
+* Removing a field does nothing, but removing part of an editor state does
+* something, and something worse: a node written without the properties its
+* class hydrates from throws when the admin editor opens it. Both are refused,
+* and only the reason differs.
+*/ const droppedFieldProblem = (config, target) => {
+	const resolution = resolutionAt(config, target);
+	const lexical = resolution?.lexical;
+	if (lexical?.kind === "property") return `"${target.pointer}" is a node property, not a list element. A "${lexical.nodeType}" node needs it, so replace it rather than removing it.`;
+	if (lexical ?? resolution?.inLexical) return `"${target.pointer}" sits inside an editor state, which is written whole, so removing it would take effect and leave a node the admin editor cannot open. Replace it instead, or remove the node that holds it.`;
+	return `"${target.pointer}" is a field, not a list element, and removing it would do nothing. The patched document is written whole, and Payload keeps any field absent from a write rather than clearing it. Use "replace" with null to clear a field, or with [] to empty a list.`;
+};
+/**
+* Dropping the only node under a root empties the state, which Lexical refuses
+* to hydrate. Checked here rather than on the written value, because a
+* `remove` carries none.
+*/ const emptiesTheRoot = (config, target) => {
+	const list = joinPath(splitPath(target.pointer).slice(0, -1));
+	const owner = resolutionAt(config, {
+		...target,
+		pointer: list
+	})?.lexical;
+	if (owner?.kind !== "nodes" || owner.isRoot !== true) return false;
+	const nodes = Pointer.fromJSON(list).get(target.doc);
+	return Array.isArray(nodes) && nodes.length === 1;
+};
 /**
 * Checked against the document as it stands when this operation runs: both
 * pointers must resolve, the written value must pass write validation, and what
@@ -128,7 +165,11 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 	const reserved = pointers.find(isReservedPointer);
 	if (reserved !== void 0) return [`"${reserved}" addresses a field Payload maintains. This tool only ever writes drafts, and id, _status, createdAt and updatedAt are not writable; use publishDocument to publish.`];
 	const dropped = droppedPointer(operation);
-	if (dropped !== void 0 && !isElementPointer(dropped)) return [`"${dropped}" is a field, not a list element, and removing it would do nothing. The patched document is written whole, and Payload keeps any field absent from a write rather than clearing it. Use "replace" with null to clear a field, or with [] to empty a list.`];
+	if (dropped !== void 0 && !isElementPointer(dropped)) return [droppedFieldProblem(config, {
+		doc,
+		pointer: dropped,
+		ref
+	})];
 	try {
 		const value = effectiveValue(operation, doc);
 		if (value !== void 0 && operation.op !== "test" && isReadOnlyPointer(config, {
@@ -141,6 +182,11 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 			pointer: dropped,
 			ref
 		})) return [`"${dropped}" sits in a read-only field and cannot be removed.`];
+		if (dropped !== void 0 && emptiesTheRoot(config, {
+			doc,
+			pointer: dropped,
+			ref
+		})) return [`"${dropped}": ${EMPTY_ROOT}`];
 		for (const pointer of pointers) {
 			const resolution = resolveDataPointer(config, {
 				addedValue: value,

package/package.json

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