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

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";
@@ -12,44 +13,56 @@ 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) => {
+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",
+	"versions"
+];
+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 versions = flag("versions") ?? false;
+	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.`);
+	if (versions && !config.versions) fail(`${kind} "${slug}" keeps no versions. Enable versions or remove versions: true.`);
+	if (versions && !read) fail(`${kind} "${slug}" has versions: true but read: false. Version history follows read.`);
+	return {
+		read,
+		write: write ? publish === false ? "draft" : "live" : false,
+		hasDrafts,
+		hasVersions: 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 +72,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 +95,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];

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: {