@abinnovision/payloadcms-mcpx 1.1.0-beta.6 → 2.0.0-beta.10

package/dist/i18n.mjs

@@ -1,27 +1,29 @@
 //#region src/i18n.ts
 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) => {
+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;
 	}
 };
 /**
-* Resolves a static label or `admin.description` to the one string a client
-* can use: the request's language, then the fallback language configured for
-* the deployment, then whichever entry the record declares first.
+* Resolves a static label or `admin.description` to one string: the request's
+* language, then the configured fallback language, then the first entry the
+* record declares.
 *
 * Anything that is not a string or a string-valued record is dropped. A
-* description written as a function or a React component is an admin-UI
-* construct that may reach client-only i18n, so it is never invoked here.
+* function or React component description may reach client-only i18n, so it is
+* never invoked.
 */ const translateStatic = (value, language) => {
 	if (typeof value === "string") return value.trim() === "" ? void 0 : value;
 	const record = stringRecord(value);
 	if (!record) return;
 	return pick(record, language.language) ?? pick(record, language.fallbackLanguage) ?? Object.values(record).find((entry) => entry.trim() !== "");
 };
-/** 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({
+const translatorFor = (i18n) => (value) => translateStatic(value, i18n);
+/**
+* For callers with no request. Both languages miss, so the first entry wins.
+*/ const translateAny = translatorFor({
 	fallbackLanguage: "",
 	language: ""
 });

package/dist/index.d.mts

@@ -1,5 +1,8 @@
-import { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, McpxWriteMode, PublishBlocker, defineMcpxTool } from "./types.mjs";
+import { DocumentId } from "./entity.mjs";
+import { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxScopeSlugs, McpxTool, McpxToolExtra, McpxToolScope, McpxWriteMode } from "./types.mjs";
+import { defineMcpxTool } from "./define-tool.mjs";
 import { mcpxPlugin } from "./plugin.mjs";
 import { isMcpxRequest } from "./request.mjs";
 import { errorResult, jsonResult } from "./result.mjs";
-export { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, McpxWriteMode, PublishBlocker, defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin };
+import { mcpxReadRequest } from "./tools/read-request.mjs";
+export { type McpxAnyTool, type McpxAuthResult, type McpxCollectionCapabilities, type McpxCollectionOptions, type DocumentId as McpxDocumentId, type McpxExposedEntity, type McpxGlobalOptions, type McpxPluginOptions, type McpxRequestContext, type McpxResolvedCapabilities, type McpxScopeSlugs, type McpxTool, type McpxToolExtra, type McpxToolScope, type McpxWriteMode, defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin, mcpxReadRequest };

package/dist/index.mjs

@@ -1,5 +1,6 @@
+import { defineMcpxTool } from "./define-tool.mjs";
 import { errorResult, jsonResult } from "./result.mjs";
-import { defineMcpxTool } from "./types.mjs";
+import { mcpxReadRequest } from "./tools/read-request.mjs";
 import { isMcpxRequest } from "./request.mjs";
 import { mcpxPlugin } from "./plugin.mjs";
-export { defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin };
+export { defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin, mcpxReadRequest };

package/dist/options.mjs

@@ -1,4 +1,5 @@
-import { BUILTIN_TOOL_NAMES } from "./tools/names.mjs";
+import { isPlainObject } from "./guards.mjs";
+import { BUILTIN_TOOL_NAMES } from "./builtin-tool-names.mjs";
 import "./version.mjs";
 import { InvalidConfiguration } from "payload";
 import { hasDraftsEnabled, hasLocalizeStatusEnabled } from "payload/shared";
@@ -11,45 +12,55 @@ 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());
 /**
-* Auth collections carry credentials: `useAPIKey` stores a key that decrypts on
-* read, and email or lockout state is PII either way. Refused for read too.
-*/ const assertExposable = (collection, apiKeysSlug) => {
+* 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());
+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".`);
+const OPTION_NAMES = [
+	"read",
+	"write",
+	"publish"
+];
+const REMOVED_WRITE_MODES = {
+	draft: "Use { publish: false } instead.",
+	live: "Writes are on by default, so remove it."
 };
