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

package/dist/options.mjs

@@ -1,7 +1,7 @@
 import { BUILTIN_TOOL_NAMES } from "./tools/names.mjs";
 import "./version.mjs";
 import { InvalidConfiguration } from "payload";
-import { hasDraftsEnabled } from "payload/shared";
+import { hasDraftsEnabled, hasLocalizeStatusEnabled } from "payload/shared";
 //#region src/options.ts
 const DEFAULT_API_KEYS_SLUG = "mcpx-api-keys";
 const DEFAULT_ENDPOINT_PATH = "/mcpx";
@@ -11,29 +11,36 @@ const TOOL_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9]*$/;
 const fail = (message) => {
 	throw new InvalidConfiguration(`[payloadcms-mcpx] ${message}`);
 };
+/** The same transform the stock MCP plugin uses to derive field names. */ const toCamelCase = (value) => value.replace(/[-_\s]+(.)?/g, (_, char) => char ? char.toUpperCase() : "").replace(/^(.)/, (_, char) => char.toLowerCase());
 /**
-* Lower camel case of a slug, the same transform the stock MCP plugin applies
-* to derive field names from collection slugs.
-*/ const toCamelCase = (value) => value.replace(/[-_\s]+(.)?/g, (_, char) => char ? char.toUpperCase() : "").replace(/^(.)/, (_, char) => char.toLowerCase());
-/**
-* Refuses collections that must never be reachable through MCP, read included.
 * Auth collections carry credentials: `useAPIKey` stores a key that decrypts on
-* read, and email or lockout state is PII either way.
+* read, and email or lockout state is PII either way. Refused for read too.
 */ const assertExposable = (collection, apiKeysSlug) => {
 	const { slug } = collection;
 	if (slug === apiKeysSlug || slug.startsWith("payload-")) fail(`Collection "${slug}" cannot be exposed.`);
 	if (collection.auth) fail(`Auth collection "${slug}" cannot be exposed. Its documents carry credentials.`);
 };
+/** Checked at runtime too: for a JS caller a typo would silently mean "no write". */ const normalizeWriteMode = (kind, slug, value) => {
+	if (value === void 0 || value === false) return false;
+	if (value === "draft" || value === "live") return value;
+	return fail(`${kind} "${slug}" has write: ${JSON.stringify(value)}. Use false, "draft" or "live".`);
+};
+/**
+* `localizeStatus` makes `_status` a localized field, which flips Payload's
+* `publishAllLocales` default to false and turns `_status` into a locale-keyed
+* object. Publishing would then cover one locale while reporting success, and
+* the tool responses model `_status` as a string. Refused until both are
+* handled.
+*/ const assertPublishable = (kind, config) => {
+	if (hasLocalizeStatusEnabled(config)) fail(`${kind} "${config.slug}" has versions.drafts.localizeStatus enabled, which write: "live" does not support yet.`);
+};
 const assertWritable = (collection, options) => {
 	const { slug } = collection;
-	if (collection.upload) fail(`Upload collection "${slug}" cannot be exposed for write.`);
 	if (collection.timestamps === false) fail(`Collection "${slug}" has timestamps disabled, which write tools need for concurrency checks.`);
-	if (!options.hasDrafts && !options.allowLiveWrites) fail(`Collection "${slug}" has no drafts. Enable versions.drafts or set allowLiveWrites.`);
+	if (options.write === "draft" && !options.hasDrafts) fail(`Collection "${slug}" has no drafts. Enable versions.drafts or set write: "live".`);
+	if (options.write === "live") assertPublishable("Collection", collection);
 };
