@abinnovision/payloadcms-mcpx 1.0.0-beta.4 → 1.0.0-beta.6

package/README.md

@@ -10,7 +10,7 @@ small and static: collection slugs, locales and operations as enums, everything
 else scalars. The field shapes are pulled on demand through `describeSchema`,
 one node at a time, stopping at every blocks boundary. And every write is
 resolved server-side against the real config and the real document, so unknown
-fields, misplaced blocks and unusable rich text nodes are refused with the
+fields, misplaced blocks and unusable rich text nodes or node fields are refused with the
 valid alternatives listed, never silently dropped.
 
 Writes are RFC 6902 patches that always land as drafts; publishing stays a
@@ -44,6 +44,9 @@ export default buildConfig({
         posts: { read: true, write: true },
         tags: true, // shorthand for { read: true }
       },
+      globals: {
+        "site-settings": { read: true, write: true },
+      },
       limits: { maxLimit: 25, maxDepth: 1 },
     }),
   ],
@@ -56,8 +59,8 @@ The plugin adds:
   JSON responses; `GET`/`DELETE` answer 405),
 - an `mcpx-api-keys` collection (admin group "MCP") holding the keys and their
   capability checkboxes,
-- a draft guard on every collection, so any write carrying the MCP request
-  marker lands as a draft, including writes made by custom tools.
+- a draft guard on every collection and global, so any write carrying the MCP
+  request marker lands as a draft, including writes made by custom tools.
 
 ## API keys
 
@@ -118,19 +121,20 @@ Claude Desktop (no direct HTTP header support) via `mcp-remote`:
 
 ## Tools
 
-The surface is fixed at seven tools plus your custom ones. `tools/list`
-reflects the key: write tools disappear for read-only keys, and every
-`collection` enum contains only the slugs the key may touch.
+The surface is fixed at seven tools plus your custom ones; exposing a global
+adds an argument, never a tool. `tools/list` reflects the key: write tools
+disappear for read-only keys, and every `collection` and `global` enum contains
+only the slugs the key may touch.
 
 | Tool               | Purpose                                                     | Key arguments                                                                                |
 | ------------------ | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
 | `listCapabilities` | What this key may do; call first to orient.                 | none                                                                                         |
-| `describeSchema`   | Field shape of one node; `next` lists the drill-down paths. | `collection`, `paths?`, `expand?`                                                            |
+| `describeSchema`   | Field shape of one node; `next` lists the drill-down paths. | `collection` \| `global`, `paths?`, `expand?`                                                |
 | `findDocuments`    | Query documents.                                            | `collection`, `where?`, `sort?`, `limit?`, `page?`, `depth?`, `select?`, `locale?`, `draft?` |
-| `getDocument`      | Read one document or a subtree of it.                       | `collection`, `id`, `path?` (JSON pointer), `depth?`, `locale?`, `draft?`                    |
-| `patchDocument`    | Apply RFC 6902 operations to the current draft.             | `collection`, `id`, `locale`, `patches`, `expectedUpdatedAt?`                                |
+| `getDocument`      | Read one document or a subtree of it.                       | `collection` + `id` \| `global`, `path?` (JSON pointer), `depth?`, `locale?`, `draft?`       |
+| `patchDocument`    | Apply RFC 6902 operations to the current draft.             | `collection` + `id` \| `global`, `locale`, `patches`, `expectedUpdatedAt?`                   |
 | `createDocument`   | Create a draft from a minimal seed.                         | `collection`, `locale`, `data`                                                               |
-| `validateDocument` | Publish blockers without writing.                           | `collection`, `id`, `locale`                                                                 |
+| `validateDocument` | Publish blockers without writing.                           | `collection` + `id` \| `global`, `locale`                                                    |
 
 Rules the tools enforce and explain in their own descriptions:
 
@@ -138,6 +142,15 @@ Rules the tools enforce and explain in their own descriptions:
   accept; every node carries `next`, the ready-to-use paths for those blocks
   (`/layout/sections/sectionWrapper`), so pass an entry of `next` as a `paths`
   element to descend. A block is described as it exists at that position.
