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

package/dist/endpoint/server.mjs

@@ -4,27 +4,13 @@ import { BUILTIN_TOOLS } from "../tools/builtin.mjs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 //#region src/endpoint/server.ts
+/** Strict, so an unknown argument is rejected by name rather than stripped. */ const toolInputSchema = (tool, scope) => z.strictObject(typeof tool.inputSchema === "function" ? tool.inputSchema(scope) : tool.inputSchema ?? {});
+/** May be built from the scope, to name the targets this key writes live. */ const toolDescription = (tool, scope) => typeof tool.description === "function" ? tool.description(scope) : tool.description;
+/** A tool that does not decide for itself is gated by its own checkbox. */ const isToolEnabled = (tool, scope) => tool.isEnabled ? tool.isEnabled(scope) : scope.capabilities.tools[tool.name] === true;
 /**
-* Builds a tool's input schema as a strict object, so an unknown argument is
-* rejected with its name instead of being silently stripped and the tool
-* answering as if it had not been passed. A tool may build its shape from the
-* scope to narrow enums to what the key may touch.
-*/ const toolInputSchema = (tool, scope) => z.strictObject(typeof tool.inputSchema === "function" ? tool.inputSchema(scope) : tool.inputSchema ?? {});
-/**
-* A tool's description, which may be built from the scope so it can name the
-* targets this key writes live.
-*/ const toolDescription = (tool, scope) => typeof tool.description === "function" ? tool.description(scope) : tool.description;
-/**
-* Whether the key may call the tool. A tool that does not decide for itself is
-* gated by its own checkbox on the key, which is how the tools from
-* `options.tools` work; the builtins derive it from the key's collection and
-* global capabilities instead.
-*/ const isToolEnabled = (tool, scope) => tool.isEnabled ? tool.isEnabled(scope) : scope.capabilities.tools[tool.name] === true;
-/**
-* Builds the MCP server for one request. Builtin and configured tools take the
-* same route: each is registered against the key's capabilities, so
-* `tools/list` shows exactly what the key may call and every `collection` enum
-* is limited to what it may touch.
+* One server per request. Builtin and configured tools take the same route,
+* each registered against the key's capabilities, so `tools/list` shows exactly
+* what the key may call.
 */ const createMcpServer = (scope, options) => {
 	const { req } = scope;
 	const { logger } = req.payload;

package/dist/i18n.mjs

@@ -1,11 +1,6 @@
 //#region src/i18n.ts
-/**
-* A locale-keyed record, once it is known to hold nothing but strings.
-*/ const stringRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && Object.values(value).every((entry) => typeof entry === "string") ? value : void 0;
-/**
-* Picks the entry a language addresses, treating an empty value as absent so
-* the chain continues rather than yielding a useless string.
-*/ const pick = (record, language) => {
+const stringRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && Object.values(value).every((entry) => typeof entry === "string") ? value : void 0;
+/** Treats an empty value as absent, so the fallback chain continues. */ const pick = (record, language) => {
 	for (const code of Array.isArray(language) ? language : [language]) {
 		const entry = record[code];
 		if (entry !== void 0 && entry.trim() !== "") return entry;
@@ -25,14 +20,8 @@
 	if (!record) return;
 	return pick(record, language.language) ?? pick(record, language.fallbackLanguage) ?? Object.values(record).find((entry) => entry.trim() !== "");
 };
-/**
-* Binds {@link translateStatic} to a request's language, so a walk that
-* resolves many descriptions carries no request of its own.
-*/ const translatorFor = (i18n) => (value) => translateStatic(value, i18n);
-/**
-* Translator for callers with no request in hand. Both language keys miss, so
-* the chain degrades to the record's first entry.
-*/ const translateAny = translatorFor({
+/** Bound to one request's language, so a walk carries no request of its own. */ const translatorFor = (i18n) => (value) => translateStatic(value, i18n);
+/** For callers with no request: both keys miss, so the first entry wins. */ const translateAny = translatorFor({
 	fallbackLanguage: "",
 	language: ""
 });

package/dist/options.mjs

@@ -11,23 +11,16 @@ 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.`);
 };
-/**
-* The write mode, checked at runtime as well as in the type. JS callers get no
-* type checking, and a typo reading as "no write" would be a silent downgrade.
-*/ const normalizeWriteMode = (kind, slug, value) => {
+/** 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".`);
@@ -43,15 +36,11 @@ const fail = (message) => {
 };
 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.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.`);
 };
 /**
@@ -77,6 +66,7 @@ const normalizeCollections = (config, options, apiKeysSlug) => {
 			read: settings.read ?? true,
 			write: normalizeWriteMode("Collection", slug, settings.write),
 			hasDrafts,
+			isUpload: Boolean(collection.upload),
 			fieldName: toCamelCase(slug)
 		};
 		if (normalized.write !== false) assertWritable(collection, normalized);
@@ -100,6 +90,7 @@ const normalizeGlobals = (config, options) => {
 			read: settings.read ?? true,
 			write: normalizeWriteMode("Global", slug, settings.write),
 			hasDrafts,
+			isUpload: false,
 			fieldName: toCamelCase(slug)
 		};
 		if (normalized.write !== false) assertGlobalWritable(global, normalized);
@@ -132,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.`);

package/dist/result.d.mts

@@ -1,12 +1,10 @@
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 //#region src/result.d.ts
-/**
- * A successful tool result carrying `value` as JSON text.
- */
+/** `value` as JSON text. */
 declare const jsonResult: (value: unknown) => CallToolResult;
 /**
- * A failed tool result. `extras` travel alongside the message so the client
- * can act on them (problems, validation errors, the current `updatedAt`).
+ * `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

package/dist/result.mjs

@@ -1,13 +1,11 @@
 //#region src/result.ts
-/**
-* A successful tool result carrying `value` as JSON text.
-*/ const jsonResult = (value) => ({ content: [{
+/** `value` as JSON text. */ const jsonResult = (value) => ({ content: [{
 	type: "text",
 	text: JSON.stringify(value)
 }] });
 /**
-* A failed tool result. `extras` travel alongside the message so the client
-* can act on them (problems, validation errors, the current `updatedAt`).
+* `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",

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

@@ -1,6 +1,6 @@
-import { allowedNodeTypes, lexicalSubSchema, nodeOptions, subSchemaNodeTypes } from "./lexical.mjs";
+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 { nodeDescriber, reachableSchemaPaths } from "./describe.mjs";
 import { resolveDataPointer } from "./pointer.mjs";
 import { validateWriteValue } from "./shape.mjs";
-export { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, allowedNodeTypes, blockOf, blockSlugsOf, describeAddressableFields, describeFields, findBlocksField, findRichTextField, joinPath, lexicalSubSchema, nodeDescriber, nodeOptions, pointerFromPayloadPath, reachableSchemaPaths, resolveDataPointer, splitPath, subSchemaNodeTypes, targetOf, validateWriteValue };
+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 };

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,160 @@ 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" };
 /**
-* 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);
+* 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 properties worth reporting and enforcing.
+* 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] ?? {});
+/** 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"]] ?? {}
+});
+/**
+* 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))
+});
+/**
 * 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 +247,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, rootProblems, subSchemaNodeTypes };

package/dist/schema/pointer.mjs

@@ -9,10 +9,7 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isI
 	descriptor,
 	parts: splitPath(descriptor.path)
 })).filter(({ parts }) => parts.every((part, offset) => partMatches(part, segments[offset]))).sort((left, right) => right.consumed - left.consumed)[0];
-/**
-* Whether the segments stop part-way through some descriptor's path, which
-* means they address a subtree rather than a field.
-*/ const isSubtreePrefix = (descriptors, segments) => descriptors.some((descriptor) => {
+/** Stopping part-way through a descriptor's path means a subtree, not a field. */ const isSubtreePrefix = (descriptors, segments) => descriptors.some((descriptor) => {
 	const parts = splitPath(descriptor.path);
 	return parts.length > segments.length && segments.every((segment, offset) => {
 		const part = parts[offset];
@@ -20,15 +17,12 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isI
 	});
 });
 /**
-* Reads the value the given pointer segments address. Unlike a descriptor
-* path, the segments carry real indices, so intervening array fields are
-* descended through rather than skipped.
+* Unlike a descriptor path, the segments carry real indices, so intervening
+* array fields are descended through rather than skipped.
 */ const valueAtSegments = (data, segments) => segments.reduce((current, segment) => current === null || typeof current !== "object" ? void 0 : current[segment], data);
 /**
-* Resolves a JSON Pointer against the schema, using the stored document to
-* choose a branch at every blocks element.
-*
-* The document is required rather than optional: `/layout/sections/3/modules/1`
+* The stored document chooses the branch at every blocks element, and is
+* required rather than optional: `/layout/sections/3/modules/1`
 * can only be resolved by reading `blockType` off `sections[3]`, since a blocks
 * field admits many shapes at the same index.
 */ const resolveDataPointer = (config, target) => {

package/dist/schema/shape.mjs

@@ -1,26 +1,22 @@
-import { lexicalSubSchema } from "./lexical.mjs";
+import { ROOT_PROPERTIES, constrainsFields, lexicalSubSchema, nodeProblems, rootProblems } 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.
-*/ const TOLERATED_VALUE_KEYS = /* @__PURE__ */ new Set([
+const TOLERATED_VALUE_KEYS = /* @__PURE__ */ new Set([
 	"blockName",
 	"blockType",
 	"id"
 ]);
 const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const quoted = (properties) => properties.map((property) => `"${property}"`).join(", ");
 /**
-* 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.
+* A node with nothing to declare, and one whose sub-fields cannot be named at a
+* position, are both left alone.
 */ const checkNodeFields = (scope, field, node) => {
 	const sub = lexicalSubSchema(field, node.type);
 	if (!sub) return;
 	const data = node.fields;
 	if (!isPlainObject(data)) {
-		scope.problems.push(`${scope.pointer}: a "${node.type}" node carries a "fields" object.`);
+		if (!constrainsFields(node.type)) scope.problems.push(`${scope.pointer}: a "${node.type}" node carries a "fields" object.`);
 		return;
 	}
 	const nested = {
@@ -47,21 +43,25 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 	}, data);
 };
 /**
-* Checks an editor state against what the field's editor can actually
-* produce: every node type, and the fields each node carries.
-*
-* Payload does not: the Lexical validator runs node validations only for the
+* 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`.
+* 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) => {
 	if (!isPlainObject(value) || !isPlainObject(value["root"])) {
 		scope.problems.push(`${scope.pointer}: expected a Lexical editor state with a "root".`);
 		return;
 	}
+	const root = value["root"];
+	const { missing, rejected, unexpected } = rootProblems(root);
+	if (missing.length > 0) scope.problems.push(`${scope.pointer}/root: the root node is missing ${quoted(missing)}. Write nodes as Lexical serializes them.`);
+	for (const problem of rejected) scope.problems.push(`${scope.pointer}/root/${problem.property}: the root node needs ${problem.needs} here.`);
+	for (const property of unexpected) scope.problems.push(`${scope.pointer}/root/${property}: no such property on the root node. Available: ${Object.keys(ROOT_PROPERTIES).join(", ")}`);
 	const walk = (nodes, pointer) => {
 		if (!Array.isArray(nodes)) return;
 		nodes.forEach((node, index) => {
@@ -74,9 +74,12 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 				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 (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 (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,
@@ -88,7 +91,7 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 			walk(node["children"], `${at}/children`);
 		});
 	};
-	walk(value["root"]["children"], `${scope.pointer}/root/children`);
+	walk(root["children"], `${scope.pointer}/root/children`);
 };
 const checkLeafValue = (scope, descriptor, value) => {
 	if (descriptor.readOnly) {
@@ -126,8 +129,7 @@ const checkLeafValue = (scope, descriptor, value) => {
 	});
 };
 /**
-* Walks an incoming value against the schema, reporting every shape problem
-* rather than the first.
+* Reports every shape problem rather than the first.
 *
 * Shape only: unknown field names, unknown block slugs, read-only fields, and
 * rich text nodes or node properties the field's editor cannot produce.