-/**
-* Refuses globals that must never be reachable. Globals cannot be auth or
-* upload entities, so only Payload's own reserved namespace is left to guard.
-*/ const assertGlobalExposable = (global) => {
+/** Globals cannot be auth or upload, so only the reserved namespace is left. */ const assertGlobalExposable = (global) => {
 	if (global.slug.startsWith("payload-")) fail(`Global "${global.slug}" cannot be exposed.`);
 };
 /**
@@ -41,7 +48,8 @@ const assertWritable = (collection, options) => {
 * `createdAt`/`updatedAt`, so the concurrency check the collection path guards
 * for is always available here. Drafts are the only requirement left.
 */ const assertGlobalWritable = (global, options) => {
-	if (!options.hasDrafts && !options.allowLiveWrites) fail(`Global "${global.slug}" has no drafts. Enable versions.drafts or set allowLiveWrites.`);
+	if (options.write === "draft" && !options.hasDrafts) fail(`Global "${global.slug}" has no drafts. Enable versions.drafts or set write: "live".`);
+	if (options.write === "live") assertPublishable("Global", global);
 };
 const normalizeCollections = (config, options, apiKeysSlug) => {
 	const collections = config.collections ?? [];
@@ -56,12 +64,12 @@ const normalizeCollections = (config, options, apiKeysSlug) => {
 		const normalized = {
 			slug,
 			read: settings.read ?? true,
-			write: settings.write ?? false,
-			allowLiveWrites: settings.allowLiveWrites ?? false,
+			write: normalizeWriteMode("Collection", slug, settings.write),
 			hasDrafts,
+			isUpload: Boolean(collection.upload),
 			fieldName: toCamelCase(slug)
 		};
-		if (normalized.write) assertWritable(collection, normalized);
+		if (normalized.write !== false) assertWritable(collection, normalized);
 		if (fieldNames.has(normalized.fieldName)) fail(`Collection "${slug}" maps to capability field "${normalized.fieldName}", which another exposed collection already uses.`);
 		fieldNames.add(normalized.fieldName);
 		return [normalized];
@@ -80,12 +88,12 @@ const normalizeGlobals = (config, options) => {
 		const normalized = {
 			slug,
 			read: settings.read ?? true,
-			write: settings.write ?? false,
-			allowLiveWrites: settings.allowLiveWrites ?? false,
+			write: normalizeWriteMode("Global", slug, settings.write),
 			hasDrafts,
+			isUpload: false,
 			fieldName: toCamelCase(slug)
 		};
-		if (normalized.write) assertGlobalWritable(global, normalized);
+		if (normalized.write !== false) assertGlobalWritable(global, normalized);
 		if (fieldNames.has(normalized.fieldName)) fail(`Global "${slug}" maps to capability field "${normalized.fieldName}", which another exposed global already uses.`);
 		fieldNames.add(normalized.fieldName);
 		return [normalized];
@@ -115,11 +123,7 @@ const normalizeLimits = (limits) => {
 		maxDepth
 	};
 };
-/**
-* Validates the plugin options against the incoming config and fills in
-* defaults. Every problem is an `InvalidConfiguration` so misconfiguration
-* fails at startup instead of at request time.
-*/ const normalizeOptions = (config, options) => {
+/** Every problem is an `InvalidConfiguration`, so it fails at startup. */ const normalizeOptions = (config, options) => {
 	const apiKeysSlug = options.apiKeys?.slug ?? DEFAULT_API_KEYS_SLUG;
 	const userCollection = options.userCollection ?? config.admin?.user ?? "users";
 	if ((config.collections ?? []).some((c) => c.slug === apiKeysSlug)) fail(`API key collection slug "${apiKeysSlug}" is already taken.`);
@@ -132,12 +136,13 @@ const normalizeLimits = (limits) => {
 		userCollection,
 		apiKeysSlug,
 		endpointPath: options.endpoint?.path ?? DEFAULT_ENDPOINT_PATH,
+		setupGuide: options.apiKeys?.setupGuide ?? true,
 		limits: normalizeLimits(options.limits),
 		tools,
 		auth: options.auth,
 		serverInfo: {
 			name: options.serverInfo?.name ?? "payloadcms-mcpx",
-			version: options.serverInfo?.version ?? "0.0.0"
+			version: options.serverInfo?.version ?? "1.0.0"
 		}
 	};
 };

package/dist/plugin.mjs

@@ -1,5 +1,6 @@
 import { createApiKeysCollection } from "./api-keys/collection.mjs";
 import { createMcpxHandler, methodNotAllowed } from "./endpoint/handler.mjs";
+import "./endpoint/index.mjs";
 import { normalizeOptions } from "./options.mjs";
 import { installDraftGuards, installGlobalDraftGuards } from "./write/draft-guard.mjs";
 import { definePlugin } from "payload";

package/dist/{write/draft-guard.d.mts → request.d.mts}

@@ -1,5 +1,5 @@
-import { CollectionConfig, PayloadRequest } from "payload";
-//#region src/write/draft-guard.d.ts
+import { PayloadRequest } from "payload";
+//#region src/request.d.ts
 /**
  * Whether a request originated from the MCP endpoint. The endpoint stamps
  * `req.context.mcpx`, which travels into every local API call made with the

package/dist/request.mjs

@@ -0,0 +1,8 @@
+//#region src/request.ts
+/**
+* Whether a request originated from the MCP endpoint. The endpoint stamps
+* `req.context.mcpx`, which travels into every local API call made with the
+* same `req`, including those made by custom tools.
+*/ const isMcpxRequest = (req) => req.context.mcpx !== void 0;
+//#endregion
+export { isMcpxRequest };

package/dist/result.d.mts

@@ -0,0 +1,11 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+//#region src/result.d.ts
+/** `value` as JSON text. */
+declare const jsonResult: (value: unknown) => CallToolResult;
+/**
+ * `extras` travel alongside the message so the client can act on them:
+ * problems, validation errors, the current `updatedAt`.
+ */
+declare const errorResult: (message: string, extras?: Record<string, unknown>) => CallToolResult;
+//#endregion
+export { errorResult, jsonResult };

package/dist/result.mjs

@@ -0,0 +1,20 @@
+//#region src/result.ts
+/** `value` as JSON text. */ const jsonResult = (value) => ({ content: [{
+	type: "text",
+	text: JSON.stringify(value)
+}] });
+/**
+* `extras` travel alongside the message so the client can act on them:
+* problems, validation errors, the current `updatedAt`.
+*/ const errorResult = (message, extras = {}) => ({
+	content: [{
+		type: "text",
+		text: JSON.stringify({
+			error: message,
+			...extras
+		})
+	}],
+	isError: true
+});
+//#endregion
+export { errorResult, jsonResult };

package/dist/schema/describe.mjs

@@ -2,13 +2,8 @@ import { lexicalSubSchema, subSchemaNodeTypes } from "./lexical.mjs";
 import { translateAny } from "../i18n.mjs";
 import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextField, joinPath, splitPath, targetOf } from "./walk.mjs";
 //#region src/schema/describe.ts
-/**
-* 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 }) => {
+/** Blocks and rich text are both leaves of the walk, so at most one matches. */ 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];
+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);
@@ -22,8 +17,6 @@ import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextFie
 	};
 };
 /**
-* 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.
@@ -52,8 +45,6 @@ import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextFie
 	};
 };
 /**
-* 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
@@ -114,11 +105,8 @@ import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextFie
 	}));
 };
 /**
-* Describes a collection or global root, one block reached through a schema
-* path, or the fields a Lexical node carries.
-*
 * Curried on the translator that resolves each `admin.description`, so a
-* request binds its language once and the walk itself stays request-free.
+* request binds its language once and the walk stays request-free.
 */ const nodeDescriber = (translate = translateAny) => (config, ref, schemaPath = "") => {
 	const { blockType, fields } = fieldsAtSchemaPath(config, targetOf(config, ref), schemaPath);
 	const descriptors = describeFields(fields, translate);

package/dist/schema/index.mjs

@@ -0,0 +1,8 @@
+import { REQUIRED_NODE_PROPERTIES, ROOT_PROPERTIES, allowedNodeTypes, constrainsFields, lexicalSubSchema, nodeOptions, nodeProblems, nodePropertiesFor, 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 { 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, nodePropertiesFor, 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". getDocument with "outline" lists every position this field holds.`);
+	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. getDocument with "outline" reports the pointer of each node in it.`);
+			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. Call getDocument with "outline" for the pointer of each node, 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

@@ -1,8 +1,6 @@
 import { flattenAllFields } from "payload";
 //#region src/schema/lexical.ts
 /**
-* Node types Lexical registers itself.
-*
 * `editorConfig.features.nodes` lists only what a feature contributed, so a
 * field whose editor enables nothing but text formatting reports none at all.
 */ const LEXICAL_CORE_NODES = [
@@ -13,26 +11,17 @@ import { flattenAllFields } from "payload";
 	"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.
+* 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.
 */ 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.
+* `null` records a node type that was asked and has nothing to describe, so it
+* is asked only once. Worth caching because describe and validate resolve the
+* same field repeatedly and the block features rebuild their answer every call.
 */ 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) => {
+/** Editors other than Lexical report only the core nodes. */ const allowedNodeTypes = (field) => {
 	const registered = (featuresOf(field)?.nodes ?? []).flatMap((entry) => {
 		const type = entry.node?.getType?.();
 		return type ? [type] : [];
@@ -53,10 +42,7 @@ const resolveSubSchema = (field, nodeType) => {
 		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) => {
+const lexicalSubSchema = (field, nodeType) => {
 	let cached = subSchemaCache.get(field);
 	if (!cached) {
 		cached = /* @__PURE__ */ new Map();
@@ -65,13 +51,195 @@ const resolveSubSchema = (field, nodeType) => {
 	if (!cached.has(nodeType)) cached.set(nodeType, resolveSubSchema(field, nodeType));
 	return cached.get(nodeType) ?? void 0;
 };
+/** In the order their features registered them. */ const subSchemaNodeTypes = (field) => [...featuresOf(field)?.getSubFields?.keys() ?? []].filter((nodeType) => lexicalSubSchema(field, nodeType) !== void 0);
+/**
+* `direction` carries Payload's own declaration for it, `oneOf` the two
+* directions or null, rather than a looser "string or null".
+*/ const KINDS = {
+	array: {
+		accepts: (value) => Array.isArray(value),
+		needs: "an array"
+	},
+	direction: {
+		accepts: (value) => value === null || value === "ltr" || value === "rtl",
+		needs: "\"ltr\", \"rtl\" or null"
+	},
+	number: {
+		accepts: (value) => typeof value === "number",
+		needs: "a number"
+	},
+	object: {
+		accepts: (value) => typeof value === "object" && value !== null && !Array.isArray(value),
+		needs: "an object"
+	},
+	optionalObject: {
+		accepts: (value) => value === null || typeof value === "object" && !Array.isArray(value),
+		needs: "an object or null"
+	},
+	string: {
+		accepts: (value) => typeof value === "string",
+		needs: "a string"
+	}
+};
+const accepts = (constraint, value) => typeof constraint === "string" ? KINDS[constraint].accepts(value) : value === constraint.is;
+const needs = (constraint) => typeof constraint === "string" ? KINDS[constraint].needs : JSON.stringify(constraint.is);
+const ELEMENT_PROPERTIES = {
+	children: "array",
+	direction: "direction",
+	indent: "number"
+};
+/** A text node and everything built on one. */ const TEXT_PROPERTIES = {
+	detail: "number",
+	format: "number",
+	mode: "string",
+	style: "string",
+	text: "string"
+};
+/**
+* Carried by every node, whatever its type.
+*
+* Aligned with Payload rather than measured: its `outputSchema` declares `type`
+* and `version` required for every node in the tree, and that declaration is
+* what types the field in `payload-types.ts`. Lexical itself hydrates a node
+* without a `version`, or with the wrong kind of one, unchanged - but a
+* consumer reading the document through the generated types has been promised
+* an integer, and `BlockNode.importJSON` migrates on it.
+*/ const UNIVERSAL_PROPERTIES = { version: "number" };
+/**
+* The root, as Payload declares it and as an editor exports it: these six
+* properties, these kinds, and nothing else.
+*/ const ROOT_PROPERTIES = {
+	children: "array",
+	direction: "direction",
+	format: "string",
+	indent: "number",
+	type: "string",
+	version: "number"
+};
 /**
-* 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);
+* What a serialized node must carry beyond {@link UNIVERSAL_PROPERTIES}, keyed
+* by node type.
+*
+* Payload stores an editor state without hydrating it, so a node written
+* without these, or with the wrong kind of value, is accepted and only fails
+* later, in the admin editor. Payload declares nothing per node type, so this
+* table is measured instead: an entry belongs here only if breaking it makes
+* Lexical throw, or changes what the editor reads back. An element's `format`
+* and a paragraph's text defaults are absent for that reason.
+* `lexical.spec.ts` holds every entry to the rule against the node classes
+* `@payloadcms/richtext-lexical` ships, so extend that test first.
+*
+* A node type with no entry is checked for the universal properties only.
+* Guessing at the requirements of a project's own nodes would reject content
+* that works.
+*/ const REQUIRED_NODE_PROPERTIES = {
+	autolink: {
+		...ELEMENT_PROPERTIES,
+		fields: "object"
+	},
+	block: { fields: "object" },
+	heading: {
+		...ELEMENT_PROPERTIES,
+		tag: "string"
+	},
+	inlineBlock: { fields: "object" },
+	link: {
+		...ELEMENT_PROPERTIES,
+		fields: "object"
+	},
+	list: {
+		...ELEMENT_PROPERTIES,
+		listType: "string",
+		start: "number"
+	},
+	listitem: {
+		...ELEMENT_PROPERTIES,
+		value: "number"
+	},
+	paragraph: ELEMENT_PROPERTIES,
+	quote: ELEMENT_PROPERTIES,
+	relationship: {
+		relationTo: "string",
+		value: "number"
+	},
+	tab: {
+		...TEXT_PROPERTIES,
+		detail: { is: 2 },
+		text: { is: "	" }
+	},
+	text: TEXT_PROPERTIES,
+	upload: {
+		fields: "optionalObject",
+		relationTo: "string",
+		value: "number"
+	}
+};
+/**
+* Whether the table already says what a node type's `fields` has to be, so the
+* sub-field walk does not report the same problem a second time.
+*/ const constrainsFields = (type) => "fields" in (REQUIRED_NODE_PROPERTIES[type] ?? {});
+const describeConstraints = (constraints) => Object.fromEntries(Object.entries(constraints).map(([property, constraint]) => [property, needs(constraint)]).sort((left, right) => left[0].localeCompare(right[0])));
+/**
+* What each of the given node types has to carry, phrased the way the write
+* side phrases it when it refuses one, so the listing and the error message
+* never disagree. Read straight off the tables above, which is what keeps it
+* true: nothing here is stated a second time.
+*
+* Keyed by node type rather than reported per field, because that is what it
+* depends on. A field says which types it allows, in its `nodes`; what a `text`
+* node has to carry is the same wherever one is written, so a response that
+* describes twenty rich text fields still states it once.
+*
+* `type` is listed although {@link UNIVERSAL_PROPERTIES} omits it. The
+* validator never reports it missing, because a node's `type` is how it finds
+* the entry to check against, but a client assembling a node from this listing
+* still has to write one.
+*/ const nodePropertiesFor = (types) => Object.fromEntries([...new Set(types)].sort().map((type) => [type, describeConstraints(type === "root" ? ROOT_PROPERTIES : {
+	...REQUIRED_NODE_PROPERTIES[type],
+	...UNIVERSAL_PROPERTIES,
+	type: "string"
+})]));
+/** Present but `null` counts as present: `direction` is serialized that way. */ const check = (node, constraints) => {
+	const problems = {
+		missing: [],
+		rejected: []
+	};
+	for (const [property, constraint] of Object.entries(constraints)) if (!(property in node)) problems.missing.push(property);
+	else if (!accepts(constraint, node[property])) problems.rejected.push({
+		needs: needs(constraint),
+		property
+	});
+	problems.missing.sort();
+	problems.rejected.sort((left, right) => left.property.localeCompare(right.property));
+	return problems;
+};
+const nodeProblems = (node) => check(node, {
+	...UNIVERSAL_PROPERTIES,
+	...REQUIRED_NODE_PROPERTIES[node["type"]] ?? {}
+});
 /**
-* Node properties worth reporting and enforcing.
+* The root is the one node Payload describes itself, down to refusing an
+* unknown property, so it is checked against that description rather than
+* against the walk's table.
+*/ const rootProblems = (root) => ({
+	...check(root, ROOT_PROPERTIES),
+	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
@@ -114,4 +282,4 @@ const stringList = (value) => Array.isArray(value) && value.every((entry) => typ
 	return entries.length > 0 ? Object.fromEntries(entries) : void 0;
 };
 //#endregion
-export { allowedNodeTypes, lexicalSubSchema, nodeOptions, subSchemaNodeTypes };
+export { REQUIRED_NODE_PROPERTIES, ROOT_PROPERTIES, allowedNodeTypes, constrainsFields, lexicalSubSchema, nodeOptions, nodeProblems, nodePropertiesFor, propertyProblem, rootProblems, subSchemaNodeTypes };