@abinnovision/payloadcms-mcpx 1.0.0-beta.9 → 1.0.0

package/dist/schema/lexical-pointer.mjs

@@ -0,0 +1,125 @@
+import { lexicalSubSchema, subSchemaNodeTypes } from "./lexical.mjs";
+import { blockOf, blockSlugsOf, isIndexSegment, isPlainObject, joinPath } from "./walk.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 { 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(", ")}`);
+	const data = node?.["fields"];
+	if (sub.kind === "fields") return {
+		data,
+		fields: sub.fields,
+		kind: "fields",
+		rest
+	};
+	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(", ")}`);
+	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(", ")}`);
+	return {
+		blockType: slug,
+		data,
+		fields: block.flattenedFields,
+		kind: "fields",
+		rest
+	};
+};
+/**
+* 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.
+*/ 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.`);
+	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.`);
+	let node = state["root"];
+	let nodeType = "root";
+	let segments = rest;
+	let walked = ["root"];
+	for (;;) {
+		if (segments.length === 0) return {
+			kind: "position",
+			position: {
+				...base,
+				...nodeType === "root" ? { isRoot: true } : {},
+				kind: "node",
+				nodeType
+			}
+		};
+		const [segment, ...remaining] = segments;
+		if (segment === "children") {
+			if (remaining.length === 0) return {
+				kind: "position",
+				position: {
+					...base,
+					...nodeType === "root" ? { isRoot: true } : {},
+					kind: "nodes",
+					nodeType
+				}
+			};
+			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.`);
+			const children = node?.["children"];
+			const child = Array.isArray(children) && index !== "-" ? children[Number(index)] : void 0;
+			const type = isPlainObject(child) ? child["type"] : addedValue?.type;
+			if (typeof type !== "string") {
+				if (beyond.length === 0) return {
+					kind: "position",
+					position: {
+						...base,
+						kind: "node"
+					}
+				};
+				throw new Error(`Cannot tell which node "${descriptor.path}${joinPath([
+					...walked,
+					"children",
+					index
+				])}" is. Call getDocument with "outline" for the pointer of each node, or address an existing position.`);
+			}
+			node = isPlainObject(child) ? child : void 0;
+			nodeType = type;
+			segments = beyond;
+			walked = [
+				...walked,
+				"children",
+				index
+			];
+			continue;
+		}
+		if (segment === "fields") return stepIntoFields({
+			addedValue,
+			config,
+			field,
+			node,
+			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.`);
+		return {
+			kind: "position",
+			position: {
+				...base,
+				...nodeType === "root" ? { isRoot: true } : {},
+				kind: "property",
+				nodeType,
+				property: segment
+			}
+		};
+	}
+};
+//#endregion
+export { resolveLexicalPointer };

package/dist/schema/lexical.mjs

@@ -1,8 +1,6 @@
 import { flattenAllFields } from "payload";
 //#region src/schema/lexical.ts
 /**
-* Node types Lexical registers itself.
-*
 * `editorConfig.features.nodes` lists only what a feature contributed, so a
 * field whose editor enables nothing but text formatting reports none at all.
 */ const LEXICAL_CORE_NODES = [
@@ -13,26 +11,17 @@ import { flattenAllFields } from "payload";
 	"tab"
 ];
 /**
-* Node types whose sub-fields exist but cannot be addressed by a schema path.
-*
-* Asked without a node, `upload` answers with every enabled collection's
-* upload fields concatenated, so the result describes no single position. It
-* would need addressing by `relationTo` to mean anything.
+* Sub-fields exist but cannot be addressed by a schema path. Asked without a
+* node, `upload` answers with every enabled collection's upload fields
+* concatenated, so the result describes no single position.
 */ const OPAQUE_NODE_TYPES = /* @__PURE__ */ new Set(["upload"]);
 /**
-* Sub-schemas per rich text field, keyed by node type. `null` records a node
-* type that was asked and has nothing to describe, so it is asked only once.
-*
-* Worth caching because the describe and validate paths resolve the same field
-* repeatedly, and because the block features build their answer from scratch on
-* every call. Keyed weakly on the sanitized field, which lives as long as the
-* config does.
+* `null` records a node type that was asked and has nothing to describe, so it
+* is asked only once. Worth caching because describe and validate resolve the
+* same field repeatedly and the block features rebuild their answer every call.
 */ const subSchemaCache = /* @__PURE__ */ new WeakMap();
 const featuresOf = (field) => field.editor?.editorConfig?.features;
-/**
-* Node types a rich text field accepts. Editors other than Lexical report
-* only the core nodes.
-*/ const allowedNodeTypes = (field) => {
+/** Editors other than Lexical report only the core nodes. */ const allowedNodeTypes = (field) => {
 	const registered = (featuresOf(field)?.nodes ?? []).flatMap((entry) => {
 		const type = entry.node?.getType?.();
 		return type ? [type] : [];
@@ -53,10 +42,7 @@ const resolveSubSchema = (field, nodeType) => {
 		kind: "fields"
 	};
 };
-/**
-* The sub-schema behind one node type of a rich text field, or `undefined`
-* when that node carries no addressable fields.
-*/ const lexicalSubSchema = (field, nodeType) => {
+const lexicalSubSchema = (field, nodeType) => {
 	let cached = subSchemaCache.get(field);
 	if (!cached) {
 		cached = /* @__PURE__ */ new Map();
@@ -65,13 +51,195 @@ const resolveSubSchema = (field, nodeType) => {
 	if (!cached.has(nodeType)) cached.set(nodeType, resolveSubSchema(field, nodeType));
 	return cached.get(nodeType) ?? void 0;
 };
+/** In the order their features registered them. */ const subSchemaNodeTypes = (field) => [...featuresOf(field)?.getSubFields?.keys() ?? []].filter((nodeType) => lexicalSubSchema(field, nodeType) !== void 0);
+/**
+* `direction` carries Payload's own declaration for it, `oneOf` the two
+* directions or null, rather than a looser "string or null".
+*/ const KINDS = {
+	array: {
+		accepts: (value) => Array.isArray(value),
+		needs: "an array"
+	},
+	direction: {
+		accepts: (value) => value === null || value === "ltr" || value === "rtl",
+		needs: "\"ltr\", \"rtl\" or null"
+	},
+	number: {
+		accepts: (value) => typeof value === "number",
+		needs: "a number"
+	},
+	object: {
+		accepts: (value) => typeof value === "object" && value !== null && !Array.isArray(value),
+		needs: "an object"
+	},
+	optionalObject: {
+		accepts: (value) => value === null || typeof value === "object" && !Array.isArray(value),
+		needs: "an object or null"
+	},
+	string: {
+		accepts: (value) => typeof value === "string",
+		needs: "a string"
+	}
+};
+const accepts = (constraint, value) => typeof constraint === "string" ? KINDS[constraint].accepts(value) : value === constraint.is;
+const needs = (constraint) => typeof constraint === "string" ? KINDS[constraint].needs : JSON.stringify(constraint.is);
+const ELEMENT_PROPERTIES = {
+	children: "array",
+	direction: "direction",
+	indent: "number"
+};
+/** A text node and everything built on one. */ const TEXT_PROPERTIES = {
+	detail: "number",
+	format: "number",
+	mode: "string",
+	style: "string",
+	text: "string"
+};
+/**
+* Carried by every node, whatever its type.
+*
+* Aligned with Payload rather than measured: its `outputSchema` declares `type`
+* and `version` required for every node in the tree, and that declaration is
+* what types the field in `payload-types.ts`. Lexical itself hydrates a node
+* without a `version`, or with the wrong kind of one, unchanged - but a
+* consumer reading the document through the generated types has been promised
+* an integer, and `BlockNode.importJSON` migrates on it.
+*/ const UNIVERSAL_PROPERTIES = { version: "number" };
+/**
+* The root, as Payload declares it and as an editor exports it: these six
+* properties, these kinds, and nothing else.
+*/ const ROOT_PROPERTIES = {
+	children: "array",
+	direction: "direction",
+	format: "string",
+	indent: "number",
+	type: "string",
+	version: "number"
+};
 /**
-* Node types of a rich text field that have a sub-schema, in the order their
-* features registered them.
-*/ const subSchemaNodeTypes = (field) => [...featuresOf(field)?.getSubFields?.keys() ?? []].filter((nodeType) => lexicalSubSchema(field, nodeType) !== void 0);
+* What a serialized node must carry beyond {@link UNIVERSAL_PROPERTIES}, keyed
+* by node type.
+*
+* Payload stores an editor state without hydrating it, so a node written
+* without these, or with the wrong kind of value, is accepted and only fails
+* later, in the admin editor. Payload declares nothing per node type, so this
+* table is measured instead: an entry belongs here only if breaking it makes
+* Lexical throw, or changes what the editor reads back. An element's `format`
+* and a paragraph's text defaults are absent for that reason.
+* `lexical.spec.ts` holds every entry to the rule against the node classes
+* `@payloadcms/richtext-lexical` ships, so extend that test first.
+*
+* A node type with no entry is checked for the universal properties only.
+* Guessing at the requirements of a project's own nodes would reject content
+* that works.
+*/ const REQUIRED_NODE_PROPERTIES = {
+	autolink: {
+		...ELEMENT_PROPERTIES,
+		fields: "object"
+	},
+	block: { fields: "object" },
+	heading: {
+		...ELEMENT_PROPERTIES,
+		tag: "string"
+	},
+	inlineBlock: { fields: "object" },
+	link: {
+		...ELEMENT_PROPERTIES,
+		fields: "object"
+	},
+	list: {
+		...ELEMENT_PROPERTIES,
+		listType: "string",
+		start: "number"
+	},
+	listitem: {
+		...ELEMENT_PROPERTIES,
+		value: "number"
+	},
+	paragraph: ELEMENT_PROPERTIES,
+	quote: ELEMENT_PROPERTIES,
+	relationship: {
+		relationTo: "string",
+		value: "number"
+	},
+	tab: {
+		...TEXT_PROPERTIES,
+		detail: { is: 2 },
+		text: { is: "	" }
+	},
+	text: TEXT_PROPERTIES,
+	upload: {
+		fields: "optionalObject",
+		relationTo: "string",
+		value: "number"
+	}
+};
+/**
+* Whether the table already says what a node type's `fields` has to be, so the
+* sub-field walk does not report the same problem a second time.
+*/ const constrainsFields = (type) => "fields" in (REQUIRED_NODE_PROPERTIES[type] ?? {});
+const describeConstraints = (constraints) => Object.fromEntries(Object.entries(constraints).map(([property, constraint]) => [property, needs(constraint)]).sort((left, right) => left[0].localeCompare(right[0])));
+/**
+* What each of the given node types has to carry, phrased the way the write
+* side phrases it when it refuses one, so the listing and the error message
+* never disagree. Read straight off the tables above, which is what keeps it
+* true: nothing here is stated a second time.
+*
+* Keyed by node type rather than reported per field, because that is what it
+* depends on. A field says which types it allows, in its `nodes`; what a `text`
+* node has to carry is the same wherever one is written, so a response that
+* describes twenty rich text fields still states it once.
+*
+* `type` is listed although {@link UNIVERSAL_PROPERTIES} omits it. The
+* validator never reports it missing, because a node's `type` is how it finds
+* the entry to check against, but a client assembling a node from this listing
+* still has to write one.
+*/ const nodePropertiesFor = (types) => Object.fromEntries([...new Set(types)].sort().map((type) => [type, describeConstraints(type === "root" ? ROOT_PROPERTIES : {
+	...REQUIRED_NODE_PROPERTIES[type],
+	...UNIVERSAL_PROPERTIES,
+	type: "string"
+})]));
+/** Present but `null` counts as present: `direction` is serialized that way. */ const check = (node, constraints) => {
+	const problems = {
+		missing: [],
+		rejected: []
+	};
+	for (const [property, constraint] of Object.entries(constraints)) if (!(property in node)) problems.missing.push(property);
+	else if (!accepts(constraint, node[property])) problems.rejected.push({
+		needs: needs(constraint),
+		property
+	});
+	problems.missing.sort();
+	problems.rejected.sort((left, right) => left.property.localeCompare(right.property));
+	return problems;
+};
+const nodeProblems = (node) => check(node, {
+	...UNIVERSAL_PROPERTIES,
+	...REQUIRED_NODE_PROPERTIES[node["type"]] ?? {}
+});
 /**
-* Node properties worth reporting and enforcing.
+* The root is the one node Payload describes itself, down to refusing an
+* unknown property, so it is checked against that description rather than
+* against the walk's table.
+*/ const rootProblems = (root) => ({
+	...check(root, ROOT_PROPERTIES),
+	unexpected: Object.keys(root).filter((property) => !(property in ROOT_PROPERTIES))
+});
+/**
+* What one serialized property has to be, for a write addressing a property
+* rather than a whole node.
 *
+* Absent where the table says nothing, which is the same tolerance the node
+* walk shows: a project's own node may carry any property, and guessing at one
+* would reject content that works.
+*/ const propertyProblem = (nodeType, property, value) => {
+	const constraint = (nodeType === "root" ? ROOT_PROPERTIES : {
+		...UNIVERSAL_PROPERTIES,
+		...REQUIRED_NODE_PROPERTIES[nodeType] ?? {}
+	})[property];
+	return constraint === void 0 || accepts(constraint, value) ? void 0 : { needs: needs(constraint) };
+};
+/**
 * Only properties a feature narrows and Lexical does not check on its own
 * belong here. Everything else a feature restricts is already visible: a
 * link's targets through its sub-schema, a block node's choices through the
@@ -114,4 +282,4 @@ const stringList = (value) => Array.isArray(value) && value.every((entry) => typ
 	return entries.length > 0 ? Object.fromEntries(entries) : void 0;
 };
 //#endregion
-export { allowedNodeTypes, lexicalSubSchema, nodeOptions, subSchemaNodeTypes };
+export { REQUIRED_NODE_PROPERTIES, ROOT_PROPERTIES, allowedNodeTypes, constrainsFields, lexicalSubSchema, nodeOptions, nodeProblems, nodePropertiesFor, propertyProblem, rootProblems, subSchemaNodeTypes };

package/dist/schema/outline.mjs

@@ -0,0 +1,67 @@
+import { allowedNodeTypes, nodeOptions } from "./lexical.mjs";
+import { isPlainObject } from "./walk.mjs";
+//#region src/schema/outline.ts
+/**
+* Long enough to identify a paragraph, short enough that an outline of a real
+* document stays a fraction of the size of its editor state.
+*/ const TEXT_PREVIEW_LENGTH = 80;
+/**
+* Every descendant text node contributes, not only direct children, since a
+* link or a formatting mark nests the text a level deeper.
+*/ const collectText = (node) => {
+	if (node["type"] === "text") return typeof node["text"] === "string" ? node["text"] : "";
+	const children = node["children"];
+	return Array.isArray(children) ? children.filter(isPlainObject).map((child) => collectText(child)).join("") : "";
+};
+const preview = (text) => text.length > TEXT_PREVIEW_LENGTH ? `${text.slice(0, TEXT_PREVIEW_LENGTH)}…` : text;
+/**
+* Only the properties a feature actually narrows for this node type, and only
+* where the node carries a string for one. A node missing the property, or
+* carrying something the feature never produces, says nothing worth reporting.
+*/ const narrowedOptions = (node, narrowed) => {
+	if (!narrowed) return;
+	const set = Object.keys(narrowed).flatMap((property) => {
+		const value = node[property];
+		return typeof value === "string" ? [[property, value]] : [];
+	});
+	return set.length > 0 ? Object.fromEntries(set) : void 0;
+};
+const walk = (node, pointer, options, entries) => {
+	const type = node["type"];
+	if (typeof type !== "string") return;
+	const version = node["version"];
+	const text = preview(collectText(node));
+	const nodeOptionsFound = narrowedOptions(node, options?.[type]);
+	const children = node["children"];
+	const childCount = Array.isArray(children) ? children.length : 0;
+	entries.push({
+		...childCount === 0 ? {} : { children: childCount },
+		...nodeOptionsFound === void 0 ? {} : { options: nodeOptionsFound },
+		pointer,
+		...text === "" ? {} : { text },
+		type,
+		...typeof version === "number" ? { version } : {}
+	});
+	if (Array.isArray(children)) children.forEach((child, index) => {
+		if (isPlainObject(child)) walk(child, `${pointer}/children/${String(index)}`, options, entries);
+	});
+};
+/**
+* A depth-first listing of every node under an editor state's root, so an
+* agent can find a position and a sibling's `version` without reading the
+* whole state. `basePointer` is the field's own pointer, e.g. "/content"; each
+* 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 options = nodeOptions(field, allowedNodeTypes(field));
+	const entries = [];
+	root["children"].forEach((child, index) => {
+		if (isPlainObject(child)) walk(child, `${basePointer}/root/children/${String(index)}`, options, entries);
+	});
+	return entries;
+};
+//#endregion
+export { lexicalOutline };

package/dist/schema/pointer.mjs

@@ -1,6 +1,6 @@
-import { blockOf, blockSlugsOf, describeAddressableFields, findBlocksField, joinPath, splitPath, targetOf } from "./walk.mjs";
+import { blockOf, blockSlugsOf, describeAddressableFields, findBlocksField, findRichTextField, isIndexSegment, joinPath, splitPath, targetOf } from "./walk.mjs";
+import { resolveLexicalPointer } from "./lexical-pointer.mjs";
 //#region src/schema/pointer.ts
-const isIndexSegment = (segment) => segment === "-" || /^\d+$/.test(segment);
 const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isIndexSegment(segment) : part === segment);
 /**
 * Longest descriptor whose path is fully consumed by the leading segments.
@@ -9,10 +9,7 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isI
 	descriptor,
 	parts: splitPath(descriptor.path)
 })).filter(({ parts }) => parts.every((part, offset) => partMatches(part, segments[offset]))).sort((left, right) => right.consumed - left.consumed)[0];
-/**
-* Whether the segments stop part-way through some descriptor's path, which
-* means they address a subtree rather than a field.
-*/ const isSubtreePrefix = (descriptors, segments) => descriptors.some((descriptor) => {
+/** Stopping part-way through a descriptor's path means a subtree, not a field. */ const isSubtreePrefix = (descriptors, segments) => descriptors.some((descriptor) => {
 	const parts = splitPath(descriptor.path);
 	return parts.length > segments.length && segments.every((segment, offset) => {
 		const part = parts[offset];
@@ -20,15 +17,33 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isI
 	});
 });
 /**
-* Reads the value the given pointer segments address. Unlike a descriptor
-* path, the segments carry real indices, so intervening array fields are
-* descended through rather than skipped.
+* Unlike a descriptor path, the segments carry real indices, so intervening
+* array fields are descended through rather than skipped.
 */ const valueAtSegments = (data, segments) => segments.reduce((current, segment) => current === null || typeof current !== "object" ? void 0 : current[segment], data);
 /**
-* Resolves a JSON Pointer against the schema, using the stored document to
-* choose a branch at every blocks element.
-*
-* The document is required rather than optional: `/layout/sections/3/modules/1`
+* The stored row decides which block sits at an index, since a blocks field
+* admits many shapes at the same position. A row the document does not have
+* yet takes its slug from the value being added.
+*/ const stepIntoBlock = (at) => {
+	const { addedValue, config, descriptor, rows } = at;
+	const [index, ...remaining] = at.rest;
+	if (!isIndexSegment(index)) throw new Error(`"${descriptor.path}" is an array; "${index}" is not an index.`);
+	const field = findBlocksField(at.fields, splitPath(descriptor.path));
+	const existing = Array.isArray(rows) && index !== "-" ? rows[Number(index)] : void 0;
+	const slug = existing?.blockType ?? addedValue?.blockType;
+	if (!field || slug === void 0) throw new Error(`Cannot tell which block "${descriptor.path}/${index}" is. Supply a "blockType" on the value, one of: ${field ? blockSlugsOf(field).join(", ") : ""}`);
+	const block = blockOf(config, field, slug);
+	if (!block) throw new Error(`"${slug}" is not allowed at "${descriptor.path}". Allowed: ${blockSlugsOf(field).join(", ")}`);
+	return {
+		blockType: slug,
+		data: existing,
+		fields: block.flattenedFields,
+		rest: remaining
+	};
+};
+/**
+* The stored document chooses the branch at every blocks element, and is
+* required rather than optional: `/layout/sections/3/modules/1`
 * can only be resolved by reading `blockType` off `sections[3]`, since a blocks
 * field admits many shapes at the same index.
 */ const resolveDataPointer = (config, target) => {
@@ -36,6 +51,8 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isI
 	let data = target.doc;
 	let blockType;
 	let segments = splitPath(target.pointer);
+	let readOnly;
+	let inLexical;
 	while (segments.length > 0) {
 		const descriptors = describeAddressableFields(fields);
 		const match = longestMatch(descriptors, segments);
@@ -43,7 +60,7 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isI
 			if (isSubtreePrefix(descriptors, segments)) return {
 				...blockType === void 0 ? {} : { blockType },
 				fields,
-				prefix: segments
+				prefix: segments.map((segment) => isIndexSegment(segment) ? "*" : segment)
 			};
 			throw new Error(`"${joinPath(segments)}" is not a field here. Available: ${descriptors.map((descriptor) => descriptor.path).join(", ")}`);
 		}
@@ -52,28 +69,58 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isI
 			...blockType === void 0 ? {} : { blockType },
 			descriptor: match.descriptor,
 			fields,
-			prefix: []
+			prefix: [],
+			...inLexical === void 0 ? {} : { inLexical },
+			...readOnly === void 0 ? {} : { readOnly }
 		};
+		if (match.descriptor.type === "richText") {
+			const field = findRichTextField(fields, splitPath(match.descriptor.path));
+			if (!field) throw new Error(`"${match.descriptor.path}" could not be resolved.`);
+			const step = resolveLexicalPointer({
+				...target.addedValue === void 0 ? {} : { addedValue: target.addedValue },
+				config,
+				descriptor: match.descriptor,
+				field,
+				segments: rest,
+				state: valueAtSegments(data, segments.slice(0, match.consumed))
+			});
+			if (step.kind === "position") return {
+				...blockType === void 0 ? {} : { blockType },
+				descriptor: match.descriptor,
+				fields,
+				lexical: step.position,
+				prefix: [],
+				...readOnly === void 0 ? {} : { readOnly }
+			};
+			inLexical = true;
+			readOnly = match.descriptor.readOnly ?? readOnly;
+			blockType = step.blockType;
+			fields = step.fields;
+			data = step.data;
+			segments = step.rest;
+			continue;
+		}
 		if (match.descriptor.type !== "blocks") throw new Error(`"${match.descriptor.path}" is a ${match.descriptor.type} field and has no "${joinPath(rest)}" beneath it.`);
-		const [index, ...remaining] = rest;
-		if (!isIndexSegment(index)) throw new Error(`"${match.descriptor.path}" is an array; "${index}" is not an index.`);
-		const parts = splitPath(match.descriptor.path);
-		const field = findBlocksField(fields, parts);
-		const rows = valueAtSegments(data, segments.slice(0, match.consumed));
-		const existing = Array.isArray(rows) && index !== "-" ? rows[Number(index)] : void 0;
-		const slug = existing?.blockType ?? target.addedValue?.blockType;
-		if (!field || slug === void 0) throw new Error(`Cannot tell which block "${match.descriptor.path}/${index}" is. Supply a "blockType" on the value, one of: ${field ? blockSlugsOf(field).join(", ") : ""}`);
-		const block = blockOf(config, field, slug);
-		if (!block) throw new Error(`"${slug}" is not allowed at "${match.descriptor.path}". Allowed: ${blockSlugsOf(field).join(", ")}`);
-		blockType = slug;
-		fields = block.flattenedFields;
-		data = existing;
-		segments = remaining;
+		const step = stepIntoBlock({
+			addedValue: target.addedValue,
+			descriptor: match.descriptor,
+			fields,
+			rest,
+			rows: valueAtSegments(data, segments.slice(0, match.consumed)),
+			config
+		});
+		readOnly = match.descriptor.readOnly ?? readOnly;
+		blockType = step.blockType;
+		fields = step.fields;
+		data = step.data;
+		segments = step.rest;
 	}
 	return {
 		...blockType === void 0 ? {} : { blockType },
 		fields,
-		prefix: []
+		...inLexical === void 0 ? {} : { inLexical },
+		prefix: [],
+		...readOnly === void 0 ? {} : { readOnly }
 	};
 };
 //#endregion