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

package/dist/schema/lexical-pointer.mjs

@@ -1,8 +1,8 @@
-import { isPlainObject } from "../guards.mjs";
-import { lexicalSubSchema, subSchemaNodeTypes } from "./lexical.mjs";
+import { isPlainObject, propOf } from "../guards.mjs";
+import { SchemaError } from "./errors.mjs";
+import { editorRoot, lexicalSubSchema, subSchemaNodeTypes } from "./lexical.mjs";
 import { isIndexSegment, joinPath } from "./path.mjs";
 import { blockOf, blockSlugsOf } from "./walk.mjs";
-import { SchemaError } from "./errors.mjs";
 //#region src/schema/lexical-pointer.ts
 const stepIntoFields = (at) => {
 	const { addedValue, config, field, node, nodeType, rest } = at;
@@ -15,8 +15,7 @@ const stepIntoFields = (at) => {
 		kind: "fields",
 		rest
 	};
-	const added = addedValue?.fields;
-	const slug = (isPlainObject(data) ? data["blockType"] : void 0) ?? (isPlainObject(added) ? added["blockType"] : void 0);
+	const slug = propOf(data, "blockType") ?? propOf(propOf(addedValue, "fields"), "blockType");
 	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);
@@ -41,10 +40,11 @@ const stepIntoFields = (at) => {
 		descriptor,
 		field
 	};