-/**
-* `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 readFlag = (kind, slug, name, value) => {
+	if (value === void 0 || typeof value === "boolean") return value;
+	const moved = name === "write" && typeof value === "string" ? REMOVED_WRITE_MODES[value] : void 0;
+	return fail(`${kind} "${slug}" has ${name}: ${JSON.stringify(value)}. ${moved ?? "Use true or false."}`);
 };
-const assertWritable = (collection, options) => {
-	const { slug } = collection;
-	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);
+const assertWritable = (kind, config, write) => {
+	if (write === "live" && hasLocalizeStatusEnabled(config)) fail(`${kind} "${config.slug}" has versions.drafts.localizeStatus enabled, which live writes do not support yet. Set publish: false or write: false.`);
 };
-/** 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.`);
+const normalizeCapabilities = (kind, config, raw) => {
+	const { slug } = config;
+	if (raw === false) fail(`${kind} "${slug}" is set to false. Remove the entry to hide the ${kind.toLowerCase()}.`);
+	if (raw !== true && !isPlainObject(raw)) fail(`${kind} "${slug}" has ${JSON.stringify(raw)}. Use true or an object of ${OPTION_NAMES.join(", ")}.`);
+	const settings = isPlainObject(raw) ? raw : {};
+	const unknownKey = Object.keys(settings).find((key) => !OPTION_NAMES.includes(key));
+	if (unknownKey !== void 0) fail(`${kind} "${slug}" has the unknown option "${unknownKey}". The options are ${OPTION_NAMES.join(", ")}.`);
+	const flag = (name) => readFlag(kind, slug, name, settings[name]);
+	const read = flag("read") ?? true;
+	const write = flag("write") ?? true;
+	const publish = flag("publish");
+	const hasDrafts = hasDraftsEnabled(config);
+	if (publish === false && write && !hasDrafts) fail(`${kind} "${slug}" has no drafts, so every write goes live. Set write: false or remove publish: false.`);
+	if (publish === true && !hasDrafts) fail(`${kind} "${slug}" has no drafts, so there is nothing to publish. Enable versions.drafts or remove publish: true.`);
+	if (publish === true && !write) fail(`${kind} "${slug}" has publish: true but write: false. Publishing follows write.`);
+	return {
+		read,
+		write: write ? publish === false ? "draft" : "live" : false,
+		hasDrafts,
+		hasVersions: read && Boolean(config.versions)
+	};
 };
-/**
-* `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.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 assertGlobalExposable = (global) => {
+	if (global.slug.startsWith("payload-")) fail(`Global "${global.slug}" cannot be exposed.`);
 };
 const normalizeCollections = (config, options, apiKeysSlug) => {
 	const collections = config.collections ?? [];
@@ -59,18 +70,16 @@ const normalizeCollections = (config, options, apiKeysSlug) => {
 		const collection = collections.find((candidate) => candidate.slug === slug);
 		if (!collection) return fail(`Exposed collection "${slug}" does not exist.`);
 		assertExposable(collection, apiKeysSlug);
-		const settings = raw === true ? {} : raw;
-		const hasDrafts = hasDraftsEnabled(collection);
 		const normalized = {
 			slug,
-			read: settings.read ?? true,
-			write: normalizeWriteMode("Collection", slug, settings.write),
-			hasDrafts,
-			hasVersions: Boolean(collection.versions),
+			...normalizeCapabilities("Collection", collection, raw),
 			isUpload: Boolean(collection.upload),
 			fieldName: toCamelCase(slug)
 		};
-		if (normalized.write !== false) assertWritable(collection, normalized);
+		if (normalized.write !== false) {
+			if (collection.timestamps === false) fail(`Collection "${slug}" has timestamps disabled, which write tools need for concurrency checks.`);
+			assertWritable("Collection", collection, normalized.write);
+		}
 		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];
@@ -84,18 +93,13 @@ const normalizeGlobals = (config, options) => {
 		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: normalizeWriteMode("Global", slug, settings.write),
-			hasDrafts,
-			hasVersions: Boolean(global.versions),
+			...normalizeCapabilities("Global", global, raw),
 			isUpload: false,
 			fieldName: toCamelCase(slug)
 		};
-		if (normalized.write !== false) assertGlobalWritable(global, normalized);
+		if (normalized.write !== false) assertWritable("Global", global, normalized.write);
 		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];
@@ -125,7 +129,9 @@ const normalizeLimits = (limits) => {
 		maxDepth
 	};
 };
-/** Every problem is an `InvalidConfiguration`, so it fails at startup. */ 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/plugin.mjs

@@ -1,6 +1,5 @@
 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/request.d.mts

@@ -1,9 +1,8 @@
 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
- * same `req`, including those made by custom tools.
+ * Whether `req` came through the MCP endpoint, which stamps `req.context.mcpx`.
+ * The stamp follows `req` into every local API call, including custom tools.
  */
 export declare const isMcpxRequest: (req: PayloadRequest) => boolean;
 //#endregion

package/dist/request.mjs

@@ -1,8 +1,7 @@
 //#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.