+- Rich text paths continue the same way. A `richText` field lists the Lexical
+  node types it accepts in `nodes`, and `next` carries a path for every node
+  type that holds fields of its own: `/content/link` for a link node,
+  `/content/block/callout` and `/content/inlineBlock/badge` for the block
+  nodes. Descending returns the real field list, so a link extended through
+  `LinkFeature({ fields })` and a Lexical block are both described rather than
+  guessed. Any feature declaring `getSubFields` is picked up, custom ones
+  included. `upload` nodes are the exception: their fields depend on the
+  collection the node points at, so they are not addressable.
 - Field and collection `admin.description` values are included in
   `describeSchema` and `listCapabilities`, so intent written for the admin
   panel reaches the client. Strings and locale-keyed records pass through;
@@ -161,13 +174,55 @@ Rules the tools enforce and explain in their own descriptions:
   `deletedAt`) are never listed and never writable; `readOnly` fields are
   listed but refused on write.
 
+## Globals
+
+A global is exposed the same way a collection is, and reached through the same
+tools rather than tools of its own:
+
+```ts
+mcpxPlugin({
+  collections: { pages: { read: true, write: true } },
+  globals: { "site-settings": { read: true, write: true } },
+});
+```
+
+Two rules follow from a global being a singleton, and because JSON Schema cannot
+state either one, both are enforced in the handler and repeated in every
+affected tool description:
+
+- Pass exactly **one** of `collection` and `global`.
+- `id` is required with `collection` and must be omitted with `global`.
+
+Refusals name the offending argument and the slug, so one failed call teaches
+the rule. `findDocuments` and `createDocument` stay collection-only: there is
+nothing to list and nothing to create when the document always exists. They
+reject a `global` argument by name.
+
+Globals get their own `capabilities.globals.<name>` checkbox group, a separate
+namespace from `capabilities.collections.<name>`, so a global may share a
+camelCase name with a collection. Keys issued before a global was exposed have
+no such group, and an absent checkbox reads as `false`, so they stay closed to
+every global until one is ticked.
+
+Globals always carry `updatedAt` — Payload appends it and there is no
+`timestamps: false` for globals — so `expectedUpdatedAt` behaves as it does for
+collections. The one exception is a global that has never been saved: it has no
+`updatedAt` to compare against, so the first write must omit
+`expectedUpdatedAt`, and supplying one is refused as a concurrency failure.
+
+If `tools/list` omits `global` entirely, no global is exposed to that key; the
+argument only appears once one is. A deployment that uses no globals sees the
+tool schemas exactly as they were.
+
 ## Drafts and publish blockers
 
 Draft-only writing is enforced on the Payload operation, not in the tool
 handlers: a `beforeOperation` hook forces `draft: true` and strips `_status`
 from every write carrying the MCP request marker, so custom tools and anything
 else writing through the same request are covered too. A `beforeChange` hook
-refuses any write that would still not land as a draft.
+refuses any write that would still not land as a draft. Globals expose the same
+`beforeOperation` interception point at the same position in the operation, so
+they are guarded exactly as strongly as collections, exposed or not.
 
 Publish blockers are advisory. Payload skips validation on draft saves (unless
 `versions.drafts.validate` is set), so after every write the plugin re-runs
@@ -224,6 +279,10 @@ Builtin tools reject them instead.
 | `collections.<slug>.read`            | `true`                         | Expose `describeSchema`, `findDocuments`, `getDocument`.                                                           |
 | `collections.<slug>.write`           | `false`                        | Expose `patchDocument`, `createDocument`, `validateDocument`. Requires `versions.drafts` unless `allowLiveWrites`. |
 | `collections.<slug>.allowLiveWrites` | `false`                        | Permit writes to a collection without drafts (they land live).                                                     |