-	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 root = editorRoot(state);
+	if (!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 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 node = root;
 	let nodeType = "root";
 	let segments = rest;
 	let walked = ["root"];
@@ -73,7 +73,7 @@ const stepIntoFields = (at) => {
 			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;
+			const type = isPlainObject(child) ? child["type"] : propOf(addedValue, "type");
 			if (typeof type !== "string") {
 				if (beyond.length === 0) return {
 					kind: "position",

package/dist/schema/lexical.mjs

@@ -1,4 +1,4 @@
-import { isPlainObject, ownValue } from "../guards.mjs";
+import { isPlainObject, ownValue, propOf } from "../guards.mjs";
 import { flattenAllFields } from "payload";
 //#region src/schema/lexical.ts
 const LEXICAL_CORE_NODES = [
@@ -11,7 +11,9 @@ const LEXICAL_CORE_NODES = [
 const OPAQUE_NODE_TYPES = /* @__PURE__ */ new Set(["upload"]);
 const subSchemaCache = /* @__PURE__ */ new WeakMap();
 const featuresOf = (field) => field.editor?.editorConfig?.features;
-/** Editors other than Lexical report only the core nodes. */ const allowedNodeTypes = (field) => {
+/**
+* Editors other than Lexical report only the core nodes.
+*/ const allowedNodeTypes = (field) => {
 	const registered = (featuresOf(field)?.nodes ?? []).flatMap((entry) => {
 		const type = entry.node?.getType?.();
 		return type ? [type] : [];
@@ -41,7 +43,9 @@ const lexicalSubSchema = (field, nodeType) => {
 	if (!cached.has(nodeType)) cached.set(nodeType, resolveSubSchema(field, nodeType));
 	return cached.get(nodeType) ?? void 0;
 };
-/** In the order their features registered them. */ const subSchemaNodeTypes = (field) => [...featuresOf(field)?.getSubFields?.keys() ?? []].filter((nodeType) => lexicalSubSchema(field, nodeType) !== void 0);
+/**
+* In the order their features registered them.
+*/ const subSchemaNodeTypes = (field) => [...featuresOf(field)?.getSubFields?.keys() ?? []].filter((nodeType) => lexicalSubSchema(field, nodeType) !== void 0);
 const KINDS = {
 	array: {
 		accepts: (value) => Array.isArray(value),
@@ -144,6 +148,16 @@ const UNIVERSAL_PROPERTIES = { version: "number" };
 	}
 };
 /**
+* The `root` node of an editor state, if it has one.
+*/ const editorRoot = (state) => {
+	const root = propOf(state, "root");
+	return isPlainObject(root) ? root : void 0;
+};
+const constraintsFor = (type) => ({
+	...UNIVERSAL_PROPERTIES,
+	...ownValue(REQUIRED_NODE_PROPERTIES, type)
+});
+/**
 * Whether the table already says what a node type's `fields` must be, so the
 * sub-field walk does not report the same problem twice.
 */ const constrainsFields = (type) => "fields" in (ownValue(REQUIRED_NODE_PROPERTIES, type) ?? {});
@@ -155,8 +169,7 @@ const describeConstraints = (constraints) => Object.fromEntries(Object.entries(c
 * {@link UNIVERSAL_PROPERTIES} omits it: the validator finds the entry by
 * `type` and so never reports it missing, but a client must still write one.
 */ const nodePropertiesFor = (types) => Object.fromEntries([...new Set(types)].sort().map((type) => [type, describeConstraints(type === "root" ? ROOT_PROPERTIES : {
-	...ownValue(REQUIRED_NODE_PROPERTIES, type),
-	...UNIVERSAL_PROPERTIES,
+	...constraintsFor(type),
 	type: "string"
 })]));
 const check = (node, constraints) => {
@@ -173,10 +186,7 @@ const check = (node, constraints) => {
 	problems.rejected.sort((left, right) => left.property.localeCompare(right.property));
 	return problems;
 };
-const nodeProblems = (node) => check(node, {
-	...UNIVERSAL_PROPERTIES,
-	...ownValue(REQUIRED_NODE_PROPERTIES, node["type"])
-});
+const nodeProblems = (node) => check(node, constraintsFor(node["type"]));
 /**
 * The root is the one node Payload describes itself, down to refusing an
 * unknown property, so it is checked against that description instead of the
@@ -190,11 +200,7 @@ const nodeProblems = (node) => check(node, {
 * instead of a whole node. Absent where the table says nothing, matching the
 * node walk: a project's own node may carry any property.
 */ const propertyProblem = (nodeType, property, value) => {
-	const constraints = nodeType === "root" ? ROOT_PROPERTIES : {
-		...UNIVERSAL_PROPERTIES,
-		...ownValue(REQUIRED_NODE_PROPERTIES, nodeType)
-	};
-	const constraint = ownValue(constraints, property);
+	const constraint = ownValue(nodeType === "root" ? ROOT_PROPERTIES : constraintsFor(nodeType), property);
 	return constraint === void 0 || accepts(constraint, value) ? void 0 : { needs: needs(constraint) };
 };
 const NODE_OPTION_SOURCES = [{
@@ -229,4 +235,4 @@ const stringList = (value) => Array.isArray(value) && value.every((entry) => typ
 	return entries.length > 0 ? Object.fromEntries(entries) : void 0;
 };
 //#endregion
-export { REQUIRED_NODE_PROPERTIES, ROOT_PROPERTIES, allowedNodeTypes, constrainsFields, lexicalSubSchema, nodeOptions, nodeProblems, nodePropertiesFor, propertyProblem, rootProblems, subSchemaNodeTypes };
+export { REQUIRED_NODE_PROPERTIES, ROOT_PROPERTIES, allowedNodeTypes, constrainsFields, editorRoot, lexicalSubSchema, nodeOptions, nodeProblems, nodePropertiesFor, propertyProblem, rootProblems, subSchemaNodeTypes };

package/dist/schema/outline.mjs

@@ -1,5 +1,5 @@
 import { isPlainObject, ownValue } from "../guards.mjs";
-import { allowedNodeTypes, nodeOptions } from "./lexical.mjs";
+import { allowedNodeTypes, editorRoot, nodeOptions } from "./lexical.mjs";
 //#region src/schema/outline.ts
 const TEXT_PREVIEW_LENGTH = 80;
 const collectText = (node) => {
@@ -43,12 +43,11 @@ const walk = (node, pointer, options, entries) => {
 * entry's `pointer` extends it with "/root" and the node's real indices, which
 * makes it directly usable in a patch operation.
 */ const lexicalOutline = (state, basePointer, field) => {
-	if (!isPlainObject(state)) return [];
-	const root = state["root"];
-	if (!isPlainObject(root) || !Array.isArray(root["children"])) return [];
+	const rootChildren = editorRoot(state)?.["children"];
+	if (!Array.isArray(rootChildren)) return [];
 	const options = nodeOptions(field, allowedNodeTypes(field));
 	const entries = [];
-	root["children"].forEach((child, index) => {
+	rootChildren.forEach((child, index) => {
 		if (isPlainObject(child)) walk(child, `${basePointer}/root/children/${String(index)}`, options, entries);
 	});
 	return entries;

package/dist/schema/path.mjs

@@ -1,7 +1,11 @@
 //#region src/schema/path.ts
 const JSON_POINTER_PATTERN = /^(\/([^~/]|~[01])*)*$/;
-/** No segments is the root pointer, `""`. */ const joinPath = (parts) => parts.map((part) => `/${part.replace(/~/g, "~0").replace(/\//g, "~1")}`).join("");
-/** Unescapes `~1` and `~0`. The root pointer yields no segments. */ const splitPath = (path) => path.split("/").slice(1).map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
+/**
+* No segments is the root pointer, `""`.
+*/ const joinPath = (parts) => parts.map((part) => `/${part.replace(/~/g, "~0").replace(/\//g, "~1")}`).join("");
+/**
+* Unescapes `~1` and `~0`. The root pointer yields no segments.
+*/ const splitPath = (path) => path.split("/").slice(1).map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
 const PROTOTYPE_SEGMENTS = /* @__PURE__ */ new Set([
 	"__proto__",
 	"constructor",
@@ -12,11 +16,16 @@ const PROTOTYPE_SEGMENTS = /* @__PURE__ */ new Set([
 * intermediate tokens but writes them as a final key, so a pointer containing
 * one is refused before anything resolves it.
 */ const prototypeSegmentProblem = (pointer) => splitPath(pointer).some((segment) => PROTOTYPE_SEGMENTS.has(segment)) ? `"${pointer}" contains a segment named __proto__, constructor or prototype, which no field or node property uses.` : void 0;
-/** `-` included, since RFC 6901 reads it as the position after the last. */ const isIndexSegment = (segment) => segment === "-" || /^\d+$/.test(segment);
+/**
+* `-` included, since RFC 6901 reads it as the position after the last.
+*/ const isIndexSegment = (segment) => segment === "-" || /^\d+$/.test(segment);
 /**
 * A path Payload reports on a validation error (`layout.0.title`) as a JSON
 * Pointer, so everything handed back addresses documents the same way. The
 * path already carries real indices, so it maps directly.
 */ const pointerFromPayloadPath = (path) => path ? joinPath(path.split(".")) : "";
+/**
+* The pointer one segment up. The root pointer stays the root.
+*/ const parentPointer = (pointer) => joinPath(splitPath(pointer).slice(0, -1));
 //#endregion
-export { JSON_POINTER_PATTERN, isIndexSegment, joinPath, pointerFromPayloadPath, prototypeSegmentProblem, splitPath };
+export { JSON_POINTER_PATTERN, isIndexSegment, joinPath, parentPointer, pointerFromPayloadPath, prototypeSegmentProblem, splitPath };

package/dist/schema/pointer.mjs

@@ -1,14 +1,10 @@
-import { isIndexSegment, joinPath, splitPath } from "./path.mjs";
-import { blockOf, blockSlugsOf, describeAddressableFields, findBlocksField, findRichTextField, schemaOf } from "./walk.mjs";
+import { propOf } from "../guards.mjs";
 import { SchemaError } from "./errors.mjs";
+import { isIndexSegment, joinPath, splitPath } from "./path.mjs";
+import { blockSlugsOf, describeAddressableFields, findFieldAt, longestMatch, requireBlock, schemaOf } from "./walk.mjs";
 import { resolveLexicalPointer } from "./lexical-pointer.mjs";
 //#region src/schema/pointer.ts
 const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isIndexSegment(segment) : part === segment);
-const matchPointerSegments = (descriptors, segments) => descriptors.map((descriptor) => ({
-	consumed: splitPath(descriptor.path).length,
-	descriptor,
-	parts: splitPath(descriptor.path)
-})).filter(({ parts }) => parts.every((part, offset) => partMatches(part, segments[offset]))).sort((left, right) => right.consumed - left.consumed)[0];
 const isSubtreePrefix = (descriptors, segments) => descriptors.some((descriptor) => {
 	const parts = splitPath(descriptor.path);
 	return parts.length > segments.length && segments.every((segment, offset) => {
@@ -21,17 +17,15 @@ const stepIntoBlock = (at) => {
 	const { addedValue, config, descriptor, rows } = at;
 	const [index, ...remaining] = at.rest;
 	if (!isIndexSegment(index)) throw new SchemaError(`"${descriptor.path}" is an array; "${index}" is not an index.`);
-	const field = findBlocksField(at.fields, splitPath(descriptor.path));
+	const field = findFieldAt(at.fields, splitPath(descriptor.path), "blocks");
 	const existing = Array.isArray(rows) && index !== "-" ? rows[Number(index)] : void 0;
-	const slug = existing?.blockType ?? addedValue?.blockType;
+	const slug = propOf(existing, "blockType") ?? propOf(addedValue, "blockType");
 	if (!field || slug === void 0) throw new SchemaError(`Cannot tell which block "${descriptor.path}/${index}" is. Supply a "blockType" on the value, one of: ${field ? blockSlugsOf(field).join(", ") : ""}`);
 	if (typeof slug !== "string") throw new SchemaError(`"blockType" must be a string naming a block at "${descriptor.path}". Allowed: ${blockSlugsOf(field).join(", ")}`);
-	const block = blockOf(config, field, slug);
-	if (!block) throw new SchemaError(`"${slug}" is not allowed at "${descriptor.path}". Allowed: ${blockSlugsOf(field).join(", ")}`);
 	return {
 		blockType: slug,
 		data: existing,
-		fields: block.flattenedFields,
+		fields: requireBlock(config, field, slug, descriptor.path).flattenedFields,
 		rest: remaining
 	};
 };
@@ -48,7 +42,7 @@ const stepIntoBlock = (at) => {
 	let inLexical;
 	while (segments.length > 0) {
 		const descriptors = describeAddressableFields(fields);
-		const match = matchPointerSegments(descriptors, segments);
+		const match = longestMatch(descriptors, segments, partMatches);
 		if (!match) {
 			if (isSubtreePrefix(descriptors, segments)) return {
 				...blockType === void 0 ? {} : { blockType },
@@ -57,7 +51,7 @@ const stepIntoBlock = (at) => {
 			};
 			throw new SchemaError(`"${joinPath(segments)}" is not a field here. Available: ${descriptors.map((descriptor) => descriptor.path).join(", ")}`);
 		}
-		const rest = segments.slice(match.consumed);
+		const rest = segments.slice(match.parts.length);
 		if (rest.length === 0) return {
 			...blockType === void 0 ? {} : { blockType },
 			descriptor: match.descriptor,
@@ -67,7 +61,7 @@ const stepIntoBlock = (at) => {
 			...readOnly === void 0 ? {} : { readOnly }
 		};
 		if (match.descriptor.type === "richText") {
-			const field = findRichTextField(fields, splitPath(match.descriptor.path));
+			const field = findFieldAt(fields, splitPath(match.descriptor.path), "richText");
 			if (!field) throw new Error(`"${match.descriptor.path}" could not be resolved.`);
 			const step = resolveLexicalPointer({
 				...target.addedValue === void 0 ? {} : { addedValue: target.addedValue },
@@ -75,7 +69,7 @@ const stepIntoBlock = (at) => {
 				descriptor: match.descriptor,
 				field,
 				segments: rest,
-				state: valueAtSegments(data, segments.slice(0, match.consumed))
+				state: valueAtSegments(data, segments.slice(0, match.parts.length))
 			});
 			if (step.kind === "position") return {
 				...blockType === void 0 ? {} : { blockType },
@@ -99,7 +93,7 @@ const stepIntoBlock = (at) => {
 			descriptor: match.descriptor,
 			fields,
 			rest,
-			rows: valueAtSegments(data, segments.slice(0, match.consumed)),
+			rows: valueAtSegments(data, segments.slice(0, match.parts.length)),
 			config
 		});
 		readOnly = match.descriptor.readOnly ?? readOnly;

package/dist/schema/shape.mjs

@@ -1,7 +1,7 @@
-import { isPlainObject, ownValue } from "../guards.mjs";
-import { ROOT_PROPERTIES, constrainsFields, lexicalSubSchema, nodeProblems, propertyProblem, rootProblems } from "./lexical.mjs";
+import { isPlainObject, ownValue, propOf } from "../guards.mjs";
+import { ROOT_PROPERTIES, constrainsFields, editorRoot, lexicalSubSchema, nodeProblems, propertyProblem, rootProblems } from "./lexical.mjs";
 import { splitPath } from "./path.mjs";
-import { ROW_KEYS, blockOf, blockSlugsOf, descriptorsUnder, findBlocksField, findRichTextField } from "./walk.mjs";
+import { ROW_KEYS, blockForRow, blockSlugsOf, classifyKey, descriptorsUnder, findFieldAt } from "./walk.mjs";
 //#region src/schema/shape.ts
 /**
 * Lexical throws when it hydrates a state whose root holds nothing. An empty
@@ -33,10 +33,9 @@ const checkNodeFields = (scope, field, node) => {
 		}, data);
 		return;
 	}
-	const slug = data["blockType"];
-	const block = typeof slug === "string" ? blockOf(scope.config, sub.blocksField, slug) : void 0;
+	const block = blockForRow(scope.config, sub.blocksField, data);
 	if (!block) {
-		scope.problems.push(`${scope.pointer}/fields: ${refusedSlug(slug)}. Allowed: ${blockSlugsOf(sub.blocksField).join(", ")}`);
+		scope.problems.push(`${scope.pointer}/fields: ${refusedSlug(data["blockType"])}. Allowed: ${blockSlugsOf(sub.blocksField).join(", ")}`);
 		return;
 	}
 	checkValue({
@@ -81,11 +80,11 @@ const checkNodes = (scope, editor, nodes, pointer) => {
 	});
 };
 const checkRichText = (scope, editor, value) => {
-	if (!isPlainObject(value) || !isPlainObject(value["root"])) {
+	const root = editorRoot(value);
+	if (!root) {
 		scope.problems.push(`${scope.pointer}: expected a Lexical editor state with a "root".`);
 		return;
 	}
-	const root = value["root"];
 	const { missing, rejected, unexpected } = rootProblems(root);
 	if (missing.length > 0) scope.problems.push(`${scope.pointer}/root: the root node is missing ${quoted(missing)}. Write nodes as Lexical serializes them.`);
 	for (const problem of rejected) scope.problems.push(`${scope.pointer}/root/${problem.property}: the root node needs ${problem.needs} here.`);
@@ -148,7 +147,7 @@ const checkLeafValue = (scope, descriptor, value) => {
 	if (descriptor.type === "richText") {
 		checkRichText(scope, {
 			allowed: descriptor.nodes ?? [],
-			field: findRichTextField(scope.fields, splitPath(descriptor.path)),
+			field: findFieldAt(scope.fields, splitPath(descriptor.path), "richText"),
 			nodeOptions: descriptor.nodeOptions
 		}, value);
 		return;
@@ -158,13 +157,12 @@ const checkLeafValue = (scope, descriptor, value) => {
 		scope.problems.push(`${scope.pointer}: expected an array of blocks.`);
 		return;
 	}
-	const field = findBlocksField(scope.fields, splitPath(descriptor.path));
-	if (!field) return;
+	const field = findFieldAt(scope.fields, splitPath(descriptor.path), "blocks");
 	value.forEach((row, index) => {
-		const slug = isPlainObject(row) ? row["blockType"] : void 0;
-		const block = typeof slug === "string" ? blockOf(scope.config, field, slug) : void 0;
+		const block = field && blockForRow(scope.config, field, row);
+		if (!field) return;
 		if (!block) {
-			scope.problems.push(`${scope.pointer}/${String(index)}: ${refusedSlug(slug)}. Allowed: ${blockSlugsOf(field).join(", ")}`);
+			scope.problems.push(`${scope.pointer}/${String(index)}: ${refusedSlug(propOf(row, "blockType"))}. Allowed: ${blockSlugsOf(field).join(", ")}`);
 			return;
 		}
 		checkValue({
@@ -177,50 +175,40 @@ const checkLeafValue = (scope, descriptor, value) => {
 };
 const checkValue = (scope, value) => {
 	if (!isPlainObject(value)) return;
-	const prefixParts = scope.prefix;
-	const relative = descriptorsUnder(scope.fields, prefixParts);
+	const relative = descriptorsUnder(scope.fields, scope.prefix);
 	for (const [key, entry] of Object.entries(value)) {
 		if (ROW_KEYS.has(key)) continue;
-		const candidates = relative.filter(({ parts }) => parts[0] === key);
 		const pointer = `${scope.pointer}/${key}`;
-		if (candidates.length === 0) {
-			scope.problems.push(`${pointer}: no such field. Available: ${[...new Set(relative.map(({ parts }) => parts[0]))].join(", ")}`);
-			continue;
-		}
-		const exact = candidates.find(({ parts }) => parts.length === 1);
-		if (exact) {
-			checkLeafValue({
-				...scope,
-				pointer
-			}, exact.descriptor, entry);
-			continue;
-		}
-		if (candidates.some(({ parts }) => parts[1] === "*")) {
-			if (!Array.isArray(entry)) {
-				scope.problems.push(`${pointer}: expected an array.`);
-				continue;
-			}
-			entry.forEach((row, index) => {
-				checkValue({
+		const found = classifyKey(relative, scope.prefix, key);
+		switch (found.kind) {
+			case "none":
+				scope.problems.push(`${pointer}: no such field. Available: ${[...new Set(relative.map(({ parts }) => parts[0]))].join(", ")}`);
+				break;
+			case "leaf":
+				checkLeafValue({
 					...scope,
-					pointer: `${pointer}/${String(index)}`,
-					prefix: [
-						...prefixParts,
-						key,
-						"*"
-					]
-				}, row);
-			});
-			continue;
+					pointer
+				}, found.descriptor, entry);
+				break;
+			case "rows":
+				if (Array.isArray(entry)) entry.forEach((row, index) => {
+					checkValue({
+						...scope,
+						pointer: `${pointer}/${String(index)}`,
+						prefix: found.prefix
+					}, row);
+				});
+				else scope.problems.push(`${pointer}: expected an array.`);
+				break;
+			case "group": checkValue({
+				...scope,
+				pointer,
+				prefix: found.prefix
+			}, entry);
 		}
-		checkValue({
-			...scope,
-			pointer,
-			prefix: [...prefixParts, key]
-		}, entry);
 	}
 };
-/** Shape problems with a value about to be written at a resolved pointer. */ const validateWriteValue = (config, target, value) => {
+const validateWriteValue = (config, target, value) => {
 	const problems = [];
 	const scope = {
 		config,

package/dist/schema/walk.mjs

@@ -1,3 +1,5 @@
+import { propOf } from "../guards.mjs";
+import { SchemaError } from "./errors.mjs";
 import { allowedNodeTypes, nodeOptions } from "./lexical.mjs";
 import { joinPath, splitPath } from "./path.mjs";
 import { translateAny } from "../i18n.mjs";
@@ -10,12 +12,17 @@ const RESERVED_FIELD_NAMES = /* @__PURE__ */ new Set([
 	"id",
 	"updatedAt"
 ]);
-/** The keys a row carries beside its fields. */ const ROW_KEYS = /* @__PURE__ */ new Set([
+/**
+* The keys a row carries beside its fields.
+*/ const ROW_KEYS = /* @__PURE__ */ new Set([
 	"blockName",
 	"blockType",
 	"id"
 ]);
-/** On a flattened field, whichever of `blockReferences` and `blocks` was declared. */ const blockSlugsOf = (field) => [...new Set((field.blockReferences ?? field.blocks).map((block) => typeof block === "string" ? block : block.slug))];
+/**
+* On a flattened field, whichever of `blockReferences` and `blocks` was
+* declared.
+*/ const blockSlugsOf = (field) => [...new Set((field.blockReferences ?? field.blocks).map((block) => typeof block === "string" ? block : block.slug))];
 /**
 * An inlined definition wins over the registry (`config.blocks`). A block's own
 * fields are identical wherever it appears, but the blocks its children accept
@@ -29,9 +36,17 @@ const RESERVED_FIELD_NAMES = /* @__PURE__ */ new Set([
 /**
 * Payload's `fieldIsHiddenOrDisabled` reads `hidden` and `admin.disabled`, not
 * `admin.hidden`, which its own upload base fields carry.
-*/ const isAdminHidden = (field) => "admin" in field && field.admin.hidden === true;
-const isSkipped = (field) => !("name" in field) || field.type === "join" || RESERVED_FIELD_NAMES.has(field.name) || fieldIsVirtual(field) || isAdminHidden(field) || fieldIsHiddenOrDisabled(field);
-const isReadOnly = (field) => "admin" in field && field.admin.readOnly === true;
+*/ const adminFlag = (field, key) => "admin" in field && field.admin[key] === true;
+const blockForRow = (config, field, row) => {
+	const slug = propOf(row, "blockType");
+	return typeof slug === "string" ? blockOf(config, field, slug) : void 0;
+};
+const requireBlock = (config, field, slug, at) => {
+	const block = blockOf(config, field, slug);
+	if (!block) throw new SchemaError(`"${slug}" is not allowed at "${at}". Allowed: ${blockSlugsOf(field).join(", ")}`);
+	return block;
+};
+const isSkipped = (field) => !("name" in field) || field.type === "join" || RESERVED_FIELD_NAMES.has(field.name) || fieldIsVirtual(field) || adminFlag(field, "hidden") || fieldIsHiddenOrDisabled(field);
 const describeBase = (field, { path, readOnly, translate }) => {
 	const description = translate("admin" in field ? field.admin.description : void 0);
 	return {
@@ -66,17 +81,11 @@ const withRows = (descriptor, field) => ({
 });
 const isContainer = (descriptor) => descriptor.type === "array" || descriptor.type === "group" || descriptor.type === "tab";
 const isInformative = (descriptor) => descriptor.description !== void 0 || descriptor.required === true || descriptor.localized === true;
-/**
-* Named tabs, groups and arrays add a path segment and are described
-* themselves only when they declare something of their own: an array always,
-* since its row counts live nowhere else. The walk stops at every blocks field
-* and names the slugs, so a node's size follows the number of blocks it
-* allows, not their definitions. Omitting `translate` costs language
-* selection, never the description itself.
-*/ const describeFields = (fields, translate = translateAny) => {
+const describedByFields = /* @__PURE__ */ new WeakMap();
+const describeWith = (fields, translate) => {
 	const walk = (current, prefix, parentReadOnly) => current.flatMap((field) => {
 		if (isSkipped(field)) return [];
-		const readOnly = parentReadOnly || isReadOnly(field);
+		const readOnly = parentReadOnly || adminFlag(field, "readOnly");
 		const path = [...prefix, field.name];
 		const at = {
 			path: joinPath(path),
@@ -97,11 +106,30 @@ const isInformative = (descriptor) => descriptor.description !== void 0 || descr
 	return walk(fields, [], false);
 };
 /**
+* Named tabs, groups and arrays add a path segment and are described
+* themselves only when they declare something of their own: an array always,
+* since its row counts live nowhere else. The walk stops at every blocks field
+* and names the slugs, so a node's size follows the number of blocks it
+* allows, not their definitions. Omitting `translate` costs language
+* selection, never the description itself.
+*/ const describeFields = (fields, translate = translateAny) => {
+	if (translate !== translateAny) return describeWith(fields, translate);
+	let described = describedByFields.get(fields);
+	if (!described) {
+		described = describeWith(fields, translate);
+		describedByFields.set(fields, described);
+	}
+	return described;
+};
+/**
 * The descriptors that address a value, which every walk resolving a path
 * against a document needs. Containers are left out, since only
 * {@link nodeDescriber} reports one.
 */ const describeAddressableFields = (fields) => describeFields(fields).filter((descriptor) => !isContainer(descriptor));
-/** The addressable descriptors under `prefix`, with their paths split relative to it. */ const descriptorsUnder = (fields, prefix) => describeAddressableFields(fields).flatMap((descriptor) => {
+/**
+* The addressable descriptors under `prefix`, with their paths split relative
+* to it.
+*/ const descriptorsUnder = (fields, prefix) => describeAddressableFields(fields).flatMap((descriptor) => {
 	const parts = splitPath(descriptor.path);
 	return prefix.every((part, offset) => part === parts[offset]) ? [{
 		descriptor,
@@ -116,11 +144,30 @@ const findFieldAt = (fields, path, type) => {
 		if (field.type === "array" && path[1] === "*") return findFieldAt(field.flattenedFields, path.slice(2), type);
 	}
 };
-const findBlocksField = (fields, path) => findFieldAt(fields, path, "blocks");
-/**
-* Locates the rich text field a resolved descriptor path refers to, so its
-* editor can be introspected for the fields its nodes carry.
-*/ const findRichTextField = (fields, path) => findFieldAt(fields, path, "richText");
+const longestMatch = (descriptors, segments, eq) => descriptors.map((descriptor) => ({
+	descriptor,
+	parts: splitPath(descriptor.path)
+})).filter(({ parts }) => parts.every((part, offset) => eq(part, segments[offset]))).sort((left, right) => right.parts.length - left.parts.length)[0];
+const classifyKey = (relative, prefix, key) => {
+	const candidates = relative.filter(({ parts }) => parts[0] === key);
+	const exact = candidates.find(({ parts }) => parts.length === 1);
+	if (exact) return {
+		descriptor: exact.descriptor,
+		kind: "leaf"
+	};
+	if (candidates.length === 0) return { kind: "none" };
+	return candidates.some(({ parts }) => parts[1] === "*") ? {
+		kind: "rows",
+		prefix: [
+			...prefix,
+			key,
+			"*"
+		]
+	} : {
+		kind: "group",
+		prefix: [...prefix, key]
+	};
+};
 /**
 * Looks up the sanitized config for a collection or global as an
 * {@link EntitySchema}. Throws on an unknown slug instead of returning
@@ -132,4 +179,4 @@ const findBlocksField = (fields, path) => findFieldAt(fields, path, "blocks");
 	return found;
 };
 //#endregion
-export { RESERVED_FIELD_NAMES, ROW_KEYS, blockOf, blockSlugsOf, describeAddressableFields, describeFields, descriptorsUnder, findBlocksField, findRichTextField, isAdminHidden, schemaOf };
+export { RESERVED_FIELD_NAMES, ROW_KEYS, adminFlag, blockForRow, blockOf, blockSlugsOf, classifyKey, describeAddressableFields, describeFields, descriptorsUnder, findFieldAt, longestMatch, requireBlock, schemaOf };

package/dist/tools/builtin.mjs

@@ -1,11 +1,14 @@
 import { createDocument } from "./create-document.mjs";
+import { deleteDocument } from "./delete-document.mjs";
 import { describeSchema } from "./describe-schema.mjs";
+import { duplicateDocument } from "./duplicate-document.mjs";
 import { findDocuments } from "./find-documents.mjs";
 import { findVersions } from "./find-versions.mjs";
 import { getDocument } from "./get-document.mjs";
 import { listCapabilities } from "./list-capabilities.mjs";
 import { patchDocument } from "./patch-document.mjs";
 import { publishDocument } from "./publish-document.mjs";
+import { createRunConfirmed } from "./run-confirmed.mjs";
 import { validateDocument } from "./validate-document.mjs";
 //#region src/tools/builtin.ts
 /**
@@ -21,8 +24,11 @@ import { validateDocument } from "./validate-document.mjs";
 	findVersions,
 	patchDocument,
 	createDocument,
+	duplicateDocument,
 	validateDocument,
-	publishDocument
+	publishDocument,
+	deleteDocument,
+	createRunConfirmed(() => BUILTIN_TOOLS)
 ];
 //#endregion
 export { BUILTIN_TOOLS };