+* Whether `req` came through the MCP endpoint, which stamps `req.context.mcpx`.
+* The stamp follows `req` into every local API call, including custom tools.
 */ const isMcpxRequest = (req) => req.context.mcpx !== void 0;
 //#endregion
 export { isMcpxRequest };

package/dist/result.d.mts

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

package/dist/result.mjs

@@ -1,11 +1,11 @@
 //#region src/result.ts
-/** `value` as JSON text. */ const jsonResult = (value) => ({ content: [{
+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`.
+* `extras` carries data the client can act on, such as problems, validation
+* errors or the current `updatedAt`.
 */ const errorResult = (message, extras = {}) => ({
 	content: [{
 		type: "text",

package/dist/schema/admin-hidden.mjs

@@ -0,0 +1,91 @@
+import { isPlainObject } from "../guards.mjs";
+import { RESERVED_FIELD_NAMES, ROW_KEYS, blockOf, blockSlugsOf, isAdminHidden, schemaOf } from "./walk.mjs";
+//#region src/schema/admin-hidden.ts
+const UPLOAD_BASE_FIELDS = /* @__PURE__ */ new Set([
+	"filename",
+	"filesize",
+	"focalX",
+	"focalY",
+	"height",
+	"mimeType",
+	"sizes",
+	"thumbnailURL",
+	"url",
+	"width"
+]);
+const NONE = /* @__PURE__ */ new Set();
+const isPayloadKey = (name) => RESERVED_FIELD_NAMES.has(name) || ROW_KEYS.has(name);
+const collectionOf = (config, slug) => config.collections.find((collection) => collection.slug === slug);
+const exemptOf = (collection) => collection?.upload ? UPLOAD_BASE_FIELDS : NONE;
+const mapEach = (value, one) => Array.isArray(value) ? value.map(one) : one(value);
+const stripFields = (config, fields, doc, exempt = NONE) => {
+	const result = { ...doc };
+	for (const field of fields) {
+		if (!("name" in field) || exempt.has(field.name) || isPayloadKey(field.name) || !Object.hasOwn(result, field.name)) continue;
+		if (isAdminHidden(field)) Reflect.deleteProperty(result, field.name);
+		else result[field.name] = stripValue(config, field, result[field.name]);
+	}
+	return result;
+};
+const stripRelated = (config, relationTo, value) => {
+	if (!isPlainObject(value)) return value;
+	if (Array.isArray(relationTo)) {
+		const slug = value["relationTo"];
+		return typeof slug === "string" && isPlainObject(value["value"]) ? {
+			...value,
+			value: stripRelated(config, slug, value["value"])
+		} : value;
+	}
+	const collection = collectionOf(config, relationTo);
+	return collection ? stripFields(config, collection.flattenedFields, value, exemptOf(collection)) : value;
+};
+const stripValue = (config, field, value) => {
+	switch (field.type) {
+		case "group":
+		case "tab": return isPlainObject(value) ? stripFields(config, field.flattenedFields, value) : value;
+		case "array": return mapEach(value, (row) => isPlainObject(row) ? stripFields(config, field.flattenedFields, row) : row);
+		case "blocks": return mapEach(value, (row) => {
+			const block = isPlainObject(row) && typeof row["blockType"] === "string" ? blockOf(config, field, row["blockType"]) : void 0;
+			return block && isPlainObject(row) ? stripFields(config, block.flattenedFields, row) : row;
+		});
+		case "relationship":
+		case "upload": return mapEach(value, (item) => stripRelated(config, field.relationTo, item));
+		case "join": return isPlainObject(value) && Array.isArray(value["docs"]) ? {
+			...value,
+			docs: value["docs"].map((item) => stripRelated(config, field.collection, item))
+		} : value;
+		default: return value;
+	}
+};
+/**
+* The document without its `admin.hidden` fields, at every depth, including
+* populated documents, which are read against their own collection. Payload's
+* upload fields stay. Rich text is not walked.
+*/ const stripAdminHidden = (config, ref, doc) => stripFields(config, schemaOf(config, ref).flattenedFields, doc, ref.kind === "collection" ? exemptOf(collectionOf(config, ref.slug)) : NONE);
+/**
+* Whether a query path inside one collection names an `admin.hidden` field or
+* a field under one. The path is dotted, with a locale segment allowed after a
+* localized field. Hops into other collections are the caller's to follow.
+*/ const addressesAdminHidden = (config, collectionSlug, path) => {
+	const collection = collectionOf(config, collectionSlug);
+	if (!collection) return false;
+	const locales = config.localization ? config.localization.localeCodes : [];
+	const walk = (fields, segments) => {
+		const [segment, ...rest] = segments;
+		if (segment === void 0 || isPayloadKey(segment)) return false;
+		const matches = fields.filter((field) => "name" in field && field.name === segment);
+		if (matches.length === 0) return locales.includes(segment) ? walk(fields, rest) : false;
+		return matches.some((field) => {
+			if (isAdminHidden(field)) return true;
+			if (field.type === "group" || field.type === "tab" || field.type === "array") return walk(field.flattenedFields, rest);
+			return field.type === "blocks" && blockSlugsOf(field).some((slug) => {
+				const block = blockOf(config, field, slug);
+				return block !== void 0 && walk(block.flattenedFields, rest);
+			});
+		});
+	};
+	const segments = path.split(".");
+	return !exemptOf(collection).has(segments[0] ?? "") && walk(collection.flattenedFields, segments);
+};
+//#endregion
+export { addressesAdminHidden, stripAdminHidden };

package/dist/schema/describe.mjs

@@ -1,68 +1,55 @@
 import { lexicalSubSchema, subSchemaNodeTypes } from "./lexical.mjs";
+import { joinPath, splitPath } from "./path.mjs";
 import { translateAny } from "../i18n.mjs";
-import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextField, joinPath, splitPath, targetOf } from "./walk.mjs";
+import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextField, schemaOf } from "./walk.mjs";
+import { SchemaError } from "./errors.mjs";
 //#region src/schema/describe.ts
-/** 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 matchSchemaSegments = (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);
-	if (slug === void 0) throw new Error(`"${joinPath(match)}" is a blocks field; append one of: ${blockSlugsOf(field).join(", ")}`);
+	if (slug === void 0) throw new SchemaError(`"${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(", ")}`);
+	if (!block) throw new SchemaError(`"${slug}" is not allowed at "${joinPath(match)}". Allowed: ${blockSlugsOf(field).join(", ")}`);
 	return {
 		blockType: slug,
 		fields: block.flattenedFields,
 		rest: remaining.slice(match.length + 1)
 	};
 };
-/**
-* 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 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}`);
+	if (nodeType === void 0) throw new SchemaError(`"${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) throw new SchemaError(`"${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}`);
+	if (slug === void 0) throw new SchemaError(`"${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}`);
+	if (!block) throw new SchemaError(`"${slug}" is not allowed at "${reached}". Allowed: ${slugs}`);
 	return {
 		blockType: slug,
 		fields: block.flattenedFields,
 		rest: remaining.slice(match.length + 2)
 	};
 };
-/**
-* A schema path alternates a blocks field's own path with the slug of one of
-* the blocks it accepts, so `/layout/sections/sectionWrapper/modules/hero`
-* reaches `hero` as it exists under `pages` specifically. The slug sits where
-* a pointer into a document would carry the element's index. A 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) => {
+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 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 match = matchSchemaSegments(descendable, remaining);
+		if (!match) throw new SchemaError(`"${joinPath(remaining)}" does not address a blocks or rich text field. Available here: ${descendable.map((descriptor) => descriptor.path).join(", ") || "none"}`);
 		const at = {
 			config,
 			fields,
@@ -79,10 +66,7 @@ const stepThroughBlocks = ({ config, fields, match, remaining }) => {
 		fields
 	};
 };
-/**
-* 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 branchesOf = (fields, descriptor, schemaPath) => {
 	const base = `${schemaPath}${descriptor.path}`;
 	if (descriptor.type === "richText") {
 		const field = findRichTextField(fields, splitPath(descriptor.path));
@@ -108,7 +92,7 @@ const stepThroughBlocks = ({ config, fields, match, remaining }) => {
 * Curried on the translator that resolves each `admin.description`, so a
 * 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 { blockType, fields } = fieldsAtSchemaPath(config, schemaOf(config, ref), schemaPath);
 	const descriptors = describeFields(fields, translate);
 	const next = descriptors.flatMap((descriptor) => branchesOf(fields, descriptor, schemaPath).map((branch) => branch.path));
 	return {
@@ -132,7 +116,7 @@ const stepThroughBlocks = ({ config, fields, match, remaining }) => {
 			return;
 		}
 		seen.push(schemaPath);
-		const { fields } = fieldsAtSchemaPath(config, targetOf(config, ref), schemaPath);
+		const { fields } = fieldsAtSchemaPath(config, schemaOf(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]);

package/dist/schema/errors.mjs

@@ -0,0 +1,8 @@
+//#region src/schema/errors.ts
+/**
+* A schema lookup the client got wrong, such as a path no field answers to.
+* The message is written for the client and names what to send instead.
+*/ var SchemaError = class extends Error {};
+SchemaError.prototype.name = "SchemaError";
+//#endregion
+export { SchemaError };

package/dist/schema/index.mjs

@@ -1,8 +1,11 @@
 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 { JSON_POINTER_PATTERN, isIndexSegment, joinPath, pointerFromPayloadPath, prototypeSegmentProblem, splitPath } from "./path.mjs";
+import { RESERVED_FIELD_NAMES, ROW_KEYS, blockOf, blockSlugsOf, describeAddressableFields, describeFields, descriptorsUnder, findBlocksField, findRichTextField, isAdminHidden, schemaOf } from "./walk.mjs";
+import { addressesAdminHidden, stripAdminHidden } from "./admin-hidden.mjs";
+import { SchemaError } from "./errors.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 };
+export { EMPTY_ROOT, JSON_POINTER_PATTERN, REQUIRED_NODE_PROPERTIES, RESERVED_FIELD_NAMES, ROOT_PROPERTIES, ROW_KEYS, SchemaError, addressesAdminHidden, allowedNodeTypes, blockOf, blockSlugsOf, constrainsFields, describeAddressableFields, describeFields, descriptorsUnder, findBlocksField, findRichTextField, isAdminHidden, isIndexSegment, joinPath, lexicalOutline, lexicalSubSchema, nodeDescriber, nodeOptions, nodeProblems, nodePropertiesFor, pointerFromPayloadPath, propertyProblem, prototypeSegmentProblem, reachableSchemaPaths, resolveDataPointer, resolveLexicalPointer, rootProblems, schemaOf, splitPath, stripAdminHidden, subSchemaNodeTypes, validateWriteValue };

package/dist/schema/lexical-pointer.mjs

@@ -1,14 +1,13 @@
+import { isPlainObject } from "../guards.mjs";
 import { lexicalSubSchema, subSchemaNodeTypes } from "./lexical.mjs";
-import { blockOf, blockSlugsOf, isIndexSegment, isPlainObject, joinPath } from "./walk.mjs";
+import { isIndexSegment, joinPath } from "./path.mjs";
+import { blockOf, blockSlugsOf } from "./walk.mjs";
+import { SchemaError } from "./errors.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 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(", ")}`);
+	if (!sub) throw new SchemaError(`"${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,
@@ -18,9 +17,10 @@ import { blockOf, blockSlugsOf, isIndexSegment, isPlainObject, joinPath } from "
 	};
 	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(", ")}`);
+	if (slug === void 0) throw new SchemaError(`Cannot tell which block a "${nodeType}" node holds. Supply a "blockType" on the value, one of: ${blockSlugsOf(sub.blocksField).join(", ")}`);
+	if (typeof slug !== "string") throw new SchemaError(`"blockType" must be a string naming a block in a "${nodeType}" node here. Allowed: ${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(", ")}`);
+	if (!block) throw new SchemaError(`"${slug}" is not allowed in a "${nodeType}" node here. Allowed: ${blockSlugsOf(sub.blocksField).join(", ")}`);
 	return {
 		blockType: slug,
 		data,
@@ -31,21 +31,19 @@ import { blockOf, blockSlugsOf, isIndexSegment, isPlainObject, joinPath } from "
 };
 /**
 * 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.
+* The stored state chooses the branch at every index, as the stored document
+* does at a blocks element: an editor state admits many node shapes at the same
+* position. 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.`);
+	if (!isPlainObject(state) || !isPlainObject(state["root"])) throw new SchemaError(`"${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.`);
+	if (entry !== "root") throw new SchemaError(`"${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;
@@ -72,7 +70,7 @@ import { blockOf, blockSlugsOf, isIndexSegment, isPlainObject, joinPath } from "
 				}
 			};
 			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.`);
+			if (!isIndexSegment(index)) throw new SchemaError(`"${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;
@@ -84,7 +82,7 @@ import { blockOf, blockSlugsOf, isIndexSegment, isPlainObject, joinPath } from "
 						kind: "node"
 					}
 				};
-				throw new Error(`Cannot tell which node "${descriptor.path}${joinPath([
+				throw new SchemaError(`Cannot tell which node "${descriptor.path}${joinPath([
 					...walked,
 					"children",
 					index
@@ -108,7 +106,7 @@ import { blockOf, blockSlugsOf, isIndexSegment, isPlainObject, joinPath } from "
 			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.`);
+		if (remaining.length > 0) throw new SchemaError(`"${segment}" is a property of a "${nodeType}" node and nothing beneath it can be addressed.`);
 		return {
 			kind: "position",
 			position: {