+| `globals`                            | `{}`                           | Allow-list of globals. `true` means `{ read: true }`.                                                              |
+| `globals.<slug>.read`                | `true`                         | Expose `describeSchema`, `getDocument`.                                                                            |
+| `globals.<slug>.write`               | `false`                        | Expose `patchDocument`, `validateDocument`. Requires `versions.drafts` unless `allowLiveWrites`.                   |
+| `globals.<slug>.allowLiveWrites`     | `false`                        | Permit writes to a global without drafts (they land live).                                                         |
 | `userCollection`                     | `config.admin.user` or `users` | Auth collection the keys act as.                                                                                   |
 | `apiKeys.slug`                       | `mcpx-api-keys`                | Slug of the generated key collection.                                                                              |
 | `apiKeys.overrideCollection`         | none                           | Final override applied to the generated collection.                                                                |
@@ -247,15 +306,16 @@ key of every user.
 - The endpoint authenticates with Bearer keys only; admin JWTs and cookies are
   ignored. Keys cannot authenticate REST or GraphQL.
 - Every operation runs under the linked user with `overrideAccess: false`.
-- Not covered in v1: `delete` (no tool exists and none is generated), globals,
-  uploads. Custom tools are trusted code and can do what the linked user may.
+- Not covered in v1: `delete` (no tool exists and none is generated), uploads.
+  Custom tools are trusted code and can do what the linked user may.
 
 ## Non-goals of v1 / roadmap
 
-Globals, deletes, uploads, markdown authoring for rich text, row addressing by
-id instead of index, cross-locale publish blockers, pagination of
-`describeSchema` with `expand`, and a handler-level timeout are all deliberate
-omissions for now.
+Deletes, uploads, markdown authoring for rich text, addressing a rich text node
+by position in a patch (an editor state is written whole), schemas for `upload`
+node fields, row addressing by id instead of index, cross-locale publish
+blockers, pagination of `describeSchema` with `expand`, and a handler-level
+timeout are all deliberate omissions for now.
 
 ## License
 

package/dist/api-keys/fields.mjs

