@harbour-enterprises/superdoc 1.17.0-next.11 → 1.17.0-next.13

package/dist/chunks/{src-DQKyE7kq.cjs → src-ByCDwKn7.cjs}

@@ -1,5 +1,5 @@
 const require_rolldown_runtime = require("./rolldown-runtime-Dp2H1eGw.cjs");
-const require_SuperConverter = require("./SuperConverter-DOQaFkjd.cjs");
+const require_SuperConverter = require("./SuperConverter-BgHHB-Z2.cjs");
 const require_jszip = require("./jszip-DCT9QYaK.cjs");
 const require_uuid = require("./uuid-CHj_rjgt.cjs");
 const require_constants = require("./constants-CpniKo9Z.cjs");
@@ -261,7 +261,7 @@ var DEFAULT_ENDPOINT = "https://ingest.superdoc.dev/v1/collect";
 const COMMUNITY_LICENSE_KEY = "community-and-eval-agplv3";
 function getSuperdocVersion() {
 	try {
-		return "1.17.0-next.11";
+		return "1.17.0-next.13";
 	} catch {
 		return "unknown";
 	}
@@ -20734,7 +20734,7 @@ const canUseDOM = () => {
 		return false;
 	}
 };
-var summaryVersion = "1.17.0-next.11";
+var summaryVersion = "1.17.0-next.13";
 var nodeKeys = [
 	"group",
 	"content",
@@ -21113,6 +21113,13 @@ const BLOCK_NODE_TYPES = [
 	"image",
 	"sdt"
 ];
+const DELETABLE_BLOCK_NODE_TYPES = [
+	"paragraph",
+	"heading",
+	"listItem",
+	"table",
+	"sdt"
+];
 const INLINE_NODE_TYPES = [
 	"run",
 	"bookmark",
@@ -21204,6 +21211,9 @@ var T_PLAN_ENGINE = [
 	"TARGET_MOVED",
 	"PLAN_CONFLICT_OVERLAP",
 	"INVALID_STEP_COMBINATION",
+	"REVISION_CHANGED_SINCE_COMPILE",
+	"INVALID_INSERTION_CONTEXT",
+	"DOCUMENT_IDENTITY_CONFLICT",
 	"CAPABILITY_UNAVAILABLE"
 ];
 var T_QUERY_MATCH = [
@@ -21305,6 +21315,27 @@ const OPERATION_DEFINITIONS = {
 		referenceDocPath: "delete.mdx",
 		referenceGroup: "core"
 	},
+	"blocks.delete": {
+		memberPath: "blocks.delete",
+		description: "Delete an entire block node (paragraph, heading, list item, table, image, or sdt) deterministically.",
+		requiresDocumentContext: true,
+		metadata: mutationOperation({
+			idempotency: "conditional",
+			supportsDryRun: true,
+			supportsTrackedMode: false,
+			possibleFailureCodes: NONE_FAILURES,
+			throws: [
+				"TARGET_NOT_FOUND",
+				"AMBIGUOUS_TARGET",
+				"CAPABILITY_UNAVAILABLE",
+				"INVALID_TARGET",
+				"INVALID_INPUT",
+				"INTERNAL_ERROR"
+			]
+		}),
+		referenceDocPath: "blocks/delete.mdx",
+		referenceGroup: "blocks"
+	},
 	"format.apply": {
 		memberPath: "format.apply",
 		description: "Apply explicit inline style changes (bold, italic, underline, strike) to the target range using boolean patch semantics.",
@@ -21879,6 +21910,7 @@ function ref$1(name) {
 }
 var nodeTypeValues = NODE_TYPES;
 var blockNodeTypeValues = BLOCK_NODE_TYPES;
+var deletableBlockNodeTypeValues = DELETABLE_BLOCK_NODE_TYPES;
 var inlineNodeTypeValues = INLINE_NODE_TYPES;
 var SHARED_DEFS = {
 	Range: objectSchema({
@@ -21938,6 +21970,15 @@ var SHARED_DEFS = {
 		"nodeType",
 		"nodeId"
 	]),
+	DeletableBlockNodeAddress: objectSchema({
+		kind: { const: "block" },
+		nodeType: { enum: [...deletableBlockNodeTypeValues] },
+		nodeId: { type: "string" }
+	}, [
+		"kind",
+		"nodeType",
+		"nodeId"
+	]),
 	ParagraphAddress: objectSchema({
 		kind: { const: "block" },
 		nodeType: { const: "paragraph" },
@@ -22105,6 +22146,7 @@ ref$1("TargetKind");
 var textAddressSchema = ref$1("TextAddress");
 var textTargetSchema = ref$1("TextTarget");
 var blockNodeAddressSchema = ref$1("BlockNodeAddress");
+var deletableBlockNodeAddressSchema = ref$1("DeletableBlockNodeAddress");
 var paragraphAddressSchema = ref$1("ParagraphAddress");
 var headingAddressSchema = ref$1("HeadingAddress");
 var listItemAddressSchema = ref$1("ListItemAddress");
@@ -22481,6 +22523,7 @@ var trackChangesListResultSchema = discoveryResultSchema(discoveryItemSchema({
 }, ["address", "type"]));
 var capabilityReasonsSchema = arraySchema({ enum: [
 	"COMMAND_UNAVAILABLE",
+	"HELPER_UNAVAILABLE",
 	"OPERATION_UNAVAILABLE",
 	"TRACKED_MODE_UNAVAILABLE",
 	"DRY_RUN_UNAVAILABLE",
@@ -22639,6 +22682,18 @@ var operationSchemas = {
 		success: textMutationSuccessSchema,
 		failure: textMutationFailureSchemaFor("format.align")
 	},
+	"blocks.delete": {
+		input: objectSchema({ target: deletableBlockNodeAddressSchema }, ["target"]),
+		output: objectSchema({
+			success: { const: true },
+			deleted: deletableBlockNodeAddressSchema
+		}, ["success", "deleted"]),
+		success: objectSchema({
+			success: { const: true },
+			deleted: deletableBlockNodeAddressSchema
+		}, ["success", "deleted"]),
+		failure: preApplyFailureResultSchemaFor("blocks.delete")
+	},
 	"create.paragraph": {
 		input: objectSchema({
 			at: { oneOf: [
@@ -22941,6 +22996,11 @@ var GROUP_METADATA = {
 		description: "Primary read and write operations.",
 		pagePath: "core/index.mdx"
 	},
+	blocks: {
+		title: "Blocks",
+		description: "Block-level structural operations.",
+		pagePath: "blocks/index.mdx"
+	},
 	capabilities: {
 		title: "Capabilities",
 		description: "Runtime support discovery for capability-aware branching.",
@@ -22989,6 +23049,7 @@ const REFERENCE_OPERATION_GROUPS = Object.keys(GROUP_METADATA).map((key$1) => ({
 }));
 const CAPABILITY_REASON_CODES = [
 	"COMMAND_UNAVAILABLE",
+	"HELPER_UNAVAILABLE",
 	"OPERATION_UNAVAILABLE",
 	"TRACKED_MODE_UNAVAILABLE",
 	"DRY_RUN_UNAVAILABLE",
@@ -23286,6 +23347,27 @@ function executeCreateHeading(adapter, input, options) {
 	validateCreateLocation(normalized.at, "create.heading");
 	return adapter.heading(normalized, normalizeMutationOptions(options));
 }
+var SUPPORTED_DELETE_NODE_TYPES = new Set(DELETABLE_BLOCK_NODE_TYPES);
+var REJECTED_DELETE_NODE_TYPES = new Set(["tableRow", "tableCell"]);
+function validateBlocksDeleteInput(input) {
+	if (!input || typeof input !== "object") throw new DocumentApiValidationError("INVALID_INPUT", "blocks.delete requires an input object.", { fields: ["input"] });
+	if (!input.target) throw new DocumentApiValidationError("INVALID_INPUT", "blocks.delete requires a target.", { fields: ["target"] });
+	if (input.target.kind !== "block") throw new DocumentApiValidationError("INVALID_INPUT", "blocks.delete target must have kind \"block\".", { fields: ["target.kind"] });
+	if (!input.target.nodeId || typeof input.target.nodeId !== "string") throw new DocumentApiValidationError("INVALID_INPUT", "blocks.delete target requires a nodeId string.", { fields: ["target.nodeId"] });
+	const { nodeType } = input.target;
+	if (REJECTED_DELETE_NODE_TYPES.has(nodeType)) throw new DocumentApiValidationError("INVALID_TARGET", `blocks.delete does not support "${nodeType}" targets. Table row/column operations are out of scope.`, {
+		fields: ["target.nodeType"],
+		nodeType
+	});
+	if (!SUPPORTED_DELETE_NODE_TYPES.has(nodeType)) throw new DocumentApiValidationError("INVALID_TARGET", `blocks.delete does not support "${nodeType}" targets.`, {
+		fields: ["target.nodeType"],
+		nodeType
+	});
+}
+function executeBlocksDelete(adapter, input, options) {
+	validateBlocksDeleteInput(input);
+	return adapter.delete(input, normalizeMutationOptions(options));
+}
 function executeTrackChangesList(adapter, input) {
 	return adapter.list(input);
 }
@@ -23329,6 +23411,7 @@ function buildDispatchTable(api) {
 		insert: (input, options) => api.insert(input, options),
 		replace: (input, options) => api.replace(input, options),
 		delete: (input, options) => api.delete(input, options),
+		"blocks.delete": (input, options) => api.blocks.delete(input, options),
 		"format.apply": (input, options) => api.format.apply(input, options),
 		"format.fontSize": (input, options) => api.format.fontSize(input, options),
 		"format.fontFamily": (input, options) => api.format.fontFamily(input, options),
@@ -23454,6 +23537,9 @@ function createDocumentApi(adapters) {
 				return executeTrackChangesDecide(adapters.trackChanges, input, options);
 			}
 		},
+		blocks: { delete(input, options) {
+			return executeBlocksDelete(adapters.blocks, input, options);
+		} },
 		create: {
 			paragraph(input, options) {
 				return executeCreateParagraph(adapters.create, input, options);
@@ -23538,6 +23624,7 @@ var REQUIRED_COMMANDS = {
 	"lists.outdent": ["setTextSelection", "decreaseListIndent"],
 	"lists.restart": ["setTextSelection", "restartNumbering"],
 	"lists.exit": ["exitListItemAt"],
+	"blocks.delete": ["deleteBlockNodeById"],
 	"comments.create": [
 		"addComment",
 		"setTextSelection",
@@ -23566,6 +23653,12 @@ function hasAllCommands(editor, operationId) {
 	if (!required || required.length === 0) return true;
 	return required.every((command$1) => hasCommand(editor, command$1));
 }
+var REQUIRED_HELPERS = { "blocks.delete": (editor) => typeof editor.helpers?.blockNode?.getBlockNodeById === "function" };
+function hasRequiredHelpers(editor, operationId) {
+	const check = REQUIRED_HELPERS[operationId];
+	if (!check) return true;
+	return check(editor);
+}
 function hasMarkCapability(editor, markName) {
 	return Boolean(editor.schema?.marks?.[markName]);
 }
@@ -23611,7 +23704,7 @@ function pushReason(reasons, reason) {
 function isOperationAvailable(editor, operationId) {
 	if (operationId === "format.apply") return MARK_KEYS.some((key$1) => hasMarkCapability(editor, STYLE_MARK_SCHEMA_NAMES[key$1] ?? key$1));
 	if (INLINE_FORMAT_OPERATIONS.has(operationId)) return hasAllCommands(editor, operationId) && hasMarkCapability(editor, "textStyle");
-	return hasAllCommands(editor, operationId);
+	return hasAllCommands(editor, operationId) && hasRequiredHelpers(editor, operationId);
 }
 function isCommandBackedAvailability(operationId) {
 	return !isMarkBackedOperation(operationId) && !INLINE_FORMAT_OPERATIONS.has(operationId);
@@ -23625,7 +23718,10 @@ function buildOperationCapabilities(editor) {
 		const dryRun = metadata.supportsDryRun && available;
 		const reasons = [];
 		if (!available) {
-			if (isCommandBackedAvailability(operationId)) pushReason(reasons, "COMMAND_UNAVAILABLE");
+			if (isCommandBackedAvailability(operationId)) {
+				if (!hasAllCommands(editor, operationId)) pushReason(reasons, "COMMAND_UNAVAILABLE");
+				if (!hasRequiredHelpers(editor, operationId)) pushReason(reasons, "HELPER_UNAVAILABLE");
+			}
 			pushReason(reasons, "OPERATION_UNAVAILABLE");
 		}
 		if (metadata.supportsTrackedMode && !tracked) pushReason(reasons, "TRACKED_MODE_UNAVAILABLE");
@@ -24115,13 +24211,21 @@ function buildBlockIndex(editor) {
 	});
 	return {
 		candidates,
-		byId
+		byId,
+		ambiguous
 	};
 }
 function findBlockById(index, address) {
 	if (address.kind !== "block") return void 0;
 	return index.byId.get(`${address.nodeType}:${address.nodeId}`);
 }
+function findBlockByIdStrict(index, address) {
+	const key$1 = `${address.nodeType}:${address.nodeId}`;
+	if (index.ambiguous.has(key$1)) throw new DocumentApiAdapterError("AMBIGUOUS_TARGET", `Multiple blocks share key "${key$1}".`, { target: address });
+	const candidate = index.byId.get(key$1);
+	if (!candidate) throw new DocumentApiAdapterError("TARGET_NOT_FOUND", `Block "${key$1}" was not found.`, { target: address });
+	return candidate;
+}
 function isTextBlockCandidate(candidate) {
 	const node = candidate.node;
 	return Boolean(node?.inlineContent || node?.isTextblock);
@@ -24207,9 +24311,11 @@ function trackRevisions(editor) {
 function checkRevision(editor, expectedRevision) {
 	if (expectedRevision === void 0) return;
 	const current = getRevision(editor);
-	if (expectedRevision !== current) throw new PlanError("REVISION_MISMATCH", `REVISION_MISMATCH — expected revision "${expectedRevision}" but document is at "${current}"`, void 0, {
+	if (expectedRevision !== current) throw new PlanError("REVISION_MISMATCH", `REVISION_MISMATCH — expected revision "${expectedRevision}" but document is at "${current}". Re-run query.match to obtain a fresh ref.`, void 0, {
 		expectedRevision,
-		currentRevision: current
+		currentRevision: current,
+		refStability: "ephemeral",
+		remediation: "Re-run query.match() to obtain a fresh ref valid for the current revision."
 	});
 }
 function resolveSegmentPosition(targetOffset, segmentStart, segmentLength, docFrom, docTo) {
@@ -24459,7 +24565,9 @@ function captureRunsInRange(editor, blockPos, from$1, to) {
 			return;
 		}
 		if (node.isLeaf) {
+			const start$1 = offset$1;
 			offset$1 += 1;
+			maybePushRun(start$1, offset$1, []);
 			return;
 		}
 		let isFirstChild = true;
@@ -24859,12 +24967,62 @@ function executeBlockSelector(index, query, diagnostics) {
 function isAssertStep(step) {
 	return step.op === "assert";
 }
+function isCreateOp(op) {
+	return op === "create.heading" || op === "create.paragraph";
+}
+var VALID_CREATE_POSITIONS = ["before", "after"];
 function isSelectWhere(where) {
 	return where.by === "select";
 }
 function isRefWhere(where) {
 	return where.by === "ref";
 }
+function validateCreateStepPosition(step) {
+	const args$1 = step.args;
+	if (args$1.position === void 0 || args$1.position === null) {
+		args$1.position = "after";
+		return;
+	}
+	if (!VALID_CREATE_POSITIONS.includes(args$1.position)) throw planError("INVALID_INPUT", `create step requires args.position to be 'before' or 'after'`, step.id, {
+		receivedPosition: args$1.position,
+		allowedValues: [...VALID_CREATE_POSITIONS],
+		default: "after"
+	});
+}
+function resolveCreateAnchorFromTargets(targets, position, stepId) {
+	const target = targets[0];
+	if (!target) throw planError("INVALID_INPUT", "create step has no resolved targets", stepId);
+	if (target.kind === "range") return target.blockId;
+	const segments = target.segments;
+	if (!segments.length) throw planError("INVALID_INPUT", "span target has no segments", stepId);
+	return position === "before" ? segments[0].blockId : segments[segments.length - 1].blockId;
+}
+function validateInsertionContext(editor, index, step, stepIndex, anchorBlockId, position) {
+	const candidate = index.candidates.find((c$3) => c$3.nodeId === anchorBlockId);
+	if (!candidate) return;
+	const paragraphType = editor.state.schema?.nodes?.paragraph;
+	if (!paragraphType) return;
+	const resolvedPos = editor.state.doc.resolve(candidate.pos);
+	const parent = resolvedPos.parent;
+	const anchorIndex = resolvedPos.index();
+	const insertionIndex = position === "before" ? anchorIndex : anchorIndex + 1;
+	if (!(typeof parent.canReplaceWith === "function" ? parent.canReplaceWith(insertionIndex, insertionIndex, paragraphType) : parent.type.contentMatch.matchType(paragraphType))) {
+		const allowedChildTypes = [];
+		const match$1 = parent.type.contentMatch;
+		for (const nodeType of Object.values(editor.state.schema.nodes)) if (match$1.matchType(nodeType)) allowedChildTypes.push(nodeType.name);
+		throw planError("INVALID_INSERTION_CONTEXT", `Cannot create ${step.op} inside ${parent.type.name}`, step.id, {
+			stepIndex,
+			stepId: step.id,
+			operation: step.op,
+			anchorBlockId,
+			parentType: parent.type.name,
+			allowedChildTypes,
+			insertionIndex,
+			requestedChildType: "paragraph",
+			requestedSemanticType: step.op === "create.heading" ? "heading" : "paragraph"
+		});
+	}
+}
 function isV3Ref(payload) {
 	return typeof payload === "object" && payload !== null && "v" in payload && payload.v === 3;
 }
@@ -25077,9 +25235,13 @@ function decodeTextRefPayload(encoded, stepId) {
 }
 function resolveV3TextRef(editor, index, step, refData) {
 	const currentRevision = getRevision(editor);
-	if (refData.rev !== currentRevision) throw planError("REVISION_MISMATCH", `text ref was created at revision "${refData.rev}" but document is at "${currentRevision}"`, step.id, {
+	if (refData.rev !== currentRevision) throw planError("REVISION_MISMATCH", `Text ref is ephemeral and revision-scoped. Re-run query.match to obtain a fresh handle.ref for revision ${currentRevision}.`, step.id, {
 		refRevision: refData.rev,
-		currentRevision
+		currentRevision,
+		refStability: "ephemeral",
+		refScope: refData.scope,
+		blockId: refData.segments?.[0]?.blockId,
+		remediation: `Re-run query.match() to obtain a fresh ref valid for the current revision.`
 	});
 	if (!refData.segments?.length) return [];
 	const segments = refData.segments.map((s) => ({
@@ -25178,7 +25340,11 @@ function resolveStepTargets(editor, index, step) {
 		return t.blockId !== prev.blockId || t.from !== prev.from || t.to !== prev.to;
 	});
 	if (refWhere) {
-		if (targets.length === 0) throw planError("MATCH_NOT_FOUND", `ref "${refWhere.ref}" did not resolve to any targets`, step.id);
+		if (targets.length === 0) throw planError("MATCH_NOT_FOUND", `ref "${refWhere.ref}" did not resolve to any targets`, step.id, {
+			selectorType: "ref",
+			selectorPattern: refWhere.ref,
+			candidateCount: 0
+		});
 		if (targets.length > 1) throw planError("AMBIGUOUS_MATCH", `ref "${refWhere.ref}" resolved to ${targets.length} targets`, step.id, { matchCount: targets.length });
 		return targets;
 	}
@@ -25187,57 +25353,157 @@ function resolveStepTargets(editor, index, step) {
 	if (selectWhere.require === "first" && targets.length > 1) targets = [targets[0]];
 	return targets;
 }
+function buildMatchNotFoundDetails(step) {
+	const where = step.where;
+	const select = "select" in where ? where.select : void 0;
+	const within$1 = "within" in where ? where.within : void 0;
+	return {
+		selectorType: select?.type ?? "unknown",
+		selectorPattern: select?.pattern ?? "",
+		selectorMode: select?.mode ?? "contains",
+		searchScope: within$1?.blockId ?? "document",
+		candidateCount: 0
+	};
+}
 function applyCardinalityCheck(step, targets) {
 	const where = step.where;
 	if (!("require" in where) || where.require === void 0) return;
 	const require$1 = where.require;
 	if (require$1 === "first") {
-		if (targets.length === 0) throw planError("MATCH_NOT_FOUND", "selector matched zero ranges", step.id);
+		if (targets.length === 0) throw planError("MATCH_NOT_FOUND", "selector matched zero ranges", step.id, buildMatchNotFoundDetails(step));
 	} else if (require$1 === "exactlyOne") {
-		if (targets.length === 0) throw planError("MATCH_NOT_FOUND", "selector matched zero ranges", step.id);
+		if (targets.length === 0) throw planError("MATCH_NOT_FOUND", "selector matched zero ranges", step.id, buildMatchNotFoundDetails(step));
 		if (targets.length > 1) throw planError("AMBIGUOUS_MATCH", `selector matched ${targets.length} ranges, expected exactly one`, step.id, { matchCount: targets.length });
 	} else if (require$1 === "all") {
-		if (targets.length === 0) throw planError("MATCH_NOT_FOUND", "selector matched zero ranges", step.id);
-	}
-}
-function detectOverlaps(steps) {
-	const rangesByBlock = /* @__PURE__ */ new Map();
-	for (const compiled of steps) for (const target of compiled.targets) if (target.kind === "range") addRange(rangesByBlock, target.blockId, target.stepId, target.from, target.to);
-	else for (const seg of target.segments) addRange(rangesByBlock, seg.blockId, target.stepId, seg.from, seg.to);
-	for (const [blockId, ranges] of rangesByBlock) {
-		ranges.sort((a, b$1) => a.from - b$1.from);
-		for (let i$1 = 1; i$1 < ranges.length; i$1++) {
-			const prev = ranges[i$1 - 1];
-			const curr = ranges[i$1];
-			if (prev.stepId !== curr.stepId && prev.to > curr.from) throw planError("PLAN_CONFLICT_OVERLAP", `steps "${prev.stepId}" and "${curr.stepId}" target overlapping ranges in block "${blockId}"`, curr.stepId, {
+		if (targets.length === 0) throw planError("MATCH_NOT_FOUND", "selector matched zero ranges", step.id, buildMatchNotFoundDetails(step));
+	}
+}
+const STEP_INTERACTION_MATRIX = new Map([
+	["text.rewrite::format.apply::same_target", "allow"],
+	["text.rewrite::text.rewrite::same_target", "reject"],
+	["text.rewrite::text.delete::overlapping", "reject"],
+	["text.rewrite::create.*::same_block", "allow"],
+	["text.rewrite::text.insert::same_target", "reject"],
+	["format.apply::format.apply::same_target", "allow"],
+	["format.apply::text.rewrite::same_target", "reject"],
+	["format.apply::text.delete::overlapping", "reject"],
+	["format.apply::create.*::same_block", "allow"],
+	["format.apply::text.insert::same_target", "allow"],
+	["text.delete::text.rewrite::overlapping", "reject"],
+	["text.delete::text.delete::overlapping", "reject"],
+	["text.delete::format.apply::overlapping", "reject"],
+	["text.delete::create.*::same_block", "allow"],
+	["text.delete::text.insert::overlapping", "reject"],
+	["create.*::text.rewrite::same_block", "allow"],
+	["create.*::format.apply::same_block", "allow"],
+	["create.*::text.delete::same_block", "allow"],
+	["create.*::create.*::same_block", "allow"],
+	["create.*::text.insert::same_block", "allow"],
+	["text.insert::format.apply::same_target", "allow"],
+	["text.insert::text.rewrite::same_target", "reject"],
+	["text.insert::text.delete::overlapping", "reject"],
+	["text.insert::create.*::same_block", "allow"],
+	["text.insert::text.insert::same_target", "reject"]
+]);
+const MATRIX_EXEMPT_OPS = new Set(["assert"]);
+function normalizeOpForMatrix(op) {
+	return op.startsWith("create.") ? "create.*" : op;
+}
+function classifyOverlap(stepA, stepB) {
+	const rangesA = extractBlockRanges(stepA);
+	const rangesB = extractBlockRanges(stepB);
+	const opA = normalizeOpForMatrix(stepA.step.op);
+	const opB = normalizeOpForMatrix(stepB.step.op);
+	const isCreateA = opA === "create.*";
+	const isCreateB = opB === "create.*";
+	for (const [blockId, aEntries] of rangesA) {
+		const bEntries = rangesB.get(blockId);
+		if (!bEntries) continue;
+		for (const a of aEntries) for (const b$1 of bEntries) {
+			if (isCreateA || isCreateB) return {
+				overlapClass: "same_block",
 				blockId,
-				rangeA: {
-					from: prev.from,
-					to: prev.to
-				},
-				rangeB: {
-					from: curr.from,
-					to: curr.to
-				}
-			});
+				rangeA: a,
+				rangeB: b$1
+			};
+			if (a.to <= b$1.from || b$1.to <= a.from) continue;
+			if (a.from === b$1.from && a.to === b$1.to) return {
+				overlapClass: "same_target",
+				blockId,
+				rangeA: a,
+				rangeB: b$1
+			};
+			return {
+				overlapClass: "overlapping",
+				blockId,
+				rangeA: a,
+				rangeB: b$1
+			};
 		}
 	}
 }
-function addRange(map$2, blockId, stepId, from$1, to) {
-	let blockRanges = map$2.get(blockId);
-	if (!blockRanges) {
-		blockRanges = [];
-		map$2.set(blockId, blockRanges);
+function extractBlockRanges(compiled) {
+	const result = /* @__PURE__ */ new Map();
+	for (const target of compiled.targets) if (target.kind === "range") pushBlockRange(result, target.blockId, target.from, target.to);
+	else for (const seg of target.segments) pushBlockRange(result, seg.blockId, seg.from, seg.to);
+	return result;
+}
+function pushBlockRange(map$2, blockId, from$1, to) {
+	let entries = map$2.get(blockId);
+	if (!entries) {
+		entries = [];
+		map$2.set(blockId, entries);
 	}
-	blockRanges.push({
-		stepId,
+	entries.push({
 		from: from$1,
 		to
 	});
 }
+function validateStepInteractions(steps) {
+	for (let i$1 = 0; i$1 < steps.length; i$1++) for (let j = i$1 + 1; j < steps.length; j++) {
+		const stepA = steps[i$1];
+		const stepB = steps[j];
+		if (MATRIX_EXEMPT_OPS.has(stepA.step.op) || MATRIX_EXEMPT_OPS.has(stepB.step.op)) continue;
+		const overlap = classifyOverlap(stepA, stepB);
+		if (!overlap) continue;
+		const matrixKey = `${normalizeOpForMatrix(stepA.step.op)}::${normalizeOpForMatrix(stepB.step.op)}::${overlap.overlapClass}`;
+		const verdict = STEP_INTERACTION_MATRIX.get(matrixKey) ?? "reject";
+		if (verdict === "reject") throw planError("PLAN_CONFLICT_OVERLAP", `steps "${stepA.step.id}" and "${stepB.step.id}" target overlapping ranges in block "${overlap.blockId}"`, stepB.step.id, {
+			blockId: overlap.blockId,
+			stepIdA: stepA.step.id,
+			stepIdB: stepB.step.id,
+			opKeyA: stepA.step.op,
+			opKeyB: stepB.step.op,
+			rangeA: overlap.rangeA,
+			rangeB: overlap.rangeB,
+			overlapRegion: {
+				from: Math.max(overlap.rangeA.from, overlap.rangeB.from),
+				to: Math.min(overlap.rangeA.to, overlap.rangeB.to)
+			},
+			matrixVerdict: verdict,
+			matrixKey
+		});
+	}
+}
+function assertNoDuplicateBlockIds(index) {
+	const seen = /* @__PURE__ */ new Map();
+	const duplicates = [];
+	for (const candidate of index.candidates) {
+		const count = seen.get(candidate.nodeId) ?? 0;
+		seen.set(candidate.nodeId, count + 1);
+		if (count === 1) duplicates.push(candidate.nodeId);
+	}
+	if (duplicates.length > 0) throw planError("DOCUMENT_IDENTITY_CONFLICT", "Document contains blocks with duplicate identities. This must be resolved before mutations can be applied.", void 0, {
+		duplicateBlockIds: duplicates,
+		blockCount: duplicates.length,
+		remediation: "Re-import the document or call document.repair() to assign unique identities."
+	});
+}
 function compilePlan(editor, steps) {
 	if (steps.length > 200) throw planError("INVALID_INPUT", `plan contains ${steps.length} steps, maximum is 200`);
+	const compiledRevision = getRevision(editor);
 	const index = getBlockIndex(editor);
+	assertNoDuplicateBlockIds(index);
 	const mutationSteps = [];
 	const assertSteps = [];
 	const seenIds = /* @__PURE__ */ new Set();
@@ -25247,26 +25513,41 @@ function compilePlan(editor, steps) {
 		seenIds.add(step.id);
 	}
 	let totalTargets = 0;
+	let stepIndex = 0;
 	for (const step of steps) {
 		if (isAssertStep(step)) {
 			assertSteps.push(step);
+			stepIndex++;
 			continue;
 		}
 		if (!hasStepExecutor(step.op)) throw planError("INVALID_INPUT", `unknown step op "${step.op}"`, step.id);
+		if (isCreateOp(step.op)) validateCreateStepPosition(step);
 		const targets = resolveStepTargets(editor, index, step);
+		if (isCreateOp(step.op) && targets.length > 0) {
+			const position = step.args.position ?? "after";
+			const anchorBlockId = resolveCreateAnchorFromTargets(targets, position, step.id);
+			validateInsertionContext(editor, index, step, stepIndex, anchorBlockId, position);
+		}
 		totalTargets += targets.length;
 		mutationSteps.push({
 			step,
 			targets
 		});
+		stepIndex++;
 	}
 	if (totalTargets > 500) throw planError("INVALID_INPUT", `plan resolved ${totalTargets} total targets, maximum is 500`);
-	detectOverlaps(mutationSteps);
+	validateStepInteractions(mutationSteps);
 	return {
 		mutationSteps,
-		assertSteps
+		assertSteps,
+		compiledRevision
 	};
 }
+function resolveBlockInsertionPos(editor, anchorBlockId, position, stepId) {
+	const candidate = getBlockIndex(editor).candidates.find((c$3) => c$3.nodeId === anchorBlockId);
+	if (!candidate) throw planError("TARGET_NOT_FOUND", `block "${anchorBlockId}" not found`, stepId);
+	return position === "before" ? candidate.pos : candidate.end;
+}
 function applyDirectMutationMeta(tr) {
 	tr.setMeta("inputType", "programmatic");
 	tr.setMeta("skipTrackChanges", true);
@@ -25311,10 +25592,28 @@ function buildMarksFromSetMarks(editor, setMarks) {
 	if (setMarks.strike && schema.marks.strike) marks.push(schema.marks.strike.create());
 	return marks;
 }
-function toAbsoluteBlockInsertPos(editor, blockId, offset$1, stepId) {
-	const candidate = getBlockIndex(editor).candidates.find((c$3) => c$3.nodeId === blockId);
-	if (!candidate) throw planError("TARGET_NOT_FOUND", `block "${blockId}" not found`, stepId);
-	return candidate.pos + offset$1;
+function applyInlineMarkPatches(editor, tr, absFrom, absTo, inline) {
+	const { schema } = editor.state;
+	let changed = false;
+	const markEntries = [
+		[inline.bold, schema.marks.bold],
+		[inline.italic, schema.marks.italic],
+		[inline.underline, schema.marks.underline],
+		[inline.strike, schema.marks.strike]
+	];
+	for (const [value, markType] of markEntries) {
+		if (value === void 0 || !markType) continue;
+		if (value) tr.addMark(absFrom, absTo, markType.create());
+		else tr.removeMark(absFrom, absTo, markType);
+		changed = true;
+	}
+	return changed;
+}
+function resolveCreateAnchorBlockId(target, position, stepId) {
+	if (target.kind === "range") return target.blockId;
+	const segments = target.segments;
+	if (!segments.length) throw planError("INVALID_INPUT", "span target has no segments", stepId);
+	return position === "before" ? segments[0].blockId : segments[segments.length - 1].blockId;
 }
 function executeTextRewrite(editor, tr, target, step, mapping) {
 	const absFrom = mapping.map(target.absFrom);
@@ -25348,39 +25647,7 @@ function executeTextDelete(_editor, tr, target, _step, mapping) {
 	return { changed: true };
 }
 function executeStyleApply(editor, tr, target, step, mapping) {
-	const absFrom = mapping.map(target.absFrom);
-	const absTo = mapping.map(target.absTo);
-	const { schema } = editor.state;
-	let changed = false;
-	const markEntries = [
-		[
-			"bold",
-			step.args.inline.bold,
-			schema.marks.bold
-		],
-		[
-			"italic",
-			step.args.inline.italic,
-			schema.marks.italic
-		],
-		[
-			"underline",
-			step.args.inline.underline,
-			schema.marks.underline
-		],
-		[
-			"strike",
-			step.args.inline.strike,
-			schema.marks.strike
-		]
-	];
-	for (const [, value, markType] of markEntries) {
-		if (value === void 0 || !markType) continue;
-		if (value) tr.addMark(absFrom, absTo, markType.create());
-		else tr.removeMark(absFrom, absTo, markType);
-		changed = true;
-	}
-	return { changed };
+	return { changed: applyInlineMarkPatches(editor, tr, mapping.map(target.absFrom), mapping.map(target.absTo), step.args.inline) };
 }
 function validateMappedSpanContiguity(target, mapping, stepId) {
 	let lastMappedEnd = -1;
@@ -25441,41 +25708,9 @@ function executeSpanTextDelete(_editor, tr, target, step, mapping) {
 }
 function executeSpanStyleApply(editor, tr, target, step, mapping) {
 	validateMappedSpanContiguity(target, mapping, step.id);
-	const { schema } = editor.state;
-	let changed = false;
 	const firstSeg = target.segments[0];
 	const lastSeg = target.segments[target.segments.length - 1];
-	const absFrom = mapping.map(firstSeg.absFrom, 1);
-	const absTo = mapping.map(lastSeg.absTo, -1);
-	const markEntries = [
-		[
-			"bold",
-			step.args.inline.bold,
-			schema.marks.bold
-		],
-		[
-			"italic",
-			step.args.inline.italic,
-			schema.marks.italic
-		],
-		[
-			"underline",
-			step.args.inline.underline,
-			schema.marks.underline
-		],
-		[
-			"strike",
-			step.args.inline.strike,
-			schema.marks.strike
-		]
-	];
-	for (const [, value, markType] of markEntries) {
-		if (value === void 0 || !markType) continue;
-		if (value) tr.addMark(absFrom, absTo, markType.create());
-		else tr.removeMark(absFrom, absTo, markType);
-		changed = true;
-	}
-	return { changed };
+	return { changed: applyInlineMarkPatches(editor, tr, mapping.map(firstSeg.absFrom, 1), mapping.map(lastSeg.absTo, -1), step.args.inline) };
 }
 function getReplacementText(replacement) {
 	if (replacement.blocks !== void 0) return replacement.blocks.map((b$1) => b$1.text).join("\n\n");
@@ -25587,7 +25822,8 @@ function buildAssertIndex(doc$2) {
 	});
 	return {
 		candidates,
-		byId
+		byId,
+		ambiguous
 	};
 }
 function resolveAssertScope(index, select, within$1) {
@@ -25645,9 +25881,11 @@ function executeAssertStep(_editor, tr, step) {
 }
 function executeCreateStep(editor, tr, step, targets, mapping) {
 	const target = targets[0];
-	if (!target || target.kind !== "range") throw planError("INVALID_INPUT", `${step.op} step requires exactly one range target`, step.id);
+	if (!target) throw planError("INVALID_INPUT", `${step.op} step requires at least one target`, step.id);
 	const args$1 = step.args;
-	const pos = mapping.map(toAbsoluteBlockInsertPos(editor, target.blockId, target.from, step.id));
+	const position = args$1.position ?? "after";
+	const anchorPos = resolveBlockInsertionPos(editor, resolveCreateAnchorBlockId(target, position, step.id), position, step.id);
+	const pos = mapping.map(anchorPos);
 	const paragraphType = editor.state.schema?.nodes?.paragraph;
 	if (!paragraphType) throw planError("INVALID_INPUT", "paragraph node type not in schema", step.id);
 	const sdBlockId = args$1.sdBlockId;
@@ -25664,6 +25902,7 @@ function executeCreateStep(editor, tr, step, targets, mapping) {
 	const node = paragraphType.createAndFill(attrs, textNode ?? void 0) ?? paragraphType.create(attrs, textNode ? [textNode] : void 0);
 	if (!node) throw planError("INVALID_INPUT", `could not create ${step.op} node`, step.id);
 	tr.insert(pos, node);
+	assertNoPostInsertDuplicateIds(tr.doc, step.id);
 	return {
 		stepId: step.id,
 		op: step.op,
@@ -25675,6 +25914,27 @@ function executeCreateStep(editor, tr, step, targets, mapping) {
 		}
 	};
 }
+function assertNoPostInsertDuplicateIds(doc$2, stepId) {
+	const seen = /* @__PURE__ */ new Set();
+	const duplicateSet = /* @__PURE__ */ new Set();
+	doc$2.descendants((node) => {
+		if (!node.isTextblock) return true;
+		const attrs = node.attrs ?? {};
+		const id = typeof attrs.paraId === "string" && attrs.paraId || typeof attrs.sdBlockId === "string" && attrs.sdBlockId || typeof attrs.nodeId === "string" && attrs.nodeId;
+		if (!id) return true;
+		if (seen.has(id)) duplicateSet.add(id);
+		else seen.add(id);
+		return true;
+	});
+	if (duplicateSet.size > 0) {
+		const duplicates = [...duplicateSet];
+		throw planError("INTERNAL_ERROR", `create step produced duplicate block identities: [${duplicates.join(", ")}]`, stepId, {
+			source: "executor:checkPostInsertIdentityUniqueness",
+			invariant: "post-insert block IDs must be unique",
+			duplicateBlockIds: duplicates
+		});
+	}
+}
 function runMutationsOnTransaction(editor, tr, compiled, options) {
 	const mapping = tr.mapping;
 	const stepOutcomes = [];
@@ -25730,6 +25990,13 @@ function executeCompiledPlan(editor, compiled, options = {}) {
 	const startTime = performance.now();
 	const revisionBefore = getRevision(editor);
 	checkRevision(editor, options.expectedRevision);
+	if (compiled.compiledRevision !== revisionBefore) throw planError("REVISION_CHANGED_SINCE_COMPILE", `Document revision changed between compile and execute. Compiled at "${compiled.compiledRevision}", now at "${revisionBefore}".`, void 0, {
+		compiledRevision: compiled.compiledRevision,
+		currentRevision: revisionBefore,
+		stepCount: compiled.mutationSteps.length,
+		failedAtStep: "pre-execution",
+		remediation: "Re-compile the plan against the current document state."
+	});
 	const tr = editor.state.tr;
 	if ((options.changeMode ?? "direct") === "tracked") applyTrackedMutationMeta(tr);
 	else applyDirectMutationMeta(tr);
@@ -25938,7 +26205,8 @@ function executeDomainCommand(editor, handler, options) {
 			},
 			targets: []
 		}],
-		assertSteps: []
+		assertSteps: [],
+		compiledRevision: getRevision(editor)
 	}, { expectedRevision: options?.expectedRevision });
 }
 function validateWriteRequest(request, resolved) {
@@ -26025,7 +26293,8 @@ function writeWrapper(editor, request, options) {
 			step: stepDef,
 			targets: [toCompiledTarget(stepId, op, resolved)]
 		}],
-		assertSteps: []
+		assertSteps: [],
+		compiledRevision: getRevision(editor)
 	}, {
 		changeMode: mode,
 		expectedRevision: options?.expectedRevision
@@ -26091,7 +26360,8 @@ function styleApplyWrapper(editor, input, options) {
 				marks: []
 			}]
 		}],
-		assertSteps: []
+		assertSteps: [],
+		compiledRevision: getRevision(editor)
 	}, {
 		changeMode: mode,
 		expectedRevision: options?.expectedRevision
@@ -26857,6 +27127,51 @@ function createCommentsWrapper(editor) {
 		list: (query) => listCommentsHandler(editor, query)
 	};
 }
+var SUPPORTED_NODE_TYPES = new Set(DELETABLE_BLOCK_NODE_TYPES);
+var REJECTED_NODE_TYPES = new Set(["tableRow", "tableCell"]);
+function validateTargetNodeType(nodeType) {
+	if (REJECTED_NODE_TYPES.has(nodeType)) throw new DocumentApiAdapterError("INVALID_TARGET", `blocks.delete does not support "${nodeType}" targets. Table row/column operations are out of scope.`, { nodeType });
+	if (!SUPPORTED_NODE_TYPES.has(nodeType)) throw new DocumentApiAdapterError("INVALID_TARGET", `blocks.delete does not support "${nodeType}" targets.`, { nodeType });
+}
+function resolveSdBlockId(candidate) {
+	const sdBlockId = candidate.node.attrs?.sdBlockId;
+	if (typeof sdBlockId === "string" && sdBlockId.length > 0) return sdBlockId;
+	throw new DocumentApiAdapterError("INTERNAL_ERROR", "Resolved block candidate is missing sdBlockId attribute. This indicates a schema/extension invariant violation.", { attrs: candidate.node.attrs });
+}
+function validateCommandLayerUniqueness(editor, sdBlockId) {
+	const getBlockNodeById = editor.helpers?.blockNode?.getBlockNodeById;
+	if (typeof getBlockNodeById !== "function") throw new DocumentApiAdapterError("CAPABILITY_UNAVAILABLE", "blocks.delete requires the blockNode helper to be registered.", { reason: "missing_helper" });
+	const matches = getBlockNodeById(sdBlockId);
+	if (!matches || Array.isArray(matches) && matches.length === 0) throw new DocumentApiAdapterError("TARGET_NOT_FOUND", `Block with sdBlockId "${sdBlockId}" was not found at the command layer.`, { sdBlockId });
+	if (Array.isArray(matches) && matches.length > 1) throw new DocumentApiAdapterError("AMBIGUOUS_TARGET", `Multiple blocks share sdBlockId "${sdBlockId}" at the command layer.`, {
+		sdBlockId,
+		count: matches.length
+	});
+}
+function blocksDeleteWrapper(editor, input, options) {
+	rejectTrackedMode("blocks.delete", options);
+	const candidate = findBlockByIdStrict(getBlockIndex(editor), input.target);
+	validateTargetNodeType(candidate.nodeType);
+	const sdBlockId = resolveSdBlockId(candidate);
+	const deleteBlockNodeById = requireEditorCommand(editor.commands?.deleteBlockNodeById, "blocks.delete");
+	validateCommandLayerUniqueness(editor, sdBlockId);
+	if (options?.dryRun) return {
+		success: true,
+		deleted: input.target
+	};
+	if (executeDomainCommand(editor, () => {
+		const didApply = deleteBlockNodeById(sdBlockId);
+		if (didApply) clearIndexCache(editor);
+		return didApply;
+	}, { expectedRevision: options?.expectedRevision }).steps[0]?.effect !== "changed") throw new DocumentApiAdapterError("INTERNAL_ERROR", "blocks.delete command returned false despite passing all pre-apply checks. This is an internal invariant violation.", {
+		sdBlockId,
+		target: input.target
+	});
+	return {
+		success: true,
+		deleted: input.target
+	};
+}
 var DERIVED_ID_LENGTH = 24;
 function getRawTrackedMarks(editor) {
 	try {
@@ -26980,9 +27295,7 @@ function resolveCreateInsertPosition(editor, at, operationLabel) {
 	const location$1 = at ?? { kind: "documentEnd" };
 	if (location$1.kind === "documentStart") return 0;
 	if (location$1.kind === "documentEnd") return editor.state.doc.content.size;
-	const target = findBlockById(getBlockIndex(editor), location$1.target);
-	if (!target) throw new DocumentApiAdapterError("TARGET_NOT_FOUND", `Create ${operationLabel} target block was not found.`, { target: location$1.target });
-	return location$1.kind === "before" ? target.pos : target.end;
+	return resolveBlockInsertionPos(editor, location$1.target.nodeId, location$1.kind);
 }
 function resolveCreatedBlock(editor, nodeType, blockId) {
 	const index = getBlockIndex(editor);
@@ -27084,7 +27397,9 @@ function createParagraphWrapper(editor, input, options) {
 			try {
 				const paragraph = resolveCreatedBlock(editor, "paragraph", paragraphId);
 				if (mode === "tracked") trackedChangeRefs = collectTrackInsertRefsInRange(editor, paragraph.pos, paragraph.end);
-			} catch {}
+			} catch (e) {
+				if (!(e instanceof DocumentApiAdapterError)) throw e;
+			}
 		}
 		return didApply;
 	}, { expectedRevision: options?.expectedRevision }).steps[0]?.effect !== "changed") return {
@@ -27146,7 +27461,9 @@ function createHeadingWrapper(editor, input, options) {
 			try {
 				const heading = resolveCreatedBlock(editor, "heading", headingId);
 				if (mode === "tracked") trackedChangeRefs = collectTrackInsertRefsInRange(editor, heading.pos, heading.end);
-			} catch {}
+			} catch (e) {
+				if (!(e instanceof DocumentApiAdapterError)) throw e;
+			}
 		}
 		return didApply;
 	}, { expectedRevision: options?.expectedRevision }).steps[0]?.effect !== "changed") return {
@@ -28358,14 +28675,15 @@ function trackChangesRejectAllWrapper(editor, _input, options) {
 	return { success: true };
 }
 function previewPlan(editor, input) {
-	const evaluatedRevision = getRevision(editor);
 	checkRevision(editor, input.expectedRevision);
 	if (!input.steps?.length) throw planError("INVALID_INPUT", "plan must contain at least one step");
 	const failures = [];
 	const stepPreviews = [];
 	let currentPhase = "compile";
+	let evaluatedRevision = getRevision(editor);
 	try {
 		const compiled = compilePlan(editor, input.steps);
+		evaluatedRevision = compiled.compiledRevision;
 		currentPhase = "execute";
 		const tr = editor.state.tr;
 		const { stepOutcomes, assertFailures } = runMutationsOnTransaction(editor, tr, compiled, { throwOnAssertFailure: false });
@@ -28868,14 +29186,24 @@ function queryMatchAdapter(editor, input) {
 	const userOffset = input.offset ?? 0;
 	const paginatedMatches = isTextSelector ? applyPagination(rawMatches, userOffset, input.limit) : rawMatches;
 	if (require$1 === "first" || require$1 === "exactlyOne" || require$1 === "all") {
-		if (totalMatches === 0) throw planError("MATCH_NOT_FOUND", "selector matched zero ranges");
+		if (totalMatches === 0) throw planError("MATCH_NOT_FOUND", "selector matched zero ranges", void 0, {
+			selectorType: input.select?.type ?? "unknown",
+			selectorPattern: input.select?.pattern ?? "",
+			selectorMode: input.select?.mode ?? "contains",
+			searchScope: (input.within?.kind === "block" ? input.within.nodeId : void 0) ?? "document",
+			candidateCount: 0
+		});
 	}
 	if (require$1 === "exactlyOne" && totalMatches > 1) throw planError("AMBIGUOUS_MATCH", `selector matched ${totalMatches} ranges, expected exactly one`, void 0, { matchCount: totalMatches });
 	const matchItems = paginatedMatches.map((raw, pageIdx) => {
 		const id = `m:${userOffset + pageIdx}`;
 		if (isTextSelector && raw.textRanges?.length) {
 			const blocks = buildMatchBlocks(editor, raw.textRanges, evaluatedRevision, id);
-			if (blocks.length === 0) throw planError("INTERNAL_ERROR", `text match produced no blocks for ${id}`);
+			if (blocks.length === 0) throw planError("INTERNAL_ERROR", `text match produced no blocks for ${id}`, void 0, {
+				source: "query-match-adapter:buildMatchEntries",
+				invariant: "text match must have at least one block after zero-width filtering",
+				context: { matchId: id }
+			});
 			const snippetResult = buildBlocksSnippet(editor, blocks);
 			return {
 				id,
@@ -29088,6 +29416,7 @@ function getDocumentApiAdapters(editor) {
 			acceptAll: (input, options) => trackChangesAcceptAllWrapper(editor, input, options),
 			rejectAll: (input, options) => trackChangesRejectAllWrapper(editor, input, options)
 		},
+		blocks: { delete: (input, options) => blocksDeleteWrapper(editor, input, options) },
 		create: {
 			paragraph: (input, options) => createParagraphWrapper(editor, input, options),
 			heading: (input, options) => createHeadingWrapper(editor, input, options)
@@ -30479,7 +30808,7 @@ var Editor = class Editor extends EventEmitter$1 {
 		return migrations.length > 0;
 	}
 	processCollaborationMigrations() {
-		console.debug("[checkVersionMigrations] Current editor version", "1.17.0-next.11");
+		console.debug("[checkVersionMigrations] Current editor version", "1.17.0-next.13");
 		if (!this.options.ydoc) return;
 		let docVersion = this.options.ydoc.getMap("meta").get("version");
 		if (!docVersion) docVersion = "initial";