@@ -56,9 +56,10 @@ const checkbox = (name, description) => ({
 	}
 ];
 /**
-* One checkbox per exposed operation, grouped per collection and per custom
-* tool. Only operations the plugin config exposes get a checkbox, so a key can
-* never enable more than the config allows. Everything defaults to off.
+* One checkbox per exposed operation, grouped per collection, per global and
+* per custom tool. Only operations the plugin config exposes get a checkbox, so
+* a key can never enable more than the config allows. Everything defaults to
+* off, which is why a key issued before a capability existed stays closed to it.
 */ const createCapabilityFields = (options) => {
 	const collectionGroups = options.collections.map((collection) => ({
 		name: collection.fieldName,
@@ -66,16 +67,30 @@ const checkbox = (name, description) => ({
 		label: collection.slug,
 		fields: [...collection.read ? [checkbox("read", "Describe, find and read documents.")] : [], ...collection.write ? [checkbox("write", "Create, patch and validate drafts.")] : []]
 	}));
-	const toolCheckboxes = options.tools.map((tool) => checkbox(tool.name, tool.description));
-	const groups = [...collectionGroups.length > 0 ? [{
-		name: "collections",
-		type: "group",
-		fields: collectionGroups
-	}] : [], ...toolCheckboxes.length > 0 ? [{
-		name: "tools",
+	const globalGroups = options.globals.map((global) => ({
+		name: global.fieldName,
 		type: "group",
-		fields: toolCheckboxes
-	}] : []];
+		label: global.slug,
+		fields: [...global.read ? [checkbox("read", "Describe and read this global.")] : [], ...global.write ? [checkbox("write", "Patch and validate this global's draft.")] : []]
+	}));
+	const toolCheckboxes = options.tools.map((tool) => checkbox(tool.name, tool.description));
+	const groups = [
+		...collectionGroups.length > 0 ? [{
+			name: "collections",
+			type: "group",
+			fields: collectionGroups
+		}] : [],
+		...globalGroups.length > 0 ? [{
+			name: "globals",
+			type: "group",
+			fields: globalGroups
+		}] : [],
+		...toolCheckboxes.length > 0 ? [{
+			name: "tools",
+			type: "group",
+			fields: toolCheckboxes
+		}] : []
+	];
 	if (groups.length === 0) return [];
 	return [{
 		name: CAPABILITIES_FIELD,

package/dist/capabilities.mjs

@@ -8,6 +8,7 @@ const flag = (group, name) => isRecord(group) && group[name] === true;
 * issued before a capability existed stay closed.
 */ const resolveCapabilities = (options, keyCapabilities) => {
 	const collectionsGroup = isRecord(keyCapabilities) ? keyCapabilities["collections"] : void 0;
+	const globalsGroup = isRecord(keyCapabilities) ? keyCapabilities["globals"] : void 0;
 	const toolsGroup = isRecord(keyCapabilities) ? keyCapabilities["tools"] : void 0;
 	const collections = {};
 	for (const collection of options.collections) {
@@ -17,14 +18,26 @@ const flag = (group, name) => isRecord(group) && group[name] === true;
 			write: collection.write && flag(group, "write")
 		};
 	}
+	const globals = {};
+	for (const global of options.globals) {
+		const group = isRecord(globalsGroup) ? globalsGroup[global.fieldName] : void 0;
+		globals[global.slug] = {
+			read: global.read && flag(group, "read"),
+			write: global.write && flag(group, "write")
+		};
+	}
 	const tools = {};
 	for (const tool of options.tools) tools[tool.name] = flag(toolsGroup, tool.name);
 	return {
 		collections,
+		globals,
 		tools
 	};
 };
-const readableSlugs = (capabilities) => Object.entries(capabilities.collections).filter(([, value]) => value.read).map(([slug]) => slug);
-const writableSlugs = (capabilities) => Object.entries(capabilities.collections).filter(([, value]) => value.write).map(([slug]) => slug);
+const pick = (entries, operation) => Object.entries(entries).filter(([, value]) => value[operation]).map(([slug]) => slug);
+const readableSlugs = (capabilities) => pick(capabilities.collections, "read");
+const writableSlugs = (capabilities) => pick(capabilities.collections, "write");
+const readableGlobalSlugs = (capabilities) => pick(capabilities.globals, "read");
+const writableGlobalSlugs = (capabilities) => pick(capabilities.globals, "write");
 //#endregion
-export { CAPABILITIES_FIELD, readableSlugs, resolveCapabilities, writableSlugs };
+export { CAPABILITIES_FIELD, readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs };

package/dist/endpoint/handler.mjs

@@ -1,4 +1,4 @@
-import { readableSlugs, resolveCapabilities, writableSlugs } from "../capabilities.mjs";
+import { readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs } from "../capabilities.mjs";
 import { resolveApiKeyAuth } from "../auth/resolve.mjs";
 import { jsonRpcError } from "./result.mjs";
 import { createMcpServer } from "./server.mjs";
@@ -12,6 +12,8 @@ const buildScope = (req, options, capabilities) => {
 		capabilities,
 		readable: readableSlugs(capabilities),
 		writable: writableSlugs(capabilities),
+		readableGlobals: readableGlobalSlugs(capabilities),
+		writableGlobals: writableGlobalSlugs(capabilities),
 		locales: localization ? localization.localeCodes : null,
 		defaultLocale: localization ? localization.defaultLocale : null
 	};

package/dist/endpoint/server.mjs

@@ -18,7 +18,7 @@ import { z } from "zod";
 	const server = new McpServer({
 		name: options.serverInfo.name,
 		version: options.serverInfo.version
-	}, { instructions: "Start with listCapabilities, then describeSchema for the collection you work on. Writes always land as drafts; a human publishes." });
+	}, { instructions: "Start with listCapabilities, then describeSchema for the collection or global you work on. Writes always land as drafts; a human publishes." });
 	const guarded = (run) => async () => {
 		try {
 			return await run();

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, defineMcpxTool } from "./types.mjs";
+import { McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, defineMcpxTool } from "./types.mjs";
 import { mcpxPlugin } from "./plugin.mjs";
 import { isMcpxRequest } from "./write/draft-guard.mjs";
 import { PublishBlocker } from "./write/publish-blockers.mjs";
-export { type McpxAuthResult, type McpxCollectionCapabilities, type McpxCollectionOptions, type McpxPluginOptions, type McpxRequestContext, type McpxResolvedCapabilities, type McpxTool, type McpxToolExtra, type PublishBlocker, defineMcpxTool, isMcpxRequest, mcpxPlugin };
+export { type McpxAuthResult, type McpxCollectionCapabilities, type McpxCollectionOptions, type McpxGlobalOptions, type McpxPluginOptions, type McpxRequestContext, type McpxResolvedCapabilities, type McpxTool, type McpxToolExtra, type PublishBlocker, defineMcpxTool, isMcpxRequest, mcpxPlugin };

package/dist/options.d.mts

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

package/dist/options.mjs

@@ -30,6 +30,19 @@ const assertWritable = (collection, options) => {
 	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.`);
 };
+/**
+* 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) => {
+	if (global.slug.startsWith("payload-")) fail(`Global "${global.slug}" cannot be exposed.`);
+};
+/**
+* `GlobalConfig` has no `timestamps` option and `sanitizeGlobal` always appends
+* `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.`);
+};
 const normalizeCollections = (config, options, apiKeysSlug) => {
 	const collections = config.collections ?? [];
 	const fieldNames = /* @__PURE__ */ new Set();
@@ -54,6 +67,30 @@ const normalizeCollections = (config, options, apiKeysSlug) => {
 		return [normalized];
 	});
 };
+const normalizeGlobals = (config, options) => {
+	const globals = config.globals ?? [];
+	const fieldNames = /* @__PURE__ */ new Set();
+	return Object.entries(options.globals ?? {}).flatMap(([slug, raw]) => {
+		if (raw === void 0) return [];
+		const global = globals.find((candidate) => candidate.slug === slug);
+		if (!global) return fail(`Exposed global "${slug}" does not exist.`);
+		assertGlobalExposable(global);
+		const settings = raw === true ? {} : raw;
+		const hasDrafts = hasDraftsEnabled(global);
+		const normalized = {
+			slug,
+			read: settings.read ?? true,
+			write: settings.write ?? false,
+			allowLiveWrites: settings.allowLiveWrites ?? false,
+			hasDrafts,
+			fieldName: toCamelCase(slug)
+		};
+		if (normalized.write) 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];
+	});
+};
 const assertUserCollection = (config, slug) => {
 	const collection = (config.collections ?? []).find((candidate) => candidate.slug === slug);
 	if (!collection) fail(`User collection "${slug}" does not exist.`);
@@ -91,6 +128,7 @@ const normalizeLimits = (limits) => {
 	assertTools(tools);
 	return {
 		collections: normalizeCollections(config, options, apiKeysSlug),
+		globals: normalizeGlobals(config, options),
 		userCollection,
 		apiKeysSlug,
 		endpointPath: options.endpoint?.path ?? DEFAULT_ENDPOINT_PATH,

package/dist/plugin.d.mts

@@ -2,7 +2,7 @@ import { McpxPluginOptions } from "./types.mjs";
 //#region src/plugin.d.ts
 /**
  * Mounts the MCP endpoint, adds the API key collection and installs the
- * draft guard on every collection.
+ * draft guard on every collection and global.
  */
 declare const mcpxPlugin: (options: McpxPluginOptions) => import("payload").Plugin;
 //#endregion

package/dist/plugin.mjs

@@ -1,12 +1,12 @@
 import { createApiKeysCollection } from "./api-keys/collection.mjs";
 import { createMcpxHandler, methodNotAllowed } from "./endpoint/handler.mjs";
 import { normalizeOptions } from "./options.mjs";
-import { installDraftGuards } from "./write/draft-guard.mjs";
+import { installDraftGuards, installGlobalDraftGuards } from "./write/draft-guard.mjs";
 import { definePlugin } from "payload";
 //#region src/plugin.ts
 /**
 * Mounts the MCP endpoint, adds the API key collection and installs the
-* draft guard on every collection.
+* draft guard on every collection and global.
 */ const mcpxPlugin = definePlugin({
 	slug: "@abinnovision/payloadcms-mcpx",
 	order: 100,
@@ -17,6 +17,7 @@ import { definePlugin } from "payload";
 		return {
 			...config,
 			collections: installDraftGuards([...config.collections ?? [], apiKeysCollection]),
+			globals: installGlobalDraftGuards(config.globals ?? []),
 			endpoints: [
 				...config.endpoints ?? [],
 				{

package/dist/schema/describe.mjs

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

package/dist/schema/lexical.mjs

@@ -1,3 +1,4 @@
+import { flattenAllFields } from "payload";
 //#region src/schema/lexical.ts
 /**
 * Node types Lexical registers itself.
@@ -12,14 +13,61 @@
 	"tab"
 ];
 /**
+* Node types whose sub-fields exist but cannot be addressed by a schema path.
+*
+* Asked without a node, `upload` answers with every enabled collection's
+* upload fields concatenated, so the result describes no single position. It
+* would need addressing by `relationTo` to mean anything.
+*/ const OPAQUE_NODE_TYPES = /* @__PURE__ */ new Set(["upload"]);
+/**
+* Sub-schemas per rich text field, keyed by node type. `null` records a node
+* type that was asked and has nothing to describe, so it is asked only once.
+*
+* Worth caching because the describe and validate paths resolve the same field
+* repeatedly, and because the block features build their answer from scratch on
+* every call. Keyed weakly on the sanitized field, which lives as long as the
+* config does.
+*/ const subSchemaCache = /* @__PURE__ */ new WeakMap();
+const featuresOf = (field) => field.editor?.editorConfig?.features;
+/**
 * Node types a rich text field accepts. Editors other than Lexical report
 * only the core nodes.
 */ const allowedNodeTypes = (field) => {
-	const registered = (field.editor?.editorConfig?.features?.nodes ?? []).flatMap((entry) => {
+	const registered = (featuresOf(field)?.nodes ?? []).flatMap((entry) => {
 		const type = entry.node?.getType?.();
 		return type ? [type] : [];
 	});
 	return [.../* @__PURE__ */ new Set([...LEXICAL_CORE_NODES, ...registered])];
 };
+const resolveSubSchema = (field, nodeType) => {
+	if (OPAQUE_NODE_TYPES.has(nodeType)) return null;
+	const fields = featuresOf(field)?.getSubFields?.get(nodeType)?.({});
+	if (!fields?.length) return null;
+	const flattened = flattenAllFields({ fields });
+	const only = flattened.length === 1 ? flattened[0] : void 0;
+	return only?.type === "blocks" ? {
+		blocksField: only,
+		kind: "blocks"
+	} : {
+		fields: flattened,
+		kind: "fields"
+	};
+};
+/**
+* The sub-schema behind one node type of a rich text field, or `undefined`
+* when that node carries no addressable fields.
+*/ const lexicalSubSchema = (field, nodeType) => {
+	let cached = subSchemaCache.get(field);
+	if (!cached) {
+		cached = /* @__PURE__ */ new Map();
+		subSchemaCache.set(field, cached);
+	}
+	if (!cached.has(nodeType)) cached.set(nodeType, resolveSubSchema(field, nodeType));
+	return cached.get(nodeType) ?? void 0;
+};
+/**
+* Node types of a rich text field that have a sub-schema, in the order their
+* features registered them.
+*/ const subSchemaNodeTypes = (field) => [...featuresOf(field)?.getSubFields?.keys() ?? []].filter((nodeType) => lexicalSubSchema(field, nodeType) !== void 0);
 //#endregion
-export { allowedNodeTypes };
+export { allowedNodeTypes, lexicalSubSchema, subSchemaNodeTypes };